rungate 0.5.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 (142) 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 +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -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
@@ -16,6 +17,10 @@ import { resolveConfig } from "./config-loader";
16
17
  // exists precisely so this module and the generators can share one answer
17
18
  // instead of drifting apart (#380).
18
19
  import { isHarnessItself } from "./harness-identity";
20
+ import { isSpecFile } from "./spec-listing";
21
+ import { scanDocsDirectory } from "./doc-routing";
22
+ import { testCommandDecision } from "./test-command";
23
+ import { projectStateDerivation, projectStateKeyFileNote } from "./project-state-derivation";
19
24
  import type {
20
25
  ProjectScan,
21
26
  ProjectType,
@@ -104,12 +109,23 @@ function detectTechStack(root: string): string[] {
104
109
 
105
110
  // ── Spec scanning ──────────────────────────────────────────────
106
111
 
107
- 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[] {
108
120
  const specsDir = join(root, "specs");
109
121
  if (!existsSync(specsDir)) return [];
110
122
 
111
123
  const specs: SpecEntry[] = [];
112
- const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md");
124
+ // `isSpecFile`, not an inline name comparison. The audit in
125
+ // `lib/scaffold/steps.ts` answered the same question with its own filter
126
+ // and reached the opposite verdict for `SPEC-TEMPLATE.md`, so the one file
127
+ // this table deliberately omits was reported as missing from it (#382).
128
+ const specFiles = readdirSorted(specsDir).filter(isSpecFile);
113
129
 
114
130
  for (const f of specFiles) {
115
131
  const content = readFileSync(join(specsDir, f), "utf-8");
@@ -126,18 +142,23 @@ function scanSpecs(root: string): SpecEntry[] {
126
142
  if (tMatch) testable = tMatch[1].trim();
127
143
  }
128
144
 
129
- specs.push({ file: f, governs, testable });
145
+ // #579. A row in this table promises a reader that the document on the
146
+ // other end governs something. When the document says it states no
147
+ // criteria, the row says so too — see `lib/spec-requirements.ts` for why
148
+ // the declaration lives in frontmatter rather than in an allowlist.
149
+ const criteriaNone = /^criteria:\s*none\s*$/m.test(fmMatch?.[1] ?? "");
150
+
151
+ specs.push({ file: f, governs, testable, criteriaNone });
130
152
  }
131
153
 
132
154
  // Also scan specs subdirectories
133
155
  try {
134
- const specSubDirs = readdirSync(specsDir, { withFileTypes: true })
135
- .filter(d => d.isDirectory())
136
- .map(d => d.name);
156
+ const specSubDirs = readdirSorted(specsDir)
157
+ .filter(n => { try { return statSync(join(specsDir, n)).isDirectory(); } catch { return false; } });
137
158
 
138
159
  for (const sub of specSubDirs) {
139
160
  const subPath = join(specsDir, sub);
140
- 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");
141
162
  if (subFiles.length > 0) {
142
163
  const indexPath = join(subPath, "INDEX.md");
143
164
  let groupGoverns = `${sub} (${subFiles.length} specs)`;
@@ -151,7 +172,24 @@ function scanSpecs(root: string): SpecEntry[] {
151
172
  }
152
173
  }
153
174
  }
154
- specs.push({ file: `${sub}/ (${subFiles.length} specs)`, governs: groupGoverns, testable: "yes" });
175
+ // `"yes"` was a literal here, and every reader of this field compares
176
+ // against the string `"true"` — so the group row has always rendered
177
+ // a word that means false to the code and true to a reader (#579).
178
+ // Derived from the members instead: testable if any of them is.
179
+ const anyTestable = subFiles.some(sf => {
180
+ try {
181
+ return /^testable:\s*true\s*$/m.test(
182
+ readFileSync(join(subPath, sf), "utf-8").match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "",
183
+ );
184
+ } catch {
185
+ return false;
186
+ }
187
+ });
188
+ specs.push({
189
+ file: `${sub}/ (${subFiles.length} specs)`,
190
+ governs: groupGoverns,
191
+ testable: String(anyTestable),
192
+ });
155
193
  }
156
194
  }
157
195
  } catch {}
@@ -176,7 +214,7 @@ function detectConsumers(root: string): string[] {
176
214
  const consumers: string[] = [];
177
215
  const consumerPatterns = ["-routes.ts", "-generator.ts", "-plan.ts", "-intel.ts"];
178
216
 
179
- for (const f of readdirSync(srcDir).filter(f => f.endsWith(".ts"))) {
217
+ for (const f of readdirSorted(srcDir).filter(f => f.endsWith(".ts"))) {
180
218
  try {
181
219
  const content = readFileSync(join(srcDir, f), "utf-8");
182
220
  const isConsumer = consumerPatterns.some(p => f.includes(p)) ||
@@ -204,7 +242,7 @@ function scanKeyFiles(root: string): KeyFile[] {
204
242
  // Always include scaffold-generated files for idempotency (SC-364)
205
243
  const keyFiles: KeyFile[] = [
206
244
  { file: "AGENTS.md", what: "Project entry point", when: "Always first" },
207
- { 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" },
208
246
  { file: "project-state.json", what: "Source of truth for project status", when: "When editing state" },
209
247
  ];
210
248
 
@@ -251,7 +289,7 @@ function scanTestFiles(root: string): TestFile[] {
251
289
  if (!testDir) return [];
252
290
 
253
291
  try {
254
- return readdirSync(join(root, testDir))
292
+ return readdirSorted(join(root, testDir))
255
293
  .filter(f => f.endsWith(".test.ts"))
256
294
  .map(f => ({
257
295
  label: f.replace(".test.ts", "").replace(/-/g, " "),
@@ -269,7 +307,7 @@ function scanRefFiles(root: string): RefFile[] {
269
307
  if (!existsSync(refDir)) return [];
270
308
 
271
309
  try {
272
- return readdirSync(refDir).map(f => ({
310
+ return readdirSorted(refDir).map(f => ({
273
311
  file: f,
274
312
  what: "Historical reference",
275
313
  }));
@@ -309,7 +347,7 @@ function scanDocRouting(root: string, categories: Category[]): DocRoute[] {
309
347
  // Recursive: reference/ held 19 markdown files, every one of them in a
310
348
  // subdirectory, and a shallow count advertised it as "(0 files)" (#91).
311
349
  // A row saying a directory is empty reads as an instruction not to look.
312
- 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"));
313
351
  docRouting.push({ need: `${cat.label} (${files.length} files)`, file: `${cat.dir}/` });
314
352
  } catch {
315
353
  docRouting.push({ need: cat.label, file: `${cat.dir}/` });
@@ -319,41 +357,24 @@ function scanDocRouting(root: string, categories: Category[]): DocRoute[] {
319
357
  }
320
358
  }
321
359
 
322
- // Docs top-level files
323
- const docsDir = join(root, "docs");
324
- if (existsSync(docsDir)) {
325
- try {
326
- const allDocs = readdirSync(docsDir).filter(f => f.endsWith(".md"));
327
- for (const f of allDocs) {
328
- const docPath = join(docsDir, f);
329
- const content = readFileSync(docPath, "utf-8");
330
- const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
331
- let need = f.replace(/\.md$/, "").replace(/-/g, " ");
332
- if (fmMatch) {
333
- const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
334
- if (gMatch && gMatch[1].trim() !== "TODO") need = gMatch[1].trim();
335
- }
336
- docRouting.push({ need, file: `docs/${f}` });
337
- }
338
- const subDirs = readdirSync(docsDir, { withFileTypes: true })
339
- .filter(d => d.isDirectory() && !categories.some(c => c.dir === `docs/${d.name}`))
340
- .map(d => d.name);
341
- for (const sub of subDirs) {
342
- const subPath = join(docsDir, sub);
343
- const subFiles = readdirSync(subPath).filter(f => f.endsWith(".md"));
344
- if (subFiles.length > 0) {
345
- docRouting.push({ need: `${sub} (${subFiles.length} files)`, file: `docs/${sub}/` });
346
- }
347
- }
348
- } catch {}
349
- }
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 {}
350
367
 
351
- // Filter to non-obvious mappings
352
- return docRouting.filter(d => {
353
- const slug = d.file.replace(/\.md$/, "").replace(/.*\//, "").toLowerCase().replace(/-/g, " ");
354
- const needLower = d.need.toLowerCase();
355
- return !needLower.startsWith(slug) || d.need.includes("—") || d.need.includes("(");
356
- });
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;
357
378
  }
358
379
 
359
380
  // ── Identity detection ─────────────────────────────────────────
@@ -449,13 +470,13 @@ function scanDirs(root: string): DirEntry[] {
449
470
  const dirs: DirEntry[] = [];
450
471
 
451
472
  try {
452
- for (const entry of readdirSync(root)) {
473
+ for (const entry of readdirSorted(root)) {
453
474
  if (entry.startsWith(".") && entry !== ".claude") continue;
454
475
  if (skip.has(entry)) continue;
455
476
  const full = join(root, entry);
456
477
  try {
457
478
  if (!statSync(full).isDirectory()) continue;
458
- const files = readdirSync(full, { recursive: true }).map(String);
479
+ const files = readdirSorted(full, { recursive: true });
459
480
  const exts = new Set(files.map(f => f.split(".").pop()).filter((e): e is string => Boolean(e)));
460
481
  dirs.push({ name: entry, fileCount: files.length, types: [...exts].slice(0, 5) });
461
482
  } catch {}
@@ -473,7 +494,7 @@ function scanModules(root: string): ModuleEntry[] {
473
494
  if (!existsSync(srcDir)) return modules;
474
495
 
475
496
  try {
476
- 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"))) {
477
498
  const content = readFileSync(join(srcDir, f), "utf-8");
478
499
  const exports: string[] = [];
479
500
  const exportPattern = /export\s+(?:function|const|class|type|interface)\s+(\w+)/g;
@@ -493,7 +514,7 @@ function scanRoutes(root: string): RouteEntry[] {
493
514
  if (!existsSync(srcDir)) return routes;
494
515
 
495
516
  try {
496
- 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"))) {
497
518
  const content = readFileSync(join(srcDir, f), "utf-8");
498
519
  const routePatterns = [
499
520
  /app\.(get|post|put|delete|patch)\s*\(\s*["'`]([^"'`]+)["'`]/gi,
@@ -553,7 +574,7 @@ function scanPromptRouting(root: string, harness: Record<string, any> | null): R
553
574
  if (!existsSync(promptsDir)) return promptsByAgent;
554
575
 
555
576
  try {
556
- const promptFiles = readdirSync(promptsDir).filter(f => f.endsWith(".md"));
577
+ const promptFiles = readdirSorted(promptsDir).filter(f => f.endsWith(".md"));
557
578
  for (const f of promptFiles) {
558
579
  const content = readFileSync(join(promptsDir, f), "utf-8");
559
580
  const lower = f.toLowerCase();
@@ -608,16 +629,13 @@ function scanAgentMeta(harness: Record<string, any> | null): Record<string, { de
608
629
 
609
630
  // ── Test command detection ─────────────────────────────────────
610
631
 
632
+ /**
633
+ * Through the one binding (#488). This knew only about package.json, so a
634
+ * consumer who set `dev.testCmd` got it honoured by the agent briefs and
635
+ * ignored by every scan-driven surface — and the CI generator read neither.
636
+ */
611
637
  function detectTestCmd(root: string): string {
612
- const pkgPath = join(root, "package.json");
613
- if (!existsSync(pkgPath)) return "bun test";
614
-
615
- try {
616
- const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
617
- if (pkg.scripts?.test) return pkg.scripts.test;
618
- } catch {}
619
-
620
- return "bun test";
638
+ return testCommandDecision(root).command;
621
639
  }
622
640
 
623
641
  // ── Categories ─────────────────────────────────────────────────
@@ -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[] = [];