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.
Files changed (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -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
- * Integers a finding reports as a reading.
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 and not a number: an issue
224
- * reference (`#1188`), an SC or AC id, a date component, and anything under
225
- * ten. Without the first of those, every finding that cites the same prior
226
- * issue collides with every other — which is a reading of the cross-reference
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): number[] {
230
- const out: number[] = [];
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
- for (const m of masked.matchAll(/\b\d[\d,]*\b/g)) {
240
- const n = Number.parseInt(m[0].replace(/,/g, ""), 10);
241
- if (Number.isFinite(n) && n >= 10) out.push(n);
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
- /** A stable identity for the symptom as a whole — the one hashing binding. */
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
- /** Keys two findings have in common, sorted. */
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
- return {
336
- duplicate:
337
- quantities >= DUPLICATE_MIN_SHARED_QUANTITIES &&
338
- locations >= DUPLICATE_MIN_SHARED_LOCATIONS,
339
- keys,
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", "no verifier group was convened, so no quorum was reached — not reaching one and not having one are different states");
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 & { budget?: number; now?: string; batch?: string },
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, { ...options, existing: seen });
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