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
package/lib/paths.ts ADDED
@@ -0,0 +1,23 @@
1
+ import { join, resolve } from "path";
2
+ import { existsSync } from "fs";
3
+
4
+ export function harnessRoot(): string {
5
+ if (process.env.HARNESS_ROOT) return process.env.HARNESS_ROOT;
6
+ const repoRoot = resolve(import.meta.dir, "..");
7
+ if (existsSync(join(repoRoot, "HARNESS.md"))) return repoRoot;
8
+ return join(process.env.HOME || "", ".claude");
9
+ }
10
+
11
+ export function paiRoot(): string {
12
+ return process.env.PAI_ROOT || join(process.env.HOME || "", ".claude");
13
+ }
14
+
15
+ export function workDir(slug: string): string {
16
+ if (slug.includes('..') || slug.startsWith('/')) throw new Error(`Invalid slug: ${slug}`);
17
+ const base = process.env.RUNGATE_WORK_DIR || join(process.env.HOME || "", ".rungate");
18
+ return join(base, slug);
19
+ }
20
+
21
+ export function gateSaltPath(): string {
22
+ return join(harnessRoot(), "gates", ".gate-salt");
23
+ }
@@ -0,0 +1,60 @@
1
+ import { z } from "zod";
2
+
3
+ const DevSchema = z.object({
4
+ start: z.string(),
5
+ apiBase: z.string().url(),
6
+ uiBase: z.string().url(),
7
+ preStart: z.string().optional(),
8
+ testCmd: z.string().optional(),
9
+ typeCheck: z.string().optional(),
10
+ note: z.string().optional(),
11
+ });
12
+
13
+ const TestSchema = z.object({
14
+ start: z.string().optional(),
15
+ apiBase: z.string().url().optional(),
16
+ note: z.string().optional(),
17
+ });
18
+
19
+ const ProdSchema = z.object({
20
+ rebuild: z.string().optional(),
21
+ apiBase: z.string().url().optional(),
22
+ uiBase: z.string().url().optional(),
23
+ smokeTest: z.string().optional(),
24
+ });
25
+
26
+ const McpServerSchema = z.object({
27
+ name: z.string(),
28
+ tools: z.array(z.string()).optional(),
29
+ });
30
+
31
+ const ResearchToolSchema = z.object({
32
+ name: z.string(),
33
+ type: z.enum(["mcp", "cli", "api"]).optional(),
34
+ });
35
+
36
+ const ProjectHarnessSchema = z.object({
37
+ project: z.string(),
38
+ repo: z.string(),
39
+ issueRepo: z.string(),
40
+ dev: DevSchema.optional(),
41
+ test: TestSchema.optional(),
42
+ prod: ProdSchema.optional(),
43
+ pages: z.record(z.string()).optional(),
44
+ codeCommittedPaths: z.array(z.string()).optional(),
45
+ consumers: z.array(z.string()).optional(),
46
+ contextDocs: z.record(z.string().nullable()).optional(),
47
+ mcp: z.array(McpServerSchema).optional(),
48
+ research: z.array(ResearchToolSchema).optional(),
49
+ schemaVersion: z.number().default(1),
50
+ });
51
+
52
+ export type ProjectHarness = z.infer<typeof ProjectHarnessSchema>;
53
+
54
+ export function parseProjectHarness(raw: unknown): ProjectHarness {
55
+ return ProjectHarnessSchema.parse(raw);
56
+ }
57
+
58
+ export function safeParseProjectHarness(raw: unknown) {
59
+ return ProjectHarnessSchema.safeParse(raw);
60
+ }
@@ -0,0 +1,7 @@
1
+ export const SIGNAL_PHRASE_PATTERNS = [
2
+ /^[-*] .*(must not|never|must|always|required|shall|prefer|eliminate).+$/gim,
3
+ /[.;]\s*(must not|never|must|always|required|shall).+?[.;\n]/gim,
4
+ /\b(explicitly prefers?|not dependent on|single chokepoint|no new).+?[.;\n]/gim,
5
+ /\b(intentional|by design|anti-pattern|permanently disabled|do not change|do not remove|do not regress)\b.+?[.;\n]/gim,
6
+ /\b(only on|only from|only when|only in|permanent[^l]|every \d+[hm]\b).+?[.;\n]/gim,
7
+ ] as const;
package/package.json ADDED
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "rungate",
3
+ "version": "0.2.0",
4
+ "type": "module",
5
+ "description": "Ship harness — workflows, gates, specs, and guard tests for PAI development lifecycle",
6
+ "exports": {
7
+ "./lib/conformity": "./lib/conformity.ts"
8
+ },
9
+ "scripts": {
10
+ "test": "bun test",
11
+ "test:structure": "bun test test/structure.test.ts",
12
+ "test:external-deps": "bun test test/external-deps.test.ts"
13
+ },
14
+ "dependencies": {
15
+ "zod": "^3.23.0"
16
+ },
17
+ "devDependencies": {
18
+ "@types/bun": "latest"
19
+ }
20
+ }
@@ -0,0 +1,20 @@
1
+ You are an adversarial AC reviewer. Your objective: find ways to pass
2
+ every AC without actually fixing the bug.
3
+
4
+ For each AC, answer:
5
+ 1. Can I write code that passes the evidence command but doesn't fix
6
+ the stated problem? How?
7
+ 2. Is the threshold meaningful? Could garbage data meet it?
8
+ 3. Does the evidence command test behavior (runtime output) or just
9
+ structure (file existence, grep count)?
10
+
11
+ Output as JSON:
12
+ {
13
+ "gameable": <number of gameable ACs>,
14
+ "approved": <true if 0 gameable>,
15
+ "exploits": [
16
+ {"acId": "SC-1", "exploit": "how to pass without fixing", "recommendation": "how to tighten"}
17
+ ]
18
+ }
19
+
20
+ If ALL ACs are robust, output: {"gameable": 0, "approved": true, "exploits": []}
@@ -0,0 +1,34 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # AC Format Requirements
9
+
10
+ ## Purpose
11
+ Standardize acceptance criteria format for mechanical verification.
12
+
13
+ ## When to use
14
+ Goal and ship phases — writing and validating ACs.
15
+
16
+ ## Format
17
+
18
+ ### Required fields
19
+ 1. **Trigger:** What action causes the behavior
20
+ 2. **Output:** What the system produces
21
+ 3. **Verify command:** Executable command that proves it works
22
+ 4. **Exclusions:** What this AC does NOT cover
23
+
24
+ ### Example
25
+ ```
26
+ AC-1 [CODE]: API returns 200 on valid input
27
+ Trigger: POST /api/data with valid JSON body
28
+ Output: 200 response with { success: true }
29
+ Verify: curl -X POST localhost:3000/api/data -d '{"key":"val"}' | jq .success
30
+ Exclusions: Error handling, auth, rate limiting
31
+ ```
32
+
33
+ ### Garbage test
34
+ "Could garbage data pass this AC?" If yes, tighten it.
@@ -0,0 +1,29 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Aditi — Designer Brief
9
+
10
+ ## Purpose
11
+ Template for Aditi Sharma's UI/UX design brief.
12
+
13
+ ## When to use
14
+ Before building any new UI surface.
15
+
16
+ ## Template
17
+
18
+ ### Identity
19
+ You are Aditi Sharma, UI/UX designer. Specify component layouts and interaction patterns.
20
+
21
+ ### Deliverables
22
+ - Component spec with layout, spacing, states
23
+ - Interaction flow (happy path + error states)
24
+ - Accessibility requirements (ARIA, keyboard nav)
25
+ - Responsive breakpoints if applicable
26
+
27
+ ### Constraints
28
+ - Use existing design system components first
29
+ - shadcn/ui as component library baseline
@@ -0,0 +1,29 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Blast Radius Assessment
9
+
10
+ ## Purpose
11
+ Ensure every code change is scoped and its impact is understood.
12
+
13
+ ## When to use
14
+ Marcus brief — pre-implementation checklist.
15
+
16
+ ## Template
17
+
18
+ ### Rule
19
+ filesRead >= filesChanged — you must read more than you change.
20
+
21
+ ### Checklist
22
+ 1. List every file you will change
23
+ 2. List every file that imports/depends on changed files
24
+ 3. Read all dependent files before changing anything
25
+ 4. If filesChanged > filesRead, stop and read more
26
+
27
+ ### Gate enforcement
28
+ - Read-before-write ratio >= 3:1 (read tokens / write tokens)
29
+ - Files changed outside brief's listed files = WARN
@@ -0,0 +1,34 @@
1
+ ---
2
+ doc-type: architecture
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Coding Principles
9
+
10
+ ## Purpose
11
+ Core coding standards for all implementation work.
12
+
13
+ ## When to use
14
+ Marcus brief — always referenced.
15
+
16
+ ## Principles
17
+
18
+ ### Deep modules over shallow wrappers
19
+ Expose a simple interface, hide complexity inside. A module with 3 public functions and 15 internal helpers is better than 15 public functions.
20
+
21
+ ### Boundary validation with Zod
22
+ Validate at system boundaries (API inputs, config files, external data). Trust internal code. Don't re-validate inside the module.
23
+
24
+ ### Exhaustive matching (assertNever)
25
+ ```typescript
26
+ function assertNever(x: never): never { throw new Error(`Unexpected: ${x}`); }
27
+ ```
28
+ Use in switch/case defaults to catch unhandled variants at compile time.
29
+
30
+ ### Immutability by default
31
+ Prefer `const`, `readonly`, and new objects over mutation. Mutation is a last resort for performance.
32
+
33
+ ### One export per concern
34
+ Each file exports one thing. If you need two, that's two files.
@@ -0,0 +1,29 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Container Rebuild
9
+
10
+ ## Purpose
11
+ Rebuild the project container with latest code changes.
12
+
13
+ ## When to use
14
+ After code changes merged to main — when prod.rebuild is configured.
15
+
16
+ ## Template
17
+
18
+ ### Pre-checks
19
+ 1. Verify prod.rebuild command exists in rungate.json
20
+ 2. Check container lock — abort if locked
21
+ 3. Verify main branch is up to date
22
+
23
+ ### Execution
24
+ Run: `${prod.rebuild}` from rungate.json
25
+
26
+ ### Post-checks
27
+ 1. Container is running
28
+ 2. Health endpoint responds
29
+ 3. Release lock on completion
@@ -0,0 +1,28 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Container Verification
9
+
10
+ ## Purpose
11
+ Verify the container is running correctly after a rebuild.
12
+
13
+ ## When to use
14
+ After container-rebuild completes — before declaring deploy success.
15
+
16
+ ## Template
17
+
18
+ ### Verification steps
19
+ 1. Container status: running
20
+ 2. Health endpoint: `curl ${prod.apiBase}/api/health`
21
+ 3. Version check: container HEAD matches expected commit SHA
22
+ 4. Smoke test: hit 2-3 critical endpoints
23
+
24
+ ### Report
25
+ - Status: verified / failed
26
+ - Container HEAD: {sha}
27
+ - Health: {response}
28
+ - Failures: [list or "none"]
@@ -0,0 +1,27 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Discovery
9
+
10
+ ## Purpose
11
+ Read project docs in order to build context before implementation.
12
+
13
+ ## When to use
14
+ DISCOVERY phase of ship cycle — before writing any code.
15
+
16
+ ## Template
17
+
18
+ ### Read order
19
+ 1. AGENTS.md — project identity, constraints, commands
20
+ 2. CODE-MAP.md — modules, routes, dependencies
21
+ 3. Governing spec (if cited in issue)
22
+ 4. Related files from issue context
23
+
24
+ ### Output
25
+ - Key constraints discovered
26
+ - Files that will be touched
27
+ - Risks or unknowns to flag
@@ -0,0 +1,28 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Environment Setup Verification
9
+
10
+ ## Purpose
11
+ Verify project environment is correctly configured before work begins.
12
+
13
+ ## When to use
14
+ Ship DISCOVERY phase — after reading docs, before coding.
15
+
16
+ ## Template
17
+
18
+ ### Checks
19
+ 1. `bun install` completes without errors
20
+ 2. `bun test` runs (capture baseline pass/fail)
21
+ 3. `bunx tsc --noEmit` passes
22
+ 4. Dev server starts (`make dev` or equivalent)
23
+ 5. Required env vars present (check .env.example)
24
+
25
+ ### Report
26
+ - Environment: ready / blocked
27
+ - Baseline test results: N pass, N fail
28
+ - Blockers: [list or "none"]
@@ -0,0 +1,38 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Escalation Decision Tree
9
+
10
+ ## Purpose
11
+ Guides agents on when to escalate vs retry.
12
+
13
+ ## When to use
14
+ Embedded in every agent brief — referenced during execution.
15
+
16
+ ## Decision tree
17
+
18
+ ### Iteration 1: Try the obvious fix
19
+ Apply the most direct solution. Run tests.
20
+
21
+ ### Iteration 2: Research before retrying
22
+ If iteration 1 failed, you MUST use research tools before trying again:
23
+ - Read related source files
24
+ - Search for similar patterns in codebase
25
+ - Check documentation for constraints
26
+
27
+ ### Iteration 3: Escalate
28
+ If iteration 2 failed with research evidence, escalate:
29
+ - Report what you tried
30
+ - Report what research revealed
31
+ - Recommend next steps
32
+
33
+ ### Available research tools
34
+ Listed in AGENTS.md "Research Tools" section and rungate.json `research` field.
35
+
36
+ ### Never
37
+ - Retry the same approach without new information
38
+ - Exceed 3 iterations without escalating
@@ -0,0 +1,31 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Evidence Hierarchy
9
+
10
+ ## Purpose
11
+ Defines evidence tiers so agents know what quality of proof is required.
12
+
13
+ ## When to use
14
+ Gate enforcement — maps evidence types to tiers per AC type.
15
+
16
+ ## Tiers
17
+
18
+ | Tier | Name | Method | Strength |
19
+ |------|------|--------|----------|
20
+ | S | Negative control | Revert fix, confirm bug returns | Strongest |
21
+ | A | Test output | `bun test` with assertion | Strong |
22
+ | B | Browser verification | Quinn screenshot + assertion | Strong for UI |
23
+ | C | Command output | curl, grep with specific check | Moderate |
24
+ | D | Static grep | `grep -r "pattern"` | Weak — cap at 25% |
25
+ | F | Self-attestation | "I checked and it works" | FAIL — always rejected |
26
+
27
+ ### Minimum tiers by AC type
28
+ - CODE → A (test output)
29
+ - UI → B (browser verification)
30
+ - BUG-FIX → S (negative control)
31
+ - Static analysis → C supplementary only
@@ -0,0 +1,22 @@
1
+ You are an evidence validator. Your objective: run evidence commands
2
+ independently and report whether results meet AC thresholds.
3
+
4
+ You run in a clean worktree. You cannot modify the code.
5
+ Execute each evidence command, capture output, compare against threshold.
6
+
7
+ Report as JSON:
8
+ {
9
+ "verdicts": [
10
+ {
11
+ "acId": "SC-1",
12
+ "command": "the command executed",
13
+ "rawOutput": "captured output",
14
+ "threshold": {"op": ">=", "value": "2", "unit": "..."},
15
+ "actual": "measured value",
16
+ "verdict": "PASS or FAIL"
17
+ }
18
+ ]
19
+ }
20
+
21
+ Do not infer, assume, or extrapolate. If the command fails to run,
22
+ verdict is FAIL with the error message as rawOutput.
@@ -0,0 +1,29 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Marcus — Engineer Brief
9
+
10
+ ## Purpose
11
+ Template for Marcus Webb's implementation brief.
12
+
13
+ ## When to use
14
+ Ship EXECUTION phase — spawning Marcus for code changes.
15
+
16
+ ## Template
17
+
18
+ ### Identity
19
+ You are Marcus Webb, principal engineer. You implement code changes, write tests, and commit.
20
+
21
+ ### Protocol
22
+ 1. Read AGENTS.md first
23
+ 2. Read every file in the brief's Files section
24
+ 3. Run existing tests to establish baseline
25
+ 4. TDD: write failing test, then implementation
26
+ 5. Run full test suite before reporting
27
+
28
+ ### Report format
29
+ For each AC, provide evidence: file:line, grep output, or test result.
@@ -0,0 +1,26 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Prevention-Oriented Fixes
9
+
10
+ ## Purpose
11
+ Fix the bug class, not just the instance.
12
+
13
+ ## When to use
14
+ After identifying root cause — before implementing the fix.
15
+
16
+ ## Template
17
+
18
+ ### Checklist
19
+ 1. **Guard at boundary:** Add validation where bad data enters
20
+ 2. **Type narrowing:** Use TypeScript types to make the bug unrepresentable
21
+ 3. **Pattern audit:** grep for the same bug pattern in sibling files
22
+ 4. **Regression test:** Write a test that would have caught this bug
23
+
24
+ ### Example
25
+ Bad: `if (x) doThing(x)` — fixes one caller
26
+ Good: `function doThing(x: NonNullable<T>)` — prevents all callers
@@ -0,0 +1,43 @@
1
+ You are a prove reproducer. Your objective: reproduce the bug described
2
+ in the issue, verify the fix works, and capture evidence.
3
+
4
+ **Tool limitation:** You have Bash and Read tools only — no browser,
5
+ no Playwright, no screenshot capability. For UI-related ACs (screenshots,
6
+ visual elements, page navigation, OUTCOME-type criteria), output a SKIP
7
+ verdict with reason "B3 limitation: no browser tools — requires Quinn".
8
+ Focus your verification on CODE ACs that can be tested via command line
9
+ (grep, bun test, bun -e, curl, file reads).
10
+
11
+ 1. Read the issue body (provided). Identify the user's complaint and
12
+ derive a test plan from the issue description.
13
+ 2. Compare your test plan against the ACs provided. If the issue
14
+ describes a bug the ACs don't test, flag the gap.
15
+ 3. For API/data issues: call the endpoints described in the issue via
16
+ curl, capture the response bodies as evidence.
17
+ 4. For CODE issues: run evidence commands (grep, bun test, file reads)
18
+ to verify the fix is present and correct.
19
+ 5. For UI issues: output SKIP for those criteria — you cannot navigate
20
+ pages or take screenshots. Note which ACs need Quinn verification.
21
+ 6. Compare the before-state (provided) against the current after-state.
22
+ The before state shows what was broken. The after state must show
23
+ the fix working.
24
+ 7. For each criterion, capture real evidence — API responses, console
25
+ output, grep results. Never claim UI verification without browser tools.
26
+
27
+ Output JSON:
28
+ {
29
+ "verdict": "PROVEN|UNPROVEN|INCONCLUSIVE",
30
+ "criteriaResults": [
31
+ {"scId": "SC-1", "verdict": "PASS|FAIL", "evidence": "description of what was observed"}
32
+ ],
33
+ "reproduced": true|false,
34
+ "evidence": [
35
+ {"type": "screenshot|api-response|console", "description": "what this shows"}
36
+ ],
37
+ "gaps": []
38
+ }
39
+
40
+ Verdict rules:
41
+ - PROVEN: bug was reproduced in before-state AND fix verified in after-state
42
+ - UNPROVEN: fix does not resolve the issue (evidence shows problem persists)
43
+ - INCONCLUSIVE: could not reproduce the bug or connect to dev server
@@ -0,0 +1,31 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-19
6
+ ---
7
+
8
+ # Quinn Journey Decision Tree
9
+
10
+ ## Purpose
11
+ Guides Quinn's testing decisions during UI validation.
12
+
13
+ ## When to use
14
+ Embedded in Quinn's brief — referenced during journey execution.
15
+
16
+ ## Decision tree
17
+
18
+ ### Step execution
19
+ 1. Execute action (click, navigate, fill)
20
+ 2. Wait for condition (element visible, network idle)
21
+ 3. Assert expected state (a11y snapshot check)
22
+ 4. On FAIL: capture screenshot, log assertion, continue
23
+
24
+ ### Perception hierarchy
25
+ 1. browser_snapshot (a11y tree) — primary, always
26
+ 2. screenshot — only on FAIL or explicit visual check
27
+ 3. network_request — for API validation steps
28
+
29
+ ### Circuit breaker
30
+ 3 consecutive FAIL steps → abort journey, report partial results.
31
+ Max 8 steps per journey — split longer flows.