mandrel 2.93.0 → 2.95.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 (130) hide show
  1. package/.agents/docs/configuration.md +8 -3
  2. package/.agents/runtime-deps.json +6 -6
  3. package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
  4. package/.agents/schemas/story-deliver-terminal.schema.json +1 -0
  5. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  6. package/.agents/scripts/board-backfill.js +1 -1
  7. package/.agents/scripts/boot-sweep.js +1 -1
  8. package/.agents/scripts/check-arch-cycles.js +69 -41
  9. package/.agents/scripts/check-doc-links.js +5 -7
  10. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  11. package/.agents/scripts/clean-temp.js +1 -1
  12. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  13. package/.agents/scripts/diagnose-friction.js +1 -1
  14. package/.agents/scripts/generate-lens-checklists.js +4 -4
  15. package/.agents/scripts/generate-skills-index.js +3 -2
  16. package/.agents/scripts/generate-workflows-doc.js +2 -1
  17. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  18. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  19. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  20. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  21. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  22. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  23. package/.agents/scripts/lib/baselines/components.js +21 -19
  24. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  25. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  26. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  27. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  28. package/.agents/scripts/lib/baselines/writer.js +2 -7
  29. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  30. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  31. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  32. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  33. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  34. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  35. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  36. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  37. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  38. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  39. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  40. package/.agents/scripts/lib/config/defaults.js +2 -1
  41. package/.agents/scripts/lib/config/qa.js +4 -5
  42. package/.agents/scripts/lib/config-schema.js +1 -8
  43. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  44. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  45. package/.agents/scripts/lib/coverage-utils.js +2 -1
  46. package/.agents/scripts/lib/cpu-pool.js +0 -1
  47. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  48. package/.agents/scripts/lib/doc-tiers.js +2 -1
  49. package/.agents/scripts/lib/duplicate-search.js +52 -18
  50. package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js +47 -20
  51. package/.agents/scripts/lib/gh-exec.js +115 -25
  52. package/.agents/scripts/lib/gh-pr-rest.js +371 -0
  53. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  54. package/.agents/scripts/lib/import-graph.js +13 -28
  55. package/.agents/scripts/lib/json-utils.js +11 -0
  56. package/.agents/scripts/lib/label-constants.js +7 -1
  57. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  58. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  59. package/.agents/scripts/lib/orchestration/board-graphql-latch.js +75 -0
  60. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  61. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +82 -41
  62. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  63. package/.agents/scripts/lib/orchestration/column-sync.js +23 -21
  64. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  65. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  66. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  67. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  68. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  69. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  70. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  71. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  72. package/.agents/scripts/lib/orchestration/merge-block-class.js +48 -47
  73. package/.agents/scripts/lib/orchestration/merge-queue.js +49 -4
  74. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  75. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +2 -2
  76. package/.agents/scripts/lib/orchestration/required-checks.js +72 -12
  77. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  78. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  79. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +132 -58
  80. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +92 -9
  81. package/.agents/scripts/lib/orchestration/single-story-close/phases/graphql-preflight.js +41 -18
  82. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  83. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  84. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  85. package/.agents/scripts/lib/orchestration/ticketing/transition.js +18 -22
  86. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  87. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  88. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  89. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  90. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  91. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  92. package/.agents/scripts/lib/util/regex.js +4 -0
  93. package/.agents/scripts/notify.js +1 -1
  94. package/.agents/scripts/plan-context.js +1 -1
  95. package/.agents/scripts/plan-critics.js +3 -11
  96. package/.agents/scripts/providers/github/auth.js +0 -4
  97. package/.agents/scripts/providers/github/board-add.js +3 -3
  98. package/.agents/scripts/providers/github/compose.js +2 -0
  99. package/.agents/scripts/providers/github/errors.js +41 -0
  100. package/.agents/scripts/providers/github/project-board.js +0 -1
  101. package/.agents/scripts/providers/github/sub-issues-rest.js +55 -0
  102. package/.agents/scripts/providers/github/sub-issues.js +9 -1
  103. package/.agents/scripts/providers/github/tickets.js +0 -2
  104. package/.agents/scripts/resync-status-column.js +1 -1
  105. package/.agents/scripts/run-tests.js +1 -1
  106. package/.agents/scripts/single-story-confirm-merge.js +2 -0
  107. package/.agents/scripts/test-wrapper.js +1 -1
  108. package/.agents/scripts/update-ticket-state.js +4 -3
  109. package/.agents/scripts/validate-skills.js +2 -1
  110. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  111. package/.agents/workflows/audit-baselines.md +21 -9
  112. package/.agents/workflows/clean-git.md +1 -1
  113. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  114. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  115. package/README.md +1 -1
  116. package/docs/CHANGELOG.md +46 -0
  117. package/lib/cli/claude-code-version.js +13 -7
  118. package/lib/cli/doctor-checks/llm-review.js +12 -5
  119. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  120. package/lib/cli/doctor-checks/project-access.js +21 -8
  121. package/lib/cli/doctor-checks/read-json.js +2 -15
  122. package/lib/cli/doctor-checks/spawn.js +29 -9
  123. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  124. package/lib/cli/doctor-checks/toolchain.js +16 -12
  125. package/lib/cli/doctor.js +31 -8
  126. package/lib/cli/registry.js +7 -10
  127. package/lib/cli/sync.js +46 -10
  128. package/lib/cli/uninstall.js +259 -175
  129. package/lib/cli/update.js +3 -3
  130. package/package.json +23 -20
@@ -5,14 +5,7 @@
5
5
  */
6
6
 
7
7
  import { Logger } from '../../../Logger.js';
8
- import {
9
- canFastForward,
10
- checkoutBranch,
11
- currentBranch,
12
- fetchRef,
13
- isWorkingTreeClean,
14
- mergeFastForward,
15
- } from './git-probes.js';
8
+ import { defaultFfProbes } from './git-probes-ff.js';
16
9
 
17
10
  const TAG = '[git-cleanup]';
18
11
 
@@ -26,10 +19,10 @@ export function planFastForward(ctx) {
26
19
  cwd,
27
20
  baseBranch,
28
21
  remoteName = 'origin',
29
- isCleanFn = isWorkingTreeClean,
30
- currentBranchFn = currentBranch,
31
- fetchFn = fetchRef,
32
- canFastForwardFn = canFastForward,
22
+ isCleanFn = defaultFfProbes.isClean,
23
+ currentBranchFn = defaultFfProbes.currentBranch,
24
+ fetchFn = defaultFfProbes.fetch,
25
+ canFastForwardFn = defaultFfProbes.canFastForward,
33
26
  } = ctx;
34
27
  if (!isCleanFn(cwd)) return { runnable: false, reason: 'dirty-tree' };
35
28
  const fetchRes = fetchFn(cwd, remoteName, baseBranch);
@@ -111,8 +104,8 @@ export function executeFastForward(ctx) {
111
104
  baseBranch,
112
105
  remoteName = 'origin',
113
106
  plan,
114
- checkoutFn = checkoutBranch,
115
- mergeFn = mergeFastForward,
107
+ checkoutFn = defaultFfProbes.checkout,
108
+ mergeFn = defaultFfProbes.merge,
116
109
  logger = Logger,
117
110
  } = ctx;
118
111
  if (!plan.runnable) {
@@ -22,26 +22,6 @@ export function isWorktreeLockFailure(stderr) {
22
22
  return WORKTREE_LOCK_RE.test(stderr ?? '');
23
23
  }
24
24
 
25
- export function isWorkingTreeClean(cwd) {
26
- return defaultFfProbes.isClean(cwd);
27
- }
28
-
29
- export function fetchRef(cwd, remoteName, ref) {
30
- return defaultFfProbes.fetch(cwd, remoteName, ref);
31
- }
32
-
33
- export function canFastForward(cwd, baseBranch, remoteName) {
34
- return defaultFfProbes.canFastForward(cwd, baseBranch, remoteName);
35
- }
36
-
37
- export function checkoutBranch(cwd, branch) {
38
- return defaultFfProbes.checkout(cwd, branch);
39
- }
40
-
41
- export function mergeFastForward(cwd, ref) {
42
- return defaultFfProbes.merge(cwd, ref);
43
- }
44
-
45
25
  /**
46
26
  * The single implementation of the FF git wrappers; callers needing an
47
27
  * injected spawn use this factory rather than a parallel copy.
@@ -109,7 +89,8 @@ export function makeFfProbes(spawn = gitSpawn) {
109
89
  };
110
90
  }
111
91
 
112
- const defaultFfProbes = makeFfProbes(gitSpawn);
92
+ /** The FF wrappers bound to the real `gitSpawn` — the phase defaults. */
93
+ export const defaultFfProbes = makeFfProbes(gitSpawn);
113
94
 
114
95
  /**
115
96
  * The destructive worktree / prune / stash wrappers over an injected spawn,
@@ -1,6 +1,5 @@
1
1
  /**
2
- * Branch / worktree / PR probes for the git-cleanup branches planner; also
3
- * re-exports the fast-forward probes from `git-probes-ff.js`.
2
+ * Branch / worktree / PR probes for the git-cleanup branches planner.
4
3
  *
5
4
  * @module lib/orchestration/git-cleanup/phases/git-probes
6
5
  */
@@ -12,18 +11,10 @@ import { parseWorktreePorcelain } from '../../../worktree-manager.js';
12
11
  import { makeWorktreeOps } from './git-probes-ff.js';
13
12
  import { resolveMergedTip } from './merged-tip.js';
14
13
 
15
- export {
16
- canFastForward,
17
- checkoutBranch,
18
- fetchRef,
19
- isWorkingTreeClean,
20
- mergeFastForward,
21
- } from './git-probes-ff.js';
22
-
23
14
  export const { removeWorktree, pruneRemoteTracking, dropStash } =
24
15
  makeWorktreeOps(gitSpawn);
25
16
 
26
- /* node:coverage ignore next */
17
+ /* node:coverage ignore next -- thin git spawn shim; real-git run in git-cleanup-content-merged.integration.test.js */
27
18
  export function listLocalBranches(cwd) {
28
19
  const res = gitSpawn(
29
20
  cwd,
@@ -60,7 +51,7 @@ function shortRemoteNames(stdout, remoteName) {
60
51
  .filter(Boolean);
61
52
  }
62
53
 
63
- /* node:coverage ignore next */
54
+ /* node:coverage ignore next -- thin git spawn shim; parsing tested via __testing.shortRemoteNames */
64
55
  export function listRemoteBranches(cwd, remoteName = 'origin') {
65
56
  const res = gitSpawn(
66
57
  cwd,
@@ -82,7 +73,7 @@ export function listRemoteBranches(cwd, remoteName = 'origin') {
82
73
  * @param {string} [remoteName]
83
74
  * @returns {string[]}
84
75
  */
85
- /* node:coverage ignore next */
76
+ /* node:coverage ignore next -- thin git spawn shim; parsing tested via __testing.shortRemoteNames */
86
77
  export function listRemoteMergedBranches(cwd, base, remoteName = 'origin') {
87
78
  const res = gitSpawn(
88
79
  cwd,
@@ -96,7 +87,7 @@ export function listRemoteMergedBranches(cwd, base, remoteName = 'origin') {
96
87
  return shortRemoteNames(res.stdout, remoteName);
97
88
  }
98
89
 
99
- /* node:coverage ignore next */
90
+ /* node:coverage ignore next -- thin git spawn shim; real-git run in git-cleanup-content-merged.integration.test.js */
100
91
  export function listMergedBranches(cwd, base) {
101
92
  const res = gitSpawn(
102
93
  cwd,
@@ -135,14 +126,14 @@ export function freshAnchoredMergedSet({
135
126
  return set;
136
127
  }
137
128
 
138
- /* node:coverage ignore next */
129
+ /* node:coverage ignore next -- thin git spawn shim; real-git run in git-cleanup-content-merged.integration.test.js */
139
130
  export function currentBranch(cwd) {
140
131
  const res = gitSpawn(cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD');
141
132
  if (res.status !== 0) return null;
142
133
  return res.stdout.trim() || null;
143
134
  }
144
135
 
145
- /* node:coverage ignore next */
136
+ /* node:coverage ignore next -- thin git spawn shim; real-git run in git-cleanup-content-merged.integration.test.js */
146
137
  export function readProtectedConfig(cwd) {
147
138
  const res = gitSpawn(cwd, 'config', '--get', 'branch.protectedBranches');
148
139
  if (res.status !== 0) return [];
@@ -152,7 +143,7 @@ export function readProtectedConfig(cwd) {
152
143
  .filter(Boolean);
153
144
  }
154
145
 
155
- /* node:coverage ignore next */
146
+ /* node:coverage ignore next -- thin git spawn shim; parsing tested via parseWorktreePorcelain */
156
147
  export function worktreesByBranch(cwd) {
157
148
  const res = gitSpawn(cwd, 'worktree', 'list', '--porcelain');
158
149
  if (res.status !== 0) return new Map();
@@ -165,8 +156,8 @@ export function worktreesByBranch(cwd) {
165
156
  return map;
166
157
  }
167
158
 
168
- /* node:coverage ignore next */
169
159
  // Synchronous on purpose: `planCleanup` is a sync planner.
160
+ /* node:coverage ignore next -- thin gh spawn shim; tests inject runGh */
170
161
  export function defaultGhRunner(args, { cwd }) {
171
162
  return runGhOrThrow(args, { cwd, encoding: 'utf8' }, execFileCapture);
172
163
  }
@@ -354,8 +345,8 @@ export function branchTipSha({
354
345
  return res.status !== 0 ? null : validSha(firstLsRemoteSha(res.stdout));
355
346
  }
356
347
 
357
- /* node:coverage ignore next */
358
348
  // Guards the `<remote>/<base>` ancestry union.
349
+ /* node:coverage ignore next -- thin git spawn shim; tests inject refExistsFn */
359
350
  export function refExists(cwd, ref) {
360
351
  const res = gitSpawn(cwd, 'rev-parse', '--verify', '--quiet', ref);
361
352
  return res.status === 0;
@@ -370,7 +361,7 @@ export function refExists(cwd, ref) {
370
361
  * @param {{ localExists?: boolean, remoteName?: string }} [opts]
371
362
  * @returns {string | null}
372
363
  */
373
- /* node:coverage ignore next */
364
+ /* node:coverage ignore next -- thin git spawn shim; real-git run in git-cleanup-content-merged.integration.test.js */
374
365
  export function branchLastCommitAt(cwd, branch, opts = {}) {
375
366
  const { localExists = true, remoteName = 'origin' } = opts;
376
367
  const ref = localExists
@@ -1,7 +1,13 @@
1
1
  /**
2
- * Per-phase drivers for git-cleanup. Each `runXPhase` composes a pure
3
- * `decideXPhase` (returns an action record) with an impure `executeXPhase`,
4
- * prompting in between for `prompt-then-execute`.
2
+ * Per-phase drivers for git-cleanup. Each exported `runXPhase` composes a
3
+ * pure `decideXPhase` (returns an action record) with an impure
4
+ * `executeXPhase`, prompting in between for `prompt-then-execute`.
5
+ *
6
+ * Every `runXPhase` takes an optional trailing `deps` bag: `prompt` (and
7
+ * `promptStash` for the stash phase) replaces the readline prompt, and every
8
+ * other key is forwarded to the phase module's plan / execute ctx as an
9
+ * injected seam (`fetchFn`, `deleteLocalFn`, `pruneFn`, `stashListerFn`, …).
10
+ * The CLI passes none, so production binds the real git / readline.
5
11
  *
6
12
  * @module lib/orchestration/git-cleanup/phases/phase-drivers
7
13
  */
@@ -27,13 +33,11 @@ import {
27
33
 
28
34
  const TAG = '[git-cleanup]';
29
35
 
30
- /* node:coverage ignore next */
31
36
  function emitCandidateList(plan, opts, baseBranch) {
32
37
  for (const l of renderCandidateList({ plan, opts, baseBranch }))
33
38
  Logger.info(l);
34
39
  }
35
40
 
36
- /* node:coverage ignore next */
37
41
  function emitExecutionHuman(result) {
38
42
  for (const r of result.worktrees) {
39
43
  Logger.info(renderExecutionLine(r, 'worktree'));
@@ -61,7 +65,7 @@ function emitExecutionHuman(result) {
61
65
  * @param {string} state.baseBranch
62
66
  * @param {string} state.cwd
63
67
  */
64
- export function decideFastForwardPhase(state) {
68
+ function decideFastForwardPhase(state) {
65
69
  const { plan, opts, baseBranch, cwd } = state;
66
70
  if (!plan.runnable) {
67
71
  return {
@@ -107,59 +111,53 @@ export function decideFastForwardPhase(state) {
107
111
  return { kind: 'execute', executeArgs };
108
112
  }
109
113
 
110
- export async function executeFastForwardPhase(action) {
111
- if (action.kind === 'skip' || action.kind === 'dry-run') {
112
- if (action.logMessage) Logger.info(action.logMessage);
113
- return action.result;
114
- }
114
+ /** `execute` runs the fast-forward; `skip` / `dry-run` log and return. */
115
+ function executeFastForwardPhase(action, seams) {
115
116
  if (action.kind === 'execute') {
116
- return executeFastForward(action.executeArgs);
117
+ return executeFastForward({ ...action.executeArgs, ...seams });
117
118
  }
118
- throw new Error(
119
- `executeFastForwardPhase: unsupported action kind '${action.kind}'`,
120
- );
119
+ Logger.info(action.logMessage);
120
+ return action.result;
121
121
  }
122
122
 
123
- /* node:coverage ignore next */
124
- export async function runFastForwardPhase(opts, cwd, baseBranch) {
123
+ export async function runFastForwardPhase(opts, cwd, baseBranch, deps = {}) {
124
+ const { prompt = promptYesNo, ...seams } = deps;
125
125
  Logger.info(`${TAG} ── phase: fast-forward-main ──`);
126
- const plan = planFastForward({ cwd, baseBranch });
126
+ const plan = planFastForward({ cwd, baseBranch, ...seams });
127
127
  const action = decideFastForwardPhase({ plan, opts, baseBranch, cwd });
128
128
  if (action.kind === 'prompt-then-execute') {
129
- if (action.logMessage) Logger.info(action.logMessage);
130
- const go = await promptYesNo(action.promptMessage);
129
+ const go = await prompt(action.promptMessage);
131
130
  if (!go) return action.declinedResult;
132
- return executeFastForward(action.executeArgs);
131
+ return executeFastForward({ ...action.executeArgs, ...seams });
133
132
  }
134
- return executeFastForwardPhase(action);
133
+ return executeFastForwardPhase(action, seams);
135
134
  }
136
135
 
137
136
  // =====================================================================
138
137
  // Prune phase
139
138
  // =====================================================================
140
139
 
141
- /* node:coverage ignore next */
142
- export async function runPrunePhase(opts, cwd) {
140
+ const PRUNE_SKIPPED = Object.freeze({
141
+ ok: true,
142
+ attempted: false,
143
+ remote: 'origin',
144
+ pruned: [],
145
+ });
146
+
147
+ export async function runPrunePhase(opts, cwd, deps = {}) {
148
+ const { prompt = promptYesNo, ...seams } = deps;
143
149
  Logger.info(`${TAG} ── phase: prune-remotes ──`);
144
150
  if (opts.dryRun) {
145
151
  Logger.info(`${TAG} DRY RUN — would run \`git fetch --prune origin\``);
146
- return { ok: true, attempted: false, remote: 'origin', pruned: [] };
152
+ return { ...PRUNE_SKIPPED };
147
153
  }
148
- if (!opts.yes) {
149
- const go = await promptYesNo(
154
+ const go =
155
+ opts.yes ||
156
+ (await prompt(
150
157
  `${TAG} Run \`git fetch --prune origin\` to drop stale tracking refs?`,
151
- );
152
- if (!go) {
153
- return {
154
- ok: true,
155
- attempted: false,
156
- remote: 'origin',
157
- pruned: [],
158
- reason: 'declined',
159
- };
160
- }
161
- }
162
- return executePrune({ cwd });
158
+ ));
159
+ if (!go) return { ...PRUNE_SKIPPED, reason: 'declined' };
160
+ return executePrune({ cwd, ...seams });
163
161
  }
164
162
 
165
163
  // =====================================================================
@@ -182,7 +180,7 @@ function countActionableCandidates(candidates, remote) {
182
180
  * @param {object} state.opts
183
181
  * @param {string} state.cwd
184
182
  */
185
- export function decideBranchPhase(state) {
183
+ function decideBranchPhase(state) {
186
184
  const { plan, opts, cwd } = state;
187
185
  if (opts.dryRun) {
188
186
  return { kind: 'dry-run', plan, result: { plan, result: null } };
@@ -227,22 +225,15 @@ export function decideBranchPhase(state) {
227
225
  };
228
226
  }
229
227
 
230
- export async function executeBranchPhase(action) {
231
- if (action.kind === 'dry-run' || action.kind === 'no-candidates') {
232
- return action.result;
233
- }
234
- if (action.kind === 'execute') {
235
- const result = executeCleanup(action.executeArgs);
236
- emitExecutionHuman(result);
237
- return { plan: action.plan, result };
238
- }
239
- throw new Error(
240
- `executeBranchPhase: unsupported action kind '${action.kind}'`,
241
- );
228
+ /** Reap the decided candidates and print the per-ref outcome lines. */
229
+ function executeBranchPhase(action, seams) {
230
+ const result = executeCleanup({ ...action.executeArgs, ...seams });
231
+ emitExecutionHuman(result);
232
+ return { plan: action.plan, result };
242
233
  }
243
234
 
244
- /* node:coverage ignore next */
245
- export async function runBranchPhase(opts, cwd, baseBranch) {
235
+ export async function runBranchPhase(opts, cwd, baseBranch, deps = {}) {
236
+ const { prompt = promptYesNo, ...seams } = deps;
246
237
  Logger.info(`${TAG} ── phase: branches ──`);
247
238
  const filter = buildGlobFilter({
248
239
  include: opts.include,
@@ -254,17 +245,17 @@ export async function runBranchPhase(opts, cwd, baseBranch) {
254
245
  baseBranch,
255
246
  filter,
256
247
  includeRemoteOnly: true,
248
+ ...seams,
257
249
  });
258
250
  emitCandidateList(plan, opts, baseBranch);
259
251
  const action = decideBranchPhase({ plan, opts, cwd });
260
252
  if (action.kind === 'prompt-then-execute') {
261
- const go = await promptYesNo(action.promptMessage);
253
+ const go = await prompt(action.promptMessage);
262
254
  if (!go) return action.declinedResult;
263
- const result = executeCleanup(action.executeArgs);
264
- emitExecutionHuman(result);
265
- return { plan, result };
255
+ } else if (action.kind !== 'execute') {
256
+ return action.result;
266
257
  }
267
- return executeBranchPhase(action);
258
+ return executeBranchPhase(action, seams);
268
259
  }
269
260
 
270
261
  // =====================================================================
@@ -273,18 +264,12 @@ export async function runBranchPhase(opts, cwd, baseBranch) {
273
264
 
274
265
  /**
275
266
  * @param {object} state
276
- * @param {Array} state.stashes
267
+ * @param {Array} state.stashes non-empty — `runStashPhase` returns early on none
277
268
  * @param {object} state.opts
278
269
  * @param {string} state.cwd
279
270
  */
280
- export function decideStashPhase(state) {
271
+ function decideStashPhase(state) {
281
272
  const { stashes, opts, cwd } = state;
282
- if (stashes.length === 0) {
283
- return {
284
- kind: 'no-stashes',
285
- result: { ok: true, actions: [], failures: [] },
286
- };
287
- }
288
273
  if (opts.dryRun) {
289
274
  return {
290
275
  kind: 'dry-run',
@@ -308,27 +293,21 @@ export function decideStashPhase(state) {
308
293
  };
309
294
  }
310
295
 
311
- export async function executeStashPhase(action) {
312
- if (action.kind === 'no-stashes' || action.kind === 'dry-run') {
313
- return action.result;
314
- }
315
- if (action.kind === 'execute-allowlist') {
316
- const { cwd, stashes, allowlist } = action.executeArgs;
317
- const decideFn = buildAllowlistDecider(allowlist);
318
- return executeStashes({ cwd, stashes, decideFn });
319
- }
320
- if (action.kind === 'execute-interactive') {
321
- const { cwd, stashes } = action.executeArgs;
322
- return executeStashes({ cwd, stashes, decideFn: promptStashDecision });
323
- }
324
- throw new Error(
325
- `executeStashPhase: unsupported action kind '${action.kind}'`,
326
- );
296
+ /** `execute-allowlist` drops the `--drop-stash` refs; interactive prompts. */
297
+ function executeStashPhase(action, promptStash, seams) {
298
+ if (action.kind === 'dry-run') return action.result;
299
+ const { cwd, stashes, allowlist } = action.executeArgs;
300
+ const decideFn =
301
+ action.kind === 'execute-allowlist'
302
+ ? buildAllowlistDecider(allowlist)
303
+ : promptStash;
304
+ return executeStashes({ ...seams, cwd, stashes, decideFn });
327
305
  }
328
306
 
329
- export async function runStashPhase(opts, cwd) {
307
+ export async function runStashPhase(opts, cwd, deps = {}) {
308
+ const { promptStash = promptStashDecision, ...seams } = deps;
330
309
  Logger.info(`${TAG} ── phase: stashes ──`);
331
- const { stashes } = planStashes({ cwd });
310
+ const { stashes } = planStashes({ cwd, ...seams });
332
311
  if (stashes.length === 0) {
333
312
  Logger.info(`${TAG} no stashes to triage`);
334
313
  return { ok: true, actions: [], failures: [] };
@@ -342,5 +321,5 @@ export async function runStashPhase(opts, cwd) {
342
321
  );
343
322
  }
344
323
  const action = decideStashPhase({ stashes, opts, cwd });
345
- return executeStashPhase(action);
324
+ return executeStashPhase(action, promptStash, seams);
346
325
  }
@@ -22,7 +22,7 @@ export function decideStashAnswer(answer) {
22
22
  return 'keep';
23
23
  }
24
24
 
25
- /* node:coverage ignore next */
25
+ /* node:coverage ignore next -- thin readline shim on process.stdin; drivers inject prompt */
26
26
  export async function promptYesNo(question) {
27
27
  const rl = readline.createInterface({
28
28
  input: process.stdin,
@@ -38,7 +38,7 @@ export async function promptYesNo(question) {
38
38
  }
39
39
  }
40
40
 
41
- /* node:coverage ignore next */
41
+ /* node:coverage ignore next -- thin readline shim; answer parsing tested via decideStashAnswer */
42
42
  export async function promptStashDecision(entry) {
43
43
  const rl = readline.createInterface({
44
44
  input: process.stdin,
@@ -33,7 +33,7 @@ export function parseStashList(stdout) {
33
33
  return out;
34
34
  }
35
35
 
36
- /* node:coverage ignore next */
36
+ /* node:coverage ignore next -- thin git spawn shim; parsing tested via parseStashList */
37
37
  function listStashes(cwd) {
38
38
  const res = gitSpawn(cwd, 'stash', 'list', '--format=%gd|%ci|%s');
39
39
  if (res.status !== 0) return [];
@@ -64,7 +64,16 @@ export function buildAllowlistDecider(allowlist) {
64
64
  return (entry) => (set.has(entry.ref) ? 'drop' : 'keep');
65
65
  }
66
66
 
67
- function applyDecision({
67
+ // A throwing prompt keeps the stash.
68
+ async function decide(decideFn, s) {
69
+ try {
70
+ return await decideFn(s);
71
+ } catch {
72
+ return 'keep';
73
+ }
74
+ }
75
+
76
+ async function applyDecision({
68
77
  s,
69
78
  decideFn,
70
79
  dropFn,
@@ -73,12 +82,12 @@ function applyDecision({
73
82
  failures,
74
83
  logger,
75
84
  }) {
76
- const decision = decideFn(s);
85
+ const decision = await decide(decideFn, s);
77
86
  if (decision === 'quit') {
78
87
  actions.push({ ref: s.ref, action: 'quit' });
79
88
  return { quit: true };
80
89
  }
81
- if (decision === 'keep') {
90
+ if (decision !== 'drop') {
82
91
  actions.push({ ref: s.ref, action: 'keep' });
83
92
  return { quit: false };
84
93
  }
@@ -104,7 +113,7 @@ function applyDecision({
104
113
  * `decideFn` so interactive prompts (readline) and non-interactive
105
114
  * allowlists (`--drop-stashes <ref>`) share the same engine.
106
115
  */
107
- export function executeStashes(ctx) {
116
+ export async function executeStashes(ctx) {
108
117
  const { cwd, stashes, decideFn, dropFn = dropStash, logger = Logger } = ctx;
109
118
  const actions = [];
110
119
  const failures = [];
@@ -119,7 +128,7 @@ export function executeStashes(ctx) {
119
128
  actions.push({ ref: s.ref, action: 'quit' });
120
129
  continue;
121
130
  }
122
- const out = applyDecision({
131
+ const out = await applyDecision({
123
132
  s,
124
133
  decideFn,
125
134
  dropFn,
@@ -7,7 +7,10 @@
7
7
  * value.
8
8
  */
9
9
 
10
- import { isValidBlockClass } from '../merge-block-class.js';
10
+ import {
11
+ isValidBlockClass,
12
+ MERGE_UNLANDED_BLOCK_CLASSES,
13
+ } from '../merge-block-class.js';
11
14
  import {
12
15
  appendLedgerEvent,
13
16
  assertMergeTerminalFields,
@@ -48,7 +51,7 @@ export function emitMergeUnlanded(opts) {
48
51
  });
49
52
  if (!isValidBlockClass(blockClass)) {
50
53
  throw new Error(
51
- `emitMergeUnlanded: blockClass "${blockClass}" is not a recognised merge-block-class value`,
54
+ `emitMergeUnlanded: blockClass "${blockClass}" must be one of: ${MERGE_UNLANDED_BLOCK_CLASSES.join(', ')}`,
52
55
  );
53
56
  }
54
57
 
@@ -14,26 +14,21 @@ import {
14
14
  } from './merge-poll.js';
15
15
 
16
16
  /**
17
- * Every class `classifyMergeBlock` can return, in its evaluation priority.
17
+ * Every valid `merge.unlanded` attribution: the first five are what
18
+ * `classifyMergeBlock` returns, in priority order; the rest are emitted
19
+ * directly (`merge-queue.js` owns the REST refusal constant).
18
20
  */
19
- export const BLOCK_CLASSES = Object.freeze([
21
+ export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
20
22
  CHECKS_FAILED_CLASS,
21
23
  'checks-pending-timeout',
22
24
  'branch-protection-human-required',
23
25
  'arm-failure',
24
26
  'api-race-other',
25
- ]);
26
-
27
- /**
28
- * Plus classes emitted directly, never by the classifier: `predicate-refused`
29
- * (kept so archived records validate) and the advisory-gate pair.
30
- */
31
- export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
32
- ...BLOCK_CLASSES,
33
27
  'predicate-refused',
34
28
  // Sourced from the gate's own constants so the vocabulary cannot drift.
35
29
  ADVISORY_GATE_RED_CLASS,
36
30
  ADVISORY_GATE_INCONCLUSIVE_CLASS,
31
+ 'merge-queue-rest-unsupported',
37
32
  ]);
38
33
 
39
34
  const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);
@@ -96,6 +91,42 @@ function hasChecksPendingEvidence(prProbe) {
96
91
  );
97
92
  }
98
93
 
94
+ // Step 1: a failed arm leaves no armed PR to probe.
95
+ function classifyArmFailure(armResult) {
96
+ const detail = armResult.reason ?? armResult.error ?? '';
97
+ if (textIncludesAny(detail, BRANCH_PROTECTION_MARKERS)) {
98
+ return {
99
+ blockClass: 'branch-protection-human-required',
100
+ reason:
101
+ detail ||
102
+ 'arm call rejected: branch protection requires a human action',
103
+ };
104
+ }
105
+ return {
106
+ blockClass: 'arm-failure',
107
+ reason: detail || 'arm call failed for an unspecified reason',
108
+ };
109
+ }
110
+
111
+ // Step 2: a slow-CI timeout must not read as human-required; `unknown`
112
+ // routes to the fallback, `undefined` keeps this mapping.
113
+ function isChecksPendingTimeout(prProbe, budget) {
114
+ if (budget?.exhausted !== true) return false;
115
+ return (
116
+ hasChecksPendingEvidence(prProbe) || prProbe?.checksStatus === undefined
117
+ );
118
+ }
119
+
120
+ // Step 3: BLOCKED counts only with checks settled — a genuinely human gate.
121
+ function isHumanRequired(prProbe) {
122
+ if (!prProbe) return false;
123
+ return (
124
+ prProbe.reviewDecision === 'REVIEW_REQUIRED' ||
125
+ (prProbe.mergeStateStatus === 'BLOCKED' &&
126
+ !hasChecksPendingEvidence(prProbe))
127
+ );
128
+ }
129
+
99
130
  /**
100
131
  * Classify why a delivery run finished without a confirmed merge. First match
101
132
  * wins: (1) arm failure (a protection rejection at arm time still routes to
@@ -122,28 +153,10 @@ function hasChecksPendingEvidence(prProbe) {
122
153
  export function classifyMergeBlock(input) {
123
154
  const { armResult, prProbe, budget } = input ?? {};
124
155
 
125
- // 1. Arm failed: no armed PR is left to probe.
126
156
  if (armResult && armResult.armed === false) {
127
- const detail = armResult.reason ?? armResult.error ?? '';
128
- if (textIncludesAny(detail, BRANCH_PROTECTION_MARKERS)) {
129
- return {
130
- blockClass: 'branch-protection-human-required',
131
- reason:
132
- detail ||
133
- 'arm call rejected: branch protection requires a human action',
134
- };
135
- }
136
- return {
137
- blockClass: 'arm-failure',
138
- reason: detail || 'arm call failed for an unspecified reason',
139
- };
157
+ return classifyArmFailure(armResult);
140
158
  }
141
159
 
142
- // Positive evidence only: `unknown` routes to the fallback; `undefined`
143
- // (no probe) keeps the step-2 mapping.
144
- const checksStatus = prProbe?.checksStatus;
145
- const checksPendingEvidence = hasChecksPendingEvidence(prProbe);
146
-
147
160
  // 1b. Definitive, and before step 3 since it also presents as BLOCKED.
148
161
  // Head-anchored evidence, not the raw rollup (optional/superseded runs).
149
162
  if (requiredCheckFailedBlocksMerge(prProbe)) {
@@ -153,30 +166,18 @@ export function classifyMergeBlock(input) {
153
166
  };
154
167
  }
155
168
 
156
- // 2. BLOCKED is the steady state while checks run; a slow-CI timeout must
157
- // not read as human-required.
158
- if (
159
- budget &&
160
- budget.exhausted === true &&
161
- (checksPendingEvidence || checksStatus === undefined)
162
- ) {
169
+ if (isChecksPendingTimeout(prProbe, budget)) {
163
170
  return {
164
171
  blockClass: 'checks-pending-timeout',
165
172
  reason: `watch budget exhausted after ${budget.elapsedSeconds ?? 'an unknown number of'} seconds with required checks still pending`,
166
173
  };
167
174
  }
168
175
 
169
- // 3. BLOCKED counts only with checks settled — a genuinely human gate.
170
- if (prProbe) {
171
- if (
172
- prProbe.reviewDecision === 'REVIEW_REQUIRED' ||
173
- (prProbe.mergeStateStatus === 'BLOCKED' && !checksPendingEvidence)
174
- ) {
175
- return {
176
- blockClass: 'branch-protection-human-required',
177
- reason: `PR requires human action (reviewDecision=${prProbe.reviewDecision ?? 'n/a'}, mergeStateStatus=${prProbe.mergeStateStatus ?? 'n/a'})`,
178
- };
179
- }
176
+ if (isHumanRequired(prProbe)) {
177
+ return {
178
+ blockClass: 'branch-protection-human-required',
179
+ reason: `PR requires human action (reviewDecision=${prProbe.reviewDecision ?? 'n/a'}, mergeStateStatus=${prProbe.mergeStateStatus ?? 'n/a'})`,
180
+ };
180
181
  }
181
182
 
182
183
  return {