rungate 0.8.13 → 0.8.14

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 (40) hide show
  1. package/README.md +82 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  4. package/lib/ai-review-rounds.ts +99 -0
  5. package/lib/ai-review-suppression.ts +200 -21
  6. package/lib/bash-write-guard.ts +50 -5
  7. package/lib/board-flow.ts +235 -0
  8. package/lib/board-lane-health.ts +381 -0
  9. package/lib/board-mirror.ts +53 -35
  10. package/lib/board-ready-fanout.ts +56 -13
  11. package/lib/board-ready-rule.ts +545 -0
  12. package/lib/board-throughput.ts +136 -0
  13. package/lib/board-walkthrough.ts +240 -0
  14. package/lib/body-evidence.ts +203 -0
  15. package/lib/branch-protection.ts +399 -9
  16. package/lib/conformity.ts +95 -2
  17. package/lib/filing-compliance.ts +367 -0
  18. package/lib/finding-arbiter.ts +79 -5
  19. package/lib/generators/agents-md.ts +149 -0
  20. package/lib/github.ts +79 -0
  21. package/lib/graphql-cursor.ts +80 -0
  22. package/lib/issue-create-override.ts +415 -3
  23. package/lib/issue-decomposition.ts +33 -3
  24. package/lib/issue-file-overlap.ts +340 -0
  25. package/lib/issue-filing-gate.ts +173 -8
  26. package/lib/issue-repair.ts +13 -9
  27. package/lib/issue-shape.ts +196 -0
  28. package/lib/scaffold/ai-review-findings.ts +9 -1
  29. package/lib/scaffold/ai-review-step.ts +35 -1
  30. package/lib/source-census.ts +108 -0
  31. package/lib/spec-deps.ts +34 -11
  32. package/lib/spec-placement.ts +108 -0
  33. package/lib/stage-ladder.ts +28 -3
  34. package/lib/work-status.ts +423 -0
  35. package/package.json +1 -1
  36. package/scripts/ai-review-findings.ts +8 -13
  37. package/scripts/ai-review-threads.ts +16 -17
  38. package/scripts/board-mirror.ts +221 -8
  39. package/scripts/generate-code-map.ts +1 -1
  40. package/scripts/plan-spec.ts +79 -1
package/README.md ADDED
@@ -0,0 +1,82 @@
1
+ # RunGate
2
+
3
+ A ship harness for AI-first development: from issue to merged PR, with a report you can trust.
4
+
5
+ You should be able to trust that report without checking it again by hand. Coding agents can write a lot of code quickly. The hard part is believing what they say about it. "Tests pass", "0 regressions" and "security: clean" are only useful if the thing reporting them could have said something else. RunGate is built around that. The automation isn't really the product. The product is a report you don't have to re-measure.
6
+
7
+ > **Status: active development, pre-1.0.** Published on npm as [`rungate`](https://www.npmjs.com/package/rungate). It is used daily on this repo and is being proven on a second, unrelated project. Expect breaking changes between minor versions.
8
+
9
+ ## What it does
10
+
11
+ RunGate sits between an issue tracker and a coding agent (Claude Code today; the design is agent-agnostic) and runs every change through a fixed pipeline:
12
+
13
+ ```
14
+ issue → SCOPE → BUILD → VERIFY → CLOSE → SHIP_PASSED | SHIP_FAILED
15
+ ```
16
+
17
+ - **Gates, not guidelines.** Each phase ends at a gate: typecheck, tests, test-first sequencing, security review, compliance grade, review currency, and commit receipt. A failed gate stops the ship. It is not just written into a log.
18
+ - **Specs with checkable criteria.** Work is driven by specs whose success criteria name the evidence that proves them. A criterion ticked without evidence is refused.
19
+ - **Spec → board, automatically.** A spec's phases become milestones, issues and `blocked by` edges on the GitHub project board. Nobody has to place the plan there by hand.
20
+ - **Project-specific agent rules.** `scaffold` gives a repo its agent files and a conformity suite. `extract-constraints` mines the repo's own docs and history for rules an agent couldn't work out from the code.
21
+ - **AI review that blocks.** AI code-review findings are judged and posted as review threads on the PR diff, and a blocking finding fails the check.
22
+ - **Workflows** for `ship`, `prove` (reproduce and attest a fix), `verify`, `batch-ship`, `ship-and-heal` and multi-agent `council` decisions.
23
+
24
+ ## What "done" means
25
+
26
+ The project measures itself against falsifiable claims in [`SUCCESS.md`](SUCCESS.md). Each claim has a named check:
27
+
28
+ 1. **Every gate can fail, and has been seen failing.** A mutant with the refusal removed must ship where the real gate refuses.
29
+ 2. **Every number a run reports describes the committed tree.** No figure can come from before the last edit it describes.
30
+ 3. **A bad ship is stopped, not described.** Every verdict the harness computes can return `SHIP_FAILED`.
31
+ 4. **"Could not measure" never reads as "nothing wrong."** Missing, empty or broken input is a separate, loud result.
32
+ 5. **It works on a repo that isn't this one.**
33
+ 6. **A managed repo carries its own rules**, mined from that repo's history, not just a generic baseline.
34
+ 7. **The plan is on the tracker, and no person or agent put it there.**
35
+
36
+ A green test suite, a passing gate and a merged PR don't count as progress unless they meet these claims. Each of them has been wrong in this repo before.
37
+
38
+ ## Where it stands
39
+
40
+ - **Working:** the ship pipeline and gates, the spec tooling, AI-review adjudication, scaffolding, and release automation to npm. About 1,500 commits and 900 merged PRs, most shipped through the harness itself. Since 2026-10-19 the repo has been shipping directly while RunGate is stabilised.
41
+ - **In progress:** the *engine*. The goal is for a spec to become a readable project board with no hand-run steps ([ADR-009](docs/adr/ADR-009-engine-goal-and-build-order.md)), and for issue intake to be governed so every issue names the criterion it serves.
42
+ - **Next:** a full run on a consumer project with a different config layout (claim 5). Until that is done, consumer support is unproven.
43
+
44
+ Live session-by-session state is in [`PROJECT-STATE.md`](PROJECT-STATE.md).
45
+
46
+ ## Quick start
47
+
48
+ Requires [Bun](https://bun.sh).
49
+
50
+ ```bash
51
+ # In the repository you want to manage
52
+ bunx rungate scaffold . # agent files, rules and conformity suite
53
+ bunx rungate create-success # seed SUCCESS.md: what the project is for
54
+ bunx rungate create-spec "Title" # a spec with checkable success criteria
55
+ bunx rungate board-mirror --project <id> # show the spec's criteria on the project board
56
+ bunx rungate board-conformance # does the board match the spec? non-zero if not
57
+ bunx rungate --help # every command and its arguments
58
+ ```
59
+
60
+ Projects are configured in `.claude/rungate.json` (project slug, code and issue repos, dev/test/prod commands). See [`HARNESS.md`](HARNESS.md) for the schema and workflow entry points.
61
+
62
+ ## Repository layout
63
+
64
+ | Path | What lives there |
65
+ |---|---|
66
+ | `bin/`, `lib/` | CLI and core library |
67
+ | `gates/` | Gate runner, ship orchestrator and gate tests |
68
+ | `workflows/` | `ship`, `prove`, `verify`, `council` and friends |
69
+ | `specs/` | Specs that govern the harness's own behaviour |
70
+ | `docs/adr/` | Architecture decisions |
71
+ | `templates/`, `prompts/` | What `scaffold` writes and the agents read |
72
+ | `test/` | The suite. Run with `bun scripts/test-clean-env.ts` |
73
+
74
+ ## Development
75
+
76
+ ```bash
77
+ bun install
78
+ bun scripts/test-clean-env.ts # the suite in a clean environment (trust this one)
79
+ bun test <file> # a single file
80
+ ```
81
+
82
+ Start with [`AGENTS.md`](AGENTS.md) and [`CODE-MAP.md`](CODE-MAP.md).
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 747398b3ddaddadd72ae597e21f050587654bc584d2f72286d66b4c2a921e001
1
+ c12fa16b484d2832d774f0c27f2e81e29259ed31eb32ca4332faa9ed6b42face
@@ -5,9 +5,9 @@
5
5
  * SC-370 (HOOK-ARCHITECTURE-SPEC): Hook SC traceability
6
6
  * SC-371 (HOOK-ARCHITECTURE-SPEC): No hook exceeds 150 lines
7
7
  *
8
- * TWO independent gates on one chokepoint — `gh issue create` reaching Bash.
9
- * Both decisions live in lib/ and not here (#365, HOOK-ARCHITECTURE-SPEC:
10
- * hooks are thin triggers).
8
+ * TWO independent gates on one chokepoint — a filing reaching Bash, in any
9
+ * spelling `createsIssue` knows (#1759). Both decisions live in lib/ and
10
+ * not here (#365, HOOK-ARCHITECTURE-SPEC: hooks are thin triggers).
11
11
  *
12
12
  * 1. **The VERIFY-phase lock** (#443, #365). Workflow discipline: during
13
13
  * VERIFY, use verifyBlockers[] instead. Waived by the override labels in
@@ -585,6 +585,105 @@ export function carryKey(finding: unknown, lineText?: unknown): string | null {
585
585
  return `${file}\u0000${anchor}\u0000${summary}`;
586
586
  }
587
587
 
588
+ /**
589
+ * THE SAME KEY WITH THE WORDING DROPPED — `file \0 t:<text>` (#1168).
590
+ *
591
+ * @identity file+text — `file` and the TEXT of the cited line, and nothing
592
+ * else. It answers a THIRD question, which is why it has a third name: not
593
+ * *is this the same finding* (`carryKey`, which adds the summary) and not
594
+ * *is this worth adjudicating* (`advisoryKey`), but **is this the same PLACE
595
+ * an earlier round already objected to**. It is derived from a `carryKey`
596
+ * string rather than from a finding, so the two cannot drift apart: there is
597
+ * no second parse of a finding here to disagree with the first.
598
+ *
599
+ * `carryKey` ends in the summary, and `suppressRepeats`' docblock below
600
+ * states what that buys: *a finding whose summary changed is not [a repeat]*.
601
+ * That was a deliberate trade — protect a genuinely different finding that
602
+ * happens to sit at a line an earlier round cited — and the measurement says
603
+ * it costs everything to buy nothing.
604
+ *
605
+ * Read on the last 25 merged pull requests of this repository, 25 round-2+
606
+ * findings: **0 repeats the full key could see, and 8 real ones**. Every one
607
+ * of the eight was the same defect restated in different words, every one
608
+ * confirmed by reading the pair, and **zero** were the case the summary
609
+ * component protects. The reviewer rewords on essentially every re-raise, so
610
+ * the population the full key can match is empty by construction — the `0` is
611
+ * the shape of the key, not the state of the repo.
612
+ *
613
+ * ## Only a TEXT anchor, and that is the whole safety argument
614
+ *
615
+ * `carryKey` falls back to `n:<line>` when the caller could not read the
616
+ * line. Two unrelated findings at line 4 of one file share that namespace and
617
+ * nothing else, so matching on it would suppress across completely different
618
+ * defects. This returns `null` for `n:` and the caller suppresses nothing —
619
+ * which also keeps the asymmetry `checkoutLineText`'s docblock describes from
620
+ * turning into over-suppression when a checkout cannot be read.
621
+ *
622
+ * ## A TEXT anchor is not automatically a DISTINCTIVE one
623
+ *
624
+ * A line reading `}` or `return null;` keys the same anchor wherever it
625
+ * recurs in its file, so two findings at two different occurrences collide
626
+ * here and this cannot tell them apart. That screen is the CALLER's, not
627
+ * this function's — it needs the file, and this takes a string. See
628
+ * `checkoutLineReader` and the uniqueness condition in
629
+ * `lib/ai-review-suppression.ts`.
630
+ *
631
+ * Measured on the same 25 pull requests, 60 findings carrying a text anchor:
632
+ * **5 — 8.3% — cite a line whose text recurs in its own file.** A minimum
633
+ * anchor LENGTH does not separate them and was the fix not taken: four of the
634
+ * five normalise to over twenty characters and one to forty-five
635
+ * (`for (const t of tokenize(heredocView(cmd))) {`). Counting occurrences is
636
+ * the only screen the reading supports.
637
+ *
638
+ * ## The direction this is allowed to be wrong in has CHANGED, deliberately
639
+ *
640
+ * Everything else here errs toward reporting a repeat twice. This errs toward
641
+ * calling two differently-worded findings one finding, which can be wrong,
642
+ * which is why the caller must report a DIFFERENT reason for it: a reader has
643
+ * to be able to tell a verbatim re-post from a judgement. The judgement is
644
+ * the only one of the two that can be appealed.
645
+ *
646
+ * Exported and total so there is one binding to mutate, and so the battery
647
+ * can drive it without a thread list.
648
+ */
649
+ export function anchorOnlyKey(key: string | null): string | null {
650
+ if (typeof key !== "string") return null;
651
+ const parts = key.split("\u0000");
652
+ if (parts.length !== 3) return null;
653
+ const [file, anchor] = parts as [string, string, string];
654
+ if (!anchor.startsWith("t:") || anchor === "t:") return null;
655
+ if (file === "") return null;
656
+ return `${file}\u0000${anchor}`;
657
+ }
658
+
659
+ /**
660
+ * The normalised TEXT out of an anchor key, so the distinctiveness screen
661
+ * counts occurrences of the same string the key was built from (#1861).
662
+ *
663
+ * Not an identity and never used as one — it returns a component, and that
664
+ * is why it is not named `…Key`. It exists so the caller does not re-derive
665
+ * the text from the finding: a second derivation is a second decider, and the
666
+ * two would agree until one of them was mutated, at which point the other
667
+ * holds every case up. `null` for anything `anchorOnlyKey` would reject.
668
+ */
669
+ export function anchorTextOf(anchorKey: string | null): string | null {
670
+ if (typeof anchorKey !== "string") return null;
671
+ const parts = anchorKey.split("\u0000");
672
+ if (parts.length !== 2) return null;
673
+ const anchor = parts[1] as string;
674
+ if (!anchor.startsWith("t:") || anchor === "t:") return null;
675
+ return anchor.slice(2);
676
+ }
677
+
678
+ /**
679
+ * The normalisation `carryKey` applies to a cited line, exported so a reader
680
+ * counting occurrences of that line compares like with like. One binding; a
681
+ * private copy in the reader would be the two-deciders fault again.
682
+ */
683
+ export function normaliseLineText(v: unknown): string {
684
+ return normalise(v);
685
+ }
686
+
588
687
  export interface SuppressionReading {
589
688
  /** Findings this round may report. */
590
689
  kept: ReviewFinding[];
@@ -14,8 +14,11 @@
14
14
  * reformat moves — measured on #1616 as 11 threads for 3 findings. A thread
15
15
  * is GitHub's own answer to the same question, so AC-1 moved the gate onto
16
16
  * it: `priorKeysFrom` reads the list the carry step fetched and nothing else.
17
- * The ledger reader is kept as `ledgerPriorKeysFrom`, called by no production
18
- * path, until AC-5 stops writing the snapshot it parses.
17
+ * The ledger reader that used to sit beside it is GONE — AC-5 stopped writing
18
+ * the snapshot it parsed and `ledgerPriorKeysFrom`, `readSnapshot` and
19
+ * `carryStateOf` were deleted with it. `test/ai-review-suppression.test.ts`
20
+ * (AS-0b) asserts all three stay absent, so this paragraph cannot go stale
21
+ * again in the other direction.
19
22
  *
20
23
  * ## Why the prior state arrives as a file and not as a fetch
21
24
  *
@@ -56,7 +59,10 @@ import { isAbsolute, resolve, sep } from "path";
56
59
 
57
60
  import {
58
61
  AI_REVIEW_PRIOR_MEASURED,
62
+ anchorOnlyKey,
63
+ anchorTextOf,
59
64
  carryKey,
65
+ normaliseLineText,
60
66
  priorFindings,
61
67
  readLedger,
62
68
  type ReviewFinding,
@@ -81,6 +87,15 @@ export interface SuppressionInputs {
81
87
  threads: string | null;
82
88
  /** The text at a finding's cited line NOW, or `undefined`. */
83
89
  lineTextFor: (finding: ReviewFinding) => string | undefined;
90
+ /**
91
+ * How many lines of `file` carry `normalisedText`, or `undefined` when the
92
+ * file could not be read (#1861).
93
+ *
94
+ * Optional, and absent means the anchor rule never fires. A caller that has
95
+ * not been rewired keeps the behaviour it had before the rule existed,
96
+ * which is the direction this module is allowed to be wrong in.
97
+ */
98
+ anchorOccurrences?: (file: string, normalisedText: string) => number | undefined;
84
99
  }
85
100
 
86
101
  /** A prior set that was established, or the sentence saying it was not. */
@@ -144,6 +159,35 @@ export function priorKeysFrom(threads: string | null): PriorKeys {
144
159
  return { status: "MEASURED", keys: reading.threads.map(t => t.key) };
145
160
  }
146
161
 
162
+ /**
163
+ * Does this anchor identify ONE line of the file it names (#1861 round 3)?
164
+ *
165
+ * The screen the round-3 review asked for, and deliberately NOT the one it
166
+ * suggested. A minimum anchor length was the obvious fix and the measurement
167
+ * refuses it: of the five ambiguous anchors in the 60-finding corpus, four
168
+ * normalise to over twenty characters and the worst is forty-five. Length
169
+ * does not predict distinctiveness; counting the occurrences measures it.
170
+ *
171
+ * Every reading that is not exactly `1` answers `false`, including every way
172
+ * of failing to read. A caller with no counter, a file that is not there, a
173
+ * key whose text cannot be recovered and a path with two matching lines all
174
+ * mean the same thing here: this anchor cannot be shown to name one place,
175
+ * so nothing is suppressed on it.
176
+ */
177
+ function uniqueAnchor(
178
+ inputs: SuppressionInputs,
179
+ finding: ReviewFinding,
180
+ anchorKey: string,
181
+ ): boolean {
182
+ const count = inputs.anchorOccurrences;
183
+ if (count === undefined) return false;
184
+ const text = anchorTextOf(anchorKey);
185
+ if (text === null || text === "") return false;
186
+ const file = finding.file;
187
+ if (typeof file !== "string" || file === "") return false;
188
+ return count(file, text) === 1;
189
+ }
190
+
147
191
  /**
148
192
  * Build the gate the adjudicator is handed, or `null` when nothing is plumbed.
149
193
  *
@@ -165,26 +209,126 @@ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSupp
165
209
  // `AiReviewJuryGate`'s docblock names. `carryKey` is the shared rule and
166
210
  // the within-round half is the growing `seen` set, exactly as
167
211
  // `suppressRepeats` spells it.
212
+ // The keys an EARLIER round posted, kept apart from the growing set
213
+ // below so the two sentences can say which of them matched (#1861 round
214
+ // 3). They used to be one set, and the message said "an earlier round"
215
+ // for a duplicate that came from this round's own payload.
216
+ const priorSet = new Set<string>(prior.keys);
168
217
  const seen = new Set<string>(prior.keys);
218
+ // #1168. The same prior set read with the wording dropped. Built from the
219
+ // SAME strings rather than from the threads a second time: two derivations
220
+ // of one identity are two deciders that agree, and a mutation of either
221
+ // leaves the other holding every case up.
222
+ const anchors = new Set<string>();
223
+ for (const k of prior.keys) {
224
+ const a = anchorOnlyKey(k);
225
+ if (a !== null) anchors.add(a);
226
+ }
169
227
  const repeat = candidates.map(c => {
170
228
  const key = carryKey(c, inputs.lineTextFor(c as ReviewFinding));
171
229
  // Unkeyable CARRIES. It cannot be shown to be a repeat, and the
172
230
  // direction this is allowed to be wrong in is toward reporting.
173
231
  if (key === null) return null;
174
- if (!seen.has(key)) {
175
- seen.add(key);
176
- return null;
177
- }
178
232
  const f = c as ReviewFinding;
179
- return (
180
- `${String(f.file ?? "(no file)")}: ${String(f.summary ?? "(no summary)")} — already ` +
181
- `raised on an earlier round of this pull request, so it is not raised again`
182
- );
233
+ const where = String(f.file ?? "(no file)");
234
+ const what = String(f.summary ?? "(no summary)");
235
+ if (seen.has(key)) {
236
+ // WHICH set matched is the difference between two true sentences and
237
+ // one false one. `priorSet` is fixed at the prior round's keys;
238
+ // anything else in `seen` was added by a sibling a few lines below.
239
+ return priorSet.has(key)
240
+ ? `${where}: ${what} — already ` +
241
+ `raised on an earlier round of this pull request, so it is not raised again`
242
+ : `${where}: ${what} — listed more than once in this round's own ` +
243
+ `report, word for word, so it is reported once`;
244
+ }
245
+ const anchor = anchorOnlyKey(key);
246
+ // The wording differs and the anchor does not. Measured at #1168: of
247
+ // eight such collisions across 25 merged pull requests, eight were the
248
+ // same defect restated and none was a new finding at an old line. This
249
+ // is a JUDGEMENT rather than an identity, so it says so — the sentence
250
+ // is what lets a reader appeal it.
251
+ //
252
+ // And it fires only on an anchor that identifies ONE line of the file.
253
+ // `}` and `return null;` key the same anchor wherever they recur, so a
254
+ // new finding at a second occurrence would be suppressed as a
255
+ // restatement of a defect somewhere else entirely. Measured at #1861:
256
+ // 5 of 60 anchors in the corpus — 8.3% — recur in their own file. An
257
+ // unreadable file counts as NOT unique, because "I could not look" and
258
+ // "it appears once" must not be the same reading.
259
+ if (anchor !== null && anchors.has(anchor) && uniqueAnchor(inputs, f, anchor)) {
260
+ return (
261
+ `${where}: ${what} — an earlier round of this pull request already ` +
262
+ `raised a finding at the same line of text in this file, in different words, ` +
263
+ `so this is read as the same finding restated and is not raised again`
264
+ );
265
+ }
266
+ seen.add(key);
267
+ // `anchors` is NOT grown here, and the asymmetry with `seen` above is
268
+ // deliberate (#1861 round 1).
269
+ //
270
+ // `seen` growing is the established within-round rule and is safe on an
271
+ // EXACT key: two candidates with the same file, anchor AND wording are
272
+ // the same finding listed twice. The anchor key drops the wording, so
273
+ // growing it would suppress a second, differently-worded finding at the
274
+ // same line because a SIBLING in this very round cited it — and the
275
+ // sentence above, which says "an earlier round", would be false.
276
+ //
277
+ // It is also unmeasured: #1168's reading characterises cross-round
278
+ // collisions only, 8 of 8 restatements. It says nothing about two
279
+ // findings a reviewer raises at one line while looking at it once,
280
+ // which is the more plausible place for two genuine defects to share an
281
+ // anchor. Suppressing on evidence that was never taken is the thing
282
+ // this whole increment is a correction for.
283
+ return null;
183
284
  });
184
285
  return { repeat, unmeasured: null };
185
286
  };
186
287
  }
187
288
 
289
+ /**
290
+ * THE ONE PLACE A PRODUCTION `SuppressionInputs` IS ASSEMBLED (#1861 round 4).
291
+ *
292
+ * Two commands form this gate — `scripts/ai-review-findings.ts`, which decides
293
+ * the exit code, and `scripts/ai-review-threads.ts`, which posts the threads.
294
+ * `ai-review-threads.ts`' own comment states the invariant: the gate is *"the
295
+ * same function the adjudicator builds, over the same file, which is what
296
+ * makes 'already raised' one decision rather than two that agree until they
297
+ * do not"*. They ran BEFORE this existed as two hand-written object literals,
298
+ * and the round-4 review found the predicted consequence: `anchorOccurrences`
299
+ * was added to one of them, so the whole anchor rule was dead in the poster —
300
+ * the half that produces #1168's actual symptom, 11 threads for 3 findings.
301
+ *
302
+ * Returning the reader alongside the gate is the other half. The poster needs
303
+ * `lineTextFor` again for the key it writes INTO each thread, and it used to
304
+ * build a second `checkoutLineText` with a second cache. One reader, one
305
+ * cache, one normalisation — and nothing left for a future field to be wired
306
+ * into unevenly.
307
+ *
308
+ * `gate` is `null` when no thread list is plumbed, which is each command's
309
+ * pre-existing behaviour and is NOT the same as a gate that finds no repeats.
310
+ * `test/ai-review-suppression.test.ts` (AS-15) asserts neither command
311
+ * assembles its own.
312
+ */
313
+ export function productionSuppression(
314
+ threadsPath: string | undefined,
315
+ root: string,
316
+ ): {
317
+ gate: AiReviewSuppressionGate | null;
318
+ lineTextFor: (finding: ReviewFinding) => string | undefined;
319
+ } {
320
+ const reader = checkoutLineReader(root);
321
+ const gate =
322
+ threadsPath === undefined || threadsPath === ""
323
+ ? null
324
+ : aiReviewSuppressionGate({
325
+ threads: readOrNull(threadsPath),
326
+ lineTextFor: reader.lineTextFor,
327
+ anchorOccurrences: reader.occurrencesOf,
328
+ });
329
+ return { gate, lineTextFor: reader.lineTextFor };
330
+ }
331
+
188
332
  /**
189
333
  * THE KEY-SYMMETRY HALF. The text at a finding's cited line, read out of the
190
334
  * checkout.
@@ -208,16 +352,35 @@ export function aiReviewSuppressionGate(inputs: SuppressionInputs): AiReviewSupp
208
352
  * RESOLVED path and not on the spelling.
209
353
  */
210
354
  export function checkoutLineText(root: string): (finding: ReviewFinding) => string | undefined {
355
+ return checkoutLineReader(root).lineTextFor;
356
+ }
357
+
358
+ /**
359
+ * Both readings of the checkout, over ONE file cache.
360
+ *
361
+ * `lineTextFor` is the key-symmetry half documented above. `occurrencesOf`
362
+ * is the distinctiveness half #1861 added: how many lines of a file carry a
363
+ * given normalised text. They share a cache because they read the same files
364
+ * on the same run, and they share `normaliseLineText` with `carryKey`
365
+ * because a counter normalising differently from the key would count
366
+ * occurrences of a string the key never built.
367
+ *
368
+ * `undefined` from `occurrencesOf` is "I could not look" — an unreadable
369
+ * file, an absolute path, an escape out of the checkout — and the caller
370
+ * reads it as not-unique. Zero is a different fact (the file was read and
371
+ * the text is not in it) and is also not one, so both refuse.
372
+ */
373
+ export function checkoutLineReader(root: string): {
374
+ lineTextFor: (finding: ReviewFinding) => string | undefined;
375
+ occurrencesOf: (file: string, normalisedText: string) => number | undefined;
376
+ } {
211
377
  const base = resolve(root);
212
378
  const cache = new Map<string, string[] | null>();
213
- return (finding: ReviewFinding) => {
214
- const file = finding.file;
215
- const line = finding.line;
216
- if (typeof file !== "string" || file === "") return undefined;
217
- if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
218
- if (isAbsolute(file)) return undefined;
379
+ const linesOf = (file: string): string[] | null => {
380
+ if (typeof file !== "string" || file === "") return null;
381
+ if (isAbsolute(file)) return null;
219
382
  const path = resolve(base, file);
220
- if (path !== base && !path.startsWith(base + sep)) return undefined;
383
+ if (path !== base && !path.startsWith(base + sep)) return null;
221
384
  if (!cache.has(path)) {
222
385
  try {
223
386
  cache.set(path, readFileSync(path, "utf-8").split("\n"));
@@ -225,10 +388,26 @@ export function checkoutLineText(root: string): (finding: ReviewFinding) => stri
225
388
  cache.set(path, null);
226
389
  }
227
390
  }
228
- const lines = cache.get(path) ?? null;
229
- if (lines === null) return undefined;
230
- const text = lines[line - 1];
231
- return typeof text === "string" && text.trim() !== "" ? text : undefined;
391
+ return cache.get(path) ?? null;
392
+ };
393
+ return {
394
+ lineTextFor: (finding: ReviewFinding) => {
395
+ const file = finding.file;
396
+ const line = finding.line;
397
+ if (typeof file !== "string") return undefined;
398
+ if (typeof line !== "number" || !Number.isInteger(line) || line < 1) return undefined;
399
+ const lines = linesOf(file);
400
+ if (lines === null) return undefined;
401
+ const text = lines[line - 1];
402
+ return typeof text === "string" && text.trim() !== "" ? text : undefined;
403
+ },
404
+ occurrencesOf: (file: string, normalisedText: string) => {
405
+ const lines = linesOf(file);
406
+ if (lines === null) return undefined;
407
+ let n = 0;
408
+ for (const l of lines) if (normaliseLineText(l) === normalisedText) n++;
409
+ return n;
410
+ },
232
411
  };
233
412
  }
234
413
 
@@ -803,8 +803,42 @@ export function stripQuoted(s: string): string {
803
803
  * `stripQuoted` because a quoted PATH is a real argument while a heredoc
804
804
  * body never is — it is the document being written, not a word of the
805
805
  * command writing it.
806
+ *
807
+ * ## `blankComments`, and the three review rounds behind it (#1741)
808
+ *
809
+ * This function has two readers with OPPOSITE needs, and for a while it
810
+ * tried to serve both with one output.
811
+ *
812
+ * The write guard needs `#`-leading lines blanked. #1176: `# First, check if
813
+ * there's a test workflow-state.json` opened a quote that stayed open across
814
+ * the newline and swallowed the redirect on a later line, so a real write to
815
+ * a protected file read as quoted text. Two commands in a 5,513-command
816
+ * corpus did exactly that, both genuine writes.
817
+ *
818
+ * The filing parser needs them KEPT. `lib/issue-create-override.ts` builds
819
+ * its view from here, so a multi-line `gh issue create --body "…"` arrived
820
+ * with every `##` markdown heading deleted — the dedupe and the symptom scan
821
+ * were reading bodies with holes and nothing reported the loss.
822
+ *
823
+ * **The first three attempts all tried to make ONE output correct for both,
824
+ * by deciding per line whether the `#` was inside a quote. Each was a
825
+ * hand-rolled shell-comment predicate and each had a narrower view than the
826
+ * shell:** a `#` line inside a quote could open a heredoc and delete the
827
+ * lines after it; an inline comment's apostrophe set a carried state that
828
+ * suppressed the next line's blanking; and `echo hi;#…` was a comment the
829
+ * predicate did not recognise. Three rounds, three edges, same shape — so
830
+ * the fourth change is not a fourth predicate. `AGENTS.md` rule 5.
831
+ *
832
+ * **The parameter is the method change.** Blanking is a WRITE-GUARD safety
833
+ * measure; it was never something the filing parser wanted, and no quote
834
+ * tracking is needed to tell the two apart because the CALLER already knows
835
+ * which one it is. #1176 is untouched — the default is the old behaviour and
836
+ * every write-guard path takes it. `heredocView` passes `false` and lets
837
+ * `tokenize`, which implements the shell's comment rule for its own
838
+ * purposes, decide what a comment is on the side of the fence that cares.
806
839
  */
807
- export function stripHeredocs(s: string): string {
840
+
841
+ export function stripHeredocs(s: string, blankComments = true): string {
808
842
  const lines = s.split('\n');
809
843
  const out: string[] = [];
810
844
  let i = 0;
@@ -816,11 +850,22 @@ export function stripHeredocs(s: string): string {
816
850
  // a later line, so a real write to a protected file read as quoted text.
817
851
  // Two commands in a 5,513-command corpus did exactly this, both of them
818
852
  // genuine writes. Dropped here rather than in each caller because every
819
- // arm reaches this function first.
820
- const isComment = /^\s*#/.test(line);
821
- out.push(isComment ? '' : line); // #1176: the OPERATOR's line is kept — see below.
853
+ // write-guard arm reaches this function first.
854
+ //
855
+ // **#1741: unconditional again, and the caller chooses.** Three
856
+ // revisions tried to decide per line whether the `#` was inside a
857
+ // quote, so that one output could serve the write guard and the filing
858
+ // parser at once. The docblock above says what each of the three cost.
859
+ // The reader that wants the comment kept now says so.
860
+ const looksComment = /^\s*#/.test(line);
861
+ out.push(looksComment && blankComments ? '' : line); // #1176: the OPERATOR's line is kept.
822
862
  i++;
823
- if (isComment) continue; // a comment cannot open a heredoc
863
+ // A `#` line cannot open a heredoc. Read from the RAW line and not from
864
+ // what was pushed, so the exemption does not move when `blankComments`
865
+ // does — a `#` line that reaches `heredocDelimiter` deletes everything
866
+ // up to the terminator, and that is the bypass the second revision of
867
+ // this change shipped.
868
+ if (looksComment) continue;
824
869
  const delim = heredocDelimiter(line);
825
870
  if (!delim) continue;
826
871
  // #1184: buffer the body rather than consuming to end-of-input. A