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.
@@ -34,13 +34,14 @@
34
34
  */
35
35
  import { spawnSync } from "child_process";
36
36
  import { existsSync, readFileSync } from "fs";
37
- import { isAbsolute, join } from "path";
37
+ import { isAbsolute, join, relative } from "path";
38
38
  import { parseArgs } from "util";
39
39
  import { describeSpecSource, resolveSpecSource, type GitRunner } from "../lib/spec-source";
40
40
  import { openFrontier, phaseOf } from "../lib/board-mirror";
41
41
  import { withoutAmbientGitOverrides } from "../lib/git-isolation";
42
42
  import { createGitHubClient, listMilestones } from "../lib/github";
43
43
  import { readBoardConfig, readBoardInputs, readQueueLabel } from "../lib/config-readers";
44
+ import { resolveConfig } from "../lib/config-loader";
44
45
  import { resolveRepoSlug } from "../lib/branch-cleanup";
45
46
  import {
46
47
  inMilestoneFamily,
@@ -56,9 +57,12 @@ import {
56
57
  criterionCoverage,
57
58
  familyOf,
58
59
  milestonePlan,
60
+ outsidePhases,
59
61
  placementCoverage,
62
+ placementsById,
60
63
  placementReading,
61
64
  type CriterionCoverage,
65
+ type SpecPlacement,
62
66
  } from "../lib/spec-placement";
63
67
  // SC-2615, SC-2616, SC-2617 — the three repository-wide populations.
64
68
  import { answerableIds, criterionAnswer, specCriteriaIn, specPathSweep } from "../lib/board-mirror";
@@ -240,6 +244,8 @@ export interface ProducedSnapshot {
240
244
  specPlacements?: SpecPlacementRow[];
241
245
  /** SC-2734: the bank in `.claude/spec-deferral-ratchet.json`. Absent when it could not be read. */
242
246
  specDeferrals?: SpecDeferral[];
247
+ /** SC-2776: `board.engineSpec` and `board.milestonePrefix` as the config holds them. */
248
+ engineConfig?: { spec: string | null; prefix: string | null };
243
249
  repoIssues?: RepoIssueCriteria[];
244
250
  plannedEdges?: PlannedEdge[];
245
251
  /** SC-2752: unticked criteria in in-scope specs and open stage items. Absent when it could not be read. */
@@ -253,8 +259,9 @@ export interface ProducedSnapshot {
253
259
  *
254
260
  * Every unticked criterion in an in-scope spec, then every open stage item
255
261
  * in `project-state.json`. In scope is the same population `spec-placement`
256
- * counts: a spec that states criteria (`PLANNED` or `UNPLANNED`) and is not
257
- * deferred. The criteria are read through `parseCriteria`, the one reader of
262
+ * counts: a spec that states criteria (`PLANNED` or `UNPLANNED`) and opts in
263
+ * with `board: { scope: active }` (SC-2776). A spec that declares nothing is
264
+ * never planned, so its unticked criteria are not work anybody declared. The criteria are read through `parseCriteria`, the one reader of
258
265
  * a spec's checkbox lines, so "unticked" has one answer in the tree.
259
266
  *
260
267
  * A consumer repository has no `project-state.json`: an absent file declares
@@ -266,12 +273,14 @@ export interface ProducedSnapshot {
266
273
  */
267
274
  export function readDeclaredWork(
268
275
  root: string,
269
- specs: readonly { path: string; state: SpecPlacementRow["state"]; deferred?: boolean }[],
276
+ specs: readonly { path: string; state: SpecPlacementRow["state"]; deferred?: boolean; board?: { scope: string } }[],
270
277
  ): { declaredWork?: DeclaredWork[] } {
271
278
  const work: DeclaredWork[] = [];
272
279
  for (const s of specs) {
273
- if (s.deferred === true || s.state === "NO_CRITERIA") continue;
280
+ // UNREADABLE first: a spec nobody could read has no declaration to be
281
+ // read either, and skipping it as "not opted in" would shorten the list.
274
282
  if (s.state === "UNREADABLE") return {};
283
+ if (s.board?.scope !== "active" || s.state === "NO_CRITERIA") continue;
275
284
  let content: string;
276
285
  try {
277
286
  content = readFileSync(join(root, s.path), "utf-8");
@@ -279,7 +288,12 @@ export function readDeclaredWork(
279
288
  // Named as UNMEASURED by the omitted key, never read as an empty spec.
280
289
  return {};
281
290
  }
282
- for (const c of parseCriteria(content)) if (!c.ticked) work.push({ kind: "criterion", id: c.id, source: s.path });
291
+ // SC-2778: the same predicate criterion-coverage's rows go through, so
292
+ // the two readings agree on every criterion the spec parks.
293
+ const placed = placementsById(content);
294
+ for (const c of parseCriteria(content)) {
295
+ if (!c.ticked) work.push({ kind: "criterion", id: c.id, source: s.path, ...outsidePhases(placed.get(c.id)) });
296
+ }
283
297
  }
284
298
  const statePath = join(root, "project-state.json");
285
299
  if (existsSync(statePath)) {
@@ -323,6 +337,55 @@ export const DEFERRAL_BANK = ".claude/spec-deferral-ratchet.json";
323
337
  * file is absent or is not `{ "deferred": [{ path, criteria }] }`, and says
324
338
  * which on stderr, because a corrupt bank is never a missing one.
325
339
  */
340
+ /**
341
+ * One sweep row as the snapshot carries it — SC-2615, SC-2734, SC-2776.
342
+ *
343
+ * Present-only, so a row from a spec that declares nothing is the same
344
+ * bytes it always was. The `board:` declaration travels with the row because
345
+ * `board-conformance` names it by path and cannot re-read the file (it stays
346
+ * import-free).
347
+ */
348
+ export function placementRow(s: SpecPlacement): SpecPlacementRow {
349
+ return {
350
+ path: s.path,
351
+ state: s.state,
352
+ criteria: s.criteria,
353
+ placed: s.placed,
354
+ ...(s.deferred ? { deferred: true } : {}),
355
+ // Whole, so a setting added to BOARD_KEYS reaches the reading untouched.
356
+ // Unknown keys stay behind: they never block a reading (ADR-018 Decision 9).
357
+ ...(s.board.scope !== "undeclared"
358
+ ? { board: { scope: s.board.scope, settings: { ...s.board.settings }, problems: [...s.board.problems] } }
359
+ : {}),
360
+ };
361
+ }
362
+
363
+ /**
364
+ * What the config says the engine is — SC-2776 — carried as DATA so
365
+ * `board-conformance` (import-free) can hold the engine spec's own `board:`
366
+ * block to it. Paths are spelled the way the sweep spells them, so
367
+ * `./specs/X.md` and `specs/X.md` are one spec.
368
+ *
369
+ * **A config nobody could find omits the key.** `readBoardInputs` returns the
370
+ * same two `null`s for an absent config and for one that sets neither key,
371
+ * and `null` here means "nothing to disagree with", so a run from the wrong
372
+ * directory would read as agreement. `resolveConfig` separates the two, as
373
+ * `enginePrefixReading` does for #1965 (review of #2308).
374
+ */
375
+ export function readEngineConfig(root: string): { engineConfig?: { spec: string | null; prefix: string | null } } {
376
+ if (resolveConfig(root).status === "absent") return {};
377
+ const configured = readBoardInputs(root);
378
+ return {
379
+ engineConfig: {
380
+ spec:
381
+ configured.engineSpec === null
382
+ ? null
383
+ : relative(root, isAbsolute(configured.engineSpec) ? configured.engineSpec : join(root, configured.engineSpec)),
384
+ prefix: configured.milestonePrefix,
385
+ },
386
+ };
387
+ }
388
+
326
389
  export function readDeferralBank(root: string): { specDeferrals?: SpecDeferral[] } {
327
390
  const path = join(root, DEFERRAL_BANK);
328
391
  if (!existsSync(path)) {
@@ -832,15 +895,11 @@ export async function main(
832
895
  coverage.specs.length === 0 && coverage.reading === "UNMEASURED"
833
896
  ? {}
834
897
  : {
835
- specPlacements: coverage.specs.map(s => ({
836
- path: s.path,
837
- state: s.state,
838
- criteria: s.criteria,
839
- placed: s.placed,
840
- ...(s.deferred ? { deferred: true } : {}),
841
- })),
898
+ specPlacements: coverage.specs.map(placementRow),
842
899
  };
843
900
 
901
+ const engineConfig = readEngineConfig(root);
902
+
844
903
  // SC-2734. The bank the deferred specs are compared against. An absent or
845
904
  // malformed file omits the key, and the reading goes UNMEASURED as soon as
846
905
  // any spec declares itself deferred — a bank nobody could read is not an
@@ -935,6 +994,7 @@ export async function main(
935
994
  criteria: criterionCoverage(content, snapshotIssues, columnRead),
936
995
  ...placements,
937
996
  ...deferrals,
997
+ ...engineConfig,
938
998
  ...repoIssues,
939
999
  ...edges,
940
1000
  ...declared,
@@ -26,7 +26,8 @@ import { describeReading } from "../lib/sc-id-cross-tree";
26
26
  import { currentScOwner } from "../lib/sc-reservations";
27
27
  import { skipLine } from "../lib/derived-spec";
28
28
  import { maySpecBeWritten, writeSpec } from "../lib/write-spec";
29
- import { join } from "path";
29
+ import { join, relative, resolve, sep } from "path";
30
+ import { bankAfterAppend, writeSpecWithBank } from "../lib/finding-promotion";
30
31
 
31
32
  /** Same resolution sync-sc-status uses, so both halves read one tree. */
32
33
  const ROOT = join(import.meta.dir, "..");
@@ -127,8 +128,39 @@ try {
127
128
 
128
129
  // Append SC line to the end of the file
129
130
  const newContent = content.trimEnd() + "\n" + scLine + "\n";
130
- writeSpec(specPath, newContent);
131
+ // A deferred spec's criteria count is banked, and SC-2734 refuses a bank
132
+ // that disagrees with it. Decided BEFORE the spec is written, so a refusal
133
+ // writes neither file. The path is a literal so the spec-write sweep
134
+ // (#1584) can see this write targets the bank and not a spec.
135
+ const bankPath = join(ROOT, ".claude/spec-deferral-ratchet.json");
136
+ const specKey = relative(ROOT, resolve(specPath)).split(sep).join("/");
137
+ const banked = bankAfterAppend(existsSync(bankPath) ? readFileSync(bankPath, "utf-8") : null, specKey, content, newContent);
138
+ if (!banked.ok) {
139
+ console.error(`ERROR: ${banked.refusal}: ${banked.why}`);
140
+ process.exit(1);
141
+ }
142
+ // Both through `writeSpec`, as finding-promotion does: the one write path
143
+ // the spec-write sweep (#1552) allows for a path matching /spec/i. Both
144
+ // or neither: a failed bank write puts the spec back.
145
+ // The bank write is spelled `writeSpec(bankPath, …)` so write
146
+ // accountability (#624) resolves it to the bank, as it does
147
+ // finding-promotion's, rather than reading an opaque `writeSpec(p)`.
148
+ const wrote = writeSpecWithBank(
149
+ (p, c) => (p === bankPath ? writeSpec(bankPath, c) : writeSpec(p, c)),
150
+ { path: specPath, before: content, after: newContent },
151
+ { path: bankPath, text: banked.text },
152
+ );
153
+ if (!wrote.ok) {
154
+ console.error(
155
+ wrote.restored
156
+ ? `ERROR: ${wrote.why}. Nothing was changed: ${specPath} is as it was.`
157
+ : `ERROR: ${wrote.why}, and ${specPath} could not be put back: it states SC-${scNumber} and the bank does not. ` +
158
+ `Remove that line, or move ${specKey}'s count in .claude/spec-deferral-ratchet.json by one.`,
159
+ );
160
+ process.exit(1);
161
+ }
131
162
  console.log(`Appended to ${specPath}: ${scLine}`);
163
+ if (banked.text !== null) console.log(` deferral bank: ${specKey} moved with it (.claude/spec-deferral-ratchet.json)`);
132
164
  // What the number is a floor over, stated rather than implied. A clone on
133
165
  // another machine is outside anything this process can reach, and an
134
166
  // allocator that printed only the number would be claiming a guarantee it
@@ -36,11 +36,12 @@ import {
36
36
  CRITERIA_HEADING,
37
37
  alreadyAnnotated,
38
38
  annotatedBody,
39
+ issuePlacement,
39
40
  multiplyAnnotated,
40
41
  parseRepairPlan,
41
42
  rowPlacement,
42
43
  } from "../lib/issue-repair";
43
- import type { RepairRow } from "../lib/issue-repair";
44
+ import type { IssueMove, PlacingFamily, RepairRow } from "../lib/issue-repair";
44
45
  import {
45
46
  closedIssueCounts,
46
47
  hasDecompositionTable,
@@ -49,9 +50,9 @@ import {
49
50
  planDecomposition,
50
51
  } from "../lib/issue-decomposition";
51
52
  import { readQueueLabel } from "../lib/config-readers";
52
- import { answerableIds, specCriteriaIn } from "../lib/board-mirror";
53
- import { milestonePlan, placementReading } from "../lib/spec-placement";
54
- import { readMilestonePrefix } from "../lib/live-issues";
53
+ import { answerableIds, specCriteriaIn, specPathSweep } from "../lib/board-mirror";
54
+ import { milestonePlan, placementCoverage, placementReading, placementsById } from "../lib/spec-placement";
55
+ import { readLiveIssues, readMilestonePrefix } from "../lib/live-issues";
55
56
  import type { LiveMilestone, MilestoneAction } from "../lib/spec-placement";
56
57
 
57
58
  /**
@@ -200,6 +201,25 @@ const USAGE = `rungate plan-issues (--repair | --decompose) <plan.md> --repo <ow
200
201
  --write apply it. Without this nothing is mutated.
201
202
  --json the whole reading.
202
203
 
204
+ rungate plan-issues --place --repo <owner/name> [--write] [--json] [--project-root <dir>]
205
+
206
+ Move each open issue into the phase milestone its criteria hold, read from
207
+ every spec that opts in with board: { scope: active, prefix } (SC-2779).
208
+ Criteria in one phase of one family: moved there, from no milestone or from
209
+ another of that family's phases. No milestone and several phases: the
210
+ lowest. Left where it is, and named: criteria from two families, a
211
+ milestone plus several phases, a milestone outside the family, a criterion
212
+ placed outside every phase, or an issue that says it serves no criterion.
213
+ A phase with no milestone, or a spec the run cannot read, refuses the run
214
+ before anything is written; plan-spec makes milestones, this never does.
215
+
216
+ rungate plan-issues --families [--project-root <dir>]
217
+
218
+ Print each opted-in family as <prefix><TAB><spec path>, one per line and
219
+ nothing else on stdout — the list a workflow loops plan-spec and plan-deps
220
+ over. The same reading --place takes, so the two never disagree; it refuses
221
+ on the same unreadable specs. Reads no tracker.
222
+
203
223
  rungate plan-issues --accepted-since <commit> [--project-root <dir>]
204
224
 
205
225
  Print each docs/adr/*.md that is accepted now and was not at <commit>, and
@@ -618,10 +638,174 @@ interface Action {
618
638
  note: string;
619
639
  }
620
640
 
641
+ /**
642
+ * Why a spec's placement table cannot place anything — #2072, and SC-2779.
643
+ *
644
+ * THE one decider, read by `--milestone-prefix` and `--place` alike, so the
645
+ * two cannot disagree about whether a table is usable (review of #2315). The
646
+ * three readings `plan-spec` and `board-snapshot` already refuse: a doubled id
647
+ * goes to whichever row comes last, an unknown one reads as two families at
648
+ * once, and an unrecognised value is neither a phase nor a known non-phase.
649
+ * `unplaced` is left out on purpose: a criterion in no row has no phase, and
650
+ * each caller already skips, refuses or leaves an issue naming one.
651
+ */
652
+ export function unsoundPlacement(placement: ReturnType<typeof placementReading>): string[] {
653
+ return [
654
+ ...placement.doubled.map(d => `${d.id} is placed twice: ${d.placements.join(" and ")}`),
655
+ ...placement.unknown.map(id => `${id} is placed but stated nowhere in the spec`),
656
+ ...placement.unrecognised.map(p => `"${p}" is neither a phase nor a known non-phase placement`),
657
+ ];
658
+ }
659
+
660
+ /** What `--place` needs from the tracker. Injected so a test never shells out. */
661
+ export interface PlaceGitHub {
662
+ /** Every milestone, open or closed — the same paginated read `--repair` uses. */
663
+ milestones: (repo: string) => Promise<LiveMilestone[]>;
664
+ /** Every OPEN issue, through the one reader the board readings use. */
665
+ openIssues: (repo: string) => Promise<{ number: number; title: string; body: string | null; milestone: string | null }[]>;
666
+ setMilestone: (repo: string, number: number, title: string) => Promise<void>;
667
+ }
668
+
669
+ const LIVE_PLACE: PlaceGitHub = {
670
+ milestones: LIVE_GITHUB.milestones,
671
+ openIssues: async repo => (await readLiveIssues(repo, false)).filter(i => i.state === "OPEN"),
672
+ setMilestone: LIVE_GITHUB.setMilestone,
673
+ };
674
+
675
+ /**
676
+ * Every opted-in family, with the milestone each placed phase has — SC-2779.
677
+ *
678
+ * The families are the specs whose frontmatter says
679
+ * `board: { scope: active, prefix }` (SC-2776); there is no list in config.
680
+ * Anything that would make the list partial refuses the whole run, by name: a
681
+ * sweep that could not be read, a `board:` block the engine could not read
682
+ * (that spec may be a family), a family's placement table that is missing or
683
+ * unsound, or two specs claiming one prefix. A partial list is worse than
684
+ * none, because the two-family rule is exactly the one that needs every
685
+ * family in view.
686
+ */
687
+ export function placingFamilies(
688
+ root: string,
689
+ live: readonly LiveMilestone[],
690
+ ): { families: PlacingFamily[]; paths: string[]; specs: string[]; refusals: string[] } {
691
+ const read = (base: string, path: string) => readFileSync(join(base, path), "utf-8");
692
+ const sweep = placementCoverage(root, specPathSweep, read);
693
+ if (sweep.reading === "UNMEASURED") return { families: [], paths: [], specs: [], refusals: sweep.unmeasuredReasons };
694
+ const refusals: string[] = [];
695
+ const families: PlacingFamily[] = [];
696
+ const paths: string[] = [];
697
+ const specs: string[] = [];
698
+ const byPrefix = new Map<string, string>();
699
+ for (const spec of sweep.specs) {
700
+ if (spec.board.problems.length > 0) {
701
+ refusals.push(`${spec.path}: its board: declaration cannot be read — ${spec.board.problems.join("; ")}`);
702
+ continue;
703
+ }
704
+ const prefix = spec.board.settings.prefix;
705
+ if (spec.board.scope !== "active" || prefix === undefined) continue;
706
+ const other = byPrefix.get(prefix);
707
+ if (other !== undefined) {
708
+ refusals.push(`${spec.path} and ${other} both declare prefix ${prefix}, so its milestones belong to neither`);
709
+ continue;
710
+ }
711
+ byPrefix.set(prefix, spec.path);
712
+ const text = read(root, spec.path);
713
+ const placement = placementReading(text);
714
+ const unsound = [...placement.unmeasuredReasons, ...unsoundPlacement(placement)];
715
+ if (unsound.length > 0) {
716
+ refusals.push(`${spec.path} (${prefix}): its placement table cannot place an issue — ${unsound.join("; ")}`);
717
+ continue;
718
+ }
719
+ const milestones = new Map<number, string>();
720
+ for (const a of milestonePlan(text, [...live], prefix).actions) if (a.existing) milestones.set(a.phase, a.existing.title);
721
+ families.push({ prefix, stated: placement.criteria, placements: placementsById(text), milestones });
722
+ paths.push(`${prefix}: ${spec.path}`);
723
+ specs.push(spec.path);
724
+ }
725
+ return refusals.length > 0 ? { families: [], paths: [], specs: [], refusals } : { families, paths, specs, refusals: [] };
726
+ }
727
+
728
+ /** `--place`: the run SC-2780 calls, after `plan-spec` and before `plan-deps`. */
729
+ async function place(gh4: PlaceGitHub, root: string, repo: string, write: boolean, json: boolean): Promise<number> {
730
+ // Both tracker reads refuse the way `decompose` does (review of #2315): a
731
+ // rate limit or a network blip is an unreadable tracker, reported as such.
732
+ const unreadable = (e: unknown): number => {
733
+ console.error(`plan-issues --place: UNMEASURED — could not read the tracker, so nothing was placed:`);
734
+ console.error(` - ${(e as Error).message}`);
735
+ return REFUSAL_EXIT;
736
+ };
737
+ let live: LiveMilestone[];
738
+ try {
739
+ live = await gh4.milestones(repo);
740
+ } catch (e) {
741
+ return unreadable(e);
742
+ }
743
+ const read = placingFamilies(root, live);
744
+ if (read.refusals.length > 0) {
745
+ console.error(`plan-issues --place: UNMEASURED — the opted-in families could not be read, so nothing was placed:`);
746
+ for (const r of read.refusals) console.error(` - ${r}`);
747
+ return REFUSAL_EXIT;
748
+ }
749
+ let issues: Awaited<ReturnType<PlaceGitHub["openIssues"]>>;
750
+ try {
751
+ issues = (await gh4.openIssues(repo)).sort((a, b) => a.number - b.number);
752
+ } catch (e) {
753
+ return unreadable(e);
754
+ }
755
+ const moves: { issue: number; move: IssueMove }[] = issues.map(i => ({ issue: i.number, move: issuePlacement(i, read.families) }));
756
+ const refused = moves.filter(m => m.move.kind === "refuse");
757
+ const count = (k: IssueMove["kind"]) => moves.filter(m => m.move.kind === k).length;
758
+ const results: string[] = [];
759
+ if (write && refused.length === 0) {
760
+ for (const m of moves) {
761
+ if (m.move.kind !== "move") continue;
762
+ try {
763
+ await gh4.setMilestone(repo, m.issue, m.move.milestone);
764
+ results.push(`placed #${m.issue} in "${m.move.milestone}"`);
765
+ } catch (e) {
766
+ results.push(`FAILED #${m.issue}: ${(e as Error).message}`);
767
+ }
768
+ }
769
+ }
770
+ const failed = results.filter(r => r.startsWith("FAILED"));
771
+ const blocked = refused.length > 0;
772
+ if (json) {
773
+ const wrote = !write ? "not-requested" : blocked ? "refused" : failed.length > 0 ? "partial" : "yes";
774
+ console.log(JSON.stringify({ families: read.paths, moves, results, wrote }, null, 2));
775
+ return blocked || failed.length > 0 ? REFUSAL_EXIT : 0;
776
+ }
777
+ console.log(`plan-issues --place — ${read.families.length} opted-in famil${read.families.length === 1 ? "y" : "ies"}, ${issues.length} open issue(s)`);
778
+ for (const p of read.paths) console.log(` ${p}`);
779
+ if (read.families.length === 0) console.log(` No spec opts in with board: { scope: active, prefix }, so no issue has a phase.`);
780
+ const mark = { move: "MOVE ", stay: "", left: "LEFT ", none: "", refuse: "REFUSED " } as const;
781
+ console.log(`\nACTIONS`);
782
+ for (const m of moves) if (mark[m.move.kind] !== "") console.log(` ${mark[m.move.kind]} #${m.issue} ${"why" in m.move ? m.move.why : ""}`);
783
+ console.log(
784
+ `\n ${count("move")} to move, ${count("stay")} already placed, ${count("left")} left where they are, ` +
785
+ `${count("none")} name no opted-in criterion, ${count("refuse")} refused`,
786
+ );
787
+ if (blocked) {
788
+ console.error(`\nplan-issues --place: ${refused.length} issue(s) belong in a phase with no milestone, so nothing was written.`);
789
+ return REFUSAL_EXIT;
790
+ }
791
+ if (!write) {
792
+ console.log(`\nNothing written. Re-run with --write to apply.`);
793
+ return 0;
794
+ }
795
+ console.log(`\nWRITING`);
796
+ for (const r of results) console.log(` ${r}`);
797
+ if (failed.length > 0) {
798
+ console.error(`\nplan-issues --place: ${failed.length} move(s) FAILED.`);
799
+ return REFUSAL_EXIT;
800
+ }
801
+ return 0;
802
+ }
803
+
621
804
  export async function main(
622
805
  argv: string[],
623
806
  gh2: PlanIssuesGitHub = LIVE_GITHUB,
624
807
  gh3: DecomposeGitHub = LIVE_DECOMPOSE,
808
+ gh4: PlaceGitHub = LIVE_PLACE,
625
809
  ): Promise<number> {
626
810
  let parsed;
627
811
  try {
@@ -637,6 +821,8 @@ export async function main(
637
821
  "accepted-since": { type: "string" },
638
822
  "milestone-prefix": { type: "string" },
639
823
  spec: { type: "string" },
824
+ place: { type: "boolean", default: false },
825
+ families: { type: "boolean", default: false },
640
826
  },
641
827
  allowPositionals: true,
642
828
  });
@@ -645,6 +831,35 @@ export async function main(
645
831
  return REFUSAL_EXIT;
646
832
  }
647
833
  const { values } = parsed;
834
+ if (values.families) {
835
+ // A listing, not a plan: alone, so nothing it prints is mistaken for a write.
836
+ if (values.place || values.repair || values.decompose || values["accepted-since"] !== undefined || values["milestone-prefix"] !== undefined || values.spec !== undefined || values.write || values.json) {
837
+ console.error(`plan-issues: --families lists the opted-in families and applies nothing — pass it alone, with --project-root at most\n\n${USAGE}`);
838
+ return REFUSAL_EXIT;
839
+ }
840
+ // No milestones: which specs are families does not depend on the tracker.
841
+ const read = placingFamilies(values["project-root"] ?? process.cwd(), []);
842
+ if (read.refusals.length > 0) {
843
+ console.error(`plan-issues --families: UNMEASURED — the opted-in families could not be read:`);
844
+ for (const r of read.refusals) console.error(` - ${r}`);
845
+ return REFUSAL_EXIT;
846
+ }
847
+ for (const [i, fam] of read.families.entries()) console.log(`${fam.prefix}\t${read.specs[i]}`);
848
+ return 0;
849
+ }
850
+ if (values.place) {
851
+ // A third plan, read from the specs rather than from a file: one at a time.
852
+ if (values.repair || values.decompose || values["accepted-since"] !== undefined || values["milestone-prefix"] !== undefined || values.spec !== undefined) {
853
+ console.error(`plan-issues: --place reads every opted-in spec itself — pass it with --repo, --write, --json and --project-root only\n\n${USAGE}`);
854
+ return REFUSAL_EXIT;
855
+ }
856
+ const placeRepo = values.repo ?? process.env.GITHUB_REPOSITORY;
857
+ if (!placeRepo) {
858
+ console.error(`plan-issues: --repo is required (or set GITHUB_REPOSITORY)\n\n${USAGE}`);
859
+ return REFUSAL_EXIT;
860
+ }
861
+ return await place(gh4, values["project-root"] ?? process.cwd(), placeRepo, values.write, values.json);
862
+ }
648
863
  if (values["accepted-since"] !== undefined) {
649
864
  if (values.repair || values.decompose) {
650
865
  console.error(`plan-issues: --accepted-since lists plans; it applies none — pass it alone\n\n${USAGE}`);
@@ -724,16 +939,8 @@ export async function main(
724
939
  for (const r of placement.unmeasuredReasons) console.error(` - ${r}`);
725
940
  return REFUSAL_EXIT;
726
941
  }
727
- // #2072: the three readings plan-spec and board-snapshot already refuse.
728
- // A doubled id would go to whichever phase row comes last, and an
729
- // unknown one reads as two families at once. `unplaced` is left out on
730
- // purpose: a criterion in no row has no phase, and `rowPlacement`
731
- // already skips or refuses a row naming one.
732
- const unsound = [
733
- ...placement.doubled.map(d => `${d.id} is placed twice: ${d.placements.join(" and ")}`),
734
- ...placement.unknown.map(id => `${id} is placed but stated nowhere in the spec`),
735
- ...placement.unrecognised.map(p => `"${p}" is neither a phase nor a known non-phase placement`),
736
- ];
942
+ // #2072: the one decider `--place` reads too.
943
+ const unsound = unsoundPlacement(placement);
737
944
  if (unsound.length > 0) {
738
945
  console.error(`plan-issues: ${values.spec}'s placement table is unsound, so no row can be placed from it:`);
739
946
  for (const u of unsound) console.error(` - ${u}`);