mandrel 2.109.0 → 2.111.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 (37) hide show
  1. package/.agents/audit-checklists/state-machines.md +21 -0
  2. package/.agents/docs/agentrc-reference.json +2 -1
  3. package/.agents/docs/configuration.md +33 -0
  4. package/.agents/docs/workflows.md +2 -1
  5. package/.agents/rules/ci-remediation.md +28 -4
  6. package/.agents/schemas/agentrc.schema.json +6 -0
  7. package/.agents/schemas/audit-rules.json +28 -0
  8. package/.agents/schemas/story-deliver-terminal.schema.json +9 -2
  9. package/.agents/scripts/coverage-capture.js +3 -1
  10. package/.agents/scripts/file-ci-gap.js +220 -10
  11. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  12. package/.agents/scripts/lib/close-validation/gates.js +48 -0
  13. package/.agents/scripts/lib/close-validation/runner.js +118 -31
  14. package/.agents/scripts/lib/config/gates/coverage.schema.js +9 -0
  15. package/.agents/scripts/lib/config/quality.js +3 -0
  16. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  17. package/.agents/scripts/lib/coverage-capture.js +16 -0
  18. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  19. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
  20. package/.agents/scripts/lib/orchestration/handoff-gates.js +108 -2
  21. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
  22. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
  23. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
  24. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +3 -0
  25. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +7 -1
  26. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +44 -11
  27. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +21 -13
  28. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +1 -0
  29. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +3 -0
  30. package/.agents/scripts/lib/orchestration/single-story-close/result.js +13 -0
  31. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +1 -0
  32. package/.agents/scripts/lib/orchestration/story-handoff.js +22 -7
  33. package/.agents/workflows/audit-state-machines.md +213 -0
  34. package/.agents/workflows/helpers/deliver-reference.md +8 -1
  35. package/.agents/workflows/helpers/plan-reference.md +10 -2
  36. package/docs/CHANGELOG.md +17 -0
  37. package/package.json +1 -1
@@ -4,7 +4,10 @@
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_OVER_BUDGET_EXIT_CODE,
9
+ COVERAGE_TIMEOUT_EXIT_CODE,
10
+ } from '../coverage-capture.js';
8
11
  import {
9
12
  fullSuiteLockPolicy,
10
13
  LOCK_WAIT_EXPIRED_EXIT_CODE,
@@ -20,7 +23,13 @@ import {
20
23
  isFormatterEligible,
21
24
  listChangedFilesForFormatGate,
22
25
  } from './commands.js';
23
- import { DEFAULT_GATES, GATE_TIMEOUT_HINT, partitionGates } from './gates.js';
26
+ import {
27
+ COVERAGE_DEFERRED_SKIP_REASON,
28
+ DEFAULT_GATES,
29
+ GATE_TIMEOUT_HINT,
30
+ OVER_BUDGET_BLOCK_HINT,
31
+ partitionGates,
32
+ } from './gates.js';
24
33
  import { defaultGateRunner } from './process.js';
25
34
  import { runProjectionAdvisories as defaultRunProjections } from './projections/advisories.js';
26
35
  import { defaultGetHeadSha } from './projections/head-sha.js';
@@ -30,13 +39,14 @@ import { defaultGetHeadSha } from './projections/head-sha.js';
30
39
  /**
31
40
  * Classify a non-zero gate exit and log it as what it is: `75` is an expired
32
41
  * 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
42
+ * `76` an over-budget capture the policy blocks (a deferring gate never gets
43
+ * here), and anything else a real failure with the gate's own hint. Returns the
34
44
  * `failed[]` entry, carrying `outcome` so callers never re-derive it; its
35
45
  * `gate.hint` is the one that fits the outcome (none when deferred), so a
36
46
  * caller replaying it never prints the failing-tests hint for a non-failure.
37
47
  *
38
48
  * @param {{ gate: Gate, status: number, cwd: string, log: (m: string) => void }} args
39
- * @returns {{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'failed' }}
49
+ * @returns {{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'over-budget'|'failed' }}
40
50
  */
41
51
  function reportGateExit({ gate, status, cwd, log }) {
42
52
  if (status === LOCK_WAIT_EXPIRED_EXIT_CODE) {
@@ -46,18 +56,8 @@ function reportGateExit({ gate, status, cwd, log }) {
46
56
  const { hint: _failureHint, ...deferredGate } = gate;
47
57
  return { gate: deferredGate, status, cwd, outcome: 'deferred' };
48
58
  }
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
- }
59
+ const hinted = hintedExit(gate, status);
60
+ if (hinted) return reportHintedExit({ gate, status, cwd, log, ...hinted });
61
61
  log(`[close-validation] ✖ ${gate.name} failed (exit ${status}) in ${cwd}`);
62
62
  if (gate.hint) log(`[close-validation] hint: ${gate.hint}`);
63
63
  return { gate, status, cwd, outcome: 'failed' };
@@ -138,8 +138,10 @@ export function applyChangedFileScope({ gate, spawnCwd, log }) {
138
138
  * shouldSkip?: typeof defaultShouldSkip,
139
139
  * }} opts An expired full-suite lock wait spawns nothing (here or in any gate
140
140
  * 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`.
141
+ * @returns {{ ok: boolean, failed: Array<{ gate: Gate, status: number, cwd: string, outcome: 'deferred'|'timeout'|'over-budget'|'failed' }>, skipped: Array<{ gate: Gate, reason: string }>, deferred: Array<{ gate: Gate, status: number, reason: 'over-budget' }> }}
142
+ * `outcome` classifies the exit: `deferred` (75), `timeout` (124),
143
+ * `over-budget` (76 under `block`), else `failed`. `deferred[]` holds a
144
+ * `deferOnOverBudget` gate that exited 76: not a failure, no evidence.
143
145
  */
144
146
  export async function runCloseValidation({
145
147
  cwd,
@@ -164,6 +166,7 @@ export async function runCloseValidation({
164
166
  shouldSkip = defaultShouldSkip,
165
167
  } = {}) {
166
168
  const failed = [];
169
+ const deferred = [];
167
170
  const lockOpts = fullSuiteLockOptions({ config, lockEvents });
168
171
  const skipped = [];
169
172
  const evidenceActive = useEvidence && storyId != null && standalone;
@@ -327,7 +330,7 @@ export async function runCloseValidation({
327
330
  if (firstIndepFailure) {
328
331
  const { gate, status } = firstIndepFailure;
329
332
  failed.push(reportGateExit({ gate, status, cwd: spawnCwd, log }));
330
- return { ok: false, failed, skipped };
333
+ return { ok: false, failed, skipped, deferred };
331
334
  }
332
335
 
333
336
  await runSerialGates(serial, {
@@ -335,6 +338,7 @@ export async function runCloseValidation({
335
338
  log,
336
339
  failed,
337
340
  skipped,
341
+ deferred,
338
342
  evidenceActive,
339
343
  evidenceClock,
340
344
  evidenceVerdict,
@@ -353,7 +357,7 @@ export async function runCloseValidation({
353
357
  });
354
358
  }
355
359
 
356
- return { ok: failed.length === 0, failed, skipped };
360
+ return { ok: failed.length === 0, failed, skipped, deferred };
357
361
  }
358
362
 
359
363
  /** The gate's `evidenceIdentity` argv hash, else its spawned argv's. */
@@ -428,6 +432,7 @@ async function runSerialGates(
428
432
  log,
429
433
  failed,
430
434
  skipped,
435
+ deferred,
431
436
  evidenceActive,
432
437
  evidenceClock,
433
438
  evidenceVerdict,
@@ -441,7 +446,7 @@ async function runSerialGates(
441
446
  for (const gate of serial) {
442
447
  let execution;
443
448
  try {
444
- execution = applyChangedFileScope({ gate, spawnCwd, log });
449
+ execution = resolveSerialExecution({ gate, spawnCwd, log, deferred });
445
450
  } catch (err) {
446
451
  log(
447
452
  `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
@@ -473,17 +478,99 @@ async function runSerialGates(
473
478
  undefined,
474
479
  configHash,
475
480
  );
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
- );
481
+ const recordPass = () =>
482
+ recordIfActive(
483
+ gate,
484
+ configHash,
485
+ evidenceActive ? evidenceClock() - startedAt : 0,
486
+ );
487
+ const settle = { deferred, log, spawnCwd, failGate, recordPass };
488
+ if (settleSerialResult(gate, result, settle)) return;
489
+ }
490
+ }
491
+
492
+ /** @param {Gate} gate @param {number} status */
493
+ function isDeferredOverBudget(gate, status) {
494
+ return status === COVERAGE_OVER_BUDGET_EXIT_CODE && gate.deferOnOverBudget;
495
+ }
496
+
497
+ /** A capture exit 76 the policy blocks. @param {Gate} gate @param {number} status */
498
+ function isBlockedOverBudget(gate, status) {
499
+ return (
500
+ status === COVERAGE_OVER_BUDGET_EXIT_CODE &&
501
+ gate.name === 'coverage-capture'
502
+ );
503
+ }
504
+
505
+ /**
506
+ * A non-failure exit that carries its own hint in place of the gate's: a
507
+ * killed suite (124), or a capture over budget the policy blocks (76).
508
+ *
509
+ * @param {Gate} gate @param {number} status
510
+ * @returns {{ outcome: 'timeout'|'over-budget', hint: string, line: string }|null}
511
+ */
512
+ function hintedExit(gate, status) {
513
+ if (status === COVERAGE_TIMEOUT_EXIT_CODE) {
514
+ const line = `⏱ ${gate.name} timed out (exit ${status})`;
515
+ return { outcome: 'timeout', hint: GATE_TIMEOUT_HINT, line };
516
+ }
517
+ if (!isBlockedOverBudget(gate, status)) return null;
518
+ const line = `✖ ${gate.name} over budget (exit ${status}) — the capture ran no tests`;
519
+ return { outcome: 'over-budget', hint: OVER_BUDGET_BLOCK_HINT, line };
520
+ }
521
+
522
+ function reportHintedExit({ gate, status, cwd, log, outcome, hint, line }) {
523
+ log(`[close-validation] ${line} in ${cwd}`);
524
+ log(`[close-validation] hint: ${hint}`);
525
+ return { gate: { ...gate, hint }, status, cwd, outcome };
526
+ }
527
+
528
+ /**
529
+ * The gate's execution: a skip once a capture deferred and the gate reads
530
+ * its artifact, else its changed-file scope.
531
+ */
532
+ function resolveSerialExecution({ gate, spawnCwd, log, deferred }) {
533
+ if (deferred.length === 0 || !gate.readsCoverageArtifact) {
534
+ return applyChangedFileScope({ gate, spawnCwd, log });
535
+ }
536
+ log(
537
+ `[close-validation] ⏭ ${gate.name} skipped (${COVERAGE_DEFERRED_SKIP_REASON})`,
538
+ );
539
+ return { gate, skip: true, skipReason: COVERAGE_DEFERRED_SKIP_REASON };
540
+ }
541
+
542
+ /**
543
+ * Settle a dispatched serial gate: a deferral or a pass continues (a pass is
544
+ * logged and earns evidence), any other non-zero exit fails the chain.
545
+ *
546
+ * @returns {boolean} `true` when the chain must stop.
547
+ */
548
+ function settleSerialResult(gate, result, ctx) {
549
+ const { deferred, log, spawnCwd, failGate, recordPass } = ctx;
550
+ if (deferOverBudget(gate, result.status, { deferred, log, spawnCwd })) {
551
+ return false;
552
+ }
553
+ if (result.status !== 0) {
554
+ failGate(gate, result.status);
555
+ return true;
486
556
  }
557
+ log(`[close-validation] ✓ ${gate.name}`);
558
+ recordPass();
559
+ return false;
560
+ }
561
+
562
+ /**
563
+ * Record a flagged capture's exit 76 as deferred to CI.
564
+ *
565
+ * @returns {boolean} `true` when the exit was a deferral.
566
+ */
567
+ function deferOverBudget(gate, status, { deferred, log, spawnCwd }) {
568
+ if (!isDeferredOverBudget(gate, status)) return false;
569
+ log(
570
+ `[close-validation] ⏭ ${gate.name} deferred to CI (exit ${status}, onOverBudget: defer-to-ci) — no suite ran in ${spawnCwd}`,
571
+ );
572
+ deferred.push({ gate, status, reason: 'over-budget' });
573
+ return true;
487
574
  }
488
575
 
489
576
  /**
@@ -29,6 +29,8 @@ export const COVERAGE_GATE_DEFAULTS = Object.freeze({
29
29
  captureScope: 'full',
30
30
  // On expiry `runCapture` exits 124 so callers can tell a hang from a failure.
31
31
  timeoutMs: 600_000,
32
+ // What a capture script's over-budget exit (76) means to handoff and close.
33
+ onOverBudget: 'block',
32
34
  });
33
35
 
34
36
  /** Schema bounds on `coverage.timeoutMs`: one minute to two hours. */
@@ -78,6 +80,13 @@ export const COVERAGE_GATE = {
78
80
  'Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure.',
79
81
  default: COVERAGE_GATE_DEFAULTS.timeoutMs,
80
82
  },
83
+ onOverBudget: {
84
+ type: 'string',
85
+ enum: ['block', 'defer-to-ci'],
86
+ description:
87
+ "What handoff and close do when the capture script exits 76 — the consumer-declared signal that the selected slice is over this host's budget and no test ran. `block` (default) stops the handoff (`blocked`) and fails close, naming this key. `defer-to-ci` settles the coverage gate as deferred to CI: no artifact is written or stamped and no credit is recorded, the coverage-reading gates (CRAP preview, coverage and CRAP baselines) are skipped, and handoff and close proceed — the terminal envelope and the PR body say coverage was deferred. Set it only when the consumer's CI runs the deferred suite with a coverage floor. A timeout (124) is never deferred, under either value.",
88
+ default: COVERAGE_GATE_DEFAULTS.onOverBudget,
89
+ },
81
90
  },
82
91
  additionalProperties: false,
83
92
  };
@@ -98,6 +98,7 @@ const COVERAGE_GATE_KEYS = new Set([
98
98
  'captureScript',
99
99
  'captureScope',
100
100
  'timeoutMs',
101
+ 'onOverBudget',
101
102
  ]);
102
103
 
103
104
  const MI_GATE_KEYS = new Set([
@@ -317,6 +318,7 @@ function resolveCoverageGate(userBlock) {
317
318
  captureScope: defaults.captureScope,
318
319
  tolerance: toleranceScalar(defaults.tolerance, 0),
319
320
  timeoutMs: defaults.timeoutMs,
321
+ onOverBudget: defaults.onOverBudget,
320
322
  };
321
323
  }
322
324
  warnUnknownKeys(userBlock, COVERAGE_GATE_KEYS, 'quality.gates.coverage');
@@ -332,6 +334,7 @@ function resolveCoverageGate(userBlock) {
332
334
  toleranceScalar(defaults.tolerance, 0),
333
335
  ),
334
336
  timeoutMs: userBlock.timeoutMs ?? defaults.timeoutMs,
337
+ onOverBudget: userBlock.onOverBudget ?? defaults.onOverBudget,
335
338
  };
336
339
  }
337
340
 
@@ -14,7 +14,7 @@ const COVERAGE_CAPTURE_USAGE = {
14
14
  invocation:
15
15
  'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--require-credited] [--ref <git-ref>] [--cwd <path>]',
16
16
  summary:
17
- 'Ensure the coverage artifact (delivery.quality.gates.coverage.coveragePath) is present and fresh before the coverage and CRAP gates fire, spawning `<pm> run <delivery.quality.gates.coverage.captureScript>` under the detected package manager only when it is stale (the affected capture script, with the base ref in MANDREL_COVERAGE_BASE_REF, under delivery.quality.gates.coverage.captureScope="affected"). Writes a content-digest capture stamp beside the artifact that close-validation reads to skip a redundant re-run. When delivery.quality.gates.crap.coveragePath names its own artifact, that artifact is then refreshed full-scope with `<pm> run <delivery.quality.gates.crap.captureScript>` and stamped beside itself.',
17
+ 'Ensure the coverage artifact (delivery.quality.gates.coverage.coveragePath) is present and fresh before the coverage and CRAP gates fire, spawning `<pm> run <delivery.quality.gates.coverage.captureScript>` under the detected package manager only when it is stale (the affected capture script, with the base ref in MANDREL_COVERAGE_BASE_REF, under delivery.quality.gates.coverage.captureScope="affected"). Writes a content-digest capture stamp beside the artifact that close-validation reads to skip a redundant re-run. When delivery.quality.gates.crap.coveragePath names its own artifact, that artifact is then refreshed full-scope with `<pm> run <delivery.quality.gates.crap.captureScript>` and stamped beside itself. A capture script that exits 76 declares its slice over this host\'s budget: nothing is stamped, no later pass runs, and the CLI exits 76 for delivery.quality.gates.coverage.onOverBudget to settle.',
18
18
  flags: [
19
19
  [
20
20
  '--skip-when-no-crap-files',
@@ -687,6 +687,13 @@ function dropCaptureStamp({ cwd, coveragePath }) {
687
687
  /** GNU `timeout(1)` code, so callers tell a hang (124) from failing tests. */
688
688
  export const COVERAGE_TIMEOUT_EXIT_CODE = TIMEOUT_EXIT_CODE;
689
689
 
690
+ /**
691
+ * A consumer capture script's declaration that the selected slice is over
692
+ * this host's budget and no test ran; `coverage.onOverBudget` decides what
693
+ * handoff and close make of it.
694
+ */
695
+ export const COVERAGE_OVER_BUDGET_EXIT_CODE = 76;
696
+
690
697
  /**
691
698
  * Spawn `<pm> run <script>` (the detected package manager, see
692
699
  * `packageScriptArgv`) asynchronously as its own process group, so
@@ -742,6 +749,14 @@ function timeoutMessage(code, script) {
742
749
  return `[coverage-capture] ⏱ the ${script} capture script timed out and was killed (exit ${code}) — no test verdict exists. This is usually host contention, not a failing test; re-run once the host is quieter.`;
743
750
  }
744
751
 
752
+ /**
753
+ * @param {number} code
754
+ * @param {string} script
755
+ */
756
+ function overBudgetMessage(code, script) {
757
+ return `[coverage-capture] ⏭ the ${script} capture script declared its slice over this host's budget (exit ${code}) — no suite ran and nothing was stamped. delivery.quality.gates.coverage.onOverBudget decides whether this defers to CI or blocks.`;
758
+ }
759
+
745
760
  /**
746
761
  * @param {number} code
747
762
  * @param {string} script
@@ -759,6 +774,7 @@ function failingSuiteMessage(code, script) {
759
774
  const NON_FAILURE_CAPTURE_EXITS = Object.freeze({
760
775
  [LOCK_WAIT_EXPIRED_EXIT_CODE]: ['info', lockWaitExpiredMessage],
761
776
  [COVERAGE_TIMEOUT_EXIT_CODE]: ['error', timeoutMessage],
777
+ [COVERAGE_OVER_BUDGET_EXIT_CODE]: ['info', overBudgetMessage],
762
778
  });
763
779
 
764
780
  const FAILING_SUITE_REPORT = Object.freeze(['error', failingSuiteMessage]);