mandrel 2.110.0 → 2.112.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 (190) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/audit-checklists/state-machines.md +21 -0
  6. package/.agents/docs/agentrc-reference.json +23 -10
  7. package/.agents/docs/configuration.md +362 -15
  8. package/.agents/docs/execution-reference.md +11 -0
  9. package/.agents/docs/workflows.md +2 -1
  10. package/.agents/rules/ci-remediation.md +28 -4
  11. package/.agents/rules/git-conventions-reference.md +7 -0
  12. package/.agents/schemas/agentrc.schema.json +179 -13
  13. package/.agents/schemas/audit-rules.json +28 -0
  14. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  15. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  16. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  17. package/.agents/schemas/baselines/crap.schema.json +37 -10
  18. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  19. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  20. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  21. package/.agents/schemas/crap-report.schema.json +6 -5
  22. package/.agents/schemas/story-deliver-terminal.schema.json +49 -3
  23. package/.agents/schemas/story-progress.schema.json +1 -1
  24. package/.agents/schemas/validation-evidence.schema.json +2 -2
  25. package/.agents/scripts/boot-sweep.js +41 -3
  26. package/.agents/scripts/coverage-capture.js +39 -3
  27. package/.agents/scripts/coverage-ratchet.js +106 -0
  28. package/.agents/scripts/evidence-gate.js +84 -21
  29. package/.agents/scripts/file-ci-gap.js +220 -10
  30. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  31. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  32. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  33. package/.agents/scripts/lib/baseline-loader.js +4 -2
  34. package/.agents/scripts/lib/baselines/codec.js +57 -0
  35. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  36. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  37. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  38. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  39. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  40. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  41. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  42. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  43. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  44. package/.agents/scripts/lib/baselines/reader.js +36 -9
  45. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  46. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  47. package/.agents/scripts/lib/baselines/writer.js +36 -21
  48. package/.agents/scripts/lib/changed-files.js +70 -6
  49. package/.agents/scripts/lib/child-exec.js +10 -0
  50. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  51. package/.agents/scripts/lib/close-lock-events.js +8 -3
  52. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  53. package/.agents/scripts/lib/close-validation/gates.js +156 -32
  54. package/.agents/scripts/lib/close-validation/process.js +16 -7
  55. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  56. package/.agents/scripts/lib/close-validation/runner.js +160 -41
  57. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  58. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  59. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  60. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  61. package/.agents/scripts/lib/config/explain.js +5 -2
  62. package/.agents/scripts/lib/config/gates/coverage.schema.js +53 -0
  63. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  64. package/.agents/scripts/lib/config/git-roots.js +38 -4
  65. package/.agents/scripts/lib/config/handoff.js +24 -0
  66. package/.agents/scripts/lib/config/quality.js +28 -12
  67. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  68. package/.agents/scripts/lib/config-resolver.js +22 -2
  69. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  70. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  71. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  73. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  74. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  75. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  76. package/.agents/scripts/lib/coverage-capture.js +31 -0
  77. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  78. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  79. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  80. package/.agents/scripts/lib/crap-engine.js +3 -3
  81. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  82. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  83. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  84. package/.agents/scripts/lib/failure-rows.js +121 -0
  85. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  86. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  87. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  88. package/.agents/scripts/lib/gh-env.js +3 -6
  89. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  90. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  91. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  92. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  93. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  94. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  95. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  96. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  97. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  102. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  103. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  104. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
  105. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  106. package/.agents/scripts/lib/orchestration/handoff-gates.js +217 -44
  107. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  108. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  109. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
  110. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
  111. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
  112. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  113. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  114. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  115. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  116. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  117. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  118. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  119. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  120. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  121. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  122. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  123. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  124. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  125. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  127. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +17 -2
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +13 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +17 -2
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +42 -20
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -1
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +51 -15
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  140. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  141. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  142. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  143. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  144. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  145. package/.agents/scripts/lib/orchestration/single-story-close/result.js +43 -13
  146. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  147. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -2
  148. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  149. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  150. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  151. package/.agents/scripts/lib/orchestration/story-handoff.js +789 -196
  152. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  153. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  154. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  155. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  156. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  157. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  158. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  159. package/.agents/scripts/lib/suite-admission.js +20 -8
  160. package/.agents/scripts/lib/suite-sizing.js +146 -0
  161. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  162. package/.agents/scripts/merge-baseline.js +14 -3
  163. package/.agents/scripts/providers/github/comments.js +19 -3
  164. package/.agents/scripts/providers/github.js +1 -0
  165. package/.agents/scripts/review-dispositions-report.js +1 -1
  166. package/.agents/scripts/role-scope-guard.js +267 -0
  167. package/.agents/scripts/single-story-close.js +4 -4
  168. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  169. package/.agents/scripts/single-story-init.js +24 -4
  170. package/.agents/scripts/story-handoff.js +3 -3
  171. package/.agents/scripts/story-outcomes-report.js +231 -0
  172. package/.agents/scripts/story-review-compute.js +9 -5
  173. package/.agents/scripts/update-coverage-baseline.js +12 -2
  174. package/.agents/scripts/update-crap-baseline.js +9 -1
  175. package/.agents/workflows/audit-state-machines.md +213 -0
  176. package/.agents/workflows/helpers/code-review.md +63 -9
  177. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  178. package/.agents/workflows/helpers/deliver-reference.md +236 -63
  179. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  180. package/.agents/workflows/helpers/deliver-story.md +7 -2
  181. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  182. package/.agents/workflows/helpers/plan-reference.md +10 -2
  183. package/docs/CHANGELOG.md +56 -0
  184. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  185. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  186. package/lib/cli/doctor-checks/llm-review.js +2 -11
  187. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  188. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  189. package/lib/cli/registry.js +5 -0
  190. package/package.json +1 -1
@@ -9,11 +9,19 @@
9
9
  */
10
10
 
11
11
  import path from 'node:path';
12
+ import {
13
+ aheadStampOf,
14
+ classifyScoringSemantics,
15
+ SCORING_SEMANTICS,
16
+ } from '../../baselines/kinds/_crap-read.js';
12
17
  import {
13
18
  compareCrap,
14
19
  filterRowsByFileScope,
15
20
  } from '../../baselines/kinds/crap.js';
16
- import { loadFile as loadBaselineFile } from '../../baselines/reader.js';
21
+ import {
22
+ loadFile as loadBaselineFile,
23
+ peekFile,
24
+ } from '../../baselines/reader.js';
17
25
  import { diffNameOnly } from '../../changed-files.js';
18
26
  import { COVERAGE_CAPTURE_DEFAULTS } from '../../config/gates/coverage.schema.js';
19
27
  import { loadCoverage } from '../../coverage-utils.js';
@@ -43,7 +51,7 @@ function normaliseSkipReason(reason) {
43
51
  * `[]` when absent or unreadable.
44
52
  *
45
53
  * @param {string} baselinePath
46
- * @returns {Array<{file: string, method: string, startLine: number, crap: number}>}
54
+ * @returns {Array<{file: string, method: string, crap: number}>}
47
55
  */
48
56
  function loadCrapBaselineRows(baselinePath) {
49
57
  let envelope;
@@ -56,7 +64,6 @@ function loadCrapBaselineRows(baselinePath) {
56
64
  return rows.map((row) => ({
57
65
  file: row.path,
58
66
  method: row.method,
59
- startLine: row.startLine,
60
67
  crap: row.crap,
61
68
  }));
62
69
  }
@@ -139,6 +146,32 @@ function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
139
146
  }
140
147
  }
141
148
 
149
+ /**
150
+ * Rows scored under other semantics are not comparable. A missing or
151
+ * unreadable file is no mismatch; it falls through to `no-baseline`.
152
+ */
153
+ function semanticsMismatch(raw) {
154
+ if (raw === null || typeof raw !== 'object') return null;
155
+ const ahead = aheadStampOf(raw);
156
+ if (ahead) return { reason: 'semantics-ahead', detail: ahead.message };
157
+ if (classifyScoringSemantics(raw.scoringSemantics) !== 'behind') return null;
158
+ return { reason: 'semantics-behind', detail: behindDetail(raw) };
159
+ }
160
+
161
+ /** Invalid inputs, then a semantics mismatch, as a skip; else null. */
162
+ function inputsSkip(inputs, peekBaseline) {
163
+ const validation = validateProjectionInputs(inputs);
164
+ if (!validation.ok) {
165
+ return { reason: normaliseSkipReason(validation.reason) };
166
+ }
167
+ return semanticsMismatch(peekBaseline(inputs.baselinePath));
168
+ }
169
+
170
+ /** The stamp pair a behind baseline reports. */
171
+ function behindDetail(raw) {
172
+ return `baseline=${raw.scoringSemantics ?? '(unstamped)'} running=${SCORING_SEMANTICS}`;
173
+ }
174
+
142
175
  /**
143
176
  * Breaches are vs the baseline row, or `newMethodCeiling` for new methods.
144
177
  * Baseline rows are narrowed to changed files so untouched rows do not read
@@ -153,6 +186,7 @@ function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
153
186
  * tolerance?: number,
154
187
  * git?: { gitSpawn: typeof defaultGitSpawn },
155
188
  * loadBaseline?: (path: string) => Array<object>,
189
+ * peekBaseline?: (path: string) => unknown,
156
190
  * scoreFiles?: (files: string[]) => Promise<Array<object>|null>|Array<object>|null,
157
191
  * }} opts
158
192
  * @returns {Promise<{
@@ -171,6 +205,7 @@ export async function projectCrapBreaches({
171
205
  tolerance = DEFAULT_CRAP_TOLERANCE,
172
206
  git = { gitSpawn: defaultGitSpawn },
173
207
  loadBaseline = loadCrapBaselineRows,
208
+ peekBaseline = peekFile,
174
209
  scoreFiles,
175
210
  } = {}) {
176
211
  const skip = (reason, detail) => ({
@@ -180,13 +215,11 @@ export async function projectCrapBreaches({
180
215
  ...(detail === undefined ? {} : { detail }),
181
216
  });
182
217
 
183
- const validation = validateProjectionInputs({
184
- cwd,
185
- baseBranch,
186
- storyBranch,
187
- baselinePath,
188
- });
189
- if (!validation.ok) return skip(normaliseSkipReason(validation.reason));
218
+ const early = inputsSkip(
219
+ { cwd, baseBranch, storyBranch, baselinePath },
220
+ peekBaseline,
221
+ );
222
+ if (early) return skip(early.reason, early.detail);
190
223
 
191
224
  const baselineRows = loadBaseline(baselinePath);
192
225
  if (!Array.isArray(baselineRows) || baselineRows.length === 0) {
@@ -4,7 +4,11 @@
4
4
  */
5
5
 
6
6
  import { getQuality } from '../config/quality.js';
7
- import { COVERAGE_TIMEOUT_EXIT_CODE } from '../coverage-capture.js';
7
+ import {
8
+ COVERAGE_HOST_RESOURCES_EXIT_CODE,
9
+ COVERAGE_OVER_BUDGET_EXIT_CODE,
10
+ COVERAGE_TIMEOUT_EXIT_CODE,
11
+ } from '../coverage-capture.js';
8
12
  import {
9
13
  fullSuiteLockPolicy,
10
14
  LOCK_WAIT_EXPIRED_EXIT_CODE,
@@ -16,11 +20,19 @@ import {
16
20
  treeFingerprint as defaultTreeFingerprint,
17
21
  hashCommandConfig,
18
22
  } from '../validation-evidence.js';
23
+ import { presetCiDeferral } from './ci-deferral.js';
19
24
  import {
20
25
  isFormatterEligible,
21
26
  listChangedFilesForFormatGate,
22
27
  } from './commands.js';
23
- import { DEFAULT_GATES, GATE_TIMEOUT_HINT, partitionGates } from './gates.js';
28
+ import {
29
+ COVERAGE_DEFERRED_SKIP_REASON,
30
+ DEFAULT_GATES,
31
+ GATE_TIMEOUT_HINT,
32
+ OVER_BUDGET_BLOCK_HINT,
33
+ partitionGates,
34
+ withFailureRows,
35
+ } from './gates.js';
24
36
  import { defaultGateRunner } from './process.js';
25
37
  import { runProjectionAdvisories as defaultRunProjections } from './projections/advisories.js';
26
38
  import { defaultGetHeadSha } from './projections/head-sha.js';
@@ -30,15 +42,16 @@ import { defaultGetHeadSha } from './projections/head-sha.js';
30
42
  /**
31
43
  * Classify a non-zero gate exit and log it as what it is: `75` is an expired
32
44
  * full-suite lock wait (nothing ran), `124` a killed suite (no verdict), and
33
- * anything else a real failure with the gate's own hint. Returns the
45
+ * `76` an over-budget capture the policy blocks (a deferring gate never gets
46
+ * here), `77` a suite gate that lost workers to host memory, and anything else a real failure with the gate's own hint. Returns the
34
47
  * `failed[]` entry, carrying `outcome` so callers never re-derive it; its
35
48
  * `gate.hint` is the one that fits the outcome (none when deferred), so a
36
49
  * caller replaying it never prints the failing-tests hint for a non-failure.
37
50
  *
38
- * @param {{ gate: Gate, status: number, cwd: string, log: (m: string) => void }} args
39
- * @returns {{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'failed' }}
51
+ * @param {{ gate: Gate, status: number, cwd: string, log: (m: string) => void, failureRows?: string[] }} args
52
+ * @returns {{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'over-budget'|'host-resources'|'failed' }}
40
53
  */
41
- function reportGateExit({ gate, status, cwd, log }) {
54
+ function reportGateExit({ gate, status, cwd, log, failureRows }) {
42
55
  if (status === LOCK_WAIT_EXPIRED_EXIT_CODE) {
43
56
  log(
44
57
  `[close-validation] ⏸ ${gate.name} deferred (exit ${status}) — the full-suite lock wait expired, so nothing ran in ${cwd}`,
@@ -46,21 +59,12 @@ function reportGateExit({ gate, status, cwd, log }) {
46
59
  const { hint: _failureHint, ...deferredGate } = gate;
47
60
  return { gate: deferredGate, status, cwd, outcome: 'deferred' };
48
61
  }
49
- if (status === COVERAGE_TIMEOUT_EXIT_CODE) {
50
- log(
51
- `[close-validation] ⏱ ${gate.name} timed out (exit ${status}) in ${cwd}`,
52
- );
53
- log(`[close-validation] hint: ${GATE_TIMEOUT_HINT}`);
54
- return {
55
- gate: { ...gate, hint: GATE_TIMEOUT_HINT },
56
- status,
57
- cwd,
58
- outcome: 'timeout',
59
- };
60
- }
62
+ const hinted = hintedExit(gate, status);
63
+ if (hinted) return reportHintedExit({ gate, status, cwd, log, ...hinted });
61
64
  log(`[close-validation] ✖ ${gate.name} failed (exit ${status}) in ${cwd}`);
62
- if (gate.hint) log(`[close-validation] hint: ${gate.hint}`);
63
- return { gate, status, cwd, outcome: 'failed' };
65
+ const failedGate = withFailureRows(gate, failureRows);
66
+ if (failedGate.hint) log(`[close-validation] hint: ${failedGate.hint}`);
67
+ return { gate: failedGate, status, cwd, outcome: 'failed' };
64
68
  }
65
69
 
66
70
  export function applyChangedFileScope({ gate, spawnCwd, log }) {
@@ -138,8 +142,12 @@ export function applyChangedFileScope({ gate, spawnCwd, log }) {
138
142
  * shouldSkip?: typeof defaultShouldSkip,
139
143
  * }} opts An expired full-suite lock wait spawns nothing (here or in any gate
140
144
  * child) and reports `LOCK_WAIT_EXPIRED_EXIT_CODE`.
141
- * @returns {{ ok: boolean, failed: Array<{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'failed' }>, skipped: Array<{ gate: Gate, reason: string }> }}
142
- * `outcome` classifies the exit: `deferred` (75), `timeout` (124), else `failed`.
145
+ * @returns {{ ok: boolean, failed: Array<{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'over-budget'|'host-resources'|'failed' }>, skipped: Array<{ gate: Gate, reason: string }>, deferred: Array<{ gate: Gate, status: number|null, reason: 'over-budget'|'suite-of-record-ci' }> }}
146
+ * `outcome` classifies the exit: `deferred` (75), `timeout` (124),
147
+ * `over-budget` (76 under `block`), `host-resources` (77 from a suite gate),
148
+ * else `failed`. `deferred[]` holds a
149
+ * `deferOnOverBudget` gate that exited 76, or a `suiteOfRecordCi` capture
150
+ * never spawned: not a failure, no evidence.
143
151
  */
144
152
  export async function runCloseValidation({
145
153
  cwd,
@@ -164,6 +172,7 @@ export async function runCloseValidation({
164
172
  shouldSkip = defaultShouldSkip,
165
173
  } = {}) {
166
174
  const failed = [];
175
+ const deferred = [];
167
176
  const lockOpts = fullSuiteLockOptions({ config, lockEvents });
168
177
  const skipped = [];
169
178
  const evidenceActive = useEvidence && storyId != null && standalone;
@@ -253,8 +262,9 @@ export async function runCloseValidation({
253
262
  ...(gate.tolerateNoFilesProcessed
254
263
  ? { tolerateNoFilesProcessed: true }
255
264
  : {}),
265
+ retainFailureRows: gate.retainFailureRows,
256
266
  });
257
- return { status: result?.status ?? 1 };
267
+ return { status: result?.status ?? 1, failureRows: result?.failureRows };
258
268
  };
259
269
 
260
270
  const { independent, serial } = partitionGates(gates);
@@ -309,7 +319,7 @@ export async function runCloseValidation({
309
319
  }
310
320
  if (result.status !== 0) {
311
321
  if (!firstIndepFailure) {
312
- firstIndepFailure = { gate, status: result.status };
322
+ firstIndepFailure = { ...result, gate };
313
323
  ac.abort();
314
324
  }
315
325
  return;
@@ -325,9 +335,8 @@ export async function runCloseValidation({
325
335
  await Promise.all(indepTasks);
326
336
 
327
337
  if (firstIndepFailure) {
328
- const { gate, status } = firstIndepFailure;
329
- failed.push(reportGateExit({ gate, status, cwd: spawnCwd, log }));
330
- return { ok: false, failed, skipped };
338
+ failed.push(reportGateExit({ ...firstIndepFailure, cwd: spawnCwd, log }));
339
+ return { ok: false, failed, skipped, deferred };
331
340
  }
332
341
 
333
342
  await runSerialGates(serial, {
@@ -335,6 +344,7 @@ export async function runCloseValidation({
335
344
  log,
336
345
  failed,
337
346
  skipped,
347
+ deferred,
338
348
  evidenceActive,
339
349
  evidenceClock,
340
350
  evidenceVerdict,
@@ -353,7 +363,7 @@ export async function runCloseValidation({
353
363
  });
354
364
  }
355
365
 
356
- return { ok: failed.length === 0, failed, skipped };
366
+ return { ok: failed.length === 0, failed, skipped, deferred };
357
367
  }
358
368
 
359
369
  /** The gate's `evidenceIdentity` argv hash, else its spawned argv's. */
@@ -428,6 +438,7 @@ async function runSerialGates(
428
438
  log,
429
439
  failed,
430
440
  skipped,
441
+ deferred,
431
442
  evidenceActive,
432
443
  evidenceClock,
433
444
  evidenceVerdict,
@@ -435,13 +446,18 @@ async function runSerialGates(
435
446
  dispatchGate,
436
447
  },
437
448
  ) {
438
- const failGate = (gate, status) => {
439
- failed.push(reportGateExit({ gate, status, cwd: spawnCwd, log }));
449
+ const failGate = (gate, status, failureRows) => {
450
+ failed.push(
451
+ reportGateExit({ gate, status, cwd: spawnCwd, log, failureRows }),
452
+ );
440
453
  };
441
454
  for (const gate of serial) {
455
+ const preset = presetCiDeferral(gate, { deferred, failed, log, spawnCwd });
456
+ if (preset === 'stop') return;
457
+ if (preset) continue;
442
458
  let execution;
443
459
  try {
444
- execution = applyChangedFileScope({ gate, spawnCwd, log });
460
+ execution = resolveSerialExecution({ gate, spawnCwd, log, deferred });
445
461
  } catch (err) {
446
462
  log(
447
463
  `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
@@ -473,19 +489,122 @@ async function runSerialGates(
473
489
  undefined,
474
490
  configHash,
475
491
  );
476
- if (result.status !== 0) {
477
- failGate(gate, result.status);
478
- return;
479
- }
480
- log(`[close-validation] ✓ ${gate.name}`);
481
- recordIfActive(
482
- gate,
483
- configHash,
484
- evidenceActive ? evidenceClock() - startedAt : 0,
485
- );
492
+ const recordPass = () =>
493
+ recordIfActive(
494
+ gate,
495
+ configHash,
496
+ evidenceActive ? evidenceClock() - startedAt : 0,
497
+ );
498
+ const settle = { deferred, log, spawnCwd, failGate, recordPass };
499
+ if (settleSerialResult(gate, result, settle)) return;
486
500
  }
487
501
  }
488
502
 
503
+ /** @param {Gate} gate @param {number} status */
504
+ function isDeferredOverBudget(gate, status) {
505
+ return status === COVERAGE_OVER_BUDGET_EXIT_CODE && gate.deferOnOverBudget;
506
+ }
507
+
508
+ /** A suite gate's exit 76 the policy blocks. @param {Gate} gate @param {number} status */
509
+ function isBlockedOverBudget(gate, status) {
510
+ return (
511
+ status === COVERAGE_OVER_BUDGET_EXIT_CODE && SUITE_GATES.has(gate.name)
512
+ );
513
+ }
514
+
515
+ /** Replaces a suite gate's own hint on exit 77: lost workers, no failing test. */
516
+ const GATE_HOST_RESOURCES_HINT =
517
+ 'The suite lost workers to host memory (exit 77) and no test failed — do not re-run it unchanged on this host. Use fewer workers or a larger host, or — when CI runs the suite with a coverage floor — have the capture script declare the slice over budget (exit 76) under `delivery.quality.gates.coverage.onOverBudget: "defer-to-ci"`.';
518
+
519
+ /** The gates that run the suite, the only ones whose 77 means lost workers. */
520
+ const SUITE_GATES = new Set(['test', 'coverage-capture']);
521
+
522
+ /**
523
+ * A non-failure exit that carries its own hint in place of the gate's: a
524
+ * killed suite (124), a suite that lost workers to host memory (77), or a
525
+ * suite over budget the policy blocks (76).
526
+ *
527
+ * @param {Gate} gate @param {number} status
528
+ * @returns {{ outcome: 'timeout'|'host-resources'|'over-budget', hint: string, line: string }|null}
529
+ */
530
+ function hintedExit(gate, status) {
531
+ if (status === COVERAGE_TIMEOUT_EXIT_CODE) {
532
+ const line = `⏱ ${gate.name} timed out (exit ${status})`;
533
+ return { outcome: 'timeout', hint: GATE_TIMEOUT_HINT, line };
534
+ }
535
+ return isBlockedOverBudget(gate, status)
536
+ ? overBudgetExit(gate, status)
537
+ : hostResourcesExit(gate, status);
538
+ }
539
+
540
+ /** @param {Gate} gate @param {number} status */
541
+ function overBudgetExit(gate, status) {
542
+ const line = `✖ ${gate.name} over budget (exit ${status}) — no tests ran`;
543
+ return { outcome: 'over-budget', hint: OVER_BUDGET_BLOCK_HINT, line };
544
+ }
545
+
546
+ /** A suite gate's 77; any other gate's 77 is an ordinary failure. @param {Gate} gate @param {number} status */
547
+ function hostResourcesExit(gate, status) {
548
+ if (status !== COVERAGE_HOST_RESOURCES_EXIT_CODE) return null;
549
+ if (!SUITE_GATES.has(gate.name)) return null;
550
+ const line = `⛔ ${gate.name} lost workers to host memory (exit ${status}) — no test failed`;
551
+ return { outcome: 'host-resources', hint: GATE_HOST_RESOURCES_HINT, line };
552
+ }
553
+
554
+ function reportHintedExit({ gate, status, cwd, log, outcome, hint, line }) {
555
+ log(`[close-validation] ${line} in ${cwd}`);
556
+ log(`[close-validation] hint: ${hint}`);
557
+ return { gate: { ...gate, hint }, status, cwd, outcome };
558
+ }
559
+
560
+ /**
561
+ * The gate's execution: a skip once a capture deferred and the gate reads
562
+ * its artifact, else its changed-file scope.
563
+ */
564
+ function resolveSerialExecution({ gate, spawnCwd, log, deferred }) {
565
+ if (deferred.length === 0 || !gate.readsCoverageArtifact) {
566
+ return applyChangedFileScope({ gate, spawnCwd, log });
567
+ }
568
+ log(
569
+ `[close-validation] ⏭ ${gate.name} skipped (${COVERAGE_DEFERRED_SKIP_REASON})`,
570
+ );
571
+ return { gate, skip: true, skipReason: COVERAGE_DEFERRED_SKIP_REASON };
572
+ }
573
+
574
+ /**
575
+ * Settle a dispatched serial gate: a deferral or a pass continues (a pass is
576
+ * logged and earns evidence), any other non-zero exit fails the chain.
577
+ *
578
+ * @returns {boolean} `true` when the chain must stop.
579
+ */
580
+ function settleSerialResult(gate, result, ctx) {
581
+ const { deferred, log, spawnCwd, failGate, recordPass } = ctx;
582
+ if (deferOverBudget(gate, result.status, { deferred, log, spawnCwd })) {
583
+ return false;
584
+ }
585
+ if (result.status !== 0) {
586
+ failGate(gate, result.status, result.failureRows);
587
+ return true;
588
+ }
589
+ log(`[close-validation] ✓ ${gate.name}`);
590
+ recordPass();
591
+ return false;
592
+ }
593
+
594
+ /**
595
+ * Record a flagged capture's exit 76 as deferred to CI.
596
+ *
597
+ * @returns {boolean} `true` when the exit was a deferral.
598
+ */
599
+ function deferOverBudget(gate, status, { deferred, log, spawnCwd }) {
600
+ if (!isDeferredOverBudget(gate, status)) return false;
601
+ log(
602
+ `[close-validation] ⏭ ${gate.name} deferred to CI (exit ${status}, onOverBudget: defer-to-ci) — no suite ran in ${spawnCwd}`,
603
+ );
604
+ deferred.push({ gate, status, reason: 'over-budget' });
605
+ return true;
606
+ }
607
+
489
608
  /**
490
609
  * No-op without a branch pair; a throw is logged, never propagated.
491
610
  *
@@ -0,0 +1,144 @@
1
+ /**
2
+ * The skip-branch `test` run: when coverage-capture takes its incremental
3
+ * skip, handoff and close run `project.commands.testChanged` keyed on the
4
+ * `origin/<baseBranch>` merge-base instead of the full suite, credited under
5
+ * close's full-suite `test` identity as `scope: delta`.
6
+ */
7
+
8
+ import { gitSpawn } from '../git-utils.js';
9
+ import { hashCommandConfig } from '../validation-evidence.js';
10
+ import { resolveTestGateArgv } from './commands.js';
11
+ import {
12
+ NO_TEST_CHANGED,
13
+ resolveTestChangedCommand,
14
+ substituteChangedSince,
15
+ } from './test-delta.js';
16
+
17
+ const HEX_SHA = /^[0-9a-f]{7,64}$/i;
18
+
19
+ /** The merge-base sha, or `null` when git fails or prints nothing. */
20
+ function readMergeBase(gitSpawnImpl, cwd, baseBranch) {
21
+ try {
22
+ const res = gitSpawnImpl(cwd, 'merge-base', `origin/${baseBranch}`, 'HEAD');
23
+ return res?.status === 0 ? String(res.stdout ?? '').trim() || null : null;
24
+ } catch {
25
+ return null;
26
+ }
27
+ }
28
+
29
+ /**
30
+ * The scope both handoff and close read: `testChanged` and the merge-base it
31
+ * is keyed on, or the reason the full suite runs instead.
32
+ *
33
+ * @returns {{ testChanged: object, since: string } | { fallback: string }}
34
+ */
35
+ function resolveSkipBranchScope({
36
+ config,
37
+ cwd,
38
+ baseBranch,
39
+ gitSpawnImpl = gitSpawn,
40
+ }) {
41
+ const testChanged = resolveTestChangedCommand(config);
42
+ if (testChanged.disabled) return { fallback: NO_TEST_CHANGED };
43
+ const since = readMergeBase(gitSpawnImpl, cwd, baseBranch);
44
+ return since ? { testChanged, since } : { fallback: 'merge-base unreadable' };
45
+ }
46
+
47
+ /** Close's skip-branch `test` gate. */
48
+ function buildSkipBranchTestGate({ config, testChanged, since }) {
49
+ const short = since.slice(0, 12);
50
+ return {
51
+ name: 'test',
52
+ label: `test (testChanged since ${short})`,
53
+ ...substituteChangedSince(testChanged, since),
54
+ fullSuiteLock: true,
55
+ evidenceIdentity: resolveTestGateArgv(config),
56
+ evidenceNote: { scope: 'delta', since },
57
+ hint: `\`${testChanged.raw}\` (\`project.commands.testChanged\`, the tests affected since ${short}) exited non-zero. Fix the failing tests, commit, and re-run close.`,
58
+ };
59
+ }
60
+
61
+ /**
62
+ * Close's `test` gate: the scoped run when a skip-branch scope resolved,
63
+ * else the plain full suite (`project.commands.test`).
64
+ */
65
+ export function closeTestGate(config, scope) {
66
+ return scope?.since
67
+ ? buildSkipBranchTestGate({ config, ...scope })
68
+ : { name: 'test', ...resolveTestGateArgv(config), fullSuiteLock: true };
69
+ }
70
+
71
+ const SKIP_PREFIX =
72
+ '[close-validation] coverage-capture will take the incremental skip (no changed file under the CRAP target dirs) — registering';
73
+
74
+ /** Close's one log line naming the `test` shape the skip branch registers. */
75
+ function describeCloseScope(scope) {
76
+ return scope.since
77
+ ? `${SKIP_PREFIX} the \`test\` gate as \`project.commands.testChanged\` since ${scope.since.slice(0, 12)}, credited as the full suite.`
78
+ : `${SKIP_PREFIX} the plain \`test\` gate (${scope.fallback}) so this close still runs the suite.`;
79
+ }
80
+
81
+ /** On the skip branch, close's scope (logged); elsewhere `null`. */
82
+ export function closeTestScope({ skipBranch, log, gitSpawnImpl, ...where }) {
83
+ if (!skipBranch) return null;
84
+ const scope = resolveSkipBranchScope({
85
+ ...where,
86
+ baseBranch: where.baseBranch || 'main',
87
+ ...(gitSpawnImpl ? { gitSpawnImpl } : {}),
88
+ });
89
+ log?.(describeCloseScope(scope));
90
+ return scope;
91
+ }
92
+
93
+ /**
94
+ * The handoff's `test` deposit tail for evidence-gate and its step label: the
95
+ * scoped run, or close's full `test` argv naming why.
96
+ *
97
+ * @returns {{ argv: string[], label: string, fallback?: string }}
98
+ */
99
+ export function skipBranchDeposit({ config, cwd, baseBranch, gitSpawnImpl }) {
100
+ const scope = resolveSkipBranchScope({
101
+ config,
102
+ cwd,
103
+ baseBranch,
104
+ gitSpawnImpl,
105
+ });
106
+ if (scope.fallback) {
107
+ const { cmd, args } = resolveTestGateArgv(config);
108
+ return {
109
+ argv: ['--', cmd, ...args],
110
+ label: `test (full suite: ${scope.fallback})`,
111
+ fallback: scope.fallback,
112
+ };
113
+ }
114
+ const { cmd, args } = scope.testChanged;
115
+ return {
116
+ argv: ['--changed-since', scope.since, '--', cmd, ...args],
117
+ label: `test (testChanged since ${scope.since.slice(0, 12)})`,
118
+ };
119
+ }
120
+
121
+ /** evidence-gate's `--changed-since` refusal, or `null` when it may run. */
122
+ export function changedSinceError(gate, changedSince) {
123
+ if (changedSince === null || changedSince === undefined) return null;
124
+ if (gate !== 'test') return '--changed-since is valid only with --gate test';
125
+ return HEX_SHA.test(String(changedSince))
126
+ ? null
127
+ : `--changed-since must be a hex commit sha, got "${changedSince}"`;
128
+ }
129
+
130
+ /**
131
+ * evidence-gate's scoped run: the token substituted, the sha in the env, and
132
+ * the pass credited under close's full-suite `test` identity.
133
+ */
134
+ export function scopedEvidenceRun({ cmd, args, since, config, cwd }) {
135
+ const run = substituteChangedSince({ cmd, args }, since);
136
+ return {
137
+ cmd: run.cmd,
138
+ cmdArgs: run.args,
139
+ env: run.env,
140
+ note: { scope: 'delta', since },
141
+ // Hashed exactly as close's runner hashes the `test` gate it spends this on.
142
+ configHash: hashCommandConfig({ ...resolveTestGateArgv(config), cwd }),
143
+ };
144
+ }
@@ -15,7 +15,7 @@ import { resolveTestGateArgv } from './commands.js';
15
15
  *
16
16
  * @param {object|null|undefined} config
17
17
  */
18
- function resolveTestChangedCommand(config) {
18
+ export function resolveTestChangedCommand(config) {
19
19
  const raw = config?.project?.commands?.testChanged?.trim() || null;
20
20
  const [cmd, ...args] = raw ? raw.split(/\s+/) : [];
21
21
  return { cmd, args, raw, disabled: raw === null };
@@ -23,15 +23,29 @@ function resolveTestChangedCommand(config) {
23
23
 
24
24
  const CHANGED_SINCE_TOKEN = '$MANDREL_CHANGED_SINCE';
25
25
 
26
- /** `testChanged` keyed on `since`, credited as the full suite; no shell runs it, so the token is substituted here. */
26
+ /**
27
+ * `testChanged` keyed on `since`: no shell runs it, so the token is
28
+ * substituted here and the sha is also handed over in the env.
29
+ *
30
+ * @param {{ cmd: string, args: string[] }} testChanged @param {string} since
31
+ */
32
+ export function substituteChangedSince({ cmd, args }, since) {
33
+ return {
34
+ cmd,
35
+ args: args.map((a) => (a === CHANGED_SINCE_TOKEN ? since : a)),
36
+ env: { MANDREL_CHANGED_SINCE: since },
37
+ };
38
+ }
39
+
40
+ export const NO_TEST_CHANGED = 'no `project.commands.testChanged`';
41
+
42
+ /** `testChanged` keyed on `since`, credited as the full suite. */
27
43
  function buildTestDeltaGate({ config, testChanged, since, incoming }) {
28
44
  const label = `test (delta since ${since.slice(0, 12)}, ${incoming} incoming path(s))`;
29
45
  return {
30
46
  name: 'test',
31
47
  label,
32
- cmd: testChanged.cmd,
33
- args: testChanged.args.map((a) => (a === CHANGED_SINCE_TOKEN ? since : a)),
34
- env: { MANDREL_CHANGED_SINCE: since },
48
+ ...substituteChangedSince(testChanged, since),
35
49
  fullSuiteLock: true,
36
50
  evidenceIdentity: resolveTestGateArgv(config),
37
51
  evidenceNote: { scope: 'delta', since },
@@ -48,7 +62,7 @@ function testDeltaIneligibility({
48
62
  storyFiles,
49
63
  config,
50
64
  }) {
51
- if (testChanged.disabled) return 'no `project.commands.testChanged`';
65
+ if (testChanged.disabled) return NO_TEST_CHANGED;
52
66
  if (captureRuns) return 'coverage-capture runs the suite';
53
67
  if (!credited()) return 'no `test` credit for the pre-sync head';
54
68
  const files = storyFiles();
@@ -71,6 +85,16 @@ function readStoryFiles({ cwd, baseBranch, getChangedFilesImpl }) {
71
85
  }
72
86
  }
73
87
 
88
+ /** The run an ineligible delta leaves in place, for its log line. */
89
+ function keptRun(gate) {
90
+ return gate?.evidenceNote ? 'the skip-branch scoped run' : 'the full suite';
91
+ }
92
+
93
+ /** The replaced gate's over-budget flag, carried onto the delta. */
94
+ function overBudgetOf({ deferOnOverBudget }) {
95
+ return deferOnOverBudget ? { deferOnOverBudget } : {};
96
+ }
97
+
74
98
  /**
75
99
  * Swap the plain `test` gate for the delta re-credit when every rule holds;
76
100
  * otherwise return `gates` unchanged, logging the failed rule (no base move
@@ -116,7 +140,7 @@ export function applyTestDelta(
116
140
  });
117
141
  if (reason) {
118
142
  log?.(
119
- `[close-validation] test delta re-credit not eligible (${reason}) — running the full suite`,
143
+ `[close-validation] test delta re-credit not eligible (${reason}) — running ${keptRun(gates[index])}`,
120
144
  );
121
145
  return gates;
122
146
  }
@@ -126,5 +150,6 @@ export function applyTestDelta(
126
150
  since,
127
151
  incoming: incoming.length,
128
152
  });
129
- return gates.map((g, i) => (i === index ? delta : g));
153
+ const swapped = { ...delta, ...overBudgetOf(gates[index]) };
154
+ return gates.map((g, i) => (i === index ? swapped : g));
130
155
  }
@@ -166,6 +166,12 @@ function renderCodexAgent({ role, source, baseDir, sourceLabel }) {
166
166
  `description = ${tomlString(description)}`,
167
167
  ];
168
168
  if (effort) lines.push(`model_reasoning_effort = ${tomlString(effort)}`);
169
+ // A Bash-free `tools` allowlist turns the shell off; Codex agent files
170
+ // cannot set `sandbox_mode` (the parent turn's sandbox is inherited).
171
+ const tools = fm?.[1].match(/^tools:(.*)$/m)?.[1].split(',');
172
+ if (tools && !tools.some((t) => t.trim() === 'Bash')) {
173
+ lines.push('features.shell_tool = false');
174
+ }
169
175
  lines.push(
170
176
  `developer_instructions = ${tomlMultiline(inlineImports(body.replace(/^\n+/, ''), baseDir))}`,
171
177
  );