rungate 0.8.13 → 0.8.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -14,6 +14,7 @@
14
14
  * "not found — role not registered", naming a file the project is documented
15
15
  * not to have. The brief was written and the role was registered nowhere.
16
16
  */
17
+ import { spawnSync } from "child_process";
17
18
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
18
19
  import { join } from "path";
19
20
  import { z } from "zod";
@@ -205,47 +206,280 @@ function normaliseConfig(raw: unknown): ResolvedConfig {
205
206
  }
206
207
 
207
208
  /**
208
- * The single resolution point. Directory form wins over the monolith.
209
+ * How the layout rules reach the config files: the working tree, or one
210
+ * commit (#1964). The rules themselves — directory form wins, the monolith is
211
+ * the fallback, fragments with no config.json refuse — live once, in
212
+ * {@link resolveWith}, so the working-tree read and the committed read cannot
213
+ * disagree about which layout a project is on. Two copies of those rules
214
+ * would be two deciders, and a consumer on the layout one of them dropped
215
+ * would silently get no config from it.
209
216
  */
210
- export function resolveConfig(projectRoot: string): ConfigResolution {
211
- const dirPath = join(projectRoot, ".claude", "rungate");
212
- const monolithPath = join(projectRoot, ".claude", "rungate.json");
217
+ interface ConfigFileAccess {
218
+ exists(rel: string): boolean;
219
+ read(rel: string): string;
220
+ /** What a resolution's `path` reports, and what an error names. */
221
+ locate(rel: string): string;
222
+ }
223
+
224
+ const DIR_REL = ".claude/rungate";
225
+ const MONOLITH_REL = ".claude/rungate.json";
226
+
227
+ function treeAccess(projectRoot: string): ConfigFileAccess {
228
+ return {
229
+ exists: rel => existsSync(join(projectRoot, rel)),
230
+ read: rel => readFileSync(join(projectRoot, rel), "utf-8"),
231
+ locate: rel => join(projectRoot, rel),
232
+ };
233
+ }
213
234
 
235
+ function resolveWith(files: ConfigFileAccess): ConfigResolution {
214
236
  // config.json is the sole marker for the directory form. Treating any
215
237
  // fragment as the marker let a stray roles.json shadow a complete monolith
216
238
  // and silently drop issueRepo/ci/test — ADR-001 Step E keeps the monolith
217
239
  // in place during migration, so that state is on the normal upgrade path.
218
- if (existsSync(join(dirPath, "config.json"))) {
240
+ if (files.exists(`${DIR_REL}/config.json`)) {
219
241
  return {
220
242
  status: "resolved",
221
- config: loadFromDirectory(dirPath),
243
+ config: loadFromDirectory(files),
222
244
  source: "directory",
223
- path: dirPath,
245
+ path: files.locate(DIR_REL),
224
246
  };
225
247
  }
226
248
 
227
- if (existsSync(monolithPath)) {
249
+ if (files.exists(MONOLITH_REL)) {
228
250
  return {
229
251
  status: "resolved",
230
- config: loadFromMonolith(monolithPath),
252
+ config: loadFromMonolith(files),
231
253
  source: "monolith",
232
- path: monolithPath,
254
+ path: files.locate(MONOLITH_REL),
233
255
  };
234
256
  }
235
257
 
236
258
  // Fragments with no config.json and no monolith is a broken directory
237
259
  // config, not an unconfigured project. Fail loudly rather than reporting
238
260
  // absent, which the caller would read as "no rungate here".
239
- const orphans = DIRECTORY_CONFIG_FILES.filter((file) => existsSync(join(dirPath, file)));
261
+ const orphans = DIRECTORY_CONFIG_FILES.filter(file => files.exists(`${DIR_REL}/${file}`));
240
262
  if (orphans.length > 0) {
241
263
  throw new Error(
242
- `Incomplete rungate config at ${dirPath}: found ${orphans.join(", ")} but no config.json`
264
+ `Incomplete rungate config at ${files.locate(DIR_REL)}: found ${orphans.join(", ")} but no config.json`
243
265
  );
244
266
  }
245
267
 
246
268
  return { status: "absent" };
247
269
  }
248
270
 
271
+ /**
272
+ * The single resolution point. Directory form wins over the monolith.
273
+ */
274
+ export function resolveConfig(projectRoot: string): ConfigResolution {
275
+ return resolveWith(treeAccess(projectRoot));
276
+ }
277
+
278
+ /**
279
+ * One commit's files, as {@link readCommittedConfig} needs them (#1964).
280
+ * Injected so a test can hand it a fixture; {@link gitCommittedFiles} is the
281
+ * live one.
282
+ */
283
+ export interface CommittedFiles {
284
+ /** The revision read, named in every message. */
285
+ ref: string;
286
+ /** Whether the revision resolves at all — false for no git, no remote, a ref never fetched. */
287
+ readable: boolean;
288
+ /** A path's content at the revision, relative to the tree's root, or `null` when it is not there. */
289
+ show: (rel: string) => string | null;
290
+ /** Why the revision could not be read, when the reader knows better than "does not resolve". */
291
+ unreadableWhy?: string;
292
+ }
293
+
294
+ /** Bounds each `git` call, so a wedged repository cannot hang the filing hook. */
295
+ export const COMMITTED_READ_TIMEOUT_MS = 10_000;
296
+
297
+ /** The remote's `main` as a commit this checkout holds, or why it could not be read. */
298
+ export type RemoteMain = { readonly sha: string } | { readonly unread: string };
299
+
300
+ /**
301
+ * The one trust anchor for "committed" — #2095.
302
+ *
303
+ * Both readers of committed state, the filing cap's config here and the plan
304
+ * exemption's `gitSource` in `lib/filing-plan.ts`, used to read the local
305
+ * `refs/remotes/origin/main`. That ref is local state: an agent can commit
306
+ * `ship.mode: "direct"` and run `git update-ref refs/remotes/origin/main
307
+ * HEAD`, with no push, no network and no review, and the gate read the
308
+ * forgery as committed. `lib/verified-push.ts` already says the same of a
309
+ * remote-tracking ref: it cannot say whether a commit ever left the machine.
310
+ *
311
+ * So the anchor is what the REMOTE says its `main` is (`git ls-remote`), read
312
+ * at that object — which a local forgery cannot produce. The object must be
313
+ * in this checkout, or nothing can be read from it.
314
+ *
315
+ * **Every failure is `unread`, and the callers take the strict reading**: no
316
+ * remote, an unreachable one, a remote with no `main`, or an object never
317
+ * fetched. Never the local ref as a fallback, which would reopen the hole.
318
+ *
319
+ * **Residual risk, stated:** `git remote set-url origin <a repository the
320
+ * agent controls>`, or an `insteadOf` rewrite, moves the anchor itself. Run
321
+ * identity reads the CONFIGURED URL (`readWorktreeRemote`), so a rewrite
322
+ * cannot also change which allowance is spent, but the content read here
323
+ * follows wherever the remote points.
324
+ */
325
+ export function remoteMainCommit(root: string): RemoteMain {
326
+ const listed = spawnSync("git", ["-C", root, "ls-remote", "origin", "refs/heads/main"], {
327
+ encoding: "utf-8",
328
+ timeout: COMMITTED_READ_TIMEOUT_MS,
329
+ // A hook has no one to answer a credential prompt; fail instead of waiting.
330
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
331
+ });
332
+ if (listed.error !== undefined || listed.status !== 0) {
333
+ return { unread: "the remote's main could not be read (`git ls-remote origin refs/heads/main` failed)" };
334
+ }
335
+ const sha = /^([0-9a-f]{40,64})\trefs\/heads\/main$/m.exec(String(listed.stdout ?? ""))?.[1];
336
+ if (sha === undefined) return { unread: "the remote names no refs/heads/main" };
337
+ const held = spawnSync("git", ["-C", root, "cat-file", "-e", `${sha}^{commit}`], {
338
+ timeout: COMMITTED_READ_TIMEOUT_MS,
339
+ });
340
+ if (held.error !== undefined || held.status !== 0) {
341
+ return { unread: `the remote's main is ${sha.slice(0, 12)}, which this checkout does not have — fetch it` };
342
+ }
343
+ return { sha };
344
+ }
345
+
346
+ /**
347
+ * `git`, reading the commit the remote's `main` names ({@link remoteMainCommit})
348
+ * and never the working tree or the local `origin/main` ref — the same anchor
349
+ * `gitSource` in `lib/filing-plan.ts` gives the plan route. A caller that
350
+ * reads both passes ONE `anchor` to each, so they cannot straddle a merge
351
+ * (review of #2140). Paths in `<sha>:path` are taken from the tree's root, so
352
+ * a `root` below the top level reads the same files.
353
+ */
354
+ export function gitCommittedFiles(root: string, anchor: RemoteMain = remoteMainCommit(root)): CommittedFiles {
355
+ if ("unread" in anchor) {
356
+ return { ref: "origin/main", readable: false, show: () => null, unreadableWhy: anchor.unread };
357
+ }
358
+ return committedFilesAt(root, anchor.sha, `origin/main@${anchor.sha.slice(0, 12)}`);
359
+ }
360
+
361
+ /** Every config file a layout can be made of, read at one commit. */
362
+ function committedFilesAt(root: string, sha: string, ref: string): CommittedFiles {
363
+ // ONE `git cat-file --batch` resolves the revision and reads every file a
364
+ // layout can be made of. The filing gate runs as a PreToolUse hook on every
365
+ // `gh issue create`, and a spawn per file cost five processes a filing.
366
+ // A name the commit does not have comes back `<name> missing`; a revision
367
+ // that does not resolve makes its `^{commit}` line missing too.
368
+ const paths = [...DIRECTORY_CONFIG_FILES.map(file => `${DIR_REL}/${file}`), MONOLITH_REL];
369
+ // Named by the SHA, never by `ref`: `ref` is the label for messages, and
370
+ // resolving a ref name here would read local state again.
371
+ const names = [`${sha}^{commit}`, ...paths.map(p => `${sha}:${p}`)];
372
+ const r = spawnSync("git", ["-C", root, "cat-file", "--batch"], {
373
+ input: names.join("\n") + "\n",
374
+ timeout: COMMITTED_READ_TIMEOUT_MS,
375
+ maxBuffer: 16 * 1024 * 1024,
376
+ });
377
+ if (r.error !== undefined || r.status !== 0 || !Buffer.isBuffer(r.stdout)) {
378
+ return { ref, readable: false, show: () => null };
379
+ }
380
+ const out = r.stdout;
381
+ const results: (string | null)[] = [];
382
+ let at = 0;
383
+ for (let i = 0; i < names.length; i++) {
384
+ const eol = out.indexOf(0x0a, at);
385
+ if (eol === -1) return { ref, readable: false, show: () => null };
386
+ const header = out.subarray(at, eol).toString("utf-8");
387
+ at = eol + 1;
388
+ // `<name> missing` / `<name> ambiguous` carry no body. Anything else is
389
+ // `<oid> <type> <size>`, then exactly `size` bytes, then a newline.
390
+ if (header.endsWith(" missing") || header.endsWith(" ambiguous")) {
391
+ results.push(null);
392
+ continue;
393
+ }
394
+ const size = Number(header.split(" ")[2]);
395
+ if (!Number.isInteger(size) || size < 0) return { ref, readable: false, show: () => null };
396
+ results.push(out.subarray(at, at + size).toString("utf-8"));
397
+ at += size + 1;
398
+ }
399
+ const readable = results[0] !== null;
400
+ const content = new Map(paths.map((p, i) => [p, results[i + 1] ?? null]));
401
+ return { ref, readable, show: rel => (readable ? (content.get(rel) ?? null) : null) };
402
+ }
403
+
404
+ /**
405
+ * The config as COMMITTED, never as the working tree has it (#1964, SC-2753).
406
+ *
407
+ * Three states, and `unreadable` is not `absent`. A revision that does not
408
+ * resolve, a malformed file and orphaned fragments are all `unreadable`,
409
+ * carrying why — a caller that folded them into `absent` would hand an
410
+ * unscaffolded tree's defaults to a project whose config simply could not be
411
+ * read, which is *Silent Default Substitution*. The error is caught here only
412
+ * to be NAMED, never dropped (`.claude/rules/config-access.md`).
413
+ */
414
+ export type CommittedConfigReading =
415
+ | { status: "resolved"; config: ResolvedConfig; source: "directory" | "monolith"; ref: string }
416
+ | { status: "absent"; ref: string }
417
+ /**
418
+ * `kind` says WHICH failure: `ref` — the revision itself does not resolve,
419
+ * so nothing was read; `content` — the commit carries a config that will
420
+ * not resolve (malformed JSON, a failed schema, orphaned fragments). They
421
+ * need different repairs, so a caller's message must be able to tell them
422
+ * apart.
423
+ */
424
+ | { status: "unreadable"; kind: "ref" | "content"; ref: string; why: string };
425
+
426
+ export function readCommittedConfig(files: CommittedFiles): CommittedConfigReading {
427
+ if (!files.readable) {
428
+ return {
429
+ status: "unreadable",
430
+ kind: "ref",
431
+ ref: files.ref,
432
+ why: files.unreadableWhy ?? `${files.ref} does not resolve here — no git, no remote, or never fetched`,
433
+ };
434
+ }
435
+ const cache = new Map<string, string | null>();
436
+ const get = (rel: string): string | null => {
437
+ if (!cache.has(rel)) cache.set(rel, files.show(rel));
438
+ return cache.get(rel) ?? null;
439
+ };
440
+ const access: ConfigFileAccess = {
441
+ exists: rel => get(rel) !== null,
442
+ read: rel => {
443
+ const content = get(rel);
444
+ if (content === null) throw new Error(`${files.ref}:${rel} is not in the commit`);
445
+ return content;
446
+ },
447
+ locate: rel => `${files.ref}:${rel}`,
448
+ };
449
+ try {
450
+ const r = resolveWith(access);
451
+ return r.status === "resolved"
452
+ ? { status: "resolved", config: r.config, source: r.source, ref: files.ref }
453
+ : { status: "absent", ref: files.ref };
454
+ } catch (e) {
455
+ return { status: "unreadable", kind: "content", ref: files.ref, why: (e as Error).message };
456
+ }
457
+ }
458
+
459
+ /** Thrown by {@link committedConfig} for an unreadable reading, so a thunk-taking reader can name it. */
460
+ export class CommittedConfigUnreadable extends Error {
461
+ constructor(
462
+ readonly kind: "ref" | "content",
463
+ readonly ref: string,
464
+ readonly why: string,
465
+ ) {
466
+ super(`the committed config at ${ref} could not be read: ${why}`);
467
+ this.name = "CommittedConfigUnreadable";
468
+ }
469
+ }
470
+
471
+ /**
472
+ * The config a committed reading resolved, `null` for a commit that carries
473
+ * none, and a THROW for one that could not be read — the same three-way
474
+ * contract as {@link tryLoadRungateConfig}, so the readers that take a
475
+ * loading thunk (`filingsPerRunFor`, `queueLabelFor`) treat it exactly as
476
+ * they treat a malformed working-tree config: strict.
477
+ */
478
+ export function committedConfig(reading: CommittedConfigReading): ResolvedConfig | null {
479
+ if (reading.status === "unreadable") throw new CommittedConfigUnreadable(reading.kind, reading.ref, reading.why);
480
+ return reading.status === "resolved" ? reading.config : null;
481
+ }
482
+
249
483
  export function loadRungateConfig(projectRoot: string): ResolvedConfig {
250
484
  const dirPath = join(projectRoot, ".claude", "rungate");
251
485
  const monolithPath = join(projectRoot, ".claude", "rungate.json");
@@ -269,23 +503,18 @@ export function tryLoadRungateConfig(projectRoot: string): ResolvedConfig | null
269
503
  return resolution.status === "resolved" ? resolution.config : null;
270
504
  }
271
505
 
272
- function loadFromDirectory(dirPath: string): ResolvedConfig {
273
- const config = readJson(join(dirPath, "config.json"));
274
- const roles = existsSync(join(dirPath, "roles.json"))
275
- ? readJson(join(dirPath, "roles.json"))
276
- : {};
277
- const hooks = existsSync(join(dirPath, "hooks.json"))
278
- ? readJson(join(dirPath, "hooks.json"))
279
- : [];
280
- const compliance = existsSync(join(dirPath, "compliance.json"))
281
- ? readJson(join(dirPath, "compliance.json"))
282
- : undefined;
506
+ function loadFromDirectory(files: ConfigFileAccess): ResolvedConfig {
507
+ const json = (file: string) => JSON.parse(files.read(`${DIR_REL}/${file}`));
508
+ const config = json("config.json");
509
+ const roles = files.exists(`${DIR_REL}/roles.json`) ? json("roles.json") : {};
510
+ const hooks = files.exists(`${DIR_REL}/hooks.json`) ? json("hooks.json") : [];
511
+ const compliance = files.exists(`${DIR_REL}/compliance.json`) ? json("compliance.json") : undefined;
283
512
 
284
513
  return normaliseConfig({ ...config, roles, hooks, compliance });
285
514
  }
286
515
 
287
- function loadFromMonolith(path: string): ResolvedConfig {
288
- return normaliseConfig(readJson(path));
516
+ function loadFromMonolith(files: ConfigFileAccess): ResolvedConfig {
517
+ return normaliseConfig(JSON.parse(files.read(MONOLITH_REL)));
289
518
  }
290
519
 
291
520
  function readJson(path: string): any {
@@ -37,7 +37,7 @@
37
37
  * pre-flight hosts. The documented migration switched the features off.
38
38
  */
39
39
 
40
- import { tryLoadRungateConfig } from "./config-loader";
40
+ import { resolveConfig, tryLoadRungateConfig } from "./config-loader";
41
41
  import type { RoleConfig } from "./rungate-schema";
42
42
 
43
43
  /**
@@ -88,21 +88,134 @@ export function readProjectSlug(projectRoot: string): string | null {
88
88
  * as blank with nothing saying so.
89
89
  */
90
90
  export function readBoardConfig(projectRoot: string): { projectId: string; criteriaFieldId: string } | null {
91
- const config = tryLoadRungateConfig(projectRoot);
92
- const board = (config as Record<string, unknown> | null)?.board;
93
- if (!board || typeof board !== "object" || Array.isArray(board)) return null;
94
- const row = board as Record<string, unknown>;
91
+ const row = boardBlock(projectRoot);
92
+ if (row === null) return null;
95
93
  const fields = row.fields;
96
94
  const criteria =
97
95
  fields && typeof fields === "object" && !Array.isArray(fields)
98
96
  ? (fields as Record<string, unknown>).Criteria
99
97
  : undefined;
100
- const projectId = typeof row.id === "string" ? row.id.trim() : "";
98
+ const projectId = projectIdIn(row);
101
99
  const criteriaFieldId = typeof criteria === "string" ? criteria.trim() : "";
102
- if (projectId === "" || criteriaFieldId === "") return null;
100
+ if (projectId === null || criteriaFieldId === "") return null;
103
101
  return { projectId, criteriaFieldId };
104
102
  }
105
103
 
104
+ /**
105
+ * The project board's node id, `board.id`, and nothing else — #1719, SC-2621.
106
+ *
107
+ * For a reader that addresses the board and reads no custom field
108
+ * (`scripts/work-status.ts`, `scripts/board-status-sweep.ts`): requiring the
109
+ * Criteria field id too, as {@link readBoardConfig} does, would refuse a board
110
+ * those readers can read perfectly well. Both readers decide the id here, in
111
+ * `projectIdIn`, so they cannot disagree about what counts as one.
112
+ *
113
+ * `null` for no config, no `board` block, or a blank id. Never a literal: until
114
+ * #1719 both scripts spelled this repository's node id, so a consumer, or a
115
+ * session told nothing, read OUR board under its own name.
116
+ */
117
+ export function readBoardProjectId(projectRoot: string): string | null {
118
+ const row = boardBlock(projectRoot);
119
+ return row === null ? null : projectIdIn(row);
120
+ }
121
+
122
+ /** The resolved config's `board` block, or `null` when there is none to read. */
123
+ function boardBlock(projectRoot: string): Record<string, unknown> | null {
124
+ const config = tryLoadRungateConfig(projectRoot);
125
+ const board = (config as Record<string, unknown> | null)?.board;
126
+ if (!board || typeof board !== "object" || Array.isArray(board)) return null;
127
+ return board as Record<string, unknown>;
128
+ }
129
+
130
+ /** `board.id`, trimmed; blank and non-string are `null`. The one decider for both readers. */
131
+ function projectIdIn(row: Record<string, unknown>): string | null {
132
+ const id = typeof row.id === "string" ? row.id.trim() : "";
133
+ return id === "" ? null : id;
134
+ }
135
+
136
+ /**
137
+ * The two inputs `board-snapshot` cannot take a reading without: which spec
138
+ * the board is supposed to mirror, and the milestone-name prefix that defines
139
+ * the population it is scored over.
140
+ *
141
+ * **Why this exists at all (#1718, SC-2619).** Both arrived only as command
142
+ * line arguments, so `rungate board-conformance` with no flags produced five
143
+ * UNMEASURED readings whose stated reason was `B1 has not wired this
144
+ * reading's source yet` — a sentence about the tool being unfinished, for a
145
+ * tool that was finished. The real cause was that nobody had passed a spec.
146
+ * A status command that misattributes its own silence is worse than one that
147
+ * refuses, and that is the whole of what this project is trying to stop.
148
+ *
149
+ * **Absent is `null`, per key, and never a literal.** `"Pipeline"` and this
150
+ * repository's own engine spec are the obvious defaults and both are wrong to
151
+ * bake in: a consumer that scaffolded rungate and never configured a board has
152
+ * no engine spec, and handing it ours would score its board against a
153
+ * document it does not have. Absent must stay nameable by the caller —
154
+ * *Silent Default Substitution*, `.claude/rules/config-access.md`.
155
+ *
156
+ * Blank and whitespace are `null` too, for the reason `readMilestonePrefix`
157
+ * already encodes: a prefix of `" "` matches no milestone on any board and
158
+ * reports every phase as missing.
159
+ */
160
+ export function readBoardInputs(projectRoot: string): {
161
+ engineSpec: string | null;
162
+ milestonePrefix: string | null;
163
+ } {
164
+ const config = tryLoadRungateConfig(projectRoot);
165
+ const board = (config as Record<string, unknown> | null)?.board;
166
+ if (!board || typeof board !== "object" || Array.isArray(board)) {
167
+ return { engineSpec: null, milestonePrefix: null };
168
+ }
169
+ const row = board as Record<string, unknown>;
170
+ const read = (key: string): string | null => {
171
+ const raw = row[key];
172
+ if (typeof raw !== "string") return null;
173
+ const value = raw.trim();
174
+ return value === "" ? null : value;
175
+ };
176
+ return { engineSpec: read("engineSpec"), milestonePrefix: read("milestonePrefix") };
177
+ }
178
+
179
+ /**
180
+ * The engine milestone family, AND whether the absence of one was measured.
181
+ *
182
+ * **Round 2 of #1965's review, and the finding was right.** The two scripts
183
+ * that order Ready read `readBoardInputs(process.cwd()).milestonePrefix`, and
184
+ * `readBoardInputs` returns `{milestonePrefix: null}` for a config it could
185
+ * not find at all — the same value a tree that genuinely declares no engine
186
+ * family gets. A `null` prefix means *order by phase alone*, which is exactly
187
+ * the pre-#1943 behaviour this work exists to remove. So a run from the wrong
188
+ * working directory — a wrapper, a cron job, a CI `working-directory` — turns
189
+ * the fix off and reports the payload above the engine again, with nothing
190
+ * saying it did. `.claude/rules/config-access.md` names that: *Silent Default
191
+ * Substitution*, reached through `process.cwd()` rather than a missing key.
192
+ *
193
+ * Two `null`s with different meanings is the whole defect, so this returns
194
+ * both the value and the reading. `resolveConfig` is what separates them —
195
+ * the documented reporter for *which case did I hit* — rather than a second
196
+ * existence check compiled here.
197
+ *
198
+ * `unmeasured` is a MESSAGE and not a boolean, because a warning that does
199
+ * not name the directory it read is a warning nobody can act on: the whole
200
+ * failure is that the directory was not the one the caller assumed.
201
+ */
202
+ export function enginePrefixReading(projectRoot: string): {
203
+ prefix: string | null;
204
+ unmeasured: string | null;
205
+ } {
206
+ const prefix = readBoardInputs(projectRoot).milestonePrefix;
207
+ if (prefix !== null) return { prefix, unmeasured: null };
208
+ if (resolveConfig(projectRoot).status !== "absent") return { prefix: null, unmeasured: null };
209
+ return {
210
+ prefix: null,
211
+ unmeasured:
212
+ `UNMEASURED: no rungate config under ${projectRoot}, so the engine milestone ` +
213
+ `family could not be read. Ready is ordered by phase number alone, which ranks ` +
214
+ `another family's lower phase above the engine's higher one (#1943). Run this from ` +
215
+ `the project root.`,
216
+ };
217
+ }
218
+
106
219
  /**
107
220
  * The label that marks an issue as being in the work queue, or `null`.
108
221
  *
@@ -124,10 +237,57 @@ export function readBoardConfig(projectRoot: string): { projectId: string; crite
124
237
  * got an empty queue, it has no queue.
125
238
  */
126
239
  export function readQueueLabel(projectRoot: string): string | null {
127
- const config = tryLoadRungateConfig(projectRoot);
128
- const board = (config as Record<string, unknown> | null)?.board;
240
+ return queueLabelIn(tryLoadRungateConfig(projectRoot));
241
+ }
242
+
243
+ /**
244
+ * The same queue label, read out of a config already loaded — #1964.
245
+ *
246
+ * The filing gate must take the label from COMMITTED config (SC-2753), so it
247
+ * loads that itself and asks here. The extraction stays one function, so the
248
+ * gate and every working-tree reader above agree on what the label is called
249
+ * and differ only in which copy of the config they were handed.
250
+ */
251
+ export function queueLabelIn(config: unknown): string | null {
252
+ return boardLabelIn(config, "queueLabel");
253
+ }
254
+
255
+ /**
256
+ * The label that promotes an issue to the top of Ready, or `null` (SC-2735).
257
+ *
258
+ * It was the constant `WORK_NEXT_LABEL` in `lib/board-ready-rule.ts`, so a
259
+ * consumer repository could not rename it and the library decided a
260
+ * project's vocabulary. `null` is the honest reading for a tree that never
261
+ * configured one: nothing can be promoted, and `workNextReading` says so as
262
+ * `UNCONFIGURED` rather than honouring a name the project never chose.
263
+ */
264
+ export function readExpediteLabel(projectRoot: string): string | null {
265
+ return readBoardLabel(projectRoot, "expediteLabel");
266
+ }
267
+
268
+ /**
269
+ * The label that waives a FindingArbiter refusal on a filing, or `null`
270
+ * (SC-2735).
271
+ *
272
+ * It was the constant `FILING_OVERRIDE_LABEL` in `lib/issue-filing-gate.ts`.
273
+ * `null` means **no waiver exists**, and that is the direction that matters:
274
+ * a built-in name substituted for absent config would hand every
275
+ * unscaffolded repository a way past the gate that its own config never
276
+ * declared — *Silent Default Substitution*, `.claude/rules/config-access.md`.
277
+ */
278
+ export function readFilingOverrideLabel(projectRoot: string): string | null {
279
+ return readBoardLabel(projectRoot, "filingOverrideLabel");
280
+ }
281
+
282
+ /** One `board.<key>` label: absent, blank and non-string are all `null`. */
283
+ function readBoardLabel(projectRoot: string, key: string): string | null {
284
+ return boardLabelIn(tryLoadRungateConfig(projectRoot), key);
285
+ }
286
+
287
+ function boardLabelIn(config: unknown, key: string): string | null {
288
+ const board = (config as Record<string, unknown> | null | undefined)?.board;
129
289
  if (!board || typeof board !== "object" || Array.isArray(board)) return null;
130
- const raw = (board as Record<string, unknown>).queueLabel;
290
+ const raw = (board as Record<string, unknown>)[key];
131
291
  if (typeof raw !== "string") return null;
132
292
  const label = raw.trim();
133
293
  return label === "" ? null : label;