@skitterbyte/skitterspec 19.0.0 → 21.0.0

package/assets/rules/spec-planning.md

@@ -29,11 +29,17 @@ rather than invoking it.
 
 `/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
 convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
-review pass is never claimed unasked. A pass can be POSTed by anything that
-reaches the page; what it cannot reach is the conversation. Because the model
-cannot invoke this skill, a pass is only ever picked up because a person typed
-the command, and typing it **is** the human signal. Prose alone did not hold
-that line once already.
+review pass is never claimed unasked. Because the model cannot invoke this
+skill, a pass named this way is only ever picked up because a person typed the
+command, and typing it **is** the human signal. Prose alone did not hold that
+line once already.
+
+It is **no longer the only way in**, and the difference is worth stating
+precisely. A phase that ends now *waits* on its page, and a pass arriving inside
+that wait is claimed by the engine (`--claim-since`) without anyone typing
+anything — scoped to the window, refusing when two arrive. `/spec-reviewed` is
+what answers everything outside it: a pass sent when nobody was waiting, two
+passes to choose between, and every harness with no file-watch to wait with.
 
 `/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
 real judgment (green tests before a land; an MCP fetch and a team-key check; ten
@@ -174,13 +180,24 @@ paste, exactly as before. The clipboard path is **not legacy**: it is the whole
 story for a local reader.
 
 The code is **not a secret** — it is printed on the page, and it cannot be a
-gate against Claude either, because the store is a file Claude can read. What
-actually holds is narrower and stronger:
-**a device that reaches your page cannot reach your conversation.**
-So a pass it queues sits in the holding area
-forever, and the rule that keeps it there is that
-**Claude never claims a pass it was not asked to** — stated in `/spec-diff` step
-0, because nothing enforces it.
+gate against Claude either, because the store is a file Claude can read.
+
+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 you typed `/spec-reviewed`. It is no longer true, deliberately —
+a phase that ends **waits** for its verdict, so the button you press on the page
+is what carries the work on. What replaced the guard is two mechanisms and one
+rule. The **serve token** — 48 bits of randomness in the URL path, minted per
+server — decides who can POST at all. The **wait window** decides which pass may
+be claimed without you naming it: the engine's `--claim-since` takes the one
+pass that arrived *while this session was waiting*, acts on nothing when none
+did, and refuses to choose when two did. And outside that window the rule stands
+unchanged and absolute: **Claude never claims a pass it was not asked to**
+(`/spec-diff` step 0, because nothing enforces it).
+
+What you give up is real and worth naming: the page can now act. What you get is
+the loop closing without anyone remembering a command — which is the failure the
+old design traded it for.
 
 What the code *does* is let you **tell two passes apart** — it is an address,
 never a password. One waiting pass is claimed and acted on the moment you type
@@ -218,6 +235,41 @@ never ticked block nothing — an unticked file is something you said nothing
 about, and requiring every one of them would be the tally this design exists to
 avoid.
 
+**The gate — a phase that ended owes an answer.** That is the second refusal,
+and it is a different kind: not a count, and not about the marks at all.
+`/spec-next` **arms** it when a phase ends and renders its page, and exactly two
+things clear it — a **committing verdict**, or
+`skitterspec spec-env review skip "<reason>"`. Until one of them happens,
+`/spec-next` refuses to build the next phase and (where the hook is installed)
+`git commit` refuses in that worktree. `skitterspec spec-env review gate
+[--check] [--json]` is what both ask.
+
+**The hook is the half that cannot be talked past.** `skitterspec init` and
+`skitterspec update` install `.claude/hooks/review-gate.cjs` and register it in
+the project's committed `.claude/settings.json`, so a `git commit` is refused by
+the harness rather than by prose — which is what covers a bare `git commit`, a chained command, and
+skittership's own `/commit` without skitterspec ever editing it. It decides
+nothing itself: it hands the command line to
+`spec-env review gate --check --for-command` and turns one exit status into an
+answer. It refuses only where the commit is running
+**inside that spec's own worktree** — a commit on the base branch, or in
+another spec's tree, is not this obligation's business — and it fails **open** on everything else: no engine, an
+unreadable payload, a crash, a timeout, a repo with no isolation.
+
+Three things keep it a push rather than a wall. It is armed
+**only by a phase ending**, so reading your own half-finished work mid-phase
+owes nothing.
+It has an **exit that is always one command**, and one of them is
+*"I am moving on"* — with a reason, because `none: additive, nothing to revert` is a decision
+a reviewer can argue with while silence is an oversight. And it accuses
+**only on a positive signal**: an unreadable sidecar, a project that set
+`review.required: false`, a spec the engine could not resolve — every
+cannot-tell exits 0 and says nothing (`.claude/rules/negative-checks.md`).
+
+It is on by default wherever isolation is configured. That is the point: the
+push toward reading the diff is the normal path, and stepping off it is the
+thing you have to do deliberately.
+
 **The verdict names the action**, and that is why it is `commit` rather than
 `approve`: a review is the guard in front of an action, and an approval that
 only recorded itself was the one control on the page that did not describe what
@@ -249,7 +301,7 @@ its verdicts and its fields.
 | **Branch** | `spec/feat-orders` · 3 commits, clean |
 | **Built** | POST /orders handler, orders schema |
 | **Tests** | 128 passed · npm test |
-| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Review** | 7 files, +212 −18 · [open the page](file:///…) |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 

package/assets/rules/spec-reports.md

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

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

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

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

@@ -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
 
 ```
@@ -384,6 +401,31 @@ Add `--json` to get the file list, totals and the page path back as data. The
 page is written to `.spec-env/reviews/<spec>.html`, which is gitignored — it
 leaves no trace in the branch under review.
 
+**Declare the button set when the work is unfinished.** A page rendered part-way
+through a run takes `--buttons midrun`, and offers `Continue` — *I have read it,
+carry on* — in place of `Commit` and `Commit & Continue`:
+
+```
+skitterspec spec-env review <spec> --buttons midrun
+```
+
+**It is a statement about the work, never a reading of the gate.** Ask whether
+the thing you just rendered is *finished*: a phase that ended, a bug fix that is
+green, a spec about to land — committing set, which is the default, so pass
+nothing. Half a phase, a hand edit, a colleague's branch mid-flight, anything
+the operator asked to look at while it is still moving — `midrun`.
+
+**Do not derive it from whether the gate is armed.** That is tidier and wrong: a
+project running `review.required: false` never arms at all, so every one of its
+pages would lose the committing buttons and its reader could never commit from
+the page. The caller knows what it rendered; the gate only knows whether the
+project opted into gating.
+
+`Continue` is not the removed `none` verdict. `none` recorded itself and did
+nothing; `Continue` **resumes the run**, so it still names an action. What it
+cannot do is commit, or clear a gate a finished phase armed — that takes a
+committing verdict or a recorded skip.
+
 **On `--page-only`, stop here** and report the path.
 
 ## 4a. Read the `reader:` line — never sniff for it yourself
@@ -422,6 +464,87 @@ 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 — 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
+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.
+
+**The rule is `.claude/rules/spec-reports.md`'s: asking implies waiting.** If
+this render asks the reader for a verdict, it waits for one. If it is not going
+to wait, it does not ask — the report names the page and its size and stops
+there. There is no third option, and in particular there is no *ask now, notice
+later*: that is the shape that stranded two passes on one spec, where the run
+said the page was **ready** rather than that it was **waiting**.
+
+**So the question is not "can I watch a file".** It is "am I asking?" — and the
+transport only decides what carries the answer back:
+
+- **A served page** posts to the local store; a file-watch sees it, and the
+  steps below are that watch.
+- **A `file://` page** has nothing to post to, so the reader pastes the pass and
+  their next message carries it. Say you are holding and **end the turn** — that
+  is the same wait, carried by the conversation. It is not a lesser one.
+- **A published page** writes to the artifact's own store, which nothing reaches
+  from here. That is the one case where the honest sentence is *press a verdict,
+  then type `/spec-reviewed`* — see the published-page paragraph below.
+
+**Do not ask, and therefore do not wait, on a render nobody is waiting behind** —
+a bare `--page-only`, a page produced alongside other work, a pass that has
+already arrived. Those get the `Review` row, no question, and nothing is owed.
+
+1. **Note the moment**, as an ISO timestamp, before you start. That instant is
+   the entire scope of what may be claimed without a person naming it.
+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, 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
@@ -505,6 +628,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 +683,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