rungate 0.4.0 → 0.5.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 (65) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/ac-quality.ts +119 -0
  11. package/lib/cli-commands.ts +7 -1
  12. package/lib/config-loader.ts +129 -5
  13. package/lib/conformity.ts +1122 -31
  14. package/lib/context-docs.ts +182 -0
  15. package/lib/create-brief.ts +22 -17
  16. package/lib/create-sc.ts +35 -8
  17. package/lib/doc-scan-targets.ts +435 -0
  18. package/lib/gate-check-audit.ts +9 -9
  19. package/lib/github.ts +195 -0
  20. package/lib/js-top-level-code.ts +27 -2
  21. package/lib/organize.ts +129 -40
  22. package/lib/package-closure.ts +387 -0
  23. package/lib/project-aliases.ts +100 -0
  24. package/lib/release-preflight.ts +352 -48
  25. package/lib/rungate-schema.ts +23 -1
  26. package/lib/sc-cover.ts +92 -1
  27. package/lib/sc-ids.ts +151 -0
  28. package/lib/scaffold/defaults.ts +40 -0
  29. package/lib/scaffold/managed-workflow.ts +125 -27
  30. package/lib/scaffold/owned-files.ts +6 -0
  31. package/lib/scaffold/profiles.ts +94 -0
  32. package/lib/scaffold/rehearsal.ts +355 -0
  33. package/lib/scaffold/steps.ts +787 -105
  34. package/lib/scaffold/write-steps.ts +208 -0
  35. package/lib/scratch-cleanup.ts +198 -0
  36. package/lib/scratch-roots.ts +94 -0
  37. package/lib/source-anchor.ts +144 -0
  38. package/lib/success-doc.ts +779 -0
  39. package/lib/suite-run-reading.ts +194 -0
  40. package/lib/test-census.ts +199 -0
  41. package/lib/trajectory.ts +377 -0
  42. package/lib/validators/spec-validators.ts +52 -35
  43. package/lib/workflow-security.ts +152 -7
  44. package/lib/workflow-test-harness.ts +349 -0
  45. package/lib/worktree-cleanup.ts +123 -7
  46. package/lib/worktree-repo.ts +165 -0
  47. package/package.json +10 -1
  48. package/scripts/audit-specs.ts +134 -37
  49. package/scripts/audit-transcript.ts +259 -0
  50. package/scripts/create-sc.ts +15 -1
  51. package/scripts/create-success.ts +162 -0
  52. package/scripts/detect-sc-drift.ts +200 -0
  53. package/scripts/extract-constraints.ts +16 -36
  54. package/scripts/scaffold-project.ts +51 -137
  55. package/scripts/split-spec.ts +315 -0
  56. package/scripts/sync-sc-status.ts +751 -0
  57. package/specs/SPEC-TEMPLATE.md +200 -0
  58. package/templates/SUCCESS-TEMPLATE.md +72 -0
  59. package/templates/agent-briefs/_shared.md +9 -0
  60. package/templates/agent-briefs/aditi.md +46 -0
  61. package/templates/agent-briefs/discovery.md +37 -0
  62. package/templates/agent-briefs/marcus.md +39 -0
  63. package/templates/agent-briefs/quinn.md +67 -0
  64. package/templates/agent-briefs/rook.md +40 -0
  65. package/templates/agent-briefs/serena.md +39 -0
@@ -0,0 +1,194 @@
1
+ /**
2
+ * What a test runner's own output says it did (#469, #490).
3
+ *
4
+ * `lib/suite-measurement.ts` reads the RECORD a run left behind and refuses
5
+ * everything that is not a complete, SHA-bound result. This file is one step
6
+ * upstream of it: it reads the runner's output and decides whether there is a
7
+ * result to record at all. The two defects it exists for are the same defect
8
+ * at two sizes.
9
+ *
10
+ * **#469 — a run that read none of its files exits 0.** Observed verbatim on
11
+ * 2026-10-16, after a worktree was deleted by hand while its suite was
12
+ * running: four `error: ENOENT reading "…"` blocks, no `N pass / N fail`
13
+ * summary, and `[exited with code 0]`. Reproduced here on bun 1.3.14 by
14
+ * removing the test directory from the first file imported, which prints the
15
+ * banner and nothing else. The exit code differs between the two — 0 then, 1
16
+ * now — which is the argument for not reading the exit code at all. Both runs
17
+ * measured nothing, and only the absence of a summary says so.
18
+ *
19
+ * **#490 — a runner that discovers nothing looks exactly like a clean run.**
20
+ * Measured on the same bun: a project whose only test file declares no tests
21
+ * prints
22
+ *
23
+ * 0 pass
24
+ * 0 fail
25
+ * Ran 0 tests across 1 file. [6.00ms]
26
+ *
27
+ * and exits 0. Every indicator is green over a suite that asserted nothing.
28
+ *
29
+ * **The file count is the proxy; the executed count is the property.** #490
30
+ * asks for the discovered FILE count to be greater than zero, and that row
31
+ * above is why this module does not stop there: one empty file satisfies
32
+ * "files > 0" while measuring exactly as much as no files at all. That is the
33
+ * trap `.claude/rules/checks-must-be-able-to-fail.md` records as wording a
34
+ * refusal after the cheapest proxy rather than after the property — a proxy
35
+ * is a thing people can satisfy directly. So the file count is READ, RECORDED
36
+ * and refused when it contradicts the results, and the refusal that carries
37
+ * the weight is about what the runner executed.
38
+ *
39
+ * Nothing here throws, for the same reason nothing in `lib/suite-measurement.ts`
40
+ * does: it is read on the path that decides whether a run may ship, and a
41
+ * throw is a refusal the caller's error handling can turn back into a ship.
42
+ */
43
+
44
+ /**
45
+ * `N pass` and `N fail` on their own lines — bun's summary, and the shape
46
+ * `parseTestFailureCount` in gates/gate-executor.ts has read since #307.
47
+ * Anchored to the whole line so a sentence mentioning "0 fail" inside a
48
+ * captured test output cannot be read as the summary.
49
+ */
50
+ const PASS_LINE = /^\s*(\d+)\s+pass\s*$/gm;
51
+ const FAIL_LINE = /^\s*(\d+)\s+fail\s*$/gm;
52
+
53
+ /** `Ran 11521 tests across 324 files.` — and `1 test across 1 file.` */
54
+ const RAN_LINE = /^Ran\s+(\d+)\s+tests?\s+across\s+(\d+)\s+files?\./gm;
55
+
56
+ export interface MeasuredRun {
57
+ status: "MEASURED";
58
+ pass: number;
59
+ fail: number;
60
+ /**
61
+ * Tests the runner says it ran, or null when it did not say.
62
+ *
63
+ * null rather than `pass + fail`: a derived number here would be
64
+ * indistinguishable from one the runner reported, and the point of the
65
+ * whole module is that a number nobody measured must not be reportable.
66
+ */
67
+ tests: number | null;
68
+ /**
69
+ * Test files the runner discovered, or null when it did not say.
70
+ *
71
+ * **null, never 0.** "This runner does not report a file count" and "this
72
+ * runner found no files" are opposite facts, and `0` is the one value that
73
+ * would let a reader add them together — `.claude/rules/config-access.md`,
74
+ * *Silent Default Substitution*, pointed at the number #490 is about.
75
+ */
76
+ files: number | null;
77
+ }
78
+
79
+ export interface UnmeasuredRun {
80
+ status: "UNMEASURED";
81
+ reason: string;
82
+ }
83
+
84
+ export type SuiteRun = MeasuredRun | UnmeasuredRun;
85
+
86
+ function unmeasured(reason: string): UnmeasuredRun {
87
+ return { status: "UNMEASURED", reason };
88
+ }
89
+
90
+ /** The last match of a global pattern, or null. Last, because a suite run can
91
+ * contain another suite's captured output and the summary is printed at the
92
+ * end — the same choice `parseTestFailureCount` made in #307. */
93
+ function lastMatch(re: RegExp, text: string): RegExpMatchArray | null {
94
+ const all = [...text.matchAll(re)];
95
+ return all.length === 0 ? null : all[all.length - 1];
96
+ }
97
+
98
+ /** How much of the output to quote back in a refusal, so a reason is readable
99
+ * without pasting a 400 KB suite log into a gate failure. */
100
+ function tail(output: string, limit = 240): string {
101
+ const lines = output.trimEnd().split("\n").filter(l => l.trim() !== "");
102
+ const last = lines.slice(-3).join(" / ");
103
+ return last.length > limit ? `${last.slice(0, limit)}…` : last || "(nothing)";
104
+ }
105
+
106
+ /**
107
+ * Read a test runner's output.
108
+ *
109
+ * FAILS CLOSED. Every path that cannot positively establish that the runner
110
+ * executed something returns UNMEASURED with a reason. There is no path that
111
+ * returns a zero-failure MEASURED reading from an output that does not say so.
112
+ *
113
+ * The EXIT CODE is deliberately not a parameter. #469's run exited 0 having
114
+ * measured nothing; the reproduction of it here exits 1. A reading that
115
+ * consulted the exit code would have been wrong about one of them, and
116
+ * choosing which is not a thing this function can know.
117
+ */
118
+ export function readSuiteRun(output: unknown): SuiteRun {
119
+ if (typeof output !== "string" || output.trim() === "") {
120
+ return unmeasured(
121
+ "the test runner produced no output, so there is nothing to read a result out of — " +
122
+ "a run with no output is not a run with no failures (#469)",
123
+ );
124
+ }
125
+
126
+ const passMatch = lastMatch(PASS_LINE, output);
127
+ const failMatch = lastMatch(FAIL_LINE, output);
128
+
129
+ // #469's shape, and half of it. ONE branch, two sentences: the run printed
130
+ // no summary, or printed half of one, and in both cases there is no result
131
+ // to read. Written as a single decider on purpose — a separate `!pass &&
132
+ // !fail` branch above this would be a second guard answering a question
133
+ // this one already answers, and no behavioural test could tell them apart
134
+ // (.claude/rules/checks-must-be-able-to-fail.md, the fourth shape). The
135
+ // distinction is a wording, so it lives in the wording.
136
+ if (!passMatch || !failMatch) {
137
+ const missing = [!passMatch && "pass", !failMatch && "fail"].filter(Boolean) as string[];
138
+ const what =
139
+ missing.length === 2
140
+ ? "printed no pass/fail summary, so it never reported a result — this is a run that " +
141
+ "measured nothing, not a run that found nothing wrong"
142
+ : `printed a "${passMatch ? "pass" : "fail"}" count but no "${missing[0]}" count, so its ` +
143
+ "summary is incomplete and the missing half cannot be assumed to be zero";
144
+ return unmeasured(`the test runner ${what} (#469). Last output: ${tail(output)}`);
145
+ }
146
+
147
+ const pass = Number(passMatch[1]);
148
+ const fail = Number(failMatch[1]);
149
+
150
+ const ran = lastMatch(RAN_LINE, output);
151
+ const tests = ran ? Number(ran[1]) : null;
152
+ const files = ran ? Number(ran[2]) : null;
153
+
154
+ // #490 SC-1, as a contradiction rather than as a second way of asking
155
+ // whether anything ran. A runner claiming results it discovered no files to
156
+ // produce is not reporting a measurement of this project, and it is the one
157
+ // case the executed-count refusal below cannot see: that one fires when
158
+ // nothing ran, and this one fires only when something did.
159
+ if (files === 0 && pass + fail > 0) {
160
+ return unmeasured(
161
+ `the test runner reported ${pass + fail} result(s) but says it discovered 0 test files — ` +
162
+ "the counts contradict each other, so neither can be read as a measurement of this project (#490)",
163
+ );
164
+ }
165
+
166
+ // #490's real shape, and the reason this is about the executed count rather
167
+ // than the file count: `Ran 0 tests across 1 file.` exits 0 with every
168
+ // indicator green. One empty file satisfies "files > 0" and measures
169
+ // nothing.
170
+ if (pass + fail === 0) {
171
+ const where =
172
+ files === null
173
+ ? "and it did not say how many test files it discovered"
174
+ : `across the ${files} test file(s) it discovered`;
175
+ return unmeasured(
176
+ `the test runner executed 0 tests ${where} — a runner that discovered nothing to run is ` +
177
+ "indistinguishable from a clean suite by its exit code, and it is not one (#490)",
178
+ );
179
+ }
180
+
181
+ return { status: "MEASURED", pass, fail, tests, files };
182
+ }
183
+
184
+ /**
185
+ * The verdict a reading supports.
186
+ *
187
+ * Three verdicts and not two, for the reason `lib/suite-measurement.ts`
188
+ * states: UNMEASURED is not a result, it is the statement that this run has
189
+ * no suite evidence.
190
+ */
191
+ export function suiteRunVerdict(run: SuiteRun): "PASS" | "FAIL" | "UNMEASURED" {
192
+ if (run.status !== "MEASURED") return "UNMEASURED";
193
+ return run.fail === 0 ? "PASS" : "FAIL";
194
+ }
@@ -0,0 +1,199 @@
1
+ /**
2
+ * test-census.ts — how many tests each file declares, before and after
3
+ *
4
+ * #307 SC-A19. Run `wf_5cdce852-1e2`'s heal loop went from 34 tests to 23
5
+ * across two rounds, with no `skip` and no `todo` recorded. Most of that
6
+ * rewrite was a fair consolidation; three guards had nothing replacing them,
7
+ * and the only thing that noticed was `SECURITY_REVIEW_STALE` — which was
8
+ * looking at something else.
9
+ *
10
+ * A heal agent is told a gate failed and asked to make it pass. Deleting the
11
+ * test is a correct solution to that instruction and an incorrect solution to
12
+ * the problem, and the gate cannot tell the difference afterwards: a suite
13
+ * with the failing test removed is green, and green is what it was asked for.
14
+ *
15
+ * So the count is taken on every gate run and compared to the previous one.
16
+ * Every heal round ends in a gate re-run, so "between gate runs" and "across
17
+ * a heal" are the same window, and the comparison lives where it can be
18
+ * executed by a test rather than in `workflows/ship.js`, which has no
19
+ * filesystem access and could only have asked an agent to do it.
20
+ *
21
+ * This module is the counting and the comparison; `gates/gate-executor.ts`
22
+ * holds the refusal and decides when to bank a new reading.
23
+ *
24
+ * ## What this guard does NOT do, stated rather than implied
25
+ *
26
+ * The banked census lives in the run's `workflow-state.json`, which is a
27
+ * file the heal agent can write. A heal agent that deleted a test AND the
28
+ * census would see `first-reading` on the next round and pass. This guard
29
+ * raises the cost of an accidental deletion, which is the failure mode that
30
+ * actually happened on `wf_5cdce852-1e2`; it is not tamper-evident against a
31
+ * deliberate one, and `writeWorkflowState`'s Zod validation does not make it
32
+ * so, because an absent optional key is valid.
33
+ *
34
+ * Closing that properly means putting the reading somewhere the guarded
35
+ * party does not write — the witness, or an HMAC over it — and is filed
36
+ * separately rather than half-done here. A guard whose limit is written down
37
+ * is a guard somebody can finish; one whose limit is implied is one everybody
38
+ * assumes is complete.
39
+ *
40
+ * ## Why a declaration count and not a run
41
+ *
42
+ * Running the suite twice per heal round costs this project about thirteen
43
+ * minutes a round. A static count costs milliseconds and answers the question
44
+ * actually asked — "did a test stop existing" — rather than "did the number of
45
+ * passing tests go down", which also moves when a heal legitimately fixes a
46
+ * failure.
47
+ *
48
+ * It is deliberately a count of DECLARATIONS, including `.skip` and `.todo`.
49
+ * A heal that converts a failing test to `test.todo` has removed the check
50
+ * just as thoroughly as deleting it, and that conversion is the cheapest way
51
+ * past a count that only looked at live tests.
52
+ */
53
+ import { existsSync, readdirSync, readFileSync, statSync } from "fs";
54
+ import { join } from "path";
55
+
56
+ /**
57
+ * Directories a census never walks into.
58
+ *
59
+ * The walk is the whole project, NOT a fixed list of test directories. A
60
+ * `["test", "gates"]` list is rungate's own layout, and a consumer that keeps
61
+ * its tests beside its sources — `src/foo.test.ts`, which is the commonest
62
+ * JavaScript convention there is — would census to `{}` on every run. An
63
+ * empty census compares clean against an empty census forever, so the guard
64
+ * would be dead for exactly the projects it is supposed to protect, and
65
+ * nothing would say so.
66
+ */
67
+ export const CENSUS_SKIP = new Set([
68
+ "node_modules",
69
+ ".git",
70
+ "dist",
71
+ "build",
72
+ "coverage",
73
+ ".next",
74
+ ".turbo",
75
+ "vendor",
76
+ "test-fixtures",
77
+ "worktrees",
78
+ ]);
79
+
80
+ /**
81
+ * What counts as a test file.
82
+ *
83
+ * The JS/TS family only, stated rather than implied: a consumer whose suite
84
+ * is pytest or `go test` censuses to `{}`, and `censusVerdict` reports that
85
+ * as UNMEASURED rather than as nothing-removed. "We cannot see this
86
+ * project's tests" is a different answer from "no test was removed", and
87
+ * only the first one is honest about a polyglot repo.
88
+ */
89
+ const TEST_FILE = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$/;
90
+
91
+ /**
92
+ * A file this large is not a hand-written suite, and reading it into memory
93
+ * on every gate run is a cost with no reading behind it.
94
+ *
95
+ * Oversized files are skipped, which is safe BECAUSE the cap is stable: a
96
+ * file over it is absent from both censuses and never reads as a deletion.
97
+ * The one case that does produce a false refusal is a file crossing the cap
98
+ * between rounds, and that is the direction to be wrong in — loudly, naming
99
+ * the file, rather than quietly dropping a test from the comparison.
100
+ */
101
+ export const MAX_CENSUS_FILE_BYTES = 2_000_000;
102
+
103
+ /**
104
+ * Declaration forms bun recognises. `test` and `it`, bare or with a modifier.
105
+ *
106
+ * Anchored on a word boundary so `subtest(` and `omit(` do not count, and
107
+ * requiring the open paren so a bare mention in prose does not. The modifier
108
+ * list is explicit rather than `\w+` because `test.each(...)(...)` and a
109
+ * hypothetical `test.anything` should not silently start counting — an
110
+ * unrecognised form is better as a miss we can see than as a count nobody
111
+ * can explain.
112
+ */
113
+ const DECLARATION =
114
+ /(?<![.\w$])(?:test|it)(?:\.(?:skip|todo|only|failing|each|skipIf|todoIf|only))?\s*[(`]/g;
115
+
116
+ /**
117
+ * How many tests a source file declares.
118
+ *
119
+ * Comments are NOT stripped. A commented-out test is a removed test, and
120
+ * stripping would make "comment the block out" a way past the guard. The
121
+ * cost is that prose saying `test(` counts, which inflates a file's number
122
+ * — and inflation is harmless here, because only a DECREASE is refused.
123
+ * The one direction this may be wrong in is toward not refusing, which is
124
+ * the direction a guard over somebody else's edits has to be wrong in.
125
+ */
126
+ export function countTestDeclarations(source: string): number {
127
+ return [...source.matchAll(DECLARATION)].length;
128
+ }
129
+
130
+ /**
131
+ * `{ "test/a.test.ts": 12, … }` for every test file anywhere under `root`.
132
+ *
133
+ * Pass a `skipped` array to be told which files the walk declined to read.
134
+ * Optional so the common caller stays a one-liner, and the gate passes one
135
+ * so it can say so rather than reporting over a comparison that quietly
136
+ * excluded something.
137
+ */
138
+ export function censusOf(root: string, skipped: string[] = []): Record<string, number> {
139
+ const out: Record<string, number> = {};
140
+ const walk = (dir: string, rel: string) => {
141
+ if (!existsSync(dir)) return;
142
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
143
+ const r = rel ? `${rel}/${e.name}` : e.name;
144
+ if (e.isDirectory()) {
145
+ if (CENSUS_SKIP.has(e.name) || e.name.startsWith(".")) continue;
146
+ walk(join(dir, e.name), r);
147
+ } else if (e.isFile() && TEST_FILE.test(e.name)) {
148
+ // `isFile()`, not `!isDirectory()`. A dirent for a symlink answers
149
+ // false to both, so this walk follows no links in either direction:
150
+ // no symlinked-directory loop, and no `readFileSync` on a link to a
151
+ // character device, which has size 0 and never ends.
152
+ const p = join(dir, e.name);
153
+ if (statSync(p).size > MAX_CENSUS_FILE_BYTES) {
154
+ // Named, not dropped. A skip the caller cannot see is a file
155
+ // silently outside the comparison, which is the shape this whole
156
+ // guard exists to refuse — and a reader looking at "no test was
157
+ // removed" deserves to know which files that sentence is not
158
+ // about.
159
+ skipped.push(r);
160
+ continue;
161
+ }
162
+ out[r] = countTestDeclarations(readFileSync(p, "utf-8"));
163
+ }
164
+ }
165
+ };
166
+ walk(root, "");
167
+ return out;
168
+ }
169
+
170
+ /**
171
+ * Files that lost tests between two censuses, named with both numbers.
172
+ *
173
+ * Three rules, and the second is the one a naive implementation misses:
174
+ *
175
+ * - a file whose count DROPPED is a regression
176
+ * - a file that DISAPPEARED is a regression of its whole count — deleting
177
+ * the file is the obvious way past a per-file comparison
178
+ * - a file that APPEARED is not a regression, and neither is a rise
179
+ *
180
+ * An empty census `before` returns nothing. That is correct and worth
181
+ * stating: it means the guard cannot refuse when it never got a reading, and
182
+ * the caller is responsible for noticing that it got one. A comparison that
183
+ * refused on an absent baseline would fire on every first round.
184
+ */
185
+ export function censusRegressions(
186
+ before: Record<string, number>,
187
+ after: Record<string, number>,
188
+ ): string[] {
189
+ const out: string[] = [];
190
+ for (const [file, was] of Object.entries(before).sort()) {
191
+ const now = after[file];
192
+ if (now === undefined) {
193
+ if (was > 0) out.push(`${file}: the file declared ${was} test(s) and is gone`);
194
+ } else if (now < was) {
195
+ out.push(`${file}: ${was} test(s) before, ${now} after`);
196
+ }
197
+ }
198
+ return out;
199
+ }