@skitterbyte/skitterspec 21.0.0 → 22.0.0

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": "21.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",