rungate 0.8.4 → 0.8.5

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/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 133dd39229ff86fc5f80fce43d9a3c806ad88e9d7d8e27b27688fc1ae27030eb
1
+ d12afb85b5ce604fa58cf050d86b431d8f5d26e9e0dc5f33320e97f7bf51bbc3
@@ -0,0 +1,295 @@
1
+ /**
2
+ * CRC-N4's suppression gate — the production caller `suppressRepeats` never
3
+ * had (#1586).
4
+ *
5
+ * `lib/ai-review-rounds.ts` has exported `carryKey → suppressRepeats` since
6
+ * #1351 and nothing called either. #1381 shipped the WALKER — the generated
7
+ * `ai-review-carry` step reads the ledger and hands the reviewer the
8
+ * unresolved set — so a repeat became *marked* rather than *dropped*. This is
9
+ * the half that drops it.
10
+ *
11
+ * ## Why the prior state arrives as a file and not as a fetch
12
+ *
13
+ * The generated job runs `ai-review-carry` → the reviewer →
14
+ * `ai-review-persist`, **which upserts this round into the ledger comment** →
15
+ * `ai-review-run`, which invokes the adjudicator. A gate that fetched the
16
+ * ledger itself would read a comment that already contains the payload it is
17
+ * deciding about: every finding would match a "prior" key that is its own,
18
+ * every round would suppress everything, and the outcome would be CLEAN
19
+ * forever. The carry step is the last position holding the state as it was
20
+ * before the reviewer ran, so it writes a snapshot and this reads it.
21
+ *
22
+ * ## Two files, because one of them cannot say why it is absent
23
+ *
24
+ * The snapshot carries BYTES and exists only on the READ path. The carry file
25
+ * carries the STATE and is written on every path by the single `carry_state`
26
+ * site. An absent snapshot therefore never means "no earlier findings" — the
27
+ * carry file says which of `AI_REVIEW_CARRY_READ`, `AI_REVIEW_CARRY_ABSENT`
28
+ * and `AI_REVIEW_CARRY_UNMEASURED` produced it. Collapsing those is #1568, in
29
+ * the half that decides a required check.
30
+ *
31
+ * ## Every refusal suppresses NOTHING
32
+ *
33
+ * There is one direction of error this module is allowed to make. Re-posting
34
+ * an advisory that was already answered is loud, cheap and self-correcting;
35
+ * dropping a finding that is still live is silent and permanent. So an
36
+ * unreadable carry file, an unreadable snapshot, a stale snapshot, an
37
+ * unrecognised identity rule and a ledger that will not parse all produce the
38
+ * same behaviour — report everything — and each produces a DIFFERENT sentence
39
+ * saying so, because "nothing was a repeat" and "nothing could be compared"
40
+ * are different facts about this round's report.
41
+ *
42
+ * ## It never sees a blocking finding
43
+ *
44
+ * `findingMustAlwaysBeReported` in `lib/scaffold/ai-review-findings.ts`
45
+ * filters before anything reaches this gate. The exemption is structural, not
46
+ * a rule this module is trusted to follow — see that predicate for the
47
+ * measurement, and for the declared deviation from the spec it rests on.
48
+ */
49
+ import { readFileSync } from "fs";
50
+ import { isAbsolute, resolve, sep } from "path";
51
+
52
+ import {
53
+ AI_REVIEW_PRIOR_MEASURED,
54
+ carryKey,
55
+ priorFindings,
56
+ readLedger,
57
+ type ReviewFinding,
58
+ } from "./ai-review-rounds";
59
+ import {
60
+ AI_REVIEW_CARRY_ABSENT,
61
+ AI_REVIEW_CARRY_READ,
62
+ AI_REVIEW_CARRY_STATE_KEY,
63
+ AI_REVIEW_CARRY_UNMEASURED,
64
+ AI_REVIEW_SNAPSHOT_ROUND_KEY,
65
+ } from "./scaffold/ai-review-step";
66
+ import type { AiReviewSuppressionGate } from "./scaffold/ai-review-findings";
67
+
68
+ /** What the gate reads, so a test can drive it without a filesystem. */
69
+ export interface SuppressionInputs {
70
+ /** The carry file's contents, or `null` when it could not be read. */
71
+ carry: string | null;
72
+ /** The snapshot's contents, or `null` when it could not be read. */
73
+ snapshot: string | null;
74
+ /** The text at a finding's cited line NOW, or `undefined`. */
75
+ lineTextFor: (finding: ReviewFinding) => string | undefined;
76
+ }
77
+
78
+ /** A prior set that was established, or the sentence saying it was not. */
79
+ export type PriorKeys =
80
+ | { status: "MEASURED"; keys: string[] }
81
+ | { status: "UNMEASURED"; reason: string };
82
+
83
+ /**
84
+ * The carry file's first line, which is the one site that decided the state.
85
+ *
86
+ * Read rather than re-derived: the walker already made this decision against
87
+ * the live API, and a second reading here would be a second decider over the
88
+ * same question — which is the shape #1568 cost three rounds of #1569.
89
+ */
90
+ export function carryStateOf(carry: string | null): string | null {
91
+ if (carry === null) return null;
92
+ const first = carry.split("\n", 1)[0] ?? "";
93
+ const prefix = `${AI_REVIEW_CARRY_STATE_KEY}=`;
94
+ return first.startsWith(prefix) ? first.slice(prefix.length).trim() : null;
95
+ }
96
+
97
+ /**
98
+ * Split the snapshot into the round it precedes and the ledger body.
99
+ *
100
+ * `round` is `null` when the header is missing or not an integer, and that is
101
+ * a REFUSAL rather than a default: a snapshot that cannot say which round it
102
+ * precedes cannot be shown to predate this one.
103
+ */
104
+ export function readSnapshot(snapshot: string): { round: number | null; body: string } {
105
+ const at = snapshot.indexOf("\n");
106
+ const head = at === -1 ? snapshot : snapshot.slice(0, at);
107
+ const body = at === -1 ? "" : snapshot.slice(at + 1);
108
+ const prefix = `${AI_REVIEW_SNAPSHOT_ROUND_KEY}=`;
109
+ if (!head.startsWith(prefix)) return { round: null, body };
110
+ const raw = head.slice(prefix.length).trim();
111
+ return { round: /^\d+$/.test(raw) ? Number(raw) : null, body };
112
+ }
113
+
114
+ /**
115
+ * Turn the two files into the keys earlier rounds raised, or the sentence
116
+ * saying they could not be established.
117
+ *
118
+ * Exported and pure so the battery can drive every refusal without a
119
+ * filesystem, and so there is one place to mutate.
120
+ */
121
+ export function priorKeysFrom(carry: string | null, snapshot: string | null): PriorKeys {
122
+ const state = carryStateOf(carry);
123
+ if (state === null) {
124
+ return {
125
+ status: "UNMEASURED",
126
+ reason:
127
+ "the carry step's own reading could not be read, so whether this pull request has " +
128
+ "earlier rounds is unknown",
129
+ };
130
+ }
131
+ if (state === AI_REVIEW_CARRY_UNMEASURED) {
132
+ return {
133
+ status: "UNMEASURED",
134
+ reason: "the carry step reported that the pull request's history could not be read",
135
+ };
136
+ }
137
+ // A complete reading, and the answer is that there is nothing to compare
138
+ // against. MEASURED with no keys, which is not the same statement as the
139
+ // branch above and must not print the same sentence.
140
+ if (state === AI_REVIEW_CARRY_ABSENT) return { status: "MEASURED", keys: [] };
141
+ if (state !== AI_REVIEW_CARRY_READ) {
142
+ return {
143
+ status: "UNMEASURED",
144
+ reason: `the carry step reported a state this reader does not know (${JSON.stringify(state)})`,
145
+ };
146
+ }
147
+
148
+ if (snapshot === null) {
149
+ return {
150
+ status: "UNMEASURED",
151
+ reason:
152
+ "the carry step read the pull request's history and the copy it left for this step " +
153
+ "could not be read",
154
+ };
155
+ }
156
+ const { round, body } = readSnapshot(snapshot);
157
+ if (round === null) {
158
+ return {
159
+ status: "UNMEASURED",
160
+ reason:
161
+ "the history copy does not say which round it precedes, so it cannot be shown to " +
162
+ "predate this round's own findings",
163
+ };
164
+ }
165
+
166
+ const reading = priorFindings(readLedger(body));
167
+ if (reading.status !== AI_REVIEW_PRIOR_MEASURED) {
168
+ return { status: "UNMEASURED", reason: reading.reason };
169
+ }
170
+
171
+ // THE ORDERING GUARD. A snapshot taken after the persist step is the same
172
+ // comment fetched the same way and is byte-shaped like a correct one; the
173
+ // only tell is that it already holds this round. Without this, the wrong
174
+ // ordering suppresses the entire payload and reports CLEAN every round.
175
+ const stale = reading.prior.filter(p => typeof p.round === "number" && p.round >= round);
176
+ if (stale.length > 0) {
177
+ return {
178
+ status: "UNMEASURED",
179
+ reason:
180
+ `the history copy holds ${stale.length} finding(s) from round ${round} or later, so it ` +
181
+ `was taken AFTER this round was recorded rather than before it. Suppressing against it ` +
182
+ `would drop this round's own findings`,
183
+ };
184
+ }
185
+
186
+ // `unmeasuredRounds` and `unkeyableRounds` are deliberately NOT a refusal.
187
+ // Both mean the key set is INCOMPLETE, and an incomplete key set suppresses
188
+ // less than a complete one — the direction this module is allowed to be
189
+ // wrong in. Refusing on them would turn a partially readable history into
190
+ // no history at all, which is the same report with a worse sentence.
191
+ return { status: "MEASURED", keys: reading.keys };
192
+ }
193
+
194
+ /**
195
+ * Build the gate the adjudicator is handed, or `null` when nothing is plumbed.
196
+ *
197
+ * `null` rather than a gate that answers "no repeats": a consumer that has
198
+ * not re-scaffolded gets exactly the reading it had before #1586, and "no
199
+ * repeat reader" is a state that cannot be confused with "the reader found
200
+ * nothing".
201
+ */
202
+ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSuppressionGate {
203
+ return (candidates: readonly unknown[]) => {
204
+ const prior = priorKeysFrom(inputs.carry, inputs.snapshot);
205
+ if (prior.status === "UNMEASURED") {
206
+ return { repeat: candidates.map(() => null), unmeasured: prior.reason };
207
+ }
208
+ // `suppressRepeats` is not called here, and that is deliberate: it
209
+ // returns partitioned LISTS, and the adjudicator's contract is
210
+ // positional. Re-deriving the position from a list would be a second
211
+ // identity derivation over findings already in order — the fault
212
+ // `AiReviewJuryGate`'s docblock names. `carryKey` is the shared rule and
213
+ // the within-round half is the growing `seen` set, exactly as
214
+ // `suppressRepeats` spells it.
215
+ const seen = new Set<string>(prior.keys);
216
+ const repeat = candidates.map(c => {
217
+ const key = carryKey(c, inputs.lineTextFor(c as ReviewFinding));
218
+ // Unkeyable CARRIES. It cannot be shown to be a repeat, and the
219
+ // direction this is allowed to be wrong in is toward reporting.
220
+ if (key === null) return null;
221
+ if (!seen.has(key)) {
222
+ seen.add(key);
223
+ return null;
224
+ }
225
+ const f = c as ReviewFinding;
226
+ return (
227
+ `${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
228
+ `raised on an earlier round of this pull request, so it is not raised again`
229
+ );
230
+ });
231
+ return { repeat, unmeasured: null };
232
+ };
233
+ }
234
+
235
+ /**
236
+ * THE KEY-SYMMETRY HALF. The text at a finding's cited line, read out of the
237
+ * checkout.
238
+ *
239
+ * `carryKey` anchors on the TEXT of the cited line and falls back to the line
240
+ * NUMBER when no text is supplied — so a caller that supplies nothing is not
241
+ * computing a weaker version of the same key, it is computing keys in a
242
+ * DIFFERENT NAMESPACE from the ledger's. The ledger records `recordedText`
243
+ * and keys `t:<text>`; a text-less caller keys `n:<line>`; the two never
244
+ * collide, so the dedupe silently suppresses nothing and every round looks
245
+ * like a round with no repeats. Measured before this landed: `kept: 1,
246
+ * suppressed: 0` on a planted exact repeat.
247
+ *
248
+ * A line that cannot be read yields `undefined` and the finding falls back to
249
+ * the number anchor — asymmetric again, for that one finding, and therefore
250
+ * reported rather than dropped.
251
+ *
252
+ * `root` bounds it. A payload is written by the reviewer and names its own
253
+ * paths, so `../../etc/passwd` is an input this must handle; `resolve`
254
+ * normalises the `..` away, which is why the containment test is on the
255
+ * RESOLVED path and not on the spelling.
256
+ */
257
+ export function checkoutLineText(root: string): (finding: ReviewFinding) => string | undefined {
258
+ const base = resolve(root);
259
+ const cache = new Map<string, string[] | null>();
260
+ return (finding: ReviewFinding) => {
261
+ const file = finding.file;
262
+ const line = finding.line;
263
+ if (typeof file !== "string" || file === "") return undefined;
264
+ if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
265
+ if (isAbsolute(file)) return undefined;
266
+ const path = resolve(base, file);
267
+ if (path !== base && !path.startsWith(base + sep)) return undefined;
268
+ if (!cache.has(path)) {
269
+ try {
270
+ cache.set(path, readFileSync(path, "utf-8").split("\n"));
271
+ } catch {
272
+ cache.set(path, null);
273
+ }
274
+ }
275
+ const lines = cache.get(path) ?? null;
276
+ if (lines === null) return undefined;
277
+ const text = lines[line - 1];
278
+ return typeof text === "string" && text.trim() !== "" ? text : undefined;
279
+ };
280
+ }
281
+
282
+ /**
283
+ * Read a path, or `null`. Absent and unreadable collapse HERE and only here,
284
+ * because the caller's three-state reading comes from the carry file's
285
+ * contents rather than from its presence — and every `null` reaching
286
+ * `priorKeysFrom` produces an UNMEASURED sentence rather than an empty set.
287
+ */
288
+ export function readOrNull(path: string | undefined): string | null {
289
+ if (path === undefined || path === "") return null;
290
+ try {
291
+ return readFileSync(path, "utf-8");
292
+ } catch {
293
+ return null;
294
+ }
295
+ }
@@ -223,8 +223,15 @@ export function classifyCategory(finding: Pick<Finding, "title" | "body">): Find
223
223
  * nothing reachable from CI could name it. Its docblock there carries the
224
224
  * input on which this and `AI_REVIEW_SEVERITIES` must disagree.
225
225
  *
226
- * Re-exported rather than moved outright so `severityOf`, the arbiter, the
227
- * filing gate and `hooks/VerifyPhaseLock.hook.ts` keep naming it here.
226
+ * Re-exported rather than moved outright so `severityOf` and the three
227
+ * modules that name the vocabulary keep naming it here:
228
+ * `lib/finding-arbiter.ts`, `lib/ai-review-jury.ts` and
229
+ * `lib/issue-filing-gate.ts`. Measured 2026-10-24, not copied: #1587's own
230
+ * brief and the spec listed `lib/failure-intake.ts` and
231
+ * `hooks/VerifyPhaseLock.hook.ts` among them and NEITHER imports this module,
232
+ * directly or transitively. `scripts/arbitrate-finding.ts` does import from
233
+ * here — `parseVotes`, `renderComment`, `VerifierVote` — but never names
234
+ * `Severity` or `SEVERITY_RANK` itself.
228
235
  */
229
236
  export { SEVERITY_RANK };
230
237
  export type { Severity };
@@ -275,6 +275,12 @@ export const AI_REVIEW_FINDINGS_TITLE = "AI review findings";
275
275
  */
276
276
  export const AI_REVIEW_ADVISORY_TITLE = "AI review advisory findings";
277
277
 
278
+ /** CRC-N4 (#1586). Repeats that were dropped, named rather than counted. */
279
+ export const AI_REVIEW_SUPPRESSED_TITLE = "AI review repeats not reported again";
280
+
281
+ /** CRC-N4 (#1586). The history could not be compared — not "no repeats". */
282
+ export const AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE = "AI review repeat check UNMEASURED";
283
+
278
284
  /**
279
285
  * A stable identity for one finding, so an answer can name it.
280
286
  *
@@ -749,6 +755,31 @@ export interface AiReviewFindingsReading {
749
755
  * already reduced.
750
756
  */
751
757
  findingTags: (Severity | null)[] | null;
758
+ /**
759
+ * Findings an earlier round already raised, DROPPED from this round's
760
+ * report (CRC-N4, #1586) — raw, named, in payload order.
761
+ *
762
+ * Never a count. "Three repeats were dropped" and "these three were
763
+ * dropped" differ exactly when somebody wants to know whether the drop was
764
+ * right, which is the only question anybody asks of a drop.
765
+ *
766
+ * `[]` means the reader ran and found no repeat. There is no `null`
767
+ * case — a run with no repeat reader simply suppresses nothing, and
768
+ * `suppressionUnmeasured` is what says the prior state could not be read.
769
+ */
770
+ suppressedReported: unknown[];
771
+ /** One line per entry in `suppressedReported`, in the same order. */
772
+ suppressionReasons: string[];
773
+ /**
774
+ * Why the prior state could not be established, or `null`.
775
+ *
776
+ * `null` with an empty `suppressedReported` is "the reader ran and nothing
777
+ * was a repeat". A sentence here is "nothing could be compared", and those
778
+ * are different facts — the second one means this round's report is a
779
+ * complete list that was never checked against the history, which is the
780
+ * distinction #1568 cost three rounds of #1569 to learn.
781
+ */
782
+ suppressionUnmeasured: string | null;
752
783
  }
753
784
 
754
785
  /**
@@ -887,6 +918,93 @@ function tagsForPayload(
887
918
  );
888
919
  }
889
920
 
921
+ /**
922
+ * Findings that are reported on EVERY round, whatever an earlier round said.
923
+ *
924
+ * ## This is the whole of CRC-N4's safety, and it is named for what it protects
925
+ *
926
+ * The deployed reviewer prompt (`buildReviewPrompt`) tells the reviewer:
927
+ *
928
+ * > CHECK EACH CARRIED FINDING AGAINST THE CODE AND RE-REPORT THE ONES THAT
929
+ * > ARE STILL TRUE … A carried finding you silently leave out is a finding
930
+ * > that has stopped being reported, and that is how a live defect reaches a
931
+ * > green check.
932
+ *
933
+ * So on every round after the first, a live unresolved finding is **supposed**
934
+ * to be in the payload, and it is key-identical to the one the ledger
935
+ * recorded. Subtracting it is therefore not a de-duplication: it is the
936
+ * deletion of the one signal the gate has. MEASURED on the real functions
937
+ * before this was written — a round-1 blocking finding, re-reported on round 2
938
+ * exactly as instructed, run through `suppressRepeats` with the ledger's keys:
939
+ *
940
+ * ```
941
+ * kept: 0 suppressed: 1 severity of what survives: []
942
+ * ```
943
+ *
944
+ * `blocking.length === 0` → `blocked: false` → `CLEAN`, which is a green
945
+ * required check over a defect a previous round blocked on. That is
946
+ * SUCCESS.md claim 4 failing inside this repository's own merge gate.
947
+ *
948
+ * ## Unclassified is protected too, and that is the three-state reading
949
+ *
950
+ * `severityBlocks` answers `true`, `false`, or `null` for a severity the
951
+ * table does not declare. Only an explicit `false` — a severity this module
952
+ * knows and knows does not block — is ever offered for suppression. `null`
953
+ * is not "does not block"; it is "nobody classified this", and dropping it
954
+ * would let an unrecognised severity become the way round the exemption.
955
+ *
956
+ * ## Widening this is a decision about the merge gate
957
+ *
958
+ * Anything that makes this return `false` more often lets a repeat stop
959
+ * blocking. `test/ai-review-suppression.test.ts` mutates it to a constant
960
+ * `false` and asserts the verdict flips from BLOCKED to CLEAN — the count
961
+ * alone is not the assertion, because a count can stay right while the
962
+ * verdict moves, and the verdict is the thing that gates.
963
+ *
964
+ * Recorded as a declared deviation from `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`
965
+ * line 480, which says the adjudicator should drop any finding matching an
966
+ * earlier round's key. The prompt above is the newer artefact and the correct
967
+ * one; the deviations table carries the reasoning so a reader finds it there.
968
+ */
969
+ export function findingMustAlwaysBeReported(finding: unknown): boolean {
970
+ if (finding === null || typeof finding !== "object" || Array.isArray(finding)) return true;
971
+ const severity = (finding as Record<string, unknown>)[AI_REVIEW_FINDING_FIELDS.severity];
972
+ return severityBlocks(severity) !== false;
973
+ }
974
+
975
+ /**
976
+ * The cross-round repeat reader, INJECTED exactly as `AiReviewJuryGate` is
977
+ * and for the same mechanical reason: three mutation batteries copy this
978
+ * module into a scratch directory carrying only `./ai-review-step`, and
979
+ * `lib/ai-review-suppression.ts` pulls `lib/ai-review-rounds.ts` behind it.
980
+ * A mutant that died on module resolution would report zero findings, which
981
+ * reads exactly like a guard behaving differently.
982
+ *
983
+ * **It never sees a blocking finding.** The caller filters with
984
+ * `findingMustAlwaysBeReported` before offering anything, so the exemption is
985
+ * structural rather than a rule the gate is trusted to follow.
986
+ *
987
+ * **Positional, like the ballot.** A map keyed by a finding's identity would
988
+ * be a SECOND derivation of that identity over a list already produced in
989
+ * order, and two findings sharing a key would share a verdict.
990
+ */
991
+ export interface AiReviewSuppressionGate {
992
+ (candidates: readonly unknown[]): {
993
+ /**
994
+ * One entry per candidate, IN INPUT ORDER: the sentence saying an earlier
995
+ * round already raised it, or `null` to report it.
996
+ */
997
+ repeat: readonly (string | null)[];
998
+ /**
999
+ * Why the prior state could not be established, or `null` when it was.
1000
+ * An unmeasured prior suppresses NOTHING — the direction this is allowed
1001
+ * to be wrong in is toward reporting a repeat twice, never toward
1002
+ * dropping something live.
1003
+ */
1004
+ unmeasured: string | null;
1005
+ };
1006
+ }
1007
+
890
1008
  function unmeasured(
891
1009
  reasons: AiReviewUnmeasuredReason[],
892
1010
  detail: string[],
@@ -897,6 +1015,14 @@ function unmeasured(
897
1015
  outcome: "UNMEASURED",
898
1016
  blocked: null,
899
1017
  reported,
1018
+ // Empty rather than null, and that is not the usual three-state reading
1019
+ // being skipped: `suppressionUnmeasured` is the field that says the
1020
+ // prior state was not established, and on an UNMEASURED payload it is
1021
+ // `readAiReviewFindings` that fills both from what `readPayload`
1022
+ // appended. Nothing was dropped on any path that reaches here.
1023
+ suppressedReported: [],
1024
+ suppressionReasons: [],
1025
+ suppressionUnmeasured: null,
900
1026
  blockingReported: null,
901
1027
  verdict: null,
902
1028
  unmeasuredReasons: reasons,
@@ -982,24 +1108,39 @@ function withScope(
982
1108
  export function readAiReviewFindings(
983
1109
  raw: string | null,
984
1110
  scope: AiReviewScopeReading = scopeNotSupplied(),
1111
+ suppress: AiReviewSuppressionGate | null = null,
985
1112
  ): AiReviewFindingsReading {
986
1113
  const preExisting: unknown[] = [];
987
1114
  // Appended to by `readPayload`, for the same reason `preExisting` is: the
988
1115
  // entries belong to the reading its caller composes, and every early return
989
1116
  // in there is a state in which the split had not happened yet.
990
1117
  const dropped: string[] = [];
1118
+ // #1586, by the same arrangement and for the same reason.
1119
+ const suppressed: unknown[] = [];
1120
+ const suppression: { reasons: string[]; unmeasured: string | null } = {
1121
+ reasons: [],
1122
+ unmeasured: null,
1123
+ };
991
1124
  const base = readPayload(
992
1125
  raw,
993
1126
  scope.status === "MEASURED" ? scope.files : undefined,
994
1127
  preExisting,
995
1128
  dropped,
1129
+ suppress,
1130
+ suppressed,
1131
+ suppression,
996
1132
  );
997
- return withScope(
998
- base,
999
- scope,
1000
- scope.status === "MEASURED" ? preExisting : null,
1001
- scope.status === "MEASURED" ? dropped : null,
1002
- );
1133
+ return {
1134
+ ...withScope(
1135
+ base,
1136
+ scope,
1137
+ scope.status === "MEASURED" ? preExisting : null,
1138
+ scope.status === "MEASURED" ? dropped : null,
1139
+ ),
1140
+ suppressedReported: suppressed,
1141
+ suppressionReasons: suppression.reasons,
1142
+ suppressionUnmeasured: suppression.unmeasured,
1143
+ };
1003
1144
  }
1004
1145
 
1005
1146
  /**
@@ -1017,6 +1158,9 @@ function readPayload(
1017
1158
  changedFiles: readonly string[] | undefined,
1018
1159
  preExisting: unknown[],
1019
1160
  dropped: string[],
1161
+ suppress: AiReviewSuppressionGate | null,
1162
+ suppressedOut: unknown[],
1163
+ suppressionOut: { reasons: string[]; unmeasured: string | null },
1020
1164
  ): AiReviewFindingsReading {
1021
1165
  if (raw === null) {
1022
1166
  return unmeasured(["FINDINGS_FILE_ABSENT"], ["no findings payload was produced"]);
@@ -1109,7 +1253,65 @@ function readPayload(
1109
1253
  /** How many findings CRC-B7 demoted. See the `agreed` computation below. */
1110
1254
  let demoted = 0;
1111
1255
 
1256
+ // ── CRC-N4, and the ONE site a repeat is dropped (#1586) ───────────────
1257
+ //
1258
+ // BEFORE the classification below, so a suppressed finding is absent from
1259
+ // `reported`, from the annotation and from the ledger alike — "dropped
1260
+ // everywhere or nowhere". A finding filtered out of one projection and
1261
+ // left in another is two answers to one question.
1262
+ //
1263
+ // Only findings `findingMustAlwaysBeReported` declines to protect are ever
1264
+ // OFFERED. The exemption is therefore structural: there is no argument the
1265
+ // gate can return that drops a blocking finding, because a blocking
1266
+ // finding is never in the list it is handed. See that predicate for the
1267
+ // measurement that made this the design.
1268
+ const offered: unknown[] = [];
1269
+ const offeredAt: number[] = [];
1112
1270
  list.forEach((item, i) => {
1271
+ if (!findingMustAlwaysBeReported(item)) {
1272
+ offered.push(item);
1273
+ offeredAt.push(i);
1274
+ }
1275
+ });
1276
+ /** Per-index reason, or null to report. Positional, never keyed. */
1277
+ const repeatOf: (string | null)[] = list.map(() => null);
1278
+ let suppressionUnmeasured: string | null = null;
1279
+ if (suppress !== null && offered.length > 0) {
1280
+ try {
1281
+ const verdict = suppress(offered);
1282
+ suppressionUnmeasured = verdict.unmeasured;
1283
+ // A gate that answered about a different number of findings than it
1284
+ // was handed has lost the positional join, and a misaligned verdict
1285
+ // suppresses the wrong finding. Refuse the whole reading rather than
1286
+ // apply part of it.
1287
+ if (verdict.repeat.length !== offered.length) {
1288
+ suppressionUnmeasured =
1289
+ `the repeat reader answered about ${verdict.repeat.length} finding(s) and was handed ` +
1290
+ `${offered.length}, so no answer could be matched to a finding and nothing was ` +
1291
+ `suppressed. Every finding this round raised is reported.`;
1292
+ } else {
1293
+ verdict.repeat.forEach((why, k) => {
1294
+ if (typeof why === "string") repeatOf[offeredAt[k]!] = why;
1295
+ });
1296
+ }
1297
+ } catch (e) {
1298
+ // FAIL TOWARD REPORTING. A reader that threw has established nothing,
1299
+ // and the cost of being wrong here is one advisory printed twice —
1300
+ // against a live finding dropped, which is silent and permanent.
1301
+ suppressionUnmeasured =
1302
+ `the repeat reader threw and nothing was suppressed: ${(e as Error).message}. Every ` +
1303
+ `finding this round raised is reported, including any an earlier round already raised.`;
1304
+ }
1305
+ }
1306
+ // Appended rather than returned, for `preExisting`'s reason: these belong
1307
+ // to the reading the caller composes, and every early return above is a
1308
+ // state in which no suppression had happened yet.
1309
+ suppressedOut.push(...list.filter((_, i) => repeatOf[i] !== null));
1310
+ suppressionOut.reasons.push(...repeatOf.filter((r): r is string => r !== null));
1311
+ suppressionOut.unmeasured = suppressionUnmeasured;
1312
+ const kept = list.filter((_, i) => repeatOf[i] === null);
1313
+
1314
+ kept.forEach((item, i) => {
1113
1315
  if (item === null || typeof item !== "object" || Array.isArray(item)) {
1114
1316
  reasons.push("FINDING_NOT_AN_OBJECT");
1115
1317
  detail.push(`finding ${i} is not an object`);
@@ -1247,9 +1449,14 @@ function readPayload(
1247
1449
  }
1248
1450
  }
1249
1451
 
1250
- const tags = tagsForPayload(list, touched);
1452
+ // Over `kept`, not over `list` (#1586). `findingTags` is parallel to
1453
+ // `reported` by index, and `reported` is now the payload MINUS the repeats
1454
+ // this round suppressed — tagging the unfiltered list would shift every tag
1455
+ // by the number of findings dropped before it, so a `Nit` would be printed
1456
+ // against an `Important`. The two have to be derived from one array.
1457
+ const tags = tagsForPayload(kept, touched);
1251
1458
 
1252
- if (reasons.length > 0) return unmeasured(reasons, detail, list, tags);
1459
+ if (reasons.length > 0) return unmeasured(reasons, detail, kept, tags);
1253
1460
 
1254
1461
  // The decision, and the only place it is made. `verdict` is compared to it
1255
1462
  // afterwards; it never contributes to it.
@@ -1272,11 +1479,17 @@ function readPayload(
1272
1479
  return {
1273
1480
  outcome,
1274
1481
  blocked,
1275
- reported: list,
1482
+ reported: kept,
1276
1483
  blockingReported: blocking,
1277
1484
  verdict,
1278
1485
  unmeasuredReasons: [],
1279
1486
  detail,
1487
+ // `readAiReviewFindings` owns these three, the way `withScope` owns the
1488
+ // two below: `readPayload` appended them to the arrays it was handed,
1489
+ // and a value here would be a second statement about the same input.
1490
+ suppressedReported: [],
1491
+ suppressionReasons: [],
1492
+ suppressionUnmeasured: null,
1280
1493
  // Both of these are `withScope`'s to set, and it is the only site that
1281
1494
  // sets either. A value here would be a second statement about the same
1282
1495
  // input, and the two could disagree.
@@ -1426,6 +1639,7 @@ export function partitionChangedFiles(
1426
1639
  export function readAiReviewFindingsFile(
1427
1640
  path: string,
1428
1641
  scope: AiReviewScopeReading = scopeNotSupplied(),
1642
+ suppress: AiReviewSuppressionGate | null = null,
1429
1643
  ): AiReviewFindingsReading {
1430
1644
  let raw: string;
1431
1645
  try {
@@ -1450,7 +1664,7 @@ export function readAiReviewFindingsFile(
1450
1664
  null,
1451
1665
  );
1452
1666
  }
1453
- return readAiReviewFindings(raw, scope);
1667
+ return readAiReviewFindings(raw, scope, suppress);
1454
1668
  }
1455
1669
 
1456
1670
  /** The sentence a refusal prints, or `null` when there is nothing to refuse. */
@@ -1687,7 +1901,7 @@ export function argumentsBeyondTheContract(argv: readonly string[]): string[] {
1687
1901
  * outcome line and the scope line, because the generated step reads the
1688
1902
  * outcome line before it reads the exit code.
1689
1903
  */
1690
- function readArgv(argv: string[]): AiReviewFindingsReading {
1904
+ function readArgv(argv: string[], suppress: AiReviewSuppressionGate | null): AiReviewFindingsReading {
1691
1905
  const extra = argumentsBeyondTheContract(argv);
1692
1906
  if (extra.length > 0) {
1693
1907
  // Scope is NOT read here. The argv is already known to be a shape this
@@ -1720,7 +1934,7 @@ function readArgv(argv: string[]): AiReviewFindingsReading {
1720
1934
  null,
1721
1935
  null,
1722
1936
  )
1723
- : readAiReviewFindingsFile(path, scope);
1937
+ : readAiReviewFindingsFile(path, scope, suppress);
1724
1938
  }
1725
1939
 
1726
1940
  /**
@@ -1730,8 +1944,12 @@ function readArgv(argv: string[]): AiReviewFindingsReading {
1730
1944
  * Returns the exit code rather than calling `process.exit`, so a test can run
1731
1945
  * it in-process as well as spawn it.
1732
1946
  */
1733
- export function main(argv: string[], jury: AiReviewJuryGate | null = null): number {
1734
- const reading = readArgv(argv);
1947
+ export function main(
1948
+ argv: string[],
1949
+ jury: AiReviewJuryGate | null = null,
1950
+ suppress: AiReviewSuppressionGate | null = null,
1951
+ ): number {
1952
+ const reading = readArgv(argv, suppress);
1735
1953
 
1736
1954
  // CRC-B4, AFTER the reading and feeding nothing back into it.
1737
1955
  //
@@ -1845,6 +2063,42 @@ export function main(argv: string[], jury: AiReviewJuryGate | null = null): numb
1845
2063
  console.log(`::notice title=${AI_REVIEW_ADVISORY_TITLE}::${escapeAnnotation(advisory)}`);
1846
2064
  }
1847
2065
 
2066
+ // CRC-N4's reading, on its own title (#1586). A `::notice`, because a
2067
+ // repeat that was dropped is the mechanism working and nothing about it
2068
+ // is a problem with the pull request.
2069
+ //
2070
+ // It NAMES them. A count cannot be argued with and cannot be audited: the
2071
+ // only question anybody asks of a suppression is whether it was right,
2072
+ // and that question needs the finding. These are advisory by construction
2073
+ // — `findingMustAlwaysBeReported` never offers a blocking finding — so
2074
+ // this annotation is the entire record that they existed.
2075
+ if (reading.suppressedReported.length > 0) {
2076
+ console.log(
2077
+ `::notice title=${AI_REVIEW_SUPPRESSED_TITLE}::${escapeAnnotation(
2078
+ `${reading.suppressedReported.length} advisory finding(s) were raised on an earlier ` +
2079
+ `round of this pull request and are not reported again: ` +
2080
+ `${reading.suppressionReasons.join("; ")}. A BLOCKING finding is never suppressed, ` +
2081
+ `on any round, at any key — it is re-reported and it blocks exactly as it did the ` +
2082
+ `first time.`,
2083
+ )}`,
2084
+ );
2085
+ }
2086
+
2087
+ // A `::warning`, and the state is NAMED, for `AI_REVIEW_JURY_UNMEASURED`'s
2088
+ // reason. An unreadable history that printed nothing would make "no
2089
+ // repeats were found" and "the history could not be compared" the same
2090
+ // observation, which is #1568 arriving one subsystem over.
2091
+ if (reading.suppressionUnmeasured !== null) {
2092
+ console.log(
2093
+ `::warning title=${AI_REVIEW_SUPPRESSED_UNMEASURED_TITLE}::${escapeAnnotation(
2094
+ `What earlier rounds of this pull request raised could not be established: ` +
2095
+ `${reading.suppressionUnmeasured}. Nothing was suppressed, so this round's report ` +
2096
+ `is complete and was simply never compared against the history. No finding's ` +
2097
+ `status changed either way.`,
2098
+ )}`,
2099
+ );
2100
+ }
2101
+
1848
2102
  // The quorum's own reading, on its own title, and emitted whatever the
1849
2103
  // outcome was. The ledger row is the durable record and it lives on the
1850
2104
  // runner, which dies with the job; this annotation is the only part of
@@ -1752,6 +1752,75 @@ export const AI_REVIEW_CARRY_PATH_VAR = "AI_REVIEW_CARRY_PATH";
1752
1752
  /** The basename inside the findings directory. One spelling. */
1753
1753
  export const AI_REVIEW_CARRY_BASENAME = "ai-review-carried.txt";
1754
1754
 
1755
+ /**
1756
+ * Where the carry step leaves the ledger comment's BODY, verbatim, for the
1757
+ * adjudicator to re-read in TypeScript (CRC-N4, #1586).
1758
+ *
1759
+ * ## Why a snapshot and not a fetch at adjudication time
1760
+ *
1761
+ * The step order is `AI_REVIEW_CARRY_STEP_ID` → the reviewer →
1762
+ * `AI_REVIEW_PERSIST_STEP_ID`, which upserts THIS round into the ledger
1763
+ * comment → `AI_REVIEW_RUN_STEP_ID`, which adjudicates. An adjudicator
1764
+ * that fetched the ledger itself would read a comment that already contains
1765
+ * the payload it is deciding about, so every finding would match a "prior"
1766
+ * key that is its own, and the suppression would empty the payload on every
1767
+ * round while looking like it worked. The prior state has to be the one that
1768
+ * existed BEFORE the reviewer ran, and the carry step is the only position
1769
+ * that holds it.
1770
+ *
1771
+ * ## Why the raw body rather than the keys
1772
+ *
1773
+ * `carryKey` is not restated in jq. The carry script reaches the body and
1774
+ * stops; `readLedger → priorFindings` forms every key in TypeScript, so
1775
+ * there is ONE decider for what a finding's identity is. A second
1776
+ * implementation in jq would be the #1568 shape again — two readers of the
1777
+ * same bytes, disagreeing on a case neither author thought to name.
1778
+ *
1779
+ * ## Written on the READ path only, and that is not a conflation
1780
+ *
1781
+ * An absent snapshot does not mean "no prior findings": the state is read
1782
+ * from `AI_REVIEW_CARRY_BASENAME`, which is written on EVERY path and is
1783
+ * the single site that decides it. UNMEASURED and ABSENT both reach the
1784
+ * adjudicator as "suppress nothing", but only one of them says the record
1785
+ * could not be read, and the adjudicator reports which.
1786
+ */
1787
+ export const AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR = "AI_REVIEW_LEDGER_SNAPSHOT_PATH";
1788
+
1789
+ /** The basename inside the findings directory. One spelling. */
1790
+ export const AI_REVIEW_LEDGER_SNAPSHOT_BASENAME = "ai-review-ledger-snapshot.txt";
1791
+
1792
+ /**
1793
+ * The round the snapshot was taken BEFORE, handed to the carry step so the
1794
+ * snapshot can carry its own provenance (#1586).
1795
+ *
1796
+ * ## What this exists to make falsifiable
1797
+ *
1798
+ * A snapshot taken at `AI_REVIEW_PERSIST_STEP_ID` instead of at the carry
1799
+ * step is byte-shaped exactly like a correct one — it is the same comment,
1800
+ * fetched the same way, by the same selector. The only thing that
1801
+ * distinguishes them is that the later one already contains THIS round, so
1802
+ * every finding in the payload matches a "prior" key that is its own and the
1803
+ * adjudicator suppresses the entire round. That failure reports as a clean
1804
+ * review on every round forever, which is the reading that looks most like
1805
+ * success.
1806
+ *
1807
+ * So the snapshot states the round it precedes, and the reader refuses a
1808
+ * snapshot containing a round at or past it. The refusal is UNMEASURED and
1809
+ * suppresses nothing, so the wrong-ordering mutant fails toward reporting.
1810
+ */
1811
+ export const AI_REVIEW_SNAPSHOT_ROUND_VAR = "AI_REVIEW_SNAPSHOT_ROUND";
1812
+
1813
+ /**
1814
+ * The snapshot's first line: `taken_before_round=<N>`. Everything after the
1815
+ * first newline is the ledger comment's body, verbatim and unescaped.
1816
+ *
1817
+ * A single header line rather than a JSON envelope, because the body is
1818
+ * arbitrary text that must survive byte-for-byte: `readLedger` is the one
1819
+ * decider for what it means, and re-encoding it here would be a second
1820
+ * format for that reader to disagree with.
1821
+ */
1822
+ export const AI_REVIEW_SNAPSHOT_ROUND_KEY = "taken_before_round";
1823
+
1755
1824
  /** The annotation title every carry warning is filed under. */
1756
1825
  export const AI_REVIEW_CARRY_TITLE = "AI review carry-forward";
1757
1826
 
@@ -4696,6 +4765,37 @@ if ! carried_count=\$(printf '%s' "\${carried}" | jq 'length'); then
4696
4765
  fi
4697
4766
 
4698
4767
  carry_state '${AI_REVIEW_CARRY_READ}'
4768
+
4769
+ # The ledger's own bytes, for the adjudicator to key in TypeScript (#1586).
4770
+ #
4771
+ # HERE and not at adjudication time: the persist step upserts THIS round into
4772
+ # that same comment before the adjudicator runs, so a later fetch would read
4773
+ # the payload it is deciding about as its own prior and suppress all of it.
4774
+ #
4775
+ # ON THE READ PATH ONLY, and after the parse above succeeded. The state the
4776
+ # adjudicator gates on lives in the carry file, which \`carry_state\` writes on
4777
+ # every path — so an absent snapshot is never read as "no earlier findings",
4778
+ # it is read as whichever of the three states that one site recorded.
4779
+ #
4780
+ # A failed write is a WARNING and not a refusal: the carry itself succeeded
4781
+ # and the reviewer's copy is already on disk. The adjudicator seeing no
4782
+ # snapshot suppresses nothing, which is the direction this is allowed to be
4783
+ # wrong in — a repeat gets posted twice, rather than a live finding dropped.
4784
+ if [ -n "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}:-}" ]; then
4785
+ # The provenance line FIRST, then the body verbatim. The reader refuses a
4786
+ # snapshot holding a round at or past this number, which is the only thing
4787
+ # that tells a snapshot taken here from one taken after the persist step —
4788
+ # they are otherwise the same comment fetched by the same selector, and the
4789
+ # later one suppresses the whole round it is deciding about.
4790
+ if ! {
4791
+ printf '%s=%s\\n' '${AI_REVIEW_SNAPSHOT_ROUND_KEY}' "\${${AI_REVIEW_SNAPSHOT_ROUND_VAR}:-}"
4792
+ printf '%s' "\${selected}" | jq -r '.body // ""'
4793
+ } > "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"; then
4794
+ rm -f "\${${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}}"
4795
+ carry_note "the ledger's own text could not be written for the adjudicator, so repeats will not be suppressed on this round. Every finding this round raises is reported, including any an earlier round already raised."
4796
+ fi
4797
+ fi
4798
+
4699
4799
  {
4700
4800
  printf 'carried_count=%s\\n' "\${carried_count}"
4701
4801
  printf 'unmeasured_rounds=%s\\n' "\${unmeasured_rounds}"
@@ -10152,6 +10252,15 @@ export function buildReviewRunStep(
10152
10252
  // Composed from the prepare step's output rather than spelled again, so
10153
10253
  // there is one declaration of where that directory is.
10154
10254
  ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10255
+ // #1586. The same directory and the same composition rule. This step is
10256
+ // the WRITER of the snapshot; the adjudicator step below names the same
10257
+ // path from the same prepare-step output, so the two agree by
10258
+ // construction rather than through an output this step might not reach.
10259
+ ` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
10260
+ // The round this snapshot precedes, so it carries its own provenance.
10261
+ // Unset is not fatal: the reader refuses an unreadable provenance the
10262
+ // same way it refuses a stale one, by suppressing nothing.
10263
+ ` ${AI_REVIEW_SNAPSHOT_ROUND_VAR}: \${{ steps.${AI_REVIEW_ROUNDS_STEP_ID}.outputs.${AI_REVIEW_ROUND_OUTPUT} }}`,
10155
10264
  ` run: |`,
10156
10265
  ...buildCarryScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
10157
10266
  ];
@@ -10300,6 +10409,18 @@ export function buildReviewRunStep(
10300
10409
  // when the writer did not reach it, the file is simply absent, which is
10301
10410
  // `CHANGED_FILES_UNREADABLE` and not a green check.
10302
10411
  ` ${AI_REVIEW_CHANGED_FILES_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CHANGED_FILES_BASENAME}`,
10412
+ // #1586, and restated here for #826's reason like the line above: a
10413
+ // step's `env:` does not carry to a later step. The carry step WROTE the
10414
+ // snapshot; these are the adjudicator's own copies, composed from the
10415
+ // same prepare output so the reader cannot be pointed at a path the
10416
+ // writer did not use.
10417
+ //
10418
+ // BOTH paths, and that is the point. The snapshot alone cannot say why
10419
+ // it is absent, and an absent snapshot read as "no earlier findings" is
10420
+ // the #1568 conflation arriving in the half that decides a required
10421
+ // check. The carry file carries the state; this one carries the bytes.
10422
+ ` ${AI_REVIEW_CARRY_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_CARRY_BASENAME}`,
10423
+ ` ${AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR}: \${{ steps.${AI_REVIEW_PREPARE_STEP_ID}.outputs.${AI_REVIEW_FINDINGS_DIR_OUTPUT} }}/${AI_REVIEW_LEDGER_SNAPSHOT_BASENAME}`,
10303
10424
  ` ${AI_REVIEW_EXECUTION_FILE_VAR}: \${{ steps.${AI_REVIEW_ACTION_STEP_ID}.outputs.execution_file }}`,
10304
10425
  // CRC-B1. The PATH, so the read-check can look for that exact string in
10305
10426
  // the transcript. #826 is why this is restated rather than inherited: a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.4",
3
+ "version": "0.8.5",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -66,10 +66,42 @@
66
66
  * here rather than refused, because the reader never learns a path it has
67
67
  * no gate for. `test/ai-review-findings-command.test.ts` holds this file
68
68
  * to supplying the gate when the variable is set.
69
+ *
70
+ * ## The second thing it supplies (CRC-N4, #1586)
71
+ *
72
+ * `aiReviewSuppressionGate` — the "no repeats" subtraction. Same reasoning
73
+ * as the jury, twice over: `lib/ai-review-suppression.ts` pulls
74
+ * `lib/ai-review-rounds.ts` behind it, which the batteries do not copy, and
75
+ * it reads the CHECKOUT, which a reader running from a scratch directory
76
+ * does not have.
77
+ *
78
+ * It takes TWO paths, and that is the part worth not collapsing. The carry
79
+ * file holds the carry step's own three-state reading and is written on
80
+ * every path; the snapshot holds the ledger's bytes and exists only on the
81
+ * READ path. An absent snapshot is therefore not "no prior findings" — the
82
+ * carry file says which. Unset either and the gate is `null`: a consumer on
83
+ * an older scaffold gets the pre-#1586 reading, not a silent "nothing was a
84
+ * repeat".
85
+ *
86
+ * **A blocking finding never reaches this gate.**
87
+ * `findingMustAlwaysBeReported` filters first, inside the reader, so no
88
+ * answer the gate could give can drop one. That is a structural exemption
89
+ * rather than a rule the gate is trusted with, and it is a declared
90
+ * deviation from CRC-N4 as written — see the deviations table in
91
+ * `specs/CODE-REVIEW-CONVERGENCE-SPEC.md`.
69
92
  */
70
93
  import { aiReviewJuryGate } from "../lib/ai-review-jury";
94
+ import {
95
+ aiReviewSuppressionGate,
96
+ checkoutLineText,
97
+ readOrNull,
98
+ } from "../lib/ai-review-suppression";
71
99
  import { main } from "../lib/scaffold/ai-review-findings";
72
- import { AI_REVIEW_BALLOT_DIR_ENV } from "../lib/scaffold/ai-review-step";
100
+ import {
101
+ AI_REVIEW_BALLOT_DIR_ENV,
102
+ AI_REVIEW_CARRY_PATH_VAR,
103
+ AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR,
104
+ } from "../lib/scaffold/ai-review-step";
73
105
 
74
106
  const ballotDir = process.env[AI_REVIEW_BALLOT_DIR_ENV];
75
107
  const jury =
@@ -77,9 +109,20 @@ const jury =
77
109
  ? null
78
110
  : (blocking: readonly unknown[]) => aiReviewJuryGate(blocking, ballotDir);
79
111
 
112
+ const carryPath = process.env[AI_REVIEW_CARRY_PATH_VAR];
113
+ const snapshotPath = process.env[AI_REVIEW_LEDGER_SNAPSHOT_PATH_VAR];
114
+ const suppress =
115
+ carryPath === undefined || carryPath === ""
116
+ ? null
117
+ : aiReviewSuppressionGate({
118
+ carry: readOrNull(carryPath),
119
+ snapshot: readOrNull(snapshotPath),
120
+ lineTextFor: checkoutLineText(process.cwd()),
121
+ });
122
+
80
123
  // One line, and `process.exit(main(` is load-bearing text: AC-4 in
81
124
  // `test/ai-review-findings-command.test.ts` reads it to prove this file
82
125
  // declares no exit code of its own. Wrapping the call across lines makes
83
126
  // that case red for a formatting reason, which is worth knowing before
84
127
  // reformatting it.
85
- process.exit(main(process.argv.slice(2), jury));
128
+ process.exit(main(process.argv.slice(2), jury, suppress));