rungate 0.8.26 → 0.8.28

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
@@ -74,7 +74,11 @@ if (!existsSync(script)) {
74
74
  // Only added when the caller did not say otherwise, and only for commands
75
75
  // that accept the flag — a script that does not would read it as a
76
76
  // positional argument.
77
- const needsRoot = command.projectRootFlag && !rest.includes("--project-root");
77
+ // Either spelling counts as the caller saying so: `--project-root=<dir>` read
78
+ // as absent appended the cwd AFTER it, and a last-one-wins reader then took
79
+ // the cwd over the directory the caller named (review of #2365).
80
+ const givesRoot = rest.some(a => a === "--project-root" || a.startsWith("--project-root="));
81
+ const needsRoot = command.projectRootFlag && !givesRoot;
78
82
  const args = needsRoot ? [...rest, "--project-root", process.cwd()] : rest;
79
83
 
80
84
  // Run the script as an ENTRY MODULE, so `import.meta.main` is true inside it
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 242fddb8d473fcc077837b3b9768f218aa828117b92d2bd7130973f9a753f373
1
+ 545e0acc9e8aaebb75f5345bedfc501cbc22cbbef652611467898dcd4736a772
@@ -167,10 +167,59 @@ export type AiReviewThreadOutcome =
167
167
  | "BLOCKED_BY_PENDING_REVIEW"
168
168
  | "FAILED";
169
169
 
170
- /** What the API said. `status` is `null` for a failure that never got one. */
170
+ /**
171
+ * One entry of a refusal's structured `errors[]` (#2363). GitHub sends objects
172
+ * naming a `field` and a `code`, or bare strings, which arrive here as
173
+ * `{ message }`.
174
+ */
175
+ export interface AiReviewApiError {
176
+ field?: string;
177
+ code?: string;
178
+ message?: string;
179
+ }
180
+
181
+ /**
182
+ * What the API said. `status` is `null` for a failure that never got one.
183
+ * `errors` is the structured body when the refusal carried one; absent, the
184
+ * classifiers fall back to the message text.
185
+ */
171
186
  export type AiReviewThreadResponse =
172
187
  | { ok: true }
173
- | { ok: false; status: number | null; message: string };
188
+ | { ok: false; status: number | null; message: string; errors?: AiReviewApiError[] };
189
+
190
+ /**
191
+ * A thrown Octokit error as a refusal, keeping `response.data.errors` (#2363).
192
+ * The status and message alone threw away the one part GitHub states as data,
193
+ * which left every classifier matching serialized text.
194
+ */
195
+ export function refusalFrom(e: unknown): Extract<AiReviewThreadResponse, { ok: false }> {
196
+ const err = e as { status?: unknown; message?: unknown; response?: { data?: { errors?: unknown } } };
197
+ const status = typeof err.status === "number" ? err.status : null;
198
+ const message = typeof err.message === "string" ? err.message : String(e);
199
+ const raw = err.response?.data?.errors;
200
+ if (!Array.isArray(raw)) return { ok: false, status, message };
201
+ const errors: AiReviewApiError[] = raw.map(x => {
202
+ if (typeof x === "string") return { message: x };
203
+ const o = (x ?? {}) as Record<string, unknown>;
204
+ return {
205
+ ...(typeof o.field === "string" ? { field: o.field } : {}),
206
+ ...(typeof o.code === "string" ? { code: o.code } : {}),
207
+ ...(typeof o.message === "string" ? { message: o.message } : {}),
208
+ };
209
+ });
210
+ return { ok: false, status, message, errors };
211
+ }
212
+
213
+ /**
214
+ * The pull-request-level fallback (#2338): a finding GitHub refuses at the line
215
+ * AND at the file goes here instead of being lost. `existing` is every body
216
+ * already on the pull request's conversation, so a later round does not post
217
+ * the same finding again.
218
+ */
219
+ export interface AiReviewPullCommenter {
220
+ post: (body: string) => Promise<AiReviewThreadResponse>;
221
+ existing: readonly string[];
222
+ }
174
223
 
175
224
  /** Sends one comment. The only thing in this module that touches a network. */
176
225
  export type AiReviewThreadPoster = (
@@ -185,6 +234,8 @@ export interface AiReviewThreadsResult {
185
234
  posted: number;
186
235
  /** Of those, how many only succeeded after dropping to file level. */
187
236
  demoted: number;
237
+ /** Of those, how many went on the conversation because GitHub refused the file too (#2338). */
238
+ pullComments: number;
188
239
  /** One sentence per thing worth reading, in the order it happened. */
189
240
  detail: string[];
190
241
  }
@@ -209,6 +260,41 @@ const FORBIDDEN = 403;
209
260
  */
210
261
  const PENDING_REVIEW_CONDITION = /pending review/i;
211
262
 
263
+ /**
264
+ * The 422 that means "this path is not in the pull request's diff" — GitHub
265
+ * names the FIELD, either as `pull_request_review_thread.path` (the #1740
266
+ * reading: `… .path "could not be resolved"`) or as `"field":"path"` in its
267
+ * errors array. The bare word "path" anywhere in a message is not that
268
+ * (review of #2358): any other 422, a stale `commit_id` among them, is a
269
+ * request this producer got wrong and stays a failure rather than moving to
270
+ * the conversation.
271
+ */
272
+ const OFF_DIFF_CONDITION = /pull_request_review_thread\.path\b|"field"\s*:\s*"path"/;
273
+
274
+ /** The fields a refusal's structured body names, or `null` when it names none. */
275
+ function fieldsNamed(answer: Extract<AiReviewThreadResponse, { ok: false }>): string[] | null {
276
+ const fields = (answer.errors ?? []).flatMap(e => (e.field === undefined ? [] : [e.field]));
277
+ return fields.length === 0 ? null : fields;
278
+ }
279
+
280
+ /** Every piece of text a refusal carries: its message and each error's message. */
281
+ function refusalText(answer: Extract<AiReviewThreadResponse, { ok: false }>): string {
282
+ return [answer.message, ...(answer.errors ?? []).flatMap(e => (e.message === undefined ? [] : [e.message]))].join("\n");
283
+ }
284
+
285
+ /**
286
+ * The off-diff 422 (#2338), decided from `errors[].field` when GitHub named
287
+ * one (#2363): `path`, or a dotted name ending in `.path`, is off-diff and
288
+ * any other field is not, whatever the message says. With no field named, the
289
+ * text decides — the message and each error's own message — through {@link OFF_DIFF_CONDITION}.
290
+ */
291
+ function isOffDiffRefusal(answer: AiReviewThreadResponse): boolean {
292
+ if (answer.ok || answer.status !== UNPROCESSABLE) return false;
293
+ const fields = fieldsNamed(answer);
294
+ if (fields !== null) return fields.some(f => f === "path" || f.endsWith(".path"));
295
+ return OFF_DIFF_CONDITION.test(refusalText(answer));
296
+ }
297
+
212
298
  /**
213
299
  * One binding, so a mutation of it is observable. Both halves are required:
214
300
  * the status narrows it to a validation refusal, the condition says WHICH —
@@ -217,7 +303,7 @@ const PENDING_REVIEW_CONDITION = /pending review/i;
217
303
  */
218
304
  function isPendingReviewRefusal(answer: AiReviewThreadResponse): boolean {
219
305
  return (
220
- !answer.ok && answer.status === UNPROCESSABLE && PENDING_REVIEW_CONDITION.test(answer.message)
306
+ !answer.ok && answer.status === UNPROCESSABLE && PENDING_REVIEW_CONDITION.test(refusalText(answer))
221
307
  );
222
308
  }
223
309
 
@@ -255,6 +341,7 @@ export async function postReviewThreads(
255
341
  post: AiReviewThreadPoster,
256
342
  keyFor?: (finding: Record<string, unknown>) => string | null,
257
343
  fork?: boolean | null,
344
+ comment?: AiReviewPullCommenter,
258
345
  ): Promise<AiReviewThreadsResult> {
259
346
  const detail: string[] = [];
260
347
 
@@ -262,17 +349,21 @@ export async function postReviewThreads(
262
349
  detail.push(
263
350
  "the review produced no usable reading, so there was nothing to post — this is not a review that found nothing",
264
351
  );
265
- return { outcome: "UNMEASURED", attempted: 0, posted: 0, demoted: 0, detail };
352
+ return { outcome: "UNMEASURED", attempted: 0, posted: 0, demoted: 0, pullComments: 0, detail };
266
353
  }
267
354
 
268
355
  const requests = reviewThreadRequests(reading, keyFor);
269
356
  if (requests.length === 0) {
270
357
  detail.push("the reading located no finding that could be anchored to a path in this diff");
271
- return { outcome: "NOTHING_TO_POST", attempted: 0, posted: 0, demoted: 0, detail };
358
+ return { outcome: "NOTHING_TO_POST", attempted: 0, posted: 0, demoted: 0, pullComments: 0, detail };
272
359
  }
273
360
 
274
361
  let posted = 0;
275
362
  let demoted = 0;
363
+ let pullComments = 0;
364
+ const alreadyOnConversation = new Set((comment?.existing ?? []).map(threadKeyFrom).filter((k): k is string => k !== null));
365
+ /** Keys this call put on the conversation, so a repeat can say WHEN (review of #2358). */
366
+ const postedThisRound = new Set<string>();
276
367
  let forbidden = 0;
277
368
  let pending = 0;
278
369
  let failed = 0;
@@ -302,6 +393,56 @@ export async function postReviewThreads(
302
393
  if (answer.ok) demoted += 1;
303
394
  }
304
395
 
396
+ // #2338: refused at the file too. The path is not in this pull request's
397
+ // diff as GitHub sees it (a branch behind its base is the measured cause),
398
+ // so the finding goes on the conversation rather than nowhere.
399
+ if (
400
+ !answer.ok &&
401
+ answer.status === UNPROCESSABLE &&
402
+ comment !== undefined &&
403
+ !isPendingReviewRefusal(answer) &&
404
+ isOffDiffRefusal(answer)
405
+ ) {
406
+ const key = threadKeyFrom(request.body);
407
+ if (key !== null && alreadyOnConversation.has(key)) {
408
+ posted += 1;
409
+ pullComments += 1;
410
+ const when = postedThisRound.has(key) ? "earlier in this round" : "from an earlier round";
411
+ detail.push(`${where}: not in this pull request's diff, and already on its conversation ${when}, so not posted again`);
412
+ continue;
413
+ }
414
+ const viaConversation = await comment.post(
415
+ `**\`${where}\` is not in this pull request's diff, so this finding could not go on it.** ` +
416
+ `GitHub refused it ${request.line === null ? "at the file" : "at the line and at the file"}. ` +
417
+ `The branch may be behind its base; rebasing usually puts the file back in the diff.\n\n` +
418
+ request.body,
419
+ );
420
+ if (viaConversation.ok) {
421
+ // Within the round too: a second finding with this key is the same finding (review of #2358).
422
+ if (key !== null) {
423
+ alreadyOnConversation.add(key);
424
+ postedThisRound.add(key);
425
+ }
426
+ posted += 1;
427
+ pullComments += 1;
428
+ detail.push(`${where}: not in this pull request's diff (422 ${request.line === null ? "at the file" : "at the line and at the file"}), so it was posted on the conversation instead`);
429
+ continue;
430
+ }
431
+ // A 403 here is the token, not the finding: the fork branch below
432
+ // decides it exactly as it decides a refused review comment (review of
433
+ // #2358 — a fork's read-only token must degrade, never fail).
434
+ if (!viaConversation.ok && viaConversation.status === FORBIDDEN) {
435
+ answer = viaConversation;
436
+ } else {
437
+ failed += 1;
438
+ detail.push(
439
+ `${where}: not in this pull request's diff (422 ${request.line === null ? "at the file" : "at the line and at the file"}), and the conversation comment was refused too: ` +
440
+ `${viaConversation.status ?? "no status"} — ${viaConversation.message}`,
441
+ );
442
+ continue;
443
+ }
444
+ }
445
+
305
446
  if (answer.ok) {
306
447
  posted += 1;
307
448
  continue;
@@ -336,10 +477,10 @@ export async function postReviewThreads(
336
477
  // -review lock, and all three outrank a partial success — a round that
337
478
  // posted three of four comments has lost a finding and must say so.
338
479
  if (failed > 0) {
339
- return { outcome: "FAILED", attempted: requests.length, posted, demoted, detail };
480
+ return { outcome: "FAILED", attempted: requests.length, posted, demoted, pullComments, detail };
340
481
  }
341
482
  if (forbidden > 0) {
342
- return { outcome: "DEGRADED_NO_WRITE", attempted: requests.length, posted, demoted, detail };
483
+ return { outcome: "DEGRADED_NO_WRITE", attempted: requests.length, posted, demoted, pullComments, detail };
343
484
  }
344
485
  if (pending > 0) {
345
486
  return {
@@ -347,14 +488,16 @@ export async function postReviewThreads(
347
488
  attempted: requests.length,
348
489
  posted,
349
490
  demoted,
491
+ pullComments,
350
492
  detail,
351
493
  };
352
494
  }
353
495
  detail.push(
354
496
  `posted ${posted} review ${posted === 1 ? "comment" : "comments"}` +
355
- (demoted === 0 ? "" : `, ${demoted} at file level after a line was refused`),
497
+ (demoted === 0 ? "" : `, ${demoted} at file level after a line was refused`) +
498
+ (pullComments === 0 ? "" : `, ${pullComments} on the conversation because the file is not in this pull request's diff`),
356
499
  );
357
- return { outcome: "POSTED", attempted: requests.length, posted, demoted, detail };
500
+ return { outcome: "POSTED", attempted: requests.length, posted, demoted, pullComments, detail };
358
501
  }
359
502
 
360
503
  /**
@@ -0,0 +1,95 @@
1
+ /**
2
+ * The one writer of `blocked by` links — #2345.
3
+ *
4
+ * `gh issue edit --add-blocked-by` exists only in recent `gh` releases. A
5
+ * consumer's self-hosted runner with an older `gh` failed every edge of a
6
+ * 35-issue plan with `unknown flag: --add-blocked-by` (2026-11-17). `gh api`
7
+ * is in every release, so links are written through the REST dependencies
8
+ * endpoint instead, and the runner's `gh` version stops mattering.
9
+ *
10
+ * **`issue_id` is the blocker's DATABASE id, not its number.** A number is
11
+ * accepted too and links whichever issue has that database id — measured
12
+ * 2026-11-05, recorded in `scripts/board-walkthrough.ts`. So each blocker's id
13
+ * is read first, and the blocked issue's links are read back once all are
14
+ * written: every blocker must be there, or the write is refused, never
15
+ * reported as wired. The read-back and not the POST's reply, because GitHub's
16
+ * documentation does not say which of the two issues that reply describes.
17
+ *
18
+ * **Calls, per blocked issue:** one id read per blocker not yet in `ids` (a
19
+ * caller writing many groups passes one map, so a blocker shared by many
20
+ * issues is read once), one POST per link, and one read-back. The REST
21
+ * endpoint takes one link per call, so a group can no longer be one call the
22
+ * way `issue edit --add-blocked-by a --add-blocked-by b` was.
23
+ */
24
+
25
+ /** How a `gh` call is made. Injected so a test never shells out. */
26
+ export type GhExec = (args: readonly string[]) => string;
27
+
28
+ function databaseId(repo: string, blocker: number, exec: GhExec, ids: Map<string, number>): number {
29
+ // Keyed by repository too: a dependency may cross repositories, so the same
30
+ // number in another repository is another issue (review of #2357).
31
+ const key = `${repo}#${blocker}`;
32
+ const known = ids.get(key);
33
+ if (known !== undefined) return known;
34
+ const raw = exec(["api", `repos/${repo}/issues/${blocker}`, "--jq", ".id"]).trim();
35
+ const id = Number(raw);
36
+ if (!Number.isSafeInteger(id) || id <= 0) {
37
+ throw new Error(`#${blocker}: could not read its database id (got "${raw.slice(0, 40)}"), so no link was written`);
38
+ }
39
+ ids.set(key, id);
40
+ return id;
41
+ }
42
+
43
+ export function addBlockers(
44
+ repo: string,
45
+ blocked: number,
46
+ blockers: readonly number[],
47
+ exec: GhExec,
48
+ ids: Map<string, number> = new Map(),
49
+ ): void {
50
+ if (blockers.length === 0) return;
51
+ // Every id before any write, so an unreadable one writes nothing for this issue.
52
+ const resolved = blockers.map(b => ({ number: b, id: databaseId(repo, b, exec, ids) }));
53
+ for (const b of resolved) {
54
+ exec(["api", "-X", "POST", `repos/${repo}/issues/${blocked}/dependencies/blocked_by`, "-F", `issue_id=${b.id}`]);
55
+ }
56
+ // One number per line: `--paginate` concatenates pages, so one JSON document would not parse.
57
+ const linked = new Set(
58
+ exec(["api", "--paginate", `repos/${repo}/issues/${blocked}/dependencies/blocked_by?per_page=100`, "--jq", ".[].number"])
59
+ .split("\n")
60
+ .map(l => l.trim())
61
+ .filter(l => l !== "")
62
+ .map(Number),
63
+ );
64
+ const missing = blockers.filter(b => !linked.has(b));
65
+ if (missing.length > 0) {
66
+ throw new Error(
67
+ `#${blocked}: the writes returned, but ${missing.map(b => `#${b}`).join(", ")} ${missing.length === 1 ? "is" : "are"} not among its blockers ` +
68
+ `on read-back (${linked.size === 0 ? "none" : [...linked].map(n => `#${n}`).join(", ")})`,
69
+ );
70
+ }
71
+ }
72
+
73
+ /**
74
+ * Remove one `blocked by` link, through the same REST endpoint and by the same
75
+ * database id — `issue edit --remove-blocked-by` is missing from the same old
76
+ * `gh` (review of #2357). Read back afterwards: a link still there is refused.
77
+ */
78
+ export function removeBlocker(
79
+ repo: string,
80
+ blocked: number,
81
+ blocker: number,
82
+ exec: GhExec,
83
+ ids: Map<string, number> = new Map(),
84
+ ): void {
85
+ const id = databaseId(repo, blocker, exec, ids);
86
+ exec(["api", "-X", "DELETE", `repos/${repo}/issues/${blocked}/dependencies/blocked_by/${id}`]);
87
+ const linked = exec(["api", "--paginate", `repos/${repo}/issues/${blocked}/dependencies/blocked_by?per_page=100`, "--jq", ".[].number"])
88
+ .split("\n")
89
+ .map(l => l.trim())
90
+ .filter(l => l !== "")
91
+ .map(Number);
92
+ if (linked.includes(blocker)) {
93
+ throw new Error(`#${blocked}: the removal returned, but #${blocker} is still among its blockers on read-back`);
94
+ }
95
+ }
@@ -170,9 +170,17 @@ function unmeasuredSweep(reasons: string[]): SpecSweep {
170
170
  return { reading: "UNMEASURED", specs: [], ids: [], collisions: [], unmeasuredReasons: reasons };
171
171
  }
172
172
 
173
- export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDir): SpecSweep {
173
+ /**
174
+ * Which files under `<root>/specs` are specs — the ONE answer, shared by
175
+ * {@link specCriteriaIn} and `rungate board-scope` (#2275). It refuses only on
176
+ * what stops it locating a file; whether any spec states a criterion is the
177
+ * id sweep's question, not this one's.
178
+ */
179
+ export function specFilesIn(
180
+ root: string,
181
+ readDir: SpecDirReader = readSpecDir,
182
+ ): { reading: "MEASURED"; paths: string[] } | { reading: "UNMEASURED"; reasons: string[] } {
174
183
  const dir = join(root, "specs");
175
- let files: string[];
176
184
  try {
177
185
  const entries = readDir(dir).filter(e => e.isFile() && e.name.endsWith(".md"));
178
186
  // `parentPath` is the ONLY field that can be trusted to name a nested
@@ -189,23 +197,34 @@ export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDi
189
197
  // not a sweep with fewer specs in it.
190
198
  const unlocatable = unlocatableEntries(entries);
191
199
  if (unlocatable.length > 0) {
192
- return unmeasuredSweep([
193
- `this runtime does not report Dirent.parentPath, so ${unlocatable.length} spec file(s) ` +
194
- `under ${dir} cannot be located — a nested spec would be read as a top-level one. ` +
195
- `Nothing was read: ${unlocatable.map(e => e.name).sort().join(", ")}`,
196
- ]);
200
+ return {
201
+ reading: "UNMEASURED",
202
+ reasons: [
203
+ `this runtime does not report Dirent.parentPath, so ${unlocatable.length} spec file(s) ` +
204
+ `under ${dir} cannot be located — a nested spec would be read as a top-level one. ` +
205
+ `Nothing was read: ${unlocatable.map(e => e.name).sort().join(", ")}`,
206
+ ],
207
+ };
197
208
  }
198
209
  // `as string` rather than a second `typeof e.parentPath === "string"`:
199
210
  // the refusal above already decided that question for every entry here,
200
211
  // and a second decider answering it again is one no behavioural test can
201
212
  // tell apart from the first.
202
- files = entries
213
+ const paths = entries
203
214
  .map(e => relative(root, join(e.parentPath as string, e.name)).split(sep).join("/"))
204
215
  .filter(p => !(NOT_A_SPEC as readonly string[]).includes(p))
205
216
  .sort();
217
+ return { reading: "MEASURED", paths };
206
218
  } catch (e) {
207
- return unmeasuredSweep([`could not read ${dir}: ${(e as Error).message}`]);
219
+ return { reading: "UNMEASURED", reasons: [`could not read ${dir}: ${(e as Error).message}`] };
208
220
  }
221
+ }
222
+
223
+ export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDir): SpecSweep {
224
+ const dir = join(root, "specs");
225
+ const listed = specFilesIn(root, readDir);
226
+ if ("reasons" in listed) return unmeasuredSweep(listed.reasons);
227
+ const files = listed.paths;
209
228
 
210
229
  const specs: SpecCriteria[] = [];
211
230
  const reasons: string[] = [];
@@ -124,6 +124,17 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
124
124
  summary: "Report which success criteria are matched, unmatched or uncovered",
125
125
  usage: "rungate audit-specs",
126
126
  },
127
+ // #2360: a consumer ticks its own criteria from its own test claims. The
128
+ // script was in `files[]` and reachable from nothing, and it read
129
+ // `join(import.meta.dir, "..")` — run from node_modules it ticked nothing
130
+ // of the consumer's and reported on rungate's specs. `projectRootFlag` is
131
+ // load-bearing, as on `audit-spec-evidence`.
132
+ "sync-sc-status": {
133
+ script: "scripts/sync-sc-status.ts",
134
+ summary: "Tick each criterion a passing test claims, in this project's specs",
135
+ usage: "rungate sync-sc-status [--dry-run] [--report] [--only <SC-id,…>] [--project-root <dir>]",
136
+ projectRootFlag: true,
137
+ },
127
138
  // Registered because `create-spec` SHIPS and stamps every generated spec
128
139
  // with `evidence: required`, and this is the only thing that enforces that
129
140
  // key (#1639). Without the entry the published package emitted a document
@@ -227,7 +238,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
227
238
  // argument it would read as a positional.
228
239
  "board-conformance": {
229
240
  script: "scripts/board-conformance.ts",
230
- summary: "Does the board say what the spec says — every reading, and whether any is short of target",
241
+ summary: "Whether the board says what the spec says, reading by reading",
231
242
  usage: "rungate board-conformance [--reading <name>] [--snapshot <path>] [--list-readings]",
232
243
  },
233
244
  // Step 4 of ADR-003, in reverse. The issue template's own footer says a
@@ -239,11 +250,36 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
239
250
  "plan-issues": {
240
251
  script: "scripts/plan-issues.ts",
241
252
  summary:
242
- "Apply an approved issue plan — --decompose creates issues from criteria (step 4), --repair links and demotes existing ones",
253
+ "Apply an approved issue plan: --decompose files issues, --repair links and demotes them",
243
254
  usage:
244
255
  "rungate plan-issues (--repair | --decompose) <plan.md> --repo <owner/name> [--write] [--json]",
245
256
  projectRootFlag: true,
246
257
  },
258
+ // ADR-020 Decision 1 (SC-2782): every open `from-consumer` issue with no
259
+ // verdict marker gets exactly one, from `lib/consumer-triage.ts`. Reads the
260
+ // tracker AND the tree (the opted-in specs place an issue), hence the root flag.
261
+ "consumer-triage": {
262
+ script: "scripts/consumer-triage.ts",
263
+ summary: "Give each consumer-filed issue with no verdict exactly one",
264
+ usage: "rungate consumer-triage --repo <owner/name> [--write] [--json]",
265
+ projectRootFlag: true,
266
+ },
267
+ // #2275, onboarding existing specs. Read-only: what each spec holds, its
268
+ // `board:` setting, and a looks-done hint per unticked criterion. It never
269
+ // ticks. Reads the working directory, so it takes no root flag.
270
+ "board-scope": {
271
+ script: "scripts/board-scope.ts",
272
+ summary: "Spec criteria and opt-in, with looks-done hints",
273
+ usage: "rungate board-scope [--spec <path>] [--json]",
274
+ },
275
+ // #2330. The pinned "where we are" view as a command a consumer can run:
276
+ // every family's phases with their open issues and blockers. Reads the
277
+ // working directory and its origin remote, so it takes no root flag.
278
+ board: {
279
+ script: "scripts/status-view.ts",
280
+ summary: "Each phase's open issues and blockers",
281
+ usage: "rungate board [--repo <owner/name>] [--markdown] (repository defaults to GITHUB_REPOSITORY, then the origin remote)",
282
+ },
247
283
  // Step 5 of ADR-003. `plan-spec` turns the placement table into milestones;
248
284
  // this turns the ORDER of those milestones into `blocked by` edges, which is
249
285
  // AGENTS.md rule 4 — ordering is data, not prose.
@@ -302,7 +338,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
302
338
  // `projectRootFlag`: it reads `process.cwd()`, which the child inherits.
303
339
  "unaccounted-work": {
304
340
  script: "scripts/unaccounted-work.ts",
305
- summary: "Report undone work declared in a repository's prose that no open issue covers",
341
+ summary: "Undone work declared in prose that no open issue covers",
306
342
  usage:
307
343
  "rungate unaccounted-work [--project-root <dir>] [--repo <owner/name>] [--issues-fixture <file.json>] [--json] " +
308
344
  "(exit 1 when work is unaccounted, 2 when a source could not be read)",
@@ -312,7 +348,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
312
348
  // each intake source runs on its own trigger.
313
349
  intake: {
314
350
  script: "scripts/intake.ts",
315
- summary: "Run each intake source and print its reading — MEASURED with a count, or UNMEASURED naming why",
351
+ summary: "Run each intake source and print its reading, MEASURED or UNMEASURED",
316
352
  usage:
317
353
  "rungate intake [--project-root <dir>] [--source <id>] [--json] " +
318
354
  "(advisory: an unreadable source prints UNMEASURED and exits 0; exit 2 on a bad argument)",
@@ -107,7 +107,7 @@
107
107
  * measured before and after, and a single new entry reverts the write.
108
108
  */
109
109
  import { spawnSync } from "child_process";
110
- import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
110
+ import { existsSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
111
111
  import { join } from "path";
112
112
  import {
113
113
  DIRECTORY_CONFIG_FILES,
@@ -183,18 +183,34 @@ function matchedByIgnoreRules(root: string, paths: readonly string[]): Trackable
183
183
  return { ignored: paths.filter(p => matched.has(p)), failure: null };
184
184
  }
185
185
 
186
+ /** git's own refusal outside a repository: exit 128, and it says so. */
187
+ const NOT_A_REPOSITORY = /not a git repository/i;
188
+
189
+ /**
190
+ * Whether `root` is inside a work tree. "Outside" is only git's own exit-128
191
+ * refusal saying so, or a probe from inside `.git` itself; a git that could
192
+ * not run, or failed any other way, is a failure string, never "outside"
193
+ * (review of #2359 — the same fail-open in two callers).
194
+ */
195
+ function workTreeProbe(root: string): "inside" | "outside" | { failure: string } {
196
+ const r = git(root, ["rev-parse", "--is-inside-work-tree"]);
197
+ if (r.status === 128 && NOT_A_REPOSITORY.test(r.stderr)) return "outside";
198
+ if (r.status !== 0) return { failure: `git rev-parse failed (${r.status}): ${r.stderr.trim() || "no output"}` };
199
+ return r.stdout.trim() === "true" ? "inside" : "outside";
200
+ }
201
+
186
202
  /**
187
203
  * Whether this project's ignore rules mark the rungate config disposable.
188
204
  *
189
205
  * A project that is not a git repository has no ignore rules and nothing can
190
206
  * delete the file on a checkout, so that is `{ ignored: [], failure: null }`
191
- * and not an error — the harness scaffolds into trees that are not repos.
207
+ * and not an error — the harness scaffolds into trees that are not repos. A
208
+ * git that cannot answer is a `failure`, not that case.
192
209
  */
193
210
  export function configPathsIgnored(root: string): TrackableReading {
194
- const inside = git(root, ["rev-parse", "--is-inside-work-tree"]);
195
- if (inside.status !== 0 || inside.stdout.trim() !== "true") {
196
- return { ignored: [], failure: null };
197
- }
211
+ const probe = workTreeProbe(root);
212
+ if (probe === "outside") return { ignored: [], failure: null };
213
+ if (probe !== "inside") return { ignored: [], failure: probe.failure };
198
214
  return matchedByIgnoreRules(root, RUNGATE_CONFIG_IGNORE_PATHS);
199
215
  }
200
216
 
@@ -437,3 +453,72 @@ export function ensureConfigTrackable(
437
453
  `and is now committable; commit it, or the next branch switch deletes it)`,
438
454
  );
439
455
  }
456
+
457
+ /**
458
+ * The concrete files a set of owned-file rows names on disk. A row is a path,
459
+ * or a `<dir>/*<ext>` class (`.claude/agents/*.md`), expanded to the files of
460
+ * that directory with that extension. Absent files are left out: an ignore
461
+ * rule only matters for a file that was written. A directory that exists but
462
+ * cannot be listed is a `failure`, not an absence (review of #2359): only
463
+ * ENOENT means nothing was written there.
464
+ */
465
+ function ownedPathsOnDisk(root: string, rows: readonly string[]): { paths: string[]; failures: string[] } {
466
+ const out: string[] = [];
467
+ const failures: string[] = [];
468
+ for (const row of rows) {
469
+ const star = row.lastIndexOf("/*");
470
+ if (star === -1) {
471
+ if (existsSync(join(root, row))) out.push(row);
472
+ continue;
473
+ }
474
+ const dir = row.slice(0, star);
475
+ const ext = row.slice(star + 2);
476
+ let names: string[];
477
+ try {
478
+ names = readdirSync(join(root, dir));
479
+ } catch (e) {
480
+ const code = (e as NodeJS.ErrnoException).code;
481
+ // ENOENT: the directory was not written, so nothing in it can be ignored.
482
+ if (code !== "ENOENT") failures.push(`${dir} could not be listed (${code ?? (e as Error).message})`);
483
+ continue;
484
+ }
485
+ for (const n of names.sort()) if (n.endsWith(ext)) out.push(`${dir}/${n}`);
486
+ }
487
+ return { paths: out, failures };
488
+ }
489
+
490
+ /**
491
+ * #2347: name every owned file this scaffold left in a path the project's
492
+ * ignore rules match. Such a file is written, never committed, and so never
493
+ * ships, which on one consumer was the `/dry-run` command (`.claude/*`
494
+ * ignored, agents and rules negated, commands not). It only reports: whether
495
+ * scaffold should also make the path trackable is a decision recorded on
496
+ * #2347, not taken here. A tree that is not a repository has no ignore rules
497
+ * and gets no line; a git that cannot answer gets an UNMEASURED line, never
498
+ * a clean silence. "Not a repository" is only git's own exit-128 refusal
499
+ * saying so; a git that could not run, or failed any other way, is
500
+ * UNMEASURED (review of #2359).
501
+ */
502
+ export function reportIgnoredOwnedFiles(root: string, actions: string[], rows: readonly string[]): void {
503
+ const unmeasured = (why: string) =>
504
+ actions.push(`UNMEASURED: whether any file scaffold owns is ignored could not be read — ${why}`);
505
+ const probe = workTreeProbe(root);
506
+ if (probe === "outside") return;
507
+ if (probe !== "inside") {
508
+ unmeasured(probe.failure);
509
+ return;
510
+ }
511
+ const owned = ownedPathsOnDisk(root, rows);
512
+ for (const f of owned.failures) unmeasured(f);
513
+ const reading = matchedByIgnoreRules(root, owned.paths);
514
+ if (reading.failure !== null) {
515
+ unmeasured(reading.failure);
516
+ return;
517
+ }
518
+ for (const path of reading.ignored) {
519
+ actions.push(
520
+ `IGNORED: ${path} is written by scaffold, but this project's ignore rules match it, so it will not be ` +
521
+ `committed and will not ship; \`git check-ignore -v ${path}\` names the rule, and a \`!\` line after it un-ignores the path`,
522
+ );
523
+ }
524
+ }