docs: update documenter purpose to snapshot framing [doc-updater]

[james-in-a-box]

Update documenter role docs to reflect snapshot-not-ledger framing from #3288.

shared/egg_contracts/agent_roles.py changed the documenter description
from "Updates documentation for the changes" to "Documents the current
state of the code", and the responsibilities now emphasize writing
snapshots rather than changelogs. Two docs referenced the old framing:

• docs/reference/agent-roles.md: **Purpose** line updated to match the new description.
• docs/guides/agent-development.md: Quoted example phrase updated to match the new _build_role_context() instruction.

Triggered by: #3318

Issue: none

Test Plan

• Automated: doc-only change, no tests
• Manual: verify quoted strings match agent_roles.py and pipelines.py

Authored-by: egg

[james-in-a-box]

Autofix tracking

{"Lint/Python": 1, "Test/Unit Tests": 1}

[egg-reviewer]

Review: docs update for documenter snapshot framing

I verified every claim in the PR against the source. The three documented changes are accurate:

• shared/egg_contracts/agent_roles.py:308 — description="Documents the current state of the code" ✓ (matches the updated docs/reference/agent-roles.md Purpose line)
• orchestrator/routes/pipelines.py:6763 — _build_role_context() documenter branch emits "Document the current state of the code in the areas these tasks touch…" ✓ (matches the updated quote in docs/guides/agent-development.md)
• The pipelines.py hunk in the second commit ("Fix checks: apply automated formatting fixes") is a pure quote-style change — escaped \"…\" inside double-quoted strings rewritten as single-quoted strings. String contents are byte-identical; no behavior change. ✓

No test pins any of the affected strings, so nothing regresses.

The reframe is applied incompletely — two stale references remain

The PR's goal is to make the docs reflect the snapshot-not-ledger framing. But the same old "Updates documentation for changes" wording — the exact changelog connotation #3288 set out to remove — still survives in two places:

1. orchestrator/routes/pipelines.py:13623 (same file this PR edits) — should fix here.

"documenter": (
    "Updates documentation for changes",
    "doc files, README updates, inline documentation",
),

This _ROLE_DESCRIPTIONS entry is rendered by _build_agent_roster() (line 13688) into the "Active Agents in This Phase" roster injected into every agent's prompt. The result is that the documenter's own prompt now contains a direct contradiction: the phase-scope block says "Document the current state of the code … not a log of what changed" (line 6763), while the roster block describes the documenter as one who "Updates documentation for changes." Since this string is in the file the PR is already modifying and embodies the precise framing being retired, it should be updated in the same change — e.g. "Documents the current state of the code" to match agent_roles.py:308.

2. docs/guides/sdlc-pipeline.md:633 (non-blocking) — terse table cell still reads:

| **Documenter** | Execution | Updates documentation | … |

Lower priority since it's a one-word summary in a different doc, but for the reframe to be coherent across the docs it should track the new Purpose ("Documents the current state of the code"). Worth folding in while touching documenter framing.

Summary

The changes made are correct. Finding #1 is a same-file inconsistency that leaves the documenter's generated prompt internally contradictory and is squarely within the PR's stated scope; please update _ROLE_DESCRIPTIONS["documenter"] in this PR. Finding #2 is a non-blocking consistency suggestion.

— Authored by egg

[james-in-a-box]

Review feedback addressed

Thanks for verifying the changes against source. Both findings addressed in commit 7f882e5:

1. orchestrator/routes/pipelines.py _ROLE_DESCRIPTIONS["documenter"] — fixed-in-PR (commit 7f882e5)
Changed "Updates documentation for changes" → "Documents the current state of the code", matching agent_roles.py:308. This removes the contradiction between the roster block injected by _build_agent_roster() and the phase-scope block at line 6763.

2. docs/guides/sdlc-pipeline.md:633 table cell — fixed-in-PR (commit 7f882e5)
Changed the Documenter Purpose cell Updates documentation → Documents the current state of the code so the table tracks the new snapshot-not-ledger Purpose. Folded in here rather than deferred since it's a one-line consistency change within the reframe's scope.

make lint ruff check/format pass on both edited files. (The 3 pre-existing mypy errors are in shared/egg_agent/client.py, untouched by this PR.)

— Authored by egg

[james-in-a-box]

egg is investigating the Test check failure...

• Unit Tests

[james-in-a-box]

Check Failure: Test / Unit Tests

What's failing: Two doc-terminology regression tests in
tests/docs/test_context_pr_doc_terminology.py:

• TestReferenceOrchestratorCliContextFields::test_cross_references_issue_2548
  — asserts "#2548" in docs/reference/orchestrator-cli.md
• TestConcurrentExecutionContextPrSection::test_slice_1_paragraph_ties_to_context_branch
  — asserts a blank-line-delimited paragraph in
  docs/guides/concurrent-execution.md contains both the literal
  egg/<id>/context token and a slice-1 mention

Root cause — pre-existing on main, not introduced by this PR. This PR
only touches docs/guides/agent-development.md,
docs/guides/sdlc-pipeline.md, docs/reference/agent-roles.md, and
orchestrator/routes/pipelines.py — none of the files these tests inspect.
The failures surface because CI merge-tests the PR head against current
main, and main is already red on these two tests:

# against the pure origin/main tree
orchestrator-cli has #2548:               False   -> test_cross_references_issue_2548 fails
concurrent-execution tied paragraph count: 0      -> test_slice_1_paragraph_ties_to_context_branch fails

The de-ledger initiative #3288 (commit ddffa6c, "implement(#3288):
de-ledger high-density reference/guide docs") deliberately stripped the
issue-number ledger from these high-density docs — dropping the #2548
cross-reference from orchestrator-cli.md and rewriting the Slice-PR-Stack
prose in concurrent-execution.md so the egg/<id>/context token no longer
shares a paragraph with a slice-1 mention. The companion regression test
tests/docs/test_context_pr_doc_terminology.py was not updated to match,
so it now enforces the old ledger convention that #3288 intentionally
reversed.

What needs to be done (out of scope for this documenter-snapshot PR, and
a design call owned by the #3288 effort):

• Update / relax TestReferenceOrchestratorCliContextFields::test_cross_references_issue_2548
  and TestConcurrentExecutionContextPrSection::test_slice_1_paragraph_ties_to_context_branch
  to reflect the de-ledgered docs, or
• Restore the #2548 cross-ref and the slice-1-tied egg/<id>/context
  paragraph if those references were removed in error.

Suggestion: Fix this on main as a #3288 follow-up (the de-ledger PR
should have updated this test in the same change). Once main is green, this
PR's Test check will pass with no changes here — the failing assertions are
entirely independent of the documenter-snapshot reframe.

— Authored by egg

[james-in-a-box]

egg check fixer completed for Test. CI will re-run to verify. View run logs

— Authored by egg