@skitterbyte/skitterspec 17.0.0 → 18.0.0

package/MIGRATION.md

@@ -1,5 +1,49 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v17 → v18 (a spec is built in its own worktree)
+
+### Breaking change
+
+**`/spec-start` no longer moves the branch into your checkout.** In `worktree`
+mode it provisions the spec's worktree, does the housekeeping there, opens a
+session in it, and stops. The spec is built where it was provisioned — which is
+what worktrees are for, and why `main` stays free.
+
+This **supersedes the "one checkout holds one spec in flight" rule** described
+under v16 → v17 below. That rule was a consequence of moving the branch into the
+primary checkout; with the move gone, so is the restriction:
+
+| v17 | v18 |
+|-----|-----|
+| `/spec-start` refused while another spec held your checkout | In `worktree` mode it only requires a **clean tree**. Several specs in flight is what the mode is for. |
+| Starting a spec took two invocations, with a `/spec-live <name>` you typed in between | **One invocation.** No hand-off command, no re-run. |
+| `/spec-live main` was one of the ways out of the gate | The ways out are `/spec-complete` and `/spec-cancel`. Parking to free a workbench is a one-workbench answer, and only `checkout` mode holds one spec now. |
+
+**`/spec-live` is for testing only** — reusing your running dev server to reach a
+spec at the canonical URL. It was never meant to be how work gets started, and no
+lifecycle skill calls it.
+
+`checkout` mode is unchanged: the branch is built in the primary checkout, the
+gate still requires the workbench free, and `/spec-start` carries straight on
+into phase 1 in the same session.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Expect a session, not a swap.** After `/spec-start` in `worktree` mode, run
+   `/spec-next` from the session it opens in the worktree. `/spec-next` builds
+   the spec it is *standing in* and refuses to build one from elsewhere.
+3. **Nothing to configure.** `spec.companionPaths` in `env.config.json` is new
+   and optional — it names paths that belong to a spec alongside its own folder
+   (a tracker's per-spec snapshot), so `/spec-start` can commit them together.
+   Empty by default; `/spec-linear-setup` sets it for you.
+
+## `@skitterbyte/skitterspec-linear` v11 → v12 (a spec is built in its own worktree)
+
+The same change as `@skitterbyte/skitterspec` v17 → v18 above — this
+distribution composes the same lifecycle skills. Read that entry; nothing here
+is Linear-specific.
+
 ## `@skitterbyte/skitterspec` v16 → v17 (`/spec-go` splits in two)
 
 ### Breaking change
@@ -36,6 +80,14 @@ branch nobody asked for.
    provider distribution must rename its fragment file to match, or the build
    fails on an orphaned seam.
 
+## `@skitterbyte/skitterspec-linear` v10 → v11 (`/spec-go` splits in two)
+
+The same change as `@skitterbyte/skitterspec` v16 → v17 above — this
+distribution composes the same lifecycle skills, so `/spec-go` is removed here
+too and replaced by `/spec-start` + `/spec-next`. Read that entry; nothing here
+is Linear-specific. (Backfilled: the base entry was written when the change
+landed and this one was missed.)
+
 ## `@skitterbyte/skitterspec-linear` v9 → v10 (`push` validates your issue states)
 
 **`spec-sync push` now refuses to run until the configured `states` names have

package/assets/claude-md-section.md

@@ -13,3 +13,13 @@ skill that wants one will tell you to type it.
 The skill table, the spec type/folder conventions and the per-spec isolation
 model all live in **`.claude/rules/spec-planning.md`**, the canonical reference
 every spec skill points at. Tailor its per-phase test commands to this stack.
+
+**Release gating** *(only when `specs/.core/gating.config.json` exists)* — each
+spec records whether it ships behind a feature flag, as
+`> **Gating:** <flag name>` or `> **Gating:** none: <one-line reason>`. `/spec`,
+`/spec-bug` and `/spec-hotfix` ask; `/spec-review`, `/spec-start` and
+`/spec-complete` report a spec that has no answer, and never block over it.
+`skitterspec gating check` lists them and always exits 0. The point is that the
+question is **on the record**: a missing line is an oversight, a reason is a
+decision. Skitterspec never reads your flag system — it asks and cites the doc
+you point it at. Without that config, none of this appears.

package/assets/core/env.config.json.example

@@ -33,6 +33,9 @@
     "pattern": "{type}/{slug}",
     "identifierField": ""
   },
+  "spec": {
+    "companionPaths": []
+  },
   "baseBranch": "",
   "guards": {
     "refuseTeardownIfDirty": true,

package/assets/core/env.config.md

@@ -8,11 +8,11 @@ in-progress spec). Provisioning is folded into `/spec-start`, teardown into
 beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-start` gives
-**every** in-progress spec its own git worktree automatically. Docker is a **per-
-spec escalation** — a spec brings up a stack only when its `> **Stack:**` header
-is `worktree + docker` (set at `/spec` when it touches the DB / stateful
-services). A `worktree`-only spec takes no registry slot, no port block, and no
-`.env`.
+**every** in-progress spec its own git worktree automatically. Docker is a
+**per- spec escalation** — a spec brings up a stack only when its
+`> **Stack:**` header is `worktree + docker` (set at `/spec` when it touches
+the DB / stateful services). A `worktree`-only spec takes no registry slot, no
+port block, and no `.env`.
 
 **Adopt it** with `skitterspec init --isolation` (or copy
 `env.config.json.example` → `env.config.json` here) and edit the values. While
@@ -124,13 +124,18 @@ no live `env.config.json` was found.
     "host": "127.0.0.1"     // bind host for the canonical ports
   },
 
-  // Optional, editor/terminal-agnostic opener. `/spec-start` RUNS it when it hands
-  // you into a new worktree — after provisioning and bootstrap, so the session
-  // opens onto a tree that is ready to work in. The template is expanded with
-  // {worktreePath}, {slug}, {branch}, {projectName}, {portOffset}.
+  // Optional, editor/terminal-agnostic opener — the FALLBACK for reaching a
+  // worktree. `/spec-start` normally moves the session you typed into into the
+  // worktree, and then there is nothing to open: it runs this only when it
+  // could not switch in place (the session is already inside another worktree,
+  // or the harness cannot move it). Run after provisioning and bootstrap, so
+  // the session opens onto a tree that is ready to work in. The template is
+  // expanded with {worktreePath}, {slug}, {branch}, {projectName},
+  // {portOffset}.
   // Empty = nothing is opened (the path is just printed), which is how you turn
-  // the auto-open off. A non-interactive run skips it either way — an opened
-  // window nobody is sitting at helps no one.
+  // the auto-open off, and the right value unless you actually want a second
+  // window on the fallback path. A non-interactive run skips it either way — an
+  // opened window nobody is sitting at helps no one.
   // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
   // or a "warp://..." deeplink for Warp users.
   "open": {
@@ -153,6 +158,26 @@ no live `env.config.json` was found.
     "identifierField": ""
   },
 
+  // Paths that belong to a spec ALONGSIDE its own `specs/<bucket>/<name>/`
+  // folder. `/spec-start` uses this to tell "the spec you just wrote, not yet
+  // committed" apart from someone else's uncommitted work: if every dirty path
+  // belongs to the spec being started it is committed for you, and if a single
+  // path does not, the start is refused as before.
+  //
+  // Provider-neutral by design — the base engine must not know that any
+  // particular tracker exists — so you declare the shape here. `{slug}` and
+  // `{identifier}` expand exactly as in `branch.pattern` above, `{identifier}`
+  // via `branch.identifierField`.
+  //
+  // A pattern using {identifier} matches NOTHING when no identifier resolves
+  // (no `identifierField` set, or a spec never pushed to a tracker). That is
+  // deliberate: the file it names then belongs to some other spec, and the safe
+  // failure is a refusal you clear with /commit, not a stranger's file swept
+  // into your commit. Default: none — a spec owns only its own folder.
+  "spec": {
+    "companionPaths": []
+  },
+
   // Integration base branch — the branch specs fork from and land back onto
   // (used by the teardown "merged?" guard and, later, the integrate step).
   // Empty = auto-detect: origin/HEAD → main → master. Set it when your default

package/assets/core/gating.config.json.example

@@ -0,0 +1,4 @@
+{
+  "guidance": "",
+  "default": "none: <reason>"
+}

package/assets/core/gating.config.md

@@ -0,0 +1,81 @@
+# `gating.config.json` — release-gating config
+
+Opt-in config for **release gating**: whether each spec records a decision about
+shipping behind a feature flag.
+
+The problem it solves is not "we forgot to use a flag" — it is that
+**nobody can tell whether the question was asked**. A spec can go from `/spec`
+through
+implementation to `/spec-complete` with no flag and no mention of one, and that
+is indistinguishable from "we considered it and decided against". Prose guidance
+in a project rule has already been shown not to close that gap; a required header
+does, because its absence is visible.
+
+**Skitterspec bakes in the offer, never the mechanism.** How your project does
+flags — a resolver, an admin toggle, env precedence, a vendor SDK — is none of
+its business, and it never reads your flag code. It asks the question, cites your
+own documentation, and records the answer.
+
+**Adopt it** by copying `gating.config.json.example` → `gating.config.json` here
+(or `skitterspec init --gating`). While this file is absent the feature is
+entirely unused: no grill question, no header, nothing to check — which is read
+as "this project does not use feature flags".
+
+## Fields
+
+```jsonc
+{
+  // Where THIS project documents how its flags work — a repo-relative path,
+  // cited when the question is asked so the answer is an informed one.
+  // Skitterspec never reads the file; it only names it. Empty = say nothing.
+  "guidance": ".claude/rules/feature-flags.md",
+
+  // The value written when the user declines a flag, so a project can
+  // standardise its wording. Must keep the `none: <reason>` shape — the reason
+  // half is the whole point (see below). Empty falls back to `none: <reason>`.
+  "default": "none: <reason>"
+}
+```
+
+## The header it drives
+
+With this file present, every spec `/spec`, `/spec-bug` and `/spec-hotfix` write
+carries a `Gating:` field beside `Stack:` in `00-overview.md`:
+
+```
+> **Gating:** search-ranking-v2
+> **Gating:** none: additive, nothing to revert
+```
+
+Two valid shapes, and one that is not:
+
+| Value | Meaning |
+|-------|---------|
+| a flag name | ships behind that flag |
+| `none: <reason>` | deliberately not flagged, and why |
+| *missing, empty, or a bare `none`* | **not a decision** — nobody answered |
+
+The reason half is load-bearing. `none: additive, nothing to revert` is a
+decision a reviewer can disagree with; a bare `none` is a shrug, and a missing
+line is an oversight. Distinguishing those three is the entire feature.
+
+## What it never does
+
+- **It never blocks.** `skitterspec gating check` reports and exits 0;
+  `/spec-start` and `/spec-complete` mention a missing header and carry on.
+  Nothing here can stop a spec being started, completed or landed.
+- **It never accuses an old spec.** Only `specs/backlog/` and
+  `specs/in-progress/` are read. Specs finished or abandoned before you adopted
+  gating are out of range by construction, not by a filter someone has to
+  remember.
+- **It never learns your flag system.** `guidance` is a path it prints, nothing
+  more.
+
+## Checking
+
+```
+skitterspec gating check              # the spec in flight here
+skitterspec gating check <spec>       # one named spec
+skitterspec gating check --all        # every active spec
+skitterspec gating check --json       # for tooling
+```

package/assets/rules/spec-planning.md

@@ -11,8 +11,8 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
 | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-start` | Put a spec in flight on this checkout, then build phase 1 | `In Progress` | `specs/in-progress/` |
-| `/spec-next` | Build the next phase of the spec in flight (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
+| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
+| `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
 | `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
 | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
 | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
@@ -22,9 +22,9 @@ and lifecycle stay consistent. Each sets a status on the spec header
 exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
 (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
 relays its output, so there is no judgment to apply and no model turn spent
-finding one. They are marked `disable-model-invocation`, meaning **only you can
-run them** — a skill that wants one will tell you to type it rather than invoking
-it.
+finding one. They are marked `disable-model-invocation`, meaning
+**only you can run them** — a skill that wants one will tell you to type it
+rather than invoking it.
 
 `/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
 real judgment (green tests before a land; an MCP fetch and a team-key check; ten
@@ -44,10 +44,11 @@ mid-spec (so the work can run in CI / a shared test env) while the spec stays
 
 **Two workspace modes.** `specs/.core/env.config.json` → `mode` decides where a
 spec's branch is built. **`worktree`** (the default) gives each spec its own
-checkout — several specs at once and `main` left free, at the cost of one
-terminal session per spec, which `/spec-start` sets up for you. **`checkout`** builds
-the branch in the primary checkout instead: one spec at a time, but no second
-session and no hand-off, so the terminal you are already in follows the work.
+checkout — several specs at once and `main` left free — and `/spec-start` moves
+the session you typed into *into* that checkout, so the work carries on in the
+same terminal. **`checkout`** builds the branch in the primary checkout instead:
+one spec at a time, and nothing to move into. Neither mode costs you a second
+terminal; the difference is how many specs can be in flight at once.
 Pick it for how you work rather than for what the project contains — a repo with
 no dev servers may still want several specs in flight. In `checkout` mode
 `/spec-connect` and `/spec-live` do not apply and say so: both exist to reach
@@ -86,7 +87,8 @@ feature at the normal URL — no second stack, no proxy. The branch checked out
 the primary checkout **is** the lock: exactly one spec is live at a time, and
 `/spec-live main` hands the instance back (fixes you make while live commit
 straight onto the branch; `/spec-complete` is live-aware and lands them). Rule of
-thumb: **live overlay is the light default for code-only specs**; it *refuses*
+thumb: **live overlay is the light default for *testing* a code-only spec** — it
+is not how work gets started, and no lifecycle skill invokes it; it *refuses*
 stateful ones (`Stack: worktree + docker`, or a branch touching migrations) — keep
 `/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
 Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
@@ -118,6 +120,21 @@ With no provider installed the seams are empty and every skill behaves as a plai
 filesystem workflow. See the provider package's own docs for its config and field
 reference.
 
+**Release gating (opt-in, config-gated).** With
+`specs/.core/gating.config.json` present, every spec `/spec`, `/spec-bug` and
+`/spec-hotfix` write carries a `> **Gating:**` header recording one decision:
+does this ship behind a feature flag, or land live? The value is a **flag name**,
+or **`none: <one-line reason>`** — and the reason half is the load-bearing part,
+because `none: additive, nothing to revert` is a decision a reviewer can argue
+with while a bare `none` is a shrug and a missing line is an oversight.
+
+Skitterspec bakes in **the offer, never the mechanism**: it asks, cites the
+project's own doc (`guidance` in that config), and records the answer. It never
+reads your flag code. `skitterspec gating check` reports specs with no decision
+and **always exits 0** — it reads only `backlog/` and `in-progress/`, so specs
+finished before you adopted gating are out of range by construction. With the
+config absent nothing appears at all: no question, no header, no check.
+
 ## Project conventions (fill this in)
 
 The spec skills tell you to run "your project's typecheck and test commands" and
@@ -160,6 +177,10 @@ Every spec header carries:
   to `git config user.name`).
 - `> **Developer:**` — who implements it (`—` until `/spec-start` starts work, then
   set to `git config user.name`; `/spec-bug` sets it immediately).
+- `> **Gating:**` — the release-gating decision,
+  **only when `specs/.core/gating.config.json` exists**: a flag name, or
+  `none: <one-line reason>`. Absent entirely in a project that has not adopted
+  gating.
 
 Every spec also has a **State log** table — the audit trail of folder/status
 transitions. Each lifecycle skill appends exactly one row when it changes state:

package/assets/skills/spec/SKILL.md

@@ -49,7 +49,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 +118,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 +224,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.
@@ -242,6 +256,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

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

@@ -51,24 +51,12 @@ provision from — you'll flesh it out in §4:
 - 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`.
+- 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
@@ -117,6 +105,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 +168,19 @@ 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

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

@@ -79,8 +79,22 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
    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.
+session's cwd is inside the spec's own worktree, get out **first**, then run the
+teardown commands. How you leave depends on how you got in:
+
+- **`/spec-start` moved this session in** — the normal path in `worktree` mode.
+  Call **`ExitWorktree`** with `action: "keep"`. It restores the session to the
+  directory it started from *and* clears the caches still pointing at the
+  worktree, which a bare `cd` does not: after a `cd` the session stays registered
+  against the tree and asks you about it again when it ends.
+- **You opened the terminal yourself** — `cd` to the primary checkout, as always.
+  `ExitWorktree` is a no-op outside a session it moved, so trying it costs
+  nothing, but the `cd` is what relocates you.
+
+**Always `keep`, never `remove`.** `ExitWorktree` refuses to remove a worktree
+entered by path in any case, and the `spec-env down` plan below has to stay the
+single thing that deletes — a second deleter 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

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

@@ -34,6 +34,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
@@ -63,9 +80,10 @@ git add specs/ && git commit -m "chore(spec): complete <name>"
 ```
 
 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`.
+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`.
 
 ## 5. Report
 
@@ -172,8 +190,22 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
 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.
+session's cwd is inside the spec's own worktree, get out **first**, then run the
+teardown commands. How you leave depends on how you got in:
+
+- **`/spec-start` moved this session in** — the normal path in `worktree` mode.
+  Call **`ExitWorktree`** with `action: "keep"`. It restores the session to the
+  directory it started from *and* clears the caches still pointing at the
+  worktree, which a bare `cd` does not: after a `cd` the session stays registered
+  against the tree and asks you about it again when it ends.
+- **You opened the terminal yourself** — `cd` to the primary checkout, as always.
+  `ExitWorktree` is a no-op outside a session it moved, so trying it costs
+  nothing, but the `cd` is what relocates you.
+
+**Always `keep`, never `remove`.** `ExitWorktree` refuses to remove a worktree
+entered by path in any case, and the `spec-env down` plan below has to stay the
+single thing that deletes — a second deleter 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 +224,16 @@ 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.
+   **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.
 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