@skitterbyte/skitterspec 21.0.0 → 22.1.0

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

@@ -1,6 +1,6 @@
 ---
 name: spec-diff
-description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, or the pasted JSON.
+description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase, and takes --reviewers to run the project's configured code reviewers. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", "run the reviewers", or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
 ---
 
 # /spec-diff — see the phase before you commit it
@@ -41,13 +41,19 @@ sole candidate or prints the candidates.
 The page has marks on it — `✓ accept` per file, notes against a line or a whole
 file, answers to the checks a written review asked — and it
 **ends in a decision**: `✓ Approve`, `↺ Request changes` or `… Discuss first`.
-A review comes back to you one of two ways, and **both are ordinary**:
+A review comes back to you one of three ways, and **all three are ordinary**:
 
 - **A six-digit code** — `418207`, on its own. A *served* page hands its pass
   straight to the engine, which holds it until someone reads the code out. This
   is the usual way on a phone.
-- **A pasted JSON blob** — a `file://` page has no server to talk to, so it
-  copies. Not legacy: it is the whole story for a local reader.
+- **A verdict word** — `commit`, `commit-continue`, `continue`, `changes` or
+  `discuss`. A `file://` page cannot send anything, so where the reader marked
+  nothing it copies a command carrying the conclusion on its own. Send it with
+  `skitterspec spec-env review <spec> --verdict <word>`; it joins the same merge
+  a claimed pass does, so everything below is unchanged.
+- **A pasted JSON blob** — the same `file://` page, once the reader has marked
+  something up: accepts and notes do not fit on a command line, so the whole
+  pass travels. Not legacy: it is the whole story for a local reader.
 
 Either way, **this is not a request to render anything**: it is a review coming
 back, and these steps replace §3–§5 below.
@@ -151,6 +157,17 @@ back, and these steps replace §3–§5 below.
    absent verdict has always meant "report it and wait" — which is why that is
    what it still means.
 
+   **A pass may carry an `action:` instead**, and then none of the above
+   applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
+   carrying both, so there is never a choice to make between them.
+
+   **It is on the `claimed:` line** — `· action: live-on` at the end of it, and
+   `claimed.action` under `--json`. Read it there rather than inferring one
+   from a pass that merged nothing: a claim reporting no verdict and no counts
+   used to be the only trace a press left, which made every action look like a
+   reader who had concluded nothing. If the line carries no action, there was
+   none.
+
 3. **Say what you read, then ask what's up.** Report the accepted count, then
    each open comment as `file:line — note`, then the files you would touch.
    **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -335,6 +352,77 @@ it — and the paste was the one place it broke. The *work* either authorises is
 ordinary phase-sized cost, and step 3 is where the operator decides whether to
 spend it.
 
+## 2b. An action changes something, then hands the page back
+
+Only on a pass carrying an **action**. Three of them, and
+**all three end the same way**:
+do the thing, re-render (§4), and wait again (§4b) — because the reader
+still has a decision in front of them and has not made it.
+
+| Action | Do | Then |
+|--------|----|------|
+| `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
+| `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
+| `allow-remote` | `skitterspec spec-env review allow remote --set on` | re-render, wait again |
+
+**THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
+live is about the diff on screen; handing the whole instance back to `main` is a
+workspace decision with nothing to do with this review. The `live:` line names
+`/spec-live main` for it — a command the operator types, which is also why no
+skill runs it.
+
+**AN ACTION IS NOT A VERDICT, and the gate is untouched by all three.** A phase
+that ended armed the gate, and it is discharged by a committing verdict or a
+recorded skip and by nothing else — so after any of these the phase still owes
+an answer, and that is exactly why the run waits again rather than finishing.
+The engine enforces this rather than trusting it: `ACTIONS` is disjoint from
+`VERDICTS` and `COMMITTING`, so nothing that routes on a verdict can see one.
+
+**`live-on` commits first, and the commit is a precondition rather than an answer.**
+`live take` refuses a dirty worktree, and even without that guard
+uncommitted work stays behind in the worktree — so what went live would be the
+*previous* commit while the page claimed to be showing this one. Hand off to
+`review.commitWith` exactly as §2a does (do not restate its rules here), then
+take the instance. The reader has not approved anything by pressing it.
+
+**It re-renders `--branch` afterwards**, because the working view is now empty:
+the commit just happened, and the branch range is what still answers "what am I
+looking at". §4's clean-tree fallback reaches the same place on its own, so
+passing `--branch` is belt and braces rather than a separate rule.
+
+**A mid-phase page does not get the commit.** Where the render took
+`--buttons midrun`, the work is half a phase — committing it to look at it
+running splits one phase across two commits and leaves a mess nobody asked for.
+Say the phase needs to land first, re-render, and wait.
+
+**Relay every refusal, and work around none of them.** `live take` refuses a
+workbench another spec holds, a hotfix, a stateful spec, a branch touching
+migrations, and a tree with no dev server listening. Each refusal names its own
+way out. **Never park another spec's live session** to make room — that is
+someone else's work, and freeing it is their decision. Re-render and wait, so
+the reader can choose something else.
+
+**A refusal may declare the way out of itself.** Ask with
+`skitterspec spec-env live take <spec> --json` and read its `offer` field:
+where one is present, relay the refusal and **then** offer it, exactly as
+`.claude/rules/offered-unblocks.md` describes. Do not re-decide from the reason
+text, and do not infer an offer that is not there — the boundary that keeps
+another spec's workbench out of this lives in that field rather than in prose
+here.
+
+**`allow` writes a committed file, and that is worth a sentence.** It edits
+`specs/.core/env.config.json` in the **primary checkout**, so it changes
+behaviour for everyone who pulls and leaves that tree dirty — unlike the live
+actions, which move a branch and write a gitignored receipt. The engine prints
+the absolute path and whose tree it dirtied; relay that rather than letting a
+shared setting change land silently. And it is **enable-only**: there is no
+action that turns a tier off, because turning `network` off from a page reached
+over the network kills the page doing the turning.
+
+**`allow remote` permits publishing. It does not publish.** Publishing stays an
+explicit ask in every case (§6), because the page it leaves behind is one this
+tooling cannot remove.
+
 ## 3. Gate it on nothing
 
 **This skill has no preconditions and must never grow one.** Not tests passing,
@@ -364,18 +452,37 @@ help someone give one.
 ```
 skitterspec spec-env review <spec>              # uncommitted work (the default)
 skitterspec spec-env review <spec> --branch     # everything since the base branch
+skitterspec spec-env review <spec> --run-reviewers   # …and run review.reviewers
 skitterspec spec-env review serve               # every spec, on localhost
 ```
 
-**The engine handles the switch.** A file when the reader is at this machine, a
-served URL when they are not: on a `remote` reader it stands its own server up
-and puts a URL the reader can open on the `open:` line. Both are free and neither
-publishes anything. You are not choosing between them; you are relaying whichever
-one the engine printed.
-
-The operator who does not want a LAN listener started for them sets
-`review.serveOnRemote: false` in `env.config.json`, and the `file://` link with
-its *will not open where you are reading* marker comes back.
+**`--run-reviewers` is opt-in here, and a BARE `/spec-diff` MUST NOT PASS IT.**
+`/spec-next` runs the project's configured reviewers once per phase, where the
+cost is paid against work that is finished. This skill answers at any point,
+including several times in one phase — and each run spends a review against
+whatever hourly limit the reviewer has, which on the tiers this was built for is
+measured in single figures.
+
+So pass it when the operator asked for it: `/spec-diff --reviewers`, or they said
+in words that they want the second opinion. Otherwise render without it. The
+cached findings from the phase-end run still show on the page whenever the diff
+has not moved, so the usual mid-phase read loses nothing by not asking.
+
+Where it does run, say what it cost — a reviewer takes 30s–3min — and nothing
+else. The page's own strip reports each reviewer's outcome, and a reviewer that
+could not run is that strip's business rather than yours.
+
+**There is no switch left to handle.** The engine serves and prints a **stack** —
+one line per tier, `local`, `network`, `remote`, each either a URL or the one
+command that turns it on. All of it is free and none of it publishes anything.
+You are not choosing between them; you are relaying every line it printed.
+`.claude/rules/spec-reports.md` carries the shape and why.
+
+The operator who does not want a LAN listener sets `review.allowNetwork: false`
+in `env.config.json` — `network` then reads `off` with the command that turns it
+back on, and `local` is the loopback page. Turning serving off entirely is
+`review.serve: "never"`, and then `local` is the `file://` page, which says on
+its own line that it cannot send a verdict.
 
 `serve` renders **per request**, so nothing it shows can be stale, and it lists
 every spec with a worktree rather than one. `--host 0.0.0.0` binds beyond
@@ -428,21 +535,29 @@ 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
-
-`spec-env review` reports where it believes the reader is, and
-**that is the only place this question is answered.** Three states:
-
-| `reader:` | What to offer |
-|-----------|---------------|
-| absent (`unknown`) | the `file://` URL, exactly as always. **Do not warn** — unknown is the ordinary state of a local machine |
-| `local` | the `file://` URL |
-| `remote` | the `open:` line as printed — the engine already served it. Pass on any `also:` lines too |
-
-**Never read an environment variable to decide this.** Not `SSH_CONNECTION`, not
-`CLAUDE_CODE_*`, not a tty check — the engine already did it, reports the answer
-on that line and in `--json`, and a second implementation here could not be
-tested and would drift from the first. The ranking and the traps
+## 4a. Relay the stack — every tier, never one you picked
+
+`spec-env review` prints one line per tier and `--json` carries the same thing
+as `tiers`. **Relay all of them, in that order**, whatever the `reader:` line
+says:
+
+| Tier | Carries |
+|------|---------|
+| `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
+| `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
+| `remote` | the published URL and *a verdict here needs `/spec-reviewed`* — or `off` with the command that turns it on |
+
+**The `reader:` line decides nothing here any more.** It is still printed and
+still the only place that question is answered, but the offer no longer branches
+on it — because branching on it is what produced a `file://` page for a session
+detected `unknown`, a LAN URL for a phone off the network, and an address that
+changed underneath a reader mid-session. A tier that is off keeps its line, so a
+reader who has left the house can see the surface exists and ask for it.
+
+**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
+for a detection to decide, and a second implementation of one could not be
+tested and would drift. The ranking and the traps
 (`CLAUDE_CODE_ENTRYPOINT` describes the *process*, not the reader; stdin is never
 a tty under Claude Code) live in `review.js` beside the code, which is where they
 belong.
@@ -461,8 +576,9 @@ answer left.
 
 `review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
 operator settle where they are reading, and an explicit value is believed without
-sniffing. `review.serveOnRemote` (default `true`) settles whether the engine may
-act on it.
+sniffing. What the engine may *do* is settled by the tier settings instead —
+`review.serve` (`always` · `never`), `review.allowNetwork` and
+`review.allowRemote` — not by the reader.
 
 ## 4b. Wait for the verdict — because asking for one means waiting for it
 
@@ -483,8 +599,8 @@ 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 served page** posts to the local store; the engine's own wait returns when
+  it lands, and the steps below run it.
 - **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.
@@ -498,9 +614,20 @@ 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.
+2. **Run the engine's wait in the background, and end the turn:**
+
+   ```
+   skitterspec spec-env review wait <spec> --since <timestamp>
+   ```
+
+   **Never a watcher of your own, and never a timeout.** It lasts as long as the
+   session, because a reader who walks away from a diff is the normal case — and
+   a loop composed here would be proven by nothing, which is how one written as
+   `[ "$x" \> "$y" ]` spun for five minutes in zsh and looked exactly like
+   patience. `/spec-next` §5 carries the full account.
+
+   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:**
 
    ```
@@ -711,8 +838,8 @@ consumed rather than stored.
 purpose; someone who forgot they had voted has not, and only the report tells
 them apart.
 
-`Review` carries the files and `+`/`−`, the page's `open:` line, and the
-published URL when there is one. Where the page holds a review pass, it also
+`Review` carries the files and `+`/`−`, and the tier stack — labelled, run
+together with `·` because a row is one cell. Where the page holds a review pass, it also
 carries the three totals — files accepted, comments open, comments answered.
 `--json` reports those under `notes.totals`; read that, never the diff.
 

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

@@ -274,30 +274,33 @@ 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.
+Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
+three — rather than the bare `page:` path: a path is not clickable in any
+terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
+line with it where the engine printed one, and nothing where it did not.
+`.claude/rules/spec-reports.md` carries the shape, including why a rigid
+contract took that line.
 
 - **Never write the review unasked**, and **never publish**. Publishing leaves
   something behind that this tooling cannot remove, so it is always an ask. A
   `file://` link is no use on a phone, and saying so **is** the ask —
   `/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.
+**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.** A `remote` reader
 authorises a local server — one process, ended by one flag, leaving nothing

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

@@ -27,8 +27,10 @@ clobber customised content. Finish with a summary of created vs already-present.
 > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
 > `--reset` (reset needs `--yes`) drive the stronger actions.
 
-The system is **twelve skills**: `spec` (feature), `spec-bug` (bug),
-`spec-hotfix` (a bug fixed on a released tag), `spec-review`, `spec-start`,
+The system is **thirteen skills**: `spec` (feature), `spec-bug` (bug),
+`spec-hotfix` (a bug fixed on a released tag),
+`no-spec` (work that genuinely has none — off the base branch all the same),
+`spec-review`, `spec-start`,
 `spec-next`, `spec-diff` (read a spec's diff as a page),
 `spec-reviewed` (pick up a review you approved on that page), `spec-to-main`,
 `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,