@skitterbyte/skitterspec-linear 10.3.0 → 10.4.0

package/src/vendor/linear/credentials.js

@@ -0,0 +1,299 @@
+'use strict'
+
+/**
+ * The user-level credentials store — where a Linear API key lives when it is
+ * not in the environment.
+ *
+ * The repo's `specs/.core/linear.config.json` is COMMITTED and deliberately
+ * holds only the NAME of an env var, never a key. That is what makes it safe to
+ * share, so a key can never go there. This store is the alternative: one file
+ * per machine, outside every repo, at
+ * `$XDG_CONFIG_HOME/skitterspec/credentials.json` (else `~/.config/…`), keyed by
+ * Linear team id so one file serves every checkout.
+ *
+ * Reads never throw. `resolveApiKey` already treats "no key" as a NORMAL state
+ * meaning "fall back to MCP" rather than an error, so every failure here returns
+ * a structured reason the caller can report or ignore — a missing store is not a
+ * problem, it is the default.
+ *
+ * Nothing in this module ever returns a key inside an error, and callers must
+ * keep it out of logs, plans, snapshots and stamped frontmatter.
+ */
+
+const { spawnSync } = require('node:child_process')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const DIR_NAME = 'skitterspec'
+const FILE_NAME = 'credentials.json'
+
+// Modes wider than owner-only. Checked ssh-style: a store other users can read
+// is refused rather than read, because silently using it would hide the leak,
+// and silently chmod'ing someone's file is not ours to do.
+const GROUP_OR_WORLD = 0o077
+
+/**
+ * Absolute path of the store. Honours `$XDG_CONFIG_HOME`, else `~/.config`.
+ * `env` and `homedir` are injected so tests never touch a real home directory.
+ */
+function storePath(env = process.env, homedir = os.homedir) {
+  const xdg = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME.trim()
+  const base = xdg || path.join(homedir(), '.config')
+  return path.join(base, DIR_NAME, FILE_NAME)
+}
+
+/**
+ * Read the store.
+ *
+ * @returns {object} `{ ok: true, store, path }` — parsed and owner-only;
+ *   `{ ok: false, reason, code, path }` otherwise. `code` is one of:
+ *   `absent` (no file — the normal default, not a problem), `permissions`
+ *   (group/world readable), `unreadable`, `malformed`.
+ */
+function readStore(file, { stat = fs.statSync, read = fs.readFileSync } = {}) {
+  let info
+  try {
+    info = stat(file)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { ok: false, code: 'absent', path: file, reason: `no credentials store at ${file}` }
+    }
+    return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
+  }
+
+  if (info.mode & GROUP_OR_WORLD) {
+    const mode = (info.mode & 0o777).toString(8)
+    return {
+      ok: false,
+      code: 'permissions',
+      path: file,
+      reason:
+        `credentials store ${file} is mode ${mode} — readable by other users.\n` +
+        `  Run: chmod 600 ${file}`,
+    }
+  }
+
+  let raw
+  try {
+    raw = read(file, 'utf-8')
+  } catch (err) {
+    return { ok: false, code: 'unreadable', path: file, reason: `cannot read ${file}: ${err.message}` }
+  }
+
+  let store
+  try {
+    store = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, code: 'malformed', path: file, reason: `invalid JSON in ${file}: ${err.message}` }
+  }
+  if (!store || typeof store !== 'object' || Array.isArray(store)) {
+    return { ok: false, code: 'malformed', path: file, reason: `invalid credentials store in ${file}` }
+  }
+  return { ok: true, store, path: file }
+}
+
+/**
+ * The key recorded for one team, or null. Never throws, and never reports the
+ * value it did or didn't find.
+ */
+function keyForTeam(store, teamId) {
+  if (!teamId) return null
+  const teams = store && store.teams
+  const entry = teams && typeof teams === 'object' ? teams[teamId] : null
+  if (!entry || typeof entry !== 'object') return null
+  const key = entry.key
+  return typeof key === 'string' && key.trim() ? key.trim() : null
+}
+
+// Last 4 characters, for reporting that a key exists without revealing it.
+function fingerprint(key) {
+  if (typeof key !== 'string' || !key) return null
+  return `…${key.slice(-4)}`
+}
+
+
+/**
+ * Record a key for one team, creating the store at `0600` and its directory at
+ * `0700`. Other teams' entries are preserved.
+ *
+ * Refuses rather than writing when the existing store is unreadable or
+ * over-permissive — the same guard as reading, because silently rewriting a
+ * world-readable file would leave the leak in place.
+ *
+ * Returns `{ ok: true, path, created }` or `{ ok: false, reason }`. The key is
+ * never echoed back in either.
+ */
+function writeKey(file, teamId, key, deps = {}) {
+  const mkdir = deps.mkdir || fs.mkdirSync
+  const write = deps.write || fs.writeFileSync
+  const chmod = deps.chmod || fs.chmodSync
+  const exists = deps.exists || fs.existsSync
+
+  if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+  if (typeof key !== 'string' || !key.trim()) return { ok: false, reason: 'empty key — nothing stored' }
+
+  const created = !exists(file)
+  let store = { version: 1, teams: {} }
+  if (!created) {
+    const current = readStore(file, deps)
+    if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
+    store = current.store
+    if (!store.teams || typeof store.teams !== 'object') store.teams = {}
+    if (!store.version) store.version = 1
+  }
+
+  store.teams[teamId] = { ...(store.teams[teamId] || {}), key: key.trim() }
+
+  mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+  // `mode` on writeFileSync only applies when the file is CREATED, so an
+  // existing file keeps its mode — narrow it explicitly.
+  chmod(file, 0o600)
+  return { ok: true, path: file, created }
+}
+
+/**
+ * Remove one team's entry, leaving every other team intact. A store or entry
+ * that isn't there is a clean no-op, not an error.
+ */
+function removeKey(file, teamId, deps = {}) {
+  const write = deps.write || fs.writeFileSync
+  const current = readStore(file, deps)
+  if (!current.ok) {
+    if (current.code === 'absent') return { ok: true, path: file, removed: false }
+    return { ok: false, reason: current.reason, code: current.code }
+  }
+  const teams = current.store.teams
+  if (!teams || !teams[teamId]) return { ok: true, path: file, removed: false }
+  delete teams[teamId]
+  write(file, JSON.stringify(current.store, null, 2) + '\n', { mode: 0o600 })
+  return { ok: true, path: file, removed: true }
+}
+
+/**
+ * Resolve one team's key from the store: a stored `key` first, else running its
+ * `keyCommand` and taking stdout.
+ *
+ * `keyCommand` is honoured ONLY from this user-level store — never from the
+ * repo's committed `linear.config.json`. That file travels with the repo, so a
+ * command named there would let a cloned repo run arbitrary code on the machine
+ * of anyone who ran `spec-sync`. The repo config keeps naming only an env var.
+ *
+ * A command that fails, times out or prints nothing resolves to no key, which is
+ * the ordinary "fall back to MCP" state — but its stderr is carried back so a
+ * broken command is diagnosable rather than mysteriously inert. Its **stdout is
+ * never** put in an error: that is the key.
+ *
+ * @returns {object} `{ key, source }` with source `'store'` | `'command'`, or
+ *   `{ key: null, source: null, reason }`.
+ */
+function resolveTeamKey(store, teamId, deps = {}) {
+  const direct = keyForTeam(store, teamId)
+  if (direct) return { key: direct, source: 'store' }
+
+  const entry = store && store.teams && typeof store.teams === 'object' ? store.teams[teamId] : null
+  const command = entry && typeof entry.keyCommand === 'string' ? entry.keyCommand.trim() : ''
+  if (!command) return { key: null, source: null }
+
+  const run = deps.run || defaultRunCommand
+  const result = run(command, deps.timeoutMs || COMMAND_TIMEOUT_MS)
+  if (!result.ok) {
+    return { key: null, source: null, command, reason: `keyCommand failed: ${result.error}` }
+  }
+  const key = (result.stdout || '').trim()
+  if (!key) {
+    return { key: null, source: null, command, reason: 'keyCommand produced no output' }
+  }
+  return { key, source: 'command', command }
+}
+
+// 60s: a password manager may prompt for biometric or a master password, and a
+// hang here would look like the CLI itself wedging.
+const COMMAND_TIMEOUT_MS = 60_000
+
+// Linear personal API keys are `lin_api_` + a long token.
+const LITERAL_KEY_RE = /lin_api_[A-Za-z0-9]{8,}/
+
+function defaultRunCommand(command, timeout) {
+  const r = spawnSync('sh', ['-c', command], { encoding: 'utf-8', timeout })
+  if (r.error) return { ok: false, error: r.error.message }
+  if (r.status !== 0) {
+    // stderr only — stdout is the secret, and must not reach an error message.
+    const detail = (r.stderr || '').trim().split('\n')[0] || `exit ${r.status}`
+    return { ok: false, error: detail }
+  }
+  return { ok: true, stdout: r.stdout }
+}
+
+/**
+ * Record a command for one team instead of a key. Unlike a key, a command is not
+ * a secret, so this one IS safe to pass as an argument.
+ */
+function writeKeyCommand(file, teamId, command, deps = {}) {
+  const mkdir = deps.mkdir || fs.mkdirSync
+  const write = deps.write || fs.writeFileSync
+  const chmod = deps.chmod || fs.chmodSync
+  const exists = deps.exists || fs.existsSync
+
+  if (!teamId) return { ok: false, reason: 'no team id — nothing to key the entry by' }
+  if (typeof command !== 'string' || !command.trim()) {
+    return { ok: false, reason: 'empty command — nothing stored' }
+  }
+  // Refusing `--key` makes `--command "echo lin_api_…"` the obvious workaround,
+  // and it is worse: a command is NOT treated as a secret — `status` prints it
+  // back, and it sits in the store in clear. Catch the shortcut at the door.
+  if (LITERAL_KEY_RE.test(command)) {
+    return {
+      ok: false,
+      reason:
+        'that command has a Linear key written into it.\n' +
+        '  A command is displayed by `credentials status` and is not treated as a\n' +
+        '  secret — embedding a key there exposes it. To store a key, run\n' +
+        '  `credentials set` with no arguments and paste at the hidden prompt.',
+    }
+  }
+
+  const created = !exists(file)
+  let store = { version: 1, teams: {} }
+  if (!created) {
+    const current = readStore(file, deps)
+    if (!current.ok) return { ok: false, reason: current.reason, code: current.code }
+    store = current.store
+    if (!store.teams || typeof store.teams !== 'object') store.teams = {}
+    if (!store.version) store.version = 1
+  }
+
+  // A command REPLACES a stored key for that team — keeping both would mean the
+  // key silently wins and the command never runs.
+  store.teams[teamId] = { keyCommand: command.trim() }
+
+  mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  write(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 })
+  chmod(file, 0o600)
+  return { ok: true, path: file, created }
+}
+
+/** The store's permission bits as an octal string, or null when absent. */
+function storeMode(file, deps = {}) {
+  const stat = deps.stat || fs.statSync
+  try {
+    return (stat(file).mode & 0o777).toString(8)
+  } catch {
+    return null
+  }
+}
+
+module.exports = {
+  storePath,
+  readStore,
+  keyForTeam,
+  fingerprint,
+  writeKey,
+  writeKeyCommand,
+  resolveTeamKey,
+  removeKey,
+  storeMode,
+  DIR_NAME,
+  FILE_NAME,
+}

package/src/vendor/linear/doctor.js

@@ -0,0 +1,341 @@
+'use strict'
+
+/**
+ * Identifier drift — the offline half of `spec-sync doctor`.
+ *
+ * When a Linear team is renamed (`REU` → `ERQ`), nothing in the repo moves: every
+ * stamped `linear_identifier` / `linear_issue_id` / `linear_url`, the config's
+ * `teamKey`, and every `linear-base/<ID>.base.json` filename keeps the old
+ * prefix. Nothing detected it and nothing repaired it; the first occurrence was
+ * fixed by hand across 221 refs in 54 files.
+ *
+ * This module only SCANS — it reads the repo and reports what disagrees with a
+ * team key it is handed. It performs no network calls and writes nothing, so the
+ * detection logic is testable without an adapter. Deciding what the current key
+ * IS (a Linear read) and repairing (phase 3) live in `cli-sync.js`.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { execFileSync } = require('node:child_process')
+
+const { BUCKETS } = require('../../env/resolve.js')
+const { parseFrontmatter } = require('../sync-core')
+
+// A Linear issue identifier: an uppercase team key, a dash, a number. The key is
+// captured so drift is a prefix comparison rather than a guess.
+const IDENTIFIER_RE = /^([A-Z][A-Z0-9]*)-(\d+)$/
+// The same, embedded in a URL path (`…/issue/REU-151/slug`).
+const URL_IDENTIFIER_RE = /\b([A-Z][A-Z0-9]*)-(\d+)\b/g
+
+const STAMP_FIELDS = ['linear_identifier', 'linear_issue_id']
+
+// Every `.md` under each spec folder — overview and phase files alike, plus the
+// legacy bare `<name>.md` shape. Anything stamped lives in one of these.
+function specMarkdownFiles(dir) {
+  const files = []
+  for (const bucket of BUCKETS) {
+    const root = path.join(dir, 'specs', bucket)
+    let entries
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const p = path.join(root, entry.name)
+      if (entry.isDirectory()) {
+        for (const f of fs.readdirSync(p)) if (f.endsWith('.md')) files.push(path.join(p, f))
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push(p)
+      }
+    }
+  }
+  return files.sort()
+}
+
+// Retarget one identifier onto `currentKey`, preserving the number. Returns null
+// when it is already current or is not an identifier at all.
+function retarget(value, currentKey) {
+  const m = IDENTIFIER_RE.exec(String(value).trim())
+  if (!m || m[1] === currentKey) return null
+  return `${currentKey}-${m[2]}`
+}
+
+/**
+ * Scan the repo for identifiers that disagree with `currentKey`.
+ *
+ * @returns {{
+ *   stamps: Array<{file, field, from, to}>,
+ *   urls: Array<{file, from, to}>,
+ *   snapshots: Array<{from, to}>,
+ *   snapshotKeys: Array<{file, from, to}>,
+ *   mentions: Array<{file, from, to}>,   // prose refs — reported, never repaired
+ *   config: {from, to}|null,
+ *   refs: Array<{from, to}>,
+ * }} `refs` is the DISTINCT set of drifted identifiers — what the caller checks
+ *    against Linear, so 221 stamps of 198 identifiers cost 198 reads, not 221.
+ */
+function scanDrift(dir, config, currentKey) {
+  const stamps = []
+  const urls = []
+  const seen = new Map()
+  const note = (from, to) => seen.set(from, to)
+
+  for (const file of specMarkdownFiles(dir)) {
+    let raw
+    try {
+      raw = fs.readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    const { data } = parseFrontmatter(raw)
+    for (const field of STAMP_FIELDS) {
+      if (!data[field]) continue
+      const to = retarget(data[field], currentKey)
+      if (!to) continue
+      stamps.push({ file: path.relative(dir, file), field, from: String(data[field]).trim(), to })
+      note(String(data[field]).trim(), to)
+    }
+    if (data.linear_url) {
+      const url = String(data.linear_url)
+      let changed = url
+      for (const m of url.matchAll(URL_IDENTIFIER_RE)) {
+        const to = retarget(m[0], currentKey)
+        if (!to) continue
+        changed = changed.split(m[0]).join(to)
+        note(m[0], to)
+      }
+      if (changed !== url) urls.push({ file: path.relative(dir, file), from: url, to: changed })
+    }
+  }
+
+  const snapshots = []
+  const snapshotKeys = []
+  const baseDir = path.resolve(dir, config.sync.baseDir)
+  let snapshotNames = []
+  try {
+    snapshotNames = fs.readdirSync(baseDir).filter((f) => f.endsWith('.base.json'))
+  } catch {
+    /* no snapshots yet — nothing to retarget */
+  }
+  for (const name of snapshotNames.sort()) {
+    const to = retarget(name.slice(0, -'.base.json'.length), currentKey)
+    if (to) {
+      snapshots.push({ from: name, to: `${to}.base.json` })
+      note(name.slice(0, -'.base.json'.length), to)
+    }
+    // A snapshot's `subIssues` map is KEYED BY IDENTIFIER, so a rename strands
+    // every key inside the file as well as the filename. Missing these made the
+    // first scan report 59 refs where the repo really carries ~198: the bulk of
+    // a linked repo's identifiers live in here, not in frontmatter. The hashes
+    // are content-derived and stay valid — only their keys move.
+    let body
+    try {
+      body = JSON.parse(fs.readFileSync(path.join(baseDir, name), 'utf-8'))
+    } catch {
+      continue
+    }
+    for (const ident of Object.keys((body && body.subIssues) || {})) {
+      const keyTo = retarget(ident, currentKey)
+      if (!keyTo) continue
+      snapshotKeys.push({ file: path.join(config.sync.baseDir, name), from: ident, to: keyTo })
+      note(ident, keyTo)
+    }
+  }
+
+  // Prose MENTIONS of a stale identifier — `(REU-61)` beside a task, "the REU-196
+  // spec claimed …". These are human-written references, not functional stamps,
+  // and repair deliberately leaves them alone: rewriting narrative text is a
+  // different risk class, and an identifier-shaped token in prose need not be a
+  // Linear ref at all. They are counted anyway so the report cannot imply a
+  // `--write` left the repo fully retargeted when ~145 mentions still say REU.
+  //
+  // Only prefixes that actually appear in the repo's STAMPS are counted, so an
+  // unrelated `ABC-123` in prose is never mistaken for a drifted ref.
+  const staleKeys = new Set([...seen.keys()].map((k) => k.split('-')[0]))
+  const mentions = []
+  if (staleKeys.size) {
+    for (const file of specMarkdownFiles(dir)) {
+      let raw
+      try {
+        raw = fs.readFileSync(file, 'utf-8')
+      } catch {
+        continue
+      }
+      const { body } = parseFrontmatter(raw)
+      for (const m of String(body).matchAll(URL_IDENTIFIER_RE)) {
+        if (!staleKeys.has(m[1]) || m[1] === currentKey) continue
+        mentions.push({ file: path.relative(dir, file), from: m[0], to: `${currentKey}-${m[2]}` })
+      }
+    }
+  }
+
+  const configured = (config.linear && config.linear.teamKey) || ''
+  const configDrift = configured && configured !== currentKey ? { from: configured, to: currentKey } : null
+
+  return {
+    stamps,
+    urls,
+    snapshots,
+    snapshotKeys,
+    mentions,
+    config: configDrift,
+    refs: [...seen.entries()].map(([from, to]) => ({ from, to })).sort((a, b) => a.from.localeCompare(b.from)),
+  }
+}
+
+// True when a scan found nothing to repair.
+function isClean(drift) {
+  return (
+    !drift.stamps.length &&
+    !drift.urls.length &&
+    !drift.snapshots.length &&
+    !drift.snapshotKeys.length &&
+    !drift.config
+  )
+}
+
+// How many distinct files a repair would touch.
+function fileCount(drift) {
+  return new Set([...drift.stamps.map((s) => s.file), ...drift.urls.map((u) => u.file)]).size
+}
+
+// --- repair ------------------------------------------------------------------
+
+// `git status --porcelain` over `dir`: [] when clean, the offending lines when
+// dirty, null when this is not a git repo at all.
+function dirtyPaths(dir) {
+  let out
+  try {
+    out = execFileSync('git', ['-C', dir, 'status', '--porcelain'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim()
+  } catch {
+    return null
+  }
+  return out ? out.split('\n') : []
+}
+
+// Rewrite identifier tokens INSIDE a file's frontmatter block only.
+//
+// Scoped to the frontmatter on purpose: the same token appears in spec prose,
+// which repair deliberately leaves alone. A blind whole-file replace would
+// rewrite narrative text as a side effect of fixing a stamp.
+function rewriteFrontmatter(raw, replacements) {
+  const m = /^(---\n[\s\S]*?\n---)(\n[\s\S]*)?$/.exec(raw)
+  if (!m) return raw
+  let head = m[1]
+  for (const [from, to] of replacements) head = head.split(from).join(to)
+  return head + (m[2] || '')
+}
+
+// Move a file, preferring `git mv` so history survives. Falls back to a plain
+// rename when the file is untracked (git mv refuses those) or git is absent.
+function moveFile(dir, from, to) {
+  try {
+    execFileSync('git', ['-C', dir, 'mv', from, to], { stdio: ['ignore', 'ignore', 'ignore'] })
+    return 'git mv'
+  } catch {
+    fs.renameSync(path.join(dir, from), path.join(dir, to))
+    return 'rename'
+  }
+}
+
+/**
+ * Apply a scan's repairs. Everything moves together — config, stamps, snapshot
+ * filenames and the identifier keys inside them — because a half-repaired repo
+ * is harder to reason about than an un-repaired one.
+ *
+ * `skip` is the set of `from` identifiers that resolve to NO issue under the new
+ * key. Those are left exactly as they are: repair fixes what is provably
+ * repairable, and reports the rest rather than inventing a target.
+ *
+ * Prose mentions are never touched — see `scanDrift`.
+ */
+function repairDrift(dir, config, drift, { skip = new Set() } = {}) {
+  const keep = (r) => !skip.has(r.from)
+  const changed = { files: [], snapshots: [], config: false, skipped: 0 }
+
+  // 1. Frontmatter stamps and urls, one pass per file.
+  const byFile = new Map()
+  for (const r of [...drift.stamps, ...drift.urls]) {
+    if (!keep(r)) {
+      changed.skipped++
+      continue
+    }
+    if (!byFile.has(r.file)) byFile.set(r.file, [])
+    byFile.get(r.file).push([r.from, r.to])
+  }
+  for (const [rel, replacements] of byFile) {
+    const abs = path.join(dir, rel)
+    const raw = fs.readFileSync(abs, 'utf-8')
+    const next = rewriteFrontmatter(raw, replacements)
+    if (next !== raw) {
+      fs.writeFileSync(abs, next, 'utf-8')
+      changed.files.push(rel)
+    }
+  }
+
+  // 2. Snapshot sub-issue keys, rewritten BEFORE the filename moves so the path
+  //    being read is still the one the scan recorded.
+  const keysByFile = new Map()
+  for (const k of drift.snapshotKeys) {
+    if (!keep(k)) {
+      changed.skipped++
+      continue
+    }
+    if (!keysByFile.has(k.file)) keysByFile.set(k.file, [])
+    keysByFile.get(k.file).push(k)
+  }
+  for (const [rel, keys] of keysByFile) {
+    const abs = path.join(dir, rel)
+    const body = JSON.parse(fs.readFileSync(abs, 'utf-8'))
+    const subIssues = {}
+    // The hashes are CONTENT-derived, so they survive a rename untouched — only
+    // the keys move. Rebuilt rather than mutated so key order stays stable.
+    for (const [ident, hash] of Object.entries(body.subIssues || {})) {
+      const hit = keys.find((k) => k.from === ident)
+      subIssues[hit ? hit.to : ident] = hash
+    }
+    fs.writeFileSync(abs, JSON.stringify({ ...body, subIssues }, null, 2) + '\n', 'utf-8')
+  }
+
+  // 3. Snapshot filenames.
+  const baseRel = config.sync.baseDir
+  for (const snap of drift.snapshots) {
+    const ident = snap.from.slice(0, -'.base.json'.length)
+    if (skip.has(ident)) {
+      changed.skipped++
+      continue
+    }
+    const how = moveFile(dir, path.join(baseRel, snap.from), path.join(baseRel, snap.to))
+    changed.snapshots.push({ ...snap, how })
+  }
+
+  // 4. The config key, last: it is the thing that makes the next scan read
+  //    clean, so it should not flip before the files it describes have moved.
+  if (drift.config) {
+    const file = path.join(dir, 'specs', '.core', 'linear.config.json')
+    const raw = fs.readFileSync(file, 'utf-8')
+    // Textual, not parse-and-restringify: the config is hand-edited and carries
+    // comments and ordering a JSON round-trip would silently discard.
+    fs.writeFileSync(file, raw.replace(/("teamKey"\s*:\s*")([^"]*)(")/, `$1${drift.config.to}$3`), 'utf-8')
+    changed.config = true
+  }
+
+  return changed
+}
+
+module.exports = {
+  scanDrift,
+  isClean,
+  fileCount,
+  retarget,
+  specMarkdownFiles,
+  dirtyPaths,
+  repairDrift,
+  rewriteFrontmatter,
+}

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

@@ -71,7 +71,9 @@ function snapshotOf(projection) {
 /**
  * Diff the local projection against the last-pushed snapshot.
  * @returns {{ issue?: object, subIssues: {create,update} }}
- *   create items carry a `ref` (local handle) and no id; update items carry `id`.
+ *   create items carry a `ref` (local handle) and no id; update items carry both
+ *   — the `ref` because the read-back check matches sub-issues to phases BY ref,
+ *   and an update with only an id makes every one of them look unmatched.
  *   `plan.issue` (when present) is the spec issue's description + state; the push
  *   skill applies `config.linear.projectId` grouping on top of it.
  */
@@ -85,7 +87,7 @@ function planChanges(projection, snapshot) {
     if (s.id == null) {
       subIssues.create.push({ ref: s.ref, name: s.name, goal: s.goal, state: s.state })
     } else if (snapS[String(s.id)] !== subIssueHash(s)) {
-      subIssues.update.push({ id: s.id, name: s.name, goal: s.goal, state: s.state })
+      subIssues.update.push({ ref: s.ref, id: s.id, name: s.name, goal: s.goal, state: s.state })
     }
   }