rungate 0.8.2 → 0.8.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 (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -50,6 +50,51 @@
50
50
  * reads as clean, and the derived decision is WITHHELD rather than defaulted:
51
51
  * `blocked` is `null` under an UNMEASURED reading.
52
52
  *
53
+ * ## Where a finding points, and why that is not a question about whether it
54
+ * is right (#1204)
55
+ *
56
+ * A blocking finding may name a file the pull request never touched. #1166
57
+ * made a finding missing `file`, `line`, `summary` or `failure_scenario` its
58
+ * own reading; that is a check on whether the payload is SELF-consistent, and
59
+ * the payload is all it needs. "The file is not in the diff" compares the
60
+ * payload against the PULL REQUEST, so it needs a second input — the list of
61
+ * paths the pull request changed — and the reading is withheld until it has
62
+ * one.
63
+ *
64
+ * **This is not a correctness filter and must never become one.** Nothing
65
+ * here asks whether a finding is RIGHT. A reviewer that is wrong about real
66
+ * code is a review problem, and suppressing findings on suspicion of being
67
+ * wrong is the fail-open this module exists against. The only question asked
68
+ * is whether the finding can be LOCATED, which is decidable from the diff
69
+ * without reading the claim at all.
70
+ *
71
+ * And an unlocatable finding is **demoted, never dropped**. The tempting
72
+ * repair is to filter it out of the blocking list and let the run go green —
73
+ * which makes a review that discarded a finding byte-indistinguishable from a
74
+ * review that found nothing. So CRC-B7 tags it `Pre-existing`: the finding is
75
+ * carried in `reported` and in `unlocatableReported`, named in the
76
+ * annotation, counted on the scope line, and does not get to block on its
77
+ * own.
78
+ *
79
+ * #1204 wrote that refusal as `BLOCKING_FINDING_UNLOCATABLE`, a red required
80
+ * check. CRC-B7's demotion satisfies #1204's own stated criterion — the
81
+ * finding is not DROPPED — and does not redden a pull request over a defect
82
+ * that was already on main, so the refusal is gone and the demotion is what
83
+ * ships. The two were written against the same input on different branches;
84
+ * this is the resolution, not an accident of the merge.
85
+ *
86
+ * The second input is NOT SUPPLIED by any generated job yet, and the absent
87
+ * state is named rather than silently skipped — `scope.status` is
88
+ * `NOT_SUPPLIED`, `main` prints it on every run, and the verdict is exactly
89
+ * what it was before. That is deliberately the third option, against the two
90
+ * #1204 tabulated: skipping silently is Silent Default Substitution, and
91
+ * refusing an absent list would redden consumers for a reason about our
92
+ * release rather than about their code. The generated step runs
93
+ * `bunx rungate@<generating version>`, so a consumer's workflow and its
94
+ * adjudicator always come from the SAME release and cannot skew apart; the
95
+ * absent state is reachable from a hand-run CLI and from a workflow older
96
+ * than the half that supplies the list.
97
+ *
53
98
  * ## The exit code
54
99
  *
55
100
  * Every refusal routes through `AI_REVIEW_REQUIRED_EXIT`, imported from
@@ -185,6 +230,182 @@ export function renderCountedFindings(reported: unknown[] | null): string[] {
185
230
  /** The annotation title the script prints its refusal under. */
186
231
  export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
187
232
 
233
+ /**
234
+ * The annotation title the advisory tail is printed under.
235
+ *
236
+ * A SEPARATE title from `AI_REVIEW_FINDINGS_TITLE`, deliberately. The refusal
237
+ * is a thing somebody has to act on before the pull request moves; this is a
238
+ * thing somebody has to answer before it merges, and GitHub groups
239
+ * annotations by title. One title for both would make the advisory tail
240
+ * read, in the checks UI, as part of the refusal — which is the misattribution
241
+ * `blockingContractViolations` is about, arriving from the other direction.
242
+ */
243
+ export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
244
+
245
+ /**
246
+ * A stable identity for one finding, so an answer can name it.
247
+ *
248
+ * @identity file+summary — whitespace-collapsed and case-folded, FNV-1a, 8
249
+ * hex characters. Total: every finding gets a key, and it is never `null`.
250
+ *
251
+ * **This is the ADJUDICATION key** — "has this advisory already been counted
252
+ * on this run". Within one payload there is only one version of the file, so
253
+ * the line genuinely does not matter, and keying on it would split one
254
+ * finding into two across a reformat.
255
+ *
256
+ * Its sibling is `carryKey` in `lib/ai-review-rounds.ts`, which is the
257
+ * PERSISTENCE key — "is the thing this round raised the thing the last round
258
+ * raised" — over `file` + the cited line's TEXT + `summary`, and partial: it
259
+ * returns `null` for a finding it cannot key, which this hash cannot do. The
260
+ * two were both called `findingKey` until #1398. They answer different
261
+ * questions and the collapse loses one; neither can quietly become the
262
+ * other, which was measured rather than assumed, but while they shared a
263
+ * name no call site could say which it had asked.
264
+ *
265
+ * CRC-B8 asks that every finding be answered — fixed, or resolved with a
266
+ * stated reason — and an answer has to name what it answers. The line number
267
+ * cannot be that name: the same finding moves line between rounds, which is
268
+ * exactly what #1319 measured (`bash-write-guard.ts:90 → :97` across two
269
+ * rounds of #1213 was *one* finding). So the key is over the file and the
270
+ * summary, whitespace-collapsed and case-folded, and it is deliberately NOT
271
+ * over the severity either — a reviewer that re-rates the same observation
272
+ * has not produced a second finding.
273
+ *
274
+ * FNV-1a, written out, rather than `node:crypto`. Not a preference: this
275
+ * module is copied into a temp directory by the mutation battery in
276
+ * `test/ai-review-advisory-findings.test.ts`, and every import it carries has
277
+ * to be carried with it. The property wanted is determinism and a short
278
+ * printable token, not collision resistance against an adversary.
279
+ *
280
+ * ## WHAT A COLLISION COSTS, and it is no longer only an annotation
281
+ *
282
+ * This docblock used to end *"a finding that forged another finding's key
283
+ * would buy the forger an answer on the wrong row, which is a worse
284
+ * annotation and not a bypass of anything."* That stopped being true the
285
+ * moment CRC-B4 made the verifier quorum read a ballot filed under this
286
+ * key: a collision between two BLOCKING findings would let one group's vote
287
+ * decide both. The sentence is corrected rather than deleted because a
288
+ * comment asserting a property the code no longer has is the reason nobody
289
+ * checks it — `lib/cli-commands.ts` carried *"runs every command for real"*
290
+ * over a test that ran one command of ten.
291
+ *
292
+ * What holds instead, and it is a property of the CALLER rather than of
293
+ * this hash: `juryGate` derives the identity once over the whole blocking
294
+ * set, refuses a key two of them share, and carries its decision back to
295
+ * the reader **by position**. So a collision is seen and both findings keep
296
+ * blocking; it cannot silently credit one finding's vote to another. The
297
+ * hash is still not adversary-resistant and is not asked to be — nothing
298
+ * downstream of it decides anything a collision could not already be
299
+ * refused for.
300
+ */
301
+ export function advisoryKey(finding: Record<string, unknown>): string {
302
+ const f = AI_REVIEW_FINDING_FIELDS;
303
+ const normalise = (v: unknown): string =>
304
+ String(v ?? "").trim().replace(/\s+/g, " ").toLowerCase();
305
+ const subject = `${normalise(finding[f.file])}\u0000${normalise(finding[f.summary])}`;
306
+ let hash = 0x811c9dc5;
307
+ for (let i = 0; i < subject.length; i++) {
308
+ hash ^= subject.charCodeAt(i);
309
+ hash = Math.imul(hash, 0x01000193) >>> 0;
310
+ }
311
+ return hash.toString(16).padStart(8, "0");
312
+ }
313
+
314
+ /**
315
+ * The findings this reading counted and did NOT act on — the advisory tail.
316
+ *
317
+ * `null`, never `[]`, when the complement cannot be taken. Under UNMEASURED
318
+ * `blockingReported` is `null` — a withheld decision, not an empty one — so
319
+ * subtracting it from `reported` would manufacture an advisory set out of
320
+ * findings nobody classified. Those are different facts and this module's
321
+ * whole philosophy is that they stay different.
322
+ *
323
+ * Computed by identity against `blockingReported` rather than by re-reading
324
+ * the severities. Re-reading them here would be a second decider over the one
325
+ * question `severityBlocks` already answers — the fourth shape in
326
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
327
+ * would leave the other holding every case up.
328
+ */
329
+ export function advisoryReported(reading: AiReviewFindingsReading): unknown[] | null {
330
+ if (reading.reported === null || reading.blockingReported === null) return null;
331
+ const blocking = new Set(reading.blockingReported);
332
+ return reading.reported.filter(item => !blocking.has(item));
333
+ }
334
+
335
+ /**
336
+ * The sentence naming every advisory finding, or `null` when there is nothing
337
+ * to name.
338
+ *
339
+ * ## The silent drop this closes (CRC-B8)
340
+ *
341
+ * `AI_REVIEW_SEVERITIES` declares `medium`, `low` and `info` as advisory, and
342
+ * until this function existed a reading counted them and then dropped them.
343
+ * `detail` is populated inside `if (blocks)`; `aiReviewRefusal` returns `null`
344
+ * for CLEAN and lists only `detail` for BLOCKED. So `main()` printed the
345
+ * outcome line and nothing else, and a payload carrying seven `medium`
346
+ * findings produced **byte-identical output** to a payload carrying none.
347
+ * The payload itself lives under `$RUNNER_TEMP`, is uploaded nowhere (#1319
348
+ * measured zero artifacts) and dies with the runner, so the finding was not
349
+ * merely unreported — it was unrecoverable the moment the job ended.
350
+ *
351
+ * That is CRC-B8's second sentence failing in the live path: *a finding is
352
+ * never silently dropped*. It is also the reason the tail could not be
353
+ * answered rather than filed — you cannot resolve on the pull request a
354
+ * finding the pull request never shows you.
355
+ *
356
+ * ## Why CONTRADICTION returns null here
357
+ *
358
+ * The contradiction arm of `aiReviewRefusal` already prints EVERY counted
359
+ * finding, advisory ones included, through `renderCountedFindings` — #1178,
360
+ * and for a reason that still holds. Emitting this notice alongside it would
361
+ * print the advisory tail twice, and that module's own comment says why that
362
+ * is worse than printing it once: *a duplicate reads as two findings*. The
363
+ * rule lives here, in one function, rather than as a condition at the call
364
+ * site, so there is one binding to mutate.
365
+ *
366
+ * ## What this does NOT do
367
+ *
368
+ * It decides nothing. `aiReviewExitCode` is untouched and reads only the
369
+ * outcome, so an advisory finding does not block and cannot be made to block
370
+ * from here. Surfacing a finding and adjudicating one are different jobs, and
371
+ * this module already holds the second; a notice that quietly became a
372
+ * refusal would be a severity table nobody declared.
373
+ */
374
+ export function advisoryNotice(reading: AiReviewFindingsReading): string | null {
375
+ if (reading.outcome === "CONTRADICTION") return null;
376
+ const advisory = advisoryReported(reading);
377
+ if (advisory === null || advisory.length === 0) return null;
378
+
379
+ // Rendered through `renderCountedFindings` over the WHOLE list and then
380
+ // selected, rather than over the filtered list. Two reasons, and the second
381
+ // is the one that bites: the renderer numbers what it is given, so rendering
382
+ // the tail alone would renumber it from zero and `finding 3` in this notice
383
+ // would be a different finding from `finding 3` in a refusal. And selecting
384
+ // out of the full render means this notice and the contradiction arm's list
385
+ // come from one call of one function, which is what keeps them from drifting.
386
+ const reported = reading.reported ?? [];
387
+ const all = renderCountedFindings(reported);
388
+ const rendered = advisory.map(item => {
389
+ const i = reported.indexOf(item);
390
+ const key =
391
+ item !== null && typeof item === "object" && !Array.isArray(item)
392
+ ? ` [key ${advisoryKey(item as Record<string, unknown>)}]`
393
+ : "";
394
+ return `${all[i]}${key}`;
395
+ });
396
+
397
+ return (
398
+ `${advisory.length} advisory finding(s) were counted and block nothing. ` +
399
+ `${rendered.join("; ")}. ` +
400
+ `Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
401
+ `resolved with a reason, or filed, and this annotation is the only place ` +
402
+ `it survives the job — the payload lives under the runner's temp directory ` +
403
+ `and is uploaded nowhere. Answer each one on this pull request (fix it, or ` +
404
+ `say in a comment why it stands), naming its key. Filing an issue is the ` +
405
+ `exception, not the default.`
406
+ );
407
+ }
408
+
188
409
  /** The four states a reading can be in. Exactly one is reached per run. */
189
410
  export type AiReviewOutcome = "CLEAN" | "BLOCKED" | "CONTRADICTION" | "UNMEASURED";
190
411
 
@@ -200,8 +421,29 @@ export type AiReviewUnmeasuredReason =
200
421
  | "SEVERITY_ABSENT"
201
422
  | "SEVERITY_UNRECOGNISED"
202
423
  | "BLOCKING_FINDING_INCOMPLETE"
424
+ // `BLOCKING_FINDING_UNLOCATABLE` was here and is gone with the merge of
425
+ // #1204 into CRC-B7. Nothing produces it: a blocking finding naming a file
426
+ // outside the diff is DEMOTED to `Pre-existing` and the run stays readable,
427
+ // rather than refusing the whole reading. A member nothing emits is a state
428
+ // no test can reach, and `not.toContain` against it passes vacuously for
429
+ // ever — which is how a deleted check goes on looking guarded.
430
+ | "ARGUMENTS_UNREADABLE"
203
431
  | "VERDICT_ABSENT"
204
- | "VERDICT_UNRECOGNISED";
432
+ | "VERDICT_UNRECOGNISED"
433
+ /**
434
+ * A changed-file list was supplied and was EMPTY. A pull request always
435
+ * touches something, so `[]` is a reading that failed rather than a pull
436
+ * request that changed nothing — and taken at face value it would tag every
437
+ * finding `Pre-existing` and block none of them, which is the fail-open this
438
+ * module exists to refuse.
439
+ */
440
+ | "CHANGED_FILES_EMPTY"
441
+ /**
442
+ * A changed-file list entry could not be read as a repository path.
443
+ * Comparing against a list the reader cannot normalise would demote every
444
+ * finding, so the list being unreadable is a reading that failed.
445
+ */
446
+ | "CHANGED_FILES_UNREADABLE";
205
447
 
206
448
  /**
207
449
  * The fields a BLOCKING finding must carry, derived from the one contract map
@@ -247,6 +489,164 @@ export function blockingContractViolations(finding: Record<string, unknown>): st
247
489
  });
248
490
  }
249
491
 
492
+ // `AI_REVIEW_CHANGED_FILES_FLAG` lived here and is gone. #1204 argued for a
493
+ // FLAG over a second positional, citing #675: `--project-root <cwd>` "would
494
+ // arrive as a second positional and be read as a second payload".
495
+ //
496
+ // That hazard was CHECKED before the constant was removed, not waved away.
497
+ // `bin/rungate.ts` appends `--project-root` only when a command declares
498
+ // `projectRootFlag`, and `ai-review-findings` declares none — which is the
499
+ // very fact #1204 cited. So nothing injects a stray positional into THIS
500
+ // command, and the argument does not reach it.
501
+ //
502
+ // The positional wins because the deployed workflow passes one and #1356
503
+ // builds on that. Two spellings for one argument would be two deciders, and
504
+ // the spelling the generated step does not use is the one that would rot.
505
+
506
+ /**
507
+ * The prefix of the line recording how the scope reading was taken.
508
+ *
509
+ * Distinct from `AI_REVIEW_OUTCOME_LINE`, which the generated step lifts its
510
+ * verdict out of by parameter expansion on the FIRST occurrence of that
511
+ * marker. This line is printed after it and contains neither that marker nor
512
+ * a newline, so nothing about the verdict extraction moves.
513
+ */
514
+ export const AI_REVIEW_SCOPE_LINE = "ai-review findings scope:";
515
+
516
+ /** Whether the pull request's changed-file list was read, and if not, why. */
517
+ export type AiReviewScopeStatus = "MEASURED" | "NOT_SUPPLIED" | "UNMEASURED";
518
+
519
+ /**
520
+ * The changed-file reading. One discriminator, `status`, and the producing
521
+ * code's own sentence beside it.
522
+ *
523
+ * `NOT_SUPPLIED` and `UNMEASURED` are different facts with different fixes.
524
+ * Nobody handed this run a list is a property of the workflow that invoked
525
+ * it; a list that could not be read is a property of this run. Collapsing
526
+ * them would make a release in which the input does not exist yet look like
527
+ * a `git diff` that failed.
528
+ */
529
+ export type AiReviewScopeReading =
530
+ | { status: "NOT_SUPPLIED"; files: null; detail: string; reason: null }
531
+ | { status: "MEASURED"; files: string[]; detail: string; reason: null }
532
+ | {
533
+ status: "UNMEASURED";
534
+ files: null;
535
+ detail: string;
536
+ reason: Extract<
537
+ AiReviewUnmeasuredReason,
538
+ "CHANGED_FILES_UNREADABLE" | "CHANGED_FILES_EMPTY"
539
+ >;
540
+ };
541
+
542
+ /** The reading for a run nobody handed a changed-file list. */
543
+ export function scopeNotSupplied(): AiReviewScopeReading {
544
+ return {
545
+ status: "NOT_SUPPLIED",
546
+ files: null,
547
+ reason: null,
548
+ detail:
549
+ `no changed-file list was given (second positional argument), so whether ` +
550
+ `a blocking finding names a file this pull request touches was not checked. ` +
551
+ `This is a reading, not a pass: the generated job does not supply the list yet`,
552
+ };
553
+ }
554
+
555
+ /**
556
+ * The reading for a run whose changed-file list was supplied directly rather
557
+ * than read from disk.
558
+ *
559
+ * Exists so a caller holding an array does not have to spell the discriminated
560
+ * union by hand. `files` is carried raw; `readPayload` normalises.
561
+ *
562
+ * An EMPTY array is still MEASURED here and is refused downstream, on purpose:
563
+ * "a list was supplied and it was empty" is a fact this type can represent and
564
+ * `readAiReviewChangedFiles` cannot produce, so the refusal lives where every
565
+ * caller passes through rather than only on the disk path.
566
+ */
567
+ export function scopeMeasured(files: readonly string[]): AiReviewScopeReading {
568
+ return {
569
+ status: "MEASURED",
570
+ files: [...files],
571
+ reason: null,
572
+ detail: `${files.length} changed path(s) supplied directly`,
573
+ };
574
+ }
575
+
576
+ /**
577
+ * Read the changed-file list from disk. Three states, each its own fact.
578
+ *
579
+ * A list that could not be read REFUSES and must never produce an empty list:
580
+ * an empty changed set makes every blocking finding unlocatable, which is the
581
+ * loud direction and loud for the wrong reason — it reads as the reviewer
582
+ * having hallucinated every finding it wrote.
583
+ *
584
+ * A list that WAS read and names no paths refuses too, under its own reason.
585
+ * A pull request that changes nothing is not a state this input can honestly
586
+ * be in, so an empty file is a diff that was lost rather than a diff that was
587
+ * empty — and the two reasons are kept apart because the fixes differ.
588
+ *
589
+ * The list must be taken from the RESTORED tree, before the reviewer could
590
+ * have written to the checkout. That is why this function is handed a path
591
+ * and never takes the diff itself: this module runs after the review, from
592
+ * the payload's own directory, so a diff computed here is one the subject of
593
+ * the review had an opportunity to edit.
594
+ */
595
+ export function readAiReviewChangedFiles(path: string | undefined): AiReviewScopeReading {
596
+ if (path === undefined || path === "") return scopeNotSupplied();
597
+
598
+ let raw: string;
599
+ try {
600
+ raw = readFileSync(path, "utf-8");
601
+ } catch (e) {
602
+ return {
603
+ status: "UNMEASURED",
604
+ files: null,
605
+ reason: "CHANGED_FILES_UNREADABLE",
606
+ detail:
607
+ `the changed-file list at ${path} could not be read: ${(e as Error).message}. ` +
608
+ `A diff that could not be taken is not a pull request that touches nothing`,
609
+ };
610
+ }
611
+
612
+ // Entries are carried RAW, trimmed only. This function decides whether the
613
+ // list is a reading; `readPayload` decides what each path means, through
614
+ // `normaliseRepoPath`. Normalising here too would be two normalisers over
615
+ // one input — and the weaker one would win silently, because it runs first.
616
+ // `normaliseRepoPath` collapses dot segments, strips a `:line` suffix and
617
+ // refuses git's C-quoted form; stripping `./` is the only thing the reader
618
+ // that used to live here could do.
619
+ const files = raw.split("\n").map(l => l.trim()).filter(p => p.length > 0);
620
+ if (files.length === 0) {
621
+ return {
622
+ status: "UNMEASURED",
623
+ files: null,
624
+ reason: "CHANGED_FILES_EMPTY",
625
+ detail:
626
+ `the changed-file list at ${path} names no paths at all. A pull request that ` +
627
+ `changes nothing is not a state this input can be in, so the diff was taken and ` +
628
+ `lost rather than taken and empty — and reading it as empty would report every ` +
629
+ `blocking finding as naming a file outside the pull request`,
630
+ };
631
+ }
632
+
633
+ return {
634
+ status: "MEASURED",
635
+ files,
636
+ reason: null,
637
+ detail: `${files.length} changed path(s) read from ${path}`,
638
+ };
639
+ }
640
+
641
+ // `unlocatableBlockingFinding` lived here and is gone. It was #1204's
642
+ // refusal predicate, and the merge with CRC-B7 retired the refusal; the
643
+ // comparison it performed now happens inside `readPayload` against
644
+ // `normaliseRepoPath`, which is the stronger reader. Deleted rather than
645
+ // left exported with no caller — `lib/ai-review-rounds.ts` (CRC-N4) and
646
+ // `lib/finding-jury.ts` (CRC-B4) are both open issues about exactly that,
647
+ // and adding a third would be the cheapest way to pretend this merge kept
648
+ // more than it did.
649
+
250
650
  export interface AiReviewFindingsReading {
251
651
  /** The single discriminator. Everything else is a projection of the same pass. */
252
652
  outcome: AiReviewOutcome;
@@ -265,6 +665,31 @@ export interface AiReviewFindingsReading {
265
665
  unmeasuredReasons: AiReviewUnmeasuredReason[];
266
666
  /** The producing code's own sentences, one per reason or blocking finding. */
267
667
  detail: string[];
668
+ /** How the pull request's changed-file list was read, and whether it was. */
669
+ scope: AiReviewScopeReading;
670
+ /**
671
+ * Blocking findings naming a file the pull request does not touch — CARRIED,
672
+ * never dropped, and `null` when the scope check did not run.
673
+ *
674
+ * `null` rather than `[]` for the did-not-run case on purpose: an empty list
675
+ * and a check nobody performed are the states this module exists to keep
676
+ * apart. `scope.status` is the discriminator; this is a projection of it.
677
+ */
678
+ unlocatableReported: unknown[] | null;
679
+ /**
680
+ * Changed-file entries this reader could not normalise and DROPPED from the
681
+ * comparison set (#1472) — RAW, named, in list order.
682
+ *
683
+ * Three states, and the middle one is the reason this is not a count.
684
+ * `null` is "no list was supplied, so nothing was read in full or in part";
685
+ * `[]` is "a list was read and every entry of it was comparable"; a
686
+ * non-empty list is "a list was read and these entries were not", which is
687
+ * a reading over a NARROWER set than the pull request actually touched. A
688
+ * reading that narrowed itself and did not say so is indistinguishable from
689
+ * a complete one — `.claude/rules/config-access.md`'s *Silent Default
690
+ * Substitution*, in the place it decides a required check.
691
+ */
692
+ scopeDropped: string[] | null;
268
693
  }
269
694
 
270
695
  /**
@@ -292,21 +717,167 @@ function unmeasured(
292
717
  verdict: null,
293
718
  unmeasuredReasons: reasons,
294
719
  detail,
720
+ scope: scopeNotSupplied(),
721
+ unlocatableReported: null,
722
+ scopeDropped: null,
295
723
  };
296
724
  }
297
725
 
726
+ /**
727
+ * The ONE place a scope reading meets a payload reading.
728
+ *
729
+ * Every reading is built carrying the NOT_SUPPLIED default and passes through
730
+ * here. A second site that set `scope`, or that raised a reading on a refused
731
+ * scope, would be a second statement about the same input and the two could
732
+ * disagree.
733
+ *
734
+ * A scope reading that REFUSES raises the whole reading, carrying the
735
+ * payload's own reasons and findings with it rather than replacing them:
736
+ * "the diff could not be taken" and "the payload is not JSON" are both true
737
+ * of such a run, and a reader fixing one needs to see the other.
738
+ */
739
+ function withScope(
740
+ reading: AiReviewFindingsReading,
741
+ scope: AiReviewScopeReading,
742
+ unlocatableReported: unknown[] | null,
743
+ scopeDropped: string[] | null,
744
+ ): AiReviewFindingsReading {
745
+ const merged =
746
+ scope.status === "UNMEASURED"
747
+ ? unmeasured(
748
+ [...reading.unmeasuredReasons, scope.reason],
749
+ [...reading.detail, scope.detail],
750
+ reading.reported,
751
+ )
752
+ : reading;
753
+ return { ...merged, scope, unlocatableReported, scopeDropped };
754
+ }
755
+
298
756
  /**
299
757
  * Read a findings payload and decide what it means.
300
758
  *
301
759
  * `raw` is `null` for "there was no payload at all", which is a reading and
302
760
  * not an error: a job whose reviewer never wrote anything has not passed a
303
761
  * review, it has not had one.
762
+ *
763
+ * `scope` is the pull request's changed-file reading, and what this function
764
+ * DOES with it is CRC-B7 (CODE-REVIEW-CONVERGENCE-SPEC): a finding naming no
765
+ * file this pull request touched is tagged `Pre-existing` and does not block,
766
+ * so a bug that was already on `main` does not read as the change's fault.
767
+ * `ai-review` reads the MERGE REF, so without this every defect on `main` is
768
+ * reported against whichever pull request is standing closest — nine of them
769
+ * at once on 2026-10-23.
770
+ *
771
+ * ## #1204 and CRC-B7 answered the same question and this merge picked one
772
+ *
773
+ * Both asked *does this finding apply to this pull request?* over the same
774
+ * input. #1204 refused — `BLOCKING_FINDING_UNLOCATABLE`, a red required
775
+ * check. CRC-B7 demotes. **CRC-B7 owns the case**, because #1204's answer
776
+ * makes its own motivating measurement worse: under it each of those nine
777
+ * findings becomes a REFUSING required check, so every pull request standing
778
+ * near a defect on `main` is unmergeable until somebody fixes `main`. That is
779
+ * worse than the state it was fixing. CRC-B7 also grades the error direction,
780
+ * which the refusal does not: an undecidable path keeps blocking, and a
781
+ * non-string path is a contract violation rather than a demotion input.
782
+ *
783
+ * What #1204 keeps is the INPUT layer — `scope`, three states as a type
784
+ * rather than as conventions over a nullable array. It is the only side that
785
+ * can tell "nobody handed this run a list" from "every finding was
786
+ * locatable", and those are the two readings a green check must not conflate.
787
+ * It defaults to NOT_SUPPLIED, under which nothing is demoted and the reading
788
+ * is exactly what it was before any of this existed.
789
+ *
790
+ * The finding's DECLARED `file` is the input, not a path mined out of its
791
+ * prose. `blockingContractViolations` already refuses a blocking finding that
792
+ * carries none, and `lib/finding-jury.ts`'s `citedPaths` text-mines only
793
+ * because the arbiter's findings arrive as prose. Mining a field the payload
794
+ * declares would be a second decider for a question already answered.
795
+ */
796
+ export function readAiReviewFindings(
797
+ raw: string | null,
798
+ scope: AiReviewScopeReading = scopeNotSupplied(),
799
+ ): AiReviewFindingsReading {
800
+ const preExisting: unknown[] = [];
801
+ // Appended to by `readPayload`, for the same reason `preExisting` is: the
802
+ // entries belong to the reading its caller composes, and every early return
803
+ // in there is a state in which the split had not happened yet.
804
+ const dropped: string[] = [];
805
+ const base = readPayload(
806
+ raw,
807
+ scope.status === "MEASURED" ? scope.files : undefined,
808
+ preExisting,
809
+ dropped,
810
+ );
811
+ return withScope(
812
+ base,
813
+ scope,
814
+ scope.status === "MEASURED" ? preExisting : null,
815
+ scope.status === "MEASURED" ? dropped : null,
816
+ );
817
+ }
818
+
819
+ /**
820
+ * The payload pass itself. `preExisting` is appended to rather than returned,
821
+ * because the findings it collects belong to the reading its caller composes
822
+ * and every early return here is a state in which none were collected.
823
+ *
824
+ * It holds the findings CRC-B7 demoted. A COUNT would not do: "three were
825
+ * demoted" and "these three were demoted" differ exactly when somebody wants
826
+ * to know whether the demotion was right, which is the only question anybody
827
+ * asks of a demotion.
304
828
  */
305
- export function readAiReviewFindings(raw: string | null): AiReviewFindingsReading {
829
+ function readPayload(
830
+ raw: string | null,
831
+ changedFiles: readonly string[] | undefined,
832
+ preExisting: unknown[],
833
+ dropped: string[],
834
+ ): AiReviewFindingsReading {
306
835
  if (raw === null) {
307
836
  return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
308
837
  }
309
838
 
839
+ if (changedFiles !== undefined && changedFiles.length === 0) {
840
+ return unmeasured(
841
+ ["CHANGED_FILES_EMPTY"],
842
+ [
843
+ "a changed-file list was supplied and was empty. A pull request always touches " +
844
+ "something, so this is a reading that failed rather than a pull request that " +
845
+ "changed nothing — and taken at face value every finding would be tagged " +
846
+ "Pre-existing and none would block.",
847
+ ],
848
+ );
849
+ }
850
+ let touched: Set<string> | null = null;
851
+ if (changedFiles !== undefined) {
852
+ // #1472. ONE unnormalisable entry used to refuse the WHOLE reading, so a
853
+ // repository holding a single tracked path with a space in it could never
854
+ // obtain a scope reading at all — `docs/my file.md` was enough, and the
855
+ // remedy the refusal named (`-z`, `core.quotePath=false`) does not apply,
856
+ // because git emits a space literally and the regex rejects it literally.
857
+ //
858
+ // The comparison is PER FINDING, so one bad entry says nothing about the
859
+ // others. The entry is dropped, the drop is NAMED, and the findings over
860
+ // normalisable paths are adjudicated as before.
861
+ const { readable, dropped: unreadable } = partitionChangedFiles(changedFiles);
862
+ dropped.push(...unreadable);
863
+ // The refusal is NARROWED, not deleted. With nothing readable left,
864
+ // `touched` is empty, every finding is tagged Pre-existing and the run
865
+ // reports a green check for a review that found something — which is the
866
+ // one input the original refusal was right about.
867
+ if (readable.length === 0) {
868
+ return unmeasured(
869
+ ["CHANGED_FILES_UNREADABLE"],
870
+ [
871
+ `all ${unreadable.length} changed-file entr(ies) could not be read as a repository ` +
872
+ `path: ${unreadable.map(p => JSON.stringify(p)).join(", ")}. ` +
873
+ `Comparing against a list with nothing readable left in it would tag every ` +
874
+ `finding Pre-existing. Produce the list with -z or core.quotePath=false`,
875
+ ],
876
+ );
877
+ }
878
+ touched = new Set(readable);
879
+ }
880
+
310
881
  let doc: unknown;
311
882
  try {
312
883
  doc = JSON.parse(raw);
@@ -349,6 +920,8 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
349
920
  const reasons: AiReviewUnmeasuredReason[] = [];
350
921
  const detail: string[] = [];
351
922
  const blocking: unknown[] = [];
923
+ /** How many findings CRC-B7 demoted. See the `agreed` computation below. */
924
+ let demoted = 0;
352
925
 
353
926
  list.forEach((item, i) => {
354
927
  if (item === null || typeof item !== "object" || Array.isArray(item)) {
@@ -390,6 +963,75 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
390
963
  );
391
964
  return;
392
965
  }
966
+ // CRC-B7, and AFTER the contract check rather than before it. A finding
967
+ // with no declared `file` cannot be tagged either way, and it has
968
+ // already been refused as incomplete one branch up — so by here `file`
969
+ // is known present, and the tag is decidable rather than guessed.
970
+ //
971
+ // It DEMOTES, it does not drop (CRC-B8). The finding stays in
972
+ // `reported`, so `advisoryReported` carries it into the notice and a
973
+ // maintainer still sees it; it simply stops reddening a required check
974
+ // over a defect the diff did not introduce and cannot fix.
975
+ if (touched !== null) {
976
+ const declared = finding[AI_REVIEW_FINDING_FIELDS.file];
977
+ // A non-string `file` is a CONTRACT violation, not a demotion input.
978
+ // `blockingContractViolations` refuses `undefined`, `null` and the
979
+ // empty string and lets a number or an object through, so without
980
+ // this a finding declaring `file: {}` stringifies to
981
+ // `[object Object]`, matches nothing, and demotes itself.
982
+ if (typeof declared !== "string") {
983
+ reasons.push("BLOCKING_FINDING_INCOMPLETE");
984
+ detail.push(
985
+ `finding ${i} blocks and declares a non-string ` +
986
+ `'${AI_REVIEW_FINDING_FIELDS.file}' (${typeof declared}). A path that is not a ` +
987
+ `string cannot be compared to the changed-file list, and a comparison that ` +
988
+ `cannot be made is not a finding that is pre-existing`,
989
+ );
990
+ return;
991
+ }
992
+ const named = normaliseRepoPath(declared);
993
+ // Undecidable is NOT pre-existing. The finding is well-formed and
994
+ // this reader simply cannot resolve its path, so it keeps blocking —
995
+ // the direction this stage is allowed to be wrong in.
996
+ if (named === null) {
997
+ detail.push(
998
+ `finding ${i} declares ${JSON.stringify(declared)}, which could not be read as a ` +
999
+ `repository path, so it could not be compared to the changed-file list. It ` +
1000
+ `keeps blocking: undecidable is not pre-existing`,
1001
+ );
1002
+ } else if (!touched.has(named)) {
1003
+ demoted += 1;
1004
+ // #1204's half that survived the merge: WHICH findings were
1005
+ // demoted, not just how many. The scope line reports it, so a
1006
+ // reader can ask whether a demotion was right — the only question
1007
+ // anybody asks of one.
1008
+ preExisting.push(item);
1009
+ detail.push(
1010
+ `finding ${i} is Pre-existing: it names ${JSON.stringify(
1011
+ finding[AI_REVIEW_FINDING_FIELDS.file],
1012
+ )}, which this pull request does not touch. It is reported and does not block — ` +
1013
+ `ai-review reads the merge ref, so a defect already on the base branch is ` +
1014
+ `adjudicated against whichever pull request is standing closest to it`,
1015
+ );
1016
+ return;
1017
+ }
1018
+ }
1019
+ // CRC-B4's verifier quorum does NOT appear here, and its absence is
1020
+ // the decision rather than an omission.
1021
+ //
1022
+ // A quorum that subtracts from this list is a gate whose input is the
1023
+ // thing it gates: the verifier reads the cited file at the HEAD
1024
+ // checkout, so code that argues itself clean would be voting on the
1025
+ // finding about itself. And the group that would cast those votes is
1026
+ // not independent — `AI_REVIEW_ALLOWED_TOOLS` grants
1027
+ // `Read,Grep,Glob,Write` and `AI_REVIEW_DENY_RULES` denies `Task`, so
1028
+ // a verifier step cannot spawn anything and N votes from one
1029
+ // invocation are one opinion written down N times.
1030
+ //
1031
+ // Until both are fixed — structural independence, and a base-ref read
1032
+ // — the ballot is RECORDED and never acted on. `main` runs the gate
1033
+ // for the ledger and the annotation; this list is untouched by it.
1034
+ // See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
393
1035
  blocking.push(item);
394
1036
  detail.push(renderFinding(i, finding));
395
1037
  }
@@ -417,7 +1059,19 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
417
1059
  // The decision, and the only place it is made. `verdict` is compared to it
418
1060
  // afterwards; it never contributes to it.
419
1061
  const blocked = blocking.length > 0;
420
- const agreed = verdict === (blocked ? AI_REVIEW_BLOCK_VERDICT : AI_REVIEW_PASS_VERDICT);
1062
+ // The agreement is measured BEFORE CRC-B7's demotion, not after it.
1063
+ //
1064
+ // The reviewer is not given the pull request's file list, so it cannot know
1065
+ // a finding is pre-existing and its `BLOCK` over one is honest. Comparing
1066
+ // its word against the post-demotion count would turn every successful
1067
+ // demotion into a CONTRADICTION — the arm would fire on the mechanism
1068
+ // working, which is the loudest possible way to be wrong.
1069
+ //
1070
+ // The real contradiction #1178 exists for is untouched: a `BLOCK` over a
1071
+ // payload whose findings are ALL advisory has `demoted === 0`, so it still
1072
+ // fires. Measured at roughly 6 of 20 runs when that was written.
1073
+ const wouldBlock = blocked || demoted > 0;
1074
+ const agreed = verdict === (wouldBlock ? AI_REVIEW_BLOCK_VERDICT : AI_REVIEW_PASS_VERDICT);
421
1075
  const outcome: AiReviewOutcome = !agreed ? "CONTRADICTION" : blocked ? "BLOCKED" : "CLEAN";
422
1076
 
423
1077
  return {
@@ -428,25 +1082,179 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
428
1082
  verdict,
429
1083
  unmeasuredReasons: [],
430
1084
  detail,
1085
+ // Both of these are `withScope`'s to set, and it is the only site that
1086
+ // sets either. A value here would be a second statement about the same
1087
+ // input, and the two could disagree.
1088
+ scope: scopeNotSupplied(),
1089
+ unlocatableReported: null,
1090
+ scopeDropped: null,
431
1091
  };
432
1092
  }
433
1093
 
1094
+ /**
1095
+ * The pull request's changed files, read from a newline-delimited file.
1096
+ *
1097
+ * `null` means the path was given and could not be read, which the caller
1098
+ * must NOT collapse into "no list was supplied" — see `readAiReviewFindings`
1099
+ * on why `undefined` and `[]` are different facts. This returns the third
1100
+ * one, and it is the same distinction a third time.
1101
+ *
1102
+ * Blank lines are dropped before the emptiness test, so a file containing
1103
+ * only whitespace reads as empty rather than as one unnamed file.
1104
+ */
1105
+ /**
1106
+ * One repository path, in the one spelling both sides of CRC-B7's comparison
1107
+ * are reduced to — or `null` for "this cannot be read as a repository path".
1108
+ *
1109
+ * **`null` is the important return.** The first cut of CRC-B7 compared
1110
+ * `String(finding.file).toLowerCase()` against a raw list, and every input
1111
+ * the comparison could not read demoted a `critical` to CLEAN, because a
1112
+ * spelling that is never in the set is indistinguishable from a file the
1113
+ * pull request did not touch. Measured against a list holding `lib/mine.ts`:
1114
+ *
1115
+ * ```
1116
+ * CLEAN 0 blocking {} 123 "./lib/mine.ts" "lib/mine.ts:12"
1117
+ * CLEAN 0 blocking "lib\mine.ts" "/lib/mine.ts"
1118
+ * ```
1119
+ *
1120
+ * Six for six, five of them the SAME FILE spelt differently. `./x`, `/x`,
1121
+ * `x` and `x:12` are one file and four strings, and an equality test over
1122
+ * raw strings answers a different question from the one being asked.
1123
+ *
1124
+ * So both sides go through here, and a `null` on either side is a refusal
1125
+ * rather than a mismatch. The git C-quoted form — `"lib/\303\251.ts"`, which
1126
+ * git emits for a non-ASCII path unless `core.quotePath=false` — is
1127
+ * deliberately `null` rather than unescaped here: decoding octal escapes to
1128
+ * compare a path is a second parser, and the right repair is to produce the
1129
+ * list with `-z` or `core.quotePath=false` in the first place.
1130
+ */
1131
+ export function normaliseRepoPath(value: unknown): string | null {
1132
+ if (typeof value !== "string") return null;
1133
+ let p = value.trim().replace(/\\/g, "/");
1134
+ // git's C-quoted spelling. Not comparable without a second unescaper.
1135
+ if (p.startsWith('"') && p.endsWith('"')) return null;
1136
+ p = p.replace(/^\/+/, "").replace(/:\d+(?::\d+)?$/, "");
1137
+
1138
+ // Dot segments are COLLAPSED, not stripped once. `.replace(/^\.\//, "")`
1139
+ // removes one leading `./` and leaves `././lib/a.ts` as `./lib/a.ts`, which
1140
+ // the shape test below accepts — `.` and `..` are both legal matches for
1141
+ // `[\w.@+-]+`. Measured on this file before the fix:
1142
+ //
1143
+ // "././lib/mine.ts" -> "./lib/mine.ts"
1144
+ // "lib/./mine.ts" -> "lib/./mine.ts"
1145
+ // "lib/../lib/mine.ts" -> "lib/../lib/mine.ts"
1146
+ //
1147
+ // Each compares unequal to `lib/mine.ts`, so a blocking finding naming the
1148
+ // file in one of those spellings was demoted to Pre-existing against a
1149
+ // change list that contained it — the same fail-open round one shipped,
1150
+ // in a narrower spelling. Found by the push review on this branch.
1151
+ //
1152
+ // A `..` that would leave the repository root is refused rather than
1153
+ // clamped: `../outside.ts` is not a repository-relative path, and turning
1154
+ // it into `outside.ts` invents a file this change may well have touched.
1155
+ const out: string[] = [];
1156
+ for (const segment of p.split("/")) {
1157
+ if (segment === "" || segment === ".") continue;
1158
+ if (segment === "..") {
1159
+ if (out.pop() === undefined) return null;
1160
+ continue;
1161
+ }
1162
+ out.push(segment);
1163
+ }
1164
+ p = out.join("/");
1165
+ if (p === "") return null;
1166
+
1167
+ return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p.toLowerCase() : null;
1168
+ }
1169
+
1170
+ /** What a changed-file list reduced to, split by whether it could be read. */
1171
+ export interface ChangedFilePartition {
1172
+ /**
1173
+ * The entries that normalised, in the one spelling both sides of the
1174
+ * comparison are reduced to. This is what `touched` is built from.
1175
+ */
1176
+ readable: string[];
1177
+ /**
1178
+ * The entries that did not, RAW and in list order — so the reader can be
1179
+ * NAMED to whoever has to fix the tree, rather than counted at them.
1180
+ */
1181
+ dropped: string[];
1182
+ }
1183
+
1184
+ /**
1185
+ * Split a changed-file list into the part this reader can compare against and
1186
+ * the part it cannot (#1472).
1187
+ *
1188
+ * **One exported binding, and the only place the split is decided.** A second
1189
+ * site answering "is this entry readable" would be two deciders over one
1190
+ * input, and a mutation of either would leave the other holding every case up
1191
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape). It is
1192
+ * exported so a battery has one thing to short-circuit.
1193
+ *
1194
+ * **Dropping is safe here and it is not an optimistic reading.** A narrower
1195
+ * `touched` can only demote MORE findings, never fewer — and the findings a
1196
+ * dropped entry could falsely demote are none at all, because BOTH sides of
1197
+ * the comparison go through `normaliseRepoPath`: an entry is dropped exactly
1198
+ * when it normalises to `null`, and a finding naming that same path
1199
+ * normalises to `null` too, which `readPayload` answers with *"it keeps
1200
+ * blocking: undecidable is not pre-existing"*. The set the drop could reach
1201
+ * and the set the drop cannot decide are the same set.
1202
+ *
1203
+ * What a drop must never be is SILENT. The caller carries `dropped` onto the
1204
+ * reading as `scopeDropped` and `aiReviewScopeLine` prints it on every run:
1205
+ * "this list was read in full" and "this list was read in part" are different
1206
+ * facts, and a reading over a narrowed set that does not say it was narrowed
1207
+ * is Silent Default Substitution (`.claude/rules/config-access.md`).
1208
+ */
1209
+ export function partitionChangedFiles(
1210
+ changedFiles: readonly string[],
1211
+ ): ChangedFilePartition {
1212
+ const readable: string[] = [];
1213
+ const dropped: string[] = [];
1214
+ for (const entry of changedFiles) {
1215
+ const normalised = normaliseRepoPath(entry);
1216
+ if (normalised === null) dropped.push(entry);
1217
+ else readable.push(normalised);
1218
+ }
1219
+ return { readable, dropped };
1220
+ }
1221
+
1222
+ // `readChangedFiles` lived here and is gone. It returned `null` for BOTH an
1223
+ // unreadable file and — via its caller — an empty one, and `main` reported
1224
+ // that single `null` as `CHANGED_FILES_EMPTY`. A failed `git diff` writes no
1225
+ // file at all, so that collapsed "the diff was lost" into "the diff was
1226
+ // empty", which are different facts with different repairs.
1227
+ // `readAiReviewChangedFiles` replaces it and keeps them apart.
1228
+
434
1229
  /** Read the payload from disk. An absent file and an unreadable one differ. */
435
- export function readAiReviewFindingsFile(path: string): AiReviewFindingsReading {
1230
+ export function readAiReviewFindingsFile(
1231
+ path: string,
1232
+ scope: AiReviewScopeReading = scopeNotSupplied(),
1233
+ ): AiReviewFindingsReading {
436
1234
  let raw: string;
437
1235
  try {
438
1236
  raw = readFileSync(path, "utf-8");
439
1237
  } catch (e) {
440
1238
  const code = (e as NodeJS.ErrnoException).code;
441
1239
  if (code === "ENOENT") {
442
- return unmeasured(["FINDINGS_FILE_ABSENT"], [`no findings payload at ${path}`]);
1240
+ return withScope(
1241
+ unmeasured(["FINDINGS_FILE_ABSENT"], [`no findings payload at ${path}`]),
1242
+ scope,
1243
+ null,
1244
+ null,
1245
+ );
443
1246
  }
444
- return unmeasured(
445
- ["FINDINGS_FILE_UNREADABLE"],
446
- [`the findings payload at ${path} could not be read: ${(e as Error).message}`],
1247
+ return withScope(
1248
+ unmeasured(
1249
+ ["FINDINGS_FILE_UNREADABLE"],
1250
+ [`the findings payload at ${path} could not be read: ${(e as Error).message}`],
1251
+ ),
1252
+ scope,
1253
+ null,
1254
+ null,
447
1255
  );
448
1256
  }
449
- return readAiReviewFindings(raw);
1257
+ return readAiReviewFindings(raw, scope);
450
1258
  }
451
1259
 
452
1260
  /** The sentence a refusal prints, or `null` when there is nothing to refuse. */
@@ -509,21 +1317,293 @@ export function aiReviewExitCode(reading: AiReviewFindingsReading): number {
509
1317
  return reading.outcome === "CLEAN" ? 0 : AI_REVIEW_REQUIRED_EXIT;
510
1318
  }
511
1319
 
1320
+ /** The annotation title the verifier quorum's own reading is printed under. */
1321
+ export const AI_REVIEW_JURY_NOTICE_TITLE = "AI review verifier quorum";
1322
+
512
1323
  /**
513
- * The CLI the generated workflow step runs: one argument, the payload's path.
1324
+ * The title the quorum's UNMEASURED state is named under.
514
1325
  *
515
- * Returns the exit code rather than calling `process.exit`, so a test can run
516
- * it in-process as well as spawn it.
1326
+ * A SEPARATE title, because it is a different fact with a different fix: a
1327
+ * group that met and disagreed is a reading, and a group that did not meet
1328
+ * is not one. GitHub groups annotations by title, so one title for both
1329
+ * would make the absence read as part of the vote.
1330
+ */
1331
+ export const AI_REVIEW_JURY_UNMEASURED_TITLE = "AI review verifier quorum UNMEASURED";
1332
+
1333
+ /**
1334
+ * The verifier quorum, as `main` consumes it (CRC-B4).
1335
+ *
1336
+ * **Injected, not imported**, and the reason is mechanical rather than
1337
+ * stylistic. This module is copied into a scratch directory by three
1338
+ * mutation batteries, which carry its one relative dependency —
1339
+ * `./ai-review-step`, which has none — along with it. `lib/ai-review-jury.ts`
1340
+ * pulls in the finding arbiter and the filing gate behind it, and a mutant
1341
+ * that dies on module resolution reports zero findings, which reads exactly
1342
+ * like a guard behaving differently
1343
+ * (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
1344
+ *
1345
+ * **The gate decides nothing.** It is consulted after the reading is
1346
+ * complete, its answer reaches an annotation and the finding ledger, and
1347
+ * `reading` is not rebuilt from it.
1348
+ *
1349
+ * So a gate that is absent, unreadable, malformed **or throwing** leaves
1350
+ * the verdict alone — and the last of those four is enforced by a `try`
1351
+ * at the call site rather than by this sentence. It is listed explicitly
1352
+ * because the first draft of this docblock claimed all four while only
1353
+ * three held: the call was outside any `catch`, so a throwing gate
1354
+ * propagated out of `main` and killed the process above the outcome
1355
+ * marker. A comment asserting a property the code lacks is the reason
1356
+ * nobody checks it — the instance this repository keeps is
1357
+ * `lib/cli-commands.ts`'s "runs every command for real" over a test that
1358
+ * ran one command of ten. `JG-6h` is now the assertion.
1359
+ *
1360
+ * That is the only honest arrangement while the group casting the votes
1361
+ * is not yet structurally independent. See `AI_REVIEW_JURY_NOTICE_TITLE`.
1362
+ *
1363
+ * **It takes the findings and nothing else.** The ballot directory is
1364
+ * bound by whoever supplies the gate, so this module never learns a path
1365
+ * and the CLI's argv contract — two positionals, `argv[2]` and up refused
1366
+ * — is untouched. A gate that is `null` is the whole of "no ballot".
1367
+ */
1368
+ export interface AiReviewJuryGate {
1369
+ (blocking: readonly unknown[]): {
1370
+ /**
1371
+ * One entry per blocking finding, **in input order** — the sentence
1372
+ * saying the group would have withheld it, or `null`.
1373
+ *
1374
+ * Positional rather than keyed, and that is the contract rather than a
1375
+ * convenience. A map from a finding identity would be a SECOND
1376
+ * derivation of that identity over a list already produced in order,
1377
+ * and two findings sharing a key would share a vote.
1378
+ * `lib/finding-arbiter.ts`'s `SHARED_BALLOT` refuses exactly that one
1379
+ * level down — *"a vote is about a finding"*.
1380
+ *
1381
+ * **"Would have".** Nothing here subtracts: the entry is recorded and
1382
+ * announced, and the finding blocks exactly as it did before the group
1383
+ * met.
1384
+ */
1385
+ wouldWithhold: readonly (string | null)[];
1386
+ /** Non-null when the ballot source could not be read. Never fatal. */
1387
+ unmeasured: string | null;
1388
+ /** One sentence per finding voted on. */
1389
+ detail: readonly string[];
1390
+ };
1391
+ }
1392
+
1393
+ /**
1394
+ * The line recording how the scope reading was taken, and the two counts a
1395
+ * reader needs to see differ when the gate fires (#1204).
1396
+ *
1397
+ * The number of findings PRODUCED and the number ALLOWED TO BLOCK are both
1398
+ * printed, because a review that quietly demoted a finding and a review that
1399
+ * never had one are otherwise the same output. The blocking count is
1400
+ * `withheld` under an UNMEASURED reading rather than `0` — the decision is
1401
+ * withheld there, and printing a number would be inventing one.
1402
+ *
1403
+ * It also reports its own COVERAGE of the changed-file list (#1472): a scan
1404
+ * that reports a verdict should say how much of its input it read. An entry
1405
+ * this reader could not normalise is dropped from the comparison rather than
1406
+ * refusing the whole run, so `dropped` is what keeps "the list was read in
1407
+ * full" apart from "the list was read in part" — and the entries are NAMED,
1408
+ * because a warning that does not say what was missing is a warning nobody
1409
+ * can act on. `not checked`, `0` and a named list are three facts, not one.
1410
+ */
1411
+ export function aiReviewScopeLine(reading: AiReviewFindingsReading): string {
1412
+ const produced = reading.reported?.length ?? 0;
1413
+ const blocking =
1414
+ reading.blockingReported === null ? "withheld" : String(reading.blockingReported.length);
1415
+ const unlocatable =
1416
+ reading.unlocatableReported === null ? "not checked" : String(reading.unlocatableReported.length);
1417
+ const drops = reading.scopeDropped;
1418
+ const dropped =
1419
+ drops === null
1420
+ ? "not checked"
1421
+ : drops.length === 0
1422
+ ? "0"
1423
+ : `${drops.length} (${drops.map(p => JSON.stringify(p)).join(", ")}), ` +
1424
+ `so this comparison ran over a NARROWER set than the pull request touched`;
1425
+ return (
1426
+ `${AI_REVIEW_SCOPE_LINE} ${reading.scope.status} — findings reported: ${produced}, ` +
1427
+ `allowed to block: ${blocking}, unlocatable: ${unlocatable}, ` +
1428
+ `changed-file entries dropped: ${dropped}. ${reading.scope.detail}`
1429
+ );
1430
+ }
1431
+
1432
+ // `parseFindingsArgv` and `AiReviewFindingsArgv` lived here and are gone.
1433
+ // The parser refused a SECOND POSITIONAL argument by design, which is
1434
+ // exactly the invocation CRC-B7 deploys, so the flag CLI and the
1435
+ // positional one could not both stand. See `main` below.
1436
+ //
1437
+ // What the parser ALSO did is kept, in `argumentsBeyondTheContract`: it
1438
+ // refused an argument nothing reads, rather than dropping it. Deleting the
1439
+ // parser silently took that with it — measured, not assumed, on the merged
1440
+ // tree: `main([payload, list, "extra"])` returned 0 and printed CLEAN. A
1441
+ // dropped argument is a caller asking for something that did not happen,
1442
+ // which is the same fault as a skipped check wearing different clothes.
1443
+
1444
+ /**
1445
+ * The arguments past the two this CLI reads. One exported binding, so the
1446
+ * refusal has a single site to mutate (`checks-must-be-able-to-fail.md`).
1447
+ *
1448
+ * It returns the arguments rather than a boolean because the refusal names
1449
+ * them: "an argument was ignored" is not something an operator can act on,
1450
+ * and the failing invocation is usually a workflow line nobody can see from
1451
+ * the log.
1452
+ */
1453
+ export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
1454
+ return argv.slice(2);
1455
+ }
1456
+
1457
+ /**
1458
+ * The CLI the generated workflow step runs: the payload's path, and
1459
+ * optionally a second POSITIONAL path to the pull request's changed files.
1460
+ *
1461
+ * Positional, not a `--changed-files` flag. #1204 wrote the flag and CRC-B7
1462
+ * wrote the positional; the generated step passes positionally and #1356
1463
+ * builds on that, so the flag is the spelling that goes. Two spellings for
1464
+ * one argument would be two deciders over the same input, and the one the
1465
+ * deployed workflow does not use is the one that would rot.
1466
+ *
1467
+ * The second argument is optional: a caller that does not pass one gets
1468
+ * exactly the reading this module gave before any of this was wired, which
1469
+ * is what keeps every existing consumer working unchanged.
1470
+ *
1471
+ * An unreadable list is NOT silently treated as absent, and `readAiReview-
1472
+ * ChangedFiles` is what keeps those apart — `CHANGED_FILES_UNREADABLE` for a
1473
+ * list that was named and could not be read, `CHANGED_FILES_EMPTY` for one
1474
+ * that was read and names nothing. A failed `git diff` writes no file at
1475
+ * all, so collapsing the two would report a diff that was lost as a diff
1476
+ * that was taken.
1477
+ *
1478
+ * An argument past those two REFUSES. Nothing reads it, and a CLI that
1479
+ * accepts an argument it ignores reports success for an invocation that did
1480
+ * not happen.
1481
+ *
1482
+ * Separate from `main` so the argv contract is decided in one place and
1483
+ * `main` is only the printing. A refusal reached here still prints the
1484
+ * outcome line and the scope line, because the generated step reads the
1485
+ * outcome line before it reads the exit code.
517
1486
  */
518
- export function main(argv: string[]): number {
1487
+ function readArgv(argv: string[]): AiReviewFindingsReading {
1488
+ const extra = argumentsBeyondTheContract(argv);
1489
+ if (extra.length > 0) {
1490
+ // Scope is NOT read here. The argv is already known to be a shape this
1491
+ // CLI does not accept, so which file argv[1] names is a question about
1492
+ // an invocation that is being refused.
1493
+ return withScope(
1494
+ unmeasured(
1495
+ ["ARGUMENTS_UNREADABLE"],
1496
+ [
1497
+ `${extra.length} argument(s) past the findings payload and the changed-file ` +
1498
+ `list were given and nothing reads them: ${extra.map(a => JSON.stringify(a)).join(", ")}. ` +
1499
+ `Usage: <path-to-findings.json> [<path-to-changed-files.txt>]`,
1500
+ ],
1501
+ ),
1502
+ scopeNotSupplied(),
1503
+ null,
1504
+ null,
1505
+ );
1506
+ }
1507
+
519
1508
  const path = argv[0];
520
- const reading =
521
- path === undefined || path === ""
522
- ? unmeasured(
1509
+ const scope = readAiReviewChangedFiles(argv[1]);
1510
+ return path === undefined || path === ""
1511
+ ? withScope(
1512
+ unmeasured(
523
1513
  ["FINDINGS_FILE_ABSENT"],
524
1514
  ["no findings payload path was given to the findings reader"],
525
- )
526
- : readAiReviewFindingsFile(path);
1515
+ ),
1516
+ scope,
1517
+ null,
1518
+ null,
1519
+ )
1520
+ : readAiReviewFindingsFile(path, scope);
1521
+ }
1522
+
1523
+ /**
1524
+ * The CLI entry point. `readArgv` above decides what the arguments mean;
1525
+ * everything here is emission.
1526
+ *
1527
+ * Returns the exit code rather than calling `process.exit`, so a test can run
1528
+ * it in-process as well as spawn it.
1529
+ */
1530
+ export function main(argv: string[], jury: AiReviewJuryGate | null = null): number {
1531
+ const reading = readArgv(argv);
1532
+
1533
+ // CRC-B4, AFTER the reading and feeding nothing back into it.
1534
+ //
1535
+ // The group votes on `blockingReported` — the existing decider's own
1536
+ // answer to "which of these block", never a list re-derived from the
1537
+ // severities, which is the criterion's first clause: a quorum over the
1538
+ // advisory tail spends a full agent context per nit.
1539
+ //
1540
+ // WHAT IT DOES NOT DO IS SUBTRACT, and that is a decision with two
1541
+ // reasons, both of them properties of the tree rather than of this
1542
+ // function:
1543
+ //
1544
+ // - **The group is not independent yet.** `AI_REVIEW_ALLOWED_TOOLS`
1545
+ // grants the review action `Read,Grep,Glob,Write` and
1546
+ // `AI_REVIEW_DENY_RULES` denies `Task`, so one invocation cannot spawn
1547
+ // verifiers. Independence has to be a property of the WORKFLOW — one
1548
+ // action invocation per verifier — and a ballot that subtracts before
1549
+ // that holds is a quorum wired to a constant: populated, plausible,
1550
+ // and filtering nothing. That is the counterfeit CRC-B4 names.
1551
+ // - **The verifier reads the head checkout.** A subtracting ballot would
1552
+ // make the branch under review an input to the gate on the branch
1553
+ // under review.
1554
+ //
1555
+ // So the votes are counted, written to the finding ledger at decision
1556
+ // time, and announced. Nothing below reads `gate` except the annotation.
1557
+ // CRC-B4's *"surfaced only if enough agree"* clause is therefore NOT
1558
+ // satisfied, and the spec says so rather than this comment alone.
1559
+ //
1560
+ // **The ballot directory is NOT a third positional argument**, and that
1561
+ // is deliberate rather than incidental. `argumentsBeyondTheContract`
1562
+ // refuses `argv[2]` and up, and one of the invocations it catches is a
1563
+ // changed-file path containing a space that an unquoted expansion
1564
+ // word-split into two — `test/ai-review-changed-files-step.test.ts`
1565
+ // CF-6 names that case. Widening the contract by one slot to carry a
1566
+ // ballot would turn that refusal into an accepted argv whose second
1567
+ // half is read as a ballot directory. So the directory binds at the
1568
+ // wrapper, which closes over it and hands this function a gate or
1569
+ // `null`; "no ballot" and "a ballot nothing reads" collapse into one
1570
+ // state that cannot be reached.
1571
+ let juryDetail: readonly string[] = [];
1572
+ let juryUnmeasured: string | null = null;
1573
+ if (jury !== null && reading.blockingReported !== null && reading.blockingReported.length > 0) {
1574
+ try {
1575
+ const gate = jury(reading.blockingReported);
1576
+ juryDetail = gate.detail;
1577
+ juryUnmeasured = gate.unmeasured;
1578
+ } catch (e) {
1579
+ // A FAIL-OPEN, DELIBERATELY, and this is the one arrangement where
1580
+ // that is the correct choice rather than the first thing
1581
+ // `.claude/rules/checks-must-be-able-to-fail.md` tells you to
1582
+ // distrust. Its warning is about a guard that converts its own
1583
+ // breakage into "no problems found". This gate finds no problems
1584
+ // and gates nothing: the verdict is `aiReviewExitCode(reading)`
1585
+ // either way, so catching here cannot hide a finding — it can only
1586
+ // stop an advisory recorder from deciding a review it has no vote
1587
+ // in. The day the ballot is allowed to subtract, this catch must
1588
+ // become a refusal, and that is the line to change.
1589
+ //
1590
+ // Without it the throw propagates out of `main`, so
1591
+ // `process.exit(main(...))` never runs and a CLEAN review dies
1592
+ // non-zero. Worse than the exit code: this block sits ABOVE the
1593
+ // `AI_REVIEW_OUTCOME_LINE` print, which the generated step greps
1594
+ // for before it will read an exit code as a verdict, so the step
1595
+ // sees an adjudicator that could not run rather than a verdict.
1596
+ //
1597
+ // Three things inside the real gate are outside any catch of their
1598
+ // own — `juryReading`, `advisoryKey` over a hostile payload, and
1599
+ // all of `juryLedgerRow`. `JG-6h` is this case.
1600
+ juryUnmeasured =
1601
+ `the verifier quorum threw and was not counted, so no vote was recorded for this ` +
1602
+ `run: ${(e as Error).message}. The verdict below is the adjudicator's own and is ` +
1603
+ `unchanged — the group decides nothing this round — but the votes for these findings ` +
1604
+ `are lost rather than merely unfavourable, and the ledger has no row to recover`;
1605
+ }
1606
+ }
527
1607
 
528
1608
  // FIRST, and before any branch below can return. The generated workflow step
529
1609
  // greps its own output for this prefix and will not read the exit code as a
@@ -531,6 +1611,16 @@ export function main(argv: string[]): number {
531
1611
  // refused both exit non-zero, and only this line tells them apart.
532
1612
  console.log(`${AI_REVIEW_OUTCOME_LINE} ${reading.outcome}`);
533
1613
 
1614
+ // AFTER the outcome line, and never instead of it. The generated step lifts
1615
+ // its verdict from the FIRST occurrence of that marker, so this line cannot
1616
+ // move it. Printed on EVERY run, including the one where no list was
1617
+ // supplied: an absent input that nothing reports is Silent Default
1618
+ // Substitution, and this line is the whole of what makes the skip a
1619
+ // reading. Escaped at emission like the annotation below — a path arriving
1620
+ // on the command line reaches a stream GitHub parses workflow commands out
1621
+ // of, and this module escapes exactly once, at the point of emission.
1622
+ console.log(escapeAnnotation(aiReviewScopeLine(reading)));
1623
+
534
1624
  // The ONE place a value reaches a workflow command. Everything upstream of
535
1625
  // here — `renderFinding`, every `detail` sentence, `aiReviewRefusal` — builds
536
1626
  // plain text and leaves escaping alone, so there is one binding to mutate and
@@ -540,6 +1630,55 @@ export function main(argv: string[]): number {
540
1630
  console.error(`::error title=${AI_REVIEW_FINDINGS_TITLE}::${escapeAnnotation(refusal)}`);
541
1631
  }
542
1632
 
1633
+ // AFTER the refusal and BEFORE the exit code, and on its own title. A
1634
+ // `::notice` rather than a `::warning` or an `::error`: the advisory tail
1635
+ // does not block, and a notice is what GitHub records against the check run
1636
+ // without changing its conclusion. It goes through the same single escaper
1637
+ // the refusal does — this is a new value reaching a workflow command, and
1638
+ // `escapeAnnotation`'s own docblock has the measured instance of what an
1639
+ // unescaped one can do to a verdict.
1640
+ const advisory = advisoryNotice(reading);
1641
+ if (advisory !== null) {
1642
+ console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
1643
+ }
1644
+
1645
+ // The quorum's own reading, on its own title, and emitted whatever the
1646
+ // outcome was. The ledger row is the durable record and it lives on the
1647
+ // runner, which dies with the job; this annotation is the only part of
1648
+ // the vote that outlives the run, so it carries the whole reading rather
1649
+ // than a count.
1650
+ //
1651
+ // A `::notice`, never an `::error`. The ballot decides nothing this round
1652
+ // and an annotation that reddened a check would be a gate arriving by the
1653
+ // back door — see the block above `juryDetail`.
1654
+ if (juryDetail.length > 0) {
1655
+ console.log(
1656
+ `::notice title=${AI_REVIEW_JURY_NOTICE_TITLE}::${escapeAnnotation(
1657
+ `A separate verifier group voted on the ${juryDetail.length} finding(s) that would ` +
1658
+ `otherwise block. ${juryDetail.join("; ")}. THE VOTE IS RECORDED AND CHANGES ` +
1659
+ `NOTHING: every finding above blocks exactly as it would have without it. The ` +
1660
+ `group is not yet structurally independent and reads the head checkout, so acting ` +
1661
+ `on it would be a gate whose input is the thing it gates.`,
1662
+ )}`,
1663
+ );
1664
+ }
1665
+
1666
+ // A `::warning`, and the state is NAMED. An absent or unreadable ballot
1667
+ // exiting 0 with no output is the Silent Default Substitution
1668
+ // `.claude/rules/config-access.md` forbids: `0`, `{}` and `null` are
1669
+ // indistinguishable from success and UNMEASURED is not. It does not
1670
+ // refuse, because the consumer decides whether an unmeasured quorum is
1671
+ // fatal and the honest default for a mechanism with no readings yet is an
1672
+ // annotation rather than a red pipeline.
1673
+ if (juryUnmeasured !== null) {
1674
+ console.log(
1675
+ `::warning title=${AI_REVIEW_JURY_UNMEASURED_TITLE}::${escapeAnnotation(
1676
+ `The verifier quorum is UNMEASURED for this run: ${juryUnmeasured}. No finding's ` +
1677
+ `status changed either way.`,
1678
+ )}`,
1679
+ );
1680
+ }
1681
+
543
1682
  return aiReviewExitCode(reading);
544
1683
  }
545
1684