mandrel 2.120.0 → 2.122.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 (41) hide show
  1. package/.agents/agents/acceptance-critic.md +5 -1
  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/instructions.md +3 -3
  6. package/.agents/schemas/acceptance-eval-verdict.schema.json +6 -1
  7. package/.agents/schemas/agentrc.schema.json +9 -0
  8. package/.agents/scripts/acceptance-eval.js +125 -13
  9. package/.agents/scripts/audit-to-stories.js +21 -0
  10. package/.agents/scripts/evidence-gate.js +15 -2
  11. package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +7 -3
  12. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +18 -1
  13. package/.agents/scripts/lib/baselines/crap-preview-scan.js +1 -0
  14. package/.agents/scripts/lib/baselines/git-base.js +43 -0
  15. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +29 -5
  16. package/.agents/scripts/lib/baselines/kinds/crap.js +7 -1
  17. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +81 -52
  18. package/.agents/scripts/lib/close-validation/projections/advisories.js +1 -0
  19. package/.agents/scripts/lib/close-validation/projections/crap.js +3 -0
  20. package/.agents/scripts/lib/config/gates/crap.schema.js +7 -0
  21. package/.agents/scripts/lib/config/quality.js +13 -6
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  23. package/.agents/scripts/lib/orchestrate/classify.js +30 -14
  24. package/.agents/scripts/lib/orchestrate/inventory.js +10 -6
  25. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +65 -6
  26. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +34 -2
  27. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +7 -2
  28. package/.agents/scripts/lib/orchestration/handoff-gates.js +2 -0
  29. package/.agents/scripts/lib/orchestration/preflight-lanes.js +2 -0
  30. package/.agents/scripts/lib/orchestration/ticket-validator.js +35 -0
  31. package/.agents/scripts/lib/orchestration/verify-credit.js +144 -0
  32. package/.agents/scripts/lib/validation-evidence.js +27 -0
  33. package/.agents/workflows/audit-to-stories.md +6 -3
  34. package/.agents/workflows/helpers/acceptance-self-eval.md +9 -1
  35. package/.agents/workflows/helpers/deliver-digest.md +7 -8
  36. package/.agents/workflows/helpers/deliver-story-reference.md +1 -1
  37. package/.agents/workflows/helpers/plan-reference.md +3 -1
  38. package/.agents/workflows/mandrel-orchestrate.md +4 -0
  39. package/.agents/workflows/memory-consolidate.md +1 -1
  40. package/docs/CHANGELOG.md +27 -0
  41. package/package.json +1 -1
@@ -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
  };
@@ -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.
@@ -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
@@ -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