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.
Files changed (44) hide show
  1. package/.agents/docs/agentrc-reference.json +2 -1
  2. package/.agents/docs/configuration.md +31 -8
  3. package/.agents/schemas/agentrc.schema.json +27 -4
  4. package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
  5. package/.agents/schemas/story-deliver-terminal.schema.json +16 -1
  6. package/.agents/scripts/lib/baselines/crap-preview-coverage.js +17 -0
  7. package/.agents/scripts/lib/baselines/crap-preview-scan.js +11 -6
  8. package/.agents/scripts/lib/baselines/preview-gates.js +2 -0
  9. package/.agents/scripts/lib/baselines/refresh-service.js +21 -6
  10. package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +152 -0
  11. package/.agents/scripts/lib/close-validation/ci-deferral.js +23 -5
  12. package/.agents/scripts/lib/close-validation/gates.js +8 -2
  13. package/.agents/scripts/lib/close-validation/runner.js +8 -10
  14. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  15. package/.agents/scripts/lib/config-settings-schema-delivery.js +22 -2
  16. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  17. package/.agents/scripts/lib/coverage-deferral.js +17 -0
  18. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  19. package/.agents/scripts/lib/observability/handoff-telemetry.js +1 -0
  20. package/.agents/scripts/lib/observability/story-outcome.js +5 -4
  21. package/.agents/scripts/lib/orchestrate/inventory.js +15 -0
  22. package/.agents/scripts/lib/orchestration/handoff-changed-tests.js +67 -0
  23. package/.agents/scripts/lib/orchestration/handoff-rescore.js +95 -25
  24. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +25 -10
  25. package/.agents/scripts/lib/orchestration/merge-block-class.js +13 -1
  26. package/.agents/scripts/lib/orchestration/merge-poll.js +9 -0
  27. package/.agents/scripts/lib/orchestration/merge-queue.js +169 -21
  28. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +2 -25
  29. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +8 -1
  30. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +26 -7
  31. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +181 -26
  32. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +3 -2
  33. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +9 -3
  34. package/.agents/scripts/lib/orchestration/single-story-close/result.js +9 -6
  35. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +1 -0
  36. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +158 -71
  37. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +4 -0
  38. package/.agents/scripts/lib/orchestration/story-handoff.js +124 -26
  39. package/.agents/scripts/quality-preview.js +57 -8
  40. package/.agents/workflows/helpers/deliver-reference.md +27 -1
  41. package/docs/CHANGELOG.md +18 -0
  42. package/lib/cli/doctor-checks/suite-ownership.js +42 -0
  43. package/lib/cli/registry.js +6 -10
  44. 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(stagedScopeLine({ staged, ref, cwd }));
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
- if (isUnknownHalf(only)) {
502
- stderr.write(
503
- `[quality:preview] --only takes mi or crap (got "${only}").\n`,
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: { cwd, staged, changedSinceRef: ref },
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
+ }
@@ -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
- name: 'version-current',
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.118.0",
3
+ "version": "2.120.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/",