@skitterbyte/skitterspec-linear 9.1.0 → 10.0.0

package/src/init.js

@@ -53,7 +53,7 @@ const CORE_FILES = listCoreTemplates()
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], removed: [], customized: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], removed: [], customized: [], healed: [], warnings: [] }
 
 function resetReport() {
   for (const k of Object.keys(report)) report[k].length = 0
@@ -82,6 +82,8 @@ function ensureDir(p) {
 // old version we own" (safe to update) from "a file the user edited" (keep). It
 // lists only managed FILES (skills, rules, .core templates) — never user content.
 
+const { linesDiff } = require('./lines-diff.js')
+
 const MANIFEST_FILE = path.join('specs', '.core', '.skitterspec-manifest.json')
 const MANIFEST_VERSION = 1
 
@@ -132,13 +134,24 @@ function writeManifest(dir, files) {
 
 // Classify a managed file against the manifest baseline.
 //   missing    — not on disk
-//   pristine   — on disk and matches the hash we recorded (ours to update)
-//   customized — on disk but differs (or unknown) — a user edit; keep it
-function managedState(dir, relPath, manifest) {
+//   pristine   — ours to update: it matches the package asset, or the hash we recorded
+//   customized — on disk but differs from both — a user edit; keep it
+//
+// `bundled` (the current package asset) is optional but decisive: a file whose
+// CONTENT equals what we ship is not customized, whatever the manifest says.
+// Without that check a stale hash pinned the file out of updates permanently —
+// anything that changed it out-of-band (an errant tool, a partial restore, a
+// manifest lost and re-seeded at the wrong version) froze it for good, silently.
+// Comparing content first makes the tool self-healing after any restore.
+// `pruneRetiredManaged` passes no `bundled` on purpose: the package no longer
+// ships that file, so there is nothing to compare it against.
+function managedState(dir, relPath, manifest, bundled) {
   const abs = path.join(dir, relPath)
   if (!fs.existsSync(abs)) return 'missing'
+  const onDisk = fs.readFileSync(abs, 'utf8')
+  if (bundled !== undefined && onDisk === bundled) return 'pristine'
   const known = manifest.files[relPath]
-  return known && sha1(fs.readFileSync(abs, 'utf8')) === known ? 'pristine' : 'customized'
+  return known && sha1(onDisk) === known ? 'pristine' : 'customized'
 }
 
 // Reconcile and persist the manifest after an install/resync run: keep prior
@@ -405,7 +418,7 @@ function isExistingSetup(dir) {
 // update; customized (edited) → keep + report, unless `force`.
 function resyncManagedFile(dir, target, manifest, force) {
   const { relPath, abs, bundled } = target
-  const state = managedState(dir, relPath, manifest)
+  const state = managedState(dir, relPath, manifest, bundled)
   const write = (bucket) => {
     ensureDir(path.dirname(abs))
     fs.writeFileSync(abs, bundled)
@@ -416,17 +429,25 @@ function resyncManagedFile(dir, target, manifest, force) {
   if (state === 'customized') {
     if (force) return write('updated')
     writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
-    return report.customized.push(relPath)
+    // Carry the change the user just DECLINED. A bare filename tells them a
+    // decision was made on their behalf but not what it was, which leaves
+    // "clobber and re-apply my edits by hand" as the only safe way to upgrade.
+    const { added, removed, hunks } = linesDiff(fs.readFileSync(abs, 'utf8'), bundled)
+    return report.customized.push({ relPath, added, removed, hunks })
   }
   // pristine — update only if the bundled content actually changed
   if (fs.readFileSync(abs, 'utf8') === bundled) {
+    // The file is ours and current, but the manifest disagreed — record the
+    // repair rather than healing in silence: a file that quietly starts
+    // updating again is as opaque as one that quietly stopped.
+    if (manifest.files[relPath] !== sha1(bundled)) report.healed.push(relPath)
     writtenHashes[relPath] = sha1(bundled)
     return report.skipped.push(relPath)
   }
   write('updated')
 }
 
-function resync(dir, { force = false, claudeMd = true } = {}) {
+function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   resetReport()
   const manifest = readManifest(dir)
@@ -436,7 +457,7 @@ function resync(dir, { force = false, claudeMd = true } = {}) {
   pruneRetiredManaged(dir, manifest)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
-  printReport(dir, 'resync')
+  printReport(dir, 'resync', { diff })
 }
 
 // The never-touch set: START AGAIN may only delete a known managed file, and may
@@ -502,7 +523,7 @@ function reset(dir, { claudeMd = true } = {}) {
   printReport(dir, 'reset')
 }
 
-function printReport(dir, mode) {
+function printReport(dir, mode, { diff = false } = {}) {
   const line = (label, items) => {
     if (!items.length) return
     process.stdout.write(`\n${label}:\n`)
@@ -512,12 +533,25 @@ function printReport(dir, mode) {
   line('created', report.created)
   line('updated', report.updated)
   line('removed', report.removed)
-  line('customized (kept)', report.customized)
+  line(
+    'customized (kept)',
+    report.customized.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
+  )
+  line('manifest repaired', report.healed)
   line('unchanged', report.skipped)
   if (report.warnings.length) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
   }
+  if (diff) {
+    for (const c of report.customized) {
+      if (!c.hunks.length) continue
+      process.stdout.write(`\n--- ${c.relPath} (kept — this is what you declined)\n`)
+      for (const h of c.hunks) process.stdout.write(`${h}\n`)
+    }
+  } else if (report.customized.length) {
+    process.stdout.write('\nRe-run with --diff to see the changes those files declined.\n')
+  }
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))
   const isolationNote = isolationOn
     ? 'Per-spec isolation is ON: every in-progress spec gets its own git worktree' +

package/src/lines-diff.js

@@ -0,0 +1,114 @@
+'use strict'
+
+/**
+ * A minimal line diff — just enough for `update` to say what it skipped.
+ *
+ * `update` reports a file it kept as `customized (kept)` and nothing else, so
+ * there is no way to learn WHICH upstream changes you declined without diffing
+ * against `node_modules` by hand. That is how a real behavioural change (the
+ * lifecycle skills learning to commit their own edits) went unnoticed through an
+ * upgrade in the field.
+ *
+ * Zero dependencies on purpose: this package ships with none, and `diff(1)` is
+ * not a portable guarantee. An LCS over lines is a few dozen lines of code and
+ * the inputs are markdown files of a few hundred lines.
+ */
+
+// Longest-common-subsequence walk over two line arrays, as a flat op list.
+// `t` is ' ' (context), '-' (only in `a`) or '+' (only in `b`).
+function diffOps(a, b) {
+  const n = a.length
+  const m = b.length
+  // dp[i][j] = LCS length of a[i..] and b[j..], flattened.
+  const dp = new Int32Array((n + 1) * (m + 1))
+  const at = (i, j) => i * (m + 1) + j
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[at(i, j)] = a[i] === b[j] ? dp[at(i + 1, j + 1)] + 1 : Math.max(dp[at(i + 1, j)], dp[at(i, j + 1)])
+    }
+  }
+
+  const ops = []
+  let i = 0
+  let j = 0
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ t: ' ', line: a[i], a: i, b: j })
+      i++
+      j++
+    } else if (dp[at(i + 1, j)] >= dp[at(i, j + 1)]) {
+      ops.push({ t: '-', line: a[i], a: i, b: j })
+      i++
+    } else {
+      ops.push({ t: '+', line: b[j], a: i, b: j })
+      j++
+    }
+  }
+  while (i < n) {
+    ops.push({ t: '-', line: a[i], a: i, b: j })
+    i++
+  }
+  while (j < m) {
+    ops.push({ t: '+', line: b[j], a: i, b: j })
+    j++
+  }
+  return ops
+}
+
+// Group the ops into unified-diff hunks, each carrying `context` unchanged lines
+// either side of a run of changes. Runs closer together than 2×context merge, as
+// `diff -u` does, so a cluster of edits reads as one hunk.
+function toHunks(ops, context) {
+  const changed = ops.map((o) => o.t !== ' ')
+  const hunks = []
+  let k = 0
+  while (k < ops.length) {
+    if (!changed[k]) {
+      k++
+      continue
+    }
+    let start = Math.max(0, k - context)
+    let end = k
+    // Extend while the next change is near enough to keep in the same hunk.
+    for (let p = k; p < ops.length; p++) {
+      if (changed[p]) end = p
+      else if (p - end > context * 2) break
+    }
+    end = Math.min(ops.length - 1, end + context)
+
+    const body = ops.slice(start, end + 1)
+    const aStart = body[0].a + 1
+    const bStart = body[0].b + 1
+    const aLen = body.filter((o) => o.t !== '+').length
+    const bLen = body.filter((o) => o.t !== '-').length
+    hunks.push(
+      [`@@ -${aStart},${aLen} +${bStart},${bLen} @@`, ...body.map((o) => `${o.t}${o.line}`)].join('\n'),
+    )
+    k = end + 1
+  }
+  return hunks
+}
+
+/**
+ * Diff `a` (what is on disk) against `b` (what the package ships).
+ *
+ * `added`/`removed` count the lines an update WOULD add and remove — the summary
+ * printed beside a kept file. `hunks` are unified-diff blocks for `--diff`.
+ *
+ * @param {string|string[]} a
+ * @param {string|string[]} b
+ * @param {{context?:number}} [opts]
+ * @returns {{added:number, removed:number, hunks:string[]}}
+ */
+function linesDiff(a, b, { context = 3 } = {}) {
+  const A = Array.isArray(a) ? a : String(a).split('\n')
+  const B = Array.isArray(b) ? b : String(b).split('\n')
+  const ops = diffOps(A, B)
+  return {
+    added: ops.filter((o) => o.t === '+').length,
+    removed: ops.filter((o) => o.t === '-').length,
+    hunks: toHunks(ops, context),
+  }
+}
+
+module.exports = { linesDiff }

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

@@ -10,12 +10,14 @@
  *
  *   spec-sync normalize <spec>   print the local projection (JSON)
  *   spec-sync push <spec>        print the create/update PLAN the skill applies
+ *                                (requires --workspace-states; see stateCheckFailure)
+ *   spec-sync stamp <spec>       write returned ids back into the spec files
  *   spec-sync record <spec>      write the last-pushed snapshot (after apply)
  *   spec-sync status <spec>      read-only drift report (never writes)
  *   spec-sync linked             list every spec's linear_identifier (offline)
  *
- * The `/spec-push` skill: `push` → apply the plan over MCP → stamp returned ids
- * into the repo → `record`. There is no pull — Linear is not read for content.
+ * The `/spec-push` skill: `push` → apply the plan over MCP → `stamp` the returned
+ * ids into the repo → `record`. There is no pull — Linear is not read for content.
  */
 
 const fs = require('node:fs')
@@ -34,6 +36,11 @@ const {
   isEmptyPlan,
   remoteWorkflowState,
   validateStates,
+  stateSuggestions,
+  lintPhases,
+  writeFrontmatter,
+  stampSubIssueId,
+  listPhaseFiles,
 } = require('../sync-core')
 
 const { loadLinearConfig } = require('./config.js')
@@ -131,6 +138,24 @@ function specSyncLinked(dir, config, flags, out) {
   out.write(lines.join('\n') + '\n')
 }
 
+// Phase-status warnings for a spec, one formatted line each.
+//
+// A spec states each phase's status three times — the phase file's h1 emoji, its
+// `> **Status:**` line, and the overview phase-index row — and only the h1 is
+// read. Get it wrong and the phase projects as `backlog`, pushes cleanly, and is
+// recorded as intended: invisible. So every subcommand that reads a projection
+// reports these, and none of them treats one as fatal — a legacy spec must still
+// push. See sync-core `lintPhases`.
+function warningLines(snapshotDir, config) {
+  return lintPhases(snapshotDir, config).map((w) => `  warning ${w.file}: ${w.message}`)
+}
+
+// Emit warnings on stderr, keeping stdout pure for a machine-readable payload.
+function warnToErr(snapshotDir, config, err) {
+  const lines = warningLines(snapshotDir, config)
+  if (lines.length) err.write(lines.join('\n') + '\n')
+}
+
 function resolveOrExit(specArg, dir, out) {
   if (!specArg) return null
   const snapshotDir = resolveSnapshotDir(specArg, dir)
@@ -142,26 +167,35 @@ function resolveOrExit(specArg, dir, out) {
 }
 
 // `spec-sync normalize <spec>` — print the local projection as JSON.
-function specSyncNormalize(dir, config, specArg, out) {
+function specSyncNormalize(dir, config, specArg, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
   if (!snapshotDir) return
+  // stdout is the projection and nothing else — callers pipe it into jq.
+  warnToErr(snapshotDir, config, err)
   out.write(JSON.stringify(projectionOf(snapshotDir, config), null, 2) + '\n')
 }
 
 // `spec-sync push <spec> [--json]` — print the create/update PLAN diffed against
 // the last-pushed snapshot. Machine-readable by default; the /spec-push skill
 // applies it over MCP then calls `record`.
-function specSyncPush(dir, config, specArg, flags, out) {
+function specSyncPush(dir, config, specArg, flags, out, err) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
-  if (!snapshotDir) return
+  if (!snapshotDir) return 1
+  const failure = stateCheckFailure(config, flags)
+  if (failure) {
+    out.write(failure.join('\n') + '\n')
+    return 1
+  }
   const identifier = specIdentifier(snapshotDir, config)
   const r = push({ dir, snapshotDir, identifier, config })
   if (flags.json || !out.isTTY) {
+    warnToErr(snapshotDir, config, err)
     out.write(JSON.stringify(r.plan, null, 2) + '\n')
-    return
+    return 0
   }
   const p = r.plan
-  const lines = [`spec-sync push: ${identifier}`]
+  const lines = [`spec-sync push: ${identifier}`, ...warningLines(snapshotDir, config)]
+  if (p.legacy) lines.push(...legacyLines(p.legacy))
   if (r.empty) lines.push('  nothing to push — mirror matches the last push')
   else {
     if (p.issue) lines.push('  issue: description/state')
@@ -170,6 +204,167 @@ function specSyncPush(dir, config, specArg, flags, out) {
     lines.push('  (run with --json for the full plan the skill applies)')
   }
   out.write(lines.join('\n') + '\n')
+  return 0
+}
+
+// The pre-9.0 mirror block. Loud on purpose: the plan below it looks entirely
+// ordinary — an all-creates plan for a spec that reads as unlinked — and
+// applying it mints a second mirror and abandons the first.
+function legacyLines(legacy) {
+  const found = legacy.keys.length ? legacy.keys.join(', ') : 'a pre-9.0 last-pushed snapshot'
+  const where = legacy.files.length ? ` in ${legacy.files.join(', ')}` : ''
+  const out = [
+    '  !! PRE-9.0 MIRROR — do not apply this plan as-is',
+    `     found ${found}${where}`,
+  ]
+  if (legacy.orphans) {
+    const o = legacy.orphans
+    out.push(
+      `     applying it would orphan ${o.total} live object(s): ` +
+        `${o.projects} project(s), ${o.milestones} milestone(s), ${o.issues} task issue(s)`,
+    )
+  }
+  out.push('     migrate first — see MIGRATION.md ("v8 → v9")')
+  return out
+}
+
+/**
+ * Validate the configured `states` names against the workspace, for a command
+ * that REFUSES without them.
+ *
+ * The engine is offline — `mcp.js` is the skill's adapter, not ours — so the
+ * names have to be fetched over MCP and handed in via `--workspace-states`. That
+ * handoff used to be advisory: `/spec-push` told the agent to run it against
+ * `status`, and skipping it sent a state name Linear **silently ignores** (the
+ * description lands, the issue never moves, nothing errors). Requiring the file
+ * turns the one check that catches it from a convention into a precondition.
+ *
+ * Returns null when the caller may proceed, or the lines to print before exiting
+ * non-zero.
+ */
+function stateCheckFailure(config, flags) {
+  if (flags.skipStateCheck) return null
+  if (!flags.workspaceStates) {
+    return [
+      'spec-sync push: refusing — the configured issue states have not been validated',
+      '  pass --workspace-states <file> (a JSON array of the workspace\'s issue',
+      '  workflow-state names, which /spec-push fetches over MCP), or',
+      '  --skip-state-check to push anyway.',
+      '  Linear silently ignores an unknown issue state: the push would look',
+      '  clean and the issue would never move.',
+    ]
+  }
+  if (!fs.existsSync(flags.workspaceStates)) {
+    return [`spec-sync push: refusing — no such --workspace-states file: ${flags.workspaceStates}`]
+  }
+  let names
+  try {
+    names = JSON.parse(fs.readFileSync(flags.workspaceStates, 'utf-8'))
+  } catch (error) {
+    return [`spec-sync push: refusing — --workspace-states is not valid JSON: ${error.message}`]
+  }
+  const list = Array.isArray(names) ? names : []
+  const missing = validateStates(config, list)
+  if (missing.length) {
+    // Say what IS available, and what to use instead. "Done is not a state" sends
+    // you to the Linear UI to go and look; naming the replacement does not.
+    const lines = ['spec-sync push: refusing — configured state name(s) not in the workspace', '']
+    for (const { bucket, configured, suggestion } of stateSuggestions(config, list)) {
+      lines.push(`  states.${bucket}: "${configured}" is not an issue state in this workspace`)
+      if (suggestion) lines.push(`    use "${suggestion}" instead`)
+    }
+    lines.push(
+      '',
+      `  available: ${list.join(', ') || '(the workspace reported none)'}`,
+      '  Fix specs/.core/linear.config.json → states. Linear silently ignores an',
+      '  unknown issue state, so this would have pushed clean and moved nothing.',
+    )
+    return lines
+  }
+  return null
+}
+
+// A tracker id as it appears in a spec: `SKI-42`. Deliberately strict — the
+// whole point of `stamp` is that a mistyped id is caught here rather than
+// re-minting a duplicate issue on the next push.
+const ID_RE = /^[A-Za-z][A-Za-z0-9]*-\d+$/
+
+// Resolve a `--sub` ref to a phase file in the spec folder. Accepts the ref as
+// the plan emits it (`01-outbox`) or with its extension (`01-outbox.md`).
+function resolvePhaseFile(snapshotDir, ref) {
+  const want = String(ref).replace(/\.md$/, '')
+  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
+}
+
+/**
+ * `spec-sync stamp <spec> --issue KEY-N [--url URL] --sub <ref>=KEY-M …`
+ *
+ * Write the ids a push just returned back into the spec: `linear_identifier` /
+ * `linear_url` onto the overview, `linear_issue_id` onto each phase file. This
+ * was prose in `/spec-push` telling the agent to hand-edit N files — the step
+ * most likely to go wrong at scale, because one mistyped id makes the next push
+ * treat the phase as unlinked and mint a duplicate issue.
+ *
+ * Validates EVERYTHING before writing ANYTHING: a bad ref or id fails the whole
+ * command with nothing touched. A half-stamped spec is worse than an unstamped
+ * one — it looks linked while pointing at the wrong object.
+ *
+ * `record` stays a separate call: this writes the repo, that writes the snapshot,
+ * and the skill sequences them.
+ */
+function specSyncStamp(dir, config, specArg, flags, out) {
+  const snapshotDir = resolveOrExit(specArg, dir, out)
+  if (!snapshotDir) return 1
+
+  const problems = []
+  if (flags.issue != null && !ID_RE.test(flags.issue)) {
+    problems.push(`--issue ${flags.issue} is not an id like SKI-42`)
+  }
+  if (flags.url != null && !/^https?:\/\//.test(flags.url)) {
+    problems.push(`--url ${flags.url} is not an http(s) URL`)
+  }
+
+  const subs = []
+  for (const raw of flags.subs) {
+    const eq = String(raw).indexOf('=')
+    if (eq === -1) {
+      problems.push(`--sub ${raw} is not <ref>=<id> (e.g. --sub 01-outbox=SKI-43)`)
+      continue
+    }
+    const ref = raw.slice(0, eq)
+    const id = raw.slice(eq + 1)
+    const file = resolvePhaseFile(snapshotDir, ref)
+    if (!file) problems.push(`--sub ${ref}: no phase file in ${path.relative(dir, snapshotDir)}`)
+    if (!ID_RE.test(id)) problems.push(`--sub ${ref}=${id}: not an id like SKI-42`)
+    if (file && ID_RE.test(id)) subs.push({ ref, id, file })
+  }
+
+  if (!problems.length && flags.issue == null && !subs.length) {
+    problems.push('nothing to stamp — pass --issue and/or --sub <ref>=<id>')
+  }
+
+  if (problems.length) {
+    // Every problem at once: fixing them one round-trip at a time is the same
+    // slow hand-editing this command replaces.
+    out.write(['spec-sync stamp: refusing to write — nothing was changed', ...problems.map((p) => `  ${p}`)].join('\n') + '\n')
+    return 1
+  }
+
+  const lines = [`spec-sync stamp: ${path.relative(dir, snapshotDir)}`]
+  if (flags.issue != null || flags.url != null) {
+    const written = writeFrontmatter(snapshotDir, config, {
+      linear_identifier: flags.issue,
+      linear_url: flags.url,
+    })
+    lines.push(`  overview: ${written.join(', ')}`)
+  }
+  for (const s of subs) {
+    stampSubIssueId(snapshotDir, s.file, s.id)
+    lines.push(`  ${s.file}: linear_issue_id = ${s.id}`)
+  }
+  lines.push('  next: skitterspec spec-sync record <spec>')
+  out.write(lines.join('\n') + '\n')
+  return 0
 }
 
 // `spec-sync record <spec>` — write the last-pushed snapshot from the CURRENT
@@ -191,7 +386,7 @@ function specSyncStatus(dir, config, specArg, flags, out) {
   const snapshotDir = resolveOrExit(specArg, dir, out)
   if (!snapshotDir) return
   const identifier = specIdentifier(snapshotDir, config)
-  const lines = [`spec-sync status: ${identifier}`]
+  const lines = [`spec-sync status: ${identifier}`, ...warningLines(snapshotDir, config)]
 
   if (flags.workspaceStates && fs.existsSync(flags.workspaceStates)) {
     const names = JSON.parse(fs.readFileSync(flags.workspaceStates, 'utf-8'))
@@ -234,15 +429,20 @@ function specSyncStatus(dir, config, specArg, flags, out) {
 
 async function specSync(rest, io = {}) {
   const out = io.out || process.stdout
+  const err = io.err || process.stderr
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
-  const flags = { json: false, remote: null, workspaceStates: null }
+  const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [] }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--dir') dir = path.resolve(args[++i])
     else if (args[i] === '--json') flags.json = true
     else if (args[i] === '--remote') flags.remote = path.resolve(args[++i])
     else if (args[i] === '--workspace-states') flags.workspaceStates = path.resolve(args[++i])
+    else if (args[i] === '--skip-state-check') flags.skipStateCheck = true
+    else if (args[i] === '--issue') flags.issue = args[++i]
+    else if (args[i] === '--url') flags.url = args[++i]
+    else if (args[i] === '--sub') flags.subs.push(args[++i])
     else positional.push(args[i])
   }
   dir = path.resolve(dir)
@@ -258,11 +458,12 @@ async function specSync(rest, io = {}) {
 
   switch (sub) {
     case 'normalize':
-      specSyncNormalize(dir, config, positional[0], out)
+      specSyncNormalize(dir, config, positional[0], out, err)
       return 0
     case 'push':
-      specSyncPush(dir, config, positional[0], flags, out)
-      return 0
+      return specSyncPush(dir, config, positional[0], flags, out, err) || 0
+    case 'stamp':
+      return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
       specSyncRecord(dir, config, positional[0], out)
       return 0
@@ -272,7 +473,9 @@ async function specSync(rest, io = {}) {
       specSyncLinked(dir, config, flags, out)
       return 0
     default:
-      out.write('Usage: skitterspec spec-sync <normalize|push|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+      out.write('Usage: skitterspec spec-sync <normalize|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+        '       skitterspec spec-sync push <spec> --workspace-states <file> [--json] [--skip-state-check]\n' +
+        '       skitterspec spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]\n' +
         '       skitterspec spec-sync linked [--json]\n')
       return 0
   }

package/src/vendor/linear/config.js

@@ -37,6 +37,13 @@ const CONFIG_FILE = join('specs', '.core', 'linear.config.json')
 
 const OWNERSHIP = Object.freeze(['both', 'pull', 'push'])
 
+// How a phase's task list is projected into its sub-issue description.
+//   checklist — mirror the tasks as a read-only markdown checklist (default)
+//   none      — sub-issue description is the phase's `**Goal:**` line alone
+// Tasks are never read back either way; the repo stays the source of truth and a
+// box ticked in the tracker is overwritten by the next push.
+const TASK_MAPPINGS = Object.freeze(['checklist', 'none'])
+
 const DEFAULT_CONFIG = Object.freeze({
   // `projectId` is the project picker's DEFAULT, not a mandate: `/spec` and the
   // first `/spec-push` offer the team's projects and pre-select this one; empty
@@ -52,7 +59,9 @@ const DEFAULT_CONFIG = Object.freeze({
   intake: Object.freeze({ label: '', bugLabels: Object.freeze([]) }),
   // A spec is a Linear ISSUE; each phase is a SUB-ISSUE of it; tasks are not
   // synced (they live only in the repo phase files).
-  mapping: Object.freeze({ specFolder: 'issue', phases: 'subissue', tasks: 'none' }),
+  // A spec is an ISSUE; each phase a SUB-ISSUE of it. `tasks` selects how the
+  // phase's checkboxes reach that sub-issue's description — see TASK_MAPPINGS.
+  mapping: Object.freeze({ specFolder: 'issue', phases: 'subissue', tasks: 'checklist' }),
   // Linear ISSUE workflow-state names — the spec issue's state (from the folder
   // bucket) and each sub-issue's state (from the phase emoji) both map through
   // this one table. They must match the workspace's issue states exactly;
@@ -183,6 +192,15 @@ function mergeConfig(base, parsed) {
     assign(base.mapping, parsed.mapping, 'specFolder', 'string')
     assign(base.mapping, parsed.mapping, 'phases', 'string')
     assign(base.mapping, parsed.mapping, 'tasks', 'string')
+    // Loud on a typo, like fieldOwnership above. Quietly falling back would make
+    // a misspelt value look like a deliberate `none` — the same silent
+    // degradation the phase-status lint exists to stamp out.
+    if (!TASK_MAPPINGS.includes(base.mapping.tasks)) {
+      throw new Error(
+        `Invalid ${CONFIG_FILE}: mapping.tasks = ${JSON.stringify(base.mapping.tasks)} ` +
+          `(expected one of ${TASK_MAPPINGS.join('|')})`,
+      )
+    }
   }
 
   if (isObject(parsed.states)) {
@@ -247,4 +265,5 @@ module.exports = {
   DEFAULT_CONFIG,
   CONFIG_FILE,
   OWNERSHIP,
+  TASK_MAPPINGS,
 }

package/src/vendor/linear/mcp.js

@@ -4,7 +4,8 @@
  * The Linear MCP boundary — the one place that knows concrete Linear tool names.
  *
  * A spec is a Linear **issue** and each phase a **sub-issue** (a child issue
- * with a `parentId`); tasks are not synced. `discoverLinear(tools)` resolves the
+ * with a `parentId`); a phase's tasks are mirrored into its sub-issue
+ * description, never created as issues. `discoverLinear(tools)` resolves the
  * issue operations the sync needs (read / create / update an issue, optionally
  * list a parent's children) against the *connected* server's advertised tool
  * list at runtime, rather than hardcoding names that drift. If Linear isn't

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

@@ -10,15 +10,17 @@
  * over its API. No remote content is read or merged.
  */
 
-const { normalizeLocal, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates } = require('./src/normalize.js')
+const { normalizeLocal, lintPhases, readSnapshot, parseFrontmatter, remoteWorkflowState, titleFromText, validateStates, stateSuggestions } = require('./src/normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan, hashField, stableStringify } = require('./src/compare.js')
 const { readBase, writeBase } = require('./src/base.js')
 const { push, recordPush, projectionOf } = require('./src/push.js')
-const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle } = require('./src/write.js')
+const { writeFrontmatter, stampSubIssueId, stampIssueId, findPhaseFileByTitle, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
+const { detectLegacyMirror } = require('./src/legacy.js')
 
 module.exports = {
   normalizeLocal,
+  lintPhases,
   readSnapshot,
   parseFrontmatter,
   projectionOf,
@@ -30,6 +32,7 @@ module.exports = {
   remoteWorkflowState,
   titleFromText,
   validateStates,
+  stateSuggestions,
   hashField,
   stableStringify,
   readBase,
@@ -38,5 +41,7 @@ module.exports = {
   stampSubIssueId,
   stampIssueId,
   findPhaseFileByTitle,
+  listPhaseFiles,
   sanitizeSpecMarkdown,
+  detectLegacyMirror,
 }