@skitterbyte/skitterspec 17.0.0 → 18.0.0

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

@@ -63,9 +63,12 @@ that header — must exist **before** `spec-env up`:
   -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. **Create the destination bucket first:**
+- Run the printed `git worktree add`, then **move the stub across yourself.**
+  This is where a hotfix differs from `/spec-bug`, which no longer needs the move:
+  that skill's worktree forks from `main`, so committing the stub puts it there,
+  while **this worktree is checked out at the tag** — a commit on `main` is not in
+  it and never will be. The move is not redundant here; keep it.
+  **Create the destination bucket first:**
 
   ```
   mkdir -p <worktreePath>/specs/in-progress
@@ -74,14 +77,13 @@ that header — must exist **before** `spec-env up`:
 
   The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
   `specs/in-progress/` is **absent** from the worktree whenever nothing was in
-  progress at that point in history — and here that point is an **old release
-  tag**, where it is absent more often than not. `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/hotfix-<name>/00-overview.md`.
-- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  progress at that point in history — and here that point is an
+  **old release tag**, where it is absent more often than not. `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/hotfix-<name>/00-overview.md`. - **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.
@@ -123,6 +125,8 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
 > **Base version:** <tag prod is running, e.g. v33.16.4>
 > **Raised:** <YYYY-MM-DD (today)>
 > **Area:** <files/modules>
+> **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
+> when release gating is configured, and overridable — see below>
 
 ## Symptom
 
@@ -189,6 +193,21 @@ narrative and decisions).
 
 
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** A hotfix is the one spec
+type that does **not** ask the question cold: it writes
+`none: hotfix — restoring released behaviour` and asks only for confirmation.
+
+The default differs on purpose. A hotfix restores behaviour a release already
+had, under time pressure, and the fix is captured by a deploy tag rather than
+riding the next release — so a flag has nothing to gate and nothing to roll back
+to. Making someone answer a design question mid-incident buys nothing.
+
+It is a **default, not a rule**: say what you are writing and let the user
+override it. If they name a flag, record that instead. Skip entirely when the
+config is absent.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;

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

@@ -37,6 +37,19 @@ checkout you are already in; one spec at a time, no hand-off). It is a question
 about how the operator works, not about what the repo contains, so ask rather
 than infer it from whether dev servers or Docker are configured.
 
+## 0b. Release gating (optional, and separate)
+
+Ask whether specs should record a **release-gating** decision — does this change
+ship behind a feature flag, or land live? Adopting it copies
+`specs/.core/gating.config.json.example` → `gating.config.json` and sets
+`guidance` to wherever this project documents its flags.
+
+It is **orthogonal to isolation**: a project can adopt either, both, or neither.
+Skitterspec never learns how the flags work — it asks the question, cites that
+path, and records the answer on each spec. Leave it off and nothing appears:
+no question, no header, no check. Off is a perfectly good answer for a project
+that does not use flags.
+
 ## 1. Folders
 
 Create any that are missing; drop a `.gitkeep` into ones that would otherwise be
@@ -80,8 +93,8 @@ Ensure it exists. If missing, create it documenting:
 - the **Author** / **Developer** header fields;
 - the **State log** audit table (folder/status transitions), kept separate from
   the **Changelog** (decisions);
-- the project's concrete typecheck/test commands, and the rule that **every
-  phase ends with creating + running tests**.
+- the project's concrete typecheck/test commands, and the rule that
+  **every phase ends with creating + running tests**.
 
 Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
 rather than inventing them. If the rule already exists, leave it unless stale.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-next
-description: Build the next unfinished phase of the spec currently in flight on this checkout — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
+description: Build the next unfinished phase of the spec in flight for this session — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one, and never builds a spec it is not standing in. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
 ---
 
 # /spec-next — build the next phase of the spec in flight
@@ -26,7 +26,7 @@ Resolve **in this order**, and stop at the first that answers:
    branch the checkout is on names the spec.
 
 **If none answers, refuse and stop:**
-`no spec in flight — run /spec-start <name> to put one on this checkout`.
+`no spec in flight — run /spec-start <name> to start one`.
 
 **Never fall back to the spec "in context".** A spec discussed in conversation
 is not a spec in flight, and this skill writes real code: building the wrong

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

@@ -44,6 +44,19 @@ trust the spec's own wording — verify:
 - **Backward compatibility.** Re-confirm the planned API/schema changes are still
   additive/safe given the current code (see the project's compatibility rules).
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>`. A spec it names has no recorded gating
+decision — or a bare `none` that records nothing — and that is
+**drift like any other**: the question was never asked, or its answer was lost. Grill for it in
+step 3 and write the header in step 4, exactly as you would a stale file path.
+
+**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. Grill only where a decision is needed
 
 Where the drift forces a choice (the old approach no longer fits, a referenced
@@ -54,12 +67,12 @@ resolve it by reading the code, do that instead of asking.
 
 ## 4. Update the spec
 
-- 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**.
+- 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**.
 - **A phase's status is the `⬜`/`🔄`/`✅` on its H1** — `# Phase 2 — <goal> 🔄`.
   It is mirrored in that file's `> **Status:**` line and in the matching
   `00-overview.md` phase-index row, but the **heading is the authoritative one**:

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

@@ -1,6 +1,6 @@
 ---
 name: spec-start
-description: Put a spec in flight on this checkout — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Refuses unless the checkout is on the base branch with nothing already in flight, so it never parks or swaps someone's unfinished work. Use when the user says "/spec-start", "start this spec", or "begin implementing <spec>".
+description: Put a spec in flight — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Commits the spec itself when that is all that is uncommitted, and refuses to touch anyone else's unfinished work. Use when the user says "/spec-start", "start this spec", or "begin implementing <spec>".
 ---
 
 # /spec-start — put a spec in flight
@@ -12,30 +12,49 @@ finishing it is `/spec-complete`.
 
 ## 1. The gate — refuse unless the workbench is free
 
-**Check this first, before resolving anything or touching a file.** In
-`worktree` mode run `skitterspec spec-env live status`; in `checkout` mode read
-the current branch. The workbench must be:
+**Check this first, before resolving anything or touching a file.** What the
+gate demands depends on the mode, because the two modes hold work in different
+places — read `mode` from `specs/.core/env.config.json` (default `worktree`).
 
-- **on the base branch** (`main`, or the configured `baseBranch`), and
-- **clean** — no uncommitted changes.
+**`worktree` mode — the tree must be clean, and that is all.** The spec is built
+in its own worktree, so another spec being in flight is not a conflict; it is the
+parallelism the mode exists for. The only requirement is that this checkout has
+no uncommitted work — *except* the spec you are starting, which `spec-env up`
+commits for you (see below). Nothing is switched here and nothing is parked.
 
-**If it isn't, relay what is in flight and stop.** Name the spec holding the
-checkout and the three ways out, then end your turn:
+**`checkout` mode — the workbench must be free**: on the base branch (`main`, or
+the configured `baseBranch`) and clean, since the branch is built right here and
+this mode holds one spec at a time. If it isn't, relay what is in flight and
+stop — name the spec holding the checkout and the two ways out, then end your
+turn:
 
 - **`/spec-complete`** — it's finished; land it and free the workbench.
 - **`/spec-cancel`** — it isn't wanted; record why and free the workbench.
-- **`/spec-live main`** *(worktree mode)* — park it: the branch goes back to its
-  worktree and stays exactly as it is, ready to resume later.
 
-**Never get past the gate yourself.** Do not stash, do not commit on the
-operator's behalf, do not `/spec-live main` for them, do not switch branches. An
-uncommitted tree, a half-built phase and a rebase are each a decision someone
-must make deliberately — and the cost of guessing is another spec's work moved
-without its author asking. A refusal costs one command; the alternative can cost
-an afternoon.
+**Never get past the gate yourself.** Do not stash, do not commit
+**another spec's** work, do not switch branches for them. An uncommitted tree
+and a half-built phase are each a decision someone must make deliberately — and
+the cost of guessing is another spec's work moved without its author asking. A
+refusal costs one command; the alternative can cost an afternoon.
 
-A dirty tree is refused *with the same words whatever the cause*: the gate does
-not try to judge whether the changes look important.
+**The one exception is the spec you are starting.** `spec-env up` classifies the
+uncommitted tree against the target spec and answers one of three ways — relay
+what it says rather than deciding for yourself:
+
+| What it found | What it does |
+|---------------|--------------|
+| clean | provisions, as always |
+| every path belongs to this spec | plans `git add` + `git commit` **first**, then the fork |
+| any path does not | refuses, naming the paths that disqualified it |
+
+That is membership in an exactly-known set — the spec's own folder plus the
+project's `spec.companionPaths` — and **not** a judgement about whether the
+changes look important. The gate still never decides that. When it plans the
+commit, the paths are printed above the commands, so run them as printed; when it
+refuses, relay the reason and stop.
+
+It also refuses a **clean** tree whose spec is not in the commit the worktree
+would fork from — otherwise you get a branch missing the very spec it is for.
 
 ## 2. Identify the spec
 
@@ -48,51 +67,88 @@ not try to judge whether the changes look important.
   spec is a `<name>/` folder whose entry point is `00-overview.md`, with one
   file per phase beside it (`01-<slug>.md`, `02-…`). Legacy specs may be a bare
   `<name>.md`, or a `00-overview.md` with inline phases — handle those too.
-- A spec already in `specs/in-progress/` was started before. If its branch is
-  parked in a worktree, this skill brings it back into flight; say so rather
-  than reporting a fresh start.
-
-## 3. Put its branch in this checkout
+- A spec already in `specs/in-progress/` was started before. Its worktree
+  probably still exists, so this is a re-attach: say so rather than reporting a
+  fresh start, and skip the housekeeping that is already done.
 
-**Read `mode` from `specs/.core/env.config.json`** (default `worktree`).
+## 3. Build its branch
 
 ### `worktree` mode
 
 1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
-   `to provision, run:` commands it prints and confirm they succeeded. Then run
-   its **`then, in the worktree, run:`** steps in order (file seeding, then
-   `setup`): a fresh worktree has no dependencies and none of the repo's
-   gitignored files, so hooks, typechecks and tests fail until they are there.
-2. **Bring the branch here.** Tell the user to type **`/spec-live <name>`** — it
-   rebases the branch, frees it from the worktree and checks it out in this
-   checkout, which is what makes this session the workbench. It is a user-only
-   command, so you cannot run it: print it, end your turn, and pick up at step 4
-   when they re-run `/spec-start`.
-   **Already here?** If the live check in step 1 showed this spec live, or the
-   branch is already checked out, the move is done — carry straight on.
-3. **A spec the live overlay refuses** — a hotfix, a stateful spec
-   (`Stack: worktree + docker`), or a branch touching migrations — **parks
-   instead.** Do the housekeeping in step 4 with `git -C <worktreePath>`, run
-   `open.command` if configured, print the worktree path, and say to run
-   `/spec-next` from a session there. Relay the engine's refusal reason as it
-   printed it; those guards protect a shared dev instance and are not yours to
-   weaken.
-   **Trust the worktree first.** `spec-env up` wrote the printed `trusted:` root
-   into `.claude/settings.local.json`, but that file will not hot-reload in this
-   session — run `/add-dir <trusted root>` before editing into the worktree, or
-   the first write prompts.
+   `to provision, run:` commands it prints and confirm they succeeded, **except**
+   the `open.command` line, which belongs to the hand-off in 3 below.
+
+2. **Enter the worktree — this session, no new window.** The spec is built in its
+   worktree; that is what the mode is for, and it is why `main` stays free and
+   several specs run at once. So put *this* session there rather than opening
+   another one: call **`EnterWorktree`** with the worktree path.
+
+   **Do it immediately after `git worktree add`, before bootstrap and before the step 4 housekeeping.**
+   Once the session is the worktree, `setup` runs in place and the housekeeping
+   is plain `git` — the `cd` and the `git -C <worktreePath>` prefix both
+   disappear. **Never `cd` into the worktree first:** `EnterWorktree` refuses a
+   path that is already the working directory
+   (`is the current working directory`), so a bootstrap `cd` does not merely
+   make the call redundant, it makes it fail.
+
+   Then run the planner's **`then, in the worktree, run:`** steps in order (file
+   seeding, then `setup`) — a fresh worktree has no dependencies and none of the
+   repo's gitignored files, so hooks, typechecks and tests fail until they are
+   there. Do the step 4 housekeeping, then say to run **`/spec-next`**, here.
+
+   **Do not move the branch into this checkout**, and do not ask the operator to.
+   Entering the worktree is the opposite of moving the branch out of it — the
+   branch never leaves. `/spec-live` is for testing a finished-enough spec on the
+   already-running dev server; it is not the way work gets started, and reaching
+   for it here is what used to split a start across two invocations.
+
+3. **When you cannot enter, hand off as before.** Two cases, and
+   **decide from cwd before calling**, not by calling and catching — an error
+   surfaced mid-skill reads as a bug, and both conditions are knowable in
+   advance:
+
+   - **This session's cwd is already inside a worktree.** `EnterWorktree` only
+     allows a worktree→worktree switch when the target lives under
+     `.claude/worktrees/`, and a project's worktree root usually does not
+     (`../{repo}-wt` is the shipped shape). Do not "fix" this by relocating the
+     root: starting a spec from the base branch is the documented path anyway.
+   - **`EnterWorktree` is unavailable** — a harness without it. There is no CLI
+     counterpart to fall back on, so the skill degrades rather than fails.
+
+   On either, do exactly what this skill did before: bootstrap with
+   `cd "<worktreePath>"`, housekeep with `git -C <worktreePath>`, run
+   `open.command` if one is configured, print the worktree path, and say to run
+   **`/spec-next`** from a session in it.
+   **Trust the worktree first** on this path: `spec-env up` wrote the printed
+   `trusted:` root into `.claude/settings.local.json`, but that file will not
+   hot-reload in this session — run `/add-dir <trusted root>` before editing into
+   the worktree, or the first write prompts. (Entering the worktree makes both
+   moot: the writes are then in-cwd.)
+
+   `EnterWorktree` is gated on being told to work in a worktree by the user or by
+   project instructions. A lifecycle skill directing it **is** project
+   instruction, so the call is in contract here.
+
+**`/spec-next` is unchanged by this.** Its rule 2 — "the worktree you are
+standing in" — is what answers once the session has actually moved; nothing about
+its resolution is loosened, and it must not be. The refusal exists so the wrong
+branch is never built.
 
 ### `checkout` mode
 
 Run `skitterspec spec-env up <name>` and the single `git switch` it prints.
-There is no worktree, no bootstrap, no live step — the checkout is already the
+There is no worktree, no bootstrap and no hand-off — the checkout is already the
 workbench. Its planner enforces the same gate from the engine side, so relay any
 refusal and stop.
 
 ## 4. Move the spec into development
 
-On the branch, in this checkout (or via `git -C <worktreePath>` for a parked
-spec):
+**Do this before you report anything**, so no path can end with a provisioned
+worktree and a spec still reading `Ready` in `specs/backlog/`. Having entered the
+worktree (step 3.2) this is plain `git` — you are standing in it. On the hand-off
+path (step 3.3) run it against the worktree with `git -C <worktreePath>` instead;
+in `checkout` mode the branch is already here.
 
 - `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
   already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
@@ -107,6 +163,17 @@ spec):
 A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
 it is well-formed first.
 
+## 4b. Note a missing gating decision (only if configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <name>` and, if it names this spec, mention it **once**
+before phase 1 starts — the cheapest moment to decide is before any code exists.
+
+**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.
+
 ## 5. Bring the spec's dev servers up — confirm before heavy steps
 
 **Only when the project configures host dev servers** (`env.config.json` → a
@@ -121,10 +188,23 @@ invoke it yourself.
 
 ## 6. Build phase 1
 
-**Carry straight on into `/spec-next`** in this session: it marks phase 1
-started, refreshes the mirror again, builds it with tests and reports. Do not
-stop and ask the operator to run it — the workbench is set up and they asked to
-start the spec.
+**`checkout` mode — carry straight on into `/spec-next`** in this session: it
+marks phase 1 started, refreshes the mirror again, builds it with tests and
+reports. Do not stop and ask the operator to run it: the branch is here and they
+asked to start the spec.
+
+**`worktree` mode — the spec is built in its worktree**, and step 3.2 put this
+session there, so end by saying the worktree path is now the session's and to run
+**`/spec-next`** here. On the hand-off path (step 3.3) the session did not move:
+say so plainly, print the path, and tell them to run `/spec-next` from a session
+in it.
+
+`/spec-next` resolves the spec it is *standing in* — the live spec of the
+checkout, the worktree its cwd is inside, or the branch in `checkout` mode — and
+a name argument narrows a re-run rather than selecting a spec elsewhere. That
+refusal is deliberate: building the wrong spec's phase writes commits on a branch
+nobody asked for. **Do not work around it**, and do not offer to build the phase
+from here.
 
 ## Opt-outs
 

package/assets/skills/spec-to-main/SKILL.md

@@ -8,9 +8,9 @@ disable-model-invocation: true
 
 The **intermediate** landing. `/spec-complete` also lands the branch, but then
 verifies every phase, flips the status to Complete, `git mv`s the spec to
-`complete/`, and tears the environment down. **`/spec-to-main` stops after the
-land**: the worktree stays, the spec stays `In Progress`, and you can land again
-as you add commits.
+`complete/`, and tears the environment down.
+**`/spec-to-main` stops after the land**: the worktree stays, the spec stays
+`In Progress`, and you can land again as you add commits.
 
 Use it when a later phase can only be done *after* the current work is on `main` —
 e.g. it needs to run in CI, a deploy pipeline, or a shared test environment that
@@ -19,9 +19,9 @@ the remaining phases with `/spec-next` and eventually `/spec-complete`.
 
 It reuses the **same engine** as `/spec-complete`'s landing (`spec-env integrate`
 — rebase + fast-forward), so it produces identical linear history. Because a
-fast-forward leaves `base == branch`, the operation is **idempotent and
-repeatable**: new commits put the branch ahead of base again, and you can run
-`/spec-to-main` as many times as you like.
+fast-forward leaves `base == branch`, the operation is
+**idempotent and repeatable**: new commits put the branch ahead of base again,
+and you can run `/spec-to-main` as many times as you like.
 
 ## 0. Preconditions — when this applies
 
@@ -58,10 +58,10 @@ primary checkout is dirty, or if a *different* spec holds it (release that one w
 
 ## 3. Tests must be green before landing
 
-Don't push red to `main`. Run the project's typecheck and test commands **in the
-worktree**; the suite must be **green**. For a **Bug** spec, confirm the
-originally-failing test now passes. If anything is red, stop and report — landing
-broken code onto `main` defeats the purpose.
+Don't push red to `main`. Run the project's typecheck and test commands
+**in the worktree**; the suite must be **green**. For a **Bug** spec, confirm
+the originally-failing test now passes. If anything is red, stop and report —
+landing broken code onto `main` defeats the purpose.
 
 (Note this is the *worktree* suite. The whole point of this skill is often to run
 a *further* check that only exists on `main` / in CI — that one runs **after** the
@@ -69,8 +69,8 @@ land, in step 5.)
 
 ## 4. Land — rebase + fast-forward
 
-Run `skitterspec spec-env integrate <name>` and run the printed commands **in
-order**:
+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.
@@ -91,8 +91,8 @@ and continue — the branch has no commits base doesn't already have.
   `- <YYYY-MM-DD> — Landed intermediate work onto <base> to <run CI / deploy to
   test env / …>; spec stays In Progress.`
 - Do **NOT**: add a State-log row (status doesn't change), flip any phase/status
-  to Complete, `git mv` the spec, or tear down the worktree/stack. **The spec
-  stays `In Progress` and the worktree stays put.**
+  to Complete, `git mv` the spec, or tear down the worktree/stack.
+  **The spec stays `In Progress` and the worktree stays put.**
 - Report: the base branch, the fast-forward result, and the green base test. It
   **never pushes** — mention the user can `git push` the base branch themselves to
   trigger CI / the shared env.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "17.0.0",
+  "version": "18.0.0",
   "description": "Spec-driven development for Claude Code — a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",