@skitterbyte/skitterspec 18.0.0 → 19.0.0

package/MIGRATION.md

@@ -1,5 +1,209 @@
 # 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
@@ -90,8 +294,7 @@ 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
@@ -105,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
 
@@ -156,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
 
@@ -274,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,50 @@
 
 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.

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,9 +25,6 @@
     "enabled": true,
     "host": "127.0.0.1"
   },
-  "open": {
-    "command": ""
-  },
   "registry": ".spec-env/registry.json",
   "branch": {
     "pattern": "{type}/{slug}",
@@ -41,6 +38,12 @@
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
   },
+  "review": {
+    "reader": "detect",
+    "servePort": 7777,
+    "serveOnRemote": true,
+    "commitWith": "/commit"
+  },
   "live": {
     "migrations": []
   }

package/assets/core/env.config.md

@@ -1,11 +1,12 @@
 # `env.config.json` — per-spec isolation config
 
 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-start`, teardown into
-`/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
-`skitterspec spec-env <up|down|prune|dev|connect|integrate>` CLI is the engine
-beneath them.
+stack + host dev servers + a front-door proxy per in-progress spec).
+Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
+`/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
+is `/spec-diff`; the `skitterspec spec-env
+<up|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
+the engine beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-start` gives
 **every** in-progress spec its own git worktree automatically. Docker is a
@@ -31,11 +32,12 @@ no live `env.config.json` was found.
   // Where a spec's branch gets built.
   //
   //   "worktree"  (default) — every spec gets its own git worktree. Several
-  //               specs run side by side and `main` stays free, at the cost of
-  //               one terminal session per spec (`/spec-start` sets it up for you).
+  //               specs run side by side and `main` stays free. `/spec-start`
+  //               moves your session into the spec's worktree with a `cd`, so
+  //               the terminal you are already in follows the work.
   //   "checkout"  — the branch is built in the primary checkout instead. One
-  //               spec at a time, but no second session and no hand-off: the
-  //               terminal you are already in follows the work.
+  //               spec at a time, and nowhere else to stand: the work comes to
+  //               your terminal rather than your terminal going to it.
   //
   // Pick it for how you work, not for what this repo contains — a project with
   // no dev servers may still want several specs in flight. An unrecognised
@@ -124,24 +126,6 @@ no live `env.config.json` was found.
     "host": "127.0.0.1"     // bind host for the canonical ports
   },
 
-  // Optional, editor/terminal-agnostic opener — the FALLBACK for reaching a
-  // worktree. `/spec-start` normally moves the session you typed into into the
-  // worktree, and then there is nothing to open: it runs this only when it
-  // could not switch in place (the session is already inside another worktree,
-  // or the harness cannot move it). Run after provisioning and bootstrap, so
-  // the session opens onto a tree that is ready to work in. The template is
-  // expanded with {worktreePath}, {slug}, {branch}, {projectName},
-  // {portOffset}.
-  // Empty = nothing is opened (the path is just printed), which is how you turn
-  // the auto-open off, and the right value unless you actually want a second
-  // window on the fallback path. A non-interactive run skips it either way — an
-  // opened window nobody is sitting at helps no one.
-  // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
-  // or a "warp://..." deeplink for Warp users.
-  "open": {
-    "command": ""
-  },
-
   // Machine-local slot registry (spec → slot index). Resolved against the
   // primary checkout root, shared by all worktrees, gitignored.
   "registry": ".spec-env/registry.json",
@@ -193,9 +177,10 @@ no live `env.config.json` was found.
     "refuseTeardownIfUnpushed": true
   },
 
-  // What teardown cleans up beyond this machine. `/spec-start` pushes the spec
-  // branch when it provisions, so without this a completed spec leaves a merged
-  // branch on the remote forever. `deleteRemoteBranch`:
+  // What teardown cleans up beyond this machine. Nothing publishes a spec
+  // branch for you, so a remote copy exists only because you pushed it by hand —
+  // and without this a completed spec leaves that merged branch on the remote
+  // forever. `deleteRemoteBranch`:
   //   "prompt"  (default) — plan `git push <remote> --delete <branch>` in its own
   //             "confirm with the user first" section; /spec-complete and
   //             /spec-cancel ask before running it.
@@ -232,6 +217,68 @@ no live `env.config.json` was found.
     "bump": "patch",
     "cherryPickMain": true,
     "targets": []
+  },
+
+  // Reading a spec's diff (`spec-env review`, `/spec-diff`).
+  //
+  // `reader` decides how the page's LOCATION IS WORDED, and — through
+  // `serveOnRemote` below — whether the engine stands its local server up so a
+  // remote reader gets a link that opens. It never decides to PUBLISH. Three
+  // values:
+  //   "local"  — you are at the machine holding the page; a file:// URL opens.
+  //   "remote" — you are not; it does not, so the page is served instead.
+  //   "detect" — work it out (the default).
+  // An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
+  // you are reading, and no signal outranks being told. Detection is only the
+  // default, and it has three outcomes rather than two — local, remote, and
+  // unknown. Unknown behaves exactly as the tool did before any of this existed
+  // (the file:// URL, no warning), because a wrong "local" prints a dead link
+  // and a wrong "remote" warns at someone whose link works fine. An
+  // unrecognised value falls through to "detect", so a typo cannot become a
+  // confident answer. Default: detect.
+  //
+  // `servePort` is the default port for `spec-env review serve`, which renders
+  // every spec's diff per request on one local server. `--port` overrides it per
+  // run. The server binds 127.0.0.1 unless `--host 0.0.0.0` is passed, which
+  // mints an unguessable path token and prints the LAN URL including it —
+  // anyone holding that URL can read every spec's diff while it runs.
+  // Default: 7777.
+  //
+  // `serveOnRemote` is whether a "remote" reader may have that server started
+  // FOR them. On (the default) the engine brings it up, binds 0.0.0.0, and puts
+  // the served URL on the `open:` line — best-guess network address first, the
+  // rest listed under it, because the guess reads interface names and a VPN or
+  // an unusual adapter will fool it. Off, you get the file:// URL with its
+  // "will not open where you are reading" marker and the command to type.
+  // Either way NOTHING IS PUBLISHED on a detection: a server is one process
+  // ended by one flag, while a published page is one this tooling cannot
+  // remove, so that half stays an explicit ask. Teardown names a server that
+  // served the last spec, and `spec-env prune` reaps a pidfile whose process is
+  // gone. Default: true.
+  //
+  // `commitWith` names the skill a COMMITTING verdict hands off to. A review
+  // page ends in a verdict — commit, commit & continue, request changes,
+  // discuss — and the point of the first two is that the commit follows from
+  // the reading rather than costing a separate decision. Skitterspec never
+  // commits through a skill it vendored: `/commit` ships with skittership, a
+  // different package, and a copy living here would fork it. Two shapes:
+  //   "/commit"  — the default; hand off to skittership's commit skill.
+  //   "<name>"   — any other skill your project installs.
+  // With the named skill unavailable, the committing branch commits directly —
+  // stage, typecheck, test, conventional message — and SAYS it took that path,
+  // because a commit made under rules nobody configured must not read as one
+  // made under /commit.
+  //
+  // THERE IS NO OFF SWITCH. `"none"` existed and was removed: it produced a
+  // verdict that records itself and does nothing, which is the one thing a
+  // review page must not offer — a review is the guard in front of an action.
+  // Recording an approval for SOMEONE ELSE to act on is a separate mechanism,
+  // not a value of this key. Default: "/commit".
+  "review": {
+    "reader": "detect",
+    "servePort": 7777,
+    "serveOnRemote": true,
+    "commitWith": "/commit"
   }
 }
 ```