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
@@ -0,0 +1,433 @@
1
+ /**
2
+ * Does the reviewer's PROMPT agree with the tools the job grants it? (#732)
3
+ *
4
+ * `.github/workflows/claude-review.yml` concluded **success** twice having
5
+ * posted nothing. The issue blames the `SlashCommand` entry on the denylist.
6
+ * That is measured to be wrong — a slash command supplied as the CLI PROMPT is
7
+ * expanded before the model sees it, and `claude -p "/canary" --disallowedTools
8
+ * "SlashCommand,…"` returns the command's output with `permission_denials: []`.
9
+ * Deleting that word would have changed nothing.
10
+ *
11
+ * What was actually blocking it is four independent facts, none of which the
12
+ * issue body names, and every one of which this module reports by its own name:
13
+ *
14
+ * 1. **`Task`.** `/code-review:code-review` says "Use a Haiku agent…", "launch
15
+ * 5 parallel Sonnet agents…" six times, including the step-1 gate whose
16
+ * negative branch says "do not proceed". `Task` is on the denylist, so an
17
+ * agent that cannot run step 1 stops having done nothing.
18
+ * 2. **`Bash`.** Every tool that command's frontmatter declares is `Bash(gh …)`,
19
+ * and its step 6 is "use the gh bash command to comment back". Also denied.
20
+ * 3. **The posting path does not match the allowlist.** The string
21
+ * `create_inline_comment` does not appear in that command at all.
22
+ * 4. **The allowed tool does not exist on this trigger.** Read from the pinned
23
+ * action at the SHA `lib/claude-code-action.ts` declares,
24
+ * `src/mcp/install-mcp-server.ts:152` — the `github_inline_comment` MCP
25
+ * server is installed only when `isEntityContext(context) && context.isPR`,
26
+ * and `src/github/context.ts:54` lists `workflow_dispatch` under
27
+ * `AUTOMATION_EVENT_NAMES`, not `ENTITY_EVENT_NAMES`. This workflow's only
28
+ * trigger is `workflow_dispatch`. So
29
+ * `mcp__github_inline_comment__create_inline_comment` — the single entry on
30
+ * the allowlist, the tool the job exists to call — **cannot exist in any run
31
+ * of it.** A fully working prompt would still have posted nothing.
32
+ *
33
+ * The fourth is the one no amount of reading the prompt finds, and it is why
34
+ * this module takes the TRIGGERS as well as the two tool lists. A grant whose
35
+ * server never starts is indistinguishable from a grant that was never used.
36
+ *
37
+ * ## Why one exported binding and not a file of assertions
38
+ *
39
+ * `.claude/rules/checks-must-be-able-to-fail.md`: one decider, one thing to
40
+ * mutate. Every violation below is reachable from `reviewToolAgreement`, so a
41
+ * mutation of it is visible to every case, and there is no second place that
42
+ * decides what counts.
43
+ *
44
+ * ## Scope, stated rather than implied
45
+ *
46
+ * No YAML parser. This repo ships four runtime dependencies and a guard is not
47
+ * a reason to add a fifth to a published package — the same decision
48
+ * `test/claude-review-no-key.test.ts` records. Everything here is a cut and a
49
+ * regex over the cut, and every cut refuses by name when it cannot find its
50
+ * region, because a slice that missed its section is an empty string and an
51
+ * empty string satisfies every claim of the form "X is not in here".
52
+ */
53
+
54
+ import { structuralCut } from "./source-slice";
55
+
56
+ /** The names this module reports. One per independent door. */
57
+ export type ReviewToolViolationKind =
58
+ | "PROMPT_IS_A_SLASH_COMMAND"
59
+ | "PROMPT_NAMES_NO_TOOL"
60
+ | "PROMPT_NAMES_A_DENIED_TOOL"
61
+ | "PROMPT_NAMES_AN_UNGRANTED_TOOL"
62
+ | "ALLOWED_TOOL_CANNOT_EXIST_ON_THIS_TRIGGER"
63
+ | "NO_POSTING_TOOL_IS_ALLOWED"
64
+ | "NO_SUBJECT_REACHES_THE_AGENT"
65
+ | "MUTABLE_PLUGIN_MARKETPLACE"
66
+ | "NO_STEP_READS_THE_EXECUTION_OUTPUT";
67
+
68
+ export type ReviewToolViolation = {
69
+ kind: ReviewToolViolationKind;
70
+ detail: string;
71
+ };
72
+
73
+ /**
74
+ * MCP servers the pinned action installs only under an ENTITY event, keyed by
75
+ * the server segment of a tool name. Read from `install-mcp-server.ts` at the
76
+ * pinned SHA; the value is the condition's own words so a reader can go and
77
+ * check it rather than trust this table.
78
+ *
79
+ * A total record rather than a list of strings, so adding a server is a typed
80
+ * edit at one site and the reason travels with the name.
81
+ */
82
+ export const ENTITY_ONLY_MCP_SERVERS: Record<string, string> = {
83
+ github_inline_comment:
84
+ "install-mcp-server.ts:152 — `isEntityContext(context) && context.isPR && (hasGitHubMcpTools || hasInlineCommentTools)`",
85
+ github_ci:
86
+ "install-mcp-server.ts:177 — `(!isAgentMode || hasGitHubCITools) && isEntityContext(context) && context.isPR && hasWorkflowToken`",
87
+ github_comment:
88
+ "github-comment-server.ts:43 — `update_claude_comment` throws without CLAUDE_COMMENT_ID, which only tag mode sets",
89
+ };
90
+
91
+ /**
92
+ * Events the pinned action treats as AUTOMATION rather than ENTITY —
93
+ * `src/github/context.ts:63` `AUTOMATION_EVENT_NAMES`. A workflow triggered
94
+ * only by these can never satisfy `isEntityContext`.
95
+ */
96
+ export const AUTOMATION_ONLY_TRIGGERS = [
97
+ "workflow_dispatch",
98
+ "repository_dispatch",
99
+ "schedule",
100
+ "workflow_run",
101
+ ] as const;
102
+
103
+ /**
104
+ * Tools that can put a human-readable finding on a pull request. The property
105
+ * AC-4 needs is "a comment naming the defect appears", so this is the set the
106
+ * allowlist must intersect — enumerated, because a server-wide grant beside
107
+ * `pull-requests: write` is the HIGH finding recorded on #732 and widening to
108
+ * `mcp__github` would satisfy a looser check while reintroducing it.
109
+ */
110
+ export const POSTING_TOOLS = [
111
+ "mcp__github__create_pending_pull_request_review",
112
+ "mcp__github__add_comment_to_pending_review",
113
+ "mcp__github__submit_pending_pull_request_review",
114
+ "mcp__github__create_and_submit_pull_request_review",
115
+ "mcp__github__add_issue_comment",
116
+ "mcp__github_inline_comment__create_inline_comment",
117
+ ] as const;
118
+
119
+ /**
120
+ * Tools that let the agent go and FETCH the thing under review. If none is
121
+ * granted, the diff has to arrive in the prompt or the agent is reviewing
122
+ * nothing — which is `NO_SUBJECT_REACHES_THE_AGENT`.
123
+ */
124
+ export const SUBJECT_FETCHING_TOOLS = [
125
+ "Read",
126
+ "Grep",
127
+ "Glob",
128
+ "Bash",
129
+ "WebFetch",
130
+ "mcp__github__get_pull_request_diff",
131
+ "mcp__github__get_pull_request_files",
132
+ "mcp__github__get_file_contents",
133
+ ] as const;
134
+
135
+ /**
136
+ * The step-output name through which the code under review reaches the agent
137
+ * when no fetching tool is granted. A convention, declared here so there is
138
+ * one binding and the rule can say what it is looking for rather than guessing
139
+ * from the shape of an interpolation — `${{ steps.guard.outputs.pr }}` is a
140
+ * step output too, and a PR NUMBER is not the code. That near-miss is the
141
+ * whole reason this is a named output and not "any interpolation".
142
+ *
143
+ * Narrow on purpose, and in the safe direction: an unconventional name costs a
144
+ * refusal somebody fixes by renaming an output. The other direction credits a
145
+ * reviewer that cannot see the diff, which is #732.
146
+ */
147
+ export const SUBJECT_OUTPUT_NAME = "diff";
148
+
149
+ /** The script whose presence in a step makes that step the reading. */
150
+ export const READING_SCRIPT = "scripts/read-review-execution.ts";
151
+
152
+ export class ReviewSourceUnreadableError extends Error {}
153
+
154
+ /**
155
+ * Every step of the job, as its own string: a `- ` list marker under `steps:`
156
+ * and every line up to the next one.
157
+ *
158
+ * **A comment above a `- ` marker lands in the PRECEDING step, and that is
159
+ * deliberate rather than overlooked.** An earlier draft reattached each
160
+ * trailing comment block to the step it introduces, which reads better and
161
+ * which this file's first measurement showed to be dead: with
162
+ * `withoutComments` below standing between every claim and the prose,
163
+ * restoring the misattribution is **0 of 31 red**, measured. Two deciders
164
+ * answering one question are behaviourally one
165
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape), so the
166
+ * cleverer one is gone and `withoutComments` is the single binding.
167
+ *
168
+ * What the misattribution broke before `withoutComments` existed is worth
169
+ * recording, because it is the reason that function is not ceremony: the
170
+ * `setup-bun` step's comment names `READING_SCRIPT` in prose, so a raw-text
171
+ * `filter` returned **two** reading steps for a file with one.
172
+ */
173
+ export function jobSteps(source: string): string[] {
174
+ const lines = source.split("\n");
175
+ const start = lines.findIndex(l => l.trimStart() === "steps:");
176
+ if (start === -1) throw new ReviewSourceUnreadableError("the job declares no steps:");
177
+ const indentOf = (l: string) => l.length - l.trimStart().length;
178
+ const base = indentOf(lines[start]);
179
+ const steps: string[][] = [];
180
+ for (let i = start + 1; i < lines.length; i++) {
181
+ const line = lines[i];
182
+ if (line.trim() !== "" && indentOf(line) <= base) break;
183
+ if (/^\s*- /.test(line)) steps.push([]);
184
+ if (steps.length > 0) steps[steps.length - 1].push(line);
185
+ }
186
+ return steps.map(s => s.join("\n"));
187
+ }
188
+
189
+ /**
190
+ * A step with its comments removed.
191
+ *
192
+ * A claim about a step's CONFIGURATION must not be satisfiable by a sentence
193
+ * ABOUT that configuration. `lib/review-tool-agreement.ts`'s own first draft
194
+ * asked `/execution_file/.test(source)` of the whole file and was satisfied by
195
+ * a comment in a different step — found by the reviewer this module exists to
196
+ * repair, posted as an inline comment on PR #746.
197
+ */
198
+ export function withoutComments(step: string): string {
199
+ return step
200
+ .split("\n")
201
+ .filter(l => !l.trimStart().startsWith("#"))
202
+ .join("\n");
203
+ }
204
+
205
+ /**
206
+ * The YAML block an anchor line opens: that line, plus every following line
207
+ * indented deeper than it, stopping at the first line indented the same or
208
+ * less. No length parameter anywhere (#664) — the region ends where the block
209
+ * ends, which is the only boundary that cannot decay as the file grows.
210
+ *
211
+ * Refuses on zero or two occurrences of the anchor, for `lib/source-slice.ts`'s
212
+ * reason: not-found and found-twice are both refusals, and a confident answer
213
+ * about the wrong region is worse than no answer.
214
+ */
215
+ export function blockUnder(source: string, anchor: string): string {
216
+ const lines = source.split("\n");
217
+ const hits = lines.map((l, i) => [l, i] as const).filter(([l]) => l.trimStart().startsWith(anchor));
218
+ if (hits.length !== 1) {
219
+ throw new ReviewSourceUnreadableError(
220
+ `the anchor ${JSON.stringify(anchor)} opens ${hits.length} lines, not one`,
221
+ );
222
+ }
223
+ const start = hits[0][1];
224
+ const indentOf = (l: string) => l.length - l.trimStart().length;
225
+ const base = indentOf(lines[start]);
226
+ const body = [lines[start]];
227
+ for (let i = start + 1; i < lines.length; i++) {
228
+ if (lines[i].trim() !== "" && indentOf(lines[i]) <= base) break;
229
+ body.push(lines[i]);
230
+ }
231
+ return body.join("\n");
232
+ }
233
+
234
+ /** Every `mcp__server__tool` token in a string, de-duplicated, in order. */
235
+ export function mcpToolsNamedIn(text: string): string[] {
236
+ const seen = new Set<string>();
237
+ for (const m of text.matchAll(/mcp__[a-z0-9_]+__[a-z0-9_]+/gi)) seen.add(m[0]);
238
+ return [...seen];
239
+ }
240
+
241
+ /** The server segment of `mcp__server__tool`, or `null` for a built-in. */
242
+ export function mcpServerOf(tool: string): string | null {
243
+ const m = /^mcp__([a-z0-9_]+)__[a-z0-9_]+$/i.exec(tool);
244
+ return m ? m[1] : null;
245
+ }
246
+
247
+ function quotedListAfter(claudeArgs: string, flag: string): string[] | null {
248
+ const m = new RegExp(`--${flag}\\s+"([^"]*)"`).exec(claudeArgs);
249
+ if (!m) return null;
250
+ return m[1]
251
+ .split(",")
252
+ .map(s => s.trim())
253
+ .filter(Boolean);
254
+ }
255
+
256
+ /**
257
+ * The regions this check is about, cut structurally. Exported so a case can
258
+ * assert the cuts are bounded before asserting anything about their contents —
259
+ * every claim below is of the form "X is not in here", and all of them hold
260
+ * vacuously of an empty string.
261
+ */
262
+ export function reviewWorkflowRegions(source: string): {
263
+ triggerBlock: string;
264
+ reviewStep: string;
265
+ prompt: string;
266
+ claudeArgs: string;
267
+ } {
268
+ const triggerBlock = structuralCut(source, "\non:", { endAnchor: "\npermissions:" });
269
+ const reviewStep = blockUnder(source, "- name: Review");
270
+
271
+ // The prompt is a YAML block scalar: `prompt: |` and everything indented
272
+ // under it, or a single-line `prompt: "…"`. Cut by indentation rather than
273
+ // by a character count (#664) — the region ends where the block ends.
274
+ const promptBlock = blockUnder(reviewStep, "prompt:");
275
+ const prompt = promptBlock.replace(/^\s*prompt:[ \t]*[|>]?[-+]?[ \t]*/, "").replace(/^"|"$/g, "");
276
+ if (prompt.trim() === "") {
277
+ throw new ReviewSourceUnreadableError("the Review step's prompt is empty");
278
+ }
279
+
280
+ const claudeArgs = blockUnder(reviewStep, "claude_args:");
281
+
282
+ return { triggerBlock, reviewStep, prompt, claudeArgs };
283
+ }
284
+
285
+ /**
286
+ * The one decider. Everything a case asserts about #732 comes back from here.
287
+ *
288
+ * `source` is the whole workflow file; the regions are cut inside, so a caller
289
+ * cannot accidentally ask the question of the wrong slice.
290
+ */
291
+ export function reviewToolAgreement(source: string): ReviewToolViolation[] {
292
+ const { triggerBlock, reviewStep, prompt, claudeArgs } = reviewWorkflowRegions(source);
293
+
294
+ const allowed = quotedListAfter(claudeArgs, "allowedTools") ?? [];
295
+ const denied = quotedListAfter(claudeArgs, "disallowedTools") ?? [];
296
+ const v: ReviewToolViolation[] = [];
297
+
298
+ // 1. The headline, kept because it is still a defect even though the
299
+ // mechanism the issue gives for it is wrong: a `/plugin:command` prompt
300
+ // makes the review's instructions live in a MUTABLE git ref that nothing
301
+ // in this repository pins or reads.
302
+ if (prompt.trim().startsWith("/")) {
303
+ v.push({
304
+ kind: "PROMPT_IS_A_SLASH_COMMAND",
305
+ detail:
306
+ `the prompt is ${JSON.stringify(prompt.trim().split("\n")[0])} — the instructions it ` +
307
+ `expands to are not in this repository, so nothing here can check which tools they need`,
308
+ });
309
+ }
310
+
311
+ // 2. A prompt that names no tool is the vacuous case: every agreement claim
312
+ // below holds trivially of it, which is exactly the shape that let two
313
+ // runs conclude success.
314
+ const promptTools = mcpToolsNamedIn(prompt);
315
+ if (promptTools.length === 0) {
316
+ v.push({
317
+ kind: "PROMPT_NAMES_NO_TOOL",
318
+ detail: "the prompt names no mcp tool at all, so it cannot be checked against the allowlist",
319
+ });
320
+ }
321
+
322
+ for (const tool of promptTools) {
323
+ if (denied.some(d => tool === d || tool.startsWith(`${d}__`))) {
324
+ v.push({
325
+ kind: "PROMPT_NAMES_A_DENIED_TOOL",
326
+ detail: `the prompt tells the agent to use ${tool}, which --disallowedTools denies`,
327
+ });
328
+ } else if (!allowed.some(a => tool === a || tool.startsWith(`${a}__`))) {
329
+ v.push({
330
+ kind: "PROMPT_NAMES_AN_UNGRANTED_TOOL",
331
+ detail: `the prompt tells the agent to use ${tool}, which --allowedTools does not grant`,
332
+ });
333
+ }
334
+ }
335
+
336
+ // 3. The door nothing in the prompt can show: a grant whose server the
337
+ // pinned action never starts under this workflow's triggers.
338
+ const triggers = [...triggerBlock.matchAll(/^\s{2}([a-z_]+):/gm)].map(m => m[1]);
339
+ const everyTriggerIsAutomation =
340
+ triggers.length > 0 &&
341
+ triggers.every(t => (AUTOMATION_ONLY_TRIGGERS as readonly string[]).includes(t));
342
+ if (everyTriggerIsAutomation) {
343
+ for (const tool of allowed) {
344
+ const server = mcpServerOf(tool);
345
+ const why = server ? ENTITY_ONLY_MCP_SERVERS[server] : undefined;
346
+ if (why) {
347
+ v.push({
348
+ kind: "ALLOWED_TOOL_CANNOT_EXIST_ON_THIS_TRIGGER",
349
+ detail:
350
+ `--allowedTools grants ${tool}, whose MCP server is installed only under an entity ` +
351
+ `event (${why}). This workflow's triggers are ${triggers.join(", ")}, all of which ` +
352
+ `the action classifies as automation events, so the tool never exists`,
353
+ });
354
+ }
355
+ }
356
+ }
357
+
358
+ // 4. Nothing on the allowlist can write a finding anywhere a human will see.
359
+ if (!allowed.some(a => (POSTING_TOOLS as readonly string[]).includes(a))) {
360
+ v.push({
361
+ kind: "NO_POSTING_TOOL_IS_ALLOWED",
362
+ detail:
363
+ `--allowedTools grants [${allowed.join(", ")}], none of which can post a review or a ` +
364
+ `comment. A review that cannot be read is indistinguishable from one that found nothing`,
365
+ });
366
+ }
367
+
368
+ // 5. With no fetching tool granted, the diff has to arrive IN the prompt.
369
+ // Interpolating a prior step's output is the only way it can.
370
+ const canFetch = allowed.some(a => (SUBJECT_FETCHING_TOOLS as readonly string[]).includes(a));
371
+ const promptCarriesSubject = new RegExp(
372
+ `\\$\\{\\{\\s*steps\\.[A-Za-z0-9_-]+\\.outputs\\.${SUBJECT_OUTPUT_NAME}\\s*\\}\\}`,
373
+ ).test(prompt);
374
+ if (!canFetch && !promptCarriesSubject) {
375
+ v.push({
376
+ kind: "NO_SUBJECT_REACHES_THE_AGENT",
377
+ detail:
378
+ `no tool on the allowlist can fetch the code and the prompt interpolates no ` +
379
+ `steps.*.outputs.${SUBJECT_OUTPUT_NAME}, so the agent is asked to review code it has ` +
380
+ `no way to see`,
381
+ });
382
+ }
383
+
384
+ // 6. #630 AC-16: plugin code loaded from a ref the publisher can repoint,
385
+ // in a file where every `uses:` is SHA-pinned.
386
+ if (/^\s*plugin_marketplaces\s*:/m.test(reviewStep)) {
387
+ v.push({
388
+ kind: "MUTABLE_PLUGIN_MARKETPLACE",
389
+ detail:
390
+ "the Review step declares plugin_marketplaces, which loads executing code from a MUTABLE " +
391
+ "git ref while every uses: in this file is pinned to a commit SHA (#630 AC-16)",
392
+ });
393
+ }
394
+
395
+ // 7. AC-1/AC-2: something has to read what the run actually did, or a run
396
+ // that made zero tool calls concludes success exactly as before.
397
+ //
398
+ // Asked of the STEP, not the document. The first draft of this check was
399
+ // `/execution_file/.test(source)` and was caught by the reviewer this
400
+ // very change exists to repair: the string already appears in a comment
401
+ // in the Review step, so the check was satisfied by prose about itself —
402
+ // `.claude/rules/checks-must-be-able-to-fail.md` §"search the slice, not
403
+ // the document", which that rule has now caught in its own subject four
404
+ // times. The step is located by the SCRIPT it runs rather than by its
405
+ // `name:`, because a name is prose and the invocation is the binding.
406
+ const readingSteps = jobSteps(source)
407
+ .map(withoutComments)
408
+ .filter(s => s.includes(READING_SCRIPT));
409
+ if (readingSteps.length !== 1) {
410
+ v.push({
411
+ kind: "NO_STEP_READS_THE_EXECUTION_OUTPUT",
412
+ detail:
413
+ `${readingSteps.length} steps run ${READING_SCRIPT}, not one. A run that made zero tool ` +
414
+ `calls and posted nothing then concludes success — which is #732's whole subject`,
415
+ });
416
+ } else {
417
+ const step = readingSteps[0];
418
+ const missing = [
419
+ /execution_file/.test(step) ? null : "it does not read the action's execution_file output",
420
+ /^\s*if:\s*always\(\)\s*$/m.test(step)
421
+ ? null
422
+ : "it is not `if: always()`, so the interesting case — the review step reporting success — skips it",
423
+ ].filter(Boolean);
424
+ if (missing.length > 0) {
425
+ v.push({
426
+ kind: "NO_STEP_READS_THE_EXECUTION_OUTPUT",
427
+ detail: `the step running ${READING_SCRIPT} cannot do its job: ${missing.join("; ")}`,
428
+ });
429
+ }
430
+ }
431
+
432
+ return v;
433
+ }
@@ -0,0 +1,234 @@
1
+ /**
2
+ * Promotion and eviction for extracted constraint candidates (#544).
3
+ *
4
+ * ## The one criterion enforced here
5
+ *
6
+ * **A candidate that cannot be traced to a dated observation is not
7
+ * promoted.** Evidence is a GATE, not a tiebreak.
8
+ *
9
+ * `specs/RULE-LIFECYCLE-AND-CONTEXT-BUDGET-SPEC.md` SC-1939 states the weaker
10
+ * form — *a candidate with no evidence never outranks one that has it* — and
11
+ * this satisfies it a fortiori: an evidence-less candidate never appears in
12
+ * `promoted` at all, at any budget, so there is no ordering in which it can
13
+ * outrank anything.
14
+ *
15
+ * The stronger form is the one the evidence supports. Every rule in this
16
+ * repository's `.claude/rules/` that an agent demonstrably acts on narrates a
17
+ * dated incident — the #70 collision, run `wf_0b15a933-b2b`, the five bugs of
18
+ * 2026-10-06. `agent-principles.md` ships *"verify before asserting"* to every
19
+ * consumer, costs budget in every session, and the learning loop still carries
20
+ * four separate low-rating patterns for failing to do exactly that. A general
21
+ * principle with nothing behind it is not a weak rule; it is a rule that has
22
+ * been measured not to work.
23
+ *
24
+ * ## Eviction is here, not in a follow-up
25
+ *
26
+ * `docs/research/context-management.md` records the measured collapse: rule
27
+ * sets lose effectiveness past roughly sixteen rules, and the threshold is
28
+ * about the TOTAL in context. So a lifecycle that only adds degrades the thing
29
+ * it feeds, and a promoter that cannot evict is a cap with no teeth. The
30
+ * budget cut and the promotion decision are therefore one reading, returned
31
+ * together, with every withheld candidate carrying the reason it lost.
32
+ *
33
+ * ## WHAT THIS DOES NOT COVER
34
+ *
35
+ * Each escape is asserted as a case in `test/failure-intake-promotion.test.ts`.
36
+ *
37
+ * - **The budget is a COUNT of promoted rules, not max-concurrent-load.**
38
+ * The spec's budget criterion asks for max-concurrent-load — for every
39
+ * file in the repository, count the rules whose globs match it, and take
40
+ * the maximum — and nothing here computes it, because nothing here emits
41
+ * `paths:` globs yet. A count is strictly more pessimistic than concurrent
42
+ * load, so this cannot under-report; it can refuse a set that would have
43
+ * been fine.
44
+ * - **Nothing reads whether the cited evidence still resolves.** The spec's
45
+ * auto-retirement criterion is not implemented: a candidate citing a commit
46
+ * that has been rebased away still ranks on its date.
47
+ * - **Recency is the only ranking signal among evidence-backed candidates.**
48
+ * The spec names four more — whether the governed code changed recently,
49
+ * the violation count in graded runs, whether the text states a prohibition,
50
+ * and whether the cited `file:line` resolves. A commit-subject candidate has
51
+ * no `file:line`, and the other three need producers that do not exist yet.
52
+ * So "the mechanical evidence score" is currently one term, and saying so is
53
+ * the difference between a scorer and a sort.
54
+ * - **A rejected hash is permanent and global.** The veto table has no
55
+ * per-source scoping, so vetoing a sentence mined from a commit also vetoes
56
+ * the identical sentence if it later appears in a doc. That is the intended
57
+ * reading of the permanent-veto criterion and is recorded here because it
58
+ * is a decision, not an accident.
59
+ */
60
+ import type { CandidateEvidence } from "./failure-intake";
61
+
62
+ export interface PromotableCandidate {
63
+ rule: string;
64
+ source: string;
65
+ hash: string;
66
+ /** Absent for a doc-prose candidate. Its absence is the gate below. */
67
+ evidence?: CandidateEvidence;
68
+ }
69
+
70
+ export type WithheldReason =
71
+ /** Vetoed previously, per the table at `reference/rejected-constraints.md`. */
72
+ | "REJECTED"
73
+ /** No dated observation behind it. The criterion this module exists for. */
74
+ | "NO_EVIDENCE"
75
+ /** Evidence-backed, and ranked below the cut. The eviction. */
76
+ | "OVER_BUDGET";
77
+
78
+ export interface WithheldCandidate {
79
+ candidate: PromotableCandidate;
80
+ reason: WithheldReason;
81
+ }
82
+
83
+ /**
84
+ * The number of mined rules allowed to be active at once.
85
+ *
86
+ * Sixteen, from `docs/research/context-management.md`: effectiveness collapses
87
+ * past roughly that many rules, and the threshold is over the total in
88
+ * context. ONE declaring position — a second literal somewhere else would be a
89
+ * second decider for a question this module answers.
90
+ *
91
+ * Superseded by the spec's max-concurrent-load budget once mined rules carry
92
+ * `paths:`. Until then this is the pessimistic stand-in, and the comment is
93
+ * here so the number is not mistaken for the budget the spec specifies.
94
+ */
95
+ export const PROMOTION_BUDGET_RULES = 16;
96
+
97
+ export const NON_POSITIVE_BUDGET = "NON_POSITIVE_BUDGET";
98
+ /** An upstream read UNMEASURED without naming a reason. */
99
+ export const UPSTREAM_UNMEASURED = "UPSTREAM_UNMEASURED";
100
+
101
+ export interface PromotionReading {
102
+ /**
103
+ * The single discriminator. `unmeasuredReasons` is the other projection of
104
+ * the same computation, so the two cannot disagree.
105
+ */
106
+ reading: "MEASURED" | "UNMEASURED";
107
+ unmeasuredReasons: string[];
108
+ budget: number;
109
+ promoted: PromotableCandidate[];
110
+ withheld: WithheldCandidate[];
111
+ }
112
+
113
+ /**
114
+ * THE ordering over evidence-backed candidates. One binding.
115
+ *
116
+ * It deliberately does NOT re-decide whether a candidate has evidence. The
117
+ * gate in `promoteCandidates` answers that, nothing evidence-less reaches this
118
+ * comparator, and a second evidence clause here would be unreachable code
119
+ * agreeing with a decision already taken — which is the fourth shape in
120
+ * `.claude/rules/checks-must-be-able-to-fail.md` built in on purpose.
121
+ *
122
+ * Dates are parsed, never compared as strings. `git log --format=%cI` emits
123
+ * whatever offset the committer's machine had: `main` carries
124
+ * `2026-10-21T19:18:27Z` and `2026-10-21T15:01:51-04:00` on adjacent commits,
125
+ * and those two sort in the wrong order lexicographically while naming almost
126
+ * the same instant.
127
+ */
128
+ export function rankForPromotion(a: PromotableCandidate, b: PromotableCandidate): number {
129
+ const ta = epoch(a);
130
+ const tb = epoch(b);
131
+ if (ta !== tb) return tb - ta;
132
+ // Stable and content-derived, so two runs over one history agree byte for
133
+ // byte. Falling back to input order would make the output depend on the
134
+ // walk, which is the idempotency SC-1946 asks for, lost for free.
135
+ return a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0;
136
+ }
137
+
138
+ function epoch(c: PromotableCandidate): number {
139
+ const parsed = c.evidence ? Date.parse(c.evidence.date) : NaN;
140
+ return Number.isNaN(parsed) ? 0 : parsed;
141
+ }
142
+
143
+ /**
144
+ * Decide what gets promoted, and say why everything else did not.
145
+ *
146
+ * Three questions, in order, each with one binding: has this been vetoed, does
147
+ * it carry evidence, and does it fit. They are not three readings of one fact
148
+ * — a vetoed candidate and an evidence-less one lose for different reasons and
149
+ * a reader can act on only one of them.
150
+ *
151
+ * `upstream` folds in the readings taken before this one — the intake's, and
152
+ * since #544 the retirement pass's. A promotion computed over a shallow
153
+ * clone's candidates is not a smaller promotion, it is a promotion over an
154
+ * unknown population, and `0 promoted` from a truncated history reads exactly
155
+ * like `0 promoted` from a repository with nothing to promote.
156
+ *
157
+ * It takes a LIST because there are now two of them, and folding two readings
158
+ * into one at the call site would put a third decider between the producers
159
+ * and this function — one that could report MEASURED while either upstream
160
+ * said otherwise. A single reading is still accepted; it is the one-element
161
+ * case.
162
+ */
163
+ export type UpstreamReading = { reading: "MEASURED" | "UNMEASURED"; unmeasuredReasons: string[] };
164
+
165
+ export function promoteCandidates(
166
+ candidates: PromotableCandidate[],
167
+ options: {
168
+ budget: number;
169
+ rejectedHashes?: ReadonlySet<string>;
170
+ upstream?: UpstreamReading | readonly UpstreamReading[];
171
+ },
172
+ ): PromotionReading {
173
+ const { budget } = options;
174
+ const rejected = options.rejectedHashes ?? new Set<string>();
175
+ const upstreams: readonly UpstreamReading[] = options.upstream
176
+ ? Array.isArray(options.upstream)
177
+ ? options.upstream
178
+ : [options.upstream as UpstreamReading]
179
+ : [];
180
+ const unmeasuredReasons = upstreams.flatMap(u => u.unmeasuredReasons);
181
+ // The discriminator is authoritative, not the reason list. An upstream that
182
+ // read UNMEASURED and named no reason is still UNMEASURED, and folding only
183
+ // the reasons would have let it through as MEASURED — a producer and a
184
+ // consumer disagreeing about one fact, with the wrong one winning.
185
+ if (upstreams.some(u => u.reading === "UNMEASURED") && unmeasuredReasons.length === 0) {
186
+ unmeasuredReasons.push(UPSTREAM_UNMEASURED);
187
+ }
188
+
189
+ const withheld: WithheldCandidate[] = [];
190
+ const eligible: PromotableCandidate[] = [];
191
+
192
+ for (const candidate of candidates) {
193
+ if (rejected.has(candidate.hash)) {
194
+ withheld.push({ candidate, reason: "REJECTED" });
195
+ continue;
196
+ }
197
+ if (!candidate.evidence) {
198
+ withheld.push({ candidate, reason: "NO_EVIDENCE" });
199
+ continue;
200
+ }
201
+ eligible.push(candidate);
202
+ }
203
+
204
+ if (budget < 1) {
205
+ unmeasuredReasons.push(NON_POSITIVE_BUDGET);
206
+ for (const candidate of eligible) withheld.push({ candidate, reason: "OVER_BUDGET" });
207
+ return { reading: "UNMEASURED", unmeasuredReasons, budget, promoted: [], withheld };
208
+ }
209
+
210
+ const ranked = [...eligible].sort(rankForPromotion);
211
+ for (const candidate of ranked.slice(budget)) {
212
+ withheld.push({ candidate, reason: "OVER_BUDGET" });
213
+ }
214
+
215
+ return {
216
+ reading: unmeasuredReasons.length > 0 ? "UNMEASURED" : "MEASURED",
217
+ unmeasuredReasons,
218
+ budget,
219
+ promoted: ranked.slice(0, budget),
220
+ withheld,
221
+ };
222
+ }
223
+
224
+ /** One line a caller can print without re-deriving any of the above. */
225
+ export function promotionSummary(reading: PromotionReading): string {
226
+ const counts = new Map<WithheldReason, number>();
227
+ for (const w of reading.withheld) counts.set(w.reason, (counts.get(w.reason) ?? 0) + 1);
228
+ const why = [...counts.entries()].map(([r, n]) => `${r}=${n}`).join(" ");
229
+ return (
230
+ `promotion ${reading.reading}: ${reading.promoted.length} promoted of budget ${reading.budget}` +
231
+ (why ? `, withheld ${why}` : "") +
232
+ (reading.unmeasuredReasons.length > 0 ? ` — ${reading.unmeasuredReasons.join("; ")}` : "")
233
+ );
234
+ }