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
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
* scored for the branch's own work, not everything the base landed.
|
|
7
7
|
*/
|
|
8
8
|
|
|
9
|
+
import path from 'node:path';
|
|
9
10
|
import process from 'node:process';
|
|
10
11
|
import {
|
|
11
12
|
runCrapPreview,
|
|
@@ -14,10 +15,11 @@ import {
|
|
|
14
15
|
import { resolveMergeHead } from './lib/changed-files.js';
|
|
15
16
|
import { runAsCli } from './lib/cli-utils.js';
|
|
16
17
|
import { CODING_GUARDRAILS } from './lib/config/quality.js';
|
|
18
|
+
import { loadCoverage } from './lib/coverage-utils.js';
|
|
17
19
|
|
|
18
20
|
const USAGE = {
|
|
19
21
|
invocation:
|
|
20
|
-
'node .agents/scripts/quality-preview.js [--staged | --changed-since <ref>] [--only mi|crap] [--json]',
|
|
22
|
+
'node .agents/scripts/quality-preview.js [--staged | --changed-since <ref>] [--only mi|crap] [--coverage-artifact <path>] [--json]',
|
|
21
23
|
summary:
|
|
22
24
|
'Preview the per-file maintainability and CRAP deltas for the change set, and exit non-zero on any threshold violation.',
|
|
23
25
|
flags: [
|
|
@@ -33,6 +35,10 @@ const USAGE = {
|
|
|
33
35
|
'--only mi|crap',
|
|
34
36
|
'Run one half only — maintainability (`mi`) or CRAP (`crap`); the other half is reported as not run. Default: both, serially.',
|
|
35
37
|
],
|
|
38
|
+
[
|
|
39
|
+
'--coverage-artifact <path>',
|
|
40
|
+
'Score the CRAP half against this coverage-final.json (e.g. a CI artifact) instead of the configured one, without checking its capture stamp. Read-only; exit 2 when it cannot be loaded.',
|
|
41
|
+
],
|
|
36
42
|
['--json', 'Emit both gate envelopes plus the merged table as JSON.'],
|
|
37
43
|
],
|
|
38
44
|
};
|
|
@@ -91,6 +97,27 @@ function parseOnlyArg(argv) {
|
|
|
91
97
|
return at === -1 ? null : (argv[at + 1] ?? '');
|
|
92
98
|
}
|
|
93
99
|
|
|
100
|
+
/** `--coverage-artifact` (last wins): `null` absent, `''` bare, else `{ given, path }`. */
|
|
101
|
+
function parseCoverageArtifactArg(argv, cwd) {
|
|
102
|
+
const at = argv.lastIndexOf('--coverage-artifact');
|
|
103
|
+
if (at === -1) return null;
|
|
104
|
+
const given = argv[at + 1];
|
|
105
|
+
if (!given || given.startsWith('--')) return '';
|
|
106
|
+
return { given, path: path.resolve(cwd, given) };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** The refusal for an unusable argv, or `null`. */
|
|
110
|
+
function usageError({ only, artifact }) {
|
|
111
|
+
if (isUnknownHalf(only)) {
|
|
112
|
+
return `--only takes mi or crap (got "${only}").`;
|
|
113
|
+
}
|
|
114
|
+
if (artifact === '') return '--coverage-artifact needs a path.';
|
|
115
|
+
if (artifact && !loadCoverage(artifact.path)) {
|
|
116
|
+
return `--coverage-artifact ${artifact.given} is missing or not a coverage JSON object.`;
|
|
117
|
+
}
|
|
118
|
+
return null;
|
|
119
|
+
}
|
|
120
|
+
|
|
94
121
|
/**
|
|
95
122
|
* @param {string|null} only
|
|
96
123
|
* @returns {boolean}
|
|
@@ -120,6 +147,17 @@ function onlyField(only) {
|
|
|
120
147
|
return only ? { only } : {};
|
|
121
148
|
}
|
|
122
149
|
|
|
150
|
+
/** The `--json` field naming the scored artifact; empty without the flag. */
|
|
151
|
+
function coverageArtifactField(artifact) {
|
|
152
|
+
return artifact ? { coverageArtifact: artifact.path } : {};
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** The scope header, then the named artifact's line when there is one. */
|
|
156
|
+
function withArtifactLine(scopeLine, artifact) {
|
|
157
|
+
if (!artifact) return scopeLine;
|
|
158
|
+
return `${scopeLine.trimEnd()}\ncoverage=${artifact.given} (named artifact; capture stamp not checked)\n\n`;
|
|
159
|
+
}
|
|
160
|
+
|
|
123
161
|
/**
|
|
124
162
|
* The report line naming the selected half; empty for the default run.
|
|
125
163
|
*
|
|
@@ -380,7 +418,7 @@ export function renderTable(merged) {
|
|
|
380
418
|
* A thrown runner degrades to the `{ exitCode: 1, envelope: null }` shape.
|
|
381
419
|
*
|
|
382
420
|
* @param {(args: object) => Promise<{exitCode: number, envelope: object|null}>} runner
|
|
383
|
-
* @param {{cwd: string, staged: boolean, changedSinceRef: string|null}} args
|
|
421
|
+
* @param {{cwd: string, staged: boolean, changedSinceRef: string|null, coverageArtifact: string|null}} args
|
|
384
422
|
* @param {'MI'|'CRAP'} label
|
|
385
423
|
* @param {{ write: (s: string) => void }} stderr
|
|
386
424
|
* @returns {Promise<{exitCode: number, envelope: object|null}>}
|
|
@@ -419,6 +457,7 @@ function stagedScopeLine({ staged, ref, cwd }) {
|
|
|
419
457
|
* @param {{
|
|
420
458
|
* json: boolean,
|
|
421
459
|
* only: string|null,
|
|
460
|
+
* artifact: { given: string, path: string } | null,
|
|
422
461
|
* staged: boolean,
|
|
423
462
|
* ref: string|null,
|
|
424
463
|
* cwd: string,
|
|
@@ -433,6 +472,7 @@ function stagedScopeLine({ staged, ref, cwd }) {
|
|
|
433
472
|
function emitReport({
|
|
434
473
|
json,
|
|
435
474
|
only,
|
|
475
|
+
artifact,
|
|
436
476
|
staged,
|
|
437
477
|
ref,
|
|
438
478
|
cwd,
|
|
@@ -451,6 +491,7 @@ function emitReport({
|
|
|
451
491
|
ref: staged ? null : ref,
|
|
452
492
|
staged,
|
|
453
493
|
...onlyField(only),
|
|
494
|
+
...coverageArtifactField(artifact),
|
|
454
495
|
mi: { exit: miExit, envelope: miResult.envelope },
|
|
455
496
|
crap: { exit: crapExit, envelope: crapResult.envelope },
|
|
456
497
|
merged,
|
|
@@ -463,7 +504,9 @@ function emitReport({
|
|
|
463
504
|
}
|
|
464
505
|
stdout.write('\n--- quality:preview ---\n');
|
|
465
506
|
stdout.write(halfLine(only));
|
|
466
|
-
stdout.write(
|
|
507
|
+
stdout.write(
|
|
508
|
+
withArtifactLine(stagedScopeLine({ staged, ref, cwd }), artifact),
|
|
509
|
+
);
|
|
467
510
|
stdout.write(`${renderTable(merged)}\n`);
|
|
468
511
|
writeAdvisories(merged.advisories, stdout);
|
|
469
512
|
const diagnostics = renderDiagnostics([miResult, crapResult]);
|
|
@@ -498,16 +541,21 @@ export async function runCli({
|
|
|
498
541
|
const staged = parseStagedFlag(argv);
|
|
499
542
|
const ref = resolveRef(argv, staged);
|
|
500
543
|
const only = parseOnlyArg(argv);
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
);
|
|
544
|
+
const artifact = parseCoverageArtifactArg(argv, cwd);
|
|
545
|
+
const refusal = usageError({ only, artifact });
|
|
546
|
+
if (refusal) {
|
|
547
|
+
stderr.write(`[quality:preview] ${refusal}\n`);
|
|
505
548
|
return { exitCode: 2, merged: mergeEnvelopes(null, null) };
|
|
506
549
|
}
|
|
507
550
|
|
|
508
551
|
const { miResult, crapResult } = await runHalves({
|
|
509
552
|
only,
|
|
510
|
-
args: {
|
|
553
|
+
args: {
|
|
554
|
+
cwd,
|
|
555
|
+
staged,
|
|
556
|
+
changedSinceRef: ref,
|
|
557
|
+
coverageArtifact: artifact?.path ?? null,
|
|
558
|
+
},
|
|
511
559
|
runMi,
|
|
512
560
|
runCrap,
|
|
513
561
|
stderr,
|
|
@@ -520,6 +568,7 @@ export async function runCli({
|
|
|
520
568
|
emitReport({
|
|
521
569
|
json,
|
|
522
570
|
only,
|
|
571
|
+
artifact,
|
|
523
572
|
staged,
|
|
524
573
|
ref,
|
|
525
574
|
cwd,
|
|
@@ -374,6 +374,23 @@ in the foreground, now bounded to the gates plus the ~60s probe, and the long
|
|
|
374
374
|
merge wait moves into the background confirm that carries the explicit
|
|
375
375
|
timeout. A local session need not pass the flag.
|
|
376
376
|
|
|
377
|
+
**A merge-queue ejection is settled from one probe.** When a close-armed PR
|
|
378
|
+
reads out of the queue with no auto-merge request (GraphQL only — over REST
|
|
379
|
+
queue membership is unreadable and the wait is unchanged), the wait reads
|
|
380
|
+
the `merge_group` run that ejected it, on the
|
|
381
|
+
`gh-readonly-queue/<base>/pr-<n>-<parentSha>` ref, and the run of the entry
|
|
382
|
+
it was built on. An **inherited** ejection (the run was cancelled, or the
|
|
383
|
+
entry ahead failed or was cancelled) re-arms once per ejecting run, at most
|
|
384
|
+
three times per head; the fourth counts as the PR's own. An **own** ejection
|
|
385
|
+
blocks at once with block class `queue-ejected`: the CI digest is written
|
|
386
|
+
from the queue run (run link, failed jobs, failure signature) and nothing is
|
|
387
|
+
re-armed. To resume, fix the failure on `story-<id>` in the Story worktree,
|
|
388
|
+
commit, re-run `story-handoff.js` to push the new head, then run the
|
|
389
|
+
friction comment's resume command. An unreadable ejecting run keeps today's
|
|
390
|
+
one blind re-arm per head. The ejection path never re-arms a PR close did
|
|
391
|
+
not arm, under `ci.autoMerge: strict`, or one `orchestrate.releaseVeto`
|
|
392
|
+
holds.
|
|
393
|
+
|
|
377
394
|
## Close-out audit {#closeout-audit}
|
|
378
395
|
|
|
379
396
|
`deliver-recover.js` names the next command for one stranded Story;
|
|
@@ -576,7 +593,16 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
|
|
|
576
593
|
no lint/format credit, `test` credit or capture stamp, and close's re-score
|
|
577
594
|
over the same tree and base reports `unchanged`. Best-effort: a failed scan
|
|
578
595
|
or refused commit settles `error` and the run continues; close's re-score
|
|
579
|
-
stays authoritative. A re-run at the HEAD it settled skips it.
|
|
596
|
+
stays authoritative. A re-run at the HEAD it settled skips it. When
|
|
597
|
+
preflight lanes are admitted (`delivery.execution.preflightConcurrency`
|
|
598
|
+
above 1, suite admission on, not inside a suite reservation, not
|
|
599
|
+
`--report-all`), the re-score scan instead overlaps preflight: it writes
|
|
600
|
+
nothing while the checks run, and a moved row is committed at a join
|
|
601
|
+
before the independent baseline compare, which then scores the new HEAD.
|
|
602
|
+
The commit touches only the duplication baseline, so the preflight credits,
|
|
603
|
+
a held lint and the static-seat marker re-key onto it. `steps[]` lists
|
|
604
|
+
`duplication-rescore` just before `preflight`, with
|
|
605
|
+
`concurrentWith: "preflight"` and its own scan time as `durationMs`.
|
|
580
606
|
- **Post-capture checks.** After depositor and seat, the handoff runs close's
|
|
581
607
|
`quality-preview-crap` entry — only when the depositor is
|
|
582
608
|
`coverage-capture`, so a project with no capture keeps its CRAP behaviour —
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,24 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.120.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.119.0...mandrel-v2.120.0) (2026-11-12)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* merge wait settles a merge-queue ejection: re-queue an inherited failure, hand back an own failure with the queue run's digest ([#6060](https://github.com/dsj1984/mandrel/issues/6060)) ([#6064](https://github.com/dsj1984/mandrel/issues/6064)) ([d6efd90](https://github.com/dsj1984/mandrel/commit/d6efd90a332636761bed253dfe726e9342562c43))
|
|
24
|
+
* under suiteOfRecord ci the handoff runs the changed-tests command as a guard, and doctor reports a suite run in both places ([#6061](https://github.com/dsj1984/mandrel/issues/6061)) ([#6062](https://github.com/dsj1984/mandrel/issues/6062)) ([1ecbfb9](https://github.com/dsj1984/mandrel/commit/1ecbfb9d377523335a8ae4d6d4ebcea0f7da383e))
|
|
25
|
+
|
|
26
|
+
## [2.119.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.118.0...mandrel-v2.119.0) (2026-11-11)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Added
|
|
30
|
+
|
|
31
|
+
* arm a merge-queue base through the CCR route over REST, and name a green-but-unlanded merge wait honestly ([#6054](https://github.com/dsj1984/mandrel/issues/6054)) ([#6058](https://github.com/dsj1984/mandrel/issues/6058)) ([c065158](https://github.com/dsj1984/mandrel/commit/c065158420e4ab4c3cdb4f20faf7481cb6deacb4))
|
|
32
|
+
* close defers typecheck, lint and the coverage capture to CI after a conflict-free base merge when delivery.close.revalidateAfterBaseSync is ci ([#6050](https://github.com/dsj1984/mandrel/issues/6050)) ([#6057](https://github.com/dsj1984/mandrel/issues/6057)) ([23e0a72](https://github.com/dsj1984/mandrel/commit/23e0a727fe7ad8aec802670353a822e3971d2650))
|
|
33
|
+
* overlap the handoff duplication re-score with preflight under the lanes opt-in ([#6051](https://github.com/dsj1984/mandrel/issues/6051)) ([#6059](https://github.com/dsj1984/mandrel/issues/6059)) ([c2fe41f](https://github.com/dsj1984/mandrel/commit/c2fe41f086378fca8c5d6afba754083390e24186))
|
|
34
|
+
* quality-preview: score CRAP against a named coverage artifact, read-only (--coverage-artifact) ([#6052](https://github.com/dsj1984/mandrel/issues/6052)) ([#6055](https://github.com/dsj1984/mandrel/issues/6055)) ([c4fdddc](https://github.com/dsj1984/mandrel/commit/c4fdddc7324e21a30c4085dd51972c1afda08c34))
|
|
35
|
+
|
|
18
36
|
## [2.118.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.117.0...mandrel-v2.118.0) (2026-11-11)
|
|
19
37
|
|
|
20
38
|
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
// lib/cli/doctor-checks/suite-ownership.js — Doctor check: suite-ownership.
|
|
2
|
+
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import { readEffectiveAgentrc } from './effective-agentrc.js';
|
|
5
|
+
|
|
6
|
+
const KEY = 'delivery.quality.gates.coverage';
|
|
7
|
+
|
|
8
|
+
const isSet = (value) => typeof value === 'string' && value.trim().length > 0;
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Advisory: who runs the suite before a PR. Reports a suite owned by both the
|
|
12
|
+
* handoff and CI (`ciRatchetCheck` set, posture local), and a `ci` posture
|
|
13
|
+
* with no `project.commands.testChanged` guard. Never fails.
|
|
14
|
+
*
|
|
15
|
+
* @param {{ projectRoot?: string, cwd?: () => string, fsImpl?: { readFileSync: Function, existsSync: Function } }} [opts]
|
|
16
|
+
* @returns {Promise<{ ok: true, detail: string }>}
|
|
17
|
+
*/
|
|
18
|
+
export async function runSuiteOwnership({
|
|
19
|
+
projectRoot,
|
|
20
|
+
cwd,
|
|
21
|
+
fsImpl = fs,
|
|
22
|
+
} = {}) {
|
|
23
|
+
const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
|
|
24
|
+
const agentrc = readEffectiveAgentrc(root, fsImpl);
|
|
25
|
+
const gate = agentrc?.delivery?.quality?.gates?.coverage ?? {};
|
|
26
|
+
const guard = agentrc?.project?.commands?.testChanged;
|
|
27
|
+
if (gate.suiteOfRecord === 'ci') {
|
|
28
|
+
return {
|
|
29
|
+
ok: true,
|
|
30
|
+
detail: isSet(guard)
|
|
31
|
+
? `CI owns the suite; the handoff runs \`${guard.trim()}\` (project.commands.testChanged) as a changed-tests guard`
|
|
32
|
+
: 'CI owns the suite and no test runs before the PR — set project.commands.testChanged to run a changed-tests guard at the handoff',
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
if (isSet(gate.ciRatchetCheck)) {
|
|
36
|
+
return {
|
|
37
|
+
ok: true,
|
|
38
|
+
detail: `the suite is owned by both the handoff and CI ("${gate.ciRatchetCheck}") — set ${KEY}.suiteOfRecord: "ci" to make CI its owner, plus project.commands.testChanged for a changed-tests guard`,
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
return { ok: true, detail: 'the handoff owns the suite' };
|
|
42
|
+
}
|
package/lib/cli/registry.js
CHANGED
|
@@ -27,6 +27,7 @@ import {
|
|
|
27
27
|
runRuntimeDeps,
|
|
28
28
|
} from './doctor-checks/runtime-deps.js';
|
|
29
29
|
import { spawn } from './doctor-checks/spawn.js';
|
|
30
|
+
import { runSuiteOwnership } from './doctor-checks/suite-ownership.js';
|
|
30
31
|
import {
|
|
31
32
|
runAgentsInSync,
|
|
32
33
|
runCommandsInSync,
|
|
@@ -53,6 +54,8 @@ export {
|
|
|
53
54
|
};
|
|
54
55
|
|
|
55
56
|
/** `advisory: true` marks a check whose `run()` never fails. */
|
|
57
|
+
const advisory = (name, run) => ({ name, advisory: true, run });
|
|
58
|
+
|
|
56
59
|
export const registry = [
|
|
57
60
|
{
|
|
58
61
|
name: 'node-version',
|
|
@@ -129,20 +132,13 @@ export const registry = [
|
|
|
129
132
|
name: 'pin-current',
|
|
130
133
|
run: (opts) => runPinCurrent(opts),
|
|
131
134
|
},
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
advisory: true,
|
|
135
|
-
run: (opts) => runVersionCurrent(opts),
|
|
136
|
-
},
|
|
137
|
-
{
|
|
138
|
-
name: 'test-credit-path',
|
|
139
|
-
advisory: true,
|
|
140
|
-
run: (opts) => runTestCreditPath(opts),
|
|
141
|
-
},
|
|
135
|
+
advisory('version-current', (opts) => runVersionCurrent(opts)),
|
|
136
|
+
advisory('test-credit-path', (opts) => runTestCreditPath(opts)),
|
|
142
137
|
{
|
|
143
138
|
name: 'coverage-ratchet',
|
|
144
139
|
run: (opts) => runCoverageRatchet(opts),
|
|
145
140
|
},
|
|
141
|
+
advisory('suite-ownership', (opts) => runSuiteOwnership(opts)),
|
|
146
142
|
];
|
|
147
143
|
|
|
148
144
|
export default registry;
|
package/package.json
CHANGED