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

| # | Symptom | Likely cause | Story |

|---|---------|--------------|-------|

| 1 | PreToolUse hook error / ModuleNotFoundError on every git commit | Unguarded third-party import in a plugin __init__.py reachable from a hook | 45dd77ef, 9bfc0a7a |

| 2 | python39-compat is the only failing CI check | A 3.10+/3.11+ construct (datetime.UTC, bare X \| Y union) entered a hook import chain | 18c9340d, PR #511 |

| 3 | Hook exits 0 but never does anything | Hook reads CLAUDE_TOOL_* env vars instead of stdin JSON | CHANGELOG 1.9.14 |

| 4 | capabilities-sync CI fails | plugin.json registrations drifted from the book reference | capabilities-sync.yml |

| 5 | Root pytest raises ImportPathMismatchError | Plugin tests collected from repo root instead of per plugin | conftest.py, pyproject norecursedirs |

| 6 | slop-check fails on a PR | Slop score over 3.0 in a docs/ or book/src/ markdown file | slop-check.yml |

| 7 | Stop hook produces no verdict at all | Inner subprocess timeout >= registered hook budget | 268cff89 |

| 8 | CI broken on a GitHub action or tool pin | Stale or nonexistent pinned version | f81d89a5, 25bf5a9d |

| 9 | Scanner reports nothing on input you know is bad | Swallowed exception (except-and-continue) drops files silently | 666171c3, b6de71cf |

| 10 | skrills: not found | Missing optional binary (a Python fallback exists) | Makefile validate-skills |

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.

9. Scanner reports nothing on input you know is bad

First command: feed the scanner one deliberately malformed file and

watch for an ADVISORY finding. Silence is the bug. Then look for the

swallow:

rg -n 'except' scripts/check_hook_modernization.py

What the result means: an except-and-continue block in a scanner loop

drops unparseable files without a trace, so the worst inputs are

exactly the ones never reported. Incidents B1-B4 (666171c3, #575, and

b6de71cf) covered hook-modernization scanning, strict-mode file drops,

and DORA metrics rating malformed tags as Elite.

Fix: Constitution rule 10. Errors are not optional: emit an advisory

finding for each skipped file or propagate. Never catch-and-continue

without output.

10. skrills not found

First command:

make validate-skills

What the result means: skrills not available, using Python fallback

followed by scripts/check_plugin_hooks.py output is normal

operation rather than an error. make analyze-skills falls back to

scripts/generate_dependency_map.py. Only build the binary if you

need the Rust path:

make skrills-build    # needs cargo and the skrills repo at $HOME/skrills
                      # (override with SKRILLS_REPO=/path)

Traps that cost real time

The linter fights the fix

Ruff's pyupgrade rule UP017 auto-rewrites timezone.utc back to the

3.11-only datetime.UTC, silently reverting the py39 fix on the next

make lint. This recurred at least three times (18c9340d, b0049fde,

709dafc9) before the durable defense landed: UP017 in root

pyproject.toml extend-ignore, per-line suppression comments with a

stated reason where needed (Constitution rule 6 requires the reason),

and above all an AST-scanning invariant test

(plugins/leyline/tests/test_python39_compat.py) that fails CI on any

reintroduction. Lesson: when an autofixer keeps reverting your fix,

re-applying is attempt N of an infinite loop. Encode the invariant as

a test that scans the source.

The green gate that checks nothing

A green check proves only that the gate's own spec was satisfied. A

gate can be quietly configured to check nothing and stay green. The

global mirrors-mypy pre-commit hook silently disabled 13 error codes,

and typecheck ran

--changed instead of --all (fixed in 1.9.12: neutered hook

removed, run-plugin-typecheck --all, typecheck.yml gating every

PR). Discriminating test for any suspicious gate: introduce one known

violation and confirm the gate goes red. If it stays green, the bug

is inside the gate itself.

The cache-dir relative path

Plugins execute from Claude Code's cache directory rather than the

repo checkout, so a CWD-relative path in a hook resolves to nothing. The

conserve session-start hook broke exactly this way and was fixed by

inlining its JSON utilities (CHANGELOG 1.4.1; the inlined-copy sync

notice lives in scripts/shared/json_utils.sh). Rule: hooks resolve

paths from ${CLAUDE_PLUGIN_ROOT} or relative to their own script

file, never from the working directory.

The two-challenge rule

After two consecutive failed attempts of the same shape (same file,

same error class, same tool), do not try a third variation. Switch to

a read-only diagnostic: the discriminating command from the matching

row above, verbose test output, or printing the actual state. Then

report four things: what you believed, what the evidence now says,

what you would try differently, and an explicit ask. This discipline

comes from the global CLAUDE.md and is wired into

plugins/sanctum/commands/fixit.md. It exists to kill the

"47 edits to make a test pass" loop.

When NOT to use

• Running tests, lint, releases, or publishing normally: use

night-market-operations.

• Recreating the dev environment (uv, tool installs, first clone): use

night-market-build-and-env.

• The history and rationale behind these battles (reverts, dead ends,

the 2026-03-28 unbloat cascade): use night-market-failure-archaeology.

• Hook, skill, and plugin mechanics as reference material: use

claude-code-plugin-reference.

• Deciding how a fix must be classified, gated, and reviewed: use

night-market-change-control.

• Configuration axes and their defaults: use night-market-config-catalog.

Exit Criteria

• [ ] The failure was matched to a symptom row, or explicitly

identified as a new failure mode not in this table.

• [ ] The row's first command was run and its output captured before

any fix was attempted.

• [ ] The applied fix matches the row's known remedy, or the deviation

is stated with evidence.

• [ ] For hook fixes: the hook was re-run under bare python3 with a

stdin JSON payload and the side effect (beyond exit 0) was

observed.

• [ ] For recurring-class fixes (py39, timeouts, swallowed errors): an

invariant test now fails if the bug is reintroduced.

• [ ] If two same-shape attempts failed, work switched to a read-only

diagnostic and a four-part report was produced.

Provenance and maintenance

Compiled 2026-07-02 against repo v1.9.15, branch discussions-fix-1.9.14.

All commit hashes verified with git log --oneline -1 <hash>. Facts

most likely to drift, with re-verification one-liners:

• Herald timeout values:

rg -n '"timeout"' plugins/herald/hooks/hooks.json and

rg -n 'LLM_TIMEOUT_SECONDS' plugins/herald/hooks/double_shot_latte.py

(10 and 8 as of 2026-07-02).

• Slop threshold and tier lists:

rg -n 'THRESHOLD|TIER1|TIER2' .github/workflows/slop-check.yml

(3.0 as of 2026-07-02).

• py39 gates:

rg -n 'UP007|--python 3.9' .github/workflows/python39-compat.yml.

• UP017 hold: rg -n 'UP017' pyproject.toml.
• Canonical hook reader exists:

rg -n 'def read_hook_payload' plugins/abstract/hooks/shared/hook_io.py.

• Pin checker and sync checker exist:

ls scripts/check_pinned_versions.py scripts/capabilities-sync-check.sh.

• skrills fallbacks: rg -n -A 8 'validate-skills:' Makefile.
• Root test exclusion: rg -n 'norecursedirs' pyproject.toml.
• Unverified beyond commit messages: none. PR #511 confirmed via

gh pr view 511 and the 18c9340d commit body.