story-044: The documenter records what it changed

[jerodw]

Every stage that writes to the repository declared a changed_files record — except the documenter. It was the least constrained stage in the workflow and the only one whose effect on the repository nothing recorded.

"name": "documenter",
"prompt": "documenter.md",
"outputs": ["documentation-report.md"]

Three checks read a stage's record and therefore skipped it entirely: blocked paths, stage-output ownership, and the freshness check that holds a required artifact to this attempt. The documenter could have edited orchestration/story_coordinator.py and nothing would have noticed.

What changed

"outputs": ["documentation-report.md", "documenter-changed-files.json"],
"changed_files": "documenter-changed-files.json",
"schemas": { "documenter-changed-files.json": "changed-files" }

Named for the stage, following changed-files.json and tester-changed-files.json, and satisfying the same schema. prompts/documenter.md asks for it the way the other writing stages' prompts do.

Why it matters beyond the record itself

It has already cost something. story-043's documenter wrote a sentence naming a module that story deleted, ARCHITECTURE.md failed story-038's dangling-path rule, and all three CI jobs went red on a run that reported story completed. Nothing could attribute the breakage, because nothing recorded that the documenter had written anything.

Seven consecutive stories — 034, 037, 039, 040, 041, 042, 043 — carry a verifier note saying the documenter's file could not be judged because the documenter had not run yet.

This story does not close that gap; the-documenter-runs-before-verification does. What it provides is the attribution that story needs: with a record, a clean-clone failure whose paths fall under the documenter can be routed to the documenter rather than guessed at.

Scope held deliberately

Confinement was considered and left out. may_not_create says "not under this prefix"; there is no "only under this prefix", so confining the documenter to documentation would mean inventing a declaration form. The record makes misbehaviour visible, which is what the queued stories need, and the only misbehaviour observed so far is a stale filename.

Verification

• 2327 passed, 11 written; verification passed on the first iteration, no retries; clean-clone green with the story committed
• 22 implementer edits under tests/ were permitted by the revert check — the suite fails with them reverted

One note for the reviewer

The verifier flagged that ARCHITECTURE.md still said "The documenter declares no record and is intentionally unchecked; enabling it later is a one-line workflow change" — true when written, false as of this story, and assigned to the documenter stage which runs after the verifier. The documenter did correct it. That it worked is luck rather than construction, and it is exactly what the next story makes structural.

🤖 Generated with Claude Code