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.
- package/gates/.gate-salt +1 -1
- package/hooks/StaleTTLCleanup.hook.ts +13 -5
- package/hooks/VerifyPhaseLock.hook.ts +8 -0
- package/hooks/lib/findWorkflow.ts +19 -3
- package/lib/active-workflow.ts +57 -0
- package/lib/ai-review-rounds.ts +102 -9
- package/lib/ai-review-threads.ts +71 -3
- package/lib/board-mirror.ts +438 -0
- package/lib/cli-commands.ts +133 -0
- package/lib/config-readers.ts +34 -0
- package/lib/crc-reading.ts +655 -0
- package/lib/criterion-issue-census.ts +325 -0
- package/lib/filing-plan.ts +381 -0
- package/lib/generators/agents-md.ts +15 -11
- package/lib/git-isolation.ts +32 -0
- package/lib/github.ts +66 -0
- package/lib/issue-decomposition.ts +523 -0
- package/lib/issue-filing-gate.ts +304 -19
- package/lib/issue-repair.ts +225 -0
- package/lib/live-issues.ts +442 -0
- package/lib/project-state-shape.ts +30 -0
- package/lib/sc-ids.ts +31 -1
- package/lib/scaffold/ai-review-step.ts +222 -48
- package/lib/scaffold/owned-files.ts +60 -2
- package/lib/scaffold/steps.ts +130 -4
- package/lib/spec-deps.ts +257 -0
- package/lib/spec-evidence.ts +479 -0
- package/lib/spec-placement.ts +430 -0
- package/lib/spec-template.ts +206 -0
- package/lib/stage-ladder.ts +628 -0
- package/lib/worktree-cleanup.ts +438 -3
- package/package.json +12 -4
- package/scripts/ai-review-threads.ts +10 -1
- package/scripts/audit-spec-evidence.ts +246 -0
- package/scripts/audit-specs.ts +27 -0
- package/scripts/board-conformance.ts +765 -0
- package/scripts/board-mirror.ts +344 -0
- package/scripts/board-snapshot.ts +459 -0
- package/scripts/create-spec.ts +8 -34
- package/scripts/criterion-inventory.ts +649 -0
- package/scripts/extract-constraints.ts +108 -9
- package/scripts/plan-deps.ts +378 -0
- package/scripts/plan-issues.ts +701 -0
- 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
|
+
}
|
package/lib/cli-commands.ts
CHANGED
|
@@ -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",
|
package/lib/config-readers.ts
CHANGED
|
@@ -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
|
*
|