rungate 0.8.2 → 0.8.4

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 (74) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/BunTestPathGuard.hook.ts +106 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
@@ -0,0 +1,253 @@
1
+ /**
2
+ * bun-test-paths.ts — the decision behind BunTestPathGuard (#1544)
3
+ *
4
+ * One question: does this Bash command hand `bun test` a path that matches
5
+ * no file?
6
+ *
7
+ * ## What bun does, measured in this tree on bun 1.3.14
8
+ *
9
+ * | command | exit | summary line |
10
+ * |---|---|---|
11
+ * | `bun test <absent>` | 1 | no test file matched at all |
12
+ * | `bun test <real> <absent>` | **0** | `Ran 4 tests across 1 file.` |
13
+ * | `bun test <real> ./<absent>` | **0** | nothing about the absent path |
14
+ *
15
+ * A path argument that matches no file is treated as a name FILTER. Bun
16
+ * exits non-zero only when the whole filter set matched zero files; if at
17
+ * least one path matched, every unmatched argument is silent and the run
18
+ * exits 0. So a typo'd path alongside real ones is indistinguishable from a
19
+ * suite that ran and passed — which is `.claude/rules/checks-must-be-able-to-fail.md`'s
20
+ * sixth shape, *green on the exit code, witnessing the wrong mechanism*, in
21
+ * the instrument every agent in this repo verifies its own work with.
22
+ *
23
+ * The live instance: on 2026-10-24, shipping #1536, a verification command
24
+ * named `test/sc-reservations.test.ts`. The real file is
25
+ * `test/sc-reservation-store.test.ts`. Five other paths ran, the command
26
+ * exited 0 reporting `181 pass, 0 fail`, and the suite that would have
27
+ * caught the defect was never opened. CI found it afterwards, on
28
+ * `test-shard (3)`.
29
+ *
30
+ * ## Why a pre-flight stat and not the summary line
31
+ *
32
+ * `Ran N tests across M files` is the only output that distinguishes the two
33
+ * cases — M must equal the number of path arguments. It is a sound reading
34
+ * and it is POST-HOC: it needs the run to have happened and the reader to
35
+ * have thought to look. This refuses before bun is invoked, costs one
36
+ * `existsSync` per argument, and does not depend on anybody remembering.
37
+ *
38
+ * ## Why a hook and not a wrapper script
39
+ *
40
+ * Measured on this tree: 55 sites execute `bun test` with a path argument,
41
+ * 49 of them inside `test/`. A wrapper covers 0 of them on the day it lands,
42
+ * and covers an agent typing `bun test …` by hand — the case that produced
43
+ * this issue — never. The Bash tool is the one chokepoint every agent-composed
44
+ * command passes through.
45
+ *
46
+ * ## The direction this is allowed to be wrong in
47
+ *
48
+ * Toward ALLOWING. The guard fires on every `bun test` an agent runs, so a
49
+ * false refusal is a wall in front of correct work, repeated. Three classes
50
+ * of argument are therefore skipped rather than resolved, because the hook
51
+ * sees the command BEFORE the shell expands it:
52
+ *
53
+ * - a glob (`test/*.test.ts`) — the shell expands it, bun never sees the
54
+ * metacharacters, and `existsSync` on the unexpanded string is always false
55
+ * - a variable or substitution (`$SUITE`, `$(…)`, backticks) — the hook has
56
+ * no access to shell state
57
+ * - anything that is not path-shaped — bun treats a bare word as a substring
58
+ * name filter and that is a legitimate thing to type
59
+ *
60
+ * ## WHAT THIS DOES NOT COVER
61
+ *
62
+ * Asserted as cases in `test/bun-test-path-guard.test.ts`, not merely listed,
63
+ * so a later widening goes red rather than silently changing behaviour.
64
+ *
65
+ * - A spawn from inside an already-running process. The 49 `test/` sites and
66
+ * `scripts/test-clean-env.ts` never reach the Bash tool, so no PreToolUse
67
+ * hook can see them. `suitePathArguments` is exported for a caller that
68
+ * wants to check its own arguments; nothing is forced to.
69
+ * - `bun test --cwd <dir> <path>`. The paths resolve against `--cwd`, not the
70
+ * tool call's cwd. `--cwd` is a flag and is skipped, so its paths are
71
+ * resolved against the wrong root and may read as absent — a false refusal,
72
+ * which is the direction above, and not one this has seen in the tree.
73
+ * - A path that exists but contains no test bun will collect. Present on
74
+ * disk is the whole reading; bun's own collection rules are not modelled.
75
+ */
76
+ import { existsSync } from "fs";
77
+ import { isAbsolute, resolve } from "path";
78
+
79
+ import { suitePathArgumentsBySegment } from "./test-suite-lock";
80
+
81
+ /**
82
+ * The field the hook protocol reads for a refusal.
83
+ *
84
+ * Declared ONCE and exported, so the refusal has a single mutable site and
85
+ * `test/bun-test-path-guard.test.ts` can remove it and observe the guard
86
+ * stop refusing. A second inlined `'block'` would bypass the mutation and
87
+ * the case would go green having witnessed nothing.
88
+ */
89
+ export const BUN_TEST_PATH_GUARD_DECISION = "block";
90
+
91
+ /**
92
+ * Shell syntax that makes a whole SEGMENT unresolvable.
93
+ *
94
+ * A command substitution spans several whitespace tokens — `$(bun scripts/x.ts)`
95
+ * tokenises to `$(bun` and `scripts/x.ts)` — so the second looks like an
96
+ * ordinary path and resolves to nothing. Judged per segment for that reason,
97
+ * not per argument. This was a live false refusal in the first implementation.
98
+ */
99
+ const UNRESOLVABLE_SEGMENT = /\$\(|`|\$\{/;
100
+
101
+ /** Shell syntax that makes a single ARGUMENT unresolvable. */
102
+ const UNRESOLVABLE_ARGUMENT = /[*?\[\]$~]/;
103
+
104
+ /**
105
+ * A segment whose first command is `cd <target>`, behind any number of
106
+ * opening subshells. `cd /x && …`, `( cd /x && … )` and `( ( cd /x && … ) )`
107
+ * all match.
108
+ *
109
+ * The repetition is not speculative. A single optional `(` lost the root on
110
+ * `( ( cd X && bun test a.test.ts ) )` and refused a correct command — found
111
+ * by a 16-row battery over subshell spellings, which is the only row of the
112
+ * sixteen that was wrong, and not one that would have been hand-written.
113
+ */
114
+ const LEADING_CD = /^\s*(?:\(\s*)*cd\s+(\S+)/;
115
+
116
+ /**
117
+ * Every directory `bun test` might run in: the tool call's cwd, plus every
118
+ * `cd` target the command names. Null when a `cd` target cannot be resolved,
119
+ * because then the set cannot be enumerated and nothing can be said.
120
+ *
121
+ * ## Why a SET of roots and not the one true cwd
122
+ *
123
+ * Raised by the AI review on PR #1562 and it was right in both directions.
124
+ * `splitTopLevel` does not track parenthesis depth, and this project mandates
125
+ * `( cd <dir> && … )` for any command working outside the session's own
126
+ * directory — so the first implementation resolved against the session cwd
127
+ * while bun would run in the cd'd tree. Measured: it REFUSED
128
+ * `( cd <target> && bun test test/real.test.ts )` naming a path that exists
129
+ * exactly where bun would have looked, and ALLOWED a path absent there but
130
+ * present in the session cwd.
131
+ *
132
+ * Modelling subshell scoping properly needs a depth counter, and a depth
133
+ * counter is a detector the next spelling defeats — the second shape in
134
+ * `.claude/rules/checks-must-be-able-to-fail.md`. Refusing only when a path
135
+ * is absent under EVERY candidate root makes the scoping question stop
136
+ * mattering instead of answering it: a typo is absent under all of them, and
137
+ * a correct path exists under at least one.
138
+ *
139
+ * The cost is declared rather than hidden: a path that exists under one root
140
+ * and not under the one bun actually uses is ALLOWED. That is the direction
141
+ * this guard is allowed to be wrong in, it is strictly better than the
142
+ * single-root reading it replaces, and it is not the #1536 shape — a typo'd
143
+ * filename exists nowhere.
144
+ */
145
+ function candidateRoots(command: string, cwd: string): string[] | null {
146
+ const roots = [cwd];
147
+ for (const { segment } of suitePathArgumentsBySegment(command)) {
148
+ const cd = LEADING_CD.exec(segment);
149
+ if (!cd) continue;
150
+ const target = cd[1];
151
+ // `cd $WORKTREE`, `cd "$(git rev-parse …)"`, `cd -`: the set of roots
152
+ // cannot be enumerated, so the command is not judged at all.
153
+ if (UNRESOLVABLE_SEGMENT.test(target) || UNRESOLVABLE_ARGUMENT.test(target) || target === "-") {
154
+ return null;
155
+ }
156
+ roots.push(isAbsolute(target) ? target : resolve(cwd, target));
157
+ }
158
+ return roots;
159
+ }
160
+
161
+ export interface MissingTestPath {
162
+ /** The argument exactly as it was typed. */
163
+ argument: string;
164
+ /** Where it resolved to, so a reader can see which root was searched. */
165
+ resolved: string;
166
+ }
167
+
168
+ export interface BunTestPathRefusal {
169
+ missing: MissingTestPath[];
170
+ message: string;
171
+ }
172
+
173
+ function refusalMessage(missing: MissingTestPath[], roots: string[]): string {
174
+ const names = missing.map((m) => ` ${m.argument} → ${m.resolved}`).join("\n");
175
+ const plural = missing.length === 1 ? "a path that matches" : "paths that match";
176
+ // Every root is named. A refusal naming one directory while bun would have
177
+ // run in another is what made the first implementation's defect invisible.
178
+ const where = roots.length === 1 ? roots[0] : `any of ${roots.join(", ")}`;
179
+ return (
180
+ `This \`bun test\` names ${plural} no file under ${where}:\n${names}\n\n` +
181
+ `Bun treats an unmatched path argument as a NAME FILTER. It exits non-zero only ` +
182
+ `when NOTHING matched; with at least one real path alongside, the run exits 0 and ` +
183
+ `reports a pass total, so the argument above would contribute nothing and nobody ` +
184
+ `could see it from the outside. Measured on bun 1.3.14 (#1544).\n\n` +
185
+ `Check the spelling against the tree. If you want to confirm a run afterwards, the ` +
186
+ `tell is bun's own summary: \`Ran N tests across M files\` — M must equal the number ` +
187
+ `of paths you passed.\n\n` +
188
+ `RUNGATE_BUN_TEST_PATH_GUARD=warn or =off reverses this without a code change.`
189
+ );
190
+ }
191
+
192
+ /**
193
+ * The refusal, or null when every path argument resolves.
194
+ *
195
+ * An unreadable command — absent, or not a string — is NOT refused. Unlike
196
+ * the cd guard, whose false allow costs a peer half a day, this one's false
197
+ * refusal blocks the agent in front of it, and a payload with no command
198
+ * string is a hook-protocol problem rather than evidence of a bad path.
199
+ */
200
+ export function bunTestPathRefusal(command: unknown, cwd: string): BunTestPathRefusal | null {
201
+ if (typeof command !== "string" || command.trim() === "") return null;
202
+
203
+ const roots = candidateRoots(command, cwd);
204
+ // A command naming a `cd` target this cannot resolve is not judged.
205
+ if (roots === null) return null;
206
+
207
+ const missing: MissingTestPath[] = [];
208
+ for (const { segment, paths } of suitePathArgumentsBySegment(command)) {
209
+ if (UNRESOLVABLE_SEGMENT.test(segment)) continue;
210
+ for (const argument of paths) {
211
+ if (UNRESOLVABLE_ARGUMENT.test(argument)) continue;
212
+ if (isAbsolute(argument)) {
213
+ if (!existsSync(argument)) missing.push({ argument, resolved: argument });
214
+ continue;
215
+ }
216
+ // Absent under EVERY root, or it is not missing. See `candidateRoots`.
217
+ const tried = roots.map((root) => resolve(root, argument));
218
+ if (tried.every((p) => !existsSync(p))) {
219
+ missing.push({ argument, resolved: tried.join(", ") });
220
+ }
221
+ }
222
+ }
223
+
224
+ if (missing.length === 0) return null;
225
+ return { missing, message: refusalMessage(missing, roots) };
226
+ }
227
+
228
+ export type BunTestPathGuardMode = "warn" | "block" | "off";
229
+
230
+ export const BUN_TEST_PATH_GUARD_MODE_VAR = "RUNGATE_BUN_TEST_PATH_GUARD";
231
+
232
+ /**
233
+ * `block`. The ladder exists so the decision is a configuration change rather
234
+ * than a code change made under pressure, and the rung is taken here.
235
+ */
236
+ export const BUN_TEST_PATH_GUARD_DEFAULT_MODE: BunTestPathGuardMode = "block";
237
+
238
+ export interface BunTestPathGuardModeReading {
239
+ mode: BunTestPathGuardMode;
240
+ /** The value that was set and not understood. A guard must not turn itself off on a typo. */
241
+ unrecognised?: string;
242
+ }
243
+
244
+ export function bunTestPathGuardMode(
245
+ env: NodeJS.ProcessEnv = process.env,
246
+ ): BunTestPathGuardModeReading {
247
+ const raw = env[BUN_TEST_PATH_GUARD_MODE_VAR];
248
+ if (raw === undefined || raw === "") return { mode: BUN_TEST_PATH_GUARD_DEFAULT_MODE };
249
+ if (raw === "warn" || raw === "block" || raw === "off") return { mode: raw };
250
+ // An unrecognised value falls back to the DEFAULT, not to `off`. A gate
251
+ // that switches itself off on a misspelling is a gate nobody can rely on.
252
+ return { mode: BUN_TEST_PATH_GUARD_DEFAULT_MODE, unrecognised: raw };
253
+ }
@@ -20,14 +20,46 @@
20
20
  * not distributable, and recommended hand-scaffolding a project. Both
21
21
  * readings of the repo were wrong, which is the state a single source fixes.
22
22
  *
23
- * ## The scripts execute on import
23
+ * ## A command script is run as an ENTRY MODULE, not imported
24
24
  *
25
- * None of them guards on `import.meta.main`; each reads `process.argv` at the
26
- * top level. That is why the dispatcher uses a dynamic `import()` and rewrites
27
- * `process.argv` first — the import IS the invocation. Adding an
28
- * `import.meta.main` guard to any of them would silently turn its subcommand
29
- * into a no-op, so `test/cli-contract.test.ts` runs every command for real.
25
+ * This section used to read: "None of them guards on `import.meta.main`
26
+ * … Adding an `import.meta.main` guard to any of them would silently turn its
27
+ * subcommand into a no-op, so `test/cli-contract.test.ts` runs every command
28
+ * for real." The hazard was named exactly. Both mitigations were false.
29
+ *
30
+ * Three scripts acquired the guard — and `import.meta.main` is FALSE for a
31
+ * dynamically imported module, so `await import(script)` loaded them, ran
32
+ * nothing, and exited 0. Measured on `3da782dc`, dispatcher against the same
33
+ * script run directly, in bytes of output:
34
+ *
35
+ * audit-specs 0 vs 2092 silent
36
+ * sync-spec-tests 0 vs 1254 silent
37
+ * extract-constraints 0 vs 57 silent
38
+ * ai-review-findings 270 vs 270 reached — see below
39
+ *
40
+ * Three of ten commands reported success having done nothing. The second
41
+ * mitigation is why nobody saw it: `test/cli-contract.test.ts` ran ONE
42
+ * command for real, `create-sc --list`, and its comment names this defect in
43
+ * as many words. One member of the population was enough to hold the
44
+ * assertion up while the other nine went unmeasured — the battery varied the
45
+ * dispatcher and held the COMMAND fixed, and the defect was on that axis
46
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, seventh shape).
47
+ *
48
+ * `scripts/ai-review-findings.ts` is the one that still worked, and it is the
49
+ * prior art rather than the exception: #675 hit this, documented the
50
+ * mechanism in its docblock, and worked around it by calling `main`
51
+ * unconditionally from a wrapper. That fixed one command and left the
52
+ * dispatcher as it was.
53
+ *
54
+ * So the fix is here, in the one place that decides how a command is invoked,
55
+ * rather than three more wrappers — a per-script workaround is three more
56
+ * places to forget, and the forgetting reads as the command succeeding.
57
+ * `runCommandScript` spawns the script with the running bun binary, which
58
+ * makes it the entry module and `import.meta.main` true, exactly as
59
+ * `bun scripts/audit-specs.ts` already was. A guard is now the normal thing
60
+ * for a script to have, instead of a trap.
30
61
  */
62
+ import { spawnSync } from "child_process";
31
63
 
32
64
  export interface CliCommand {
33
65
  /** The script this runs, relative to the package root. Must be in `files`. */
@@ -111,14 +143,35 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
111
143
  // because a scaffolded consumer has no copy of rungate's sources at a path
112
144
  // the workflow could hardcode. This registry is the path (#675).
113
145
  //
114
- // No `projectRootFlag`: the argument is the findings payload, which lives
115
- // outside the checkout by design (`RUNNER_TEMP`), and appending
116
- // `--project-root <cwd>` would arrive as a second positional and be read as
117
- // a second payload.
146
+ // No `projectRootFlag`: the arguments are the findings payload and the
147
+ // changed-path list, both of which live outside the checkout by design
148
+ // (`RUNNER_TEMP`), and appending `--project-root <cwd>` would arrive as a
149
+ // third positional. That absence is now load-bearing twice over — it is
150
+ // also why the changed-path list may safely BE a positional.
118
151
  "ai-review-findings": {
119
152
  script: "scripts/ai-review-findings.ts",
120
153
  summary: "Adjudicate an AI review's findings payload — exits non-zero on a blocking finding",
121
- usage: "rungate ai-review-findings <path-to-findings.json>",
154
+ // The second positional is the pull request's changed-path list, one path
155
+ // per line (#1204, #1435). It is OPTIONAL: no generated job supplies it
156
+ // yet, and an absent list reports its own state rather than switching a
157
+ // check off in silence.
158
+ usage: "rungate ai-review-findings <path-to-findings.json> [<path-to-changed-files.txt>]",
159
+ },
160
+ // Registered for the same reason `ai-review-findings` is, one workflow
161
+ // over (#1488): the generated `ai-review-unmeasured.yml` runs in a
162
+ // consumer's repository, which has no copy of rungate's sources at any
163
+ // path the workflow could name. This registry is the path.
164
+ //
165
+ // No `projectRootFlag`: every argument is a flag and the script reads no
166
+ // project tree at all — it talks to the GitHub API about a repository it
167
+ // is told the name of, so an appended `--project-root <cwd>` would be
168
+ // refused by `parseArgs` as an unknown argument.
169
+ "record-ai-review-unmeasured": {
170
+ script: "scripts/record-ai-review-unmeasured.ts",
171
+ summary: "Record WHICH kind of unmeasured each unmeasured AI-review round was",
172
+ usage:
173
+ "rungate record-ai-review-unmeasured --repo <owner/name> " +
174
+ "[--head-sha <sha> | --pr <n> | --limit <n>] [--write]",
122
175
  },
123
176
  };
124
177
 
@@ -127,6 +180,65 @@ export function publishedCommands(): string[] {
127
180
  return Object.keys(CLI_COMMANDS);
128
181
  }
129
182
 
183
+ /** What a dispatched command returned, and what it wrote when captured. */
184
+ export interface CommandRun {
185
+ /** The code to exit with. Never `null` — a killed or unspawnable child is non-zero. */
186
+ code: number;
187
+ /** Present only when `capture` was asked for. */
188
+ stdout?: string;
189
+ stderr?: string;
190
+ }
191
+
192
+ /**
193
+ * Run a command's script AS AN ENTRY MODULE, and return the code to exit with.
194
+ *
195
+ * THE single binding for how a subcommand is invoked. The dispatcher calls
196
+ * nothing else, so there is one place to mutate and a test can watch the
197
+ * invocation stop being an entry-module run — see the docblock at the top of
198
+ * this file for the three commands that were silently no-ops when this was
199
+ * `await import(script)`.
200
+ *
201
+ * `process.execPath` rather than the string `"bun"`: the child must be the
202
+ * same runtime the parent is already running under, and a consumer's PATH is
203
+ * not ours to assume.
204
+ *
205
+ * ## Every way this can fail to run is non-zero
206
+ *
207
+ * `spawnSync` reports `status: null` for a child that never produced an exit
208
+ * code — killed by a signal, or never spawned at all. Mapping that to 0 would
209
+ * reinstate the defect this function exists to remove, one layer out: a
210
+ * command that did not run, reporting success.
211
+ *
212
+ * ONE `??`, not a `signal` branch beside it. The first version had both, and
213
+ * the separate branch made `?? 1` unreachable — no input could distinguish it
214
+ * from `?? 0`, so the case asserting "a script that cannot run is a failure"
215
+ * passed under that mutation. It was green because a missing script makes
216
+ * *bun* exit non-zero, which is a real status the `??` never sees
217
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, third shape: an assertion
218
+ * holding for a reason that is not the one claimed). Collapsed to one path,
219
+ * a SIGKILLed child reaches it and the mutation is caught.
220
+ */
221
+ export function runCommandScript(
222
+ script: string,
223
+ args: string[],
224
+ opts?: { capture?: boolean },
225
+ ): CommandRun {
226
+ const r = spawnSync(process.execPath, [script, ...args], {
227
+ stdio: opts?.capture ? "pipe" : "inherit",
228
+ encoding: "utf-8",
229
+ });
230
+ const captured = opts?.capture ? { stdout: r.stdout ?? "", stderr: r.stderr ?? "" } : {};
231
+ // A spawn error is not a verdict the script reached. Say so on stderr —
232
+ // under `stdio: "inherit"` the child wrote nothing and a bare exit code
233
+ // would be the silent failure again, one layer out.
234
+ if (r.error) {
235
+ const why = `rungate: could not run ${script}: ${r.error.message}`;
236
+ if (!opts?.capture) console.error(why);
237
+ return { code: 1, ...captured, ...(opts?.capture ? { stderr: why } : {}) };
238
+ }
239
+ return { code: r.status ?? 1, ...captured };
240
+ }
241
+
130
242
  export function helpText(): string {
131
243
  const rows = Object.entries(CLI_COMMANDS).map(
132
244
  ([name, c]) => ` ${name.padEnd(20)}${c.summary}\n ${" ".repeat(20)}${c.usage}`,
@@ -143,6 +255,135 @@ export function helpText(): string {
143
255
  ].join("\n");
144
256
  }
145
257
 
258
+ /**
259
+ * The routing table for `.claude/rules/commands-routing.md`, generated.
260
+ *
261
+ * #1309 in one function. The scaffold routed specs, docs, key files and
262
+ * managed files and did not route COMMANDS, so a command reached an agent
263
+ * only if somebody had hand-written a row for it in `AGENTS.md`'s Commands
264
+ * table — four of ten, and the four were the four somebody happened to need
265
+ * in 2026-09. Measured over the always-loaded surface on `11a60f67`, seven of
266
+ * the ten were named in no file an agent loads, including `audit-specs`,
267
+ * whose whole job is reporting spec status. An agent spent a day
268
+ * hand-building a tracking mechanism that was already a subcommand.
269
+ *
270
+ * Generated from `CLI_COMMANDS` rather than written, because a hand-list is
271
+ * precisely what failed: the generated table is present and plausible, reads
272
+ * as complete, and nothing in it signals that six more commands exist.
273
+ *
274
+ * ## No usage strings here, deliberately
275
+ *
276
+ * `helpText()` carries them and `--help` prints them. This table is the
277
+ * always-loaded surface, which is at 93% of `SURFACE_BUDGET_BYTES` — adding
278
+ * ten usage lines would cost ~600 bytes to save one `--help`, and the thing
279
+ * an agent cannot discover by running a command is that the command EXISTS.
280
+ * The summary is what makes `audit-specs` findable by someone thinking "which
281
+ * criteria are covered"; the arguments are one invocation away.
282
+ */
283
+ export function commandRoutingTable(): string {
284
+ const rows = Object.entries(CLI_COMMANDS).map(
285
+ ([name, c]) => `| \`${name}\` | ${c.summary} |`,
286
+ );
287
+ return ["| Command | What it does |", "|---------|--------------|", ...rows].join("\n");
288
+ }
289
+
290
+ /**
291
+ * Every code span in a markdown document — fenced blocks and inline spans.
292
+ *
293
+ * `commandNamed` searches this slice rather than the whole document, and the
294
+ * slice is the point: `.claude/rules/harness-managed.md` says "a re-scaffold
295
+ * rewrites them" and `AGENTS.md` says "Re-scaffold", and neither of those
296
+ * routes anyone to the `scaffold` command. A command name is a thing you
297
+ * TYPE, so the region where it counts is the region reserved for things you
298
+ * type (`.claude/rules/checks-must-be-able-to-fail.md`, "search the slice,
299
+ * not the document").
300
+ */
301
+ export function codeSpans(markdown: string): string {
302
+ const fenced = markdown.match(/```[\s\S]*?```/g) ?? [];
303
+ const withoutFences = markdown.replace(/```[\s\S]*?```/g, "\n");
304
+ const inline = withoutFences.match(/`[^`\n]+`/g) ?? [];
305
+ return [...fenced, ...inline].join("\n");
306
+ }
307
+
308
+ /**
309
+ * Is `name` typed, as a whole word, anywhere in this document's code spans?
310
+ *
311
+ * `.` is in the boundary class alongside `-` so that `scripts/convert-spec.ts`
312
+ * does not count as routing the `convert-spec` COMMAND. It is the script the
313
+ * command runs, named in the form a consumer cannot use, and treating a path
314
+ * as a routing is how `convert-spec` read as present while `bunx rungate
315
+ * convert-spec` was documented nowhere.
316
+ *
317
+ * The direction this is allowed to be wrong in is toward reporting a command
318
+ * UNROUTED: a routing form nobody thought of costs one generated row, and the
319
+ * other direction is a command that reads as discoverable and is not — which
320
+ * is the whole of #1309.
321
+ */
322
+ export function commandNamed(markdown: string, name: string): boolean {
323
+ const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
324
+ return new RegExp(`(?<![a-z0-9.-])${escaped}(?![a-z0-9.-])`).test(codeSpans(markdown));
325
+ }
326
+
327
+ /** One always-loaded document, as `measureSurface` reports the population. */
328
+ export interface SurfaceDoc {
329
+ file: string;
330
+ text: string;
331
+ }
332
+
333
+ export interface CommandRoutingReading {
334
+ /** UNMEASURED FAILS. An empty search is not a clean one. */
335
+ reading: "MEASURED" | "UNMEASURED";
336
+ unmeasuredReasons: string[];
337
+ /** Registered commands named nowhere in the surface. */
338
+ unrouted: string[];
339
+ filesSearched: number;
340
+ /** Bytes of code span searched. Zero is the instrument, not the answer. */
341
+ spanBytes: number;
342
+ }
343
+
344
+ /**
345
+ * Which registered commands are named nowhere an agent loads.
346
+ *
347
+ * Takes the surface as an argument rather than deriving it, because the
348
+ * population of always-loaded files is already decided once, by
349
+ * `measureSurface` in `scripts/check-instruction-surface.ts`. A second
350
+ * definition here would be two deciders that agree, and the one that matters
351
+ * — whether a `paths:` key has quietly moved a rule out of the launch surface
352
+ * — would be invisible to a check that had its own idea of what loads.
353
+ *
354
+ * The three UNMEASURED states are all ways this returns `[]` while having
355
+ * searched nothing: no documents, no code spans in any of them, or an empty
356
+ * registry. Each of them reads exactly like a tree where every command is
357
+ * routed (`.claude/rules/config-access.md`).
358
+ */
359
+ export function commandRoutingReading(surface: SurfaceDoc[]): CommandRoutingReading {
360
+ const reasons: string[] = [];
361
+ const spans = surface.map(d => codeSpans(d.text)).join("\n");
362
+ const spanBytes = Buffer.byteLength(spans, "utf-8");
363
+ const names = publishedCommands();
364
+
365
+ if (surface.length === 0) {
366
+ reasons.push("the always-loaded surface came back empty — no documents were searched");
367
+ }
368
+ if (spanBytes === 0) {
369
+ reasons.push(
370
+ `${surface.length} document(s) yielded no code spans at all; a command name is only ` +
371
+ `counted inside one, so every command would read as unrouted for an instrument reason`,
372
+ );
373
+ }
374
+ if (names.length === 0) {
375
+ reasons.push("CLI_COMMANDS is empty — nothing to route, which is not the same as routed");
376
+ }
377
+
378
+ return {
379
+ reading: reasons.length > 0 ? "UNMEASURED" : "MEASURED",
380
+ unmeasuredReasons: reasons,
381
+ unrouted: names.filter(n => !surface.some(d => commandNamed(d.text, n))),
382
+ filesSearched: surface.length,
383
+ spanBytes,
384
+ };
385
+ }
386
+
146
387
  /**
147
388
  * Every `bunx <pkg> <cmd>` invocation in a markdown command table.
148
389
  *