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,156 @@
1
+ /**
2
+ * The tree a report was measured against, stated by the reporter (#553).
3
+ *
4
+ * Two security reviews arrived from peer sessions on 2026-10-17. Both
5
+ * reported CONFIRMED findings, both were measured against a tree the branch
6
+ * had already moved past, and in both cases the report gave no way to tell.
7
+ * sec-492's three findings were measured at `7fdfa72a` (20:32); two commits
8
+ * landed about 75 minutes later and closed all three, and two of the
9
+ * "0 red" mutation rows are 3 and 1 on main.
10
+ *
11
+ * ## What is missing is the SENDING side
12
+ *
13
+ * `.claude/rules/parallel-sessions.md` already covers the receiving side —
14
+ * *"peer reports are evidence, not fact"* — and that rule worked both times:
15
+ * the reports were checked before anything was acted on, which is the only
16
+ * reason neither cost anything. But verifying every finding from scratch is
17
+ * the expensive path to a cheap fact that **the reviewer already holds**.
18
+ *
19
+ * The ship pipeline solves this inside itself: `reviewIsCurrent` pins a
20
+ * review to a commit and blocks when the branch has moved, which is #129,
21
+ * #169, #171 and #244 of accumulated work. A review conducted OUTSIDE
22
+ * `workflows/ship.js` inherits none of it.
23
+ *
24
+ * So this is that same binding, reachable from a terminal. It does not
25
+ * reimplement the comparison — `reviewIsCurrent` is imported, because a
26
+ * second decider answering the same question is behaviourally one decider
27
+ * and no test can tell them apart
28
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
29
+ *
30
+ * ## It fails closed, and an unanswerable question is not a pass
31
+ *
32
+ * A branch that cannot be resolved, a SHA that is not a SHA, a directory
33
+ * that is not a repository: all `current: false`, each with a reason naming
34
+ * what could not be read. A reviewer who cannot establish currency has
35
+ * learned something worth putting in the report, and a provenance block that
36
+ * went quiet on an error would be worse than none — it would be a claim.
37
+ */
38
+ import { execFileSync } from "child_process";
39
+
40
+ import { reviewIsCurrent } from "./security-verdict";
41
+
42
+ /** The exit code of a stale or unmeasurable reading. One site, so it can be mutated. */
43
+ export const STALE_EXIT = 1;
44
+
45
+ export interface ProvenanceReading {
46
+ /** The commit the report describes. */
47
+ measured: string | null;
48
+ /** The commit the branch ends at now, or null when it could not be read. */
49
+ tip: string | null;
50
+ /** The ref the tip was read from, e.g. `origin/fix/553`. */
51
+ ref: string | null;
52
+ current: boolean;
53
+ /** Always present. Names both operands when there are two to name. */
54
+ reason: string;
55
+ }
56
+
57
+ function git(root: string, args: string[]): string | null {
58
+ try {
59
+ return execFileSync("git", args, {
60
+ cwd: root,
61
+ encoding: "utf-8",
62
+ timeout: 60_000,
63
+ stdio: ["ignore", "pipe", "pipe"],
64
+ }).trim();
65
+ } catch {
66
+ return null;
67
+ }
68
+ }
69
+
70
+ /**
71
+ * The ref whose tip a report should be aged against.
72
+ *
73
+ * `origin/<branch>` when it exists, because that is what another session can
74
+ * see; the local branch otherwise, which is the honest answer for work that
75
+ * has not been pushed. Detached HEAD has no branch and says so.
76
+ */
77
+ export function defaultRef(root: string): string | null {
78
+ const branch = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
79
+ if (branch === null || branch === "" || branch === "HEAD") return null;
80
+ if (git(root, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`]) !== null) {
81
+ return `origin/${branch}`;
82
+ }
83
+ return branch;
84
+ }
85
+
86
+ /**
87
+ * Compare the tree a report describes against the tree the branch ends at.
88
+ *
89
+ * `measured` defaults to this working tree's HEAD, which is what a reviewer
90
+ * who just finished reading has in front of them.
91
+ */
92
+ export function provenanceReading(
93
+ root: string,
94
+ measured?: string,
95
+ ref?: string,
96
+ ): ProvenanceReading {
97
+ const measuredSha = measured ?? git(root, ["rev-parse", "HEAD"]);
98
+ const resolvedRef = ref ?? defaultRef(root);
99
+
100
+ if (resolvedRef === null) {
101
+ return {
102
+ measured: measuredSha,
103
+ tip: null,
104
+ ref: null,
105
+ current: false,
106
+ reason:
107
+ `UNMEASURED: no branch to age this report against — ${root} is not a repository, ` +
108
+ `or HEAD is detached. State the commit you measured and say that the branch could ` +
109
+ `not be resolved.`,
110
+ };
111
+ }
112
+
113
+ // Fetch nothing. A reviewer who has not fetched is comparing against a
114
+ // stale remote-tracking ref, which is a different failure from a moved
115
+ // branch and must not be hidden by a network call this function made on
116
+ // its own.
117
+ const tip = git(root, ["rev-parse", "--verify", `${resolvedRef}^{commit}`]);
118
+ if (tip === null) {
119
+ return {
120
+ measured: measuredSha,
121
+ tip: null,
122
+ ref: resolvedRef,
123
+ current: false,
124
+ reason:
125
+ `UNMEASURED: ${resolvedRef} could not be resolved, so there is nothing to compare ` +
126
+ `${measuredSha ?? "an unreadable HEAD"} against.`,
127
+ };
128
+ }
129
+
130
+ // The one binding. `workflows/ship.js` inlines a copy of this function for
131
+ // the sandbox (#69) and `test/security-verdict-blocks.test.ts` holds the
132
+ // two to parity; this is the library side, imported rather than repeated.
133
+ const currency = reviewIsCurrent(measuredSha, tip);
134
+ return {
135
+ measured: measuredSha,
136
+ tip,
137
+ ref: resolvedRef,
138
+ current: currency.current,
139
+ reason: currency.current
140
+ ? `the report describes ${measuredSha}, which is the tip of ${resolvedRef}`
141
+ : (currency.reason ??
142
+ `the report describes ${measuredSha}, which is not the tip of ${resolvedRef} (${tip})`),
143
+ };
144
+ }
145
+
146
+ /** The block to paste at the top of a report. Always states both commits. */
147
+ export function provenanceBlock(reading: ProvenanceReading): string {
148
+ const lines = [
149
+ `Measured against: ${reading.measured ?? "UNKNOWN"}`,
150
+ `Branch tip (${reading.ref ?? "unresolved"}): ${reading.tip ?? "UNKNOWN"}`,
151
+ reading.current
152
+ ? `Currency: CURRENT — ${reading.reason}`
153
+ : `Currency: NOT CURRENT — ${reading.reason}`,
154
+ ];
155
+ return lines.join("\n");
156
+ }
@@ -0,0 +1,206 @@
1
+ /**
2
+ * What did the review run actually DO? (#732 AC-1, AC-2)
3
+ *
4
+ * Both runs on #732's table concluded **success** having posted nothing. The
5
+ * job had no way to notice: `claude-code-action` sets `conclusion: success`
6
+ * when the CLI exits zero, and a CLI that produced no tool calls and no
7
+ * comments exits zero. `0`, `{}`, `null` and `SKIP` are indistinguishable from
8
+ * success — `.claude/rules/config-access.md` — and so is a review that
9
+ * produced no output. `UNMEASURED` is the only reading that is not.
10
+ *
11
+ * Two facts, deliberately separate, because they can disagree and the
12
+ * disagreement is the interesting case:
13
+ *
14
+ * - **tool calls** — what the agent did, read from the action's
15
+ * `execution_file` (`claude-execution-output.json`, a JSON array of SDK
16
+ * messages; a tool call is a `tool_use` content block on an assistant
17
+ * message). Zero is AC-2: the agent executed nothing, so whatever it
18
+ * concluded it concluded from nothing.
19
+ * - **reviews THIS RUN added** — what GitHub holds after, minus what it held
20
+ * before, counted by the caller against the API. Zero is AC-1: nobody can
21
+ * read this run's review.
22
+ *
23
+ * **A DELTA, and not a total, and that is not a refinement.** The first live
24
+ * dispatch of the fixed workflow posted one review on PR #746. A total would
25
+ * then have read `1` for every subsequent run of that PR forever — including
26
+ * a run that posted nothing, which is the exact state #732 is about. A
27
+ * cumulative count makes the second run of any reviewed PR unfalsifiable, so
28
+ * the before-count is taken before the agent starts and the reading is the
29
+ * difference.
30
+ *
31
+ * These are not two deciders answering one question
32
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape). An agent
33
+ * that called the posting tool and had the API reject it has a non-zero tool
34
+ * count and a zero review count, and that run is a different defect from one
35
+ * that never tried. Folding them into one boolean would lose exactly that.
36
+ *
37
+ * ## The run's own table could not answer AC-2, which is why this exists
38
+ *
39
+ * #732's "tool calls of any kind: 0" is not readable from either run's log.
40
+ * The action prints `Running Claude Code via SDK (full output hidden for
41
+ * security)` and the JSON result block carries `num_turns`,
42
+ * `permission_denials_count` and `total_cost_usd` and no per-tool record.
43
+ * `num_turns: 13` with 4 denials is in fact evidence the agent WAS attempting
44
+ * tool calls. The execution file is where the answer lives, and nothing was
45
+ * reading it.
46
+ *
47
+ * ## One exit constant
48
+ *
49
+ * `scripts/read-review-execution.ts` routes its only refusal through
50
+ * `REVIEW_UNMEASURED_EXIT`, declared once here, so a test can build a mutant
51
+ * with it set to `0` and watch the refusal stop happening. A later branch that
52
+ * inlines `process.exit(1)` would bypass the mutation and the case would go
53
+ * green having witnessed nothing.
54
+ */
55
+
56
+ /** The single non-zero exit a review reading refuses with. */
57
+ export const REVIEW_UNMEASURED_EXIT = 1;
58
+
59
+ export type ReviewUnmeasuredReason =
60
+ | "EXECUTION_FILE_ABSENT"
61
+ | "EXECUTION_FILE_UNREADABLE"
62
+ | "NO_TOOL_CALLS"
63
+ | "NO_REVIEW_POSTED"
64
+ | "REVIEW_COUNT_UNAVAILABLE"
65
+ | "DIFF_TRUNCATED";
66
+
67
+ export type ReviewExecutionReading = {
68
+ reading: "MEASURED" | "UNMEASURED";
69
+ /** `null` when the execution file could not be read at all. */
70
+ toolCalls: number | null;
71
+ /** Tool calls by tool name, for the annotation — "which door" needs names. */
72
+ toolCallsByName: Record<string, number>;
73
+ /** Reviews this run ADDED — after minus before. `null` when either
74
+ * count could not be taken. */
75
+ reviewsPosted: number | null;
76
+ reasons: ReviewUnmeasuredReason[];
77
+ /** One sentence per reason, in the same order. */
78
+ detail: string[];
79
+ };
80
+
81
+ export type ReviewExecutionInput = {
82
+ /** The contents of `claude-execution-output.json`, or `null` if absent. */
83
+ executionFileRaw: string | null;
84
+ /** Reviews this run ADDED — the PR's review count after the run minus its
85
+ * count before it, or `null` when either could not be taken. A TOTAL would
86
+ * make the second run of any reviewed PR unfalsifiable. */
87
+ reviewsPosted: number | null;
88
+ /** Whether the diff handed to the agent was cut short of the real one. */
89
+ diffTruncated: boolean;
90
+ };
91
+
92
+ function countToolUses(raw: string): Record<string, number> | null {
93
+ let parsed: unknown;
94
+ try {
95
+ parsed = JSON.parse(raw);
96
+ } catch {
97
+ return null;
98
+ }
99
+ if (!Array.isArray(parsed)) return null;
100
+ const byName: Record<string, number> = {};
101
+ for (const message of parsed) {
102
+ const content = (message as { message?: { content?: unknown } })?.message?.content;
103
+ if (!Array.isArray(content)) continue;
104
+ for (const block of content) {
105
+ const b = block as { type?: unknown; name?: unknown };
106
+ if (b?.type !== "tool_use") continue;
107
+ const name = typeof b.name === "string" ? b.name : "<unnamed>";
108
+ byName[name] = (byName[name] ?? 0) + 1;
109
+ }
110
+ }
111
+ return byName;
112
+ }
113
+
114
+ /**
115
+ * The one decider. `reading` and `reasons` are both projections of the same
116
+ * list computed here and nowhere else, so they cannot disagree.
117
+ */
118
+ export function reviewExecutionReading(input: ReviewExecutionInput): ReviewExecutionReading {
119
+ const reasons: ReviewUnmeasuredReason[] = [];
120
+ const detail: string[] = [];
121
+ const add = (reason: ReviewUnmeasuredReason, why: string) => {
122
+ reasons.push(reason);
123
+ detail.push(why);
124
+ };
125
+
126
+ let toolCallsByName: Record<string, number> = {};
127
+ let toolCalls: number | null = null;
128
+
129
+ if (input.executionFileRaw === null) {
130
+ add(
131
+ "EXECUTION_FILE_ABSENT",
132
+ "the action produced no execution_file, so nothing can say what the run did",
133
+ );
134
+ } else {
135
+ const byName = countToolUses(input.executionFileRaw);
136
+ if (byName === null) {
137
+ add(
138
+ "EXECUTION_FILE_UNREADABLE",
139
+ "the execution file is not a JSON array of SDK messages — a reading that could not be " +
140
+ "taken is not a reading that passed",
141
+ );
142
+ } else {
143
+ toolCallsByName = byName;
144
+ toolCalls = Object.values(byName).reduce((a, b) => a + b, 0);
145
+ if (toolCalls === 0) {
146
+ add(
147
+ "NO_TOOL_CALLS",
148
+ "the agent made zero tool calls of any kind: it executed nothing, so whatever it " +
149
+ "concluded it concluded from nothing (AC-2)",
150
+ );
151
+ }
152
+ }
153
+ }
154
+
155
+ if (input.reviewsPosted === null) {
156
+ add(
157
+ "REVIEW_COUNT_UNAVAILABLE",
158
+ "the pull request's review count could not be taken before or after the run, so 'this " +
159
+ "run posted a review' is unestablished rather than false",
160
+ );
161
+ } else if (input.reviewsPosted === 0) {
162
+ add(
163
+ "NO_REVIEW_POSTED",
164
+ "this run added no review to the pull request: a review nobody can read is " +
165
+ "indistinguishable from one that found nothing (AC-1)",
166
+ );
167
+ }
168
+
169
+ if (input.diffTruncated) {
170
+ add(
171
+ "DIFF_TRUNCATED",
172
+ "the diff handed to the agent was cut short, so part of the pull request was never looked " +
173
+ "at — a partial review reported as a clean one is the same defect in miniature",
174
+ );
175
+ }
176
+
177
+ return {
178
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
179
+ toolCalls,
180
+ toolCallsByName,
181
+ reviewsPosted: input.reviewsPosted,
182
+ reasons,
183
+ detail,
184
+ };
185
+ }
186
+
187
+ /** The annotation body. Named reasons, named counts — a warning that does not
188
+ * say what was missing is a warning nobody can act on. */
189
+ export function reviewReadingReport(r: ReviewExecutionReading): string {
190
+ const calls =
191
+ r.toolCalls === null
192
+ ? "tool calls: UNREADABLE"
193
+ : `tool calls: ${r.toolCalls}` +
194
+ (r.toolCalls > 0
195
+ ? ` (${Object.entries(r.toolCallsByName)
196
+ .map(([n, c]) => `${n}×${c}`)
197
+ .join(", ")})`
198
+ : "");
199
+ const reviews =
200
+ r.reviewsPosted === null
201
+ ? "reviews added by this run: UNCOUNTED"
202
+ : `reviews added by this run: ${r.reviewsPosted}`;
203
+ const head = `${r.reading} — ${calls}; ${reviews}`;
204
+ if (r.reading === "MEASURED") return head;
205
+ return [head, ...r.reasons.map((reason, i) => ` ${reason}: ${r.detail[i]}`)].join("\n");
206
+ }