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
@@ -13,15 +13,79 @@
13
13
  * Lines containing `Quinn` + action verb → assert Quinn integration
14
14
  */
15
15
 
16
- import { readFileSync, writeFileSync, readdirSync } from "fs";
16
+ import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
17
+ import { collectSpecFiles } from "../lib/spec-files";
17
18
  import { resolve, join } from "path";
19
+ import { harnessRootFor } from "../lib/paths";
18
20
 
19
- const HOME = process.env.HOME || "";
20
- const HARNESS_ROOT = process.env.HARNESS_ROOT || join(HOME, ".claude");
21
- const SPECS_DIR = resolve(HARNESS_ROOT, "PAI/Specs");
22
- const SHIP_PATH = resolve(HARNESS_ROOT, "workflows/ship.js");
23
- const PROVE_PATH = resolve(HARNESS_ROOT, "workflows/prove.js");
24
- const OUTPUT_PATH = resolve(HARNESS_ROOT, "test/spec-compliance-auto.test.ts");
21
+ /**
22
+ * Where this script reads specs and writes tests (#141).
23
+ *
24
+ * It used to compute these itself:
25
+ *
26
+ * const HARNESS_ROOT = process.env.HARNESS_ROOT || join(HOME, ".claude");
27
+ * const SPECS_DIR = resolve(HARNESS_ROOT, "PAI/Specs");
28
+ * const OUTPUT_PATH = resolve(HARNESS_ROOT, "test/spec-compliance-auto.test.ts");
29
+ *
30
+ * `HARNESS_ROOT` is never exported — no profile, CI file, hook or skill sets
31
+ * it; it is only ever passed as a workflow argument. So the default applied,
32
+ * and the generator read `~/.claude/PAI/Specs` and wrote
33
+ * `~/.claude/test/spec-compliance-auto.test.ts`, while `lib/paths.ts`
34
+ * `harnessRoot()` resolved to this checkout. Two functions, one concept, two
35
+ * answers — and both directories exist, so nothing ever errored.
36
+ *
37
+ * The cost: `specs/` holds 30 spec files and this generator had never read
38
+ * one of them. "SCs without tests are wishes" is the project's own rule, and
39
+ * the mechanism meant to enforce it wrote its output where the suite does not
40
+ * look and reported success. `gates/gate-executor.ts` runs it on every gate.
41
+ *
42
+ * Pure in `root` so the resolution is testable without a filesystem, which is
43
+ * the shape the issue asked for.
44
+ */
45
+ export interface SyncPaths {
46
+ specsDir: string;
47
+ shipPath: string;
48
+ provePath: string;
49
+ outputPath: string;
50
+ }
51
+
52
+ export function resolveSyncPaths(root: string): SyncPaths {
53
+ return {
54
+ specsDir: resolve(root, "specs"),
55
+ shipPath: resolve(root, "workflows/ship.js"),
56
+ provePath: resolve(root, "workflows/prove.js"),
57
+ outputPath: resolve(root, "test/spec-compliance-auto.test.ts"),
58
+ };
59
+ }
60
+
61
+ /**
62
+ * The tree this script WRITES to, stated rather than inherited (#190).
63
+ *
64
+ * It was `const ROOT = harnessRoot()` at module scope, which made the
65
+ * destination of a write depend on two things the caller never said: the
66
+ * `HARNESS_ROOT` environment variable, and which checkout happened to load
67
+ * `lib/paths.ts`. `gates/gate-executor.ts` runs this on every scope gate, so a
68
+ * gate whose root was resolved elsewhere regenerated a DIFFERENT checkout's
69
+ * `test/spec-compliance-auto.test.ts` and left its own stale — silently, since
70
+ * both files exist and both are real.
71
+ *
72
+ * Resolution order:
73
+ *
74
+ * 1. `argv[2]`, when a caller names the tree it means.
75
+ * 2. Otherwise the checkout this script file lives in.
76
+ *
77
+ * `bun <checkout>/scripts/sync-spec-tests.ts` therefore writes into
78
+ * `<checkout>`, whatever the cwd and whatever the environment says. Deliberately
79
+ * NOT `harnessRoot()`: a writer that can be aimed by an env var is how #141
80
+ * happened, and `HARNESS_ROOT` is set by the ship workflow for reasons that
81
+ * have nothing to do with where generated tests belong.
82
+ */
83
+ export function syncRoot(argv: string[] = process.argv): string {
84
+ const arg = argv[2];
85
+ // `join(dir, "..")` because this file sits in `scripts/`; `harnessRootFor`
86
+ // resolves and validates the path it is handed, it does not search upward.
87
+ return arg ? harnessRootFor(arg) : harnessRootFor(join(import.meta.dir, ".."));
88
+ }
25
89
 
26
90
  function parseTestable(content: string): boolean | null {
27
91
  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
@@ -31,13 +95,36 @@ function parseTestable(content: string): boolean | null {
31
95
  return testableMatch[1] === "true";
32
96
  }
33
97
 
34
- function discoverTestableSpecs(): { path: string; name: string }[] {
35
- const files = readdirSync(SPECS_DIR).filter(f => f.endsWith(".md"));
98
+ /**
99
+ * Whether a spec makes claims about THIS harness's own workflows (#225).
100
+ *
101
+ * Every claim this script extracts is asserted against `workflows/ship.js` or
102
+ * `workflows/prove.js`, so it only means anything for a spec describing the
103
+ * harness. `specs/bootstrap-data-flow/template-architecture.md` describes what
104
+ * a SCAFFOLDED CONSUMER's files look like, and its `make dev-all` /
105
+ * `make test-rebuild` / `make prove-up` are examples of a consumer Makefile —
106
+ * turning them into "rungate's ship.js must contain this string" is a false
107
+ * assertion about a different project.
108
+ *
109
+ * This was always true; it only started firing when #225 made the collectors
110
+ * recursive and the consumer-facing specs became visible for the first time.
111
+ * The opt-out is frontmatter rather than a path rule so it stays explicit and
112
+ * reviewable, and so making a spec visible to the conformity engine and making
113
+ * it a source of harness claims remain two separate decisions.
114
+ */
115
+ function parseWorkflowClaims(content: string): boolean {
116
+ const fm = content.match(/^---\n([\s\S]*?)\n---/);
117
+ if (!fm) return true;
118
+ return !/^workflow-claims:\s*false\s*$/m.test(fm[1]);
119
+ }
120
+
121
+ function discoverTestableSpecs(specsDir: string): { path: string; name: string }[] {
122
+ const files = collectSpecFiles(specsDir); // #225 — subdirectories too
36
123
  const testable: { path: string; name: string }[] = [];
37
124
  for (const f of files) {
38
- const fullPath = join(SPECS_DIR, f);
125
+ const fullPath = join(specsDir, f);
39
126
  const content = readFileSync(fullPath, "utf-8");
40
- if (parseTestable(content) === true) {
127
+ if (parseTestable(content) === true && parseWorkflowClaims(content)) {
41
128
  testable.push({ path: fullPath, name: f });
42
129
  }
43
130
  }
@@ -54,116 +141,93 @@ interface Claim {
54
141
  context: string;
55
142
  }
56
143
 
57
- function extractClaims(spec: string): Claim[] {
58
- const claims: Claim[] = [];
59
- const lines = spec.split("\n");
60
- let claimCounter = 0;
61
-
62
- for (let i = 0; i < lines.length; i++) {
63
- const line = lines[i];
64
- const lineNum = i + 1;
65
-
66
- // Make commands: make test-up, make prove-up, make test-rebuild, make rebuild
67
- const makeMatch = line.match(/`(make\s+[\w-]+)`/);
68
- if (makeMatch) {
69
- const cmd = makeMatch[1];
70
- // Determine target based on section context and command name
71
- const isProveSection = lines.slice(Math.max(0, i - 30), i).some(l => /Step 4.*PROVE|PROVE.*post-merge|Layer 3.*Prove/i.test(l));
72
- const isReleaseSection = lines.slice(Math.max(0, i - 20), i).some(l => /Step 5.*RELEASE|RELEASE/i.test(l));
73
- // Skip release commands — they belong to release skill, not ship/prove
74
- if (isReleaseSection) continue;
75
- const target = isProveSection || cmd.includes("prove") ? "prove" : "ship";
76
- // For ship, test-up may have been upgraded to test-rebuild — check for either
77
- const searchTerm = cmd.replace("make ", "");
78
- claims.push({
79
- id: `AUTO-MAKE-${++claimCounter}`,
80
- spec_line: lineNum,
81
- claim: `Spec requires make ${searchTerm}`,
82
- target,
83
- assertion_type: "contains",
84
- search_term: searchTerm,
85
- context: line.trim().slice(0, 100),
86
- });
87
- }
88
-
89
- // GATE markers
90
- if (line.includes("**GATE:") || line.includes("**Gate:**")) {
91
- const gateText = line.replace(/\*\*/g, "").replace("GATE:", "").replace("Gate:", "").trim();
92
- const target = line.toLowerCase().includes("prove") ? "prove" : "ship";
93
- claims.push({
94
- id: `AUTO-GATE-${++claimCounter}`,
95
- spec_line: lineNum,
96
- claim: `Gate: ${gateText.slice(0, 80)}`,
97
- target,
98
- assertion_type: "contains",
99
- search_term: gateText.includes("Quinn") ? "quinn" : gateText.includes("Ship gate") ? "ship" : "gate",
100
- context: line.trim().slice(0, 100),
101
- });
102
- }
103
-
104
- // Port references in context of specific tools
105
- const portMatch = line.match(/:(\d{4})\b/);
106
- if (portMatch) {
107
- const port = portMatch[1];
108
- if (["7776", "7777", "7778", "5173"].includes(port)) {
109
- // Determine which file should reference this port
110
- const isProveSection = lines.slice(Math.max(0, i - 20), i).some(l => /Step 4.*PROVE|PROVE.*post-merge/i.test(l));
111
- const target = isProveSection ? "prove" : "ship";
112
- claims.push({
113
- id: `AUTO-PORT-${++claimCounter}`,
114
- spec_line: lineNum,
115
- claim: `Port ${port} referenced in ${isProveSection ? "PROVE" : "SHIP"} context`,
116
- target,
117
- assertion_type: "port",
118
- search_term: port,
119
- context: line.trim().slice(0, 100),
120
- });
121
- }
122
- }
123
-
124
- // Quinn + action verb patterns
125
- const quinnMatch = line.match(/Quinn\s+(validates|captures|tests|navigates|compares|verifies)/i);
126
- if (quinnMatch) {
127
- const action = quinnMatch[1].toLowerCase();
128
- const isProveSection = lines.slice(Math.max(0, i - 20), i).some(l => /Step 4.*PROVE|PROVE.*post-merge/i.test(l));
129
- const target = isProveSection ? "prove" : "ship";
130
- claims.push({
131
- id: `AUTO-QUINN-${++claimCounter}`,
132
- spec_line: lineNum,
133
- claim: `Quinn ${action} in ${isProveSection ? "PROVE" : "SHIP"}`,
134
- target,
135
- assertion_type: "contains",
136
- search_term: "quinn",
137
- context: line.trim().slice(0, 100),
138
- });
139
- }
140
- }
141
-
142
- // Deduplicate by search_term + target
143
- const seen = new Set<string>();
144
- return claims.filter(c => {
145
- const key = `${c.target}:${c.assertion_type}:${c.search_term}`;
146
- if (seen.has(key)) return false;
147
- seen.add(key);
148
- return true;
149
- });
144
+ /**
145
+ * #277/#343 — this emitted twelve assertions, every one of which was a bare
146
+ * substring presence check against a 4,000-line workflow file.
147
+ *
148
+ * Four claim shapes were extracted from spec prose — \`make x\`, \`**GATE:**\`,
149
+ * a port number, and "Quinn <verb>" — and each became
150
+ * \`expect(SHIP_JS.toLowerCase()).toContain(<search_term>)\` where the search
151
+ * term was a generic word lifted out of the sentence. Counted in ship.js:
152
+ *
153
+ * "gate" 196 occurrences
154
+ * "ship" 264
155
+ * "quinn" 94
156
+ * "rebuild" 17
157
+ * "x" 563 <- from the literal spec phrase \`make x\`
158
+ *
159
+ * None of them could fail. Not "unlikely to fail" — the terms are structural
160
+ * vocabulary of the file being searched, so the assertions were true before
161
+ * the spec sentence existed and would stay true if the behaviour were
162
+ * deleted. Twelve named checks, zero measurement, counted in the suite total
163
+ * and in every compliance report.
164
+ *
165
+ * Found because an SC line added in #343 — about REMOVING a hardcoded
166
+ * \`make rebuild\` — matched the \`make x\` shape and generated a thirteenth
167
+ * test asserting ship.js contains "rebuild". A spec sentence describing the
168
+ * deletion of a thing generated a test demanding its presence.
169
+ *
170
+ * Removed rather than weakened, which is what #315 did with
171
+ * \`evidence-target-valid\` for the same reason: a name in a report with
172
+ * nothing behind it is worse than an absence, because the absence is visible.
173
+ * Rebuilding spec-claim extraction with assertions that can fail is real
174
+ * work with a real design question behind it — what IS the checkable content
175
+ * of "Spec requires make rebuild"? — and it is not done by keeping these.
176
+ *
177
+ * \`test/spec-compliance-config.test.ts\` holds the hand-written checks that
178
+ * used to live in the generated file and are genuinely load-bearing.
179
+ */
180
+ function extractClaims(_spec: string): Claim[] {
181
+ return [];
150
182
  }
151
183
 
152
184
  function generateTest(claims: Claim[]): string {
185
+ // No claims means no file worth importing: the header alone would read
186
+ // `workflows/ship.js` at module scope to populate two constants nothing
187
+ // uses, so a missing workflow file would fail a suite that asserts nothing.
188
+ if (claims.length === 0) {
189
+ return [
190
+ `// AUTO-GENERATED by scripts/sync-spec-tests.ts — do not edit manually`,
191
+ `// Regenerate: bun scripts/sync-spec-tests.ts`,
192
+ ``,
193
+ `// No generated claims. extractClaims returns nothing on purpose — see the`,
194
+ `// docblock above it in scripts/sync-spec-tests.ts. The twelve assertions`,
195
+ `// this file used to hold were bare substring checks for words like "gate"`,
196
+ `// and "ship" against a file containing them 196 and 264 times.`,
197
+ `//`,
198
+ `// Hand-written spec-compliance checks live in`,
199
+ `// test/spec-compliance-config.test.ts and test/spec-compliance.test.ts.`,
200
+ ``,
201
+ ].join("\n");
202
+ }
203
+
153
204
  const shipClaims = claims.filter(c => c.target === "ship" || c.target === "both");
154
205
  const proveClaims = claims.filter(c => c.target === "prove" || c.target === "both");
155
206
 
156
207
  const lines: string[] = [
157
208
  `// AUTO-GENERATED by scripts/sync-spec-tests.ts — do not edit manually`,
158
209
  `// Regenerate: bun scripts/sync-spec-tests.ts`,
159
- `// Source: PAI/specs/HARNESS-SKILL-CHAIN.md`,
210
+ `// Source: specs/ (every spec with testable: true)`,
160
211
  `// Generated: ${new Date().toISOString().split("T")[0]}`,
161
212
  ``,
162
213
  `import { test, expect, describe } from "bun:test";`,
163
214
  `import { readFileSync } from "fs";`,
215
+ `import { join } from "path";`,
216
+ `import { harnessRootFor } from "../lib/paths";`,
164
217
  ``,
165
- `const SHIP_JS = readFileSync("${SHIP_PATH}", "utf-8");`,
166
- `const PROVE_JS = readFileSync("${PROVE_PATH}", "utf-8");`,
218
+ `// Resolved at run time, not baked in: an absolute path written by whoever`,
219
+ `// last ran the generator makes the file unrunnable anywhere else, CI`,
220
+ `// included.`,
221
+ `//`,
222
+ `// Resolved from THIS file's own location, not from the implicit`,
223
+ `// module-relative root (#190). These cases grade workflows/ship.js, and`,
224
+ `// the implicit root honours HARNESS_ROOT — so a run with it set read a`,
225
+ `// different checkout's ship.js than the one this file was generated`,
226
+ `// from. A generated test grading a tree it does not belong to reports`,
227
+ `// failures that exist in nobody's checkout.`,
228
+ `const HR = harnessRootFor(join(import.meta.dir, ".."));`,
229
+ `const SHIP_JS = readFileSync(join(HR, "workflows/ship.js"), "utf-8");`,
230
+ `const PROVE_JS = readFileSync(join(HR, "workflows/prove.js"), "utf-8");`,
167
231
  ``,
168
232
  ];
169
233
 
@@ -209,28 +273,49 @@ function generateTest(claims: Claim[]): string {
209
273
  return lines.join("\n") + "\n";
210
274
  }
211
275
 
212
- // Main — glob scan all testable specs
213
- const testableSpecs = discoverTestableSpecs();
214
- const allFiles = readdirSync(SPECS_DIR).filter(f => f.endsWith(".md"));
276
+ // Main — glob scan all testable specs.
277
+ //
278
+ // Behind `import.meta.main` so importing this module for its pure path
279
+ // helpers does not rewrite a test file as a side effect of the import. The
280
+ // test that covers resolveSyncPaths does exactly that import, and without
281
+ // this guard it regenerated the suite's own source mid-run.
282
+ export function main(root: string) {
283
+ const { specsDir: SPECS_DIR, outputPath: OUTPUT_PATH } = resolveSyncPaths(root);
284
+
285
+ // Fail loudly on a missing spec directory. The previous version could not:
286
+ // `~/.claude/PAI/Specs` happened to exist, so reading the wrong tree looked
287
+ // exactly like reading the right one.
288
+ if (!existsSync(SPECS_DIR)) {
289
+ console.error(
290
+ `sync-spec-tests: no spec directory at ${SPECS_DIR}\n` +
291
+ ` (harness root given as ${root} — pass the root as argv[2] if that is wrong)`,
292
+ );
293
+ process.exit(1);
294
+ }
215
295
 
216
- console.log(`Spec discovery: ${allFiles.length} specs scanned, ${testableSpecs.length} testable`);
296
+ const testableSpecs = discoverTestableSpecs(SPECS_DIR);
297
+ const allFiles = collectSpecFiles(SPECS_DIR); // #225 — subdirectories too
217
298
 
218
- let allClaims: Claim[] = [];
219
- for (const spec of testableSpecs) {
220
- const content = readFileSync(spec.path, "utf-8");
221
- const claims = extractClaims(content);
222
- allClaims = allClaims.concat(claims);
223
- console.log(` ${spec.name}: ${claims.length} claims`);
224
- }
299
+ console.log(`Spec discovery: ${allFiles.length} specs scanned, ${testableSpecs.length} testable`);
300
+
301
+ let allClaims: Claim[] = [];
302
+ for (const spec of testableSpecs) {
303
+ const content = readFileSync(spec.path, "utf-8");
304
+ const claims = extractClaims(content);
305
+ allClaims = allClaims.concat(claims);
306
+ console.log(` ${spec.name}: ${claims.length} claims`);
307
+ }
225
308
 
226
- const testContent = generateTest(allClaims);
227
- writeFileSync(OUTPUT_PATH, testContent);
309
+ writeFileSync(OUTPUT_PATH, generateTest(allClaims));
228
310
 
229
- console.log(`\nTotal: ${allClaims.length} claims extracted`);
230
- console.log(` ship.js: ${allClaims.filter(c => c.target === "ship").length}`);
231
- console.log(` prove.js: ${allClaims.filter(c => c.target === "prove").length}`);
232
- console.log(`Written to: ${OUTPUT_PATH}`);
311
+ console.log(`\nTotal: ${allClaims.length} claims extracted`);
312
+ console.log(` ship.js: ${allClaims.filter(c => c.target === "ship").length}`);
313
+ console.log(` prove.js: ${allClaims.filter(c => c.target === "prove").length}`);
314
+ console.log(`Written to: ${OUTPUT_PATH}`);
233
315
 
234
- for (const c of allClaims) {
235
- console.log(` ${c.id} [${c.target}] L${c.spec_line}: ${c.claim}`);
316
+ for (const c of allClaims) {
317
+ console.log(` ${c.id} [${c.target}] L${c.spec_line}: ${c.claim}`);
318
+ }
236
319
  }
320
+
321
+ if (import.meta.main) main(syncRoot());
@@ -1,47 +0,0 @@
1
- ---
2
- name: aditi
3
- description: UX/UI designer — component specs, visual review, accessibility
4
- tools: [Bash, Read]
5
- model: sonnet
6
- ---
7
-
8
- You are Aditi Sharma, UX/UI designer. You design component specs and review UI implementations.
9
-
10
- ## Project
11
-
12
- Implementation quality framework for PAI (Personal AI Infrastructure). Provides workflows (ship, prove, council), gates (scope, verify, ship), hooks (IssueCloseGuard, MergeGuard, AutoVerifyGate), specs, and tests. Built with Bun/TypeScript.
13
-
14
- - **Issues:** github.com/hornjason/pai-config (not this repo)
15
- - **Code:** github.com/hornjason/rungate
16
- ## Context (MANDATORY — read before designing)
17
-
18
- 1. **AGENTS.md** — project identity, critical rules, documentation routing
19
- 2. **CODE-MAP.md § Page → Component Map** — which components render on each page
20
- 3. **CODE-MAP.md § React Components** — full component inventory
21
- 4. Read any visual specs or mockups referenced in the brief
22
-
23
- ## What you do
24
-
25
- 1. Review proposed UI changes against design principles
26
- 2. Create component specs with layout, spacing, typography, color
27
- 3. Assess visual hierarchy and information density
28
- 4. Evaluate accessibility (contrast, focus order, screen reader labels)
29
-
30
- ## Design principles
31
-
32
- - shadcn/ui component library as the base
33
- - Consistent spacing scale (4px base)
34
- - Clear visual hierarchy — primary action obvious
35
- - Accessible: WCAG 2.1 AA minimum
36
-
37
- ## Report
38
-
39
- - APPROVED or REVISION_NEEDED with specific changes
40
- - Mockups as HTML when proposing new layouts
41
- - Annotated screenshots when reviewing existing UI
42
- - Specific CSS values, not vague directions
43
-
44
- ## Rules
45
-
46
- - Never modify source code directly — provide specs for Marcus
47
- - Never run builds or tests
@@ -1,50 +0,0 @@
1
- ---
2
- name: marcus
3
- description: Principal engineer — implements code changes with TDD, writes tests, commits
4
- tools: [Bash, Read, Write, Edit]
5
- model: opus
6
- ---
7
-
8
- You are Marcus Webb, principal engineer. You implement code changes, write tests, and commit.
9
-
10
- ## Project
11
-
12
- Implementation quality framework for PAI (Personal AI Infrastructure). Provides workflows (ship, prove, council), gates (scope, verify, ship), hooks (IssueCloseGuard, MergeGuard, AutoVerifyGate), specs, and tests. Built with Bun/TypeScript.
13
-
14
- - **Issues:** github.com/hornjason/pai-config (not this repo)
15
- - **Code:** github.com/hornjason/rungate
16
- ## Context (MANDATORY — read before coding)
17
-
18
- 1. **AGENTS.md** — project identity, critical rules, documentation routing
19
- 2. **CODE-MAP.md § Module Dependencies** — import chains for cascade impact analysis
20
- 3. **CODE-MAP.md § Code Health** — circular deps and unused files to avoid
21
-
22
- ## Source Directories
23
-
24
- - `lib/`
25
- - `gates/`
26
- - `hooks/`
27
- ## Before writing code
28
- 2. Read every file listed in the brief's **Files** section
29
- 3. Read the **Governing Spec** if one is cited
30
- 4. Run existing tests to establish baseline: `bun test`
31
-
32
- ## While coding
33
-
34
- - TDD: write the failing test first, then the implementation
35
- - Deep modules, thin consumers: shared logic in lib/, consumers call one function
36
- - No hardcoded values — use config or environment variables
37
- - All thresholds configurable
38
-
39
- ## Before reporting done
40
-
41
- 1. Run `bun test` — all tests pass
42
- 2. Run `bunx tsc --noEmit` — no type errors
43
- 3. Run `npx fallow audit` — no new dead code or circular deps introduced
44
- 4. Commit all changes referencing the issue number
45
- 5. Push branch with -u flag
46
-
47
- ## Rules
48
-
49
- - Never run `make rebuild` — only the DA does that
50
- - Dev server: `make dev-all` starts API (http://localhost:7778) and UI (http://localhost:5173)
@@ -1,58 +0,0 @@
1
- ---
2
- name: quinn
3
- description: QA engineer — tests as brand-new user, browser validation, UI regression
4
- doc-type: reference
5
- status: active
6
- owner: jason
7
- updated: 2026-09-18
8
- ---
9
-
10
- You are Quinn Torres, QA engineer. You test as a brand-new user who has never seen this app before.
11
-
12
- ## Project
13
-
14
- Implementation quality framework for PAI (Personal AI Infrastructure). Provides workflows (ship, prove, council), gates (scope, verify, ship), hooks (IssueCloseGuard, MergeGuard, AutoVerifyGate), specs, and tests. Built with Bun/TypeScript.
15
-
16
- - **Issues:** github.com/hornjason/pai-config (not this repo)
17
- - **Code:** github.com/hornjason/rungate
18
- ## Context (MANDATORY — read before testing)
19
-
20
- 1. **AGENTS.md** — project identity, critical rules, documentation routing
21
- 2. **CODE-MAP.md § Page → Component Map** — which components are on each page (your test targets)
22
- 3. **CODE-MAP.md § API Routes** — endpoint inventory for API-level checks
23
- 4. **node_modules/rungate/prompts/quinn-ui-brief.md** — structured UI testing methodology
24
-
25
- ## Environment
26
-
27
- - **Dev UI:** http://localhost:5173
28
- - **Dev API:** http://localhost:7778
29
- - **Viewport:** 1280x720 (set via browser_resize FIRST)
30
- - **Never test on port 7777** — that's the live container
31
-
32
-
33
-
34
- ## Pre-conditions (GATE — stop if any fail)
35
-
36
- 1. Set viewport: browser_resize(1280, 720)
37
- 2. Navigate to target URL
38
- 3. browser_snapshot() — verify page loaded (no error banners, data present)
39
- If pre-conditions fail → report FAIL immediately, do NOT proceed.
40
-
41
- ## Tools
42
-
43
- - browser_snapshot() for ALL assertions (text, fast, cheap)
44
- - browser_take_screenshot() ONLY for evidence after assertions pass
45
- - Never guess URLs — read .claude/rungate.json pages map
46
-
47
- ## Anti-checks (ALWAYS run)
48
-
49
- - No "undefined" or "null" rendered as visible text
50
- - No stuck loading spinners
51
- - No error banners or toast messages
52
- - Interactive elements respond to clicks
53
-
54
- ## Report
55
-
56
- - PASS/FAIL per AC with snapshot/screenshot evidence
57
- - Anti-check results
58
- - Any new findings flagged as blocking or non-blocking
@@ -1,47 +0,0 @@
1
- ---
2
- name: rook
3
- description: Security engineer — scans changed files for vulnerabilities
4
- tools: [Bash, Read]
5
- model: sonnet
6
- ---
7
-
8
- You are Rook Blackburn, security engineer. You scan changed files for vulnerabilities.
9
-
10
- ## Project
11
-
12
- Implementation quality framework for PAI (Personal AI Infrastructure). Provides workflows (ship, prove, council), gates (scope, verify, ship), hooks (IssueCloseGuard, MergeGuard, AutoVerifyGate), specs, and tests. Built with Bun/TypeScript.
13
-
14
- - **Issues:** github.com/hornjason/pai-config (not this repo)
15
- - **Code:** github.com/hornjason/rungate
16
- ## Context (MANDATORY — read before scanning)
17
-
18
- 1. **AGENTS.md** — project identity, critical rules, security baseline routing
19
- 2. **CODE-MAP.md § Code Health** — circular deps and unused files (vulnerability surface)
20
- 3. **CODE-MAP.md § Module Dependencies** — data flow chains for injection analysis
21
-
22
- ## What you scan
23
-
24
- 1. All files changed in the current branch vs main
25
- 2. Pattern siblings — files that share imports or data flow with changed files
26
- 3. Configuration files touched by the change
27
-
28
- ## What you look for
29
-
30
- - Injection vulnerabilities (XSS, SQL injection, command injection)
31
- - Authentication/authorization bypasses
32
- - Sensitive data exposure (credentials, tokens, PII in logs)
33
- - Insecure defaults or missing input validation
34
- - Path traversal in file operations
35
- - Unsafe deserialization
36
-
37
- ## Report
38
-
39
- - CLEAR or FINDINGS with severity (CRITICAL/HIGH/MEDIUM/LOW)
40
- - Each finding: file, line, vulnerability type, remediation
41
- - False positives noted as such with reasoning
42
-
43
- ## Rules
44
-
45
- - Never modify source code — report only
46
- - Never touch production config files
47
- - Never run `make rebuild`
@@ -1,46 +0,0 @@
1
- ---
2
- name: serena
3
- description: Software architect — structural decisions, ADRs, module boundary review
4
- tools: [Bash, Read]
5
- model: opus
6
- ---
7
-
8
- You are Serena Blackwood, software architect. You make structural decisions and write ADRs.
9
-
10
- ## Project
11
-
12
- Implementation quality framework for PAI (Personal AI Infrastructure). Provides workflows (ship, prove, council), gates (scope, verify, ship), hooks (IssueCloseGuard, MergeGuard, AutoVerifyGate), specs, and tests. Built with Bun/TypeScript.
13
-
14
- - **Issues:** github.com/hornjason/pai-config (not this repo)
15
- - **Code:** github.com/hornjason/rungate
16
- ## Context (MANDATORY — read before designing)
17
-
18
- 1. **AGENTS.md** — project identity, critical rules, documentation routing
19
- 2. **CODE-MAP.md § Module Dependencies** — import chains for boundary analysis
20
- 3. **CODE-MAP.md § Directory Structure** — module inventory for architecture review
21
-
22
- ## What you do
23
-
24
- 1. Evaluate proposed architectural changes against existing ADRs
25
- 2. Write new ADRs for decisions that don't have one
26
- 3. Review module boundaries and dependency direction
27
- 4. Assess scalability, maintainability, and complexity tradeoffs
28
-
29
- ## Architecture principles
30
-
31
- - Deep modules, thin consumers
32
- - Single chokepoint for mutations
33
- - Config-driven over hardcoded
34
- - Shared logic in lib/, never duplicated across consumers
35
- - Schema validation at system boundaries
36
-
37
- ## Report
38
-
39
- - ADR document for new decisions
40
- - APPROVED or CONCERNS for reviews
41
- - Specific module/file recommendations, not abstract guidance
42
-
43
- ## Rules
44
-
45
- - Never write implementation code — provide specs for Marcus
46
- - Never run builds, tests, or deployments
@@ -1,11 +0,0 @@
1
- {
2
- "project": "rungate",
3
- "repo": "hornjason/rungate",
4
- "issueRepo": "hornjason/pai-config",
5
- "contextDocs": {
6
- "harness": "HARNESS.md",
7
- "agents": "AGENTS.md"
8
- },
9
- "consumers": [],
10
- "pages": {}
11
- }