rungate 0.8.13 → 0.8.16

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 (88) hide show
  1. package/README.md +182 -0
  2. package/gates/.gate-salt +1 -1
  3. package/hooks/HarnessAFKGate.hook.ts +5 -1
  4. package/hooks/HookCurrency.hook.ts +11 -8
  5. package/hooks/MergeGuard.hook.ts +7 -1
  6. package/hooks/StaleTTLCleanup.hook.ts +4 -4
  7. package/hooks/VerifyPhaseLock.hook.ts +3 -3
  8. package/hooks/lib/findWorkflow.ts +3 -2
  9. package/hooks/lib/paths.ts +14 -2
  10. package/hooks/lib/utils.ts +23 -3
  11. package/lib/active-milestone.ts +50 -0
  12. package/lib/ai-review-rounds.ts +99 -0
  13. package/lib/ai-review-suppression.ts +200 -21
  14. package/lib/bash-write-guard.ts +397 -23
  15. package/lib/board-flow.ts +280 -0
  16. package/lib/board-lane-health.ts +578 -0
  17. package/lib/board-mirror.ts +136 -39
  18. package/lib/board-ready-fanout.ts +297 -14
  19. package/lib/board-ready-rule.ts +1211 -0
  20. package/lib/board-throughput.ts +136 -0
  21. package/lib/board-walkthrough.ts +240 -0
  22. package/lib/body-evidence.ts +203 -0
  23. package/lib/branch-protection.ts +399 -9
  24. package/lib/bun-version.ts +36 -0
  25. package/lib/cli-commands.ts +75 -4
  26. package/lib/closing-reference-audit.ts +307 -6
  27. package/lib/config-loader.ts +254 -25
  28. package/lib/config-readers.ts +170 -10
  29. package/lib/config-trackable.ts +96 -57
  30. package/lib/conformity.ts +121 -7
  31. package/lib/create-sc.ts +25 -2
  32. package/lib/derived-spec.ts +21 -9
  33. package/lib/filing-compliance.ts +367 -0
  34. package/lib/filing-plan.ts +47 -21
  35. package/lib/finding-arbiter.ts +79 -5
  36. package/lib/finding-jury.ts +43 -4
  37. package/lib/finding-promotion.ts +1123 -0
  38. package/lib/generators/agents-md.ts +149 -0
  39. package/lib/git-isolation.ts +137 -1
  40. package/lib/github-api-base.ts +66 -0
  41. package/lib/github.ts +194 -9
  42. package/lib/graphql-cursor.ts +80 -0
  43. package/lib/hook-scopes.ts +78 -0
  44. package/lib/issue-create-override.ts +415 -3
  45. package/lib/issue-decomposition.ts +124 -7
  46. package/lib/issue-extraction.ts +9 -7
  47. package/lib/issue-file-overlap.ts +373 -0
  48. package/lib/issue-filing-gate.ts +1109 -52
  49. package/lib/issue-repair.ts +90 -9
  50. package/lib/issue-shape.ts +199 -0
  51. package/lib/live-issues.ts +31 -2
  52. package/lib/local-work.ts +423 -0
  53. package/lib/markdown-fence.ts +134 -0
  54. package/lib/milestone-title.ts +46 -0
  55. package/lib/scaffold/ai-review-findings.ts +148 -3
  56. package/lib/scaffold/ai-review-step.ts +65 -5
  57. package/lib/scaffold/ai-review-unmeasured-workflow.ts +3 -0
  58. package/lib/scaffold/steps.ts +115 -9
  59. package/lib/source-census.ts +108 -0
  60. package/lib/spec-deps.ts +55 -11
  61. package/lib/spec-placement.ts +203 -13
  62. package/lib/spec-registry.ts +75 -16
  63. package/lib/spec-source.ts +609 -0
  64. package/lib/spec-write-sweep.ts +4 -0
  65. package/lib/stage-ladder.ts +896 -3
  66. package/lib/state-claim-readings.ts +252 -0
  67. package/lib/success-doc.ts +7 -6
  68. package/lib/test-command-positions.ts +135 -1
  69. package/lib/work-status.ts +551 -0
  70. package/lib/worktree-repo.ts +14 -2
  71. package/package.json +7 -1
  72. package/scripts/ai-review-findings.ts +8 -13
  73. package/scripts/ai-review-threads.ts +16 -17
  74. package/scripts/audit-closing-references.ts +330 -0
  75. package/scripts/audit-specs.ts +59 -103
  76. package/scripts/board-conformance.ts +747 -40
  77. package/scripts/board-mirror.ts +594 -13
  78. package/scripts/board-ready.ts +979 -0
  79. package/scripts/board-snapshot.ts +464 -12
  80. package/scripts/claim-files.ts +578 -0
  81. package/scripts/criterion-inventory.ts +526 -50
  82. package/scripts/finding-promotion.ts +547 -0
  83. package/scripts/generate-code-map.ts +1 -1
  84. package/scripts/plan-issues.ts +279 -40
  85. package/scripts/plan-spec.ts +105 -3
  86. package/scripts/sync-sc-status.ts +147 -7
  87. package/scripts/worktree-census.ts +958 -0
  88. package/scripts/worktree-sweep.ts +269 -0
@@ -0,0 +1,252 @@
1
+ /**
2
+ * A ratio `project-state.json` states about the board, and the live reading
3
+ * that re-takes it — #1889.
4
+ *
5
+ * ## The defect, and what it is NOT
6
+ *
7
+ * Three review rounds on PR #1888 each found the same thing in
8
+ * `priorities[]` prose, and all three were caught by a reader doing
9
+ * arithmetic in their head. `scripts/board-conformance.ts` has exactly this
10
+ * relationship with the board — it re-takes every reading and refuses while
11
+ * any is short — and the state file had no equivalent. So a figure in
12
+ * `priorities[]` was a number a report states about the tracker, which
13
+ * nothing compared against the tracker.
14
+ *
15
+ * This is **not** a fact-checker for English. It reads one shape: a ratio
16
+ * written immediately after the name of a reading `board-conformance`
17
+ * already produces. Anything else is UNRECOGNISED and is reported as such —
18
+ * never as agreed, because an extractor that silently matches nothing
19
+ * certifies the file by counting nothing
20
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the vacuous assertion).
21
+ *
22
+ * ## A dated figure is a RECORD, and the file is mostly records
23
+ *
24
+ * Measured before this was written, not assumed: of 29 `priorities[]`
25
+ * entries on 2026-11-08, six sentences cite a reading by name, and two of
26
+ * the six carry the date the reading was taken. `priorities[]` is an
27
+ * append-only log of sessions, so most of what is in it was true when it
28
+ * was written and is not a claim about today.
29
+ *
30
+ * So a cited figure whose sentence carries a date or a commit SHA is
31
+ * `RECORDED` — reported, counted, and never compared. One whose sentence
32
+ * carries neither asserts the present tense, and is re-derived. That is the
33
+ * distinction round 1 of #1888 got wrong in the other direction: it read a
34
+ * dated 2026-11-03 recording as a statement about today and concluded the
35
+ * numbers had not moved.
36
+ *
37
+ * **The direction this is allowed to be wrong in** is toward RECORDED. A
38
+ * figure wrongly treated as a record costs a comparison nobody took, which
39
+ * is the status quo for every figure in the file. A figure wrongly compared
40
+ * reddens a true sentence, and the fix for that is to date it — which is
41
+ * the thing the file should be doing anyway.
42
+ */
43
+
44
+ /** One reading as `scripts/board-conformance.ts` produces it. */
45
+ export interface LiveReading {
46
+ name: string;
47
+ measured: number;
48
+ target: number;
49
+ }
50
+
51
+ /** A ratio found in prose, and the reading it names. */
52
+ export interface CitedReading {
53
+ /** The reading's name, exactly as `board-conformance` spells it. */
54
+ reading: string;
55
+ measured: number;
56
+ target: number;
57
+ /** The sentence it was read out of, so a refusal can quote its evidence. */
58
+ sentence: string;
59
+ /**
60
+ * Does the sentence carry a date or a commit SHA? A cited figure that
61
+ * says when it was taken is a record of a past reading, not a claim about
62
+ * the present, and is not compared.
63
+ */
64
+ dated: boolean;
65
+ }
66
+
67
+ /**
68
+ * Three outcomes, and they are three different facts.
69
+ *
70
+ * There is deliberately no `UNRESOLVABLE`. One was written, and it was a
71
+ * **dead branch**: `judgeClaims` derives its name list from the live
72
+ * readings, so a citation of a name they no longer carry is invisible to
73
+ * the extractor and never reaches a verdict at all. A branch that cannot
74
+ * fire is not protection, and keeping it would have been the worst kind of
75
+ * guard — one whose presence is the reason nobody checks.
76
+ *
77
+ * The rename it was meant to catch is caught where it can be: the ratchet
78
+ * names the reading set it was banked against, and
79
+ * `scripts/check-state-claims.ts` refuses when the live set differs.
80
+ */
81
+ export type ClaimVerdict =
82
+ | { kind: "AGREED"; cited: CitedReading }
83
+ | { kind: "DISAGREED"; cited: CitedReading; live: LiveReading }
84
+ | { kind: "RECORDED"; cited: CitedReading };
85
+
86
+ /**
87
+ * A date, or a commit SHA: either says WHEN the figure was taken.
88
+ *
89
+ * **The SHA arm requires a letter AND a digit**, and both halves were put
90
+ * there by a case that got through:
91
+ *
92
+ * - **Letters only** — `[0-9a-f]{7,}` matches ordinary English spelt from
93
+ * those characters: `defaced`, `effaced`, `faceted`.
94
+ * - **Digits only** — and this is the one the first fix missed, because
95
+ * requiring *a* digit does not exclude a number. A plain decimal of
96
+ * seven or more digits is valid hex, so `filed as run 12345678` marked
97
+ * its sentence RECORDED. A GitHub run id, an issue count, a line
98
+ * number: any of them suppressed the comparison.
99
+ *
100
+ * A detector that suppresses the comparison on a word or a count is a
101
+ * bypass, not a heuristic. Both populations are controls in
102
+ * `test/state-claim-readings.test.ts`.
103
+ *
104
+ * **What this gives up, deliberately**: a SHA prefix that happens to be all
105
+ * digits is no longer read as one, so a figure beside it is compared rather
106
+ * than recorded. That errs toward comparing, which is the direction stated
107
+ * at the top of this file — the remedy a refusal names is "date the
108
+ * sentence", and a sentence citing a commit usually carries a date too.
109
+ */
110
+ const STAMPED = /\b\d{4}-\d{2}-\d{2}\b|\b(?=[0-9a-f]{7,40}\b)(?=[0-9a-f]*[a-f])(?=[0-9a-f]*\d)[0-9a-f]{7,40}\b/;
111
+
112
+ /**
113
+ * Sentence boundaries, and `\n` counts as one.
114
+ *
115
+ * A `priorities[]` entry is one long string with hard line breaks in it,
116
+ * and two figures either side of a newline are two statements. Splitting on
117
+ * `[.!?]` alone joined them, and the gap window below would then reach
118
+ * across the break.
119
+ */
120
+ const SENTENCE = /(?<=[.!?])\s+|\n+/;
121
+
122
+ /**
123
+ * How much may sit between a reading's name and its ratio.
124
+ *
125
+ * Wide enough for `blocked-by-edges to 6 of 6` and `milestones 26 of 26`.
126
+ *
127
+ * Two separate restrictions, and a mutation of each turns a different case
128
+ * red. They were briefly described as doing the same job, and the mutation
129
+ * that widened the punctuation stop turned ZERO cases red — because the
130
+ * list it was credited with catching is caught by the other half:
131
+ *
132
+ * - **No other reading's name inside the window.** This is what stops
133
+ * `blocked-by-edges 5 of 6, criteria-field 5 of 6` pairing the first
134
+ * name with the second ratio, and it works on a list with no punctuation
135
+ * in it at all.
136
+ * - **Stopped at `,` `;` and `.`.** This does something the name guard
137
+ * cannot: `blocked-by-edges MET, but 3 of 9 elsewhere` has no second
138
+ * reading in it, so only the clause boundary keeps the ratio from being
139
+ * read as this reading's.
140
+ */
141
+ const GAP_MAX = 24;
142
+
143
+ function escapeForPattern(s: string): string {
144
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
145
+ }
146
+
147
+ /**
148
+ * The reading's name must be the WHOLE name, not the start or end of a
149
+ * longer one.
150
+ *
151
+ * Unanchored, `milestones` matched inside `milestones-tracking is 5 of 5`,
152
+ * `sub-milestones 3 of 4` and `milestones_v2 is 1 of 2`, each producing a
153
+ * citation of a reading the sentence never mentions. That errs toward
154
+ * COMPARING — the opposite of the direction this file declares — so it
155
+ * reddens a true sentence, or worse, AGREES and masks a real one.
156
+ *
157
+ * **`\b` is not the fix, and it is the fix everybody reaches for.** `-` is
158
+ * a non-word character, so `milestones\b` matches inside
159
+ * `milestones-tracking` and `\bblocked` matches inside `re-blocked-by-edges`
160
+ * — and every reading in this project is hyphenated. The boundary has to
161
+ * exclude `-` and `_` as well as word characters, or the control case goes
162
+ * green under a fix that changed nothing.
163
+ */
164
+ const NAME_LEFT = "(?<![\\w-])";
165
+ const NAME_RIGHT = "(?![\\w-])";
166
+
167
+ /**
168
+ * Every ratio in `prose` that names one of `names`.
169
+ *
170
+ * The names are passed in rather than declared here, and that is the point:
171
+ * `board-conformance` owns what a reading is called, and a second list here
172
+ * would be a second decider for a question already answered — two deciders
173
+ * that agree, which no behavioural test can tell apart.
174
+ */
175
+ export function citedReadings(prose: string, names: readonly string[]): CitedReading[] {
176
+ const out: CitedReading[] = [];
177
+ // Longest first, so `criterion-coverage` is never matched as `criteri…`
178
+ // by a shorter sibling that happens to be a prefix of it.
179
+ const ordered = [...names].sort((a, b) => b.length - a.length);
180
+ for (const sentence of prose.split(SENTENCE)) {
181
+ const dated = STAMPED.test(sentence);
182
+ for (const name of ordered) {
183
+ const re = new RegExp(
184
+ `${NAME_LEFT}${escapeForPattern(name)}${NAME_RIGHT}([^,;.]{0,${GAP_MAX}}?)\\b(\\d+)\\s*(?:of|/)\\s*(\\d+)\\b`,
185
+ "gi",
186
+ );
187
+ for (const m of sentence.matchAll(re)) {
188
+ const gap = m[1] ?? "";
189
+ // A different reading's name inside the window means this ratio
190
+ // belongs to that one, not to this one.
191
+ if (ordered.some(other => other !== name && gap.toLowerCase().includes(other.toLowerCase()))) {
192
+ continue;
193
+ }
194
+ out.push({
195
+ reading: name,
196
+ measured: Number(m[2]),
197
+ target: Number(m[3]),
198
+ sentence: sentence.trim(),
199
+ dated,
200
+ });
201
+ }
202
+ }
203
+ }
204
+ return out;
205
+ }
206
+
207
+ /** Compare each cited figure against the live reading of the same name. */
208
+ export function judgeClaims(prose: string, live: readonly LiveReading[]): ClaimVerdict[] {
209
+ const byName = new Map(live.map(r => [r.name, r]));
210
+ return citedReadings(prose, [...byName.keys()]).map((cited): ClaimVerdict => {
211
+ // Non-null by construction: the name list IS `byName`'s keys, so the
212
+ // extractor cannot produce a citation this map does not answer. Said
213
+ // as an assertion rather than a branch, because the branch that used
214
+ // to be here could not fire and read as protection.
215
+ const now = byName.get(cited.reading)!;
216
+ if (cited.dated) return { kind: "RECORDED", cited };
217
+ if (cited.measured === now.measured && cited.target === now.target) {
218
+ return { kind: "AGREED", cited };
219
+ }
220
+ return { kind: "DISAGREED", cited, live: now };
221
+ });
222
+ }
223
+
224
+ /**
225
+ * A reading of a whole state file: how many of each verdict, and which.
226
+ *
227
+ * `claims === 0` is its own fact and the caller must be able to say so.
228
+ * "no readable claims in this file" and "every claim agreed" are the same
229
+ * zero disagreements and completely different states, and conflating them
230
+ * is how a check certifies a file it never looked inside.
231
+ */
232
+ export interface StateClaimReading {
233
+ verdicts: ClaimVerdict[];
234
+ claims: number;
235
+ agreed: number;
236
+ disagreed: ClaimVerdict[];
237
+ recorded: number;
238
+ }
239
+
240
+ export function readStateClaims(
241
+ entries: readonly string[],
242
+ live: readonly LiveReading[],
243
+ ): StateClaimReading {
244
+ const verdicts = entries.flatMap(e => judgeClaims(e, live));
245
+ return {
246
+ verdicts,
247
+ claims: verdicts.length,
248
+ agreed: verdicts.filter(v => v.kind === "AGREED").length,
249
+ disagreed: verdicts.filter(v => v.kind === "DISAGREED"),
250
+ recorded: verdicts.filter(v => v.kind === "RECORDED").length,
251
+ };
252
+ }
@@ -43,6 +43,8 @@ import { existsSync, lstatSync, readFileSync } from "fs";
43
43
  import { dirname, join } from "path";
44
44
  import { fileURLToPath } from "url";
45
45
 
46
+ import { readFences } from "./markdown-fence";
47
+
46
48
  /**
47
49
  * The token the template puts on every line a human must replace.
48
50
  *
@@ -151,15 +153,14 @@ export function parseSuccessDoc(text: string): SuccessDoc {
151
153
  const lines = text.split("\n");
152
154
 
153
155
  let current: SuccessClaim | null = null;
154
- let fenced = false;
156
+ // A fence closes only on its own marker (#2130): a `~~~` line inside a
157
+ // ``` block used to toggle the block shut.
158
+ const { roles } = readFences(lines);
155
159
  for (let i = 0; i < lines.length; i++) {
156
160
  const line = lines[i];
157
- if (/^\s*(```|~~~)/.test(line)) {
158
- fenced = !fenced;
159
- continue;
160
- }
161
+ if (roles[i] === "fence") continue;
161
162
  if (line.includes(PLACEHOLDER_MARKER)) placeholderLines.push(i + 1);
162
- if (fenced) continue;
163
+ if (roles[i] === "code") continue;
163
164
 
164
165
  let heading: RegExpExecArray | null = null;
165
166
  for (const form of CLAIM_FORMS) {
@@ -192,6 +192,140 @@ const NOT_THE_TEST_STEP = new Set(["bun install", "bun run typecheck"]);
192
192
  */
193
193
  const SHARD_SELECTOR = /\s+--shard=.+?\/\d+\s*$/;
194
194
 
195
+ /**
196
+ * Where a generated run writes its JUnit report (#1173).
197
+ *
198
+ * `runner.temp`, not the checkout: several suites in `test/` spawn `bun test`
199
+ * as a subprocess with the repository as cwd, so a repository-relative path
200
+ * is written by every nested run and the last writer wins.
201
+ *
202
+ * `leg` distinguishes the legs of a matrix and is `""` when there is no
203
+ * matrix. It is a PARAMETER rather than a constant because `shardCount`
204
+ * returns 1 for every project that has not set `ci.shards` — the default
205
+ * scaffold output, not an edge case — and the unsharded template is a
206
+ * different `- run:` line in the generator. `${{ matrix.shard }}` is not
207
+ * expanded outside a matrix job, so the suffix cannot be passed
208
+ * unconditionally.
209
+ *
210
+ * It lives HERE rather than beside the generator because the selector below
211
+ * is derived from it, and `lib/scaffold/steps.ts` already imports from this
212
+ * module — the other direction would be a cycle, and a second copy of the
213
+ * path is the thing that makes a producer and a reader disagree.
214
+ */
215
+ export function ciJunitOutfile(leg: string): string {
216
+ return `\${{ runner.temp }}/rungate-junit${leg}.xml`;
217
+ }
218
+
219
+ /** The leg suffix for a matrix job, and the one for a job with no matrix. */
220
+ export const CI_JUNIT_SHARD_LEG = `-\${{ matrix.shard }}`;
221
+ export const CI_JUNIT_SINGLE_LEG = "";
222
+
223
+ /**
224
+ * The JUnit reporter is CI INSTRUMENTATION, not a different test command
225
+ * (#1173), and it is stripped here for the same reason the shard selector is:
226
+ * leaving it in turns the agreement check red, and the cheap fix for THAT red
227
+ * is to put `--reporter=junit --reporter-outfile=…` in the AGENTS.md row a
228
+ * human copies to run the suite locally — a CI-only flag in the one place it
229
+ * must never be.
230
+ *
231
+ * ## It matches OUR outfile by name, and that is the whole point
232
+ *
233
+ * The first spelling was `--reporter-outfile=.*$` — anything, to end of line.
234
+ * Round 4 of #1926 caught what that costs, and measuring it showed the
235
+ * finding's own scope was too narrow: for a consumer whose `test.command`
236
+ * already is `bun test --reporter=junit --reporter-outfile=./custom.xml`,
237
+ * `mayInstrumentJunit` correctly appends nothing, and then this stripped the
238
+ * consumer's OWN flags and read `bun test`. The agreement check would report
239
+ * a mismatch nobody caused. In the sharded template it was worse, not better:
240
+ * `.*$` swallowed the shard selector too.
241
+ *
242
+ * Their suffix and ours are **the same spelling in the unsharded template**,
243
+ * so no amount of anchoring separates them. The discriminator has to be
244
+ * something we control, and that is the outfile: this generator only ever
245
+ * writes under `${{ runner.temp }}` with the `rungate-junit` stem, derived
246
+ * from `ciJunitOutfile` above rather than spelled again. A consumer writing
247
+ * to exactly that path has configured what we would have configured, so
248
+ * stripping it is correct there too.
249
+ */
250
+ const CI_REPORTER_SELECTOR = new RegExp(
251
+ `\\s+--reporter=junit\\s+--reporter-outfile=(?:${[CI_JUNIT_SHARD_LEG, CI_JUNIT_SINGLE_LEG]
252
+ .map(leg => ciJunitOutfile(leg).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
253
+ .join("|")})(?=\\s|$)`,
254
+ );
255
+
256
+ /**
257
+ * Is this test command a `bun test` invocation?
258
+ *
259
+ * The scaffold generates CI for consumers, and `test.command` is theirs — a
260
+ * project running `npm test` or `pytest` must not be handed bun's reporter
261
+ * flags. So the instrumentation is conditional on the command it is being
262
+ * appended to, and a command this cannot recognise gets nothing rather than
263
+ * a flag its runner will reject.
264
+ *
265
+ * **Whitespace or end of string, NOT `\b`.** `\b` asks only for a non-word
266
+ * character, and `:` and `-` are non-word characters — so the first spelling
267
+ * of this matched `bun test:unit` (a package script) and `bun test-runner.ts`
268
+ * (a file), neither of which is bun's built-in runner. Bun intercepts the
269
+ * exact token `test` and nothing else, so those commands would have had
270
+ * `--reporter=junit` appended to some script's argv, and a report uploaded
271
+ * that the script never writes. Round 2 of #1926's review; measured, not
272
+ * reasoned about — `/^bun\s+test\b/` returns true for all three.
273
+ */
274
+ export function isBunTestCommand(command: string): boolean {
275
+ return /^bun\s+test(\s|$)/.test(command.trim());
276
+ }
277
+
278
+ /**
279
+ * A command that already chose a reporter.
280
+ *
281
+ * Only the flag, not a bare `--reporterish` word: `(=|\s|$)` so
282
+ * `--reporter-outfile` alone does not count as choosing one, and
283
+ * `--no-reporter` is not matched by the leading `(^|\s)--reporter`.
284
+ */
285
+ const DECLARES_REPORTER = /(^|\s)--reporter(=|\s|$)/;
286
+
287
+ /**
288
+ * May this command be given a JUnit reporter? ONE answer, two reasons.
289
+ *
290
+ * Both reasons were found by review rather than by me, one round apart
291
+ * (#1926), and that is the argument for them living in one predicate rather
292
+ * than as two guards at two call sites. Round 2 fixed `isBunTestCommand` and
293
+ * I did not then ask what ELSE makes a command ineligible; round 3 named the
294
+ * second reason. A third would be added here, not somewhere new.
295
+ *
296
+ * 1. **It must be bun's built-in runner.** See `isBunTestCommand`.
297
+ * 2. **It must not already declare a reporter.** A consumer whose
298
+ * `test.command` is `bun test --reporter=junit --reporter-outfile=./x.xml`
299
+ * has already solved this, and appending a second pair does not merely
300
+ * override their choice — measured, it breaks their build. The CI
301
+ * extractor below strips from the FIRST `--reporter=junit` to end of
302
+ * line, so it reads `bun test` while their config and AGENTS.md row say
303
+ * the full command, and the three-position agreement check goes red.
304
+ *
305
+ * Both `junitReporterFlags` and the scaffold's upload step ask THIS, so the
306
+ * flags and the artifact step cannot disagree about whether a report exists.
307
+ */
308
+ export function mayInstrumentJunit(command: string): boolean {
309
+ return isBunTestCommand(command) && !DECLARES_REPORTER.test(command.trim());
310
+ }
311
+
312
+ /**
313
+ * The flags that make a `bun test` run write per-case durations, or `""`.
314
+ *
315
+ * `outfile` is the caller's, because the only correct answer involves the
316
+ * runner's own temp directory and the shard index, and neither is this
317
+ * module's to know. **It must not be repository-relative**: several suites in
318
+ * `test/` spawn `bun test` as a subprocess with the repository as cwd, so a
319
+ * relative path — or a `bunfig.toml` declaration, which every nested run
320
+ * inherits — means the last writer wins and a 15,000-case run can end with a
321
+ * three-case report on disk. Three cases is not empty, so the UNMEASURED
322
+ * guards downstream would not catch it.
323
+ */
324
+ export function junitReporterFlags(command: string, outfile: string): string {
325
+ if (!mayInstrumentJunit(command)) return "";
326
+ return ` --reporter=junit --reporter-outfile=${outfile}`;
327
+ }
328
+
195
329
  /** The test step of the generated suite job in ci.yml. */
196
330
  export function testCommandsNamedByCiWorkflow(text: string): NamedTestCommand[] {
197
331
  // `suiteJobName` is the one binding for "which job runs the suite" — it is
@@ -217,7 +351,7 @@ export function testCommandsNamedByCiWorkflow(text: string): NamedTestCommand[]
217
351
  // `run: |` opens a block scalar; the body is not a command on this line.
218
352
  .filter(cmd => cmd !== "|" && !cmd.startsWith("|"))
219
353
  .filter(cmd => !NOT_THE_TEST_STEP.has(cmd))
220
- .map(cmd => cmd.replace(SHARD_SELECTOR, ""));
354
+ .map(cmd => cmd.replace(CI_REPORTER_SELECTOR, "").replace(SHARD_SELECTOR, ""));
221
355
 
222
356
  if (runs.length === 0) {
223
357
  refuse(CI_YML, "its `test:` job runs nothing but setup and the type check");