@skitterbyte/skitterspec-linear 12.0.0 → 14.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:** …`):
@@ -13,6 +13,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (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/` |
@@ -26,6 +27,20 @@ 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. Because the model cannot invoke this
+skill, a pass named this way 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.
+
+It is **no longer the only way in**, and the difference is worth stating
+precisely. A phase that ends now *waits* on its page, and a pass arriving inside
+that wait is claimed by the engine (`--claim-since`) without anyone typing
+anything — scoped to the window, refusing when two arrive. `/spec-reviewed` is
+what answers everything outside it: a pass sent when nobody was waiting, two
+passes to choose between, and every harness with no file-watch to wait with.
+
 `/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
 subcommands) — but they are marked user-only too, since nobody reaches them
@@ -44,11 +59,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 — and `/spec-start` moves
-the session you typed into *into* that checkout, so the work carries on in the
-same terminal. **`checkout`** builds the branch in the primary checkout instead:
-one spec at a time, and nothing to move into. Neither mode costs you a second
-terminal; the difference is how many specs can be in flight at once.
+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
@@ -68,8 +87,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
@@ -81,9 +103,12 @@ 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
@@ -93,6 +118,203 @@ stateful ones (`Stack: worktree + docker`, or a branch touching migrations) —
 `/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.
+
+It was once true that a device reaching your page
+**could not reach your conversation**, and that fact was the whole guard: a pass sat in the holding
+area until you typed `/spec-reviewed`. It is no longer true, deliberately —
+a phase that ends **waits** for its verdict, so the button you press on the page
+is what carries the work on. What replaced the guard is two mechanisms and one
+rule. The **serve token** — 48 bits of randomness in the URL path, minted per
+server — decides who can POST at all. The **wait window** decides which pass may
+be claimed without you naming it: the engine's `--claim-since` takes the one
+pass that arrived *while this session was waiting*, acts on nothing when none
+did, and refuses to choose when two did. And outside that window the rule stands
+unchanged and absolute: **Claude never claims a pass it was not asked to**
+(`/spec-diff` step 0, because nothing enforces it).
+
+What you give up is real and worth naming: the page can now act. What you get is
+the loop closing without anyone remembering a command — which is the failure the
+old design traded it for.
+
+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 gate — a phase that ended owes an answer.** That is the second refusal,
+and it is a different kind: not a count, and not about the marks at all.
+`/spec-next` **arms** it when a phase ends and renders its page, and exactly two
+things clear it — a **committing verdict**, or
+`skitterspec spec-env review skip "<reason>"`. Until one of them happens,
+`/spec-next` refuses to build the next phase and (where the hook is installed)
+`git commit` refuses in that worktree. `skitterspec spec-env review gate
+[--check] [--json]` is what both ask.
+
+**The hook is the half that cannot be talked past.** `skitterspec init` installs
+`.claude/hooks/review-gate.js` and registers it in the project's committed
+`.claude/settings.json`, so a `git commit` is refused by the harness rather than
+by prose — which is what covers a bare `git commit`, a chained command, and
+skittership's own `/commit` without skitterspec ever editing it. It decides
+nothing itself: it hands the command line to
+`spec-env review gate --check --for-command` and turns one exit status into an
+answer. It refuses only where the commit is running
+**inside that spec's own worktree** — a commit on the base branch, or in
+another spec's tree, is not this obligation's business — and it fails **open** on everything else: no engine, an
+unreadable payload, a crash, a timeout, a repo with no isolation.
+
+Three things keep it a push rather than a wall. It is armed
+**only by a phase ending**, so reading your own half-finished work mid-phase
+owes nothing.
+It has an **exit that is always one command**, and one of them is
+*"I am moving on"* — with a reason, because `none: additive, nothing to revert` is a decision
+a reviewer can argue with while silence is an oversight. And it accuses
+**only on a positive signal**: an unreadable sidecar, a project that set
+`review.required: false`, a spec the engine could not resolve — every
+cannot-tell exits 0 and says nothing (`.claude/rules/negative-checks.md`).
+
+It is on by default wherever isolation is configured. That is the point: the
+push toward reading the diff is the normal path, and stepping off it is the
+thing you have to do deliberately.
+
+**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
@@ -111,6 +333,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;

package/assets/rules/spec-reports.md

@@ -0,0 +1,321 @@
+# 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.**
+`Notes` is the row most of that content belongs in.
+
+**Two controls may follow the block, and nothing else ever.** The ban exists
+because *prose* after the block competes with it for the reader's attention and
+loses them the rows. A control does not compete: it is a row made actionable, in
+the place the reader's eye already finishes. Prose after either of them is the
+same violation wearing a control's clothes.
+
+**The first is a picker.** Where the run ends in a choice the reader must make,
+the options may be offered after the table.
+
+**The second is the review call-to-action**, and only where the run is actually
+**waiting** on a verdict. It is a banner, not a sentence:
+
+---
+
+## ⏸ Review ready — 7 files, +212 −18
+
+**[Open the page](http://…)** · I'm holding here until you send a verdict.
+
+`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
+
+---
+
+A rule, a heading naming the state and the size, the link in bold, one line
+saying the run is stopped, and the two exits. Nothing else, and never a
+paragraph explaining it.
+
+**Only promise a wait the transport can deliver.** A page the engine SERVES
+hands its pass to the local store, which a file-watch sees — that is the one
+case where *"I'm holding here"* is true. A **published** page writes to the
+artifact's own store, and nothing pushes from there into the conversation, so a
+verdict pressed on it is invisible until someone asks for it. Its banner says
+so instead:
+
+**[Open the page](https://…)** · press a verdict, then type `/spec-reviewed` — I cannot see it until you do.
+
+**Exactly one link, never two.** The banner offers the page the reader can
+actually use, and the engine has already decided which that is — a served URL
+when it could serve, a published one only when it could not. Handing over both
+asks the reader to know which door the run is standing behind, and they cannot:
+it was done, and a verdict was pressed on the published page three times while
+each one sat unread under a line claiming the run was waiting. Two links is not
+a convenience with a caveat; it is the caveat existing at all.
+
+**This is not the old failure returning**, and the difference is the whole
+justification. The offer used to be two quoted lines in the tail of a long
+report, addressed to nobody, under a closing line that told the reader to move
+on — and it was never once taken. It was moved into a labelled row to make it
+findable, and that worked. What changed since is that the run now *waits*: the
+reader is not being offered something optional, they are being told the work has
+stopped until they answer. A row cannot carry that, because a row is scanned at
+the same weight as every other row. So the state gets the loudest shape on
+screen, at the end, where reading finishes.
+
+**Where the run is not waiting, it stays a `Review` row.** A render nobody is
+being held for — a mid-phase `/spec-diff`, a page produced alongside other work
+— is a convenience, and giving it a banner teaches the reader to scroll past
+banners. The shape marks the difference between *here is a page* and *nothing
+proceeds until you answer*.
+
+**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. |
+| `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. 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. **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
+| `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** — and where the run is waiting, it is no rows
+at all. 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. A waiting
+run promotes the whole subject into the banner; keeping the row as well would
+recreate that split with the two halves further apart than ever.
+
+## 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.