rungate 0.8.2 → 0.8.4

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 (74) 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/BunTestPathGuard.hook.ts +106 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
@@ -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
@@ -86,6 +131,8 @@ import {
86
131
  AI_REVIEW_SEVERITIES,
87
132
  AI_REVIEW_SEVERITY_KEY,
88
133
  AI_REVIEW_VERDICT_KEY,
134
+ SEVERITY_RANK,
135
+ type Severity,
89
136
  } from "./ai-review-step";
90
137
 
91
138
  export {
@@ -97,7 +144,9 @@ export {
97
144
  AI_REVIEW_SEVERITIES,
98
145
  AI_REVIEW_SEVERITY_KEY,
99
146
  AI_REVIEW_VERDICT_KEY,
147
+ SEVERITY_RANK,
100
148
  };
149
+ export type { Severity };
101
150
 
102
151
  /**
103
152
  * Percent-encode a value before it is interpolated into a workflow command.
@@ -131,8 +180,25 @@ export const AI_REVIEW_DETAIL_MAX = 300;
131
180
  * site in `main()`, because two escapers applied in sequence turn `%` into
132
181
  * `%2525` and the bug that produces is invisible until someone reads a log.
133
182
  * One rule, one binding, applied last.
183
+ *
184
+ * `tag` is CRC-B7's Important / Nit / Pre-existing, appended AFTER the cap
185
+ * rather than before it. A tag inside the capped region is a tag a long
186
+ * summary deletes, and the one finding whose attribution a reader most needs
187
+ * is the verbose one — "this is not your bug" truncated away reads as "this
188
+ * is your bug". `null` renders nothing at all, because a finding whose
189
+ * severity the contract does not declare has no tag, and an empty bracket
190
+ * would read as one.
191
+ *
192
+ * The INDEX is the payload index and stays the payload index whatever the
193
+ * display order is. The refusal and the advisory notice share this numbering
194
+ * (#1178), so a sort that renumbered would make `finding 3` mean two
195
+ * different findings in two annotations about the same run.
134
196
  */
135
- export function renderFinding(index: number, finding: Record<string, unknown>): string {
197
+ export function renderFinding(
198
+ index: number,
199
+ finding: Record<string, unknown>,
200
+ tag: Severity | null = null,
201
+ ): string {
136
202
  const f = AI_REVIEW_FINDING_FIELDS;
137
203
  const where = finding[f.file] !== undefined
138
204
  ? `${String(finding[f.file])}:${String(finding[f.line] ?? "?")}`
@@ -141,7 +207,9 @@ export function renderFinding(index: number, finding: Record<string, unknown>):
141
207
  ? String(finding[f.summary])
142
208
  : "(no summary recorded)";
143
209
  const line = `finding ${index} is ${String(finding[f.severity])} at ${where}: ${what}`;
144
- return line.length > AI_REVIEW_DETAIL_MAX ? `${line.slice(0, AI_REVIEW_DETAIL_MAX)}…` : line;
210
+ const body =
211
+ line.length > AI_REVIEW_DETAIL_MAX ? `${line.slice(0, AI_REVIEW_DETAIL_MAX)}…` : line;
212
+ return tag === null ? body : `${body} [${tag}]`;
145
213
  }
146
214
 
147
215
  /**
@@ -172,12 +240,22 @@ export function renderFinding(index: number, finding: Record<string, unknown>):
172
240
  * arm is unreachable from `aiReviewRefusal`. It exists because the function
173
241
  * is exported and `unknown[]` is what it is handed: a renderer that throws
174
242
  * on a shape it was told it would never see is a refusal nobody can read.
243
+ *
244
+ * The result is indexed BY PAYLOAD INDEX and is deliberately not sorted here.
245
+ * Callers that display it order it with `tagOrder`, and they have to: this
246
+ * array is subscripted by `advisoryNotice` (`all[i]`, where `i` is the item's
247
+ * position in `reported`), so a sort applied inside would silently re-point
248
+ * every one of those lookups at a different finding. Rendering and ordering
249
+ * are separate jobs and the bug that merges them is invisible.
175
250
  */
176
- export function renderCountedFindings(reported: unknown[] | null): string[] {
251
+ export function renderCountedFindings(
252
+ reported: unknown[] | null,
253
+ tags: readonly (Severity | null)[] | null = null,
254
+ ): string[] {
177
255
  if (reported === null) return [];
178
256
  return reported.map((item, i) =>
179
257
  item !== null && typeof item === "object" && !Array.isArray(item)
180
- ? renderFinding(i, item as Record<string, unknown>)
258
+ ? renderFinding(i, item as Record<string, unknown>, tags?.[i] ?? null)
181
259
  : `finding ${i} is ${JSON.stringify(item)}`,
182
260
  );
183
261
  }
@@ -185,6 +263,191 @@ export function renderCountedFindings(reported: unknown[] | null): string[] {
185
263
  /** The annotation title the script prints its refusal under. */
186
264
  export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
187
265
 
266
+ /**
267
+ * The annotation title the advisory tail is printed under.
268
+ *
269
+ * A SEPARATE title from `AI_REVIEW_FINDINGS_TITLE`, deliberately. The refusal
270
+ * is a thing somebody has to act on before the pull request moves; this is a
271
+ * thing somebody has to answer before it merges, and GitHub groups
272
+ * annotations by title. One title for both would make the advisory tail
273
+ * read, in the checks UI, as part of the refusal — which is the misattribution
274
+ * `blockingContractViolations` is about, arriving from the other direction.
275
+ */
276
+ export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
277
+
278
+ /**
279
+ * A stable identity for one finding, so an answer can name it.
280
+ *
281
+ * @identity file+summary — whitespace-collapsed and case-folded, FNV-1a, 8
282
+ * hex characters. Total: every finding gets a key, and it is never `null`.
283
+ *
284
+ * **This is the ADJUDICATION key** — "has this advisory already been counted
285
+ * on this run". Within one payload there is only one version of the file, so
286
+ * the line genuinely does not matter, and keying on it would split one
287
+ * finding into two across a reformat.
288
+ *
289
+ * Its sibling is `carryKey` in `lib/ai-review-rounds.ts`, which is the
290
+ * PERSISTENCE key — "is the thing this round raised the thing the last round
291
+ * raised" — over `file` + the cited line's TEXT + `summary`, and partial: it
292
+ * returns `null` for a finding it cannot key, which this hash cannot do. The
293
+ * two were both called `findingKey` until #1398. They answer different
294
+ * questions and the collapse loses one; neither can quietly become the
295
+ * other, which was measured rather than assumed, but while they shared a
296
+ * name no call site could say which it had asked.
297
+ *
298
+ * CRC-B8 asks that every finding be answered — fixed, or resolved with a
299
+ * stated reason — and an answer has to name what it answers. The line number
300
+ * cannot be that name: the same finding moves line between rounds, which is
301
+ * exactly what #1319 measured (`bash-write-guard.ts:90 → :97` across two
302
+ * rounds of #1213 was *one* finding). So the key is over the file and the
303
+ * summary, whitespace-collapsed and case-folded, and it is deliberately NOT
304
+ * over the severity either — a reviewer that re-rates the same observation
305
+ * has not produced a second finding.
306
+ *
307
+ * FNV-1a, written out, rather than `node:crypto`. Not a preference: this
308
+ * module is copied into a temp directory by the mutation battery in
309
+ * `test/ai-review-advisory-findings.test.ts`, and every import it carries has
310
+ * to be carried with it. The property wanted is determinism and a short
311
+ * printable token, not collision resistance against an adversary.
312
+ *
313
+ * ## WHAT A COLLISION COSTS, and it is no longer only an annotation
314
+ *
315
+ * This docblock used to end *"a finding that forged another finding's key
316
+ * would buy the forger an answer on the wrong row, which is a worse
317
+ * annotation and not a bypass of anything."* That stopped being true the
318
+ * moment CRC-B4 made the verifier quorum read a ballot filed under this
319
+ * key: a collision between two BLOCKING findings would let one group's vote
320
+ * decide both. The sentence is corrected rather than deleted because a
321
+ * comment asserting a property the code no longer has is the reason nobody
322
+ * checks it — `lib/cli-commands.ts` carried *"runs every command for real"*
323
+ * over a test that ran one command of ten.
324
+ *
325
+ * What holds instead, and it is a property of the CALLER rather than of
326
+ * this hash: `juryGate` derives the identity once over the whole blocking
327
+ * set, refuses a key two of them share, and carries its decision back to
328
+ * the reader **by position**. So a collision is seen and both findings keep
329
+ * blocking; it cannot silently credit one finding's vote to another. The
330
+ * hash is still not adversary-resistant and is not asked to be — nothing
331
+ * downstream of it decides anything a collision could not already be
332
+ * refused for.
333
+ */
334
+ export function advisoryKey(finding: Record<string, unknown>): string {
335
+ const f = AI_REVIEW_FINDING_FIELDS;
336
+ const normalise = (v: unknown): string =>
337
+ String(v ?? "").trim().replace(/\s+/g, " ").toLowerCase();
338
+ const subject = `${normalise(finding[f.file])}\u0000${normalise(finding[f.summary])}`;
339
+ let hash = 0x811c9dc5;
340
+ for (let i = 0; i < subject.length; i++) {
341
+ hash ^= subject.charCodeAt(i);
342
+ hash = Math.imul(hash, 0x01000193) >>> 0;
343
+ }
344
+ return hash.toString(16).padStart(8, "0");
345
+ }
346
+
347
+ /**
348
+ * The findings this reading counted and did NOT act on — the advisory tail.
349
+ *
350
+ * `null`, never `[]`, when the complement cannot be taken. Under UNMEASURED
351
+ * `blockingReported` is `null` — a withheld decision, not an empty one — so
352
+ * subtracting it from `reported` would manufacture an advisory set out of
353
+ * findings nobody classified. Those are different facts and this module's
354
+ * whole philosophy is that they stay different.
355
+ *
356
+ * Computed by identity against `blockingReported` rather than by re-reading
357
+ * the severities. Re-reading them here would be a second decider over the one
358
+ * question `severityBlocks` already answers — the fourth shape in
359
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and a mutation of either
360
+ * would leave the other holding every case up.
361
+ */
362
+ export function advisoryReported(reading: AiReviewFindingsReading): unknown[] | null {
363
+ if (reading.reported === null || reading.blockingReported === null) return null;
364
+ const blocking = new Set(reading.blockingReported);
365
+ return reading.reported.filter(item => !blocking.has(item));
366
+ }
367
+
368
+ /**
369
+ * The sentence naming every advisory finding, or `null` when there is nothing
370
+ * to name.
371
+ *
372
+ * ## The silent drop this closes (CRC-B8)
373
+ *
374
+ * `AI_REVIEW_SEVERITIES` declares `medium`, `low` and `info` as advisory, and
375
+ * until this function existed a reading counted them and then dropped them.
376
+ * `detail` is populated inside `if (blocks)`; `aiReviewRefusal` returns `null`
377
+ * for CLEAN and lists only `detail` for BLOCKED. So `main()` printed the
378
+ * outcome line and nothing else, and a payload carrying seven `medium`
379
+ * findings produced **byte-identical output** to a payload carrying none.
380
+ * The payload itself lives under `$RUNNER_TEMP`, is uploaded nowhere (#1319
381
+ * measured zero artifacts) and dies with the runner, so the finding was not
382
+ * merely unreported — it was unrecoverable the moment the job ended.
383
+ *
384
+ * That is CRC-B8's second sentence failing in the live path: *a finding is
385
+ * never silently dropped*. It is also the reason the tail could not be
386
+ * answered rather than filed — you cannot resolve on the pull request a
387
+ * finding the pull request never shows you.
388
+ *
389
+ * ## Why CONTRADICTION returns null here
390
+ *
391
+ * The contradiction arm of `aiReviewRefusal` already prints EVERY counted
392
+ * finding, advisory ones included, through `renderCountedFindings` — #1178,
393
+ * and for a reason that still holds. Emitting this notice alongside it would
394
+ * print the advisory tail twice, and that module's own comment says why that
395
+ * is worse than printing it once: *a duplicate reads as two findings*. The
396
+ * rule lives here, in one function, rather than as a condition at the call
397
+ * site, so there is one binding to mutate.
398
+ *
399
+ * ## What this does NOT do
400
+ *
401
+ * It decides nothing. `aiReviewExitCode` is untouched and reads only the
402
+ * outcome, so an advisory finding does not block and cannot be made to block
403
+ * from here. Surfacing a finding and adjudicating one are different jobs, and
404
+ * this module already holds the second; a notice that quietly became a
405
+ * refusal would be a severity table nobody declared.
406
+ */
407
+ export function advisoryNotice(reading: AiReviewFindingsReading): string | null {
408
+ if (reading.outcome === "CONTRADICTION") return null;
409
+ const advisory = advisoryReported(reading);
410
+ if (advisory === null || advisory.length === 0) return null;
411
+
412
+ // Rendered through `renderCountedFindings` over the WHOLE list and then
413
+ // selected, rather than over the filtered list. Two reasons, and the second
414
+ // is the one that bites: the renderer numbers what it is given, so rendering
415
+ // the tail alone would renumber it from zero and `finding 3` in this notice
416
+ // would be a different finding from `finding 3` in a refusal. And selecting
417
+ // out of the full render means this notice and the contradiction arm's list
418
+ // come from one call of one function, which is what keeps them from drifting.
419
+ const reported = reading.reported ?? [];
420
+ const all = renderCountedFindings(reported, reading.findingTags);
421
+ // CRC-B7's sort, applied to the DISPLAY and not to the payload. `all` stays
422
+ // subscripted by payload index — `tagOrder` returns indices into it — so
423
+ // every line still says `finding <payload index>` and still agrees with the
424
+ // refusal's numbering. Reordering `advisory` itself and re-rendering would
425
+ // renumber the tail from zero, which AD-2 reds on.
426
+ const rendered = tagOrder(
427
+ reading.findingTags,
428
+ advisory.map(item => reported.indexOf(item)),
429
+ ).map(i => {
430
+ const item = reported[i];
431
+ const key =
432
+ item !== null && typeof item === "object" && !Array.isArray(item)
433
+ ? ` [key ${advisoryKey(item as Record<string, unknown>)}]`
434
+ : "";
435
+ return `${all[i]}${key}`;
436
+ });
437
+
438
+ return (
439
+ `${advisory.length} advisory finding(s) were counted and block nothing, ` +
440
+ `in Important / Pre-existing / Nit order. ` +
441
+ `${rendered.join("; ")}. ` +
442
+ `Each is UNANSWERED: nothing in this pipeline requires it to be fixed, ` +
443
+ `resolved with a reason, or filed, and this annotation is the only place ` +
444
+ `it survives the job — the payload lives under the runner's temp directory ` +
445
+ `and is uploaded nowhere. Answer each one on this pull request (fix it, or ` +
446
+ `say in a comment why it stands), naming its key. Filing an issue is the ` +
447
+ `exception, not the default.`
448
+ );
449
+ }
450
+
188
451
  /** The four states a reading can be in. Exactly one is reached per run. */
189
452
  export type AiReviewOutcome = "CLEAN" | "BLOCKED" | "CONTRADICTION" | "UNMEASURED";
190
453
 
@@ -200,8 +463,29 @@ export type AiReviewUnmeasuredReason =
200
463
  | "SEVERITY_ABSENT"
201
464
  | "SEVERITY_UNRECOGNISED"
202
465
  | "BLOCKING_FINDING_INCOMPLETE"
466
+ // `BLOCKING_FINDING_UNLOCATABLE` was here and is gone with the merge of
467
+ // #1204 into CRC-B7. Nothing produces it: a blocking finding naming a file
468
+ // outside the diff is DEMOTED to `Pre-existing` and the run stays readable,
469
+ // rather than refusing the whole reading. A member nothing emits is a state
470
+ // no test can reach, and `not.toContain` against it passes vacuously for
471
+ // ever — which is how a deleted check goes on looking guarded.
472
+ | "ARGUMENTS_UNREADABLE"
203
473
  | "VERDICT_ABSENT"
204
- | "VERDICT_UNRECOGNISED";
474
+ | "VERDICT_UNRECOGNISED"
475
+ /**
476
+ * A changed-file list was supplied and was EMPTY. A pull request always
477
+ * touches something, so `[]` is a reading that failed rather than a pull
478
+ * request that changed nothing — and taken at face value it would tag every
479
+ * finding `Pre-existing` and block none of them, which is the fail-open this
480
+ * module exists to refuse.
481
+ */
482
+ | "CHANGED_FILES_EMPTY"
483
+ /**
484
+ * A changed-file list entry could not be read as a repository path.
485
+ * Comparing against a list the reader cannot normalise would demote every
486
+ * finding, so the list being unreadable is a reading that failed.
487
+ */
488
+ | "CHANGED_FILES_UNREADABLE";
205
489
 
206
490
  /**
207
491
  * The fields a BLOCKING finding must carry, derived from the one contract map
@@ -247,6 +531,164 @@ export function blockingContractViolations(finding: Record<string, unknown>): st
247
531
  });
248
532
  }
249
533
 
534
+ // `AI_REVIEW_CHANGED_FILES_FLAG` lived here and is gone. #1204 argued for a
535
+ // FLAG over a second positional, citing #675: `--project-root <cwd>` "would
536
+ // arrive as a second positional and be read as a second payload".
537
+ //
538
+ // That hazard was CHECKED before the constant was removed, not waved away.
539
+ // `bin/rungate.ts` appends `--project-root` only when a command declares
540
+ // `projectRootFlag`, and `ai-review-findings` declares none — which is the
541
+ // very fact #1204 cited. So nothing injects a stray positional into THIS
542
+ // command, and the argument does not reach it.
543
+ //
544
+ // The positional wins because the deployed workflow passes one and #1356
545
+ // builds on that. Two spellings for one argument would be two deciders, and
546
+ // the spelling the generated step does not use is the one that would rot.
547
+
548
+ /**
549
+ * The prefix of the line recording how the scope reading was taken.
550
+ *
551
+ * Distinct from `AI_REVIEW_OUTCOME_LINE`, which the generated step lifts its
552
+ * verdict out of by parameter expansion on the FIRST occurrence of that
553
+ * marker. This line is printed after it and contains neither that marker nor
554
+ * a newline, so nothing about the verdict extraction moves.
555
+ */
556
+ export const AI_REVIEW_SCOPE_LINE = "ai-review findings scope:";
557
+
558
+ /** Whether the pull request's changed-file list was read, and if not, why. */
559
+ export type AiReviewScopeStatus = "MEASURED" | "NOT_SUPPLIED" | "UNMEASURED";
560
+
561
+ /**
562
+ * The changed-file reading. One discriminator, `status`, and the producing
563
+ * code's own sentence beside it.
564
+ *
565
+ * `NOT_SUPPLIED` and `UNMEASURED` are different facts with different fixes.
566
+ * Nobody handed this run a list is a property of the workflow that invoked
567
+ * it; a list that could not be read is a property of this run. Collapsing
568
+ * them would make a release in which the input does not exist yet look like
569
+ * a `git diff` that failed.
570
+ */
571
+ export type AiReviewScopeReading =
572
+ | { status: "NOT_SUPPLIED"; files: null; detail: string; reason: null }
573
+ | { status: "MEASURED"; files: string[]; detail: string; reason: null }
574
+ | {
575
+ status: "UNMEASURED";
576
+ files: null;
577
+ detail: string;
578
+ reason: Extract<
579
+ AiReviewUnmeasuredReason,
580
+ "CHANGED_FILES_UNREADABLE" | "CHANGED_FILES_EMPTY"
581
+ >;
582
+ };
583
+
584
+ /** The reading for a run nobody handed a changed-file list. */
585
+ export function scopeNotSupplied(): AiReviewScopeReading {
586
+ return {
587
+ status: "NOT_SUPPLIED",
588
+ files: null,
589
+ reason: null,
590
+ detail:
591
+ `no changed-file list was given (second positional argument), so whether ` +
592
+ `a blocking finding names a file this pull request touches was not checked. ` +
593
+ `This is a reading, not a pass: the generated job does not supply the list yet`,
594
+ };
595
+ }
596
+
597
+ /**
598
+ * The reading for a run whose changed-file list was supplied directly rather
599
+ * than read from disk.
600
+ *
601
+ * Exists so a caller holding an array does not have to spell the discriminated
602
+ * union by hand. `files` is carried raw; `readPayload` normalises.
603
+ *
604
+ * An EMPTY array is still MEASURED here and is refused downstream, on purpose:
605
+ * "a list was supplied and it was empty" is a fact this type can represent and
606
+ * `readAiReviewChangedFiles` cannot produce, so the refusal lives where every
607
+ * caller passes through rather than only on the disk path.
608
+ */
609
+ export function scopeMeasured(files: readonly string[]): AiReviewScopeReading {
610
+ return {
611
+ status: "MEASURED",
612
+ files: [...files],
613
+ reason: null,
614
+ detail: `${files.length} changed path(s) supplied directly`,
615
+ };
616
+ }
617
+
618
+ /**
619
+ * Read the changed-file list from disk. Three states, each its own fact.
620
+ *
621
+ * A list that could not be read REFUSES and must never produce an empty list:
622
+ * an empty changed set makes every blocking finding unlocatable, which is the
623
+ * loud direction and loud for the wrong reason — it reads as the reviewer
624
+ * having hallucinated every finding it wrote.
625
+ *
626
+ * A list that WAS read and names no paths refuses too, under its own reason.
627
+ * A pull request that changes nothing is not a state this input can honestly
628
+ * be in, so an empty file is a diff that was lost rather than a diff that was
629
+ * empty — and the two reasons are kept apart because the fixes differ.
630
+ *
631
+ * The list must be taken from the RESTORED tree, before the reviewer could
632
+ * have written to the checkout. That is why this function is handed a path
633
+ * and never takes the diff itself: this module runs after the review, from
634
+ * the payload's own directory, so a diff computed here is one the subject of
635
+ * the review had an opportunity to edit.
636
+ */
637
+ export function readAiReviewChangedFiles(path: string | undefined): AiReviewScopeReading {
638
+ if (path === undefined || path === "") return scopeNotSupplied();
639
+
640
+ let raw: string;
641
+ try {
642
+ raw = readFileSync(path, "utf-8");
643
+ } catch (e) {
644
+ return {
645
+ status: "UNMEASURED",
646
+ files: null,
647
+ reason: "CHANGED_FILES_UNREADABLE",
648
+ detail:
649
+ `the changed-file list at ${path} could not be read: ${(e as Error).message}. ` +
650
+ `A diff that could not be taken is not a pull request that touches nothing`,
651
+ };
652
+ }
653
+
654
+ // Entries are carried RAW, trimmed only. This function decides whether the
655
+ // list is a reading; `readPayload` decides what each path means, through
656
+ // `normaliseRepoPath`. Normalising here too would be two normalisers over
657
+ // one input — and the weaker one would win silently, because it runs first.
658
+ // `normaliseRepoPath` collapses dot segments, strips a `:line` suffix and
659
+ // refuses git's C-quoted form; stripping `./` is the only thing the reader
660
+ // that used to live here could do.
661
+ const files = raw.split("\n").map(l => l.trim()).filter(p => p.length > 0);
662
+ if (files.length === 0) {
663
+ return {
664
+ status: "UNMEASURED",
665
+ files: null,
666
+ reason: "CHANGED_FILES_EMPTY",
667
+ detail:
668
+ `the changed-file list at ${path} names no paths at all. A pull request that ` +
669
+ `changes nothing is not a state this input can be in, so the diff was taken and ` +
670
+ `lost rather than taken and empty — and reading it as empty would report every ` +
671
+ `blocking finding as naming a file outside the pull request`,
672
+ };
673
+ }
674
+
675
+ return {
676
+ status: "MEASURED",
677
+ files,
678
+ reason: null,
679
+ detail: `${files.length} changed path(s) read from ${path}`,
680
+ };
681
+ }
682
+
683
+ // `unlocatableBlockingFinding` lived here and is gone. It was #1204's
684
+ // refusal predicate, and the merge with CRC-B7 retired the refusal; the
685
+ // comparison it performed now happens inside `readPayload` against
686
+ // `normaliseRepoPath`, which is the stronger reader. Deleted rather than
687
+ // left exported with no caller — `lib/ai-review-rounds.ts` (CRC-N4) and
688
+ // `lib/finding-jury.ts` (CRC-B4) are both open issues about exactly that,
689
+ // and adding a third would be the cheapest way to pretend this merge kept
690
+ // more than it did.
691
+
250
692
  export interface AiReviewFindingsReading {
251
693
  /** The single discriminator. Everything else is a projection of the same pass. */
252
694
  outcome: AiReviewOutcome;
@@ -265,6 +707,48 @@ export interface AiReviewFindingsReading {
265
707
  unmeasuredReasons: AiReviewUnmeasuredReason[];
266
708
  /** The producing code's own sentences, one per reason or blocking finding. */
267
709
  detail: string[];
710
+ /** How the pull request's changed-file list was read, and whether it was. */
711
+ scope: AiReviewScopeReading;
712
+ /**
713
+ * Blocking findings naming a file the pull request does not touch — CARRIED,
714
+ * never dropped, and `null` when the scope check did not run.
715
+ *
716
+ * `null` rather than `[]` for the did-not-run case on purpose: an empty list
717
+ * and a check nobody performed are the states this module exists to keep
718
+ * apart. `scope.status` is the discriminator; this is a projection of it.
719
+ */
720
+ unlocatableReported: unknown[] | null;
721
+ /**
722
+ * Changed-file entries this reader could not normalise and DROPPED from the
723
+ * comparison set (#1472) — RAW, named, in list order.
724
+ *
725
+ * Three states, and the middle one is the reason this is not a count.
726
+ * `null` is "no list was supplied, so nothing was read in full or in part";
727
+ * `[]` is "a list was read and every entry of it was comparable"; a
728
+ * non-empty list is "a list was read and these entries were not", which is
729
+ * a reading over a NARROWER set than the pull request actually touched. A
730
+ * reading that narrowed itself and did not say so is indistinguishable from
731
+ * a complete one — `.claude/rules/config-access.md`'s *Silent Default
732
+ * Substitution*, in the place it decides a required check.
733
+ */
734
+ scopeDropped: string[] | null;
735
+ /**
736
+ * CRC-B7's tag for each entry of `reported`, BY PAYLOAD INDEX, or `null`
737
+ * when there was no payload to tag.
738
+ *
739
+ * Parallel to `reported` rather than keyed, for the reason
740
+ * `AiReviewJuryGate.wouldWithhold` is positional: a map from a finding
741
+ * identity would be a second derivation of that identity over a list
742
+ * already produced in order, and two findings sharing a key would share a
743
+ * tag. An entry is `null` when the finding's severity is one the contract
744
+ * does not declare — unclassified, which is not the same as `Nit`.
745
+ *
746
+ * Computed ONCE, during the payload pass, where `touched` exists. A
747
+ * renderer that re-derived it would have to rebuild the changed-path set,
748
+ * which is a second normaliser over the one input `partitionChangedFiles`
749
+ * already reduced.
750
+ */
751
+ findingTags: (Severity | null)[] | null;
268
752
  }
269
753
 
270
754
  /**
@@ -279,10 +763,135 @@ export function severityBlocks(severity: unknown): boolean | null {
279
763
  return blocks === undefined ? null : blocks;
280
764
  }
281
765
 
766
+ /**
767
+ * Whether a finding names code this pull request touched. FOUR states, and
768
+ * the first two are the ones a boolean would destroy.
769
+ *
770
+ * `NOT_CHECKED` is "nobody handed this run a changed-file list", and
771
+ * `UNDECIDABLE` is "a list was read and this finding's path could not be
772
+ * compared to it". Neither is `PRE_EXISTING`, and collapsing either into it
773
+ * is the fail-open CRC-B7's first cut shipped: a spelling the comparison
774
+ * cannot read is never in the set, so every unreadable input demoted a
775
+ * `critical` to CLEAN. The direction this stage is allowed to be wrong in is
776
+ * toward blocking.
777
+ *
778
+ * **ONE binding, and the only place the question is answered.** `readPayload`
779
+ * asks it to decide whether a blocking finding is demoted; `findingTag` asks
780
+ * it to decide what the finding is labelled. Two sites answering it
781
+ * separately would be the fourth shape in
782
+ * `.claude/rules/checks-must-be-able-to-fail.md` — behaviourally one decider,
783
+ * of which a mutation leaves the other holding every case up — and they would
784
+ * be free to disagree, which is a run whose annotation says `Pre-existing`
785
+ * about a finding that blocked it.
786
+ *
787
+ * Both sides of the comparison go through `normaliseRepoPath`, which is also
788
+ * what makes the drop in `partitionChangedFiles` safe: an entry is dropped
789
+ * exactly when it normalises to `null`, and a finding naming that same path
790
+ * answers `UNDECIDABLE` here.
791
+ */
792
+ export type FindingPathScope = "NOT_CHECKED" | "UNDECIDABLE" | "IN_DIFF" | "PRE_EXISTING";
793
+
794
+ export function findingPathScope(
795
+ finding: Record<string, unknown>,
796
+ touched: ReadonlySet<string> | null,
797
+ ): FindingPathScope {
798
+ if (touched === null) return "NOT_CHECKED";
799
+ // `normaliseRepoPath` answers `null` for a non-string as well as for a
800
+ // string it cannot read, so there is no separate type test here. Whether a
801
+ // non-string `file` is additionally a CONTRACT violation is a different
802
+ // question with a different answer per severity, and `readPayload` owns it.
803
+ const named = normaliseRepoPath(finding[AI_REVIEW_FINDING_FIELDS.file]);
804
+ if (named === null) return "UNDECIDABLE";
805
+ return touched.has(named) ? "IN_DIFF" : "PRE_EXISTING";
806
+ }
807
+
808
+ /**
809
+ * CRC-B7's tag for one finding — `Important`, `Nit` or `Pre-existing`.
810
+ *
811
+ * A COMPOSITION of the two deciders that already exist, and not a third
812
+ * table. Attribution is asked first because it outranks magnitude: a defect
813
+ * the change did not introduce is `Pre-existing` whether it is `critical` or
814
+ * `info`, which is the whole of "a pre-existing bug does not read as the
815
+ * author's fault". Below that the tag is `severityBlocks`' own answer
816
+ * re-spelt — blocking is `Important`, advisory is `Nit` — read from
817
+ * `AI_REVIEW_SEVERITIES` rather than from a second list of severity words.
818
+ *
819
+ * `null` for a severity the contract does not declare. That reading is
820
+ * already UNMEASURED by the time anything displays it, and a guessed
821
+ * `Important` would be the module inventing the classification it refuses the
822
+ * payload for omitting.
823
+ *
824
+ * Applied to EVERY finding, advisory ones included, which is wider than the
825
+ * demotion in `readPayload` and deliberately so: the demotion changes what
826
+ * blocks and must only ever touch findings that would block, while the tag
827
+ * changes what a maintainer reads and an `info` about code on `main` is
828
+ * misattributed exactly as badly as a `critical` is. It decides nothing —
829
+ * `aiReviewExitCode` never sees it.
830
+ */
831
+ export function findingTag(
832
+ finding: Record<string, unknown>,
833
+ touched: ReadonlySet<string> | null,
834
+ ): Severity | null {
835
+ if (findingPathScope(finding, touched) === "PRE_EXISTING") return "Pre-existing";
836
+ const blocks = severityBlocks(finding[AI_REVIEW_SEVERITY_KEY]);
837
+ return blocks === null ? null : blocks ? "Important" : "Nit";
838
+ }
839
+
840
+ /**
841
+ * The rank an untagged finding sorts at — below every declared tag, derived
842
+ * from the table rather than written as a literal, so a fourth tag does not
843
+ * leave this number sitting in the middle of the order.
844
+ */
845
+ export const UNTAGGED_RANK = Object.keys(SEVERITY_RANK).length;
846
+
847
+ /**
848
+ * CRC-B7's sort: payload indices, in the order they should be DISPLAYED.
849
+ *
850
+ * Indices rather than rendered strings, because the index is the one thing
851
+ * the display order must not change. `renderFinding` prints `finding
852
+ * <payload index>` and the blocking annotation and the advisory notice share
853
+ * that numbering, so this reorders the lines and renumbers nothing —
854
+ * `test/ai-review-advisory-findings.test.ts` AD-2 reds on the other
855
+ * arrangement, correctly.
856
+ *
857
+ * **ONE comparator, exported, and the only ordering in this module.** The
858
+ * ties break on the payload index rather than on `Array.prototype.sort`'s
859
+ * stability, so the order is a total function of the input: a run that
860
+ * printed findings in one order and a re-run that printed them in another
861
+ * would be two readings of one payload.
862
+ */
863
+ export function tagOrder(
864
+ tags: readonly (Severity | null)[] | null,
865
+ indices: readonly number[],
866
+ ): number[] {
867
+ const rankOf = (i: number): number => {
868
+ const tag = tags?.[i] ?? null;
869
+ return tag === null ? UNTAGGED_RANK : SEVERITY_RANK[tag];
870
+ };
871
+ return [...indices].sort((a, b) => rankOf(a) - rankOf(b) || a - b);
872
+ }
873
+
874
+ /**
875
+ * Every finding's tag, by payload index. Non-objects tag `null`: they are
876
+ * already a `FINDING_NOT_AN_OBJECT` reason, and a shape with no severity has
877
+ * no tag to carry.
878
+ */
879
+ function tagsForPayload(
880
+ list: readonly unknown[],
881
+ touched: ReadonlySet<string> | null,
882
+ ): (Severity | null)[] {
883
+ return list.map(item =>
884
+ item !== null && typeof item === "object" && !Array.isArray(item)
885
+ ? findingTag(item as Record<string, unknown>, touched)
886
+ : null,
887
+ );
888
+ }
889
+
282
890
  function unmeasured(
283
891
  reasons: AiReviewUnmeasuredReason[],
284
892
  detail: string[],
285
893
  reported: unknown[] | null = null,
894
+ findingTags: (Severity | null)[] | null = null,
286
895
  ): AiReviewFindingsReading {
287
896
  return {
288
897
  outcome: "UNMEASURED",
@@ -292,21 +901,169 @@ function unmeasured(
292
901
  verdict: null,
293
902
  unmeasuredReasons: reasons,
294
903
  detail,
904
+ scope: scopeNotSupplied(),
905
+ unlocatableReported: null,
906
+ scopeDropped: null,
907
+ findingTags,
295
908
  };
296
909
  }
297
910
 
911
+ /**
912
+ * The ONE place a scope reading meets a payload reading.
913
+ *
914
+ * Every reading is built carrying the NOT_SUPPLIED default and passes through
915
+ * here. A second site that set `scope`, or that raised a reading on a refused
916
+ * scope, would be a second statement about the same input and the two could
917
+ * disagree.
918
+ *
919
+ * A scope reading that REFUSES raises the whole reading, carrying the
920
+ * payload's own reasons and findings with it rather than replacing them:
921
+ * "the diff could not be taken" and "the payload is not JSON" are both true
922
+ * of such a run, and a reader fixing one needs to see the other.
923
+ */
924
+ function withScope(
925
+ reading: AiReviewFindingsReading,
926
+ scope: AiReviewScopeReading,
927
+ unlocatableReported: unknown[] | null,
928
+ scopeDropped: string[] | null,
929
+ ): AiReviewFindingsReading {
930
+ const merged =
931
+ scope.status === "UNMEASURED"
932
+ ? unmeasured(
933
+ [...reading.unmeasuredReasons, scope.reason],
934
+ [...reading.detail, scope.detail],
935
+ reading.reported,
936
+ reading.findingTags,
937
+ )
938
+ : reading;
939
+ return { ...merged, scope, unlocatableReported, scopeDropped };
940
+ }
941
+
298
942
  /**
299
943
  * Read a findings payload and decide what it means.
300
944
  *
301
945
  * `raw` is `null` for "there was no payload at all", which is a reading and
302
946
  * not an error: a job whose reviewer never wrote anything has not passed a
303
947
  * review, it has not had one.
948
+ *
949
+ * `scope` is the pull request's changed-file reading, and what this function
950
+ * DOES with it is CRC-B7 (CODE-REVIEW-CONVERGENCE-SPEC): a finding naming no
951
+ * file this pull request touched is tagged `Pre-existing` and does not block,
952
+ * so a bug that was already on `main` does not read as the change's fault.
953
+ * `ai-review` reads the MERGE REF, so without this every defect on `main` is
954
+ * reported against whichever pull request is standing closest — nine of them
955
+ * at once on 2026-10-23.
956
+ *
957
+ * ## #1204 and CRC-B7 answered the same question and this merge picked one
958
+ *
959
+ * Both asked *does this finding apply to this pull request?* over the same
960
+ * input. #1204 refused — `BLOCKING_FINDING_UNLOCATABLE`, a red required
961
+ * check. CRC-B7 demotes. **CRC-B7 owns the case**, because #1204's answer
962
+ * makes its own motivating measurement worse: under it each of those nine
963
+ * findings becomes a REFUSING required check, so every pull request standing
964
+ * near a defect on `main` is unmergeable until somebody fixes `main`. That is
965
+ * worse than the state it was fixing. CRC-B7 also grades the error direction,
966
+ * which the refusal does not: an undecidable path keeps blocking, and a
967
+ * non-string path is a contract violation rather than a demotion input.
968
+ *
969
+ * What #1204 keeps is the INPUT layer — `scope`, three states as a type
970
+ * rather than as conventions over a nullable array. It is the only side that
971
+ * can tell "nobody handed this run a list" from "every finding was
972
+ * locatable", and those are the two readings a green check must not conflate.
973
+ * It defaults to NOT_SUPPLIED, under which nothing is demoted and the reading
974
+ * is exactly what it was before any of this existed.
975
+ *
976
+ * The finding's DECLARED `file` is the input, not a path mined out of its
977
+ * prose. `blockingContractViolations` already refuses a blocking finding that
978
+ * carries none, and `lib/finding-jury.ts`'s `citedPaths` text-mines only
979
+ * because the arbiter's findings arrive as prose. Mining a field the payload
980
+ * declares would be a second decider for a question already answered.
304
981
  */
305
- export function readAiReviewFindings(raw: string | null): AiReviewFindingsReading {
982
+ export function readAiReviewFindings(
983
+ raw: string | null,
984
+ scope: AiReviewScopeReading = scopeNotSupplied(),
985
+ ): AiReviewFindingsReading {
986
+ const preExisting: unknown[] = [];
987
+ // Appended to by `readPayload`, for the same reason `preExisting` is: the
988
+ // entries belong to the reading its caller composes, and every early return
989
+ // in there is a state in which the split had not happened yet.
990
+ const dropped: string[] = [];
991
+ const base = readPayload(
992
+ raw,
993
+ scope.status === "MEASURED" ? scope.files : undefined,
994
+ preExisting,
995
+ dropped,
996
+ );
997
+ return withScope(
998
+ base,
999
+ scope,
1000
+ scope.status === "MEASURED" ? preExisting : null,
1001
+ scope.status === "MEASURED" ? dropped : null,
1002
+ );
1003
+ }
1004
+
1005
+ /**
1006
+ * The payload pass itself. `preExisting` is appended to rather than returned,
1007
+ * because the findings it collects belong to the reading its caller composes
1008
+ * and every early return here is a state in which none were collected.
1009
+ *
1010
+ * It holds the findings CRC-B7 demoted. A COUNT would not do: "three were
1011
+ * demoted" and "these three were demoted" differ exactly when somebody wants
1012
+ * to know whether the demotion was right, which is the only question anybody
1013
+ * asks of a demotion.
1014
+ */
1015
+ function readPayload(
1016
+ raw: string | null,
1017
+ changedFiles: readonly string[] | undefined,
1018
+ preExisting: unknown[],
1019
+ dropped: string[],
1020
+ ): AiReviewFindingsReading {
306
1021
  if (raw === null) {
307
1022
  return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
308
1023
  }
309
1024
 
1025
+ if (changedFiles !== undefined && changedFiles.length === 0) {
1026
+ return unmeasured(
1027
+ ["CHANGED_FILES_EMPTY"],
1028
+ [
1029
+ "a changed-file list was supplied and was empty. A pull request always touches " +
1030
+ "something, so this is a reading that failed rather than a pull request that " +
1031
+ "changed nothing — and taken at face value every finding would be tagged " +
1032
+ "Pre-existing and none would block.",
1033
+ ],
1034
+ );
1035
+ }
1036
+ let touched: Set<string> | null = null;
1037
+ if (changedFiles !== undefined) {
1038
+ // #1472. ONE unnormalisable entry used to refuse the WHOLE reading, so a
1039
+ // repository holding a single tracked path with a space in it could never
1040
+ // obtain a scope reading at all — `docs/my file.md` was enough, and the
1041
+ // remedy the refusal named (`-z`, `core.quotePath=false`) does not apply,
1042
+ // because git emits a space literally and the regex rejects it literally.
1043
+ //
1044
+ // The comparison is PER FINDING, so one bad entry says nothing about the
1045
+ // others. The entry is dropped, the drop is NAMED, and the findings over
1046
+ // normalisable paths are adjudicated as before.
1047
+ const { readable, dropped: unreadable } = partitionChangedFiles(changedFiles);
1048
+ dropped.push(...unreadable);
1049
+ // The refusal is NARROWED, not deleted. With nothing readable left,
1050
+ // `touched` is empty, every finding is tagged Pre-existing and the run
1051
+ // reports a green check for a review that found something — which is the
1052
+ // one input the original refusal was right about.
1053
+ if (readable.length === 0) {
1054
+ return unmeasured(
1055
+ ["CHANGED_FILES_UNREADABLE"],
1056
+ [
1057
+ `all ${unreadable.length} changed-file entr(ies) could not be read as a repository ` +
1058
+ `path: ${unreadable.map(p => JSON.stringify(p)).join(", ")}. ` +
1059
+ `Comparing against a list with nothing readable left in it would tag every ` +
1060
+ `finding Pre-existing. Produce the list with -z or core.quotePath=false`,
1061
+ ],
1062
+ );
1063
+ }
1064
+ touched = new Set(readable);
1065
+ }
1066
+
310
1067
  let doc: unknown;
311
1068
  try {
312
1069
  doc = JSON.parse(raw);
@@ -349,6 +1106,8 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
349
1106
  const reasons: AiReviewUnmeasuredReason[] = [];
350
1107
  const detail: string[] = [];
351
1108
  const blocking: unknown[] = [];
1109
+ /** How many findings CRC-B7 demoted. See the `agreed` computation below. */
1110
+ let demoted = 0;
352
1111
 
353
1112
  list.forEach((item, i) => {
354
1113
  if (item === null || typeof item !== "object" || Array.isArray(item)) {
@@ -390,8 +1149,84 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
390
1149
  );
391
1150
  return;
392
1151
  }
1152
+ // CRC-B7, and AFTER the contract check rather than before it. A finding
1153
+ // with no declared `file` cannot be tagged either way, and it has
1154
+ // already been refused as incomplete one branch up — so by here `file`
1155
+ // is known present, and the tag is decidable rather than guessed.
1156
+ //
1157
+ // It DEMOTES, it does not drop (CRC-B8). The finding stays in
1158
+ // `reported`, so `advisoryReported` carries it into the notice and a
1159
+ // maintainer still sees it; it simply stops reddening a required check
1160
+ // over a defect the diff did not introduce and cannot fix.
1161
+ if (touched !== null) {
1162
+ const declared = finding[AI_REVIEW_FINDING_FIELDS.file];
1163
+ // A non-string `file` is a CONTRACT violation, not a demotion input.
1164
+ // `blockingContractViolations` refuses `undefined`, `null` and the
1165
+ // empty string and lets a number or an object through, so without
1166
+ // this a finding declaring `file: {}` stringifies to
1167
+ // `[object Object]`, matches nothing, and demotes itself.
1168
+ if (typeof declared !== "string") {
1169
+ reasons.push("BLOCKING_FINDING_INCOMPLETE");
1170
+ detail.push(
1171
+ `finding ${i} blocks and declares a non-string ` +
1172
+ `'${AI_REVIEW_FINDING_FIELDS.file}' (${typeof declared}). A path that is not a ` +
1173
+ `string cannot be compared to the changed-file list, and a comparison that ` +
1174
+ `cannot be made is not a finding that is pre-existing`,
1175
+ );
1176
+ return;
1177
+ }
1178
+ // THE one decider, shared with `findingTag`. Re-reading the path
1179
+ // here would let the demotion and the tag disagree about one finding.
1180
+ const scoped = findingPathScope(finding, touched);
1181
+ // Undecidable is NOT pre-existing. The finding is well-formed and
1182
+ // this reader simply cannot resolve its path, so it keeps blocking —
1183
+ // the direction this stage is allowed to be wrong in.
1184
+ if (scoped === "UNDECIDABLE") {
1185
+ detail.push(
1186
+ `finding ${i} declares ${JSON.stringify(declared)}, which could not be read as a ` +
1187
+ `repository path, so it could not be compared to the changed-file list. It ` +
1188
+ `keeps blocking: undecidable is not pre-existing`,
1189
+ );
1190
+ } else if (scoped === "PRE_EXISTING") {
1191
+ demoted += 1;
1192
+ // #1204's half that survived the merge: WHICH findings were
1193
+ // demoted, not just how many. The scope line reports it, so a
1194
+ // reader can ask whether a demotion was right — the only question
1195
+ // anybody asks of one.
1196
+ preExisting.push(item);
1197
+ detail.push(
1198
+ `finding ${i} is Pre-existing: it names ${JSON.stringify(
1199
+ finding[AI_REVIEW_FINDING_FIELDS.file],
1200
+ )}, which this pull request does not touch. It is reported and does not block — ` +
1201
+ `ai-review reads the merge ref, so a defect already on the base branch is ` +
1202
+ `adjudicated against whichever pull request is standing closest to it`,
1203
+ );
1204
+ return;
1205
+ }
1206
+ }
1207
+ // CRC-B4's verifier quorum does NOT appear here, and its absence is
1208
+ // the decision rather than an omission.
1209
+ //
1210
+ // A quorum that subtracts from this list is a gate whose input is the
1211
+ // thing it gates: the verifier reads the cited file at the HEAD
1212
+ // checkout, so code that argues itself clean would be voting on the
1213
+ // finding about itself. And the group that would cast those votes is
1214
+ // not independent — `AI_REVIEW_ALLOWED_TOOLS` grants
1215
+ // `Read,Grep,Glob,Write` and `AI_REVIEW_DENY_RULES` denies `Task`, so
1216
+ // a verifier step cannot spawn anything and N votes from one
1217
+ // invocation are one opinion written down N times.
1218
+ //
1219
+ // Until both are fixed — structural independence, and a base-ref read
1220
+ // — the ballot is RECORDED and never acted on. `main` runs the gate
1221
+ // for the ledger and the annotation; this list is untouched by it.
1222
+ // See `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` under CRC-B4.
393
1223
  blocking.push(item);
394
- detail.push(renderFinding(i, finding));
1224
+ // Tagged through the same binding every other render uses. By here the
1225
+ // tag is `Important` by construction — the severity blocks and the
1226
+ // finding is not Pre-existing, or the branch above would have returned
1227
+ // — so this list is not re-ordered: a sort over one rank reorders
1228
+ // nothing, and applying one would be a comparator no case could redden.
1229
+ detail.push(renderFinding(i, finding, findingTag(finding, touched)));
395
1230
  }
396
1231
  });
397
1232
 
@@ -412,12 +1247,26 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
412
1247
  }
413
1248
  }
414
1249
 
415
- if (reasons.length > 0) return unmeasured(reasons, detail, list);
1250
+ const tags = tagsForPayload(list, touched);
1251
+
1252
+ if (reasons.length > 0) return unmeasured(reasons, detail, list, tags);
416
1253
 
417
1254
  // The decision, and the only place it is made. `verdict` is compared to it
418
1255
  // afterwards; it never contributes to it.
419
1256
  const blocked = blocking.length > 0;
420
- const agreed = verdict === (blocked ? AI_REVIEW_BLOCK_VERDICT : AI_REVIEW_PASS_VERDICT);
1257
+ // The agreement is measured BEFORE CRC-B7's demotion, not after it.
1258
+ //
1259
+ // The reviewer is not given the pull request's file list, so it cannot know
1260
+ // a finding is pre-existing and its `BLOCK` over one is honest. Comparing
1261
+ // its word against the post-demotion count would turn every successful
1262
+ // demotion into a CONTRADICTION — the arm would fire on the mechanism
1263
+ // working, which is the loudest possible way to be wrong.
1264
+ //
1265
+ // The real contradiction #1178 exists for is untouched: a `BLOCK` over a
1266
+ // payload whose findings are ALL advisory has `demoted === 0`, so it still
1267
+ // fires. Measured at roughly 6 of 20 runs when that was written.
1268
+ const wouldBlock = blocked || demoted > 0;
1269
+ const agreed = verdict === (wouldBlock ? AI_REVIEW_BLOCK_VERDICT : AI_REVIEW_PASS_VERDICT);
421
1270
  const outcome: AiReviewOutcome = !agreed ? "CONTRADICTION" : blocked ? "BLOCKED" : "CLEAN";
422
1271
 
423
1272
  return {
@@ -428,25 +1277,180 @@ export function readAiReviewFindings(raw: string | null): AiReviewFindingsReadin
428
1277
  verdict,
429
1278
  unmeasuredReasons: [],
430
1279
  detail,
1280
+ // Both of these are `withScope`'s to set, and it is the only site that
1281
+ // sets either. A value here would be a second statement about the same
1282
+ // input, and the two could disagree.
1283
+ scope: scopeNotSupplied(),
1284
+ unlocatableReported: null,
1285
+ scopeDropped: null,
1286
+ findingTags: tags,
431
1287
  };
432
1288
  }
433
1289
 
1290
+ /**
1291
+ * The pull request's changed files, read from a newline-delimited file.
1292
+ *
1293
+ * `null` means the path was given and could not be read, which the caller
1294
+ * must NOT collapse into "no list was supplied" — see `readAiReviewFindings`
1295
+ * on why `undefined` and `[]` are different facts. This returns the third
1296
+ * one, and it is the same distinction a third time.
1297
+ *
1298
+ * Blank lines are dropped before the emptiness test, so a file containing
1299
+ * only whitespace reads as empty rather than as one unnamed file.
1300
+ */
1301
+ /**
1302
+ * One repository path, in the one spelling both sides of CRC-B7's comparison
1303
+ * are reduced to — or `null` for "this cannot be read as a repository path".
1304
+ *
1305
+ * **`null` is the important return.** The first cut of CRC-B7 compared
1306
+ * `String(finding.file).toLowerCase()` against a raw list, and every input
1307
+ * the comparison could not read demoted a `critical` to CLEAN, because a
1308
+ * spelling that is never in the set is indistinguishable from a file the
1309
+ * pull request did not touch. Measured against a list holding `lib/mine.ts`:
1310
+ *
1311
+ * ```
1312
+ * CLEAN 0 blocking {} 123 "./lib/mine.ts" "lib/mine.ts:12"
1313
+ * CLEAN 0 blocking "lib\mine.ts" "/lib/mine.ts"
1314
+ * ```
1315
+ *
1316
+ * Six for six, five of them the SAME FILE spelt differently. `./x`, `/x`,
1317
+ * `x` and `x:12` are one file and four strings, and an equality test over
1318
+ * raw strings answers a different question from the one being asked.
1319
+ *
1320
+ * So both sides go through here, and a `null` on either side is a refusal
1321
+ * rather than a mismatch. The git C-quoted form — `"lib/\303\251.ts"`, which
1322
+ * git emits for a non-ASCII path unless `core.quotePath=false` — is
1323
+ * deliberately `null` rather than unescaped here: decoding octal escapes to
1324
+ * compare a path is a second parser, and the right repair is to produce the
1325
+ * list with `-z` or `core.quotePath=false` in the first place.
1326
+ */
1327
+ export function normaliseRepoPath(value: unknown): string | null {
1328
+ if (typeof value !== "string") return null;
1329
+ let p = value.trim().replace(/\\/g, "/");
1330
+ // git's C-quoted spelling. Not comparable without a second unescaper.
1331
+ if (p.startsWith('"') && p.endsWith('"')) return null;
1332
+ p = p.replace(/^\/+/, "").replace(/:\d+(?::\d+)?$/, "");
1333
+
1334
+ // Dot segments are COLLAPSED, not stripped once. `.replace(/^\.\//, "")`
1335
+ // removes one leading `./` and leaves `././lib/a.ts` as `./lib/a.ts`, which
1336
+ // the shape test below accepts — `.` and `..` are both legal matches for
1337
+ // `[\w.@+-]+`. Measured on this file before the fix:
1338
+ //
1339
+ // "././lib/mine.ts" -> "./lib/mine.ts"
1340
+ // "lib/./mine.ts" -> "lib/./mine.ts"
1341
+ // "lib/../lib/mine.ts" -> "lib/../lib/mine.ts"
1342
+ //
1343
+ // Each compares unequal to `lib/mine.ts`, so a blocking finding naming the
1344
+ // file in one of those spellings was demoted to Pre-existing against a
1345
+ // change list that contained it — the same fail-open round one shipped,
1346
+ // in a narrower spelling. Found by the push review on this branch.
1347
+ //
1348
+ // A `..` that would leave the repository root is refused rather than
1349
+ // clamped: `../outside.ts` is not a repository-relative path, and turning
1350
+ // it into `outside.ts` invents a file this change may well have touched.
1351
+ const out: string[] = [];
1352
+ for (const segment of p.split("/")) {
1353
+ if (segment === "" || segment === ".") continue;
1354
+ if (segment === "..") {
1355
+ if (out.pop() === undefined) return null;
1356
+ continue;
1357
+ }
1358
+ out.push(segment);
1359
+ }
1360
+ p = out.join("/");
1361
+ if (p === "") return null;
1362
+
1363
+ return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p.toLowerCase() : null;
1364
+ }
1365
+
1366
+ /** What a changed-file list reduced to, split by whether it could be read. */
1367
+ export interface ChangedFilePartition {
1368
+ /**
1369
+ * The entries that normalised, in the one spelling both sides of the
1370
+ * comparison are reduced to. This is what `touched` is built from.
1371
+ */
1372
+ readable: string[];
1373
+ /**
1374
+ * The entries that did not, RAW and in list order — so the reader can be
1375
+ * NAMED to whoever has to fix the tree, rather than counted at them.
1376
+ */
1377
+ dropped: string[];
1378
+ }
1379
+
1380
+ /**
1381
+ * Split a changed-file list into the part this reader can compare against and
1382
+ * the part it cannot (#1472).
1383
+ *
1384
+ * **One exported binding, and the only place the split is decided.** A second
1385
+ * site answering "is this entry readable" would be two deciders over one
1386
+ * input, and a mutation of either would leave the other holding every case up
1387
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape). It is
1388
+ * exported so a battery has one thing to short-circuit.
1389
+ *
1390
+ * **Dropping is safe here and it is not an optimistic reading.** A narrower
1391
+ * `touched` can only demote MORE findings, never fewer — and the findings a
1392
+ * dropped entry could falsely demote are none at all, because BOTH sides of
1393
+ * the comparison go through `normaliseRepoPath`: an entry is dropped exactly
1394
+ * when it normalises to `null`, and a finding naming that same path
1395
+ * normalises to `null` too, which `readPayload` answers with *"it keeps
1396
+ * blocking: undecidable is not pre-existing"*. The set the drop could reach
1397
+ * and the set the drop cannot decide are the same set.
1398
+ *
1399
+ * What a drop must never be is SILENT. The caller carries `dropped` onto the
1400
+ * reading as `scopeDropped` and `aiReviewScopeLine` prints it on every run:
1401
+ * "this list was read in full" and "this list was read in part" are different
1402
+ * facts, and a reading over a narrowed set that does not say it was narrowed
1403
+ * is Silent Default Substitution (`.claude/rules/config-access.md`).
1404
+ */
1405
+ export function partitionChangedFiles(
1406
+ changedFiles: readonly string[],
1407
+ ): ChangedFilePartition {
1408
+ const readable: string[] = [];
1409
+ const dropped: string[] = [];
1410
+ for (const entry of changedFiles) {
1411
+ const normalised = normaliseRepoPath(entry);
1412
+ if (normalised === null) dropped.push(entry);
1413
+ else readable.push(normalised);
1414
+ }
1415
+ return { readable, dropped };
1416
+ }
1417
+
1418
+ // `readChangedFiles` lived here and is gone. It returned `null` for BOTH an
1419
+ // unreadable file and — via its caller — an empty one, and `main` reported
1420
+ // that single `null` as `CHANGED_FILES_EMPTY`. A failed `git diff` writes no
1421
+ // file at all, so that collapsed "the diff was lost" into "the diff was
1422
+ // empty", which are different facts with different repairs.
1423
+ // `readAiReviewChangedFiles` replaces it and keeps them apart.
1424
+
434
1425
  /** Read the payload from disk. An absent file and an unreadable one differ. */
435
- export function readAiReviewFindingsFile(path: string): AiReviewFindingsReading {
1426
+ export function readAiReviewFindingsFile(
1427
+ path: string,
1428
+ scope: AiReviewScopeReading = scopeNotSupplied(),
1429
+ ): AiReviewFindingsReading {
436
1430
  let raw: string;
437
1431
  try {
438
1432
  raw = readFileSync(path, "utf-8");
439
1433
  } catch (e) {
440
1434
  const code = (e as NodeJS.ErrnoException).code;
441
1435
  if (code === "ENOENT") {
442
- return unmeasured(["FINDINGS_FILE_ABSENT"], [`no findings payload at ${path}`]);
1436
+ return withScope(
1437
+ unmeasured(["FINDINGS_FILE_ABSENT"], [`no findings payload at ${path}`]),
1438
+ scope,
1439
+ null,
1440
+ null,
1441
+ );
443
1442
  }
444
- return unmeasured(
445
- ["FINDINGS_FILE_UNREADABLE"],
446
- [`the findings payload at ${path} could not be read: ${(e as Error).message}`],
1443
+ return withScope(
1444
+ unmeasured(
1445
+ ["FINDINGS_FILE_UNREADABLE"],
1446
+ [`the findings payload at ${path} could not be read: ${(e as Error).message}`],
1447
+ ),
1448
+ scope,
1449
+ null,
1450
+ null,
447
1451
  );
448
1452
  }
449
- return readAiReviewFindings(raw);
1453
+ return readAiReviewFindings(raw, scope);
450
1454
  }
451
1455
 
452
1456
  /** The sentence a refusal prints, or `null` when there is nothing to refuse. */
@@ -487,9 +1491,16 @@ export function aiReviewRefusal(reading: AiReviewFindingsReading): string | null
487
1491
  // Used INSTEAD of `detail` rather than appended to it. The two overlap
488
1492
  // exactly on the blocking findings, so appending would print those
489
1493
  // twice, and a duplicate reads as two findings.
490
- const counted = renderCountedFindings(reading.reported);
491
- const payload = counted.length > 0
492
- ? `${counted.join("; ")}. `
1494
+ const counted = renderCountedFindings(reading.reported, reading.findingTags);
1495
+ // Same sort, same binding, same payload numbering. The contradiction
1496
+ // arm is the one place every counted finding is printed together, so
1497
+ // it is where an unordered list costs the most.
1498
+ const ordered = tagOrder(
1499
+ reading.findingTags,
1500
+ counted.map((_, i) => i),
1501
+ ).map(i => counted[i]);
1502
+ const payload = ordered.length > 0
1503
+ ? `${ordered.join("; ")}. `
493
1504
  : `The payload records no findings at all. `;
494
1505
  return (
495
1506
  `The AI review's verdict ${JSON.stringify(reading.verdict)} contradicts its ` +
@@ -509,21 +1520,293 @@ export function aiReviewExitCode(reading: AiReviewFindingsReading): number {
509
1520
  return reading.outcome === "CLEAN" ? 0 : AI_REVIEW_REQUIRED_EXIT;
510
1521
  }
511
1522
 
1523
+ /** The annotation title the verifier quorum's own reading is printed under. */
1524
+ export const AI_REVIEW_JURY_NOTICE_TITLE = "AI review verifier quorum";
1525
+
512
1526
  /**
513
- * The CLI the generated workflow step runs: one argument, the payload's path.
1527
+ * The title the quorum's UNMEASURED state is named under.
514
1528
  *
515
- * Returns the exit code rather than calling `process.exit`, so a test can run
516
- * it in-process as well as spawn it.
1529
+ * A SEPARATE title, because it is a different fact with a different fix: a
1530
+ * group that met and disagreed is a reading, and a group that did not meet
1531
+ * is not one. GitHub groups annotations by title, so one title for both
1532
+ * would make the absence read as part of the vote.
517
1533
  */
518
- export function main(argv: string[]): number {
1534
+ export const AI_REVIEW_JURY_UNMEASURED_TITLE = "AI review verifier quorum UNMEASURED";
1535
+
1536
+ /**
1537
+ * The verifier quorum, as `main` consumes it (CRC-B4).
1538
+ *
1539
+ * **Injected, not imported**, and the reason is mechanical rather than
1540
+ * stylistic. This module is copied into a scratch directory by three
1541
+ * mutation batteries, which carry its one relative dependency —
1542
+ * `./ai-review-step`, which has none — along with it. `lib/ai-review-jury.ts`
1543
+ * pulls in the finding arbiter and the filing gate behind it, and a mutant
1544
+ * that dies on module resolution reports zero findings, which reads exactly
1545
+ * like a guard behaving differently
1546
+ * (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
1547
+ *
1548
+ * **The gate decides nothing.** It is consulted after the reading is
1549
+ * complete, its answer reaches an annotation and the finding ledger, and
1550
+ * `reading` is not rebuilt from it.
1551
+ *
1552
+ * So a gate that is absent, unreadable, malformed **or throwing** leaves
1553
+ * the verdict alone — and the last of those four is enforced by a `try`
1554
+ * at the call site rather than by this sentence. It is listed explicitly
1555
+ * because the first draft of this docblock claimed all four while only
1556
+ * three held: the call was outside any `catch`, so a throwing gate
1557
+ * propagated out of `main` and killed the process above the outcome
1558
+ * marker. A comment asserting a property the code lacks is the reason
1559
+ * nobody checks it — the instance this repository keeps is
1560
+ * `lib/cli-commands.ts`'s "runs every command for real" over a test that
1561
+ * ran one command of ten. `JG-6h` is now the assertion.
1562
+ *
1563
+ * That is the only honest arrangement while the group casting the votes
1564
+ * is not yet structurally independent. See `AI_REVIEW_JURY_NOTICE_TITLE`.
1565
+ *
1566
+ * **It takes the findings and nothing else.** The ballot directory is
1567
+ * bound by whoever supplies the gate, so this module never learns a path
1568
+ * and the CLI's argv contract — two positionals, `argv[2]` and up refused
1569
+ * — is untouched. A gate that is `null` is the whole of "no ballot".
1570
+ */
1571
+ export interface AiReviewJuryGate {
1572
+ (blocking: readonly unknown[]): {
1573
+ /**
1574
+ * One entry per blocking finding, **in input order** — the sentence
1575
+ * saying the group would have withheld it, or `null`.
1576
+ *
1577
+ * Positional rather than keyed, and that is the contract rather than a
1578
+ * convenience. A map from a finding identity would be a SECOND
1579
+ * derivation of that identity over a list already produced in order,
1580
+ * and two findings sharing a key would share a vote.
1581
+ * `lib/finding-arbiter.ts`'s `SHARED_BALLOT` refuses exactly that one
1582
+ * level down — *"a vote is about a finding"*.
1583
+ *
1584
+ * **"Would have".** Nothing here subtracts: the entry is recorded and
1585
+ * announced, and the finding blocks exactly as it did before the group
1586
+ * met.
1587
+ */
1588
+ wouldWithhold: readonly (string | null)[];
1589
+ /** Non-null when the ballot source could not be read. Never fatal. */
1590
+ unmeasured: string | null;
1591
+ /** One sentence per finding voted on. */
1592
+ detail: readonly string[];
1593
+ };
1594
+ }
1595
+
1596
+ /**
1597
+ * The line recording how the scope reading was taken, and the two counts a
1598
+ * reader needs to see differ when the gate fires (#1204).
1599
+ *
1600
+ * The number of findings PRODUCED and the number ALLOWED TO BLOCK are both
1601
+ * printed, because a review that quietly demoted a finding and a review that
1602
+ * never had one are otherwise the same output. The blocking count is
1603
+ * `withheld` under an UNMEASURED reading rather than `0` — the decision is
1604
+ * withheld there, and printing a number would be inventing one.
1605
+ *
1606
+ * It also reports its own COVERAGE of the changed-file list (#1472): a scan
1607
+ * that reports a verdict should say how much of its input it read. An entry
1608
+ * this reader could not normalise is dropped from the comparison rather than
1609
+ * refusing the whole run, so `dropped` is what keeps "the list was read in
1610
+ * full" apart from "the list was read in part" — and the entries are NAMED,
1611
+ * because a warning that does not say what was missing is a warning nobody
1612
+ * can act on. `not checked`, `0` and a named list are three facts, not one.
1613
+ */
1614
+ export function aiReviewScopeLine(reading: AiReviewFindingsReading): string {
1615
+ const produced = reading.reported?.length ?? 0;
1616
+ const blocking =
1617
+ reading.blockingReported === null ? "withheld" : String(reading.blockingReported.length);
1618
+ const unlocatable =
1619
+ reading.unlocatableReported === null ? "not checked" : String(reading.unlocatableReported.length);
1620
+ const drops = reading.scopeDropped;
1621
+ const dropped =
1622
+ drops === null
1623
+ ? "not checked"
1624
+ : drops.length === 0
1625
+ ? "0"
1626
+ : `${drops.length} (${drops.map(p => JSON.stringify(p)).join(", ")}), ` +
1627
+ `so this comparison ran over a NARROWER set than the pull request touched`;
1628
+ return (
1629
+ `${AI_REVIEW_SCOPE_LINE} ${reading.scope.status} — findings reported: ${produced}, ` +
1630
+ `allowed to block: ${blocking}, unlocatable: ${unlocatable}, ` +
1631
+ `changed-file entries dropped: ${dropped}. ${reading.scope.detail}`
1632
+ );
1633
+ }
1634
+
1635
+ // `parseFindingsArgv` and `AiReviewFindingsArgv` lived here and are gone.
1636
+ // The parser refused a SECOND POSITIONAL argument by design, which is
1637
+ // exactly the invocation CRC-B7 deploys, so the flag CLI and the
1638
+ // positional one could not both stand. See `main` below.
1639
+ //
1640
+ // What the parser ALSO did is kept, in `argumentsBeyondTheContract`: it
1641
+ // refused an argument nothing reads, rather than dropping it. Deleting the
1642
+ // parser silently took that with it — measured, not assumed, on the merged
1643
+ // tree: `main([payload, list, "extra"])` returned 0 and printed CLEAN. A
1644
+ // dropped argument is a caller asking for something that did not happen,
1645
+ // which is the same fault as a skipped check wearing different clothes.
1646
+
1647
+ /**
1648
+ * The arguments past the two this CLI reads. One exported binding, so the
1649
+ * refusal has a single site to mutate (`checks-must-be-able-to-fail.md`).
1650
+ *
1651
+ * It returns the arguments rather than a boolean because the refusal names
1652
+ * them: "an argument was ignored" is not something an operator can act on,
1653
+ * and the failing invocation is usually a workflow line nobody can see from
1654
+ * the log.
1655
+ */
1656
+ export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
1657
+ return argv.slice(2);
1658
+ }
1659
+
1660
+ /**
1661
+ * The CLI the generated workflow step runs: the payload's path, and
1662
+ * optionally a second POSITIONAL path to the pull request's changed files.
1663
+ *
1664
+ * Positional, not a `--changed-files` flag. #1204 wrote the flag and CRC-B7
1665
+ * wrote the positional; the generated step passes positionally and #1356
1666
+ * builds on that, so the flag is the spelling that goes. Two spellings for
1667
+ * one argument would be two deciders over the same input, and the one the
1668
+ * deployed workflow does not use is the one that would rot.
1669
+ *
1670
+ * The second argument is optional: a caller that does not pass one gets
1671
+ * exactly the reading this module gave before any of this was wired, which
1672
+ * is what keeps every existing consumer working unchanged.
1673
+ *
1674
+ * An unreadable list is NOT silently treated as absent, and `readAiReview-
1675
+ * ChangedFiles` is what keeps those apart — `CHANGED_FILES_UNREADABLE` for a
1676
+ * list that was named and could not be read, `CHANGED_FILES_EMPTY` for one
1677
+ * that was read and names nothing. A failed `git diff` writes no file at
1678
+ * all, so collapsing the two would report a diff that was lost as a diff
1679
+ * that was taken.
1680
+ *
1681
+ * An argument past those two REFUSES. Nothing reads it, and a CLI that
1682
+ * accepts an argument it ignores reports success for an invocation that did
1683
+ * not happen.
1684
+ *
1685
+ * Separate from `main` so the argv contract is decided in one place and
1686
+ * `main` is only the printing. A refusal reached here still prints the
1687
+ * outcome line and the scope line, because the generated step reads the
1688
+ * outcome line before it reads the exit code.
1689
+ */
1690
+ function readArgv(argv: string[]): AiReviewFindingsReading {
1691
+ const extra = argumentsBeyondTheContract(argv);
1692
+ if (extra.length > 0) {
1693
+ // Scope is NOT read here. The argv is already known to be a shape this
1694
+ // CLI does not accept, so which file argv[1] names is a question about
1695
+ // an invocation that is being refused.
1696
+ return withScope(
1697
+ unmeasured(
1698
+ ["ARGUMENTS_UNREADABLE"],
1699
+ [
1700
+ `${extra.length} argument(s) past the findings payload and the changed-file ` +
1701
+ `list were given and nothing reads them: ${extra.map(a => JSON.stringify(a)).join(", ")}. ` +
1702
+ `Usage: <path-to-findings.json> [<path-to-changed-files.txt>]`,
1703
+ ],
1704
+ ),
1705
+ scopeNotSupplied(),
1706
+ null,
1707
+ null,
1708
+ );
1709
+ }
1710
+
519
1711
  const path = argv[0];
520
- const reading =
521
- path === undefined || path === ""
522
- ? unmeasured(
1712
+ const scope = readAiReviewChangedFiles(argv[1]);
1713
+ return path === undefined || path === ""
1714
+ ? withScope(
1715
+ unmeasured(
523
1716
  ["FINDINGS_FILE_ABSENT"],
524
1717
  ["no findings payload path was given to the findings reader"],
525
- )
526
- : readAiReviewFindingsFile(path);
1718
+ ),
1719
+ scope,
1720
+ null,
1721
+ null,
1722
+ )
1723
+ : readAiReviewFindingsFile(path, scope);
1724
+ }
1725
+
1726
+ /**
1727
+ * The CLI entry point. `readArgv` above decides what the arguments mean;
1728
+ * everything here is emission.
1729
+ *
1730
+ * Returns the exit code rather than calling `process.exit`, so a test can run
1731
+ * it in-process as well as spawn it.
1732
+ */
1733
+ export function main(argv: string[], jury: AiReviewJuryGate | null = null): number {
1734
+ const reading = readArgv(argv);
1735
+
1736
+ // CRC-B4, AFTER the reading and feeding nothing back into it.
1737
+ //
1738
+ // The group votes on `blockingReported` — the existing decider's own
1739
+ // answer to "which of these block", never a list re-derived from the
1740
+ // severities, which is the criterion's first clause: a quorum over the
1741
+ // advisory tail spends a full agent context per nit.
1742
+ //
1743
+ // WHAT IT DOES NOT DO IS SUBTRACT, and that is a decision with two
1744
+ // reasons, both of them properties of the tree rather than of this
1745
+ // function:
1746
+ //
1747
+ // - **The group is not independent yet.** `AI_REVIEW_ALLOWED_TOOLS`
1748
+ // grants the review action `Read,Grep,Glob,Write` and
1749
+ // `AI_REVIEW_DENY_RULES` denies `Task`, so one invocation cannot spawn
1750
+ // verifiers. Independence has to be a property of the WORKFLOW — one
1751
+ // action invocation per verifier — and a ballot that subtracts before
1752
+ // that holds is a quorum wired to a constant: populated, plausible,
1753
+ // and filtering nothing. That is the counterfeit CRC-B4 names.
1754
+ // - **The verifier reads the head checkout.** A subtracting ballot would
1755
+ // make the branch under review an input to the gate on the branch
1756
+ // under review.
1757
+ //
1758
+ // So the votes are counted, written to the finding ledger at decision
1759
+ // time, and announced. Nothing below reads `gate` except the annotation.
1760
+ // CRC-B4's *"surfaced only if enough agree"* clause is therefore NOT
1761
+ // satisfied, and the spec says so rather than this comment alone.
1762
+ //
1763
+ // **The ballot directory is NOT a third positional argument**, and that
1764
+ // is deliberate rather than incidental. `argumentsBeyondTheContract`
1765
+ // refuses `argv[2]` and up, and one of the invocations it catches is a
1766
+ // changed-file path containing a space that an unquoted expansion
1767
+ // word-split into two — `test/ai-review-changed-files-step.test.ts`
1768
+ // CF-6 names that case. Widening the contract by one slot to carry a
1769
+ // ballot would turn that refusal into an accepted argv whose second
1770
+ // half is read as a ballot directory. So the directory binds at the
1771
+ // wrapper, which closes over it and hands this function a gate or
1772
+ // `null`; "no ballot" and "a ballot nothing reads" collapse into one
1773
+ // state that cannot be reached.
1774
+ let juryDetail: readonly string[] = [];
1775
+ let juryUnmeasured: string | null = null;
1776
+ if (jury !== null && reading.blockingReported !== null && reading.blockingReported.length > 0) {
1777
+ try {
1778
+ const gate = jury(reading.blockingReported);
1779
+ juryDetail = gate.detail;
1780
+ juryUnmeasured = gate.unmeasured;
1781
+ } catch (e) {
1782
+ // A FAIL-OPEN, DELIBERATELY, and this is the one arrangement where
1783
+ // that is the correct choice rather than the first thing
1784
+ // `.claude/rules/checks-must-be-able-to-fail.md` tells you to
1785
+ // distrust. Its warning is about a guard that converts its own
1786
+ // breakage into "no problems found". This gate finds no problems
1787
+ // and gates nothing: the verdict is `aiReviewExitCode(reading)`
1788
+ // either way, so catching here cannot hide a finding — it can only
1789
+ // stop an advisory recorder from deciding a review it has no vote
1790
+ // in. The day the ballot is allowed to subtract, this catch must
1791
+ // become a refusal, and that is the line to change.
1792
+ //
1793
+ // Without it the throw propagates out of `main`, so
1794
+ // `process.exit(main(...))` never runs and a CLEAN review dies
1795
+ // non-zero. Worse than the exit code: this block sits ABOVE the
1796
+ // `AI_REVIEW_OUTCOME_LINE` print, which the generated step greps
1797
+ // for before it will read an exit code as a verdict, so the step
1798
+ // sees an adjudicator that could not run rather than a verdict.
1799
+ //
1800
+ // Three things inside the real gate are outside any catch of their
1801
+ // own — `juryReading`, `advisoryKey` over a hostile payload, and
1802
+ // all of `juryLedgerRow`. `JG-6h` is this case.
1803
+ juryUnmeasured =
1804
+ `the verifier quorum threw and was not counted, so no vote was recorded for this ` +
1805
+ `run: ${(e as Error).message}. The verdict below is the adjudicator's own and is ` +
1806
+ `unchanged — the group decides nothing this round — but the votes for these findings ` +
1807
+ `are lost rather than merely unfavourable, and the ledger has no row to recover`;
1808
+ }
1809
+ }
527
1810
 
528
1811
  // FIRST, and before any branch below can return. The generated workflow step
529
1812
  // greps its own output for this prefix and will not read the exit code as a
@@ -531,6 +1814,16 @@ export function main(argv: string[]): number {
531
1814
  // refused both exit non-zero, and only this line tells them apart.
532
1815
  console.log(`${AI_REVIEW_OUTCOME_LINE} ${reading.outcome}`);
533
1816
 
1817
+ // AFTER the outcome line, and never instead of it. The generated step lifts
1818
+ // its verdict from the FIRST occurrence of that marker, so this line cannot
1819
+ // move it. Printed on EVERY run, including the one where no list was
1820
+ // supplied: an absent input that nothing reports is Silent Default
1821
+ // Substitution, and this line is the whole of what makes the skip a
1822
+ // reading. Escaped at emission like the annotation below — a path arriving
1823
+ // on the command line reaches a stream GitHub parses workflow commands out
1824
+ // of, and this module escapes exactly once, at the point of emission.
1825
+ console.log(escapeAnnotation(aiReviewScopeLine(reading)));
1826
+
534
1827
  // The ONE place a value reaches a workflow command. Everything upstream of
535
1828
  // here — `renderFinding`, every `detail` sentence, `aiReviewRefusal` — builds
536
1829
  // plain text and leaves escaping alone, so there is one binding to mutate and
@@ -540,6 +1833,55 @@ export function main(argv: string[]): number {
540
1833
  console.error(`::error title=${AI_REVIEW_FINDINGS_TITLE}::${escapeAnnotation(refusal)}`);
541
1834
  }
542
1835
 
1836
+ // AFTER the refusal and BEFORE the exit code, and on its own title. A
1837
+ // `::notice` rather than a `::warning` or an `::error`: the advisory tail
1838
+ // does not block, and a notice is what GitHub records against the check run
1839
+ // without changing its conclusion. It goes through the same single escaper
1840
+ // the refusal does — this is a new value reaching a workflow command, and
1841
+ // `escapeAnnotation`'s own docblock has the measured instance of what an
1842
+ // unescaped one can do to a verdict.
1843
+ const advisory = advisoryNotice(reading);
1844
+ if (advisory !== null) {
1845
+ console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
1846
+ }
1847
+
1848
+ // The quorum's own reading, on its own title, and emitted whatever the
1849
+ // outcome was. The ledger row is the durable record and it lives on the
1850
+ // runner, which dies with the job; this annotation is the only part of
1851
+ // the vote that outlives the run, so it carries the whole reading rather
1852
+ // than a count.
1853
+ //
1854
+ // A `::notice`, never an `::error`. The ballot decides nothing this round
1855
+ // and an annotation that reddened a check would be a gate arriving by the
1856
+ // back door — see the block above `juryDetail`.
1857
+ if (juryDetail.length > 0) {
1858
+ console.log(
1859
+ `::notice title=${AI_REVIEW_JURY_NOTICE_TITLE}::${escapeAnnotation(
1860
+ `A separate verifier group voted on the ${juryDetail.length} finding(s) that would ` +
1861
+ `otherwise block. ${juryDetail.join("; ")}. THE VOTE IS RECORDED AND CHANGES ` +
1862
+ `NOTHING: every finding above blocks exactly as it would have without it. The ` +
1863
+ `group is not yet structurally independent and reads the head checkout, so acting ` +
1864
+ `on it would be a gate whose input is the thing it gates.`,
1865
+ )}`,
1866
+ );
1867
+ }
1868
+
1869
+ // A `::warning`, and the state is NAMED. An absent or unreadable ballot
1870
+ // exiting 0 with no output is the Silent Default Substitution
1871
+ // `.claude/rules/config-access.md` forbids: `0`, `{}` and `null` are
1872
+ // indistinguishable from success and UNMEASURED is not. It does not
1873
+ // refuse, because the consumer decides whether an unmeasured quorum is
1874
+ // fatal and the honest default for a mechanism with no readings yet is an
1875
+ // annotation rather than a red pipeline.
1876
+ if (juryUnmeasured !== null) {
1877
+ console.log(
1878
+ `::warning title=${AI_REVIEW_JURY_UNMEASURED_TITLE}::${escapeAnnotation(
1879
+ `The verifier quorum is UNMEASURED for this run: ${juryUnmeasured}. No finding's ` +
1880
+ `status changed either way.`,
1881
+ )}`,
1882
+ );
1883
+ }
1884
+
543
1885
  return aiReviewExitCode(reading);
544
1886
  }
545
1887