feat(workflows): add iteration-history requirement to spec workflows

Specs reviewed under either workflow now carry a bottom =Review and iteration history= section. Each entry is an org subheading with a compound id (timestamp, contributor, role) plus What/Why/Artifacts body fields. The id is opaque. Timestamp, contributor, and role concatenate without implying any decision ordering.

spec-review.org adds the gate item, the entry-shape spec, and a "Preserve iteration provenance" principle. spec-response.org adds the matching Phase 4 step and a "history explains provenance" principle. Canonical and mirror updated together.

4 files changed, 86 insertions, 16 deletions

diff --git a/.ai/workflows/spec-response.org b/.ai/workflows/spec-response.org
index 2986d0d..c3ece69 100644
--- a/.ai/workflows/spec-response.org
+++ b/.ai/workflows/spec-response.org
@@ -30,10 +30,11 @@ A spec's review is fully processed when:
 1. *Every recommendation has an explicit disposition* — accepted, modified, or rejected. None dropped.
 2. *Accepted recommendations are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog.
 3. *Modified and rejected recommendations are documented in a bottom section* (e.g. "Review dispositions") with a one-paragraph reason each, so the reviewer can find the reasoning.
-4. *Pre-agreed decisions are baked in as decisions*, moved out of "open questions."
-5. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together.
-6. *The review file is deleted* once 1-5 hold.
-7. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready.
+4. *Review/response provenance is documented in the spec* — iteration count/date, contributor, role, what changed, and why.
+5. *Pre-agreed decisions are baked in as decisions*, moved out of "open questions."
+6. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together.
+7. *The review file is deleted* once 1-6 hold.
+8. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready.
 
 The whole run is done when no =*-review.org= files remain and each spec is judged implementation-ready (or its remaining blockers are named).
 
@@ -85,9 +86,20 @@ When related specs were reviewed together, two reviews can recommend opposite th
 
 1. *Weave accepted recommendations into the body.* The spec should read naturally — a new "Selector semantics" section, a revised phase plan, an added test-strategy section — not a list of "review said X so I did Y." The body reflects the decisions; it doesn't narrate them.
 2. *Add a bottom "Review dispositions" section* listing only the *modified* and *rejected* recommendations, each with a short reason. Close it with a one-line "everything else accepted as written" so the reader knows the omissions from this section are accepts, not gaps.
-3. *Move settled questions out of "Open decisions"* into an "Agreed decisions" (or equivalent) section. Open decisions should contain only what genuinely still blocks.
-4. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early.
-5. *Update the status line* to note "review incorporated (<reviewer>, <date>)."
+3. *Update or add a bottom "Review and iteration history" section.* Every response pass gets an entry, even when all findings are accepted. Each entry is an org subheading with a compound id followed by three body fields:
+
+   Heading format: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role=
+
+   Timestamp + contributor + role concatenate as an opaque id; nothing more should be read into it. Contributor uses short parenthetical project context where session matters (e.g. =Claude Code (rulesets)=, =Codex=, =Craig Jennings=). Role can be compound (e.g. =reviewer + responder=) when one pass fused multiple roles.
+
+   Body fields:
+
+   - *What changed:* compact summary of accepted, modified, and rejected work.
+   - *Why:* the rationale or decision pressure behind the changes.
+   - *Artifacts:* review filename, disposition section, task IDs, source checks, or commits when useful.
+4. *Move settled questions out of "Open decisions"* into an "Agreed decisions" (or equivalent) section. Open decisions should contain only what genuinely still blocks.
+5. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early.
+6. *Update the status line* to note "review incorporated (<reviewer>, <date>)."
 
 ** Phase 5: Close out and iterate
 
@@ -120,6 +132,9 @@ Recording a reasoned reject is the floor, not the close. Communicate the rejecti
 ** The spec reads forward, the dispositions read backward
 The body is written for the implementer (no review archaeology). The dispositions section is written for the reviewer (the reasoning trail). Keep the two audiences separate.
 
+** The history explains provenance, not implementation behavior
+The spec body should still be the implementation contract. The bottom =Review and iteration history= section is for provenance: number of iterations, dates, contributors (including agents), roles, what each pass contributed, and why. Keep it short enough that future readers can understand how decisions evolved without rereading chats, deleted review files, or session logs.
+
 ** Re-read before editing
 The spec may have changed since you last saw it. Edit the current file, reconcile against the latest tracking state.
 
diff --git a/.ai/workflows/spec-review.org b/.ai/workflows/spec-review.org
index 2bdcf73..d0c49c2 100644
--- a/.ai/workflows/spec-review.org
+++ b/.ai/workflows/spec-review.org
@@ -29,7 +29,8 @@ A review is complete when:
 1. *The implementation-readiness gate has been evaluated* and a rubric label assigned (=Ready= / =Ready with caveats= / =Not ready= / =Needs research=).
 2. *If ready:* the user is told plainly ("This spec is implementation-ready. I have no further blocking review notes."), and the review stops — no churn for its own sake.
 3. *If not ready:* a =<spec>-review.org= file is written next to the spec, in the standard structure, with every finding specific and actionable (current behavior named, risk explained, change recommended, blocking-or-not stated).
-4. *Deferred work is logged* to =todo.org= (v1 = =[#B]=, vNext/someday = =[#D]=), not left only in chat.
+4. *The spec's review history is updated* with who reviewed it, when, which iteration it was, what changed or was recommended, and why.
+5. *Deferred work is logged* to =todo.org= (v1 = =[#B]=, vNext/someday = =[#D]=), not left only in chat.
 
 *Measurable validation:* after reading the review, an implementer knows exactly what to decide or change before starting, and an author running spec-response can give every finding an accept/modify/reject without guessing what it means.
 
@@ -155,6 +156,22 @@ The most useful reviews move a spec from =Not ready= to =Ready with caveats= or
 
 Finding severity maps to blocking power: *high-priority findings block =Ready=* — they hold the rubric at =Not ready= (or =Ready with caveats= if the author accepts and tracks them) until dispositioned; *medium-priority findings are the author's discretion* and don't block. State the blocking status on each finding so the author running spec-response knows which ones gate the rubric.
 
+Then update the spec's review history. Specs should carry a bottom section named =Review and iteration history= (or the nearest existing equivalent) that tracks each material author/reviewer pass. Add a concise entry for this review even when the spec is ready and no review file is written.
+
+Each entry is an org subheading with a compound id followed by three body fields.
+
+Heading format: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role=
+
+The timestamp + contributor + role concatenate as an opaque id — nothing more should be read into it. Timestamp matches the project's todo-format event-log convention and gives natural temporal sort without implying any decision ordering. Contributor uses short parenthetical project context where session matters (e.g. =Claude Code (linear-emacs)=, =Claude Code (rulesets)=, =Codex=, =Craig Jennings=). Role can be compound (e.g. =reviewer + responder=) when one pass fused multiple roles. Author, reviewer, responder, verifier, and researcher are the standard role names.
+
+Body fields:
+
+- *What changed or was recommended:* high-signal summary, not a duplicate of the whole review.
+- *Why:* the decision pressure or rationale that caused the contribution.
+- *Artifacts:* links to the review file, response/disposition section, commits, task IDs, or source checks when useful.
+
+If the spec has no such section, add it at the bottom. Keep the history short and cumulative; it is provenance for future readers, not a session transcript.
+
 Then log deferred work to =todo.org=: v1 implementation = =[#B]= (unless urgent or speculative); vNext/someday = =[#D]=. Tag =:feature:= / =:bug:= / =:refactor:= / =:test:= / =:quick:= / =:solo:= only when accurate. Don't leave important deferred decisions only in chat.
 
 * Principles to Follow
@@ -173,6 +190,9 @@ The spec says fetched comments render as subheadings but doesn't define whether
 ** Decide readiness first, critique second
 The gate is the product of the review. A long critique on a spec that's actually ready just creates churn; a "looks fine" on one that isn't ships hidden decisions.
 
+** Preserve iteration provenance
+Future reviewers and implementers need to know not just the current decision, but how the spec got there: how many review/response loops happened, who contributed, what they changed or recommended, and why. Keep that record in the spec itself under =Review and iteration history= so the trail survives deleted review files, chat loss, and agent handoffs.
+
 ** Be strict about ownership
 Especially for org-mode features: a user treats visible text as editable unless the representation says otherwise. Make generated-vs-editable explicit.
 
diff --git a/claude-templates/.ai/workflows/spec-response.org b/claude-templates/.ai/workflows/spec-response.org
index 2986d0d..c3ece69 100644
--- a/claude-templates/.ai/workflows/spec-response.org
+++ b/claude-templates/.ai/workflows/spec-response.org
@@ -30,10 +30,11 @@ A spec's review is fully processed when:
 1. *Every recommendation has an explicit disposition* — accepted, modified, or rejected. None dropped.
 2. *Accepted recommendations are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog.
 3. *Modified and rejected recommendations are documented in a bottom section* (e.g. "Review dispositions") with a one-paragraph reason each, so the reviewer can find the reasoning.
-4. *Pre-agreed decisions are baked in as decisions*, moved out of "open questions."
-5. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together.
-6. *The review file is deleted* once 1-5 hold.
-7. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready.
+4. *Review/response provenance is documented in the spec* — iteration count/date, contributor, role, what changed, and why.
+5. *Pre-agreed decisions are baked in as decisions*, moved out of "open questions."
+6. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together.
+7. *The review file is deleted* once 1-6 hold.
+8. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready.
 
 The whole run is done when no =*-review.org= files remain and each spec is judged implementation-ready (or its remaining blockers are named).
 
@@ -85,9 +86,20 @@ When related specs were reviewed together, two reviews can recommend opposite th
 
 1. *Weave accepted recommendations into the body.* The spec should read naturally — a new "Selector semantics" section, a revised phase plan, an added test-strategy section — not a list of "review said X so I did Y." The body reflects the decisions; it doesn't narrate them.
 2. *Add a bottom "Review dispositions" section* listing only the *modified* and *rejected* recommendations, each with a short reason. Close it with a one-line "everything else accepted as written" so the reader knows the omissions from this section are accepts, not gaps.
-3. *Move settled questions out of "Open decisions"* into an "Agreed decisions" (or equivalent) section. Open decisions should contain only what genuinely still blocks.
-4. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early.
-5. *Update the status line* to note "review incorporated (<reviewer>, <date>)."
+3. *Update or add a bottom "Review and iteration history" section.* Every response pass gets an entry, even when all findings are accepted. Each entry is an org subheading with a compound id followed by three body fields:
+
+   Heading format: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role=
+
+   Timestamp + contributor + role concatenate as an opaque id; nothing more should be read into it. Contributor uses short parenthetical project context where session matters (e.g. =Claude Code (rulesets)=, =Codex=, =Craig Jennings=). Role can be compound (e.g. =reviewer + responder=) when one pass fused multiple roles.
+
+   Body fields:
+
+   - *What changed:* compact summary of accepted, modified, and rejected work.
+   - *Why:* the rationale or decision pressure behind the changes.
+   - *Artifacts:* review filename, disposition section, task IDs, source checks, or commits when useful.
+4. *Move settled questions out of "Open decisions"* into an "Agreed decisions" (or equivalent) section. Open decisions should contain only what genuinely still blocks.
+5. *Raise the spec to implementation-ready:* consolidate decisions up front, add any implementation prerequisites the review surfaced (e.g. a schema-verification checklist), a consolidated test strategy, and a phased plan ordered so dependencies (like an output model everything depends on) come early.
+6. *Update the status line* to note "review incorporated (<reviewer>, <date>)."
 
 ** Phase 5: Close out and iterate
 
@@ -120,6 +132,9 @@ Recording a reasoned reject is the floor, not the close. Communicate the rejecti
 ** The spec reads forward, the dispositions read backward
 The body is written for the implementer (no review archaeology). The dispositions section is written for the reviewer (the reasoning trail). Keep the two audiences separate.
 
+** The history explains provenance, not implementation behavior
+The spec body should still be the implementation contract. The bottom =Review and iteration history= section is for provenance: number of iterations, dates, contributors (including agents), roles, what each pass contributed, and why. Keep it short enough that future readers can understand how decisions evolved without rereading chats, deleted review files, or session logs.
+
 ** Re-read before editing
 The spec may have changed since you last saw it. Edit the current file, reconcile against the latest tracking state.
 
diff --git a/claude-templates/.ai/workflows/spec-review.org b/claude-templates/.ai/workflows/spec-review.org
index 2bdcf73..d0c49c2 100644
--- a/claude-templates/.ai/workflows/spec-review.org
+++ b/claude-templates/.ai/workflows/spec-review.org
@@ -29,7 +29,8 @@ A review is complete when:
 1. *The implementation-readiness gate has been evaluated* and a rubric label assigned (=Ready= / =Ready with caveats= / =Not ready= / =Needs research=).
 2. *If ready:* the user is told plainly ("This spec is implementation-ready. I have no further blocking review notes."), and the review stops — no churn for its own sake.
 3. *If not ready:* a =<spec>-review.org= file is written next to the spec, in the standard structure, with every finding specific and actionable (current behavior named, risk explained, change recommended, blocking-or-not stated).
-4. *Deferred work is logged* to =todo.org= (v1 = =[#B]=, vNext/someday = =[#D]=), not left only in chat.
+4. *The spec's review history is updated* with who reviewed it, when, which iteration it was, what changed or was recommended, and why.
+5. *Deferred work is logged* to =todo.org= (v1 = =[#B]=, vNext/someday = =[#D]=), not left only in chat.
 
 *Measurable validation:* after reading the review, an implementer knows exactly what to decide or change before starting, and an author running spec-response can give every finding an accept/modify/reject without guessing what it means.
 
@@ -155,6 +156,22 @@ The most useful reviews move a spec from =Not ready= to =Ready with caveats= or
 
 Finding severity maps to blocking power: *high-priority findings block =Ready=* — they hold the rubric at =Not ready= (or =Ready with caveats= if the author accepts and tracks them) until dispositioned; *medium-priority findings are the author's discretion* and don't block. State the blocking status on each finding so the author running spec-response knows which ones gate the rubric.
 
+Then update the spec's review history. Specs should carry a bottom section named =Review and iteration history= (or the nearest existing equivalent) that tracks each material author/reviewer pass. Add a concise entry for this review even when the spec is ready and no review file is written.
+
+Each entry is an org subheading with a compound id followed by three body fields.
+
+Heading format: =YYYY-MM-DD Day @ HH:MM:SS -ZZZZ — Contributor — Role=
+
+The timestamp + contributor + role concatenate as an opaque id — nothing more should be read into it. Timestamp matches the project's todo-format event-log convention and gives natural temporal sort without implying any decision ordering. Contributor uses short parenthetical project context where session matters (e.g. =Claude Code (linear-emacs)=, =Claude Code (rulesets)=, =Codex=, =Craig Jennings=). Role can be compound (e.g. =reviewer + responder=) when one pass fused multiple roles. Author, reviewer, responder, verifier, and researcher are the standard role names.
+
+Body fields:
+
+- *What changed or was recommended:* high-signal summary, not a duplicate of the whole review.
+- *Why:* the decision pressure or rationale that caused the contribution.
+- *Artifacts:* links to the review file, response/disposition section, commits, task IDs, or source checks when useful.
+
+If the spec has no such section, add it at the bottom. Keep the history short and cumulative; it is provenance for future readers, not a session transcript.
+
 Then log deferred work to =todo.org=: v1 implementation = =[#B]= (unless urgent or speculative); vNext/someday = =[#D]=. Tag =:feature:= / =:bug:= / =:refactor:= / =:test:= / =:quick:= / =:solo:= only when accurate. Don't leave important deferred decisions only in chat.
 
 * Principles to Follow
@@ -173,6 +190,9 @@ The spec says fetched comments render as subheadings but doesn't define whether
 ** Decide readiness first, critique second
 The gate is the product of the review. A long critique on a spec that's actually ready just creates churn; a "looks fine" on one that isn't ships hidden decisions.
 
+** Preserve iteration provenance
+Future reviewers and implementers need to know not just the current decision, but how the spec got there: how many review/response loops happened, who contributed, what they changed or recommended, and why. Keep that record in the spec itself under =Review and iteration history= so the trail survives deleted review files, chat loss, and agent handoffs.
+
 ** Be strict about ownership
 Especially for org-mode features: a user treats visible text as editable unless the representation says otherwise. Make generated-vs-editable explicit.