rungate 0.5.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 (142) 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 +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -31,24 +31,62 @@
31
31
  * difference is whether an implementation could change the answer.
32
32
  *
33
33
  * So every refusal here holds for all possible code. That is a hard bar and it
34
- * is why the set is small — three shapes, each of which makes the verdict a
35
- * constant.
34
+ * is why the set is small — six shapes, each of which makes the verdict a
35
+ * constant, or makes the number being compared a different number from the
36
+ * one the criterion is about.
37
+ *
38
+ * ## The three #669 clauses, and what widened the bar
39
+ *
40
+ * #664's run (`wf_448af2c4-6c1`) failed three of six ACs over correct and
41
+ * complete work, and two of the three could not have passed it. All three
42
+ * defects were in the instrument:
43
+ *
44
+ * 4. **A declared unit that is not what the command counts.** AC-6's
45
+ * threshold counts red test cases; its command counts matching lines of
46
+ * prose in a markdown section. Both integers, so the comparison is
47
+ * well-typed and meaningless.
48
+ * 5. **A literal the tree does not hold and the brief never named.** Both
49
+ * AC-6 and AC-7 opened an `awk` range on a heading DISCOVERY invented.
50
+ * The implementer wrote a better one, the range came back empty, and the
51
+ * gate read `0`.
52
+ * 6. **A flag the tool ignores.** `bun test --grep` is not a bun flag; bun
53
+ * exits 0 without complaining, so AC-2's command was behaviourally
54
+ * identical to AC-1's and the criterion that existed to be independent
55
+ * of AC-1 was checked by the same observation.
56
+ *
57
+ * Clauses 4 and 6 keep the original bar: the verdict cannot be about the code
58
+ * under any implementation. Clause 5 is the one widening — the number it
59
+ * produces is a constant only until somebody guesses the string, which is the
60
+ * point. It is also the only clause that needs to read the tree, so it is the
61
+ * only one with a context argument, and with no reader in hand it refuses
62
+ * nothing rather than guessing at a project root.
36
63
  */
37
64
 
38
65
  // ── Shell tokenising ─────────────────────────────────────────────────────
39
66
 
67
+ /** One token of a command, and whether any of it arrived inside quotes. */
68
+ interface Token {
69
+ text: string;
70
+ quoted: boolean;
71
+ }
72
+
40
73
  /**
41
74
  * Split one pipeline stage into tokens, honouring quotes, and strip the
42
75
  * quotes. Not a shell parser — it is enough to find grep's flags and its
43
76
  * pattern argument, and anything it cannot read falls through to NO refusal.
44
77
  * A tokeniser that guesses would refuse a working command, and a false
45
78
  * refusal here stops a legitimate run cold.
79
+ *
80
+ * `quoted` is carried because a flag clause must not read `-t '--grep is not
81
+ * a flag'` as an invocation of `--grep`, and the quoting is the only thing
82
+ * that distinguishes them once the quotes are gone.
46
83
  */
47
- function tokenize(stage: string): string[] {
48
- const tokens: string[] = [];
84
+ function tokenizeParts(stage: string): Token[] {
85
+ const tokens: Token[] = [];
49
86
  let current = "";
50
87
  let quote: '"' | "'" | null = null;
51
88
  let started = false;
89
+ let quotedHere = false;
52
90
 
53
91
  for (let i = 0; i < stage.length; i++) {
54
92
  const ch = stage[i];
@@ -60,23 +98,95 @@ function tokenize(stage: string): string[] {
60
98
  if (ch === '"' || ch === "'") {
61
99
  quote = ch;
62
100
  started = true;
101
+ quotedHere = true;
63
102
  continue;
64
103
  }
65
104
  if (/\s/.test(ch)) {
66
- if (started || current) tokens.push(current);
105
+ if (started || current) tokens.push({ text: current, quoted: quotedHere });
67
106
  current = "";
68
107
  started = false;
108
+ quotedHere = false;
69
109
  continue;
70
110
  }
71
111
  current += ch;
72
112
  }
73
- if (started || current) tokens.push(current);
113
+ if (started || current) tokens.push({ text: current, quoted: quotedHere });
74
114
  return tokens;
75
115
  }
76
116
 
117
+ function tokenize(stage: string): string[] {
118
+ return tokenizeParts(stage).map((t) => t.text);
119
+ }
120
+
121
+ /**
122
+ * Split on delimiters that are not inside quotes.
123
+ *
124
+ * A naive `split("|")` cuts a command in half at the alternation inside
125
+ * `grep -ciE 'a|b'` and then reads `b'` as the producing stage — which is
126
+ * how #664's AC-6 passed every clause in this file while counting lines of
127
+ * prose against a threshold of test cases. Measured: with the naive split,
128
+ * `satisfiabilityRefusal` returns null for that AC; with this one it names
129
+ * the mismatch.
130
+ *
131
+ * Delimiters are matched longest-first, so `&&` is not read as two empty
132
+ * segments around nothing.
133
+ *
134
+ * #659 found the same defect from the other end: `'SKIP_STATES|pattern: …'`
135
+ * carries a `|` inside single quotes, and a split that cannot see the quotes
136
+ * cuts one grep into four stages whose last word is part of a regex. Every
137
+ * reading taken off the last stage — `emitsCount`, and so both the threshold
138
+ * clause and the count-of-counts clause — then answers about a stage that
139
+ * does not exist.
140
+ */
141
+ function splitUnquoted(command: string, delimiters: readonly string[]): string[] {
142
+ const parts: string[] = [];
143
+ let current = "";
144
+ let quote: '"' | "'" | null = null;
145
+
146
+ for (let i = 0; i < command.length; i++) {
147
+ const ch = command[i];
148
+ if (quote) {
149
+ current += ch;
150
+ if (ch === quote) quote = null;
151
+ continue;
152
+ }
153
+ if (ch === '"' || ch === "'") {
154
+ quote = ch;
155
+ current += ch;
156
+ continue;
157
+ }
158
+ const hit = delimiters.find((d) => command.startsWith(d, i));
159
+ if (hit) {
160
+ parts.push(current);
161
+ current = "";
162
+ i += hit.length - 1;
163
+ continue;
164
+ }
165
+ current += ch;
166
+ }
167
+ parts.push(current);
168
+ return parts.map((s) => s.trim()).filter((s) => s.length > 0);
169
+ }
170
+
77
171
  /** The pipeline stages of a command, in order, trimmed. */
78
172
  function stages(command: string): string[] {
79
- return command.split("|").map((s) => s.trim()).filter((s) => s.length > 0);
173
+ return splitUnquoted(command, ["|"]);
174
+ }
175
+
176
+ /**
177
+ * The commands the shell would run one after another.
178
+ *
179
+ * `;`, `&&` and a newline, and deliberately NOT `||`: `cmd || true` is the
180
+ * fallback idiom, only one side of it runs, and treating the alternative as
181
+ * a second command would refuse a command that emits exactly one value
182
+ * (#659).
183
+ *
184
+ * `&&` is listed first because `splitUnquoted` matches delimiters in array
185
+ * order, so a shorter delimiter placed ahead of a longer one it prefixes
186
+ * would cut the longer one in half.
187
+ */
188
+ function commandList(command: string): string[] {
189
+ return splitUnquoted(command, ["&&", ";", "\n"]);
80
190
  }
81
191
 
82
192
  /** Strip leading `VAR=value` assignments and return the command word. */
@@ -195,17 +305,75 @@ function breRefusal(g: GrepStage): string | null {
195
305
 
196
306
  // ── Clause 2: a count compared as text ───────────────────────────────────
197
307
 
198
- /** Does this command's output consist of a number rather than the matched text? */
199
- function emitsCount(command: string): boolean {
308
+ /**
309
+ * What quantity a counting command counts.
310
+ *
311
+ * `unknown` is a count whose quantity this cannot name — bare `wc` prints
312
+ * three numbers — and it is compatible with every unit, because a clause that
313
+ * refused on a reading it could not take would be guessing.
314
+ */
315
+ type CountClass = "lines" | "files" | "words" | "bytes" | "unknown";
316
+
317
+ interface CountedQuantity {
318
+ klass: CountClass;
319
+ /** How the refusal names it to a reader. */
320
+ text: string;
321
+ }
322
+
323
+ /** Does this stage print file NAMES, one per line, rather than file content? */
324
+ function listsFiles(stage: string): boolean {
325
+ const tokens = tokenize(stage);
326
+ const word = commandWord(tokens);
327
+ if (word === "find" || word === "ls") return true;
328
+ if (word === "git" && tokens.includes("ls-files")) return true;
329
+ const g = readGrep(stage);
330
+ if (!g) return false;
331
+ return tokens.some((t) => /^-[a-zA-Z]*[lL][a-zA-Z]*$/.test(t) || t === "--files-with-matches");
332
+ }
333
+
334
+ /**
335
+ * The quantity this command's output IS, or null when its output is text
336
+ * rather than a count.
337
+ *
338
+ * One binding, and `emitsCount` is a projection of it: a second function
339
+ * answering "is this a count" beside this one would be two deciders agreeing
340
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape), and a
341
+ * mutation of either would leave the other holding every case up.
342
+ */
343
+ function countedQuantity(command: string): CountedQuantity | null {
200
344
  const all = stages(command);
201
345
  // `tr -d ' '` and friends reformat a value without changing what it IS, so
202
346
  // the producing stage is the last one that is not pure reformatting.
203
347
  let i = all.length - 1;
204
348
  while (i > 0 && commandWord(tokenize(all[i])) === "tr") i--;
205
349
  const last = all[i];
206
- if (commandWord(tokenize(last)) === "wc") return true;
350
+
351
+ if (commandWord(tokenize(last)) === "wc") {
352
+ const flags = tokenize(last)
353
+ .filter((t) => /^-[a-zA-Z]+$/.test(t))
354
+ .join("");
355
+ if (flags.includes("l")) {
356
+ return i > 0 && listsFiles(all[i - 1])
357
+ ? { klass: "files", text: "the files the previous stage listed, one per line" }
358
+ : { klass: "lines", text: "lines of its input" };
359
+ }
360
+ if (flags.includes("w")) return { klass: "words", text: "words of its input" };
361
+ if (flags.includes("c") || flags.includes("m")) {
362
+ return { klass: "bytes", text: "bytes of its input" };
363
+ }
364
+ return { klass: "unknown", text: "a count of its input" };
365
+ }
366
+
207
367
  const g = readGrep(last);
208
- return g?.counting === true;
368
+ if (g?.counting === true) {
369
+ return { klass: "lines", text: "lines matching the pattern, one count per file" };
370
+ }
371
+ return null;
372
+ }
373
+
374
+ /** Does this command's output consist of a number rather than the matched text? */
375
+ function emitsCount(command: string): boolean {
376
+ return countedQuantity(command) !== null;
209
377
  }
210
378
 
211
379
  function thresholdRefusal(command: string, op: string): string | null {
@@ -243,6 +411,314 @@ function countOfCountsRefusal(command: string): string | null {
243
411
  );
244
412
  }
245
413
 
414
+ // ── Clause 4: a declared unit that is not what the command counts ────────
415
+
416
+ /**
417
+ * The quantities a `unit` can name, and the words that name them.
418
+ *
419
+ * Deliberately small. A word not in here is not a quantity as far as this is
420
+ * concerned, and an AC whose unit names no quantity is accepted — "sites",
421
+ * "windows", "occurrences", "violations" and "matches" are all one-per-line
422
+ * readings an author is entitled to, and refusing them would make the most
423
+ * common evidence shape in the repo unusable.
424
+ *
425
+ * `(?<![-\w])` keeps a hyphenated modifier out of it: #664 AC-1's unit is
426
+ * "fixed-character slice windows", which names no quantity, and a bare
427
+ * `\bcharacters?\b` would have read it as a count of bytes.
428
+ *
429
+ * `test` and `tests` are NOT here, on purpose. They are modifiers far more
430
+ * often than heads in this repo's units — "test files read by the scan",
431
+ * "converted test sites importing the shared helper" — and the quantity
432
+ * #664's AC-6 actually declared is `cases`.
433
+ */
434
+ type DeclaredClass = "lines" | "files" | "words" | "bytes" | "cases";
435
+
436
+ const UNIT_CLASSES: Array<[DeclaredClass, RegExp]> = [
437
+ ["lines", /(?<![-\w])(?:lines?|rows?)\b/i],
438
+ ["files", /(?<![-\w])(?:files?|paths?)\b/i],
439
+ ["words", /(?<![-\w])words?\b/i],
440
+ ["bytes", /(?<![-\w])(?:bytes?|characters?|chars?)\b/i],
441
+ // A count of test cases is never a count of lines of a document, which is
442
+ // the whole of #664 AC-6.
443
+ ["cases", /(?<![-\w])(?:test cases?|cases?|assertions?)\b/i],
444
+ ];
445
+
446
+ /** Which declared quantity is compatible with which counted one. */
447
+ const COMPATIBLE: Record<Exclude<CountClass, "unknown">, ReadonlySet<DeclaredClass>> = {
448
+ lines: new Set<DeclaredClass>(["lines"]),
449
+ // A list of file names IS a list of lines, so both readings are honest.
450
+ files: new Set<DeclaredClass>(["files", "lines"]),
451
+ words: new Set<DeclaredClass>(["words"]),
452
+ bytes: new Set<DeclaredClass>(["bytes"]),
453
+ };
454
+
455
+ /** How a refusal names each declared quantity. */
456
+ const CLASS_LABEL: Record<DeclaredClass, string> = {
457
+ lines: "lines",
458
+ files: "files",
459
+ words: "words",
460
+ bytes: "bytes",
461
+ cases: "test cases",
462
+ };
463
+
464
+ /**
465
+ * The quantity the unit is ABOUT — its head phrase, cut at the first
466
+ * preposition.
467
+ *
468
+ * "matching lines in lib/a.ts" is a count of lines; "red cases, one per
469
+ * matching line" is a count of cases the author has told you how to read off
470
+ * lines. Searching the whole string for a compatible word is the right
471
+ * reading for the second and the wrong one for the first, so the head is
472
+ * searched for the DISAGREEMENT and the whole string for the AGREEMENT. The
473
+ * asymmetry is in the safe direction: anything the author related to the
474
+ * counted quantity anywhere in the unit is accepted.
475
+ */
476
+ function unitHead(unit: string): string {
477
+ const cut = unit.search(
478
+ /\b(?:in|of|per|from|across|under|by|with|over|within|into|for|on|at|between|through|after|before|against)\b/i,
479
+ );
480
+ return cut > 0 ? unit.slice(0, cut) : unit;
481
+ }
482
+
483
+ function classesIn(text: string): DeclaredClass[] {
484
+ return UNIT_CLASSES.filter(([, re]) => re.test(text)).map(([k]) => k);
485
+ }
486
+
487
+ function unitDisagreementRefusal(
488
+ id: string,
489
+ command: string,
490
+ threshold: { unit?: string } | undefined,
491
+ ): string | null {
492
+ const counted = countedQuantity(command);
493
+ if (!counted || counted.klass === "unknown") return null;
494
+
495
+ const unit = typeof threshold?.unit === "string" ? threshold.unit.trim() : "";
496
+ if (unit.length === 0) return null;
497
+
498
+ const compatible = COMPATIBLE[counted.klass];
499
+ const declared = classesIn(unitHead(unit));
500
+ if (declared.length === 0) return null;
501
+ if (declared.some((d) => compatible.has(d))) return null;
502
+ // The author may have related the two quantities further into the unit.
503
+ if (classesIn(unit).some((d) => compatible.has(d))) return null;
504
+
505
+ const named = declared.map((d) => CLASS_LABEL[d]).join(" and ");
506
+ return (
507
+ `${id}: the threshold's unit "${unit}" declares a count of ${named}, but the command counts ` +
508
+ `${counted.text} — the two are both integers, so the comparison is well-typed and about ` +
509
+ `nothing. Count the thing the unit names, or name the thing the command counts`
510
+ );
511
+ }
512
+
513
+ // ── Clause 5: a literal the tree does not hold ───────────────────────────
514
+
515
+ /**
516
+ * Pull the plain-text literals a command keys on out of its quoted
517
+ * arguments.
518
+ *
519
+ * Quoted arguments ONLY. An unquoted path that does not exist already fails
520
+ * the dry run with grep's exit 2 and is classified `broken` there, and a
521
+ * second decider for a question something else already answers is the fourth
522
+ * shape in `.claude/rules/checks-must-be-able-to-fail.md`.
523
+ *
524
+ * An `awk`/`sed` program is unwrapped first: `'/^## Heading/,/^## [^T]/'` is
525
+ * one quoted token carrying two patterns, and the heading is the half a
526
+ * reader can act on.
527
+ *
528
+ * A candidate must survive three filters, each of which exists to keep a
529
+ * refusal actionable:
530
+ *
531
+ * - anchors are stripped, then anything still carrying a regular-expression
532
+ * metacharacter is dropped. `^## [^T]` is a pattern, not a string a tree
533
+ * can hold, and telling an implementer to go and add it is nonsense.
534
+ * - it must be at least `MIN_LITERAL` characters. Short tokens are words,
535
+ * flags and single letters, and the thing this clause is about is an
536
+ * invented heading or marker.
537
+ * - it must contain a letter, so a number or a punctuation run is not
538
+ * quoted back as an interface.
539
+ */
540
+ const MIN_LITERAL = 12;
541
+
542
+ function literalCandidates(command: string): string[] {
543
+ const out: string[] = [];
544
+ for (const m of command.matchAll(/'([^']*)'|"([^"]*)"/g)) {
545
+ const raw = m[1] ?? m[2] ?? "";
546
+ const pieces = /^\s*\/.*\/\s*(?:,\s*\/.*\/\s*)?$/.test(raw)
547
+ ? [...raw.matchAll(/\/((?:[^/\\]|\\.)*)\//g)].map((p) => p[1])
548
+ : [raw];
549
+ for (const piece of pieces) {
550
+ const text = piece.replace(/^\^/, "").replace(/\$$/, "").trim();
551
+ if (text.length < MIN_LITERAL) continue;
552
+ if (/[\\[\]{}()|*+?]|\.\*/.test(text)) continue;
553
+ if (!/[A-Za-z]/.test(text)) continue;
554
+ if (!out.includes(text)) out.push(text);
555
+ }
556
+ }
557
+ return out;
558
+ }
559
+
560
+ function absentLiteralRefusal(
561
+ id: string,
562
+ command: string,
563
+ evidenceType: string | undefined,
564
+ declaredInterfaces: readonly string[],
565
+ context: SatisfiabilityContext | undefined,
566
+ ): string | null {
567
+ const treeContains = context?.treeContains;
568
+ // No reader, no reading. UNMEASURED, not clean — and the caller is told so
569
+ // by the docstring rather than by a refusal this cannot support.
570
+ if (typeof treeContains !== "function") return null;
571
+ if (String(evidenceType ?? "").toUpperCase() !== "COMMAND") return null;
572
+
573
+ const named = [...declaredInterfaces, ...(context?.briefInterfaces ?? [])].map(String);
574
+ const absent = literalCandidates(command).filter(
575
+ (lit) => !treeContains(lit) && !named.some((n) => n.includes(lit)),
576
+ );
577
+ if (absent.length === 0) return null;
578
+
579
+ return (
580
+ `${id}: the evidence keys on ${absent.map((l) => `\`${l}\``).join(", ")}, which the tree does ` +
581
+ `not hold at run start and the implementer's brief does not name as an interface — the gate ` +
582
+ `would be measuring whether the implementer guessed that exact string. Carry it into the ` +
583
+ `brief as a named interface, or key the evidence on something that exists`
584
+ );
585
+ }
586
+
587
+ // ── Clause 6: a flag the tool does not accept ────────────────────────────
588
+
589
+ /**
590
+ * Every long flag `bun test` accepts, transcribed from `bun test --help` and
591
+ * `bun --help` on v1.3.x, without the leading dashes.
592
+ *
593
+ * Exported because `test/evidence-flag-validation.test.ts` runs the real
594
+ * binary's help and asserts the table still covers it. A transcription with
595
+ * nothing comparing it to the tool is #621's defect: two documents naming one
596
+ * thing and no check between them.
597
+ */
598
+ export const BUN_TEST_FLAGS: ReadonlySet<string> = new Set([
599
+ // bun test
600
+ "no-orphans", "timeout", "update-snapshots", "rerun-each", "retry", "todo", "only",
601
+ "pass-with-no-tests", "concurrent", "randomize", "seed", "coverage", "coverage-reporter",
602
+ "coverage-dir", "bail", "test-name-pattern", "reporter", "reporter-outfile", "dots",
603
+ "only-failures", "max-concurrency", "path-ignore-patterns", "changed", "isolate",
604
+ "parallel", "parallel-delay", "test-worker", "shard",
605
+ // bun, globally
606
+ "conditions", "console-depth", "cpu-prof", "cpu-prof-dir", "cpu-prof-interval", "cpu-prof-md",
607
+ "cpu-prof-name", "cron-period", "cron-title", "cwd", "dns-result-order", "elide-lines",
608
+ "env-file", "experimental-http2-fetch", "experimental-http3-fetch", "expose-gc",
609
+ "fetch-preconnect", "heap-prof", "heap-prof-dir", "heap-prof-md", "heap-prof-name", "hot",
610
+ "if-present", "import", "inspect", "inspect-brk", "inspect-wait", "install",
611
+ "max-http-header-size", "no-addons", "no-clear-screen", "no-deprecation", "no-env-file",
612
+ "no-exit-on-error", "no-install", "port", "prefer-latest", "prefer-offline",
613
+ "redis-preconnect", "require", "revision", "sequential", "shell", "silent", "smol",
614
+ "sql-preconnect", "throw-deprecation", "title", "unhandled-rejections", "use-bundled-ca",
615
+ "use-openssl-ca", "use-system-ca", "user-agent", "watch", "workspaces", "zero-fill-buffers",
616
+ "bun", "config", "eval", "filter", "help", "print", "preload", "version",
617
+ ]);
618
+
619
+ /**
620
+ * A flag somebody reached for, and what the tool actually calls it.
621
+ *
622
+ * A refusal naming only what is wrong costs a round; naming the replacement
623
+ * is what makes the next run a fix rather than a guess (#263).
624
+ */
625
+ const BUN_TEST_ALTERNATIVES: Record<string, string> = {
626
+ "--grep": "--test-name-pattern",
627
+ "--testNamePattern": "--test-name-pattern",
628
+ "--test-name-filter": "--test-name-pattern",
629
+ "--testPathPattern": "a bare path argument",
630
+ "--runInBand": "--parallel=1",
631
+ "--verbose": "no equivalent — bun test prints every test name by default",
632
+ };
633
+
634
+ /**
635
+ * Split a command into the things that get EXECUTED, across `|`, `&&`, `||`
636
+ * and `;`.
637
+ *
638
+ * Not `stages()`, which answers a different question — which stage produces
639
+ * the output — and must stay pipe-only to answer it. Two questions, two
640
+ * splitters; collapsing them would make `cd /tmp && bun test …` look like a
641
+ * command whose output is `cd`'s.
642
+ */
643
+ function executedSegments(command: string): string[] {
644
+ return splitUnquoted(command, ["&&", "||", "|", ";", "\n"]);
645
+ }
646
+
647
+ function unknownFlagRefusal(id: string, command: string): string | null {
648
+ for (const segment of executedSegments(command)) {
649
+ const tokens = tokenizeParts(segment).filter((t) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(t.text));
650
+ if (tokens[0]?.text !== "bun" || tokens[0].quoted) continue;
651
+ const sub = tokens.slice(1).find((t) => !t.text.startsWith("-"));
652
+ if (sub?.text !== "test") continue;
653
+
654
+ for (const t of tokens.slice(1)) {
655
+ if (t.quoted || !t.text.startsWith("--") || t.text === "--") continue;
656
+ const name = t.text.split("=")[0];
657
+ const bare = name.slice(2);
658
+ if (BUN_TEST_FLAGS.has(bare)) continue;
659
+ if (bare.startsWith("no-") && BUN_TEST_FLAGS.has(bare.slice(3))) continue;
660
+ const alternative = BUN_TEST_ALTERNATIVES[name];
661
+ return (
662
+ `${id}: \`bun test\` does not accept \`${name}\` — it is not in \`bun test --help\`, and ` +
663
+ `bun IGNORES it silently rather than failing, so the command runs clean and measures ` +
664
+ `something other than what the criterion says` +
665
+ (alternative ? `. Use \`${alternative}\` instead` : "")
666
+ );
667
+ }
668
+ }
669
+ return null;
670
+ }
671
+
672
+ // ── Clause 4: more values than the threshold can judge ───────────────────
673
+
674
+ /**
675
+ * The operators that compare ONE value with one other value.
676
+ *
677
+ * `contains` and `exists` read the output as text, and the concatenation of
678
+ * several outputs is text that may legitimately contain the value — so they
679
+ * are outside this clause rather than inside it with an exception.
680
+ */
681
+ const VALUE_OPS = new Set(["==", ">=", "<=", ">", "<", "!=", "notContains"]);
682
+
683
+ /**
684
+ * Two or more commands, each printing its own count, judged by one threshold
685
+ * (#659).
686
+ *
687
+ * Measured on `wf_2abbe96f-546`. Its AC-9 ran two greps joined by a
688
+ * semicolon and carried `{op: "==", value: 0}`. The first prints `0` and the
689
+ * second `2` — at BOTH of that run's build commits — so the command's output
690
+ * is the two-line string `"0\n2"`, which is not a number and cannot be
691
+ * compared with `0`. The scorer recorded `2`, the AC went FAIL, and a repair
692
+ * cycle then deleted three passing tests trying to satisfy a verdict that was
693
+ * never about the code.
694
+ *
695
+ * This holds for ALL possible code, which is the bar this module sets: no
696
+ * implementation makes two numbers into one, and nothing in the AC says which
697
+ * half the threshold is about. The verdict is a property of which value the
698
+ * scorer happens to read — the same defect
699
+ * `.claude/rules/checks-must-be-able-to-fail.md` is about, reached from a
700
+ * third side.
701
+ *
702
+ * NARROW ON PURPOSE, in the direction this module is allowed to be wrong in.
703
+ * A prelude (`cd lib; grep -c …`), a fallback (`grep -c … || true`) and a
704
+ * trailing `echo` all leave exactly one counting command and are accepted.
705
+ * The boundary is held in both directions by
706
+ * `test/unit/multi-value-evidence.test.ts`.
707
+ */
708
+ function multiValueRefusal(command: string, op: string | undefined): string | null {
709
+ if (typeof op !== "string" || !VALUE_OPS.has(op)) return null;
710
+ const list = commandList(command);
711
+ if (list.length < 2) return null;
712
+ const counting = list.filter(emitsCount);
713
+ if (counting.length < 2) return null;
714
+ return (
715
+ `the command runs ${counting.length} separate commands that each print a count ` +
716
+ `(\`${counting.join("`, `")}\`), so its output is ${counting.length} values and a single ` +
717
+ `\`${op}\` threshold can judge only one of them — which one is read is a property of the ` +
718
+ `scorer rather than of the code, under every implementation. Split it into one AC per value`
719
+ );
720
+ }
721
+
246
722
  // ── The one decider ──────────────────────────────────────────────────────
247
723
 
248
724
  /** The shape this reads. Structurally `ACInput`, repeated so this stays a leaf. */
@@ -250,6 +726,27 @@ export interface SatisfiabilityInput {
250
726
  id?: string;
251
727
  evidenceMethod?: { type?: string; command?: string };
252
728
  threshold?: { op?: string; value?: string | number; unit?: string };
729
+ /**
730
+ * Literals this AC's evidence keys on that the implementer is being TOLD
731
+ * about — the waiver clause 5 reads. An invented string is only a guess
732
+ * while nobody has been shown it.
733
+ */
734
+ evidenceInterfaces?: readonly string[];
735
+ }
736
+
737
+ /**
738
+ * What the decider is allowed to read about the world outside the AC.
739
+ *
740
+ * Optional, and every clause that uses it refuses nothing without it. The
741
+ * alternative — defaulting a project root — is Silent Default Substitution
742
+ * (`.claude/rules/config-access.md`) in the position where it does the most
743
+ * damage: a refusal computed against the wrong tree.
744
+ */
745
+ export interface SatisfiabilityContext {
746
+ /** Does the tree, as it stands BEFORE the work, hold this literal anywhere? */
747
+ treeContains?: (literal: string) => boolean;
748
+ /** Literals the implementer's brief names as interfaces. */
749
+ briefInterfaces?: readonly string[];
253
750
  }
254
751
 
255
752
  /**
@@ -261,10 +758,14 @@ export interface SatisfiabilityInput {
261
758
  * be wrong in. Missing a bad AC costs one failed run that a human reads. A
262
759
  * false refusal blocks a correct run, and nobody trusts the refuser again.
263
760
  */
264
- export function satisfiabilityRefusal(ac: SatisfiabilityInput | null | undefined): string | null {
761
+ export function satisfiabilityRefusal(
762
+ ac: SatisfiabilityInput | null | undefined,
763
+ context?: SatisfiabilityContext,
764
+ ): string | null {
265
765
  const command = ac?.evidenceMethod?.command;
266
766
  if (typeof command !== "string" || command.trim().length === 0) return null;
267
767
 
768
+ const id = typeof ac?.id === "string" && ac.id.length > 0 ? ac.id : "this AC";
268
769
  const reasons: string[] = [];
269
770
 
270
771
  const countOfCounts = countOfCountsRefusal(command);
@@ -276,6 +777,9 @@ export function satisfiabilityRefusal(ac: SatisfiabilityInput | null | undefined
276
777
  if (mismatch) reasons.push(mismatch);
277
778
  }
278
779
 
780
+ const multiValue = multiValueRefusal(command, op);
781
+ if (multiValue) reasons.push(multiValue);
782
+
279
783
  for (const stage of stages(command)) {
280
784
  const g = readGrep(stage);
281
785
  if (!g) continue;
@@ -283,6 +787,24 @@ export function satisfiabilityRefusal(ac: SatisfiabilityInput | null | undefined
283
787
  if (bre) reasons.push(bre);
284
788
  }
285
789
 
790
+ // #669. Three clauses about the instrument rather than the pattern: what
791
+ // the number counts, what string the command bets on, and whether the tool
792
+ // is even reading the flag.
793
+ const unitDisagreement = unitDisagreementRefusal(id, command, ac?.threshold);
794
+ if (unitDisagreement) reasons.push(unitDisagreement);
795
+
796
+ const absentLiteral = absentLiteralRefusal(
797
+ id,
798
+ command,
799
+ ac?.evidenceMethod?.type,
800
+ Array.isArray(ac?.evidenceInterfaces) ? ac.evidenceInterfaces : [],
801
+ context,
802
+ );
803
+ if (absentLiteral) reasons.push(absentLiteral);
804
+
805
+ const unknownFlag = unknownFlagRefusal(id, command);
806
+ if (unknownFlag) reasons.push(unknownFlag);
807
+
286
808
  if (reasons.length === 0) return null;
287
809
  return reasons.join("; ");
288
810
  }