@skitterbyte/skitterspec-linear 3.4.0 → 4.0.0

package/README.md

@@ -39,14 +39,15 @@ behaves exactly like the base.
 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 today:** the whole spec body travels as the Linear Project
+**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. A per-**Milestone** /
-per-**Issue** round-trip (phases and tasks as first-class Linear objects) is a
-planned extension — see `linear.config.md`. **Base sidecars**
-(`specs/.core/linear-base/`) are committed; **backups**
+`--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

package/assets/core/SETUP.md

@@ -124,11 +124,17 @@ in-repo → `/spec-push` (send content up).
 | `priority` | Linear | pull only |
 | `labels` | Linear | pull only |
 
-The **entire spec body travels as the project `description`** — phases and
-acceptance criteria included. A separate per-milestone / per-issue round-trip
-(editing an individual phase in Linear and pulling just that back) is **not yet
-implemented**; opt in later by adding `milestones`/`phaseBodies`/`taskBreakdown`
-to `sync.fieldOwnership` once that write path exists.
+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

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

@@ -30,6 +30,7 @@
       "priority": "pull",
       "labels": "pull"
     },
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
+    "localOnlySections": ["State log", "Changelog", "Open questions"],
+    "keyedFields": {}
   }
 }

package/assets/core/linear.config.md

@@ -92,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-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.4.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

@@ -63,6 +63,11 @@ const DEFAULT_CONFIG = Object.freeze({
       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({}),
   }),
 })
 
@@ -83,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 },
     },
   }
 }
@@ -115,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.
@@ -152,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

@@ -102,6 +102,12 @@ function makeAdapter(callTool, resolved) {
     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'), { project: projectId, ...milestone })
@@ -109,6 +115,17 @@ function makeAdapter(callTool, resolved) {
     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 updateIssue(id, updates) {
+      return callTool(need('issueUpdate'), { id, ...updates })
+    },
   }
 }
 

package/src/vendor/sync-core/src/compare.js

@@ -52,6 +52,94 @@ function rawStatus(localH, remoteH, baseH) {
   return 'conflict'
 }
 
+// --- keyed collections (per-item three-way) --------------------------------
+
+// Index an array of items by their `idKey` value (stringified). Non-arrays and
+// items missing the id are skipped — they can't participate in a keyed merge.
+function indexById(arr, idKey) {
+  const map = new Map()
+  if (Array.isArray(arr)) {
+    for (const item of arr) {
+      if (item && typeof item === 'object' && item[idKey] != null) {
+        map.set(String(item[idKey]), item)
+      }
+    }
+  }
+  return map
+}
+
+// Signature of an item under a given id: its content hash with the id stripped
+// (so an id-only change / reorder is not a content edit), or 'ABSENT' when the
+// id isn't present on that side. 'ABSENT' never collides with a hex hash.
+function itemSignature(map, id, idKey) {
+  if (!map.has(id)) return 'ABSENT'
+  const { [idKey]: _omit, ...content } = map.get(id)
+  return hashField(content)
+}
+
+// Raw per-item three-way: which side moved off base, and how (added/edited/
+// removed). Mirrors rawStatus but tracks presence so add vs edit vs remove is
+// distinguishable.
+function itemRaw(localSig, remoteSig, baseSig) {
+  const localChanged = localSig !== baseSig
+  const remoteChanged = remoteSig !== baseSig
+  if (!localChanged && !remoteChanged) return { raw: 'unchanged', side: null }
+  const kind = (sig, base) => (base === 'ABSENT' ? 'added' : sig === 'ABSENT' ? 'removed' : 'edited')
+  if (localChanged && !remoteChanged) return { raw: kind(localSig, baseSig), side: 'local' }
+  if (!localChanged && remoteChanged) return { raw: kind(remoteSig, baseSig), side: 'remote' }
+  if (localSig === remoteSig) return { raw: 'unchanged', side: null } // both converged
+  return { raw: 'conflict', side: null }
+}
+
+// Collapse a raw per-item outcome through ownership into an effective status +
+// push/pull flags. Removals are report-only in v1 (surfaced, never auto-applied).
+function collapseItem({ raw, side }, ownership) {
+  const canPush = ownership === 'both' || ownership === 'push'
+  const canPull = ownership === 'both' || ownership === 'pull'
+  if (raw === 'unchanged') return { status: 'unchanged', side: null, pushable: false, pullable: false, report: false }
+  if (raw === 'removed') return { status: 'removed', side, pushable: false, pullable: false, report: true }
+  if (raw === 'conflict') {
+    if (ownership === 'push') return { status: 'edited', side: 'local', pushable: true, pullable: false, report: false }
+    if (ownership === 'pull') return { status: 'edited', side: 'remote', pushable: false, pullable: true, report: false }
+    return { status: 'conflict', side: null, pushable: true, pullable: true, report: false }
+  }
+  // added / edited
+  if (side === 'local') return { status: raw, side, pushable: canPush, pullable: false, report: false }
+  return { status: raw, side, pushable: false, pullable: canPull, report: false }
+}
+
+/**
+ * Classify a keyed collection field item-by-item. Returns one entry per id seen
+ * across local/remote/base, each with its effective status and push/pull flags,
+ * plus the local/remote item values so a caller can apply the change.
+ */
+function classifyItems(local, remote, base, ownership, idKey) {
+  const lMap = indexById(local, idKey)
+  const rMap = indexById(remote, idKey)
+  const bMap = indexById(base, idKey)
+  const ids = new Set([...lMap.keys(), ...rMap.keys(), ...bMap.keys()])
+  const items = []
+  for (const id of ids) {
+    const raw = itemRaw(
+      itemSignature(lMap, id, idKey),
+      itemSignature(rMap, id, idKey),
+      itemSignature(bMap, id, idKey),
+    )
+    const c = collapseItem(raw, ownership)
+    items.push({
+      id,
+      status: c.status,
+      side: c.side,
+      pushable: c.pushable,
+      pullable: c.pullable,
+      report: c.report,
+      local: lMap.get(id) || null,
+      remote: rMap.get(id) || null,
+    })
+  }
+  return items
+}
+
 // Collapse the raw status through ownership into an effective status + flags.
 function collapse(raw, ownership) {
   const canPush = ownership === 'both' || ownership === 'push'
@@ -78,9 +166,36 @@ function collapse(raw, ownership) {
  */
 function classify(local, remote, base, config) {
   const ownership = config.sync.fieldOwnership
+  const keyed = (config.sync && config.sync.keyedFields) || {}
   const baseObj = base || {}
   return Object.keys(ownership).map((field) => {
     const own = ownership[field]
+    const idKey = keyed[field]
+
+    // Keyed collection: per-item three-way. Field-level flags aggregate the
+    // items so existing summary code still sees "does this field have work?".
+    if (idKey) {
+      const items = classifyItems(
+        local ? local[field] : null,
+        remote ? remote[field] : null,
+        field in baseObj ? baseObj[field] : null,
+        own,
+        idKey,
+      )
+      const active = items.filter((i) => i.status !== 'unchanged')
+      return {
+        field,
+        ownership: own,
+        keyed: true,
+        idKey,
+        items,
+        status: active.length ? 'items-changed' : 'unchanged',
+        pushable: items.some((i) => i.pushable),
+        pullable: items.some((i) => i.pullable),
+      }
+    }
+
+    // Scalar / whole-field (behaviour unchanged).
     const localH = hashField(local ? local[field] : null)
     const remoteH = hashField(remote ? remote[field] : null)
     const baseH = hashField(field in baseObj ? baseObj[field] : null)
@@ -92,6 +207,7 @@ function classify(local, remote, base, config) {
 
 module.exports = {
   classify,
+  classifyItems,
   hashField,
   stableStringify,
   rawStatus,

package/src/vendor/sync-core/src/normalize.js

@@ -121,7 +121,37 @@ function parsePhaseIndex(phasesSection) {
   return rows
 }
 
-// Read the phase files (01-*.md, 02-*.md …) in execution order.
+// The phase's descriptive title: the h1 with the "Phase N — " prefix and any
+// trailing status emoji stripped (so it matches its Linear Milestone name).
+function phaseTitle(body) {
+  const h1 = /^#\s+(.*)$/m.exec(body)
+  if (!h1) return null
+  const t = h1[1]
+    .replace(/\s*[⬜🔄✅]\s*$/u, '')
+    .replace(/^Phase\s+\d+\s*[—–-]\s*/i, '')
+    .trim()
+  return t || null
+}
+
+// Parse a task line (already stripped of its leading "- ") into a keyed item:
+// its checkbox state, its text, and the inline Linear issue identifier if present
+// (`… (SKI-123)`). Returns null for a non-task line.
+function parseTaskLine(line) {
+  const m = /^\[([ xX])\]\s*(.*)$/.exec(line)
+  if (!m) return null
+  const done = m[1].toLowerCase() === 'x'
+  let text = m[2].trim()
+  let id = null
+  const idm = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/.exec(text)
+  if (idm) {
+    id = idm[1]
+    text = text.slice(0, idm.index).trim()
+  }
+  return { id, text, done }
+}
+
+// Read the phase files (01-*.md, 02-*.md …) in execution order. Each yields its
+// linked milestone id (from optional frontmatter), title, goal and tasks.
 function readPhaseFiles(snapshotDir) {
   let entries
   try {
@@ -134,11 +164,19 @@ function readPhaseFiles(snapshotDir) {
     .sort()
     .map((file) => {
       const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
-      const goal = (/^\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/m.exec(raw) || [])[1] || ''
-      const tasks = (raw.match(/^-\s*\[[ x]\]\s*.*$/gm) || []).map((t) =>
+      const { data, body } = parseFrontmatter(raw)
+      const goal = (/^\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/m.exec(body) || [])[1] || ''
+      const tasks = (body.match(/^-\s*\[[ x]\]\s*.*$/gm) || []).map((t) =>
         t.replace(/^-\s*/, '').trim(),
       )
-      return { phase: file.replace(/\.md$/, ''), goal: goal.trim(), tasks }
+      return {
+        phase: file.replace(/\.md$/, ''),
+        file,
+        id: data.linear_milestone_id != null ? String(data.linear_milestone_id) : null,
+        name: phaseTitle(body),
+        goal: goal.trim(),
+        tasks,
+      }
     })
 }
 
@@ -170,9 +208,11 @@ function readSnapshot(snapshotDir, config) {
 }
 
 // Build the pushed description: the overview prose with local-only sections
-// removed. Keeps the title line for context.
-function buildDescription(title, sections, localOnlySections) {
-  const skip = new Set(localOnlySections || [])
+// removed. Keeps the title line for context. `extraSkip` drops additional
+// sections (e.g. "Phases" once milestones sync as first-class Linear objects, so
+// the phase list isn't duplicated in the description — Decision 5).
+function buildDescription(title, sections, localOnlySections, extraSkip = []) {
+  const skip = new Set([...(localOnlySections || []), ...extraSkip])
   const parts = []
   if (title) parts.push(`# ${title}`)
   for (const [heading, content] of Object.entries(sections)) {
@@ -187,9 +227,24 @@ function buildDescription(title, sections, localOnlySections) {
  */
 function normalizeLocal(snapshotDir, config) {
   const { frontmatter, title, sections, phases } = readSnapshot(snapshotDir, config)
+  const milestonesKeyed = !!(config.sync.keyedFields && config.sync.keyedFields.milestones)
   const extracted = {
-    description: buildDescription(title, sections, config.sync.localOnlySections),
-    milestones: parsePhaseIndex(sections.Phases),
+    description: buildDescription(
+      title,
+      sections,
+      config.sync.localOnlySections,
+      milestonesKeyed ? ['Phases'] : [],
+    ),
+    // Keyed milestone items: a phase's linked milestone id (or null when
+    // unlinked), its title and goal. Unlinked phases carry id:null and are
+    // skipped by the keyed compare until they're linked.
+    milestones: phases
+      .filter((p) => p.name)
+      .map((p) => ({ id: p.id, name: p.name, goal: p.goal })),
+    // Keyed task items across all phases: inline issue id (or null), text, done.
+    // Deliberately just {id,text,done} so it hashes equal to a remote issue — the
+    // owning phase is recovered at push time by locating the task line.
+    tasks: phases.flatMap((p) => p.tasks.map(parseTaskLine).filter(Boolean)),
     phaseBodies: phases.map((p) => ({ phase: p.phase, goal: p.goal })),
     acceptanceCriteria: sections['Acceptance criteria'] || null,
     taskBreakdown: phases.map((p) => ({ phase: p.phase, tasks: p.tasks })),
@@ -251,25 +306,19 @@ function remoteLabels(labels) {
     .filter((n) => n != null)
 }
 
-// A real Linear milestone has no workflow state — only `progress` ("0%".."100%").
-// Fall back to a legacy `status`/`state` when present (fixtures / older shapes).
-function remoteMilestoneStatus(m) {
-  if (m.status != null) return canonicalRemoteStatus(m.status)
-  if (m.state != null) return canonicalRemoteStatus(m.state)
-  if (m.progress != null) {
-    const pct = parseInt(String(m.progress), 10)
-    if (Number.isFinite(pct)) {
-      if (pct >= 100) return 'done'
-      if (pct > 0) return 'in-progress'
-    }
-    return 'not-started'
-  }
-  return 'not-started'
+// Whether a remote Linear issue is complete. The real MCP shape is a flat
+// `statusType` ("completed") — accept the legacy `state.type` and `completedAt`
+// / bare `done` too (fixtures, older shapes).
+function remoteIssueDone(iss) {
+  if (iss.done === true) return true
+  const type = iss.statusType != null ? iss.statusType : iss.state && iss.state.type
+  if (type != null) return String(type).toLowerCase() === 'completed'
+  return iss.completedAt != null
 }
 
 /**
- * Normalize a remote Project projection (from the Phase 2 MCP adapter, or a
- * fixture) into the same field set as `normalizeLocal`.
+ * Normalize a remote Project projection (from the MCP adapter, or a fixture)
+ * into the same field set as `normalizeLocal`.
  */
 function normalizeRemote(project, config) {
   const p = project || {}
@@ -277,15 +326,31 @@ function normalizeRemote(project, config) {
   const stateName = remoteStateName(p)
   const extracted = {
     description: p.description != null ? canonicalizeMarkdown(p.description) : null,
+    // Keyed milestone items mirroring normalizeLocal: id, title, goal (the Linear
+    // milestone's description). Progress is Linear-derived and not synced.
     milestones: milestones.map((m) => ({
+      id: m.id != null ? String(m.id) : null,
       name: m.name,
-      status: remoteMilestoneStatus(m),
+      // A milestone's description mirrors the phase's `**Goal:**` line; strip the
+      // label so it hashes equal to the local goal (which readPhaseFiles already
+      // captures without it).
+      goal: (m.description != null ? m.description : '')
+        .replace(/^\s*\*\*Goal:\*\*\s*/, '')
+        .trim(),
     })),
     phaseBodies: milestones.map((m) => ({
       phase: m.name,
       goal: (m.description != null ? m.description : '').trim(),
     })),
     acceptanceCriteria: p.acceptanceCriteria != null ? p.acceptanceCriteria : null,
+    // Keyed task items from the project's issues: keyed by the human identifier
+    // (SKI-123, what the inline task-line id carries — the Linear MCP returns it as
+    // the issue's `id`), text ← title, done ← a completed-type workflow state.
+    tasks: (Array.isArray(p.issues) ? p.issues : []).map((iss) => ({
+      id: iss.identifier != null ? String(iss.identifier) : iss.id != null ? String(iss.id) : null,
+      text: iss.title != null ? iss.title : '',
+      done: remoteIssueDone(iss),
+    })),
     taskBreakdown: milestones.map((m) => ({
       phase: m.name,
       tasks: Array.isArray(m.tasks) ? m.tasks : [],
@@ -304,6 +369,7 @@ module.exports = {
   parseFrontmatter,
   parseSections,
   parsePhaseIndex,
+  parseTaskLine,
   canonicalRemoteStatus,
   canonicalizeMarkdown,
   bucketForState,

package/src/vendor/sync-core/src/pull.js

@@ -18,9 +18,23 @@
 const { normalizeLocal, normalizeRemote } = require('./normalize.js')
 const { classify } = require('./compare.js')
 const { readBase, writeBase, backup } = require('./base.js')
-const { writeFrontmatter } = require('./write.js')
+const { writeFrontmatter, applyMilestonesPull, applyTasksPull } = require('./write.js')
 const { frontmatterPatchFor } = require('./apply.js')
 
+// Collect the conflicting units across scalar (field-level) and keyed
+// (item-level) fields, as stable labels for the refusal message.
+function collectConflicts(fields) {
+  const out = []
+  for (const f of fields) {
+    if (f.keyed) {
+      for (const it of f.items) if (it.status === 'conflict') out.push(`${f.field}#${it.id}`)
+    } else if (f.status === 'conflict') {
+      out.push(f.field)
+    }
+  }
+  return out
+}
+
 async function pull({ dir, snapshotDir, identifier, projectId, adapter, config, force = false, timestamp }) {
   const local = normalizeLocal(snapshotDir, config)
   const remoteRaw = await adapter.readProject(projectId)
@@ -31,40 +45,54 @@ async function pull({ dir, snapshotDir, identifier, projectId, adapter, config,
   const base = readBase(dir, identifier, config)
   const fields = classify(local, remote, base, config)
 
-  const conflicts = fields.filter((f) => f.status === 'conflict').map((f) => f.field)
+  const conflicts = collectConflicts(fields)
   if (conflicts.length && !force) {
     return {
       ok: false,
       blocked: true,
       reason: 'conflict',
       conflicts,
-      message: `pull refused — ${conflicts.length} field(s) changed on both sides: ` +
+      message: `pull refused — ${conflicts.length} unit(s) changed on both sides: ` +
         `${conflicts.join(', ')}. Resolve locally or re-run with --force (remote wins).`,
     }
   }
 
-  // Everything remote wants to write down: remote-only fields, plus (under force)
-  // both-conflict fields where remote wins.
-  const pullFields = fields.filter((f) => f.pullable)
-  const fieldValues = {}
-  for (const f of pullFields) fieldValues[f.field] = remote[f.field]
-
-  const { patch, applied, deferred } = frontmatterPatchFor(fieldValues, config)
-
   // --force overwrites local edits — back the local side up first.
   let backupPath = null
   if (force) {
     backupPath = backup('local', dir, identifier, config, { timestamp, data: local })
   }
 
-  // Apply frontmatter-mapped fields + stamp the sync.
+  // Keyed body fields (e.g. milestones) — apply per-item via the denormalizer,
+  // which writes/creates the matching phase files. Removals are report-only.
+  const keyedApplied = []
+  const keyedCreated = []
+  const keyedReported = []
+  for (const f of fields) {
+    if (!f.keyed) continue
+    const apply = f.field === 'tasks' ? applyTasksPull : applyMilestonesPull
+    const res = apply(snapshotDir, f.items)
+    if (res.applied.length || res.created.length) keyedApplied.push(f.field)
+    keyedCreated.push(...res.created)
+    keyedReported.push(...res.reported.map((id) => `${f.field}#${id}`))
+  }
+
+  // Scalar pull-owned fields → frontmatter (keyed fields handled above).
+  const scalarPull = fields.filter((f) => f.pullable && !f.keyed)
+  const fieldValues = {}
+  for (const f of scalarPull) fieldValues[f.field] = remote[f.field]
+  const { patch, applied, deferred } = frontmatterPatchFor(fieldValues, config)
+
   if (applied.length || timestamp) {
     writeFrontmatter(snapshotDir, config, { ...patch, last_synced_at: timestamp })
   }
 
-  // Advance base only for reconciled fields; deferred (body) fields keep the
-  // local value as base so the remote edit stays pending, not marked synced.
-  const newBase = { ...local }
+  // Re-normalize local so the base reflects the phase-file writes we just made,
+  // then advance base: scalar-applied fields take the remote value; keyed fields
+  // take the (now-updated) local value so applied items read in-sync and any
+  // report-only removal stays pending.
+  const newLocal = normalizeLocal(snapshotDir, config)
+  const newBase = { ...newLocal }
   for (const field of applied) newBase[field] = remote[field]
   newBase.__meta = { updatedAt: remoteRaw.updatedAt || null, syncedAt: timestamp }
   const basePath = writeBase(dir, identifier, config, newBase)
@@ -74,10 +102,13 @@ async function pull({ dir, snapshotDir, identifier, projectId, adapter, config,
     blocked: false,
     applied,
     deferred,
+    keyedApplied,
+    keyedCreated,
+    keyedReported,
     conflictsForced: force ? conflicts : [],
     backupPath,
     basePath,
-    pulled: pullFields.map((f) => f.field),
+    pulled: [...scalarPull.map((f) => f.field), ...keyedApplied],
   }
 }
 

package/src/vendor/sync-core/src/push.js

@@ -32,13 +32,17 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
 
   // Remote moved past base only if a *co-authored* (`both`) field diverged on the
   // remote side — that's the case the repo can't safely overwrite without a pull.
-  // A `pull`-owned change (status/priority/labels) is Linear's to own and must
-  // NOT block a content push, and a bare `updatedAt` bump (which any Linear edit
-  // produces) is too coarse to gate on — the pre-write re-read below still catches
-  // a racer that lands during the push itself.
+  // For a keyed field the equivalent is a same-item conflict (independent edits to
+  // different items don't collide, so they don't block). A `pull`-owned change
+  // (status/priority/labels) is Linear's to own and must NOT block a content push,
+  // and a bare `updatedAt` bump is too coarse to gate on — the pre-write re-read
+  // below still catches a racer that lands during the push itself.
   const remoteDivergedFields = fields
-    .filter((f) => f.ownership === 'both' && (f.raw === 'remote-only' || f.raw === 'conflict'))
+    .filter((f) => !f.keyed && f.ownership === 'both' && (f.raw === 'remote-only' || f.raw === 'conflict'))
     .map((f) => f.field)
+  for (const f of fields) {
+    if (f.keyed) for (const it of f.items) if (it.status === 'conflict') remoteDivergedFields.push(`${f.field}#${it.id}`)
+  }
   const moved = remoteDivergedFields.length > 0
 
   if (moved && !force) {
@@ -54,8 +58,37 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
     }
   }
 
-  const pushFields = fields.filter((f) => f.pushable)
-  if (!pushFields.length && !force) {
+  // Scalar push goes through the project adapter here. Keyed body fields
+  // (milestones) can't be written by the offline engine — the provider skill does
+  // the MCP create/update and stamps new ids — so the engine emits a *plan* the
+  // skill applies. The base still advances to local (below): a created milestone's
+  // id:null item is skipped by the keyed compare until the skill stamps it, then
+  // it converges on the next sync, so no special base handling is needed.
+  const pushFields = fields.filter((f) => f.pushable && !f.keyed)
+  // A per-field create/update plan for each keyed collection. The item content
+  // (minus its id) is exactly what the skill sends to the Linear save tool.
+  const keyedPush = {}
+  for (const f of fields) {
+    if (!f.keyed) continue
+    const strip = (obj) => {
+      const { [f.idKey]: _omit, ...rest } = obj
+      return rest
+    }
+    const plan = { create: [], update: [] }
+    // Edits to already-linked items (matched by id) → update.
+    for (const it of f.items) {
+      if (!it.pushable || !it.local) continue
+      if (it.status !== 'added') plan.update.push({ id: it.id, ...strip(it.local) })
+    }
+    // Unlinked local items (no id yet) are new content to create; the keyed
+    // compare skips them (nothing to key on), so collect them straight from local.
+    const localItems = Array.isArray(local[f.field]) ? local[f.field] : []
+    for (const li of localItems) if (li && li[f.idKey] == null) plan.create.push(strip(li))
+    if (plan.create.length || plan.update.length) keyedPush[f.field] = plan
+  }
+  const hasKeyedPush = Object.keys(keyedPush).length > 0
+
+  if (!pushFields.length && !hasKeyedPush && !force) {
     return { ok: true, blocked: false, written: [], skipped: [], note: 'nothing to push' }
   }
 
@@ -78,7 +111,9 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
 
   const updates = {}
   for (const f of pushFields) updates[f.field] = local[f.field]
-  const updated = (await adapter.updateProject(projectId, updates)) || remoteRaw2 || remoteRaw
+  const updated = Object.keys(updates).length
+    ? (await adapter.updateProject(projectId, updates)) || remoteRaw2 || remoteRaw
+    : remoteRaw2 || remoteRaw
   const updatedRemote = normalizeRemote(updated, config)
 
   // Reconciled base: local is the source of truth for the fields we pushed (and
@@ -97,8 +132,12 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
     ok: true,
     blocked: false,
     written: pushFields.map((f) => f.field),
+    // The skill applies these Linear writes (create → stamp the new id back into
+    // the phase file / task line; update → save by id). Omitted when empty.
+    ...(keyedPush.milestones ? { milestonesPush: keyedPush.milestones } : {}),
+    ...(keyedPush.tasks ? { issuesPush: keyedPush.tasks } : {}),
     skipped: fields
-      .filter((f) => !f.pushable && f.status !== 'unchanged')
+      .filter((f) => !f.pushable && !f.keyed && f.status !== 'unchanged')
       .map((f) => f.field),
     backupPath,
     basePath,

package/src/vendor/sync-core/src/write.js

@@ -79,8 +79,255 @@ function writeFrontmatter(snapshotDir, config, patch) {
   return Object.keys(clean)
 }
 
+// --- phase-file denormalizer (keyed milestone pull) ------------------------
+//
+// Writes pulled milestone edits back into the *body* — the phase files — which
+// the frontmatter writer above never touches. An edit updates the matching phase
+// file (by its linear_milestone_id) in place, leaving everything else
+// byte-untouched; a Linear-only milestone becomes a new phase file. Removals are
+// never applied here (report-only, Decision 7).
+
+// Phase files in a snapshot dir (01-*.md …), execution order.
+function listPhaseFiles(snapshotDir) {
+  try {
+    return fs
+      .readdirSync(snapshotDir)
+      .filter((f) => /^\d\d-.*\.md$/.test(f) && !f.startsWith('00-'))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+// The linear_milestone_id recorded in a phase file's frontmatter, or null.
+function phaseMilestoneId(raw) {
+  const { fmLines } = splitFrontmatter(raw)
+  for (const line of fmLines) {
+    const m = /^linear_milestone_id:\s*(.*)$/.exec(line)
+    if (m) return m[1].trim().replace(/^["']|["']$/g, '') || null
+  }
+  return null
+}
+
+// Find the phase file linked to a milestone id, or null.
+function findPhaseFileByMilestoneId(snapshotDir, id) {
+  const want = String(id)
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+    if (phaseMilestoneId(raw) === want) return file
+  }
+  return null
+}
+
+// Find the phase file whose h1 title matches `name` (used to link a freshly
+// created milestone back to the phase it came from, before it has an id).
+function findPhaseFileByTitle(snapshotDir, name) {
+  const want = String(name).trim()
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const raw = fs.readFileSync(path.join(snapshotDir, file), 'utf-8')
+    const h1 = /^#\s+(.*)$/m.exec(splitFrontmatter(raw).body)
+    if (!h1) continue
+    const title = h1[1]
+      .replace(/\s*[⬜🔄✅]\s*$/u, '')
+      .replace(/^Phase\s+\d+\s*[—–-]\s*/i, '')
+      .trim()
+    if (title === want) return file
+  }
+  return null
+}
+
+// Update a phase file's title (h1, preserving the "Phase N — " prefix + status
+// emoji) and its `**Goal:**` line, leaving everything else untouched.
+function writeMilestoneFields(snapshotDir, file, { name, goal }) {
+  const p = path.join(snapshotDir, file)
+  let raw = fs.readFileSync(p, 'utf-8')
+  if (name != null) {
+    raw = raw.replace(/^(#[ \t]+)(.*)$/m, (_full, hash, rest) => {
+      const pm = /^(Phase\s+\d+\s*[—–-]\s*)(.*?)(\s*[⬜🔄✅])?\s*$/.exec(rest)
+      return pm ? `${hash}${pm[1]}${name}${pm[3] || ''}` : `${hash}${name}`
+    })
+  }
+  if (goal != null && /^\*\*Goal:\*\*/m.test(raw)) {
+    raw = raw.replace(/^(\*\*Goal:\*\*[ \t]*).*$/m, `$1${goal}`)
+  }
+  fs.writeFileSync(p, raw, 'utf-8')
+}
+
+// Add/update linear_milestone_id in a phase file's frontmatter (in place).
+function stampMilestoneId(snapshotDir, file, id) {
+  const p = path.join(snapshotDir, file)
+  const raw = fs.readFileSync(p, 'utf-8')
+  const { fmLines, body, had } = splitFrontmatter(raw)
+  const patched = patchFrontmatterLines(fmLines, { linear_milestone_id: String(id) })
+  const fm = `---\n${patched.join('\n')}\n---\n`
+  fs.writeFileSync(p, had ? fm + body : fm + '\n' + raw, 'utf-8')
+}
+
+const slugify = (name) =>
+  String(name || 'phase')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'phase'
+
+// Next phase number (max existing + 1).
+function nextPhaseNumber(snapshotDir) {
+  const nums = listPhaseFiles(snapshotDir)
+    .map((f) => parseInt(f.slice(0, 2), 10))
+    .filter(Number.isFinite)
+  return nums.length ? Math.max(...nums) + 1 : 1
+}
+
+// Create a new phase file for a Linear-only milestone. Returns the filename.
+function createPhaseFileForMilestone(snapshotDir, { id, name, goal }) {
+  const n = nextPhaseNumber(snapshotDir)
+  const file = `${String(n).padStart(2, '0')}-${slugify(name)}.md`
+  const content =
+    `---\nlinear_milestone_id: ${JSON.stringify(String(id))}\n---\n\n` +
+    `# Phase ${n} — ${name || 'Untitled'} ⬜\n\n` +
+    `> Spec: [00-overview.md](00-overview.md) · **Status:** Not started\n\n` +
+    `**Goal:** ${goal || ''}\n\n## Tasks\n\n- [ ] (pulled from Linear — flesh out)\n`
+  fs.writeFileSync(path.join(snapshotDir, file), content, 'utf-8')
+  return file
+}
+
+/**
+ * Apply a pull's keyed milestone item outcomes to the phase files.
+ * @param items classifyItems output for the milestones field.
+ * @returns { applied:string[], created:Array<{id,file}>, reported:string[] }
+ */
+function applyMilestonesPull(snapshotDir, items) {
+  const applied = []
+  const created = []
+  const reported = []
+  for (const it of items || []) {
+    if (it.report) {
+      reported.push(it.id)
+      continue
+    }
+    if (!it.pullable || !it.remote) continue
+    if (it.status === 'added') {
+      const file = createPhaseFileForMilestone(snapshotDir, it.remote)
+      created.push({ id: it.id, file })
+    } else if (it.status === 'edited' || it.status === 'conflict') {
+      const file = findPhaseFileByMilestoneId(snapshotDir, it.id)
+      if (file) {
+        writeMilestoneFields(snapshotDir, file, it.remote)
+        applied.push(it.id)
+      }
+    }
+  }
+  return { applied, created, reported }
+}
+
+// --- task-line denormalizer (keyed issue pull) -----------------------------
+//
+// Tasks live as checkbox lines inside phase files. A pulled issue edit rewrites
+// the matching line (by its inline id) in place; a Linear-only issue appends a
+// new task line; a created issue's id is stamped inline. Removals report-only.
+
+const TASK_RE = /^(\s*)-\s*\[([ xX])\]\s*(.*)$/
+const INLINE_ID_RE = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/
+
+// Render a task line from an item.
+function taskLine(indent, { id, text, done }) {
+  return `${indent}- [${done ? 'x' : ' '}] ${text}${id ? ` (${id})` : ''}`
+}
+
+// Update the task line carrying inline id `id` (text + checkbox), in place.
+function updateTaskLine(snapshotDir, id, { text, done }) {
+  const want = String(id)
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const p = path.join(snapshotDir, file)
+    const lines = fs.readFileSync(p, 'utf-8').split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const m = TASK_RE.exec(lines[i])
+      if (!m) continue
+      const idm = INLINE_ID_RE.exec(m[3])
+      if (idm && idm[1] === want) {
+        lines[i] = taskLine(m[1], { id: want, text, done })
+        fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+        return true
+      }
+    }
+  }
+  return false
+}
+
+// Append a task line for a Linear-only issue after the last existing task line
+// (falls back to end of the last phase file). Returns the file it landed in.
+function addTaskLine(snapshotDir, item) {
+  const files = listPhaseFiles(snapshotDir)
+  const file = files[files.length - 1]
+  if (!file) return null
+  const p = path.join(snapshotDir, file)
+  const lines = fs.readFileSync(p, 'utf-8').split('\n')
+  let lastTask = -1
+  for (let i = 0; i < lines.length; i++) if (TASK_RE.test(lines[i])) lastTask = i
+  const line = taskLine('', item)
+  if (lastTask >= 0) lines.splice(lastTask + 1, 0, line)
+  else lines.push(line)
+  fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+  return file
+}
+
+// Stamp an inline id onto the (idless) task line whose text matches — used after
+// the skill creates an issue for a new local task.
+function stampIssueId(snapshotDir, text, id) {
+  const want = String(text).trim()
+  for (const file of listPhaseFiles(snapshotDir)) {
+    const p = path.join(snapshotDir, file)
+    const lines = fs.readFileSync(p, 'utf-8').split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const m = TASK_RE.exec(lines[i])
+      if (!m || INLINE_ID_RE.test(m[3])) continue
+      if (m[3].trim() === want) {
+        lines[i] = `${m[1]}- [${m[2].toLowerCase() === 'x' ? 'x' : ' '}] ${want} (${id})`
+        fs.writeFileSync(p, lines.join('\n'), 'utf-8')
+        return file
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Apply a pull's keyed task item outcomes to the phase files' task lines.
+ * @returns { applied:string[], created:Array<{id,file}>, reported:string[] }
+ */
+function applyTasksPull(snapshotDir, items) {
+  const applied = []
+  const created = []
+  const reported = []
+  for (const it of items || []) {
+    if (it.report) {
+      reported.push(it.id)
+      continue
+    }
+    if (!it.pullable || !it.remote) continue
+    if (it.status === 'added') {
+      const file = addTaskLine(snapshotDir, it.remote)
+      if (file) created.push({ id: it.id, file })
+    } else if (it.status === 'edited' || it.status === 'conflict') {
+      if (updateTaskLine(snapshotDir, it.id, it.remote)) applied.push(it.id)
+    }
+  }
+  return { applied, created, reported }
+}
+
 module.exports = {
   writeFrontmatter,
   splitFrontmatter,
   serialize,
+  listPhaseFiles,
+  findPhaseFileByMilestoneId,
+  findPhaseFileByTitle,
+  writeMilestoneFields,
+  stampMilestoneId,
+  createPhaseFileForMilestone,
+  applyMilestonesPull,
+  updateTaskLine,
+  addTaskLine,
+  stampIssueId,
+  applyTasksPull,
 }