@skitterbyte/skitterspec-linear 7.0.2 → 8.0.0

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

@@ -1,147 +1,53 @@
 'use strict'
 
 /**
- * `push` — repo → remote, three-way aware and ownership-respecting.
+ * `push` — repo → Linear, one-way. The repo is the source of truth; Linear is a
+ * generated mirror. We never read remote content: `push` builds the local
+ * projection, diffs it against the committed **last-pushed snapshot**, and
+ * returns a **create/update plan** the provider skill applies over MCP.
  *
- * Never writes a `pull`-owned field or a `localOnlySection` (those aren't in the
- * pushable set / the field set at all). Optimistic concurrency: if the remote has
- * moved past the base — detected both by the classifier (any remote-only/conflict
- * field) and by the recorded `updatedAt` — it aborts with "pull first" unless
- * `--force`. It also **re-reads the remote immediately before writing** to catch a
- * writer that raced in during the compare. `--force` makes local win after backing
- * up the remote side. On success it rewrites the base and stamps `last_synced_at`.
+ * The skill: applies the plan → stamps each newly-created id back into the phase
+ * frontmatter / task line → calls `recordPush`, which re-reads the (now
+ * id-stamped) projection and writes the snapshot. That closes the loop: the next
+ * `push` sees an unchanged snapshot and produces an empty plan.
  *
- * Pure orchestration over an injected `adapter` (readProject + updateProject) and
- * injected `timestamp`. Tests drive it with a fake in-memory adapter.
+ * Pure aside from reading the snapshot; no adapter, no remote read, no
+ * Date.now(). `recordPush` writes the snapshot sidecar.
  */
 
-const { normalizeLocal, normalizeRemote } = require('./normalize.js')
-const { classify } = require('./compare.js')
-const { readBase, writeBase, backup } = require('./base.js')
-const { writeFrontmatter } = require('./write.js')
+const { normalizeLocal } = require('./normalize.js')
+const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
+const { readBase, writeBase } = require('./base.js')
 
-async function push({ dir, snapshotDir, identifier, projectId, adapter, config, force = false, timestamp }) {
+// Build the one-way projection from a local snapshot: the project prose + status,
+// and the milestone/issue items. `status` is the local lifecycle bucket; the
+// skill maps it to the Linear project-state NAME via config.states at apply time.
+function projectionOf(snapshotDir, config) {
   const local = normalizeLocal(snapshotDir, config)
-  const remoteRaw = await adapter.readProject(projectId)
-  if (!remoteRaw) {
-    return { ok: false, error: `remote project not found: ${projectId}` }
-  }
-  const remote = normalizeRemote(remoteRaw, config)
-  const base = readBase(dir, identifier, config)
-  const fields = classify(local, remote, base, 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.
-  // 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.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) {
-    return {
-      ok: false,
-      blocked: true,
-      reason: 'remote-moved',
-      movedFields: remoteDivergedFields,
-      message:
-        'push refused — remote moved since the last sync' +
-        (remoteDivergedFields.length ? ` (${remoteDivergedFields.join(', ')})` : '') +
-        '. Pull first, or re-run with --force (local wins).',
-    }
-  }
-
-  // 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' }
-  }
-
-  // Optimistic concurrency: re-read immediately before writing to catch a racer.
-  const remoteRaw2 = await adapter.readProject(projectId)
-  if (remoteRaw2 && remoteRaw2.updatedAt !== remoteRaw.updatedAt && !force) {
-    return {
-      ok: false,
-      blocked: true,
-      reason: 'concurrent-write',
-      message: 'push refused — remote changed during the push. Pull first, or --force.',
-    }
-  }
-
-  // --force clobbers the remote side — back it up first.
-  let backupPath = null
-  if (force) {
-    backupPath = backup('remote', dir, identifier, config, { timestamp, data: remoteRaw2 || remoteRaw })
-  }
-
-  const updates = {}
-  for (const f of pushFields) updates[f.field] = local[f.field]
-  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
-  // for unchanged/local-only fields); pull-owned fields keep remote's value so
-  // they don't read as pending next time.
-  const newBase = { ...local }
-  for (const [field, own] of Object.entries(config.sync.fieldOwnership)) {
-    if (own === 'pull') newBase[field] = updatedRemote[field]
+  return {
+    description: local.description ?? null,
+    status: local.workflowState ?? null,
+    priority: local.priority ?? null,
+    labels: Array.isArray(local.labels) ? local.labels : [],
+    milestones: Array.isArray(local.milestones) ? local.milestones : [],
+    issues: Array.isArray(local.tasks) ? local.tasks : [],
   }
-  newBase.__meta = { updatedAt: updated.updatedAt || null, syncedAt: timestamp }
-  const basePath = writeBase(dir, identifier, config, newBase)
+}
 
-  if (timestamp) writeFrontmatter(snapshotDir, config, { last_synced_at: timestamp })
+function push({ dir, snapshotDir, identifier, config }) {
+  const projection = projectionOf(snapshotDir, config)
+  const snapshot = readBase(dir, identifier, config)
+  const plan = planChanges(projection, snapshot)
+  return { ok: true, empty: isEmptyPlan(plan), plan, projection }
+}
 
-  return {
-    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.keyed && f.status !== 'unchanged')
-      .map((f) => f.field),
-    backupPath,
-    basePath,
-  }
+/**
+ * Record the last-pushed snapshot from the CURRENT files — call after the skill
+ * has applied the plan and stamped new ids. Returns the snapshot path.
+ */
+function recordPush({ dir, snapshotDir, identifier, config }) {
+  const projection = projectionOf(snapshotDir, config)
+  return writeBase(dir, identifier, config, snapshotOf(projection))
 }
 
-module.exports = { push }
+module.exports = { push, recordPush, projectionOf }

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

@@ -15,12 +15,7 @@
  * Pure string→string (`sanitizeSpecMarkdown`); the CLI wraps it with fs walking.
  */
 
-const {
-  wrapEmphasisAware,
-  collapse,
-  inferWidth,
-  DEFAULT_WIDTH,
-} = require('./task-block.js')
+const { wrapEmphasisAware, collapseHyphenAware, inferWidth, DEFAULT_WIDTH } = require('./task-block.js')
 const { joinEmphasisAcrossBreaks } = require('./normalize.js')
 
 // A run of non-blank lines contains an emphasis straddle / mangle iff joining
@@ -30,9 +25,10 @@ function hasStraddle(text) {
 }
 
 // Turn a multi-line region into its clean single logical line: repair mangles and
-// join straddles first (needs the newlines), then collapse whitespace.
+// join straddles first (needs the newlines), then collapse whitespace — hyphen-
+// aware, so a compound wrapped at the hyphen isn't spaced out.
 function cleanLogicalLine(text) {
-  return collapse(joinEmphasisAcrossBreaks(text))
+  return collapseHyphenAware(joinEmphasisAcrossBreaks(text))
 }
 
 // A bullet line: indent, marker (`- `, `* `, `+ `, `1. `, optionally a `[ ]`/`[x]`

package/src/vendor/sync-core/src/task-block.js

@@ -26,6 +26,17 @@ function collapse(text) {
   return String(text).replace(/\s+/g, ' ').trim()
 }
 
+// Like `collapse`, but a word wrapped at a hyphen (`state-entry-with-`⏎
+// `assignment`) rejoins TIGHT — one compound — instead of gaining a space. Every
+// other break collapses to a single space. Use this wherever hand-wrapped prose
+// is flattened to one logical line, so a hard wrap at a hyphen isn't data loss.
+function collapseHyphenAware(text) {
+  return String(text)
+    .replace(/(\w-)[ \t]*\n[ \t]*(?=\w)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 // Mark every character of `body` that lies inside an inline emphasis or link
 // span — `**bold**`, `*italic*`, `[text](url)` — so wrapping can avoid breaking
 // one across a line (Linear mangles a straddling `**`/`*`/link on save). Code
@@ -84,7 +95,7 @@ function findTaskBlocks(lines) {
       end: j,
       indent: m[1],
       mark: m[2].toLowerCase() === 'x' ? 'x' : ' ',
-      text: collapse(parts.join(' ')),
+      text: collapseHyphenAware(parts.join('\n')),
     })
     i = j - 1
   }
@@ -171,6 +182,7 @@ module.exports = {
   wrapEmphasisAware,
   spanMask,
   collapse,
+  collapseHyphenAware,
   inferWidth,
   DEFAULT_WIDTH,
 }

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

@@ -1,32 +1,25 @@
 'use strict'
 
 /**
- * Local snapshot writes for pull (remote → repo).
+ * Push-side writeback: after `push` creates milestones/issues in Linear, the
+ * skill stamps each returned id back into the repo so the next push updates
+ * rather than recreates. Everything here edits the repo in place:
  *
- * Phase 2 applies **frontmatter-mapped** pulled fields — the `pull`-owned data
- * remote genuinely owns (`workflowState` → `spec_status`, `priority`, `labels`)
- * plus sync bookkeeping (`last_synced_at`, ids) — by surgically editing the YAML
- * frontmatter of `00-overview.md` and leaving the markdown body byte-for-byte
- * untouched. Existing keys are updated in place (order preserved); new keys are
- * appended; a file with no frontmatter gets one prepended.
+ *   - `stampMilestoneId(dir, file, id)` — add/update `linear_milestone_id` in a
+ *     phase file's frontmatter (locate the file with `findPhaseFileByTitle`).
+ *   - `stampIssueId(dir, text, id)` — append `(ID)` to the matching task line,
+ *     re-wrapped in the file's own style.
+ *   - `writeFrontmatter(dir, config, patch)` — patch `00-overview.md` frontmatter
+ *     (e.g. `last_synced_at`).
  *
- * Body/`both`-owned fields (`description`, `milestones`, …) are NOT written back
- * here — that denormalizer is a tracked follow-up (see the spec). Callers advance
- * the base only for fields they actually applied, so an un-applied remote edit
- * stays pending rather than being silently marked synced.
+ * No remote read, no pull writeback — the repo is the source of truth.
  */
 
 const fs = require('node:fs')
 const path = require('node:path')
-const {
-  findTaskBlocks,
-  renderTaskBlock,
-  collapse,
-  inferWidth,
-} = require('./task-block.js')
+const { findTaskBlocks, renderTaskBlock, collapse, inferWidth } = require('./task-block.js')
 
-// Serialize a JS value as a YAML-ish frontmatter scalar. null/undefined → the
-// key is dropped (caller shouldn't pass those).
+// Serialize a JS value as a YAML-ish frontmatter scalar.
 function serialize(value) {
   if (Array.isArray(value)) return JSON.stringify(value)
   if (typeof value === 'number' || typeof value === 'boolean') return String(value)
@@ -54,7 +47,6 @@ function patchFrontmatterLines(lines, patch) {
       out.push(line)
     }
   }
-  // Append any new keys not already present.
   for (const key of Object.keys(patch)) {
     if (!seen.has(key)) out.push(`${key}: ${serialize(patch[key])}`)
   }
@@ -85,14 +77,6 @@ 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 {
@@ -105,28 +89,8 @@ function listPhaseFiles(snapshotDir) {
   }
 }
 
-// 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).
+// Find the phase file whose h1 title matches `name` (used to stamp a freshly
+// created milestone's id back into the phase it came from).
 function findPhaseFileByTitle(snapshotDir, name) {
   const want = String(name).trim()
   for (const file of listPhaseFiles(snapshotDir)) {
@@ -142,23 +106,6 @@ function findPhaseFileByTitle(snapshotDir, name) {
   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)
@@ -169,111 +116,8 @@ function stampMilestoneId(snapshotDir, file, id) {
   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 (hand-wrapped) checkbox bullets inside phase files. A pulled
-// issue edit rewrites the matching bullet — whole block, re-wrapped — by its
-// inline id; a Linear-only issue appends a new bullet; a created issue's id is
-// stamped inline. Removals report-only. See task-block.js for the wrapping.
-
 const INLINE_ID_RE = /\s*\(([A-Za-z][A-Za-z0-9]*-\d+)\)\s*$/
 
-// Update the task carrying inline id `id` (text + checkbox), in place.
-//
-// Block-aware: a task bullet is hand-wrapped across several lines, so the whole
-// block is replaced and the new text re-wrapped in the file's own style. Editing
-// only the first line would strand its continuation lines as orphaned prose.
-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')
-    const width = inferWidth(lines)
-    for (const b of findTaskBlocks(lines)) {
-      const idm = INLINE_ID_RE.exec(b.text)
-      if (!idm || idm[1] !== want) continue
-      const rendered = renderTaskBlock({ indent: b.indent, done, text, id: want }, width)
-      lines.splice(b.start, b.end - b.start, ...rendered)
-      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')
-  const blocks = findTaskBlocks(lines)
-  const rendered = renderTaskBlock({ indent: '', ...item }, inferWidth(lines))
-  if (blocks.length) lines.splice(blocks[blocks.length - 1].end, 0, ...rendered)
-  else lines.push(...rendered)
-  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) {
@@ -285,10 +129,7 @@ function stampIssueId(snapshotDir, text, id) {
     for (const b of findTaskBlocks(lines)) {
       if (INLINE_ID_RE.test(b.text)) continue
       if (b.text !== want) continue
-      const rendered = renderTaskBlock(
-        { indent: b.indent, done: b.mark === 'x', text: want, id },
-        width,
-      )
+      const rendered = renderTaskBlock({ indent: b.indent, done: b.mark === 'x', text: want, id }, width)
       lines.splice(b.start, b.end - b.start, ...rendered)
       fs.writeFileSync(p, lines.join('\n'), 'utf-8')
       return file
@@ -297,43 +138,12 @@ function stampIssueId(snapshotDir, text, id) {
   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,
 }

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

@@ -1,49 +0,0 @@
----
-name: spec-pull
-description: Pull a spec's linked Linear project into the local spec (Linear → repo), three-way aware. Applies remote-only fields; refuses to clobber local edits on a conflict unless --force (which backs up the local side first). Fetches Linear over MCP and runs `skitterspec spec-sync pull`. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-pull", "pull from Linear", "sync Linear changes down", or "update this spec from Linear".
----
-
-# /spec-pull — bring Linear changes into the spec
-
-Linear → repo. Applies fields Linear changed since the last sync (status,
-priority, labels, and co-authored fields), rewrites the committed base, and
-stamps `last_synced_at`. It **refuses** to overwrite a local edit that conflicts
-with a Linear edit unless you pass `--force`.
-
-**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
-tell the user how to enable Linear sync and stop.
-
-## 1. Identify the target spec
-
-Use the argument, else the spec in context; ask if unclear.
-
-## 2. Fetch the Linear project
-
-- Read `linear_project_id` from `00-overview.md` frontmatter; if missing, the
-  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 (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
-
-```
-skitterspec spec-sync pull <spec> --remote <tempfile> [--force]
-```
-
-- **No conflict** — the engine applies remote-only fields to the local snapshot,
-  rewrites the base, and stamps the sync. Body fields with no local home yet are
-  reported as `deferred` (apply them by hand from Linear if needed).
-- **Conflict** (a co-authored field changed on both sides) — the engine
-  **refuses** and lists the fields. Relay that; do not force on the user's behalf.
-- **`--force`** — only when the user explicitly asks. Remote wins after the engine
-  backs up the local side under `sync.backupDir` (the reflog). Relay the backup
-  path.
-
-## 4. Report
-
-Relay the git-like summary (applied / deferred / conflicts / backup / base). If
-fields were applied, remind the user to review and commit the refreshed snapshot.

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

@@ -1,66 +0,0 @@
-'use strict'
-
-/**
- * Translate normalized field values into a local frontmatter patch (pull side).
- *
- * Only the `pull`-owned, frontmatter-backed fields have a local home in Phase 2:
- *   workflowState → spec_status (remote state name mapped back to the bucket),
- *   priority      → priority,
- *   labels        → labels.
- * Any other field handed in (a body field like `description`/`milestones`) has no
- * frontmatter mapping yet, so it's returned in `deferred` — the caller must NOT
- * advance its base, keeping the remote edit pending instead of falsely synced.
- */
-
-// field name → frontmatter key.
-const FRONTMATTER_FIELD = {
-  workflowState: 'spec_status',
-  priority: 'priority',
-  labels: 'labels',
-}
-
-// Invert config.states ({ bucket: "remote Name" }) → { "remote name": bucket }.
-function invertStates(config) {
-  const out = {}
-  const states = (config && config.states) || {}
-  for (const [bucket, name] of Object.entries(states)) {
-    if (typeof name === 'string') out[name.toLowerCase()] = bucket
-  }
-  return out
-}
-
-// Map a remote workflowState (a remote state name) back to a local bucket. Falls
-// back to the raw value when it isn't one of the configured states.
-function localWorkflowState(value, config) {
-  if (value == null) return null
-  const bucket = invertStates(config)[String(value).toLowerCase()]
-  return bucket || String(value)
-}
-
-/**
- * Build the frontmatter patch for a set of applied field values.
- * @param {object} fieldValues  { fieldName: value } to write locally
- * @returns {{ patch:object, applied:string[], deferred:string[] }}
- */
-function frontmatterPatchFor(fieldValues, config) {
-  const patch = {}
-  const applied = []
-  const deferred = []
-  for (const [field, value] of Object.entries(fieldValues)) {
-    const key = FRONTMATTER_FIELD[field]
-    if (!key) {
-      deferred.push(field)
-      continue
-    }
-    patch[key] = field === 'workflowState' ? localWorkflowState(value, config) : value
-    applied.push(field)
-  }
-  return { patch, applied, deferred }
-}
-
-module.exports = {
-  frontmatterPatchFor,
-  localWorkflowState,
-  invertStates,
-  FRONTMATTER_FIELD,
-}