feat(workflows): backfill iteration history in spec workflows

Closes the org-drill backfill TODO. Both workflow files now carry a bottom "Review and iteration history" section with four entries: Draft 1 (linear-emacs origin, 2026-05-23, placeholder timestamp), Review-and-Fold (commit 7f2aea1, 2026-05-23), Requirement addition (commit 55adf6e, 2026-05-28), and this backfill commit. Canonical and mirror updated together. Working directory working/spec-workflows-iteration-history-backfill/ removed on this commit.

The spec-response cycle on the working draft (two Codex reviews, three rulesets responses) validated the entry-shape and the content before splice. Codex caught file-history conflation that would have made per-file provenance inaccurate. Craig's direct rationale on the Iteration 1 and Iteration 3 Why lines replaced the original INFERRED markers.

5 files changed, 90 insertions, 1 deletions

diff --git a/.ai/workflows/spec-response.org b/.ai/workflows/spec-response.org
index c3ece69..99619cc 100644
--- a/.ai/workflows/spec-response.org
+++ b/.ai/workflows/spec-response.org
@@ -151,3 +151,25 @@ Update this workflow as we learn what works. Capture new disposition patterns, b
 *Learning:* The reviews were high quality and mostly accepts, which made the genuine modify/reject cases the high-value work — and the cross-spec reconciliation (replace-on-switch vs merge-on-refresh) was the single most useful synthesis, something neither review could do alone. The "Review dispositions" section closing with "everything else accepted as written" proved important: without it, a reader can't tell whether an unlisted recommendation was accepted or missed.
 
 *Open question for next run:* whether to keep dispositions inside each spec (current approach) or in a shared response doc when many specs are reviewed at once. Inside-the-spec kept the reasoning next to the affected text, which read well for two specs.
+
+* Review and iteration history
+
+** 2026-05-23 Sat @ 00:00:00 -0500 — Claude Code (linear-emacs) — author
+- *What:* Initial draft of the workflow file. Validated by the same 2026-05-23 linear-emacs run that exercised spec-review.org.
+- *Why:* Craig wanted to use each contributor for their value — his time goes into user scenarios and direction-setting, agents' time goes into structured technical review (accept/modify/reject discipline, disposition tracking) where agents are more consistent than humans. spec-response formalized the responder-side discipline so review findings get processed completely rather than skimmed.
+- *Artifacts:* Delivered to =rulesets/inbox/= on 2026-05-23 in the same 4-file handoff as spec-review.org. Heading timestamp is approximate per the opaque-id convention; no exact time was recorded.
+
+** 2026-05-23 Sat @ 12:59:31 -0500 — Claude Code (rulesets) — reviewer + responder
+- *What:* Three response-workflow edits: Overview now names spec-review as the review-file producer (closing the cross-link the handoff had asked for); added "A reject goes back to the reviewer" principle (Google eng-practices, IETF RFC 7282); added explicit response-loop termination condition under "Converge to implementation-ready." Paired review-workflow edits landed in the same commit and are recorded in spec-review.org's history.
+- *Why:* Pre-install review found the missing cross-link to spec-review. Disposition-tracking research flagged unilateral rejection without reviewer escalation as a documented anti-pattern.
+- *Artifacts:* Same commit =7f2aea1= (the workflow pair shipped together).
+
+** 2026-05-28 Thu @ 03:22:25 -0500 — Craig Jennings — author
+- *What:* Added the paired Review-and-iteration-history requirement on the response side. New goal item #4 with downstream renumbering; new Phase 4 sub-step with the entry shape (heading-as-compound-id + What/Why/Artifacts body); new "history explains provenance, not implementation behavior" principle.
+- *Why:* Same as spec-review.org's matching entry — Craig had no way to scan a spec under review and tell which iterations had been processed vs new vs pending; file mtime was the only signal, silly and error-prone. The responder side needs the same visibility surface so the response cycle can leave its provenance alongside the review side's.
+- *Artifacts:* Commit =55adf6e=.
+
+** 2026-05-28 Thu @ 03:23:01 -0500 — Claude Code (rulesets) — author
+- *What:* Backfilled this section with entries for the workflow file's prior iterations (Draft 1, Review-and-Fold, Requirement addition). Used commit author dates where exact; Draft 1's timestamp is an opaque-id placeholder since no exact time was recorded.
+- *Why:* The iteration-history requirement landed in =55adf6e= without retroactive entries for the workflow file's own prior history. This pass closes that gap so the section starts with full provenance rather than empty.
+- *Artifacts:* Working draft sources at =working/spec-workflows-iteration-history-backfill/draft-entries.org= (deleted on this commit). Spec-response cycle (two Codex reviews and three rulesets responses on the draft) validated the entries and the entry-shape before splicing.
diff --git a/.ai/workflows/spec-review.org b/.ai/workflows/spec-review.org
index d0c49c2..b4ca437 100644
--- a/.ai/workflows/spec-review.org
+++ b/.ai/workflows/spec-review.org
@@ -226,3 +226,25 @@ Sources:
 - [[https://www.atlassian.com/software/confluence/templates/design-review][Atlassian: Design Review Template]]
 - [[https://www.geeksforgeeks.org/software-engineering/software-requirement-specification-srs-document-checklist/][GeeksforGeeks: SRS Document Checklist]]
 - [[https://gerrit-review.googlesource.com/Documentation/dev-design-docs.html][Gerrit: Design Docs Review Process]]
+
+* Review and iteration history
+
+** 2026-05-23 Sat @ 00:00:00 -0500 — Claude Code (linear-emacs) — author
+- *What:* Initial draft of the workflow file. Validated by a real 2026-05-23 run against a linear-emacs ticket before being handed off to rulesets.
+- *Why:* Craig wanted to use each contributor for their value — his time goes into user scenarios and direction-setting, agents' time goes into structured technical review (gate-checking, finding-tracking, disposition rigor) where agents are more consistent than humans. spec-review formalized the reviewer-side discipline so Craig doesn't spend his time on gate-checks an agent can do better.
+- *Artifacts:* Delivered to =rulesets/inbox/= on 2026-05-23 as part of a 4-file handoff (2 workflow drafts + 2 handoff notes). Inbox files since deleted after install. Heading timestamp is approximate per the opaque-id convention; no exact time was recorded.
+
+** 2026-05-23 Sat @ 12:59:31 -0500 — Claude Code (rulesets) — reviewer + responder
+- *What:* Three tightening edits to the review workflow itself before install: Phase 1 reframed as fast triage with Phase 3 the authoritative gate after the code read; readiness gate expanded from 11 to 13 items adding security/privacy and observability (each with an escape hatch for trivial features); severity-to-blocking-power mapping added in Phase 6 (high blocks Ready, medium is author discretion). Paired response-workflow edits landed in the same commit and are recorded in spec-response.org's history.
+- *Why:* Three parallel research subagents (Definition-of-Ready / INVEST, requirements-quality IEEE 830 / ISO 29148, disposition-tracking peer-review practice) confirmed gaps. Close-read identified the Phase 1 vs Phase 3 ordering tension (gate items needed code-read context) and a security/observability blind spot.
+- *Artifacts:* Commit =7f2aea1=, +706 lines across 6 files including INDEX entries and the paired spec-response.org edits.
+
+** 2026-05-28 Thu @ 03:22:25 -0500 — Craig Jennings — author
+- *What:* Added the Review-and-iteration-history requirement itself. New goal item ("the spec's review history is updated"); new Phase 6 sub-section with the entry shape (heading-as-compound-id + What/Why/Artifacts body); new "Preserve iteration provenance" principle.
+- *Why:* Craig had no way to scan a spec under review and tell which iterations had already been processed, which were new, and which were pending — file mtime / created-time was the only signal, silly and error-prone. The iteration-history section makes processing state visible inside the spec content itself.
+- *Artifacts:* Commit =55adf6e=.
+
+** 2026-05-28 Thu @ 03:23:01 -0500 — Claude Code (rulesets) — author
+- *What:* Backfilled this section with entries for the workflow file's prior iterations (Draft 1, Review-and-Fold, Requirement addition). Used commit author dates where exact; Draft 1's timestamp is an opaque-id placeholder since no exact time was recorded.
+- *Why:* The iteration-history requirement landed in =55adf6e= without retroactive entries for the workflow file's own prior history. This pass closes that gap so the section starts with full provenance rather than empty.
+- *Artifacts:* Working draft sources at =working/spec-workflows-iteration-history-backfill/draft-entries.org= (deleted on this commit). Spec-response cycle (two Codex reviews and three rulesets responses on the draft) validated the entries and the entry-shape before splicing.
diff --git a/claude-templates/.ai/workflows/spec-response.org b/claude-templates/.ai/workflows/spec-response.org
index c3ece69..99619cc 100644
--- a/claude-templates/.ai/workflows/spec-response.org
+++ b/claude-templates/.ai/workflows/spec-response.org
@@ -151,3 +151,25 @@ Update this workflow as we learn what works. Capture new disposition patterns, b
 *Learning:* The reviews were high quality and mostly accepts, which made the genuine modify/reject cases the high-value work — and the cross-spec reconciliation (replace-on-switch vs merge-on-refresh) was the single most useful synthesis, something neither review could do alone. The "Review dispositions" section closing with "everything else accepted as written" proved important: without it, a reader can't tell whether an unlisted recommendation was accepted or missed.
 
 *Open question for next run:* whether to keep dispositions inside each spec (current approach) or in a shared response doc when many specs are reviewed at once. Inside-the-spec kept the reasoning next to the affected text, which read well for two specs.
+
+* Review and iteration history
+
+** 2026-05-23 Sat @ 00:00:00 -0500 — Claude Code (linear-emacs) — author
+- *What:* Initial draft of the workflow file. Validated by the same 2026-05-23 linear-emacs run that exercised spec-review.org.
+- *Why:* Craig wanted to use each contributor for their value — his time goes into user scenarios and direction-setting, agents' time goes into structured technical review (accept/modify/reject discipline, disposition tracking) where agents are more consistent than humans. spec-response formalized the responder-side discipline so review findings get processed completely rather than skimmed.
+- *Artifacts:* Delivered to =rulesets/inbox/= on 2026-05-23 in the same 4-file handoff as spec-review.org. Heading timestamp is approximate per the opaque-id convention; no exact time was recorded.
+
+** 2026-05-23 Sat @ 12:59:31 -0500 — Claude Code (rulesets) — reviewer + responder
+- *What:* Three response-workflow edits: Overview now names spec-review as the review-file producer (closing the cross-link the handoff had asked for); added "A reject goes back to the reviewer" principle (Google eng-practices, IETF RFC 7282); added explicit response-loop termination condition under "Converge to implementation-ready." Paired review-workflow edits landed in the same commit and are recorded in spec-review.org's history.
+- *Why:* Pre-install review found the missing cross-link to spec-review. Disposition-tracking research flagged unilateral rejection without reviewer escalation as a documented anti-pattern.
+- *Artifacts:* Same commit =7f2aea1= (the workflow pair shipped together).
+
+** 2026-05-28 Thu @ 03:22:25 -0500 — Craig Jennings — author
+- *What:* Added the paired Review-and-iteration-history requirement on the response side. New goal item #4 with downstream renumbering; new Phase 4 sub-step with the entry shape (heading-as-compound-id + What/Why/Artifacts body); new "history explains provenance, not implementation behavior" principle.
+- *Why:* Same as spec-review.org's matching entry — Craig had no way to scan a spec under review and tell which iterations had been processed vs new vs pending; file mtime was the only signal, silly and error-prone. The responder side needs the same visibility surface so the response cycle can leave its provenance alongside the review side's.
+- *Artifacts:* Commit =55adf6e=.
+
+** 2026-05-28 Thu @ 03:23:01 -0500 — Claude Code (rulesets) — author
+- *What:* Backfilled this section with entries for the workflow file's prior iterations (Draft 1, Review-and-Fold, Requirement addition). Used commit author dates where exact; Draft 1's timestamp is an opaque-id placeholder since no exact time was recorded.
+- *Why:* The iteration-history requirement landed in =55adf6e= without retroactive entries for the workflow file's own prior history. This pass closes that gap so the section starts with full provenance rather than empty.
+- *Artifacts:* Working draft sources at =working/spec-workflows-iteration-history-backfill/draft-entries.org= (deleted on this commit). Spec-response cycle (two Codex reviews and three rulesets responses on the draft) validated the entries and the entry-shape before splicing.
diff --git a/claude-templates/.ai/workflows/spec-review.org b/claude-templates/.ai/workflows/spec-review.org
index d0c49c2..b4ca437 100644
--- a/claude-templates/.ai/workflows/spec-review.org
+++ b/claude-templates/.ai/workflows/spec-review.org
@@ -226,3 +226,25 @@ Sources:
 - [[https://www.atlassian.com/software/confluence/templates/design-review][Atlassian: Design Review Template]]
 - [[https://www.geeksforgeeks.org/software-engineering/software-requirement-specification-srs-document-checklist/][GeeksforGeeks: SRS Document Checklist]]
 - [[https://gerrit-review.googlesource.com/Documentation/dev-design-docs.html][Gerrit: Design Docs Review Process]]
+
+* Review and iteration history
+
+** 2026-05-23 Sat @ 00:00:00 -0500 — Claude Code (linear-emacs) — author
+- *What:* Initial draft of the workflow file. Validated by a real 2026-05-23 run against a linear-emacs ticket before being handed off to rulesets.
+- *Why:* Craig wanted to use each contributor for their value — his time goes into user scenarios and direction-setting, agents' time goes into structured technical review (gate-checking, finding-tracking, disposition rigor) where agents are more consistent than humans. spec-review formalized the reviewer-side discipline so Craig doesn't spend his time on gate-checks an agent can do better.
+- *Artifacts:* Delivered to =rulesets/inbox/= on 2026-05-23 as part of a 4-file handoff (2 workflow drafts + 2 handoff notes). Inbox files since deleted after install. Heading timestamp is approximate per the opaque-id convention; no exact time was recorded.
+
+** 2026-05-23 Sat @ 12:59:31 -0500 — Claude Code (rulesets) — reviewer + responder
+- *What:* Three tightening edits to the review workflow itself before install: Phase 1 reframed as fast triage with Phase 3 the authoritative gate after the code read; readiness gate expanded from 11 to 13 items adding security/privacy and observability (each with an escape hatch for trivial features); severity-to-blocking-power mapping added in Phase 6 (high blocks Ready, medium is author discretion). Paired response-workflow edits landed in the same commit and are recorded in spec-response.org's history.
+- *Why:* Three parallel research subagents (Definition-of-Ready / INVEST, requirements-quality IEEE 830 / ISO 29148, disposition-tracking peer-review practice) confirmed gaps. Close-read identified the Phase 1 vs Phase 3 ordering tension (gate items needed code-read context) and a security/observability blind spot.
+- *Artifacts:* Commit =7f2aea1=, +706 lines across 6 files including INDEX entries and the paired spec-response.org edits.
+
+** 2026-05-28 Thu @ 03:22:25 -0500 — Craig Jennings — author
+- *What:* Added the Review-and-iteration-history requirement itself. New goal item ("the spec's review history is updated"); new Phase 6 sub-section with the entry shape (heading-as-compound-id + What/Why/Artifacts body); new "Preserve iteration provenance" principle.
+- *Why:* Craig had no way to scan a spec under review and tell which iterations had already been processed, which were new, and which were pending — file mtime / created-time was the only signal, silly and error-prone. The iteration-history section makes processing state visible inside the spec content itself.
+- *Artifacts:* Commit =55adf6e=.
+
+** 2026-05-28 Thu @ 03:23:01 -0500 — Claude Code (rulesets) — author
+- *What:* Backfilled this section with entries for the workflow file's prior iterations (Draft 1, Review-and-Fold, Requirement addition). Used commit author dates where exact; Draft 1's timestamp is an opaque-id placeholder since no exact time was recorded.
+- *Why:* The iteration-history requirement landed in =55adf6e= without retroactive entries for the workflow file's own prior history. This pass closes that gap so the section starts with full provenance rather than empty.
+- *Artifacts:* Working draft sources at =working/spec-workflows-iteration-history-backfill/draft-entries.org= (deleted on this commit). Spec-response cycle (two Codex reviews and three rulesets responses on the draft) validated the entries and the entry-shape before splicing.
diff --git a/todo.org b/todo.org
index 6d63109..1642b1c 100644
--- a/todo.org
+++ b/todo.org
@@ -1189,7 +1189,8 @@ Before any implementation: needs a real review pass on the spec, and a decision
 :LAST_REVIEWED: 2026-05-28
 :END:
 
-** TODO [#C] Iteration-history backfill for spec-review and spec-response :docs:followup:
+** DONE [#C] Iteration-history backfill for spec-review and spec-response :docs:followup:
+CLOSED: [2026-05-28 Thu]
 Source: org-drill inbox 2026-05-28.
 
 Once the in-flight WIP lands (the requirement that specs carry a bottom =Review and iteration history= section, with iteration / date / contributor / role / what / why / artifacts), backfill the two workflow files themselves using rulesets' session history as evidence.