@skitterbyte/skitterspec-linear 9.2.0 → 10.0.1

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,6 +10,7 @@
  *
  *   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)
@@ -35,6 +36,7 @@ const {
   isEmptyPlan,
   remoteWorkflowState,
   validateStates,
+  stateSuggestions,
   lintPhases,
   writeFrontmatter,
   stampSubIssueId,
@@ -178,16 +180,22 @@ function specSyncNormalize(dir, config, specArg, out, err) {
 // applies it over MCP then calls `record`.
 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}`, ...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')
@@ -196,6 +204,84 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
     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
@@ -347,12 +433,13 @@ async function specSync(rest, io = {}) {
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
-  const flags = { json: false, remote: null, workspaceStates: null, issue: null, url: null, subs: [] }
+  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])
@@ -374,8 +461,7 @@ async function specSync(rest, io = {}) {
       specSyncNormalize(dir, config, positional[0], out, err)
       return 0
     case 'push':
-      specSyncPush(dir, config, positional[0], flags, out, err)
-      return 0
+      return specSyncPush(dir, config, positional[0], flags, out, err) || 0
     case 'stamp':
       return specSyncStamp(dir, config, positional[0], flags, out)
     case 'record':
@@ -387,7 +473,8 @@ 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/sync-core/index.js

@@ -10,12 +10,13 @@
  * over its API. No remote content is read or merged.
  */
 
-const { normalizeLocal, lintPhases, 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, listPhaseFiles } = require('./src/write.js')
 const { sanitizeSpecMarkdown } = require('./src/sanitise.js')
+const { detectLegacyMirror } = require('./src/legacy.js')
 
 module.exports = {
   normalizeLocal,
@@ -31,6 +32,7 @@ module.exports = {
   remoteWorkflowState,
   titleFromText,
   validateStates,
+  stateSuggestions,
   hashField,
   stableStringify,
   readBase,
@@ -41,4 +43,5 @@ module.exports = {
   findPhaseFileByTitle,
   listPhaseFiles,
   sanitizeSpecMarkdown,
+  detectLegacyMirror,
 }

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

@@ -0,0 +1,90 @@
+'use strict'
+
+/**
+ * Detect a spec whose mirror was created under the **pre-9.0 model**.
+ *
+ * v9 remapped the mirror: a spec is an issue (was a Project), a phase is a
+ * sub-issue (was a Milestone), and tasks are no longer objects at all. The
+ * frontmatter keys moved with it — `linear_project_id` → `linear_identifier`,
+ * `linear_milestone_id` → `linear_issue_id`.
+ *
+ * The failure this guards is silent and destructive: v9 looks for the new keys,
+ * finds nothing, and produces a perfectly ordinary **all-creates** plan. Applying
+ * it mints a fresh mirror and abandons the old one — in the field that would have
+ * been 17 new objects against 2 projects, 15 milestones and 145 task issues left
+ * orphaned, with nothing on screen suggesting a prior mirror existed. It was
+ * caught only because an all-creates plan looked wrong for specs synced an hour
+ * earlier.
+ *
+ * Pure reads; returns `null` for anything that is not demonstrably pre-9.0, so a
+ * never-pushed spec is never mistaken for a stranded one.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const { parseFrontmatter } = require('./normalize.js')
+const { readBase } = require('./base.js')
+const { listPhaseFiles } = require('./write.js')
+
+// Frontmatter keys only the pre-9.0 model ever wrote.
+const LEGACY_OVERVIEW_KEY = 'linear_project_id'
+const LEGACY_PHASE_KEY = 'linear_milestone_id'
+
+function frontmatterOf(file) {
+  try {
+    return parseFrontmatter(fs.readFileSync(file, 'utf-8')).data || {}
+  } catch {
+    return {}
+  }
+}
+
+// A pre-9.0 snapshot recorded `{project, milestones, issues}`; v9 records
+// `{issue, subIssues}`. Counting what it holds turns the warning from "this
+// looks old" into "this many live objects would be abandoned".
+function countOrphans(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object') return null
+  const size = (v) => (Array.isArray(v) ? v.length : v && typeof v === 'object' ? Object.keys(v).length : 0)
+  const projects = snapshot.project ? 1 : 0
+  const milestones = size(snapshot.milestones)
+  const issues = size(snapshot.issues)
+  if (!projects && !milestones && !issues) return null
+  return { projects, milestones, issues, total: projects + milestones + issues }
+}
+
+/**
+ * @returns {null|{keys:string[], files:string[], orphans:object|null, orphanCount:number}}
+ */
+function detectLegacyMirror({ dir, snapshotDir, identifier, config }) {
+  const keys = []
+  const files = []
+
+  const overviewFile = (config && config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const overview = frontmatterOf(path.join(snapshotDir, overviewFile))
+  if (overview[LEGACY_OVERVIEW_KEY] != null) {
+    keys.push(LEGACY_OVERVIEW_KEY)
+    files.push(overviewFile)
+  }
+
+  for (const file of listPhaseFiles(snapshotDir)) {
+    if (frontmatterOf(path.join(snapshotDir, file))[LEGACY_PHASE_KEY] != null) {
+      if (!keys.includes(LEGACY_PHASE_KEY)) keys.push(LEGACY_PHASE_KEY)
+      files.push(file)
+    }
+  }
+
+  let orphans = null
+  try {
+    orphans = countOrphans(readBase(dir, identifier, config))
+  } catch {
+    /* an unreadable snapshot is not evidence either way */
+  }
+
+  // A legacy snapshot alone is enough: the spec may have had its frontmatter
+  // hand-cleaned while the mirror it names is still live.
+  if (!keys.length && !orphans) return null
+
+  return { keys, files, orphans, orphanCount: orphans ? orphans.total : 0 }
+}
+
+module.exports = { detectLegacyMirror }

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

@@ -319,6 +319,46 @@ function parseTaskLine(line) {
   return { id, text, done }
 }
 
+/**
+ * Split a phase's task blocks into the `##` sections they were written under.
+ *
+ * The checklist used to be one flat list under a hardcoded `## Tasks`, so a
+ * criterion written under `## Acceptance` arrived in the mirror as an ordinary
+ * open task. Nothing was lost — it was just unreadable.
+ *
+ * Grouping is done by MAPPING blocks onto headings, not by re-parsing the body
+ * section by section: `findTaskBlocks` tracks open task subtrees across a
+ * continuous body, and slicing that body at every heading would change what a
+ * block claims at a section boundary. A heading inside a fence is not a heading
+ * (`fenceMask`), and the phase file's own `#` H1 is not a section.
+ *
+ * @returns {Array<{heading:string|null, tasks:string[]}>} in source order;
+ *   `heading` is null for blocks that precede every heading, and a heading with
+ *   no blocks under it never appears.
+ */
+function groupTasksByHeading(lines, blocks, renderTask) {
+  const inFence = fenceMask(lines)
+  const headings = []
+  for (let i = 0; i < lines.length; i++) {
+    if (inFence[i]) continue
+    const m = /^(#{2,6})\s+(.*\S)\s*$/.exec(lines[i])
+    if (m) headings.push({ line: i, heading: `${m[1]} ${m[2]}` })
+  }
+
+  const groups = []
+  for (const b of blocks) {
+    let heading = null
+    for (const h of headings) {
+      if (h.line >= b.start) break
+      heading = h.heading
+    }
+    const last = groups[groups.length - 1]
+    if (last && last.heading === heading) last.tasks.push(renderTask(b))
+    else groups.push({ heading, tasks: [renderTask(b)] })
+  }
+  return groups
+}
+
 // 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) {
@@ -343,14 +383,23 @@ function readPhaseFiles(snapshotDir) {
       // both sides keeps a wrapped goal from diffing forever.
       const goal = collapseHyphenAware((/\*\*Goal:\*\*\s*([\s\S]*?)(?:\n\n|$)/.exec(body) || [])[1] || '')
       // Rendered as markdown checklist lines, ready to drop into a sub-issue
-      // description: indentation kept so nesting survives, the bullet marker
-      // normalised to `-`, and any inline `(KEY-123)` stamped on a legacy task
+      // description: indentation kept so nesting survives, each bullet keeping
+      // the marker its author wrote, and any inline `(KEY-123)` stamped on a legacy task
       // line stripped — those ids were per-task issues we no longer create, and
       // they read as noise in the mirror.
-      const tasks = findTaskBlocks(body.split('\n')).map((b) => {
-        const parsed = parseTaskLine(`[${b.mark}] ${b.text}`)
-        return `${b.indent}- [${b.mark}] ${parsed ? parsed.text : b.text}`
-      })
+      const lines = body.split('\n')
+      const renderTask = (b) => {
+        // `findTaskBlocks` also returns the plain sub-bullets written underneath
+        // a task. They carry no checkbox, so they render as the bullet their
+        // author used — emitting `- [ ]` here would invent a task that does not
+        // exist in the repo.
+        const parsed = parseTaskLine(`[${b.checkbox ? b.mark : ' '}] ${b.text}`)
+        const text = parsed ? parsed.text : b.text
+        return b.checkbox ? `${b.indent}- [${b.mark}] ${text}` : `${b.indent}${b.marker} ${text}`
+      }
+      const blocks = findTaskBlocks(lines)
+      const tasks = blocks.map(renderTask)
+      const taskGroups = groupTasksByHeading(lines, blocks, renderTask)
       return {
         phase: file.replace(/\.md$/, ''),
         file,
@@ -365,6 +414,7 @@ function readPhaseFiles(snapshotDir) {
         emoji: headingEmoji(body),
         statusLine: phaseStatusLine(body),
         tasks,
+        taskGroups,
       }
     })
 }
@@ -492,7 +542,14 @@ function subIssueBody(phase, tasksMode) {
   if (tasksMode !== 'checklist' || !phase.tasks.length) return phase.goal
   const parts = []
   if (phase.goal) parts.push(phase.goal, '')
-  parts.push('## Tasks', '', ...phase.tasks)
+  // One section per source heading, in source order. Checkboxes written before
+  // any heading keep the `## Tasks` default, so a phase file with a single task
+  // section — every one in this repo's corpus but two — projects unchanged.
+  const groups = phase.taskGroups && phase.taskGroups.length ? phase.taskGroups : [{ heading: null, tasks: phase.tasks }]
+  groups.forEach((group, i) => {
+    if (i) parts.push('')
+    parts.push(group.heading || '## Tasks', '', ...group.tasks)
+  })
   return parts.join('\n')
 }
 
@@ -663,7 +720,43 @@ function validateStates(config, workspaceStates) {
   return configured.filter((name) => !have.has(name.toLowerCase().trim()))
 }
 
+// Words that identify a workspace state as belonging to a lifecycle bucket.
+// Used only to SUGGEST a replacement for a configured name the workspace does
+// not have — never to pick one silently. The 8→9 case this exists for is
+// `complete`, where the correct value inverts: the project status `Completed`
+// became the issue state `Done`, and no string-distance measure gets you from
+// one to the other.
+const BUCKET_WORDS = {
+  backlog: ['backlog', 'triage', 'todo', 'to do'],
+  'in-progress': ['in progress', 'in-progress', 'doing', 'started', 'in review'],
+  complete: ['done', 'complete', 'completed', 'shipped', 'merged', 'released'],
+  cancelled: ['canceled', 'cancelled', 'abandoned', "won't do", 'wont do', 'duplicate'],
+}
+
+/**
+ * For each configured state name the workspace lacks, what to use instead.
+ *
+ * `validateStates` says a name is wrong; this says what is right, which is the
+ * difference between an error you can act on and one you have to go look up.
+ *
+ * @returns {Array<{bucket:string, configured:string, suggestion:string|null}>}
+ */
+function stateSuggestions(config, workspaceStates) {
+  const names = (workspaceStates || []).map((s) => String(s)).filter(Boolean)
+  const have = new Set(names.map((n) => n.toLowerCase().trim()))
+  const out = []
+  for (const [bucket, configured] of Object.entries((config && config.states) || {})) {
+    if (typeof configured !== 'string') continue
+    if (have.has(configured.toLowerCase().trim())) continue
+    const words = BUCKET_WORDS[bucket] || []
+    const suggestion = names.find((n) => words.includes(n.toLowerCase().trim())) || null
+    out.push({ bucket, configured, suggestion })
+  }
+  return out
+}
+
 module.exports = {
+  stateSuggestions,
   normalizeLocal,
   lintPhases,
   readSnapshot,

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

@@ -18,6 +18,7 @@
 const { normalizeLocal } = require('./normalize.js')
 const { planChanges, snapshotOf, isEmptyPlan } = require('./compare.js')
 const { readBase, writeBase } = require('./base.js')
+const { detectLegacyMirror } = require('./legacy.js')
 
 // Build the one-way projection from a local snapshot: the spec issue's prose +
 // status, and its phase sub-issues. `status` is the local lifecycle bucket; the
@@ -36,6 +37,12 @@ function push({ dir, snapshotDir, identifier, config }) {
   const projection = projectionOf(snapshotDir, config)
   const snapshot = readBase(dir, identifier, config)
   const plan = planChanges(projection, snapshot)
+  // A spec still linked under the pre-9.0 model reads as unlinked here, so the
+  // plan above is all-creates and would abandon a live mirror. Carry the finding
+  // ON THE PLAN, not as a warning: `--json` routes warnings to stderr, and the
+  // skill that applies this plan is exactly the consumer that would miss them.
+  const legacy = detectLegacyMirror({ dir, snapshotDir, identifier, config })
+  if (legacy) plan.legacy = legacy
   return { ok: true, empty: isEmptyPlan(plan), plan, projection }
 }