@skitterbyte/skitterspec-linear 18.3.0 → 19.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -25,7 +25,9 @@ const path = require('node:path')
25
25
 
26
26
  const { BUCKETS, findSpecFolder, branchFor, splitPrefix, currentBranch } = require('../../env/resolve.js')
27
27
  const { loadEnvConfig } = require('../../env/config.js')
28
- const { ticketsInRange, partitionStageMoves, stageOrderWarning } = require('./released.js')
28
+ const { ticketsInRange, nameTickets, refuseRemovedVerb } = require('./released.js')
29
+ const { retiredKeysRow } = require('../provider-kit/src/config.js')
30
+ const { doctorRow } = require('../provider-kit/src/doctor.js')
29
31
  const { execFileSync } = require('node:child_process')
30
32
  const {
31
33
  normalizeLocal,
@@ -37,9 +39,7 @@ const {
37
39
  projectionOf,
38
40
  planChanges,
39
41
  isEmptyPlan,
40
- remoteWorkflowState,
41
- remoteStage,
42
- LADDER_ORIGIN_BUCKET,
42
+ stateNamesFor,
43
43
  validateStates,
44
44
  stateSuggestions,
45
45
  lintPhases,
@@ -64,9 +64,7 @@ const {
64
64
  defaults: configDefaults,
65
65
  CONFIG_FILE,
66
66
  LIFECYCLE_BUCKETS,
67
- releaseStages,
68
67
  releaseIgnorePaths,
69
- stageFor,
70
68
  } = require('./config.js')
71
69
  const { resolveApiKey, makeApiAdapter, stateIdFor, fetchWorkspaceStates } = require('./api.js')
72
70
  const { runChecks } = require('./doctor.js')
@@ -124,7 +122,8 @@ const { applySpecPlan } = require('../provider-kit/src/apply.js')
124
122
  // (`src/specs.js`), keyed by this provider's `config.fields`. `linkedIdentifier`
125
123
  // keeps a config-free arity below for its many local callers.
126
124
  const specHelpers = require('../provider-kit/src/specs.js').makeSpecHelpers({ program: 'spec-sync' })
127
- const { resolveSnapshotDir, specIdentifier, listSpecs, resolveOrExit, warningLines, warnToErr } = specHelpers
125
+ const { resolveSnapshotDir, specIdentifier, listSpecs, listSpecsLive, resolveOrExit, warningLines, warnToErr } = specHelpers
126
+ const { expandStateArgs, specColumn, specCell } = require('../provider-kit/src/list-rows.js')
128
127
 
129
128
  // The stamp key is fixed for this provider, so the config-free arity survives
130
129
  // for the call sites that predate the kit.
@@ -461,21 +460,9 @@ function specSyncStatus(dir, config, specArg, flags, out) {
461
460
 
462
461
  if (flags.remote && fs.existsSync(flags.remote)) {
463
462
  const remote = JSON.parse(fs.readFileSync(flags.remote, 'utf-8'))
464
- const rState = remoteWorkflowState(remote, config)
465
- const lState = projection.status
466
- // A declared deployment stage is POSITION, not disagreement: the spec is
467
- // complete and the pipeline has moved it on. Reporting that as drift would
468
- // accuse every deployed spec, for as long as it sits in the pipeline — and
469
- // "repo wins on next push" would be a lie, since a finished spec's state no
470
- // longer re-pushes (see compare.js `issueChanges`).
471
- const stage = remoteStage(remote, config)
472
- if (stage) {
473
- lines.push(` stage: Linear is at "${stage.state}" (release stage "${stage.key}", past ${lState})`)
474
- } else if (rState && lState && rState !== lState) {
475
- lines.push(` drift: Linear workflow-state is "${rState}" but the spec is "${lState}" (repo wins on next push)`)
476
- } else {
477
- lines.push(' drift: none — Linear workflow-state matches the spec')
478
- }
463
+ // NO STATE LINE, deliberately: skitterspec tells the tracker about its own
464
+ // transitions and never reads a status back. A ticket someone moved there
465
+ // is theirs to have moved, and push resends State only when the spec does.
479
466
  lines.push(...assigneeLines(remote, projection, plan))
480
467
  lines.push(...descriptionDriftLines(remote, snapshot, identifier, config))
481
468
  }
@@ -645,7 +632,6 @@ async function specSyncDoctor(dir, flags, out) {
645
632
  state.mcp = read.facts
646
633
  }
647
634
  if (flags.remoteCheck) state.remote = await checkRemote(state, flags)
648
- if (state.remote && state.remote.issueStates) state.ladder.workspaceStates = state.remote.issueStates
649
635
 
650
636
  const report = runChecks(state)
651
637
 
@@ -755,20 +741,7 @@ async function checkRemote(state, flags) {
755
741
  }
756
742
  }
757
743
 
758
- // Only fetched when a ladder is declared: the rows that do not need state
759
- // types must not pay for a call that answers a question nobody asked.
760
- let issueStates = null
761
- if (releaseStages(state._config).length && typeof adapter.listIssueStates === 'function') {
762
- try {
763
- issueStates = await adapter.listIssueStates(state.tracker.teamId)
764
- } catch {
765
- // Unexamined, on the same rule as the project read: a transport failure is
766
- // not evidence about the ladder's shape.
767
- issueStates = null
768
- }
769
- }
770
-
771
- return { checked: true, ok: true, teamKey: team.key, teamId: team.id, organization, recordedKey: state.tracker.teamKey, project, issueStates }
744
+ return { checked: true, ok: true, teamKey: team.key, teamId: team.id, organization, recordedKey: state.tracker.teamKey, project }
772
745
  }
773
746
 
774
747
  /**
@@ -908,9 +881,7 @@ function gatherState(dir, flags) {
908
881
  }
909
882
 
910
883
  state._config = config
911
- // Declared here, checked only if `--check-remote` fetches the state TYPES the
912
- // shape check needs (see `ladderCheck`). Offline, the row stays `skipped`.
913
- state.ladder = { stages: releaseStages(config) }
884
+ state.retired = retiredKeysRow(path.join(dir, CONFIG_FILE), CONFIG_FILE, doctorRow)
914
885
  return state
915
886
  }
916
887
 
@@ -1088,6 +1059,7 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
1088
1059
  const { range, commits } = read
1089
1060
 
1090
1061
  const report = ticketsInRange(commits, { ignorePaths: releaseIgnorePaths(config) })
1062
+ report.tickets = nameTickets(report.tickets, listSpecs(dir, config, { urls: true }))
1091
1063
 
1092
1064
  // Titles are an ENRICHMENT: the scan itself is offline. No key, the MCP
1093
1065
  // transport, or a read failure degrades to bare refs — never a failure.
@@ -1121,7 +1093,7 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
1121
1093
  if (!report.tickets.length) lines.push(' no ticket references found')
1122
1094
  for (const t of report.tickets) {
1123
1095
  const title = titles && titles[t.ref] ? ` ${titles[t.ref]}` : ''
1124
- lines.push(` ${t.ref}${title}`)
1096
+ lines.push(` ${t.ref}${title}${t.spec ? ` (${t.spec})` : ''}`)
1125
1097
  }
1126
1098
  if (titleNote) lines.push(titleNote)
1127
1099
  lines.push('')
@@ -1140,198 +1112,6 @@ async function specSyncReleased(dir, config, rangeArg, flags, out) {
1140
1112
  return 0
1141
1113
  }
1142
1114
 
1143
- /**
1144
- * `spec-sync stage <key> [<range>] [--apply] [--json]` — move a release's
1145
- * tickets onto a declared deployment rung.
1146
- *
1147
- * The counterpart to `released`, which reports and cannot write. This is the
1148
- * write, and it is deliberately a separate verb: someone typing `released` in a
1149
- * terminal should never be able to move anything.
1150
- *
1151
- * **Dry run is the default.** `--apply` is required to touch Linear, and the
1152
- * resolved range, the target state and the full plan print either way — a wrong
1153
- * range is then visible before it is acted on rather than after.
1154
- *
1155
- * What it refuses to move is as important as what it moves: see
1156
- * `partitionStageMoves`. Every excluded ref is named with its reason, because a
1157
- * silent exclusion and a successful move look identical in a pipeline log.
1158
- */
1159
- async function specSyncStage(dir, config, stageKey, rangeArg, flags, out) {
1160
- const stages = releaseStages(config)
1161
- if (!stages.length) {
1162
- out.write(
1163
- 'spec-sync stage: no deployment ladder is declared.\n' +
1164
- ` Add release.stages to ${CONFIG_FILE} — see its docs for the shape.\n`,
1165
- )
1166
- return 1
1167
- }
1168
- if (!stageKey) {
1169
- out.write(`spec-sync stage: no stage given. Declared: ${stages.map((s) => s.key).join(', ')}\n`)
1170
- return 1
1171
- }
1172
- const stage = stageFor(config, stageKey)
1173
- if (!stage) {
1174
- out.write(
1175
- `spec-sync stage: no stage named ${JSON.stringify(stageKey)}.\n` +
1176
- ` Declared: ${stages.map((s) => s.key).join(', ')}\n`,
1177
- )
1178
- return 1
1179
- }
1180
-
1181
- const read = readCommitRange(dir, rangeArg, 'stage')
1182
- if (read.error) {
1183
- out.write(read.error.join('\n') + '\n')
1184
- return 1
1185
- }
1186
- const { range, commits } = read
1187
-
1188
- const report = ticketsInRange(commits, { ignorePaths: releaseIgnorePaths(config) })
1189
- const teamKey = (config.linear && config.linear.teamKey) || ''
1190
- const parts = partitionStageMoves({
1191
- tickets: report.tickets,
1192
- teamKey,
1193
- specs: listSpecs(dir, config),
1194
- cededBucket: LADDER_ORIGIN_BUCKET,
1195
- })
1196
-
1197
- const key = resolveApiKey(config, flags.env || process.env)
1198
- const transport = resolveTransport(flags, config, key.ok)
1199
- const applying = Boolean(flags.apply)
1200
-
1201
- if (applying && transport !== 'api') {
1202
- out.write(
1203
- `spec-sync stage: refusing to apply over ${transport}.\n` +
1204
- ` ${key.ok ? '--via api is required' : key.error}\n` +
1205
- ' Re-run without --apply for the plan.\n',
1206
- )
1207
- return 1
1208
- }
1209
-
1210
- // Read each movable issue BEFORE any write: it yields the id the update needs,
1211
- // its title for the report, and its current state for the order warning. A ref
1212
- // that cannot be read is dropped from the move rather than guessed at.
1213
- const adapter = transport === 'api' && key.ok ? flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch }) : null
1214
- const moves = []
1215
- const unreadable = []
1216
- for (const ticket of parts.movable) {
1217
- if (!adapter) {
1218
- moves.push({ ...ticket, title: null, from: null, warning: null })
1219
- continue
1220
- }
1221
- let issue = null
1222
- try {
1223
- issue = await adapter.readIssue(ticket.ref)
1224
- } catch {
1225
- issue = null
1226
- }
1227
- if (!issue || !issue.id) {
1228
- unreadable.push(ticket)
1229
- continue
1230
- }
1231
- const from = issue.state && issue.state.name ? issue.state.name : null
1232
- moves.push({
1233
- ...ticket,
1234
- id: issue.id,
1235
- title: issue.title || null,
1236
- from,
1237
- warning: stageOrderWarning(stages, from, stage.key, Object.values(config.states || {})),
1238
- })
1239
- }
1240
-
1241
- let moved = []
1242
- let failed = []
1243
- if (applying && moves.length) {
1244
- let states
1245
- try {
1246
- states = await adapter.listIssueStates((config.linear && config.linear.teamId) || null)
1247
- } catch (error) {
1248
- out.write(`spec-sync stage: could not read the workspace states — ${error.message}\n`)
1249
- return 1
1250
- }
1251
- // Resolve the target id BEFORE the first write, mirroring `apply`: a state
1252
- // name the workspace lacks must fail with nothing moved, not halfway through.
1253
- const target = states.find((st) => st && st.name && st.name.toLowerCase().trim() === stage.state.toLowerCase().trim())
1254
- if (!target) {
1255
- out.write(
1256
- `spec-sync stage: refusing — no issue state named ${JSON.stringify(stage.state)} in this workspace.\n` +
1257
- ` available: ${states.map((st) => st.name).join(', ') || '(none reported)'}\n` +
1258
- ' Linear silently ignores an unknown state, so this would have moved nothing.\n',
1259
- )
1260
- return 1
1261
- }
1262
- for (const move of moves) {
1263
- try {
1264
- await adapter.updateIssue(move.id, { stateId: target.id })
1265
- moved.push(move)
1266
- } catch (error) {
1267
- failed.push({ ...move, error: error.message })
1268
- }
1269
- }
1270
- }
1271
-
1272
- if (flags.json) {
1273
- out.write(
1274
- JSON.stringify(
1275
- {
1276
- range,
1277
- stage: { key: stage.key, state: stage.state },
1278
- applied: applying,
1279
- moves: moves.map((m) => ({ ref: m.ref, title: m.title, from: m.from, warning: m.warning })),
1280
- moved: moved.map((m) => m.ref),
1281
- failed: failed.map((m) => ({ ref: m.ref, error: m.error })),
1282
- skipped: {
1283
- foreign: parts.foreign.map((t) => t.ref),
1284
- unlinked: parts.unlinked.map((t) => t.ref),
1285
- unfinished: parts.unfinished.map((t) => ({ ref: t.ref, bucket: t.bucket })),
1286
- unreadable: unreadable.map((t) => t.ref),
1287
- },
1288
- unreferencedCommits: report.unreferenced,
1289
- ignoredCommits: report.ignored,
1290
- totalCommits: report.total,
1291
- },
1292
- null,
1293
- 2,
1294
- ) + '\n',
1295
- )
1296
- return failed.length ? 1 : 0
1297
- }
1298
-
1299
- const lines = [`spec-sync stage: ${stage.key} -> "${stage.state}" (${range})`, '']
1300
- if (!moves.length) {
1301
- lines.push(applying ? ' moved nothing' : ' would move nothing')
1302
- } else {
1303
- lines.push(` ${applying ? 'moved' : 'would move'} ${applying ? moved.length : moves.length} ticket(s)`)
1304
- for (const m of moves) {
1305
- const title = m.title ? ` ${m.title}` : ''
1306
- lines.push(` ${m.ref}${title}`)
1307
- if (m.warning) lines.push(` warning: ${m.warning}`)
1308
- }
1309
- }
1310
- for (const { label, items } of [
1311
- { label: 'not team ' + (teamKey || '(unset)'), items: parts.foreign.map((t) => t.ref) },
1312
- { label: 'no spec in this repo claims it', items: parts.unlinked.map((t) => t.ref) },
1313
- {
1314
- label: 'spec not complete — push still owns its state',
1315
- items: parts.unfinished.map((t) => `${t.ref} (${t.bucket})`),
1316
- },
1317
- { label: 'could not be read from Linear', items: unreadable.map((t) => t.ref) },
1318
- ]) {
1319
- if (items.length) lines.push(` skipped ${items.length} — ${label}: ${items.join(', ')}`)
1320
- }
1321
- for (const f of failed) lines.push(` FAILED ${f.ref}: ${f.error}`)
1322
- lines.push('')
1323
- // Said even when zero, for the reason `released` says it: a chore commit
1324
- // legitimately carries no ref and a MISSED trailer looks identical, so silence
1325
- // would read as "every commit is accounted for".
1326
- lines.push(` ${report.unreferenced} commit(s) carry no ref, of ${report.total}`)
1327
- if (report.ignored) {
1328
- lines.push(` ${report.ignored} commit(s) ignored as bookkeeping (release.ignorePaths)`)
1329
- }
1330
- if (!applying) lines.push(' dry run — pass --apply to move them')
1331
- out.write(lines.join('\n') + '\n')
1332
- return failed.length ? 1 : 0
1333
- }
1334
-
1335
1115
  /**
1336
1116
  * `spec-sync ref [<spec>] [--json]` — the ticket a commit's work belongs to.
1337
1117
  *
@@ -1665,9 +1445,8 @@ async function specSyncStates(dir, config, flags, out) {
1665
1445
  }
1666
1446
 
1667
1447
  // The state names this project's config points at, shown against what the
1668
- // workspace actually has — the bucket map, then the deployment ladder in its
1669
- // declared order. One command then shows the whole vocabulary, instead of the
1670
- // ladder living only in a file nobody re-reads.
1448
+ // workspace actually has — the bucket map and its aliases, so one command
1449
+ // shows the whole vocabulary.
1671
1450
  //
1672
1451
  // A name the workspace lacks is flagged here but nothing is refused: `states`
1673
1452
  // is a report. The push path is where that is fatal.
@@ -1677,13 +1456,9 @@ function configuredVocabularyLines(config, names) {
1677
1456
  const lines = ['', ' configured:']
1678
1457
  for (const [bucket, name] of Object.entries((config && config.states) || {})) {
1679
1458
  lines.push(` states.${bucket}: ${name}${mark(name)}`)
1680
- }
1681
- const stages = releaseStages(config)
1682
- if (stages.length) {
1683
- lines.push(` release.stages: ${stages.length} rung(s), in order`)
1684
- stages.forEach((stage, i) => {
1685
- lines.push(` ${i + 1}. ${stage.key} -> ${stage.state}${mark(stage.state)}`)
1686
- })
1459
+ for (const alias of stateNamesFor(bucket, config).slice(1)) {
1460
+ lines.push(` also reads as ${bucket}: ${alias}${mark(alias)}`)
1461
+ }
1687
1462
  }
1688
1463
  return lines
1689
1464
  }
@@ -2058,15 +1833,16 @@ async function specSyncList(dir, config, flags, out) {
2058
1833
  // The scope. `--all` drops the state filter; `--state` names states directly;
2059
1834
  // the default reads the two live buckets out of `config.states` rather than
2060
1835
  // restating them, so a workspace that renamed "Backlog" needs no second edit.
1836
+ // Every name of a bucket counts, aliases included (`stateNamesFor`).
2061
1837
  const wantedNames = next !== null
2062
- ? [config.states.backlog]
1838
+ ? stateNamesFor('backlog', config)
2063
1839
  : flags.inProgress === true
2064
- ? [config.states['in-progress']]
1840
+ ? stateNamesFor('in-progress', config)
2065
1841
  : flags.all === true
2066
1842
  ? null
2067
1843
  : flags.stateArgs.length
2068
- ? flags.stateArgs
2069
- : [config.states.backlog, config.states['in-progress']]
1844
+ ? expandStateArgs(flags.stateArgs, config)
1845
+ : [...stateNamesFor('backlog', config), ...stateNamesFor('in-progress', config)]
2070
1846
 
2071
1847
  let stateIds = null
2072
1848
  if (wantedNames) {
@@ -2183,7 +1959,9 @@ async function specSyncList(dir, config, flags, out) {
2183
1959
  // is what every existing caller already reads.
2184
1960
  const ordered = next === null ? issues : issues.slice().sort(backlogOrder)
2185
1961
 
2186
- const localSpecs = listSpecs(dir, config)
1962
+ // Each spec's bucket from where it actually lives — its own worktree when it
1963
+ // has one — since on the base branch an in-flight spec still reads backlog.
1964
+ const localSpecs = listSpecsLive(dir, config)
2187
1965
  const byIdentifier = new Map(
2188
1966
  localSpecs
2189
1967
  .filter((s) => s.identifier)
@@ -2224,6 +2002,7 @@ async function specSyncList(dir, config, flags, out) {
2224
2002
  // close, so hiding it would defeat the command.
2225
2003
  spec: local ? local.spec : null,
2226
2004
  bucket: local ? local.bucket : null,
2005
+ disagrees: specColumn((issue.state && issue.state.name) || null, local, config).disagrees,
2227
2006
  assignee: (issue.assignee && issue.assignee.name) || null,
2228
2007
  // Filled in below for in-progress rows only; `null` on every row that was
2229
2008
  // never looked up, so the shape does not vary by state.
@@ -2265,10 +2044,10 @@ async function specSyncList(dir, config, flags, out) {
2265
2044
  // One extra Linear call per in-progress row, and NONE for any other — a
2266
2045
  // backlog listing costs exactly what it did before. Run over `shown`, not
2267
2046
  // `rows`, so a capped listing does not pay for phases it will not print.
2268
- const inProgressState = config.states['in-progress']
2047
+ const inProgressStates = stateNamesFor('in-progress', config)
2269
2048
  const phaseFailures = []
2270
2049
  for (const row of shown) {
2271
- if (!sameState(row.state, inProgressState)) continue
2050
+ if (!inProgressStates.some((name) => sameState(row.state, name))) continue
2272
2051
  // An `inline`-mode spec keeps its phases in the issue DESCRIPTION, so there
2273
2052
  // are no children to read. Asking anyway would report "no phase in progress"
2274
2053
  // for a spec that is mid-build — an absence that means nothing. The bucket
@@ -2289,7 +2068,7 @@ async function specSyncList(dir, config, flags, out) {
2289
2068
  continue
2290
2069
  }
2291
2070
  const phases = (children || []).slice().sort(phaseOrder)
2292
- const live = phases.filter((c) => c && sameState(c.state && c.state.name, inProgressState))
2071
+ const live = phases.filter((c) => c && inProgressStates.some((name) => sameState(c.state && c.state.name, name)))
2293
2072
  if (!live.length) continue
2294
2073
  row.phase = {
2295
2074
  n: phases.indexOf(live[0]) + 1,
@@ -2359,7 +2138,9 @@ async function specSyncList(dir, config, flags, out) {
2359
2138
  } else {
2360
2139
  const idW = Math.max(...shown.map((r) => r.identifier.length))
2361
2140
  const stW = Math.max(...shown.map((r) => r.state.length))
2362
- const pad = ' '.repeat(idW + stW + 4)
2141
+ const cell = (r) => specCell({ specStatus: r.bucket, disagrees: r.disagrees })
2142
+ const bkW = Math.max(...shown.map((r) => cell(r).length))
2143
+ const pad = ' '.repeat(idW + stW + bkW + 6)
2363
2144
  const specW = Math.max(...shown.map((r) => (r.spec || UNLINKED).length))
2364
2145
  for (const row of shown) {
2365
2146
  // Who holds it, and where the work is — the two things the repo could not
@@ -2368,7 +2149,7 @@ async function specSyncList(dir, config, flags, out) {
2368
2149
  // nothing but width.
2369
2150
  const held = [row.assignee, phaseLabel(row.phase)].filter(Boolean).join(' · ')
2370
2151
  lines.push(
2371
- ` ${row.identifier.padEnd(idW)} ${row.state.padEnd(stW)} ` +
2152
+ ` ${row.identifier.padEnd(idW)} ${row.state.padEnd(stW)} ${cell(row).padEnd(bkW)} ` +
2372
2153
  (held ? `${(row.spec || UNLINKED).padEnd(specW)} ${held}` : row.spec || UNLINKED),
2373
2154
  )
2374
2155
  if (row.title) lines.push(` ${pad}${row.title}`)
@@ -2816,10 +2597,6 @@ function specSyncInitConfig(dir, flags, out) {
2816
2597
  if (flags.hotfixLabels.length) intake.hotfixLabels = flags.hotfixLabels
2817
2598
  if (Object.keys(intake).length) draft.intake = intake
2818
2599
  if (Object.keys(flags.stateNames).length) draft.states = { ...flags.stateNames }
2819
- // The ladder, in the order given. `mergeConfig` below is what validates the
2820
- // shape — a blank key or a duplicate fails there, in one place, rather than
2821
- // being re-checked here and drifting from the loader.
2822
- if (flags.stages.length) draft.release = { stages: flags.stages }
2823
2600
  // Assignment ships ON, so the flag is the OPT-OUT and it writes `none`. The
2824
2601
  // previous `--assign` is gone rather than kept as a no-op: a flag whose meaning
2825
2602
  // the default flip inverted, still accepted and doing nothing, is the
@@ -2872,8 +2649,6 @@ function specSyncInitConfig(dir, flags, out) {
2872
2649
  const lines = ['spec-sync init-config: refusing — configured state name(s) not in the workspace', '']
2873
2650
  for (const { bucket, label, configured, suggestion } of stateSuggestions(effective, workspace)) {
2874
2651
  lines.push(` ${label}: "${configured}" is not an issue state in this workspace`)
2875
- // `--state <bucket>=<name>` only addresses the bucket map; a ladder rung
2876
- // is edited in the config, and never carries a suggestion anyway.
2877
2652
  if (suggestion && bucket) lines.push(` pass --state ${bucket}="${suggestion}"`)
2878
2653
  }
2879
2654
  lines.push(
@@ -3421,7 +3196,7 @@ async function specSync(rest, io = {}) {
3421
3196
  // after the loop.
3422
3197
  const unknownFlags = []
3423
3198
  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,
3424
- mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, stateArgs: [], statesFile: null, stages: [], limit: null, next: null, archived: false, noAssign: false, mine: false, by: null, inProgress: false, text: null }
3199
+ mcp: null, force: false, yes: false, apply: false, remoteCheck: false, teamId: '', teamKey: '', projectId: '', intakeLabel: '', bugLabels: [], hotfixLabels: [], stateNames: {}, stateArgs: [], statesFile: null, limit: null, next: null, archived: false, noAssign: false, mine: false, by: null, inProgress: false, text: null }
3425
3200
  for (let i = 0; i < args.length; i++) {
3426
3201
  if (args[i] === '--dir') dir = path.resolve(args[++i])
3427
3202
  else if (args[i] === '--json') flags.json = true
@@ -3495,11 +3270,6 @@ async function specSync(rest, io = {}) {
3495
3270
  const [bucket, ...rest] = raw.split('=')
3496
3271
  flags.stateNames[String(bucket).trim()] = rest.join('=').trim()
3497
3272
  if (raw) flags.stateArgs.push(raw)
3498
- } else if (args[i] === '--stage') {
3499
- // `--stage test="On Test"`, repeatable. Order matters and is the order
3500
- // given, so the ladder is written exactly as the operator listed it.
3501
- const [key, ...rest] = String(args[++i] || '').split('=')
3502
- flags.stages.push({ key: String(key).trim(), state: rest.join('=').trim() })
3503
3273
  } else if (args[i] === '--states') flags.statesFile = path.resolve(args[++i])
3504
3274
  else if (args[i].startsWith('--')) unknownFlags.push(args[i])
3505
3275
  else positional.push(args[i])
@@ -3600,7 +3370,7 @@ async function specSync(rest, io = {}) {
3600
3370
  case 'released':
3601
3371
  return (await specSyncReleased(dir, config, positional[0], flags, out)) || 0
3602
3372
  case 'stage':
3603
- return (await specSyncStage(dir, config, positional[0], positional[1], flags, out)) || 0
3373
+ return refuseRemovedVerb(out, 'spec-sync', 'stage')
3604
3374
  case 'ref':
3605
3375
  return specSyncRef(dir, config, positional[0], flags, out, err) || 0
3606
3376
  case 'retarget':
@@ -3634,7 +3404,6 @@ async function specSync(rest, io = {}) {
3634
3404
  ' skitterspec spec-sync linked [--json]\n' +
3635
3405
  ' skitterspec spec-sync ref [<spec>] [--json]\n' +
3636
3406
  ' skitterspec spec-sync released [<range>] [--json]\n' +
3637
- ' skitterspec spec-sync stage <key> [<range>] [--apply] [--json]\n' +
3638
3407
  ' skitterspec spec-sync reattach <spec> [--to <ISSUE-REF>] [--json]\n' +
3639
3408
  ' skitterspec spec-sync retarget [--yes]\n' +
3640
3409
  ' skitterspec spec-sync doctor [--check-remote] [--mcp <file>] [--json]\n' +
@@ -20,7 +20,7 @@
20
20
  * intake: { label, bugLabels, hotfixLabels, preserveOriginal },
21
21
  * mapping: { specFolder, phases, tasks },
22
22
  * states: { backlog, "in-progress", complete, cancelled },
23
- * release: { stages: [{ key, state }] },
23
+ * release: { ignorePaths },
24
24
  * snapshot: { overviewFile },
25
25
  * branch: { pattern },
26
26
  * sync: {
@@ -89,19 +89,6 @@ const TRANSPORTS = Object.freeze(['api', 'mcp'])
89
89
  // nothing secret is ever written to the repo.
90
90
  const DEFAULT_KEY_ENV = 'LINEAR_API_KEY'
91
91
 
92
- // The project's OWN deployment ladder: where a ticket goes AFTER its spec is
93
- // complete — deployed to test, approved for demo, live in prod. Deliberately an
94
- // open, ORDERED list in the project's vocabulary rather than a fixed set: one
95
- // team's `On Test`/`Ready for Demo` is another's `staging`, and most projects
96
- // have none at all. Empty (the default) means the project declared no ladder,
97
- // and every stage-aware path is simply unused.
98
- //
99
- // It is NOT keyed by lifecycle bucket, unlike `states` and `mapping.phases`.
100
- // A deployment stage is a fact about an ENVIRONMENT, and no folder under
101
- // `specs/` can ever derive one — which is why it must not join
102
- // LIFECYCLE_BUCKETS.
103
- const DEFAULT_RELEASE_STAGES = Object.freeze([])
104
-
105
92
  // Repo-relative path prefixes whose commits are BOOKKEEPING, not shipped work.
106
93
  //
107
94
  // A spec's `chore(spec): complete <name>` commit carries the same `Refs:`
@@ -179,12 +166,9 @@ const DEFAULT_CONFIG = Object.freeze({
179
166
  legacyIdentifier: 'linear_project_id',
180
167
  legacyIssueId: 'linear_milestone_id',
181
168
  }),
182
- // See DEFAULT_RELEASE_STAGES above. `stages` is ordered: the order is recorded
183
- // for reporting and doctor's ladder check, and deliberately NOT enforced — a
184
- // rollback from test and a hotfix going straight to prod are both legitimate.
185
- // `ignorePaths` (see DEFAULT_RELEASE_IGNORE_PATHS) is what `released`/`stage`
186
- // treat as bookkeeping rather than shipped work.
187
- release: Object.freeze({ stages: DEFAULT_RELEASE_STAGES, ignorePaths: DEFAULT_RELEASE_IGNORE_PATHS }),
169
+ // `ignorePaths` (see DEFAULT_RELEASE_IGNORE_PATHS) is what `released` treats
170
+ // as bookkeeping rather than shipped work.
171
+ release: Object.freeze({ ignorePaths: DEFAULT_RELEASE_IGNORE_PATHS }),
188
172
  branch: Object.freeze({ pattern: '{type}/{slug}' }),
189
173
  // `keyEnv` names the env var holding the personal API key. It is a NAME, not a
190
174
  // key: putting the secret itself here would commit it.
@@ -289,10 +273,10 @@ function defaults() {
289
273
  },
290
274
  mapping: { ...DEFAULT_CONFIG.mapping },
291
275
  states: { ...DEFAULT_CONFIG.states },
276
+ stateAliases: {},
292
277
  snapshot: { ...DEFAULT_CONFIG.snapshot },
293
278
  fields: { ...DEFAULT_CONFIG.fields },
294
279
  release: {
295
- stages: DEFAULT_CONFIG.release.stages.map((s) => ({ ...s })),
296
280
  ignorePaths: [...DEFAULT_CONFIG.release.ignorePaths],
297
281
  },
298
282
  branch: { ...DEFAULT_CONFIG.branch },
@@ -312,7 +296,7 @@ function defaults() {
312
296
  // vocabularies; `mergeConfig` below is the part that is Linear's — which keys
313
297
  // exist and how they nest.
314
298
  const { isObject, stringList, assign } = kitConfig
315
- const { mergeFieldOwnership, mergePhaseMapping, mergeReleaseStages, mergeReleaseIgnorePaths, mergeKeyedFields } =
299
+ const { mergeStates, mergeFieldOwnership, mergePhaseMapping, mergeReleaseIgnorePaths, mergeKeyedFields } =
316
300
  kitConfig.makeMergeHelpers({
317
301
  configFile: CONFIG_FILE,
318
302
  ownership: OWNERSHIP,
@@ -361,18 +345,13 @@ function mergeConfig(base, parsed) {
361
345
  mergePhaseMapping(base.mapping, parsed.mapping)
362
346
  }
363
347
 
364
- if (isObject(parsed.states)) {
365
- for (const key of Object.keys(base.states)) {
366
- assign(base.states, parsed.states, key, 'string')
367
- }
368
- }
348
+ mergeStates(base, parsed)
369
349
 
370
350
  if (isObject(parsed.snapshot)) {
371
351
  assign(base.snapshot, parsed.snapshot, 'overviewFile', 'string')
372
352
  }
373
353
 
374
354
  if (isObject(parsed.release)) {
375
- mergeReleaseStages(base.release, parsed.release)
376
355
  mergeReleaseIgnorePaths(base.release, parsed.release)
377
356
  }
378
357
 
@@ -414,8 +393,7 @@ function mergeConfig(base, parsed) {
414
393
  * Returns `{ config, present }`:
415
394
  * - missing file → `{ config: defaults, present: false }` (opt-out; never throws)
416
395
  * - present → `{ config: merged, present: true }`
417
- * Malformed JSON, a bad `fieldOwnership` enum, or a malformed `release.stages`
418
- * entry → throws a clear Error.
396
+ * Malformed JSON or a bad `fieldOwnership` enum → throws a clear Error.
419
397
  */
420
398
  // Attach the parts of the provider contract that are code, not JSON: the
421
399
  // markdown dialect (sync-core calls its hooks wherever it used to hardcode
@@ -454,21 +432,6 @@ function loadLinearConfig(dir = process.cwd()) {
454
432
  return { config: withRuntime(mergeConfig(base, parsed)), present: true }
455
433
  }
456
434
 
457
- /**
458
- * The project's declared deployment ladder, always an array (empty = none
459
- * declared). Callers read this rather than reaching into the config, so an
460
- * older config object without a `release` block cannot throw.
461
- */
462
- function releaseStages(config) {
463
- const stages = config && config.release && config.release.stages
464
- return Array.isArray(stages) ? stages : []
465
- }
466
-
467
- /** The ladder rung with this key, or null. */
468
- function stageFor(config, key) {
469
- return releaseStages(config).find((s) => s.key === key) || null
470
- }
471
-
472
435
  /**
473
436
  * The path prefixes whose commits are bookkeeping, always an array.
474
437
  *
@@ -484,9 +447,7 @@ function releaseIgnorePaths(config) {
484
447
 
485
448
  module.exports = {
486
449
  loadLinearConfig,
487
- releaseStages,
488
450
  releaseIgnorePaths,
489
- stageFor,
490
451
  mergeConfig,
491
452
  defaults,
492
453
  DEFAULT_CONFIG,