@skitterbyte/skitterspec-linear 10.3.0 → 10.5.0

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

@@ -42,10 +42,24 @@ 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 { runChecks } = require('./doctor.js')
+const {
+  storePath,
+  storeMode,
+  fingerprint,
+  writeKey,
+  writeKeyCommand,
+  removeKey,
+} = require('./credentials.js')
 
 // Resolve a spec argument to its snapshot dir. Accepts a spec name/folder found
 // under specs/** (preferred) or a literal path to a snapshot directory.
@@ -494,6 +508,26 @@ function specSyncVerify(dir, config, specArg, flags, out) {
     )
     return 1
   }
+  // A `.base.json` is the LAST-PUSHED SNAPSHOT, not a read-back: it stores
+  // content HASHES keyed by identifier, never description text. Passed as
+  // `--stored` it parses fine and compares a description against a hash, so the
+  // report is confidently, entirely wrong — a real field run read "5045
+  // character(s) lost" off an intact mirror. Refused here rather than only
+  // documented, because a guard is enforceable and prose is not.
+  const snapshotRoot = path.resolve(dir, config.sync.baseDir)
+  const isSnapshot =
+    flags.stored.endsWith('.base.json') || !path.relative(snapshotRoot, flags.stored).startsWith('..')
+  if (isSnapshot) {
+    out.write(
+      `spec-sync verify: ${path.relative(dir, flags.stored)} is a last-pushed snapshot, not a read-back.\n` +
+        '  It holds content hashes keyed by identifier — comparing one against a\n' +
+        '  description reports enormous bogus losses on a perfectly intact mirror.\n' +
+        '  --stored wants what the tracker CURRENTLY holds:\n' +
+        '    {"issue": "…", "subIssues": {"<ref>": "…"}}\n' +
+        '  /spec-push reads that back over MCP and writes it for this command.\n',
+    )
+    return 1
+  }
   let stored
   try {
     stored = JSON.parse(fs.readFileSync(flags.stored, 'utf-8'))
@@ -550,6 +584,373 @@ function verifyLines(snapshotDir, config, stored, identifier) {
   return lines
 }
 
+/**
+ * `spec-sync doctor [--json]` — is this project set up, across every layer?
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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, 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')
+
+  // 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 retarget: transport = mcp — cannot read the team key (nothing was changed)',
+        `  ${key.ok ? '--via mcp was requested' : key.error}`,
+        `  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 adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  let team
+  try {
+    team = await adapter.readTeam(teamId)
+  } catch (error) {
+    out.write(`spec-sync retarget: could not read the team: ${error.message}\n`)
+    return 1
+  }
+  if (!team || !team.key) {
+    out.write(`spec-sync retarget: Linear returned no team for ${teamId}\n`)
+    return 1
+  }
+
+  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 (team.key === recorded.key) {
+    out.write([...header, '', '  already current — nothing to retarget'].join('\n') + '\n')
+    return 0
+  }
+
+  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
+  }
+
+  // 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
+  }
+
+  if (!flags.yes) {
+    lines.push('  dry-run — re-run with --yes to apply.')
+    out.write(lines.join('\n') + '\n')
+    return 0
+  }
+
+  const dirty = dirtyPaths(dir)
+  if (dirty === null) {
+    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(`  --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 rewrite must land as one reviewable, revertable change')
+    out.write(lines.join('\n') + '\n')
+    return 1
+  }
+
+  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')
+  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` }
+}
+
 /**
  * `spec-sync states [--json]` — which transport this repo will use, and on the
  * API path the workspace's issue state NAMES.
@@ -746,13 +1147,22 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
   }
 
   // 3. Sub-issue updates — already linked, nothing to stamp.
+  //
+  // Keyed by REF, never by id: step 4 matches the read-back against the
+  // projection, which keys phases by ref. Keying an update by its id made every
+  // updated sub-issue report as a stale ref on every push. A plan written before
+  // updates carried a ref still resolves — by id, off the projection.
+  const refById = new Map()
+  for (const s of projectionOf(snapshotDir, config).subIssues || []) {
+    if (s.id != null) refById.set(String(s.id), s.ref)
+  }
   for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
     await adapter.updateIssue(sub.id, withoutNull({
       title: sub.name,
       description: sub.goal,
       stateId: stateId(sub.state),
     }))
-    result.subIssues[sub.ref || sub.id] = sub.id
+    result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
     lines.push(`  sub-issue updated: ${sub.id}`)
   }
 
@@ -1173,14 +1583,229 @@ function withoutNull(obj) {
   return out
 }
 
+// --- credentials -------------------------------------------------------------
+
+/**
+ * `spec-sync credentials <status|set|unset>` — manage the user-level API key.
+ *
+ * The split here is deliberate and is the whole point of the feature:
+ *
+ *   `status`  is SAFE FOR A SKILL TO RUN. It reports readiness and never the
+ *             value — path, mode, team, and a masked fingerprint.
+ *   `set`     is for a HUMAN, run outside the model. It reads the key from a TTY
+ *             with echo off (or `--stdin`), never from argv.
+ *
+ * A key typed into a chat enters the transcript, is sent to the model and may be
+ * logged; moving where a key is STORED is worthless if it travels through the
+ * conversation to get there. So nothing in this file ever prints a key, and
+ * `--key <value>` is refused rather than supported.
+ */
+async function specSyncCredentials(dir, config, action, flags, out) {
+  const env = flags.env || process.env
+  const file = storePath(env)
+  const teamId = (config.linear && config.linear.teamId) || ''
+  const teamKey = (config.linear && config.linear.teamKey) || ''
+  const label = teamKey ? `${teamId} (${teamKey})` : teamId
+
+  if (!teamId) {
+    out.write(
+      'spec-sync credentials: no linear.teamId in specs/.core/linear.config.json.\n' +
+        '  The store is keyed by team — run `spec-sync init-config` first.\n',
+    )
+    return 1
+  }
+
+  if (action === 'status' || !action) return credentialsStatus(dir, config, file, label, flags, out)
+  if (action === 'set') return credentialsSet(file, teamId, label, flags, out)
+  if (action === 'unset') return credentialsUnset(file, teamId, label, out)
+
+  out.write('Usage: skitterspec spec-sync credentials <status|set|unset> [--stdin] [--json]\n')
+  return 1
+}
+
+// Readiness only — the command a skill runs. Never prints the key.
+function credentialsStatus(dir, config, file, label, flags, out) {
+  const resolved = resolveApiKey(config, flags.env || process.env)
+  const mode = storeMode(file)
+  const present = resolved.ok
+  const payload = {
+    store: file,
+    mode,
+    team: label,
+    key: present ? { present: true, source: resolved.source, fingerprint: fingerprint(resolved.key) } : { present: false },
+  }
+  if (flags.json) {
+    out.write(JSON.stringify(payload, null, 2) + '\n')
+    return present ? 0 : 1
+  }
+
+  const lines = ['spec-sync credentials:']
+  const strayed = repoConfigKeyCommand(dir)
+  if (strayed) {
+    lines.push(
+      '  note:   a keyCommand in specs/.core/linear.config.json is IGNORED.',
+      '          That file is committed, so a command there would run on the',
+      '          machine of anyone who cloned the repo. Record it here instead:',
+      '            skitterspec spec-sync credentials set --command <cmd>',
+    )
+  }
+  lines.push(`  store:  ${file}${mode ? ` (${mode})` : ' (not created yet)'}`)
+  lines.push(`  team:   ${label}`)
+  if (present) {
+    const where =
+      resolved.source === 'env'
+        ? `environment (${resolved.envVar})`
+        : resolved.source === 'command'
+          ? 'keyCommand'
+          : 'store'
+    lines.push(`  key:    set — ${fingerprint(resolved.key)} from the ${where}`)
+    if (resolved.command) lines.push(`  runs:   ${resolved.command}`)
+  } else {
+    lines.push('  key:    not set')
+    // `resolveApiKey` appends a reason when the store or its keyCommand is
+    // broken rather than merely absent. Dropping it here would report a failing
+    // command as "you never set a key" and send the user to set it again.
+    for (const detail of resolved.error.split('\n').slice(1)) {
+      if (detail.trim()) lines.push(`  problem:${detail.replace(/^ +/, ' ')}`)
+    }
+    lines.push('')
+    lines.push('  Run this yourself, in your own terminal — not through an assistant:')
+    lines.push('    skitterspec spec-sync credentials set')
+  }
+  out.write(lines.join('\n') + '\n')
+  return present ? 0 : 1
+}
+
+// The human-facing setter. TTY prompt with echo off, or `--stdin` for a pipe.
+async function credentialsSet(file, teamId, label, flags, out) {
+  if (flags.keyArgGiven) {
+    out.write(
+      'spec-sync credentials: --key is not supported, on purpose.\n' +
+        '  A secret in the command line is visible in shell history and to `ps`.\n' +
+        '  Run `credentials set` with no arguments and paste at the prompt (input\n' +
+        '  is hidden), or pipe it: `… | credentials set --stdin`.\n',
+    )
+    return 1
+  }
+
+  // A command is not a secret — it names WHERE the key lives, so unlike --key it
+  // is safe on the command line and nothing is prompted for.
+  if (flags.command) {
+    const r = writeKeyCommand(file, teamId, flags.command)
+    if (!r.ok) {
+      out.write(`spec-sync credentials: ${r.reason}\n`)
+      return 1
+    }
+    out.write(
+      `spec-sync credentials: ${label} will resolve its key by running:\n` +
+        `  ${flags.command}\n` +
+        `  recorded in ${r.path} (600)\n`,
+    )
+    return 0
+  }
+
+  let key
+  if (flags.stdin) {
+    key = (await readAllStdin(flags.input || process.stdin)).trim()
+    if (!key) {
+      out.write('spec-sync credentials: nothing on stdin — no key stored.\n')
+      return 1
+    }
+  } else {
+    const input = flags.input || process.stdin
+    if (!input.isTTY) {
+      out.write(
+        'spec-sync credentials: not a terminal — cannot prompt for a key.\n' +
+          '  Run it in your own terminal, or pipe the key with --stdin.\n',
+      )
+      return 1
+    }
+    key = (await promptHidden(`Linear personal API key for ${label} (hidden): `, input, out)).trim()
+    if (!key) {
+      out.write('spec-sync credentials: empty input — no key stored.\n')
+      return 1
+    }
+  }
+
+  const r = writeKey(file, teamId, key)
+  if (!r.ok) {
+    out.write(`spec-sync credentials: ${r.reason}\n`)
+    return 1
+  }
+  out.write(`spec-sync credentials: key stored for ${label} in ${r.path} (600)\n`)
+  return 0
+}
+
+function credentialsUnset(file, teamId, label, out) {
+  const r = removeKey(file, teamId)
+  if (!r.ok) {
+    out.write(`spec-sync credentials: ${r.reason}\n`)
+    return 1
+  }
+  out.write(
+    r.removed
+      ? `spec-sync credentials: removed the key for ${label} from ${r.path}\n`
+      : `spec-sync credentials: no key stored for ${label} — nothing to remove\n`,
+  )
+  return 0
+}
+
+// Is a keyCommand set in the REPO's committed config? It is never honoured — the
+// loader drops unknown keys — but silently ignoring it would leave someone
+// wondering why their command never runs, so `status` calls it out.
+function repoConfigKeyCommand(dir) {
+  try {
+    const raw = fs.readFileSync(path.join(dir, CONFIG_FILE), 'utf-8')
+    const parsed = JSON.parse(raw)
+    const auth = parsed && parsed.auth
+    return auth && typeof auth.keyCommand === 'string' && auth.keyCommand.trim()
+      ? auth.keyCommand.trim()
+      : null
+  } catch {
+    return null
+  }
+}
+
+// Read stdin to completion (for `--stdin`).
+function readAllStdin(input) {
+  return new Promise((resolve, reject) => {
+    let data = ''
+    input.setEncoding('utf-8')
+    input.on('data', (chunk) => (data += chunk))
+    input.on('end', () => resolve(data))
+    input.on('error', reject)
+  })
+}
+
+// Prompt on a TTY with the input hidden. `_writeToOutput` is readline's own echo
+// hook — silencing it is what keeps the key off the screen (and out of a
+// screen-shared terminal or a recorded session).
+function promptHidden(question, input, out) {
+  const readline = require('node:readline')
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input, output: process.stdout, terminal: true })
+    out.write(question)
+    rl.question('', (answer) => {
+      out.write('\n')
+      rl.close()
+      resolve(answer)
+    })
+    rl._writeToOutput = () => {}
+  })
+}
+
 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 = []
+  // 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, 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
@@ -1196,6 +1821,18 @@ 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] === '--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') {
+      // Consumed and DELIBERATELY DISCARDED. A secret in argv is visible in
+      // shell history and to `ps`, so this is refused rather than supported —
+      // but it must still be swallowed here, or the value would fall through to
+      // `positional` and end up printed back in a usage message.
+      i++
+      flags.keyArgGiven = true
+    }
     else if (args[i] === '--team-id') flags.teamId = String(args[++i] || '').trim()
     else if (args[i] === '--team-key') flags.teamKey = String(args[++i] || '').trim()
     else if (args[i] === '--project-id') flags.projectId = String(args[++i] || '').trim()
@@ -1208,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
@@ -1223,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(
@@ -1247,6 +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 'retarget':
+      return (await specSyncRetarget(dir, config, flags, out)) || 0
     case 'apply':
       return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
     case 'verify':
@@ -1254,8 +1924,11 @@ async function specSync(rest, io = {}) {
     case 'linked':
       specSyncLinked(dir, config, flags, out)
       return 0
+    case 'credentials':
+      return await specSyncCredentials(dir, config, positional[0], flags, out)
     default:
       out.write('Usage: skitterspec spec-sync <normalize|record|status> <spec> [--json] [--remote file] [--workspace-states file]\n' +
+        '       skitterspec spec-sync credentials <status|set|unset> [--stdin] [--json]\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 states [--via api|mcp] [--json]\n' +
@@ -1264,6 +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 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')