@skitterbyte/skitterspec-linear 19.11.0 → 19.13.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.
@@ -138,7 +138,7 @@ async function specSyncBoard(dir, config, specArg, flags, out) {
138
138
  const specSyncWhoami = (dir, config, flags, out) => assignment.whoami(dir, config, flags, out)
139
139
  const specSyncUsers = (dir, config, query, flags, out) => assignment.users(dir, config, query, flags, out)
140
140
  const { readAllStdin, promptHidden } = require('../provider-kit/src/prompt.js')
141
- const { applySpecPlan } = require('../provider-kit/src/apply.js')
141
+ const { applySpecPlan, heldFlags, heldOverMcp } = require('../provider-kit/src/apply.js')
142
142
 
143
143
  // Spec resolution, listing and lint reporting come from the provider kit
144
144
  // (`src/specs.js`), keyed by this provider's `config.fields`. `linkedIdentifier`
@@ -178,6 +178,109 @@ function specSyncLinked(dir, config, flags, out) {
178
178
  out.write(lines.join('\n') + '\n')
179
179
  }
180
180
 
181
+ // `idea add|list|drop` — the store `skitterspec idea` hands Linear: an issue in
182
+ // the configured team carrying `intake.ideaLabel`, deliberately in NO project.
183
+ // A project is where specs live; a parked thought does not belong to one.
184
+ // `/spec KEY-N` adopts an idea like any other issue, which is why an adopted
185
+ // one drops out of `list`.
186
+ //
187
+ // API only. Without a key a capture REFUSES (exit 1) and hands the text back —
188
+ // a write that did not happen must not read as one that did — while the
189
+ // listing exits 0 with `count: null`, because zero ideas and "could not ask"
190
+ // are different answers.
191
+ async function specSyncIdea(dir, config, positional, flags, out) {
192
+ const [verb, ...words] = positional
193
+ const label = config.intake.ideaLabel
194
+ const teamId = config.linear.teamId
195
+ const text = words.join(' ')
196
+ const say = (json, lines) => out.write(flags.json ? JSON.stringify(json, null, 2) + '\n' : lines.join('\n') + '\n')
197
+ const refuse = (reason, extra = {}) => {
198
+ const back = verb === 'add' && text ? `\n your idea, so nothing is lost:\n ${text.replace(/\n/g, '\n ')}` : ''
199
+ say({ ok: false, store: 'linear', refused: reason, ...extra }, [`spec-sync idea: ${reason}${back}`])
200
+ return 1
201
+ }
202
+ if (!['add', 'list', 'drop'].includes(verb)) {
203
+ out.write('Usage: skitterspec spec-sync idea add <text> | list [--count] | drop <KEY-N> [--reason <why>] [--json]\n')
204
+ return verb ? 1 : 0
205
+ }
206
+ if (!label) return refuse('intake.ideaLabel is empty — an idea is an issue carrying that label, so set one')
207
+ if (!teamId) return refuse('linear.teamId is not set — an idea is filed in the configured team')
208
+
209
+ const key = resolveApiKey(config, flags.env || process.env)
210
+ if (resolveTransport(flags, config, key.ok) === 'mcp' || !key.ok) {
211
+ const why = key.ok ? '--via mcp was requested' : key.error.split('\n')[0]
212
+ if (verb === 'list') {
213
+ say({ store: 'linear', count: null, ideas: null }, [`spec-sync idea: needs the API — ${why}`])
214
+ return 0
215
+ }
216
+ return refuse(`needs the API — ${why}; nothing was written`, verb === 'add' ? { text } : {})
217
+ }
218
+ const linear = flags.adapter || makeApiAdapter({ apiKey: key.key, fetch: flags.fetch })
219
+
220
+ const open = async () => {
221
+ const claimed = new Set(listSpecs(dir, config).map((s) => s.identifier).filter(Boolean))
222
+ const issues = await linear.searchIssues({ label, teamId, openOnly: true })
223
+ return issues.filter((i) => !claimed.has(i.identifier))
224
+ }
225
+
226
+ try {
227
+ if (verb === 'add') {
228
+ const lines = text.replace(/\r\n/g, '\n').split('\n')
229
+ const at = lines.findIndex((l) => l.trim())
230
+ if (at === -1) return refuse('nothing to capture — give the idea some text')
231
+ const title = lines[at].trim()
232
+ const description = lines.slice(at + 1).join('\n').trim()
233
+ const found = (await linear.listLabels(teamId)).find((l) => String(l.name).toLowerCase() === label.toLowerCase())
234
+ if (!found) return refuse(`the team has no "${label}" label — create it in Linear, or set intake.ideaLabel`, { text })
235
+ const made = await linear.createIssue({ teamId, title, description, labelIds: [found.id] })
236
+ say({ ok: true, store: 'linear', action: 'add', identifier: made.identifier, url: made.url, title }, [
237
+ `spec-sync idea: filed ${made.identifier} "${title}" (labelled "${label}", in no project)`,
238
+ ` url: ${made.url}`,
239
+ ` promote: /spec ${made.identifier}`,
240
+ ])
241
+ return 0
242
+ }
243
+
244
+ if (verb === 'list') {
245
+ const ideas = (await open()).map((i) => ({ identifier: i.identifier, title: i.title, url: i.url, promote: `/spec ${i.identifier}` }))
246
+ if (flags.count) {
247
+ say({ store: 'linear', count: ideas.length }, [String(ideas.length)])
248
+ return 0
249
+ }
250
+ say(
251
+ { store: 'linear', label, ideas },
252
+ ideas.length
253
+ ? [`spec-sync idea: "${label}"`, ...ideas.map((i) => ` ${i.identifier}\t${i.title || ''}`)]
254
+ : [`spec-sync idea: nothing waiting under "${label}"`],
255
+ )
256
+ return 0
257
+ }
258
+
259
+ // drop. The open-ideas listing is the positive signal that the reference
260
+ // IS an idea — closing an arbitrary issue under that name is the expensive
261
+ // mistake here, so anything not in it is refused and left alone.
262
+ const ref = words[0]
263
+ if (!ref) return refuse('name the idea to drop — `idea list` shows them')
264
+ const issue = (await open()).find((i) => i.identifier === ref || i.id === ref)
265
+ if (!issue) return refuse(`${ref} is not an open idea under "${label}" — left alone`)
266
+ const cancelled = (await linear.listIssueStates(teamId)).find((s) => s.type === 'canceled')
267
+ if (!cancelled) return refuse('the team has no cancelled state to move the idea to')
268
+ const why = flags.reason && String(flags.reason).trim() ? String(flags.reason).trim() : 'no reason given'
269
+ await linear.createComment(issue.id, `Dropped as an idea: ${why}`)
270
+ await linear.updateIssue(issue.id, { stateId: cancelled.id })
271
+ say({ ok: true, store: 'linear', action: 'drop', identifier: issue.identifier, title: issue.title, reason: why }, [
272
+ `spec-sync idea: dropped ${issue.identifier} "${issue.title || ''}" — moved to ${cancelled.name} (${why})`,
273
+ ])
274
+ return 0
275
+ } catch (error) {
276
+ if (verb === 'list') {
277
+ say({ store: 'linear', count: null, ideas: null }, [`spec-sync idea: ${error.message}`])
278
+ return 1
279
+ }
280
+ return refuse(`Linear refused — ${error.message}`, verb === 'add' ? { text } : {})
281
+ }
282
+ }
283
+
181
284
  // `spec-sync normalize <spec>` — print the local projection as JSON.
182
285
  function specSyncNormalize(dir, config, specArg, out, err) {
183
286
  const snapshotDir = resolveOrExit(specArg, dir, out)
@@ -432,11 +535,14 @@ function specSyncStamp(dir, config, specArg, flags, out) {
432
535
 
433
536
  // `spec-sync record <spec>` — write the last-pushed snapshot from the CURRENT
434
537
  // files. The skill calls this AFTER applying the plan and stamping new ids.
435
- function specSyncRecord(dir, config, specArg, out) {
538
+ function specSyncRecord(dir, config, specArg, flags, out) {
436
539
  const snapshotDir = resolveOrExit(specArg, dir, out)
437
540
  if (!snapshotDir) return 1
438
541
  const identifier = specIdentifier(snapshotDir, config)
439
- const file = recordPush({ dir, snapshotDir, identifier, config })
542
+ // --held: the hand-applied twin of `apply --hold-state` — the state was left
543
+ // out on purpose, and is recorded as sent so run 2 rewrites nothing.
544
+ const sent = flags && flags.held ? { issue: true, subIssues: new Set() } : null
545
+ const file = recordPush({ dir, snapshotDir, identifier, config, sent })
440
546
  out.write(`spec-sync record: snapshot written → ${path.relative(dir, file).split(path.sep).join('/')}\n`)
441
547
  }
442
548
 
@@ -2309,7 +2415,20 @@ function specKindOf(snapshotDir) {
2309
2415
  return 'feature'
2310
2416
  }
2311
2417
 
2312
- async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, project, states, forceNew = false, out = null }) {
2418
+ async function applyOneSpec({
2419
+ dir,
2420
+ config,
2421
+ snapshotDir,
2422
+ plan,
2423
+ adapter,
2424
+ teamId,
2425
+ project,
2426
+ states,
2427
+ forceNew = false,
2428
+ holdState = false,
2429
+ sendHeld = false,
2430
+ out = null,
2431
+ }) {
2313
2432
  const kind = specKindOf(snapshotDir)
2314
2433
  // Per-kind state resolution: statesByKind[kind] overlays states inside
2315
2434
  // stateIdFor, and a bucket overridden to null resolves to no transition.
@@ -2424,7 +2543,7 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2424
2543
  }))
2425
2544
  },
2426
2545
  }
2427
- return applySpecPlan({ dir, config, snapshotDir, plan, adapter, ops, forceNew })
2546
+ return applySpecPlan({ dir, config, snapshotDir, plan, adapter, ops, forceNew, holdState, sendHeld, program: 'spec-sync' })
2428
2547
  }
2429
2548
 
2430
2549
 
@@ -2460,6 +2579,11 @@ async function applyOneSpec({ dir, config, snapshotDir, plan, adapter, teamId, p
2460
2579
  */
2461
2580
  async function specSyncApply(dir, config, specArg, flags, out) {
2462
2581
  const bulk = flags.all != null
2582
+ const held = heldFlags(flags, 'spec-sync')
2583
+ if (held.error) {
2584
+ out.write(held.error + '\n')
2585
+ return 1
2586
+ }
2463
2587
  if (bulk && !BUCKETS.includes(flags.all)) {
2464
2588
  out.write(`spec-sync apply: --all ${flags.all} is not a bucket (${BUCKETS.join('|')})\n`)
2465
2589
  return 1
@@ -2470,7 +2594,11 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2470
2594
  if (!bulk) {
2471
2595
  snapshotDir = resolveOrExit(specArg, dir, out)
2472
2596
  if (!snapshotDir) return 1
2473
- if (!flags.plan) {
2597
+ if (!flags.plan && held.sendHeld) {
2598
+ // --send-held computes its own. After the merge it is normally empty, and
2599
+ // that empty plan is what tells apply that run 1 held the state.
2600
+ plan = push({ dir, snapshotDir, identifier: specIdentifier(snapshotDir, config), config }).plan
2601
+ } else if (!flags.plan) {
2474
2602
  out.write(
2475
2603
  'spec-sync apply: refusing to run without --plan <file>.\n' +
2476
2604
  ' Get one with: skitterspec spec-sync plan <spec> --json > plan.json\n' +
@@ -2478,11 +2606,13 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2478
2606
  )
2479
2607
  return 1
2480
2608
  }
2481
- try {
2482
- plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
2483
- } catch (error) {
2484
- out.write(`spec-sync apply: cannot read --plan ${flags.plan}: ${error.message}\n`)
2485
- return 1
2609
+ if (flags.plan) {
2610
+ try {
2611
+ plan = JSON.parse(fs.readFileSync(flags.plan, 'utf-8'))
2612
+ } catch (error) {
2613
+ out.write(`spec-sync apply: cannot read --plan ${flags.plan}: ${error.message}\n`)
2614
+ return 1
2615
+ }
2486
2616
  }
2487
2617
 
2488
2618
  // A pre-9.0 mirror reads as unlinked, so its plan is all-creates and applying
@@ -2494,7 +2624,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2494
2624
  )
2495
2625
  return 1
2496
2626
  }
2497
- if (isEmptyPlan(plan)) {
2627
+ if (!held.sendHeld && isEmptyPlan(plan)) {
2498
2628
  out.write('spec-sync apply: nothing to apply — the mirror is up to date.\n')
2499
2629
  return 0
2500
2630
  }
@@ -2523,6 +2653,7 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2523
2653
  ' apply the plan over MCP as /spec-push describes, then run:',
2524
2654
  ' skitterspec spec-sync stamp <spec> --issue … [--sub <ref>=… …]',
2525
2655
  ' skitterspec spec-sync record <spec>',
2656
+ ...[heldOverMcp(held, 'spec-sync')].filter(Boolean),
2526
2657
  ].join('\n') + '\n',
2527
2658
  )
2528
2659
  return 0
@@ -2543,7 +2674,18 @@ async function specSyncApply(dir, config, specArg, flags, out) {
2543
2674
  out.write(`spec-sync apply: ${error.message}\n`)
2544
2675
  return 1
2545
2676
  }
2546
- const shared = { dir, config, adapter, teamId, project: flags.project, states, forceNew: flags.forceNew, out }
2677
+ const shared = {
2678
+ dir,
2679
+ config,
2680
+ adapter,
2681
+ teamId,
2682
+ project: flags.project,
2683
+ states,
2684
+ forceNew: flags.forceNew,
2685
+ holdState: held.holdState,
2686
+ sendHeld: held.sendHeld,
2687
+ out,
2688
+ }
2547
2689
 
2548
2690
  if (!bulk) {
2549
2691
  const lines = ['spec-sync apply: transport = api']
@@ -3426,6 +3568,9 @@ async function specSync(rest, io = {}) {
3426
3568
  // Distinct from `--force`, deliberately. That one overrides other guards;
3427
3569
  // this one says "the duplicate title is real, create a second issue".
3428
3570
  else if (args[i] === '--force-new') flags.forceNew = true
3571
+ else if (args[i] === '--hold-state') flags.holdState = true
3572
+ else if (args[i] === '--send-held') flags.sendHeld = true
3573
+ else if (args[i] === '--held') flags.held = true
3429
3574
  else if (args[i] === '--yes') flags.yes = true
3430
3575
  else if (args[i] === '--check-remote') flags.remoteCheck = true
3431
3576
  else if (args[i] === '--stdin') flags.stdin = true
@@ -3438,6 +3583,8 @@ async function specSync(rest, io = {}) {
3438
3583
  else if (args[i] === '--to') flags.to = String(args[++i] || '').trim()
3439
3584
  else if (args[i] === '--release') flags.release = true
3440
3585
  else if (args[i] === '--if-unassigned') flags.ifUnassigned = true
3586
+ else if (args[i] === '--reason') flags.reason = args[++i]
3587
+ else if (args[i] === '--count') flags.count = true
3441
3588
  else if (args[i] === '--no-assign') flags.noAssign = true
3442
3589
  else if (args[i] === '--limit') flags.limit = Number(args[++i]) || 0
3443
3590
  else if (args[i] === '--cursor') flags.cursor = String(args[++i] || '').trim()
@@ -3548,7 +3695,7 @@ async function specSync(rest, io = {}) {
3548
3695
  case 'stamp':
3549
3696
  return specSyncStamp(dir, config, positional[0], flags, out)
3550
3697
  case 'record':
3551
- return specSyncRecord(dir, config, positional[0], out) || 0
3698
+ return specSyncRecord(dir, config, positional[0], flags, out) || 0
3552
3699
  case 'status':
3553
3700
  return specSyncStatus(dir, config, positional[0], flags, out) || 0
3554
3701
  case 'projects':
@@ -3587,6 +3734,8 @@ async function specSync(rest, io = {}) {
3587
3734
  case 'linked':
3588
3735
  specSyncLinked(dir, config, flags, out)
3589
3736
  return 0
3737
+ case 'idea':
3738
+ return specSyncIdea(dir, config, positional, flags, out)
3590
3739
  case 'ownership':
3591
3740
  return specSyncOwnership(config, flags, out, 'spec-sync')
3592
3741
  case 'board':
@@ -3604,6 +3753,7 @@ async function specSync(rest, io = {}) {
3604
3753
  ' skitterspec spec-sync users [<name-or-email>] [--limit N] [--cursor C] [--json]\n' +
3605
3754
  ' skitterspec spec-sync assign <spec> --to <id> [--name N] [--if-unassigned] | --release [--json]\n' +
3606
3755
  ' skitterspec spec-sync apply <spec> --plan <file> [--via api|mcp] [--project id] [--json]\n' +
3756
+ ' skitterspec spec-sync apply <spec> --hold-state | --send-held (PR-mode completion)\n' +
3607
3757
  ' skitterspec spec-sync apply --all <bucket> [--via api|mcp] [--json]\n' +
3608
3758
  ' skitterspec spec-sync verify <spec> --stored <file>\n' +
3609
3759
  ' skitterspec spec-sync splice <spec> --live <file> [--phase <ref>]\n' +
@@ -3611,6 +3761,7 @@ async function specSync(rest, io = {}) {
3611
3761
  ' skitterspec spec-sync comment <spec> --file <file> [--via api|mcp]\n' +
3612
3762
  ' skitterspec spec-sync list [--state <name> …|--all|--in-progress] [--next N] [--mine|--by <user>] [--limit N] [--archived] [--json]\n' +
3613
3763
  ' skitterspec spec-sync linked [--json]\n' +
3764
+ ' skitterspec spec-sync idea add <text> | list [--count] | drop <KEY-N> [--reason R] [--json]\n' +
3614
3765
  ' skitterspec spec-sync ownership [--json]\n' +
3615
3766
  ' skitterspec spec-sync board <spec> [--json]\n' +
3616
3767
  ' skitterspec spec-sync ref [<spec>] [--json]\n' +
@@ -145,7 +145,7 @@ const DEFAULT_CONFIG = Object.freeze({
145
145
  // feature, and the only signal would be noticing a lost report weeks later.
146
146
  // Being wrong in this direction costs a comment nobody needed; the other
147
147
  // direction costs someone their words.
148
- intake: Object.freeze({ label: '', bugLabels: Object.freeze([]), hotfixLabels: Object.freeze([]), preserveOriginal: true }),
148
+ intake: Object.freeze({ label: '', ideaLabel: 'idea', bugLabels: Object.freeze([]), hotfixLabels: Object.freeze([]), preserveOriginal: true }),
149
149
  // A spec is a Linear ISSUE; each phase is a SUB-ISSUE of it; tasks are not
150
150
  // synced (they live only in the repo phase files).
151
151
  // A spec is an ISSUE; each phase a SUB-ISSUE of it. `tasks` selects how the
@@ -282,6 +282,7 @@ function defaults() {
282
282
  linear: { ...DEFAULT_CONFIG.linear, labelsByKind: { ...DEFAULT_CONFIG.linear.labelsByKind }, severityLabels: { ...DEFAULT_CONFIG.linear.severityLabels } },
283
283
  intake: {
284
284
  label: DEFAULT_CONFIG.intake.label,
285
+ ideaLabel: DEFAULT_CONFIG.intake.ideaLabel,
285
286
  bugLabels: [...DEFAULT_CONFIG.intake.bugLabels],
286
287
  hotfixLabels: [...DEFAULT_CONFIG.intake.hotfixLabels],
287
288
  preserveOriginal: DEFAULT_CONFIG.intake.preserveOriginal,
@@ -355,6 +356,7 @@ function mergeConfig(base, parsed) {
355
356
 
356
357
  if (isObject(parsed.intake)) {
357
358
  assign(base.intake, parsed.intake, 'label', 'string?')
359
+ assign(base.intake, parsed.intake, 'ideaLabel', 'string?')
358
360
  if (Array.isArray(parsed.intake.bugLabels)) {
359
361
  base.intake.bugLabels = stringList(parsed.intake.bugLabels)
360
362
  }
@@ -52,6 +52,7 @@ const path = require('node:path')
52
52
  const {
53
53
  readSnapshot,
54
54
  readBase,
55
+ isEmptyPlan,
55
56
  projectionOf,
56
57
  recordPush,
57
58
  writeFrontmatter,
@@ -85,16 +86,58 @@ async function applySpecPlan(args) {
85
86
  }
86
87
  }
87
88
 
88
- async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progress, forceNew = false, program = 'spec-sync' }) {
89
+ async function applyInner({
90
+ dir,
91
+ config,
92
+ snapshotDir,
93
+ plan,
94
+ adapter,
95
+ ops,
96
+ progress,
97
+ forceNew = false,
98
+ holdState = false,
99
+ sendHeld = false,
100
+ program = 'spec-sync',
101
+ }) {
89
102
  const fields = fieldsOf(config)
90
103
  const helpers = makeSpecHelpers({ program })
91
104
  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
92
105
  const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
93
106
  const lines = []
94
107
  const result = { issue: null, subIssues: {} }
108
+
109
+ // PR-MODE COMPLETION, `branch` lane (spec bug-pr-complete-snapshot-on-base).
110
+ // Run 1 commits the move to ride the PR, but the Done waits for the merge —
111
+ // and run 2 sends it from the base branch, where no spec branch is left to
112
+ // commit a snapshot to. So run 1 HOLDS the state yet records it as sent, and
113
+ // run 2 SENDS only that state: the snapshot it records is byte-identical to
114
+ // the one the merge brought, and the base branch stays clean.
115
+ if (holdState && sendHeld) throw new Error(`${program} apply: --hold-state and --send-held are two runs, not one`)
116
+ if ((holdState || sendHeld) && !identifier) {
117
+ throw new Error(`${program} apply: an unlinked spec has no transition to hold — push it plainly`)
118
+ }
119
+ let heldState = false
120
+ let fellBack = false
121
+ if (holdState && plan.issue && plan.issue.state != null) {
122
+ const { state, stateResend, ...rest } = plan.issue
123
+ plan = { ...plan, issue: Object.keys(rest).length ? rest : undefined }
124
+ heldState = state
125
+ } else if (sendHeld) {
126
+ // A NON-EMPTY PLAN MEANS RUN 1 HELD NOTHING — it predates the hold, so the
127
+ // whole completion is still unsent. Sending the state alone would strand
128
+ // the rest; apply it all, as before, and say which file that leaves dirty.
129
+ if (isEmptyPlan(plan)) {
130
+ const status = projectionOf(snapshotDir, config).status
131
+ if (status != null) plan = { ...plan, issue: { state: status } }
132
+ } else {
133
+ fellBack = true
134
+ }
135
+ }
136
+
95
137
  // Which items this apply carried a state for — the snapshot records today's
96
- // state name for these and only these (`recordPush`).
97
- const sent = { issue: !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
138
+ // state name for these and only these (`recordPush`). A held state counts:
139
+ // run 2 sends it, and what run 2 records has to match what run 1 committed.
140
+ const sent = { issue: !!heldState || !!(plan.issue && plan.issue.state != null), subIssues: new Set() }
98
141
  // Handed out immediately, so a throw from anywhere below still reports what
99
142
  // had been stamped by the time it happened.
100
143
  if (progress) progress.result = result
@@ -268,7 +311,12 @@ async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progre
268
311
  const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config, sent, keepSubIssues })
269
312
  // A repo path, `/`-separated on every platform — the form every other
270
313
  // spec path in this output takes.
271
- lines.push(` snapshot: ${path.relative(dir, file).split(path.sep).join('/')}`)
314
+ const snapshotPath = path.relative(dir, file).split(path.sep).join('/')
315
+ lines.push(` snapshot: ${snapshotPath}`)
316
+ if (heldState) lines.push(` state held: ${identifier} → ${heldState} waits for the merge — run 2 sends it with --send-held`)
317
+ if (fellBack) {
318
+ lines.push(` !! nothing was held for ${identifier} — sent the whole plan; ${snapshotPath} now differs from the merged copy`)
319
+ }
272
320
  return { result, lines, lost }
273
321
  }
274
322
 
@@ -304,4 +352,41 @@ function resolvePhaseFileIn(snapshotDir, ref) {
304
352
  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
305
353
  }
306
354
 
307
- module.exports = { applySpecPlan }
355
+ /**
356
+ * `--hold-state` / `--send-held` as every provider's `apply` reads them: one
357
+ * spec, one of the two, never both. Returns `{ holdState, sendHeld }`, or
358
+ * `{ error }` for the provider to print and exit 1 on.
359
+ */
360
+ function heldFlags(flags, program) {
361
+ const holdState = !!(flags && flags.holdState)
362
+ const sendHeld = !!(flags && flags.sendHeld)
363
+ if (holdState && sendHeld) return { error: `${program} apply: --hold-state and --send-held are two runs, not one` }
364
+ if ((holdState || sendHeld) && flags.all != null) {
365
+ return { error: `${program} apply --all: --hold-state and --send-held act on one spec at a time` }
366
+ }
367
+ return { holdState, sendHeld }
368
+ }
369
+
370
+ /**
371
+ * What the MCP transport adds to its "nothing written" note, so the hand-applied
372
+ * push ends with the same snapshot the API path would record. Null when neither
373
+ * flag is set.
374
+ */
375
+ function heldOverMcp({ holdState, sendHeld }, program) {
376
+ if (holdState) {
377
+ return (
378
+ " --hold-state: apply the plan WITHOUT the spec issue's state, then record with\n" +
379
+ ` \`${program} record <spec> --held\` — run 2 sends the state after the merge.`
380
+ )
381
+ }
382
+ if (sendHeld) {
383
+ return (
384
+ " --send-held: if `plan` is empty, send the spec issue's state alone and record\n" +
385
+ ' nothing — the merged snapshot already says it. If it is not, run 1 held\n' +
386
+ ' nothing: apply it whole and record as usual.'
387
+ )
388
+ }
389
+ return null
390
+ }
391
+
392
+ module.exports = { applySpecPlan, heldFlags, heldOverMcp }