rungate 0.8.2 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -39,7 +39,7 @@
39
39
  * **A finding fingerprint may not be keyed on a line number.** The first case
40
40
  * above moved 318 → 375 between rounds while staying byte-identical, so a
41
41
  * `file:line` key would have failed to suppress the one repeat we can
42
- * actually observe. `findingKey` therefore keys on the file, the normalised
42
+ * actually observe. `carryKey` therefore keys on the file, the normalised
43
43
  * TEXT of the cited line, and the normalised summary.
44
44
  *
45
45
  * **`git blame` is the wrong instrument for this question.** It attributed
@@ -259,6 +259,24 @@ function normalise(v: unknown): string {
259
259
  /**
260
260
  * The identity of a finding, for deciding whether it has already been raised.
261
261
  *
262
+ * @identity file+text+summary — `file`, the TEXT of the cited line (falling
263
+ * back to the line NUMBER when the text is not known), and `summary`.
264
+ * Partial: `null` for a finding it cannot key.
265
+ *
266
+ * **This is the PERSISTENCE key** — "is the thing this round raised the thing
267
+ * the last round raised". It is the one the ledger's anchors are recorded
268
+ * under ({@link AI_REVIEW_LEDGER_IDENTITY}) and the one that can refuse.
269
+ *
270
+ * Its sibling is `advisoryKey` in `lib/scaffold/ai-review-findings.ts`, which
271
+ * is the ADJUDICATION key — "has this advisory already been counted on this
272
+ * run" — over `file`+`summary` only, total, never `null`. The two were both
273
+ * called `findingKey` until #1398 and they are deliberately different: a
274
+ * line anchor here is what makes a re-summary of one file two findings
275
+ * rather than one, and a line anchor THERE would split a single finding in
276
+ * two across a reformat. Neither rule can quietly become the other —
277
+ * measured, and both unification mutants are caught — but a call site could
278
+ * not tell which question it was asking while they shared a name.
279
+ *
262
280
  * `file` + the TEXT of the cited line + `summary`. **Not the line number**,
263
281
  * and that is the measured part rather than a preference: the one repeat this
264
282
  * repository can actually show moved from `:318` to `:375` between rounds
@@ -275,7 +293,7 @@ function normalise(v: unknown): string {
275
293
  * nothing to compare such a finding against, and giving it a key would make
276
294
  * every one of them a repeat of the first.
277
295
  */
278
- export function findingKey(finding: unknown, lineText?: unknown): string | null {
296
+ export function carryKey(finding: unknown, lineText?: unknown): string | null {
279
297
  if (typeof finding !== "object" || finding === null || Array.isArray(finding)) return null;
280
298
  const f = finding as ReviewFinding;
281
299
  const file = normalise(f.file);
@@ -300,7 +318,7 @@ export interface SuppressionReading {
300
318
  /**
301
319
  * Drop findings an earlier round already raised.
302
320
  *
303
- * Keyed by `findingKey`, so a finding whose line number moved is still a
321
+ * Keyed by `carryKey`, so a finding whose line number moved is still a
304
322
  * repeat and a finding whose summary changed is not.
305
323
  *
306
324
  * **Within this round too.** A reviewer that lists the same defect twice in
@@ -331,7 +349,7 @@ export function suppressRepeats(
331
349
  continue;
332
350
  }
333
351
  const f = raw as ReviewFinding;
334
- const key = findingKey(f, lineTextFor?.(f));
352
+ const key = carryKey(f, lineTextFor?.(f));
335
353
  if (key === null || !seen.has(key)) {
336
354
  if (key !== null) seen.add(key);
337
355
  kept.push(f);
@@ -385,6 +403,20 @@ export function carryForward(
385
403
  ): ReviewFinding[] {
386
404
  const out: ReviewFinding[] = [];
387
405
  for (const entry of prior) {
406
+ // NOTHING WAS RECORDED, so resolution is UNDECIDABLE — carry it.
407
+ //
408
+ // This branch is the whole of the reading half's first defect. Without
409
+ // it, `normalise(undefined)` is `""`, which differs from any real line,
410
+ // so a finding whose text was never recorded is read as RESOLVED and
411
+ // dropped — silently, every time. Measured against the ledger #1319
412
+ // actually writes, which recorded `{severity, file, line, summary}` and
413
+ // no text: one finding in, zero carried out. An absent reading is not a
414
+ // reading that cleared, and this is the same refusal `roundOutcome`
415
+ // makes about an unreadable budget.
416
+ if (typeof entry.recordedText !== "string") {
417
+ out.push(entry.finding);
418
+ continue;
419
+ }
388
420
  const now = currentLineText(entry.finding);
389
421
  if (typeof now !== "string") {
390
422
  out.push(entry.finding);
@@ -396,6 +428,761 @@ export function carryForward(
396
428
  return out;
397
429
  }
398
430
 
431
+ /* ───────────────── reading the ledger a previous round wrote ──────────────
432
+ *
433
+ * `lib/scaffold/ai-review-step.ts` upserts ONE comment per pull request
434
+ * holding one JSON entry per review round (#1319). Everything above this line
435
+ * takes the prior rounds as a parameter, deliberately — a function that
436
+ * fetches its own evidence cannot be given a negative control. This is the
437
+ * part that turns that comment into the parameter.
438
+ *
439
+ * The two properties it exists to hold, both of which are easy to lose:
440
+ *
441
+ * 1. **Identity is stated, not assumed.** The ledger stamps the rule its
442
+ * anchors were recorded under. A reader that meets a rule it does not
443
+ * know refuses to form keys rather than keying under its own — because
444
+ * keying under the wrong rule does not fail, it silently compares two
445
+ * different things and suppresses live findings.
446
+ *
447
+ * 2. **"Nothing recorded" and "could not read what was recorded" are
448
+ * different facts.** `lib/config-loader.ts` makes the same distinction
449
+ * about an absent config versus a corrupt one, for the same reason: both
450
+ * yield nothing, and only one of them is a reading. Here the type carries
451
+ * it — an unmeasured reading does not HAVE a `keys` field, so a caller
452
+ * cannot reach for one without narrowing the status first.
453
+ *
454
+ * These four constants are declared again in `lib/scaffold/ai-review-step.ts`
455
+ * and must agree. They are not imported from there, and that file must not
456
+ * import this one: the mutation batteries build a mutant by copying that file
457
+ * alone into a scratch directory, so a relative import added to it resolves
458
+ * to nothing and the mutant fails to LOAD — which reads as a behavioural
459
+ * difference on every row (`.claude/rules/self-referential-tests.md`, Tier 1).
460
+ * `test/ai-review-ledger-read.test.ts` AC-R6 binds all four instead.
461
+ */
462
+
463
+ /**
464
+ * The identity rule the ledger's recorded anchors were formed under.
465
+ *
466
+ * Versioned in the string itself. A reader meeting an identity it does not
467
+ * recognise carries the findings and declines to key them, so changing the
468
+ * rule is a safe, one-sided operation: old rounds stop suppressing, and
469
+ * nothing silently compares an old anchor against a new rule.
470
+ */
471
+ export const AI_REVIEW_LEDGER_IDENTITY = "file+text+summary@v1";
472
+
473
+ /** The HTML comment that identifies the ledger comment. */
474
+ export const AI_REVIEW_LEDGER_COMMENT_MARKER = "<!-- rungate:ai-review-ledger:v1 -->";
475
+
476
+ /** The key the per-round findings array is recorded under. */
477
+ export const AI_REVIEW_LEDGER_FINDINGS_KEY = "findings";
478
+
479
+ /**
480
+ * The key the round array hangs off in the windowed ledger shape.
481
+ *
482
+ * The ledger's JSON block was originally the array itself. That shape has no
483
+ * position to say anything ABOUT the array, which is #1405: a ledger holding
484
+ * twelve rounds because twelve is all there have been, and a ledger holding
485
+ * twelve because it evicted eight, are byte-identical. The eviction is
486
+ * announced in a warning annotation that lives in the job log and expires.
487
+ */
488
+ export const AI_REVIEW_LEDGER_ROUNDS_KEY = "rounds";
489
+
490
+ /** The key holding how many rounds the window has dropped off the front. */
491
+ export const AI_REVIEW_LEDGER_TRUNCATED_KEY = "truncated";
492
+
493
+ /** The key holding the text at the cited line when the finding was raised. */
494
+ export const AI_REVIEW_LEDGER_FINDING_TEXT = "text";
495
+
496
+ /**
497
+ * The key holding how many turns the reviewer spent on this round (#1380).
498
+ *
499
+ * #1380 measured 3 of 3 observable same-tree re-runs producing a DIFFERENT
500
+ * verdict, the strongest being merge commit `99d50fc` at round 5 both times,
501
+ * BLOCKED then CLEAN, at 51 turns and 52 against a cap of 80. The turn count
502
+ * is the only candidate mechanism anyone has for that, and it is the one
503
+ * thing about a round that nothing recorded.
504
+ *
505
+ * Mining the history cannot settle it: at the pre-#1198 26% payload rate,
506
+ * n=20 readable same-tree pairs needs ~290 re-runs and 28 exist. So the
507
+ * number has to be captured going forward or not at all, and this is the
508
+ * position that already records `sha`, `run`, `attempt`, `round` and
509
+ * `identity` per entry.
510
+ */
511
+ export const AI_REVIEW_LEDGER_TURNS_KEY = "turns";
512
+
513
+ /**
514
+ * The key holding the commit the reviewer actually read (#1380).
515
+ *
516
+ * NOT the same fact as `sha`, and that is the whole reason it exists. `sha`
517
+ * is `github.event.pull_request.head.sha`; the review ran over whatever
518
+ * `actions/checkout` put in the tree, which on a `pull_request` event is the
519
+ * MERGE commit — head merged into the base as it stood when the run started.
520
+ *
521
+ * So two rounds sharing a `sha` are not two rounds over one tree: the base
522
+ * moves without the head moving, and the reviewer sees different bytes. A
523
+ * same-tree pair is two rounds sharing THIS field, and #1380's whole
524
+ * conditioning caveat — 28 same-tree pairs, 3 readable — was derived from
525
+ * merge commits off the Actions API because the ledger could not answer it.
526
+ */
527
+ export const AI_REVIEW_LEDGER_MERGE_KEY = "merge";
528
+
529
+ /**
530
+ * The key holding the verdict WORD the reviewer wrote beside its findings
531
+ * (#1511).
532
+ *
533
+ * Not an adjudicated outcome and not derivable from `findings`. The payload
534
+ * contract asks the reviewer for a word, `lib/scaffold/ai-review-findings.ts`
535
+ * compares it to what the severities say, and a disagreement is a
536
+ * CONTRADICTION — #1178's shape, measured at roughly a third of runs. A
537
+ * reader handed findings alone can compute what the word SHOULD have been
538
+ * and cannot recover what it WAS, so the contradiction is unobservable
539
+ * through a ledger that does not record it.
540
+ *
541
+ * Which is what the ledger did until #1511, and why
542
+ * `evals/ai-review-control/` could reach `QUIET`, `FIRED` and `MISSED` and
543
+ * never `DETECTED`: every captured round scored `VERDICT_ABSENT`.
544
+ *
545
+ * Declared here and in `lib/scaffold/ai-review-step.ts` as
546
+ * `AI_REVIEW_VERDICT_KEY`, bound by `AC-R6` in
547
+ * `test/ai-review-ledger-read.test.ts` rather than by an import, because
548
+ * that module must stay import-free — the mutation batteries copy it into a
549
+ * temp directory where no relative specifier resolves.
550
+ */
551
+ export const AI_REVIEW_LEDGER_VERDICT_KEY = "verdict";
552
+
553
+ /** The round predates #1511. Nobody tried to record a verdict word. */
554
+ export const AI_REVIEW_VERDICT_NOT_RECORDED = "AI_REVIEW_VERDICT_NOT_RECORDED";
555
+
556
+ /** The round tried to record a verdict word and found none to record. */
557
+ export const AI_REVIEW_VERDICT_UNREADABLE = "AI_REVIEW_VERDICT_UNREADABLE";
558
+
559
+ /** A verdict word was recorded. What it SAYS is the adjudicator's question. */
560
+ export const AI_REVIEW_VERDICT_RECORDED = "AI_REVIEW_VERDICT_RECORDED";
561
+
562
+ /**
563
+ * The verdict word a round recorded, or why there is none.
564
+ *
565
+ * Three states and not two, the same split `turns` carries one key over and
566
+ * for the same reason: a round written before #1511 has no key, and a round
567
+ * written after it always has one. Collapsing them makes a ledger that never
568
+ * recorded a verdict indistinguishable from a reviewer that wrote none.
569
+ *
570
+ * `word` is `unknown` and is **never validated here**. Whether `PASS` and
571
+ * `BLOCK` are the only legal words is
572
+ * `lib/scaffold/ai-review-findings.ts`' decision and it already makes it;
573
+ * a second gate here would be two deciders answering one question, of which
574
+ * a mutation leaves either one holding the case up. A ledger carrying
575
+ * `MAYBE` reports `MAYBE`, and the adjudicator calls it
576
+ * `VERDICT_UNRECOGNISED` — which is the truth about that round.
577
+ */
578
+ export type LedgerVerdictReading =
579
+ | { status: typeof AI_REVIEW_VERDICT_NOT_RECORDED }
580
+ | { status: typeof AI_REVIEW_VERDICT_UNREADABLE }
581
+ | { status: typeof AI_REVIEW_VERDICT_RECORDED; word: unknown };
582
+
583
+ /**
584
+ * Read the verdict word off a ledger round.
585
+ *
586
+ * `undefined` — no key at all — is NOT_RECORDED. A JSON `null` is the
587
+ * writer saying it looked and found nothing, which is UNREADABLE. Anything
588
+ * else is carried through verbatim, including shapes no contract declares.
589
+ */
590
+ export function readRoundVerdict(raw: unknown): LedgerVerdictReading {
591
+ if (raw === undefined) return { status: AI_REVIEW_VERDICT_NOT_RECORDED };
592
+ if (raw === null) return { status: AI_REVIEW_VERDICT_UNREADABLE };
593
+ return { status: AI_REVIEW_VERDICT_RECORDED, word: raw };
594
+ }
595
+
596
+ /** The round predates #1380. Nobody tried to read a turn count. */
597
+ export const AI_REVIEW_TURNS_NOT_RECORDED = "AI_REVIEW_TURNS_NOT_RECORDED";
598
+
599
+ /** This round tried to read a turn count and could not. */
600
+ export const AI_REVIEW_TURNS_UNREADABLE = "AI_REVIEW_TURNS_UNREADABLE";
601
+
602
+ /** The turn count was read. */
603
+ export const AI_REVIEW_TURNS_READ = "AI_REVIEW_TURNS_READ";
604
+
605
+ /**
606
+ * How many turns the reviewer spent, or why that is not known.
607
+ *
608
+ * The non-READ arms carry **no count field at all**, the construction
609
+ * `LedgerTruncation` and `PriorState` already use here: a caller cannot
610
+ * reach for a number without narrowing the status first, so "I could not
611
+ * tell" has no way to be read as zero. `0` is the answer that matters —
612
+ * a run whose execution file never arrived and a run that spent no turns
613
+ * are not the same event, and a `?? 0` makes them one.
614
+ *
615
+ * THREE STATES AND NOT TWO. Absent is NOT_RECORDED and `null` is
616
+ * UNREADABLE, which is the same split `findings` already carries one key
617
+ * over: every round written before #1380 has no key, and a round written
618
+ * after it always has one. Collapsing them would make a ledger that
619
+ * measured nothing indistinguishable from a ledger written last week.
620
+ */
621
+ export type TurnReading =
622
+ | { status: typeof AI_REVIEW_TURNS_NOT_RECORDED }
623
+ | { status: typeof AI_REVIEW_TURNS_UNREADABLE }
624
+ | { status: typeof AI_REVIEW_TURNS_READ; turns: number };
625
+
626
+ /**
627
+ * Read the turn count off a ledger round.
628
+ *
629
+ * `undefined` — no key at all — is NOT_RECORDED. Anything that is not a
630
+ * non-negative integer is UNREADABLE rather than the nearest number: a
631
+ * `"51"` the writer never produces, a float, a negative, `null` itself.
632
+ * There is no branch that returns a count it had to repair.
633
+ */
634
+ export function readRoundTurns(raw: unknown): TurnReading {
635
+ if (raw === undefined) return { status: AI_REVIEW_TURNS_NOT_RECORDED };
636
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
637
+ return { status: AI_REVIEW_TURNS_UNREADABLE };
638
+ }
639
+ return { status: AI_REVIEW_TURNS_READ, turns: raw };
640
+ }
641
+
642
+ /** No ledger comment on this pull request. A MEASURED reading of nothing. */
643
+ export const AI_REVIEW_LEDGER_ABSENT = "AI_REVIEW_LEDGER_ABSENT";
644
+
645
+ /** A ledger is there and could not be read. NOT the same as absent. */
646
+ export const AI_REVIEW_LEDGER_UNREADABLE = "AI_REVIEW_LEDGER_UNREADABLE";
647
+
648
+ /** The ledger was read. */
649
+ export const AI_REVIEW_LEDGER_READ = "AI_REVIEW_LEDGER_READ";
650
+
651
+ /** Keyed on the file, the recorded TEXT of the cited line, and the summary. */
652
+ export const FINDING_IDENTITY_TEXT = "file+text+summary";
653
+
654
+ /**
655
+ * Keyed on the file, the cited line NUMBER, and the summary.
656
+ *
657
+ * Weaker, and recorded as such rather than passed off as the above: the one
658
+ * repeat this repository can demonstrate moved `:318` → `:375` between rounds
659
+ * while staying byte-identical, so this key would have missed it.
660
+ */
661
+ export const FINDING_IDENTITY_LINE = "file+line+summary";
662
+
663
+ /** No key could be formed. The finding is carried and suppresses nothing. */
664
+ export const FINDING_IDENTITY_NONE = "unclassifiable";
665
+
666
+ export type FindingIdentity =
667
+ | typeof FINDING_IDENTITY_TEXT
668
+ | typeof FINDING_IDENTITY_LINE
669
+ | typeof FINDING_IDENTITY_NONE;
670
+
671
+ export interface LedgerRound {
672
+ /** The round number the entry recorded, or null if it recorded none. */
673
+ round: number | null;
674
+ /** The pull request's HEAD commit at the round. NOT the tree reviewed. */
675
+ sha: string;
676
+ /**
677
+ * The commit the reviewer actually read — see `AI_REVIEW_LEDGER_MERGE_KEY`.
678
+ * `""` when the entry recorded none, which is every round before #1380.
679
+ */
680
+ mergeSha: string;
681
+ /** How many turns the reviewer spent, or why that is unknown (#1380). */
682
+ turns: TurnReading;
683
+ /** The verdict word the reviewer wrote, or why there is none (#1511). */
684
+ verdict: LedgerVerdictReading;
685
+ /** False when the entry recorded `findings: null`, or was not an object. */
686
+ measured: boolean;
687
+ /** True when the entry stamped the identity rule this reader knows. */
688
+ keyable: boolean;
689
+ findings: ReviewFinding[];
690
+ }
691
+
692
+ /** How many rounds fell off the front of the window could not be established. */
693
+ export const AI_REVIEW_TRUNCATION_UNKNOWN = "AI_REVIEW_TRUNCATION_UNKNOWN";
694
+
695
+ /** The ledger states how many rounds it has dropped. `0` is a statement. */
696
+ export const AI_REVIEW_TRUNCATION_STATED = "AI_REVIEW_TRUNCATION_STATED";
697
+
698
+ /**
699
+ * The round cap in force when every bare-array ledger in existence was
700
+ * written (#1447).
701
+ *
702
+ * **Deliberately not `AI_REVIEW_LEDGER_MAX_ROUNDS`, and deliberately not
703
+ * imported from it.** Two separate reasons, and they are both load-bearing:
704
+ *
705
+ * The derivation below — *a bare array shorter than its cap was never cut* —
706
+ * is only sound against the cap that was in force when that array was
707
+ * written. Binding it to the live cap would mean lowering the cap tomorrow
708
+ * silently re-reads ledgers written months ago as complete when they were
709
+ * truncated. It cannot do that here: the bare-array shape is CLOSED. #1405's
710
+ * writer migrates every ledger it touches to `{rounds, truncated}`, so no new
711
+ * bare array will ever be written and the population this constant describes
712
+ * is fixed. A fact about history is spelled as a historical constant.
713
+ *
714
+ * The value is 12 because `AI_REVIEW_LEDGER_MAX_ROUNDS` has been 12 since it
715
+ * was introduced in `41f2e93f` (#1168) and has never held another value —
716
+ * checked rather than assumed, because a cap that had once been lower would
717
+ * make every bare array between the old cap and 12 read as a complete history
718
+ * when it had been cut. That is the direction `lib/rounds-to-pass.ts` warns
719
+ * about in its own docblock: this metric's errors all flatter.
720
+ *
721
+ * And this module must gain no import. Mutation batteries copy it into a
722
+ * tmpdir, where a relative import dies on module resolution and the mutant
723
+ * reads as a refusal rather than as a guard that held —
724
+ * `.claude/rules/self-referential-tests.md`, Tier 1.
725
+ */
726
+ export const AI_REVIEW_LEGACY_LEDGER_CAP = 12;
727
+
728
+ /**
729
+ * Whether the rounds in hand are the whole history.
730
+ *
731
+ * UNKNOWN carries **no count field at all**, the same construction
732
+ * `PriorState` uses: a caller cannot reach for a number without narrowing the
733
+ * status first, so "I could not tell" has no way to be read as zero. That is
734
+ * the defect this type exists to make unrepresentable — on #1396 an
735
+ * unreadable eviction count and "nothing was dropped" shared a `case` arm in
736
+ * the shell, and the ledger was written having evicted rounds it did not
737
+ * mention.
738
+ *
739
+ * A legacy ledger — the bare array, written before #1405 — is UNKNOWN and not
740
+ * zero. It may well be complete, and nothing in it says so.
741
+ */
742
+ export type LedgerTruncation =
743
+ | { status: typeof AI_REVIEW_TRUNCATION_UNKNOWN; reason: string }
744
+ | { status: typeof AI_REVIEW_TRUNCATION_STATED; dropped: number };
745
+
746
+ /**
747
+ * The UNREADABLE arm, named so one construction site serves both a READING
748
+ * of a ledger body and a SELECTION among comments. Two literals would be two
749
+ * things to keep in step for one fact.
750
+ */
751
+ export type LedgerUnreadable = {
752
+ status: typeof AI_REVIEW_LEDGER_UNREADABLE;
753
+ reason: string;
754
+ };
755
+
756
+ export type LedgerReading =
757
+ | { status: typeof AI_REVIEW_LEDGER_ABSENT }
758
+ | LedgerUnreadable
759
+ | {
760
+ status: typeof AI_REVIEW_LEDGER_READ;
761
+ rounds: LedgerRound[];
762
+ truncation: LedgerTruncation;
763
+ };
764
+
765
+ /**
766
+ * Say that the ledger could not be read, for a reason only the caller knows.
767
+ *
768
+ * The API call that lists a pull request's comments can fail, and when it
769
+ * does the caller has no body to hand to `readLedger`. Without this it would
770
+ * have to pass `null`, which reads as ABSENT — a failed fetch would then be
771
+ * indistinguishable from a pull request on its first round, and every earlier
772
+ * finding would silently stop being carried.
773
+ */
774
+ export function ledgerUnreadable(reason: string): LedgerUnreadable {
775
+ return { status: AI_REVIEW_LEDGER_UNREADABLE, reason };
776
+ }
777
+
778
+ /**
779
+ * The login the ledger comment is written as, and the only one selected.
780
+ *
781
+ * **This clause is the load-bearing one, and the repository's own tracker is
782
+ * the counter-example that makes it so.** The rationale this selection used
783
+ * to carry said the conjunction was safe because *nothing else writes the
784
+ * marker*. Measured against the live API on 2026-10-24, pull requests #1319
785
+ * and #1386 each carry TWO comments containing
786
+ * `AI_REVIEW_LEDGER_COMMENT_MARKER`: the ledger, written by
787
+ * `github-actions[bot]`, and a `type: "User"` comment that quotes the marker
788
+ * while discussing it. The marker is a quotable string and uniqueness of a
789
+ * quotable string is not obtainable — so making the marker more exotic is
790
+ * not the answer, and the login clause is what separates the two today.
791
+ *
792
+ * `lib/scaffold/ai-review-step.ts` declares the same string as
793
+ * `AI_REVIEW_LEDGER_BOT_LOGIN` and `test/ai-review-ledger-selection.test.ts`
794
+ * binds the two, rather than importing: that module is copied into a tmpdir
795
+ * by mutation batteries, where a relative specifier dies on resolution.
796
+ */
797
+ export const AI_REVIEW_LEDGER_BOT_LOGIN_NAME = "github-actions[bot]";
798
+
799
+ /**
800
+ * How many comments on one pull request may be the ledger. **One.**
801
+ *
802
+ * The single site every ambiguity refusal below is routed through, so a test
803
+ * can build a mutant copy of this module with the bound widened and watch
804
+ * the refusal stop happening. Raise it and `selectLedgerComment` returns the
805
+ * first match instead — which is the defect, performed and observed, rather
806
+ * than a sentence claiming the guard works
807
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
808
+ */
809
+ export const AI_REVIEW_LEDGER_MAX_MATCHES = 1;
810
+
811
+ /**
812
+ * A pull-request comment, reduced to the four fields the selection reads.
813
+ *
814
+ * Every field is `unknown` because they arrive from an API response that a
815
+ * caller has at best parsed, never validated. A comment whose author block
816
+ * is missing is not a comment this selection may adopt.
817
+ */
818
+ export interface LedgerCandidate {
819
+ id: unknown;
820
+ body: unknown;
821
+ login: unknown;
822
+ type: unknown;
823
+ }
824
+
825
+ /** A candidate that passed the selection — every field narrowed. */
826
+ export interface LedgerComment {
827
+ id: number;
828
+ body: string;
829
+ login: string;
830
+ type: string;
831
+ }
832
+
833
+ /**
834
+ * Which comment on a pull request IS the ledger, or why that is not knowable.
835
+ *
836
+ * Deliberately the same three statuses `LedgerReading` uses, because they are
837
+ * the same three facts one step earlier: there is no ledger here, there is
838
+ * something here that cannot be read as one, or here it is. A fourth status
839
+ * would be a second vocabulary for a question already answered.
840
+ */
841
+ export type LedgerSelection =
842
+ | { status: typeof AI_REVIEW_LEDGER_ABSENT }
843
+ | LedgerUnreadable
844
+ | { status: typeof AI_REVIEW_LEDGER_READ; comment: LedgerComment };
845
+
846
+ /**
847
+ * Pick the ledger out of a pull request's comments, or REFUSE.
848
+ *
849
+ * **Two matches is not a reading, and the first of them is not an answer.**
850
+ * This is the whole of #1412: a reader handed more than one comment carrying
851
+ * the ledger marker has no way to tell which document it is about, and a
852
+ * wrong comment that parses is byte-indistinguishable from a right one — so
853
+ * every number computed off it (rounds-to-pass, the unmeasured split, the
854
+ * turn counts) would be read off a population nobody can name. Ambiguous and
855
+ * absent are different states and neither one is a ledger.
856
+ *
857
+ * Three readings, and they are kept apart on purpose:
858
+ *
859
+ * * **ABSENT** — no comment here was written by this bot carrying the
860
+ * marker. A MEASURED reading of nothing, correct and complete on round
861
+ * one, and the only one that licenses POSTing a first ledger.
862
+ * * **UNREADABLE** — more than one did. The reason names every id, because
863
+ * a refusal that does not say which documents collided is a refusal
864
+ * nobody can act on.
865
+ * * **READ** — exactly one, narrowed.
866
+ *
867
+ * A `type: "User"` comment quoting the marker is not a candidate and does
868
+ * not make the reading ambiguous either: it is not a ledger, so it is not
869
+ * one of the things that could be. See `AI_REVIEW_LEDGER_BOT_LOGIN_NAME` for
870
+ * why that clause — and not the marker's supposed uniqueness — is what makes
871
+ * this selection an identity.
872
+ */
873
+ export function selectLedgerComment(
874
+ comments: readonly LedgerCandidate[],
875
+ ): LedgerSelection {
876
+ const matches: LedgerComment[] = [];
877
+ for (const c of comments) {
878
+ if (c.type !== "Bot") continue;
879
+ if (c.login !== AI_REVIEW_LEDGER_BOT_LOGIN_NAME) continue;
880
+ if (typeof c.body !== "string") continue;
881
+ if (!c.body.includes(AI_REVIEW_LEDGER_COMMENT_MARKER)) continue;
882
+ if (typeof c.id !== "number" || !Number.isInteger(c.id)) {
883
+ return ledgerUnreadable(
884
+ `a comment written by ${AI_REVIEW_LEDGER_BOT_LOGIN_NAME} carries the ledger ` +
885
+ `marker and reports ${JSON.stringify(c.id)} as its id, which is not one, so ` +
886
+ "it cannot be addressed and is not being treated as absent",
887
+ );
888
+ }
889
+ matches.push({ id: c.id, body: c.body, login: c.login, type: c.type });
890
+ }
891
+ if (matches.length === 0) return { status: AI_REVIEW_LEDGER_ABSENT };
892
+ if (matches.length > AI_REVIEW_LEDGER_MAX_MATCHES) {
893
+ return ledgerUnreadable(
894
+ `${matches.length} comments on this pull request are written by ` +
895
+ `${AI_REVIEW_LEDGER_BOT_LOGIN_NAME} and carry the ledger marker (ids ` +
896
+ `${matches.map(m => m.id).join(", ")}), so which one is the ledger cannot be ` +
897
+ "established. Refusing to read the first: a wrong ledger that parses is " +
898
+ "indistinguishable from the right one afterwards",
899
+ );
900
+ }
901
+ return { status: AI_REVIEW_LEDGER_READ, comment: matches[0] };
902
+ }
903
+
904
+ /**
905
+ * Parse the ledger comment's body.
906
+ *
907
+ * `null`, `undefined` and a body without the marker are ABSENT: there is no
908
+ * ledger, which is the correct and complete reading on round one. A body that
909
+ * HAS the marker and whose JSON block is missing, truncated, unparseable or
910
+ * neither of the two round shapes is UNREADABLE — never an empty ledger,
911
+ * because treating a damaged ledger as empty discards every round it holds at
912
+ * exactly the moment nothing can tell that it happened.
913
+ *
914
+ * Two round shapes are accepted and the reading says which was found through
915
+ * `truncation`: a bare array, which is every ledger written before #1405 and
916
+ * is still live on open pull requests, and `{rounds, truncated}`, which can
917
+ * say how much of the history fell off the front of the window. Rejecting the
918
+ * bare array would discard the history of every pull request mid-flight at
919
+ * the moment the new writer merged.
920
+ */
921
+ export function readLedger(body: unknown): LedgerReading {
922
+ if (typeof body !== "string") return { status: AI_REVIEW_LEDGER_ABSENT };
923
+ const marker = body.indexOf(AI_REVIEW_LEDGER_COMMENT_MARKER);
924
+ if (marker === -1) return { status: AI_REVIEW_LEDGER_ABSENT };
925
+
926
+ const fence = body.indexOf("```json", marker);
927
+ if (fence === -1) {
928
+ return ledgerUnreadable(
929
+ "the ledger comment is present and holds no ```json block, so the rounds it " +
930
+ "recorded cannot be read; it is not being treated as an empty ledger",
931
+ );
932
+ }
933
+ const start = body.indexOf("\n", fence);
934
+ const close = start === -1 ? -1 : body.indexOf("\n```", start);
935
+ if (close === -1) {
936
+ return ledgerUnreadable(
937
+ "the ledger comment's ```json block is not closed, so it was truncated in " +
938
+ "transit or in storage and the rounds it recorded cannot be read",
939
+ );
940
+ }
941
+
942
+ let parsed: unknown;
943
+ try {
944
+ parsed = JSON.parse(body.slice(start + 1, close));
945
+ } catch (e) {
946
+ return ledgerUnreadable(
947
+ `the ledger comment's JSON block could not be parsed (${
948
+ e instanceof Error ? e.message : String(e)
949
+ }), so the rounds it recorded cannot be read`,
950
+ );
951
+ }
952
+ // Two shapes, and the older one is still on every open pull request that
953
+ // has a ledger. A bare array is the pre-#1405 ledger: readable, and silent
954
+ // about whether it is the whole history — but not therefore unknowable.
955
+ if (Array.isArray(parsed)) {
956
+ return {
957
+ status: AI_REVIEW_LEDGER_READ,
958
+ rounds: parsed.map(toLedgerRound),
959
+ truncation: legacyTruncation(parsed.length),
960
+ };
961
+ }
962
+ if (typeof parsed !== "object" || parsed === null) {
963
+ return ledgerUnreadable(
964
+ `the ledger comment's JSON block is ${describe(parsed)} rather than an array of ` +
965
+ "rounds, so the rounds it recorded cannot be read",
966
+ );
967
+ }
968
+ const obj = parsed as Record<string, unknown>;
969
+ const rounds = obj[AI_REVIEW_LEDGER_ROUNDS_KEY];
970
+ if (!Array.isArray(rounds)) {
971
+ return ledgerUnreadable(
972
+ `the ledger comment's JSON block is an object whose \`${AI_REVIEW_LEDGER_ROUNDS_KEY}\` ` +
973
+ `is ${describe(rounds)} rather than an array, so the rounds it recorded cannot be read`,
974
+ );
975
+ }
976
+ return {
977
+ status: AI_REVIEW_LEDGER_READ,
978
+ rounds: rounds.map(toLedgerRound),
979
+ truncation: readTruncation(obj[AI_REVIEW_LEDGER_TRUNCATED_KEY]),
980
+ };
981
+ }
982
+
983
+ /**
984
+ * How deep a legacy bare-array ledger is, derived from its length (#1447).
985
+ *
986
+ * The list grows by exactly one entry per round and is only ever cut when it
987
+ * reaches the cap, so **a length below the cap means the cut never ran** and
988
+ * the array is the whole history. That is a derivation from the writer's
989
+ * behaviour, not an assumption about it, and #1405's writer already makes the
990
+ * identical one when it migrates such a ledger forward — this is the reader
991
+ * catching up to it, for the ledgers no future round will ever touch.
992
+ *
993
+ * At or above the cap the length is a LOWER BOUND and nothing more: this
994
+ * round's eviction is knowable and the ones before it are not, and writing
995
+ * the bound as a count would hand a caller a number it cannot tell from a
996
+ * total.
997
+ *
998
+ * The cheap wrong fix is to call every bare array complete. It passes every
999
+ * case below the cap and is wrong at it, which is why
1000
+ * `test/ai-review-ledger-read.test.ts` puts 11 and 12 adjacent.
1001
+ */
1002
+ function legacyTruncation(length: number): LedgerTruncation {
1003
+ if (length < AI_REVIEW_LEGACY_LEDGER_CAP) {
1004
+ return { status: AI_REVIEW_TRUNCATION_STATED, dropped: 0 };
1005
+ }
1006
+ return {
1007
+ status: AI_REVIEW_TRUNCATION_UNKNOWN,
1008
+ reason:
1009
+ `the ledger's JSON block is a bare array of ${length} rounds, the shape written ` +
1010
+ `before the \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` count existed, and it is at or past ` +
1011
+ `the ${AI_REVIEW_LEGACY_LEDGER_CAP}-round cap those ledgers were written under. A ` +
1012
+ `shorter one could be derived complete — the list only grows by one per round and is ` +
1013
+ `only cut at the cap — but at the cap its length is a lower bound on the rounds it ` +
1014
+ `held and says nothing about how many fell off the front`,
1015
+ };
1016
+ }
1017
+
1018
+ /**
1019
+ * Read the dropped-round count off a windowed ledger.
1020
+ *
1021
+ * A malformed count is UNKNOWN, never zero, and never a reason to refuse the
1022
+ * whole ledger: the rounds in hand are still real and still carryable. What
1023
+ * the caller must not be able to do is report the history as complete on the
1024
+ * strength of a field it could not read — which is exactly what a `?? 0`
1025
+ * here would let it do.
1026
+ */
1027
+ function readTruncation(raw: unknown): LedgerTruncation {
1028
+ if (raw === undefined) {
1029
+ return {
1030
+ status: AI_REVIEW_TRUNCATION_UNKNOWN,
1031
+ reason:
1032
+ `the ledger is an object and carries no \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` key, so ` +
1033
+ "it states nothing about rounds dropped off the front",
1034
+ };
1035
+ }
1036
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
1037
+ return {
1038
+ status: AI_REVIEW_TRUNCATION_UNKNOWN,
1039
+ reason:
1040
+ `the ledger's \`${AI_REVIEW_LEDGER_TRUNCATED_KEY}\` is ${describe(raw)} rather than a ` +
1041
+ "non-negative integer, so how many rounds it dropped cannot be established",
1042
+ };
1043
+ }
1044
+ return { status: AI_REVIEW_TRUNCATION_STATED, dropped: raw };
1045
+ }
1046
+
1047
+ function toLedgerRound(raw: unknown): LedgerRound {
1048
+ // An entry that is not an object is a round that was recorded and cannot be
1049
+ // read. It is counted, not skipped: a round that vanishes from the count
1050
+ // makes a three-round pull request look like a two-round one.
1051
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
1052
+ // An unreadable entry has not stated a turn count, and it has not failed
1053
+ // to read one either — nobody got as far as asking. NOT_RECORDED, which
1054
+ // is also what every pre-#1380 round reads as.
1055
+ return {
1056
+ round: null,
1057
+ sha: "",
1058
+ mergeSha: "",
1059
+ turns: { status: AI_REVIEW_TURNS_NOT_RECORDED },
1060
+ // Nobody got as far as asking, which is NOT_RECORDED for the same
1061
+ // reason the turn count above is: an entry that is not an object has
1062
+ // not stated a verdict and has not failed to state one.
1063
+ verdict: { status: AI_REVIEW_VERDICT_NOT_RECORDED },
1064
+ measured: false,
1065
+ keyable: false,
1066
+ findings: [],
1067
+ };
1068
+ }
1069
+ const e = raw as Record<string, unknown>;
1070
+ const list = e[AI_REVIEW_LEDGER_FINDINGS_KEY];
1071
+ const measured = Array.isArray(list);
1072
+ return {
1073
+ round: readRoundNumber(e.round),
1074
+ sha: typeof e.sha === "string" ? e.sha : "",
1075
+ mergeSha:
1076
+ typeof e[AI_REVIEW_LEDGER_MERGE_KEY] === "string"
1077
+ ? (e[AI_REVIEW_LEDGER_MERGE_KEY] as string)
1078
+ : "",
1079
+ turns: readRoundTurns(e[AI_REVIEW_LEDGER_TURNS_KEY]),
1080
+ verdict: readRoundVerdict(e[AI_REVIEW_LEDGER_VERDICT_KEY]),
1081
+ measured,
1082
+ keyable: e.identity === AI_REVIEW_LEDGER_IDENTITY,
1083
+ findings: measured
1084
+ ? (list as unknown[]).filter(
1085
+ (f): f is ReviewFinding => typeof f === "object" && f !== null && !Array.isArray(f),
1086
+ )
1087
+ : [],
1088
+ };
1089
+ }
1090
+
1091
+ /** The prior state could not be established at all. */
1092
+ export const AI_REVIEW_PRIOR_UNMEASURED = "AI_REVIEW_PRIOR_UNMEASURED";
1093
+
1094
+ /** The prior state was established — possibly as nothing. */
1095
+ export const AI_REVIEW_PRIOR_MEASURED = "AI_REVIEW_PRIOR_MEASURED";
1096
+
1097
+ export interface PriorFinding {
1098
+ finding: ReviewFinding;
1099
+ /**
1100
+ * The text at the cited line when the finding was raised. Absent when the
1101
+ * ledger did not record one — and absent is UNDECIDABLE in `carryForward`,
1102
+ * not resolved.
1103
+ */
1104
+ recordedText?: string;
1105
+ /** Which rule formed this finding's key. Stated, so a caller can weigh it. */
1106
+ identity: FindingIdentity;
1107
+ /** The key, or null when no identity could be formed. */
1108
+ key: string | null;
1109
+ /** The round it was raised on, where the ledger recorded one. */
1110
+ round: number | null;
1111
+ }
1112
+
1113
+ export type PriorState =
1114
+ | { status: typeof AI_REVIEW_PRIOR_UNMEASURED; reason: string }
1115
+ | {
1116
+ status: typeof AI_REVIEW_PRIOR_MEASURED;
1117
+ /** Keys earlier rounds raised, for `suppressRepeats`. */
1118
+ keys: string[];
1119
+ /** Everything earlier rounds raised, for `carryForward`. */
1120
+ prior: PriorFinding[];
1121
+ /** Rounds recorded whose findings were never read. */
1122
+ unmeasuredRounds: number;
1123
+ /** Rounds read under an identity rule this reader does not know. */
1124
+ unkeyableRounds: number;
1125
+ };
1126
+
1127
+ /**
1128
+ * Turn a ledger reading into what `suppressRepeats` and `carryForward` take.
1129
+ *
1130
+ * `PriorFinding` is assignable to `CarriedFinding`, so `prior` goes straight
1131
+ * into `carryForward` with no adapter between them — that join is the point
1132
+ * of the shape.
1133
+ *
1134
+ * **An UNREADABLE ledger returns a state with no `keys` and no `prior`.** Not
1135
+ * empty ones: absent ones. A caller holding an unmeasured state cannot
1136
+ * suppress a finding or resolve one, and the type stops it reaching for the
1137
+ * fields that would let it, instead of trusting it to check a boolean nobody
1138
+ * has to read.
1139
+ */
1140
+ export function priorFindings(reading: LedgerReading): PriorState {
1141
+ if (reading.status === AI_REVIEW_LEDGER_UNREADABLE) {
1142
+ return { status: AI_REVIEW_PRIOR_UNMEASURED, reason: reading.reason };
1143
+ }
1144
+ if (reading.status === AI_REVIEW_LEDGER_ABSENT) {
1145
+ return {
1146
+ status: AI_REVIEW_PRIOR_MEASURED,
1147
+ keys: [],
1148
+ prior: [],
1149
+ unmeasuredRounds: 0,
1150
+ unkeyableRounds: 0,
1151
+ };
1152
+ }
1153
+
1154
+ const keys: string[] = [];
1155
+ const prior: PriorFinding[] = [];
1156
+ let unmeasuredRounds = 0;
1157
+ let unkeyableRounds = 0;
1158
+
1159
+ for (const round of reading.rounds) {
1160
+ if (!round.measured) {
1161
+ unmeasuredRounds++;
1162
+ continue;
1163
+ }
1164
+ if (!round.keyable) unkeyableRounds++;
1165
+ for (const finding of round.findings) {
1166
+ const recorded = finding[AI_REVIEW_LEDGER_FINDING_TEXT];
1167
+ const recordedText = typeof recorded === "string" ? recorded : undefined;
1168
+ let identity: FindingIdentity = FINDING_IDENTITY_NONE;
1169
+ let key: string | null = null;
1170
+ // Only a round stamped with the rule this reader knows gets a key. An
1171
+ // unrecognised rule is carried, never dropped, and never keyed.
1172
+ if (round.keyable) {
1173
+ key = carryKey(finding, recordedText);
1174
+ if (key !== null) {
1175
+ identity = normalise(recordedText) !== "" ? FINDING_IDENTITY_TEXT : FINDING_IDENTITY_LINE;
1176
+ keys.push(key);
1177
+ }
1178
+ }
1179
+ prior.push({ finding, recordedText, identity, key, round: round.round });
1180
+ }
1181
+ }
1182
+
1183
+ return { status: AI_REVIEW_PRIOR_MEASURED, keys, prior, unmeasuredRounds, unkeyableRounds };
1184
+ }
1185
+
399
1186
  /**
400
1187
  * What the reviewer is told once the budget is spent.
401
1188
  *