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.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/BunTestPathGuard.hook.ts +106 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/TopLevelCdGuard.hook.ts +38 -6
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/bun-test-paths.ts +253 -0
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +17 -1
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +61 -5
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +646 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +21 -1
- package/lib/project-state-shape.ts +56 -5
- package/lib/release-preflight.ts +90 -1
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +218 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1369 -27
- package/lib/scaffold/ai-review-step.ts +4095 -119
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +100 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +22 -2
- package/lib/spec-write-ast.ts +728 -0
- package/lib/spec-write-sweep.ts +470 -0
- package/lib/test-suite-lock.ts +127 -13
- package/lib/ts-ast.ts +26 -0
- package/lib/validators/spec-validators.ts +36 -7
- package/lib/write-spec.ts +138 -0
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -24
- package/scripts/convert-spec.ts +7 -2
- package/scripts/create-sc.ts +14 -2
- package/scripts/create-spec.ts +5 -2
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +17 -4
- package/scripts/sync-sc-status.ts +14 -2
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The workflow that runs the unmeasured classifier automatically (#1488).
|
|
3
|
+
*
|
|
4
|
+
* #1486 shipped the classifier — `lib/ai-review-unmeasured.ts` — and a
|
|
5
|
+
* recorder somebody has to type, `scripts/record-ai-review-unmeasured.ts`.
|
|
6
|
+
* It works: #1470's ledger comment carries five `"unmeasured": "declined"`
|
|
7
|
+
* beside five intact `"findings": null`. What it does not do is run, and the
|
|
8
|
+
* evidence it reads has a deadline. Actions logs expire, so every round whose
|
|
9
|
+
* log ages out loses its discriminator permanently. The classifier makes the
|
|
10
|
+
* question answerable; until this file it did not make it answered.
|
|
11
|
+
*
|
|
12
|
+
* ## Why this is a second workflow and not a step in the ai-review job
|
|
13
|
+
*
|
|
14
|
+
* The persist step runs MID-JOB, between the reviewer and the adjudicator,
|
|
15
|
+
* and `gh run view --job <id> --log` on a running job answers
|
|
16
|
+
*
|
|
17
|
+
* ```
|
|
18
|
+
* run <id> is still in progress; logs will be available when it is complete
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* There is no moment inside that job at which the log exists to be read. Two
|
|
22
|
+
* older readings agree and are now corroboration rather than the argument:
|
|
23
|
+
* `AI_REVIEW_APP_INSTALL_CAUSE`'s docblock (*"A later step cannot read a
|
|
24
|
+
* previous step's stdout"*, #803), and `test/ai-review-payload-reading.test.ts`
|
|
25
|
+
* AC-6, which refuses the action's skip prose anywhere in the generated
|
|
26
|
+
* script because *"the check cannot tell a grep from a mention"*.
|
|
27
|
+
*
|
|
28
|
+
* `workflow_run: completed` fires after the job ends, which is the first
|
|
29
|
+
* moment the log is served.
|
|
30
|
+
*
|
|
31
|
+
* ## It is not a required check and it must never look like one
|
|
32
|
+
*
|
|
33
|
+
* A `workflow_run` workflow reports no status to the pull request, so it
|
|
34
|
+
* cannot gate anything and cannot hang a merge queue. That is why it is the
|
|
35
|
+
* one generated workflow with no `merge_group` trigger —
|
|
36
|
+
* `test/merge-group-trigger.test.ts` narrows its population to the workflows
|
|
37
|
+
* that CAN be required, and `test/ai-review-unmeasured-workflow.test.ts`
|
|
38
|
+
* AC-7 asserts this file is outside it for the stated reason rather than by
|
|
39
|
+
* being forgotten.
|
|
40
|
+
*
|
|
41
|
+
* ## The subscription is DERIVED, not spelled twice
|
|
42
|
+
*
|
|
43
|
+
* `workflow_run.workflows` matches on a workflow's `name:`. Two literals
|
|
44
|
+
* reading `AI Review` in two files is two deciders agreeing, and a rename of
|
|
45
|
+
* one would leave this workflow subscribed to a workflow that no longer
|
|
46
|
+
* exists — firing never, which is indistinguishable from firing and finding
|
|
47
|
+
* nothing to classify. So `AI_REVIEW_WORKFLOW_NAME` is declared here, the
|
|
48
|
+
* generated `ai-review.yml` renders its `name:` from it, and AC-8 asserts
|
|
49
|
+
* the subscription names the workflow the generator actually produced.
|
|
50
|
+
*
|
|
51
|
+
* ## The known boundary: two of these jobs can lose one reading
|
|
52
|
+
*
|
|
53
|
+
* The ledger PATCH is a read-modify-write of one comment. Two review rounds
|
|
54
|
+
* finishing close together fire two of these jobs, both read the ledger
|
|
55
|
+
* before either writes, and the later write can drop the earlier round's
|
|
56
|
+
* discriminator. Recorded rather than papered over, because the obvious fix
|
|
57
|
+
* is worse: a `concurrency:` group holds at most one pending run and
|
|
58
|
+
* **cancels** whatever arrives behind it, so a burst would classify nothing
|
|
59
|
+
* at all — and a cancelled run and a run that found nothing to classify are
|
|
60
|
+
* the same absence, which is this feature's own defect.
|
|
61
|
+
*
|
|
62
|
+
* The recovery is the one #1488 already names. A round that lost its
|
|
63
|
+
* reading still reads NOT_RECORDED, so the next round on that pull request
|
|
64
|
+
* records it, and `scripts/record-ai-review-unmeasured.ts` over a window
|
|
65
|
+
* catches whatever is left while its log still exists.
|
|
66
|
+
*/
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* The `name:` of the workflow that produces the rounds this one classifies.
|
|
70
|
+
*
|
|
71
|
+
* Declared HERE rather than in `lib/scaffold/steps.ts` beside the file it
|
|
72
|
+
* titles, because the subscriber is the side that breaks silently: a
|
|
73
|
+
* workflow whose `workflows:` list names nothing never runs, and a workflow
|
|
74
|
+
* that never runs emits no annotation, no log and no check.
|
|
75
|
+
*/
|
|
76
|
+
export const AI_REVIEW_WORKFLOW_NAME = "AI Review";
|
|
77
|
+
|
|
78
|
+
/** The file this module generates, under `.github/workflows/`. */
|
|
79
|
+
export const AI_REVIEW_UNMEASURED_WORKFLOW_FILE = "ai-review-unmeasured.yml";
|
|
80
|
+
|
|
81
|
+
/** The one job in it. */
|
|
82
|
+
export const AI_REVIEW_UNMEASURED_JOB = "record-unmeasured";
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The CLI command the step runs.
|
|
86
|
+
*
|
|
87
|
+
* Spelled once, and `lib/cli-commands.ts` must register it or the generated
|
|
88
|
+
* workflow invokes a command `bin/rungate.ts` will refuse — which is #675's
|
|
89
|
+
* defect, a documented interface with nothing behind it.
|
|
90
|
+
*/
|
|
91
|
+
export const AI_REVIEW_UNMEASURED_COMMAND = "record-ai-review-unmeasured";
|
|
92
|
+
|
|
93
|
+
/** `owner/name` of the repository whose ledger comments are being patched. */
|
|
94
|
+
export const AI_REVIEW_UNMEASURED_REPO_VAR = "AI_REVIEW_UNMEASURED_REPO";
|
|
95
|
+
|
|
96
|
+
/** The head commit of the run that just finished. */
|
|
97
|
+
export const AI_REVIEW_UNMEASURED_SHA_VAR = "AI_REVIEW_UNMEASURED_HEAD_SHA";
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* The step's `run:` body.
|
|
101
|
+
*
|
|
102
|
+
* Exported so `test/ai-review-unmeasured-workflow.test.ts` executes THIS
|
|
103
|
+
* text, rather than a paraphrase of it, against a planted ledger and a stub
|
|
104
|
+
* `gh`. A test that asserts on a string the job never runs is the shape
|
|
105
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` opens with.
|
|
106
|
+
*
|
|
107
|
+
* ## Every line of it is about one of two conflations
|
|
108
|
+
*
|
|
109
|
+
* **An absent sha is UNMEASURED, not "no rounds to classify".** A
|
|
110
|
+
* `workflow_run` payload with no `head_sha` is a reading that could not be
|
|
111
|
+
* taken. Exiting 0 silently here would report the same thing as a run that
|
|
112
|
+
* read forty rounds and found them all already recorded.
|
|
113
|
+
*
|
|
114
|
+
* **The recorder's own exit code is this step's.** It exits non-zero when it
|
|
115
|
+
* REFUSED a pull request — an unlocatable fence, a body that would not read
|
|
116
|
+
* back, a failed PATCH — and those are the cases where a round's reading was
|
|
117
|
+
* taken and then dropped, with the log now one day closer to expiry. A
|
|
118
|
+
* `continue-on-error` or a `|| true` here would convert each of them into a
|
|
119
|
+
* green check, which is this feature's own defect reintroduced in its
|
|
120
|
+
* delivery mechanism.
|
|
121
|
+
*
|
|
122
|
+
* Note what is NOT here: no filter on the finished run's conclusion. A
|
|
123
|
+
* declined run SUCCEEDS — the action exits zero on its own
|
|
124
|
+
* workflow-validation guard — so `if: failure()` would skip exactly the
|
|
125
|
+
* population #1455 is about, and `conclusion == 'success'` would admit it by
|
|
126
|
+
* accident rather than on purpose. The classifier reads the log; nothing
|
|
127
|
+
* upstream of it gets to pre-judge which runs are worth reading.
|
|
128
|
+
*/
|
|
129
|
+
export function buildRecordUnmeasuredScript(version: string): string {
|
|
130
|
+
return `set -u
|
|
131
|
+
if [ -z "\${${AI_REVIEW_UNMEASURED_SHA_VAR}}" ]; then
|
|
132
|
+
echo "::warning title=AI review unmeasured UNMEASURED::The workflow_run payload carried no head_sha, so no pull request could be resolved and no round was classified. This is UNMEASURED — not a run with nothing to classify. The two are the same green check from outside, which is the conflation this workflow exists to undo."
|
|
133
|
+
exit 0
|
|
134
|
+
fi
|
|
135
|
+
# The FULL log of each round's own run, never --log-failed: the skip line is
|
|
136
|
+
# emitted by a step that SUCCEEDS, so --log-failed returns 0 bytes on a
|
|
137
|
+
# declined run. Never the clock either. Both readings are measured in
|
|
138
|
+
# lib/ai-review-unmeasured.ts and both are wrong.
|
|
139
|
+
#
|
|
140
|
+
# --write, because a reading taken and not stored is a log fetched one day
|
|
141
|
+
# before it expired and thrown away.
|
|
142
|
+
bunx rungate@${version} ${AI_REVIEW_UNMEASURED_COMMAND} \\
|
|
143
|
+
--repo "\${${AI_REVIEW_UNMEASURED_REPO_VAR}}" \\
|
|
144
|
+
--head-sha "\${${AI_REVIEW_UNMEASURED_SHA_VAR}}" \\
|
|
145
|
+
--write
|
|
146
|
+
`;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export interface UnmeasuredWorkflowOptions {
|
|
150
|
+
/** The `runs-on:` value, already JSON-quoted by the caller. */
|
|
151
|
+
runsOn: string;
|
|
152
|
+
/** The pinned `oven-sh/setup-bun` action reference. */
|
|
153
|
+
setupBun: string;
|
|
154
|
+
/**
|
|
155
|
+
* The `with:` body of that step, at ten spaces.
|
|
156
|
+
*
|
|
157
|
+
* `setupBunWith` renders the project's single bun declaration and nothing
|
|
158
|
+
* else; the `- uses:` line around it is the caller's, exactly as it is for
|
|
159
|
+
* the other three generated workflows. Taking the composed block instead
|
|
160
|
+
* would put a second renderer of that declaration in the tree, which is
|
|
161
|
+
* the defect #622 removed.
|
|
162
|
+
*/
|
|
163
|
+
setupBunWith: string;
|
|
164
|
+
/** The published harness version the step runs through `bunx`. */
|
|
165
|
+
version: string;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* The whole `ai-review-unmeasured.yml` body.
|
|
170
|
+
*
|
|
171
|
+
* No `actions/checkout`. The step reads nothing out of the repository — it
|
|
172
|
+
* talks to the GitHub API about a repository it is told the name of — and a
|
|
173
|
+
* `workflow_run` workflow that checks out code is the shape that turns a
|
|
174
|
+
* fork's pull request into code execution with a write token.
|
|
175
|
+
*/
|
|
176
|
+
export function buildAiReviewUnmeasuredWorkflow(opts: UnmeasuredWorkflowOptions): string {
|
|
177
|
+
const script = buildRecordUnmeasuredScript(opts.version)
|
|
178
|
+
.trimEnd()
|
|
179
|
+
.split("\n")
|
|
180
|
+
.map(line => (line === "" ? "" : ` ${line}`))
|
|
181
|
+
.join("\n");
|
|
182
|
+
|
|
183
|
+
return `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
184
|
+
#
|
|
185
|
+
# WHICH KIND of unmeasured each unmeasured AI review round was (#1488).
|
|
186
|
+
#
|
|
187
|
+
# 48 of 117 rounds across the 45 most recent pull requests recorded
|
|
188
|
+
# \`findings: null\` — a round nobody read — and nothing said whether that was
|
|
189
|
+
# the action declining on its own workflow-validation guard (#1455), a run
|
|
190
|
+
# that reviewed and wrote no payload (#1478), or a payload that did not
|
|
191
|
+
# parse. Three facts that cost the same and are fixed differently, and a row
|
|
192
|
+
# that cannot tell them apart is a row nobody can act on.
|
|
193
|
+
#
|
|
194
|
+
# The evidence is the finished run's FULL job log, and it is only readable
|
|
195
|
+
# from OUTSIDE the run: the persist step that writes the round runs mid-job,
|
|
196
|
+
# and the Actions log endpoint refuses a job that is still running. Hence a
|
|
197
|
+
# second workflow on \`workflow_run: completed\` rather than a step.
|
|
198
|
+
#
|
|
199
|
+
# THIS WORKFLOW REPORTS NO STATUS TO THE PULL REQUEST. A \`workflow_run\`
|
|
200
|
+
# workflow cannot be a required check and cannot hang a merge queue, which is
|
|
201
|
+
# why — alone among the generated workflows — it declares no \`merge_group\`
|
|
202
|
+
# trigger. Do not add one: it would fire with no \`workflow_run\` context.
|
|
203
|
+
#
|
|
204
|
+
# IT WRITES, SO READ WHAT IT CAN REACH. The only write is a PATCH of the
|
|
205
|
+
# AI-review ledger comment on the pull request carrying the finished run's
|
|
206
|
+
# head commit. It checks out no code, which is what keeps a fork's pull
|
|
207
|
+
# request from reaching a write token through it.
|
|
208
|
+
name: AI Review Unmeasured
|
|
209
|
+
|
|
210
|
+
on:
|
|
211
|
+
workflow_run:
|
|
212
|
+
# The NAME of the producing workflow, which is the only thing
|
|
213
|
+
# \`workflow_run\` matches on. Generated from one constant shared with the
|
|
214
|
+
# file it names, because a subscription to a renamed workflow fires never
|
|
215
|
+
# and firing never looks exactly like finding nothing to classify.
|
|
216
|
+
workflows: ["${AI_REVIEW_WORKFLOW_NAME}"]
|
|
217
|
+
types: [completed]
|
|
218
|
+
|
|
219
|
+
permissions:
|
|
220
|
+
contents: read
|
|
221
|
+
# Read the finished run's full job log. The whole reading.
|
|
222
|
+
actions: read
|
|
223
|
+
# PATCH the findings ledger comment with the discriminator (#1486).
|
|
224
|
+
pull-requests: write
|
|
225
|
+
|
|
226
|
+
jobs:
|
|
227
|
+
${AI_REVIEW_UNMEASURED_JOB}:
|
|
228
|
+
runs-on: ${opts.runsOn}
|
|
229
|
+
steps:
|
|
230
|
+
- uses: ${opts.setupBun}
|
|
231
|
+
with:
|
|
232
|
+
${opts.setupBunWith}
|
|
233
|
+
- name: Record which kind of unmeasured each round was
|
|
234
|
+
env:
|
|
235
|
+
${AI_REVIEW_UNMEASURED_REPO_VAR}: \${{ github.repository }}
|
|
236
|
+
${AI_REVIEW_UNMEASURED_SHA_VAR}: \${{ github.event.workflow_run.head_sha }}
|
|
237
|
+
# The recorder shells out to \`gh\`. No secret is involved: the
|
|
238
|
+
# run's own token carries exactly the three permissions above.
|
|
239
|
+
GH_TOKEN: \${{ github.token }}
|
|
240
|
+
run: |
|
|
241
|
+
${script}
|
|
242
|
+
`;
|
|
243
|
+
}
|
|
@@ -156,6 +156,20 @@ export const OWNED_FILES: OwnedFile[] = [
|
|
|
156
156
|
customize: "Set `ci.vertex` in `.claude/rungate/config.json` to authenticate on Vertex with Workload Identity Federation; add your own jobs alongside the generated `ai-review` job",
|
|
157
157
|
avoid: "Don't edit the generated `ai-review` job",
|
|
158
158
|
},
|
|
159
|
+
{
|
|
160
|
+
// #1488. The `workflow_run: completed` half of the AI review: it runs
|
|
161
|
+
// the unmeasured classifier after the review job ends, which is the
|
|
162
|
+
// first moment that job's log is served. Declared the moment the
|
|
163
|
+
// generator learned to write it — the whole of #631's lesson one file
|
|
164
|
+
// over is that ownership has to travel with the bytes, and a workflow
|
|
165
|
+
// the generator writes and this list does not name is a consumer's hand
|
|
166
|
+
// edit overwritten in silence.
|
|
167
|
+
path: ".github/workflows/ai-review-unmeasured.yml",
|
|
168
|
+
strategy: "job-preserving",
|
|
169
|
+
servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
|
|
170
|
+
customize: "Set `ci.runner` in `.claude/rungate/config.json`; add your own jobs alongside the generated `record-unmeasured` job",
|
|
171
|
+
avoid: "Don't edit the generated `record-unmeasured` job, and don't give it a `merge_group` trigger — it reports no status to the pull request and cannot be a required check",
|
|
172
|
+
},
|
|
159
173
|
{
|
|
160
174
|
// `regenerate` until #655, and the declaration was never consulted:
|
|
161
175
|
// `generateAgentBriefsStep` called `writeFileSync` directly, so the row
|
package/lib/scaffold/steps.ts
CHANGED
|
@@ -12,6 +12,7 @@ import { readdirSorted } from "../readdir-sorted";
|
|
|
12
12
|
import { fileExtensions } from "../file-extensions";
|
|
13
13
|
import { join, basename, dirname, resolve, sep } from "path";
|
|
14
14
|
import { auditSpecs } from "../../scripts/audit-specs";
|
|
15
|
+
import { writeSpec } from "../write-spec";
|
|
15
16
|
import { generateAgentsMd as buildAgentsMdContent, generateScopedRules } from "../generators/agents-md";
|
|
16
17
|
import { HARNESS_PACKAGE, isHarnessItself } from "../harness-identity";
|
|
17
18
|
import { scanSpecs } from "../scanner";
|
|
@@ -43,6 +44,10 @@ import {
|
|
|
43
44
|
buildReviewRunStep,
|
|
44
45
|
vertexCiConfig,
|
|
45
46
|
} from "./ai-review-step";
|
|
47
|
+
import {
|
|
48
|
+
AI_REVIEW_WORKFLOW_NAME,
|
|
49
|
+
buildAiReviewUnmeasuredWorkflow,
|
|
50
|
+
} from "./ai-review-unmeasured-workflow";
|
|
46
51
|
import { CI_SUITE_FETCH_DEPTH, baseRefFetchDepth } from "../ci-history-depth";
|
|
47
52
|
import { CLAUDE_CODE_ACTION } from "../claude-code-action";
|
|
48
53
|
import { GOOGLE_AUTH_ACTION } from "../google-auth-action";
|
|
@@ -60,6 +65,7 @@ import {
|
|
|
60
65
|
import { healthPathIn } from "../liveness-contradiction";
|
|
61
66
|
import { localCalendarDay } from "../local-calendar-day";
|
|
62
67
|
import { decideRuleWrite } from "../rule-provenance";
|
|
68
|
+
import { rowDriftClause, ruleRowDrift } from "../rule-row-drift";
|
|
63
69
|
import { actionRef } from "../workflow-actions";
|
|
64
70
|
import { ciSetupStep } from "../ci-setup-step";
|
|
65
71
|
import { DEFAULT_PROFILE, isRuleIncluded, type ScaffoldProfile } from "./profiles";
|
|
@@ -586,9 +592,18 @@ export function generateAgentsMdContent(
|
|
|
586
592
|
if (decision.action === "preserve") {
|
|
587
593
|
// Reported, never resolved. A divergence the run silently fixed is the
|
|
588
594
|
// defect; a divergence named in the report is a decision for a human.
|
|
595
|
+
//
|
|
596
|
+
// Preservation is per-FILE and staleness is per-ROW (#1287), so the
|
|
597
|
+
// skip says which generated rows the file no longer reproduces. Without
|
|
598
|
+
// it one hand-edited row freezes every other row in the file and a
|
|
599
|
+
// consumer who upgraded to receive a correction never learns it did not
|
|
600
|
+
// arrive. See lib/rule-row-drift.ts for why the row is the unit, why
|
|
601
|
+
// #1148's per-file `generated-sha` discriminator cannot express this,
|
|
602
|
+
// and why this reports rather than rewrites.
|
|
603
|
+
const rows = rowDriftClause(ruleRowDrift(existing!, rule.content));
|
|
589
604
|
actions.push(
|
|
590
605
|
`PRESERVED: .claude/rules/${rule.filename} (${decision.reason}) — ` +
|
|
591
|
-
`generator output withheld; delete the file and re-run to accept it`,
|
|
606
|
+
`generator output withheld; ${rows}; delete the file and re-run to accept it`,
|
|
592
607
|
);
|
|
593
608
|
continue;
|
|
594
609
|
}
|
|
@@ -1676,8 +1691,27 @@ export function copySpecTemplateIfEmpty(specsDir: string, actions: string[]): vo
|
|
|
1676
1691
|
}
|
|
1677
1692
|
|
|
1678
1693
|
const template = readFileSync(templatePath, "utf-8");
|
|
1679
|
-
|
|
1680
|
-
|
|
1694
|
+
const destPath = join(specsDir, "SPEC-TEMPLATE.md");
|
|
1695
|
+
|
|
1696
|
+
// #1549: the emptiness test above excludes `SPEC-TEMPLATE.md` by name, so a
|
|
1697
|
+
// `specs/` holding ONLY that file reads as empty and we arrive here with the
|
|
1698
|
+
// consumer's own template already on disk. #1286 guarded eleven in-place
|
|
1699
|
+
// spec writers and missed this one, because its completeness check is built
|
|
1700
|
+
// from files that read and write the same path — and this writes a path it
|
|
1701
|
+
// never read. Ask who owns the bytes before replacing them.
|
|
1702
|
+
// #1552: the reading, the refusal line and the write are one call now.
|
|
1703
|
+
const existed = existsSync(destPath);
|
|
1704
|
+
const result = writeSpec(destPath, template, { label: "specs/SPEC-TEMPLATE.md" });
|
|
1705
|
+
if (!result.written) {
|
|
1706
|
+
actions.push(result.refusal!);
|
|
1707
|
+
return;
|
|
1708
|
+
}
|
|
1709
|
+
// #1549: the verb is a reading, not a label. `CREATED` for a file that was
|
|
1710
|
+
// already on disk tells a reader scanning the report for destructive
|
|
1711
|
+
// actions the opposite of what happened.
|
|
1712
|
+
actions.push(
|
|
1713
|
+
`${existed ? "UPDATED" : "CREATED"}: specs/SPEC-TEMPLATE.md (starter template)`,
|
|
1714
|
+
);
|
|
1681
1715
|
}
|
|
1682
1716
|
|
|
1683
1717
|
// ── tsconfig.json ──────────────────────────────────────────────
|
|
@@ -3918,10 +3952,24 @@ ${bunStep}
|
|
|
3918
3952
|
// test/ai-review-surface-census.test.ts compares the committed file
|
|
3919
3953
|
// against a FRESH generation — so the two orders are a byte difference
|
|
3920
3954
|
// that reads as a hand-edit. Measured: that is exactly how this was found.
|
|
3955
|
+
// `pull-requests: write` is #1168's second half: the findings ledger is an
|
|
3956
|
+
// upserted pull-request comment, and nothing else in this job writes one.
|
|
3957
|
+
//
|
|
3958
|
+
// It is APPENDED after `actions: read` for the merge reason above, and it
|
|
3959
|
+
// is the narrowest grant that can write a comment — `issues: write` would
|
|
3960
|
+
// also work and would additionally let this job edit issues, which it has
|
|
3961
|
+
// no reason to touch.
|
|
3962
|
+
//
|
|
3963
|
+
// On a FORK pull request GitHub hands this job a read-only token whatever
|
|
3964
|
+
// is written here, so the grant is inert exactly where the checked-out code
|
|
3965
|
+
// is untrusted. The ledger step reports that case rather than failing on
|
|
3966
|
+
// it. For a same-repo branch the author could already push to the
|
|
3967
|
+
// repository, so the grant adds no reach an attacker did not have.
|
|
3968
|
+
const ledgerPermission = ` # Upsert the findings ledger comment — the round history (#1168).\n pull-requests: write`;
|
|
3921
3969
|
const aiReviewPermissions =
|
|
3922
3970
|
vertex.config === null
|
|
3923
|
-
? `permissions:\n contents: read\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read`
|
|
3924
|
-
: `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read`;
|
|
3971
|
+
? `permissions:\n contents: read\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read\n${ledgerPermission}`
|
|
3972
|
+
: `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read\n${ledgerPermission}`;
|
|
3925
3973
|
|
|
3926
3974
|
const aiReviewYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
3927
3975
|
#
|
|
@@ -3942,12 +3990,32 @@ ${buildOutcomesHeader(vertex)}#
|
|
|
3942
3990
|
# credential exists anywhere on the runner (#677 AC-15). What this job holds
|
|
3943
3991
|
# as read from this consumer's config:
|
|
3944
3992
|
# ${vertex.reason}
|
|
3945
|
-
name:
|
|
3993
|
+
name: ${AI_REVIEW_WORKFLOW_NAME}
|
|
3946
3994
|
|
|
3947
3995
|
on:
|
|
3948
3996
|
# See the block comment in lib/scaffold/steps.ts: no branches: filter, and
|
|
3949
3997
|
# its absence hangs a merge queue silently rather than failing it (#867).
|
|
3950
3998
|
merge_group:
|
|
3999
|
+
# #1469. PROTECT-1 (lib/branch-protection.ts) refuses to recommend
|
|
4000
|
+
# required_status_checks.strict = false on a repository whose required
|
|
4001
|
+
# contexts do not run on push: to the default branch, and refuses
|
|
4002
|
+
# strict = true on a user-owned account because it serialises every PR.
|
|
4003
|
+
# A required ai-review that runs only on pull_request therefore has no
|
|
4004
|
+
# reading that clears, and this trigger is the refusal's own remedy.
|
|
4005
|
+
#
|
|
4006
|
+
# It does NOT review the commit. The review action throws
|
|
4007
|
+
# "Unsupported event type: push" before reading anything, exactly as it
|
|
4008
|
+
# does on merge_group, so every step that wants a pull request says it
|
|
4009
|
+
# had none and the report step annotates UNMEASURED and passes. What
|
|
4010
|
+
# push-CI buys here is the semantic-conflict net, and in this generated
|
|
4011
|
+
# set that is ci.yml's test job, which has had this trigger all along.
|
|
4012
|
+
#
|
|
4013
|
+
# The branch list is the consumer's own ci.branches, the same reading
|
|
4014
|
+
# ci.yml and gates.yml use. A literal here would be a second decider and
|
|
4015
|
+
# would be wrong on every repository whose default branch is not ours.
|
|
4016
|
+
push:
|
|
4017
|
+
branches:
|
|
4018
|
+
${branchList}
|
|
3951
4019
|
${AI_REVIEW_PULL_REQUEST_TRIGGER}
|
|
3952
4020
|
|
|
3953
4021
|
${aiReviewPermissions}
|
|
@@ -3963,6 +4031,8 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
|
|
|
3963
4031
|
auth: actionRef(GOOGLE_AUTH_ACTION),
|
|
3964
4032
|
review: actionRef(CLAUDE_CODE_ACTION),
|
|
3965
4033
|
setupBun: actionRef("oven-sh/setup-bun"),
|
|
4034
|
+
// #1307. The witness on the UNMEASURED route.
|
|
4035
|
+
uploadArtifact: actionRef("actions/upload-artifact"),
|
|
3966
4036
|
// The same single declaration the test and gates jobs resolve from
|
|
3967
4037
|
// (#622), at the indent this job's step bodies use.
|
|
3968
4038
|
setupBunWith: setupBunWith(declaredBunVersion(root), " "),
|
|
@@ -3980,6 +4050,21 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
|
|
|
3980
4050
|
harnessVersion(),
|
|
3981
4051
|
)}`;
|
|
3982
4052
|
|
|
4053
|
+
// #1488. The second AI-review workflow: `workflow_run: completed`, which is
|
|
4054
|
+
// the first moment the finished job's log is served. It is generated here
|
|
4055
|
+
// rather than in `lib/scaffold/ai-review-step.ts` because that module
|
|
4056
|
+
// builds the STEPS of the review job and this is a different file with a
|
|
4057
|
+
// different trigger — and because the one thing the two must agree on, the
|
|
4058
|
+
// producing workflow's `name:`, is a constant the subscriber owns.
|
|
4059
|
+
const aiReviewUnmeasuredYml = buildAiReviewUnmeasuredWorkflow({
|
|
4060
|
+
runsOn,
|
|
4061
|
+
setupBun: actionRef("oven-sh/setup-bun"),
|
|
4062
|
+
// The same `bunStep` the three jobs above render, at the same indent and
|
|
4063
|
+
// from the same single declaration (#622).
|
|
4064
|
+
setupBunWith: bunStep,
|
|
4065
|
+
version: harnessVersion(),
|
|
4066
|
+
});
|
|
4067
|
+
|
|
3983
4068
|
// Not `writeFileSync`. The harness owns the `test` and `gates` jobs; it does
|
|
3984
4069
|
// not own the file, and a consumer's own jobs have to survive the update
|
|
3985
4070
|
// that re-scaffolding IS. A refusal is recorded rather than thrown so that
|
|
@@ -3995,7 +4080,7 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
|
|
|
3995
4080
|
// lib/conformity.ts reads back, and the two are held together by
|
|
3996
4081
|
// test/ai-review-workflow.test.ts AC-1, which looks for the constant's
|
|
3997
4082
|
// filename in what this loop actually wrote.
|
|
3998
|
-
for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml]] as const) {
|
|
4083
|
+
for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml]] as const) {
|
|
3999
4084
|
const label = `.github/workflows/${name}`;
|
|
4000
4085
|
try {
|
|
4001
4086
|
// Keyed by FILE, and the lookup is here because this loop is the only
|
|
@@ -5188,9 +5273,15 @@ export function runAuditSpecsFix(root: string, actions: string[]): void {
|
|
|
5188
5273
|
actions.push(`KEPT: specs/${r.specFile} ${r.scId} — ${r.kept}`);
|
|
5189
5274
|
}
|
|
5190
5275
|
|
|
5191
|
-
|
|
5276
|
+
// #1286: a spec a generator owns is named here, individually, with the
|
|
5277
|
+
// reason. This is the path that edited a consumer's hash-pinned
|
|
5278
|
+
// `specs/POV-SPEC.md` under a `UPDATED:` line; a refusal it did not print
|
|
5279
|
+
// would be the same failure with the bytes left alone.
|
|
5280
|
+
for (const s of result.skipped) actions.push(s.message);
|
|
5281
|
+
|
|
5282
|
+
if (entries.length === 0 && result.skipped.length === 0) {
|
|
5192
5283
|
actions.push("SKIP: audit-specs (all SCs already matchable)");
|
|
5193
|
-
} else {
|
|
5284
|
+
} else if (entries.length > 0) {
|
|
5194
5285
|
actions.push(
|
|
5195
5286
|
`SKIP: audit-specs summary (rewrote ${rewritten.length} SCs, left ${kept.length} unmatched but intact)`,
|
|
5196
5287
|
);
|
package/lib/scratch-roots.ts
CHANGED
|
@@ -20,16 +20,52 @@
|
|
|
20
20
|
|
|
21
21
|
import { stripJsComments } from "./strip-js-comments";
|
|
22
22
|
|
|
23
|
+
/**
|
|
24
|
+
* The call that makes a directory unique by construction.
|
|
25
|
+
*
|
|
26
|
+
* ONE spelling, consulted by both questions the module asks: `DECL` builds
|
|
27
|
+
* its wrapped-form group from it, and `boundToMkdtemp` decides from it that
|
|
28
|
+
* an identifier names a unique directory rather than the checkout. A second
|
|
29
|
+
* spelling would be a second decider for one question, and the two would
|
|
30
|
+
* disagree the first time either moved —
|
|
31
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, fourth shape.
|
|
32
|
+
*/
|
|
33
|
+
const MKDTEMP_CALL = String.raw`mkdtempSync\s*\(\s*`;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Is this right-hand side ITSELF an `mkdtempSync(...)` call?
|
|
37
|
+
*
|
|
38
|
+
* Anchored at the start of the RHS, not a substring test, because the whole
|
|
39
|
+
* defect being fixed here is a substring test standing in for a structural
|
|
40
|
+
* question (#1482).
|
|
41
|
+
*/
|
|
42
|
+
function boundToMkdtemp(rhs: string): boolean {
|
|
43
|
+
return new RegExp(`^\\s*${MKDTEMP_CALL}`).test(rhs);
|
|
44
|
+
}
|
|
45
|
+
|
|
23
46
|
/**
|
|
24
47
|
* Identifiers bound to the repository root, per file.
|
|
25
48
|
*
|
|
26
49
|
* `join(tmpDir, ".claude")` is a fixed name under an ALREADY-UNIQUE root —
|
|
27
50
|
* the suffix is on the parent, which is just as good. Only a path rooted at
|
|
28
51
|
* the shared checkout can collide, so the root is the thing to look at.
|
|
52
|
+
*
|
|
53
|
+
* An `mkdtempSync(...)` is excluded whatever its argument contains (#1482).
|
|
54
|
+
* The test below is whether the RHS MENTIONS a root spelling, and
|
|
55
|
+
* `mkdtempSync(join(import.meta.dir, ".x-"))` mentions one — so the
|
|
56
|
+
* identifier naming a directory that is unique by construction was being
|
|
57
|
+
* added to the set of identifiers bound to the shared checkout, which
|
|
58
|
+
* inverts the paragraph above. `fixedScratchRoots` then flagged a fixed name
|
|
59
|
+
* under it as shared, and `uniqueScratchPrefixes` put a prefix planted
|
|
60
|
+
* INSIDE it into a deletion allowlist that only ever reads the repo root.
|
|
61
|
+
*
|
|
62
|
+
* The exclusion is the safe direction. A root this misses costs a prefix
|
|
63
|
+
* nobody swept; a root it invents feeds a name into a recursive delete.
|
|
29
64
|
*/
|
|
30
65
|
export function repoRootIdents(src: string): Set<string> {
|
|
31
66
|
const idents = new Set<string>();
|
|
32
67
|
for (const m of src.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^;\n]+)/g)) {
|
|
68
|
+
if (boundToMkdtemp(m[2]!)) continue;
|
|
33
69
|
if (/import\.meta\.dir|process\.cwd\(\)/.test(m[2]!)) idents.add(m[1]!);
|
|
34
70
|
}
|
|
35
71
|
return idents;
|
|
@@ -63,7 +99,52 @@ export function repoRootIdents(src: string): Set<string> {
|
|
|
63
99
|
* which hold the equivalence element by element against a frozen copy of the
|
|
64
100
|
* old parse.
|
|
65
101
|
*/
|
|
66
|
-
|
|
102
|
+
/**
|
|
103
|
+
* The root spellings that ARE the shared checkout, with no name in between
|
|
104
|
+
* (#1473).
|
|
105
|
+
*
|
|
106
|
+
* `repoRootIdents` finds names BOUND to one of these. It cannot find a use
|
|
107
|
+
* that never bound a name:
|
|
108
|
+
*
|
|
109
|
+
* const tmpDir = join(import.meta.dir, ".tmp-scan-test"); // invisible
|
|
110
|
+
* const ROOT = join(import.meta.dir, ".."); // seen
|
|
111
|
+
* const tmpDir = join(ROOT, ".tmp-scan-test"); // via ROOT
|
|
112
|
+
*
|
|
113
|
+
* The two are the same directory and the same collision. The first escaped
|
|
114
|
+
* for as long as the parse required `join`'s first argument to be an
|
|
115
|
+
* identifier — `test/scan-stale-issues.test.ts` sat in the tree writing a
|
|
116
|
+
* fixed `.tmp-scan-test` under `test/`, and `fixedScratchRoots` returned
|
|
117
|
+
* `[]` for it. Measured over 531 files, the inline form appears three times
|
|
118
|
+
* and that was the only mutating one.
|
|
119
|
+
*
|
|
120
|
+
* Kept as a named constant rather than inlined into `DECL` because
|
|
121
|
+
* `isInlineRoot` has to recognise exactly the same set: an alternation that
|
|
122
|
+
* matched a spelling the predicate then failed to classify would drop the
|
|
123
|
+
* declaration on the floor, which is the quiet direction.
|
|
124
|
+
*/
|
|
125
|
+
const INLINE_ROOTS = ["import\\.meta\\.dir", "process\\.cwd\\(\\)"] as const;
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Is this capture an inline root spelling rather than an identifier?
|
|
129
|
+
*
|
|
130
|
+
* A root spelled inline needs no `repoRootIdents` lookup — it does not name
|
|
131
|
+
* the checkout, it IS the checkout. Deriving the test from `INLINE_ROOTS`
|
|
132
|
+
* means the matcher and the classifier cannot disagree about the set.
|
|
133
|
+
*/
|
|
134
|
+
function isInlineRoot(captured: string): boolean {
|
|
135
|
+
return INLINE_ROOTS.some(r => new RegExp(`^${r}$`).test(captured));
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const DECL = new RegExp(
|
|
139
|
+
String.raw`([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(` + MKDTEMP_CALL + String.raw`)?join\(\s*` +
|
|
140
|
+
// The inline spellings first. `import` would otherwise be consumed by the
|
|
141
|
+
// identifier branch, which then fails on the `.` and backtracks — correct
|
|
142
|
+
// but only by accident, and it costs an attempt at every `import` in the
|
|
143
|
+
// file.
|
|
144
|
+
`(${INLINE_ROOTS.join("|")}|[A-Za-z_][A-Za-z0-9_]*)` +
|
|
145
|
+
String.raw`\s*,\s*"(\.[^"]*)"`,
|
|
146
|
+
"g",
|
|
147
|
+
);
|
|
67
148
|
|
|
68
149
|
/**
|
|
69
150
|
* The same pattern, un-anchored and non-global, used only to decide whether
|
|
@@ -105,7 +186,9 @@ export function fixedScratchRoots(source: string): string[] {
|
|
|
105
186
|
for (const m of src.matchAll(new RegExp(DECL.source, "g"))) {
|
|
106
187
|
const [, name, wrapped, rootIdent, literal] = m;
|
|
107
188
|
if (wrapped) continue; // mkdtempSync — unique per run, which is the fix
|
|
108
|
-
|
|
189
|
+
// An inline root IS the checkout and binds no name, so there is nothing
|
|
190
|
+
// for `repoRootIdents` to have found (#1473).
|
|
191
|
+
if (!isInlineRoot(rootIdent!) && !roots.has(rootIdent!)) continue; // already under a unique root
|
|
109
192
|
if (isNavigation(literal!)) continue;
|
|
110
193
|
// Only a directory this suite CREATES or DELETES is scratch. One it merely
|
|
111
194
|
// reads is configuration, and renaming it per run would break the read.
|
|
@@ -131,7 +214,14 @@ export function uniqueScratchPrefixes(source: string): string[] {
|
|
|
131
214
|
for (const m of src.matchAll(new RegExp(DECL.source, "g"))) {
|
|
132
215
|
const [, , wrapped, rootIdent, literal] = m;
|
|
133
216
|
if (!wrapped) continue; // a fixed path is the other function's subject
|
|
134
|
-
|
|
217
|
+
// #1473, and this is the direction that needs justifying: widening a
|
|
218
|
+
// parse that feeds a DELETION allowlist. It adds a prefix only for a
|
|
219
|
+
// genuine `mkdtempSync(join(import.meta.dir, "<prefix>"))`, which is a
|
|
220
|
+
// directory this tree really does plant and really should sweep. Measured
|
|
221
|
+
// over test/ at the time of the change: zero such declarations, so the
|
|
222
|
+
// allowlist is byte-identical. `test/scratch-cleanup.test.ts` holds that
|
|
223
|
+
// against the frozen pre-#793 reference, element by element.
|
|
224
|
+
if (!isInlineRoot(rootIdent!) && !roots.has(rootIdent!)) continue;
|
|
135
225
|
if (isNavigation(literal!)) continue;
|
|
136
226
|
if (!out.includes(literal!)) out.push(literal!);
|
|
137
227
|
}
|
package/lib/spec-updater.ts
CHANGED
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
* replaces ACCEPTED status with SHIPPED + issue number.
|
|
5
5
|
* Project-agnostic: never hardcodes any specific spec filename.
|
|
6
6
|
*/
|
|
7
|
-
import { readFileSync,
|
|
7
|
+
import { readFileSync, existsSync } from "fs";
|
|
8
|
+
import { skipLine } from "./derived-spec";
|
|
9
|
+
import { maySpecBeWritten, writeSpec } from "./write-spec";
|
|
8
10
|
|
|
9
11
|
export interface SpecUpdateInput {
|
|
10
12
|
goalRecord: {
|
|
@@ -79,8 +81,26 @@ export async function updateSpecStatus(input: SpecUpdateInput): Promise<SpecUpda
|
|
|
79
81
|
}
|
|
80
82
|
}
|
|
81
83
|
|
|
84
|
+
// #1286: marking a decision row SHIPPED is an in-place spec edit. On a
|
|
85
|
+
// spec a generator owns it is discarded at the next regeneration, after
|
|
86
|
+
// breaking whatever pins the file.
|
|
87
|
+
// #1552: asked early because the caller's `skipped`/`reason` fields are
|
|
88
|
+
// part of this function's contract, then asked again by `writeSpec`. Two
|
|
89
|
+
// consults of one decider — `mayWrite` — not two deciders.
|
|
90
|
+
const early = maySpecBeWritten(content);
|
|
91
|
+
if (rowsUpdated > 0 && !early.allowed) {
|
|
92
|
+
console.warn(skipLine(specPath, early.reading));
|
|
93
|
+
return {
|
|
94
|
+
updated: false,
|
|
95
|
+
skipped: true,
|
|
96
|
+
specPath,
|
|
97
|
+
rowsUpdated: 0,
|
|
98
|
+
reason: skipLine(specPath, early.reading),
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
82
102
|
if (rowsUpdated > 0) {
|
|
83
|
-
|
|
103
|
+
writeSpec(specPath, content);
|
|
84
104
|
}
|
|
85
105
|
|
|
86
106
|
return {
|