rungate 0.8.13 → 0.8.14
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 +82 -0
- package/gates/.gate-salt +1 -1
- package/hooks/VerifyPhaseLock.hook.ts +3 -3
- package/lib/ai-review-rounds.ts +99 -0
- package/lib/ai-review-suppression.ts +200 -21
- package/lib/bash-write-guard.ts +50 -5
- package/lib/board-flow.ts +235 -0
- package/lib/board-lane-health.ts +381 -0
- package/lib/board-mirror.ts +53 -35
- package/lib/board-ready-fanout.ts +56 -13
- package/lib/board-ready-rule.ts +545 -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/conformity.ts +95 -2
- package/lib/filing-compliance.ts +367 -0
- package/lib/finding-arbiter.ts +79 -5
- package/lib/generators/agents-md.ts +149 -0
- package/lib/github.ts +79 -0
- package/lib/graphql-cursor.ts +80 -0
- package/lib/issue-create-override.ts +415 -3
- package/lib/issue-decomposition.ts +33 -3
- package/lib/issue-file-overlap.ts +340 -0
- package/lib/issue-filing-gate.ts +173 -8
- package/lib/issue-repair.ts +13 -9
- package/lib/issue-shape.ts +196 -0
- package/lib/scaffold/ai-review-findings.ts +9 -1
- package/lib/scaffold/ai-review-step.ts +35 -1
- package/lib/source-census.ts +108 -0
- package/lib/spec-deps.ts +34 -11
- package/lib/spec-placement.ts +108 -0
- package/lib/stage-ladder.ts +28 -3
- package/lib/work-status.ts +423 -0
- package/package.json +1 -1
- package/scripts/ai-review-findings.ts +8 -13
- package/scripts/ai-review-threads.ts +16 -17
- package/scripts/board-mirror.ts +221 -8
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/plan-spec.ts +79 -1
|
@@ -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/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
|
|
|
@@ -696,5 +696,154 @@ Check the claim against the repo before you build on it.
|
|
|
696
696
|
`,
|
|
697
697
|
});
|
|
698
698
|
|
|
699
|
+
// #1742 — a consumer that cannot report what it found upstream has not
|
|
700
|
+
// been supported, it has been shipped to. Measured 2026-11-03: the
|
|
701
|
+
// `from-consumer` label did not exist among 23 labels, no milestone was a
|
|
702
|
+
// triage lane among 18, and there was no rule. Consumers reached for
|
|
703
|
+
// `external-audit` — the label Jason's decision (c) ruled out — and
|
|
704
|
+
// fifteen open issues carry it.
|
|
705
|
+
//
|
|
706
|
+
// **Inline here, like every other rule, and NOT in a module of its own.**
|
|
707
|
+
// #1742's file list predicted `lib/scaffold/reporting-upstream.ts`; that
|
|
708
|
+
// shape was built and withdrawn, because `test/harness-fixed-point.test.ts`
|
|
709
|
+
// copies this generator into an `mkdtemp` tree and the new import died
|
|
710
|
+
// there with `Cannot find module`. That is Tier 1 of
|
|
711
|
+
// `.claude/rules/self-referential-tests.md` exactly — and a battery whose
|
|
712
|
+
// mutant fails to load goes GREEN while witnessing nothing, so the cheap
|
|
713
|
+
// fix of teaching the copier one more path buys a second thing to keep in
|
|
714
|
+
// step. Every other rule in this file is inline; so is this one.
|
|
715
|
+
//
|
|
716
|
+
// **Path-scoped to `package.json`, and the scope is forced twice over.**
|
|
717
|
+
// `scripts/check-instruction-surface.ts` read 258 bytes of headroom under
|
|
718
|
+
// the 64,000-byte budget, so an unscoped rule reddens
|
|
719
|
+
// `.claude/agents/aditi.md` — a file with nothing to do with reporting
|
|
720
|
+
// upstream. A scoped rule is billed against every file its globs match,
|
|
721
|
+
// and `harness-managed.md` already claims `AGENTS.md`, both workflows,
|
|
722
|
+
// `.claude/agents/**`, `.claude/rules/**`, `CODE-MAP.md` and
|
|
723
|
+
// `test/scaffold-conformity.test.ts` — a second rule on any of those sums
|
|
724
|
+
// with it and goes over. The harness config directory was the first
|
|
725
|
+
// choice and CONFIG-1 refuses it: a config path spelled in a string is a
|
|
726
|
+
// direct access site, which is the same trap `STEPS_NOT_MINIMAL` in
|
|
727
|
+
// `lib/scaffold/profiles.ts` describes in its own comment.
|
|
728
|
+
//
|
|
729
|
+
// `package.json` is what is left, and the first version of this comment
|
|
730
|
+
// justified it with "it holds the `rungate` dependency entry, which is the
|
|
731
|
+
// version this rule tells the reporter to quote." **That was false**, and
|
|
732
|
+
// the AI review of #1813 said so: this repository's own `package.json` is
|
|
733
|
+
// `"name": "rungate"` with a top-level `version`, no such entry — and a
|
|
734
|
+
// workspace-linked consumer's entry is a path, not a version.
|
|
735
|
+
//
|
|
736
|
+
// The scope stands on the honest reading instead. `package.json` is the
|
|
737
|
+
// file that answers *what is rungate to this project* — a dependency, a
|
|
738
|
+
// link, or the project itself — and that is precisely the question an
|
|
739
|
+
// agent is holding when it needs this rule. The rule now enumerates all
|
|
740
|
+
// three and says UNMEASURED when none resolves.
|
|
741
|
+
//
|
|
742
|
+
// **No `isHarnessItself` branch**, which is where the review's own fix
|
|
743
|
+
// pointed. It catches rungate's own repo and NOT the workspace-linked
|
|
744
|
+
// consumer the review named in the same paragraph, so it closes one of
|
|
745
|
+
// the two cases and reads as if it closed both — the shape #1810 spent
|
|
746
|
+
// three rounds on, each repair loosening the branch the next one arrived
|
|
747
|
+
// through. Prose covering every case has no branch to drift, and
|
|
748
|
+
// `test/gen-agents-md.test.ts` asserts the harness and a consumer get
|
|
749
|
+
// byte-identical content so none can be added without being noticed.
|
|
750
|
+
//
|
|
751
|
+
// Emitted into EVERY profile, including minimal. `RULES_NOT_MINIMAL`
|
|
752
|
+
// excludes a rule naming machinery the profile did not install, and this
|
|
753
|
+
// one names a tracker that exists either way — a minimal consumer is if
|
|
754
|
+
// anything the likeliest to hit something and have nowhere to put it.
|
|
755
|
+
rules.push({
|
|
756
|
+
filename: "reporting-upstream.md",
|
|
757
|
+
content: `---
|
|
758
|
+
description: How to report a problem you found in rungate itself, from this repository
|
|
759
|
+
paths:
|
|
760
|
+
- "package.json"
|
|
761
|
+
---
|
|
762
|
+
|
|
763
|
+
## You found something in rungate, not in this project
|
|
764
|
+
|
|
765
|
+
File it on **hornjason/rungate**, not here, and not as a code comment that
|
|
766
|
+
nobody upstream reads.
|
|
767
|
+
|
|
768
|
+
\`\`\`bash
|
|
769
|
+
gh issue create --repo hornjason/rungate \\
|
|
770
|
+
--label from-consumer \\
|
|
771
|
+
--title "<the symptom, not the fix>" \\
|
|
772
|
+
--body-file <a file you wrote FIRST, in a separate command>
|
|
773
|
+
\`\`\`
|
|
774
|
+
|
|
775
|
+
## Show the body to your user before you send it
|
|
776
|
+
|
|
777
|
+
**hornjason/rungate is somebody else's repository, and its issues are
|
|
778
|
+
public.** Filing there publishes whatever you wrote, permanently — a
|
|
779
|
+
deletion later does not un-cache or un-index it. So the body is not yours to
|
|
780
|
+
send on your own judgement: write the file, show it to your user, and send
|
|
781
|
+
it only once they have said yes.
|
|
782
|
+
|
|
783
|
+
What goes in it is the **smallest thing that reproduces the problem**, and
|
|
784
|
+
nothing else:
|
|
785
|
+
|
|
786
|
+
- a reproducer you constructed, never a paste of this project's source,
|
|
787
|
+
config, logs, stack traces, test output or data
|
|
788
|
+
- paths only where the path IS the symptom — and say so
|
|
789
|
+
- no credentials, tokens, keys, internal hostnames, URLs or customer data,
|
|
790
|
+
including inside a quoted error message
|
|
791
|
+
|
|
792
|
+
If you cannot describe the problem without one of those, that is the thing
|
|
793
|
+
to tell your user. It is not a reason to send it anyway.
|
|
794
|
+
|
|
795
|
+
## The label is \`from-consumer\`, and it is not \`external-audit\`
|
|
796
|
+
|
|
797
|
+
\`external-audit\` means *rungate audited something else*. A consumer report
|
|
798
|
+
is the opposite direction, and conflating them is how a report from a real
|
|
799
|
+
user lands in a queue nobody triages as user feedback.
|
|
800
|
+
|
|
801
|
+
If \`from-consumer\` does not exist on the repository, say so in the body
|
|
802
|
+
rather than substituting the nearest label. A label chosen because it was
|
|
803
|
+
available is a routing decision nobody made.
|
|
804
|
+
|
|
805
|
+
## What the body must carry
|
|
806
|
+
|
|
807
|
+
The three sections every issue there needs. No criterion id — you cannot
|
|
808
|
+
know one from here and you are not expected to:
|
|
809
|
+
|
|
810
|
+
- **What must become true** — the symptom, with the numbers you measured
|
|
811
|
+
- **Files this will change** — if you know; *unknown* is an honest answer
|
|
812
|
+
- **How we will know** — what you would run to see it fixed
|
|
813
|
+
|
|
814
|
+
**Say which version of rungate you are on, and how you know.** A report
|
|
815
|
+
against a version nobody can identify cannot be reproduced, and will be
|
|
816
|
+
closed as such.
|
|
817
|
+
|
|
818
|
+
Where that number lives depends on how rungate reached this project, and
|
|
819
|
+
there is no one key to read:
|
|
820
|
+
|
|
821
|
+
- a declared dependency — the \`rungate\` entry under \`dependencies\` or
|
|
822
|
+
\`devDependencies\` in \`package.json\`
|
|
823
|
+
- a workspace or \`link:\` resolution — the entry is a path, not a version,
|
|
824
|
+
so read \`version\` out of the resolved package's own \`package.json\`
|
|
825
|
+
- **this project IS rungate** — then nothing below applies. There is no
|
|
826
|
+
upstream to report to: what you found is an ordinary issue on this
|
|
827
|
+
repository, and the version is the top-level \`version\` field.
|
|
828
|
+
|
|
829
|
+
If none of those resolves, write **UNMEASURED** and say which you tried.
|
|
830
|
+
Guessing a version is worse than not supplying one — it sends the
|
|
831
|
+
maintainers to the wrong tree.
|
|
832
|
+
|
|
833
|
+
## Do not open a pull request first
|
|
834
|
+
|
|
835
|
+
File the issue, link it, and wait for a reply. A pull request from a
|
|
836
|
+
consumer against a harness they do not own is expensive to review and
|
|
837
|
+
frequently solves the wrong half of the problem — the maintainers may
|
|
838
|
+
already know the cause.
|
|
839
|
+
|
|
840
|
+
## What belongs here instead
|
|
841
|
+
|
|
842
|
+
A problem in **this** project's own code, config or specs is an ordinary
|
|
843
|
+
issue on this repository. The test is simple: if deleting rungate would
|
|
844
|
+
make the problem go away it is upstream, and if it would not it is yours.
|
|
845
|
+
`,
|
|
846
|
+
});
|
|
847
|
+
|
|
699
848
|
return rules;
|
|
700
849
|
}
|