rungate 0.8.10 → 0.8.13
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/bin/rungate.ts +14 -0
- package/gates/.gate-salt +1 -1
- package/lib/board-ready-fanout.ts +237 -0
- package/lib/config-readers.ts +30 -0
- package/lib/github.ts +136 -15
- package/lib/harness-identity.ts +56 -0
- package/lib/scaffold/ai-review-findings.ts +181 -2
- package/lib/scaffold/ai-review-step.ts +55 -4
- package/package.json +1 -1
- package/scripts/board-conformance.ts +65 -2
- package/scripts/board-snapshot.ts +10 -1
- package/scripts/plan-issues.ts +23 -3
package/bin/rungate.ts
CHANGED
|
@@ -14,9 +14,23 @@ import { existsSync } from "fs";
|
|
|
14
14
|
import { dirname, join, resolve } from "path";
|
|
15
15
|
import { fileURLToPath } from "url";
|
|
16
16
|
import { CLI_COMMANDS, helpText, runCommandScript } from "../lib/cli-commands";
|
|
17
|
+
import { harnessVersionLine } from "../lib/harness-identity";
|
|
17
18
|
|
|
18
19
|
const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
19
20
|
|
|
21
|
+
// Say which version is running, before anything else can fail.
|
|
22
|
+
//
|
|
23
|
+
// On STDERR, and that is the whole design. `ai-review.yml` captures the
|
|
24
|
+
// adjudicator with `2>&1`, so this reaches the CI log either way and nothing
|
|
25
|
+
// is lost by keeping it off stdout — while stdout stays what a caller can
|
|
26
|
+
// parse. `--version` in particular exists to be read by a machine and must
|
|
27
|
+
// remain exactly one line.
|
|
28
|
+
//
|
|
29
|
+
// Emitted for every invocation including `--help` and an unknown command: the
|
|
30
|
+
// runs worth attributing are the ones that went wrong, and a banner that
|
|
31
|
+
// skips the failure paths is absent exactly when it is wanted.
|
|
32
|
+
console.error(harnessVersionLine(PACKAGE_ROOT));
|
|
33
|
+
|
|
20
34
|
const [name, ...rest] = process.argv.slice(2);
|
|
21
35
|
|
|
22
36
|
if (!name || name === "--help" || name === "-h" || name === "help") {
|
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
747398b3ddaddadd72ae597e21f050587654bc584d2f72286d66b4c2a921e001
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* When a blocking issue closes, which of the issues it was blocking should
|
|
3
|
+
* move to Ready — and which should be left exactly where they are.
|
|
4
|
+
*
|
|
5
|
+
* #1744. Moves Claim 7, whose third falsification reads *"a board state
|
|
6
|
+
* reachable only by someone running a command by hand"*. Ready is that today:
|
|
7
|
+
* `board-mirror --ready --write` is the only thing that writes it, and a
|
|
8
|
+
* person has to remember.
|
|
9
|
+
*
|
|
10
|
+
* ## Why an Action at all
|
|
11
|
+
*
|
|
12
|
+
* Researched against docs.github.com on 2026-11-03. GitHub has no built-in
|
|
13
|
+
* workflow keyed on dependencies; `actions/add-to-project` takes only
|
|
14
|
+
* `project-url`, `github-token`, `labeled` and `label-operator` and **cannot
|
|
15
|
+
* set a field**. GitHub's own documented answer for this is a self-written
|
|
16
|
+
* Action driving `updateProjectV2ItemFieldValue`.
|
|
17
|
+
*
|
|
18
|
+
* There is also **no "became unblocked" event**. `issue_dependencies` exists
|
|
19
|
+
* as a webhook but is not a valid Actions `on:` trigger, and
|
|
20
|
+
* `blocked_by_removed` fires when somebody unlinks a dependency, not when the
|
|
21
|
+
* blocker closes. So the trigger is `issues: [closed]` and the fan-out walks
|
|
22
|
+
* that issue's `blocking` list. No cron — a schedule is the thing this exists
|
|
23
|
+
* to remove.
|
|
24
|
+
*
|
|
25
|
+
* GitHub roadmap **#1336 "Granular issue status"** is in public preview and
|
|
26
|
+
* would make this module dead code. That is a reason to keep it small, not a
|
|
27
|
+
* reason to wait.
|
|
28
|
+
*
|
|
29
|
+
* ## What this file deliberately does NOT do
|
|
30
|
+
*
|
|
31
|
+
* **It does not decide readiness.** `isReady` does, and it carries the
|
|
32
|
+
* phase-frontier rule that stopped the Ready lane holding 36 of 46 open
|
|
33
|
+
* issues. A second decider here would agree with it on every input anybody
|
|
34
|
+
* thought to test, so no behavioural case could tell which was live and a
|
|
35
|
+
* mutation of either would leave the other holding the case up. `BR-7`
|
|
36
|
+
* asserts the agreement across a 48-row grid rather than trusting the import.
|
|
37
|
+
*
|
|
38
|
+
* **It does not add anything to the board.** Membership is `board-mirror`'s.
|
|
39
|
+
* An Action that added items would make the board's contents depend on which
|
|
40
|
+
* issues happened to close.
|
|
41
|
+
*/
|
|
42
|
+
import { isReady } from "./board-mirror";
|
|
43
|
+
|
|
44
|
+
/** One issue that the closed blocker was blocking. */
|
|
45
|
+
export interface Dependent {
|
|
46
|
+
readonly number: number;
|
|
47
|
+
/** `OPEN` or `CLOSED`, as GraphQL spells it. */
|
|
48
|
+
readonly state: string;
|
|
49
|
+
readonly phase: number | null;
|
|
50
|
+
/**
|
|
51
|
+
* OPEN blockers only — the lifetime count never goes back down.
|
|
52
|
+
*
|
|
53
|
+
* **`null` means the dependency summary could not be read**, which is not
|
|
54
|
+
* the same as zero. `issueDependenciesSummary` is absent on a response the
|
|
55
|
+
* token was not scoped for, and `?? 0` turned that into "nothing is
|
|
56
|
+
* blocking it" — a fail-open that moves a genuinely blocked issue to
|
|
57
|
+
* Ready. Caught in review of #1747.
|
|
58
|
+
*/
|
|
59
|
+
readonly blockedByOpen: number | null;
|
|
60
|
+
/**
|
|
61
|
+
* **`null` means the assignee count could not be read**, exactly as above.
|
|
62
|
+
* `?? 0` here says "nobody has claimed it", and that is the direction that
|
|
63
|
+
* MOVES — an issue somebody is already working on lands in Ready. The
|
|
64
|
+
* sibling field was fixed for this and this one was left; caught in review
|
|
65
|
+
* of #1747, round 7.
|
|
66
|
+
*/
|
|
67
|
+
readonly assignees: number | null;
|
|
68
|
+
/** Is this issue on the board at all? Membership is `board-mirror`'s. */
|
|
69
|
+
readonly onBoard: boolean;
|
|
70
|
+
/**
|
|
71
|
+
* The board column, or `null` when the item has no Status VALUE.
|
|
72
|
+
*
|
|
73
|
+
* Not the same question as `onBoard`, and the two were one field until
|
|
74
|
+
* review of #1747 round 6. GraphQL returns a
|
|
75
|
+
* `ProjectV2ItemFieldSingleSelectValue` node only for a field that already
|
|
76
|
+
* has a value, so an item added to the project and never given a Status
|
|
77
|
+
* returns no node — producing the same `null` as an issue that is not on
|
|
78
|
+
* the board. One of those means "board-mirror owns this, leave it"; the
|
|
79
|
+
* other means "it is here and I cannot see where".
|
|
80
|
+
*/
|
|
81
|
+
readonly boardStatus: string | null;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export type FanoutDecision =
|
|
85
|
+
| { readonly number: number; readonly move: true }
|
|
86
|
+
| { readonly number: number; readonly move: false; readonly why: string };
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Why `isReady` said no, for the log.
|
|
90
|
+
*
|
|
91
|
+
* **This explains a verdict; it never produces one.** It is only ever called
|
|
92
|
+
* after `isReady` has already returned false, so a wrong or incomplete reason
|
|
93
|
+
* costs a confusing log line and cannot move an issue. Keeping that ordering
|
|
94
|
+
* is what stops it becoming the second decider described above.
|
|
95
|
+
*/
|
|
96
|
+
function whyNotReady(d: Dependent, frontier: number | null): string {
|
|
97
|
+
if (d.state !== "OPEN") return `the issue is ${d.state}`;
|
|
98
|
+
if (d.blockedByOpen === null) return "UNMEASURED — the dependency summary could not be read";
|
|
99
|
+
if (d.blockedByOpen > 0) {
|
|
100
|
+
return `${d.blockedByOpen} open blocker${d.blockedByOpen === 1 ? "" : "s"} remain`;
|
|
101
|
+
}
|
|
102
|
+
if (d.assignees === null) return "UNMEASURED — the assignee count could not be read";
|
|
103
|
+
if (d.assignees > 0) return "somebody has claimed it";
|
|
104
|
+
if (frontier === null) return "no phase has open work, so nothing is next";
|
|
105
|
+
if (d.phase === null) return "no phase milestone — it serves no criterion (ADR-003)";
|
|
106
|
+
if (d.phase !== frontier) return `phase ${d.phase} is behind the frontier at phase ${frontier}`;
|
|
107
|
+
return "isReady said no and this reason list did not anticipate it";
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* One decision per dependent. Writes nothing; the caller performs the moves.
|
|
112
|
+
*/
|
|
113
|
+
export function fanoutDecisions(
|
|
114
|
+
dependents: readonly Dependent[],
|
|
115
|
+
frontier: number | null,
|
|
116
|
+
readyColumn: string,
|
|
117
|
+
): FanoutDecision[] {
|
|
118
|
+
return dependents.map((d): FanoutDecision => {
|
|
119
|
+
if (!d.onBoard) {
|
|
120
|
+
return { number: d.number, move: false, why: "not on the board — board-mirror owns membership" };
|
|
121
|
+
}
|
|
122
|
+
// On the board, and no Status value. Distinct from the line above on
|
|
123
|
+
// purpose: the caller resolves the Status FIELD ID from the item's own
|
|
124
|
+
// value node, so an item that has never had a Status has nothing to
|
|
125
|
+
// write through. Saying "not on the board" sent the reader to
|
|
126
|
+
// board-mirror to add an item that was already there.
|
|
127
|
+
if (d.boardStatus === null) {
|
|
128
|
+
return {
|
|
129
|
+
number: d.number,
|
|
130
|
+
move: false,
|
|
131
|
+
why:
|
|
132
|
+
"UNMEASURED — it is on the board with no Status value, so there is no Status field id " +
|
|
133
|
+
"to write through. This is NOT absent from the board.",
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
if (d.boardStatus === readyColumn) {
|
|
137
|
+
return { number: d.number, move: false, why: `already ${readyColumn}` };
|
|
138
|
+
}
|
|
139
|
+
// An unreadable blocker count is UNMEASURED, and UNMEASURED never moves.
|
|
140
|
+
// It cannot be handed to `isReady`, whose parameter is a number and whose
|
|
141
|
+
// honest answer here does not exist — the question is unanswerable, not
|
|
142
|
+
// answered false. Refusing before the decider is what keeps `isReady` the
|
|
143
|
+
// only thing that says yes.
|
|
144
|
+
if (d.blockedByOpen === null || d.assignees === null) {
|
|
145
|
+
return { number: d.number, move: false, why: whyNotReady(d, frontier) };
|
|
146
|
+
}
|
|
147
|
+
const measured = { ...d, blockedByOpen: d.blockedByOpen, assignees: d.assignees };
|
|
148
|
+
if (!isReady(measured, frontier)) {
|
|
149
|
+
return { number: d.number, move: false, why: whyNotReady(d, frontier) };
|
|
150
|
+
}
|
|
151
|
+
return { number: d.number, move: true };
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** A GraphQL connection, as far as truncation is concerned. */
|
|
156
|
+
interface MaybeTruncated {
|
|
157
|
+
readonly pageInfo?: { readonly hasNextPage?: boolean } | null;
|
|
158
|
+
readonly nodes?: readonly unknown[] | null;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Which dependents had their board membership read only in part.
|
|
163
|
+
*
|
|
164
|
+
* `projectItems` and `fieldValues` are sub-selections inside a paginated
|
|
165
|
+
* list, so cursoring them costs a round trip per node and both are bounded
|
|
166
|
+
* in practice. **"Bounded in practice" is the reasoning that has been wrong
|
|
167
|
+
* four times on this day's work**, so it is not trusted: each is asked for
|
|
168
|
+
* with a `pageInfo`, and a truncated page is UNMEASURED.
|
|
169
|
+
*
|
|
170
|
+
* It matters because a Status field on page two and no Status field at all
|
|
171
|
+
* produce the same `undefined`, and one of those means "leave it alone"
|
|
172
|
+
* while the other means "I could not look".
|
|
173
|
+
*/
|
|
174
|
+
export function truncatedReadings(
|
|
175
|
+
dependents: readonly { readonly number: number; readonly projectItems?: MaybeTruncated | null }[],
|
|
176
|
+
): number[] {
|
|
177
|
+
return dependents
|
|
178
|
+
.filter(d => {
|
|
179
|
+
const items = d.projectItems;
|
|
180
|
+
if (items?.pageInfo?.hasNextPage === true) return true;
|
|
181
|
+
return (items?.nodes ?? []).some(
|
|
182
|
+
(n: any) => n?.fieldValues?.pageInfo?.hasNextPage === true,
|
|
183
|
+
);
|
|
184
|
+
})
|
|
185
|
+
.map(d => d.number);
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* May the identity that triggered this run cause a board write?
|
|
190
|
+
*
|
|
191
|
+
* The first version of this gate was an Actions `if:` reading
|
|
192
|
+
* `github.event.issue.author_association`, and review was right that it
|
|
193
|
+
* checks the wrong person: that field describes whoever OPENED the issue,
|
|
194
|
+
* never whoever closed it. The two differ in both directions and the
|
|
195
|
+
* ordinary direction is the damaging one — a maintainer closing an outside
|
|
196
|
+
* contributor's issue would have been refused, so the feature would have
|
|
197
|
+
* quietly not worked for exactly the issues most likely to come from
|
|
198
|
+
* outside.
|
|
199
|
+
*
|
|
200
|
+
* `repos/{repo}/collaborators/{actor}/permission` answers about the ACTOR.
|
|
201
|
+
* Its `permission` field is one of `admin`, `write`, `read`, `none`, and an
|
|
202
|
+
* unreadable response is `null` — which is UNMEASURED and refuses, because
|
|
203
|
+
* a permission we could not read is not a permission we were granted.
|
|
204
|
+
*/
|
|
205
|
+
export const WRITING_PERMISSIONS: readonly string[] = ["admin", "write", "maintain"];
|
|
206
|
+
|
|
207
|
+
export function actorMayWrite(permission: string | null): boolean {
|
|
208
|
+
if (permission === null) return false;
|
|
209
|
+
return WRITING_PERMISSIONS.includes(permission);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** The credential, or the reason there is no reading to report. */
|
|
213
|
+
export type CredentialReading =
|
|
214
|
+
| { readonly kind: "present"; readonly token: string }
|
|
215
|
+
| { readonly kind: "UNMEASURED"; readonly why: string };
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* `GITHUB_TOKEN` cannot write ProjectsV2, so this needs a PAT or a GitHub
|
|
219
|
+
* App. A run without one has not found nothing to move — it has not looked,
|
|
220
|
+
* and those are different states (`.claude/rules/config-access.md`).
|
|
221
|
+
*
|
|
222
|
+
* Whitespace is absence. A secret that was declared and left empty produces
|
|
223
|
+
* `""`, and treating that as a token turns the refusal into a 401 three calls
|
|
224
|
+
* later, where it reads as GitHub's problem.
|
|
225
|
+
*/
|
|
226
|
+
export function readBoardCredential(env: Record<string, string | undefined>): CredentialReading {
|
|
227
|
+
const raw = (env.BOARD_PROJECT_TOKEN ?? "").trim();
|
|
228
|
+
if (raw === "") {
|
|
229
|
+
return {
|
|
230
|
+
kind: "UNMEASURED",
|
|
231
|
+
why:
|
|
232
|
+
"BOARD_PROJECT_TOKEN is not set. GITHUB_TOKEN cannot write ProjectsV2, " +
|
|
233
|
+
"so this run could not read or move anything — it is UNMEASURED, not clean.",
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
return { kind: "present", token: raw };
|
|
237
|
+
}
|
package/lib/config-readers.ts
CHANGED
|
@@ -103,6 +103,36 @@ export function readBoardConfig(projectRoot: string): { projectId: string; crite
|
|
|
103
103
|
return { projectId, criteriaFieldId };
|
|
104
104
|
}
|
|
105
105
|
|
|
106
|
+
/**
|
|
107
|
+
* The label that marks an issue as being in the work queue, or `null`.
|
|
108
|
+
*
|
|
109
|
+
* **One binding, because the writer and the reading must not disagree.**
|
|
110
|
+
* `scripts/plan-issues.ts` applies it when it creates an issue and
|
|
111
|
+
* `scripts/board-conformance.ts`'s `queue-label` reading scores it, and
|
|
112
|
+
* before #1727 only the second knew the name. `--decompose --write` created
|
|
113
|
+
* seven issues on 2026-11-02 and the reading fell MET 12 of 12 → 5 of 12 on
|
|
114
|
+
* a command that never consulted it; the repair was seven `gh issue edit`
|
|
115
|
+
* calls by hand, which is what SC-2625 forbids.
|
|
116
|
+
*
|
|
117
|
+
* Spelling `"engine"` in the writer as well would have fixed that day and
|
|
118
|
+
* built the *two deciders that agree* shape — no behavioural case can tell
|
|
119
|
+
* them apart, and a mutation of either leaves the other holding every case
|
|
120
|
+
* up (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
121
|
+
*
|
|
122
|
+
* `null` for absent, blank or non-string, and callers must say UNMEASURED
|
|
123
|
+
* rather than substitute one: a tree that never configured a queue has not
|
|
124
|
+
* got an empty queue, it has no queue.
|
|
125
|
+
*/
|
|
126
|
+
export function readQueueLabel(projectRoot: string): string | null {
|
|
127
|
+
const config = tryLoadRungateConfig(projectRoot);
|
|
128
|
+
const board = (config as Record<string, unknown> | null)?.board;
|
|
129
|
+
if (!board || typeof board !== "object" || Array.isArray(board)) return null;
|
|
130
|
+
const raw = (board as Record<string, unknown>).queueLabel;
|
|
131
|
+
if (typeof raw !== "string") return null;
|
|
132
|
+
const label = raw.trim();
|
|
133
|
+
return label === "" ? null : label;
|
|
134
|
+
}
|
|
135
|
+
|
|
106
136
|
/**
|
|
107
137
|
* Pre-flight SSH hosts, keyed by name. `{}` when none are configured.
|
|
108
138
|
*
|
package/lib/github.ts
CHANGED
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
|
|
21
21
|
import { Octokit } from "@octokit/rest";
|
|
22
22
|
|
|
23
|
+
|
|
23
24
|
// ── Types ──────────────────────────────────────────────────────────────────
|
|
24
25
|
|
|
25
26
|
export interface GitHubClient {
|
|
@@ -193,31 +194,142 @@ export function createGitHubClient(): GitHubClient {
|
|
|
193
194
|
* name hidden in the userinfo (`https://127.0.0.1@evil.com`) are both
|
|
194
195
|
* refused. GitHub Enterprise needs a host outside this list and stays a
|
|
195
196
|
* separate, deliberate decision rather than a side effect of a test seam.
|
|
197
|
+
*
|
|
198
|
+
* **A second caller is coming, and is not here yet** — a paginating reader
|
|
199
|
+
* following `Link: rel="next"`, which is a **response** header, so the host it
|
|
200
|
+
* names is chosen by whoever answered rather than by us. Same question,
|
|
201
|
+
* second input. That reader is `restAll()` in `scripts/work-status.ts` and it
|
|
202
|
+
* lands with #1740; this tree does not contain it.
|
|
203
|
+
*
|
|
204
|
+
* The check is therefore `tokenRefusalReason` below, exported so one decider
|
|
205
|
+
* can answer both: two copies of an allowlist are one guard with a dead twin,
|
|
206
|
+
* and no behavioural case can tell which half it exercised. Written in the
|
|
207
|
+
* future tense on purpose — the earlier wording said "appeared" and "both" of
|
|
208
|
+
* a tree holding one caller, and a reader going to check found nothing and
|
|
209
|
+
* could not tell a split from a sentence nobody updated.
|
|
210
|
+
*
|
|
211
|
+
* It stays in THIS file rather than moving to a leaf module, and the three
|
|
212
|
+
* red checks that settled it are worth recording: SC-528 binds the literals
|
|
213
|
+
* `loopback` and `url.hostname` to `lib/github.ts`, and #827's fixed-point
|
|
214
|
+
* battery copies this file into an `mkdtemp` alone, where a new relative
|
|
215
|
+
* import dies on module resolution — a mutant that fails to load reads as a
|
|
216
|
+
* refusal (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
|
|
196
217
|
*/
|
|
218
|
+
export function resolveApiBaseUrl(): string | undefined {
|
|
219
|
+
const raw = process.env.GITHUB_API_URL?.trim();
|
|
220
|
+
if (!raw) return undefined;
|
|
221
|
+
const reason = tokenRefusalReason(raw);
|
|
222
|
+
if (reason !== null) throw new Error(`GITHUB_API_URL ${reason}`);
|
|
223
|
+
return raw;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* GitHub itself, or a port on this machine. Nothing else.
|
|
228
|
+
*
|
|
229
|
+
* Hostname is compared **exactly**, and the userinfo fields are checked
|
|
230
|
+
* separately — `https://127.0.0.1@evil.com` has hostname `evil.com`, and
|
|
231
|
+
* `https://evil.com@api.github.com` has an allowed hostname while still
|
|
232
|
+
* sending credentials nobody wrote. Neither may pass.
|
|
233
|
+
*/
|
|
234
|
+
// BRACKETED ONLY. These are compared against `url.hostname`, and WHATWG
|
|
235
|
+
// always brackets an IPv6 host — `http://[::1]/x` and the longhand
|
|
236
|
+
// `http://[0:0:0:0:0:0:0:1]/x` both yield `"[::1]"`, and `http://::1/x` is
|
|
237
|
+
// not a parseable URL at all. An unbracketed `"::1"` was here and matched
|
|
238
|
+
// nothing; its removal changes no outcome, which is why the row that holds
|
|
239
|
+
// this is a source assertion rather than a behavioural case.
|
|
240
|
+
const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
|
|
241
|
+
|
|
197
242
|
const ALLOWED_API_HOSTS = new Set([
|
|
198
243
|
"api.github.com",
|
|
199
244
|
"github.com",
|
|
200
|
-
|
|
201
|
-
"127.0.0.1",
|
|
202
|
-
"[::1]",
|
|
203
|
-
"::1",
|
|
245
|
+
...LOOPBACK_HOSTS,
|
|
204
246
|
]);
|
|
205
247
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
248
|
+
/**
|
|
249
|
+
* Why this URL may not carry our bearer token, or `null` when it may.
|
|
250
|
+
*
|
|
251
|
+
* One decider, and these are its callers as this tree actually stands:
|
|
252
|
+
*
|
|
253
|
+
* | caller | where | passes `base` |
|
|
254
|
+
* |---|---|---|
|
|
255
|
+
* | `resolveApiBaseUrl` | ABOVE, over `GITHUB_API_URL` | no |
|
|
256
|
+
* | `assertTokenMayReach` | BELOW, the throwing wrapper | yes, passes through |
|
|
257
|
+
* | `test/token-host-allowlist.test.ts` | the suite | yes, directly |
|
|
258
|
+
*
|
|
259
|
+
* `assertTokenMayReach` has **no in-tree production caller**. It is the entry
|
|
260
|
+
* point `restAll()` in `scripts/work-status.ts` will use, and that lands with
|
|
261
|
+
* #1740 — so today only the suite reaches it, and only the suite exercises
|
|
262
|
+
* `base`, which resolves a relative `Link: rel="next"` against the page it
|
|
263
|
+
* arrived on.
|
|
264
|
+
*
|
|
265
|
+
* Spelled out as a table because prose got it wrong twice: once naming
|
|
266
|
+
* `scripts/work-status.ts` as a current input when this tree lacks the file,
|
|
267
|
+
* and once naming `assertTokenMayReach` as the `GITHUB_API_URL` caller — the
|
|
268
|
+
* wrong function, in the wrong direction, and the one with no caller at all.
|
|
269
|
+
*/
|
|
270
|
+
export function tokenRefusalReason(raw: string, base?: string): string | null {
|
|
209
271
|
let url: URL;
|
|
210
272
|
try {
|
|
211
|
-
url = new URL(raw);
|
|
273
|
+
url = new URL(raw, base);
|
|
212
274
|
} catch {
|
|
213
|
-
|
|
275
|
+
return `is not a valid URL: ${raw}`;
|
|
214
276
|
}
|
|
277
|
+
// **The host check is first, and the order is asserted.** Every refusal
|
|
278
|
+
// here is a refusal whatever the order, so this is about the REASON, and a
|
|
279
|
+
// reason is the only part of a refusal anybody reads. `http://evil.com` and
|
|
280
|
+
// `https://127.0.0.1@evil.com` are host problems that also happen to be a
|
|
281
|
+
// scheme problem and a userinfo problem; reporting the incidental one sends
|
|
282
|
+
// the reader to fix the wrong thing. The existing cases in
|
|
283
|
+
// `test/github-client.test.ts` match on `/loopback/` and caught exactly
|
|
284
|
+
// this when the scheme check was added above them.
|
|
215
285
|
if (!ALLOWED_API_HOSTS.has(url.hostname)) {
|
|
216
|
-
|
|
217
|
-
`GITHUB_API_URL may only point at GitHub or loopback — refusing to send a token to ${url.hostname}`,
|
|
218
|
-
);
|
|
286
|
+
return `may only point at GitHub or loopback — refusing to send a token to ${url.hostname}`;
|
|
219
287
|
}
|
|
220
|
-
|
|
288
|
+
// `https://evil.com@api.github.com` has an ALLOWED hostname and still sends
|
|
289
|
+
// credentials nobody wrote, so this cannot be folded into the check above.
|
|
290
|
+
if (url.username || url.password) {
|
|
291
|
+
return `refuses to send a token to a URL carrying userinfo: ${url.host}`;
|
|
292
|
+
}
|
|
293
|
+
// THE SCHEME IS CHECKED WITHOUT REFERENCE TO THE HOST, and the single
|
|
294
|
+
// condition below used to do both at once:
|
|
295
|
+
//
|
|
296
|
+
// url.protocol !== "https:" && !LOOPBACK_HOSTS.has(url.hostname)
|
|
297
|
+
//
|
|
298
|
+
// which is a conjunction, so a loopback host short-circuited the scheme
|
|
299
|
+
// test away entirely. `ftp://127.0.0.1/x`, `ws://localhost/x` and
|
|
300
|
+
// `gopher://[::1]/x` all returned null. The documented contract is "https
|
|
301
|
+
// everywhere, plain http only for loopback"; what was implemented was "any
|
|
302
|
+
// scheme at all for loopback".
|
|
303
|
+
//
|
|
304
|
+
// It survived six rounds of review on #1740 because the two cases around
|
|
305
|
+
// it each vary one axis and the gap sits on the pair neither visits: one
|
|
306
|
+
// tries a bad scheme on a REAL host, the other tries `http:` on LOOPBACK.
|
|
307
|
+
// Nothing tried a bad scheme on loopback until round 12 read the
|
|
308
|
+
// conjunction itself (`.claude/rules/checks-must-be-able-to-fail.md`, the
|
|
309
|
+
// seventh shape).
|
|
310
|
+
if (url.protocol !== "https:" && url.protocol !== "http:") {
|
|
311
|
+
return `refuses to send a token over ${url.protocol}// to ${url.hostname}`;
|
|
312
|
+
}
|
|
313
|
+
// An allowed hostname over cleartext still puts the token on the wire.
|
|
314
|
+
// `http://api.github.com/x` passes every check above. Loopback keeps
|
|
315
|
+
// `http:` on purpose — a local test server has no certificate and the
|
|
316
|
+
// token never leaves the machine.
|
|
317
|
+
if (url.protocol !== "https:" && !LOOPBACK_HOSTS.has(url.hostname)) {
|
|
318
|
+
return `refuses to send a token over ${url.protocol}// to ${url.hostname}`;
|
|
319
|
+
}
|
|
320
|
+
return null;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* Throw unless this URL may carry the token. `context` names where the URL
|
|
325
|
+
* came from, because "refused" is only actionable when the reader knows which
|
|
326
|
+
* input produced it — an environment variable and a response header are
|
|
327
|
+
* repaired differently.
|
|
328
|
+
*/
|
|
329
|
+
export function assertTokenMayReach(raw: string, context: string, base?: string): URL {
|
|
330
|
+
const reason = tokenRefusalReason(raw, base);
|
|
331
|
+
if (reason !== null) throw new Error(`${context} ${reason}`);
|
|
332
|
+
return new URL(raw, base);
|
|
221
333
|
}
|
|
222
334
|
|
|
223
335
|
/**
|
|
@@ -240,9 +352,18 @@ export function resolveApiBaseUrl(): string | undefined {
|
|
|
240
352
|
* exported-but-unset variable must produce the clear error here rather than
|
|
241
353
|
* an unauthenticated client that 401s somewhere less obvious.
|
|
242
354
|
*/
|
|
243
|
-
export function resolveGitHubToken(
|
|
355
|
+
export function resolveGitHubToken(
|
|
356
|
+
// Injectable so a second implementation can be asserted to AGREE with this
|
|
357
|
+
// one on the same inputs. `scripts/check-state-record-closes.ts` must stay
|
|
358
|
+
// import-free — `test/state-record-closes-mutation.test.ts` asserts it,
|
|
359
|
+
// because its mutants run from a temp directory and a relative import
|
|
360
|
+
// makes every one of them die on module resolution, which reads as a
|
|
361
|
+
// refusal on the merits. So that file cannot call this; the next best
|
|
362
|
+
// thing is that the two cannot silently disagree.
|
|
363
|
+
env: Record<string, string | undefined> = process.env,
|
|
364
|
+
): string | undefined {
|
|
244
365
|
for (const name of ["GITHUB_TOKEN", "GH_TOKEN"]) {
|
|
245
|
-
const v =
|
|
366
|
+
const v = env[name];
|
|
246
367
|
// Trimmed, not just tested: `GH_TOKEN=$(cat token)` carries a trailing
|
|
247
368
|
// newline, and Octokit sends it in the Authorization header, where it
|
|
248
369
|
// 401s with nothing pointing at the whitespace as the cause.
|
package/lib/harness-identity.ts
CHANGED
|
@@ -43,6 +43,62 @@ import { join } from "path";
|
|
|
43
43
|
/** The harness's own package name. The one fact this module knows. */
|
|
44
44
|
export const HARNESS_PACKAGE = "rungate";
|
|
45
45
|
|
|
46
|
+
/**
|
|
47
|
+
* What the CLI says about itself before it does anything (#1598 follow-up).
|
|
48
|
+
*
|
|
49
|
+
* ## The reading this exists to make possible
|
|
50
|
+
*
|
|
51
|
+
* CI invokes the adjudicator as `bunx rungate@<version>`, and the version in
|
|
52
|
+
* that command is **authored text**. It is written into
|
|
53
|
+
* `.github/workflows/ai-review.yml` by the scaffold at generation time, and
|
|
54
|
+
* it is written again into the `::notice` annotation that quotes the command
|
|
55
|
+
* back to the reader. So a log can carry the string `rungate@0.8.4` three
|
|
56
|
+
* times and still not contain a single resolved reading of which version ran.
|
|
57
|
+
*
|
|
58
|
+
* That is not hypothetical. On 2026-10-24 three consecutive attempts to
|
|
59
|
+
* establish a version from a run log were wrong in the same direction, each
|
|
60
|
+
* correction finding the next layer:
|
|
61
|
+
*
|
|
62
|
+
* | the reading | why it cannot attribute a version |
|
|
63
|
+
* |---|---|
|
|
64
|
+
* | grep the log for `rungate@0.8.x` | matches the PR body, echoed by the round-counting step |
|
|
65
|
+
* | the same grep with colour codes excluded | still matches the annotation, which is authored |
|
|
66
|
+
* | bun's resolve block above the adjudication | prints `Resolved, downloaded and extracted [76]` — a count, no name, no version |
|
|
67
|
+
*
|
|
68
|
+
* The version had to be recovered from outside the log entirely, by reading
|
|
69
|
+
* the pin out of `ai-review.yml` at main's commit as of the run's
|
|
70
|
+
* `createdAt`. That works and it is three readings, two of which are easy to
|
|
71
|
+
* take against the wrong tree — `refs/pull/<N>/merge` is recomputed when main
|
|
72
|
+
* moves, so it describes a tree the run never saw.
|
|
73
|
+
*
|
|
74
|
+
* One line printed by the running process collapses all three into one.
|
|
75
|
+
*
|
|
76
|
+
* ## Why the spelling is deliberately not the pin's
|
|
77
|
+
*
|
|
78
|
+
* `rungate-version:` rather than `rungate@<v>`. If the announcement used the
|
|
79
|
+
* pin's spelling, a grep for a resolved value would match authored text again
|
|
80
|
+
* and this would have bought nothing — the defect reproduced inside its own
|
|
81
|
+
* fix. The marker is the discriminator; the version is the payload.
|
|
82
|
+
*
|
|
83
|
+
* ## UNMEASURED rather than a plausible default
|
|
84
|
+
*
|
|
85
|
+
* An unreadable or version-less `package.json` returns `UNMEASURED`, not a
|
|
86
|
+
* guess and not an empty string. A version that could not be read must not be
|
|
87
|
+
* spelled the same as one that could — `.claude/rules/config-access.md`,
|
|
88
|
+
* *Silent Default Substitution*. It does not throw: a CLI that dies because
|
|
89
|
+
* it could not introduce itself is worse than one that cannot.
|
|
90
|
+
*/
|
|
91
|
+
export function harnessVersionLine(root: string): string {
|
|
92
|
+
let version: unknown;
|
|
93
|
+
try {
|
|
94
|
+
version = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))?.version;
|
|
95
|
+
} catch {
|
|
96
|
+
version = undefined;
|
|
97
|
+
}
|
|
98
|
+
const resolved = typeof version === "string" && version.length > 0 ? version : "UNMEASURED";
|
|
99
|
+
return `rungate-version: ${resolved} (resolved at runtime, not the pin)`;
|
|
100
|
+
}
|
|
101
|
+
|
|
46
102
|
export function isHarnessItself(root: string): boolean {
|
|
47
103
|
try {
|
|
48
104
|
return JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))?.name === HARNESS_PACKAGE;
|
|
@@ -125,6 +125,7 @@ import {
|
|
|
125
125
|
AI_REVIEW_BLOCK_VERDICT,
|
|
126
126
|
AI_REVIEW_FINDING_FIELDS,
|
|
127
127
|
AI_REVIEW_FINDINGS_KEY,
|
|
128
|
+
AI_REVIEW_OPTIONAL_FINDING_FIELDS,
|
|
128
129
|
AI_REVIEW_OUTCOME_LINE,
|
|
129
130
|
AI_REVIEW_PASS_VERDICT,
|
|
130
131
|
AI_REVIEW_REQUIRED_EXIT,
|
|
@@ -140,6 +141,7 @@ export {
|
|
|
140
141
|
AI_REVIEW_BLOCK_VERDICT,
|
|
141
142
|
AI_REVIEW_FINDING_FIELDS,
|
|
142
143
|
AI_REVIEW_FINDINGS_KEY,
|
|
144
|
+
AI_REVIEW_OPTIONAL_FINDING_FIELDS,
|
|
143
145
|
AI_REVIEW_OUTCOME_LINE,
|
|
144
146
|
AI_REVIEW_PASS_VERDICT,
|
|
145
147
|
AI_REVIEW_SEVERITIES,
|
|
@@ -174,6 +176,107 @@ export function escapeAnnotation(value: unknown): string {
|
|
|
174
176
|
/** Annotation detail is capped: a megabyte of agent prose is not a message. */
|
|
175
177
|
export const AI_REVIEW_DETAIL_MAX = 300;
|
|
176
178
|
|
|
179
|
+
/** How many findings declared a class size, how many did not, and the total. */
|
|
180
|
+
export interface PopulationReading {
|
|
181
|
+
/** Findings carrying a readable population. */
|
|
182
|
+
declared: number;
|
|
183
|
+
/** Findings carrying none, or one this cannot read. UNMEASURED, not one. */
|
|
184
|
+
undeclared: number;
|
|
185
|
+
/** Instances claimed by the declared findings. Never includes a default. */
|
|
186
|
+
instances: number;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* One population value as a count, or `null`.
|
|
191
|
+
*
|
|
192
|
+
* ONE binding, so there is one thing to mutate and one place that decides
|
|
193
|
+
* what counts as a class size. `"3"`, `0`, `-1`, `1.5` and `true` are all
|
|
194
|
+
* things a model emits and none is a population; each returns `null` and the
|
|
195
|
+
* finding is UNMEASURED rather than contributing a number nobody measured.
|
|
196
|
+
*
|
|
197
|
+
* A string is refused rather than parsed on purpose. `duplicateOf` in
|
|
198
|
+
* `lib/filing-compliance.ts` went the other way for a good reason — it reads
|
|
199
|
+
* a ledger written by two writers over two days — but this field is being
|
|
200
|
+
* introduced now, with one producer and a contract, so accepting a second
|
|
201
|
+
* spelling on day one is how the contract stops meaning anything.
|
|
202
|
+
*/
|
|
203
|
+
function populationCount(value: unknown): number | null {
|
|
204
|
+
if (typeof value !== "number") return null;
|
|
205
|
+
return Number.isInteger(value) && value >= 1 ? value : null;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Did the reviewer say how big each defect class was?
|
|
210
|
+
*
|
|
211
|
+
* #1651's acceptance line is *"a finding payload carries the sibling sites it
|
|
212
|
+
* found, or states that it swept and found none"*, and this is the reading
|
|
213
|
+
* that makes it checkable. It judges nothing and blocks nothing — it reports,
|
|
214
|
+
* so the class instruction in `REVIEW.md` stops being prose with no
|
|
215
|
+
* instrument (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
216
|
+
*
|
|
217
|
+
* `declared + undeclared` is the payload size and `instances` is a different
|
|
218
|
+
* unit entirely. Do not add them, and do not render `instances` as though an
|
|
219
|
+
* undeclared finding contributed one to it.
|
|
220
|
+
*/
|
|
221
|
+
// The parameter is `reported` and not `findings` on purpose: AC-8a counts
|
|
222
|
+
// every `findings:` spelling across this module and `ai-review-step.ts` and
|
|
223
|
+
// requires exactly one, so that nothing reads the payload key except through
|
|
224
|
+
// `AI_REVIEW_FINDINGS_KEY`. A parameter name is indistinguishable from a key
|
|
225
|
+
// read to that census, and widening the census to exclude parameter names
|
|
226
|
+
// would weaken the check to buy a nicer identifier here.
|
|
227
|
+
/**
|
|
228
|
+
* #1651. The population reading, as the line a real run prints.
|
|
229
|
+
*
|
|
230
|
+
* `populationReading` without this was an instrument with no consumer — the
|
|
231
|
+
* aggregate existed, its tests passed, and no review run computed it. That is
|
|
232
|
+
* the defect this pull request describes, written into the fix for it, and it
|
|
233
|
+
* was caught on review rather than by me.
|
|
234
|
+
*
|
|
235
|
+
* Returns `null` for an empty payload, because "0 of 0 findings declared a
|
|
236
|
+
* class size" is not a reading anybody can act on and a notice on every clean
|
|
237
|
+
* review is a notice nobody reads.
|
|
238
|
+
*
|
|
239
|
+
* `instances` is printed only when something declared one, and it is NEVER
|
|
240
|
+
* added to the finding count: they are different units (see
|
|
241
|
+
* `PopulationReading`). An undeclared finding is reported as undeclared and
|
|
242
|
+
* contributes nothing — `.claude/rules/config-access.md`'s rule against
|
|
243
|
+
* substituting a default for a measurement nobody took.
|
|
244
|
+
*/
|
|
245
|
+
export function populationNotice(reported: readonly unknown[]): string | null {
|
|
246
|
+
if (reported.length === 0) return null;
|
|
247
|
+
const { declared, undeclared, instances } = populationReading(reported);
|
|
248
|
+
const head = `${declared} of ${reported.length} finding(s) declared how many instances their class has`;
|
|
249
|
+
const tail =
|
|
250
|
+
declared === 0
|
|
251
|
+
? ""
|
|
252
|
+
: `, covering ${instances} instance(s) in total`;
|
|
253
|
+
const rest =
|
|
254
|
+
undeclared === 0
|
|
255
|
+
? "."
|
|
256
|
+
: `. ${undeclared} did not, so for those the class size is UNMEASURED — not one. ` +
|
|
257
|
+
`REVIEW.md asks for the whole class in one finding; the cap counts classes, not instances.`;
|
|
258
|
+
return `${head}${tail}${rest}`;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
export function populationReading(reported: readonly unknown[]): PopulationReading {
|
|
262
|
+
let declared = 0;
|
|
263
|
+
let undeclared = 0;
|
|
264
|
+
let instances = 0;
|
|
265
|
+
for (const item of reported) {
|
|
266
|
+
const n =
|
|
267
|
+
item !== null && typeof item === "object"
|
|
268
|
+
? populationCount((item as Record<string, unknown>)[AI_REVIEW_FINDING_FIELDS.population])
|
|
269
|
+
: null;
|
|
270
|
+
if (n === null) {
|
|
271
|
+
undeclared++;
|
|
272
|
+
continue;
|
|
273
|
+
}
|
|
274
|
+
declared++;
|
|
275
|
+
instances += n;
|
|
276
|
+
}
|
|
277
|
+
return { declared, undeclared, instances };
|
|
278
|
+
}
|
|
279
|
+
|
|
177
280
|
/**
|
|
178
281
|
* One finding, rendered for an annotation — capped, naming file and summary.
|
|
179
282
|
*
|
|
@@ -210,7 +313,16 @@ export function renderFinding(
|
|
|
210
313
|
const line = `finding ${index} is ${String(finding[f.severity])} at ${where}: ${what}`;
|
|
211
314
|
const body =
|
|
212
315
|
line.length > AI_REVIEW_DETAIL_MAX ? `${line.slice(0, AI_REVIEW_DETAIL_MAX)}…` : line;
|
|
213
|
-
|
|
316
|
+
// The class size, AFTER the cap, for the same reason `tag` is: the finding
|
|
317
|
+
// whose class a reader most needs is the verbose one, and "this is 9 of a
|
|
318
|
+
// kind" truncated away reads as "this is one line". A finding that
|
|
319
|
+
// declared none renders nothing here — an invented "(1 instance)" is the
|
|
320
|
+
// default substitution `populationReading` exists to refuse.
|
|
321
|
+
const population = populationCount(finding[f.population]);
|
|
322
|
+
const sized = population === null
|
|
323
|
+
? body
|
|
324
|
+
: `${body} [${population} instance${population === 1 ? "" : "s"} of this shape]`;
|
|
325
|
+
return tag === null ? sized : `${sized} [${tag}]`;
|
|
214
326
|
}
|
|
215
327
|
|
|
216
328
|
/**
|
|
@@ -282,6 +394,16 @@ export const AI_REVIEW_SUPPRESSED_TITLE = "AI review repeats not reported again"
|
|
|
282
394
|
/** CRC-N4 (#1586). The history could not be compared — not "no repeats". */
|
|
283
395
|
export const AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE = "AI review repeat check UNMEASURED";
|
|
284
396
|
|
|
397
|
+
/**
|
|
398
|
+
* #1651. How many of this round's findings said how big their class is.
|
|
399
|
+
*
|
|
400
|
+
* Its own title, for `AI_REVIEW_ADVISORY_TITLE`'s reason: this is not a
|
|
401
|
+
* finding and nobody has to act on it. It is the reading that tells us
|
|
402
|
+
* whether the class-naming instruction in `REVIEW.md` is being followed —
|
|
403
|
+
* which, before this, nothing anywhere computed.
|
|
404
|
+
*/
|
|
405
|
+
export const AI_REVIEW_POPULATION_TITLE = "AI review class sizes declared";
|
|
406
|
+
|
|
285
407
|
/**
|
|
286
408
|
* A stable identity for one finding, so an answer can name it.
|
|
287
409
|
*
|
|
@@ -502,12 +624,19 @@ export type AiReviewUnmeasuredReason =
|
|
|
502
624
|
* two reasons; a second check of it would be the fourth shape in
|
|
503
625
|
* `.claude/rules/checks-must-be-able-to-fail.md` — two deciders agreeing about
|
|
504
626
|
* one input, of which a mutation leaves either one holding the case up.
|
|
627
|
+
*
|
|
628
|
+
* `AI_REVIEW_OPTIONAL_FINDING_FIELDS` is subtracted rather than spelled out
|
|
629
|
+
* here. Optionality is a property of the contract, so it is declared once,
|
|
630
|
+
* beside the contract, and this module reads it — a second list of excluded
|
|
631
|
+
* names in this file would be a second decider about what a finding must
|
|
632
|
+
* carry, and the two would drift the first time either moved.
|
|
505
633
|
*/
|
|
506
634
|
export const AI_REVIEW_BLOCKING_REQUIRED_FIELDS: readonly string[] = Object.entries(
|
|
507
635
|
AI_REVIEW_FINDING_FIELDS,
|
|
508
636
|
)
|
|
509
637
|
.filter(([key]) => key !== "severity")
|
|
510
|
-
.map(([, name]) => name)
|
|
638
|
+
.map(([, name]) => name)
|
|
639
|
+
.filter(name => !AI_REVIEW_OPTIONAL_FINDING_FIELDS.includes(name));
|
|
511
640
|
|
|
512
641
|
/**
|
|
513
642
|
* The contract fields a blocking finding failed to supply, in contract order.
|
|
@@ -887,6 +1016,25 @@ export interface AiReviewThreadRequest {
|
|
|
887
1016
|
* a hunk, which is a separate 422 the caller has to be able to fall back
|
|
888
1017
|
* from. Dropping here would silently lose findings whose only defect is that
|
|
889
1018
|
* the reviewer wrote no line number.
|
|
1019
|
+
*
|
|
1020
|
+
* **A finding whose file is not in the diff is not requested, blocking or
|
|
1021
|
+
* not.** `unlocatableReported` is populated by `readPayload`'s DEMOTION
|
|
1022
|
+
* branch, and that branch only runs for a finding that BLOCKS — so the
|
|
1023
|
+
* subtraction above cannot see a non-blocking finding carried forward onto a
|
|
1024
|
+
* path this branch has since stopped touching. It was sent, and GitHub
|
|
1025
|
+
* answered `422 pull_request_review_thread.path "could not be resolved"` at
|
|
1026
|
+
* the line AND again at file level, because the caller's demotion answers
|
|
1027
|
+
* "the line moved" and has no answer for "the file left". That lands in
|
|
1028
|
+
* `failed`, the one refusing outcome. Observed on #1740 head
|
|
1029
|
+
* `1d95e1da457cf5fc91298bd017a94087b8244d46`, run `41950364518`: two carried
|
|
1030
|
+
* findings on `lib/github.ts`, `0 of 2 posted`, exit 1, and a required check
|
|
1031
|
+
* permanently red over a branch with nothing wrong in it.
|
|
1032
|
+
*
|
|
1033
|
+
* The two skips are NOT the fourth shape in
|
|
1034
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, because each has an input
|
|
1035
|
+
* the other cannot answer: a MEASURED scope with `unlocatableReported` null
|
|
1036
|
+
* is reachable only by the scope check, and a reading carrying no scope with
|
|
1037
|
+
* `unlocatableReported` set is reachable only by the subtraction.
|
|
890
1038
|
*/
|
|
891
1039
|
export function reviewThreadRequests(
|
|
892
1040
|
reading: AiReviewFindingsReading,
|
|
@@ -896,11 +1044,31 @@ export function reviewThreadRequests(
|
|
|
896
1044
|
if (reading.reported === null) return [];
|
|
897
1045
|
const unlocatable = new Set(reading.unlocatableReported ?? []);
|
|
898
1046
|
|
|
1047
|
+
// Only a scope that was TAKEN can retire anything. `NOT_SUPPLIED` and
|
|
1048
|
+
// `UNMEASURED` leave `touched` null, which `findingPathScope` answers
|
|
1049
|
+
// `NOT_CHECKED` for every finding — a reading nobody took is not a pull
|
|
1050
|
+
// request that touched nothing, and must never become a blanket excuse for
|
|
1051
|
+
// posting less.
|
|
1052
|
+
const scope = reading.scope;
|
|
1053
|
+
let touched: ReadonlySet<string> | null = null;
|
|
1054
|
+
if (scope?.status === "MEASURED") {
|
|
1055
|
+
// The same conversion `readPayload` makes, through the same function, so
|
|
1056
|
+
// the skip here and the demotion there cannot disagree about one finding.
|
|
1057
|
+
const { readable } = partitionChangedFiles(scope.files);
|
|
1058
|
+
// Nothing readable left is the input `readPayload` refuses the whole
|
|
1059
|
+
// reading over, for the reason stated there: comparing against it would
|
|
1060
|
+
// retire every finding. Here the equivalent is to decide nothing.
|
|
1061
|
+
if (readable.length > 0) touched = new Set(readable);
|
|
1062
|
+
}
|
|
1063
|
+
|
|
899
1064
|
const requests: AiReviewThreadRequest[] = [];
|
|
900
1065
|
for (const item of reading.reported) {
|
|
901
1066
|
if (unlocatable.has(item)) continue;
|
|
902
1067
|
if (typeof item !== "object" || item === null) continue;
|
|
903
1068
|
const finding = item as Record<string, unknown>;
|
|
1069
|
+
// `PRE_EXISTING` only. `UNDECIDABLE` is a path this reader could not
|
|
1070
|
+
// compare, and it keeps the behaviour the line below already gives it.
|
|
1071
|
+
if (findingPathScope(finding, touched) === "PRE_EXISTING") continue;
|
|
904
1072
|
|
|
905
1073
|
const raw = finding[f.file];
|
|
906
1074
|
// Readability is asked of the normalised spelling; the answer is carried
|
|
@@ -2230,6 +2398,17 @@ export function main(
|
|
|
2230
2398
|
console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
|
|
2231
2399
|
}
|
|
2232
2400
|
|
|
2401
|
+
// #1651's reading, on its own title. A `::notice`: it decides nothing and
|
|
2402
|
+
// `aiReviewExitCode` never sees it — an undeclared class size is a thing to
|
|
2403
|
+
// watch across rounds, not a reason to refuse a pull request today. Emitted
|
|
2404
|
+
// for EVERY round including a clean one with findings, because the whole
|
|
2405
|
+
// point is a series: a rate that only appears when it is bad is a rate
|
|
2406
|
+
// nobody can compare against anything.
|
|
2407
|
+
const population = populationNotice(reading.reported ?? []);
|
|
2408
|
+
if (population !== null) {
|
|
2409
|
+
console.log(`::notice title=${AI_REVIEW_POPULATION_TITLE}::${escapeAnnotation(population)}`);
|
|
2410
|
+
}
|
|
2411
|
+
|
|
2233
2412
|
// CRC-N4's reading, on its own title (#1586). A `::notice`, because a
|
|
2234
2413
|
// repeat that was dropped is the mechanism working and nothing about it
|
|
2235
2414
|
// is a problem with the pull request.
|
|
@@ -3808,8 +3808,42 @@ export const AI_REVIEW_FINDING_FIELDS = {
|
|
|
3808
3808
|
line: "line",
|
|
3809
3809
|
summary: "summary",
|
|
3810
3810
|
failureScenario: "failure_scenario",
|
|
3811
|
+
/**
|
|
3812
|
+
* How many instances of this defect's shape exist — #1651, CRC-N3.
|
|
3813
|
+
*
|
|
3814
|
+
* `REVIEW.md` has told the reviewer to name the CLASS since CRC-N3 landed,
|
|
3815
|
+
* and nothing read whether it did, so the instruction had no instrument
|
|
3816
|
+
* and could never be observed failing. This is where the answer goes.
|
|
3817
|
+
*
|
|
3818
|
+
* **Not required, and deliberately so.** A finding without it is
|
|
3819
|
+
* UNMEASURED about its class size, which `populationReading` counts and
|
|
3820
|
+
* names apart — never folded into 1, because "I swept and this is the only
|
|
3821
|
+
* one" and "I did not sweep" are the two readings this field exists to
|
|
3822
|
+
* separate, and defaulting collapses them at the one place it matters.
|
|
3823
|
+
*/
|
|
3824
|
+
population: "population",
|
|
3811
3825
|
} as const;
|
|
3812
3826
|
|
|
3827
|
+
/**
|
|
3828
|
+
* Members of the contract a finding may omit, declared HERE beside the
|
|
3829
|
+
* contract and nowhere else.
|
|
3830
|
+
*
|
|
3831
|
+
* `AI_REVIEW_BLOCKING_REQUIRED_FIELDS` derives the required set from
|
|
3832
|
+
* `AI_REVIEW_FINDING_FIELDS` minus `severity` (#1166), deliberately, so that
|
|
3833
|
+
* adding a member cannot leave the enforcement behind. Adding `population`
|
|
3834
|
+
* therefore made it REQUIRED on every blocking finding — which is wrong for
|
|
3835
|
+
* a field whose absence is a meaningful reading, and which turned 14 cases
|
|
3836
|
+
* red the moment it was added. That red is the derivation working.
|
|
3837
|
+
*
|
|
3838
|
+
* The fix is not a second exclusion list in the deriving module: optionality
|
|
3839
|
+
* is a property of the contract, so it is stated once, next to it, and the
|
|
3840
|
+
* derivation subtracts it. A name here that the contract does not declare is
|
|
3841
|
+
* refused by `test/finding-population.test.ts`.
|
|
3842
|
+
*/
|
|
3843
|
+
export const AI_REVIEW_OPTIONAL_FINDING_FIELDS: readonly string[] = [
|
|
3844
|
+
AI_REVIEW_FINDING_FIELDS.population,
|
|
3845
|
+
];
|
|
3846
|
+
|
|
3813
3847
|
/**
|
|
3814
3848
|
* The marker that carries a posted thread's identity, so a later round can
|
|
3815
3849
|
* ask the thread list whether a finding was already raised.
|
|
@@ -5797,15 +5831,32 @@ The payload is a single JSON object shaped exactly like this:
|
|
|
5797
5831
|
"${f.file}": "repo-relative path",
|
|
5798
5832
|
"${f.line}": 1,
|
|
5799
5833
|
"${f.summary}": "one sentence stating the defect",
|
|
5800
|
-
"${f.failureScenario}": "concrete inputs or state, then the wrong output"
|
|
5834
|
+
"${f.failureScenario}": "concrete inputs or state, then the wrong output",
|
|
5835
|
+
"${f.population}": 1
|
|
5801
5836
|
}
|
|
5802
5837
|
],
|
|
5803
5838
|
"${AI_REVIEW_VERDICT_KEY}": "${AI_REVIEW_VERDICTS.join(" or ")}"
|
|
5804
5839
|
}
|
|
5805
5840
|
|
|
5806
|
-
Every
|
|
5807
|
-
missing \`${f.file}\` or \`${f.summary}\` reaches a
|
|
5808
|
-
naming no code and no defect, which is the same
|
|
5841
|
+
Every member name above except \`${f.population}\` is required on every
|
|
5842
|
+
finding. A finding missing \`${f.file}\` or \`${f.summary}\` reaches a
|
|
5843
|
+
maintainer as an annotation naming no code and no defect, which is the same
|
|
5844
|
+
as not reporting it.
|
|
5845
|
+
|
|
5846
|
+
\`${f.population}\` is how many places have the shape you just described,
|
|
5847
|
+
counting the one you cited and the ones OUTSIDE the diff. Scope it to the
|
|
5848
|
+
PROPERTY and not to the spelling you matched: three unpaginated REST reads
|
|
5849
|
+
and two unpaginated GraphQL selections in one file are five, because they
|
|
5850
|
+
truncate for the same reason and the author fixes them in one edit.
|
|
5851
|
+
|
|
5852
|
+
It is the one optional member, and the only honest reason to omit it is that
|
|
5853
|
+
you did not sweep. Leave it off in that case — absent reads as unmeasured,
|
|
5854
|
+
which is true. Do not write \`1\` for a class you did not check: that says
|
|
5855
|
+
you looked and found nothing else, and a maintainer who believes it stops
|
|
5856
|
+
looking. The non-blocking cap counts CLASSES, so a finding carrying
|
|
5857
|
+
\`"${f.population}": 9\` costs the same one slot as a finding carrying 1 —
|
|
5858
|
+
there is never a reason to split a class across findings or to hold
|
|
5859
|
+
instances back for a later round.
|
|
5809
5860
|
|
|
5810
5861
|
On a finding whose severity BLOCKS, that requirement is now read back and
|
|
5811
5862
|
enforced: a blocking finding missing any of \`${f.file}\`, \`${f.line}\`,
|
package/package.json
CHANGED
|
@@ -102,6 +102,23 @@ export interface BoardSnapshot {
|
|
|
102
102
|
issues: BoardIssue[];
|
|
103
103
|
criteria: BoardCriterion[];
|
|
104
104
|
phases: BoardPhase[];
|
|
105
|
+
/**
|
|
106
|
+
* The project's work-queue label, carried as DATA rather than read here.
|
|
107
|
+
*
|
|
108
|
+
* It arrives on the snapshot for a mechanical reason as well as a design
|
|
109
|
+
* one. `test/board-conformance.test.ts` builds a mutant copy of this file
|
|
110
|
+
* in an `mkdtemp` directory, and a relative import makes that copy fail
|
|
111
|
+
* to load — which reads as a refusal on the merits and leaves every
|
|
112
|
+
* negative case witnessing nothing
|
|
113
|
+
* (`.claude/rules/self-referential-tests.md`). `scripts/board-snapshot.ts`
|
|
114
|
+
* already imports `readQueueLabel`, so the producer resolves it and this
|
|
115
|
+
* file stays import-free.
|
|
116
|
+
*
|
|
117
|
+
* **Absent means the producer never resolved one**, and `queue-label`
|
|
118
|
+
* goes UNMEASURED rather than counting 0 — same convention as
|
|
119
|
+
* {@link closedBlockers}.
|
|
120
|
+
*/
|
|
121
|
+
queueLabel?: string | null;
|
|
105
122
|
/**
|
|
106
123
|
* The CLOSED issues that at least one engine issue names as a blocker.
|
|
107
124
|
*
|
|
@@ -308,9 +325,27 @@ export const READINGS: readonly ReadingSpec[] = [
|
|
|
308
325
|
{
|
|
309
326
|
name: "queue-label",
|
|
310
327
|
item: "B6",
|
|
311
|
-
what: "every engine issue carries the
|
|
328
|
+
what: "every engine issue carries the queue label, so the queue is the label",
|
|
312
329
|
readsIssueRefs: false,
|
|
313
|
-
|
|
330
|
+
// The label is CONFIGURED, and this reading no longer knows its name on
|
|
331
|
+
// its own. Before #1727 it spelled `"engine"` and was the only thing
|
|
332
|
+
// that did, so `plan-issues --decompose --write` could create seven
|
|
333
|
+
// issues without it and take this reading MET 12 of 12 → 5 of 12 — a
|
|
334
|
+
// writer failing a reading it never consults. Both now go through
|
|
335
|
+
// `readQueueLabel`, so there is ONE answer to mutate rather than two
|
|
336
|
+
// that agree (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
337
|
+
unreadable: b =>
|
|
338
|
+
typeof b.queueLabel === "string" && b.queueLabel.trim() !== ""
|
|
339
|
+
? null
|
|
340
|
+
: "no queue label is in the snapshot — set `board.queueLabel` in .claude/rungate/config.json and " +
|
|
341
|
+
"re-take it. A tree that never named a queue has not got an empty one, so this is UNMEASURED " +
|
|
342
|
+
"rather than 0 of N.",
|
|
343
|
+
measure: b => {
|
|
344
|
+
// Non-null here: `unreadable` above refused every other case, and
|
|
345
|
+
// `takeReading` runs it first.
|
|
346
|
+
const label = b.queueLabel!;
|
|
347
|
+
return { measured: b.issues.filter(i => i.labels.includes(label)).length, target: b.issues.length };
|
|
348
|
+
},
|
|
314
349
|
},
|
|
315
350
|
];
|
|
316
351
|
|
|
@@ -538,12 +573,40 @@ export function readSnapshotText(text: string): SnapshotRead {
|
|
|
538
573
|
const closed = Array.isArray(raw.closedBlockers)
|
|
539
574
|
? { closedBlockers: raw.closedBlockers.filter((n): n is number => typeof n === "number") }
|
|
540
575
|
: {};
|
|
576
|
+
|
|
577
|
+
// TRIMMED here, which is the only place it can be. `readQueueLabel`
|
|
578
|
+
// trims at the config read, but that is the PRODUCER path — this function
|
|
579
|
+
// also accepts a hand-written or externally produced `--snapshot`, and
|
|
580
|
+
// copying `" engine "` through verbatim passed `unreadable` (non-blank
|
|
581
|
+
// after trim) and then had `measure` search issue labels for the literal
|
|
582
|
+
// `" engine "`, which no GitHub label can equal. The reading would have
|
|
583
|
+
// said 0 of N — a confident wrong number where UNMEASURED or the right
|
|
584
|
+
// count belonged. Found in review of #1727.
|
|
585
|
+
//
|
|
586
|
+
// Normalising at the boundary rather than re-trimming inside `measure`
|
|
587
|
+
// keeps ONE answer to *what is the label*: `unreadable` and `measure`
|
|
588
|
+
// then read the same bytes by construction, instead of two guards
|
|
589
|
+
// agreeing to trim and a third one later forgetting.
|
|
590
|
+
//
|
|
591
|
+
// `queueLabel` is carried the same way as `closedBlockers`, for the same
|
|
592
|
+
// reason — #1727.
|
|
593
|
+
// This function rebuilds the board from a NAMED list of fields rather
|
|
594
|
+
// than spreading `raw`, so a key nobody adds here is silently dropped on
|
|
595
|
+
// EVERY path: `--snapshot` as well as `--produce`. The producer wrote
|
|
596
|
+
// the label, the reading never saw it, and `queue-label` reported
|
|
597
|
+
// UNMEASURED against a snapshot that carried exactly what it asked for.
|
|
598
|
+
//
|
|
599
|
+
// Present-only, like `closedBlockers`: absence is the signal the reading
|
|
600
|
+
// reports on, so writing the key unconditionally would make a tree that
|
|
601
|
+
// never configured a queue indistinguishable from one that did.
|
|
602
|
+
const queue = typeof raw.queueLabel === "string" ? { queueLabel: raw.queueLabel.trim() } : {};
|
|
541
603
|
return {
|
|
542
604
|
board: {
|
|
543
605
|
issues: issues as BoardIssue[],
|
|
544
606
|
criteria: criteria as BoardCriterion[],
|
|
545
607
|
phases: phases as BoardPhase[],
|
|
546
608
|
...closed,
|
|
609
|
+
...queue,
|
|
547
610
|
},
|
|
548
611
|
why: null,
|
|
549
612
|
};
|
|
@@ -37,7 +37,7 @@ import { isAbsolute, join } from "path";
|
|
|
37
37
|
import { parseArgs } from "util";
|
|
38
38
|
import { openFrontier, phaseOf } from "../lib/board-mirror";
|
|
39
39
|
import { createGitHubClient, listMilestones } from "../lib/github";
|
|
40
|
-
import { readBoardConfig } from "../lib/config-readers";
|
|
40
|
+
import { readBoardConfig, readQueueLabel } from "../lib/config-readers";
|
|
41
41
|
import {
|
|
42
42
|
inMilestoneFamily,
|
|
43
43
|
readIssueStates,
|
|
@@ -190,6 +190,14 @@ export interface ProducedSnapshot {
|
|
|
190
190
|
* has a resolved edge.
|
|
191
191
|
*/
|
|
192
192
|
closedBlockers: number[];
|
|
193
|
+
/**
|
|
194
|
+
* The work-queue label from `board.queueLabel`, or `null` when the
|
|
195
|
+
* project configures none. Resolved HERE because `board-conformance`
|
|
196
|
+
* must stay free of relative imports — its mutation battery copies it
|
|
197
|
+
* into an `mkdtemp` and a relative import makes the mutant fail to load
|
|
198
|
+
* (`.claude/rules/self-referential-tests.md`).
|
|
199
|
+
*/
|
|
200
|
+
queueLabel: string | null;
|
|
193
201
|
/**
|
|
194
202
|
* The spec's criteria, and what the board says about each — item **B2**.
|
|
195
203
|
*
|
|
@@ -449,6 +457,7 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
|
|
|
449
457
|
phases: actions.map(a => ({ phase: a.phase, criteria: a.criteria, milestoneState: a.action })),
|
|
450
458
|
issues: snapshotIssues,
|
|
451
459
|
closedBlockers: [...named].sort((a, b) => a - b),
|
|
460
|
+
queueLabel: readQueueLabel(root),
|
|
452
461
|
criteria: criterionCoverage(content, snapshotIssues, columnRead),
|
|
453
462
|
};
|
|
454
463
|
|
package/scripts/plan-issues.ts
CHANGED
|
@@ -40,6 +40,7 @@ import {
|
|
|
40
40
|
} from "../lib/issue-repair";
|
|
41
41
|
import type { RepairRow } from "../lib/issue-repair";
|
|
42
42
|
import { parseDecompositionPlan, planDecomposition } from "../lib/issue-decomposition";
|
|
43
|
+
import { readQueueLabel } from "../lib/config-readers";
|
|
43
44
|
|
|
44
45
|
/**
|
|
45
46
|
* THE one non-zero exit. One site, so `test/plan-issues.test.ts` can build a
|
|
@@ -165,7 +166,14 @@ export interface DecomposeGitHub {
|
|
|
165
166
|
milestones: (repo: string) => Promise<Set<string>>;
|
|
166
167
|
create: (
|
|
167
168
|
repo: string,
|
|
168
|
-
|
|
169
|
+
/**
|
|
170
|
+
* `label` is the work-queue label from `readQueueLabel`, or `null` when
|
|
171
|
+
* the project configures none. It is part of CREATION rather than a
|
|
172
|
+
* later edit because #1727 is what a later edit looks like: seven
|
|
173
|
+
* issues arrived on 2026-11-02 without it and `queue-label` fell MET
|
|
174
|
+
* 12 of 12 → 5 of 12, repaired by seven `gh issue edit` calls by hand.
|
|
175
|
+
*/
|
|
176
|
+
issue: { title: string; body: string; milestone: string | null; label: string | null },
|
|
169
177
|
) => Promise<number>;
|
|
170
178
|
addBlockedBy: (repo: string, blocked: number, blocker: number) => Promise<void>;
|
|
171
179
|
/**
|
|
@@ -244,6 +252,7 @@ const LIVE_DECOMPOSE: DecomposeGitHub = {
|
|
|
244
252
|
create: async (repo, issue) => {
|
|
245
253
|
const args = ["issue", "create", "--repo", repo, "--title", issue.title, "--body-file", "-"];
|
|
246
254
|
if (issue.milestone !== null) args.push("--milestone", issue.milestone);
|
|
255
|
+
if (issue.label !== null) args.push("--label", issue.label);
|
|
247
256
|
const url = gh(args, issue.body).trim();
|
|
248
257
|
const n = Number(url.split("/").pop());
|
|
249
258
|
// A URL whose last segment is not a number means `gh` printed something
|
|
@@ -329,6 +338,12 @@ async function decompose(
|
|
|
329
338
|
write: boolean,
|
|
330
339
|
json: boolean,
|
|
331
340
|
api: DecomposeGitHub,
|
|
341
|
+
/**
|
|
342
|
+
* The work-queue label to stamp on everything created, or `null`. Passed
|
|
343
|
+
* in rather than read here so a test can state both worlds without a
|
|
344
|
+
* config fixture on disk.
|
|
345
|
+
*/
|
|
346
|
+
queueLabel: string | null,
|
|
332
347
|
): Promise<number> {
|
|
333
348
|
const refuse = refusalReporter(json);
|
|
334
349
|
|
|
@@ -371,7 +386,12 @@ async function decompose(
|
|
|
371
386
|
for (const a of planned.actions) {
|
|
372
387
|
if (a.kind !== "create") continue;
|
|
373
388
|
try {
|
|
374
|
-
const n = await api.create(repo, {
|
|
389
|
+
const n = await api.create(repo, {
|
|
390
|
+
title: a.title,
|
|
391
|
+
body: a.body,
|
|
392
|
+
milestone: a.row.milestone,
|
|
393
|
+
label: queueLabel,
|
|
394
|
+
});
|
|
375
395
|
numbers.set(a.row.outcome, n);
|
|
376
396
|
created.push({ title: a.title, number: n });
|
|
377
397
|
} catch (e) {
|
|
@@ -534,7 +554,7 @@ export async function main(
|
|
|
534
554
|
const within = relative(root, planPath);
|
|
535
555
|
const escapes = within === ".." || within.startsWith(`..${sep}`);
|
|
536
556
|
const planLabel = within === "" || escapes ? planPath : within;
|
|
537
|
-
return await decompose(planPath, planLabel, repo, values.write, values.json, gh3);
|
|
557
|
+
return await decompose(planPath, planLabel, repo, values.write, values.json, gh3, readQueueLabel(root));
|
|
538
558
|
}
|
|
539
559
|
|
|
540
560
|
const reading = parseRepairPlan(readFileSync(planPath, "utf-8"));
|