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.
Files changed (113) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,247 @@
1
+ /**
2
+ * #804 / #323 — what a scan says about itself while it is still running.
3
+ *
4
+ * ## The gap this fills, and why the instrument next door does not fill it
5
+ *
6
+ * `lib/suite-timeout-margin.ts` (#811) composes `timeoutProximityViolations`
7
+ * over a JUnit report. It is the right reading and it is a reading taken
8
+ * AFTERWARDS: a `bun test` run cannot read its own report, because the file is
9
+ * written when the run ends. Three consequences, each of which is the whole of
10
+ * why this module exists rather than a call into that one:
11
+ *
12
+ * 1. **A killed case is a row with no message.** #804's subject in one
13
+ * sentence. The report says `TimeoutError` and `5005.68ms`; it does not
14
+ * say what the scan was reading at 5005ms, how many files it had got
15
+ * through, or what the budget was. An agent sees a red case named after a
16
+ * rule it has not broken and goes looking for a violation that does not
17
+ * exist.
18
+ * 2. **A per-test timeout SILENCES the proximity row**, deliberately —
19
+ * `lib/junit-checks.ts` says so in those words, and it is right to: an
20
+ * 8-second test that says it needs 8 seconds is a decision somebody made.
21
+ * So the case that carried `}, 60_000)` was the one case #804 is about
22
+ * AND the one case the #621 instrument could not see.
23
+ * 3. **Nothing has wired a report to it yet.** That decision is #804's own
24
+ * open half and is not taken here.
25
+ *
26
+ * This is therefore not a second decider for the question
27
+ * `suiteMarginReading` answers. That question is *"across a finished run's
28
+ * report, which cases ended near the budget"*. This one is *"while THIS scan
29
+ * is running, has it crossed its stated fraction of the budget, and on which
30
+ * path"* — a different population, a different clock, and an answer that has
31
+ * to exist before the runner's kill rather than after it. The budget itself
32
+ * has one reader for both: `bunfigTestTimeoutMs`.
33
+ *
34
+ * ## One comparison, read twice
35
+ *
36
+ * `scanBudgetViolations` is the only comparison in this file.
37
+ * `measureScan` calls it on a PARTIAL reading after each file and emits
38
+ * whatever it returns, and the caller calls it again on the final reading and
39
+ * asserts. Mid-scan emission is what survives a kill — a line already written
40
+ * to stdout is in the captured transcript whether or not the case lives to
41
+ * assert anything. A second renderer for the mid-scan line would be two
42
+ * deciders that agree (`.claude/rules/checks-must-be-able-to-fail.md`, fourth
43
+ * shape), so there is not one.
44
+ */
45
+ import { bunfigTestTimeoutMs } from "./junit-checks";
46
+
47
+ /**
48
+ * The fraction of the per-test budget a scan is allowed to spend: 50%.
49
+ *
50
+ * Not 1% and not 20%. Those are PROXIMITY bands — "this case nearly died" —
51
+ * and the two numbers `lib/suite-timeout-margin.ts` documents are the right
52
+ * ones for that question. This is a CEILING on a cost that grows with the
53
+ * tree, so it has to fire with room left to fix it, and it has to not fire on
54
+ * a loaded machine running a scan that is fine.
55
+ *
56
+ * Both halves, measured rather than asserted, against the 5000ms budget
57
+ * `bunfig.toml` declares:
58
+ *
59
+ * - **It catches the defect it was written for.** The pre-#798 scan was
60
+ * 3482ms idle over 378 files, and it is what took `main` red twice at
61
+ * 5005.68ms and 5172.46ms on loaded CI shards. 3482 is past 2500, so this
62
+ * reports it — by name, with a duration and a path — on an IDLE machine,
63
+ * before any shard is loaded.
64
+ * - **It does not fire on the scan that exists.** Measured 2026-10-21 on
65
+ * `41d287c5`: 174.68ms over 427 files, which is 3.5% of the budget. A
66
+ * false red needs 14.3x inflation. The observed idle-to-loaded inflation
67
+ * on the pre-#798 numbers is 5005/3482 = 1.44x.
68
+ *
69
+ * The cheapest wrong fix for a red here is to raise this number, and it is
70
+ * refused above 1 for a reason that is not tidiness: a ceiling at or past the
71
+ * budget cannot fire at all, because the runner kills the case first. Below 1
72
+ * it is a judgement call and a reviewer's problem, which is the right place
73
+ * for it.
74
+ */
75
+ export const SCAN_CEILING = 0.5;
76
+
77
+ export interface ScanBudgetReading {
78
+ /** The budget in force, or null when none could be read. */
79
+ budgetMs: number | null;
80
+ /** Wall-clock spent in the scan at the moment this reading was taken. */
81
+ elapsedMs: number;
82
+ /** Files read so far. */
83
+ filesRead: number;
84
+ /** Files the scan set out to read. */
85
+ filesTotal: number;
86
+ /** The directory being scanned — "which path it was scanning", at the top. */
87
+ root: string;
88
+ /** The file in hand when this reading was taken, if the scan is mid-flight. */
89
+ current: string | null;
90
+ /** The single costliest file, which is where a regression usually is. */
91
+ slowest: { path: string; ms: number } | null;
92
+ /** False for a mid-scan reading. An incomplete scan read fewer files than it will. */
93
+ complete: boolean;
94
+ }
95
+
96
+ /**
97
+ * Everything wrong with the reading AND everything wrong with what it read,
98
+ * as ONE list.
99
+ *
100
+ * FAILS CLOSED, in both directions that matter:
101
+ *
102
+ * - **No budget is not a clean scan.** A reading with nothing to compare
103
+ * against is UNMEASURED and says so by name. `0`, `null` and silence are
104
+ * indistinguishable from success (`.claude/rules/config-access.md`).
105
+ * - **An empty scan is not a fast scan.** A completed scan that read zero
106
+ * files finishes inside any budget by having nothing in it — the #492
107
+ * shape, and the one this check is most able to acquire by accident,
108
+ * because a `readdirSync` filter that stops matching produces exactly it.
109
+ */
110
+ export function scanBudgetViolations(r: ScanBudgetReading, ceiling: number = SCAN_CEILING): string[] {
111
+ const out: string[] = [];
112
+
113
+ if (!Number.isFinite(ceiling) || ceiling <= 0 || ceiling > 1) {
114
+ out.push(
115
+ `UNMEASURED: a scan ceiling of ${ceiling} is not a fraction of the budget. At or past 1 it can ` +
116
+ `never fire — the runner kills the case at the budget first — so raising it past 1 silences ` +
117
+ `this check rather than widening it (#804)`,
118
+ );
119
+ return out;
120
+ }
121
+
122
+ if (r.budgetMs === null || !Number.isFinite(r.budgetMs) || r.budgetMs <= 0) {
123
+ out.push(
124
+ `UNMEASURED: no usable per-test budget to compare ${r.elapsedMs.toFixed(2)}ms against ` +
125
+ `(read ${r.budgetMs}). bunfig.toml's [test] timeout is the one declaring position for it, and ` +
126
+ `defaulting to bun's built-in 5000 here would be a second one (#621, #804)`,
127
+ );
128
+ return out;
129
+ }
130
+
131
+ if (r.complete && r.filesRead === 0) {
132
+ out.push(
133
+ `UNMEASURED: the scan of ${r.root} completed having read 0 of ${r.filesTotal} files in ` +
134
+ `${r.elapsedMs.toFixed(2)}ms. An empty scan finishes inside any budget by having nothing in ` +
135
+ `it, so this is not a measurement of anything (#492, #804)`,
136
+ );
137
+ return out;
138
+ }
139
+
140
+ const limit = r.budgetMs * ceiling;
141
+ if (r.elapsedMs >= limit) {
142
+ const pct = ((r.elapsedMs / r.budgetMs) * 100).toFixed(1);
143
+ const per = r.filesRead > 0 ? (r.elapsedMs / r.filesRead).toFixed(2) : "n/a";
144
+ const where = r.current !== null ? ` scanning ${r.current}` : "";
145
+ const slowest =
146
+ r.slowest !== null ? ` Costliest file so far: ${r.slowest.path} at ${r.slowest.ms.toFixed(2)}ms.` : "";
147
+ out.push(
148
+ `the scan of ${r.root} has spent ${r.elapsedMs.toFixed(2)}ms of its ${r.budgetMs}ms per-test budget ` +
149
+ `(${pct}%, ceiling ${ceiling * 100}% = ${limit.toFixed(0)}ms) after ${r.filesRead} of ` +
150
+ `${r.filesTotal} files${where} — ${per}ms per file.${slowest} ` +
151
+ `Make the scan cheaper or stop re-reading what it already knows. Raising the ceiling, or giving ` +
152
+ `the case a per-test timeout of its own, moves the same red further away AND takes this case out ` +
153
+ `of the #621 proximity reading, which is how #804 happened (#804, #323)`,
154
+ );
155
+ }
156
+ return out;
157
+ }
158
+
159
+ /** The sentence a caller prints beside a reading, violations or not. */
160
+ export function describeScanBudget(r: ScanBudgetReading, ceiling: number = SCAN_CEILING): string {
161
+ const v = scanBudgetViolations(r, ceiling);
162
+ const head =
163
+ v.length > 0
164
+ ? `${v.length} finding(s) for the scan of ${r.root}:`
165
+ : `MEASURED: the scan of ${r.root} read ${r.filesRead} of ${r.filesTotal} files in ` +
166
+ `${r.elapsedMs.toFixed(2)}ms, ${((r.elapsedMs / (r.budgetMs || NaN)) * 100).toFixed(1)}% of the ` +
167
+ `${r.budgetMs}ms budget (ceiling ${ceiling * 100}%).`;
168
+ return [head, ...v.map(x => ` - ${x}`)].join("\n");
169
+ }
170
+
171
+ /**
172
+ * The budget in force for the tree rooted at `root`, read from its
173
+ * `bunfig.toml`, or null when it declares none.
174
+ *
175
+ * One reader, shared with #621 and #811. A copy of the TOML parse here would
176
+ * be a second decider over one key.
177
+ */
178
+ export function scanBudgetFromBunfig(source: string | null): number | null {
179
+ return source === null ? null : bunfigTestTimeoutMs(source);
180
+ }
181
+
182
+ /**
183
+ * Run `read` over `files`, timing each one, and emit the moment the scan
184
+ * crosses its ceiling.
185
+ *
186
+ * The emission is the point. An assertion after the loop is unreachable on
187
+ * the run that matters — the one where the runner kills the case — and a
188
+ * killed case is #804's whole subject. A line already on stdout is in the
189
+ * captured transcript regardless, which is #323's SC-3 arriving at the place
190
+ * where a name is lost rather than at the transport.
191
+ *
192
+ * Emits AT MOST ONCE. A warning on every one of 427 iterations is a warning
193
+ * nobody reads, which is the failure mode #804's own thread recorded for the
194
+ * UNMEASURED line that had printed on every run for a month.
195
+ *
196
+ * `now` and `emit` are injected so a case can drive a slow scan without being
197
+ * slow, and read what was emitted without capturing a stream.
198
+ */
199
+ export function measureScan<T>(opts: {
200
+ root: string;
201
+ files: string[];
202
+ budgetMs: number | null;
203
+ read: (file: string) => T[];
204
+ ceiling?: number;
205
+ now?: () => number;
206
+ emit?: (line: string) => void;
207
+ }): { values: T[]; reading: ScanBudgetReading } {
208
+ const ceiling = opts.ceiling ?? SCAN_CEILING;
209
+ const now = opts.now ?? (() => performance.now());
210
+ const emit = opts.emit ?? ((line: string) => console.error(line));
211
+
212
+ const started = now();
213
+ const values: T[] = [];
214
+ let slowest: { path: string; ms: number } | null = null;
215
+ let emitted = false;
216
+ let filesRead = 0;
217
+
218
+ const readingAt = (current: string | null, complete: boolean): ScanBudgetReading => ({
219
+ budgetMs: opts.budgetMs,
220
+ elapsedMs: now() - started,
221
+ filesRead,
222
+ filesTotal: opts.files.length,
223
+ root: opts.root,
224
+ current,
225
+ slowest,
226
+ complete,
227
+ });
228
+
229
+ for (const file of opts.files) {
230
+ const before = now();
231
+ values.push(...opts.read(file));
232
+ const cost = now() - before;
233
+ filesRead += 1;
234
+ if (slowest === null || cost > slowest.ms) slowest = { path: file, ms: cost };
235
+
236
+ if (!emitted) {
237
+ // The SAME comparison the caller will assert on, over a partial reading.
238
+ const found = scanBudgetViolations(readingAt(file, false), ceiling);
239
+ if (found.length > 0) {
240
+ emitted = true;
241
+ for (const line of found) emit(`[#804] ${line}`);
242
+ }
243
+ }
244
+ }
245
+
246
+ return { values, reading: readingAt(null, true) };
247
+ }
package/lib/scanner.ts CHANGED
@@ -8,7 +8,8 @@
8
8
  * no generation logic (agents-md, agent-briefs, code-map) is imported here
9
9
  * (SC-365, AC-3).
10
10
  */
11
- import { existsSync, readFileSync, readdirSync, statSync } from "fs";
11
+ import { existsSync, readFileSync, statSync } from "fs";
12
+ import { readdirSorted } from "./readdir-sorted";
12
13
  import { join, basename } from "path";
13
14
  import { resolveConfig } from "./config-loader";
14
15
  // A leaf, not a generator. SC-365 / AC-3 keeps generation logic out of the
@@ -17,7 +18,9 @@ import { resolveConfig } from "./config-loader";
17
18
  // instead of drifting apart (#380).
18
19
  import { isHarnessItself } from "./harness-identity";
19
20
  import { isSpecFile } from "./spec-listing";
21
+ import { scanDocsDirectory } from "./doc-routing";
20
22
  import { testCommandDecision } from "./test-command";
23
+ import { projectStateDerivation, projectStateKeyFileNote } from "./project-state-derivation";
21
24
  import type {
22
25
  ProjectScan,
23
26
  ProjectType,
@@ -106,7 +109,14 @@ function detectTechStack(root: string): string[] {
106
109
 
107
110
  // ── Spec scanning ──────────────────────────────────────────────
108
111
 
109
- function scanSpecs(root: string): SpecEntry[] {
112
+ /**
113
+ * Exported for `lib/scaffold/steps.ts`, which used to answer this question
114
+ * with its own copy. The copy drifted three times — #382's `SPEC-TEMPLATE.md`
115
+ * filter and #579's `criteriaNone` and `testable` derivation — each time
116
+ * because a fix landed here and nobody knew a second implementation existed.
117
+ * One derivation, so the next fix cannot land in only half of them (#827).
118
+ */
119
+ export function scanSpecs(root: string): SpecEntry[] {
110
120
  const specsDir = join(root, "specs");
111
121
  if (!existsSync(specsDir)) return [];
112
122
 
@@ -115,7 +125,7 @@ function scanSpecs(root: string): SpecEntry[] {
115
125
  // `lib/scaffold/steps.ts` answered the same question with its own filter
116
126
  // and reached the opposite verdict for `SPEC-TEMPLATE.md`, so the one file
117
127
  // this table deliberately omits was reported as missing from it (#382).
118
- const specFiles = readdirSync(specsDir).filter(isSpecFile);
128
+ const specFiles = readdirSorted(specsDir).filter(isSpecFile);
119
129
 
120
130
  for (const f of specFiles) {
121
131
  const content = readFileSync(join(specsDir, f), "utf-8");
@@ -143,13 +153,12 @@ function scanSpecs(root: string): SpecEntry[] {
143
153
 
144
154
  // Also scan specs subdirectories
145
155
  try {
146
- const specSubDirs = readdirSync(specsDir, { withFileTypes: true })
147
- .filter(d => d.isDirectory())
148
- .map(d => d.name);
156
+ const specSubDirs = readdirSorted(specsDir)
157
+ .filter(n => { try { return statSync(join(specsDir, n)).isDirectory(); } catch { return false; } });
149
158
 
150
159
  for (const sub of specSubDirs) {
151
160
  const subPath = join(specsDir, sub);
152
- const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md") && f !== "INDEX.md");
161
+ const subFiles = readdirSorted(subPath).filter(f => f.endsWith(".md") && f !== "INDEX.md");
153
162
  if (subFiles.length > 0) {
154
163
  const indexPath = join(subPath, "INDEX.md");
155
164
  let groupGoverns = `${sub} (${subFiles.length} specs)`;
@@ -205,7 +214,7 @@ function detectConsumers(root: string): string[] {
205
214
  const consumers: string[] = [];
206
215
  const consumerPatterns = ["-routes.ts", "-generator.ts", "-plan.ts", "-intel.ts"];
207
216
 
208
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts"))) {
217
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts"))) {
209
218
  try {
210
219
  const content = readFileSync(join(srcDir, f), "utf-8");
211
220
  const isConsumer = consumerPatterns.some(p => f.includes(p)) ||
@@ -233,7 +242,7 @@ function scanKeyFiles(root: string): KeyFile[] {
233
242
  // Always include scaffold-generated files for idempotency (SC-364)
234
243
  const keyFiles: KeyFile[] = [
235
244
  { file: "AGENTS.md", what: "Project entry point", when: "Always first" },
236
- { file: "PROJECT-STATE.md", what: "Live status + handoff (generated from project-state.json — don't edit directly)", when: "Session start, always first after AGENTS.md" },
245
+ { file: "PROJECT-STATE.md", what: projectStateKeyFileNote(projectStateDerivation(root)), when: "Session start, always first after AGENTS.md" },
237
246
  { file: "project-state.json", what: "Source of truth for project status", when: "When editing state" },
238
247
  ];
239
248
 
@@ -280,7 +289,7 @@ function scanTestFiles(root: string): TestFile[] {
280
289
  if (!testDir) return [];
281
290
 
282
291
  try {
283
- return readdirSync(join(root, testDir))
292
+ return readdirSorted(join(root, testDir))
284
293
  .filter(f => f.endsWith(".test.ts"))
285
294
  .map(f => ({
286
295
  label: f.replace(".test.ts", "").replace(/-/g, " "),
@@ -298,7 +307,7 @@ function scanRefFiles(root: string): RefFile[] {
298
307
  if (!existsSync(refDir)) return [];
299
308
 
300
309
  try {
301
- return readdirSync(refDir).map(f => ({
310
+ return readdirSorted(refDir).map(f => ({
302
311
  file: f,
303
312
  what: "Historical reference",
304
313
  }));
@@ -338,7 +347,7 @@ function scanDocRouting(root: string, categories: Category[]): DocRoute[] {
338
347
  // Recursive: reference/ held 19 markdown files, every one of them in a
339
348
  // subdirectory, and a shallow count advertised it as "(0 files)" (#91).
340
349
  // A row saying a directory is empty reads as an instruction not to look.
341
- const files = readdirSync(catPath, { recursive: true }).map(String).filter(f => f.endsWith(".md"));
350
+ const files = readdirSorted(catPath, { recursive: true }).filter(f => f.endsWith(".md"));
342
351
  docRouting.push({ need: `${cat.label} (${files.length} files)`, file: `${cat.dir}/` });
343
352
  } catch {
344
353
  docRouting.push({ need: cat.label, file: `${cat.dir}/` });
@@ -348,41 +357,24 @@ function scanDocRouting(root: string, categories: Category[]): DocRoute[] {
348
357
  }
349
358
  }
350
359
 
351
- // Docs top-level files
352
- const docsDir = join(root, "docs");
353
- if (existsSync(docsDir)) {
354
- try {
355
- const allDocs = readdirSync(docsDir).filter(f => f.endsWith(".md"));
356
- for (const f of allDocs) {
357
- const docPath = join(docsDir, f);
358
- const content = readFileSync(docPath, "utf-8");
359
- const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
360
- let need = f.replace(/\.md$/, "").replace(/-/g, " ");
361
- if (fmMatch) {
362
- const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
363
- if (gMatch && gMatch[1].trim() !== "TODO") need = gMatch[1].trim();
364
- }
365
- docRouting.push({ need, file: `docs/${f}` });
366
- }
367
- const subDirs = readdirSync(docsDir, { withFileTypes: true })
368
- .filter(d => d.isDirectory() && !categories.some(c => c.dir === `docs/${d.name}`))
369
- .map(d => d.name);
370
- for (const sub of subDirs) {
371
- const subPath = join(docsDir, sub);
372
- const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md"));
373
- if (subFiles.length > 0) {
374
- docRouting.push({ need: `${sub} (${subFiles.length} files)`, file: `docs/${sub}/` });
375
- }
376
- }
377
- } catch {}
378
- }
360
+ // Docs top-level files and subdirectories, through the one binding (#617,
361
+ // #619). This was a complete second copy of `lib/scaffold/steps.ts`'s scan,
362
+ // with its own inline `governs:` regex — which is how one site could learn
363
+ // about a new frontmatter field and the other not.
364
+ try {
365
+ docRouting.push(...scanDocsDirectory(join(root, "docs"), categories.map(c => c.dir)));
366
+ } catch {}
379
367
 
380
- // Filter to non-obvious mappings
381
- return docRouting.filter(d => {
382
- const slug = d.file.replace(/\.md$/, "").replace(/.*\//, "").toLowerCase().replace(/-/g, " ");
383
- const needLower = d.need.toLowerCase();
384
- return !needLower.startsWith(slug) || d.need.includes("—") || d.need.includes("(");
385
- });
368
+ // The "filter to non-obvious mappings" that used to end this function is
369
+ // deleted (#617). It could only ever drop a top-level `docs/*.md`: every
370
+ // other row's description contains an em dash or a parenthesis, or does not
371
+ // begin with its own filename. Dropping those IS the defect — 38 of 38 on
372
+ // one consumer — and a document with no `governs:` is UNMEASURED, not
373
+ // "governs nothing". Exclusion is the document's own declaration now, read
374
+ // once in `topLevelDocRoute`. Keeping the filter as well would leave a
375
+ // second decider that no mutation could distinguish from live code, since
376
+ // the marker it emits already defeats it.
377
+ return docRouting;
386
378
  }
387
379
 
388
380
  // ── Identity detection ─────────────────────────────────────────
@@ -478,13 +470,13 @@ function scanDirs(root: string): DirEntry[] {
478
470
  const dirs: DirEntry[] = [];
479
471
 
480
472
  try {
481
- for (const entry of readdirSync(root)) {
473
+ for (const entry of readdirSorted(root)) {
482
474
  if (entry.startsWith(".") && entry !== ".claude") continue;
483
475
  if (skip.has(entry)) continue;
484
476
  const full = join(root, entry);
485
477
  try {
486
478
  if (!statSync(full).isDirectory()) continue;
487
- const files = readdirSync(full, { recursive: true }).map(String);
479
+ const files = readdirSorted(full, { recursive: true });
488
480
  const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
489
481
  dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
490
482
  } catch {}
@@ -502,7 +494,7 @@ function scanModules(root: string): ModuleEntry[] {
502
494
  if (!existsSync(srcDir)) return modules;
503
495
 
504
496
  try {
505
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
497
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
506
498
  const content = readFileSync(join(srcDir, f), "utf-8");
507
499
  const exports: string[] = [];
508
500
  const exportPattern = /export\s+(?:function|const|class|type|interface)\s+(\w+)/g;
@@ -522,7 +514,7 @@ function scanRoutes(root: string): RouteEntry[] {
522
514
  if (!existsSync(srcDir)) return routes;
523
515
 
524
516
  try {
525
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
517
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts") || f.endsWith(".js"))) {
526
518
  const content = readFileSync(join(srcDir, f), "utf-8");
527
519
  const routePatterns = [
528
520
  /app\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi,
@@ -582,7 +574,7 @@ function scanPromptRouting(root: string, harness: Record<string, any> | null): R
582
574
  if (!existsSync(promptsDir)) return promptsByAgent;
583
575
 
584
576
  try {
585
- const promptFiles = readdirSync(promptsDir).filter(f => f.endsWith(".md"));
577
+ const promptFiles = readdirSorted(promptsDir).filter(f => f.endsWith(".md"));
586
578
  for (const f of promptFiles) {
587
579
  const content = readFileSync(join(promptsDir, f), "utf-8");
588
580
  const lower = f.toLowerCase();
@@ -29,7 +29,7 @@ import { stripJsComments } from "./strip-js-comments";
29
29
  */
30
30
  export function repoRootIdents(src: string): Set<string> {
31
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)) {
32
+ for (const m of src.matchAll(/([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^;\n]+)/g)) {
33
33
  if (/import\.meta\.dir|process\.cwd\(\)/.test(m[2]!)) idents.add(m[1]!);
34
34
  }
35
35
  return idents;
@@ -38,14 +38,51 @@ export function repoRootIdents(src: string): Set<string> {
38
38
  /**
39
39
  * The declaration forms a scratch root can arrive in.
40
40
  *
41
- * `const` is matched optionally, and that is #437's doing rather than
42
- * tidiness. Moving creation out of module scope means writing
41
+ * The keyword is not matched AT ALL, and that is #437's requirement rather
42
+ * than tidiness. Moving creation out of module scope means writing
43
43
  * `let SCRATCH = ""` at the top and `SCRATCH = mkdtempSync(...)` inside
44
44
  * `beforeAll`, and a `const`-only pattern stops seeing both forms at once —
45
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.
46
+ * fixed paths. Measured: it is 3 red if the keyword is required.
47
+ *
48
+ * It used to be matched OPTIONALLY — `(?:const|let|var\s+)?\s*` in front of
49
+ * the identifier — which satisfies #437 and is what #793 is about. An
50
+ * optional group with nothing required before it starts a backtracking
51
+ * attempt at essentially every offset: 1716ms over this repository's `test/`,
52
+ * and still 1712ms with the whole `join(...)` tail deleted, so the cost was
53
+ * never in the tail. The group was optional AND non-capturing, so it fed no
54
+ * capture and deleting it changes no output that is not a misparse: 32ms,
55
+ * with a byte-identical 400-element ident list over the real tree.
56
+ *
57
+ * The one input on which the two readings differ is an identifier literally
58
+ * beginning with a keyword — `letROOT = join(import.meta.dir, "..")`. The old
59
+ * pattern consumed `let` and captured `ROOT`, a variable nothing declared,
60
+ * and a root identifier nothing declared puts an unrelated `join(ROOT, ...)`
61
+ * prefix into a recursive-delete allowlist. Reading the identifier whole
62
+ * narrows that allowlist. See the #793 cases in `test/scratch-cleanup.test.ts`,
63
+ * which hold the equivalence element by element against a frozen copy of the
64
+ * old parse.
65
+ */
66
+ const DECL = /([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(mkdtempSync\s*\(\s*)?join\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*"(\.[^"]*)"/g;
67
+
68
+ /**
69
+ * The same pattern, un-anchored and non-global, used only to decide whether
70
+ * the expensive path is worth entering.
71
+ *
72
+ * DERIVED FROM `DECL`, never written out a second time. A hand-copied probe
73
+ * that drifts from the real pattern is how a guard goes quiet: it would skip
74
+ * the file the real regex was about to match on, report `[]`, and read as a
75
+ * clean scan. Building it from `DECL.source` means the two cannot disagree.
76
+ *
77
+ * Non-global on purpose — `.test()` on a `/g` regex advances `lastIndex` and
78
+ * returns a different answer on the next call with the same input.
79
+ *
80
+ * Sound because `stripJsComments` only ever REMOVES text: if the raw source
81
+ * cannot match, the stripped source cannot match either. The converse is not
82
+ * true — a match inside a comment enters the slow path and is then discarded
83
+ * there, which costs time and never costs correctness.
47
84
  */
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;
85
+ const DECL_PROBE = new RegExp(DECL.source);
49
86
 
50
87
  /** Navigation, not a scratch name. */
51
88
  function isNavigation(literal: string): boolean {
@@ -54,6 +91,14 @@ function isNavigation(literal: string): boolean {
54
91
 
55
92
  /** Scratch roots declared at a fixed path under the shared checkout. */
56
93
  export function fixedScratchRoots(source: string): string[] {
94
+ // 379 test files, 5.8MB, and 75 of them can possibly match. Stripping
95
+ // comments from the other 304 cost 3.5s of the 5s budget and found nothing
96
+ // — enough that this test timed out on a Mini running five CI jobs while
97
+ // passing in milliseconds on an idle laptop. Skipping them is 906ms.
98
+ //
99
+ // A timeout bump was the other option and is the wrong one: it makes the
100
+ // red slower to arrive without making the scan any more able to finish.
101
+ if (!DECL_PROBE.test(source)) return [];
57
102
  const src = stripJsComments(source);
58
103
  const roots = repoRootIdents(src);
59
104
  const out: string[] = [];
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Where a prove run's UI evidence lives, and what is actually in it (#809).
3
+ *
4
+ * ## The defect
5
+ *
6
+ * `workflows/prove.js` globbed **all of `/tmp`** for
7
+ * `playwright-screenshot.*\.png$|browser-screenshot.*\.png$`, handed every
8
+ * match to `uploadScreenshotsToIssue`, and embedded the resulting PUBLIC gist
9
+ * links in a PR comment. Nothing scoped that read to this run, this issue, or
10
+ * this project, on a machine that routinely carries a dozen concurrent
11
+ * worktrees.
12
+ *
13
+ * It never fired, and the reason is worth keeping because it is the more
14
+ * serious half. Playwright's `browser_take_screenshot` writes
15
+ * `.playwright-mcp/page-{timestamp}.png` under the workspace root when given
16
+ * no `filename` — not `/tmp`, and matching neither pattern. Measured across
17
+ * the machine this was found on: 96 files produced by the tool between
18
+ * 2026-09-28 and 2026-10-19, and zero ever named for either pattern. So the
19
+ * glob could not match its producer, UI evidence had never been attached to
20
+ * any pull request, and the phase reported success every time because
21
+ * `markdownLinks.length > 0` was simply false.
22
+ *
23
+ * ## Why a directory rather than a better pattern
24
+ *
25
+ * A narrower glob is still a guess about a filename somebody else chooses.
26
+ * `prove.js` now creates this directory, tells Quinn to write into it, and
27
+ * reads nothing else — so a concurrent run cannot place a file where this
28
+ * one will find it. That is a property of the layout rather than a prediction
29
+ * about names, and it closes the exposure instead of narrowing it.
30
+ *
31
+ * The `--public` flag in `lib/screenshot-upload.ts` is deliberately NOT
32
+ * touched here. Whether evidence is world-readable is a disclosure decision
33
+ * for the repository owner, and changing it inside a scoping fix would make
34
+ * that decision look like a cleanup.
35
+ */
36
+
37
+ import { existsSync, readdirSync, statSync } from "fs";
38
+ import { join } from "path";
39
+
40
+ /**
41
+ * The directory a prove run writes and reads its screenshots in.
42
+ *
43
+ * Derived from `WORK_DIR`, which `prove.js` already scopes per issue, so two
44
+ * issues cannot share one. A plain subdirectory rather than `mkdtemp`: the
45
+ * name has to be computable twice — once to tell Quinn, once to read it back
46
+ * — and a random suffix would have to be threaded through an agent prompt and
47
+ * returned intact, which is a second decider about the same path.
48
+ */
49
+ export function screenshotDirFor(workDir: string): string {
50
+ return join(workDir, "screenshots");
51
+ }
52
+
53
+ /**
54
+ * What a scan of that directory found.
55
+ *
56
+ * Three cases, not two, because the old code had one. `missing` and `none`
57
+ * both produced an empty array, `markdownLinks.length > 0` was false for
58
+ * both, and the phase reported success either way — so a feature that had
59
+ * never worked was indistinguishable from a run with nothing to show. The
60
+ * distinction is the fix for that, and it only means anything because
61
+ * `prove.js` creates the directory BEFORE Quinn runs: after that, empty is a
62
+ * statement about Quinn and absent is a statement about us.
63
+ */
64
+ export type ScreenshotScan =
65
+ | { kind: "found"; dir: string; files: string[] }
66
+ | { kind: "none"; dir: string }
67
+ | { kind: "missing"; dir: string };
68
+
69
+ /** PNG only. The tool drops `.yml` snapshots and `.log` console dumps beside its images. */
70
+ function isScreenshot(name: string): boolean {
71
+ return name.toLowerCase().endsWith(".png");
72
+ }
73
+
74
+ /**
75
+ * Lists the names in a directory. A seam, for one reason: the sort below.
76
+ *
77
+ * `readdirSync` returns sorted order on the filesystem this was written on,
78
+ * so a battery row that deleted the `.sort()` measured **0 red** — the
79
+ * mechanism was present and unprovable, and a sort nothing can witness is a
80
+ * sort somebody later deletes as dead code. Handing the lister in lets a case
81
+ * return names in the wrong order on purpose. Same shape as `GistCreator` in
82
+ * `lib/screenshot-upload.ts`.
83
+ */
84
+ export type DirLister = (dir: string) => string[];
85
+
86
+ const realLister: DirLister = dir => readdirSync(dir);
87
+
88
+ /**
89
+ * Reads exactly one directory, non-recursively, and reports what is in it.
90
+ *
91
+ * Returns absolute paths because the only consumer hands them to
92
+ * `uploadScreenshotsToIssue`, which calls `existsSync` on each — a relative
93
+ * path there resolves against whatever the process cwd happens to be and
94
+ * lands in `failed` with no explanation.
95
+ *
96
+ * Sorted, so the order evidence appears in a PR comment is the order the
97
+ * filenames imply rather than the order the filesystem offers.
98
+ */
99
+ export function discoverScreenshots(dir: string, list: DirLister = realLister): ScreenshotScan {
100
+ if (!existsSync(dir)) return { kind: "missing", dir };
101
+
102
+ const files = list(dir)
103
+ .filter(isScreenshot)
104
+ .map(name => join(dir, name))
105
+ .filter(path => statSync(path).isFile())
106
+ .sort();
107
+
108
+ return files.length === 0 ? { kind: "none", dir } : { kind: "found", dir, files };
109
+ }
110
+
111
+ /** One sentence for the run log, so each of the three readings is legible. */
112
+ export function describeScan(scan: ScreenshotScan): string {
113
+ switch (scan.kind) {
114
+ case "found":
115
+ return `${scan.files.length} screenshot(s) from ${scan.dir}`;
116
+ case "none":
117
+ return `no screenshots: Quinn ran and wrote none into ${scan.dir}`;
118
+ case "missing":
119
+ return `UNMEASURED: ${scan.dir} does not exist, so no screenshot was ever looked for`;
120
+ }
121
+ }