@skitterbyte/skitterspec-linear 3.1.0 → 4.0.0

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

@@ -82,6 +82,25 @@ function parseSections(body) {
   return { title, sections }
 }
 
+// Canonicalise markdown so semantically-equal content hashes equal across the
+// boundary. Linear reserializes markdown on save (authored `-` bullets come back
+// as `*`, trailing whitespace trimmed, blank runs collapsed), so without this a
+// clean push→pull would report `description` as perpetually changed. Applied to
+// the description on BOTH sides. Conservative: only unifies list markers and
+// whitespace — the transforms actually observed from Linear.
+function canonicalizeMarkdown(text) {
+  if (text == null) return text
+  return String(text)
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    // Unordered-list marker at line start (`*`/`+`/`-`) → `-`. Requires a space
+    // after the marker so bold/emphasis (`**Goal:**`) is untouched.
+    .map((line) => line.replace(/^(\s*)[*+-]( +)/, '$1-$2').replace(/[ \t]+$/, ''))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
 // Canonical milestone status from the phase-index emoji.
 const EMOJI_STATUS = { '⬜': 'not-started', '🔄': 'in-progress', '✅': 'done' }
 
@@ -102,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 {
@@ -115,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,
+      }
     })
 }
 
@@ -151,16 +208,18 @@ 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)) {
     if (skip.has(heading)) continue
     parts.push(`## ${heading}\n\n${content}`.trim())
   }
-  return parts.join('\n\n').trim() || null
+  return canonicalizeMarkdown(parts.join('\n\n')) || null
 }
 
 /**
@@ -168,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 })),
@@ -208,31 +282,82 @@ function canonicalRemoteStatus(state) {
   return s
 }
 
+// The real Linear projection carries the project's workflow state in `status`
+// (an object `{ name, type }`); accept a bare string / legacy `state` too.
+function remoteStateName(project) {
+  const st = project.status != null ? project.status : project.state
+  if (st == null) return null
+  if (typeof st === 'object') return st.name != null ? st.name : st.type != null ? st.type : null
+  return st
+}
+
+// Real Linear priority is an object `{ value, name }`; accept a bare number too.
+function remotePriority(priority) {
+  if (priority == null) return null
+  if (typeof priority === 'object') return priority.value != null ? priority.value : null
+  return priority
+}
+
+// Real Linear labels are `[{ id, name }]`; accept bare strings too.
+function remoteLabels(labels) {
+  if (!Array.isArray(labels)) return []
+  return labels
+    .map((l) => (typeof l === 'string' ? l : l && l.name != null ? l.name : null))
+    .filter((n) => n != null)
+}
+
+// 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 || {}
   const milestones = Array.isArray(p.milestones) ? p.milestones : []
+  const stateName = remoteStateName(p)
   const extracted = {
-    description: p.description != null ? p.description : null,
+    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: canonicalRemoteStatus(m.status != null ? m.status : m.state),
+      // 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 : [],
     })),
-    workflowState: p.state != null ? bucketForState(p.state, config) : null,
-    priority: p.priority != null ? p.priority : null,
-    labels: Array.isArray(p.labels) ? p.labels : [],
+    workflowState: stateName != null ? bucketForState(stateName, config) : null,
+    priority: remotePriority(p.priority),
+    labels: remoteLabels(p.labels),
   }
   return toFieldSet(extracted, config)
 }
@@ -244,6 +369,8 @@ 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

@@ -28,16 +28,22 @@ async function push({ dir, snapshotDir, identifier, projectId, adapter, config,
   }
   const remote = normalizeRemote(remoteRaw, config)
   const base = readBase(dir, identifier, config)
-  const baseStamp = base && base.__meta ? base.__meta.updatedAt : null
   const fields = classify(local, remote, base, config)
 
-  // Remote moved past base if the classifier sees remote-side divergence OR the
-  // recorded updatedAt no longer matches (a change we can't even see as a field).
+  // 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.
+  // 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.raw === 'remote-only' || f.raw === 'conflict')
+    .filter((f) => !f.keyed && f.ownership === 'both' && (f.raw === 'remote-only' || f.raw === 'conflict'))
     .map((f) => f.field)
-  const stampMoved = baseStamp != null && remoteRaw.updatedAt !== baseStamp
-  const moved = remoteDivergedFields.length > 0 || stampMoved
+  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) {
     return {
@@ -52,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' }
   }
 
@@ -76,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
@@ -95,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,