@skitterbyte/skitterspec 17.0.0 → 19.0.0

package/MIGRATION.md

@@ -1,5 +1,253 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v18 → v19 (starting a spec offers phase 1)
+
+### Breaking change
+
+**skitterspec now requires Node 22.13 or newer.** `engines.node` was `>=18`, and
+that floor was a claim nobody was testing: the test suite cannot run without an
+install, and pnpm 11.11 — the package manager this repo pins — itself requires
+22.13. A floor CI cannot exercise is a promise rather than a guarantee, so it was
+raised to the version the toolchain actually needs.
+
+On Node 18 or 20, `npm install` now warns — or fails, under `engine-strict`.
+Upgrade Node, or stay on v18 of skitterspec. Nothing in your config changes
+either way.
+
+### Releases now carry provenance
+
+Every release from v19 onwards is built and signed by GitHub Actions through npm
+Trusted Publishing, so no publish token exists anywhere to be leaked. Each
+published version carries a signed attestation you can verify back to the commit
+it was built from:
+
+```
+npm view @skitterbyte/skitterspec@19.0.0 dist.attestations
+```
+
+Nothing to do — it is a property of the package you receive.
+
+### Breaking change
+
+**`/spec-start` no longer pushes the spec's branch.** It provisions the worktree
+and commits the spec's move to `in-progress/` exactly as before, and then stops.
+Publishing is yours to do, whenever you want the work somewhere other than your
+machine:
+
+```
+git -C <worktreePath> push -u origin <branch>
+```
+
+Two things change for you, and neither is in your config:
+
+- **Spec branches stop appearing on the remote.** Nothing is lost — the branch
+  and its commits are in the worktree — but a branch you have not pushed is on
+  one machine only, and that is now the default rather than something the
+  tooling quietly undid.
+- **Cancelling a spec with unpublished work now refuses.** `/spec-cancel` has
+  always respected `guards.refuseTeardownIfUnpushed`, but the guard could never
+  fire while provisioning published every branch. It fires now, at the one moment
+  it was written for: the work really is about to be destroyed, and the worktree
+  is the only copy. `/spec-cancel` names both ways out — publish the branch and
+  re-run, or `spec-env down <name> --force` accepting the loss. Nothing was
+  removed from your config and nothing needs adding to it.
+
+The justification for the old behaviour does not survive reading, which is why
+it went rather than becoming a setting: it claimed to fire the tracker's branch
+automation, and that needs `{identifier}` in `branch.pattern`, which the shipped
+default does not carry. `/spec-bug` never pushed and `/spec-hotfix` forbids it,
+so this also makes the three consistent.
+
+**The `open.command` config key is gone.** It was the editor/terminal-agnostic
+opener — `code {worktreePath}`, a `tmux` command, a `warp://` deeplink — that
+`/spec-start` ran when it could not move your session into the worktree.
+
+**Leaving it in `env.config.json` is harmless and silent** — which is the part
+to watch. The config merge copies known keys only, so a leftover `open` block is
+ignored rather than rejected: nothing errors, and your editor simply stops
+opening. If you set it deliberately, that absence is the only signal you get.
+
+**`/spec-start` no longer moves your session into the worktree either.** It
+provisions the worktree, does the housekeeping there, prints the path, and stops.
+This **supersedes the "opens a session in it" half of v17 → v18 below** — the
+branch still never leaves its worktree, but nothing tries to relocate your shell
+to reach it.
+
+| v18 | v19 |
+|-----|-----|
+| Three paths through `/spec-start`: enter the session, or fall back two ways | **One path.** Provision, bootstrap, print the path. |
+| Reaching the work meant getting a shell or a window into the worktree | **`/spec-diff`** renders the worktree's diff as a page you read anywhere |
+| `open.command` opened an editor on the fallback path | Removed. Nothing opens anything. |
+
+### What replaced it
+
+**`/spec-diff`** — a new skill, and the reason the opener had nothing left to do.
+A phase is built in its own worktree, so `git diff` in your terminal answers
+about the base branch. `/spec-diff` collects that worktree's changes with
+`git -C` and writes a self-contained HTML page: whole-file context that folds
+away, a file tree, untracked files included. Open it locally, or publish it and
+read it on a phone.
+
+The page lands in `.spec-env/reviews/<spec>.html` (gitignored), and
+**the diff never passes through the model** — so it costs no context tokens
+however large it is. The optional *written* review is the part that costs, and it
+is offered rather than assumed. `/spec-next` writes the page at the end of every
+phase. Beneath it, `skitterspec spec-env review <spec> [--branch]` is the engine.
+
+### `/spec-start` lands you in the worktree, and offers phase 1
+
+Two changes to the same moment. In `worktree` mode `/spec-start` used to
+provision the branch, print the path and leave your session where it was; opening
+a session in the worktree was then yours to do. It now
+**moves your session into the worktree** as part of bootstrapping it, and asks
+whether to build phase 1:
+
+```
+worktree ready — this session is now in it:
+  ../myrepo-wt/sort-inbox
+
+build phase 1 now?
+  yes -> carries on into /spec-next
+  no  -> you are already there; type /spec-next whenever you like
+```
+
+**Your shell will not be where it was.** A session that was on `main` in the
+primary checkout is standing in the spec's worktree afterwards, on the spec's
+branch — so the next command you type runs there. That is the point of it, and it
+is still a real change to plan for. The move is a plain `cd`: nothing prompts you
+for approval, nothing opens a new terminal or window, and your primary checkout
+is untouched and still on the base branch.
+
+**`/spec-next` needs no argument now.** Say **yes** and `/spec-start` carries on
+into a bare `/spec-next`; say **no** and typing `/spec-next` an hour later does
+the same thing, because you are already standing in the right place. Neither is
+assumed, because provisioning is cheap and reversible while a phase build is
+neither.
+
+**This is not a loosened refusal.** A bare `/spec-next` still refuses to build a
+spec it is not standing in, exactly as before — what changed is where you are
+standing, not how weakly the rule reads. `--worktree <path>` survives beside it as
+the explicit way to build a spec you are *not* in, and a path you pass is still
+not a path anything guessed.
+
+**Leaving is a `cd` too.** `/spec-complete` and `/spec-cancel` delete the
+worktree, which is now the directory you are standing in, so both tell you to `cd`
+to the primary checkout first. `git worktree remove` **succeeds** on the tree you
+occupy rather than refusing — the teardown looks fine and every command after it
+dies with `Unable to read current working directory`.
+
+**The `--worktree` build checks itself.** On that path, `/spec-next` first records
+what your primary checkout looked like, and afterwards reports anything that
+appeared in it — the signature of a relative path that missed the worktree. It
+reports rather than accuses: it cannot know who wrote a file, so it names both
+readings and deletes nothing.
+`skitterspec spec-env resolve <spec> --record-primary` and
+`--assert-primary-clean` are the engine underneath, usable on their own.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Delete the `open` block from `specs/.core/env.config.json`**, if you have
+   one. Optional — it is ignored either way — but leaving it implies a setting
+   that no longer does anything.
+3. **Answer the question `/spec-start` now asks.** In `worktree` mode it offers
+   phase 1 before it finishes. Take the offer and it is built there and then;
+   decline and you are left standing in the provisioned worktree, free to type
+   `/spec-next` whenever you like. Both endings are fully supported — decline when
+   the phase is a big one and you would rather spend a fresh context on it.
+4. **Expect your shell to move, whichever you answer.** Anything you had queued
+   for the primary checkout — a `git` command, a script, a relative path — now
+   runs in the worktree instead. `cd` back when you want the base branch, and note
+   that `/spec-complete` and `/spec-cancel` require exactly that before they tear
+   the worktree down.
+5. **Use `/spec-diff` to read the work** rather than reaching for a terminal in
+   the worktree. It is gated on nothing — half a phase, a hand edit, or a
+   colleague's branch are all ordinary inputs.
+
+`checkout` mode is unchanged.
+
+## `@skitterbyte/skitterspec-linear` v12 → v13 (starting a spec offers phase 1)
+
+The same change as `@skitterbyte/skitterspec` v18 → v19 above — this
+distribution composes the same lifecycle skills. Read that entry first.
+
+### Breaking change
+
+**`spec-sync push` is now `spec-sync plan`.** The verb computes a create/update
+plan and performs no network I/O; `spec-sync apply` is what writes to Linear.
+Calling it `push` put three unrelated things behind one word — this verb, the
+`/spec-push` skill, and `git push` — and it was the one that pushes nothing.
+
+```
+skitterspec spec-sync plan <spec> --workspace-states <file> --json > plan.json
+skitterspec spec-sync apply <spec> --plan plan.json
+```
+
+The old name is **not** aliased. It is recognised and exits 1 naming its
+replacement, so a script that calls it fails loudly with the fix in the message
+rather than drifting on a name that will be removed later.
+
+**Your `linear.config.json` needs no change.** The `"push"` values under
+`sync.fieldOwnership` — `assignee: "push"`, `description: "push"`,
+`workflowState: "push"` — are a different vocabulary: they name a direction of
+ownership, not a subcommand. They are untouched and still mean what they meant.
+Do not search-and-replace `push` in your config.
+
+### What else is here
+
+**One thing here is Linear-specific.** `/spec-start` now pushes to Linear itself,
+right after it commits the spec's move to `in-progress/`. It used to push nothing
+and leave the mirror to the refresh `/spec-next` runs — immediate in `checkout`
+mode, but in `worktree` mode hours away or never. Until it came, the issue sat in
+its old workflow state with nobody assigned while the repo read `in-progress`
+with a developer on it. Expect one more Linear call per `/spec-start`, and expect
+the issue to be current the moment the spec is in flight. Nothing else changes:
+sync is still one-way, and an unlinked spec is still skipped rather than minted.
+
+## `@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,10 +284,17 @@ 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
-been checked against your Linear workspace.** The check itself is not new — it
+**`spec-sync push` now refuses to run until the configured `states` names have been checked against your Linear workspace.** The check itself is not new — it
 already existed on `spec-sync status --workspace-states` — but it was advisory,
 and skipping it sent a state name Linear **silently ignores**: the description
 lands, the issue never moves, and nothing errors. The base
@@ -53,8 +308,7 @@ lands, the issue never moves, and nothing errors. The base
 | A configured state absent from the workspace | pushed, silently no-op | **exits 1**, naming the workspace's real states |
 
 `/spec-push` handles this for you — it fetches the workspace's issue
-workflow-state names over MCP and passes them on. **Nothing changes if you drive
-sync through the skill.** Only a direct CLI caller needs updating.
+workflow-state names over MCP and passes them on. **Nothing changes if you drive sync through the skill.** Only a direct CLI caller needs updating.
 
 ### What to do
 
@@ -104,8 +358,7 @@ sync through the skill.** Only a direct CLI caller needs updating.
 **v9 remaps the Linear mirror.** A spec is now a Linear **issue** (not a Project),
 each phase a **sub-issue** (not a Milestone), and **tasks are no longer synced**
 (they stay in the repo phase files). This collapses a large spec from ~1 project +
-N milestones + dozens of task-issues down to **one issue + one sub-issue per
-phase**. The base `@skitterbyte/skitterspec` is unaffected (still v15).
+N milestones + dozens of task-issues down to **one issue + one sub-issue per phase**. The base `@skitterbyte/skitterspec` is unaffected (still v15).
 
 ### Breaking changes
 
@@ -222,10 +475,7 @@ both as optional — `/spec-review` adds them if you want them.
 
 ## `@skitterbyte/skitterspec` v2 → v3 (slimmer surface + local traffic diversion)
 
-**v3 shrinks the everyday command surface to five verbs — `spec → go → connect →
-commit → complete` — by folding provisioning, teardown, and grooming into the
-lifecycle skills, and adds `/spec-connect` for testing a worktree at your normal
-`localhost` URL.** (`@skitterbyte/skitterspec-linear` moves to v2.0.0 in lockstep.)
+**v3 shrinks the everyday command surface to five verbs — `spec → go → connect → commit → complete` — by folding provisioning, teardown, and grooming into the lifecycle skills, and adds `/spec-connect` for testing a worktree at your normal `localhost` URL.** (`@skitterbyte/skitterspec-linear` moves to v2.0.0 in lockstep.)
 
 ### Removed skills (breaking) → where they went
 

package/README.md

@@ -6,13 +6,14 @@ Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
 ```
 /spec  →  /spec-start  →  /spec-next  →  /commit  →  /spec-complete
  plan      build it     test it live      save it     finish + land
+                          ↳ /spec-diff — read what the phase changed
 ```
 
 Ships the spec-lifecycle skills (`/spec`, `/spec-start`, `/spec-next`, `/spec-complete`,
-`/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.
+`/spec-cancel`, `/spec-bug`, `/spec-hotfix`, `/spec-review`, `/spec-diff`,
+`/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
@@ -63,6 +64,54 @@ 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.
 
+## Reading the diff — `/spec-diff`
+
+A phase is built in its own worktree, so `git diff` in your terminal answers
+about the base branch — and a 350-line diff read as terminal text is scrolling,
+not review. **`/spec-diff`** collects the worktree's changes with `git -C` and
+writes a self-contained HTML page: whole-file context that folds away, a file
+tree, new files included. Open it locally, or publish it and read it on a phone.
+
+The page lands in `.spec-env/reviews/<spec>.html`, which is gitignored — so
+reviewing a branch leaves no change in the branch you are reviewing. **The diff never passes through the model**, so it costs no context tokens however large it
+is; the optional *written* review (a short read plus `flag`/`confirm`/`good`
+notes) is the part that costs, and it is offered rather than assumed. Publishing
+is always opt-in, and one page per spec — later phases update the same link.
+
+`/spec-next` writes the page at the end of every phase. Nothing about it depends
+on where your shell is.
+
+## One ending, every skill — `.claude/rules/spec-reports.md`
+
+Every skill finishes with the same block, and says nothing while it runs beyond
+a question it cannot answer itself or a failure at the moment it happens:
+
+✅ **Phase 2 built** — `feat-orders`, 2 of 4
+
+| | |
+|---|---|
+| **Branch** | `spec/feat-orders` · 3 commits, clean |
+| **Built** | POST /orders handler, orders schema |
+| **Tests** | 128 passed · npm test |
+| **Review** | 7 files, +212 −18 · [open the page](file:///…) — want a written review before you commit? |
+| **Follow-ups** | none |
+| **Next** | `/spec-next` → phase 3 (Auth) |
+
+Four verdicts, and the last two are different facts about your repo: `✅` done ·
+`⚠️` done with caveats · `❌` failed part-way, so there is a mess to clear ·
+`⏸` refused before acting, so nothing changed.
+**A refusal emits the block too**, so "nothing happened" is a reported outcome
+rather than an absent one.
+
+Fields come from a fixed vocabulary in a fixed order, and a skill emits only the
+ones it declares — `Next` is last because it is the only row you act on. (A `Tracker` row leads the
+table once a ticketing provider is installed; the base has none, so it never
+appears.)
+`Follow-ups` is always there: a recorded `none` is a decision where a missing
+line is an oversight. The block covers **that run only** — what else is in
+flight is a different question, and answering it here leaves you unable to tell
+what followed from the run you just watched.
+
 ## Production hotfixes — `/spec-hotfix`
 
 When prod is on a tagged release, a fix must be built on **that** version, not

package/assets/claude-md-section.md

@@ -2,14 +2,60 @@
 
 Spec-driven development runs through the lifecycle **skills** — use them so
 structure and lifecycle stay consistent. The everyday loop is
-**`spec → start → next → commit → complete`**, with `/spec-connect` when you want to test
-the spec in a browser.
+**`spec → start → next → commit → complete`**, with **`/spec-diff`** to read what
+a phase changed and `/spec-connect` when you want to test the spec in a browser.
 
 **Skills vs commands.** The lifecycle skills are read by Claude, which exercises
 judgment. `/spec-connect` and `/spec-live` are **slash commands** instead — each
 pre-executes one `spec-env` verb and relays it, so only you can run them; a
 skill that wants one will tell you to type it.
 
+**Seeing the work.** A phase is built in its own worktree, so `git diff` in your
+terminal answers about the base branch. **`/spec-diff`** renders that worktree's
+diff as a self-contained HTML page you open locally — or publish, and read on a
+phone. The diff never passes through the model, so the page costs no context
+tokens however large it is; the optional written review is the part that costs,
+and it is offered rather than assumed. `/spec-next` writes the page at the end of
+every phase.
+
+**Handing the review back.** The page takes marks: tick `✓ accept` per file as
+you read, note anything against a line or a whole file, answer the questions a
+written review asked — then **end it in a decision**. Three buttons, each
+carrying its own verdict:
+`✓ Commit` commits it, `✓ Commit & Continue` commits and builds the next phase,
+`↺ Request changes` sends it straight back to be worked, `… Discuss first` asks
+you what's up. A **served** page hands the pass to
+the engine, which **holds** it and shows a six-digit code. Type `/spec-reviewed`
+and the waiting pass is picked up and acted on; paste the code after it
+(`/spec-reviewed 324199`) to name one exactly, which matters only when two are
+waiting. **Nothing pushes** — a device that reaches your page cannot reach this
+conversation, which is what keeps a stray approval out of your review, and is
+why the code is an address rather than a password. A `file://` page has no server to talk to, so it
+copies and you paste, as before. Approve is unavailable while a note is open —
+you asked for something, so it cannot also be fine — and it hands off to your
+own commit skill (`review.commitWith`, `/commit` by default) rather than a copy
+living here. Fixes come back as resolutions, so the next render shows each note
+struck through with what changed. An accept remembers the file's content, so it
+lapses by itself when that file changes again. The marks are information —
+nothing gates on them; the verdict is the one thing you choose, once.
+
+**One ending.** Every spec skill finishes with the same block — a verdict
+(`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
+ending on the one thing to do next. A refusal emits it too, so "nothing
+happened" is reported rather than absent, and `Follow-ups` is always there
+because a recorded `none` is a decision. Skills stay quiet while they run. The
+shape lives in **`.claude/rules/spec-reports.md`**.
+
 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/commands/spec-connect.md

@@ -1,6 +1,6 @@
 ---
-description: Expose one spec's dev servers on the canonical localhost ports (or `main` to hand them back)
-argument-hint: "[spec|main]"
+description: Expose one spec's dev servers on the canonical localhost ports — bare uses the spec you are on, `main` hands them back
+argument-hint: "[<spec> | main]"
 allowed-tools: Bash({{exec}} skitterspec spec-env connect:*)
 disable-model-invocation: true
 ---

package/assets/commands/spec-live.md

@@ -1,6 +1,6 @@
 ---
-description: Put one spec live on the already-running dev server — `<spec>` takes it, a bare `take` takes the spec you are on, `main` hands the instance back
-argument-hint: "[<spec> | main | take | release | abort | status]"
+description: Put one spec live on the already-running dev server — bare takes the spec you are on, `<spec>` takes that one, `main` hands the instance back
+argument-hint: "[<spec> | main | status | release | abort]"
 allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
 disable-model-invocation: true
 ---

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

@@ -25,19 +25,25 @@
     "enabled": true,
     "host": "127.0.0.1"
   },
-  "open": {
-    "command": ""
-  },
   "registry": ".spec-env/registry.json",
   "branch": {
     "pattern": "{type}/{slug}",
     "identifierField": ""
   },
+  "spec": {
+    "companionPaths": []
+  },
   "baseBranch": "",
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
   },
+  "review": {
+    "reader": "detect",
+    "servePort": 7777,
+    "serveOnRemote": true,
+    "commitWith": "/commit"
+  },
   "live": {
     "migrations": []
   }