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,37 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-08
6
+ ---
7
+
8
+ # Rook Blackburn — Security Review
9
+
10
+ You are Rook Blackburn, security engineer. You scan changed files for vulnerabilities.
11
+
12
+ ## What you scan
13
+
14
+ 1. All files changed in the current branch vs main
15
+ 2. Pattern siblings — files that share imports or data flow with changed files
16
+ 3. Configuration files touched by the change
17
+
18
+ ## What you look for
19
+
20
+ - Injection vulnerabilities (XSS, SQL injection, command injection)
21
+ - Authentication/authorization bypasses
22
+ - Sensitive data exposure (credentials, tokens, PII in logs)
23
+ - Insecure defaults or missing input validation
24
+ - Path traversal in file operations
25
+ - Unsafe deserialization
26
+
27
+ ## How you report
28
+
29
+ - CLEAR or FINDINGS with severity (CRITICAL/HIGH/MEDIUM/LOW)
30
+ - Each finding: file, line, vulnerability type, remediation
31
+ - False positives noted as such with reasoning
32
+
33
+ ## What you do NOT do
34
+
35
+ - Never modify source code — report only
36
+ - Never touch production config files
37
+ - Never run `make rebuild`
@@ -0,0 +1,37 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-08
6
+ ---
7
+
8
+ # Serena Blackwood — Architecture
9
+
10
+ You are Serena Blackwood, software architect. You make structural decisions and write ADRs.
11
+
12
+ ## What you do
13
+
14
+ 1. Evaluate proposed architectural changes against existing ADRs
15
+ 2. Write new ADRs for decisions that don't have one
16
+ 3. Review module boundaries and dependency direction
17
+ 4. Assess scalability, maintainability, and complexity tradeoffs
18
+ 5. Design data flow and integration points
19
+
20
+ ## Architecture principles
21
+
22
+ - Deep modules, thin consumers
23
+ - Single chokepoint for mutations (saveCustomers, saveConfig, etc.)
24
+ - Config-driven over hardcoded
25
+ - Shared logic in lib/, never duplicated across consumers
26
+ - Schema validation at system boundaries
27
+
28
+ ## How you report
29
+
30
+ - ADR document for new decisions
31
+ - APPROVED or CONCERNS for reviews
32
+ - Specific module/file recommendations, not abstract guidance
33
+
34
+ ## What you do NOT do
35
+
36
+ - Never write implementation code — provide architecture specs for Marcus
37
+ - Never run builds, tests, or deployments
@@ -0,0 +1,170 @@
1
+ ---
2
+ name: Council
3
+ description: Multi-round parallel debate with progressive transcript passing for architecture decisions and tradeoff analysis.
4
+ version: 1.1.0
5
+ doc-type: reference
6
+ status: active
7
+ owner: jason
8
+ updated: 2026-09-06
9
+ contract:
10
+ input: "Topic string + optional context + optional governingSpec"
11
+ gateIn: "None — /council is standalone"
12
+ gateOut: "Synthesis with convergencePoints, recommendation, specAlignment, enforcementClassification"
13
+ artifact: "council-synthesis.json at ~/.rungate/{slug}/"
14
+ outputSchema: "schemas/council-synthesis.schema.json"
15
+ telemetry: "harness-telemetry.jsonl with skill=council"
16
+ errorRecovery:
17
+ timeout_seconds: 600
18
+ failure_mode: WARN
19
+ cleanup_action: "None — council is read-only"
20
+ resumable: false
21
+ ---
22
+
23
+ # Council
24
+
25
+ Multi-round parallel debate with progressive transcript passing. Produces convergence-tested synthesis for architecture decisions, tradeoff analysis, and design reviews.
26
+
27
+ ## Interface
28
+
29
+ ```
30
+ /council "topic" — debate with research (default)
31
+ /council "topic" --noResearch — debate without codebase/external research
32
+ /council "topic" --governingSpec PATH — force-read a governing spec before debate
33
+ /council on 306 — debate issue #306 with research
34
+ ```
35
+
36
+ **Research is ON by default.** Phase 0 runs parallel codebase + external research agents before the debate. Use `--noResearch` only for pure opinion/tradeoff debates with no codebase context needed.
37
+
38
+ **Governing spec (#309):** When `--governingSpec` is passed, the research agent reads that spec FIRST and extracts all design decisions. Council members must align with the spec or explicitly argue for amendment. Synthesis includes `specAlignment` field.
39
+
40
+ **Invocation:** Always use `scriptPath` to get the latest version:
41
+ ```
42
+ Workflow({ scriptPath: "~/.claude/workflows/council.js", args: { topic, governingSpec, ... } })
43
+ ```
44
+
45
+ ## Trigger conditions
46
+
47
+ - When: `/council`, "run a council", "debate this", "get multiple perspectives"
48
+ - Standalone: yes — can run at any point in the harness chain
49
+ - Chain position: lateral (any point) — does not block or advance the main chain
50
+ - Skip when: single-option decisions, trivial config changes, already-decided ADRs
51
+
52
+ ## Workflow
53
+
54
+ ### Step 1 — Frame the question
55
+
56
+ **The DA frames the question as a PROBLEM, not a PLAN.** This is the single highest-leverage decision in the entire council process.
57
+
58
+ Bad: "Here are 7 issues. Is this right-sized?" → council can only say "fewer" or "more"
59
+ Good: "Bash gates still run despite migration declared complete. How should we fix this?" → council proposes solutions
60
+
61
+ **Briefing rules (mandatory):**
62
+
63
+ 1. **Problem, not plan.** Give the council the failure/gap/decision. Do NOT give them your proposed solution. When you hand them a plan, they evaluate. When you hand them a problem, they think. If you already have a plan, describe the PROBLEM the plan is trying to solve, not the plan itself.
64
+
65
+ 2. **Code-first, not authority-first.** Include in the brief: "Positions must cite specific file:line numbers from the codebase. Do not cite Fowler, Larson, Brooks, or industry patterns as primary evidence — reason from THIS code. External patterns may support a code-grounded argument but cannot replace one." Without this, council members pattern-match against authorities instead of reading the actual code.
66
+
67
+ 3. **Include a premise-challenger.** One council member must be briefed: "Your job is to argue we should NOT do this at all. What's the case for the opposite direction? What's the simplest fix that avoids the proposed work entirely? What assumptions is everyone else making that might be wrong?" This role must be explicitly assigned — without it, all members optimize within the same frame.
68
+
69
+ 4. **Constrain the output toward simplicity.** Add one of: "Your recommendation must result in fewer total lines of code than exist today" or "The simplest fix wins — justify every line you add" or "What can we DELETE instead of building?" Without a simplicity constraint, councils default to adding — more checks, more enforcement, more architecture.
70
+
71
+ 5. **Ask one hard question about the code.** Not "should we port convergence.sh?" but "convergence.sh is 66 lines of state machine logic. Is this logic necessary? What breaks if we delete it entirely?" Force members to evaluate whether complexity should be ported or eliminated.
72
+
73
+ 6. **No plan-shaped questions.** Questions like "Is 7 issues the right number?" or "Should #307 be a dependency?" presuppose the plan structure. Instead: "What is the minimum change that prevents this failure from recurring?"
74
+
75
+ **Anti-patterns in council briefs:**
76
+ - Giving 5+ questions (council optimizes for answering questions, not solving problems)
77
+ - Including your proposed issue structure (council evaluates it instead of proposing alternatives)
78
+ - Asking "should we use X?" (binary validation, not design thinking)
79
+ - Omitting file paths (council cites abstractions instead of code)
80
+
81
+ 1. Extract the core PROBLEM from user input — not the user's proposed solution
82
+ 2. Identify relevant context (issue, spec, prior decisions)
83
+ 3. Set round count (default: 3 rounds)
84
+
85
+ ### Step 2 — Spawn parallel debaters
86
+
87
+ 1. Launch 3+ agents with distinct perspectives (e.g., pragmatist, purist, operator)
88
+ 2. **One agent must be a premise-challenger** — briefed to argue against the assumed direction
89
+ 3. Each agent receives: problem statement, file paths to read, role brief
90
+ 4. Round 1: independent analysis (no cross-pollination)
91
+
92
+ ### Step 3 — Progressive rounds
93
+
94
+ 1. After each round, synthesize positions
95
+ 2. Pass synthesis + all transcripts to next round
96
+ 3. Agents respond to each other's arguments
97
+ 4. Track convergence points and persistent disagreements
98
+
99
+ ### Step 4 — Synthesize
100
+
101
+ 1. Identify convergence points (all agents agree)
102
+ 2. Identify persistent disagreements (with each side's strongest argument)
103
+ 3. Generate recommendation with confidence level
104
+ 4. Classify enforcement: behavioral rule, mechanical gate, or advisory
105
+
106
+ ### Step 5 — Log telemetry
107
+
108
+ Append to harness-telemetry.jsonl:
109
+ ```json
110
+ {"ts":"...","skill":"council","issue":0,"check":"synthesis","result":"COMPLETE","duration_ms":120000}
111
+ ```
112
+
113
+ ### Artifact Output
114
+
115
+ After synthesis is complete, the council produces a structured artifact:
116
+
117
+ 1. The council workflow returns a synthesis object matching `council-synthesis.schema.json`
118
+ 2. Key addition from ADR-007: the `decisions[]` array with structured tracking:
119
+ ```json
120
+ {
121
+ "id": "D-001",
122
+ "statement": "Use file presence for chain detection, not env vars",
123
+ "target": {"type": "adr", "ref": "~/.claude/PAI/ADR/ADR-007-universal-skill-contract.md", "section": "Chain Detection"},
124
+ "disposition": "ACCEPTED",
125
+ "correlationTags": ["chain-detection", "file-presence"],
126
+ "phase": "Phase 2b-B"
127
+ }
128
+ ```
129
+ 3. Every convergence point and recommendation becomes a decision entry
130
+ 4. Post-council, run `decision-reconcile.sh` against the target document to verify all decisions made it into the doc
131
+
132
+ ### Decision Tracking
133
+
134
+ After any council session that produces decisions targeting a specific document:
135
+
136
+ 1. Save synthesis as `~/.rungate/{slug}/council-synthesis.json`
137
+ 2. Run: `bash ~/.claude/scripts/decision-reconcile.sh ~/.rungate/{slug}/council-synthesis.json --target <doc-path>`
138
+ 3. If MISSING count > 0: patch the document before presenting results
139
+ 4. Report: "N decisions, N captured, M dropped" — the count forces accountability
140
+
141
+ ### Research Mode with Performance Data
142
+
143
+ When council is invoked with `--research` or for skill improvement decisions, performance profiles from AgentGrit feed into the council context:
144
+
145
+ 1. Load all performance profiles from `~/agentgrit/data/profiles/*.json`
146
+ 2. Format as evidence table for council members:
147
+ ```
148
+ Skill Performance Profiles (last 30 days):
149
+ | Skill | Execs | Hit Rate | Gap Rate | Iterations | Trend |
150
+ | prove | 47 | 82% | 18% | 1.3 | improving |
151
+ | ship | 89 | 95% | 5% | 2.1 | stable |
152
+ ```
153
+ 3. Council members receive profiles as part of their context — decisions are data-backed
154
+ 4. If no profiles exist (AgentGrit not yet producing): council proceeds without, notes data gap
155
+
156
+ ### Data-Driven Contract Updates
157
+
158
+ When council recommends a skill contract change:
159
+ 1. The recommendation includes the performance data that motivated it
160
+ 2. Example: "prove gapRate 18% on UI issues → add screenshot SC requirement to prove contract"
161
+ 3. The change is tracked as a decision with `correlationTag: "performance-driven"`
162
+ 4. Post-implementation: Learn phase captures new data → profiles update → next audit verifies improvement
163
+
164
+ ## Error handling
165
+
166
+ - Timeout: 600 seconds total
167
+ - Per-agent timeout: 180 seconds
168
+ - On agent timeout: proceed with available responses
169
+ - On all agents timeout: return partial synthesis with WARN
170
+ - Not resumable — re-run produces fresh debate
@@ -0,0 +1,235 @@
1
+ ---
2
+ name: Goal
3
+ description: Mandatory first step of the harness loop — decomposes goals into measurable GitHub issues with garbage-tested ACs.
4
+ version: 1.0.0
5
+ doc-type: reference
6
+ status: active
7
+ owner: jason
8
+ updated: 2026-09-06
9
+ contract:
10
+ input: "Observation, screenshot, verbal description, email, or link from user"
11
+ gateIn: "None — /goal is the chain entry point"
12
+ gateOut: "GitHub issue exists with measurable ACs + beforeState captured"
13
+ artifact: "GitHub issue + workflow-state.json with issueGoal, ACs, beforeState"
14
+ outputSchema: "schemas/goal-record.schema.json"
15
+ telemetry: "harness-telemetry.jsonl with skill=goal"
16
+ errorRecovery:
17
+ timeout_seconds: 300
18
+ failure_mode: BLOCK
19
+ cleanup_action: "Close draft issue if created"
20
+ resumable: true
21
+ ---
22
+
23
+ # Goal
24
+
25
+ The mandatory first step of the PAI agentic harness loop. Every implementation task starts here — no exceptions.
26
+
27
+ Read `PAI/HARNESS-STANDARD.md` for how this skill fits into the full loop.
28
+
29
+ ## Trigger conditions
30
+
31
+ - When: `/goal`, "I want to...", "we need to...", "fix this...", any new implementation request
32
+ - Standalone: yes — always the first skill in the chain
33
+ - Chain position: start (entry point)
34
+ - Skip when: issue already exists with ACs (use Mode 3 to validate)
35
+
36
+ ## Workflow
37
+
38
+ See Three Entry Modes below for the full workflow per mode.
39
+
40
+ ## Three Entry Modes
41
+
42
+ The DA determines which mode applies, then follows that mode's process.
43
+
44
+ ### Mode 1: Goal, No Issues
45
+
46
+ **Trigger:** Jason states a goal in natural language and no GitHub issues exist for it yet.
47
+
48
+ **What happens:**
49
+ 1. The DA reads project PRINCIPLES.md pre-flight questions (if the project has one) — these inform goal decomposition
50
+ 2. The goal is decomposed into measurable success criteria (SC-1, SC-2, ...)
51
+ 3. **Garbage test on every SC:** Each SC is tested: "Could garbage data pass this?" If yes, the SC is tightened until the answer is no
52
+ 4. Scope boundary is defined (what's in, what's out)
53
+ 5. Circuit breaker defaults are set (or Jason is consulted if non-default needed):
54
+ - Per-issue: 5 iterations max
55
+ - Per-goal: $20 cost ceiling, 5M token ceiling
56
+ 6. A GitHub issue is created via `gh issue create` using the template below
57
+ 7. A checkpoint is written to `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md`
58
+
59
+ ### Mode 2: Goal, Issues Exist
60
+
61
+ **Trigger:** Jason states a goal and related GitHub issues already exist.
62
+
63
+ **What happens:**
64
+ 1. Existing issues are searched: `gh issue list --repo hornjason/pai-config --state open --search "[keywords]"` (also checks hornjason/asaCommandCenter)
65
+ 2. Each related issue is read — existing scope is understood
66
+ 3. Existing issues are mapped against the goal — which success criteria do they cover?
67
+ 4. Gaps are identified — which criteria have no issue yet?
68
+ 5. Only gap issues are created using the template below
69
+ 6. **Umbrella trigger (mechanical):** If 2+ issues (existing + newly created) map to this goal, an umbrella issue is auto-created:
70
+ - The `decomposed` label is added to the umbrella
71
+ - The goal issue template below is used with an additional `## Children` section:
72
+ ```
73
+ ## Children
74
+ - [ ] #N — [title]
75
+ - [ ] #M — [title]
76
+
77
+ max-children: 8
78
+ ```
79
+ - `Parent: #UMBRELLA` is added to each child issue body at creation time
80
+ - The umbrella's SCs are the aggregate goal; children have decomposed ACs
81
+ - close-gate.sh handles rollup validation (D1: child-refs, D2: children-closed + shipped label, D3: no-orphans, D4: max-children WARN)
82
+ - If only 1 issue maps to the goal, umbrella creation is skipped — single-issue flow unchanged
83
+ 7. A checkpoint is written
84
+
85
+ ### Mode 3: Issue, No Goal
86
+
87
+ **Trigger:** Jason points at a specific issue number ("ship issue #33").
88
+
89
+ **What happens:**
90
+ 1. The issue is read: `gh issue view [number] --repo [repo]`
91
+ 2. ACs are validated against the garbage test — if any AC could be passed by garbage, the DA tightens it
92
+ 3. Standardized structure is checked — if missing sections (Goal, Success Criteria, Scope Boundary, Circuit Breakers), they are added via `gh issue comment`
93
+ 4. Related issues are checked: `gh issue list --search "[keywords]"`
94
+ 5. **Governing Spec Detection:** The skill detects if the issue references a governing spec:
95
+ - The issue body is grepped for `ADR-`, `Governing spec:`, `spec/`, or spec file paths
96
+ - If found: the spec is read, the path is extracted, and it is added to GoalRecord as `governingSpec.path` with `detectedFrom: "issue-body"`
97
+ - If not found: `governingSpec` is omitted from GoalRecord (optional field)
98
+ - When governingSpec is present: each SC traces to a spec claim (or notes "no spec claim — new behavior")
99
+ 6. A checkpoint is written
100
+
101
+ ## Goal Type Classification
102
+
103
+ Before creating output, the goal type is classified using this deterministic decision tree:
104
+
105
+ ```
106
+ Is this a structural/architectural decision?
107
+ YES → Is there an existing ADR for this area?
108
+ YES → type: github-issue (implement against existing ADR)
109
+ NO → type: adr (create ADR first, then issues)
110
+ NO → Is this a multi-issue initiative (L-sized)?
111
+ YES → Is there a clear scope + user value?
112
+ YES → type: prd (create PRD, then decompose to issues)
113
+ NO → type: research-brief (research first, then PRD)
114
+ NO → Is this investigative/exploratory?
115
+ YES → type: research-brief
116
+ NO → type: github-issue (default)
117
+ ```
118
+
119
+ ### Output Types
120
+
121
+ | Type | Output | When | Example |
122
+ |---|---|---|---|
123
+ | `github-issue` | GitHub issue with ACs | Default — most goals | "Fix subject duplication in batch emails" |
124
+ | `adr` | ADR document + GitHub issue for implementation | Structural/architectural decisions with no existing ADR | "How should skills communicate state?" |
125
+ | `prd` | PRD document + decomposed issues | L-sized initiatives with clear scope | "Build campaign UI with real-time preview" |
126
+ | `spec` | Spec document | Defining behavior for an existing system | "Document the skill chain handoff protocol" |
127
+ | `research-brief` | Research output document | Exploratory/investigative goals, unclear scope | "What multi-agent frameworks handle chain state?" |
128
+
129
+ ### Routing Rules
130
+
131
+ - **`github-issue` (default):** Follows existing Mode 1/2/3 workflow. GoalRecord `artifactRef.type` = "github-issue".
132
+ - **`adr`:** The ADR is written to `PAI/ADR/ADR-NNN-{slug}.md` using ADR template. A GitHub issue is created for Phase 1 implementation. GoalRecord `artifactRef.type` = "adr", `artifactRef.locator` = ADR file path.
133
+ - **`prd`:** The PRD is created via `Skill("to-prd")`. Decomposition happens via `Skill("to-issues")`. GoalRecord `artifactRef.type` = "prd", `artifactRef.locator` = PRD issue number.
134
+ - **`spec`:** The spec is written to `PAI/specs/{name}.md`. GoalRecord `artifactRef.type` = "spec", `artifactRef.locator` = spec file path.
135
+ - **`research-brief`:** Research agent(s) are spawned. Output goes to `~/.rungate/{slug}/research-output.json`. GoalRecord `artifactRef.type` = "research-brief", `artifactRef.locator` = output file path.
136
+
137
+ ### Phase Note
138
+
139
+ Phase 3b defines the classification and routing rules. The actual implementation of non-issue output types (ADR writing, PRD creation, spec templates) is handled by existing skills (`to-prd`, `to-issues`) or future work. The decision tree ensures consistent classification from day one.
140
+
141
+ ## GitHub Issue Template
142
+
143
+ Every issue produced by this skill uses this structure. Posted as issue body (Mode 1) or as a structured comment (Mode 3 enrichment):
144
+
145
+ ```markdown
146
+ ## Goal
147
+ [Jason's words, verbatim — or issue's original description]
148
+
149
+ ## Success Criteria
150
+ - [ ] SC-1: [measurable, garbage-tested — specific numbers, not "exists" or "works"]
151
+ - [ ] SC-2: [measurable, garbage-tested]
152
+ - [ ] SC-A1: [anti-criterion — must NOT happen]
153
+
154
+ ## Scope Boundary
155
+ - In: [explicit list of what this covers]
156
+ - Out: [explicit list of what this does NOT cover]
157
+
158
+ ## Circuit Breakers
159
+ - Per-issue: 5 iterations max (override: [N])
160
+ - Per-goal: $20 cost ceiling (override: [$N])
161
+ - Per-goal: 5M token ceiling (override: [NM])
162
+
163
+ ## Related Issues
164
+ - #N — [open/closed] — [how it relates to this goal]
165
+ ```
166
+
167
+ ## Quality Bar
168
+
169
+ The skill does not exit until ALL of the following are true. The gate enforces these mechanically:
170
+ - [ ] Every SC passes the garbage test
171
+ - [ ] Scope boundary has at least one "In" and one "Out" item
172
+ - [ ] Circuit breakers are set (defaults or overrides)
173
+ - [ ] Related issues searched and listed (even if none found — state "none found")
174
+ - [ ] GitHub issue created or enriched
175
+ - [ ] Checkpoint written to `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md`
176
+
177
+ ## What This Skill Does NOT Do
178
+
179
+ - Does NOT size the work — sizing happens in Ship SCOPE (PLANNING step)
180
+ - Does NOT read project docs for context — that's DISCOVERY
181
+ - Does NOT write code or run tests — that's EXECUTION
182
+ - Does NOT decompose L-sized work into vertical slices — that's `Skill("to-issues")`
183
+
184
+ ### Before-state capture
185
+
186
+ After the issue is created, the current state of the bug/feature area is captured in workflow-state.json:
187
+
188
+ - `beforeState.type`: text | screenshot | api | none
189
+ - `beforeState.path`: file path to captured evidence
190
+ - `beforeState.capturedAt`: ISO timestamp
191
+
192
+ For LIGHT tier, `type: "none"` is acceptable. /prove reads beforeState for before/after comparison.
193
+
194
+ **Test baseline (#483):** If rungate.json has a `testCmd`, the DA runs it at goal time and captures pass/fail counts in `beforeState.testBaseline`:
195
+ ```json
196
+ "testBaseline": {
197
+ "command": "bun test --isolate test/unit/",
198
+ "pass": 47,
199
+ "fail": 7,
200
+ "capturedAt": "2026-09-11T..."
201
+ }
202
+ ```
203
+ Ship gate uses this to distinguish pre-existing failures from regressions — a test count INCREASE in fails is a regression; same or fewer fails is pre-existing. Gate comparison implementation tracked separately.
204
+
205
+ ### Artifact Output
206
+
207
+ After the GitHub issue is created and before-state is captured, the GoalRecord artifact is written:
208
+
209
+ 1. `~/.rungate/{slug}/goal-record.json` is created with:
210
+ ```json
211
+ {
212
+ "contractVersion": "1.0",
213
+ "id": "issue-{N}",
214
+ "goalStatement": "[issueGoal verbatim]",
215
+ "successCriteria": [/* SCs from issue, each with id, assertion, evidenceType, threshold */],
216
+ "scopeBoundary": {"in": [...], "out": [...]},
217
+ "artifactRef": {"type": "github-issue", "locator": "owner/repo#N"}
218
+ }
219
+ ```
220
+ 2. Validation runs via Zod schema — `writeWorkflowState()` in `gates/orchestrator.ts` validates at write time.
221
+ 3. If validation fails, the error lists valid enum values — fix and re-write. The skill blocks handoff on invalid artifacts.
222
+
223
+ ## Handoff
224
+
225
+ After this skill completes, the harness proceeds to DISCOVERY (built into Ship SCOPE):
226
+ - **Output:** GitHub issue number + checkpoint path
227
+ - **Next step:** Project docs are read (PRINCIPLES.md -> ARCHITECTURE.md -> PROJECT-STATE.md)
228
+
229
+ ## Termination Criteria
230
+
231
+ This skill terminates when:
232
+ 1. A GitHub issue exists with all template sections populated
233
+ 2. All SCs pass the garbage test
234
+ 3. Checkpoint is written
235
+ 4. Control returns to the harness for DISCOVERY