mandrel 2.89.0 → 2.91.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 +38 -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/board-backfill.js +253 -0
  14. package/.agents/scripts/check-arch-cycles.js +1 -5
  15. package/.agents/scripts/check-context-budget.js +1 -5
  16. package/.agents/scripts/check-cyclomatic.js +1 -5
  17. package/.agents/scripts/check-dead-exports.js +23 -14
  18. package/.agents/scripts/check-doc-links.js +4 -4
  19. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  20. package/.agents/scripts/coverage-capture.js +14 -6
  21. package/.agents/scripts/diagnose-friction.js +8 -10
  22. package/.agents/scripts/generate-workflows-doc.js +5 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  24. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  25. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  26. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  27. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  28. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  29. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  30. package/.agents/scripts/lib/baselines/components.js +5 -5
  31. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  32. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  33. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  34. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  36. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  37. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  38. package/.agents/scripts/lib/baselines/writer.js +4 -4
  39. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  40. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  41. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  42. package/.agents/scripts/lib/child-exec.js +4 -4
  43. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  44. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  45. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  46. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  47. package/.agents/scripts/lib/close-validation/process.js +5 -1
  48. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  49. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  50. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  51. package/.agents/scripts/lib/config/commands.js +82 -7
  52. package/.agents/scripts/lib/config/explain.js +2 -1
  53. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  54. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  55. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  56. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  57. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  58. package/.agents/scripts/lib/config/git-roots.js +120 -0
  59. package/.agents/scripts/lib/config/quality.js +46 -50
  60. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  61. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  62. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  63. package/.agents/scripts/lib/config-resolver.js +5 -9
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  66. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  67. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  68. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  69. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  70. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  71. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture.js +80 -43
  73. package/.agents/scripts/lib/coverage-utils.js +34 -16
  74. package/.agents/scripts/lib/cpu-pool.js +2 -4
  75. package/.agents/scripts/lib/crap-engine.js +19 -1
  76. package/.agents/scripts/lib/crap-utils.js +2 -1
  77. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  78. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  79. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  80. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  81. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  82. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  83. package/.agents/scripts/lib/gh-env.js +72 -0
  84. package/.agents/scripts/lib/gh-exec.js +26 -1
  85. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  86. package/.agents/scripts/lib/npm-scripts.js +1 -1
  87. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  88. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  89. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  90. package/.agents/scripts/lib/orchestration/board-access-latch.js +112 -0
  91. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  92. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  93. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  94. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  95. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  96. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  97. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  98. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  99. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  100. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  101. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  102. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  103. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  104. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  105. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  106. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  107. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  108. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  109. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  110. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  111. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  112. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  113. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  114. package/.agents/scripts/lib/orchestration/story-handoff.js +27 -6
  115. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  116. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  117. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  118. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  119. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  120. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  121. package/.agents/scripts/lib/source-extensions.js +30 -15
  122. package/.agents/scripts/lib/test-run-credit.js +1 -9
  123. package/.agents/scripts/lib/test-temp.js +22 -21
  124. package/.agents/scripts/lib/util/ajv.js +111 -0
  125. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  126. package/.agents/scripts/lib/util/paths.js +51 -0
  127. package/.agents/scripts/lib/util/sleep.js +6 -0
  128. package/.agents/scripts/lib/util/slug.js +12 -0
  129. package/.agents/scripts/lib/validation-evidence.js +19 -40
  130. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  131. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  132. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  133. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  134. package/.agents/scripts/lint-issue-body.js +2 -2
  135. package/.agents/scripts/plan-context.js +2 -7
  136. package/.agents/scripts/providers/github/auth.js +3 -3
  137. package/.agents/scripts/providers/github/board-add.js +18 -9
  138. package/.agents/scripts/providers/github/errors.js +3 -1
  139. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  140. package/.agents/scripts/providers/github/issues.js +6 -2
  141. package/.agents/scripts/providers/github/mappers.js +1 -5
  142. package/.agents/scripts/providers/github/projects-v2-graphql.js +26 -6
  143. package/.agents/scripts/providers/github/search-budget.js +3 -1
  144. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  145. package/.agents/scripts/sync-agentrc.js +5 -14
  146. package/.agents/scripts/sync-claude-agents.js +38 -150
  147. package/.agents/scripts/sync-claude-commands.js +35 -218
  148. package/.agents/scripts/update-coverage-baseline.js +1 -1
  149. package/.agents/scripts/update-crap-baseline.js +1 -1
  150. package/.agents/scripts/update-duplication-baseline.js +2 -16
  151. package/.agents/scripts/validate-skills.js +6 -10
  152. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  153. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  154. package/.agents/workflows/audit-exceptions.md +9 -0
  155. package/.agents/workflows/audit-lean.md +129 -0
  156. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  157. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  158. package/.agents/workflows/helpers/code-review.md +15 -1
  159. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  160. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +48 -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 +124 -0
  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 +11 -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
@@ -13,7 +13,7 @@ import { isIgnoredByGlobs } from '../../maintainability-utils.js';
13
13
  * scoring nothing would silently retire the dimension.
14
14
  *
15
15
  * @param {{ resolveConfigFn?: typeof resolveConfig, getQualityFn?: typeof getQuality }} [deps]
16
- * @returns {string[]} minimatch patterns; `[]` when unset or unresolvable.
16
+ * @returns {string[]} picomatch patterns; `[]` when unset or unresolvable.
17
17
  */
18
18
  export function resolveMaintainabilityIgnoreGlobs({
19
19
  resolveConfigFn = resolveConfig,
@@ -29,7 +29,7 @@ export function resolveMaintainabilityIgnoreGlobs({
29
29
 
30
30
  /**
31
31
  * Matches through `isIgnoredByGlobs`, the same rule the baseline uses; a
32
- * local `minimatch` would let the two surfaces disagree.
32
+ * local `picomatch` would let the two surfaces disagree.
33
33
  *
34
34
  * @param {string[]} files
35
35
  * @param {string[]} ignoreGlobs
@@ -9,7 +9,6 @@
9
9
  * @typedef {import('./types.js').ReviewProvider} ReviewProvider
10
10
  */
11
11
 
12
- import path from 'node:path';
13
12
  import { POOL_SERIAL_THRESHOLD, runOnPool } from '../../cpu-pool.js';
14
13
  import { gitSpawn } from '../../git-utils.js';
15
14
  import {
@@ -17,6 +16,7 @@ import {
17
16
  classifyReport,
18
17
  } from '../../maintainability-engine.js';
19
18
  import { PROJECT_ROOT } from '../../project-root.js';
19
+ import { isScorableSourceFile } from '../../source-extensions.js';
20
20
  import { transpileForReport } from '../../transpile.js';
21
21
  import {
22
22
  resolveMaintainabilityIgnoreGlobs,
@@ -28,11 +28,9 @@ const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
28
28
  import.meta.url,
29
29
  );
30
30
 
31
- /** Below this JS-file count scoring runs in-process; at or above, on the worker pool. */
31
+ /** Below this scorable-file count scoring runs in-process; at or above, on the worker pool. */
32
32
  export const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
33
33
 
34
- const JS_MAINTAINABILITY_EXTS = new Set(['.js', '.mjs', '.cjs']);
35
-
36
34
  /**
37
35
  * Read the file at `headRef`, never from disk: close runs from the main
38
36
  * checkout, where disk holds the BASE content. `null` when absent at head.
@@ -142,10 +140,6 @@ function accumulateClassified(results, classified) {
142
140
  if (mediumFinding) results.mediumFindings.push(mediumFinding);
143
141
  }
144
142
 
145
- function isJsMaintainabilityFile(relPath) {
146
- return JS_MAINTAINABILITY_EXTS.has(path.extname(relPath));
147
- }
148
-
149
143
  /**
150
144
  * Pooled at or above `serialThreshold`. An injected `reportFn` forces the
151
145
  * serial path (a closure cannot cross the worker boundary).
@@ -174,11 +168,11 @@ export async function analyzeChangedFiles(
174
168
  mediumFindings: [],
175
169
  };
176
170
 
177
- const jsFiles = changedFiles.filter(isJsMaintainabilityFile);
178
- results.jsFiles = jsFiles.length;
179
- if (jsFiles.length === 0) return results;
171
+ const scorableFiles = changedFiles.filter(isScorableSourceFile);
172
+ results.jsFiles = scorableFiles.length;
173
+ if (scorableFiles.length === 0) return results;
180
174
 
181
- const sources = jsFiles.map((relPath) =>
175
+ const sources = scorableFiles.map((relPath) =>
182
176
  headRef == null ? '' : readHeadSourceFn(relPath, headRef, gitSpawnFn),
183
177
  );
184
178
 
@@ -186,9 +180,9 @@ export async function analyzeChangedFiles(
186
180
  reportFn ?? ((source, relPath) => scoreSourceReport(source, relPath));
187
181
  const customReportFn = reportFn != null;
188
182
 
189
- if (jsFiles.length < serialThreshold || customReportFn) {
190
- for (let i = 0; i < jsFiles.length; i += 1) {
191
- const relPath = jsFiles[i];
183
+ if (scorableFiles.length < serialThreshold || customReportFn) {
184
+ for (let i = 0; i < scorableFiles.length; i += 1) {
185
+ const relPath = scorableFiles[i];
192
186
  const source = sources[i];
193
187
  if (source == null) continue;
194
188
  accumulateClassified(
@@ -204,10 +198,10 @@ export async function analyzeChangedFiles(
204
198
 
205
199
  // Send head content (not a disk path) so the worker scores what the serial path does.
206
200
  const poolItems = [];
207
- const poolIndex = []; // poolItems[k] corresponds to jsFiles[poolIndex[k]]
208
- for (let i = 0; i < jsFiles.length; i += 1) {
201
+ const poolIndex = []; // poolItems[k] corresponds to scorableFiles[poolIndex[k]]
202
+ for (let i = 0; i < scorableFiles.length; i += 1) {
209
203
  if (sources[i] == null) continue;
210
- poolItems.push({ source: sources[i], label: jsFiles[i] });
204
+ poolItems.push({ source: sources[i], label: scorableFiles[i] });
211
205
  poolIndex.push(i);
212
206
  }
213
207
  if (poolItems.length === 0) return results;
@@ -217,7 +211,7 @@ export async function analyzeChangedFiles(
217
211
  poolItems,
218
212
  );
219
213
  for (let k = 0; k < poolIndex.length; k += 1) {
220
- const relPath = jsFiles[poolIndex[k]];
214
+ const relPath = scorableFiles[poolIndex[k]];
221
215
  const poolEntry = poolResults[k];
222
216
  // A pool error or null report drops the file, as a serial throw does.
223
217
  if (!poolEntry || poolEntry.__cpuPoolError || poolEntry.report == null) {
@@ -21,7 +21,8 @@ const DEPTH_DIRECTIVES = Object.freeze({
21
21
  'Review depth: DEEP. Cover all review pillars at full thoroughness, then ' +
22
22
  'make a second adversarial pass over the diff specifically hunting for ' +
23
23
  'integration regressions and security-relevant edges before finalizing ' +
24
- 'findings.',
24
+ 'findings. Check every caller in the callers block against the new ' +
25
+ 'signature or shape.',
25
26
  });
26
27
 
27
28
  /**
@@ -30,7 +31,7 @@ const DEPTH_DIRECTIVES = Object.freeze({
30
31
  * @param {unknown} depth
31
32
  * @returns {ReviewDepth}
32
33
  */
33
- function normalizeDepth(depth) {
34
+ export function normalizeDepth(depth) {
34
35
  return depth === 'light' || depth === 'deep' ? depth : 'standard';
35
36
  }
36
37
 
@@ -18,6 +18,7 @@ import { DEFAULT_REVIEW_PROVIDERS } from '../../config/review-chain-default.js';
18
18
  import { createCodeReviewProviderForRegistry } from './code-review.js';
19
19
  import { createCodexProviderForRegistry } from './codex.js';
20
20
  import { mergeChainDegradations } from './degraded-gates.js';
21
+ import { createLlmReviewProviderForRegistry } from './llm-review.js';
21
22
  import { createNativeProviderForRegistry } from './native.js';
22
23
  import { createSecurityReviewProviderForRegistry } from './security-review.js';
23
24
  import { createUltrareviewProviderForRegistry } from './ultrareview.js';
@@ -26,6 +27,7 @@ import { createUltrareviewProviderForRegistry } from './ultrareview.js';
26
27
  const INLINE_PROVIDERS = Object.freeze({
27
28
  'code-review': createCodeReviewProviderForRegistry,
28
29
  codex: createCodexProviderForRegistry,
30
+ 'llm-review': createLlmReviewProviderForRegistry,
29
31
  native: createNativeProviderForRegistry,
30
32
  'security-review': createSecurityReviewProviderForRegistry,
31
33
  });
@@ -10,6 +10,7 @@
10
10
  */
11
11
 
12
12
  import { spawnSync } from 'node:child_process';
13
+ import { resolveAgentrcRoot } from '../../config/git-roots.js';
13
14
  import { parseProviderFindings } from './parse-findings.js';
14
15
  import { PROVIDER_SEVERITY_MAP } from './provider-severity.js';
15
16
  import { renderDepthDirective } from './review-depth.js';
@@ -118,12 +119,16 @@ export function buildSecurityReviewPrompt(input) {
118
119
  }
119
120
 
120
121
  /**
122
+ * Spawns in the reviewed checkout: the tree this process judges.
123
+ *
121
124
  * @param {ReviewInput} input
125
+ * @param {typeof spawnSync} [spawnFn]
122
126
  * @returns {{ status: number, stdout: string, stderr: string }}
123
127
  */
124
- function defaultInvokeSecurityReview(input) {
128
+ function defaultInvokeSecurityReview(input, spawnFn = spawnSync) {
125
129
  const prompt = buildSecurityReviewPrompt(input);
126
- const result = spawnSync('claude', ['--print', prompt], {
130
+ const result = spawnFn('claude', ['--print', prompt], {
131
+ cwd: resolveAgentrcRoot(),
127
132
  encoding: 'utf-8',
128
133
  shell: process.platform === 'win32',
129
134
  timeout: 10 * 60 * 1000,
@@ -155,6 +160,7 @@ export function buildUnparseableFallbackFinding() {
155
160
  * @param {{
156
161
  * probeFn?: () => boolean,
157
162
  * invokeFn?: (input: ReviewInput) => { status: number, stdout: string, stderr: string },
163
+ * spawnFn?: Function,
158
164
  * logger?: { info?: Function, warn?: Function, error?: Function },
159
165
  * }} [deps]
160
166
  * @returns {ReviewProvider}
@@ -164,7 +170,9 @@ export function createSecurityReviewProvider(deps = {}) {
164
170
  if (!probeFn()) {
165
171
  throw buildSecurityReviewUnavailableError();
166
172
  }
167
- const invokeFn = deps.invokeFn ?? defaultInvokeSecurityReview;
173
+ const invokeFn =
174
+ deps.invokeFn ??
175
+ ((input) => defaultInvokeSecurityReview(input, deps.spawnFn));
168
176
  const logger = deps.logger;
169
177
 
170
178
  return {
@@ -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 {
@@ -176,6 +176,19 @@ function headSha(ctx) {
176
176
  return gitLine(ctx.git, ctx.cwd, ['rev-parse', 'HEAD']);
177
177
  }
178
178
 
179
+ /**
180
+ * A child's env with `AP_AGENTRC_CWD` pinned to the Story worktree, layered
181
+ * last so a stale inherited value cannot win: a gate judges the branch by
182
+ * the branch's own `.agentrc.json`.
183
+ *
184
+ * @param {object} ctx
185
+ * @param {Record<string, string|undefined>} [env] defaults to `ctx.env`.
186
+ * @returns {Record<string, string|undefined>}
187
+ */
188
+ function worktreeEnv(ctx, env) {
189
+ return { ...(env ?? ctx.env), AP_AGENTRC_CWD: ctx.cwd };
190
+ }
191
+
179
192
  /**
180
193
  * Run one child with its combined output streamed live into the step's
181
194
  * evidence log (announced, and recorded in story-progress, before it spawns).
@@ -197,7 +210,7 @@ async function runLogged(ctx, logName, cmd, args, env) {
197
210
  progress: ctx.progress,
198
211
  cmd,
199
212
  args,
200
- opts: { cwd: ctx.cwd, env },
213
+ opts: { cwd: ctx.cwd, env: worktreeEnv(ctx, env) },
201
214
  file,
202
215
  tag: logName,
203
216
  });
@@ -286,6 +299,17 @@ function describeSuiteFailure(status) {
286
299
  return `red suite (exit ${status}) — fix the failing tests, commit, re-run`;
287
300
  }
288
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
+
289
313
  /**
290
314
  * Lint, quality-preview, then each ratchet whose baseline is committed.
291
315
  *
@@ -293,9 +317,6 @@ function describeSuiteFailure(status) {
293
317
  * @returns {Array<{ key: string, cmd: string, args: string[], gated?: boolean }>}
294
318
  */
295
319
  function preflightChecks(ctx) {
296
- const [lintCmd, ...lintArgs] = resolveLintCommand(ctx.config)
297
- .split(/\s+/)
298
- .filter(Boolean);
299
320
  const ratchets = RATCHETS.filter((r) =>
300
321
  fs.existsSync(path.join(ctx.cwd, r.baseline)),
301
322
  ).map((r) => ({
@@ -305,7 +326,7 @@ function preflightChecks(ctx) {
305
326
  gated: true,
306
327
  }));
307
328
  return [
308
- { key: 'lint', cmd: lintCmd, args: lintArgs },
329
+ ...lintPreflight(ctx.config),
309
330
  {
310
331
  key: 'quality-preview',
311
332
  cmd: 'node',
@@ -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
  /**
@@ -6,8 +6,14 @@
6
6
  */
7
7
 
8
8
  import { resolveTestGateArgv } from '../close-validation/commands.js';
9
+ import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
9
10
  import { getQuality, resolveConfig } from '../config-resolver.js';
10
11
  import { isCoverageFresh } from '../coverage-capture.js';
12
+ import {
13
+ captureGates,
14
+ isCaptureActive,
15
+ primaryCaptureSource,
16
+ } from '../coverage-capture-passes.js';
11
17
  import { gitSpawn } from '../git-utils.js';
12
18
  import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
13
19
  import {
@@ -24,7 +30,10 @@ export const FULL_SUITE_SHAPE_WARNING =
24
30
 
25
31
  const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
26
32
 
27
- const FULL_SUITE_SCRIPTS = new Set(['test', 'test:coverage']);
33
+ const FULL_SUITE_SCRIPTS = new Set([
34
+ 'test',
35
+ COVERAGE_CAPTURE_DEFAULTS.captureScript,
36
+ ]);
28
37
 
29
38
  /** Filter flags that scope a bare-looking `node --test`; `=value` form too. */
30
39
  const NARROWING_FLAGS = Object.freeze([
@@ -45,6 +54,30 @@ function hasNarrowingFlag(tokens) {
45
54
  );
46
55
  }
47
56
 
57
+ /**
58
+ * The credit mode, and — in capture mode — the primary artifact's freshness.
59
+ *
60
+ * @param {{ quality: object, scripts: object, worktree: string, hasNpmScriptImpl: Function, isCoverageFreshImpl: Function }} opts
61
+ */
62
+ function probeCaptureStamp({
63
+ quality,
64
+ scripts,
65
+ worktree,
66
+ hasNpmScriptImpl,
67
+ isCoverageFreshImpl,
68
+ }) {
69
+ const gates = captureGates(quality);
70
+ if (!isCaptureActive({ ...gates, scripts, hasNpmScriptImpl })) {
71
+ return { mode: 'evidence', freshness: null };
72
+ }
73
+ const freshness = isCoverageFreshImpl({
74
+ coveragePath: primaryCaptureSource(gates).coveragePath,
75
+ targetDirs: gates.crap.targetDirs,
76
+ cwd: worktree,
77
+ });
78
+ return { mode: 'capture', freshness };
79
+ }
80
+
48
81
  /**
49
82
  * Strip a trailing `(<tier>)` tag, which would otherwise make every entry
50
83
  * look scoped.
@@ -136,34 +169,25 @@ export function resolveVerifyCredit(
136
169
  warning: FULL_SUITE_SHAPE_WARNING,
137
170
  };
138
171
  const config = resolveConfigImpl({ cwd: worktree });
139
- const { crap } = getQualityImpl(config);
140
- const mode =
141
- crap?.enabled !== false &&
142
- hasNpmScriptImpl(
143
- readPackageScriptsImpl(worktree),
144
- crap?.captureScript ?? 'test:coverage',
145
- )
146
- ? 'capture'
147
- : 'evidence';
148
-
149
- let stampReason = null;
150
- if (mode === 'capture') {
151
- const freshness = isCoverageFreshImpl({
152
- coveragePath: crap.coveragePath,
153
- targetDirs: crap.targetDirs,
154
- cwd: worktree,
155
- });
156
- if (freshness?.fresh === true) {
157
- return {
158
- ...scoped,
159
- mode,
160
- credited: true,
161
- spawn: false,
162
- reason: 'capture-stamp-fresh',
163
- };
164
- }
165
- stampReason = freshness?.reason ?? 'unknown';
172
+ const { mode, freshness } = probeCaptureStamp({
173
+ quality: getQualityImpl(config),
174
+ scripts: readPackageScriptsImpl(worktree),
175
+ worktree,
176
+ hasNpmScriptImpl,
177
+ isCoverageFreshImpl,
178
+ });
179
+
180
+ if (freshness?.fresh === true) {
181
+ return {
182
+ ...scoped,
183
+ mode,
184
+ credited: true,
185
+ spawn: false,
186
+ reason: 'capture-stamp-fresh',
187
+ };
166
188
  }
189
+ const stampReason =
190
+ mode === 'capture' ? (freshness?.reason ?? 'unknown') : null;
167
191
 
168
192
  // A stale stamp is not the last word: a green `npm test` deposits `test`
169
193
  // evidence, consulted in both modes before spawning.