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 +1 -1
- package/lib/ai-review-jury.ts +9 -0
- package/lib/ai-review-rounds.ts +282 -19
- package/lib/ai-review-threads.ts +188 -0
- package/lib/cli-commands.ts +21 -0
- package/lib/finding-arbiter.ts +69 -0
- package/lib/github.ts +25 -0
- package/lib/issue-filing-gate.ts +1611 -19
- package/lib/launch-base.ts +19 -4
- package/lib/scaffold/ai-review-findings.ts +106 -0
- package/lib/scaffold/ai-review-step.ts +803 -153
- package/lib/worktree-repo.ts +74 -4
- package/package.json +2 -1
- package/scripts/ai-review-threads.ts +172 -0
- package/scripts/arbitrate-finding.ts +10 -0
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
aa2a5af1b31b712c5702035b4740c14f591f59fdcbed342e791976869850bfd2
|
package/lib/ai-review-jury.ts
CHANGED
|
@@ -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
|
|
package/lib/ai-review-rounds.ts
CHANGED
|
@@ -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
|
|
65
|
-
*
|
|
66
|
-
* diff-scoped round honest
|
|
67
|
-
* the ADJUDICATOR rather than re-discovered by the
|
|
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".
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
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
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
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,
|
|
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
|
-
|
|
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
|
+
}
|
package/lib/cli-commands.ts
CHANGED
|
@@ -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",
|
package/lib/finding-arbiter.ts
CHANGED
|
@@ -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
|
/**
|