@skitterbyte/skitterspec-linear 12.0.0 → 13.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

@@ -1,7 +1,6 @@
 # @skitterbyte/skitterspec-linear
 
-Spec-driven development for [Claude Code](https://claude.com/claude-code), **with
-one-way Linear sync**. A strict **superset** of
+Spec-driven development for [Claude Code](https://claude.com/claude-code), **with one-way Linear sync**. A strict **superset** of
 [`@skitterbyte/skitterspec`](https://www.npmjs.com/package/@skitterbyte/skitterspec):
 everything in the base filesystem workflow, plus one-way sync from a spec up to
 its linked Linear issue — the repo is canonical, Linear is a generated mirror.
@@ -114,6 +113,37 @@ also start **from** an existing issue — `/spec SKI-123`,
 `/spec-hotfix v33.16.4 SKI-123`, or `--from-issue` to browse the ones your web
 app filed. There is no pull — the repo is already canonical.
 
+## 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
+
+| | |
+|---|---|
+| **Tracker** | [SKS-88](https://linear.app/…/SKS-88) · `feat-orders` · phase 2 moved |
+| **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 — `Tracker` first because the id is how you address the work
+outside the repo, `Next` last because it is the only row you act on.
+`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.
+
 ## Opt-in
 
 Linear sync is inert until `specs/.core/linear.config.json` exists — copy the

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/SETUP.md

@@ -20,9 +20,9 @@ Fresh installs can skip this section. **`MIGRATION.md` ships with the package**
 read the entry for the version you are coming from before upgrading a repo with a
 live mirror.
 
-**From 9.x — `push` now validates your issue states.** `spec-sync push` refuses
-to run until the configured `states` names have been checked against the
-workspace. `/spec-push` does that for you, so nothing changes if you drive sync
+**From 9.x — the plan verb validates your issue states.** `spec-sync plan`
+(named `spec-sync push` before v13) refuses to run until the configured `states`
+names have been checked against the workspace. `/spec-push` does that for you, so nothing changes if you drive sync
 through the skill; a script calling the CLI directly must pass
 `--workspace-states <file>` (or `--skip-state-check`). See `MIGRATION.md`
 → "v9 → v10".
@@ -202,9 +202,14 @@ Two ways to get there:
 |---------|-----------|--------------|
 | `/spec-status` | — | Read-only drift report: what would push (create/update), and whether Linear's workflow-state drifted from the spec. Writes nothing. |
 | `/spec-push`   | repo → Linear | Computes a create/update plan vs the last-pushed snapshot and applies it (issue description/state, phase sub-issues), stamping new ids back into the spec. |
+| `/spec-claim`  | repo → Linear | Take a spec over, `--release` it, or hand it `--to` a teammate. Records the owner in the spec, then pushes. Needs assignment enabled (below). |
+| `/spec-list`   | Linear → you | Read-only listing of every spec Linear holds — id, title, state, who holds it and the local spec name to start it by. Filters by state, backlog order, or assignee. Writes nothing. |
 
 Typical loop: edit the spec in-repo → `/spec-status` (what's pending) →
 `/spec-push` (send it up). There is no pull — Linear is a generated mirror.
+`/spec-list` is the read side of that: it asks Linear what exists rather than
+the repo, which is the only way to see a spec someone started on a branch you
+have not got.
 
 ### What gets pushed
 
@@ -229,6 +234,19 @@ Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog
 **Open questions**) are stripped from the pushed description — they never leave
 the repo.
 
+### Assignment (opt-in)
+
+Add `"assignee": "push"` to `sync.fieldOwnership` and the spec issue is assigned
+to whoever is building it: `/spec-start` records them, and the issue is released
+automatically when the spec completes. Left out, nothing about it happens at all
+— see **Assignment** in `linear.config.md` for the full rules.
+
+You do not configure *who you are*: it comes from your own API key. Check it
+with `skitterspec spec-sync whoami` (`--set` overrides it if the key is shared or
+a bot's), and `skitterspec spec-sync users <name-or-email>` looks somebody up.
+`skitterspec spec-sync doctor` reports the resolved identity, and stays quiet
+about it in a project that has not opted in.
+
 ## 7. What to commit
 
 - **Commit** `specs/.core/linear-base/` — the last-pushed snapshots (content

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"
   }
 }
 ```

package/assets/core/linear.config.md

@@ -133,6 +133,64 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 }
 ```
 
+## Assignment (`sync.fieldOwnership.assignee`)
+
+Off by default. Add one key and the spec issue is assigned to whoever is
+building it:
+
+```jsonc
+"fieldOwnership": {
+  "description": "push",
+  "subIssues": "push",
+  "workflowState": "push",
+  "assignee": "push"          // <- the whole opt-in
+}
+```
+
+It is deliberately **not** a config key of its own. `fieldOwnership` is already
+the documented extension point — "any key you add joins the pushed projection" —
+and assignment is exactly one more field the repo owns.
+
+- **Absent = inert.** No writes, no prompts, no drift line, and no assignee hash
+  in any snapshot. A project that never opts in cannot tell the feature exists,
+  which is why it is missing from `linear.config.json.example`: that file is
+  copied verbatim into new projects, and shipping the key there would opt
+  everyone in by default.
+- **The bucket decides.** The spec's `linear_assignee_id` is pushed while the
+  spec is live (`backlog`, `in-progress`) and cleared once it reaches `complete`
+  or `cancelled` — so finishing a spec hands the issue back with no unassign
+  step for anyone to remember. The stamp stays in the file, and so does
+  `> **Developer:**`: they record who *actioned* the work, which outlives who is
+  holding it.
+- **Unset means don't touch.** A spec that records nobody sends no assignee at
+  all, so an issue a PM assigned in Linear is never overwritten. Only an assignee
+  the repo itself pushed is ever cleared — and a snapshot written before you
+  opted in counts as "never pushed", not as "was nobody".
+- **Only the spec issue.** Phase sub-issues are never assigned: one person builds
+  a spec, and N assigned sub-issues is N notifications for one piece of work.
+  They stay independently assignable in Linear.
+
+**Who you are** is not configured here, and cannot be — this file is committed,
+so a user id in it would follow the repo to every teammate who clones it. It is
+derived from your own API key (`viewer`) and cached per machine in
+`~/.config/skitterspec/credentials.json` beside the key. `spec-sync whoami`
+shows it, `--set` overrides it when the key is shared or a bot's, and
+`spec-sync users` looks somebody up by name or email.
+
+Ownership moves with **`/spec-claim`** — take it, `--release` it, or `--to` a
+teammate.
+
+**Reading it back** is **`/spec-list`** (engine: `spec-sync list`), the one
+command that asks Linear what exists instead of the repo. It lists parentless
+issues — a phase sub-issue carries a parent, a spec issue does not — joined to
+the local spec folder that owns each one, so every row carries the name you
+paste into `/spec-start`. Scope is the live states by default
+(`--state`/`--all`/`--in-progress` to change it, `--next N` for the top of the
+backlog in Linear's own order), and `--mine`/`--by <user>` filter by assignee,
+reusing the identity above rather than a second copy of it. It writes nothing,
+and it says what it did not show — the count, the archived exclusion, and any
+cap — rather than implying a completeness it never checked.
+
 ## The deployment ladder (`release.stages`)
 
 A spec's lifecycle stops at `complete`. Where a ticket goes **after** that —