mandrel 2.90.0 → 2.92.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 (175) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +31 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/check-arch-cycles.js +1 -5
  14. package/.agents/scripts/check-context-budget.js +1 -5
  15. package/.agents/scripts/check-cyclomatic.js +1 -5
  16. package/.agents/scripts/check-dead-exports.js +23 -14
  17. package/.agents/scripts/check-doc-links.js +4 -4
  18. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  19. package/.agents/scripts/coverage-capture.js +14 -6
  20. package/.agents/scripts/diagnose-friction.js +8 -10
  21. package/.agents/scripts/generate-workflows-doc.js +5 -0
  22. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  24. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  25. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  26. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  27. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  28. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  29. package/.agents/scripts/lib/baselines/components.js +5 -5
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  32. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  33. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  34. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  36. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  37. package/.agents/scripts/lib/baselines/writer.js +4 -4
  38. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  39. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  40. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  41. package/.agents/scripts/lib/child-exec.js +4 -4
  42. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  43. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  44. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  45. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  46. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  47. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  48. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  49. package/.agents/scripts/lib/config/commands.js +82 -7
  50. package/.agents/scripts/lib/config/explain.js +2 -1
  51. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  52. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  53. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  54. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  55. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  56. package/.agents/scripts/lib/config/git-roots.js +120 -0
  57. package/.agents/scripts/lib/config/quality.js +46 -50
  58. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  59. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  60. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  61. package/.agents/scripts/lib/config-resolver.js +5 -9
  62. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  63. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  64. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  65. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  67. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  68. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  69. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  70. package/.agents/scripts/lib/coverage-capture.js +31 -20
  71. package/.agents/scripts/lib/coverage-utils.js +34 -16
  72. package/.agents/scripts/lib/cpu-pool.js +2 -4
  73. package/.agents/scripts/lib/crap-engine.js +19 -1
  74. package/.agents/scripts/lib/crap-utils.js +2 -1
  75. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  76. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  77. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  78. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  79. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  80. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  81. package/.agents/scripts/lib/gh-env.js +72 -0
  82. package/.agents/scripts/lib/gh-exec.js +26 -1
  83. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  84. package/.agents/scripts/lib/npm-scripts.js +1 -1
  85. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  86. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  87. package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
  88. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  89. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  90. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  91. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  92. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  93. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  94. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  95. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  96. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  97. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  98. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  99. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  100. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  101. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  102. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  103. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  104. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  105. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +4 -1
  106. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +49 -83
  107. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  108. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  109. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  110. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  111. package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
  112. package/.agents/scripts/lib/orchestration/story-init-result.js +11 -0
  113. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  114. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  115. package/.agents/scripts/lib/orchestration/ticketing/transition.js +47 -21
  116. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  117. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  118. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  119. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  120. package/.agents/scripts/lib/source-extensions.js +30 -15
  121. package/.agents/scripts/lib/test-run-credit.js +1 -9
  122. package/.agents/scripts/lib/test-temp.js +22 -21
  123. package/.agents/scripts/lib/util/ajv.js +111 -0
  124. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  125. package/.agents/scripts/lib/util/paths.js +51 -0
  126. package/.agents/scripts/lib/util/sleep.js +6 -0
  127. package/.agents/scripts/lib/util/slug.js +12 -0
  128. package/.agents/scripts/lib/validation-evidence.js +19 -40
  129. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  130. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  131. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  132. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  133. package/.agents/scripts/lint-issue-body.js +2 -2
  134. package/.agents/scripts/plan-context.js +2 -7
  135. package/.agents/scripts/providers/github/auth.js +3 -3
  136. package/.agents/scripts/providers/github/errors.js +3 -1
  137. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  138. package/.agents/scripts/providers/github/issues.js +6 -2
  139. package/.agents/scripts/providers/github/mappers.js +1 -5
  140. package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
  141. package/.agents/scripts/providers/github/search-budget.js +3 -1
  142. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  143. package/.agents/scripts/single-story-init.js +18 -14
  144. package/.agents/scripts/sync-agentrc.js +5 -14
  145. package/.agents/scripts/sync-claude-agents.js +38 -150
  146. package/.agents/scripts/sync-claude-commands.js +35 -218
  147. package/.agents/scripts/update-coverage-baseline.js +1 -1
  148. package/.agents/scripts/update-crap-baseline.js +1 -1
  149. package/.agents/scripts/update-duplication-baseline.js +2 -16
  150. package/.agents/scripts/validate-skills.js +6 -10
  151. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  152. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  153. package/.agents/workflows/audit-exceptions.md +9 -0
  154. package/.agents/workflows/audit-lean.md +129 -0
  155. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  156. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  157. package/.agents/workflows/helpers/code-review.md +15 -1
  158. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  159. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  160. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +42 -0
  163. package/lib/cli/doctor-checks/codex.js +6 -5
  164. package/lib/cli/doctor-checks/llm-review.js +102 -0
  165. package/lib/cli/doctor-checks/project-access.js +20 -10
  166. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  167. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  168. package/lib/cli/doctor-checks/toolchain.js +5 -3
  169. package/lib/cli/registry.js +5 -0
  170. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  171. package/lib/migrations/index.js +6 -0
  172. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  173. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  174. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  175. package/package.json +1 -3
@@ -51,35 +51,9 @@ import { discardHeldReview } from './review-overlap.js';
51
51
 
52
52
  const progress = Logger.createProgress('single-story-close', { stderr: true });
53
53
 
54
- async function releaseLease({ storyId }, deps) {
55
- try {
56
- const outcome = await deps.releaseLease({
57
- provider: deps.provider,
58
- storyId,
59
- config: deps.config,
60
- });
61
- progress(
62
- 'LEASE',
63
- outcome.released
64
- ? `🔓 Story #${storyId} lease released.`
65
- : `🔓 Story #${storyId} lease not released (${outcome.reason}).`,
66
- );
67
- return outcome.released;
68
- } catch (err) {
69
- progress(
70
- 'LEASE',
71
- `⚠️ lease release failed (close continues): ${err?.message ?? err}`,
72
- );
73
- return false;
74
- }
75
- }
76
-
77
54
  /**
78
- * Re-take the Story lease before any gate, push or PR write: a block released
79
- * it, and init is the only other acquirer, so a re-close would otherwise run
80
- * unassigned and unguarded. No steal — a foreign holder throws init's
81
- * refusal. No configured operator handle skips the acquire (release is
82
- * best-effort for the same reason), so close never newly hard-fails on it.
55
+ * Re-affirm the Story lease before any write; normally `already-held`, since
56
+ * only the post-land tail releases it. No steal; no operator handle skips it.
83
57
  */
84
58
  async function acquireLease({ storyId }, deps) {
85
59
  const operator = resolveOperatorFromCandidates({
@@ -105,24 +79,6 @@ async function acquireLease({ storyId }, deps) {
105
79
  return lease;
106
80
  }
107
81
 
108
- /**
109
- * Release the lease best-effort before re-throwing a blocked-prone phase's
110
- * error verbatim. The lease has no TTL, so a stranded claim would refuse the
111
- * next operator who picks up the blocked Story.
112
- *
113
- * @template T
114
- * @param {() => Promise<T>} run
115
- * @returns {Promise<T>}
116
- */
117
- async function releaseLeaseOnBlock(run, ctx, deps) {
118
- try {
119
- return await run();
120
- } catch (err) {
121
- await releaseLease(ctx, deps);
122
- throw err;
123
- }
124
- }
125
-
126
82
  /**
127
83
  * Tests mock these at their module URLs and re-import only this module, so
128
84
  * they are bound here and handed to the phases rather than imported there.
@@ -161,6 +117,21 @@ function resolveCloseDeps(options, injected) {
161
117
  };
162
118
  }
163
119
 
120
+ function assertStoryId(options) {
121
+ if (!options.storyId) {
122
+ throw new Error(
123
+ 'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>] [--worker-tokens <n>] [--worker-model <model>] [--worker-effort <level>]',
124
+ );
125
+ }
126
+ }
127
+
128
+ function tagCloseError(err, { phaseTimer, phase, observedGates }) {
129
+ if (!err || typeof err !== 'object') return;
130
+ err.closePhaseDurations = phaseTimer.finish();
131
+ if (!err.closePhase) err.closePhase = phase;
132
+ if (!err.closeGates && observedGates) err.closeGates = observedGates;
133
+ }
134
+
164
135
  export async function runSingleStoryClose({
165
136
  storyId: storyIdParam,
166
137
  cwd: cwdParam,
@@ -194,11 +165,7 @@ export async function runSingleStoryClose({
194
165
  workerModelParam,
195
166
  workerEffortParam,
196
167
  });
197
- if (!options.storyId) {
198
- throw new Error(
199
- 'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>] [--worker-tokens <n>] [--worker-model <model>] [--worker-effort <level>]',
200
- );
201
- }
168
+ assertStoryId(options);
202
169
 
203
170
  // The runner keeps THROWING; it only tags the error with its phase and the
204
171
  // gates it observed (null until validation reports), and the CLI boundary
@@ -236,11 +203,7 @@ export async function runSingleStoryClose({
236
203
  deps,
237
204
  );
238
205
  } catch (err) {
239
- if (err && typeof err === 'object') {
240
- err.closePhaseDurations = phaseTimer.finish();
241
- if (!err.closePhase) err.closePhase = phase;
242
- if (!err.closeGates && observedGates) err.closeGates = observedGates;
243
- }
206
+ tagCloseError(err, { phaseTimer, phase, observedGates });
244
207
  throw err;
245
208
  }
246
209
  }
@@ -271,7 +234,6 @@ async function graphqlPreflightPhase(ctx, deps) {
271
234
  probe: deps.graphqlProbe,
272
235
  });
273
236
  if (!preflight) return null;
274
- await releaseLease(ctx, deps);
275
237
  return await preflightBlockedResult({
276
238
  storyId: ctx.storyId,
277
239
  preflight,
@@ -396,11 +358,7 @@ function landedPr(ctx) {
396
358
  }
397
359
 
398
360
  async function prePushPhase(ctx, deps) {
399
- ctx.prePush = await releaseLeaseOnBlock(
400
- () => runPrePushPhases(ctx, deps),
401
- ctx,
402
- deps,
403
- );
361
+ ctx.prePush = await runPrePushPhases(ctx, deps);
404
362
  if (!ctx.prePush.pending) return null;
405
363
  discardHeldReview(ctx.heldReview, 'validation pending', progress);
406
364
  return await finishDeferred(ctx.prePush.lockWait, {
@@ -415,11 +373,7 @@ async function prePushPhase(ctx, deps) {
415
373
  }
416
374
 
417
375
  async function openPrPhase(ctx, deps) {
418
- ctx.pr = await releaseLeaseOnBlock(
419
- () => openAndReviewPr(ctx, deps),
420
- ctx,
421
- deps,
422
- );
376
+ ctx.pr = await openAndReviewPr(ctx, deps);
423
377
  return null;
424
378
  }
425
379
 
@@ -460,22 +414,9 @@ async function armPhase(ctx, deps) {
460
414
  return null;
461
415
  }
462
416
 
463
- /** Wait-for-merge needs the arm outcome, so it is resolved here. */
464
- async function finishPhase(ctx, deps) {
417
+ function buildPrContext(ctx, deps) {
465
418
  const { options, arm } = ctx;
466
- const { waitForMerge, reason: waitForMergeReason } = resolveWaitForMerge({
467
- waitForMergeExplicit: options.waitForMergeExplicit,
468
- noWaitForMerge: options.noWaitForMerge,
469
- config: deps.config,
470
- autoMergeReason: arm.autoMergeReason,
471
- });
472
- reportOperatorMergeSkip({
473
- waitForMergeReason,
474
- autoMergeReason: arm.autoMergeReason,
475
- storyId: ctx.storyId,
476
- waitForMergeExplicit: options.waitForMergeExplicit,
477
- });
478
- const prCtx = {
419
+ return {
479
420
  storyId: ctx.storyId,
480
421
  storyBranch: ctx.storyBranch,
481
422
  baseBranch: ctx.baseBranch,
@@ -500,8 +441,32 @@ async function finishPhase(ctx, deps) {
500
441
  ctx.pr.reviewDegraded,
501
442
  ),
502
443
  };
444
+ }
445
+
446
+ function decideWaitForMerge(ctx, deps) {
447
+ const { options, arm } = ctx;
448
+ const decision = resolveWaitForMerge({
449
+ waitForMergeExplicit: options.waitForMergeExplicit,
450
+ noWaitForMerge: options.noWaitForMerge,
451
+ config: deps.config,
452
+ autoMergeReason: arm.autoMergeReason,
453
+ });
454
+ reportOperatorMergeSkip({
455
+ waitForMergeReason: decision.reason,
456
+ autoMergeReason: arm.autoMergeReason,
457
+ storyId: ctx.storyId,
458
+ waitForMergeExplicit: options.waitForMergeExplicit,
459
+ });
460
+ return decision;
461
+ }
462
+
463
+ /** Wait-for-merge needs the arm outcome, so it is resolved here. */
464
+ async function finishPhase(ctx, deps) {
465
+ const { options } = ctx;
466
+ const { waitForMerge, reason } = decideWaitForMerge(ctx, deps);
467
+ const prCtx = buildPrContext(ctx, deps);
503
468
  if (!waitForMerge) {
504
- return await finishWithoutMergeWait(prCtx, waitForMergeReason);
469
+ return await finishWithoutMergeWait(prCtx, reason);
505
470
  }
506
471
  return await finishWithMergeWait(prCtx, {
507
472
  cwd: options.cwd,
@@ -513,6 +478,7 @@ async function finishPhase(ctx, deps) {
513
478
  injectedGh: deps.gh,
514
479
  injectedNotify: deps.notify,
515
480
  runConfirmMergePhase: deps.runConfirmMergePhase,
481
+ releaseLease: deps.releaseLease,
516
482
  });
517
483
  }
518
484
 
@@ -31,6 +31,7 @@ import {
31
31
  import { getQuality } from '../../config-resolver.js';
32
32
  import { gitSync as defaultGitSync } from '../../git-utils.js';
33
33
  import { Logger as DefaultLogger } from '../../Logger.js';
34
+ import { isScorableSourceFile } from '../../source-extensions.js';
34
35
  import {
35
36
  currentBranch,
36
37
  listChangedFiles,
@@ -44,8 +45,6 @@ const KIND = 'maintainability';
44
45
  /** Matches the drift detector's maintainability default tolerance. */
45
46
  const DEFAULT_TOLERANCE = 0.5;
46
47
 
47
- const SCORABLE = /\.(?:m?[jt]sx?)$/i;
48
-
49
48
  /**
50
49
  * Skips that fire before any scoring, so `ran: false` means exactly "a guard
51
50
  * stopped this"; outcome reasons are deliberately absent.
@@ -323,7 +322,7 @@ export async function runBaselineUpwardWriteback({
323
322
  baseBranch: resolveScopeBase({ workTree, git, baseBranch }),
324
323
  storyBranch,
325
324
  git,
326
- }).filter((file) => SCORABLE.test(file));
325
+ }).filter(isScorableSourceFile);
327
326
 
328
327
  const writePath = resolveWritePath({ cwd: workTree });
329
328
  const relPath = path.relative(workTree, writePath).split(path.sep).join('/');
@@ -7,24 +7,34 @@
7
7
  * formats the changed files and commits the result instead.
8
8
  */
9
9
 
10
- import { execFileSync } from 'node:child_process';
11
-
12
10
  import { diffNameOnly } from '../../changed-files.js';
11
+ import { execFileCapture } from '../../child-exec.js';
13
12
  import { resolveFormatWriteCommand } from '../../close-validation/commands.js';
14
13
  import { Logger as DefaultLogger } from '../../Logger.js';
15
14
 
16
15
  const SCOPED_TAG = '[format-autofix-scoped]';
17
16
 
17
+ /**
18
+ * `-- <paths…>` when pathspecs are given, else nothing (whole tree).
19
+ *
20
+ * @param {string[]} [paths]
21
+ * @returns {string[]}
22
+ */
23
+ const pathspecArgs = (paths = []) => (paths.length ? ['--', ...paths] : []);
24
+
18
25
  /**
19
26
  * Paths from `git status --porcelain`. Lines are `XY <path>` and the status
20
27
  * pair's leading space is significant, so slice 3 chars rather than trim.
28
+ * With `paths`, the status walk is limited to those pathspecs.
21
29
  *
22
30
  * @param {string} cwd
23
31
  * @param {(args: string[], opts: object) => string} git
32
+ * @param {string[]} [paths] - Pathspecs to scope the status to.
24
33
  * @returns {string[]}
25
34
  */
26
- export function listDirtyPaths(cwd, git) {
27
- const out = git(['status', '--porcelain'], {
35
+ export function listDirtyPaths(cwd, git, paths) {
36
+ const scope = pathspecArgs(paths);
37
+ const out = git(['status', '--porcelain', ...scope], {
28
38
  cwd,
29
39
  encoding: 'utf8',
30
40
  stdio: ['ignore', 'pipe', 'ignore'],
@@ -74,18 +84,22 @@ export function currentBranch(cwd, git) {
74
84
  }
75
85
 
76
86
  /**
77
- * `git add -u` + commit with hooks enabled (never `--no-verify`).
87
+ * `git add -u` + commit with hooks enabled (never `--no-verify`). With
88
+ * `paths`, both the staging and the commit are limited to those pathspecs, so
89
+ * a change outside them is never swept in.
78
90
  *
79
91
  * @param {{
80
92
  * cwd: string,
81
93
  * git: (args: string[], opts: object) => string,
82
94
  * subject: string,
95
+ * paths?: string[],
83
96
  * }} opts
84
97
  * @returns {string} short HEAD SHA of the new commit
85
98
  */
86
- export function commitDirtyPaths({ cwd, git, subject }) {
87
- git(['add', '-u'], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
88
- git(['commit', '-m', subject], {
99
+ export function commitDirtyPaths({ cwd, git, subject, paths }) {
100
+ const scope = pathspecArgs(paths);
101
+ git(['add', '-u', ...scope], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
102
+ git(['commit', '-m', subject, ...scope], {
89
103
  cwd,
90
104
  stdio: ['ignore', 'pipe', 'pipe'],
91
105
  });
@@ -142,7 +156,7 @@ export function listChangedFiles({ cwd, baseBranch, storyBranch, git }) {
142
156
  * storyBranch: string,
143
157
  * config?: object,
144
158
  * logger?: object,
145
- * spawnSync?: typeof execFileSync,
159
+ * spawnSync?: Function,
146
160
  * gitSync?: (args: string[], opts: object) => string,
147
161
  * }} opts
148
162
  * @returns {{
@@ -161,7 +175,7 @@ export function runScopedFormatAutofix({
161
175
  storyBranch,
162
176
  config,
163
177
  logger = DefaultLogger,
164
- spawnSync = execFileSync,
178
+ spawnSync,
165
179
  gitSync,
166
180
  } = {}) {
167
181
  if (!cwd) throw new Error('runScopedFormatAutofix: cwd is required');
@@ -172,7 +186,12 @@ export function runScopedFormatAutofix({
172
186
 
173
187
  const workTree = worktreePath || cwd;
174
188
 
175
- const git = gitSync ?? ((args, opts) => spawnSync('git', args, opts));
189
+ // `spawnSync` is an `execFileSync`-shaped seam: it becomes the wrapper's
190
+ // `run`, so the wrapper's stdout ceiling covers the diff, status and
191
+ // formatter captures whether or not a test injects it.
192
+ const exec = (file, args, opts) =>
193
+ execFileCapture(file, args, spawnSync ? { ...opts, run: spawnSync } : opts);
194
+ const git = gitSync ?? ((args, opts) => exec('git', args, opts));
176
195
 
177
196
  const { writeCmdString, writeCmd, writeArgs } = resolveFormatterCmd({
178
197
  commands: config?.project?.commands,
@@ -191,7 +210,7 @@ export function runScopedFormatAutofix({
191
210
  return { ran: false, committed: false, reason: 'no-changed-files' };
192
211
  }
193
212
 
194
- const dirtyBefore = listDirtyPaths(workTree, git);
213
+ const dirtyBefore = listDirtyPaths(workTree, git, changed);
195
214
  if (dirtyBefore.length) {
196
215
  logger.info?.(
197
216
  `${SCOPED_TAG} skipped — working tree dirty before scoped autofix (${dirtyBefore.length} paths).`,
@@ -201,7 +220,7 @@ export function runScopedFormatAutofix({
201
220
 
202
221
  // A non-zero exit is tolerated: the downstream check gate is authoritative.
203
222
  try {
204
- spawnSync(writeCmd, [...writeArgs, ...changed], {
223
+ exec(writeCmd, [...writeArgs, ...changed], {
205
224
  cwd: workTree,
206
225
  stdio: ['ignore', 'pipe', 'pipe'],
207
226
  encoding: 'utf8',
@@ -212,7 +231,7 @@ export function runScopedFormatAutofix({
212
231
  );
213
232
  }
214
233
 
215
- const dirtyAfter = listDirtyPaths(workTree, git);
234
+ const dirtyAfter = listDirtyPaths(workTree, git, changed);
216
235
  if (!dirtyAfter.length) {
217
236
  logger.info?.(
218
237
  `${SCOPED_TAG} no format drift on ${changed.length} changed file(s).`,
@@ -230,7 +249,14 @@ export function runScopedFormatAutofix({
230
249
  }
231
250
 
232
251
  const subject = `fix(story-close): auto-apply biome format in scoped lint (story #${storyId})`;
233
- const sha = commitDirtyPaths({ cwd: workTree, git, subject });
252
+ const sha = commitDirtyPaths({
253
+ cwd: workTree,
254
+ git,
255
+ subject,
256
+ // The dirty set, not `changed`: a path the branch deleted is no pathspec
257
+ // `git add` / `git commit` can match.
258
+ paths: dirtyAfter,
259
+ });
234
260
 
235
261
  logger.warn?.(
236
262
  `${SCOPED_TAG} auto-applied biome format to ${dirtyAfter.length} path(s) on story #${storyId}: ${dirtyAfter.join(', ')}; committed as ${sha}.`,
@@ -9,8 +9,7 @@ import fs from 'node:fs';
9
9
  import path from 'node:path';
10
10
  import { fileURLToPath } from 'node:url';
11
11
 
12
- import Ajv2020 from 'ajv/dist/2020.js';
13
- import addFormats from 'ajv-formats';
12
+ import { createAjv2020 } from '../util/ajv.js';
14
13
 
15
14
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
16
15
 
@@ -57,8 +56,7 @@ function getValidator(source) {
57
56
  if (!source?.schema) return null;
58
57
  const cached = VALIDATORS.get(source);
59
58
  if (cached) return cached;
60
- const ajv = new Ajv2020({ allErrors: true, strict: false });
61
- addFormats(ajv);
59
+ const ajv = createAjv2020({ allErrors: true, strict: false });
62
60
  const validate = ajv.compile(source.schema);
63
61
  VALIDATORS.set(source, validate);
64
62
  return validate;
@@ -5,9 +5,9 @@
5
5
  */
6
6
 
7
7
  import nodeFs from 'node:fs';
8
- import path from 'node:path';
9
8
  import { storyTerminalEnvelopePath } from '../config/temp-paths.js';
10
9
  import { resolveConfig } from '../config-resolver.js';
10
+ import { writeFileAtomic } from '../util/atomic-write.js';
11
11
  import { validateTerminalEnvelope } from './story-deliver-terminal-schema.js';
12
12
 
13
13
  export { validateTerminalEnvelope };
@@ -273,23 +273,12 @@ export function persistTerminalEnvelope(
273
273
  ) {
274
274
  const storyId = envelope?.storyId;
275
275
  if (!Number.isInteger(storyId) || storyId <= 0) return null;
276
- let tmpPath = null;
277
276
  try {
278
277
  const resolved = config ?? tolerantConfig(resolveConfigImpl);
279
278
  const target = storyTerminalEnvelopePath(storyId, resolved);
280
- fsImpl.mkdirSync(path.dirname(target), { recursive: true });
281
- tmpPath = `${target}.${process.pid}.tmp`;
282
- fsImpl.writeFileSync(tmpPath, `${JSON.stringify(envelope)}\n`, 'utf8');
283
- fsImpl.renameSync(tmpPath, target);
279
+ writeFileAtomic(target, `${JSON.stringify(envelope)}\n`, { fsImpl });
284
280
  return target;
285
281
  } catch {
286
- if (tmpPath) {
287
- try {
288
- fsImpl.rmSync(tmpPath, { force: true });
289
- } catch {
290
- // Best-effort.
291
- }
292
- }
293
282
  return null;
294
283
  }
295
284
  }
@@ -25,7 +25,7 @@ import { fileURLToPath } from 'node:url';
25
25
  import { spawnStreamAsync } from '../child-exec.js';
26
26
  import { createLockEventChannel } from '../close-lock-events.js';
27
27
  import {
28
- resolveLintCommand,
28
+ resolveGateCommand,
29
29
  resolveTestGateArgv,
30
30
  } from '../close-validation/commands.js';
31
31
  import {
@@ -299,6 +299,17 @@ function describeSuiteFailure(status) {
299
299
  return `red suite (exit ${status}) — fix the failing tests, commit, re-run`;
300
300
  }
301
301
 
302
+ /**
303
+ * The lint preflight, absent when `project.commands.lint` is `null`.
304
+ *
305
+ * @param {object} config
306
+ * @returns {Array<{ key: string, cmd: string, args: string[] }>}
307
+ */
308
+ function lintPreflight(config) {
309
+ const lint = resolveGateCommand(config, 'lint');
310
+ return lint.disabled ? [] : [{ key: 'lint', cmd: lint.cmd, args: lint.args }];
311
+ }
312
+
302
313
  /**
303
314
  * Lint, quality-preview, then each ratchet whose baseline is committed.
304
315
  *
@@ -306,9 +317,6 @@ function describeSuiteFailure(status) {
306
317
  * @returns {Array<{ key: string, cmd: string, args: string[], gated?: boolean }>}
307
318
  */
308
319
  function preflightChecks(ctx) {
309
- const [lintCmd, ...lintArgs] = resolveLintCommand(ctx.config)
310
- .split(/\s+/)
311
- .filter(Boolean);
312
320
  const ratchets = RATCHETS.filter((r) =>
313
321
  fs.existsSync(path.join(ctx.cwd, r.baseline)),
314
322
  ).map((r) => ({
@@ -318,7 +326,7 @@ function preflightChecks(ctx) {
318
326
  gated: true,
319
327
  }));
320
328
  return [
321
- { key: 'lint', cmd: lintCmd, args: lintArgs },
329
+ ...lintPreflight(ctx.config),
322
330
  {
323
331
  key: 'quality-preview',
324
332
  cmd: 'node',
@@ -25,6 +25,7 @@ const INSTALL_FLAGS = Object.freeze({ installed: 'true', failed: 'false' });
25
25
  * @param {boolean} args.dryRun
26
26
  * @param {{ remoteVerified: boolean, remoteUrl?: string, detail?: string }} args.remote
27
27
  * @param {string|null} args.checklistPath
28
+ * @param {{ status: string, reason?: string }|null} [args.boardSync]
28
29
  * @returns {{ result: object, summary: object }}
29
30
  */
30
31
  export function composeStoryInitResult({
@@ -41,6 +42,7 @@ export function composeStoryInitResult({
41
42
  dryRun,
42
43
  remote,
43
44
  checklistPath,
45
+ boardSync = null,
44
46
  }) {
45
47
  const dependenciesInstalled =
46
48
  INSTALL_FLAGS[installStatus.status] ?? 'skipped';
@@ -68,6 +70,7 @@ export function composeStoryInitResult({
68
70
  // Footprint-matched write-time checklist (null when no lens matches) —
69
71
  // the same Story-scoped path a multi-Story dispatch prompt names.
70
72
  checklistPath,
73
+ boardSync,
71
74
  };
72
75
  const summary = {
73
76
  storyId,
@@ -78,6 +81,14 @@ export function composeStoryInitResult({
78
81
  remoteVerified: remote.remoteVerified,
79
82
  checklistPath,
80
83
  dryRun,
84
+ boardSync: summarizeBoardSync(boardSync),
81
85
  };
82
86
  return { result, summary };
83
87
  }
88
+
89
+ /** The status, plus its reason when the board did not move. */
90
+ function summarizeBoardSync(boardSync) {
91
+ if (!boardSync) return null;
92
+ if (!boardSync.reason) return boardSync.status;
93
+ return `${boardSync.status} (${boardSync.reason})`;
94
+ }
@@ -6,15 +6,15 @@
6
6
  *
7
7
  * Advisory only — nothing in Mandrel decides on it. Every write is best
8
8
  * effort (an fs error is swallowed and logged at debug) and atomic (a
9
- * `<file>.tmp` sibling renamed over the target), so a poller never parses
9
+ * pid-scoped tmp sibling renamed over the target), so a poller never parses
10
10
  * half a file and an unwritable temp folder changes no delivery outcome.
11
11
  */
12
12
 
13
13
  import fs from 'node:fs';
14
- import path from 'node:path';
15
14
 
16
15
  import { storyProgressPath } from '../config/temp-paths.js';
17
16
  import { Logger } from '../Logger.js';
17
+ import { writeFileAtomic } from '../util/atomic-write.js';
18
18
 
19
19
  const STORY_PROGRESS_KIND = 'story-progress';
20
20
 
@@ -43,18 +43,10 @@ export function handoffStepName(step) {
43
43
  function writeStoryProgress(file, record, deps = {}) {
44
44
  const fsImpl = deps.fsImpl ?? fs;
45
45
  const debug = deps.debug ?? ((msg) => Logger.debug(msg));
46
- const tmp = `${file}.tmp`;
47
46
  try {
48
- fsImpl.mkdirSync(path.dirname(file), { recursive: true });
49
- fsImpl.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
50
- fsImpl.renameSync(tmp, file);
47
+ writeFileAtomic(file, `${JSON.stringify(record, null, 2)}\n`, { fsImpl });
51
48
  return true;
52
49
  } catch (err) {
53
- try {
54
- fsImpl.rmSync(tmp, { force: true });
55
- } catch {
56
- // The stray tmp is harmless; the next write overwrites it.
57
- }
58
50
  debug(`[story-progress] write skipped for ${file}: ${err?.message ?? err}`);
59
51
  return false;
60
52
  }
@@ -6,6 +6,7 @@
6
6
  */
7
7
 
8
8
  import { Logger } from '../../Logger.js';
9
+ import { defaultSleep } from '../../util/sleep.js';
9
10
  import { ALL_STATES, STATE_LABELS } from './reads.js';
10
11
  import {
11
12
  postStructuredComment,
@@ -15,10 +16,8 @@ import {
15
16
 
16
17
  /** Backoff for transient `gh` failures inside the cascade transition. */
17
18
  const CASCADE_RETRY_BACKOFF_MS = [250, 500, 1000];
18
- const defaultCascadeSleep = (ms) =>
19
- new Promise((resolve) => setTimeout(resolve, ms));
20
19
  let _cascadeRetryDelays = CASCADE_RETRY_BACKOFF_MS;
21
- let _cascadeSleep = defaultCascadeSleep;
20
+ let _cascadeSleep = defaultSleep;
22
21
 
23
22
  /**
24
23
  * Test seam; call with no arguments to restore defaults.
@@ -29,8 +28,7 @@ export function __setCascadeRetryDelays(opts = {}) {
29
28
  _cascadeRetryDelays = Array.isArray(opts.delays)
30
29
  ? opts.delays
31
30
  : CASCADE_RETRY_BACKOFF_MS;
32
- _cascadeSleep =
33
- typeof opts.sleep === 'function' ? opts.sleep : defaultCascadeSleep;
31
+ _cascadeSleep = typeof opts.sleep === 'function' ? opts.sleep : defaultSleep;
34
32
  }
35
33
 
36
34
  /**