@skitterbyte/skitterspec-linear 10.0.1 → 10.2.0

package/assets/skills/spec/SKILL.md

@@ -36,28 +36,58 @@ Then:
 2. **Read the issue** with the discovered issue-read tool: title, description,
    labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
    without it — a spec written from the user's own description is still a spec.
-3. **Route bugs away — in `/spec` only.** If any of the issue's labels matches
-   `intake.bugLabels` (case-insensitive), this is a bug report, not a feature
-   request. Say so, name the matching label, and tell the user to run
-   **`/spec-bug <ISSUE-REF>`** — then stop, without authoring a Feature spec.
-   With `intake.bugLabels` unset nothing is routed and every issue is treated as a
-   feature request.
-
-   **In `/spec-bug` this step is skipped** — you are already in the bug path.
-   Adopt the issue, then reproduce it as usual: the issue body is your repro
+3. **Route the issue to the right skill.** Match the issue's labels
+   (case-insensitively) against two lists, **checking `hotfixLabels` first**:
+
+   - **`intake.hotfixLabels`** → this is broken in **production**, so it needs a
+     fix against the released version, not `main`. Say so, name the matching
+     label, and tell the user to run **`/spec-hotfix <ISSUE-REF>`** — then stop.
+   - **`intake.bugLabels`** → a bug report, not a feature request. Say so, name
+     the label, and tell the user to run **`/spec-bug <ISSUE-REF>`** — then stop,
+     without authoring a Feature spec.
+
+   **Hotfix wins when an issue carries both**, and deliberately: production is the
+   more specific destination, and the two mistakes are not equally costly. Routing
+   a prod issue to `/spec-bug` produces a fix that lands on `main` and never
+   reaches the running version — discovered only when someone asks why it hasn't
+   shipped. The reverse is a hotfix branch for something that could have waited,
+   which is merely wasteful.
+
+   With a list unset, nothing routes through it; with both unset every issue is
+   treated as a feature request, exactly as before.
+
+   **Which checks run depends on where you are**, because a skip is about not
+   bouncing someone to the skill they are already in — not about ignoring an
+   escalation:
+
+   - **In `/spec`** — both checks run.
+   - **In `/spec-bug`** — the bug check is skipped (it would route you to
+     yourself), but the **hotfix check still runs**. A bug report labelled for
+     production is not "already handled" by being in the bug path: `/spec-bug`
+     fixes on `main`, and prod would stay broken. Say so and hand off.
+   - **In `/spec-hotfix`** — both are skipped. It is already the most specific
+     destination; there is nowhere left to route.
+
+   Then adopt the issue and reproduce it as usual: the issue body is your repro
    material, and the failing test comes before the spec exactly as normal.
 4. **Seed, don't skip, the grill.** The issue's title becomes the working spec
-   title and its description the starting material for **Problem** — quote the
+   title and its description the starting material for **Problem** — or
+   **Symptom** in a bug or hotfix spec, which is where a report belongs. Quote the
    reporter's words rather than paraphrasing them away. Note the reporter and the
    issue URL for context. Everything after this runs exactly as normal: an issue
    is a *request*, not a groomed spec, so grill it as hard as anything else.
 
+   **In `/spec-hotfix`, also mine the issue for a version.** Any release-shaped
+   string in the report is a *suggestion* for the base tag, offered when the skill
+   asks which version prod is running — never used as a default. The reporter's
+   version is the one they saw the bug on, which is often not what is deployed.
+
 ### Adopting the issue
 
 The issue **becomes** the spec's issue — it is not copied and no second issue is
-minted. This is identical in `/spec` and `/spec-bug`; only *when* it happens
-differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4). Once the
-spec file exists:
+minted. This is identical in `/spec`, `/spec-bug` and `/spec-hotfix`; only *when*
+it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4,
+`/spec-hotfix` in its step 5). Once the spec file exists:
 
 - **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
   from the adopted issue. That is the whole link: every later skill
@@ -66,13 +96,15 @@ spec file exists:
   somewhere deliberately — where it lives is Linear's business, and adoption is
   not a mint.
 - **Do not write a base sidecar.** Leaving `sync.baseDir` empty for this spec is
-  what makes the first `/spec-push` push the spec over the reporter's original
+  what makes the **linking push** send the spec over the reporter's original
   description (an **update** to the existing issue, plus a sub-issue per phase).
   Recording a snapshot here would declare the mirror already in sync and strand
   the issue showing the raw report forever.
-- **Say what will happen** in the finish-up message: the first `/spec-push` will
-  overwrite the issue's description with the spec, and the original report is
-  preserved in the spec's **Problem** section.
+- **Say what will happen** in the finish-up message. The linking step runs right
+  after the spec is written, so the issue's description is replaced by the spec
+  **then** — not on some later manual push. The reporter's words are not lost:
+  they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
+  keeps the original in the issue's history.
 
 ## Phase A — reach a clear shared understanding (grill first)
 
@@ -286,49 +318,54 @@ while the repo stays the source of truth — follow the provider's link steps
 below (nothing to do here without one).
 
 **Only when `specs/.core/linear.config.json` exists** (Linear sync is opted in).
-If it's absent, skip this phase entirely — the spec stays local-only and `/spec`
-behaves exactly as above. When present, after writing the spec, link it to Linear
-so status and discussion live there while the repo stays the co-authoring surface.
-A spec is a Linear **issue**; each phase is a **sub-issue**, carrying that
-phase's tasks in its description as a read-only checklist:
-
-- **Discover the Linear MCP tools at runtime** (don't hardcode names). If Linear
-  isn't connected/authed, relay the fix and stop — leave the spec written and
-  local; the user can link it later with `/spec-push`. Do nothing destructive.
-- **Pick the Project** — run the picker in **Picking the Linear Project** below,
-  then **create the Issue** from the spec: `title` from the spec title,
-  `description` from the `00-overview.md` plan, `team` = `linear.teamId`, and
-  `project` = the picked id (omitted when the user chose None).
-- **Create a sub-issue per phase** (the `mapping.phases` target — `subissue` by
-  default): a child issue with `parentId` = the spec issue, named from each phase
-  file, in execution order.
-- **Stamp the ids** so the spec is linkable — one call, no hand-edited
-  frontmatter:
-
-  ```
-  skitterspec spec-sync stamp <spec> \
-    --issue TEAM-123 --url https://linear.app/… \
-    --sub 01-<slug>=TEAM-124 --sub 02-<slug>=TEAM-125
-  ```
-
-  It writes `linear_identifier`/`linear_url` onto `00-overview.md` and each phase
-  file's `linear_issue_id`, validating every ref and id **before** touching a
-  file — on any problem it changes nothing and exits non-zero, so a typo can't
-  leave the spec pointing at an issue that isn't there. (Status is not stored in
-  frontmatter — it comes from the spec's lifecycle folder.)
-- **Write the initial base sidecar** so the spec starts clean and non-diverged —
-  run `skitterspec spec-sync record <spec>` to capture the local snapshot as the
-  committed base (`sync.baseDir`). `/spec-status` should report in-sync right after.
-  (`record` is the writer; `normalize` only *prints* the projection.) Skip this
-  when the spec **adopted** an existing issue — see Phase 0 — because the issue's
-  description is still the reporter's, not the spec.
-- **Echo the branch name** from `branch.pattern` so the user knows what `/spec-go`
-  will fork.
+If it's absent, skip this entirely — the spec stays local-only and the skill
+behaves exactly as above. When present, link the spec you just wrote so status
+and discussion live in Linear while the repo stays the source of truth. A spec is
+a Linear **issue**; each phase is a **sub-issue**, carrying that phase's tasks in
+its description as a read-only checklist.
+
+**Linking is just the first push**, so it runs the same engine path `/spec-push`
+does — you never create the issue by hand:
+
+1. **Pick the transport.** `skitterspec spec-sync states --json`. With a Linear
+   API key set it answers `api` and prints the workspace's state names; without
+   one it answers `mcp` and you do the MCP work `/spec-push` describes. Write the
+   state names to a file for step 3.
+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`
+   — the spec is unlinked, so this plan is all-creates: the issue and one
+   sub-issue per phase.
+4. **Apply it.**
+   `skitterspec spec-sync apply <spec> --plan plan.json --project <chosen id>`.
+   That creates the issue and its sub-issues and checks what Linear stored. It
+   then **stamps the ids into the spec** — `linear_identifier`/`linear_url` on the
+   overview, `linear_issue_id` on each phase — and **records the base snapshot**,
+   so `/spec-status` reports in-sync immediately. There is no hand-editing of
+   frontmatter and no separate `stamp` or `record` call.
+
+   If it prints `transport = mcp`, it wrote nothing: apply the plan over MCP as
+   `/spec-push` steps 4a–5 describe, ending with `spec-sync stamp` and
+   `spec-sync record`. That path is fully supported — it is what anyone without
+   an API key uses.
+5. **Echo the branch name** from `branch.pattern` so the user knows what
+   `/spec-go` will fork.
+
+**If Linear can't be reached**, say so in one line and leave the spec written and
+local — it is still a perfectly good spec, and `/spec-push` links it later. Do
+nothing destructive.
+
+**A spec that adopted an existing issue** (see the intake step) is already
+stamped, so its plan is an **update**, not a create: applying it replaces the
+reporter's description with the spec. That is the one-way rule working as
+intended — the repo is canonical and the original text stays in Linear's history.
+Skip the project picker for an adopted issue: its placement is Linear's.
 
 Leave committing to the existing convention (the user commits the spec as usual)
 and **never auto-push git** — Linear's own automation reacts to real branch/PR
-events later. Report the Linear issue URL and the base as part of Phase C's
-finish-up message.
+events later. Report the Linear issue URL as part of the skill's finish-up
+message.
 
 ### Picking the Linear Project
 
@@ -338,8 +375,10 @@ placement is **Linear's to own**: never send `project` on an update, and never
 record the choice in the spec file or the snapshot. A PM re-homing a spec issue
 must not show up as drift or be overwritten on the next push.
 
-1. **List the candidates.** Call the discovered project-list tool for
-   `linear.teamId`. Drop archived / completed projects — they can't take new work.
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
 2. **Offer them.** Show the names (most recently updated first is fine), plus an
    explicit **None (team only)** option. Pre-select `linear.projectId` from
    `linear.config.json` when it's set and still in the list; otherwise pre-select
@@ -348,13 +387,14 @@ must not show up as drift or be overwritten on the next push.
    the list case-insensitively by name and re-offer. Don't re-fetch.
 4. **Never offer to create a project.** Projects are the PM's surface — if none
    fits, that's **None (team only)**, and someone makes the project in Linear.
-5. **Pass it once.** Include `project: <chosen id>` on the issue-create call.
-   Chose None → omit the key entirely (do not send an empty string).
-
-**Degrade, never block.** If Linear isn't connected, or the server exposes no
-project-list tool, say so in one line — *"project picker unavailable; creating the
-issue without a project"* — and carry on with `linear.projectId` if it's set, else
-no project at all. A missing picker must never fail `/spec` or `/spec-push`.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
 
 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.

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

@@ -35,28 +35,58 @@ Then:
 2. **Read the issue** with the discovered issue-read tool: title, description,
    labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
    without it — a spec written from the user's own description is still a spec.
-3. **Route bugs away — in `/spec` only.** If any of the issue's labels matches
-   `intake.bugLabels` (case-insensitive), this is a bug report, not a feature
-   request. Say so, name the matching label, and tell the user to run
-   **`/spec-bug <ISSUE-REF>`** — then stop, without authoring a Feature spec.
-   With `intake.bugLabels` unset nothing is routed and every issue is treated as a
-   feature request.
-
-   **In `/spec-bug` this step is skipped** — you are already in the bug path.
-   Adopt the issue, then reproduce it as usual: the issue body is your repro
+3. **Route the issue to the right skill.** Match the issue's labels
+   (case-insensitively) against two lists, **checking `hotfixLabels` first**:
+
+   - **`intake.hotfixLabels`** → this is broken in **production**, so it needs a
+     fix against the released version, not `main`. Say so, name the matching
+     label, and tell the user to run **`/spec-hotfix <ISSUE-REF>`** — then stop.
+   - **`intake.bugLabels`** → a bug report, not a feature request. Say so, name
+     the label, and tell the user to run **`/spec-bug <ISSUE-REF>`** — then stop,
+     without authoring a Feature spec.
+
+   **Hotfix wins when an issue carries both**, and deliberately: production is the
+   more specific destination, and the two mistakes are not equally costly. Routing
+   a prod issue to `/spec-bug` produces a fix that lands on `main` and never
+   reaches the running version — discovered only when someone asks why it hasn't
+   shipped. The reverse is a hotfix branch for something that could have waited,
+   which is merely wasteful.
+
+   With a list unset, nothing routes through it; with both unset every issue is
+   treated as a feature request, exactly as before.
+
+   **Which checks run depends on where you are**, because a skip is about not
+   bouncing someone to the skill they are already in — not about ignoring an
+   escalation:
+
+   - **In `/spec`** — both checks run.
+   - **In `/spec-bug`** — the bug check is skipped (it would route you to
+     yourself), but the **hotfix check still runs**. A bug report labelled for
+     production is not "already handled" by being in the bug path: `/spec-bug`
+     fixes on `main`, and prod would stay broken. Say so and hand off.
+   - **In `/spec-hotfix`** — both are skipped. It is already the most specific
+     destination; there is nowhere left to route.
+
+   Then adopt the issue and reproduce it as usual: the issue body is your repro
    material, and the failing test comes before the spec exactly as normal.
 4. **Seed, don't skip, the grill.** The issue's title becomes the working spec
-   title and its description the starting material for **Problem** — quote the
+   title and its description the starting material for **Problem** — or
+   **Symptom** in a bug or hotfix spec, which is where a report belongs. Quote the
    reporter's words rather than paraphrasing them away. Note the reporter and the
    issue URL for context. Everything after this runs exactly as normal: an issue
    is a *request*, not a groomed spec, so grill it as hard as anything else.
 
+   **In `/spec-hotfix`, also mine the issue for a version.** Any release-shaped
+   string in the report is a *suggestion* for the base tag, offered when the skill
+   asks which version prod is running — never used as a default. The reporter's
+   version is the one they saw the bug on, which is often not what is deployed.
+
 ### Adopting the issue
 
 The issue **becomes** the spec's issue — it is not copied and no second issue is
-minted. This is identical in `/spec` and `/spec-bug`; only *when* it happens
-differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4). Once the
-spec file exists:
+minted. This is identical in `/spec`, `/spec-bug` and `/spec-hotfix`; only *when*
+it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4,
+`/spec-hotfix` in its step 5). Once the spec file exists:
 
 - **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
   from the adopted issue. That is the whole link: every later skill
@@ -65,13 +95,15 @@ spec file exists:
   somewhere deliberately — where it lives is Linear's business, and adoption is
   not a mint.
 - **Do not write a base sidecar.** Leaving `sync.baseDir` empty for this spec is
-  what makes the first `/spec-push` push the spec over the reporter's original
+  what makes the **linking push** send the spec over the reporter's original
   description (an **update** to the existing issue, plus a sub-issue per phase).
   Recording a snapshot here would declare the mirror already in sync and strand
   the issue showing the raw report forever.
-- **Say what will happen** in the finish-up message: the first `/spec-push` will
-  overwrite the issue's description with the spec, and the original report is
-  preserved in the spec's **Problem** section.
+- **Say what will happen** in the finish-up message. The linking step runs right
+  after the spec is written, so the issue's description is replaced by the spec
+  **then** — not on some later manual push. The reporter's words are not lost:
+  they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
+  keeps the original in the issue's history.
 
 ## 1. Reproduce & isolate (light investigation)
 
@@ -216,6 +248,56 @@ The **State log** is the folder/status audit trail; later transitions
 (`/spec-complete`, `/spec-cancel`) append a row. The **Changelog** is for the
 fix narrative and decisions — keep them separate.
 
+**Only when `specs/.core/linear.config.json` exists** (Linear sync is opted in).
+If it's absent, skip this entirely — the spec stays local-only and the skill
+behaves exactly as above. When present, link the spec you just wrote so status
+and discussion live in Linear while the repo stays the source of truth. A spec is
+a Linear **issue**; each phase is a **sub-issue**, carrying that phase's tasks in
+its description as a read-only checklist.
+
+**Linking is just the first push**, so it runs the same engine path `/spec-push`
+does — you never create the issue by hand:
+
+1. **Pick the transport.** `skitterspec spec-sync states --json`. With a Linear
+   API key set it answers `api` and prints the workspace's state names; without
+   one it answers `mcp` and you do the MCP work `/spec-push` describes. Write the
+   state names to a file for step 3.
+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`
+   — the spec is unlinked, so this plan is all-creates: the issue and one
+   sub-issue per phase.
+4. **Apply it.**
+   `skitterspec spec-sync apply <spec> --plan plan.json --project <chosen id>`.
+   That creates the issue and its sub-issues and checks what Linear stored. It
+   then **stamps the ids into the spec** — `linear_identifier`/`linear_url` on the
+   overview, `linear_issue_id` on each phase — and **records the base snapshot**,
+   so `/spec-status` reports in-sync immediately. There is no hand-editing of
+   frontmatter and no separate `stamp` or `record` call.
+
+   If it prints `transport = mcp`, it wrote nothing: apply the plan over MCP as
+   `/spec-push` steps 4a–5 describe, ending with `spec-sync stamp` and
+   `spec-sync record`. That path is fully supported — it is what anyone without
+   an API key uses.
+5. **Echo the branch name** from `branch.pattern` so the user knows what
+   `/spec-go` will fork.
+
+**If Linear can't be reached**, say so in one line and leave the spec written and
+local — it is still a perfectly good spec, and `/spec-push` links it later. Do
+nothing destructive.
+
+**A spec that adopted an existing issue** (see the intake step) is already
+stamped, so its plan is an **update**, not a create: applying it replaces the
+reporter's description with the spec. That is the one-way rule working as
+intended — the repo is canonical and the original text stays in Linear's history.
+Skip the project picker for an adopted issue: its placement is Linear's.
+
+Leave committing to the existing convention (the user commits the spec as usual)
+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.
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all

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

@@ -51,6 +51,40 @@ Add a **Changelog** entry:
 `git mv "specs/<bucket>/<name>" "specs/cancelled/<name>"` (preserve history;
 move the whole folder).
 
+**Only when `specs/.core/linear.config.json` exists** and the spec's overview
+carries a `linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on. Nothing else in
+this step changes.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this spec's state, and the tracker is a generated mirror
+of it — leaving them to diverge until someone remembers to push by hand is the
+gap this exists to close. It costs one engine call and no model tokens when a
+Linear API key is set (see `apply.transport` in `linear.config.md`).
+
+- **Never mint.** An unlinked spec is skipped, not created. An issue born `Done`
+  or `Canceled` is tracker noise, and a spec kept deliberately local should stay
+  that way — `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
+  the repo regardless; the mirror is disposable and the next push repairs it.
+  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.
+
+### Why it sits here
+
+In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
+**after the `git mv` and before the commit**, and both halves matter:
+
+- **After the move**, because the projection reads a spec's workflow state from
+  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
+  uncommitted, which makes `spec-env integrate` refuse to land the branch.
+
 Then **commit the cancellation edits** — this skill wrote them, so it commits
 them:
 

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

@@ -53,6 +53,40 @@ Before marking complete, confirm the work is actually finished:
 move the whole folder). The `specs/complete/` folder is the record of finished
 specs — `git log`/the per-spec State log give the completion order.
 
+**Only when `specs/.core/linear.config.json` exists** and the spec's overview
+carries a `linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on. Nothing else in
+this step changes.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this spec's state, and the tracker is a generated mirror
+of it — leaving them to diverge until someone remembers to push by hand is the
+gap this exists to close. It costs one engine call and no model tokens when a
+Linear API key is set (see `apply.transport` in `linear.config.md`).
+
+- **Never mint.** An unlinked spec is skipped, not created. An issue born `Done`
+  or `Canceled` is tracker noise, and a spec kept deliberately local should stay
+  that way — `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
+  the repo regardless; the mirror is disposable and the next push repairs it.
+  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.
+
+### Why it sits here
+
+In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
+**after the `git mv` and before the commit**, and both halves matter:
+
+- **After the move**, because the projection reads a spec's workflow state from
+  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
+  uncommitted, which makes `spec-env integrate` refuse to land the branch.
+
 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:
 
@@ -128,14 +162,14 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
      recover those commits onto the branch, then re-run.
    - *no worktree* — the spec is live but its worktree is gone. Re-isolate it with
      `skitterspec spec-env up <name>`, then re-run.
-   Relay the diagnostic to the user and **stop** — do not proceed to teardown.
+   Relay the diagnostic to the user and **stop** — do not tear anything down.
 2. **Plan + execute.** Run `skitterspec spec-env integrate <name>` and run the
    printed commands **in order**:
    - `git -C <worktree> rebase <base>` — replay the branch onto base.
    - `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
    On a **rebase conflict** (non-zero exit), run
    `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
-   to the user; do not offer teardown.
+   to the user; do not tear anything down.
    On a **no-op** ("already landed"), just say so and continue.
 3. **Re-test on base.** Run the project's test command from the primary checkout;
    it must be **green** before you call the landing done.
@@ -144,9 +178,22 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
 
 ## 7. Tear down the environment (opt-in, only if configured)
 
-**Only when `specs/.core/env.config.json` exists**, offer — don't force — to
-reclaim the finished spec's environment. On confirmation, run the `spec-env` CLI
-directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
+**Only when `specs/.core/env.config.json` exists.** Reclaiming the environment is
+what completing a spec *is*, so sub-steps 1–3 run **automatically — do not ask**.
+Run the `spec-env` CLI directly (the old `/spec-env-down` skill is gone —
+teardown is folded in here).
+
+**The precondition is that the work actually landed.** Only tear down when step 6
+completed: it landed (or reported "already landed") **and** the base suite came
+back green. A rebase conflict, a work-loss abort or a red suite means step 6 told
+you to stop — tear nothing down, because the worktree is where the user picks the
+problem up. That precondition is what makes a confirmation redundant: by the time
+you get here the branch is an ancestor of base and the engine's guards have
+nothing left to protect.
+
+**Opt-out:** if the user passed **`--keep-env`**, skip sub-steps 1–3, say the
+worktree and branch are being kept, and go straight to sub-step 4. Mention
+`skitterspec spec-env up <name>` re-attaches it later either way.
 
 1. **Disconnect the proxy if this spec is connected.** If `.spec-env/connected`
    names this spec, run `skitterspec spec-env connect main` first so the
@@ -154,20 +201,28 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
 3. **Remove worktree + stack + slot:** run `skitterspec spec-env down <name>`
-   and execute the commands it prints, in order. After a **feature/bug** landing
-   the branch is merged into base, so teardown needs **no `--force`** and deletes
-   the branch (`git branch -d`). After a **hotfix** landing the branch isn't
-   merged (it was tagged + cherry-picked), but its head is captured by the deploy
-   tag, so teardown still needs no `--force` and drops the branch with
-   `git branch -D` (the tag holds the commits). It still respects the guards (won't
-   destroy a dirty, or unpushed-and-unlanded, worktree without `--force`).
+   and execute the commands it prints, in order. After a landing — merged into
+   base for a **feature/bug**, captured by the deploy tag for a **hotfix** —
+   teardown needs **no `--force`** and drops the branch with `git branch -D`,
+   which is safe precisely because the commits are already somewhere else. It
+   still respects the guards (won't destroy a dirty, or unpushed-and-unlanded,
+   worktree without `--force`), so if it *does* refuse, relay that and stop
+   rather than reaching for `--force`.
 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
    `git worktree remove`, or `--keep-volumes`. Show the user the orphan list and,
    **only on their confirmation**, execute the printed `docker volume rm`
-   commands. Non-fatal: if prune can't run (Docker down) or the user declines,
-   report it and finish completing anyway — never block the spec on it. Skip when
-   Docker isn't in use (the command self-reports "no orphaned volumes").
+   commands. **This one still asks**, unlike 1–3: it reaps volumes belonging to
+   *other* specs, and this spec having landed cleanly says nothing about those.
+   Non-fatal: if prune can't run (Docker down) or the user declines, report it and
+   finish completing anyway — never block the spec on it. Skip when Docker isn't
+   in use (the command self-reports "no orphaned volumes").
+
+**Say what you reclaimed.** With no confirmation step the user never saw this
+coming, so the final report must name the worktree path removed and the branch
+deleted (or, under `--keep-env`, that both were kept). A teardown nobody
+authorised and nobody was told about is the one way this step can lose someone's
+place.
 
 If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -152,9 +152,16 @@ below. Follow the provider's steps below (nothing to do here without one).
   to bring down before building — the repo is already the source of truth. (A
   workflow-state a teammate moved in Linear is advisory only; `/spec-status`
   surfaces it. It is overwritten on the next push.)
-- **Optional: refresh the mirror.** If you want Linear to reflect the now
-  in-progress spec, run `/spec-push` to send it up. This is optional at
-  `/spec-go` time — the mirror can equally be refreshed later.
+- **Refresh the mirror.** Run `/spec-push` to send the now in-progress spec up.
+  Whether that is optional depends on `mapping.phases`:
+  - `"subissue"` (the default) — **optional**. The phase sub-issues already
+    exist; this push only moves their states. Refresh now or later.
+  - `"deferred"` — **do it now, without asking.** Under deferral a spec sitting
+    in the backlog is mirrored as the issue alone, and this push is what mints
+    its phase sub-issues. Skip it and a started spec stays mirrored as a
+    phase-less issue until someone happens to run `/spec-push` by hand. Run it
+    straight after the step-2 commit, so the sub-issues land with the same
+    branch push that fires the tracker's automation.
 - Linear's GitHub branch/PR automation may drive status transitions off the
   branch/PR you pushed in step 2; that's expected and the repo still wins on the
   next `/spec-push`.