rungate 0.8.25 → 0.8.26

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.
@@ -80,6 +80,14 @@ export interface BoardCriterion {
80
80
  satisfiedByIssue: number | null;
81
81
  /** Already true in the tree and needing no issue. */
82
82
  recordedTrue?: boolean;
83
+ /**
84
+ * The spec places it outside every phase — Blocked, Not adopted —
85
+ * deliberate, or Not observable here — as written (SC-2778). Named apart and
86
+ * out of both sides of `criterion-coverage`; never covered by an issue.
87
+ */
88
+ outside?: string;
89
+ /** Placed under a value the engine does not know — the reading goes UNMEASURED (SC-2778). */
90
+ unknownPlacement?: string;
83
91
  }
84
92
 
85
93
  /**
@@ -159,6 +167,19 @@ export interface BoardSnapshot {
159
167
  */
160
168
  specDeferrals?: SpecDeferral[];
161
169
 
170
+ /**
171
+ * `board.engineSpec` and `board.milestonePrefix` as the config holds
172
+ * them — SC-2776. The engine spec's own `board:` block must agree with
173
+ * both, or the disagreement is reported by name.
174
+ *
175
+ * **Absent means the producer never read the config**, and
176
+ * `spec-placement` goes UNMEASURED: whether the engine spec opts itself
177
+ * in is then unknown, which is not the same as known to agree. `null` in
178
+ * either field is a config that sets nothing there, so there is nothing
179
+ * for the block to disagree with.
180
+ */
181
+ engineConfig?: { spec: string | null; prefix: string | null };
182
+
162
183
  /**
163
184
  * EVERY open issue in the repository and what it says it serves — SC-2616.
164
185
  *
@@ -191,7 +212,8 @@ export interface BoardSnapshot {
191
212
  * Work the repository DECLARES, and what each piece points at — SC-2752.
192
213
  *
193
214
  * Every unticked criterion in an in-scope spec (one that states criteria
194
- * and is not deferred), and every open stage item in `project-state.json`.
215
+ * and opts in with `board: { scope: active }`, SC-2776 — the population
216
+ * `spec-placement` measures), and every open stage item in `project-state.json`.
195
217
  * A commitment written into a file is indistinguishable from one never
196
218
  * made until something reads the file and asks for its tracker object;
197
219
  * thirteen were found by hand on 2026-11-09 (#1938-#1946, #1948-#1951).
@@ -241,6 +263,10 @@ export interface DeclaredWork {
241
263
  * {@link BoardSnapshot.repoIssues} — the one decider of what an issue names.
242
264
  */
243
265
  issue?: number | null;
266
+ /** A criterion its spec places outside every phase, as written — SC-2778. Never unaccounted. */
267
+ outside?: string;
268
+ /** A criterion placed under a value the engine does not know — `declared-work` goes UNMEASURED (SC-2778). */
269
+ unknownPlacement?: string;
244
270
  }
245
271
 
246
272
  /**
@@ -255,7 +281,9 @@ export interface DeclaredWork {
255
281
  export function declaredWorkUnaccounted(b: BoardSnapshot): DeclaredWork[] {
256
282
  const open = new Set((b.repoIssues ?? []).map(i => i.number));
257
283
  const named = new Set((b.repoIssues ?? []).flatMap(i => i.names));
258
- return (b.declaredWork ?? []).filter(w =>
284
+ // SC-2778: a criterion the spec parks outside every phase is declared, not
285
+ // owed — asking for its issue asks for work the spec says cannot start.
286
+ return (b.declaredWork ?? []).filter(w => w.outside === undefined).filter(w =>
259
287
  w.kind === "criterion" ? !named.has(w.id) : !(typeof w.issue === "number" && open.has(w.issue)),
260
288
  );
261
289
  }
@@ -275,10 +303,33 @@ export interface SpecPlacementRow {
275
303
  /** How many criteria the spec states, and how many its table places. */
276
304
  criteria: number;
277
305
  placed: number;
278
- /** The spec declares `board-scope: deferred` in its frontmatter — SC-2734. */
306
+ /** The spec declares `scope: deferred` (or the legacy `board-scope: deferred`) — SC-2734. */
279
307
  deferred?: boolean;
308
+ /**
309
+ * What the spec's own `board:` frontmatter declares — SC-2776. Absent for
310
+ * a spec that declares nothing, which is never measured, whatever else it
311
+ * carries (ADR-018 Decision 8).
312
+ *
313
+ * Carried WHOLE from `boardDeclaration` in `lib/spec-placement.ts`, where
314
+ * the keys the engine knows are listed once: a new setting passes through
315
+ * here without this file naming it.
316
+ */
317
+ board?: RowBoard;
318
+ }
319
+
320
+ /** A spec's `board:` declaration as the snapshot carries it — SC-2776. */
321
+ export interface RowBoard {
322
+ /** `active` is the only scope measured. */
323
+ scope: string;
324
+ /** Every setting the block declares, as text — `settings.prefix`, and any key added later. */
325
+ settings: Record<string, string>;
326
+ /** What stops the declaration being read as written, each reported by name. */
327
+ problems: string[];
280
328
  }
281
329
 
330
+ /** The spec opts itself in — SC-2776. THE one test of membership, for every reader here. */
331
+ const optedIn = (s: SpecPlacementRow): boolean => s.board?.scope === "active";
332
+
282
333
  /** One entry in the deferral bank, `.claude/spec-deferral-ratchet.json` — SC-2734. */
283
334
  export interface SpecDeferral {
284
335
  path: string;
@@ -312,6 +363,54 @@ export function deferralDifferences(rows: readonly SpecPlacementRow[], bank: rea
312
363
  return out;
313
364
  }
314
365
 
366
+ /**
367
+ * Every `board:` declaration the reading cannot take as written, by name — SC-2776.
368
+ *
369
+ * Three kinds, each one sentence naming the spec:
370
+ * - what the producer reported about a spec's own block (an unknown scope
371
+ * value, an active spec with no prefix, a block that is not YAML);
372
+ * - a row both active and deferred, which no single block can say;
373
+ * - the engine spec's block disagreeing with `board.engineSpec` or
374
+ * `board.milestonePrefix`, or the config never read at all.
375
+ */
376
+ export function boardDeclarationProblems(
377
+ rows: readonly SpecPlacementRow[],
378
+ engine: BoardSnapshot["engineConfig"],
379
+ ): string[] {
380
+ const out = rowDeclarationProblems(rows);
381
+ if (engine === undefined) {
382
+ out.push("board.engineSpec and board.milestonePrefix were never read, so whether the engine spec opts itself in is unknown");
383
+ return out;
384
+ }
385
+ if (engine.spec === null) return out;
386
+ const row = rows.find(r => r.path === engine.spec);
387
+ if (row === undefined) out.push(`board.engineSpec names ${engine.spec}, which the specs/ sweep did not find`);
388
+ else if (!optedIn(row)) {
389
+ out.push(`${engine.spec} is board.engineSpec and its frontmatter does not opt it in — it needs a board: block with scope: active`);
390
+ } else if (engine.prefix !== null && row.board?.settings.prefix !== engine.prefix) {
391
+ const declared = row.board?.settings.prefix;
392
+ out.push(
393
+ `${engine.spec} declares board.prefix ${declared === undefined ? "(none)" : JSON.stringify(declared)} and board.milestonePrefix is ${JSON.stringify(engine.prefix)}`,
394
+ );
395
+ }
396
+ return out;
397
+ }
398
+
399
+ /**
400
+ * What each spec's own `board:` declaration could not say, by name — the half
401
+ * of {@link boardDeclarationProblems} that needs no config. `declared-work`
402
+ * refuses on it too (SC-2778): a spec whose declaration is unreadable has an
403
+ * unknown membership, so the population it would be counted in is unknown.
404
+ */
405
+ export function rowDeclarationProblems(rows: readonly SpecPlacementRow[]): string[] {
406
+ const out: string[] = [];
407
+ for (const r of rows) {
408
+ for (const p of r.board?.problems ?? []) out.push(`${r.path}: ${p}`);
409
+ if (optedIn(r) && r.deferred === true) out.push(`${r.path} is read as both active and deferred`);
410
+ }
411
+ return out;
412
+ }
413
+
315
414
  /** One open issue, and the criteria it names — SC-2616. */
316
415
  export interface RepoIssueCriteria {
317
416
  number: number;
@@ -360,6 +459,15 @@ export interface Reading {
360
459
  * reading cannot pay for a list nobody reads.
361
460
  */
362
461
  offenders: string[];
462
+ /**
463
+ * Rows the reading leaves out of BOTH sides because the spec declares them
464
+ * outside every phase — SC-2778. Named on every reading that took a
465
+ * measurement, met or short, in a line of their own (ADR-018 Decision 5):
466
+ * a criterion that silently left the denominator is indistinguishable from
467
+ * one nobody wrote down. Always set by `takeReading`; optional so a Reading
468
+ * built elsewhere (a test, a formatter caller) need not invent an empty list.
469
+ */
470
+ declared?: string[];
363
471
  }
364
472
 
365
473
  interface ReadingSpec {
@@ -405,6 +513,8 @@ interface ReadingSpec {
405
513
  * ones have populations in the dozens, where a ratio is unactionable.
406
514
  */
407
515
  offenders?: (board: BoardSnapshot) => string[];
516
+ /** The rows declared outside every phase, named — see {@link Reading.declared}. */
517
+ declared?: (board: BoardSnapshot) => string[];
408
518
  }
409
519
 
410
520
  /** The issue numbers actually on the board, for resolving a reference. */
@@ -477,15 +587,29 @@ export const READINGS: readonly ReadingSpec[] = [
477
587
  // reference, a typo or a renumbered issue is a pointer to nothing, and
478
588
  // counting it is the same defect one level deeper: coverage asserted
479
589
  // against data the reading never looked at.
590
+ // SC-2778. A placement value the engine does not know is refused by
591
+ // name: counting the criterion as missing or as declared would each be a
592
+ // guess about what the spec meant.
593
+ unreadable: b => {
594
+ const unknown = b.criteria.filter(c => c.unknownPlacement !== undefined);
595
+ return unknown.length === 0
596
+ ? null
597
+ : `the spec places criteria under values the engine does not know: ` +
598
+ unknown.map(c => `${c.id} is placed ${JSON.stringify(c.unknownPlacement)}`).join("; ");
599
+ },
600
+ // A criterion declared outside every phase leaves BOTH sides — so an
601
+ // issue that happens to name it is never counted as covering it.
480
602
  measure: b => {
481
603
  const present = onBoard(b);
604
+ const counted = b.criteria.filter(c => c.outside === undefined);
482
605
  return {
483
- measured: b.criteria.filter(
606
+ measured: counted.filter(
484
607
  c => (typeof c.satisfiedByIssue === "number" && present.has(c.satisfiedByIssue)) || c.recordedTrue === true,
485
608
  ).length,
486
- target: b.criteria.length,
609
+ target: counted.length,
487
610
  };
488
611
  },
612
+ declared: b => b.criteria.filter(c => c.outside !== undefined).map(c => `${c.id} — ${c.outside}`),
489
613
  },
490
614
  {
491
615
  name: "blocked-by-edges",
@@ -571,7 +695,7 @@ export const READINGS: readonly ReadingSpec[] = [
571
695
  {
572
696
  name: "spec-placement",
573
697
  item: "E1",
574
- what: "every criterion in every testable spec sits in a phase, or its spec is named UNPLANNED",
698
+ what: "every criterion in every opted-in spec sits in a phase, or its spec is named UNPLANNED",
575
699
  readsIssueRefs: false,
576
700
  // Counted in CRITERIA, not specs — the same choice B1 makes and for the
577
701
  // same reason. A spec stating fourteen unplaced criteria and one stating
@@ -604,12 +728,16 @@ export const READINGS: readonly ReadingSpec[] = [
604
728
  "was not read, so the population being measured is not one anybody banked";
605
729
  }
606
730
  const diff = deferralDifferences(b.specPlacements, b.specDeferrals ?? []);
607
- return diff.length === 0
608
- ? null
609
- : `the deferred specs disagree with .claude/spec-deferral-ratchet.json: ${diff.join("; ")}`;
731
+ if (diff.length > 0) return `the deferred specs disagree with .claude/spec-deferral-ratchet.json: ${diff.join("; ")}`;
732
+ // SC-2776. A declaration the engine could not read leaves the spec's
733
+ // membership unknown, so the population is not one anybody declared.
734
+ const declared = boardDeclarationProblems(b.specPlacements, b.engineConfig);
735
+ return declared.length === 0 ? null : `the specs' board: declarations cannot be read as written: ${declared.join("; ")}`;
610
736
  },
737
+ // SC-2776: only the specs that opt themselves in. A spec with no
738
+ // `board:` block is out of both sides, whatever table it carries.
611
739
  measure: b => {
612
- const specs = b.specPlacements!.filter(s => s.state !== "NO_CRITERIA" && s.deferred !== true);
740
+ const specs = b.specPlacements!.filter(s => s.state !== "NO_CRITERIA" && optedIn(s));
613
741
  return {
614
742
  measured: specs.reduce((n, s) => n + s.placed, 0),
615
743
  target: specs.reduce((n, s) => n + s.criteria, 0),
@@ -617,7 +745,7 @@ export const READINGS: readonly ReadingSpec[] = [
617
745
  },
618
746
  offenders: b =>
619
747
  b.specPlacements!
620
- .filter(s => s.state === "UNPLANNED" && s.deferred !== true)
748
+ .filter(s => s.state === "UNPLANNED" && optedIn(s))
621
749
  .map(s => `${s.path} — ${s.criteria - s.placed} of ${s.criteria} criteria in no phase`),
622
750
  },
623
751
  {
@@ -742,18 +870,32 @@ export const READINGS: readonly ReadingSpec[] = [
742
870
  // Both halves of the question must have been read. Declared work with no
743
871
  // issue set to resolve it against would blame every row on a lookup that
744
872
  // never happened; an issue set with no declared work has nothing to ask.
745
- unreadable: b =>
746
- b.declaredWork === undefined
747
- ? "declared work was never read — no unticked criteria and no stage items reached the snapshot, " +
748
- "which is not the same as a repository that declares none"
749
- : b.repoIssues === undefined
750
- ? "open issues were never read, so whether any of them accounts for the declared work is unknown"
751
- : null,
873
+ unreadable: b => {
874
+ if (b.declaredWork === undefined) {
875
+ return "declared work was never read — no unticked criteria and no stage items reached the snapshot, " +
876
+ "which is not the same as a repository that declares none";
877
+ }
878
+ if (b.repoIssues === undefined) {
879
+ return "open issues were never read, so whether any of them accounts for the declared work is unknown";
880
+ }
881
+ // SC-2778, and PR #2308's round 7: the population is the opted-in
882
+ // specs, so a spec whose declaration cannot be read makes it unknown.
883
+ const declarations = rowDeclarationProblems(b.specPlacements ?? []);
884
+ if (declarations.length > 0) {
885
+ return `a spec's board: declaration cannot be read, so which specs declare work is unknown: ${declarations.join("; ")}`;
886
+ }
887
+ const unknown = b.declaredWork.filter(w => w.unknownPlacement !== undefined);
888
+ return unknown.length === 0
889
+ ? null
890
+ : `criteria are placed under values the engine does not know: ` +
891
+ unknown.map(w => `${w.id} (${w.source}) is placed ${JSON.stringify(w.unknownPlacement)}`).join("; ");
892
+ },
752
893
  measure: b => {
753
- const total = b.declaredWork!.length;
894
+ const total = b.declaredWork!.filter(w => w.outside === undefined).length;
754
895
  return { measured: total - declaredWorkUnaccounted(b).length, target: total };
755
896
  },
756
897
  offenders: b => declaredWorkUnaccounted(b).map(w => `${w.id} (${w.source}) names no open issue`),
898
+ declared: b => b.declaredWork!.filter(w => w.outside !== undefined).map(w => `${w.id} (${w.source}) — ${w.outside}`),
757
899
  },
758
900
  ];
759
901
 
@@ -779,15 +921,16 @@ export function takeReading(spec: ReadingSpec, board: BoardSnapshot | null): Rea
779
921
  // board to hand it. `main` can no longer reach this arm at all (#1718:
780
922
  // every source either produces a board or returns a reason), so the one
781
923
  // way here is an API caller passing null, and that is what it now says.
782
- return { ...base, status: "unmeasured", measured: 0, target: 0, why: "no board snapshot was passed to this reading, so nothing was measured — that is a caller with no board, not a board with nothing on it", offenders: [] };
924
+ return { ...base, status: "unmeasured", measured: 0, target: 0, why: "no board snapshot was passed to this reading, so nothing was measured — that is a caller with no board, not a board with nothing on it", offenders: [], declared: [] };
783
925
  }
784
926
  const why = spec.unreadable?.(board) ?? null;
785
- if (why !== null) return { ...base, status: "unmeasured", measured: 0, target: 0, why, offenders: [] };
927
+ if (why !== null) return { ...base, status: "unmeasured", measured: 0, target: 0, why, offenders: [], declared: [] };
786
928
  const { measured, target } = spec.measure(board);
929
+ const declared = spec.declared?.(board) ?? [];
787
930
  if (target === 0) {
788
- return { ...base, status: "unmeasured", measured, target, why: "the board carries nothing for this reading to count, so 0 of 0 is not a pass", offenders: [] };
931
+ return { ...base, status: "unmeasured", measured, target, why: "the board carries nothing for this reading to count, so 0 of 0 is not a pass", offenders: [], declared };
789
932
  }
790
- if (measured >= target) return { ...base, status: "met", measured, target, why: `${measured} of ${target}`, offenders: [] };
933
+ if (measured >= target) return { ...base, status: "met", measured, target, why: `${measured} of ${target}`, offenders: [], declared };
791
934
  // Named only here. A met reading never pays for the list, and an
792
935
  // UNMEASURED one must not print rows — it did not read the population it
793
936
  // would be naming them out of.
@@ -798,6 +941,7 @@ export function takeReading(spec: ReadingSpec, board: BoardSnapshot | null): Rea
798
941
  target,
799
942
  why: `${measured} of ${target} — ${target - measured} short`,
800
943
  offenders: spec.offenders?.(board) ?? [],
944
+ declared,
801
945
  };
802
946
  }
803
947
 
@@ -820,7 +964,11 @@ export const OFFENDERS_SHOWN = 10;
820
964
 
821
965
  export function formatReading(r: Reading): string {
822
966
  const mark = r.status === "met" ? "MET " : r.status === "short" ? "SHORT " : "UNMEASURED ";
823
- const head = `${mark} ${r.name.padEnd(20)} ${r.why}\n ${r.what} [${r.item}]`;
967
+ // SC-2778: named apart on a met reading too — a row that left the
968
+ // denominator silently reads the same as one nobody wrote down.
969
+ const named = r.declared ?? [];
970
+ const declared = named.length === 0 ? "" : `\n declared outside phases (${named.length}): ${named.join(", ")}`;
971
+ const head = `${mark} ${r.name.padEnd(20)} ${r.why}\n ${r.what} [${r.item}]${declared}`;
824
972
  if (r.offenders.length === 0) return head;
825
973
  const shown = r.offenders.slice(0, OFFENDERS_SHOWN).map(o => `\n ${o}`).join("");
826
974
  const rest = r.offenders.length > OFFENDERS_SHOWN
@@ -873,9 +1021,24 @@ const normaliseCriterion = (v: unknown): BoardCriterion | null => {
873
1021
  id: c.id,
874
1022
  satisfiedByIssue: typeof c.satisfiedByIssue === "number" ? c.satisfiedByIssue : null,
875
1023
  recordedTrue: c.recordedTrue === true,
1024
+ ...placementAnnotation(c),
876
1025
  };
877
1026
  };
878
1027
 
1028
+ /**
1029
+ * SC-2778's two row annotations, carried across the snapshot boundary
1030
+ * present-only. A non-string value is kept as an unknown placement rather
1031
+ * than dropped: dropping `outside` would count a parked criterion as missing,
1032
+ * and dropping `unknownPlacement` would measure what the engine cannot read.
1033
+ */
1034
+ const placementAnnotation = (r: { outside?: unknown; unknownPlacement?: unknown }): { outside?: string; unknownPlacement?: string } => {
1035
+ if (r.unknownPlacement !== undefined) {
1036
+ return { unknownPlacement: typeof r.unknownPlacement === "string" ? r.unknownPlacement : JSON.stringify(r.unknownPlacement) };
1037
+ }
1038
+ if (r.outside === undefined) return {};
1039
+ return typeof r.outside === "string" ? { outside: r.outside } : { unknownPlacement: JSON.stringify(r.outside) };
1040
+ };
1041
+
879
1042
  /**
880
1043
  * The four values `milestonePlan` emits. Spelled out rather than accepted
881
1044
  * as any string, because a typo — or a producer inventing a fifth verdict —
@@ -918,7 +1081,32 @@ const normaliseSpecPlacement = (v: unknown): SpecPlacementRow | null => {
918
1081
  // A row claiming more placed than stated would let one spec carry another
919
1082
  // spec's shortfall, and the sum is the whole reading.
920
1083
  if (criteria < 0 || placed < 0 || placed > criteria) return null;
921
- return { path: s.path, state, criteria, placed, ...(s.deferred === true ? { deferred: true } : {}) };
1084
+ return {
1085
+ path: s.path,
1086
+ state,
1087
+ criteria,
1088
+ placed,
1089
+ ...(s.deferred === true ? { deferred: true } : {}),
1090
+ ...("board" in s ? { board: normaliseRowBoard(s.board) } : {}),
1091
+ };
1092
+ };
1093
+
1094
+ /**
1095
+ * A row's `board` declaration — SC-2776. Generic over the settings, so no key
1096
+ * is named here. A declaration that is PRESENT and malformed is kept as a
1097
+ * problem rather than dropped: dropping it would turn an opted-in spec into an
1098
+ * undeclared one, which leaves the measure, so the reading would get easier.
1099
+ */
1100
+ const normaliseRowBoard = (v: unknown): RowBoard => {
1101
+ const b = (typeof v === "object" && v !== null ? v : {}) as Partial<Record<keyof RowBoard, unknown>>;
1102
+ const settings = typeof b.settings === "object" && b.settings !== null && !Array.isArray(b.settings)
1103
+ ? Object.fromEntries(Object.entries(b.settings).filter((e): e is [string, string] => typeof e[1] === "string"))
1104
+ : null;
1105
+ const problems = Array.isArray(b.problems) ? b.problems.filter((p): p is string => typeof p === "string") : null;
1106
+ if (typeof b.scope !== "string" || settings === null || problems === null) {
1107
+ return { scope: "invalid", settings: {}, problems: ["the snapshot carries a board declaration this command cannot read"] };
1108
+ }
1109
+ return { scope: b.scope, settings, problems };
922
1110
  };
923
1111
 
924
1112
  const normaliseDeferral = (v: unknown): SpecDeferral | null => {
@@ -1114,6 +1302,15 @@ export function readSnapshotText(text: string): SnapshotRead {
1114
1302
  const deferrals = Array.isArray(raw.specDeferrals)
1115
1303
  ? { specDeferrals: raw.specDeferrals.map(normaliseDeferral).filter((d): d is SpecDeferral => d !== null) }
1116
1304
  : {};
1305
+ // SC-2776. Present-only, like the populations: absence is "never read".
1306
+ // A field that is neither a string nor null makes the whole object unread
1307
+ // rather than guessing which half to keep.
1308
+ const ec = raw.engineConfig as { spec?: unknown; prefix?: unknown } | undefined;
1309
+ const textOrNull = (v: unknown): v is string | null => v === null || typeof v === "string";
1310
+ const engine =
1311
+ typeof ec === "object" && ec !== null && textOrNull(ec.spec) && textOrNull(ec.prefix)
1312
+ ? { engineConfig: { spec: ec.spec, prefix: ec.prefix } }
1313
+ : {};
1117
1314
  const repoIssues = Array.isArray(raw.repoIssues)
1118
1315
  ? { repoIssues: raw.repoIssues.map(normaliseRepoIssue).filter((i): i is RepoIssueCriteria => i !== null) }
1119
1316
  : {};
@@ -1145,6 +1342,7 @@ export function readSnapshotText(text: string): SnapshotRead {
1145
1342
  ...queue,
1146
1343
  ...placements,
1147
1344
  ...deferrals,
1345
+ ...engine,
1148
1346
  ...repoIssues,
1149
1347
  ...edges,
1150
1348
  ...declared,
@@ -1170,7 +1368,7 @@ function normaliseDeclaredWork(raw: unknown): DeclaredWork | null {
1170
1368
  if (raw === null || typeof raw !== "object") return null;
1171
1369
  const r = raw as Record<string, unknown>;
1172
1370
  if (typeof r.id !== "string" || r.id === "" || typeof r.source !== "string") return null;
1173
- if (r.kind === "criterion") return { kind: "criterion", id: r.id, source: r.source };
1371
+ if (r.kind === "criterion") return { kind: "criterion", id: r.id, source: r.source, ...placementAnnotation(r) };
1174
1372
  if (r.kind !== "stage-item") return null;
1175
1373
  if (r.issue === null || r.issue === undefined) return { kind: "stage-item", id: r.id, source: r.source, issue: null };
1176
1374
  return typeof r.issue === "number" && Number.isInteger(r.issue)
@@ -66,7 +66,9 @@ import {
66
66
  isReady,
67
67
  mirrorRows,
68
68
  specCriteriaIn,
69
+ specPathSweep,
69
70
  } from "../lib/board-mirror";
71
+ import { placementCoverage } from "../lib/spec-placement";
70
72
 
71
73
  /**
72
74
  * THE one non-zero exit, so `test/board-mirror.test.ts` can build a mutant
@@ -76,15 +78,15 @@ import {
76
78
  export const REFUSAL_EXIT = 1;
77
79
 
78
80
  /**
79
- * Which open issues in the engine's milestone family lack the queue label —
80
- * #2062, SC-2609.
81
+ * Which open issues in any queued milestone family lack the queue label —
82
+ * #2062, SC-2609, widened to every opted-in family by SC-2777.
81
83
  *
82
84
  * `plan-issues --decompose` labels what it creates, and nothing labelled an
83
85
  * issue somebody milestoned by hand: on 2026-11-12 six such issues took the
84
86
  * `queue-label` reading (B6) from 12 of 12 to 6 of 12 (#2020). That reading
85
- * counts open issues whose milestone is in the engine family, so this picks
87
+ * counts open issues whose milestone is in a queued family, so this picks
86
88
  * its population with the same {@link inMilestoneFamily} rather than a test
87
- * of its own — two deciders of "engine issue" would disagree on some title,
89
+ * of its own — two deciders of "queued issue" would disagree on some title,
88
90
  * and the repair would leave the reading short while reporting nothing to do.
89
91
  *
90
92
  * A cut label list is `unreadable`, not missing: the label may be on the page
@@ -92,13 +94,15 @@ export const REFUSAL_EXIT = 1;
92
94
  */
93
95
  export function queueLabelRepairs(
94
96
  issues: readonly Pick<LiveIssue, "number" | "state" | "milestone" | "labels" | "labelsTruncated">[],
95
- prefix: string,
97
+ families: readonly string[],
96
98
  queueLabel: string,
97
99
  ): { add: number[]; unreadable: number[] } {
98
100
  const add: number[] = [];
99
101
  const unreadable: number[] = [];
100
102
  for (const i of issues) {
101
- if (i.state !== "OPEN" || !inMilestoneFamily(i.milestone, prefix)) continue;
103
+ // SC-2777: any family the queue holds, through the same inMilestoneFamily
104
+ // the readings use, so "in a family" has one answer.
105
+ if (i.state !== "OPEN" || !families.some(f => inMilestoneFamily(i.milestone, f))) continue;
102
106
  if (i.labels.includes(queueLabel)) continue;
103
107
  if (i.labelsTruncated === true) unreadable.push(i.number);
104
108
  else add.push(i.number);
@@ -106,6 +110,49 @@ export function queueLabelRepairs(
106
110
  return { add, unreadable };
107
111
  }
108
112
 
113
+ /**
114
+ * The milestone families whose phase issues belong in the one queue — SC-2777.
115
+ *
116
+ * Every spec that opts itself in (`board: { scope: active, prefix }`, SC-2776)
117
+ * names its family; there is no list in config (ADR-018 Decision 1). The
118
+ * configured engine family, `board.milestonePrefix`, is included as well, so a
119
+ * tree whose specs have not opted in yet labels exactly what it labelled
120
+ * before. The spec-placement reading holds the engine spec's own block to
121
+ * that config, so the two do not drift apart unseen.
122
+ *
123
+ * A sweep that could not be read is UNMEASURED, not "no families": labelling
124
+ * from a partial list would leave an opted-in family out of the queue with
125
+ * nothing saying so. No family at all is refused the same way.
126
+ */
127
+ export function queueFamilies(root: string): { families: string[]; unmeasured: string | null } {
128
+ const sweep = placementCoverage(root, specPathSweep, (base, path) => readFileSync(join(base, path), "utf-8"));
129
+ if (sweep.reading === "UNMEASURED") {
130
+ return {
131
+ families: [],
132
+ unmeasured:
133
+ `board-mirror: UNMEASURED — the specs/ sweep could not be read, so which families opt in is unknown: ` +
134
+ `${sweep.unmeasuredReasons.join("; ")}. Nothing written.`,
135
+ };
136
+ }
137
+ const families = new Set<string>();
138
+ for (const s of sweep.specs) {
139
+ const prefix = s.board.settings.prefix;
140
+ if (s.board.scope === "active" && prefix !== undefined) families.add(prefix);
141
+ }
142
+ const engine = enginePrefixReading(root);
143
+ if (engine.prefix !== null) families.add(engine.prefix);
144
+ if (families.size === 0) {
145
+ return {
146
+ families: [],
147
+ unmeasured:
148
+ engine.unmeasured ??
149
+ "board-mirror: UNMEASURED — no spec opts into the engine (board: { scope: active, prefix }) and " +
150
+ "board.milestonePrefix is not set, so there is no family to label. Nothing written.",
151
+ };
152
+ }
153
+ return { families: [...families].sort(), unmeasured: null };
154
+ }
155
+
109
156
  /**
110
157
  * `board-mirror --queue-label --repo owner/name [--write]` — #2062, SC-2609.
111
158
  *
@@ -122,14 +169,15 @@ export function queueLabelRepairs(
122
169
  * milestoned by a tool (whose `GITHUB_TOKEN` write fires no event) is repaired
123
170
  * by the next run.
124
171
  *
125
- * Refuses, writing nothing, when the engine family or the queue label is not
126
- * configured — a tree that never named a queue has no queue, not an empty one
127
- * — or when any candidate's label list was cut.
172
+ * Refuses, writing nothing, when no family can be read ({@link queueFamilies})
173
+ * or the queue label is not configured — a tree that never named a queue has
174
+ * no queue, not an empty one — or when any candidate's label list was cut.
128
175
  */
129
176
  export async function queueLabelRun(opts: {
130
177
  repo: string;
131
- prefix: string | null;
132
- prefixUnmeasured: string | null;
178
+ /** Every family the queue holds — {@link queueFamilies}. Empty refuses. */
179
+ families: readonly string[];
180
+ familiesUnmeasured: string | null;
133
181
  queueLabel: string | null;
134
182
  write: boolean;
135
183
  exec?: GraphQlExec;
@@ -137,11 +185,8 @@ export async function queueLabelRun(opts: {
137
185
  }): Promise<number> {
138
186
  const log = opts.log ?? ((line: string) => console.log(line));
139
187
  const exec = opts.exec ?? ghWithoutGhToken;
140
- if (opts.prefix === null) {
141
- log(
142
- opts.prefixUnmeasured ??
143
- "board-mirror: UNMEASURED — board.milestonePrefix is not set, so there is no engine family to label. Nothing written.",
144
- );
188
+ if (opts.families.length === 0) {
189
+ log(opts.familiesUnmeasured ?? "board-mirror: UNMEASURED — there is no milestone family to label. Nothing written.");
145
190
  return REFUSAL_EXIT;
146
191
  }
147
192
  if (opts.queueLabel === null) {
@@ -149,7 +194,7 @@ export async function queueLabelRun(opts: {
149
194
  return REFUSAL_EXIT;
150
195
  }
151
196
  const issues = await readLiveIssues(opts.repo, false, exec);
152
- const { add, unreadable } = queueLabelRepairs(issues, opts.prefix, opts.queueLabel);
197
+ const { add, unreadable } = queueLabelRepairs(issues, opts.families, opts.queueLabel);
153
198
  if (unreadable.length > 0) {
154
199
  log(
155
200
  `board-mirror: UNMEASURED — the label list was cut for ${unreadable.map(n => `#${n}`).join(", ")}, so ` +
@@ -158,7 +203,10 @@ export async function queueLabelRun(opts: {
158
203
  return REFUSAL_EXIT;
159
204
  }
160
205
  if (add.length === 0) {
161
- log(`board-mirror: every open "${opts.prefix} Phase" issue carries "${opts.queueLabel}" — nothing to add.`);
206
+ log(
207
+ `board-mirror: every open issue in ${opts.families.map(f => `"${f} Phase"`).join(", ")} carries ` +
208
+ `"${opts.queueLabel}" — nothing to add.`,
209
+ );
162
210
  return 0;
163
211
  }
164
212
  // Every repair is attempted, and the run ends red naming each that failed
@@ -417,7 +465,9 @@ const USAGE = `rungate board-mirror --project <node-id> [--spec <spec.md>] [--fi
417
465
  rungate board-mirror --queue-label --repo <owner/name> [--write]
418
466
 
419
467
  --queue-label instead of the board, add board.queueLabel to every open
420
- issue in the engine's milestone family that lacks it (#2062).
468
+ issue in an opted-in family's phase milestone that lacks it:
469
+ every spec with board: { scope: active, prefix }, plus
470
+ board.milestonePrefix (#2062, SC-2777).
421
471
  Needs --repo, and refuses --project: it is an issue write made
422
472
  with the repository's own token, never the board token.
423
473
 
@@ -539,11 +589,11 @@ export async function main(argv: string[]): Promise<number> {
539
589
  return REFUSAL_EXIT;
540
590
  }
541
591
  const labelRoot = values["project-root"] ?? process.cwd();
542
- const engine = enginePrefixReading(labelRoot);
592
+ const read = queueFamilies(labelRoot);
543
593
  return queueLabelRun({
544
594
  repo: values.repo,
545
- prefix: engine.prefix,
546
- prefixUnmeasured: engine.unmeasured,
595
+ families: read.families,
596
+ familiesUnmeasured: read.unmeasured,
547
597
  queueLabel: readQueueLabel(labelRoot),
548
598
  write: values.write,
549
599
  });