@skitterbyte/skitterspec-linear 18.3.1 → 19.1.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.
Files changed (36) hide show
  1. package/MIGRATION.md +170 -1
  2. package/README.md +9 -7
  3. package/assets/core/SETUP.md +4 -4
  4. package/assets/core/env.config.md +1 -1
  5. package/assets/core/linear.config.json.example +2 -1
  6. package/assets/core/linear.config.md +59 -48
  7. package/assets/rules/spec-planning.md +35 -12
  8. package/assets/rules/spec-reports.md +47 -6
  9. package/assets/skills/no-spec/SKILL.md +2 -2
  10. package/assets/skills/spec/SKILL.md +32 -9
  11. package/assets/skills/spec-bug/SKILL.md +6 -4
  12. package/assets/skills/spec-hotfix/SKILL.md +4 -2
  13. package/assets/skills/spec-linear-setup/SKILL.md +9 -35
  14. package/assets/skills/spec-list/SKILL.md +13 -1
  15. package/assets/skills/spec-next/SKILL.md +5 -3
  16. package/assets/skills/spec-push/SKILL.md +1 -1
  17. package/assets/skills/spec-status/SKILL.md +30 -26
  18. package/assets/skills/spec-sync/SKILL.md +6 -5
  19. package/package.json +1 -1
  20. package/src/cli.js +114 -28
  21. package/src/env/resolve.js +11 -4
  22. package/src/env/review.js +126 -2
  23. package/src/vendor/linear/api.js +30 -1
  24. package/src/vendor/linear/cli-sync.js +64 -269
  25. package/src/vendor/linear/config.js +30 -49
  26. package/src/vendor/linear/doctor.js +4 -66
  27. package/src/vendor/provider-kit/src/config.js +101 -48
  28. package/src/vendor/provider-kit/src/list-assignee.js +71 -0
  29. package/src/vendor/provider-kit/src/list-rows.js +35 -0
  30. package/src/vendor/provider-kit/src/released.js +27 -77
  31. package/src/vendor/provider-kit/src/specs.js +89 -7
  32. package/src/vendor/sync-core/index.js +3 -4
  33. package/src/vendor/sync-core/src/compare.js +6 -6
  34. package/src/vendor/sync-core/src/normalize.js +60 -59
  35. package/assets/core/ci-stages.md +0 -110
  36. package/src/vendor/provider-kit/src/releases.js +0 -380
@@ -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}`)
@@ -2445,8 +2226,32 @@ function describeRefusal(error) {
2445
2226
  * stripped (`withoutNull`) except the assignee clear, and the refusal texts
2446
2227
  * name Linear and its commands.
2447
2228
  */
2448
- async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false }) {
2229
+ // A spec's KIND, read off its folder prefix — the same convention the
2230
+ // lifecycle skills stamp into `> **Type:**`, but greppable with no file read.
2231
+ function specKindOf(snapshotDir) {
2232
+ const name = path.basename(String(snapshotDir || ''))
2233
+ if (name.startsWith('bug-')) return 'bug'
2234
+ if (name.startsWith('hotfix-')) return 'hotfix'
2235
+ if (name.startsWith('chore-')) return 'chore'
2236
+ return 'feature'
2237
+ }
2238
+
2239
+ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false, out = null }) {
2449
2240
  const stateId = (bucket) => (bucket ? stateIdFor(bucket, config, states) : null)
2241
+ // THIS spec's kind label (linear.labelsByKind), resolved name → id once per
2242
+ // apply. A label Linear does not have is a one-line note and an unlabelled
2243
+ // mint, never a failed push — and with nothing configured, no label call is
2244
+ // made at all.
2245
+ const kindLabelName = (config.linear && config.linear.labelsByKind && config.linear.labelsByKind[specKindOf(snapshotDir)]) || ''
2246
+ let kindLabelIds = null
2247
+ if (kindLabelName && teamId && typeof adapter.listLabels === 'function') {
2248
+ const labels = await adapter.listLabels(teamId)
2249
+ const hit = labels.find((l) => l && String(l.name).toLowerCase() === kindLabelName.toLowerCase())
2250
+ if (hit) kindLabelIds = [hit.id]
2251
+ else if (out) out.write(` !! label "${kindLabelName}" is not on the team — minted without it\n`)
2252
+ } else if (kindLabelName && out && typeof adapter.listLabels !== 'function') {
2253
+ out.write(` !! label "${kindLabelName}" skipped — this transport cannot list labels\n`)
2254
+ }
2450
2255
  const ops = {
2451
2256
  prevalidateStates: (buckets) => {
2452
2257
  for (const bucket of buckets) stateId(bucket)
@@ -2469,6 +2274,8 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2469
2274
  // Assert only. An issue being minted has no assignee to retract, so
2470
2275
  // `withoutNull` dropping a null here is exactly right.
2471
2276
  assigneeId: (issue && issue.assignee) || null,
2277
+ // The kind's label, when configured and resolved above; null drops out.
2278
+ labelIds: kindLabelIds,
2472
2279
  }))
2473
2280
  if (!created || !created.identifier) throw new Error('Linear returned no issue for the spec create')
2474
2281
  return created
@@ -2623,7 +2430,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2623
2430
  out.write(`spec-sync apply: ${error.message}\n`)
2624
2431
  return 1
2625
2432
  }
2626
- const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew }
2433
+ const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew, out }
2627
2434
 
2628
2435
  if (!bulk) {
2629
2436
  const lines = ['spec-sync apply: transport = api']
@@ -2816,10 +2623,6 @@ function specSyncInitConfig(dir, flags, out) {
2816
2623
  if (flags.hotfixLabels.length) intake.hotfixLabels = flags.hotfixLabels
2817
2624
  if (Object.keys(intake).length) draft.intake = intake
2818
2625
  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
2626
  // Assignment ships ON, so the flag is the OPT-OUT and it writes `none`. The
2824
2627
  // previous `--assign` is gone rather than kept as a no-op: a flag whose meaning
2825
2628
  // the default flip inverted, still accepted and doing nothing, is the
@@ -2872,8 +2675,6 @@ function specSyncInitConfig(dir, flags, out) {
2872
2675
  const lines = ['spec-sync init-config: refusing — configured state name(s) not in the workspace', '']
2873
2676
  for (const { bucket, label, configured, suggestion } of stateSuggestions(effective, workspace)) {
2874
2677
  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
2678
  if (suggestion && bucket) lines.push(` pass --state ${bucket}="${suggestion}"`)
2878
2679
  }
2879
2680
  lines.push(
@@ -3421,7 +3222,7 @@ async function specSync(rest, io = {}) {
3421
3222
  // after the loop.
3422
3223
  const unknownFlags = []
3423
3224
  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 }
3225
+ 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
3226
  for (let i = 0; i < args.length; i++) {
3426
3227
  if (args[i] === '--dir') dir = path.resolve(args[++i])
3427
3228
  else if (args[i] === '--json') flags.json = true
@@ -3495,11 +3296,6 @@ async function specSync(rest, io = {}) {
3495
3296
  const [bucket, ...rest] = raw.split('=')
3496
3297
  flags.stateNames[String(bucket).trim()] = rest.join('=').trim()
3497
3298
  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
3299
  } else if (args[i] === '--states') flags.statesFile = path.resolve(args[++i])
3504
3300
  else if (args[i].startsWith('--')) unknownFlags.push(args[i])
3505
3301
  else positional.push(args[i])
@@ -3600,7 +3396,7 @@ async function specSync(rest, io = {}) {
3600
3396
  case 'released':
3601
3397
  return (await specSyncReleased(dir, config, positional[0], flags, out)) || 0
3602
3398
  case 'stage':
3603
- return (await specSyncStage(dir, config, positional[0], positional[1], flags, out)) || 0
3399
+ return refuseRemovedVerb(out, 'spec-sync', 'stage')
3604
3400
  case 'ref':
3605
3401
  return specSyncRef(dir, config, positional[0], flags, out, err) || 0
3606
3402
  case 'retarget':
@@ -3634,7 +3430,6 @@ async function specSync(rest, io = {}) {
3634
3430
  ' skitterspec spec-sync linked [--json]\n' +
3635
3431
  ' skitterspec spec-sync ref [<spec>] [--json]\n' +
3636
3432
  ' skitterspec spec-sync released [<range>] [--json]\n' +
3637
- ' skitterspec spec-sync stage <key> [<range>] [--apply] [--json]\n' +
3638
3433
  ' skitterspec spec-sync reattach <spec> [--to <ISSUE-REF>] [--json]\n' +
3639
3434
  ' skitterspec spec-sync retarget [--yes]\n' +
3640
3435
  ' skitterspec spec-sync doctor [--check-remote] [--mcp <file>] [--json]\n' +