rungate 0.6.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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +81 -16
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-id-cross-tree.ts +19 -7
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +241 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Can this module write to the filesystem? (#968, hardening #323 SC-6.)
|
|
3
|
+
*
|
|
4
|
+
* ## Why this exists
|
|
5
|
+
*
|
|
6
|
+
* `test/scratch-paths-unique.test.ts` excludes itself from its own scan,
|
|
7
|
+
* because its negative fixtures are source text and the detector reads its
|
|
8
|
+
* own test data as violations. An unchecked exclusion is how an exemption
|
|
9
|
+
* becomes a hole, so the exclusion is paired with a case asserting the file
|
|
10
|
+
* creates nothing. That case was:
|
|
11
|
+
*
|
|
12
|
+
* ```ts
|
|
13
|
+
* const fsImport = /import\s*\{([^}]*)\}\s*from\s*"fs";/.exec(self);
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* `exec` returns the FIRST match. MEASURED by mutating the real file and
|
|
17
|
+
* running it: adding `import { mkdirSync } from "fs";` as a SECOND import
|
|
18
|
+
* leaves the suite at 8 pass / 0 fail, and so does
|
|
19
|
+
* `import { mkdirSync } from "node:fs";`. The file gains a write primitive
|
|
20
|
+
* and the case that exists to notice stays green.
|
|
21
|
+
*
|
|
22
|
+
* One claim in #968 did NOT reproduce and is recorded here so it is not
|
|
23
|
+
* re-fixed: the old check does not fail open. Replacing the braced import
|
|
24
|
+
* with `import * as fs from "fs"` makes `exec` return null, and the
|
|
25
|
+
* `.not.toBeNull()` line goes red — 1 fail, measured. The defect is the first
|
|
26
|
+
* match, not the missing match.
|
|
27
|
+
*
|
|
28
|
+
* ## Capability, not use
|
|
29
|
+
*
|
|
30
|
+
* This reports what the module CAN do, not what it does. An imported but
|
|
31
|
+
* uncalled `mkdirSync` is reported, deliberately: the exclusion it guards is
|
|
32
|
+
* about what the file could hide, and "imported but currently unused" is one
|
|
33
|
+
* edit away from used. That is also what the regex it replaces did, so the
|
|
34
|
+
* false-positive surface is unchanged on that axis.
|
|
35
|
+
*
|
|
36
|
+
* ## Why an AST
|
|
37
|
+
*
|
|
38
|
+
* The file being checked is full of `mkdtempSync(` and `rmSync(` as STRING
|
|
39
|
+
* DATA — its own negative fixtures. A source-text count reads them as calls;
|
|
40
|
+
* the old check sidestepped that by reading only the import list, which is
|
|
41
|
+
* what made it blind to the second import. In an AST a string is a `Literal`
|
|
42
|
+
* and a call is a `CallExpression`, so the detector can read both the imports
|
|
43
|
+
* and the calls without its fixtures lying to it.
|
|
44
|
+
*
|
|
45
|
+
* `null` means the source did not parse — a REFUSAL, distinct from `[]`.
|
|
46
|
+
*
|
|
47
|
+
* ## WHAT THIS DOES NOT COVER (stated, because an unstated boundary reads as
|
|
48
|
+
* coverage, and a clean report from an incomplete detector is worse than no
|
|
49
|
+
* detector — #968's own thesis)
|
|
50
|
+
*
|
|
51
|
+
* MEASURED against the current implementation, each of these returns `[]`:
|
|
52
|
+
*
|
|
53
|
+
* - **An indirection through a variable.** `const w = mkdirSync` after a
|
|
54
|
+
* read-only import, `const m = await import("fs"); m.mkdirSync(…)`, or a
|
|
55
|
+
* write primitive received as a function argument. Only bindings created
|
|
56
|
+
* by an import statement, `require` or `Bun.*` are read.
|
|
57
|
+
* - **A write primitive re-exported by a local module.** `import { write }
|
|
58
|
+
* from "./helpers"` is not an fs module and is not reported, by design —
|
|
59
|
+
* the alternative is following the import graph, which this is not.
|
|
60
|
+
* - **`process.binding`, `Deno.*`, raw syscalls, and native addons.**
|
|
61
|
+
* - **A write performed by code this module merely CALLS.** The reading is
|
|
62
|
+
* per-module, not transitive.
|
|
63
|
+
*
|
|
64
|
+
* What IS covered, and measured: named/namespace/default imports from `fs`,
|
|
65
|
+
* `node:fs`, `fs/promises`, `node:fs/promises`; `require()` and dynamic
|
|
66
|
+
* `import()` of those; `child_process` and `node:child_process`; and
|
|
67
|
+
* `Bun.write`, `Bun.$`, `Bun.spawn`, `Bun.spawnSync`.
|
|
68
|
+
*
|
|
69
|
+
* The consumer that matters — `test/scratch-paths-unique.test.ts` — holds
|
|
70
|
+
* none of the uncovered forms, and the covered set includes every form that
|
|
71
|
+
* file could plausibly acquire. The gap is bounded by the thing it guards
|
|
72
|
+
* rather than argued away.
|
|
73
|
+
*/
|
|
74
|
+
|
|
75
|
+
import { type AstNode, calleeRoot, parseTsModule, walkNodes } from "./ts-ast";
|
|
76
|
+
|
|
77
|
+
/** Module specifiers that resolve to node's filesystem API. */
|
|
78
|
+
const FS_MODULES = new Set(["fs", "node:fs", "fs/promises", "node:fs/promises"]);
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Named exports of `fs` that CANNOT modify the filesystem. Everything else
|
|
82
|
+
* an fs module exports is treated as a write capability.
|
|
83
|
+
*
|
|
84
|
+
* ## The ratchet direction, which is the whole point of this list
|
|
85
|
+
*
|
|
86
|
+
* This was an allowlist of write names, and an allowlist has its default
|
|
87
|
+
* pointing the wrong way: every export node adds in future arrives
|
|
88
|
+
* classified as safe, silently, and the detector reports clean on it. The
|
|
89
|
+
* list was already five short — MEASURED on the allowlist version, all of
|
|
90
|
+
* `link`, `chmod`, `utimes`, `writev` and `ftruncate` returned `[]`.
|
|
91
|
+
*
|
|
92
|
+
* Inverted, an unknown name is a write. A name on THIS list is a name
|
|
93
|
+
* somebody considered and classified, which is the property an exemption
|
|
94
|
+
* list has and an allowlist does not: naming what is exempt is evidence the
|
|
95
|
+
* entry was looked at, naming what is safe is not.
|
|
96
|
+
*
|
|
97
|
+
* The cost of the inversion is false positives on read-only exports not
|
|
98
|
+
* listed here, and it is measured rather than asserted — see the census in
|
|
99
|
+
* the PR and the over-report cases in
|
|
100
|
+
* `test/fs-write-capabilities.test.ts`. `readFileSync` and `readdirSync` are
|
|
101
|
+
* how the detector's own consumer does its job and must not be refused.
|
|
102
|
+
*/
|
|
103
|
+
const FS_READ_ONLY_NAMES = new Set([
|
|
104
|
+
"access", "accessSync",
|
|
105
|
+
"createReadStream",
|
|
106
|
+
"exists", "existsSync",
|
|
107
|
+
"lstat", "lstatSync",
|
|
108
|
+
"opendir", "opendirSync",
|
|
109
|
+
"readFile", "readFileSync",
|
|
110
|
+
"readdir", "readdirSync",
|
|
111
|
+
"readlink", "readlinkSync",
|
|
112
|
+
"realpath", "realpathSync",
|
|
113
|
+
"stat", "statSync",
|
|
114
|
+
"statfs", "statfsSync",
|
|
115
|
+
"watch", "watchFile",
|
|
116
|
+
// Added after the inversion's census over 667 files flagged them. Both are
|
|
117
|
+
// genuinely read-only and were the ONLY false positives the inversion
|
|
118
|
+
// introduced: `glob` enumerates, `close` releases a descriptor. They are
|
|
119
|
+
// listed rather than quietly tolerated, which is exactly the property the
|
|
120
|
+
// inverted list is for — a name here is a name somebody classified.
|
|
121
|
+
"glob", "globSync",
|
|
122
|
+
"close", "closeSync",
|
|
123
|
+
"fstat", "fstatSync",
|
|
124
|
+
// Type-only and constant exports, which carry no capability at all.
|
|
125
|
+
"constants", "Dirent", "Dir", "Stats", "promises",
|
|
126
|
+
]);
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Modules whose exports can write without touching `fs` — a shell or a
|
|
130
|
+
* spawn is a write capability however it is spelled.
|
|
131
|
+
*/
|
|
132
|
+
const PROCESS_MODULES = new Set([
|
|
133
|
+
"child_process",
|
|
134
|
+
"node:child_process",
|
|
135
|
+
"bun",
|
|
136
|
+
]);
|
|
137
|
+
|
|
138
|
+
function literalString(node: unknown): string | null {
|
|
139
|
+
const n = node as AstNode | undefined;
|
|
140
|
+
if (n?.type === "Literal" && typeof n.value === "string") return n.value;
|
|
141
|
+
return null;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function isFsModule(spec: string | null): boolean {
|
|
145
|
+
return spec !== null && FS_MODULES.has(spec);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function isProcessModule(spec: string | null): boolean {
|
|
149
|
+
return spec !== null && PROCESS_MODULES.has(spec);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Every filesystem-write capability `source` holds, as human sentences, in
|
|
154
|
+
* document order. Empty means the module cannot write. `null` means the
|
|
155
|
+
* source did not parse.
|
|
156
|
+
*/
|
|
157
|
+
export function fsWriteCapabilities(source: string): string[] | null {
|
|
158
|
+
const parsed = parseTsModule(source);
|
|
159
|
+
if (parsed === null) return null;
|
|
160
|
+
|
|
161
|
+
const out: string[] = [];
|
|
162
|
+
for (const node of walkNodes(parsed.tree)) {
|
|
163
|
+
if (node.type === "ImportDeclaration") {
|
|
164
|
+
const spec = literalString(node.source);
|
|
165
|
+
if (isProcessModule(spec)) {
|
|
166
|
+
out.push(`"${spec}" is imported, and a spawned process can write anything`);
|
|
167
|
+
continue;
|
|
168
|
+
}
|
|
169
|
+
if (!isFsModule(spec)) continue;
|
|
170
|
+
for (const s of (node.specifiers ?? []) as AstNode[]) {
|
|
171
|
+
// A namespace or default binding carries the WHOLE module, so every
|
|
172
|
+
// write primitive comes with it whether or not it is named here.
|
|
173
|
+
// Reported on the BINDING rather than on `fs.writeFileSync(…)` member
|
|
174
|
+
// access: the binding is the capability, and tracking member access
|
|
175
|
+
// would be a narrower reading that an indirection defeats.
|
|
176
|
+
if (s.type === "ImportNamespaceSpecifier" || s.type === "ImportDefaultSpecifier") {
|
|
177
|
+
out.push(`the whole of "${spec}" is bound as \`${(s.local as AstNode).name}\``);
|
|
178
|
+
continue;
|
|
179
|
+
}
|
|
180
|
+
const imported = (s.imported as AstNode | undefined)?.name;
|
|
181
|
+
// INVERTED (#968 review): anything not known to be read-only is a
|
|
182
|
+
// write. An unknown export defaults to reported, not to safe.
|
|
183
|
+
if (typeof imported === "string" && !FS_READ_ONLY_NAMES.has(imported)) {
|
|
184
|
+
out.push(`\`${imported}\` is imported from "${spec}" and is not a known read-only export`);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
continue;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
if (node.type === "ImportExpression") {
|
|
191
|
+
const spec = literalString(node.source);
|
|
192
|
+
if (isFsModule(spec)) out.push(`"${spec}" is imported dynamically`);
|
|
193
|
+
else if (isProcessModule(spec)) out.push(`"${spec}" is imported dynamically`);
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// `Bun.$\`…\`` is a tagged template, not a call. Checked separately or it
|
|
198
|
+
// is the one shell spelling this detector cannot see — the exact shape of
|
|
199
|
+
// defect #968 is about.
|
|
200
|
+
if (node.type === "TaggedTemplateExpression") {
|
|
201
|
+
const tag = node.tag as AstNode | undefined;
|
|
202
|
+
if (tag && calleeRoot(tag) === "Bun") {
|
|
203
|
+
const text = parsed.js.slice(tag.start, tag.end);
|
|
204
|
+
if (/^Bun\s*\.\s*\$$/.test(text)) out.push(`\`${text}\` can write without importing fs`);
|
|
205
|
+
}
|
|
206
|
+
continue;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
if (node.type !== "CallExpression") continue;
|
|
210
|
+
const args = (node.arguments ?? []) as AstNode[];
|
|
211
|
+
|
|
212
|
+
// `require("fs")` — the whole module, same as a namespace import.
|
|
213
|
+
if ((node.callee as AstNode)?.type === "Identifier" && (node.callee as AstNode).name === "require") {
|
|
214
|
+
const spec = literalString(args[0]);
|
|
215
|
+
if (isFsModule(spec) || isProcessModule(spec)) out.push(`"${spec}" is loaded with require()`);
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// Bun's own writers and spawners, which import nothing and so are
|
|
220
|
+
// invisible to any import-list check. `Bun.$` is reported even though a
|
|
221
|
+
// read-only shell call writes nothing: a shell is a write capability,
|
|
222
|
+
// and the cost of over-reporting it is named in the caller.
|
|
223
|
+
const callee = node.callee as AstNode | undefined;
|
|
224
|
+
if (callee && calleeRoot(callee) === "Bun") {
|
|
225
|
+
const text = parsed.js.slice(callee.start, callee.end);
|
|
226
|
+
if (/^Bun\s*\.\s*(write|\$|spawn|spawnSync)$/.test(text)) {
|
|
227
|
+
out.push(`\`${text}\` can write without importing fs`);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
return out;
|
|
232
|
+
}
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One runner buffer, split into the runs it actually holds (#737).
|
|
3
|
+
*
|
|
4
|
+
* A LEAF module, in the shape `lib/git-dates.ts` established (#508): one
|
|
5
|
+
* exported reading, no relative imports, so there is exactly one thing to
|
|
6
|
+
* mutate and every consumer names the same rule.
|
|
7
|
+
*
|
|
8
|
+
* ## Why this exists
|
|
9
|
+
*
|
|
10
|
+
* `parseGateResults` read one buffer two ways. The summary reading collected
|
|
11
|
+
* every `N pass` / `N fail` line and took the LAST — something nobody writes
|
|
12
|
+
* unless they know the buffer can hold more than one run. Three lines later
|
|
13
|
+
* `parseTestResults(testOutput)` was handed the whole buffer with no scoping
|
|
14
|
+
* at all, and pushed a result for every `(fail)` marker anywhere in it.
|
|
15
|
+
*
|
|
16
|
+
* On `main` at `71e3f413`, run `39325676895`:
|
|
17
|
+
*
|
|
18
|
+
* Test results: 158 pass, 1 fail, 1 warn
|
|
19
|
+
* BATCH DIAGNOSIS: 2 failures — fix all before re-running
|
|
20
|
+
* AC/Evidence (2): brief-ac-alignment: ..., brief-ac-alignment: ...
|
|
21
|
+
* Gate verify: FAIL (attempt 2)
|
|
22
|
+
*
|
|
23
|
+
* One check, named twice, counted as one. `1 fail` is attempt 2's summary;
|
|
24
|
+
* `2 failures` is one check failing in both attempts. Two deciders for "how
|
|
25
|
+
* many checks failed" that agree on every single-run output — which is every
|
|
26
|
+
* output anyone had looked at — and diverge only on a retry
|
|
27
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
|
|
28
|
+
*
|
|
29
|
+
* **And the disagreement was printed.** Those two numbers appeared eleven
|
|
30
|
+
* lines apart in every retried gate run this project has ever produced, and
|
|
31
|
+
* nobody read them as contradicting each other, because each is individually
|
|
32
|
+
* believable. #700 was being diagnosed off the corrupted one.
|
|
33
|
+
*
|
|
34
|
+
* ## The semantics, decided rather than fallen into (#737 SC-5)
|
|
35
|
+
*
|
|
36
|
+
* **Last attempt wins.** A retry exists precisely so the later attempt is the
|
|
37
|
+
* verdict: the branch moved, and attempt 1's failures describe a tree that
|
|
38
|
+
* has been superseded. Reporting them under attempt 2's heading sends an
|
|
39
|
+
* operator to reasons that may already be fixed.
|
|
40
|
+
*
|
|
41
|
+
* The alternative — accumulate every attempt — was rejected because it makes
|
|
42
|
+
* a gate that eventually passed still report failures, and there is no way to
|
|
43
|
+
* tell those from failures that are still live.
|
|
44
|
+
*
|
|
45
|
+
* This is also written down in `specs/GATE-CONTRACTS-SPEC.md`, because a
|
|
46
|
+
* parser is a bad place to learn what a retry means.
|
|
47
|
+
*
|
|
48
|
+
* ## Why an absent final summary is UNMEASURED and not an earlier run's number
|
|
49
|
+
*
|
|
50
|
+
* #469's shape, which `lib/suite-run-reading.ts` already refuses: a run that
|
|
51
|
+
* produced no summary did not report zero failures, it reported nothing.
|
|
52
|
+
* Falling back to the previous run's numbers is *Silent Default
|
|
53
|
+
* Substitution* — `0`, `{}`, `null` and silence are indistinguishable from
|
|
54
|
+
* success, and the pre-#737 code did exactly that by taking the last match
|
|
55
|
+
* in the whole buffer regardless of which run it came from.
|
|
56
|
+
*/
|
|
57
|
+
|
|
58
|
+
/** Bun prints this once per invocation; it is the only run boundary available. */
|
|
59
|
+
const RUN_BANNER = /^bun test v.*$/gm;
|
|
60
|
+
|
|
61
|
+
const PASS_LINE = /^\s*(\d+)\s+pass\s*$/gm;
|
|
62
|
+
const FAIL_LINE = /^\s*(\d+)\s+fail\s*$/gm;
|
|
63
|
+
|
|
64
|
+
export interface RunSummary {
|
|
65
|
+
pass: number;
|
|
66
|
+
fail: number;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export interface GateRun {
|
|
70
|
+
/** 0-based position in the buffer. */
|
|
71
|
+
index: number;
|
|
72
|
+
/** This run's slice of the buffer, verbatim. Concatenated, the runs ARE the buffer. */
|
|
73
|
+
text: string;
|
|
74
|
+
/** The run's own summary, or null when it printed none. */
|
|
75
|
+
summary: RunSummary | null;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export interface GateBufferReading {
|
|
79
|
+
/** The one discriminator. Everything else is a projection of `runs`. */
|
|
80
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
81
|
+
unmeasuredReasons: string[];
|
|
82
|
+
runs: GateRun[];
|
|
83
|
+
/**
|
|
84
|
+
* The run whose verdict counts — the last one. `null` under an UNMEASURED
|
|
85
|
+
* reading, so a caller cannot read numbers off a buffer that has none.
|
|
86
|
+
*/
|
|
87
|
+
verdict: GateRun | null;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function summaryOf(text: string): RunSummary | null {
|
|
91
|
+
// Last within THIS run: bun prints one summary per invocation, but a
|
|
92
|
+
// nested runner or a wrapper can emit more, and the final one is the
|
|
93
|
+
// run's own. Scoped to the slice, never to the document.
|
|
94
|
+
const passes = [...text.matchAll(PASS_LINE)];
|
|
95
|
+
const fails = [...text.matchAll(FAIL_LINE)];
|
|
96
|
+
if (passes.length === 0 && fails.length === 0) return null;
|
|
97
|
+
return {
|
|
98
|
+
pass: passes.length > 0 ? parseInt(passes[passes.length - 1][1], 10) : 0,
|
|
99
|
+
fail: fails.length > 0 ? parseInt(fails[fails.length - 1][1], 10) : 0,
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Split a runner buffer into runs, and say which one is the verdict.
|
|
105
|
+
*
|
|
106
|
+
* The ONE binding. `fails`, `passes` and the per-check results are all
|
|
107
|
+
* derived from this split by `parseGateResults`, so the two readings cannot
|
|
108
|
+
* be scoped differently again — which was the whole defect.
|
|
109
|
+
*
|
|
110
|
+
* Text before the first banner belongs to the first run, so for a buffer
|
|
111
|
+
* with one run the slice is the buffer byte for byte. That is asserted
|
|
112
|
+
* rather than promised (#737 SC-6): this change has to be provably confined
|
|
113
|
+
* to the multi-run case.
|
|
114
|
+
*/
|
|
115
|
+
export function splitGateRuns(buffer: string): GateBufferReading {
|
|
116
|
+
const starts = [...buffer.matchAll(RUN_BANNER)].map(m => m.index!);
|
|
117
|
+
// Run 0 starts at byte 0 whether or not a banner does, so a preamble
|
|
118
|
+
// belongs to the first run rather than becoming a run of its own. Only
|
|
119
|
+
// the SECOND banner onwards opens a new run.
|
|
120
|
+
const bounds = [0, ...starts.slice(1)];
|
|
121
|
+
|
|
122
|
+
const runs: GateRun[] = bounds.map((start, i) => {
|
|
123
|
+
const end = i + 1 < bounds.length ? bounds[i + 1] : buffer.length;
|
|
124
|
+
const text = buffer.slice(start, end);
|
|
125
|
+
return { index: i, text, summary: summaryOf(text) };
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
const reasons: string[] = [];
|
|
129
|
+
// An empty buffer agrees with every claim. Said first, because the
|
|
130
|
+
// summary check below cannot distinguish "no runs" from "one clean run".
|
|
131
|
+
if (buffer.trim() === "") {
|
|
132
|
+
reasons.push("the runner produced no output at all, so no run can be read from it");
|
|
133
|
+
} else if (runs[runs.length - 1].summary === null) {
|
|
134
|
+
reasons.push(
|
|
135
|
+
`the last of ${runs.length} run(s) in the buffer printed no summary line, so its ` +
|
|
136
|
+
`pass/fail counts are unknown. Taking an earlier run's numbers would report a ` +
|
|
137
|
+
`superseded attempt as this one's result (#469).`,
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
return {
|
|
142
|
+
reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
|
|
143
|
+
unmeasuredReasons: reasons,
|
|
144
|
+
runs,
|
|
145
|
+
verdict: reasons.length === 0 ? runs[runs.length - 1] : null,
|
|
146
|
+
};
|
|
147
|
+
}
|
|
@@ -14,6 +14,7 @@ import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
|
|
|
14
14
|
import { isHarnessItself } from "../harness-identity";
|
|
15
15
|
import { typecheckDecision } from "../typescript-project";
|
|
16
16
|
import { localCalendarDay } from "../local-calendar-day";
|
|
17
|
+
import { resolveShipPolicy, shipWorkflowRule } from "../ship-mode";
|
|
17
18
|
|
|
18
19
|
/**
|
|
19
20
|
* Build the AGENTS.md frontmatter block.
|
|
@@ -45,8 +46,47 @@ export function existingFrontmatter(root: string): Record<string, string> {
|
|
|
45
46
|
return existing;
|
|
46
47
|
}
|
|
47
48
|
|
|
48
|
-
|
|
49
|
-
|
|
49
|
+
/**
|
|
50
|
+
* The committed AGENTS.md with its frontmatter block removed (#827).
|
|
51
|
+
*
|
|
52
|
+
* `null` means there is nothing to compare against — no file, or a file with
|
|
53
|
+
* no frontmatter block, which is a shape this generator has never written.
|
|
54
|
+
* Null and `""` are different facts and the caller must not conflate them:
|
|
55
|
+
* an absent file has no `updated:` to carry forward, so it gets today's.
|
|
56
|
+
*/
|
|
57
|
+
export function existingBody(root: string): string | null {
|
|
58
|
+
const path = join(root, "AGENTS.md");
|
|
59
|
+
if (!existsSync(path)) return null;
|
|
60
|
+
const content = readFileSync(path, "utf-8");
|
|
61
|
+
const match = content.match(/^---\n[\s\S]*?\n---\n\n/);
|
|
62
|
+
if (!match) return null;
|
|
63
|
+
return content.slice(match[0].length);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Build the AGENTS.md frontmatter block.
|
|
68
|
+
*
|
|
69
|
+
* Preserves whatever the existing file declared (owner, status, custom keys)
|
|
70
|
+
* and refreshes `updated:` ONLY when the body it is about actually changed.
|
|
71
|
+
* Regenerating from scratch would silently drop a hand-set owner, and
|
|
72
|
+
* emitting nothing — the behavior before #552 — stripped the block entirely
|
|
73
|
+
* on every re-scaffold.
|
|
74
|
+
*
|
|
75
|
+
* #827: `updated` used to be forced to today AFTER the spread, so it could
|
|
76
|
+
* never be carried forward and AGENTS.md could never be a fixed point of its
|
|
77
|
+
* own generator — the file stopped being one the morning after it was
|
|
78
|
+
* written, with no code or spec change in between. Dropping the field
|
|
79
|
+
* instead would make the file a fixed point and lose the freshness signal
|
|
80
|
+
* doc-hygiene wants, so neither of those is the fix. What the field claims
|
|
81
|
+
* to mean is "the date this file's content last changed", and deriving it
|
|
82
|
+
* from the body is what makes it mean that; the fixed point then falls out
|
|
83
|
+
* rather than being exempted into existence.
|
|
84
|
+
*
|
|
85
|
+
* @param bodyUnchanged the generator's body for this scan equals the one on
|
|
86
|
+
* disk. The caller computes the body first and answers
|
|
87
|
+
* this; the frontmatter is not in a position to.
|
|
88
|
+
*/
|
|
89
|
+
function buildFrontmatter(root: string, today: string, bodyUnchanged: boolean): string {
|
|
50
90
|
const defaults: Record<string, string> = {
|
|
51
91
|
"doc-type": "reference",
|
|
52
92
|
status: "active",
|
|
@@ -55,7 +95,12 @@ function buildFrontmatter(root: string): string {
|
|
|
55
95
|
|
|
56
96
|
const existing = existingFrontmatter(root);
|
|
57
97
|
|
|
58
|
-
|
|
98
|
+
// An existing stamp survives only when the body it dates is unchanged. A
|
|
99
|
+
// file with no stamp at all gets today's either way — there is nothing to
|
|
100
|
+
// carry, and a missing `updated:` is not evidence of freshness.
|
|
101
|
+
const stamp = bodyUnchanged ? (existing.updated ?? today) : today;
|
|
102
|
+
|
|
103
|
+
const merged: Record<string, string> = { ...defaults, ...existing, updated: stamp };
|
|
59
104
|
const order = ["doc-type", "status", "owner", "updated"];
|
|
60
105
|
const keys = [...order.filter(k => k in merged), ...Object.keys(merged).filter(k => !order.includes(k))];
|
|
61
106
|
return `---\n${keys.map(k => `${k}: ${merged[k]}`).join("\n")}\n---\n\n`;
|
|
@@ -66,7 +111,14 @@ export interface GeneratedRule {
|
|
|
66
111
|
content: string;
|
|
67
112
|
}
|
|
68
113
|
|
|
69
|
-
|
|
114
|
+
/**
|
|
115
|
+
* @param today the calendar day a CHANGED body is stamped with. Injectable
|
|
116
|
+
* so a test can advance the clock without advancing anything
|
|
117
|
+
* else — the whole of #827 is a field that moves when nothing
|
|
118
|
+
* else did, and a case that cannot change the date cannot see
|
|
119
|
+
* it. Defaults to the real day, so every caller is unchanged.
|
|
120
|
+
*/
|
|
121
|
+
export function generateAgentsMd(scan: ProjectScan, today: string = localCalendarDay()): string {
|
|
70
122
|
const {
|
|
71
123
|
name,
|
|
72
124
|
identity,
|
|
@@ -102,11 +154,6 @@ export function generateAgentsMd(scan: ProjectScan): string {
|
|
|
102
154
|
? `\n## Consumers (${consumers.length})\n\n${consumers.map(c => `- ${c}`).join("\n")}\n\nCheck cascade impact when modifying shared modules.`
|
|
103
155
|
: "";
|
|
104
156
|
|
|
105
|
-
// Re-scaffolding used to strip AGENTS.md's frontmatter, because the
|
|
106
|
-
// generator never emitted any. Carry the existing block forward with a
|
|
107
|
-
// refreshed `updated:` so doc-hygiene keeps working across re-scaffolds.
|
|
108
|
-
const frontmatter = buildFrontmatter(scan.root);
|
|
109
|
-
|
|
110
157
|
// convert-spec is only advertised where the script actually exists —
|
|
111
158
|
// rungate has it, a scaffolded consumer may not. It was being dropped on
|
|
112
159
|
// every re-scaffold because the table did not know about it at all.
|
|
@@ -179,7 +226,12 @@ bunx rungate --help
|
|
|
179
226
|
|
|
180
227
|
Pin the version: re-scaffolding on a newer rungate rewrites generated files.`;
|
|
181
228
|
|
|
182
|
-
|
|
229
|
+
// Re-scaffolding used to strip AGENTS.md's frontmatter, because the
|
|
230
|
+
// generator never emitted any. Carry the existing block forward so
|
|
231
|
+
// doc-hygiene keeps working across re-scaffolds — and build the BODY
|
|
232
|
+
// first, because `updated:` is a statement about the body and cannot be
|
|
233
|
+
// decided before it exists (#827).
|
|
234
|
+
const body = `# ${name}
|
|
183
235
|
|
|
184
236
|
## Project Identity
|
|
185
237
|
|
|
@@ -211,6 +263,8 @@ ${consumerSection}
|
|
|
211
263
|
${repoLine}${makeTargets}
|
|
212
264
|
- **Test:** \`${testCmd}\`
|
|
213
265
|
`;
|
|
266
|
+
|
|
267
|
+
return buildFrontmatter(scan.root, today, body === existingBody(scan.root)) + body;
|
|
214
268
|
}
|
|
215
269
|
|
|
216
270
|
/**
|
|
@@ -283,24 +337,14 @@ description: Shared behavioral principles for all agents working in this project
|
|
|
283
337
|
`,
|
|
284
338
|
});
|
|
285
339
|
|
|
340
|
+
// The TEXT is not a constant any more (#911). A project that has decided to
|
|
341
|
+
// bypass the harness declares `ship.mode: "direct"` in its config, and this
|
|
342
|
+
// rule says so — with the date and the reason — instead of telling every
|
|
343
|
+
// agent the opposite of its instructions. `lib/ship-mode.ts` is the single
|
|
344
|
+
// decider; an unrecognised mode throws out of here rather than defaulting.
|
|
286
345
|
rules.push({
|
|
287
346
|
filename: "ship-workflow.md",
|
|
288
|
-
content:
|
|
289
|
-
description: All implementation work must go through the ship workflow — never spawn agents directly
|
|
290
|
-
---
|
|
291
|
-
|
|
292
|
-
## Ship Workflow Required
|
|
293
|
-
|
|
294
|
-
When shipping an issue or implementing code changes, use the ship workflow:
|
|
295
|
-
|
|
296
|
-
\`\`\`
|
|
297
|
-
Skill("ship") → Workflow({ scriptPath: "workflows/ship.js" })
|
|
298
|
-
\`\`\`
|
|
299
|
-
|
|
300
|
-
**NEVER spawn Marcus, Quinn, or Rook directly with the Agent tool.** The ship workflow captures transcripts, runs compliance grading, and enforces gates. Spawning agents directly bypasses all measurement.
|
|
301
|
-
|
|
302
|
-
If Skill("harness") or Skill("goal") fails, fall back to Skill("ship") with the issue number.
|
|
303
|
-
`,
|
|
347
|
+
content: shipWorkflowRule(resolveShipPolicy(scan.harnessConfig)),
|
|
304
348
|
});
|
|
305
349
|
|
|
306
350
|
if (specs.length > 0) {
|
|
@@ -397,16 +441,47 @@ section is yours, and a re-scaffold carries it forward verbatim —
|
|
|
397
441
|
including the \`<!-- BEGIN AUTO-EXTRACTED -->\` block, and including any
|
|
398
442
|
lines you wrote outside it.
|
|
399
443
|
|
|
400
|
-
|
|
401
|
-
regeneration, which is a promise \`specs/bootstrap-data-flow/\`
|
|
402
|
-
nothing kept until #568: one run on a consumer removed 37
|
|
403
|
-
lines and reported \`REGENERATED: AGENTS.md\`, exit 0. Put
|
|
404
|
-
project rules there — the ones an agent cannot read off the
|
|
405
|
-
nowhere else in the file.
|
|
444
|
+
It was the only user-owned content in the tree that survived
|
|
445
|
+
regeneration until #655, which is a promise \`specs/bootstrap-data-flow/\`
|
|
446
|
+
makes and nothing kept until #568: one run on a consumer removed 37
|
|
447
|
+
constraint lines and reported \`REGENERATED: AGENTS.md\`, exit 0. Put
|
|
448
|
+
non-inferable project rules there — the ones an agent cannot read off the
|
|
449
|
+
code — and nowhere else in the file.
|
|
406
450
|
|
|
407
451
|
If a run cannot carry every one of those lines forward it **refuses the
|
|
408
452
|
write**, names the lines, and leaves your file untouched.
|
|
409
453
|
|
|
454
|
+
### An agent brief is section-owned too (#655)
|
|
455
|
+
|
|
456
|
+
A rule mined from THIS repository's compliance history — the output of the
|
|
457
|
+
hill-climb loop — is non-inferable by construction, and until #655 it had
|
|
458
|
+
nowhere in the project to live. Every brief surface was rebuilt from
|
|
459
|
+
harness-wide inputs on the next \`bunx rungate scaffold .\`:
|
|
460
|
+
\`templates/agent-briefs/_shared.md\` resolves under the harness's own
|
|
461
|
+
templates directory, so a project rule written there reaches every
|
|
462
|
+
consumer; \`roles.json\`'s \`tiers.reinforcement\` carries section NAMES, not
|
|
463
|
+
rule text; and the write itself was a bare \`writeFileSync\`.
|
|
464
|
+
|
|
465
|
+
So \`.claude/agents/*.md\` now works the way \`AGENTS.md\` does, through the
|
|
466
|
+
same merge in \`lib/agents-md-sections.ts\`:
|
|
467
|
+
|
|
468
|
+
- Add a \`## Project Constraints\` heading to a brief and everything under
|
|
469
|
+
it, up to the next \`##\`, is yours. A re-scaffold carries it forward
|
|
470
|
+
verbatim and rewrites the rest.
|
|
471
|
+
- The section is **opt-in**. No template emits it, because a generated
|
|
472
|
+
section would collide with yours and the merge would refuse every run.
|
|
473
|
+
A heading plus one line is a section; a heading alone is not.
|
|
474
|
+
- If a run cannot carry every one of those lines forward it **refuses the
|
|
475
|
+
write**, names the lines, and leaves the brief untouched — the same
|
|
476
|
+
refusal-rather-than-silent-loss property #568 gave AGENTS.md.
|
|
477
|
+
- A reinforcement the hill-climb applies goes there in preference to
|
|
478
|
+
\`## Efficiency Rules\`, \`## Testing Rules\` or \`## Never Do\`, so what the
|
|
479
|
+
loop writes is the content a re-scaffold preserves.
|
|
480
|
+
|
|
481
|
+
The \`## Hard Constraints\` spelling is AGENTS.md's and only AGENTS.md's. A
|
|
482
|
+
brief section is scoped to one role; using one heading for both would make
|
|
483
|
+
a rule written in the wrong file look like it was in the right one.
|
|
484
|
+
|
|
410
485
|
### The workflow files are job-owned, not file-owned (#216)
|
|
411
486
|
|
|
412
487
|
rungate owns the \`test\` job in \`ci.yml\` and the \`gates\` job in
|
|
@@ -419,6 +494,39 @@ cannot carry a job forward — a flow mapping (\`jobs: {deploy: {...}}\`), or a
|
|
|
419
494
|
file it cannot parse — it **refuses the write**, names the jobs at risk and
|
|
420
495
|
the line delta, and leaves your file untouched. Re-run with \`--force\` only
|
|
421
496
|
if you mean to discard them.
|
|
497
|
+
|
|
498
|
+
### Every workflow file is reported, owned or not (#722)
|
|
499
|
+
|
|
500
|
+
The table above is a list of files this generator **writes**. That is why a
|
|
501
|
+
workflow it did not write could not be added to it: the next scaffold would
|
|
502
|
+
either start generating the file or the row would describe behaviour the
|
|
503
|
+
code does not have, which is #208 exactly.
|
|
504
|
+
|
|
505
|
+
So ownership travels with the bytes instead. Each generated workflow carries
|
|
506
|
+
a \`# generated-sha:\` marker on its first line — a YAML comment, invisible
|
|
507
|
+
to anything that parses the file — and a re-scaffold reports **every** file
|
|
508
|
+
in \`.github/workflows/\`:
|
|
509
|
+
|
|
510
|
+
| Status | What it means |
|
|
511
|
+
|--------|---------------|
|
|
512
|
+
| generated-and-unchanged | rungate wrote it and nobody has touched it |
|
|
513
|
+
| generated-and-hand-edited | rungate wrote it and the bytes have moved; preserved, not rewritten |
|
|
514
|
+
| NOT-OWNED | no marker — rungate did not write this and does not manage it |
|
|
515
|
+
|
|
516
|
+
**A NOT-OWNED workflow is reported by name and otherwise left alone.** What
|
|
517
|
+
you do with it is yours; the harness only refuses to keep quiet about it.
|
|
518
|
+
Each name is printed individually, because "5 unowned workflows" is not
|
|
519
|
+
something anybody can act on.
|
|
520
|
+
|
|
521
|
+
The line also carries its own coverage — \`read N/M file(s)\` — and a
|
|
522
|
+
directory that could not be read reports \`UNMEASURED\` rather than an empty
|
|
523
|
+
list. A scan that read 2 of 7 files and a scan that read all 7 are otherwise
|
|
524
|
+
the same clean report, and no reader can tell them apart from the output.
|
|
525
|
+
|
|
526
|
+
This matters on a tree the harness was added to rather than one it created.
|
|
527
|
+
One consumer ran five \`engine: copilot\` workflows that cost money, failed on
|
|
528
|
+
quota and emailed its owner, and every scaffold run reported clean — not
|
|
529
|
+
because anything went wrong, but because nothing had ever looked.
|
|
422
530
|
`,
|
|
423
531
|
});
|
|
424
532
|
|