rungate 0.8.13 → 0.8.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
package/lib/spec-deps.ts CHANGED
@@ -20,9 +20,9 @@
20
20
  *
21
21
  * ## The phase sequence is the phases that EXIST, never N-1 arithmetic
22
22
  *
23
- * {@link dependencyPlan} sorts the phases that actually carry issues and
24
- * chains adjacent members of that list. A spec whose placement table skips a
25
- * number — Phase 0, 1, 3 with nothing in 2 — would otherwise leave Phase 3
23
+ * {@link dependencyPlan} sorts the phases that actually carry issues and hands
24
+ * that list to {@link chainAdjacentPhases}. A spec whose placement table skips
25
+ * a number — Phase 0, 1, 3 with nothing in 2 — would otherwise leave Phase 3
26
26
  * blocked by a phase that does not exist, which reads as *unblocked* and puts
27
27
  * the last phase in the Ready lane beside the first.
28
28
  *
@@ -45,6 +45,7 @@
45
45
  * `includeClosed` to derive them anyway; the default is to leave them out.
46
46
  */
47
47
  import { phaseOf } from "./board-mirror";
48
+ import { familyOf } from "./spec-placement";
48
49
 
49
50
  export interface DepIssue {
50
51
  readonly number: number;
@@ -164,6 +165,36 @@ export function degenerateReasons(r: {
164
165
  return out;
165
166
  }
166
167
 
168
+ /**
169
+ * The cross product of each phase with the one immediately before it in the
170
+ * list it is handed — the whole of the ordering rule, in one symbol.
171
+ *
172
+ * `phases` must be the phases that EXIST, ascending. This function does no
173
+ * arithmetic on the numbers: it pairs index `k` with index `k - 1`, so a
174
+ * placement table that skips Phase 2 chains 1 → 3 rather than leaving Phase 3
175
+ * blocked by a phase carrying nothing. Passing an unsorted list, or one
176
+ * containing a phase with no issues, is what a caller must not do.
177
+ *
178
+ * It lives here rather than inline in {@link dependencyPlan} because SC-2606
179
+ * is the criterion that this rule is *named*: a reader looking for where
180
+ * adjacency is decided has one symbol to open, and a mutation of it moves
181
+ * every edge the plan reports.
182
+ */
183
+ export function chainAdjacentPhases(
184
+ phases: readonly number[],
185
+ byPhase: ReadonlyMap<number, readonly DepIssue[]>,
186
+ ): DepEdge[] {
187
+ const edges: DepEdge[] = [];
188
+ for (let k = 1; k < phases.length; k++) {
189
+ for (const blocked of byPhase.get(phases[k]) ?? []) {
190
+ for (const blocker of byPhase.get(phases[k - 1]) ?? []) {
191
+ edges.push({ blocked: blocked.number, blocker: blocker.number });
192
+ }
193
+ }
194
+ }
195
+ return edges;
196
+ }
197
+
167
198
  /**
168
199
  * What the repository's `blocked by` edges should be, given the phases its
169
200
  * issues sit in.
@@ -183,6 +214,9 @@ export function dependencyPlan(
183
214
  const unphased: number[] = [];
184
215
  const byPhase = new Map<number, DepIssue[]>();
185
216
  for (const i of considered) {
217
+ // One reading of the title (#2057): a phase always has a family, so the
218
+ // "phase but no family" state the review of #2055 had to report is gone.
219
+ // `Release (Phase 3)` is not a phase milestone, to every reader.
186
220
  const p = phaseOf(i.milestone);
187
221
  if (p === null) {
188
222
  unphased.push(i.number);
@@ -200,16 +234,26 @@ export function dependencyPlan(
200
234
  truncated: issues.filter(i => i.blockedByTruncated === true).map(i => i.number),
201
235
  });
202
236
 
203
- // Adjacent members of the phases that EXIST. See the header: `p - 1` would
204
- // leave a phase after a gap blocked by nothing and reading as startable.
205
- const derived: DepEdge[] = [];
206
- for (let k = 1; k < phases.length; k++) {
207
- for (const blocked of byPhase.get(phases[k])!) {
208
- for (const blocker of byPhase.get(phases[k - 1])!) {
209
- derived.push({ blocked: blocked.number, blocker: blocker.number });
210
- }
237
+ // Adjacent members of the phases that EXIST, chained WITHIN each milestone
238
+ // family (#2024, SC-2617). See the header: `p - 1` would leave a phase after
239
+ // a gap blocked by nothing and reading as startable. And `Convergence
240
+ // Phase 1` follows `Convergence Phase 0`, never `Pipeline Phase 0`: a
241
+ // repository-wide plan bucketed by number alone chains one spec to another,
242
+ // which is how #1903's reading measured 129 of 154 and was withdrawn.
243
+ // `plan-deps` narrows to one family before calling, so it sees one bucket.
244
+ const byFamily = new Map<string, Map<number, DepIssue[]>>();
245
+ for (const [p, members] of byPhase) {
246
+ for (const i of members) {
247
+ const f = familyOf(i.milestone) as string;
248
+ const fam = byFamily.get(f) ?? new Map<number, DepIssue[]>();
249
+ fam.set(p, [...(fam.get(p) ?? []), i]);
250
+ byFamily.set(f, fam);
211
251
  }
212
252
  }
253
+ const derived: DepEdge[] = [];
254
+ for (const fam of byFamily.values()) {
255
+ derived.push(...chainAdjacentPhases([...fam.keys()].sort((a, b) => a - b), fam));
256
+ }
213
257
 
214
258
  const key = (e: DepEdge): string => `${e.blocked}<-${e.blocker}`;
215
259
  const derivedKeys = new Set(derived.map(key));
@@ -34,6 +34,7 @@
34
34
  * 7's opened-to-closed ratio. {@link uncoveredByMilestone} reports the input
35
35
  * to that decision and stops there.
36
36
  */
37
+ import { PHASE_TOKEN, readMilestoneTitle } from "./milestone-title";
37
38
  import { oneScMentionPattern } from "./sc-ids";
38
39
  import { parseCriteria } from "./spec-evidence";
39
40
 
@@ -57,7 +58,7 @@ export const NON_PHASE_PLACEMENTS = [
57
58
  ] as const;
58
59
 
59
60
  /** `Phase 0`, `Phase 11`. The capture is the number. */
60
- export const PHASE_VALUE = /^Phase (\d+)$/;
61
+ export const PHASE_VALUE = new RegExp(`^${PHASE_TOKEN}$`);
61
62
 
62
63
  /**
63
64
  * Which phase of `prefix`'s family this milestone title is, or `null`.
@@ -78,8 +79,9 @@ export const PHASE_VALUE = /^Phase (\d+)$/;
78
79
  * them a case is holding up: `.claude/rules/checks-must-be-able-to-fail.md`,
79
80
  * fourth shape.
80
81
  *
81
- * The prefix is escaped, so a family name containing regex punctuation is
82
- * matched literally rather than compiled.
82
+ * The family is compared as a string against `readMilestoneTitle`'s reading,
83
+ * never compiled into a pattern, so a family name containing regex
84
+ * punctuation (`C++`) means itself.
83
85
  *
84
86
  * Not to be confused with `phaseOf` in `lib/board-mirror.ts`, which reads a
85
87
  * phase number out of ANY title regardless of family. That one answers a
@@ -88,8 +90,29 @@ export const PHASE_VALUE = /^Phase (\d+)$/;
88
90
  * is derived.
89
91
  */
90
92
  export function phaseInFamily(title: string | null | undefined, prefix: string): number | null {
91
- const m = (title ?? "").match(new RegExp(String.raw`^${escapeRe(prefix)} Phase (\d+)\b`));
92
- return m ? Number(m[1]) : null;
93
+ // #2057: compared against the one reading, not interpolated into a second
94
+ // regex. An empty prefix is no family here: it is refused upstream
95
+ // (lib/live-issues.ts) and must not match every bare `Phase N` title.
96
+ const r = readMilestoneTitle(title);
97
+ return prefix !== "" && r !== null && r.family === prefix ? r.phase : null;
98
+ }
99
+
100
+ /**
101
+ * The family a phase milestone belongs to — `Pipeline` for `Pipeline Phase 6
102
+ * — …`, `""` for a bare `Phase N` title (a repository with no prefix has one
103
+ * family, the reading `familyRank` takes for a null prefix), or null when
104
+ * the title is neither shape (#2024). Null is not a family: a caller must
105
+ * not fold it into one, or every unreadable title chains to every other.
106
+ *
107
+ * The same grammar as {@link phaseInFamily}, read the other way: for every
108
+ * title this returns a NON-EMPTY family for, `phaseInFamily(title,
109
+ * familyOf(title))` is the title's phase. The unprefixed family `""` is the
110
+ * one exception — `phaseInFamily` takes a prefix and an empty one is refused
111
+ * upstream (`lib/live-issues.ts`), so it has no `""` reading to agree with. `test/plan-deps.test.ts` asserts that agreement, so the
112
+ * two cannot drift into a second decider of what a family is.
113
+ */
114
+ export function familyOf(title: string | null | undefined): string | null {
115
+ return readMilestoneTitle(title)?.family ?? null;
93
116
  }
94
117
 
95
118
  export interface PlacementRow {
@@ -141,11 +164,14 @@ export function parsePlacementRows(content: string): PlacementRow[] {
141
164
  return out;
142
165
  }
143
166
 
167
+ /** `## Phase N — title` to `#### …`: the heading a milestone is named from. */
168
+ const PHASE_HEADING = new RegExp(String.raw`^#{2,4} (${PHASE_TOKEN}(?:\s*[—–-]\s*(.*))?)\s*$`);
169
+
144
170
  /** Every `### Phase N — …` heading, in document order. */
145
171
  export function parsePhaseHeadings(content: string): PhaseHeading[] {
146
172
  const out: PhaseHeading[] = [];
147
173
  content.split("\n").forEach((line, i) => {
148
- const m = line.match(/^#{2,4} (Phase (\d+)(?:\s*[—–-]\s*(.*))?)\s*$/);
174
+ const m = line.match(PHASE_HEADING);
149
175
  if (!m) return;
150
176
  out.push({ number: Number(m[2]), title: (m[3] ?? "").trim(), heading: m[1].trim(), line: i + 1 });
151
177
  });
@@ -203,6 +229,130 @@ export function placementReading(content: string): PlacementReading {
203
229
  };
204
230
  }
205
231
 
232
+ /** What one spec's planning state is, across the whole tree — SC-2611. */
233
+ export type PlacementState = "PLANNED" | "UNPLANNED" | "NO_CRITERIA" | "UNREADABLE";
234
+
235
+ export interface SpecPlacement {
236
+ /** Repo-relative, as the sweep spells it. */
237
+ path: string;
238
+ state: PlacementState;
239
+ /** Why it is not PLANNED. Empty exactly when it is. */
240
+ reasons: string[];
241
+ /** How many criteria the spec states, and how many the table places. */
242
+ criteria: number;
243
+ placed: number;
244
+ /** The spec declares `board-scope: deferred` in its frontmatter — SC-2734. */
245
+ deferred: boolean;
246
+ }
247
+
248
+ /**
249
+ * Whether a spec holds itself back from the board — SC-2734.
250
+ *
251
+ * Read from the FRONTMATTER only: a body line spelling the same words is
252
+ * prose about the convention, not a declaration, and reading it would let a
253
+ * spec defer itself by quoting this rule.
254
+ */
255
+ export function declaresDeferred(content: string): boolean {
256
+ const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
257
+ if (m === null) return false;
258
+ return /^board-scope:[ \t]*(["']?)deferred\1[ \t]*\r?$/m.test(m[1]!);
259
+ }
260
+
261
+ export interface PlacementCoverage {
262
+ /** UNMEASURED FAILS. An empty list from a sweep that failed is not a clean one. */
263
+ reading: "MEASURED" | "UNMEASURED";
264
+ unmeasuredReasons: string[];
265
+ /** Every spec the sweep located, in its order. */
266
+ specs: SpecPlacement[];
267
+ /** The paths in each state, so a caller reports names rather than a count. */
268
+ planned: string[];
269
+ unplanned: string[];
270
+ noCriteria: string[];
271
+ }
272
+
273
+ /** THE one way out of {@link placementCoverage} without a reading. */
274
+ function unmeasuredCoverage(reasons: string[]): PlacementCoverage {
275
+ return { reading: "UNMEASURED", unmeasuredReasons: reasons, specs: [], planned: [], unplanned: [], noCriteria: [] };
276
+ }
277
+
278
+ /**
279
+ * Every spec in the tree, and whether its criteria are placed — SC-2611.
280
+ *
281
+ * **The gap this closes.** {@link placementReading} answers the question for
282
+ * ONE spec, and both of its callers are given a spec on the command line. So
283
+ * a spec with no `### Phase placement` table contributed nothing to any
284
+ * repository-wide view: it had no phases, so it raised no milestone, so it
285
+ * appeared in no lane. 1 of 26 specs had a table on 2026-10-29 and the other
286
+ * 25 were indistinguishable from specs with no work left — which is the
287
+ * flattering reading of the two, and the wrong one.
288
+ *
289
+ * **`NO_CRITERIA` is separate from `UNPLANNED` deliberately.** A spec that
290
+ * states nothing to place genuinely has no work in it; a spec that states
291
+ * twelve criteria and places none has twelve. Folding them together
292
+ * reproduces the defect one level up — the count would be honest and the
293
+ * reader still could not act on it.
294
+ *
295
+ * **One unreadable spec makes the whole reading UNMEASURED**, not a shorter
296
+ * list: a shorter list is exactly what a tree with fewer specs produces. The
297
+ * spec is still carried in `specs` as `UNREADABLE` so the reason names it.
298
+ *
299
+ * The enumeration is `listSpecs`, not a second directory walk. `specs/` is
300
+ * already swept in one place, and a second walk is a second decider for
301
+ * "which files are specs" that no behavioural test of either could separate
302
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
303
+ */
304
+ export function placementCoverage(
305
+ root: string,
306
+ listSpecs: (root: string) => { reading: "MEASURED" | "UNMEASURED"; unmeasuredReasons: string[]; paths: string[] },
307
+ readSpec: (root: string, path: string) => string,
308
+ ): PlacementCoverage {
309
+ const sweep = listSpecs(root);
310
+ if (sweep.reading === "UNMEASURED") {
311
+ return unmeasuredCoverage([
312
+ `the specs/ sweep could not be taken, so nothing below is a reading of this tree: ` +
313
+ sweep.unmeasuredReasons.join("; "),
314
+ ]);
315
+ }
316
+
317
+ const specs: SpecPlacement[] = [];
318
+ const reasons: string[] = [];
319
+ for (const path of sweep.paths) {
320
+ let content: string;
321
+ try {
322
+ content = readSpec(root, path);
323
+ } catch (e) {
324
+ specs.push({ path, state: "UNREADABLE", reasons: [(e as Error).message], criteria: 0, placed: 0, deferred: false });
325
+ reasons.push(`could not read ${path}: ${(e as Error).message}`);
326
+ continue;
327
+ }
328
+ const r = placementReading(content);
329
+ const placed = r.criteria.length - r.unplaced.length;
330
+ const state: PlacementState =
331
+ r.criteria.length === 0 ? "NO_CRITERIA" : r.reading === "MEASURED" ? "PLANNED" : "UNPLANNED";
332
+ specs.push({
333
+ path,
334
+ state,
335
+ reasons: state === "PLANNED" ? [] : r.unmeasuredReasons,
336
+ criteria: r.criteria.length,
337
+ placed,
338
+ deferred: declaresDeferred(content),
339
+ });
340
+ }
341
+
342
+ if (reasons.length > 0) {
343
+ // Carry the per-spec rows: the refusal has to be able to NAME the file.
344
+ return { ...unmeasuredCoverage(reasons), specs };
345
+ }
346
+ return {
347
+ reading: "MEASURED",
348
+ unmeasuredReasons: [],
349
+ specs,
350
+ planned: specs.filter(s => s.state === "PLANNED").map(s => s.path),
351
+ unplanned: specs.filter(s => s.state === "UNPLANNED").map(s => s.path),
352
+ noCriteria: specs.filter(s => s.state === "NO_CRITERIA").map(s => s.path),
353
+ };
354
+ }
355
+
206
356
  /** One criterion, and what the board says about it — item **B2**. */
207
357
  export interface CriterionCoverage {
208
358
  id: string;
@@ -338,12 +488,34 @@ export function milestoneBody(criteria: string[]): string {
338
488
  * A live milestone whose title carries no `Phase N` for this prefix is left
339
489
  * alone and reported by the caller, not deleted. `Convergence Machinery` is
340
490
  * the live instance: real, in use, and derived from nothing here.
491
+ *
492
+ * ## `renameFrom`: moving a whole family to a new name (#2124)
493
+ *
494
+ * Without it, renaming the family in config plans a CREATE per phase, and
495
+ * every issue stays in the old milestones, now unmanaged. With it, a phase
496
+ * that has no milestone in `prefix` takes the one `renameFrom` holds for that
497
+ * phase as its existing milestone. The action is then a rename that keeps
498
+ * the milestone number, so every issue keeps its lane. Only the table's
499
+ * phases are adopted; an old-family milestone for any other phase stays
500
+ * unmanaged.
501
+ *
502
+ * A phase both families hold is a `conflict`. Neither milestone is picked,
503
+ * because either pick strands the other's issues. The caller refuses.
341
504
  */
505
+ export interface FamilyConflict {
506
+ phase: number;
507
+ /** The milestone already in the family being written. */
508
+ current: LiveMilestone;
509
+ /** The milestone in the family being renamed from. */
510
+ previous: LiveMilestone;
511
+ }
512
+
342
513
  export function milestonePlan(
343
514
  content: string,
344
515
  live: LiveMilestone[],
345
516
  prefix: string,
346
- ): { actions: MilestoneAction[]; unmanaged: LiveMilestone[] } {
517
+ renameFrom?: string,
518
+ ): { actions: MilestoneAction[]; unmanaged: LiveMilestone[]; conflicts: FamilyConflict[] } {
347
519
  const headings = new Map(parsePhaseHeadings(content).map(h => [h.number, h]));
348
520
  const rows = parsePlacementRows(content);
349
521
  const byPhase = new Map<number, string[]>();
@@ -358,13 +530,31 @@ export function milestonePlan(
358
530
  const n = phaseOf(l.title);
359
531
  if (n !== null) liveByPhase.set(n, l);
360
532
  }
533
+ const previousByPhase = new Map<number, LiveMilestone>();
534
+ if (renameFrom !== undefined) {
535
+ for (const l of live) {
536
+ const n = phaseInFamily(l.title, renameFrom);
537
+ if (n !== null && byPhase.has(n)) previousByPhase.set(n, l);
538
+ }
539
+ }
540
+ const conflicts: FamilyConflict[] = [];
541
+ for (const [phase, previous] of previousByPhase) {
542
+ const current = liveByPhase.get(phase);
543
+ if (current) conflicts.push({ phase, current, previous });
544
+ }
545
+ // Adopted means USED as a phase's existing milestone. A conflicting phase
546
+ // keeps its current-family milestone, so its old one is in no action and
547
+ // must stay in `unmanaged` rather than vanish (review of #2126).
548
+ const adopted = new Set(
549
+ [...previousByPhase].filter(([phase]) => !liveByPhase.has(phase)).map(([, m]) => m.number),
550
+ );
361
551
 
362
552
  const actions = [...byPhase.keys()]
363
553
  .sort((a, b) => a - b)
364
554
  .map((phase): MilestoneAction => {
365
555
  const heading = headings.get(phase);
366
556
  const title = `${prefix} ${heading ? heading.heading : `Phase ${phase}`}`;
367
- const existing = liveByPhase.get(phase);
557
+ const existing = liveByPhase.get(phase) ?? previousByPhase.get(phase);
368
558
  const criteria = byPhase.get(phase) ?? [];
369
559
  if (!existing) return { title, phase, criteria, action: "create" };
370
560
  // Both halves of what `--write` would put there, so `unchanged` means
@@ -383,11 +573,11 @@ export function milestonePlan(
383
573
  };
384
574
  });
385
575
 
386
- return { actions, unmanaged: live.filter(l => phaseOf(l.title) === null) };
387
- }
388
-
389
- function escapeRe(s: string): string {
390
- return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
576
+ return {
577
+ actions,
578
+ unmanaged: live.filter(l => phaseOf(l.title) === null && !adopted.has(l.number)),
579
+ conflicts: conflicts.sort((a, b) => a.phase - b.phase),
580
+ };
391
581
  }
392
582
 
393
583
  /**
@@ -8,6 +8,14 @@
8
8
  * conformity.ts, spec-validators.ts). This module centralizes the contract
9
9
  * so doc-hygiene, scaffold, and gate enforcement share one source of truth.
10
10
  *
11
+ * #1692 and #1906 finished that for the two that DECIDE: `governsOf` is the
12
+ * one extractor and `isValidGoverns` the one predicate, and `HYGIENE-1` in
13
+ * `lib/conformity.ts` calls both. This module holds no frontmatter parser of
14
+ * its own, and `test/governs-folded-scalar.test.ts` asserts that rather than
15
+ * leaving it to this sentence. `scanner.ts` and `spec-validators.ts` still
16
+ * extract their own; they render text and compose a warning, and neither
17
+ * decides whether a spec is governed.
18
+ *
11
19
  * Issue: #24
12
20
  */
13
21
 
@@ -24,26 +32,77 @@ export interface SpecEntry {
24
32
  }
25
33
 
26
34
  /**
27
- * Parse frontmatter from a markdown file's content.
28
- * Returns key-value pairs from YAML-style frontmatter block.
35
+ * A YAML block-scalar header, which is what a line-based frontmatter reader
36
+ * captures when the value is folded onto the lines below it.
37
+ *
38
+ * `>` folds, `|` keeps newlines, either may carry a chomping indicator
39
+ * (`-`/`+`) and an explicit indentation digit, in either order, and either
40
+ * may be followed by a comment. The class is deliberately a touch wider than
41
+ * YAML — `>--` is not legal YAML and is not governs text either, and a
42
+ * detector narrower than the syntax it detects is the defect in #1692, not
43
+ * the fix for it.
44
+ *
45
+ * The comment is matched here rather than stripped beforehand, so a `#` in
46
+ * real governs text — "the # anchor parser" — is never cut: nothing is
47
+ * removed unless what precedes it is already a block header.
29
48
  */
30
- function parseFrontmatter(content: string): Record<string, string> | null {
31
- const match = content.match(/^---\n([\s\S]*?)\n---/);
32
- if (!match) return null;
33
- const fields: Record<string, string> = {};
34
- for (const line of match[1].split('\n')) {
35
- const kv = line.match(/^(\w[\w-]*):\s*(.+)$/);
36
- if (kv) fields[kv[1]] = kv[2].trim();
37
- }
38
- return fields;
49
+ const BLOCK_SCALAR_HEADER = /^[>|][0-9+-]{0,2}(\s+#.*)?$/;
50
+
51
+ /** The frontmatter block: everything between the opening and closing `---`. */
52
+ const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
53
+
54
+ /** A `governs:` line at column 0, and whatever follows it on that line. */
55
+ const GOVERNS_LINE = /^governs:[ \t]*(.*)$/m;
56
+
57
+ /**
58
+ * The inline text of a document's `governs:` field — the one extractor.
59
+ *
60
+ * Returns `undefined` when the document declares no `governs` at all, and
61
+ * the empty string when it declares one whose value is not on that line.
62
+ * Those are different facts and both callers need to tell them apart.
63
+ *
64
+ * Deliberately reads the inline text ONLY. Raised in review of #1906: the
65
+ * two callers used to extract `governs` with two different frontmatter
66
+ * parsers, and on a bare `governs:` with the text indented below,
67
+ * `lib/conformity.ts`'s flattened the continuation lines and joined them
68
+ * with `"; "` while `lib/spec-registry.ts`'s never set the key — so
69
+ * HYGIENE-1 called the spec governed and `getUngoverned` called the same
70
+ * spec ungoverned, in the same run. Unifying the predicate had not fixed
71
+ * that, because the disagreement was upstream of the predicate.
72
+ *
73
+ * A value on the lines below is therefore absent to both readers rather
74
+ * than present and different. That is the same decision #1692 made about
75
+ * the folded form, applied to the shape that has no indicator: `governs`
76
+ * is one line, and anything else is refused rather than guessed at.
77
+ */
78
+ export function governsOf(content: string): string | undefined {
79
+ const fm = FRONTMATTER.exec(content);
80
+ if (!fm) return undefined;
81
+ const line = GOVERNS_LINE.exec(fm[1]);
82
+ return line ? line[1].trim() : undefined;
39
83
  }
40
84
 
41
85
  /**
42
- * Check if a governs field value is valid (non-empty, not TODO).
86
+ * Check if a governs field value is valid (non-empty, not TODO, not a
87
+ * folded block whose text this reader never saw).
88
+ *
89
+ * #1692: `governs: >-` with the prose on the indented lines below parses to
90
+ * the two characters `">-"` in every line-based reader in this tree. That is
91
+ * non-empty and contains no `TODO`, so it used to pass here and in
92
+ * `HYGIENE-1` while `lib/scanner.ts` dropped it for being under six
93
+ * characters and rendered a blank routing row. A folded `governs` is
94
+ * REFUSED rather than supported: all specs state it on one line, and
95
+ * supporting it means a reader that knows how `>` and `|` join their lines,
96
+ * which nothing here needs.
97
+ *
98
+ * `lib/conformity.ts`'s HYGIENE-1 calls this, over a value `governsOf`
99
+ * extracted. One extractor and one predicate — two copies of either is what
100
+ * let the disagreement sit unnoticed.
43
101
  */
44
- function isValidGoverns(governs: string | undefined): governs is string {
102
+ export function isValidGoverns(governs: string | undefined): governs is string {
45
103
  if (!governs) return false;
46
104
  const trimmed = governs.trim();
105
+ if (BLOCK_SCALAR_HEADER.test(trimmed)) return false;
47
106
  return trimmed.length > 0 && !trimmed.includes('TODO');
48
107
  }
49
108
 
@@ -73,13 +132,13 @@ function scanSpecDir(dir: string, prefix: string = ''): { governed: SpecEntry[];
73
132
 
74
133
  const filePath = join(dir, entry.name);
75
134
  const content = readFileSync(filePath, 'utf-8');
76
- const fm = parseFrontmatter(content);
135
+ const governs = governsOf(content); // #1906 — the one extractor
77
136
  const relFile = prefix ? `${prefix}/${entry.name}` : entry.name;
78
137
 
79
- if (fm && isValidGoverns(fm.governs)) {
138
+ if (isValidGoverns(governs)) {
80
139
  governed.push({
81
140
  file: relFile,
82
- governs: fm.governs,
141
+ governs,
83
142
  path: filePath,
84
143
  });
85
144
  } else {