@skitterbyte/skitterspec-linear 3.1.0 → 4.0.0

package/README.md

@@ -32,16 +32,23 @@ and `/spec-go` pulls first so you build against the current shared state.
 ## Opt-in
 
 Linear sync is inert until `specs/.core/linear.config.json` exists — copy the
-scaffolded `linear.config.json.example` and fill in your team / initiative IDs
-(every field is documented in `specs/.core/linear.config.md`). Without it, this
+scaffolded `linear.config.json.example` and fill in your team id. Without it, this
 behaves exactly like the base.
 
-**Mapping** (config-driven): spec folder → Linear **Project**; each phase → a
-**Milestone**; tasks → **Issues**; an optional **Initiative** groups specs.
-**Field ownership** (`both` / `pull` / `push`) collapses conflicts — only a `both`
-field that moved on both sides is a real conflict, and `--force` backs up the
-losing side before winning. **Base sidecars** (`specs/.core/linear-base/`) are
-committed; **backups** (`specs/.core/linear-backups/`) are gitignored.
+**Start here:** `specs/.core/SETUP.md` (scaffolded by `init`) is the full
+setup guide — connecting the `linear` MCP server, finding your team id, linking a
+spec, and a smoke test. Per-field docs live in `specs/.core/linear.config.md`.
+
+**What syncs:** by default the whole spec body travels as the Linear Project
+**`description`** (co-authored, push + pull); **status / priority / labels** are
+Linear-owned (pull only). **Field ownership** (`both` / `pull` / `push`) collapses
+conflicts — only a `both` field that moved on both sides is a real conflict, and
+`--force` backs up the losing side before winning. **Opt into a per-Milestone /
+per-Issue body round-trip** — phases ↔ Linear Milestones and tasks ↔ Issues,
+compared per item — by adding `milestones`/`tasks` to `sync.keyedFields` (see the
+"Body round-trip" section of `linear.config.md`); deletions there are report-only.
+**Base sidecars** (`specs/.core/linear-base/`) are committed; **backups**
+(`specs/.core/linear-backups/`) are gitignored.
 
 Branch naming that embeds the Linear id lives in the isolation config
 (`env.config.json` → `branch.pattern` with `{identifier}`, `branch.identifierField:

package/assets/core/SETUP.md

@@ -0,0 +1,175 @@
+# Setting up Linear hybrid-sync
+
+A start-to-finish guide to getting `/spec-status`, `/spec-pull`, and `/spec-push`
+working against a real Linear workspace. 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,
+> everything below is inert and the package behaves exactly like the base
+> `@skitterbyte/skitterspec`.
+
+---
+
+## 1. Install the package
+
+Install the Linear superset (or, if you already run the base, switch to it — it
+contains the entire base, so install one **or** the other, never both):
+
+```sh
+npx @skitterbyte/skitterspec-linear init
+```
+
+## 2. Connect the Linear MCP server
+
+The sync skills talk to Linear over MCP. Add Linear's official remote server and
+authenticate — this is a one-time, per-machine step.
+
+```sh
+claude mcp add --transport http linear https://mcp.linear.app/mcp
+```
+
+Then, **inside Claude Code**, authenticate (a browser window opens for OAuth —
+pick the workspace you want to sync into):
+
+```
+/mcp        →  select "linear"  →  Authenticate
+```
+
+A newly added server only appears in `/mcp` **after Claude Code restarts** — if
+you don't see `linear`, relaunch with `claude --continue` and try again.
+
+Verify it's connected:
+
+```sh
+claude mcp list
+# linear: https://mcp.linear.app/mcp (HTTP) - ✓ authenticated
+```
+
+> Read-only trial: use `https://mcp.linear.app/mcp/readonly` to exercise
+> `/spec-status` and `/spec-pull` without granting write access. `/spec-push`
+> needs the full (writable) endpoint.
+
+## 3. Find your team id
+
+`linear.config.json` needs your Linear **team UUID**. The easiest way is to just
+ask Claude once the MCP server is connected:
+
+> "List my Linear teams with their ids."
+
+It calls the Linear `list_teams` tool and returns rows like:
+
+```
+Skitterspec — e07c2b54-dcf6-4b6e-81bd-175a9bc79868  (key: SKI)
+```
+
+Copy the `id` (the UUID). The `key` (e.g. `SKI`) is the short human handle. If you
+want an **Initiative** to group your specs, ask "list my Linear initiatives" and
+copy that id too (optional).
+
+## 4. Scaffold the config
+
+`init` dropped a `specs/.core/linear.config.json.example`. Copy it and fill in the
+ids from step 3 — the team id is the only required field:
+
+```jsonc
+// specs/.core/linear.config.json
+{
+  "linear": {
+    "teamKey": "SKI",
+    "teamId": "e07c2b54-dcf6-4b6e-81bd-175a9bc79868",
+    "initiativeId": ""            // optional
+  }
+}
+```
+
+Everything else (state names, field ownership) has sensible defaults — see
+`linear.config.md` to customise. The moment this file exists, the Linear steps in
+`/spec` and `/spec-go` and the three sync skills switch on.
+
+## 5. Link a spec to a Linear project
+
+A spec syncs once its `00-overview.md` frontmatter carries a `linear_project_id`.
+Two ways to get there:
+
+- **New spec:** run `/spec` — with Linear configured it offers to create a linked
+  Linear **Project** (one Milestone per phase) and stamps the id for you.
+- **Existing spec / existing Linear project:** add the id by hand. Ask Claude to
+  "create a Linear project for this spec" (or find an existing one's id via
+  `list_projects`), then set the frontmatter:
+
+  ```yaml
+  ---
+  linear_project_id: "640bcb1a-28cd-46b5-b2f8-ff47ce494ed1"
+  ---
+  ```
+
+## 6. Everyday sync
+
+| Command | Direction | What it does |
+|---------|-----------|--------------|
+| `/spec-status` | — | Read-only. Per-field divergence: `local-only` / `remote-only` / `conflict` / `in sync`. |
+| `/spec-pull`   | Linear → repo | Applies remote-owned fields (status/priority/labels). Refuses a real conflict unless `--force`. |
+| `/spec-push`   | repo → Linear | Sends the co-authored `description` up. Refuses if a co-authored field moved on Linear since your last sync (pull first) unless `--force`. |
+
+Typical loop: `/spec-status` → `/spec-pull` (take Linear's status) → edit the spec
+in-repo → `/spec-push` (send content up).
+
+### What actually syncs
+
+| Field | Owner | Direction |
+|-------|-------|-----------|
+| `description` (the whole spec body: problem, solution, **phases**, acceptance criteria) | co-authored | push **and** pull |
+| `workflowState` → `spec_status` | Linear | pull only |
+| `priority` | Linear | pull only |
+| `labels` | Linear | pull only |
+
+By default the **entire spec body travels as the project `description`** — phases
+and acceptance criteria included.
+
+**Optional: body round-trip.** Opt in — add `milestones`/`tasks` to
+`sync.keyedFields` (and `sync.fieldOwnership`) — and phases sync as **Milestones**
+and tasks as **Issues**, compared per item: edit an individual phase or task in
+Linear and pull just that back into the right phase file / task line, or push
+local changes up. The link ids live in the phase file frontmatter
+(`linear_milestone_id`) and inline on task lines (`- [ ] do it (SKI-123)`).
+Deletions are report-only (surfaced by `/spec-status`, never auto-applied). Full
+details in the "Body round-trip" section of `linear.config.md`.
+
+Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog**,
+**Open questions**) are stripped from the pushed description — they never leave
+the repo.
+
+## 7. What to commit
+
+- **Commit** `specs/.core/linear-base/` — the three-way merge's base sidecars
+  (last-synced snapshot per spec). Each worktree carries its own, so it must
+  travel with the branch.
+- **Gitignore** `specs/.core/linear-backups/` — `--force` recovery copies, local
+  and per-machine. Add `specs/.core/linear-backups/` to `.gitignore`.
+
+## 8. Smoke test (verify your setup)
+
+With a linked spec, confirm the round-trip end-to-end:
+
+1. `/spec-status` → note the current divergence.
+2. `/spec-pull` → Linear's status/priority/labels land in the spec's frontmatter
+   (`spec_status`, `priority`, `labels`).
+3. `/spec-status` again → **in sync**. (This also proves description idempotency:
+   Linear rewrites markdown bullets on save, and the sync canonicalizes both
+   sides so that never shows as a spurious change.)
+4. Edit the spec body locally, `/spec-push` → the change lands on the Linear
+   project's description; `/spec-status` returns to **in sync**.
+
+## Troubleshooting
+
+- **"connect the `linear` MCP server"** — the server isn't connected/authed for
+  this session. Re-run step 2; remember a fresh add needs a Claude Code restart.
+- **"missing required tools: projectUpdate"** — you're on the read-only endpoint
+  (or a restricted API key). Use `https://mcp.linear.app/mcp` for push.
+- **A field won't stop showing as diverged** — that field genuinely differs on
+  the two sides. `pull`-owned fields (status/priority/labels) resolve to Linear;
+  `/spec-pull` reconciles them. For a co-authored `conflict`, resolve locally or
+  `--force` (which backs up the losing side under `sync.backupDir` first).
+- **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one
+  workspace. Remove and re-add the server to authenticate against another.

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

@@ -26,14 +26,11 @@
     "backupDir": "specs/.core/linear-backups",
     "fieldOwnership": {
       "description": "both",
-      "milestones": "both",
-      "phaseBodies": "both",
-      "acceptanceCriteria": "both",
-      "taskBreakdown": "both",
       "workflowState": "pull",
       "priority": "pull",
       "labels": "pull"
     },
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
+    "localOnlySections": ["State log", "Changelog", "Open questions"],
+    "keyedFields": {}
   }
 }

package/assets/core/linear.config.md

@@ -77,13 +77,14 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     //   "push" — local→Linear only; a remote edit never pulls and a conflict
     //            resolves to local-wins.
     // Any field key you add here joins the compared field set; a value outside
-    // both|pull|push is rejected at load time.
+    // both|pull|push is rejected at load time. The default set is scoped to the
+    // fields that round-trip through the live skill today: the whole spec body
+    // travels as `description`; status/priority/labels are Linear-owned (pull).
+    // A phase/milestone or per-issue round-trip is a future extension — opt in by
+    // adding `milestones`/`phaseBodies`/`taskBreakdown` here once that write path
+    // exists (see the deferred body write-back note in the package README).
     "fieldOwnership": {
       "description": "both",
-      "milestones": "both",
-      "phaseBodies": "both",
-      "acceptanceCriteria": "both",
-      "taskBreakdown": "both",
       "workflowState": "pull",
       "priority": "pull",
       "labels": "pull"
@@ -91,11 +92,48 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 
     // Markdown sections of 00-overview.md that are local-only scaffolding and
     // are stripped from the pushed `description` (never sent to Linear).
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
+    "localOnlySections": ["State log", "Changelog", "Open questions"],
+
+    // OPT-IN body round-trip. Map a keyed collection field → its item id key to
+    // sync it per item (each phase ↔ a Milestone, each task ↔ an Issue) instead of
+    // as one description blob. Empty by default. See "Body round-trip" below.
+    "keyedFields": {}
   }
 }
 ```
 
+## Body round-trip (milestones & tasks) — opt-in
+
+By default the whole spec body travels as the project **`description`**. Opt a
+workspace into a finer-grained, bidirectional sync by adding the keyed fields:
+
+```jsonc
+"sync": {
+  "fieldOwnership": { "milestones": "both", "tasks": "both" },
+  "keyedFields": { "milestones": "id", "tasks": "id" }
+}
+```
+
+With this on:
+
+- **Phases ↔ Milestones.** Each phase file maps to a Linear Milestone. The link id
+  lives in the phase file's frontmatter (`linear_milestone_id`); its title ← the
+  phase h1, its description ← the phase `**Goal:**` line. The `Phases` index is
+  then stripped from the pushed `description` (no duplication).
+- **Tasks ↔ Issues.** Each `- [ ]` task line maps to a Linear Issue. The link id
+  is carried **inline** on the line — `- [ ] do the thing (SKI-123)`. Text ↔ the
+  issue title; `[x]`/`[ ]` ↔ a completed / non-completed issue state.
+- **Per-item merge.** Items are compared by id, so editing milestone A locally and
+  milestone B in Linear both apply; only the *same* item moving on both sides is a
+  conflict.
+- **Deletions are report-only.** A phase/milestone or task/issue removed on either
+  side is surfaced by `/spec-status` (and the pull/push summaries) for you to
+  resolve by hand — it is never auto-deleted.
+
+Unlinked local items (a new phase with no `linear_milestone_id`, a task with no
+inline id) are created in Linear on the next `/spec-push`, which stamps the new id
+back so they link from then on.
+
 ## Field ownership & conflicts
 
 The spec is a set of structured fields, most written by only one side. Marking a

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

@@ -1,6 +1,6 @@
 ---
 name: spec-bug
-description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
+description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. When per-spec isolation is enabled it provisions a worktree first, so the failing test and fix land on the bug's own branch, never on main. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
 ---
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
@@ -24,7 +24,49 @@ Bugs are concrete — confirm, don't over-grill. Establish:
   against the broken one (the bug usually lives in the differential). Do NOT
   patch a symptom before you understand the cause.
 
-## 2. Write the failing test FIRST (RED) — mandatory
+## 2. Isolate the fix in a worktree — when isolation is enabled
+
+**Only when per-spec isolation is enabled** (`specs/.core/env.config.json`
+exists). Skip this whole section otherwise — the fix happens in place, on the
+current branch.
+
+**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
+place), skip this whole section and fix on the current branch — same as when
+isolation is off. Warn that the fix will land wherever you currently are (usually
+`main`); reserve it for a trivial one-liner or an explicit request.
+
+A bug fix changes real source, so — exactly like `/spec-go` — it belongs on the
+bug's **own branch**, never directly on `main`. Provision the worktree **now**,
+before the failing test, so the test, the fix, and the spec all land together and
+arrive as one reviewable PR.
+
+The engine resolves a spec by its folder, so seed a **minimal stub** for it to
+provision from — you'll flesh it out in §4:
+
+- From the base branch (`main`), create
+  `specs/in-progress/bug-<name>/00-overview.md` with just the header block and the
+  `## Symptom` you established above.
+- Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
+  the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
+  the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
+- Run the printed `git worktree add`. **The worktree forks from `main`'s last
+  commit, so your uncommitted stub doesn't travel with it** — move it across so
+  `main` is left pristine:
+  `mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/`.
+- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  none of the repo's gitignored files (`.env`, local overrides). Run the printed
+  `in the worktree, run:` steps (file seeding, then `setup`) in order, before
+  anything else.
+- **Trust the worktree for this session.** The engine wrote the printed
+  `trusted:` root into `.claude/settings.local.json`, but it won't hot-reload now
+  — run `/add-dir <trusted root>` before editing into the worktree, or the first
+  edits will prompt.
+- **Do everything below in the worktree**, on the branch — the red test, the fix,
+  and the rest of the spec. Act on the worktree with absolute paths /
+  `git -C <worktreePath>`, or open a fresh session rooted there (the printed
+  opener). `main` changes only when the branch merges (at `/spec-complete`).
+
+## 3. Write the failing test FIRST (RED) — mandatory
 
 Encode the **correct** (expected) behaviour as a test, then run it and confirm it
 **fails for the right reason**:
@@ -36,10 +78,13 @@ Encode the **correct** (expected) behaviour as a test, then run it and confirm i
   passes before the fix proves nothing — keep refining the assertion until it
   genuinely captures the bug.
 
-## 3. Write the Bug spec
+## 4. Write the Bug spec
 
-Create the spec **folder** `specs/in-progress/bug-<kebab-name>/` with its entry
-point `00-overview.md` (every spec is a folder — never a bare file). A bug is
+Fill in the spec's entry point `00-overview.md`. **When isolated**, you already
+seeded this stub in §2 and moved it into the worktree — flesh it out there.
+**When not isolated**, create the spec **folder**
+`specs/in-progress/bug-<kebab-name>/` with its entry point `00-overview.md` now
+(every spec is a folder — never a bare file). A bug is
 usually a single-pass fix, so the `## Fix` block can live directly in
 `00-overview.md`. **If the fix needs phasing** (large/uncertain root cause),
 split it into phase files (`01-<slug>.md`, `02-…`) with a phase index in
@@ -90,7 +135,7 @@ The **State log** is the folder/status audit trail; later transitions
 (`/spec-complete`, `/spec-cancel`) append a row. The **Changelog** is for the
 fix narrative and decisions — keep them separate.
 
-## 4. Drive to GREEN
+## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all
   project rules (see `.claude/rules/`).
@@ -103,8 +148,10 @@ test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
 `00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
 Say so explicitly — don't fake green.
 
-## 5. Report
+## 6. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test
 result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
-archive it. Do **not** `git commit` unless the user asks.
+archive it (**when isolated**, the fix lives on the bug's branch, and
+`/spec-complete` merges it back to `main`). Do **not** `git commit` unless the
+user asks.

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

@@ -26,6 +26,12 @@ Diverting your browser to the spec is a separate explicit step — `/spec-connec
 the spec doesn't already have a worktree, provision it **first**, so all the
 housekeeping below lands on the spec's branch and never on `main`:
 
+**Opt-out:** if the user passes `--no-worktree` (or explicitly asks to work in
+place), skip the provisioning bullets below and build on the current branch — the
+same "in place otherwise" path used when isolation is off. Warn that the work
+will land wherever you currently are (usually `main`); reserve it for a trivial
+change or an explicit request.
+
 - Run `skitterspec spec-env up <name>` (the `spec-env` CLI engine). It adds a git
   worktree on a branch forked from `main`, and — only when the spec's
   `> **Stack:**` header is `worktree + docker` — also brings up its Docker stack.

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

@@ -23,7 +23,10 @@ Use the argument, else the spec in context; ask if unclear.
   spec isn't linked — stop and point at `/spec`.
 - Discover the Linear MCP project-read tool at runtime. If Linear isn't
   connected, relay the fix and stop — **do nothing destructive**.
-- Call it and write the project JSON to a temp file.
+- Call it (include milestones) and write the project JSON to a temp file. When
+  tasks are keyed, also list the project's issues and add them as an `issues`
+  array on that JSON (each `{ identifier, title, state }`) so the engine can
+  reconcile task lines.
 
 ## 3. Run the engine
 

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

@@ -47,6 +47,27 @@ tool with that field's local value (e.g. `description` → the project descripti
 The engine has already vetted the change and moved the base — so if a Linear
 write fails, re-run `/spec-pull` to reconcile rather than retrying blindly.
 
+**Milestones (`milestonesPush` in the result).** When milestones are keyed, the
+engine can't write them itself — apply the plan over MCP:
+
+- `update`: for each `{ id, name, goal }`, call the milestone-save tool with that
+  `id` (name → milestone name, goal → its description).
+- `create`: for each `{ name, goal }`, call the milestone-save tool with no id to
+  create it under the project, then **stamp the returned milestone id** into the
+  matching phase file's frontmatter (`linear_milestone_id`) so it links on the
+  next sync. Match the phase file by its title.
+
+Progress is Linear-derived — never push it.
+
+**Issues (`issuesPush` in the result).** When tasks are keyed:
+
+- `update`: for each `{ id, text, done }`, call the issue-save tool with that `id`
+  (text → title; `done` → a completed state, else a non-completed state — leave an
+  already-non-completed issue's exact state untouched).
+- `create`: for each `{ text, done }`, create an issue under the project (attach it
+  to the milestone of the phase the task lives in when known), then **stamp the new
+  issue identifier inline** on that task line (`… (SKI-123)`), matching by text.
+
 ## 5. Report
 
 Relay the git-like summary (written / skipped / backup / base) plus which Linear

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": "Spec-driven development for Claude Code, with Linear hybrid-sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus git-like /spec-status · /spec-pull · /spec-push and the spec-sync CLI. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/vendor/linear/cli-sync.js

@@ -112,6 +112,17 @@ function specSyncStatus(dir, config, specArg, flags = {}) {
       out.push(`  ${f.status.padEnd(12)} ${f.field.padEnd(18)} (${f.ownership}, ${dir_})`)
     }
   }
+  // Deletions are never auto-applied (Decision 7) — surface them for the operator
+  // to resolve by hand: a removed keyed item on either side.
+  const removed = []
+  for (const f of fields) {
+    if (!f.keyed) continue
+    for (const it of f.items) if (it.report) removed.push(`${f.field}#${it.id} (removed in ${it.side})`)
+  }
+  if (removed.length) {
+    out.push('  needs manual resolution — removed, not auto-applied:')
+    for (const r of removed) out.push(`    ${r}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -157,11 +168,31 @@ function printSyncResult(kind, result) {
   } else {
     out.push(`spec-sync ${kind}: ok`)
     if (kind === 'pull') {
+      const keyedApplied = result.keyedApplied || []
+      const keyedCreated = result.keyedCreated || []
+      const keyedReported = result.keyedReported || []
       if (result.applied.length) out.push(`  applied:   ${result.applied.join(', ')}`)
+      if (keyedApplied.length) out.push(`  updated:   ${keyedApplied.join(', ')} (phase files)`)
+      if (keyedCreated.length) out.push(`  created:   ${keyedCreated.map((c) => c.file).join(', ')}`)
+      if (keyedReported.length) out.push(`  removed:   ${keyedReported.join(', ')} (in Linear — resolve manually)`)
       if (result.deferred.length) out.push(`  deferred:  ${result.deferred.join(', ')} (body write-back — manual)`)
-      if (!result.applied.length && !result.deferred.length) out.push('  nothing to pull — up to date')
+      if (
+        !result.applied.length &&
+        !keyedApplied.length &&
+        !keyedCreated.length &&
+        !keyedReported.length &&
+        !result.deferred.length
+      ) {
+        out.push('  nothing to pull — up to date')
+      }
     } else {
       if (result.written && result.written.length) out.push(`  written:   ${result.written.join(', ')}`)
+      const mp = result.milestonesPush
+      if (mp && mp.create.length) out.push(`  milestones create: ${mp.create.map((m) => m.name).join(', ')} (skill applies via MCP)`)
+      if (mp && mp.update.length) out.push(`  milestones update: ${mp.update.map((m) => m.id).join(', ')} (skill applies via MCP)`)
+      const ip = result.issuesPush
+      if (ip && ip.create.length) out.push(`  issues create: ${ip.create.length} (skill applies via MCP)`)
+      if (ip && ip.update.length) out.push(`  issues update: ${ip.update.map((i) => i.id).join(', ')} (skill applies via MCP)`)
       if (result.skipped && result.skipped.length) out.push(`  skipped:   ${result.skipped.join(', ')} (not pushable)`)
       if (result.note) out.push(`  ${result.note}`)
     }

package/src/vendor/linear/config.js

@@ -50,17 +50,24 @@ const DEFAULT_CONFIG = Object.freeze({
   sync: Object.freeze({
     baseDir: 'specs/.core/linear-base',
     backupDir: 'specs/.core/linear-backups',
+    // The synced field set. Kept to the fields that genuinely round-trip through
+    // the live skill today: the project `description` (co-authored) plus the
+    // Linear-owned status/priority/labels (pull-only). A spec's phase/milestone,
+    // acceptance-criteria and task detail still travel *inside* `description` — a
+    // separate milestone/issue round-trip is a future extension (add the fields
+    // here to opt a workspace in). Any key you add joins the compared set.
     fieldOwnership: Object.freeze({
       description: 'both',
-      milestones: 'both',
-      phaseBodies: 'both',
-      acceptanceCriteria: 'both',
-      taskBreakdown: 'both',
       workflowState: 'pull',
       priority: 'pull',
       labels: 'pull',
     }),
     localOnlySections: Object.freeze(['State log', 'Changelog', 'Open questions']),
+    // Fields that are keyed collections (arrays of objects with a stable id),
+    // compared/merged per item rather than as one opaque value. Map field name →
+    // the item's id property. Empty by default — a workspace opts a field in
+    // (e.g. { milestones: "id", tasks: "id" }) once the body round-trip is wired.
+    keyedFields: Object.freeze({}),
   }),
 })
 
@@ -81,6 +88,7 @@ function defaults() {
       backupDir: DEFAULT_CONFIG.sync.backupDir,
       fieldOwnership: { ...DEFAULT_CONFIG.sync.fieldOwnership },
       localOnlySections: [...DEFAULT_CONFIG.sync.localOnlySections],
+      keyedFields: { ...DEFAULT_CONFIG.sync.keyedFields },
     },
   }
 }
@@ -113,6 +121,21 @@ function mergeFieldOwnership(base, parsed) {
   }
 }
 
+// Merge (and validate) sync.keyedFields. Each value is the item's id property
+// name (a non-empty string); a field listed here is compared per item.
+function mergeKeyedFields(base, parsed) {
+  if (!isObject(parsed)) return
+  for (const [field, idKey] of Object.entries(parsed)) {
+    if (typeof idKey !== 'string' || !idKey.trim()) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: sync.keyedFields.${field} = ${JSON.stringify(idKey)} ` +
+          '(expected the item id property name, a non-empty string)',
+      )
+    }
+    base[field] = idKey.trim()
+  }
+}
+
 /**
  * Merge a parsed config over the defaults. Only known keys are copied (unknown
  * keys ignored for forward-compat). Nested objects are merged field-by-field.
@@ -150,6 +173,7 @@ function mergeConfig(base, parsed) {
     assign(base.sync, parsed.sync, 'baseDir', 'string')
     assign(base.sync, parsed.sync, 'backupDir', 'string')
     mergeFieldOwnership(base.sync.fieldOwnership, parsed.sync.fieldOwnership)
+    mergeKeyedFields(base.sync.keyedFields, parsed.sync.keyedFields)
     if (Array.isArray(parsed.sync.localOnlySections)) {
       base.sync.localOnlySections = parsed.sync.localOnlySections
         .filter((s) => typeof s === 'string' && s.trim())

package/src/vendor/linear/mcp.js

@@ -16,18 +16,20 @@
  */
 
 // Canonical operations, and the regexes that match a Linear MCP tool name to
-// each. Ordered patterns: first match wins. Verified against the connected
-// Linear MCP server during build (resolves the overview's Open questions).
+// each. Ordered patterns: first match wins. Matched against the real connected
+// Linear MCP server: it exposes a single upsert `save_*` tool per object (create
+// when no id, update when id given) rather than separate create/update verbs, so
+// each write op accepts `save_*` as well as the legacy `create_`/`update_` names.
 const MATCHERS = {
   projectRead: [/get_?project\b/i, /read_?project/i, /project_?get/i],
-  projectUpdate: [/update_?project/i, /project_?update/i],
-  projectCreate: [/create_?project/i, /project_?create/i],
+  projectUpdate: [/save_?project/i, /update_?project/i, /project_?update/i],
+  projectCreate: [/save_?project/i, /create_?project/i, /project_?create/i],
   milestoneList: [/list_?.*milestone/i, /milestones?_?list/i, /get_?.*milestones?/i],
-  milestoneCreate: [/create_?.*milestone/i, /milestone_?create/i],
-  milestoneUpdate: [/update_?.*milestone/i, /milestone_?update/i],
+  milestoneCreate: [/save_?.*milestone/i, /create_?.*milestone/i, /milestone_?create/i],
+  milestoneUpdate: [/save_?.*milestone/i, /update_?.*milestone/i, /milestone_?update/i],
   issueList: [/list_?issues?/i, /issues?_?list/i, /get_?issues?/i],
-  issueCreate: [/create_?issue/i, /issue_?create/i],
-  issueUpdate: [/update_?issue/i, /issue_?update/i],
+  issueCreate: [/save_?issue/i, /create_?issue/i, /issue_?create/i],
+  issueUpdate: [/save_?issue/i, /update_?issue/i, /issue_?update/i],
 }
 
 // The minimum the push/pull engine can't run without. Milestone/issue ops are
@@ -88,17 +90,41 @@ function makeAdapter(callTool, resolved) {
     return name
   }
   return {
+    // Linear's project-read tool keys on `query` (accepts a UUID, key, or slug).
     async readProject(id) {
-      return callTool(need('projectRead'), { id })
+      return callTool(need('projectRead'), { query: id })
+    },
+    // `save_project` upserts: with `id` it updates, without it creates. Create
+    // needs a name and at least one team (`addTeams`).
+    async createProject(project) {
+      return callTool(need('projectCreate'), { ...project })
     },
     async updateProject(id, updates) {
       return callTool(need('projectUpdate'), { id, ...updates })
     },
+    // List a project's milestones (the pull read side). Most Linear reads also
+    // return milestones inline on the project via includeMilestones — this is the
+    // explicit list op for callers that need it on its own.
+    async listMilestones(projectId) {
+      return callTool(need('milestoneList'), { project: projectId })
+    },
+    // `save_milestone` requires the owning `project`; upserts on `id`.
     async createMilestone(projectId, milestone) {
-      return callTool(need('milestoneCreate'), { projectId, ...milestone })
+      return callTool(need('milestoneCreate'), { project: projectId, ...milestone })
+    },
+    async updateMilestone(projectId, id, updates) {
+      return callTool(need('milestoneUpdate'), { project: projectId, id, ...updates })
+    },
+    // Issues (tasks). List the project's issues (pull read side); `save_issue`
+    // upserts on `id`, attached to the project (and optionally a milestone).
+    async listIssues(projectId) {
+      return callTool(need('issueList'), { project: projectId })
+    },
+    async createIssue(projectId, issue) {
+      return callTool(need('issueCreate'), { project: projectId, ...issue })
     },
-    async updateMilestone(id, updates) {
-      return callTool(need('milestoneUpdate'), { id, ...updates })
+    async updateIssue(id, updates) {
+      return callTool(need('issueUpdate'), { id, ...updates })
     },
   }
 }