@skitterbyte/skitterspec-linear 12.0.0 → 14.0.0

package/MIGRATION.md

@@ -1,5 +1,297 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v19 → v20 (a phase owes a verdict)
+
+### Breaking change
+
+**A phase that has ended now refuses to go further until you send a verdict.**
+`/spec-next` **arms** a gate when it finishes a phase and renders its review
+page. While it is armed, two things refuse:
+
+- `/spec-next` will not build the next phase.
+- `git commit` inside **that spec's own worktree** is blocked by a harness hook
+  — which is what covers a bare `git commit`, a chained command, and
+  skittership's `/commit` without skitterspec editing any of them.
+
+Exactly two things clear it, and both are one command:
+
+```
+# press Commit or Commit & Continue on the review page — or:
+skitterspec spec-env review skip "none: additive, nothing to revert"
+```
+
+The skip is deliberately not silent: the reason goes into the review outcome
+log, on the same reasoning as the `Gating:` header — a reason is a decision a
+reviewer can argue with, where silence is an oversight.
+
+**It is on by default** wherever isolation is configured (`env.config.json`
+present). To turn it off for a project, add to `specs/.core/env.config.json`:
+
+```json
+{ "review": { "required": false } }
+```
+
+Three things keep it a push rather than a wall, and they are worth knowing
+before you reach for that setting. It is armed **only by a phase ending**, so a
+mid-phase `/spec-diff` owes nothing. The exit is always one command. And it
+accuses only on a positive signal — no engine, an unreadable payload, a commit
+on the base branch or in another spec's tree, a repo with no isolation: every
+cannot-tell lets the commit through.
+
+### Breaking change
+
+**`.claude/settings.json` is now written by the installer.** `skitterspec init`
+and `skitterspec update` copy `.claude/hooks/review-gate.js` and register it as
+a `PreToolUse` hook in your project's **committed** settings file. That is a
+tracked file in most repos, so expect it in `git status` after upgrading — and
+commit it, because a hook only a fraction of the team has is a gate that holds
+for a fraction of the team.
+
+A settings file that cannot be parsed is **reported and left alone**, never
+rewritten. The hook is an extra layer: the engine and `/spec-next` hold the gate
+without it.
+
+### The review page can now reach your session — deliberately
+
+This inverts an invariant the docs used to state outright: *a device that
+reaches your page cannot reach your conversation*. It no longer holds, and the
+change is the point. `/spec-next` now ends a phase by rendering the page and
+**waiting** on it, so the button you press is what carries the work on — there
+is no command to remember.
+
+What replaced the old guard is two mechanisms and one rule:
+
+- **The serve token** — 48 random bits in the URL path, minted per server —
+  decides who can POST at all.
+- **The wait window** — only a pass that arrives *while the session is waiting*
+  is claimed for you, and two arrivals refuse rather than pick one.
+- Outside that window nothing is claimed unasked. `/spec-reviewed`, or
+  `/spec-reviewed 324199` to name one exactly, is still how a pass sent when
+  nobody was waiting gets picked up — and it is still user-only, so the model
+  cannot claim a pass on its own.
+
+A `file://` page has no server to talk to, so it copies and you paste, exactly
+as before.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Commit `.claude/settings.json` and `.claude/hooks/review-gate.js`.** Both
+   are new in your working tree after the update.
+3. **Nothing else to configure.** `review.required` defaults to `true` and
+   `review.commitWith` defaults to `/commit`; neither needs adding unless you
+   are changing it.
+
+## `@skitterbyte/skitterspec-linear` v13 → v14 (a phase owes a verdict)
+
+The same change as `@skitterbyte/skitterspec` v19 → v20 above — this
+distribution composes the same lifecycle skills. Read that entry; nothing here
+is Linear-specific.
+
+## `@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 +382,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 +396,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 +446,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 +563,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,13 @@
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
   },
+  "review": {
+    "reader": "detect",
+    "servePort": 7777,
+    "serveOnRemote": true,
+    "commitWith": "/commit",
+    "required": true
+  },
   "live": {
     "migrations": []
   }