rungate 0.8.13 → 0.8.14

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 (40) hide show
  1. package/README.md +82 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  4. package/lib/ai-review-rounds.ts +99 -0
  5. package/lib/ai-review-suppression.ts +200 -21
  6. package/lib/bash-write-guard.ts +50 -5
  7. package/lib/board-flow.ts +235 -0
  8. package/lib/board-lane-health.ts +381 -0
  9. package/lib/board-mirror.ts +53 -35
  10. package/lib/board-ready-fanout.ts +56 -13
  11. package/lib/board-ready-rule.ts +545 -0
  12. package/lib/board-throughput.ts +136 -0
  13. package/lib/board-walkthrough.ts +240 -0
  14. package/lib/body-evidence.ts +203 -0
  15. package/lib/branch-protection.ts +399 -9
  16. package/lib/conformity.ts +95 -2
  17. package/lib/filing-compliance.ts +367 -0
  18. package/lib/finding-arbiter.ts +79 -5
  19. package/lib/generators/agents-md.ts +149 -0
  20. package/lib/github.ts +79 -0
  21. package/lib/graphql-cursor.ts +80 -0
  22. package/lib/issue-create-override.ts +415 -3
  23. package/lib/issue-decomposition.ts +33 -3
  24. package/lib/issue-file-overlap.ts +340 -0
  25. package/lib/issue-filing-gate.ts +173 -8
  26. package/lib/issue-repair.ts +13 -9
  27. package/lib/issue-shape.ts +196 -0
  28. package/lib/scaffold/ai-review-findings.ts +9 -1
  29. package/lib/scaffold/ai-review-step.ts +35 -1
  30. package/lib/source-census.ts +108 -0
  31. package/lib/spec-deps.ts +34 -11
  32. package/lib/spec-placement.ts +108 -0
  33. package/lib/stage-ladder.ts +28 -3
  34. package/lib/work-status.ts +423 -0
  35. package/package.json +1 -1
  36. package/scripts/ai-review-findings.ts +8 -13
  37. package/scripts/ai-review-threads.ts +16 -17
  38. package/scripts/board-mirror.ts +221 -8
  39. package/scripts/generate-code-map.ts +1 -1
  40. package/scripts/plan-spec.ts +79 -1
@@ -92,6 +92,7 @@ import { readFileSync, readdirSync, statSync } from "fs";
92
92
  import { join } from "path";
93
93
 
94
94
  import { createGitHubClient, parseOwnerRepo, type GitHubClient } from "./github";
95
+ import { AI_REVIEW_THREADS_STEP_ID } from "./scaffold/ai-review-step";
95
96
  import { originSlug } from "./verified-push";
96
97
 
97
98
  // ── Facts ───────────────────────────────────────────────
@@ -124,6 +125,25 @@ export interface ProtectionFacts {
124
125
  * excuse `strict: true`.
125
126
  */
126
127
  mergeQueueEnabled: boolean | null;
128
+ /**
129
+ * `required_conversation_resolution`, or null when the payload said nothing
130
+ * either way — CRC-C3, #1650.
131
+ *
132
+ * GitHub's native implementation of *a finding blocks merge until somebody
133
+ * dispositions it*. It is the only protection setting that can read a
134
+ * review thread, so it is the only one that can tell "this finding was
135
+ * answered" from "nobody looked".
136
+ *
137
+ * **It regresses silently, and did.** The protection endpoint's `PUT`
138
+ * replaces the whole object, so any update that omits this field turns it
139
+ * off and reports success. It was read `true` on 2026-10-25 and behaved
140
+ * that way through 2026-10-27 — three separate pull requests sat at
141
+ * `BLOCKED` on one unresolved thread with every check green, and flipped to
142
+ * `CLEAN` on resolving it. On 2026-11-07 it read `false`, and #1857 merged
143
+ * carrying five unresolved threads. Nothing in the tree read the field, so
144
+ * thirteen days passed with the spec recording it as applied.
145
+ */
146
+ conversationResolution: boolean | null;
127
147
  /**
128
148
  * Non-null when something could not be read: no credential, no remote, a
129
149
  * 403, a network failure. Named, because a cause the operator cannot see is
@@ -138,6 +158,17 @@ export interface PushCiReading {
138
158
  onPush: string[];
139
159
  /** Required contexts with no such trigger. Non-empty blocks `strict: false`. */
140
160
  missing: string[];
161
+ /**
162
+ * Required contexts that DECLARE a push trigger and still cannot contribute
163
+ * the semantic-conflict net, because the action they run rejects the event
164
+ * at its own entry point — #1503.
165
+ *
166
+ * Counted apart from both other lists on purpose. In `onPush` it clears the
167
+ * precondition vacuously, which is the defect. In `missing` the remedy
168
+ * printed is *add a push trigger*, which is the change PR #1502 made: it
169
+ * empties `missing`, lifts the refusal, and reviews nothing.
170
+ */
171
+ cannotRunOnPush: string[];
141
172
  /**
142
173
  * Non-null when the workflows could not be read at all, so neither list
143
174
  * means anything. An empty `missing` from an unread directory is the
@@ -329,6 +360,33 @@ export function readMergeSerialisation(
329
360
  };
330
361
  }
331
362
 
363
+ // #1503: a context that DECLARES a push trigger but runs an action which
364
+ // rejects the `push` event provides no net. It is deliberately not in
365
+ // `missing` — the remedy printed there is *add a push trigger*, which this
366
+ // context already has, and adding one is what produced this state.
367
+ if (pushCi.cannotRunOnPush.length > 0) {
368
+ const names = pushCi.cannotRunOnPush.join(", ");
369
+ const plural = pushCi.cannotRunOnPush.length === 1;
370
+ return {
371
+ verdict: "FAIL",
372
+ reason:
373
+ `${base} Whether it is safe to turn strict off here is UNMEASURED: ${names} ` +
374
+ `${plural ? "declares" : "declare"} a push: trigger but ${plural ? "runs" : "run"} ` +
375
+ `${plural ? "an action" : "actions"} that ${plural ? "rejects" : "reject"} the push ` +
376
+ `event at ${plural ? "its" : "their"} own entry point, so the run fails immediately ` +
377
+ "and reviews nothing.",
378
+ remedy:
379
+ "REFUSING to recommend strict: false, and NOT because a push trigger is missing — " +
380
+ `${names} ${plural ? "has" : "have"} one. The run it produces cannot go red for a ` +
381
+ "semantic conflict (two PRs each green alone, broken together), so the trigger clears " +
382
+ "this precondition without providing the net strict: true is being traded against. " +
383
+ "Adding more push triggers will not fix it. Either give the default branch a required " +
384
+ `context that genuinely runs the suite on push, or leave strict: true. The ` +
385
+ `event-restricted actions this check knows about: ${EVENT_RESTRICTED_ACTIONS.join(", ")}.`,
386
+ mergeQueuePossible: false,
387
+ };
388
+ }
389
+
332
390
  const covered = pushCi.onPush.length
333
391
  ? `All ${pushCi.onPush.length} required context(s) — ${pushCi.onPush.join(", ")} — already run on push: to ${facts.branch ?? "the default branch"}`
334
392
  : "No contexts are required, so nothing is lost by it";
@@ -370,6 +428,7 @@ export function unreadableFacts(slug: string, why: string): ProtectionFacts {
370
428
  ownerType: null,
371
429
  contexts: [],
372
430
  mergeQueueEnabled: null,
431
+ conversationResolution: null,
373
432
  unreadable: why,
374
433
  };
375
434
  }
@@ -475,8 +534,14 @@ export const githubProtectionProbe: ProtectionProbe = async (slug) => {
475
534
 
476
535
  // An unprotected branch requires nothing, so nothing is strict and nothing
477
536
  // serialises. Measured false, not an unread null.
537
+ //
538
+ // `conversationResolution` is false here for the same reason and it is the
539
+ // same kind of fact: an unprotected branch cannot hold a merge for an
540
+ // unanswered finding, so a review that opens threads on one gates nothing.
541
+ // Reading it as `null` would call that unestablished when it is the one
542
+ // case the endpoint lets us establish without admin (#1650).
478
543
  if (!isProtected) {
479
- return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: null, unreadable: null };
544
+ return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: null, conversationResolution: false, unreadable: null };
480
545
  }
481
546
 
482
547
  try {
@@ -517,7 +582,7 @@ export function protectionFactsFromPayload(
517
582
  // No required_status_checks block: protection exists but requires no
518
583
  // checks, so there is no strictness and nothing to be out of date against.
519
584
  if (!rsc || typeof rsc !== "object") {
520
- return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: mergeQueueFrom(d), unreadable: null };
585
+ return { slug, branch, strict: false, ownerType, contexts: [], mergeQueueEnabled: mergeQueueFrom(d), conversationResolution: conversationResolutionFrom(d), unreadable: null };
521
586
  }
522
587
 
523
588
  const strict = typeof rsc.strict === "boolean" ? rsc.strict : null;
@@ -531,7 +596,7 @@ export function protectionFactsFromPayload(
531
596
  (c: unknown): c is string => typeof c === "string" && c.length > 0,
532
597
  );
533
598
 
534
- return { slug, branch, strict, ownerType, contexts, mergeQueueEnabled: mergeQueueFrom(d), unreadable: null };
599
+ return { slug, branch, strict, ownerType, contexts, mergeQueueEnabled: mergeQueueFrom(d), conversationResolution: conversationResolutionFrom(d), unreadable: null };
535
600
  }
536
601
 
537
602
  function mergeQueueFrom(d: Record<string, any>): boolean | null {
@@ -539,6 +604,19 @@ function mergeQueueFrom(d: Record<string, any>): boolean | null {
539
604
  return typeof e === "boolean" ? e : null;
540
605
  }
541
606
 
607
+ /**
608
+ * `required_conversation_resolution.enabled`, and **only** from that shape.
609
+ *
610
+ * The protection endpoint answers `{"enabled": false}` for off and omits the
611
+ * key entirely on an unprotected branch, so a reader that coerced the object
612
+ * itself would read the `false` case as truthy. Absent stays `null`: the
613
+ * payload did not say, and "did not say" is not "off".
614
+ */
615
+ function conversationResolutionFrom(d: Record<string, any>): boolean | null {
616
+ const e = d.required_conversation_resolution?.enabled;
617
+ return typeof e === "boolean" ? e : null;
618
+ }
619
+
542
620
  /** The `owner/name` this tree pushes to, for the probe to ask about. */
543
621
  export function protectionSubject(root: string): string | null {
544
622
  return originSlug(root);
@@ -581,6 +659,7 @@ export function readPushCi(root: string, contexts: string[], branch: string): Pu
581
659
 
582
660
  const unreadable: string[] = [];
583
661
  const pushContexts = new Set<string>();
662
+ const restricted = new Set<string>();
584
663
  for (const name of entries) {
585
664
  let text: string;
586
665
  try {
@@ -593,6 +672,7 @@ export function readPushCi(root: string, contexts: string[], branch: string): Pu
593
672
  }
594
673
  if (!runsOnPushTo(text, branch)) continue;
595
674
  for (const job of jobContextNames(text)) pushContexts.add(job);
675
+ for (const job of eventRestrictedContexts(text)) restricted.add(job);
596
676
  }
597
677
 
598
678
  if (unreadable.length > 0) {
@@ -603,20 +683,79 @@ export function readPushCi(root: string, contexts: string[], branch: string): Pu
603
683
  }
604
684
 
605
685
  return {
606
- onPush: contexts.filter(c => pushContexts.has(c)),
607
- missing: contexts.filter(c => !pushContexts.has(c)),
686
+ // A restricted context is in NEITHER of the first two lists. `onPush`
687
+ // would clear the precondition with a run that throws; `missing` would
688
+ // print "add a push trigger", which is the change that produced it.
689
+ onPush: contexts.filter(c => pushContexts.has(c) && !restricted.has(c)),
690
+ missing: contexts.filter(c => !pushContexts.has(c) && !restricted.has(c)),
691
+ cannotRunOnPush: contexts.filter(c => restricted.has(c)),
608
692
  unmeasured: null,
609
693
  };
610
694
  }
611
695
 
612
- function unmeasuredPushCi(why: string): PushCiReading {
696
+ /**
697
+ * The refusal shape for a push-CI reading that could not be taken.
698
+ *
699
+ * Exported since #1503 so `lib/conformity.ts` stops hand-building the same
700
+ * object literal: two spellings of one refusal are two deciders, and the
701
+ * inline one silently lacked `cannotRunOnPush` the moment the field existed.
702
+ */
703
+ export function unmeasuredPushCi(why: string): PushCiReading {
613
704
  return {
614
705
  onPush: [],
615
706
  missing: [],
707
+ cannotRunOnPush: [],
616
708
  unmeasured: `UNMEASURED push-CI: ${why}.`,
617
709
  };
618
710
  }
619
711
 
712
+ /**
713
+ * Actions that reject a `push` event at their own entry point — #1503.
714
+ *
715
+ * A closed set in SOURCE, never config and never an allowlist a repository
716
+ * can append to. The issue names why: a list anybody can extend turns the
717
+ * refusal into an opt-out, and the first thing a blocked operator would add
718
+ * is whichever context is blocking them.
719
+ *
720
+ * `anthropics/claude-code-action` is the measured instance. At the SHA this
721
+ * repository pins, `src/github/context.ts` throws `Unsupported event type`
722
+ * for anything outside `pull_request`, `issue_comment`, `issues`, `schedule`
723
+ * and `workflow_dispatch`. So a job running it under `on: push` produces a
724
+ * run that fails immediately and reviews nothing — it can never go red for
725
+ * the semantic conflict `strict: false` is traded against.
726
+ *
727
+ * Adding a row here is a source change with a review, and it needs the same
728
+ * evidence this one has: the line in the action that rejects the event.
729
+ */
730
+ export const EVENT_RESTRICTED_ACTIONS = ["anthropics/claude-code-action"] as const;
731
+
732
+ /**
733
+ * The context names of jobs that run an {@link EVENT_RESTRICTED_ACTIONS}
734
+ * action, judged from the same per-job walk {@link jobContextNames} does.
735
+ *
736
+ * Same walk deliberately: two walks of the `jobs:` block would be two
737
+ * deciders for "where does this job end", and a job whose context name one
738
+ * of them resolved differently would be restricted under one and not the
739
+ * other (`.claude/rules/checks-must-be-able-to-fail.md`).
740
+ */
741
+ export function eventRestrictedContexts(text: string): string[] {
742
+ return jobBlocks(text)
743
+ .filter(j => j.body.some(line => EVENT_RESTRICTED_ACTIONS.some(a => usesAction(line, a))))
744
+ .map(j => j.context);
745
+ }
746
+
747
+ /** `uses: <action>@<ref>` on this line, matching the action and not a prefix. */
748
+ function usesAction(line: string, action: string): boolean {
749
+ // The trailing `# v1` is not decoration — every pinned action in this repo
750
+ // carries one, and a `\s*$` anchor that forgets it matches nothing at all.
751
+ const m = line.trim().match(/^-?\s*uses\s*:\s*(["']?)([^"'\s]+)\1\s*(?:#.*)?$/);
752
+ if (!m) return false;
753
+ const ref = m[2];
754
+ // `owner/name@sha` and `owner/name/sub@sha` both count; `owner/name-2` does
755
+ // not, which is the prefix a bare `startsWith` would wrongly accept.
756
+ return ref === action || ref.startsWith(`${action}@`) || ref.startsWith(`${action}/`);
757
+ }
758
+
620
759
  // ── The small amount of YAML this needs ─────────────────
621
760
  //
622
761
  // A real parser is not pulled in for this. The two questions are "is there a
@@ -768,12 +907,35 @@ export function runsOnPushTo(text: string, branch: string): boolean {
768
907
  * would call a configured repo unconfigured.
769
908
  */
770
909
  export function jobContextNames(text: string): string[] {
910
+ return jobBlocks(text).map(j => j.context);
911
+ }
912
+
913
+ /** One job of a workflow: the context name it reports, and its own lines. */
914
+ export interface JobBlock {
915
+ /** `name:` when the job has one, its key otherwise. */
916
+ context: string;
917
+ /** The job's significant lines, excluding the key line itself. */
918
+ body: string[];
919
+ }
920
+
921
+ /**
922
+ * Every job in a workflow, with the context name each reports.
923
+ *
924
+ * The single decider for *where a job ends and what it is called* — #1503.
925
+ * {@link jobContextNames} and {@link eventRestrictedContexts} both read it
926
+ * rather than walking `jobs:` themselves, because two walks would be two
927
+ * deciders answering the same question: a job whose extent they resolved
928
+ * differently would be restricted under one and named under the other, and
929
+ * no behavioural test could tell which of them was live
930
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
931
+ */
932
+ export function jobBlocks(text: string): JobBlock[] {
771
933
  const lines = significantLines(text);
772
934
  const jobs = topLevelBlock(lines, ["jobs"]);
773
935
  if (!jobs || jobs.body.length === 0) return [];
774
936
  const base = Math.min(...jobs.body.map(indentOf));
775
937
 
776
- const names: string[] = [];
938
+ const out: JobBlock[] = [];
777
939
  for (let i = 0; i < jobs.body.length; i++) {
778
940
  if (indentOf(jobs.body[i]) !== base) continue;
779
941
  const key = jobs.body[i].trim().match(/^(["']?)([A-Za-z_][A-Za-z0-9_-]*)\1\s*:\s*$/);
@@ -784,7 +946,235 @@ export function jobContextNames(text: string): string[] {
784
946
  block.push(jobs.body[j]);
785
947
  }
786
948
  const name = childBlock(block, "name");
787
- names.push(name?.header ? unquote(name.header) : key[2]);
949
+ out.push({ context: name?.header ? unquote(name.header) : key[2], body: block });
950
+ }
951
+ return out;
952
+ }
953
+
954
+ // ── CRC-C3: a finding blocks merge until somebody dispositions it ──
955
+
956
+ /**
957
+ * The step id the generated AI review uses to open one review thread per
958
+ * finding — **re-exported from the generator that writes it**, never spelled
959
+ * again here (ai-review review round 1 of #1858).
960
+ *
961
+ * The first version of this declared its own `"ai-review-threads"` literal
962
+ * beside a comment claiming it was "spelled once". It was spelled twice:
963
+ * `AI_REVIEW_THREADS_STEP_ID` in `lib/scaffold/ai-review-step.ts` is what
964
+ * actually gets written into the generated workflow's `id:` line, and the two
965
+ * agreed by coincidence rather than by construction.
966
+ *
967
+ * That is the *two deciders that agree* shape, and it fails in the direction
968
+ * that matters: rename the step in the generator alone and `readThreadProducer`
969
+ * stops matching, `produces` goes false, `readFindingDisposition` takes the
970
+ * PASS branch below — and PROTECT-2 silently clears on a tree that still opens
971
+ * a review thread per finding. The gate built to catch a silent regression
972
+ * would have regressed silently.
973
+ *
974
+ * It is the PRECONDITION the whole check turns on: a repo that does not
975
+ * produce threads has nothing for `required_conversation_resolution` to gate,
976
+ * and refusing there would tell an operator to configure a setting that would
977
+ * do nothing for them.
978
+ */
979
+ export const THREAD_PRODUCER_STEP_ID = AI_REVIEW_THREADS_STEP_ID;
980
+
981
+ /** Whether this tree opens a review thread per finding. */
982
+ export interface ThreadProducerReading {
983
+ /** True only when a workflow was read and declares the producing step. */
984
+ produces: boolean;
985
+ /** The workflow file it was found in, for the reason string. */
986
+ where: string | null;
987
+ /**
988
+ * Non-null when the workflows could not be read, so `produces: false` means
989
+ * nothing. An unread directory reporting "no producer" would clear this
990
+ * check vacuously on every tree whose `.github/` is unreadable.
991
+ */
992
+ unmeasured: string | null;
993
+ }
994
+
995
+ export function readThreadProducer(root: string): ThreadProducerReading {
996
+ const dir = join(root, ".github", "workflows");
997
+ const unread = (why: string): ThreadProducerReading => ({ produces: false, where: null, unmeasured: why });
998
+
999
+ let entries: string[];
1000
+ try {
1001
+ if (!statSync(dir).isDirectory()) return unread(`${dir} is not a directory`);
1002
+ entries = readdirSync(dir).filter(n => WORKFLOW_EXT.test(n)).sort();
1003
+ } catch (e) {
1004
+ const why = (e as NodeJS.ErrnoException).code === "ENOENT"
1005
+ ? `${dir} does not exist`
1006
+ : `${dir} is unreadable — ${(e as Error).message}`;
1007
+ return unread(why);
1008
+ }
1009
+
1010
+ const unreadable: string[] = [];
1011
+ for (const name of entries) {
1012
+ let text: string;
1013
+ try {
1014
+ text = readFileSync(join(dir, name), "utf-8");
1015
+ } catch (e) {
1016
+ unreadable.push(`${name} (${(e as Error).message})`);
1017
+ continue;
1018
+ }
1019
+ // The step ID in a declaring position, not the string anywhere. The
1020
+ // workflow mentions `ai-review-threads` in a comment and in three env
1021
+ // var values; matching those would report a producer in a tree that had
1022
+ // deleted the step and left the prose.
1023
+ // `- id: x` is as legal as `id: x` — a step may lead with any key, and
1024
+ // the generator only happens to lead with `name:`. The first spelling of
1025
+ // this required the line to BEGIN with whitespace then `id:`, so a step
1026
+ // written the other way read as no producer at all. Found by a fixture
1027
+ // that spelled it the legal second way (#1858).
1028
+ //
1029
+ // `escapeRegex`, because the id is not this file's value to trust. It is
1030
+ // the generator's constant, imported — which is the whole point of the
1031
+ // re-export above — and a rename to anything containing `.`, `+` or `(`
1032
+ // would change what this pattern MEANS rather than throw. A `.` in the id
1033
+ // would quietly match any character. Round 2 of #1858; the helper was
1034
+ // already in use a few dozen lines up for exactly this reason.
1035
+ if (new RegExp(`^\\s*(?:-\\s*)?id:\\s*["']?${escapeRegex(THREAD_PRODUCER_STEP_ID)}["']?\\s*$`, "m").test(text)) {
1036
+ return { produces: true, where: name, unmeasured: null };
1037
+ }
788
1038
  }
789
- return names;
1039
+
1040
+ if (unreadable.length > 0) {
1041
+ return unread(
1042
+ `${unreadable.length} workflow file(s) could not be read — ${unreadable.join(", ")} — ` +
1043
+ "so whether any opens a review thread is unestablished",
1044
+ );
1045
+ }
1046
+ return { produces: false, where: null, unmeasured: null };
1047
+ }
1048
+
1049
+ /** One reading of whether a finding can be left undispositioned. */
1050
+ export interface DispositionReading {
1051
+ verdict: ProtectionVerdict;
1052
+ /** A sentence naming why, in every branch including PASS. */
1053
+ reason: string;
1054
+ /** Empty on PASS and on UNMEASURED — nothing to remedy, or nothing established. */
1055
+ remedy: string;
1056
+ }
1057
+
1058
+ /**
1059
+ * CRC-C3 — can a pull request merge with a finding nobody answered?
1060
+ *
1061
+ * `required_conversation_resolution` is GitHub's own implementation of it,
1062
+ * and the only protection setting that can read a review thread. It is
1063
+ * therefore the only one that can tell *this finding was answered* from
1064
+ * *nobody looked*.
1065
+ *
1066
+ * ## Why this check exists rather than a line in the spec
1067
+ *
1068
+ * It was ON and it silently went OFF. `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`
1069
+ * records it applied on 2026-10-23 and read `true` from the API on
1070
+ * 2026-10-25, and three pull requests behaved accordingly through 2026-10-27:
1071
+ * each sat at `BLOCKED` on one unresolved thread with every required check
1072
+ * green, and each flipped to `CLEAN` when that thread was resolved — same
1073
+ * head, no push, no re-run.
1074
+ *
1075
+ * On 2026-11-07 the same field read `false`, and #1857 merged carrying five
1076
+ * unresolved threads, two of them not even outdated. **Nothing in the tree
1077
+ * read the field**, so thirteen days passed with the spec recording a setting
1078
+ * that was not in force. The protection endpoint's `PUT` replaces the whole
1079
+ * object, so any update that omits the field turns it off and returns 200 —
1080
+ * there is no event to notice and no error to read.
1081
+ *
1082
+ * That is the shape this repository keeps paying for: a documented status
1083
+ * that nothing re-reads. The remedy is not a better sentence in the spec.
1084
+ *
1085
+ * ## No branch reaches PASS by not finding a problem
1086
+ *
1087
+ * A tree that opens no review threads PASSES, and says that is why — there is
1088
+ * nothing for the setting to gate, and demanding it there would be advice
1089
+ * that changes nothing. Everything unread is UNMEASURED: the protection
1090
+ * endpoint needs admin and the default Actions token has none, so UNMEASURED
1091
+ * is the ordinary outcome in a consumer's CI and must never read as clean.
1092
+ */
1093
+ export function readFindingDisposition(
1094
+ facts: ProtectionFacts,
1095
+ producer: ThreadProducerReading,
1096
+ ): DispositionReading {
1097
+ // **The producer reading comes FIRST, and the order is the finding** (ai-review
1098
+ // round 1 of #1858). A tree with no thread producer passes whatever the
1099
+ // protection says, because nothing depends on reading it — so asking about
1100
+ // protection before asking whether the question applies made the answer
1101
+ // depend on a fact that cannot change it.
1102
+ //
1103
+ // It is not a tidiness point. The two conditions it put in the wrong order
1104
+ // are BOTH the ordinary state of a consumer: most have not adopted
1105
+ // `ai-review-threads`, and most run with the default `GITHUB_TOKEN`, which
1106
+ // has no admin and so cannot read protection at all. Every one of them would
1107
+ // have got `UNMEASURED: this repo's protection could not be read` on every
1108
+ // run — a warning about a setting that would do nothing for them if they
1109
+ // set it. That is how a gate gets switched off.
1110
+ if (producer.unmeasured) {
1111
+ return {
1112
+ verdict: "UNMEASURED",
1113
+ reason:
1114
+ `UNMEASURED: ${producer.unmeasured}. With no reading of whether anything opens a review ` +
1115
+ "thread, the setting's relevance is unestablished and the protection reading alone " +
1116
+ "cannot decide it.",
1117
+ remedy: "",
1118
+ };
1119
+ }
1120
+ if (!producer.produces) {
1121
+ return {
1122
+ verdict: "PASS",
1123
+ reason:
1124
+ "no workflow in this tree declares a step that opens a review thread per finding, so " +
1125
+ "there is nothing for required_conversation_resolution to gate and requiring it here " +
1126
+ "would change nothing.",
1127
+ remedy: "",
1128
+ };
1129
+ }
1130
+ // Only now does protection matter: something opens threads, so whether they
1131
+ // have to be answered is a live question.
1132
+ if (facts.unreadable) {
1133
+ return {
1134
+ verdict: "UNMEASURED",
1135
+ reason:
1136
+ `UNMEASURED: this repo's protection could not be read — ${facts.unreadable}. Whether a ` +
1137
+ "finding can be left undispositioned is unestablished, which is not the same as fine.",
1138
+ remedy: "",
1139
+ };
1140
+ }
1141
+ if (facts.conversationResolution === null) {
1142
+ return {
1143
+ verdict: "UNMEASURED",
1144
+ reason:
1145
+ "UNMEASURED: the protection payload said nothing about " +
1146
+ "required_conversation_resolution, so it is unestablished rather than off. An absent " +
1147
+ "key and a false one are different facts.",
1148
+ remedy: "",
1149
+ };
1150
+ }
1151
+ if (facts.conversationResolution) {
1152
+ return {
1153
+ verdict: "PASS",
1154
+ reason:
1155
+ `required_conversation_resolution is on, and ${producer.where ?? "a workflow"} opens a ` +
1156
+ "review thread per finding — so a finding nobody answered blocks the merge.",
1157
+ remedy: "",
1158
+ };
1159
+ }
1160
+ return {
1161
+ verdict: "FAIL",
1162
+ reason:
1163
+ `${producer.where ?? "a workflow"} opens a review thread per finding and ` +
1164
+ "required_conversation_resolution is OFF, so a pull request merges with every one of them " +
1165
+ "unanswered. The review runs, writes its findings onto the diff, and gates nothing — " +
1166
+ "which reads as a reviewed change and is not one.",
1167
+ remedy:
1168
+ "Require conversation resolution before merging on this branch. It is a setting, not " +
1169
+ "engineering. **A branch with NO protection at all reaches this same verdict** — nothing " +
1170
+ "is requiring anything, so nothing can hold a merge for an unanswered finding — and there " +
1171
+ "the fix is to create the protection rather than amend it. Either way, write it with a " +
1172
+ "FULL PUT: `PUT /repos/{owner}/{repo}/branches/{branch}/protection` replaces the whole " +
1173
+ "object and requires required_status_checks, enforce_admins, " +
1174
+ "required_pull_request_reviews and restrictions to be present even when you are only " +
1175
+ "turning one thing on — so read the current protection first and restate every field you " +
1176
+ "want to keep. An update that omits a field silently disables it, which is how this regressed " +
1177
+ "once already. Clearing a false positive is a documented step, not a judgement call — " +
1178
+ "reference/clearing-a-false-positive.md.",
1179
+ };
790
1180
  }
package/lib/conformity.ts CHANGED
@@ -36,11 +36,15 @@ import {
36
36
  } from "./behavioral-cache";
37
37
  import { tryLoadRungateConfig } from "./config-loader";
38
38
  import {
39
+ type ProtectionFacts,
39
40
  type ProtectionProbe,
40
41
  githubProtectionProbe,
41
42
  protectionSubject,
43
+ readFindingDisposition,
42
44
  readMergeSerialisation,
43
45
  readPushCi,
46
+ readThreadProducer,
47
+ unmeasuredPushCi,
44
48
  } from "./branch-protection";
45
49
  import { stripJsComments } from "./strip-js-comments";
46
50
  import { remedyMessage } from "./check-remedy";
@@ -4973,6 +4977,24 @@ export function runBranchProtectionValidation(
4973
4977
  const probe = opts.probe ?? githubProtectionProbe;
4974
4978
  const subject = opts.subject ?? protectionSubject;
4975
4979
 
4980
+ /**
4981
+ * ONE protection reading per run, shared by both checks (#1858 round 4).
4982
+ *
4983
+ * PROTECT-2 called `probe` a second time for the same slug. That is three
4984
+ * more admin-scoped GETs per run, and worse than the cost: **two readings
4985
+ * of one branch inside one run can disagree.** The protection endpoint
4986
+ * 403s as its ORDINARY outcome on a consumer's default token, and a
4987
+ * secondary rate limit trips on the second round-trip rather than the
4988
+ * first — so a run could report PROTECT-1 clean and PROTECT-2 UNMEASURED
4989
+ * about the identical branch, with nothing in the output saying which
4990
+ * reading to believe.
4991
+ *
4992
+ * That is the same defect #1852 closed one lane over, reintroduced here by
4993
+ * the check that was written to catch a different instance of it.
4994
+ */
4995
+ let protectionOnce: Promise<ProtectionFacts> | null = null;
4996
+ const factsFor = (slug: string): Promise<ProtectionFacts> => (protectionOnce ??= probe(slug));
4997
+
4976
4998
  describe("Branch protection (#909)", () => {
4977
4999
  test("PROTECT-1: merging one PR does not invalidate every other open PR", async () => {
4978
5000
  const slug = subject(root);
@@ -4988,12 +5010,12 @@ export function runBranchProtectionValidation(
4988
5010
  return;
4989
5011
  }
4990
5012
 
4991
- const facts = await probe(slug);
5013
+ const facts = await factsFor(slug);
4992
5014
  // Read against the branch the FACTS are about. Defaulting to "main"
4993
5015
  // here would answer a question about a branch the repo may not protect.
4994
5016
  const pushCi = facts.branch
4995
5017
  ? readPushCi(root, facts.contexts, facts.branch)
4996
- : { onPush: [], missing: [], unmeasured: "UNMEASURED push-CI: the default branch is unknown, so no trigger could be matched against it." };
5018
+ : unmeasuredPushCi("the default branch is unknown, so no trigger could be matched against it");
4997
5019
  const reading = readMergeSerialisation(facts, pushCi);
4998
5020
 
4999
5021
  if (reading.verdict === "UNMEASURED") {
@@ -5020,6 +5042,77 @@ export function runBranchProtectionValidation(
5020
5042
  // written against the value rather than against the narrowing.
5021
5043
  expect(reading.verdict as string, message).toBe("PASS");
5022
5044
  });
5045
+
5046
+ /**
5047
+ * PROTECT-2 (#1650, CRC-C3) — a finding nobody answered blocks the merge.
5048
+ *
5049
+ * The same probe and the same facts object as PROTECT-1, one question
5050
+ * further on: `required_conversation_resolution`. It is the only
5051
+ * protection setting that can read a review thread, so it is the only one
5052
+ * that can tell *this finding was answered* from *nobody looked*.
5053
+ *
5054
+ * **It exists because the setting regressed in silence.** On this repo it
5055
+ * was applied 2026-10-23, read `true` 2026-10-25, and observably gating
5056
+ * three pull requests through 2026-10-27. On 2026-11-07 it read `false`
5057
+ * and #1857 merged with five unresolved threads. The field had no reader
5058
+ * anywhere in the tree, so the spec went on recording it as applied for
5059
+ * thirteen days. `lib/branch-protection.ts` carries the readings.
5060
+ *
5061
+ * FAILS, like PROTECT-1, and for the same reason: the thing that did not
5062
+ * work was writing it down.
5063
+ */
5064
+ test("PROTECT-2: a pull request cannot merge with a finding nobody answered", async () => {
5065
+ const slug = subject(root);
5066
+ if (!slug) {
5067
+ addFinding({
5068
+ ruleId: "PROTECT-2",
5069
+ severity: "WARN",
5070
+ file: "",
5071
+ message:
5072
+ "UNMEASURED: this tree's origin remote names no owner/name, so there is no repo to " +
5073
+ "read protection for. Nothing was checked, which is not the same as nothing being wrong.",
5074
+ });
5075
+ return;
5076
+ }
5077
+
5078
+ // **No short-circuit here, and the battery is why.** The first draft of
5079
+ // this returned early when `readThreadProducer` found no producer, on
5080
+ // the reasoning that round 1 applied inside `readFindingDisposition`:
5081
+ // do not consult a fact that cannot change the answer. Mutating that
5082
+ // branch away reddened NOTHING — predicted 1, observed 0.
5083
+ //
5084
+ // It was dead, and `factsFor` is why: PROTECT-1 has already taken the
5085
+ // reading on every path that reaches here, so the memo returns it and
5086
+ // no request is saved. Keeping the branch would have shipped a line
5087
+ // whose removal no case can observe, which is the shape this session
5088
+ // spent four rounds finding elsewhere
5089
+ // (`.claude/rules/checks-must-be-able-to-fail.md`).
5090
+ const producer = readThreadProducer(root);
5091
+ const facts = await factsFor(slug);
5092
+ const disposition = readFindingDisposition(facts, producer);
5093
+
5094
+ if (disposition.verdict === "UNMEASURED") {
5095
+ addFinding({ ruleId: "PROTECT-2", severity: "WARN", file: "", message: disposition.reason });
5096
+ return;
5097
+ }
5098
+ if (disposition.verdict === "PASS") return;
5099
+
5100
+ addFinding({
5101
+ ruleId: "PROTECT-2",
5102
+ severity: "FAIL",
5103
+ file: "",
5104
+ message: `${disposition.reason}\n\nREMEDY: ${disposition.remedy}`,
5105
+ // Reads. Never writes — the same line PROTECT-1 holds. A fixCommand
5106
+ // that PUT a protection payload would be the harness silently
5107
+ // rewriting a repository's security settings, and the operator's next
5108
+ // read of their own config would be a reading of what a tool decided.
5109
+ fixCommand: `gh api repos/${facts.slug}/branches/${facts.branch ?? "main"}/protection -q .required_conversation_resolution`,
5110
+ });
5111
+ // Widened for the same reason as PROTECT-1: control flow has narrowed
5112
+ // `verdict` to "FAIL", so the comparison typechecks as a contradiction
5113
+ // and reads as dead. It is what turns the finding into a red suite.
5114
+ expect(disposition.verdict as string, `${disposition.reason}\n\nREMEDY: ${disposition.remedy}`).toBe("PASS");
5115
+ });
5023
5116
  });
5024
5117
  }
5025
5118