rungate 0.8.8 → 0.8.10

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 (44) hide show
  1. package/gates/.gate-salt +1 -1
  2. package/hooks/StaleTTLCleanup.hook.ts +13 -5
  3. package/hooks/VerifyPhaseLock.hook.ts +8 -0
  4. package/hooks/lib/findWorkflow.ts +19 -3
  5. package/lib/active-workflow.ts +57 -0
  6. package/lib/ai-review-rounds.ts +102 -9
  7. package/lib/ai-review-threads.ts +71 -3
  8. package/lib/board-mirror.ts +438 -0
  9. package/lib/cli-commands.ts +133 -0
  10. package/lib/config-readers.ts +34 -0
  11. package/lib/crc-reading.ts +655 -0
  12. package/lib/criterion-issue-census.ts +325 -0
  13. package/lib/filing-plan.ts +381 -0
  14. package/lib/generators/agents-md.ts +15 -11
  15. package/lib/git-isolation.ts +32 -0
  16. package/lib/github.ts +66 -0
  17. package/lib/issue-decomposition.ts +523 -0
  18. package/lib/issue-filing-gate.ts +304 -19
  19. package/lib/issue-repair.ts +225 -0
  20. package/lib/live-issues.ts +442 -0
  21. package/lib/project-state-shape.ts +30 -0
  22. package/lib/sc-ids.ts +31 -1
  23. package/lib/scaffold/ai-review-step.ts +222 -48
  24. package/lib/scaffold/owned-files.ts +60 -2
  25. package/lib/scaffold/steps.ts +130 -4
  26. package/lib/spec-deps.ts +257 -0
  27. package/lib/spec-evidence.ts +479 -0
  28. package/lib/spec-placement.ts +430 -0
  29. package/lib/spec-template.ts +206 -0
  30. package/lib/stage-ladder.ts +628 -0
  31. package/lib/worktree-cleanup.ts +438 -3
  32. package/package.json +12 -4
  33. package/scripts/ai-review-threads.ts +10 -1
  34. package/scripts/audit-spec-evidence.ts +246 -0
  35. package/scripts/audit-specs.ts +27 -0
  36. package/scripts/board-conformance.ts +765 -0
  37. package/scripts/board-mirror.ts +344 -0
  38. package/scripts/board-snapshot.ts +459 -0
  39. package/scripts/create-spec.ts +8 -34
  40. package/scripts/criterion-inventory.ts +649 -0
  41. package/scripts/extract-constraints.ts +108 -9
  42. package/scripts/plan-deps.ts +378 -0
  43. package/scripts/plan-issues.ts +701 -0
  44. package/scripts/plan-spec.ts +371 -0
@@ -0,0 +1,438 @@
1
+ /**
2
+ * What a board COLUMN may say about an issue, and where that sentence is
3
+ * allowed to come from.
4
+ *
5
+ * ## The field is a mirror. The issue body is the source.
6
+ *
7
+ * A Projects v2 custom field is invisible to `gh`: `gh issue list --json
8
+ * projectItems` returns Status and nothing else, measured on #1592, which had
9
+ * two custom fields set at the time. Agents read the tracker through `gh`, so
10
+ * nothing an agent must ACT on can live in a project field — that is step 3 of
11
+ * `docs/adr/ADR-003-spec-to-tracker-mapping.md` and it has not changed.
12
+ *
13
+ * What a field CAN do is be looked at. Jason asked to open the board and see,
14
+ * per issue, the milestone it sits in and the criteria it serves, without
15
+ * opening anything. The milestone is already a built-in field. The criteria
16
+ * are in the issue body, and a board does not render bodies.
17
+ *
18
+ * So: this module derives the column from the body and never the other way
19
+ * round. `mirrorText` is a pure function of the issue's own text. If the field
20
+ * and the body ever disagree, the body is right and the field is stale, and
21
+ * the repair is to re-run the command — never to edit the column.
22
+ *
23
+ * ## One decider, which already existed
24
+ *
25
+ * "Does this issue name this criterion" is answered by `oneScMentionPattern`
26
+ * against the title and the body, which is exactly what
27
+ * `scripts/criterion-inventory.ts` has always asked. This module calls it
28
+ * rather than spelling the question again: two deciders that agree are
29
+ * behaviourally one, and no test can tell which of them is dead
30
+ * (`.claude/rules/checks-must-be-able-to-fail.md`). A duplicate of this very
31
+ * matcher was built and removed earlier in #1647, so the trap is not
32
+ * hypothetical here.
33
+ */
34
+ import { readdirSync, readFileSync } from "fs";
35
+ import { join, relative, sep } from "path";
36
+ import { idBoundedPattern, oneScMentionPattern } from "./sc-ids";
37
+ import { parseCriteria } from "./spec-evidence";
38
+
39
+ /** One spec, and the criterion ids it states. */
40
+ export interface SpecCriteria {
41
+ /** Repo-relative, with `/` separators, so a reading is comparable across machines. */
42
+ readonly path: string;
43
+ readonly ids: readonly string[];
44
+ }
45
+
46
+ /** What `specCriteriaIn` found, including what it could not resolve. */
47
+ export interface SpecSweep {
48
+ readonly reading: "MEASURED" | "UNMEASURED";
49
+ readonly specs: readonly SpecCriteria[];
50
+ /** The union, in (spec path, then spec) order. Deterministic across runs. */
51
+ readonly ids: readonly string[];
52
+ /** An id two specs both state — reported, never silently merged. */
53
+ readonly collisions: readonly { readonly id: string; readonly specs: readonly string[] }[];
54
+ readonly unmeasuredReasons: readonly string[];
55
+ }
56
+
57
+ /**
58
+ * The one spec whose ids are illustrative rather than stated.
59
+ *
60
+ * `specs/SPEC-TEMPLATE.md` is the frame a new spec is copied from, and its
61
+ * criteria read `- [ ] SC-1: [first criterion]`. Those ids are the lowest and
62
+ * most collidable in the whole namespace, so including them credits any issue
63
+ * mentioning `SC-1` to a criterion nobody ever wrote.
64
+ *
65
+ * It is named rather than detected. A heuristic — "skip drafts", "skip
66
+ * `testable: false`" — would also drop `DA-COMPLIANCE-SPEC.md`, which states
67
+ * real criteria, and blanking a real cell is the exact failure SC-2610 is
68
+ * about. `test/board-mirror.test.ts` asserts the file still exists, so this
69
+ * cannot rot into an exclusion pointing at nothing.
70
+ */
71
+ export const NOT_A_SPEC = ["specs/SPEC-TEMPLATE.md"] as const;
72
+
73
+ /**
74
+ * Every criterion id in `<root>/specs`, from every spec, including nested ones.
75
+ *
76
+ * **Why this is not a `--spec` argument.** The column answers "which criteria
77
+ * does this issue serve", and an issue does not know which spec the person at
78
+ * the keyboard happened to name. Filtering the id set to one spec means every
79
+ * issue serving any of the other 25 specs' criteria renders as an EMPTY cell —
80
+ * and a blank cell reads as *not yet filled in*, *the tool could not tell* and
81
+ * *deliberately none* at once. 28 cells on the live board were blank for this
82
+ * reason on 2026-10-29, which is the measurement behind SC-2610.
83
+ *
84
+ * A directory that exists and yields no criteria at all is UNMEASURED rather
85
+ * than an empty set: a tree with no specs and a tree whose specs could not be
86
+ * parsed produce the same empty list, and only one of them is a board in good
87
+ * order (*Silent Default Substitution*, `.claude/rules/config-access.md`).
88
+ */
89
+ /**
90
+ * The criterion ids ONE spec states, de-duplicated.
91
+ *
92
+ * `parseCriteria` matches every `- [ ] ID:` line independently and does not
93
+ * dedupe, so a spec stating an id twice yields it twice. Downstream that is
94
+ * a cell reading `SC-10 SC-10`, or — once the ids are pooled across specs —
95
+ * a criterion that looks ambiguous because it collided with itself.
96
+ *
97
+ * Exported and used by BOTH readers. The sweep was fixed first and the
98
+ * `--spec` path was left parsing for itself, so the two paths of one script
99
+ * disagreed about the very case the fix was written for: two deciders, and
100
+ * no behavioural test of either one can see the other going wrong. Both
101
+ * findings came from the AI review of #1679, one round apart.
102
+ */
103
+ export function criterionIdsIn(specText: string): string[] {
104
+ return [...new Set(parseCriteria(specText).map(c => c.id))];
105
+ }
106
+
107
+ /**
108
+ * Directory entries whose real parent cannot be established.
109
+ *
110
+ * Its own function so a case can hand it an entry with no `parentPath` —
111
+ * `readdirSync` cannot be asked to omit the field, so the refusal would
112
+ * otherwise be unreachable from a test and would read exactly like a
113
+ * refusal that works.
114
+ */
115
+ export function unlocatableEntries<T extends { name: string; parentPath?: string }>(
116
+ entries: readonly T[],
117
+ ): T[] {
118
+ return entries.filter(e => typeof e.parentPath !== "string" || e.parentPath === "");
119
+ }
120
+
121
+ /** The shape `specCriteriaIn` needs from a directory entry, and nothing more. */
122
+ export interface SpecDirEntry {
123
+ name: string;
124
+ parentPath?: string;
125
+ isFile(): boolean;
126
+ }
127
+
128
+ /**
129
+ * How the sweep lists `specs/`. A parameter, not a hardcoded call, because
130
+ * `readdirSync` on a runtime that HAS `parentPath` can never produce an entry
131
+ * without one — so with the call inlined the refusal below is unreachable from
132
+ * any test, and an unreachable refusal is indistinguishable from a working one
133
+ * (`.claude/rules/checks-must-be-able-to-fail.md`). Testing
134
+ * `unlocatableEntries` alone does not close that: the predicate is not the
135
+ * `SpecSweep` the refusal assembles, and a wrong field or a broken message in
136
+ * that object would go unobserved. Found by the AI review of #1679.
137
+ */
138
+ export type SpecDirReader = (dir: string) => readonly SpecDirEntry[];
139
+
140
+ export const readSpecDir: SpecDirReader = dir =>
141
+ readdirSync(dir, { recursive: true, withFileTypes: true });
142
+
143
+ /**
144
+ * THE one way out of `specCriteriaIn` without a reading.
145
+ *
146
+ * A refusal must carry nothing read. A populated `ids` beside
147
+ * `reading: "UNMEASURED"` is the partial result the refusal exists to
148
+ * prevent, handed back quietly for any caller that checks the array before
149
+ * it checks the reading.
150
+ *
151
+ * It is a function rather than three careful `return`s because three
152
+ * careful `return`s is what this function had, and the third one leaked.
153
+ * Each of the first two was written, reviewed and fixed on its own; the one
154
+ * nobody was looking at kept its partial `specs` and `ids` — and no
155
+ * behavioural test of either fixed branch could see it, because they are
156
+ * separate branches answering the same question (*two deciders that agree*,
157
+ * at N=3, `.claude/rules/checks-must-be-able-to-fail.md`). So the property
158
+ * is asserted across the SITES: `test/board-mirror.test.ts` requires the
159
+ * `UNMEASURED` literal to appear exactly once in this file. A fourth branch
160
+ * cannot leak, because a fourth branch cannot spell the reading itself.
161
+ */
162
+ function unmeasuredSweep(reasons: string[]): SpecSweep {
163
+ return { reading: "UNMEASURED", specs: [], ids: [], collisions: [], unmeasuredReasons: reasons };
164
+ }
165
+
166
+ export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDir): SpecSweep {
167
+ const dir = join(root, "specs");
168
+ let files: string[];
169
+ try {
170
+ const entries = readDir(dir).filter(e => e.isFile() && e.name.endsWith(".md"));
171
+ // `parentPath` is the ONLY field that can be trusted to name a nested
172
+ // entry's real parent. There is no fallback: `Dirent.path` under a
173
+ // recursive readdir historically resolved to the top-level directory
174
+ // rather than the entry's parent — that bug is why `parentPath` exists —
175
+ // so on a runtime old enough to lack `parentPath`, `path` carries the
176
+ // wrong value rather than a usable one. `?? dir` and `?? e.path` are the
177
+ // same guess wearing different names, and both FLATTEN a nested spec
178
+ // silently. Both were written here and both were caught by the AI review
179
+ // of #1679, one round apart.
180
+ //
181
+ // So: refuse. A sweep that cannot locate a file it can see is UNMEASURED,
182
+ // not a sweep with fewer specs in it.
183
+ const unlocatable = unlocatableEntries(entries);
184
+ if (unlocatable.length > 0) {
185
+ return unmeasuredSweep([
186
+ `this runtime does not report Dirent.parentPath, so ${unlocatable.length} spec file(s) ` +
187
+ `under ${dir} cannot be located — a nested spec would be read as a top-level one. ` +
188
+ `Nothing was read: ${unlocatable.map(e => e.name).sort().join(", ")}`,
189
+ ]);
190
+ }
191
+ // `as string` rather than a second `typeof e.parentPath === "string"`:
192
+ // the refusal above already decided that question for every entry here,
193
+ // and a second decider answering it again is one no behavioural test can
194
+ // tell apart from the first.
195
+ files = entries
196
+ .map(e => relative(root, join(e.parentPath as string, e.name)).split(sep).join("/"))
197
+ .filter(p => !(NOT_A_SPEC as readonly string[]).includes(p))
198
+ .sort();
199
+ } catch (e) {
200
+ return unmeasuredSweep([`could not read ${dir}: ${(e as Error).message}`]);
201
+ }
202
+
203
+ const specs: SpecCriteria[] = [];
204
+ const reasons: string[] = [];
205
+ const seen = new Map<string, string[]>();
206
+ for (const path of files) {
207
+ let ids: string[];
208
+ try {
209
+ // De-duplicated WITHIN the spec. `parseCriteria` matches every
210
+ // `- [ ] ID:` line independently and does not dedupe, so one spec
211
+ // stating an id twice — a pasted-twice criterion — would push its own
212
+ // path onto `seen` twice and read downstream as a cross-spec
213
+ // collision: the id dropped as ambiguous, and a note saying it is
214
+ // "stated by specs/A.md and specs/A.md". An unambiguous criterion
215
+ // misreported as ambiguous, with a nonsensical reason. Found by the
216
+ // AI review of #1679; zero specs state a duplicate today, so nothing
217
+ // observable changes and the guard is for the case that arrives.
218
+ ids = criterionIdsIn(readFileSync(join(root, path), "utf-8"));
219
+ } catch (e) {
220
+ // One unreadable spec does not make a SHORTER id list — it makes the
221
+ // whole sweep unmeasured, because a shorter list is exactly what a
222
+ // repository with fewer criteria produces.
223
+ reasons.push(`could not read ${path}: ${(e as Error).message}`);
224
+ continue;
225
+ }
226
+ specs.push({ path, ids });
227
+ for (const id of ids) seen.set(id, [...(seen.get(id) ?? []), path]);
228
+ }
229
+
230
+ // An id two specs both state is AMBIGUOUS, and the column has one cell per
231
+ // issue with no room to say which spec was meant. #312 mentions `SC-A1`
232
+ // meaning another repository's criterion; three specs here state `SC-A1`,
233
+ // so writing it attributes the issue to a criterion at random. Dropped from
234
+ // the id set and reported — the issue keeps whatever unambiguous ids it
235
+ // also names, so this narrows a cell rather than blanking it.
236
+ const ids = [...seen.keys()].filter(id => (seen.get(id) as string[]).length === 1);
237
+ const collisions = [...seen.entries()]
238
+ .filter(([, where]) => where.length > 1)
239
+ .map(([id, where]) => ({ id, specs: where }));
240
+
241
+ // Two different ways to end up with no usable id, and they need different
242
+ // sentences. The caller refuses on UNMEASURED before it prints the
243
+ // collision notes, so if the empty set came from ambiguity the reason line
244
+ // is the ONLY place that can say so — and "no spec states a criterion" is
245
+ // then actively false. Raised by the AI review of #1679.
246
+ if (reasons.length === 0 && ids.length === 0) {
247
+ reasons.push(
248
+ seen.size === 0
249
+ ? `no spec under ${dir} states a criterion, so no cell could be filled`
250
+ : `every criterion under ${dir} is stated by more than one spec, so none can be ` +
251
+ `attributed to a single one: ${collisions.map(c => `${c.id} (${c.specs.join(", ")})`).join("; ")}`,
252
+ );
253
+ }
254
+ // The third branch, and the one that leaked. A spec `readdirSync` listed
255
+ // and `readFileSync` could not open — a permission bit, a race with a
256
+ // delete — pushed a reason and carried on, so the sweep returned
257
+ // UNMEASURED with the OTHER specs' ids still in it. The caller refuses on
258
+ // the reading before it touches the array, so nothing was wrong today;
259
+ // what was wrong is that the exported contract contradicted itself and the
260
+ // next caller to read `ids` first would get a short list that looks whole.
261
+ // Raised by the AI review of #1679, one round after the two branches above
262
+ // were each fixed on their own.
263
+ if (reasons.length > 0) return unmeasuredSweep(reasons);
264
+ return { reading: "MEASURED", specs, ids, collisions, unmeasuredReasons: [] };
265
+ }
266
+
267
+ /** What the board is told about one issue. */
268
+ export interface MirrorRow {
269
+ readonly number: number;
270
+ /** Criterion ids the issue's own text names, in spec order. */
271
+ readonly criteria: readonly string[];
272
+ /** Exactly what goes in the text field. */
273
+ readonly text: string;
274
+ }
275
+
276
+ /** The text used when an issue names no criterion at all. */
277
+ export const NAMES_NONE = "";
278
+
279
+ /**
280
+ * Every id, never a summary.
281
+ *
282
+ * The first version of this capped the cell at six ids and appended
283
+ * `+N more`, on the stated grounds that a board cell is narrow and that the
284
+ * widest issue in this repository names six, so the overflow branch would be
285
+ * reached by nothing. **The first run falsified both halves in one line:**
286
+ * #1437 names nine, and the cell it produced was
287
+ * `CRC-E1 CRC-E2 CRC-E3 CRC-E4 CRC-E5 CRC-E6 +3 more`.
288
+ *
289
+ * Which is the worse of the two failures. The column exists so Jason can see
290
+ * which criteria an issue serves without opening it; a cell that silently
291
+ * drops three of them answers the question wrongly rather than partially, and
292
+ * it does so on exactly the issue with the most to say. A visually clipped
293
+ * cell is still the whole value — the table widens, the tooltip shows it, and
294
+ * the JSON carries it. So there is no cap, and the bound that was never
295
+ * measured is gone rather than raised.
296
+ */
297
+ export function mirrorText(criteria: readonly string[]): string {
298
+ if (criteria.length === 0) return NAMES_NONE;
299
+ return criteria.join(" ");
300
+ }
301
+
302
+ /**
303
+ * An issue STATING a criterion of its own, rather than naming one it serves.
304
+ *
305
+ * `- [ ] SC-1 — A test fails when a hook name exists in both trees` is #713
306
+ * writing its own acceptance criteria in the shape a spec uses. It is not a
307
+ * reference to `specs/bootstrap-data-flow/success-criteria.md`'s `SC-1`, and
308
+ * the two are indistinguishable to a bare mention test. Measured 2026-10-30:
309
+ * reading every spec made #713's cell read `SC-1 SC-2 SC-3 SC-4 SC-5 SC-6`,
310
+ * six criteria it has nothing to do with.
311
+ *
312
+ * A wrong cell is worse than the blank one SC-2609 is about. A blank says
313
+ * "nothing known"; a populated cell is read as a fact.
314
+ *
315
+ * The checkbox is the whole signal, and it is the right one: ADR-003 step 3
316
+ * says an issue names what it serves under a CRITERIA heading as plain text.
317
+ * Nothing in this repository's issue template writes a served criterion as a
318
+ * task checkbox.
319
+ */
320
+ export function declaresOwnCriterion(text: string, id: string): boolean {
321
+ return idBoundedPattern("^[ \\t]*[-*][ \\t]*\\[[ xX]\\][ \\t]*", id, "m").test(text);
322
+ }
323
+
324
+ /**
325
+ * Which of `criterionIds` this issue's text names.
326
+ *
327
+ * Order follows `criterionIds`, so the column reads in spec order rather than
328
+ * in whatever order the issue's prose happened to mention them. Two issues
329
+ * serving the same pair then render identically, which is what makes the
330
+ * column scannable down a group.
331
+ */
332
+ export function criteriaNamedBy(
333
+ issue: { readonly title: string; readonly body?: string | null },
334
+ criterionIds: readonly string[],
335
+ ): string[] {
336
+ const text = `${issue.title}\n${issue.body ?? ""}`;
337
+ return criterionIds.filter(
338
+ id => oneScMentionPattern(id).test(text) && !declaresOwnCriterion(text, id),
339
+ );
340
+ }
341
+
342
+ export function mirrorRows(
343
+ issues: readonly { readonly number: number; readonly title: string; readonly body?: string | null }[],
344
+ criterionIds: readonly string[],
345
+ ): MirrorRow[] {
346
+ return issues.map(i => {
347
+ const criteria = criteriaNamedBy(i, criterionIds);
348
+ return { number: i.number, criteria, text: mirrorText(criteria) };
349
+ });
350
+ }
351
+
352
+ /**
353
+ * An item is READY when nothing open is blocking it.
354
+ *
355
+ * **This cannot be a saved view filter, and the reason is measured.**
356
+ * GitHub's `no:blocked-by` and `has:blocked-by` match on whether a dependency
357
+ * LINK exists, not on whether the blocker is still open. Taken 2026-10-28
358
+ * against `LucasDesenvGit/financas-local`, the only public repository with
359
+ * dependency edges I could find to use as a positive control: its issues #78,
360
+ * #92, #191 and #210 are open with `issueDependenciesSummary { blockedBy: 0,
361
+ * totalBlockedBy: 1 }` — one dependency, already closed — and all four match
362
+ * `has:blocked-by` while none matches `no:blocked-by`.
363
+ *
364
+ * So a Ready lane defined as `is:open no:blocked-by` would drop an issue the
365
+ * moment anything was ever linked to it and never give it back, including
366
+ * after the blocker shipped. The open count has to be read and the lane
367
+ * written. `blockedBy` is the OPEN count and `totalBlockedBy` the lifetime
368
+ * one; they are separate fields and only the first one answers this.
369
+ *
370
+ * `issueDependenciesSummary` is GraphQL-only — `gh issue view --json` exposes
371
+ * `blockedBy` and `blocking` but not the summary.
372
+ */
373
+ export function isUnblocked(summary: { readonly blockedBy: number }, assignees: number): boolean {
374
+ return summary.blockedBy === 0 && assignees === 0;
375
+ }
376
+
377
+ /** The phase number in a milestone title, or null for a milestone that is not a phase. */
378
+ export function phaseOf(milestoneTitle: string | null | undefined): number | null {
379
+ const m = /\bPhase (\d+)\b/.exec(milestoneTitle ?? "");
380
+ return m ? Number(m[1]) : null;
381
+ }
382
+
383
+ /**
384
+ * The lowest phase number that still has open work, or null if none does.
385
+ *
386
+ * This is the whole ordering, and it is derived rather than declared: the
387
+ * spec's *Phase placement* table decides which phase a criterion is in,
388
+ * `rungate plan-spec` turns the phases into milestones, and a milestone is
389
+ * single-valued so an issue sits in exactly one. Nothing here is a number
390
+ * anybody types.
391
+ */
392
+ export function openFrontier(
393
+ items: readonly { readonly state: string; readonly phase: number | null }[],
394
+ ): number | null {
395
+ const open = items.filter(i => i.state === "OPEN" && i.phase !== null).map(i => i.phase as number);
396
+ return open.length === 0 ? null : Math.min(...open);
397
+ }
398
+
399
+ /**
400
+ * READY means *pick this up next*, which is narrower than *nothing is
401
+ * blocking it*.
402
+ *
403
+ * The first run of this made 36 of 46 open issues Ready, because the
404
+ * repository has almost no dependency edges and an issue with no blockers is
405
+ * trivially unblocked. A lane holding 36 items is the backlog with a
406
+ * different name, and it answers the question Jason actually asked — *what
407
+ * can I pick up* — with "anything", which is the same as not answering.
408
+ *
409
+ * So readiness carries the phase order too: an issue is Ready when it is
410
+ * unblocked, unassigned, AND sits in the earliest phase that still has open
411
+ * work. Later phases are not ready because the spec says they come later,
412
+ * and that ordering is data — the placement table — not a judgement made
413
+ * here.
414
+ *
415
+ * An issue with no phase milestone is never Ready. That is not a
416
+ * demotion: 19 of the 46 open issues are reviewer findings that serve no
417
+ * criterion and belong to no phase (ADR-003), and putting them in the lane
418
+ * that means "this is the next convergence work" would make the lane lie.
419
+ */
420
+ export function isReady(
421
+ item: {
422
+ readonly state: string;
423
+ readonly phase: number | null;
424
+ readonly blockedByOpen: number;
425
+ readonly assignees: number;
426
+ },
427
+ frontier: number | null,
428
+ ): boolean {
429
+ if (item.state !== "OPEN") return false;
430
+ // No separate `item.phase === null` guard. It was here, and the mutation
431
+ // battery removed it with every case still green: `null !== frontier` is
432
+ // already false for any non-null frontier, so the two lines were one
433
+ // decider spelled twice, and no behavioural test could ever tell which of
434
+ // them was live (`.claude/rules/checks-must-be-able-to-fail.md`).
435
+ if (frontier === null) return false;
436
+ if (item.phase !== frontier) return false;
437
+ return isUnblocked({ blockedBy: item.blockedByOpen }, item.assignees);
438
+ }
@@ -122,6 +122,139 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
122
122
  summary: "Report which success criteria are matched, unmatched or uncovered",
123
123
  usage: "rungate audit-specs",
124
124
  },
125
+ // Registered because `create-spec` SHIPS and stamps every generated spec
126
+ // with `evidence: required`, and this is the only thing that enforces that
127
+ // key (#1639). Without the entry the published package emitted a document
128
+ // declaring itself gated and carried no gate — half of a generator/checker
129
+ // pair, which is the shape the `create-spec` note above records this
130
+ // registry already having been built for once.
131
+ //
132
+ // Raised by the required reviewer on EVERY round of #1639, rounds 1 through
133
+ // 5, and answered on none of them: its finding anchors `package.json`,
134
+ // which is not in that pull request's diff, so `ai-review-threads` could
135
+ // not create the thread (422, "path could not be resolved") and the job
136
+ // failed with a message naming the posting failure rather than the finding.
137
+ // A finding on a file outside the diff is invisible to anyone reading
138
+ // review threads. Read the ledger.
139
+ //
140
+ // `projectRootFlag` is load-bearing: the script defaults its root to its
141
+ // own location, so without the flag `bunx rungate audit-spec-evidence`
142
+ // would walk `node_modules/rungate/specs/` and report RUNGATE's compliance
143
+ // as the consumer's — a pass about a tree it never opened.
144
+ "audit-spec-evidence": {
145
+ script: "scripts/audit-spec-evidence.ts",
146
+ summary: "Refuse a ticked criterion that does not name what proved it",
147
+ usage: "rungate audit-spec-evidence [--json] [--record-fingerprints]",
148
+ projectRootFlag: true,
149
+ },
150
+ // Step 2 of `docs/adr/ADR-003-spec-to-tracker-mapping.md`, which was eight
151
+ // `gh` commands typed by hand before this existed (#1647). Registered
152
+ // rather than left a script because the whole point is that a CONSUMER can
153
+ // turn their own spec into their own milestones — the derivation is not
154
+ // about this repository's phases, and a script in `scripts/` reaches
155
+ // nobody who installed the package.
156
+ //
157
+ // `projectRootFlag` is load-bearing for the same reason it is on
158
+ // `audit-spec-evidence`: the spec path is resolved against the root, so
159
+ // without the flag `bunx rungate plan-spec specs/X.md` would read
160
+ // `node_modules/rungate/specs/X.md` and derive RUNGATE's phases into the
161
+ // consumer's repository.
162
+ "plan-spec": {
163
+ script: "scripts/plan-spec.ts",
164
+ summary: "Derive a repository's milestones from a spec's Phase placement table",
165
+ usage: "rungate plan-spec <spec.md> --repo <owner/name> --prefix <name> [--write] [--json]",
166
+ projectRootFlag: true,
167
+ },
168
+ // Registered after two hours of building a weaker version of it beside it
169
+ // (#1647). This script has produced the full criterion-to-issue-to-PR-to-
170
+ // test matrix since it was written, and was reachable from nothing: not a
171
+ // command, not in `files[]`, not in CI, named in no always-loaded document.
172
+ // `rungate plan-spec`'s coverage column was written in ignorance of it and
173
+ // duplicated its matcher. An unregistered tool is indistinguishable from an
174
+ // absent one, which is the whole of #1309 and is why that registry exists.
175
+ //
176
+ // `projectRootFlag`, and the script REFUSES a `--project-root` without a
177
+ // `--spec`: its default spec is rungate's own convergence document.
178
+ "criterion-inventory": {
179
+ script: "scripts/criterion-inventory.ts",
180
+ summary: "Trace every criterion to the tests, issues and pull requests that name it",
181
+ usage: "rungate criterion-inventory --snapshot <dir> --spec <path> [--json] [--markdown]",
182
+ projectRootFlag: true,
183
+ },
184
+ // Step 3 of ADR-003 made VISIBLE (#1647). The issue body declares which
185
+ // criteria the work serves and the board renders fields, not bodies, so the
186
+ // declaration was invisible without opening every issue in turn. This
187
+ // derives a text column from the bodies and writes it.
188
+ //
189
+ // The direction is load-bearing and stated in `lib/board-mirror.ts`: the
190
+ // body is the source, the column is a mirror. A project custom field cannot
191
+ // be read through `gh` at all, so nothing an agent acts on may live there.
192
+ //
193
+ // `projectRootFlag` for the same reason as its neighbours — the spec path
194
+ // resolves against the root, and without it a consumer would mirror
195
+ // RUNGATE's criteria onto their own board.
196
+ // `--spec` is BRACKETED, and that is load-bearing rather than cosmetic.
197
+ // Spelling it as required tells a reader to narrow the sweep to one spec,
198
+ // which blanks the cell of every issue serving any other spec — SC-2610,
199
+ // the defect the flag was made optional to fix. This registry is a second
200
+ // place that documents the same contract as `USAGE` in
201
+ // `scripts/board-mirror.ts`, so `test/board-mirror.test.ts` asserts the two
202
+ // agree: the AI review of #1679 raised this stale string on ten rounds
203
+ // running and each round found it unswept, because a fix applied to the
204
+ // script never reached the sibling that describes it.
205
+ "board-mirror": {
206
+ script: "scripts/board-mirror.ts",
207
+ summary: "Show every spec's criteria, and what is ready to pick up, on the project board",
208
+ usage:
209
+ "rungate board-mirror --project <node-id> [--spec <spec.md>] [--field <name>] [--write] [--ready] [--json]",
210
+ projectRootFlag: true,
211
+ },
212
+ // Item B5 of the ladder in `project-state.json`, and the plan's terminal
213
+ // condition: the overall goal's verify command is this one with no
214
+ // arguments. Five of Stage B's six items are each one of its readings, so
215
+ // it is also the command most likely to be made vacuous — a skeleton
216
+ // exiting 0 would turn the whole plan green at once.
217
+ //
218
+ // It therefore refuses in three states rather than two. `unmeasured` is
219
+ // not `met`: with no `--snapshot` nothing has been read, and a board
220
+ // nobody could read has not passed. `test/board-conformance.test.ts`
221
+ // proves each refusal against a mutant with the exit constant zeroed.
222
+ //
223
+ // No `projectRootFlag`: it takes an explicit `--snapshot` path and reads
224
+ // nothing relative to a root, so adding the flag would hand the script an
225
+ // argument it would read as a positional.
226
+ "board-conformance": {
227
+ script: "scripts/board-conformance.ts",
228
+ summary: "Does the board say what the spec says — every reading, and whether any is short of target",
229
+ usage: "rungate board-conformance [--reading <name>] [--snapshot <path>] [--list-readings]",
230
+ },
231
+ // Step 4 of ADR-003, in reverse. The issue template's own footer says a
232
+ // GitHub issue form cannot set a milestone or a dependency; this does both
233
+ // from a plan somebody approved. `--repair` fixes issues that already
234
+ // exist.
235
+ //
236
+ // `projectRootFlag` because the plan path resolves against the root.
237
+ "plan-issues": {
238
+ script: "scripts/plan-issues.ts",
239
+ summary:
240
+ "Apply an approved issue plan — --decompose creates issues from criteria (step 4), --repair links and demotes existing ones",
241
+ usage:
242
+ "rungate plan-issues (--repair | --decompose) <plan.md> --repo <owner/name> [--write] [--json]",
243
+ projectRootFlag: true,
244
+ },
245
+ // Step 5 of ADR-003. `plan-spec` turns the placement table into milestones;
246
+ // this turns the ORDER of those milestones into `blocked by` edges, which is
247
+ // AGENTS.md rule 4 — ordering is data, not prose.
248
+ //
249
+ // No `projectRootFlag`: it reads the tracker, not the tree. The phase is
250
+ // read off each issue's milestone title, so there is no spec path to
251
+ // resolve and nothing on disk it could resolve against the wrong root.
252
+ "plan-deps": {
253
+ script: "scripts/plan-deps.ts",
254
+ summary: "Write a spec's phase order onto the tracker as blocked-by edges",
255
+ usage:
256
+ "rungate plan-deps --repo <owner/name> --milestone-prefix <name> [--write] [--json] [--include-closed]",
257
+ },
125
258
  "sync-spec-tests": {
126
259
  script: "scripts/sync-spec-tests.ts",
127
260
  summary: "Regenerate the conformity suite from the specs",
@@ -69,6 +69,40 @@ export function readProjectSlug(projectRoot: string): string | null {
69
69
  return typeof slug === "string" && slug.trim() ? slug : null;
70
70
  }
71
71
 
72
+ /**
73
+ * The project board this repository's readings are taken against — item **B4**.
74
+ *
75
+ * `null` when no `board` block is configured, or when it does not carry both
76
+ * identifiers a field read needs. Null rather than a partial object: a caller
77
+ * holding a project id with no field id cannot read a column, and handing it
78
+ * half the block makes it decide for itself what to do about the other half —
79
+ * which is a second decider in every caller.
80
+ *
81
+ * `board` is not in `ProjectHarnessSchema`; it reaches the resolved config
82
+ * through `.passthrough()`, same as `remoteHosts`, which is why every field
83
+ * access below is guarded rather than typed.
84
+ *
85
+ * **The field is named by ID, and only by id.** `lib/live-issues.ts` resolves
86
+ * it to a name against the API. A name configured beside the id would be two
87
+ * identifiers for one field, and a rename on the board would read every value
88
+ * as blank with nothing saying so.
89
+ */
90
+ export function readBoardConfig(projectRoot: string): { projectId: string; criteriaFieldId: string } | null {
91
+ const config = tryLoadRungateConfig(projectRoot);
92
+ const board = (config as Record<string, unknown> | null)?.board;
93
+ if (!board || typeof board !== "object" || Array.isArray(board)) return null;
94
+ const row = board as Record<string, unknown>;
95
+ const fields = row.fields;
96
+ const criteria =
97
+ fields && typeof fields === "object" && !Array.isArray(fields)
98
+ ? (fields as Record<string, unknown>).Criteria
99
+ : undefined;
100
+ const projectId = typeof row.id === "string" ? row.id.trim() : "";
101
+ const criteriaFieldId = typeof criteria === "string" ? criteria.trim() : "";
102
+ if (projectId === "" || criteriaFieldId === "") return null;
103
+ return { projectId, criteriaFieldId };
104
+ }
105
+
72
106
  /**
73
107
  * Pre-flight SSH hosts, keyed by name. `{}` when none are configured.
74
108
  *