@skitterbyte/skitterspec 17.0.0 → 19.0.0

package/assets/rules/spec-planning.md

@@ -1,6 +1,6 @@
 # Spec Planning
 
-Spec-driven development is driven by nine lifecycle skills (plus the
+Spec-driven development is driven by ten lifecycle skills (plus the
 `/spec-connect` and `/spec-live` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
@@ -11,8 +11,9 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
 | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-start` | Put a spec in flight on this checkout, then build phase 1 | `In Progress` | `specs/in-progress/` |
-| `/spec-next` | Build the next phase of the spec in flight (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
+| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
+| `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
+| `/spec-reviewed` | Pick up a review approved on the page — offered by its code, claimed on your word | (unchanged) | (unchanged) |
 | `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
 | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
 | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
@@ -22,9 +23,17 @@ and lifecycle stay consistent. Each sets a status on the spec header
 exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
 (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
 relays its output, so there is no judgment to apply and no model turn spent
-finding one. They are marked `disable-model-invocation`, meaning **only you can
-run them** — a skill that wants one will tell you to type it rather than invoking
-it.
+finding one. They are marked `disable-model-invocation`, meaning
+**only you can run them** — a skill that wants one will tell you to type it
+rather than invoking it.
+
+`/spec-reviewed` is a **skill** and **user-only**, and there the marking is not
+convenience — it is the enforcement of `/spec-diff` step 0's rule that a waiting
+review pass is never claimed unasked. A pass can be POSTed by anything that
+reaches the page; what it cannot reach is the conversation. Because the model
+cannot invoke this skill, a pass is only ever picked up because a person typed
+the command, and typing it **is** the human signal. Prose alone did not hold
+that line once already.
 
 `/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
 real judgment (green tests before a land; an MCP fetch and a team-key check; ten
@@ -44,10 +53,15 @@ mid-spec (so the work can run in CI / a shared test env) while the spec stays
 
 **Two workspace modes.** `specs/.core/env.config.json` → `mode` decides where a
 spec's branch is built. **`worktree`** (the default) gives each spec its own
-checkout — several specs at once and `main` left free, at the cost of one
-terminal session per spec, which `/spec-start` sets up for you. **`checkout`** builds
-the branch in the primary checkout instead: one spec at a time, but no second
-session and no hand-off, so the terminal you are already in follows the work.
+checkout — several specs at once and `main` left free. `/spec-start` builds the
+branch there, **moves your session into it** with a plain `cd`, and then asks:
+build phase 1 now? Say yes and it carries on into a bare `/spec-next`; say no and
+you are already standing in the worktree, so `/spec-next` typed later does the
+same thing. The primary checkout stays on the base branch throughout — the
+session followed the spec, nothing was checked out anywhere.
+**`checkout`** builds the branch in the primary checkout instead: one spec at a
+time, nowhere else to stand, and the build always carries straight on.
+The difference is how many specs can be in flight at once.
 Pick it for how you work rather than for what the project contains — a repo with
 no dev servers may still want several specs in flight. In `checkout` mode
 `/spec-connect` and `/spec-live` do not apply and say so: both exist to reach
@@ -67,8 +81,11 @@ your canonical `localhost` ports so you can test it at the normal URL
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|down|prune|dev|connect|integrate|hotfix|live|status|resolve>` is the CLI
-engine (omit the spec name and it uses the worktree you are standing in). Teardown drops
+<up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
+engine. **Omit the spec name anywhere and it uses the worktree you are standing in**,
+else the sole provisioned spec — with no exceptions left: a bare
+`/spec-connect` connects, and a bare `/spec-live` takes, where both once meant
+`main`. Teardown drops
 the finished spec's own test-DB volume; `spec-env prune` additionally reaps
 **orphaned** volumes left by declined/aborted teardowns, so `/spec-complete` and
 `/spec-cancel` also sweep orphans (confirm-first). A **hotfix** is the one
@@ -80,17 +97,172 @@ when `env.config.json` is absent — every skill then behaves as it does today.
 **Live overlay (`/spec-live`, a command) — the light way to test a spec.** `/spec-connect`
 runs a spec's *own* dev stack and proxies the canonical ports to it (one stack per
 spec). **Live overlay** instead reuses the one dev server you already have running:
-`/spec-live <spec>` rebases the branch onto base, frees it from its worktree, and
+`/spec-live <spec>` — or a bare `/spec-live`, which takes the spec you are
+standing on — rebases the branch onto base, frees it from its worktree, and
 checks it out **in the primary checkout**, so your running server hot-reloads the
-feature at the normal URL — no second stack, no proxy. The branch checked out in
+feature at the normal URL — no second stack, no proxy. Bare only acts when there
+is exactly one answer *and* the workbench is free; anything else prints the
+status report rather than guessing. The branch checked out in
 the primary checkout **is** the lock: exactly one spec is live at a time, and
 `/spec-live main` hands the instance back (fixes you make while live commit
 straight onto the branch; `/spec-complete` is live-aware and lands them). Rule of
-thumb: **live overlay is the light default for code-only specs**; it *refuses*
+thumb: **live overlay is the light default for *testing* a code-only spec** — it
+is not how work gets started, and no lifecycle skill invokes it; it *refuses*
 stateful ones (`Stack: worktree + docker`, or a branch touching migrations) — keep
 `/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
 Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
 
+**Staging one spec and not another (`spec-env stage`).** Several specs are
+authored at once — that is what the worktree mode is for — and they all land in
+the same `specs/` folder until they are committed. A `git add specs/` there
+stages a *directory*, sweeping whatever another session happens to have written
+into this spec's commit, under this spec's ticket trailer.
+`skitterspec spec-env stage [<spec>] [--json]` is how a skill asks instead of
+guessing: it splits the uncommitted tree into the paths that are this spec's —
+its folder in **any** bucket, so a tree mid-`git mv` is handled, plus each
+`spec.companionPaths` entry the project declares — and the paths that are not.
+It reads **the tree you are standing in**, which is the worktree inside one and
+the primary checkout outside, and prints which. The `owned` half is the spec's
+**documents**, never its code: a phase's own implementation is `foreign`, because
+the commits this bounds are the lifecycle ones. Nothing here refuses, writes, or
+exits non-zero — `foreign` is a list of paths to leave alone, not an accusation.
+
+**Naming the paths is necessary and not sufficient**, which is why every spec
+commit is also pathspec-limited: `git add -- <paths>` **and**
+`git commit -m "…" -- <paths>`. A checkout has one `.git/index` and every session
+standing in it shares that index, so a bare `git commit` takes whatever another
+session has already staged no matter how carefully this one staged its own. The
+`add` is still needed — `git commit` cannot take a path git has never seen, which
+is every brand-new spec folder — but it is the `--` on the **commit** that bounds
+what lands. The two failures are different and the fix needs both halves.
+
+**Reading a spec's diff (`/spec-diff`) — seeing the work, not running it.**
+`/spec-connect` and `/spec-live` both exist to reach a *running app*.
+**`/spec-diff`** answers the other question: what did this actually change? A
+phase is built in its own worktree, so `git diff` in your terminal answers about
+the base branch — and a 350-line diff read as terminal text is scrolling, not
+review. The engine collects the worktree's changes with `git -C` and writes a
+self-contained HTML page (`.spec-env/reviews/<spec>.html`, gitignored) with
+whole-file context that folds away, a file tree, and new files included. You open
+it locally, or publish it and read it on a phone.
+**The diff never passes through the model**, so the page is free to produce
+however large it is; the *written*
+review — a short read plus `flag`/`confirm`/`good` notes — is the part that costs
+tokens, and it is offered rather than assumed. It is a **skill**, model-invocable,
+and it is gated on nothing: half a phase, a hand edit and a colleague's branch are
+all ordinary inputs. `/spec-next` renders the page at the end of a phase and
+offers the review; `skitterspec spec-env review <spec> [--branch]` is the engine.
+
+**The page is not read-only — it takes a review pass back.** Tick `✓ accept` per
+file as you read, write notes against a line or a whole file, answer the
+questions a written review asked, then **end it in a decision** and hand it
+back. Three buttons, each carrying its own verdict:
+**`✓ Approve`** (commit it), **`↺ Request changes`** (work them now),
+**`… Discuss first`** (report and talk). `/spec-diff` stores it (`--notes`),
+plays back what it read, and routes on the verdict — `changes` **is** the
+go-ahead, so it works the commented files immediately, while `discuss`, a
+refused approval and a pass carrying no verdict at all report and wait, which
+is what a bare paste has always done. Accepted files stay unopened either way.
+
+**Two ways back, and both are ordinary.** A **served** page POSTs the pass to
+its own URL; the engine holds it in a gitignored `.pending.json` beside the
+notes sidecar and answers with a **six-digit code**. Read the code out and
+`/spec-diff` claims it (`--claim`), merging exactly the pass that code names.
+A `file://` page has no server to talk to — the File System Access API is
+Chrome-only and absent on iOS Safari — so it copies to the clipboard and you
+paste, exactly as before. The clipboard path is **not legacy**: it is the whole
+story for a local reader.
+
+The code is **not a secret** — it is printed on the page, and it cannot be a
+gate against Claude either, because the store is a file Claude can read. What
+actually holds is narrower and stronger:
+**a device that reaches your page cannot reach your conversation.**
+So a pass it queues sits in the holding area
+forever, and the rule that keeps it there is that
+**Claude never claims a pass it was not asked to** — stated in `/spec-diff` step
+0, because nothing enforces it.
+
+What the code *does* is let you **tell two passes apart** — it is an address,
+never a password. One waiting pass is claimed and acted on the moment you type
+`/spec-reviewed`, with nothing read back: the round-trip verified *which* pass
+in a design where the page pushed and the agent went looking, and that design is
+gone. Two waiting is a refusal to guess — the one case where a stranger's pass
+sits beside yours, and the one case where six digits are worth anyone's time.
+Pasting the code (`/spec-reviewed 324199`) skips even that. A pass you disown is `--drop <code>`; left there it is reported on every
+render until you stop reading the line.
+
+A code that matches nothing refuses, **names nothing**, and never falls back to
+"the only one" — that fallback is precisely what would let an unread pass
+through. Claiming **consumes**: a code works once. A second pass from the same
+page render supersedes the first, so the code on screen is always the pass on
+screen; passes from different renders stand alongside each other.
+
+**And a claimed pass never enters the model's context.** The engine holds it,
+merges it, and reports the counts — six digits is what reaches Claude, where a
+pasted blob costs context in proportion to how much you wrote. That is the same
+rule the diff already follows, applied to the one place it used to break. What it did comes back as a **resolution** (`--resolve`),
+so the next render shows each note struck through with a one-line account and you
+verify the fix instead of trusting it. An accept is keyed to the file's
+**content hash**, so it survives the commit that ends the phase and lapses by
+itself when that file changes again — announced as `accepted earlier — changed since`, never
+silently. All of it lives beside the page in gitignored `.spec-env/`, and
+**the marks are information, never a gate**: nothing counts them and nothing
+refuses on them.
+
+**The verdict is chosen, never derived.** A verdict is one person's conclusion,
+sent once per pass; a counting gate is a refusal computed from how many boxes
+are ticked, and it stays forbidden. The one refusal here is not a count of
+ticks: **committing** is unavailable while any **comment** is unresolved,
+because you asked for something and it therefore cannot also be fine. Files you
+never ticked block nothing — an unticked file is something you said nothing
+about, and requiring every one of them would be the tally this design exists to
+avoid.
+
+**The verdict names the action**, and that is why it is `commit` rather than
+`approve`: a review is the guard in front of an action, and an approval that
+only recorded itself was the one control on the page that did not describe what
+it does. Both committing verdicts hand off to the project's own commit skill
+(`review.commitWith` in `env.config.json`, `/commit` by default) — skitterspec
+never vendors one, because `/commit` belongs to skittership.
+**There is no off switch**: `"none"` existed and was removed, since it produced
+exactly the record-and-do-nothing verdict this design is against.
+`Commit & Continue` then runs `/spec-next` and **stops there** — it never
+completes, lands or tears anything down.
+
+A verdict is **consumed**, not stored: a commit verdict is spent by the commit
+and a changes one by the work, so neither can go stale and later act on
+something nobody read. What survives is a one-line outcome log, shown on the
+next render as history.
+
+**One ending, every skill (`.claude/rules/spec-reports.md`).** Every skill in
+the table above finishes with the same block — a verdict, then a table of only
+the fields that skill declares — and says nothing while it runs beyond a
+question it cannot answer itself or a failure at the moment it happens. The
+shape is defined once in that rule; each skill's `## Report` section names only
+its verdicts and its fields.
+
+✅ **Phase 2 built** — `feat-orders`, 2 of 4
+
+| | |
+|---|---|
+| **Tracker** | [ABC-88](https://example.invalid/ABC-88) · `feat-orders` · phase 2 moved |
+| **Branch** | `spec/feat-orders` · 3 commits, clean |
+| **Built** | POST /orders handler, orders schema |
+| **Tests** | 128 passed · npm test |
+| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Follow-ups** | none |
+| **Next** | `/spec-next` → phase 3 (Auth) |
+
+Four verdicts, and the last two are different facts about the repo: `✅` done ·
+`⚠️` done with caveats · `❌` failed part-way, so there is a mess to clear ·
+`⏸` refused before acting, so nothing changed.
+**A refusal emits the block too** — "nothing happened" is a reported outcome
+rather than an absent one.
+`Follow-ups` is always present, because a recorded `none` is a decision where a
+missing line is an oversight. And the block covers **that run only**: what else
+is in flight is another question, and volunteering it here leaves the reader
+unable to tell what followed from the run they just watched.
+
 **Ticketing-provider sync (opt-in, a separate package).** The base is
 tracker-free: it knows nothing about any specific ticketing system. A
 ticketing provider is installed as its own distribution that plugs into named
@@ -109,6 +281,24 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
 workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
 the tracker is never read back or merged.
 
+A provider may also ship a **read-only listing** of what the tracker holds. That
+is not a pull: nothing is merged back and no spec file is written. It exists
+because the folder buckets are only the truth *on the branch you are standing
+on* — `/spec-start` moves a spec to
+`specs/in-progress/` on that spec's own branch, so on the base branch an
+in-flight spec still reads `backlog` and a teammate's unlanded spec is not on
+disk at all. The tracker knows both, and each row carries the spec's folder name
+so `/spec-start <name>` is a copy-paste away. See the provider's own docs for
+what it calls the command.
+
+A provider may also mirror **who is building a spec**, as one more field the repo
+owns. Where it does, `/spec-start` records the developer and the tracker's ticket
+is assigned to them, the assignment is released when the spec completes, and
+`/spec-claim` moves ownership mid-flight — take it, hand it back, or hand it to a
+teammate. Like everything else here it is opt-in and one-way: the spec file is
+the record, and the ticket is the mirror. See the provider's own docs for how to
+turn it on.
+
 **Every skill that moves a spec through the lifecycle carries a seam**, so the
 mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
 `/spec-hotfix` link the spec they create; `/spec-next` refreshes it as work starts;
@@ -118,6 +308,21 @@ With no provider installed the seams are empty and every skill behaves as a plai
 filesystem workflow. See the provider package's own docs for its config and field
 reference.
 
+**Release gating (opt-in, config-gated).** With
+`specs/.core/gating.config.json` present, every spec `/spec`, `/spec-bug` and
+`/spec-hotfix` write carries a `> **Gating:**` header recording one decision:
+does this ship behind a feature flag, or land live? The value is a **flag name**,
+or **`none: <one-line reason>`** — and the reason half is the load-bearing part,
+because `none: additive, nothing to revert` is a decision a reviewer can argue
+with while a bare `none` is a shrug and a missing line is an oversight.
+
+Skitterspec bakes in **the offer, never the mechanism**: it asks, cites the
+project's own doc (`guidance` in that config), and records the answer. It never
+reads your flag code. `skitterspec gating check` reports specs with no decision
+and **always exits 0** — it reads only `backlog/` and `in-progress/`, so specs
+finished before you adopted gating are out of range by construction. With the
+config absent nothing appears at all: no question, no header, no check.
+
 ## Project conventions (fill this in)
 
 The spec skills tell you to run "your project's typecheck and test commands" and
@@ -160,6 +365,10 @@ Every spec header carries:
   to `git config user.name`).
 - `> **Developer:**` — who implements it (`—` until `/spec-start` starts work, then
   set to `git config user.name`; `/spec-bug` sets it immediately).
+- `> **Gating:**` — the release-gating decision,
+  **only when `specs/.core/gating.config.json` exists**: a flag name, or
+  `none: <one-line reason>`. Absent entirely in a project that has not adopted
+  gating.
 
 Every spec also has a **State log** table — the audit trail of folder/status
 transitions. Each lifecycle skill appends exactly one row when it changes state:

package/assets/rules/spec-reports.md

@@ -0,0 +1,269 @@
+# Spec Reports
+
+Every lifecycle skill ends with the same block. This file is its whole
+definition — a skill's `## Report` section names only which fields it emits and
+any behaviour that was always there.
+
+Two things it buys: a run's outcome is scannable in one shape rather than
+composed fresh each time, and "nothing happened" becomes a reported outcome
+instead of an absent one.
+
+## Silence during the run
+
+**Do not narrate.** Not what you are about to do, not why, not which step you
+are on. The tool calls are already on screen, so a line per step re-states the
+transcript in words that never vary.
+
+Speak mid-run for exactly two reasons:
+
+- **A question you cannot answer yourself** — a decision the spec left open, a
+  confirmation a guard demands, an ambiguity with more than one defensible
+  answer.
+- **A failure, at the moment it happens** — a red test, a refused command, a
+  conflict. Say it where it occurs; do not hold it back for the block.
+
+Everything else waits.
+
+## The block
+
+A verdict sentence, a blank line, then a two-column table:
+
+✅ **Phase 2 built** — `feat-foo`, 2 of 4
+
+| | |
+|---|---|
+| **Tracker** | [ABC-88](https://example.invalid/ABC-88) · `feat-foo` · phase 2 moved |
+| **Branch** | `spec/feat-foo` · 3 commits, clean |
+| **Built** | POST /orders handler, orders schema |
+| **Tests** | 128 passed · npm test |
+| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Follow-ups** | none |
+| **Next** | `/spec-next` → phase 3 (Auth) |
+
+**A table, and never a fenced block.** An aligned label column is only
+achievable inside a fence, because markdown collapses runs of spaces outside
+one — so alignment and being recognised as a report are mutually exclusive, and
+the report wins. A fence renders as the same grey box as a code sample, and a
+reader who has been shown code all session reads one more box as code: the first
+person to receive one of these did not register it as output at all, and missed
+the `Next` row inside it. That is the exact scanning failure this contract exists
+to fix, so producing it in the contract's own format is not a cosmetic mistake.
+
+**The verdict sentence** is `<state> **<one clause>** — <spec>, <where it got
+to>`. The clause says what happened; the tail says to what, and how far. Name
+the skill in the clause when the run's identity is not obvious from the
+conversation — a refusal, or a skill invoked by another. A run with no spec to
+name drops that segment rather than inventing one.
+
+**The header row is empty.** The labels are the left column, and a header over
+them would only be able to say "field", which no one needs told.
+
+**The block is the last thing in the message.** Nothing follows it — not a
+closing line, not a next step, not the offer. Everything the reader must act on
+is a row, which is what earns the block its position.
+
+**And that is a rule about the destination, not only the prohibition.** It was
+stated plainly and broken repeatedly, by runs that had something worth saying
+and nowhere in the block to say it — so the paragraph went after the table,
+where it buried the rows it was meant to sit beside. A missing destination reads
+as a rule that does not fit the work, and a rule that does not fit gets ignored.
+So: **if it is worth telling the reader, it is a row.**
+**If it is not a row, it is not worth telling them.**
+`Snags` is the row most of that content belongs in.
+
+**One control may follow the block: a picker.** Where the run ends in a choice
+the reader must make, the options may be offered after the table. That is not
+an exception squeezed into the rule — the ban exists because *prose* after the
+block competes with it for the reader's attention and loses them the rows. A
+picker does not compete: it is the `Next` row made actionable, in the place the
+reader's eye already finishes. Prose after the block stays banned, and adding a
+sentence alongside the picker is the same violation wearing a control's clothes.
+
+**Never fence a message to the reader.** A fenced block is for a command to
+run, code, or engine output quoted verbatim — things the reader copies or
+compares. A question, an offer, a hand-off is prose. The same mechanism that
+made the old report unreadable applies to anything else in a grey box: it is
+read as an artefact to skim rather than as something addressed to someone, so a
+question inside one goes unanswered and an instruction inside one goes unread.
+
+**It reports this run and nothing else.** Not what else is in flight, not the
+other worktrees, not the backlog, not the state of the repo at large. A reader
+finishing one piece of work cannot tell whether a line about some other spec is
+a consequence of what just happened or an unrelated aside, and has to stop and
+work it out — which is the cost this block exists to remove. If they want the
+wider picture there is a skill that answers it; volunteering it here muddies the
+one thing they asked about.
+
+`Next` is the single next action **for this work**, not a menu of what else
+could be done.
+
+**And it must be runnable from the state the run actually leaves behind.** Most
+of these skills deliberately do not commit — they finish, verify, and wait — so
+the tree they hand back is dirty, and several of the commands they would name
+next refuse on a dirty tree. A `Next` that omits the commit therefore sends the
+reader to a refusal: `/spec-next` leaves a phase uncommitted and its own §2
+refuses on exactly that, and `/spec-bug` leaves a fix uncommitted where
+`/spec-complete` refuses the same way. Where the skill does not commit, the row
+says `/commit, then <the thing>`.
+
+This is not a style rule. `Next` is the one row a reader is meant to act on, and
+it closes the block because the closing row should be the one that moves the
+work on. A row that cannot be run spends the trust the position was designed to
+earn — and the two skills that got it wrong got it wrong independently, which is
+what makes it a missing constraint rather than two slips.
+
+## Field vocabulary, in this order
+
+A skill emits only the fields it declares, in this order, skipping the rest.
+`Follow-ups` is the exception: always present, second to last.
+
+`Tracker` is the conditional one: a skill may declare it and still never emit
+it, because no ticketing provider is installed. That is an absence with nothing
+behind it — say nothing rather than reporting that there was nothing to report.
+
+| Field | Carries |
+|-------|---------|
+| `Tracker` | **First.** The ticket id, linked where the spec has a url, the spec's folder name beside it, and what changed there. |
+| `Why` | **Non-`✅` only.** What stopped it, in one clause. |
+| `Branch` | Branch name, commit count, clean or dirty. |
+| `Spec` | The spec document's own state: status, bucket, phase. |
+| `Cause` | The root cause, for work that diagnosed one. |
+| `Built` | What the run produced — the code, the edits, the spec written. |
+| `Tests` | The result and the command that produced it. |
+| `Snags` | What this run hit and handled — one short paragraph. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
+| `Landed` | A fast-forward, a tag, a cherry-pick. |
+| `Worktree` | A worktree provisioned, entered, or torn down. |
+| `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
+| `Review` | The rendered diff page: files, `+`/`−`, the link — and the offer of a written review, in the same row. |
+| `Follow-ups` | **Always.** `none`, or one line each. |
+| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
+
+The order runs identity → context → what happened → where it went → what to do.
+**`Tracker` is first** because the id is what addresses this work outside the
+repo, and **`Next` is last** because it is the only row the reader acts on: the
+closing row should be the one that moves the work on.
+
+**`Untouched` is a fact, not a caveat.** A run that provisions beside another
+spec's uncommitted work has done nothing wrong and nothing partial — it left
+alone something that was never its business — so it stays `✅` with a row, and
+does not become `⚠️`. Several specs in flight at once is what the worktree mode
+is *for*; spending the "something is worth knowing" verdict on the normal case
+is how that verdict stops meaning anything. It is still reported rather than
+silent, because "I provisioned, and your four files are still sitting there" is
+a different sentence from "I provisioned".
+
+**`Review` is one row, not two.** The page and the offer to read it are the same
+subject, and splitting them made the reader resolve a distinction before acting
+on either. The offer does not need the final row once it has a label column to
+be found by.
+
+## The four verdicts
+
+| State | Means |
+|-------|-------|
+| `✅` | Done. Everything the skill set out to do happened. |
+| `⚠️` | Done with caveats — it finished, but something is worth knowing. |
+| `❌` | Failed part-way. It acted, and the repo is mid-something. |
+| `⏸` | Refused before acting. Nothing changed. |
+
+**`❌` and `⏸` are different facts about the repo**, and the difference decides
+what happens next. A failed landing leaves a conflicted rebase and a standing
+worktree — there is a mess to clear. A refusal leaves nothing at all, and the
+only thing to do is supply what was missing. Collapsing them sends people
+looking for wreckage that is not there, or past wreckage that is.
+
+**A refusal still emits the block.** That is the point of having four states:
+every invocation ends the same way, so an outcome is never inferred from
+silence.
+
+## Where the block may grow
+
+One place only. A non-`✅` verdict adds a `Why` row, and quotes the output that
+justifies it — the failing assertion, the conflict, the engine's refusal — in a
+fenced block **above** the table, where a fence means what a fence should mean:
+
+```
+✖ rejects a negative quantity
+  expected 422, got 500
+```
+
+❌ **Phase 2 stopped — tests red** — `feat-foo`, 2 of 4
+
+| | |
+|---|---|
+| **Why** | 3 assertions fail in `orders.test.js`; nothing committed |
+| **Branch** | `spec/feat-foo` · 2 commits, dirty |
+| **Built** | POST /orders handler, orders schema |
+| **Tests** | 125 passed, 3 failed · npm test |
+| **Follow-ups** | none |
+| **Next** | fix the failures, then `/spec-next` to finish phase 2 |
+
+Everywhere else the block stays the size it is. Prose after it, an extra row of
+your own invention, a second block — all three are the shape drifting back to
+what this replaced.
+
+## Follow-ups
+
+**Always present.** A recorded `none` is a decision; a missing line is an
+oversight — the same logic as the `Gating` header.
+
+The bar is deliberately high. A follow-up is something *this* work surfaced
+that *this* spec will not fix — a wrong assumption, a missing guard, a decision
+the spec deferred and the code then leaned on. It is **not** "could be tidier",
+and it is **not** anything already sitting in the spec's Open questions.
+
+When there is one, **offer to `/spec` it on the spot**. If the user does not
+take the offer, write one dated line into the spec's Changelog before you
+finish, so it outlives the session:
+
+```
+- 2026-01-09 — Follow-up surfaced: connect's port picker assumes a free
+  canonical port; not in scope here.
+```
+
+**Say where the spec would be written.** These skills run inside the spec's own
+worktree, and a spec authored there physically lives on that branch — invisible
+from the base branch, and cancelled along with its host if the host is
+cancelled. So the offer names the primary checkout as the place to write it.
+`spec-planning.md` and `commit-trailers.md` carry the reasoning.
+
+## Worked examples
+
+**`⚠️` — it finished, with something worth knowing.**
+
+⚠️ **Phase 3 built; tracker not updated** — `feat-foo`, 3 of 4
+
+| | |
+|---|---|
+| **Branch** | `spec/feat-foo` · 4 commits, clean |
+| **Built** | Auth middleware, session table |
+| **Tests** | 140 passed · npm test |
+| **Follow-ups** | Session expiry is read from two places; phase 4 leans on one |
+| **Next** | `/spec-next` → phase 4 (Docs) |
+
+**`⏸` — refused, nothing changed.**
+
+⏸ **`/spec-next` refused — no spec in flight**
+
+| | |
+|---|---|
+| **Why** | Not standing in a worktree, and 2 specs are provisioned |
+| **Follow-ups** | none |
+| **Next** | `/spec-start <name>`, or `cd` into `../repo-wt/feat-orders` or `../repo-wt/feat-auth` |
+
+**`✅` — a spec finished and landed.**
+
+✅ **Landed and torn down** — `feat-foo`, complete
+
+| | |
+|---|---|
+| **Tracker** | [ABC-88](https://example.invalid/ABC-88) · `feat-foo` · moved to its done state |
+| **Spec** | Complete · `specs/complete/feat-foo` |
+| **Tests** | 131 passed · npm test |
+| **Landed** | base fast-forwarded to 4a1c9e2 |
+| **Worktree** | removed · `../repo-wt/feat-foo` |
+| **Follow-ups** | none |
+| **Next** | pick the next spec from `specs/backlog/` |
+
+The `❌` example is in **Where the block may grow** above, since the failing
+output it quotes is the thing that example exists to show.