/night-market-failure-archaeology

name: night-market-failure-archaeology
description: Chronicles settled battles, reverts, and dead ends. Use when a fix echoes a past failure. Do not use for live triage; use night-market-debugging-playbook.

Night Market Failure Archaeology

This is a reference document, not a runbook. It records every major investigation, dead end, rejected fix, and revert in this repo as symptom, root cause, evidence, status, and lesson, so nobody re-fights a settled battle. For triage of a failure happening right now, use `night-market-debugging-playbook`. Come here when a proposed change smells like something the repo already tried and rejected.

Jargon used below:

• "py39 hooks": hook scripts run under the host system Python (3.9

floor), while the rest of the repo requires Python 3.12. Enforced by `.github/workflows/python39-compat.yml`.

• "unbloat": the conserve plugin's dead-code deletion campaign.
• "Stop hook": a Claude Code hook that runs when a session turn ends.
• "settled": the fight is over. Re-opening it requires new evidence

and a note in the collective memory, not a hunch.

How to use this chronicle

1. Before implementing, scan the battle titles and the recurring-class table for anything resembling your plan. 2. If a battle matches, read its lesson. Follow it, or write down why this time is different before overriding it. 3. Verify any hash you rely on: `git log --format='%h %s' -1 <hash>`. 4. When your own battle settles, add an entry (format at the bottom).

Settled battles

SB1: tasks_manager cross-plugin DRY consolidation (reverted)

• Symptom: three near-identical `tasks_manager.py` copies in attune,

sanctum, and spec-kit looked like textbook duplication.

• Root cause of the failure: consolidating them into a root

`scripts/tasks_manager.py` (1,169 lines deleted across 6 files) broke plugin self-containment. Plugins are independent deployables that run from a Claude Code cache directory, so they cannot import from the repo root.

• Evidence: `054e2679` (consolidate, 2026-01-23), `29961cd2` (revert,

same day), `d89a55c7` (differentiated per-plugin copies). All three copies exist today under `plugins/<p>/scripts/tasks_manager.py`. `docs/dependency-audit.md` tracks cross-plugin deps and fallbacks.

• Status: settled. Per-plugin copies are intentional.
• Lesson: DRY across plugin boundaries is an anti-pattern here. Do not

"helpfully" re-consolidate duplicated plugin scripts.

SB2: LSP proxy (speculative infrastructure, killed)

• Symptom: `scripts/lsp-proxy.py` added for "graceful server fallback"

with no consumer demanding it.

• Root cause: speculative abstraction built ahead of need.
• Evidence: `2fcb256d` (add), killed in PR #193 review, `bc318947`

(revert, 2026-02-11, restores `.cclsp.json`).

• Status: settled. Do not re-add without a concrete consumer.
• Lesson: infrastructure without a present consumer dies in review.

See also `.claude/rules/shared-utility-consumer-rule.md`.

SB3: Tier-3 unbloat over-deletion (2026-03-28, the big one)

• Symptom: unbloat deleted 182 files (66K lines) using only the Python

import graph to decide what was dead.

• Root cause: skills and commands reference scripts from markdown, not

Python imports. 28 actively referenced scripts plus 18 companion test files were classified dead and deleted.

• Evidence: `a3f11323` (the deletion), `3f280334` (restore the 28

scripts and 18 tests), `b5f08bf7` (CI repair: dead docs workflow, missing capabilities entries), `d6c128f5` and `01a13e70` (further repair and governance follow-ups). Recovery point was branch `backup/unbloat-20260328`.

• Status: settled, with the highest single blast radius on record.
• Lesson: any deletion campaign must scan markdown references

(skills, commands, agents), never imports alone. Always take a `backup/unbloat-<date>` branch first.

SB4: bulk lint ignores (reverted)

• Symptom: global ruff ignores made parseltongue lint pass while

hiding 73 real violations.

• Root cause: silencing the gate instead of fixing the findings.
• Evidence: `06b9b1db` (2026-03-10) reverts the bulk ignores and fixes

all 73 at source. The commit body cites issue #296 as the anti-bulk-ignore policy anchor.

• Status: settled. Constitution rule 6 also bans bare suppressions.
• Lesson: a suppressed violation is a hidden defect. Fix at source or

suppress per line with a stated reason.

SB5: datetime.UTC breaking py39 hooks (fixed 3+ times)

• Symptom: hook import chains crash under host Python 3.9 because

`datetime.UTC` is a 3.11+ alias. On PR #511 this was the sole failing check, with three cascade failures rooted in one ImportError.

• Root cause: ruff's pyupgrade rule UP017 kept auto-rewriting

`timezone.utc` back to `datetime.UTC`, silently re-breaking the fix. The linter was fighting the fix.

• Evidence: `18c9340d` (leyline quota_tracker, 2026-05-07),

`b0049fde` (abstract), `709dafc9` (attune).

• Status: settled by a durable guard, not by the fixes themselves:

an AST-scanning test (`plugins/leyline/tests/test_python39_compat.py`) fails CI on any reintroduction, root ruff config extend-ignores UP017, and the surviving per-line pyupgrade suppression markers each carry a stated reason.

• Lesson: when the linter fights the fix, only an AST invariant test

holds the line. A fix commit alone will be reverted by tooling.

SB6: unguarded yaml/anthropic imports in hook chains

• Symptom: every `git commit` emitted a PreToolUse hook

ModuleNotFoundError.

• Root cause: gauntlet's `__init__` eagerly imported dependencies

(yaml, anthropic) that the bare host interpreter running hooks does not have.

• Evidence: `45dd77ef` (guard yaml import, #518, 2026-05-08),

`9bfc0a7a` (defer anthropic import to function scope). Regression tests block re-imports with a `sys.meta_path` blocker (`plugins/gauntlet/tests/unit/test_challenges.py`).

• Status: settled.
• Lesson: hook entrypoints and everything they tran