@skitterbyte/skitterspec 17.0.0 → 19.0.0

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

@@ -5,6 +5,11 @@ description: Fix a production bug on the exact released version — fork a workt
 
 # /spec-hotfix — fix a released version, tag it, cherry-pick back to main
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 This is the **hotfix** counterpart to `/spec-bug`. Same test-first discipline
 (reproduce as a **failing test (RED)**, then drive to **GREEN**), but the base is
 a **release tag**, not `main`: prod is running a tagged version, so the fix must
@@ -61,11 +66,13 @@ that header — must exist **before** `spec-env up`:
   `## Symptom` you established. It starts in `in-progress` — work begins now.
 - Run `skitterspec spec-env up hotfix-<name>`. It prints a `git worktree add …
   -b hotfix/<slug> <tag>` command (the branch forks from **the tag**, not
-  `main`), the worktree path, the opener, and any `in the worktree, run:`
-  bootstrap steps.
-- Run the printed `git worktree add`. **The worktree is checked out at the tag,
-  so your uncommitted stub doesn't travel with it** — move it across so `main`
-  stays pristine. **Create the destination bucket first:**
+  `main`), the worktree path, and any `in the worktree, run:` bootstrap steps.
+- Run the printed `git worktree add`, then **move the stub across yourself.**
+  This is where a hotfix differs from `/spec-bug`, which no longer needs the move:
+  that skill's worktree forks from `main`, so committing the stub puts it there,
+  while **this worktree is checked out at the tag** — a commit on `main` is not in
+  it and never will be. The move is not redundant here; keep it.
+  **Create the destination bucket first:**
 
   ```
   mkdir -p <worktreePath>/specs/in-progress
@@ -74,14 +81,13 @@ that header — must exist **before** `spec-env up`:
 
   The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
   `specs/in-progress/` is **absent** from the worktree whenever nothing was in
-  progress at that point in history — and here that point is an **old release
-  tag**, where it is absent more often than not. `mv` into a missing destination
-  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
-  end up one level too high, `00-overview.md` sits where the bucket should be, and
-  every later step still appears to work until something cannot find the spec.
-  Confirm the result before carrying on — you want
-  `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`.
-- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  progress at that point in history — and here that point is an
+  **old release tag**, where it is absent more often than not. `mv` into a
+  missing destination renames your spec folder **to** `specs/in-progress`,
+  silently: the spec's files end up one level too high, `00-overview.md` sits
+  where the bucket should be, and every later step still appears to work until
+  something cannot find the spec. Confirm the result before carrying on — you
+  want `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`. - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
   anything else.
@@ -123,6 +129,8 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
 > **Base version:** <tag prod is running, e.g. v33.16.4>
 > **Raised:** <YYYY-MM-DD (today)>
 > **Area:** <files/modules>
+> **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
+> when release gating is configured, and overridable — see below>
 
 ## Symptom
 
@@ -189,6 +197,23 @@ narrative and decisions).
 
 
 
+
+
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** A hotfix is the one spec
+type that does **not** ask the question cold: it writes
+`none: hotfix — restoring released behaviour` and asks only for confirmation.
+
+The default differs on purpose. A hotfix restores behaviour a release already
+had, under time pressure, and the fix is captured by a deploy tag rather than
+riding the next release — so a flag has nothing to gate and nothing to roll back
+to. Making someone answer a design question mid-incident buys nothing.
+
+It is a **default, not a rule**: say what you are writing and let the user
+override it. If they name a flag, record that instead. Skip entirely when the
+config is absent.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
@@ -205,18 +230,115 @@ is a no-op.
 
 
 
+## 6b. Render the page — then offer the review, never write it
+
+**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 —
+skip it in silence rather than explaining an absence.
+
+The fix is green and nothing is committed yet. That is the moment the page is
+about, so render it now — **after** the tests pass and **before** the commit:
+
+```
+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.
+
+**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.
+
+
+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.
+
+- **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.
+
+**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. 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.
+
+- **Never fatal.** A failed render — no worktree, a git error — is one line, and
+  the fix is still done. The page is a convenience; the repo is the record.
+
+**The range is measured from the base tag, not from `main`.** A hotfix forks its
+worktree from its `> **Base version:**` tag, and the engine reads that header, so
+the header line says `since <tag>` — do not relay it as `since main`, and do not
+reach for a branch view expecting the base branch.
+
 ## 7. Report
 
-Summarise: the base tag, root cause, the failing→passing test, the fix, and the
-full test result. The spec stays in `in-progress`.
+Do **not** `git push` or `git tag`-and-push unless the user asks — deploying to
+prod is theirs to trigger. The spec stays in `in-progress`.
 
 - **`/spec-live` is refused for a hotfix** — its branch is built on an old tag, so
   hot-reloading it onto the running dev server could break the shared instance.
   To test it, the user runs `/spec-connect` (its own isolated stack).
-- Suggest **`/spec-complete`** to land it: it patch-bumps the base tag, tags the
-  hotfix branch **locally** (you push it to deploy), and cherry-picks the fix onto
-  `main`. Add `--also <tag>` at completion to also patch other release lines
-  (test/demo on their own versions).
+- `Next` points at **`/spec-complete`** to land it: it patch-bumps the base tag,
+  tags the hotfix branch **locally** (you push it to deploy), and cherry-picks the
+  fix onto `main`. Add `--also <tag>` at completion to also patch other release
+  lines (test/demo on their own versions).
 
-Do **not** `git push` or `git tag`-and-push unless the user asks — deploying to
-prod is theirs to trigger.
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — red→green on the base tag, fix in, suite passing.
+- `⚠️` — green, with something worth knowing.
+- `❌` — still red, or a later test broke. Quote the failure.
+- `⏸` — no reproduction on that tag, or the tag could not be established.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
+`Review` · `Follow-ups` · `Next`
+
+**The base tag goes in the verdict clause** — `✅ /spec-hotfix · hotfix-foo ·
+green on v2.3.1`. Which released version this was fixed against is the first
+thing anyone needs, and it is not a field: the clause is where the run says
+where it got to.
+
+Step 6b'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.

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

@@ -5,6 +5,11 @@ description: Bootstrap the spec-driven-development workflow in the current proje
 
 # /spec-init — set up the spec-driven-development workflow
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 Bootstrap (or repair) everything this project needs to run the spec lifecycle.
 **Idempotent:** detect what already exists, create only what's missing, and never
 clobber customised content. Finish with a summary of created vs already-present.
@@ -22,10 +27,11 @@ 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 **ten skills**: `spec` (feature), `spec-bug` (bug),
+The system is **twelve skills**: `spec` (feature), `spec-bug` (bug),
 `spec-hotfix` (a bug fixed on a released tag), `spec-review`, `spec-start`,
-`spec-next`, `spec-to-main`, `spec-complete`, `spec-cancel`, and this
-`spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
+`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`,
 with `.core` holding always-apply project rules.
 
 ## 0. Workspace mode (only when adopting isolation)
@@ -37,6 +43,19 @@ checkout you are already in; one spec at a time, no hand-off). It is a question
 about how the operator works, not about what the repo contains, so ask rather
 than infer it from whether dev servers or Docker are configured.
 
+## 0b. Release gating (optional, and separate)
+
+Ask whether specs should record a **release-gating** decision — does this change
+ship behind a feature flag, or land live? Adopting it copies
+`specs/.core/gating.config.json.example` → `gating.config.json` and sets
+`guidance` to wherever this project documents its flags.
+
+It is **orthogonal to isolation**: a project can adopt either, both, or neither.
+Skitterspec never learns how the flags work — it asks the question, cites that
+path, and records the answer on each spec. Leave it off and nothing appears:
+no question, no header, no check. Off is a perfectly good answer for a project
+that does not use flags.
+
 ## 1. Folders
 
 Create any that are missing; drop a `.gitkeep` into ones that would otherwise be
@@ -80,8 +99,8 @@ Ensure it exists. If missing, create it documenting:
 - the **Author** / **Developer** header fields;
 - the **State log** audit table (folder/status transitions), kept separate from
   the **Changelog** (decisions);
-- the project's concrete typecheck/test commands, and the rule that **every
-  phase ends with creating + running tests**.
+- the project's concrete typecheck/test commands, and the rule that
+  **every phase ends with creating + running tests**.
 
 Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
 rather than inventing them. If the rule already exists, leave it unless stale.
@@ -96,7 +115,28 @@ the section exists, refresh only stale folder/skill names — don't rewrite it.
 
 ## 6. Report
 
-Summarise per area — folders, `.gitignore` lines, tooling-ignore negations,
-skills (present/missing), rule file, CLAUDE.md section — as created / updated /
-already-present, plus the `git check-ignore` result for `.core`. Do **not**
-`git commit` unless the user asks.
+Do **not** `git commit` unless the user asks.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — every area is in place.
+- `⚠️` — bootstrapped, with something worth knowing: a skill that could not be
+  installed, a CLAUDE.md that was left alone, a `.core` that is still ignored.
+- `❌` — it wrote some areas and failed on another. Name which, so the re-run is
+  informed; this skill is idempotent and re-running it is the fix.
+- `⏸` — not a git repo, or nothing it could safely write into.
+
+**Fields:** `Built` · `Follow-ups` · `Next`
+
+**`Built` is per area, one line each** — folders, `.gitignore` lines,
+tooling-ignore negations, skills (present/missing), rule files, CLAUDE.md
+section — as created / updated / already-present, plus the `git check-ignore`
+result for `.core`. This is the one skill whose `Built` is a list rather than a
+clause, because "what is now true of this project" is the entire answer it
+exists to give.
+
+**There is no spec to name**, so the verdict line drops that segment:
+`✅ /spec-init · every area in place`.

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

@@ -1,10 +1,15 @@
 ---
 name: spec-next
-description: Build the next unfinished phase of the spec currently in flight on this checkout — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
+description: Build the next unfinished phase of the spec in flight for this session — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one, and builds wherever that spec resolves rather than wherever the session happens to stand. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
 ---
 
 # /spec-next — build the next phase of the spec in flight
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 It assumes the workbench is already set up: a spec is **in flight** on this
 checkout, and this skill implements its next unfinished phase. Putting a spec in
 flight — provisioning, moving it to `in-progress`, getting its branch here — is
@@ -13,7 +18,36 @@ flight — provisioning, moving it to `in-progress`, getting its branch here —
 
 ## 1. Identify the spec in flight
 
-Resolve **in this order**, and stop at the first that answers:
+**`--worktree <path>` answers before anything else.** When the invocation names a
+worktree, that is the spec to build and that is where it is built — cwd is not
+consulted. It is how `/spec-start` carries on into phase 1 without moving your
+session, and you can type it yourself.
+
+**This is not a loosening of the refusal below.** That refusal exists against
+*guessing* which spec to build, and a path someone typed is not a guess. A bare
+`/spec-next` still refuses exactly as it does today.
+
+**Validate the path before writing a line into it.** Run the resolver *from* the
+path, so the answer comes from where you are about to write:
+
+```
+cd "<path>" && skitterspec spec-env resolve
+```
+
+Check the `worktree:` line it prints is that same path. If it is not — or the
+command reports that isolation is not enabled — refuse and stop, naming what you
+were given. A path that is not a provisioned worktree must never become a place
+to write code.
+**Read the output, not the exit status** — it exits 0 even when it
+cannot resolve anything.
+
+**Not `--dir <path>`.** That flag sets the **repo root**, not the worktree to
+resolve from, so it answers a different question: on a repo with two or more
+worktrees it refuses with *"no spec given, and N specs have worktrees"* and
+validates nothing at all. The `cd` form is what makes the path itself the
+evidence.
+
+Otherwise resolve **in this order**, and stop at the first that answers:
 
 1. **The live spec of this checkout** — run
    `skitterspec spec-env live status` and read its `live:` line. `live: yes`
@@ -24,15 +58,60 @@ Resolve **in this order**, and stop at the first that answers:
    opened in one is its own workbench.
 3. **The current branch, in `checkout` mode** — no worktrees exist, so the
    branch the checkout is on names the spec.
+4. **The only spec provisioned in this repo** — ask the engine, with no spec
+   named, from wherever you happen to be standing:
+
+   ```
+   skitterspec spec-env resolve
+   ```
+
+   Take its `spec:` line **only when it names exactly one spec**.
+
+   This is the **durable** rung, and that is the whole reason it exists. Rungs 1
+   to 3 all read *session* state, and session state does not survive a `/clear`,
+   a new terminal tab, or coming back tomorrow — while the provisioned worktree
+   they are each a proxy for is **on disk** and survives all three. `/spec-start`
+   does leave the session standing in the worktree and that `cd` is real; what it
+   is not is durable. Without this rung, a repo holding exactly one answer sends
+   the operator away to re-supply something it already knew.
+
+   It is also the resolution every other bare command in this workflow already
+   uses — the worktree you are standing in, else the sole provisioned spec — so
+   this rung is what stops `/spec-next` being a silent exception to a rule
+   `.claude/rules/spec-planning.md` states has none left.
+
+   **Say which spec you resolved and how**, before writing a line of it:
+   *"not standing in a worktree — `<spec>` is the only spec provisioned"*. Rungs
+   1 to 3 are self-evident to whoever typed the command; this one is not, and
+   the operator cannot see from where they sit what you picked.
+
+   **Several worktrees stay a refusal.** The engine names them and resolves
+   nothing — exactly the ambiguity the refusal below exists for. Relay its list
+   unchanged and stop; never pick from it.
+
+   WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is still
+   a worktree, so a finished spec can go on counting as provisioned. That widens
+   the candidate set, so the failure it produces is an extra candidate — an
+   ambiguity the engine refuses on — and never a wrong spec built. It cannot
+   manufacture an *absence*, which is why the absence below is still worth
+   refusing on.
 
 **If none answers, refuse and stop:**
-`no spec in flight — run /spec-start <name> to put one on this checkout`.
+`no spec in flight — run /spec-start <name> to start one`.
+
+That now answers a real absence — no worktree anywhere, the engine included —
+rather than a session that merely lost track of where it was standing.
 
 **Never fall back to the spec "in context".** A spec discussed in conversation
 is not a spec in flight, and this skill writes real code: building the wrong
 spec's phase produces commits on a branch nobody asked for. The refusal is
 cheap; the mistake is not.
 
+**Rung 4 is not that fallback wearing a hat.** A provisioned worktree is a
+record that someone ran `/spec-start`: it is on disk, the engine reads it, and it
+either names one spec or refuses. A spec named in conversation is a guess about
+intent with nothing underneath it, and no number of them ever resolves to one.
+
 A **name argument** is accepted, but it must *match* the spec in flight — it
 narrows a re-run, it does not select a different spec. A mismatch refuses,
 naming both.
@@ -63,6 +142,33 @@ once it is over. Without a provider this is a no-op and nothing below changes.
 
 
 
+**Before building, compare the worktree against where you are standing.** Take
+the `worktree:` line from `skitterspec spec-env resolve <spec>` and compare it
+with this session's cwd, resolving both paths first so a symlinked or
+trailing-slash spelling of one tree does not read as two.
+
+Same tree — the ordinary case, since `/spec-start` leaves the session standing
+in it — and the rest of this step is inert.
+**Different trees, and the discipline below applies however the spec was resolved.**
+`--worktree <path>` is one way to get here and §1's rung 4 is another: a bare
+`/spec-next` typed from the primary checkout resolves the sole provisioned spec
+and builds it somewhere this session is not. What makes the discipline necessary
+is the two trees, so that is what it is conditioned on — not the shape of the
+invocation, which cannot see rung 4 at all.
+
+Record the baseline before you write anything:
+
+```
+skitterspec spec-env resolve <spec> --record-primary
+```
+
+Then build as below, with one discipline on top.
+**The session is not standing in the worktree**, so every write takes an
+absolute path under it and every command
+is prefixed `cd "<worktreePath>" &&` — typecheck and tests included. A single
+relative path lands the work in the primary checkout, on the base branch, and
+nothing about it looks wrong at the time. Step 4b is what catches it.
+
 Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
 
 - Work task by task through the phase file. Make focused edits that match
@@ -91,8 +197,184 @@ a mirror lag a whole spec behind. Without a provider this is a no-op.
 
 
 
-## 5. Report
+## 4b. Prove nothing leaked into the primary checkout
+
+**Only when the resolved worktree is not this session's cwd** — the same
+comparison step 3 made, and it holds however the spec was resolved. Standing in
+the worktree there is no second tree to have written into, so this step does not
+apply and there is nothing to check.
+
+WHAT WOULD FOOL THIS CHECK: it watches the **primary checkout** and nothing
+else, so a build run from inside *another* spec's worktree would leak there
+unseen. That is left unhandled deliberately rather than overlooked — reaching it
+takes an explicit `--worktree` typed from a second worktree — and the cost of the
+gap is a missed leak, never a false accusation.
+
+The phase is built and its progress recorded — all of it written into a tree this
+session is not standing in. Before reporting any of it as done:
+
+```
+skitterspec spec-env resolve <spec> --assert-primary-clean
+```
+
+- **Exit 0, "primary checkout clean"** — carry on.
+- **Non-zero** — stop and relay the engine's message unchanged. It names the
+  paths and both readings: this build wrote them and they belong in the worktree,
+  or something else did and the baseline wants re-recording.
+  **Do not guess which, and do not delete anything.**
+  A path that appeared is not proof of who put it there.
+- **"cannot tell"** — no baseline, or one from another spec. It exits 0 and
+  claims nothing; say so in one line and carry on. An absence is not evidence.
+
+## 5. Render the page — then offer the review, never write it
+
+**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.
+
+The phase is built, its tests are green, and nothing is committed yet. That is
+the moment the page is about, so render it now — **after** the tests pass and
+**before** the commit:
+
+```
+skitterspec spec-env review <spec>
+```
+
+**This is free.** It is the engine reading git and splicing text into a template;
+the diff never passes through you, so a 266KB patch costs nothing. Report the
+path it prints and move on.
+
+**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.
+
+**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.
+
+**Non-blocking, deliberately.** Do not end your turn waiting on the answer.
+Phases get chained — `/commit && /spec-next` typed as one line — and a question
+that stops the run taxes every phase to fix a problem the row already fixes.
+
+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.
+
+- **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. 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.
+
+- **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.
+- If the project has no isolation config, skip the whole step in silence rather
+  than explaining an absence.
+
+## 6. Report
+
+Do **not** `git commit` unless the user asks — finish, verify, and wait.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the phase is built and its tests are green.
+- `⚠️` — built and green, with something worth knowing (a mirror that did not
+  refresh, a deviation from the plan).
+- `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
+- `⏸` — no spec in flight, or the name given does not match the one that is.
+
+**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Snags` · `Review` ·
+`Follow-ups` · `Next`
+
+## 6a. End in a picker
+
+The block says what happened; this is what to do about it. Offer the same four
+endings the review page carries, so a review finishes the same way wherever the
+reader is standing — the page, a pasted code, or here.
+
+| Option | Does |
+|--------|------|
+| `Reviewed` | Claims the waiting pass and routes on its verdict |
+| `Commit` | Runs the project's commit skill, and stops |
+| `Commit & Continue` | Commits, then `/spec-next` — and **stops there** |
+| `Discuss` | Asks what is up; changes nothing |
+
+**`Reviewed` only when a pass is actually waiting.** The render's `pending:`
+block already says. Offering a pickup with nothing to pick up is the empty
+gesture this exists against — the other three stand on their own.
+
+**Do not restate the routing.** `/spec-diff` §2, §2a and §4 own it, including
+the commit hand-off through `review.commitWith` and what `commit-continue` does
+after. Two copies of a routing rule is how the two come to disagree.
+
+**It does not break a chained run.** `/commit && /spec-next` is typed as one
+line and the picker appears at the **end**, by which point the chain has already
+finished. The cost that was feared here — a question stopping a run mid-way — is
+not a cost this placement has.
+
+**Nothing may claim a pass without a pick.** `/spec-reviewed` is user-only by
+*harness enforcement*, because prose alone once failed to stop an agent claiming
+a pass nobody asked it to. A pick keeps the **property** that makes that safe —
+a person in the conversation chose, and a device that reaches the page cannot —
+while routing around the **mechanism**, since the claim runs downstream of the
+pick. That trade is deliberate and it has exactly one condition: a run that
+shows no picker claims nothing, and a picker nobody answered claims nothing.
+
+WHAT WOULD FOOL THIS: a picker shown reflexively at the end of every run trains
+the reader to dismiss it, and a dismissed picker is indistinguishable from a
+considered decline. So offer it where there is a real choice, and let the `Next`
+row carry the rest.
+
+`Next` names the commit and then the phase, as
+`/commit, then /spec-next → phase 3 (Auth)`, so the block says what to do and
+which phase is next without a line of prose for either.
+
+**The commit is not optional politeness.** Step 6 above deliberately leaves the
+phase uncommitted, and §2 of this very skill refuses to build the next phase on
+top of an uncommitted one — so a `Next` that names only `/spec-next` sends the
+reader straight into that refusal. The two halves are four hundred lines apart,
+which is exactly how they drifted.
 
-Summarise what was implemented, the test result (quote failures if any), and
-which phase is next. Do **not** `git commit` unless the user asks — finish,
-verify, and wait.
+**Step 5's offer is the `Review` row.** It is not a paragraph after the block,
+because nothing is after the block: the counts, the page link and the question
+go in one row, above `Follow-ups` and `Next`. Step 5 renders before the commit
+and this step is where its offer lands, so the two must not disagree about where
+it goes.