rungate 0.8.2 → 0.8.4

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 (74) 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/BunTestPathGuard.hook.ts +106 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
@@ -6,9 +6,28 @@
6
6
  *
7
7
  * Exit **0** — post it as an inline comment that must be answered.
8
8
  * Exit **3** — file it as an issue. Only reachable with `--out-of-scope`.
9
+ * Exit **4** — post it, but on ANOTHER open pull request. See below.
9
10
  * Exit **1** — drop it; the refusal and its reason are on stdout.
10
11
  * Exit **2** — usage.
11
12
  *
13
+ * ## Exit 4: the tracker is not the only other place a finding can go (#1343)
14
+ *
15
+ * About 45% of filings measured while working #1261 named a file an open pull
16
+ * request was already changing, and a tracker row about a file somebody is
17
+ * editing is a race it usually loses. The same shape arrives from the review
18
+ * side, because `ai-review` reads the MERGE REF and attributes a defect that
19
+ * lives on `main` to whichever pull request is standing closest — on
20
+ * 2026-10-23 that blocked #1393 with a `high` naming `lib/ai-review-rounds.ts`
21
+ * and #1354 with a `critical` naming `lib/bash-write-guard.ts`, neither file
22
+ * in the diff it was blocking. Both were re-routed by a person reading diffs.
23
+ *
24
+ * `lib/finding-pr-routing.ts` is that lookup, and the reading is printed on
25
+ * every run. It only CHANGES the exit when exactly one other open pull request
26
+ * holds the cited file: several holders, no holder, or a corpus that could not
27
+ * be read all leave the arbiter's own disposition alone and say so on stdout.
28
+ * A router that guessed between two candidates would be worse than the hand
29
+ * routing it replaces.
30
+ *
12
31
  * **Exit 1 is also what UNMEASURED produces.** A finding the arbiter could
13
32
  * not evaluate is not a finding that passes; that is #1187's doctrine and the
14
33
  * one behaviour here that must not be softened into a warning.
@@ -33,6 +52,27 @@
33
52
  * `--votes` is a JSON array of `{ verifier, real, reason, category?,
34
53
  * severity? }`. **It is not optional**: a finding nobody voted on has not
35
54
  * cleared a quorum, it has not had one, and those are different states.
55
+ *
56
+ * ## Every adjudication is appended to the ledger (#1467, CRC-B4)
57
+ *
58
+ * One row per run, to `ledgerPath()` — the same
59
+ * `~/.rungate/finding-ledger.jsonl` the `gh issue create` chokepoint writes,
60
+ * because the value of the two populations is the corpus they form together.
61
+ * Redirect it with `RUNGATE_FINDING_LEDGER`.
62
+ *
63
+ * This is the only writer in the tree that can fill the row's `jury`: the
64
+ * chokepoint convenes no verifier group, so every row it has ever written
65
+ * carries `null` there. The row records **every verifier's individual vote**
66
+ * and **whether they disagreed**, which is what CRC-B4 asks for and what no
67
+ * count of agreement can reconstruct — the verifiers are a sampled
68
+ * instrument, so a second ballot is a second draw and not a recovery of the
69
+ * first. See `ledgerRow` for why a DROP is recorded too.
70
+ *
71
+ * **What it still cannot record: a group of any size but three.** There is no
72
+ * `--group-size`/`--quorum` flag, so a hand-run two-verifier quorum — the
73
+ * shape of the first real split this path has seen — arrives here as a short
74
+ * ballot and is refused `INCOMPLETE_GROUP`. A flag for it is a separate
75
+ * change, and worth one.
36
76
  */
37
77
 
38
78
  import { execFileSync } from "child_process";
@@ -40,12 +80,23 @@ import { readFileSync } from "fs";
40
80
 
41
81
  import {
42
82
  arbitrate,
83
+ symptomKeys,
43
84
  UNFILED_ID,
44
85
  verdictSummary,
45
86
  type Finding,
46
87
  type Verdict,
47
88
  } from "../lib/finding-arbiter";
48
89
  import { parseVotes, renderComment, type VerifierVote } from "../lib/finding-jury";
90
+ import { filingBatch, ledgerPath, recordAdjudication, type FilingLedgerRow } from "../lib/issue-filing-gate";
91
+ import {
92
+ citedPathsFromKeys,
93
+ normalisePath,
94
+ routePaths,
95
+ routingSummary,
96
+ type OpenPrCorpus,
97
+ type OpenPullRequest,
98
+ type Routing,
99
+ } from "../lib/finding-pr-routing";
49
100
 
50
101
  interface Args {
51
102
  title: string;
@@ -59,6 +110,10 @@ interface Args {
59
110
  json: boolean;
60
111
  comment: boolean;
61
112
  limit: number;
113
+ anchorFile: string | null;
114
+ openPrsFile: string | null;
115
+ thisPr: number | null;
116
+ prLimit: number;
62
117
  }
63
118
 
64
119
  /** Exit codes, each declared once so no branch can invent its own. */
@@ -66,6 +121,45 @@ export const EXIT_COMMENT = 0;
66
121
  export const EXIT_DROP = 1;
67
122
  export const EXIT_USAGE = 2;
68
123
  export const EXIT_ISSUE = 3;
124
+ export const EXIT_OTHER_PR = 4;
125
+
126
+ /**
127
+ * The paths to route on: the anchor when the finding cites it, else the
128
+ * finding's own cited paths (#1427).
129
+ *
130
+ * The anchor narrows; it never introduces a path the finding does not name.
131
+ * Compared through `normalisePath` so `./lib/a.ts`, `lib/a.ts` and a leading
132
+ * slash are one path — otherwise the verification is defeated by spelling,
133
+ * which is the same bug one layer down.
134
+ *
135
+ * Exported because this is the whole of the trust decision, and a caller
136
+ * reading `routePaths(...)` should be able to find it as one named thing.
137
+ */
138
+ export function anchorOrCited(anchor: string | null, cited: readonly string[]): string[] {
139
+ if (anchor === null) return [...cited];
140
+ const wanted = normalisePath(anchor);
141
+ return cited.some(p => normalisePath(p) === wanted) ? [anchor] : [...cited];
142
+ }
143
+
144
+ /**
145
+ * A pull request number, or `null` for absent AND for unusable (#1427).
146
+ *
147
+ * Exported so the two states can be witnessed directly. `--this-pr` is read
148
+ * from a workflow expression, so "the expression produced nothing" arrives
149
+ * as an empty string or a literal `${{ … }}` rather than as a missing flag.
150
+ */
151
+ export function parsePrNumber(raw: string | null): number | null {
152
+ if (raw === null) return null;
153
+ const n = Number(raw.trim());
154
+ return Number.isSafeInteger(n) && n > 0 ? n : null;
155
+ }
156
+
157
+ /** Was `--this-pr` given a value this script could not use? */
158
+ export function prNumberIsUnusable(argv: readonly string[]): boolean {
159
+ const i = argv.indexOf("--this-pr");
160
+ if (i === -1 || i + 1 >= argv.length) return false;
161
+ return parsePrNumber(argv[i + 1]) === null;
162
+ }
69
163
 
70
164
  function parseArgs(argv: string[]): Args {
71
165
  const get = (flag: string): string | null => {
@@ -84,9 +178,99 @@ function parseArgs(argv: string[]): Args {
84
178
  json: argv.includes("--json"),
85
179
  comment: argv.includes("--comment"),
86
180
  limit: Number.parseInt(get("--limit") ?? "60", 10),
181
+ anchorFile: get("--file"),
182
+ openPrsFile: get("--open-prs"),
183
+ // #1427: `null` for a malformed value, never `NaN`. A NaN here is the
184
+ // worst of the three states — the router sees `thisPr !== undefined` so
185
+ // it does not refuse for a missing identity, and then
186
+ // `p.number !== NaN` is true of every row so the own-PR exclusion
187
+ // removes nothing. The pull request being arbitrated stays a candidate
188
+ // to route to, which is exactly the fail-open the refusal exists for,
189
+ // reached through a typo instead of an omission. `main` turns the null
190
+ // into EXIT_USAGE so a bad flag is reported rather than absorbed.
191
+ thisPr: parsePrNumber(get("--this-pr")),
192
+ // Its own knob, not `--limit`. That one bounds the ISSUE population and
193
+ // this one bounds the PULL REQUEST population; one flag for two
194
+ // populations would make a truncation refusal name the wrong corpus.
195
+ prLimit: Number.parseInt(get("--pr-limit") ?? "60", 10),
87
196
  };
88
197
  }
89
198
 
199
+ /**
200
+ * The open pull requests the finding is routed against (#1343).
201
+ *
202
+ * Fetched in ONE call — `gh pr list --json files` resolves each PR's diff in
203
+ * the same GraphQL query, so this is not N round-trips — and `changedFiles`
204
+ * is asked for alongside `files` so a page-limited file list is detectable
205
+ * without hardcoding whatever page size `gh` currently uses. The two numbers
206
+ * disagreeing IS the truncation detector; see `OpenPullRequest`.
207
+ *
208
+ * Every failure here is `unmeasured` and never an empty list. "No open pull
209
+ * request touches this file" is the reading that sends a finding to the
210
+ * tracker, and producing it from a `gh` that did not run is the fail-open
211
+ * this whole module exists to avoid.
212
+ */
213
+ function openPrCorpus(args: Args): OpenPrCorpus {
214
+ if (args.openPrsFile === null && !args.repo) {
215
+ return { status: "unmeasured", why: "no --repo and no --open-prs, so no pull requests were looked at" };
216
+ }
217
+ let raw: string;
218
+ try {
219
+ raw = args.openPrsFile
220
+ ? readFileSync(args.openPrsFile, "utf-8")
221
+ : execFileSync(
222
+ "gh",
223
+ ["pr", "list", "--repo", args.repo, "--state", "open",
224
+ "--limit", String(args.prLimit + 1), "--json", "number,changedFiles,files"],
225
+ { encoding: "utf-8", maxBuffer: 32 * 1024 * 1024 },
226
+ );
227
+ } catch (error) {
228
+ return { status: "unmeasured", why: `the open pull requests could not be listed: ${message(error)}` };
229
+ }
230
+ let rows: unknown;
231
+ try {
232
+ rows = JSON.parse(raw);
233
+ } catch (error) {
234
+ return { status: "unmeasured", why: `the open pull request list is not JSON: ${message(error)}` };
235
+ }
236
+ if (!Array.isArray(rows)) {
237
+ return { status: "unmeasured", why: "the open pull request list is not an array" };
238
+ }
239
+ if (args.openPrsFile === null && rows.length > args.prLimit) {
240
+ return {
241
+ status: "unmeasured",
242
+ why: `the repository returned more than --pr-limit ${args.prLimit} open pull requests, ` +
243
+ "so a PR holding the cited file may not be in the population at all",
244
+ };
245
+ }
246
+ const prs: OpenPullRequest[] = [];
247
+ for (const row of rows) {
248
+ if (row === null || typeof row !== "object") {
249
+ return { status: "unmeasured", why: "an entry in the open pull request list is not an object" };
250
+ }
251
+ const r = row as { number?: unknown; files?: unknown; changedFiles?: unknown };
252
+ const files = Array.isArray(r.files)
253
+ ? r.files.map(f => (typeof f === "string" ? f : (f as { path?: unknown })?.path)).filter((p): p is string => typeof p === "string")
254
+ : null;
255
+ if (typeof r.number !== "number" || files === null) {
256
+ return { status: "unmeasured", why: `pull request entry ${JSON.stringify(r.number)} has no number or no file list` };
257
+ }
258
+ prs.push({
259
+ number: r.number,
260
+ files,
261
+ // An absent count is not a complete one. Reporting `files.length` here
262
+ // would assert the list is whole on the strength of nothing, which is
263
+ // the one reading the truncation guard exists to refuse.
264
+ declaredFileCount: typeof r.changedFiles === "number" ? r.changedFiles : -1,
265
+ });
266
+ }
267
+ return { status: "measured", prs };
268
+ }
269
+
270
+ function message(error: unknown): string {
271
+ return error instanceof Error ? error.message : String(error);
272
+ }
273
+
90
274
  /** Raised when the comparison population could not be read in full. */
91
275
  class TruncatedPopulation extends Error {}
92
276
 
@@ -162,14 +346,76 @@ function readVotes(path: string): readonly VerifierVote[] {
162
346
  }
163
347
  }
164
348
 
165
- function emit(args: Args, verdict: Verdict, finding: Finding): void {
349
+ /**
350
+ * The adjudication, as a ledger row (#1467, CRC-B4).
351
+ *
352
+ * **One site, and it is the whole of the recording**, so a mutant copy with
353
+ * `jury: verdict.jury` set to `null` neutralises the thing under test and
354
+ * nothing else — `test/finding-arbiter.test.ts`'s `AR-25` runs that mutant
355
+ * beside the real script and `AR-26` asserts the string appears exactly once,
356
+ * because a second assignment somewhere else would survive the mutation and
357
+ * the case would go green having witnessed nothing
358
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
359
+ *
360
+ * `FilingLedgerRow` and not a new shape: the value of the two row populations
361
+ * — the chokepoint's and this one's — is the corpus they form together, and a
362
+ * second vocabulary for `category` / `refusal` / `withheldBy` would make that
363
+ * union a join nobody can write. The chokepoint cannot fill `jury`; this is
364
+ * the only writer that can, which is the point.
365
+ *
366
+ * **Written for a DROP as well as for a COMMENT, and that is the criterion
367
+ * rather than a detail.** The cheapest wrong version of this records what it
368
+ * surfaces, which satisfies every row a reader goes looking for and leaves the
369
+ * withheld population exactly as unrecoverable as it was. A candidate the
370
+ * quorum voted down is the one row that cannot be reconstructed from anywhere
371
+ * else: it is never filed, never commented on, never fixed, so it enters no
372
+ * downstream graph at all. `CandidateRecord`'s own header says it — *"written
373
+ * down at the moment the candidate is withheld, or never."*
374
+ */
375
+ export function ledgerRow(finding: Finding, verdict: Verdict, at: string): FilingLedgerRow {
376
+ const batch = filingBatch(at);
377
+ const emitted = verdict.disposition !== "DROP";
378
+ return {
379
+ at,
380
+ // `${batch}/0`: one adjudication per process here, where the hook writes
381
+ // one row per `gh issue create` clause. Same composition, so a row from
382
+ // either writer is told apart from every other on the shared ledger.
383
+ key: batch === null ? null : `${batch}/0`,
384
+ id: verdict.id,
385
+ title: finding.title,
386
+ symptomHash: verdict.symptomHash,
387
+ category: verdict.category,
388
+ severity: verdict.severity,
389
+ disposition: verdict.disposition,
390
+ refusal: verdict.refusal,
391
+ emitted,
392
+ withheldBy: emitted ? null : (verdict.refusal ?? "UNACCOUNTED"),
393
+ jury: verdict.jury,
394
+ duplicateOf: verdict.duplicateOf,
395
+ // No override exists on this path. The `arbiter-override` label is a
396
+ // `gh issue create` flag the chokepoint reads, and nothing here has one.
397
+ overridden: false,
398
+ // A ballot is cast over one candidate, not over a re-filing, so there is
399
+ // no earlier refusal of this title for it to waive. The chokepoint in
400
+ // `lib/issue-filing-gate.ts` is the writer that performs that lookup.
401
+ refiledAfter: null,
402
+ };
403
+ }
404
+
405
+ function emit(args: Args, verdict: Verdict, finding: Finding, routing: Routing | null): void {
166
406
  if (args.json) {
167
- console.log(JSON.stringify(verdict, null, 2));
168
- } else if (args.comment && verdict.disposition === "COMMENT") {
407
+ console.log(JSON.stringify({ ...verdict, routing }, null, 2));
408
+ return;
409
+ }
410
+ if (args.comment && verdict.disposition === "COMMENT") {
169
411
  console.log(renderComment(finding, verdict.severity ?? "Important", verdict.category));
170
412
  } else {
171
413
  console.log(verdictSummary(verdict));
172
414
  }
415
+ // Always printed when it was taken, including when it changed nothing. A
416
+ // routing reading that only appears when it fires is one a reader cannot
417
+ // tell from one that was never asked for.
418
+ if (routing !== null) console.log(routingSummary(routing));
173
419
  }
174
420
 
175
421
  function main(): number {
@@ -178,10 +424,19 @@ function main(): number {
178
424
  console.error(
179
425
  "usage: arbitrate-finding.ts --title <t> --body-file <p> --votes <p> " +
180
426
  "[--repo owner/name | --existing issues.json] [--project-root <p>] " +
181
- "[--changed-files a.ts,b.ts] [--out-of-scope <reason>] [--json|--comment] [--limit N]",
427
+ "[--changed-files a.ts,b.ts] [--out-of-scope <reason>] [--json|--comment] [--limit N] " +
428
+ "[--this-pr N] [--file path] [--open-prs prs.json] [--pr-limit N]",
182
429
  );
183
430
  return EXIT_USAGE;
184
431
  }
432
+ // #1427: a `--this-pr` that was GIVEN and could not be read is a usage
433
+ // error, not an absent identity. Absorbing it would make the router's
434
+ // refusal fire on a typo and read like a missing flag, and the whole
435
+ // point of that refusal is that it names what is missing.
436
+ if (prNumberIsUnusable(process.argv.slice(2))) {
437
+ console.error("--this-pr must be a positive integer; refusing rather than routing with an unreadable identity");
438
+ return EXIT_USAGE;
439
+ }
185
440
  // Not usage errors: these are stages with no input, and the doctrine for an
186
441
  // absent input is to refuse, not to skip it.
187
442
  if (!args.repo && !args.existingFile) {
@@ -200,25 +455,88 @@ function main(): number {
200
455
  ...(args.outOfScope ? { outOfScope: { reason: args.outOfScope } } : {}),
201
456
  };
202
457
 
458
+ const changedFiles =
459
+ args.changedFilesArg !== null
460
+ ? args.changedFilesArg.split(",").map(s => s.trim()).filter(Boolean)
461
+ : null;
462
+
203
463
  let verdict: Verdict;
204
464
  try {
205
465
  verdict = arbitrate(finding, {
206
466
  projectRoot: args.projectRoot,
207
467
  existing: existingFindings(args),
208
468
  votes: readVotes(args.votesFile),
209
- ...(args.changedFilesArg !== null
210
- ? { changedFiles: args.changedFilesArg.split(",").map(s => s.trim()).filter(Boolean) }
211
- : {}),
469
+ ...(changedFiles !== null ? { changedFiles } : {}),
212
470
  });
213
471
  } catch (error) {
214
- const why = error instanceof Error ? error.message : String(error);
215
- console.log(`DROP new (UNMEASURED): ${why}`);
472
+ // No verdict, so no row. The ballot is not lost with the process the way
473
+ // an in-memory one would be — it is the caller's own `--votes` file and
474
+ // is still on disk — but nothing here records that it was refused.
475
+ console.log(`DROP new (UNMEASURED): ${message(error)}`);
216
476
  return EXIT_DROP;
217
477
  }
218
478
 
219
- emit(args, verdict, finding);
220
- if (verdict.disposition === "ISSUE") return EXIT_ISSUE;
221
- return verdict.disposition === "COMMENT" ? EXIT_COMMENT : EXIT_DROP;
479
+ // ── Record the decision, at decision time ────────────────────────────────
480
+ //
481
+ // Before the routing below, which costs a `gh pr list`: a decision recorded
482
+ // only once the network answered is a decision the ledger loses whenever the
483
+ // network does. And before the exit, for every disposition — see
484
+ // `ledgerRow`.
485
+ //
486
+ // A write that fails does NOT change the exit. `recordAdjudication`'s
487
+ // standing doctrine is that a measurement apparatus must not block the thing
488
+ // it measures, and the policy over that failure is to proceed LOUDLY: the
489
+ // line below is the difference between an unrecorded decision and a silent
490
+ // one.
491
+ if (!recordAdjudication(ledgerRow(finding, verdict, new Date().toISOString()))) {
492
+ console.log(
493
+ `UNMEASURED: the adjudication could not be appended to ${ledgerPath()}, so this ballot is ` +
494
+ "not on the record — re-running would re-sample the verifiers rather than recover their votes",
495
+ );
496
+ }
497
+
498
+ // Cost order, the same doctrine `arbitrate` applies to its own stages: a
499
+ // dropped finding is going nowhere, so it is never paid a `gh pr list`.
500
+ const routing =
501
+ verdict.disposition === "DROP"
502
+ ? null
503
+ // `--file` is the payload's own anchor, and it SELECTS among the paths
504
+ // the finding cites rather than replacing them. An `ai-review` finding
505
+ // names one file, and the body around it usually names more — the
506
+ // exemplar that motivated #1343 cites the reader it is about AND the
507
+ // writer it blames. Unioning them routes a precise finding by an
508
+ // imprecise signal: run live on 2026-10-23 the full prose keys read
509
+ // AMBIGUOUS across three pull requests holding the second file, while
510
+ // the anchor alone named the one PR holding the first.
511
+ //
512
+ // #1427: it used to REPLACE them, unverified, and the agent being
513
+ // arbitrated supplies it. An anchor pointing at some other open pull
514
+ // request's files produced OTHER_PR, and the caller turns OTHER_PR
515
+ // into exit 4, which suppresses the filing — so an agent could steer
516
+ // its own adjudication into silence with one flag, and the finding's
517
+ // own cited paths were never consulted on that path.
518
+ //
519
+ // An anchor the finding does not cite is therefore IGNORED rather than
520
+ // obeyed, and routing falls back to the finding's own evidence. Not
521
+ // refused: #1416 is live and working, a wrong answer in the refusing
522
+ // direction is cheap only when it does not suppress, and falling back
523
+ // can only widen the cited set — AMBIGUOUS and TRACKER both leave the
524
+ // arbiter's disposition standing, so this path cannot newly silence
525
+ // anything.
526
+ : routePaths(anchorOrCited(args.anchorFile, citedPathsFromKeys(symptomKeys(finding))), {
527
+ corpus: openPrCorpus(args),
528
+ ...(args.thisPr !== null ? { thisPr: args.thisPr } : {}),
529
+ ...(changedFiles !== null ? { changedFiles } : {}),
530
+ });
531
+
532
+ emit(args, verdict, finding, routing);
533
+ if (verdict.disposition === "DROP") return EXIT_DROP;
534
+ // Only the unambiguous case moves the answer. AMBIGUOUS, TRACKER,
535
+ // NO_CITED_PATH and UNMEASURED all leave the arbiter's disposition standing
536
+ // — see the exit-4 section at the top of this file for why a router that
537
+ // picked between two candidates would be worse than the hand routing.
538
+ if (routing !== null && routing.route === "OTHER_PR") return EXIT_OTHER_PR;
539
+ return verdict.disposition === "ISSUE" ? EXIT_ISSUE : EXIT_COMMENT;
222
540
  }
223
541
 
224
542
  process.exit(main());