rungate 0.8.1 → 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 (75) 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/BashWriteGuard.hook.ts +19 -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/VerifyPhaseLock.hook.ts +68 -11
  13. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  14. package/lib/ai-review-jury.ts +725 -0
  15. package/lib/ai-review-rounds.ts +1249 -0
  16. package/lib/ai-review-unmeasured.ts +361 -0
  17. package/lib/bash-file-read.ts +17 -3
  18. package/lib/bash-write-guard.ts +2165 -51
  19. package/lib/cli-commands.ts +252 -11
  20. package/lib/closing-reference-audit.ts +163 -0
  21. package/lib/conformity.ts +12 -0
  22. package/lib/create-sc.ts +45 -12
  23. package/lib/derived-spec.ts +206 -0
  24. package/lib/distribution-standing.ts +75 -4
  25. package/lib/failure-intake.ts +12 -4
  26. package/lib/file-claims.ts +335 -0
  27. package/lib/file-extensions.ts +81 -0
  28. package/lib/finding-arbiter.ts +1489 -0
  29. package/lib/finding-jury.ts +584 -0
  30. package/lib/finding-pr-routing.ts +333 -0
  31. package/lib/frontmatter.ts +16 -0
  32. package/lib/gate-check-audit.ts +259 -0
  33. package/lib/generators/agents-md.ts +29 -0
  34. package/lib/github.ts +160 -0
  35. package/lib/hook-tree-currency.ts +494 -0
  36. package/lib/interpreters.ts +64 -0
  37. package/lib/issue-closure-audit.ts +161 -14
  38. package/lib/issue-create-override.ts +122 -11
  39. package/lib/issue-filing-gate.ts +1602 -0
  40. package/lib/local-review-rounds.ts +523 -0
  41. package/lib/organize.ts +10 -0
  42. package/lib/project-state-shape.ts +56 -5
  43. package/lib/publish-window.ts +287 -0
  44. package/lib/repo-path.ts +94 -0
  45. package/lib/report-provenance.ts +65 -3
  46. package/lib/risk-tier.ts +302 -0
  47. package/lib/rounds-to-pass.ts +274 -0
  48. package/lib/rule-row-drift.ts +199 -0
  49. package/lib/sc-claim-forms.ts +33 -5
  50. package/lib/sc-guard.ts +11 -1
  51. package/lib/sc-id-cross-tree.ts +17 -2
  52. package/lib/sc-ids.ts +71 -6
  53. package/lib/sc-reservations.ts +158 -14
  54. package/lib/scaffold/ai-review-findings.ts +1157 -18
  55. package/lib/scaffold/ai-review-step.ts +4672 -85
  56. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  57. package/lib/scaffold/managed-workflow.ts +163 -4
  58. package/lib/scaffold/owned-files.ts +14 -0
  59. package/lib/scaffold/steps.ts +462 -108
  60. package/lib/scanner.ts +10 -3
  61. package/lib/scratch-roots.ts +93 -3
  62. package/lib/spec-updater.ts +16 -0
  63. package/lib/ticked-sc-symbols.ts +361 -0
  64. package/lib/validators/spec-validators.ts +28 -2
  65. package/lib/workflow-actions.ts +18 -0
  66. package/package.json +3 -1
  67. package/scripts/ai-review-findings.ts +41 -1
  68. package/scripts/arbitrate-finding.ts +542 -0
  69. package/scripts/audit-specs.ts +225 -23
  70. package/scripts/create-sc.ts +11 -0
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/generate-code-map.ts +6 -3
  73. package/scripts/record-ai-review-unmeasured.ts +370 -0
  74. package/scripts/split-spec.ts +12 -0
  75. package/scripts/sync-sc-status.ts +93 -8
@@ -0,0 +1,1249 @@
1
+ /**
2
+ * Bounding review rounds on an open pull request (#1168).
3
+ *
4
+ * `lib/security-verdict.ts` already decides all of this for rook inside a
5
+ * ship run: `reReviewDecision` caps rounds and fails closed on an unreadable
6
+ * budget, `reReviewScope` works out that a stale FAIL and a stale PASS need
7
+ * different re-review scopes, and `reviewIsCurrent` clears a finding when a
8
+ * later commit replaced the code it was about. None of it is reachable from
9
+ * CI, because it governs a ship run and the swarm bypasses ship.js.
10
+ *
11
+ * **This module does not reimplement any of it.** Every decision below
12
+ * delegates to that file. What is added here is the part that file has no
13
+ * opinion about: where a round NUMBER comes from on a pull request, and what
14
+ * the reviewer should be told once the budget is spent.
15
+ *
16
+ * ## The measurement this was built from
17
+ *
18
+ * Anthropic report that `git blame` over what their reviewer kept flagging on
19
+ * later rounds showed ~59% of it was code already present at the first pass —
20
+ * the reviewer was finding a few more OLD bugs each round, not new ones.
21
+ *
22
+ * Measured here on 2026-10-22 over all 524 `AI Review` runs this repository
23
+ * has ever had: the findings adjudicator has only existed since #1013, so the
24
+ * whole population of blocking findings is 8, across 6 branches, and exactly
25
+ * **2** of them are round-2-or-later. Both cite a line that was present at
26
+ * round 1:
27
+ *
28
+ * * `rg/1175`, round 2 flagged `lib/bash-write-guard.ts:375`
29
+ * (`LINK_CREATION`). The byte-identical line was at `:318` at round 1.
30
+ * * `fix/1129`, round 2 flagged `lib/launch-base.ts:184`
31
+ * (`canonical === given`). `git diff` between the two reviewed commits
32
+ * reports the file UNCHANGED.
33
+ *
34
+ * 2 of 2 is 100% on a denominator of 2. It is consistent with their 59% and
35
+ * it is not a replication of it, and this module does not claim one.
36
+ *
37
+ * ## What that measurement changed in the design
38
+ *
39
+ * **A finding fingerprint may not be keyed on a line number.** The first case
40
+ * above moved 318 → 375 between rounds while staying byte-identical, so a
41
+ * `file:line` key would have failed to suppress the one repeat we can
42
+ * actually observe. `carryKey` therefore keys on the file, the normalised
43
+ * TEXT of the cited line, and the normalised summary.
44
+ *
45
+ * **`git blame` is the wrong instrument for this question.** It attributed
46
+ * the first case to a commit that is not an ancestor of the round-1 head (the
47
+ * branch was rebased between rounds) and the second to the round-2 commit
48
+ * itself (the round-2 commit is an amend of the round-1 one). Blame would
49
+ * have scored BOTH of our stale findings as fresh. Content presence is the
50
+ * reading; authorship is not.
51
+ *
52
+ * ## Why diff-scoping a later round is not safe on its own
53
+ *
54
+ * Anthropic ship diff-only re-review after the first few passes. Applied
55
+ * directly here that is `46034035` — the `fail-open-security-gate` this
56
+ * repository found and reverted — because a diff against the flagged commit
57
+ * does not contain the flagged code, so a later round that reads only the
58
+ * diff says nothing about a finding raised earlier. Theirs is safe because
59
+ * their findings are inline comments that PERSIST on the pull request and
60
+ * block merge until they are answered; ours is a check-run annotation that
61
+ * the next run replaces wholesale, so a finding not re-raised simply
62
+ * disappears and the check goes green.
63
+ *
64
+ * So `reviewScopeForRound` delegates to `reReviewScope`, which refuses to
65
+ * diff-scope anything but a held PASS, and `carryForward` is what makes a
66
+ * diff-scoped round honest: the unresolved earlier findings are re-emitted by
67
+ * the ADJUDICATOR rather than re-discovered by the reviewer.
68
+ */
69
+
70
+ import {
71
+ RE_REVIEW,
72
+ REVIEW_CURRENT,
73
+ REVIEW_SCOPE_DIFF,
74
+ REVIEW_SCOPE_FULL,
75
+ SECURITY_REREVIEW_EXHAUSTED,
76
+ reReviewDecision,
77
+ reReviewScope,
78
+ type ReviewScope,
79
+ } from "./security-verdict.ts";
80
+
81
+ export { REVIEW_SCOPE_DIFF, REVIEW_SCOPE_FULL, type ReviewScope };
82
+
83
+ /**
84
+ * How many review rounds a pull request gets before the reviewer is told to
85
+ * stop listing defects and assess the approach instead.
86
+ *
87
+ * Three, which is the number Anthropic shipped. Re-derived against this
88
+ * repository rather than adopted: over 294 merged pull requests that had an
89
+ * `AI Review` run, 22 (7.5%) went past three rounds, 13 (4.4%) reached five
90
+ * or more, and the mean was 1.738. So a cap of three leaves 92.5% of pull
91
+ * requests untouched and still reaches every run that has actually gone long.
92
+ */
93
+ export const AI_REVIEW_ROUND_CAP = 3;
94
+
95
+ /**
96
+ * The round from which a re-review may be scoped to the diff.
97
+ *
98
+ * Anthropic's "after the first few passes". Here it is the round AFTER the
99
+ * first, and it is a floor rather than the decision: `reviewScopeForRound`
100
+ * still refuses to diff-scope a round whose held verdict is not a PASS, which
101
+ * is `reReviewScope`'s rule and the whole of #244.
102
+ */
103
+ export const AI_REVIEW_DIFF_SCOPE_FROM_ROUND = 3;
104
+
105
+ /**
106
+ * The round budget could not be read, so this job does not know which round
107
+ * it is on.
108
+ *
109
+ * DECLARED ONCE, as an exported constant, for the reason
110
+ * `SECURITY_REREVIEW_EXHAUSTED` is: a second spelling is a second refusal
111
+ * path, reachable by code the first one's tests never visit.
112
+ *
113
+ * This is a REFUSAL and not a warning, and the reasoning is
114
+ * `reReviewDecision`'s own — a budget nobody can read is not a budget with
115
+ * room left in it. The specific fail-open it closes: an unreadable counter
116
+ * makes round 12 indistinguishable from round 1, and reading it as round 1
117
+ * resets the bound on every run, which is a cap that can never be reached.
118
+ */
119
+ export const AI_REVIEW_ROUNDS_UNMEASURED = "AI_REVIEW_ROUNDS_UNMEASURED";
120
+
121
+ /** The review is within budget and reviews normally. */
122
+ export const AI_REVIEW_ROUND_OPEN = "AI_REVIEW_ROUND_OPEN";
123
+ /**
124
+ * The budget is spent. The reviewer still speaks — see `atCapInstruction` —
125
+ * it just stops enumerating defects and says something about the approach.
126
+ */
127
+ export const AI_REVIEW_ROUND_AT_CAP = "AI_REVIEW_ROUND_AT_CAP";
128
+
129
+ export type RoundDecision =
130
+ | typeof AI_REVIEW_ROUND_OPEN
131
+ | typeof AI_REVIEW_ROUND_AT_CAP
132
+ | typeof AI_REVIEW_ROUNDS_UNMEASURED;
133
+
134
+ export interface RoundOutcome {
135
+ /** Exactly one of the three verdicts above. */
136
+ decision: RoundDecision;
137
+ /** The round this run is, or null when it could not be read. */
138
+ round: number | null;
139
+ /** Why the run is not in the ordinary state. Null — and only null — when it is. */
140
+ reason: string | null;
141
+ }
142
+
143
+ /**
144
+ * A round number as it arrives from the workflow: a decimal string on stdout,
145
+ * or nothing.
146
+ *
147
+ * FAILS CLOSED. Anything that is not a positive decimal integer is null, and
148
+ * null is the refusal above. `Number()` is not used: it reads `""` as 0,
149
+ * `" 2 "` as 2 and `0x3` as 3, and a counter that accepts three spellings of
150
+ * a number accepts inputs nobody has decided about.
151
+ *
152
+ * Zero is refused along with the rest. A run that is happening is at least
153
+ * round 1, so a counter reporting 0 has not counted this run — which is a
154
+ * different defect from an unreadable one and not one to paper over by
155
+ * adding one to it.
156
+ */
157
+ export function readRoundNumber(v: unknown): number | null {
158
+ if (typeof v === "number") {
159
+ return Number.isInteger(v) && v >= 1 ? v : null;
160
+ }
161
+ if (typeof v !== "string") return null;
162
+ const trimmed = v.trim();
163
+ if (!/^[0-9]+$/.test(trimmed)) return null;
164
+ const n = Number.parseInt(trimmed, 10);
165
+ return Number.isSafeInteger(n) && n >= 1 ? n : null;
166
+ }
167
+
168
+ /**
169
+ * Which state is this round in?
170
+ *
171
+ * The cap arithmetic is NOT done here. It is handed to `reReviewDecision`,
172
+ * which already answers "is there a round left in this budget" and already
173
+ * fails closed on an unreadable one — so the two cannot be changed apart, and
174
+ * a mutation of its `spent < cap` is observable through this function. The
175
+ * currency argument is the stale shape on purpose: a run that is reviewing is
176
+ * by definition reviewing something a previous round did not clear, so the
177
+ * only question left for that function is the budget one.
178
+ *
179
+ * `roundsSpent` is `round - 1` — the rounds that are already over. At round
180
+ * 4 with a cap of 3 that is 3 of 3 and the budget is gone, which is what
181
+ * makes round 4 the first capped round and rounds 1-3 the three the author
182
+ * gets.
183
+ */
184
+ export function roundOutcome(raw: unknown, cap: unknown = AI_REVIEW_ROUND_CAP): RoundOutcome {
185
+ const round = readRoundNumber(raw);
186
+ if (round === null) {
187
+ return {
188
+ decision: AI_REVIEW_ROUNDS_UNMEASURED,
189
+ round: null,
190
+ reason:
191
+ `the review-round counter read ${describe(raw)}, which is not a round number — ` +
192
+ `this job cannot tell a first review from a twelfth, so the round budget is ` +
193
+ `unreadable and refusing is the only reading that is not a guess`,
194
+ };
195
+ }
196
+
197
+ const stale = {
198
+ current: false,
199
+ reason: `this is review round ${round} on this pull request`,
200
+ };
201
+ const outcome = reReviewDecision(stale, round - 1, cap);
202
+
203
+ if (outcome.decision === RE_REVIEW) {
204
+ return { decision: AI_REVIEW_ROUND_OPEN, round, reason: null };
205
+ }
206
+ // REVIEW_CURRENT cannot be reached: the currency handed in is always stale.
207
+ // Checked anyway rather than folded into the exhaustion branch, because the
208
+ // two mean opposite things and a later change to the currency above would
209
+ // otherwise report "nothing to review" as "out of rounds".
210
+ if (outcome.decision === REVIEW_CURRENT) {
211
+ return { decision: AI_REVIEW_ROUND_OPEN, round, reason: null };
212
+ }
213
+ return {
214
+ decision: AI_REVIEW_ROUND_AT_CAP,
215
+ round,
216
+ reason: outcome.reason,
217
+ };
218
+ }
219
+
220
+ /**
221
+ * The scope the reviewer should read on this round.
222
+ *
223
+ * Two gates, and BOTH must open. The round floor is Anthropic's "after the
224
+ * first few passes"; `reReviewScope` is #244's refusal to diff-scope anything
225
+ * but a held PASS. The second is the one that matters, and it is delegated
226
+ * rather than restated: a diff against the flagged commit does not contain
227
+ * the flagged code.
228
+ *
229
+ * FAILS CLOSED TOWARD READING MORE, in both halves. An unreadable round is a
230
+ * full review, not a skipped one.
231
+ */
232
+ export function reviewScopeForRound(rawRound: unknown, heldVerdict: unknown): ReviewScope {
233
+ const round = readRoundNumber(rawRound);
234
+ if (round === null || round < AI_REVIEW_DIFF_SCOPE_FROM_ROUND) return REVIEW_SCOPE_FULL;
235
+ return reReviewScope(heldVerdict);
236
+ }
237
+
238
+ /** A finding as the payload contract spells it (`AI_REVIEW_FINDING_FIELDS`). */
239
+ export interface ReviewFinding {
240
+ severity?: unknown;
241
+ file?: unknown;
242
+ line?: unknown;
243
+ summary?: unknown;
244
+ failure_scenario?: unknown;
245
+ [k: string]: unknown;
246
+ }
247
+
248
+ /**
249
+ * Collapse the incidental differences between two spellings of one sentence.
250
+ *
251
+ * Case and whitespace only. Not punctuation, and not stemming: two findings
252
+ * that differ in a word are two findings, and a key that erases the
253
+ * difference suppresses a real one.
254
+ */
255
+ function normalise(v: unknown): string {
256
+ return typeof v === "string" ? v.trim().toLowerCase().replace(/\s+/g, " ") : "";
257
+ }
258
+
259
+ /**
260
+ * The identity of a finding, for deciding whether it has already been raised.
261
+ *
262
+ * @identity file+text+summary — `file`, the TEXT of the cited line (falling
263
+ * back to the line NUMBER when the text is not known), and `summary`.
264
+ * Partial: `null` for a finding it cannot key.
265
+ *
266
+ * **This is the PERSISTENCE key** — "is the thing this round raised the thing
267
+ * the last round raised". It is the one the ledger's anchors are recorded
268
+ * under ({@link AI_REVIEW_LEDGER_IDENTITY}) and the one that can refuse.
269
+ *
270
+ * Its sibling is `advisoryKey` in `lib/scaffold/ai-review-findings.ts`, which
271
+ * is the ADJUDICATION key — "has this advisory already been counted on this
272
+ * run" — over `file`+`summary` only, total, never `null`. The two were both
273
+ * called `findingKey` until #1398 and they are deliberately different: a
274
+ * line anchor here is what makes a re-summary of one file two findings
275
+ * rather than one, and a line anchor THERE would split a single finding in
276
+ * two across a reformat. Neither rule can quietly become the other —
277
+ * measured, and both unification mutants are caught — but a call site could
278
+ * not tell which question it was asking while they shared a name.
279
+ *
280
+ * `file` + the TEXT of the cited line + `summary`. **Not the line number**,
281
+ * and that is the measured part rather than a preference: the one repeat this
282
+ * repository can actually show moved from `:318` to `:375` between rounds
283
+ * while staying byte-identical, so a `file:line` key would have let it
284
+ * through. See this module's header.
285
+ *
286
+ * `lineText` is the content at the cited line, supplied by the caller because
287
+ * only the caller has the checkout. Absent or empty, the key falls back to
288
+ * the line NUMBER — which is weaker, and is the honest answer when the line
289
+ * cannot be read: a key that pretends to content it never saw would suppress
290
+ * on a collision of empty strings, and that suppresses everything.
291
+ *
292
+ * Returns null for a finding with no `file` and no `summary`. There is
293
+ * nothing to compare such a finding against, and giving it a key would make
294
+ * every one of them a repeat of the first.
295
+ */
296
+ export function carryKey(finding: unknown, lineText?: unknown): string | null {
297
+ if (typeof finding !== "object" || finding === null || Array.isArray(finding)) return null;
298
+ const f = finding as ReviewFinding;
299
+ const file = normalise(f.file);
300
+ const summary = normalise(f.summary);
301
+ if (!file && !summary) return null;
302
+ const text = normalise(lineText);
303
+ const anchor = text !== ""
304
+ ? `t:${text}`
305
+ : `n:${typeof f.line === "number" && Number.isInteger(f.line) ? f.line : ""}`;
306
+ return `${file}\u0000${anchor}\u0000${summary}`;
307
+ }
308
+
309
+ export interface SuppressionReading {
310
+ /** Findings this round may report. */
311
+ kept: ReviewFinding[];
312
+ /** Findings dropped because an earlier round already raised them. */
313
+ suppressed: ReviewFinding[];
314
+ /** One line per suppressed finding, for the annotation. */
315
+ reasons: string[];
316
+ }
317
+
318
+ /**
319
+ * Drop findings an earlier round already raised.
320
+ *
321
+ * Keyed by `carryKey`, so a finding whose line number moved is still a
322
+ * repeat and a finding whose summary changed is not.
323
+ *
324
+ * **Within this round too.** A reviewer that lists the same defect twice in
325
+ * one payload is the same waste as one that lists it on two rounds, and the
326
+ * first occurrence is kept. An unkeyable finding (no file, no summary) is
327
+ * always kept: it cannot be shown to be a repeat, and the direction this is
328
+ * allowed to be wrong in is toward reporting.
329
+ *
330
+ * `priorKeys` is what earlier rounds raised. It is a parameter rather than
331
+ * something read here, because only the caller can reach the pull request's
332
+ * history, and a function that fetches its own evidence cannot be given a
333
+ * negative control.
334
+ */
335
+ export function suppressRepeats(
336
+ fresh: unknown,
337
+ priorKeys: Iterable<string>,
338
+ lineTextFor?: (f: ReviewFinding) => string | undefined,
339
+ ): SuppressionReading {
340
+ const seen = new Set<string>(priorKeys);
341
+ const kept: ReviewFinding[] = [];
342
+ const suppressed: ReviewFinding[] = [];
343
+ const reasons: string[] = [];
344
+ const list = Array.isArray(fresh) ? fresh : [];
345
+
346
+ for (const raw of list) {
347
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
348
+ kept.push(raw as ReviewFinding);
349
+ continue;
350
+ }
351
+ const f = raw as ReviewFinding;
352
+ const key = carryKey(f, lineTextFor?.(f));
353
+ if (key === null || !seen.has(key)) {
354
+ if (key !== null) seen.add(key);
355
+ kept.push(f);
356
+ continue;
357
+ }
358
+ suppressed.push(f);
359
+ reasons.push(
360
+ `${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
361
+ `raised on an earlier round of this pull request, so it is not raised again`,
362
+ );
363
+ }
364
+
365
+ return { kept, suppressed, reasons };
366
+ }
367
+
368
+ /**
369
+ * Which of an earlier round's findings are still unresolved at this commit?
370
+ *
371
+ * This is what makes a diff-scoped round honest. A diff-scoped reviewer never
372
+ * reads the code an earlier finding was about, so if the adjudicator does not
373
+ * re-emit the unresolved ones the finding vanishes and the check goes green —
374
+ * `46034035` arriving by a different door.
375
+ *
376
+ * A finding is RESOLVED when the line it names is no longer the line it named:
377
+ * `currentLineText` differs from the text recorded with the finding. It is
378
+ * UNRESOLVED when the text is unchanged. When the text cannot be read at all
379
+ * it is UNRESOLVED, because a finding nobody could check is not a finding
380
+ * anybody cleared — the direction `reviewIsCurrent` also fails in.
381
+ *
382
+ * **It is a CONTENT comparison and not `reviewIsCurrent`, deliberately.**
383
+ * That function compares two commit SHAs, which is the right reading for "is
384
+ * this whole review still about this branch" and the wrong one for "is this
385
+ * one finding still true". Measured on this repository's own two multi-round
386
+ * cases: on `rg/1175` the branch was rebased between rounds, so the commit
387
+ * that introduced the flagged line is not an ancestor of the round-1 head
388
+ * even though the line is byte-identical in it; on `fix/1129` the round-2
389
+ * commit is an amend of the round-1 one, so blame attributes a line to it
390
+ * that it did not touch. Both findings were stale and a SHA or ancestry
391
+ * reading calls both of them fresh. Content is the only reading that was
392
+ * right on both.
393
+ */
394
+ export interface CarriedFinding {
395
+ finding: ReviewFinding;
396
+ /** The text at the cited line when the finding was raised. */
397
+ recordedText?: string;
398
+ }
399
+
400
+ export function carryForward(
401
+ prior: readonly CarriedFinding[],
402
+ currentLineText: (f: ReviewFinding) => string | undefined,
403
+ ): ReviewFinding[] {
404
+ const out: ReviewFinding[] = [];
405
+ for (const entry of prior) {
406
+ // NOTHING WAS RECORDED, so resolution is UNDECIDABLE — carry it.
407
+ //
408
+ // This branch is the whole of the reading half's first defect. Without
409
+ // it, `normalise(undefined)` is `""`, which differs from any real line,
410
+ // so a finding whose text was never recorded is read as RESOLVED and
411
+ // dropped — silently, every time. Measured against the ledger #1319
412
+ // actually writes, which recorded `{severity, file, line, summary}` and
413
+ // no text: one finding in, zero carried out. An absent reading is not a
414
+ // reading that cleared, and this is the same refusal `roundOutcome`
415
+ // makes about an unreadable budget.
416
+ if (typeof entry.recordedText !== "string") {
417
+ out.push(entry.finding);
418
+ continue;
419
+ }
420
+ const now = currentLineText(entry.finding);
421
+ if (typeof now !== "string") {
422
+ out.push(entry.finding);
423
+ continue;
424
+ }
425
+ if (normalise(now) !== normalise(entry.recordedText)) continue;
426
+ out.push(entry.finding);
427
+ }
428
+ return out;
429
+ }
430
+
431
+ /* ───────────────── reading the ledger a previous round wrote ──────────────
432
+ *
433
+ * `lib/scaffold/ai-review-step.ts` upserts ONE comment per pull request
434
+ * holding one JSON entry per review round (#1319). Everything above this line
435
+ * takes the prior rounds as a parameter, deliberately — a function that
436
+ * fetches its own evidence cannot be given a negative control. This is the
437
+ * part that turns that comment into the parameter.
438
+ *
439
+ * The two properties it exists to hold, both of which are easy to lose:
440
+ *
441
+ * 1. **Identity is stated, not assumed.** The ledger stamps the rule its
442
+ * anchors were recorded under. A reader that meets a rule it does not
443
+ * know refuses to form keys rather than keying under its own — because
444
+ * keying under the wrong rule does not fail, it silently compares two
445
+ * different things and suppresses live findings.
446
+ *
447
+ * 2. **"Nothing recorded" and "could not read what was recorded" are
448
+ * different facts.** `lib/config-loader.ts` makes the same distinction
449
+ * about an absent config versus a corrupt one, for the same reason: both
450
+ * yield nothing, and only one of them is a reading. Here the type carries
451
+ * it — an unmeasured reading does not HAVE a `keys` field, so a caller
452
+ * cannot reach for one without narrowing the status first.
453
+ *
454
+ * These four constants are declared again in `lib/scaffold/ai-review-step.ts`
455
+ * and must agree. They are not imported from there, and that file must not
456
+ * import this one: the mutation batteries build a mutant by copying that file
457
+ * alone into a scratch directory, so a relative import added to it resolves
458
+ * to nothing and the mutant fails to LOAD — which reads as a behavioural
459
+ * difference on every row (`.claude/rules/self-referential-tests.md`, Tier 1).
460
+ * `test/ai-review-ledger-read.test.ts` AC-R6 binds all four instead.
461
+ */
462
+
463
+ /**
464
+ * The identity rule the ledger's recorded anchors were formed under.
465
+ *
466
+ * Versioned in the string itself. A reader meeting an identity it does not
467
+ * recognise carries the findings and declines to key them, so changing the
468
+ * rule is a safe, one-sided operation: old rounds stop suppressing, and
469
+ * nothing silently compares an old anchor against a new rule.
470
+ */
471
+ export const AI_REVIEW_LEDGER_IDENTITY = "file+text+summary@v1";
472
+
473
+ /** The HTML comment that identifies the ledger comment. */
474
+ export const AI_REVIEW_LEDGER_COMMENT_MARKER = "<!-- rungate:ai-review-ledger:v1 -->";
475
+
476
+ /** The key the per-round findings array is recorded under. */
477
+ export const AI_REVIEW_LEDGER_FINDINGS_KEY = "findings";
478
+
479
+ /**
480
+ * The key the round array hangs off in the windowed ledger shape.
481
+ *
482
+ * The ledger's JSON block was originally the array itself. That shape has no
483
+ * position to say anything ABOUT the array, which is #1405: a ledger holding
484
+ * twelve rounds because twelve is all there have been, and a ledger holding
485
+ * twelve because it evicted eight, are byte-identical. The eviction is
486
+ * announced in a warning annotation that lives in the job log and expires.
487
+ */
488
+ export const AI_REVIEW_LEDGER_ROUNDS_KEY = "rounds";
489
+
490
+ /** The key holding how many rounds the window has dropped off the front. */
491
+ export const AI_REVIEW_LEDGER_TRUNCATED_KEY = "truncated";
492
+
493
+ /** The key holding the text at the cited line when the finding was raised. */
494
+ export const AI_REVIEW_LEDGER_FINDING_TEXT = "text";
495
+
496
+ /**
497
+ * The key holding how many turns the reviewer spent on this round (#1380).
498
+ *
499
+ * #1380 measured 3 of 3 observable same-tree re-runs producing a DIFFERENT
500
+ * verdict, the strongest being merge commit `99d50fc` at round 5 both times,
501
+ * BLOCKED then CLEAN, at 51 turns and 52 against a cap of 80. The turn count
502
+ * is the only candidate mechanism anyone has for that, and it is the one
503
+ * thing about a round that nothing recorded.
504
+ *
505
+ * Mining the history cannot settle it: at the pre-#1198 26% payload rate,
506
+ * n=20 readable same-tree pairs needs ~290 re-runs and 28 exist. So the
507
+ * number has to be captured going forward or not at all, and this is the
508
+ * position that already records `sha`, `run`, `attempt`, `round` and
509
+ * `identity` per entry.
510
+ */
511
+ export const AI_REVIEW_LEDGER_TURNS_KEY = "turns";
512
+
513
+ /**
514
+ * The key holding the commit the reviewer actually read (#1380).
515
+ *
516
+ * NOT the same fact as `sha`, and that is the whole reason it exists. `sha`
517
+ * is `github.event.pull_request.head.sha`; the review ran over whatever
518
+ * `actions/checkout` put in the tree, which on a `pull_request` event is the
519
+ * MERGE commit — head merged into the base as it stood when the run started.
520
+ *
521
+ * So two rounds sharing a `sha` are not two rounds over one tree: the base
522
+ * moves without the head moving, and the reviewer sees different bytes. A
523
+ * same-tree pair is two rounds sharing THIS field, and #1380's whole
524
+ * conditioning caveat — 28 same-tree pairs, 3 readable — was derived from
525
+ * merge commits off the Actions API because the ledger could not answer it.
526
+ */
527
+ export const AI_REVIEW_LEDGER_MERGE_KEY = "merge";
528
+
529
+ /**
530
+ * The key holding the verdict WORD the reviewer wrote beside its findings
531
+ * (#1511).
532
+ *
533
+ * Not an adjudicated outcome and not derivable from `findings`. The payload
534
+ * contract asks the reviewer for a word, `lib/scaffold/ai-review-findings.ts`
535
+ * compares it to what the severities say, and a disagreement is a
536
+ * CONTRADICTION — #1178's shape, measured at roughly a third of runs. A
537
+ * reader handed findings alone can compute what the word SHOULD have been
538
+ * and cannot recover what it WAS, so the contradiction is unobservable
539
+ * through a ledger that does not record it.
540
+ *
541
+ * Which is what the ledger did until #1511, and why
542
+ * `evals/ai-review-control/` could reach `QUIET`, `FIRED` and `MISSED` and
543
+ * never `DETECTED`: every captured round scored `VERDICT_ABSENT`.
544
+ *
545
+ * Declared here and in `lib/scaffold/ai-review-step.ts` as
546
+ * `AI_REVIEW_VERDICT_KEY`, bound by `AC-R6` in
547
+ * `test/ai-review-ledger-read.test.ts` rather than by an import, because
548
+ * that module must stay import-free — the mutation batteries copy it into a
549
+ * temp directory where no relative specifier resolves.
550
+ */
551
+ export const AI_REVIEW_LEDGER_VERDICT_KEY = "verdict";
552
+
553
+ /** The round predates #1511. Nobody tried to record a verdict word. */
554
+ export const AI_REVIEW_VERDICT_NOT_RECORDED = "AI_REVIEW_VERDICT_NOT_RECORDED";
555
+
556
+ /** The round tried to record a verdict word and found none to record. */
557
+ export const AI_REVIEW_VERDICT_UNREADABLE = "AI_REVIEW_VERDICT_UNREADABLE";
558
+
559
+ /** A verdict word was recorded. What it SAYS is the adjudicator's question. */
560
+ export const AI_REVIEW_VERDICT_RECORDED = "AI_REVIEW_VERDICT_RECORDED";
561
+
562
+ /**
563
+ * The verdict word a round recorded, or why there is none.
564
+ *
565
+ * Three states and not two, the same split `turns` carries one key over and
566
+ * for the same reason: a round written before #1511 has no key, and a round
567
+ * written after it always has one. Collapsing them makes a ledger that never
568
+ * recorded a verdict indistinguishable from a reviewer that wrote none.
569
+ *
570
+ * `word` is `unknown` and is **never validated here**. Whether `PASS` and
571
+ * `BLOCK` are the only legal words is
572
+ * `lib/scaffold/ai-review-findings.ts`' decision and it already makes it;
573
+ * a second gate here would be two deciders answering one question, of which
574
+ * a mutation leaves either one holding the case up. A ledger carrying
575
+ * `MAYBE` reports `MAYBE`, and the adjudicator calls it
576
+ * `VERDICT_UNRECOGNISED` — which is the truth about that round.
577
+ */
578
+ export type LedgerVerdictReading =
579
+ | { status: typeof AI_REVIEW_VERDICT_NOT_RECORDED }
580
+ | { status: typeof AI_REVIEW_VERDICT_UNREADABLE }
581
+ | { status: typeof AI_REVIEW_VERDICT_RECORDED; word: unknown };
582
+
583
+ /**
584
+ * Read the verdict word off a ledger round.
585
+ *
586
+ * `undefined` — no key at all — is NOT_RECORDED. A JSON `null` is the
587
+ * writer saying it looked and found nothing, which is UNREADABLE. Anything
588
+ * else is carried through verbatim, including shapes no contract declares.
589
+ */
590
+ export function readRoundVerdict(raw: unknown): LedgerVerdictReading {
591
+ if (raw === undefined) return { status: AI_REVIEW_VERDICT_NOT_RECORDED };
592
+ if (raw === null) return { status: AI_REVIEW_VERDICT_UNREADABLE };
593
+ return { status: AI_REVIEW_VERDICT_RECORDED, word: raw };
594
+ }
595
+
596
+ /** The round predates #1380. Nobody tried to read a turn count. */
597
+ export const AI_REVIEW_TURNS_NOT_RECORDED = "AI_REVIEW_TURNS_NOT_RECORDED";
598
+
599
+ /** This round tried to read a turn count and could not. */
600
+ export const AI_REVIEW_TURNS_UNREADABLE = "AI_REVIEW_TURNS_UNREADABLE";
601
+
602
+ /** The turn count was read. */
603
+ export const AI_REVIEW_TURNS_READ = "AI_REVIEW_TURNS_READ";
604
+
605
+ /**
606
+ * How many turns the reviewer spent, or why that is not known.
607
+ *
608
+ * The non-READ arms carry **no count field at all**, the construction
609
+ * `LedgerTruncation` and `PriorState` already use here: a caller cannot
610
+ * reach for a number without narrowing the status first, so "I could not
611
+ * tell" has no way to be read as zero. `0` is the answer that matters —
612
+ * a run whose execution file never arrived and a run that spent no turns
613
+ * are not the same event, and a `?? 0` makes them one.
614
+ *
615
+ * THREE STATES AND NOT TWO. Absent is NOT_RECORDED and `null` is
616
+ * UNREADABLE, which is the same split `findings` already carries one key
617
+ * over: every round written before #1380 has no key, and a round written
618
+ * after it always has one. Collapsing them would make a ledger that
619
+ * measured nothing indistinguishable from a ledger written last week.
620
+ */
621
+ export type TurnReading =
622
+ | { status: typeof AI_REVIEW_TURNS_NOT_RECORDED }
623
+ | { status: typeof AI_REVIEW_TURNS_UNREADABLE }
624
+ | { status: typeof AI_REVIEW_TURNS_READ; turns: number };
625
+
626
+ /**
627
+ * Read the turn count off a ledger round.
628
+ *
629
+ * `undefined` — no key at all — is NOT_RECORDED. Anything that is not a
630
+ * non-negative integer is UNREADABLE rather than the nearest number: a
631
+ * `"51"` the writer never produces, a float, a negative, `null` itself.
632
+ * There is no branch that returns a count it had to repair.
633
+ */
634
+ export function readRoundTurns(raw: unknown): TurnReading {
635
+ if (raw === undefined) return { status: AI_REVIEW_TURNS_NOT_RECORDED };
636
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
637
+ return { status: AI_REVIEW_TURNS_UNREADABLE };
638
+ }
639
+ return { status: AI_REVIEW_TURNS_READ, turns: raw };
640
+ }
641
+
642
+ /** No ledger comment on this pull request. A MEASURED reading of nothing. */
643
+ export const AI_REVIEW_LEDGER_ABSENT = "AI_REVIEW_LEDGER_ABSENT";
644
+
645
+ /** A ledger is there and could not be read. NOT the same as absent. */
646
+ export const AI_REVIEW_LEDGER_UNREADABLE = "AI_REVIEW_LEDGER_UNREADABLE";
647
+
648
+ /** The ledger was read. */
649
+ export const AI_REVIEW_LEDGER_READ = "AI_REVIEW_LEDGER_READ";
650
+
651
+ /** Keyed on the file, the recorded TEXT of the cited line, and the summary. */
652
+ export const FINDING_IDENTITY_TEXT = "file+text+summary";
653
+
654
+ /**
655
+ * Keyed on the file, the cited line NUMBER, and the summary.
656
+ *
657
+ * Weaker, and recorded as such rather than passed off as the above: the one
658
+ * repeat this repository can demonstrate moved `:318` → `:375` between rounds
659
+ * while staying byte-identical, so this key would have missed it.
660
+ */
661
+ export const FINDING_IDENTITY_LINE = "file+line+summary";
662
+
663
+ /** No key could be formed. The finding is carried and suppresses nothing. */
664
+ export const FINDING_IDENTITY_NONE = "unclassifiable";
665
+
666
+ export type FindingIdentity =
667
+ | typeof FINDING_IDENTITY_TEXT
668
+ | typeof FINDING_IDENTITY_LINE
669
+ | typeof FINDING_IDENTITY_NONE;
670
+
671
+ export interface LedgerRound {
672
+ /** The round number the entry recorded, or null if it recorded none. */
673
+ round: number | null;
674
+ /** The pull request's HEAD commit at the round. NOT the tree reviewed. */
675
+ sha: string;
676
+ /**
677
+ * The commit the reviewer actually read — see `AI_REVIEW_LEDGER_MERGE_KEY`.
678
+ * `""` when the entry recorded none, which is every round before #1380.
679
+ */
680
+ mergeSha: string;
681
+ /** How many turns the reviewer spent, or why that is unknown (#1380). */
682
+ turns: TurnReading;
683
+ /** The verdict word the reviewer wrote, or why there is none (#1511). */
684
+ verdict: LedgerVerdictReading;
685
+ /** False when the entry recorded `findings: null`, or was not an object. */
686
+ measured: boolean;
687
+ /** True when the entry stamped the identity rule this reader knows. */
688
+ keyable: boolean;
689
+ findings: ReviewFinding[];
690
+ }
691
+
692
+ /** How many rounds fell off the front of the window could not be established. */
693
+ export const AI_REVIEW_TRUNCATION_UNKNOWN = "AI_REVIEW_TRUNCATION_UNKNOWN";
694
+
695
+ /** The ledger states how many rounds it has dropped. `0` is a statement. */
696
+ export const AI_REVIEW_TRUNCATION_STATED = "AI_REVIEW_TRUNCATION_STATED";
697
+
698
+ /**
699
+ * The round cap in force when every bare-array ledger in existence was
700
+ * written (#1447).
701
+ *
702
+ * **Deliberately not `AI_REVIEW_LEDGER_MAX_ROUNDS`, and deliberately not
703
+ * imported from it.** Two separate reasons, and they are both load-bearing:
704
+ *
705
+ * The derivation below — *a bare array shorter than its cap was never cut* —
706
+ * is only sound against the cap that was in force when that array was
707
+ * written. Binding it to the live cap would mean lowering the cap tomorrow
708
+ * silently re-reads ledgers written months ago as complete when they were
709
+ * truncated. It cannot do that here: the bare-array shape is CLOSED. #1405's
710
+ * writer migrates every ledger it touches to `{rounds, truncated}`, so no new
711
+ * bare array will ever be written and the population this constant describes
712
+ * is fixed. A fact about history is spelled as a historical constant.
713
+ *
714
+ * The value is 12 because `AI_REVIEW_LEDGER_MAX_ROUNDS` has been 12 since it
715
+ * was introduced in `41f2e93f` (#1168) and has never held another value —
716
+ * checked rather than assumed, because a cap that had once been lower would
717
+ * make every bare array between the old cap and 12 read as a complete history
718
+ * when it had been cut. That is the direction `lib/rounds-to-pass.ts` warns
719
+ * about in its own docblock: this metric's errors all flatter.
720
+ *
721
+ * And this module must gain no import. Mutation batteries copy it into a
722
+ * tmpdir, where a relative import dies on module resolution and the mutant
723
+ * reads as a refusal rather than as a guard that held —
724
+ * `.claude/rules/self-referential-tests.md`, Tier 1.
725
+ */
726
+ export const AI_REVIEW_LEGACY_LEDGER_CAP = 12;
727
+
728
+ /**
729
+ * Whether the rounds in hand are the whole history.
730
+ *
731
+ * UNKNOWN carries **no count field at all**, the same construction
732
+ * `PriorState` uses: a caller cannot reach for a number without narrowing the
733
+ * status first, so "I could not tell" has no way to be read as zero. That is
734
+ * the defect this type exists to make unrepresentable — on #1396 an
735
+ * unreadable eviction count and "nothing was dropped" shared a `case` arm in
736
+ * the shell, and the ledger was written having evicted rounds it did not
737
+ * mention.
738
+ *
739
+ * A legacy ledger — the bare array, written before #1405 — is UNKNOWN and not
740
+ * zero. It may well be complete, and nothing in it says so.
741
+ */
742
+ export type LedgerTruncation =
743
+ | { status: typeof AI_REVIEW_TRUNCATION_UNKNOWN; reason: string }
744
+ | { status: typeof AI_REVIEW_TRUNCATION_STATED; dropped: number };
745
+
746
+ /**
747
+ * The UNREADABLE arm, named so one construction site serves both a READING
748
+ * of a ledger body and a SELECTION among comments. Two literals would be two
749
+ * things to keep in step for one fact.
750
+ */
751
+ export type LedgerUnreadable = {
752
+ status: typeof AI_REVIEW_LEDGER_UNREADABLE;
753
+ reason: string;
754
+ };
755
+
756
+ export type LedgerReading =
757
+ | { status: typeof AI_REVIEW_LEDGER_ABSENT }
758
+ | LedgerUnreadable
759
+ | {
760
+ status: typeof AI_REVIEW_LEDGER_READ;
761
+ rounds: LedgerRound[];
762
+ truncation: LedgerTruncation;
763
+ };
764
+
765
+ /**
766
+ * Say that the ledger could not be read, for a reason only the caller knows.
767
+ *
768
+ * The API call that lists a pull request's comments can fail, and when it
769
+ * does the caller has no body to hand to `readLedger`. Without this it would
770
+ * have to pass `null`, which reads as ABSENT — a failed fetch would then be
771
+ * indistinguishable from a pull request on its first round, and every earlier
772
+ * finding would silently stop being carried.
773
+ */
774
+ export function ledgerUnreadable(reason: string): LedgerUnreadable {
775
+ return { status: AI_REVIEW_LEDGER_UNREADABLE, reason };
776
+ }
777
+
778
+ /**
779
+ * The login the ledger comment is written as, and the only one selected.
780
+ *
781
+ * **This clause is the load-bearing one, and the repository's own tracker is
782
+ * the counter-example that makes it so.** The rationale this selection used
783
+ * to carry said the conjunction was safe because *nothing else writes the
784
+ * marker*. Measured against the live API on 2026-10-24, pull requests #1319
785
+ * and #1386 each carry TWO comments containing
786
+ * `AI_REVIEW_LEDGER_COMMENT_MARKER`: the ledger, written by
787
+ * `github-actions[bot]`, and a `type: "User"` comment that quotes the marker
788
+ * while discussing it. The marker is a quotable string and uniqueness of a
789
+ * quotable string is not obtainable — so making the marker more exotic is
790
+ * not the answer, and the login clause is what separates the two today.
791
+ *
792
+ * `lib/scaffold/ai-review-step.ts` declares the same string as
793
+ * `AI_REVIEW_LEDGER_BOT_LOGIN` and `test/ai-review-ledger-selection.test.ts`
794
+ * binds the two, rather than importing: that module is copied into a tmpdir
795
+ * by mutation batteries, where a relative specifier dies on resolution.
796
+ */
797
+ export const AI_REVIEW_LEDGER_BOT_LOGIN_NAME = "github-actions[bot]";
798
+
799
+ /**
800
+ * How many comments on one pull request may be the ledger. **One.**
801
+ *
802
+ * The single site every ambiguity refusal below is routed through, so a test
803
+ * can build a mutant copy of this module with the bound widened and watch
804
+ * the refusal stop happening. Raise it and `selectLedgerComment` returns the
805
+ * first match instead — which is the defect, performed and observed, rather
806
+ * than a sentence claiming the guard works
807
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
808
+ */
809
+ export const AI_REVIEW_LEDGER_MAX_MATCHES = 1;
810
+
811
+ /**
812
+ * A pull-request comment, reduced to the four fields the selection reads.
813
+ *
814
+ * Every field is `unknown` because they arrive from an API response that a
815
+ * caller has at best parsed, never validated. A comment whose author block
816
+ * is missing is not a comment this selection may adopt.
817
+ */
818
+ export interface LedgerCandidate {
819
+ id: unknown;
820
+ body: unknown;
821
+ login: unknown;
822
+ type: unknown;
823
+ }
824
+
825
+ /** A candidate that passed the selection — every field narrowed. */
826
+ export interface LedgerComment {
827
+ id: number;
828
+ body: string;
829
+ login: string;
830
+ type: string;
831
+ }
832
+
833
+ /**
834
+ * Which comment on a pull request IS the ledger, or why that is not knowable.
835
+ *
836
+ * Deliberately the same three statuses `LedgerReading` uses, because they are
837
+ * the same three facts one step earlier: there is no ledger here, there is
838
+ * something here that cannot be read as one, or here it is. A fourth status
839
+ * would be a second vocabulary for a question already answered.
840
+ */
841
+ export type LedgerSelection =
842
+ | { status: typeof AI_REVIEW_LEDGER_ABSENT }
843
+ | LedgerUnreadable
844
+ | { status: typeof AI_REVIEW_LEDGER_READ; comment: LedgerComment };
845
+
846
+ /**
847
+ * Pick the ledger out of a pull request's comments, or REFUSE.
848
+ *
849
+ * **Two matches is not a reading, and the first of them is not an answer.**
850
+ * This is the whole of #1412: a reader handed more than one comment carrying
851
+ * the ledger marker has no way to tell which document it is about, and a
852
+ * wrong comment that parses is byte-indistinguishable from a right one — so
853
+ * every number computed off it (rounds-to-pass, the unmeasured split, the
854
+ * turn counts) would be read off a population nobody can name. Ambiguous and
855
+ * absent are different states and neither one is a ledger.
856
+ *
857
+ * Three readings, and they are kept apart on purpose:
858
+ *
859
+ * * **ABSENT** — no comment here was written by this bot carrying the
860
+ * marker. A MEASURED reading of nothing, correct and complete on round
861
+ * one, and the only one that licenses POSTing a first ledger.
862
+ * * **UNREADABLE** — more than one did. The reason names every id, because
863
+ * a refusal that does not say which documents collided is a refusal
864
+ * nobody can act on.
865
+ * * **READ** — exactly one, narrowed.
866
+ *
867
+ * A `type: "User"` comment quoting the marker is not a candidate and does
868
+ * not make the reading ambiguous either: it is not a ledger, so it is not
869
+ * one of the things that could be. See `AI_REVIEW_LEDGER_BOT_LOGIN_NAME` for
870
+ * why that clause — and not the marker's supposed uniqueness — is what makes
871
+ * this selection an identity.
872
+ */
873
+ export function selectLedgerComment(
874
+ comments: readonly LedgerCandidate[],
875
+ ): LedgerSelection {
876
+ const matches: LedgerComment[] = [];
877
+ for (const c of comments) {
878
+ if (c.type !== "Bot") continue;
879
+ if (c.login !== AI_REVIEW_LEDGER_BOT_LOGIN_NAME) continue;
880
+ if (typeof c.body !== "string") continue;
881
+ if (!c.body.includes(AI_REVIEW_LEDGER_COMMENT_MARKER)) continue;
882
+ if (typeof c.id !== "number" || !Number.isInteger(c.id)) {
883
+ return ledgerUnreadable(
884
+ `a comment written by ${AI_REVIEW_LEDGER_BOT_LOGIN_NAME} carries the ledger ` +
885
+ `marker and reports ${JSON.stringify(c.id)} as its id, which is not one, so ` +
886
+ "it cannot be addressed and is not being treated as absent",
887
+ );
888
+ }
889
+ matches.push({ id: c.id, body: c.body, login: c.login, type: c.type });
890
+ }
891
+ if (matches.length === 0) return { status: AI_REVIEW_LEDGER_ABSENT };
892
+ if (matches.length > AI_REVIEW_LEDGER_MAX_MATCHES) {
893
+ return ledgerUnreadable(
894
+ `${matches.length} comments on this pull request are written by ` +
895
+ `${AI_REVIEW_LEDGER_BOT_LOGIN_NAME} and carry the ledger marker (ids ` +
896
+ `${matches.map(m => m.id).join(", ")}), so which one is the ledger cannot be ` +
897
+ "established. Refusing to read the first: a wrong ledger that parses is " +
898
+ "indistinguishable from the right one afterwards",
899
+ );
900
+ }
901
+ return { status: AI_REVIEW_LEDGER_READ, comment: matches[0] };
902
+ }
903
+
904
+ /**
905
+ * Parse the ledger comment's body.
906
+ *
907
+ * `null`, `undefined` and a body without the marker are ABSENT: there is no
908
+ * ledger, which is the correct and complete reading on round one. A body that
909
+ * HAS the marker and whose JSON block is missing, truncated, unparseable or
910
+ * neither of the two round shapes is UNREADABLE — never an empty ledger,
911
+ * because treating a damaged ledger as empty discards every round it holds at
912
+ * exactly the moment nothing can tell that it happened.
913
+ *
914
+ * Two round shapes are accepted and the reading says which was found through
915
+ * `truncation`: a bare array, which is every ledger written before #1405 and
916
+ * is still live on open pull requests, and `{rounds, truncated}`, which can
917
+ * say how much of the history fell off the front of the window. Rejecting the
918
+ * bare array would discard the history of every pull request mid-flight at
919
+ * the moment the new writer merged.
920
+ */
921
+ export function readLedger(body: unknown): LedgerReading {
922
+ if (typeof body !== "string") return { status: AI_REVIEW_LEDGER_ABSENT };
923
+ const marker = body.indexOf(AI_REVIEW_LEDGER_COMMENT_MARKER);
924
+ if (marker === -1) return { status: AI_REVIEW_LEDGER_ABSENT };
925
+
926
+ const fence = body.indexOf("```json", marker);
927
+ if (fence === -1) {
928
+ return ledgerUnreadable(
929
+ "the ledger comment is present and holds no ```json block, so the rounds it " +
930
+ "recorded cannot be read; it is not being treated as an empty ledger",
931
+ );
932
+ }
933
+ const start = body.indexOf("\n", fence);
934
+ const close = start === -1 ? -1 : body.indexOf("\n```", start);
935
+ if (close === -1) {
936
+ return ledgerUnreadable(
937
+ "the ledger comment's ```json block is not closed, so it was truncated in " +
938
+ "transit or in storage and the rounds it recorded cannot be read",
939
+ );
940
+ }
941
+
942
+ let parsed: unknown;
943
+ try {
944
+ parsed = JSON.parse(body.slice(start + 1, close));
945
+ } catch (e) {
946
+ return ledgerUnreadable(
947
+ `the ledger comment's JSON block could not be parsed (${
948
+ e instanceof Error ? e.message : String(e)
949
+ }), so the rounds it recorded cannot be read`,
950
+ );
951
+ }
952
+ // Two shapes, and the older one is still on every open pull request that
953
+ // has a ledger. A bare array is the pre-#1405 ledger: readable, and silent
954
+ // about whether it is the whole history — but not therefore unknowable.
955
+ if (Array.isArray(parsed)) {
956
+ return {
957
+ status: AI_REVIEW_LEDGER_READ,
958
+ rounds: parsed.map(toLedgerRound),
959
+ truncation: legacyTruncation(parsed.length),
960
+ };
961
+ }
962
+ if (typeof parsed !== "object" || parsed === null) {
963
+ return ledgerUnreadable(
964
+ `the ledger comment's JSON block is ${describe(parsed)} rather than an array of ` +
965
+ "rounds, so the rounds it recorded cannot be read",
966
+ );
967
+ }
968
+ const obj = parsed as Record<string, unknown>;
969
+ const rounds = obj[AI_REVIEW_LEDGER_ROUNDS_KEY];
970
+ if (!Array.isArray(rounds)) {
971
+ return ledgerUnreadable(
972
+ `the ledger comment's JSON block is an object whose \`${AI_REVIEW_LEDGER_ROUNDS_KEY}\` ` +
973
+ `is ${describe(rounds)} rather than an array, so the rounds it recorded cannot be read`,
974
+ );
975
+ }
976
+ return {
977
+ status: AI_REVIEW_LEDGER_READ,
978
+ rounds: rounds.map(toLedgerRound),
979
+ truncation: readTruncation(obj[AI_REVIEW_LEDGER_TRUNCATED_KEY]),
980
+ };
981
+ }
982
+
983
+ /**
984
+ * How deep a legacy bare-array ledger is, derived from its length (#1447).
985
+ *
986
+ * The list grows by exactly one entry per round and is only ever cut when it
987
+ * reaches the cap, so **a length below the cap means the cut never ran** and
988
+ * the array is the whole history. That is a derivation from the writer's
989
+ * behaviour, not an assumption about it, and #1405's writer already makes the
990
+ * identical one when it migrates such a ledger forward — this is the reader
991
+ * catching up to it, for the ledgers no future round will ever touch.
992
+ *
993
+ * At or above the cap the length is a LOWER BOUND and nothing more: this
994
+ * round's eviction is knowable and the ones before it are not, and writing
995
+ * the bound as a count would hand a caller a number it cannot tell from a
996
+ * total.
997
+ *
998
+ * The cheap wrong fix is to call every bare array complete. It passes every
999
+ * case below the cap and is wrong at it, which is why
1000
+ * `test/ai-review-ledger-read.test.ts` puts 11 and 12 adjacent.
1001
+ */
1002
+ function legacyTruncation(length: number): LedgerTruncation {
1003
+ if (length < AI_REVIEW_LEGACY_LEDGER_CAP) {
1004
+ return { status: AI_REVIEW_TRUNCATION_STATED, dropped: 0 };
1005
+ }
1006
+ return {
1007
+ status: AI_REVIEW_TRUNCATION_UNKNOWN,
1008
+ reason:
1009
+ `the ledger's JSON block is a bare array of ${length} rounds, the shape written ` +
1010
+ `before the \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` count existed, and it is at or past ` +
1011
+ `the ${AI_REVIEW_LEGACY_LEDGER_CAP}-round cap those ledgers were written under. A ` +
1012
+ `shorter one could be derived complete — the list only grows by one per round and is ` +
1013
+ `only cut at the cap — but at the cap its length is a lower bound on the rounds it ` +
1014
+ `held and says nothing about how many fell off the front`,
1015
+ };
1016
+ }
1017
+
1018
+ /**
1019
+ * Read the dropped-round count off a windowed ledger.
1020
+ *
1021
+ * A malformed count is UNKNOWN, never zero, and never a reason to refuse the
1022
+ * whole ledger: the rounds in hand are still real and still carryable. What
1023
+ * the caller must not be able to do is report the history as complete on the
1024
+ * strength of a field it could not read — which is exactly what a `?? 0`
1025
+ * here would let it do.
1026
+ */
1027
+ function readTruncation(raw: unknown): LedgerTruncation {
1028
+ if (raw === undefined) {
1029
+ return {
1030
+ status: AI_REVIEW_TRUNCATION_UNKNOWN,
1031
+ reason:
1032
+ `the ledger is an object and carries no \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` key, so ` +
1033
+ "it states nothing about rounds dropped off the front",
1034
+ };
1035
+ }
1036
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
1037
+ return {
1038
+ status: AI_REVIEW_TRUNCATION_UNKNOWN,
1039
+ reason:
1040
+ `the ledger's \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` is ${describe(raw)} rather than a ` +
1041
+ "non-negative integer, so how many rounds it dropped cannot be established",
1042
+ };
1043
+ }
1044
+ return { status: AI_REVIEW_TRUNCATION_STATED, dropped: raw };
1045
+ }
1046
+
1047
+ function toLedgerRound(raw: unknown): LedgerRound {
1048
+ // An entry that is not an object is a round that was recorded and cannot be
1049
+ // read. It is counted, not skipped: a round that vanishes from the count
1050
+ // makes a three-round pull request look like a two-round one.
1051
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
1052
+ // An unreadable entry has not stated a turn count, and it has not failed
1053
+ // to read one either — nobody got as far as asking. NOT_RECORDED, which
1054
+ // is also what every pre-#1380 round reads as.
1055
+ return {
1056
+ round: null,
1057
+ sha: "",
1058
+ mergeSha: "",
1059
+ turns: { status: AI_REVIEW_TURNS_NOT_RECORDED },
1060
+ // Nobody got as far as asking, which is NOT_RECORDED for the same
1061
+ // reason the turn count above is: an entry that is not an object has
1062
+ // not stated a verdict and has not failed to state one.
1063
+ verdict: { status: AI_REVIEW_VERDICT_NOT_RECORDED },
1064
+ measured: false,
1065
+ keyable: false,
1066
+ findings: [],
1067
+ };
1068
+ }
1069
+ const e = raw as Record<string, unknown>;
1070
+ const list = e[AI_REVIEW_LEDGER_FINDINGS_KEY];
1071
+ const measured = Array.isArray(list);
1072
+ return {
1073
+ round: readRoundNumber(e.round),
1074
+ sha: typeof e.sha === "string" ? e.sha : "",
1075
+ mergeSha:
1076
+ typeof e[AI_REVIEW_LEDGER_MERGE_KEY] === "string"
1077
+ ? (e[AI_REVIEW_LEDGER_MERGE_KEY] as string)
1078
+ : "",
1079
+ turns: readRoundTurns(e[AI_REVIEW_LEDGER_TURNS_KEY]),
1080
+ verdict: readRoundVerdict(e[AI_REVIEW_LEDGER_VERDICT_KEY]),
1081
+ measured,
1082
+ keyable: e.identity === AI_REVIEW_LEDGER_IDENTITY,
1083
+ findings: measured
1084
+ ? (list as unknown[]).filter(
1085
+ (f): f is ReviewFinding => typeof f === "object" && f !== null && !Array.isArray(f),
1086
+ )
1087
+ : [],
1088
+ };
1089
+ }
1090
+
1091
+ /** The prior state could not be established at all. */
1092
+ export const AI_REVIEW_PRIOR_UNMEASURED = "AI_REVIEW_PRIOR_UNMEASURED";
1093
+
1094
+ /** The prior state was established — possibly as nothing. */
1095
+ export const AI_REVIEW_PRIOR_MEASURED = "AI_REVIEW_PRIOR_MEASURED";
1096
+
1097
+ export interface PriorFinding {
1098
+ finding: ReviewFinding;
1099
+ /**
1100
+ * The text at the cited line when the finding was raised. Absent when the
1101
+ * ledger did not record one — and absent is UNDECIDABLE in `carryForward`,
1102
+ * not resolved.
1103
+ */
1104
+ recordedText?: string;
1105
+ /** Which rule formed this finding's key. Stated, so a caller can weigh it. */
1106
+ identity: FindingIdentity;
1107
+ /** The key, or null when no identity could be formed. */
1108
+ key: string | null;
1109
+ /** The round it was raised on, where the ledger recorded one. */
1110
+ round: number | null;
1111
+ }
1112
+
1113
+ export type PriorState =
1114
+ | { status: typeof AI_REVIEW_PRIOR_UNMEASURED; reason: string }
1115
+ | {
1116
+ status: typeof AI_REVIEW_PRIOR_MEASURED;
1117
+ /** Keys earlier rounds raised, for `suppressRepeats`. */
1118
+ keys: string[];
1119
+ /** Everything earlier rounds raised, for `carryForward`. */
1120
+ prior: PriorFinding[];
1121
+ /** Rounds recorded whose findings were never read. */
1122
+ unmeasuredRounds: number;
1123
+ /** Rounds read under an identity rule this reader does not know. */
1124
+ unkeyableRounds: number;
1125
+ };
1126
+
1127
+ /**
1128
+ * Turn a ledger reading into what `suppressRepeats` and `carryForward` take.
1129
+ *
1130
+ * `PriorFinding` is assignable to `CarriedFinding`, so `prior` goes straight
1131
+ * into `carryForward` with no adapter between them — that join is the point
1132
+ * of the shape.
1133
+ *
1134
+ * **An UNREADABLE ledger returns a state with no `keys` and no `prior`.** Not
1135
+ * empty ones: absent ones. A caller holding an unmeasured state cannot
1136
+ * suppress a finding or resolve one, and the type stops it reaching for the
1137
+ * fields that would let it, instead of trusting it to check a boolean nobody
1138
+ * has to read.
1139
+ */
1140
+ export function priorFindings(reading: LedgerReading): PriorState {
1141
+ if (reading.status === AI_REVIEW_LEDGER_UNREADABLE) {
1142
+ return { status: AI_REVIEW_PRIOR_UNMEASURED, reason: reading.reason };
1143
+ }
1144
+ if (reading.status === AI_REVIEW_LEDGER_ABSENT) {
1145
+ return {
1146
+ status: AI_REVIEW_PRIOR_MEASURED,
1147
+ keys: [],
1148
+ prior: [],
1149
+ unmeasuredRounds: 0,
1150
+ unkeyableRounds: 0,
1151
+ };
1152
+ }
1153
+
1154
+ const keys: string[] = [];
1155
+ const prior: PriorFinding[] = [];
1156
+ let unmeasuredRounds = 0;
1157
+ let unkeyableRounds = 0;
1158
+
1159
+ for (const round of reading.rounds) {
1160
+ if (!round.measured) {
1161
+ unmeasuredRounds++;
1162
+ continue;
1163
+ }
1164
+ if (!round.keyable) unkeyableRounds++;
1165
+ for (const finding of round.findings) {
1166
+ const recorded = finding[AI_REVIEW_LEDGER_FINDING_TEXT];
1167
+ const recordedText = typeof recorded === "string" ? recorded : undefined;
1168
+ let identity: FindingIdentity = FINDING_IDENTITY_NONE;
1169
+ let key: string | null = null;
1170
+ // Only a round stamped with the rule this reader knows gets a key. An
1171
+ // unrecognised rule is carried, never dropped, and never keyed.
1172
+ if (round.keyable) {
1173
+ key = carryKey(finding, recordedText);
1174
+ if (key !== null) {
1175
+ identity = normalise(recordedText) !== "" ? FINDING_IDENTITY_TEXT : FINDING_IDENTITY_LINE;
1176
+ keys.push(key);
1177
+ }
1178
+ }
1179
+ prior.push({ finding, recordedText, identity, key, round: round.round });
1180
+ }
1181
+ }
1182
+
1183
+ return { status: AI_REVIEW_PRIOR_MEASURED, keys, prior, unmeasuredRounds, unkeyableRounds };
1184
+ }
1185
+
1186
+ /**
1187
+ * What the reviewer is told once the budget is spent.
1188
+ *
1189
+ * **A cap is not a silencer.** A reviewer that goes quiet at round 4 has
1190
+ * handed the author a green check on a pull request three reviews have failed
1191
+ * to settle, which is the outcome the cap exists to prevent, not the one it
1192
+ * is for. So the reviewer still runs and still writes a payload; what changes
1193
+ * is the question it is answering.
1194
+ *
1195
+ * Emitted at a NON-blocking severity by contract — the text says so — because
1196
+ * "this approach is not converging" is not a defect at a line and the payload
1197
+ * contract refuses a blocking finding that cannot name one. The round that
1198
+ * blocks is the one that found the bug; this one is advice.
1199
+ */
1200
+ export function atCapInstruction(round: number, cap: number = AI_REVIEW_ROUND_CAP): string {
1201
+ return (
1202
+ `THIS IS REVIEW ROUND ${round}. This pull request has already had ${cap} rounds of ` +
1203
+ `review and has not settled, so do not spend this round listing more defects.\n` +
1204
+ `\n` +
1205
+ `Step back and say something about the APPROACH instead. Three rounds that each ` +
1206
+ `found something is evidence about the change, not about the reviewer: the usual ` +
1207
+ `causes are a change that is doing more than one thing, a defect class being fixed ` +
1208
+ `one line at a time, or a design that makes the defect easy to reintroduce. Say ` +
1209
+ `which of those you think this is and what you would do instead.\n` +
1210
+ `\n` +
1211
+ `Write ONE finding, at a non-blocking severity, whose summary is that assessment. ` +
1212
+ `Do not raise it to a blocking severity: the budget being spent is not itself a ` +
1213
+ `defect at a line, and a blocking finding that cannot name one makes the whole ` +
1214
+ `review unreadable. Stay silent and the author gets a green check on a pull ` +
1215
+ `request three reviews could not settle, which is worse than either.`
1216
+ );
1217
+ }
1218
+
1219
+ /**
1220
+ * The block appended to the prompt listing what has already been said.
1221
+ *
1222
+ * Handed to the reviewer as well as enforced by the adjudicator, and both on
1223
+ * purpose: the instruction saves the round, and the adjudicator makes the
1224
+ * saving checkable. An instruction nobody enforces is a request.
1225
+ */
1226
+ export function noRepeatsInstruction(priorSummaries: readonly string[]): string {
1227
+ if (priorSummaries.length === 0) return "";
1228
+ const list = priorSummaries.map(s => ` - ${s}`).join("\n");
1229
+ return (
1230
+ `ALREADY RAISED ON AN EARLIER ROUND OF THIS PULL REQUEST. Do not report any of ` +
1231
+ `these again, at any severity, however you would word it:\n` +
1232
+ `${list}\n` +
1233
+ `\n` +
1234
+ `A later step drops a finding that matches one of these on the file, the text of ` +
1235
+ `the cited line and the summary — it does NOT match on the line number, so moving ` +
1236
+ `the same defect to a new line does not make it a new finding. Report what is new ` +
1237
+ `on this round, or report nothing.`
1238
+ );
1239
+ }
1240
+
1241
+ function describe(v: unknown): string {
1242
+ if (v === undefined) return "nothing";
1243
+ if (v === null) return "null";
1244
+ if (Array.isArray(v)) return `an array of ${v.length}`;
1245
+ if (typeof v === "object") return "an object";
1246
+ return JSON.stringify(v);
1247
+ }
1248
+
1249
+ export { SECURITY_REREVIEW_EXHAUSTED };