@skitterbyte/skitterspec-linear 10.4.0 → 10.5.0

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

@@ -42,11 +42,16 @@ const {
   stampSubIssueId,
   listPhaseFiles,
   compareStored,
+  planRetarget,
+  applyRetarget,
+  deriveRecordedKey,
+  isEmptyRetarget,
+  dirtyPaths,
 } = require('../sync-core')
 
 const { loadLinearConfig, mergeConfig, defaults: configDefaults, CONFIG_FILE, LIFECYCLE_BUCKETS } = require('./config.js')
 const { resolveApiKey, makeApiAdapter, stateIdFor, fetchWorkspaceStates } = require('./api.js')
-const { scanDrift, isClean, fileCount, dirtyPaths, repairDrift } = require('./doctor.js')
+const { runChecks } = require('./doctor.js')
 const {
   storePath,
   storeMode,
@@ -580,157 +585,370 @@ function verifyLines(snapshotDir, config, stored, identifier) {
 }
 
 /**
- * `spec-sync doctor [--json]` — identifier drift against the team's CURRENT key.
+ * `spec-sync doctor [--json]` — is this project set up, across every layer?
  *
- * A Linear team rename leaves every stamped identifier, the config `teamKey` and
- * every snapshot filename on the old prefix, and nothing noticed. This reports
- * it. Read-only: exit 0 whether or not it finds drift; non-zero only when it
- * could not look (no key, MCP, unreadable team).
+ * The scaffold, isolation, the tracker config and the key are each checked by a
+ * different command or by none, so nothing answered the whole question. This
+ * does, and every failing row names the command that fixes it.
  *
- * Two things it deliberately does NOT do:
+ * The report itself is `doctor.js`, which is pure — this half only GATHERS. It
+ * is the one place allowed to touch the filesystem for that, and it must not
+ * throw doing it: a doctor that dies on a malformed config is useless on exactly
+ * the repo that needs it. So every read is wrapped, and a parse failure becomes
+ * a `broken` row rather than a stack trace.
  *
- * 1. It does not trust `config.linear.teamKey` for the current key — that value
- *    is itself one of the things that goes stale, so trusting it would make the
- *    drift invisible. `teamId` survives a rename; the key does not.
- * 2. It does not resolve refs with a bulk `team.issues` query. That connection
- *    excludes archived issues AND caps at 250 per page, so the naive version
- *    reports most of a healthy repo as missing — measured on a real workspace:
- *    328 issues, 149 archived, and the unpaginated default returns 179. Reading
- *    each ref individually has no list to page and no archived flag to forget;
- *    `issue(id:)` resolves an archived issue by identifier (also verified).
+ * Dispatched BEFORE the config load for the same reason (like `init-config`):
+ * the loader throws on malformed JSON and the dispatcher short-circuits when no
+ * config exists, so a doctor sitting after it could never report the two states
+ * it most needs to.
  */
-async function specSyncDoctor(dir, config, flags, out) {
+async function specSyncDoctor(dir, flags, out) {
+  const state = gatherState(dir, flags)
+  if (flags.remoteCheck) state.remote = await checkRemote(state, flags)
+
+  const report = runChecks(state)
+
+  if (flags.json) {
+    out.write(JSON.stringify(report, null, 2) + '\n')
+    return report.ok ? 0 : 1
+  }
+
+  const width = Math.max(...report.checks.map((c) => c.label.length))
+  const lines = ['skitterspec doctor:']
+  for (const c of report.checks) {
+    lines.push(`  ${c.label.padEnd(width)}  ${c.state.padEnd(8)} ${c.detail}`)
+    // The fix sits under the row it belongs to, indented past the state column,
+    // so a wall of rows still reads as "this one, and here is the command".
+    if (c.fix) lines.push(`  ${' '.repeat(width)}  ${' '.repeat(8)} → ${c.fix}`)
+  }
+  // Everything not `ok`/`skipped` needs a human's attention — including a
+  // `missing` one, which is why the count and the EXIT CODE differ: a declined
+  // opt-in is worth reporting but must not fail the run (see `runChecks`).
+  const attention = report.checks.filter((c) => c.state === 'broken' || c.state === 'missing').length
+  lines.push('')
+  lines.push(attention ? `  ${attention} check(s) need attention.` : '  ready.')
+
+  out.write(lines.join('\n') + '\n')
+  return report.ok ? 0 : 1
+}
+
+/**
+ * The live half of the report: one `team(id:)` call proving the id resolves and
+ * the key is accepted. Well-formed config is not working config.
+ *
+ * Opt-in because it is the only part that needs the network — the offline checks
+ * have to stay usable with no connectivity, which is exactly when a setup
+ * problem is most annoying to diagnose.
+ *
+ * **No API message is ever relayed.** A GraphQL error body can echo the request
+ * back, and this is a command a skill prints; so a failure is CLASSIFIED into a
+ * short reason of our own words.
+ */
+async function checkRemote(state, flags) {
+  if (!state.tracker.parsed || !state.tracker.teamId) {
+    return { checked: true, skipped: true, reason: 'no usable tracker config to check against' }
+  }
+  if (!state.key.ok) {
+    return { checked: true, skipped: true, reason: 'no key, so there is nothing to check with' }
+  }
+
+  const key = resolveApiKey(state._config, flags.env || process.env)
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  let team
+  try {
+    team = await adapter.readTeam(state.tracker.teamId)
+  } catch (error) {
+    const failure = classifyRemoteFailure(error)
+    // NEVER ANSWERED is not the same as ANSWERED NO. An unreachable API or a
+    // rate-limit means the check did not run — the setup is unexamined, not
+    // wrong — so it reports `skipped`, the same state as "you didn't ask for
+    // it". Calling it `broken` exited 1 on a healthy project that merely had no
+    // network, and every skill branching on that code failed with it.
+    if (failure.reached === false) return { checked: true, skipped: true, reason: failure.reason }
+    return { checked: true, ok: false, ...failure }
+  }
+  if (!team || !team.key) {
+    return {
+      checked: true,
+      ok: false,
+      reason: 'the key was accepted, but no team has that id',
+      fix: '/spec-linear-setup',
+    }
+  }
+  return { checked: true, ok: true, teamKey: team.key, recordedKey: state.tracker.teamKey }
+}
+
+// Map a thrown API error onto our own short reason. Matched on the shapes
+// `api.js` raises; anything unrecognised degrades to a generic line rather than
+// leaking the message.
+//
+// BLIND SPOT: matching on message text, so an api.js rewording lands here as the
+// unrecognised case. That is why the fallback stays `broken` — Linear ANSWERED
+// and refused, which is evidence of a problem even when we cannot name it. Only
+// a request that got no answer at all (`reached: false`) is un-evidence.
+function classifyRemoteFailure(error) {
+  const m = String((error && error.message) || '')
+  if (/rejected the API key|HTTP 401|HTTP 403/.test(m)) {
+    return { reason: 'Linear rejected the key — it may be revoked or for another workspace', fix: 'skitterspec spec-sync credentials set' }
+  }
+  // `reached: false` — the request never got an answer, so it says nothing about
+  // whether this project is set up correctly. See the caller.
+  if (/unreachable/.test(m)) {
+    return { reason: 'Linear could not be reached — check your connection', fix: null, reached: false }
+  }
+  if (/rate-limited/.test(m)) {
+    return { reason: 'Linear rate-limited the request and did not recover', fix: null, reached: false }
+  }
+  if (/Entity not found|not found/i.test(m)) {
+    return { reason: 'no team with that id in this workspace', fix: '/spec-linear-setup' }
+  }
+  return { reason: 'Linear did not accept the request', fix: null }
+}
+
+// Read the project's real state for `runChecks`. Never throws: every probe that
+// can fail reports the failure as data.
+function gatherState(dir, flags) {
+  const state = { scaffold: {}, isolation: {}, tracker: {}, key: {}, remote: { checked: false } }
+
+  const specs = path.join(dir, 'specs')
+  state.scaffold.specsDir = fs.existsSync(specs)
+  if (state.scaffold.specsDir) {
+    state.scaffold.core = fs.existsSync(path.join(specs, '.core'))
+    // Reported for context only — a missing bucket is normal (see scaffoldCheck).
+    state.scaffold.buckets = BUCKETS.filter((b) => fs.existsSync(path.join(specs, b)))
+    state.scaffold.skills = countSkills(dir)
+  }
+
+  const envFile = path.join(dir, 'specs', '.core', 'env.config.json')
+  state.isolation.present = fs.existsSync(envFile)
+  if (state.isolation.present) {
+    try {
+      JSON.parse(fs.readFileSync(envFile, 'utf-8'))
+      state.isolation.parsed = true
+    } catch (error) {
+      state.isolation.parsed = false
+      state.isolation.error = error.message
+    }
+  }
+
+  state.tracker.present = fs.existsSync(path.join(dir, CONFIG_FILE))
+  let config = null
+  if (state.tracker.present) {
+    try {
+      config = loadLinearConfig(dir).config
+      state.tracker.parsed = true
+      state.tracker.teamId = (config.linear && config.linear.teamId) || ''
+      state.tracker.teamKey = (config.linear && config.linear.teamKey) || ''
+    } catch (error) {
+      state.tracker.parsed = false
+      state.tracker.error = error.message
+    }
+  }
+
+  // Without a parsed config there is no `auth.keyEnv` and no team to key on, so
+  // there is nothing to look up — the key row reports as skipped instead.
+  if (config) {
+    const resolved = resolveApiKey(config, flags.env || process.env)
+    // A key resolves from the environment, the store, or a `keyCommand` the
+    // store runs — `resolveApiKey` covers all three, so the row must not be read
+    // as "env var unset".
+    //
+    // When it does NOT resolve, `resolveApiKey` appends the reason on later
+    // lines: a store that is world-readable, or a keyCommand that failed.
+    // Dropping it reported a broken command as `no key for SKS` and sent the
+    // user to set a key they had already set (`credentials status` keeps it for
+    // the same reason).
+    const why = resolved.ok ? '' : resolved.error.split('\n').slice(1).map((l) => l.trim()).filter(Boolean).join('; ')
+    state.key = resolved.ok
+      ? { ok: true, source: resolved.source === 'env' ? `the environment (${resolved.envVar})` : resolved.source, fingerprint: fingerprint(resolved.key) }
+      : { ok: false, error: `no key for ${state.tracker.teamKey || state.tracker.teamId}${why ? ` — ${why}` : ''}` }
+  }
+
+  state._config = config
+  return state
+}
+
+// How many skills are installed in the target project.
+function countSkills(dir) {
+  const skills = path.join(dir, '.claude', 'skills')
+  try {
+    return fs
+      .readdirSync(skills, { withFileTypes: true })
+      .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && fs.existsSync(path.join(skills, e.name, 'SKILL.md')))
+      .length
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * `spec-sync retarget [--yes]` — repoint a mirror after a team-key rename.
+ *
+ * Renaming a Linear team rewrites the key in every issue identifier, and the
+ * repo stamps those in three places. Nothing moved them, so afterwards
+ * `/spec-push` fails with `no Linear issue found for SKI-7` — the right failure,
+ * with no way out but a hand rewrite (done twice by hand on 2026-09-02).
+ *
+ * The rewrite itself is provider-neutral and lives in `sync-core/retarget.js`.
+ * Only two things here touch Linear:
+ *
+ * 1. **Detection.** `teamId` survives a rename, so ask Linear for that team's
+ *    CURRENT key and compare it with the recorded one. A difference IS the
+ *    rename. It is never taken as an argument: nothing stops a typo rewriting
+ *    every stamp to a key that does not exist.
+ * 2. **One spot-check.** Resolve the first remapped identifier and compare its
+ *    TITLE to the spec's. That is what makes the number-preservation assumption
+ *    safe, and it tests identity rather than mere existence — `SKS-7` existing
+ *    does not make it the issue that was `SKI-7`. One read, which is also what
+ *    keeps the MCP path viable.
+ */
+async function specSyncRetarget(dir, config, flags, out) {
+  const teamId = (config.linear && config.linear.teamId) || ''
+  if (!teamId) {
+    out.write('spec-sync retarget: no linear.teamId in specs/.core/linear.config.json — nothing to compare against.\n')
+    return 1
+  }
+
+  const recorded = deriveRecordedKey(dir, config)
+  if (!recorded.key) {
+    out.write(`spec-sync retarget: cannot tell which key this repo is stamped with.\n  ${recorded.reason}\n`)
+    return 1
+  }
+
   const key = resolveApiKey(config, flags.env || process.env)
   const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
 
-  // One read PER DRIFTED REF is the whole design; over MCP that is a model
-  // round-trip each, which is impractical at the scale this exists for (198 refs
-  // in the run that motivated it). Refused rather than quietly slow — the same
-  // call `apply --all` makes.
+  // Linear's MCP `get_team` does not return the team key (observed 2026-09-02),
+  // so the one fact detection needs is unavailable there. Report what IS known
+  // and let the operator supply it, rather than guessing or silently skipping.
   if (transport === 'mcp') {
     out.write(
       [
-        'spec-sync doctor: needs the api transport (nothing was read)',
+        'spec-sync retarget: transport = mcp — cannot read the team key (nothing was changed)',
         `  ${key.ok ? '--via mcp was requested' : key.error}`,
-        '  it reads one issue per drifted ref, which MCP would route through the model.',
+        `  recorded key: ${recorded.key} (from ${recorded.source})`,
+        "  Linear's MCP get_team does not return a team key, so a rename cannot be detected here.",
+        '  Confirm the current key in Linear, then set an API key and re-run for the plan.',
       ].join('\n') + '\n',
     )
     return 1
   }
 
-  const teamId = (config.linear && config.linear.teamId) || ''
-  if (!teamId) {
-    out.write('spec-sync doctor: no linear.teamId in specs/.core/linear.config.json — nothing to compare against.\n')
-    return 1
-  }
-
   const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
   let team
   try {
     team = await adapter.readTeam(teamId)
   } catch (error) {
-    out.write(`spec-sync doctor: could not read the team: ${error.message}\n`)
+    out.write(`spec-sync retarget: could not read the team: ${error.message}\n`)
     return 1
   }
   if (!team || !team.key) {
-    out.write(`spec-sync doctor: Linear returned no team for ${teamId}\n`)
+    out.write(`spec-sync retarget: Linear returned no team for ${teamId}\n`)
     return 1
   }
 
-  const drift = scanDrift(dir, config, team.key)
-
-  // Only the DISTINCT drifted identifiers are checked, so 221 stamps of 198
-  // identifiers cost 198 reads.
-  const missing = []
-  for (const ref of drift.refs) {
-    let got
-    try {
-      got = await adapter.readIssue(ref.to)
-    } catch (error) {
-      out.write(`spec-sync doctor: could not read ${ref.to}: ${error.message}\n`)
-      return 1
-    }
-    if (!got) missing.push(ref)
-  }
+  const header = [
+    `spec-sync retarget: team ${teamId} (${team.name || team.key})`,
+    `  recorded key: ${recorded.key}  (from ${recorded.source})`,
+    `  linear  key:  ${team.key}${team.key === recorded.key ? '' : '   <- renamed'}`,
+  ]
 
-  if (flags.json) {
-    out.write(JSON.stringify({ team: { id: team.id, key: team.key, name: team.name }, ...drift, missing }, null, 2) + '\n')
+  if (team.key === recorded.key) {
+    out.write([...header, '', '  already current — nothing to retarget'].join('\n') + '\n')
     return 0
   }
 
-  const was = [...new Set(drift.refs.map((r) => r.from.split('-')[0]))]
-  const lines = [`spec-sync doctor: team ${team.key}${was.length ? ` (stamps still on ${was.join(', ')})` : ''}`]
-  if (isClean(drift)) {
-    lines.push('  drift:   none — every stamped identifier is on the current team key')
-    out.write(lines.join('\n') + '\n')
+  const plan = planRetarget({ dir, oldKey: recorded.key, newKey: team.key, config })
+  if (isEmptyRetarget(plan)) {
+    out.write([...header, '', '  the key moved, but nothing in the repo is stamped with it'].join('\n') + '\n')
     return 0
   }
 
-  const driftLines = []
-  const stamped = drift.stamps.length + drift.urls.length
-  if (stamped) driftLines.push(`${stamped} stamp(s) across ${fileCount(drift)} file(s), ${drift.refs.length} distinct ref(s)`)
-  if (drift.snapshots.length || drift.snapshotKeys.length) {
-    const parts = []
-    if (drift.snapshots.length) parts.push(`${drift.snapshots.length} filename(s)`)
-    if (drift.snapshotKeys.length) parts.push(`${drift.snapshotKeys.length} sub-issue key(s)`)
-    driftLines.push(`snapshots: ${parts.join(' + ')} under ${config.sync.baseDir}`)
-  }
-  if (drift.config) driftLines.push(`config linear.teamKey = "${drift.config.from}"`)
-  lines.push(`  drift:   ${driftLines[0]}`)
-  for (const l of driftLines.slice(1)) lines.push(`           ${l}`)
-
-  // Reported SEPARATELY from drift: a ref that resolves is repairable, one that
-  // does not is a different problem and must not be silently rewritten.
-  // Prose mentions are NOT repaired, so they are reported outside the drift
-  // block — a report that folded them in would imply --write fixes them.
-  if (drift.mentions.length) {
-    lines.push(
-      `  mentions: ${drift.mentions.length} stale ref(s) in spec prose — reported, NOT repaired by --write`,
-    )
+  // Spot-check BEFORE reporting the plan as safe: a wrong mapping is caught
+  // here, not after the files have moved.
+  const check = await spotCheck({ dir, config, plan, adapter, oldKey: recorded.key, newKey: team.key })
+  const lines = [
+    ...header,
+    '',
+    '  would rewrite:',
+    `    ${plan.stamps.length} frontmatter stamp(s)  (linear_identifier, linear_url, linear_issue_id)`,
+    `    ${plan.snapshots.length} base snapshot(s)      (rename + re-key subIssues)`,
+    `    ${plan.configKey ? 1 : 0} config key            (linear.teamKey)`,
+    '',
+    `  spot-check: ${check.line}`,
+  ]
+
+  if (!check.ok) {
+    lines.push('  refusing — the mapping is not safe to apply')
+    out.write(lines.join('\n') + '\n')
+    return 1
   }
-  lines.push(`  missing: ${missing.length} ref(s) that resolve to no issue under ${team.key}`)
-  for (const m of missing.slice(0, 10)) lines.push(`           ${m.from} → ${m.to} does not exist`)
-  if (missing.length > 10) lines.push(`           … and ${missing.length - 10} more`)
 
-  if (!flags.write) {
-    lines.push('  run with --write to repair (requires a clean git tree)')
+  if (!flags.yes) {
+    lines.push('  dry-run — re-run with --yes to apply.')
     out.write(lines.join('\n') + '\n')
     return 0
   }
 
-  // A repair rewrites hundreds of stamps across dozens of files. That is only
-  // safe to hand someone if it arrives as ONE reviewable diff they can throw
-  // away with `git checkout -- .` — which a dirty tree destroys. Same guard
-  // `spec-env integrate` uses, and for the same reason.
   const dirty = dirtyPaths(dir)
   if (dirty === null) {
-    lines.push('  --write refused: not a git repository, so the rewrite would not be reviewable')
+    lines.push('  --yes refused: not a git repository, so the rewrite would not be reviewable')
     out.write(lines.join('\n') + '\n')
     return 1
   }
   if (dirty.length) {
-    lines.push(`  --write refused: ${dirty.length} uncommitted change(s) — commit or stash first`)
+    lines.push(`  --yes refused: ${dirty.length} uncommitted change(s) — commit or stash first`)
     for (const d of dirty.slice(0, 10)) lines.push(`           ${d}`)
     if (dirty.length > 10) lines.push(`           … and ${dirty.length - 10} more`)
-    lines.push('           the repair is one large diff; it must be reviewable on its own')
+    lines.push('           the rewrite must land as one reviewable, revertable change')
     out.write(lines.join('\n') + '\n')
     return 1
   }
 
-  const skip = new Set(missing.map((m) => m.from))
-  const changed = repairDrift(dir, config, drift, { skip })
-  lines.push('  repaired:')
-  lines.push(`           ${changed.files.length} spec file(s)`)
-  lines.push(`           ${changed.snapshots.length} snapshot file(s) moved`)
-  if (changed.config) lines.push('           config linear.teamKey')
-  if (changed.skipped) {
-    lines.push(`           ${changed.skipped} ref(s) LEFT ALONE — they resolve to no issue under ${team.key}`)
-  }
-  lines.push('  review the diff, then commit it')
+  const changed = applyRetarget(plan, { dir, config })
+  lines.push(
+    '  applied:',
+    `    ${changed.files.length} spec file(s)`,
+    `    ${changed.snapshots.length} snapshot(s) moved`,
+    ...(changed.configKey ? ['    config linear.teamKey'] : []),
+    "  nothing was pushed — only the repo's stamps moved; the mirror is untouched.",
+    '  review the diff, then commit it.',
+  )
   out.write(lines.join('\n') + '\n')
-  // Non-zero when anything was left behind, so a caller cannot read a partial
-  // repair as a complete one.
-  return changed.skipped ? 1 : 0
+  return 0
+}
+
+/**
+ * Resolve the first remapped SPEC issue and compare its title to the spec's.
+ *
+ * Deliberately ONE read. Checking every ref instead would cost a request each
+ * (~198 on a real repo), force an MCP refusal, and still only prove the issues
+ * exist — not that they are the same issues.
+ */
+async function spotCheck({ dir, config, plan, adapter, oldKey, newKey }) {
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const stamp = plan.stamps.find((s) => path.basename(s.file) === overviewFile)
+  if (!stamp) return { ok: true, line: 'skipped — no spec issue in the plan to check' }
+
+  const before = parseFrontmatter(stamp.from).data.linear_identifier
+  if (!before) return { ok: true, line: 'skipped — no linear_identifier in the plan to check' }
+  const from = String(before).trim()
+  const to = `${newKey}-${from.slice(oldKey.length + 1)}`
+
+  let issue
+  try {
+    issue = await adapter.readIssue(to)
+  } catch (error) {
+    return { ok: false, line: `${to} could not be read — ${error.message}` }
+  }
+  if (!issue) return { ok: false, line: `${from} → ${to}, but ${to} does not exist in Linear` }
+
+  const expected = readSnapshot(path.dirname(path.join(dir, stamp.file)), config).title
+  const got = issue.title || ''
+  if (expected && got && expected.trim() !== got.trim()) {
+    return { ok: false, line: `${to} resolves, but its title is "${got}" — the spec's is "${expected}"` }
+  }
+  return { ok: true, line: `${to} resolves, title matches the spec` }
 }
 
 /**
@@ -1582,8 +1800,12 @@ async function specSync(rest, io = {}) {
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
+  // Anything `--`-prefixed that no branch below consumed. Collected rather than
+  // pushed onto `positional`, where it was silently discarded — see the refusal
+  // after the loop.
+  const unknownFlags = []
   const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null, plan: null, via: null, project: null, all: null,
-    force: false, write: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
+    force: false, yes: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
   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
@@ -1599,7 +1821,8 @@ async function specSync(rest, io = {}) {
     else if (args[i] === '--url') flags.url = args[++i]
     else if (args[i] === '--sub') flags.subs.push(args[++i])
     else if (args[i] === '--force') flags.force = true
-    else if (args[i] === '--write') flags.write = true
+    else if (args[i] === '--yes') flags.yes = true
+    else if (args[i] === '--check-remote') flags.remoteCheck = true
     else if (args[i] === '--stdin') flags.stdin = true
     else if (args[i] === '--command') flags.command = String(args[++i] || '').trim()
     else if (args[i] === '--key') {
@@ -1622,8 +1845,34 @@ async function specSync(rest, io = {}) {
       const [bucket, ...rest] = String(args[++i] || '').split('=')
       flags.stateNames[String(bucket).trim()] = rest.join('=').trim()
     } else if (args[i] === '--states') flags.statesFile = path.resolve(args[++i])
+    else if (args[i].startsWith('--')) unknownFlags.push(args[i])
     else positional.push(args[i])
   }
+  // REFUSE AN UNKNOWN FLAG, before anything runs.
+  //
+  // These used to land in `positional` and vanish. That is merely untidy for a
+  // typo, but it turned a RENAMED flag into a silent no-op: `--write` moved to
+  // `--yes` when `doctor` became `retarget`, so `spec-sync doctor --write` — the
+  // exact 10.4.0 invocation for repairing a renamed team — parsed, ran the
+  // readiness report instead, ignored the flag and exited 0. A script would read
+  // that as "repaired".
+  //
+  // A spec name never starts with `--`, so this cannot swallow a real argument.
+  if (unknownFlags.length) {
+    const lines = [`spec-sync: unknown flag ${unknownFlags.join(', ')}`]
+    // Renamed flags get a specific hand-off; a bare "unknown flag" would leave
+    // the caller to guess what replaced it.
+    if (unknownFlags.includes('--write')) {
+      lines.push(
+        '  --write was replaced by --yes, and the command that repairs a renamed',
+        '  team is now `spec-sync retarget --yes` (it was `doctor --write`).',
+      )
+    }
+    lines.push('  run `skitterspec spec-sync` for the full usage.')
+    out.write(lines.join('\n') + '\n')
+    return 1
+  }
+
   dir = path.resolve(dir)
   // Injection seam, alongside cwd/out/err: `env` supplies the key lookup and
   // `adapter`/`fetch` stand in for the network, so `apply` is exercised end to
@@ -1637,6 +1886,11 @@ async function specSync(rest, io = {}) {
   // malformed enough for the loader to throw on.
   if (sub === 'init-config') return specSyncInitConfig(dir, flags, out)
 
+  // Same reason as init-config: this is the command you run when the config is
+  // missing or malformed, so it must not sit behind a loader that throws on the
+  // one and short-circuits on the other.
+  if (sub === 'doctor') return await specSyncDoctor(dir, flags, out)
+
   const { config, present } = loadLinearConfig(dir)
   if (!present) {
     out.write(
@@ -1661,8 +1915,8 @@ async function specSync(rest, io = {}) {
       return (await specSyncProjects(dir, config, flags, out)) || 0
     case 'states':
       return (await specSyncStates(dir, config, flags, out)) || 0
-    case 'doctor':
-      return (await specSyncDoctor(dir, config, flags, out)) || 0
+    case 'retarget':
+      return (await specSyncRetarget(dir, config, flags, out)) || 0
     case 'apply':
       return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
     case 'verify':
@@ -1683,7 +1937,8 @@ async function specSync(rest, io = {}) {
         '       skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
         '       skitterspec spec-sync verify <spec> --stored <file>\n' +
         '       skitterspec spec-sync linked [--json]\n' +
-        '       skitterspec spec-sync doctor [--write] [--json]\n' +
+        '       skitterspec spec-sync retarget [--yes]\n' +
+        '       skitterspec spec-sync doctor [--check-remote] [--json]\n' +
         '       skitterspec spec-sync init-config --team-id <id> [--team-key K] [--project-id id]\n' +
         '                    [--intake-label L] [--bug-labels a,b] [--hotfix-labels a,b]\n' +
         '                    [--state <bucket>=<name> …] [--states <file>] [--force] [--json]\n')