mandrel 2.118.0 → 2.120.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.
- package/.agents/docs/agentrc-reference.json +2 -1
- package/.agents/docs/configuration.md +31 -8
- package/.agents/schemas/agentrc.schema.json +27 -4
- package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
- package/.agents/schemas/story-deliver-terminal.schema.json +16 -1
- package/.agents/scripts/lib/baselines/crap-preview-coverage.js +17 -0
- package/.agents/scripts/lib/baselines/crap-preview-scan.js +11 -6
- package/.agents/scripts/lib/baselines/preview-gates.js +2 -0
- package/.agents/scripts/lib/baselines/refresh-service.js +21 -6
- package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +152 -0
- package/.agents/scripts/lib/close-validation/ci-deferral.js +23 -5
- package/.agents/scripts/lib/close-validation/gates.js +8 -2
- package/.agents/scripts/lib/close-validation/runner.js +8 -10
- package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
- package/.agents/scripts/lib/config-settings-schema-delivery.js +22 -2
- package/.agents/scripts/lib/config-settings-schema.js +1 -1
- package/.agents/scripts/lib/coverage-deferral.js +17 -0
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/observability/handoff-telemetry.js +1 -0
- package/.agents/scripts/lib/observability/story-outcome.js +5 -4
- package/.agents/scripts/lib/orchestrate/inventory.js +15 -0
- package/.agents/scripts/lib/orchestration/handoff-changed-tests.js +67 -0
- package/.agents/scripts/lib/orchestration/handoff-rescore.js +95 -25
- package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +25 -10
- package/.agents/scripts/lib/orchestration/merge-block-class.js +13 -1
- package/.agents/scripts/lib/orchestration/merge-poll.js +9 -0
- package/.agents/scripts/lib/orchestration/merge-queue.js +169 -21
- package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +2 -25
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +8 -1
- package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +26 -7
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +181 -26
- package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +3 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +9 -3
- package/.agents/scripts/lib/orchestration/single-story-close/result.js +9 -6
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +1 -0
- package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +158 -71
- package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +4 -0
- package/.agents/scripts/lib/orchestration/story-handoff.js +124 -26
- package/.agents/scripts/quality-preview.js +57 -8
- package/.agents/workflows/helpers/deliver-reference.md +27 -1
- package/docs/CHANGELOG.md +18 -0
- package/lib/cli/doctor-checks/suite-ownership.js +42 -0
- package/lib/cli/registry.js +6 -10
- package/package.json +1 -1
|
@@ -41,7 +41,8 @@ import { closeTestGate, closeTestScope } from './skip-branch-test.js';
|
|
|
41
41
|
* @property {boolean} [lockEventChannel] - The child reports on close's lock-event channel.
|
|
42
42
|
* @property {boolean} [deferOnOverBudget] - An exit 76 defers to CI instead of failing.
|
|
43
43
|
* @property {{ ciRatchetCheck: string|null }} [suiteOfRecordCi] - Deferred to CI without spawning; fails when no check is declared.
|
|
44
|
-
* @property {boolean} [readsCoverageArtifact] - Skipped once
|
|
44
|
+
* @property {boolean} [readsCoverageArtifact] - Skipped once a suite gate deferred.
|
|
45
|
+
* @property {{ reason: string, checks: string[] }} [ciDeferred] - Deferred to the named CI checks without spawning.
|
|
45
46
|
* @property {{ cmd: string, args: string[] }} [evidenceIdentity] - Evidence argv, if not the spawned one.
|
|
46
47
|
* @property {{ scope: 'delta', since: string }} [evidenceNote]
|
|
47
48
|
* @property {string} [label]
|
|
@@ -722,6 +723,11 @@ export function isIndependentGate(name) {
|
|
|
722
723
|
return INDEPENDENT_GATE_NAMES.has(name);
|
|
723
724
|
}
|
|
724
725
|
|
|
726
|
+
/** A `ciDeferred` gate is settled up front by the serial loop. */
|
|
727
|
+
function runsIndependently(gate) {
|
|
728
|
+
return isIndependentGate(gate.name) && !gate.ciDeferred;
|
|
729
|
+
}
|
|
730
|
+
|
|
725
731
|
/**
|
|
726
732
|
* Order is preserved within each bucket.
|
|
727
733
|
*
|
|
@@ -732,7 +738,7 @@ export function partitionGates(gates) {
|
|
|
732
738
|
const independent = [];
|
|
733
739
|
const serial = [];
|
|
734
740
|
for (const gate of gates) {
|
|
735
|
-
if (
|
|
741
|
+
if (runsIndependently(gate)) independent.push(gate);
|
|
736
742
|
else serial.push(gate);
|
|
737
743
|
}
|
|
738
744
|
return { independent, serial };
|
|
@@ -9,6 +9,7 @@ import {
|
|
|
9
9
|
COVERAGE_OVER_BUDGET_EXIT_CODE,
|
|
10
10
|
COVERAGE_TIMEOUT_EXIT_CODE,
|
|
11
11
|
} from '../coverage-capture.js';
|
|
12
|
+
import { SUITE_GATE_NAMES, suiteGateDeferral } from '../coverage-deferral.js';
|
|
12
13
|
import {
|
|
13
14
|
fullSuiteLockPolicy,
|
|
14
15
|
LOCK_WAIT_EXPIRED_EXIT_CODE,
|
|
@@ -142,12 +143,12 @@ export function applyChangedFileScope({ gate, spawnCwd, log }) {
|
|
|
142
143
|
* shouldSkip?: typeof defaultShouldSkip,
|
|
143
144
|
* }} opts An expired full-suite lock wait spawns nothing (here or in any gate
|
|
144
145
|
* child) and reports `LOCK_WAIT_EXPIRED_EXIT_CODE`.
|
|
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
|
+
* @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'|'base-sync-ci' }> }}
|
|
146
147
|
* `outcome` classifies the exit: `deferred` (75), `timeout` (124),
|
|
147
148
|
* `over-budget` (76 under `block`), `host-resources` (77 from a suite gate),
|
|
148
149
|
* else `failed`. `deferred[]` holds a
|
|
149
|
-
* `deferOnOverBudget` gate that exited 76, or a `suiteOfRecordCi` capture
|
|
150
|
-
* never spawned: not a failure, no evidence.
|
|
150
|
+
* `deferOnOverBudget` gate that exited 76, or a `suiteOfRecordCi` capture or
|
|
151
|
+
* `ciDeferred` gate never spawned: not a failure, no evidence.
|
|
151
152
|
*/
|
|
152
153
|
export async function runCloseValidation({
|
|
153
154
|
cwd,
|
|
@@ -508,7 +509,7 @@ function isDeferredOverBudget(gate, status) {
|
|
|
508
509
|
/** A suite gate's exit 76 the policy blocks. @param {Gate} gate @param {number} status */
|
|
509
510
|
function isBlockedOverBudget(gate, status) {
|
|
510
511
|
return (
|
|
511
|
-
status === COVERAGE_OVER_BUDGET_EXIT_CODE &&
|
|
512
|
+
status === COVERAGE_OVER_BUDGET_EXIT_CODE && SUITE_GATE_NAMES.has(gate.name)
|
|
512
513
|
);
|
|
513
514
|
}
|
|
514
515
|
|
|
@@ -516,9 +517,6 @@ function isBlockedOverBudget(gate, status) {
|
|
|
516
517
|
const GATE_HOST_RESOURCES_HINT =
|
|
517
518
|
'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
|
|
|
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
520
|
/**
|
|
523
521
|
* A non-failure exit that carries its own hint in place of the gate's: a
|
|
524
522
|
* killed suite (124), a suite that lost workers to host memory (77), or a
|
|
@@ -546,7 +544,7 @@ function overBudgetExit(gate, status) {
|
|
|
546
544
|
/** A suite gate's 77; any other gate's 77 is an ordinary failure. @param {Gate} gate @param {number} status */
|
|
547
545
|
function hostResourcesExit(gate, status) {
|
|
548
546
|
if (status !== COVERAGE_HOST_RESOURCES_EXIT_CODE) return null;
|
|
549
|
-
if (!
|
|
547
|
+
if (!SUITE_GATE_NAMES.has(gate.name)) return null;
|
|
550
548
|
const line = `⛔ ${gate.name} lost workers to host memory (exit ${status}) — no test failed`;
|
|
551
549
|
return { outcome: 'host-resources', hint: GATE_HOST_RESOURCES_HINT, line };
|
|
552
550
|
}
|
|
@@ -558,11 +556,11 @@ function reportHintedExit({ gate, status, cwd, log, outcome, hint, line }) {
|
|
|
558
556
|
}
|
|
559
557
|
|
|
560
558
|
/**
|
|
561
|
-
* The gate's execution: a skip once a
|
|
559
|
+
* The gate's execution: a skip once a suite gate deferred and the gate reads
|
|
562
560
|
* its artifact, else its changed-file scope.
|
|
563
561
|
*/
|
|
564
562
|
function resolveSerialExecution({ gate, spawnCwd, log, deferred }) {
|
|
565
|
-
if (
|
|
563
|
+
if (!(gate.readsCoverageArtifact && suiteGateDeferral(deferred))) {
|
|
566
564
|
return applyChangedFileScope({ gate, spawnCwd, log });
|
|
567
565
|
}
|
|
568
566
|
log(
|
|
@@ -100,7 +100,7 @@ export const COVERAGE_GATE = {
|
|
|
100
100
|
type: 'string',
|
|
101
101
|
enum: ['local', 'ci'],
|
|
102
102
|
description:
|
|
103
|
-
"Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. Requires `ciRatchetCheck`; without it handoff blocks and close fails.",
|
|
103
|
+
"Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. When `project.commands.testChanged` is set, the handoff first runs it as a changed-tests guard. Requires `ciRatchetCheck`; without it handoff blocks and close fails.",
|
|
104
104
|
default: COVERAGE_GATE_DEFAULTS.suiteOfRecord,
|
|
105
105
|
},
|
|
106
106
|
ciRatchetCheck: {
|
|
@@ -108,7 +108,7 @@ const EXECUTION_SCHEMA = {
|
|
|
108
108
|
minimum: 1,
|
|
109
109
|
default: 1,
|
|
110
110
|
description:
|
|
111
|
-
"Story #5997. The most handoff preflight checks that may run at once. `1` (the default) is the serial preflight. Above 1, typecheck, lint and format (close's independent gates) may also run in up to N − 1 extra lanes, each admitted through suite admission with no wait under close's argv for that gate; a miss hands the check back to the serial lane. Set it per host in `.agentrc.local.json`: whether a host can afford a second CPU-heavy check is a per-host fact.",
|
|
111
|
+
"Story #5997. The most handoff preflight checks that may run at once. `1` (the default) is the serial preflight. Above 1, typecheck, lint and format (close's independent gates) may also run in up to N − 1 extra lanes, each admitted through suite admission with no wait under close's argv for that gate; a miss hands the check back to the serial lane. When lanes are admitted (and not under `--report-all`), the handoff's duplication re-score scan also overlaps preflight instead of running before it: a moved row is committed at a join before the independent baseline compare runs, and the preflight credits re-key onto that commit. Set it per host in `.agentrc.local.json`: whether a host can afford a second CPU-heavy check is a per-host fact.",
|
|
112
112
|
},
|
|
113
113
|
},
|
|
114
114
|
additionalProperties: false,
|
|
@@ -222,7 +222,7 @@ const WORKTREE_ISOLATION_SCHEMA = {
|
|
|
222
222
|
const CLOSE_SCHEMA = {
|
|
223
223
|
type: 'object',
|
|
224
224
|
description:
|
|
225
|
-
'Close-time posture (Story #5954). `baseSync` decides whether close and a handoff re-run merge `origin/<baseBranch>` before validating.',
|
|
225
|
+
'Close-time posture (Story #5954). `baseSync` decides whether close and a handoff re-run merge `origin/<baseBranch>` before validating; the `revalidate*` keys decide what close re-runs after that merge.',
|
|
226
226
|
properties: {
|
|
227
227
|
baseSync: {
|
|
228
228
|
type: 'string',
|
|
@@ -231,6 +231,26 @@ const CLOSE_SCHEMA = {
|
|
|
231
231
|
"`always` (default) merges `origin/<baseBranch>` on every close, as before. `on-conflict` first runs a conflict-only probe and skips the merge when it is conflict-free (`git merge-tree --write-tree`) and the incoming and Story paths are disjoint (raw paths, `baselines/` and renames included); `check-baselines` then compares against the merge-base and the terminal envelope's `baseSync` says why. Any other probe answer merges as today. A handoff applies the probe only on a re-run. Opt in only behind a merge queue that re-tests the merged tree and with no up-to-date-branch requirement: a semantic conflict the probe cannot see surfaces in CI, and coverage is measured on the pre-merge tree.",
|
|
232
232
|
default: 'always',
|
|
233
233
|
},
|
|
234
|
+
revalidateAfterBaseSync: {
|
|
235
|
+
type: 'string',
|
|
236
|
+
enum: ['full', 'ci'],
|
|
237
|
+
description:
|
|
238
|
+
"What close re-runs after base-sync merged `origin/<baseBranch>`. `full` (default) re-runs every gate, as before. `ci` defers `typecheck`, `lint` and the coverage capture to the CI checks named in `revalidateCiChecks` — never spawned, reported `deferred`, the capture writing `Coverage-deferred: base-sync-ci` — but only for a conflict-free merge commit whose pre-sync head carries `typecheck` and `lint` pass evidence, with no incoming path under `revalidateAlwaysPaths` and, when the capture is registered, a `coverage.ciRatchetCheck`. Any other close re-runs everything and the terminal envelope's `revalidation` names why.",
|
|
239
|
+
default: 'full',
|
|
240
|
+
},
|
|
241
|
+
revalidateCiChecks: {
|
|
242
|
+
type: 'array',
|
|
243
|
+
items: { type: 'string', minLength: 1 },
|
|
244
|
+
uniqueItems: true,
|
|
245
|
+
description:
|
|
246
|
+
'The CI check names (check-run or status context) a `revalidateAfterBaseSync: "ci"` deferral leans on. Absent or empty, the mode falls back to a full re-run.',
|
|
247
|
+
},
|
|
248
|
+
revalidateAlwaysPaths: {
|
|
249
|
+
type: 'array',
|
|
250
|
+
items: { type: 'string', minLength: 1 },
|
|
251
|
+
description:
|
|
252
|
+
'Globs (picomatch, dotfiles included) for whole-repo invariants: a base merge bringing in any matching path always re-runs every gate under `revalidateAfterBaseSync: "ci"`.',
|
|
253
|
+
},
|
|
234
254
|
},
|
|
235
255
|
additionalProperties: false,
|
|
236
256
|
};
|
|
@@ -89,7 +89,7 @@ const COMMANDS_SCHEMA = {
|
|
|
89
89
|
testChanged: {
|
|
90
90
|
...NULLABLE_NONEMPTY_SAFE_STRING,
|
|
91
91
|
description:
|
|
92
|
-
"Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. Absent or `null` keeps the full re-run and the full skip-branch suite.",
|
|
92
|
+
"Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. It is also the handoff's changed-tests guard under `delivery.quality.gates.coverage.suiteOfRecord: ci` (see § Deferring coverage to CI). Absent or `null` keeps the full re-run and the full skip-branch suite.",
|
|
93
93
|
},
|
|
94
94
|
typecheck: {
|
|
95
95
|
...NULLABLE_NONEMPTY_SAFE_STRING,
|
|
@@ -13,14 +13,30 @@ const COVERAGE_DEFERRED_KEY = 'Coverage-deferred';
|
|
|
13
13
|
export const COVERAGE_DEFERRED_REASONS = Object.freeze({
|
|
14
14
|
overBudget: 'over-budget',
|
|
15
15
|
suiteOfRecordCi: 'suite-of-record-ci',
|
|
16
|
+
baseSyncCi: 'base-sync-ci',
|
|
16
17
|
});
|
|
17
18
|
|
|
19
|
+
/** The gates that run the suite: only their deferral is a coverage deferral. */
|
|
20
|
+
export const SUITE_GATE_NAMES = new Set(['test', 'coverage-capture']);
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* The suite gate's entry among a close's `deferred[]`, else `undefined`; a
|
|
24
|
+
* typecheck or lint deferral never stands for the suite.
|
|
25
|
+
*
|
|
26
|
+
* @param {Array<{ gate: { name: string }, reason: string }>|undefined} deferred
|
|
27
|
+
*/
|
|
28
|
+
export function suiteGateDeferral(deferred) {
|
|
29
|
+
return (deferred ?? []).find((d) => SUITE_GATE_NAMES.has(d.gate.name));
|
|
30
|
+
}
|
|
31
|
+
|
|
18
32
|
/** The prose line each reason adds beneath `Closes #<id>`. */
|
|
19
33
|
const PROSE = Object.freeze({
|
|
20
34
|
[COVERAGE_DEFERRED_REASONS.overBudget]:
|
|
21
35
|
"Coverage deferred to CI: the capture slice was over this host's budget (exit 76, onOverBudget: defer-to-ci).",
|
|
22
36
|
[COVERAGE_DEFERRED_REASONS.suiteOfRecordCi]:
|
|
23
37
|
'Coverage deferred to CI: CI is the coverage and CRAP ratchet of record (suiteOfRecord: ci).',
|
|
38
|
+
[COVERAGE_DEFERRED_REASONS.baseSyncCi]:
|
|
39
|
+
'Coverage deferred to CI: close merged the base conflict-free and CI revalidates the merged tree (revalidateAfterBaseSync: ci).',
|
|
24
40
|
});
|
|
25
41
|
|
|
26
42
|
const PROSE_LINES = new Set(Object.values(PROSE));
|
|
@@ -29,6 +45,7 @@ const PROSE_LINES = new Set(Object.values(PROSE));
|
|
|
29
45
|
const POLICY = Object.freeze({
|
|
30
46
|
[COVERAGE_DEFERRED_REASONS.overBudget]: 'defer-to-ci',
|
|
31
47
|
[COVERAGE_DEFERRED_REASONS.suiteOfRecordCi]: 'suite-of-record',
|
|
48
|
+
[COVERAGE_DEFERRED_REASONS.baseSyncCi]: 'base-sync',
|
|
32
49
|
});
|
|
33
50
|
|
|
34
51
|
/**
|