[issue-3288][slice-1/6] Documenter agent: snapshot of current...

[james-in-a-box]

Text-only prompt/role edits making the documenter write current-state snapshots, not change-logs. Reframe the documenter "## Your Task" block in orchestrator/routes/pipelines.py and DOCUMENTER_ROLE in shared/egg_contracts/agent_roles.py to: describe the current state as if pipeline machinery never existed; never emit slice/TASK/phase/HITL ids into any doc/docstring/comment; include history only when tangibly valuable (rationale over chronology); fold new state into the snapshot and REMOVE stale ledger entries rather than append. Preserve verbatim the BRC no-op propose path and the DOCUMENTER_ROLE file_access boundaries. Establishes the go-forward standard the corpus is cleaned against.

Base PR: #3317

What's in this PR

Commits (3):

• Persist BRC history for slice-1 (Slice PRs are missing analysis/plan docs and all BRC history; need a 'context' PR for refine+plan phases plus per-slice BRC in each slice PR #2548)
• implement(Documenter agent + docs: snapshot of current state, not a ledger of changes #3288): tests for documenter snapshot-not-ledger framing
• implement(Documenter agent + docs: snapshot of current state, not a ledger of changes #3288): documenter writes snapshots, not ledgers

.egg-state/brc-history/3288-implement-slice-1.json | 715 ++++++++++++++++++++++++++++++++++++++++
 .egg-state/brc-history/3288-implement-slice-1.md   | 727 +++++++++++++++++++++++++++++++++++++++++
 orchestrator/routes/pipelines.py                   |  37 ++-
 orchestrator/tests/test_pipeline_prompts.py        | 119 ++++++-
 shared/egg_contracts/agent_roles.py                |  12 +-
 shared/egg_contracts/tests/test_agent_roles.py     |  79 +++++
 6 files changed, 1670 insertions(+), 19 deletions(-)

This slice

Documenter agent: snapshot of current state, not a ledger of changes

Files affected:

• orchestrator/routes/pipelines.py
• shared/egg_contracts/agent_roles.py
• orchestrator/tests/test_pipeline_prompts.py
• shared/egg_contracts/tests/test_agent_roles.py

Tasks (3) + acceptance criteria

• task-1-1: Rewrite the documenter "## Your Task" prompt assembly in orchestrator/routes/pipelines.py. Three regions: (a) the implement-phase block (≈14781) that currently opens "Update documentation for the changes made by the CODER agent:" with a "Focus on: accurate descriptions of new features or changes / breaking changes" list — rewrite so it instructs the documenter to describe the CURRENT STATE of the code after the change 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 it writes; include historical context (issue links, "previously X" rationale, migration notes) ONLY when tangibly valuable to a reader of the current system, preferring rationale ("why it is this way") over chronology ("what it used to be / when it changed"); and, when updating an existing doc, fold the new state into the snapshot and REMOVE now-stale ledger/historical entries rather than appending another layer. (b) the per-phase summary (≈6761) "Focus your documentation on changes from plan phase {phase_obj.id}" — reframe to current state without leaking the phase id as a documentation target. (c) the plan-phase orientation/no-op branch (≈14157). PRESERVE the "### When the slice warrants no doc updates (BRC: a producer with no work in a slice has no accepted no-op path — empty proposal deadlocks against reviewer NACK + escalates to HITL (gap in #2581/#2444) #3027)" no-op propose block (≈14800) and the plan-phase no-op branch behaviorally unchanged — the documenter MUST still propose --no-changes-needed when there is no doc impact; only reword the example reason string (≈14818, "e.g. slice-3 is a pure decomposition…") to a non-slice example. Do not touch any other agent's prompt block.
  • Acceptance criteria: - The implement-phase documenter block instructs current-state (snapshot) documentation and explicitly forbids slice/TASK/phase/ HITL-iteration references in any doc/docstring/comment. - It instructs preferring rationale over chronology and folding new state into the snapshot while removing stale ledger entries. - The per-phase summary and plan-phase orientation no longer frame the documenter's job as documenting "the changes from phase {id}". - The --no-changes-needed no-op propose path is still present and behaviorally unchanged (implement-phase block and plan-phase branch); the no-op example reason no longer references a slice. - No other agent role's prompt text is modified.
• task-1-2: Update DOCUMENTER_ROLE in shared/egg_contracts/agent_roles.py. Change description="Updates documentation for the changes" and the change-oriented responsibilities ("Update relevant documentation", "Ensure README files are current", etc.) to snapshot framing: describe the current state of the code after a change; never embed SDLC artifacts (slice/TASK/phase/HITL iteration numbers) in docs, docstrings, or comments; prefer rationale over chronology; fold new state into the snapshot and remove stale ledger entries. PRESERVE the FileAccessPattern EXACTLY — allowed_write (docs/, **/README.md, /*.md, .egg-state/agent-outputs/) and blocked_write (/.py, **/.ts/tsx/js/jsx/go, tests/, .egg-state/contracts/, .github/) are a hard constraint and must not change. Keep the explanatory comments on the blocked_write entries (e.g. the No agent role can modify .github/ (CI workflows): hard-blocked by both egg patterns AND likely by GitHub auth scope #2508 branch-protection rationale) — those are load-bearing rationale, not ledger noise.
  • Acceptance criteria: - DOCUMENTER_ROLE.description and responsibilities express current-state / snapshot documentation, not "documentation for the changes". - The file_access allowed_write and blocked_write lists are byte-unchanged. - Load-bearing rationale comments on blocked_write entries are retained.
• task-1-3: Update/extend the prompt-assembly and role tests for the snapshot framing. In orchestrator/tests/test_pipeline_prompts.py, update any assertions pinned to the old documenter strings and add assertions that the documenter prompt (i) instructs current-state documentation, (ii) forbids slice/TASK/phase references in written docs, and (iii) still emits the --no-changes-needed no-op propose instruction for the no-doc-impact case. Add/extend a role test under shared/egg_contracts/tests/ asserting DOCUMENTER_ROLE retains its allowed_write / blocked_write boundaries after the wording change. Run via make test.
  • Acceptance criteria: - test_pipeline_prompts.py asserts the new current-state framing and the no-slice/TASK rule, and that the no-op propose path is still present; no stale assertion references the removed strings. - A role test asserts DOCUMENTER_ROLE.file_access boundaries are unchanged. - make test passes for the touched suites.

Stack

• Position: slice 1 of 6 in pipeline issue-3288
• Base PR: Documenter snapshot-not-ledger framing + corpus cleanup (#3288) #3317
• Stacked on top of egg/issue-3288/work