docs: refresh agent/architecture docs against current code

[slittycode]

Summary

CLAUDE.md, apps/backend/ARCHITECTURE.md, both AGENTS.md files, and both app README.md files had drifted past several recent shipped changes (the Live 12 source-catalogue gate from #119, the transcription pianoroll work from #117/#120, and the recommendation-proof campaign UI badge / status docs from the GOAL.md track). An agent reading the docs would not have seen these modules, scripts, or new top-level directories.

This commit catches the docs up to the code:

• New backend modules surfaced. live12_catalogue.py and phase2_catalogue_gates.py (the warn-and-keep Live 12 source-catalogue gate added in Live 12 catalogue + Phase 2 output validator (warn-and-keep), symusic MIDI migration #119) now appear in CLAUDE.md's Core Files list, apps/backend/ARCHITECTURE.md's component table, the Phase 2 verification section, the backend AGENTS.md File Map, and the backend README.md tech stack / companion data section. The note clarifies how the new data/live12_catalogue.json differs from the prompt-injected prompts/live12_device_catalog.json (runtime output validation vs. Gemini system-prompt injection).
• New top-level data/ directory documented. Added to the CLAUDE.md repo-layout map (product path, not off-path) and cross-referenced from the backend README.
• Recommendation-proof campaign surfaced. The root README's doc table, the root AGENTS.md precedence order, and CLAUDE.md's Companion Agent Docs all now link GOAL.md, apps/backend/NEEDS.md, and apps/backend/RECOMMENDATION_VERDICT.md so the live north-star campaign is discoverable from the entry-point docs.
• Missing operator scripts documented. Top-level scripts/build_live12_catalogue.py and apps/backend/scripts/parity_probe_synth_backends.py are now in CLAUDE.md's Scripts-at-a-glance. The backend AGENTS.md script list also gains evaluate_recommendations.py and emit_deterministic_recs.ts.
• UI components/services documented. RecommendationVerificationBadge (sub-goal 4 badge), Phase2ConsistencyReport (chain-of-custody report), and the transcription-pianoroll client + components are now in apps/ui/README.md's feature list and apps/ui/AGENTS.md's File Map.

All referenced files were verified to exist at the paths cited. No code changes — pure documentation refresh.

Test plan

• Verify every file path referenced in the updated docs exists (ls sweep across all newly cited files).
• Confirm no doc claims a module/file that isn't on disk (cross-checked live12_catalogue.py, phase2_catalogue_gates.py, data/live12_catalogue.json, data/live12_catalogue.schema.json, scripts/build_live12_catalogue.py, scripts/parity_probe_synth_backends.py, RECOMMENDATION_VERDICT.md, NEEDS.md, RecommendationVerificationBadge.tsx, Phase2ConsistencyReport.tsx, TranscriptionPianoroll*.tsx, recommendationVerification.ts/.tsx, transcriptionPianorollClient.ts).
• Skim each updated doc end-to-end on the PR view to confirm the inserted prose reads cleanly and doesn't contradict surrounding sentences.

https://claude.ai/code/session_01KKfCTxJ3Bbadbd2naTagSb

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE (posted as COMMENT — can't self-approve)

Summary

Pure documentation refresh catching 8 markdown files up to modules shipped in #117/#119/#120 and the ongoing recommendation-proof campaign. No code changes, no contract changes. The descriptions of live12_catalogue.py, phase2_catalogue_gates.py, the pianoroll client, and the verification badge are all consistent with how those modules behave and with the warn-and-keep / Phase 1 ground-truth invariants. The AGENTS.md precedence rewrite (this file → explicit CLAUDE.md) is an accuracy fix, not fluff — the old this file was ambiguous for any agent not reading AGENTS.md as the root entry point.

Findings

None.

Test results

N/A — no code changed.

Phase boundary check

Clean — docs only, no code paths introduced.

---

Generated by Claude Code

[slittycode]

Verdict: COMMENT

Summary

Pure documentation refresh with no code changes. All 19 file paths cited in the updated docs exist on disk. Behavioral descriptions of live12_catalogue.py (case-insensitive has_device, fuzzy_resolve), phase2_catalogue_gates.py (warn-and-keep, NEVER drops/rewrites), and their wiring order in server.py are accurate against the source. The decision to record the fuzzy-rewrite failure history inline — "an earlier path landed on the wrong EQ band and wrong A/B curve" — is useful context for anyone tempted to reintroduce it. No test coverage needed or expected.

Findings

Should fix:

CLAUDE.md — data/ is declared on the product path in the first sentence of the Repo Layout section and appears as item #1 in the numbered list that opens with "The remaining top-level directories are off-path and safe to skip." That's a contradiction: if data/ is product path, it shouldn't be in the off-path inventory. Either remove it from the numbered list and let the product-path sentence do the work, or reword the intro from "The remaining top-level directories are off-path" to something like "Top-level directories not on the request path." (This contradictory structure already existed in CLAUDE.md before this PR; the PR is propagating it correctly from the source — but since CLAUDE.md is in the diff, this is the right moment to fix it.)

Worth considering:

AGENTS.md — the precedence list now reads PURPOSE.md > CLAUDE.md > GOAL.md > per-app AGENTS.md. GOAL.md is a campaign-status doc, not an architecture or invariant doc. Placing it above per-app AGENTS.md means a campaign goal could in theory override a local app constraint. Probably fine in practice since PURPOSE.md already locks the invariants, but worth a conscious decision rather than a side-effect of making it discoverable.

Test results

N/A — pure documentation, no code touched.

Phase boundary check

N/A — no code changes.

---

Generated by Claude Code