rungate 0.8.8 → 0.8.12

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 (45) 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 +64 -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-findings.ts +142 -2
  24. package/lib/scaffold/ai-review-step.ts +277 -52
  25. package/lib/scaffold/owned-files.ts +60 -2
  26. package/lib/scaffold/steps.ts +130 -4
  27. package/lib/spec-deps.ts +257 -0
  28. package/lib/spec-evidence.ts +479 -0
  29. package/lib/spec-placement.ts +430 -0
  30. package/lib/spec-template.ts +206 -0
  31. package/lib/stage-ladder.ts +628 -0
  32. package/lib/worktree-cleanup.ts +438 -3
  33. package/package.json +12 -4
  34. package/scripts/ai-review-threads.ts +10 -1
  35. package/scripts/audit-spec-evidence.ts +246 -0
  36. package/scripts/audit-specs.ts +27 -0
  37. package/scripts/board-conformance.ts +828 -0
  38. package/scripts/board-mirror.ts +344 -0
  39. package/scripts/board-snapshot.ts +468 -0
  40. package/scripts/create-spec.ts +8 -34
  41. package/scripts/criterion-inventory.ts +649 -0
  42. package/scripts/extract-constraints.ts +108 -9
  43. package/scripts/plan-deps.ts +378 -0
  44. package/scripts/plan-issues.ts +721 -0
  45. package/scripts/plan-spec.ts +371 -0
@@ -0,0 +1,325 @@
1
+ /**
2
+ * Which ticked criteria an open issue NAMES — and nothing else.
3
+ *
4
+ * ## The one design decision in this file, stated out loud
5
+ *
6
+ * The column is **"an open issue names this criterion"**. It is mechanical,
7
+ * re-derivable from the tree and the tracker by anyone at any time, and two
8
+ * people running it get the same answer.
9
+ *
10
+ * The column is **not** "an open issue contradicts this criterion". That
11
+ * sounds like the useful question and it is the one that must not be a
12
+ * column, because it is a judgement. A boolean nobody can re-derive, settable
13
+ * by whoever is looking, is exactly the defect this whole line of work exists
14
+ * to escape: a tick in a checkbox is a human-settable boolean asserting that
15
+ * something is true, and `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` is bound to
16
+ * the evidence rule precisely so that a tick has to name what proved it. A
17
+ * "contradicts" column rebuilds the mechanical-tick-is-proof defect one level
18
+ * up, in the instrument built to measure it.
19
+ *
20
+ * So the judgement is recorded **separately, dated and attributed**, in the
21
+ * shape OSCAL gives an observation: a thing somebody observed, when, and by
22
+ * what method — never a property of the subject. {@link Adjudication} is that
23
+ * record. A row carries at most one, and carries it only while the criterion's
24
+ * wording is unchanged: an adjudication whose fingerprint no longer matches is
25
+ * reported **STALE**, not silently carried onto text nobody adjudicated. That
26
+ * is the same rule `lib/spec-evidence.ts` applies to `proved-by:`.
27
+ *
28
+ * ## Signal to noise, measured before this was written
29
+ *
30
+ * A sweep of every ticked criterion in the tree against every open issue on
31
+ * 2026-10-28 produced **12 raw hits, of which 2 were confirmed and 1
32
+ * plausible**: CRC-M11 (#1592 — the metric counts run ATTEMPTS, the sentence
33
+ * says ROUNDS), CRC-B7 (#1567 — nobody has observed a demotion on the live
34
+ * path), and SC-518 (#1585). Three were citations, where the issue names the
35
+ * criterion because it is working on it. Six were ambiguous-id noise.
36
+ *
37
+ * ## What this instrument cannot see, found by using it
38
+ *
39
+ * **It reads OPEN issues only, so a contradiction recorded in a closed issue
40
+ * is invisible.** That is not hypothetical: the first run adjudicated SC-453
41
+ * against #1162, which names the criterion only inside a *Related* line
42
+ * pointing at #1161 — *"SC-453 ticked without an implementation"* — and #1161
43
+ * is closed. So the census reports the citation and cannot report the claim
44
+ * the citation points at. Widening to closed issues is not obviously right
45
+ * either: most closed issues are closed because the thing was done, so the
46
+ * population would be mostly noise. Stated here rather than fixed, because an
47
+ * instrument whose blind spot is written down is a different thing from one
48
+ * whose blind spot is not.
49
+ *
50
+ * Which is why the two ambiguity classes below are excluded rather than
51
+ * reported and filtered later: an `SC-1`..`SC-9` match is as likely to be an
52
+ * issue's own numbering as a reference to a spec's criterion, and an `SC-A<n>`
53
+ * anti-criterion is numbered per spec so the id alone does not identify one.
54
+ * Reporting them would make the mechanical column itself unreliable, and a
55
+ * mechanical column that needs a human to discount half its rows is a
56
+ * judgement wearing a census's clothes.
57
+ */
58
+
59
+ import { criterionFingerprint, isIsoDay, parseCriteria } from "./spec-evidence";
60
+ import { isAntiCriterion, isIssueShaped, isTemplateSpec, oneScMentionPattern } from "./sc-ids";
61
+
62
+ /** An open issue, reduced to the two fields a name-match can read. */
63
+ export interface IssueRef {
64
+ number: number;
65
+ title: string;
66
+ body: string;
67
+ }
68
+
69
+ /** A spec, as read off disk. `file` is repo-relative. */
70
+ export interface SpecRef {
71
+ file: string;
72
+ content: string;
73
+ }
74
+
75
+ /**
76
+ * A judgement somebody made about one (criterion, issue) pair.
77
+ *
78
+ * `collected` and `by` are not optional and not defaulted. An observation with
79
+ * no date and no observer is an assertion, which is the thing this record
80
+ * exists not to be.
81
+ */
82
+ export interface Adjudication {
83
+ criterion: string;
84
+ issue: number;
85
+ /**
86
+ * `contradicts` — the issue says the ticked criterion is not true.
87
+ * `cites` — the issue names the criterion as the work it is doing.
88
+ * `unrelated` — the id matched and the issue is about something else.
89
+ */
90
+ verdict: "contradicts" | "cites" | "unrelated";
91
+ by: string;
92
+ /** YYYY-MM-DD, the day the judgement was made. */
93
+ collected: string;
94
+ note: string;
95
+ /** The criterion's fingerprint when the judgement was made. */
96
+ fingerprint: string;
97
+ }
98
+
99
+ /** What the adjudication record says about a row, right now. */
100
+ export type AdjudicationStanding =
101
+ | { status: "none" }
102
+ | { status: "current"; record: Adjudication }
103
+ | { status: "stale"; record: Adjudication; fingerprint: string };
104
+
105
+ export interface CensusRow {
106
+ spec: string;
107
+ id: string;
108
+ ticked: boolean;
109
+ fingerprint: string;
110
+ /** Open issues naming this criterion, ascending. The mechanical column. */
111
+ namedBy: number[];
112
+ /** One standing per naming issue, keyed by issue number. */
113
+ standing: Record<number, AdjudicationStanding>;
114
+ }
115
+
116
+ /**
117
+ * Ids whose match carries no information, and why each is excluded.
118
+ *
119
+ * Exported so a test can assert the exclusion is the one documented rather
120
+ * than whatever the predicate happens to do today.
121
+ */
122
+ export function isAmbiguousId(id: string): boolean {
123
+ return isIssueShaped(id) || isAntiCriterion(id);
124
+ }
125
+
126
+ /**
127
+ * The spec template is a worked example, not a document making claims.
128
+ *
129
+ * `specs/SPEC-TEMPLATE.md` ships `- [x] SC-2: [second criterion]` to show an
130
+ * author what a ticked line looks like. That placeholder stays out of the
131
+ * census today only because `SC-2` is single-digit and therefore ambiguous —
132
+ * renumber it to `SC-10` while leaving it ticked and the template's
133
+ * boilerplate becomes a row indistinguishable from a real contested
134
+ * criterion. Excluding the file by name is what `buildScRegistry` already
135
+ * does, and it does not depend on how the example happens to be numbered.
136
+ * Raised by the required reviewer on #1641.
137
+ */
138
+ // `isTemplateSpec` from `./sc-ids` — the function `buildScRegistry` itself
139
+ // calls — rather than a second list here. The first draft of this shipped its
140
+ // own `EXCLUDED_SPECS` array while the comment above claimed it did what
141
+ // `buildScRegistry` does; that is the "two deciders that agree" shape
142
+ // `.claude/rules/checks-must-be-able-to-fail.md` names, and the failure is
143
+ // silent — a mutation of either leaves the other holding every case up, so
144
+ // both read as covered and nobody can see which one is dead. Raised by the
145
+ // required reviewer on #1641, round 4.
146
+
147
+ /**
148
+ * Refuse an adjudication record this module cannot read, naming it.
149
+ *
150
+ * The store is hand-maintained JSON, so `"issue": "1567"` as a string is a
151
+ * plausible typo — and it would throw nowhere: the lookup in {@link
152
+ * censusRows} is a strict `===`, so the record simply never matches and the
153
+ * row reports UNADJUDICATED while a human's judgement sits in the file. That
154
+ * is the same corruption-as-absence the file-level read was fixed for, one
155
+ * level down. Raised by the required reviewer on #1641.
156
+ */
157
+ export function assertAdjudicationShape(
158
+ record: unknown,
159
+ at: string,
160
+ ): asserts record is Adjudication {
161
+ if (record === null || typeof record !== "object") {
162
+ throw new Error(`${at} is not an object. A record this module cannot read is a refusal.`);
163
+ }
164
+ const r = record as Partial<Adjudication>;
165
+ const problems: string[] = [];
166
+ for (const key of ["criterion", "by", "fingerprint"] as const) {
167
+ if (typeof r[key] !== "string" || r[key]!.length === 0) {
168
+ problems.push(`\`${key}\` must be a non-empty string, got ${JSON.stringify(r[key])}`);
169
+ }
170
+ }
171
+ if (typeof r.note !== "string") {
172
+ problems.push(`\`note\` must be a string, got ${JSON.stringify(r.note)}`);
173
+ }
174
+ // Named rather than coerced. `"1567"` is a typo somebody should see, and
175
+ // silently accepting it teaches the store that either spelling works.
176
+ if (typeof r.issue !== "number" || !Number.isInteger(r.issue)) {
177
+ problems.push(`\`issue\` must be an integer, got ${JSON.stringify(r.issue)}`);
178
+ }
179
+ if (!["contradicts", "cites", "unrelated"].includes(r.verdict as string)) {
180
+ problems.push(
181
+ `\`verdict\` must be contradicts, cites or unrelated, got ${JSON.stringify(r.verdict)}`,
182
+ );
183
+ }
184
+ // `isIsoDay` from `lib/spec-evidence.ts`, not a second regex. The pattern
185
+ // alone accepts `2026-02-30`, which is not a day, and a record dated to a
186
+ // day that does not exist prints in the view as though somebody looked at
187
+ // the issue on it. Reusing the module's own validator also keeps this from
188
+ // becoming the "two deciders that agree" shape
189
+ // `.claude/rules/checks-must-be-able-to-fail.md` names: a second copy here
190
+ // would survive any mutation of the first and nobody could tell which one
191
+ // the suite was holding up. Raised by the required reviewer on #1641.
192
+ if (!isIsoDay(r.collected ?? "")) {
193
+ problems.push(`\`collected\` must be a real YYYY-MM-DD day, got ${JSON.stringify(r.collected)}`);
194
+ }
195
+ if (problems.length > 0) {
196
+ throw new Error(
197
+ `${at} is malformed and would silently report as UNADJUDICATED: ${problems.join("; ")}.`,
198
+ );
199
+ }
200
+ }
201
+
202
+ /**
203
+ * Refuse a store holding two judgements for the same (criterion, issue).
204
+ *
205
+ * The lookup below is a `find`, so it takes the FIRST match and the rest are
206
+ * invisible — and the store is hand-maintained and append-ordered, which makes
207
+ * appending a correction the obvious way to change your mind. Under a `find`
208
+ * that correction never takes effect and the view keeps printing the judgement
209
+ * it replaced, with its original date and signer, looking entirely current.
210
+ *
211
+ * Taking the last record instead would be the cheap fix and the wrong one: it
212
+ * makes the store's meaning depend on line order, which nothing states and no
213
+ * reader can see. Two records for one pair is somebody's unresolved
214
+ * disagreement, and the only honest reading of it is a refusal. Raised by the
215
+ * required reviewer on #1641 — the same corruption-as-absence shape as the
216
+ * file read and the per-record validation, one level further out.
217
+ */
218
+ export function assertOneJudgementPerPair(adjudications: readonly Adjudication[]): void {
219
+ const seen = new Map<string, number>();
220
+ const duplicates: string[] = [];
221
+ adjudications.forEach((a, at) => {
222
+ const key = `${a.criterion}/#${a.issue}`;
223
+ const first = seen.get(key);
224
+ if (first === undefined) seen.set(key, at);
225
+ else duplicates.push(`${key} (records ${first} and ${at})`);
226
+ });
227
+ if (duplicates.length > 0) {
228
+ throw new Error(
229
+ `the adjudication store holds more than one judgement for: ${duplicates.join("; ")}. ` +
230
+ `The lookup takes the first match, so every later record — including a correction ` +
231
+ `appended deliberately — would be silently ignored. Edit the existing record instead.`,
232
+ );
233
+ }
234
+ }
235
+
236
+ /** Does this issue name this criterion, on a word boundary? */
237
+ export function issueNames(issue: IssueRef, id: string): boolean {
238
+ const pattern = oneScMentionPattern(id);
239
+ return pattern.test(issue.title) || pattern.test(issue.body ?? "");
240
+ }
241
+
242
+ /**
243
+ * The census.
244
+ *
245
+ * Only ticked criteria are rows: an open issue naming an UNTICKED criterion is
246
+ * the normal way work is tracked and says nothing is wrong. The question this
247
+ * answers is narrower and is the one with a defect behind it — *this document
248
+ * says we have done something, and the tracker has something open that names
249
+ * it.*
250
+ */
251
+ export function censusRows(
252
+ specs: readonly SpecRef[],
253
+ issues: readonly IssueRef[],
254
+ adjudications: readonly Adjudication[],
255
+ ): CensusRow[] {
256
+ assertOneJudgementPerPair(adjudications);
257
+ const rows: CensusRow[] = [];
258
+
259
+ for (const spec of specs) {
260
+ if (isTemplateSpec(spec.file)) continue;
261
+ for (const c of parseCriteria(spec.content)) {
262
+ if (!c.ticked) continue;
263
+ if (isAmbiguousId(c.id)) continue;
264
+
265
+ const namedBy = issues
266
+ .filter(i => issueNames(i, c.id))
267
+ .map(i => i.number)
268
+ .sort((a, b) => a - b);
269
+ if (namedBy.length === 0) continue;
270
+
271
+ const fingerprint = criterionFingerprint(c.text);
272
+ const standing: Record<number, AdjudicationStanding> = {};
273
+ for (const issue of namedBy) {
274
+ const record = adjudications.find(
275
+ a => a.criterion === c.id && a.issue === issue,
276
+ );
277
+ if (!record) {
278
+ standing[issue] = { status: "none" };
279
+ } else if (record.fingerprint === fingerprint) {
280
+ standing[issue] = { status: "current", record };
281
+ } else {
282
+ standing[issue] = { status: "stale", record, fingerprint };
283
+ }
284
+ }
285
+
286
+ rows.push({ spec: spec.file, id: c.id, ticked: true, fingerprint, namedBy, standing });
287
+ }
288
+ }
289
+
290
+ return rows;
291
+ }
292
+
293
+ /**
294
+ * Rows a person still owes a judgement on: named by an issue, and either never
295
+ * adjudicated or adjudicated against wording that has since changed.
296
+ */
297
+ export function unadjudicated(rows: readonly CensusRow[]): CensusRow[] {
298
+ return rows.filter(r =>
299
+ r.namedBy.some(i => r.standing[i].status !== "current"),
300
+ );
301
+ }
302
+
303
+ /** The view, as text. One line per (criterion, issue) pair. */
304
+ export function renderCensus(rows: readonly CensusRow[], taken: string): string {
305
+ const out: string[] = [
306
+ `criterion/issue census — ${taken}`,
307
+ ` ${rows.length} ticked criterion(s) are named by an open issue.`,
308
+ "",
309
+ ];
310
+ for (const r of rows) {
311
+ for (const issue of r.namedBy) {
312
+ const s = r.standing[issue];
313
+ const verdict =
314
+ s.status === "none"
315
+ ? "UNADJUDICATED"
316
+ : s.status === "stale"
317
+ ? `STALE (judged ${s.record.verdict} by ${s.record.by} on ${s.record.collected}, ` +
318
+ `against fingerprint ${s.record.fingerprint}; the text now hashes to ${s.fingerprint})`
319
+ : `${s.record.verdict.toUpperCase()} (${s.record.by}, ${s.record.collected})`;
320
+ out.push(` ${r.id} (${r.spec}) named by #${issue} — ${verdict}`);
321
+ if (s.status !== "none" && s.record.note) out.push(` ${s.record.note}`);
322
+ }
323
+ }
324
+ return out.join("\n");
325
+ }