@skitterbyte/skitterspec-linear 11.0.0 → 13.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`.
 
@@ -139,7 +144,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.
@@ -198,6 +213,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
 
@@ -301,13 +319,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.
@@ -315,10 +334,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)
 
@@ -332,6 +351,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
@@ -359,7 +387,7 @@ does — you never create the issue by hand:
 2. **Pick the Project** — run the picker in **Picking the Linear Project** below.
    Keep the chosen id for step 4.
 3. **Get the plan.**
-   `skitterspec spec-sync push <spec> --workspace-states <file> --json > plan.json`
+   `skitterspec spec-sync plan <spec> --workspace-states <file> --json > plan.json`
    — the spec is unlinked, so this plan is all-creates: the issue and one
    sub-issue per phase.
 4. **Apply it.**
@@ -423,3 +451,26 @@ say so in one line — *"project picker unavailable"* — and carry on with
 
 If `linear.projectId` is set but that Project is archived or missing, relay
 Linear's error and stop rather than silently minting an unparented issue.
+
+## 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**.
@@ -140,25 +145,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
@@ -169,8 +162,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
 
@@ -207,6 +200,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
 
@@ -281,7 +276,7 @@ does — you never create the issue by hand:
 2. **Pick the Project** — run the picker in **Picking the Linear Project** below.
    Keep the chosen id for step 4.
 3. **Get the plan.**
-   `skitterspec spec-sync push <spec> --workspace-states <file> --json > plan.json`
+   `skitterspec spec-sync plan <spec> --workspace-states <file> --json > plan.json`
    — the spec is unlinked, so this plan is all-creates: the issue and one
    sub-issue per phase.
 4. **Apply it.**
@@ -314,6 +309,66 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+**Only when all three hold**: `specs/.core/linear.config.json` exists, its
+`sync.fieldOwnership` includes `assignee`, and the spec carries a
+`linear_identifier`. Any one missing → skip this step silently and carry on; a
+project that has not opted in must see no trace of assignment.
+
+**Never blocks, never fails the skill.** Everything below is best-effort: the
+branch is provisioned and the spec is moving either way, and an unassigned issue
+is a cosmetic gap that `/spec-claim` closes later.
+
+1. **Work out who you are.** Run `skitterspec spec-sync whoami --json`.
+   - `ok: true` → use `id` and `name`. Nothing to ask.
+   - `source: "mcp"` or the command reports no API key → call the discovered
+     user-read tool with `me`, then cache it:
+     `skitterspec spec-sync whoami --set <id> --name "<name>"`.
+   - `ok: false` → identity is **unknown**, which is an ordinary state (a shared
+     or bot key, an offline machine). Go to step 2.
+2. **Unknown identity — three states, not two.** Decide by what is actually
+   reachable, and route the third to inaction:
+   - **Linear reachable *and* this is an interactive session** → offer a short
+     user search (`skitterspec spec-sync users <name-or-email>`, or the
+     user-list tool on MCP), let the operator pick, and offer to cache it with
+     `whoami --set` so this is asked once per machine rather than once per spec.
+   - **Not reachable, or not interactive** → say so in one line
+     (`assignment skipped — no Linear identity`) and **carry on**. Do not prompt
+     for something you could not act on, and never stall a `/spec-start` on it.
+3. **Record it on the spec** — through the engine, never by hand-editing
+   frontmatter:
+
+   ```
+   skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
+   ```
+
+4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
+   seam already set it, and this seam must not overwrite it with the tracker's
+   display name.
+
+   Those two names are the same person and often not the same string, and the
+   git one is the one everything else in the spec already uses: `Author:`, every
+   **State log** `By` row, and every commit. Writing the tracker's name into this
+   one field would leave a spec whose own audit trail contradicts its header —
+   a worse problem than the one it would solve. Anyone wanting a different name
+   on their specs sets `git config user.name`, and it stays consistent
+   everywhere.
+
+   The header names **who is building this**; the stamp in step 3 names
+   **which tracker account it is assigned to**. They answer different questions,
+   so they need not be the same string. The one place that reasoning does not hold
+   is handing a spec to *someone else* — there is no local git name for them —
+   and that case belongs to `/spec-claim --to`, which sets the header from the
+   tracker deliberately.
+
+**Nothing is pushed here.** `assign` writes the repo only, and the refresh these
+skills already run sends it. Assignment is an ordinary field of the projection,
+not a side errand with its own network call.
+
+**There is no unassign step anywhere.** The projection derives the assignee from
+the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
+issue through the push they already make. The stamp deliberately stays in the
+file: who actioned the work outlives who is currently holding it.
+
 ### Picking the Linear Project
 
 Run this **only when minting a spec issue** — creating it for the first time. On
@@ -346,6 +401,19 @@ say so in one line — *"project picker unavailable"* — and carry on with
 If `linear.projectId` is set but that Project is archived or missing, relay
 Linear's error and stop rather than silently minting an unparented issue.
 
+### 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
@@ -383,10 +451,108 @@ sub-issue jump from Backlog straight to Done, with nothing visible in between.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
 
+## 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,
@@ -71,6 +76,12 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
   Do not roll anything back, and do not stop to ask.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
+- **There is no unassign step, and that is not an omission.** With `assignee` in
+  `sync.fieldOwnership`, the projection derives it from the spec's lifecycle
+  bucket — so moving the folder to `complete`/`cancelled` is *itself* what
+  releases the issue, and the push above carries it like any other field. The
+  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
+  they record who actioned the work, which outlives who is holding it.
 
 ### Why it sits here
 
@@ -81,17 +92,33 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
   its folder bucket. Push while the folder is still in `in-progress/` and the
   issue is set to the state the spec is *leaving*.
 - **Before the commit**, because the push stamps ids into the spec and writes a
-  snapshot under `specs/.core/`. The `git add specs/` that follows sweeps both up
-  with the status change; push after it instead and those files are left
+  snapshot under `specs/.core/`. Push after the commit instead and both are left
   uncommitted, which makes `spec-env integrate` refuse to land the branch.
 
+The snapshot is reached **by name**, not by breadth. It is a declared
+`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
+so `spec-env stage` returns it among this spec's owned paths and the commit below
+names it. This is why the commit no longer stages `specs/` wholesale: the one
+file outside the spec's folder that had to be swept up is addressable, so the
+breadth bought nothing and cost another session's work.
+
 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
@@ -99,7 +126,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)
 
@@ -110,9 +161,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
@@ -126,6 +191,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: