@skitterbyte/skitterspec 20.0.0 → 22.0.0

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,53 +224,67 @@ 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.
-
-**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.
+**Then arm the gate**, so the fix now owes a verdict:
 
+```
+skitterspec spec-env review arm <spec>
+```
 
-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.
+**Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
+than reading a second copy here: note the moment, run
+`skitterspec spec-env review wait <spec> --since <that moment>` in the
+background, end your turn, and let `--claim-since` pick the one pass that
+arrived inside the window. **Do not compose a watcher**, and do not give the
+wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
+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 engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three — rather than the bare `page:` path: a path is not clickable in any
+terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
+line with it where the engine printed one, and nothing where it did not.
+`.claude/rules/spec-reports.md` carries the shape, including why a rigid
+contract took that line.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always an ask. A
   `file://` link is no use on a phone, and saying so **is** the ask —
   `/spec-diff` §6 owns how.
-**Follow the `reader:` line the engine printed — do not sniff for it.** It
-answers where the person reading this is sitting, and the offer changes with it:
-
-- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
-  unknown is the ordinary state of a local machine, and a warning there is an
-  accusation against a healthy session.
-- **`local`** — the `file://` URL.
-- **`remote`** — the engine has already stood its local server up and put a URL
-  the reader can open on `open:`. So there is **nothing special to say**: relay
-  that line like any other. Any `also:` lines under it are the other addresses
-  this machine has, offered because the best-guess one can be wrong — pass them
-  on rather than editing them out.
-
-**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
-not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
-and in `--json`, and a second implementation here could not be tested and would
-drift.
+**The `reader:` line no longer decides anything here, and that is the point.**
+It is still printed, and it is still the only place that question is answered —
+but the offer does not change with it, because the stack lists every tier
+whatever it says. Three reader states used to mean three different offers, and
+that branching is exactly what produced a `file://` page on a session detected
+`unknown`, a LAN URL for a phone off the network, and an address that changed
+underneath a reader when detection flipped mid-session.
+
+So: **relay all three tier lines, every time.** Any `also:` lines sit under
+`network` — the other addresses this machine has, offered because the
+best-guess one can be wrong — so pass them on rather than editing them out.
+
+**Never read an environment variable to decide anything about the offer** — not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
+here for a detection to decide, and a second implementation of one could not be
+tested and would drift.
 
 **Serving is the engine's to do; publishing is never.** A `remote` reader
 authorises a local server — one process, ended by one flag, leaving nothing
@@ -307,9 +321,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

@@ -1,6 +1,6 @@
 ---
 name: spec-diff
-description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, or the pasted JSON.
+description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
 ---
 
 # /spec-diff — see the phase before you commit it
@@ -41,13 +41,19 @@ sole candidate or prints the candidates.
 The page has marks on it — `✓ accept` per file, notes against a line or a whole
 file, answers to the checks a written review asked — and it
 **ends in a decision**: `✓ Approve`, `↺ Request changes` or `… Discuss first`.
-A review comes back to you one of two ways, and **both are ordinary**:
+A review comes back to you one of three ways, and **all three are ordinary**:
 
 - **A six-digit code** — `418207`, on its own. A *served* page hands its pass
   straight to the engine, which holds it until someone reads the code out. This
   is the usual way on a phone.
-- **A pasted JSON blob** — a `file://` page has no server to talk to, so it
-  copies. Not legacy: it is the whole story for a local reader.
+- **A verdict word** — `commit`, `commit-continue`, `continue`, `changes` or
+  `discuss`. A `file://` page cannot send anything, so where the reader marked
+  nothing it copies a command carrying the conclusion on its own. Send it with
+  `skitterspec spec-env review <spec> --verdict <word>`; it joins the same merge
+  a claimed pass does, so everything below is unchanged.
+- **A pasted JSON blob** — the same `file://` page, once the reader has marked
+  something up: accepts and notes do not fit on a command line, so the whole
+  pass travels. Not legacy: it is the whole story for a local reader.
 
 Either way, **this is not a request to render anything**: it is a review coming
 back, and these steps replace §3–§5 below.
@@ -151,6 +157,10 @@ back, and these steps replace §3–§5 below.
    absent verdict has always meant "report it and wait" — which is why that is
    what it still means.
 
+   **A pass may carry an `action:` instead**, and then none of the above
+   applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
+   carrying both, so there is never a choice to make between them.
+
 3. **Say what you read, then ask what's up.** Report the accepted count, then
    each open comment as `file:line — note`, then the files you would touch.
    **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -335,6 +345,69 @@ it — and the paste was the one place it broke. The *work* either authorises is
 ordinary phase-sized cost, and step 3 is where the operator decides whether to
 spend it.
 
+## 2b. An action changes something, then hands the page back
+
+Only on a pass carrying an **action**. Three of them, and
+**all three end the same way**:
+do the thing, re-render (§4), and wait again (§4b) — because the reader
+still has a decision in front of them and has not made it.
+
+| Action | Do | Then |
+|--------|----|------|
+| `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
+| `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
+| `allow-remote` | `skitterspec spec-env review allow remote --set on` | re-render, wait again |
+
+**THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
+live is about the diff on screen; handing the whole instance back to `main` is a
+workspace decision with nothing to do with this review. The `live:` line names
+`/spec-live main` for it — a command the operator types, which is also why no
+skill runs it.
+
+**AN ACTION IS NOT A VERDICT, and the gate is untouched by all three.** A phase
+that ended armed the gate, and it is discharged by a committing verdict or a
+recorded skip and by nothing else — so after any of these the phase still owes
+an answer, and that is exactly why the run waits again rather than finishing.
+The engine enforces this rather than trusting it: `ACTIONS` is disjoint from
+`VERDICTS` and `COMMITTING`, so nothing that routes on a verdict can see one.
+
+**`live-on` commits first, and the commit is a precondition rather than an answer.**
+`live take` refuses a dirty worktree, and even without that guard
+uncommitted work stays behind in the worktree — so what went live would be the
+*previous* commit while the page claimed to be showing this one. Hand off to
+`review.commitWith` exactly as §2a does (do not restate its rules here), then
+take the instance. The reader has not approved anything by pressing it.
+
+**It re-renders `--branch` afterwards**, because the working view is now empty:
+the commit just happened, and the branch range is what still answers "what am I
+looking at". §4's clean-tree fallback reaches the same place on its own, so
+passing `--branch` is belt and braces rather than a separate rule.
+
+**A mid-phase page does not get the commit.** Where the render took
+`--buttons midrun`, the work is half a phase — committing it to look at it
+running splits one phase across two commits and leaves a mess nobody asked for.
+Say the phase needs to land first, re-render, and wait.
+
+**Relay every refusal, and work around none of them.** `live take` refuses a
+workbench another spec holds, a hotfix, a stateful spec, a branch touching
+migrations, and a tree with no dev server listening. Each refusal names its own
+way out. **Never park another spec's live session** to make room — that is
+someone else's work, and freeing it is their decision. Re-render and wait, so
+the reader can choose something else.
+
+**`allow` writes a committed file, and that is worth a sentence.** It edits
+`specs/.core/env.config.json` in the **primary checkout**, so it changes
+behaviour for everyone who pulls and leaves that tree dirty — unlike the live
+actions, which move a branch and write a gitignored receipt. The engine prints
+the absolute path and whose tree it dirtied; relay that rather than letting a
+shared setting change land silently. And it is **enable-only**: there is no
+action that turns a tier off, because turning `network` off from a page reached
+over the network kills the page doing the turning.
+
+**`allow remote` permits publishing. It does not publish.** Publishing stays an
+explicit ask in every case (§6), because the page it leaves behind is one this
+tooling cannot remove.
+
 ## 3. Gate it on nothing
 
 **This skill has no preconditions and must never grow one.** Not tests passing,
@@ -367,15 +440,17 @@ skitterspec spec-env review <spec> --branch     # everything since the base bran
 skitterspec spec-env review serve               # every spec, on localhost
 ```
 
-**The engine handles the switch.** A file when the reader is at this machine, a
-served URL when they are not: on a `remote` reader it stands its own server up
-and puts a URL the reader can open on the `open:` line. Both are free and neither
-publishes anything. You are not choosing between them; you are relaying whichever
-one the engine printed.
+**There is no switch left to handle.** The engine serves and prints a **stack** —
+one line per tier, `local`, `network`, `remote`, each either a URL or the one
+command that turns it on. All of it is free and none of it publishes anything.
+You are not choosing between them; you are relaying every line it printed.
+`.claude/rules/spec-reports.md` carries the shape and why.
 
-The operator who does not want a LAN listener started for them sets
-`review.serveOnRemote: false` in `env.config.json`, and the `file://` link with
-its *will not open where you are reading* marker comes back.
+The operator who does not want a LAN listener sets `review.allowNetwork: false`
+in `env.config.json` — `network` then reads `off` with the command that turns it
+back on, and `local` is the loopback page. Turning serving off entirely is
+`review.serve: "never"`, and then `local` is the `file://` page, which says on
+its own line that it cannot send a verdict.
 
 `serve` renders **per request**, so nothing it shows can be stale, and it lists
 every spec with a worktree rather than one. `--host 0.0.0.0` binds beyond
@@ -401,23 +476,56 @@ 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.
 
-**On `--page-only`, stop here** and report the path.
+**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`.
 
-## 4a. Read the `reader:` line — never sniff for it yourself
+**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.
 
-`spec-env review` reports where it believes the reader is, and
-**that is the only place this question is answered.** Three states:
+`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.
 
-| `reader:` | What to offer |
-|-----------|---------------|
-| absent (`unknown`) | the `file://` URL, exactly as always. **Do not warn** — unknown is the ordinary state of a local machine |
-| `local` | the `file://` URL |
-| `remote` | the `open:` line as printed — the engine already served it. Pass on any `also:` lines too |
+**On `--page-only`, stop here** and report the path.
 
-**Never read an environment variable to decide this.** Not `SSH_CONNECTION`, not
-`CLAUDE_CODE_*`, not a tty check — the engine already did it, reports the answer
-on that line and in `--json`, and a second implementation here could not be
-tested and would drift from the first. The ranking and the traps
+## 4a. Relay the stack — every tier, never one you picked
+
+`spec-env review` prints one line per tier and `--json` carries the same thing
+as `tiers`. **Relay all of them, in that order**, whatever the `reader:` line
+says:
+
+| Tier | Carries |
+|------|---------|
+| `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
+| `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
+| `remote` | the published URL and *a verdict here needs `/spec-reviewed`* — or `off` with the command that turns it on |
+
+**The `reader:` line decides nothing here any more.** It is still printed and
+still the only place that question is answered, but the offer no longer branches
+on it — because branching on it is what produced a `file://` page for a session
+detected `unknown`, a LAN URL for a phone off the network, and an address that
+changed underneath a reader mid-session. A tier that is off keeps its line, so a
+reader who has left the house can see the surface exists and ask for it.
+
+**Never read an environment variable to decide anything about the offer.** Not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check — there is nothing left
+for a detection to decide, and a second implementation of one could not be
+tested and would drift. The ranking and the traps
 (`CLAUDE_CODE_ENTRYPOINT` describes the *process*, not the reader; stdin is never
 a tty under Claude Code) live in `review.js` beside the code, which is where they
 belong.
@@ -436,10 +544,11 @@ answer left.
 
 `review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
 operator settle where they are reading, and an explicit value is believed without
-sniffing. `review.serveOnRemote` (default `true`) settles whether the engine may
-act on it.
+sniffing. What the engine may *do* is settled by the tier settings instead —
+`review.serve` (`always` · `never`), `review.allowNetwork` and
+`review.allowRemote` — not by the reader.
 
-## 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,16 +557,45 @@ 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; the engine's own wait returns when
+  it lands, and the steps below run it.
+- **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.
-2. **Watch** `.spec-env/reviews/<spec>.pending.json` in the primary checkout,
-   and **end the turn**. Not a poll and not a held-open turn: the operator has
-   their terminal back, and the session costs nothing while they read.
+2. **Run the engine's wait in the background, and end the turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <timestamp>
+   ```
+
+   **Never a watcher of your own, and never a timeout.** It lasts as long as the
+   session, because a reader who walks away from a diff is the normal case — and
+   a loop composed here would be proven by nothing, which is how one written as
+   `[ "$x" \> "$y" ]` spun for five minutes in zsh and looked exactly like
+   patience. `/spec-next` §5 carries the full account.
+
+   Not a poll and not a held-open turn: the operator has their terminal back,
+   and the session costs nothing while they read.
 3. **On waking, let the engine choose:**
 
    ```
@@ -492,10 +630,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
@@ -662,8 +806,8 @@ consumed rather than stored.
 purpose; someone who forgot they had voted has not, and only the report tells
 them apart.
 
-`Review` carries the files and `+`/`−`, the page's `open:` line, and the
-published URL when there is one. Where the page holds a review pass, it also
+`Review` carries the files and `+`/`−`, and the tier stack — labelled, run
+together with `·` because a row is one cell. Where the page holds a review pass, it also
 carries the three totals — files accepted, comments open, comments answered.
 `--json` reports those under `notes.totals`; read that, never the diff.
 

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,53 +246,61 @@ 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.
-
-**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.
+**Then arm the gate**, so the fix now owes a verdict:
 
+```
+skitterspec spec-env review arm <spec>
+```
 
-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.
+**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 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.
+
+**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 engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three — rather than the bare `page:` path: a path is not clickable in any
+terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
+line with it where the engine printed one, and nothing where it did not.
+`.claude/rules/spec-reports.md` carries the shape, including why a rigid
+contract took that line.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always an ask. A
   `file://` link is no use on a phone, and saying so **is** the ask —
   `/spec-diff` §6 owns how.
-**Follow the `reader:` line the engine printed — do not sniff for it.** It
-answers where the person reading this is sitting, and the offer changes with it:
-
-- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
-  unknown is the ordinary state of a local machine, and a warning there is an
-  accusation against a healthy session.
-- **`local`** — the `file://` URL.
-- **`remote`** — the engine has already stood its local server up and put a URL
-  the reader can open on `open:`. So there is **nothing special to say**: relay
-  that line like any other. Any `also:` lines under it are the other addresses
-  this machine has, offered because the best-guess one can be wrong — pass them
-  on rather than editing them out.
-
-**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
-not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
-and in `--json`, and a second implementation here could not be tested and would
-drift.
+**The `reader:` line no longer decides anything here, and that is the point.**
+It is still printed, and it is still the only place that question is answered —
+but the offer does not change with it, because the stack lists every tier
+whatever it says. Three reader states used to mean three different offers, and
+that branching is exactly what produced a `file://` page on a session detected
+`unknown`, a LAN URL for a phone off the network, and an address that changed
+underneath a reader when detection flipped mid-session.
+
+So: **relay all three tier lines, every time.** Any `also:` lines sit under
+`network` — the other addresses this machine has, offered because the
+best-guess one can be wrong — so pass them on rather than editing them out.
+
+**Never read an environment variable to decide anything about the offer** — not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
+here for a detection to decide, and a second implementation of one could not be
+tested and would drift.
 
 **Serving is the engine's to do; publishing is never.** A `remote` reader
 authorises a local server — one process, ended by one flag, leaving nothing
@@ -335,10 +343,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