story-012: Add retry-history.json, the backward-looking record of each attempt

[jerodw]

Summary

The harness writes retry-guidance.json, which looks forward: it tells the next implementer attempt what to fix. Nothing looked backward. When a run had retried twice, no artifact said what each attempt tried and why it failed — that had to be reconstructed by reading events.log beside the archived directories.

This story adds retry-history.json: one entry per retry actually taken, naming the attempt that failed, the blocking issues as the verifier recorded them, the stage execution was rerouted to, the guidance that attempt produced, and where its artifacts were archived.

It is deliberately none of the three things it sits beside. Not retry-guidance.json, which addresses the next attempt. Not the attempts/ archive, which holds the evidence itself rather than an index of it. Not execution-history.json, which is a chronological stream where a retry is one entry among many. A run that never retries produces no file at all — not an empty array — so its absence is itself evidence.

Changes

• schemas/retry-history.schema.json (new) — the artifact's shape. attempt, blocking_issues, retry_stage and archive_directory are required; guidance is optional, because a retry can be routed with no verifier guidance behind it — a clean-clone failure follows a passing verdict.
• schemas/manifest.json — the new schema declared in the inventory story-013 had just moved out of tests/. First use of that mechanism: adding a schema now touches schemas/ only.
• orchestration/story_coordinator.py — append_retry_record writes one entry in the retry branch, beside the existing archive_attempt call, so the entry and the archive it names are produced at the same point. Nothing reads it back to route.
• tests/test_story_012_validation.py (new, tester stage) — 44 tests covering the entry shape, the one-entry-per-retry correspondence, the no-file-without-a-retry case, and schema conformance.
• .harness/docs/ARCHITECTURE.md — the artifact, its place beside the other three, and the rule that it is evidence rather than state.

Testing

796 passed, verified twice by the harness in two environments:

• test-results.json: 796 run, 796 passed, 44 new.
• clean-clone-result.json: exit_code: 0, 796 passed, python_version: 3.10.20 — the suite re-run in a fresh clone with the story committed, on the oldest Python CI tests.

Notes for review

• The retry is the interesting part, and the verifier caught a real defect. The first attempt's append_retry_record read retry-guidance.json off the run-directory root unconditionally. Nothing ever removes or supersedes that file, so an entry could carry guidance written for a different attempt — the acceptance criterion says each entry carries the guidance written for the attempt that follows it. The verifier found this by reading the write path rather than by a failing test, and the retry was scoped to two files. Second iteration passed with zero blocking issues.
• One requirement is still not met, and the verifier said so rather than clearing it. The story asks that the implementer's changed-files.json list nothing under tests/; it lists tests/test_story_013_validation.py as modified. Three story-013 assertions resolved their "after" state from the working tree, so adding a schema file broke them. The verifier judged the edit forced rather than convenient, inspected it directly, and carried the finding into the final verdict as unresolved rather than dropping it between iterations.
• This story's own run has no retry-history.json. Its retry was routed by a coordinator that did not yet contain the feature — the same shape as story-014, which could not exercise its own clean-clone check. All artifact-shape evidence comes from the tests rather than from a live run, which the verifier recorded explicitly. story-012's own retry will be the first one the artifact could have described, and the next retried run is where it gets exercised for real.
• The verifier also noted it could not confirm from the documents that repository standards prescribe the history-bounded assertion pattern the implementer attributed to ARCHITECTURE.md. It inspected the repointing directly instead, so correctness does not rest on that attribution.

🤖 Generated with Claude Code