story-045: The documenter runs before verification

[jerodw]

The workflow ran implementer → tester → verifier → documenter, so every check happened before the last stage that writes. The documenter's output was the only stage output nothing verified, and story-043 shipped a red suite because of it: its documenter named a module the same story deleted, ARCHITECTURE.md failed story-038's dangling-path rule, all three CI jobs went red, and the run recorded story completed.

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

What changed

The order is now implementer → tester → documenter → verifier.

One reorder closes both gaps. The verifier sees the documenter's output and judges it. And the clean-clone check — declared on the verifier stage — now commits a tree that already holds the documenter's edits, so story completed stops being compatible with a red suite.

The third route

The verifier declares documentation, routing to the documenter:

the defect is in the documentation itself: it describes behaviour the code does not have, names a file, module or symbol that does not exist, contradicts what the run's own artifacts record, or omits a change the story required be written down. Judge the document against the code as it now stands: a document that accurately describes wrong behaviour is an implementation defect, not a documentation one, and belongs to the category that owns the code.

That last sentence is the line the category most needed. Without it, a verifier finding wrong behaviour that the document faithfully describes would send a code defect to the documenter.

The route could not have landed separately. retry_routing_problems refuses a destination that does not sit strictly before the declaring stage, so declaring documentation before this reorder would have made every run refuse at pre-flight. And it could not have been omitted either: story-028's rule is that an unrecognised category escalates rather than falling back, so giving the verifier documentation as a subject with no category that owns it would have turned every documentation finding into an escalation.

What it costs

Documentation is redone on every retry — a failing verdict re-enters at the implementer and the documenter runs again on the way back. That is the reason it was placed last originally. It is the right trade because the alternative is documentation nothing judges, and the cost is only paid when a story retries, but it is a real extra invocation.

Verification

• 2366 passed, 31 written; verification passed on the first iteration, no retries; clean-clone green with the story committed
• 23 implementer edits under tests/ were permitted by the revert check

Notes for the reviewer

This story could not verify itself. The coordinator loads the workflow at start, so this run executed under the old order — the same property story-028 and story-030 recorded. The reorder takes effect from the next run.

prompts/documenter.md was modified though the story lists it under do_not_modify. Adjudicated by the verifier as forced rather than a scope violation: test_every_stage_that_can_receive_a_retry_declares_the_placeholders requires a retry-receiving stage to declare the retry placeholders, and the documenter can now receive a retry.

One follow-up commit on this branch fixes a comment the verifier reported as factually right and grammatically broken.

🤖 Generated with Claude Code