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.

1 files changed, 22 insertions, 7 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.