mandrel 2.120.0 → 2.121.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 (32) hide show
  1. package/.agents/agents/acceptance-critic.md +4 -0
  2. package/.agents/agents/story-worker.md +1 -1
  3. package/.agents/docs/agentrc-reference.json +1 -0
  4. package/.agents/docs/configuration.md +1 -0
  5. package/.agents/schemas/acceptance-eval-verdict.schema.json +6 -1
  6. package/.agents/schemas/agentrc.schema.json +9 -0
  7. package/.agents/scripts/acceptance-eval.js +125 -13
  8. package/.agents/scripts/evidence-gate.js +15 -2
  9. package/.agents/scripts/lib/baselines/crap-preview-scan.js +1 -0
  10. package/.agents/scripts/lib/baselines/git-base.js +43 -0
  11. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +29 -5
  12. package/.agents/scripts/lib/baselines/kinds/crap.js +7 -1
  13. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +81 -52
  14. package/.agents/scripts/lib/close-validation/projections/advisories.js +1 -0
  15. package/.agents/scripts/lib/close-validation/projections/crap.js +3 -0
  16. package/.agents/scripts/lib/config/gates/crap.schema.js +7 -0
  17. package/.agents/scripts/lib/config/quality.js +13 -6
  18. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  19. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +65 -6
  20. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +34 -2
  21. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +7 -2
  22. package/.agents/scripts/lib/orchestration/handoff-gates.js +2 -0
  23. package/.agents/scripts/lib/orchestration/preflight-lanes.js +2 -0
  24. package/.agents/scripts/lib/orchestration/ticket-validator.js +35 -0
  25. package/.agents/scripts/lib/orchestration/verify-credit.js +144 -0
  26. package/.agents/scripts/lib/validation-evidence.js +27 -0
  27. package/.agents/workflows/helpers/acceptance-self-eval.md +9 -1
  28. package/.agents/workflows/helpers/deliver-digest.md +7 -8
  29. package/.agents/workflows/helpers/deliver-story-reference.md +1 -1
  30. package/.agents/workflows/helpers/plan-reference.md +3 -1
  31. package/docs/CHANGELOG.md +15 -0
  32. package/package.json +1 -1
@@ -9,6 +9,7 @@ import { createHash } from 'node:crypto';
9
9
  import { readFileSync } from 'node:fs';
10
10
 
11
11
  import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
12
+ import { normalizeVerifyCommand } from './verify-credit.js';
12
13
 
13
14
  const EPIC_SIGNALS_BASENAME = 'signals.ndjson';
14
15
 
@@ -55,11 +56,52 @@ function partitionCriteria(criteria) {
55
56
  return { metCount, notMet };
56
57
  }
57
58
 
59
+ /**
60
+ * Fold the gate's own verify runs into the verdict: a criterion citing a
61
+ * failed run without a `waiver` is scored `unmet`, whatever it self-reported.
62
+ *
63
+ * @param {{ criteria?: Array<object> }} verdict
64
+ * @param {Array<{ command: string, exitCode: number|null, outcome: string, deadPaths?: string[] }>} [verifyRuns]
65
+ * @returns {{ criteria: Array<object>, verifyRuns: Array<object> }}
66
+ */
67
+ export function scoreVerifyRuns(verdict, verifyRuns = []) {
68
+ const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
69
+ const cites = (c) =>
70
+ (c?.verifyEvidence ?? []).map((item) => ({
71
+ command: normalizeVerifyCommand(item?.command),
72
+ waived: typeof item?.waiver === 'string' && item.waiver.length > 0,
73
+ }));
74
+ const runs = verifyRuns.map((run) => ({
75
+ ...run,
76
+ waived: criteria.some((c) =>
77
+ cites(c).some((i) => i.waived && i.command === run.command),
78
+ ),
79
+ }));
80
+ const failed = new Map(
81
+ runs.filter((r) => r.outcome !== 'pass').map((r) => [r.command, r]),
82
+ );
83
+ const scored = criteria.map((c) => {
84
+ const hit = cites(c).find((i) => !i.waived && failed.has(i.command));
85
+ if (!hit) return c;
86
+ const run = failed.get(hit.command);
87
+ const why = run.deadPaths?.length
88
+ ? `selects no test file at ${run.deadPaths.join(', ')}`
89
+ : `exited ${run.exitCode ?? 'without a code (timeout or spawn failure)'}`;
90
+ return {
91
+ ...c,
92
+ verdict: 'unmet',
93
+ evidence: `gate run of \`${run.command}\` ${why}; ${c.evidence ?? ''}`,
94
+ };
95
+ });
96
+ return { criteria: scored, verifyRuns: runs };
97
+ }
98
+
58
99
  /**
59
100
  * @param {object} args
60
101
  * @param {{ criteria?: Array<object> }} args.verdict Its own `round` is ignored.
61
102
  * @param {number} args.maxRounds
62
103
  * @param {number} [args.round] From `resolveAcceptanceEvalRound`.
104
+ * @param {Array<object>} [args.verifyRuns] The gate's own scoped runs.
63
105
  * @returns {{
64
106
  * decision: 'proceed' | 'redraft' | 'block',
65
107
  * round: number,
@@ -70,10 +112,17 @@ function partitionCriteria(criteria) {
70
112
  * capReached: boolean,
71
113
  * }}
72
114
  */
73
- export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
115
+ export function decideAcceptanceEval({
116
+ verdict,
117
+ maxRounds,
118
+ round: roundIn,
119
+ verifyRuns = [],
120
+ }) {
74
121
  const cap = effectiveCap(maxRounds);
75
122
  const round = Number.isInteger(roundIn) && roundIn >= 1 ? roundIn : 1;
76
- const { metCount, notMet } = partitionCriteria(verdict?.criteria);
123
+ const { metCount, notMet } = partitionCriteria(
124
+ scoreVerifyRuns(verdict, verifyRuns).criteria,
125
+ );
77
126
  const totalCriteria = metCount + notMet.length;
78
127
  const allMet = notMet.length === 0;
79
128
  const capReached = round >= cap;
@@ -205,14 +254,24 @@ function readPriorAcceptanceEvalRecords({
205
254
  return records;
206
255
  }
207
256
 
257
+ /** No gate inputs hashes the verdict alone, keeping recorded fingerprints. */
258
+ function withGateInputs(canonical, { verifyRuns = [], headSha = null } = {}) {
259
+ const runs = verifyRuns.map((r) => [r.command, r.outcome]);
260
+ return runs.length > 0 || headSha
261
+ ? { canonical, runs, head: headSha }
262
+ : canonical;
263
+ }
264
+
208
265
  /**
209
- * Hashes only what the decision depends on, so an unchanged evaluation
210
- * fingerprints the same and real rework does not.
266
+ * Hashes only what the decision depends on — the verdict, the gate's real
267
+ * verify outcomes and HEAD — so an unchanged evaluation fingerprints the same
268
+ * and real rework does not.
211
269
  *
212
270
  * @param {{ criteria?: Array<object> }} verdict
271
+ * @param {{ verifyRuns?: Array<{ command: string, outcome: string }>, headSha?: string|null }} [gate]
213
272
  * @returns {string}
214
273
  */
215
- export function computeVerdictFingerprint(verdict) {
274
+ export function computeVerdictFingerprint(verdict, gate) {
216
275
  const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
217
276
  const canonical = criteria.map((c) => [
218
277
  Number.isInteger(c?.index) ? c.index : null,
@@ -221,7 +280,7 @@ export function computeVerdictFingerprint(verdict) {
221
280
  typeof c?.evidence === 'string' ? c.evidence : '',
222
281
  ]);
223
282
  return createHash('sha256')
224
- .update(JSON.stringify(canonical))
283
+ .update(JSON.stringify(withGateInputs(canonical, gate)))
225
284
  .digest('hex')
226
285
  .slice(0, 16);
227
286
  }
@@ -7,8 +7,12 @@
7
7
 
8
8
  import { decodeEnvelope } from '../../../baselines/codec.js';
9
9
  import { EXIT_CONFIG } from '../../../baselines/exit-codes.js';
10
- import { readBaseFromGit } from '../../../baselines/git-base.js';
10
+ import {
11
+ readBaseFromGit,
12
+ readRenamesFromGit,
13
+ } from '../../../baselines/git-base.js';
11
14
  import { getKindModule } from '../../../baselines/kernel.js';
15
+ import { canonicalizeBaselinePath } from '../../../baselines/path-canon.js';
12
16
  import { resolveScope } from '../../../baselines/scope.js';
13
17
  import { Logger } from '../../../Logger.js';
14
18
  import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
@@ -71,6 +75,27 @@ function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
71
75
  }
72
76
  }
73
77
 
78
+ /** Git renames since the base ref, keyed by canonical baseline path. */
79
+ function canonicalRenames(ref, cwd) {
80
+ const out = new Map();
81
+ for (const [to, from] of readRenamesFromGit(ref, { cwd })) {
82
+ out.set(canonicalizeBaselinePath(to), canonicalizeBaselinePath(from));
83
+ }
84
+ return out;
85
+ }
86
+
87
+ /**
88
+ * The compare's third argument: renames for every kind, and the coverage
89
+ * `*` floor as the minimum a new file must meet.
90
+ */
91
+ function compareOptionsFor(kind, gateBlock, scope, cwd) {
92
+ const floor = gateBlock?.floors?.['*'];
93
+ return {
94
+ renames: canonicalRenames(scope.ref, cwd),
95
+ newFileMinimum: kind === 'coverage' && floor ? floor : null,
96
+ };
97
+ }
98
+
74
99
  export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
75
100
  if (scope.mode !== 'diff' || !scope.ref) return emptyCompareResult(null);
76
101
  const basePayload = readBaseBaselinePayload(scope, kind, gateBlock, cwd);
@@ -79,7 +104,13 @@ export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
79
104
  if (typeof kindModule.compare !== 'function') {
80
105
  return emptyCompareResult(scope.ref);
81
106
  }
82
- return { baseRef: scope.ref, baseRead: true, basePayload, kindModule };
107
+ return {
108
+ baseRef: scope.ref,
109
+ baseRead: true,
110
+ basePayload,
111
+ kindModule,
112
+ compareOptions: compareOptionsFor(kind, gateBlock, scope, cwd),
113
+ };
83
114
  }
84
115
 
85
116
  /**
@@ -119,6 +150,7 @@ export function runCompareStage(headBaseline, cmp) {
119
150
  const result = cmp.kindModule.compare(
120
151
  { rows: headBaseline.rows },
121
152
  { rows: baseRows },
153
+ cmp.compareOptions,
122
154
  );
123
155
  return {
124
156
  regressions: result?.regressions ?? [],
@@ -43,7 +43,7 @@ function formatRemedyLine(g) {
43
43
  const fmt = (n) => String(Number(n.toFixed(2)));
44
44
 
45
45
  /** `<field> <base> → <head>` per numeric field that moved; `(new)` without a base. */
46
- function formatRegressionLine({ key, head, base }) {
46
+ function formatRegressionLine({ key, head, base, renamedFrom, newFile }) {
47
47
  const numeric = Object.entries(head ?? {}).filter(
48
48
  ([, v]) => typeof v === 'number',
49
49
  );
@@ -54,7 +54,12 @@ function formatRegressionLine({ key, head, base }) {
54
54
  const moved = numeric
55
55
  .filter(([f, v]) => typeof base[f] === 'number' && base[f] !== v)
56
56
  .map(([f, v]) => `${f} ${fmt(base[f])} → ${fmt(v)}`);
57
- return ` · ${key}: ${moved.join(', ')}`;
57
+ return ` · ${regressionLabel(key, renamedFrom, newFile)}: ${moved.join(', ')}`;
58
+ }
59
+
60
+ function regressionLabel(key, renamedFrom, newFile) {
61
+ if (renamedFrom) return `${key} (renamed from ${renamedFrom})`;
62
+ return newFile ? `${key} (new, under the minimum)` : key;
58
63
  }
59
64
 
60
65
  function formatRegressionLines(g) {
@@ -22,6 +22,7 @@ import {
22
22
  } from '../coverage-deferral.js';
23
23
  import { quoteFailureRows } from '../failure-rows.js';
24
24
  import {
25
+ assertCleanTree,
25
26
  hashCommandConfig,
26
27
  recordPass,
27
28
  treeFingerprint,
@@ -153,6 +154,7 @@ export function recordPreflightCredit(ctx, check) {
153
154
  /** Re-key one credit onto the seated HEAD; best-effort, like close's rerun. */
154
155
  export function carryCredit(ctx, gateName, credit) {
155
156
  try {
157
+ assertCleanTree(ctx.cwd, ctx.git);
156
158
  recordPass(
157
159
  {
158
160
  storyId: ctx.storyId,
@@ -12,6 +12,7 @@ import {
12
12
  SUITE_RESERVATION_ENV,
13
13
  } from '../full-suite-lock.js';
14
14
  import {
15
+ assertCleanTree,
15
16
  hashCommandConfig,
16
17
  recordPass,
17
18
  shouldSkip,
@@ -190,6 +191,7 @@ function reconcileDeposit(ctx, check) {
190
191
  const opts = { cwd: ctx.evidenceCwd, standalone: true };
191
192
  const key = { storyId: ctx.storyId, gateName: check.key, configHash };
192
193
  try {
194
+ assertCleanTree(ctx.cwd, ctx.git);
193
195
  if (shouldSkip({ ...key, currentSha: ctx.head }, opts).skip) return;
194
196
  recordPass(
195
197
  {
@@ -253,6 +253,38 @@ function assertEveryStoryHasInlineContract({ stories }) {
253
253
  );
254
254
  }
255
255
 
256
+ const QUOTED_RE = /'[^']*'|"(?:\\.|[^"\\])*"/g;
257
+ const DISCARD_RE = /\|\|\s*(?:true|:|break|continue)(?=\s*(?:$|;|done\b|\)))/m;
258
+ const LOOP_RE = /(?:^|[;&|(]|\bdo|\bthen)\s*(?:for|while|until)\s/m;
259
+ const FAILING_EXIT_RE = /\bexit\s+(?:[1-9]\d*|\$\?)/;
260
+
261
+ /**
262
+ * True when a verify command can exit 0 after its check failed: a failure
263
+ * branch that discards status, or a loop (status = last iteration's) with no
264
+ * failing `exit`. Quoted strings are ignored. `|| echo …` passes on purpose.
265
+ *
266
+ * @param {string} entry
267
+ * @returns {boolean}
268
+ */
269
+ function discardsExitStatus(entry) {
270
+ const code = String(entry ?? '').replace(QUOTED_RE, "''");
271
+ if (DISCARD_RE.test(code)) return true;
272
+ return LOOP_RE.test(code) && !FAILING_EXIT_RE.test(code);
273
+ }
274
+
275
+ function assertVerifyKeepsExitStatus({ stories }) {
276
+ const offenders = stories.flatMap((s) =>
277
+ (Array.isArray(s.verify) ? s.verify : [])
278
+ .filter((entry) => typeof entry === 'string' && discardsExitStatus(entry))
279
+ .map((entry) => ` - ${s.slug}: ${entry}`),
280
+ );
281
+ if (offenders.length === 0) return;
282
+ throw new Error(
283
+ `Cross-Validation Failed: ${offenders.length} verify[] entry/entries can exit 0 after a failure:\n${offenders.join('\n')}\n\n` +
284
+ 'Fail the entry with `|| exit 1` instead of discarding the status.',
285
+ );
286
+ }
287
+
256
288
  /**
257
289
  * @param {object[]} stories
258
290
  * @returns {string[]}
@@ -347,6 +379,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
347
379
 
348
380
  assertAllTicketsAreStories({ tickets, stories });
349
381
  assertEveryStoryHasInlineContract({ stories });
382
+ assertVerifyKeepsExitStatus({ stories });
350
383
  assertStoryProvenanceShape({ stories });
351
384
  assertNoUnknownDeps({ tickets, ticketBySlug });
352
385
 
@@ -407,6 +440,8 @@ export const _internal = {
407
440
  indexTicketsBySlug,
408
441
  assertAllTicketsAreStories,
409
442
  assertEveryStoryHasInlineContract,
443
+ assertVerifyKeepsExitStatus,
444
+ discardsExitStatus,
410
445
  assertStoryProvenanceShape,
411
446
  assertNoUnknownDeps,
412
447
  assertAcyclic,
@@ -5,6 +5,9 @@
5
5
  * manufactures a pass.
6
6
  */
7
7
 
8
+ import { globSync } from 'node:fs';
9
+
10
+ import { spawnChild } from '../child-exec.js';
8
11
  import { resolveTestGateArgv } from '../close-validation/commands.js';
9
12
  import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
10
13
  import { getQuality, resolveConfig } from '../config-resolver.js';
@@ -258,3 +261,144 @@ export function planVerifyExecution(entries, context, deps = {}) {
258
261
  return { ...resolveVerifyCredit({ ...context, command }, deps), tier };
259
262
  });
260
263
  }
264
+
265
+ const MANUAL_ENTRY = /^manual:/i;
266
+
267
+ const VERIFY_RUN_TIMEOUT_MS = 10 * 60 * 1000;
268
+
269
+ /** Any of these makes an entry compound, so its paths are not probed. */
270
+ const COMPOUND_SHELL = /[;|&<>()`]|\$\(/;
271
+
272
+ /** Flags whose next token is a value, not a test path. */
273
+ const VALUE_FLAGS = new Set([
274
+ '--test-name-pattern',
275
+ '--test-skip-pattern',
276
+ '--test-reporter',
277
+ '--test-reporter-destination',
278
+ '--test-concurrency',
279
+ '--test-timeout',
280
+ '--test-shard',
281
+ '--test-isolation',
282
+ '--test-global-setup',
283
+ '--test-coverage-include',
284
+ '--test-coverage-exclude',
285
+ '--import',
286
+ '--require',
287
+ '-r',
288
+ '--loader',
289
+ '--experimental-loader',
290
+ '--env-file',
291
+ '--conditions',
292
+ '-C',
293
+ '--config',
294
+ '-c',
295
+ '--project',
296
+ '--reporter',
297
+ '--root',
298
+ '--dir',
299
+ '-t',
300
+ '--testNamePattern',
301
+ '--environment',
302
+ '--pool',
303
+ '--shard',
304
+ '--outputFile',
305
+ '--exclude',
306
+ '--maxWorkers',
307
+ '--minWorkers',
308
+ '--testTimeout',
309
+ '--mode',
310
+ '--workspace',
311
+ '--retry',
312
+ ]);
313
+
314
+ /** `parseVerifyEntry` plus collapsed whitespace: the evidence match key. */
315
+ export function normalizeVerifyCommand(entry) {
316
+ return parseVerifyEntry(entry).command.replace(/\s+/g, ' ');
317
+ }
318
+
319
+ /** `required` must be evidenced; `scoped` (not full-suite) is also run. */
320
+ export function classifyVerifyEntries(entries) {
321
+ const required = [
322
+ ...new Set((entries ?? []).map(normalizeVerifyCommand).filter(Boolean)),
323
+ ].filter((command) => !MANUAL_ENTRY.test(command));
324
+ return {
325
+ required,
326
+ scoped: required.filter((command) => !isFullSuiteCommand(command)),
327
+ };
328
+ }
329
+
330
+ const unquote = (token) => token.replace(/^(['"])(.*)\1$/, '$2');
331
+
332
+ /** Runner and test paths of a simple `vitest run` / `node --test`, else null. */
333
+ function extractTestPaths(command) {
334
+ if (COMPOUND_SHELL.test(command)) return null;
335
+ const tokens = command.split(' ').map(unquote);
336
+ let runner = 'node';
337
+ let start = 2;
338
+ if (tokens[0] !== 'node' || tokens[1] !== '--test') {
339
+ const lead = { npx: 1, pnpm: 1, npm: tokens[1] === 'exec' ? 2 : -1 };
340
+ const at = lead[tokens[0]] ?? 0;
341
+ if (at < 0 || tokens[at] !== 'vitest' || tokens[at + 1] !== 'run') {
342
+ return null;
343
+ }
344
+ runner = 'vitest';
345
+ start = at + 2;
346
+ }
347
+ const paths = [];
348
+ for (let i = start; i < tokens.length; i += 1) {
349
+ if (!tokens[i].startsWith('-')) paths.push(tokens[i]);
350
+ else if (VALUE_FLAGS.has(tokens[i])) i += 1;
351
+ }
352
+ return { runner, paths };
353
+ }
354
+
355
+ /** @param {string} pattern @param {string} cwd @returns {number} */
356
+ function countGlobFiles(pattern, cwd) {
357
+ try {
358
+ return globSync(pattern, { cwd }).length;
359
+ } catch {
360
+ return 0;
361
+ }
362
+ }
363
+
364
+ /** Listed lines count: `vitest list` exits 0 on an empty selection. */
365
+ function countVitestFiles(testPath, cwd) {
366
+ const res = spawnChild('npx', ['vitest', 'list', testPath, '--filesOnly'], {
367
+ cwd,
368
+ shell: process.platform === 'win32',
369
+ timeout: VERIFY_RUN_TIMEOUT_MS,
370
+ });
371
+ return String(res.stdout ?? '')
372
+ .split('\n')
373
+ .filter((line) => line.trim().length > 0).length;
374
+ }
375
+
376
+ /** Output goes to stderr so stdout stays one envelope; null on timeout. */
377
+ function spawnVerifyCommand(command, cwd) {
378
+ const res = spawnChild(command, [], {
379
+ cwd,
380
+ shell: true,
381
+ stdio: ['ignore', 2, 2],
382
+ timeout: VERIFY_RUN_TIMEOUT_MS,
383
+ });
384
+ return Number.isInteger(res.status) ? res.status : null;
385
+ }
386
+
387
+ /** Run one scoped entry in `cwd`; a dead test path fails it unspawned. */
388
+ export function runScopedVerifyEntry(command, { cwd }, deps = {}) {
389
+ const {
390
+ spawnImpl = spawnVerifyCommand,
391
+ listVitestImpl = countVitestFiles,
392
+ globImpl = countGlobFiles,
393
+ } = deps;
394
+ const selection = extractTestPaths(command);
395
+ const count = selection?.runner === 'vitest' ? listVitestImpl : globImpl;
396
+ const deadPaths = (selection?.paths ?? []).filter((p) => count(p, cwd) < 1);
397
+ const exitCode = deadPaths.length > 0 ? null : spawnImpl(command, cwd);
398
+ return {
399
+ command,
400
+ exitCode,
401
+ outcome: exitCode === 0 ? 'pass' : 'fail',
402
+ deadPaths,
403
+ };
404
+ }
@@ -254,6 +254,33 @@ export function treeFingerprint(cwd, gitSpawnFn) {
254
254
  }
255
255
  }
256
256
 
257
+ /**
258
+ * Why evidence must be bypassed — the tree differs from HEAD, or the probe
259
+ * failed — or `null` on a clean tree. Gitignored files are not counted.
260
+ */
261
+ export function dirtyTreeReason(cwd, gitSpawnFn) {
262
+ let res;
263
+ try {
264
+ res = gitSpawnFn(cwd, 'status', '--porcelain', '--untracked-files=normal');
265
+ } catch {
266
+ res = null;
267
+ }
268
+ if (res?.status !== 0) return 'git status probe failed';
269
+ // The runner trims stdout: strip the status code by shape, not width.
270
+ const paths = (res.stdout || '')
271
+ .split(/\r?\n/)
272
+ .map((line) => line.replace(/^\s*[ MADRCUT?!]{1,2}\s/, '').trim())
273
+ .filter(Boolean);
274
+ if (paths.length === 0) return null;
275
+ return `tree differs from HEAD: ${paths[0]}, ${paths.length} changed path(s)`;
276
+ }
277
+
278
+ /** Throws the {@link dirtyTreeReason} when evidence must not be recorded. */
279
+ export function assertCleanTree(cwd, gitSpawnFn) {
280
+ const reason = dirtyTreeReason(cwd, gitSpawnFn);
281
+ if (reason) throw new Error(reason);
282
+ }
283
+
257
284
  /**
258
285
  * Skip only when gate and config hash match and either the SHA or a non-empty
259
286
  * input fingerprint matches; otherwise `reason` says why not.
@@ -112,9 +112,17 @@ per-criterion, mid-delivery, and evaluates the actual work product.
112
112
 
113
113
  ```bash
114
114
  node <main-repo>/.agents/scripts/acceptance-eval.js \
115
- --story <storyId> --verdict <verdict-path>
115
+ --story <storyId> --verdict <verdict-path> --cwd <workCwd>
116
116
  ```
117
117
 
118
+ The gate runs each scoped Story `verify[]` entry itself in `--cwd`
119
+ (full-suite and `manual:` entries are not spawned). Every required entry
120
+ must be cited in some criterion's `verifyEvidence[]`, and a `met`
121
+ criterion over a non-`pass` item needs a `waiver` — both are refused
122
+ before scoring, consuming no round. A criterion citing an entry whose
123
+ gate run fails (non-zero exit, or a test path selecting no file) is
124
+ scored `unmet`.
125
+
118
126
  The gate reads the Story's `acceptance[]` count itself (Story #5313): a
119
127
  verdict whose `criteria[]` length differs — one covering only part of the
120
128
  Story — is rejected **before scoring**, with an error naming the count and
@@ -76,18 +76,17 @@ skeleton — it derives § 3's `files` and `verdictOwner` with the same function
76
76
  `node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId> --init
77
77
  --cwd <workCwd>`
78
78
 
79
- It writes one empty record per `acceptance[]` item and prints its
80
- path. The owner fills **every** record,
81
- scored against that change set with `verify[]` output as evidence, and scores
82
- it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
79
+ It writes one empty record per `acceptance[]` item and prints its path. The
80
+ owner fills **every** record against that change set, `verify[]` output as
81
+ evidence, and scores it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
83
82
  (default 2; `0` scores once with no redraft).
84
83
 
85
84
  `node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId>
86
- --verdict <verdict-path>`
85
+ --verdict <verdict-path> --cwd <workCwd>`
87
86
 
88
- The gate reads the Story's `acceptance[]` count itself and rejects, **before**
89
- scoring and consuming no round, a verdict whose `criteria[]` length differs
90
- or with an unfilled record (naming its indices).
87
+ Refused before scoring (no round): a `criteria[]` length off the
88
+ `acceptance[]` count, an unfilled record, an uncited `verify[]` entry. The
89
+ gate runs scoped entries in `--cwd`.
91
90
 
92
91
  `proceed` → § 5. `redraft` → one more round inside the cap. `block` → **do
93
92
  not close**: post a `friction` comment and flip `agent::blocked`.
@@ -184,7 +184,7 @@ criteria, then transition the Story to `agent::blocked`:
184
184
 
185
185
  ```bash
186
186
  node .agents/scripts/diagnose-friction.js --story <storyId> \
187
- --cmd node .agents/scripts/acceptance-eval.js --story <storyId> --verdict <verdict-path>
187
+ --cmd node .agents/scripts/acceptance-eval.js --story <storyId> --verdict <verdict-path> --cwd <workCwd>
188
188
  node .agents/scripts/update-ticket-state.js --ticket <storyId> --state agent::blocked
189
189
  ```
190
190
 
@@ -381,7 +381,9 @@ half with the second suppressed. Either way every gate runs before the first
381
381
  where the second half is read:
382
382
 
383
383
  **Hard — the run refuses:** a body that does not parse, a ticket that is not
384
- a Story, an empty `acceptance[]`, an unknown or cyclic `depends_on`, the
384
+ a Story, an empty `acceptance[]`, a `verify[]` entry that can exit 0 after a
385
+ failure (`|| true`, `|| :`, `|| break`, `|| continue`, or a loop with no
386
+ failing `exit`; use `|| exit 1`), an unknown or cyclic `depends_on`, the
385
387
  same-wave collision refusal at N>1, a supersede claim on a non-source id or
386
388
  one claimed twice, and a `deletes` entry naming a path absent at base.
387
389
  Commit subjects are not scanned — the `commit-msg` hook and
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,21 @@ 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.121.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.120.0...mandrel-v2.121.0) (2026-11-12)
19
+
20
+
21
+ ### Added
22
+
23
+ * new and renamed files are judged by the coverage gate, and untested new files get the full CRAP check ([#6068](https://github.com/dsj1984/mandrel/issues/6068)) ([#6076](https://github.com/dsj1984/mandrel/issues/6076)) ([b28ce16](https://github.com/dsj1984/mandrel/commit/b28ce16a6d739f94782df6748632cf3952aae989))
24
+ * plan-persist refuses verify entries that discard their exit status ([#6071](https://github.com/dsj1984/mandrel/issues/6071)) ([#6073](https://github.com/dsj1984/mandrel/issues/6073)) ([9fb3ace](https://github.com/dsj1984/mandrel/commit/9fb3ace0e1ca567034050e6485a57d837742e4a9))
25
+ * the acceptance gate runs the Story's scoped verify[] entries itself and refuses a met verdict without passing evidence ([#6067](https://github.com/dsj1984/mandrel/issues/6067)) ([#6077](https://github.com/dsj1984/mandrel/issues/6077)) ([fbe68cd](https://github.com/dsj1984/mandrel/commit/fbe68cd21a7646db46e3efc72200a8c8a3fc4d95))
26
+
27
+
28
+ ### Fixed
29
+
30
+ * evidence-gate neither spends nor records credit when the working tree differs from HEAD ([#6070](https://github.com/dsj1984/mandrel/issues/6070)) ([#6074](https://github.com/dsj1984/mandrel/issues/6074)) ([c0bf74e](https://github.com/dsj1984/mandrel/commit/c0bf74e78e517e859570c37ad9b88e6dfd7ab1e6))
31
+ * handoff's credit re-recorders skip a dirty tree, sharing evidence-gate's probe ([#6078](https://github.com/dsj1984/mandrel/issues/6078)) ([#6079](https://github.com/dsj1984/mandrel/issues/6079)) ([012f305](https://github.com/dsj1984/mandrel/commit/012f305a0a62c1e569f475f7ef17ead9bf8ab08c))
32
+
18
33
  ## [2.120.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.119.0...mandrel-v2.120.0) (2026-11-12)
19
34
 
20
35
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.120.0",
3
+ "version": "2.121.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/",