@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

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

@@ -0,0 +1,218 @@
+---
+name: spec-list
+description: List every spec Linear holds — id, title, workflow state, who holds it, and the local spec folder name to paste into /spec-start. Read-only, and it starts nothing. Falls back to the repo's own listing when Linear is unreachable. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-list", "what specs are there", "what is in the backlog", "what is Jane working on", or "list specs from Linear".
+disable-model-invocation: true
+---
+
+# /spec-list — every spec Linear holds
+
+> 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.
+
+Read-only. It answers a question and writes nothing — no branch, no folder move,
+no Linear write.
+
+Why ask Linear rather than `ls specs/`? Because `/spec-start` moves a spec to
+`specs/in-progress/` **on that spec's own branch**. On the base branch an
+in-flight spec still reads `backlog`, and a teammate's unlanded spec is not on
+disk at all. Linear knows what is actually in progress and who holds it; the repo
+knows what each issue is **called on disk**. The listing joins the two.
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync (`/spec-linear-setup`) and stop.
+
+## 1. Turn the question into flags
+
+The user asks in plain language; the engine takes flags. Map, then run:
+
+| They ask | Flags |
+|----------|-------|
+| "what specs are there", "/spec-list" | *(none — the live default)* |
+| "what's done", "everything" | `--all` |
+| "what's cancelled", a named state | `--state "<name>"` (repeatable) |
+| "what's next", "the next few in the backlog" | `--next N` |
+| "what am I on", "assigned to me" | `--mine` |
+| "what is Jane on", "Jane's specs" | `--by "Jane"` |
+| "what's in flight", "what's being worked on" | `--in-progress` |
+| "just the first few" | `--limit N` |
+| "include the archived ones" | `--archived` |
+
+The default scope is **live** — whatever `config.states` maps `backlog` and
+`in-progress` to. It is deliberately not everything: in a workspace with any
+history, Done dwarfs the rows anyone wanted.
+
+`--mine` and `--by` filter by assignee and stack with any one scope flag —
+`--next 5 --mine` and `--in-progress --by "Jane"` both read naturally. The scope
+flags themselves (`--state`, `--all`, `--next`, `--in-progress`) are
+**alternatives**, and the engine refuses any two of them rather than letting one
+win silently.
+
+`--next N` is **backlog-only and ordered**, so it does not combine with
+`--state` or `--all`; the engine refuses that pair rather than picking a winner.
+It reproduces Linear's own Backlog order — priority first, then the manual
+drag-order — and when nothing is prioritised it says so, because that order is
+then a person's arrangement rather than a ranking.
+
+## 2. Run the engine
+
+```
+skitterspec spec-sync list [--state <name> …|--all] [--limit N] [--archived] [--json]
+```
+
+- **`transport = api`** (a key is set) → it queried Linear and printed the
+  listing. **Relay its output verbatim** and stop. Do not re-format it and do not
+  make Linear calls of your own — the engine already joined the local spec
+  folders on.
+- **`transport = mcp`** → the engine made no call. Go to step 3.
+- Anything else it prints on one `spec-sync list:` line is a **degradation**, not
+  a crash — go to step 4.
+
+**These two failures are not the same, and the engine says so.**
+Relay the difference rather than flattening it. `--mine` when nobody can say
+who you are (a shared or bot key, an offline machine) is an ordinary state: it
+prints one line, lists nothing and exits 0. `--by "someone"` that matches no
+user, or matches several, is a wrong argument: it lists the candidates or says
+there are none, and exits non-zero. Neither ever falls back to the whole team —
+a heading promising one person's work over everyone's is the failure both are
+written to avoid.
+
+## 3. The MCP path
+
+Only when the engine said `transport = mcp`. Discover the issue **list** tool at
+runtime the way `/spec-push` describes (`list_issues`). If Linear isn't connected
+or the tool is missing, go to step 4 — do not stop with nothing.
+
+Then, per state you are listing:
+
+- **One call per state.** The tool's `state` takes a single state name, not a
+  list, so the live default is **two** calls (`backlog` and `in-progress` from
+  `config.states`). Merge the results and de-duplicate by identifier.
+- **Ask for the fields you print** — `fields: ["title", "status", "assignee",
+  "url", "parentId"]`. `parentId` is not optional: it is the discriminator in the
+  next bullet, and it is absent from the default response.
+- **Filter out phase sub-issues yourself.** The tool can filter *to* a parent
+  (`parentId`) but has no "parentless" filter, so **you** must drop every issue
+  that came back carrying a `parentId`. A spec issue has none; a phase sub-issue
+  does.
+- **Page, and never cap silently.** `limit` defaults to 50 and maxes at 250;
+  follow `cursor` until it runs out. If you stop early, say so on its own line
+  and say what you stopped at.
+- Pass `includeArchived` only when the user asked for `--archived`.
+- **Assignee needs no identity lookup here.** The tool takes `assignee` as a
+  user id, name, email **or the literal `"me"`** — so `--mine` is
+  `assignee: "me"` and `--by "Jane"` is `assignee: "Jane"`. Do **not** call
+  `spec-sync whoami` on this path; it exists for the API path, which needs an
+  id. If the name matches nobody, say so and list nothing.
+
+**`--next` cannot be fully reproduced over MCP, and you must say so.** The tool
+returns `priority` as a field, so order by that; but `sortOrder` — Linear's
+manual drag-order — is **not among the fields it can return** at all, and its
+`orderBy` offers only `createdAt` and `updatedAt`. So within one priority you
+are printing Linear's default order, not the Backlog order. Say that on its own
+line rather than letting the rows imply an order they do not have:
+
+```
+sortOrder is unavailable over MCP — within a priority these are in Linear's
+default order, not the Backlog drag-order. Set a Linear API key for the real one.
+```
+
+**The current phase, on in-progress rows only.** For each row whose state is the
+in-progress one, call the list tool again with `parentId` set to that issue and
+`fields: ["title", "status"]`. Order the children by **identifier**, numerically
+— `sortOrder` is unavailable here for the same reason it is under `--next`, and
+sub-issues are minted in phase order, so the identifier carries it. Print the
+live one as `2/5 — <title>`. Three shapes, none of them guessed at:
+
+- **No child in progress** — print nothing extra. A spec sits between phases all
+  the time; that is not a missing phase.
+- **More than one** — print the lowest-numbered, then append
+  `(+N more in progress)`. Two people on one spec is real, not an error.
+- **`mapping.phases` is `inline` for this spec's bucket** — skip the call
+  entirely. Those phases live in the spec issue's own description, so there are
+  no children, and asking would report "no phase in progress" for a spec that is
+  mid-build.
+
+Do **not** make this call for backlog, done or cancelled rows — one lookup per
+in-progress row is the budget, and there are rarely many.
+
+Then join locally — no second Linear call:
+
+```
+skitterspec spec-sync linked --json
+```
+
+That is `[{ spec, bucket, identifier }]`. Key it by `identifier` and attach each
+issue's local `spec` folder name. Format the rows exactly as the API path does
+(step 5), including the archived-exclusion line and the `showing N of M` count.
+
+## 4. Degrade — never leave them with nothing
+
+Linear unreachable, no credential, no MCP tool, a Linear error: **do not stop**.
+Print the local listing instead:
+
+```
+skitterspec spec-sync linked --json
+```
+
+Show `spec`, `bucket` and `identifier`, under a one-line banner naming what is
+missing and why it may be wrong:
+
+```
+Linear unreachable (<reason>) — this is the repo's own listing.
+Buckets are this branch's; a spec someone else has started still reads "backlog" here.
+```
+
+That caveat is the point of the banner. A local bucket is not evidence of a
+spec's real state — it is evidence of what this branch knows, which is exactly
+what the command exists to go beyond. A query command that fails closed is one
+people stop typing.
+
+## 5. Report
+
+Relay the listing. Whatever the path, three things must survive into what the
+user reads:
+
+- **The count, as `showing N of M`.** If they are not the same number, say what
+  was left out and how to see it.
+- **The archived line.** Excluded by default, and said so — a blind spot named
+  rather than left to be discovered.
+- **The phase, on in-progress rows** — `2/5 — <title>`, after the assignee.
+- **A row with no local match stays in**, marked `— (not linked here)`. It is not
+  noise: a teammate's unlanded spec, or one authored inside another spec's
+  worktree, is precisely what the repo could not have told them.
+
+Finish with the hand-off, because every row carries the folder name for it —
+as a sentence, not a fenced block: say that `/spec-start <name>` starts any of
+them, with the name copied from a row.
+
+**Never start it yourself.** `/spec-start` provisions a branch, moves a folder
+and commits, and it has dirty-tree refusals this skill does not reproduce.
+Offering the name is the whole job.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**The listing goes above the block, unflattened.** It is rows of other people's
+work; the block is the verdict on this run of the query. Do not fold the listing
+into fields, and do not repeat it there.
+
+**Verdicts**
+
+- `✅` — the listing is Linear's, joined to the local folder names.
+- `⚠️` — listed, with a caveat that changes how the rows read: a paging cap you
+  stopped at, or `sortOrder` unavailable over MCP so `--next` is not really
+  Backlog order.
+- `⏸` — `--mine` with no identity available. It lists nothing and that is an
+  ordinary state, not a failure.
+- `❌` — the query was wrong: `--by` matching nobody or several, or two scope
+  flags together.
+
+**Fields:** `Follow-ups` · `Next`
+
+**No `Tracker` row.** This skill names many specs and owns none, so an id row
+would have to pick one. The counts — `showing N of M` — and the archived
+exclusion belong to the listing above, where the engine already prints them.
+
+`Next` is the hand-off: `/spec-start <name>`, with a name copied from a row.

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.
@@ -79,6 +158,17 @@ once it is over. Without a provider this is a no-op and nothing below changes.
     them. Skip it and a started spec stays mirrored as a phase-less issue.
 - **Never mint the spec issue.** An unlinked spec is skipped, not created —
   `/spec-push` is how someone opts in.
+- **Backfill a missing assignee silently; never ask.** Only when
+  `sync.fieldOwnership` includes `assignee`. If the spec records nobody and
+  `skitterspec spec-sync whoami --json` answers, stamp it with
+  `skitterspec spec-sync assign <spec> --to <id> --name "<name>"` and let the
+  push above carry it. If identity is unknown, skip it in silence.
+  **Do not prompt**: an assignment question in the middle of a build is an
+  interruption with no deadline, and `/spec-claim` answers it whenever the
+  operator likes.
+- **A spec assigned to someone else is left alone.** Say so once
+  (`assigned to <name> — /spec-claim to take it`) and change nothing. Picking up
+  a colleague's spec is a decision, not a side effect of running the next phase.
 - **Never fatal.** If the push fails — offline, no key, a Linear error — say so
   and **carry on with the build**. The repo is correct regardless; the mirror is
   disposable and the next push repairs it.
@@ -89,6 +179,33 @@ once it is over. Without a provider this is a no-op and nothing below changes.
   branch/PR you pushed in step 2; that's expected and the repo still wins on the
   next `/spec-push`.
 
+**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
@@ -134,8 +251,184 @@ sub-issue jump from Backlog straight to Done, with nothing visible in between.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
 
-## 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.