@skitterbyte/skitterspec-linear 3.4.0 → 5.0.0

package/src/prompts.js

@@ -53,4 +53,40 @@ async function confirmRemoveReleaseTooling() {
   return Boolean(ans.remove)
 }
 
-module.exports = { promptSetup, confirmRemoveReleaseTooling }
+/**
+ * Interactive choice when `init` finds an already-set-up repo. Returns one of
+ * `leave` | `resync` | `reset`. Defaults to (and cancels to) `leave` — the safe
+ * no-op — and asks a second confirm before `reset` (destructive to managed files).
+ */
+async function promptExistingSetup() {
+  const prompts = require('prompts')
+  const { action } = await prompts(
+    {
+      type: 'select',
+      name: 'action',
+      message: 'This project already has skitterspec set up. What would you like to do?',
+      initial: 0,
+      choices: [
+        { title: 'Leave alone — make no changes', value: 'leave' },
+        { title: 'Resync — update managed files to the latest, keep my edits', value: 'resync' },
+        { title: 'Start again — reset the scaffolding (your specs & config are kept)', value: 'reset' },
+      ],
+    },
+    { onCancel: () => {} },
+  )
+  if (action === 'reset') {
+    const { confirm } = await prompts(
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Start again overwrites managed skills/rules. Your specs and config are untouched. Continue?',
+        initial: false,
+      },
+      { onCancel: () => false },
+    )
+    if (!confirm) return 'leave'
+  }
+  return action || 'leave'
+}
+
+module.exports = { promptSetup, confirmRemoveReleaseTooling, promptExistingSetup }

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],
   }
 }