mandrel 2.108.0 → 2.110.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.
@@ -129,9 +129,9 @@ the authoritative gate — do not pre-run it. Your whole tail is one command:
129
129
 
130
130
  `node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
131
131
 
132
- It runs the blocking preflight, the base merge, the one credited run, the
133
- `--seat-missing` seat, the push with its remote-ref check, and the held
134
- review, then prints one envelope (what each step runs:
132
+ It runs the base merge, the blocking preflight, the one credited run, the
133
+ `--seat-missing` seat, the post-capture checks, the push with its remote-ref
134
+ check, and the held review, then prints one envelope (what each step runs:
135
135
  [`deliver-digest.md`](../workflows/helpers/deliver-digest.md) § 5).
136
136
  `ready` → return. `fix-required` (exit 2) → fix the cause it names, commit,
137
137
  re-run it; the same cause surviving the same fix twice is your blocked path.
@@ -396,7 +396,7 @@ const COVERAGE_CAPTURE_ARGS = Object.freeze([
396
396
  * the CRAP half stays serial behind coverage-capture. Every name MUST be in
397
397
  * the `gateName` enum of `validation-evidence.schema.json`.
398
398
  */
399
- const QUALITY_PREVIEW_GATE_NAMES = Object.freeze({
399
+ export const QUALITY_PREVIEW_GATE_NAMES = Object.freeze({
400
400
  maintainability: 'quality-preview-mi',
401
401
  crap: 'quality-preview-crap',
402
402
  });
@@ -70,7 +70,7 @@ const MARKER_PROBE_TAIL_LINES = 32;
70
70
  * @param {string} output - Combined stdout/stderr.
71
71
  * @returns {boolean}
72
72
  */
73
- function isBiomeNoFilesProcessed(output) {
73
+ export function isBiomeNoFilesProcessed(output) {
74
74
  return (
75
75
  typeof output === 'string' && output.includes(BIOME_NO_FILES_PROCESSED)
76
76
  );
@@ -63,7 +63,7 @@ function reportGateExit({ gate, status, cwd, log }) {
63
63
  return { gate, status, cwd, outcome: 'failed' };
64
64
  }
65
65
 
66
- function applyChangedFileScope({ gate, spawnCwd, log }) {
66
+ export function applyChangedFileScope({ gate, spawnCwd, log }) {
67
67
  // A skip decided when the gate list was built wins over everything.
68
68
  if (gate.skip) {
69
69
  log(`[close-validation] ⏭ ${gate.name} skipped (${gate.skip.reason})`);
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * `project.commands.*` tri-state: absent → default; own-present `null` →
3
3
  * disabled (optional gates only); string → that command. Anything else throws.
4
+ * A no-default key (`testChanged`) resolves absent the same as `null`.
4
5
  */
5
6
 
6
7
  import { isObject } from '../json-utils.js';
@@ -14,11 +15,18 @@ export const COMMANDS_DEFAULTS = Object.freeze({
14
15
  formatWrite: 'npx biome format --write .',
15
16
  });
16
17
 
18
+ /** Every known key's absent value — a default, or `null` (disabled, no argv). */
19
+ const ABSENT_COMMANDS = Object.freeze({
20
+ ...COMMANDS_DEFAULTS,
21
+ testChanged: null,
22
+ });
23
+
17
24
  /** The gates an explicit `null` disables. */
18
25
  const OPTIONAL_COMMAND_KEYS = Object.freeze([
19
26
  'typecheck',
20
27
  'lint',
21
28
  'formatCheck',
29
+ 'testChanged',
22
30
  ]);
23
31
 
24
32
  /** @param {string} raw */
@@ -54,6 +62,17 @@ function disabledCommand(key) {
54
62
  return { argv: [], raw: null, disabled: true, source: 'disabled' };
55
63
  }
56
64
 
65
+ /** @param {object} commands @param {string} key */
66
+ function isUnset(commands, key) {
67
+ return !Object.hasOwn(commands, key) || commands[key] === undefined;
68
+ }
69
+
70
+ /** @param {string} key */
71
+ function absentCommand(key) {
72
+ const fallback = ABSENT_COMMANDS[key];
73
+ return fallback ? enabled(fallback, 'default') : disabledCommand(key);
74
+ }
75
+
57
76
  /** @param {string} key @param {unknown} value */
58
77
  function configuredCommand(key, value) {
59
78
  const raw = typeof value === 'string' ? value.trim() : '';
@@ -65,22 +84,20 @@ function configuredCommand(key, value) {
65
84
 
66
85
  /** @param {string} key */
67
86
  function assertKnownKey(key) {
68
- if (!Object.hasOwn(COMMANDS_DEFAULTS, key)) {
87
+ if (!Object.hasOwn(ABSENT_COMMANDS, key)) {
69
88
  throw configError(`.${key} is not a known command`);
70
89
  }
71
90
  }
72
91
 
73
92
  /**
74
93
  * @param {object|null|undefined} config
75
- * @param {keyof typeof COMMANDS_DEFAULTS} key
94
+ * @param {keyof typeof COMMANDS_DEFAULTS | 'testChanged'} key
76
95
  * @returns {{ argv: string[], raw: string|null, disabled: boolean, source: 'default'|'disabled'|'config' }}
77
96
  */
78
97
  export function resolveProjectCommand(config, key) {
79
98
  assertKnownKey(key);
80
99
  const commands = commandsBlock(config);
81
- if (!Object.hasOwn(commands, key) || commands[key] === undefined) {
82
- return enabled(COMMANDS_DEFAULTS[key], 'default');
83
- }
100
+ if (isUnset(commands, key)) return absentCommand(key);
84
101
  return commands[key] === null
85
102
  ? disabledCommand(key)
86
103
  : configuredCommand(key, commands[key]);
@@ -89,7 +106,7 @@ export function resolveProjectCommand(config, key) {
89
106
  /** Projection over {@link resolveProjectCommand}; a disabled gate keeps `null`. */
90
107
  export function getCommands(config) {
91
108
  return Object.fromEntries(
92
- Object.keys(COMMANDS_DEFAULTS).map((key) => [
109
+ Object.keys(ABSENT_COMMANDS).map((key) => [
93
110
  key,
94
111
  resolveProjectCommand(config, key).raw,
95
112
  ]),
@@ -0,0 +1,150 @@
1
+ /**
2
+ * handoff-gates.js — the handoff's view of close's own gate list, so argv,
3
+ * env and evidence keys never drift from close.
4
+ */
5
+
6
+ import path from 'node:path';
7
+ import { fileURLToPath } from 'node:url';
8
+
9
+ import {
10
+ BASELINES_GATE_NAMES,
11
+ buildDefaultGates,
12
+ QUALITY_PREVIEW_GATE_NAMES,
13
+ } from '../close-validation/gates.js';
14
+ import {
15
+ hashCommandConfig,
16
+ recordPass,
17
+ treeFingerprint,
18
+ } from '../validation-evidence.js';
19
+
20
+ const EVIDENCE_GATE = path.resolve(
21
+ path.dirname(fileURLToPath(import.meta.url)),
22
+ '..',
23
+ '..',
24
+ 'evidence-gate.js',
25
+ );
26
+
27
+ /** Close's gate list, built with the inputs its validation phase passes. */
28
+ function closeGates(ctx) {
29
+ return buildDefaultGates({
30
+ config: ctx.config,
31
+ baseBranch: ctx.baseBranch,
32
+ cwd: ctx.cwd,
33
+ evidenceCwd: ctx.evidenceCwd,
34
+ storyId: ctx.storyId,
35
+ packageScripts: ctx.scripts,
36
+ presentBaselines: ctx.presentBaselines,
37
+ getChangedFilesImpl: ctx.getChangedFilesFn,
38
+ gitSpawnImpl: ctx.git,
39
+ });
40
+ }
41
+
42
+ /**
43
+ * Close's `lint` and `format` entries wrapped in `evidence-gate.js` with the
44
+ * argv close executes; a disabled or scoped-out gate deposits nothing.
45
+ */
46
+ export function creditedPreflight(ctx) {
47
+ const checks = [];
48
+ for (const gate of closeGates(ctx).filter((g) =>
49
+ ['lint', 'format'].includes(g.name),
50
+ )) {
51
+ const run = ctx.scopeGate({
52
+ gate,
53
+ spawnCwd: ctx.cwd,
54
+ log: (m) => ctx.progress('preflight', m),
55
+ });
56
+ if (run.skip) continue;
57
+ checks.push({
58
+ key: gate.name,
59
+ cmd: 'node',
60
+ args: [
61
+ EVIDENCE_GATE,
62
+ '--standalone',
63
+ '--scope-id',
64
+ String(ctx.storyId),
65
+ '--gate',
66
+ gate.name,
67
+ '--worktree',
68
+ ctx.cwd,
69
+ '--cwd',
70
+ ctx.evidenceCwd,
71
+ '--',
72
+ run.cmd,
73
+ ...run.args,
74
+ ],
75
+ deposit: { cmd: run.cmd, args: run.args },
76
+ tolerateNoFilesProcessed: run.tolerateNoFilesProcessed,
77
+ });
78
+ }
79
+ return checks;
80
+ }
81
+
82
+ /** The `lint` credit a clean preflight deposited, hashed as close hashes it. */
83
+ export function lintCredit(ctx, check) {
84
+ return {
85
+ head: ctx.head,
86
+ configHash: hashCommandConfig({ ...check.deposit, cwd: ctx.cwd }),
87
+ };
88
+ }
89
+
90
+ /**
91
+ * Re-key the `lint` pass deposited at `priorHead` onto the seated HEAD. Not
92
+ * `format`: its scoped argv names the changed files, which the seat changes.
93
+ * Best-effort: a failed write only costs close a lint run.
94
+ */
95
+ export function carryLintCredit(ctx, priorHead) {
96
+ const credit = ctx.state.lintCredit;
97
+ if (credit?.head !== priorHead) return;
98
+ try {
99
+ recordPass(
100
+ {
101
+ storyId: ctx.storyId,
102
+ gateName: 'lint',
103
+ sha: ctx.head,
104
+ configHash: credit.configHash,
105
+ inputFingerprint: treeFingerprint(ctx.cwd, ctx.git),
106
+ },
107
+ { cwd: ctx.evidenceCwd, standalone: true },
108
+ );
109
+ ctx.state.lintCredit = { ...credit, head: ctx.head };
110
+ } catch (err) {
111
+ ctx.progress('seat', `⚠️ lint credit not carried: ${err?.message ?? err}`);
112
+ }
113
+ }
114
+
115
+ /** `quality-preview-crap` (capture depositor only) and every baselines entry. */
116
+ function postCaptureGates(ctx) {
117
+ const names = new Set(Object.values(BASELINES_GATE_NAMES));
118
+ if (ctx.depositor === 'coverage-capture') {
119
+ names.add(QUALITY_PREVIEW_GATE_NAMES.crap);
120
+ }
121
+ return closeGates(ctx).filter((g) => names.has(g.name) && !g.skip);
122
+ }
123
+
124
+ /** The gate name, plus the kinds a baselines entry scores. */
125
+ function describeGate(gate) {
126
+ const i = gate.args.indexOf('--gate');
127
+ return i === -1 ? gate.name : `${gate.name} (kinds: ${gate.args[i + 1]})`;
128
+ }
129
+
130
+ /** Run each post-capture gate through `run`; the first non-zero exit is the finding. */
131
+ export async function scorePostCapture(ctx, run) {
132
+ const gates = postCaptureGates(ctx);
133
+ for (const gate of gates) {
134
+ const env = gate.env ? { ...ctx.env, ...gate.env } : undefined;
135
+ const res = await run(
136
+ `post-capture-${gate.name}`,
137
+ gate.cmd,
138
+ gate.args,
139
+ env,
140
+ );
141
+ if (res.status !== 0) {
142
+ const finding = `${describeGate(gate)} finding (exit ${res.status}) — fix and commit, then re-run`;
143
+ return {
144
+ gates,
145
+ failed: { gate: gate.name, finding, evidencePath: res.evidencePath },
146
+ };
147
+ }
148
+ }
149
+ return { gates, failed: null };
150
+ }
@@ -23,11 +23,14 @@ const RECORD_SEP = '\u0000';
23
23
 
24
24
  /**
25
25
  * Whole messages (bodies carry the breaking footer), oldest-first for the
26
- * type tie-break. A failed read returns `[]`, degrading to safe defaults.
26
+ * type tie-break. Merge commits are included (a delivery trailer can sit on
27
+ * one) unless `scope` narrows the read. A failed read returns `[]`,
28
+ * degrading to safe defaults.
27
29
  *
28
30
  * @param {{
29
31
  * storyBranch: string,
30
32
  * baseBranch: string,
33
+ * scope?: string[],
31
34
  * cwd?: string,
32
35
  * gitSpawn?: typeof defaultGitSpawn,
33
36
  * logger?: { warn?: Function },
@@ -37,6 +40,7 @@ const RECORD_SEP = '\u0000';
37
40
  function readBranchCommits({
38
41
  storyBranch,
39
42
  baseBranch,
43
+ scope = [],
40
44
  cwd = process.cwd(),
41
45
  gitSpawn = defaultGitSpawn,
42
46
  logger = DefaultLogger,
@@ -47,7 +51,7 @@ function readBranchCommits({
47
51
  const result = gitSpawn(
48
52
  cwd,
49
53
  'log',
50
- '--no-merges',
54
+ ...scope,
51
55
  '--reverse',
52
56
  '--format=%B%x00',
53
57
  range,
@@ -72,6 +76,14 @@ function readBranchCommits({
72
76
  }
73
77
  }
74
78
 
79
+ /** The Story's own first-parent commits: merged-in history must not pick the type. */
80
+ function readOwnCommits(read) {
81
+ return readBranchCommits({
82
+ ...read,
83
+ scope: ['--first-parent', '--no-merges'],
84
+ });
85
+ }
86
+
75
87
  /**
76
88
  * A conventional title is kept verbatim; prose is synthesized as
77
89
  * `<derivedType>: <shaped title>`. Either gets `(#<id>)` and, if breaking, `!`.
@@ -80,6 +92,7 @@ function readBranchCommits({
80
92
  * storyTitle: string,
81
93
  * storyId: number|string,
82
94
  * commitMessages?: string[],
95
+ * ownCommitMessages?: string[],
83
96
  * storyBody?: string,
84
97
  * }} args
85
98
  * @returns {{ title: string, breaking: boolean, breakingNotes: string[] }}
@@ -88,6 +101,7 @@ function normalizePrTitle({
88
101
  storyTitle,
89
102
  storyId,
90
103
  commitMessages = [],
104
+ ownCommitMessages = commitMessages,
91
105
  storyBody = '',
92
106
  }) {
93
107
  const idSuffix = `(#${storyId})`;
@@ -99,7 +113,11 @@ function normalizePrTitle({
99
113
 
100
114
  const subject = isConventionalSubject(trimmed)
101
115
  ? trimmed
102
- : synthesizeSubject({ description: trimmed, storyId, commitMessages });
116
+ : synthesizeSubject({
117
+ description: trimmed,
118
+ storyId,
119
+ commitMessages: ownCommitMessages,
120
+ });
103
121
 
104
122
  const marked = breaking ? markBreaking(subject) : subject;
105
123
  return { title: `${marked} ${idSuffix}`, breaking, breakingNotes: notes };
@@ -171,16 +189,13 @@ export function buildPullRequestFields({
171
189
  config,
172
190
  progress = () => {},
173
191
  }) {
174
- const commitMessages = readBranchCommits({
175
- storyBranch,
176
- baseBranch,
177
- cwd,
178
- gitSpawn,
179
- });
192
+ const read = { storyBranch, baseBranch, cwd, gitSpawn };
193
+ const commitMessages = readBranchCommits(read);
180
194
  const { title, breaking, breakingNotes } = normalizePrTitle({
181
195
  storyTitle,
182
196
  storyId,
183
197
  commitMessages,
198
+ ownCommitMessages: readOwnCommits(read),
184
199
  storyBody,
185
200
  });
186
201
  if (breaking) announceBreaking(breakingNotes, progress);
@@ -1,10 +1,11 @@
1
1
  /**
2
2
  * story-handoff.js — the story-worker's whole post-implementation tail as one
3
- * deterministic sequence: blocking preflight (lint, quality-preview, baselined
4
- * ratchets) → base merge → the one credited run with the held review beside
5
- * it → baseline seating → push + remote-ref check → review awaited. It runs
6
- * exactly what deliver-digest § 5 and deliver-reference § Held review define,
7
- * changing nothing close credits or adopts, and settles one envelope:
3
+ * deterministic sequence: base merge → blocking preflight (lint and format
4
+ * deposited as close's credit, quality-preview, baselined ratchets) → the one
5
+ * credited run with the held review beside it → baseline seating → close's
6
+ * post-capture CRAP and baselines scoring → push + remote-ref check → review
7
+ * awaited. It runs exactly what deliver-digest § 5 and deliver-reference
8
+ * define, with close's own gate identities, and settles one envelope:
8
9
  *
9
10
  * - `ready` (exit 0) — hand off.
10
11
  * - `fix-required` (exit 2) — the worker can fix it by editing the branch;
@@ -27,14 +28,13 @@ import {
27
28
  createLockEventChannel,
28
29
  summarizeLockEvents,
29
30
  } from '../close-lock-events.js';
30
- import {
31
- resolveGateCommand,
32
- resolveTestGateArgv,
33
- } from '../close-validation/commands.js';
31
+ import { resolveTestGateArgv } from '../close-validation/commands.js';
34
32
  import {
35
33
  isCrapGateEnabled,
36
34
  resolveCreditedDepositor,
37
35
  } from '../close-validation/gates.js';
36
+ import { isBiomeNoFilesProcessed } from '../close-validation/process.js';
37
+ import { applyChangedFileScope } from '../close-validation/runner.js';
38
38
  import {
39
39
  orchestrationLogDir,
40
40
  storyReviewDepositPath,
@@ -47,10 +47,17 @@ import { syncBranchFromBase } from '../git/sync-from-base.js';
47
47
  import { getStoryBranch, gitSpawn } from '../git-utils.js';
48
48
  import { readPackageScripts } from '../npm-scripts.js';
49
49
  import { TIMEOUT_EXIT_CODE } from '../process-group.js';
50
+ import { PROJECT_ROOT } from '../project-root.js';
50
51
  import { describeBlocking } from '../suite-admission.js';
51
52
  import { writeFileAtomic } from '../util/atomic-write.js';
52
53
  import { defaultSleep } from '../util/sleep.js';
53
54
  import { runStreamed } from './evidence-stream.js';
55
+ import {
56
+ carryLintCredit,
57
+ creditedPreflight,
58
+ lintCredit,
59
+ scorePostCapture,
60
+ } from './handoff-gates.js';
54
61
  import { handoffStatePath } from './handoff-state.js';
55
62
  import { probeHeldReviewDiff } from './review-deposit.js';
56
63
  import { createStoryProgress, handoffStepName } from './story-progress.js';
@@ -314,21 +321,11 @@ function describeSuiteFailure(status) {
314
321
  }
315
322
 
316
323
  /**
317
- * The lint preflight, absent when `project.commands.lint` is `null`.
318
- *
319
- * @param {object} config
320
- * @returns {Array<{ key: string, cmd: string, args: string[] }>}
321
- */
322
- function lintPreflight(config) {
323
- const lint = resolveGateCommand(config, 'lint');
324
- return lint.disabled ? [] : [{ key: 'lint', cmd: lint.cmd, args: lint.args }];
325
- }
326
-
327
- /**
328
- * Lint, quality-preview, then each ratchet whose baseline is committed.
324
+ * Lint and format (deposited), quality-preview, then each ratchet whose
325
+ * baseline is committed.
329
326
  *
330
327
  * @param {object} ctx
331
- * @returns {Array<{ key: string, cmd: string, args: string[], gated?: boolean }>}
328
+ * @returns {Array<{ key: string, cmd: string, args: string[], gated?: boolean, deposit?: object }>}
332
329
  */
333
330
  function preflightChecks(ctx) {
334
331
  const ratchets = RATCHETS.filter((r) =>
@@ -340,7 +337,7 @@ function preflightChecks(ctx) {
340
337
  gated: true,
341
338
  }));
342
339
  return [
343
- ...lintPreflight(ctx.config),
340
+ ...creditedPreflight(ctx),
344
341
  {
345
342
  key: 'quality-preview',
346
343
  cmd: 'node',
@@ -364,6 +361,10 @@ function preflightChecks(ctx) {
364
361
  function preflightFinding(check, run) {
365
362
  const gateFailed = check.gated === true && SIGNALS.gateFail.test(run.output);
366
363
  if (run.status === 0 && !gateFailed) return null;
364
+ // Close downgrades biome's all-paths-ignored exit the same way.
365
+ if (check.tolerateNoFilesProcessed && isBiomeNoFilesProcessed(run.output)) {
366
+ return null;
367
+ }
367
368
  const offending = check.gated
368
369
  ? run.output
369
370
  .split(/\r?\n/)
@@ -383,7 +384,16 @@ async function stepPreflight(ctx) {
383
384
  `preflight already passed at ${ctx.head.slice(0, 12)}`,
384
385
  );
385
386
  }
386
- const checks = preflightChecks(ctx);
387
+ ctx.state.lintCredit = null;
388
+ let checks;
389
+ try {
390
+ checks = preflightChecks(ctx);
391
+ } catch (err) {
392
+ return fixRequired(
393
+ name,
394
+ `could not resolve close's lint/format gates: ${err?.message ?? err}`,
395
+ );
396
+ }
387
397
  for (const check of checks) {
388
398
  const run = await runLogged(
389
399
  ctx,
@@ -395,6 +405,7 @@ async function stepPreflight(ctx) {
395
405
  if (finding) {
396
406
  return fixRequired(name, finding, { evidencePath: run.evidencePath });
397
407
  }
408
+ if (check.key === 'lint') ctx.state.lintCredit = lintCredit(ctx, check);
398
409
  }
399
410
  ctx.state.preflightHead = ctx.head;
400
411
  return ran(name, `${checks.map((c) => c.key).join(', ')} clean`);
@@ -575,7 +586,8 @@ async function commitSeatedRows(ctx, total, evidencePath) {
575
586
  { evidencePath: ctx.writeEvidence('seat-commit', detail) },
576
587
  );
577
588
  }
578
- const creditedPrior = ctx.state.creditHead === ctx.head;
589
+ const priorHead = ctx.head;
590
+ const creditedPrior = ctx.state.creditHead === priorHead;
579
591
  ctx.head = headSha(ctx) ?? ctx.head;
580
592
  ctx.state.seatHead = ctx.head;
581
593
  // Both capture-stamp digests leave `baselines/` out, so a baseline-JSON-only
@@ -583,6 +595,9 @@ async function commitSeatedRows(ctx, total, evidencePath) {
583
595
  if (creditedPrior && ctx.depositor === 'coverage-capture') {
584
596
  recordCredit(ctx, { ...ctx.state.creditTimings, head: ctx.head });
585
597
  }
598
+ if (paths.every((p) => p.startsWith('baselines/'))) {
599
+ carryLintCredit(ctx, priorHead);
600
+ }
586
601
  return ran(name, `seated ${total} row(s) and committed them`, {
587
602
  evidencePath,
588
603
  });
@@ -839,7 +854,35 @@ function stepReview(ctx) {
839
854
  }
840
855
 
841
856
  /**
842
- * The run's step order. On the evidence-gate path the `test` credit is keyed
857
+ * Pure scoring after depositor and seat: no lock, no suite, no evidence, so
858
+ * close re-scores them and stays authoritative.
859
+ *
860
+ * @param {object} ctx @returns {Promise<StepResult>}
861
+ */
862
+ async function stepPostCapture(ctx) {
863
+ const name = 'post-capture';
864
+ const { postCaptureHead, creditHead } = ctx.state;
865
+ if (postCaptureHead === ctx.head && creditHead === ctx.head) {
866
+ return skipped(name, `already clean at ${ctx.head.slice(0, 12)}`);
867
+ }
868
+ const { gates, failed } = await scorePostCapture(ctx, (...a) =>
869
+ runLogged(ctx, ...a),
870
+ );
871
+ if (failed) {
872
+ return fixRequired(name, failed.finding, {
873
+ evidencePath: failed.evidencePath,
874
+ gate: failed.gate,
875
+ });
876
+ }
877
+ ctx.state.postCaptureHead = ctx.head;
878
+ return gates.length > 0
879
+ ? ran(name, `${gates.map((g) => g.name).join(', ')} clean`)
880
+ : skipped(name, 'no post-capture gate registered');
881
+ }
882
+
883
+ /**
884
+ * The run's step order. The base merges first, so every check scores the
885
+ * tree that is pushed. On the evidence-gate path the `test` credit is keyed
843
886
  * on the tree, so seating (static MI) goes first and cannot void it; the
844
887
  * capture stamp's digests leave `baselines/` out, so a baseline seat after it
845
888
  * keeps the stamp fresh.
@@ -852,7 +895,14 @@ function stepOrder(depositor) {
852
895
  depositor === 'test'
853
896
  ? [stepSeat, stepCreditedRun]
854
897
  : [stepCreditedRun, stepSeat];
855
- return [stepPreflight, stepBaseMerge, ...middle, stepPush, stepReview];
898
+ return [
899
+ stepBaseMerge,
900
+ stepPreflight,
901
+ ...middle,
902
+ stepPostCapture,
903
+ stepPush,
904
+ stepReview,
905
+ ];
856
906
  }
857
907
 
858
908
  /**
@@ -907,7 +957,7 @@ function precheck(ctx) {
907
957
  *
908
958
  * @param {string} statePath
909
959
  * @param {(tag: string, msg: string) => void} progress
910
- * @returns {{ preflightHead?: string, creditHead?: string, creditTimings?: object, seatHead?: string }}
960
+ * @returns {{ preflightHead?: string, lintCredit?: { head: string, configHash: string }|null, creditHead?: string, creditTimings?: object, seatHead?: string, postCaptureHead?: string }}
911
961
  */
912
962
  function readState(statePath, progress) {
913
963
  let raw;
@@ -984,7 +1034,11 @@ async function defaultBlock({
984
1034
  * reraise?: (signal: string) => void,
985
1035
  * evidenceFs?: typeof fs,
986
1036
  * now?: () => number,
987
- * }} deps `runCommand` receives `onChunk`, `signal` and (when set)
1037
+ * evidenceCwd?: string,
1038
+ * scopeGate?: typeof applyChangedFileScope,
1039
+ * presentBaselines?: string[],
1040
+ * }} deps `evidenceCwd` anchors close's evidence store (the main checkout);
1041
+ * `runCommand` receives `onChunk`, `signal` and (when set)
988
1042
  * `timeoutMs` beside `cwd`/`env`; a runner that never calls `onChunk`
989
1043
  * still gets its whole output written at settle.
990
1044
  * @returns {Promise<{ envelope: object, exitCode: number }>}
@@ -1011,6 +1065,9 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
1011
1065
  reraise,
1012
1066
  evidenceFs,
1013
1067
  now = Date.now,
1068
+ evidenceCwd = PROJECT_ROOT,
1069
+ scopeGate = applyChangedFileScope,
1070
+ presentBaselines,
1014
1071
  } = deps;
1015
1072
  const block =
1016
1073
  deps.block ??
@@ -1047,17 +1104,16 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
1047
1104
  lockPollMs,
1048
1105
  env,
1049
1106
  now,
1107
+ evidenceCwd,
1108
+ scopeGate,
1109
+ presentBaselines,
1110
+ getChangedFilesFn,
1050
1111
  state: readState(statePath, progress),
1051
1112
  review: null,
1052
1113
  reviewPending: null,
1053
1114
  reviewMs: null,
1054
1115
  reviewPath: storyReviewDepositPath(storyId, config),
1055
- depositor: selectCreditedDepositor({
1056
- config,
1057
- scripts: readPackageScriptsFn(cwd),
1058
- cwd,
1059
- getChangedFilesImpl: getChangedFilesFn,
1060
- }),
1116
+ scripts: readPackageScriptsFn(cwd),
1061
1117
  storyProgress,
1062
1118
  // Undefined fields take runStreamed's defaults.
1063
1119
  stream: {
@@ -1074,6 +1130,12 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
1074
1130
  return file;
1075
1131
  },
1076
1132
  };
1133
+ ctx.depositor = selectCreditedDepositor({
1134
+ config,
1135
+ scripts: ctx.scripts,
1136
+ cwd,
1137
+ getChangedFilesImpl: getChangedFilesFn,
1138
+ });
1077
1139
  ctx.head = headSha(ctx);
1078
1140
 
1079
1141
  const steps = [];
@@ -113,12 +113,11 @@ or an unregistered merge driver: it flips `agent::blocked` and posts
113
113
  close, opens a PR or writes another label. Outruns the sync Bash ceiling → run
114
114
  it in the **background**.
115
115
 
116
- 1. **Preflight — blocking.** `project.commands.lint`,
116
+ 1. **Base merge.** It will merge `origin/<baseBranch>` into the Story branch
117
+ **first**, ahead of every check: close's base-sync then no-ops.
118
+ 2. **Preflight — blocking.** `lint`/`format` (close's credit),
117
119
  `quality-preview.js --changed-since origin/<baseBranch>`, then each
118
- baselined standalone ratchet (dead exports, cycles, cyclomatic) — [`deliver-reference.md`](deliver-reference.md) § Preflight.
119
- 2. **Base merge.** It will merge `origin/<baseBranch>` into the Story branch
120
- **first**, ahead of this run and the push: close's base-sync then no-ops,
121
- so neither stamp goes stale.
120
+ baselined ratchet — [`deliver-reference.md`](deliver-reference.md) § Preflight.
122
121
  3. **One depositor**, by the one predicate close registers `coverage-capture`
123
122
  on — coverage or CRAP gate on **and** a `captureScript`:
124
123
  - **Capture-active** →
@@ -129,12 +128,13 @@ it in the **background**.
129
128
  --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`.
130
129
  Signal: `✓ test passed` — the `test` evidence close reads.
131
130
  4. **Seat.** CRAP or MI gate on → `--seat-missing` for each (signal
132
- `seated: N`), committed as `chore(baselines): baseline-refresh: …`.
131
+ `seated: N`), committed as `chore(baselines): baseline-refresh: …`; then
132
+ post-capture checks: close's `quality-preview-crap` and `check-baselines`.
133
133
  5. **Push** `story-<id>`; the remote ref must equal HEAD.
134
134
  6. **Held review** beside step 3, which a CRITICAL aborts —
135
135
  [`deliver-reference.md`](deliver-reference.md) § Held review.
136
136
 
137
- A later commit voids either credit; a baseline-JSON seat keeps the stamp. It
137
+ A later commit voids any credit; a baseline-JSON seat keeps the stamp. It
138
138
  reads the **output**, not the exit code: a run that prints no signal
139
139
  deposits nothing. Seat order, runner shapes, redraft rounds:
140
140
  [`deliver-reference.md`](deliver-reference.md) § Credited run.
@@ -367,15 +367,26 @@ sibling to unblock, and the foreground wait is the cheapest path to `landed`.
367
367
 
368
368
  ## Preflight (before close) {#preflight}
369
369
 
370
- Digest § 5 states the rule: `story-handoff.js` runs, before the credited
371
- suite run, the configured `project.commands.lint` (falling back to
372
- `npm run lint`), `quality-preview.js --changed-since origin/<baseBranch>`,
373
- then the shipped standalone ratchets CI's `baselines` job runs —
374
- `check-dead-exports.js` (default and `--production`), `check-arch-cycles.js`
375
- and `check-cyclomatic.js` — in the worktree; a finding is `fix-required` —
376
- fix, commit, re-run it. It runs **before** the credited run because a
377
- fix commit afterwards would void that run's credit.
378
-
370
+ Digest § 5 states the rule: `story-handoff.js` runs, after the base merge
371
+ and before the credited suite run, close's own `lint` and `format` gates,
372
+ `quality-preview.js --changed-since origin/<baseBranch>`, then the shipped
373
+ standalone ratchets CI's `baselines` job runs — `check-dead-exports.js`
374
+ (default and `--production`), `check-arch-cycles.js` and
375
+ `check-cyclomatic.js` — in the worktree; a finding is `fix-required` — fix,
376
+ commit, re-run it. It runs **before** the credited run because a fix commit
377
+ afterwards would void that run's credit.
378
+
379
+ - **Lint and format are close's credit.** The handoff takes both entries from
380
+ close's `buildDefaultGates` (same config, base branch, worktree and
381
+ evidence root) and runs them through `evidence-gate.js --standalone
382
+ --gate <name>`, so the pass lands in close's evidence store keyed to the
383
+ post-merge HEAD and tree, with close's command hash. `format` runs the argv
384
+ close's runner scopes to the changed files, and deposits nothing when that
385
+ scoping skips it or `project.commands.formatCheck` is `null`. Close on the
386
+ handed-off HEAD skips both as `evidence-match`. A baselines-only seat commit
387
+ re-keys the `lint` record to the seated HEAD; `format` is not carried (its
388
+ argv names the changed files). Any other commit, or a close-time base move,
389
+ re-runs them.
379
390
  - **Why.** Close runs lint and the maintainability half of the preview
380
391
  (`quality-preview-mi`) in its parallel phase, but a regression found there
381
392
  still costs a close round-trip. Seconds of preflight in the worktree is
@@ -391,6 +402,7 @@ fix commit afterwards would void that run's credit.
391
402
  rows. Close does not run them — CI stays their backstop.
392
403
  - **Close stays authoritative.** Its `quality-preview-crap` gate scores a
393
404
  fresh capture after `coverage-capture`; a preflight pass never skips it.
405
+ The handoff's post-capture step (§ Credited run) runs that gate early too.
394
406
 
395
407
  ## Credited run (situational) {#credited-run}
396
408
 
@@ -437,6 +449,15 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
437
449
  over the in-scope files is exactly 100% — a lower rate means the artifact's
438
450
  coordinates predate the tree. The refusal names the rate, the unresolved
439
451
  files and the fix: re-run the digest § 5 capture, then seat.
452
+ - **Post-capture checks.** After depositor and seat, the handoff runs close's
453
+ `quality-preview-crap` entry — only when the depositor is
454
+ `coverage-capture`, so a project with no capture keeps its CRAP behaviour —
455
+ and every registered `check-baselines` entry (`single`, or `independent`
456
+ plus `coverage`), each with close's argv and env (`BASELINE_REF`). A
457
+ non-zero exit is `fix-required` naming the gate and its kinds, with the log
458
+ as evidence; nothing is pushed. They are pure scoring: no lock, no suite,
459
+ no evidence, so close re-scores them. A re-run at a credited, unchanged
460
+ HEAD skips them.
440
461
  - **Seat order vs credit.** Neither capture-stamp digest reads
441
462
  `baselines/`, so a baseline-JSON-only seat commit leaves it fresh and the
442
463
  capture credit stands. The evidence-gate `test` credit is keyed on the tree, so on that
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.110.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.109.0...mandrel-v2.110.0) (2026-11-05)
19
+
20
+
21
+ ### Fixed
22
+
23
+ * close lifts PR-body trailers from merge commits and takes the PR type from the Story branch's own commits ([#5942](https://github.com/dsj1984/mandrel/issues/5942)) ([#5943](https://github.com/dsj1984/mandrel/issues/5943)) ([adbc4f6](https://github.com/dsj1984/mandrel/commit/adbc4f6d608a43ba79beeeb2b217ee494a8b1ead))
24
+
25
+ ## [2.109.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.108.0...mandrel-v2.109.0) (2026-10-30)
26
+
27
+
28
+ ### Added
29
+
30
+ * handoff merges the base first, deposits lint/format credit close reuses, and scores CRAP and baselines after the capture ([#5937](https://github.com/dsj1984/mandrel/issues/5937)) ([#5941](https://github.com/dsj1984/mandrel/issues/5941)) ([76f7191](https://github.com/dsj1984/mandrel/commit/76f71918fb06cfc5b99ce2db42039b420b64027f))
31
+
32
+
33
+ ### Fixed
34
+
35
+ * **deps:** pin re2js ^2.8.7 tree-wide to clear GHSA-gg6h-894w-4m9c (refs [#5932](https://github.com/dsj1984/mandrel/issues/5932)) ([#5938](https://github.com/dsj1984/mandrel/issues/5938)) ([cf7a25e](https://github.com/dsj1984/mandrel/commit/cf7a25e473514f9061048efa90d46db324c8babd))
36
+ * resolveConfig() keeps project.commands.testChanged so close's base-moved delta re-credit fires ([#5936](https://github.com/dsj1984/mandrel/issues/5936)) ([#5940](https://github.com/dsj1984/mandrel/issues/5940)) ([7931049](https://github.com/dsj1984/mandrel/commit/7931049e346eb29d9139c334a7421c18bcf60271))
37
+
18
38
  ## [2.108.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.107.0...mandrel-v2.108.0) (2026-10-27)
19
39
 
20
40
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.108.0",
3
+ "version": "2.110.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/",
@@ -150,12 +150,14 @@
150
150
  "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
151
151
  "overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.24.x declares an EXACT markdown-it 15.0.3, and this tree-wide ^15.0.3 pin keeps every markdown-it consumer on that patched major. The 14.x line carried GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths) and GHSA-gfr2-rv44-r23c (high — quadratic-time rendering of a multi-line link reference definition, vulnerable >=14.1.0 <14.3.3); the pin's floor tracks markdownlint-cli2's own declaration so the two never split. `npm run lint` is what must be re-run if this pin moves.",
152
152
  "overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.24.x declares an EXACT smol-toml 1.9.1, and this tree-wide ^1.9.1 pin keeps every smol-toml consumer at or above it. Older lines carried GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML, vulnerable <= 1.7.0) and GHSA-r4xh-jqrq-34v2 (moderate — quadratic-time parse(), vulnerable <= 1.8.0). knip declares ^1.6.1 and is satisfied natively. `npm run lint` is what must be re-run if this pin moves. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync.",
153
- "overrides.katex": "Clears GHSA-238p-pmpm-9mq7 (low — prototype pollution bypassing trust restrictions, vulnerable >=0.11.0 <0.18.2). katex reaches the tree only through markdownlint (micromark-extension-math declares ^0.16.0, so no lockfile-only resolution reaches the fix). markdownlint imports only the math SYNTAX extension, never the HTML renderer that loads katex, so this tree-wide ^0.18.2 pin changes no executed code; `npm run lint` is what must be re-run if it moves. katex is NOT a direct dependency, so there is no lockstep duplicate range."
153
+ "overrides.katex": "Clears GHSA-238p-pmpm-9mq7 (low — prototype pollution bypassing trust restrictions, vulnerable >=0.11.0 <0.18.2). katex reaches the tree only through markdownlint (micromark-extension-math declares ^0.16.0, so no lockfile-only resolution reaches the fix). markdownlint imports only the math SYNTAX extension, never the HTML renderer that loads katex, so this tree-wide ^0.18.2 pin changes no executed code; `npm run lint` is what must be re-run if it moves. katex is NOT a direct dependency, so there is no lockstep duplicate range.",
154
+ "overrides.re2js": "Clears GHSA-gg6h-894w-4m9c (high — quadratic-time denial of service in lookbehind matching, vulnerable >=2.2.0 <=2.8.6). re2js reaches the tree only through markdownlint, which declares an EXACT re2js 2.8.6 even in its latest release, so neither a lockfile-only resolution nor a parent bump reaches the fix; `npm audit fix --force` would instead downgrade markdownlint-cli2 to 0.23.x and break the overrides above. This tree-wide ^2.8.7 pin stays on the 2.x major; `npm run lint` is what must be re-run if it moves. Drop it once markdownlint declares re2js >= 2.8.7. re2js is NOT a direct dependency, so there is no lockstep duplicate range."
154
155
  },
155
156
  "overrides": {
156
157
  "js-yaml": "^5.4.3",
157
158
  "markdown-it": "^15.0.3",
158
159
  "smol-toml": "^1.9.1",
159
- "katex": "^0.18.2"
160
+ "katex": "^0.18.2",
161
+ "re2js": "^2.8.7"
160
162
  }
161
163
  }