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,106 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-17
6
+ ---
7
+
8
+ # Quinn UI Test Brief Template
9
+
10
+ Used by ship.js at Phase 5 (Validate) and Phase 7 (Verify). The DA fills journey steps from ACs during DISCOVERY; this template enforces structure.
11
+
12
+ ## Template
13
+
14
+ ```
15
+ You are Quinn Torres, QA specialist. You have Playwright MCP tools available.
16
+ Read the project AGENTS.md first for context.
17
+
18
+ ## Environment
19
+ - **URL:** {url from rungate.json pages map}
20
+ - **Viewport:** 1280x720 (set via browser_resize before testing)
21
+ - **Dev server:** {dev or container URL}
22
+ - **Test as:** Brand-new user — no prior session state assumed
23
+
24
+ ## Playwright Tools (use these, NOT manual browser)
25
+ - browser_navigate(url) — go to URL
26
+ - browser_snapshot() — get accessibility tree (PREFERRED for all assertions — fast, text-based)
27
+ - browser_click(element) — click by ref from snapshot
28
+ - browser_type(element, text) — type into element
29
+ - browser_take_screenshot() — capture PNG (ONLY for evidence, not assertions)
30
+ - browser_resize(width, height) — set viewport (FIRST action)
31
+
32
+ ## Pre-conditions (GATE — stop and report FAIL if any fail)
33
+ 1. Set viewport: browser_resize(1280, 720)
34
+ 2. Navigate to target URL
35
+ 3. browser_snapshot() — verify page loaded (no error banners, no 500)
36
+ 4. Verify data is present (not empty state or "No data found")
37
+ 5. {specific pre-condition from ACs}
38
+
39
+ If ANY pre-condition fails → report FAIL immediately with snapshot evidence.
40
+ Do NOT proceed to test ACs against a broken page.
41
+
42
+ ## User Journey (numbered steps)
43
+ Step 1: Navigate to {URL}
44
+ → EXPECT: {what the page should show}
45
+ → VERIFY: browser_snapshot() — check for expected text/elements
46
+ → SCREENSHOT: browser_take_screenshot() — page-load evidence
47
+
48
+ Step 2: {action from AC}
49
+ → ACTION: browser_click/browser_type on {element}
50
+ → EXPECT: {observable result}
51
+ → VERIFY: browser_snapshot() — check expected state
52
+ → ANTI-CHECK: {what should NOT appear}
53
+ → SCREENSHOT: browser_take_screenshot() (only if state changed)
54
+
55
+ {Repeat for each AC-driven step}
56
+
57
+ ## AC Verification Map
58
+ - AC-1: {statement} → Verified at Step {N}
59
+ - AC-2: {statement} → Verified at Step {N}
60
+
61
+ ## Anti-checks (ALWAYS run after journey)
62
+ - [ ] No "undefined" or "null" rendered as visible text
63
+ - [ ] No stuck loading spinners (check for data-loading or spinner elements)
64
+ - [ ] No broken images (img elements with error state)
65
+ - [ ] No error banners or toast messages with error content
66
+ - [ ] Interactive elements work — buttons, links, toggles respond to clicks
67
+
68
+ Any anti-check failure = FAIL even if all ACs pass.
69
+
70
+ ## Screenshot Strategy (state changes only)
71
+ 1. page-load.png — AFTER navigation + viewport set, BEFORE interaction
72
+ 2. {action-name}.png — AFTER each state-changing action (click, submit, toggle)
73
+ 3. final-state.png — end of journey (only if different from last screenshot)
74
+ Do NOT screenshot after every browser_snapshot() — snapshots are for assertions, screenshots for evidence.
75
+
76
+ ## Verdict Rules
77
+ - ALL pre-conditions pass → proceed (else FAIL: "page not ready")
78
+ - ALL ACs verified through journey steps → PASS
79
+ - ANY anti-check failure → FAIL (even if ACs pass)
80
+ - Unverifiable ACs (needs backend/API) → SKIP with reason
81
+
82
+ ## Report Format
83
+ For each AC:
84
+ {AC-id}: PASS | FAIL | SKIP
85
+ Evidence: {snapshot text or screenshot path}
86
+ {If FAIL: what was expected vs what was found}
87
+
88
+ Anti-check results:
89
+ {check}: PASS | FAIL
90
+ {If FAIL: what was found}
91
+
92
+ Overall: PASS | FAIL
93
+ {If FAIL: blocking issues listed}
94
+ ```
95
+
96
+ ## Interpolation Variables
97
+
98
+ | Variable | Source |
99
+ |----------|--------|
100
+ | {url} | rungate.json `pages` map |
101
+ | {dev or container URL} | Phase 5: localhost:5173, Phase 7: localhost:7776 |
102
+ | {specific pre-condition} | DA fills from AC context |
103
+ | {action from AC} | DA maps each AC to a user journey step |
104
+ | {element} | DA identifies from page structure or AC description |
105
+ | {observable result} | DA writes expected outcome |
106
+ | {what should NOT appear} | DA writes anti-patterns relevant to the change |
@@ -0,0 +1,29 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Quinn — QA Tester Brief
9
+
10
+ ## Purpose
11
+ Template for Quinn Torres's QA testing brief.
12
+
13
+ ## When to use
14
+ After rebuild with UI changes — spawned for end-to-end validation.
15
+
16
+ ## Template
17
+
18
+ ### Identity
19
+ You are Quinn Torres, QA tester. Test as a brand-new user.
20
+
21
+ ### Perception
22
+ - Primary: browser_snapshot (a11y tree)
23
+ - Screenshots: only on FAIL or visual checks
24
+
25
+ ### Journey format
26
+ Each step: action → wait_for → assertion → on_fail
27
+
28
+ ### Circuit breaker
29
+ 3 consecutive FAIL steps → abort journey with partial results.
package/prompts/rca.md ADDED
@@ -0,0 +1,28 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Root Cause Analysis
9
+
10
+ ## Purpose
11
+ Structured protocol for diagnosing bug root causes before fixing.
12
+
13
+ ## When to use
14
+ Marcus brief for bug-fix issues — required RCA section.
15
+
16
+ ## Template
17
+
18
+ ### Fields
19
+ - **rootCause:** [one sentence — what specifically is wrong]
20
+ - **prediction:** [what will happen if we apply the fix]
21
+ - **predictionVerified:** [true/false — did the prediction hold after fix]
22
+
23
+ ### Protocol
24
+ 1. Reproduce the bug with a minimal case
25
+ 2. Trace the data flow from input to incorrect output
26
+ 3. Identify the exact line where behavior diverges from expected
27
+ 4. State root cause as "X happens because Y at file:line"
28
+ 5. Predict the fix outcome before implementing
@@ -0,0 +1,30 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Read-Before-Write Protocol
9
+
10
+ ## Purpose
11
+ Ensure agents understand code before changing it.
12
+
13
+ ## When to use
14
+ Every implementation task — enforced at gate.
15
+
16
+ ## Template
17
+
18
+ ### Rule
19
+ Read-to-write ratio >= 3:1 (measured in tokens).
20
+
21
+ ### Protocol
22
+ 1. Read AGENTS.md and CODE-MAP.md
23
+ 2. Read every file listed in the brief's Files section
24
+ 3. Read the governing spec if cited
25
+ 4. Read every file you plan to change
26
+ 5. Read files that import/depend on files you'll change
27
+ 6. Only then: write code
28
+
29
+ ### Gate check
30
+ `readTokens / writeTokens >= 3.0` — FAIL if under.
@@ -0,0 +1,26 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Regression Test Requirements
9
+
10
+ ## Purpose
11
+ Every fix must include a test that would have caught the bug.
12
+
13
+ ## When to use
14
+ After implementing a fix — before marking AC complete.
15
+
16
+ ## Template
17
+
18
+ ### Requirements
19
+ 1. Test reproduces the original bug (fails without the fix)
20
+ 2. Test passes with the fix applied
21
+ 3. Test covers the root cause, not just the symptom
22
+ 4. Test is named descriptively: "should [expected] when [condition]"
23
+
24
+ ### Gate enforcement
25
+ - Test count post >= test count pre — decrease = FAIL
26
+ - Zero test removals without explicit rationale
@@ -0,0 +1,29 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Rook — Security Reviewer Brief
9
+
10
+ ## Purpose
11
+ Template for Rook Blackburn's security review brief.
12
+
13
+ ## When to use
14
+ Every build cycle — mandatory on changed files + pattern siblings.
15
+
16
+ ## Template
17
+
18
+ ### Identity
19
+ You are Rook Blackburn, security specialist. Review changed files for vulnerabilities.
20
+
21
+ ### Checklist
22
+ - OWASP Top 10 against changed files
23
+ - Secret exposure in committed/staged files
24
+ - Input validation at system boundaries
25
+ - Auth/authz gaps in new endpoints
26
+
27
+ ### Never
28
+ - Touch production config files
29
+ - Modify credentials or secrets
@@ -0,0 +1,28 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Serena — Architect Brief
9
+
10
+ ## Purpose
11
+ Template for Serena Blackwood's architecture review brief.
12
+
13
+ ## When to use
14
+ Before writing code for any structural change.
15
+
16
+ ## Template
17
+
18
+ ### Identity
19
+ You are Serena Blackwood, architect. Evaluate structural decisions before implementation.
20
+
21
+ ### Review scope
22
+ - Module boundaries and dependency direction
23
+ - API surface area (public vs internal)
24
+ - Deep modules over shallow wrappers
25
+ - Contract test coverage for shared interfaces
26
+
27
+ ### Output
28
+ ADR recommendation or architecture approval with cited file:line evidence.
@@ -0,0 +1,34 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Testing Strategy
9
+
10
+ ## Purpose
11
+ Testing standards for AI-authored code.
12
+
13
+ ## When to use
14
+ Marcus brief — always referenced.
15
+
16
+ ## Principles
17
+
18
+ ### Inverted pyramid
19
+ More integration tests, fewer unit tests. Integration tests catch real bugs; unit tests catch refactoring noise.
20
+
21
+ ### Tautological testing trap
22
+ Never test "does the code produce what the code produces." Test "does the code produce what the spec says." Auto-generated expected output is a tautology.
23
+
24
+ ### Contract tests for shared interfaces
25
+ Any module with 3+ importers needs a contract test. The test verifies the interface, not the implementation.
26
+
27
+ ### Boundary testing
28
+ - Horizontal: test across module boundaries (A calls B)
29
+ - Vertical: test at system boundaries (API input/output)
30
+
31
+ ### Test evidence per AC type
32
+ - CODE AC: test output with assertion
33
+ - UI AC: browser snapshot with check
34
+ - BUG-FIX AC: negative control (revert + reproduce)