@skitterbyte/skitterspec 20.0.0 → 22.0.0

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

@@ -154,6 +154,24 @@ Before writing any code for this phase, get the workspace clean:
   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.
 
+- **Report anything left waiting, and claim none of it.** Ask the engine once:
+
+  ```
+  skitterspec spec-env review waiting
+  ```
+
+  A pass listed here arrived when nothing was watching — a wait that never ran,
+  a session cleared, a terminal closed overnight — and no watcher can recover
+  those, however good. Relay what it prints: the spec, the code, the verdict and
+  the age, with `/spec-reviewed <code>` to pick one up and `--drop <code>` to
+  disown it.
+
+  **It is information, not a gate.** It never refuses, nothing here is
+  conditional on it, and **you never claim one** — `/spec-diff` §0 stands
+  unchanged, and a pass sitting there when you arrived was not sent to you.
+  Silent when nothing is waiting, which is the usual case: say nothing rather
+  than reporting that there was nothing to report.
+
 ## 3. Implement the phase
 
 Identify the **first unfinished phase** from the `00-overview.md` phase index,
@@ -269,6 +287,12 @@ skitterspec spec-env review <spec>
 the diff never passes through you, so a 266KB patch costs nothing. Report the
 path it prints and move on.
 
+**This render takes the committing button set**, which is the default — so
+`--buttons` is not passed. That is a statement about the work, not about the
+gate: the phase is finished, so `Commit` and `Commit & Continue` are the right
+verbs for it. A render part-way through a run takes `--buttons midrun` and
+offers `Continue` instead; `/spec-diff` owns that case.
+
 **Then arm the gate**, so the phase now owes a verdict:
 
 ```
@@ -293,41 +317,72 @@ 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.
+- **local** — <the `local:` URL>
+- **network** — <the `network:` URL, or off with the command that turns it on>
+- **remote** — <the `remote:` URL, or off with the command that turns it on>
 
-`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+<the `live:` line, exactly as the engine printed it — omitted when it printed none>
 
-**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.
+I'm holding here until you send a verdict — the wait covers local and network.
 
-**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.
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+
+**The stack is the engine's — copy it, do not compose it.** `spec-env review`
+printed one line per tier, in that order, and `--json` carries the same thing as
+`tiers`. Relay all three whatever they say, including the ones that are off with
+the command that turns them on: a reader who has left the house cannot ask for a
+remote page they were never shown.
+
+**Do not pick one for them.** The engine used to, and the guess failed three
+separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
+why the *one link, never two* rule now reads
+**one link per reachable store, each labelled** —
+local and network are two doors into one room, so the wait
+covers both. `remote` is a second store, so its own line carries its own caveat:
+*a verdict here needs `/spec-reviewed`*, because nothing pushes from
+the artifact store into this conversation. Never let the holding line promise a
+wait over that tier.
+
+**Publishing is still never yours to do.** `remote` reading `off` is the normal
+state, and the fix for it is the command on that line — typed by the operator,
+or pressed on the page, because a published page is one this tooling cannot
+remove and permitting it is not publishing it.
+
+**The `live:` line goes with the stack**, and it is the engine's line too —
+copied as printed, and **absent when the engine printed none**. The page can act
+on it: a press puts the spec live or takes it down and hands the reader back the
+same page, which is `/spec-diff` §2b's routing and not this skill's. What
+matters here is that an action **never clears the gate this phase armed** — the
+reader has looked at it running and concluded nothing, so the phase still owes a
+verdict.
 
 ---
 
-**Where you are not waiting, it stays the `Review` row** — the counts, the page
-link and a question, in one row:
+**Where you are not waiting, it stays the `Review` row** — the counts and the
+page link, and **no question**:
+
+| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** off |
 
-| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+At the end of a phase you are always waiting, so this shape belongs to the
+renders that are not this step: a mid-phase `/spec-diff`, a page produced
+alongside other work. A row cannot be waited on, so a question in one is
+unanswerable however findable it is.
 
 **Both shapes are addressed to someone, and that is the constraint.** The offer
 was once a fenced block of engine output: two quoted lines under the test
 counts, addressed to nobody, with the report then closing on *"commit this
 first"* — the last instruction the reader got was to move on, so they did. A row
-in a labelled table is findable; a question in it is answerable; a banner says
-the work has stopped. What must never come back is something unaddressed,
-unfindable, or fenced.
+in a labelled table is findable; a banner says the work has stopped. What must
+never come back is something unaddressed, unfindable, or fenced.
+
+**The row asks nothing, and that is not a weakening of the above.** A row cannot
+be waited on, so a question in one is unanswerable however findable it is —
+which is the failure `spec-reports.md` records under *asking implies waiting*.
+The row names the page; the banner is what asks, because the banner is the shape
+the run is standing behind.
 
 **Never bury it and never split it.** The row sits above the last two rows of
-the block, and the page and the question stay in the same row; the banner
+the block, and the page and its counts stay in the same row; the banner
 replaces the row rather than joining it. Two places naming one page make the reader
 resolve a distinction before acting on either — which is the same failure
 whether the two places are adjacent rows or a row and a banner.
@@ -336,16 +391,25 @@ whether the two places are adjacent rows or a row and a banner.
 
 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.
+
+**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. **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.
+2. **Run the engine's wait in the background, and end your turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <the timestamp>
+   ```
+
+   It returns when a pass arrives inside that window, and
+   **it takes no timeout unless you pass one** —
+   the wait lasts as long as your session, because a reader who walks away from
+   a diff is the normal case rather than the edge one. Do not give it a duration
+   of your own.
+
+   Then **end your turn**. Do not poll it 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**:
 
    ```
@@ -353,11 +417,26 @@ reader pressed is what carries the work on.
    ```
 
    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).
+   at all when none did (the wait can be woken by something 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 A COMMAND RATHER THAN A LOOP YOU COMPOSE.** This step used to say "watch
+the pending store" and stop, so every run invented its own watcher in shell —
+and three failed in two days, each reaching the operator as *"I pressed the
+button and nothing happened"*. The worst wrote
+`until [ -f "$P" ] && [ "$x" \> "$y" ]`: valid bash, a syntax error in zsh, a
+predicate that could never be true. It spun for five minutes writing to a
+stderr nobody reads.
+
+**The bug is not the lesson — the silence is.** A watcher that can never fire
+and one patiently working are indistinguishable from outside, so nothing about
+that run looked wrong until the operator asked. `review wait` says it has
+started, is written once, and is tested against a store that gains a pass
+mid-flight. A predicate composed fresh each time is proven by nothing.
+
 **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
@@ -371,46 +450,52 @@ 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.
+**Where the harness cannot run something in the background, you still wait** —
+the turn ending is the wait. Say the page is rendered and that you are holding
+for the pass, then end your turn; the reader's next message is what carries it,
+and `/spec-diff` picks it up from the paste exactly as it always has. The gate
+holds either way: it is the engine's, not the wait's.
+
+This once read *"change nothing"* — keep the row, keep the question, do not
+wait — and that exemption is the hatch a whole class of unanswerable questions
+came through. Every harness can end a turn.
 
 **It still does not break a chained run.** `/commit && /spec-next` is typed as
 one line; by the time this step is reached the chain has finished, so waiting
 here stops nothing that was still going to happen.
 
-Relay the **`open:`** line the engine prints, not the bare path: a path is not
-clickable in any terminal, and a page nobody can open is a page nobody reads.
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines —
+never the bare `page:` path: a path is not clickable in any terminal, and a page
+nobody can open is a page nobody reads.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always something
   someone asks for. A `file://` link is no use on a phone, and saying so **is**
   the ask — publishing is the answer to it, and `/spec-diff` §6 owns how.
-**Follow the `reader:` line the engine printed — do not sniff for it.** It
-answers where the person reading this is sitting, and the offer changes with it:
-
-- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
-  unknown is the ordinary state of a local machine, and a warning there is an
-  accusation against a healthy session.
-- **`local`** — the `file://` URL.
-- **`remote`** — the engine has already stood its local server up and put a URL
-  the reader can open on `open:`. So there is **nothing special to say**: relay
-  that line like any other. Any `also:` lines under it are the other addresses
-  this machine has, offered because the best-guess one can be wrong — pass them
-  on rather than editing them out.
-
-**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
-not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
-and in `--json`, and a second implementation here could not be tested and would
-drift.
-
-**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. 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.
+**The `reader:` line no longer decides anything here, and that is the point.**
+It is still printed, and it is still the only place that question is answered —
+but the offer does not change with it, because the stack lists every tier
+whatever it says. Three reader states used to mean three different offers, and
+that branching is exactly what produced a `file://` page on a session detected
+`unknown`, a LAN URL for a phone off the network, and an address that changed
+underneath a reader when detection flipped mid-session.
+
+So: **relay all three tier lines, every time.** Any `also:` lines sit under
+`network` — the other addresses this machine has, offered because the
+best-guess one can be wrong — so pass them on rather than editing them out.
+
+**Never read an environment variable to decide anything about the offer** — not
+`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
+here for a detection to decide, and a second implementation of one could not be
+tested and would drift.
+
+**Serving is the engine's to do; publishing is never.** The server is one
+process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
+decides whether it binds wide — no detection involved. A reader the server CAN
+reach is not a reason to publish as well: the tiers they can already open are on
+the stack. Publishing leaves a page this tooling cannot remove, so it stays an
+ask in every case, always — which is why `remote` shows the command rather than
+a URL until someone types it.
 
 - **Never fatal.** A failed render — no worktree, a git error — is one line and
   the phase is still done. The page is a convenience; the repo is the record.

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

@@ -102,6 +102,67 @@ resolve it by reading the code, do that instead of asking.
 
 
 
+## 4b. Hand the refresh back on a page, then wait
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present) **and this review actually changed something.** Either missing → skip
+the whole step in silence.
+
+A refreshed spec is a rewrite of a document someone is about to work from, so it
+gets read before it is committed — the same ending `/spec` now has:
+
+```
+skitterspec spec-env review <spec> --docs --buttons refresh
+```
+
+`--docs` reads the spec's own documents from the tree you are standing in, so it
+wants no worktree and works for a spec in any bucket. These documents are
+**tracked**, so the diff against `HEAD` is a patch rather than a set of new
+files — which is exactly what the reader wants here: what drifted, and what you
+rewrote.
+
+**Render nothing when nothing changed.** `/spec-review` frequently concludes a
+spec is still accurate, and that is a success rather than a gap. A page showing
+an empty diff under a commit button asks for a verdict on nothing, and the
+engine refuses it for the same reason — `nothing to review`. Take that refusal
+as the answer and report the `⏸`/`✅` you already had.
+
+**Arm nothing.** No `review arm` here: the gate asserts that a phase which ended
+owes an answer, and a re-validated spec has ended no phase. Walking away leaves
+an uncommitted spec, which is the state this skill has always finished in.
+
+### The three endings
+
+`--buttons refresh` offers `Commit`, `Request changes` and `Discuss`.
+
+**No start verdict, deliberately.** The spec this skill refreshed may already be
+in progress — that is half of what it is used for — so `Commit & Start` would
+offer to provision a worktree for a spec that already has one.
+
+- **`commit`** — hand off to `review.commitWith` (`/commit` by default) with the
+  pathspec the render reported on `docs.paths`, then finish. The spec keeps
+  whatever status step 4 left it in.
+- **`changes`** — work the notes into the spec, record a resolution for each so
+  the next render strikes it through with what changed, re-render, and wait
+  again.
+- **`discuss`** — report and talk. Claim nothing, change nothing.
+
+### Then wait for it
+
+**The wait is a command. Do not write one.** Note the moment you start waiting
+as an ISO timestamp, run the engine's wait in the background, and end your turn:
+
+```
+skitterspec spec-env review wait <spec> --since <the timestamp>
+```
+
+Pass no timeout. On waking, let the engine pick the pass —
+`skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json`
+— and route on the verdict above.
+
+**Where the page is `file://`** the pass is copied and pasted, so the wait is the
+turn ending and the banner says so. Do not start a watch that cannot fire.
+
 ## 5. Report
 
 Do **not** `git commit` unless the user asks.
@@ -122,6 +183,32 @@ the shape; this section carries only what is specific here.
 API that moved, a task the code already does. `Spec` carries the status the
 review leaves it in, which is the answer to "can I start this?".
 
+**Where step 4b rendered a page the run is waiting**, so the block omits the
+`Review` row and ends on the banner from `.claude/rules/spec-reports.md` — the
+tier stack copied from the engine's own lines, never one link chosen for the
+reader:
+
+---
+
+## ⏸ 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` commits the refresh · `Request changes` works them now
+
+---
+
+`Next` then names the page rather than a command, because the button is what
+carries the work on.
+
+Where nothing was rendered — no isolation, or no drift to show — `Next` is
+`/commit, then /spec-start <name>`, since this skill does not commit and
+`/spec-start` refuses a tree holding anything that is not the spec's.
+
 **Drift found and not fixed is a `Follow-up`, not a silence.** A spec this skill
 declared reviewed is one nobody will re-read; something it noticed and left
 undone has to leave the session in writing or it did not happen.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-reviewed
-description: Pick up the review you approved on the page — run it bare to pick up the single waiting pass, paste the six-digit code off the page ("/spec-reviewed 608223") to name one exactly, and be asked which only when two are waiting. Use when the user says "/spec-reviewed", "I approved it", "I've reviewed it", "pick up my review", "I pressed approve", or otherwise says they have finished reviewing a rendered diff.
+description: Pick up the review you approved on the page — run it bare to pick up the single waiting pass, paste the six-digit code off the page ("/spec-reviewed 608223") to name one exactly, or pass the verdict itself ("/spec-reviewed commit") when the page could not send and copied you a command instead. Use when the user says "/spec-reviewed", "I approved it", "I've reviewed it", "pick up my review", "I pressed approve", or otherwise says they have finished reviewing a rendered diff.
 disable-model-invocation: true
 ---
 
@@ -70,16 +70,42 @@ Several provisioned and none resolved is a refusal — relay its list and stop,
 never pick from it. See `.claude/rules/spec-planning.md`; do not restate the
 rule here.
 
-**Three argument shapes, and they cannot collide.** A **six-digit code**
-matches `^\d{6}$`; a **tracker id** carries a letter and a hyphen; a
-**spec name** is neither. So the parse needs no flag, and nothing has to be
-guessed at from context.
+**Four argument shapes, and they cannot collide.** A **six-digit code**
+matches `^\d{6}$`; a **verdict** is one of a closed list of six words;
+a **tracker id** carries a letter and a hyphen;
+a **spec name** is none of them and always carries a lifecycle prefix
+(`feat-`, `bug-`, `hotfix-`), which no verdict does. So the parse needs no flag,
+and nothing has to be guessed at from context.
 
 A **six-digit code** is a pass the operator read off their own page. It says
 **which pass**, not which spec — so resolve the spec exactly as a bare
 invocation does, above, and claim the code *there*. Then go to step 4 — a named
 pass has nothing to disambiguate.
 
+A **verdict word** — `commit`, `commit-continue`, `commit-start`, `continue`,
+`changes`, `discuss` — is the conclusion itself, arriving without a pass behind
+it. It is
+what a **`file://` page** hands over: that page has no server to POST to and no
+store to write to, so it copies a command instead of sending anything, and this
+is the command. Resolve the spec as a bare invocation does, then send the word
+through the engine:
+
+```
+skitterspec spec-env review <spec> --verdict <word>
+```
+
+It joins the same merge a claimed pass goes through, so the routing in step 4
+is unchanged: a commit over open notes is refused exactly as it would be, the
+outcome log records it, and the gate a phase armed is cleared. Then go to step
+4 — there is nothing to disambiguate.
+
+**A word carries a verdict and nothing else**, and that is a property of the
+transport, not a shortcut. Accepts and comments do not fit on a command line,
+so the page only ever offers the words while the reader has marked nothing —
+the moment they tick an accept or write a note it goes back to handing over the
+blob. If someone tells you they marked things up *and* gives you a word, ask
+for the pass: the word would land a verdict with their notes silently dropped.
+
 A **name** targets that spec instead. A **tracker id** does too, but only
 through a **provider seam**: the base knows nothing about tracker ids, so
 resolve one by asking whichever provider is installed for its listing —

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

@@ -268,6 +268,25 @@ here beyond knowing it is no longer dead code.
 A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
 it is well-formed first.
 
+- **Report anything left waiting, and claim none of it.** Ask the engine once:
+
+  ```
+  skitterspec spec-env review waiting
+  ```
+
+  A pass listed here arrived when nothing was watching — a wait that never ran,
+  a session cleared, a terminal closed overnight — and no watcher can recover
+  those, however good. Relay what it prints: the spec, the code, the verdict and
+  the age, with `/spec-reviewed <code>` to pick one up and `--drop <code>` to
+  disown it.
+
+  **It is information, not a gate.** It never refuses, nothing here is
+  conditional on it, and **you never claim one** — `/spec-diff` §0 stands
+  unchanged, and a pass sitting there when you arrived was not sent to you.
+  Silent when nothing is waiting, which is the usual case: say nothing rather
+  than reporting that there was nothing to report.
+
+
 ## 4b. Note a missing gating decision (only if configured)
 
 **Only when `specs/.core/gating.config.json` exists.** Run

package/package.json

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