@skitterbyte/skitterspec 19.0.0 → 20.0.0

package/assets/rules/spec-reports.md

@@ -69,15 +69,66 @@ where it buried the rows it was meant to sit beside. A missing destination reads
 as a rule that does not fit the work, and a rule that does not fit gets ignored.
 So: **if it is worth telling the reader, it is a row.**
 **If it is not a row, it is not worth telling them.**
-`Snags` is the row most of that content belongs in.
+`Notes` is the row most of that content belongs in.
 
-**One control may follow the block: a picker.** Where the run ends in a choice
-the reader must make, the options may be offered after the table. That is not
-an exception squeezed into the rule — the ban exists because *prose* after the
-block competes with it for the reader's attention and loses them the rows. A
-picker does not compete: it is the `Next` row made actionable, in the place the
-reader's eye already finishes. Prose after the block stays banned, and adding a
-sentence alongside the picker is the same violation wearing a control's clothes.
+**Two controls may follow the block, and nothing else ever.** The ban exists
+because *prose* after the block competes with it for the reader's attention and
+loses them the rows. A control does not compete: it is a row made actionable, in
+the place the reader's eye already finishes. Prose after either of them is the
+same violation wearing a control's clothes.
+
+**The first is a picker.** Where the run ends in a choice the reader must make,
+the options may be offered after the table.
+
+**The second is the review call-to-action**, and only where the run is actually
+**waiting** on a verdict. It is a banner, not a sentence:
+
+---
+
+## ⏸ Review ready — 7 files, +212 −18
+
+**[Open the page](http://…)** · I'm holding here until you send a verdict.
+
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+
+---
+
+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:
+
+**[Open the page](https://…)** · press a verdict, then type `/spec-reviewed` — I cannot see it until you do.
+
+**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
+asks the reader to know which door the run is standing behind, and they cannot:
+it was done, and a verdict was pressed on the published page three times while
+each one sat unread under a line claiming the run was waiting. Two links is not
+a convenience with a caveat; it is the caveat existing at all.
+
+**This is not the old failure returning**, and the difference is the whole
+justification. The offer used to be two quoted lines in the tail of a long
+report, addressed to nobody, under a closing line that told the reader to move
+on — and it was never once taken. It was moved into a labelled row to make it
+findable, and that worked. What changed since is that the run now *waits*: the
+reader is not being offered something optional, they are being told the work has
+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*.
 
 **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
@@ -130,11 +181,11 @@ behind it — say nothing rather than reporting that there was nothing to report
 | `Cause` | The root cause, for work that diagnosed one. |
 | `Built` | What the run produced — the code, the edits, the spec written. |
 | `Tests` | The result and the command that produced it. |
-| `Snags` | What this run hit and handled — one short paragraph. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
+| `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
 | `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. |
+| `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. |
 | `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. |
 
@@ -152,10 +203,11 @@ is how that verdict stops meaning anything. It is still reported rather than
 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.** 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. The offer does not need the final row once it has a label column to
-be found by.
+**`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
+recreate that split with the two halves further apart than ever.
 
 ## The four verdicts
 

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

@@ -52,14 +52,20 @@ A review comes back to you one of two ways, and **both are ordinary**:
 Either way, **this is not a request to render anything**: it is a review coming
 back, and these steps replace §3–§5 below.
 
-0. **Never claim a pass you were not asked to claim.**
+0. **Never claim a pass you were not asked to claim.** And never go looking
+   for one.
 
-   This is the whole security property and there is no second one. A device that
-   reaches the page can POST all day; what it cannot reach is
-   **this conversation**. So a pass it queues sits in the holding area forever —
-   unless
-   you go and fetch it, at which point the rogue pass lands in the operator's
-   review and nothing anywhere noticed.
+   A device that reaches the page can POST all day. What decides whether one of
+   those passes reaches the operator's review is this rule, and — since the wait
+   in §4b — two mechanical facts beside it: the **serve token**, 48 unguessable
+   bits minted per server, which decides who can POST at all; and the wait
+   **window**, which decides which pass a watch may claim. There is exactly one
+   way a pass is taken without a person naming it, `--claim-since`, it is
+   described in §4b, and it acts on nothing unless precisely one pass arrived
+   while this session was waiting for it.
+
+   Everything else here is unchanged. A pass that was already sitting there when
+   you arrived is never yours to take.
 
    **Do not read the code out of `.spec-env/reviews/<spec>.pending.json`.** The
    store is a file you can open, so nothing stops you; that is precisely why the
@@ -342,6 +348,17 @@ is no. The page is free to produce and changes nothing. The same goes for the
 marks: a spec with unread files or open comments is an ordinary spec, and
 nothing here may start counting them.
 
+**And this skill never arms the gate.** Arming is `/spec-next`'s, at the one
+moment that means something: a phase ended. Rendering mid-phase — the common
+case this skill exists for — must not create an obligation, because then
+looking at your own work halfway through would owe you a verdict on it. Reading
+is free; ending a phase is what is answerable.
+
+An **already-armed** gate is a different matter, and it is not this skill's to
+enforce either: `/spec-next` §2 is where that refusal lives. Here it is only
+context — the render says a verdict is owed, and this skill's whole job is to
+help someone give one.
+
 ## 4. Render the page — or serve it
 
 ```
@@ -422,6 +439,63 @@ 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
+
+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
+types `/spec-reviewed`, so the review and the work carrying on are two separate
+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.
+
+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.
+3. **On waking, let the engine choose:**
+
+   ```
+   skitterspec spec-env review <spec> --claim-since <timestamp> --json
+   ```
+
+   Three answers, and only one of them acts. One pass in the window — that is
+   the pass, claimed and merged exactly as `--claim` would. **None** — ordinary;
+   the file changed for some other reason, so say nothing and wait again or
+   stop. **Two or more** — it refuses and names the count, never the codes; that
+   is §2 step 0's two-passes case, so offer them from the render and ask.
+4. **Route on the verdict** through §2 step 2 onward. A claim is a delivery
+   mechanism; nothing downstream may behave differently because a watch woke
+   you rather than a person typing.
+
+**What holds this up.** Not "the page cannot reach the conversation" — after
+this step it can, deliberately. Two things replace it. The **serve token** is
+48 bits of `crypto` randomness in the URL path, minted per server, and it
+decides who can POST at all. The **window** decides which pass is yours: a pass
+sitting there before you started waiting is never swept up, which is precisely
+the stranger's pass the old rule was written about, and two arrivals refuse
+rather than pick. What is left of the old rule is unchanged and still absolute —
+outside this window, a pass is claimed because a person named it.
+
+**The wait covers the SERVED page and nothing else.** It watches the engine's
+local store, which is where a served page POSTs. A **published** page writes to
+the artifact's own store instead, and no watch of any kind reaches that — so a
+verdict pressed there is invisible until someone asks for it. Never start a
+wait and then hand over a published link under it: that reads as a promise to
+notice, and it was made three times in a row while three verdicts sat unread.
+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
+enforcement that makes a named claim a person's decision.
+
 ## 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
@@ -505,6 +579,46 @@ The engine knows nothing about publishing and cannot do it. It writes a file and
 reads a URL back as an opaque string; everything about what that string means
 lives here.
 
+### Publish it so the buttons still work
+
+A published page is the answer for a reader **no local server can reach** — a
+phone on mobile data, anyone away from the LAN the engine serves on. It is also
+the one surface where the verdict buttons have nowhere to POST: the page's own
+URL is on claude.ai, so a POST fails and the reader gets "could not reach the
+server" after pressing a verdict they meant.
+
+So **publish it with a store**, and the page uses it:
+
+- Declare `capabilities: {db: {}}`. The page checks for `window.claude.use` and
+  writes the pass into the artifact's own `passes` collection instead of
+  POSTing. Nothing else about it changes — same marks, same verdicts, same
+  refusal to commit over an open comment.
+- **Do not declare `user`.** The pass is not per-viewer private state, a shared
+  collection is what it wants, and a declaration nothing uses is a grant asked
+  for nothing.
+- **Same file path every time**, so a redeploy reuses the URL. That is what
+  answers the clear-down worry: one page per spec, replaced at each render,
+  rather than an artifact per phase accumulating in the gallery.
+- **Send a push notification with the URL** when you publish. The reader is by
+  definition somewhere else — that is why it was published.
+
+### Taking a stored pass back
+
+A pass in the store is claimed the same way in spirit and a different way in
+mechanism, because the engine cannot see it:
+
+1. Read the `passes` collection with the Artifact tool's `read_db`.
+2. **Apply step 0 unchanged.** One waiting pass, offered by what it says and
+   when it was sent; two is a refusal to guess. Nothing here is automatic —
+   there is no wait window on this transport, because nothing pushes from the
+   store to this conversation.
+3. Write the pass's `blob` to a scratch file **verbatim** and merge it with
+   `spec-env review <spec> --notes <file>`. It rejoins the ordinary path at §2
+   step 1, so the verdict is judged and routed exactly as any other.
+4. **Delete the document** with `write_db` once it is merged. A claim consumes:
+   a pass left in the store is claimable twice, which is the one property the
+   six-digit code has always had and this transport must not lose.
+
 ## 7. Report
 
 End with the block defined in `.claude/rules/spec-reports.md`. That file carries
@@ -520,7 +634,7 @@ the shape; this section carries only what is specific here.
 - `⏸` — the spec has no worktree. Say that plainly: a spec that has not been
   started has nothing to diff, which is an ordinary state and not an error.
 
-**Fields:** `Built` · `Tests` · `Snags` · `Review` · `Follow-ups` · `Next`
+**Fields:** `Built` · `Tests` · `Notes` · `Review` · `Follow-ups` · `Next`
 
 ## 7a. End in a picker
 

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

@@ -105,6 +105,28 @@ 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.
+
+**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,115 @@ 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.
 
+**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 ready — <N> files, +<a> −<d>
+
+**[Open the page](<the `open:` URL>)** · I'm holding here until you send a verdict.
+
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+
+**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.
+
+---
+
+**Where you are not waiting, it stays the `Review` row** — 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.
+**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.
+
+**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
+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**:
 
-**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 <spec> --claim-since <the timestamp> --json
+   ```
 
-**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.
+   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, 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.
+
+**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 +406,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 +432,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 +441,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 +490,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": "20.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",