@skitterbyte/skitterspec 12.0.0 → 14.0.0

package/README.md

@@ -9,10 +9,10 @@ Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
 ```
 
 Ships the spec-lifecycle skills (`/spec`, `/spec-go`, `/spec-complete`,
-`/spec-cancel`, `/spec-bug`, `/spec-review`, `/spec-init`) plus per-spec
-**isolation** — a git worktree per in-progress spec, Docker on demand, host dev
-servers on reserved ports, and `/spec-connect` to test a worktree at your normal
-`localhost` URL.
+`/spec-cancel`, `/spec-bug`, `/spec-hotfix`, `/spec-review`, `/spec-init`) plus
+per-spec **isolation** — a git worktree per in-progress spec, Docker on demand,
+host dev servers on reserved ports, and `/spec-connect` to test a worktree at your
+normal `localhost` URL.
 
 ```sh
 npx @skitterbyte/skitterspec init
@@ -44,6 +44,17 @@ no external install), so you test at the exact URL you always use.
 `/spec-connect main` hands the ports back. Exclusive: one spec at a time. See
 `specs/.core/env.config.md` for the `dev`/`proxy` config.
 
+## Production hotfixes — `/spec-hotfix`
+
+When prod is on a tagged release, a fix must be built on **that** version, not
+`main`. `/spec-hotfix <tag> <name>` forks a worktree from the tag, then works
+test-first like `/spec-bug`. `/spec-complete` lands it by patch-bumping the tag
+and tagging the branch (your CI/CD deploys the tag — you push it) and
+cherry-picking the fix onto `main`; `--also <tag>` patches extra release lines
+(test/demo). Hotfixes refuse `/spec-live` (their old-tag branch could break the
+running instance) — test them with `/spec-connect`. Tune the `hotfix` block in
+`specs/.core/env.config.md`.
+
 ## v3 — slimmer surface + `/spec-connect`
 
 **3.0** folds provisioning into `/spec-go`, teardown into

package/assets/core/env.config.md

@@ -4,8 +4,8 @@ Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
 stack + host dev servers + a front-door proxy + an optional opener per
 in-progress spec). Provisioning is folded into `/spec-go`, teardown into
 `/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
-`skitterspec spec-env <up|down|dev|connect|integrate>` CLI is the engine beneath
-them.
+`skitterspec spec-env <up|down|prune|dev|connect|integrate>` CLI is the engine
+beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-go` gives
 **every** in-progress spec its own git worktree automatically. Docker is a **per-
@@ -155,6 +155,20 @@ no live `env.config.json` was found.
   // refuses it (code-only v1 — use `/spec-connect` for those). Default: none.
   "live": {
     "migrations": []
+  },
+
+  // Hotfix landing (`spec-env hotfix land` / `/spec-complete` on a Type: Hotfix
+  // spec). A hotfix forks from a release tag and lands by tag + cherry-pick, not
+  // fast-forward. `bump` is the version-bump strategy for the new deploy tag (only
+  // "patch" today: v33.16.4 -> v33.16.5). `cherryPickMain` also cherry-picks the
+  // fix onto the base branch for the next release (default true). `targets` is an
+  // optional default list of extra base tags to also patch (test/demo lines);
+  // `--also <tag>` adds more at run time. Nothing is ever pushed — you push the
+  // deploy tag to trigger CI/CD. Default: patch, main, none.
+  "hotfix": {
+    "bump": "patch",
+    "cherryPickMain": true,
+    "targets": []
   }
 }
 ```
@@ -165,3 +179,26 @@ no live `env.config.json` was found.
 - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
   (safe for a `COMPOSE_PROJECT_NAME`).
 - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).
+
+## Pruning orphaned test-DB volumes
+
+`spec-env down` drops the finished spec's own Docker volume, but volumes leak
+when that path is skipped — a declined/guard-aborted teardown, a manual
+`git worktree remove`, or `--keep-volumes`. Over many worktrees these orphaned
+DB volumes pile up and eat disk.
+
+`skitterspec spec-env prune` reconciles the live volumes in the
+`{repoSlug}_*` namespace against the specs that still have a **worktree** and
+lists the orphans (volumes owned by no live spec) plus the `docker volume rm`
+commands to remove them. It plans only — you run the printed commands — and it
+frees any stale registry slot for a reaped spec.
+
+- **Liveness = an existing worktree, not the registry** (the registry is what
+  goes stale). A spec with a live worktree — in any bucket, including one checked
+  out only on its branch — is always protected.
+- **No backup.** Unlike `spec-env down`, prune does **not** run
+  `backupCommand`: an orphan has no running DB to dump. Add `--older-than <days>`
+  to only reap volumes older than a cutoff (volumes of unknown age are kept).
+- `/spec-complete` and `/spec-cancel` run prune (confirm-first) as their last
+  teardown step, so orphans get swept as specs finish. You can also run it by
+  hand at any time to clear an existing backlog.

package/assets/rules/spec-planning.md

@@ -1,6 +1,6 @@
 # Spec Planning
 
-Spec-driven development is driven by seven lifecycle skills (plus `/spec-connect`
+Spec-driven development is driven by nine lifecycle skills (plus `/spec-connect`
 when isolation is on) — use them rather than hand-rolling specs so the structure
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
@@ -9,8 +9,10 @@ and lifecycle stay consistent. Each sets a status on the spec header
 |-------|---------|--------|--------|
 | `/spec` | (Feature) Grill to a clear shared understanding, then write a groomed spec | `Ready` (or `Draft`) | `specs/backlog/` |
 | `/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-go` | Provision the env, bring dev servers up, implement the next phase | `In Progress` | `specs/in-progress/` |
+| `/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/` |
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
@@ -18,8 +20,12 @@ and lifecycle stay consistent. Each sets a status on the spec header
 Status flow: `Ready → In Progress → Complete` (or `Cancelled` from any state).
 `/spec` grills to a **Ready** spec directly — there is no separate grooming
 command; it writes `Draft` only when open questions are deliberately left.
-`/spec-bug` is test-first and starts straight in `In Progress` (work begins
-immediately), so it skips Draft/Ready.
+`/spec-bug` and `/spec-hotfix` are test-first and start straight in `In Progress`
+(work begins immediately), so they skip Draft/Ready. `/spec-to-main` does **not**
+move the spec through the flow at all — it lands the branch on the base branch
+mid-spec (so the work can run in CI / a shared test env) while the spec stays
+`In Progress` in `specs/in-progress/`; it's the intermediate, repeatable half of
+`/spec-complete`'s landing, without the finalise-and-tear-down.
 
 **Per-spec isolation (opt-in to adopt, then the default policy).** When a project
 adopts isolation (`skitterspec init --isolation`, or `specs/.core/env.config.json`
@@ -35,9 +41,14 @@ your canonical `localhost` ports so you can test it at the normal URL
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|down|dev|connect|integrate>` is the CLI engine. Isolation is **orthogonal to
-lifecycle status** and inactive when `env.config.json` is absent — every skill
-then behaves as it does today.
+<up|down|prune|dev|connect|integrate|hotfix>` is the CLI engine. Teardown drops
+the finished spec's own test-DB volume; `spec-env prune` additionally reaps
+**orphaned** volumes left by declined/aborted teardowns, so `/spec-complete` and
+`/spec-cancel` also sweep orphans (confirm-first). A **hotfix** is the one
+exception to "fork from `main`": `/spec-hotfix` forks the worktree from a release
+tag and `/spec-complete` lands it via `spec-env hotfix land` (tag + cherry-pick),
+not a fast-forward. Isolation is **orthogonal to lifecycle status** and inactive
+when `env.config.json` is absent — every skill then behaves as it does today.
 
 **Live overlay (`/spec-live`) — the light way to test a spec.** `/spec-connect`
 runs a spec's *own* dev stack and proxies the canonical ports to it (one stack per
@@ -77,16 +88,24 @@ consistent with the codebase:
 - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
   (architecture, code style, testing, database, etc.) rather than restating them.
 
-## Spec types — Feature vs Bug
+## Spec types — Feature, Bug, Hotfix
 
-Every spec is one of two types, recorded **both** in the header and the filename:
+Every spec is one of three types, recorded **both** in the header and the filename:
 
-- **Header field:** `> **Type:** Feature` or `> **Type:** Bug` (authoritative,
-  greppable: `grep -rl 'Type:.*Bug' specs/`).
-- **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs
-  (visible in listings; glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
+- **Header field:** `> **Type:** Feature`, `> **Type:** Bug`, or
+  `> **Type:** Hotfix` (authoritative, greppable:
+  `grep -rl 'Type:.*Hotfix' specs/`).
+- **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs,
+  `hotfix-<name>` for hotfixes (visible in listings; glob-safe — never use
+  `[BUG]`/`[FEATURE]` brackets).
 
-Both types share the same lifecycle folders below — type is orthogonal to status.
+A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
+carries an extra `> **Base version:** <tag>` header, forks its worktree from that
+tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
+fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
+
+All three types share the same lifecycle folders below — type is orthogonal to
+status.
 
 ## Header fields & State log (audit trail)
 
@@ -140,9 +159,11 @@ Every spec is a **folder** `specs/<bucket>/<name>/` — never a bare file, even
 simple changes. Inside it:
 
 - `00-overview.md` is the entry point / dashboard: header, Problem, Decisions,
-  Solution overview, the **phase index** (a table linking to each phase file with
-  its status), Open questions, State log, Changelog. **No per-phase task lists
-  live here.**
+  Solution overview, the **Impact map** (a `Surface | Change | Detail` table
+  naming the concrete surfaces the spec touches — endpoints, schemas, DB tables,
+  domain objects, routes, business rules — as the scannable blast radius), the
+  **phase index** (a table linking to each phase file with its status), Open
+  questions, State log, Changelog. **No per-phase task lists live here.**
 - **One file per phase** — `01-<phase-slug>.md`, `02-<phase-slug>.md`, … in
   execution order. Each holds that phase's goal, its task checkboxes (tests
   included), and any phase-specific notes. Even a single-phase spec gets `01-….md`

package/assets/skills/spec/SKILL.md

@@ -96,6 +96,26 @@ the spec — be specific.>
 <Short prose or bullets describing the chosen shape end-to-end. Optional small
 schema/grammar/output snippets where they remove ambiguity.>
 
+## Impact
+
+<The concrete surfaces this spec touches — the scannable blast radius, so a
+reader can eyeball where the spec got something wrong without reading prose.
+`Change` is `add` · `update` · `remove`. `Surface` is guided-but-open: use
+values like Endpoint, Route/UI, Schema/model, DB table/migration, Domain object,
+Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
+this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
+terse — names/signatures, not sentences. List **only** surfaces that actually
+change; the heading is always present, but if nothing external changes write the
+single line below instead of an empty table.>
+
+| Surface | Change | Detail |
+|---------|--------|--------|
+| <e.g. Endpoint> | add | <e.g. POST /orders> |
+| <e.g. DB> | update | <e.g. orders (+status col)> |
+
+<_No external surface changes — internal refactor only._ — use this line in
+place of the table when the spec touches no external surface.>
+
 ## Phases
 
 Each phase lives in its own file in this folder. Status: ⬜ not started ·
@@ -163,6 +183,13 @@ 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.
 - **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.

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

@@ -120,6 +120,26 @@ because work is already underway. Keep it lean:
       commands — confirm no regressions.
 - [ ] <any follow-up hardening, or "None">
 
+## Impact
+
+<The concrete surfaces this spec touches — the scannable blast radius, so a
+reader can eyeball where the spec got something wrong without reading prose.
+`Change` is `add` · `update` · `remove`. `Surface` is guided-but-open: use
+values like Endpoint, Route/UI, Schema/model, DB table/migration, Domain object,
+Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
+this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
+terse — names/signatures, not sentences. List **only** surfaces that actually
+change; the heading is always present, but if nothing external changes write the
+single line below instead of an empty table. A bug fix often changes no external
+surface — that's fine, use the one-liner.>
+
+| Surface | Change | Detail |
+|---------|--------|--------|
+| <e.g. Endpoint> | update | <e.g. GET /orders (fix null total)> |
+
+<_No external surface changes — internal refactor only._ — use this line in
+place of the table when the spec touches no external surface.>
+
 ## State log
 
 | Date | Status | Folder | By |

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

@@ -64,5 +64,10 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 3. `skitterspec spec-env down <name>` — then execute the printed commands to
    remove the worktree/stack and free the slot. It respects the teardown guards
    (won't destroy a dirty/unpushed worktree without `--force`).
+4. `skitterspec spec-env prune` — reap orphaned test-DB volumes that belong to no
+   live spec (leftovers from declined/aborted teardowns or manual worktree
+   removal). Show the orphan list and, **only on the user's confirmation**, run
+   the printed `docker volume rm` commands. Non-fatal: if it can't run or the user
+   declines, report and finish cancelling anyway.
 
 If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -21,8 +21,9 @@ Before marking complete, confirm the work is actually finished:
   done in the code — tick it (`- [x]`) if so, or surface it if not.
 - Run the project's typecheck and test commands. The suite must be **green** to
   call a spec complete.
-- For a **Bug** spec (`Type: Bug`), confirm the originally-failing test named in
-  the spec now passes — that test is the proof the bug is fixed.
+- For a **Bug** or **Hotfix** spec (`Type: Bug` / `Type: Hotfix`), confirm the
+  originally-failing test named in the spec now passes — that test is the proof
+  the fix works.
 - If genuinely incomplete work remains, **stop and tell the user** rather than
   forcing completion. Offer to finish it (`/spec-go`) or to complete with the
   remaining items explicitly listed as deferred.
@@ -51,13 +52,45 @@ specs — `git log`/the per-spec State log give the completion order.
 Confirm the move, the final test result, and list anything deferred. Do **not**
 `git commit` unless the user asks.
 
-## 6. Integrate onto the base branch (opt-in, only if isolated)
+## 6. Land the branch (opt-in, only if isolated)
 
 **Only when `specs/.core/env.config.json` exists and the spec is on a worktree**
-(it was provisioned by `/spec-go`). Otherwise skip this entirely — a non-isolated
-spec has nothing to land, and `/spec-complete` behaves exactly as before. When it
-applies, offer to land the finished branch on the base branch so the work reaches
-`main` (or your configured `baseBranch`) in one flow:
+(it was provisioned by `/spec-go` or `/spec-hotfix`). Otherwise skip this entirely
+— a non-isolated spec has nothing to land, and `/spec-complete` behaves exactly as
+before. When it applies, offer to land the finished branch so the work reaches its
+destination in one flow. **How it lands depends on the spec type:**
+
+### 6-hotfix. `Type: Hotfix` — tag + cherry-pick (not fast-forward)
+
+A hotfix is built on an old release **tag**, so it can't fast-forward onto `main`.
+Use the hotfix landing instead of the integrate steps below:
+
+1. **Require a clean worktree** — the completion edits (status flip, `git mv` to
+   `complete/`) must be committed first. If dirty, offer `/commit` and **stop**.
+2. **Plan + execute.** Run `skitterspec spec-env hotfix land <name>` — add
+   `--also <tag>` for each extra release line to patch (test/demo on their own
+   versions). Run the printed commands **in order**. It:
+   - tags the hotfix branch with the **patch-bumped base tag** (the deploy tag) —
+     **created locally; you push it** (`git push origin <tag>`) to trigger CI/CD;
+   - for each `--also` target, cherry-picks the fix onto a throwaway worktree at
+     that tag and re-tags it;
+   - cherry-picks the fix onto `main` for the next release.
+   On a **cherry-pick conflict** (non-zero exit), run `git -C <checkout>
+   cherry-pick --abort` there, relay the conflict, and **stop** — don't offer
+   teardown.
+   On a **no-op** ("nothing to land"), say so and continue.
+3. **Re-test on `main`** after the cherry-pick — it must be **green**.
+4. **Report** the deploy tag(s) and the `main` cherry-pick. It **never pushes** —
+   remind the user to `git push origin <deploy-tag>` to deploy. Then teardown
+   (step 7) applies: a tagged hotfix branch tears down with **no `--force`**.
+
+### 6-feature/bug. `Type: Feature` / `Type: Bug` — rebase + fast-forward
+
+Land the finished branch on the base branch so the work reaches `main` (or your
+configured `baseBranch`) in one flow. (Need the work on `main` *before* the spec
+is finished — e.g. to run a later phase in CI or a shared test env? Use
+**`/spec-to-main`**: same rebase + fast-forward, but it leaves the spec
+`In Progress` and the worktree standing, and it's repeatable.)
 
 1. **Require a clean worktree.** The completion edits (status flip, the
    `git mv` to `complete/`) must be committed first — integrate refuses a dirty
@@ -68,6 +101,16 @@ applies, offer to land the finished branch on the base branch so the work reache
    the normal landing plan. Commit any live fixes to the branch first; it refuses
    if the primary checkout is dirty, or if a *different* spec holds it (release that
    one with `/spec-live main`). Teardown (step 7) is unchanged.
+   **Work-loss abort.** Before it ends the live session, `integrate` checks the
+   work is actually landable and **aborts loudly** rather than finalize a spec
+   having landed nothing. Two cases, both leaving the live session intact:
+   - *stranded commits* — commits sit on the worktree's **detached HEAD** (e.g. a
+     pre-fix `/spec-go` committed there instead of on the branch). It prints the
+     count, the sha, and a `git -C <worktree> branch <tmp> <sha>` recovery hint —
+     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.
 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.
@@ -93,9 +136,20 @@ 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. Post-integrate the branch is
-   merged into base, so teardown needs **no `--force`** and deletes the branch
-   (`git branch -d`) as part of the plan. It still respects the guards (won't
-   destroy a dirty or unpushed-and-unmerged worktree without `--force`).
+   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`).
+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").
 
 If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -22,9 +22,24 @@ Diverting your browser to the spec is a separate explicit step — `/spec-connec
 
 ## 2. Move it into development
 
-**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists) and
-the spec doesn't already have a worktree, provision it **first**, so all the
-housekeeping below lands on the spec's branch and never on `main`:
+**Live check first (isolation only).** If per-spec isolation is enabled, before
+provisioning run `skitterspec spec-env live status <name>` and read its `live:`
+line. If it says **`live: yes`**, this spec is already checked out in the
+**primary checkout** (you took it live with `/spec-live`) — **do not provision,
+do not run `spec-env up`, and do not "work in the worktree"**. Its branch lives
+in the primary checkout and its worktree is on a **detached HEAD**, so a commit
+made in the worktree would strand on that detached HEAD and never reach the
+branch. Instead skip the provisioning bullets and step 2b, leave the spec where
+it is, and go straight to **step 4**, implementing the phase **in the primary
+checkout on the branch** — edits and commits there advance the branch, and
+`/spec-complete` lands them. (`spec-env up` refuses while live and says the same.
+To return to an isolated worktree instead, run `/spec-live main` first, then
+re-run `/spec-go`.)
+
+**If per-spec isolation is enabled** (`specs/.core/env.config.json` exists), the
+spec **isn't already live** (the check above), and it doesn't already have a
+worktree, provision it **first**, so all the housekeeping below lands on the
+spec's branch and never on `main`:
 
 **Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
 place), skip the provisioning bullets below and build on the current branch — the

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

@@ -0,0 +1,181 @@
+---
+name: spec-hotfix
+description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green like /spec-bug, then land it by tagging a new patch (for CI/CD to deploy) and cherry-picking the fix back onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Creates specs/in-progress/hotfix-<name>/00-overview.md. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
+---
+
+# /spec-hotfix — fix a released version, tag it, cherry-pick back to main
+
+This is the **hotfix** counterpart to `/spec-bug`. Same test-first discipline
+(reproduce as a **failing test (RED)**, then drive to **GREEN**), but the base is
+a **release tag**, not `main`: prod is running a tagged version, so the fix must
+be built on **that** commit line, shipped as a **new patch tag** (your CI/CD
+deploys tags), and only then cherry-picked onto `main` for the next release.
+
+Spec type convention (see `.claude/rules/spec-planning.md`):
+- Hotfix specs are named `hotfix-<kebab-name>`; every header carries
+  `> **Type:** Hotfix` and `> **Base version:** <tag>`.
+- Branch is `hotfix/<slug>`, forked from the base tag.
+
+**Isolation is required.** A hotfix forks a worktree from a tag and lands by
+tag + cherry-pick — it needs the isolation engine (`specs/.core/env.config.json`).
+If isolation is absent, say so and stop; there is no in-place path.
+
+## 1. Establish the base version (the tag)
+
+- Take the release tag from the argument — `/spec-hotfix <tag> <name>` (e.g.
+  `/spec-hotfix v33.16.4 login-crash`). If it's missing, **ask which version prod
+  is running** — don't guess.
+- **Verify the tag exists** before anything else:
+  `git rev-parse --verify <tag>^{commit}`. If it doesn't resolve, stop and ask.
+
+## 2. Reproduce & isolate (light investigation)
+
+Hotfixes are concrete — confirm, don't over-grill. Establish:
+
+- **Repro:** exact steps / input that triggers it on the released version.
+- **Expected vs actual:** what *should* happen vs what does.
+- **Root cause:** read the code **at the base tag** and trace it to `file:line`.
+  The fix belongs on the tag's line, so reason about that code, not `main`'s.
+
+## 3. Seed the stub, then provision the worktree from the tag
+
+The engine forks the worktree from the spec's `Base version`, so the stub — with
+that header — must exist **before** `spec-env up`:
+
+- From the base branch (`main`), create
+  `specs/in-progress/hotfix-<name>/00-overview.md` with the header block
+  (including `> **Type:** Hotfix` and `> **Base version:** <tag>`) and the
+  `## Symptom` you established. It starts in `in-progress` — work begins now.
+- Run `skitterspec spec-env up hotfix-<name>`. It prints a `git worktree add …
+  -b hotfix/<slug> <tag>` command (the branch forks from **the tag**, not
+  `main`), the worktree path, the opener, and any `in the worktree, run:`
+  bootstrap steps.
+- Run the printed `git worktree add`. **The worktree is checked out at the tag,
+  so your uncommitted stub doesn't travel with it** — move it across so `main`
+  stays pristine:
+  `mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/`.
+- **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
+  anything else.
+- **Trust the worktree for this session.** The engine wrote the printed
+  `trusted:` root into `.claude/settings.local.json`, but it won't hot-reload now
+  — run `/add-dir <trusted root>` before editing into the worktree, or the first
+  edits will prompt.
+- **Do everything below in the worktree**, on the `hotfix/<slug>` branch — the red
+  test, the fix, and the rest of the spec. Act with absolute paths /
+  `git -C <worktreePath>`, or open a fresh session rooted there. `main` changes
+  only at `/spec-complete` (via cherry-pick, not merge).
+
+## 4. Write the failing test FIRST (RED) — mandatory
+
+Encode the **correct** (expected) behaviour as a test, then run it and confirm it
+**fails for the right reason**, on the hotfix branch:
+
+- Put it where the suite already covers that area. Reuse existing test helpers /
+  factories; follow the project's test rules (see `.claude/rules/`). Never
+  hardcode dates — compute them relative to now.
+- Run it with the project's test command. Quote the red output. A test that
+  passes before the fix proves nothing — keep refining until it genuinely
+  captures the bug on this version.
+
+## 5. Write the Hotfix spec
+
+Flesh out `00-overview.md` in the worktree (you seeded the stub in §3). A hotfix
+is usually a single-pass fix, so the `## Fix` block can live directly in
+`00-overview.md`. Keep it lean:
+
+```markdown
+# Hotfix: <short title>
+
+> **Type:** Hotfix
+> **Status:** In Progress — fixing (red test added)
+> **Author:** <git user.name — who reported/captured it>
+> **Developer:** <git user.name — you, since you're fixing it now>
+> **Base version:** <tag prod is running, e.g. v33.16.4>
+> **Raised:** <YYYY-MM-DD (today)>
+> **Area:** <files/modules>
+
+## Symptom
+
+<observed wrong behaviour on the released version + repro steps; paste any error>
+
+## Root cause
+
+<the actual cause, at `file:line` on the base tag. One paragraph — be specific.>
+
+## Failing test (red)
+
+<test name + path; what it asserts. How to run it. Paste the red failure line.>
+
+## Fix
+
+- [ ] <the minimal change that addresses the root cause, not the symptom>
+- [ ] Failing test now passes (GREEN); run the project's typecheck and test
+      commands — confirm no regressions.
+- [ ] <any follow-up hardening, or "None">
+
+## Impact
+
+<The concrete surfaces this spec touches — the scannable blast radius, so a
+reader can eyeball where the spec got something wrong without reading prose.
+`Change` is `add` · `update` · `remove`. `Surface` is guided-but-open: use
+values like Endpoint, Route/UI, Schema/model, DB table/migration, Domain object,
+Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
+this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
+terse — names/signatures, not sentences. List **only** surfaces that actually
+change; the heading is always present, but if nothing external changes write the
+single line below instead of an empty table. A hotfix should be minimal — often
+no external surface changes; that's fine, use the one-liner.>
+
+| Surface | Change | Detail |
+|---------|--------|--------|
+| <e.g. Endpoint> | update | <e.g. GET /orders (fix null total)> |
+
+<_No external surface changes — internal refactor only._ — use this line in
+place of the table when the spec touches no external surface.>
+
+## Landing
+
+- [ ] Deploy tag (patch bump of the base version) created at `/spec-complete`
+      and pushed **by you** to trigger CI/CD.
+- [ ] Fix cherry-picked onto `main` (and any `--also` release lines).
+
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| <YYYY-MM-DD> | In Progress | in-progress | <developer> |
+
+## Changelog
+
+- <YYYY-MM-DD> — Hotfix reproduced on <tag>; failing test added (red).
+```
+
+Keep the **State log** (state transitions) separate from the **Changelog** (fix
+narrative and decisions).
+
+## 6. Drive to GREEN
+
+- Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
+  honour all project rules (see `.claude/rules/`).
+- Re-run the failing test → it must pass. Then run the project's typecheck and
+  test commands to confirm no regressions. Quote results.
+- Commit the fix to the `hotfix/<slug>` branch (this commit is what gets tagged
+  and cherry-picked). Tick the Fix tasks; add a Changelog line.
+
+## 7. Report
+
+Summarise: the base tag, root cause, the failing→passing test, the fix, and the
+full test result. The spec stays in `in-progress`.
+
+- **`/spec-live` is refused for a hotfix** — its branch is built on an old tag, so
+  hot-reloading it onto the running dev server could break the shared instance.
+  To test it, use `/spec-connect` (its own isolated stack).
+- Suggest **`/spec-complete`** to land it: it patch-bumps the base tag, tags the
+  hotfix branch **locally** (you push it to deploy), and cherry-picks the fix onto
+  `main`. Add `--also <tag>` at completion to also patch other release lines
+  (test/demo on their own versions).
+
+Do **not** `git push` or `git tag`-and-push unless the user asks — deploying to
+prod is theirs to trigger.

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

@@ -18,7 +18,10 @@ absent, say so and stop.
 **Code-only.** Live overlay refuses a **stateful** spec — one whose `> **Stack:**`
 is `worktree + docker`, or whose branch changes migrations (per
 `env.config.json` → `live.migrations`). Those keep their isolated stack; use
-`/spec-connect` for them. The engine enforces this and prints why.
+`/spec-connect` for them. It also **always refuses a `Type: Hotfix` spec** — its
+branch is built on an old release tag, so hot-reloading it onto the running dev
+server could break the shared instance; test a hotfix with `/spec-connect`. The
+engine enforces all of this and prints why.
 
 ## 1. Identify the target
 

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

@@ -26,6 +26,13 @@ trust the spec's own wording — verify:
 - **Referenced things still exist.** Grep/read for each `file:line`, module,
   function, route, model, type, or symbol the spec names. Flag anything renamed,
   moved, or deleted.
+- **Impact map matches reality.** Walk every row of the `## Impact` table and
+  verify against the code: does the named surface (endpoint, schema/model, DB
+  table/migration, domain object, route, business rule) exist, and does its
+  stated `Change` (add/update/remove) still hold? A stale Impact map is the
+  highest-signal drift — each row is a named, checkable surface, so a wrong row
+  is exactly the "obvious mistake" the map exists to surface. Flag/refresh stale
+  rows (and add rows for surfaces the spec now touches but omits).
 - **Tasks already done.** For each `- [ ]`, check whether the code already
   implements it (it may have landed via other work). Tick `- [x]` what's done.
 - **Decisions still valid.** Re-check each `## Decisions` entry against the
@@ -47,9 +54,9 @@ reading the code, do that instead of asking.
 
 ## 4. Update the spec
 
-- Rewrite stale **Decisions** / **Solution overview** in `00-overview.md` and
-  stale **tasks** in the phase files so they match the current code and the
-  resolved questions. Add/remove tasks within a phase file; add a new phase by
+- Rewrite stale **Decisions** / **Solution overview** and refresh the **Impact
+  map** in `00-overview.md`, and stale **tasks** in the phase files, so they
+  match the current code and the resolved questions. Add/remove tasks within a phase file; add a new phase by
   creating a `0N-<slug>.md` file **and** a matching overview index row, or drop a
   dead phase by removing both. Keep the index and files in sync; **preserve
   completed `[x]` history**.