rungate 0.8.8 → 0.8.12

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 (45) hide show
  1. package/gates/.gate-salt +1 -1
  2. package/hooks/StaleTTLCleanup.hook.ts +13 -5
  3. package/hooks/VerifyPhaseLock.hook.ts +8 -0
  4. package/hooks/lib/findWorkflow.ts +19 -3
  5. package/lib/active-workflow.ts +57 -0
  6. package/lib/ai-review-rounds.ts +102 -9
  7. package/lib/ai-review-threads.ts +71 -3
  8. package/lib/board-mirror.ts +438 -0
  9. package/lib/cli-commands.ts +133 -0
  10. package/lib/config-readers.ts +64 -0
  11. package/lib/crc-reading.ts +655 -0
  12. package/lib/criterion-issue-census.ts +325 -0
  13. package/lib/filing-plan.ts +381 -0
  14. package/lib/generators/agents-md.ts +15 -11
  15. package/lib/git-isolation.ts +32 -0
  16. package/lib/github.ts +66 -0
  17. package/lib/issue-decomposition.ts +523 -0
  18. package/lib/issue-filing-gate.ts +304 -19
  19. package/lib/issue-repair.ts +225 -0
  20. package/lib/live-issues.ts +442 -0
  21. package/lib/project-state-shape.ts +30 -0
  22. package/lib/sc-ids.ts +31 -1
  23. package/lib/scaffold/ai-review-findings.ts +142 -2
  24. package/lib/scaffold/ai-review-step.ts +277 -52
  25. package/lib/scaffold/owned-files.ts +60 -2
  26. package/lib/scaffold/steps.ts +130 -4
  27. package/lib/spec-deps.ts +257 -0
  28. package/lib/spec-evidence.ts +479 -0
  29. package/lib/spec-placement.ts +430 -0
  30. package/lib/spec-template.ts +206 -0
  31. package/lib/stage-ladder.ts +628 -0
  32. package/lib/worktree-cleanup.ts +438 -3
  33. package/package.json +12 -4
  34. package/scripts/ai-review-threads.ts +10 -1
  35. package/scripts/audit-spec-evidence.ts +246 -0
  36. package/scripts/audit-specs.ts +27 -0
  37. package/scripts/board-conformance.ts +828 -0
  38. package/scripts/board-mirror.ts +344 -0
  39. package/scripts/board-snapshot.ts +468 -0
  40. package/scripts/create-spec.ts +8 -34
  41. package/scripts/criterion-inventory.ts +649 -0
  42. package/scripts/extract-constraints.ts +108 -9
  43. package/scripts/plan-deps.ts +378 -0
  44. package/scripts/plan-issues.ts +721 -0
  45. package/scripts/plan-spec.ts +371 -0
@@ -0,0 +1,655 @@
1
+ /**
2
+ * CRC-M11's convergence reading, as a program rather than a shell recipe.
3
+ *
4
+ * Covers CRC-M11 (specs/CODE-REVIEW-CONVERGENCE-SPEC.md). The spec's
5
+ * measurement section was four hand-run commands and a hand-typed table, and
6
+ * the reviewer named that as the structural cause three rounds running on
7
+ * #1632. This module is the reading those commands were approximating; the
8
+ * table in the spec is rendered from a stored row rather than retyped.
9
+ *
10
+ * ## What the jq recipe could not do, and why that is the reason this exists
11
+ *
12
+ * **Per-pull-request refusal.** `jq` walks a list with one filter: a ledger
13
+ * whose JSON is truncated, or whose object has no `rounds` key, aborts the
14
+ * whole pipeline and **the entire range is lost**, not the one pull request.
15
+ * That is the same *Silent Default Substitution* shape the rest of this
16
+ * measurement is careful about, arriving as a stack trace instead of a
17
+ * number. Here a bad ledger is one `UNMEASURED LEDGER_UNREADABLE` line and
18
+ * the other forty-five still score.
19
+ *
20
+ * **A fence rule that survives its own payload.** The recipe cut the ledger
21
+ * with `split("```json")[1] | split("```")[0]`. On 2026-10-27 that cut a
22
+ * 27,252-character ledger at 18,021 characters, and the text at the cut was a
23
+ * reviewer quoting the recipe itself into a finding. **The recipe cut itself
24
+ * in half on any pull request whose review quoted it.** `ledgerRawRounds` and
25
+ * `readLedger` use `indexOf`, which does not.
26
+ *
27
+ * ## Two columns, and they answer different questions
28
+ *
29
+ * ALL-ROUNDS counts every round the ledger recorded, whether or not a review
30
+ * came out of it. MEASURED-ONLY counts only rounds whose `findings` is an
31
+ * array. The gap between them is the share of rounds in which no review
32
+ * happened, which on the readings so far is the larger half of the problem.
33
+ *
34
+ * **`findings != null` is the predicate, never `unmeasured == null`.** A
35
+ * ledger round is written twice: `lib/scaffold/ai-review-step.ts` emits it
36
+ * with no `unmeasured` key at all, and `lib/ai-review-unmeasured.ts` adds one
37
+ * in a second pass. So `unmeasured == null` asks whether the second pass ran,
38
+ * and a round the recorder never reached would score as measured.
39
+ *
40
+ * ## Both columns use the same denominators, and that is a change
41
+ *
42
+ * `lib/rounds-to-pass.ts` puts the mean and the one-round rate over the pull
43
+ * requests that PASSED, and the five-or-more tail over ALL measured ones,
44
+ * because *"a tail measured on survivors only has had its tail cut off"*. The
45
+ * hand-run measured-only column put all three over merged pull requests. This
46
+ * module applies the `rounds-to-pass` convention to both columns, so the
47
+ * measured-only tail now carries still-open pull requests that have at least
48
+ * one measured round. That moves the published 2026-10-27 figure and the
49
+ * numerators are printed so a reader can see which way.
50
+ */
51
+
52
+ import {
53
+ AI_REVIEW_LEDGER_READ,
54
+ AI_REVIEW_TRUNCATION_STATED,
55
+ ledgerRawRounds,
56
+ readLedger,
57
+ type LedgerTruncation,
58
+ } from "./ai-review-rounds";
59
+ import {
60
+ AI_REVIEW_UNMEASURED_NOT_RECORDED,
61
+ readRecordedUnmeasuredState,
62
+ } from "./ai-review-unmeasured";
63
+ import { LONG_REVIEW_ROUNDS, roundsTaken } from "./rounds-to-pass";
64
+
65
+ /**
66
+ * One pull request as the fetch produced it.
67
+ *
68
+ * `truncated` is the comment page's own statement that it did not carry every
69
+ * comment — it is a property of the FETCH and nothing downstream can
70
+ * reconstruct it, which is why it rides along rather than being inferred.
71
+ */
72
+ export interface CrcEntry {
73
+ readonly number: number;
74
+ /** Merged. Named `passed` because `rounds-to-pass` is deliberately agnostic. */
75
+ readonly passed: boolean;
76
+ readonly truncated: boolean;
77
+ readonly body: string | null;
78
+ }
79
+
80
+ /** A fetched page that cannot answer whether a ledger exists. */
81
+ export const CRC_PREMISE_UNRESOLVABLE_ABSENCE = "UNRESOLVABLE_ABSENCE";
82
+
83
+ /** The page did not reach both ends of the range that was asked for. */
84
+ export const CRC_PREMISE_RANGE_NOT_COVERED = "RANGE_NOT_COVERED";
85
+
86
+ /** An entry is outside `[lo, hi]`, so the cohort is not the one named. */
87
+ export const CRC_PREMISE_OUT_OF_RANGE = "ENTRY_OUT_OF_RANGE";
88
+
89
+ /** The same pull request appears twice, which doubles its weight. */
90
+ export const CRC_PREMISE_DUPLICATE = "DUPLICATE_ENTRY";
91
+
92
+ export interface PremiseViolation {
93
+ readonly kind:
94
+ | typeof CRC_PREMISE_UNRESOLVABLE_ABSENCE
95
+ | typeof CRC_PREMISE_RANGE_NOT_COVERED
96
+ | typeof CRC_PREMISE_OUT_OF_RANGE
97
+ | typeof CRC_PREMISE_DUPLICATE;
98
+ readonly detail: string;
99
+ }
100
+
101
+ /**
102
+ * THE SINGLE DECISION SITE for whether the fetched page can be scored at all.
103
+ *
104
+ * Both guards are about the FETCH, not the ledgers, and neither can be
105
+ * recovered downstream — which is why they refuse rather than warn.
106
+ *
107
+ * The first is narrow on purpose. The ledger is one upserted comment, so its
108
+ * position in a creation-ordered connection is fixed when round 1 writes it
109
+ * and no later volume pushes it past the hundredth. A full page WITH a ledger
110
+ * is therefore fine, and a short page with no ledger is a real absence. The
111
+ * only unresolvable reading is a full page with no ledger found, where absent
112
+ * and not-fetched are the same bytes.
113
+ *
114
+ * The second catches an under-sized `first:N`, which silently returns a
115
+ * PREFIX of the range and whose figures are internally consistent and about
116
+ * the wrong cohort. An empty list fails it too: there is no `min` to equal
117
+ * `lo`, and a reading over nothing must not pass a range check.
118
+ *
119
+ * **The third and fourth exist because a min and a max do not describe a
120
+ * set.** #1633 round 3: `fetchEntries` filters to `[lo, hi]` and the
121
+ * `--from` loader does not, so a stale or hand-edited entries file reaches
122
+ * the scorer unfiltered and inflates the pull-request count, the round
123
+ * total and both columns' denominators — which `--record --write-spec` then
124
+ * lands in the store and in the spec.
125
+ *
126
+ * **They are not equally severe and the difference is worth stating.** An
127
+ * out-of-range number cannot evade the min/max check; it necessarily moves
128
+ * one of them. What it could do was arrive MISDIAGNOSED, because the only
129
+ * message said the page spans the wrong thing and told the reader to *raise
130
+ * the page size* — the opposite of the fix, for a file carrying too many
131
+ * rows. A **duplicate** is the one that was genuinely invisible: it changes
132
+ * neither min nor max, and it weights one pull request twice in the round
133
+ * total and in both columns.
134
+ *
135
+ * Both are checked HERE rather than fixed in the loader, deliberately.
136
+ * Filtering the file down to `[lo, hi]` would silently trim a stale input,
137
+ * which is the same class of problem one layer along: a file that disagrees
138
+ * with the range it was handed is a file nobody should score.
139
+ */
140
+ export function premiseViolations(
141
+ entries: readonly CrcEntry[],
142
+ lo: number,
143
+ hi: number,
144
+ ): PremiseViolation[] {
145
+ const out: PremiseViolation[] = [];
146
+
147
+ const unresolvable = entries.filter(e => e.body === null && e.truncated).map(e => e.number);
148
+ if (unresolvable.length > 0) {
149
+ out.push({
150
+ kind: CRC_PREMISE_UNRESOLVABLE_ABSENCE,
151
+ detail:
152
+ `${unresolvable.length} pull request(s) returned a FULL comment page and no ledger: ` +
153
+ `${unresolvable.map(n => `#${n}`).join(", ")}. On those, "no ledger" and "the page ` +
154
+ `did not reach it" are the same bytes, so the absence cannot be scored either way.`,
155
+ });
156
+ }
157
+
158
+ const numbers = entries.map(e => e.number);
159
+ const min = numbers.length === 0 ? null : Math.min(...numbers);
160
+ const max = numbers.length === 0 ? null : Math.max(...numbers);
161
+ if (min !== lo || max !== hi) {
162
+ out.push({
163
+ kind: CRC_PREMISE_RANGE_NOT_COVERED,
164
+ detail:
165
+ `the fetched page spans ${min === null ? "nothing" : `#${min}–#${max}`} and the range ` +
166
+ `asked for is #${lo}–#${hi}. An under-sized page returns a PREFIX of the range, whose ` +
167
+ `figures are internally consistent and about a different cohort — raise the page size.`,
168
+ });
169
+ }
170
+
171
+ const outside = numbers.filter(n => n < lo || n > hi);
172
+ if (outside.length > 0) {
173
+ out.push({
174
+ kind: CRC_PREMISE_OUT_OF_RANGE,
175
+ detail:
176
+ `${outside.length} pull request(s) fall outside #${lo}–#${hi}: ` +
177
+ `${outside.map(n => `#${n}`).join(", ")}. A min and a max that line up do not make the ` +
178
+ `set the range it is labelled with, and every one of these inflates a denominator.`,
179
+ });
180
+ }
181
+
182
+ const seen = new Set<number>();
183
+ const duplicates = [...new Set(numbers.filter(n => (seen.has(n) ? true : (seen.add(n), false))))];
184
+ if (duplicates.length > 0) {
185
+ out.push({
186
+ kind: CRC_PREMISE_DUPLICATE,
187
+ detail:
188
+ `${duplicates.length} pull request(s) appear more than once: ` +
189
+ `${duplicates.map(n => `#${n}`).join(", ")}. A repeated entry is counted twice in the ` +
190
+ `round total and in both columns, which is a weighting nobody chose.`,
191
+ });
192
+ }
193
+ return out;
194
+ }
195
+
196
+ /** Why one pull request could not be scored in a column. */
197
+ export interface CrcRefusal {
198
+ readonly number: number;
199
+ readonly refusal: string;
200
+ readonly detail: string;
201
+ }
202
+
203
+ /** One pull request's round count in one column, or its refusal. */
204
+ export type CrcRoundCount = { readonly rounds: number } | CrcRefusal;
205
+
206
+ /**
207
+ * How many rounds this pull request had, counting every round.
208
+ *
209
+ * Delegates to `roundsTaken`, which is `lib/rounds-to-pass.ts`'s own single
210
+ * decision site, so the truncation refusal and the `rounds.length + dropped`
211
+ * arithmetic are not restated here. A second copy of that rule is a second
212
+ * decider that would drift, and the drift direction is flattering.
213
+ */
214
+ export function allRoundsFor(entry: CrcEntry): CrcRoundCount {
215
+ const taken = roundsTaken({
216
+ number: entry.number,
217
+ passed: entry.passed,
218
+ ledger: readLedger(entry.body),
219
+ });
220
+ if ("refusal" in taken) {
221
+ return { number: entry.number, refusal: taken.refusal, detail: taken.detail };
222
+ }
223
+ return taken;
224
+ }
225
+
226
+ /**
227
+ * The ONLY refusal the measured-only column is allowed to score through.
228
+ *
229
+ * Every other refusal `roundsTaken` can make is a fact about the ledger —
230
+ * absent, unreadable, an eviction count that is not a number, no rounds at
231
+ * all — and a fact about the ledger is true in both columns or neither. This
232
+ * set is the closed statement of where the two columns may disagree, in one
233
+ * direction; `ZERO_MEASURED_ROUNDS` is the disagreement in the other, and
234
+ * there is no third. `test/crc-reading.test.ts` runs the pair over every
235
+ * ledger shape in this file and fails on any divergence not named here, so a
236
+ * refusal added to `rounds-to-pass.ts` later cannot quietly join this set.
237
+ */
238
+ const MEASURED_ONLY_SCORES_ANYWAY: ReadonlySet<string> = new Set(["ROUNDS_TRUNCATION_UNKNOWN"]);
239
+
240
+ /**
241
+ * How many of this pull request's rounds produced a review.
242
+ *
243
+ * A pull request whose every round was refused by the review system has no
244
+ * rounds-to-pass in this column and is UNMEASURED, not zero. That single
245
+ * decision is worth thirteen points: the first published measured-only column
246
+ * scored twelve never-reviewed pull requests as one-round passes and reported
247
+ * 62.8% where the refusing rule reports 48.4%.
248
+ *
249
+ * Truncation is NOT refused here and the difference from `allRoundsFor` is
250
+ * deliberate. An evicted round's kind is unrecoverable — it may have been
251
+ * measured or not — so a ledger that evicted rounds yields a **lower bound**
252
+ * on its measured count. Refusing it would drop the longest histories, which
253
+ * is the direction this metric is already biased in; the bound is reported
254
+ * instead.
255
+ *
256
+ * **The reading is returned whole, as `LedgerTruncation`, not flattened to a
257
+ * number.** #1633 round 2: it used to return `evicted: 0` for both a ledger
258
+ * STATING zero evictions and a legacy bare-array ledger whose eviction count
259
+ * is unknowable — and the module's own test demonstrated it, with
260
+ * `allRoundsFor` refusing that input as `ROUNDS_TRUNCATION_UNKNOWN` while
261
+ * this one answered `evicted: 0` on the same bytes. A range of open pull
262
+ * requests on the legacy format would then have suppressed the LOWER BOUND
263
+ * banner entirely. `LedgerTruncation` has no number to reach for without
264
+ * narrowing the status first, which is why it is that type upstream.
265
+ */
266
+ export function measuredRoundsFor(
267
+ entry: CrcEntry,
268
+ ): ({ readonly rounds: number; readonly truncation: LedgerTruncation } | CrcRefusal) {
269
+ const reading = readLedger(entry.body);
270
+
271
+ // Both columns ask `roundsTaken` FIRST, so every refusal that is a fact
272
+ // about the LEDGER — absent, unreadable, no rounds at all — is decided in
273
+ // one place and the two columns cannot disagree about it. Only
274
+ // `MEASURED_ONLY_SCORES_ANYWAY` is allowed to differ, and it is listed
275
+ // rather than implied. #1633 round 4 found the divergence this closes: an
276
+ // empty ledger was ROUNDS_EMPTY through `allRoundsFor` and
277
+ // ZERO_MEASURED_ROUNDS here, so a pull request the reviewer never ran on
278
+ // was listed beside ones it ran on and produced nothing — and a ledger
279
+ // whose eviction count is not a number reached the eviction SUM.
280
+ const taken = roundsTaken({ number: entry.number, passed: entry.passed, ledger: reading });
281
+ if ("refusal" in taken && !MEASURED_ONLY_SCORES_ANYWAY.has(taken.refusal)) {
282
+ return { number: entry.number, refusal: taken.refusal, detail: taken.detail };
283
+ }
284
+ if (reading.status !== AI_REVIEW_LEDGER_READ) {
285
+ /* c8 ignore next 2 — unreachable: a non-READ reading always refuses above. */
286
+ return { number: entry.number, refusal: "LEDGER_UNREADABLE", detail: "unreachable" };
287
+ }
288
+ const measured = reading.rounds.filter(r => r.measured).length;
289
+ if (measured === 0) {
290
+ return {
291
+ number: entry.number,
292
+ refusal: "ZERO_MEASURED_ROUNDS",
293
+ detail:
294
+ `${reading.rounds.length} round(s) recorded and not one produced a review. A pull ` +
295
+ `request the reviewer never read once has no rounds-to-pass; scoring it as a ` +
296
+ `one-round pass is the most favourable thing this reading could say about a pull ` +
297
+ `request the review system refused.`,
298
+ };
299
+ }
300
+ return { rounds: measured, truncation: reading.truncation };
301
+ }
302
+
303
+ /** One scored column — the three figures, each with its own numerator. */
304
+ export interface CrcColumn {
305
+ /** Pull requests that scored, passed or not. The tail's denominator. */
306
+ readonly measured: number;
307
+ /** Of those, the ones that passed. The mean's and one-round's denominator. */
308
+ readonly passed: number;
309
+ /** Rounds spent by the ones that passed. The mean's numerator. */
310
+ readonly passedRounds: number;
311
+ readonly mean: number | null;
312
+ readonly oneRound: number | null;
313
+ readonly fiveOrMore: number | null;
314
+ readonly refusals: readonly CrcRefusal[];
315
+ }
316
+
317
+ interface Scored {
318
+ readonly passed: boolean;
319
+ readonly rounds: number;
320
+ }
321
+
322
+ /**
323
+ * The three figures over one column's scored pull requests.
324
+ *
325
+ * Null, never zero, when there is nothing to average. A mean of nothing is
326
+ * not 0 and a rate over nothing is not 0%, and both of those read as perfect
327
+ * on the table this feeds.
328
+ */
329
+ export function scoreColumn(scored: readonly Scored[], refusals: readonly CrcRefusal[]): CrcColumn {
330
+ const passed = scored.filter(s => s.passed);
331
+ const passedRounds = passed.reduce((a, s) => a + s.rounds, 0);
332
+ return {
333
+ measured: scored.length,
334
+ passed: passed.length,
335
+ passedRounds,
336
+ mean: passed.length === 0 ? null : passedRounds / passed.length,
337
+ oneRound: passed.length === 0 ? null : passed.filter(s => s.rounds === 1).length,
338
+ // Whole measured population, passed or not — `lib/rounds-to-pass.ts`'s
339
+ // choice, applied to both columns so the two are read the same way.
340
+ fiveOrMore:
341
+ scored.length === 0 ? null : scored.filter(s => s.rounds >= LONG_REVIEW_ROUNDS).length,
342
+ refusals,
343
+ };
344
+ }
345
+
346
+ /** Rounds by what came out of them, over every pull request in the range. */
347
+ export interface CrcSplit {
348
+ readonly total: number;
349
+ /** State name -> rounds. `measured` plus whatever the recorder wrote. */
350
+ readonly kinds: Readonly<Record<string, number>>;
351
+ }
352
+
353
+ /** The split's name for a round that produced a review. */
354
+ export const CRC_ROUND_MEASURED = "measured";
355
+
356
+ /**
357
+ * The round-kind split, over ALL pull requests in the range, merged or not.
358
+ *
359
+ * This reading needs BOTH views of each round and takes each from its own
360
+ * owner. **Whether the round was measured comes from `readLedger`** —
361
+ * `toLedgerRound` already computes `Array.isArray(findings)` and that is the
362
+ * only place in the tree allowed to decide it, so the split's `measured`
363
+ * total and `measuredRoundsFor`'s per-pull-request counts cannot drift.
364
+ * **Which KIND of unmeasured comes from the raw entry**, because
365
+ * `LedgerRound` has no slot for the `unmeasured` discriminator.
366
+ *
367
+ * The first draft restated the measured predicate inline, hardcoding the
368
+ * string `"findings"` beside a docblock arguing against exactly that. A
369
+ * reviewer caught it on #1633 and was right: tightening `toLedgerRound`'s
370
+ * rule would have moved one column and not the other, silently.
371
+ *
372
+ * The two views are `readLedger(body).rounds` and `ledgerRawRounds(body)`,
373
+ * which are the same array — one mapped, one not — so they align by index.
374
+ * That is asserted rather than assumed: a length mismatch means one of the
375
+ * two parsers changed and the pull request is skipped rather than zipped
376
+ * against the wrong entries.
377
+ *
378
+ * A ledger that refuses contributes nothing and is not counted as zero
379
+ * rounds. Its pull request is already named in both columns' refusals.
380
+ */
381
+ export function splitRoundKinds(entries: readonly CrcEntry[]): CrcSplit {
382
+ const kinds: Record<string, number> = {};
383
+ let total = 0;
384
+ for (const entry of entries) {
385
+ const reading = readLedger(entry.body);
386
+ const raw = ledgerRawRounds(entry.body);
387
+ if (reading.status !== AI_REVIEW_LEDGER_READ || raw === null) continue;
388
+ if (raw.length !== reading.rounds.length) continue;
389
+ for (let i = 0; i < raw.length; i++) {
390
+ total++;
391
+ const kind = reading.rounds[i].measured
392
+ ? CRC_ROUND_MEASURED
393
+ : readRecordedUnmeasuredState(raw[i]);
394
+ kinds[kind] = (kinds[kind] ?? 0) + 1;
395
+ }
396
+ }
397
+ return { total, kinds };
398
+ }
399
+
400
+ /** One dated reading, as it is stored and as the spec renders it. */
401
+ export interface CrcReadingRow {
402
+ /** ISO day the reading was taken. */
403
+ readonly date: string;
404
+ readonly lo: number;
405
+ readonly hi: number;
406
+ readonly pullRequests: number;
407
+ readonly allRounds: CrcColumn;
408
+ readonly measuredOnly: CrcColumn;
409
+ /**
410
+ * Rounds the scored ledgers STATED they evicted. Above zero means the
411
+ * measured-only figures are a LOWER BOUND by at least this much.
412
+ */
413
+ readonly measuredOnlyEvicted: number;
414
+ /**
415
+ * Scored pull requests whose eviction count could not be established at
416
+ * all — a different fact from zero, and the one a single number hid.
417
+ * Non-empty also means LOWER BOUND, by an amount nobody can state.
418
+ */
419
+ readonly measuredOnlyEvictionUnknown: readonly number[];
420
+ readonly split: CrcSplit;
421
+ /** Pull requests whose every round was refused by the review system. */
422
+ readonly zeroMeasured: readonly number[];
423
+ }
424
+
425
+ /** Take the whole reading. Premises are the caller's to check first. */
426
+ export function takeCrcReading(
427
+ entries: readonly CrcEntry[],
428
+ lo: number,
429
+ hi: number,
430
+ date: string,
431
+ ): CrcReadingRow {
432
+ const allScored: Scored[] = [];
433
+ const allRefusals: CrcRefusal[] = [];
434
+ const measuredScored: Scored[] = [];
435
+ const measuredRefusals: CrcRefusal[] = [];
436
+ const zeroMeasured: number[] = [];
437
+ const measuredOnlyEvictionUnknown: number[] = [];
438
+ let measuredOnlyEvicted = 0;
439
+
440
+ for (const entry of entries) {
441
+ const all = allRoundsFor(entry);
442
+ if ("refusal" in all) allRefusals.push(all);
443
+ else allScored.push({ passed: entry.passed, rounds: all.rounds });
444
+
445
+ const only = measuredRoundsFor(entry);
446
+ if ("refusal" in only) {
447
+ measuredRefusals.push(only);
448
+ if (only.refusal === "ZERO_MEASURED_ROUNDS") zeroMeasured.push(entry.number);
449
+ } else {
450
+ measuredScored.push({ passed: entry.passed, rounds: only.rounds });
451
+ // Narrowed, not defaulted. An unknown eviction count has no number to
452
+ // add and is recorded as its own fact instead of folded into zero.
453
+ if (only.truncation.status === AI_REVIEW_TRUNCATION_STATED) {
454
+ measuredOnlyEvicted += only.truncation.dropped;
455
+ } else {
456
+ measuredOnlyEvictionUnknown.push(entry.number);
457
+ }
458
+ }
459
+ }
460
+
461
+ return {
462
+ date,
463
+ lo,
464
+ hi,
465
+ pullRequests: entries.length,
466
+ allRounds: scoreColumn(allScored, allRefusals),
467
+ measuredOnly: scoreColumn(measuredScored, measuredRefusals),
468
+ measuredOnlyEvicted,
469
+ measuredOnlyEvictionUnknown: measuredOnlyEvictionUnknown.sort((a, b) => a - b),
470
+ split: splitRoundKinds(entries),
471
+ zeroMeasured: zeroMeasured.sort((a, b) => a - b),
472
+ };
473
+ }
474
+
475
+ const pct = (n: number | null, d: number): string =>
476
+ n === null || d === 0 ? "UNMEASURED" : `${((n / d) * 100).toFixed(1)}%`;
477
+ const num = (v: number | null): string => (v === null ? "UNMEASURED" : v.toFixed(2));
478
+
479
+ /** `12 / 43`, or `UNMEASURED` — the numerator belongs in the table. */
480
+ const over = (n: number | null, d: number): string => (n === null ? "—" : `${n} / ${d}`);
481
+
482
+ /**
483
+ * The reading as the markdown the spec carries.
484
+ *
485
+ * Every denominator is printed beside its numerator, because two cells in one
486
+ * row can have different ones and a reader who cannot reproduce a percentage
487
+ * from the counts beside it has to rerun the whole thing to check it.
488
+ */
489
+ export function renderCrcReading(row: CrcReadingRow): string[] {
490
+ const a = row.allRounds;
491
+ const m = row.measuredOnly;
492
+ const lines = [
493
+ `Read over **#${row.lo}–#${row.hi}** on ${row.date} — ${row.pullRequests} pull requests, ` +
494
+ `${row.split.total} rounds.`,
495
+ "",
496
+ "| | all rounds | numerator | measured rounds only | numerator |",
497
+ "|---|---|---|---|---|",
498
+ `| mean rounds to pass | ${num(a.mean)} | ${a.passedRounds} / ${a.passed} | ` +
499
+ `${num(m.mean)} | ${m.passedRounds} / ${m.passed} |`,
500
+ `| passed after one round | ${pct(a.oneRound, a.passed)} | ${over(a.oneRound, a.passed)} | ` +
501
+ `${pct(m.oneRound, m.passed)} | ${over(m.oneRound, m.passed)} |`,
502
+ `| ${LONG_REVIEW_ROUNDS} or more rounds | ${pct(a.fiveOrMore, a.measured)} | ` +
503
+ `${over(a.fiveOrMore, a.measured)} | ${pct(m.fiveOrMore, m.measured)} | ` +
504
+ `${over(m.fiveOrMore, m.measured)} |`,
505
+ "",
506
+ "The five-or-more row's denominator is ALL measured pull requests and the two above it " +
507
+ "are over the ones that PASSED, in both columns — a tail measured on survivors only " +
508
+ "has had its tail cut off.",
509
+ "",
510
+ "| round outcome | rounds | share |",
511
+ "|---|---|---|",
512
+ ];
513
+ for (const [kind, n] of Object.entries(row.split.kinds).sort((x, y) => y[1] - x[1])) {
514
+ lines.push(`| \`${kind}\` | ${n} | ${pct(n, row.split.total)} |`);
515
+ }
516
+ lines.push("");
517
+ const unknown = row.measuredOnlyEvictionUnknown;
518
+ if (row.measuredOnlyEvicted > 0 || unknown.length > 0) {
519
+ const stated =
520
+ row.measuredOnlyEvicted > 0
521
+ ? `${row.measuredOnlyEvicted} round(s) were evicted from ledgers that scored in it, and ` +
522
+ "an evicted round's kind is unrecoverable"
523
+ : null;
524
+ const unknowable =
525
+ unknown.length > 0
526
+ ? `${unknown.length} scored pull request(s) cannot say how many rounds they evicted ` +
527
+ `(${unknown.map(n => `#${n}`).join(", ")}), so the shortfall there is not even a ` +
528
+ "number — which is a different fact from zero and is why this line exists"
529
+ : null;
530
+ lines.push(
531
+ `**The measured-only column is a LOWER BOUND.** ${[stated, unknowable]
532
+ .filter(Boolean)
533
+ .join(". ")}.`,
534
+ "",
535
+ );
536
+ }
537
+ lines.push(
538
+ row.zeroMeasured.length === 0
539
+ ? "**Every pull request in the range had at least one measured round.**"
540
+ : `**${row.zeroMeasured.length} pull request(s) had zero measured rounds in their ` +
541
+ `entire lives** and are UNMEASURED in the measured-only column rather than scored ` +
542
+ `as one-round passes: ${row.zeroMeasured.map(n => `#${n}`).join(", ")}.`,
543
+ );
544
+ return lines;
545
+ }
546
+
547
+ const signed = (v: number, digits: number): string =>
548
+ `${v >= 0 ? "+" : "−"}${Math.abs(v).toFixed(digits)}`;
549
+
550
+ function deltaRow(label: string, before: number | null, after: number | null): string {
551
+ if (before === null || after === null) return ` ${label}: UNMEASURED on one side`;
552
+ return ` ${label}: ${before.toFixed(2)} → ${after.toFixed(2)} (${signed(after - before, 2)})`;
553
+ }
554
+
555
+ function rateRow(
556
+ label: string,
557
+ before: CrcColumn,
558
+ after: CrcColumn,
559
+ pick: (c: CrcColumn) => { n: number | null; d: number },
560
+ ): string {
561
+ const b = pick(before);
562
+ const c = pick(after);
563
+ if (b.n === null || c.n === null || b.d === 0 || c.d === 0) {
564
+ return ` ${label}: UNMEASURED on one side`;
565
+ }
566
+ const bp = (b.n / b.d) * 100;
567
+ const cp = (c.n / c.d) * 100;
568
+ return (
569
+ ` ${label}: ${bp.toFixed(1)}% (${b.n}/${b.d}) → ${cp.toFixed(1)}% (${c.n}/${c.d})` +
570
+ ` (${signed(cp - bp, 1)}pt)`
571
+ );
572
+ }
573
+
574
+ /**
575
+ * The delta against the previous row — and it names BOTH ranges first.
576
+ *
577
+ * A delta between two differently-ranged readings is a comparison of two
578
+ * cohorts, not a measurement of change, and the only honest form of it says
579
+ * so in the same breath as the numbers. The ranges are on the first line for
580
+ * the reason the unmeasured count is on `formatRoundsToPass`'s first line: a
581
+ * reader quotes what they saw first.
582
+ */
583
+ export function deltaLines(previous: CrcReadingRow | null, row: CrcReadingRow): string[] {
584
+ if (previous === null) {
585
+ return [
586
+ `delta: NONE — #${row.lo}–#${row.hi} on ${row.date} is the first row in the store.`,
587
+ ];
588
+ }
589
+ const shared =
590
+ Math.min(previous.hi, row.hi) - Math.max(previous.lo, row.lo) + 1;
591
+ const lines = [
592
+ `delta: #${previous.lo}–#${previous.hi} (${previous.date}) → #${row.lo}–#${row.hi} ` +
593
+ `(${row.date}) — ${shared > 0 ? `${shared} pull request numbers in common` : "DISJOINT ranges"}.` +
594
+ (previous.lo === row.lo && previous.hi === row.hi
595
+ ? ""
596
+ : " These are different cohorts; the figures below are a comparison, not a change."),
597
+ ];
598
+ for (const [name, b, a] of [
599
+ ["all rounds", previous.allRounds, row.allRounds],
600
+ ["measured only", previous.measuredOnly, row.measuredOnly],
601
+ ] as const) {
602
+ lines.push(`${name}:`);
603
+ lines.push(deltaRow("mean rounds to pass ", b.mean, a.mean));
604
+ lines.push(rateRow("passed after one round", b, a, c => ({ n: c.oneRound, d: c.passed })));
605
+ lines.push(
606
+ rateRow(`${LONG_REVIEW_ROUNDS} or more rounds `, b, a, c => ({
607
+ n: c.fiveOrMore,
608
+ d: c.measured,
609
+ })),
610
+ );
611
+ }
612
+ const un = (s: CrcSplit) => s.total - (s.kinds[CRC_ROUND_MEASURED] ?? 0);
613
+ lines.push(
614
+ `unmeasured rounds: ${pct(un(previous.split), previous.split.total)} ` +
615
+ `(${un(previous.split)}/${previous.split.total}) → ${pct(un(row.split), row.split.total)} ` +
616
+ `(${un(row.split)}/${row.split.total})`,
617
+ );
618
+ return lines;
619
+ }
620
+
621
+ /** Rounds nothing classified — present only on ledgers older than #1486. */
622
+ export function notRecordedRounds(split: CrcSplit): number {
623
+ return split.kinds[AI_REVIEW_UNMEASURED_NOT_RECORDED] ?? 0;
624
+ }
625
+
626
+ /** Where the rendered block starts in the spec. */
627
+ export const CRC_BLOCK_BEGIN =
628
+ "<!-- crc-reading:begin — generated by `bun scripts/crc-reading.ts`; do not edit by hand -->";
629
+
630
+ /** Where it ends. */
631
+ export const CRC_BLOCK_END = "<!-- crc-reading:end -->";
632
+
633
+ /**
634
+ * Put the rendered reading between the markers.
635
+ *
636
+ * THE SINGLE SITE for the splice, so the script that writes the block and
637
+ * the test that checks it cannot disagree about where the block is. Two
638
+ * implementations of "find the markers" is the shape
639
+ * `.claude/rules/checks-must-be-able-to-fail.md` calls *two deciders*: the
640
+ * check would go green against its own idea of the boundary.
641
+ *
642
+ * `null` when either marker is missing or they are the wrong way round — a
643
+ * document that cannot say where its generated block goes must refuse, not
644
+ * get one appended somewhere plausible.
645
+ */
646
+ export function spliceCrcBlock(document: string, row: CrcReadingRow): string | null {
647
+ const begin = document.indexOf(CRC_BLOCK_BEGIN);
648
+ const end = document.indexOf(CRC_BLOCK_END, begin);
649
+ if (begin === -1 || end === -1) return null;
650
+ return (
651
+ document.slice(0, begin + CRC_BLOCK_BEGIN.length) +
652
+ `\n\n${renderCrcReading(row).join("\n")}\n\n` +
653
+ document.slice(end)
654
+ );
655
+ }