rungate 0.8.2 → 0.8.3
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/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +11 -0
package/lib/finding-arbiter.ts
CHANGED
|
@@ -142,6 +142,16 @@ export const UNFILED_ID = "new";
|
|
|
142
142
|
|
|
143
143
|
export type SymptomKeyKind = "sym" | "file" | "qty";
|
|
144
144
|
|
|
145
|
+
/**
|
|
146
|
+
* A quantity key, `qty:<n>:<what was counted>`.
|
|
147
|
+
*
|
|
148
|
+
* Its own type because it is **not** a symptom key since #1536: it answers
|
|
149
|
+
* "did these two take the same reading?", which is a different question from
|
|
150
|
+
* "are these two the same finding?", and only the second belongs in an
|
|
151
|
+
* identity. See `quantityKeys`.
|
|
152
|
+
*/
|
|
153
|
+
export type QuantityKeyKind = "qty";
|
|
154
|
+
|
|
145
155
|
/** How many cited symbols the branch-scope reading will pay a `git grep` for. */
|
|
146
156
|
const MAX_SYMBOLS_PROBED = 8;
|
|
147
157
|
|
|
@@ -218,27 +228,115 @@ function pathsIn(body: string): string[] {
|
|
|
218
228
|
}
|
|
219
229
|
|
|
220
230
|
/**
|
|
221
|
-
*
|
|
231
|
+
* Readings a finding reports, each as `<n>:<what it counted>`.
|
|
232
|
+
*
|
|
233
|
+
* ## A BARE INTEGER IS NOT A SYMPTOM (#1536)
|
|
234
|
+
*
|
|
235
|
+
* This emitted the integer alone, and the integer alone cannot say whether
|
|
236
|
+
* `19` is a line number, a count of check names or a byte figure. Two
|
|
237
|
+
* measured false `DUPLICATE`s on 2026-10-24, both overridden after a human
|
|
238
|
+
* read the issue the refusal named:
|
|
239
|
+
*
|
|
240
|
+
* | refused | called a duplicate of | on |
|
|
241
|
+
* |---|---|---|
|
|
242
|
+
* | #1520 instruction-surface headroom | #1506 reservation protocol | `qty:20`, `qty:99` + one path |
|
|
243
|
+
* | #1534 clean arm's banked reading | #1162 findings discarded four ways | `qty:19`, `qty:22`, `qty:28` + one symbol |
|
|
244
|
+
*
|
|
245
|
+
* In #1534 the three integers are LINE NUMBERS — *"the clean arm changes
|
|
246
|
+
* 7–11, 22, 25, 28"* — and in #1162 they are counts: *"19 distinct check
|
|
247
|
+
* names"*, *"22 times"*, *"28 carrying refusals"*. Nothing the old key
|
|
248
|
+
* carried could tell those apart, so any issue quoting a measurement
|
|
249
|
+
* collided with any other issue quoting a measurement.
|
|
250
|
+
*
|
|
251
|
+
* So the key carries **the word the number qualifies**: the token
|
|
252
|
+
* immediately after it, joined by one space or one hyphen. `19 violations`
|
|
253
|
+
* is a reading; `19` followed by a comma, a full stop or a line end is a
|
|
254
|
+
* position in a list and emits nothing. No stopword list and no second
|
|
255
|
+
* threshold — a number with nothing naming what it counted is simply not a
|
|
256
|
+
* key, which is the one direction this function is allowed to be wrong in.
|
|
257
|
+
*
|
|
258
|
+
* Measured over a 103-issue live corpus (43 open + the 60 most recent
|
|
259
|
+
* closed) on 2026-10-24, 5,253 pairs, before and after — together with
|
|
260
|
+
* moving these keys out of the identity set, which is the other half of the
|
|
261
|
+
* change and cannot be measured apart from it:
|
|
262
|
+
*
|
|
263
|
+
* | | pairs flagged | byte-identical re-filings refused |
|
|
264
|
+
* |---|---|---|
|
|
265
|
+
* | before | 6 — **4 of them false** | 96/103 |
|
|
266
|
+
* | after | **3** — all four false pairs gone | 93/103 |
|
|
267
|
+
*
|
|
268
|
+
* Both true duplicates on that corpus survive (#1456/#1454 at 0.900,
|
|
269
|
+
* #1409/#1406 at 1.000) and one new pair appears: **#1394/#1353**, two
|
|
270
|
+
* ai-review ledger defects in one file at containment exactly 0.800. It is
|
|
271
|
+
* named here rather than tuned away, the way this file names the rest of
|
|
272
|
+
* its false positives — the refusal is reviewable and `arbiter-override`
|
|
273
|
+
* waives it.
|
|
274
|
+
*
|
|
275
|
+
* The price, stated: ten findings carrying one to three location keys
|
|
276
|
+
* (#1492, #1395, #1341, #1167, #1160, #1157, #1437, #1426, #1413, #1412)
|
|
277
|
+
* reached the floor only through bare integers and can now be re-filed
|
|
278
|
+
* byte-identically. A duplicate that gets filed is a tracker row somebody
|
|
279
|
+
* closes; a false `DUPLICATE` silences a finding. The asymmetry this file
|
|
280
|
+
* argues everywhere else is what chooses the direction.
|
|
222
281
|
*
|
|
223
|
-
* The exclusions are what make this a measurement
|
|
224
|
-
* reference (`#1188`), an SC or AC id, a date
|
|
225
|
-
* ten. Without the first of those, every
|
|
226
|
-
* issue collides with every other — which
|
|
227
|
-
* graph, not of the defect.
|
|
282
|
+
* The other exclusions are unchanged and are what make this a measurement
|
|
283
|
+
* and not a number: an issue reference (`#1188`), an SC or AC id, a date
|
|
284
|
+
* component, and anything under ten. Without the first of those, every
|
|
285
|
+
* finding that cites the same prior issue collides with every other — which
|
|
286
|
+
* is a reading of the cross-reference graph, not of the defect.
|
|
228
287
|
*/
|
|
229
|
-
function quantitiesIn(body: string):
|
|
230
|
-
const out:
|
|
288
|
+
function quantitiesIn(body: string): string[] {
|
|
289
|
+
const out: string[] = [];
|
|
231
290
|
// Blank out the shapes whose digits are identifiers rather than readings,
|
|
232
291
|
// keeping the length so no two tokens are glued together by the removal.
|
|
233
292
|
const masked = body
|
|
293
|
+
// Emphasis first, and to a SPACE so lengths still hold. `**144** rows`
|
|
294
|
+
// and `144 rows` are the same reading written twice, and a qualifier the
|
|
295
|
+
// author happened to bold away would be the second shape in
|
|
296
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` — a detector narrower
|
|
297
|
+
// than what it detects, defeated by a reformat.
|
|
298
|
+
.replace(/\*/g, " ")
|
|
234
299
|
.replace(/#\d+/g, m => " ".repeat(m.length))
|
|
235
300
|
.replace(/\b(?:SC|AC|PR|H|R)-?\d+/gi, m => " ".repeat(m.length))
|
|
236
301
|
.replace(/\d{4}-\d{2}-\d{2}(?:T[\d:.]+Z?)?/g, m => " ".repeat(m.length))
|
|
302
|
+
// Before the `:\d+` rule, not after (#1333). That rule takes the minutes
|
|
303
|
+
// and leaves the hour, so by the time a later rule ran there would be no
|
|
304
|
+
// clock time left to see — `15:24` scored `qty:15`, the same key a
|
|
305
|
+
// genuine reading of 15 produces. Colon-joined numbers are a time or a
|
|
306
|
+
// ratio far more often than two independent readings, and masking both
|
|
307
|
+
// is the direction this function is allowed to be wrong in: a key it
|
|
308
|
+
// declines to emit cannot make two unrelated findings agree.
|
|
309
|
+
// ## The boundaries are lookarounds, NOT `\b` (#1385)
|
|
310
|
+
//
|
|
311
|
+
// This shipped as `/\b\d{1,2}:\d{2}(?::\d{2})?\b/` and the trailing `\b`
|
|
312
|
+
// is the bug: it needs a NON-word character after the match, and a UTC
|
|
313
|
+
// `Z` is a word character. So `19:05Z` did not match, the `:\d+` rule
|
|
314
|
+
// below then ate `:05`, and the hour survived as `qty:19` — the exact
|
|
315
|
+
// defect #1333 was filed about, surviving #1333's fix.
|
|
316
|
+
//
|
|
317
|
+
// It had a live instance. `#1226` says "registry served 0.8.1 at roughly
|
|
318
|
+
// 19:05Z" and `#1162` says "19 distinct check names"; that collision was
|
|
319
|
+
// one of only two cross-issue duplicate pairs the arbiter produced on the
|
|
320
|
+
// open corpus, and closing it drops the pair below the quantity floor.
|
|
321
|
+
//
|
|
322
|
+
// `(?<![\d:])` refuses to start mid-number, so the `48` of `15:48:30`
|
|
323
|
+
// cannot begin a second match. `(?!\d)` refuses to stop mid-number but
|
|
324
|
+
// allows a letter, which is the whole fix.
|
|
325
|
+
.replace(/(?<![\d:])\d{1,2}:\d{2}(?::\d{2})?(?!\d)/g, m => " ".repeat(m.length))
|
|
237
326
|
.replace(/:\d+/g, m => " ".repeat(m.length))
|
|
238
327
|
.replace(/\bv?\d+\.\d+(?:\.\d+)?/g, m => " ".repeat(m.length));
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
328
|
+
// The qualifier is whatever word the number runs into, with no vocabulary
|
|
329
|
+
// of accepted units: a list of units is a list somebody has to maintain,
|
|
330
|
+
// and one that is missing a word silently drops a real reading. Two
|
|
331
|
+
// findings agreeing on `144:of` agree on more than two findings agreeing
|
|
332
|
+
// on `144`, which is the entire claim.
|
|
333
|
+
// `[ -]+` and not `[ -]`: the emphasis mask above turns `**144** rows`
|
|
334
|
+
// into two spaces, and a reading that depended on how many spaces the
|
|
335
|
+
// author's markdown left behind would be the second shape in
|
|
336
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` all over again.
|
|
337
|
+
for (const m of masked.matchAll(/\b(\d[\d,]*)[ -]+([A-Za-z]+)/g)) {
|
|
338
|
+
const n = Number.parseInt(m[1].replace(/,/g, ""), 10);
|
|
339
|
+
if (Number.isFinite(n) && n >= 10) out.push(`${n}:${m[2].toLowerCase()}`);
|
|
242
340
|
}
|
|
243
341
|
return out;
|
|
244
342
|
}
|
|
@@ -246,31 +344,94 @@ function quantitiesIn(body: string): number[] {
|
|
|
246
344
|
/**
|
|
247
345
|
* The keys a finding is deduplicated on.
|
|
248
346
|
*
|
|
347
|
+
* ## What the key set is FOR, and why quantities are no longer in it (#1536)
|
|
348
|
+
*
|
|
349
|
+
* It answers one question and no other: **would these two findings be
|
|
350
|
+
* closed by the same change?** Every admission rule below follows from that
|
|
351
|
+
* and from nothing else. A `sym:` or `file:` key names something a fix would
|
|
352
|
+
* edit — which is why a bare lowercase word is not a symbol and an unsnaked
|
|
353
|
+
* all-caps token is not either: `CLEAN` and `dequote` name nothing anybody
|
|
354
|
+
* would change.
|
|
355
|
+
*
|
|
356
|
+
* **A measurement is not part of that identity.** A reading is evidence
|
|
357
|
+
* *about* a defect, and the same defect measured twice gives two numbers
|
|
358
|
+
* while two unrelated defects give one. That is not a claim from first
|
|
359
|
+
* principles; it is the shape of both false `DUPLICATE`s of 2026-10-24,
|
|
360
|
+
* which `quantitiesIn` records. So quantities moved out of this set and into
|
|
361
|
+
* `quantityKeys`, read by the one arm that asks about readings.
|
|
362
|
+
*
|
|
363
|
+
* That split is also what stopped the fix costing the pair this module was
|
|
364
|
+
* built on. Qualifying the quantity and leaving it here was tried first and
|
|
365
|
+
* **lost #1175/#1177**, whose containment fell from 1.000 to 0.417: the key
|
|
366
|
+
* sets grew, because prose repeats a number beside a different word each
|
|
367
|
+
* time, and a ratio whose denominator grows with prose is measuring prose.
|
|
368
|
+
* A reading could never have belonged in that denominator.
|
|
369
|
+
*
|
|
370
|
+
* This set is deliberately NOT a relevance score, not a topic model, and not
|
|
371
|
+
* an index: a key that merely says two findings are *about* the same area
|
|
372
|
+
* produces the `lib/bash-write-guard.ts` cluster, six distinct defects in
|
|
373
|
+
* one file that this rule exists to keep apart.
|
|
374
|
+
*
|
|
375
|
+
* What was measured and NOT adopted, so the next reader does not re-derive
|
|
376
|
+
* it: #1536 also asks whether a path or symbol appearing only as *cited
|
|
377
|
+
* evidence* — inside a blockquote, or in a table of candidates — should
|
|
378
|
+
* weigh as a subject. Both variants were run over the same 103-issue corpus.
|
|
379
|
+
* Excluding blockquote lines moved **nothing**: zero pairs, zero re-filings.
|
|
380
|
+
* Excluding table rows as well cost a TRUE duplicate — #1456/#1454 fell from
|
|
381
|
+
* 0.900 to 0.750 — because in this repository a table is where a finding
|
|
382
|
+
* states its own fixture paths. Neither narrowing removed a false positive
|
|
383
|
+
* the qualified quantity had not already removed, so neither shipped: an
|
|
384
|
+
* admission rule with no measured case is an unproven rule, and this file
|
|
385
|
+
* already has more constants than corpus to justify them.
|
|
386
|
+
*
|
|
249
387
|
* Sorted and de-duplicated, so two runs over one finding agree byte for byte
|
|
250
388
|
* and a caller can print the intersection without re-deriving it.
|
|
251
389
|
*/
|
|
252
390
|
export function symptomKeys(finding: Finding): string[] {
|
|
253
391
|
const keys = new Set<string>();
|
|
254
|
-
// The title contributes symbols and paths but NOT quantities: a title
|
|
255
|
-
// states a headline number the body also states, and counting it twice
|
|
256
|
-
// would let two findings agree on one reading reported in two places.
|
|
257
392
|
for (const span of [...codeSpans(finding.body), finding.title]) {
|
|
258
393
|
for (const id of identifiersIn(span)) keys.add(`sym:${id}`);
|
|
259
394
|
}
|
|
260
395
|
for (const p of [...pathsIn(finding.body), ...pathsIn(finding.title)]) keys.add(`file:${p}`);
|
|
261
|
-
for (const q of quantitiesIn(finding.body)) keys.add(`qty:${q}`);
|
|
262
396
|
return [...keys].sort();
|
|
263
397
|
}
|
|
264
398
|
|
|
265
|
-
/**
|
|
399
|
+
/**
|
|
400
|
+
* The readings a finding reports — a different question from its identity.
|
|
401
|
+
*
|
|
402
|
+
* Read ONLY by `duplicateOverlap`'s same-reading arm. Deliberately not part
|
|
403
|
+
* of `symptomKeys`, `symptomHash` or `containmentOf`: see `symptomKeys` for
|
|
404
|
+
* what the identity set is for, and `quantitiesIn` for the two false
|
|
405
|
+
* `DUPLICATE`s that moved these out of it.
|
|
406
|
+
*
|
|
407
|
+
* The body only, never the title. A title states a headline number the body
|
|
408
|
+
* also states, and counting it twice would let two findings agree on one
|
|
409
|
+
* reading reported in two places.
|
|
410
|
+
*/
|
|
411
|
+
export function quantityKeys(finding: Finding): string[] {
|
|
412
|
+
return [...new Set(quantitiesIn(finding.body).map(q => `qty:${q}`))].sort();
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/**
|
|
416
|
+
* A stable identity for the symptom as a whole — the one hashing binding.
|
|
417
|
+
*
|
|
418
|
+
* Location keys only since #1536, so **re-measuring does not change the
|
|
419
|
+
* hash**. Hashes written to `~/.rungate/finding-ledger.jsonl` before that
|
|
420
|
+
* date were taken over a different key set and will not match one taken now;
|
|
421
|
+
* the field was never a row identity and `FilingLedgerRow.key` says so.
|
|
422
|
+
*/
|
|
266
423
|
export function symptomHash(finding: Finding): string {
|
|
267
424
|
return contentHash(symptomKeys(finding).join("\n"));
|
|
268
425
|
}
|
|
269
426
|
|
|
270
|
-
/**
|
|
427
|
+
/**
|
|
428
|
+
* Keys two findings have in common, sorted — both kinds, because this is
|
|
429
|
+
* what a refusal prints and a reader asked to review a refusal needs to see
|
|
430
|
+
* every key it was decided on, not only the ones in the identity set.
|
|
431
|
+
*/
|
|
271
432
|
export function sharedKeys(a: Finding, b: Finding): string[] {
|
|
272
|
-
const left = new Set(symptomKeys(a));
|
|
273
|
-
return symptomKeys(b).filter(k => left.has(k));
|
|
433
|
+
const left = new Set([...symptomKeys(a), ...quantityKeys(a)]);
|
|
434
|
+
return [...symptomKeys(b), ...quantityKeys(b)].filter(k => left.has(k)).sort();
|
|
274
435
|
}
|
|
275
436
|
|
|
276
437
|
/**
|
|
@@ -306,6 +467,148 @@ export function sharedKeys(a: Finding, b: Finding): string[] {
|
|
|
306
467
|
export const DUPLICATE_MIN_SHARED_QUANTITIES = 2;
|
|
307
468
|
export const DUPLICATE_MIN_SHARED_LOCATIONS = 1;
|
|
308
469
|
|
|
470
|
+
/**
|
|
471
|
+
* The second arm: how much of one finding's key set must sit inside the
|
|
472
|
+
* other's before it is the same finding rather than a similar one (#1301).
|
|
473
|
+
*
|
|
474
|
+
* **A re-filing and a paraphrase are different questions and only the second
|
|
475
|
+
* was being asked.** The rule above asks "do these two share enough to be the
|
|
476
|
+
* same symptom?", which is right for #1175/#1177 and wrong for a finding
|
|
477
|
+
* being filed twice: measured over the live tracker on 2026-10-23, 26 of 38
|
|
478
|
+
* open findings re-filed BYTE-IDENTICALLY were refused and **12 were
|
|
479
|
+
* allowed**, every one of them because it carries fewer than two quantity
|
|
480
|
+
* keys. They are not key-poor — median 7.5 location keys, one with nineteen
|
|
481
|
+
* — they name symbols and files and report no measured numbers.
|
|
482
|
+
*
|
|
483
|
+
* Lowering `DUPLICATE_MIN_SHARED_QUANTITIES` is the cheap fix and the wrong
|
|
484
|
+
* one. At 1 the self-refile rate goes to 82% and the `lib/bash-write-guard.ts`
|
|
485
|
+
* cluster comes back, in the direction this file already calls worse.
|
|
486
|
+
*
|
|
487
|
+
* So this is an ADDITIONAL arm, OR-ed with the one above and never replacing
|
|
488
|
+
* it. Measured over all 44 findings — the 38 open plus the six closed cluster
|
|
489
|
+
* issues, which a sweep of open issues alone cannot see — across 946 pairs:
|
|
490
|
+
*
|
|
491
|
+
* | rule | cross-issue pairs |
|
|
492
|
+
* |---|---|
|
|
493
|
+
* | `qty>=2 AND loc>=1` | 4 — 1175/1177, 1195/1196, 1269/1286, 1162/1226 |
|
|
494
|
+
* | containment >= 0.6 | 3 — 1175/1177, 1195/1196, 1195/1239 |
|
|
495
|
+
* | containment >= 0.8 | **1** — 1175/1177 |
|
|
496
|
+
*
|
|
497
|
+
* The two pairs the quantity threshold was tuned to CATCH are the top two by
|
|
498
|
+
* containment, at 1.00 and 0.78. The four inside the cluster it was tuned to
|
|
499
|
+
* KEEP APART top out at 0.44. At 0.8 this arm adds **zero** cross-issue pairs
|
|
500
|
+
* over the whole corpus while taking the self-refile rate to 38 of 38.
|
|
501
|
+
*
|
|
502
|
+
* ## The caveat, in the same terms as the tuning above
|
|
503
|
+
*
|
|
504
|
+
* 0.8 is fitted on 44 findings, and on that corpus the only thing separating
|
|
505
|
+
* it from 0.6 is a single pair. It is chosen for the error direction rather
|
|
506
|
+
* than for a margin the data supports, and a false DUPLICATE here stays
|
|
507
|
+
* reviewable: the refusal names the colliding issue and the shared keys, and
|
|
508
|
+
* `arbiter-override` waives it.
|
|
509
|
+
*
|
|
510
|
+
* ## THAT SEPARATING PAIR WAS A TIMESTAMP, AND THE JUSTIFICATION IS VOID (#1333)
|
|
511
|
+
*
|
|
512
|
+
* The single pair was #1195/#1196 at 0.778, and 0.778 was inflated by a leak:
|
|
513
|
+
* both findings say "merged 15:48" and `quantitiesIn` emitted the hour as
|
|
514
|
+
* `qty:15`. With the leak masked the pair reads **0.750** — and so does
|
|
515
|
+
* #1195/#1239, which is a DIFFERENT write-guard defect. They are exactly
|
|
516
|
+
* tied, so **no value of this constant admits the first and excludes the
|
|
517
|
+
* second.** The margin that chose 0.8 over 0.6 was the two findings
|
|
518
|
+
* mentioning the same time of day.
|
|
519
|
+
*
|
|
520
|
+
* Measured on the 11 issues this file's tables name, 49 pairs after the
|
|
521
|
+
* cross-reference escape, with two known duplicates (#1175/#1177,
|
|
522
|
+
* #1195/#1196):
|
|
523
|
+
*
|
|
524
|
+
* | arm | can it isolate #1195/#1196? |
|
|
525
|
+
* |---|---|
|
|
526
|
+
* | containment | **no** — tied at 0.750 with a distinct pair |
|
|
527
|
+
* | quantities | **no** — needs `>= 1`, which fires on 11 distinct pairs |
|
|
528
|
+
* | locations | **no** — the highest shared-location pair (7) is distinct, above the true pair (5) |
|
|
529
|
+
*
|
|
530
|
+
* **We are not losing a capability here; we are finding out we never had
|
|
531
|
+
* one, because the only reason that pair was ever caught was two findings
|
|
532
|
+
* mentioning the same time of day.**
|
|
533
|
+
*
|
|
534
|
+
* **The tie survives the floor of 4 below**, re-measured against the merged
|
|
535
|
+
* constant rather than predicted: both pairs still read 0.750, because #1239
|
|
536
|
+
* carries exactly 4 keys and sits on the floor rather than under it. A floor
|
|
537
|
+
* of 5 would separate them — by refusing the distinct pair a reading at all,
|
|
538
|
+
* which is a different mechanism from a ratio and is not an argument for
|
|
539
|
+
* moving the ratio.
|
|
540
|
+
*
|
|
541
|
+
* So both constants are left where they are. Every setting that recovers the
|
|
542
|
+
* pair costs false positives, and a false DUPLICATE is a real finding
|
|
543
|
+
* silently withheld — the direction this file already calls worse. Missing a
|
|
544
|
+
* duplicate means a duplicate gets filed, which a human can see.
|
|
545
|
+
*
|
|
546
|
+
* ### THE TIE IS BROKEN, AND NOT BY EITHER CONSTANT (#1536)
|
|
547
|
+
*
|
|
548
|
+
* Everything above is still the correct reading *of a ratio taken over a key
|
|
549
|
+
* set that mixed readings with locations*. It stopped being the reading when
|
|
550
|
+
* quantities left `symptomKeys` — re-measured against the four live bodies
|
|
551
|
+
* on 2026-10-24:
|
|
552
|
+
*
|
|
553
|
+
* | pair | before | after |
|
|
554
|
+
* |---|---|---|
|
|
555
|
+
* | #1195/#1196, the true duplicate | 0.750 | **0.833 — caught** |
|
|
556
|
+
* | #1195/#1239, the distinct pair | 0.750 | **0.000 — below the floor** |
|
|
557
|
+
*
|
|
558
|
+
* Both constants are untouched. What moved is the denominator: #1239's three
|
|
559
|
+
* remaining keys put it under `DUPLICATE_CONTAINMENT_MIN_KEYS`, and #1196's
|
|
560
|
+
* five shared symbols are five of its six. So the sentence above — *no value
|
|
561
|
+
* of this constant admits the first and excludes the second* — was true of
|
|
562
|
+
* the ratio and false of the problem, and the capability it declared lost
|
|
563
|
+
* was never a property of the cut. That is worth saying plainly rather than
|
|
564
|
+
* deleting: a measurement that names a mechanism it never varied will read
|
|
565
|
+
* as settled for as long as nobody varies it.
|
|
566
|
+
*
|
|
567
|
+
* **The 946-pair table above is not reproducible.** It was measured live
|
|
568
|
+
* against a tracker that has moved and no corpus was stored, so neither
|
|
569
|
+
* constant can be re-derived by anyone — including anyone who disagrees with
|
|
570
|
+
* leaving them. **Tracked as #1365**; until a fixture exists, treat every
|
|
571
|
+
* number in this docblock as a reading someone took once.
|
|
572
|
+
*
|
|
573
|
+
* The floor exists because containment is meaningless on a tiny key set — a
|
|
574
|
+
* one-key finding is wholly contained in anything mentioning that key, which
|
|
575
|
+
* would manufacture a duplicate out of one word.
|
|
576
|
+
*
|
|
577
|
+
* ## The floor is 4, and it was 2 for about an hour (#1318)
|
|
578
|
+
*
|
|
579
|
+
* It shipped at 2 on the argument that "a floor of 4 costs three of the 38
|
|
580
|
+
* and flags not one pair fewer" — which was true, and was the wrong thing to
|
|
581
|
+
* weigh. Counting the pairs it does not flag says nothing about the findings
|
|
582
|
+
* it eats, and no case in the suite asked the second question. Re-measured on
|
|
583
|
+
* the live tracker, at ratio 0.8 over the 35 findings the corpus filters to:
|
|
584
|
+
*
|
|
585
|
+
* | floor | self-refile | cross-issue pairs |
|
|
586
|
+
* |---|---|---|
|
|
587
|
+
* | 2 | 35/35 | 0 |
|
|
588
|
+
* | 3 | 34/35 | 0 |
|
|
589
|
+
* | 4 | **32/35** | 0 |
|
|
590
|
+
* | 5 | 30/35 | 0 |
|
|
591
|
+
*
|
|
592
|
+
* No floor in that range costs a single cross-issue pair, so three of
|
|
593
|
+
* thirty-five self-refiles is the entire price. What it buys: #1162 carries
|
|
594
|
+
* 40 keys, and at floor 2 a TWO-key finding whose keys both appear in it is
|
|
595
|
+
* refused as a duplicate of it. That is a real finding withheld by an
|
|
596
|
+
* unrelated issue, reachable on the tracker as it stands.
|
|
597
|
+
*
|
|
598
|
+
* The two directions are not symmetric and that is what decides this. A
|
|
599
|
+
* missed duplicate is a tracker row somebody closes. A false DUPLICATE
|
|
600
|
+
* silences a finding, and an arbiter that quietly eats novel findings turns a
|
|
601
|
+
* visible backlog into an invisible one — worse than the backlog it exists to
|
|
602
|
+
* shrink. `AR-20` is the ALLOW-direction control that was missing.
|
|
603
|
+
*
|
|
604
|
+
* **Not closed by this:** a FOUR-key finding wholly inside that same issue is
|
|
605
|
+
* still refused, at either floor. The floor shortens the swallow's reach; it
|
|
606
|
+
* does not remove it. An absolute shared-key minimum beside the ratio would
|
|
607
|
+
* not reach that case either, since four keys are genuinely shared.
|
|
608
|
+
*/
|
|
609
|
+
export const DUPLICATE_CONTAINMENT_RATIO = 0.8;
|
|
610
|
+
export const DUPLICATE_CONTAINMENT_MIN_KEYS = 4;
|
|
611
|
+
|
|
309
612
|
/** Does `text` reference `id` as an issue number? */
|
|
310
613
|
function references(text: string, id: string): boolean {
|
|
311
614
|
if (!/^\d+$/.test(id)) return false;
|
|
@@ -330,14 +633,50 @@ function references(text: string, id: string): boolean {
|
|
|
330
633
|
export function duplicateOverlap(a: Finding, b: Finding): { duplicate: boolean; keys: string[] } {
|
|
331
634
|
const keys = sharedKeys(a, b);
|
|
332
635
|
if (references(a.body, b.id) || references(b.body, a.id)) return { duplicate: false, keys };
|
|
636
|
+
// Counted from their own producers rather than by prefix over `keys`
|
|
637
|
+
// (#1536). The two kinds are now two sets and the prefix test was the
|
|
638
|
+
// place that still treated them as one — a quantity that slipped into the
|
|
639
|
+
// identity set would be counted by both arms and nothing would say so.
|
|
333
640
|
const quantities = keys.filter(k => k.startsWith("qty:")).length;
|
|
334
641
|
const locations = keys.length - quantities;
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
642
|
+
const sameSymptom =
|
|
643
|
+
quantities >= DUPLICATE_MIN_SHARED_QUANTITIES &&
|
|
644
|
+
locations >= DUPLICATE_MIN_SHARED_LOCATIONS;
|
|
645
|
+
|
|
646
|
+
// The second arm, OR-ed and never replacing the first: is one of these
|
|
647
|
+
// findings' key sets essentially INSIDE the other's? That is the question a
|
|
648
|
+
// re-filing answers yes to and a paraphrase does not, and the first arm
|
|
649
|
+
// cannot ask it — see DUPLICATE_CONTAINMENT_RATIO for the 946-pair reading
|
|
650
|
+
// that sets the cut and for what the floor is protecting against.
|
|
651
|
+
const contained = containmentOf(a, b) >= DUPLICATE_CONTAINMENT_RATIO;
|
|
652
|
+
|
|
653
|
+
return { duplicate: sameSymptom || contained, keys };
|
|
654
|
+
}
|
|
655
|
+
|
|
656
|
+
/**
|
|
657
|
+
* How much of the smaller key set sits inside the larger, as a ratio.
|
|
658
|
+
*
|
|
659
|
+
* **`0` when either side is under `DUPLICATE_CONTAINMENT_MIN_KEYS`** — a
|
|
660
|
+
* refusal, not a reading, and the two are deliberately the same number here
|
|
661
|
+
* because both mean "this arm does not fire". A caller that needs to tell
|
|
662
|
+
* them apart must check the sizes itself, and `AR-9`'s tie case does.
|
|
663
|
+
*
|
|
664
|
+
* Exported so the arm has **one binding**. A test that recomputed this
|
|
665
|
+
* expression would be a second decider over the same question and a
|
|
666
|
+
* mutation of either would leave the other holding the case up
|
|
667
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
668
|
+
*/
|
|
669
|
+
export function containmentOf(a: Finding, b: Finding): number {
|
|
670
|
+
const left = new Set(symptomKeys(a));
|
|
671
|
+
const sizeA = left.size;
|
|
672
|
+
const sizeB = symptomKeys(b).length;
|
|
673
|
+
if (Math.min(sizeA, sizeB) < DUPLICATE_CONTAINMENT_MIN_KEYS) return 0;
|
|
674
|
+
// Identity keys ONLY, on both sides of the ratio (#1536). A reading in the
|
|
675
|
+
// denominator makes the ratio move when a finding re-states a number, and
|
|
676
|
+
// that is what cost #1175/#1177 when the qualifier was tried inside
|
|
677
|
+
// `symptomKeys` — see that function's header.
|
|
678
|
+
const shared = symptomKeys(b).filter(k => left.has(k)).length;
|
|
679
|
+
return Math.max(shared / sizeA, shared / sizeB);
|
|
341
680
|
}
|
|
342
681
|
|
|
343
682
|
/**
|
|
@@ -452,6 +791,12 @@ export type ArbiterRefusal =
|
|
|
452
791
|
| "DROPPED_CATEGORY"
|
|
453
792
|
/** A cited line is past the end of the file it cites. */
|
|
454
793
|
| "STALE_CITATION"
|
|
794
|
+
/**
|
|
795
|
+
* The filing names no `SUCCESS.md` claim, so nothing says what it moves.
|
|
796
|
+
* A chokepoint refusal only — a review round's findings are adjudicated
|
|
797
|
+
* against a diff rather than filed by hand, and have no title to carry one.
|
|
798
|
+
*/
|
|
799
|
+
| "NO_CLAIM"
|
|
455
800
|
/** Something could not be evaluated. Fails; never skips. */
|
|
456
801
|
| "UNMEASURED";
|
|
457
802
|
|
|
@@ -502,6 +847,39 @@ export interface Verdict {
|
|
|
502
847
|
symptomHash: string;
|
|
503
848
|
}
|
|
504
849
|
|
|
850
|
+
/** No group was convened at all. The single-finding case. */
|
|
851
|
+
export const NO_BALLOT =
|
|
852
|
+
"no verifier group was convened, so no quorum was reached — not reaching one and not having one are different states";
|
|
853
|
+
|
|
854
|
+
/**
|
|
855
|
+
* One ballot was offered for a batch of several findings.
|
|
856
|
+
*
|
|
857
|
+
* A vote is about a finding. Spreading one across a heterogeneous batch does
|
|
858
|
+
* not give the other findings a quorum, it gives them somebody else's — and
|
|
859
|
+
* `VERIFIER_QUORUM` then counts agreement that was never about them. The
|
|
860
|
+
* refusal is the point: a batch cannot be waved through on one vote.
|
|
861
|
+
*/
|
|
862
|
+
export const SHARED_BALLOT =
|
|
863
|
+
"one ballot was supplied for a batch of several findings, and a vote is about a finding: " +
|
|
864
|
+
"the other findings in this batch have not failed a quorum, they have not had one. " +
|
|
865
|
+
"Supply `ballots`, one group per finding, in input order";
|
|
866
|
+
|
|
867
|
+
/**
|
|
868
|
+
* The ballot list did not describe the batch.
|
|
869
|
+
*
|
|
870
|
+
* Padding the short end would invent votes nobody cast and truncating the
|
|
871
|
+
* long end would discard ones somebody did — the same argument
|
|
872
|
+
* `INCOMPLETE_GROUP` makes one level down, where an absent vote is neither
|
|
873
|
+
* agreement nor dissent.
|
|
874
|
+
*/
|
|
875
|
+
export const BALLOT_COUNT_MISMATCH =
|
|
876
|
+
"the ballot list does not have one entry per finding, so which group voted on which finding is not recoverable";
|
|
877
|
+
|
|
878
|
+
/** Both `votes` and `ballots` arrived. Two instructions, no tie-break. */
|
|
879
|
+
export const BALLOT_AMBIGUOUS =
|
|
880
|
+
"both `votes` and `ballots` were supplied and they are two different instructions about the same batch; " +
|
|
881
|
+
"choosing one silently would be a decision nobody recorded";
|
|
882
|
+
|
|
505
883
|
export interface ArbitrateOptions {
|
|
506
884
|
/** Repository root. `origin/main` is read from here; never checked out. */
|
|
507
885
|
projectRoot: string;
|
|
@@ -517,6 +895,17 @@ export interface ArbitrateOptions {
|
|
|
517
895
|
* repository, and no caller genuinely has no verifiers.
|
|
518
896
|
*/
|
|
519
897
|
votes?: readonly VerifierVote[];
|
|
898
|
+
/**
|
|
899
|
+
* What to say when `votes` is absent. The refusal is unchanged either way
|
|
900
|
+
* — this is the sentence, not the reading.
|
|
901
|
+
*
|
|
902
|
+
* It exists because `arbitrateBatch` knows something this function cannot:
|
|
903
|
+
* *why* a finding has no ballot. "Nobody convened a group" and "a ballot
|
|
904
|
+
* list arrived that does not describe this finding" are the same verdict
|
|
905
|
+
* and different defects, and a reader debugging the second one should not
|
|
906
|
+
* be told the first.
|
|
907
|
+
*/
|
|
908
|
+
noBallotReason?: string;
|
|
520
909
|
/** Group size and quorum. Both default; see `lib/finding-jury.ts`. */
|
|
521
910
|
jury?: JuryConfig;
|
|
522
911
|
/**
|
|
@@ -586,7 +975,7 @@ export function arbitrate(finding: Finding, options: ArbitrateOptions): Verdict
|
|
|
586
975
|
|
|
587
976
|
// ── 2. do enough of the verifiers agree it is real? ──
|
|
588
977
|
if (votes === undefined) {
|
|
589
|
-
return drop("UNMEASURED",
|
|
978
|
+
return drop("UNMEASURED", options.noBallotReason ?? NO_BALLOT);
|
|
590
979
|
}
|
|
591
980
|
const jury = juryReading(votes, options.jury);
|
|
592
981
|
if (jury.reading === "UNMEASURED") {
|
|
@@ -726,6 +1115,15 @@ export const FILING_BUDGET_FINDINGS = 6;
|
|
|
726
1115
|
* candidate refused `UNMEASURED` in its own right carries `UNMEASURED`;
|
|
727
1116
|
* the two are deliberately distinguishable, because the first set is what
|
|
728
1117
|
* explains the second.
|
|
1118
|
+
* - `COMMAND_BLOCKED` — the same shape one layer out, and the reason it is a
|
|
1119
|
+
* value of its own rather than a reuse of the one above (#1344). At the
|
|
1120
|
+
* `gh issue create` chokepoint the unit is a Bash COMMAND, and a hook's one
|
|
1121
|
+
* lever is all of it: a clause that cleared on its own merits beside a
|
|
1122
|
+
* clause that was refused reached the tracker exactly as little as the
|
|
1123
|
+
* refused one did. It is not `BATCH_UNMEASURED` — nothing here was
|
|
1124
|
+
* unmeasured, the sibling was measured and refused — and it is not the
|
|
1125
|
+
* sibling's own `ArbiterRefusal`, because this clause was never refused and
|
|
1126
|
+
* is the one an agent should re-run.
|
|
729
1127
|
* - `UNACCOUNTED` — the promoter returned this candidate in neither
|
|
730
1128
|
* `promoted` nor `withheld`. It partitions its input, so this cannot
|
|
731
1129
|
* happen; it is named instead of defaulted so that if the partition ever
|
|
@@ -735,6 +1133,7 @@ export type WithheldBy =
|
|
|
735
1133
|
| ArbiterRefusal
|
|
736
1134
|
| WithheldReason
|
|
737
1135
|
| "BATCH_UNMEASURED"
|
|
1136
|
+
| "COMMAND_BLOCKED"
|
|
738
1137
|
| "UNACCOUNTED";
|
|
739
1138
|
|
|
740
1139
|
/**
|
|
@@ -814,6 +1213,37 @@ export interface CandidateRecord {
|
|
|
814
1213
|
* construction, with no collision bookkeeping to be a second decider.
|
|
815
1214
|
*/
|
|
816
1215
|
key: string | null;
|
|
1216
|
+
/**
|
|
1217
|
+
* The tracker's issue number once the finding has been filed, and
|
|
1218
|
+
* `UNFILED_ID` before that.
|
|
1219
|
+
*
|
|
1220
|
+
* **For a withheld candidate this is `UNFILED_ID`, and it will never be
|
|
1221
|
+
* anything else.** Not "not yet" — never. Being withheld IS the state of
|
|
1222
|
+
* not acquiring an issue number, so the two can only ever be read
|
|
1223
|
+
* together: there is no later moment at which a row recording a finding
|
|
1224
|
+
* the quorum voted down, or the category filter dropped, or the budget
|
|
1225
|
+
* ranked below the cut, comes back carrying a number. Those rows are the
|
|
1226
|
+
* population this ledger exists to record, so the field is absent exactly
|
|
1227
|
+
* where the data matters.
|
|
1228
|
+
*
|
|
1229
|
+
* ## What follows, and it is the reason this comment is here
|
|
1230
|
+
*
|
|
1231
|
+
* **The outcome join has to be on content.** This ledger supplies the
|
|
1232
|
+
* left-hand side of a join against something that arrives later and from
|
|
1233
|
+
* somewhere else — a fixing commit, a re-report, a bug that shipped. The
|
|
1234
|
+
* right-hand side will be keyed by whatever that source keys by, and the
|
|
1235
|
+
* one thing it can never be matched on is this field, because half the
|
|
1236
|
+
* rows do not have a value and the half that do were never the question.
|
|
1237
|
+
* Match on `symptomHash`, on the title, on the cited symbols — on
|
|
1238
|
+
* something the finding SAYS.
|
|
1239
|
+
*
|
|
1240
|
+
* **So do not add an id field to make the join easier.** It is the
|
|
1241
|
+
* obvious repair and there is nothing to put in it: a synthetic id minted
|
|
1242
|
+
* here is a key only this file has ever seen, which is `key` and is
|
|
1243
|
+
* already present, and it still will not appear on the other side of the
|
|
1244
|
+
* join. The thing that looks like a missing column is a fact about the
|
|
1245
|
+
* domain.
|
|
1246
|
+
*/
|
|
817
1247
|
id: string;
|
|
818
1248
|
symptomHash: string;
|
|
819
1249
|
category: FindingCategory;
|
|
@@ -899,17 +1329,61 @@ function walkOrder(findings: readonly Finding[]): Array<{ finding: Finding; inde
|
|
|
899
1329
|
*
|
|
900
1330
|
* So each survivor joins the comparison set for everything walked after it.
|
|
901
1331
|
* See `walkOrder` for why the order is pinned rather than inherited.
|
|
1332
|
+
*
|
|
1333
|
+
* ## One ballot per finding, and no way to spread one across the batch
|
|
1334
|
+
*
|
|
1335
|
+
* `ballots` is indexed by INPUT position, not by walk order and not by id —
|
|
1336
|
+
* every unfiled finding carries `UNFILED_ID`, so a batch of them is a batch
|
|
1337
|
+
* of one id and an id-keyed ballot map resolves all of them to whichever came
|
|
1338
|
+
* first.
|
|
1339
|
+
*
|
|
1340
|
+
* `votes` remains the single-finding path and is refused for a batch of
|
|
1341
|
+
* several, because a vote is about a finding: spreading one across a
|
|
1342
|
+
* heterogeneous batch does not give the others a quorum, it gives them
|
|
1343
|
+
* somebody else's, and `VERIFIER_QUORUM` then counts agreement that was never
|
|
1344
|
+
* about them.
|
|
1345
|
+
*
|
|
1346
|
+
* **There is deliberately no `sharedBallot: true`.** A flag that re-enables
|
|
1347
|
+
* the defect is satisfied by typing a word, and every caller who wants to get
|
|
1348
|
+
* past a gate learns to type it — the same thing `--label follow-up` had
|
|
1349
|
+
* become before #1261. A caller that genuinely has one group's verdict on
|
|
1350
|
+
* several findings writes the expansion at its own call site, where a reader
|
|
1351
|
+
* can see that it happened.
|
|
902
1352
|
*/
|
|
903
1353
|
export function arbitrateBatch(
|
|
904
1354
|
findings: readonly Finding[],
|
|
905
|
-
options: ArbitrateOptions & {
|
|
1355
|
+
options: ArbitrateOptions & {
|
|
1356
|
+
budget?: number;
|
|
1357
|
+
now?: string;
|
|
1358
|
+
batch?: string;
|
|
1359
|
+
/** One verifier group per finding, in INPUT order. */
|
|
1360
|
+
ballots?: readonly (readonly VerifierVote[])[];
|
|
1361
|
+
},
|
|
906
1362
|
): BatchReading {
|
|
907
1363
|
const date = options.now ?? new Date().toISOString();
|
|
908
1364
|
const seen: Finding[] = [...options.existing];
|
|
909
1365
|
const verdicts: Verdict[] = new Array(findings.length);
|
|
1366
|
+
const { ballots } = options;
|
|
1367
|
+
|
|
1368
|
+
// Resolved once, before the walk, so every finding in a refused batch gets
|
|
1369
|
+
// the same sentence and no finding is adjudicated on a ballot the batch as
|
|
1370
|
+
// a whole could not account for.
|
|
1371
|
+
const refusal: string | null =
|
|
1372
|
+
ballots !== undefined && options.votes !== undefined
|
|
1373
|
+
? BALLOT_AMBIGUOUS
|
|
1374
|
+
: ballots !== undefined && ballots.length !== findings.length
|
|
1375
|
+
? BALLOT_COUNT_MISMATCH
|
|
1376
|
+
: ballots === undefined && options.votes !== undefined && findings.length > 1
|
|
1377
|
+
? SHARED_BALLOT
|
|
1378
|
+
: null;
|
|
910
1379
|
|
|
911
1380
|
for (const { finding, index } of walkOrder(findings)) {
|
|
912
|
-
const verdict = arbitrate(finding, {
|
|
1381
|
+
const verdict = arbitrate(finding, {
|
|
1382
|
+
...options,
|
|
1383
|
+
existing: seen,
|
|
1384
|
+
votes: refusal !== null ? undefined : (ballots?.[index] ?? options.votes),
|
|
1385
|
+
noBallotReason: refusal ?? options.noBallotReason,
|
|
1386
|
+
});
|
|
913
1387
|
verdicts[index] = verdict;
|
|
914
1388
|
// Only something that will actually be posted or filed occupies the
|
|
915
1389
|
// space. A dropped finding leaves no artefact for a later one to
|