docs: CLAUDE.md becomes a constitution; current truth gets one owner each

[adrianwedd]

Documentation architecture only. No behaviour change — no file under src/ or bin/ is touched.

The problem

CLAUDE.md was 495 lines mixing four genres in one voice: binding rules, subsystem detail, tuning constants, and incident narrative. Nothing in it could be trimmed safely, and because none of it was checkable, several claims had quietly outlived the code they described.

What changed

CLAUDE.md → 212 lines, holding only what a fresh agent must never break and where current truth lives: ten cross-cutting invariants, a "where current truth lives" table, a "read this before touching that" table, and the tool-addition checklist.

16 canonical docs, each separating ## Invariant (current, testable, citing the code and the test that pins it) from ## Why it looks like this (history, explicitly labelled as rationale rather than rule).

docs/architecture/  overview, resident-brain, policy-and-authority,
                    provenance, privacy, memory-and-learning
docs/hardware/      gpio-and-alive, wander-safety, audio-and-mic, power
docs/operations/    state-and-runtime, health, llm-routing, deployment
docs/               testing, git-workflow

Stale claims corrected against code

Each was verified by reading the source, not by trusting the old text:

Claim in old CLAUDE.md	Reality on master
"~1235 tests"	1460 collected
provenance has "six kinds"	seven — model_perception (ceiling 0.75, added by #177) was undocumented
DESCRIBE_SCENE_TIMEOUT 150s	165s, raised with CLAUDE_TIMEOUT 45→60 by #202
evolve blacklist	omitted policy.py + test_policy_invariants.py, both in BLACKLIST_FILES
state/ is where state lives	runtime_paths.py's /run/spark tmpfs class was absent entirely, though it is what ended the px-alive watchdog storm
README "1070 dry-run" tests	corrected, plus a pointer to the canonical docs

Also verified and left alone because they are still true: SIGUSR1/yield_alive, the GPIO lease and PX_GPIO_LEASE_ID borrowing, and the three-enforcement-point policy description. Every numeric claim carried forward — the Claude budget table, PIN lockout, consolidation window, STALE_AFTER_S, relay address — was re-read from source.

Fossils

docs/superpowers/README.md and docs/historical/README.md carry a banner making clear those documents are decision fossils, not current truth. HANDOFF.md and docs/ALL_DOCS_REVIEW.md move under docs/historical/ (pure renames). AGENTS.md described a Codex-only voice loop that no longer exists and becomes a pointer to CLAUDE.md.

Preserved rather than duplicated

docs/SCRIPTS.md already owned px-race's PD sign convention and safety-layer ordering more accurately than CLAUDE.md did — it correctly explains the negative gains. wander-safety.md links to it. Same for systemd/README.md, whose back-reference into a CLAUDE.md section that no longer exists is repointed to docs/operations/deployment.md.

Tests

tests/test_docs.py — 25 tests, deliberately small. Relative links resolve; the blanket-staging prohibition is present in CLAUDE.md; the fossil banner exists; every canonical doc separates invariant from history.

Each check was confirmed to fail when broken (broke a link, removed the staging rule, removed the banner, removed an ## Invariant heading — one red each, then restored). A doc test that cannot fail is worse than none.

Verification

Full suite run on this branch: 1459 passed, 21 failed, 1 skipped in 23m52s. All 21 accounted for and none caused by this branch:

Failures	Cause
11	test_tools_live.py — needs sudo and free hardware
6	test_mind_utils — live session sampling, #210 (fixed by #212, not on master)
2	TestBudgetSummary — new finding, filed as #213
2	TestRaceEndpoint — fixed thread waits under load, #211

The TestBudgetSummary pair was reproduced on a pristine origin/master worktree before being attributed elsewhere.

Defects found and filed, not absorbed

• test(budget): TestBudgetSummary fails between midnight and ~08:20 Hobart #213 (new) — TestBudgetSummary fails deterministically between midnight and ~08:20 Hobart: fixtures use fixed offsets (_ts_ago(30000)) while _today_entries() filters by Hobart calendar day.
• docs(provenance): module docstring says "Six kinds" above a table of seven #214 (new) — src/pxh/provenance.py's docstring says "Six kinds" above a table of seven. This is the root of the CLAUDE.md error, so fixing it needs a src/ change and is out of this PR's scope.
• yield_alive returns success after a 5s timeout — caller races px-alive for GPIO5 #205 (existing) — yield_alive's 5s poll has no failure branch; cited in docs/hardware/gpio-and-alive.md.

Noted, not fixed

docs/SCRIPTS.md claims to document every script but has no entry for px-post, px-blog, mcp-server, or tool-announce. Out of scope here.

Base is origin/master (825c253c), not the #212 branch — #212 is still open, so documenting its fixture as current would have been wrong. docs/testing.md marks session isolation as pending.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TTC3fktSvjQNSShHyj7ATt