rungate 0.2.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 (196) hide show
  1. package/.claude/agents/aditi.md +47 -0
  2. package/.claude/agents/marcus.md +50 -0
  3. package/.claude/agents/quinn.md +58 -0
  4. package/.claude/agents/rook.md +47 -0
  5. package/.claude/agents/serena.md +46 -0
  6. package/.claude/rungate.json +11 -0
  7. package/.fallowrc.json +28 -0
  8. package/.github/copilot-instructions.md +20 -0
  9. package/.rungate/conformity-findings.json +648 -0
  10. package/AGENTS.md +106 -0
  11. package/CODE-MAP.md +50 -0
  12. package/HARNESS.md +88 -0
  13. package/bun.lock +26 -0
  14. package/bunfig.toml +2 -0
  15. package/config/brief-policies.json +28 -0
  16. package/config/ceremony-profiles.json +212 -0
  17. package/config/consumer-cascade-map.json +24 -0
  18. package/config/doc-cascade-map.json +24 -0
  19. package/config/eval.json +84 -0
  20. package/config/profiles/account-plan.yaml +36 -0
  21. package/config/profiles/campaign.yaml +94 -0
  22. package/config/prove-evidence.schema.json +65 -0
  23. package/config/spec-policies.json +36 -0
  24. package/config/workflow-schema.json +281 -0
  25. package/gates/SCHEMA-GUIDE.md +121 -0
  26. package/gates/ac-quality.test.ts +106 -0
  27. package/gates/adversarial.test.ts +274 -0
  28. package/gates/brief-assembler.test.ts +429 -0
  29. package/gates/brief-assembler.ts +334 -0
  30. package/gates/bunfig.toml +2 -0
  31. package/gates/chain.test.ts +91 -0
  32. package/gates/e2e-smoke.test.ts +234 -0
  33. package/gates/error-classifier.test.ts +249 -0
  34. package/gates/error-classifier.ts +89 -0
  35. package/gates/orchestrator.test.ts +950 -0
  36. package/gates/orchestrator.ts +569 -0
  37. package/gates/preload.ts +77 -0
  38. package/gates/prompts/ac-adversary.md +20 -0
  39. package/gates/prompts/evidence-validator.md +22 -0
  40. package/gates/prompts/prove-reproducer.md +53 -0
  41. package/gates/prove.test.ts +164 -0
  42. package/gates/run-gate.ts +936 -0
  43. package/gates/schema-parity.test.ts +197 -0
  44. package/gates/schema.ts +362 -0
  45. package/gates/self-heal.test.ts +511 -0
  46. package/gates/self-heal.ts +121 -0
  47. package/gates/ship-orchestrator.test.ts +379 -0
  48. package/gates/ship-orchestrator.ts +363 -0
  49. package/gates/test-fixtures/broken-no-environments.json +60 -0
  50. package/gates/test-fixtures/valid-standard.json +54 -0
  51. package/gates/test-utils.ts +43 -0
  52. package/gates/witness.ts +220 -0
  53. package/gates/workflow.test.ts +1053 -0
  54. package/hooks/AgentBriefGuard.hook.ts +586 -0
  55. package/hooks/AgentVerdictCapture.hook.ts +134 -0
  56. package/hooks/AutoVerifyGate.hook.ts +76 -0
  57. package/hooks/GateEnforcement.hook.ts +273 -0
  58. package/hooks/IssueCloseGuard.hook.ts +116 -0
  59. package/hooks/MergeGuard.hook.ts +55 -0
  60. package/hooks/StaleTTLCleanup.hook.ts +133 -0
  61. package/hooks/VerifyPhaseLock.hook.ts +81 -0
  62. package/hooks/WorkflowStateGuard.hook.ts +37 -0
  63. package/hooks/lib/agentDetection.ts +70 -0
  64. package/hooks/lib/findWorkflow.ts +101 -0
  65. package/hooks/lib/parseStdin.ts +37 -0
  66. package/hooks/lib/paths.ts +111 -0
  67. package/hooks/lib/utils.ts +81 -0
  68. package/lib/conformity.ts +959 -0
  69. package/lib/paths.ts +23 -0
  70. package/lib/rungate-schema.ts +60 -0
  71. package/lib/signal-phrases.ts +7 -0
  72. package/package.json +20 -0
  73. package/prompts/ac-adversary.md +20 -0
  74. package/prompts/ac-format.md +34 -0
  75. package/prompts/aditi.md +29 -0
  76. package/prompts/blast-radius.md +29 -0
  77. package/prompts/coding-principles.md +34 -0
  78. package/prompts/container-rebuild.md +29 -0
  79. package/prompts/container-verify.md +28 -0
  80. package/prompts/discovery.md +27 -0
  81. package/prompts/environment.md +28 -0
  82. package/prompts/escalation-decision-tree.md +38 -0
  83. package/prompts/evidence-hierarchy.md +31 -0
  84. package/prompts/evidence-validator.md +22 -0
  85. package/prompts/marcus.md +29 -0
  86. package/prompts/prevention.md +26 -0
  87. package/prompts/prove-reproducer.md +43 -0
  88. package/prompts/quinn-decision-tree.md +31 -0
  89. package/prompts/quinn-ui-brief.md +106 -0
  90. package/prompts/quinn.md +29 -0
  91. package/prompts/rca.md +28 -0
  92. package/prompts/read-before-write.md +30 -0
  93. package/prompts/regression.md +26 -0
  94. package/prompts/rook.md +29 -0
  95. package/prompts/serena.md +28 -0
  96. package/prompts/testing-strategy.md +34 -0
  97. package/reference/migration-manifest.json +554 -0
  98. package/reference/prompts/agent-aditi.md +38 -0
  99. package/reference/prompts/agent-marcus.md +38 -0
  100. package/reference/prompts/agent-quinn.md +38 -0
  101. package/reference/prompts/agent-rook.md +37 -0
  102. package/reference/prompts/agent-serena.md +37 -0
  103. package/reference/prompts/council-skill.md +170 -0
  104. package/reference/prompts/goal-skill.md +235 -0
  105. package/reference/prompts/prove-skill.md +283 -0
  106. package/reference/prompts/quinn-standard.md +246 -0
  107. package/reference/prompts/ship-convergence.md +65 -0
  108. package/reference/prompts/ship-escalation.md +43 -0
  109. package/reference/prompts/ship-iteration.md +382 -0
  110. package/reference/prompts/ship-pending-patches.md +246 -0
  111. package/reference/prompts/ship-reference.md +250 -0
  112. package/reference/prompts/ship-skill.md +347 -0
  113. package/reference/prompts/ship-templates.md +215 -0
  114. package/reference/scripts/batch-status.sh +68 -0
  115. package/reference/scripts/chain-compat-check.sh +67 -0
  116. package/reference/scripts/context-audit.sh +314 -0
  117. package/reference/scripts/dead-export-check.sh +61 -0
  118. package/reference/scripts/generate-qc-tables.sh +92 -0
  119. package/reference/scripts/harness-init.sh +111 -0
  120. package/reference/scripts/pai-054-baseline-check.sh +40 -0
  121. package/reference/scripts/prove-smoke-test.sh +112 -0
  122. package/reference/scripts/setup-keychain-salt.sh +12 -0
  123. package/reference/scripts/skill-optimizer-friday.sh +88 -0
  124. package/reference/scripts/skill-qc-test.sh +351 -0
  125. package/reference/scripts/skill-synthesize-tonight.sh +66 -0
  126. package/reference/specs/HARNESS-EXTRACTION-SPEC.md +263 -0
  127. package/reference/specs/harness-v3-bash-deletion-plan.md +65 -0
  128. package/reference/specs/harness-v3-migration-plan.md +188 -0
  129. package/scripts/decision-reconcile.sh +74 -0
  130. package/scripts/decision-reconcile.ts +152 -0
  131. package/scripts/extract-constraints.ts +260 -0
  132. package/scripts/generate-code-map.ts +339 -0
  133. package/scripts/git-hooks/pre-commit +76 -0
  134. package/scripts/git-hooks/pre-push +271 -0
  135. package/scripts/harness-skill-check.sh +52 -0
  136. package/scripts/lib/gap-emit.sh +65 -0
  137. package/scripts/lib/jq-update.sh +30 -0
  138. package/scripts/lib/resolve-slug.sh +30 -0
  139. package/scripts/lib/verify-spec-compliance.sh +102 -0
  140. package/scripts/prove-backfill.sh +87 -0
  141. package/scripts/scaffold-project.ts +1488 -0
  142. package/scripts/scaffold-rungate-config.ts +91 -0
  143. package/scripts/self-containment-check.sh +109 -0
  144. package/scripts/skill-qc-validator.sh +402 -0
  145. package/scripts/slug-resolver.sh +14 -0
  146. package/scripts/sync-spec-tests.ts +236 -0
  147. package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +2493 -0
  148. package/specs/BOOTSTRAP-TEST-PLAN.md +571 -0
  149. package/specs/HARNESS-GATES.md +256 -0
  150. package/specs/HARNESS-SKILL-CHAIN.md +286 -0
  151. package/specs/HARNESS-SKILL-CONTRACT.md +93 -0
  152. package/specs/HARNESS-STANDARD.md +488 -0
  153. package/specs/SPEC-TEMPLATE.md +53 -0
  154. package/specs/bootstrap-data-flow.png +0 -0
  155. package/specs/harness-automation-matrix.md +314 -0
  156. package/specs/harness-automation-matrix.rules.json +64 -0
  157. package/test/anti.test.ts +80 -0
  158. package/test/contract-negative.test.ts +86 -0
  159. package/test/contract.test.ts +158 -0
  160. package/test/external-deps.test.ts +48 -0
  161. package/test/fixtures/golden-project/.env.example +3 -0
  162. package/test/fixtures/golden-project/Makefile +7 -0
  163. package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +23 -0
  164. package/test/fixtures/golden-project/docs/setup-guide.md +10 -0
  165. package/test/fixtures/golden-project/package.json +10 -0
  166. package/test/fixtures/golden-project/specs/api-spec.md +20 -0
  167. package/test/fixtures/golden-project/src/auth.ts +8 -0
  168. package/test/fixtures/golden-project/src/db.ts +11 -0
  169. package/test/fixtures/golden-project/src/index.ts +19 -0
  170. package/test/fixtures/golden-project/src/utils/format.ts +3 -0
  171. package/test/fixtures/golden-project/test/auth.test.ts +15 -0
  172. package/test/fixtures/golden-project/tsconfig.json +12 -0
  173. package/test/meta-sc-coverage.test.ts +159 -0
  174. package/test/phase-0.test.ts +846 -0
  175. package/test/phase-1.test.ts +617 -0
  176. package/test/phase-2.test.ts +620 -0
  177. package/test/phase-3.test.ts +99 -0
  178. package/test/scaffold-conformity.test.ts +8 -0
  179. package/test/schema-canary.test.ts +51 -0
  180. package/test/spec-compliance-auto.test.ts +64 -0
  181. package/test/spec-compliance.test.ts +295 -0
  182. package/test/spec-discovery.test.ts +68 -0
  183. package/test/spec-drift.test.ts +5 -0
  184. package/test/structure.test.ts +165 -0
  185. package/test/unit/agent-brief-guard-ship.test.ts +293 -0
  186. package/test/unit/extract-constraints.test.ts +145 -0
  187. package/test/unit/issue-close-guard.test.ts +204 -0
  188. package/test/unit/scaffold-project.test.ts +417 -0
  189. package/test/unit/skill-cooccurrence.test.ts +177 -0
  190. package/test/unit/skill-sequence-logger.test.ts +244 -0
  191. package/test/unit/workflow-state-guard.test.ts +95 -0
  192. package/workflows/batch-ship.js +295 -0
  193. package/workflows/council.js +481 -0
  194. package/workflows/prove.js +560 -0
  195. package/workflows/ship.js +789 -0
  196. package/workflows/verify.js +236 -0
@@ -0,0 +1,263 @@
1
+ ---
2
+ doc-type: spec
3
+ status: in-progress
4
+ owner: jason
5
+ created: 2026-09-16
6
+ updated: 2026-09-16
7
+ testable: true
8
+ council-reviewed: 2026-09-16
9
+ councils: [adversarial-harness-extraction-wf_4fc577fc, architecture-council-harness-wf_7c6db7df]
10
+ related-issues: [517, 281, 513, 514]
11
+ ---
12
+
13
+ # Harness Extraction Spec
14
+
15
+ Extract all harness code from scattered locations into one self-contained git repo (`~/Projects/rungate/`), with mechanical tests that prevent drift forever.
16
+
17
+ ## Problem Statement
18
+
19
+ The ship harness (workflows, gates, tests, specs, prompts, config) is scattered across 10+ directories under `~/.claude/`. This makes it:
20
+ - **Non-portable** — can't clone to Mac Mini or new machine
21
+ - **Drift-prone** — 35 hardcoded paths, 3 duplicate config files, no containment enforcement
22
+ - **Untestable as a unit** — tests reference absolute paths, auto-generation hardcodes one spec
23
+ - **Invisible to agents** — no single entry point; agents need DOCS.md + CONTEXT_ROUTING + CLAUDE.md to find harness files
24
+
25
+ ## Success Criteria (all 10 must be true)
26
+
27
+ - [ ] SC-1: `~/Projects/rungate/` exists with all harness files in target structure
28
+ - [ ] SC-2: `hornjason/rungate` public repo on GitHub with clean history
29
+ - [ ] SC-3: Zero harness files in old scattered locations (containment test GREEN)
30
+ - [ ] SC-4: Zero hardcoded `~/.claude/` paths in any workflow/gate file (path-purity test GREEN)
31
+ - [ ] SC-5: All specs have `testable: true/false` frontmatter; auto-discovery working
32
+ - [ ] SC-6: Zod schema validates DDB rungate.json at gate load time
33
+ - [ ] SC-7: #513 fixed — AC evidence uses AC-specific commands
34
+ - [ ] SC-8: #514 fixed — phase advance blocked when ACs FAIL
35
+ - [ ] SC-9: One STANDARD-tier DDB issue SHIP_PASSED + PROVE_PROVEN through rungate/ workflows
36
+ - [ ] SC-10: Guard validation proven — intentional violations caught, then cleaned up
37
+
38
+ ## Council Findings (2 councils, 2026-09-16)
39
+
40
+ ### Council 1 — Migration Mechanics (adversarial, 4 members, 2 rounds)
41
+
42
+ 13 convergence points, 7 BLOCKERS. Core risk: 4 categories of path references, only TypeScript imports caught by compiler. Template literal agent prompts, CLAUDE.md natural-language rules, and hook system-reminder strings all fail silently.
43
+
44
+ | Blocker | What | File:Line |
45
+ |---|---|---|
46
+ | B1 | spec-compliance.test.ts 4 absolute paths | test/spec-compliance.test.ts:4-6,237 |
47
+ | B2 | sync-spec-tests.ts hardcoded paths | scripts/sync-spec-tests.ts:19-23 |
48
+ | B3 | HOME defaults to '/Users/jhorn' | ship.js:120, prove.js:123 |
49
+ | B4 | Create lib/paths.ts (harnessRoot, paiRoot) | New file |
50
+ | B5 | 10 template literal paths in workflows | ship.js:132,135,153,202,242,283,368,724,746; prove.js:126 |
51
+ | B7 | pre-push hook cross-directory imports | scripts/git-hooks/pre-push:13-14 |
52
+ | B9 | run-gate.ts 7 cwd references | run-gate.ts:163,199,205,232,315,497,558 |
53
+
54
+ Additional convergence points (HIGH/MEDIUM):
55
+ - CP-8: 9 structure tests needed (HIGH)
56
+ - CP-9: 3 hook system-reminder strings with relative gate paths (HIGH) — AutoVerifyGate:103, MergeGuard:113, IssueCloseGuard:450,530,548
57
+ - CP-10: Config file deduplication — ceremony-profiles.json, workflow-schema.json, spec-policies.json (MEDIUM)
58
+ - CP-11: .gate-salt cross-repo dependency — orchestrator.ts:125-131, witness.ts:20-26 (MEDIUM)
59
+ - CP-12: GP-1/GP-2 assertions encode old path as correct — spec-compliance.test.ts:191-199 (HIGH)
60
+ - CP-13: batch-ship.js:211 worktree heuristic uses `PROJECT_ROOT.includes('/.claude/')` (MEDIUM)
61
+
62
+ Migration strategy: symlink-based batch (not atomic cutover). Symlinks from old→new during transition, remove in final commit.
63
+
64
+ ### Council 2 — Architecture Decisions (3 members, 1 round)
65
+
66
+ | Decision | Verdict | Detail |
67
+ |---|---|---|
68
+ | D1: Spec frontmatter | MODIFY | `testable: true/false` required on every spec. Missing = FAIL. Drop check-types — parser determines claim types via regex. |
69
+ | D2: Self-contained repo | MODIFY | Self-contained for development. One CONTEXT_ROUTING entry. HARNESS.md lists "External Dependencies" — CLAUDE.md rule names. Drift detector test. |
70
+ | D3: HARNESS.md | KEEP | ~80 lines. 3 workflow entry points + rungate.json schema + test command + spec index. No internal layout exposed. |
71
+ | D4: rungate.json | MODIFY | DROP harnessRoot (use HARNESS_ROOT env var). ADD Zod schema validation at scaffold/load/test. |
72
+
73
+ **Repo boundary rule:** Harness repo owns execution machinery (phases, gates, specs, agent prompts). Does NOT own behavioral rules (CLAUDE.md), orchestration mode (Algorithm), project config (rungate.json), or PAI-wide routing (DOCS.md).
74
+
75
+ ## Execution Plan (AFK overnight 2026-09-16)
76
+
77
+ ### Pre-decided Answers (zero stops)
78
+
79
+ - Canary issue: create new issue meeting all 9 canary requirements
80
+ - Verify gate fails: iterate (circuit breaker at 6)
81
+ - Spec frontmatter ambiguity: default `testable: false`
82
+ - Test failure can't diagnose: log, file follow-up issue, continue
83
+ - Merge/push: push to rungate repo; commit ~/.claude changes to main
84
+ - Something breaks mid-migration: iterate via convergence loop (rollback only if 3+ phases fail)
85
+
86
+ ### Phase A — Spec Infrastructure (20 min)
87
+
88
+ - [ ] A1: Add `testable: true/false` to all specs in PAI/Specs/
89
+ - [ ] A2: Modify sync-spec-tests.ts → glob scan instead of hardcoded path
90
+ - [ ] A3: Write spec-discovery.test.ts (frontmatter enforcement: every spec has field, every testable:true has ≥1 claim)
91
+ - [ ] A4: Run → verify claim extraction works across all specs
92
+
93
+ ### Phase B — Path Foundation (30 min)
94
+
95
+ - [ ] B1: Create lib/paths.ts — `harnessRoot()`, `paiRoot()`, `workDir(slug)`, `gateSaltPath()`
96
+ - [ ] B2: Fix HOME defaults: ship.js:120, prove.js:123 (`'/Users/jhorn'` → `process.env.HOME`)
97
+ - [ ] B3: Fix spec-compliance.test.ts:4-6,237 + sync-spec-tests.ts:19-23 (use lib/paths.ts)
98
+ - [ ] B4: Fix 10 template literal paths in ship.js + prove.js:126 (use HARNESS_ROOT)
99
+ - [ ] B5: Fix run-gate.ts 7 cwd references (harnessRoot for Bun, paiRoot for CLI)
100
+ - [ ] B6: Fix pre-push hook cross-directory imports (scripts/git-hooks/pre-push:13-14)
101
+ - [ ] B7: Fix GP-1/GP-2 assertions in spec-compliance.test.ts:191-199
102
+ - [ ] GATE: run 12 migration invariants → all GREEN
103
+
104
+ ### Phase C — Schema + Validation (20 min)
105
+
106
+ - [ ] C1: Create lib/rungate-schema.ts (Zod) — required: project, repo, issueRepo, dev.start, dev.apiBase, dev.uiBase
107
+ - [ ] C2: Validate DDB rungate.json against schema
108
+ - [ ] C3: Wire validation into run-gate.ts load time (actionable error naming missing fields)
109
+ - [ ] C4: Write schema-canary.test.ts (validates DDB config as regression canary)
110
+ - [ ] GATE: run 12 invariants → GREEN
111
+
112
+ ### Phase D — Repo Structure + Guards (30 min)
113
+
114
+ - [ ] D1: Create ~/Projects/rungate/ — git init, package.json, bunfig.toml
115
+ - [ ] D2: `gh repo create hornjason/rungate --public`
116
+ - [ ] D3: Write HARNESS.md (~80 lines: 3 entry points, schema summary, test cmd, spec index, External Dependencies section)
117
+ - [ ] D4: Write migration-manifest.json (all files, migrated:false)
118
+ - [ ] D5: Write test/structure.test.ts — containment + path-purity + manifest checks (all FAIL expected)
119
+ - [ ] D6: Write test/external-deps.test.ts — drift detector (HARNESS.md External Dependencies vs CLAUDE.md)
120
+ - [ ] GATE: structure tests FAIL (expected baseline)
121
+
122
+ ### Phase E — Move Files + Wire (45 min)
123
+
124
+ - [ ] E1: Copy all files to rungate/ target structure
125
+ - [ ] E2: Create symlinks: old paths → new locations
126
+ - [ ] E3: Flip manifest entries → migrated:true
127
+ - [ ] E3.5: Update 3 hook system-reminder strings (AutoVerifyGate:103, MergeGuard:113, IssueCloseGuard:450,530,548) → absolute HARNESS_ROOT paths
128
+ - [ ] E3.6: Fix batch-ship.js:211 worktree heuristic (`PROJECT_ROOT.includes('/.claude/')`)
129
+ - [ ] E4: Dedup 3 config files (delete skills/ship/ copies, remove run-gate.ts:33-35 ternary fallback)
130
+ - [ ] E5: Move .gate-salt to gates/.gate-salt (update orchestrator.ts:125-131, witness.ts:20-26)
131
+ - [ ] E6: Add spec frontmatter to moved specs
132
+ - [ ] E7: Run ALL tests (invariant + structure) → GREEN
133
+ - [ ] E8: Update CLAUDE.md scriptPath rule → new location
134
+ - [ ] E9: Remove symlinks (final cleanup commit)
135
+ - [ ] E10: Run ALL tests again → GREEN
136
+ - [ ] GATE: containment GREEN, path-purity GREEN, manifest complete
137
+
138
+ ### Phase F — Fix #513 + #514 (45 min)
139
+
140
+ - [ ] F1: AC evidence must use AC-specific commands (#513)
141
+ - [ ] F2: Block phase advance when ACs FAIL (#514)
142
+ - [ ] F3: Gate tests pass from new location
143
+ - [ ] GATE: all tests GREEN
144
+
145
+ ### Phase G — Canary Ship Cycle (60 min)
146
+
147
+ Canary issue must exercise (council-specified 9 requirements):
148
+ 1. STANDARD tier (not LIGHT) — exercises AC Adversary, Evidence Validator, Quinn
149
+ 2. At least one OUTCOME-type AC — triggers dev server liveness check
150
+ 3. At least one .tsx file change — triggers Quinn local dev validation
151
+ 4. Full 4-gate chain: scope → verify → ship → prove
152
+ 5. Trigger at least one verify failure iteration — proves convergence loop works
153
+ 6. Invoke prove.js via workflow scriptPath — proves chained workflow resolution
154
+ 7. Post results to GitHub issue — proves GitHub integration
155
+ 8. Run brief-assembler.ts from new location — proves brief generation pipeline
156
+ 9. Run run-gate.ts child process spawns from new HARNESS_ROOT cwd
157
+
158
+ - [ ] G1: Create STANDARD-tier DDB issue meeting all 9 requirements
159
+ - [ ] G2: Full /ship through rungate/ workflows
160
+ - [ ] G3: Convergence loop on any failures (circuit breaker at 6)
161
+ - [ ] G4: /prove the shipped issue
162
+ - [ ] GATE: SHIP_PASSED + PROVE_PROVEN
163
+
164
+ ### Phase H — Guard Validation + Publish (15 min)
165
+
166
+ - [ ] H1: Intentionally create harness file in old location → containment test FAIL
167
+ - [ ] H2: Add hardcoded path to workflow file → path-purity test FAIL
168
+ - [ ] H3: Remove spec frontmatter from one spec → spec-discovery test FAIL
169
+ - [ ] H4: Clean up intentional violations → all tests GREEN
170
+ - [ ] H5: Push to hornjason/rungate public repo
171
+ - [ ] H6: Update checkpoint file with final status
172
+ - [ ] GATE: all 10 success criteria met
173
+
174
+ ## Target Structure (council-validated)
175
+
176
+ ```
177
+ rungate/
178
+ ├── HARNESS.md ← agent entry point (~80 lines, no internal layout)
179
+ ├── lib/ ← paths.ts, rungate-schema.ts (FOUNDATION)
180
+ ├── workflows/ ← ship.js, prove.js, council.js (EXECUTION — 3 entry points)
181
+ ├── gates/ ← run-gate.ts, tests, schema, .gate-salt (ENFORCEMENT)
182
+ ├── scripts/ ← sync-spec-tests, scaffold-rungate-config (TOOLING)
183
+ ├── hooks/ ← harness-lifecycle hooks only (~24, not all 52) (LIFECYCLE)
184
+ ├── test/ ← spec-compliance, spec-discovery, structure, schema-canary, external-deps (VERIFICATION)
185
+ ├── specs/ ← governing specs with testable frontmatter (TRUTH)
186
+ ├── config/ ← ceremony-profiles, schemas — 1 canonical copy each (CONFIG)
187
+ ├── prompts/ ← MarcusContext, QUINN-STANDARD, brief templates, SKILL.md docs (CONTEXT)
188
+ ├── package.json ← bun dependencies (zod, etc.)
189
+ ├── bunfig.toml ← test configuration
190
+ └── migration-manifest.json ← tracks every file source→dest (migration artifact)
191
+ ```
192
+
193
+ **No `skills/` dir.** SKILL.md files are context docs — move to `prompts/`.
194
+ **No `templates/` dir.** Brief templates move to `prompts/`. Issue templates move to `config/`.
195
+ **No `testing/` dir.** QUINN-STANDARD.md moves to `prompts/`.
196
+
197
+ ## Test Architecture (council-validated)
198
+
199
+ ### Spec Discovery
200
+
201
+ Glob scan `specs/*.md` filtered by YAML frontmatter `testable: true`. Every spec MUST have `testable: true` or `testable: false` — missing = FAIL. Parser extracts claims via regex (make commands, GATE markers, port refs, Quinn verbs). Scanner emits manifest: N specs, N testable, N claims.
202
+
203
+ ### Test Types
204
+
205
+ | Test file | What it checks | Decay it prevents |
206
+ |---|---|---|
207
+ | spec-compliance-auto.test.ts | Auto-generated assertions from spec claims | Spec↔code drift |
208
+ | spec-discovery.test.ts | Every spec has frontmatter, testable specs have claims | Silent test erosion |
209
+ | structure.test.ts | File layout, containment, path-purity, manifest | Migration stragglers, path regression |
210
+ | schema-canary.test.ts | rungate.json validates against Zod schema | Config drift |
211
+ | external-deps.test.ts | HARNESS.md External Dependencies match CLAUDE.md rules | Cross-repo behavioral drift |
212
+ | workflow.test.ts | Existing gate tests (code-committed, ports, config) | Gate regression |
213
+ | e2e-smoke.test.ts | Existing structural checks (case/default counts) | Structural regression |
214
+
215
+ ### Decay Prevention (3 layers)
216
+
217
+ 1. **Frontmatter enforcement** — missing field = FAIL (not skip)
218
+ 2. **Claim count regression** — manifest tracks per-spec claims; decrease without opt-out = FAIL
219
+ 3. **Cross-repo drift** — external-deps.test.ts catches CLAUDE.md rule changes that affect harness
220
+
221
+ ## rungate.json Contract (council-validated Zod schema)
222
+
223
+ **Required fields:** project, repo, issueRepo, dev.start, dev.apiBase, dev.uiBase
224
+ **Optional fields:** dev.preStart, dev.testCmd, dev.typeCheck, test.start, test.apiBase, prod.rebuild, prod.apiBase, prod.uiBase, prod.smokeTest, pages, codeCommittedPaths, consumers, contextDocs
225
+ **Dropped fields:** harnessRoot (use HARNESS_ROOT env var), context.architecture/agents/specs (zero consumers), healthCheck (derived from apiBase)
226
+ **Validation points:** scaffold output, run-gate.ts load time, schema-canary.test.ts
227
+ **Schema versioning:** schemaVersion field, breaking changes bump major version
228
+
229
+ ## Rollback Plan
230
+
231
+ 1. `git revert` migration commit(s) on main
232
+ 2. Remove symlinks: `find ~/.claude -type l -delete` (scoped)
233
+ 3. Restart Claude Code session (reloads CLAUDE.md/settings.json)
234
+ 4. Run `bun test gates/` + `bun test test/spec-compliance.test.ts` from `~/.claude/` → GREEN
235
+ 5. Accept one broken session between revert and restart
236
+
237
+ ## Migration Invariants (must pass at EVERY phase gate)
238
+
239
+ - INV-1: All gate unit tests in gates/*.test.ts pass
240
+ - INV-2: spec-compliance SC-1 through SC-5 pass (content-based)
241
+ - INV-3: spec-compliance PO-1 through PO-6 pass (phase ordering)
242
+ - INV-4: spec-compliance PI-1 through PI-3 pass (prompt immutability)
243
+ - INV-5: spec-compliance ER-1 through ER-4 pass (error recovery)
244
+ - INV-6: schema-parity.test.ts passes (Zod vs JSON schema)
245
+ - INV-7: chain.test.ts passes (witness chain structure)
246
+ - INV-8: ship-orchestrator.test.ts passes (self-contained in /tmp/)
247
+ - INV-9: `bun run gates/run-gate.ts --help` succeeds (import resolution smoke)
248
+ - INV-10: git push succeeds without pre-push import errors
249
+ - INV-11: No `/Users/jhorn` literal in workflows/*.js or gates/*.ts
250
+ - INV-12: Containment grep returns only intentional PAI-context references
251
+
252
+ ## npm Packaging (DEFERRED)
253
+
254
+ Only when git repo proves insufficient for multi-machine use.
255
+ - Namespace: `rungate` (NOT `@agentgrit/harness` — false coupling per council)
256
+ - CLI, provenance, separate npm publish
257
+
258
+ ## Related Docs
259
+
260
+ - `PAI/specs/REMOTE-EXECUTION-SPEC.md` — remote execution (Mac Mini, Tailscale, --bg)
261
+ - `PAI/specs/HARNESS-SKILL-CHAIN.md` — harness phases
262
+ - `PAI/HARNESS-STANDARD.md` — harness loop
263
+ - `PAI/HARNESS-GATES.md` — gate definitions
@@ -0,0 +1,65 @@
1
+ ---
2
+ doc-type: spec
3
+ status: ready
4
+ owner: jason
5
+ updated: 2026-09-08
6
+ testable: true
7
+ ---
8
+
9
+ # Harness v3 — Bash Deletion Plan
10
+
11
+ ## Status: Ready to delete after validation period
12
+
13
+ Run both systems in parallel for 1-2 more issues. If Bun gates catch everything bash caught, delete bash.
14
+
15
+ ## Files to delete
16
+
17
+ | File | Lines | Replaced by | Validated |
18
+ |---|---|---|---|
19
+ | `scripts/skill-runner.sh` | 1120 | Workflow scripts + post-agent.sh | #1333 shipped without it |
20
+ | `skills/ship/gate-runner.sh` | 294 | gates/workflow.test.ts + e2e-smoke.test.ts | #1333 gates passed |
21
+ | `skills/ship/gate-checks.sh` | 547 | gates/workflow.test.ts + e2e-smoke.test.ts | 28/28 tests |
22
+ | `scripts/git-hooks/pre-push` | 240 | Advisory — IssueCloseGuard enforces | D-025 made advisory |
23
+ | `scripts/lib/gap-emit.sh` | 88 | gates/learn.ts | #423 shipped |
24
+ | `skills/ship/gate-smoke-test.sh` | ~100 | gates/chain.test.ts + prove.test.ts | #1333 proven |
25
+ | `skills/ship/gate-smoke-test-e2e.sh` | ~80 | gates/chain.test.ts | Seeded tests pass |
26
+ | `scripts/prove-backfill.sh` | ~60 | gates/prove.test.ts | #1333 proven |
27
+ | `skills/ship/ceremony-profiles.json` | ~50 | Sizing logic in workflow.test.ts | — |
28
+ | `skills/ship/spec-policies.json` | ~30 | e2e-smoke.test.ts reads actual spec | ADR-050 validated |
29
+ | **Total** | **~2609** | **662 lines Bun** | |
30
+
31
+ ## Files to KEEP
32
+
33
+ | File | Why |
34
+ |---|---|
35
+ | `skills/ship/SKILL.md` | Documentation — describes the workflow |
36
+ | `skills/ship/workflow-schema.json` | Reference — Zod schema is canonical now but keep for docs |
37
+ | `scripts/slug-resolver.sh` | Used by multiple systems, not just gates |
38
+ | `scripts/validate-skill-output.sh` | Used by goal/ship/prove skills |
39
+ | `hooks/AgentBriefGuard.hook.ts` | Modified (#420) — still active |
40
+ | `hooks/IssueCloseGuard.hook.ts` | Still enforces issue close — not replaced |
41
+
42
+ ## Deletion command
43
+
44
+ ```bash
45
+ git rm scripts/skill-runner.sh
46
+ git rm skills/ship/gate-runner.sh
47
+ git rm skills/ship/gate-checks.sh
48
+ git rm scripts/git-hooks/pre-push
49
+ git rm scripts/lib/gap-emit.sh
50
+ git rm skills/ship/gate-smoke-test.sh
51
+ git rm skills/ship/gate-smoke-test-e2e.sh
52
+ git rm scripts/prove-backfill.sh
53
+ git rm skills/ship/ceremony-profiles.json
54
+ git rm skills/ship/spec-policies.json
55
+ git commit -m "chore: delete bash harness — replaced by Bun gates (ADR-008)"
56
+ ```
57
+
58
+ ## Validation checklist (before deleting)
59
+
60
+ - [x] #1333 shipped through Bun gates (goal→ship→prove→close)
61
+ - [x] #420 AgentBriefGuard accepts workflow-state.json
62
+ - [x] #422 Phase advancement mechanical
63
+ - [x] #423 Learning capture working
64
+ - [ ] Ship 1-2 more DDB issues through Bun gates without bash fallback
65
+ - [ ] Verify no other scripts source/call the deleted files
@@ -0,0 +1,188 @@
1
+ ---
2
+ doc-type: spec
3
+ status: proposed
4
+ owner: jason
5
+ updated: 2026-09-08
6
+ testable: true
7
+ ---
8
+
9
+ # Harness v3 Migration Plan
10
+
11
+ ## Viability Test (do this FIRST — 30 minutes)
12
+
13
+ Before migrating anything, prove the approach works with one seeded test.
14
+
15
+ ### Step 0: Scaffold
16
+
17
+ ```bash
18
+ mkdir -p ~/.claude/gates
19
+ cd ~/.claude
20
+ bun init -y # if no package.json
21
+ bun add -d zod
22
+ ```
23
+
24
+ ### Step 1: Write ONE gate check as a Bun test
25
+
26
+ ```typescript
27
+ // gates/viability.test.ts
28
+ import { test, expect } from "bun:test";
29
+ import { z } from "zod";
30
+ import { readFileSync, existsSync } from "fs";
31
+
32
+ const WorkflowState = z.object({
33
+ schemaVersion: z.literal(2),
34
+ issue: z.number(),
35
+ phase: z.string(),
36
+ acs: z.array(z.object({
37
+ id: z.string(),
38
+ threshold: z.object({ op: z.string(), value: z.string() }).optional(),
39
+ })),
40
+ });
41
+
42
+ const TEST_DIR = process.env.TEST_WORK_DIR || "/tmp/gate-viability-test";
43
+
44
+ test("workflow-state.json validates against schema", () => {
45
+ const wf = JSON.parse(readFileSync(`${TEST_DIR}/workflow-state.json`, "utf-8"));
46
+ expect(() => WorkflowState.parse(wf)).not.toThrow();
47
+ });
48
+
49
+ test("all ACs have thresholds", () => {
50
+ const wf = JSON.parse(readFileSync(`${TEST_DIR}/workflow-state.json`, "utf-8"));
51
+ const missing = wf.acs.filter((ac: any) => !ac.threshold);
52
+ expect(missing.length).toBe(0);
53
+ });
54
+
55
+ test("no hardcoded thresholds in changed files", () => {
56
+ // Simulates spec compliance check
57
+ const changedFiles = (process.env.CHANGED_FILES || "").split(",").filter(Boolean);
58
+ for (const f of changedFiles) {
59
+ if (!existsSync(f)) continue;
60
+ const content = readFileSync(f, "utf-8");
61
+ const hardcoded = content.match(/=[0-9]+$/gm) || [];
62
+ expect(hardcoded.length).toBe(0);
63
+ }
64
+ });
65
+ ```
66
+
67
+ ### Step 2: Create seeded test data
68
+
69
+ ```bash
70
+ mkdir -p /tmp/gate-viability-test
71
+ cat > /tmp/gate-viability-test/workflow-state.json << 'EOF'
72
+ {
73
+ "schemaVersion": 2,
74
+ "issue": 999,
75
+ "phase": "VERIFY",
76
+ "acs": [
77
+ {"id": "SC-1", "threshold": {"op": ">=", "value": "1"}},
78
+ {"id": "SC-2", "threshold": {"op": "==", "value": "0"}}
79
+ ]
80
+ }
81
+ EOF
82
+ ```
83
+
84
+ ### Step 3: Run it
85
+
86
+ ```bash
87
+ TEST_WORK_DIR=/tmp/gate-viability-test bun test gates/viability.test.ts
88
+ ```
89
+
90
+ **Expected:** 3 tests pass. If they do, the approach is viable. If not, we learn why before investing more.
91
+
92
+ ### Step 4: Run with FAILING seed data
93
+
94
+ ```bash
95
+ # Seed with missing threshold
96
+ cat > /tmp/gate-viability-test/workflow-state.json << 'EOF'
97
+ {
98
+ "schemaVersion": 2,
99
+ "issue": 999,
100
+ "phase": "VERIFY",
101
+ "acs": [
102
+ {"id": "SC-1"},
103
+ {"id": "SC-2", "threshold": {"op": "==", "value": "0"}}
104
+ ]
105
+ }
106
+ EOF
107
+
108
+ TEST_WORK_DIR=/tmp/gate-viability-test bun test gates/viability.test.ts
109
+ ```
110
+
111
+ **Expected:** "all ACs have thresholds" FAILS. This proves the gate catches violations.
112
+
113
+ ---
114
+
115
+ ## Full Migration (after viability confirmed)
116
+
117
+ ### Phase 1: Port checks (2 hours)
118
+
119
+ Port the 10 most important gate-checks.sh functions to gates/workflow.test.ts:
120
+ 1. acs-exist
121
+ 2. acs-have-threshold
122
+ 3. all-acs-pass
123
+ 4. evidence-type-ratio
124
+ 5. code-committed
125
+ 6. branch-merged
126
+ 7. code-pushed
127
+ 8. decision-id-valid
128
+ 9. spec-drift
129
+ 10. tests-pass
130
+
131
+ Run bash gate AND bun test in parallel for one session. Compare results. Fix discrepancies.
132
+
133
+ ### Phase 2: Hook wiring (30 minutes)
134
+
135
+ Add to `.claude/settings.json`:
136
+ ```json
137
+ {
138
+ "hooks": {
139
+ "SubagentStop": [{
140
+ "command": "bun test --bail gates/workflow.test.ts",
141
+ "description": "Gate checks after agent completion"
142
+ }]
143
+ }
144
+ }
145
+ ```
146
+
147
+ ### Phase 3: Chain as Workflow (1 hour)
148
+
149
+ One workflow script replaces skill-runner.sh chain logic:
150
+ ```javascript
151
+ export const meta = {
152
+ name: 'harness-chain',
153
+ description: 'goal → ship → prove → close',
154
+ phases: [{ title: 'Goal' }, { title: 'Ship' }, { title: 'Prove' }]
155
+ }
156
+
157
+ phase('Goal')
158
+ const goal = await agent('Run /goal for issue ' + args.issue)
159
+
160
+ phase('Ship')
161
+ const ship = await agent('Run /ship for issue ' + args.issue)
162
+
163
+ phase('Prove')
164
+ const prove = await agent('Run /prove for issue ' + args.issue)
165
+ ```
166
+
167
+ ### Phase 4: Delete bash (30 minutes)
168
+
169
+ After one full session with both running:
170
+ - Delete skill-runner.sh (keep git history)
171
+ - Delete gate-runner.sh
172
+ - Delete gate-checks.sh
173
+ - Replace pre-push with lefthook.yml
174
+
175
+ ---
176
+
177
+ ## DDB Onboarding (after migration)
178
+
179
+ ```bash
180
+ cd ~/Projects/DailyBriefDashboard
181
+ mkdir -p gates
182
+ cp ~/.claude/gates/workflow.test.ts gates/ # copy, then customize schema
183
+ # Edit schema to match DDB's workflow-state shape
184
+ # Add project-specific checks
185
+ bun test gates/ # verify
186
+ ```
187
+
188
+ Done. No 10 bash scripts. No ceremony-profiles.json. No skill-registry.json.
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env bash
2
+ # decision-reconcile.sh — Verify council decisions are present in target documents
3
+ # Usage: decision-reconcile.sh <council-synthesis.json> [--target <file>]
4
+ # Without --target: checks ALL decisions against their declared targets
5
+ # With --target: checks only decisions targeting that specific file
6
+ set -euo pipefail
7
+
8
+ SYNTHESIS="${1:?Usage: decision-reconcile.sh <council-synthesis.json> [--target <file>]}"
9
+ TARGET_FILTER=""
10
+ if [[ "${2:-}" == "--target" ]]; then
11
+ TARGET_FILTER="${3:?Usage: decision-reconcile.sh <file> --target <target-file>}"
12
+ fi
13
+
14
+ [[ -f "$SYNTHESIS" ]] || { echo "FAIL: $SYNTHESIS not found" >&2; exit 1; }
15
+ jq empty "$SYNTHESIS" 2>/dev/null || { echo "FAIL: $SYNTHESIS is invalid JSON" >&2; exit 1; }
16
+
17
+ RESULTS=$(python3 -c "
18
+ import json, sys, os
19
+
20
+ data = json.load(open('$SYNTHESIS'))
21
+ decisions = data.get('decisions', [])
22
+ target_filter = '$TARGET_FILTER'
23
+ home = os.path.expanduser('~')
24
+
25
+ for d in decisions:
26
+ target = d.get('target', {})
27
+ ref = target.get('ref', '')
28
+ if not ref:
29
+ continue
30
+ if target_filter and ref != target_filter:
31
+ continue
32
+
33
+ filepath = ref.replace('~', home)
34
+
35
+ try:
36
+ with open(filepath) as f:
37
+ content = f.read()
38
+ except FileNotFoundError:
39
+ print(f'MISSING|{d[\"id\"]}|{d[\"statement\"][:60]}|file not found: {ref}')
40
+ continue
41
+
42
+ statement = d['statement']
43
+ words = [w for w in statement.split() if len(w) > 3][:5]
44
+ key_phrase = ' '.join(words[:3])
45
+
46
+ if key_phrase.lower() in content.lower() or d['id'] in content:
47
+ print(f'FOUND|{d[\"id\"]}|{d[\"statement\"][:60]}')
48
+ else:
49
+ section = target.get('section', '')
50
+ if section and section.lower() in content.lower():
51
+ print(f'FOUND|{d[\"id\"]}|{d[\"statement\"][:60]}|via section match')
52
+ else:
53
+ print(f'MISSING|{d[\"id\"]}|{d[\"statement\"][:60]}|not found in {ref}')
54
+ " 2>/dev/null)
55
+
56
+ TOTAL=0
57
+ FOUND=0
58
+ MISSING=0
59
+
60
+ while IFS='|' read -r status id statement detail; do
61
+ [[ -z "$status" ]] && continue
62
+ TOTAL=$((TOTAL + 1))
63
+ if [[ "$status" == "FOUND" ]]; then
64
+ FOUND=$((FOUND + 1))
65
+ echo " FOUND: $id — $statement"
66
+ else
67
+ MISSING=$((MISSING + 1))
68
+ echo " MISSING: $id — $statement ($detail)"
69
+ fi
70
+ done <<< "$RESULTS"
71
+
72
+ echo ""
73
+ echo "=== Reconcile: $FOUND found, $MISSING missing out of $TOTAL decisions ==="
74
+ [[ $MISSING -eq 0 ]] && exit 0 || exit 1