@skitterbyte/skitterspec 17.0.0 → 19.0.0

package/assets/skills/spec/SKILL.md

@@ -5,6 +5,11 @@ description: Create a new spec-driven-development spec. Grills the user to a cle
 
 # /spec — author a new spec
 
+> 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.
+
 Produce ONE concise spec in `specs/backlog/`. Do not start coding — this skill
 plans only. Implementation happens later via `/spec-start`.
 
@@ -49,7 +54,17 @@ not write the spec until this is resolved.
      `worktree + docker` only when it must. This sets the `> **Stack:**` header
      that `/spec-start` acts on (it can be escalated later). Skip when isolation
      isn't enabled — leave the default `worktree`.
-  10. **Open questions** — anything still undecided.
+  10. **Release gating** *(only when `specs/.core/gating.config.json` exists)* —
+      should this ship behind a feature flag, or land live?
+      **Offer, don't impose**: the user decides and you raise it, so a spec
+      never reaches
+      `/spec-complete` with the question unasked. Cite the project's own
+      `guidance` path from that config when it names one — skitterspec knows
+      nothing about how this project does flags, and must not guess. Record the
+      answer **either way**: a flag name, or `none: <one-line reason>`. "No" is a
+      decision and belongs in the header; silence is not. Skip entirely when the
+      config is absent — that project does not use flags.
+  11. **Open questions** — anything still undecided.
 
 Stop grilling when there are no unresolved branches that would change the spec.
 Briefly play back the agreed understanding before writing.
@@ -108,6 +123,9 @@ the codebase, link rather than duplicate):
 > **Area:** <comma-separated files/modules this touches>
 > **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
 > services; only acted on when isolation is enabled — see Phase A item 9>
+> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
+> is configured; omit the line entirely otherwise. An empty value or a bare
+> "none" is not a valid outcome — see Phase A item 10>
 
 ## Problem
 
@@ -211,13 +229,14 @@ Rules for the spec body:
   phase index.
 - **Honour project conventions** when writing tasks — reference the relevant
   `.claude/rules/*.md` rather than re-explaining them.
-- **The `## Impact` table is derived from Phase A items 3 (Affected areas) & 5
-  (Data/API impact)** — a structured place to record what those already surface,
-  not new grilling. It is the scannable substitute for spelling impact out in
-  prose: name the surfaces (endpoints, schemas, DB tables, domain objects,
-  routes, business rules) instead of describing them, keep `Detail` terse, and
-  let it — not paragraphs — carry the blast radius. It complements the `Area:`
-  header (files) by naming behavioural surfaces.
+-
+  **The `## Impact` table is derived from Phase A items 3 (Affected areas) & 5 (Data/API impact)**
+  — a structured place to record what those already surface, not new grilling.
+  It is the scannable substitute for spelling impact out in prose: name the
+  surfaces (endpoints, schemas, DB tables, domain objects, routes, business
+  rules) instead of describing them, keep `Detail` terse, and let it — not
+  paragraphs — carry the blast radius. It complements the `Area:` header
+  (files) by naming behavioural surfaces.
 - **Changelog** is mandatory and lives in the spec. Every later decision or
   course-correction gets a dated one-line entry. Convert relative dates to
   absolute.
@@ -225,10 +244,10 @@ Rules for the spec body:
 
 ## Phase C — finish up
 
-After writing, tell the user the path and that it's **`Ready`** in `backlog`
-(grilling in Phase A resolved the open questions). If you deliberately left open
-questions unresolved, write `Draft` instead and say what still needs deciding.
-Either way, the next step is `/spec-start` to start building.
+Decide the status: **`Ready`** in `backlog` when grilling in Phase A resolved the
+open questions, `Draft` when you deliberately left some unresolved. Either way
+the next step is `/spec-start`. The Report section below is where all of that
+reaches the user — do not narrate it here as well.
 
 ## Phase D — record the isolation stack (only if configured)
 
@@ -242,6 +261,15 @@ run `skitterspec spec-env up <name>` to add Docker to an existing worktree). If
 `env.config.json` is absent, isolation is off — leave the default `worktree` and
 finish as above.
 
+## Phase D2 — record the gating decision (only if configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Make sure the
+`> **Gating:**` header carries the Phase A item 10 answer — a flag name, or
+`none: <reason>` using the config's `default` wording if it sets one. Nothing is
+provisioned or enforced by this: the header exists so the decision is
+**on the record and reviewable**, and `skitterspec gating check` reports a spec that has
+none. It never blocks. If the config is absent, do not write the line at all.
+
 ## Phase E — link to a ticketing provider (only if one is installed)
 
 **Only when a ticketing provider is installed and configured** (it ships the
@@ -255,3 +283,26 @@ below (nothing to do here without one).
 
 
 
+
+## Report
+
+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**
+
+- `✅` — a `Ready` spec is written to `specs/backlog/<name>/`.
+- `⚠️` — written as `Draft`; open questions were deliberately left. Name them.
+- `⏸` — grilling did not reach a shared understanding, so nothing was written.
+  That is the skill working: a spec written over an unresolved requirement is
+  the outcome Phase A exists to prevent.
+
+**Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
+
+`Built` is the spec's path and phase count; `Spec` is its status and bucket;
+`Next` is `/spec-start <name>`, with the name spelled the way it must be typed.
+`Tracker` appears only when a provider is installed and linked it.
+
+**`Follow-ups` is almost always `none` here.** This skill's whole job is to
+capture work, so anything it surfaced belongs in the spec it just wrote rather
+than in a follow-up line beneath it.

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

@@ -5,6 +5,11 @@ description: Investigate a bug, capture it as a Bug-type spec, and drive it red
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 This is the **bug** counterpart to `/spec` (which is for **features**, plan-only).
 Unlike `/spec`, this skill is hands-on and test-first: it reproduces the bug as a
 **failing test (RED)**, captures a lean Bug spec, then works the test to **GREEN**.
@@ -50,25 +55,13 @@ provision from — you'll flesh it out in §4:
   `## Symptom` you established above.
 - Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
   the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
-  the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
-- Run the printed `git worktree add`. **The worktree forks from `main`'s last
-  commit, so your uncommitted stub doesn't travel with it** — move it across so
-  `main` is left pristine. **Create the destination bucket first:**
-
-  ```
-  mkdir -p <worktreePath>/specs/in-progress
-  mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/
-  ```
-
-  The `mkdir -p` is not belt-and-braces. Git does not store empty directories,
-  so `specs/in-progress/` is **absent** from a fresh worktree whenever that
-  bucket happens to be empty on `main` — the common case, since it empties every
-  time the last in-progress spec completes. `mv` into a missing destination
-  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
-  end up one level too high, `00-overview.md` sits where the bucket should be,
-  and every later step still appears to work until something cannot find the
-  spec. Confirm the result before carrying on — you want
-  `<worktreePath>/specs/in-progress/bug-<name>/00-overview.md`.
+  the worktree path, and any `in the worktree, run:` bootstrap steps.
+- Run the printed commands in order. The plan **commits the stub first** — the
+  worktree forks from `main`'s last commit, so the stub has to be in it — and
+  then adds the worktree. Nothing to move afterwards: the spec is already there.
+  The commit is planned, not silent; it appears in the printed plan above the
+  `git worktree add`, and `spec-env up` refuses outright if anything *other* than
+  this spec is uncommitted.
 - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
@@ -79,8 +72,8 @@ provision from — you'll flesh it out in §4:
   edits will prompt.
 - **Do everything below in the worktree**, on the branch — the red test, the fix,
   and the rest of the spec. Act on the worktree with absolute paths /
-  `git -C <worktreePath>`, or open a fresh session rooted there (the printed
-  opener). `main` changes only when the branch merges (at `/spec-complete`).
+  `git -C <worktreePath>`, or open a session rooted at the printed path. `main`
+  changes only when the branch merges (at `/spec-complete`).
 
 ## 3. Write the failing test FIRST (RED) — mandatory
 
@@ -117,6 +110,8 @@ because work is already underway. Keep it lean:
 > **Developer:** <git user.name — you, since you're fixing it now>
 > **Raised:** <YYYY-MM-DD (today)>
 > **Area:** <files/modules>
+> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
+> is configured; omit the line entirely otherwise>
 
 ## Symptom
 
@@ -178,6 +173,21 @@ fix narrative and decisions — keep them separate.
 
 
 
+
+
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Before writing the spec,
+ask: should this fix ship behind a feature flag, or land live?
+**Offer, don't impose** — cite the project's own `guidance` path when the config
+names one, and
+record the answer either way, as a flag name or `none: <one-line reason>`.
+
+A bug fix ships in the next release exactly like a feature, so it gets the same
+question rather than an assumption. A risky rewrite of a broken path is precisely
+where a kill-switch earns its keep; a one-line null check is precisely where
+`none:` is the honest answer. Skip entirely when the config is absent.
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all
@@ -198,10 +208,108 @@ is a no-op.
 
 
 
+## 5b. Render the page — then offer the review, never write it
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no worktree to read and this step does not exist —
+skip it in silence rather than explaining an absence.
+
+The fix is green and nothing is committed yet. That is the moment the page is
+about, so render it now — **after** the tests pass and **before** the commit:
+
+```
+skitterspec spec-env review <spec>
+```
+
+**This is free.** The engine reads git and splices the patches into a template;
+the diff never passes through you, so a 266KB patch costs nothing.
+
+**Then offer `/spec-diff`. Do not run it.** The written review is the part that
+costs — roughly **700 output tokens**, because writing it means reading the diff
+— and that spend is the operator's call, not a default.
+
+**The offer is the `Review` row of step 6's block** — the counts, the page link
+and a question, in one row:
+
+| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+
+**It ends in a question, addressed to someone.** It was once a fenced block of
+engine output, and it fired on every phase and was never once taken: two quoted
+lines under the test counts, addressed to nobody, with the report then closing
+on *"commit this first"* — the last instruction the reader got was to move on,
+so they did. A row in a labelled table is findable; a question in it is
+answerable. Both halves are load-bearing.
+
+**Never bury it and never split it.** It sits above `Follow-ups` and `Next`, and
+the page and the question stay in the same row: two adjacent rows about one page
+make the reader resolve a distinction before acting on either. A later edit that
+moves it out of the block, or separates the link from the question, undoes this
+and should be read as a regression rather than tidying.
+
+
+Relay the **`open:`** line rather than the bare path: a path is not clickable in
+any terminal, and a page nobody can open is a page nobody reads.
+
+- **Never write the review unasked**, and **never publish**. Publishing leaves
+  something behind that this tooling cannot remove, so it is always an ask. A
+  `file://` link is no use on a phone, and saying so **is** the ask —
+  `/spec-diff` §6 owns how.
+**Follow the `reader:` line the engine printed — do not sniff for it.** It
+answers where the person reading this is sitting, and the offer changes with it:
+
+- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
+  unknown is the ordinary state of a local machine, and a warning there is an
+  accusation against a healthy session.
+- **`local`** — the `file://` URL.
+- **`remote`** — the engine has already stood its local server up and put a URL
+  the reader can open on `open:`. So there is **nothing special to say**: relay
+  that line like any other. Any `also:` lines under it are the other addresses
+  this machine has, offered because the best-guess one can be wrong — pass them
+  on rather than editing them out.
+
+**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
+not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
+and in `--json`, and a second implementation here could not be tested and would
+drift.
+
+**Serving is the engine's to do; publishing is never.** A `remote` reader
+authorises a local server — one process, ended by one flag, leaving nothing
+behind — and authorises nothing else. Publishing leaves a page this tooling
+cannot remove, so it stays an ask in every case, always. If the engine could not
+serve (a busy port, a machine with no network address) it falls back to the
+`file://` URL with its marker, and that is when publishing is worth naming.
+
+- **Never fatal.** A failed render — no worktree, a git error — is one line, and
+  the fix is still done. The page is a convenience; the repo is the record.
+
 ## 6. Report
 
-Summarise: root cause, the failing→passing test, the fix, and the full test
-result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
-archive it (**when isolated**, the fix lives on the bug's branch, and
-`/spec-complete` merges it back to `main`). Do **not** `git commit` unless the
-user asks.
+Do **not** `git commit` unless the user asks. The spec stays in `in-progress`;
+`Next` names the commit and then `/spec-complete`, as
+`/commit, then /spec-complete` — this skill leaves the fix uncommitted, and
+`/spec-complete` §2 refuses on pre-existing uncommitted changes, so naming only
+the second half sends the reader into a refusal. `/spec-complete` then verifies
+and archives it (**when isolated**, the fix lives on the bug's branch, and it
+merges that back to `main`).
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — red→green, the fix is in and the suite passes.
+- `⚠️` — green, with something worth knowing (a narrowed repro, a mirror that
+  did not refresh).
+- `❌` — the test is still red, or a later test broke. Quote the failure.
+- `⏸` — the bug could not be reproduced, so nothing was written. Say what was
+  tried; an unreproduced bug is a finding, not a failed run.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
+`Review` · `Follow-ups` · `Next`
+
+`Cause` is the root cause in one clause and `Built` is the fix — the
+failing→passing test belongs in `Tests`, named, so the evidence is a test name
+rather than an adjective.
+
+Step 5b's offer is the `Review` row, not a paragraph after the block — the
+counts, the link and the question in one row. Nothing follows the block.

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

@@ -5,6 +5,11 @@ description: Cancel a spec — capture the reason, record final progress, stamp
 
 # /spec-cancel — record, stamp a reason, archive a spec
 
+> 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.
+
 ## 1. Identify the target spec
 
 - Use the name/path argument if given, else the spec **in context**. If unclear,
@@ -54,12 +59,22 @@ move the whole folder).
 
 
 Then **commit the cancellation edits** — this skill wrote them, so it commits
-them:
+them. Ask the engine which paths are this spec's, then stage and commit
+**exactly those**:
 
 ```
-git add specs/ && git commit -m "chore(spec): cancel <name>"
+skitterspec spec-env stage <name>     # lists them; --json to consume
+git add -- <the owned paths>
+git commit -m "chore(spec): cancel <name>" -- <the owned paths>
 ```
 
+**Never `git add specs/`.** That stages a *directory*, so a spec another
+session is part-way through writing lands in this commit under this spec's
+ticket. The `--` on the **commit** is the other half: a checkout has one
+`.git/index`, shared by every session standing in it, so a bare `git commit`
+takes whatever else is staged there however carefully you staged your own.
+`.claude/rules/spec-planning.md` carries the full account.
+
 **This matters more here than anywhere else.** Teardown (step 7) refuses a dirty
 worktree and offers `--force` as the way through — and forcing would destroy the
 cancellation record this skill just wrote. Committing first means teardown never
@@ -67,7 +82,31 @@ needs `--force`. Do not `git push`.
 
 ## 6. Report
 
-Confirm the cancellation, the reason recorded, the new location, and the commit.
+**The block is emitted when the run ends, not where this section sits.** The
+sections below run after it, so their outcome belongs in the block — write it
+once, at the end, with what actually happened.
+
+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**
+
+- `✅` — stamped, moved to `cancelled`, committed, torn down.
+- `⚠️` — cancelled, with something worth knowing: teardown declined, a tracker
+  refresh that failed, unpushed commits the operator chose to let go.
+- `❌` — it acted and stopped part-way. Say what is where.
+- `⏸` — no reason given, or no such spec. Nothing changed.
+
+**Fields:** `Tracker` · `Spec` · `Worktree` · `Follow-ups` · `Next`
+
+**The reason goes in the verdict clause** — `✅ /spec-cancel · feat-foo ·
+superseded by feat-bar`. It is the one thing anyone reading this later wants,
+and a cancellation is an ordinary successful run, so it must not be mistaken for
+a `Why`: that field is for a run that did not do what it set out to.
+
+`Worktree` says what was reclaimed, or that teardown was declined and the
+worktree still stands — on a cancelled spec that worktree may hold the only copy
+of the work, so an unreclaimed one is worth a line rather than a silence.
 
 ## 7. Tear down the environment (opt-in, only if configured)
 
@@ -78,9 +117,23 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
    main` first to free the canonical ports.
 2. `skitterspec spec-env dev down <name>` — stop its host dev servers.
-**Standing in the worktree? Leave it before you tear it down.** If this
-session's cwd is inside the spec's own worktree, `cd` to the primary checkout
-**first**, then run the teardown commands.
+**Standing in the worktree? Leave it before you tear it down.** If this session's
+cwd is inside the spec's own worktree — the normal case in `worktree` mode, since
+`/spec-start` moves you there — get out **first**, then run the teardown commands.
+One instruction covers it:
+
+```
+cd <primary checkout>
+```
+
+That is the whole mechanism, and it does not matter how you got in: the session
+was moved by a `cd` and it leaves by one. There is no tool to call here, and none
+should be reached for — the move in is a plain `cd` precisely because a tool that
+asks for approval is unusable on a phone.
+
+**`spec-env down` stays the single thing that deletes a worktree.** The plan
+below is the only deleter, because a second one is how the teardown guards get
+bypassed.
 
 Not because git refuses — it does not. `git worktree remove` **succeeds** on the
 tree you are standing in, and that is the problem: the directory vanishes under
@@ -94,6 +147,32 @@ only ordering that survives.
    remove the worktree/stack and free the slot. It respects the teardown guards
    (won't destroy a dirty/unpushed worktree without `--force`).
 
+   **When it refuses over unpushed commits, relay both ways out.**
+   A cancelled spec is normally unlanded, so this is the one moment in the
+   lifecycle where that guard genuinely fires — and it fires about real loss.
+   The worktree is the only copy of this work: the branch is on no remote and
+   not merged into the base branch, so removing it ends it. Say that plainly,
+   relay the engine's reason, and give both endings:
+
+   ```
+   publish it first — keeps the work reachable, then re-run /spec-cancel:
+     git -C <worktreePath> push -u origin <branch>
+
+   or accept the loss (the worktree and its commits go):
+     skitterspec spec-env down <name> --force
+   ```
+
+   **Print the push; never run it.** Publishing abandoned work to a shared
+   remote is the same unasked-for act this workflow took out of `/spec-start`,
+   and it is no more wanted here — someone may well want this branch to exist
+   nowhere but their own machine. Offer the command and wait for an answer.
+
+   **Never reach for `--force` yourself either.** The engine's own message names
+   only that half, which is the whole reason this step exists: meeting a wall
+   labelled *--force to tear down anyway* at the exact moment a backup is still
+   cheap is how work gets thrown away. Both options, then stop — the choice is
+   a decision about someone's work, and it is theirs.
+
    If the plan prints a `remote branch — confirm with the user first:` section,
    **ask before running that line** — it is a `git push <remote> --delete`, and
    the branch is merged, so it loses nothing. Usually there is nothing to ask:

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

@@ -5,6 +5,11 @@ description: Finish a spec — verify all phases are genuinely done, update prog
 
 # /spec-complete — verify, finalise, archive a spec
 
+> 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.
+
 ## 1. Identify the target spec
 
 - Use the name/path argument if given, else the spec **in context**. If unclear,
@@ -34,6 +39,23 @@ Before marking complete, confirm the work is actually finished:
   is its own, and step 4 commits that.
 
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>` and report what it says. This is the last point
+at which the question can still be answered cheaply, which is exactly why it is
+asked here — a spec that reaches `Complete` with no decision recorded is the gap
+the feature exists to close.
+
+**Never refuse to complete over it.** Say plainly that no decision was recorded,
+offer to record one now, and finish either way. The work is done; withholding the
+status flip would punish the wrong thing.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
 ## 3. Update the spec
 
 - Tick all completed tasks in the phase files; flip every finished phase-file
@@ -56,20 +78,63 @@ specs — `git log`/the per-spec State log give the completion order.
 
 
 Then **commit the completion edits** — steps 3–4 are this skill's own output, so
-it finishes its own work rather than handing you a dirty tree:
+it finishes its own work rather than handing you a dirty tree. Ask the engine
+which paths are this spec's, then stage and commit **exactly those**:
 
 ```
-git add specs/ && git commit -m "chore(spec): complete <name>"
+skitterspec spec-env stage <name>     # lists them; --json to consume
+git add -- <the owned paths>
+git commit -m "chore(spec): complete <name>" -- <the owned paths>
 ```
 
-Step 2 established the tree was otherwise clean, so this commits exactly the
-status flip and the move — nothing of yours rides along. **This is what lets step
-6 land:** `integrate` refuses a dirty worktree, so without committing here the
-skill would block on the very edits it just made. Do not `git push`.
+**Never `git add specs/`.** That stages a *directory*, so a spec another
+session is part-way through writing lands in this commit under this spec's
+ticket. The `--` on the **commit** is the other half: a checkout has one
+`.git/index`, shared by every session standing in it, so a bare `git commit`
+takes whatever else is staged there however carefully you staged your own.
+`.claude/rules/spec-planning.md` carries the full account.
+
+So this commits exactly the status flip and the move, and nothing of yours — or
+of anyone else's — rides along.
+**This is what lets step 6 land:** `integrate` refuses a dirty worktree, so
+without committing here the skill would block on the very edits it just made.
+Do not `git push`.
 
 ## 5. Report
 
-Confirm the move, the commit, the final test result, and list anything deferred.
+**The block is emitted when the run ends, not where this section sits.** The
+sections below run after it, so their outcome belongs in the block — write it
+once, at the end, with what actually happened.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — every phase done, tests green, landed, torn down.
+- `⚠️` — finished, with something worth knowing: teardown declined, a tracker
+  refresh that failed, a hotfix tag still waiting to be pushed.
+- `❌` — it acted and stopped part-way — a conflicted rebase, a failed
+  cherry-pick, a red base after landing. Say what state the repo is in and quote
+  the failure; there is a mess to clear and the reader needs to know where.
+- `⏸` — phases are unfinished, tests are red, or the tree is dirty. Nothing
+  moved.
+
+**Fields:** `Tracker` · `Spec` · `Tests` · `Landed` · `Worktree` ·
+`Follow-ups` · `Next`
+
+**Report this spec and no other.** A completion is the moment it is most
+tempting to survey what is left — what else is in flight, what is in the
+backlog, which worktrees are still standing — and it is the moment it helps
+least: the reader has just finished something and cannot tell whether a line
+about another spec followed from it. `Next` is one action for this spec, and
+`/spec-list` is where the wider picture lives if they want it.
+
+`Landed` says how, because the two ways differ: a fast-forward names the base
+and the commit, a hotfix names the deploy tag and the `main` cherry-pick — and
+a deploy tag that has not been pushed is a `⚠️`, not a `✅`. `Worktree` says
+what was reclaimed, including any orphaned volumes swept, or that teardown was
+declined and the worktree still stands.
 
 ## 6. Land the branch (opt-in, only if isolated)
 
@@ -171,9 +236,23 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    canonical ports go back to the primary checkout.
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
-**Standing in the worktree? Leave it before you tear it down.** If this
-session's cwd is inside the spec's own worktree, `cd` to the primary checkout
-**first**, then run the teardown commands.
+**Standing in the worktree? Leave it before you tear it down.** If this session's
+cwd is inside the spec's own worktree — the normal case in `worktree` mode, since
+`/spec-start` moves you there — get out **first**, then run the teardown commands.
+One instruction covers it:
+
+```
+cd <primary checkout>
+```
+
+That is the whole mechanism, and it does not matter how you got in: the session
+was moved by a `cd` and it leaves by one. There is no tool to call here, and none
+should be reached for — the move in is a plain `cd` precisely because a tool that
+asks for approval is unusable on a phone.
+
+**`spec-env down` stays the single thing that deletes a worktree.** The plan
+below is the only deleter, because a second one is how the teardown guards get
+bypassed.
 
 Not because git refuses — it does not. `git worktree remove` **succeeds** on the
 tree you are standing in, and that is the problem: the directory vanishes under
@@ -192,16 +271,26 @@ only ordering that survives.
    worktree without `--force`), so if it *does* refuse, relay that and stop
    rather than reaching for `--force`.
 
-   **If the plan prints a `remote branch — confirm with the user first:`
-   section, ask before running it.** `/spec-start` pushed this branch when it
-   provisioned, so the remote copy outlives teardown unless someone deletes it.
-   The planner only ever offers this for a branch that has **landed**, so say so
-   plainly when you ask — the commits are on the base branch (or captured by the
-   deploy tag), so deleting the remote branch loses nothing. On a yes, run the
-   printed `git push <remote> --delete <branch>`; on a no, leave it and say the
-   remote branch is still there. Never fold it into the `run these:` batch — a
-   project that wants it unattended sets `teardown.deleteRemoteBranch: "always"`
-   in `env.config.json`, and then it appears in `run these:` instead of here.
+   **The unpushed half of that guard cannot fire here, by construction.**
+   Step 6 landed the branch, so `merged` is true and `planDown` skips the check
+   entirely (`env/teardown.js`) — completing a spec never meets it, however the
+   branch was or was not published. `/spec-cancel` is where it does fire, because
+   a cancelled spec is unlanded and its worktree really is the only copy; the
+   publish-or-`--force` path therefore lives in that skill and this one needs no
+   equivalent. A refusal reaching this step is about a **dirty tree** instead,
+   which means something wrote into the worktree after the landing — read it,
+   don't force it.
+
+   **If the plan prints a `remote branch — confirm with the user first:` section, ask before running it.**
+   Nothing published this branch for you, so a remote copy exists only because
+   you pushed it by hand — and it outlives teardown unless someone deletes it. The planner only ever offers
+   this for a branch that has **landed**, so say so plainly when you ask — the
+   commits are on the base branch (or captured by the deploy tag), so deleting
+   the remote branch loses nothing. On a yes, run the printed
+   `git push <remote> --delete <branch>`; on a no, leave it and say the remote
+   branch is still there. Never fold it into the `run these:` batch — a project
+   that wants it unattended sets `teardown.deleteRemoteBranch: "always"` in
+   `env.config.json`, and then it appears in `run these:` instead of here.
 4. **Reap orphaned test-DB volumes:** run `skitterspec spec-env prune`. It lists
    Docker volumes in the repo namespace that belong to **no live spec** (no
    worktree) — leftovers from declined/aborted teardowns, manual