rungate 0.2.1 → 0.4.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 (129) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
@@ -0,0 +1,343 @@
1
+ /**
2
+ * Whether a `gh issue create` may run during VERIFY, and why not (#365).
3
+ *
4
+ * `hooks/VerifyPhaseLock.hook.ts` asked the question in eight lines:
5
+ *
6
+ * if (cmd.includes('--label') && cmd.includes('follow-up')) process.exit(0);
7
+ *
8
+ * That is not a test that a label argument equals `follow-up`. It is a test
9
+ * that the string `follow-up` appears SOMEWHERE in the command, so
10
+ *
11
+ * gh issue create --label bug --title "Fix the follow-up handler"
12
+ *
13
+ * bypasses the lock entirely while applying no override label at all. A
14
+ * detector whose input is the whole command string cannot tell an argument
15
+ * from a word in a title — shape two of
16
+ * `.claude/rules/checks-must-be-able-to-fail.md`, pointed outward: the guard
17
+ * is wider than the thing it guards.
18
+ *
19
+ * The same shape hid a second bypass one line down. `cmd.includes('gh issue
20
+ * comment')` is unreachable for a plain comment, because the create check
21
+ * above it has already exited — but it IS reachable for
22
+ * `gh issue comment … && gh issue create …`, where the comment clause
23
+ * exempts the create clause.
24
+ *
25
+ * ## The second defect is about the tracker, not the hook
26
+ *
27
+ * `follow-up` means "follow-up work from a shipped issue", and it was the
28
+ * only override, so anything filed during VERIFY had to claim an origin it
29
+ * did not have. On 2026-10-13 an external audit of two consumer projects
30
+ * surfaced three consumer-blocking defects here; #362, #363 and #364 all
31
+ * wear `follow-up` and not one of them is follow-up work from a shipped
32
+ * issue. An agent filtering that label to find loose ends from recent ships
33
+ * gets three unrelated results. `external-audit` exists for exactly that
34
+ * origin and is accepted here.
35
+ *
36
+ * ## What this is, and what it is not
37
+ *
38
+ * Stated because two rounds of commit security review walked the parser
39
+ * inward and a third would too. **This is workflow discipline over `gh`
40
+ * invocations reaching PreToolUse on Bash. It is not a sandbox.** It exists
41
+ * to catch a reflex — an agent mid-VERIFY reaching for `gh issue create`
42
+ * when `verifyBlockers[]` is the right place — and a reflex is defeated by
43
+ * saying no to the command shapes someone actually types.
44
+ *
45
+ * So the parser is held to ordinary shapes: operators with or without
46
+ * surrounding whitespace, newlines, subshells, command substitution
47
+ * including backticks, a path-qualified binary, quoted arguments, trailing
48
+ * `#` comments, backslash line continuations, and `-c` / `-lc` / `eval`
49
+ * wrappers. **Every one of those was a measured bypass of an earlier version
50
+ * of this file**, and each has a row in `test/verify-phase-lock.test.ts`.
51
+ *
52
+ * Out of scope ON PURPOSE, and not a gap to file:
53
+ *
54
+ * - `curl` against the REST API, or the GitHub MCP tools — neither is Bash,
55
+ * so the hook never sees them.
56
+ * - `ssh host "gh issue create …"` — that runs on another machine against
57
+ * whatever repo it is configured for, and descending into every remote
58
+ * command mentioning `gh` buys false refusals, not safety.
59
+ * - Variable indirection — `GH=gh; $GH issue create`. Resolving it means
60
+ * tracking assignments across clauses, which is the shell interpreter this
61
+ * file is explicitly not, and nobody reaches for `$GH` by reflex.
62
+ * - Here-strings and here-documents — `bash <<< "gh issue create …"`. Same
63
+ * reason: a deliberate construction, not a reflex.
64
+ * - A caller who writes a script and runs it.
65
+ *
66
+ * Each of those takes a decision to get around the lock, and an agent that
67
+ * has made that decision is a problem no matcher fixes. Chasing them trades
68
+ * false refusals — which teach people to work around a guard — for
69
+ * protection against someone already doing so.
70
+ */
71
+
72
+ /** Labels that permit an issue to be filed mid-VERIFY, and what each means. */
73
+ export const OVERRIDE_LABELS: Record<string, string> = {
74
+ "follow-up": "follow-up work from a shipped issue",
75
+ "external-audit": "a defect found outside the ship loop",
76
+ };
77
+
78
+ /**
79
+ * Shell operators that end one command and begin another.
80
+ *
81
+ * Emitted as their OWN tokens, which is the whole point. The first version
82
+ * of this file split on whitespace alone, so `foo;gh issue create` and
83
+ * `gh issue comment 1&&gh issue create` produced the tokens `foo;gh` and
84
+ * `1&&gh` — and since those are not the word `gh`, `createsIssue` said no
85
+ * and the lock allowed both. That is the same defect as the substring
86
+ * matcher this file replaced, one layer in: a parser that disagrees with the
87
+ * shell about where a command begins. Found by the commit security review,
88
+ * not by me.
89
+ *
90
+ * A newline is in the list for the same reason. Without it,
91
+ * `gh issue create --label follow-up` and `gh issue create --label bug` on
92
+ * two lines are one clause, and the first line's override covers the second.
93
+ *
94
+ * Backticks are here for the same reason `(` and `)` are: they delimit a
95
+ * command substitution, and without them `` `gh issue create` `` yields the
96
+ * token `` `gh `` rather than `gh`.
97
+ *
98
+ * Longest first: `&&` must be tried before `&`, `||` before `|`.
99
+ */
100
+ const OPERATORS = ["&&", "||", ";;", ";", "|", "&", "(", ")", "`", "\n"];
101
+
102
+ /**
103
+ * Split a command the way a shell would, so an argument can be told from a
104
+ * word inside a quoted string — and an operator from a word glued to one.
105
+ *
106
+ * Not a full shell parser and does not need to be: the only question is
107
+ * where one command ends and the next begins, and which tokens are its
108
+ * arguments. Unterminated quotes yield the rest of the string as one token,
109
+ * which keeps a malformed command from splitting into things that look like
110
+ * flags nobody wrote.
111
+ */
112
+ export function tokenize(cmd: string): string[] {
113
+ const out: string[] = [];
114
+ let cur = "";
115
+ let quote: '"' | "'" | null = null;
116
+ let started = false;
117
+ const flush = () => {
118
+ if (started) out.push(cur);
119
+ cur = "";
120
+ started = false;
121
+ };
122
+ for (let i = 0; i < cmd.length; i++) {
123
+ const c = cmd[i];
124
+ if (c === "\\" && quote !== "'" && i + 1 < cmd.length) {
125
+ // A backslash-newline is a line continuation: it joins, and adds
126
+ // nothing. Treating it as an escaped character put a literal newline
127
+ // inside the token, so `gh issue \⏎ create` produced `\ncreate` and
128
+ // the lock allowed it — and wrapping a long command across lines is
129
+ // something people do on purpose.
130
+ if (cmd[i + 1] === "\n") {
131
+ i++;
132
+ continue;
133
+ }
134
+ cur += cmd[++i];
135
+ started = true;
136
+ continue;
137
+ }
138
+ // `#` starts a comment only at the start of a word, which is the shell's
139
+ // own rule. Without it, `--label bug # --label follow-up` read the
140
+ // commented-out override as a real one.
141
+ if (!quote && !started && c === "#") {
142
+ while (i < cmd.length && cmd[i] !== "\n") i++;
143
+ i--;
144
+ continue;
145
+ }
146
+ if (quote) {
147
+ if (c === quote) quote = null;
148
+ else cur += c;
149
+ continue;
150
+ }
151
+ if (c === '"' || c === "'") {
152
+ quote = c;
153
+ started = true;
154
+ continue;
155
+ }
156
+ const op = OPERATORS.find(o => cmd.startsWith(o, i));
157
+ if (op) {
158
+ flush();
159
+ out.push(op);
160
+ i += op.length - 1;
161
+ continue;
162
+ }
163
+ if (/\s/.test(c)) {
164
+ flush();
165
+ continue;
166
+ }
167
+ cur += c;
168
+ started = true;
169
+ }
170
+ flush();
171
+ return out;
172
+ }
173
+
174
+ const SEPARATORS = new Set(OPERATORS);
175
+
176
+ /**
177
+ * The command list, one token array per clause, descending into `-c`.
178
+ *
179
+ * The recursion is why `echo 'gh issue create --label bug'` stays allowed
180
+ * while `bash -c 'gh issue create --label bug'` does not. A quoted string is
181
+ * data to `echo` and a command to a shell, and only the second one files an
182
+ * issue. Refusing both would be the safer direction and the wrong one — a
183
+ * guard that refuses commands which create nothing is a guard people learn
184
+ * to work around.
185
+ *
186
+ * **There is deliberately no allowlist of shell names here.** The first
187
+ * version had one — `sh`, `bash`, `zsh`, `dash`, `ksh`, `fish`, with the
188
+ * program name resolved past any `VAR=value` prefix — and removing it
189
+ * scored **0 red of 38**. No command could be written that the allowlist
190
+ * decided: a non-shell interpreter's `-c` argument is source code, and
191
+ * source code quotes the command it runs, so the inner text arrives as one
192
+ * token and `createsIssue` needs three adjacent ones. `python3 -c
193
+ * "print('gh issue create --label bug')"` is a table case and is allowed
194
+ * with or without the allowlist. A branch no input can distinguish is a
195
+ * branch that will be wrong silently, so it is gone rather than kept for
196
+ * reassurance.
197
+ */
198
+ export function clauses(cmd: string, depth = 0): string[][] {
199
+ const flat: string[][] = [[]];
200
+ for (const t of tokenize(cmd)) {
201
+ if (SEPARATORS.has(t)) flat.push([]);
202
+ else flat[flat.length - 1].push(t);
203
+ }
204
+
205
+ const out: string[][] = [];
206
+ for (const c of flat) {
207
+ if (c.length === 0) continue;
208
+ out.push(c);
209
+ if (depth >= 4) continue; // a wrapper chain this deep is not an accident
210
+ for (const inner of commandArguments(c)) out.push(...clauses(inner, depth + 1));
211
+ }
212
+ return out;
213
+ }
214
+
215
+ /** Arguments of this clause that are themselves commands. */
216
+ function commandArguments(tokens: string[]): string[] {
217
+ const out: string[] = [];
218
+ for (let i = 0; i < tokens.length; i++) {
219
+ const t = tokens[i];
220
+ if (COMMAND_FLAG.test(t) || basename(t) === "eval") {
221
+ if (i + 1 < tokens.length) out.push(tokens[i + 1]);
222
+ }
223
+ }
224
+ return out;
225
+ }
226
+
227
+ /** The program a token names, ignoring any path it was reached by. */
228
+ const basename = (t: string) => t.split("/").pop()!;
229
+
230
+ /**
231
+ * Does this clause invoke `gh issue create`?
232
+ *
233
+ * Compared on the basename, because `/usr/bin/gh issue create` and
234
+ * `./gh issue create` are the same command and the first version of this
235
+ * function allowed both.
236
+ */
237
+ export function createsIssue(tokens: string[]): boolean {
238
+ for (let i = 0; i + 2 < tokens.length; i++) {
239
+ if (basename(tokens[i]) === "gh" && tokens[i + 1] === "issue" && tokens[i + 2] === "create") {
240
+ return true;
241
+ }
242
+ }
243
+ return false;
244
+ }
245
+
246
+ /**
247
+ * Flags whose next argument is a command string rather than data.
248
+ *
249
+ * `-c`, but also `-lc` and `-ic`: short flags combine, and only the last
250
+ * letter takes the argument, so `sh -lc "…"` is a login shell running a
251
+ * command. Both of those were allowed until the second security review.
252
+ */
253
+ const COMMAND_FLAG = /^-[A-Za-z]*c$/;
254
+
255
+ /**
256
+ * Flags of `gh issue create` that do NOT consume the following token.
257
+ *
258
+ * Everything else that looks like a flag is assumed to take a value, which
259
+ * is the conservative direction here — see `labelValues`.
260
+ */
261
+ const BOOLEAN_FLAGS = new Set(["-w", "--web", "-h", "--help", "--recover-only"]);
262
+
263
+ /**
264
+ * The values passed to `--label` / `-l`, in both the spaced and `=` forms.
265
+ *
266
+ * `gh` accepts a comma-separated list in one flag, so `--label a,b` is two
267
+ * labels and not one named `a,b`.
268
+ *
269
+ * **A token that is another flag's value is data, not a flag.** Scanning for
270
+ * `--label=` anywhere in the clause reintroduced #365 exactly — the defect
271
+ * this whole file exists to fix — through the back door:
272
+ *
273
+ * gh issue create --label bug --title "--label=follow-up"
274
+ *
275
+ * `gh` gives that title to the issue and applies only `bug`; the old scan
276
+ * read the title as an override and allowed it. Found by the third round of
277
+ * commit security review, and it is the same bypass as the original with one
278
+ * more layer of quoting. The unquoted form is the same command — the shell
279
+ * strips the quotes either way, so the quoting is not what makes it work.
280
+ *
281
+ * So the walk tracks arity the way `gh`'s own flag parser does: a flag
282
+ * consumes the next token unless it is known to be boolean. An unknown flag
283
+ * is assumed to take a value, which can only ever cause a `--label` to be
284
+ * MISSED — and a missed label is a refusal, the direction this guard is
285
+ * allowed to be wrong in.
286
+ */
287
+ export function labelValues(tokens: string[]): string[] {
288
+ const out: string[] = [];
289
+ const add = (v: string) => {
290
+ for (const part of v.split(",")) {
291
+ const t = part.trim();
292
+ if (t) out.push(t);
293
+ }
294
+ };
295
+ for (let i = 0; i < tokens.length; i++) {
296
+ const t = tokens[i];
297
+ if (!t.startsWith("-") || t === "-" || t === "--") continue;
298
+
299
+ const eq = t.indexOf("=");
300
+ if (eq !== -1) {
301
+ const name = t.slice(0, eq);
302
+ if (name === "--label" || name === "-l") add(t.slice(eq + 1));
303
+ continue; // `--flag=value` carries its own value; it consumes nothing
304
+ }
305
+ if (t === "--label" || t === "-l") {
306
+ if (i + 1 < tokens.length) add(tokens[++i]);
307
+ continue;
308
+ }
309
+ // `-lfollow-up` — pflag lets a short flag carry its value attached.
310
+ if (/^-l[^-=]/.test(t)) {
311
+ add(t.slice(2));
312
+ continue;
313
+ }
314
+ if (!BOOLEAN_FLAGS.has(t)) i++; // this flag eats the next token
315
+ }
316
+ return out;
317
+ }
318
+
319
+ /**
320
+ * The single place that decides. `null` means allow.
321
+ *
322
+ * One exported function so there is one binding to mutate. Asked per clause
323
+ * rather than per command: a command that comments on an issue AND creates
324
+ * one is a create, and the old substring form let the first half excuse the
325
+ * second.
326
+ */
327
+ export function verifyPhaseRefusal(cmd: string): string | null {
328
+ const offending = clauses(cmd).filter(createsIssue);
329
+ if (offending.length === 0) return null;
330
+
331
+ const names = Object.keys(OVERRIDE_LABELS);
332
+ const allowed = offending.every(c => labelValues(c).some(l => names.includes(l)));
333
+ if (allowed) return null;
334
+
335
+ return (
336
+ "[VerifyPhaseLock] During VERIFY phase, use verifyBlockers[] in " +
337
+ "workflow-state.json instead of creating new issues. To override, apply a " +
338
+ "label that states where the issue came from: " +
339
+ names.map(n => `--label ${n} (${OVERRIDE_LABELS[n]})`).join(", ") +
340
+ ". The label must be a real --label argument; a matching word in the title " +
341
+ "is not an override."
342
+ );
343
+ }