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
@@ -32,12 +32,16 @@
32
32
  * A producer that repaired the thing it measures would make the reading
33
33
  * true by taking it.
34
34
  */
35
+ import { spawnSync } from "child_process";
35
36
  import { existsSync, readFileSync } from "fs";
36
37
  import { isAbsolute, join } from "path";
37
38
  import { parseArgs } from "util";
39
+ import { describeSpecSource, resolveSpecSource, type GitRunner } from "../lib/spec-source";
38
40
  import { openFrontier, phaseOf } from "../lib/board-mirror";
41
+ import { withoutAmbientGitOverrides } from "../lib/git-isolation";
39
42
  import { createGitHubClient, listMilestones } from "../lib/github";
40
- import { readBoardConfig, readQueueLabel } from "../lib/config-readers";
43
+ import { readBoardConfig, readBoardInputs, readQueueLabel } from "../lib/config-readers";
44
+ import { resolveRepoSlug } from "../lib/branch-cleanup";
41
45
  import {
42
46
  inMilestoneFamily,
43
47
  readIssueStates,
@@ -48,7 +52,18 @@ import {
48
52
  type LiveIssue,
49
53
  type ProjectFieldReading,
50
54
  } from "../lib/live-issues";
51
- import { criterionCoverage, milestonePlan, placementReading, type CriterionCoverage } from "../lib/spec-placement";
55
+ import {
56
+ criterionCoverage,
57
+ milestonePlan,
58
+ placementCoverage,
59
+ placementReading,
60
+ type CriterionCoverage,
61
+ } from "../lib/spec-placement";
62
+ // SC-2615, SC-2616, SC-2617 — the three repository-wide populations.
63
+ import { answerableIds, criterionAnswer, specCriteriaIn, specPathSweep } from "../lib/board-mirror";
64
+ import { dependencyPlan } from "../lib/spec-deps";
65
+ import type { DeclaredWork, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
66
+ import { parseCriteria } from "../lib/spec-evidence";
52
67
 
53
68
  /**
54
69
  * THE one non-zero exit, declared once so `test/board-snapshot.test.ts` can
@@ -208,9 +223,267 @@ export interface ProducedSnapshot {
208
223
  * {@link criterionCoverage}, which owns that decision.
209
224
  */
210
225
  criteria: CriterionCoverage[];
226
+ /**
227
+ * The three REPOSITORY-WIDE populations — SC-2615, SC-2616, SC-2617.
228
+ *
229
+ * Optional in the type because they are optional on the wire: each is
230
+ * emitted only when it could be taken, and `board-conformance` reads an
231
+ * absent key as UNMEASURED rather than as a zero.
232
+ *
233
+ * The row types are IMPORTED from the reader rather than spelled again
234
+ * here. Two declarations of one wire shape are two deciders that agree —
235
+ * `.claude/rules/checks-must-be-able-to-fail.md` — and nothing would have
236
+ * gone red when they drifted. The import is `type`-only and the reader has
237
+ * no relative imports of its own, so its mutation battery is untouched.
238
+ */
239
+ specPlacements?: SpecPlacementRow[];
240
+ /** SC-2734: the bank in `.claude/spec-deferral-ratchet.json`. Absent when it could not be read. */
241
+ specDeferrals?: SpecDeferral[];
242
+ repoIssues?: RepoIssueCriteria[];
243
+ plannedEdges?: PlannedEdge[];
244
+ /** SC-2752: unticked criteria in in-scope specs and open stage items. Absent when it could not be read. */
245
+ declaredWork?: DeclaredWork[];
246
+ }
247
+
248
+ /**
249
+ * The work this repository DECLARES — SC-2752, #1953.
250
+ *
251
+ * Every unticked criterion in an in-scope spec, then every open stage item
252
+ * in `project-state.json`. In scope is the same population `spec-placement`
253
+ * counts: a spec that states criteria (`PLANNED` or `UNPLANNED`) and is not
254
+ * deferred. The criteria are read through `parseCriteria`, the one reader of
255
+ * a spec's checkbox lines, so "unticked" has one answer in the tree.
256
+ *
257
+ * A consumer repository has no `project-state.json`: an absent file declares
258
+ * no stage work, which is a measured fact. A file that is present and will
259
+ * not parse, an UNREADABLE in-scope spec, or a spec that cannot be read is
260
+ * returned as `{}` — the key omitted, which `declared-work` reads as
261
+ * UNMEASURED. A shorter list is exactly what a tree with fewer commitments
262
+ * produces, so a partial read must never be emitted as one.
263
+ */
264
+ export function readDeclaredWork(
265
+ root: string,
266
+ specs: readonly { path: string; state: SpecPlacementRow["state"]; deferred?: boolean }[],
267
+ ): { declaredWork?: DeclaredWork[] } {
268
+ const work: DeclaredWork[] = [];
269
+ for (const s of specs) {
270
+ if (s.deferred === true || s.state === "NO_CRITERIA") continue;
271
+ if (s.state === "UNREADABLE") return {};
272
+ let content: string;
273
+ try {
274
+ content = readFileSync(join(root, s.path), "utf-8");
275
+ } catch {
276
+ // Named as UNMEASURED by the omitted key, never read as an empty spec.
277
+ return {};
278
+ }
279
+ for (const c of parseCriteria(content)) if (!c.ticked) work.push({ kind: "criterion", id: c.id, source: s.path });
280
+ }
281
+ const statePath = join(root, "project-state.json");
282
+ if (existsSync(statePath)) {
283
+ let state: unknown;
284
+ try {
285
+ state = JSON.parse(readFileSync(statePath, "utf-8"));
286
+ } catch {
287
+ return {};
288
+ }
289
+ // Every level must be the shape it claims, or the population is unread.
290
+ // `JSON.parse` accepts `null` and `[]`, and optional chaining on either
291
+ // reads as "no stages", which would drop the stage half silently (AI
292
+ // review of #2096). Only a plan with no `stages` key declares none.
293
+ const isObject = (v: unknown): v is Record<string, unknown> =>
294
+ v !== null && typeof v === "object" && !Array.isArray(v);
295
+ if (!isObject(state)) return {};
296
+ const stages = state.stages;
297
+ if (stages !== undefined && !Array.isArray(stages)) return {};
298
+ for (const stage of (stages ?? []) as unknown[]) {
299
+ if (!isObject(stage) || !Array.isArray(stage.items)) return {};
300
+ for (const item of stage.items as unknown[]) {
301
+ if (!isObject(item)) return {};
302
+ if (item.done !== false || typeof item.id !== "string") continue;
303
+ work.push({
304
+ kind: "stage-item",
305
+ id: item.id,
306
+ source: "project-state.json",
307
+ issue: typeof item.issue === "number" ? item.issue : null,
308
+ });
309
+ }
310
+ }
311
+ }
312
+ return { declaredWork: work };
313
+ }
314
+
315
+ /** The path the deferral bank lives at, relative to the project root — SC-2734. */
316
+ export const DEFERRAL_BANK = ".claude/spec-deferral-ratchet.json";
317
+
318
+ /**
319
+ * Read the deferral bank — SC-2734. Returns `{}` (the key omitted) when the
320
+ * file is absent or is not `{ "deferred": [{ path, criteria }] }`, and says
321
+ * which on stderr, because a corrupt bank is never a missing one.
322
+ */
323
+ export function readDeferralBank(root: string): { specDeferrals?: SpecDeferral[] } {
324
+ const path = join(root, DEFERRAL_BANK);
325
+ if (!existsSync(path)) {
326
+ process.stderr.write(`board-snapshot: ${DEFERRAL_BANK} is absent; deferred specs cannot be checked\n`);
327
+ return {};
328
+ }
329
+ let raw: unknown;
330
+ try {
331
+ raw = JSON.parse(readFileSync(path, "utf-8"));
332
+ } catch (e) {
333
+ process.stderr.write(`board-snapshot: ${DEFERRAL_BANK} could not be parsed (${(e as Error).message}); deferred specs cannot be checked\n`);
334
+ return {};
335
+ }
336
+ const list = (raw as { deferred?: unknown })?.deferred;
337
+ if (!Array.isArray(list) || !list.every(d => typeof d?.path === "string" && Number.isInteger(d?.criteria))) {
338
+ process.stderr.write(`board-snapshot: ${DEFERRAL_BANK} is not { "deferred": [{ path, criteria }] }; deferred specs cannot be checked\n`);
339
+ return {};
340
+ }
341
+ return { specDeferrals: list.map(d => ({ path: d.path as string, criteria: d.criteria as number })) };
342
+ }
343
+
344
+ /**
345
+ * `git -C <root> …`, built per root so the runner cannot be pointed at one
346
+ * checkout while the reading is taken in another.
347
+ *
348
+ * Injected for the same reason {@link BoardSnapshotGitHub} is: a case that
349
+ * reaches a real repository measures whatever this machine happens to be on,
350
+ * and goes green or red for reasons the case never wrote down.
351
+ */
352
+ /**
353
+ * How long any one `git` call may take before it is killed.
354
+ *
355
+ * **One of these calls is network I/O.** `resolveSpecSource` runs `git fetch`,
356
+ * and a stalled remote or an HTTPS remote that drops to a credential prompt
357
+ * blocks `spawnSync` forever. Through `board-conformance` the outer
358
+ * `PRODUCE_TIMEOUT_MS` eventually kills the child, but `board-snapshot` is
359
+ * also a standalone entry point and there is nothing above it — so an
360
+ * unattended run wedges with no bound at all. A wedge is worse than a
361
+ * refusal, because nothing observes it. Review of #1896 round 3.
362
+ *
363
+ * **And it must be strictly UNDER the outer bound, which is why it is
364
+ * derived rather than written.** Round 12 found the two equal: this was
365
+ * `60_000` and `board-conformance`'s `PRODUCE_TIMEOUT_MS` is
366
+ * `Number(process.env.RUNGATE_PRODUCE_TIMEOUT_MS) || 60_000`. With both at
367
+ * 60s the outer `spawnSync` kills the whole child at the same moment the
368
+ * inner timeout would fire, so the specific message this code builds —
369
+ * *"it timed out — the bound is 60000ms"* — never reaches anyone through
370
+ * the primary caller. The reader saw `board-snapshot was killed by
371
+ * SIGTERM` instead, which names the wrong bound and the wrong subject.
372
+ *
373
+ * A diagnostic that cannot fire in the path it was written for is the
374
+ * shape `.claude/rules/checks-must-be-able-to-fail.md` calls a line in a
375
+ * report. Reading the same env var keeps the margin under a consumer who
376
+ * lowers the outer bound, which a fixed smaller number would not.
377
+ */
378
+ export const GIT_TIMEOUT_FRACTION = 0.5;
379
+
380
+ /** The outer bound this must stay under, read the same way the outer reads it. */
381
+ export function gitTimeoutFor(env: NodeJS.ProcessEnv): number {
382
+ const outer = Number(env.RUNGATE_PRODUCE_TIMEOUT_MS) || 60_000;
383
+ return Math.max(1, Math.floor(outer * GIT_TIMEOUT_FRACTION));
211
384
  }
212
385
 
213
- export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB): Promise<number> {
386
+ export const GIT_TIMEOUT_MS = gitTimeoutFor(process.env);
387
+
388
+ /**
389
+ * The ambient environment with every git override removed.
390
+ *
391
+ * **The list is not declared here.** Round 8 of this review added a
392
+ * seven-name denylist to this file and round 9 found it short by the whole
393
+ * `GIT_CONFIG*` family — which is the predictable outcome of a second
394
+ * registry, not bad luck about one entry: two deciders over one question
395
+ * are behaviourally one, and no case here could tell which was answering
396
+ * (`.claude/rules/checks-must-be-able-to-fail.md`). `lib/git-isolation.ts`
397
+ * has owned this set since #1001, so this is the declaration's second
398
+ * consumer rather than its second spelling.
399
+ *
400
+ * {@link withoutAmbientGitOverrides} is the half that only REMOVES.
401
+ * `gitIsolatedEnv` is deliberately not used: it additionally sets
402
+ * `GIT_CONFIG_GLOBAL=/dev/null`, which discards `credential.helper` —
403
+ * measured on this machine as the system gitconfig's `osxkeychain` — and
404
+ * {@link GIT_TIMEOUT_MS}'s comment above records that one of these calls
405
+ * is a `git fetch`. Isolation that cannot authenticate turns a reading
406
+ * into a refusal.
407
+ */
408
+ export function gitEnv(from: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
409
+ return { ...withoutAmbientGitOverrides(from), GIT_TERMINAL_PROMPT: "0" };
410
+ }
411
+
412
+ /**
413
+ * `spawnSync`, injected so a case can assert WHAT was asked for.
414
+ *
415
+ * A timeout is invisible from outside unless something hangs, and a test
416
+ * that hangs to prove it does not hang is not a test. The seam puts the
417
+ * options object where a case can read it, and lets a case hand back the
418
+ * shape `spawnSync` returns when it kills a child — which is the half that
419
+ * actually decides what the caller sees.
420
+ */
421
+ export type GitSpawn = typeof spawnSync;
422
+
423
+ export const LIVE_GIT = (root: string, spawn: GitSpawn = spawnSync): GitRunner => {
424
+ return args => {
425
+ const r = spawn("git", ["-C", root, ...args], {
426
+ encoding: "utf-8",
427
+ timeout: GIT_TIMEOUT_MS,
428
+ // A prompt is a hang wearing a different hat: git waits on a terminal
429
+ // nobody is sitting at. Refusing to ask is what makes the timeout the
430
+ // last line of defence rather than the first.
431
+ //
432
+ // **AND THE REPO-LOCATING VARIABLES ARE STRIPPED.** `GIT_DIR`,
433
+ // `GIT_WORK_TREE` and friends take precedence over `-C root`'s
434
+ // discovery, so a caller that already set them — a git hook, a
435
+ // wrapper around its own nested git — silently points every call
436
+ // here at a DIFFERENT repository while each downstream check still
437
+ // reports a clean, confident reading for the wrong tree. That is
438
+ // this module's whole defect reached through the environment
439
+ // instead of through an exit code. Review of #1896 round 8.
440
+ env: gitEnv(process.env),
441
+ });
442
+ // `code` carries `status`, and `status` is NULL when the process never
443
+ // ran — no `git` on PATH — or when it was killed by a signal, which now
444
+ // includes the timeout above. Both are a different fact from any exit
445
+ // code, and `lib/spec-source.ts` refuses on either rather than reading
446
+ // it as an answer about a file.
447
+ //
448
+ // **BUT THEY ARE NOT THE SAME SENTENCE, AND A SIGNAL IS NOT A
449
+ // MECHANISM.** Measured, with Bun's `spawnSync`:
450
+ //
451
+ // timeout status null signal SIGTERM code ETIMEDOUT
452
+ // maxBuffer status null signal SIGTERM code ENOBUFS
453
+ // no binary status UNDEFINED signal null code ENOENT
454
+ //
455
+ // Two things fall out, and neither was in the review that prompted
456
+ // this. The middle row is indistinguishable from the first by signal
457
+ // alone, so only `ETIMEDOUT` may name the bound — `r.signal !== null`
458
+ // attributed an out-of-buffer kill, or an OOM killer, to a timeout
459
+ // that had not fired. And the last row returns **undefined**, not
460
+ // null, so `code: r.status` made `inRepo.code === null` false and a
461
+ // missing `git` walked past the one guard written for it into a
462
+ // working-tree read. `?? null` is the fix and the tri-state is the
463
+ // lesson again.
464
+ const code = r.status ?? null;
465
+ const why =
466
+ code !== null || r.error === undefined
467
+ ? ""
468
+ : (r.error as NodeJS.ErrnoException).code === "ETIMEDOUT"
469
+ ? `${r.error.message} (timed out — the bound is ${GIT_TIMEOUT_MS}ms)`
470
+ : r.signal !== null
471
+ ? `${r.error.message} (killed by ${r.signal}; the cause was not reported as a timeout)`
472
+ : `${r.error.message} (it never started — this is not a timeout)`;
473
+ return {
474
+ ok: r.status === 0,
475
+ code,
476
+ stdout: r.stdout ?? "",
477
+ stderr: [r.stderr ?? "", why].filter(s => s !== "").join("\n"),
478
+ };
479
+ };
480
+ };
481
+
482
+ export async function main(
483
+ argv: string[],
484
+ gh: BoardSnapshotGitHub = LIVE_GITHUB,
485
+ git: (root: string) => GitRunner = LIVE_GIT,
486
+ ): Promise<number> {
214
487
  let parsed;
215
488
  try {
216
489
  parsed = parseArgs({
@@ -228,9 +501,25 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
228
501
  }
229
502
 
230
503
  const { values, positionals } = parsed;
231
- const specArg = positionals[0];
504
+ // THE ROOT IS RESOLVED FIRST, because the config under it is now one of
505
+ // the places the arguments come from (#1718). It used to be read after
506
+ // every argument check, which is fine when arguments are the only source
507
+ // and impossible once they are not.
508
+ const root = values["project-root"] ?? process.cwd();
509
+ const configured = readBoardInputs(root);
510
+
511
+ // **An argument the caller gave always wins, and a BLANK one still
512
+ // refuses.** Falling back to config on a blank would substitute a value
513
+ // for one somebody typed — `--prefix ""` is a mistake to name, not a
514
+ // request for the default. So the fallback is reached only by absence,
515
+ // which is the one case that carries no instruction to override.
516
+ const specArg = positionals[0] ?? configured.engineSpec ?? undefined;
232
517
  if (!specArg) {
233
- console.error(`board-snapshot: no spec given\n\n${USAGE}`);
518
+ console.error(
519
+ `board-snapshot: no spec given, and no \`board.engineSpec\` in this project's rungate config ` +
520
+ `(read from ${root}). Pass the spec as the first argument, or set \`board.engineSpec\` so the ` +
521
+ `command can take its own reading.\n\n${USAGE}`,
522
+ );
234
523
  return REFUSAL_EXIT;
235
524
  }
236
525
  // ONE reading, trimmed once — the same binding `plan-spec` and `plan-deps`
@@ -238,30 +527,90 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
238
527
  // milestone titles starting with the space, matched none of the live ones,
239
528
  // and reported a conformant board as needing every milestone created.
240
529
  // Round 1 of #1705.
241
- const prefixRead = readMilestonePrefix(values.prefix);
530
+ const prefixRead = readMilestonePrefix(values.prefix ?? configured.milestonePrefix ?? undefined);
242
531
  if (prefixRead.kind !== "given") {
243
532
  console.error(
244
533
  prefixRead.kind === "absent"
245
- ? `board-snapshot: --prefix is required\n\n${USAGE}`
534
+ ? `board-snapshot: --prefix is required, and no \`board.milestonePrefix\` is set in this ` +
535
+ `project's rungate config (read from ${root})\n\n${USAGE}`
246
536
  : `board-snapshot: --prefix was given as ${JSON.stringify(prefixRead.raw)}, which is blank. ` +
247
537
  `It would match no milestone on the board and report every phase as missing.\n\n${USAGE}`,
248
538
  );
249
539
  return REFUSAL_EXIT;
250
540
  }
251
541
  const prefix = prefixRead.prefix;
252
- const repo = values.repo ?? process.env.GITHUB_REPOSITORY;
542
+ // The third input, same shape: the flag, then the environment CI sets,
543
+ // then the project's own `origin`. `resolveRepoSlug` is the existing
544
+ // binding for that last step and carries its own reason when it fails —
545
+ // a second reader here would be two deciders over one fact.
546
+ //
547
+ // **AND THE SAME BLANK RULE, which review of #1890 found applied to two
548
+ // of the three inputs.** `"" ?? x` keeps `""`, and `resolveRepoSlug`'s
549
+ // own `if (repo && repo.trim())` is falsy for it, so `--repo ""` — a CI
550
+ // line interpolating an unset `$REPO` — fell through to this checkout's
551
+ // `origin` and took a live reading against a repository the caller never
552
+ // named, without even the provenance line, which fires only when the
553
+ // flag was ABSENT. Spelled here rather than inside `resolveRepoSlug`:
554
+ // its other callers may legitimately read a blank as "not given", and
555
+ // this command's contract is that a typed empty is a mistake to name.
556
+ if (values.repo !== undefined && String(values.repo).trim() === "") {
557
+ console.error(
558
+ `board-snapshot: --repo was given as ${JSON.stringify(values.repo)}, which is blank. Falling back to ` +
559
+ `this project's origin would take a reading against a repository you did not name. Pass a value, or ` +
560
+ `omit --repo entirely.\n\n${USAGE}`,
561
+ );
562
+ return REFUSAL_EXIT;
563
+ }
564
+ const slug = resolveRepoSlug({ projectRoot: root, repo: values.repo ?? process.env.GITHUB_REPOSITORY });
565
+ const repo = slug.slug;
253
566
  if (!repo) {
254
- console.error(`board-snapshot: --repo is required (or set GITHUB_REPOSITORY)\n\n${USAGE}`);
567
+ console.error(
568
+ `board-snapshot: --repo is required (or set GITHUB_REPOSITORY). Falling back to this ` +
569
+ `project's origin remote did not resolve one either: ${slug.reason ?? "no reason given"}\n\n${USAGE}`,
570
+ );
255
571
  return REFUSAL_EXIT;
256
572
  }
257
573
 
258
- const root = values["project-root"] ?? process.cwd();
574
+ // WHERE EACH INPUT CAME FROM, on stderr so it never reaches the snapshot
575
+ // on stdout. A reading taken from config and one taken from the command
576
+ // line are the same bytes downstream, and only one of them is reproducible
577
+ // by somebody who did not watch you type it.
578
+ const fromConfig = [
579
+ positionals[0] === undefined && configured.engineSpec !== null ? `spec=${specArg} (board.engineSpec)` : null,
580
+ values.prefix === undefined && configured.milestonePrefix !== null
581
+ ? `prefix=${prefix} (board.milestonePrefix)`
582
+ : null,
583
+ slug.source === "origin" ? `repo=${repo} (origin remote of ${root})` : null,
584
+ ].filter((s): s is string => s !== null);
585
+ if (fromConfig.length > 0) {
586
+ console.error(`board-snapshot: resolved from the repository, not the command line — ${fromConfig.join(", ")}`);
587
+ }
588
+
589
+ // **THE SPEC COMES FROM `origin/main`, AND THE LINE BELOW SAYS SO** — D3.
590
+ // This was a bare `readFileSync` until 2026-11-08, so every reading it
591
+ // produced was scoped by whichever branch the caller stood on and the
592
+ // output named none of them. A branch mid-edit on a Phase placement table
593
+ // and a branch four days behind main give different numbers against the
594
+ // SAME live board, and both printed as an ordinary reading.
595
+ //
596
+ // Three answers, and the third is the point: a tracked path is read from
597
+ // the ref; an UNTRACKED one is read from disk and said so (a planted
598
+ // fixture has no `origin/main` version, which is a fact about the file);
599
+ // and a failure anywhere in between is UNMEASURED. It does NOT fall back
600
+ // to disk — that is the working-tree read wearing a repair, and it fires
601
+ // in exactly the case where the two disagree most.
259
602
  const specPath = isAbsolute(specArg) ? specArg : join(root, specArg);
260
- if (!existsSync(specPath)) {
603
+ const source = resolveSpecSource({ root, absPath: specPath, git: git(root) });
604
+ // ALWAYS, never only on the interesting arm. A provenance line that
605
+ // appears when something is odd teaches the reader that silence means
606
+ // origin/main, and silence is also what a broken emitter looks like.
607
+ console.error(`board-snapshot: ${describeSpecSource(source)}`);
608
+ if (source.kind === "unmeasured") return REFUSAL_EXIT;
609
+ if (source.kind === "untracked" && !existsSync(specPath)) {
261
610
  console.error(`board-snapshot: no such spec: ${specPath}`);
262
611
  return REFUSAL_EXIT;
263
612
  }
264
- const content = readFileSync(specPath, "utf-8");
613
+ const content = source.kind === "ref" ? source.content : readFileSync(specPath, "utf-8");
265
614
 
266
615
  // An unsound placement table is UNMEASURED, not a board with fewer
267
616
  // phases. A criterion the table never places, or places twice, makes the
@@ -451,6 +800,104 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
451
800
  const columnRead =
452
801
  board !== null && snapshotIssues.length > 0 && snapshotIssues.every(i => "criteriaField" in i);
453
802
 
803
+ // ── The three REPOSITORY-WIDE populations — SC-2615, SC-2616, SC-2617 ──
804
+ //
805
+ // Everything above this line is engine-scoped: `phases` comes from the one
806
+ // spec named on the command line and `issues` is that spec's milestone
807
+ // family. Each of the three below asks the same shape of question of the
808
+ // whole tree, and each is emitted ONLY when it could actually be taken —
809
+ // `board-conformance` reads an absent key as UNMEASURED, and an absent key
810
+ // is the honest thing to write when nothing was read.
811
+
812
+ // SC-2615. The sweep's own `specs` rows are passed through, UNREADABLE
813
+ // ones included: the reading refuses on them by name, which it cannot do
814
+ // if the producer drops them. The key is omitted only when the sweep could
815
+ // not enumerate `specs/` at all — then there are no rows to carry, and an
816
+ // empty list would be indistinguishable from a tree whose specs are all
817
+ // placed.
818
+ const coverage = placementCoverage(root, specPathSweep, (base, path) =>
819
+ readFileSync(join(base, path), "utf-8"),
820
+ );
821
+ const placements =
822
+ coverage.specs.length === 0 && coverage.reading === "UNMEASURED"
823
+ ? {}
824
+ : {
825
+ specPlacements: coverage.specs.map(s => ({
826
+ path: s.path,
827
+ state: s.state,
828
+ criteria: s.criteria,
829
+ placed: s.placed,
830
+ ...(s.deferred ? { deferred: true } : {}),
831
+ })),
832
+ };
833
+
834
+ // SC-2734. The bank the deferred specs are compared against. An absent or
835
+ // malformed file omits the key, and the reading goes UNMEASURED as soon as
836
+ // any spec declares itself deferred — a bank nobody could read is not an
837
+ // empty bank, and reading it as one would let every deferral through.
838
+ const deferrals = readDeferralBank(root);
839
+
840
+ // SC-2616. The criterion union comes from the SAME sweep `board-mirror`
841
+ // uses to build the column, so "which ids exist" has one answer. A second
842
+ // enumeration here would be a second decider that no behavioural case
843
+ // could separate from the first.
844
+ //
845
+ // `servesNone` is the literal `NAMES_NONE` string, which is the one way
846
+ // this repository spells the declaration (SC-2609). Matching anything
847
+ // looser — "no criterion", "n/a" — would let an issue opt out by accident,
848
+ // and the entire criterion is that *has not said* and *says none* are
849
+ // different facts.
850
+ // An UNMEASURED sweep omits the key, the same way the other two do. `ids`
851
+ // is `[]` on a sweep that refused — an unreadable `specs/`, a criterion two
852
+ // specs both state — and an empty union matches nothing in any issue, so
853
+ // every issue would report `names: []` whatever it actually names. The
854
+ // reading has no way to tell that from a tracker where nobody has declared
855
+ // anything: it would call all 72 issues offenders, or, if every one of them
856
+ // happened to carry the `servesNone` text, report MET. Raised in review of
857
+ // #1903 — the producer had the gate on the other two populations and not on
858
+ // this one.
859
+ const sweep = specCriteriaIn(root);
860
+ const openIssues = liveIssues.filter(i => i.state === "OPEN");
861
+ const ids = answerableIds(sweep);
862
+ const repoIssues =
863
+ sweep.reading === "UNMEASURED"
864
+ ? {}
865
+ : {
866
+ repoIssues: openIssues.map(i => {
867
+ // The one decider (#2020): the `needs-criterion` label reads it too.
868
+ const { names, servesNone } = criterionAnswer({ title: i.title, body: i.body }, ids);
869
+ return { number: i.number, names, servesNone };
870
+ }),
871
+ };
872
+
873
+ // SC-2617. `missing` and `present` are the plan's own two halves — derived
874
+ // edges the tracker lacks, and derived edges it carries. `extra` is
875
+ // deliberately excluded: an edge somebody added that the plan does not
876
+ // derive is reported by `plan-deps` and removed by nobody, so counting it
877
+ // here would let hand-added ordering satisfy a reading about derived
878
+ // ordering.
879
+ //
880
+ // An UNMEASURED plan omits the key. `dependencyPlan` returns UNMEASURED
881
+ // for a truncated `blockedBy` among other reasons, and a truncated read
882
+ // produces exactly the false `missing` edges this reading would then count
883
+ // as the tracker's failure.
884
+ const plan = dependencyPlan(liveIssues);
885
+ const edges =
886
+ plan.reading === "UNMEASURED"
887
+ ? {}
888
+ : {
889
+ plannedEdges: [
890
+ ...plan.present.map(e => ({ blocked: e.blocked, blocker: e.blocker, present: true })),
891
+ ...plan.missing.map(e => ({ blocked: e.blocked, blocker: e.blocker, present: false })),
892
+ ],
893
+ };
894
+
895
+ // SC-2752. Built from the SAME sweep rows `spec-placement` reads, so the two
896
+ // readings cannot disagree about which specs are in scope. A sweep that
897
+ // could not enumerate `specs/` emits no rows, and `declared-work` is then
898
+ // UNMEASURED rather than a stage-only count.
899
+ const declared = placements.specPlacements === undefined ? {} : readDeclaredWork(root, placements.specPlacements);
900
+
454
901
  const snapshot: ProducedSnapshot = {
455
902
  producedAt: new Date().toISOString(),
456
903
  spec: specArg,
@@ -459,6 +906,11 @@ export async function main(argv: string[], gh: BoardSnapshotGitHub = LIVE_GITHUB
459
906
  closedBlockers: [...named].sort((a, b) => a - b),
460
907
  queueLabel: readQueueLabel(root),
461
908
  criteria: criterionCoverage(content, snapshotIssues, columnRead),
909
+ ...placements,
910
+ ...deferrals,
911
+ ...repoIssues,
912
+ ...edges,
913
+ ...declared,
462
914
  };
463
915
 
464
916
  process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);