@skitterbyte/skitterspec-linear 10.0.1 → 10.2.0

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

@@ -1,6 +1,6 @@
 ---
 name: spec-hotfix
-description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green like /spec-bug, then land it by tagging a new patch (for CI/CD to deploy) and cherry-picking the fix back onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Creates specs/in-progress/hotfix-<name>/00-overview.md. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
+description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green like /spec-bug, then land it by tagging a new patch (for CI/CD to deploy) and cherry-picking the fix back onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Can start from a tracker issue when a provider is installed (`/spec-hotfix <tag> <ISSUE-REF>`), adopting it as the hotfix's issue. Creates specs/in-progress/hotfix-<name>/00-overview.md. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
 ---
 
 # /spec-hotfix — fix a released version, tag it, cherry-pick back to main
@@ -20,11 +20,114 @@ Spec type convention (see `.claude/rules/spec-planning.md`):
 tag + cherry-pick — it needs the isolation engine (`specs/.core/env.config.json`).
 If isolation is absent, say so and stop; there is no in-place path.
 
+## Phase 0 — start from a Linear issue (only when asked)
+
+**Only when `specs/.core/linear.config.json` exists** *and* the invocation names an
+issue. Otherwise skip this phase entirely and grill from the user's own words.
+
+Two ways in:
+
+- **`<ISSUE-REF>`** (`SKI-123`, an issue URL, or a bare id anywhere in the
+  arguments) — adopt that issue.
+- **`--from-issue [query]`** — browse the intake inbox: issues carrying
+  `intake.label` (what the web app files under). With a `query`, filter that list
+  case-insensitively by title. Show the shortlist and let the user pick one.
+
+Then:
+
+1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
+   and drop any issue whose identifier is already stamped on a spec. If the user
+   named such an issue directly, **stop** and point them at that spec — one issue
+   never becomes two specs.
+2. **Read the issue** with the discovered issue-read tool: title, description,
+   labels, reporter, URL. If Linear isn't connected, say so and offer to carry on
+   without it — a spec written from the user's own description is still a spec.
+3. **Route the issue to the right skill.** Match the issue's labels
+   (case-insensitively) against two lists, **checking `hotfixLabels` first**:
+
+   - **`intake.hotfixLabels`** → this is broken in **production**, so it needs a
+     fix against the released version, not `main`. Say so, name the matching
+     label, and tell the user to run **`/spec-hotfix <ISSUE-REF>`** — then stop.
+   - **`intake.bugLabels`** → a bug report, not a feature request. Say so, name
+     the label, and tell the user to run **`/spec-bug <ISSUE-REF>`** — then stop,
+     without authoring a Feature spec.
+
+   **Hotfix wins when an issue carries both**, and deliberately: production is the
+   more specific destination, and the two mistakes are not equally costly. Routing
+   a prod issue to `/spec-bug` produces a fix that lands on `main` and never
+   reaches the running version — discovered only when someone asks why it hasn't
+   shipped. The reverse is a hotfix branch for something that could have waited,
+   which is merely wasteful.
+
+   With a list unset, nothing routes through it; with both unset every issue is
+   treated as a feature request, exactly as before.
+
+   **Which checks run depends on where you are**, because a skip is about not
+   bouncing someone to the skill they are already in — not about ignoring an
+   escalation:
+
+   - **In `/spec`** — both checks run.
+   - **In `/spec-bug`** — the bug check is skipped (it would route you to
+     yourself), but the **hotfix check still runs**. A bug report labelled for
+     production is not "already handled" by being in the bug path: `/spec-bug`
+     fixes on `main`, and prod would stay broken. Say so and hand off.
+   - **In `/spec-hotfix`** — both are skipped. It is already the most specific
+     destination; there is nowhere left to route.
+
+   Then adopt the issue and reproduce it as usual: the issue body is your repro
+   material, and the failing test comes before the spec exactly as normal.
+4. **Seed, don't skip, the grill.** The issue's title becomes the working spec
+   title and its description the starting material for **Problem** — or
+   **Symptom** in a bug or hotfix spec, which is where a report belongs. Quote the
+   reporter's words rather than paraphrasing them away. Note the reporter and the
+   issue URL for context. Everything after this runs exactly as normal: an issue
+   is a *request*, not a groomed spec, so grill it as hard as anything else.
+
+   **In `/spec-hotfix`, also mine the issue for a version.** Any release-shaped
+   string in the report is a *suggestion* for the base tag, offered when the skill
+   asks which version prod is running — never used as a default. The reporter's
+   version is the one they saw the bug on, which is often not what is deployed.
+
+### Adopting the issue
+
+The issue **becomes** the spec's issue — it is not copied and no second issue is
+minted. This is identical in `/spec`, `/spec-bug` and `/spec-hotfix`; only *when*
+it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step 4,
+`/spec-hotfix` in its step 5). Once the spec file exists:
+
+- **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
+  from the adopted issue. That is the whole link: every later skill
+  (`/spec-push`, `/spec-status`, `/spec-go`) keys off it being present.
+- **Do not run the project picker** and never send `project`. The issue was filed
+  somewhere deliberately — where it lives is Linear's business, and adoption is
+  not a mint.
+- **Do not write a base sidecar.** Leaving `sync.baseDir` empty for this spec is
+  what makes the **linking push** send the spec over the reporter's original
+  description (an **update** to the existing issue, plus a sub-issue per phase).
+  Recording a snapshot here would declare the mirror already in sync and strand
+  the issue showing the raw report forever.
+- **Say what will happen** in the finish-up message. The linking step runs right
+  after the spec is written, so the issue's description is replaced by the spec
+  **then** — not on some later manual push. The reporter's words are not lost:
+  they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
+  keeps the original in the issue's history.
+
 ## 1. Establish the base version (the tag)
 
-- Take the release tag from the argument — `/spec-hotfix <tag> <name>` (e.g.
-  `/spec-hotfix v33.16.4 login-crash`). If it's missing, **ask which version prod
-  is running** — don't guess.
+- **Read the arguments.** `/spec-hotfix <tag> <name>` (e.g.
+  `/spec-hotfix v33.16.4 login-crash`). An argument shaped like an issue
+  reference — letters, a hyphen, digits (`SKI-123`) —
+  is **always a reference, never a name**, so `/spec-hotfix v33.16.4 SKI-123` and
+  `/spec-hotfix SKI-123`
+  both mean "adopt that issue". Release tags don't take that shape, so the two
+  can't be confused. With no name and no reference, ask what to call it.
+- Take the release tag from the argument. If it's missing,
+  **ask which version prod is running** — don't guess. When an issue was adopted
+  above, **offer any versions it mentions** as suggestions — clearly labelled as
+  the reporter's words, not a default — and still wait for the answer. A reporter
+  usually names
+  the version they *saw* the bug on, which is not necessarily what is deployed,
+  and a hotfix forked from the wrong tag fails late.
 - **Verify the tag exists** before anything else:
   `git rev-parse --verify <tag>^{commit}`. If it doesn't resolve, stop and ask.
 
@@ -156,6 +259,56 @@ place of the table when the spec touches no external surface.>
 Keep the **State log** (state transitions) separate from the **Changelog** (fix
 narrative and decisions).
 
+**Only when `specs/.core/linear.config.json` exists** (Linear sync is opted in).
+If it's absent, skip this entirely — the spec stays local-only and the skill
+behaves exactly as above. When present, link the spec you just wrote so status
+and discussion live in Linear while the repo stays the source of truth. 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.
+
+**Linking is just the first push**, so it runs the same engine path `/spec-push`
+does — you never create the issue by hand:
+
+1. **Pick the transport.** `skitterspec spec-sync states --json`. With a Linear
+   API key set it answers `api` and prints the workspace's state names; without
+   one it answers `mcp` and you do the MCP work `/spec-push` describes. Write the
+   state names to a file for step 3.
+2. **Pick the Project** — run the picker in **Picking the Linear Project** below.
+   Keep the chosen id for step 4.
+3. **Get the plan.**
+   `skitterspec spec-sync push <spec> --workspace-states <file> --json > plan.json`
+   — the spec is unlinked, so this plan is all-creates: the issue and one
+   sub-issue per phase.
+4. **Apply it.**
+   `skitterspec spec-sync apply <spec> --plan plan.json --project <chosen id>`.
+   That creates the issue and its sub-issues and checks what Linear stored. It
+   then **stamps the ids into the spec** — `linear_identifier`/`linear_url` on the
+   overview, `linear_issue_id` on each phase — and **records the base snapshot**,
+   so `/spec-status` reports in-sync immediately. There is no hand-editing of
+   frontmatter and no separate `stamp` or `record` call.
+
+   If it prints `transport = mcp`, it wrote nothing: apply the plan over MCP as
+   `/spec-push` steps 4a–5 describe, ending with `spec-sync stamp` and
+   `spec-sync record`. That path is fully supported — it is what anyone without
+   an API key uses.
+5. **Echo the branch name** from `branch.pattern` so the user knows what
+   `/spec-go` will fork.
+
+**If Linear can't be reached**, say so in one line and leave the spec written and
+local — it is still a perfectly good spec, and `/spec-push` links it later. Do
+nothing destructive.
+
+**A spec that adopted an existing issue** (see the intake step) is already
+stamped, so its plan is an **update**, not a create: applying it replaces the
+reporter's description with the spec. That is the one-way rule working as
+intended — the repo is canonical and the original text stays in Linear's history.
+Skip the project picker for an adopted issue: its placement is Linear's.
+
+Leave committing to the existing convention (the user commits the spec as usual)
+and **never auto-push git** — Linear's own automation reacts to real branch/PR
+events later. Report the Linear issue URL as part of the skill's finish-up
+message.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;

package/assets/skills/spec-linear-setup/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: spec-linear-setup
+description: Configure Linear sync for this repo by interview rather than by hand. Discovers the workspace over MCP (teams, projects, labels, issue workflow states), asks how the work is organised — which team this repo files into, whether products are split by team or by project, which labels drive intake — then hands the answers to `skitterspec spec-sync init-config`, which validates them and writes specs/.core/linear.config.json. Checks the configured workflow-state names against the workspace, so a renamed state is caught now instead of silently producing a mirror that never moves. Safe to re-run: an existing config is reviewed, never overwritten without consent. Use when the user says "/spec-linear-setup", "set up Linear sync", "connect this repo to Linear", "configure linear.config.json", or "check my Linear setup".
+---
+
+# /spec-linear-setup — configure Linear sync by interview
+
+Writes `specs/.core/linear.config.json`, the file that switches one-way Linear
+sync on for this repo. You **discover and interview**; the engine
+(`spec-sync init-config`) **validates and writes**. Keep that split: composing the
+JSON yourself is how a malformed config gets committed, and the engine already
+rejects everything the loader would later reject.
+
+The gap this closes is not "I can't find my team's UUID" — it's that nothing ever
+asks how the workspace is *organised*, so the config ends up describing a shape
+nobody confirmed. Ask about structure first; the ids fall out of the answers.
+
+**Prerequisite:** the Linear MCP server connected and authenticated (`SETUP.md`
+step 2). Without it, see step 1's degrade rule — never half-write a config.
+
+## 1. Check what already exists
+
+Read `specs/.core/linear.config.json`.
+
+- **Absent** — this is a first-time setup. Carry on.
+- **Present** — say so and default to **reviewing** it, not replacing it: run the
+  discovery in step 2 and report where the live config disagrees with the
+  workspace (a team that no longer exists, a state name that was renamed, an
+  intake label that's gone). That is the most useful thing a re-run can do. Only
+  write when the user asks for it, and then pass `--force`.
+
+Then confirm MCP is reachable by making the first discovery call in step 2.
+**Degrade, never block:** if Linear isn't connected or the tools are missing, say
+so in one line — *"Linear MCP not connected — can't discover the workspace"* —
+point at the manual path in `SETUP.md` ("Configure by hand"), and
+**stop without writing anything**. A half-written config is worse than none:
+every other command switches on the moment the file exists.
+
+## 2. Discover the workspace
+
+Discover the Linear MCP read tools at runtime and call them before asking
+anything. The interview offers real lists; it never prompts for a raw id.
+
+| Tool | What you need from it |
+|------|----------------------|
+| `list_teams` | every team's name, **key** (e.g. `SKI`) and **id** (UUID) |
+| `list_projects` | the projects, per candidate team — names + ids, minus archived/completed |
+| `list_issue_statuses` | the team's **issue workflow-state names**, exactly as spelled |
+| `list_issue_labels` | the label names available for intake routing |
+
+Projects, labels and statuses are all **team-scoped** — fetch them for the team
+once step 3 has settled it, not for the whole workspace up front.
+
+## 3. Which team does this repo file into?
+
+**This config pins exactly one team for the whole repo.** Say that plainly
+whenever there is more than one, because it reframes the question: it isn't
+"which team do you like", it's *"which product's work does this repo hold"*.
+
+- **One team** — confirm it and move on; there is nothing to decide.
+- **Several teams** — list them (name + key), and ask which one this repo's specs
+  belong to. **Recommend** the team whose key or name matches the repo, and say
+  why. If the user has one repo per product and a team per product, that mapping
+  is the answer.
+- **The repo genuinely spans two teams** — sync can't express that today. Say so,
+  and offer the two honest options: pick the team that owns most of the work, or
+  split the repo's specs across two checkouts. Don't invent a workaround.
+
+## 4. How is the work split — by team, or by project?
+
+The question the old setup never asked. Both shapes are normal in Linear:
+
+- **Team per product** — each product gets its own team, its own issue prefix and
+  its own cycles. Usual when the products have different people or cadences.
+  Then `teamId` *is* the product, and `projectId` stays empty: every spec files
+  straight into the team.
+- **Project per product, inside one team** — one team, each product a project.
+  Usual when the same people work across products. Then `teamId` is that one
+  team, and `projectId` is the **default** project the picker pre-selects.
+- **Neither — projects are per-milestone/quarter** — leave `projectId` empty and
+  let the picker ask each time.
+
+Ask which shape this workspace uses, offering the discovered project list as
+evidence. **Recommend** based on what you actually see: several teams whose names
+read as products ⇒ team-per-product; one team with product-shaped projects ⇒
+project-per-product.
+
+Then set the default: offer the team's live projects plus an explicit
+**None (team only)**, and say what the choice means — `projectId` is the picker's
+*pre-selection*, not a mandate. `/spec` still offers the full list on every spec,
+and a PM re-homing an issue in Linear is never overwritten.
+
+> **Initiatives are not used for placement.** A spec issue attaches to a team and
+> optionally a project; if this workspace groups projects under initiatives, pick
+> the project inside the initiative and the grouping keeps working in Linear.
+
+## 5. Which labels drive intake? (optional)
+
+Only relevant if the user wants to *start* specs from Linear issues
+(`/spec <ISSUE-REF>`, `/spec --from-issue`). Ask, offering the discovered labels;
+"none" is a fine answer and leaves intake off entirely — a bare issue ref still
+works.
+
+- **`intake.label`** — the inbox `/spec --from-issue` browses.
+- **`bugLabels`** — issues carrying one of these route to `/spec-bug`.
+- **`hotfixLabels`** — route to `/spec-hotfix` instead: a bug that must be patched
+  on the *released* version. Takes precedence over `bugLabels` on an issue
+  carrying both.
+
+Recommend the obvious matches from the label list (a `bug` label for `bugLabels`,
+a `production`/`hotfix` label for `hotfixLabels`) rather than asking cold.
+
+## 6. Check the workflow-state names
+
+Write the `list_issue_statuses` names to a temp file as a JSON array, exactly as
+Linear spells them:
+
+```json
+["Backlog", "Todo", "In Progress", "Done", "Canceled"]
+```
+
+Pass it as `--states`. This is the check worth having:
+**Linear silently ignores an unknown issue state**, so a workspace that renamed
+`Done` would push clean and produce a mirror that never moves. Catching it here
+— while the user is still in the setup conversation — is the whole reason the
+engine validates rather than just writes.
+
+If the engine refuses, it names each bad state *and the flag that fixes it*:
+
+```
+states.complete: "Done" is not an issue state in this workspace
+  pass --state complete="Shipped"
+```
+
+Relay that, confirm the mapping with the user (the suggestion is a suggestion —
+never apply one they didn't agree to), and re-run with the `--state` flags. If it
+made no suggestion for a bucket, **ask** which state means "finished" here rather
+than guessing.
+
+## 7. Write it
+
+```
+skitterspec spec-sync init-config \
+  --team-id <uuid> [--team-key KEY] [--project-id <uuid>] \
+  [--intake-label <name>] [--bug-labels a,b] [--hotfix-labels a,b] \
+  [--state <bucket>=<name> …] \
+  --states <statesfile> [--force] [--json]
+```
+
+The engine writes **only the keys that differ from the defaults**, so the file
+shows this repo's choices and keeps inheriting everything else. `--force` is
+required to replace an existing config — never pass it without the user having
+asked for a rewrite in step 1.
+
+**Relay the engine's report as printed.** It names the team, the project (or
+"team only"), the intake labels, and how many state names were checked against
+the workspace — that report is the evidence the setup is right, so don't
+paraphrase it into "done".
+
+## 8. Report and hand off
+
+Confirm the file written and what it says, then name the next step:
+
+- `/spec` — write a spec; with Linear configured it offers the project picker,
+  creates the linked issue and stamps the id.
+- `/spec-status` — read-only drift report, the safe way to prove the link works.
+- `/spec-push` — send a spec up.
+
+Mention what setup did **not** configure, so the defaults aren't mistaken for
+decisions: phase mapping (`mapping.phases` — sub-issue per phase by default),
+field ownership, and the API key (`LINEAR_API_KEY`, which makes pushes take the
+fast path and never lives in the config). Point at `linear.config.md` for those.

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

@@ -1,14 +1,17 @@
 ---
 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, 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".
+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, then applies it with `spec-sync apply` — straight to Linear's API when a key is set (descriptions never pass through the model), or over MCP when it isn't — stamping the returned ids back into the spec and recording the snapshot. Never merges 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), 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
+issue), and the phase file is mirrored into that sub-issue's description as
+written — its prose, its sections, and its tasks as a read-only checklist, never
+as issues of their own. Only the phase's h1 and `> **Status:**` line are left
+out, because both are pushed as fields of their own (the sub-issue's title and
+state). 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.
@@ -20,21 +23,37 @@ tell the user how to enable Linear sync and stop.
 
 Use the argument, else the spec in context; ask if unclear.
 
-## 2. Connect, and validate the issue states
+## 2. Pick the transport, and get the workspace 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**.
+**Ask the engine first — it decides, not you:**
 
-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`.
+```
+skitterspec spec-sync states --json
+```
+
+With a Linear API key set (`LINEAR_API_KEY`, or whatever `auth.keyEnv` names) the
+engine talks to Linear directly. That is the **fast path**, and it is the default
+whenever a key is present: descriptions never pass through you, in either
+direction. Without a key it falls back to MCP and everything below works as it
+always has.
+
+- **`transport = api`** → the command prints the workspace's state names as a
+  JSON array. Write it to a file and carry on to step 3.
+  **Skip the MCP tool discovery entirely** — you make no Linear calls here.
+- **`transport = mcp`** → do the MCP work: 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 — 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** yourself and write them to a file as a JSON array
+  (e.g. `["Backlog","In Progress","Done","Canceled"]`).
+
+Either way you end up with a states file. Step 3 requires it:
+`push` **refuses to run** without one, 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
@@ -69,6 +88,27 @@ 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.
 
+A **`phasesDeferred`** field means `mapping.phases` is `"deferred"` and this spec
+has not started, so its phases are deliberately absent from the plan — the issue
+pushes alone and the sub-issues are minted by the push that follows `/spec-go`.
+Relay the count; it is not a sign the phase files failed to parse. Nothing else
+about applying the plan changes.
+
+The plan always carries a **`phaseMode`** field — `subissue`, `deferred` or
+`inline` — the mode that resolved for THIS spec's lifecycle bucket.
+`mapping.phases` may be a per-bucket map, so the config alone no longer tells you
+which mode a given spec got. Relay it whenever it is not `subissue`:
+
+- **`inline`** — no sub-issues are created at all. Each unlinked phase is a
+  section of the spec issue's own description, and the `## Phases` index stays as
+  its table of contents. A plan with no sub-issue creates is the expected shape,
+  not a parse failure. A phase that already carries an id keeps its sub-issue and
+  still appears under `subIssues` — apply those normally.
+- **`deferred`** — as above; the `phasesDeferred` count says how many are waiting.
+
+Nothing about how you apply the plan changes in either mode: apply exactly the
+`issue` and `subIssues` the plan lists.
+
 ### Stop if the plan reports a pre-9.0 mirror
 
 If the plan carries a **`legacy`** field, this spec was linked under the pre-9.0
@@ -79,7 +119,37 @@ mirror and **abandons** the existing one. **Stop.** Relay `legacy.keys`,
 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)
+## 4. Apply the plan
+
+**On `transport = api`, this is one command:**
+
+```
+skitterspec spec-sync apply <spec> --plan plan.json
+```
+
+It creates and updates the issue and its sub-issues, reads each description back
+and runs the same check as step 4b, stamps every returned id into the spec, and
+records the snapshot. **Steps 4a–5 below are then already done** — skip to step 6
+and report what it printed, including the transport.
+
+Two things it guarantees, so you don't have to manage them:
+
+- **It writes nothing until everything checkable has been checked** — a legacy
+  plan, a missing key, or a `config.states` name the workspace lacks all fail
+  before the first write.
+- **It stamps each id the moment its object exists.** If a run is interrupted,
+  re-run the same command: the objects it already created are linked, so the new
+  plan sees them as updates and no duplicate is minted. Never "start again" by
+  hand.
+
+If it prints **`transport = mcp`** it has written nothing and is telling you to
+apply the plan yourself — do steps 4a, 4b and 5 below. Pass `--via mcp` to force
+that deliberately.
+
+If the picker is needed (a first push minting the issue), run it first and pass
+the chosen project through as `--project <id>`.
+
+## 4a. Apply it yourself — the MCP path (order matters)
 
 1. **Spec issue** → if the overview has no `linear_identifier`, this push
    **mints** it: run the picker in **Picking the Linear Project** below, then
@@ -97,7 +167,41 @@ migrated or explicitly confirms they want a new mirror.
 Priority, labels, cycles and comments are Linear-native triage — do **not** push
 them; they're the PM's.
 
-## 5. Stamp the ids, then record the snapshot
+## 4b. Verify what Linear actually stored — the MCP path
+
+*(On the API path `apply` already did this. Skip.)*
+
+Linear reserialises markdown on save, and it does not always preserve what you
+sent — a table nested in a list item comes back with characters missing from
+every data cell, silently. Check before you record the push as good.
+
+For each issue you created or updated in step 4a, read its `description` back
+(`get_issue`) and write what you got to a JSON file:
+
+```json
+{ "issue": "<stored description>", "subIssues": { "01-outbox": "<stored>" } }
+```
+
+Then:
+
+```
+skitterspec spec-sync verify <spec> --stored <file>
+```
+
+It compares against what the engine sent, ignoring the reformatting Linear
+legitimately applies (renumbered ordered lists, `-`→`*`, collapsed table
+separators, checkbox case, whitespace) and reporting only lost or altered **word
+characters**. Relay any divergence — it prints both sides around the first
+difference. It exits 0 either way: the repo is unaffected and still correct, so
+this is a warning, not a failure.
+
+This is **not a pull**. Nothing read here is merged, stamped, or written
+anywhere; the repo remains the only source of truth. Do it before step 5 so a
+corrupted push is visible before the snapshot records it as good.
+
+## 5. Stamp the ids, then record the snapshot — the MCP path
+
+*(On the API path `apply` already did both. Skip.)*
 
 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:
@@ -109,7 +213,7 @@ skitterspec spec-sync stamp <spec> \
 ```
 
 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
+`--sub <ref>=<id>` for every sub-issue **created** in step 4a.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
@@ -128,8 +232,13 @@ branch so the mirror-link rides in the PR.
 ## 6. Report
 
 Summarise what was created/updated in Linear (the spec issue and its
-sub-issues) and confirm the snapshot was recorded. There is no pull — Linear is
-a generated mirror.
+sub-issues), **say which transport was used**, and confirm the snapshot was
+recorded. There is no pull — Linear is a generated mirror.
+
+Saying the transport matters: on the API path you never saw the descriptions, so
+"pushed 12 sub-issues" is the engine's report, not your observation. If it warned
+that Linear stored different text, relay that — the repo is still correct, and a
+re-push overwrites the mirror.
 
 ### Picking the Linear Project
 
@@ -139,8 +248,10 @@ placement is **Linear's to own**: never send `project` on an update, and never
 record the choice in the spec file or the snapshot. A PM re-homing a spec issue
 must not show up as drift or be overwritten on the next push.
 
-1. **List the candidates.** Call the discovered project-list tool for
-   `linear.teamId`. Drop archived / completed projects — they can't take new work.
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
 2. **Offer them.** Show the names (most recently updated first is fine), plus an
    explicit **None (team only)** option. Pre-select `linear.projectId` from
    `linear.config.json` when it's set and still in the list; otherwise pre-select
@@ -149,13 +260,14 @@ must not show up as drift or be overwritten on the next push.
    the list case-insensitively by name and re-offer. Don't re-fetch.
 4. **Never offer to create a project.** Projects are the PM's surface — if none
    fits, that's **None (team only)**, and someone makes the project in Linear.
-5. **Pass it once.** Include `project: <chosen id>` on the issue-create call.
-   Chose None → omit the key entirely (do not send an empty string).
-
-**Degrade, never block.** If Linear isn't connected, or the server exposes no
-project-list tool, say so in one line — *"project picker unavailable; creating the
-issue without a project"* — and carry on with `linear.projectId` if it's set, else
-no project at all. A missing picker must never fail `/spec` or `/spec-push`.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
 
 If `linear.projectId` is set but that Project is archived or missing, relay
 Linear's error and stop rather than silently minting an unparented issue.

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

@@ -82,6 +82,40 @@ reading the code, do that instead of asking.
   re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
   **State log** row).
 
+**Only when `specs/.core/linear.config.json` exists** and the spec's overview
+carries a `linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on. Nothing else in
+this step changes.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this spec's state, and the tracker is a generated mirror
+of it — leaving them to diverge until someone remembers to push by hand is the
+gap this exists to close. It costs one engine call and no model tokens when a
+Linear API key is set (see `apply.transport` in `linear.config.md`).
+
+- **Never mint.** An unlinked spec is skipped, not created. An issue born `Done`
+  or `Canceled` is tracker noise, and a spec kept deliberately local should stay
+  that way — `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
+  the repo regardless; the mirror is disposable and the next push repairs it.
+  Do not roll anything back, and do not stop to ask.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
+### Why it sits here
+
+In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
+**after the `git mv` and before the commit**, and both halves matter:
+
+- **After the move**, because the projection reads a spec's workflow state from
+  its folder bucket. Push while the folder is still in `in-progress/` and the
+  issue is set to the state the spec is *leaving*.
+- **Before the commit**, because the push stamps ids into the spec and writes a
+  snapshot under `specs/.core/`. The `git add specs/` that follows sweeps both up
+  with the status change; push after it instead and those files are left
+  uncommitted, which makes `spec-env integrate` refuse to land the branch.
+
 ## 5. Report
 
 Summarise the drift found, what you changed, any questions still open, and

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

@@ -50,3 +50,12 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
 
 Relay the engine's output verbatim. Suggest `/spec-push` if a push is pending.
 Never write to either side.
+
+A **`phases: <mode>`** line names the phase mode that resolved for this spec's
+lifecycle bucket, and appears only when it is not the default `subissue`.
+`mapping.phases` may be a per-bucket map, so this is the only place the mode a
+given spec got is stated. Under **`inline`** the phases live in the spec issue's
+description rather than as sub-issues, so "0 to create" is the expected shape
+rather than a sign the phase files failed to parse; under **`deferred`** the
+`N phase(s) deferred` line above it says how many are still waiting on
+`/spec-go`. Relay both lines as printed.