@skitterbyte/skitterspec-linear 10.5.2 → 10.7.0

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

@@ -23,7 +23,10 @@
 const fs = require('node:fs')
 const path = require('node:path')
 
-const { BUCKETS, findSpecFolder } = require('../../env/resolve.js')
+const { BUCKETS, findSpecFolder, branchFor, splitPrefix, currentBranch } = require('../../env/resolve.js')
+const { loadEnvConfig } = require('../../env/config.js')
+const { ticketsInRange, partitionStageMoves, stageOrderWarning } = require('./released.js')
+const { execFileSync } = require('node:child_process')
 const {
   normalizeLocal,
   readSnapshot,
@@ -35,6 +38,8 @@ const {
   planChanges,
   isEmptyPlan,
   remoteWorkflowState,
+  remoteStage,
+  LADDER_ORIGIN_BUCKET,
   validateStates,
   stateSuggestions,
   lintPhases,
@@ -49,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 {
@@ -323,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(
@@ -474,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')
@@ -613,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)
 
@@ -632,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.')
 
@@ -722,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 }
 }
 
 /**
@@ -844,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
 }
 
@@ -860,6 +898,465 @@ function countSkills(dir) {
   }
 }
 
+/**
+ * `spec-sync released [<range>] [--json]` — the tickets a release contains.
+ *
+ * Read-only, and deliberately so: it reports what shipped, it does not move
+ * anything. A release can be cut and never deployed, and workflow state is
+ * pushed from a spec's lifecycle bucket — "released" is not one, so moving
+ * tickets here would be a new kind of write with no dry run.
+ *
+ * The default range is the most recent tag reachable from HEAD, resolved with
+ * `git describe` rather than by knowing a tag scheme. This repo tags
+ * `name@version`, but a consumer may tag `v1.2.3` — and the scheme lives in
+ * `scripts/`, which is not shipped. The chosen range is always printed, so a
+ * wrong guess is visible rather than silent.
+ */
+/**
+ * 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()
+    } catch {
+      return null
+    }
+  }
+
+  let range = rangeArg
+  if (!range) {
+    const tag = (git(['describe', '--tags', '--abbrev=0']) || '').trim()
+    if (!tag) {
+      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) {
+    return { error: [`spec-sync ${verb}: git could not resolve the range "${range}".`] }
+  }
+
+  const commits = raw
+    .split('\x1e')
+    .map((r) => r.replace(/^\n/, ''))
+    .filter((r) => r.trim())
+    .map((record) => {
+      const [sha, subject, ...rest] = record.split('\x00')
+      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
+  // transport, or a read failure degrades to bare refs — never a failure.
+  const key = resolveApiKey(config, flags.env || process.env)
+  const transport = flags.via || (config.apply && config.apply.transport) || (key.ok ? 'api' : 'mcp')
+  let titles = null
+  let titleNote = ''
+  if (report.tickets.length && transport === 'api') {
+    const adapter = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
+    titles = {}
+    for (const t of report.tickets) {
+      try {
+        const issue = await adapter.readIssue(t.ref)
+        if (issue && issue.title) titles[t.ref] = issue.title
+      } catch {
+        titleNote = '  (titles unavailable — Linear could not be read)'
+        titles = null
+        break
+      }
+    }
+  } else if (report.tickets.length) {
+    titleNote = `  (titles unavailable — transport = ${transport})`
+  }
+
+  if (flags.json) {
+    out.write(JSON.stringify({ range, ...report, titles }, null, 2) + '\n')
+    return 0
+  }
+
+  const lines = [`spec-sync released: ${range}`, '']
+  if (!report.tickets.length) lines.push('  no ticket references found')
+  for (const t of report.tickets) {
+    const title = titles && titles[t.ref] ? `  ${titles[t.ref]}` : ''
+    lines.push(`  ${t.ref}${title}`)
+  }
+  if (titleNote) lines.push(titleNote)
+  lines.push('')
+  lines.push(`  ${report.tickets.length} ticket(s) in ${report.total} commit(s)`)
+  // Said even when zero: a chore commit legitimately carries no ticket and a
+  // MISSED trailer looks identical, so silence here would read as "everything is
+  // accounted for".
+  lines.push(`  ${report.unreferenced} commit(s) carry no ref`)
+  out.write(lines.join('\n') + '\n')
+  return 0
+}
+
+/**
+ * `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
+ * rule would drift from the one that created the branch.
+ *
+ * **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 `$(…)`. 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, 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()
+    } catch {
+      return null
+    }
+  }
+  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
+  }
+
+  const env = loadEnvConfig(dir).config
+  let match = null
+  for (const bucket of BUCKETS) {
+    let entries
+    try {
+      entries = fs.readdirSync(path.join(dir, 'specs', bucket), { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const specPath = path.join(dir, 'specs', bucket, entry.name)
+      const { type, slug } = splitPrefix(entry.name)
+      if (branchFor({ type, slug, path: specPath }, env) === branch) {
+        match = { folder: entry.name, bucket, path: specPath }
+        break
+      }
+    }
+    if (match) break
+  }
+
+  if (!match) {
+    say(`branch "${branch}" is not a spec branch — no ticket to reference`)
+    return 1
+  }
+
+  return emitRef(match, branch)
+}
+
 /**
  * `spec-sync retarget [--yes]` — repoint a mirror after a team-key rename.
  *
@@ -1077,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>]`
  *
@@ -1556,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)) {
@@ -1595,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(
         '',
@@ -1910,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])
@@ -1950,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])
@@ -2025,6 +2564,12 @@ async function specSync(rest, io = {}) {
       return (await specSyncProjects(dir, config, flags, out)) || 0
     case 'states':
       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, positional[0], flags, out, err) || 0
     case 'retarget':
       return (await specSyncRetarget(dir, config, flags, out)) || 0
     case 'apply':
@@ -2047,6 +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 [<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' +