1 files changed, 33 insertions, 28 deletions

diff --git a/.ai/workflows/spec-response.org b/.ai/workflows/spec-response.org
index 2686cf8..de5b1c8 100644
--- a/.ai/workflows/spec-response.org
+++ b/.ai/workflows/spec-response.org
@@ -5,9 +5,9 @@
 
 * Overview
 
-The spec-response workflow processes external reviews of a design spec and folds them into the spec until it is implementation-ready. A reviewer (human or another agent) leaves a review file next to the spec — typically produced by its counterpart, the *spec-review* workflow, which writes =<spec-basename>-review.org= and assigns a readiness rubric. Claude works through every recommendation, deciding accept / modify / reject for each, updates the spec for the accepted ones, documents the modified and rejected ones with reasons, then deletes the review file. Repeat for each spec under review.
+The spec-response workflow processes a review's findings and folds them into the spec until it is implementation-ready. A reviewer (human or another agent) records findings in the spec's =* Review findings= section — typically via its counterpart, the *spec-review* workflow, which writes one =TODO= task per finding (=[/]= cookie on the heading) and assigns a readiness rubric. Claude works through every finding, deciding accept / modify / reject, updates the spec body for the accepted ones, and completes each finding task in place: accept and modify finish =DONE= (the modify's change noted in the body), reject finishes =CANCELLED= with the reason. Repeat for each spec under review.
 
-The output is a spec a reader could implement from, plus a durable record — inside the spec — of why any recommendation was changed or declined, so the reviewer can find the reasoning later without re-litigating.
+The output is a spec a reader could implement from, plus a durable record — inside the spec — of why any finding was changed or declined, so the reviewer can find the reasoning later without re-litigating. The reasoning lives on the completed finding task, not a separate file.
 
 This workflow was first run on 2026-05-23 against the linear-emacs =issue-query-spec.org= and =issue-representation-spec.org= reviews, and written up from that run.
 
@@ -27,25 +27,25 @@ A review is only useful if every point in it gets a decision. Without a defined
 
 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.
+1. *Every finding has an explicit disposition* — accepted, modified, or rejected, and its task completed (=DONE= or =CANCELLED=). None dropped.
+2. *Accepted findings are woven into the spec body* — the spec reads as if they were always there, not appended as a changelog.
+3. *Modified and rejected findings carry a one-paragraph reason in the completed task's body*, so the reviewer can find the reasoning.
 4. *Review/response provenance is documented in the spec* — iteration count/date, contributor, role, what changed, and why.
 5. *Pre-agreed decisions are flipped to =DONE=* — each settled decision's =TODO= becomes =DONE=, and the =[/]= cookie on the spec's =* Decisions= heading reflects the tally.
 6. *Cross-spec tensions are reconciled in writing* when related specs were reviewed together.
-7. *The review file is deleted* once 1-6 hold.
+7. *Every finding task is completed* — the =* Review findings= =[/]= cookie reads complete (each finding =DONE= or =CANCELLED=).
 8. *Tracking is updated* — the spec's VERIFY/task body notes "review incorporated" and whether it's implementation-ready.
 9. *Implementation tasks exist* — once the author confirms the spec is Ready, the project's =todo.org= carries the full implementation-task breakdown (Phase 6), reviewed for completeness, with =:solo:= marked and a Manual-testing task for everything else.
 
-The whole run is done when no =*-review.org= files remain and each spec is judged implementation-ready (or its remaining blockers are named).
+The whole run is done when every spec's =* Review findings= cookie reads complete and each spec is judged implementation-ready (or its remaining blockers are named).
 
-*Measurable validation:* a reader scanning the review against the revised spec can find, for every review point, either the change in the body or its disposition at the bottom. Nothing is unaccounted for.
+*Measurable validation:* a reader scanning the spec can find, for every finding, either the change in the body or its disposition on the completed finding task. Nothing is unaccounted for.
 
 * When to Use This Workflow
 
 Trigger when:
 
-- A reviewer drops a review file alongside a spec — convention: same basename with a =-review.org= suffix (=foo.org= → =foo-review.org=).
+- A reviewer records findings in the spec's =* Review findings= section — typically via the spec-review workflow.
 - Craig says "respond to the review" / "let's run the spec-response workflow" / "process the spec reviews."
 - Any time a spec needs to absorb structured external feedback and converge to implementation-ready.
 
@@ -63,7 +63,7 @@ the file should be renamed first. Spec workflows require the -spec.org suffix as
 guard against pointing the workflow at tutorial, inventory, or setup docs.
 #+end_example
 
-The review file the response consumes follows the convention =<spec-basename>-review.org=, so a misnamed spec produces a mis-pointed review file too. Fix the spec name first.
+The findings the response consumes live in the spec's own =* Review findings= section, so the spec filename is the handle the workflow keys on — point it at the right =-spec.org= file. Fix the spec name first.
 
 The user resolves the mismatch and re-invokes the workflow. Do not proceed with the response against a misnamed spec.
 
@@ -71,7 +71,7 @@ The user resolves the mismatch and re-invokes the workflow. Do not proceed with
 
 ** Phase 0: Orient
 
-1. List the review files (=ls docs/*-review.org= or wherever they live). Process them one at a time in whatever order; the user may name an order.
+1. Find specs with open findings — a =* Review findings= section whose =[/]= cookie isn't complete (=TODO= findings remain). Process them one at a time in whatever order; the user may name an order.
 2. Re-read the *current* spec, not your memory of it — it may have changed since you wrote it (the user or a linter may have edited it, and pre-agreed decisions may already be encoded in the tracking file).
 3. Note any *pre-agreed decisions* the reviewer or user has already settled — in the review's own "Agreed decisions" section, or in the spec's tracking task. These are settled inputs. Don't reopen them; bake them in.
 
@@ -79,15 +79,15 @@ The user resolves the mismatch and re-invokes the workflow. Do not proceed with
 
 Read the entire review first. Recommendations interact — an early "medium" finding may be subsumed by a "high" one, or two findings may point at the same edit. Decide dispositions with the whole picture in view, not finding-by-finding as you scroll.
 
-** Phase 2: Decide a disposition for every recommendation
+** Phase 2: Decide a disposition for every finding
 
-For each recommendation, choose one:
+For each finding, choose one:
 
-- *Accept* — the recommendation is right as written. Plan the edit.
-- *Modify* — the recommendation is right in spirit but wrong in detail or scope. Adjust it, and record what you changed and why.
-- *Reject* — the recommendation doesn't fit. Record why.
+- *Accept* — the finding is right as written. Plan the edit.
+- *Modify* — the finding is right in spirit but wrong in detail or scope. Adjust it, and record what you changed and why.
+- *Reject* — the finding doesn't fit. Record why.
 
-*Engage critically.* Rubber-stamping is a failure mode. On a strong review most points are accepts, but actively look for the genuine modify/reject cases — they are where your judgment earns its place. Examples from the first run:
+*Engage critically.* Rubber-stamping is a failure mode. On a strong review most findings are accepts, but actively look for the genuine modify/reject cases — they are where your judgment earns its place. Examples from the first run:
 
 - *Modify:* the review proposed an automatic cache-TTL defcustom. Accepted the goal (fresh data) but deferred TTL to vNext because for a single-user tool an explicit force-refresh + clear-cache command covers it without invalidation complexity.
 - *Reject:* the review floated a separate =default-issue-filter= defcustom. Rejected as redundant — a fixed default command plus a default-view preference already covered it.
@@ -101,8 +101,8 @@ When related specs were reviewed together, two reviews can recommend opposite th
 
 ** Phase 4: Update the spec
 
-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.
+1. *Weave accepted findings 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. *Complete each finding task in place.* Accept → =DONE=, body noting where it was folded; modify → =DONE=, body noting what you changed and why; reject → =CANCELLED=, body giving the reason. The =[/]= cookie on =* Review findings= tracks progress. The reason on a modified or rejected finding is the durable record — accepted findings are recorded by the body change itself, so they need no separate note. The asymmetry is deliberate.
 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=
@@ -113,17 +113,17 @@ When related specs were reviewed together, two reviews can recommend opposite th
 
    - *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.
+   - *Artifacts:* the relevant findings, task IDs, source checks, or commits when useful.
 4. *Flip settled decisions to =DONE=.* Each decision the decision-maker has agreed flips its =TODO= to =DONE=; the =[/]= cookie on the =* Decisions= heading tracks the tally. A contested decision stays =TODO= with the back-and-forth under its =*** Discussion= child header. Decisions still =TODO= should be only what genuinely still blocks, each with an owner and a by-when.
-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. *Gate:* the spec Status cannot move past =draft= to implementation-ready while any decision is still =TODO= — the =[/]= cookie must read complete, or the author consciously accepts and records the risk of building with one open.
+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. *Gate:* the spec Status cannot move past =draft= to implementation-ready while any decision or any =:blocking:= finding is still =TODO= — both =[/]= cookies must read complete, or the author consciously accepts and records the risk of building with one open. *If this response expanded scope* — folding a finding in added new phases, decisions, or external-dependency assumptions — re-run spec-review's readiness rubric against the *expanded* spec, and file any new gap as a finding or decision before claiming =Ready=. Disposition-completeness gates the *review*; the readiness rubric gates the *spec*. A response can resolve every finding and still be less ready than before, because the answers introduced unproven obligations — the cookies only protect you if the new obligation is actually filed.
 6. *Update the status line* to note "review incorporated (<reviewer>, <date>)."
 
 ** Phase 5: Close out and iterate
 
-1. *Delete the review file* — only after every recommendation has a disposition. Its deletion is the signal the review is fully processed.
-2. *Update tracking* — the spec's VERIFY/task body gets a line noting review incorporated, what changed at a high level, which recommendations were modified (pointing at Review dispositions), and whether it's now implementation-ready pending final go.
+1. *Confirm every finding is completed* — the =* Review findings= =[/]= cookie reads complete (every finding =DONE= or =CANCELLED=). The complete cookie is the signal the review is fully processed; there is no file to delete.
+2. *Update tracking* — the spec's VERIFY/task body gets a line noting review incorporated, what changed at a high level, which findings were modified or rejected (pointing at the completed findings), and whether it's now implementation-ready pending final go.
 3. *Update the session log* (state changed this turn).
-4. *Move to the next review file.* Repeat Phases 1-5 until none remain.
+4. *Move to the next spec with open findings.* Repeat Phases 1-5 until none remain.
 5. *Report* what was accepted-wholesale, what was modified/rejected and why, any cross-spec reconciliations, and the implementation-ready verdict per spec.
 
 ** Phase 6: On Ready, build the implementation-task breakdown
@@ -150,7 +150,7 @@ The workflow is complete when these tasks exist, the completeness pass confirms
 Accept, modify, or reject — but never silently drop. The reviewer must be able to account for every point.
 
 ** Document the no's, not the yes's
-Accepted recommendations live in the spec body (the change *is* the record). Modified and rejected ones need an explicit written reason at the bottom, because the change is invisible and the reasoning would otherwise be lost. The asymmetry is deliberate.
+Accepted findings live in the spec body (the change *is* the record). Modified and rejected ones need an explicit written reason on the completed finding task, because the change is invisible and the reasoning would otherwise be lost. The asymmetry is deliberate.
 
 ** Critique, don't rubber-stamp
 A review you accept entirely without finding a single thing to push on probably wasn't read critically. Your judgment — including a well-reasoned no — is the value you add.
@@ -164,11 +164,11 @@ When reviews conflict, find the framing where both are right. Silently honoring
 ** A reject goes back to the reviewer, not just into the file
 Recording a reasoned reject is the floor, not the close. Communicate the rejection and its reason to the reviewer — a reject is a two-party event, not a unilateral call. If the reviewer disagrees, that's a discussion: weigh the counter, and if you still can't agree, escalate to whoever owns the decision rather than letting the author's "no" stand by default. "I'm not doing that" with no reason the reviewer can engage is the failure mode. (For a tight solo author-reviewer loop this is lightweight; for a team it's the difference between a review and a rubber-stamp-in-reverse.)
 
-** 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 spec reads forward, the findings read backward
+The body is written for the implementer (no review archaeology). A completed finding's reason 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.
+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 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.
@@ -213,3 +213,8 @@ Update this workflow as we learn what works. Capture new disposition patterns, b
 - *What:* Reconciled this workflow to spec-create's new Decisions convention (each decision is an org =TODO= task that flips to =DONE= on agreement, with a =[/]= cookie on the =* Decisions= heading and a =*** Discussion= child for disputes). Exit Criterion 5, Phase 2's pre-agreed-decisions step, and Phase 4 steps 4-5 now speak in flip-to-=DONE= terms, and the implementation-ready step gates on the all-=DONE= cookie.
 - *Why:* The convention change landed in spec-create.org via an .emacs.d handoff (originated in its keymap-consolidation spec); this workflow still described the retired =State: proposed | accepted | superseded= model.
 - *Artifacts:* Handoff =inbox/2026-06-12-1906-from-.emacs.d-spec-create-decisions-todo-note.org=. Paired spec-create.org and spec-review.org edits in the same commit.
+
+** 2026-06-21 Sun @ 23:16:06 -0400 — Claude Code (rulesets) — responder
+- *What:* Folded the review into the spec. Findings are now =* Review findings= =TODO= tasks the responder completes in place (accept/modify → =DONE=, reject → =CANCELLED= with the reason) instead of a "Review dispositions" section; the response is done when the =[/]= cookie reads complete, not when a review file is deleted. Phase 0 finds open work by an incomplete findings cookie; the Phase 4 implementation-ready gate now also requires the findings cookie, and rerun-the-readiness-rubric-on-expanded-scope is folded into that gate (a scope-expanding response must file new obligations as findings or decisions before claiming =Ready=).
+- *Why:* Deleting the review file left the iteration-history =Artifacts= line dangling and lost the verbatim review; keeping the file collided with this workflow's file discovery and its "no review files remain" done-condition. Craig's call: incorporate the review into the document, reusing the decisions machinery so the readiness signal is a cookie. The scope-expansion rerun closes a real gap — a response can resolve every finding and still introduce unreviewed obligations.
+- *Artifacts:* Paired spec-review.org edits in the same commit. Inbox handoffs =2026-06-20-2339-from-home-spec-response-readiness-gate-proposal.org= and =2026-06-21-0156-from-home-companion-to-tonight-s-spec-response.org=.