rungate 0.2.1 → 0.4.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 (129) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
package/lib/conformity.ts CHANGED
@@ -6,8 +6,18 @@
6
6
  * runScaffoldConformity(import.meta.dir + "/..");
7
7
  */
8
8
  import { describe, test, expect } from "bun:test";
9
- import { existsSync, readFileSync, readdirSync } from "fs";
10
- import { join } from "path";
9
+ import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
10
+ import { collectSpecFiles } from "./spec-files";
11
+ import { spawnSync } from "child_process";
12
+ import { join, dirname } from "path";
13
+ import { fileURLToPath } from "url";
14
+ import { deriveDirectoryName } from "../scripts/split-spec";
15
+ import { readFreshCache } from "./behavioral-cache";
16
+ import { tryLoadRungateConfig } from "./config-loader";
17
+ import { stripJsComments } from "./strip-js-comments";
18
+ import { parseScDeclarations } from "./sc-ids";
19
+ import { isHarnessItself } from "./harness-identity";
20
+ import { tsconfigVerdict } from "./typescript-project";
11
21
 
12
22
  // ── Shared utilities ────────────────────────────────────────
13
23
 
@@ -15,13 +25,89 @@ export function parseFrontmatter(content: string): Record<string, string> | null
15
25
  const match = content.match(/^---\n([\s\S]*?)\n---/);
16
26
  if (!match) return null;
17
27
  const fields: Record<string, string> = {};
18
- for (const line of match[1].split("\n")) {
19
- const kv = line.match(/^(\w[\w-]*):\s*(.+)$/);
20
- if (kv) fields[kv[1]] = kv[2].trim();
28
+ const lines = match[1].split("\n");
29
+ for (let i = 0; i < lines.length; i++) {
30
+ const kv = lines[i].match(/^(\w[\w-]*):\s*(.+)$/);
31
+ if (kv) {
32
+ fields[kv[1]] = kv[2].trim();
33
+ continue;
34
+ }
35
+ // Block-style key — `tiers:` with its value on the indented lines below.
36
+ // Without this branch the key reads as ABSENT, so a presence check on a
37
+ // field that is plainly there (marcus.md's `tiers`, SC-423) fails against
38
+ // correct input. The value is the flattened block, which is enough for the
39
+ // presence and substring checks the conformity matchers make of it.
40
+ const blockKey = lines[i].match(/^(\w[\w-]*):\s*$/);
41
+ if (!blockKey) continue;
42
+ const block: string[] = [];
43
+ while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
44
+ block.push(lines[++i].trim());
45
+ }
46
+ fields[blockKey[1]] = block.join("; ");
21
47
  }
22
48
  return fields;
23
49
  }
24
50
 
51
+ /**
52
+ * SC-286: Resolve and validate file paths - reject traversal and absolute paths
53
+ * Returns resolved path or null if path is unsafe
54
+ */
55
+ export function resolveAndContain(root: string, target: string): string | null {
56
+ // Reject path traversal
57
+ if (target.includes("../")) return null;
58
+ // Reject absolute paths
59
+ if (target.startsWith("/")) return null;
60
+ // Allow normal relative paths (including those with dots in filenames like .rungate)
61
+ return join(root, target);
62
+ }
63
+
64
+ /**
65
+ * Resolve the actual .git directory, handling worktrees where .git is a file
66
+ * containing "gitdir: /path/to/real/gitdir".
67
+ */
68
+ function resolveGitDir(root: string): string {
69
+ const dotGit = join(root, ".git");
70
+ if (!existsSync(dotGit)) return dotGit;
71
+ const stat = statSync(dotGit);
72
+ if (stat.isDirectory()) return dotGit;
73
+ // Worktree: .git is a file with "gitdir: <path>"
74
+ const content = readFileSync(dotGit, "utf-8").trim();
75
+ const match = content.match(/^gitdir:\s*(.+)$/);
76
+ if (match) {
77
+ const gitdir = match[1].trim();
78
+ // gitdir may be absolute or relative
79
+ return gitdir.startsWith("/") ? gitdir : join(root, gitdir);
80
+ }
81
+ return dotGit;
82
+ }
83
+
84
+ /**
85
+ * Resolve a file path that starts with .git/ through the worktree-aware git dir.
86
+ * For non-.git paths, returns the normal join(root, file).
87
+ */
88
+ function resolveFilePath(root: string, file: string): string {
89
+ if (file.startsWith(".git/")) {
90
+ const gitDir = resolveGitDir(root);
91
+ // For worktrees, hooks live in the main repo's hooks dir, not the worktree gitdir.
92
+ // The worktree gitdir (e.g. .git/worktrees/name/) doesn't have hooks/.
93
+ // Walk up to the main .git dir if we're in a worktree subdir.
94
+ const suffix = file.slice(".git/".length); // e.g. "hooks/pre-commit"
95
+ const resolved = join(gitDir, suffix);
96
+ if (existsSync(resolved)) return resolved;
97
+ // Try the common dir (main repo .git) for shared resources like hooks
98
+ const commonDirFile = join(gitDir, "commondir");
99
+ if (existsSync(commonDirFile)) {
100
+ const commonDir = readFileSync(commonDirFile, "utf-8").trim();
101
+ const commonResolved = commonDir.startsWith("/")
102
+ ? join(commonDir, suffix)
103
+ : join(gitDir, commonDir, suffix);
104
+ if (existsSync(commonResolved)) return commonResolved;
105
+ }
106
+ return resolved;
107
+ }
108
+ return join(root, file);
109
+ }
110
+
25
111
  export { SIGNAL_PHRASE_PATTERNS } from "./signal-phrases";
26
112
 
27
113
  // ── Structured findings (machine-readable for agents) ──────
@@ -51,6 +137,7 @@ export interface StalenessEntry {
51
137
  const _findings: ConformityFinding[] = [];
52
138
  const _candidates: ConstraintCandidate[] = [];
53
139
  const _staleness: StalenessEntry[] = [];
140
+ let _behavioralCount = 0;
54
141
 
55
142
  export function addFinding(finding: ConformityFinding): void {
56
143
  _findings.push(finding);
@@ -80,6 +167,70 @@ export function clearFindings(): void {
80
167
  _findings.length = 0;
81
168
  _candidates.length = 0;
82
169
  _staleness.length = 0;
170
+ _behavioralCount = 0;
171
+ }
172
+
173
+ export function addBehavioralCount(count: number): void {
174
+ _behavioralCount += count;
175
+ }
176
+
177
+ export function getBehavioralCount(): number {
178
+ return _behavioralCount;
179
+ }
180
+
181
+ // ── Auto-flip: track passing SCs and flip checkboxes ────────
182
+
183
+ interface PassingSC {
184
+ id: string;
185
+ specPath: string;
186
+ }
187
+
188
+ const _passingSCs: PassingSC[] = [];
189
+
190
+ export function recordPassingSC(id: string, specPath: string): void {
191
+ _passingSCs.push({ id, specPath });
192
+ }
193
+
194
+ export function getPassingSCs(): readonly PassingSC[] {
195
+ return _passingSCs;
196
+ }
197
+
198
+ /**
199
+ * Flip `- [ ] SC-N` to `- [x] SC-N` for every SC recorded as passing in this
200
+ * process.
201
+ *
202
+ * DELIBERATELY HAS NO AUTOMATIC CALLER (#86). It used to run from an afterAll
203
+ * inside runScaffoldConformity, which made a test run mutate the spec files
204
+ * that the next run's test collection reads from — the suite alternated
205
+ * between 57 and 99 tests and reported 0 fail either way.
206
+ *
207
+ * Routine syncing is handled by scripts/sync-sc-status.ts via the `posttest`
208
+ * hook, which re-derives pass state independently. Call this only from an
209
+ * explicitly-invoked command, never from a test lifecycle hook.
210
+ */
211
+ export function flipPassingCheckboxes(): number {
212
+ const byFile = new Map<string, Set<string>>();
213
+ for (const { id, specPath } of _passingSCs) {
214
+ if (!byFile.has(specPath)) byFile.set(specPath, new Set());
215
+ byFile.get(specPath)!.add(id);
216
+ }
217
+
218
+ let flipped = 0;
219
+ for (const [specPath, ids] of byFile) {
220
+ if (!existsSync(specPath)) continue;
221
+ let content = readFileSync(specPath, "utf-8");
222
+ let changed = false;
223
+ for (const id of ids) {
224
+ const unchecked = `- [ ] ${id}:`;
225
+ if (content.includes(unchecked)) {
226
+ content = content.replace(unchecked, `- [x] ${id}:`);
227
+ changed = true;
228
+ flipped++;
229
+ }
230
+ }
231
+ if (changed) writeFileSync(specPath, content);
232
+ }
233
+ return flipped;
83
234
  }
84
235
 
85
236
  export function writeFindingsReport(root: string): string {
@@ -94,6 +245,7 @@ export function writeFindingsReport(root: string): string {
94
245
  failures: _findings.filter(f => f.severity === "FAIL").length,
95
246
  warnings: _findings.filter(f => f.severity === "WARN").length,
96
247
  candidateCount: _candidates.length,
248
+ behavioralCount: _behavioralCount,
97
249
  staleCount: _staleness.length,
98
250
  findings: _findings,
99
251
  constraintCandidates: _candidates,
@@ -102,32 +254,115 @@ export function writeFindingsReport(root: string): string {
102
254
  return reportPath;
103
255
  }
104
256
 
105
- interface ParsedSC {
257
+ export interface ParsedSC {
106
258
  id: string;
107
259
  statement: string;
108
260
  specFile: string;
261
+ /**
262
+ * Whether the SC's checkbox is ticked — `- [x]` rather than `- [ ]`.
263
+ *
264
+ * This drives the whole binding: a CHECKED SC claims to be done, so it is
265
+ * run as a real assertion and may fail the suite; an UNCHECKED one is work
266
+ * not started, so it is emitted as `test.todo`. Optional only because
267
+ * ParsedSC is constructed by hand in a dozen call sites that predate the
268
+ * field; `extractSCs` always sets it, and the planner treats a missing
269
+ * value as unchecked.
270
+ */
271
+ checked?: boolean;
109
272
  }
110
273
 
111
- function extractSCs(content: string, specFile: string): ParsedSC[] {
112
- const scs: ParsedSC[] = [];
113
- const pattern = /^- \[ \] (SC-\w+):\s*(.+)$/gm;
114
- let match;
115
- while ((match = pattern.exec(content)) !== null) {
116
- scs.push({ id: match[1], statement: match[2].trim(), specFile });
117
- }
118
- return scs;
274
+ /** A ParsedSC as produced by extractSCs, where the checkbox state is known. */
275
+ export interface ExtractedSC extends ParsedSC {
276
+ checked: boolean;
277
+ }
278
+
279
+ // ── Behavioral SC detection ───────────────────────────────
280
+
281
+ /**
282
+ * Detects whether an SC has the (behavioral) suffix, indicating it requires
283
+ * runtime verification (agent sessions, transcripts, auditing) and cannot
284
+ * be tested by static file checks.
285
+ */
286
+ export function isBehavioralSC(sc: ParsedSC): boolean {
287
+ return /\(behavioral\)\s*$/.test(sc.statement);
288
+ }
289
+
290
+ /**
291
+ * Counts behavioral SCs in a list.
292
+ */
293
+ export function countBehavioralSCs(scs: ParsedSC[]): number {
294
+ return scs.filter(isBehavioralSC).length;
295
+ }
296
+
297
+ /**
298
+ * Returns the routing annotation for behavioral SCs.
299
+ * Behavioral SCs are verified via SESSION-AUDIT-SPEC's two feedback loops,
300
+ * not via static conformity checks.
301
+ */
302
+ export function getBehavioralRouting(sc: ParsedSC): string | null {
303
+ if (!isBehavioralSC(sc)) return null;
304
+ return "Verified via SESSION-AUDIT-SPEC § Two Feedback Loops (runtime behavioral check)";
305
+ }
306
+
307
+ /**
308
+ * Returns an AssertionFn for a behavioral SC when cached results exist.
309
+ * Returns null when no fresh cache entry exists (treated as unmatchable).
310
+ * Stale entries (>= 7 days old) return null so they're treated as unmatchable.
311
+ */
312
+ export function behavioralPattern(sc: ParsedSC, cachePath: string): ((root: string) => void) | null {
313
+ const cache = readFreshCache(cachePath);
314
+ const entry = cache[sc.id];
315
+ if (!entry) return null;
316
+
317
+ return (_root: string) => {
318
+ if (!entry.passed) {
319
+ throw new Error(`Behavioral SC ${sc.id} failed: ${entry.evidence}`);
320
+ }
321
+ };
322
+ }
323
+
324
+ /**
325
+ * Pull every success criterion out of a spec, in BOTH checkbox states.
326
+ *
327
+ * This used to be `/^- \[ \] (SC-\w+)/` — unchecked only. Every SC marked
328
+ * done was therefore invisible to the engine: 261 of them in this repo,
329
+ * none asserted, and the suite reported 0 fail because it never looked.
330
+ * Narrowing this pattern again is caught by the floor test in
331
+ * test/phase-1-5.test.ts.
332
+ *
333
+ * The pattern itself moved to `lib/sc-ids.ts` (#330). It was one of four
334
+ * copies in the tree, each with a different idea of what an id looks like:
335
+ * this one admitted `SC-\w+`, the coverage lookup and the uniqueness guard
336
+ * only `SC-\d+`, so an anti-criterion was a declaration to this reader and
337
+ * invisible to the other two.
338
+ */
339
+ export function extractSCs(content: string, specFile: string): ExtractedSC[] {
340
+ return parseScDeclarations(content, specFile);
341
+ }
342
+
343
+ export interface SpecMetadata {
344
+ scs: ExtractedSC[];
345
+ compliance: "strict" | "permissive";
346
+ status: "active" | "draft";
119
347
  }
120
348
 
121
- function collectTestableSpecs(root: string, extraSpecDirs?: string[]): ParsedSC[] {
122
- const allSCs: ParsedSC[] = [];
349
+ export function collectTestableSpecs(root: string, extraSpecDirs?: string[]): Map<string, SpecMetadata> {
350
+ const specMap = new Map<string, SpecMetadata>();
123
351
 
124
352
  const localSpecs = join(root, "specs");
125
353
  if (existsSync(localSpecs)) {
126
- for (const f of readdirSync(localSpecs).filter(f => f.endsWith(".md"))) {
354
+ for (const f of collectSpecFiles(localSpecs)) {
127
355
  const content = readFileSync(join(localSpecs, f), "utf-8");
128
356
  const fm = parseFrontmatter(content);
129
357
  if (fm?.testable === "true") {
130
- allSCs.push(...extractSCs(content, f));
358
+ const compliance = fm?.compliance === "permissive" ? "permissive" : "strict";
359
+ const scs = extractSCs(content, f);
360
+ const hasCheckedSC = /- \[x\] SC-/i.test(content);
361
+ specMap.set(f, {
362
+ scs,
363
+ compliance,
364
+ status: hasCheckedSC ? "active" : "draft",
365
+ });
131
366
  }
132
367
  }
133
368
  }
@@ -140,38 +375,355 @@ function collectTestableSpecs(root: string, extraSpecDirs?: string[]): ParsedSC[
140
375
  if (fm?.testable !== "true") continue;
141
376
  const governs = fm?.governs || "";
142
377
  if (!governs.toLowerCase().includes("scaffold") && !governs.toLowerCase().includes("universal")) continue;
143
- allSCs.push(...extractSCs(content, `${dir.split("/").pop()}/${f}`));
378
+ const compliance = fm?.compliance === "permissive" ? "permissive" : "strict";
379
+ const hasCheckedSC = /- \[x\] SC-/i.test(content);
380
+ const specFile = `${dir.split("/").pop()}/${f}`;
381
+ specMap.set(specFile, {
382
+ scs: extractSCs(content, specFile),
383
+ compliance,
384
+ status: hasCheckedSC ? "active" : "draft",
385
+ });
144
386
  }
145
387
  }
146
388
 
147
- return allSCs;
389
+ return specMap;
148
390
  }
149
391
 
150
392
  // ── Pattern matchers ────────────────────────────────────────
151
393
 
152
394
  type AssertionFn = (root: string) => void;
395
+ type MatcherHandler = (sc: ParsedSC, match: RegExpMatchArray) => AssertionFn | null;
396
+
397
+ // Config loading with caching
398
+ const _registryCache = new Map<string, Array<{ name: string; regex: string }>>();
399
+
400
+ /**
401
+ * Project-owned conformity exemptions, read from
402
+ * `<root>/.claude/conformity-allowlists.json`.
403
+ *
404
+ * A file rather than a constant because the callers that need it differ in
405
+ * editability: test/scaffold-conformity.test.ts is harness-managed and
406
+ * regenerated on re-scaffold, so a list written into it would be silently
407
+ * wiped. Keying on `root` is also what keeps a consumer from inheriting
408
+ * rungate's exemptions, which is the defect this replaced.
409
+ *
410
+ * Absent or unreadable means no exemptions adopted, and the checks report
411
+ * advisory rather than failing. That is deliberate: before #80 they could not
412
+ * fail at all, so a missing file must not break an existing consumer.
413
+ */
414
+ function loadConformityAllowlists(root: string): {
415
+ untestedSpecs?: string[];
416
+ orphanFiles?: string[];
417
+ } {
418
+ try {
419
+ const p = join(root, ".claude", "conformity-allowlists.json");
420
+ if (!existsSync(p)) return {};
421
+ const parsed = JSON.parse(readFileSync(p, "utf-8"));
422
+ return {
423
+ untestedSpecs: Array.isArray(parsed.untestedSpecs) ? parsed.untestedSpecs : undefined,
424
+ orphanFiles: Array.isArray(parsed.orphanFiles) ? parsed.orphanFiles : undefined,
425
+ };
426
+ } catch {
427
+ return {};
428
+ }
429
+ }
430
+
431
+ /**
432
+ * The exemption lists in a conformity-allowlists file, keyed by list name.
433
+ *
434
+ * Every array-valued key is read, not just the two `loadConformityAllowlists`
435
+ * consumes. A list added later must be covered by the growth check the day it
436
+ * appears, not the day someone remembers to add it here — the opposite
437
+ * arrangement is how an exemption mechanism acquires an unwatched corner.
438
+ */
439
+ export function allowlistEntries(json: string): Record<string, string[]> {
440
+ const parsed = JSON.parse(json);
441
+ const lists: Record<string, string[]> = {};
442
+ for (const [key, value] of Object.entries(parsed)) {
443
+ if (Array.isArray(value)) lists[key] = value.map(String);
444
+ }
445
+ return lists;
446
+ }
447
+
448
+ /**
449
+ * Entries present in `headJson` and absent from `baseJson` (#302).
450
+ *
451
+ * The existing ratchet enforces STALENESS — an entry that stops being a
452
+ * violation fails the build — and that half is real. It does not enforce
453
+ * GROWTH: a new entry for a genuinely new violation is not stale, so every
454
+ * check passes. An agent could introduce a violation and exempt it in the
455
+ * same commit, which is the one move this harness exists to prevent — an
456
+ * agent must not be able to pass a gate by editing the gate.
457
+ *
458
+ * Direction is the whole point. REMOVALS always pass: an agent that fixes a
459
+ * violation and delists it is the case the ratchet is for, and refusing that
460
+ * would trade one outage for another. Only additions are reported.
461
+ *
462
+ * Comparing against `origin/main` rather than the merge base is deliberate
463
+ * and safe in the direction that matters: entries added on main that a branch
464
+ * does not carry read as REMOVALS and pass, so the base can be stale without
465
+ * producing a false refusal.
466
+ */
467
+ export function allowlistAdditions(baseJson: string, headJson: string): string[] {
468
+ const base = allowlistEntries(baseJson);
469
+ const head = allowlistEntries(headJson);
470
+ const added: string[] = [];
471
+ for (const [list, entries] of Object.entries(head)) {
472
+ const before = new Set(base[list] ?? []);
473
+ for (const entry of entries) {
474
+ if (!before.has(entry)) added.push(`${list}: ${entry}`);
475
+ }
476
+ }
477
+ return added;
478
+ }
479
+
480
+ /**
481
+ * Report a check that did not run, rather than returning silently.
482
+ *
483
+ * A bare `return` on a missing directory reads as a pass in every report, which
484
+ * is the same failure as the `expect(true).toBe(true)` bodies removed in #80 —
485
+ * the check contributes a green tick while verifying nothing. Wording matches
486
+ * the fallow skips so skipped checks are greppable as one class.
487
+ */
488
+ function checkSkipped(check: string, reason: string): void {
489
+ console.warn(`SKIP ${check}: ${reason} — this check did NOT run.`);
490
+ }
491
+
492
+ function loadBuiltInRegistry(): Array<{ name: string; regex: string }> {
493
+ const key = "__builtin__";
494
+ if (_registryCache.has(key)) return _registryCache.get(key)!;
495
+ const configPath = join(dirname(fileURLToPath(import.meta.url)), "..", "config", "matcher-registry.json");
496
+ const entries: Array<{ name: string; regex: string }> = JSON.parse(readFileSync(configPath, "utf-8"));
497
+ _registryCache.set(key, entries);
498
+ return entries;
499
+ }
500
+
501
+ /**
502
+ * Load the matcher registry, optionally merging consumer-defined custom matchers.
503
+ *
504
+ * When projectRoot is provided, looks for .claude/rungate.json in that directory
505
+ * and merges any `customMatchers` array entries with the built-in registry.
506
+ * Consumer entries with the same `name` as a built-in entry override the built-in.
507
+ */
508
+ /**
509
+ * `allowBuiltInOverride` is the difference between the AUTHORING view and the
510
+ * VERIFICATION view of the same config, and the two must not be the same.
511
+ *
512
+ * A consumer may name a custom matcher after a built-in, and `create-spec`
513
+ * honours it — that is a documented feature and extending the vocabulary is
514
+ * the point of custom matchers. But the conformity engine is verifying the
515
+ * very project that wrote that config, and `.claude/rungate.json` shadowing
516
+ * `content-contains` with a regex that matches nothing would switch the
517
+ * check off from inside the subject under test. The run would stay green and
518
+ * report nothing unusual, which is the defect class this repo exists to
519
+ * catch, arriving through its own extension point.
520
+ *
521
+ * So the engine takes `allowBuiltInOverride: false`: a consumer may ADD a
522
+ * matcher, never REPLACE one. A shadowing entry is dropped and named, rather
523
+ * than dropped quietly, because a consumer who meant it needs to know it did
524
+ * not take effect.
525
+ *
526
+ * This only became reachable when the runner started passing its project root
527
+ * (#212). Before that the engine ignored consumer config entirely, which is
528
+ * why the asymmetry had never had to be stated.
529
+ */
530
+ function loadRegistry(
531
+ projectRoot?: string,
532
+ opts?: { allowBuiltInOverride?: boolean },
533
+ ): Array<{ name: string; regex: string }> {
534
+ const allowOverride = opts?.allowBuiltInOverride ?? true;
535
+ const cacheKey = `${projectRoot ?? "__builtin__"}::${allowOverride ? "permissive" : "strict"}`;
536
+ if (_registryCache.has(cacheKey)) return _registryCache.get(cacheKey)!;
537
+
538
+ const builtIn = loadBuiltInRegistry();
539
+ if (!projectRoot) {
540
+ return builtIn;
541
+ }
542
+
543
+ // Consumer custom matchers, via the loader (ADR-002 D1, #309). Reading the
544
+ // monolith directly saw nothing on a project that had migrated to the
545
+ // directory layout, so a consumer's custom matchers silently stopped
546
+ // existing the moment they ran the scaffold that migrates them.
547
+ // Named without constructing the path — the loader resolves either layout,
548
+ // so there is no single file to point at, and spelling one out here would
549
+ // be the very access CONFIG-1 forbids in the file that hosts CONFIG-1.
550
+ const configDesc = `the rungate config under ${projectRoot}`;
551
+ let customMatchers: Array<{ name: string; regex: string }>;
552
+ try {
553
+ const config = tryLoadRungateConfig(projectRoot);
554
+ if (!config) {
555
+ _registryCache.set(cacheKey, builtIn);
556
+ return builtIn;
557
+ }
558
+ customMatchers = (config as { customMatchers?: Array<{ name: string; regex: string }> })
559
+ .customMatchers ?? [];
560
+ } catch (err) {
561
+ // Falling back to the built-ins is right — one consumer's broken config
562
+ // must not take the engine's own matchers down with it. Doing it in
563
+ // silence was not: every SC written against a custom matcher then reads
564
+ // as unrecognised, with nothing anywhere saying the config failed to
565
+ // parse (#212).
566
+ //
567
+ // The error's TYPE is reported and its message is not. A parse failure's
568
+ // message routinely quotes the bytes around the offending position, and
569
+ // this file is a project's own config — echoing its contents into build
570
+ // logs is how a secret in a misplaced field reaches somewhere it was
571
+ // never meant to go.
572
+ console.warn(
573
+ `WARN: ${configDesc} could not be read as JSON (${err instanceof Error ? err.name : "error"}; ` +
574
+ `message withheld — it can quote file contents). ` +
575
+ `Falling back to the built-in matcher registry — any customMatchers in that file are NOT loaded, ` +
576
+ `so SCs written against them will be reported as having no matcher.`,
577
+ );
578
+ _registryCache.set(cacheKey, builtIn);
579
+ return builtIn;
580
+ }
581
+
582
+ if (customMatchers.length === 0) {
583
+ _registryCache.set(cacheKey, builtIn);
584
+ return builtIn;
585
+ }
586
+
587
+ const builtInNames = new Set(builtIn.map((e) => e.name));
588
+ const accepted: Array<{ name: string; regex: string }> = [];
589
+ for (const candidate of customMatchers) {
590
+ if (!allowOverride && builtInNames.has(candidate.name)) {
591
+ console.warn(
592
+ `WARN: ${configDesc} defines a custom matcher named "${candidate.name}", which is a built-in. ` +
593
+ `A project cannot replace a built-in matcher while being verified by it — the entry is IGNORED. ` +
594
+ `Rename it to extend the vocabulary instead.`,
595
+ );
596
+ continue;
597
+ }
598
+ // Compiled here rather than at use: a regex that cannot compile would
599
+ // otherwise throw from inside the matcher loop, taking down a run over
600
+ // one bad consumer entry. The entry is refused; the rest still load.
601
+ try {
602
+ new RegExp(candidate.regex, "i");
603
+ } catch {
604
+ console.warn(
605
+ `WARN: ${configDesc} custom matcher "${candidate.name}" has a regex that does not compile — the entry is IGNORED.`,
606
+ );
607
+ continue;
608
+ }
609
+ accepted.push(candidate);
610
+ }
611
+
612
+ // Built-ins first. In the permissive view a shadowing entry has already
613
+ // displaced its built-in; in the strict view it was dropped above, so
614
+ // ordering alone cannot let a consumer entry pre-empt a built-in check.
615
+ const merged = allowOverride
616
+ ? [...builtIn.filter((e) => !accepted.some((c) => c.name === e.name)), ...accepted]
617
+ : [...builtIn, ...accepted];
618
+
619
+ _registryCache.set(cacheKey, merged);
620
+ return merged;
621
+ }
622
+
623
+ // ── Compound success criteria (#220) ────────────────────────
624
+ //
625
+ // `content-contains` captures exactly one bracket list and `matchPattern`
626
+ // returns on the first registry hit, so "FILE contains [a] and not contains
627
+ // [b]" bound, asserted [a], and discarded the rest with no signal. 21 ticked
628
+ // SCs were in that state; three of them asserted something false and passed
629
+ // anyway. The sweep is in #220.
630
+ //
631
+ // Two rules the parser follows, both of which a narrower reading gets wrong:
632
+ //
633
+ // - An SC's requirement ends where its explanation begins. Everything from
634
+ // the first " — " is rationale, and rationale saying "the reader and the
635
+ // writer agree" must not become a clause.
636
+ // - The defect is NOT about negation. Two of the 21 carry a POSITIVE second
637
+ // clause naming a different file, and a fix written in terms of
638
+ // "not contains" would leave those just as unasserted.
639
+
640
+ export type SCClause = { file: string; items: string[]; negated: boolean };
641
+
642
+ const CLAUSE_HEAD = /^(\S+)\s+contains?\s+\[([^\]]+)\]/;
643
+ const CLAUSE_TAIL =
644
+ /^\s+and\s+(?:(\S*[./]\S*)\s+)?(not\s+contains?|does\s+not\s+contain|must\s+NOT\s+contain|has\s+no|contains?)\s+\[([^\]]+)\]/i;
645
+
646
+ /** Rationale is commentary, not requirement. */
647
+ const requirementOf = (statement: string) => statement.split(" — ")[0].trimEnd();
648
+
649
+ const splitItems = (raw: string) => raw.split(",").map(i => i.trim()).filter(Boolean);
153
650
 
154
- function matchPattern(sc: ParsedSC): AssertionFn | null {
155
- const s = sc.statement;
651
+ const isCodeFile = (file: string) => /\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(file);
156
652
 
157
- const existsMatch = s.match(/^(\S+)\s+exists?\b(?:\s+at\s+root)?/i);
158
- if (existsMatch) {
159
- const target = existsMatch[1].replace(/`/g, "");
653
+ /**
654
+ * Parse a contains-family statement into every clause it states.
655
+ * Returns null when the statement is not compound, so callers fall through to
656
+ * the single-clause matcher rather than this becoming a second way to bind.
657
+ */
658
+ export function parseCompoundClauses(statement: string): SCClause[] | null {
659
+ const body = requirementOf(statement);
660
+ const head = CLAUSE_HEAD.exec(body);
661
+ if (!head) return null;
662
+
663
+ const headFile = head[1].replace(/`/g, "");
664
+ const clauses: SCClause[] = [{ file: headFile, items: splitItems(head[2]), negated: false }];
665
+
666
+ let end = head[0].length;
667
+ for (;;) {
668
+ const tail = CLAUSE_TAIL.exec(body.slice(end));
669
+ if (!tail) break;
670
+ end += tail[0].length;
671
+ const verb = tail[2].toLowerCase();
672
+ clauses.push({
673
+ file: (tail[1] ?? headFile).replace(/`/g, ""),
674
+ items: splitItems(tail[3]),
675
+ negated: /\bnot\b|has\s+no/.test(verb),
676
+ });
677
+ }
678
+ return clauses.length > 1 ? clauses : null;
679
+ }
680
+
681
+ /**
682
+ * The guard's view of its own input: text a contains-family statement states
683
+ * but no clause consumed. A leftover bracket list is a requirement that would
684
+ * be silently dropped, so it is named rather than discarded.
685
+ *
686
+ * Prose residue is deliberately NOT refused here. Around eight SCs carry real
687
+ * requirements as prose ("and is under 3,000 tokens"); refusing those turns 39
688
+ * SCs malformed at once, and rewriting them into testable form is #211's work.
689
+ * Returns null for statements no contains-family matcher owns — other matchers
690
+ * answer for their own spans, and "AGENTS.md is under [200] lines" is not a
691
+ * discarded assertion.
692
+ */
693
+ export function unconsumedAssertion(statement: string): string | null {
694
+ const body = requirementOf(statement);
695
+ const head = CLAUSE_HEAD.exec(body);
696
+ if (!head) return null;
697
+
698
+ let end = head[0].length;
699
+ for (;;) {
700
+ const tail = CLAUSE_TAIL.exec(body.slice(end));
701
+ if (!tail) break;
702
+ end += tail[0].length;
703
+ }
704
+ const residue = body.slice(end).trim();
705
+ return /\[[^\]]+\]/.test(residue) ? residue : null;
706
+ }
707
+
708
+ // Handler registry — one function per pattern type
709
+ const matcherHandlers: Record<string, MatcherHandler> = {
710
+ "file-exists": (sc, match) => {
711
+ const target = match[1].replace(/`/g, "");
160
712
  if (target.startsWith("~/") || target.startsWith("/")) return null;
161
- const limitMatch = s.match(/≤\s*(\d+)\s*lines/);
713
+ const limitMatch = sc.statement.match(/≤\s*(\d+)\s*lines/);
162
714
  return (root) => {
163
715
  expect(existsSync(join(root, target))).toBe(true);
164
716
  if (limitMatch) {
165
717
  const content = readFileSync(join(root, target), "utf-8");
166
- expect(content.split("\n").length).toBeLessThanOrEqual(parseInt(limitMatch[1]));
718
+ const lineCount = content.trimEnd().split("\n").length;
719
+ expect(lineCount).toBeLessThanOrEqual(parseInt(limitMatch[1]));
167
720
  }
168
721
  };
169
- }
722
+ },
170
723
 
171
- const dirMatch = s.match(/^(\S+?)\/?\s+directory\s+exists/i);
172
- if (dirMatch) {
173
- const dir = dirMatch[1].replace(/`/g, "");
174
- const minMatch = s.match(/(?:with\s+)?≥\s*(\d+)\s+(\w+)/);
724
+ "dir-exists": (sc, match) => {
725
+ const dir = match[1].replace(/`/g, "");
726
+ const minMatch = sc.statement.match(/(?:with\s+)?≥\s*(\d+)\s+(\w+)/);
175
727
  const aliases: Record<string, string[]> = {
176
728
  "tests": ["tests", "test"],
177
729
  "test": ["test", "tests"],
@@ -180,28 +732,55 @@ function matchPattern(sc: ParsedSC): AssertionFn | null {
180
732
  const candidates = aliases[dir] || [dir];
181
733
  return (root) => {
182
734
  const found = candidates.find(d => existsSync(join(root, d)));
735
+ if (!found) {
736
+ addFinding({
737
+ ruleId: "SCAFFOLD-DIR-EXISTS",
738
+ severity: "FAIL",
739
+ file: dir,
740
+ message: `Required directory "${dir}" not found`,
741
+ fixCommand: `mkdir -p ${dir}`,
742
+ });
743
+ }
183
744
  expect(found).toBeDefined();
184
745
  if (minMatch && found) {
185
- expect(readdirSync(join(root, found)).length).toBeGreaterThanOrEqual(parseInt(minMatch[1]));
746
+ const count = readdirSync(join(root, found)).length;
747
+ const required = parseInt(minMatch[1]);
748
+ if (count < required) {
749
+ addFinding({
750
+ ruleId: "SCAFFOLD-DIR-COUNT",
751
+ severity: "FAIL",
752
+ file: found,
753
+ message: `${found}/ has ${count} files (requires ≥${required})`,
754
+ fixCommand: `Add files to ${found}/ — needs at least ${required}`,
755
+ });
756
+ }
757
+ expect(count).toBeGreaterThanOrEqual(required);
186
758
  }
187
759
  };
188
- }
760
+ },
189
761
 
190
- if (/^all\s+specs\s+have\b/i.test(s) && /frontmatter/i.test(s)) {
762
+ "all-specs-frontmatter": (sc) => {
191
763
  return (root) => {
192
764
  const specsDir = join(root, "specs");
193
765
  if (!existsSync(specsDir)) return;
194
- const missing = readdirSync(specsDir).filter(f => f.endsWith(".md")).filter(f => {
766
+
767
+ // #225 — the hand-rolled one-level descent that used to live here is
768
+ // now the shared collector, so the seven flat callers get the same
769
+ // behaviour instead of this one site being the only correct reader.
770
+ const specFiles = collectSpecFiles(specsDir);
771
+
772
+ const missing = specFiles.filter(f => {
195
773
  const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
774
+ // Skip redirect files (status: split)
775
+ if (fm?.status === "split") return false;
196
776
  return !fm || !("testable" in fm);
197
777
  });
198
778
  expect(missing).toEqual([]);
199
779
  };
200
- }
780
+ },
201
781
 
202
- if (/all\s+paths\s+referenced\s+in\s+(\S+)\s+resolve/i.test(s)) {
203
- const fileMatch = s.match(/in\s+(\S+)/i);
204
- const target = fileMatch?.[1]?.replace(/`/g, "") || "AGENTS.md";
782
+ "paths-resolve": (sc, match) => {
783
+ const target = match[1]?.replace(/`/g, "") || "AGENTS.md";
205
784
  return (root) => {
206
785
  const p = join(root, target);
207
786
  if (!existsSync(p)) return;
@@ -215,81 +794,586 @@ function matchPattern(sc: ParsedSC): AssertionFn | null {
215
794
  }
216
795
  expect(broken).toEqual([]);
217
796
  };
218
- }
797
+ },
219
798
 
220
- if (/root\s+is\s+clean/i.test(s)) {
221
- const contentLimit = s.match(/content:\s*≤\s*(\d+)/i);
222
- const codeLimit = s.match(/code:\s*≤\s*(\d+)/i);
799
+ "root-clean": (sc) => {
800
+ const contentLimit = sc.statement.match(/content:\s*≤\s*(\d+)/i);
801
+ const codeLimit = sc.statement.match(/code:\s*≤\s*(\d+)/i);
223
802
  return (root) => {
224
803
  const items = readdirSync(root).filter(f => !f.startsWith(".") && f !== "node_modules");
225
- // Detect project type: if src/, lib/, gates/, or package.json with deps → code project
226
804
  const isCode = existsSync(join(root, "src")) || existsSync(join(root, "lib")) ||
227
805
  existsSync(join(root, "gates")) || existsSync(join(root, "Makefile"));
228
806
  const limit = isCode
229
807
  ? (codeLimit ? parseInt(codeLimit[1]) : 30)
230
808
  : (contentLimit ? parseInt(contentLimit[1]) : 10);
809
+ if (items.length > limit) {
810
+ addFinding({
811
+ ruleId: "SCAFFOLD-ROOT-CLEAN",
812
+ severity: "FAIL",
813
+ file: ".",
814
+ message: `Root has ${items.length} items (limit: ${limit}). Move non-essential files to subdirectories.`,
815
+ fixCommand: `Review root items and move docs to docs/, scripts to scripts/, specs to specs/`,
816
+ });
817
+ }
231
818
  expect(items.length).toBeLessThanOrEqual(limit);
232
819
  };
233
- }
820
+ },
234
821
 
235
- const pointerMatch = s.match(/(\S+)\s+exists\s+with\s+pointer\s+to\s+(\S+)/i);
236
- if (pointerMatch) {
237
- const file = pointerMatch[1].replace(/`/g, "");
238
- const target = pointerMatch[2].replace(/`/g, "");
822
+ "pointer-exists": (sc, match) => {
823
+ const file = match[1].replace(/`/g, "");
824
+ const target = match[2].replace(/`/g, "");
239
825
  return (root) => {
240
- expect(existsSync(join(root, file))).toBe(true);
241
- expect(readFileSync(join(root, file), "utf-8")).toContain(target);
826
+ const path = resolveFilePath(root, file);
827
+ expect(existsSync(path)).toBe(true);
828
+ expect(readFileSync(path, "utf-8")).toContain(target);
242
829
  };
243
- }
830
+ },
244
831
 
245
- if (/bun\s+test.*passes/i.test(s)) return () => { expect(true).toBe(true); };
246
832
 
247
- if (/canary/i.test(s)) {
833
+ "canary": () => {
248
834
  return (root) => {
249
835
  const testDir = existsSync(join(root, "test")) ? join(root, "test") : join(root, "tests");
250
836
  if (!existsSync(testDir)) return;
251
837
  const testFiles = readdirSync(testDir).filter(f => f.includes("conformity") || f.includes("canary"));
252
838
  expect(testFiles.length).toBeGreaterThanOrEqual(1);
253
839
  };
840
+ },
841
+
842
+ "content-contains-compound": (sc) => {
843
+ const clauses = parseCompoundClauses(sc.statement);
844
+ // Not actually compound — fall through so `content-contains` handles it.
845
+ if (!clauses) return null;
846
+ return (root) => {
847
+ for (const clause of clauses) {
848
+ const path = resolveFilePath(root, clause.file);
849
+ if (!existsSync(path)) {
850
+ expect(existsSync(path)).toBe(true);
851
+ return;
852
+ }
853
+ const content = readFileSync(path, "utf-8");
854
+ const view = clause.negated && isCodeFile(clause.file)
855
+ ? stripJsComments(content)
856
+ : content;
857
+ for (const item of clause.items) {
858
+ if (clause.negated) {
859
+ expect(view).not.toContain(item);
860
+ } else {
861
+ expect(view).toContain(item);
862
+ }
863
+ }
864
+ }
865
+ };
866
+ },
867
+
868
+ "content-contains": (sc, match) => {
869
+ const file = match[1].replace(/`/g, "");
870
+ const items = match[2].split(",").map(i => i.trim());
871
+ return (root) => {
872
+ const path = resolveFilePath(root, file);
873
+ if (!existsSync(path)) {
874
+ expect(existsSync(path)).toBe(true);
875
+ return;
876
+ }
877
+ const content = readFileSync(path, "utf-8");
878
+ for (const item of items) {
879
+ expect(content).toContain(item);
880
+ }
881
+ };
882
+ },
883
+
884
+ "content-not-contains": (sc, match) => {
885
+ const file = match[1].replace(/`/g, "");
886
+ const items = match[2].split(",").map(i => i.trim());
887
+ return (root) => {
888
+ const path = resolveFilePath(root, file);
889
+ if (!existsSync(path)) {
890
+ expect(existsSync(path)).toBe(true);
891
+ return;
892
+ }
893
+ const content = readFileSync(path, "utf-8");
894
+ for (const item of items) {
895
+ expect(content).not.toContain(item);
896
+ }
897
+ };
898
+ },
899
+
900
+ "count-threshold": (sc, match) => {
901
+ // #225 — the registry's regex is `^(.+?)\s+(?:is under|at most)…`, which
902
+ // is wider than this handler was. "AGENTS.md Rules section at most [200]
903
+ // words" matched, and the whole phrase "AGENTS.md Rules section" was then
904
+ // treated as a path: the file did not exist, so the check failed an SC
905
+ // that the tree satisfies (97 words against a threshold of 200). The
906
+ // registry's own `syntax` field says `{file} is under [N] lines|words`
907
+ // and never promised sections, so the regex admitted a form the handler
908
+ // could not honour — the shape #212 is about, met from the handler side.
909
+ const subject = match[1].replace(/`/g, "").trim();
910
+ const sectionMatch = subject.match(/^(\S+)\s+(.+?)\s+section$/i);
911
+ const file = sectionMatch ? sectionMatch[1] : subject;
912
+ const section = sectionMatch ? sectionMatch[2] : null;
913
+ const threshold = parseInt(match[2]);
914
+ const unit = match[3].toLowerCase();
915
+ // "(excluding tables/headers)" is part of the criterion, not commentary:
916
+ // a Rules section is mostly a table, and counting the table's words
917
+ // measures the opposite of the leanness the SC asks for.
918
+ const excludeTables = /excluding\s+tables/i.test(sc.statement);
919
+ return (root) => {
920
+ const path = join(root, file);
921
+ if (!existsSync(path)) {
922
+ expect(existsSync(path)).toBe(true);
923
+ return;
924
+ }
925
+ let content = readFileSync(path, "utf-8");
926
+ if (section) {
927
+ const lines = content.split("\n");
928
+ const start = lines.findIndex(l => new RegExp(`^#+\\s+${section}\\s*$`, "i").test(l));
929
+ // A named section that is not there is a failure of the criterion,
930
+ // not a reason to measure the whole file and probably pass.
931
+ expect(start, `${file} has no "${section}" section to measure`).toBeGreaterThan(-1);
932
+ const rest = lines.slice(start + 1);
933
+ const end = rest.findIndex(l => /^#+\s/.test(l));
934
+ content = (end === -1 ? rest : rest.slice(0, end)).join("\n");
935
+ }
936
+ if (excludeTables) {
937
+ content = content
938
+ .split("\n")
939
+ .filter(l => !/^\s*\|/.test(l) && !/^#+\s/.test(l))
940
+ .join("\n");
941
+ }
942
+ if (unit.startsWith("line")) {
943
+ const lineCount = content.trimEnd().split("\n").length;
944
+ expect(lineCount).toBeLessThanOrEqual(threshold);
945
+ } else {
946
+ const wordCount = content.split(/\s+/).filter(w => w.length > 0).length;
947
+ expect(wordCount).toBeLessThanOrEqual(threshold);
948
+ }
949
+ };
950
+ },
951
+
952
+ "json-field-equals": (sc, match) => {
953
+ const file = match[1].replace(/`/g, "");
954
+ const field = match[2];
955
+ const expectedValue = match[3];
956
+ return (root) => {
957
+ const path = join(root, file);
958
+ if (!existsSync(path)) {
959
+ expect(existsSync(path)).toBe(true);
960
+ return;
961
+ }
962
+ const content = readFileSync(path, "utf-8");
963
+ const json = JSON.parse(content);
964
+ // Support nested fields like "config.name"
965
+ const fieldParts = field.split(".");
966
+ let value = json;
967
+ for (const part of fieldParts) {
968
+ value = value?.[part];
969
+ }
970
+ expect(value).toBe(expectedValue);
971
+ };
972
+ },
973
+
974
+ "section-exists": (sc, match) => {
975
+ const file = match[1].replace(/`/g, "");
976
+ const sectionName = match[2];
977
+ return (root) => {
978
+ const path = join(root, file);
979
+ if (!existsSync(path)) {
980
+ expect(existsSync(path)).toBe(true);
981
+ return;
982
+ }
983
+ const content = readFileSync(path, "utf-8");
984
+ // Match both # and ## headings
985
+ const hasSection = new RegExp(`^#+ ${sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "mi").test(content);
986
+ expect(hasSection).toBe(true);
987
+ };
988
+ },
989
+
990
+ "regex-match": (sc, match) => {
991
+ const file = match[1].replace(/`/g, "");
992
+ const pattern = match[2];
993
+ const flags = match[3] || "";
994
+ return (root) => {
995
+ const path = join(root, file);
996
+ if (!existsSync(path)) {
997
+ expect(existsSync(path)).toBe(true);
998
+ return;
999
+ }
1000
+ const content = readFileSync(path, "utf-8");
1001
+ const regex = new RegExp(pattern, flags);
1002
+ expect(regex.test(content)).toBe(true);
1003
+ };
1004
+ },
1005
+
1006
+ "source-contains": (sc, match) => {
1007
+ const file = match[1].replace(/`/g, "");
1008
+ // Only match if it's a source file path (lib/, scripts/, hooks/, gates/) or has "harness" prefix
1009
+ const isSourceFile = /^(lib|scripts|hooks|gates)\//.test(file) || sc.statement.toLowerCase().includes("harness");
1010
+ if (isSourceFile) {
1011
+ const items = match[2].split(",").map(i => i.trim());
1012
+ return (root) => {
1013
+ const path = join(root, file);
1014
+ if (!existsSync(path)) {
1015
+ expect(existsSync(path)).toBe(true);
1016
+ return;
1017
+ }
1018
+ const content = readFileSync(path, "utf-8");
1019
+ for (const item of items) {
1020
+ expect(content).toContain(item);
1021
+ }
1022
+ };
1023
+ }
1024
+ return null;
1025
+ },
1026
+
1027
+ "json-has-field": (sc, match) => {
1028
+ const file = match[1].replace(/`/g, "");
1029
+ const filePath = file.endsWith(".json") ? file : `${file}.json`;
1030
+ const field = match[2];
1031
+ return (root) => {
1032
+ const path = join(root, filePath);
1033
+ if (!existsSync(path)) {
1034
+ expect(existsSync(path)).toBe(true);
1035
+ return;
1036
+ }
1037
+ const content = readFileSync(path, "utf-8");
1038
+ const json = JSON.parse(content);
1039
+ // Support nested fields like "config.name"
1040
+ const fieldParts = field.split(".");
1041
+ let value = json;
1042
+ for (const part of fieldParts) {
1043
+ value = value?.[part];
1044
+ }
1045
+ expect(value).toBeDefined();
1046
+ };
1047
+ },
1048
+
1049
+ "scaffold-produces": (sc, match) => {
1050
+ const file = match[1].replace(/`/g, "");
1051
+ return (root) => {
1052
+ // For now, this checks if the file exists in the root
1053
+ // A more complete implementation would actually run scaffold and check output
1054
+ const path = join(root, file);
1055
+ expect(existsSync(path)).toBe(true);
1056
+ };
1057
+ },
1058
+
1059
+ "frontmatter-field": (sc, match) => {
1060
+ const file = match[1].replace(/`/g, "");
1061
+ const field = match[2];
1062
+ const expectedValue = match[3]?.trim();
1063
+ return (root) => {
1064
+ const path = join(root, file);
1065
+ if (!existsSync(path)) {
1066
+ expect(existsSync(path)).toBe(true);
1067
+ return;
1068
+ }
1069
+ const content = readFileSync(path, "utf-8");
1070
+ const fm = parseFrontmatter(content);
1071
+ expect(fm).toBeDefined();
1072
+ expect(fm?.[field]).toBeDefined();
1073
+ if (expectedValue !== undefined) {
1074
+ expect(fm?.[field]).toBe(expectedValue);
1075
+ }
1076
+ };
1077
+ },
1078
+
1079
+ "file-line-range": (sc, match) => {
1080
+ const file = match[1].replace(/`/g, "");
1081
+ const min = parseInt(match[2]);
1082
+ const max = parseInt(match[3]);
1083
+ return (root) => {
1084
+ const path = join(root, file);
1085
+ if (!existsSync(path)) {
1086
+ expect(existsSync(path)).toBe(true);
1087
+ return;
1088
+ }
1089
+ const content = readFileSync(path, "utf-8");
1090
+ const lineCount = content.trimEnd().split("\n").length;
1091
+ expect(lineCount).toBeGreaterThanOrEqual(min);
1092
+ expect(lineCount).toBeLessThanOrEqual(max);
1093
+ };
1094
+ },
1095
+
1096
+ "command-output": (sc, match) => {
1097
+ const command = match[1];
1098
+ const items = match[2].split(",").map(i => i.trim());
1099
+ return (root) => {
1100
+ const result = spawnSync("sh", ["-c", command], {
1101
+ cwd: root,
1102
+ timeout: 10000,
1103
+ encoding: "utf-8",
1104
+ env: { ...process.env },
1105
+ });
1106
+ const exitCode = result.status ?? 1;
1107
+ expect(exitCode).toBe(0);
1108
+ const stdout = result.stdout || "";
1109
+ for (const item of items) {
1110
+ expect(stdout.includes(item)).toBe(true);
1111
+ }
1112
+ };
1113
+ },
1114
+ };
1115
+
1116
+ /**
1117
+ * The names the engine can actually assert. Exported so the registry can be
1118
+ * reconciled against it (#212) instead of the two drifting apart unobserved —
1119
+ * `matchPattern` iterates the REGISTRY, so a handler missing from it is
1120
+ * unreachable however well tested, and an entry missing a handler asserts
1121
+ * nothing while still matching the author's syntax.
1122
+ */
1123
+ export function matcherHandlerNames(): string[] {
1124
+ return Object.keys(matcherHandlers);
1125
+ }
1126
+
1127
+ /**
1128
+ * Why a statement did or did not become an assertion.
1129
+ *
1130
+ * `matchPattern` answered `null` for two different situations, and collapsing
1131
+ * them is the defect in #212: a statement that matched a registry regex whose
1132
+ * entry has no handler was reported exactly like a statement that matched
1133
+ * nothing at all. The first means "recognised, and nothing implements it";
1134
+ * the second means "unrecognised". SUCCESS.md claim 4 — "could not measure"
1135
+ * must never read as "nothing wrong" — needs them distinct.
1136
+ */
1137
+ export type MatcherResolution =
1138
+ | { kind: "assert"; matcher: string; assertion: AssertionFn }
1139
+ | { kind: "unimplemented"; matcher: string }
1140
+ | { kind: "unrecognised" };
1141
+
1142
+ export function resolveMatcher(sc: ParsedSC, projectRoot?: string): MatcherResolution {
1143
+ // Strict view: the project being verified may add matchers, never replace a
1144
+ // built-in one. See loadRegistry's docblock — `isMatchablePattern` keeps the
1145
+ // permissive view because it answers an authoring question, not a
1146
+ // verification one.
1147
+ const registry = loadRegistry(projectRoot, { allowBuiltInOverride: false });
1148
+ let recognisedBy: string | null = null;
1149
+
1150
+ for (const entry of registry) {
1151
+ const regex = new RegExp(entry.regex, "i");
1152
+ const match = sc.statement.match(regex);
1153
+ if (!match) continue;
1154
+
1155
+ const handler = matcherHandlers[entry.name];
1156
+ if (!handler) {
1157
+ // Recognised. Remember which matcher claimed it, but keep looking — a
1158
+ // later entry may both match and be implemented, and that is a better
1159
+ // answer than refusing.
1160
+ recognisedBy ??= entry.name;
1161
+ continue;
1162
+ }
1163
+ const result = handler(sc, match);
1164
+ if (result) return { kind: "assert", matcher: entry.name, assertion: result };
1165
+ }
1166
+
1167
+ return recognisedBy ? { kind: "unimplemented", matcher: recognisedBy } : { kind: "unrecognised" };
1168
+ }
1169
+
1170
+ export function matchPattern(sc: ParsedSC, projectRoot?: string): AssertionFn | null {
1171
+ const outcome = resolveMatcher(sc, projectRoot);
1172
+ return outcome.kind === "assert" ? outcome.assertion : null;
1173
+ }
1174
+
1175
+ /**
1176
+ * Check if an SC statement matches any pattern in the registry (built-in + consumer).
1177
+ * Unlike matchPattern, this only checks regex matches — it does not require a handler.
1178
+ * Used by create-spec for SC validation: a consumer custom pattern without a handler
1179
+ * is still a valid SC pattern for specification purposes.
1180
+ */
1181
+ export function isMatchablePattern(sc: ParsedSC, projectRoot?: string): boolean {
1182
+ const registry = loadRegistry(projectRoot);
1183
+ for (const entry of registry) {
1184
+ const regex = new RegExp(entry.regex, "i");
1185
+ if (regex.test(sc.statement)) {
1186
+ return true;
1187
+ }
254
1188
  }
1189
+ return false;
1190
+ }
1191
+
1192
+ // ── SC → test binding ───────────────────────────────────────
1193
+
1194
+ /**
1195
+ * How a single SC becomes (or fails to become) a test.
1196
+ *
1197
+ * Kept as data, separate from `describe`/`test`, so the binding rules can be
1198
+ * asserted directly — see test/conformity-sc-binding.test.ts. The important
1199
+ * property is that an `assert` entry hands back the RAW assertion: nothing
1200
+ * here catches, so a failing checked SC fails the suite.
1201
+ */
1202
+ export type SCPlanEntry =
1203
+ | { kind: "behavioral"; sc: ParsedSC; routing: string | null }
1204
+ | { kind: "todo"; sc: ParsedSC }
1205
+ | { kind: "unmatched"; sc: ParsedSC }
1206
+ | { kind: "unimplemented"; sc: ParsedSC; matcher: string }
1207
+ | { kind: "assert"; sc: ParsedSC; assertion: AssertionFn };
255
1208
 
256
- return null;
1209
+ /**
1210
+ * Decide what each SC becomes:
1211
+ * behavioral — runtime-only, routed to SESSION-AUDIT-SPEC
1212
+ * todo — unchecked, i.e. work not started; never a silent assertion
1213
+ * assert — checked and matchable; runs for real and may fail
1214
+ * unmatched — checked but the statement binds to no matcher: a coverage
1215
+ * gap, reported and ratcheted rather than silently dropped
1216
+ * unimplemented — checked, and the statement DID match a registry entry
1217
+ * that has no handler. Reported apart from `unmatched`
1218
+ * because "recognised and nothing implements it" is a
1219
+ * different defect from "unrecognised", and the author of
1220
+ * such an SC was told by create-spec that it was valid (#212)
1221
+ */
1222
+ export function planSCTests(scs: ParsedSC[], projectRoot?: string): SCPlanEntry[] {
1223
+ return scs.map((sc): SCPlanEntry => {
1224
+ if (isBehavioralSC(sc)) return { kind: "behavioral", sc, routing: getBehavioralRouting(sc) };
1225
+ if (!sc.checked) return { kind: "todo", sc };
1226
+ const outcome = resolveMatcher(sc, projectRoot);
1227
+ if (outcome.kind === "assert") return { kind: "assert", sc, assertion: outcome.assertion };
1228
+ if (outcome.kind === "unimplemented") return { kind: "unimplemented", sc, matcher: outcome.matcher };
1229
+ return { kind: "unmatched", sc };
1230
+ });
257
1231
  }
258
1232
 
259
1233
  // ── Exported test runners ───────────────────────────────────
260
1234
 
261
1235
  export function runScaffoldConformity(root: string, opts?: { extraSpecDirs?: string[] }) {
262
- const HOME = process.env.HOME || "";
263
- const defaultExtraSpecs = [join(HOME, ".claude", "PAI", "specs")];
264
- const allSCs = collectTestableSpecs(root, opts?.extraSpecDirs ?? defaultExtraSpecs);
1236
+ const specMap = collectTestableSpecs(root, opts?.extraSpecDirs ?? []);
1237
+ const specsDir = join(root, "specs");
1238
+
1239
+ function resolveSpecPath(specFile: string): string {
1240
+ if (specFile.includes("/")) {
1241
+ const parts = specFile.split("/");
1242
+ for (const dir of opts?.extraSpecDirs ?? []) {
1243
+ if (dir.endsWith(parts[0])) return join(dir, parts.slice(1).join("/"));
1244
+ }
1245
+ }
1246
+ return join(specsDir, specFile);
1247
+ }
265
1248
 
266
1249
  describe("Spec-Driven Conformity Tests", () => {
267
- if (allSCs.length === 0) {
268
- test("at least one testable spec with SCs exists", () => {
269
- expect(allSCs.length).toBeGreaterThan(0);
270
- });
1250
+ if (specMap.size === 0) {
1251
+ test.skip("at least one testable spec with SCs exists (no specs found — consumer project)", () => {});
271
1252
  return;
272
1253
  }
273
1254
 
274
- const bySpec = new Map<string, ParsedSC[]>();
275
- for (const sc of allSCs) {
276
- const group = bySpec.get(sc.specFile) || [];
277
- group.push(sc);
278
- bySpec.set(sc.specFile, group);
279
- }
280
-
281
- for (const [specFile, scs] of bySpec) {
1255
+ // No afterAll checkbox flip here, deliberately (#86).
1256
+ //
1257
+ // This describe builds its test list at collection time by reading SC
1258
+ // checkboxes off disk. Writing those same files back at the end of the run
1259
+ // meant run N mutated the input run N+1 collected from, so the generated
1260
+ // test list alternated between two shapes — 57 tests, then 99, then 57.
1261
+ // Both parities reported 0 fail, so nothing ever surfaced it: the suite was
1262
+ // not hiding a failure, it was hiding whether 42 checks ran at all.
1263
+ //
1264
+ // Checkbox syncing still happens, deliberately and separately, via the
1265
+ // `posttest` hook in package.json -> scripts/sync-sc-status.ts. That script
1266
+ // re-derives pass state from the specs itself rather than riding on a test
1267
+ // run's in-memory bookkeeping, so it is not load-bearing for this suite and
1268
+ // nothing is lost by removing the hook.
1269
+
1270
+ for (const [specFile, metadata] of specMap) {
282
1271
  describe(specFile, () => {
283
1272
  const unmatched: string[] = [];
284
- for (const sc of scs) {
285
- const assertion = matchPattern(sc);
286
- if (!assertion) { unmatched.push(`${sc.id}: ${sc.statement}`); continue; }
287
- test(`${sc.id}: ${sc.statement}`, () => { assertion(root); });
1273
+ const unimplemented: string[] = [];
1274
+ const behavioral: string[] = [];
1275
+ const specPath = resolveSpecPath(specFile);
1276
+ // `root`, not nothing: without it `loadRegistry` never reads the
1277
+ // consumer's `.claude/rungate.json`, so every custom matcher is
1278
+ // invisible to the engine while `create-spec` — which DOES pass a
1279
+ // project root to `isMatchablePattern` — accepts criteria written
1280
+ // against them. That is the authoring-tool/engine divergence in #212,
1281
+ // and it was not hypothetical: the planted-project test in
1282
+ // test/matcher-registry-parity.test.ts reported its criterion as
1283
+ // `unmatched` until this argument was supplied.
1284
+ for (const entry of planSCTests(metadata.scs, root)) {
1285
+ const { sc } = entry;
1286
+ if (entry.kind === "behavioral") {
1287
+ behavioral.push(`${sc.id}: ${sc.statement} → ${entry.routing}`);
1288
+ } else if (entry.kind === "todo") {
1289
+ // bun-types declares test.todo as requiring a body even though the
1290
+ // runtime accepts a bare label. A no-op body satisfies both: todo
1291
+ // tests are not executed unless `bun test --todo` is passed.
1292
+ test.todo(`${sc.id}: ${sc.statement}`, () => {});
1293
+ } else if (entry.kind === "unmatched") {
1294
+ unmatched.push(`${sc.id}: ${sc.statement}`);
1295
+ } else if (entry.kind === "unimplemented") {
1296
+ // Not folded into `unmatched`: this SC's syntax WAS recognised,
1297
+ // and create-spec would have told its author it was valid. The
1298
+ // gap is a registry entry with no handler, which is a different
1299
+ // thing to fix and a different thing to report (#212).
1300
+ unimplemented.push(`${sc.id}: matched "${entry.matcher}", which has no handler — ${sc.statement}`);
1301
+ } else {
1302
+ // A CHECKED SC claims the work is done. Run its assertion for
1303
+ // real: no try/catch, so it fails the suite when the claim is
1304
+ // false. The old body swallowed the throw, which is why 13 false
1305
+ // claims sat green for months (#209).
1306
+ test(`${sc.id}: ${sc.statement}`, () => {
1307
+ entry.assertion(root);
1308
+ recordPassingSC(sc.id, specPath);
1309
+ });
1310
+ }
1311
+ }
1312
+ if (behavioral.length > 0) {
1313
+ addBehavioralCount(behavioral.length);
1314
+ // This is a REPORT, not a test, and that is the fix (#328).
1315
+ //
1316
+ // It used to be a `test()` whose body was `expect(true).toBe(true)`
1317
+ // — shape three in .claude/rules/checks-must-be-able-to-fail.md,
1318
+ // written out literally rather than arrived at by accident, and the
1319
+ // only executable check on 40 ticked criteria.
1320
+ //
1321
+ // The first attempt at a repair kept the `test()` and asserted that
1322
+ // every listed SC carries the `(behavioral)` marker. The mutation
1323
+ // harness measured that at ZERO red, and it was right to: this list
1324
+ // is only ever appended to when `entry.kind === "behavioral"`, which
1325
+ // happens only when `isBehavioralSC(sc)` is already true. The
1326
+ // assertion was a tautology — a second unfalsifiable check wearing
1327
+ // the first one's clothes.
1328
+ //
1329
+ // There is nothing locally falsifiable to put here. Whether a
1330
+ // behavioral criterion is SATISFIED is a runtime question this file
1331
+ // cannot answer, and whether it is CLASSIFIED correctly is true by
1332
+ // construction. So the slot stops pretending: the listing stays,
1333
+ // because findability is genuinely useful, and the teeth live in
1334
+ // test/behavioral-sc-ratchet.test.ts, which bounds the population
1335
+ // and which the same harness measures at 1 red when slackened.
1336
+ //
1337
+ // A report that admits it is a report is strictly better than a test
1338
+ // that cannot fail, because only one of them is counted as evidence.
1339
+ console.log(
1340
+ `Behavioral SCs in ${specFile} — NOT VERIFIED HERE, bounded by ` +
1341
+ `BEHAVIORAL_TICKED_RATCHET (#328):\n ${behavioral.join("\n ")}`,
1342
+ );
288
1343
  }
289
1344
  if (unmatched.length > 0) {
290
- test(`WARN: ${unmatched.length} SCs have no pattern matcher`, () => {
291
- console.warn(`Unmatched SCs in ${specFile}:\n ${unmatched.join("\n ")}`);
292
- expect(true).toBe(true);
1345
+ // SC-287 used to FAIL here in strict mode. That branch had never
1346
+ // fired: the only SCs that reached it were unchecked ones, and
1347
+ // unchecked SCs now become `todo` before the matcher runs. The
1348
+ // population is now CHECKED SCs written in prose no matcher binds
1349
+ // to — 54 of them on the day they first became visible (#209).
1350
+ //
1351
+ // Failing 54 specs at once would get the whole file skipped, so the
1352
+ // teeth live in a single repo-wide ratchet instead:
1353
+ // test/conformity-sc-binding.test.ts asserts the total may fall but
1354
+ // never rise. Here we name them, per spec, so they are findable.
1355
+ const level = metadata.compliance === "permissive" ? "WARN" : "WARN (strict)";
1356
+ test(`${level}: ${unmatched.length} checked SCs have no pattern matcher`, () => {
1357
+ console.warn(`Unmatched checked SCs in ${specFile}:\n ${unmatched.join("\n ")}`);
1358
+ expect(unmatched.length).toBeGreaterThan(0);
1359
+ });
1360
+ }
1361
+ // Deliberately BELOW the unmatched branch, not between it and the
1362
+ // behavioral report. #328's guard slices the source from the
1363
+ // behavioral branch to `if (unmatched.length > 0) {` and asserts that
1364
+ // region contains no `test(` — the behavioral slot must stay a report.
1365
+ // This block legitimately IS a test, so placing it in that window
1366
+ // turns #328's guard red. The guard is right; this belongs here.
1367
+ if (unimplemented.length > 0) {
1368
+ // Unlike the unmatched aggregate above, this one FAILS, and it can
1369
+ // afford to: the population is zero in this repo and the parity
1370
+ // test in test/matcher-registry-parity.test.ts keeps it there, so
1371
+ // it cannot turn specs red en masse. A registry entry with no
1372
+ // handler is a harness defect, not a backlog of prose criteria
1373
+ // waiting to be rewritten — the author was told by create-spec that
1374
+ // their syntax was valid, and the engine then asserted nothing.
1375
+ test(`FAIL: ${unimplemented.length} SCs matched a registry entry that has no handler`, () => {
1376
+ expect(unimplemented).toEqual([]);
293
1377
  });
294
1378
  }
295
1379
  });
@@ -299,19 +1383,28 @@ export function runScaffoldConformity(root: string, opts?: { extraSpecDirs?: str
299
1383
  describe("Scaffold: structural checks", () => {
300
1384
  test("AGENTS.md has required standard sections", () => {
301
1385
  if (!existsSync(join(root, "AGENTS.md"))) {
1386
+ addFinding({ ruleId: "SCAFFOLD-AGENTS-MISSING", severity: "FAIL", file: "AGENTS.md", message: "AGENTS.md not found", fixCommand: "Run scaffold to generate AGENTS.md" });
302
1387
  expect(existsSync(join(root, "AGENTS.md"))).toBe(true);
303
1388
  return;
304
1389
  }
305
1390
  const content = readFileSync(join(root, "AGENTS.md"), "utf-8");
306
- const required = ["Project Identity", "Key Files", "Specs", "Tests", "Workflow"];
1391
+ const required = ["Project Identity", "Rules", "Commands", "Workflow"];
307
1392
  const missing = required.filter(s => !content.toLowerCase().includes(s.toLowerCase()));
1393
+ if (missing.length > 0) {
1394
+ addFinding({ ruleId: "SCAFFOLD-AGENTS-SECTIONS", severity: "FAIL", file: "AGENTS.md", message: `Missing sections: ${missing.join(", ")}`, fixCommand: "Re-run scaffold to regenerate AGENTS.md" });
1395
+ }
308
1396
  expect(missing).toEqual([]);
309
1397
  });
310
1398
 
311
- test("rungate.json has required fields (if exists)", () => {
312
- const p = join(root, ".claude", "rungate.json");
313
- if (!existsSync(p)) return;
314
- const config = JSON.parse(readFileSync(p, "utf-8"));
1399
+ test("rungate config has required fields (if configured)", () => {
1400
+ // Through the loader (ADR-002 D1, #309). Reading the monolith directly
1401
+ // meant a project on the directory layout skipped this check entirely —
1402
+ // `existsSync` was false, the test returned, and a config missing
1403
+ // `project` or `repo` passed by never being looked at. Exactly the
1404
+ // shape .claude/rules/checks-must-be-able-to-fail.md opens with, in the
1405
+ // check that validates config.
1406
+ const config = tryLoadRungateConfig(root);
1407
+ if (!config) return;
315
1408
  expect(config.project).toBeDefined();
316
1409
  expect(config.repo).toBeDefined();
317
1410
  });
@@ -336,25 +1429,56 @@ export function runSpecDiscovery(root: string) {
336
1429
 
337
1430
  test("every .md in specs/ has testable field", () => {
338
1431
  if (!existsSync(specsDir)) return;
339
- const missing = readdirSync(specsDir).filter(f => f.endsWith(".md")).filter(f => {
1432
+ const missing = collectSpecFiles(specsDir).filter(f => {
340
1433
  const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
341
1434
  return !fm || !("testable" in fm);
342
1435
  });
1436
+ for (const f of missing) {
1437
+ addFinding({ ruleId: "SPEC-FRONTMATTER", severity: "FAIL", file: `specs/${f}`, message: `Spec "${f}" missing testable field in frontmatter`, fixCommand: `Add "testable: true" or "testable: false" to frontmatter of specs/${f}` });
1438
+ }
343
1439
  expect(missing).toEqual([]);
344
1440
  });
345
1441
 
346
1442
  test("at least one testable spec exists", () => {
347
1443
  if (!existsSync(specsDir)) return;
348
- const testable = readdirSync(specsDir).filter(f => f.endsWith(".md")).filter(f => {
1444
+ const testable = collectSpecFiles(specsDir).filter(f => {
349
1445
  const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
350
1446
  return fm?.testable === "true";
351
1447
  });
352
- expect(testable.length).toBeGreaterThan(0);
1448
+ if (testable.length === 0) {
1449
+ addFinding({
1450
+ ruleId: "SPEC-DISCOVERY-TESTABLE",
1451
+ severity: "WARN",
1452
+ file: "specs/",
1453
+ message: "No spec has testable: true. Add testable: true to a spec when ready for conformity testing.",
1454
+ fixCommand: `Add "testable: true" to frontmatter of a spec in specs/`,
1455
+ });
1456
+ console.warn("SPEC-DISCOVERY: No testable specs found — skipping (add testable: true when ready)");
1457
+ } else {
1458
+ expect(testable.length).toBeGreaterThan(0);
1459
+ }
353
1460
  });
354
1461
  });
355
1462
  }
356
1463
 
357
- export function runSpecDrift(root: string) {
1464
+ /**
1465
+ * @param options.untestedAllowlist Specs permitted to have no referencing test,
1466
+ * owned by the CALLING project. Omitted means the caller has not adopted the
1467
+ * ratchet, and DRIFT-2 reports advisory instead of failing — see the comment
1468
+ * on DRIFT-2 for why a consumer must not inherit rungate's backlog.
1469
+ *
1470
+ * The allowlist is deliberately in `options`, not position 2: the consumer test
1471
+ * that lib/scaffold/steps.ts generates calls `runSpecDrift(ROOT, findings)`, so
1472
+ * a positional second parameter would receive a findings array and exempt
1473
+ * nothing, failing every consumer build.
1474
+ */
1475
+ export function runSpecDrift(
1476
+ root: string,
1477
+ _findings?: unknown[],
1478
+ options?: { untestedAllowlist?: string[] },
1479
+ ) {
1480
+ const untestedAllowlist =
1481
+ options?.untestedAllowlist ?? loadConformityAllowlists(root).untestedSpecs;
358
1482
  const specsDir = join(root, "specs");
359
1483
  const testDirs = [join(root, "test"), join(root, "tests")].filter(d => existsSync(d));
360
1484
 
@@ -387,8 +1511,8 @@ export function runSpecDrift(root: string) {
387
1511
  });
388
1512
 
389
1513
  test("DRIFT-2: Every testable spec is referenced by at least one test", () => {
390
- if (!existsSync(specsDir)) return;
391
- const testable = readdirSync(specsDir).filter(f => f.endsWith(".md")).filter(f => {
1514
+ if (!existsSync(specsDir)) return checkSkipped("DRIFT-2", "no specs/ directory");
1515
+ const testable = collectSpecFiles(specsDir).filter(f => {
392
1516
  const fm = parseFrontmatter(readFileSync(join(specsDir, f), "utf-8"));
393
1517
  return fm?.testable === "true";
394
1518
  });
@@ -401,15 +1525,170 @@ export function runSpecDrift(root: string) {
401
1525
  }
402
1526
 
403
1527
  const orphaned = testable.filter(s => !allContent.includes(s));
404
- if (orphaned.length > 0) {
405
- console.warn(`Testable specs with no test references: ${orphaned.join(", ")}`);
1528
+
1529
+ // Was `expect(true).toBe(true)` after a console.warn, so the mechanical
1530
+ // enforcement of CLAUDE.md's "SCs without tests are wishes" could never
1531
+ // fail (#80). Turning it on revealed 10 testable specs in rungate with no
1532
+ // test referencing them at all — over half the testable surface.
1533
+ //
1534
+ // That backlog cannot be asserted to zero without writing ten tests, so
1535
+ // adopters pass a RATCHET list: anything on it may stay untested, an
1536
+ // addition fails the build, and a listed spec that GAINS a test must be
1537
+ // delisted or the build fails — otherwise the allowlist rots into another
1538
+ // artifact that certifies nothing.
1539
+ //
1540
+ // The list belongs to the CALLING PROJECT, never to this file. An earlier
1541
+ // version hardcoded rungate's ten spec filenames here, and
1542
+ // lib/scaffold/steps.ts generates a consumer conformity test that calls
1543
+ // this function — so every consumer inherited rungate's backlog. A
1544
+ // consumer with an untested spec of a matching name was silently
1545
+ // exempted, and a consumer that HAD such a spec with a test failed its
1546
+ // own build demanding it delist an entry from a file inside rungate that
1547
+ // it cannot edit.
1548
+ if (!untestedAllowlist) {
1549
+ // No ratchet adopted. Report, but do not fail: before #80 this check
1550
+ // could not fail at all, so failing here would break every existing
1551
+ // consumer on upgrade for a backlog they never opted into.
1552
+ if (orphaned.length > 0) {
1553
+ console.warn(
1554
+ `WARN DRIFT-2: ${orphaned.length} testable spec(s) have no referencing test — ` +
1555
+ `${orphaned.join(", ")}. This check is ADVISORY because no untestedAllowlist ` +
1556
+ `was supplied. Pass one to runSpecDrift to enforce it as a ratchet.`,
1557
+ );
1558
+ }
1559
+ return;
406
1560
  }
407
- expect(true).toBe(true);
1561
+
1562
+ const newlyOrphaned = orphaned.filter(s => !untestedAllowlist.includes(s));
1563
+ expect(newlyOrphaned).toEqual([]);
1564
+
1565
+ const staleAllowlist = untestedAllowlist.filter(
1566
+ s => testable.includes(s) && !orphaned.includes(s),
1567
+ );
1568
+ expect(staleAllowlist).toEqual([]);
1569
+ });
1570
+
1571
+ test("DRIFT-3: the exemption lists did not GROW", () => {
1572
+ // #302. The staleness checks above enforce one direction: an entry that
1573
+ // stops being a violation fails. A NEW entry for a genuinely new
1574
+ // violation is not stale, so until now an agent could introduce a
1575
+ // conformity violation and exempt it in the same commit — passing a
1576
+ // gate by editing the gate, which is the one move this harness exists
1577
+ // to refuse.
1578
+ //
1579
+ // It sits here rather than in the collection guard deliberately. The
1580
+ // collection guard sees paths, not contents, and would catch only
1581
+ // growth arriving via agent collection — not a human commit, a heal
1582
+ // round, or a single-worktree run that bypasses collection entirely.
1583
+ const allowlistPath = join(root, ".claude", "conformity-allowlists.json");
1584
+ if (!existsSync(allowlistPath)) return;
1585
+
1586
+ const show = spawnSync("git", ["-C", root, "show", `origin/main:.claude/conformity-allowlists.json`], {
1587
+ encoding: "utf-8",
1588
+ timeout: 20_000,
1589
+ });
1590
+
1591
+ if (show.error || show.status !== 0) {
1592
+ // ADVISORY, not a refusal, and only here. A consumer may legitimately
1593
+ // have no `origin/main` — a fresh scaffold, a local-only repo — and
1594
+ // refusing for want of a comparison base would break every one of
1595
+ // them on upgrade for a rule they never opted into. That is the same
1596
+ // judgement loadConformityAllowlists already makes about a missing
1597
+ // allowlist file. rungate's own suite asserts the base IS readable,
1598
+ // because in this repo an unreadable one is a fault, not a setup.
1599
+ console.warn(
1600
+ `WARN DRIFT-3: could not read origin/main's copy of the conformity allowlist, so ` +
1601
+ `growth was NOT checked. This is UNMEASURED, not clean.`,
1602
+ );
1603
+ return;
1604
+ }
1605
+
1606
+ const added = allowlistAdditions(show.stdout, readFileSync(allowlistPath, "utf-8"));
1607
+ expect(
1608
+ added,
1609
+ `an exemption was ADDED relative to origin/main. Fix the violation, or make the ` +
1610
+ `exemption a deliberate recorded decision rather than a diff.`,
1611
+ ).toEqual([]);
408
1612
  });
409
1613
  });
410
1614
  }
411
1615
 
412
- export function runDocHygiene(root: string) {
1616
+ /**
1617
+ * @param options.orphanAllowlist Files permitted to have zero references, owned
1618
+ * by the CALLING project. Same contract and same positional constraint as
1619
+ * runSpecDrift's untestedAllowlist — the generated consumer test calls
1620
+ * `runDocHygiene(ROOT, findings)`.
1621
+ */
1622
+ /**
1623
+ * Every path's most recent commit date, from ONE git subprocess (#323).
1624
+ *
1625
+ * Exported so the regression test can run it against the repository and
1626
+ * compare it to the per-file calls it replaced — a single site to mutate, and
1627
+ * the only way to prove the parser still agrees with git rather than merely
1628
+ * being faster. A detector that got quicker by finding less would pass every
1629
+ * timing test and none of the ones that matter.
1630
+ *
1631
+ * Walks newest-first, so the first time a path appears is its latest commit
1632
+ * and later entries are ignored. Paths deleted or renamed earlier in history
1633
+ * also appear; they are never looked up, which is cheaper than filtering them.
1634
+ *
1635
+ * `pathspecs` must be the SET OF PATHS THE CALLER WILL LOOK UP, not the
1636
+ * directories they mostly live in. The first version of this took the six doc
1637
+ * directories, which is where the staleness scan finds most of its files — but
1638
+ * the scan also walks root-level markdown, and `git log -- specs docs` cannot
1639
+ * report a commit for `AGENTS.md`. Six files silently dropped out of the
1640
+ * lookup and `if (!dateStr) continue` read that as "newly added, so not
1641
+ * stale". A detector narrower than what it detects, shipped inside the fix for
1642
+ * a different instance of the same thing. Passing the lookup set makes the
1643
+ * pathspec and the keys the same list by construction, so they cannot drift.
1644
+ *
1645
+ * Fails CLOSED. `spawnSync` does not throw when git exits non-zero, so a
1646
+ * broken invocation would otherwise return an empty map and every file would
1647
+ * read as newly added — total blindness that looks exactly like a clean run.
1648
+ */
1649
+ export function lastCommitDates(root: string, pathspecs: string[]): Map<string, string> {
1650
+ const lastCommit = new Map<string, string>();
1651
+ // Not a git repository: nothing is tracked, so no path has a commit date.
1652
+ // That is a real answer, not a failure, and scaffolded projects hit it.
1653
+ if (!existsSync(join(root, ".git"))) return lastCommit;
1654
+ if (pathspecs.length === 0) return lastCommit;
1655
+ {
1656
+ const log = spawnSync(
1657
+ "git",
1658
+ ["-C", root, "log", "--format=%H %ci", "--name-only", "--", ...pathspecs],
1659
+ { timeout: 60_000, maxBuffer: 64 * 1024 * 1024 },
1660
+ );
1661
+ if (log.error) {
1662
+ throw new Error(`lastCommitDates: git log could not run in ${root}: ${log.error.message}`);
1663
+ }
1664
+ if (log.status !== 0) {
1665
+ throw new Error(
1666
+ `lastCommitDates: git log exited ${log.status} in ${root}: ` +
1667
+ `${log.stderr?.toString().trim() || "(no stderr)"}`,
1668
+ );
1669
+ }
1670
+ let currentDate = "";
1671
+ for (const line of log.stdout.toString().split("\n")) {
1672
+ const header = /^[0-9a-f]{7,40} (\d{4}-\d{2}-\d{2})/.exec(line);
1673
+ if (header) {
1674
+ currentDate = header[1];
1675
+ continue;
1676
+ }
1677
+ const path = line.trim();
1678
+ if (!path || !currentDate) continue;
1679
+ if (!lastCommit.has(path)) lastCommit.set(path, currentDate);
1680
+ }
1681
+ }
1682
+ return lastCommit;
1683
+ }
1684
+
1685
+ export function runDocHygiene(
1686
+ root: string,
1687
+ _findings?: unknown[],
1688
+ options?: { orphanAllowlist?: string[] },
1689
+ ) {
1690
+ const orphanAllowlist =
1691
+ options?.orphanAllowlist ?? loadConformityAllowlists(root).orphanFiles;
413
1692
  const specsDir = join(root, "specs");
414
1693
  const refDir = join(root, "reference");
415
1694
  // .claude/agents/ excluded — Claude Code reads those by name convention, not import
@@ -440,7 +1719,24 @@ export function runDocHygiene(root: string) {
440
1719
  ? readdirSync(dir).filter(f => exts.some(e => f.endsWith(e)))
441
1720
  : readdirSync(dir, { recursive: true }).map(f => String(f)).filter(f => exts.some(e => f.endsWith(e)));
442
1721
  for (const f of files) {
443
- try { chunks.push(readFileSync(join(dir, String(f)), "utf-8")); } catch {}
1722
+ const rel = String(f);
1723
+
1724
+ // skipDirs above only filters TOP-LEVEL entries of root, so the
1725
+ // recursive walk still descended into .claude/worktrees/ — which
1726
+ // holds full copies of the repo, 39 of them on the machine where
1727
+ // this was found. Every file in every worktree counted as a
1728
+ // reference, so nothing was ever an orphan locally while a clean CI
1729
+ // checkout saw three. That divergence is what made HYGIENE-3 look
1730
+ // intermittent and got a real failure dismissed as flake.
1731
+ if (rel.includes("worktrees/") || skipDirs.has(rel.split("/")[0])) continue;
1732
+
1733
+ // The allowlist names the very files it exempts, so counting it as a
1734
+ // reference makes every listed orphan stop being an orphan — the
1735
+ // ratchet then fails demanding they be delisted, and delisting makes
1736
+ // them orphans again. A list that invalidates itself by existing.
1737
+ if (rel.endsWith("conformity-allowlists.json")) continue;
1738
+
1739
+ try { chunks.push(readFileSync(join(dir, rel), "utf-8")); } catch {}
444
1740
  }
445
1741
  } catch {}
446
1742
  }
@@ -455,27 +1751,33 @@ export function runDocHygiene(root: string) {
455
1751
 
456
1752
  describe("Doc Hygiene", () => {
457
1753
  test("HYGIENE-1: All specs have non-empty governs field", () => {
458
- if (!existsSync(specsDir)) return;
1754
+ if (!existsSync(specsDir)) return checkSkipped("HYGIENE-1", "no specs/ directory");
459
1755
  const missing: string[] = [];
460
- for (const f of readdirSync(specsDir).filter(f => f.endsWith(".md"))) {
1756
+ for (const f of collectSpecFiles(specsDir)) { // #225 — subdirectories too
461
1757
  const content = readFileSync(join(specsDir, f), "utf-8");
462
1758
  const fm = parseFrontmatter(content);
463
1759
  if (!fm) continue;
464
1760
  const governs = fm.governs || "";
465
1761
  if (!governs || governs.includes("TODO")) missing.push(f);
466
1762
  }
467
- if (missing.length > 0) {
468
- console.warn(`Specs with empty/TODO governs field: ${missing.join(", ")}`);
469
- }
470
- expect(true).toBe(true);
1763
+ // Was unconditionally passing after a console.warn (#80).
1764
+ expect(missing).toEqual([]);
471
1765
  });
472
1766
 
473
1767
  test("HYGIENE-2: All specs have updated field in frontmatter", () => {
474
1768
  if (!existsSync(specsDir)) return;
475
1769
  const missing: string[] = [];
476
- for (const f of readdirSync(specsDir).filter(f => f.endsWith(".md"))) {
1770
+
1771
+ // #225 — the hand-rolled one-level descent that used to live here is
1772
+ // now the shared collector, so the seven flat callers get the same
1773
+ // behaviour instead of this one site being the only correct reader.
1774
+ const specFiles = collectSpecFiles(specsDir);
1775
+
1776
+ for (const f of specFiles) {
477
1777
  const content = readFileSync(join(specsDir, f), "utf-8");
478
1778
  const fm = parseFrontmatter(content);
1779
+ // Skip redirect files (status: split)
1780
+ if (fm?.status === "split") continue;
479
1781
  if (!fm || !fm.updated) missing.push(f);
480
1782
  }
481
1783
  expect(missing).toEqual([]);
@@ -490,25 +1792,60 @@ export function runDocHygiene(root: string) {
490
1792
  if (!index.includes(f)) orphans.push(`${relPath}/${f}`);
491
1793
  }
492
1794
  }
493
- if (orphans.length > 0) {
494
- console.warn(`Orphaned files (0 references — consider archiving to reference/):\n ${orphans.join("\n ")}`);
1795
+ // Was unconditionally passing after a console.warn (#80). Two orphans it
1796
+ // had been quietly reporting — specs/bootstrap-data-flow.png and
1797
+ // scripts/self-containment-check.sh — were archived to reference/, the
1798
+ // remedy this check recommends in its own message.
1799
+ //
1800
+ // Converting it to a bare `expect(orphans).toEqual([])` then turned Gates
1801
+ // red on main, because sizing from the warn output was taken as the
1802
+ // post-merge state without re-running the check against a clean tree. The
1803
+ // warn output listed two; a clean checkout has three more that local runs
1804
+ // did not surface. Same instrument as DRIFT-2 applies here and was not
1805
+ // used: list what cannot be fixed now, fail on an addition, fail if a
1806
+ // listed file gains a reference and is not delisted.
1807
+ //
1808
+ // Caller-owned for the same reason as DRIFT-2 — consumers must not
1809
+ // inherit rungate's exemptions.
1810
+ if (!orphanAllowlist) {
1811
+ if (orphans.length > 0) {
1812
+ console.warn(
1813
+ `WARN HYGIENE-3: ${orphans.length} file(s) with zero references — ` +
1814
+ `${orphans.join(", ")}. ADVISORY because no orphanAllowlist was supplied. ` +
1815
+ `Pass one to runDocHygiene to enforce it as a ratchet.`,
1816
+ );
1817
+ }
1818
+ return;
495
1819
  }
496
- expect(true).toBe(true);
1820
+
1821
+ const newOrphans = orphans.filter(o => !orphanAllowlist.includes(o));
1822
+ expect(newOrphans).toEqual([]);
1823
+
1824
+ const staleAllowlist = orphanAllowlist.filter(o => !orphans.includes(o));
1825
+ expect(staleAllowlist).toEqual([]);
497
1826
  });
498
1827
 
499
- test("HYGIENE-4: All specs listed in AGENTS.md are in AGENTS.md specs table", () => {
500
- if (!existsSync(specsDir) || !existsSync(join(root, "AGENTS.md"))) return;
501
- const agentsContent = readFileSync(join(root, "AGENTS.md"), "utf-8");
502
- const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md"));
503
- const unlisted = specFiles.filter(f => !agentsContent.includes(f));
504
- if (unlisted.length > 0) {
505
- console.warn(`Specs not listed in AGENTS.md: ${unlisted.join(", ")}`);
506
- }
507
- expect(true).toBe(true);
1828
+ test("HYGIENE-4: Every spec appears in the specs routing table", () => {
1829
+ // The table lives in .claude/rules/specs-routing.md, NOT AGENTS.md. This
1830
+ // check read AGENTS.md, which contains no spec references at all, so it
1831
+ // "found" 22 violations — every spec in the repo — and reported none of
1832
+ // them because it ended in expect(true).toBe(true) (#80). The premise was
1833
+ // stale, which is how a check this wrong stayed invisible.
1834
+ const routingPath = join(root, ".claude", "rules", "specs-routing.md");
1835
+ if (!existsSync(specsDir)) return checkSkipped("HYGIENE-4", "no specs/ directory");
1836
+ if (!existsSync(routingPath)) return checkSkipped("HYGIENE-4", "no .claude/rules/specs-routing.md");
1837
+ const routing = readFileSync(routingPath, "utf-8");
1838
+ const specFiles = readdirSync(specsDir)
1839
+ .filter(f => f.endsWith(".md"))
1840
+ // SPEC-TEMPLATE.md documents how to write a spec; it governs nothing.
1841
+ .filter(f => f !== "SPEC-TEMPLATE.md");
1842
+ const unlisted = specFiles.filter(f => !routing.includes(f));
1843
+ expect(unlisted).toEqual([]);
508
1844
  });
509
1845
 
510
1846
  test("HYGIENE-5: reference/ contents not in active routing", () => {
511
- if (!existsSync(refDir) || !existsSync(join(root, "AGENTS.md"))) return;
1847
+ if (!existsSync(refDir)) return checkSkipped("HYGIENE-5", "no reference/ directory");
1848
+ if (!existsSync(join(root, "AGENTS.md"))) return checkSkipped("HYGIENE-5", "no AGENTS.md");
512
1849
  const agentsContent = readFileSync(join(root, "AGENTS.md"), "utf-8");
513
1850
  const leaked: string[] = [];
514
1851
  for (const sub of readdirSync(refDir)) {
@@ -523,10 +1860,8 @@ export function runDocHygiene(root: string) {
523
1860
  }
524
1861
  } catch {}
525
1862
  }
526
- if (leaked.length > 0) {
527
- console.warn(`Archived files still referenced in AGENTS.md (stale routing): ${leaked.join(", ")}`);
528
- }
529
- expect(true).toBe(true);
1863
+ // Was unconditionally passing after a console.warn (#80).
1864
+ expect(leaked).toEqual([]);
530
1865
  });
531
1866
 
532
1867
  test("HYGIENE-10: All ADRs have doc-type: adr in frontmatter", () => {
@@ -540,7 +1875,7 @@ export function runDocHygiene(root: string) {
540
1875
  missing.push(f);
541
1876
  addFinding({
542
1877
  ruleId: "HYGIENE-10",
543
- severity: "FAIL",
1878
+ severity: "WARN",
544
1879
  file: `docs/adr/${f}`,
545
1880
  message: `ADR "${f}" missing doc-type: adr in frontmatter`,
546
1881
  fixCommand: `Add "doc-type: adr" to frontmatter of docs/adr/${f}`,
@@ -548,9 +1883,8 @@ export function runDocHygiene(root: string) {
548
1883
  }
549
1884
  }
550
1885
  if (missing.length > 0) {
551
- console.error(`HYGIENE-10 FAIL: ADRs missing doc-type: ${missing.join(", ")}`);
1886
+ console.warn(`HYGIENE-10 WARN: ADRs missing doc-type: ${missing.join(", ")}. Fix: add "doc-type: adr" to frontmatter.`);
552
1887
  }
553
- expect(missing).toEqual([]);
554
1888
  });
555
1889
 
556
1890
  test("HYGIENE-7: No spec files at root (must be in specs/)", () => {
@@ -636,7 +1970,14 @@ export function runDocHygiene(root: string) {
636
1970
  expect(misplaced).toEqual([]);
637
1971
  });
638
1972
 
639
- test("HYGIENE-6: No unreviewed constraint candidates in changed docs", async () => {
1973
+ // WARN, not a gate, and the name now says so. This reports a review
1974
+ // BACKLOG — 119 pending candidates on rungate as of #80 — so asserting it
1975
+ // to zero would block every push until someone triages all of them. It
1976
+ // previously claimed "No unreviewed constraint candidates" while ending in
1977
+ // expect(true).toBe(true), which is the dishonest combination: a gate-
1978
+ // sounding name over an unconditional pass. Advisory is the honest shape
1979
+ // here; the lie was the name, not the leniency.
1980
+ test("WARN HYGIENE-6: Unreviewed constraint candidates in changed docs", async () => {
640
1981
  const { extractConstraints } = await import("../scripts/extract-constraints");
641
1982
  const result = await extractConstraints(root, { apply: false });
642
1983
 
@@ -663,6 +2004,116 @@ export function runDocHygiene(root: string) {
663
2004
  expect(true).toBe(true);
664
2005
  });
665
2006
 
2007
+ test("HYGIENE-11: Stale unreferenced files warn with archival suggestion", () => {
2008
+ const index = getRefIndex();
2009
+ // stalenessThreshold through the loader (ADR-002 D1, #309), default 90
2010
+ // days. The bare `catch {}` is kept deliberately narrow in meaning: a
2011
+ // config that cannot be read must not take HYGIENE-11 down, but it also
2012
+ // must not silently become 90 — which, with nothing logged, is what it
2013
+ // used to do.
2014
+ let threshold = 90;
2015
+ try {
2016
+ const config = tryLoadRungateConfig(root);
2017
+ if (typeof config?.stalenessThreshold === "number") {
2018
+ threshold = config.stalenessThreshold;
2019
+ }
2020
+ } catch (err) {
2021
+ console.warn(
2022
+ `WARN: HYGIENE-11 could not read the rungate config (${(err as Error).name}); ` +
2023
+ `using the ${threshold}-day default. A configured threshold is NOT in effect.`,
2024
+ );
2025
+ }
2026
+
2027
+ // Scan docs directories for markdown files — skip reference/ entirely (AC-2)
2028
+ const scanTargets: string[] = [];
2029
+ const docDirs = ["specs", "docs", "docs/adr", "docs/research", "docs/council", "docs/guides"];
2030
+ for (const rel of docDirs) {
2031
+ const dir = join(root, rel);
2032
+ if (!existsSync(dir)) continue;
2033
+ for (const f of readdirSync(dir).filter(f => f.endsWith(".md"))) {
2034
+ const fullPath = join(dir, f);
2035
+ try {
2036
+ if (statSync(fullPath).isFile()) {
2037
+ scanTargets.push(`${rel}/${f}`);
2038
+ }
2039
+ } catch {}
2040
+ }
2041
+ }
2042
+
2043
+ // Also scan root-level markdown (excluding reference/)
2044
+ for (const f of readdirSync(root).filter(f => f.endsWith(".md"))) {
2045
+ scanTargets.push(f);
2046
+ }
2047
+
2048
+ // Filter out reference/ paths (AC-2)
2049
+ const filtered = scanTargets.filter(f => !f.startsWith("reference/") && !f.includes("/reference/"));
2050
+
2051
+ // One git call for every file, not one per file (#323).
2052
+ //
2053
+ // This was `spawnSync("git", ["log", "-1", ..., "--", rel])` inside the
2054
+ // loop: 60 serial subprocesses against the same repository, each with
2055
+ // its own 5-second timeout. Nothing was wrong with any single call — the
2056
+ // test was load-sensitive by construction, and if any one spawn was slow
2057
+ // (another suite holding the index, a busy machine, a cold cache) it hit
2058
+ // the timeout and the test went red. Measured at 1 failure in 3
2059
+ // identical runs, always at ~5007 ms. It also got worse on its own as
2060
+ // the repo grew, because more docs means more dice rolls.
2061
+ //
2062
+ // `--name-only` over the whole history, walked newest-first, gives every
2063
+ // path's most recent commit date from a single subprocess. The first
2064
+ // time a path is seen is its latest commit, so later entries are
2065
+ // ignored.
2066
+ //
2067
+ // `filtered` is passed, NOT `docDirs`. The first cut of this fix passed
2068
+ // the six doc directories, and `git log -- specs docs` has nothing to
2069
+ // say about the six root-level markdown files this scan also walks —
2070
+ // AGENTS.md, CLAUDE.md, SUCCESS.md and friends dropped out of the map,
2071
+ // and the `if (!dateStr) continue` below read that as "newly added, so
2072
+ // not stale". Handing it the exact lookup set keeps the pathspec and the
2073
+ // keys the same list by construction.
2074
+ const lastCommit = lastCommitDates(root, filtered);
2075
+
2076
+ const staleUnreferenced: { file: string; daysSince: number }[] = [];
2077
+ for (const rel of filtered) {
2078
+ const dateStr = lastCommit.get(rel);
2079
+ // No commit for this path means it is untracked or newly added, which
2080
+ // is the opposite of stale.
2081
+ if (!dateStr) continue;
2082
+ const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
2083
+ if (daysSince <= threshold) continue;
2084
+
2085
+ // Check cross-references: filename must appear somewhere in the codebase index
2086
+ const basename = rel.split("/").pop()!;
2087
+ if (index.includes(basename)) continue;
2088
+
2089
+ staleUnreferenced.push({ file: rel, daysSince: Math.floor(daysSince) });
2090
+ }
2091
+
2092
+ // AC-3: Each warning includes git mv archival command
2093
+ if (staleUnreferenced.length > 0) {
2094
+ for (const entry of staleUnreferenced) {
2095
+ const archiveDest = `reference/${entry.file.split("/").pop()}`;
2096
+ addFinding({
2097
+ ruleId: "HYGIENE-11",
2098
+ severity: "WARN",
2099
+ file: entry.file,
2100
+ message: `Stale unreferenced file (${entry.daysSince}d, threshold=${threshold}d)`,
2101
+ fixCommand: `git mv ${entry.file} ${archiveDest}`,
2102
+ });
2103
+ console.warn(`HYGIENE-11: ${entry.file} — stale (${entry.daysSince}d) and unreferenced. Fix: git mv ${entry.file} ${archiveDest}`);
2104
+ }
2105
+ }
2106
+
2107
+ // AC-1: At least 2 assertions
2108
+ // 1. reference/ files were filtered out
2109
+ const referenceFiles = scanTargets.filter(f => f.startsWith("reference/") || f.includes("/reference/"));
2110
+ expect(filtered.every(f => !f.startsWith("reference/") && !f.includes("/reference/"))).toBe(true);
2111
+
2112
+ // 2. All stale unreferenced entries have git mv fix commands
2113
+ const hygieneFindings = getFindings().filter(f => f.ruleId === "HYGIENE-11");
2114
+ expect(hygieneFindings.every(f => f.fixCommand?.startsWith("git mv "))).toBe(true);
2115
+ });
2116
+
666
2117
  test("HYGIENE-REPORT: Write unified findings report", () => {
667
2118
  const findings = getFindings();
668
2119
  const candidates = getCandidates();
@@ -756,20 +2207,239 @@ export function runAgentFileValidation(root: string) {
756
2207
  expect(mismatched).toEqual([]);
757
2208
  });
758
2209
 
759
- test("AGENT-5: Agent files reference AGENTS.md for context", () => {
2210
+ test("AGENT-5: Shared agent principles exist as unconditional rule", () => {
2211
+ const rulesDir = join(root, ".claude", "rules");
2212
+ if (!existsSync(rulesDir)) {
2213
+ addFinding({ ruleId: "AGENT-5", severity: "FAIL", file: ".claude/rules/", message: "No rules directory found", fixCommand: "Re-scaffold to generate rules" });
2214
+ expect(existsSync(rulesDir)).toBe(true);
2215
+ return;
2216
+ }
2217
+ const principlesFile = join(rulesDir, "agent-principles.md");
2218
+ expect(existsSync(principlesFile)).toBe(true);
2219
+ const content = readFileSync(principlesFile, "utf-8");
2220
+ expect(content).toContain("Core Principles");
2221
+ });
2222
+
2223
+ test("AGENT-7: All agent briefs have required sections", () => {
760
2224
  if (!existsSync(agentsDir)) return;
2225
+ const sectionChecks: Array<{ name: string; pattern: RegExp }> = [
2226
+ { name: "frontmatter", pattern: /^---\n[\s\S]*?\n---/ },
2227
+ { name: "identity", pattern: /You are\s+\w+/i },
2228
+ { name: "agent-specific-section", pattern: /^##\s+(Workflow|Rules|Testing|Discovery|What you|TDD|CLI|UI|Project Type|Efficiency|Design|Architecture|Context|Report)/im },
2229
+ ];
761
2230
  const missing: string[] = [];
762
2231
  for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
763
2232
  const content = readFileSync(join(agentsDir, f), "utf-8");
764
- if (!content.includes("AGENTS.md")) {
765
- missing.push(f);
2233
+ for (const check of sectionChecks) {
2234
+ if (!check.pattern.test(content)) {
2235
+ missing.push(`${f}: missing required section '${check.name}'`);
2236
+ addFinding({
2237
+ ruleId: "AGENT-REQUIRED-SECTION",
2238
+ severity: "FAIL",
2239
+ file: `.claude/agents/${f}`,
2240
+ message: `Brief missing required section: ${check.name}`,
2241
+ });
2242
+ }
766
2243
  }
767
2244
  }
768
2245
  if (missing.length > 0) {
769
- console.warn(`Agent files not referencing AGENTS.md (won't read project context):\n ${missing.join("\n ")}`);
2246
+ console.error(`Agent briefs missing required sections:\n ${missing.join("\n ")}`);
770
2247
  }
771
2248
  expect(missing).toEqual([]);
772
2249
  });
2250
+
2251
+ test("AGENT-8: Agent brief models match the roles config", () => {
2252
+ if (!existsSync(agentsDir)) return;
2253
+ // Was hardcoded to "sonnet". Roles are now routed per-role, so the
2254
+ // meaningful check is that each brief matches its configured model —
2255
+ // briefs are generated from that config, and a mismatch means someone
2256
+ // hand-edited generated output.
2257
+ //
2258
+ // #90: this read `.claude/rungate.json` directly, which is the LEGACY
2259
+ // monolith. Scaffold migrated projects to `.claude/rungate/` and
2260
+ // generates briefs from `roles.json` there, so on any migrated project
2261
+ // the generator and this validator read different files. They disagreed
2262
+ // in this very repo — roles.json said sonnet, the stale monolith said
2263
+ // opus — and AGENT-8 reported a violation against output that exactly
2264
+ // matched its real source.
2265
+ //
2266
+ // The failure mode was worse than a false alarm: the message told the
2267
+ // reader to "re-scaffold instead of editing the brief", and
2268
+ // re-scaffolding reproduced the same briefs, so following the advice
2269
+ // could not clear it.
2270
+ //
2271
+ // Go through the canonical loader, which understands both layouts and
2272
+ // prefers the directory. tryLoadRungateConfig is the non-throwing
2273
+ // variant: absent config is "nothing to check", while a MALFORMED
2274
+ // config still throws, per ADR-001 D2 — a broken config must not read
2275
+ // as an unconfigured one.
2276
+ const VALID_MODELS = ["sonnet", "opus", "haiku", "fable"];
2277
+ const roles: Record<string, { model?: string }> =
2278
+ (tryLoadRungateConfig(root)?.roles as Record<string, { model?: string }>) ?? {};
2279
+
2280
+ const wrong: string[] = [];
2281
+ for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
2282
+ const content = readFileSync(join(agentsDir, f), "utf-8");
2283
+ const fm = parseFrontmatter(content);
2284
+ const role = f.replace(/\.md$/, "");
2285
+ const expected = roles[role]?.model;
2286
+ if (!fm?.model) {
2287
+ wrong.push(`${f}: missing model field`);
2288
+ } else if (!VALID_MODELS.includes(fm.model)) {
2289
+ wrong.push(`${f}: model is "${fm.model}", expected one of ${VALID_MODELS.join("|")}`);
2290
+ } else if (expected && fm.model !== expected) {
2291
+ wrong.push(`${f}: model is "${fm.model}", but the roles config says "${expected}" — re-scaffold instead of editing the brief`);
2292
+ }
2293
+ }
2294
+ if (wrong.length > 0) {
2295
+ wrong.forEach(w => addFinding({
2296
+ ruleId: "AGENT-MODEL",
2297
+ severity: "FAIL",
2298
+ file: `.claude/agents/${w.split(":")[0]}`,
2299
+ message: w,
2300
+ }));
2301
+ console.error(`Agent briefs with wrong model:\n ${wrong.join("\n ")}`);
2302
+ }
2303
+ expect(wrong).toEqual([]);
2304
+ });
2305
+
2306
+ test("AGENT-9: All agent briefs are under 120 lines", () => {
2307
+ if (!existsSync(agentsDir)) return;
2308
+ const over: string[] = [];
2309
+ for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
2310
+ const content = readFileSync(join(agentsDir, f), "utf-8");
2311
+ const lineCount = content.trimEnd().split("\n").length;
2312
+ if (lineCount > 120) {
2313
+ over.push(`${f}: ${lineCount} lines (max 120)`);
2314
+ addFinding({
2315
+ ruleId: "AGENT-LINECOUNT",
2316
+ severity: "FAIL",
2317
+ file: `.claude/agents/${f}`,
2318
+ message: `Brief is ${lineCount} lines, exceeds 120-line cap`,
2319
+ });
2320
+ }
2321
+ }
2322
+ if (over.length > 0) {
2323
+ console.error(`Agent briefs over 120 lines:\n ${over.join("\n ")}`);
2324
+ }
2325
+ expect(over).toEqual([]);
2326
+ });
2327
+
2328
+ test("AGENT-11: AGENTS.md is under line cap (sigmoid collapse prevention)", () => {
2329
+ const agentsMdPath = join(root, "AGENTS.md");
2330
+ if (!existsSync(agentsMdPath)) return;
2331
+ const content = readFileSync(agentsMdPath, "utf-8");
2332
+ const lineCount = content.trimEnd().split("\n").length;
2333
+ const consumerLines = (content.match(/^- \w/gm) || []).length;
2334
+ const cap = 100 + Math.max(0, consumerLines - 10);
2335
+ if (lineCount > cap) {
2336
+ addFinding({
2337
+ ruleId: "AGENTS-MD-LINECOUNT",
2338
+ severity: "FAIL",
2339
+ file: "AGENTS.md",
2340
+ message: `AGENTS.md is ${lineCount} lines, exceeds ${cap}-line cap (base 100 + ${Math.max(0, consumerLines - 10)} consumer lines). Move reference tables to .claude/rules/`,
2341
+ });
2342
+ }
2343
+ expect(lineCount).toBeLessThanOrEqual(cap);
2344
+ });
2345
+
2346
+ test("AGENT-10: No unfilled template variables in agent briefs", () => {
2347
+ if (!existsSync(agentsDir)) return;
2348
+ const unfilled: string[] = [];
2349
+ for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
2350
+ const content = readFileSync(join(agentsDir, f), "utf-8");
2351
+ const vars = content.match(/\$\{[A-Z_]+\}/g);
2352
+ if (vars && vars.length > 0) {
2353
+ unfilled.push(`${f}: unfilled template variables: ${vars.join(", ")}`);
2354
+ addFinding({
2355
+ ruleId: "AGENT-TEMPLATE-VAR",
2356
+ severity: "FAIL",
2357
+ file: `.claude/agents/${f}`,
2358
+ message: `Brief has unfilled template variables: ${vars.join(", ")}`,
2359
+ });
2360
+ }
2361
+ }
2362
+ if (unfilled.length > 0) {
2363
+ console.error(`Agent briefs with unfilled template variables:\n ${unfilled.join("\n ")}`);
2364
+ }
2365
+ expect(unfilled).toEqual([]);
2366
+ });
2367
+
2368
+ test("AGENT-6: All file paths referenced in briefs exist", () => {
2369
+ if (!existsSync(agentsDir)) return;
2370
+ const broken: string[] = [];
2371
+ for (const f of readdirSync(agentsDir).filter(f => f.endsWith(".md"))) {
2372
+ const content = readFileSync(join(agentsDir, f), "utf-8");
2373
+ const refs = content.match(/node_modules\/[^\s`*)"']+/g) || [];
2374
+ for (const ref of refs) {
2375
+ const clean = ref.replace(/[`*)"']+$/, "");
2376
+ if (!existsSync(join(root, clean))) {
2377
+ broken.push(`${f} → ${clean}`);
2378
+ addFinding({
2379
+ ruleId: "AGENT-BROKEN-REF",
2380
+ severity: "FAIL",
2381
+ file: `.claude/agents/${f}`,
2382
+ message: `Brief references "${clean}" but file does not exist`,
2383
+ fixCommand: `Check prompts/ directory for correct filename — may be a typo or renamed file`,
2384
+ });
2385
+ }
2386
+ }
2387
+ }
2388
+ if (broken.length > 0) {
2389
+ console.error(`Broken references in agent briefs:\n ${broken.join("\n ")}`);
2390
+ }
2391
+ expect(broken).toEqual([]);
2392
+ });
2393
+ });
2394
+ }
2395
+
2396
+ // ── SC-294: Directory validation ───────────────────────────
2397
+
2398
+ export function runDirectoryValidation(root: string) {
2399
+ const specsDir = join(root, "specs");
2400
+
2401
+ describe("Directory Validation (SC-294)", () => {
2402
+ test("SC-294: Every specs/ subdirectory has a parent spec file", () => {
2403
+ if (!existsSync(specsDir)) return;
2404
+
2405
+ const invalid: string[] = [];
2406
+
2407
+ // Find all subdirectories in specs/
2408
+ const entries = readdirSync(specsDir);
2409
+ const subdirs = entries.filter(entry => {
2410
+ const fullPath = join(specsDir, entry);
2411
+ try {
2412
+ return statSync(fullPath).isDirectory();
2413
+ } catch {
2414
+ return false;
2415
+ }
2416
+ });
2417
+
2418
+ // For each subdirectory, check if there's a corresponding parent spec
2419
+ for (const subdir of subdirs) {
2420
+ // Find all .md files in specs/
2421
+ const specFiles = entries.filter(f => f.endsWith(".md"));
2422
+
2423
+ // Check if any spec file derives to this directory name
2424
+ let found = false;
2425
+ for (const specFile of specFiles) {
2426
+ const derived = deriveDirectoryName(specFile);
2427
+ if (derived === subdir) {
2428
+ found = true;
2429
+ break;
2430
+ }
2431
+ }
2432
+
2433
+ if (!found) {
2434
+ invalid.push(`${subdir}/: no parent spec derives to this directory name`);
2435
+ }
2436
+ }
2437
+
2438
+ if (invalid.length > 0) {
2439
+ console.error(`Hand-created directories (SC-294 violation):\n ${invalid.join("\n ")}\n\nDirectories MUST be created by split-spec.ts, not manually.`);
2440
+ }
2441
+ expect(invalid).toEqual([]);
2442
+ });
773
2443
  });
774
2444
  }
775
2445
 
@@ -786,7 +2456,38 @@ interface FallowResult {
786
2456
  workspace_diagnostics: Array<{ kind: string; message: string }>;
787
2457
  }
788
2458
 
2459
+ // `fallow` is an optional external tool and is NOT a declared dependency. When
2460
+ // it is absent, `npx fallow` does a registry fetch on every invocation — four
2461
+ // tests x one fetch each, each outliving bun's per-test timeout. The tests then
2462
+ // fail as timeouts instead of skipping, which blocks the pre-push conformity
2463
+ // gate on a tool nobody installed.
2464
+ //
2465
+ // Resolve it locally instead, with no network path. Memoised PER ROOT —
2466
+ // runFallowCheck is exported and consumer projects call it with their own
2467
+ // root, so a single process can ask about several. A root-independent cache
2468
+ // would answer for the wrong directory.
2469
+ const FALLOW_AVAILABLE = new Map<string, boolean>();
2470
+
2471
+ function fallowAvailable(root: string): boolean {
2472
+ const cached = FALLOW_AVAILABLE.get(root);
2473
+ if (cached !== undefined) return cached;
2474
+ const available =
2475
+ existsSync(join(root, "node_modules", ".bin", "fallow")) ||
2476
+ Bun.which("fallow") !== null;
2477
+ FALLOW_AVAILABLE.set(root, available);
2478
+ return available;
2479
+ }
2480
+
2481
+ /** Shared skip notice — a skipped check must say so, not read as a pass. */
2482
+ function fallowSkipped(check: string): void {
2483
+ console.warn(
2484
+ `SKIP ${check}: fallow is not installed (not a declared dependency) — ` +
2485
+ `this check did NOT run. Install it to enable static analysis.`,
2486
+ );
2487
+ }
2488
+
789
2489
  function runFallowCommand(root: string, args: string[]): FallowResult | null {
2490
+ if (!fallowAvailable(root)) return null;
790
2491
  const result = Bun.spawnSync(["npx", "fallow", ...args, "--format", "json", "--quiet"], {
791
2492
  cwd: root,
792
2493
  env: { ...process.env, NODE_NO_WARNINGS: "1" },
@@ -806,10 +2507,7 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
806
2507
  describe("Fallow: static analysis", () => {
807
2508
  test("FALLOW-1: No unused files", () => {
808
2509
  const result = runFallowCommand(root, ["dead-code", "--unused-files"]);
809
- if (!result) {
810
- console.warn("Fallow not available or failed to run — skipping");
811
- return;
812
- }
2510
+ if (!result) { fallowSkipped("FALLOW-1 (unused files)"); return; }
813
2511
  const unused = result.unused_files.map(f => f.path).filter(p => !p.includes("test/fixtures/") && !p.includes("reference/"));
814
2512
  if (unused.length > 0) {
815
2513
  console.warn(`Unused files (${unused.length}):\n ${unused.slice(0, 10).join("\n ")}${unused.length > 10 ? `\n ... and ${unused.length - 10} more` : ""}`);
@@ -820,7 +2518,7 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
820
2518
  if (!opts?.skipUnusedExports) {
821
2519
  test("FALLOW-2: No unused exports", () => {
822
2520
  const result = runFallowCommand(root, ["dead-code", "--unused-exports"]);
823
- if (!result) return;
2521
+ if (!result) { fallowSkipped("FALLOW-2 (unused exports)"); return; }
824
2522
  const unused = (result.unused_exports || [])
825
2523
  .filter(e => !e.path.includes("test/fixtures/") && !e.path.includes("reference/"))
826
2524
  .map(e => `${e.path}:${e.line ?? "?"} ${e.export_name}`);
@@ -833,7 +2531,7 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
833
2531
 
834
2532
  test("FALLOW-3: No unused dependencies", () => {
835
2533
  const result = runFallowCommand(root, ["dead-code", "--unused-deps"]);
836
- if (!result) return;
2534
+ if (!result) { fallowSkipped("FALLOW-3 (unused dependencies)"); return; }
837
2535
  const unused = result.unused_dependencies?.map(d => d.name) || [];
838
2536
  if (unused.length > 0) {
839
2537
  console.warn(`Unused dependencies (${unused.length}):\n ${unused.join("\n ")}`);
@@ -843,10 +2541,10 @@ export function runFallowCheck(root: string, opts?: { skipUnusedExports?: boolea
843
2541
 
844
2542
  test("FALLOW-4: No circular dependencies", () => {
845
2543
  const result = runFallowCommand(root, ["dead-code"]);
846
- if (!result) return;
2544
+ if (!result) { fallowSkipped("FALLOW-4 (circular dependencies)"); return; }
847
2545
  const circles = result.circular_dependencies || [];
848
2546
  if (circles.length > 0) {
849
- console.warn(`Circular dependencies (${circles.length}):\n ${circles.slice(0, 5).map(c => c.path || JSON.stringify(c.files || c)).join("\n ")}${circles.length > 5 ? `\n ... and ${circles.length - 5} more` : ""}`);
2547
+ console.warn(`Circular dependencies (${circles.length}):\n ${circles.slice(0, 5).map(c => c.path || JSON.stringify(c.chain ?? c)).join("\n ")}${circles.length > 5 ? `\n ... and ${circles.length - 5} more` : ""}`);
850
2548
  }
851
2549
  if (fail) expect(circles).toEqual([]);
852
2550
  });
@@ -872,15 +2570,51 @@ export function runPackageValidation(root: string) {
872
2570
  const pkgPath = join(root, "package.json");
873
2571
  if (!existsSync(pkgPath)) return;
874
2572
  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
2573
+ // The harness is not a consumer of itself. npm has no way to express
2574
+ // a self-dependency and would be wrong to: `rungate` IS the thing
2575
+ // this check asks every other project to depend on. Surfaced by #208
2576
+ // — once rungate's own conformity test stopped being frozen by
2577
+ // `safeWrite`, this check ran here for the first time and failed on a
2578
+ // requirement it is not possible to satisfy.
2579
+ if (isHarnessItself(root)) return;
875
2580
  expect(pkg.devDependencies?.rungate).toBeDefined();
876
2581
  });
877
2582
  });
878
2583
  }
879
2584
 
2585
+ /**
2586
+ * #87 — TSC-1 demanded a tsconfig.json that the generator had deliberately
2587
+ * decided not to write.
2588
+ *
2589
+ * `createTsconfig` skips a project with no hand-written TypeScript, because a
2590
+ * tsconfig whose `include` matches nothing is tsc error TS18003 — a type check
2591
+ * that reads as broken rather than as "nothing to check". `createCiWorkflows`
2592
+ * and the AGENTS.md generator both agreed and emitted no step and no row. Then
2593
+ * this hard assert ran in that same consumer's generated conformity suite and
2594
+ * failed over the absent file. Both halves of the question were asserted at
2595
+ * once, which is the contradiction #87 was filed to settle.
2596
+ *
2597
+ * Settled in favour of "consumers may be non-TypeScript projects", so TSC-1
2598
+ * asks `tsconfigVerdict` — the one predicate `createTsconfig` uses — whether
2599
+ * it has anything to assert. The skip is RECORDED as a finding rather than
2600
+ * taken quietly: an unmeasured check and a satisfied check look identical from
2601
+ * the outside, and `.claude/rules/config-access.md` names the silent form as
2602
+ * the anti-pattern it is.
2603
+ */
880
2604
  export function runTsconfigValidation(root: string) {
881
2605
  describe("TSConfig validation", () => {
882
- test("TSC-1: tsconfig.json exists", () => {
883
- expect(existsSync(join(root, "tsconfig.json"))).toBe(true);
2606
+ test("TSC-1: tsconfig.json exists where TypeScript source does", () => {
2607
+ const verdict = tsconfigVerdict(root);
2608
+ if (!verdict.applicable) {
2609
+ addFinding({
2610
+ ruleId: "TSC-1",
2611
+ severity: "WARN",
2612
+ file: "tsconfig.json",
2613
+ message: `UNMEASURED: ${verdict.reason}`,
2614
+ });
2615
+ return;
2616
+ }
2617
+ expect(verdict.present, verdict.reason).toBe(true);
884
2618
  });
885
2619
 
886
2620
  test("TSC-2: strict mode enabled", () => {
@@ -940,12 +2674,302 @@ export function runModuleDepthCheck(root: string) {
940
2674
  });
941
2675
  }
942
2676
 
2677
+ // ── Config access conformity (ADR-002 D4, #309) ────────────────
2678
+ //
2679
+ // ADR-001 decided the single-loader policy on 2026-10-05 and specified this
2680
+ // check as the enforcement. It was never built. Six days later the thing it
2681
+ // was written to stop had gone from ~24 sites to ~89 — the policy was
2682
+ // written down the whole time, which is the measurement that makes
2683
+ // "a rule nothing executes is not a rule" a number rather than a slogan.
2684
+ //
2685
+ // TWO checks, not one, because there are two bypass routes and ADR-001's
2686
+ // single check would have missed eleven of them: `workflows/*.js` reaches
2687
+ // config from inside agent PROMPT TEXT, which a TypeScript-source scan does
2688
+ // not look at.
2689
+ //
2690
+ // ## The self-reference trap
2691
+ //
2692
+ // This file is inside the scanned set and is about to contain the literals
2693
+ // it searches for. An allowlist naming the exempt files becomes evidence
2694
+ // those files are referenced — this repo has hit that three times. So the
2695
+ // pattern is ASSEMBLED from fragments that never appear adjacent in this
2696
+ // source, and the test asserts the check reports zero against its own file.
2697
+ // The three real violations this file used to carry are migrated to the
2698
+ // loader in the same change, so that zero is a fact and not an exemption.
2699
+ const CFG_DOT = ".";
2700
+ const CFG_DIR = "claude";
2701
+ const CFG_NAME = "rungate";
2702
+
2703
+ /**
2704
+ * A path being built to the config, in CODE.
2705
+ *
2706
+ * Comments are blanked by `stripJsComments` before this runs — offset
2707
+ * preserving, already proven on `ship.js` by its own suite — rather than by a
2708
+ * line rule of my own. Prose that DISCUSSES the config is not an access, and
2709
+ * counting it would bury the real sites in noise until the ratchet became a
2710
+ * number nobody reads.
2711
+ *
2712
+ * STATED LIMIT, carried over from ADR-001 and not an oversight: this is
2713
+ * string matching, so `join(root, CFG_DOT + CFG_DIR, dynamicName)` is not
2714
+ * caught. It catches every one of the present sites; a variable-constructed
2715
+ * path is not the realistic failure mode and an AST check is not worth the
2716
+ * dependency.
2717
+ */
2718
+ function configAccessPattern(): RegExp {
2719
+ return new RegExp(
2720
+ "\\" + CFG_DOT + CFG_DIR + "[\"'`/\\\\,\\s)]+\\s*[\"'`]?" + CFG_NAME,
2721
+ "g",
2722
+ );
2723
+ }
2724
+
2725
+ /** Directories CHECK-1 walks. Tests and `test/` are excluded by ADR-002 D4. */
2726
+ const CONFIG_SCAN_DIRS = ["lib", "gates", "scripts", "hooks", "generators"];
2727
+
2728
+ /** The one module allowed to read the config. ADR-002 D1. */
2729
+ const CONFIG_LOADER = "lib/config-loader.ts";
2730
+
2731
+ function walkSources(dir: string, rel: string, out: Array<{ path: string; text: string }>) {
2732
+ let entries;
2733
+ try {
2734
+ entries = readdirSync(dir, { withFileTypes: true });
2735
+ } catch {
2736
+ return;
2737
+ }
2738
+ for (const e of entries) {
2739
+ const abs = join(dir, e.name);
2740
+ const relPath = rel ? `${rel}/${e.name}` : e.name;
2741
+ if (e.isDirectory()) {
2742
+ if (e.name === "test" || e.name === "node_modules") continue;
2743
+ walkSources(abs, relPath, out);
2744
+ continue;
2745
+ }
2746
+ if (!/\.(ts|js)$/.test(e.name) || /\.test\.ts$/.test(e.name)) continue;
2747
+ out.push({ path: relPath, text: readFileSync(abs, "utf-8") });
2748
+ }
2749
+ }
2750
+
2751
+ /** What a scan saw: per-file counts, and how much it actually read. */
2752
+ export interface ConfigAccessScan {
2753
+ /** Repo-relative path -> site count. Allowlisted files are excluded. */
2754
+ counts: Record<string, number>;
2755
+ /** Files walked. ZERO means the scan found nothing to look at. */
2756
+ filesScanned: number;
2757
+ /** Bytes read. Zero with a non-zero file count means empty sources. */
2758
+ bytesScanned: number;
2759
+ }
2760
+
2761
+ /**
2762
+ * CHECK-1's reading: direct config access in TypeScript sources.
2763
+ *
2764
+ * A separate function from the refusal so there is ONE site for the mutation
2765
+ * harness to short-circuit (`.claude/rules/checks-must-be-able-to-fail.md`,
2766
+ * and ADR-002 D4's third mutation).
2767
+ */
2768
+ export function scanConfigAccess(root: string): ConfigAccessScan {
2769
+ const files: Array<{ path: string; text: string }> = [];
2770
+ for (const d of CONFIG_SCAN_DIRS) walkSources(join(root, d), d, files);
2771
+
2772
+ const counts: Record<string, number> = {};
2773
+ let bytesScanned = 0;
2774
+ for (const f of files) {
2775
+ bytesScanned += f.text.length;
2776
+ if (f.path === CONFIG_LOADER) continue;
2777
+ const n = (stripJsComments(f.text).match(configAccessPattern()) || []).length;
2778
+ if (n > 0) counts[f.path] = n;
2779
+ }
2780
+ return { counts, filesScanned: files.length, bytesScanned };
2781
+ }
2782
+
2783
+ /**
2784
+ * CHECK-2's reading: config access inside `workflows/*.js`, prompts included.
2785
+ *
2786
+ * Comments are stripped and literals are NOT, which is the whole point —
2787
+ * `ship.js` is mostly prompt text, and the eleven sites ADR-001's check could
2788
+ * not see all live inside template literals handed to agents.
2789
+ */
2790
+ export function scanPromptConfigAccess(root: string): ConfigAccessScan {
2791
+ const dir = join(root, "workflows");
2792
+ const counts: Record<string, number> = {};
2793
+ let filesScanned = 0;
2794
+ let bytesScanned = 0;
2795
+ let entries: string[];
2796
+ try {
2797
+ entries = readdirSync(dir).filter(f => f.endsWith(".js"));
2798
+ } catch {
2799
+ return { counts, filesScanned: 0, bytesScanned: 0 };
2800
+ }
2801
+ for (const f of entries) {
2802
+ const text = readFileSync(join(dir, f), "utf-8");
2803
+ filesScanned++;
2804
+ bytesScanned += text.length;
2805
+ const n = (stripJsComments(text).match(configAccessPattern()) || []).length;
2806
+ if (n > 0) counts[`workflows/${f}`] = n;
2807
+ }
2808
+ return { counts, filesScanned, bytesScanned };
2809
+ }
2810
+
2811
+ /**
2812
+ * The banked violations, read from `.claude/config-access-ratchet.json`.
2813
+ *
2814
+ * Data rather than a constant, because `lib/conformity.ts` travels into every
2815
+ * scaffolded project and rungate's own numbers have no business there. A
2816
+ * consumer with no ratchet file gets `{}` — zero tolerance, which is the
2817
+ * right default for a tree that has never had the defect.
2818
+ *
2819
+ * NOT `.claude/rungate*`, deliberately: this is harness metadata about a
2820
+ * migration, not project config, and routing it through the loader would make
2821
+ * the check depend on the thing it is enforcing access to.
2822
+ */
2823
+ export function readConfigAccessRatchet(
2824
+ root: string,
2825
+ scope: "sources" | "workflows" | "all" = "all",
2826
+ ): Record<string, number> {
2827
+ const p = join(root, ".claude", "config-access-ratchet.json");
2828
+ if (!existsSync(p)) return {};
2829
+ const raw = JSON.parse(readFileSync(p, "utf-8"));
2830
+ const out: Record<string, number> = {};
2831
+ for (const [k, v] of Object.entries(raw)) {
2832
+ if (typeof v !== "number") continue;
2833
+ // One file, two checks. Scoping matters because the both-ways ratchet
2834
+ // complains about a banked entry with no violations left, and CHECK-1
2835
+ // never scans `workflows/` — without this it would demand the removal of
2836
+ // every entry CHECK-2 owns, and vice versa.
2837
+ const isWorkflow = k.startsWith("workflows/");
2838
+ if (scope === "sources" && isWorkflow) continue;
2839
+ if (scope === "workflows" && !isWorkflow) continue;
2840
+ out[k] = v;
2841
+ }
2842
+ return out;
2843
+ }
2844
+
2845
+ /**
2846
+ * Turn a scan into refusals. Empty allows. BOTH DIRECTIONS.
2847
+ *
2848
+ * Over its number refuses, and so does UNDER — an entry that has stopped
2849
+ * being a violation is an entry nobody will ever remove, and the list rots
2850
+ * into one more artefact that certifies nothing. A file absent from the
2851
+ * ratchet is allowed nothing, which is ADR-002 D4's requirement that the
2852
+ * ratchet "refuses on any new file entering the violation set even while the
2853
+ * count is above zero": the migration window is exactly when the next reader
2854
+ * is most likely to be written.
2855
+ *
2856
+ * An EMPTY SCAN REFUSES. A conformity check that silently scans zero files
2857
+ * reports zero violations and is indistinguishable from compliance, which is
2858
+ * this repo's defining defect and would be the most embarrassing possible
2859
+ * place to reproduce it (ADR-002 D4, mutation 5).
2860
+ */
2861
+ export function configAccessViolations(
2862
+ scan: ConfigAccessScan,
2863
+ banked: Record<string, number>,
2864
+ label: string,
2865
+ requireNonEmpty = true,
2866
+ ): string[] {
2867
+ const out: string[] = [];
2868
+ if (requireNonEmpty && scan.filesScanned === 0) {
2869
+ return [
2870
+ `${label}: the scan read NO files. A check that scans nothing reports ` +
2871
+ `zero violations and cannot be told from compliance — refusing rather ` +
2872
+ `than reporting clean (ADR-002 D4).`,
2873
+ ];
2874
+ }
2875
+ if (requireNonEmpty && scan.filesScanned > 0 && scan.bytesScanned === 0) {
2876
+ return [`${label}: ${scan.filesScanned} files were walked and none had any content.`];
2877
+ }
2878
+
2879
+ for (const [file, n] of Object.entries(scan.counts).sort()) {
2880
+ const allowed = banked[file] ?? 0;
2881
+ if (n > allowed) {
2882
+ out.push(
2883
+ `${label}: ${file} has ${n} direct config access site(s), ${allowed} allowed. ` +
2884
+ `Only ${CONFIG_LOADER} may read the config (ADR-002 D1). Use ` +
2885
+ `loadRungateConfig / tryLoadRungateConfig / resolveConfig.`,
2886
+ );
2887
+ } else if (n < allowed) {
2888
+ out.push(
2889
+ `${label}: ${file} is banked at ${allowed} but only ${n} remain — lower the ` +
2890
+ `number in .claude/config-access-ratchet.json in the same commit that earned it.`,
2891
+ );
2892
+ }
2893
+ }
2894
+ for (const [file, allowed] of Object.entries(banked).sort()) {
2895
+ if (allowed > 0 && !(file in scan.counts)) {
2896
+ out.push(
2897
+ `${label}: ${file} is banked at ${allowed} but has no violations left — ` +
2898
+ `remove its entry from .claude/config-access-ratchet.json.`,
2899
+ );
2900
+ }
2901
+ }
2902
+ return out;
2903
+ }
2904
+
2905
+ /**
2906
+ * CHECK-1 — direct config access in TypeScript sources (ADR-002 D4).
2907
+ *
2908
+ * FAILS; does not warn. `DEPTH-1` and `ABSENCE-1` only `console.warn`, and
2909
+ * warnings are how 89 sites accumulated with the policy written down.
2910
+ */
2911
+ export function runConfigAccessValidation(root: string) {
2912
+ describe("Config access (ADR-002 D1)", () => {
2913
+ test("CONFIG-1: only the loader reads the rungate config", () => {
2914
+ const scan = scanConfigAccess(root);
2915
+ const violations = configAccessViolations(
2916
+ scan,
2917
+ readConfigAccessRatchet(root, "sources"),
2918
+ "CONFIG-1",
2919
+ );
2920
+ for (const v of violations) {
2921
+ addFinding({
2922
+ ruleId: "CONFIG-1",
2923
+ severity: "FAIL",
2924
+ file: v.split(": ")[1]?.split(" ")[0] || "",
2925
+ message: v,
2926
+ fixCommand: "Route the read through lib/config-loader.ts",
2927
+ });
2928
+ }
2929
+ expect(violations, violations.join("\n")).toEqual([]);
2930
+ });
2931
+ });
2932
+ }
2933
+
2934
+ /**
2935
+ * CHECK-2 — config access inside workflow prompt text (ADR-002 D4).
2936
+ *
2937
+ * The check ADR-001 did not have, and the reason its single check would have
2938
+ * been insufficient: `ship.js:1637` reaches the config from inside a prompt.
2939
+ * Allowlist is empty — no workflow has any business reading it directly.
2940
+ */
2941
+ export function runPromptConfigAccessValidation(root: string) {
2942
+ describe("Config access in workflows (ADR-002 D4)", () => {
2943
+ test("CONFIG-2: no workflow reaches the rungate config, prompts included", () => {
2944
+ const scan = scanPromptConfigAccess(root);
2945
+ // A project with no workflows/ directory is not in violation; the
2946
+ // empty-scan refusal above is for a scan that should have found files.
2947
+ const violations = configAccessViolations(
2948
+ scan,
2949
+ readConfigAccessRatchet(root, "workflows"),
2950
+ "CONFIG-2",
2951
+ scan.filesScanned > 0,
2952
+ );
2953
+ for (const v of violations) {
2954
+ addFinding({
2955
+ ruleId: "CONFIG-2",
2956
+ severity: "FAIL",
2957
+ file: v.split(": ")[1]?.split(" ")[0] || "",
2958
+ message: v,
2959
+ fixCommand: "Point the prompt at the resolved-config artefact instead",
2960
+ });
2961
+ }
2962
+ expect(violations, violations.join("\n")).toEqual([]);
2963
+ });
2964
+ });
2965
+ }
2966
+
943
2967
  export function runAbsenceValidation(root: string) {
944
2968
  describe("Absence validation", () => {
945
2969
  test("ABSENCE-1: anti-criteria use absence verification", () => {
946
2970
  const specsDir = join(root, "specs");
947
2971
  if (!existsSync(specsDir)) return;
948
- for (const f of readdirSync(specsDir).filter(f => f.endsWith(".md"))) {
2972
+ for (const f of collectSpecFiles(specsDir)) { // #225 — subdirectories too
949
2973
  const content = readFileSync(join(specsDir, f), "utf-8");
950
2974
  const antiCriteria = content.match(/^- \[ \] SC-A\d+:.+$/gm) || [];
951
2975
  for (const ac of antiCriteria) {