rungate 0.8.5 → 0.8.7

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.
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- d12afb85b5ce604fa58cf050d86b431d8f5d26e9e0dc5f33320e97f7bf51bbc3
1
+ aa2a5af1b31b712c5702035b4740c14f591f59fdcbed342e791976869850bfd2
@@ -538,6 +538,15 @@ export function juryLedgerRow(
538
538
  // so there is no earlier filing of this title for one to be a re-draft
539
539
  // of. `null` is the reading here, not an unperformed lookup (#1536).
540
540
  refiledAfter: null,
541
+ // #1595's declaration is read off a `gh issue create` command line, and
542
+ // a review round has none. `null` is the reading — nobody could have
543
+ // declared one here — and not a declaration that was looked for and
544
+ // missing. `emitted` and `refusal` already tell the two apart.
545
+ exemption: null,
546
+ // #1595's cap counts filings per CHECKOUT, and this path adjudicates a
547
+ // candidate inside a review round rather than a `gh issue create` from
548
+ // one. `null` is the reading: there is no run to attribute it to.
549
+ run: null,
541
550
  };
542
551
  }
543
552
 
@@ -61,10 +61,18 @@
61
61
  * the next run replaces wholesale, so a finding not re-raised simply
62
62
  * disappears and the check goes green.
63
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.
64
+ * So for as long as nothing re-emitted them, `reviewScopeForRound` delegated
65
+ * gate 2 to `reReviewScope` and no round was ever narrowed. **`carryForward`
66
+ * is what makes a diff-scoped round honest**: the unresolved earlier findings
67
+ * are re-emitted by the ADJUDICATOR rather than re-discovered by the
68
+ * reviewer, so they are in the payload whether or not the diff contains the
69
+ * lines they name.
70
+ *
71
+ * That is now a production path rather than a plan — the generated
72
+ * `ai-review-carry` step restates this module's walker in bash and reported
73
+ * `2 finding(s) ... unanswered at this commit` on run `40137812549` — so
74
+ * #1600 narrows from the floor below, gated on the carry having actually been
75
+ * READ with no blind spots. See `reviewScopeForRound`.
68
76
  */
69
77
 
70
78
  import {
@@ -74,7 +82,6 @@ import {
74
82
  REVIEW_SCOPE_FULL,
75
83
  SECURITY_REREVIEW_EXHAUSTED,
76
84
  reReviewDecision,
77
- reReviewScope,
78
85
  type ReviewScope,
79
86
  } from "./security-verdict.ts";
80
87
 
@@ -95,13 +102,158 @@ export const AI_REVIEW_ROUND_CAP = 3;
95
102
  /**
96
103
  * The round from which a re-review may be scoped to the diff.
97
104
  *
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.
105
+ * Anthropic's "after the first few passes". It is a FLOOR and not the
106
+ * decision — `reviewScopeForRound` has a second gate below it.
107
+ *
108
+ * **Three, re-derived against this repository rather than inherited from the
109
+ * cap it happens to equal (#1600).** Measured 2026-10-24 over the ai-review
110
+ * ledgers of the 90 most recent pull requests, all 90 parseable. Counted in
111
+ * DISTINCT ROUNDS and not in ledger entries — an entry is a run ATTEMPT and a
112
+ * re-run appends another at the same round number (#1592). 202 entries
113
+ * collapse to 161 distinct rounds here, 1.25x, which is the same direction and
114
+ * near the 1.32x that measurement reports.
115
+ *
116
+ * | round | distinct rounds | share |
117
+ * |---|---|---|
118
+ * | 1 | 90 | 55.9% |
119
+ * | 2 | 37 | 23.0% |
120
+ * | 3 | 19 | 11.8% |
121
+ * | 4 | 9 | 5.6% |
122
+ * | 5 | 6 | 3.7% |
123
+ *
124
+ * The internal control on that reading: round 1 is 90, which is exactly the
125
+ * number of pull requests, and every pull request that has a ledger has had a
126
+ * first round. A round-1 count below the PR count would have meant the walk
127
+ * was dropping entries.
128
+ *
129
+ * So the floor decides what share of rounds narrows: **>=2 is 44.1%, >=3 is
130
+ * 21.1%, >=4 is 9.3%.** Three is taken because it leaves the first two rounds
131
+ * of every pull request reading the whole branch. Round 2 is the round most
132
+ * likely to reach a part of the branch round 1 never got to — the reviewer is
133
+ * a sampled instrument, not an enumerated one, and two full draws is the
134
+ * cheapest protection against that. A floor of 4 narrows 9.3% of rounds and
135
+ * would be adoption on paper.
136
+ *
137
+ * **The cohort is right-censored**: an open pull request can still gain a
138
+ * round, so the tail shares are a lower bound. That moves the >=3 share UP,
139
+ * which is the direction that argues for this floor rather than against it.
140
+ *
141
+ * ## 21.1% is this FLOOR's reach. It is not CRC-N2's reach
142
+ *
143
+ * Every number above is gate 1 alone — the share of rounds at or past the
144
+ * floor. A reader reaching this table reads it as what narrowing does, and
145
+ * narrowing does far less, because the other gates then refuse most of what
146
+ * the floor admits. Both numbers belong here or the docblock overstates the
147
+ * change by an order of magnitude.
148
+ *
149
+ * Re-measured 2026-10-25 by walking **all 828 pull requests** over the
150
+ * GraphQL API and replaying the decision per round against the ledger **as
151
+ * the carry step would have read it at that round** — entries with
152
+ * `round < r`, never the final ledger, which charges a round 3 for an entry
153
+ * that arrived on round 4:
154
+ *
155
+ * | | rounds | share of all 333 |
156
+ * |---|---|---|
157
+ * | at or past the floor (gate 1 alone) | 115 | 34.5% |
158
+ * | **narrow under every gate as built** | **12** | **3.6%** |
159
+ * | would narrow with #1592 fixed | 20 | 6.0% |
160
+ *
161
+ * **3.6%, not 34.5%.** The subtraction is almost entirely gate 3: of the 115
162
+ * at-floor rounds it refuses 96, truncation refuses 46 and the round-gap
163
+ * refuses 15 (not exclusive). **8 of the refusals are #1592 and nothing
164
+ * else** — `unmeasured_rounds` counts dead ENTRIES, and a re-run appends an
165
+ * entry at the same round number, so a round whose first attempt wrote no
166
+ * payload and whose second wrote a full one is unmeasured for ever. #1569 is
167
+ * the clean instance: 5 rounds, every one readable on attempt 2, three dead
168
+ * attempt-1 entries, refused on every round it will ever have. That unit was
169
+ * a warning's wording until this constant started reading it.
170
+ *
171
+ * **This corpus is larger than the one the table above was taken on** (147
172
+ * pull requests carrying a parseable ledger, 333 distinct rounds, against 90
173
+ * and 161). The earlier walk enumerated fewer pull requests; this one took
174
+ * every one of the 828 and carries two controls — **0** ledger comments that
175
+ * failed to parse, and **0** pull requests with more than 100 comments, so
176
+ * no ledger was missed behind a comment page. The floor's shares move with
177
+ * it (>=3 is 34.5% here) and the floor does not: rounds 1 and 2 are still
178
+ * 65.5% and still read the whole branch.
179
+ *
180
+ * It equals `AI_REVIEW_ROUND_CAP` and is deliberately a SEPARATE constant:
181
+ * they answer different questions — one bounds how many rounds an author
182
+ * gets, the other says when a round may read less — and binding them would
183
+ * make lowering the cap silently narrow earlier.
102
184
  */
103
185
  export const AI_REVIEW_DIFF_SCOPE_FROM_ROUND = 3;
104
186
 
187
+ /**
188
+ * The carry reading that makes a narrowed round honest.
189
+ *
190
+ * Declared again here and in `lib/scaffold/ai-review-step.ts` as
191
+ * `AI_REVIEW_CARRY_READ`, and bound by an agreement assertion rather than an
192
+ * import, for the reason every other constant in this file is: that module is
193
+ * copied into a `mkdtemp` by the mutation batteries, where a relative
194
+ * specifier does not resolve and the mutant fails to LOAD — which reads as a
195
+ * behavioural difference on every row (`.claude/rules/self-referential-tests.md`,
196
+ * Tier 1).
197
+ */
198
+ export const AI_REVIEW_CARRY_READ_STATE = "AI_REVIEW_CARRY_READ";
199
+
200
+ /**
201
+ * The carry step's reading, reduced to the two fields the scope depends on.
202
+ *
203
+ * Both `unknown`, because they arrive as text off a file written by a bash
204
+ * step on a runner. `unmeasuredRounds` is the carry's own word for "rounds
205
+ * this pull request recorded whose findings list could not be read", and it
206
+ * is `"unknown"` when even that count could not be established.
207
+ */
208
+ export interface CarryScopeReading {
209
+ state: unknown;
210
+ unmeasuredRounds: unknown;
211
+ /**
212
+ * How many paths this pull request changed, as the changed-files step
213
+ * recorded them. A narrowed round is an instruction to read THIS list, so
214
+ * a list that could not be read or that is empty is a `diff` scope naming
215
+ * nothing — the one failure in this subsystem strictly worse than reading
216
+ * too much, because a compliant reviewer then reads nothing at all.
217
+ */
218
+ changedFileCount: unknown;
219
+ /**
220
+ * How many earlier rounds the ledger dropped, from its own `truncated`
221
+ * key (#1405). A COUNT, not a flag — measured across the corpus on
222
+ * 2026-10-24, every #1405-era ledger reads the number `0` and no ledger
223
+ * has ever read a boolean.
224
+ *
225
+ * It is a SEPARATE reading from `unmeasuredRounds` and the distinction is
226
+ * the whole of why this field exists: `unmeasuredRounds` counts recorded
227
+ * rounds whose findings list could not be PARSED, so it is a statement
228
+ * about what is in front of the reader. A truncated ledger's earlier
229
+ * rounds are ABSENT — nothing to fail to parse — so every entry still
230
+ * present reads fine, `unmeasuredRounds` is `0`, and a completeness gate
231
+ * built on it alone narrows the scope over a hole it cannot see. That is
232
+ * #1601's shape one level up, and it was found by review rather than by
233
+ * this file's own tests.
234
+ */
235
+ truncatedRounds: unknown;
236
+ /**
237
+ * The ledger's recorded rounds STRICTLY BELOW this one: how many distinct
238
+ * round numbers, and the highest of them.
239
+ *
240
+ * Two numbers because one cannot say what this gate needs: rounds 1, 2
241
+ * and 5 before a snapshot at 6 has a highest of 5 and a count of 3, and
242
+ * the hole at 3 and 4 is exactly the difference. Nothing is truncated and
243
+ * nothing is unparseable, so neither reading above can see it.
244
+ *
245
+ * **Strictly below**, because a re-run appends another entry at the round
246
+ * it is re-running (#1592). Counting the current round's own entry would
247
+ * make the gate refuse every re-run for a reason that is not a hole.
248
+ *
249
+ * Measured: of 197 rounds at or past the floor across 144 ledgers, 14
250
+ * carry a genuine gap — #1420 has no round 2, #1391 no round 1 — and 100
251
+ * are clean. So this refuses something real and is not adoption on paper.
252
+ */
253
+ priorRounds: unknown;
254
+ highestPriorRound: unknown;
255
+ }
256
+
105
257
  /**
106
258
  * The round budget could not be read, so this job does not know which round
107
259
  * it is on.
@@ -220,19 +372,130 @@ export function roundOutcome(raw: unknown, cap: unknown = AI_REVIEW_ROUND_CAP):
220
372
  /**
221
373
  * The scope the reviewer should read on this round.
222
374
  *
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.
375
+ * FOUR gates, and all four must open. Anything else is `REVIEW_SCOPE_FULL`.
376
+ *
377
+ * 1. the round number is readable, and is at or past the floor above;
378
+ * 2. the carry reading is `READ` — the earlier rounds were actually read;
379
+ * 3. no recorded round of this pull request had an unreadable findings list;
380
+ * 4. the changed-file list was read and names at least one path.
381
+ *
382
+ * FAILS CLOSED TOWARD READING MORE, in every half. An unreadable round, an
383
+ * unreadable carry, a carry that could not count its own blind spots: all
384
+ * full reviews. A narrowed round is the only outcome that can lose a finding,
385
+ * so it is the one that has to be earned.
386
+ *
387
+ * ## Why the held-verdict gate is gone, and what replaced it (#1600)
388
+ *
389
+ * This function used to delegate gate 2 to `reReviewScope`, which refuses to
390
+ * diff-scope anything but a held PASS. That rule is #244's and it is right in
391
+ * the context it was written for — a ship run, where a held FAIL names code
392
+ * the diff does not contain, so a diff-scoped re-review says nothing about
393
+ * it. `reReviewScope` still governs that path through `reReviewBaseFor` and
394
+ * is unchanged.
395
+ *
396
+ * It is the wrong gate HERE, and not because the risk went away. There is no
397
+ * held verdict on a CI round, so a conjunction including it could never open
398
+ * and this function would be a decider that always answers FULL — a
399
+ * configuration that reads like a decision, which is the shape this
400
+ * repository keeps paying for.
401
+ *
402
+ * What makes a narrowed round honest is the thing #244 said was missing:
403
+ * `carryForward` re-emits every earlier finding whose cited line still reads
404
+ * as it did, **whether or not that line is in the diff**, and the prompt
405
+ * requires the reviewer to check each one against the code. So the finding a
406
+ * diff-scoped round would have lost is in the payload by construction. That
407
+ * is the spec's own declared retirement condition for this deviation —
408
+ * *"an adjudicator re-emits unresolved findings"* — and it fired in
409
+ * production on run `40137812549`, which carried 2.
410
+ *
411
+ * Gate 3 is the part that keeps gate 2 from being a formality. `READ` with
412
+ * `unmeasuredRounds > 0` means the carried set is a LOWER BOUND: some
413
+ * recorded round's findings could not be read, so a live earlier finding may
414
+ * be absent from the list. Narrowing on top of that is exactly the silent
415
+ * loss the deviation existed to prevent, with the carry present and saying so
416
+ * in a warning nobody is required to read. `"unknown"` — the carry could not
417
+ * even count them — is refused with the rest.
418
+ *
419
+ * Gate 4 is the asymmetric one. Gates 1-3 fail toward a reviewer reading MORE
420
+ * than it needed to, which costs turns. Gate 4 is the only one whose absence
421
+ * fails the other way: `diff` is an instruction to read the changed files,
422
+ * and a changed-file list that could not be produced — the step warns
423
+ * `CHANGED_FILES_UNREADABLE` and writes nothing — leaves a compliant reviewer
424
+ * with nothing to read at all. The prompt also tells the reviewer to fall
425
+ * back to `full` in that case, and that is a second line of defence rather
426
+ * than this one: a prompt is a request, and whether the reviewer honours one
427
+ * is the thing this whole criterion cannot yet measure.
428
+ *
429
+ * ## What this function does NOT establish
430
+ *
431
+ * That the reviewer HONOURS the scope. This returns a word; whether a
432
+ * narrowed round's reads were confined is a behaviour, measurable only from a
433
+ * real run, and #1533 measured the reviewer reading whole files under a
434
+ * prompt that told it to. Treat a `diff` here as a request, and see
435
+ * `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` for why the observation is recorded
436
+ * UNMEASURED rather than inferred from this value.
231
437
  */
232
- export function reviewScopeForRound(rawRound: unknown, heldVerdict: unknown): ReviewScope {
438
+ export function reviewScopeForRound(rawRound: unknown, carry: unknown): ReviewScope {
233
439
  const round = readRoundNumber(rawRound);
234
440
  if (round === null || round < AI_REVIEW_DIFF_SCOPE_FROM_ROUND) return REVIEW_SCOPE_FULL;
235
- return reReviewScope(heldVerdict);
441
+ if (typeof carry !== "object" || carry === null || Array.isArray(carry)) return REVIEW_SCOPE_FULL;
442
+ const c = carry as CarryScopeReading;
443
+ if (c.state !== AI_REVIEW_CARRY_READ_STATE) return REVIEW_SCOPE_FULL;
444
+ // Not `!= 0`, and not `Number(...)`: `""`, `" 0 "` and `"0x0"` all read as
445
+ // zero through a coercion, and a blind-spot count nobody wrote is not a
446
+ // count of zero. The carry writes a decimal integer or the word `unknown`.
447
+ if (!isZeroCount(c.unmeasuredRounds)) return REVIEW_SCOPE_FULL;
448
+ // A DIFFERENT question from the one above, and the reason is the whole of
449
+ // this gate: `unmeasuredRounds` asks whether what is present parses.
450
+ // `truncated` asks whether anything is missing. A ledger that dropped its
451
+ // first four rounds parses perfectly, so the gate above reads `0` and
452
+ // narrows the scope over history it cannot see.
453
+ if (!isZeroCount(c.truncatedRounds)) return REVIEW_SCOPE_FULL;
454
+ // And a hole needs neither truncation nor an unparseable round to exist:
455
+ // rounds 1, 2 and 5 recorded before a snapshot at 6 is a gap that both
456
+ // readings above call clean. The prior rounds must be exactly 1..round-1.
457
+ const highest = readCount(c.highestPriorRound);
458
+ const distinct = readCount(c.priorRounds);
459
+ if (highest === null || distinct === null) return REVIEW_SCOPE_FULL;
460
+ if (highest !== round - 1 || distinct !== highest) return REVIEW_SCOPE_FULL;
461
+ if (!isPositiveCount(c.changedFileCount)) return REVIEW_SCOPE_FULL;
462
+ return REVIEW_SCOPE_DIFF;
463
+ }
464
+
465
+ /**
466
+ * A non-negative decimal integer, as a number or as the string a shell
467
+ * emits — or `null` for anything that is not one.
468
+ *
469
+ * `null` rather than a sentinel number, because every caller above treats an
470
+ * unreadable count as a refusal and a sentinel would have to be a value the
471
+ * comparison could accidentally satisfy.
472
+ */
473
+ function readCount(v: unknown): number | null {
474
+ if (typeof v === "number") return Number.isInteger(v) && v >= 0 ? v : null;
475
+ if (typeof v !== "string" || !/^[0-9]+$/.test(v)) return null;
476
+ const n = Number.parseInt(v, 10);
477
+ return Number.isSafeInteger(n) ? n : null;
478
+ }
479
+
480
+ /**
481
+ * Exactly zero, written as a number or as the decimal string a shell emits.
482
+ *
483
+ * Not `== 0` and not `Number(v) === 0`: `""`, `null`, `false`, `[]` and
484
+ * `" 0 "` all read as zero through a coercion, and a count nobody wrote is
485
+ * not a count of none. `"unknown"` — the carry's own word for a blind-spot
486
+ * count it could not establish — fails here, which is the point.
487
+ */
488
+ function isZeroCount(v: unknown): boolean {
489
+ if (typeof v === "number") return Number.isInteger(v) && v === 0;
490
+ return v === "0";
491
+ }
492
+
493
+ /** A decimal integer of at least one, as a number or as a shell's string. */
494
+ function isPositiveCount(v: unknown): boolean {
495
+ if (typeof v === "number") return Number.isInteger(v) && v >= 1;
496
+ if (typeof v !== "string" || !/^[0-9]+$/.test(v)) return false;
497
+ const n = Number.parseInt(v, 10);
498
+ return Number.isSafeInteger(n) && n >= 1;
236
499
  }
237
500
 
238
501
  /** A finding as the payload contract spells it (`AI_REVIEW_FINDING_FIELDS`). */
@@ -0,0 +1,188 @@
1
+ /**
2
+ * lib/ai-review-threads.ts — posting a review's findings onto the diff.
3
+ *
4
+ * #1612. Measured 2026-10-25 across every merged pull request on the
5
+ * consumer that runs the generated `ai-review` job: zero review threads,
6
+ * ever. The job's only output has been a GitHub Actions annotation, which
7
+ * lives as long as the run log. A repository that switches
8
+ * `required_conversation_resolution` on against that gets a gate whose
9
+ * population is always empty — satisfied by construction.
10
+ *
11
+ * This module owns the half `reviewThreadRequests` does not: what happened
12
+ * when the comments were sent. That matters because **zero comments posted
13
+ * is the same observation in four different situations** — the review found
14
+ * nothing, the review could not run, the token could not write, or this code
15
+ * is broken. One channel, four mechanisms, which is the sixth shape in
16
+ * `.claude/rules/checks-must-be-able-to-fail.md`. Collapsing them into a
17
+ * boolean is how a producer stays dead without anybody noticing, which is
18
+ * precisely the history being fixed here.
19
+ *
20
+ * So the outcome is NAMED, and exactly one of the names is a refusal.
21
+ *
22
+ * The HTTP call is injected rather than performed. Every decision below is
23
+ * therefore reachable from a test over a recorded response, including the
24
+ * two that only a live fork or a line outside a hunk would otherwise produce.
25
+ */
26
+ import { reviewThreadRequests, type AiReviewFindingsReading } from "./scaffold/ai-review-findings";
27
+ import type { AiReviewThreadRequest } from "./scaffold/ai-review-findings";
28
+
29
+ /**
30
+ * The single non-zero exit. Declared once, so a mutant can set it to `0` and
31
+ * a case can observe the refusal disappearing — `.claude/rules/checks-must-be-able-to-fail.md`,
32
+ * *For a script whose job is to exit non-zero*. A `process.exit(1)` or a
33
+ * second literal anywhere in this module would bypass that mutation and the
34
+ * case would go green over a refusal it never witnessed.
35
+ */
36
+ export const AI_REVIEW_THREADS_REFUSAL = 1;
37
+
38
+ /**
39
+ * What a posting round was, in the words that distinguish the four ways it
40
+ * can produce no comments.
41
+ *
42
+ * | Outcome | Comments | Refusal | What it means |
43
+ * |---|---|---|---|
44
+ * | `POSTED` | ≥ 1 | no | the producer works |
45
+ * | `NOTHING_TO_POST` | 0 | no | the review located nothing to anchor |
46
+ * | `UNMEASURED` | 0 | no | there was no reading to post FROM |
47
+ * | `DEGRADED_NO_WRITE` | 0 | no | the token cannot write; see below |
48
+ * | `FAILED` | any | **yes** | the producer is broken |
49
+ *
50
+ * `UNMEASURED` is not a quieter `NOTHING_TO_POST`. A review that did not run
51
+ * has not found zero findings, and a tree that cannot tell those apart is the
52
+ * *Silent Default Substitution* anti-pattern in `.claude/rules/config-access.md`.
53
+ */
54
+ export type AiReviewThreadOutcome =
55
+ | "POSTED"
56
+ | "NOTHING_TO_POST"
57
+ | "UNMEASURED"
58
+ | "DEGRADED_NO_WRITE"
59
+ | "FAILED";
60
+
61
+ /** What the API said. `status` is `null` for a failure that never got one. */
62
+ export type AiReviewThreadResponse =
63
+ | { ok: true }
64
+ | { ok: false; status: number | null; message: string };
65
+
66
+ /** Sends one comment. The only thing in this module that touches a network. */
67
+ export type AiReviewThreadPoster = (
68
+ request: AiReviewThreadRequest,
69
+ ) => Promise<AiReviewThreadResponse>;
70
+
71
+ export interface AiReviewThreadsResult {
72
+ outcome: AiReviewThreadOutcome;
73
+ /** Comments this round meant to create. */
74
+ attempted: number;
75
+ /** Comments the API accepted. */
76
+ posted: number;
77
+ /** Of those, how many only succeeded after dropping to file level. */
78
+ demoted: number;
79
+ /** One sentence per thing worth reading, in the order it happened. */
80
+ detail: string[];
81
+ }
82
+
83
+ /** HTTP 422 — the documented answer to a `line` outside a diff hunk. */
84
+ const UNPROCESSABLE = 422;
85
+ /** HTTP 403 — the documented answer to a token without `pull-requests: write`. */
86
+ const FORBIDDEN = 403;
87
+
88
+ /**
89
+ * Post every comment a reading calls for, and say which of the four
90
+ * no-comment states this was if none appeared.
91
+ *
92
+ * Three behaviours are worth stating because each has a cheaper wrong answer:
93
+ *
94
+ * **An UNMEASURED reading posts nothing and attempts nothing.** Not because
95
+ * posting would fail, but because there is no reading to post from, and a
96
+ * round that posted a guess would put the reviewer's absence on the diff as
97
+ * though it were a finding.
98
+ *
99
+ * **A 422 demotes before it fails.** `line` is documented as "Required
100
+ * unless using subject_type:file", and a line outside a hunk is refused with
101
+ * 422. Being in the changed-file set locates a finding to a FILE and never
102
+ * to a hunk, so this response is EXPECTED on a correct request and the
103
+ * retry is part of the contract rather than error recovery. Only a 422 that
104
+ * survives the demotion is a defect.
105
+ *
106
+ * **A 403 degrades and does not refuse — but only when it is the whole
107
+ * story.** For a `pull_request` from a forked repository GitHub downgrades
108
+ * write permissions to read regardless of what the workflow declares, unless
109
+ * an admin enabled *Send write tokens to workflows from pull requests*. So on
110
+ * a fork this producer cannot run, the adjudicator's annotation is still
111
+ * produced, and failing here would red every fork pull request for something
112
+ * the contributor cannot fix. What that must NOT do is become a blanket
113
+ * excuse: a round that saw a 403 AND some other failure is `FAILED`, because
114
+ * a broken producer hiding behind a fork is the fail-open this whole module
115
+ * exists to prevent.
116
+ */
117
+ export async function postReviewThreads(
118
+ reading: AiReviewFindingsReading,
119
+ post: AiReviewThreadPoster,
120
+ ): Promise<AiReviewThreadsResult> {
121
+ const detail: string[] = [];
122
+
123
+ if (reading.outcome === "UNMEASURED") {
124
+ detail.push(
125
+ "the review produced no usable reading, so there was nothing to post — this is not a review that found nothing",
126
+ );
127
+ return { outcome: "UNMEASURED", attempted: 0, posted: 0, demoted: 0, detail };
128
+ }
129
+
130
+ const requests = reviewThreadRequests(reading);
131
+ if (requests.length === 0) {
132
+ detail.push("the reading located no finding that could be anchored to a path in this diff");
133
+ return { outcome: "NOTHING_TO_POST", attempted: 0, posted: 0, demoted: 0, detail };
134
+ }
135
+
136
+ let posted = 0;
137
+ let demoted = 0;
138
+ let forbidden = 0;
139
+ let failed = 0;
140
+
141
+ for (const request of requests) {
142
+ const where = request.line === null ? request.path : `${request.path}:${request.line}`;
143
+ let answer = await post(request);
144
+
145
+ // The demotion, and only from a line. A file-level request that is
146
+ // refused has nothing left to drop.
147
+ if (!answer.ok && answer.status === UNPROCESSABLE && request.line !== null) {
148
+ detail.push(`${where}: line refused (422), retrying as a file-level comment`);
149
+ answer = await post({ ...request, line: null });
150
+ if (answer.ok) demoted += 1;
151
+ }
152
+
153
+ if (answer.ok) {
154
+ posted += 1;
155
+ continue;
156
+ }
157
+ if (answer.status === FORBIDDEN) {
158
+ forbidden += 1;
159
+ detail.push(
160
+ `${where}: 403 — this token cannot write pull-request comments. A pull_request run from a ` +
161
+ `fork is handed a read-only token whatever the workflow declares.`,
162
+ );
163
+ continue;
164
+ }
165
+ failed += 1;
166
+ detail.push(`${where}: ${answer.status ?? "no status"} — ${answer.message}`);
167
+ }
168
+
169
+ // Order matters. A real failure outranks the fork excuse, and both outrank
170
+ // a partial success — a round that posted three of four comments has lost
171
+ // a finding and must say so.
172
+ if (failed > 0) {
173
+ return { outcome: "FAILED", attempted: requests.length, posted, demoted, detail };
174
+ }
175
+ if (forbidden > 0) {
176
+ return { outcome: "DEGRADED_NO_WRITE", attempted: requests.length, posted, demoted, detail };
177
+ }
178
+ detail.push(
179
+ `posted ${posted} review ${posted === 1 ? "comment" : "comments"}` +
180
+ (demoted === 0 ? "" : `, ${demoted} at file level after a line was refused`),
181
+ );
182
+ return { outcome: "POSTED", attempted: requests.length, posted, demoted, detail };
183
+ }
184
+
185
+ /** The exit code a round's outcome earns. Only `FAILED` refuses. */
186
+ export function aiReviewThreadsExitCode(result: AiReviewThreadsResult): number {
187
+ return result.outcome === "FAILED" ? AI_REVIEW_THREADS_REFUSAL : 0;
188
+ }
@@ -166,6 +166,27 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
166
166
  // project tree at all — it talks to the GitHub API about a repository it
167
167
  // is told the name of, so an appended `--project-root <cwd>` would be
168
168
  // refused by `parseArgs` as an unknown argument.
169
+ // Registered for the same reachability reason as the two around it
170
+ // (#1612): the generated `ai-review` job runs in a consumer's repository,
171
+ // which holds no copy of rungate's sources at any path a workflow could
172
+ // name. This registry is that path.
173
+ //
174
+ // SEPARATE from `ai-review-findings` on purpose. That command exits
175
+ // non-zero on a blocking finding — so a poster sharing its entry point
176
+ // could never run on the review that actually found something, which is
177
+ // the only review worth posting.
178
+ //
179
+ // No `projectRootFlag`: the payload lives outside the checkout in
180
+ // `RUNNER_TEMP`, everything else is a flag, and an appended
181
+ // `--project-root <cwd>` would arrive as a second positional, which
182
+ // `parse` refuses by name rather than silently reading as the payload.
183
+ "ai-review-threads": {
184
+ script: "scripts/ai-review-threads.ts",
185
+ summary: "Post an AI review's findings onto the pull request's diff as review threads",
186
+ usage:
187
+ "rungate ai-review-threads <path-to-findings.json> --repo <owner/name> " +
188
+ "--pr <n> --commit <sha> [--changed-files <path>]",
189
+ },
169
190
  "record-ai-review-unmeasured": {
170
191
  script: "scripts/record-ai-review-unmeasured.ts",
171
192
  summary: "Record WHICH kind of unmeasured each unmeasured AI-review round was",
@@ -797,6 +797,66 @@ export type ArbiterRefusal =
797
797
  * against a diff rather than filed by hand, and have no title to carry one.
798
798
  */
799
799
  | "NO_CLAIM"
800
+ /**
801
+ * Nobody declared a reason this finding cannot be a comment (#1595).
802
+ *
803
+ * The refusal this file's own header has asked for since it was written —
804
+ * *"`Disposition` defaults to `COMMENT`, `ISSUE` requires an explicit
805
+ * declared reason from the caller (`Finding.outOfScope`)"*. `arbitrate`
806
+ * enforces it at stage 6 and the `gh issue create` chokepoint did not,
807
+ * because its header lists the three stages that genuinely cannot run at a
808
+ * PreToolUse hook and `outOfScope` was quietly carried along with them. It
809
+ * is not one of them: a declaration is readable from the command line the
810
+ * hook already has.
811
+ *
812
+ * A chokepoint refusal only, for the same reason `NO_CLAIM` is: on the
813
+ * `arbitrate` path the same question is the `COMMENT` disposition, which
814
+ * is an outcome rather than a refusal.
815
+ */
816
+ | "COMMENT_INSTEAD"
817
+ /**
818
+ * An earlier clause of the SAME command already files this finding's class
819
+ * (#1595, CRC-N3's hook-side half).
820
+ *
821
+ * *"Flag the class of bug, so the author fixes every instance, not one
822
+ * line"* — so two findings that share a class are one item saying *every
823
+ * instance*, never two issues. Distinct from `DUPLICATE`, which is about
824
+ * the TRACKER: a duplicate names an issue a reader can go and read, and
825
+ * this names a clause in a command that has not run yet.
826
+ */
827
+ | "SAME_CLASS_IN_RUN"
828
+ /**
829
+ * The run has already filed its allowance of issues (#1595, scope item 4).
830
+ *
831
+ * **The only refusal here that requires no reasoning to apply, which is
832
+ * why it is the one that holds.** The declared-reason check it stands
833
+ * beside is a per-finding judgement, and a per-finding judgement drifts:
834
+ * applied to the three issues filed on 2026-10-24 all three cleared it on
835
+ * individually sound arguments, which is not a result a bar produces. A
836
+ * count has no clause to argue into.
837
+ *
838
+ * So it takes no argument and no label. `arbiter-override` waives a claim
839
+ * about a FINDING; this is an accounting of a RUN, and there is nothing
840
+ * about the finding for a waiver to address.
841
+ */
842
+ | "OVER_CAP"
843
+ /**
844
+ * The ledger is present and unreadable, so the allowance cannot be counted
845
+ * (#1595, scope item 4).
846
+ *
847
+ * **Distinct from `UNMEASURED`, and fails in the opposite direction from
848
+ * every other unreadable input in this gate.** Elsewhere an unreadable
849
+ * input allows loudly, because a measurement apparatus must not block the
850
+ * thing it measures. The ledger is not the apparatus here — it is the
851
+ * cap's STATE, so "unreadable" means the cap does not exist, and allowing
852
+ * on it is not a loud note but a silent removal of the gate.
853
+ *
854
+ * `readLedgerRows` already separates the two readings this turns on:
855
+ * `[]` for a genuinely absent file, `null` for present-and-unreadable. An
856
+ * empty population is a legitimate answer and allows; UNMEASURED is not an
857
+ * answer at all and refuses, naming the path so an operator can act.
858
+ */
859
+ | "UNMEASURED_CAP"
800
860
  /** Something could not be evaluated. Fails; never skips. */
801
861
  | "UNMEASURED";
802
862
 
@@ -1124,6 +1184,14 @@ export const FILING_BUDGET_FINDINGS = 6;
1124
1184
  * unmeasured, the sibling was measured and refused — and it is not the
1125
1185
  * sibling's own `ArbiterRefusal`, because this clause was never refused and
1126
1186
  * is the one an agent should re-run.
1187
+ * - `INTENT_PENDING` — the row is an INTENT to file, appended by the cap
1188
+ * before it decides, and at the moment it is written nothing has reached
1189
+ * the tracker and nothing has refused it. It is not `COMMAND_BLOCKED`,
1190
+ * which is a decision, and not a refusal, which is a judgement: it is the
1191
+ * state a reservation is in for the microseconds between the append and the
1192
+ * re-read that resolves it. The outcome lands on a SECOND row sharing this
1193
+ * one's key without the `#intent` suffix. See `intentsInRun` in
1194
+ * `lib/issue-filing-gate.ts` for why the reservation is a separate row.
1127
1195
  * - `UNACCOUNTED` — the promoter returned this candidate in neither
1128
1196
  * `promoted` nor `withheld`. It partitions its input, so this cannot
1129
1197
  * happen; it is named instead of defaulted so that if the partition ever
@@ -1134,6 +1202,7 @@ export type WithheldBy =
1134
1202
  | WithheldReason
1135
1203
  | "BATCH_UNMEASURED"
1136
1204
  | "COMMAND_BLOCKED"
1205
+ | "INTENT_PENDING"
1137
1206
  | "UNACCOUNTED";
1138
1207
 
1139
1208
  /**