@skitterbyte/skitterspec-linear 10.6.0 → 10.7.0

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

@@ -25,7 +25,7 @@ const path = require('node:path')
 
 const { BUCKETS, findSpecFolder, branchFor, splitPrefix, currentBranch } = require('../../env/resolve.js')
 const { loadEnvConfig } = require('../../env/config.js')
-const { ticketsInRange } = require('./released.js')
+const { ticketsInRange, partitionStageMoves, stageOrderWarning } = require('./released.js')
 const { execFileSync } = require('node:child_process')
 const {
   normalizeLocal,
@@ -38,6 +38,8 @@ const {
   planChanges,
   isEmptyPlan,
   remoteWorkflowState,
+  remoteStage,
+  LADDER_ORIGIN_BUCKET,
   validateStates,
   stateSuggestions,
   lintPhases,
@@ -52,7 +54,15 @@ const {
   dirtyPaths,
 } = require('../sync-core')
 
-const { loadLinearConfig, mergeConfig, defaults: configDefaults, CONFIG_FILE, LIFECYCLE_BUCKETS } = require('./config.js')
+const {
+  loadLinearConfig,
+  mergeConfig,
+  defaults: configDefaults,
+  CONFIG_FILE,
+  LIFECYCLE_BUCKETS,
+  releaseStages,
+  stageFor,
+} = require('./config.js')
 const { resolveApiKey, makeApiAdapter, stateIdFor, fetchWorkspaceStates } = require('./api.js')
 const { runChecks } = require('./doctor.js')
 const {
@@ -326,8 +336,8 @@ function stateCheckFailure(config, flags) {
     // Say what IS available, and what to use instead. "Done is not a state" sends
     // you to the Linear UI to go and look; naming the replacement does not.
     const lines = ['spec-sync push: refusing — configured state name(s) not in the workspace', '']
-    for (const { bucket, configured, suggestion } of stateSuggestions(config, list)) {
-      lines.push(`  states.${bucket}: "${configured}" is not an issue state in this workspace`)
+    for (const { label, configured, suggestion } of stateSuggestions(config, list)) {
+      lines.push(`  ${label}: "${configured}" is not an issue state in this workspace`)
       if (suggestion) lines.push(`    use "${suggestion}" instead`)
     }
     lines.push(
@@ -477,7 +487,15 @@ function specSyncStatus(dir, config, specArg, flags, out) {
     const remote = JSON.parse(fs.readFileSync(flags.remote, 'utf-8'))
     const rState = remoteWorkflowState(remote, config)
     const lState = projection.status
-    if (rState && lState && rState !== lState) {
+    // A declared deployment stage is POSITION, not disagreement: the spec is
+    // complete and the pipeline has moved it on. Reporting that as drift would
+    // accuse every deployed spec, for as long as it sits in the pipeline — and
+    // "repo wins on next push" would be a lie, since a finished spec's state no
+    // longer re-pushes (see compare.js `issueChanges`).
+    const stage = remoteStage(remote, config)
+    if (stage) {
+      lines.push(`  stage: Linear is at "${stage.state}" (release stage "${stage.key}", past ${lState})`)
+    } else if (rState && lState && rState !== lState) {
       lines.push(`  drift: Linear workflow-state is "${rState}" but the spec is "${lState}" (repo wins on next push)`)
     } else {
       lines.push('  drift: none — Linear workflow-state matches the spec')
@@ -616,6 +634,7 @@ async function specSyncDoctor(dir, flags, out) {
     state.mcp = read.facts
   }
   if (flags.remoteCheck) state.remote = await checkRemote(state, flags)
+  if (state.remote && state.remote.issueStates) state.ladder.workspaceStates = state.remote.issueStates
 
   const report = runChecks(state)
 
@@ -635,7 +654,7 @@ async function specSyncDoctor(dir, flags, out) {
   // 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
+  const attention = report.checks.filter((c) => c.state === 'broken' || c.state === 'missing' || c.state === 'warn').length
   lines.push('')
   lines.push(attention ? `  ${attention} check(s) need attention.` : '  ready.')
 
@@ -725,7 +744,20 @@ async function checkRemote(state, flags) {
     }
   }
 
-  return { checked: true, ok: true, teamKey: team.key, teamId: team.id, organization, recordedKey: state.tracker.teamKey, project }
+  // Only fetched when a ladder is declared: the rows that do not need state
+  // types must not pay for a call that answers a question nobody asked.
+  let issueStates = null
+  if (releaseStages(state._config).length && typeof adapter.listIssueStates === 'function') {
+    try {
+      issueStates = await adapter.listIssueStates(state.tracker.teamId)
+    } catch {
+      // Unexamined, on the same rule as the project read: a transport failure is
+      // not evidence about the ladder's shape.
+      issueStates = null
+    }
+  }
+
+  return { checked: true, ok: true, teamKey: team.key, teamId: team.id, organization, recordedKey: state.tracker.teamKey, project, issueStates }
 }
 
 /**
@@ -847,6 +879,9 @@ function gatherState(dir, flags) {
   }
 
   state._config = config
+  // Declared here, checked only if `--check-remote` fetches the state TYPES the
+  // shape check needs (see `ladderCheck`). Offline, the row stays `skipped`.
+  state.ladder = { stages: releaseStages(config) }
   return state
 }
 
@@ -877,7 +912,44 @@ function countSkills(dir) {
  * `scripts/`, which is not shipped. The chosen range is always printed, so a
  * wrong guess is visible rather than silent.
  */
-async function specSyncReleased(dir, config, rangeArg, flags, out) {
+/**
+ * The base of a two-dot range that git cannot actually reach from the head, or
+ * null when the range is trustworthy (or is not a shape we can check).
+ *
+ * Deliberately NOT "is this repository shallow?". A shallow clone deep enough to
+ * contain the base has a COMPLETE range and is perfectly healthy — refusing it
+ * would accuse a working setup, which is the failure the stays-silent test in
+ * `cli-shallow-range.test.js` pins down. `merge-base --is-ancestor` asks the
+ * narrower question the range actually depends on.
+ *
+ * A range that is not `A..B` (a bare ref, a `...` symmetric difference, a
+ * revision expression) has no single base to check, so it is left alone: a guard
+ * that cannot see the shape must not pretend to have checked it. The shallow
+ * warning in the caller covers that case instead.
+ */
+function unreachableBase(git, range) {
+  const text = String(range || '')
+  if (text.includes('...')) return null
+  const parts = text.split('..')
+  if (parts.length !== 2) return null
+  const [base, head] = [parts[0].trim(), parts[1].trim() || 'HEAD']
+  if (!base) return null
+  // `is-ancestor` answers with its EXIT CODE, so a null return (non-zero) is the
+  // "not an ancestor" answer, not a missing tool. A base git cannot resolve at
+  // all falls through to the existing `git log` refusal, which names it better.
+  if (git(['rev-parse', '-q', '--verify', `${base}^{commit}`]) === null) return null
+  if (git(['rev-parse', '-q', '--verify', `${head}^{commit}`]) === null) return null
+  return git(['merge-base', '--is-ancestor', base, head]) === null ? base : null
+}
+
+/**
+ * Resolve a commit range and read it, shared by `released` (which reports on it)
+ * and `stage` (which acts on it). Both must agree on what a release contains,
+ * and a second copy of this would be a second answer.
+ *
+ * @returns {{range:string, commits:Array}|{error:string[]}}
+ */
+function readCommitRange(dir, rangeArg, verb) {
   const git = (argv) => {
     try {
       return execFileSync('git', ['-C', dir, ...argv], { stdio: ['ignore', 'pipe', 'ignore'] }).toString()
@@ -890,21 +962,40 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
   if (!range) {
     const tag = (git(['describe', '--tags', '--abbrev=0']) || '').trim()
     if (!tag) {
-      out.write(
-        'spec-sync released: no range given and no tag to default from.\n' +
-          '  Pass one explicitly, e.g. spec-sync released v1.2.0..HEAD\n',
-      )
-      return 1
+      return {
+        error: [
+          `spec-sync ${verb}: no range given and no tag to default from.`,
+          `  Pass one explicitly, e.g. spec-sync ${verb} v1.2.0..HEAD`,
+        ],
+      }
     }
     range = `${tag}..HEAD`
   }
 
+  // WHAT WOULD FOOL THIS: `git log` reports a TRUNCATED history as a successful
+  // one. On a shallow clone whose depth stops before the base, `git log
+  // base..HEAD` exits 0 and returns only the commits it happens to hold, so the
+  // range silently loses tickets. The tag itself resolves — `rev-parse --verify`
+  // passes — so "does the base exist?" is not the question. The question is
+  // whether the base is in THIS history, which is what `merge-base` answers.
+  const unreachable = unreachableBase(git, range)
+  if (unreachable) {
+    return {
+      error: [
+        `spec-sync ${verb}: refusing — "${unreachable}" is not reachable in this clone's history.`,
+        '  The range would silently report fewer commits than it contains.',
+        '  This is usually a shallow clone: fetching tags makes the tag resolve',
+        '  without deepening the history. Fetch full history (CI: fetch-depth: 0),',
+        '  or pass a range whose base is present.',
+      ],
+    }
+  }
+
   // NUL-delimited so a subject or body containing the separator cannot split a
   // record; RS between commits for the same reason.
   const raw = git(['log', '--format=%H%x00%s%x00%b%x1e', range])
   if (raw === null) {
-    out.write(`spec-sync released: git could not resolve the range "${range}".\n`)
-    return 1
+    return { error: [`spec-sync ${verb}: git could not resolve the range "${range}".`] }
   }
 
   const commits = raw
@@ -916,6 +1007,17 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
       return { sha, subject, body: rest.join('\x00') }
     })
 
+  return { range, commits }
+}
+
+async function specSyncReleased(dir, config, rangeArg, flags, out) {
+  const read = readCommitRange(dir, rangeArg, 'released')
+  if (read.error) {
+    out.write(read.error.join('\n') + '\n')
+    return 1
+  }
+  const { range, commits } = read
+
   const report = ticketsInRange(commits)
 
   // Titles are an ENRICHMENT: the scan itself is offline. No key, the MCP
@@ -964,13 +1066,216 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
 }
 
 /**
- * `spec-sync ref [--json]` — the ticket this branch's work belongs to.
+ * `spec-sync stage <key> [<range>] [--apply] [--json]` — move a release's
+ * tickets onto a declared deployment rung.
+ *
+ * The counterpart to `released`, which reports and cannot write. This is the
+ * write, and it is deliberately a separate verb: someone typing `released` in a
+ * terminal should never be able to move anything.
+ *
+ * **Dry run is the default.** `--apply` is required to touch Linear, and the
+ * resolved range, the target state and the full plan print either way — a wrong
+ * range is then visible before it is acted on rather than after.
+ *
+ * What it refuses to move is as important as what it moves: see
+ * `partitionStageMoves`. Every excluded ref is named with its reason, because a
+ * silent exclusion and a successful move look identical in a pipeline log.
+ */
+async function specSyncStage(dir, config, stageKey, rangeArg, flags, out) {
+  const stages = releaseStages(config)
+  if (!stages.length) {
+    out.write(
+      'spec-sync stage: no deployment ladder is declared.\n' +
+        `  Add release.stages to ${CONFIG_FILE} — see its docs for the shape.\n`,
+    )
+    return 1
+  }
+  if (!stageKey) {
+    out.write(`spec-sync stage: no stage given. Declared: ${stages.map((s) => s.key).join(', ')}\n`)
+    return 1
+  }
+  const stage = stageFor(config, stageKey)
+  if (!stage) {
+    out.write(
+      `spec-sync stage: no stage named ${JSON.stringify(stageKey)}.\n` +
+        `  Declared: ${stages.map((s) => s.key).join(', ')}\n`,
+    )
+    return 1
+  }
+
+  const read = readCommitRange(dir, rangeArg, 'stage')
+  if (read.error) {
+    out.write(read.error.join('\n') + '\n')
+    return 1
+  }
+  const { range, commits } = read
+
+  const report = ticketsInRange(commits)
+  const teamKey = (config.linear && config.linear.teamKey) || ''
+  const parts = partitionStageMoves({
+    tickets: report.tickets,
+    teamKey,
+    specs: listSpecs(dir, config),
+    cededBucket: LADDER_ORIGIN_BUCKET,
+  })
+
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+  const applying = Boolean(flags.apply)
+
+  if (applying && transport !== 'api') {
+    out.write(
+      `spec-sync stage: refusing to apply over ${transport}.\n` +
+        `  ${key.ok ? '--via api is required' : key.error}\n` +
+        '  Re-run without --apply for the plan.\n',
+    )
+    return 1
+  }
+
+  // Read each movable issue BEFORE any write: it yields the id the update needs,
+  // its title for the report, and its current state for the order warning. A ref
+  // that cannot be read is dropped from the move rather than guessed at.
+  const adapter = transport === 'api' && key.ok ? flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch }) : null
+  const moves = []
+  const unreadable = []
+  for (const ticket of parts.movable) {
+    if (!adapter) {
+      moves.push({ ...ticket, title: null, from: null, warning: null })
+      continue
+    }
+    let issue = null
+    try {
+      issue = await adapter.readIssue(ticket.ref)
+    } catch {
+      issue = null
+    }
+    if (!issue || !issue.id) {
+      unreadable.push(ticket)
+      continue
+    }
+    const from = issue.state && issue.state.name ? issue.state.name : null
+    moves.push({
+      ...ticket,
+      id: issue.id,
+      title: issue.title || null,
+      from,
+      warning: stageOrderWarning(stages, from, stage.key, Object.values(config.states || {})),
+    })
+  }
+
+  let moved = []
+  let failed = []
+  if (applying && moves.length) {
+    let states
+    try {
+      states = await adapter.listIssueStates((config.linear && config.linear.teamId) || null)
+    } catch (error) {
+      out.write(`spec-sync stage: could not read the workspace states — ${error.message}\n`)
+      return 1
+    }
+    // Resolve the target id BEFORE the first write, mirroring `apply`: a state
+    // name the workspace lacks must fail with nothing moved, not halfway through.
+    const target = states.find((st) => st && st.name && st.name.toLowerCase().trim() === stage.state.toLowerCase().trim())
+    if (!target) {
+      out.write(
+        `spec-sync stage: refusing — no issue state named ${JSON.stringify(stage.state)} in this workspace.\n` +
+          `  available: ${states.map((st) => st.name).join(', ') || '(none reported)'}\n` +
+          '  Linear silently ignores an unknown state, so this would have moved nothing.\n',
+      )
+      return 1
+    }
+    for (const move of moves) {
+      try {
+        await adapter.updateIssue(move.id, { stateId: target.id })
+        moved.push(move)
+      } catch (error) {
+        failed.push({ ...move, error: error.message })
+      }
+    }
+  }
+
+  if (flags.json) {
+    out.write(
+      JSON.stringify(
+        {
+          range,
+          stage: { key: stage.key, state: stage.state },
+          applied: applying,
+          moves: moves.map((m) => ({ ref: m.ref, title: m.title, from: m.from, warning: m.warning })),
+          moved: moved.map((m) => m.ref),
+          failed: failed.map((m) => ({ ref: m.ref, error: m.error })),
+          skipped: {
+            foreign: parts.foreign.map((t) => t.ref),
+            unlinked: parts.unlinked.map((t) => t.ref),
+            unfinished: parts.unfinished.map((t) => ({ ref: t.ref, bucket: t.bucket })),
+            unreadable: unreadable.map((t) => t.ref),
+          },
+          unreferencedCommits: report.unreferenced,
+          totalCommits: report.total,
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return failed.length ? 1 : 0
+  }
+
+  const lines = [`spec-sync stage: ${stage.key} -> "${stage.state}"  (${range})`, '']
+  if (!moves.length) {
+    lines.push(applying ? '  moved nothing' : '  would move nothing')
+  } else {
+    lines.push(`  ${applying ? 'moved' : 'would move'} ${applying ? moved.length : moves.length} ticket(s)`)
+    for (const m of moves) {
+      const title = m.title ? `  ${m.title}` : ''
+      lines.push(`    ${m.ref}${title}`)
+      if (m.warning) lines.push(`      warning: ${m.warning}`)
+    }
+  }
+  for (const { label, items } of [
+    { label: 'not team ' + (teamKey || '(unset)'), items: parts.foreign.map((t) => t.ref) },
+    { label: 'no spec in this repo claims it', items: parts.unlinked.map((t) => t.ref) },
+    {
+      label: 'spec not complete — push still owns its state',
+      items: parts.unfinished.map((t) => `${t.ref} (${t.bucket})`),
+    },
+    { label: 'could not be read from Linear', items: unreadable.map((t) => t.ref) },
+  ]) {
+    if (items.length) lines.push(`  skipped ${items.length} — ${label}: ${items.join(', ')}`)
+  }
+  for (const f of failed) lines.push(`  FAILED ${f.ref}: ${f.error}`)
+  lines.push('')
+  // Said even when zero, for the reason `released` says it: a chore commit
+  // legitimately carries no ref and a MISSED trailer looks identical, so silence
+  // would read as "every commit is accounted for".
+  lines.push(`  ${report.unreferenced} commit(s) carry no ref, of ${report.total}`)
+  if (!applying) lines.push('  dry run — pass --apply to move them')
+  out.write(lines.join('\n') + '\n')
+  return failed.length ? 1 : 0
+}
+
+/**
+ * `spec-sync ref [<spec>] [--json]` — the ticket a commit's work belongs to.
  *
  * Exists so neither a person nor a model has to go spelunking for the id when
  * writing a commit: `Refs: $(spec-sync ref)`. With a fast-forward-only history
  * the commit message is the ONLY place a ticket survives into the range a
  * release scans — branch names never reach it.
  *
+ * **Bare, it answers from the branch**, which is the same thing as "the ticket
+ * this commit belongs to" only while you are committing that branch's own
+ * implementation work. `/spec` requires no particular branch, so authoring a
+ * backlog spec part-way through another spec makes the two diverge: the commit
+ * is entirely the new spec's and the branch answer is a wrong ref stamped on it.
+ * **Naming the spec resolves it directly** — the branch is then not consulted at
+ * all, so it also works from `main`.
+ *
+ * The default deliberately stays branch-derived rather than inferring the spec
+ * from staged paths. Inference would change what gets stamped based on a lookup
+ * that `git commit -a`, partial staging, or a spec touching shared code each
+ * blind — silently, and in the destructive direction (a plausible wrong ref
+ * beats no ref for looking correct). An explicit override cannot be blinded, and
+ * needs no answer for mixed staging.
+ *
  * The branch→spec direction is the INVERSE of what `/spec-go` provisions with,
  * so it is computed by running `branchFor` over each spec and matching, rather
  * than by re-deriving the pattern here. A second implementation of the naming
@@ -979,11 +1284,25 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
  * **Every no-ref case prints nothing on stdout** and exits non-zero. A commit on
  * `main`, or on a spec kept deliberately local, has no ticket — and a command
  * that wrote an error message to stdout would see a shell splice it straight
- * into the commit body via `$(…)`.
+ * into the commit body via `$(…)`. That contract covers the named form too: an
+ * unknown spec name must FAIL rather than quietly falling back to the branch,
+ * which would turn a typo into a confidently wrong ref.
  */
-function specSyncRef(dir, config, flags, out, err) {
+function specSyncRef(dir, config, specArg, flags, out, err) {
   const say = (msg) => err.write(`spec-sync ref: ${msg}\n`)
 
+  // Shared tail: an unlinked spec is a no-ref case like any other, so it keeps
+  // stdout empty whichever form asked.
+  const emitRef = (spec, branch) => {
+    const identifier = linkedIdentifier(path.join(spec.path, (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'))
+    if (!identifier) {
+      say(`${spec.folder} is not linked to Linear — /spec-push to mirror it`)
+      return 1
+    }
+    out.write(flags.json ? JSON.stringify({ ref: identifier, spec: spec.folder, branch }, null, 2) + '\n' : `${identifier}\n`)
+    return 0
+  }
+
   const git = (argv) => {
     try {
       return execFileSync('git', ['-C', dir, ...argv], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()
@@ -992,6 +1311,18 @@ function specSyncRef(dir, config, flags, out, err) {
     }
   }
   const branch = currentBranch(git)
+
+  // The named form answers about the SPEC, so a missing branch is irrelevant to
+  // it — resolve before the branch is required at all.
+  if (specArg) {
+    const named = findSpecFolder(specArg, dir)
+    if (!named) {
+      say(`no spec folder named "${specArg}" in specs/ — check the name`)
+      return 1
+    }
+    return emitRef(named, branch || null)
+  }
+
   if (!branch) {
     say('not on a git branch (detached HEAD, or not a git repository)')
     return 1
@@ -1023,14 +1354,7 @@ function specSyncRef(dir, config, flags, out, err) {
     return 1
   }
 
-  const identifier = linkedIdentifier(path.join(match.path, (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'))
-  if (!identifier) {
-    say(`${match.folder} is not linked to Linear — /spec-push to mirror it`)
-    return 1
-  }
-
-  out.write(flags.json ? JSON.stringify({ ref: identifier, spec: match.folder, branch }, null, 2) + '\n' : `${identifier}\n`)
-  return 0
+  return emitRef(match, branch)
 }
 
 /**
@@ -1250,13 +1574,41 @@ async function specSyncStates(dir, config, flags, out) {
   }
   if (flags.json) {
     // The bare array `--workspace-states` takes, so this can be piped into it.
+    // Deliberately NOT widened to carry the configured vocabulary: every caller
+    // pipes this straight into that flag, and an object here would break them.
     out.write(JSON.stringify(names, null, 2) + '\n')
     return 0
   }
-  out.write(`spec-sync states: transport = api\n  ${names.join(', ')}\n`)
+  const lines = ['spec-sync states: transport = api', `  workspace: ${names.join(', ')}`]
+  lines.push(...configuredVocabularyLines(config, names))
+  out.write(lines.join('\n') + '\n')
   return 0
 }
 
+// The state names this project's config points at, shown against what the
+// workspace actually has — the bucket map, then the deployment ladder in its
+// declared order. One command then shows the whole vocabulary, instead of the
+// ladder living only in a file nobody re-reads.
+//
+// A name the workspace lacks is flagged here but nothing is refused: `states`
+// is a report. The push path is where that is fatal.
+function configuredVocabularyLines(config, names) {
+  const have = new Set((names || []).map((n) => String(n).toLowerCase().trim()))
+  const mark = (name) => (have.has(String(name).toLowerCase().trim()) ? '' : '   <- not in the workspace')
+  const lines = ['', '  configured:']
+  for (const [bucket, name] of Object.entries((config && config.states) || {})) {
+    lines.push(`    states.${bucket}: ${name}${mark(name)}`)
+  }
+  const stages = releaseStages(config)
+  if (stages.length) {
+    lines.push(`    release.stages: ${stages.length} rung(s), in order`)
+    stages.forEach((stage, i) => {
+      lines.push(`      ${i + 1}. ${stage.key} -> ${stage.state}${mark(stage.state)}`)
+    })
+  }
+  return lines
+}
+
 /**
  * `spec-sync apply <spec> --plan <file> [--via api|mcp] [--project <id>]`
  *
@@ -1729,6 +2081,10 @@ function specSyncInitConfig(dir, flags, out) {
   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 }
+  // The ladder, in the order given. `mergeConfig` below is what validates the
+  // shape — a blank key or a duplicate fails there, in one place, rather than
+  // being re-checked here and drifting from the loader.
+  if (flags.stages.length) draft.release = { stages: flags.stages }
 
   for (const bucket of Object.keys(flags.stateNames)) {
     if (!LIFECYCLE_BUCKETS.includes(bucket)) {
@@ -1768,9 +2124,11 @@ function specSyncInitConfig(dir, flags, out) {
     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}"`)
+      for (const { bucket, label, configured, suggestion } of stateSuggestions(effective, workspace)) {
+        lines.push(`  ${label}: "${configured}" is not an issue state in this workspace`)
+        // `--state <bucket>=<name>` only addresses the bucket map; a ladder rung
+        // is edited in the config, and never carries a suggestion anyway.
+        if (suggestion && bucket) lines.push(`    pass --state ${bucket}="${suggestion}"`)
       }
       lines.push(
         '',
@@ -2083,10 +2441,13 @@ async function specSync(rest, io = {}) {
   // 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,
-    mcp: null, force: false, yes: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null }
+    mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, statesFile: null, stages: [] }
   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
+    // `stage` writes only on --apply: the dry run is the default so a wrong
+    // range is seen before it is acted on, not after.
+    else if (args[i] === '--apply') flags.apply = 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] === '--mcp') flags.mcp = path.resolve(args[++i])
@@ -2123,6 +2484,11 @@ async function specSync(rest, io = {}) {
       // 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] === '--stage') {
+      // `--stage test="On Test"`, repeatable. Order matters and is the order
+      // given, so the ladder is written exactly as the operator listed it.
+      const [key, ...rest] = String(args[++i] || '').split('=')
+      flags.stages.push({ key: String(key).trim(), state: 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])
@@ -2200,8 +2566,10 @@ async function specSync(rest, io = {}) {
       return (await specSyncStates(dir, config, flags, out)) || 0
     case 'released':
       return (await specSyncReleased(dir, config, positional[0], flags, out)) || 0
+    case 'stage':
+      return (await specSyncStage(dir, config, positional[0], positional[1], flags, out)) || 0
     case 'ref':
-      return specSyncRef(dir, config, flags, out, err) || 0
+      return specSyncRef(dir, config, positional[0], flags, out, err) || 0
     case 'retarget':
       return (await specSyncRetarget(dir, config, flags, out)) || 0
     case 'apply':
@@ -2224,8 +2592,9 @@ 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 ref [--json]\n' +
+        '       skitterspec spec-sync ref [<spec>] [--json]\n' +
         '       skitterspec spec-sync released [<range>] [--json]\n' +
+        '       skitterspec spec-sync stage <key> [<range>] [--apply] [--json]\n' +
         '       skitterspec spec-sync retarget [--yes]\n' +
         '       skitterspec spec-sync doctor [--check-remote] [--mcp <file>] [--json]\n' +
         '       skitterspec spec-sync init-config --team-id <id> [--team-key K] [--project-id id]\n' +