Documenter snapshot-not-ledger framing + corpus cleanup (#3288)

[james-in-a-box]

Documentation in egg had drifted into a ledger of changes — slice numbers, TASK-N ids, phase/HITL iteration numbers, and "what was removed in #NNNN" interleaved with how the system actually works today. Once a pipeline lands on main that process framing is noise: it does not describe the current code, it costs the reader to parse, and it rots as later changes invalidate the narrative.

This change makes documentation a snapshot of current state, across two coupled work streams on the architect's six-slice DAG (slice 1 the root; slices 2-6 file-disjoint children). HITL: cq-1=enumerated+bounded-sweep, cq-2=no lint guard.

1. Documenter agent (slice 1). The documenter's task instructions (orchestrator/routes/pipelines.py) and role definition (shared/egg_contracts/agent_roles.py DOCUMENTER_ROLE) are reframed from "update documentation for the changes made by the CODER agent" to: describe the current state of the code as if the slice/pipeline machinery did not exist; never reference SDLC artifacts (slice numbers, TASK-N ids, phase/HITL iteration numbers) in any doc, docstring, or inline comment; include historical context only when tangibly valuable, preferring rationale over chronology; and, when editing an existing doc, fold the new state into the snapshot and remove stale ledger entries rather than append. The documenter's gateway write boundaries (docs/, **/*.md, .egg-state/agent-outputs/) and the BRC no-op / no-doc-impact propose path are preserved unchanged.

2. Corpus cleanup (slices 2-6), sliced by package/area. Architecture docs split into line-edit pages (brc-memory.md, orchestrator.md, and the remaining lower-density architecture pages) and load-bearing total-refactor pages (gateway-auto-filter.md "what was removed", coordination-state.md "landed in six slices" + Retired-surface tables, slice-dag.md). Per-package code cleanup pairs the .py docstrings (coder) with that package's CLAUDE.md (documenter): gateway (artifact_api.py, jira_client.py, gateway/CLAUDE.md); orchestrator (kubernetes_spawner.py, orchestrator/CLAUDE.md); shared (egg_anchor/protected_root.py, egg_agent/context_discipline.py, egg_agent/main.py) plus a bounded sweep of the highest-density remaining reference/guide docs. Slice 6 closes with an explicit enumerated list of the deferred long-tail files so coverage is auditable.

Not in scope: deleting issue references that justify why the current system is shaped the way it is (kept, reframed as rationale); references to slices/TASK-N that name live runtime machinery (the prompt strings, the TASK-N plan-format type, slice scheduling) rather than archaeology; an automated lint guard (cq-2); and the low-density long tail of the corpus (cq-1) — both deferred to follow-up issues.

Test Plan

Automated:

• make test narrows to the reachable suites; make test-all before phase exit; make lint green.
• Slice 1: orchestrator/tests/test_pipeline_prompts.py asserts the documenter implement-phase and per-phase prompt text uses the current-state / no-SDLC-artifact framing, and that the no-op (--no-changes-needed) propose block is still emitted for the no-doc-impact case. Role-definition assertions in shared/egg_contracts/tests confirm DOCUMENTER_ROLE keeps its allowed_write / blocked_write boundaries while the description and responsibilities carry the snapshot framing.

Doc/comment slices (2-6) have no behavioral tests; verification is by review:

• No slice-N / TASK-N / phase-iteration references remain in the files each slice touches (a grep -nE 'slice-[0-9]|TASK-[0-9]' over the touched files returns only live-machinery hits the reviewer accepts).
• Rewritten sections read as descriptions of current behavior, not change logs; retained issue links are rationale ("why it is this way"), not chronology.
• For slices 4/5 (coder .py edits): the package's targeted test suite stays green (make test), proving comment/docstring-only edits did not change behavior.
• make lint (markdown/structure + python) stays green.

Manual Steps

Pre-merge: none.

Post-merge: none required — all changes are documentation and agent-prompt text and are no-ops for running pipelines. The documenter prompt change takes effect for future pipelines once the orchestrator image is rebuilt/redeployed on the normal release cadence. A follow-up issue should be filed for (a) the deferred long-tail corpus enumerated in slice 6's PR notes and (b) an optional lint/CI guard against re-introducing slice/TASK references in committed docs (HITL cq-2).

Pipeline context

• Pipeline: issue-3288
• Issue: Documenter agent + docs: snapshot of current state, not a ledger of changes #3288
• Slices (6):
  1. Documenter agent: snapshot of current state, not a ledger of changes (slice-1) — [issue-3288][slice-1/6] Documenter agent: snapshot of current... #3318
  2. De-ledger docs/architecture line-edit pages (slice-2) — [issue-3288][slice-2/6] De-ledger docs/architecture line-edit pages #3319
  3. Total-refactor load-bearing architecture pages (slice-3) — [issue-3288][slice-3/6] Total-refactor load-bearing architecture pages #3320
  4. Gateway docstrings + gateway/CLAUDE.md (slice-4) — [issue-3288][slice-4/6] Gateway docstrings + gateway/CLAUDE.md #3321
  5. Orchestrator docstrings + orchestrator/CLAUDE.md (slice-5) — [issue-3288][slice-5/6] Orchestrator docstrings... #3322
  6. Shared docstrings + bounded high-density sweep; enumerate deferred tail (slice-6) — [issue-3288][slice-6/6] Shared docstrings + bounded high-density... #3323
• Docs: Refine analysis, Refine analysis (human summary), Implementation plan, Implementation plan (human summary)

Per-phase BRC transcripts: refine, plan.