docs(agents): collapse §2/§3 restated mechanics to their SSOT owners

[Nikita-Guzenko]

What

SSOT pointer-collapse of the restated mechanics in AGENTS.md §2 (Layout and state) and §3 (Session start) only. Every other section is byte-for-byte unchanged (git diff touches lines 67-78, 84-85, 107, 116 in §2 and 155-173 in §3).

Before → after

Section	Before	After	Δ
§2 Layout and state	13,049 B (~3,260 tok)	11,815 B (~2,950 tok)	−1,234 B (~−9.5%)
§3 Session start	7,627 B (~1,910 tok)	4,279 B (~1,070 tok)	−3,348 B (~−44%)
whole file	568 lines	556 lines	−12 lines

The lever

§2's own intro already names the owner ("docs/configuration.md is the single owner … each producing script's header and help own exact child fields and mutation mechanics") and §3's intro already names "bin/fm-session-start.sh … the single owner of composed commands, ordering, and digest contents." The per-entry field-lists and the 7-step digest enumeration were duplicating those owners. This collapses that duplication to a pointer while keeping the map usable and every safety note.

Pointers introduced (each verified to contain the moved content)

§2 config/data/state entries — each keeps its one-line purpose + every safety flag; mechanics point to:

• config/crew-harness, config/secondmate-harness → docs/configuration.md "Harness support" (owns default-mirroring, the secondmate-crewmate inheritance, the fallback chain, and "not inherited because secondmates do not launch secondmates").
• config/crew-dispatch.json → docs/configuration.md "Crew dispatch profiles".
• config/backlog-backend → docs/configuration.md "Backlog backend".
• config/backend → docs/configuration.md "Runtime backend" (owns selection order and accepted/rejected values incl. codex-app rejection).
• config/calm, config/startup-memory-budget, config/trace-context → docs/configuration.md "Pi Calm preference" / "Startup memory budget" / "Trace context propagation".
• config/herdr-presentation-spaces → docs/herdr-backend.md "Presentation spaces"; config/cmux-socket-password → docs/cmux-backend.md "Setup"; config/wedge-alarm → docs/wedge-alarm.md.
• data/projects.md, data/secondmates.md → section 6 (dropped "parsed/maintained by <script>" provenance).
• state/pending-replies/ → fm-pending-reply-lib.sh + docs/configuration.md (dropped the field list); state/.startup-network.* → fm-startup-network.sh (dropped the field list).

§3 — the 7-step digest enumeration → bin/fm-session-start.sh's header, which owns the exact ordering and each section's contents (its header even states it "Collapses AGENTS.md sections 3 and 5 into ONE script"). The step narration duplicated the wake-queue handling contract, which section 8 owns (drain, OPEN DECISIONS, UNREAD STATUS, --ack-through durability).

Invariants preserved (not dropped)

• Lock acquired first; mutating sweeps and network checks run only when locked; a lock-refused session stays read-only (also §3 line 149) and runs no network checks.
• The digest presents the durable wake queue once; section 8 owns handling and acknowledgement.
• Exactly one supervision block is emitted; the script never starts supervision itself.
• Endpoint liveness is a presence check only — use bin/fm-crew-state.sh for real state.
• ABSENT marker semantics kept above (§3 line 146).

Safety confirmation

Safety-token counts across the changed §2/§3 region are unchanged: LOCAL, gitignored 17→17, never touch 5→5, NOT inherited/not inherited preserved, firstmate-private 2→2, and the bin/fm-send.sh fails closed note is intact. The only two removed safety-token occurrences are guard-output UX ("read-only advisory" wording) and sweep mechanics ("skipped or failed guarantees" for SECONDMATE_LIVENESS), both owned by bin/fm-bootstrap.sh and routed via bootstrap-diagnostics; the lock-refused read-only invariant they described is fully retained at §3 line 149. Every "never touch" / security / trust / quarantine / provenance line in the state/ tree (check.sh, procevent, pr-poll-*, autoarm/cursor internals) is verbatim.

Verification

• git diff confined to §2/§3; all other sections identical.
• Every retired phrase grep-confirmed present in its named owner.
• bin/fm-doc-audience-check.sh → ok (68 surfaces, 253 local links).
• bin/fm-lint.sh → clean (no changed lint targets).
• No test asserts the changed prose (tests use those config files as runtime inputs only, never as AGENTS.md text).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PEwdqRzwcC2Zmrk6SrbST1