mandrel 2.94.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 (110) hide show
  1. package/.agents/runtime-deps.json +6 -6
  2. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  3. package/.agents/scripts/board-backfill.js +1 -1
  4. package/.agents/scripts/boot-sweep.js +1 -1
  5. package/.agents/scripts/check-arch-cycles.js +69 -41
  6. package/.agents/scripts/check-doc-links.js +5 -7
  7. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  8. package/.agents/scripts/clean-temp.js +1 -1
  9. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  10. package/.agents/scripts/diagnose-friction.js +1 -1
  11. package/.agents/scripts/generate-lens-checklists.js +4 -4
  12. package/.agents/scripts/generate-skills-index.js +3 -2
  13. package/.agents/scripts/generate-workflows-doc.js +2 -1
  14. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  15. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  16. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  17. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  18. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  19. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  20. package/.agents/scripts/lib/baselines/components.js +21 -19
  21. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  22. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  23. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  24. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  25. package/.agents/scripts/lib/baselines/writer.js +2 -7
  26. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  27. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  28. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  29. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  30. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  31. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  32. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  33. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  34. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  35. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  36. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  37. package/.agents/scripts/lib/config/defaults.js +2 -1
  38. package/.agents/scripts/lib/config/qa.js +4 -5
  39. package/.agents/scripts/lib/config-schema.js +1 -8
  40. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  41. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  42. package/.agents/scripts/lib/coverage-utils.js +2 -1
  43. package/.agents/scripts/lib/cpu-pool.js +0 -1
  44. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  45. package/.agents/scripts/lib/doc-tiers.js +2 -1
  46. package/.agents/scripts/lib/gh-exec.js +21 -1
  47. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  48. package/.agents/scripts/lib/import-graph.js +13 -28
  49. package/.agents/scripts/lib/json-utils.js +11 -0
  50. package/.agents/scripts/lib/label-constants.js +7 -1
  51. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  52. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  53. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  54. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +9 -12
  55. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  56. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  57. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  58. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  59. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  60. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  61. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  62. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  63. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  64. package/.agents/scripts/lib/orchestration/merge-block-class.js +47 -48
  65. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  66. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  67. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  68. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  69. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  70. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  71. package/.agents/scripts/lib/orchestration/ticketing/transition.js +17 -21
  72. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  73. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  74. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  75. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  76. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  77. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  78. package/.agents/scripts/lib/util/regex.js +4 -0
  79. package/.agents/scripts/notify.js +1 -1
  80. package/.agents/scripts/plan-context.js +1 -1
  81. package/.agents/scripts/plan-critics.js +3 -11
  82. package/.agents/scripts/providers/github/auth.js +0 -4
  83. package/.agents/scripts/providers/github/project-board.js +0 -1
  84. package/.agents/scripts/providers/github/tickets.js +0 -2
  85. package/.agents/scripts/resync-status-column.js +1 -1
  86. package/.agents/scripts/run-tests.js +1 -1
  87. package/.agents/scripts/test-wrapper.js +1 -1
  88. package/.agents/scripts/update-ticket-state.js +4 -3
  89. package/.agents/scripts/validate-skills.js +2 -1
  90. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  91. package/.agents/workflows/audit-baselines.md +21 -9
  92. package/.agents/workflows/clean-git.md +1 -1
  93. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  94. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  95. package/README.md +1 -1
  96. package/docs/CHANGELOG.md +34 -0
  97. package/lib/cli/claude-code-version.js +13 -7
  98. package/lib/cli/doctor-checks/llm-review.js +12 -5
  99. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  100. package/lib/cli/doctor-checks/project-access.js +21 -8
  101. package/lib/cli/doctor-checks/read-json.js +2 -15
  102. package/lib/cli/doctor-checks/spawn.js +29 -9
  103. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  104. package/lib/cli/doctor-checks/toolchain.js +16 -12
  105. package/lib/cli/doctor.js +31 -8
  106. package/lib/cli/registry.js +7 -10
  107. package/lib/cli/sync.js +46 -10
  108. package/lib/cli/uninstall.js +259 -175
  109. package/lib/cli/update.js +3 -3
  110. package/package.json +23 -20
@@ -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,23 +14,16 @@ 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), the advisory-gate pair, and the REST
30
- * transport's merge-queue refusal (`merge-queue.js` owns its constant).
31
- */
32
- export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
33
- ...BLOCK_CLASSES,
34
27
  'predicate-refused',
35
28
  // Sourced from the gate's own constants so the vocabulary cannot drift.
36
29
  ADVISORY_GATE_RED_CLASS,
@@ -98,6 +91,42 @@ function hasChecksPendingEvidence(prProbe) {
98
91
  );
99
92
  }
100
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
+
101
130
  /**
102
131
  * Classify why a delivery run finished without a confirmed merge. First match
103
132
  * wins: (1) arm failure (a protection rejection at arm time still routes to
@@ -124,28 +153,10 @@ function hasChecksPendingEvidence(prProbe) {
124
153
  export function classifyMergeBlock(input) {
125
154
  const { armResult, prProbe, budget } = input ?? {};
126
155
 
127
- // 1. Arm failed: no armed PR is left to probe.
128
156
  if (armResult && armResult.armed === false) {
129
- const detail = armResult.reason ?? armResult.error ?? '';
130
- if (textIncludesAny(detail, BRANCH_PROTECTION_MARKERS)) {
131
- return {
132
- blockClass: 'branch-protection-human-required',
133
- reason:
134
- detail ||
135
- 'arm call rejected: branch protection requires a human action',
136
- };
137
- }
138
- return {
139
- blockClass: 'arm-failure',
140
- reason: detail || 'arm call failed for an unspecified reason',
141
- };
157
+ return classifyArmFailure(armResult);
142
158
  }
143
159
 
144
- // Positive evidence only: `unknown` routes to the fallback; `undefined`
145
- // (no probe) keeps the step-2 mapping.
146
- const checksStatus = prProbe?.checksStatus;
147
- const checksPendingEvidence = hasChecksPendingEvidence(prProbe);
148
-
149
160
  // 1b. Definitive, and before step 3 since it also presents as BLOCKED.
150
161
  // Head-anchored evidence, not the raw rollup (optional/superseded runs).
151
162
  if (requiredCheckFailedBlocksMerge(prProbe)) {
@@ -155,30 +166,18 @@ export function classifyMergeBlock(input) {
155
166
  };
156
167
  }
157
168
 
158
- // 2. BLOCKED is the steady state while checks run; a slow-CI timeout must
159
- // not read as human-required.
160
- if (
161
- budget &&
162
- budget.exhausted === true &&
163
- (checksPendingEvidence || checksStatus === undefined)
164
- ) {
169
+ if (isChecksPendingTimeout(prProbe, budget)) {
165
170
  return {
166
171
  blockClass: 'checks-pending-timeout',
167
172
  reason: `watch budget exhausted after ${budget.elapsedSeconds ?? 'an unknown number of'} seconds with required checks still pending`,
168
173
  };
169
174
  }
170
175
 
171
- // 3. BLOCKED counts only with checks settled — a genuinely human gate.
172
- if (prProbe) {
173
- if (
174
- prProbe.reviewDecision === 'REVIEW_REQUIRED' ||
175
- (prProbe.mergeStateStatus === 'BLOCKED' && !checksPendingEvidence)
176
- ) {
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
- };
181
- }
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
+ };
182
181
  }
183
182
 
184
183
  return {
@@ -403,6 +403,24 @@ function logPersistEpilogue({
403
403
  }
404
404
  }
405
405
 
406
+ /**
407
+ * A dry run wrote nothing, so it claims no ready flip and offers no deliver
408
+ * command; the per-ticket `dry-run: would …` lines already said what it would do.
409
+ *
410
+ * @param {Parameters<typeof logPersistEpilogue>[0] & { dryRun: boolean }} args
411
+ * @returns {void}
412
+ */
413
+ function logRunEpilogue({ dryRun, ...epilogue }) {
414
+ if (!dryRun) {
415
+ logPersistEpilogue(epilogue);
416
+ return;
417
+ }
418
+ Logger.info(
419
+ `[plan-persist] dry-run: validated ${epilogue.created.length} Story(ies); ` +
420
+ 'nothing was written to GitHub.',
421
+ );
422
+ }
423
+
406
424
  /**
407
425
  * @param {{
408
426
  * provider: object,
@@ -597,11 +615,12 @@ export async function runPlanPersist({
597
615
  supersede.sourceTicketOrigin = sourceTicketOrigin;
598
616
 
599
617
  await cleanupPlanDirs({ config, planDir, skipCleanup });
600
- logPersistEpilogue({
618
+ logRunEpilogue({
601
619
  created,
602
620
  primary,
603
621
  planRunLabel,
604
622
  planRunLabelApplied,
623
+ dryRun,
605
624
  });
606
625
 
607
626
  return {
@@ -5,6 +5,7 @@
5
5
  * @typedef {import('./types.js').Finding} Finding
6
6
  */
7
7
 
8
+ import { isObject } from '../../json-utils.js';
8
9
  import { buildFinding, unwrapEnvelope } from './parse-findings.js';
9
10
 
10
11
  export const FINDINGS_SCHEMA_JSON = JSON.stringify({
@@ -192,9 +193,7 @@ function failureReason(result, envelope) {
192
193
 
193
194
  function parseEnvelope(stdout) {
194
195
  const parsed = tryParseJson(stdout);
195
- return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
196
- ? parsed
197
- : null;
196
+ return isObject(parsed) ? parsed : null;
198
197
  }
199
198
 
200
199
  function isSuccess(result, envelope) {
@@ -7,6 +7,8 @@
7
7
  * @typedef {import('./types.js').Severity} Severity
8
8
  */
9
9
 
10
+ import { isObject } from '../../json-utils.js';
11
+
10
12
  /**
11
13
  * Unwrap a bare array, `{ findings }`, or either under `result`/`data`.
12
14
  * A non-array result is returned for the caller to reject.
@@ -16,12 +18,12 @@
16
18
  */
17
19
  export function unwrapEnvelope(parsed) {
18
20
  let value = parsed;
19
- if (value && typeof value === 'object' && !Array.isArray(value)) {
21
+ if (isObject(value)) {
20
22
  if (Array.isArray(value.findings)) value = value.findings;
21
23
  else if (value.result !== undefined) value = value.result;
22
24
  else if (value.data !== undefined) value = value.data;
23
25
  }
24
- if (value && typeof value === 'object' && !Array.isArray(value)) {
26
+ if (isObject(value)) {
25
27
  if (Array.isArray(value.findings)) value = value.findings;
26
28
  }
27
29
  return value;
@@ -15,7 +15,6 @@
15
15
  */
16
16
 
17
17
  import path from 'node:path';
18
-
19
18
  import {
20
19
  compare as compareMaintainability,
21
20
  projectRow as projectMaintainabilityRow,
@@ -32,6 +31,7 @@ import { getQuality } from '../../config-resolver.js';
32
31
  import { gitSync as defaultGitSync } from '../../git-utils.js';
33
32
  import { Logger as DefaultLogger } from '../../Logger.js';
34
33
  import { isScorableSourceFile } from '../../source-extensions.js';
34
+ import { toPosix } from '../../util/paths.js';
35
35
  import {
36
36
  currentBranch,
37
37
  listChangedFiles,
@@ -325,7 +325,7 @@ export async function runBaselineUpwardWriteback({
325
325
  }).filter(isScorableSourceFile);
326
326
 
327
327
  const writePath = resolveWritePath({ cwd: workTree });
328
- const relPath = path.relative(workTree, writePath).split(path.sep).join('/');
328
+ const relPath = toPosix(path.relative(workTree, writePath));
329
329
 
330
330
  const blocked = precheck({
331
331
  gate,
@@ -11,7 +11,6 @@
11
11
 
12
12
  import fs from 'node:fs';
13
13
  import path from 'node:path';
14
-
15
14
  import {
16
15
  diffRows as defaultDiffDeadExportRows,
17
16
  loadBaseline as loadJsonBaseline,
@@ -31,6 +30,7 @@ import {
31
30
  import { resolveDeadExportsMode } from '../../dead-exports-mode.js';
32
31
  import { gitSync as defaultGitSync } from '../../git-utils.js';
33
32
  import { Logger as DefaultLogger } from '../../Logger.js';
33
+ import { toPosix } from '../../util/paths.js';
34
34
  import { currentBranch, listDirtyPaths } from './format-autofix.js';
35
35
 
36
36
  const TAG = '[ratchet-shrink]';
@@ -81,7 +81,7 @@ function planDeadExportShrink({
81
81
  diffRows = defaultDiffDeadExportRows,
82
82
  }) {
83
83
  const { baseline } = resolveDeadExportsMode(production);
84
- const relPath = baseline.split(path.sep).join('/');
84
+ const relPath = toPosix(baseline);
85
85
  const committed = loadJsonBaseline(path.join(workTree, baseline));
86
86
  if (!Array.isArray(committed?.rows))
87
87
  return { relPath, reason: 'no-baseline' };
@@ -291,7 +291,7 @@ export function runRatchetShrinkWriteback({
291
291
  resolveDeadExportsMode(false).baseline,
292
292
  resolveDeadExportsMode(true).baseline,
293
293
  DEFAULT_CYCLOMATIC_BASELINE,
294
- ].map((p) => p.split(path.sep).join('/'));
294
+ ].map(toPosix);
295
295
  try {
296
296
  if (currentBranch(workTree, git) !== storyBranch) {
297
297
  return skip(logger, 'wrong-branch');