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.
@@ -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 (Story #4593). If no change set reached you, say so
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 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. |
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 `coverage-capture.js`
672
- never runs. It applies only when `coverage-capture` is the credited
673
- depositor; under the `test` depositor it changes nothing. It needs
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
@@ -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; you MUST strictly adhere to it.
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
- No persona packs, no `persona::*` labels — constraints come from this
17
- file, the rules, and skills; "act as [role]" means apply the matching
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 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.",
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 { AUDIT_LENSES, auditLabelsForFindings } from './audit-lenses.js';
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 `AUDIT_LENSES` SSOT the generator uses. */
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 = lensFromSourceReport(finding?.sourceReport);
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 [{ ...closeTestGate(config, scope), ...overBudgetFlag(config) }];
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 flag, carried onto the delta. */
94
- function overBudgetOf({ deferOnOverBudget }) {
95
- return deferOnOverBudget ? { deferOnOverBudget } : {};
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, ...overBudgetOf(gates[index]) };
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 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.",
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 red.
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 && !red && !running && !queued,
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, green-not-queued,
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 done(
78
- ctx.inheritedPrs.has(pr.number) ? 'red-inherited' : 'red-own-failure',
79
- );
88
+ return ctx.inheritedPrs.has(pr.number)
89
+ ? 'red-inherited'
90
+ : 'red-own-failure';
80
91
  }
81
- return done(quietState(pr, checks, ctx));
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
- if (!headMoved(pr)) blockedBy.push('head-not-moved');
110
- if (!green) blockedBy.push('checks-not-green');
111
- if (vetoHeld) blockedBy.push('release-veto');
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
- isRunInFlight,
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: Boolean(redConclusionOf(node)),
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 capture spawned and no credit was deposited${checked.note}`,
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 capture depositor's step under the `ci` posture: deferred to CI, or
36
- * `blocked` when no `ciRatchetCheck` would take the ratchet. `null` when the
37
- * posture is off or the depositor is `test`.
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 || ctx.depositor !== 'coverage-capture') return null;
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({ ejecting, parentRuns, entries }) {
190
+ function classifyEjection({ conclusion, parentRuns, entries }) {
191
191
  const inherited =
192
- ejecting.conclusion === 'cancelled' ||
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 ejecting.conclusion === 'failure' ? 'own' : 'unknown';
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
- ejecting,
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' ? await readFailedJobs(get, ejecting.id) : [];
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
- /** Failed job names of a run; `[]` when unreadable. */
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::*` at
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**, by the one predicate close registers `coverage-capture`
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 capture is deferred before anything
718
- spawns (no lock, no credit). A deferral reports the gate `deferred`, the
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 (Story #5312 retired those arms): a pass that
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.121.0",
3
+ "version": "2.123.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",