mandrel 2.121.0 → 2.123.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/agents/acceptance-critic.md +1 -1
- package/.agents/docs/configuration.md +6 -4
- package/.agents/instructions.md +3 -3
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/audit-to-stories.js +21 -0
- package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +7 -3
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +18 -1
- package/.agents/scripts/lib/close-validation/gates.js +16 -3
- package/.agents/scripts/lib/close-validation/test-delta.js +9 -4
- package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
- package/.agents/scripts/lib/coverage-baseline.js +5 -1
- package/.agents/scripts/lib/orchestrate/classify.js +30 -14
- package/.agents/scripts/lib/orchestrate/inventory.js +10 -6
- package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +15 -7
- package/.agents/scripts/lib/orchestration/merge-queue.js +36 -10
- package/.agents/workflows/audit-to-stories.md +6 -3
- package/.agents/workflows/helpers/deliver-digest.md +1 -1
- package/.agents/workflows/helpers/deliver-reference.md +7 -2
- package/.agents/workflows/mandrel-orchestrate.md +4 -0
- package/.agents/workflows/memory-consolidate.md +1 -1
- package/docs/CHANGELOG.md +20 -0
- package/package.json +1 -1
|
@@ -76,7 +76,7 @@ turned in about it. Your only trusted inputs are:
|
|
|
76
76
|
into your spawn context. Do **not** re-derive the set yourself —
|
|
77
77
|
re-enumerating it can pick up commits that landed after your caller routed
|
|
78
78
|
the ceremony, and then you would be scoring a different change than the one
|
|
79
|
-
you were dispatched for
|
|
79
|
+
you were dispatched for. If no change set reached you, say so
|
|
80
80
|
in your verdict rather than substituting your own enumeration.
|
|
81
81
|
- the Story's inline `acceptance[]` and `verify[]` arrays, read from the
|
|
82
82
|
**Story body itself** (`gh issue view <storyId> --json body`) — its `##
|
|
@@ -183,7 +183,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
183
183
|
| `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `captureScript`. `affected` runs the consumer-owned `test:coverage:affected` script with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
|
|
184
184
|
| `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | 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. |
|
|
185
185
|
| `quality.gates.coverage.onOverBudget` | No | `"block"` \| `"defer-to-ci"` | `"block"` | What handoff and close do when the capture script — or the `test` command (`project.commands.test`, or `testChanged` on the skip branch and the delta re-credit) — 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. |
|
|
186
|
-
| `quality.gates.coverage.suiteOfRecord` | No | `"local"` \| `"ci"` | `"local"` | 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
|
|
186
|
+
| `quality.gates.coverage.suiteOfRecord` | No | `"local"` \| `"ci"` | `"local"` | 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 suite gate (the capture, or `test` when it is the depositor) as deferred (reason `suite-of-record-ci`) without spawning it, 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. |
|
|
187
187
|
| `quality.gates.coverage.ciRatchetCheck` | No | `string` \| `null` | `null` | Name of the consumer's CI check (check-run or status context) that runs `coverage-ratchet.js` on a deferred PR. Required by `suiteOfRecord: ci`; when set, confirm-merge holds `agent::done` on a PR carrying the `Coverage-deferred:` key line until this check is green on the PR head. Default `null`. |
|
|
188
188
|
| `quality.gates.coverage.nonInputGlobs` | No | `array<string>` | `[]` | Repo-relative picomatch globs naming paths no test reads. A matching path is dropped from both sides of the coverage delta-refresh overlap check and from the re-measured set — a delta of only matching, baseline and coverage-directory paths restamps without a run — and from the overlap check of close's `test` delta re-credit (its incoming count and emptiness test are unchanged). It never changes the suite-input filter, the tree digest or stamp freshness. Default `[]`: nothing is built in, so Markdown counts as an input unless declared here. |
|
|
189
189
|
| `quality.gates.coverage.captureHandlesConfigChanges` | No | `boolean` | `false` | Declares that the affected capture script, given `MANDREL_COVERAGE_BASE_REF`, widens its own selection when a coverage-determining config file (`package.json`, a lockfile, `tsconfig*.json`, a test-runner config) changes. When `true`, such a file in the coverage delta no longer refuses the delta refresh. Close's `test` delta re-credit refuses on a config file under either value. Default `false`. |
|
|
@@ -668,9 +668,11 @@ place.
|
|
|
668
668
|
deferred, reason `over-budget`.
|
|
669
669
|
- **`suiteOfRecord: "ci"`.** Set it in a small host's `.agentrc.local.json`.
|
|
670
670
|
The handoff and close defer the capture before anything spawns, reason
|
|
671
|
-
`suite-of-record-ci`: no full-suite lock is taken and
|
|
672
|
-
|
|
673
|
-
|
|
671
|
+
`suite-of-record-ci`: no full-suite lock is taken and neither
|
|
672
|
+
`coverage-capture.js` nor `project.commands.test` runs. It applies to
|
|
673
|
+
either credited depositor: a Story with no changed file under
|
|
674
|
+
`crap.targetDirs`, or a host with no active capture, defers its `test`
|
|
675
|
+
run the same way, and close writes the same PR marker. It needs
|
|
674
676
|
`ciRatchetCheck`. Without one the handoff settles `blocked`
|
|
675
677
|
(`ci-ratchet-undeclared`) and close fails, both naming the two keys.
|
|
676
678
|
- **The changed-tests guard.** Under `suiteOfRecord: "ci"`, when
|
package/.agents/instructions.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Agent Execution Protocol
|
|
2
2
|
|
|
3
3
|
You operate under the Agent Execution Protocol — this instruction set
|
|
4
|
-
governs your behavior and constraints
|
|
4
|
+
governs your behavior and constraints.
|
|
5
5
|
It is a lean always-on spine: procedural detail lives in the on-demand
|
|
6
6
|
tier (§ 1.F rules,
|
|
7
7
|
[`docs/execution-reference.md`](docs/execution-reference.md), skills)
|
|
@@ -13,8 +13,8 @@ and is read when the task engages it.
|
|
|
13
13
|
|
|
14
14
|
### A. Role Framing
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
16
|
+
Constraints come from this file, the rules, and skills; "act as
|
|
17
|
+
[role]" means apply the matching
|
|
18
18
|
skill or workflow guidance. Role-scoped spawn contexts live under
|
|
19
19
|
`.agents/agents/` (`delivery.routing.roleScopedAgents`); `qa.personas`
|
|
20
20
|
is a separate fixture concept. **Host mapping:** a `subagent_type: <role>`
|
|
@@ -758,7 +758,7 @@
|
|
|
758
758
|
"suiteOfRecord": {
|
|
759
759
|
"type": "string",
|
|
760
760
|
"enum": ["local", "ci"],
|
|
761
|
-
"description": "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
|
|
761
|
+
"description": "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 suite gate (the capture, or `test` when it is the depositor) as deferred (reason `suite-of-record-ci`) without spawning it, 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.",
|
|
762
762
|
"default": "local"
|
|
763
763
|
},
|
|
764
764
|
"ciRatchetCheck": {
|
|
@@ -10,6 +10,10 @@ import path from 'node:path';
|
|
|
10
10
|
import process from 'node:process';
|
|
11
11
|
import { pathToFileURL } from 'node:url';
|
|
12
12
|
import { parseArgs } from 'node:util';
|
|
13
|
+
import {
|
|
14
|
+
AUDIT_CUSTOM_LENS,
|
|
15
|
+
lensFromSourceReport,
|
|
16
|
+
} from './lib/audit-to-stories/audit-lenses.js';
|
|
13
17
|
import { buildStoryBody } from './lib/audit-to-stories/build-story-body.js';
|
|
14
18
|
import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-against-github.js';
|
|
15
19
|
import { formatEpicGrouping } from './lib/audit-to-stories/epic-grouping-directive.js';
|
|
@@ -109,6 +113,22 @@ function formatTally(tally) {
|
|
|
109
113
|
return `Critical ${tally.critical} / High ${tally.high} / Medium ${tally.medium} / Low ${tally.low}`;
|
|
110
114
|
}
|
|
111
115
|
|
|
116
|
+
/**
|
|
117
|
+
* One warning per report that maps to no canonical lens, so the fallback
|
|
118
|
+
* label is visible before anything is filed.
|
|
119
|
+
*
|
|
120
|
+
* @param {Array<{ sourceReport: string }>} reports
|
|
121
|
+
* @returns {string[]}
|
|
122
|
+
*/
|
|
123
|
+
function customLensWarnings(reports) {
|
|
124
|
+
return reports
|
|
125
|
+
.filter((r) => lensFromSourceReport(r.sourceReport) === null)
|
|
126
|
+
.map(
|
|
127
|
+
(r) =>
|
|
128
|
+
`audit lens: ${r.sourceReport} names no canonical lens; its Stories carry audit::${AUDIT_CUSTOM_LENS}.`,
|
|
129
|
+
);
|
|
130
|
+
}
|
|
131
|
+
|
|
112
132
|
/**
|
|
113
133
|
* Cross-check the reports, warn on stderr, and throw under
|
|
114
134
|
* `failOnReportFailures` (`--auto`) BEFORE any GitHub write; `--scan`
|
|
@@ -663,6 +683,7 @@ async function buildPlan(
|
|
|
663
683
|
{ groups, useProvider, issues },
|
|
664
684
|
{ loadProviderImpl, classifyGroupsImpl, logger },
|
|
665
685
|
);
|
|
686
|
+
for (const warning of customLensWarnings(reports)) logger.warn(warning);
|
|
666
687
|
|
|
667
688
|
return {
|
|
668
689
|
generatedAt: new Date().toISOString(),
|
|
@@ -12,7 +12,11 @@ import {
|
|
|
12
12
|
TYPE_LABELS,
|
|
13
13
|
} from '../label-constants.js';
|
|
14
14
|
import { labelDescription } from '../label-taxonomy.js';
|
|
15
|
-
import {
|
|
15
|
+
import {
|
|
16
|
+
AUDIT_CUSTOM_LENS,
|
|
17
|
+
AUDIT_LENSES,
|
|
18
|
+
auditLabelsForFindings,
|
|
19
|
+
} from './audit-lenses.js';
|
|
16
20
|
|
|
17
21
|
/** A lens absent here falls back to {@link DEFAULT_LENS_META}. */
|
|
18
22
|
const LENS_META = Object.freeze({
|
|
@@ -84,9 +88,9 @@ function hex(color) {
|
|
|
84
88
|
return String(color).replace('#', '');
|
|
85
89
|
}
|
|
86
90
|
|
|
87
|
-
/** Derived from the same
|
|
91
|
+
/** Derived from the same lens SSOT the generator uses. */
|
|
88
92
|
const AUDIT_LENS_LABELS = Object.freeze(
|
|
89
|
-
AUDIT_LENSES.map((name) => ({
|
|
93
|
+
[...AUDIT_LENSES, AUDIT_CUSTOM_LENS].map((name) => ({
|
|
90
94
|
name: `audit::${name}`,
|
|
91
95
|
...(LENS_META[name] ?? DEFAULT_LENS_META),
|
|
92
96
|
})),
|
|
@@ -66,13 +66,30 @@ export function lensFromSourceReport(sourceReport) {
|
|
|
66
66
|
}
|
|
67
67
|
|
|
68
68
|
/**
|
|
69
|
+
* The fixed lens a non-canonical report falls back to. Not in
|
|
70
|
+
* {@link AUDIT_LENSES}: no `/audit-custom` workflow exists to iterate.
|
|
71
|
+
*/
|
|
72
|
+
export const AUDIT_CUSTOM_LENS = 'custom';
|
|
73
|
+
|
|
74
|
+
/** Canonical lens, else the fallback for any named report, else `null`. */
|
|
75
|
+
function labelLens(sourceReport) {
|
|
76
|
+
if (typeof sourceReport !== 'string' || sourceReport.length === 0) {
|
|
77
|
+
return null;
|
|
78
|
+
}
|
|
79
|
+
return lensFromSourceReport(sourceReport) ?? AUDIT_CUSTOM_LENS;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The dedup corpus is listed by these labels, so a named report always yields
|
|
84
|
+
* one: a bespoke report gets `audit::custom` rather than none.
|
|
85
|
+
*
|
|
69
86
|
* @param {Array<{ sourceReport?: unknown }>} findings
|
|
70
87
|
* @returns {string[]} sorted, deduped `audit::<lens>` labels.
|
|
71
88
|
*/
|
|
72
89
|
export function auditLabelsForFindings(findings) {
|
|
73
90
|
const lenses = new Set();
|
|
74
91
|
for (const finding of findings ?? []) {
|
|
75
|
-
const lens =
|
|
92
|
+
const lens = labelLens(finding?.sourceReport);
|
|
76
93
|
if (lens) lenses.add(lens);
|
|
77
94
|
}
|
|
78
95
|
return [...lenses].sort().map((lens) => `audit::${lens}`);
|
|
@@ -136,6 +136,11 @@ function suiteOfRecordFlag(config) {
|
|
|
136
136
|
return ci ? { suiteOfRecordCi: { ciRatchetCheck } } : {};
|
|
137
137
|
}
|
|
138
138
|
|
|
139
|
+
/** A skip branch close scopes locally: under `suiteOfRecord: "ci"` CI owns it. */
|
|
140
|
+
function scopesSkipBranch(skipBranch, config) {
|
|
141
|
+
return skipBranch && !suiteOfRecord(config).ci;
|
|
142
|
+
}
|
|
143
|
+
|
|
139
144
|
/** Shown when `suiteOfRecord: "ci"` has no ratchet check to hand the ratchet to. */
|
|
140
145
|
export const CI_RATCHET_UNDECLARED_HINT =
|
|
141
146
|
'`delivery.quality.gates.coverage.suiteOfRecord: "ci"` defers the coverage capture to CI, but `delivery.quality.gates.coverage.ciRatchetCheck` is unset, so nothing would ratchet coverage or CRAP. Name the CI check that runs `coverage-ratchet.js`, or set `suiteOfRecord` back to `"local"`.';
|
|
@@ -171,7 +176,9 @@ function isCoverageCaptureActive(config, scripts) {
|
|
|
171
176
|
* close must keep exactly one working test gate. Its argv is
|
|
172
177
|
* `project.commands.test` (default `npm test`); after a base move close's
|
|
173
178
|
* phase may swap it for the delta re-credit (`test-delta.js`), which runs
|
|
174
|
-
* `testChanged` keyed on `MANDREL_CHANGED_SINCE`.
|
|
179
|
+
* `testChanged` keyed on `MANDREL_CHANGED_SINCE`. Under
|
|
180
|
+
* `suiteOfRecord: "ci"` it carries the posture, so the runner defers it to
|
|
181
|
+
* CI before spawning, as it does the capture.
|
|
175
182
|
*
|
|
176
183
|
* @param {boolean} coverageCaptureRunsSuite
|
|
177
184
|
* @param {object|undefined|null} config - Canonical resolved config.
|
|
@@ -181,7 +188,13 @@ function buildTestGateEntry(coverageCaptureRunsSuite, config, scope) {
|
|
|
181
188
|
if (coverageCaptureRunsSuite) return [];
|
|
182
189
|
// `fullSuiteLock` serializes this suite behind the host lock; when
|
|
183
190
|
// coverage-capture runs instead, `runCapture` takes the lock itself.
|
|
184
|
-
return [
|
|
191
|
+
return [
|
|
192
|
+
{
|
|
193
|
+
...closeTestGate(config, scope),
|
|
194
|
+
...overBudgetFlag(config),
|
|
195
|
+
...suiteOfRecordFlag(config),
|
|
196
|
+
},
|
|
197
|
+
];
|
|
185
198
|
}
|
|
186
199
|
|
|
187
200
|
const CHECK_BASELINES_HINT =
|
|
@@ -605,7 +618,7 @@ export function buildDefaultGates({
|
|
|
605
618
|
resolveBaseRefImpl,
|
|
606
619
|
}).skipBranch;
|
|
607
620
|
const testScope = closeTestScope({
|
|
608
|
-
skipBranch: captureSkipPredicted,
|
|
621
|
+
skipBranch: scopesSkipBranch(captureSkipPredicted, config),
|
|
609
622
|
config,
|
|
610
623
|
cwd,
|
|
611
624
|
baseBranch,
|
|
@@ -90,9 +90,14 @@ function keptRun(gate) {
|
|
|
90
90
|
return gate?.evidenceNote ? 'the skip-branch scoped run' : 'the full suite';
|
|
91
91
|
}
|
|
92
92
|
|
|
93
|
-
/** The replaced gate's over-budget
|
|
94
|
-
|
|
95
|
-
|
|
93
|
+
/** The replaced gate's flags the delta keeps: over-budget, and CI ownership. */
|
|
94
|
+
const CARRIED_FLAGS = ['deferOnOverBudget', 'suiteOfRecordCi'];
|
|
95
|
+
|
|
96
|
+
/** The replaced gate's carried flags that are set. */
|
|
97
|
+
function carriedFlags(gate) {
|
|
98
|
+
return Object.fromEntries(
|
|
99
|
+
CARRIED_FLAGS.filter((key) => gate[key]).map((key) => [key, gate[key]]),
|
|
100
|
+
);
|
|
96
101
|
}
|
|
97
102
|
|
|
98
103
|
/**
|
|
@@ -150,6 +155,6 @@ export function applyTestDelta(
|
|
|
150
155
|
since,
|
|
151
156
|
incoming: incoming.length,
|
|
152
157
|
});
|
|
153
|
-
const swapped = { ...delta, ...
|
|
158
|
+
const swapped = { ...delta, ...carriedFlags(gates[index]) };
|
|
154
159
|
return gates.map((g, i) => (i === index ? swapped : g));
|
|
155
160
|
}
|
|
@@ -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
|
|
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 suite gate (the capture, or `test` when it is the depositor) as deferred (reason `suite-of-record-ci`) without spawning it, 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: {
|
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
MissingCoverageArtifactError,
|
|
14
14
|
} from './coverage-capture.js';
|
|
15
15
|
import { isObject } from './json-utils.js';
|
|
16
|
+
import { isScorableSourceFile } from './source-extensions.js';
|
|
16
17
|
|
|
17
18
|
const COVERAGE_FINAL_PATH = COVERAGE_CAPTURE_DEFAULTS.coveragePath;
|
|
18
19
|
const COVERAGE_BASELINE_PATH = 'baselines/coverage.json';
|
|
@@ -342,9 +343,12 @@ export async function resolveCoverageRefreshScope({
|
|
|
342
343
|
if (fullScope) return { fullScope: true };
|
|
343
344
|
return diffScopeRef ? { baseRef: diffScopeRef } : {};
|
|
344
345
|
}
|
|
346
|
+
// Only a scorable source can carry a row; a docs-only diff scopes nothing.
|
|
345
347
|
const diff = fullScope
|
|
346
348
|
? null
|
|
347
|
-
: await deriveDiffFiles(diffScopeRef ?? 'origin/main')
|
|
349
|
+
: (await deriveDiffFiles(diffScopeRef ?? 'origin/main')).filter(
|
|
350
|
+
isScorableSourceFile,
|
|
351
|
+
);
|
|
348
352
|
return {
|
|
349
353
|
scopeFiles: narrowScopeToMeasured(diff, listMeasured(cwd), inCoverageScope),
|
|
350
354
|
requireRowsForScopeFiles: true,
|
|
@@ -14,17 +14,22 @@ const CONFLICTS_SHOWN = 10;
|
|
|
14
14
|
const BUDGET_BYTES = 16384;
|
|
15
15
|
const OVERLAPS_KEPT = 10;
|
|
16
16
|
|
|
17
|
+
/** A check that concluded and passed: done, not red, not halted. */
|
|
18
|
+
const passed = (c) => c.phase === 'done' && !c.red && !c.halted;
|
|
19
|
+
|
|
17
20
|
/**
|
|
18
21
|
* Rollup over the required checks (every check when the required set is
|
|
19
|
-
* unknown). Green needs every required name present, done and not
|
|
22
|
+
* unknown). Green needs every required name present, done, not red and not
|
|
23
|
+
* halted (cancelled, stale or awaiting action).
|
|
20
24
|
*
|
|
21
|
-
* @param {Array<{ name: string, phase: string, red: boolean }>} checks
|
|
25
|
+
* @param {Array<{ name: string, phase: string, red: boolean, halted?: boolean }>} checks
|
|
22
26
|
* @param {string[]|null} required
|
|
23
27
|
*/
|
|
24
28
|
function rollup(checks, required) {
|
|
25
29
|
const want = required ? new Set(required) : null;
|
|
26
30
|
const relevant = want ? checks.filter((c) => want.has(c.name)) : checks;
|
|
27
31
|
const red = relevant.some((c) => c.red);
|
|
32
|
+
const halted = relevant.some((c) => c.halted === true);
|
|
28
33
|
const running = relevant.some((c) => c.phase === 'running');
|
|
29
34
|
const queued = relevant.some((c) => c.phase === 'queued');
|
|
30
35
|
const present = new Set(relevant.map((c) => c.name));
|
|
@@ -33,9 +38,10 @@ function rollup(checks, required) {
|
|
|
33
38
|
: relevant.length > 0;
|
|
34
39
|
return {
|
|
35
40
|
red,
|
|
41
|
+
halted,
|
|
36
42
|
running,
|
|
37
43
|
queued,
|
|
38
|
-
green: complete &&
|
|
44
|
+
green: complete && relevant.every(passed),
|
|
39
45
|
};
|
|
40
46
|
}
|
|
41
47
|
|
|
@@ -57,8 +63,8 @@ function isEjected(pr, queueReadable) {
|
|
|
57
63
|
|
|
58
64
|
/**
|
|
59
65
|
* The first rule that holds wins: ejected, conflicted-real / -driver-only,
|
|
60
|
-
* red-inherited, red-own-failure, waiting-on-runner,
|
|
61
|
-
* stale, moving.
|
|
66
|
+
* red-inherited, red-own-failure, checks-cancelled, waiting-on-runner,
|
|
67
|
+
* green-not-queued, stale, moving.
|
|
62
68
|
*
|
|
63
69
|
* @param {object} pr normalised snapshot row
|
|
64
70
|
* @param {{ queueReadable: boolean, inheritedPrs: Set<number>,
|
|
@@ -73,12 +79,17 @@ function classifyPr(pr, ctx) {
|
|
|
73
79
|
const conflict = conflictState(pr.conflict);
|
|
74
80
|
return done(conflict.state, { conflict });
|
|
75
81
|
}
|
|
82
|
+
return done(checksState(pr, checks, ctx) ?? quietState(pr, checks, ctx));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Red outranks halted: a real failure stays the owner's to fix. */
|
|
86
|
+
function checksState(pr, checks, ctx) {
|
|
76
87
|
if (checks.red) {
|
|
77
|
-
return
|
|
78
|
-
|
|
79
|
-
|
|
88
|
+
return ctx.inheritedPrs.has(pr.number)
|
|
89
|
+
? 'red-inherited'
|
|
90
|
+
: 'red-own-failure';
|
|
80
91
|
}
|
|
81
|
-
return
|
|
92
|
+
return checks.halted ? 'checks-cancelled' : null;
|
|
82
93
|
}
|
|
83
94
|
|
|
84
95
|
/** The states below red: waiting-on-runner, green-not-queued, stale, moving. */
|
|
@@ -104,11 +115,15 @@ function substitute(requeueCommand, number) {
|
|
|
104
115
|
};
|
|
105
116
|
}
|
|
106
117
|
|
|
107
|
-
function requeueOf(pr, { green, vetoHeld, requeueCommand }) {
|
|
108
|
-
const blockedBy = [
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
118
|
+
function requeueOf(pr, { green, halted, vetoHeld, requeueCommand }) {
|
|
119
|
+
const blockedBy = [
|
|
120
|
+
[!headMoved(pr), 'head-not-moved'],
|
|
121
|
+
[!green, 'checks-not-green'],
|
|
122
|
+
[halted, 'checks-cancelled'],
|
|
123
|
+
[vetoHeld, 'release-veto'],
|
|
124
|
+
]
|
|
125
|
+
.filter(([hit]) => hit)
|
|
126
|
+
.map(([, reason]) => reason);
|
|
112
127
|
return {
|
|
113
128
|
eligible: blockedBy.length === 0,
|
|
114
129
|
blockedBy,
|
|
@@ -170,6 +185,7 @@ function prEntry(pr, verdict, opts) {
|
|
|
170
185
|
if (verdict.state === 'ejected') {
|
|
171
186
|
entry.requeue = requeueOf(pr, {
|
|
172
187
|
green: verdict.checks.green,
|
|
188
|
+
halted: verdict.checks.halted,
|
|
173
189
|
vetoHeld: vetoed && opts.vetoHeld,
|
|
174
190
|
requeueCommand: opts.requeueCommand,
|
|
175
191
|
});
|
|
@@ -10,11 +10,8 @@ import { spawnCapture } from '../child-exec.js';
|
|
|
10
10
|
import { gh as defaultGh, prTransportOf } from '../gh-exec.js';
|
|
11
11
|
import { parseApiJson } from '../gh-pr-rest.js';
|
|
12
12
|
import { gitSpawn, parseStoryBranch } from '../git-utils.js';
|
|
13
|
-
import {
|
|
14
|
-
|
|
15
|
-
readRunName,
|
|
16
|
-
redConclusionOf,
|
|
17
|
-
} from '../orchestration/merge-poll.js';
|
|
13
|
+
import { classifyRollupEntry } from '../orchestration/check-state.js';
|
|
14
|
+
import { isRunInFlight, readRunName } from '../orchestration/merge-poll.js';
|
|
18
15
|
import { parseGraphqlData } from '../orchestration/merge-queue.js';
|
|
19
16
|
import { readBaseRequiredNames } from '../orchestration/required-checks.js';
|
|
20
17
|
import { buildEnvelope } from './classify.js';
|
|
@@ -54,16 +51,23 @@ const latest = (...times) => {
|
|
|
54
51
|
return ms.length ? new Date(Math.max(...ms)).toISOString() : null;
|
|
55
52
|
};
|
|
56
53
|
|
|
54
|
+
/** Outcomes that are a real failure; the close-path merge wait reads these differently. */
|
|
55
|
+
const RED_OUTCOMES = new Set(['failure', 'timed_out']);
|
|
56
|
+
/** A run that never passed and never failed: not green, not the owner's red. */
|
|
57
|
+
const HALTED_OUTCOMES = new Set(['cancelled', 'stale', 'action_required']);
|
|
58
|
+
|
|
57
59
|
/** A rollup node (GraphQL, or REST mapped to the same shape) as a terse check. */
|
|
58
60
|
function normalizeCheck(node) {
|
|
59
61
|
const status = String(node?.status ?? '').toUpperCase();
|
|
60
62
|
let phase = 'done';
|
|
61
63
|
if (isRunInFlight(node))
|
|
62
64
|
phase = status === 'IN_PROGRESS' ? 'running' : 'queued';
|
|
65
|
+
const outcome = classifyRollupEntry(node);
|
|
63
66
|
return {
|
|
64
67
|
name: readRunName(node) ?? '',
|
|
65
68
|
phase,
|
|
66
|
-
red:
|
|
69
|
+
red: RED_OUTCOMES.has(outcome),
|
|
70
|
+
halted: HALTED_OUTCOMES.has(outcome),
|
|
67
71
|
note: node?.annotations?.nodes?.[0]?.message ?? node?.output?.title ?? null,
|
|
68
72
|
at: latest(node?.startedAt, node?.completedAt, node?.createdAt),
|
|
69
73
|
};
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* handoff-suite-of-record.js — the credited-run step under
|
|
3
3
|
* `coverage.suiteOfRecord: "ci"`, decided from config before any lock or spawn
|
|
4
|
-
* but the changed-tests guard.
|
|
4
|
+
* but the changed-tests guard, whichever depositor was resolved.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
7
|
import { suiteOfRecord } from '../close-validation/gates.js';
|
|
@@ -14,6 +14,14 @@ import { changedTestsGuard } from './handoff-changed-tests.js';
|
|
|
14
14
|
const UNDECLARED_DETAIL =
|
|
15
15
|
'delivery.quality.gates.coverage.suiteOfRecord is "ci" but delivery.quality.gates.coverage.ciRatchetCheck is unset — name the CI check that runs coverage-ratchet.js, or set suiteOfRecord to "local"';
|
|
16
16
|
|
|
17
|
+
/** Why this depositor holds the credited run, named in the deferred detail. */
|
|
18
|
+
function depositorReason(ctx) {
|
|
19
|
+
if (ctx.depositor === 'coverage-capture') return 'coverage-capture';
|
|
20
|
+
return ctx.skipBranch
|
|
21
|
+
? 'test (no changed file under crap.targetDirs)'
|
|
22
|
+
: 'test (no active coverage capture)';
|
|
23
|
+
}
|
|
24
|
+
|
|
17
25
|
/**
|
|
18
26
|
* The deferred step, once the changed-tests guard did not stop the run.
|
|
19
27
|
*
|
|
@@ -25,25 +33,25 @@ function deferred(ctx, name, ciRatchetCheck, checked) {
|
|
|
25
33
|
return {
|
|
26
34
|
name,
|
|
27
35
|
outcome: 'deferred',
|
|
28
|
-
detail: `coverage deferred to CI (suiteOfRecord: ci, ratchet check "${ciRatchetCheck}") — no
|
|
36
|
+
detail: `coverage deferred to CI (suiteOfRecord: ci, ratchet check "${ciRatchetCheck}", depositor ${depositorReason(ctx)}) — no suite spawned and no credit was deposited${checked.note}`,
|
|
29
37
|
depositor: ctx.depositor,
|
|
30
38
|
...checked.extra,
|
|
31
39
|
};
|
|
32
40
|
}
|
|
33
41
|
|
|
34
42
|
/**
|
|
35
|
-
* The
|
|
36
|
-
* `blocked` when no `ciRatchetCheck` would take the
|
|
37
|
-
*
|
|
43
|
+
* The credited-run step under the `ci` posture, for either depositor:
|
|
44
|
+
* deferred to CI, or `blocked` when no `ciRatchetCheck` would take the
|
|
45
|
+
* ratchet. `null` when the posture is off.
|
|
38
46
|
*
|
|
39
|
-
* @param {{ config: object, depositor: string, head: string, state: object }} ctx
|
|
47
|
+
* @param {{ config: object, depositor: string, skipBranch?: boolean, head: string, state: object }} ctx
|
|
40
48
|
* @param {string} name
|
|
41
49
|
* @param {{ run: Function, signal: AbortSignal }} guard runs `testChanged`.
|
|
42
50
|
* @returns {Promise<object|null>}
|
|
43
51
|
*/
|
|
44
52
|
export async function settleSuiteOfRecord(ctx, name, guard) {
|
|
45
53
|
const { ci, ciRatchetCheck } = suiteOfRecord(ctx.config);
|
|
46
|
-
if (!ci
|
|
54
|
+
if (!ci) return null;
|
|
47
55
|
const extra = { depositor: ctx.depositor };
|
|
48
56
|
if (!ciRatchetCheck) {
|
|
49
57
|
return {
|
|
@@ -187,12 +187,21 @@ function ejectingRunOf(runs) {
|
|
|
187
187
|
}
|
|
188
188
|
|
|
189
189
|
/** First rule wins: inherited (capped), own, unknown. */
|
|
190
|
-
function classifyEjection({
|
|
190
|
+
function classifyEjection({ conclusion, parentRuns, entries }) {
|
|
191
191
|
const inherited =
|
|
192
|
-
|
|
192
|
+
conclusion === 'cancelled' ||
|
|
193
193
|
parentRuns.some((r) => RED_RUN.has(r.conclusion));
|
|
194
194
|
if (inherited) return entries > MAX_INHERITED_REARMS ? 'own' : 'inherited';
|
|
195
|
-
return
|
|
195
|
+
return conclusion === 'failure' ? 'own' : 'unknown';
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** A cancelled run with a job that failed on its own was a fail-fast cancel. */
|
|
199
|
+
async function settledConclusion(get, ejecting) {
|
|
200
|
+
if (ejecting.conclusion !== 'cancelled') {
|
|
201
|
+
return { conclusion: ejecting.conclusion, jobs: null };
|
|
202
|
+
}
|
|
203
|
+
const jobs = await readFailedJobs(get, ejecting.id);
|
|
204
|
+
return { conclusion: jobs?.length ? 'failure' : 'cancelled', jobs };
|
|
196
205
|
}
|
|
197
206
|
|
|
198
207
|
/**
|
|
@@ -239,8 +248,9 @@ export async function readQueueEjection({
|
|
|
239
248
|
const parentRuns = (
|
|
240
249
|
(await get(`${QUEUE_RUNS}&head_sha=${parentSha}`))?.workflow_runs ?? []
|
|
241
250
|
).filter((r) => r.head_sha === parentSha);
|
|
251
|
+
const settled = await settledConclusion(get, ejecting);
|
|
242
252
|
const verdict = classifyEjection({
|
|
243
|
-
|
|
253
|
+
conclusion: settled.conclusion,
|
|
244
254
|
parentRuns,
|
|
245
255
|
entries: new Set(runs.map((r) => r.head_sha)).size,
|
|
246
256
|
});
|
|
@@ -251,24 +261,40 @@ export async function readQueueEjection({
|
|
|
251
261
|
conclusion: ejecting.conclusion,
|
|
252
262
|
};
|
|
253
263
|
const failedJobs =
|
|
254
|
-
verdict === 'own'
|
|
264
|
+
verdict === 'own'
|
|
265
|
+
? await failedJobsOf(get, ejecting.id, settled.jobs)
|
|
266
|
+
: [];
|
|
255
267
|
return { verdict, labels, run, failedJobs };
|
|
256
268
|
} catch (err) {
|
|
257
269
|
return { verdict: 'unknown', labels, detail: describeGhFailure(err) };
|
|
258
270
|
}
|
|
259
271
|
}
|
|
260
272
|
|
|
261
|
-
|
|
273
|
+
const OWN_FAILURE = new Set(['failure', 'timed_out']);
|
|
274
|
+
|
|
275
|
+
/** A run cancel rewrites a running job to `cancelled`; its failed step keeps `failure`. */
|
|
276
|
+
function failedOnItsOwn(job) {
|
|
277
|
+
if (OWN_FAILURE.has(job.conclusion)) return true;
|
|
278
|
+
return (
|
|
279
|
+
job.conclusion === 'cancelled' &&
|
|
280
|
+
(job.steps ?? []).some((s) => s.conclusion === 'failure')
|
|
281
|
+
);
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** Failed job names, reusing a read already made; `[]` when unreadable. */
|
|
285
|
+
async function failedJobsOf(get, runId, jobs) {
|
|
286
|
+
return jobs ?? (await readFailedJobs(get, runId)) ?? [];
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** Names of a run's jobs that failed on their own; `null` when unreadable. */
|
|
262
290
|
async function readFailedJobs(get, runId) {
|
|
263
291
|
try {
|
|
264
292
|
const body = await get(
|
|
265
293
|
`repos/{owner}/{repo}/actions/runs/${runId}/jobs?filter=latest&per_page=100`,
|
|
266
294
|
);
|
|
267
|
-
return (body?.jobs ?? [])
|
|
268
|
-
.filter((j) => j.conclusion === 'failure')
|
|
269
|
-
.map((j) => j.name);
|
|
295
|
+
return (body?.jobs ?? []).filter(failedOnItsOwn).map((j) => j.name);
|
|
270
296
|
} catch {
|
|
271
|
-
return
|
|
297
|
+
return null;
|
|
272
298
|
}
|
|
273
299
|
}
|
|
274
300
|
|
|
@@ -234,7 +234,10 @@ Labels applied:
|
|
|
234
234
|
|
|
235
235
|
- `type::story`
|
|
236
236
|
- `audit::<dimension>` — one per dimension represented in the merge
|
|
237
|
-
(cross-audit groups carry multiple).
|
|
237
|
+
(cross-audit groups carry multiple). A bespoke report whose name is not a
|
|
238
|
+
canonical lens (`audit-guard-census-results.md`) gets `audit::custom`
|
|
239
|
+
instead, so the Story stays in the label-listed dedup corpus; `--scan` warns
|
|
240
|
+
once per such report.
|
|
238
241
|
- `risk::high` — added when any finding in the group is Critical.
|
|
239
242
|
|
|
240
243
|
**No `agent::` state label, deliberately.** `agent::ready` is what
|
|
@@ -326,8 +329,8 @@ group is classified `create` and the operator is told dedupe was skipped — a
|
|
|
326
329
|
re-run opens duplicates.
|
|
327
330
|
|
|
328
331
|
**Reachable, but not through `gh`** (a cloud sandbox: no `gh`, no direct API,
|
|
329
|
-
MCP fine): fetch the corpus yourself. List every issue labelled `audit::*`
|
|
330
|
-
state `all` — `mcp__github__list_issues` or any other path — write the raw
|
|
332
|
+
MCP fine): fetch the corpus yourself. List every issue labelled `audit::*`
|
|
333
|
+
(`audit::custom` included) at state `all` — `mcp__github__list_issues` or any other path — write the raw
|
|
331
334
|
result as a JSON array, and pass it:
|
|
332
335
|
|
|
333
336
|
```bash
|
|
@@ -115,7 +115,7 @@ driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
|
|
|
115
115
|
per-host `.agentrc.local.json` sets `delivery.execution.preflightConcurrency`
|
|
116
116
|
above 1 (default 1): close's independent gates then run in admitted
|
|
117
117
|
lanes beside the base lane — [`deliver-reference.md`](deliver-reference.md) § Preflight.
|
|
118
|
-
3. **One depositor
|
|
118
|
+
3. **One depositor** (`suiteOfRecord: ci`: CI's), by one predicate close registers `coverage-capture`
|
|
119
119
|
on — coverage or CRAP gate on **and** a `captureScript`:
|
|
120
120
|
- **Capture-active** →
|
|
121
121
|
`node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
|
|
@@ -518,6 +518,10 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
|
|
|
518
518
|
`testChanged` or an unreadable merge-base falls back to the full
|
|
519
519
|
`project.commands.test`, logging which reason applied. An exit 76 from any
|
|
520
520
|
`test` form settles by `coverage.onOverBudget`, as the capture's does.
|
|
521
|
+
Under `coverage.suiteOfRecord: "ci"` none of this runs: the `test`
|
|
522
|
+
depositor is deferred to CI like the capture (no lock, no credit, the
|
|
523
|
+
`Coverage-deferred:` marker), after the changed-tests guard when
|
|
524
|
+
`testChanged` is set.
|
|
521
525
|
- **Runner shapes.** A bare `npm test` earns the `test` credit **only** where
|
|
522
526
|
the project's test script routes through mandrel's own runner, which prints
|
|
523
527
|
the outcome. On any other runner it deposits nothing and prints nothing, so
|
|
@@ -714,8 +718,9 @@ line naming host contention — neither is reported as failing tests. A
|
|
|
714
718
|
coverage-capture exiting `76` (the consumer's capture script declared its
|
|
715
719
|
slice over this host's budget, so nothing ran) follows
|
|
716
720
|
`delivery.quality.gates.coverage.onOverBudget`, and under
|
|
717
|
-
`coverage.suiteOfRecord: "ci"` the
|
|
718
|
-
|
|
721
|
+
`coverage.suiteOfRecord: "ci"` the credited suite — the capture or the
|
|
722
|
+
`test` depositor — is deferred before anything spawns (no lock, no
|
|
723
|
+
credit). A deferral reports the gate `deferred`, the
|
|
719
724
|
coverage-reading gates `skipped` (`coverage-deferred-ci`), settles the
|
|
720
725
|
handoff `ready` with a `coverage` field, and puts a `Coverage-deferred:
|
|
721
726
|
<reason>` key line in the PR body. CI's `ciRatchetCheck` job then runs
|
|
@@ -97,6 +97,10 @@ annotation, which the inventory already carries.
|
|
|
97
97
|
- **`green-not-queued`**: arm auto-merge only when `arm-auto-merge` is
|
|
98
98
|
granted and no release veto holds (`veto` is not `held`); otherwise raise
|
|
99
99
|
once.
|
|
100
|
+
- **`checks-cancelled`**: a required check was cancelled, went stale or
|
|
101
|
+
awaits action, so it never passed. Never arm auto-merge or requeue it, and
|
|
102
|
+
never message the owner about a failure; raise it once naming the halted
|
|
103
|
+
checks, so the operator decides whether to re-run them.
|
|
100
104
|
- **`waiting-on-runner`**: no action. Report the `runners` backlog, and hold
|
|
101
105
|
back optional load while it is saturated.
|
|
102
106
|
- **`stale`**: raise once.
|
|
@@ -103,7 +103,7 @@ the pass; nothing in the framework reads it back.
|
|
|
103
103
|
The `/mandrel-plan` Phase 0 advisory re-arms on exactly one condition:
|
|
104
104
|
`MEMORY.md` exceeding the fixed 24576-byte index ceiling —
|
|
105
105
|
the harness cap past which the index it loads is truncated. Pool size and
|
|
106
|
-
stamp age never trigger it
|
|
106
|
+
stamp age never trigger it: a pass that
|
|
107
107
|
rewrites long index lines short quiets it without pruning an entry.
|
|
108
108
|
|
|
109
109
|
Write it **only** after Gate #2 — the stamp asserts an operator reviewed the
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,26 @@ 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.123.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.122.0...mandrel-v2.123.0) (2026-11-17)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
* merge wait reads a fail-fast-cancelled queue run as an own ejection ([#6086](https://github.com/dsj1984/mandrel/issues/6086)) ([#6088](https://github.com/dsj1984/mandrel/issues/6088)) ([4f94261](https://github.com/dsj1984/mandrel/commit/4f94261818494b76208e6828fca0fd74d319e5eb))
|
|
24
|
+
* under suiteOfRecord ci, the test depositor defers to CI too, so a Story with no change under the CRAP target dirs runs no full local suite ([#6087](https://github.com/dsj1984/mandrel/issues/6087)) ([#6090](https://github.com/dsj1984/mandrel/issues/6090)) ([7a184a9](https://github.com/dsj1984/mandrel/commit/7a184a92bd535ae54a3d7760ae6076a5a9f200b4))
|
|
25
|
+
|
|
26
|
+
## [2.122.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.121.0...mandrel-v2.122.0) (2026-11-13)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Added
|
|
30
|
+
|
|
31
|
+
* audit-to-stories: a non-canonical report's findings carry audit::custom so indexed dedup sees their Stories ([#6081](https://github.com/dsj1984/mandrel/issues/6081)) ([#6082](https://github.com/dsj1984/mandrel/issues/6082)) ([896a468](https://github.com/dsj1984/mandrel/commit/896a4687157ddd5fe4eff000b7b440c2421ed6fe))
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
|
|
36
|
+
* orchestrate-inventory stops reporting cancelled or timed-out required checks as green ([#6084](https://github.com/dsj1984/mandrel/issues/6084)) ([#6085](https://github.com/dsj1984/mandrel/issues/6085)) ([2f1e16b](https://github.com/dsj1984/mandrel/commit/2f1e16b73cd9433ecb18a53bee43fbf4e53ebb2c))
|
|
37
|
+
|
|
18
38
|
## [2.121.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.120.0...mandrel-v2.121.0) (2026-11-12)
|
|
19
39
|
|
|
20
40
|
|
package/package.json
CHANGED