Night Market Debugging Playbook

Night Market Debugging Playbook

Match the symptom to a row, run the one discriminating command, apply the known fix. Every row below is a failure this repo has already paid for, with the commit hash that settled it. Do not re-derive a diagnosis that archaeology already produced.

Vocabulary

Terms used throughout, defined once:

• Hook: a script Claude Code runs on events (PreToolUse, PostToolUse, Stop, SessionStart). Registered in a plugin's hooks/hooks.json with a command and a timeout.
• Hook budget: that registered timeout in seconds. The harness kills the hook when it expires, before any output is honored.
• Host interpreter: hooks run as python3 ... under the machine's system Python (floor: 3.9), NOT the repo's uv-managed 3.12 venv. Third-party packages a plugin declares are not guaranteed present.
• skrills: optional Rust binary for skill validation and analysis. Every Makefile target that uses it has a Python fallback.
• Import chain: everything a import x transitively pulls in, including the plugin's __init__.py.

Symptom index

Triage runbooks

1. ModuleNotFoundError from a hook on every commit

First command (substitute the hook path from the error message):

echo '{}' | python3 plugins/gauntlet/hooks/precommit_gate.py; echo "exit=$?"

What the result means: a traceback names the module whose import chain pulls in a package the host interpreter lacks. Exit 0 with no output means the hook is import-safe and the problem is elsewhere (check the hook registration in hooks/hooks.json).

Fix: guard the import at module level or defer it into the function that needs it. The gauntlet incident: precommit_gate.py imported gauntlet.knowledge_store, whose __init__.py eagerly imported modules doing bare import yaml and import anthropic. Guarded in 45dd77ef (#518), deferred in 9bfc0a7a. Add a regression test that blocks the package via a sys.meta_path blocker and re-imports the hook (pattern in plugins/gauntlet/tests/unit/test_challenges.py).

2. python39-compat is the only failing check

The repo is Python 3.12, but hook scripts and their transitive imports must stay importable under Python 3.9 (.github/workflows/ python39-compat.yml). First command:

uv run ruff check --select UP007 --target-version py39 plugins/<plugin>/hooks/
rg -n 'datetime\.UTC|from datetime import UTC' plugins/<plugin>/

What the result means: UP007 hits are bare X | Y union annotations that raise TypeError at import time on 3.9. The rg hits are the datetime.UTC alias (3.11+), which UP007 does not catch. Either one in a hook import chain breaks every hook at once: on PR #511 a single datetime.UTC in leyline.quota_tracker produced three cascade failures (18c9340d).

Fix: use from datetime import timezone with timezone.utc, and typing.Union/Optional or a from __future__ import annotations line for unions. To mirror CI's Gate 2 locally (verified 2026-07-02):

uv venv --python 3.9 /tmp/hook39
VIRTUAL_ENV=/tmp/hook39 uv pip install pytest pyyaml
cd plugins/abstract
/tmp/hook39/bin/python -m pytest tests/hooks --override-ini="addopts="

The addopts override strips per-plugin coverage flags that need packages the bare venv lacks. See also the linter trap below: ruff will fight this fix.

3. Hook exits 0 but never does anything

First command:

rg -l 'CLAUDE_TOOL_' plugins/*/hooks/
rg -ln 'read_hook_payload' plugins/*/hooks/

What the result means: Claude Code never sets CLAUDE_TOOL_* environment variables. The payload arrives as JSON on stdin. A hook reading only env vars is a silent no-op: it exits 0, CI is green, and nothing downstream ever happens. This starved the [Learning] discussion digests for two months (last digest 2026-04-25) before anyone noticed (CHANGELOG 1.9.14).

Fix: read stdin first via the canonical reader plugins/abstract/hooks/shared/hook_io.py (read_hook_payload, stdin-first with env-var fallback for the test harness). Then verify the hook actually fires: pipe a realistic payload in and check for the side effect rather than the exit code alone.

4. capabilities-sync CI fails

First command:

bash scripts/capabilities-sync-check.sh

What the result means: the script diffs every plugin's .claude-plugin/plugin.json registrations against book/src/reference/capabilities-reference.md and prints the drifted entries. PASSED: All capabilities are in sync means the CI failure was against an older commit. Rebase and rerun.

Fix: run the sanctum sync command with the fix flag:

/sanctum:sync-capabilities --fix

5. Root pytest raises ImportPathMismatchError

First command:

rg -n 'norecursedirs' pyproject.toml

What the result means: root pytest excludes plugins/* on purpose. Plugins carry duplicate test module names and conftest fixtures, and collecting them from the root collides (documented in conftest.py). If you see this error you ran pytest across plugin boundaries.

Fix: run tests per plugin, never from the root against plugins:

cd plugins/imbue && uv run pytest tests/unit/test_deferred_capture.py -x -q
make sanctum-test          # delegation target, any plugin name works
./scripts/run-plugin-tests.sh --all

6. slop-check fails on a PR

First command: read the PR comment the workflow posts (it lists the failing files and scores), then reproduce locally. The score is tier-1 hits x3 plus tier-2 hits x2 plus em dashes, per 100 words, threshold 3.0. Copy the TIER1 and TIER2 regexes from .github/workflows/slop-check.yml rather than retyping the word lists, then:

grep -o '—' docs/<file>.md | wc -l
grep -oiE "$TIER1" docs/<file>.md | wc -l

Fix: rewrite per .claude/rules/slop-scan-for-docs.md. Replace em dashes with colons or periods, and replace the flagged vocabulary with plain words. Never de-slop historical CHANGELOG entries.

7. Stop hook produces no verdict at all

First command:

rg -n '"timeout"' plugins/herald/hooks/hooks.json
rg -n 'TIMEOUT' plugins/herald/hooks/double_shot_latte.py

What the result means: if any subprocess or LLM-call timeout inside the hook is greater than or equal to the registered hook budget, the harness kills the whole hook before it can print a decision, and the hook dies without emitting anything. Herald shipped LLM_TIMEOUT_SECONDS = 30 inside a 10-second registered budget (fixed in 268cff89: capped to 8 with startup margin, and the LLM second shot gated to the single ambiguous outcome).

Fix: cap every inner timeout strictly below the registered budget and pin the invariant with a guard test, as in plugins/herald/tests/unit/test_double_shot_latte.py:: test_llm_timeout_fits_within_hook_timeout. Deterministic tests do not exercise optional LLM branches, so the timeout relation must be asserted directly.

8. CI broken on an action or tool pin

First command:

python3 scripts/check_pinned_versions.py

What the result means: the script checks GitHub-sourced pins (CI actions in .github/workflows/*, external rev: hooks in .pre-commit-config.yaml) against upstream and prints stale or held pins with reasons. Two settled incidents: setup-uv@v8 failed because the bare v8 tag does not exist upstream (pinned to v8.2.0, f81d89a5), and bandit 1.9+ dropped Python 3.9 support (held at 1.8.6, 25bf5a9d).

Fix: pin to a full existing tag, and when holding a version back, record the reason where the checker reports it so the hold is visible.