crysk 0.3.1 → 0.3.3

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 (80) hide show
  1. package/README.md +61 -37
  2. package/dist/SKILL-12as0f3q.md +74 -0
  3. package/dist/SKILL-2h445snn.md +140 -0
  4. package/dist/SKILL-6j27707y.md +140 -0
  5. package/dist/SKILL-6vy283pt.md +140 -0
  6. package/dist/SKILL-816621e5.md +74 -0
  7. package/dist/SKILL-bnh7nrjz.md +74 -0
  8. package/dist/SKILL-ebn0fqaq.md +140 -0
  9. package/dist/SKILL-fv8x6hhx.md +140 -0
  10. package/dist/SKILL-nv32jpc5.md +74 -0
  11. package/dist/SKILL-qnfc8yp3.md +539 -0
  12. package/dist/SKILL-xr56f0b6.md +140 -0
  13. package/dist/SKILL-yz6wk92g.md +542 -0
  14. package/dist/ci-admission-09k2ba89.md +126 -0
  15. package/dist/ci-admission-a6d0wk1c.md +128 -0
  16. package/dist/ci-admission-f19qh39t.md +128 -0
  17. package/dist/ci-admission-tcqsj7b2.md +126 -0
  18. package/dist/cli.js +11544 -10726
  19. package/dist/index.js +1578 -942
  20. package/dist/materiality-f1qwnvg1.md +27 -0
  21. package/dist/review-refuter-btpgnkcd.md +77 -0
  22. package/package.json +3 -2
  23. package/prompts/default/PROVENANCE.md +1 -0
  24. package/prompts/default/review-refuter.md +6 -0
  25. package/prompts/materiality.md +27 -0
  26. package/skills/crysk/SKILL.md +5 -5
  27. package/skills/crysk-ci-setup/SKILL.md +16 -10
  28. package/skills/crysk-ci-setup/references/ci-admission.md +4 -0
  29. package/skills/crysk-loop/SKILL.md +32 -5
  30. package/src/asset-manifest.ts +2 -0
  31. package/src/assets.ts +4 -1
  32. package/src/brand.ts +11 -9
  33. package/src/ci/cli-record.ts +1 -1
  34. package/src/ci/gates.ts +31 -0
  35. package/src/ci/outcome.ts +6 -5
  36. package/src/ci/override.ts +11 -10
  37. package/src/ci/publish.ts +44 -103
  38. package/src/ci/reporter.ts +34 -5
  39. package/src/ci/review-levels.ts +21 -0
  40. package/src/ci/setup.ts +1 -2
  41. package/src/commands/ci-setup.ts +21 -18
  42. package/src/commands/init.ts +21 -12
  43. package/src/commands/post.ts +17 -0
  44. package/src/compare/loop.ts +356 -0
  45. package/src/compare/materiality.ts +266 -0
  46. package/src/compare/noise.ts +166 -0
  47. package/src/diversity/projection.ts +3 -0
  48. package/src/doctor.ts +48 -29
  49. package/src/index.ts +1 -1
  50. package/src/menu-context.ts +1 -1
  51. package/src/model/routing.ts +62 -0
  52. package/src/pr/admission.ts +13 -1
  53. package/src/pr/discovery.ts +17 -5
  54. package/src/pr/inline.ts +15 -1
  55. package/src/pr/plan.ts +5 -0
  56. package/src/pr/post-floor.ts +30 -0
  57. package/src/pr/posting.ts +4 -0
  58. package/src/pr/pr-status.ts +14 -0
  59. package/src/pr/pr.ts +50 -34
  60. package/src/pr/preflight.ts +2 -2
  61. package/src/pr/publish-outcome.ts +4 -0
  62. package/src/pr/review-pr.ts +65 -26
  63. package/src/pr/target.ts +16 -3
  64. package/src/pr/teardown.ts +1 -1
  65. package/src/rereview/prepare.ts +16 -0
  66. package/src/rereview/state.ts +206 -25
  67. package/src/review/boundary.ts +5 -1
  68. package/src/review/dedupe.ts +48 -4
  69. package/src/review/findings.ts +47 -1
  70. package/src/review/materiality-gate.ts +158 -0
  71. package/src/review/pipeline.ts +581 -56
  72. package/src/review/preflight.ts +201 -28
  73. package/src/review/prompt-set.ts +12 -8
  74. package/src/review/report.ts +73 -10
  75. package/src/review/review.ts +30 -5
  76. package/src/review/route-preflight.ts +29 -1
  77. package/src/review/run.ts +56 -18
  78. package/src/ui/config.ts +8 -0
  79. package/src/updater.ts +1 -1
  80. package/src/wizard.ts +35 -9
@@ -5,8 +5,12 @@
5
5
  // the hunts and the refutation themselves.
6
6
 
7
7
  import { existsSync } from "node:fs";
8
- import { chmod, mkdir } from "node:fs/promises";
8
+ import { chmod, mkdir, realpath } from "node:fs/promises";
9
9
  import path from "node:path";
10
+ import {
11
+ type MaterialityVerdict,
12
+ parseJudgeVerdict,
13
+ } from "#compare/materiality";
10
14
  import {
11
15
  defaultEffortForRole,
12
16
  type Effort,
@@ -15,10 +19,14 @@ import {
15
19
  import {
16
20
  agentStepKey,
17
21
  buildResolvedRoutePlan,
22
+ isMeasuredJudgeRoute,
23
+ MATERIALITY_JUDGE_MODEL,
24
+ MATERIALITY_STEP_KEY,
18
25
  type ResolvedModelRoute,
19
26
  type ResolvedRoutePlan,
20
27
  type RoutingConfig,
21
28
  type RunnerBackend,
29
+ resolveMaterialityJudgeRoute,
22
30
  spawnModelForClaudeCli,
23
31
  } from "#model/routing";
24
32
  import {
@@ -33,7 +41,11 @@ import {
33
41
  type WorseningHit,
34
42
  } from "#rereview/classify";
35
43
  import type { RereviewProvenance } from "#rereview/prepare";
36
- import { assembleLive, type GateRow } from "#rereview/state";
44
+ import {
45
+ assembleLive,
46
+ type GateRow,
47
+ materialityReleasedIds,
48
+ } from "#rereview/state";
37
49
  import {
38
50
  assignVerifyIds,
39
51
  closeVerifyQueue,
@@ -84,6 +96,13 @@ import {
84
96
  type RunSummary,
85
97
  type SkillOutput,
86
98
  } from "#review/findings";
99
+ import {
100
+ applyMaterialityVerdicts,
101
+ codeWindow,
102
+ isSafetyProtected,
103
+ materialityCandidates,
104
+ renderMaterialityPrompt,
105
+ } from "#review/materiality-gate";
87
106
  import {
88
107
  parseAgentFile,
89
108
  parseAgentSource,
@@ -159,7 +178,12 @@ import { type SessionUsage, sumUsage, zeroUsage } from "../usage";
159
178
  // preflight and not a runtime dependency on it (the same seam review/size-gate.ts
160
179
  // already uses for NumstatFile).
161
180
  import type { ConfigSources, LocalConfig } from "./preflight";
162
- import { agentFilePath, gotchasUnusableReason } from "./preflight";
181
+ import {
182
+ agentFilePath,
183
+ gotchasUnusableReason,
184
+ NO_REVIEW_INSTRUCTIONS,
185
+ ownerPolicyText,
186
+ } from "./preflight";
163
187
  import {
164
188
  capScoutLeads,
165
189
  renderLeadsBlock,
@@ -203,7 +227,10 @@ export interface PipelineInput {
203
227
  ref?: string;
204
228
  found: boolean;
205
229
  };
206
- gotchasPath: string;
230
+ // Undefined: the repo has no REVIEW.md or gotchas file, and the review runs
231
+ // with NO_REVIEW_INSTRUCTIONS in the block (odd/tasks/review-md.md S3). A
232
+ // path whose file is missing still reads as empty and aborts below.
233
+ gotchasPath?: string;
207
234
  agentsDir: string;
208
235
  // Logical agent filename -> readable path, present only when the prompt set
209
236
  // is the compiled binary's BUNDLED one, where every prompt is embedded at a
@@ -262,6 +289,20 @@ export interface PipelineInput {
262
289
  // (`enabled: false`, `status: "skipped"`), the scout's rule, so the two
263
290
  // arms are told apart from the artifact alone.
264
291
  consolidate?: { promptPath: string; model?: string };
292
+ // Optional engine-owned materiality gate (odd/tasks/materiality-gate.md):
293
+ // an isolated judge reads every finding that would post as blocking and
294
+ // demotes the immaterial ones to advisory. ABSENT means no judge step and
295
+ // findings exactly as before (the scout's rule); pipeline.json still
296
+ // carries a `materiality` record (`enabled: false`, `status: "skipped"`).
297
+ // No `model` seat on purpose: the judge is pinned to the model it was
298
+ // measured on (MATERIALITY_JUDGE_MODEL), and neither `--model` nor a
299
+ // frontmatter edit may move it.
300
+ materiality?: { promptPath: string };
301
+ // The PR title the materiality judge reads (S9): PrTarget.title in PR mode,
302
+ // the reviewed head's commit subject in local mode. Author-controlled, so
303
+ // the judge receives it wrapped as untrusted data. Absent or blank renders
304
+ // MATERIALITY_TITLE_FALLBACK. Read by no other step.
305
+ prTitle?: string;
265
306
  // `--shared-prefix` (opt-in, off by default). Each hunter's system prompt
266
307
  // becomes the patch and output contract, which is byte-identical across
267
308
  // hunters that share settings, and its role moves to the user message. A
@@ -1157,6 +1198,35 @@ interface ConsolidationRecord {
1157
1198
  duration_ms: number;
1158
1199
  }
1159
1200
 
1201
+ // pipeline.json's `materiality` key, written on every run for ScoutRecord's
1202
+ // reason: "the key is missing" is indistinguishable from "this run predates
1203
+ // the key". "skipped" means the gate was not asked for; "ceiling" means it was
1204
+ // asked for and the pipeline ceiling (or its budget) stood it down before it
1205
+ // spawned; "unsupported_route" means the judge would not have run the
1206
+ // measured model through the Claude Code CLI, so it never spawned (S14); "ran"
1207
+ // means candidates were selected and every judgeable one was sent. In every
1208
+ // road but "ran" no finding is demoted.
1209
+ interface MaterialityRecord {
1210
+ enabled: boolean;
1211
+ status: "skipped" | "ran" | "unsupported_route" | "ceiling";
1212
+ reason?: string;
1213
+ // Steps actually spawned, one per judged finding.
1214
+ judged: number;
1215
+ // Findings the judge labelled immaterial: the ones finish() demotes.
1216
+ demoted: number;
1217
+ // Blocking findings the safety guard kept away from the judge.
1218
+ protected: number;
1219
+ // Spawned steps with no usable verdict (step failed, output unparsable,
1220
+ // runner threw). Each one stays blocking (S6).
1221
+ failed: number;
1222
+ // Findings whose content carried the boundary nonce, so no safe prompt
1223
+ // could be composed. Never spawned, stay blocking.
1224
+ skipped_unsafe: number;
1225
+ model?: string;
1226
+ prompt_sha256?: string;
1227
+ duration_ms: number;
1228
+ }
1229
+
1160
1230
  // Mutated as steps complete so the pipeline-ceiling path can assemble
1161
1231
  // whatever exists at the moment the ceiling fires.
1162
1232
  interface RunState {
@@ -1174,6 +1244,15 @@ interface RunState {
1174
1244
  // applies it; the ceiling path reaches finish() without one and so never
1175
1245
  // consolidates.
1176
1246
  consolidationPlan?: PlanEntry[];
1247
+ materiality?: MaterialityRecord;
1248
+ // Set only by a materiality step leg that settled, keyed by finding id.
1249
+ // finish() applies it after the consolidation plan; a finding with no entry
1250
+ // (not judged, failed, unsafe) keeps the tier finish() derived.
1251
+ materialityVerdicts?: Map<string, MaterialityVerdict>;
1252
+ // The findings finish() returns, set just before it writes pipeline.json, so
1253
+ // fillRereviewProvenance can record which priors a materiality demotion
1254
+ // released. Absent on every road that writes no findings.
1255
+ finalFindings?: Finding[];
1177
1256
  // When the pipeline ceiling will fire (epoch ms). Set once in runPipeline;
1178
1257
  // runConsolidation reads it to refuse a spawn that could outlive it.
1179
1258
  ceilingDeadlineMs?: number;
@@ -1184,6 +1263,12 @@ interface RunState {
1184
1263
  // Optional only because the pipeline ceiling can fire before `execute` got
1185
1264
  // that far — a run that never selected a nonce also never composed a prompt.
1186
1265
  boundaryNonce?: string;
1266
+ // The review-instructions text the hunters got (REVIEW.md, gotchas, or
1267
+ // NO_REVIEW_INSTRUCTIONS), set beside the nonce. The refuter and verifier
1268
+ // bodies render it into their `{{GOTCHAS}}` anchor as repository facts
1269
+ // (odd/tasks/review-md.md S5): owner context for the counterexample hunt,
1270
+ // never a posting policy — that belongs to the materiality judge.
1271
+ reviewInstructions?: string;
1187
1272
  parityFired: boolean;
1188
1273
  hunterCount: number;
1189
1274
  hunterFailures: number;
@@ -1399,12 +1484,14 @@ async function execute(
1399
1484
  deps: PipelineDeps,
1400
1485
  state: RunState,
1401
1486
  ): Promise<PipelineResult> {
1402
- // Step 2 — gotchas fail-loud. Gotchas that are missing, empty, or still the
1403
- // untouched scaffold are a deliberate, visible failure signal: run_status
1404
- // "partial" with zero findings is distinguishable from a legitimate
1405
- // "hunters ran, found nothing" complete run. Never silently proceed as if
1406
- // gotchas were simply empty — no step is spawned. sessionFailed stays
1407
- // false: no hunter FAILED, none ever ran.
1487
+ // Step 2 — gotchas fail-loud. A review-instructions file (REVIEW.md or
1488
+ // gotchas) that is missing, empty, or still the untouched scaffold is a
1489
+ // deliberate, visible failure signal: run_status "partial" with zero findings
1490
+ // is distinguishable from a legitimate "hunters ran, found nothing" complete
1491
+ // run. Never silently proceed as if it were simply empty — no step is
1492
+ // spawned. sessionFailed stays false: no hunter FAILED, none ever ran. No
1493
+ // path at all is different: the repo has no such file, which is an opt-out,
1494
+ // not an unfinished setup, and the hunters get NO_REVIEW_INSTRUCTIONS.
1408
1495
  //
1409
1496
  // The scaffold arm is not a nicety: `gotchas.trim().length === 0` passed
1410
1497
  // every file `init`/`setup` writes, so the run this abort exists to prevent
@@ -1412,8 +1499,11 @@ async function execute(
1412
1499
  // reporting clean — was the DEFAULT outcome right after onboarding.
1413
1500
  // `gotchasUnusableReason` is shared with the CLI and doctor so the four
1414
1501
  // gates cannot drift apart again.
1415
- const gotchasFile = Bun.file(input.gotchasPath);
1416
- const gotchas = (await gotchasFile.exists()) ? await gotchasFile.text() : "";
1502
+ let gotchas = NO_REVIEW_INSTRUCTIONS;
1503
+ if (input.gotchasPath !== undefined) {
1504
+ const gotchasFile = Bun.file(input.gotchasPath);
1505
+ gotchas = (await gotchasFile.exists()) ? await gotchasFile.text() : "";
1506
+ }
1417
1507
  if (gotchasUnusableReason(gotchas) !== undefined) {
1418
1508
  // The plan is still written, and that is not tidiness — `writePipelinePlan`
1419
1509
  // is the ONLY caller of `fillRereviewProvenance`, and that is the only
@@ -1555,6 +1645,9 @@ async function execute(
1555
1645
  defaultModel: DEFAULT_CONSOLIDATE_MODEL,
1556
1646
  },
1557
1647
  }),
1648
+ ...(input.materiality === undefined
1649
+ ? {}
1650
+ : { materiality: true as const }),
1558
1651
  });
1559
1652
  } catch (error) {
1560
1653
  // Spec: legacy Claude-only runs without operator routing keep today's
@@ -1660,6 +1753,7 @@ async function execute(
1660
1753
  renderPriorsBlock(input.suspicionPriors),
1661
1754
  ]);
1662
1755
  state.boundaryNonce = boundaryNonce;
1756
+ state.reviewInstructions = gotchas;
1663
1757
 
1664
1758
  const stepsDir = path.join(input.runDir, "steps");
1665
1759
 
@@ -2299,6 +2393,16 @@ async function execute(
2299
2393
  }
2300
2394
  state.consolidation ??= skippedConsolidation(input);
2301
2395
 
2396
+ // Step 6c — the materiality gate, over exactly the blocking findings
2397
+ // finish() will post (post-refuter, post-consolidation). HERE and never
2398
+ // inside finish(): finish() is also the ceiling's landing zone, and a
2399
+ // landing zone that spawns would bill a run already reported finished.
2400
+ // The verdicts ride on state; finish() applies whatever settled.
2401
+ if (input.materiality !== undefined && !ceilingAborted(deps, state)) {
2402
+ await runMaterialityJudge(input, deps, state, stepsDir, boundaryNonce);
2403
+ }
2404
+ state.materiality ??= skippedMateriality(input, state);
2405
+
2302
2406
  // Steps 7 + 8 live in finish(), shared with the ceiling path.
2303
2407
  return finish(input, state);
2304
2408
  }
@@ -2351,10 +2455,18 @@ async function runRefuter(
2351
2455
  // One shared body, written once: every step is the same agent asked about a
2352
2456
  // different finding.
2353
2457
  const systemPromptPath = path.join(options.stepsDir, "refuter.system.md");
2354
- // The refuter body carries no {{PRIORS}}/{{GOTCHAS}} anchors — written
2355
- // as-is under the preamble, same audit-artifact role as the hunter system
2356
- // prompts.
2357
- await writeSystemPrompt(systemPromptPath, agent.body);
2458
+ // The refuter body may anchor `{{GOTCHAS}}` (the bundled one does): it is
2459
+ // rendered with the same instructions text and nonce the hunters got. It
2460
+ // carries no `{{PRIORS}}` — suspicion priors steer the hunt, not a verdict —
2461
+ // so priors are passed empty. A body without anchors is written unchanged.
2462
+ await writeSystemPrompt(
2463
+ systemPromptPath,
2464
+ renderAgentBody(agent.body, {
2465
+ priors: [],
2466
+ gotchas: state.reviewInstructions ?? NO_REVIEW_INSTRUCTIONS,
2467
+ nonce: options.nonce,
2468
+ }),
2469
+ );
2358
2470
  const model = resolveModel(
2359
2471
  input,
2360
2472
  options.agent.model,
@@ -2577,7 +2689,15 @@ async function runVerify(
2577
2689
  agentPromptPath(input, options.agent.file),
2578
2690
  );
2579
2691
  const systemPromptPath = path.join(options.stepsDir, "verifier.system.md");
2580
- await writeSystemPrompt(systemPromptPath, agent.body);
2692
+ // Same body as the refuter, so the same render (see runRefuter).
2693
+ await writeSystemPrompt(
2694
+ systemPromptPath,
2695
+ renderAgentBody(agent.body, {
2696
+ priors: [],
2697
+ gotchas: state.reviewInstructions ?? NO_REVIEW_INSTRUCTIONS,
2698
+ nonce: options.nonce,
2699
+ }),
2700
+ );
2581
2701
  const model = resolveModel(
2582
2702
  input,
2583
2703
  options.agent.model,
@@ -3363,21 +3483,347 @@ async function runConsolidation(
3363
3483
  record.duration_ms = Date.now() - startedAt;
3364
3484
  }
3365
3485
 
3366
- // Steps 7 + 8: map verdicts, assign tiers, assemble the SkillOutput draft and
3367
- // write pipeline.json. Also the ceiling path's landing zone — it dedupes
3368
- // whatever hunters completed so even a truncated run emits canonical ids.
3369
- async function finish(
3486
+ // The judge's budgets. A judgment is one short JSON object over a claim and a
3487
+ // 51-line window with no tools, so a step that needs more than three minutes
3488
+ // is stuck, not thinking. Two attempts, the consolidation pass's count: a
3489
+ // transient failure gets one retry, and a judge that still cannot answer
3490
+ // leaves the finding blocking (S6) rather than holding the run.
3491
+ const MATERIALITY_TIMEOUT_MS = 3 * 60 * 1000;
3492
+ const MATERIALITY_MAX_ATTEMPTS = 2;
3493
+ // The per-agent usage key: one row for the whole fan-out, runAdjudicate's
3494
+ // shape, so `per_agent` stays one entry per stage however many were judged.
3495
+ const MATERIALITY_AGENT = "materiality";
3496
+ export const MATERIALITY_TITLE_FALLBACK = "(title unavailable)";
3497
+ // A source file larger than this is not read for the window: the judge then
3498
+ // sees the claim and path without code, which the prompt already allows for.
3499
+ // It bounds what a hunter-chosen path can pull into a prompt.
3500
+ const MATERIALITY_MAX_FILE_BYTES = 1024 * 1024;
3501
+
3502
+ function skippedMateriality(
3370
3503
  input: PipelineInput,
3371
3504
  state: RunState,
3372
- ): Promise<PipelineResult> {
3505
+ ): MaterialityRecord {
3506
+ const enabled = input.materiality !== undefined;
3507
+ return {
3508
+ // `enabled` reports whether the gate was ASKED for, so a ceiling-cut run
3509
+ // that wanted it reads "enabled, ceiling", never as the flag off.
3510
+ enabled,
3511
+ status: enabled && state.ceilingFired ? "ceiling" : "skipped",
3512
+ judged: 0,
3513
+ demoted: 0,
3514
+ protected: 0,
3515
+ failed: 0,
3516
+ skipped_unsafe: 0,
3517
+ duration_ms: 0,
3518
+ };
3519
+ }
3520
+
3521
+ // The ±25-line window at the reviewed head, or null when it cannot be read
3522
+ // safely. `finding.path` is hunter-written text, and what this reads goes
3523
+ // into a model prompt whose reason may be posted: an absolute path, a `../`
3524
+ // walk or a symlink whose target leaves the worktree is refused, the
3525
+ // threat model of rule 4 applied to a read the driver makes on an agent's
3526
+ // behalf. Any failure is a null window, never a thrown run.
3527
+ async function materialityWindow(
3528
+ worktree: string,
3529
+ relPath: string,
3530
+ line: number,
3531
+ ): Promise<string | null> {
3532
+ if (path.isAbsolute(relPath)) return null;
3533
+ try {
3534
+ const root = await realpath(worktree);
3535
+ const target = await realpath(path.join(root, relPath));
3536
+ const rel = path.relative(root, target);
3537
+ if (
3538
+ rel === "" ||
3539
+ rel === ".." ||
3540
+ rel.startsWith(`..${path.sep}`) ||
3541
+ path.isAbsolute(rel)
3542
+ ) {
3543
+ return null;
3544
+ }
3545
+ const file = Bun.file(target);
3546
+ if (file.size > MATERIALITY_MAX_FILE_BYTES) return null;
3547
+ return codeWindow(await file.text(), line);
3548
+ } catch {
3549
+ return null;
3550
+ }
3551
+ }
3552
+
3553
+ // One isolated judge step per blocking, unprotected finding (S3-S7). The
3554
+ // verdicts land on `state.materialityVerdicts` for finish() to apply.
3555
+ //
3556
+ // NEVER sets `state.partial`, on any road, for the consolidation pass's
3557
+ // reason: the gate is a precision pass, and a judge that failed leaves the
3558
+ // finding exactly as the refuter left it — blocking (S6). The review is
3559
+ // complete; it just posts one more blocker. The failure is still never
3560
+ // silent: the record's `failed`, the step rows and `per_agent.materiality`.
3561
+ async function runMaterialityJudge(
3562
+ input: PipelineInput,
3563
+ deps: PipelineDeps,
3564
+ state: RunState,
3565
+ stepsDir: string,
3566
+ nonce: string,
3567
+ ): Promise<void> {
3568
+ if (!input.materiality) {
3569
+ state.materiality = skippedMateriality(input, state);
3570
+ return;
3571
+ }
3572
+ const startedAt = Date.now();
3573
+ const record: MaterialityRecord = {
3574
+ enabled: true,
3575
+ status: "ran",
3576
+ judged: 0,
3577
+ demoted: 0,
3578
+ protected: 0,
3579
+ failed: 0,
3580
+ skipped_unsafe: 0,
3581
+ model: MATERIALITY_JUDGE_MODEL,
3582
+ duration_ms: 0,
3583
+ };
3584
+ state.materiality = record;
3373
3585
  if (!state.survivors) {
3374
3586
  const { survivors, deduped } = mergeAndDedupe(state.drafts);
3375
3587
  state.survivors = survivors;
3376
3588
  state.deduped = deduped;
3377
3589
  }
3378
- let findings: Finding[] = [];
3590
+ // The list finish() will post, from the same derivation finish() uses.
3591
+ const tiered = tierFindings(state, state.survivors);
3592
+ const { judge, protectedCount } = materialityCandidates(
3593
+ tiered.findings,
3594
+ tiered.protectedIds,
3595
+ );
3596
+ record.protected = protectedCount;
3597
+
3598
+ // S14. A routed run whose plan does not carry a claude-code judge would run
3599
+ // some other model, or nothing at all: a different, unmeasured judge is
3600
+ // worse than no judge, so the stage stands down and every finding keeps
3601
+ // its tier. A run with no route plan is the legacy Claude-only path, where
3602
+ // the step goes to the Claude Code runner exactly as the judge was
3603
+ // measured. A plan WITHOUT the key also stands down rather than spawning a
3604
+ // route-less step inside a routed run: that is a caller that never threaded
3605
+ // the gate into its plan, and the record's reason says so.
3606
+ let route: ResolvedModelRoute | undefined;
3607
+ if (state.routePlan !== undefined) {
3608
+ route = routeForStepKey(state.routePlan, MATERIALITY_STEP_KEY);
3609
+ if (route === undefined || !isMeasuredJudgeRoute(route)) {
3610
+ record.status = "unsupported_route";
3611
+ // A route in hand that fails the check names itself; only a plan with
3612
+ // no judge step asks the config whether the step was left out because
3613
+ // the configured route is not the measured one.
3614
+ record.reason =
3615
+ route !== undefined ||
3616
+ resolveMaterialityJudgeRoute(
3617
+ input.routingConfig ?? input.config?.effective?.routing,
3618
+ ) === undefined
3619
+ ? "judge route is not the measured claude-code route"
3620
+ : "route plan carries no judge step";
3621
+ return;
3622
+ }
3623
+ }
3624
+ if (judge.length === 0) return;
3625
+
3626
+ // The consolidation pass's budget rule: an optional precision pass must
3627
+ // never be the step that turns a complete run partial. One step's worst case
3628
+ // is maxAttempts + the format retry at the full watchdog. The steps are
3629
+ // admitted through the max_concurrent_steps gate, so with a cap they run in
3630
+ // waves of `cap`, and the leg's worst case is one step's worst case per
3631
+ // wave. Only the waves that fit before the ceiling (minus its settle grace)
3632
+ // are judged; findings past them keep their tier, unjudged (fail-open
3633
+ // toward blocking). No wave fits: the gate stands down.
3634
+ const deadline = state.ceilingDeadlineMs;
3635
+ if (deadline !== undefined) {
3636
+ const perWaveMs = MATERIALITY_TIMEOUT_MS * (MATERIALITY_MAX_ATTEMPTS + 1);
3637
+ const budgetMs =
3638
+ deadline - Date.now() - (state.ceilingGraceMs ?? ceilingGraceMs(input));
3639
+ const waves = Math.floor(budgetMs / perWaveMs);
3640
+ if (waves < 1) {
3641
+ record.status = "ceiling";
3642
+ record.reason = "ceiling budget";
3643
+ return;
3644
+ }
3645
+ const cap = input.config?.effective.max_concurrent_steps;
3646
+ if (cap !== undefined && judge.length > waves * cap) {
3647
+ record.reason = `ceiling budget: judged ${waves * cap} of ${judge.length}`;
3648
+ judge.splice(waves * cap);
3649
+ }
3650
+ }
3651
+
3652
+ const systemPromptPath = path.join(stepsDir, "materiality.system.md");
3653
+ // An EMPTY registry, written per run and never `input.mcpConfigPath`: the
3654
+ // judge was measured claims-and-window only, and the hunters' registry
3655
+ // grants codegraph, which would let the judge go read the repository.
3656
+ // Combined with `--strict-mcp-config` (the runner always passes it) this
3657
+ // file is the whole MCP surface the step has.
3658
+ const mcpConfigPath = path.join(stepsDir, "materiality.mcp.json");
3659
+ try {
3660
+ // Read once, hashed and parsed from the same bytes.
3661
+ const raw = await Bun.file(input.materiality.promptPath).text();
3662
+ const agent = parseAgentSource(raw);
3663
+ record.prompt_sha256 = new Bun.CryptoHasher("sha256")
3664
+ .update(raw)
3665
+ .digest("hex");
3666
+ // writeSystemPrompt prepends RUNTIME_PREAMBLE, as for every step.
3667
+ await writeSystemPrompt(systemPromptPath, agent.body);
3668
+ await Bun.write(mcpConfigPath, JSON.stringify({ mcpServers: {} }));
3669
+ await chmod(mcpConfigPath, 0o600);
3670
+ } catch {
3671
+ // A missing or malformed prompt file: nothing is judged, every candidate
3672
+ // stays blocking, and the record says why.
3673
+ record.failed = judge.length;
3674
+ record.reason = "prompt file unreadable";
3675
+ record.duration_ms = Date.now() - startedAt;
3676
+ return;
3677
+ }
3678
+
3679
+ const prTitle =
3680
+ input.prTitle !== undefined && input.prTitle.trim() !== ""
3681
+ ? input.prTitle
3682
+ : MATERIALITY_TITLE_FALLBACK;
3683
+ const effort = defaultEffortForRole("other");
3684
+ const specs: Array<{ id: string; spec: StepSpec; meta: StepMeta }> = [];
3685
+ // The owner's file as posting policy, or undefined when it holds nothing of
3686
+ // the owner's own: template text never reaches the judge (ownerPolicyText).
3687
+ const ownerPolicy =
3688
+ state.reviewInstructions === undefined ||
3689
+ state.reviewInstructions === NO_REVIEW_INSTRUCTIONS
3690
+ ? undefined
3691
+ : ownerPolicyText(state.reviewInstructions);
3692
+ for (const finding of judge) {
3693
+ const prompt = renderMaterialityPrompt(
3694
+ {
3695
+ prTitle,
3696
+ claim: finding.claim,
3697
+ path: finding.path,
3698
+ window: await materialityWindow(
3699
+ input.worktree,
3700
+ finding.path,
3701
+ finding.line,
3702
+ ),
3703
+ // No owner text: no block, so the prompt stays the measured one.
3704
+ ...(ownerPolicy === undefined ? {} : { instructions: ownerPolicy }),
3705
+ },
3706
+ nonce,
3707
+ );
3708
+ // Content that already carries the run's nonce could forge a boundary.
3709
+ // The nonce cannot be re-drawn mid-run, so the finding is not judged and
3710
+ // stays blocking.
3711
+ if (prompt === null) {
3712
+ record.skipped_unsafe++;
3713
+ continue;
3714
+ }
3715
+ const dir = path.join(stepsDir, "materiality", finding.id);
3716
+ await mkdir(dir, { recursive: true });
3717
+ const spec: StepSpec = {
3718
+ name: `materiality-${finding.id}`,
3719
+ systemPromptPath,
3720
+ prompt,
3721
+ // FORCED to empty, never read from the prompt's frontmatter, for the
3722
+ // scout's and the consolidation pass's reason: the judge is measured
3723
+ // without tools, and a guarantee a prompt edit can revoke is not a
3724
+ // guarantee.
3725
+ tools: [],
3726
+ mcpConfigPath,
3727
+ // PINNED, never `input.model` or the frontmatter: the measured judge is
3728
+ // sonnet, and a judge on another model is a different, unmeasured judge
3729
+ // deciding which blockers post.
3730
+ model: MATERIALITY_JUDGE_MODEL,
3731
+ effort,
3732
+ cwd: input.worktree,
3733
+ outPath: path.join(dir, "result.json"),
3734
+ timeoutMs: MATERIALITY_TIMEOUT_MS,
3735
+ maxAttempts: MATERIALITY_MAX_ATTEMPTS,
3736
+ ...(route === undefined ? {} : { route }),
3737
+ parse: parseJudgeVerdict,
3738
+ onRetry: (info) => emit(deps, { kind: "step-retry", ...info }),
3739
+ };
3740
+ specs.push({ id: finding.id, spec, meta: stepMeta(spec) });
3741
+ }
3742
+ record.judged = specs.length;
3743
+ if (specs.length === 0) {
3744
+ record.duration_ms = Date.now() - startedAt;
3745
+ return;
3746
+ }
3747
+ for (const { meta } of specs) state.steps.push(meta);
3748
+ const settled = await Promise.allSettled(
3749
+ specs.map(({ spec }) => deps.runner.run(spec)),
3750
+ );
3751
+ const verdicts = new Map<string, MaterialityVerdict>();
3752
+ let usage: SessionUsage | undefined;
3753
+ let attempts = 0;
3754
+ for (const [i, entry] of specs.entries()) {
3755
+ const outcome = settled[i];
3756
+ const result = outcome?.status === "fulfilled" ? outcome.value : undefined;
3757
+ if (result) {
3758
+ usage = usage ? sumUsage(usage, result.usage) : result.usage;
3759
+ attempts += result.attempts;
3760
+ recordSettlement(entry.meta, result, input.runDir);
3761
+ state.usageTotal = sumUsage(state.usageTotal, result.usage);
3762
+ accumulateUsageV2(state, result);
3763
+ } else {
3764
+ recordStepFailure(
3765
+ entry.meta,
3766
+ outcome?.status === "rejected"
3767
+ ? outcome.reason
3768
+ : "materiality step produced no result",
3769
+ );
3770
+ }
3771
+ if (result?.status === "ok") {
3772
+ const verdict = result.output as MaterialityVerdict;
3773
+ verdicts.set(entry.id, verdict);
3774
+ if (verdict.label === "immaterial") record.demoted++;
3775
+ continue;
3776
+ }
3777
+ record.failed++;
3778
+ }
3779
+ state.perAgent[MATERIALITY_AGENT] = usage
3780
+ ? {
3781
+ tokens_total: usage.tokens_total,
3782
+ duration_ms: Date.now() - startedAt,
3783
+ tokens_in: usage.tokens_in,
3784
+ tokens_out: usage.tokens_out,
3785
+ cost_usd_est: usage.cost_usd_est,
3786
+ attempts,
3787
+ status: record.failed > 0 ? "failed" : "ok",
3788
+ ...(record.failed > 0 ? firstFailureDetail(settled) : {}),
3789
+ }
3790
+ : failedAgentEntry();
3791
+ state.materialityVerdicts = verdicts;
3792
+ record.duration_ms = Date.now() - startedAt;
3793
+ }
3794
+
3795
+ // The findings finish() posts, before root-cause clustering and the
3796
+ // materiality verdicts: tiers derived from the refuter's verdicts, refuted
3797
+ // findings set aside, and the consolidation plan applied when it still
3798
+ // matches. PURE over `state`: it reads, never writes. Two callers need the
3799
+ // exact same list — finish(), and runMaterialityJudge, which must judge the
3800
+ // list that will actually post — and a second copy of this derivation would
3801
+ // be a parallel mechanism able to disagree with the first. What happened to
3802
+ // the plan comes back in `consolidation` for finish() alone to record.
3803
+ interface TieredFindings {
3804
+ findings: Finding[];
3805
+ // Pre-plan count, for a plan that no longer matches.
3806
+ tieredCount: number;
3807
+ refuted: DebugRefutedFinding[];
3808
+ // Ids in `findings` the materiality safety guard must protect: every
3809
+ // pre-plan finding the guard matches, plus every plan primary that folded
3810
+ // one in. Consolidation rewrites the claim and keeps the primary's path, so
3811
+ // a protected source merged into a benign primary would otherwise vanish
3812
+ // from the guard's view (S4) — the guard follows the defect, not its wording.
3813
+ protectedIds: Set<string>;
3814
+ consolidation:
3815
+ | { kind: "none" }
3816
+ | { kind: "mismatch" }
3817
+ | { kind: "applied"; repairs: number; findingsOut: number };
3818
+ }
3819
+
3820
+ function tierFindings(
3821
+ state: RunState,
3822
+ survivors: readonly DedupedSurvivor[],
3823
+ ): TieredFindings {
3824
+ const findings: Finding[] = [];
3379
3825
  const refuted: DebugRefutedFinding[] = [];
3380
- for (const survivor of state.survivors) {
3826
+ for (const survivor of survivors) {
3381
3827
  const verdict: RefuterVerdict =
3382
3828
  state.verdicts.get(survivor.id) ?? "not_submitted";
3383
3829
  if (verdict === "refuted") {
@@ -3394,6 +3840,9 @@ async function finish(
3394
3840
  severity: survivor.severity,
3395
3841
  evidence_class: survivor.evidence_class,
3396
3842
  refuter_verdict: verdict,
3843
+ causal_disposition: survivor.causal_disposition,
3844
+ claim: survivor.claim,
3845
+ path: survivor.path,
3397
3846
  },
3398
3847
  // The conjunction is computed HERE, and both conjuncts are the same
3399
3848
  // kind of trap one level apart.
@@ -3426,6 +3875,77 @@ async function finish(
3426
3875
  ),
3427
3876
  });
3428
3877
  }
3878
+ const tieredCount = findings.length;
3879
+ const protectedIds = new Set(
3880
+ findings.filter((f) => isSafetyProtected(f)).map((f) => f.id),
3881
+ );
3882
+ // The consolidation plan was validated against the ids runConsolidation
3883
+ // sent; it is re-validated here against the ids this function produced,
3884
+ // because the two lists are derived separately and a plan applied to a
3885
+ // list it was not written for would merge the wrong findings. A mismatch
3886
+ // keeps the findings as they are: precision lost, never recall.
3887
+ if (state.consolidationPlan === undefined) {
3888
+ return {
3889
+ findings,
3890
+ tieredCount,
3891
+ refuted,
3892
+ protectedIds,
3893
+ consolidation: { kind: "none" },
3894
+ };
3895
+ }
3896
+ let plan: PlanEntry[] | undefined;
3897
+ try {
3898
+ plan = validatePlan(
3899
+ { findings: state.consolidationPlan },
3900
+ findings.map((f) => f.id),
3901
+ new Set(),
3902
+ );
3903
+ } catch {
3904
+ plan = undefined;
3905
+ }
3906
+ if (plan === undefined) {
3907
+ return {
3908
+ findings,
3909
+ tieredCount,
3910
+ refuted,
3911
+ protectedIds,
3912
+ consolidation: { kind: "mismatch" },
3913
+ };
3914
+ }
3915
+ const stats = { repairs: 0 };
3916
+ plan = enforcePlanInvariants(plan, findings, stats);
3917
+ for (const entry of plan) {
3918
+ if (entry.sources.some((id) => protectedIds.has(id))) {
3919
+ protectedIds.add(entry.primary);
3920
+ }
3921
+ }
3922
+ return {
3923
+ findings: applyPlan(findings, plan, []),
3924
+ tieredCount,
3925
+ refuted,
3926
+ protectedIds,
3927
+ consolidation: {
3928
+ kind: "applied",
3929
+ repairs: stats.repairs,
3930
+ findingsOut: plan.length,
3931
+ },
3932
+ };
3933
+ }
3934
+
3935
+ // Steps 7 + 8: map verdicts, assign tiers, assemble the SkillOutput draft and
3936
+ // write pipeline.json. Also the ceiling path's landing zone — it dedupes
3937
+ // whatever hunters completed so even a truncated run emits canonical ids.
3938
+ async function finish(
3939
+ input: PipelineInput,
3940
+ state: RunState,
3941
+ ): Promise<PipelineResult> {
3942
+ if (!state.survivors) {
3943
+ const { survivors, deduped } = mergeAndDedupe(state.drafts);
3944
+ state.survivors = survivors;
3945
+ state.deduped = deduped;
3946
+ }
3947
+ const tiered = tierFindings(state, state.survivors);
3948
+ const refuted = tiered.refuted;
3429
3949
  // Merge losers were never submitted to the refuter — stamp the canonical
3430
3950
  // not_submitted verdict the debug shape requires.
3431
3951
  const deduped = (state.deduped ?? []).map((loser) => ({
@@ -3440,40 +3960,31 @@ async function finish(
3440
3960
  // above keep their ids, order, tiers and verdicts; only `root_cause_id` is
3441
3961
  // stamped on, and only when the clusterer actually placed the finding.
3442
3962
  //
3443
- // Consolidation is applied FIRST, so the clusterer and everything after it
3444
- // see the list that is actually posted. The plan was validated against the
3445
- // ids runConsolidation sent; it is re-validated here against the ids this
3446
- // function produced, because the two lists are derived separately and a
3447
- // plan applied to a list it was not written for would merge the wrong
3448
- // findings. A mismatch keeps the findings as they are: precision lost,
3449
- // never recall.
3450
- if (state.consolidationPlan !== undefined) {
3451
- let plan: PlanEntry[] | undefined;
3452
- try {
3453
- plan = validatePlan(
3454
- { findings: state.consolidationPlan },
3455
- findings.map((f) => f.id),
3456
- new Set(),
3457
- );
3458
- } catch {
3459
- plan = undefined;
3460
- }
3461
- if (plan === undefined) {
3462
- if (state.consolidation !== undefined) {
3463
- state.consolidation.status = "failed";
3464
- state.consolidation.reason = "plan no longer matches findings";
3465
- state.consolidation.findings_out = findings.length;
3466
- }
3467
- } else {
3468
- const stats = { repairs: 0 };
3469
- plan = enforcePlanInvariants(plan, findings, stats);
3470
- if (state.consolidation !== undefined) {
3471
- state.consolidation.plan_repairs = stats.repairs;
3472
- state.consolidation.findings_out = plan.length;
3473
- }
3474
- findings = applyPlan(findings, plan, []);
3963
+ // Consolidation is applied FIRST (inside tierFindings), so the clusterer
3964
+ // and everything after it see the list that is actually posted.
3965
+ if (state.consolidation !== undefined) {
3966
+ if (tiered.consolidation.kind === "mismatch") {
3967
+ state.consolidation.status = "failed";
3968
+ state.consolidation.reason = "plan no longer matches findings";
3969
+ state.consolidation.findings_out = tiered.tieredCount;
3970
+ } else if (tiered.consolidation.kind === "applied") {
3971
+ state.consolidation.plan_repairs = tiered.consolidation.repairs;
3972
+ state.consolidation.findings_out = tiered.consolidation.findingsOut;
3475
3973
  }
3476
3974
  }
3975
+ // The materiality verdicts land AFTER the plan (S5), keyed by id, on the
3976
+ // list runMaterialityJudge judged. applyMaterialityVerdicts re-checks the
3977
+ // tier and the safety guard itself, so a verdict can only ever demote a
3978
+ // blocking, unprotected finding — and a finding with no verdict (stage off,
3979
+ // a failed step, an unsafe prompt, a ceiling cut) keeps its tier.
3980
+ const findings =
3981
+ state.materialityVerdicts === undefined
3982
+ ? tiered.findings
3983
+ : applyMaterialityVerdicts(
3984
+ tiered.findings,
3985
+ state.materialityVerdicts,
3986
+ tiered.protectedIds,
3987
+ );
3477
3988
  state.consolidation ??= skippedConsolidation(input);
3478
3989
  const rootCauses = clusterByRootCause(findings);
3479
3990
  const rootCauseId = rootCauseIdByFinding(rootCauses);
@@ -3496,6 +4007,7 @@ async function finish(
3496
4007
  run_status: state.partial ? "partial" : "complete",
3497
4008
  ...(state.summary === undefined ? {} : { summary: state.summary }),
3498
4009
  };
4010
+ state.finalFindings = clustered;
3499
4011
  await writePipelinePlan(input, state);
3500
4012
  return {
3501
4013
  skillOutput,
@@ -3652,6 +4164,9 @@ async function writePipelinePlan(
3652
4164
  ...(state.consolidation === undefined
3653
4165
  ? {}
3654
4166
  : { consolidation: state.consolidation }),
4167
+ // Unconditional, unlike the two above: every road to this write (the
4168
+ // gotchas early return included) records whether the gate was asked for.
4169
+ materiality: state.materiality ?? skippedMateriality(input, state),
3655
4170
  // `--shared-prefix` arm identity, read off the artifact like `scout`: a run
3656
4171
  // whose hunters all sit in groups of one has no warm-up row to tell it
3657
4172
  // from control. Absent means the control layout, byte for byte.
@@ -3721,6 +4236,7 @@ function fillRereviewProvenance(
3721
4236
  tier: row.tier,
3722
4237
  locs: row.locs,
3723
4238
  status: row.status,
4239
+ claim: row.claim,
3724
4240
  })),
3725
4241
  verifiedGone: base.resolved_verified ?? 0,
3726
4242
  verifiedGoneIds: base.resolved_ids ?? [],
@@ -3740,6 +4256,14 @@ function fillRereviewProvenance(
3740
4256
  verifyVerdicts: state.verifyVerdicts,
3741
4257
  });
3742
4258
  state.gatePriors = assembled.gateRows;
4259
+ // The priors the gate count releases through a materiality demotion, read
4260
+ // off the same findings and gate rows the count reads. Recorded here so both
4261
+ // posting roads re-tier them in the state block: --pr --post reads this
4262
+ // object, and post --from reads it back from pipeline.json.
4263
+ const released = materialityReleasedIds(
4264
+ state.finalFindings ?? [],
4265
+ assembled.gateRows,
4266
+ );
3743
4267
  const filled: RereviewProvenance = {
3744
4268
  ...base,
3745
4269
  verified: state.verificationSpawned,
@@ -3751,6 +4275,7 @@ function fillRereviewProvenance(
3751
4275
  returned: assembled.returned,
3752
4276
  re_tiered: assembled.reTiered,
3753
4277
  ...(state.worsenedHits.length > 0 ? { worsened: state.worsenedHits } : {}),
4278
+ ...(released.length > 0 ? { materiality_released_ids: released } : {}),
3754
4279
  };
3755
4280
  // The CLI holds this object; mutating it is how the post path sees live[].
3756
4281
  Object.assign(base, filled);