@skitterbyte/skitterspec 16.3.2 → 16.5.0

package/assets/rules/spec-planning.md

@@ -66,17 +66,23 @@ Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engin
 
 **Ticketing-provider sync (opt-in, a separate package).** The base is
 tracker-free: it knows nothing about any specific ticketing system. A
-ticketing provider is installed as its own distribution that plugs into two named
-**seams** in the shared skills (`/spec` Phase E, `/spec-go` step 3b) and fulfils a
-skill-name + CLI contract. Sync is **one-way**: the repo is the source of truth
-and the tracker is a **generated mirror**. It ships `/spec-push` (repo→tracker;
-computes a create/update plan against a committed last-pushed snapshot and applies
-it) and `/spec-status` (read-only drift report — what would push, and whether the
-tracker's workflow-state drifted), backed by a `spec-sync` CLI. There is no
-content pull — the tracker is never read back or merged. When a provider is
-present, `/spec` also links the spec to the tracker. With no provider installed
-the seams are empty and every skill behaves as a plain filesystem workflow. See
-the provider package's own docs for its config and field reference.
+ticketing provider is installed as its own distribution that plugs into named
+**seams** in the shared skills and fulfils a skill-name + CLI contract.
+Sync is **one-way**: the repo is the source of truth and the tracker is a
+**generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
+against a committed last-pushed snapshot and applies it) and `/spec-status`
+(read-only drift report — what would push, and whether the tracker's
+workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
+the tracker is never read back or merged.
+
+**Every skill that moves a spec through the lifecycle carries a seam**, so the
+mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
+`/spec-hotfix` link the spec they create; `/spec-go` refreshes it as work starts;
+`/spec-complete`, `/spec-cancel` and `/spec-review` refresh it after they change
+it. `/spec-to-main` and `/spec-live` carry none — they change no status.
+With no provider installed the seams are empty and every skill behaves as a plain
+filesystem workflow. See the provider package's own docs for its config and field
+reference.
 
 ## Project conventions (fill this in)
 

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

@@ -158,6 +158,8 @@ The **State log** is the folder/status audit trail; later transitions
 (`/spec-complete`, `/spec-cancel`) append a row. The **Changelog** is for the
 fix narrative and decisions — keep them separate.
 
+
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all

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

@@ -51,6 +51,8 @@ Add a **Changelog** entry:
 `git mv "specs/<bucket>/<name>" "specs/cancelled/<name>"` (preserve history;
 move the whole folder).
 
+
+
 Then **commit the cancellation edits** — this skill wrote them, so it commits
 them:
 

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

@@ -53,6 +53,8 @@ Before marking complete, confirm the work is actually finished:
 move the whole folder). The `specs/complete/` folder is the record of finished
 specs — `git log`/the per-spec State log give the completion order.
 
+
+
 Then **commit the completion edits** — steps 3–4 are this skill's own output, so
 it finishes its own work rather than handing you a dirty tree:
 
@@ -128,14 +130,14 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
      recover those commits onto the branch, then re-run.
    - *no worktree* — the spec is live but its worktree is gone. Re-isolate it with
      `skitterspec spec-env up <name>`, then re-run.
-   Relay the diagnostic to the user and **stop** — do not proceed to teardown.
+   Relay the diagnostic to the user and **stop** — do not tear anything down.
 2. **Plan + execute.** Run `skitterspec spec-env integrate <name>` and run the
    printed commands **in order**:
    - `git -C <worktree> rebase <base>` — replay the branch onto base.
    - `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
    On a **rebase conflict** (non-zero exit), run
    `git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
-   to the user; do not offer teardown.
+   to the user; do not tear anything down.
    On a **no-op** ("already landed"), just say so and continue.
 3. **Re-test on base.** Run the project's test command from the primary checkout;
    it must be **green** before you call the landing done.
@@ -144,9 +146,22 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
 
 ## 7. Tear down the environment (opt-in, only if configured)
 
-**Only when `specs/.core/env.config.json` exists**, offer — don't force — to
-reclaim the finished spec's environment. On confirmation, run the `spec-env` CLI
-directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
+**Only when `specs/.core/env.config.json` exists.** Reclaiming the environment is
+what completing a spec *is*, so sub-steps 1–3 run **automatically — do not ask**.
+Run the `spec-env` CLI directly (the old `/spec-env-down` skill is gone —
+teardown is folded in here).
+
+**The precondition is that the work actually landed.** Only tear down when step 6
+completed: it landed (or reported "already landed") **and** the base suite came
+back green. A rebase conflict, a work-loss abort or a red suite means step 6 told
+you to stop — tear nothing down, because the worktree is where the user picks the
+problem up. That precondition is what makes a confirmation redundant: by the time
+you get here the branch is an ancestor of base and the engine's guards have
+nothing left to protect.
+
+**Opt-out:** if the user passed **`--keep-env`**, skip sub-steps 1–3, say the
+worktree and branch are being kept, and go straight to sub-step 4. Mention
+`skitterspec spec-env up <name>` re-attaches it later either way.
 
 1. **Disconnect the proxy if this spec is connected.** If `.spec-env/connected`
    names this spec, run `skitterspec spec-env connect main` first so the
@@ -154,20 +169,28 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
 3. **Remove worktree + stack + slot:** run `skitterspec spec-env down <name>`
-   and execute the commands it prints, in order. After a **feature/bug** landing
-   the branch is merged into base, so teardown needs **no `--force`** and deletes
-   the branch (`git branch -d`). After a **hotfix** landing the branch isn't
-   merged (it was tagged + cherry-picked), but its head is captured by the deploy
-   tag, so teardown still needs no `--force` and drops the branch with
-   `git branch -D` (the tag holds the commits). It still respects the guards (won't
-   destroy a dirty, or unpushed-and-unlanded, worktree without `--force`).
+   and execute the commands it prints, in order. After a landing — merged into
+   base for a **feature/bug**, captured by the deploy tag for a **hotfix** —
+   teardown needs **no `--force`** and drops the branch with `git branch -D`,
+   which is safe precisely because the commits are already somewhere else. It
+   still respects the guards (won't destroy a dirty, or unpushed-and-unlanded,
+   worktree without `--force`), so if it *does* refuse, relay that and stop
+   rather than reaching for `--force`.
 4. **Reap orphaned test-DB volumes:** run `skitterspec spec-env prune`. It lists
    Docker volumes in the repo namespace that belong to **no live spec** (no
    worktree) — leftovers from declined/aborted teardowns, manual
    `git worktree remove`, or `--keep-volumes`. Show the user the orphan list and,
    **only on their confirmation**, execute the printed `docker volume rm`
-   commands. Non-fatal: if prune can't run (Docker down) or the user declines,
-   report it and finish completing anyway — never block the spec on it. Skip when
-   Docker isn't in use (the command self-reports "no orphaned volumes").
+   commands. **This one still asks**, unlike 1–3: it reaps volumes belonging to
+   *other* specs, and this spec having landed cleanly says nothing about those.
+   Non-fatal: if prune can't run (Docker down) or the user declines, report it and
+   finish completing anyway — never block the spec on it. Skip when Docker isn't
+   in use (the command self-reports "no orphaned volumes").
+
+**Say what you reclaimed.** With no confirmation step the user never saw this
+coming, so the final report must name the worktree path removed and the branch
+deleted (or, under `--keep-env`, that both were kept). A teardown nobody
+authorised and nobody was told about is the one way this step can lose someone's
+place.
 
 If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. Can start from a tracker issue when a provider is installed (`/spec-hotfix <tag> <ISSUE-REF>`), adopting it as the hotfix's issue. 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
@@ -20,11 +20,24 @@ Spec type convention (see `.claude/rules/spec-planning.md`):
 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.
+- **Read the arguments.** `/spec-hotfix <tag> <name>` (e.g.
+  `/spec-hotfix v33.16.4 login-crash`). An argument shaped like an issue
+  reference — letters, a hyphen, digits (`SKI-123`) —
+  is **always a reference, never a name**, so `/spec-hotfix v33.16.4 SKI-123` and
+  `/spec-hotfix SKI-123`
+  both mean "adopt that issue". Release tags don't take that shape, so the two
+  can't be confused. With no name and no reference, ask what to call it.
+- Take the release tag from the argument. If it's missing,
+  **ask which version prod is running** — don't guess. When an issue was adopted
+  above, **offer any versions it mentions** as suggestions — clearly labelled as
+  the reporter's words, not a default — and still wait for the answer. A reporter
+  usually names
+  the version they *saw* the bug on, which is not necessarily what is deployed,
+  and a hotfix forked from the wrong tag fails late.
 - **Verify the tag exists** before anything else:
   `git rev-parse --verify <tag>^{commit}`. If it doesn't resolve, stop and ask.
 
@@ -156,6 +169,8 @@ place of the table when the spec touches no external surface.>
 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;

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

@@ -82,6 +82,8 @@ reading the code, do that instead of asking.
   re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
   **State log** row).
 
+
+
 ## 5. Report
 
 Summarise the drift found, what you changed, any questions still open, and

package/bin/skitterspec.js

@@ -1,6 +1,25 @@
 #!/usr/bin/env node
 'use strict'
 
+// This package's bin/, src/ and assets/ are COMPOSED by scripts/build-dist.js and
+// gitignored, not committed — so a checkout linked before a build (or after a
+// `git clean`) has a working binary with nothing behind it. Say that, instead of
+// letting `require` raise MODULE_NOT_FOUND on an internal path the caller has no
+// way to interpret.
+//
+// Inline rather than shared: a helper would have to live in src/, which is
+// exactly what may be missing. In the workspace packages src/ always exists, so
+// this is inert there.
+const { existsSync } = require('node:fs')
+const { join } = require('node:path')
+if (!existsSync(join(__dirname, '..', 'src'))) {
+  console.error(
+    'skitterspec: no build output — this package\'s bin/src/assets are composed, not committed.\n' +
+      '  run "npm run build" in the skitterspec repo, then try again.',
+  )
+  process.exit(1)
+}
+
 const { run } = require('../src/cli.js')
 
 run(process.argv.slice(2)).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "16.3.2",
+  "version": "16.5.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",

package/src/cli.js

@@ -48,6 +48,29 @@ const { renderRoutes, portsInUse, waitListening } = require('./env/proxy.js')
 
 const pkg = require('../package.json')
 
+// Commands this (tracker-free) base does NOT ship, and the distribution that
+// does. Without this the base says only "unknown command: spec-sync", which a
+// user correctly reads as "no such feature" — nothing anywhere named the
+// distribution that has it, so they were stranded. Naming Linear here is a
+// diagnostic string, not provider machinery: `init.js` already knows
+// `linear.config.json` and `linear-base/` by name in order to protect them.
+const PROVIDER_COMMANDS = {
+  'spec-sync': '@skitterbyte/skitterspec-linear',
+  'spec-sanitise': '@skitterbyte/skitterspec-linear',
+}
+
+function unknownCommand(cmd) {
+  const dist = PROVIDER_COMMANDS[cmd]
+  if (dist) {
+    return (
+      `unknown command: ${cmd} — this is the base distribution, which does not ` +
+      `ship it.\n  ${cmd} comes from ${dist} (a superset of this package): ` +
+      `install that instead.`
+    )
+  }
+  return `unknown command: ${cmd} (try --help)`
+}
+
 const HELP = `skitterspec — spec-driven-development for Claude Code
 
 Usage:
@@ -190,7 +213,7 @@ function specEnvUp(dir, config, specArg) {
     process.stdout.write('Usage: skitterspec spec-env up <spec>\n')
     return
   }
-  const spec = resolveSpec(specArg, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Live-safe: if this spec is already live on the primary checkout (its branch was
   // branch-switched in by `live take`), a `git worktree add` would fail — the branch
@@ -357,7 +380,7 @@ function specEnvDown(dir, config, specArg, flags) {
     process.stdout.write('Usage: skitterspec spec-env down <spec> [--keep-volumes] [--force]\n')
     return
   }
-  const spec = resolveSpec(specArg, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // A worktree-only spec never held a slot but its worktree still needs removing,
   // so "nothing to do" means neither a slot nor a worktree exists.
@@ -459,6 +482,31 @@ function liveWorktreePaths(dir) {
   return paths
 }
 
+// Resolve a spec argument the ONE way every spec-env subcommand resolves it:
+// against the primary checkout first, then the spec's own worktree, then every
+// other checkout git knows about. An in-progress spec is git-mv'd into
+// specs/in-progress/ **on its own branch**, so it exists only in its worktree —
+// a primary-checkout-only lookup fails for exactly the specs these commands
+// serve. The first fallback is the worktree path the config derives for this
+// spec (cheap, no git); the rest come from `git worktree list`, so a worktree
+// provisioned under an older `worktree.root` still resolves. Identity and
+// coordinate tokens always expand against `dir` (the primary checkout), so the
+// answer is identical whether the command was run from main or a worktree.
+function resolveSpecWithWorktree(dir, config, specArg) {
+  const { slug } = splitPrefix(path.basename(specArg))
+  const { repo, repoSlug } = repoInfo(dir)
+  const wtTokens = { repo, repoSlug, slug }
+  const worktreeGuess = path.resolve(
+    dir,
+    expandTokens(config.worktree.root, wtTokens),
+    expandTokens(config.worktree.folderPattern, wtTokens),
+  )
+  const searchDirs = [...new Set([worktreeGuess, ...liveWorktreePaths(dir)])].filter(
+    (p) => p !== dir,
+  )
+  return resolveSpec(specArg, dir, config, { searchDirs })
+}
+
 // Every spec folder name found under specs/* across the given checkout roots.
 // An in-progress spec lives on its *worktree branch*, not the primary checkout,
 // so we must scan the worktrees too — otherwise a live spec's DB looks orphaned.
@@ -771,7 +819,7 @@ function specEnvResolve(dir, config, specArg) {
     process.stdout.write('Usage: skitterspec spec-env resolve <spec>\n')
     return
   }
-  const r = resolveSpec(specArg, dir, config)
+  const r = resolveSpecWithWorktree(dir, config, specArg)
   process.stdout.write(
     `spec:       ${r.folder} (${r.bucket})\n` +
       `type/slug:  ${r.type} / ${r.slug}\n` +
@@ -792,7 +840,7 @@ async function specEnvDev(dir, config, positional) {
     process.stdout.write('Usage: skitterspec spec-env dev <up|down> <spec>\n')
     return
   }
-  const spec = resolveSpec(specArg, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
   if (!config.dev.length) {
     process.stdout.write(
       'spec-env dev: no dev processes configured — set "dev": [...] in env.config.json.\n',
@@ -888,7 +936,7 @@ async function specEnvConnect(dir, config, specArg) {
     return
   }
 
-  const spec = resolveSpec(target, dir, config)
+  const spec = resolveSpecWithWorktree(dir, config, target)
   const registry = readRegistry(dir, config)
   if (!Object.prototype.hasOwnProperty.call(registry.slots, spec.folder)) {
     process.stdout.write(
@@ -984,20 +1032,6 @@ async function specEnvLive(dir, config, positional) {
   }
 }
 
-// Resolve a spec, offering its worktree as a fallback search dir — a spec authored
-// on its own branch may not exist in the primary checkout's specs/**.
-function resolveSpecWithWorktree(dir, config, specArg) {
-  const { slug } = splitPrefix(path.basename(specArg))
-  const { repo, repoSlug } = repoInfo(dir)
-  const wtTokens = { repo, repoSlug, slug }
-  const worktreeGuess = path.resolve(
-    dir,
-    expandTokens(config.worktree.root, wtTokens),
-    expandTokens(config.worktree.folderPattern, wtTokens),
-  )
-  return resolveSpec(specArg, dir, config, { searchDirs: [worktreeGuess] })
-}
-
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
@@ -1373,8 +1407,8 @@ async function run(argv) {
       await cleanupReleaseTooling(dir, opts)
       break
     default:
-      throw new Error(`unknown command: ${cmd} (try --help)`)
+      throw new Error(unknownCommand(cmd))
   }
 }
 
-module.exports = { run, parse }
+module.exports = { run, parse, HELP, unknownCommand }

package/src/env/resolve.js

@@ -217,9 +217,14 @@ function assertPrimaryOnMain(config, git) {
  * (the primary checkout), so a worktree-only spec resolves to the right base.
  */
 function resolveSpec(specArg, dir, config, opts = {}) {
-  const found = findSpecFolder(specArg, dir, opts.searchDirs || [])
+  const searchDirs = opts.searchDirs || []
+  const found = findSpecFolder(specArg, dir, searchDirs)
   if (!found) {
-    throw new Error(`spec not found under specs/**: ${specArg}`)
+    // Name the roots we looked under: the usual cause is a spec that only exists
+    // on its own branch, and the message should say where we didn't find it.
+    throw new Error(
+      `spec not found under specs/**: ${specArg} (searched: ${[dir, ...searchDirs].join(', ')})`,
+    )
   }
 
   const { type, slug } = splitPrefix(found.folder)

package/src/env/teardown.js

@@ -33,7 +33,10 @@ function planDown(spec, config, flags, ctx) {
   // A hotfix lands by tag + cherry-pick, so its branch is never an ancestor of
   // base — but once its head is captured by a tag (the deploy tag from
   // `hotfix land`), the commits are recoverable and the branch is safe to drop.
-  // Treat "reachable from a tag" as landed, alongside merged.
+  // Treat "reachable from a tag" as landed, alongside merged. Read twice below:
+  // it decides whether the unpushed guard blocks, and whether the branch delete
+  // can use `-D` — the same question ("are these commits recoverable?"), so the
+  // two must never answer it differently.
   const landed = Boolean(worktreeState.merged || worktreeState.reachableFromTag)
 
   // --- guards (overridable with --force) ---
@@ -88,15 +91,26 @@ function planDown(spec, config, flags, ctx) {
   )
 
   // --- delete the branch ---
-  // Runs after the worktree remove frees the branch. Normally `-d` (safe: refuses
-  // an unmerged branch, never -D). A tag-landed hotfix branch is intentionally NOT
-  // an ancestor of base, so `-d` would refuse it — but its commits are captured by
-  // the deploy tag, so `-D` is safe *only* in that case. Everything else stays `-d`;
-  // on a forced teardown of a genuinely unmerged branch it fails loudly and the
-  // skill relays it rather than -D-ing.
+  // Runs after the worktree remove frees the branch. `-D` exactly when we have
+  // PROVEN the commits survive the delete, `-d` otherwise.
+  //
+  // `-d` looks like the safe default and mostly is, but its refusal answers a
+  // different question from ours: it also declines a branch that is ahead of its
+  // upstream ref, reporting `not yet merged to refs/remotes/origin/<branch>,
+  // even though it is merged to HEAD`. That fires on the ordinary spec flow —
+  // `/spec-go` pushes the branch when it provisions, and the phase commits after
+  // it are landed locally rather than pushed — so teardown meets a branch whose
+  // every commit is on `main` and `-d` refuses it. `merged` (HEAD is an ancestor
+  // of base) already establishes what we actually care about, and establishes it
+  // more strongly than `-d` checks.
+  //
+  // `reachableFromTag` is the same argument for a hotfix: never an ancestor of
+  // base, but its head is captured by the deploy tag.
+  //
+  // Everything else keeps `-d`, so a forced teardown of a genuinely unlanded
+  // branch fails loudly and the skill relays it rather than -D-ing.
   if (spec.branch) {
-    const tagLanded = Boolean(worktreeState.reachableFromTag && !worktreeState.merged)
-    commands.push(`git branch ${tagLanded ? '-D' : '-d'} ${spec.branch}`)
+    commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
   }
 
   return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }

package/src/init.js

@@ -558,12 +558,22 @@ function printReport(dir, mode, { diff = false } = {}) {
       ' at /spec-go (Docker is a per-spec escalation — set > **Stack:** in the spec).\n'
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
+  // A provider superset ships its own `spec-<provider>-setup` skill; the base
+  // ships none. Discovering it from what was actually installed keeps this file
+  // tracker-free — it never has to know which tracker (if any) is in the box.
+  const setupSkill = SKILLS.find((s) => /^spec-.+-setup$/.test(s))
+  const trackerNote = setupSkill
+    ? `Tracker sync is opt-in: run /${setupSkill} to configure it` +
+      ' (it discovers your workspace and writes the config), or see' +
+      ' specs/.core/SETUP.md.\n'
+    : ''
   process.stdout.write(
     '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
       ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
-      isolationNote,
+      isolationNote +
+      trackerNote,
   )
 }