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.
- package/README.md +82 -0
- package/gates/.gate-salt +1 -1
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +50 -5
- package/lib/board-flow.ts +235 -0
- package/lib/board-lane-health.ts +381 -0
- package/lib/board-mirror.ts +53 -35
- package/lib/board-ready-fanout.ts +56 -13
- package/lib/board-ready-rule.ts +545 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/conformity.ts +95 -2
- package/lib/filing-compliance.ts +367 -0
- package/lib/finding-arbiter.ts +79 -5
- package/lib/generators/agents-md.ts +149 -0
- package/lib/github.ts +79 -0
- package/lib/graphql-cursor.ts +80 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +33 -3
- package/lib/issue-file-overlap.ts +340 -0
- package/lib/issue-filing-gate.ts +173 -8
- package/lib/issue-repair.ts +13 -9
- package/lib/issue-shape.ts +196 -0
- package/lib/scaffold/ai-review-findings.ts +9 -1
- package/lib/scaffold/ai-review-step.ts +35 -1
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +34 -11
- package/lib/spec-placement.ts +108 -0
- package/lib/stage-ladder.ts +28 -3
- package/lib/work-status.ts +423 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/board-mirror.ts +221 -8
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-spec.ts +79 -1
package/lib/branch-protection.ts
CHANGED
|
@@ -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
|
-
|
|
607
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
:
|
|
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
|
|