rungate 0.6.0 → 0.7.0

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 (113) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,653 @@
1
+ /**
2
+ * Which test cases a repair round DELETED, and whether they were green
3
+ * before it (#659).
4
+ *
5
+ * ## The run this exists for
6
+ *
7
+ * `wf_2abbe96f-546`, issue #646. The verify gate recorded AC-9 FAIL over an
8
+ * evidence command that emits two numbers against one threshold — a verdict
9
+ * that was never about the code (see `lib/evidence-satisfiability.ts`). The
10
+ * repair round the FAIL triggered deleted three PASSING test cases from
11
+ * `test/unit/hill-climb-receipt.test.ts` and 296 net lines overall, and
12
+ * deleting them changed nothing about what AC-9 measures. The run's output
13
+ * was a smaller green tree, and nothing in the run said what left.
14
+ *
15
+ * ## Why two commits, and why these two
16
+ *
17
+ * The cases were added at the first build commit and removed at the repair
18
+ * commit, both on the run's own branch. Against the merge base they never
19
+ * existed — so the PR diff, `git log main..branch`, and every "what did this
20
+ * branch change" reading are all clean of the deletion. The only window it
21
+ * is visible in is between the two BUILD COMMITS, which is why this takes a
22
+ * pair of commits and reads them out of the object store rather than looking
23
+ * at a working tree or a branch.
24
+ *
25
+ * ## Absence is not the finding
26
+ *
27
+ * A name that is gone is a deleted passing test, a deleted failing test, a
28
+ * renamed test, or a test somebody moved to another file. Only the first is
29
+ * the defect. So the verdict needs the PREVIOUS commit's own ledger, and
30
+ * three outcomes rather than two:
31
+ *
32
+ * CLEAN nothing left, or what left was not green before
33
+ * DELETED a case the previous build commit proved green is gone
34
+ * UNMEASURED the ledger does not say — which is NOT "the case was red"
35
+ *
36
+ * That last one is `lib/suite-run-reading.ts`'s distinction, in a second
37
+ * place: `0`, `{}` and silence are indistinguishable from success, and
38
+ * UNMEASURED is the only reading that is not.
39
+ */
40
+ import { spawnSync } from "child_process";
41
+ import { readJunitOutcomes } from "./junit-checks";
42
+ import { caseDeclarations, renamePairs } from "./test-case-bodies";
43
+
44
+ // ── Reading a commit ─────────────────────────────────────────────────────
45
+
46
+ /** A commit SHA or any other revision git can resolve. */
47
+ function git(projectRoot: string, args: string[]): { out: string; status: number } {
48
+ const r = spawnSync("git", ["-C", projectRoot, ...args], {
49
+ encoding: "utf-8",
50
+ timeout: 30_000,
51
+ maxBuffer: 64 * 1024 * 1024,
52
+ });
53
+ if (r.error) throw r.error;
54
+ return { out: r.stdout ?? "", status: r.status ?? 1 };
55
+ }
56
+
57
+ /**
58
+ * The commit a revision names, or a throw.
59
+ *
60
+ * A throw rather than a null: every caller of this module is deciding
61
+ * whether a run may ship, and a revision that does not resolve produces an
62
+ * empty reading — which is byte-identical to "nothing was deleted". Run
63
+ * `wf_2abbe96f-546`'s own context records the shell form of this trap: in
64
+ * zsh, `$SHA:path` is parsed as a parameter modifier, mangles the ref, and
65
+ * makes `grep -c` return 0, "which reads exactly like a clean result". No
66
+ * command here goes through a shell, and an unresolvable revision stops the
67
+ * reading rather than emptying it.
68
+ */
69
+ function resolveCommit(projectRoot: string, revision: string): string {
70
+ const r = git(projectRoot, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`]);
71
+ const sha = r.out.trim();
72
+ if (r.status !== 0 || sha === "") {
73
+ throw new Error(`the revision "${revision}" does not resolve to a commit in ${projectRoot}`);
74
+ }
75
+ return sha;
76
+ }
77
+
78
+ /** A file's contents at a commit, or `null` when the commit does not hold it. */
79
+ function blobAt(projectRoot: string, commit: string, path: string): string | null {
80
+ // `commit:path` is built as ONE argv element and handed to spawn, never to
81
+ // a shell. The ref is not re-parsed by anything.
82
+ const r = git(projectRoot, ["show", `${commit}:${path}`]);
83
+ return r.status === 0 ? r.out : null;
84
+ }
85
+
86
+ /** Paths a tree holds that look like test files. */
87
+ const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
88
+
89
+ /**
90
+ * The test files that CHANGED between the two commits, including the ones
91
+ * the second commit no longer has.
92
+ *
93
+ * `-z` everywhere, because `--name-only` C-quotes any path with a non-ASCII
94
+ * byte, a quote, a tab or a newline — `"caf\303\251.test.ts"`, quotes
95
+ * included. Fed back to `git show` that string resolves on neither commit,
96
+ * both readings come back empty, and a file whose every case was deleted
97
+ * reports no deletions (#516 measured exactly this).
98
+ *
99
+ * `--no-renames` so a renamed file arrives as a delete plus an add. A rename
100
+ * that also dropped cases is then visible; with rename detection on, the
101
+ * drop would be folded into a similarity score.
102
+ */
103
+ function changedTestFiles(projectRoot: string, previous: string, current: string): string[] {
104
+ const r = git(projectRoot, [
105
+ "diff", "--name-only", "-z", "--no-renames", "--diff-filter=MD", previous, current,
106
+ ]);
107
+ if (r.status !== 0) {
108
+ throw new Error(`git diff between ${previous} and ${current} failed in ${projectRoot}`);
109
+ }
110
+ return r.out.split("\0").filter(p => p !== "" && TEST_FILE.test(p));
111
+ }
112
+
113
+ // ── Reading the cases a source file declares ─────────────────────────────
114
+
115
+ /**
116
+ * Every test case name a source file declares, in declaration order.
117
+ *
118
+ * A PROJECTION of `caseDeclarations`, which owns the declaration pattern
119
+ * since #880. The names and the bodies this module compares are therefore
120
+ * one reading seen twice: a scan that found a case and a scan that found its
121
+ * body cannot disagree about which cases exist, because there is only one
122
+ * scan (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
123
+ *
124
+ * Exported so a caller can compare a reading of one commit against an
125
+ * instrument that is not this one — `test/unit/deletion-build-commit-pair.test.ts`
126
+ * checks both totals against the counts the verify gate's own `test-census`
127
+ * recorded on the run, which is the only thing that can say this reads the
128
+ * file rather than producing the right three names by luck.
129
+ */
130
+ export function caseNames(source: string): string[] {
131
+ return caseDeclarations(source).map(d => d.name);
132
+ }
133
+
134
+ // ── The deletion ─────────────────────────────────────────────────────────
135
+
136
+ /** One test case present at the previous commit and absent at the current one. */
137
+ export interface DeletedCase {
138
+ /** The name as the source declared it, with no describe chain. */
139
+ name: string;
140
+ /** The path it was declared in, at the previous commit. */
141
+ file: string;
142
+ }
143
+
144
+ /**
145
+ * One test case present at both commits under two different titles (#880).
146
+ *
147
+ * A rename and a deletion are different facts and the remedies are opposite
148
+ * — one needs nothing done, the other needs the test restored — so they are
149
+ * different fields rather than one list with a flag.
150
+ */
151
+ export interface RenamedCase {
152
+ /** The path, which is the same at both commits: a pair is within one file. */
153
+ file: string;
154
+ /** The title at the previous commit. */
155
+ from: string;
156
+ /** The title at the current commit. */
157
+ to: string;
158
+ }
159
+
160
+ /** What a round did to the cases in the files it touched. */
161
+ export interface CaseChanges {
162
+ deleted: DeletedCase[];
163
+ renamed: RenamedCase[];
164
+ }
165
+
166
+ /**
167
+ * What the current commit did to the previous one's test cases.
168
+ *
169
+ * Both sides are read out of the object store, so neither commit has to be
170
+ * checked out and the working tree is never touched. Only files the diff
171
+ * reports as modified or deleted are read: a file whose blob is identical
172
+ * cannot have lost a case, and reading every test file in both trees would
173
+ * be ~700 git invocations for an answer the diff already narrows.
174
+ *
175
+ * ## A title that is gone is four different facts (#880)
176
+ *
177
+ * This module's own docblock has said so since #659 and the reading could
178
+ * only tell apart the last of them. Run `wf_99ed276b-cf3` reported eight
179
+ * cases missing from one file; seven were renamed by the repair round and
180
+ * net coverage over the run went 19 → 27. A rename changes the title and
181
+ * leaves the body, so the body is what separates the two, and
182
+ * `renamePairs` does it by IDENTITY of the normalised body rather than by
183
+ * any similarity score — see `lib/test-case-bodies.ts` for why a score was
184
+ * refused.
185
+ *
186
+ * **Pairing is within ONE file.** A case moved to another file is still
187
+ * absent from this one, and saying "renamed" about it would be an answer to
188
+ * a question nobody asked — the file it went to is not in the pair, so a
189
+ * reader could not go and check. It is reported as a deletion, which is
190
+ * what it is from here.
191
+ */
192
+ export function caseChanges(
193
+ projectRoot: string,
194
+ previousCommit: string,
195
+ currentCommit: string,
196
+ ): CaseChanges {
197
+ const previous = resolveCommit(projectRoot, previousCommit);
198
+ const current = resolveCommit(projectRoot, currentCommit);
199
+ const deleted: DeletedCase[] = [];
200
+ const renamed: RenamedCase[] = [];
201
+
202
+ for (const file of changedTestFiles(projectRoot, previous, current)) {
203
+ const beforeSource = blobAt(projectRoot, previous, file);
204
+ if (beforeSource === null) continue;
205
+ const afterSource = blobAt(projectRoot, current, file);
206
+ const before = caseDeclarations(beforeSource);
207
+ const after = afterSource === null ? [] : caseDeclarations(afterSource);
208
+
209
+ const pairs = renamePairs(before, after);
210
+ for (const p of pairs) renamed.push({ file, from: p.from, to: p.to });
211
+ const paired = new Set(pairs.map(p => p.from));
212
+
213
+ const survived = new Set(after.map(d => d.name));
214
+ for (const name of new Set(before.map(d => d.name))) {
215
+ if (!survived.has(name) && !paired.has(name)) deleted.push({ name, file });
216
+ }
217
+ }
218
+ return { deleted, renamed };
219
+ }
220
+
221
+ /**
222
+ * Every test case the current commit has lost since the previous one.
223
+ *
224
+ * A projection of `caseChanges`, kept because every existing caller asks
225
+ * only this question. It is a projection and not a second walk: two walks
226
+ * would be two deciders, and the one that reported deletions could go on
227
+ * reporting a rename as one after the other had stopped.
228
+ */
229
+ export function deletedCases(
230
+ projectRoot: string,
231
+ previousCommit: string,
232
+ currentCommit: string,
233
+ ): DeletedCase[] {
234
+ return caseChanges(projectRoot, previousCommit, currentCommit).deleted;
235
+ }
236
+
237
+ // ── The verdict ──────────────────────────────────────────────────────────
238
+
239
+ /** What the previous build commit's own run says about each case. */
240
+ export type PassLedger =
241
+ | { status: "MEASURED"; passed: string[]; failed: string[] }
242
+ | { status: "UNMEASURED"; reason: string };
243
+
244
+ /**
245
+ * A deletion the operator has taken responsibility for (#661).
246
+ *
247
+ * Carries the reason with it rather than beside it, so a waived case and
248
+ * the justification for waiving it cannot be read apart in the artefact.
249
+ */
250
+ export interface WaivedCase extends DeletedCase {
251
+ acceptedReason: string;
252
+ /**
253
+ * What the previous build commit's ledger said about this case.
254
+ *
255
+ * A waiver RECORDS the reading, it does not erase it. Waiving a case the
256
+ * ledger proved green and waiving one nothing can judge are different
257
+ * acts, and a CLEAN that cannot tell them apart has thrown away the one
258
+ * fact this module exists to carry (`.claude/rules/config-access.md`:
259
+ * keep the whole reading, derive the boolean).
260
+ */
261
+ ledgerReading: LedgerReading;
262
+ }
263
+
264
+ /** What a ledger says about one case. `unjudged` is not `red`. */
265
+ export type LedgerReading = "green" | "red" | "unjudged";
266
+
267
+ /**
268
+ * Per-case waivers, modelled on `scripts/verify-merge-content.ts`.
269
+ *
270
+ * `cases` are matched by EXACT case name. There is deliberately no pattern,
271
+ * no prefix and no `all`: a waiver you have to write out one name at a time
272
+ * is a waiver somebody has to look at, and the artefact then lists each one
273
+ * against the reason. The cheapest wrong fix for a refusal is to widen it
274
+ * until it stops firing, and a wildcard here is that fix pre-installed.
275
+ */
276
+ export interface DeletionWaivers {
277
+ /**
278
+ * Each entry is `<file> :: <case name>` — the same spelling every report
279
+ * in this module prints, so a waiver is copied from the refusal rather
280
+ * than retyped.
281
+ *
282
+ * The FILE is required, and a waiver without one is refused rather than
283
+ * matched on the name alone. A case name is not unique across a tree:
284
+ * the round this check exists for deleted cases from two files at once,
285
+ * and a bare name like `the baseline` is the kind of name test files
286
+ * share. A name-only waiver silently clears every file that happens to
287
+ * declare it, which is the widening the exact-match design exists to
288
+ * prevent, in the one dimension a name cannot see.
289
+ */
290
+ cases: string[];
291
+ reason: string;
292
+ }
293
+
294
+ /** The separator every report and every waiver uses. One spelling. */
295
+ export const WAIVER_SEPARATOR = " :: ";
296
+
297
+ /** A waiver string, split — or a throw naming what was wrong with it. */
298
+ export function parseWaiver(raw: string): DeletedCase {
299
+ const at = raw.indexOf(WAIVER_SEPARATOR);
300
+ if (at < 0) {
301
+ throw new Error(
302
+ `the waiver "${raw}" names no file. Write it as it is printed — ` +
303
+ `"<file>${WAIVER_SEPARATOR}<case name>" — because a case name is not unique across ` +
304
+ "a tree and a name-only waiver clears every file that declares it",
305
+ );
306
+ }
307
+ const file = raw.slice(0, at);
308
+ const name = raw.slice(at + WAIVER_SEPARATOR.length);
309
+ if (file.trim() === "" || name.trim() === "") {
310
+ throw new Error(`the waiver "${raw}" has an empty file or case name`);
311
+ }
312
+ return { file, name };
313
+ }
314
+
315
+ /**
316
+ * The reading, with UNMEASURED as a first-class outcome.
317
+ *
318
+ * `renamed` is carried on every arm and never affects the verdict. A rename
319
+ * is not a deletion, so it cannot make a round dirty; and it is not nothing,
320
+ * so a round that renamed seven cases must not report the same thing as a
321
+ * round that touched none — that silence is what sent run `wf_99ed276b-cf3`
322
+ * looking for lost coverage that was sitting in front of it (#880).
323
+ */
324
+ export type DeletionReading =
325
+ | { verdict: "CLEAN"; cases: DeletedCase[]; waived?: WaivedCase[]; unusedWaivers?: string[]; renamed?: RenamedCase[] }
326
+ | { verdict: "DELETED"; cases: DeletedCase[]; waived?: WaivedCase[]; unusedWaivers?: string[]; renamed?: RenamedCase[] }
327
+ | {
328
+ verdict: "UNMEASURED";
329
+ cases: DeletedCase[];
330
+ reason: string;
331
+ waived?: WaivedCase[];
332
+ unusedWaivers?: string[];
333
+ renamed?: RenamedCase[];
334
+ };
335
+
336
+ /** A ledger from a bun JUnit report written at the previous build commit. */
337
+ export function ledgerFromJunit(path: string): PassLedger {
338
+ const reading = readJunitOutcomes(path);
339
+ if (reading.passed === null) {
340
+ return { status: "UNMEASURED", reason: reading.reason ?? `no JUnit report could be read at ${path}` };
341
+ }
342
+ return { status: "MEASURED", passed: reading.passed, failed: reading.failed };
343
+ }
344
+
345
+ /**
346
+ * Whether a ledger entry is about this case.
347
+ *
348
+ * bun's report carries the full `describe > describe > case` chain; a source
349
+ * file declares the bare name. A matcher demanding equality would read every
350
+ * case inside a describe block as never having run, and UNMEASURED would be
351
+ * the only verdict this check could ever produce on a real suite.
352
+ */
353
+ function names(entries: string[], name: string): boolean {
354
+ return entries.some(entry => entry === name || entry.endsWith(` > ${name}`));
355
+ }
356
+
357
+ /**
358
+ * The verdict for one deletion against one ledger.
359
+ *
360
+ * ONE discriminator: `verdict`. The three outcomes are projections of the
361
+ * same two lists computed here and nowhere else, so no two of them can
362
+ * disagree (`.claude/rules/config-access.md`).
363
+ *
364
+ * UNMEASURED outranks DELETED when both apply. A reading that reported
365
+ * DELETED while part of its input was unjudgeable would be claiming a
366
+ * complete answer it does not have, and the two outcomes refuse the run
367
+ * either way — what differs is what an operator is told to go and do.
368
+ */
369
+ export function deletionReading(
370
+ deleted: DeletedCase[],
371
+ ledger: PassLedger,
372
+ waivers: DeletionWaivers = { cases: [], reason: "" },
373
+ renamed: RenamedCase[] = [],
374
+ ): DeletionReading {
375
+ // Waivers are applied HERE, in the owning binding, and not in the script.
376
+ // A script that filtered its own input before calling this would be a
377
+ // second decider agreeing with the first, and a mutation of either would
378
+ // leave the other holding every case up
379
+ // (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
380
+ //
381
+ // ONE predicate, used by all three readers below. "Is this case waived?"
382
+ // asked in two places is two deciders that agree, so a mutation of either
383
+ // leaves the other applying the waiver and no behavioural test can tell
384
+ // them apart — measured: widening the `waived` list alone moved the record
385
+ // and left the verdict untouched, which is a mutant that proves nothing.
386
+ // `matches` is that predicate, and it is the ONLY place the shape of a
387
+ // waiver is decided. Widening it to a prefix — the cheap repair for an
388
+ // operator with five long case names to type — then moves the waived
389
+ // list, the verdict and the unused-waiver report together, instead of
390
+ // moving one and leaving the others to hold the case up.
391
+ // `matches` is that predicate, and it is the ONLY place the shape of a
392
+ // waiver is decided. Widening it to a prefix — the cheap repair for an
393
+ // operator with five long case names to type — then moves the waived
394
+ // list, the verdict and the unused-waiver report together, instead of
395
+ // moving one and leaving the others to hold the case up. Both components
396
+ // are compared: a name alone does not identify a case across a tree.
397
+ const refs = waivers.cases.map(parseWaiver);
398
+ const matches = (w: DeletedCase, d: DeletedCase) => w.name === d.name && w.file === d.file;
399
+ const isWaived = (d: DeletedCase) => refs.some(w => matches(w, d));
400
+
401
+ // The ledger's answer for one case, asked in ONE place. The green/red/
402
+ // unjudged split below is derived from it too, so a waived case and an
403
+ // unwaived one cannot be classified by two different readers.
404
+ const ledgerReadingOf = (d: DeletedCase): LedgerReading => {
405
+ if (ledger.status !== "MEASURED") return "unjudged";
406
+ if (names(ledger.passed, d.name)) return "green";
407
+ if (names(ledger.failed, d.name)) return "red";
408
+ return "unjudged";
409
+ };
410
+
411
+ const waived: WaivedCase[] = deleted
412
+ .filter(isWaived)
413
+ .map(d => ({ ...d, acceptedReason: waivers.reason, ledgerReading: ledgerReadingOf(d) }));
414
+ // A waiver that matches nothing is REPORTED, never silently dropped. It
415
+ // means either the deletion it covered is gone — so the waiver should go
416
+ // too — or the case was renamed and the waiver has quietly stopped
417
+ // applying, which is the failure mode an allowlist has
418
+ // (`feedback-exemption-list-self-reference`). Reported and not refused:
419
+ // refusing would be a scope this issue did not ask for.
420
+ const unusedWaivers = waivers.cases.filter((_raw, i) => !deleted.some(d => matches(refs[i], d)));
421
+ const extra = {
422
+ ...(waived.length > 0 ? { waived } : {}),
423
+ ...(unusedWaivers.length > 0 ? { unusedWaivers } : {}),
424
+ // Present only when there were any, so a round with no renames produces
425
+ // the record it always produced. An empty list beside an absent one is
426
+ // two spellings of the same fact, and the signature would then have two
427
+ // tokens for one reading.
428
+ ...(renamed.length > 0 ? { renamed } : {}),
429
+ };
430
+
431
+ deleted = deleted.filter(d => !isWaived(d));
432
+
433
+ // Nothing left, so there is nothing a ledger could tell us. This arm is
434
+ // what keeps the check usable: requiring a ledger on every round would
435
+ // refuse every run, and a refusal everyone overrides is not a check.
436
+ if (deleted.length === 0) return { verdict: "CLEAN", cases: [], ...extra };
437
+
438
+ if (ledger.status !== "MEASURED") {
439
+ return {
440
+ verdict: "UNMEASURED",
441
+ cases: deleted,
442
+ ...extra,
443
+ reason:
444
+ `${deleted.length} test case(s) were deleted between the two build commits and the ` +
445
+ `previous commit's ledger could not be read, so nothing says whether they were passing: ` +
446
+ `${ledger.reason}. Deleted: ${deleted.map(d => `${d.file} :: ${d.name}`).join("; ")}`,
447
+ };
448
+ }
449
+
450
+ // Three projections of ONE reading. `red` is not consulted below — a case
451
+ // the ledger proved red is not this defect — and it is named here so the
452
+ // three outcomes are visible as a partition rather than as two tests and
453
+ // a remainder.
454
+ const green = deleted.filter(d => ledgerReadingOf(d) === "green");
455
+ const unjudged = deleted.filter(d => ledgerReadingOf(d) === "unjudged");
456
+
457
+ if (unjudged.length > 0) {
458
+ return {
459
+ verdict: "UNMEASURED",
460
+ cases: deleted,
461
+ ...extra,
462
+ reason:
463
+ `the previous build commit's ledger does not mention ${unjudged.length} of the ` +
464
+ `${deleted.length} deleted case(s), so they are neither proven green nor proven red — ` +
465
+ `a case the ledger never ran is UNMEASURED, not red: ` +
466
+ `${unjudged.map(d => `${d.file} :: ${d.name}`).join("; ")}`,
467
+ };
468
+ }
469
+
470
+ // A case that was RED before is not this defect. Deleting it may still be
471
+ // wrong, and the test census (#307 SC-A19) is what refuses a round that
472
+ // removes tests at all; this check is about the narrower and more
473
+ // dangerous thing — a repair that deleted the evidence that it was not
474
+ // needed.
475
+ if (green.length === 0) return { verdict: "CLEAN", cases: [], ...extra };
476
+
477
+ return { verdict: "DELETED", cases: green, ...extra };
478
+ }
479
+
480
+ // ── The artefact, and the token that lets a restatement be checked ───────
481
+
482
+ /**
483
+ * What `--out` writes, and what the recommit-verify agent relays (#684).
484
+ *
485
+ * One composing binding rather than an object literal inside the script, so
486
+ * the signature is computed over the SAME object that reaches the disk. A
487
+ * script that built the artefact and then signed a second literal would be
488
+ * two deciders that agree (`.claude/rules/checks-must-be-able-to-fail.md`,
489
+ * the fourth shape), and a mutation of either would leave the other holding
490
+ * every case up.
491
+ */
492
+ export interface DeletionArtefact {
493
+ verdict: "CLEAN" | "DELETED" | "UNMEASURED";
494
+ previous: string;
495
+ current: string;
496
+ cases: DeletedCase[];
497
+ /** Why the reading is UNMEASURED, or null when it is not. */
498
+ reason: string | null;
499
+ waived?: WaivedCase[];
500
+ unusedWaivers?: string[];
501
+ /** Cases that changed title and nothing else (#880). */
502
+ renamed?: RenamedCase[];
503
+ /** @see deletionSignature */
504
+ signature: string;
505
+ }
506
+
507
+ /**
508
+ * A deterministic 32-bit fold, mirrored byte-for-byte in `workflows/ship.js`.
509
+ *
510
+ * FNV-1a and not a cryptographic hash, deliberately — see the
511
+ * `deletionSignature` docblock for what the signature does and does not
512
+ * claim. Its job is to make LIST CONTENTS part of the compared value at a
513
+ * fixed width, so the signature covers membership and not only counts.
514
+ *
515
+ * Simple enough to reimplement exactly in a workflow script that cannot
516
+ * import (#69), which is the actual constraint; anything needing a real
517
+ * digest would need a crypto primitive the workflow sandbox does not have.
518
+ */
519
+ export function deletionFold(s: string): string {
520
+ let h = 0x811c9dc5;
521
+ for (let i = 0; i < s.length; i++) {
522
+ h ^= s.charCodeAt(i);
523
+ h = Math.imul(h, 0x01000193) >>> 0;
524
+ }
525
+ return (h >>> 0).toString(16).padStart(8, "0");
526
+ }
527
+
528
+ /**
529
+ * The script's own canonical summary of the reading it wrote (#684).
530
+ *
531
+ * WHAT THIS IS FOR. `workflows/ship.js` never opens `deleted-cases.json`. It
532
+ * asks the repair agent to run the command and report the result, then
533
+ * branches the whole REPAIR_DELETED_TESTS decision off what came back. Before
534
+ * #684 that was `reCommit?.deletionVerdict || 'UNMEASURED'` and nothing
535
+ * compared the restatement against the thing restated — the agent whose
536
+ * verdict was being read is the agent the check exists to catch (#659).
537
+ *
538
+ * WHY A SIGNATURE RATHER THAN READING THE FILE, which is what #684 asks for
539
+ * in as many words. `ship.js` CANNOT read a file: it runs in a sandbox with
540
+ * no filesystem and no module loading (#69), and every `readFileSync` in it
541
+ * is inside a prompt string or a `bun -e` subprocess. Routing the read
542
+ * through a second agent would make the comparison itself a restatement,
543
+ * which is the defect wearing a fix. A signature moves the comparison into
544
+ * `ship.js`'s OWN process: the agent copies one opaque token, `ship.js`
545
+ * recomputes it from the structured fields it was handed, and a disagreement
546
+ * is UNMEASURED. This is #663's fix for `persistReceiptLines`, in the second
547
+ * place the same defect lives.
548
+ *
549
+ * THE COVERAGE IS THE RULE, and it is the first thing to check when adding a
550
+ * field to the operator line: **everything printed as evidence is in the
551
+ * signature, or it is not printed as evidence.** `cases`, `waived` (with each
552
+ * case's `ledgerReading` and `acceptedReason`), `unusedWaivers` and `reason`
553
+ * are all printed by `deletionVerdictReading`, so all of them are in here.
554
+ *
555
+ * Lists are covered by MEMBERSHIP and not by length: a restatement can swap
556
+ * an entry without changing a count, which is the trap
557
+ * `.claude/rules/checks-must-be-able-to-fail.md` names about #532. They are
558
+ * sorted first so the token is canonical rather than order-dependent — the
559
+ * question is which cases, not which order a summariser listed them in.
560
+ *
561
+ * WHICH OF #684'S THREE DOORS THIS CLOSES, stated rather than left for a
562
+ * reader to discover:
563
+ *
564
+ * 1. report CLEAN and never run the command — NOT closed. Fabricating a
565
+ * consistent token means reimplementing this function, and no in-process
566
+ * check can do better while #69 holds.
567
+ * 2. run it, read DELETED, report CLEAN — CLOSED. Altering the verdict
568
+ * breaks the token; copying the token and altering the one-word
569
+ * restatement breaks the comparison against it.
570
+ * 3. re-run it with --accept per case (#661) — never a hole, and now
571
+ * VISIBLE: a waived CLEAN logs as a waived CLEAN.
572
+ *
573
+ * The honest claim is "a restatement cannot drift SILENTLY", not "the
574
+ * artefact is authenticated".
575
+ *
576
+ * The format is versioned because `ship.js` carries a second implementation
577
+ * it cannot import, and two positions that must agree need a way to say they
578
+ * are talking about the same thing.
579
+ */
580
+ export function deletionSignature(a: {
581
+ verdict: string;
582
+ cases: DeletedCase[];
583
+ reason?: string | null;
584
+ waived?: WaivedCase[];
585
+ unusedWaivers?: string[];
586
+ renamed?: RenamedCase[];
587
+ }): string {
588
+ const cases = a.cases ?? [];
589
+ const waived = a.waived ?? [];
590
+ const unused = a.unusedWaivers ?? [];
591
+ const renamed = a.renamed ?? [];
592
+ const count = (reading: LedgerReading) => waived.filter(w => w.ledgerReading === reading).length;
593
+ // The three ledger readings are counted separately because the operator
594
+ // line distinguishes them: a waived case the ledger proved green and one
595
+ // nothing could judge are different acts (#661), and a token that reported
596
+ // them identically would let a restatement move a case between the two.
597
+ //
598
+ // `v2` because #880 added `renamed`, and a token's version is the only
599
+ // thing that can say two positions carrying the same prefix are talking
600
+ // about the same reading. `workflows/ship.js` carries the second
601
+ // implementation and cannot import this one; `test/deletion-verdict-relay.test.ts`
602
+ // compares them over a matrix, which is what makes a one-sided edit here
603
+ // a red suite rather than a silent UNMEASURED on every run.
604
+ const readable =
605
+ `v2:${a.verdict}:c${cases.length}:w${waived.length}:s${unused.length}` +
606
+ `:g${count("green")}:r${count("red")}:j${count("unjudged")}:n${renamed.length}`;
607
+ const caseIds = cases.map(c => `${c.file}${WAIVER_SEPARATOR}${c.name}`).sort();
608
+ const waivedIds = waived
609
+ .map(w => `${w.file}${WAIVER_SEPARATOR}${w.name}${WAIVER_SEPARATOR}${w.ledgerReading}${WAIVER_SEPARATOR}${w.acceptedReason}`)
610
+ .sort();
611
+ // Both titles, because the pair IS the evidence: a restatement that kept
612
+ // the old title and invented a new one would be claiming a rename that
613
+ // did not happen, which is the reassuring-direction error #880 names.
614
+ const renamedIds = renamed
615
+ .map(r => `${r.file}${WAIVER_SEPARATOR}${r.from}${WAIVER_SEPARATOR}${r.to}`)
616
+ .sort();
617
+ const members = [
618
+ ...caseIds,
619
+ "\u0000",
620
+ ...waivedIds,
621
+ "\u0000",
622
+ ...[...unused].sort(),
623
+ "\u0000",
624
+ ...renamedIds,
625
+ "\u0000",
626
+ a.reason ?? "",
627
+ ].join("\u0001");
628
+ return `${readable}:h${deletionFold(members)}`;
629
+ }
630
+
631
+ /** The reading, as the artefact on disk and in the agent's reply. */
632
+ export function deletionArtefact(
633
+ reading: DeletionReading,
634
+ previous: string,
635
+ current: string,
636
+ ): DeletionArtefact {
637
+ const base = {
638
+ verdict: reading.verdict,
639
+ previous,
640
+ current,
641
+ cases: reading.cases.map(c => ({ name: c.name, file: c.file })),
642
+ reason: reading.verdict === "UNMEASURED" ? reading.reason : null,
643
+ // Recorded unconditionally when present, so a CLEAN reached by waiving
644
+ // and a CLEAN reached by deleting nothing are different records.
645
+ ...(reading.waived ? { waived: reading.waived } : {}),
646
+ ...(reading.unusedWaivers ? { unusedWaivers: reading.unusedWaivers } : {}),
647
+ // A CLEAN reached by renaming seven cases and a CLEAN reached by
648
+ // touching none are different rounds, and the second is what the
649
+ // pre-#880 artefact said about both.
650
+ ...(reading.renamed ? { renamed: reading.renamed } : {}),
651
+ };
652
+ return { ...base, signature: deletionSignature(base) };
653
+ }