rungate 0.8.0 → 0.8.2

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 (73) hide show
  1. package/gates/.gate-salt +1 -0
  2. package/gates/SCHEMA-GUIDE.md +485 -0
  3. package/gates/ac-quality.test.ts +106 -0
  4. package/gates/adversarial.test.ts +283 -0
  5. package/gates/brief-assembler.test.ts +487 -0
  6. package/gates/brief-assembler.ts +448 -0
  7. package/gates/bunfig.toml +2 -0
  8. package/gates/chain.test.ts +91 -0
  9. package/gates/e2e-smoke.test.ts +234 -0
  10. package/gates/error-classifier.test.ts +250 -0
  11. package/gates/error-classifier.ts +99 -0
  12. package/gates/gate-executor.ts +3071 -0
  13. package/gates/orchestrator.test.ts +968 -0
  14. package/gates/orchestrator.ts +827 -0
  15. package/gates/preload.ts +89 -0
  16. package/gates/prompts/ac-adversary.md +20 -0
  17. package/gates/prompts/evidence-validator.md +22 -0
  18. package/gates/prompts/prove-reproducer.md +53 -0
  19. package/gates/prompts.sha256 +3 -0
  20. package/gates/prove.test.ts +164 -0
  21. package/gates/rook-state.test.ts +108 -0
  22. package/gates/run-attribution.ts +290 -0
  23. package/gates/run-gate.ts +163 -0
  24. package/gates/schema-parity.test.ts +378 -0
  25. package/gates/schema.ts +1209 -0
  26. package/gates/self-heal.test.ts +511 -0
  27. package/gates/self-heal.ts +125 -0
  28. package/gates/ship-orchestrator.test.ts +399 -0
  29. package/gates/ship-orchestrator.ts +384 -0
  30. package/gates/spec-compliance-probe.ts +159 -0
  31. package/gates/test-fixtures/broken-no-environments.json +110 -0
  32. package/gates/test-fixtures/consumer-directory-layout.json +90 -0
  33. package/gates/test-fixtures/valid-standard.json +91 -0
  34. package/gates/test-utils.ts +43 -0
  35. package/gates/typecheck-gate.ts +111 -0
  36. package/gates/witness.ts +349 -0
  37. package/gates/workflow.test.ts +2018 -0
  38. package/hooks/BashWriteGuard.hook.ts +19 -0
  39. package/hooks/GateResultProtection.hook.ts +27 -1
  40. package/hooks/VerifyPhaseLock.hook.ts +51 -11
  41. package/hooks/WorkflowStateGuard.hook.ts +24 -0
  42. package/lib/ai-review-rounds.ts +462 -0
  43. package/lib/bash-file-read.ts +17 -3
  44. package/lib/bash-write-guard.ts +1285 -50
  45. package/lib/distribution-standing.ts +75 -4
  46. package/lib/failure-intake.ts +12 -4
  47. package/lib/file-extensions.ts +81 -0
  48. package/lib/finding-arbiter.ts +1015 -0
  49. package/lib/finding-jury.ts +537 -0
  50. package/lib/gate-enforcement.ts +171 -43
  51. package/lib/gate-result-protection.ts +12 -2
  52. package/lib/generators/code-map.ts +55 -4
  53. package/lib/generators/types.ts +27 -1
  54. package/lib/github.ts +55 -0
  55. package/lib/interpreters.ts +64 -0
  56. package/lib/issue-create-override.ts +69 -8
  57. package/lib/issue-filing-gate.ts +605 -0
  58. package/lib/js-top-level-code.ts +20 -2
  59. package/lib/junit-checks.ts +239 -1
  60. package/lib/package-closure.ts +114 -0
  61. package/lib/publish-window.ts +287 -0
  62. package/lib/scaffold/ai-review-findings.ts +142 -3
  63. package/lib/scaffold/ai-review-step.ts +1012 -18
  64. package/lib/scaffold/managed-workflow.ts +163 -4
  65. package/lib/scaffold/steps.ts +498 -22
  66. package/lib/scanner.ts +13 -4
  67. package/lib/ticked-sc-symbols.ts +361 -0
  68. package/lib/transcript-checker.ts +6 -0
  69. package/lib/workflow-actions.ts +18 -0
  70. package/package.json +3 -1
  71. package/scripts/arbitrate-finding.ts +224 -0
  72. package/scripts/generate-code-map.ts +18 -10
  73. package/scripts/sync-sc-status.ts +82 -8
@@ -0,0 +1,537 @@
1
+ /**
2
+ * The verifier jury: who agrees a finding is real, what kind it is, and where
3
+ * it goes (#1187).
4
+ *
5
+ * ## The topology this implements, and the one it replaces
6
+ *
7
+ * #1187 was filed asking which findings are worth **filing**. That framing is
8
+ * wrong, and the correction is the point of this module. The published design
9
+ * it was inspired by files nothing at all:
10
+ *
11
+ * > Several agents look for bugs at the same time. Then a separate group votes
12
+ * > on each finding, and it only gets posted if enough of them agree it's
13
+ * > real. Findings that are only about style, diagnostics, or cleanup get
14
+ * > dropped. We A/B tested those filters on our own PRs before keeping them.
15
+ * > What's left shows up as inline comments sorted by severity. Each is tagged
16
+ * > Important, Nit, or Pre-existing.
17
+ *
18
+ * So the pipeline is **hunters → a separate verifier group votes → quorum →
19
+ * category filter → severity sort → inline PR comments that block merge until
20
+ * answered.** A finding is resolved by being fixed or by the thread being
21
+ * closed with a reason. Nothing becomes a tracker issue, which is why that
22
+ * pipeline has no backlog and ours regenerates: we added a filing step it does
23
+ * not have. Measured on this tracker on 2026-10-22, **23 of 27 open issues
24
+ * were created the same day and 10 of them name one subsystem.**
25
+ *
26
+ * `DEFAULT_DISPOSITION` is therefore `COMMENT`, and `ISSUE` is reachable only
27
+ * by an explicit, reasoned declaration from the caller — see `adjudicate`.
28
+ *
29
+ * ## What this module owns, and what it does not
30
+ *
31
+ * It owns the **gate**, not the agents. Spawning hunters and verifiers is the
32
+ * orchestrator's job; a library that spawned them could not be tested without
33
+ * a model in the loop, and `lib/rule-promotion.ts` already set the precedent —
34
+ * it owns the ranking and the budget and nothing that produces candidates.
35
+ *
36
+ * So a caller hands in `VerifierVote[]` and this counts them.
37
+ *
38
+ * ## WHAT THIS DOES NOT COVER
39
+ *
40
+ * - **Whether the verifiers are independent.** Three votes from one agent run
41
+ * three times is not a group, and the only shape of that this can see is a
42
+ * repeated `verifier` id, which it refuses. Three genuinely separate agents
43
+ * given the same prompt and the same context are correlated in a way nothing
44
+ * here can read.
45
+ * - **Whether the category a verifier reports is the right one.**
46
+ * `classifyCategory` is a keyword fallback and a measuring instrument, not
47
+ * an adjudicator. Its error direction is deliberately toward KEEP.
48
+ * - **Whether a dropped finding was real.** A dropped finding leaves a reason
49
+ * and a category on the reading; nothing re-examines it later.
50
+ */
51
+
52
+ import type { Finding } from "./finding-arbiter";
53
+
54
+ // ── Cardinalities ────────────────────────────────────────────────────────
55
+
56
+ /**
57
+ * How many verifiers vote on each finding.
58
+ *
59
+ * **Three, and this is a default rather than a derivation.** The published
60
+ * design gives the topology and publishes no cardinality — not the number of
61
+ * hunters, not the number of verifiers, not the quorum. Writing a number into
62
+ * the code as though it had been measured would be the worst of both.
63
+ *
64
+ * What can be argued for three:
65
+ *
66
+ * - It is the smallest group in which **one voter does not decide the
67
+ * outcome**. At two, a single dissent either deadlocks or wins.
68
+ * - It is odd, so a majority always exists and no tie-break rule is needed —
69
+ * and a tie-break rule is a second decider over the same input
70
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
71
+ * - Each verifier is a full agent context. Five-of-three costs 67% more per
72
+ * finding and buys tolerance of **two** dissenters, which is only worth
73
+ * paying once a measured single-dissent rate shows it is common.
74
+ *
75
+ * What would derive it: the disagreement rate between independent verifiers on
76
+ * one finding. **That cannot be measured in this repository today**, because
77
+ * nothing records a finding before it is filed — every artefact on this
78
+ * tracker and in `.claude/` is already post-filter. Recording the pre-filter
79
+ * population is the prerequisite, not a tuning pass.
80
+ */
81
+ export const VERIFIER_GROUP_SIZE = 3;
82
+
83
+ /**
84
+ * How many of them must agree a finding is real for it to be posted.
85
+ *
86
+ * Two of three: the weakest threshold that still means *agreement* rather than
87
+ * *anyone*. `juryReading` refuses a configured quorum that is not a strict
88
+ * majority — see `NON_MAJORITY_QUORUM` — because a "quorum" of one is a group
89
+ * with no gate in it, and that failure is invisible from the outcome.
90
+ */
91
+ export const VERIFIER_QUORUM = 2;
92
+
93
+ export const INCOMPLETE_GROUP = "the ballot's size does not match the declared group size: an absent vote is neither agreement nor dissent, and an extra one is not a larger group";
94
+ export const REPEATED_VERIFIER = "one verifier voted more than once, so the votes are not independent";
95
+ export const NON_MAJORITY_QUORUM = "the configured quorum is not a strict majority of the group";
96
+
97
+ // ── Categories ───────────────────────────────────────────────────────────
98
+
99
+ export type FindingCategory =
100
+ | "correctness"
101
+ | "security"
102
+ | "performance"
103
+ | "style"
104
+ | "diagnostics"
105
+ | "cleanup"
106
+ /** No signal either way. Kept, never dropped. */
107
+ | "unclassified";
108
+
109
+ /** Dropped outright. The three the source design names, and no others. */
110
+ export const DROPPED_CATEGORIES: ReadonlySet<FindingCategory> = new Set<FindingCategory>([
111
+ "style",
112
+ "diagnostics",
113
+ "cleanup",
114
+ ]);
115
+
116
+ const KEEP_SIGNALS: Array<[Exclude<FindingCategory, "style" | "diagnostics" | "cleanup" | "unclassified">, RegExp]> = [
117
+ [
118
+ "security",
119
+ /\b(secret|credential|token|api key|injection|traversal|privilege|sandbox escape|arbitrary (read|write|code)|unauthenticated|spoof)\b/i,
120
+ ],
121
+ [
122
+ "correctness",
123
+ /\b(bug|defect|regression|incorrect|wrong|broken|crash|throws|race|deadlock|off.by.one|silently|never fires|cannot fail|false (positive|negative)|fails? (open|closed|to)|returns the wrong|mismatch|data loss|corrupt|does not (match|fire|run|refuse|catch))\b/i,
124
+ ],
125
+ ["performance", /\b(timeout|unbounded|memory leak|leaks? (memory|descriptors)|hangs?|exhaust)\b/i],
126
+ ];
127
+
128
+ const DROP_SIGNALS: Array<[Extract<FindingCategory, "style" | "diagnostics" | "cleanup">, RegExp]> = [
129
+ ["style", /\b(nit|typo|formatting|indentation|naming convention|rename (it|this|the variable)|readability|capitalisation|capitalization|whitespace)\b/i],
130
+ ["diagnostics", /\b(error message|log(ging| line| statement)|warning text|annotation text|stack trace|observability|console\.log|more helpful message)\b/i],
131
+ ["cleanup", /\b(unused (import|variable|export|function)|commented.out|refactor|tidy|house ?keeping|nitpick|cosmetic|delete the comment|redundant comment)\b/i],
132
+ ];
133
+
134
+ /**
135
+ * A keyword reading of what kind of finding this is.
136
+ *
137
+ * **This is a fallback and a measuring instrument, not an adjudicator.** In
138
+ * production the category comes from the verifier vote, which is a model
139
+ * reading the finding; this runs only when no verifier supplied one, and it is
140
+ * what `adjudicate` reports so the category is never silently absent.
141
+ *
142
+ * ## The error direction, chosen deliberately
143
+ *
144
+ * A drop category is returned **only when a drop signal matched and no keep
145
+ * signal did.** So the cheap way for this to be wrong is to keep a nit, which
146
+ * costs one comment thread; the expensive way — dropping a real bug — requires
147
+ * a finding that uses none of the correctness, security or performance
148
+ * vocabulary while using the style, diagnostics or cleanup vocabulary.
149
+ *
150
+ * ## THE SCOPE IS THE TITLE, AND THAT IS THE WHOLE RULE
151
+ *
152
+ * **A finding's title states what it is about; its body argues, and an
153
+ * argument quotes the vocabulary of the thing it is not.**
154
+ *
155
+ * Measured, not asserted. Over the 385 issues on this tracker closed as
156
+ * COMPLETED, reading the whole text drops **8**, and all eight are that
157
+ * failure: `prose` inside `refs(c.branch) || prose(c.subject)` (#900), inside
158
+ * "template prose" (#515), inside "entries carried prose" (#611) — and #781,
159
+ * whose body contains the sentence *"the reason this is not just a wording
160
+ * fix"*. Scoping to the title drops **0** of the same 385.
161
+ *
162
+ * Three terms were then removed from the signal lists, and this is a fit to
163
+ * this corpus rather than a forecast, so it is stated as one: `prose` and
164
+ * `wording` are **domain vocabulary here** — this project argues about prose
165
+ * versus mechanism constantly — and `dead code` is how a reachability defect
166
+ * is *described* (#1110's title calls an unreachable blocking branch "dead
167
+ * code"), not a request to tidy. They would be reasonable signals in a
168
+ * codebase that did not talk this way.
169
+ *
170
+ * ## Measured backwards, before the filter shipped
171
+ *
172
+ * The source design A/B tested its filters before keeping them. The
173
+ * backwards-equivalent available here is to run the filter over findings whose
174
+ * outcome is already known: closed as COMPLETED means a merged PR fixed it, so
175
+ * it was real.
176
+ *
177
+ * | population | n | dropped |
178
+ * |---|---|---|
179
+ * | closed COMPLETED — real, somebody wrote the fix | 385 | **0** |
180
+ * | closed NOT_PLANNED | 15 | **0** |
181
+ * | open on 2026-10-22 | 27 | **0** |
182
+ * | planted: one style, one diagnostics, one cleanup, one correctness control | 4 | **3** |
183
+ *
184
+ * **Read the fourth row before the first three.** Zero drops over 427 real
185
+ * issues would otherwise be indistinguishable from a filter that cannot fire
186
+ * — the inert-knob shape in `.claude/rules/checks-must-be-able-to-fail.md`.
187
+ * The planted row is in `test/finding-jury.test.ts` under `JURY-4` and it is
188
+ * what separates those two readings.
189
+ *
190
+ * **And read the first three as safety, not as usefulness.** The filter is
191
+ * inert on this corpus because what this tracker carries is already almost
192
+ * entirely correctness-shaped (278 of 385 by this same classifier). Its real
193
+ * population is raw hunter output *before* anybody decided to file, and
194
+ * **this repository does not record that population anywhere** — which is the
195
+ * same gap that makes the quorum cardinality above a default rather than a
196
+ * derivation. So: safe to ship, not yet shown to earn its place.
197
+ */
198
+ export function classifyCategory(finding: Pick<Finding, "title" | "body">): FindingCategory {
199
+ const scope = finding.title;
200
+ for (const [category, signal] of KEEP_SIGNALS) {
201
+ if (signal.test(scope)) return category;
202
+ }
203
+ for (const [category, signal] of DROP_SIGNALS) {
204
+ if (signal.test(scope)) return category;
205
+ }
206
+ return "unclassified";
207
+ }
208
+
209
+ // ── Severity ─────────────────────────────────────────────────────────────
210
+
211
+ /**
212
+ * The three tags the source design posts, and no fourth.
213
+ *
214
+ * `Pre-existing` is the one that matters most here and the one we had no way
215
+ * to say: a finding about code the change never touched is not the author's
216
+ * defect and should not be priced like one.
217
+ */
218
+ export type Severity = "Important" | "Nit" | "Pre-existing";
219
+
220
+ /** Sort order for the posted comments. A pre-existing bug is still a bug. */
221
+ export const SEVERITY_RANK: Record<Severity, number> = { Important: 0, "Pre-existing": 1, Nit: 2 };
222
+
223
+ // ── The vote ─────────────────────────────────────────────────────────────
224
+
225
+ export interface VerifierVote {
226
+ /** Which verifier cast it. Two votes under one id is not a group. */
227
+ verifier: string;
228
+ /** The one question a vote answers: is this real? */
229
+ real: boolean;
230
+ reason: string;
231
+ category?: FindingCategory;
232
+ severity?: Severity;
233
+ }
234
+
235
+ /**
236
+ * Every category name, bound to the union by the compiler.
237
+ *
238
+ * A `Record<FindingCategory, true>` is exhaustive: add a member to the union
239
+ * and this object fails to typecheck until it carries it. That is the point —
240
+ * a hand-written array would quietly stop recognising the new category and
241
+ * `parseVotes` would start refusing a vote that is in fact well-formed.
242
+ */
243
+ const CATEGORY_MEMBERS: Record<FindingCategory, true> = {
244
+ correctness: true,
245
+ security: true,
246
+ performance: true,
247
+ style: true,
248
+ diagnostics: true,
249
+ cleanup: true,
250
+ unclassified: true,
251
+ };
252
+
253
+ /** What a malformed entry is called in the refusal. One string, one binding. */
254
+ export const UNREADABLE_VOTE = "a vote nobody can read is UNMEASURED, not a dissent";
255
+
256
+ /** `"a string"`, `3`, `null` — enough to identify the entry without echoing a body. */
257
+ function shapeOf(value: unknown): string {
258
+ if (value === null) return "null";
259
+ if (Array.isArray(value)) return "an array";
260
+ return typeof value === "string" ? `the string ${JSON.stringify(value)}` : `a ${typeof value}`;
261
+ }
262
+
263
+ /**
264
+ * Read an untrusted ballot, or refuse it.
265
+ *
266
+ * **This is the boundary, and it is the whole of #1235.** `readVotes` in
267
+ * `scripts/arbitrate-finding.ts` checked that the parsed JSON was an array and
268
+ * then cast it — `parsed as VerifierVote[]` — so nothing ever looked at an
269
+ * entry. `juryReading` counts agreement with `votes.filter(v => v.real)`, a
270
+ * truthy test, and **the string `"false"` is truthy**. A verifier who wrote
271
+ * `"real": "false"` was counted as agreeing with the finding they rejected.
272
+ * Measured before the fix: three votes, all three rejecting, two of them
273
+ * spelling it `"false"`, returned `MEASURED passed=true` at `2 of 3`.
274
+ *
275
+ * ## Why this refuses the ballot instead of coercing the vote
276
+ *
277
+ * The cheap repair is to read `"false"` as `false`. It fixes the headline case
278
+ * and is wrong in the same direction: it invents a dissent. A vote that cannot
279
+ * be read is not a vote that was cast, and counting it as a no is a second
280
+ * reading nobody took — `.claude/rules/config-access.md`'s *Silent Default
281
+ * Substitution*. One unreadable entry among two genuine yeses still clears a
282
+ * 2-of-3 quorum under coercion, and `test/finding-arbiter.test.ts`'s `AR-16`
283
+ * case `B` is that input.
284
+ *
285
+ * Nor is the entry dropped. A two-vote ballot against a declared group of
286
+ * three refuses as `INCOMPLETE_GROUP` — "a verifier did not report" — when in
287
+ * fact it reported unreadably. Both refuse; only one names what happened.
288
+ *
289
+ * ## Why here and not in `juryReading`
290
+ *
291
+ * `juryReading` owns the *group* properties — `INCOMPLETE_GROUP`,
292
+ * `REPEATED_VERIFIER`, `NON_MAJORITY_QUORUM` — and should keep owning only
293
+ * those. They are facts about a ballot already known to be made of votes. This
294
+ * is the question of whether it is, and it belongs where the JSON enters.
295
+ *
296
+ * Validating the whole declared interface rather than only `real` is
297
+ * deliberate: the cast asserted every field, so every field was unchecked, and
298
+ * two of the others carry the same defect. An unrecognised `category` is not
299
+ * in `DROPPED_CATEGORIES`, so it reads to `juryCategory` as a keep category.
300
+ * An unrecognised `severity` indexes `SEVERITY_RANK` to `undefined`, making
301
+ * the sort comparator in `severityOf` return `NaN`.
302
+ *
303
+ * **`Object.hasOwn`, never the `in` operator**, and this is not a style
304
+ * preference. `in` walks the prototype chain, so `"constructor" in
305
+ * CATEGORY_MEMBERS` is `true` and a vote claiming `category: "constructor"`
306
+ * was accepted — an accepted-but-unrecognised category is absent from
307
+ * `DROPPED_CATEGORIES` and so reads as a **keep**, which is this function's
308
+ * own defect reintroduced inside its fix. Eight values were wrongly accepted
309
+ * across the two fields; `JURY-6` runs five of them against both.
310
+ *
311
+ * @throws if the ballot is not an array, or any entry is not a well-formed vote.
312
+ */
313
+ export function parseVotes(parsed: unknown): readonly VerifierVote[] {
314
+ if (!Array.isArray(parsed)) {
315
+ throw new Error(`the ballot is ${shapeOf(parsed)}, not a JSON array of votes`);
316
+ }
317
+ return parsed.map((entry, at): VerifierVote => {
318
+ const where = `vote ${at} of the ballot`;
319
+ if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
320
+ throw new Error(`${where} is ${shapeOf(entry)}, not an object: ${UNREADABLE_VOTE}`);
321
+ }
322
+ const v = entry as Record<string, unknown>;
323
+ if (typeof v.verifier !== "string" || v.verifier === "") {
324
+ throw new Error(
325
+ `${where} has no \`verifier\` id (${shapeOf(v.verifier)}): an anonymous vote cannot be ` +
326
+ `checked for independence, so ${UNREADABLE_VOTE}`,
327
+ );
328
+ }
329
+ if (typeof v.real !== "boolean") {
330
+ throw new Error(
331
+ `${where}, from \`${v.verifier}\`, has a non-boolean \`real\` (${shapeOf(v.real)}): ` +
332
+ `agreement is counted by truthiness, so this would read as a yes — ${UNREADABLE_VOTE}`,
333
+ );
334
+ }
335
+ if (typeof v.reason !== "string") {
336
+ throw new Error(`${where}, from \`${v.verifier}\`, has no \`reason\` (${shapeOf(v.reason)}): ${UNREADABLE_VOTE}`);
337
+ }
338
+ if (v.category !== undefined && !(typeof v.category === "string" && Object.hasOwn(CATEGORY_MEMBERS, v.category))) {
339
+ throw new Error(
340
+ `${where}, from \`${v.verifier}\`, names an unknown \`category\` (${shapeOf(v.category)}): ` +
341
+ `an unrecognised category is not a dropped one, so it would read as a keep — ${UNREADABLE_VOTE}`,
342
+ );
343
+ }
344
+ if (v.severity !== undefined && !(typeof v.severity === "string" && Object.hasOwn(SEVERITY_RANK, v.severity))) {
345
+ throw new Error(
346
+ `${where}, from \`${v.verifier}\`, names an unknown \`severity\` (${shapeOf(v.severity)}): ` +
347
+ `it has no rank, so the severity sort would compare against NaN — ${UNREADABLE_VOTE}`,
348
+ );
349
+ }
350
+ return {
351
+ verifier: v.verifier,
352
+ real: v.real,
353
+ reason: v.reason,
354
+ ...(v.category !== undefined ? { category: v.category as FindingCategory } : {}),
355
+ ...(v.severity !== undefined ? { severity: v.severity as Severity } : {}),
356
+ };
357
+ });
358
+ }
359
+
360
+ export interface JuryConfig {
361
+ groupSize?: number;
362
+ quorum?: number;
363
+ }
364
+
365
+ export interface JuryReading {
366
+ reading: "MEASURED" | "UNMEASURED";
367
+ /** `true` only under a MEASURED reading that cleared the quorum. */
368
+ passed: boolean;
369
+ votes: number;
370
+ agree: number;
371
+ quorum: number;
372
+ groupSize: number;
373
+ unmeasuredReasons: string[];
374
+ }
375
+
376
+ /**
377
+ * Count the votes.
378
+ *
379
+ * Three ways this refuses rather than deciding, all of them the same doctrine
380
+ * #1187 states for the arbiter — **UNMEASURED fails, it never skips:**
381
+ *
382
+ * - **Fewer votes than the group size.** A verifier that did not report is not
383
+ * a "no" and not a "yes". Treating a short group as a complete one is how a
384
+ * quorum of three becomes a quorum of however many happened to answer, and
385
+ * the outcome looks identical either way.
386
+ * - **A repeated verifier id.** One agent run three times is one opinion.
387
+ * - **A quorum that is not a strict majority.** A configuration error that is
388
+ * undetectable from any single outcome.
389
+ *
390
+ * **The ballot size must EQUAL the declared group size, not merely reach it.**
391
+ * Accepting an over-size ballot was wrong in the same direction as everything
392
+ * else this module guards: with the 3/2 defaults, five votes of which two
393
+ * agree returned `passed: true` — 2 of 5, which is not a majority of anything,
394
+ * because the quorum was being compared against the *declaration* rather than
395
+ * against the ballot actually counted. A ballot whose cardinality disagrees
396
+ * with its declaration is UNMEASURED, not a smaller or a larger reading. A
397
+ * caller who genuinely convened five verifiers says `groupSize: 5`.
398
+ */
399
+ export function juryReading(votes: readonly VerifierVote[], config: JuryConfig = {}): JuryReading {
400
+ const groupSize = config.groupSize ?? VERIFIER_GROUP_SIZE;
401
+ const quorum = config.quorum ?? VERIFIER_QUORUM;
402
+ const agree = votes.filter(v => v.real).length;
403
+ const base = { votes: votes.length, agree, quorum, groupSize };
404
+ const unmeasuredReasons: string[] = [];
405
+
406
+ if (quorum * 2 <= groupSize || quorum < 1) {
407
+ unmeasuredReasons.push(`${NON_MAJORITY_QUORUM}: ${quorum} of ${groupSize}`);
408
+ }
409
+ if (votes.length !== groupSize) {
410
+ unmeasuredReasons.push(`${INCOMPLETE_GROUP}: ${votes.length} of ${groupSize}`);
411
+ }
412
+ if (new Set(votes.map(v => v.verifier)).size !== votes.length) {
413
+ unmeasuredReasons.push(REPEATED_VERIFIER);
414
+ }
415
+
416
+ if (unmeasuredReasons.length > 0) {
417
+ return { ...base, reading: "UNMEASURED", passed: false, unmeasuredReasons };
418
+ }
419
+ return { ...base, reading: "MEASURED", passed: agree >= quorum, unmeasuredReasons };
420
+ }
421
+
422
+ /**
423
+ * The category the jury reports.
424
+ *
425
+ * **A DROP category requires an outright majority of the real votes; a keep
426
+ * category needs only a plurality.** The asymmetry is the whole function, and
427
+ * it was measured rather than reasoned: under a plain plurality, a group of
428
+ * three that unanimously called a finding real, with **one** member tagging
429
+ * it `cleanup` and two tagging nothing, returned `cleanup` — one voice
430
+ * suppressing a finding the group passed.
431
+ *
432
+ * The source design drops style, diagnostics and cleanup because *the group*
433
+ * said so. A plurality of one is not the group, and the cost of the two error
434
+ * directions is not symmetric: wrongly keeping costs one comment thread,
435
+ * wrongly dropping withholds a real bug and leaves no artefact behind to find
436
+ * it by. So ties resolve toward keep, and a drop that cannot command a
437
+ * majority falls back to the best keep category the verifiers named, and only
438
+ * then to the keyword classifier.
439
+ */
440
+ export function juryCategory(
441
+ finding: Pick<Finding, "title" | "body">,
442
+ votes: readonly VerifierVote[],
443
+ ): FindingCategory {
444
+ const real = votes.filter(v => v.real);
445
+ const tally = new Map<FindingCategory, number>();
446
+ for (const v of real) {
447
+ if (v.category) tally.set(v.category, (tally.get(v.category) ?? 0) + 1);
448
+ }
449
+ const ranked = [...tally.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
450
+ const keep = ranked.find(([category]) => !DROPPED_CATEGORIES.has(category));
451
+
452
+ for (const [category, count] of ranked) {
453
+ if (!DROPPED_CATEGORIES.has(category)) return category;
454
+ // A drop needs a strict majority of the real votes, and must not merely
455
+ // tie with a keep category.
456
+ if (count * 2 > real.length && count > (keep?.[1] ?? 0)) return category;
457
+ break;
458
+ }
459
+ return keep?.[0] ?? classifyCategory(finding);
460
+ }
461
+
462
+ /**
463
+ * The severity tag.
464
+ *
465
+ * **`Pre-existing` is decided mechanically and beats any vote**, because it is
466
+ * the one tag of the three that is a fact about the diff rather than a
467
+ * judgement about the defect: a finding whose cited files are all absent from
468
+ * the change is about code the change never touched. Letting a verifier
469
+ * override that would put a judgement in front of a measurement.
470
+ *
471
+ * `changedFiles` absent means the diff was not read, so the pre-existing axis
472
+ * is simply not available — the votes decide, and with no votes carrying a
473
+ * tag the answer is `null` rather than a guessed `Important`.
474
+ */
475
+ export function severityOf(
476
+ finding: Pick<Finding, "title" | "body">,
477
+ votes: readonly VerifierVote[],
478
+ changedFiles?: readonly string[],
479
+ ): Severity | null {
480
+ if (changedFiles !== undefined) {
481
+ const changed = new Set(changedFiles.map(f => f.toLowerCase()));
482
+ const cited = citedPaths(finding);
483
+ if (cited.length > 0 && !cited.some(p => changed.has(p))) return "Pre-existing";
484
+ }
485
+ const tally = new Map<Severity, number>();
486
+ for (const v of votes) {
487
+ if (v.real && v.severity) tally.set(v.severity, (tally.get(v.severity) ?? 0) + 1);
488
+ }
489
+ const ranked = [...tally.entries()].sort((a, b) => b[1] - a[1] || SEVERITY_RANK[a[0]] - SEVERITY_RANK[b[0]]);
490
+ return ranked.length > 0 ? ranked[0][0] : null;
491
+ }
492
+
493
+ /** Repository-shaped paths a finding names, lowercased. Shared with the arbiter's key. */
494
+ function citedPaths(finding: Pick<Finding, "title" | "body">): string[] {
495
+ const out = new Set<string>();
496
+ for (const m of `${finding.title}\n${finding.body}`.matchAll(
497
+ /(?:[\w.@-]+\/)+[\w.-]+\.(?:ts|tsx|js|mjs|cjs|md|json|ya?ml|sh)\b/g,
498
+ )) {
499
+ out.add(m[0].toLowerCase());
500
+ }
501
+ return [...out];
502
+ }
503
+
504
+ // ── Where it goes ────────────────────────────────────────────────────────
505
+
506
+ /**
507
+ * What to do with a finding.
508
+ *
509
+ * `COMMENT` is the default and `ISSUE` is the exception. That is the inversion
510
+ * of what #1187 asked for, and it is the whole correction: a tracker issue is
511
+ * a thing nobody has to answer, so it accumulates; an inline comment blocks
512
+ * the merge until it is fixed or closed with a reason, so it does not.
513
+ */
514
+ export type Disposition = "COMMENT" | "ISSUE" | "DROP";
515
+
516
+ export const DEFAULT_DISPOSITION: Disposition = "COMMENT";
517
+
518
+ /**
519
+ * The line that makes a comment a gate rather than a remark.
520
+ *
521
+ * The source design's whole mechanism for having no backlog is that **every
522
+ * finding has to be answered** — fixed, or the thread closed with a reason —
523
+ * and the PR cannot merge while one is open. A comment that carries no such
524
+ * obligation is a tracker issue with extra steps.
525
+ */
526
+ export const MUST_BE_ANSWERED =
527
+ "Answer this before merge: fix it, or resolve this thread with a reason. " +
528
+ "A reason closes a finding; silence does not.";
529
+
530
+ /** The inline comment a surviving finding becomes. */
531
+ export function renderComment(
532
+ finding: Pick<Finding, "title" | "body">,
533
+ severity: Severity,
534
+ category: FindingCategory,
535
+ ): string {
536
+ return `**${severity}** · _${category}_ — ${finding.title}\n\n${finding.body}\n\n${MUST_BE_ANSWERED}`;
537
+ }