rungate 0.8.13 → 0.8.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +182 -0
- package/gates/.gate-salt +1 -1
- package/hooks/HarnessAFKGate.hook.ts +5 -1
- package/hooks/HookCurrency.hook.ts +11 -8
- package/hooks/MergeGuard.hook.ts +7 -1
- package/hooks/StaleTTLCleanup.hook.ts +4 -4
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/hooks/lib/findWorkflow.ts +3 -2
- package/hooks/lib/paths.ts +14 -2
- package/hooks/lib/utils.ts +23 -3
- package/lib/active-milestone.ts +50 -0
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +397 -23
- package/lib/board-flow.ts +280 -0
- package/lib/board-lane-health.ts +578 -0
- package/lib/board-mirror.ts +136 -39
- package/lib/board-ready-fanout.ts +297 -14
- package/lib/board-ready-rule.ts +1211 -0
- package/lib/board-throughput.ts +136 -0
- package/lib/board-walkthrough.ts +240 -0
- package/lib/body-evidence.ts +203 -0
- package/lib/branch-protection.ts +399 -9
- package/lib/bun-version.ts +36 -0
- package/lib/cli-commands.ts +75 -4
- package/lib/closing-reference-audit.ts +307 -6
- package/lib/config-loader.ts +254 -25
- package/lib/config-readers.ts +170 -10
- package/lib/config-trackable.ts +96 -57
- package/lib/conformity.ts +121 -7
- package/lib/create-sc.ts +25 -2
- package/lib/derived-spec.ts +21 -9
- package/lib/filing-compliance.ts +367 -0
- package/lib/filing-plan.ts +47 -21
- package/lib/finding-arbiter.ts +79 -5
- package/lib/finding-jury.ts +43 -4
- package/lib/finding-promotion.ts +1123 -0
- package/lib/generators/agents-md.ts +149 -0
- package/lib/git-isolation.ts +137 -1
- package/lib/github-api-base.ts +66 -0
- package/lib/github.ts +194 -9
- package/lib/graphql-cursor.ts +80 -0
- package/lib/hook-scopes.ts +78 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +124 -7
- package/lib/issue-extraction.ts +9 -7
- package/lib/issue-file-overlap.ts +373 -0
- package/lib/issue-filing-gate.ts +1109 -52
- package/lib/issue-repair.ts +90 -9
- package/lib/issue-shape.ts +199 -0
- package/lib/live-issues.ts +31 -2
- package/lib/local-work.ts +423 -0
- package/lib/markdown-fence.ts +134 -0
- package/lib/milestone-title.ts +46 -0
- package/lib/scaffold/ai-review-findings.ts +148 -3
- package/lib/scaffold/ai-review-step.ts +65 -5
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
- package/lib/scaffold/steps.ts +115 -9
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +55 -11
- package/lib/spec-placement.ts +203 -13
- package/lib/spec-registry.ts +75 -16
- package/lib/spec-source.ts +609 -0
- package/lib/spec-write-sweep.ts +4 -0
- package/lib/stage-ladder.ts +896 -3
- package/lib/state-claim-readings.ts +252 -0
- package/lib/success-doc.ts +7 -6
- package/lib/test-command-positions.ts +135 -1
- package/lib/work-status.ts +551 -0
- package/lib/worktree-repo.ts +14 -2
- package/package.json +7 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/audit-closing-references.ts +330 -0
- package/scripts/audit-specs.ts +59 -103
- package/scripts/board-conformance.ts +747 -40
- package/scripts/board-mirror.ts +594 -13
- package/scripts/board-ready.ts +979 -0
- package/scripts/board-snapshot.ts +464 -12
- package/scripts/claim-files.ts +578 -0
- package/scripts/criterion-inventory.ts +526 -50
- package/scripts/finding-promotion.ts +547 -0
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-issues.ts +279 -40
- package/scripts/plan-spec.ts +105 -3
- package/scripts/sync-sc-status.ts +147 -7
- package/scripts/worktree-census.ts +958 -0
- package/scripts/worktree-sweep.ts +269 -0
|
@@ -0,0 +1,367 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Did a refused filing become the comment the refusal told it to be?
|
|
3
|
+
*
|
|
4
|
+
* ## The question, and why nothing answered it before
|
|
5
|
+
*
|
|
6
|
+
* `lib/issue-filing-gate.ts` refuses a filing and routes it to a comment. It
|
|
7
|
+
* does not WRITE the comment — it returns a refusal naming where one should
|
|
8
|
+
* go, and the finding survives only if the agent then writes it. So the gate
|
|
9
|
+
* can be working perfectly while findings are being deleted, and the ledger
|
|
10
|
+
* records the refusal either way. **Compliance with a refusal is the one
|
|
11
|
+
* thing nothing in this tree records.**
|
|
12
|
+
*
|
|
13
|
+
* It matters more than it sounds. The measure the cap was shipped against is
|
|
14
|
+
* issues opened per day, and that number falls **identically** whether the
|
|
15
|
+
* agent writes the comment or drops the finding on the floor. A metric that
|
|
16
|
+
* reads the same on the good outcome and the bad one is not measuring the
|
|
17
|
+
* thing anybody wants.
|
|
18
|
+
*
|
|
19
|
+
* ## A rate of zero and a denominator of zero are different readings
|
|
20
|
+
*
|
|
21
|
+
* This module exists in a world where the honest answer is *nobody has been
|
|
22
|
+
* refused yet*: measured 2026-10-25, the production ledger holds 261 rows
|
|
23
|
+
* and **zero** `OVER_CAP` and **zero** `COMMENT_INSTEAD`. So `rate` is
|
|
24
|
+
* `number | null` and is `null` whenever `observable === 0`. Not `0`, and
|
|
25
|
+
* not a thrown error — `0` is the reading that says agents ignore refusals,
|
|
26
|
+
* which is a serious claim to make about a population that does not exist.
|
|
27
|
+
*
|
|
28
|
+
* `unobservableByRefusal` is beside it so the gap is attributable: a reader
|
|
29
|
+
* learns *which* refusals could not be followed up, which is what decides
|
|
30
|
+
* whether the fix is to persist a field or to wait for traffic.
|
|
31
|
+
*
|
|
32
|
+
* ## Why it is an UPPER BOUND and says so in the field name
|
|
33
|
+
*
|
|
34
|
+
* The ledger does not record WHO attempted the filing. So a comment landing
|
|
35
|
+
* on the target inside the window cannot be attributed to the agent that was
|
|
36
|
+
* refused; it may be anyone's, including a human answering something else.
|
|
37
|
+
* Counting it as compliance can only ever overstate.
|
|
38
|
+
*
|
|
39
|
+
* That is still worth having, because the bound is informative in one
|
|
40
|
+
* direction: an upper bound of zero is decisive, and that is the reading we
|
|
41
|
+
* expect to be arguing about. `compliedUpperBound` is named rather than
|
|
42
|
+
* called `complied` so a later reader cannot quote it as a compliance rate.
|
|
43
|
+
*
|
|
44
|
+
* ## A comment is a TIMELINE EVENT. An issue-body edit is not.
|
|
45
|
+
*
|
|
46
|
+
* Measured on this tracker, 2026-10-25: #1592 carries four `commented`
|
|
47
|
+
* timeline events, while #1476 — edited twice on 10-24, at `00:29:52Z` and
|
|
48
|
+
* `01:32:24Z` — carries **no timeline event for either edit**. The edits
|
|
49
|
+
* exist only under GraphQL `userContentEdits`, which nothing subscribes to.
|
|
50
|
+
*
|
|
51
|
+
* So an answer appended to an issue BODY notifies nobody and is not
|
|
52
|
+
* compliance in any sense a human experiences. `ghIssueComments` reads the
|
|
53
|
+
* comments endpoint and never the body, and a `CommentReading` carries only
|
|
54
|
+
* comment timestamps, so no caller of this module can accidentally count a
|
|
55
|
+
* body edit.
|
|
56
|
+
*
|
|
57
|
+
* ## The target is only recoverable for one refusal class today
|
|
58
|
+
*
|
|
59
|
+
* The refusal MESSAGE names a comment target, computed at refusal time. The
|
|
60
|
+
* ledger ROW does not persist it. The one exception is `DUPLICATE`, whose
|
|
61
|
+
* `duplicateOf` holds the issues the finding collided with — so those rows
|
|
62
|
+
* carry their own target and are the only historical population this can
|
|
63
|
+
* read. Everything else is `UNOBSERVABLE`, by name, with the refusal in the
|
|
64
|
+
* reason. Persisting the target on the row is the change that would widen
|
|
65
|
+
* the denominator; that is a decision for whoever reads this output, and it
|
|
66
|
+
* is deliberately not made here.
|
|
67
|
+
*/
|
|
68
|
+
|
|
69
|
+
import { createGitHubClient, listIssueComments, type GitHubClient } from "./github";
|
|
70
|
+
import type { ArbiterRefusal } from "./finding-arbiter";
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The fields of a ledger row this reading needs.
|
|
74
|
+
*
|
|
75
|
+
* Deliberately a structural subset of `FilingLedgerRow` rather than an
|
|
76
|
+
* import of it: rows are read back from JSONL written by two different
|
|
77
|
+
* writers over two days, and several of them predate fields the current
|
|
78
|
+
* interface declares. A reader that required the full shape would refuse
|
|
79
|
+
* the population it exists to measure.
|
|
80
|
+
*/
|
|
81
|
+
export interface FilingComplianceRow {
|
|
82
|
+
at: string;
|
|
83
|
+
title: string;
|
|
84
|
+
refusal: string | null;
|
|
85
|
+
emitted: boolean;
|
|
86
|
+
/**
|
|
87
|
+
* **Written as STRINGS by the live writer**, and typed to say so.
|
|
88
|
+
*
|
|
89
|
+
* Measured on the production ledger 2026-10-25: all 14 elements across 261
|
|
90
|
+
* rows are decimal strings — `["1214"]` — and the first version of this
|
|
91
|
+
* module accepted only `number`, so it discarded every target it had and
|
|
92
|
+
* reported a denominator of zero for the entire file. That is the failure
|
|
93
|
+
* this module is otherwise built to refuse, arriving through the parser
|
|
94
|
+
* instead of through the data: an empty population and a population the
|
|
95
|
+
* reader could not see are the same output.
|
|
96
|
+
*/
|
|
97
|
+
duplicateOf?: readonly (number | string)[];
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Where a refused finding was told to go, or why that cannot be read. */
|
|
101
|
+
export type ComplianceTarget =
|
|
102
|
+
| { reading: "NAMED"; issues: number[] }
|
|
103
|
+
| { reading: "UNOBSERVABLE"; why: string };
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* The comments on one target, or the sentence saying why none were read.
|
|
107
|
+
*
|
|
108
|
+
* **An `UNMEASURED` lookup must never render as "no comment".** They are the
|
|
109
|
+
* two readings this whole module exists to keep apart, and a lookup that
|
|
110
|
+
* returned `[]` on an HTTP error would collapse them at the one place a
|
|
111
|
+
* caller cannot see.
|
|
112
|
+
*/
|
|
113
|
+
export type CommentReading =
|
|
114
|
+
| { reading: "MEASURED"; comments: readonly { at: string }[] }
|
|
115
|
+
| { reading: "UNMEASURED"; why: string };
|
|
116
|
+
|
|
117
|
+
export type CommentLookup = (issue: number) => Promise<CommentReading>;
|
|
118
|
+
|
|
119
|
+
export type RowReading =
|
|
120
|
+
| { state: "COMPLIED"; title: string; target: number; at: string }
|
|
121
|
+
| { state: "NOT_OBSERVED"; title: string; targets: number[] }
|
|
122
|
+
| { state: "UNOBSERVABLE"; title: string; why: string };
|
|
123
|
+
|
|
124
|
+
export interface ComplianceReading {
|
|
125
|
+
rows: RowReading[];
|
|
126
|
+
/** Rows on which compliance could be read at all. The denominator. */
|
|
127
|
+
observable: number;
|
|
128
|
+
/** Rows with no recoverable target, or whose lookup failed. */
|
|
129
|
+
unobservable: number;
|
|
130
|
+
/** See the header: an upper bound, because comments are unattributed. */
|
|
131
|
+
compliedUpperBound: number;
|
|
132
|
+
/** `null` when `observable === 0`. Never `0` for an empty population. */
|
|
133
|
+
rate: number | null;
|
|
134
|
+
/** Which refusals could not be followed up, and how many of each. */
|
|
135
|
+
unobservableByRefusal: Record<string, number>;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** A row that was never refused has nothing to comply with. */
|
|
139
|
+
const NOT_REFUSED = "NOT_REFUSED";
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* A row that WAS refused and whose refusal the ledger did not label. Distinct
|
|
143
|
+
* from `NOT_REFUSED`, which means the row was emitted and has nothing to
|
|
144
|
+
* comply with. Both are "no refusal string"; only one of them is a gap.
|
|
145
|
+
*/
|
|
146
|
+
const REFUSED_UNLABELLED = "REFUSED_UNLABELLED";
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* The one refusal whose row persists its own comment target.
|
|
150
|
+
*
|
|
151
|
+
* One binding, so the rule the header states and the rule the code applies
|
|
152
|
+
* are the same string, and a mutation of it moves the behaviour.
|
|
153
|
+
* `issue-filing-gate.ts` writes this literal on the dedupe refusal.
|
|
154
|
+
*/
|
|
155
|
+
const DUPLICATE: ArbiterRefusal = "DUPLICATE";
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* One `duplicateOf` element as an issue number, or `null`.
|
|
159
|
+
*
|
|
160
|
+
* One binding, so there is one thing to mutate and one place that decides
|
|
161
|
+
* what counts as a target. A value that names no issue returns `null` and
|
|
162
|
+
* the row goes UNOBSERVABLE — never `NaN`, which would be carried into a
|
|
163
|
+
* lookup and come back as an error that reads like a tracker fault.
|
|
164
|
+
*/
|
|
165
|
+
function issueNumber(value: unknown): number | null {
|
|
166
|
+
if (typeof value === "number") return Number.isInteger(value) && value > 0 ? value : null;
|
|
167
|
+
if (typeof value !== "string") return null;
|
|
168
|
+
const digits = value.trim().replace(/^#/, "");
|
|
169
|
+
if (!/^[0-9]+$/.test(digits)) return null;
|
|
170
|
+
const n = Number(digits);
|
|
171
|
+
return Number.isInteger(n) && n > 0 ? n : null;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
export function targetOf(row: FilingComplianceRow): ComplianceTarget {
|
|
175
|
+
if (row.emitted) {
|
|
176
|
+
return {
|
|
177
|
+
reading: "UNOBSERVABLE",
|
|
178
|
+
why: "this filing was not refused — it reached the tracker, so there is no comment to look for",
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
// **`duplicateOf` is only this row's target when the row's OWN refusal is
|
|
182
|
+
// `DUPLICATE`.** Review raised this twice before it was fixed, and it is
|
|
183
|
+
// the module's header contradicting its own code: the header says the one
|
|
184
|
+
// exception is `DUPLICATE`, whose `duplicateOf` holds the issues the
|
|
185
|
+
// finding collided with, and the code read the field on any unemitted row.
|
|
186
|
+
//
|
|
187
|
+
// `issue-filing-gate.ts` can reach a refusal other than `DUPLICATE` on a
|
|
188
|
+
// finding that already collided — the dedupe stage computes collisions
|
|
189
|
+
// before the later stages run — so a `TOO_MANY_FILES` row can carry a
|
|
190
|
+
// populated `duplicateOf`. Reading it measures whether somebody commented
|
|
191
|
+
// on an unrelated issue, and counts the answer as compliance with a
|
|
192
|
+
// refusal that named a different target entirely. It is the quiet
|
|
193
|
+
// direction: the denominator looks healthier and the rate is wrong.
|
|
194
|
+
if (row.refusal === DUPLICATE) {
|
|
195
|
+
const issues = (row.duplicateOf ?? [])
|
|
196
|
+
.map(issueNumber)
|
|
197
|
+
.filter((n): n is number => n !== null);
|
|
198
|
+
if (issues.length > 0) return { reading: "NAMED", issues: [...issues] };
|
|
199
|
+
}
|
|
200
|
+
return {
|
|
201
|
+
reading: "UNOBSERVABLE",
|
|
202
|
+
why:
|
|
203
|
+
`the ledger records no comment target for a ${row.refusal ?? REFUSED_UNLABELLED} refusal. ` +
|
|
204
|
+
"The refusal message named one, computed at refusal time; the row does not persist it",
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Was there a comment on this target inside the window?
|
|
210
|
+
*
|
|
211
|
+
* The window is closed at both ends on purpose. A comment written BEFORE the
|
|
212
|
+
* refusal cannot be an answer to it — that is the reading that would turn
|
|
213
|
+
* every duplicate-of-a-busy-issue into compliance — and one written after the
|
|
214
|
+
* window is not evidence about this refusal either.
|
|
215
|
+
*/
|
|
216
|
+
function commentInWindow(
|
|
217
|
+
reading: CommentReading,
|
|
218
|
+
fromMs: number,
|
|
219
|
+
windowMs: number,
|
|
220
|
+
): string | null {
|
|
221
|
+
if (reading.reading !== "MEASURED") return null;
|
|
222
|
+
for (const c of reading.comments) {
|
|
223
|
+
const at = Date.parse(c.at);
|
|
224
|
+
if (Number.isNaN(at)) continue;
|
|
225
|
+
if (at >= fromMs && at <= fromMs + windowMs) return c.at;
|
|
226
|
+
}
|
|
227
|
+
return null;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
export async function complianceReading(input: {
|
|
231
|
+
rows: readonly FilingComplianceRow[];
|
|
232
|
+
lookup: CommentLookup;
|
|
233
|
+
windowMs: number;
|
|
234
|
+
}): Promise<ComplianceReading> {
|
|
235
|
+
const rows: RowReading[] = [];
|
|
236
|
+
const unobservableByRefusal: Record<string, number> = {};
|
|
237
|
+
|
|
238
|
+
const countUnobservable = (row: FilingComplianceRow) => {
|
|
239
|
+
// TWO POPULATIONS, NOT ONE. This was
|
|
240
|
+
// `row.emitted ? NOT_REFUSED : (row.refusal ?? NOT_REFUSED)`, so a row
|
|
241
|
+
// that WAS refused but carries `refusal: null` — which the type allows
|
|
242
|
+
// and `targetOf`'s own UNOBSERVABLE message anticipates — landed in the
|
|
243
|
+
// same bucket as a row that was emitted and had nothing to comply with.
|
|
244
|
+
//
|
|
245
|
+
// This field exists to ATTRIBUTE the gap, and those two rows are the
|
|
246
|
+
// opposite ends of it: one needed no follow-up, the other needed one and
|
|
247
|
+
// the ledger cannot say what kind. Collapsing them is the one attribution
|
|
248
|
+
// this reading must never make, so the unlabelled refusal gets its own
|
|
249
|
+
// bucket rather than a default (`.claude/rules/config-access.md`, Silent
|
|
250
|
+
// Default Substitution).
|
|
251
|
+
const key = row.emitted ? NOT_REFUSED : (row.refusal ?? REFUSED_UNLABELLED);
|
|
252
|
+
unobservableByRefusal[key] = (unobservableByRefusal[key] ?? 0) + 1;
|
|
253
|
+
};
|
|
254
|
+
|
|
255
|
+
for (const row of input.rows) {
|
|
256
|
+
const target = targetOf(row);
|
|
257
|
+
if (target.reading === "UNOBSERVABLE") {
|
|
258
|
+
rows.push({ state: "UNOBSERVABLE", title: row.title, why: target.why });
|
|
259
|
+
countUnobservable(row);
|
|
260
|
+
continue;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
const from = Date.parse(row.at);
|
|
264
|
+
if (Number.isNaN(from)) {
|
|
265
|
+
rows.push({
|
|
266
|
+
state: "UNOBSERVABLE",
|
|
267
|
+
title: row.title,
|
|
268
|
+
why: `the row's timestamp \`${row.at}\` could not be read, so no window could be opened`,
|
|
269
|
+
});
|
|
270
|
+
countUnobservable(row);
|
|
271
|
+
continue;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
// A single COMPLIED is decisive, so an unreadable sibling target does not
|
|
275
|
+
// demote it. The reverse is not true: NOT_OBSERVED over a target we could
|
|
276
|
+
// not read is the conflation this module exists to refuse.
|
|
277
|
+
let complied: { target: number; at: string } | null = null;
|
|
278
|
+
let unreadable: string | null = null;
|
|
279
|
+
for (const issue of target.issues) {
|
|
280
|
+
const reading = await input.lookup(issue);
|
|
281
|
+
if (reading.reading === "UNMEASURED") {
|
|
282
|
+
unreadable ??= `#${issue} could not be read: ${reading.why}`;
|
|
283
|
+
continue;
|
|
284
|
+
}
|
|
285
|
+
const at = commentInWindow(reading, from, input.windowMs);
|
|
286
|
+
if (at !== null) {
|
|
287
|
+
complied = { target: issue, at };
|
|
288
|
+
break;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
if (complied !== null) {
|
|
293
|
+
rows.push({
|
|
294
|
+
state: "COMPLIED",
|
|
295
|
+
title: row.title,
|
|
296
|
+
target: complied.target,
|
|
297
|
+
at: complied.at,
|
|
298
|
+
});
|
|
299
|
+
continue;
|
|
300
|
+
}
|
|
301
|
+
if (unreadable !== null) {
|
|
302
|
+
rows.push({ state: "UNOBSERVABLE", title: row.title, why: unreadable });
|
|
303
|
+
countUnobservable(row);
|
|
304
|
+
continue;
|
|
305
|
+
}
|
|
306
|
+
rows.push({ state: "NOT_OBSERVED", title: row.title, targets: [...target.issues] });
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
const observable = rows.filter(r => r.state !== "UNOBSERVABLE").length;
|
|
310
|
+
const compliedUpperBound = rows.filter(r => r.state === "COMPLIED").length;
|
|
311
|
+
return {
|
|
312
|
+
rows,
|
|
313
|
+
observable,
|
|
314
|
+
unobservable: rows.length - observable,
|
|
315
|
+
compliedUpperBound,
|
|
316
|
+
// The whole point of the module, in one expression: an empty denominator
|
|
317
|
+
// withholds the number rather than printing the most alarming one.
|
|
318
|
+
rate: observable === 0 ? null : compliedUpperBound / observable,
|
|
319
|
+
unobservableByRefusal,
|
|
320
|
+
};
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* The real lookup: the tracker's COMMENTS endpoint, never the issue body.
|
|
325
|
+
*
|
|
326
|
+
* Separate from the pure reading above so the cases can drive every state
|
|
327
|
+
* without a network, and exported so the reading can be run from a one-liner
|
|
328
|
+
* rather than needing a script nothing else references:
|
|
329
|
+
*
|
|
330
|
+
* ```
|
|
331
|
+
* bun -e 'import {complianceReading, ghIssueComments} from "./lib/filing-compliance";
|
|
332
|
+
* const rows = (await Bun.file(process.env.HOME + "/.rungate/finding-ledger.jsonl").text())
|
|
333
|
+
* .trim().split("\n").map(l => JSON.parse(l));
|
|
334
|
+
* console.log(await complianceReading({rows, lookup: ghIssueComments("hornjason/pai-harness"),
|
|
335
|
+
* windowMs: 24 * 3_600_000}));'
|
|
336
|
+
* ```
|
|
337
|
+
*
|
|
338
|
+
* Every failure is `UNMEASURED` carrying its own sentence. There is no path
|
|
339
|
+
* here that returns an empty comment list for a request that did not succeed.
|
|
340
|
+
*/
|
|
341
|
+
export function ghIssueComments(
|
|
342
|
+
repo: string,
|
|
343
|
+
// The seam exists so the failure path can be DRIVEN rather than provoked.
|
|
344
|
+
// Its first version had no argument, so the only way to observe the
|
|
345
|
+
// UNMEASURED branch was to run the case against the live API and hope it
|
|
346
|
+
// failed — a case whose verdict depends on the network is not a case.
|
|
347
|
+
makeClient: () => GitHubClient = createGitHubClient,
|
|
348
|
+
): CommentLookup {
|
|
349
|
+
return async (issue: number): Promise<CommentReading> => {
|
|
350
|
+
// SC-893: Octokit, not a `gh` subprocess. The three readings are
|
|
351
|
+
// unchanged — a client that cannot be built and a request that failed are
|
|
352
|
+
// both UNMEASURED carrying their own sentence, and neither may degrade
|
|
353
|
+
// into an empty comment list, which would read as "nobody commented".
|
|
354
|
+
let client: GitHubClient;
|
|
355
|
+
try {
|
|
356
|
+
client = makeClient();
|
|
357
|
+
} catch (e) {
|
|
358
|
+
return { reading: "UNMEASURED", why: `no GitHub client: ${(e as Error).message}` };
|
|
359
|
+
}
|
|
360
|
+
try {
|
|
361
|
+
const rows = await listIssueComments(client, repo, issue);
|
|
362
|
+
return { reading: "MEASURED", comments: rows.map(r => ({ at: r.created_at })) };
|
|
363
|
+
} catch (e) {
|
|
364
|
+
return { reading: "UNMEASURED", why: `the comments request failed: ${(e as Error).message}` };
|
|
365
|
+
}
|
|
366
|
+
};
|
|
367
|
+
}
|
package/lib/filing-plan.ts
CHANGED
|
@@ -51,6 +51,9 @@
|
|
|
51
51
|
*/
|
|
52
52
|
import { spawnSync } from "child_process";
|
|
53
53
|
|
|
54
|
+
import { remoteMainCommit, type RemoteMain } from "./config-loader";
|
|
55
|
+
import { closesFence, fenceOpening, type FenceOpening } from "./markdown-fence";
|
|
56
|
+
|
|
54
57
|
/**
|
|
55
58
|
* Where a reviewed plan lives.
|
|
56
59
|
*
|
|
@@ -61,6 +64,9 @@ import { spawnSync } from "child_process";
|
|
|
61
64
|
*/
|
|
62
65
|
export const PLAN_DIR = "docs/adr";
|
|
63
66
|
|
|
67
|
+
/** A template cell an author has not filled in yet: `{outcome}`, `{blocked-by}`. */
|
|
68
|
+
const PLACEHOLDER = /^\{[a-z-]+\}$/;
|
|
69
|
+
|
|
64
70
|
/** The column whose cells are issue titles. The header spelling is the contract. */
|
|
65
71
|
export const TITLE_COLUMN = "Outcome";
|
|
66
72
|
|
|
@@ -184,11 +190,10 @@ export function plannedTitles(content: string): PlannedTitle[] {
|
|
|
184
190
|
* no Outcome column" are different states that must reset together, and two
|
|
185
191
|
* flags that must agree are two places to forget one. */
|
|
186
192
|
let table: { column: number | null } | null = null;
|
|
187
|
-
/** The
|
|
188
|
-
let fence:
|
|
193
|
+
/** The fence we are inside, or `null`. The grammar is `lib/markdown-fence.ts`'s (#2130). */
|
|
194
|
+
let fence: FenceOpening | null = null;
|
|
189
195
|
/** Whether we are inside a `<!-- … -->` that spans lines. */
|
|
190
196
|
let commented = false;
|
|
191
|
-
const opener = /^[ \t]*(`{3,}|~{3,})(.*)$/;
|
|
192
197
|
for (let i = 0; i < lines.length; i++) {
|
|
193
198
|
// Every region below also ENDS the table it interrupts, the same way a
|
|
194
199
|
// line of prose does, so `column` is reset on every one of their lines.
|
|
@@ -203,18 +208,11 @@ export function plannedTitles(content: string): PlannedTitle[] {
|
|
|
203
208
|
// That direction only DENIES, but it denies a plan a reviewer merged and
|
|
204
209
|
// the `why` would not say so. Found by the AI review of this change.
|
|
205
210
|
if (fence !== null) {
|
|
206
|
-
const c = indent(lines[i]) <= 3 ? opener.exec(lines[i]) : null;
|
|
207
211
|
// Only the same marker, at least as long, AND nothing after it. A ```
|
|
208
212
|
// inside a ~~~ block is content; so is ```js inside a ```md block,
|
|
209
|
-
// which is the differential a bare marker test would miss.
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
c[1][0] === fence[0] &&
|
|
213
|
-
c[1].length >= fence.length &&
|
|
214
|
-
c[2].trim() === ""
|
|
215
|
-
) {
|
|
216
|
-
fence = null;
|
|
217
|
-
}
|
|
213
|
+
// which is the differential a bare marker test would miss. Four or
|
|
214
|
+
// more leading spaces is indented code here, so it never closes.
|
|
215
|
+
if (indent(lines[i]) <= 3 && closesFence(lines[i], fence)) fence = null;
|
|
218
216
|
table = null;
|
|
219
217
|
continue;
|
|
220
218
|
}
|
|
@@ -234,13 +232,14 @@ export function plannedTitles(content: string): PlannedTitle[] {
|
|
|
234
232
|
const text = line.text;
|
|
235
233
|
|
|
236
234
|
const ind = indent(text);
|
|
237
|
-
const f = ind <= 3 ?
|
|
235
|
+
const f = ind <= 3 ? fenceOpening(text) : null;
|
|
238
236
|
// Any marker run OPENS, info string or not — including the spellings
|
|
239
237
|
// CommonMark would reject as openers. That is deliberate: refusing to
|
|
240
238
|
// open leaves what follows live, and a reading this function is unsure
|
|
241
|
-
// about must not be the one that authorises.
|
|
239
|
+
// about must not be the one that authorises. `fenceOpening` keeps that
|
|
240
|
+
// property for every caller, and says so.
|
|
242
241
|
if (f !== null) {
|
|
243
|
-
fence = f
|
|
242
|
+
fence = f;
|
|
244
243
|
table = null;
|
|
245
244
|
continue;
|
|
246
245
|
}
|
|
@@ -280,7 +279,11 @@ export function plannedTitles(content: string): PlannedTitle[] {
|
|
|
280
279
|
}
|
|
281
280
|
if (table.column === null) continue;
|
|
282
281
|
const title = cells[table.column];
|
|
283
|
-
|
|
282
|
+
// **A `{placeholder}` is not a title** (security review of #2008).
|
|
283
|
+
// `docs/adr/TEMPLATE.md` keeps a live table so the decomposition parser
|
|
284
|
+
// can be tested against it, and its Outcome cell is `{outcome}`. Read as a
|
|
285
|
+
// title, that would exempt a filing nobody planned from the cap.
|
|
286
|
+
if (title !== undefined && title !== "" && !PLACEHOLDER.test(title)) out.push({ title, line: i + 1 });
|
|
284
287
|
}
|
|
285
288
|
return out;
|
|
286
289
|
}
|
|
@@ -293,8 +296,26 @@ export interface PlanSource {
|
|
|
293
296
|
show: (path: string) => string | null;
|
|
294
297
|
}
|
|
295
298
|
|
|
296
|
-
/**
|
|
297
|
-
|
|
299
|
+
/**
|
|
300
|
+
* `git`, reading the commit the REMOTE's `main` names and never the working
|
|
301
|
+
* tree or the local `origin/main` ref — #2095. The anchor is
|
|
302
|
+
* `remoteMainCommit` in `lib/config-loader.ts`. A plan an agent committed and
|
|
303
|
+
* pinned under a forged `origin/main` exempts nothing, because the remote
|
|
304
|
+
* never saw it.
|
|
305
|
+
*
|
|
306
|
+
* `anchorOf` lets the filing gate hand in the ONE reading it also gives the
|
|
307
|
+
* cap's config read, so a merge landing mid-filing cannot judge the plan
|
|
308
|
+
* exemption and the cap against two commits (review of #2140). Alone, it
|
|
309
|
+
* reads the remote itself. Either way it is resolved once, on first use, so a
|
|
310
|
+
* source nobody consults costs no network call. An anchor that cannot be read
|
|
311
|
+
* makes `list` and `show` `null`: could not read, never "no plans".
|
|
312
|
+
*/
|
|
313
|
+
export function gitSource(root: string, anchorOf: () => RemoteMain = () => remoteMainCommit(root)): PlanSource {
|
|
314
|
+
let anchor: RemoteMain | undefined;
|
|
315
|
+
const ref = (): string | null => {
|
|
316
|
+
anchor ??= anchorOf();
|
|
317
|
+
return "sha" in anchor ? anchor.sha : null;
|
|
318
|
+
};
|
|
298
319
|
const git = (args: string[]): string | null => {
|
|
299
320
|
const r = spawnSync("git", ["-C", root, ...args], {
|
|
300
321
|
encoding: "utf-8",
|
|
@@ -328,13 +349,18 @@ export function gitSource(root: string, ref: string = "origin/main"): PlanSource
|
|
|
328
349
|
* ways on 2026-10-29; found by the AI review of this change.
|
|
329
350
|
*/
|
|
330
351
|
list: () => {
|
|
352
|
+
const sha = ref();
|
|
353
|
+
if (sha === null) return null;
|
|
331
354
|
const out = git([
|
|
332
|
-
"ls-tree", "-r", "--full-name", "--name-only",
|
|
355
|
+
"ls-tree", "-r", "--full-name", "--name-only", sha, "--", `:(top)${PLAN_DIR}/`,
|
|
333
356
|
]);
|
|
334
357
|
if (out === null) return null;
|
|
335
358
|
return out.split("\n").map(s => s.trim()).filter(s => s.endsWith(".md"));
|
|
336
359
|
},
|
|
337
|
-
show: path =>
|
|
360
|
+
show: path => {
|
|
361
|
+
const sha = ref();
|
|
362
|
+
return sha === null ? null : git(["show", `${sha}:${path}`]);
|
|
363
|
+
},
|
|
338
364
|
};
|
|
339
365
|
}
|
|
340
366
|
|
package/lib/finding-arbiter.ts
CHANGED
|
@@ -564,11 +564,62 @@ export const DUPLICATE_MIN_SHARED_LOCATIONS = 1;
|
|
|
564
564
|
* deleting: a measurement that names a mechanism it never varied will read
|
|
565
565
|
* as settled for as long as nobody varies it.
|
|
566
566
|
*
|
|
567
|
-
* **The 946-pair table above is not reproducible.** It was
|
|
568
|
-
* against a tracker that has moved and no corpus was stored
|
|
569
|
-
*
|
|
570
|
-
*
|
|
571
|
-
*
|
|
567
|
+
* **The 946-pair table above is not reproducible, and never will be.** It was
|
|
568
|
+
* measured live against a tracker that has moved and no corpus was stored.
|
|
569
|
+
* Those 44 findings are gone; #1365 did not recover them and nothing here
|
|
570
|
+
* claims it did. Treat every number above this line as a reading someone took
|
|
571
|
+
* once.
|
|
572
|
+
*
|
|
573
|
+
* ## WHAT IS REPRODUCIBLE, FROM HERE ON (#1365)
|
|
574
|
+
*
|
|
575
|
+
* A corpus is now frozen in `test/fixtures/finding-dedupe-corpus.json` — the
|
|
576
|
+
* fourteen findings these docblocks name inside a PAIR or a CLUSTER, fetched
|
|
577
|
+
* once by `scripts/freeze-dedupe-corpus.ts` and committed. The table below is
|
|
578
|
+
* the stdout of `bun scripts/print-dedupe-pair-table.ts` over that fixture,
|
|
579
|
+
* and `test/dedupe-corpus-table.test.ts` fails when the two differ. So it is
|
|
580
|
+
* a command's output rather than a reading, and it cannot go stale quietly.
|
|
581
|
+
*
|
|
582
|
+
* **Membership is checked, not asserted.** Each of the fourteen carries the
|
|
583
|
+
* sentence from THIS file that admits it, and
|
|
584
|
+
* `test/dedupe-corpus-membership.test.ts` refuses an id whose sentence is
|
|
585
|
+
* absent, does not name it, or lies inside the generated block below — so a
|
|
586
|
+
* member can never be justified by the table its own membership produced.
|
|
587
|
+
*
|
|
588
|
+
* <!-- BEGIN dedupe-pair-table -->
|
|
589
|
+
* Corpus: 14 findings, 91 pairs, frozen 2026-11-07.
|
|
590
|
+
* Regenerate with `bun scripts/print-dedupe-pair-table.ts`.
|
|
591
|
+
*
|
|
592
|
+
* | rule | pairs | which |
|
|
593
|
+
* |---|---|---|
|
|
594
|
+
* | `qty>=2 AND loc>=1` | 1 | 1176/1187 |
|
|
595
|
+
* | containment >= 0.6 | 3 | 1175/1177, 1195/1196, 1454/1456 |
|
|
596
|
+
* | containment >= 0.8 (shipped) | 3 | 1175/1177, 1195/1196, 1454/1456 |
|
|
597
|
+
* | either arm — what the arbiter calls DUPLICATE | 4 | 1175/1177, 1176/1187, 1195/1196, 1454/1456 |
|
|
598
|
+
*
|
|
599
|
+
* Findings under the floor of 4 identity keys, which the containment arm scores 0 against everything: #1239.
|
|
600
|
+
* <!-- END dedupe-pair-table -->
|
|
601
|
+
*
|
|
602
|
+
* ### Four claims above reproduce. One does not.
|
|
603
|
+
*
|
|
604
|
+
* Reproduced exactly, against the live bodies: #1175/#1177 at 1.000 and
|
|
605
|
+
* #1454/#1456 at 0.900 and #1195/#1196 at **0.833**, and #1195/#1239 scoring
|
|
606
|
+
* **0.000** because #1239 carries three identity keys and sits under the
|
|
607
|
+
* floor. That is the whole of the #1536 table, re-derived from a fixture.
|
|
608
|
+
*
|
|
609
|
+
* **The `qty>=2 AND loc>=1` row does not.** It reads *4 — 1175/1177,
|
|
610
|
+
* 1195/1196, 1269/1286, 1162/1226*; over the frozen corpus that arm flags
|
|
611
|
+
* **one** pair, and the pair is #1176/#1187 — the shape this file already
|
|
612
|
+
* names as the one it cannot tell from a duplicate, since #1187 quotes other
|
|
613
|
+
* findings' readings because it is *about* them.
|
|
614
|
+
*
|
|
615
|
+
* **This is a failure to reproduce, not a demonstration that the row was
|
|
616
|
+
* false.** The fixture holds the bodies as the tracker had them on the freeze
|
|
617
|
+
* date, and an issue body is editable: six of these fourteen were closed and
|
|
618
|
+
* several edited in the weeks between. What can be said is the thing #1365
|
|
619
|
+
* exists to make sayable at all — *the row cannot be checked against anything,
|
|
620
|
+
* and the arm it justifies is the one tuned on the corpus that was lost.*
|
|
621
|
+
* Neither constant is moved on this reading; a re-tune needs a corpus
|
|
622
|
+
* collected for the purpose, which is a different issue from freezing one.
|
|
572
623
|
*
|
|
573
624
|
* The floor exists because containment is meaningless on a tiny key set — a
|
|
574
625
|
* one-key finding is wholly contained in anything mentioning that key, which
|
|
@@ -857,6 +908,29 @@ export type ArbiterRefusal =
|
|
|
857
908
|
* answer at all and refuses, naming the path so an operator can act.
|
|
858
909
|
*/
|
|
859
910
|
| "UNMEASURED_CAP"
|
|
911
|
+
/**
|
|
912
|
+
* The body is short a section the issue form requires (#1741).
|
|
913
|
+
*
|
|
914
|
+
* **The last stage, and it converts an ALLOW only.** Everything before it
|
|
915
|
+
* asks whether this should be on the tracker at all; this one asks whether
|
|
916
|
+
* what is about to land on the tracker is readable by the things that read
|
|
917
|
+
* it. An issue naming no files cannot be checked against rule 2, cannot be
|
|
918
|
+
* scanned for the file-overlap conflicts that put four agents on
|
|
919
|
+
* `lib/bash-write-guard.ts`, and cannot tell a picker what they are picking
|
|
920
|
+
* up.
|
|
921
|
+
*
|
|
922
|
+
* **Waivable, and deliberately so.** Unlike the three above, this one IS a
|
|
923
|
+
* claim about the filing — it says a named section is absent, which is a
|
|
924
|
+
* fact the agent can refute by adding it or override when they genuinely
|
|
925
|
+
* mean to file a stub. A count takes no argument; a shape does.
|
|
926
|
+
*
|
|
927
|
+
* The sections come from `requiredSections` in `lib/issue-shape.ts`, which
|
|
928
|
+
* is the same decider the two issue forms and `plan-issues --decompose`
|
|
929
|
+
* read. That is the whole of #1741: before it, a gate requiring the form's
|
|
930
|
+
* fields would have refused every row of every decomposed plan, because
|
|
931
|
+
* the generator emitted two of the five.
|
|
932
|
+
*/
|
|
933
|
+
| "MALFORMED"
|
|
860
934
|
/** Something could not be evaluated. Fails; never skips. */
|
|
861
935
|
| "UNMEASURED";
|
|
862
936
|
|
package/lib/finding-jury.ts
CHANGED
|
@@ -210,7 +210,10 @@ export function classifyCategory(finding: Pick<Finding, "title" | "body">): Find
|
|
|
210
210
|
// ── Severity ─────────────────────────────────────────────────────────────
|
|
211
211
|
|
|
212
212
|
/**
|
|
213
|
-
*
|
|
213
|
+
* How an ai-review tag SORTS. Three of its members are also the three tags
|
|
214
|
+
* the source design posts; `Unobserved` (#1879) is a fourth that no
|
|
215
|
+
* verifier votes — `JURY_VOTE_SEVERITIES` below is the set that answers
|
|
216
|
+
* that question, and this one is allowed to be wider.
|
|
214
217
|
*
|
|
215
218
|
* `Pre-existing` is the one that matters most here and the one we had no way
|
|
216
219
|
* to say: a finding about code the change never touched is not the author's
|
|
@@ -236,6 +239,32 @@ export function classifyCategory(finding: Pick<Finding, "title" | "body">): Find
|
|
|
236
239
|
export { SEVERITY_RANK };
|
|
237
240
|
export type { Severity };
|
|
238
241
|
|
|
242
|
+
/**
|
|
243
|
+
* What a VERIFIER may vote, which is not the same question as how a tag
|
|
244
|
+
* sorts — #1914 round 3.
|
|
245
|
+
*
|
|
246
|
+
* `SEVERITY_RANK` was doing both jobs, and they coincided only because the
|
|
247
|
+
* two sets happened to be equal. #1879 added `Unobserved` to the sort,
|
|
248
|
+
* because an ai-review annotation needs somewhere to put a finding whose
|
|
249
|
+
* claim nothing ran to produce; `parseVotes` validated against the same
|
|
250
|
+
* table, so a verifier vote declaring `severity: "Unobserved"` silently
|
|
251
|
+
* became legal, could win `severityOf`'s majority, and would be
|
|
252
|
+
* interpolated into a posted comment as a word this module defines no
|
|
253
|
+
* meaning for. Nothing prompts a verifier with it today — but the guard
|
|
254
|
+
* had stopped being able to refuse it, which is the shape
|
|
255
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` is about.
|
|
256
|
+
*
|
|
257
|
+
* So the two questions get two lists. This one is CLOSED: a verifier
|
|
258
|
+
* assigns the author a severity, and `Unobserved` is not something a
|
|
259
|
+
* verifier observes — it is a statement about the review job, not about
|
|
260
|
+
* the finding's magnitude.
|
|
261
|
+
*
|
|
262
|
+
* `test/finding-jury.test.ts` asserts every member is a key of
|
|
263
|
+
* `SEVERITY_RANK`, so this list cannot drift to a tag that does not sort.
|
|
264
|
+
* The relation is one-way by design: the rank table may be wider.
|
|
265
|
+
*/
|
|
266
|
+
export const JURY_VOTE_SEVERITIES: readonly Severity[] = ["Important", "Nit", "Pre-existing"];
|
|
267
|
+
|
|
239
268
|
// ── The vote ─────────────────────────────────────────────────────────────
|
|
240
269
|
|
|
241
270
|
export interface VerifierVote {
|
|
@@ -314,7 +343,9 @@ function shapeOf(value: unknown): string {
|
|
|
314
343
|
* two of the others carry the same defect. An unrecognised `category` is not
|
|
315
344
|
* in `DROPPED_CATEGORIES`, so it reads to `juryCategory` as a keep category.
|
|
316
345
|
* An unrecognised `severity` indexes `SEVERITY_RANK` to `undefined`, making
|
|
317
|
-
* the sort comparator in `severityOf` return `NaN`.
|
|
346
|
+
* the sort comparator in `severityOf` return `NaN`. It is checked against
|
|
347
|
+
* `JURY_VOTE_SEVERITIES` rather than against that table — see there for why
|
|
348
|
+
* the two are different questions (#1914 round 3).
|
|
318
349
|
*
|
|
319
350
|
* **`Object.hasOwn`, never the `in` operator**, and this is not a style
|
|
320
351
|
* preference. `in` walks the prototype chain, so `"constructor" in
|
|
@@ -357,10 +388,18 @@ export function parseVotes(parsed: unknown): readonly VerifierVote[] {
|
|
|
357
388
|
`an unrecognised category is not a dropped one, so it would read as a keep — ${UNREADABLE_VOTE}`,
|
|
358
389
|
);
|
|
359
390
|
}
|
|
360
|
-
|
|
391
|
+
// #1914 round 3: `JURY_VOTE_SEVERITIES`, not `SEVERITY_RANK`. The rank
|
|
392
|
+
// table answers how a tag SORTS and is allowed to be wider than what a
|
|
393
|
+
// verifier may vote; validating against it made every new ai-review tag
|
|
394
|
+
// a legal vote by accident. `includes` over a frozen list rather than
|
|
395
|
+
// `Object.hasOwn`, so there is no prototype chain to walk at all.
|
|
396
|
+
if (
|
|
397
|
+
v.severity !== undefined &&
|
|
398
|
+
!(typeof v.severity === "string" && JURY_VOTE_SEVERITIES.includes(v.severity as Severity))
|
|
399
|
+
) {
|
|
361
400
|
throw new Error(
|
|
362
401
|
`${where}, from \`${v.verifier}\`, names an unknown \`severity\` (${shapeOf(v.severity)}): ` +
|
|
363
|
-
`
|
|
402
|
+
`a verifier may vote ${JURY_VOTE_SEVERITIES.join(", ")} and nothing else — ${UNREADABLE_VOTE}`,
|
|
364
403
|
);
|
|
365
404
|
}
|
|
366
405
|
return {
|