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.
- package/.claude/agents/aditi.md +47 -0
- package/.claude/agents/marcus.md +50 -0
- package/.claude/agents/quinn.md +58 -0
- package/.claude/agents/rook.md +47 -0
- package/.claude/agents/serena.md +46 -0
- package/.claude/rungate.json +11 -0
- package/.fallowrc.json +28 -0
- package/.github/copilot-instructions.md +20 -0
- package/.rungate/conformity-findings.json +648 -0
- package/AGENTS.md +106 -0
- package/CODE-MAP.md +50 -0
- package/HARNESS.md +88 -0
- package/bun.lock +26 -0
- package/bunfig.toml +2 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +212 -0
- package/config/consumer-cascade-map.json +24 -0
- package/config/doc-cascade-map.json +24 -0
- package/config/eval.json +84 -0
- package/config/profiles/account-plan.yaml +36 -0
- package/config/profiles/campaign.yaml +94 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/workflow-schema.json +281 -0
- package/gates/SCHEMA-GUIDE.md +121 -0
- package/gates/ac-quality.test.ts +106 -0
- package/gates/adversarial.test.ts +274 -0
- package/gates/brief-assembler.test.ts +429 -0
- package/gates/brief-assembler.ts +334 -0
- package/gates/bunfig.toml +2 -0
- package/gates/chain.test.ts +91 -0
- package/gates/e2e-smoke.test.ts +234 -0
- package/gates/error-classifier.test.ts +249 -0
- package/gates/error-classifier.ts +89 -0
- package/gates/orchestrator.test.ts +950 -0
- package/gates/orchestrator.ts +569 -0
- package/gates/preload.ts +77 -0
- package/gates/prompts/ac-adversary.md +20 -0
- package/gates/prompts/evidence-validator.md +22 -0
- package/gates/prompts/prove-reproducer.md +53 -0
- package/gates/prove.test.ts +164 -0
- package/gates/run-gate.ts +936 -0
- package/gates/schema-parity.test.ts +197 -0
- package/gates/schema.ts +362 -0
- package/gates/self-heal.test.ts +511 -0
- package/gates/self-heal.ts +121 -0
- package/gates/ship-orchestrator.test.ts +379 -0
- package/gates/ship-orchestrator.ts +363 -0
- package/gates/test-fixtures/broken-no-environments.json +60 -0
- package/gates/test-fixtures/valid-standard.json +54 -0
- package/gates/test-utils.ts +43 -0
- package/gates/witness.ts +220 -0
- package/gates/workflow.test.ts +1053 -0
- package/hooks/AgentBriefGuard.hook.ts +586 -0
- package/hooks/AgentVerdictCapture.hook.ts +134 -0
- package/hooks/AutoVerifyGate.hook.ts +76 -0
- package/hooks/GateEnforcement.hook.ts +273 -0
- package/hooks/IssueCloseGuard.hook.ts +116 -0
- package/hooks/MergeGuard.hook.ts +55 -0
- package/hooks/StaleTTLCleanup.hook.ts +133 -0
- package/hooks/VerifyPhaseLock.hook.ts +81 -0
- package/hooks/WorkflowStateGuard.hook.ts +37 -0
- package/hooks/lib/agentDetection.ts +70 -0
- package/hooks/lib/findWorkflow.ts +101 -0
- package/hooks/lib/parseStdin.ts +37 -0
- package/hooks/lib/paths.ts +111 -0
- package/hooks/lib/utils.ts +81 -0
- package/lib/conformity.ts +959 -0
- package/lib/paths.ts +23 -0
- package/lib/rungate-schema.ts +60 -0
- package/lib/signal-phrases.ts +7 -0
- package/package.json +20 -0
- package/prompts/ac-adversary.md +20 -0
- package/prompts/ac-format.md +34 -0
- package/prompts/aditi.md +29 -0
- package/prompts/blast-radius.md +29 -0
- package/prompts/coding-principles.md +34 -0
- package/prompts/container-rebuild.md +29 -0
- package/prompts/container-verify.md +28 -0
- package/prompts/discovery.md +27 -0
- package/prompts/environment.md +28 -0
- package/prompts/escalation-decision-tree.md +38 -0
- package/prompts/evidence-hierarchy.md +31 -0
- package/prompts/evidence-validator.md +22 -0
- package/prompts/marcus.md +29 -0
- package/prompts/prevention.md +26 -0
- package/prompts/prove-reproducer.md +43 -0
- package/prompts/quinn-decision-tree.md +31 -0
- package/prompts/quinn-ui-brief.md +106 -0
- package/prompts/quinn.md +29 -0
- package/prompts/rca.md +28 -0
- package/prompts/read-before-write.md +30 -0
- package/prompts/regression.md +26 -0
- package/prompts/rook.md +29 -0
- package/prompts/serena.md +28 -0
- package/prompts/testing-strategy.md +34 -0
- package/reference/migration-manifest.json +554 -0
- package/reference/prompts/agent-aditi.md +38 -0
- package/reference/prompts/agent-marcus.md +38 -0
- package/reference/prompts/agent-quinn.md +38 -0
- package/reference/prompts/agent-rook.md +37 -0
- package/reference/prompts/agent-serena.md +37 -0
- package/reference/prompts/council-skill.md +170 -0
- package/reference/prompts/goal-skill.md +235 -0
- package/reference/prompts/prove-skill.md +283 -0
- package/reference/prompts/quinn-standard.md +246 -0
- package/reference/prompts/ship-convergence.md +65 -0
- package/reference/prompts/ship-escalation.md +43 -0
- package/reference/prompts/ship-iteration.md +382 -0
- package/reference/prompts/ship-pending-patches.md +246 -0
- package/reference/prompts/ship-reference.md +250 -0
- package/reference/prompts/ship-skill.md +347 -0
- package/reference/prompts/ship-templates.md +215 -0
- package/reference/scripts/batch-status.sh +68 -0
- package/reference/scripts/chain-compat-check.sh +67 -0
- package/reference/scripts/context-audit.sh +314 -0
- package/reference/scripts/dead-export-check.sh +61 -0
- package/reference/scripts/generate-qc-tables.sh +92 -0
- package/reference/scripts/harness-init.sh +111 -0
- package/reference/scripts/pai-054-baseline-check.sh +40 -0
- package/reference/scripts/prove-smoke-test.sh +112 -0
- package/reference/scripts/setup-keychain-salt.sh +12 -0
- package/reference/scripts/skill-optimizer-friday.sh +88 -0
- package/reference/scripts/skill-qc-test.sh +351 -0
- package/reference/scripts/skill-synthesize-tonight.sh +66 -0
- package/reference/specs/HARNESS-EXTRACTION-SPEC.md +263 -0
- package/reference/specs/harness-v3-bash-deletion-plan.md +65 -0
- package/reference/specs/harness-v3-migration-plan.md +188 -0
- package/scripts/decision-reconcile.sh +74 -0
- package/scripts/decision-reconcile.ts +152 -0
- package/scripts/extract-constraints.ts +260 -0
- package/scripts/generate-code-map.ts +339 -0
- package/scripts/git-hooks/pre-commit +76 -0
- package/scripts/git-hooks/pre-push +271 -0
- package/scripts/harness-skill-check.sh +52 -0
- package/scripts/lib/gap-emit.sh +65 -0
- package/scripts/lib/jq-update.sh +30 -0
- package/scripts/lib/resolve-slug.sh +30 -0
- package/scripts/lib/verify-spec-compliance.sh +102 -0
- package/scripts/prove-backfill.sh +87 -0
- package/scripts/scaffold-project.ts +1488 -0
- package/scripts/scaffold-rungate-config.ts +91 -0
- package/scripts/self-containment-check.sh +109 -0
- package/scripts/skill-qc-validator.sh +402 -0
- package/scripts/slug-resolver.sh +14 -0
- package/scripts/sync-spec-tests.ts +236 -0
- package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +2493 -0
- package/specs/BOOTSTRAP-TEST-PLAN.md +571 -0
- package/specs/HARNESS-GATES.md +256 -0
- package/specs/HARNESS-SKILL-CHAIN.md +286 -0
- package/specs/HARNESS-SKILL-CONTRACT.md +93 -0
- package/specs/HARNESS-STANDARD.md +488 -0
- package/specs/SPEC-TEMPLATE.md +53 -0
- package/specs/bootstrap-data-flow.png +0 -0
- package/specs/harness-automation-matrix.md +314 -0
- package/specs/harness-automation-matrix.rules.json +64 -0
- package/test/anti.test.ts +80 -0
- package/test/contract-negative.test.ts +86 -0
- package/test/contract.test.ts +158 -0
- package/test/external-deps.test.ts +48 -0
- package/test/fixtures/golden-project/.env.example +3 -0
- package/test/fixtures/golden-project/Makefile +7 -0
- package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +23 -0
- package/test/fixtures/golden-project/docs/setup-guide.md +10 -0
- package/test/fixtures/golden-project/package.json +10 -0
- package/test/fixtures/golden-project/specs/api-spec.md +20 -0
- package/test/fixtures/golden-project/src/auth.ts +8 -0
- package/test/fixtures/golden-project/src/db.ts +11 -0
- package/test/fixtures/golden-project/src/index.ts +19 -0
- package/test/fixtures/golden-project/src/utils/format.ts +3 -0
- package/test/fixtures/golden-project/test/auth.test.ts +15 -0
- package/test/fixtures/golden-project/tsconfig.json +12 -0
- package/test/meta-sc-coverage.test.ts +159 -0
- package/test/phase-0.test.ts +846 -0
- package/test/phase-1.test.ts +617 -0
- package/test/phase-2.test.ts +620 -0
- package/test/phase-3.test.ts +99 -0
- package/test/scaffold-conformity.test.ts +8 -0
- package/test/schema-canary.test.ts +51 -0
- package/test/spec-compliance-auto.test.ts +64 -0
- package/test/spec-compliance.test.ts +295 -0
- package/test/spec-discovery.test.ts +68 -0
- package/test/spec-drift.test.ts +5 -0
- package/test/structure.test.ts +165 -0
- package/test/unit/agent-brief-guard-ship.test.ts +293 -0
- package/test/unit/extract-constraints.test.ts +145 -0
- package/test/unit/issue-close-guard.test.ts +204 -0
- package/test/unit/scaffold-project.test.ts +417 -0
- package/test/unit/skill-cooccurrence.test.ts +177 -0
- package/test/unit/skill-sequence-logger.test.ts +244 -0
- package/test/unit/workflow-state-guard.test.ts +95 -0
- package/workflows/batch-ship.js +295 -0
- package/workflows/council.js +481 -0
- package/workflows/prove.js +560 -0
- package/workflows/ship.js +789 -0
- 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.
|
package/prompts/aditi.md
ADDED
|
@@ -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.
|