rungate 0.3.0 → 0.4.1

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 (49) hide show
  1. package/lib/ac-quality.ts +119 -0
  2. package/lib/brief-precedence.ts +114 -0
  3. package/lib/ci-checkout.ts +27 -1
  4. package/lib/compliance-backfill.ts +16 -4
  5. package/lib/compliance-report.ts +109 -8
  6. package/lib/config-loader.ts +129 -5
  7. package/lib/config-readers.ts +86 -0
  8. package/lib/conformity.ts +520 -27
  9. package/lib/context-docs.ts +182 -0
  10. package/lib/create-brief.ts +22 -17
  11. package/lib/create-sc.ts +55 -33
  12. package/lib/decomposition-waves.ts +197 -0
  13. package/lib/doc-scan-targets.ts +435 -0
  14. package/lib/gate-check-audit.ts +190 -0
  15. package/lib/generators/agents-md.ts +10 -5
  16. package/lib/issue-extraction.ts +368 -0
  17. package/lib/organize.ts +129 -40
  18. package/lib/package-closure.ts +111 -0
  19. package/lib/phase2-decomposition.ts +270 -0
  20. package/lib/prior-branch.ts +24 -1
  21. package/lib/project-aliases.ts +100 -0
  22. package/lib/prove-label-gate.ts +93 -0
  23. package/lib/release-preflight.ts +225 -15
  24. package/lib/rungate-schema.ts +36 -2
  25. package/lib/sc-cover.ts +92 -1
  26. package/lib/sc-ids.ts +151 -0
  27. package/lib/scaffold/pre-push-hook.ts +165 -0
  28. package/lib/scaffold/rehearsal.ts +330 -0
  29. package/lib/scaffold/steps.ts +175 -122
  30. package/lib/scaffold/write-steps.ts +167 -0
  31. package/lib/scope-denylist.ts +258 -0
  32. package/lib/scratch-cleanup.ts +198 -0
  33. package/lib/scratch-roots.ts +94 -0
  34. package/lib/task-completion-checks.ts +50 -3
  35. package/lib/typescript-project.ts +233 -0
  36. package/lib/validators/spec-validators.ts +23 -34
  37. package/lib/verified-push.ts +179 -2
  38. package/lib/workflow-security.ts +51 -7
  39. package/lib/worktree-cleanup.ts +318 -20
  40. package/lib/worktree-repo.ts +465 -0
  41. package/package.json +8 -2
  42. package/scripts/audit-specs.ts +134 -37
  43. package/scripts/audit-transcript.ts +259 -0
  44. package/scripts/create-sc.ts +15 -1
  45. package/scripts/detect-sc-drift.ts +200 -0
  46. package/scripts/extract-constraints.ts +16 -36
  47. package/scripts/scaffold-project.ts +26 -136
  48. package/scripts/split-spec.ts +315 -0
  49. package/scripts/sync-sc-status.ts +751 -0
@@ -0,0 +1,258 @@
1
+ /**
2
+ * Files a goal put out of bounds, and the plans that claimed them anyway (#306).
3
+ *
4
+ * ## What happened
5
+ *
6
+ * #274 attempt 4 (`wf_b3714a40-bb7`). The goal said, under a heading in
7
+ * capitals, "ALSO DO NOT FIX, ALREADY FILED: #295 … leave it there". The
8
+ * `to-issues` decomposer then emitted a sub-issue whose `filesToModify` was
9
+ * `gates/schema.ts`, `lib/evidence-prevalidator.ts`,
10
+ * `gates/SCHEMA-GUIDE.md` — the three files you would touch to fix #295, and
11
+ * nothing to do with #274. The agent did what its file list permitted, and
12
+ * the run refused on its own contradiction: one sub-issue both documented the
13
+ * defect and removed it.
14
+ *
15
+ * The attribution is the decomposer's, not the agent's. The collection guard
16
+ * (#178, SC-413) refuses any file no sub-issue claimed, and it did not refuse
17
+ * these — so they were in the plan. An agent handed `gates/schema.ts` and a
18
+ * defect description has been told, by the strongest signal in the system,
19
+ * that the file is in scope.
20
+ *
21
+ * ## One thing #306 got wrong, corrected here
22
+ *
23
+ * The issue proposes "the goal already names them; the decomposer could be
24
+ * given an explicit deny-list". **The goal did not name them.** Re-read the
25
+ * quoted prohibition: it names an ISSUE (`#295`) and three code symbols
26
+ * (`prevalidationViolations`, `reading.broken`, `acs[].status`). Not one file
27
+ * path. The paths came from `discovery.filesToModify`, which
28
+ * `workflows/ship.js:1952` hands to the decomposer verbatim as "Files to
29
+ * modify".
30
+ *
31
+ * That changes the fix in a way worth stating, because a deny-list built on
32
+ * the issue's premise would have returned `[]` for the very run that
33
+ * motivated it and passed — the decorative check
34
+ * `.claude/rules/checks-must-be-able-to-fail.md` is about, shipped as its own
35
+ * remedy. So this module has two outputs, not one:
36
+ *
37
+ * - `deniedFiles` — paths the prohibition actually named, which can be
38
+ * enforced.
39
+ * - `unresolvedProhibitions` — prohibitions that named an issue and no file,
40
+ * which CANNOT be enforced and are reported rather than counted as clean.
41
+ * #274's own goal is this case. An empty deny-list and an unenforceable one
42
+ * look identical from the outside, and conflating them is the whole bug.
43
+ */
44
+
45
+ /** A marked region of goal text and what could be extracted from it. */
46
+ export interface Prohibition {
47
+ /** The text of the marked paragraph. */
48
+ text: string;
49
+ /** Repo-relative paths named inside it. */
50
+ files: string[];
51
+ /** Issue numbers named inside it, as `#295`. */
52
+ issues: string[];
53
+ }
54
+
55
+ /**
56
+ * Line markers that put the rest of a paragraph out of bounds.
57
+ *
58
+ * Deliberately short and literal. A wider list reads ordinary prose as a
59
+ * prohibition and starts denying files the run needs, which fails a correct
60
+ * plan — and a guard that fires on correct work is removed within a week.
61
+ */
62
+ const MARKERS = [
63
+ /\bdo\s+not\s+fix\b/i,
64
+ /\bdo\s+not\s+touch\b/i,
65
+ /\bdo\s+not\s+modify\b/i,
66
+ /\bout\s+of\s+scope\b/i,
67
+ /\bnot\s+in\s+scope\b/i,
68
+ /\balready\s+filed\b/i,
69
+ ];
70
+
71
+ /**
72
+ * A source path: an optional directory prefix and a KNOWN EXTENSION.
73
+ *
74
+ * The extension is what does the discriminating, and that is worth stating
75
+ * because the first draft of this file claimed the `/` did. It does not.
76
+ * `reading.broken` and `acs[].status` — both in #274's prohibition, both code
77
+ * expressions — are excluded because `.broken` and `.status` are not
78
+ * extensions, not because they lack a separator. Mutating the `/` from
79
+ * required to optional scored **zero red** against the cases written to
80
+ * defend it, which is how the claim was caught.
81
+ *
82
+ * The separator is optional on purpose, once it stopped being load-bearing:
83
+ * requiring it silently misses every root-level file a goal might name —
84
+ * `package.json`, `AGENTS.md`, `CODE-MAP.md` — which is a false negative in
85
+ * exactly the common case. How a bare name matches a plan entry is
86
+ * `matchesDenied` below, and it is not the same rule as for a full path.
87
+ */
88
+ const PATH = /\b([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*\.(?:ts|tsx|js|jsx|md|json|ya?ml|sh))\b/g;
89
+
90
+ const ISSUE_REF = /#(\d+)\b/g;
91
+
92
+ /** Paths named in a span of text, deduplicated, in first-seen order. */
93
+ export function pathsNamedIn(text: string): string[] {
94
+ return [...new Set([...text.matchAll(PATH)].map(m => m[1]))];
95
+ }
96
+
97
+ /**
98
+ * Split goal text into the paragraphs a marker puts out of bounds.
99
+ *
100
+ * A paragraph, not a line: #274's prohibition is one bolded lead-in followed
101
+ * by two sentences, and a line-scoped reader would see the marker and stop
102
+ * before the content. A paragraph, not the rest of the document: a marker
103
+ * near the top would otherwise deny the entire goal.
104
+ */
105
+ export function prohibitions(goalText: string): Prohibition[] {
106
+ const out: Prohibition[] = [];
107
+ for (const para of String(goalText ?? "").split(/\n\s*\n/)) {
108
+ if (!MARKERS.some(m => m.test(para))) continue;
109
+ out.push({
110
+ text: para.trim(),
111
+ files: pathsNamedIn(para),
112
+ issues: [...new Set([...para.matchAll(ISSUE_REF)].map(m => `#${m[1]}`))],
113
+ });
114
+ }
115
+ return out;
116
+ }
117
+
118
+ /**
119
+ * Every file the goal put out of bounds.
120
+ *
121
+ * `scopeOut` entries count in full — that field exists to say what is out of
122
+ * scope, so it needs no marker. Until now nothing read it at all: it was
123
+ * required by the discovery schema, appended to in one place, and consulted
124
+ * by nothing, which is its own small version of this bug.
125
+ */
126
+ export function deniedFiles(goalText: string, scopeOut: readonly string[] = []): string[] {
127
+ const fromGoal = prohibitions(goalText).flatMap(p => p.files);
128
+ const fromScopeOut = scopeOut.flatMap(s => pathsNamedIn(String(s ?? "")));
129
+ return [...new Set([...fromGoal, ...fromScopeOut])];
130
+ }
131
+
132
+ /**
133
+ * Prohibitions that name an issue and no file (#306).
134
+ *
135
+ * These are the ones the deny-list cannot act on, and reporting them is the
136
+ * point. "Nothing was denied because the goal named nothing" and "nothing was
137
+ * denied because the goal named no files" are the same empty list, and only
138
+ * the first is a clean run.
139
+ */
140
+ export function unresolvedProhibitions(goalText: string): Prohibition[] {
141
+ return prohibitions(goalText).filter(p => p.files.length === 0 && p.issues.length > 0);
142
+ }
143
+
144
+ /** A plan item that claims files. Shaped to match a sub-issue or discovery. */
145
+ export interface FileClaimant {
146
+ title?: string;
147
+ filesToModify?: readonly string[];
148
+ }
149
+
150
+ /**
151
+ * One spelling per path, so a guard cannot be stepped around by rewriting it.
152
+ *
153
+ * A string comparison is only as good as its normalisation, and `./a/b.ts`,
154
+ * `a//b.ts`, `a/./b.ts` and `a/c/../b.ts` are four spellings of one file that
155
+ * an `===` reads as four different ones. The whole value of this module is a
156
+ * comparison, so an un-normalised one is a guard with a documented bypass —
157
+ * "a detector narrower than what it detects", third shape in
158
+ * `.claude/rules/checks-must-be-able-to-fail.md`.
159
+ *
160
+ * A leading `..` is kept rather than resolved away: it escapes the repo root
161
+ * and there is nothing above it to collapse into, so dropping it would make
162
+ * `../secrets.ts` normalise to `secrets.ts` and match a deny entry that never
163
+ * meant it. Raised by the commit security review on this change.
164
+ */
165
+ export function normalisePath(p: string): string {
166
+ const raw = String(p ?? "").trim().replace(/\\/g, "/");
167
+ const out: string[] = [];
168
+ for (const seg of raw.split("/")) {
169
+ if (seg === "" || seg === ".") continue;
170
+ if (seg === ".." && out.length > 0 && out.at(-1) !== "..") out.pop();
171
+ else out.push(seg);
172
+ }
173
+ return out.join("/");
174
+ }
175
+
176
+ /**
177
+ * Does a plan's file entry fall under a denied entry?
178
+ *
179
+ * Two rules, because a goal names files two ways:
180
+ *
181
+ * - **A denied entry WITH a separator matches exactly**, after normalisation.
182
+ * A suffix match would read `test/gates/schema.ts` as `gates/schema.ts` and
183
+ * deny a file the prohibition never mentioned.
184
+ * - **A denied entry with NO separator matches by basename.** "Do not touch
185
+ * package.json" has to reach `package.json`, and "do not touch
186
+ * HARNESS-STANDARD.md" has to reach `specs/HARNESS-STANDARD.md` — a goal
187
+ * author naming a bare file means the file, wherever it lives. Requiring
188
+ * the path instead would make the common phrasing silently do nothing,
189
+ * which is this issue's own defect one level down.
190
+ *
191
+ * The basename arm compares the last segment rather than testing `endsWith`,
192
+ * because `endsWith("/package.json")` is satisfied by nothing a normalised
193
+ * path can spell differently but the segment comparison says what it means.
194
+ */
195
+ export function matchesDenied(planFile: string, deniedEntry: string): boolean {
196
+ const plan = normalisePath(planFile);
197
+ const denied = normalisePath(deniedEntry);
198
+ if (denied === "" || plan === "") return false;
199
+ if (denied.includes("/")) return plan === denied;
200
+ return plan === denied || plan.split("/").at(-1) === denied;
201
+ }
202
+
203
+ /** Violations, one line each. Empty allows. */
204
+ export function denylistViolations(
205
+ claimants: readonly FileClaimant[],
206
+ denied: readonly string[],
207
+ ): string[] {
208
+ const out: string[] = [];
209
+ for (const [i, c] of claimants.entries()) {
210
+ for (const f of c.filesToModify ?? []) {
211
+ if (!denied.some(d => matchesDenied(f, d))) continue;
212
+ out.push(
213
+ `${c.title ? `"${c.title}"` : `plan item ${i + 1}`} claims ${f}, which the goal ` +
214
+ `put out of scope. An agent handed a file is an agent told the file is in ` +
215
+ `scope (#306).`,
216
+ );
217
+ }
218
+ }
219
+ return out;
220
+ }
221
+
222
+ /**
223
+ * Did the deny-list eat the entire plan? (commit security review, #306)
224
+ *
225
+ * Two findings on this change were about the same hazard from opposite
226
+ * sides. The goal text is attacker-influenceable — issue bodies are — and
227
+ * nothing here validates it. What limits the damage is direction: a
228
+ * deny-list only ever NARROWS what an agent may write, so a hostile goal can
229
+ * deny progress but cannot grant access. That is the safe direction, and it
230
+ * is why this is a report rather than a refusal.
231
+ *
232
+ * The one outcome that is NOT safe is silence. If every file the run was
233
+ * going to touch is denied, stripping leaves an empty plan, and an empty
234
+ * plan is indistinguishable from a run with nothing to do — work refused,
235
+ * reported as work completed. That is the fail-open, and it is the shape the
236
+ * rest of this issue is about, so it gets a message rather than an empty
237
+ * array.
238
+ */
239
+ export function scopeContradiction(
240
+ files: readonly string[],
241
+ denied: readonly string[],
242
+ ): string | null {
243
+ if (files.length === 0 || denied.length === 0) return null;
244
+ if (withoutDenied(files, denied).length > 0) return null;
245
+ return (
246
+ `every file the run planned to touch is out of scope (${files.join(", ")} vs ` +
247
+ `denied ${denied.join(", ")}). An empty plan looks exactly like a run with ` +
248
+ `nothing to do, so this is reported rather than stripped in silence (#306).`
249
+ );
250
+ }
251
+
252
+ /** The denied files stripped out, order preserved. Same rule as above. */
253
+ export function withoutDenied(
254
+ files: readonly string[],
255
+ denied: readonly string[],
256
+ ): string[] {
257
+ return files.filter(f => !denied.some(d => matchesDenied(f, d)));
258
+ }
@@ -0,0 +1,198 @@
1
+ /**
2
+ * Sweep scratch directories the test suite leaked into the repo root (#437).
3
+ *
4
+ * `test/tree-under-test.test.ts` and four others plant their fixtures with
5
+ * `mkdtempSync(join(REPO_ROOT, "<prefix>"))`. They all have correct `afterAll`
6
+ * cleanup; that is the point. The directory is created when bun *imports* the
7
+ * file, before any lifecycle hook can run and before any hook is guaranteed to
8
+ * run at all, so a suite that is interrupted, killed, or that throws during
9
+ * collection leaves one behind. 34 of them had accumulated when Jason noticed,
10
+ * all but one 0 bytes — created at import, never populated, never cleaned.
11
+ *
12
+ * #437 moves creation into `beforeAll`, which stops new ones appearing. This
13
+ * is the other half: the ones already there, and the ones a kill during
14
+ * `beforeAll` can still produce.
15
+ *
16
+ * Same family as #68 (39 stale worktrees) and #436 (a worktree git had pruned
17
+ * out from under): a resource created by tooling that only gets cleaned on the
18
+ * happy path.
19
+ */
20
+
21
+ import { readdirSync, statSync, rmSync } from "fs";
22
+ import { join } from "path";
23
+ import { readFileSync } from "fs";
24
+ import { uniqueScratchPrefixes } from "./scratch-roots";
25
+
26
+ export interface ScratchCleanupResult {
27
+ /** Directories removed, named relative to the repo root. */
28
+ removed: string[];
29
+ /** Matched a prefix but was too young to be certain it is not in use. */
30
+ kept: string[];
31
+ /** Did not match any derived prefix — the overwhelming majority. */
32
+ refused: string[];
33
+ errors: string[];
34
+ }
35
+
36
+ export interface ScratchCleanupOptions {
37
+ repoRoot: string;
38
+ /**
39
+ * How old a scratch directory must be before it is swept. Default one hour.
40
+ *
41
+ * NOT belt-and-braces. This runs at SessionStart, and another session may be
42
+ * three minutes into a suite whose scratch directory is live. The suite that
43
+ * created it cannot defend it — the directory is anonymous and holds no lock
44
+ * — so age is the only signal available, and the direction to be wrong in is
45
+ * leaving litter rather than deleting a running suite's fixtures.
46
+ */
47
+ maxAgeMs?: number;
48
+ /** Report what would go without removing anything. */
49
+ dryRun?: boolean;
50
+ }
51
+
52
+ const ONE_HOUR_MS = 60 * 60 * 1000;
53
+
54
+ /**
55
+ * The file whose "prefixes" are test fixtures rather than real scratch roots.
56
+ *
57
+ * `test/scratch-paths-unique.test.ts` carries `mkdtempSync(join(ROOT, ".x-"))`
58
+ * as a STRING LITERAL, because that is the only way to prove its detector
59
+ * still fires. Stripping comments does not remove it. Deriving from it would
60
+ * put `.x-` into a deletion allowlist on the strength of a test fixture, which
61
+ * is the self-reference trap with a recursive delete on the end of it.
62
+ */
63
+ const FIXTURE_FILE = "scratch-paths-unique.test.ts";
64
+
65
+ /**
66
+ * Every prefix any suite in `test/` plants under the repo root.
67
+ *
68
+ * Derived, never listed. A hand-maintained list is a second place to forget,
69
+ * and forgetting there means a new suite's leak accumulates silently — which
70
+ * is the defect this module exists for, one level up.
71
+ */
72
+ export function scratchPrefixes(repoRoot: string): string[] {
73
+ const testDir = join(repoRoot, "test");
74
+ const out: string[] = [];
75
+ let entries: string[];
76
+ try {
77
+ entries = readdirSync(testDir);
78
+ } catch {
79
+ return out; // no test directory — nothing plants anything
80
+ }
81
+ for (const f of entries) {
82
+ if (!f.endsWith(".ts")) continue;
83
+ if (f === FIXTURE_FILE) continue;
84
+ let src: string;
85
+ try {
86
+ src = readFileSync(join(testDir, f), "utf-8");
87
+ } catch {
88
+ continue;
89
+ }
90
+ for (const p of uniqueScratchPrefixes(src)) if (!out.includes(p)) out.push(p);
91
+ }
92
+ return out.sort();
93
+ }
94
+
95
+ /**
96
+ * Exactly what `mkdtempSync` appends: six characters from this alphabet.
97
+ *
98
+ * Measured over 200 calls rather than read off the documentation — the
99
+ * lengths set came back `[6]` and the alphabet came back `[A-Za-z0-9]`.
100
+ */
101
+ const MKDTEMP_SUFFIX = "[A-Za-z0-9]{6}";
102
+
103
+ /** A prefix is data; it reaches a RegExp, so it is escaped rather than trusted. */
104
+ function escapeRegex(s: string): string {
105
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
106
+ }
107
+
108
+ /**
109
+ * Whether `entry` is a name `mkdtempSync` could have produced from `prefixes`.
110
+ *
111
+ * The prefix list is a deletion allowlist, so this is written as one, and the
112
+ * first version was written as a weaker one. It asked only that the entry
113
+ * start with a prefix and be longer — and since the prefixes are DERIVED from
114
+ * `test/*.ts`, a suite writing `mkdtempSync(join(REPO_ROOT, ".c"))` would have
115
+ * armed a SessionStart hook to recursively delete `.claude/`.
116
+ * `isScratchEntry(".claude", [".c"])` returned true; it was found by a
117
+ * security review of the first push and confirmed by running it (BUG-437-A).
118
+ *
119
+ * The paths were never the hole — the sweeper builds those itself. The
120
+ * ALLOWLIST was, and an allowlist derived from file content is content
121
+ * steering a recursive delete just as surely as a path would be.
122
+ *
123
+ * So the test is the full shape, not a prefix test: the entry must be a
124
+ * prefix followed by EXACTLY the suffix `mkdtempSync` produces. A bare prefix
125
+ * with nothing after it is a directory someone made deliberately, and
126
+ * anything else is not a name this repo's tooling can have written.
127
+ *
128
+ * ONE anchored match, not a `startsWith` beside a slice at `p.length`. Those
129
+ * two are behaviourally identical on every input — relaxing `startsWith` to
130
+ * `includes` measured **0 of 24**, because the fixed offset refuses whatever
131
+ * the substring match would have let through. Two deciders that agree, with
132
+ * the delete still on the end of them. See
133
+ * `.claude/rules/checks-must-be-able-to-fail.md`.
134
+ */
135
+ export function isScratchEntry(entry: string, prefixes: string[]): boolean {
136
+ return prefixes.some(p =>
137
+ p.length > 1 && new RegExp(`^${escapeRegex(p)}${MKDTEMP_SUFFIX}$`).test(entry));
138
+ }
139
+
140
+ /**
141
+ * Remove leaked scratch directories from the repo root.
142
+ *
143
+ * Every path this deletes is one THIS function built, from
144
+ * `join(opts.repoRoot, entry)` where `entry` came from reading that same
145
+ * directory. No absolute path from any other source — not a config, not a
146
+ * prefix, not a `.git` file — can reach the `rmSync`. #436 learned that one
147
+ * the expensive way: content must never steer a recursive delete.
148
+ */
149
+ export function cleanupScratchDirs(opts: ScratchCleanupOptions): ScratchCleanupResult {
150
+ const result: ScratchCleanupResult = { removed: [], kept: [], refused: [], errors: [] };
151
+ const maxAgeMs = opts.maxAgeMs ?? ONE_HOUR_MS;
152
+ const prefixes = scratchPrefixes(opts.repoRoot);
153
+
154
+ let entries: string[];
155
+ try {
156
+ entries = readdirSync(opts.repoRoot);
157
+ } catch (err) {
158
+ result.errors.push(`Failed to read ${opts.repoRoot}: ${err}`);
159
+ return result;
160
+ }
161
+
162
+ for (const entry of entries) {
163
+ if (!isScratchEntry(entry, prefixes)) {
164
+ result.refused.push(entry);
165
+ continue;
166
+ }
167
+ const path = join(opts.repoRoot, entry);
168
+ let age: number;
169
+ try {
170
+ const stat = statSync(path);
171
+ if (!stat.isDirectory()) {
172
+ result.refused.push(entry);
173
+ continue;
174
+ }
175
+ age = Date.now() - stat.mtimeMs;
176
+ } catch (err) {
177
+ result.errors.push(`Failed to stat ${entry}: ${err}`);
178
+ continue;
179
+ }
180
+
181
+ if (age < maxAgeMs) {
182
+ result.kept.push(`${entry} (${Math.round(age / 1000)}s old — a suite may still be using it)`);
183
+ continue;
184
+ }
185
+ if (opts.dryRun) {
186
+ result.removed.push(`${entry} (dry run)`);
187
+ continue;
188
+ }
189
+ try {
190
+ rmSync(path, { recursive: true, force: true });
191
+ result.removed.push(entry);
192
+ } catch (err) {
193
+ result.errors.push(`Failed to remove ${entry}: ${err}`);
194
+ }
195
+ }
196
+
197
+ return result;
198
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The single owner of "what does a scratch root in this repo look like" (#437).
3
+ *
4
+ * Two questions are asked about the same source text, and they are asked from
5
+ * two different places:
6
+ *
7
+ * - `test/scratch-paths-unique.test.ts` asks which scratch roots are FIXED,
8
+ * because a fixed path under the shared checkout is a shared mutable
9
+ * resource (#323 SC-6).
10
+ * - `lib/scratch-cleanup.ts` asks which PREFIXES the unique ones use,
11
+ * because a sweeper needs to know what it is allowed to delete.
12
+ *
13
+ * They are the same parse. Two copies of it would be two deciders that agree —
14
+ * the fourth shape in `.claude/rules/checks-must-be-able-to-fail.md` — and
15
+ * worse than usual here, because the second decider's output is a deletion
16
+ * allowlist. A parser that quietly stopped seeing a prefix would not go red;
17
+ * it would stop sweeping, which is indistinguishable from nothing having
18
+ * leaked.
19
+ */
20
+
21
+ import { stripJsComments } from "./strip-js-comments";
22
+
23
+ /**
24
+ * Identifiers bound to the repository root, per file.
25
+ *
26
+ * `join(tmpDir, ".claude")` is a fixed name under an ALREADY-UNIQUE root —
27
+ * the suffix is on the parent, which is just as good. Only a path rooted at
28
+ * the shared checkout can collide, so the root is the thing to look at.
29
+ */
30
+ export function repoRootIdents(src: string): Set<string> {
31
+ const idents = new Set<string>();
32
+ for (const m of src.matchAll(/(?:const|let|var)?\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^;\n]+)/g)) {
33
+ if (/import\.meta\.dir|process\.cwd\(\)/.test(m[2]!)) idents.add(m[1]!);
34
+ }
35
+ return idents;
36
+ }
37
+
38
+ /**
39
+ * The declaration forms a scratch root can arrive in.
40
+ *
41
+ * `const` is matched optionally, and that is #437's doing rather than
42
+ * tidiness. Moving creation out of module scope means writing
43
+ * `let SCRATCH = ""` at the top and `SCRATCH = mkdtempSync(...)` inside
44
+ * `beforeAll`, and a `const`-only pattern stops seeing both forms at once —
45
+ * so the fix for the leak would have opened a hole in the guard against
46
+ * fixed paths. Measured: it is 3 red without the relaxation.
47
+ */
48
+ const DECL = /(?:const|let|var\s+)?\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(mkdtempSync\s*\(\s*)?join\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*"(\.[^"]*)"/g;
49
+
50
+ /** Navigation, not a scratch name. */
51
+ function isNavigation(literal: string): boolean {
52
+ return literal === "." || literal === ".." || literal.startsWith("../");
53
+ }
54
+
55
+ /** Scratch roots declared at a fixed path under the shared checkout. */
56
+ export function fixedScratchRoots(source: string): string[] {
57
+ const src = stripJsComments(source);
58
+ const roots = repoRootIdents(src);
59
+ const out: string[] = [];
60
+ for (const m of src.matchAll(new RegExp(DECL.source, "g"))) {
61
+ const [, name, wrapped, rootIdent, literal] = m;
62
+ if (wrapped) continue; // mkdtempSync — unique per run, which is the fix
63
+ if (!roots.has(rootIdent!)) continue; // already under a unique root
64
+ if (isNavigation(literal!)) continue;
65
+ // Only a directory this suite CREATES or DELETES is scratch. One it merely
66
+ // reads is configuration, and renaming it per run would break the read.
67
+ const mutates = new RegExp(`(?:mkdirSync|rmSync)\\(\\s*(?:join\\(\\s*)?${name}\\b`);
68
+ if (mutates.test(src)) out.push(`${name} = ${literal}`);
69
+ }
70
+ return out;
71
+ }
72
+
73
+ /**
74
+ * The `mkdtempSync` prefixes a file plants under the repo root.
75
+ *
76
+ * This is the other half of the same parse, and it is what the sweeper's
77
+ * allowlist is built from. It deliberately returns the prefix EXACTLY as
78
+ * written — including the trailing `-` that `mkdtempSync` appends its random
79
+ * suffix to — because a prefix widened by even one character is a wider
80
+ * deletion allowlist.
81
+ */
82
+ export function uniqueScratchPrefixes(source: string): string[] {
83
+ const src = stripJsComments(source);
84
+ const roots = repoRootIdents(src);
85
+ const out: string[] = [];
86
+ for (const m of src.matchAll(new RegExp(DECL.source, "g"))) {
87
+ const [, , wrapped, rootIdent, literal] = m;
88
+ if (!wrapped) continue; // a fixed path is the other function's subject
89
+ if (!roots.has(rootIdent!)) continue;
90
+ if (isNavigation(literal!)) continue;
91
+ if (!out.includes(literal!)) out.push(literal!);
92
+ }
93
+ return out;
94
+ }
@@ -11,6 +11,8 @@ import { spawnSync } from 'child_process';
11
11
  import { existsSync, readFileSync } from 'fs';
12
12
  import { join } from 'path';
13
13
 
14
+ import { tryLoadRungateConfig } from './config-loader';
15
+
14
16
  export interface CompletionCheckResult {
15
17
  passed: boolean;
16
18
  blockers: string[];
@@ -105,15 +107,60 @@ export function checkUncommittedChanges(projectRoot: string): CompletionCheckRes
105
107
  }
106
108
 
107
109
  /**
108
- * Run conformity checks if rungate.json exists.
110
+ * Run conformity checks if the project is scaffolded.
109
111
  * Returns blocker if conformity fails.
110
112
  */
111
113
  export function checkConformity(projectRoot: string): CompletionCheckResult {
112
114
  const blockers: string[] = [];
113
115
  const warnings: string[] = [];
114
116
 
115
- const rungateConfig = join(projectRoot, '.claude', 'rungate.json');
116
- if (!existsSync(rungateConfig)) {
117
+ // Either layout counts as scaffolded. The old existence check named the
118
+ // monolith only, so every consumer that followed the documented migration
119
+ // to `.claude/rungate/` stopped having its conformity suite run here —
120
+ // silently, reporting passed.
121
+ //
122
+ // The throw is CAUGHT and converted to a blocker, which is the one place in
123
+ // this migration that is not simply "let the loader throw". This function is
124
+ // reached from `hooks/TaskCompleted.hook.ts`, which has no catch of its own,
125
+ // and a hook that exits 1 is neither allow (0) nor block (2) — so an
126
+ // escaping throw would disable the entire completion gate, not just this
127
+ // check, on one unparseable byte. Blocking keeps ADR-001 D2's distinction
128
+ // (a corrupt config is never a missing config) and keeps the gate closed.
129
+ let configured: boolean;
130
+ try {
131
+ configured = tryLoadRungateConfig(projectRoot) !== null;
132
+ } catch (err: unknown) {
133
+ // The CLASS, not the message. `JSON.parse` quotes a token from the file it
134
+ // failed on — "Unexpected identifier \"ghp_…\"" — and a config can hold
135
+ // credentials, so the parser's text is a channel out of the file and into
136
+ // this blocker, which is printed to stderr and captured in transcripts.
137
+ // The reproduction command is the replacement for the detail: it gives the
138
+ // operator the full message on their own terminal, where the config
139
+ // already is.
140
+ const kind = err instanceof Error && err.name ? err.name : "error";
141
+ // No runnable command in the text, and the path is JSON-quoted.
142
+ //
143
+ // The first draft printed `bun -e '…${projectRoot}…'` for the operator to
144
+ // paste, which the push review called command injection and is: this is a
145
+ // library function, the root reaches it from the caller, and a path
146
+ // carrying `'; rm -rf ~; '` would have been printed as a command a human
147
+ // is being told to run. A refusal that hands someone a line to paste is
148
+ // an execution path with a person in the middle of it.
149
+ //
150
+ // `JSON.stringify` on the path escapes quotes and newlines, so a crafted
151
+ // root cannot end the sentence and forge a second one either.
152
+ return {
153
+ passed: false,
154
+ blockers: [
155
+ `rungate config under ${JSON.stringify(join(projectRoot, '.claude'))} could not be read ` +
156
+ `(${kind}), so conformity did not run — a config that exists and cannot be parsed is ` +
157
+ `not an unconfigured project. Load that root with loadRungateConfig from ` +
158
+ `lib/config-loader.ts to see the parser's own message.`,
159
+ ],
160
+ warnings: [],
161
+ };
162
+ }
163
+ if (!configured) {
117
164
  // No rungate config — skip conformity check
118
165
  return { passed: true, blockers: [], warnings: [] };
119
166
  }