@skitterbyte/skitterspec-linear 9.1.0 → 10.0.0

package/MIGRATION.md

@@ -0,0 +1,156 @@
+# Migration guide
+
+## `@skitterbyte/skitterspec-linear` v8 → v9 (a spec is an Issue, phases are sub-issues)
+
+**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).
+
+### Breaking changes
+
+| Area | v8 | v9 |
+|------|-----|-----|
+| `linear.config.json` → `mapping` | `{specFolder:"project", phases:"milestone", tasks:"issue"}` | `{specFolder:"issue", phases:"subissue", tasks:"none"}` |
+| `linear.config.json` → `linear` | `initiativeId` | `projectId` (the project picker's default) |
+| `linear.config.json` → `states` | Linear **Project** statuses (e.g. `Completed`) | Linear **issue** workflow states (e.g. `Done`) |
+| `linear.config.json` → `sync.fieldOwnership` | `{description, milestones, tasks, workflowState}` | `{description, subIssues, workflowState}` |
+| Phase frontmatter | `linear_milestone_id` | `linear_issue_id` (the sub-issue id) |
+| Overview frontmatter | `linear_project_id` + `linear_identifier` | `linear_identifier` (the spec issue) |
+| Last-pushed snapshot | `{project, milestones, issues}` | `{issue, subIssues}` |
+
+### What to do
+
+1. **Upgrade and re-run `update`:** `npx @skitterbyte/skitterspec-linear update`.
+   It refreshes the skills, the `linear.config.md` / `SETUP.md` docs, and the
+   config example.
+2. **Edit `specs/.core/linear.config.json`** to the new keys above (or delete it
+   and re-copy `linear.config.json.example`). Point `states` at your workspace's
+   **issue** states; set `linear.projectId` if most specs belong to one Project —
+   it pre-selects the picker's default rather than fixing every spec there.
+3. **Optionally add `intake`** to start specs from issues someone else filed:
+
+   ```jsonc
+   "intake": {
+     "label": "web-app",      // the inbox `/spec --from-issue` browses
+     "bugLabels": ["bug"]     // issues with these route to /spec-bug
+   }
+   ```
+
+   Without it, `/spec SKI-123` still adopts an issue by id; only the browsable
+   inbox and the bug routing need the labels.
+4. **Existing pushed specs:** the snapshot format changed, so the first
+   `/spec-push` after upgrading **re-creates** the mirror (a fresh issue +
+   sub-issues). Delete any stale `specs/.core/linear-base/*.base.json` and the old
+   `linear_project_id` / `linear_milestone_id` frontmatter first. If you were
+   pre-first-push, there's nothing to reconcile.
+5. **Task-level issues** created under v8 are no longer managed by the sync —
+   close or repurpose them in Linear by hand.
+
+## `@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.)
+
+### Removed skills (breaking) → where they went
+
+| Removed skill | Replaced by |
+|---------------|-------------|
+| `/spec-env` | **Automatic in `/spec-go`** — it provisions the worktree and (with your OK) starts the spec's dev servers. Escalate Docker later with the CLI: `skitterspec spec-env up <name>`. |
+| `/spec-env-down` | **Folded into `/spec-complete` and `/spec-cancel`** — they tear the environment down (dev servers, worktree, stack, slot) as part of finishing/abandoning a spec. |
+| `/spec-ready` | **Folded into `/spec`** — grilling now writes a `Ready` spec directly (or `Draft` if you deliberately leave open questions). Go straight to `/spec-go`. |
+
+The **`skitterspec spec-env` CLI engine stays** (`up`, `down`, `dev`, `connect`,
+`integrate`, `status`, `resolve`) — only the three *skills* were removed. Anything
+that scripted those CLI verbs keeps working.
+
+### New — `/spec-connect` and two config blocks
+
+- **`/spec-connect <name>`** points your canonical `localhost` ports at a spec's
+  running dev servers (so you can test a worktree's UI/API at the normal URL);
+  `/spec-connect main` hands the ports back. It's a small bundled Node reverse
+  proxy — no external install. Exclusive: one spec exposed at a time.
+- **`env.config.json` gains `dev` and `proxy` blocks.** `dev` lists the host dev
+  servers `/spec-go` starts (`{ name, command, portVar, health?, frontPort? }`);
+  `proxy` configures the front-door proxy (`{ enabled, host }`). Both default to
+  off/empty, so existing projects are unaffected until you fill `dev` in.
+
+### What to do
+
+1. **Upgrade and re-run `init`** (or `update`): `npx @skitterbyte/skitterspec
+   update`. It stops installing the three removed skills, installs `/spec-connect`,
+   and refreshes the CLAUDE.md section + `spec-planning` rule. Your specs and
+   `env.config.json` are untouched.
+2. **Remove muscle memory for the old commands** — use `/spec-go` to bring a spec
+   up, `/spec-complete`/`/spec-cancel` to tear it down, and `/spec` (no separate
+   `/spec-ready`) to reach a Ready spec.
+3. **To test UI/API worktrees:** add a `dev` block to `env.config.json` (see
+   `specs/.core/env.config.md`), then `/spec-go` → `/spec-connect <name>`.
+
+## `@skitterbyte/skitterspec` v1 → v2 (tracker-free base)
+
+**v2 of the base package is tracker-free.** The Linear sync feature — the
+`/spec-status`, `/spec-push` skills, the `spec-sync` CLI, the
+Linear-aware steps of `/spec` and `/spec-go`, and the `linear.config.*`
+templates — moved out of `@skitterbyte/skitterspec` into a separate **superset**
+distribution, `@skitterbyte/skitterspec-linear`. You now install exactly one:
+
+| If you… | Install |
+|---------|---------|
+| don't sync specs to a tracker | `@skitterbyte/skitterspec` (v2) |
+| use (or want) Linear sync | `@skitterbyte/skitterspec-linear` |
+
+Everything else — the spec lifecycle and per-spec isolation — is unchanged and
+present in **both**.
+
+### If you did NOT use Linear sync
+
+Nothing to do. Upgrade to v2 and re-run `init` (or `update`) as usual. The base
+never installed the Linear skills for you, so there's nothing to remove.
+
+### If you DID use Linear sync
+
+Switching is one install plus a re-`init`:
+
+1. **Install the superset** (in place of the base):
+
+   ```sh
+   npm rm @skitterbyte/skitterspec        # if it was a dependency
+   npx @skitterbyte/skitterspec-linear init
+   ```
+
+2. **Re-run `init`.** It re-installs the shared skills (now composed with the
+   Linear steps) and the three sync skills, and re-scaffolds the config
+   templates. Your existing files are preserved — `init` never overwrites without
+   `--force`.
+
+3. **Your config is unchanged.** The live config path is still
+   `specs/.core/linear.config.json`, and the committed base sidecars under
+   `specs/.core/linear-base/` are read as-is. No re-linking, no re-sync.
+
+That's it — `/spec-status`, `/spec-push`, and `skitterspec-linear
+spec-sync …` work exactly as before.
+
+### One config note — branch naming
+
+Embedding the Linear identifier in a worktree branch name is now configured in the
+**isolation** config, not the Linear config. In `specs/.core/env.config.json` set:
+
+```jsonc
+"branch": { "pattern": "{identifier}-{slug}", "identifierField": "linear_identifier" }
+```
+
+If you don't need the id in branch names, leave the default `{type}/{slug}` — the
+old implicit Linear-branch behaviour is off unless you opt in this way. (This is
+the only behavioural change beyond the package split.)
+
+## Why the split
+
+The base couldn't ship without a specific tracker's fingerprints baked into shared
+skills and a `src/sync/` engine. Extracting the provider makes the base a clean,
+tracker-free workflow and lets a new provider (e.g. Jira) ship as another superset
+over the same base — without re-patching the base. See
+`specs/complete/feat-extract-ticketing-provider/` for the full rationale.

package/README.md

@@ -51,17 +51,38 @@ fuller guide):
    `/spec-status` reports what would push. Sync is **one-way**: the repo is the
    source of truth and Linear is a generated mirror.
 
+## Upgrading
+
+```sh
+npx @skitterbyte/skitterspec-linear update
+```
+
+`update` refreshes the files it manages (skills, rules, `specs/.core` docs) and
+**keeps anything you edited**. A file it kept is listed under
+`customized (kept)` with the change it declined summarised as `+added −removed`:
+
+```
+customized (kept):
+  .claude/rules/spec-planning.md  +34 −13
+```
+
+Add `--diff` to see those changes as a unified diff before deciding whether to
+re-apply your edits on top, or `--force` to take the package version and lose
+them. Your `specs/` content and live `.core` config are never touched.
+
 ## What the superset adds
 
 On top of the base skills (`/spec`, `/spec-go`, isolation, …):
 
 - **`/spec-status`** — read-only drift report: what the next push would create /
-  update, plus any workflow-state drift. Changes nothing.
+  update, any workflow-state drift, and any phase whose status signals disagree
+  (see **Phase status** below). Changes nothing.
 - **`/spec-push`** — repo → Linear, one-way. Diffs the spec against a committed
   last-pushed snapshot and applies only what changed (issue description + state,
   phase sub-issues), stamping the returned ids back into the spec.
 - **`spec-sync` CLI** (`skitterspec-linear spec-sync …`) — the deterministic
-  engine behind the skills, for CI / local runs.
+  engine behind the skills, for CI / local runs:
+  `normalize` · `push` · `stamp` · `record` · `status` · `linked`.
 
 The shared `/spec`, `/spec-bug` and `/spec-go` skills come composed with the
 Linear steps filled in: `/spec` asks which Linear **Project** the spec belongs to,
@@ -83,8 +104,10 @@ spec, and a smoke test. Per-field docs live in `specs/.core/linear.config.md`.
 **What pushes:** the spec is one Linear **issue** — the spec body travels as its
 **`description`**, each phase as a **sub-issue** (phase name → title, `**Goal:**`
 → description, phase emoji → state), and the spec's lifecycle folder sets the
-issue's **workflow state**. Tasks are **not** synced — they stay in the repo phase
-files. Priority, labels, cycles and comments are **Linear-native triage** — the
+issue's **workflow state**. A phase's **tasks are mirrored** into its sub-issue's
+description as a read-only checklist (`mapping.tasks: "checklist"`, the default;
+`"none"` keeps the Goal line alone) — no issue is created per task, and a box
+ticked in Linear is overwritten by the next push. Priority, labels, cycles and comments are **Linear-native triage** — the
 PM's to set in Linear; one-way sync neither pushes nor reads them, so they're
 never clobbered. A workflow-state a teammate moves in Linear is surfaced by
 `/spec-status` as drift and overwritten on the next push. **Last-pushed snapshots**
@@ -105,6 +128,13 @@ replaces the description with the spec. A bug-labelled issue routes to
 `/spec-bug`, which adopts it the same way. `skitterspec-linear spec-sync linked`
 lists what's already adopted, so an issue never becomes two specs.
 
+**Phase status.** A phase's state in Linear comes from the `⬜`/`🔄`/`✅` on its
+phase-file **heading** — not from its `> **Status:**` line and not from the
+overview's phase-index row, which are the human mirrors of it. A heading carrying
+no emoji reads as *not started*, so `spec-sync normalize|push|status` warn when
+the emoji is missing or when the three disagree, rather than quietly mirroring a
+finished phase as backlog. The warnings never block a push.
+
 Branch naming that embeds the Linear id lives in the isolation config
 (`env.config.json` → `branch.pattern` with `{identifier}`, `branch.identifierField:
 "linear_identifier"`), not in `linear.config.json`.

package/assets/core/SETUP.md

@@ -3,8 +3,9 @@
 A start-to-finish guide to getting `/spec-status` and `/spec-push` working against
 a real Linear workspace. Sync is **one-way**: the repo is the source of truth and
 the linked Linear **issue** is a **generated mirror** — content is pushed up, never
-read back or merged. A spec is a Linear issue and each phase a sub-issue; tasks are
-not synced. Covers the **Linear side** (connecting the MCP server, finding your
+read back or merged. A spec is a Linear issue and each phase a sub-issue, with the
+phase's tasks mirrored into that sub-issue's description as a read-only
+checklist. Covers the **Linear side** (connecting the MCP server, finding your
 team) that the config reference (`linear.config.md`) assumes you already have.
 
 > The whole feature is **opt-in**: until `specs/.core/linear.config.json` exists,
@@ -13,6 +14,17 @@ team) that the config reference (`linear.config.md`) assumes you already have.
 
 ---
 
+## Upgrading from 8.x
+
+**v9 remapped the mirror.** A spec is now an **issue** (was a Project), a phase a
+**sub-issue** (was a Milestone), and tasks are no longer objects. The frontmatter
+keys moved with it, so a spec linked under 8.x reads as **unlinked** to v9 — the
+next `/spec-push` would mint a fresh mirror and abandon the old one.
+
+`spec-sync push` detects this and refuses to let the plan be applied blind, but
+read **`MIGRATION.md`** ("v8 → v9", shipped with the package) before upgrading a
+repo with a live mirror. Fresh installs can skip this section.
+
 ## 1. Install the package
 
 Install the Linear superset (or, if you already run the base, switch to it — it
@@ -172,10 +184,15 @@ With a linked spec, confirm push end-to-end:
   this session. Re-run step 2; remember a fresh add needs a Claude Code restart.
 - **"missing required tools: issueCreate"** — you're on the read-only endpoint
   (or a restricted API key). Use `https://mcp.linear.app/mcp` for push.
-- **A configured state name silently does nothing** — Linear ignores an unknown
-  issue state. Run `/spec-status` (it validates the `states` names against the
-  workspace) and fix `linear.config.json` to the real issue-state names
-  (`Backlog / Todo / In Progress / Done / Canceled`).
+- **"refusing — the configured issue states have not been validated"** — `push`
+  requires the workspace's issue-state names (`--workspace-states <file>`), which
+  `/spec-push` fetches for you. Run the skill rather than the CLI directly, or
+  pass the file yourself.
+- **"refusing — configured state name(s) not in the workspace"** — Linear ignores
+  an unknown issue state, so this is caught before the push rather than after.
+  Fix `linear.config.json` to the real issue-state names
+  (`Backlog / Todo / In Progress / Done / Canceled`). Upgrading from 8.x, the
+  value inverts: project status `Completed` → issue state `Done`.
 - **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one
   workspace. Remove and re-add the server to authenticate against another.
 - **Bold around an inline code span renders oddly in Linear** — Linear moves the

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

@@ -11,7 +11,7 @@
   "mapping": {
     "specFolder": "issue",
     "phases": "subissue",
-    "tasks": "none"
+    "tasks": "checklist"
   },
   "states": {
     "backlog": "Backlog",

package/assets/core/linear.config.md

@@ -3,7 +3,8 @@
 Opt-in config for the Linear sync (`/spec-status`, `/spec-push`, and the
 Linear-aware paths of `/spec` and `/spec-go`). Sync is **one-way**: the repo is
 the source of truth and the Linear **issue** is a **generated mirror**. A spec is
-a Linear issue and each phase a sub-issue; tasks are not synced. Content is
+a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
+that sub-issue's description as a read-only checklist. Content is
 pushed up and never read back or merged — `/spec-push` diffs the spec against a
 committed **last-pushed snapshot** and applies only what changed; `/spec-status`
 is a read-only drift report. The `sync.fieldOwnership` map now just selects the
@@ -41,16 +42,24 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   },
 
   // How a spec's parts map onto Linear objects: a spec is an Issue, each phase a
-  // sub-issue (a child issue), tasks are not synced. These are the defaults.
+  // sub-issue (a child issue). `tasks` selects how a phase's checkboxes reach
+  // that sub-issue: "checklist" mirrors them into its description (default),
+  // "none" leaves the description as the phase's Goal line alone. Either way no
+  // issue is created per task. These are the defaults.
   "mapping": {
     "specFolder": "issue",
     "phases": "subissue",
-    "tasks": "none"
+    "tasks": "checklist"
   },
 
   // Map the spec's lifecycle bucket → the Linear ISSUE workflow-state name. Used
   // for the spec issue's state (from its folder) AND each sub-issue's state (from
-  // the phase emoji). Names must match the workspace's issue states exactly.
+  // the phase emoji). Names must match the workspace's issue states exactly —
+  // Linear silently IGNORES an unknown state, so a typo pushes clean and the
+  // issue never moves. `/spec-push` fetches the workspace's names and `push`
+  // refuses to run without them, so a wrong name here fails loudly rather than
+  // quietly. (Upgrading from 8.x? The right value inverts: the project status
+  // `Completed` becomes the issue state `Done`.)
   "states": {
     "backlog": "Backlog",
     "in-progress": "In Progress",
@@ -112,8 +121,18 @@ recreates:
 - **Phases → sub-issues.** Each phase file maps to a child issue (`parentId` = the
   spec issue). The link id lives in the phase file's frontmatter
   (`linear_issue_id`); its title ← the phase h1, its description ← the phase
-  `**Goal:**` line, its state ← the phase heading emoji (⬜/🔄/✅).
-- **Tasks are not synced.** Task checkboxes stay in the repo phase files only.
+  `**Goal:**` line plus its task checklist (see below), its state ← the phase
+  heading emoji (⬜/🔄/✅).
+- **Tasks are mirrored, not synced.** With `mapping.tasks: "checklist"` (the
+  default) a phase's checkboxes are rendered into its sub-issue's description as
+  a markdown checklist — nesting and `[x]` state preserved, any legacy inline
+  `(KEY-123)` stripped. No issue is created per task and nothing is read back, so
+  a box ticked in Linear is overwritten by the next push. Set `"none"` to keep
+  the description as the Goal line alone.
+
+  Turning this on (or off) changes every sub-issue's description, so the first
+  `/spec-push` afterwards reports every already-linked sub-issue as an update.
+  That is expected — they update in place and no duplicates are minted.
 
 Unlinked local items (a spec with no `linear_identifier`, a phase with no
 `linear_issue_id`) are created in Linear on the next `/spec-push`, which stamps

package/assets/skills/spec/SKILL.md

@@ -289,7 +289,8 @@ below (nothing to do here without one).
 If it's absent, skip this phase entirely — the spec stays local-only and `/spec`
 behaves exactly as above. When present, after writing the spec, link it to Linear
 so status and discussion live there while the repo stays the co-authoring surface.
-A spec is a Linear **issue**; each phase is a **sub-issue**; tasks are not synced:
+A spec is a Linear **issue**; each phase is a **sub-issue**, carrying that
+phase's tasks in its description as a read-only checklist:
 
 - **Discover the Linear MCP tools at runtime** (don't hardcode names). If Linear
   isn't connected/authed, relay the fix and stop — leave the spec written and
@@ -301,19 +302,20 @@ A spec is a Linear **issue**; each phase is a **sub-issue**; tasks are not synce
 - **Create a sub-issue per phase** (the `mapping.phases` target — `subissue` by
   default): a child issue with `parentId` = the spec issue, named from each phase
   file, in execution order.
-- **Add the frontmatter block** to `00-overview.md` (above the `#` title) so the
-  spec is linkable:
-
-  ```yaml
-  ---
-  linear_identifier: "<TEAM-123>"
-  linear_url: "https://linear.app/..."
-  last_synced_at: "<ISO-8601 now>"
-  ---
+- **Stamp the ids** so the spec is linkable — one call, no hand-edited
+  frontmatter:
+
+  ```
+  skitterspec spec-sync stamp <spec> \
+    --issue TEAM-123 --url https://linear.app/… \
+    --sub 01-<slug>=TEAM-124 --sub 02-<slug>=TEAM-125
   ```
 
-  Stamp each phase file's `linear_issue_id` with its sub-issue id. (Status is not
-  stored in frontmatter — it comes from the spec's lifecycle folder.)
+  It writes `linear_identifier`/`linear_url` onto `00-overview.md` and each phase
+  file's `linear_issue_id`, validating every ref and id **before** touching a
+  file — on any problem it changes nothing and exits non-zero, so a typo can't
+  leave the spec pointing at an issue that isn't there. (Status is not stored in
+  frontmatter — it comes from the spec's lifecycle folder.)
 - **Write the initial base sidecar** so the spec starts clean and non-diverged —
   run `skitterspec spec-sync record <spec>` to capture the local snapshot as the
   committed base (`sync.baseDir`). `/spec-status` should report in-sync right after.

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

@@ -1,13 +1,14 @@
 ---
 name: spec-push
-description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. A spec is a Linear issue and each phase a sub-issue; tasks are not synced. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (issue description/state, phase sub-issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
+description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. A spec is a Linear issue and each phase a sub-issue, with the phase's tasks mirrored read-only into that sub-issue's description. Runs `skitterspec spec-sync push` to get a create/update plan, applies it over MCP (issue description/state, phase sub-issues), stamps the returned ids back into the spec, then records the snapshot. Never reads Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
 ---
 
 # /spec-push — send a spec up to Linear (one-way)
 
 Repo → Linear. The repo is the **source of truth**; Linear is a **generated
 mirror**. A spec is a Linear **issue**; each phase is a **sub-issue** (a child
-issue). Tasks are not synced — they live only in the repo phase files. This skill
+issue), and a phase's tasks are mirrored into that sub-issue's description as a
+read-only checklist — never as issues of their own. This skill
 computes what changed since the last push and applies it — it never reads Linear
 content back or merges. A person editing the mirror in Linear will see it
 overwritten on the next push.
@@ -19,10 +20,36 @@ tell the user how to enable Linear sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Get the plan from the engine
+## 2. Connect, and validate the issue states
+
+Discover the issue **read + create/update** tools at runtime (`get_issue`,
+`save_issue` — a single upsert covers create and update), plus the **project
+list** tool if this push will mint the spec issue (see the picker below — it is
+optional; without it the picker is skipped, not failed). If Linear isn't
+connected or a needed tool is missing, relay the fix and stop, **writing
+nothing**.
+
+Then fetch the workspace's issue workflow-state **names** and write them to a
+file as a JSON array (e.g. `["Backlog","In Progress","Done","Canceled"]`). Step 3
+requires that file: `push` **refuses to run** without it, because Linear silently
+ignores an unknown issue state — the description lands, the issue never moves,
+and nothing errors. If the check reports a name that isn't in the workspace, stop
+and fix `specs/.core/linear.config.json`.
+
+**If the check refuses, offer to fix it.** The refusal lists every configured
+name the workspace lacks, the workspace's real state names, and — where the
+bucket makes it unambiguous — which one to use instead. Relay that, then offer to
+apply it to `specs/.core/linear.config.json` → `states`, and do so on the user's
+confirmation. Never edit their config without asking, and never guess a bucket
+the refusal made no suggestion for — ask which state they want.
+
+`--skip-state-check` exists for the deliberate exception; do not reach for it to
+get past a failing check.
+
+## 3. Get the plan from the engine
 
 ```
-skitterspec spec-sync push <spec> --json
+skitterspec spec-sync push <spec> --workspace-states <file> --json
 ```
 
 The engine prints a JSON **plan** (no network, no remote read):
@@ -42,19 +69,15 @@ date — say so and stop. `state` values are local buckets
 (`backlog`/`in-progress`/`complete`/`cancelled`); map each to the Linear
 issue-state NAME via `config.states` at apply time.
 
-## 3. Discover the Linear MCP tools
+### Stop if the plan reports a pre-9.0 mirror
 
-Discover the issue **read + create/update** tools at runtime (`get_issue`,
-`save_issue` — a single upsert covers create and update), plus the **project
-list** tool if this push will mint the spec issue (see the picker below — it is
-optional; without it the picker is skipped, not failed). If Linear isn't
-connected or a needed tool is missing, relay the fix and stop, **writing
-nothing**.
-
-**Validate the issue states first.** Fetch the workspace's issue workflow-state
-names and run `skitterspec spec-sync status <spec> --workspace-states <file>`; if
-it errors (a configured `states` name isn't in the workspace), stop and fix the
-config — Linear silently ignores an unknown issue state.
+If the plan carries a **`legacy`** field, this spec was linked under the pre-9.0
+model (`linear_project_id` / `linear_milestone_id`). v9 reads the new keys, finds
+none, and the plan above is therefore **all-creates** — applying it mints a fresh
+mirror and **abandons** the existing one. **Stop.** Relay `legacy.keys`,
+`legacy.files` and `legacy.orphanCount` ("this would orphan N live objects"),
+point at `MIGRATION.md` → "v8 → v9", and apply nothing until the user has
+migrated or explicitly confirms they want a new mirror.
 
 ## 4. Apply the plan (order matters)
 
@@ -62,22 +85,37 @@ config — Linear silently ignores an unknown issue state.
    **mints** it: run the picker in **Picking the Linear Project** below, then
    create it with `save_issue` (`team` = `linear.teamId`; `project` = the picked
    id; `title` from the spec title; `description` from `plan.issue.description`;
-   state from `plan.issue.state` via `config.states`). Stamp the returned
-   identifier into `00-overview.md` frontmatter as `linear_identifier` (and
-   `linear_url`). If it already exists and `plan.issue` is present, **update it by
-   id and send no `project`** — its placement is Linear's from then on.
+   state from `plan.issue.state` via `config.states`). Keep the returned
+   identifier and url for step 5 — don't hand-edit frontmatter. If it already
+   exists and `plan.issue` is present, **update it by id and send no `project`**
+   — its placement is Linear's from then on.
 2. **Sub-issues create** → for each, `save_issue` with `parentId` = the spec
-   issue id (`name` → title, `goal` → description, `state` via `config.states`);
-   stamp the returned id into its phase file as `linear_issue_id` (`ref` is the
-   phase-file basename).
+   issue id (`name` → title, `goal` → description, `state` via `config.states`).
+   Keep each returned id against its `ref` (the phase-file basename).
 3. **Sub-issues update** → `save_issue` by `id` (title/description/state).
 
 Priority, labels, cycles and comments are Linear-native triage — do **not** push
 them; they're the PM's.
 
-## 5. Record the snapshot
+## 5. Stamp the ids, then record the snapshot
+
+Write every id you collected back into the spec in **one** call — the engine
+does the file edits, so there is no hand-editing of frontmatter:
+
+```
+skitterspec spec-sync stamp <spec> \
+  --issue SKI-11 --url https://linear.app/… \
+  --sub 01-outbox=SKI-12 --sub 02-api=SKI-13
+```
+
+Pass `--issue`/`--url` only on the push that minted the spec issue; pass one
+`--sub <ref>=<id>` for every sub-issue **created** in step 4.2 (updates already
+have their id). It validates every ref and id **before** writing anything and
+exits non-zero having changed nothing if any is wrong — so a typo can't leave the
+spec half-stamped, pointing at an issue that isn't there. Fix what it reports and
+re-run; it is safe to repeat.
 
-After everything applied and the ids are stamped into the files:
+Then record what was pushed:
 
 ```
 skitterspec spec-sync record <spec>

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

@@ -60,6 +60,19 @@ reading the code, do that instead of asking.
   creating a `0N-<slug>.md` file **and** a matching overview index row, or drop a
   dead phase by removing both. Keep the index and files in sync; **preserve
   completed `[x]` history**.
+- **A phase's status is the `⬜`/`🔄`/`✅` on its H1** — `# Phase 2 — <goal> 🔄`.
+  It is mirrored in that file's `> **Status:**` line and in the matching
+  `00-overview.md` phase-index row, but the **heading is the authoritative one**:
+  tooling reads it, and a heading carrying no emoji reads as *not started*. So a
+  finished phase marked only by a `**Status:** done` line is silently wrong
+  everywhere except the file itself. Set all three together.
+- **Especially when you create phase files.** Migrating a legacy spec (a bare
+  `<name>.md`, or a `00-overview.md` with inline phases) into the folder +
+  phase-file form means authoring `0N-<slug>.md` headings from scratch — carry
+  each phase's real status onto its H1 as you split it out, rather than
+  defaulting every new file to `⬜`. A ticketing provider projects that emoji as
+  the phase's state in the tracker, so getting it wrong mirrors a
+  complete phase as not-started.
 - Tick tasks already satisfied by the code; re-open `## Open questions` for
   anything still undecided.
 - Add a dated **Changelog** entry summarising the review (e.g. `- <date> —

package/bin/skitterspec-linear.js

@@ -15,7 +15,11 @@ const { specSanitise } = require('../src/vendor/linear/cli-sanitise.js')
 async function main(argv) {
   const [cmd, ...rest] = argv
   if (cmd === 'spec-sync') {
-    await specSync(rest)
+    // Propagate the exit code, like spec-sanitise below. Dropping it made
+    // `status --workspace-states` (a bad state name) and `stamp` (a refused
+    // write) both look successful to any caller checking $?, which is exactly
+    // what the /spec-push skill does before it applies a plan.
+    process.exitCode = await specSync(rest)
     return
   }
   if (cmd === 'spec-sanitise') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "9.1.0",
+  "version": "10.0.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",
@@ -21,7 +21,8 @@
   "files": [
     "bin",
     "src",
-    "assets"
+    "assets",
+    "MIGRATION.md"
   ],
   "engines": {
     "node": ">=18"

package/src/cli.js

@@ -79,6 +79,8 @@ Options (init / update):
   --reset                  (init) Start again: reset managed scaffolding fresh
                            (needs --yes; never touches your specs or config)
   --force                  Overwrite skill/rule/script files that already exist
+  --diff                   (update) Show the upstream changes each customized
+                           file declined, as a unified diff
   --dir <path>             Target project dir (default: positional arg or cwd)
   --no-claude-md           Skip creating/patching CLAUDE.md
   --yes, -y                Accept defaults; skip the interactive setup prompts
@@ -104,6 +106,7 @@ function parse(argv) {
     removeReleaseTooling: false,
     resync: false,
     reset: false,
+    diff: false,
   }
   const positional = []
   for (let i = 0; i < argv.length; i++) {
@@ -116,6 +119,7 @@ function parse(argv) {
     else if (a === '--remove-release-tooling') opts.removeReleaseTooling = true
     else if (a === '--resync') opts.resync = true
     else if (a === '--reset') opts.reset = true
+    else if (a === '--diff') opts.diff = true
     else if (a === '--dir') opts.dir = argv[++i]
     else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
     else positional.push(a)
@@ -1346,7 +1350,7 @@ async function run(argv) {
           break
         }
         if (action === 'resync') {
-          resync(dir, { claudeMd: opts.claudeMd, force: opts.force })
+          resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
           break
         }
         // action === 'create-missing' → fall through to a normal (skip-existing) init.
@@ -1365,7 +1369,7 @@ async function run(argv) {
     case 'update':
       // `update` is a resync — refresh managed files, keep customized ones
       // (--force to overwrite). Leaves specs/ and live .core config alone.
-      resync(dir, { claudeMd: opts.claudeMd, force: opts.force })
+      resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
       await cleanupReleaseTooling(dir, opts)
       break
     default: