@skitterbyte/skitterspec 20.0.0 → 21.0.0

package/MIGRATION.md

@@ -1,5 +1,85 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v20 → v21 (the gate installs, and asking implies waiting)
+
+If you upgraded to v20 and the commit gate never once fired, this is why. Two
+independent bugs, either of which alone made it a no-op.
+
+### Breaking change
+
+**The hook ships as `.claude/hooks/review-gate.cjs`**, renamed from
+`review-gate.js`. The script is CommonJS and it is copied *into your* project,
+where your `package.json` decides how node parses a `.js` — so in any
+`"type": "module"` project it died on its own first `require`, printing a stack
+trace on **every Bash tool call**. `.cjs` settles the parse mode at the file,
+which is the only place independent of the one file skitterspec does not
+control. An ESM rewrite would have inverted the same problem onto CommonJS
+projects, which are still the default for anything with no `"type"` set.
+
+The upgrade migrates you: your existing `PreToolUse` entry has its path
+**rewritten in place** — so a wrapper, a flag or a different interpreter you
+added all survive — and the retired `review-gate.js` is deleted. If you edited
+that file yourself it is **kept**, with a warning, and left for you to remove.
+
+### Bug fix
+
+**`skitterspec update` now registers the hook.** v20's notes said `init` and
+`update` both did; only `init` did. `update` copied the script, reported
+`created: .claude/hooks/review-gate.js`, and wired nothing — so every project
+that upgraded into v20 got a hook file and no hook, with nothing saying so.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Commit `.claude/settings.json` and `.claude/hooks/review-gate.cjs`**, and
+   the deletion of `.claude/hooks/review-gate.js`. A hook only a fraction of the
+   team has is a gate that holds for a fraction of the team.
+3. **Check it is actually on** — the update reports
+   `updated: .claude/settings.json (review-gate hook)` the first time, and
+   `unchanged` afterwards. If it says neither, your settings file could not be
+   parsed; it was left untouched and the hook is not registered.
+
+### Behaviour change — a bug fix and a hotfix now owe a verdict
+
+**`/spec-bug` and `/spec-hotfix` now arm the review gate**, as `/spec-next`
+already did. Both render the page at the end of red→green work, and both now
+wait for your verdict instead of finishing — so in that spec's worktree a
+`git commit` is **refused** until one of two things happens:
+
+- you send a verdict from the page (or `/spec-reviewed` picks up one already
+  waiting), or
+- you run `skitterspec spec-env review skip "<reason>"`, which records the
+  decision to move on.
+
+The gate is still only armed by work that **finished**, it still fails open on
+every cannot-tell, and `review.required: false` in `specs/.core/env.config.json`
+still turns it off for a project.
+
+**Why.** Those two skills used to render the page, ask *"want a written review
+before you commit?"* and finish with nothing watching. A verdict pressed on that
+page sat in the holding area until someone typed `/spec-reviewed` — which they
+had no reason to do, because the run had said the page was *ready* rather than
+that it was *waiting*. Two verdicts were stranded that way on one spec, and the
+second existed only because the first appeared to do nothing.
+
+### New, and not breaking — the `Continue` verdict
+
+**A page rendered part-way through a run offers `Continue`** — *I have read it,
+carry on* — instead of the committing buttons, via
+`spec-env review <spec> --buttons midrun`. The default is unchanged, so a caller
+that passes nothing renders exactly the page it rendered before. `Continue` can
+never clear an armed gate: that still takes a committing verdict or a recorded
+skip.
+
+Nothing else changes: `review.required` still defaults to `true`, and the engine
+and `/spec-next` held the gate throughout regardless of the hook.
+
+## `@skitterbyte/skitterspec-linear` v14 → v15 (the gate installs, and asking implies waiting)
+
+The same change as `@skitterbyte/skitterspec` v20 → v21 above — this
+distribution composes the same lifecycle skills. Read that entry; nothing here
+is Linear-specific.
+
 ## `@skitterbyte/skitterspec` v19 → v20 (a phase owes a verdict)
 
 ### Breaking change
@@ -41,8 +121,10 @@ cannot-tell lets the commit through.
 ### Breaking change
 
 **`.claude/settings.json` is now written by the installer.** `skitterspec init`
-and `skitterspec update` copy `.claude/hooks/review-gate.js` and register it as
-a `PreToolUse` hook in your project's **committed** settings file. That is a
+and `skitterspec update` copy the hook script and register it as a `PreToolUse`
+hook in your project's **committed** settings file. (In v20 `update` copied
+without registering, and the script was named `review-gate.js` — both fixed in
+v21; read that entry above if you are landing on the current release.) That is a
 tracked file in most repos, so expect it in `git status` after upgrading — and
 commit it, because a hook only a fraction of the team has is a gate that holds
 for a fraction of the team.
@@ -76,8 +158,8 @@ as before.
 ### What to do
 
 1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
-2. **Commit `.claude/settings.json` and `.claude/hooks/review-gate.js`.** Both
-   are new in your working tree after the update.
+2. **Commit `.claude/settings.json` and the hook script.** Both are new in your
+   working tree after the update.
 3. **Nothing else to configure.** `review.required` defaults to `true` and
    `review.commitWith` defaults to `/commit`; neither needs adding unless you
    are changing it.

package/assets/core/env.config.md

@@ -74,8 +74,9 @@ no live `env.config.json` was found.
   // `spec-env up`, right after `git worktree add` and BEFORE `setup` runs — so a
   // fresh linked worktree (which starts with none of the repo's gitignored files)
   // has the .env / local secret overrides / local config that setup steps and
-  // git hooks depend on. Without this a step like `prisma generate` hard-fails in
-  // the new worktree because .env (its datasource URL) isn't there.
+  // git hooks depend on. Without this any setup step that reads .env — a schema
+  // or client generator, a codegen pass — hard-fails in the new worktree
+  // because the file it expects isn't there.
   //   mode   "symlink" (default) points the worktree file at the main file, so it
   //          stays in sync; "copy" makes an independent copy.
   //   files  repo-relative paths to seed. A source absent in main is a printed

package/assets/review/page.html

@@ -386,7 +386,13 @@ tr.note-row td {
 .verdict-title { font-size: .8rem; color: var(--muted); }
 .verdict-count { font-size: .8rem; color: var(--muted); }
 .v-commit { color: var(--good-fg); background: var(--good-bg); }
+/* Continue borrows the same affirmative pair: it is the mid-run reader saying
+   carry on, and it never appears beside a commit button to be confused with. */
+.v-continue { color: var(--good-fg); background: var(--good-bg); }
 .v-changes { color: var(--flag-fg); background: var(--flag-bg); }
+/* A button the render did not ask for is GONE, not dimmed — a disabled control
+   invites a reader to work out how to enable it, and there is nothing to do. */
+.verdict button[hidden] { display: none; }
 /* A blocked control is dashed as well as dimmed, so the block survives a
    greyscale screen — and the reason rides in the label, never in a tooltip
    nobody hovers on a phone. */
@@ -570,6 +576,12 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
         <span class="verdict-title">Your verdict</span>
         <button id="verdict-commit" class="v-commit" type="button" aria-live="polite">✓ Commit</button>
         <button id="verdict-commit-continue" class="v-commit" type="button" aria-live="polite">✓ Commit &amp; Continue</button>
+        <!-- THE MID-RUN VERDICT, hidden unless the render asked for it. "Commit"
+             is the wrong verb for unfinished work, so a page rendered part-way
+             through a run offers this instead of the committing pair: I have
+             read it, carry on. It is not the removed `none` verdict — that
+             recorded itself and did nothing, while this one resumes the run. -->
+        <button id="verdict-continue" class="v-continue" type="button" hidden>→ Continue</button>
         <button id="verdict-changes" class="v-changes" type="button">↺ Request changes</button>
         <button id="verdict-discuss" type="button">… Discuss first</button>
         <span class="verdict-count" id="verdict-count" aria-live="polite"></span>
@@ -1216,6 +1228,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   var verdictBtns = {
     commit: document.getElementById('verdict-commit'),
     'commit-continue': document.getElementById('verdict-commit-continue'),
+    continue: document.getElementById('verdict-continue'),
     changes: document.getElementById('verdict-changes'),
     discuss: document.getElementById('verdict-discuss'),
   }
@@ -1223,12 +1236,34 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
   // here, and the shared block below follows for free — the same reason the
   // engine keeps a `COMMITTING` list rather than a second condition.
   var COMMITTERS = ['commit', 'commit-continue']
-  // ALL FOUR, because this is now the one place a verdict gets a reader-facing
+
+  /*
+   * WHICH BUTTONS THIS PAGE OFFERS, and it comes from the render rather than
+   * from the gate. Deriving it — mid-run iff nothing is armed — would take the
+   * committing buttons away from every page in a project running
+   * `review.required: false`, which never arms and whose readers must still be
+   * able to commit from the page. The engine's `BUTTON_SETS` is the same
+   * decision on the other side of the wire.
+   *
+   * ABSENT IS THE COMMITTING SET. A page rendered before any of this existed,
+   * and a caller that did not ask, both land here — so nothing about their page
+   * changes.
+   */
+  var MIDRUN = data.buttons === 'midrun'
+  var OFFERED = MIDRUN ? ['continue', 'changes', 'discuss'] : ['commit', 'commit-continue', 'changes', 'discuss']
+  Object.keys(verdictBtns).forEach(function (key) {
+    verdictBtns[key].hidden = OFFERED.indexOf(key) === -1
+  })
+
+  // EVERY VERDICT, because this is the one place a verdict gets a reader-facing
   // name: `refresh` relabels only the committing pair, but the decided panel
-  // has to name whichever verdict was actually sent.
+  // has to name whichever verdict was actually sent — including one this page
+  // never offered, since a decision restored from storage outlives the render
+  // that made it.
   var LABELS = {
     commit: '✓ Commit',
     'commit-continue': '✓ Commit & Continue',
+    continue: '→ Continue',
     changes: '↺ Request changes',
     discuss: '… Discuss first',
   }
@@ -1237,6 +1272,9 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     // Says what it will NOT do: a reader must not press this expecting the
     // spec to be finished and landed.
     'commit-continue': 'Commit what you just read, then build the next phase — nothing is landed',
+    // Says what it will NOT do, for the same reason: nothing is committed by
+    // this, so the work it resumes is still uncommitted afterwards.
+    continue: 'You have read it — carry on with the run; nothing is committed',
   }
 
   var verdictCount = document.getElementById('verdict-count')
@@ -1286,7 +1324,9 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     var open = openNotes()
     verdictCount.textContent = n
       ? n + (n === 1 ? ' mark to send' : ' marks to send')
-      : 'Nothing marked — a clean read still commits'
+      // Names the action this page actually offers. A mid-run page saying "a
+      // clean read still commits" would promise the one thing it cannot do.
+      : MIDRUN ? 'Nothing marked — a clean read still carries on' : 'Nothing marked — a clean read still commits'
     // ONE COUNT, BOTH BUTTONS. Two committing controls blocked by two separate
     // reads is how a page ends up with one disabled and the other not — which
     // would be a way around the single refusal this page makes.
@@ -1315,8 +1355,15 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
           : TITLES[key]
     })
     // Said rather than left unset: the committing pair is the ONLY thing this
-    // page ever blocks, and the other two are always available on purpose — a
-    // note you want acted on, and a question, are never the wrong thing to send.
+    // page ever blocks, and the others are always available on purpose — a note
+    // you want acted on, and a question, are never the wrong thing to send.
+    //
+    // CONTINUE IS NOT BLOCKED, and that mirrors the engine rather than softening
+    // it: `judgeVerdict` refuses a COMMITTING verdict against an open note, and
+    // `continue` is deliberately not one. A disabled button here would be a
+    // second opinion about a refusal the engine does not make, which is the one
+    // thing this bar must never be.
+    verdictBtns.continue.disabled = false
     verdictBtns.changes.disabled = false
     verdictBtns.discuss.disabled = false
     save()
@@ -1400,6 +1447,7 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
     approve: 'committed',
     commit: 'committed',
     'commit-continue': 'committed, then carried on',
+    continue: 'read it and carried on',
     changes: 'changes requested',
     discuss: 'discussed',
     skip: 'moved on without a verdict',
@@ -1716,9 +1764,11 @@ button:disabled:hover { color: var(--muted); border-color: var(--line); }
 
   Object.keys(verdictBtns).forEach(function (verdict) {
     verdictBtns[verdict].addEventListener('click', function () {
-      // A disabled button does not fire in a browser; the guard is for every
-      // other caller, and it keeps the block a fact rather than a style.
-      if (verdictBtns[verdict].disabled) return
+      // A disabled or hidden button does not fire in a browser; the guard is
+      // for every other caller, and it keeps both the block and the button set
+      // facts rather than styles — a verdict this render never offered must not
+      // be reachable by dispatching at it.
+      if (verdictBtns[verdict].disabled || verdictBtns[verdict].hidden) return
       send(verdict)
     })
   })

package/assets/rules/spec-planning.md

@@ -244,10 +244,10 @@ things clear it — a **committing verdict**, or
 `git commit` refuses in that worktree. `skitterspec spec-env review gate
 [--check] [--json]` is what both ask.
 
-**The hook is the half that cannot be talked past.** `skitterspec init` installs
-`.claude/hooks/review-gate.js` and registers it in the project's committed
-`.claude/settings.json`, so a `git commit` is refused by the harness rather than
-by prose — which is what covers a bare `git commit`, a chained command, and
+**The hook is the half that cannot be talked past.** `skitterspec init` and
+`skitterspec update` install `.claude/hooks/review-gate.cjs` and register it in
+the project's committed `.claude/settings.json`, so a `git commit` is refused by
+the harness rather than by prose — which is what covers a bare `git commit`, a chained command, and
 skittership's own `/commit` without skitterspec ever editing it. It decides
 nothing itself: it hands the command line to
 `spec-env review gate --check --for-command` and turns one exit status into an
@@ -301,7 +301,7 @@ its verdicts and its fields.
 | **Branch** | `spec/feat-orders` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
 | **Tests** | 128 passed · npm test |
-| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Review** | 7 files, +212 −18 · [open the page](file:///…) |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 

package/assets/rules/spec-reports.md

@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
 | **Branch** | `spec/feat-foo` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
 | **Tests** | 128 passed · npm test |
-| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Review** | 7 files, +212 −18 · [open the page](file:///…) |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 
@@ -97,15 +97,54 @@ A rule, a heading naming the state and the size, the link in bold, one line
 saying the run is stopped, and the two exits. Nothing else, and never a
 paragraph explaining it.
 
-**Only promise a wait the transport can deliver.** A page the engine SERVES
-hands its pass to the local store, which a file-watch sees — that is the one
-case where *"I'm holding here"* is true. A **published** page writes to the
-artifact's own store, and nothing pushes from there into the conversation, so a
-verdict pressed on it is invisible until someone asks for it. Its banner says
-so instead:
+**Only promise a wait the transport can deliver.** The wait itself is real in
+every case; what varies is what carries it back, not whether the run is
+stopped. Three transports, three true sentences:
+
+- **A page the engine SERVES** hands its pass to the local store, which a
+  file-watch sees. The run is woken by the press:
+  *"I'm holding here until you send a verdict."*
+- **A `file://` page** has no server to POST to, so the pass is copied and
+  pasted — the reader's next message is what carries it. The run is stopped just
+  the same, and says so:
+  *"I'm holding here — paste the pass when you have it."*
+  This is the same wait, carried by the conversation instead of a watch. It is
+  not a lesser one, and it is not an excuse to ask without waiting.
+- **A PUBLISHED page** writes to the artifact's own store, and nothing pushes
+  from there into the conversation. That is the one case where a verdict is
+  genuinely invisible until someone asks for it, so the banner says that instead
+  of claiming a watch:
 
 **[Open the page](https://…)** · press a verdict, then type `/spec-reviewed` — I cannot see it until you do.
 
+**A harness with no file-watch does not get an exemption.** It once read
+"change nothing" — keep the row, keep the question, do not wait — and that
+escape hatch is what let a whole class of runs go on asking questions nobody was
+listening for. Where a watch is unavailable the wait is the turn ending, which
+every harness can do.
+
+**The `Continue` ending, and why the banner's exits differ mid-run.** A page
+rendered part-way through a run offers `Continue` — *I have read it, carry on* —
+in place of the committing verdicts, because "commit" is the wrong verb for
+unfinished work. Its banner names the same state and different exits:
+
+**[Open the page](http://…)** · I'm holding here until you send a verdict.
+
+`Continue` carries on · `Request changes` works them now
+
+**It is not the `none` verdict that was removed.** `none` recorded itself and
+did nothing, which is the record-and-do-nothing ending this contract exists
+against. `Continue` **resumes the run** — it names an action, which is the bar
+every verdict has to clear. What it does not do is commit, and it can never
+clear the gate a finished phase armed: that gate is discharged by a committing
+verdict or a recorded skip, and by nothing else.
+
+**So waiting and arming are separate**, and only one of them is about this
+block. *Waiting* is what any offer does, and it is what this section governs.
+*Arming* asserts an obligation that outlives the turn, and belongs only to work
+that is finished. A mid-run render waits without arming — walking away from it
+costs nothing, which is exactly why `Continue` is safe to offer there.
+
 **Exactly one link, never two.** The banner offers the page the reader can
 actually use, and the engine has already decided which that is — a served URL
 when it could serve, a published one only when it could not. Handing over both
@@ -124,11 +163,34 @@ stopped until they answer. A row cannot carry that, because a row is scanned at
 the same weight as every other row. So the state gets the loudest shape on
 screen, at the end, where reading finishes.
 
-**Where the run is not waiting, it stays a `Review` row.** A render nobody is
-being held for — a mid-phase `/spec-diff`, a page produced alongside other work
-— is a convenience, and giving it a banner teaches the reader to scroll past
-banners. The shape marks the difference between *here is a page* and *nothing
-proceeds until you answer*.
+**ASKING IMPLIES WAITING — one rule, and the two shapes follow from it.** Any
+render that asks the reader for a verdict ends the turn watching for one. A run
+that does not intend to wait does not ask: its `Review` row keeps the counts and
+the link and **loses the question**.
+
+So there are two shapes and no third:
+
+- **Asking** → the banner above, and the run waits.
+- **Not asking** → the `Review` row: counts and link, no question.
+
+**What this guards against is a reader taught that the button is decorative.**
+`/spec-bug` and `/spec-hotfix` used to render the page, emit a row
+asking *"want a written review before you commit?"*, and finish — with nothing
+watching. A verdict pressed on that page landed in the holding area and stayed
+there, because the run had told the reader the page was **ready** rather than
+that it was **waiting**. It happened twice on one spec, and the second press
+existed only because the first appeared to do nothing. An offer that cannot be
+answered costs more than never having offered.
+
+**Rejected: keeping the question and adding a caveat** — *"press a verdict, but
+I will not see it until you ask"*. That is exactly the shape that stranded those
+two passes, and a truthful caveat does not make an unanswerable question worth
+asking. Either watch for the answer, or do not ask.
+
+**A render nobody is being held for is still worth reporting** — a mid-phase
+`/spec-diff`, a page produced alongside other work. It gets the row, because
+giving it a banner teaches the reader to scroll past banners. The shape marks
+the difference between *here is a page* and *nothing proceeds until you answer*.
 
 **Never fence a message to the reader.** A fenced block is for a command to
 run, code, or engine output quoted verbatim — things the reader copies or
@@ -185,7 +247,7 @@ behind it — say nothing rather than reporting that there was nothing to report
 | `Landed` | A fast-forward, a tag, a cherry-pick. |
 | `Worktree` | A worktree provisioned, entered, or torn down. |
 | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
-| `Review` | The rendered diff page: files, `+`/`−`, the link — and the offer of a written review, in the same row. **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
+| `Review` | The rendered diff page: files, `+`/`−`, the link. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
 | `Follow-ups` | **Always.** `none`, or one line each. |
 | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
 
@@ -204,11 +266,17 @@ silent, because "I provisioned, and your four files are still sitting there" is
 a different sentence from "I provisioned".
 
 **`Review` is one row, not two** — and where the run is waiting, it is no rows
-at all. The page and the offer to read it are the same subject, and splitting
-them made the reader resolve a distinction before acting on either. A waiting
-run promotes the whole subject into the banner; keeping the row as well would
+at all. The page and what to do with it are the same subject, and splitting them
+made the reader resolve a distinction before acting on either. A waiting run
+promotes the whole subject into the banner; keeping the row as well would
 recreate that split with the two halves further apart than ever.
 
+**The row carries no question, and that is the rule above applied here.** It
+once ended *"want a written review before you commit?"* — a question addressed
+to a reader the run was not waiting for. Putting it in a findable row fixed
+where it was; it did not fix that nothing was listening. A run that wants that
+question answered waits for it, and waiting means the banner.
+
 ## The four verdicts
 
 | State | Means |

package/assets/skills/spec-bug/SKILL.md

@@ -208,7 +208,7 @@ is a no-op.
 
 
 
-## 5b. Render the page — then offer the review, never write it
+## 5b. Render the page, arm the gate, then wait for the verdict
 
 **Only when the project has per-spec isolation** (`specs/.core/env.config.json`
 present). Without it there is no worktree to read and this step does not exist —
@@ -224,28 +224,37 @@ skitterspec spec-env review <spec>
 **This is free.** The engine reads git and splices the patches into a template;
 the diff never passes through you, so a 266KB patch costs nothing.
 
-**Then offer `/spec-diff`. Do not run it.** The written review is the part that
-costs — roughly **700 output tokens**, because writing it means reading the diff
-— and that spend is the operator's call, not a default.
+**Then arm the gate**, so the fix now owes a verdict:
 
-**The offer is the `Review` row of step 6's block** — the counts, the page link
-and a question, in one row:
-
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
-
-**It ends in a question, addressed to someone.** It was once a fenced block of
-engine output, and it fired on every phase and was never once taken: two quoted
-lines under the test counts, addressed to nobody, with the report then closing
-on *"commit this first"* — the last instruction the reader got was to move on,
-so they did. A row in a labelled table is findable; a question in it is
-answerable. Both halves are load-bearing.
-
-**Never bury it and never split it.** It sits above `Follow-ups` and `Next`, and
-the page and the question stay in the same row: two adjacent rows about one page
-make the reader resolve a distinction before acting on either. A later edit that
-moves it out of the block, or separates the link from the question, undoes this
-and should be read as a regression rather than tidying.
+```
+skitterspec spec-env review arm <spec>
+```
 
+**Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
+than reading a second copy here: note the moment you start waiting, watch the
+pending store, end your turn, and let `--claim-since` pick the one pass that
+arrived inside the window. The banner it describes is what this skill emits in
+place of a `Review` row, and the routing on the verdict is `/spec-diff` §2 and
+§4, as it is everywhere.
+
+**Why this skill arms as well as waits.** Waiting is what any offer does;
+**arming** asserts an obligation that outlives the turn, and belongs only to
+work that is finished. A bug fix is a completed unit — red→green, suite
+passing — so it qualifies, and a wait with nothing owed behind it is a
+suggestion rather than a gate. A mid-run render waits without arming, and
+walking away from that costs nothing.
+
+**This is the gap this step existed inside.** It used to render the page, emit a
+row asking *"want a written review before you commit?"*, and finish — with
+nothing watching. A verdict pressed on that page landed in the holding area and
+stayed there, because the run had said the page was **ready** rather than that
+it was **waiting**. Two were pressed on one spec and both were stranded; the
+second existed only because the first appeared to do nothing.
+
+**It is user-visible, and that is deliberate.** Once armed, a `git commit` in
+this worktree is refused until a verdict is sent or
+`skitterspec spec-env review skip "<reason>"` records the decision to move on.
+The exit is always one command, and one of them is *"I am moving on"*.
 
 Relay the **`open:`** line rather than the bare path: a path is not clickable in
 any terminal, and a page nobody can open is a page nobody reads.
@@ -307,9 +316,15 @@ the shape; this section carries only what is specific here.
 **Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
 `Review` · `Follow-ups` · `Next`
 
+**`Review` is emitted only where step 5b did not run** — a project with no
+isolation, or a render that failed. Where the run is waiting, the banner carries
+the whole subject and the row is dropped, per `.claude/rules/spec-reports.md`.
+
 `Cause` is the root cause in one clause and `Built` is the fix — the
 failing→passing test belongs in `Tests`, named, so the evidence is a test name
 rather than an adjective.
 
-Step 5b's offer is the `Review` row, not a paragraph after the block — the
-counts, the link and the question in one row. Nothing follows the block.
+Step 5b ends in the **banner**, not a paragraph and not a row — the run is
+waiting on a verdict, and the banner is the shape that says so. Nothing follows
+it. Where the run is not waiting it asks nothing at all: a `Review` row carries
+the counts and the link, and no question (*asking implies waiting*).

package/assets/skills/spec-diff/SKILL.md

@@ -401,6 +401,31 @@ Add `--json` to get the file list, totals and the page path back as data. The
 page is written to `.spec-env/reviews/<spec>.html`, which is gitignored — it
 leaves no trace in the branch under review.
 
+**Declare the button set when the work is unfinished.** A page rendered part-way
+through a run takes `--buttons midrun`, and offers `Continue` — *I have read it,
+carry on* — in place of `Commit` and `Commit & Continue`:
+
+```
+skitterspec spec-env review <spec> --buttons midrun
+```
+
+**It is a statement about the work, never a reading of the gate.** Ask whether
+the thing you just rendered is *finished*: a phase that ended, a bug fix that is
+green, a spec about to land — committing set, which is the default, so pass
+nothing. Half a phase, a hand edit, a colleague's branch mid-flight, anything
+the operator asked to look at while it is still moving — `midrun`.
+
+**Do not derive it from whether the gate is armed.** That is tidier and wrong: a
+project running `review.required: false` never arms at all, so every one of its
+pages would lose the committing buttons and its reader could never commit from
+the page. The caller knows what it rendered; the gate only knows whether the
+project opted into gating.
+
+`Continue` is not the removed `none` verdict. `none` recorded itself and did
+nothing; `Continue` **resumes the run**, so it still names an action. What it
+cannot do is commit, or clear a gate a finished phase armed — that takes a
+committing verdict or a recorded skip.
+
 **On `--page-only`, stop here** and report the path.
 
 ## 4a. Read the `reader:` line — never sniff for it yourself
@@ -439,7 +464,7 @@ operator settle where they are reading, and an explicit value is believed withou
 sniffing. `review.serveOnRemote` (default `true`) settles whether the engine may
 act on it.
 
-## 4b. Wait for the verdict, where the harness can watch a file
+## 4b. Wait for the verdict — because asking for one means waiting for it
 
 A served page can hand its pass back the moment it is pressed. Without a wait,
 that pass lands in the holding area and stops — nothing happens until someone
@@ -448,10 +473,28 @@ acts joined only by the operator remembering.
 **This is the step that joins them**, and it is this skill's, so `/spec-next` can point here rather than
 keeping a second copy.
 
-**Wait when the page was served and the reader is going to read it now.** That
-is the phase-end case, and an operator who says they will look later. Do not
-wait on a bare `--page-only`, on a render nobody asked to be woken about, or
-when the pass has already arrived — there is nothing to wait for.
+**The rule is `.claude/rules/spec-reports.md`'s: asking implies waiting.** If
+this render asks the reader for a verdict, it waits for one. If it is not going
+to wait, it does not ask — the report names the page and its size and stops
+there. There is no third option, and in particular there is no *ask now, notice
+later*: that is the shape that stranded two passes on one spec, where the run
+said the page was **ready** rather than that it was **waiting**.
+
+**So the question is not "can I watch a file".** It is "am I asking?" — and the
+transport only decides what carries the answer back:
+
+- **A served page** posts to the local store; a file-watch sees it, and the
+  steps below are that watch.
+- **A `file://` page** has nothing to post to, so the reader pastes the pass and
+  their next message carries it. Say you are holding and **end the turn** — that
+  is the same wait, carried by the conversation. It is not a lesser one.
+- **A published page** writes to the artifact's own store, which nothing reaches
+  from here. That is the one case where the honest sentence is *press a verdict,
+  then type `/spec-reviewed`* — see the published-page paragraph below.
+
+**Do not ask, and therefore do not wait, on a render nobody is waiting behind** —
+a bare `--page-only`, a page produced alongside other work, a pass that has
+already arrived. Those get the `Review` row, no question, and nothing is owed.
 
 1. **Note the moment**, as an ISO timestamp, before you start. That instant is
    the entire scope of what may be claimed without a person naming it.
@@ -492,10 +535,16 @@ Where the page is published, say plainly that `/spec-reviewed` is what picks it
 up.
 
 **`/spec-reviewed` is not replaced by this.** It stays the way in for a pass
-that arrived when nobody was waiting, for the two-passes case, for every
-published page, and for every harness with no file-watch at all. It is user-only, and that is still the
+that arrived when nobody was waiting, for the two-passes case, and for every
+published page. It is user-only, and that is still the
 enforcement that makes a named claim a person's decision.
 
+**A harness with no file-watch is no longer on that list**, and that is the
+change. It used to be — the row and `/spec-reviewed` were "the whole story",
+which read as permission to ask without waiting. Now the turn ending is the
+wait, and every harness can end a turn; `/spec-reviewed` remains available
+there, as it is everywhere, for a pass nobody was holding for.
+
 ## 5. Offer the written review — say what it costs first
 
 The page is free. The **written review is not**, and it costs in two separate

package/assets/skills/spec-hotfix/SKILL.md

@@ -230,7 +230,7 @@ is a no-op.
 
 
 
-## 6b. Render the page — then offer the review, never write it
+## 6b. Render the page, arm the gate, then wait for the verdict
 
 **Only when the project has per-spec isolation** (`specs/.core/env.config.json`
 present). Without it there is no worktree to read and this step does not exist —
@@ -246,28 +246,33 @@ skitterspec spec-env review <spec>
 **This is free.** The engine reads git and splices the patches into a template;
 the diff never passes through you, so a 266KB patch costs nothing.
 
-**Then offer `/spec-diff`. Do not run it.** The written review is the part that
-costs — roughly **700 output tokens**, because writing it means reading the diff
-— and that spend is the operator's call, not a default.
+**Then arm the gate**, so the fix now owes a verdict:
 
-**The offer is the `Review` row of step 6's block** — the counts, the page link
-and a question, in one row:
+```
+skitterspec spec-env review arm <spec>
+```
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+**Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
+than reading a second copy here: note the moment you start waiting, watch the
+pending store, end your turn, and let `--claim-since` pick the one pass that
+arrived inside the window. The banner it describes is what this skill emits in
+place of a `Review` row, and the routing on the verdict is `/spec-diff` §2 and
+§4, as it is everywhere.
 
-**It ends in a question, addressed to someone.** It was once a fenced block of
-engine output, and it fired on every phase and was never once taken: two quoted
-lines under the test counts, addressed to nobody, with the report then closing
-on *"commit this first"* — the last instruction the reader got was to move on,
-so they did. A row in a labelled table is findable; a question in it is
-answerable. Both halves are load-bearing.
+**Why this skill arms as well as waits.** Waiting is what any offer does;
+**arming** asserts an obligation that outlives the turn, and belongs only to
+work that is finished. A hotfix is a completed unit — red→green against a
+released tag — so it qualifies, and a wait with nothing owed behind it is a
+suggestion rather than a gate.
 
-**Never bury it and never split it.** It sits above `Follow-ups` and `Next`, and
-the page and the question stay in the same row: two adjacent rows about one page
-make the reader resolve a distinction before acting on either. A later edit that
-moves it out of the block, or separates the link from the question, undoes this
-and should be read as a regression rather than tidying.
+**A hotfix is the case where reading it matters most.** This change is about to
+be tagged and shipped to production from a release line, not merged into a
+branch someone else will read first. The verdict is the only review it gets.
 
+**It is user-visible, and that is deliberate.** Once armed, a `git commit` in
+this worktree is refused until a verdict is sent or
+`skitterspec spec-env review skip "<reason>"` records the decision to move on.
+The exit is always one command, and one of them is *"I am moving on"*.
 
 Relay the **`open:`** line rather than the bare path: a path is not clickable in
 any terminal, and a page nobody can open is a page nobody reads.
@@ -335,10 +340,16 @@ the shape; this section carries only what is specific here.
 **Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
 `Review` · `Follow-ups` · `Next`
 
+**`Review` is emitted only where step 6b did not run** — a project with no
+isolation, or a render that failed. Where the run is waiting, the banner carries
+the whole subject and the row is dropped, per `.claude/rules/spec-reports.md`.
+
 **The base tag goes in the verdict clause** — `✅ /spec-hotfix · hotfix-foo ·
 green on v2.3.1`. Which released version this was fixed against is the first
 thing anyone needs, and it is not a field: the clause is where the run says
 where it got to.
 
-Step 6b's offer is the `Review` row, not a paragraph after the block — the
-counts, the link and the question in one row. Nothing follows the block.
+Step 6b ends in the **banner**, not a paragraph and not a row — the run is
+waiting on a verdict, and the banner is the shape that says so. Nothing follows
+it. Where the run is not waiting it asks nothing at all: a `Review` row carries
+the counts and the link, and no question (*asking implies waiting*).

package/assets/skills/spec-init/SKILL.md

@@ -105,12 +105,24 @@ Ensure it exists. If missing, create it documenting:
 Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
 rather than inventing them. If the rule already exists, leave it unless stale.
 
-## 4a. The review-gate hook (`.claude/hooks/review-gate.js`)
-
-`skitterspec init` installs the hook script and registers it in the project's
-**committed** `.claude/settings.json` as a `PreToolUse` hook on `Bash`. It runs
-one engine call per Bash tool call and refuses a `git commit` in a worktree
-whose phase is still awaiting a verdict.
+## 4a. The review-gate hook (`.claude/hooks/review-gate.cjs`)
+
+`skitterspec init` **and `skitterspec update`** install the hook script and
+register it in the project's **committed** `.claude/settings.json` as a
+`PreToolUse` hook on `Bash`. It runs one engine call per Bash tool call and
+refuses a `git commit` in a worktree whose phase is still awaiting a verdict.
+
+**Both commands, and that is not a detail.** Copying the script and registering
+it are one operation, and they were once split across two code paths — so
+`update` landed the file, reported `created:`, and wired nothing, on every
+project that upgraded. Landing the script is not installing the hook.
+
+**`.cjs`, and the extension is load-bearing.** The script lands inside the
+target project, where *that* project's `package.json` decides how node parses a
+`.js` — so CommonJS shipped as `.js` crashes in any `"type": "module"` project,
+on every Bash tool call. `.cjs` settles it at the file. A registration left over
+from the release that named `.js` is rewritten in place, keeping any wrapping
+the operator added, rather than gaining a second entry beside it.
 
 **Committed, not machine-local**, and the difference is the point: the trusted
 worktree root is one machine's absolute path, while *a phase that ended owes an

package/assets/skills/spec-next/SKILL.md

@@ -269,6 +269,12 @@ skitterspec spec-env review <spec>
 the diff never passes through you, so a 266KB patch costs nothing. Report the
 path it prints and move on.
 
+**This render takes the committing button set**, which is the default — so
+`--buttons` is not passed. That is a statement about the work, not about the
+gate: the phase is finished, so `Commit` and `Commit & Continue` are the right
+verbs for it. A render part-way through a run takes `--buttons midrun` and
+offers `Continue` instead; `/spec-diff` owns that case.
+
 **Then arm the gate**, so the phase now owes a verdict:
 
 ```
@@ -313,21 +319,31 @@ else.
 
 ---
 
-**Where you are not waiting, it stays the `Review` row** — the counts, the page
-link and a question, in one row:
+**Where you are not waiting, it stays the `Review` row** — the counts and the
+page link, and **no question**:
+
+| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) |
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+At the end of a phase you are always waiting, so this shape belongs to the
+renders that are not this step: a mid-phase `/spec-diff`, a page produced
+alongside other work. A row cannot be waited on, so a question in one is
+unanswerable however findable it is.
 
 **Both shapes are addressed to someone, and that is the constraint.** The offer
 was once a fenced block of engine output: two quoted lines under the test
 counts, addressed to nobody, with the report then closing on *"commit this
 first"* — the last instruction the reader got was to move on, so they did. A row
-in a labelled table is findable; a question in it is answerable; a banner says
-the work has stopped. What must never come back is something unaddressed,
-unfindable, or fenced.
+in a labelled table is findable; a banner says the work has stopped. What must
+never come back is something unaddressed, unfindable, or fenced.
+
+**The row asks nothing, and that is not a weakening of the above.** A row cannot
+be waited on, so a question in one is unanswerable however findable it is —
+which is the failure `spec-reports.md` records under *asking implies waiting*.
+The row names the page; the banner is what asks, because the banner is the shape
+the run is standing behind.
 
 **Never bury it and never split it.** The row sits above the last two rows of
-the block, and the page and the question stay in the same row; the banner
+the block, and the page and its counts stay in the same row; the banner
 replaces the row rather than joining it. Two places naming one page make the reader
 resolve a distinction before acting on either — which is the same failure
 whether the two places are adjacent rows or a row and a banner.
@@ -371,9 +387,15 @@ is that the page can now act, so the token has become a credential rather than
 a convenience — and `--claim-since` refusing to choose between two passes is
 what stops a race becoming a wrong commit.
 
-**Where the harness cannot watch a file, change nothing.** The `Review` row and
-`/spec-reviewed` are the whole story, exactly as before. The gate still holds
-either way: it is the engine's, not the watch's.
+**Where the harness cannot watch a file, you still wait** — the turn ending is
+the wait. Say the page is rendered and that you are holding for the pass, then end
+your turn; the reader's next message is what carries it, and `/spec-diff` picks
+it up from the paste exactly as it always has. The gate holds either way: it is
+the engine's, not the watch's.
+
+This once read *"change nothing"* — keep the row, keep the question, do not
+wait — and that exemption is the hatch a whole class of unanswerable questions
+came through. Every harness can end a turn.
 
 **It still does not break a chained run.** `/commit && /spec-next` is typed as
 one line; by the time this step is reached the chain has finished, so waiting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "20.0.0",
+  "version": "21.0.0",
   "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -76,6 +76,8 @@ const {
   mergeNotes,
   applyResolutions,
   COMMITTING,
+  BUTTON_SETS,
+  DEFAULT_BUTTON_SET,
   reviewGatePath,
   readGate,
   writeGate,
@@ -1633,6 +1635,9 @@ function verdictSaid(v) {
   // thing that will happen to the repo and the reader should see it coming.
   if (v.effective === 'commit') return `committing with ${v.commitWith}`
   if (v.effective === 'commit-continue') return `committing with ${v.commitWith}, then the next phase`
+  // Names what it does NOT do, because the reader of a mid-run page has just
+  // pressed a green button and must not read it as a commit.
+  if (v.effective === 'continue') return 'read — carrying on, nothing committed'
   if (v.effective === 'changes') return 'changes requested'
   return 'discuss first'
 }
@@ -1827,6 +1832,20 @@ function specEnvReviewSkip(dir, config, reason, flags) {
 }
 
 async function specEnvReview(dir, config, specArg, flags) {
+  // REFUSED BY NAME, never coerced to the default. A typo'd button set silently
+  // rendering the committing page is the same failure the verdict validator
+  // refuses for the same reason: a caller asking for the mid-run page and
+  // getting the committing one would offer a reader a commit on unfinished
+  // work, and nothing would have said so.
+  if (flags.buttons !== null && !BUTTON_SETS.includes(flags.buttons)) {
+    process.stdout.write(
+      `spec-env review: --buttons ${JSON.stringify(flags.buttons)} is not one of ` +
+        `${BUTTON_SETS.join(', ')} — nothing rendered.\n`,
+    )
+    return
+  }
+  const buttons = flags.buttons || DEFAULT_BUTTON_SET
+
   // An unknown name throws here rather than falling back to the branch: a review
   // of the wrong spec looks exactly like a review of the right one.
   const spec = resolveSpecWithWorktree(dir, config, specArg)
@@ -2166,7 +2185,7 @@ async function specEnvReview(dir, config, specArg, flags) {
   const gate = gateNow.corrupt ? null : gateNow.gate
 
   const now = new Date().toISOString()
-  let data = collectReview({ spec, git, mode, ref, base, now, notes, gate })
+  let data = collectReview({ spec, git, mode, ref, base, now, notes, gate, buttons })
 
   // A CLEAN WORKING TREE IS NOT "NOTHING TO REVIEW". It is the state a phase
   // ends in: the page is rendered before the commit, the commit happens
@@ -2199,6 +2218,7 @@ async function specEnvReview(dir, config, specArg, flags) {
         now,
         notes,
         gate,
+        buttons,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -2291,6 +2311,10 @@ async function specEnvReview(dir, config, specArg, flags) {
           urlFile,
           url,
           notesFile: reviewNotesPath(out),
+          // Absent stays absent, exactly as it is in the page payload: the
+          // committing set is what a caller that did not ask always got, so
+          // reporting it would make every existing consumer see a new key.
+          ...(data.buttons ? { buttons: data.buttons } : {}),
           reviewed: Boolean(data.review),
           totals: data.totals,
           notes: data.notes,
@@ -3444,6 +3468,7 @@ async function specEnv(rest) {
     outcome: null,
     claim: null,
     drop: null,
+    buttons: null,
     json: false,
   }
   for (let i = 0; i < args.length; i++) {
@@ -3458,6 +3483,7 @@ async function specEnv(rest) {
     else if (args[i] === '--port') flags.port = args[++i]
     else if (args[i] === '--host') flags.host = args[++i]
     else if (args[i] === '--publish-copy') flags.publishCopy = true
+    else if (args[i] === '--buttons') flags.buttons = args[++i]
     else if (args[i] === '--out') flags.out = args[++i]
     else if (args[i] === '--review') flags.review = args[++i]
     else if (args[i] === '--notes') flags.notes = args[++i]
@@ -3556,13 +3582,14 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--json] [--record-primary] [--assert-primary-clean]\n' +
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>] [--branch] [--out <file>] [--review <json>] [--notes <json>] [--resolve <json>] [--outcome <text>] [--claim <code>] [--drop <code>] [--buttons <set>] [--json] [--record-primary] [--assert-primary-clean]\n' +
         '  review serve [--port <n>] [--host <addr>] [--stop] [--status]  serve every diff locally\n' +
           '  review arm [spec] [--phase <n>]        a phase ended — its diff now owes a verdict\n' +
           '  review gate [spec] [--check] [--json]  is one owed? --check exits non-zero if so\n' +
           '       [--for-command <cmdline>]         ...but only when that command is a git commit\n' +
           '  review skip "<reason>"                 move on without one, on the record\n' +
           '  review [spec] --claim-since <iso>      claim the one pass that arrived since <iso>\n' +
+          '  review [spec] --buttons midrun         the page offers Continue, not a commit\n' +
           '  [spec] is optional everywhere: omit it and the worktree you are standing\n' +
           '  in is used, else the sole provisioned spec (several -> it lists them).\n' +
           '  A bare `live` takes that spec when the workbench is free, and prints the\n' +

package/src/env/hooks.js

@@ -18,8 +18,21 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
-const HOOK_SCRIPT = '.claude/hooks/review-gate.js'
+// `.cjs`, and the extension is load-bearing. This file is copied INTO the target
+// project, where that project's `package.json` decides how node parses a `.js` —
+// so the CommonJS script shipped as `review-gate.js` died on its own first
+// `require` in every `"type": "module"` project, printing a stack trace over
+// every Bash tool call. `.cjs` settles the parse mode at the file, independently
+// of the one file skitterspec does not control.
+const HOOK_STEM = '.claude/hooks/review-gate'
+const HOOK_SCRIPT = `${HOOK_STEM}.cjs`
 const HOOK_COMMAND = `node "\${CLAUDE_PROJECT_DIR}/${HOOK_SCRIPT}"`
+
+// Our script under ANY extension, so a registration naming the retired `.js` is
+// recognised as ours and migrated rather than duplicated. The trailing lookahead
+// is the boundary: without it `review-gate-extra.js` — somebody else's hook —
+// matches on the stem and gets silently rewritten.
+const HOOK_SCRIPT_RE = /[.]claude[/\\]hooks[/\\]review-gate(?:[.][A-Za-z0-9]+)?(?![\w.-])/
 // Seconds. The engine call behind this is one git-free read of a small JSON
 // file, so anything approaching this is a wedge rather than slow work — and a
 // hook that times out fails OPEN, which is the answer we want for a wedge.
@@ -55,13 +68,21 @@ function hookEntry() {
  * run it twice and look like a bug in the gate.
  */
 function alreadyRegistered(preToolUse) {
-  if (!Array.isArray(preToolUse)) return false
-  return preToolUse.some(
-    (group) =>
-      isObject(group) &&
-      Array.isArray(group.hooks) &&
-      group.hooks.some((h) => isObject(h) && typeof h.command === 'string' && h.command.includes(HOOK_SCRIPT)),
-  )
+  return registeredHooks(preToolUse).length > 0
+}
+
+// Every hook object under `PreToolUse` whose command names our script, whatever
+// extension it names it under. Pure.
+function registeredHooks(preToolUse) {
+  if (!Array.isArray(preToolUse)) return []
+  const out = []
+  for (const group of preToolUse) {
+    if (!isObject(group) || !Array.isArray(group.hooks)) continue
+    for (const h of group.hooks) {
+      if (isObject(h) && typeof h.command === 'string' && HOOK_SCRIPT_RE.test(h.command)) out.push(h)
+    }
+  }
+  return out
 }
 
 /**
@@ -69,6 +90,7 @@ function alreadyRegistered(preToolUse) {
  * Idempotent and non-destructive. Returns `{ changed, reason }`:
  *   - `created`   — no settings file; one was written
  *   - `added`     — merged into an existing file
+ *   - `migrated`  — registered under a retired path; the path was rewritten
  *   - `present`   — already registered (no write)
  *   - `malformed` — the file exists but is not parseable JSON (left untouched)
  */
@@ -98,7 +120,22 @@ function ensureReviewGateHook(dir) {
 
   const hooks = isObject(parsed.hooks) ? parsed.hooks : {}
   const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
-  if (alreadyRegistered(preToolUse)) return { changed: false, reason: 'present' }
+
+  // Registered already — but possibly under a path that no longer exists, since
+  // the script's extension changed. Rewrite the path IN PLACE rather than
+  // replacing the command: an operator who wrapped our hook, added a flag or
+  // changed the interpreter has registered it their way, and the thing that
+  // moved is the file, not their command. Adding a fresh entry beside theirs
+  // would run the gate twice and read as a bug in the gate; leaving the old one
+  // alone would aim the harness at a file this same upgrade retires.
+  const registered = registeredHooks(preToolUse)
+  if (registered.length) {
+    const stale = registered.filter((h) => !h.command.includes(HOOK_SCRIPT))
+    if (!stale.length) return { changed: false, reason: 'present' }
+    for (const h of stale) h.command = h.command.replace(HOOK_SCRIPT_RE, HOOK_SCRIPT)
+    writeSettings(file, parsed)
+    return { changed: true, reason: 'migrated' }
+  }
 
   writeSettings(file, {
     ...parsed,
@@ -110,8 +147,11 @@ function ensureReviewGateHook(dir) {
 module.exports = {
   ensureReviewGateHook,
   alreadyRegistered,
+  registeredHooks,
   hookEntry,
   settingsPath,
+  HOOK_STEM,
   HOOK_SCRIPT,
+  HOOK_SCRIPT_RE,
   HOOK_COMMAND,
 }

package/src/env/review.js

@@ -230,8 +230,11 @@ function resolveReader(config, env = {}) {
  * `fellBack` records that `branch` was reached because the working tree was
  * clean, not because the caller asked for it — see the fallback in
  * `specEnvReview` (`cli.js`).
+ *
+ * `buttons` is the button set the page renders — see `BUTTON_SETS`. It is the
+ * caller's declaration about the work, not a reading of the gate.
  */
-function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false }) {
+function collectReview({ spec, git, mode = 'working', ref, base = null, now, notes = null, gate = null, fellBack = false, buttons = null }) {
   const files = []
   for (const f of trackedFiles(git, ref)) {
     const { patch, whole } = patchFor(git, ref, f, false)
@@ -301,6 +304,10 @@ function collectReview({ spec, git, mode = 'working', ref, base = null, now, not
     // Same rule again: a gate that was never armed and never skipped adds no
     // key at all.
     ...(gateForPage(gate) ? { gate: gateForPage(gate) } : {}),
+    // THE DEFAULT ADDS NO KEY, so a caller that did not ask for a button set —
+    // and a caller that asked for the default by name — renders the payload it
+    // rendered before this existed. Opting in is the only thing that shows.
+    ...(buttons && buttons !== DEFAULT_BUTTON_SET ? { buttons } : {}),
     // WHICH ENGINE DREW THIS PAGE. The render is always current — the git reads
     // happen per request — so a page rendered by a stale process looks entirely
     // right: the counts move, `generatedAt` moves, the diff is correct. Only the
@@ -399,16 +406,46 @@ const NOTES_VERSION = 1
  * `discuss` is the default because it is the behaviour that existed before any
  * verdict did. So a blob from an older page, or one a reader sent without
  * choosing, keeps doing exactly what it always did.
+ *
+ * `continue` is the mid-run verdict: *I have read it, carry on*. It names an
+ * action, which is what separates it from the `none` verdict that was removed —
+ * `none` recorded itself and did nothing, while this one resumes the run. What
+ * it does NOT do is commit, so it is deliberately absent from `COMMITTING`
+ * below and is therefore structurally incapable of clearing an armed gate: a
+ * phase that ended still owes a committing verdict or a recorded skip.
  */
-const VERDICTS = ['commit', 'commit-continue', 'changes', 'discuss']
+const VERDICTS = ['commit', 'commit-continue', 'continue', 'changes', 'discuss']
 const DEFAULT_VERDICT = 'discuss'
 
 // The verdicts that COMMIT, and are therefore blocked by an open comment. One
-// list, so a fourth verdict cannot become a way around the single refusal this
+// list, so a fifth verdict cannot become a way around the single refusal this
 // engine makes — adding a committing verdict means adding it here, and the
 // block follows for free.
+//
+// `continue` IS DELIBERATELY NOT HERE, and that omission is the whole of
+// decision 2: waiting is what any offer does, while arming asserts an
+// obligation that outlives the turn. A mid-run reader saying "carry on" has
+// answered the offer in front of them and nothing else, so the gate a finished
+// phase armed must survive it untouched.
 const COMMITTING = ['commit', 'commit-continue']
 
+/**
+ * Which set of buttons a rendered page shows.
+ *
+ * DECLARED BY THE CALLER, NEVER DERIVED FROM THE GATE. Deriving it — mid-run
+ * iff the gate is unarmed — is tidier and wrong: a project running
+ * `review.required: false` never arms at all, so every one of its pages would
+ * lose the committing buttons and the reader could never commit from the page.
+ * The caller knows whether the work it just rendered is finished; the gate only
+ * knows whether this project opted into gating.
+ *
+ * `committing` is the default, so a caller that says nothing keeps today's page
+ * exactly — the key is left off the payload entirely rather than written out as
+ * the default, so an unchanged caller renders an unchanged page.
+ */
+const BUTTON_SETS = ['committing', 'midrun']
+const DEFAULT_BUTTON_SET = 'committing'
+
 /**
  * What an older sidecar's `approve` means now. Pure.
  *
@@ -1465,6 +1502,8 @@ module.exports = {
   NOTES_VERSION,
   VERDICTS,
   COMMITTING,
+  BUTTON_SETS,
+  DEFAULT_BUTTON_SET,
   readVerdict,
   DEFAULT_VERDICT,
   DELETED_HASH,

package/src/init.js

@@ -39,14 +39,23 @@ function listCommands() {
   }
 }
 
-// Hook scripts shipped as `assets/hooks/*.js`, installed to `.claude/hooks/`.
-// Discovered from the bundled tree like everything else, so a distribution
-// installs precisely what it ships and a hook can be retired by deleting it.
+// Hook scripts shipped as `assets/hooks/*.cjs` (or `*.mjs`), installed to
+// `.claude/hooks/`. Discovered from the bundled tree like everything else, so a
+// distribution installs precisely what it ships and a hook can be retired by
+// deleting it.
+//
+// A BARE `.js` IS DELIBERATELY NOT DISCOVERED. These files are copied into the
+// TARGET project, where that project's `package.json` — the one file skitterspec
+// does not control — decides how node parses a `.js`. Shipping CommonJS as `.js`
+// crashed the review-gate hook in every `"type": "module"` project, on every
+// Bash tool call. The extension is the only thing that settles it at the file,
+// so both accepted forms pin it; `env-review-hook.test.js` asserts the rule over
+// the whole directory rather than over this filter.
 function listHooks() {
   try {
     return fs
       .readdirSync(path.join(ASSETS, 'hooks'))
-      .filter((f) => f.endsWith('.js'))
+      .filter((f) => f.endsWith('.cjs') || f.endsWith('.mjs'))
       .sort()
   } catch {
     return [] // a distribution may ship no hooks
@@ -412,6 +421,12 @@ function registerReviewGateHook(dir) {
     report.created.push(label)
   } else if (res.reason === 'added') {
     report.updated.push(label)
+  } else if (res.reason === 'migrated') {
+    // A WRITE, so it may not fall through to `skipped`. It was doing exactly
+    // that: rewriting the registered path and then reporting "already
+    // registered" — a run that acts and says it did not, which is the shape of
+    // the bug this whole change exists to fix.
+    report.updated.push('.claude/settings.json (review-gate hook repointed at the renamed script)')
   } else {
     report.skipped.push('.claude/settings.json (review-gate hook already registered)')
   }
@@ -728,6 +743,15 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
   installFolders(dir)
   removeRetiredFiles(dir)
   pruneRetiredManaged(dir, manifest)
+  // The hook SCRIPT arrives above, as one more managed target; registering it is
+  // a separate write to a file we do not manage, so it has to be asked for here.
+  // It is easy to read this as duplication of `installHooks()` and delete it —
+  // it is not. `installHooks()` is unreachable from this path, and the two
+  // halves being in different functions is exactly how they drifted apart once:
+  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
+  // project, while reporting a file created. `init-review-gate-hook.test.js`
+  // asserts over the entry points rather than over this call.
+  registerReviewGateHook(dir)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
   printReport(dir, 'resync', { diff })