@skitterbyte/skitterspec 19.0.0 → 21.0.0

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,6 +105,40 @@ 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.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
+answer* is the project's policy and should reach everyone who clones it. The
+command is written with `${CLAUDE_PROJECT_DIR}`, so it holds in worktrees too.
+
+**Say it is there, once.** A hook that blocks a commit with the operator not
+knowing a hook exists reads as a broken git, so name it in the report when it is
+newly registered — and say what turns it off (`review.required: false` in
+`env.config.json`, which the hook defers to entirely).
+
+**Never fatal, and never rewritten.** A settings file that is not parseable JSON
+is reported and left exactly as it is — it is the operator's config, and
+everything else in it would be lost. A settings file that already names this
+script, however it was wrapped, is left alone rather than gaining a second copy.
+
 ## 5. CLAUDE.md
 
 Ensure a `## Spec workflow` section exists. If absent, add one with the

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

@@ -116,7 +116,7 @@ A **name argument** is accepted, but it must *match* the spec in flight — it
 narrows a re-run, it does not select a different spec. A mismatch refuses,
 naming both.
 
-## 2. Pre-flight — commit prior work
+## 2. Pre-flight — the last phase is committed, and was answered
 
 Before writing any code for this phase, get the workspace clean:
 
@@ -128,6 +128,32 @@ Before writing any code for this phase, get the workspace clean:
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
 
+- **Confirm the last phase's review was answered.** Ask the engine, never the
+  sidecar:
+
+  ```
+  skitterspec spec-env review gate <spec> --json
+  ```
+
+  `state: "armed"` means a phase ended, its page was rendered, and nobody has
+  said what they concluded. **Refuse, with the `⏸` block**, and name the three
+  ways out in the `Next` row: read the page and send a verdict, type
+  `/spec-reviewed` if one is already waiting, or
+  `skitterspec spec-env review skip "<reason>"` to move on with the reason on
+  the record.
+
+  `state: "clear"` carries on.
+  **`state: "unknown"` also carries on, in silence** — it is the project opting out, a sidecar that could not be read, or
+  a spec the engine could not resolve, and none of those is evidence that
+  anything is owed (`.claude/rules/negative-checks.md`). Do not mention it: a
+  line about a gate nobody armed is an accusation against a healthy repo.
+
+  **This refusal counts nothing.** It is not a tally of ticked boxes — those
+  still gate nothing and still are not counted. It asserts one thing: a phase
+  that ended has an answer. And the exit is always **one command**, one of them
+  being *"I am moving on"*, which is what keeps this a push rather than a wall —
+  a gate with no exit gets switched off wholesale instead of answered.
+
 ## 3. Implement the phase
 
 Identify the **first unfinished phase** from the `00-overview.md` phase index,
@@ -226,7 +252,7 @@ skitterspec spec-env resolve <spec> --assert-primary-clean
 - **"cannot tell"** — no baseline, or one from another spec. It exits 0 and
   claims nothing; say so in one line and carry on. An absence is not evidence.
 
-## 5. Render the page — then offer the review, never write it
+## 5. 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.
@@ -243,31 +269,137 @@ 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:
+
+```
+skitterspec spec-env review arm <spec> --phase <n>
+```
+
+It is idempotent within a phase, so a re-render does not restart the clock, and
+it is **never fatal**: a project that opted out, or an engine that could not
+resolve the spec, says so and the phase is still built. Nothing here counts
+anything — the gate asserts that a phase which ended has an answer, and that is
+all it asserts.
+
 **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:
+**Where you are going to wait, the offer is the banner after the block** —
+defined in `.claude/rules/spec-reports.md`, and **the `Review` row is dropped**
+so one subject lives in one place:
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+---
+
+## ⏸ Review ready — <N> files, +<a> −<d>
+
+**[Open the page](<the `open:` URL>)** · I'm holding here until you send a verdict.
 
-**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.
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
 
-**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.
+**One link, and the engine has already chosen it.** Where it served, the
+banner carries the served URL and the wait is real. Where it could not serve —
+a busy port, a machine with no network address — that is the case publishing
+exists for, and then the banner carries the published URL with what is true of
+it: *press a verdict, then type `/spec-reviewed`*, because nothing pushes from
+the artifact store into this conversation.
+
+**Never offer both.** Publishing while the server is reachable adds a second
+door the reader cannot tell apart from the first, and the wait only stands
+behind one of them — that was done, and three verdicts were pressed on the
+published page while each sat unread under a line saying I was holding. The
+published page is for the reader the server cannot reach, and for nobody
+else.
+
+---
 
-**Non-blocking, deliberately.** Do not end your turn waiting on the answer.
-Phases get chained — `/commit && /spec-next` typed as one line — and a question
-that stops the run taxes every phase to fix a problem the row already fixes.
+**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>) |
+
+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 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 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.
+
+### Then wait for the verdict, where the harness can
+
+The row is findable, but a row cannot make the continuation follow from the
+reading — and that is the gap the whole gate exists to close.
+**Where this harness can watch a file and wake the session on a change, use it.** The pass
+arrives at the engine's holding area, the watch fires, and the verdict the
+reader pressed is what carries the work on.
+
+1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
+   the whole scope of what you may claim.
+2. **Watch the pending store** for the spec —
+   `.spec-env/reviews/<spec>.pending.json` in the primary checkout — and
+   **end your turn**. Do not poll, and do not hold the turn open: the point is that
+   the reader has the terminal back while they read.
+3. **On waking, let the engine pick**:
+
+   ```
+   skitterspec spec-env review <spec> --claim-since <the timestamp> --json
+   ```
+
+   It claims the one pass that arrived inside the window, and acts on nothing
+   at all when none did (the watch can fire on a write that was not a pass) or
+   when two did (two sittings, or two people — the operator has the codes).
+4. **Route on the verdict** exactly as `/spec-diff` §2 and §4 describe. Do not
+   restate that routing here.
+
+**WHY THIS IS SAFE, AND WHAT IT COSTS.** It was once true that a device
+reaching your page could not reach your conversation, and that fact was the
+whole guard: a pass sat in the holding area until a person typed
+`/spec-reviewed`. This replaces that guard rather than weakening it by
+accident, and the replacement is two things together — **the serve token**,
+48 unguessable bits minted per server, which is what decides who can POST at
+all; and **the window**, which is what decides which pass is yours. A pass
+already waiting when the wait began is never claimed by it, which is exactly
+the stranger's pass the old rule was written about. What is genuinely given up
+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, 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
+here stops nothing that was still going to happen.
 
 Relay the **`open:`** line the engine prints, not the bare path: a path is not
 clickable in any terminal, and a page nobody can open is a page nobody reads.
@@ -296,7 +428,8 @@ 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
-behind — and authorises nothing else. Publishing leaves a page this tooling
+behind — and authorises nothing else. A reader the server CAN reach is not a
+reason to publish as well: the page they can already open is the page to name. Publishing leaves a page this tooling
 cannot remove, so it stays an ask in every case, always. If the engine could not
 serve (a busy port, a machine with no network address) it falls back to the
 `file://` URL with its marker, and that is when publishing is worth naming.
@@ -321,7 +454,7 @@ the shape; this section carries only what is specific here.
 - `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
 - `⏸` — no spec in flight, or the name given does not match the one that is.
 
-**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Snags` · `Review` ·
+**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Notes` · `Review` ·
 `Follow-ups` · `Next`
 
 ## 6a. End in a picker
@@ -330,6 +463,12 @@ The block says what happened; this is what to do about it. Offer the same four
 endings the review page carries, so a review finishes the same way wherever the
 reader is standing — the page, a pasted code, or here.
 
+**Not when you are waiting.** Where §5 set a watch and ended the turn, the
+verdict is coming from the page and the picker would be a second way to answer
+a question already asked — so the block ends on `Next`, which names the page.
+The picker is for the run that did not wait: no watch available, or a render
+the reader is expected to come back to in their own time.
+
 | Option | Does |
 |--------|------|
 | `Reviewed` | Claims the waiting pass and routes on its verdict |
@@ -373,8 +512,10 @@ top of an uncommitted one — so a `Next` that names only `/spec-next` sends the
 reader straight into that refusal. The two halves are four hundred lines apart,
 which is exactly how they drifted.
 
-**Step 5's offer is the `Review` row.** It is not a paragraph after the block,
-because nothing is after the block: the counts, the page link and the question
-go in one row, above `Follow-ups` and `Next`. Step 5 renders before the commit
-and this step is where its offer lands, so the two must not disagree about where
-it goes.
+**Step 5's offer lands in one of two shapes, and never both.** Waiting on a
+verdict → the **banner** after the block, and no `Review` row. Not waiting → the
+`Review` row, and no banner. Neither is a paragraph: the ban on prose after the
+block is untouched, and the banner is a control the contract names
+(`.claude/rules/spec-reports.md`). Step 5 renders before the commit and this
+step is where its offer lands, so the two must not disagree about which shape it
+takes.

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

@@ -37,16 +37,25 @@ of `/spec-diff` step 0's central rule:
 **never claim a pass you were not asked to claim**.
 
 That rule exists because a review pass can be POSTed by anything that reaches
-the page, and what it cannot reach is **this conversation**. So a stranger's pass
-sits in the holding area forever — unless an agent goes and fetches it, which is
-exactly what happened once: an agent found a waiting approval, read its code off
-disk, claimed it, and reported the round-trip working.
+the page. So a stranger's pass sits in the holding area — unless an agent goes
+and fetches it, which is exactly what happened once: an agent found a waiting
+approval, read its code off disk, claimed it, and reported the round-trip
+working.
 
 Prose alone did not prevent that. The harness does —
-**the model cannot invoke this skill** — so a pass is only ever picked up
-because a person typed the command. Typing it *is* the human signal. A later edit that makes this skill
-model-invocable does not make it more convenient — it removes the only thing
-standing between a stray approval and someone's repo.
+**the model cannot invoke this skill** — so a pass picked up *this way* is only
+ever picked up because a person typed the command. Typing it *is* the human
+signal. A later edit that makes this skill model-invocable does not make it more
+convenient — it removes the only thing standing between a stray approval and
+someone's repo.
+
+**There is exactly one other way in, and it is bounded rather than trusting.**
+A phase that ends waits on its page, and a pass arriving *during that wait* is
+claimed by the engine (`--claim-since`, `/spec-diff` §4b): scoped to the window,
+acting on nothing when no pass arrived, refusing when two did. A pass already
+sitting there when the wait began is never swept up by it — which is the
+stranger's pass this whole rule was written about. Everything outside that
+window still comes through here.
 
 ## 1. Resolve the spec
 
@@ -141,10 +150,17 @@ everything a decision needs, so there is nothing to go looking for, and going
 looking is the bypass step 0 forbids. The file is right there and readable; that
 is precisely why the rule is written down rather than assumed.
 
-**Nothing waiting is an ordinary answer.** Say so and stop. Do not hunt through
-other specs, and do not treat an empty holding area as a problem — a `file://`
-page copies to the clipboard instead of sending, so mention that the pass may be
-on their clipboard waiting to be pasted, and finish.
+**Check the store before concluding nothing is waiting.** Only when this spec
+has a published page (`--json` reports a `url`): a reader off the LAN sent their
+pass to the artifact's own `passes` collection rather than to the engine, so an
+empty holding area is not an empty answer yet. Read it with the Artifact tool's
+`read_db`, merge the `blob` through `--notes`, and **delete the document** —
+`/spec-diff` §6 owns the whole sequence, including that a claim consumes.
+
+**Nothing waiting in either is an ordinary answer.** Say so and stop. Do not hunt
+through other specs, and do not treat an empty holding area as a problem — a
+`file://` page copies to the clipboard instead of sending, so mention that the
+pass may be on their clipboard waiting to be pasted, and finish.
 
 ## 3. One pass waiting? Act on it
 
@@ -155,10 +171,11 @@ manufactured, because the model cannot invoke it.
 
 **The code was never an authorisation.** A later edit must not restore it as
 one. It earned its keep when the *page* pushed: the agent went looking, found
-a pass, and had to prove which one it had. That channel is gone. What stops a
-stranger's approval reaching your repo is that a device on your network can
-reach your page and cannot reach this conversation — the confirmation step
-added nothing to that, and cost a round-trip on every review.
+a pass, and had to prove which one it had. What stops a stranger's approval
+reaching your repo is not those six digits — it is that this command cannot be
+typed by anything but a person, and that the one automatic path (`--claim-since`)
+is bounded by a window a stranger's pass falls outside of. The confirmation step
+added nothing to either, and cost a round-trip on every review.
 
 So the code has exactly one job left: **telling two passes apart**. That is
 disambiguation, not a gate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "19.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",