@skitterbyte/skitterspec-linear 10.1.0 → 10.2.0

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

@@ -44,7 +44,8 @@ const {
   compareStored,
 } = require('../sync-core')
 
-const { loadLinearConfig } = require('./config.js')
+const { loadLinearConfig, mergeConfig, defaults: configDefaults, CONFIG_FILE, LIFECYCLE_BUCKETS } = require('./config.js')
+const { resolveApiKey, makeApiAdapter, stateIdFor, fetchWorkspaceStates } = require('./api.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.
@@ -198,6 +199,7 @@ function specSyncPush(dir, config, specArg, flags, out, err) {
   const lines = [`spec-sync push: ${identifier}`, ...warningLines(snapshotDir, config)]
   if (p.legacy) lines.push(...legacyLines(p.legacy))
   if (p.phasesDeferred) lines.push(...deferredLines(p.phasesDeferred))
+  lines.push(...phaseModeLines(p.phaseMode, r.projection.status))
   if (r.empty) lines.push('  nothing to push — mirror matches the last push')
   else {
     if (p.issue) lines.push('  issue: description/state')
@@ -219,6 +221,25 @@ function deferredLines(n) {
   ]
 }
 
+// Which phase mode resolved for this spec, and what it means for the plan below.
+//
+// Silent for `subissue`: the sub-issue lines are right there and explain
+// themselves. Said for anything else, because `mapping.phases` can now be a
+// per-bucket map — so the mode that applied is no longer readable off the config
+// without knowing which bucket the spec is in, and the alternative reading of a
+// spec with no sub-issues is that its phase files failed to parse.
+function phaseModeLines(mode, bucket) {
+  if (!mode || mode === 'subissue') return []
+  const why = {
+    inline: 'each phase is a section of this issue\'s description, not a sub-issue',
+    deferred: 'unlinked phases are held back until the spec leaves backlog/cancelled',
+  }[mode]
+  const where = bucket ? ` for this spec's bucket ("${bucket}")` : ''
+  const lines = [`  phases: ${mode} — mapping.phases resolved${where}`]
+  if (why) lines.push(`     ${why}`)
+  return lines
+}
+
 // 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.
@@ -419,6 +440,7 @@ function specSyncStatus(dir, config, specArg, flags, out) {
   // From the projection, not the plan: `status` builds its plan with
   // `planChanges` directly rather than going through `push`.
   if (projection.phasesWithheld) lines.push(...deferredLines(projection.phasesWithheld))
+  lines.push(...phaseModeLines(projection.phaseMode, projection.status))
   if (!snapshot) lines.push('  push: never pushed — everything is pending')
   else if (isEmptyPlan(plan)) lines.push('  push: up to date — nothing changed since the last push')
   else {
@@ -474,6 +496,18 @@ function specSyncVerify(dir, config, specArg, flags, out) {
   }
 
   const identifier = specIdentifier(snapshotDir, config)
+  out.write(verifyLines(snapshotDir, config, stored, identifier).join('\n') + '\n')
+  return 0
+}
+
+/**
+ * The verify comparison itself, as reportable lines.
+ *
+ * Split out of `specSyncVerify` so `apply` runs the SAME check on the read-back
+ * it does itself, rather than a second implementation that could disagree about
+ * what counts as lost text.
+ */
+function verifyLines(snapshotDir, config, stored, identifier) {
   const projection = projectionOf(snapshotDir, config)
   const checks = []
   if (typeof stored.issue === 'string') checks.push(['issue', projection.description, stored.issue])
@@ -506,30 +540,681 @@ function specSyncVerify(dir, config, specArg, flags, out) {
   }
   if (!bad) lines.push(`  ${checks.length} description(s) round-tripped intact`)
   else lines.push('     the repo is unchanged and still correct; re-push to overwrite the mirror')
+  return lines
+}
+
+/**
+ * `spec-sync states [--json]` — which transport this repo will use, and on the
+ * API path the workspace's issue state NAMES.
+ *
+ * This exists to break a chicken-and-egg in `/spec-push`: the skill cannot know
+ * whether to do MCP work until it knows the transport, but `push` refuses to run
+ * without `--workspace-states`, which on the MCP path only an MCP call can
+ * supply. Asking the engine first makes the skill linear, and on the API path it
+ * removes the state fetch from the model's work entirely — the same reason
+ * `apply` exists.
+ *
+ * Read-only: fetches states, writes nothing, changes nothing.
+ */
+async function specSyncStates(dir, config, flags, out) {
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+
+  if (transport === 'mcp') {
+    if (flags.json) {
+      out.write(JSON.stringify({ transport: 'mcp', reason: key.ok ? 'requested' : key.error, states: null }, null, 2) + '\n')
+      return 0
+    }
+    out.write(
+      [
+        'spec-sync states: transport = mcp',
+        `  ${key.ok ? '--via mcp was requested' : key.error}`,
+        '  fetch the workspace states over MCP, as /spec-push describes',
+      ].join('\n') + '\n',
+    )
+    return 0
+  }
+  if (!key.ok) {
+    out.write(`spec-sync states: refusing — ${key.error}\n`)
+    return 1
+  }
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  const teamId = (config.linear && config.linear.teamId) || null
+  let names
+  try {
+    names = await fetchWorkspaceStates(adapter, teamId)
+  } catch (error) {
+    out.write(`spec-sync states: ${error.message}\n`)
+    return 1
+  }
+  if (flags.json) {
+    // The bare array `--workspace-states` takes, so this can be piped into it.
+    out.write(JSON.stringify(names, null, 2) + '\n')
+    return 0
+  }
+  out.write(`spec-sync states: transport = api\n  ${names.join(', ')}\n`)
+  return 0
+}
+
+/**
+ * `spec-sync apply <spec> --plan <file> [--via api|mcp] [--project <id>]`
+ *
+ * Apply a push plan to Linear **without any description passing through the
+ * agent**. `/spec-push` used to hand the plan to the model, which re-emitted
+ * every description as generated tokens — twice, once to write and once for the
+ * verify read-back — making throughput a function of decode speed rather than of
+ * Linear's API. This does the writes, the read-back, the stamping and the
+ * snapshot in one call.
+ *
+ * Two guarantees shape the code:
+ *
+ *   - **Nothing is written until everything is checked.** A legacy plan, a
+ *     missing key, or a `config.states` name the workspace lacks all fail before
+ *     the first mutation. A half-applied plan is the one outcome worse than an
+ *     unapplied one.
+ *   - **Each id is stamped the moment its object exists**, not batched at the
+ *     end. An interrupted run therefore leaves the objects it did create linked,
+ *     so the next run's plan sees them as updates and mints no duplicates. That
+ *     is the whole resumability story — there is no separate ledger to disagree
+ *     with the spec files.
+ *
+ * On the MCP transport it writes nothing and prints the plan for the skill to
+ * apply, exactly as before.
+ */
+/**
+ * `spec-sync projects [--json]` — the team's Linear Projects, for the picker.
+ *
+ * The picker is the one interactive step in linking a spec, and on the API path
+ * there is no MCP tool to list from — the whole point of that path is that the
+ * agent makes no Linear calls. So the engine offers the list, exactly as
+ * `spec-sync states` offers workspace states.
+ *
+ * Degrades rather than blocks: no key, or a Linear that will not answer, exits 0
+ * with an empty list and says why. A missing picker must never fail `/spec`.
+ */
+async function specSyncProjects(dir, config, flags, out) {
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+  const teamId = (config.linear && config.linear.teamId) || null
+
+  const degrade = (reason) => {
+    if (flags.json) out.write(JSON.stringify({ transport, projects: null, reason }, null, 2) + '\n')
+    else out.write(`spec-sync projects: ${reason}\n`)
+    return 0
+  }
+  if (transport === 'mcp') {
+    return degrade(
+      `transport = mcp — ${key.ok ? '--via mcp was requested' : key.error}; list projects over MCP instead`,
+    )
+  }
+  if (!key.ok) return degrade(key.error)
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  let projects
+  try {
+    projects = await adapter.listProjects(teamId)
+  } catch (error) {
+    // The picker's contract is "degrade, never block" — a project list we cannot
+    // fetch means no picker, not a failed link.
+    return degrade(`could not list projects (${error.message}); continuing without the picker`)
+  }
+  const rows = projects.map((p) => ({ id: p.id, name: p.name })).filter((p) => p.id)
+  if (flags.json) {
+    out.write(JSON.stringify({ transport: 'api', projects: rows }, null, 2) + '\n')
+    return 0
+  }
+  out.write(
+    [`spec-sync projects: transport = api, ${rows.length} project(s)`, ...rows.map((p) => `  ${p.id}  ${p.name}`)].join('\n') + '\n',
+  )
+  return 0
+}
+
+/**
+ * Apply one spec's plan. Returns what happened rather than printing it, so the
+ * single-spec command and the bulk loop report in their own voices while sharing
+ * one implementation of the part that actually matters.
+ *
+ * Every id is stamped the moment its object exists — see `specSyncApply`.
+ */
+async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states }) {
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const identifier = linkedIdentifier(path.join(snapshotDir, overviewFile))
+  const lines = []
+  const result = { issue: null, subIssues: {} }
+  const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states) : null)
+
+  // Resolve every state id BEFORE the first write, so a bad config.states value
+  // cannot strand the spec mid-apply.
+  const wanted = new Set()
+  if (plan.issue && plan.issue.state) wanted.add(plan.issue.state)
+  for (const s of (plan.subIssues && plan.subIssues.create) || []) if (s.state) wanted.add(s.state)
+  for (const s of (plan.subIssues && plan.subIssues.update) || []) if (s.state) wanted.add(s.state)
+  for (const bucket of wanted) stateId(bucket)
+
+  // 1. The spec issue. No identifier yet → this push mints it.
+  let parentId = null
+  if (!identifier) {
+    const created = await adapter.createIssue(withoutNull({
+      title: readSnapshot(snapshotDir, config).title,
+      teamId,
+      projectId: project || (config.linear && config.linear.projectId) || null,
+      description: plan.issue && plan.issue.description,
+      stateId: stateId(plan.issue && plan.issue.state),
+    }))
+    if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
+    parentId = created.id
+    // Stamped NOW: an interrupt after this point must not mint a second issue.
+    writeFrontmatter(snapshotDir, config, { linear_identifier: created.identifier, linear_url: created.url })
+    result.issue = { id: created.id, identifier: created.identifier, url: created.url }
+    lines.push(`  issue created: ${created.identifier}`)
+  } else {
+    const existing = await adapter.readIssue(identifier)
+    if (!existing || !existing.id) throw new Error(`no Linear issue found for ${identifier}`)
+    parentId = existing.id
+    result.issue = { id: existing.id, identifier: existing.identifier, url: existing.url }
+    if (plan.issue) {
+      await adapter.updateIssue(existing.id, withoutNull({
+        description: plan.issue.description,
+        stateId: stateId(plan.issue.state),
+      }))
+      lines.push(`  issue updated: ${identifier}`)
+    }
+  }
+
+  // 2. Sub-issue creates — each stamped as it lands, for the same reason.
+  for (const sub of (plan.subIssues && plan.subIssues.create) || []) {
+    const created = await adapter.createSubIssue(parentId, withoutNull({
+      title: sub.name,
+      teamId,
+      description: sub.goal,
+      stateId: stateId(sub.state),
+    }))
+    if (!created || !created.identifier) throw new Error(`Linear returned no issue for sub-issue ${sub.ref}`)
+    const file = resolvePhaseFile(snapshotDir, sub.ref)
+    if (!file) throw new Error(`no phase file for ref ${sub.ref}`)
+    stampSubIssueId(snapshotDir, file, created.identifier)
+    result.subIssues[sub.ref] = created.identifier
+    lines.push(`  sub-issue created: ${sub.ref} → ${created.identifier}`)
+  }
+
+  // 3. Sub-issue updates — already linked, nothing to stamp.
+  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
+    lines.push(`  sub-issue updated: ${sub.id}`)
+  }
+
+  // 4. Read back what Linear stored and run the SAME check `verify` runs.
+  const stored = { issue: undefined, subIssues: {} }
+  if (result.issue) {
+    const back = await adapter.readIssue(result.issue.id)
+    if (back && typeof back.description === 'string') stored.issue = back.description
+  }
+  for (const [ref, id] of Object.entries(result.subIssues)) {
+    const back = await adapter.readIssue(id)
+    if (back && typeof back.description === 'string') stored.subIssues[ref] = back.description
+  }
+  const verify = verifyLines(snapshotDir, config, stored, result.issue ? result.issue.identifier : identifier)
+  lines.push(...verify.map((l) => `  ${l}`))
+  const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
+
+  // 5. Record the snapshot from the now-stamped files, so the next push is empty.
+  const file = recordPush({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config })
+  lines.push(`  snapshot: ${path.relative(dir, file)}`)
+  return { result, lines, lost }
+}
+
+/**
+ * `spec-sync apply <spec> --plan <file> [--via api|mcp] [--project <id>]`
+ * `spec-sync apply --all <bucket> [--via api|mcp] [--json]`
+ *
+ * Apply a push plan to Linear **without any description passing through the
+ * agent**. `/spec-push` used to hand the plan to the model, which re-emitted
+ * every description as generated tokens — twice, once to write and once for the
+ * verify read-back — making throughput a function of decode speed rather than of
+ * Linear's API. This does the writes, the read-back, the stamping and the
+ * snapshot in one call.
+ *
+ * Two guarantees shape the code:
+ *
+ *   - **Nothing is written until everything is checked.** A legacy plan, a
+ *     missing key, or a `config.states` name the workspace lacks all fail before
+ *     the first mutation. A half-applied plan is the one outcome worse than an
+ *     unapplied one.
+ *   - **Each id is stamped the moment its object exists**, not batched at the
+ *     end. An interrupted run therefore leaves the objects it did create linked,
+ *     so the next run's plan sees them as updates and mints no duplicates. That
+ *     is the whole resumability story — there is no separate ledger to disagree
+ *     with the spec files.
+ *
+ * `--all <bucket>` walks every spec in one lifecycle bucket, computing each plan
+ * in process (no plan files) and carrying on past a spec that fails. That is
+ * first-time adoption on an established repo: one command instead of a session.
+ *
+ * On the MCP transport it writes nothing and prints the plan for the skill to
+ * apply, exactly as before.
+ */
+async function specSyncApply(dir, config, specArg, flags, out) {
+  const bulk = flags.all != null
+  if (bulk && !BUCKETS.includes(flags.all)) {
+    out.write(`spec-sync apply: --all ${flags.all} is not a bucket (${BUCKETS.join('|')})\n`)
+    return 1
+  }
+
+  let snapshotDir = null
+  let plan = null
+  if (!bulk) {
+    snapshotDir = resolveOrExit(specArg, dir, out)
+    if (!snapshotDir) return 1
+    if (!flags.plan) {
+      out.write(
+        'spec-sync apply: refusing to run without --plan <file>.\n' +
+          '  Get one with: skitterspec spec-sync push <spec> --json > plan.json\n' +
+          '  Or apply a whole bucket at once with --all <bucket>.\n',
+      )
+      return 1
+    }
+    try {
+      plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
+    } catch (error) {
+      out.write(`spec-sync apply: cannot read --plan ${flags.plan}: ${error.message}\n`)
+      return 1
+    }
+
+    // A pre-9.0 mirror reads as unlinked, so its plan is all-creates and applying
+    // it would abandon the live objects. The API path must not do that faster
+    // than a human can read about it.
+    if (plan.legacy) {
+      out.write(
+        ['spec-sync apply: refusing — this spec is linked under the pre-9.0 model.', ...legacyLines(plan.legacy)].join('\n') + '\n',
+      )
+      return 1
+    }
+    if (isEmptyPlan(plan)) {
+      out.write('spec-sync apply: nothing to apply — the mirror is up to date.\n')
+      return 0
+    }
+  }
+
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+
+  if (transport === 'mcp') {
+    if (bulk) {
+      // Bulk over MCP is the very thing this command exists to avoid; pretending
+      // to support it would hand the model every description in the bucket.
+      out.write(
+        [
+          'spec-sync apply: --all needs the api transport (no writes made here)',
+          `  ${key.ok ? '--via mcp was requested' : key.error}`,
+          '  push specs one at a time with /spec-push, or set a key and re-run.',
+        ].join('\n') + '\n',
+      )
+      return 1
+    }
+    out.write(
+      [
+        'spec-sync apply: transport = mcp (no writes made here)',
+        key.ok ? '  --via mcp was requested' : `  ${key.error}`,
+        '  apply the plan over MCP as /spec-push describes, then run:',
+        '    skitterspec spec-sync stamp <spec> --issue … [--sub <ref>=… …]',
+        '    skitterspec spec-sync record <spec>',
+      ].join('\n') + '\n',
+    )
+    return 0
+  }
+  if (!key.ok) {
+    // --via api (or apply.transport: api) was explicit, so this is a failure
+    // rather than a quiet fallback — and it happens before any write.
+    out.write(`spec-sync apply: refusing — ${key.error}\n`)
+    return 1
+  }
+
+  const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+  const teamId = (config.linear && config.linear.teamId) || null
+  let states
+  try {
+    states = await adapter.listIssueStates(teamId)
+  } catch (error) {
+    out.write(`spec-sync apply: ${error.message}\n`)
+    return 1
+  }
+  const shared = { dir, config, adapter, teamId, project: flags.project, states }
+
+  if (!bulk) {
+    const lines = ['spec-sync apply: transport = api']
+    let applied
+    try {
+      applied = await applyOneSpec({ ...shared, snapshotDir, plan })
+    } catch (error) {
+      // Whatever landed before the failure is already stamped, so re-running
+      // resumes rather than duplicating — say so instead of leaving it ambiguous.
+      out.write(
+        [...lines, `  !! ${error.message}`, '  ids stamped so far are saved — re-run to resume without duplicating'].join('\n') + '\n',
+      )
+      return 1
+    }
+    if (flags.json) {
+      out.write(JSON.stringify(applied.result, null, 2) + '\n')
+      return 0
+    }
+    out.write([...lines, ...applied.lines].join('\n') + '\n')
+    return 0
+  }
+
+  // --- bulk -------------------------------------------------------------------
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const specs = listSpecs(dir, config).filter((s) => s.bucket === flags.all)
+  const lines = [`spec-sync apply --all ${flags.all}: transport = api, ${specs.length} spec(s)`]
+  const summary = { created: 0, updated: 0, upToDate: 0, failed: 0, altered: 0 }
+  const failures = []
+
+  const fail = (spec, why) => {
+    summary.failed++
+    failures.push(`${spec}: ${why}`)
+    lines.push(`  x ${spec}: ${why}`)
+  }
+
+  for (const { spec } of specs) {
+    const specDir = resolveSnapshotDir(spec, dir)
+    if (!specDir) {
+      fail(spec, 'could not resolve its folder')
+      continue
+    }
+    let specPlan
+    try {
+      specPlan = push({ dir, snapshotDir: specDir, identifier: specIdentifier(specDir, config), config }).plan
+    } catch (error) {
+      fail(spec, error.message)
+      continue
+    }
+    // Never silently: applying this would abandon a live pre-9.0 mirror.
+    if (specPlan.legacy) {
+      fail(spec, `pre-9.0 mirror — would orphan ${specPlan.legacy.orphanCount} object(s); see MIGRATION.md`)
+      continue
+    }
+    if (isEmptyPlan(specPlan)) {
+      summary.upToDate++
+      lines.push(`  . ${spec}: up to date`)
+      continue
+    }
+    const minted = !linkedIdentifier(path.join(specDir, overviewFile))
+    let applied
+    try {
+      applied = await applyOneSpec({ ...shared, snapshotDir: specDir, plan: specPlan })
+    } catch (error) {
+      fail(spec, error.message)
+      continue
+    }
+    if (minted) summary.created++
+    else summary.updated++
+    const id = applied.result.issue ? applied.result.issue.identifier : '?'
+    const subs = Object.keys(applied.result.subIssues).length
+    lines.push(`  ok ${spec}: ${minted ? 'created' : 'updated'} ${id}${subs ? ` (+${subs} sub-issue(s))` : ''}`)
+    if (applied.lost) {
+      summary.altered++
+      lines.push(...applied.lines.filter((l) => l.includes('!!') || l.includes('??')))
+    }
+  }
+
+  lines.push(
+    '',
+    `  created ${summary.created} · updated ${summary.updated} · up to date ${summary.upToDate} · failed ${summary.failed}`,
+  )
+  if (summary.altered) {
+    lines.push(`  ${summary.altered} spec(s) had text altered by Linear — the repo is unchanged and still correct`)
+  }
+  if (failures.length) {
+    lines.push('', '  failed:')
+    for (const f of failures) lines.push(`    ${f}`)
+    lines.push('  re-run to retry them — everything already created is linked, so nothing duplicates')
+  }
+  if (flags.json) out.write(JSON.stringify({ summary, failures }, null, 2) + '\n')
+  else out.write(lines.join('\n') + '\n')
+  // Non-zero when anything failed, so a scripted backfill is checkable.
+  return summary.failed ? 1 : 0
+}
+
+// A comma-separated label flag (`--bug-labels bug,defect`) as the trimmed,
+// non-empty list the config stores.
+function labelList(value) {
+  return String(value || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+/**
+ * `spec-sync init-config --team-id <id> [flags]`
+ *
+ * Turn values gathered from the workspace into a valid
+ * `specs/.core/linear.config.json`. The engine half of `/spec-linear-setup`:
+ * the skill discovers over MCP and interviews, this validates and writes, so a
+ * malformed config can never be the model's formatting. Same split as
+ * `/spec-push` gathering and `spec-sync apply` writing.
+ *
+ * Three things shape it:
+ *
+ *   - **Only the keys the operator set are written.** The shipped defaults
+ *     already carry every other value; restating them buries the two or three
+ *     lines that are genuinely this repo's, and freezes today's defaults into a
+ *     file that then never picks up a change to them.
+ *   - **Nothing is written until the loader would accept it.** The draft is run
+ *     through `mergeConfig` — the very function `loadLinearConfig` uses — so an
+ *     enum this rejects is exactly an enum that would have thrown on first use.
+ *   - **State names are checked here, not at first push.** Linear silently
+ *     ignores an unknown issue state, so a workspace that renamed `Done` gets a
+ *     mirror that never moves. `--states` makes that a setup-time failure with
+ *     the replacement named.
+ *
+ * `--states` is optional, and deliberately so: `spec-sync states` cannot run
+ * before a config exists (every other subcommand exits early on `present:false`),
+ * so requiring it here would make the config unbootstrappable. The skill always
+ * passes it from MCP discovery; a bare CLI run without it writes and says
+ * loudly that the names are unverified.
+ */
+function specSyncInitConfig(dir, flags, out) {
+  const file = path.join(dir, CONFIG_FILE)
+  const rel = CONFIG_FILE
+  const existed = fs.existsSync(file)
+  const fail = (lines, extra = {}) => {
+    if (flags.json) {
+      out.write(JSON.stringify({ ok: false, file: rel, error: lines[0], ...extra }, null, 2) + '\n')
+    } else {
+      out.write(lines.join('\n') + '\n')
+    }
+    return 1
+  }
+
+  if (existed && !flags.force) {
+    return fail([
+      `spec-sync init-config: refusing — ${rel} already exists`,
+      '  pass --force to replace it. Re-running setup on a configured repo is',
+      '  meant to be a way to CHECK the setup, not a way to lose it.',
+    ])
+  }
+  if (!flags.teamId) {
+    return fail([
+      'spec-sync init-config: refusing — --team-id is required',
+      '  it is the one value with no useful default: without it nothing knows',
+      '  which Linear team a spec files into.',
+    ])
+  }
+
+  // Only what the operator actually set. Empty strings/arrays are treated as
+  // "not set" — the defaults already say that, and more clearly.
+  const draft = {}
+  const linear = {}
+  if (flags.teamId) linear.teamId = flags.teamId
+  if (flags.teamKey) linear.teamKey = flags.teamKey
+  if (flags.projectId) linear.projectId = flags.projectId
+  draft.linear = linear
+  const intake = {}
+  if (flags.intakeLabel) intake.label = flags.intakeLabel
+  if (flags.bugLabels.length) intake.bugLabels = flags.bugLabels
+  if (flags.hotfixLabels.length) intake.hotfixLabels = flags.hotfixLabels
+  if (Object.keys(intake).length) draft.intake = intake
+  if (Object.keys(flags.stateNames).length) draft.states = { ...flags.stateNames }
+
+  for (const bucket of Object.keys(flags.stateNames)) {
+    if (!LIFECYCLE_BUCKETS.includes(bucket)) {
+      return fail([
+        `spec-sync init-config: refusing — --state ${bucket}=… is not a lifecycle bucket`,
+        `  expected one of ${LIFECYCLE_BUCKETS.join(', ')}`,
+      ])
+    }
+  }
+
+  // The loader's own merge, so anything it would reject is rejected now rather
+  // than on the first command that reads the file.
+  let effective
+  try {
+    effective = mergeConfig(configDefaults(), draft)
+  } catch (error) {
+    return fail([`spec-sync init-config: refusing — ${error.message}`])
+  }
+
+  // Workspace state names, when the caller discovered them.
+  let workspace = null
+  if (flags.statesFile) {
+    if (!fs.existsSync(flags.statesFile)) {
+      return fail([`spec-sync init-config: refusing — no such --states file: ${flags.statesFile}`])
+    }
+    let parsed
+    try {
+      parsed = JSON.parse(fs.readFileSync(flags.statesFile, 'utf-8'))
+    } catch (error) {
+      return fail([`spec-sync init-config: refusing — --states is not valid JSON: ${error.message}`])
+    }
+    if (!Array.isArray(parsed)) {
+      return fail(['spec-sync init-config: refusing — --states must be a JSON array of state names'])
+    }
+    workspace = parsed.map((s) => String(s)).filter(Boolean)
+
+    const missing = validateStates(effective, workspace)
+    if (missing.length) {
+      const lines = ['spec-sync init-config: refusing — configured state name(s) not in the workspace', '']
+      for (const { bucket, configured, suggestion } of stateSuggestions(effective, workspace)) {
+        lines.push(`  states.${bucket}: "${configured}" is not an issue state in this workspace`)
+        if (suggestion) lines.push(`    pass --state ${bucket}="${suggestion}"`)
+      }
+      lines.push(
+        '',
+        `  available: ${workspace.join(', ') || '(the workspace reported none)'}`,
+        '  Linear silently ignores an unknown issue state, so writing this would',
+        '  have produced a mirror that never moves.',
+      )
+      return fail(lines, { missing })
+    }
+  }
+
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(draft, null, 2) + '\n', 'utf-8')
+
+  const checked = Object.keys(effective.states).length
+  if (flags.json) {
+    out.write(
+      JSON.stringify(
+        {
+          ok: true,
+          file: rel,
+          replaced: existed,
+          wrote: draft,
+          validated: {
+            teamId: flags.teamId,
+            states: workspace ? { checked, against: workspace.length, missing: [] } : null,
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return 0
+  }
+
+  const lines = [`spec-sync init-config: wrote ${rel}`]
+  lines.push(`  team:      ${flags.teamKey ? `${flags.teamKey} · ` : ''}${flags.teamId}`)
+  lines.push(`  project:   ${flags.projectId || '(none — team only; the picker offers the rest)'}`)
+  if (draft.intake) {
+    const bits = []
+    if (intake.label) bits.push(`inbox "${intake.label}"`)
+    if (intake.bugLabels) bits.push(`bug: ${intake.bugLabels.join(', ')}`)
+    if (intake.hotfixLabels) bits.push(`hotfix: ${intake.hotfixLabels.join(', ')}`)
+    lines.push(`  intake:    ${bits.join(' · ')}`)
+  }
+  if (workspace) {
+    lines.push(`  states:    ${checked} checked against ${workspace.length} workspace state(s) — all present`)
+  } else {
+    lines.push(`  states:    NOT validated — the defaults (${Object.values(effective.states).join(', ')}) are assumed`)
+    lines.push('             pass --states <file> to check them; a renamed state pushes clean and moves nothing')
+  }
+  lines.push(`  Wrote ${Object.keys(draft).length} section(s); everything else uses the shipped defaults.`)
   out.write(lines.join('\n') + '\n')
   return 0
 }
 
+// Drop null/undefined so a GraphQL input never carries a key it has no value
+// for — Linear rejects an explicit null where it expects a field to be absent.
+function withoutNull(obj) {
+  const out = {}
+  for (const [k, v] of Object.entries(obj)) if (v !== null && v !== undefined) out[k] = v
+  return out
+}
+
 async function specSync(rest, io = {}) {
   const out = io.out || process.stdout
   const err = io.err || process.stderr
   const [sub, ...args] = rest
   let dir = io.cwd || process.cwd()
   const positional = []
-  const flags = { json: false, remote: null, workspaceStates: null, skipStateCheck: false, issue: null, url: null, subs: [], stored: null }
+  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 }
   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] === '--stored') flags.stored = path.resolve(args[++i])
+    else if (args[i] === '--plan') flags.plan = path.resolve(args[++i])
+    else if (args[i] === '--via') flags.via = args[++i]
+    else if (args[i] === '--all') flags.all = args[++i]
+    else if (args[i] === '--project') flags.project = args[++i]
     else if (args[i] === '--workspace-states') flags.workspaceStates = path.resolve(args[++i])
     else if (args[i] === '--skip-state-check') flags.skipStateCheck = true
     else if (args[i] === '--issue') flags.issue = args[++i]
     else if (args[i] === '--url') flags.url = args[++i]
     else if (args[i] === '--sub') flags.subs.push(args[++i])
+    else if (args[i] === '--force') flags.force = 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()
+    else if (args[i] === '--intake-label') flags.intakeLabel = String(args[++i] || '').trim()
+    else if (args[i] === '--bug-labels') flags.bugLabels = labelList(args[++i])
+    else if (args[i] === '--hotfix-labels') flags.hotfixLabels = labelList(args[++i])
+    else if (args[i] === '--state') {
+      // `--state complete=Shipped`, repeatable. Only the buckets a workspace
+      // actually renamed get written; the rest keep the defaults.
+      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 positional.push(args[i])
   }
   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
+  // end offline. Production passes none of them and gets the real thing.
+  flags.env = io.env || process.env
+  if (io.adapter) flags.adapter = io.adapter
+  if (io.fetch) flags.fetch = io.fetch
+
+  // Dispatched ahead of the load on purpose: this is the command you run when
+  // there is no config, and `--force` must be able to replace one that is
+  // malformed enough for the loader to throw on.
+  if (sub === 'init-config') return specSyncInitConfig(dir, flags, out)
 
   const { config, present } = loadLinearConfig(dir)
   if (!present) {
@@ -553,6 +1238,12 @@ async function specSync(rest, io = {}) {
       return 0
     case 'status':
       return specSyncStatus(dir, config, positional[0], flags, out) || 0
+    case 'projects':
+      return (await specSyncProjects(dir, config, flags, out)) || 0
+    case 'states':
+      return (await specSyncStates(dir, config, flags, out)) || 0
+    case 'apply':
+      return (await specSyncApply(dir, config, positional[0], flags, out)) || 0
     case 'verify':
       return specSyncVerify(dir, config, positional[0], flags, out) || 0
     case 'linked':
@@ -562,8 +1253,15 @@ async function specSync(rest, io = {}) {
       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 states [--via api|mcp] [--json]\n' +
+        '       skitterspec spec-sync projects [--via api|mcp] [--json]\n' +
+        '       skitterspec spec-sync apply <spec> --plan <file> [--via api|mcp] [--project id] [--json]\n' +
+        '       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 linked [--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')
       return 0
   }
 }