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.
- package/gates/.gate-salt +1 -1
- package/lib/finding-promotion.ts +57 -0
- package/lib/issue-repair.ts +124 -0
- package/lib/scaffold/managed-workflow.ts +112 -26
- package/lib/scaffold/owned-files.ts +4 -4
- package/lib/scaffold/steps.ts +12 -0
- package/lib/spec-placement.ts +320 -11
- package/package.json +1 -1
- package/scripts/board-conformance.ts +224 -26
- package/scripts/board-mirror.ts +72 -22
- package/scripts/board-snapshot.ts +73 -13
- package/scripts/create-sc.ts +34 -2
- package/scripts/plan-issues.ts +221 -14
|
@@ -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
|
|
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
|
-
|
|
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 `
|
|
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:
|
|
606
|
+
measured: counted.filter(
|
|
484
607
|
c => (typeof c.satisfiedByIssue === "number" && present.has(c.satisfiedByIssue)) || c.recordedTrue === true,
|
|
485
608
|
).length,
|
|
486
|
-
target:
|
|
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
|
|
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
|
-
|
|
608
|
-
|
|
609
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
748
|
-
"which is not the same as a repository that declares none"
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
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
|
-
|
|
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 {
|
|
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)
|
package/scripts/board-mirror.ts
CHANGED
|
@@ -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
|
|
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
|
|
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 "
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
126
|
-
* configured — a tree that never named a queue has
|
|
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
|
-
|
|
132
|
-
|
|
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.
|
|
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.
|
|
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(
|
|
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
|
|
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
|
|
592
|
+
const read = queueFamilies(labelRoot);
|
|
543
593
|
return queueLabelRun({
|
|
544
594
|
repo: values.repo,
|
|
545
|
-
|
|
546
|
-
|
|
595
|
+
families: read.families,
|
|
596
|
+
familiesUnmeasured: read.unmeasured,
|
|
547
597
|
queueLabel: readQueueLabel(labelRoot),
|
|
548
598
|
write: values.write,
|
|
549
599
|
});
|