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 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
- b3f611f4544c955941ff527106a0f7260cb49e435e814901388c5d79e5dbf9ad
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
+ }
@@ -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
- "localhost",
201
- "127.0.0.1",
202
- "[::1]",
203
- "::1",
245
+ ...LOOPBACK_HOSTS,
204
246
  ]);
205
247
 
206
- export function resolveApiBaseUrl(): string | undefined {
207
- const raw = process.env.GITHUB_API_URL?.trim();
208
- if (!raw) return undefined;
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
- throw new Error(`GITHUB_API_URL is not a valid URL: ${raw}`);
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
- throw new Error(
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
- return raw;
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(): string | undefined {
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 = process.env[name];
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.
@@ -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
- return tag === null ? body : `${body} [${tag}]`;
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 one of those member names is required on every finding. A finding
5807
- missing \`${f.file}\` or \`${f.summary}\` reaches a maintainer as an annotation
5808
- naming no code and no defect, which is the same as not reporting it.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.10",
3
+ "version": "0.8.13",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -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 `engine` label, so the queue is the label",
328
+ what: "every engine issue carries the queue label, so the queue is the label",
312
329
  readsIssueRefs: false,
313
- measure: b => ({ measured: b.issues.filter(i => i.labels.includes("engine")).length, target: b.issues.length }),
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
 
@@ -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
- issue: { title: string; body: string; milestone: string | null },
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, { title: a.title, body: a.body, milestone: a.row.milestone });
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"));