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.
- 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 +64 -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-findings.ts +142 -2
- package/lib/scaffold/ai-review-step.ts +277 -52
- 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 +828 -0
- package/scripts/board-mirror.ts +344 -0
- package/scripts/board-snapshot.ts +468 -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 +721 -0
- 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
|
+
}
|