rungate 0.2.0 → 0.3.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 (282) 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/canary.ts +117 -0
  11. package/lib/check-registry.ts +226 -0
  12. package/lib/ci-checkout.ts +400 -0
  13. package/lib/cli-commands.ts +137 -0
  14. package/lib/compliance-backfill.ts +220 -0
  15. package/lib/compliance-report.ts +504 -0
  16. package/lib/compliance.ts +361 -0
  17. package/lib/config-loader.ts +255 -0
  18. package/lib/conformity.ts +1818 -131
  19. package/lib/container-provenance.ts +230 -0
  20. package/lib/create-brief.ts +150 -0
  21. package/lib/create-sc.ts +272 -0
  22. package/lib/deep-merge.ts +69 -0
  23. package/lib/dev-liveness.ts +214 -0
  24. package/lib/directive-extractor.ts +210 -0
  25. package/lib/distribution-standing.ts +113 -0
  26. package/lib/doc-hygiene.ts +238 -0
  27. package/lib/eval-criteria.ts +6 -0
  28. package/lib/evidence-portability.ts +123 -0
  29. package/lib/evidence-prevalidator.ts +390 -0
  30. package/lib/evidence-required.ts +150 -0
  31. package/lib/evidence-satisfiability.ts +288 -0
  32. package/lib/frontmatter.ts +163 -0
  33. package/lib/gap-scanner.ts +348 -0
  34. package/lib/gate-enforcement.ts +366 -0
  35. package/lib/generators/agent-briefs.ts +136 -0
  36. package/lib/generators/agents-md.ts +506 -0
  37. package/lib/generators/code-map.ts +60 -0
  38. package/lib/generators/types.ts +184 -0
  39. package/lib/git-ref-normalizer.ts +107 -0
  40. package/lib/github.ts +539 -0
  41. package/lib/harness-identity.ts +63 -0
  42. package/lib/hill-climb.ts +164 -0
  43. package/lib/instruction-effectiveness.ts +131 -0
  44. package/lib/issue-closure-audit.ts +225 -0
  45. package/lib/issue-create-override.ts +343 -0
  46. package/lib/js-top-level-code.ts +250 -0
  47. package/lib/liveness-contradiction.ts +149 -0
  48. package/lib/organize.ts +505 -0
  49. package/lib/paths.ts +197 -6
  50. package/lib/post-fix-verify.ts +157 -0
  51. package/lib/prior-branch.ts +489 -0
  52. package/lib/project-state-shape.ts +166 -0
  53. package/lib/promote-outputs.ts +156 -0
  54. package/lib/prove-label-gate.ts +35 -0
  55. package/lib/reachability.ts +302 -0
  56. package/lib/release-preflight.ts +186 -0
  57. package/lib/rule-health-pipeline.ts +264 -0
  58. package/lib/rule-health-trend.ts +161 -0
  59. package/lib/rule-provenance.ts +149 -0
  60. package/lib/rule-registry.ts +128 -0
  61. package/lib/rungate-schema.ts +114 -4
  62. package/lib/sc-claim-forms.ts +179 -0
  63. package/lib/sc-cover.ts +150 -0
  64. package/lib/sc-guard.ts +157 -0
  65. package/lib/sc-ids.ts +344 -0
  66. package/lib/scaffold/defaults.ts +165 -0
  67. package/lib/scaffold/managed-workflow.ts +370 -0
  68. package/lib/scaffold/owned-files.ts +265 -0
  69. package/lib/scaffold/steps.ts +2680 -0
  70. package/lib/scanner.ts +701 -0
  71. package/lib/screenshot-upload.ts +73 -0
  72. package/lib/secret-patterns.ts +112 -0
  73. package/lib/security-verdict.ts +616 -0
  74. package/lib/signal-phrases.ts +1 -0
  75. package/lib/spec-change-conformity.ts +80 -0
  76. package/lib/spec-files.ts +62 -0
  77. package/lib/spec-registry.ts +133 -0
  78. package/lib/spec-updater.ts +96 -0
  79. package/lib/stale-cleanup.ts +224 -0
  80. package/lib/stale-issue-scanner.ts +36 -0
  81. package/lib/strip-js-comments.ts +269 -0
  82. package/lib/suite-measurement.ts +228 -0
  83. package/lib/task-completion-checks.ts +177 -0
  84. package/lib/test-suite-lock.ts +1136 -0
  85. package/lib/transcript-checker.ts +1140 -0
  86. package/lib/validators/spec-validators.ts +171 -0
  87. package/lib/verdict-capture.ts +73 -0
  88. package/lib/verified-push.ts +358 -0
  89. package/lib/workflow-security.ts +174 -0
  90. package/lib/worktree-cleanup.ts +250 -0
  91. package/lib/worktree-collect.ts +283 -0
  92. package/lib/worktree-isolation.ts +82 -0
  93. package/package.json +36 -3
  94. package/prompts/ac-adversary.md +14 -2
  95. package/prompts/aditi.md +5 -0
  96. package/prompts/blast-radius.md +5 -0
  97. package/prompts/container-verify.md +5 -0
  98. package/prompts/discovery.md +4 -0
  99. package/prompts/environment.md +5 -0
  100. package/prompts/evidence-hierarchy.md +5 -0
  101. package/prompts/evidence-validator.md +11 -0
  102. package/prompts/marcus.md +5 -0
  103. package/prompts/prevention.md +5 -0
  104. package/prompts/prove-reproducer.md +12 -0
  105. package/prompts/quinn-decision-tree.md +5 -0
  106. package/prompts/quinn-ui-brief.md +5 -0
  107. package/prompts/quinn.md +5 -0
  108. package/prompts/rca.md +5 -0
  109. package/prompts/read-before-write.md +4 -0
  110. package/prompts/regression.md +5 -0
  111. package/prompts/serena.md +5 -0
  112. package/scripts/audit-specs.ts +464 -0
  113. package/scripts/convert-spec.ts +293 -0
  114. package/scripts/create-sc.ts +92 -0
  115. package/scripts/create-spec.ts +166 -0
  116. package/scripts/extract-constraints.ts +4 -3
  117. package/scripts/generate-code-map.ts +1 -1
  118. package/scripts/scaffold-project.ts +138 -1426
  119. package/scripts/sync-spec-tests.ts +211 -126
  120. package/.claude/agents/aditi.md +0 -47
  121. package/.claude/agents/marcus.md +0 -50
  122. package/.claude/agents/quinn.md +0 -58
  123. package/.claude/agents/rook.md +0 -47
  124. package/.claude/agents/serena.md +0 -46
  125. package/.claude/rungate.json +0 -11
  126. package/.fallowrc.json +0 -28
  127. package/.github/copilot-instructions.md +0 -20
  128. package/.rungate/conformity-findings.json +0 -648
  129. package/AGENTS.md +0 -106
  130. package/CODE-MAP.md +0 -50
  131. package/HARNESS.md +0 -88
  132. package/bun.lock +0 -26
  133. package/bunfig.toml +0 -2
  134. package/config/brief-policies.json +0 -28
  135. package/config/ceremony-profiles.json +0 -212
  136. package/config/consumer-cascade-map.json +0 -24
  137. package/config/doc-cascade-map.json +0 -24
  138. package/config/eval.json +0 -84
  139. package/config/profiles/account-plan.yaml +0 -36
  140. package/config/profiles/campaign.yaml +0 -94
  141. package/config/prove-evidence.schema.json +0 -65
  142. package/config/spec-policies.json +0 -36
  143. package/config/workflow-schema.json +0 -281
  144. package/gates/SCHEMA-GUIDE.md +0 -121
  145. package/gates/ac-quality.test.ts +0 -106
  146. package/gates/adversarial.test.ts +0 -274
  147. package/gates/brief-assembler.test.ts +0 -429
  148. package/gates/brief-assembler.ts +0 -334
  149. package/gates/bunfig.toml +0 -2
  150. package/gates/chain.test.ts +0 -91
  151. package/gates/e2e-smoke.test.ts +0 -234
  152. package/gates/error-classifier.test.ts +0 -249
  153. package/gates/error-classifier.ts +0 -89
  154. package/gates/orchestrator.test.ts +0 -950
  155. package/gates/orchestrator.ts +0 -569
  156. package/gates/preload.ts +0 -77
  157. package/gates/prompts/ac-adversary.md +0 -20
  158. package/gates/prompts/evidence-validator.md +0 -22
  159. package/gates/prompts/prove-reproducer.md +0 -53
  160. package/gates/prove.test.ts +0 -164
  161. package/gates/run-gate.ts +0 -936
  162. package/gates/schema-parity.test.ts +0 -197
  163. package/gates/schema.ts +0 -362
  164. package/gates/self-heal.test.ts +0 -511
  165. package/gates/self-heal.ts +0 -121
  166. package/gates/ship-orchestrator.test.ts +0 -379
  167. package/gates/ship-orchestrator.ts +0 -363
  168. package/gates/test-fixtures/broken-no-environments.json +0 -60
  169. package/gates/test-fixtures/valid-standard.json +0 -54
  170. package/gates/test-utils.ts +0 -43
  171. package/gates/witness.ts +0 -220
  172. package/gates/workflow.test.ts +0 -1053
  173. package/hooks/AgentBriefGuard.hook.ts +0 -586
  174. package/hooks/AgentVerdictCapture.hook.ts +0 -134
  175. package/hooks/AutoVerifyGate.hook.ts +0 -76
  176. package/hooks/GateEnforcement.hook.ts +0 -273
  177. package/hooks/IssueCloseGuard.hook.ts +0 -116
  178. package/hooks/MergeGuard.hook.ts +0 -55
  179. package/hooks/StaleTTLCleanup.hook.ts +0 -133
  180. package/hooks/VerifyPhaseLock.hook.ts +0 -81
  181. package/hooks/WorkflowStateGuard.hook.ts +0 -37
  182. package/hooks/lib/agentDetection.ts +0 -70
  183. package/hooks/lib/findWorkflow.ts +0 -101
  184. package/hooks/lib/parseStdin.ts +0 -37
  185. package/hooks/lib/paths.ts +0 -111
  186. package/hooks/lib/utils.ts +0 -81
  187. package/reference/migration-manifest.json +0 -554
  188. package/reference/prompts/agent-aditi.md +0 -38
  189. package/reference/prompts/agent-marcus.md +0 -38
  190. package/reference/prompts/agent-quinn.md +0 -38
  191. package/reference/prompts/agent-rook.md +0 -37
  192. package/reference/prompts/agent-serena.md +0 -37
  193. package/reference/prompts/council-skill.md +0 -170
  194. package/reference/prompts/goal-skill.md +0 -235
  195. package/reference/prompts/prove-skill.md +0 -283
  196. package/reference/prompts/quinn-standard.md +0 -246
  197. package/reference/prompts/ship-convergence.md +0 -65
  198. package/reference/prompts/ship-escalation.md +0 -43
  199. package/reference/prompts/ship-iteration.md +0 -382
  200. package/reference/prompts/ship-pending-patches.md +0 -246
  201. package/reference/prompts/ship-reference.md +0 -250
  202. package/reference/prompts/ship-skill.md +0 -347
  203. package/reference/prompts/ship-templates.md +0 -215
  204. package/reference/scripts/batch-status.sh +0 -68
  205. package/reference/scripts/chain-compat-check.sh +0 -67
  206. package/reference/scripts/context-audit.sh +0 -314
  207. package/reference/scripts/dead-export-check.sh +0 -61
  208. package/reference/scripts/generate-qc-tables.sh +0 -92
  209. package/reference/scripts/harness-init.sh +0 -111
  210. package/reference/scripts/pai-054-baseline-check.sh +0 -40
  211. package/reference/scripts/prove-smoke-test.sh +0 -112
  212. package/reference/scripts/setup-keychain-salt.sh +0 -12
  213. package/reference/scripts/skill-optimizer-friday.sh +0 -88
  214. package/reference/scripts/skill-qc-test.sh +0 -351
  215. package/reference/scripts/skill-synthesize-tonight.sh +0 -66
  216. package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
  217. package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
  218. package/reference/specs/harness-v3-migration-plan.md +0 -188
  219. package/scripts/decision-reconcile.sh +0 -74
  220. package/scripts/decision-reconcile.ts +0 -152
  221. package/scripts/git-hooks/pre-commit +0 -76
  222. package/scripts/git-hooks/pre-push +0 -271
  223. package/scripts/harness-skill-check.sh +0 -52
  224. package/scripts/lib/gap-emit.sh +0 -65
  225. package/scripts/lib/jq-update.sh +0 -30
  226. package/scripts/lib/resolve-slug.sh +0 -30
  227. package/scripts/lib/verify-spec-compliance.sh +0 -102
  228. package/scripts/prove-backfill.sh +0 -87
  229. package/scripts/scaffold-rungate-config.ts +0 -91
  230. package/scripts/self-containment-check.sh +0 -109
  231. package/scripts/skill-qc-validator.sh +0 -402
  232. package/scripts/slug-resolver.sh +0 -14
  233. package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
  234. package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
  235. package/specs/HARNESS-GATES.md +0 -256
  236. package/specs/HARNESS-SKILL-CHAIN.md +0 -286
  237. package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
  238. package/specs/HARNESS-STANDARD.md +0 -488
  239. package/specs/SPEC-TEMPLATE.md +0 -53
  240. package/specs/bootstrap-data-flow.png +0 -0
  241. package/specs/harness-automation-matrix.md +0 -314
  242. package/specs/harness-automation-matrix.rules.json +0 -64
  243. package/test/anti.test.ts +0 -80
  244. package/test/contract-negative.test.ts +0 -86
  245. package/test/contract.test.ts +0 -158
  246. package/test/external-deps.test.ts +0 -48
  247. package/test/fixtures/golden-project/.env.example +0 -3
  248. package/test/fixtures/golden-project/Makefile +0 -7
  249. package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
  250. package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
  251. package/test/fixtures/golden-project/package.json +0 -10
  252. package/test/fixtures/golden-project/specs/api-spec.md +0 -20
  253. package/test/fixtures/golden-project/src/auth.ts +0 -8
  254. package/test/fixtures/golden-project/src/db.ts +0 -11
  255. package/test/fixtures/golden-project/src/index.ts +0 -19
  256. package/test/fixtures/golden-project/src/utils/format.ts +0 -3
  257. package/test/fixtures/golden-project/test/auth.test.ts +0 -15
  258. package/test/fixtures/golden-project/tsconfig.json +0 -12
  259. package/test/meta-sc-coverage.test.ts +0 -159
  260. package/test/phase-0.test.ts +0 -846
  261. package/test/phase-1.test.ts +0 -617
  262. package/test/phase-2.test.ts +0 -620
  263. package/test/phase-3.test.ts +0 -99
  264. package/test/scaffold-conformity.test.ts +0 -8
  265. package/test/schema-canary.test.ts +0 -51
  266. package/test/spec-compliance-auto.test.ts +0 -64
  267. package/test/spec-compliance.test.ts +0 -295
  268. package/test/spec-discovery.test.ts +0 -68
  269. package/test/spec-drift.test.ts +0 -5
  270. package/test/structure.test.ts +0 -165
  271. package/test/unit/agent-brief-guard-ship.test.ts +0 -293
  272. package/test/unit/extract-constraints.test.ts +0 -145
  273. package/test/unit/issue-close-guard.test.ts +0 -204
  274. package/test/unit/scaffold-project.test.ts +0 -417
  275. package/test/unit/skill-cooccurrence.test.ts +0 -177
  276. package/test/unit/skill-sequence-logger.test.ts +0 -244
  277. package/test/unit/workflow-state-guard.test.ts +0 -95
  278. package/workflows/batch-ship.js +0 -295
  279. package/workflows/council.js +0 -481
  280. package/workflows/prove.js +0 -560
  281. package/workflows/ship.js +0 -789
  282. package/workflows/verify.js +0 -236
@@ -0,0 +1,464 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * audit-specs — Scan spec files, classify SCs, optionally fix unmatched ones.
4
+ *
5
+ * Usage:
6
+ * bun scripts/audit-specs.ts . # audit mode
7
+ * bun scripts/audit-specs.ts . --fix # fix mode (rewrite in-place)
8
+ *
9
+ * Thin CLI consumer — core logic exported for testing.
10
+ */
11
+ import { readFileSync, writeFileSync, readdirSync, existsSync } from "fs";
12
+ import { join, dirname } from "path";
13
+ import { fileURLToPath } from "url";
14
+ import {
15
+ parseFrontmatter,
16
+ matchPattern,
17
+ isBehavioralSC,
18
+ type ParsedSC,
19
+ } from "../lib/conformity";
20
+
21
+ // ── Types ─────────────────────────────────────────────────────
22
+
23
+ export interface SpecAuditResult {
24
+ specFile: string;
25
+ total: number;
26
+ matched: number;
27
+ unmatched: number;
28
+ behavioral: number;
29
+ compliance: "strict" | "permissive";
30
+ matchedSCs: SCClassification[];
31
+ unmatchedSCs: SCClassification[];
32
+ behavioralSCs: SCClassification[];
33
+ }
34
+
35
+ export interface SCClassification {
36
+ id: string;
37
+ statement: string;
38
+ category: "matched" | "unmatched" | "behavioral";
39
+ }
40
+
41
+ export interface RewriteEntry {
42
+ scId: string;
43
+ specFile: string;
44
+ before: string;
45
+ after: string;
46
+ patternUsed: string;
47
+ ambiguous: boolean;
48
+ }
49
+
50
+ export interface AuditResult {
51
+ specs: SpecAuditResult[];
52
+ totalSCs: number;
53
+ totalMatched: number;
54
+ totalUnmatched: number;
55
+ totalBehavioral: number;
56
+ strictUnmatched: number;
57
+ rewrites?: RewriteEntry[];
58
+ }
59
+
60
+ // ── Registry loading ──────────────────────────────────────────
61
+
62
+ interface RegistryEntry {
63
+ name: string;
64
+ syntax: string;
65
+ regex: string;
66
+ example: string;
67
+ notes: string;
68
+ }
69
+
70
+ let _registryCache: RegistryEntry[] | null = null;
71
+
72
+ function loadRegistry(): RegistryEntry[] {
73
+ if (_registryCache) return _registryCache;
74
+ const configPath = join(
75
+ dirname(fileURLToPath(import.meta.url)),
76
+ "..",
77
+ "config",
78
+ "matcher-registry.json"
79
+ );
80
+ _registryCache = JSON.parse(readFileSync(configPath, "utf-8"));
81
+ return _registryCache!;
82
+ }
83
+
84
+ // ── SC extraction ─────────────────────────────────────────────
85
+
86
+ function extractSCs(content: string, specFile: string): ParsedSC[] {
87
+ const scs: ParsedSC[] = [];
88
+ const pattern = /^- \[ \] (SC-\w+):\s*(.+)$/gm;
89
+ let match;
90
+ while ((match = pattern.exec(content)) !== null) {
91
+ scs.push({ id: match[1], statement: match[2].trim(), specFile });
92
+ }
93
+ return scs;
94
+ }
95
+
96
+ // ── Closest pattern matching for rewrites ─────────────────────
97
+
98
+ /**
99
+ * Score how well an SC statement matches a registry pattern by
100
+ * looking for keyword overlaps. Returns the best pattern name and
101
+ * a generated rewrite, or null if nothing is close enough.
102
+ */
103
+ function findClosestPattern(
104
+ statement: string
105
+ ): { patternName: string; rewrite: string; ambiguous: boolean } | null {
106
+ const registry = loadRegistry();
107
+ const lower = statement.toLowerCase();
108
+
109
+ // Heuristic keyword rules per pattern — ordered by specificity
110
+ const heuristics: Array<{
111
+ pattern: string;
112
+ keywords: string[];
113
+ extractor: (stmt: string) => string | null;
114
+ }> = [
115
+ {
116
+ pattern: "pointer-exists",
117
+ keywords: ["pointer", "reference to", "contains reference"],
118
+ extractor: (s) => {
119
+ const m = s.match(/(?:file\s+)?(\S+\.?\w+)\s+(?:contains?|has|with)\s+(?:pointer|reference)\s+to\s+(\S+)/i);
120
+ return m ? `${m[1]} exists with pointer to ${m[2]}` : null;
121
+ },
122
+ },
123
+ {
124
+ pattern: "content-contains",
125
+ keywords: ["contains [", "includes ["],
126
+ extractor: (s) => {
127
+ const m = s.match(/(\S+)\s+(?:contains?|includes?)\s+\[([^\]]+)\]/i);
128
+ return m ? `${m[1]} contains [${m[2]}]` : null;
129
+ },
130
+ },
131
+ {
132
+ pattern: "content-not-contains",
133
+ keywords: ["not contain", "must not have", "has no ["],
134
+ extractor: (s) => {
135
+ const m = s.match(/(\S+)\s+(?:must\s+not\s+contain|has\s+no)\s+\[([^\]]+)\]/i);
136
+ return m ? `${m[1]} must NOT contain [${m[2]}]` : null;
137
+ },
138
+ },
139
+ {
140
+ pattern: "dir-exists",
141
+ keywords: ["directory"],
142
+ extractor: (s) => {
143
+ const m = s.match(/(?:the\s+)?(?:directory\s+)?(\S+?)\/?\s+(?:directory\s+)?(?:should\s+)?(?:be\s+present|exists?|is\s+present|must\s+exist)/i);
144
+ if (m) return `${m[1].replace(/\/$/, "")}/ directory exists`;
145
+ const m2 = s.match(/(?:directory|dir|folder)\s+(\S+?)\/?\s/i);
146
+ if (m2) return `${m2[1].replace(/\/$/, "")}/ directory exists`;
147
+ return null;
148
+ },
149
+ },
150
+ {
151
+ pattern: "file-exists",
152
+ keywords: ["exist", "file", "present", "must be"],
153
+ extractor: (s) => {
154
+ // Match "file X exists" or "X should exist" or "X must exist" patterns
155
+ const m = s.match(
156
+ /(?:the\s+)?(?:file\s+)?(\S+\.\w+)\s+(?:should\s+|must\s+)?(?:exist|be\s+present)/i
157
+ );
158
+ if (m) return `${m[1]} exists`;
159
+ // Match "exists" at end
160
+ const m2 = s.match(/(\S+\.\w+)\s+exists/i);
161
+ if (m2) return `${m2[1]} exists`;
162
+ return null;
163
+ },
164
+ },
165
+ {
166
+ pattern: "section-exists",
167
+ keywords: ["section", "heading"],
168
+ extractor: (s) => {
169
+ const m = s.match(/(\S+)\s+has\s+(?:a\s+)?section\s+(?:called\s+|named\s+)?\[([^\]]+)\]/i);
170
+ return m ? `${m[1]} has section [${m[2]}]` : null;
171
+ },
172
+ },
173
+ {
174
+ pattern: "count-threshold",
175
+ keywords: ["under", "at most", "lines", "words"],
176
+ extractor: (s) => {
177
+ const m = s.match(/(\S+)\s+(?:is\s+under|at\s+most)\s+\[?(\d+)\]?\s+(lines?|words?)/i);
178
+ return m ? `${m[1]} is under [${m[2]}] ${m[3]}` : null;
179
+ },
180
+ },
181
+ {
182
+ pattern: "json-field-equals",
183
+ keywords: ["field equals"],
184
+ extractor: (s) => {
185
+ const m = s.match(/(\S+)\s+(\S+)\s+field\s+equals\s+\[([^\]]+)\]/i);
186
+ return m ? `${m[1]} ${m[2]} field equals [${m[3]}]` : null;
187
+ },
188
+ },
189
+ {
190
+ pattern: "json-has-field",
191
+ keywords: ["has field"],
192
+ extractor: (s) => {
193
+ const m = s.match(/(\S+)\s+has\s+field\s+(\S+)/i);
194
+ return m ? `${m[1]} has field ${m[2]}` : null;
195
+ },
196
+ },
197
+ {
198
+ pattern: "frontmatter-field",
199
+ keywords: ["frontmatter"],
200
+ extractor: (s) => {
201
+ const m = s.match(/(\S+)\s+frontmatter\s+has\s+(\S+)(?:\s*=\s*(.+))?/i);
202
+ return m
203
+ ? m[3]
204
+ ? `${m[1]} frontmatter has ${m[2]} = ${m[3]}`
205
+ : `${m[1]} frontmatter has ${m[2]}`
206
+ : null;
207
+ },
208
+ },
209
+ {
210
+ pattern: "root-clean",
211
+ keywords: ["root is clean", "clean root"],
212
+ extractor: () => "root is clean",
213
+ },
214
+ {
215
+ pattern: "paths-resolve",
216
+ keywords: ["paths resolve", "links resolve"],
217
+ extractor: (s) => {
218
+ const m = s.match(/paths?\s+(?:referenced\s+)?in\s+(\S+)\s+resolve/i);
219
+ return m ? `all paths referenced in ${m[1]} resolve` : null;
220
+ },
221
+ },
222
+ {
223
+ pattern: "all-specs-frontmatter",
224
+ keywords: ["all specs", "frontmatter"],
225
+ extractor: () => "all specs have frontmatter",
226
+ },
227
+ {
228
+ pattern: "canary",
229
+ keywords: ["canary"],
230
+ extractor: () => "canary test exists",
231
+ },
232
+ ];
233
+
234
+ // Try each heuristic — first one whose extractor succeeds wins
235
+ for (const h of heuristics) {
236
+ // Check if any keyword matches
237
+ const hasKeyword = h.keywords.some((k) => lower.includes(k));
238
+ if (!hasKeyword) continue;
239
+
240
+ const rewrite = h.extractor(statement);
241
+ if (rewrite) {
242
+ return { patternName: h.pattern, rewrite, ambiguous: false };
243
+ }
244
+ }
245
+
246
+ // If no heuristic matched, try a loose file-exists match
247
+ // Look for any filename-like token (word.ext) in the statement
248
+ const fileToken = statement.match(/\b(\S+\.\w{1,5})\b/);
249
+ if (fileToken) {
250
+ return {
251
+ patternName: "file-exists",
252
+ rewrite: `${fileToken[1]} exists`,
253
+ ambiguous: true,
254
+ };
255
+ }
256
+
257
+ // Truly unresolvable
258
+ return null;
259
+ }
260
+
261
+ // ── Core audit function ───────────────────────────────────────
262
+
263
+ export function auditSpecs(
264
+ root: string,
265
+ opts?: { fix?: boolean }
266
+ ): AuditResult {
267
+ const specsDir = join(root, "specs");
268
+ const specs: SpecAuditResult[] = [];
269
+ const rewrites: RewriteEntry[] = [];
270
+
271
+ if (!existsSync(specsDir)) {
272
+ return { specs, totalSCs: 0, totalMatched: 0, totalUnmatched: 0, totalBehavioral: 0, strictUnmatched: 0, rewrites };
273
+ }
274
+
275
+ const specFiles = readdirSync(specsDir).filter((f) => f.endsWith(".md"));
276
+
277
+ for (const specFile of specFiles) {
278
+ const filePath = join(specsDir, specFile);
279
+ const content = readFileSync(filePath, "utf-8");
280
+ const fm = parseFrontmatter(content);
281
+
282
+ // Skip non-testable specs
283
+ if (!fm || fm.testable !== "true") continue;
284
+
285
+ const compliance: "strict" | "permissive" =
286
+ fm.compliance === "permissive" ? "permissive" : "strict";
287
+
288
+ const scs = extractSCs(content, specFile);
289
+ const matchedSCs: SCClassification[] = [];
290
+ const unmatchedSCs: SCClassification[] = [];
291
+ const behavioralSCs: SCClassification[] = [];
292
+
293
+ for (const sc of scs) {
294
+ if (isBehavioralSC(sc)) {
295
+ behavioralSCs.push({ id: sc.id, statement: sc.statement, category: "behavioral" });
296
+ } else if (matchPattern(sc) !== null) {
297
+ matchedSCs.push({ id: sc.id, statement: sc.statement, category: "matched" });
298
+ } else {
299
+ unmatchedSCs.push({ id: sc.id, statement: sc.statement, category: "unmatched" });
300
+ }
301
+ }
302
+
303
+ specs.push({
304
+ specFile,
305
+ total: scs.length,
306
+ matched: matchedSCs.length,
307
+ unmatched: unmatchedSCs.length,
308
+ behavioral: behavioralSCs.length,
309
+ compliance,
310
+ matchedSCs,
311
+ unmatchedSCs,
312
+ behavioralSCs,
313
+ });
314
+
315
+ // ── Fix mode: rewrite unmatched SCs in-place ──────────────
316
+ if (opts?.fix && unmatchedSCs.length > 0) {
317
+ let modified = content;
318
+ let hasChanges = false;
319
+
320
+ for (const usc of unmatchedSCs) {
321
+ const closest = findClosestPattern(usc.statement);
322
+ if (!closest) {
323
+ // Can't rewrite — mark with REVIEW comment
324
+ const scLinePattern = new RegExp(
325
+ `^(- \\[ \\] ${usc.id}:\\s*)(.+)$`,
326
+ "m"
327
+ );
328
+ const scMatch = modified.match(scLinePattern);
329
+ if (scMatch) {
330
+ // `closest` is null inside this branch, so the rewrite arm of the
331
+ // old ternary was unreachable. Only the REVIEW marker can apply.
332
+ const replacement = `${scMatch[0]}\n<!-- REVIEW: original — ${usc.statement} -->`;
333
+ modified = modified.replace(scLinePattern, replacement);
334
+ hasChanges = true;
335
+ rewrites.push({
336
+ scId: usc.id,
337
+ specFile,
338
+ before: usc.statement,
339
+ after: usc.statement, // unchanged
340
+ patternUsed: "none",
341
+ ambiguous: true,
342
+ });
343
+ }
344
+ continue;
345
+ }
346
+
347
+ const scLinePattern = new RegExp(
348
+ `^(- \\[ \\] ${usc.id}:\\s*)(.+)$`,
349
+ "m"
350
+ );
351
+ const scMatch = modified.match(scLinePattern);
352
+ if (scMatch) {
353
+ let replacement = `${scMatch[1]}${closest.rewrite}`;
354
+ if (closest.ambiguous) {
355
+ replacement += `\n<!-- REVIEW: original — ${usc.statement} -->`;
356
+ }
357
+ modified = modified.replace(scLinePattern, replacement);
358
+ hasChanges = true;
359
+ rewrites.push({
360
+ scId: usc.id,
361
+ specFile,
362
+ before: usc.statement,
363
+ after: closest.rewrite,
364
+ patternUsed: closest.patternName,
365
+ ambiguous: closest.ambiguous,
366
+ });
367
+ }
368
+ }
369
+
370
+ if (hasChanges) {
371
+ writeFileSync(filePath, modified);
372
+ }
373
+ }
374
+ }
375
+
376
+ const totalSCs = specs.reduce((sum, s) => sum + s.total, 0);
377
+ const totalMatched = specs.reduce((sum, s) => sum + s.matched, 0);
378
+ const totalUnmatched = specs.reduce((sum, s) => sum + s.unmatched, 0);
379
+ const totalBehavioral = specs.reduce((sum, s) => sum + s.behavioral, 0);
380
+ const strictUnmatched = specs
381
+ .filter((s) => s.compliance === "strict")
382
+ .reduce((sum, s) => sum + s.unmatched, 0);
383
+
384
+ return { specs, totalSCs, totalMatched, totalUnmatched, totalBehavioral, strictUnmatched, rewrites };
385
+ }
386
+
387
+ // ── Report formatting ─────────────────────────────────────────
388
+
389
+ export function formatReport(result: AuditResult): string {
390
+ const lines: string[] = [];
391
+ lines.push("audit-specs report");
392
+ lines.push("=".repeat(60));
393
+ lines.push("");
394
+
395
+ // Per-spec table
396
+ lines.push(
397
+ `${"Spec".padEnd(45)} ${"total".padEnd(6)} ${"matched".padEnd(8)} ${"unmatched".padEnd(10)} ${"behavioral".padEnd(10)}`
398
+ );
399
+ lines.push("-".repeat(80));
400
+
401
+ for (const spec of result.specs) {
402
+ lines.push(
403
+ `${spec.specFile.padEnd(45)} ${String(spec.total).padEnd(6)} ${String(spec.matched).padEnd(8)} ${String(spec.unmatched).padEnd(10)} ${String(spec.behavioral).padEnd(10)}`
404
+ );
405
+ }
406
+
407
+ lines.push("-".repeat(80));
408
+ lines.push(
409
+ `${"TOTAL".padEnd(45)} ${String(result.totalSCs).padEnd(6)} ${String(result.totalMatched).padEnd(8)} ${String(result.totalUnmatched).padEnd(10)} ${String(result.totalBehavioral).padEnd(10)}`
410
+ );
411
+ lines.push("");
412
+
413
+ return lines.join("\n");
414
+ }
415
+
416
+ // ── Diff summary formatting ───────────────────────────────────
417
+
418
+ export function formatDiffSummary(result: AuditResult): string {
419
+ const lines: string[] = [];
420
+
421
+ if (!result.rewrites || result.rewrites.length === 0) {
422
+ lines.push("No rewrites applied.");
423
+ return lines.join("\n");
424
+ }
425
+
426
+ lines.push("Rewrite diff summary");
427
+ lines.push("=".repeat(60));
428
+ lines.push("");
429
+
430
+ for (const r of result.rewrites) {
431
+ lines.push(`${r.scId} (${r.specFile}):`);
432
+ lines.push(` before: ${r.before}`);
433
+ lines.push(` after: ${r.after}`);
434
+ lines.push(` pattern: ${r.patternUsed}${r.ambiguous ? " (AMBIGUOUS — needs review)" : ""}`);
435
+ lines.push("");
436
+ }
437
+
438
+ return lines.join("\n");
439
+ }
440
+
441
+ // ── CLI entry point ───────────────────────────────────────────
442
+
443
+ if (import.meta.main) {
444
+ const args = process.argv.slice(2);
445
+ const root = args.find((a) => !a.startsWith("-")) || ".";
446
+ const fix = args.includes("--fix");
447
+
448
+ if (!existsSync(root)) {
449
+ console.error(`ERROR: Path does not exist: ${root}`);
450
+ process.exit(1);
451
+ }
452
+
453
+ const result = auditSpecs(root, { fix });
454
+ console.log(formatReport(result));
455
+
456
+ if (fix && result.rewrites && result.rewrites.length > 0) {
457
+ console.log(formatDiffSummary(result));
458
+ }
459
+
460
+ // Exit with non-zero if there are unmatched SCs in strict specs
461
+ if (result.strictUnmatched > 0 && !fix) {
462
+ process.exit(1);
463
+ }
464
+ }