@skitterbyte/skitterspec-jira 2.3.0 → 2.4.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 (57) hide show
  1. package/assets/claude-md-section.md +20 -1
  2. package/assets/core/env.config.json.example +1 -0
  3. package/assets/core/env.config.md +90 -6
  4. package/assets/core/jira.config.md +4 -2
  5. package/assets/hooks/main-guard.cjs +18 -2
  6. package/assets/hooks/review-gate.cjs +19 -2
  7. package/assets/rules/commit-trailers.md +24 -1
  8. package/assets/rules/spec-planning.md +81 -18
  9. package/assets/rules/spec-reports.md +1 -1
  10. package/assets/skills/spec/SKILL.md +55 -2
  11. package/assets/skills/spec-bug/SKILL.md +25 -1
  12. package/assets/skills/spec-cancel/SKILL.md +35 -0
  13. package/assets/skills/spec-complete/SKILL.md +113 -0
  14. package/assets/skills/spec-hotfix/SKILL.md +40 -2
  15. package/assets/skills/spec-incident/SKILL.md +22 -0
  16. package/assets/skills/spec-jira-setup/SKILL.md +23 -1
  17. package/assets/skills/spec-next/SKILL.md +9 -4
  18. package/assets/skills/spec-push/SKILL.md +22 -0
  19. package/assets/skills/spec-review/SKILL.md +32 -0
  20. package/assets/skills/spec-start/SKILL.md +39 -1
  21. package/assets/skills/spec-status/SKILL.md +18 -3
  22. package/assets/skills/spec-sync/SKILL.md +1 -0
  23. package/assets/skills/spec-to-main/SKILL.md +47 -1
  24. package/package.json +1 -1
  25. package/src/cli.js +1091 -39
  26. package/src/env/base.js +104 -0
  27. package/src/env/config.js +75 -3
  28. package/src/env/disposition.js +62 -0
  29. package/src/env/handoff.js +80 -0
  30. package/src/env/host.js +262 -0
  31. package/src/env/hotfix.js +225 -0
  32. package/src/env/hotfixland.js +103 -9
  33. package/src/env/inflight.js +95 -0
  34. package/src/env/integrate.js +130 -4
  35. package/src/env/mainguard.js +6 -0
  36. package/src/env/phases.js +28 -0
  37. package/src/env/provision.js +18 -6
  38. package/src/env/resolve.js +108 -9
  39. package/src/env/serve.js +6 -1
  40. package/src/env/specstate.js +101 -0
  41. package/src/env/teardown.js +42 -0
  42. package/src/vendor/jira/cli-sync.js +45 -3
  43. package/src/vendor/jira/config.js +17 -5
  44. package/src/vendor/provider-kit/index.js +4 -0
  45. package/src/vendor/provider-kit/src/apply.js +49 -4
  46. package/src/vendor/provider-kit/src/assignment.js +78 -1
  47. package/src/vendor/provider-kit/src/config.js +34 -1
  48. package/src/vendor/provider-kit/src/list-rows.js +35 -11
  49. package/src/vendor/provider-kit/src/released.js +14 -1
  50. package/src/vendor/provider-kit/src/specs.js +4 -2
  51. package/src/vendor/provider-kit/src/splice.js +64 -0
  52. package/src/vendor/provider-kit/src/status.js +137 -0
  53. package/src/vendor/sync-core/index.js +14 -1
  54. package/src/vendor/sync-core/src/compare.js +17 -5
  55. package/src/vendor/sync-core/src/normalize.js +50 -7
  56. package/src/vendor/sync-core/src/push.js +26 -2
  57. package/src/vendor/sync-core/src/summary.js +257 -0
package/src/env/hotfix.js CHANGED
@@ -341,6 +341,229 @@ function planHotfixLand(spec, config, ctx) {
341
341
  return { ...result, commands, steps, afterLand, prodTag, targets, fixRange }
342
342
  }
343
343
 
344
+ /**
345
+ * Plan a BRANCH-BASED hotfix land (`Base version: <branch>@<sha>`, from
346
+ * `hotfix.releaseBranch`): the release line is a branch, so the fix lands ON it —
347
+ * by the project's `land.strategy` — rather than being tagged off a fork.
348
+ *
349
+ * ff rebase onto <remote>/<branch> → release (optional tag) → push the hotfix
350
+ * head to <branch>, then the tag. The push is the land, so it waits on
351
+ * consent exactly as the tag push does today.
352
+ * pr rebase → push the hotfix branch → open a READY pull request into
353
+ * <branch> → hold until the host merges it. The run that sees it merged
354
+ * tags <remote>/<branch> and pushes the tag. A hotfix PR is finished work,
355
+ * which is why it is never a draft.
356
+ *
357
+ * Every "already done" is a positive signal from git or the host, so a re-run
358
+ * picks up where the last one stopped: HEAD already on the remote branch is a
359
+ * landed ff, a host-reported merge is a landed PR, a recorded release still at
360
+ * HEAD is reused rather than re-cut.
361
+ *
362
+ * Once the land is confirmed the fix is CARRIED to the resolved base — the
363
+ * current rc under a rolling base — the same carry a tag-based hotfix makes to
364
+ * `main` under `ff`, and under `pr` a `carry/<slug>` branch with its own ready
365
+ * PR, because the rc may be protected too. `ctx.carry` describes it; null means
366
+ * there is nothing to carry (`cherryPickMain: false`, or the base IS the release
367
+ * branch).
368
+ *
369
+ * ctx: { dirty, remote, strategy, push, behind, onRelease, ahead,
370
+ * headOnRemote, pr: { state, id, url } | null, prCommand,
371
+ * lastTag, existingTags, released, tagPushed,
372
+ * carry: { base, strategy, path, tmpPath, commits, startRef?,
373
+ * carryBranch?, prCommand?, prState?, files? } | null }
374
+ * behind <remote>/<branch> is not an ancestor of HEAD — rebase first
375
+ * onRelease HEAD is an ancestor of <remote>/<branch> — an ff land is done
376
+ * lastTag the newest tag reachable from <remote>/<branch> (bump base)
377
+ */
378
+ function planBranchHotfixLand(spec, config, ctx) {
379
+ const c = ctx || {}
380
+ const v = spec.baseVersion || {}
381
+ const releaseBranch = v.branch
382
+ const remote = c.remote || 'origin'
383
+ const releaseRef = `${remote}/${releaseBranch}`
384
+ const branch = spec.branch
385
+ const hotfixCfg = (config && config.hotfix) || {}
386
+ const tagging = hotfixCfg.tag !== false
387
+ const releaseWith = String(hotfixCfg.releaseWith || '').trim()
388
+ const bump = hotfixCfg.bump || 'patch'
389
+ const strategy = c.strategy === 'pr' ? 'pr' : 'ff'
390
+ const cwd = spec.worktreePath
391
+ const result = {
392
+ blocked: false,
393
+ noop: false,
394
+ reason: null,
395
+ steps: [],
396
+ strategy,
397
+ releaseBranch,
398
+ releaseRef,
399
+ branch,
400
+ afterLand: afterLandFor(null),
401
+ }
402
+ const block = (reason) => ({ ...result, blocked: true, reason })
403
+
404
+ if (!releaseBranch) return block('spec has no branch-based Base version (<branch>@<sha>)')
405
+ if (c.dirty) return block('worktree has uncommitted changes — commit the completion first')
406
+ // A project's release command cuts its version commit and tag on the hotfix
407
+ // branch. Under a PR the commit rides the PR but the host's merge (squash,
408
+ // rebase) leaves the tag on a commit the release branch never has.
409
+ if (strategy === 'pr' && tagging && releaseWith) {
410
+ return block(
411
+ 'hotfix.releaseWith cannot release a branch-based hotfix landed by PR — the tag would ' +
412
+ 'point at a commit the merge rewrites; use the built-in tag, or set hotfix.tag false',
413
+ )
414
+ }
415
+
416
+ // The tag the built-in tagger cuts, bumped from the newest one the release
417
+ // branch already has. Computed lazily: only a run that cuts one needs it.
418
+ const builtInTag = () => {
419
+ if (!c.lastTag) return { refused: `no release tag on ${releaseBranch} to bump from — set hotfix.tag false, or hotfix.releaseWith` }
420
+ const tag = nextTag(c.lastTag, c.existingTags, bump)
421
+ if ((c.existingTags || []).includes(tag)) {
422
+ return { refused: `tag ${tag} already exists${freeTagHint(c.lastTag, c.existingTags, bump)}` }
423
+ }
424
+ return { tag }
425
+ }
426
+ const pushVia = (done) => (done ? 'remote' : c.push ? 'push' : 'hold')
427
+
428
+ // The carry, appended once the land is confirmed. Nothing left to pick — the
429
+ // base already has every fix commit — is no step at all, so a finished land
430
+ // reads as a no-op on re-run rather than as a carry that did nothing.
431
+ const carryStep = () => {
432
+ const k = c.carry
433
+ if (!k || !Array.isArray(k.commits) || !k.commits.length) return null
434
+ return {
435
+ kind: 'carry',
436
+ base: k.base,
437
+ strategy: k.strategy,
438
+ cwd: k.path,
439
+ root: k.root || k.path,
440
+ tmpPath: k.tmpPath || null,
441
+ commits: k.commits,
442
+ startRef: k.startRef || null,
443
+ carryBranch: k.carryBranch || null,
444
+ remote,
445
+ push: Boolean(c.push),
446
+ prCommand: k.prCommand || null,
447
+ prState: k.prState || null,
448
+ }
449
+ }
450
+ const withCarry = (steps) => {
451
+ const k = carryStep()
452
+ if (!k) return steps
453
+ result.afterLand = k.strategy === 'pr' ? afterLandFor(null) : afterLandFor(config, k.root, rangeOf({ changedFiles: c.carry.files }))
454
+ return [...steps, k]
455
+ }
456
+
457
+ if (strategy === 'ff') {
458
+ const landed = Boolean(c.onRelease)
459
+ // A recorded release is only good while it is still at HEAD; a rebase
460
+ // moves HEAD, so a run that must rebase cuts afresh.
461
+ const released = c.behind ? null : c.released || null
462
+ if (landed && (!tagging || (released && c.tagPushed))) {
463
+ const steps = withCarry([])
464
+ if (!steps.length) {
465
+ return { ...result, noop: true, reason: `${branch} is already on ${releaseRef} — nothing to land` }
466
+ }
467
+ return { ...result, steps }
468
+ }
469
+ const steps = []
470
+ if (c.behind && !landed) steps.push({ kind: 'rebase', onto: releaseRef, cwd })
471
+ if (tagging) {
472
+ if (released && released.tag) {
473
+ steps.push({ kind: 'release', via: 'recorded', tag: released.tag, release: released })
474
+ } else if (releaseWith) {
475
+ steps.push({ kind: 'release', via: 'command', command: releaseWith, cwd })
476
+ } else {
477
+ const t = builtInTag()
478
+ if (t.refused) return block(t.refused)
479
+ steps.push({ kind: 'release', via: 'tag', tag: t.tag, cwd, baseTag: c.lastTag, branch })
480
+ }
481
+ }
482
+ steps.push({
483
+ kind: 'push',
484
+ via: pushVia(landed && (!tagging || c.tagPushed)),
485
+ remote,
486
+ branch,
487
+ refs: landed ? [] : [`${branch}:${releaseBranch}`],
488
+ withTag: tagging,
489
+ cwd,
490
+ })
491
+ const all = withCarry(steps)
492
+ return { ...result, steps: all }
493
+ }
494
+
495
+ // pr
496
+ const merged = c.pr && c.pr.state === 'merged'
497
+ if (!merged) {
498
+ const steps = []
499
+ if (c.behind) steps.push({ kind: 'rebase', onto: releaseRef, cwd })
500
+ // --force-with-lease because the rebase rewrites a branch that may
501
+ // already be on the remote; -u so the first push sets the upstream.
502
+ steps.push({ kind: 'push', via: pushVia(c.headOnRemote && !c.behind), remote, branch, refs: [branch], withTag: false, force: true, cwd })
503
+ steps.push({ kind: 'pr', command: c.prCommand || null, state: c.pr ? c.pr.state : 'cannot-tell', id: c.pr ? c.pr.id : null, base: releaseBranch, cwd })
504
+ steps.push({ kind: 'wait', base: releaseBranch, pr: c.pr || null })
505
+ return { ...result, steps }
506
+ }
507
+ if (!tagging || (c.released && c.tagPushed)) {
508
+ const steps = withCarry([])
509
+ if (!steps.length) {
510
+ return { ...result, noop: true, reason: `the PR into ${releaseBranch} is merged — nothing to land` }
511
+ }
512
+ return { ...result, steps }
513
+ }
514
+ const steps = []
515
+ if (c.released && c.released.tag) {
516
+ steps.push({ kind: 'release', via: 'recorded', tag: c.released.tag, release: c.released })
517
+ } else {
518
+ const t = builtInTag()
519
+ if (t.refused) return block(t.refused)
520
+ // Tagged at the release branch as the host left it — the merge, whatever
521
+ // style made it — not at the hotfix branch, which a squash never reaches.
522
+ steps.push({ kind: 'release', via: 'tag', tag: t.tag, at: releaseRef, cwd, baseTag: c.lastTag, branch })
523
+ }
524
+ steps.push({ kind: 'push', via: pushVia(c.tagPushed), remote, branch, refs: [], withTag: true, cwd })
525
+ const all = withCarry(steps)
526
+ return { ...result, steps: all }
527
+ }
528
+
529
+ /**
530
+ * Plan `spec-env hotfix finish` for a BRANCH-BASED hotfix. The fix lives on the
531
+ * release branch once landed, so the tag-based guards (a tag at HEAD, the branch
532
+ * on the remote) are the wrong question; these ask whether the work reached
533
+ * both places it was going:
534
+ * - a clean tree;
535
+ * - the land confirmed — HEAD on the release branch (ff) or the host saying
536
+ * the PR merged (pr). Cannot-tell refuses: the branch may be the only copy;
537
+ * - the carry done — the base has every fix commit, its carry PR merged, or
538
+ * there was nothing to carry. Cannot-tell refuses for the same reason.
539
+ * Every failing one is named, and there is no `--force`.
540
+ *
541
+ * state: { dirty, landed: true|false|undefined, carried: true|false|undefined|'not-needed',
542
+ * releaseBranch, base, hasSlot, mainRepoPath }
543
+ */
544
+ function planBranchHotfixFinish(spec, state) {
545
+ const s = state || {}
546
+ const reasons = []
547
+ if (s.dirty) reasons.push('the worktree has uncommitted changes')
548
+ if (s.landed === undefined) reasons.push(`cannot tell whether the fix is on ${s.releaseBranch} — the host or remote did not answer`)
549
+ else if (!s.landed) reasons.push(`the fix is not on ${s.releaseBranch} yet — run \`spec-env hotfix land\` (and merge its PR)`)
550
+ if (s.carried === undefined) reasons.push(`cannot tell whether ${s.base} has the fix — the host or remote did not answer`)
551
+ else if (s.carried === false) reasons.push(`${s.base} does not have the fix yet — re-run \`spec-env hotfix land\` to carry it (and merge the carry PR)`)
552
+ if (s.hasSlot) reasons.push(`${spec.folder} holds a Docker stack — tear it down with \`spec-env down\``)
553
+ if (reasons.length) return { blocked: true, reasons, argvs: [] }
554
+ const root = s.mainRepoPath
555
+ return {
556
+ blocked: false,
557
+ reasons: [],
558
+ argvs: [
559
+ ['-C', root, 'worktree', 'remove', spec.worktreePath],
560
+ // -D: under a squash or rebase merge the branch is never an ancestor of
561
+ // anything, and the land above is what proved its commits are kept.
562
+ ['-C', root, 'branch', '-D', spec.branch],
563
+ ],
564
+ }
565
+ }
566
+
344
567
  /**
345
568
  * Plan `spec-env hotfix finish`: the teardown a hotfix waits for until its
346
569
  * deploy is out.
@@ -409,5 +632,7 @@ module.exports = {
409
632
  BUMPS,
410
633
  tagSlug,
411
634
  planHotfixLand,
635
+ planBranchHotfixLand,
636
+ planBranchHotfixFinish,
412
637
  planHotfixFinish,
413
638
  }
@@ -70,17 +70,35 @@ function describeStep(step) {
70
70
  case 'release':
71
71
  if (step.via === 'command') return `release: ${step.command}`
72
72
  if (step.via === 'recorded') return `release: ${step.tag} (cut earlier — not re-run)`
73
- return `release: git tag ${step.tag}`
74
- case 'push':
75
- if (step.via === 'remote') return `push: ${step.tag || 'the tag'} is already on ${step.remote}`
73
+ return `release: git tag ${step.tag}${step.at ? ` ${step.at}` : ''}`
74
+ case 'push': {
75
+ if (step.via === 'remote') {
76
+ return step.refs ? `push: already on ${step.remote}` : `push: ${step.tag || 'the tag'} is already on ${step.remote}`
77
+ }
76
78
  if (step.via === 'hold') return `push: held — no consent to push to ${step.remote}`
77
- return `push: ${step.branch}, then ${step.tag || 'the tag'}, to ${step.remote}`
79
+ const what = [...pushRefs(step), ...(pushesTag(step) ? [step.tag || 'the tag'] : [])]
80
+ return `push: ${what.join(', then ')}, to ${step.remote}`
81
+ }
82
+ case 'rebase':
83
+ return `rebase: onto ${step.onto}`
84
+ case 'pr':
85
+ if (!step.command) return `pr: cannot tell the PR's state — open one into ${step.base} on the host`
86
+ if (step.command.startsWith('#')) return `pr: ${step.command.slice(1).trim()}`
87
+ return `pr: ${step.command}`
88
+ case 'wait':
89
+ return `wait: the PR into ${step.base} is not merged yet — re-run once the host merges it`
78
90
  case 'target':
79
91
  return `target: ${step.base} -> ${step.tag} (cherry-pick, tag)`
80
92
  case 'carry': {
81
93
  const n = Array.isArray(step.commits) ? step.commits.length : 0
82
94
  const what = n === 1 ? '1 commit' : `${n} commits`
83
95
  if (step.strategy === 'worktree') return `carry: cherry-pick ${what} onto ${step.base} (throwaway worktree)`
96
+ if (step.strategy === 'pr') {
97
+ if (step.prState === 'open' || step.prState === 'draft') return `carry: the PR from ${step.carryBranch} into ${step.base} is open — merge it to finish`
98
+ if (step.prState === 'merged') return `carry: the PR from ${step.carryBranch} into ${step.base} is merged`
99
+ if (!step.push) return `carry: held — no consent to push ${step.carryBranch} to ${step.remote}`
100
+ return `carry: cherry-pick ${what} onto ${step.carryBranch}, push it, open a PR into ${step.base}`
101
+ }
84
102
  return `carry: cherry-pick ${what} onto ${step.base}`
85
103
  }
86
104
  default:
@@ -88,6 +106,16 @@ function describeStep(step) {
88
106
  }
89
107
  }
90
108
 
109
+ // What a push step sends besides the tag. A tag-based land pushes its branch;
110
+ // a branch-based one names its refs — `<hotfix>:<release>` for an ff land, the
111
+ // hotfix branch for a PR, or none at all when only the tag is left to publish.
112
+ function pushRefs(step) {
113
+ return Array.isArray(step.refs) ? step.refs : [step.branch]
114
+ }
115
+ function pushesTag(step) {
116
+ return step.withTag !== false
117
+ }
118
+
91
119
  // The last non-blank line a command wrote to stderr — skittership's refusals
92
120
  // are one `✖ release-hotfix: <reason>` line there, and that is what to relay.
93
121
  function lastLine(text) {
@@ -108,7 +136,7 @@ function runRelease(step, ctx) {
108
136
  return { outcome: 'skipped', line: describeStep(step), release: step.release }
109
137
  }
110
138
  if (step.via === 'tag') {
111
- const res = ctx.spawn('git', ['-C', step.cwd, 'tag', step.tag], {
139
+ const res = ctx.spawn('git', ['-C', step.cwd, 'tag', step.tag, ...(step.at ? [step.at] : [])], {
112
140
  stdio: ['ignore', 'pipe', 'pipe'],
113
141
  encoding: 'utf8',
114
142
  })
@@ -151,15 +179,16 @@ function runPush(step, release, ctx) {
151
179
  const s = { ...step, tag: release ? release.tag : null }
152
180
  if (s.via === 'remote') return { outcome: 'skipped', line: describeStep(s) }
153
181
  if (s.via === 'hold') return { outcome: 'held', line: describeStep(s) }
154
- if (!release) return { outcome: 'failed', line: `${describeStep(s)} — no release to push` }
155
- for (const ref of [s.branch, s.tag]) {
156
- const argv = ['-C', s.cwd, 'push', s.remote, ref]
182
+ if (pushesTag(s) && !release) return { outcome: 'failed', line: `${describeStep(s)} — no release to push` }
183
+ const refs = [...pushRefs(s), ...(pushesTag(s) ? [s.tag] : [])]
184
+ for (const ref of refs) {
185
+ const argv = ['-C', s.cwd, 'push', ...(s.force && ref !== s.tag ? ['--force-with-lease', '-u'] : []), s.remote, ref]
157
186
  const res = ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
158
187
  if (res.error || res.status !== 0) {
159
188
  return { outcome: 'failed', line: `push ${ref} to ${s.remote} — ${lastLine(res.stderr) || why(res)}` }
160
189
  }
161
190
  }
162
- return { outcome: 'pushed', line: `pushed ${s.branch}, then ${s.tag}, to ${s.remote}` }
191
+ return { outcome: 'pushed', line: `pushed ${refs.join(', then ')}, to ${s.remote}` }
163
192
  }
164
193
 
165
194
  /**
@@ -184,6 +213,7 @@ function runCarry(step, release, ctx) {
184
213
  if (!commits.length) {
185
214
  return { outcome: 'skipped', line: `carry: nothing to carry — ${step.base} already has the fix`, carried: 0 }
186
215
  }
216
+ if (step.strategy === 'pr') return runCarryPr(step, commits, ctx)
187
217
  if (step.strategy === 'dirty') {
188
218
  return {
189
219
  outcome: 'refused',
@@ -223,6 +253,65 @@ function runCarry(step, release, ctx) {
223
253
  return { outcome: 'ran', line: `carried ${what} onto ${step.base}`, carried: commits.length }
224
254
  }
225
255
 
256
+ // The carry under `land.strategy: "pr"`: the base may be protected, so the fix
257
+ // reaches it the way everything else does — a `carry/<slug>` branch cut from
258
+ // the base, the fix picked onto it in a throwaway worktree, pushed on consent,
259
+ // and a READY PR into the base. A carry PR already open or merged is the host
260
+ // saying this ran before; neither re-runs anything.
261
+ function runCarryPr(step, commits, ctx) {
262
+ if (step.prState === 'open' || step.prState === 'draft' || step.prState === 'merged') {
263
+ return { outcome: 'skipped', line: describeStep(step), carried: 0 }
264
+ }
265
+ if (!step.push) return { outcome: 'held', line: describeStep(step) }
266
+ const git = (argv) =>
267
+ ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
268
+ const fail = (line) => ({ outcome: 'failed', line })
269
+ const add = git(['-C', step.root, 'worktree', 'add', '-B', step.carryBranch, step.tmpPath, step.startRef])
270
+ if (add.error || add.status !== 0) return fail(`carry: worktree add ${step.tmpPath} — ${lastLine(add.stderr) || why(add)}`)
271
+ const cleanup = () => git(['-C', step.root, 'worktree', 'remove', '--force', step.tmpPath])
272
+ for (const sha of commits) {
273
+ const res = git(['-C', step.tmpPath, 'cherry-pick', sha])
274
+ if (res.error || res.status !== 0) {
275
+ git(['-C', step.tmpPath, 'cherry-pick', '--abort'])
276
+ cleanup()
277
+ return fail(`carry: cherry-pick ${sha} onto ${step.carryBranch} conflicted — aborted; ${lastLine(res.stderr) || why(res)}`)
278
+ }
279
+ }
280
+ const push = git(['-C', step.tmpPath, 'push', '--force-with-lease', '-u', step.remote, step.carryBranch])
281
+ cleanup()
282
+ if (push.error || push.status !== 0) return fail(`carry: push ${step.carryBranch} — ${lastLine(push.stderr) || why(push)}`)
283
+ if (!step.prCommand || step.prCommand.startsWith('#')) {
284
+ return { outcome: 'ran', line: `carry: pushed ${step.carryBranch} — open a PR into ${step.base} on the host`, carried: 0 }
285
+ }
286
+ const pr = ctx.spawn(step.prCommand, { cwd: step.root, shell: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
287
+ if (pr.error || pr.status !== 0) return fail(`carry: ${step.prCommand} — ${lastLine(pr.stderr) || why(pr)}`)
288
+ return { outcome: 'ran', line: `carry: opened a PR from ${step.carryBranch} into ${step.base}`, carried: 0 }
289
+ }
290
+
291
+ // Replay the hotfix onto the release branch as it is now. A conflict is
292
+ // aborted, leaving the branch exactly where it was, so a re-run tries again.
293
+ function runRebase(step, ctx) {
294
+ const git = (argv) => ctx.spawn('git', argv, { stdio: ['ignore', ctx.childStdout, 'pipe'], encoding: 'utf8' })
295
+ const res = git(['-C', step.cwd, 'rebase', step.onto])
296
+ if (res.error || res.status !== 0) {
297
+ git(['-C', step.cwd, 'rebase', '--abort'])
298
+ return { outcome: 'failed', line: `rebase onto ${step.onto} conflicted — aborted; ${lastLine(res.stderr) || why(res)}` }
299
+ }
300
+ return { outcome: 'ran', line: `rebased onto ${step.onto}` }
301
+ }
302
+
303
+ // Open the PR, through the host's own CLI. A `# …` command is the host saying
304
+ // one already exists (the push updated it); null is a host that could not be
305
+ // asked — neither runs anything.
306
+ function runPr(step, ctx) {
307
+ if (!step.command || step.command.startsWith('#')) return { outcome: 'skipped', line: describeStep(step) }
308
+ const res = ctx.spawn(step.command, { cwd: step.cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' })
309
+ if (res.error || res.status !== 0) {
310
+ return { outcome: 'failed', line: `pr: ${step.command} — ${lastLine(res.stderr) || why(res)}` }
311
+ }
312
+ return { outcome: 'ran', line: `opened a PR into ${step.base}${res.stdout ? ` — ${lastLine(res.stdout)}` : ''}` }
313
+ }
314
+
226
315
  // A step that is a list of git argvs run in order — a target's worktree,
227
316
  // cherry-pick, tag and cleanup, or the carry's cherry-pick.
228
317
  function runArgvs(step, ctx) {
@@ -267,6 +356,11 @@ function runHotfixLand(steps, io = {}) {
267
356
  if (step.kind === 'release') r = runRelease(step, ctx)
268
357
  else if (step.kind === 'push') r = runPush(step, release, ctx)
269
358
  else if (step.kind === 'carry') r = runCarry(step, release, ctx)
359
+ else if (step.kind === 'rebase') r = runRebase(step, ctx)
360
+ else if (step.kind === 'pr') r = runPr(step, ctx)
361
+ // Not a failure: the land is waiting on the host, and nothing after it
362
+ // (the tag, the carry) may run before the merge.
363
+ else if (step.kind === 'wait') r = { outcome: 'held', line: describeStep(step) }
270
364
  else if (step.kind === 'target') {
271
365
  // A project's release command can cut a tag the built-in tagger also
272
366
  // planned for a target on the same root. Refuse rather than collide.
@@ -0,0 +1,95 @@
1
+ 'use strict'
2
+
3
+ /**
4
+ * What is in flight here — the rows behind `skitterspec status`, and the detail
5
+ * `spec-env status` prints beside each provisioned spec.
6
+ *
7
+ * Each spec is read in ITS OWN worktree (`readSpecState`), where the bucket and
8
+ * the phase files are truthful, and again in the checkout the command was run
9
+ * from, so the output can say when the two disagree. Offline by construction:
10
+ * nothing here asks a tracker — the board's view is `spec-sync list` and
11
+ * `spec-sync board` (Decision 7).
12
+ *
13
+ * Pure but for the injected reader, so the command layer is testable without a
14
+ * worktree.
15
+ */
16
+
17
+ const path = require('node:path')
18
+
19
+ const { readSpecState } = require('./specstate.js')
20
+ const { progressText } = require('./phases.js')
21
+
22
+ /**
23
+ * @param {object} a
24
+ * - `dir` the checkout the command was run from
25
+ * - `provisioned` `[{ folder, wt, specless }]`, from the worktree list
26
+ * - `read` `readSpecState`, injectable
27
+ */
28
+ function collectInFlight({ dir, provisioned, read = readSpecState }) {
29
+ return provisioned.map(({ folder, wt, specless }) => {
30
+ // A `/no-spec` record has a branch and no document BY DESIGN (Decision 6).
31
+ // It is listed, and never read, so it can never be called unknown.
32
+ if (specless) return { spec: folder, worktree: wt, specless: true }
33
+ const there = read(wt, folder)
34
+ const here = read(dir, folder)
35
+ return {
36
+ spec: folder,
37
+ worktree: wt,
38
+ specless: false,
39
+ ...there,
40
+ // Where this checkout files it: a bucket, or null when it is not on this
41
+ // branch at all (a spec authored and started without landing here).
42
+ here: here.found ? here.bucket : null,
43
+ }
44
+ })
45
+ }
46
+
47
+ // The one-line detail for a row. Every part is optional except the bucket: a
48
+ // `pull`-era spec carries no Status or Developer, and that is the normal shape.
49
+ function detailOf(row) {
50
+ if (row.specless) return '(no spec)'
51
+ if (!row.found) return `status unknown — ${row.reason}`
52
+ const parts = [row.bucket]
53
+ if (row.phasesTotal !== null) {
54
+ parts.push(progressText({ done: row.phasesDone, total: row.phasesTotal, current: row.currentPhase }))
55
+ }
56
+ if (row.status) parts.push(row.status)
57
+ if (row.developer) parts.push(row.developer)
58
+ return parts.join(' · ')
59
+ }
60
+
61
+ // Rows whose bucket here differs from the bucket in their own worktree — the
62
+ // confusion the closing line explains. A positive signal: both reads found the
63
+ // spec and named different buckets, or the worktree found it and this checkout
64
+ // does not have it at all. An unreadable worktree copy is never counted.
65
+ function disagreeing(rows) {
66
+ return rows.filter((r) => !r.specless && r.found && r.here !== r.bucket)
67
+ }
68
+
69
+ // A worktree outlives its spec when a teardown was declined, so a provisioned
70
+ // spec is not necessarily in flight. Finished is the positive signal — the
71
+ // worktree's own copy sits in `complete/` or `cancelled/` — and everything else,
72
+ // an unreadable copy included, is counted as in flight and still listed.
73
+ const FINISHED = new Set(['complete', 'cancelled'])
74
+ const isInFlight = (r) => !r.specless && !(r.found && FINISHED.has(r.bucket))
75
+
76
+ function formatInFlight(rows, { dir }) {
77
+ if (!rows.length) return 'no specs in flight\n'
78
+ const width = Math.max(...rows.map((r) => r.spec.length))
79
+ const live = rows.filter(isInFlight).length
80
+ const out = [live ? `${live} spec${live === 1 ? '' : 's'} in flight` : 'no specs in flight']
81
+ for (const r of rows) {
82
+ out.push(` ${r.spec.padEnd(width)} ${detailOf(r)}`)
83
+ out.push(` ${path.relative(dir, r.worktree) || r.worktree}`)
84
+ }
85
+ // SAID ONLY WHEN TRUE. On an idle repo, or one whose worktrees all agree with
86
+ // this checkout, the line would explain a discrepancy that is not there.
87
+ const off = disagreeing(rows)
88
+ if (off.length) {
89
+ const n = off.length
90
+ out.push('', `On this branch ${n} of these ${n === 1 ? 'reads' : 'read'} differently — a spec's bucket moves on its own branch.`)
91
+ }
92
+ return out.join('\n') + '\n'
93
+ }
94
+
95
+ module.exports = { collectInFlight, detailOf, disagreeing, formatInFlight, isInFlight }
@@ -24,12 +24,15 @@ const { globToRegExp } = require('./glob.js')
24
24
  * returns is identical so callers need no second code path.
25
25
  *
26
26
  * @param {object} ctx { worktreeState: { dirty }, base, aheadOfBase, mainRepoPath,
27
- * changedFiles } — `changedFiles` is what the land brings
28
- * in (`base...branch`), or null when it could not be read
27
+ * changedFiles, primarySwitch } — `changedFiles` is what the
28
+ * land brings in (`base...branch`), or null when it could not
29
+ * be read. `primarySwitch` is set when the primary checkout
30
+ * sits on an older rolling-base match:
31
+ * `{ from, create, remote, dirty }`
29
32
  * @returns {object} { blocked, noop, reason, commands, afterLand, base, branch }
30
33
  */
31
34
  function planIntegrate(spec, config, ctx) {
32
- const { worktreeState = {}, base, aheadOfBase, mainRepoPath } = ctx || {}
35
+ const { worktreeState = {}, base, aheadOfBase, mainRepoPath, primarySwitch } = ctx || {}
33
36
  const branch = spec.branch
34
37
  const result = {
35
38
  blocked: false, noop: false, reason: null, commands: [], afterLand: noAfterLand(), base, branch,
@@ -48,9 +51,24 @@ function planIntegrate(spec, config, ctx) {
48
51
  return { ...result, noop: true, afterLand: afterLandFor(config, mainRepoPath, null) }
49
52
  }
50
53
 
54
+ // `merge --ff-only` moves whatever the primary checkout has checked out, so a
55
+ // checkout still on the previous release candidate would RECEIVE the land.
56
+ // Switch it first — and refuse while it holds uncommitted work, which a switch
57
+ // would carry onto the new base or refuse halfway through.
58
+ if (primarySwitch && primarySwitch.dirty) {
59
+ return {
60
+ ...result,
61
+ blocked: true,
62
+ reason:
63
+ `the primary checkout is on ${primarySwitch.from}, not ${base}, and has uncommitted ` +
64
+ `changes — commit or stash them there so it can switch to ${base}`,
65
+ }
66
+ }
67
+
51
68
  return {
52
69
  ...result,
53
70
  commands: [
71
+ ...(primarySwitch ? [switchCommand(mainRepoPath, base, primarySwitch)] : []),
54
72
  `git -C ${spec.worktreePath} rebase ${base}`,
55
73
  `git -C ${mainRepoPath} merge --ff-only ${branch}`,
56
74
  ],
@@ -58,6 +76,14 @@ function planIntegrate(spec, config, ctx) {
58
76
  }
59
77
  }
60
78
 
79
+ // Put the primary checkout on `base`, creating the local branch from the remote
80
+ // when this clone has never had it (a release candidate cut since).
81
+ function switchCommand(repo, base, { create, remote }) {
82
+ return create
83
+ ? `git -C ${repo} switch -c ${base} --track ${remote || 'origin'}/${base}`
84
+ : `git -C ${repo} switch ${base}`
85
+ }
86
+
61
87
  /**
62
88
  * Pure integrate planner for CHECKOUT mode.
63
89
  *
@@ -116,6 +142,106 @@ function planIntegrateCheckout(spec, config, ctx) {
116
142
  }
117
143
  }
118
144
 
145
+ /**
146
+ * Pure integrate planner for PR mode (`land.strategy: "pr"`).
147
+ *
148
+ * Landing is not a local fast-forward: the branch is rebased onto the REMOTE
149
+ * image of base, pushed, and a pull request carries it the rest of the way —
150
+ * the base branch moves only when the host merges. So the plan ends in a push,
151
+ * and the push is consent-gated with exactly `planHotfixLand`'s shape: a branch
152
+ * already on the remote at HEAD is honoured as the positive signal (`via:
153
+ * "remote"`), `--push` is the operator's recorded yes (`via: "push"`), and
154
+ * otherwise the plan HOLDS (`via: "hold"`) — the push and PR commands go in
155
+ * `holdCommands` for the skill to print, run by nobody until someone consents.
156
+ *
157
+ * `afterLand` is DEFERRED, never emitted: base has not moved when these
158
+ * commands finish, so the project's after-land steps belong to the completion
159
+ * run that follows the host merge. `afterLandPending: "after-merge"` is how the
160
+ * plan says so.
161
+ *
162
+ * One planner serves both modes: `treePath` is the worktree in worktree mode
163
+ * and the primary checkout in checkout mode, and `onBranch` is asked only where
164
+ * the caller supplies it (checkout mode), exactly as `planIntegrateCheckout`
165
+ * asks it.
166
+ *
167
+ * ctx: { worktreeState: { dirty }, base, remote, treePath, aheadOfRemoteBase,
168
+ * pushedAtHead, push, prCreateCommand, onBranch }
169
+ */
170
+ function planIntegratePr(spec, config, ctx) {
171
+ const { worktreeState = {}, base, treePath, onBranch } = ctx || {}
172
+ const remote = (ctx && ctx.remote) || 'origin'
173
+ const branch = spec.branch
174
+ const result = {
175
+ blocked: false, noop: false, reason: null, commands: [],
176
+ push: null, holdCommands: [], finish: null,
177
+ afterLand: noAfterLand(), afterLandPending: 'after-merge',
178
+ base, branch, remote,
179
+ }
180
+
181
+ // "Already landed" is answered FIRST, as the checkout planner does: a landed
182
+ // spec needs no action wherever the tree happens to be standing, and
183
+ // /spec-complete re-runs integrate on exactly that state. ONLY an explicit
184
+ // false lands here: `aheadOfRemoteBase: null` means `<remote>/<base>` could
185
+ // not be read (never fetched, no network), which is an absence — so it plans
186
+ // rather than claiming landed (`.claude/rules/negative-checks.md` rule 4);
187
+ // the plan's own fetch is what makes the next run answerable.
188
+ //
189
+ // A landed PR-mode branch carries the FINISH half: the host merged, so local
190
+ // base wants catching up and the deferred afterLand comes due here — this is
191
+ // completion run 2, the `hotfix finish` shape. `primaryPath` and
192
+ // `changedFiles` come from the caller like every other git fact; absent a
193
+ // primaryPath (pure tests, checkout mode asking oddly) the finish still
194
+ // names no commands rather than guessing a cwd.
195
+ if (ctx.aheadOfRemoteBase === false) {
196
+ const finish = {
197
+ commands: ctx.primaryPath
198
+ ? [
199
+ `git -C ${ctx.primaryPath} fetch ${remote} ${base}`,
200
+ `git -C ${ctx.primaryPath} merge --ff-only ${remote}/${base}`,
201
+ ]
202
+ : [],
203
+ afterLand: afterLandFor(config, ctx.primaryPath || null, rangeOf(ctx)),
204
+ }
205
+ return { ...result, noop: true, finish }
206
+ }
207
+ if (worktreeState.dirty) {
208
+ return { ...result, blocked: true, reason: 'worktree has uncommitted changes — commit the completion first' }
209
+ }
210
+ if (onBranch === false) {
211
+ return { ...result, blocked: true, reason: `the checkout is not on ${branch} — switch to it before landing` }
212
+ }
213
+
214
+ const commands = [
215
+ `git -C ${treePath} fetch ${remote} ${base}`,
216
+ `git -C ${treePath} rebase ${remote}/${base}`,
217
+ ]
218
+ // --force-with-lease because the rebase rewrites; -u so the first push sets
219
+ // the upstream the unpushed guard reads.
220
+ const pushCommand = `git -C ${treePath} push --force-with-lease -u ${remote} ${branch}`
221
+ // Composed by the host adapter where one exists; until the caller supplies
222
+ // one, a comment line that cannot be run by accident.
223
+ const prCommand = (ctx && ctx.prCreateCommand)
224
+ || `# open a pull request: ${branch} -> ${base} on ${remote} (gh / az repos)`
225
+
226
+ if (ctx.pushedAtHead || ctx.push) {
227
+ // Consent is satisfied — by the operator having already published the
228
+ // branch (the positive signal), or by `--push`. Pushing after the rebase is
229
+ // safe either way: a no-op push says "Everything up-to-date".
230
+ const via = ctx.pushedAtHead ? 'remote' : 'push'
231
+ return {
232
+ ...result,
233
+ commands: [...commands, pushCommand, prCommand],
234
+ push: { kind: 'push', via, remote, branch },
235
+ }
236
+ }
237
+ return {
238
+ ...result,
239
+ commands,
240
+ push: { kind: 'push', via: 'hold', remote, branch },
241
+ holdCommands: [pushCommand, prCommand],
242
+ }
243
+ }
244
+
119
245
  // The after-land half of a plan: `config.afterLand`, to run in `cwd` (the
120
246
  // primary checkout, standing on base) once the land commands have succeeded.
121
247
  // A blocked plan carries the empty form — nothing landed, so nothing follows.
@@ -164,4 +290,4 @@ function noAfterLand() {
164
290
  return { cwd: null, commands: [], entries: [], range: null }
165
291
  }
166
292
 
167
- module.exports = { planIntegrate, planIntegrateCheckout, afterLandFor, rangeOf }
293
+ module.exports = { planIntegrate, planIntegrateCheckout, planIntegratePr, afterLandFor, rangeOf }