@skitterbyte/skitterspec-linear 14.0.0 → 17.0.0

package/assets/rules/spec-planning.md

@@ -1,7 +1,7 @@
 # Spec Planning
 
 Spec-driven development is driven by ten lifecycle skills (plus the
-`/spec-connect` and `/spec-live` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
+`/spec-connect`, `/spec-live` and `/spec-remote-review` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
 
@@ -20,13 +20,24 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
 
 **Skills vs commands.** The table above lists **skills** — Claude reads them and
-exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
+exercises judgment. `/spec-connect`, `/spec-live` and `/spec-remote-review` are
+instead **slash commands**
 (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
 relays its output, so there is no judgment to apply and no model turn spent
 finding one. They are marked `disable-model-invocation`, meaning
 **only you can run them** — a skill that wants one will tell you to type it
 rather than invoking it.
 
+**`/spec-remote-review`** is the newest and the smallest: it toggles
+`review.allowRemote`, and takes `on`/`off` when you would rather say which.
+It exists because a render's `remote:` line has to name something a person can
+act on, and `skitterspec spec-env review allow remote` is not what anyone
+reconstructs from a page they are reading on a phone. Making the line
+*clickable* was considered and rejected — the only clickable thing markdown has
+is a URL, and a URL that acts when it is **fetched** is one a link previewer or
+a prefetcher fires with nobody involved. It **permits** publishing; it publishes
+nothing.
+
 `/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. Because the model cannot invoke this
@@ -244,10 +255,10 @@ things clear it — a **committing verdict**, or
 `git commit` refuses in that worktree. `skitterspec spec-env review gate
 [--check] [--json]` is what both ask.
 
-**The hook is the half that cannot be talked past.** `skitterspec init` installs
-`.claude/hooks/review-gate.js` and registers it in the project's committed
-`.claude/settings.json`, so a `git commit` is refused by the harness rather than
-by prose — which is what covers a bare `git commit`, a chained command, and
+**The hook is the half that cannot be talked past.** `skitterspec init` and
+`skitterspec update` install `.claude/hooks/review-gate.cjs` and register it in
+the project's committed `.claude/settings.json`, so a `git commit` is refused by
+the harness rather than by prose — which is what covers a bare `git commit`, a chained command, and
 skittership's own `/commit` without skitterspec ever editing it. It decides
 nothing itself: it hands the command line to
 `spec-env review gate --check --for-command` and turns one exit status into an
@@ -301,7 +312,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 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 
@@ -333,6 +344,27 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
 workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
 the tracker is never read back or merged.
 
+**One-way means the repo wins, and it now wins *loudly*.** Those are different
+claims and only the first was ever in doubt. A ticket's description is generated
+from the spec, so a person editing it there is writing something the next push
+replaces — which is correct, and which used to happen in silence. The engine now
+compares a hash of what the tracker holds against a hash of what the repo last
+sent, and says *that* it changed and where to read it.
+It **reports and never refuses**: only a person can tell a typo fix from a
+paragraph worth keeping.
+
+**This is still not a pull.** Nothing read is merged, written to a spec, or fed
+into the projection, and the text never enters the conversation — the comparison
+is hashes, and the output is one line for a human. It is the same thing
+`compareStored` has always done for a different question.
+
+**And adoption no longer costs the reporter their words.** When a provider
+adopts an existing ticket — one a PM or colleague filed — the linking push
+replaces its description with the spec. Before that happens the original is
+posted back onto the ticket as a **comment**: a surface one-way sync never
+touches, so no later push can clobber it. Where a provider supports it, this is
+automatic and has an opt-out. See the provider's own docs.
+
 A provider may also ship a **read-only listing** of what the tracker holds. That
 is not a pull: nothing is merged back and no spec file is written. It exists
 because the folder buckets are only the truth *on the branch you are standing

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 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
 | **Follow-ups** | none |
 | **Next** | `/spec-next` → phase 3 (Auth) |
 
@@ -87,32 +87,182 @@ the options may be offered after the table.
 
 ## ⏸ Review ready — 7 files, +212 −18
 
-**[Open the page](http://…)** · I'm holding here until you send a verdict.
+- **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
+- **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
+- **remote** — off · `/spec-remote-review` turns it on
 
-`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
-
----
+live: off — /spec-live to put it live
 
-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.
+I'm holding here until you send a verdict — the wait covers local and network.
 
-**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:
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
 
-**[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.
+A rule, a heading naming the state and the size, **the stack**, the `live:`
+line, one line saying the run is stopped and which tiers it covers, and the two
+exits. Nothing else, and never a paragraph explaining it.
+
+**The `live:` line, and why a rigid contract took a second amendment.** Reading
+a diff is not the only way to judge a change — often the question is whether it
+*works* — and the answer to that lives at the running URL. A reader deciding
+whether to open the page at all wants to know whether it is already running
+somewhere, and finding that out any other way is a trip to a terminal in the
+middle of a review.
+
+**Each line names a command a person types**, rather than describing a
+capability. `live: off — the page can put it live` told the reader that a page
+somewhere could do it and left them to find the verb — and the verb is what they
+need when they are in a terminal rather than on the page. So the lines say
+`/spec-live`, `/spec-live main`, `/spec-remote-review`. Making them *clickable*
+was considered and rejected: the only clickable thing markdown has is a URL, and
+a URL that acts when it is **fetched** is one a link previewer or a prefetcher
+fires with nobody involved.
+
+It is the engine's line, copied like the stack: `spec-env review` prints it and
+`--json` carries the same answer as `live`, from one function, so the report and
+the command cannot disagree. Four states, and only three of them are a line —
+`on` (with the URL when the project configured one), `off`, `held` (naming the
+spec holding the workbench). The fourth, `unavailable`,
+**prints nothing at all**:
+a project with no isolation and a spec with no worktree both land there,
+and a line about a surface that does not exist is an accusation against a
+healthy repo.
+
+**This is the second amendment to this section in two specs**, which is worth
+naming rather than letting pass. The contract earns its rigidity from real
+failures, and two amendments in a row is how a rigid contract quietly becomes a
+negotiable one. Both have carried their reason and both replaced a line rather
+than adding a paragraph.
+**A third should have to argue harder than either did.**
+
+**The stack is the engine's, copied rather than composed.** `spec-env review`
+prints one line per tier and `--json` carries the same thing as `tiers`, so take
+it from there in the order it comes — and do not decide which tiers are worth
+mentioning. The whole reason the stack exists is that the engine was being asked
+to guess where the reader was sitting, and it guessed wrong three separate ways
+in one day; a skill re-deciding that in prose is the same guess one layer up.
+
+**Three tiers, always all three, in this order.**
+
+| Tier | Is | Off when |
+|------|----|----------|
+| `local` | the loopback URL — the machine the run is on | never. With nothing served it is the `file://` page, and says it cannot send a verdict |
+| `network` | the LAN URL — a phone on the same wifi | `review.allowNetwork` is false, or this machine has no network address |
+| `remote` | a published page, for a reader off the network | `review.allowRemote` is false, or nothing has been published |
+
+A tier that is off **keeps its line** and names the one command that turns it
+on. Dropping the line is what left a reader who had walked out of the house with
+nothing on screen to tell them a remote page was even possible — they could not
+ask for what they could not see.
+
+**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, and
+  `spec-env review wait` returns when it lands. The run is woken by the press:
+  *"I'm holding here until you send a verdict."*
+
+  **That sentence is only true for as long as the wait is actually running**, so
+  the wait is the engine's and never one composed for the occasion. A watcher
+  written per run is proven by nothing: one was written
+  `until [ -f "$P" ] && [ "$x" \> "$y" ]` — valid bash, a syntax error in zsh,
+  a predicate that could never be true — and it spun for five minutes while the
+  report underneath it said the run was holding.
+  **Silence is what made that expensive**:
+  a wait that cannot fire and one patiently working look identical,
+  so nothing seemed wrong until the reader asked. Give the wait no timeout
+  either; it lasts as long as the session, because a reader who walks away from
+  a diff is the normal case and a bounded watch once lost a verdict to a lunch
+  break.
+- **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 its line in the stack says
+  that rather than letting the holding line speak for it:
+
+- **remote** — [https://…](https://…) · a verdict here needs `/spec-reviewed`
+
+  Where `remote` is the only tier a reader can reach, the holding line says so
+  too: *press a verdict, then type `/spec-reviewed` — I cannot see it until you
+  do.* Where a served tier is reachable as well, the holding line keeps naming
+  the tiers the wait covers, and `remote`'s own caveat sits on `remote`'s line
+  where it belongs.
+
+**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 the same stack, and
+different exits:
+
+…the stack, unchanged…
+
+I'm holding here until you send a verdict — the wait covers local and network.
+
+`Continue` carries on · `Request changes` works them now
+
+The stack is written out once, above, and referred to everywhere else. Two
+copies of it is how the two come to disagree about which tiers exist.
+
+**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.
+
+**One link per reachable store, each labelled.** This amends
+*"exactly one link, never two"*, and the evidence that rule was written on is
+the reason it still reads the way it does. Two links were handed over, the wait
+stood behind only one of them, 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 was not a convenience with a caveat; the caveat existing was the bug.
+
+**What that evidence is about is the store, not the count.** A served page hands
+its pass to the local pending store, which `spec-env review wait` watches; a
+published page writes to the artifact's own store, which nothing here can see.
+Two links into two stores asks the reader to know which door the run is standing
+behind, and they cannot.
+
+**Local and network are two doors into one room.** The page POSTs with
+`fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
+opened at `192.168.0.136:7760/…` reach the same server process and the same
+pending store. One wait covers both, and a verdict pressed on either wakes the
+same run. Between those two the objection does not apply — which is why both are
+offered, and why offering them gives nothing up.
+
+**So two things are required, and the second is what the old rule lacked.**
+Every link is **labelled** with its tier, and one line says
+**which tiers the wait covers**.
+Two *unlabelled* links stay forbidden exactly as before, because
+the reader still cannot tell them apart.
+
+**`remote` keeps the caveat it always had.** It is listed so a reader off the
+network knows the surface exists and what turns it on — never as a door the wait
+is claimed to cover. Where it is on and published, its line says what is true of
+it: *a verdict here needs `/spec-reviewed`*.
+
+**Still forbidden**, in the words of the rule this amends: offering two links
+into **different** stores without saying which one the wait is watching. That is
+the failure that cost three unread verdicts, and nothing here touches it.
 
 **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
@@ -124,11 +274,34 @@ stopped until they answer. A row cannot carry that, because a row is scanned at
 the same weight as every other row. So the state gets the loudest shape on
 screen, at the end, where reading finishes.
 
-**Where the run is not waiting, it stays a `Review` row.** A render nobody is
-being held for — a mid-phase `/spec-diff`, a page produced alongside other work
-— is a convenience, and giving it a banner teaches the reader to scroll past
-banners. The shape marks the difference between *here is a page* and *nothing
-proceeds until you answer*.
+**ASKING IMPLIES WAITING — one rule, and the two shapes follow from it.** Any
+render that asks the reader for a verdict ends the turn watching for one. A run
+that does not intend to wait does not ask: its `Review` row keeps the counts and
+the link and **loses the question**.
+
+So there are two shapes and no third:
+
+- **Asking** → the banner above, and the run waits.
+- **Not asking** → the `Review` row: counts and link, no question.
+
+**What this guards against is a reader taught that the button is decorative.**
+`/spec-bug` and `/spec-hotfix` used to render the page, emit a row
+asking *"want a written review before you commit?"*, and finish — with nothing
+watching. A verdict pressed on that page landed in the holding area and stayed
+there, because the run had told the reader the page was **ready** rather than
+that it was **waiting**. It happened twice on one spec, and the second press
+existed only because the first appeared to do nothing. An offer that cannot be
+answered costs more than never having offered.
+
+**Rejected: keeping the question and adding a caveat** — *"press a verdict, but
+I will not see it until you ask"*. That is exactly the shape that stranded those
+two passes, and a truthful caveat does not make an unanswerable question worth
+asking. Either watch for the answer, or do not ask.
+
+**A render nobody is being held for is still worth reporting** — a mid-phase
+`/spec-diff`, a page produced alongside other work. It gets the row, because
+giving it a banner teaches the reader to scroll past banners. The shape marks
+the difference between *here is a page* and *nothing proceeds until you answer*.
 
 **Never fence a message to the reader.** A fenced block is for a command to
 run, code, or engine output quoted verbatim — things the reader copies or
@@ -185,7 +358,7 @@ behind it — say nothing rather than reporting that there was nothing to report
 | `Landed` | A fast-forward, a tag, a cherry-pick. |
 | `Worktree` | A worktree provisioned, entered, or torn down. |
 | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
-| `Review` | The rendered diff page: files, `+`/`−`, the link — and the offer of a written review, in the same row. **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
+| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
 | `Follow-ups` | **Always.** `none`, or one line each. |
 | `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
 
@@ -204,11 +377,17 @@ silent, because "I provisioned, and your four files are still sitting there" is
 a different sentence from "I provisioned".
 
 **`Review` is one row, not two** — and where the run is waiting, it is no rows
-at all. The page and the offer to read it are the same subject, and splitting
-them made the reader resolve a distinction before acting on either. A waiting
-run promotes the whole subject into the banner; keeping the row as well would
+at all. The page and what to do with it are the same subject, and splitting them
+made the reader resolve a distinction before acting on either. A waiting run
+promotes the whole subject into the banner; keeping the row as well would
 recreate that split with the two halves further apart than ever.
 
+**The row carries no question, and that is the rule above applied here.** It
+once ended *"want a written review before you commit?"* — a question addressed
+to a reader the run was not waiting for. Putting it in a findable row fixed
+where it was; it did not fix that nothing was listening. A run that wants that
+question answered waits for it, and waiting means the banner.
+
 ## The four verdicts
 
 | State | Means |

package/assets/skills/spec/SKILL.md

@@ -105,11 +105,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
   description (an **update** to the existing issue, plus a sub-issue per phase).
   Recording a snapshot here would declare the mirror already in sync and strand
   the issue showing the raw report forever.
+- **Preserve the original, before anything replaces it.** Run this the moment
+  the spec file exists and **before the linking push**:
+
+  ```
+  skitterspec spec-sync preserve <spec>
+  ```
+
+  It posts the issue's current description onto the issue as a comment — the one
+  surface one-way sync never touches, so no push can clobber it. On the API path
+  it reads the description itself; without a key it prints the body and the
+  marker, and you post it with the Linear comment tool after checking the
+  comments for that marker.
+
+  **The ordering is the whole correctness condition.** Run before the push, this
+  keeps what the reporter filed. Run after it, it would keep the generated spec
+  and report success — which is why it is a step of its own here rather than a
+  line in the push sequence. The engine warns when it can tell it is late, but it
+  cannot always tell.
+
+  **It never fails the adoption.** A project that set
+  `intake.preserveOriginal: false`, an unreachable Linear, an issue with no
+  description, a comment Linear refused — every one of them exits 0 and says so.
+  Relay what it printed and carry on.
 - **Say what will happen** in the finish-up message. The linking step runs right
   after the spec is written, so the issue's description is replaced by the spec
-  **then** — not on some later manual push. The reporter's words are not lost:
-  they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
-  keeps the original in the issue's history.
+  **then** — not on some later manual push. Say both halves: the description
+  becomes the spec, **and** the original is preserved as a comment on the same
+  issue, so the reporter can still read what they wrote.
+
+  **Do not send anyone to the issue's history for it.** This used to say Linear
+  keeps the original there, and that is true and useless: history is a diff
+  viewer nobody opens, it is not quotable, and it degrades to "it is in there
+  somewhere". The comment is the answer, and the other half is the spec's own
+  **Problem** (or **Symptom**) section quoting the reporter.
 
 ## Phase A — reach a clear shared understanding (grill first)
 
@@ -339,6 +368,104 @@ open questions, `Draft` when you deliberately left some unresolved. Either way
 the next step is `/spec-start`. The Report section below is where all of that
 reaches the user — do not narrate it here as well.
 
+## Phase C2 — render the spec, then wait for the verdict
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no page and this phase does not exist — skip it in
+silence rather than explaining an absence.
+
+A spec is the one artefact whose whole purpose is to be
+**read before work begins**, and until now it was the only one with no reading
+surface: `/spec`
+finished, the spec sat uncommitted, and `/spec-start` had to point that out and
+commit it as a side effect of provisioning. So this phase ends where every other
+phase of the lifecycle ends — on a page, in a verdict.
+
+```
+skitterspec spec-env review <spec> --docs --buttons authoring
+```
+
+`--docs` reads the spec's own documents from the tree you are standing in, so it
+never wants a worktree — a backlog spec has none. It renders
+**this spec's documents and nobody else's**: several specs are routinely
+authored in one
+checkout, and the file set comes from `spec-env stage`'s `owned` half precisely
+so a colleague's spec cannot land on your page and then be committed under your
+verdict.
+
+**This is free.** The engine reads git and splices text into a template; the
+diff never passes through you.
+
+**Render nothing when nothing was written.** A `⏸` run — grilling that never
+reached a shared understanding — has no spec to show, and must not ask for a
+verdict on one.
+
+**Arm nothing.** There is no `spec-env review arm` in this path, and that is a
+decision rather than an omission: the gate asserts that *a phase which ended*
+owes an answer, and a backlog spec owes no phase. Walking away from this page
+costs nothing — the spec is simply still uncommitted, which `/spec-start` already
+handles. A `/spec` run must leave `spec-env review gate --check` exiting 0.
+
+### The two endings this page offers
+
+`--buttons authoring` offers `Commit & Start` and `Commit` in place of the
+committing pair, because "commit and build the next phase" is meaningless for a
+spec with no phase in flight.
+
+- **`commit-start`** — hand off to `review.commitWith` (`/commit` by default),
+  passing the pathspec the render reported on `docs.paths`, then run
+  **`/spec-start <name>`** and **stop there**. It never completes, lands or tears
+  anything down, exactly as `commit-continue` stops after `/spec-next`. This is
+  the `commit && /spec-start` that was typed by hand.
+- **`commit`** — the same commit, then finish. The spec stays `Ready` in
+  `backlog`, ready for a `/spec-start` whenever it is wanted.
+- **`changes`** — work the notes into the spec, record a resolution for each one
+  so the next render shows it struck through with what changed, then
+  **re-render, and wait again**. The reader is still holding a decision, so
+  ending the turn and
+  making them type `/spec-diff` would reopen the loop this exists to close.
+- **`discuss`** — report and talk. Claim nothing, change nothing.
+
+**Take the pathspec from the render, not from the tree.** A checkout is shared,
+so the set of this spec's uncommitted documents can differ between the render and
+the verdict — and the reader's conclusion is about what the page showed them.
+
+### Then wait for it
+
+**The wait is a command. Do not write one.**
+
+1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
+   the whole scope of what you may claim.
+2. **Run the engine's wait in the background, and end your turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <the timestamp>
+   ```
+
+   It takes no timeout unless you pass one, and you must not pass one: a reader
+   who walks away from a spec is the normal case, and a bounded watch once lost a
+   verdict to a lunch break.
+3. **On waking, let the engine pick:**
+
+   ```
+   skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
+   ```
+
+   It claims the one pass that arrived inside the window, acts on nothing when
+   none did, and refuses to choose when two did.
+4. **Route on the verdict** as above.
+
+**Where the page is `file://`** — the engine could not serve — there is no server
+to POST to, so the pass is copied and pasted and the reader's next message is
+what carries it. **Do not start a watch that cannot fire**: a wait on the pending
+store would spin forever while the report underneath it claimed to be holding,
+which is the exact failure `.claude/rules/spec-reports.md` records. The wait is
+the turn ending, and the banner says so.
+
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three, in that order — never the bare `page:` path. `.claude/rules/spec-reports.md`
+carries the shape and why every tier is named rather than one being chosen.
+
 ## Phase D — record the isolation stack (only if configured)
 
 **Only when `specs/.core/env.config.json` exists** (per-spec isolation is
@@ -468,9 +595,39 @@ the shape; this section carries only what is specific here.
 **Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
 
 `Built` is the spec's path and phase count; `Spec` is its status and bucket;
-`Next` is `/spec-start <name>`, with the name spelled the way it must be typed.
 `Tracker` appears only when a provider is installed and linked it.
 
+**`Next` depends on whether Phase C2 rendered a page.** Where it did, the run is
+waiting on a verdict, so the block **omits the `Review` row** and ends on the
+banner defined in `.claude/rules/spec-reports.md` — counts, the tier stack, and
+this page's two exits:
+
+---
+
+## ⏸ Review ready — &lt;N&gt; files, +&lt;a&gt; −&lt;d&gt;
+
+- **local** — &lt;the `local:` URL&gt;
+- **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
+- **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
+
+I'm holding here until you send a verdict — the wait covers local and network.
+
+`Commit & Start` puts it in flight · `Commit` keeps it for later
+
+---
+
+There `Next` names the page rather than a command, because the button is what
+carries the work on.
+
+Where no page was rendered — isolation is not configured, or nothing was
+written — `Next` is `/spec-start <name>`, with the name spelled the way it must
+be typed.
+
+**A spec written without a page is still uncommitted**, so that `Next` relies on
+`/spec-start` committing the spec when it is all that is uncommitted. Say
+`/commit, then /spec-start <name>` when anything else is uncommitted too, or the
+row sends the reader to a refusal.
+
 **`Follow-ups` is almost always `none` here.** This skill's whole job is to
 capture work, so anything it surfaced belongs in the spec it just wrote rather
 than in a follow-up line beneath it.