Organism docs sweep: promote Nerves to 7th organ + PyAutoBrain AGENTS.md diet + stale-ref fixes

[Jammy2211]

Status: PLANNED, not started. Approved plan for an organism-wide docs/wiring consistency sweep + PyAutoBrain AGENTS.md scaling fix. Local plan file: ~/.claude/plans/vivid-brewing-coral.md. This issue is the mobile-resume artifact — everything needed to execute is below, including the machinery gotchas so they don't have to be re-derived.

Context

Review sweep of PyAutoScientist + its 7 organs found the canonical docs drifted as the organism grew (Gut + Nerves added, extra feedback enacted). Every generated surface passes its own checks — all the drift is in hand-maintained prose. Fix principle: generate or point, never restate.

Two design decisions taken with the user:

1. Promote Nerves (PyAutoConf) to a full 7th organ — reconcile the code's strict-6 internal map with the human's & public 7-organ model.
2. Aggressively slim PyAutoBrain/AGENTS.md (335 lines) — same ~18 agents described 3× (rich prose + generated verb table + hand routing table); the two hand rosters have drifted differently. Rich prose already lives in each agent's own AGENTS.md (66–196 lines each), so deletion destroys nothing.

Load-bearing findings (verified — don't re-derive)

• FIREWALL_ORGANS = ("PyAutoBrain","PyAutoHeart","PyAutoBuild") is a fixed tuple, not category-derived → promoting PyAutoConf to category: organ does NOT add it to the tenant-firewall scan, and it removes "PyAutoConf" as a hunted token (safe, can only reduce findings).
• repos_sync map-block generation is opt-in (organs without :map: markers are cleanly skipped) → promoting Conf won't crash --write; must ADD markers to PyAutoConf/AGENTS.md to get its block.
• The sizing faculty is real (both intake AND feature consult agents/faculties/sizing/_sizing.py — see intake/INTAKE_TAXONOMY.md, intake/AGENTS.md). It's just missing its AGENTS.md + CLI-registry entry. Wire it up, don't delete.
• PyAutoScientist should be category: project (matches sibling front door pyautolabs.github.io). Adding that row makes "PyAutoScientist" a firewall token appearing in PyAutoBrain/docs/conf.py + PyAutoBuild/autobuild/generate_release_notes.py → +2 findings (folds into WS5; check is already red).
• Root <workspace>/AGENTS.md (routing table), .github/profile/README.md, and PyAutoScientist/README.md are all repos_sync --write targets → the "sixth organ" role-string fix + new rows propagate automatically.

Workstream 1 — Organ ledger: promote Nerves to 7th organ

• PyAutoMind/repos.yaml: PyAutoConf category: library→**organ**; remove front_door: true (redundant); fix role — drop the wrong "the sixth organ" ordinal. Update the front_door explanatory comment (~L50-54; keep mechanism, drop Nerves example). Optionally move Conf's block under # --- organs ---.
• PyAutoConf/AGENTS.md: add <!-- repos_sync:map:begin -->/:map:end marker pair (has history block, no map block); add a "this repo is the Nerves organ" line to the intro.
• PyAutoBrain/ORGANISM.md: add Nerves|PyAutoConf row (→7 organs); remove PyAutoConf from the "scientific libraries … not organs" list (~L22); soften the growth-rule "configuration belongs to existing config surfaces" clause (~L62) — note Nerves is the standing exception.
• PyAutoHeart/AGENTS.md:11: chain says …→ Hands (execute) while ORGANISM.md says Build — unify on Build; state Hands≡Build once in ORGANISM.md.
• Propagate: python3 PyAutoMind/scripts/repos_sync.py --write (regenerates all 7 organ map blocks + root routing table + both public organ tables).

Workstream 2 — Brain AGENTS.md diet (335 → ~140 lines)

• PyAutoBrain/AGENTS.md: DELETE the ### Conductors/### Faculties per-agent prose (~120 lines; home confirmed in per-agent docs) and the drifted hand "command surface (Brain implicit)" routing table (missing /hygiene,/profiling,/clone,/release). KEEP the tier contract, the generated pyauto:commands verb tables (the single roster), the consult-DAG paragraph, Running notes, history block. Move the "Build vs release resolved" blockquote + "earned its promotion" narratives → agents' DESIGN.md / Mind complete records. Add the scaling invariant: adding an agent touches only bin/pyauto-brain + the agent's own dir — never hand-edit this file's roster.
• Sizing faculty: add agents/faculties/sizing/AGENTS.md (Tier: faculty, SizingSurface/difficulty contract); register sizing in the faculty table of bin/pyauto-brain; regenerate: PyAutoBrain/bin/install.sh --write-agents-surface. Optional thin sizing.sh entrypoint for parity.

Workstream 3 — PyAutoScientist identity + guidance

• PyAutoMind/repos.yaml (add alongside WS1 so --write runs once):

  PyAutoScientist:
    github: PyAutoLabs/PyAutoScientist
    category: project
    role: "The umbrella landing repo — docs + links presenting the organism; RTD source currently lives in PyAutoBrain/docs/."

• New PyAutoScientist/AGENTS.md (~20 lines) + content-free PyAutoScientist/CLAUDE.md (@AGENTS.md): what it is; organ table is repos_sync-generated (don't hand-edit); RTD docs source lives in PyAutoBrain/docs/; record the future "migrate RTD in to make it the real center" intent (Phase 3, demand-gated — not now).

Workstream 4 — Stale cross-ref fixes (small)

• PyAutoMemory/AGENTS.md:47: complete.md → complete/<YYYY>/<MM>/ records.
• PyAutoGut/AGENTS.md:95: wrong path → point at complete/2026/07/pyautogut-organ.md (note lifecycle smell: shipped doc still in draft/).
• PyAutoMind/AGENTS.md registry list: add condemned.md.
• PyAutoBuild/AGENTS.md:20-22: executor list omits clone_seed.py, navigator.py, release-notes/Slack tooling — broaden or defer to internals.md.

Workstream 5 — Tenant-firewall findings (FILE ONLY via /intake, do not execute here)

7 pre-existing mismatches (hardcoded Jammy2211/PyAutoLabs/HowTo*/workspace names in community, workspace, clone conductor code + 4 Brain tests) + 2 from WS3 + admin_jammy has no AGENTS.md. File as hygiene/maintenance prompt — allowlist legit branded facts or refactor out.

Sequencing

Each repo = own branch/PR (report root+branch first). (1) WS1+WS3 repos.yaml + ORGANISM.md edits + Conf markers → (2) repos_sync.py --write once → (3) commit regenerated + hand edits per-repo → (4) WS2 Brain → (5) WS3 Scientist → (6) WS4 smalls → (7) WS5 filed.

Verification

• python3 PyAutoMind/scripts/repos_sync.py (no --write) → all generated checks OK (tenant-firewall still lists 7+2, expected).
• bash PyAutoBrain/bin/install.sh --check-agents-surface → OK (incl. new sizing row).
• wc -l PyAutoBrain/AGENTS.md ≈ 140; grep /hygiene + sizing present via generated tables; no hand roster.
• PyAutoScientist/README.md + .github/profile/README.md organ tables: exactly 7 organs, Nerves last, identical rendered role text.

[Jammy2211]

All five workstreams shipped and merged:

• WS1 — Nerves (PyAutoConf) promoted to the 7th organ: PyAutoMind#85, PyAutoConf#133, PyAutoBrain#141, PyAutoHeart#90, PyAutoGut#1.
• WS2 — PyAutoBrain AGENTS.md diet (335→189, roster duplication removed) + sizing faculty wired: PyAutoBrain#141.
• WS3 — PyAutoScientist identity (AGENTS.md + CLAUDE.md; category: project row): PyAutoScientist#2, PyAutoMind#85.
• WS4 — stale cross-ref fixes: PyAutoMemory#26, PyAutoGut#1, PyAutoMind#85, PyAutoBuild#166.
• WS5 — tenant-firewall findings filed (not executed here) as draft/maintenance/pyautobrain/tenant_firewall_drift.md in PyAutoMind#85; now being picked up as its own task.

Verification passed: repos_sync.py generated checks OK, install.sh --check-agents-surface OK, Brain roster now single-sourced from the registry, PyAutoScientist README shows 7 organs (Nerves last).

Follow-ups spun out separately: the WS5 firewall task (above), the deferred PyAutoConf→PyAutoNerves / PyAutoBuild→PyAutoHands repo renames, and the PyAutoGut/pyautogut-organ.md draft-duplicate lifecycle smell.

Closing as completed.

---

Generated by Claude Code