rungate 0.8.2 → 0.8.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +11 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rungate",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
|
|
6
6
|
"repository": {
|
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
"scripts/create-success.ts",
|
|
31
31
|
"scripts/create-sc.ts",
|
|
32
32
|
"scripts/ai-review-findings.ts",
|
|
33
|
+
"scripts/record-ai-review-unmeasured.ts",
|
|
33
34
|
"scripts/arbitrate-finding.ts",
|
|
34
35
|
"scripts/split-spec.ts",
|
|
35
36
|
"scripts/sync-sc-status.ts",
|
|
@@ -39,7 +39,47 @@
|
|
|
39
39
|
* here would be a second non-zero exit that the mutation cannot reach, and
|
|
40
40
|
* the case would go green over a refusal that no longer came from the
|
|
41
41
|
* constant.
|
|
42
|
+
*
|
|
43
|
+
* ## The one thing this file supplies rather than forwards (CRC-B4)
|
|
44
|
+
*
|
|
45
|
+
* `aiReviewJuryGate` — the verifier quorum that counts the ballot before a
|
|
46
|
+
* finding is allowed to block. It is handed in here because the reader
|
|
47
|
+
* cannot import it: three mutation batteries copy
|
|
48
|
+
* `lib/scaffold/ai-review-findings.ts` into a scratch directory carrying
|
|
49
|
+
* only its one dependency, and this gate pulls the finding arbiter and the
|
|
50
|
+
* filing gate behind it. A mutant that died on module resolution would
|
|
51
|
+
* report zero findings, which reads exactly like a guard behaving
|
|
52
|
+
* differently.
|
|
53
|
+
*
|
|
54
|
+
* **The ballot directory binds HERE, out of the environment, and never as
|
|
55
|
+
* a third positional.** `argumentsBeyondTheContract` refuses `argv[2]` and
|
|
56
|
+
* up, and one invocation it catches is a changed-file path containing a
|
|
57
|
+
* space that an unquoted expansion word-split in two (CF-6 in
|
|
58
|
+
* `test/ai-review-changed-files-step.test.ts`). Widening the argv contract
|
|
59
|
+
* by one slot to carry a ballot would make that refusal an accepted argv
|
|
60
|
+
* whose second half is read as a directory, so the refusal keeps its full
|
|
61
|
+
* width and the path arrives by a channel word-splitting cannot reach.
|
|
62
|
+
*
|
|
63
|
+
* With no `AI_REVIEW_BALLOT_DIR_ENV` set, the gate handed over is `null`
|
|
64
|
+
* and the reader behaves exactly as it did before the group existed. There
|
|
65
|
+
* is no third state: a ballot directory nothing can read is impossible
|
|
66
|
+
* here rather than refused, because the reader never learns a path it has
|
|
67
|
+
* no gate for. `test/ai-review-findings-command.test.ts` holds this file
|
|
68
|
+
* to supplying the gate when the variable is set.
|
|
42
69
|
*/
|
|
70
|
+
import { aiReviewJuryGate } from "../lib/ai-review-jury";
|
|
43
71
|
import { main } from "../lib/scaffold/ai-review-findings";
|
|
72
|
+
import { AI_REVIEW_BALLOT_DIR_ENV } from "../lib/scaffold/ai-review-step";
|
|
73
|
+
|
|
74
|
+
const ballotDir = process.env[AI_REVIEW_BALLOT_DIR_ENV];
|
|
75
|
+
const jury =
|
|
76
|
+
ballotDir === undefined || ballotDir === ""
|
|
77
|
+
? null
|
|
78
|
+
: (blocking: readonly unknown[]) => aiReviewJuryGate(blocking, ballotDir);
|
|
44
79
|
|
|
45
|
-
process.exit(main(
|
|
80
|
+
// One line, and `process.exit(main(` is load-bearing text: AC-4 in
|
|
81
|
+
// `test/ai-review-findings-command.test.ts` reads it to prove this file
|
|
82
|
+
// declares no exit code of its own. Wrapping the call across lines makes
|
|
83
|
+
// that case red for a formatting reason, which is worth knowing before
|
|
84
|
+
// reformatting it.
|
|
85
|
+
process.exit(main(process.argv.slice(2), jury));
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
...(
|
|
210
|
-
? { changedFiles: args.changedFilesArg.split(",").map(s => s.trim()).filter(Boolean) }
|
|
211
|
-
: {}),
|
|
469
|
+
...(changedFiles !== null ? { changedFiles } : {}),
|
|
212
470
|
});
|
|
213
471
|
} catch (error) {
|
|
214
|
-
|
|
215
|
-
|
|
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
|
-
|
|
220
|
-
|
|
221
|
-
|
|
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());
|