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,488 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-08-06
6
+ testable: true
7
+ ---
8
+
9
+ # PAI Agentic Harness Standard
10
+ # Version 1.0 | 2026-06-19
11
+
12
+ Every issue follows the same loop. No improvisation. Each step invokes a skill or is handled by hooks. The standard defines WHAT is invoked, WHEN, and WHAT artifact each step produces.
13
+
14
+ **Governing principle:** Determinism through architecture, not models. Every step is a skill invocation or a mechanical check — never "remember to do X."
15
+
16
+ **AFK autonomy rule:** Once the harness plan receives Jason's approval, execute autonomously with **zero `AskUserQuestion` interruptions**. The DA makes all judgment calls — approach selection, cleanup scope, agent routing, ordering. The only acceptable interruptions are: (1) a circuit breaker firing, (2) a destructive action on shared state (force push, production deploy, data deletion), (3) the final completion report. "Which option do you prefer?" mid-execution is a harness violation — the DA was hired to make those calls.
17
+
18
+ **Relationship to other docs:**
19
+ - **Algorithm v3.7.0** — orchestrates work selection and ISC decomposition. The Algorithm invokes the FULL harness starting at GOAL (not just ship). The Algorithm selects WHICH issue to work; the harness defines HOW to work it.
20
+ - **Ship SKILL.md** — implements EXECUTION and VERIFICATION. This standard wraps ship with the surrounding steps (GOAL, DISCOVERY, RESEARCH, ITERATION, FEEDBACK).
21
+ - **ADR-039** — defines convergence loop architecture. This standard operationalizes it.
22
+
23
+ ---
24
+
25
+ ## The Loop
26
+
27
+ ```
28
+ GOAL → DISCOVERY → RESEARCH → PLANNING → EXECUTION → VERIFICATION → ITERATION → FEEDBACK
29
+ ▲ │
30
+ └───────────────────────── (loop back on failure) ──────────────────────┘
31
+ ```
32
+
33
+ ```mermaid
34
+ flowchart TD
35
+ GOAL["0. GOAL<br/>Skill: goal<br/>Capture · decompose · garbage-test<br/>GitHub issue + checkpoint"] --> DISCOVERY
36
+
37
+ DISCOVERY["1. DISCOVERY<br/>Built into Ship SCOPE<br/>Read: PRINCIPLES · ARCHITECTURE · PROJECT-STATE<br/>Read: checkpoint · FAILURES/<br/>Post structured comment to issue"] --> RESEARCH
38
+
39
+ RESEARCH{"2. RESEARCH<br/>Unknowns?"}
40
+ RESEARCH -->|Yes| RESEARCH_STEP["2a. RESOLVE<br/>Context7 MCP first (10s)<br/>Then Skill: Research<br/>Max 1 cycle per issue<br/>Findings posted to issue"]
41
+ RESEARCH -->|No| PLANNING
42
+ RESEARCH_STEP --> PLANNING
43
+
44
+ PLANNING["3. PLANNING<br/>XS/S: ACs → post to issue<br/>M: Skill: grill-with-docs → ACs<br/>L: grill → to-prd → council → to-issues<br/>Marcus brief from BRIEF-TEMPLATES.md"]
45
+ PLANNING --> EXECUTION
46
+
47
+ EXECUTION["4. EXECUTION<br/>Skill: ship BUILD step<br/>├ Route: local · remote · container<br/>├ Skill: tdd (red-green-refactor)<br/>├ Marcus builds (worktree or direct)<br/>├ Skill: simplify · fallow · architecture check<br/>└ Deploy: project CLAUDE.md command"]
48
+
49
+ BASELINE_CHECK{"Step 0:<br/>Baseline drift >20%?"}
50
+ EXECUTION --> BASELINE_CHECK
51
+ BASELINE_CHECK -->|"YES — drift detected"| GOAL_AUDIT
52
+ BASELINE_CHECK -->|"NO — baselines valid"| VERIFICATION
53
+
54
+ VERIFICATION["5. VERIFICATION<br/>Default-FAIL — evidence required<br/>├ Every AC checked with evidence<br/>├ Full test suite (unit + integration)<br/>├ Quinn UI (if .tsx changed)<br/>├ Rook security (if M+)<br/>├ Consumer contract (if consumer changed)<br/>├ Goal statement check<br/>└ Docs cascade check"]
55
+ VERIFICATION --> RESULT
56
+
57
+ RESULT{"All gates<br/>pass?"}
58
+ RESULT -->|Yes| FEEDBACK
59
+ RESULT -->|No| STUCK
60
+
61
+ STUCK{"6. ITERATION<br/>Stuck detection"}
62
+ STUCK -->|"Same error 3x"| GOAL_AUDIT
63
+ STUCK -->|"Making progress"| DISCOVERY
64
+ STUCK -->|"Budget exhausted"| STOP["STOP<br/>Checkpoint + notify"]
65
+
66
+ GOAL_AUDIT{"Goal Audit<br/>Baseline valid?"}
67
+ GOAL_AUDIT -->|"T1: Drift >20%<br/>T2: Entity missing<br/>T3: Research contradicts"| GOAL_RESPONSE
68
+ GOAL_AUDIT -->|"Baselines valid"| CIRCUIT["CIRCUIT BREAK"]
69
+
70
+ GOAL_RESPONSE{"Size-gated<br/>response"}
71
+ GOAL_RESPONSE -->|"XS/S"| STOP
72
+ GOAL_RESPONSE -->|"M: DA amends ACs"| DISCOVERY
73
+ GOAL_RESPONSE -->|"L: Council reviews GOAL"| COUNCIL_GOAL["Skill: council<br/>Goal-Level Review<br/>Revise · Investigate · Abort"]
74
+ COUNCIL_GOAL --> DISCOVERY
75
+
76
+ CIRCUIT --> DECIDE
77
+ DECIDE{"Decision tree"}
78
+ DECIDE -->|"Framework issue"| CTX7["Context7 → retry"]
79
+ DECIDE -->|"Need info"| SPAWN_RESEARCH["Skill: Research<br/>→ new issue if unresolved"]
80
+ DECIDE -->|"1-2 attempts failed"| ESCALATE["Escalate to specialist<br/>Marcus · Quinn · Rook"]
81
+ DECIDE -->|"Structural replan"| COUNCIL["Skill: council<br/>4 agents · 3 rounds<br/>before new direction"]
82
+
83
+ CTX7 --> DISCOVERY
84
+ SPAWN_RESEARCH --> DISCOVERY
85
+ ESCALATE --> DISCOVERY
86
+ COUNCIL --> DISCOVERY
87
+
88
+ FEEDBACK["7. FEEDBACK<br/>├ Signal capture → ratings.jsonl<br/>├ Correction capture → memories<br/>├ Checkpoint marked complete<br/>├ Docs cascade verified<br/>├ Close issue with evidence<br/>└ Follow-ups logged to backlog"]
89
+ FEEDBACK --> NIGHTLY
90
+
91
+ NIGHTLY["NIGHTLY (automatic)<br/>MemoryLoop.sh @ 23:30<br/>├ RuleTracker → rule-stats.json<br/>├ LearningReview → propose rules<br/>├ GraphBuilder → knowledge graph<br/>└ RecallEvaluator → recall@5"]
92
+ NIGHTLY --> WEEKLY
93
+
94
+ WEEKLY["WEEKLY (DA runs)<br/>optimize-rules workflow<br/>├ Mine signals · adversarial verify<br/>├ AskUserQuestion checkboxes<br/>└ Apply approved changes"]
95
+ WEEKLY -.->|"System learns"| DISCOVERY
96
+
97
+ style GOAL fill:#e1f5fe
98
+ style FEEDBACK fill:#c8e6c9
99
+ style VERIFICATION fill:#e8f5e9
100
+ style NIGHTLY fill:#f3e5f5
101
+ style WEEKLY fill:#f3e5f5
102
+ style STOP fill:#ffcdd2
103
+ style BASELINE_CHECK fill:#e8f5e9
104
+ style GOAL_AUDIT fill:#fff3e0
105
+ style COUNCIL_GOAL fill:#fff3e0
106
+ style COUNCIL fill:#fff3e0
107
+ ```
108
+
109
+ ---
110
+
111
+ ## 0. GOAL — `Skill("goal")`
112
+
113
+ **Purpose:** Capture the goal, decompose into measurable criteria, persist to GitHub issue.
114
+
115
+ **Three entry modes:**
116
+
117
+ | Mode | Trigger | Goal skill behavior |
118
+ |---|---|---|
119
+ | **Goal, no issues** | Jason states a goal in natural language | Read project PRINCIPLES.md pre-flight questions to inform decomposition → Decompose → garbage-test each criterion → `gh issue create` |
120
+ | **Goal, issues exist** | Jason states a goal + related issues already open | `gh issue list` → map existing issues against goal → create only gap issues |
121
+ | **Issue, no goal** | Jason points at a specific issue number | Read issue → validate ACs meet garbage test → enrich if needed |
122
+
123
+ **Outputs (MANDATORY — skill does not exit without these):**
124
+ - GitHub issue with standardized body:
125
+ ```
126
+ ## Goal
127
+ [Jason's words, verbatim]
128
+
129
+ ## Success Criteria
130
+ - [ ] SC-1: [measurable, garbage-tested]
131
+ - [ ] SC-2: [measurable, garbage-tested]
132
+
133
+ ## Scope Boundary
134
+ - In: [explicit]
135
+ - Out: [explicit]
136
+
137
+ ## Circuit Breakers
138
+ - Per-issue: [N iterations max]
139
+ - Per-goal: [token/cost ceiling or "all issues closed/deferred"]
140
+
141
+ ## Baseline Values
142
+ - SC-1 baseline: [the quantity or entity this SC measures against] Source: [where this number comes from]
143
+ - SC-2 baseline: [same]
144
+ These values are the Goal Audit comparison targets. Every AC with a numeric threshold
145
+ must state its denominator and source. M/L mandatory, XS/S optional.
146
+
147
+ ## Related Issues
148
+ - #N — [status] — [how it relates]
149
+ ```
150
+ - Checkpoint written to `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md`
151
+
152
+ **Quality bar:** Every success criterion passes the garbage test ("Could garbage data pass this?"). If yes, tighten until no. Every AC with a numeric threshold must state its denominator ("download 80% of N items where N = [source]").
153
+
154
+ **Handoff to DISCOVERY:** GitHub issue number + checkpoint path.
155
+
156
+ ---
157
+
158
+ ## 1. DISCOVERY — Built into Ship SCOPE
159
+
160
+ **Purpose:** Load all context needed to size and plan the work.
161
+
162
+ **Process (mechanical — same every time):**
163
+ 1. Read project docs in order: PRINCIPLES.md → ARCHITECTURE.md → PROJECT-STATE.md
164
+ 2. Read the GitHub issue + any linked specs/ADRs
165
+ 3. Read checkpoint if resuming (`$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md`)
166
+ 4. Read `MEMORY/LEARNING/FAILURES/` for prior patterns matching this domain
167
+ 5. Check `gh issue list` for related open issues
168
+
169
+ **Output:** Structured GitHub issue comment posted via `gh issue comment` with:
170
+ - Answer to each quality-bar question below
171
+ - File path + line number citation for every fact
172
+ - Last-modified timestamp for every doc read
173
+ This artifact is durable — it survives context compaction and session boundaries.
174
+
175
+ **Quality bar — must answer ALL of these from docs (not memory):**
176
+ - What exists now? What needs to change? What constraints apply?
177
+ - For scraper/infrastructure work: Where does this run? What auth? What prerequisites? Where does output go?
178
+ - For UI work: Which component? What data feeds it? What consumers read it?
179
+ - If ANY answer is "I don't know" and it's not in the docs → that's a **doc gap**. Log as issue via `gh issue create` immediately. Then either fix the doc gap first or proceed with RESEARCH to find the answer.
180
+
181
+ **Critical rule:** Every fact used in PLANNING and EXECUTION must trace to a doc read during DISCOVERY — never to DA memory. If the DA "knows" something but can't point to the file and line where it's documented, it's not verified. Read the doc or flag the gap.
182
+
183
+ **Handoff to RESEARCH:** List of unknowns (if any). If no unknowns, skip to PLANNING.
184
+
185
+ **Reference:** → Ship SKILL.md "Project docs gate" for the reading order.
186
+
187
+ ---
188
+
189
+ ## 2. RESEARCH — Conditional
190
+
191
+ **Purpose:** Resolve unknowns before planning. Prevent spiraling.
192
+
193
+ **Gate (mechanical checks — no judgment):**
194
+ - `grep -r "api_name\|library_name" src/` returns 0 hits → external API/library not in codebase → YES
195
+ - DISCOVERY quality bar has an unanswered question → YES
196
+ - Framework/library error encountered during prior iteration → YES
197
+ - If ALL checks return NO → skip to PLANNING
198
+
199
+ **Process (strict order — Context7 first, always):**
200
+ 1. **Context7 MCP** (`resolve-library-id` → `query-docs`) — 10 seconds max. Try this FIRST for any framework/library question.
201
+ 2. **Only if Context7 doesn't answer** → `Skill("Research")` with specific question.
202
+ 3. **Max 1 research cycle per issue.** If research doesn't resolve it, the finding becomes "we need more info" — log as a new issue, move on.
203
+
204
+ **Output:** Findings posted to GitHub issue via `gh issue comment`.
205
+
206
+ **Quality bar:** Every unknown from DISCOVERY is either resolved or logged as a separate issue. No unknowns carry forward silently.
207
+
208
+ **Handoff to PLANNING:** Resolved findings. Unresolved unknowns become new issues.
209
+
210
+ **Anti-pattern:** 2+ hours of research without resolution. If this happens, STOP — create an issue for the unknown and move to the next actionable item.
211
+
212
+ **Reference:** → Research SKILL.md for deep research workflows. Context7 MCP for framework docs.
213
+
214
+ ---
215
+
216
+ ## 3. PLANNING — Size-dependent skill chain
217
+
218
+ **Purpose:** Right-size the ceremony. Small work ships fast. Large work gets stress-tested.
219
+
220
+ **Size routing (determined by Ship SCOPE):**
221
+
222
+ | Size | Ceremony | Skills invoked |
223
+ |---|---|---|
224
+ | **XS/S** | Write ACs → post to issue → go to EXECUTION | None — Ship SCOPE handles inline |
225
+ | **M** | Stress-test approach first | `Skill("grill-with-docs")` → ACs → post to issue |
226
+ | **L** | Full planning pipeline | `Skill("grill-with-docs")` → `Skill("to-prd")` → `Skill("council")` (debate the PRD) → `Skill("to-issues")` → each sub-issue re-enters at GOAL |
227
+
228
+ **Output:**
229
+ - ACs posted to GitHub issue via `gh issue comment` (BEFORE execution starts)
230
+ - Marcus brief prepared (from BRIEF-TEMPLATES.md)
231
+ - For L: sub-issues created, each with own ACs
232
+
233
+ **Quality bar:** Every AC has a declared evidence type (code presence, grep absence, screenshot, API response, test pass). Every AC passes the garbage test.
234
+
235
+ **Handoff to EXECUTION:** GitHub issue with ACs + Marcus brief.
236
+
237
+ **Reference:** → Ship REFERENCE.md for AC templates, evidence types, issue templates, garbage test table. → BRIEF-TEMPLATES.md for Marcus brief format.
238
+
239
+ ---
240
+
241
+ ## 4. EXECUTION — `Skill("ship")` BUILD step
242
+
243
+ **Purpose:** Build the thing. TDD. Deploy.
244
+
245
+ **Process (Ship BUILD — same every time):**
246
+
247
+ **Step 0: Execution target routing (from DISCOVERY):**
248
+ Check DISCOVERY's answer to "Where does this run?":
249
+ - **Local** (laptop, this machine) → proceed to step 1 below (Marcus builds locally)
250
+ - **Remote host** (Mac Mini, server, external container) → route through `Skill("infrastructure-and-devops")`:
251
+ 1. Read project CLAUDE.md for the remote host (e.g., "SalesHub scraper runs ONLY on the Mac Mini container")
252
+ 2. Read `reference_mac_mini_ssh` memory (or equivalent) for SSH credentials — `jasonhorn@mini.local`
253
+ 3. SSH to remote host → sync code (`git pull origin main`) → rebuild container → execute the task
254
+ 4. Verify results remotely before returning to VERIFICATION
255
+ 5. DA never types raw SSH commands — always through the infrastructure skill or a standard pattern
256
+ - **Container-only** → read project CLAUDE.md for container deploy command (e.g., `make rebuild`)
257
+
258
+ **Step 1 (local builds only):**
259
+ 1. `Skill("tdd")` — red-green-refactor, vertical slices (exempt: config-only, pure doc, JSON, UI copy)
260
+ 2. Marcus builds — isolation mode is a mechanical check, not memory:
261
+ - Project root under `~/.claude/`? → `isolation: "worktree"`
262
+ - Project root elsewhere? → direct (no worktree)
263
+ 3. Architecture check (M+ only) — `Skill("improve-codebase-architecture")`
264
+ 4. `Skill("simplify")` — 3-agent code review on changed files
265
+ 5. `npx fallow` — static analysis on changed files (unused code, circular deps, duplication, complexity). Zero-token, ~10 sec. Runs for all sizes.
266
+ 5. For M/L iterative work: Marcus works on a feature branch per ADR-039 ("main branch untouched until full convergence"). XS/S may commit to main directly.
267
+ 6. DA merges to main + deploy — read project CLAUDE.md for deploy command. Do not assume any specific deploy command.
268
+ 7. Rollback protocol: every iteration produces one squashed commit on feature branch. Rollback = `git revert`, not `git reset`. Main branch untouched until full convergence (ADR-039 gate 5).
269
+
270
+ **Output:** Code committed, tests passing, deployed to test environment.
271
+
272
+ **Quality bar:** Read project CLAUDE.md for test commands. Tests pass with 0 failures. Code deployed and reachable.
273
+
274
+ **Handoff to VERIFICATION:** List of changed files + deploy confirmation.
275
+
276
+ **Reference:** → Ship SKILL.md BUILD step. → BRIEF-TEMPLATES.md for Marcus brief.
277
+
278
+ ---
279
+
280
+ ## 5. VERIFICATION — Ship VERIFY step + agents
281
+
282
+ **Purpose:** Prove every AC is met with evidence. Default-FAIL — nothing passes without proof.
283
+
284
+ **Process (mechanical — same every time):**
285
+ 0. **Baseline validity check.** For each SC with a Baseline Value, compare against the latest execution observation from structured findings on the issue. If drift exceeds 20%, SKIP AC evaluation and route to ITERATION Goal Audit gate. This prevents false PASS on wrong premises.
286
+ 0.5. **Issue re-read (inherited drift check).** After receiving agent output and before writing the completion report, re-read the GitHub issue body via `gh issue view NUM`. Compare agent output against the original AC text and thresholds on the issue — not conversation memory or the brief's paraphrase. Inherited drift accumulates when the DA evaluates against a stale mental model of the ACs instead of the canonical source. This step costs 5 seconds and prevents false PASS from drift.
287
+ 1. Every AC-N checked against evidence (→ Ship REFERENCE.md evidence types)
288
+ 2. Full test suite: `bun test --isolate test/unit/` AND `bun test test/integration/`
289
+ 3. Tests pass on test env — read project CLAUDE.md for test port (e.g., 7776 for DailyBriefDashboard). Do not assume port.
290
+ 4. If UI change (any `.tsx` file modified) → spawn Quinn (QUINN-STANDARD.md)
291
+ 5. If M+ size → spawn Rook (security scan on changed files)
292
+ 6. If consumer change (read project PRINCIPLES.md consumer list; if any changed file is in consumer list → mandatory) → Consumer 4-layer verification (→ Ship REFERENCE.md)
293
+ 7. Goal statement check (→ `project_application_mission.md`)
294
+ 8. Docs cascade check (→ Ship SKILL.md DURABILITY matrix)
295
+
296
+ **Output:** PASS/FAIL per AC with evidence. Completion report (→ Ship REFERENCE.md template).
297
+
298
+ **Quality bar:** ALL ACs have evidence. ALL tests pass (zero tolerance). Quinn PASS if UI. Rook PASS if M+.
299
+
300
+ **Handoff to ITERATION:** PASS → close issue, go to FEEDBACK. FAIL → enter ITERATION.
301
+
302
+ **Reference:** → Ship SKILL.md VERIFY step. → Ship REFERENCE.md completion report template. → QUINN-STANDARD.md for Quinn protocol.
303
+
304
+ ---
305
+
306
+ ## 6. ITERATION — Convergence + stuck detection
307
+
308
+ **Purpose:** Decide what to do when verification fails. Replan, don't just retry.
309
+
310
+ **Doc hygiene at every iteration boundary (MANDATORY):** Before looping back to DISCOVERY, run `Skill("doc-hygiene")` to verify ARCHITECTURE.md, PROJECT-STATE.md, PRINCIPLES.md, and any relevant ADRs reflect what was learned or changed in the iteration just completed. This is not deferred to FEEDBACK — operational discoveries (e.g., which data directory holds live auth, which env vars are required) rot fastest and must be captured while fresh. If doc-hygiene finds nothing to update, it exits immediately (<5s). The cost of running it is near-zero; the cost of skipping it is a repeat investigation next session.
311
+
312
+ **Deterministic compaction (Extended+ effort):** At every phase transition (DISCOVERY->RESEARCH, RESEARCH->PLANNING, PLANNING->EXECUTION, etc.), run `/compact` if the current effort tier is Extended or higher. This is deterministic — not triggered by a context % threshold. Phase transitions are natural compaction points because the prior phase's tool output is no longer needed verbatim.
313
+
314
+ **Stuck detection (mechanical checks — run every iteration):**
315
+
316
+ | Signal | Detection | Action |
317
+ |---|---|---|
318
+ | Same error 3x | Hash stderr output; trip when any hash appears 3 times | CIRCUIT BREAK |
319
+ | Same tool call 3x | Hash tool name + canonicalized args; trip on 3 matches | CIRCUIT BREAK |
320
+ | Iteration limit hit | Count iterations per issue; compare to circuit breaker in GOAL | CIRCUIT BREAK |
321
+ | Wall clock exceeded | Compare current time to start timestamp in checkpoint | CIRCUIT BREAK |
322
+ | Making progress | At least 1 new AC passed since last iteration | Continue — loop back to DISCOVERY |
323
+
324
+ **Stuck detection storage:** State persists in `$RUNGATE_WORK_DIR/{slug}/stuck-detection.json`:
325
+ ```json
326
+ {
327
+ "iteration_count": 0,
328
+ "start_timestamp": "ISO-8601",
329
+ "stderr_hashes": ["hash1", "hash1", "hash2"],
330
+ "tool_call_hashes": ["hash1", "hash2"],
331
+ "acs_passed_per_iteration": [0, 1, 1],
332
+ "goal_audit_events": [],
333
+ "goal_audit_count": 0,
334
+ "baseline_values": { "SC-1": "54 downloadable items", "SC-2": "80% coverage" }
335
+ }
336
+ ```
337
+ Updated at each iteration boundary. Read at each iteration start. Survives context compaction.
338
+
339
+ **Goal Audit gate (fires after stuck detection, before circuit-break decision tree):**
340
+
341
+ Three mechanical triggers — any one fires the gate:
342
+ - **T1: Numeric baseline drift** — a structured FINDING on the issue shows an SC baseline differs from the measured value by more than 20%
343
+ - **T2: Entity/method non-existence** — a structured FINDING reports an entity, API, or method referenced in an SC does not exist or fails reproducibly (not transiently)
344
+ - **T3: Research contradiction** — a RESEARCH finding posted after GOAL creation contradicts a scope boundary in the issue body
345
+
346
+ Detection runs for ALL sizes (cost: under 10 seconds of grep against issue comments for `FINDING:` patterns).
347
+
348
+ Response is size-gated:
349
+ - **XS/S:** STOP. Notify DA: "SC-N baseline incorrect: assumed [X], measured [Y]. Source: [FINDING comment URL]." DA decides next step.
350
+ - **M:** DA amends ACs on the GitHub issue (strikethrough old values, add new, document rationale via `gh issue comment`). Reset `stderr_hashes` and `tool_call_hashes` in stuck-detection.json. Re-enter at DISCOVERY.
351
+ - **L:** Mandatory council review of the GOAL (not the approach) using Goal-Level Review brief template (→ BRIEF-TEMPLATES.md). Council decides: revise ACs, investigate assumption, or abort.
352
+
353
+ **Meta-circuit-breaker:** Max 2 goal amendments per issue. Third trigger = STOP unconditionally + notify Jason. This counts council-revised goals — the council is not exempt. `goal_audit_count` tracks this.
354
+
355
+ When Goal Audit amends ACs: reset `stderr_hashes` and `tool_call_hashes` (old errors were against wrong criteria). Preserve `iteration_count` (total budget tracking). Add event to `goal_audit_events` array:
356
+ ```json
357
+ { "iteration": 3, "sc_id": "SC-1", "assumed": "54", "measured": "97", "category": "baseline_drift", "outcome": "amended", "timestamp": "ISO-8601" }
358
+ ```
359
+
360
+ **Distinguishing goal invalidity from method unreliability:** If the measured value contradicts the assumed value (54 items is actually 97), it is **baseline drift** — Goal Audit handles it. If the measured value is an error (4xx, timeout, exception), it is **infrastructure** — existing circuit-break path handles it. Do not conflate these.
361
+
362
+ **ADR-039 convergence-mode gates (M/L iterative work):**
363
+ - Immutable plugin registry — DISCOVERY audit functions locked at loop start; no dynamic registration mid-loop
364
+ - Git revert rollback — every iteration produces one squashed commit on feature branch; rollback = `git revert`; main untouched until convergence
365
+ - Numeric baseline corrections (changing the count an SC measures against, without changing goal intent) are NOT scope changes and do not require council vote. The DA amends via `gh issue comment` with rationale. Only intent-level changes (what we are trying to achieve, not just the numbers) require council.
366
+
367
+ **On CIRCUIT BREAK — decision tree (in order):**
368
+
369
+ ```
370
+ 0. Goal assumptions still valid?
371
+ └─ NO (Goal Audit triggered) → size-gated response above
372
+ └─ YES → continue to step 1
373
+
374
+ 1. Framework/library issue?
375
+ └─ YES → Context7 MCP first (10 sec), then retry
376
+
377
+ 2. Need more information?
378
+ └─ YES → Skill("Research") → findings to issue → replan
379
+
380
+ 3. Found new sub-problems during execution?
381
+ └─ YES → Create sub-issues via gh issue create
382
+ → If parent has `Parent: #NNN` in body, post `CHILD-ADDED: #NEW — [title]` on umbrella
383
+ → Work those via GOAL entry
384
+ → Return to parent issue when sub-issues close
385
+ → Umbrella closes via close-gate.sh decomposed path (D1-D4) when all children ship
386
+
387
+ 4. 1-2 attempts failed on same approach?
388
+ └─ YES → Escalate to specialist (→ CLAUDE.md Delegation Matrix for who handles what; → BRIEF-TEMPLATES.md for brief format)
389
+
390
+ 5. Per-goal budget exhausted?
391
+ └─ YES → STOP
392
+ → Write convergence report to GitHub issue
393
+ → Write checkpoint to $RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md
394
+ → Notify Jason with: what shipped, what didn't, why, options
395
+ ```
396
+
397
+ **Dynamic replanning (on every loop-back):**
398
+ - Re-read the GitHub issue (may have new comments/findings)
399
+ - Re-read findings from failed iteration
400
+ - Adjust approach based on what was learned
401
+ - If structured findings from VERIFICATION contradict the ACs themselves (not just the approach), fire the Goal Audit gate before replanning. If no structured findings were posted despite AC failures, DURABILITY gate blocks (durability-gate.sh check #2).
402
+ - Do NOT just retry the same thing
403
+
404
+ **Council gate (on structural replans):**
405
+ When a circuit break leads to a fundamentally different approach (not just a retry), run `Skill("council")` — 4 agents, 3 rounds — before committing to the new direction. This prevents the DA from picking a bad approach alone and catches drift before it compounds. Council is mandatory when:
406
+ - The replan changes the file scope (touching different files than the original plan)
407
+ - The replan changes the architectural approach (different data flow, different module ownership)
408
+ - 2+ circuit breaks have fired on the same issue (pattern of failed approaches)
409
+
410
+ **Output:** Either: issue closed (all ACs pass) OR checkpoint + convergence report.
411
+
412
+ **Quality bar:** Never retry without replanning. Never loop more than N iterations without hitting a circuit breaker. Never silently give up.
413
+
414
+ **Handoff:** PASS → FEEDBACK. BUDGET HIT → checkpoint + notify Jason.
415
+
416
+ **Reference:** → ADR-039 for convergence loop architecture, gap-list schema, convergence report template.
417
+
418
+ ---
419
+
420
+ ## 7. FEEDBACK — Automatic (hooks + DA actions)
421
+
422
+ **Purpose:** Make the system smarter for next time. Every closed issue feeds the learning loop.
423
+
424
+ **Process (fires on every issue close):**
425
+ 1. Signal capture → ratings.jsonl (SentimentScorer hook, automatic)
426
+ 2. Correction capture → if Jason corrected during session, feedback memory written
427
+ 3. Update checkpoint → `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md` marked complete
428
+ 4. Doc cascade → `Skill("doc-hygiene")` — verifies ARCHITECTURE.md, PROJECT-STATE.md, PRINCIPLES.md, CONTEXT.md, ADRs all reflect what shipped. Not optional — stale docs cause the same failures as stale code. Falls back to Ship DURABILITY matrix if skill unavailable.
429
+ 5. Close GitHub issue with evidence summary via `gh issue close`
430
+ 6. BACKLOG.md → any follow-ups discovered during work get logged
431
+
432
+ **Nightly (automatic — MemoryLoop.sh at 23:30):**
433
+ - RuleTracker → correlates rules with session outcomes
434
+ - LearningReview → promotes recurring failures to CLAUDE.md rules
435
+ - GraphBuilder → rebuilds knowledge graph from memories
436
+ - RecallEvaluator → tests graph retrieval quality
437
+ - SkillOptimizer → monthly hill-climbing on skill text
438
+
439
+ **Output:** System learns. Next session starts smarter.
440
+
441
+ **Reference:** → MEMORY-LOOP.md for full nightly pipeline. → SELFLEARNING.md for the four-tier pipeline.
442
+
443
+ ---
444
+
445
+ ## Circuit Breaker Defaults
446
+
447
+ | Scope | Default | Override |
448
+ |---|---|---|
449
+ | Per-issue iterations | 5 | Set in GOAL issue body |
450
+ | Per-issue wall clock | 90 minutes | Set in GOAL issue body |
451
+ | Per-goal cost | $20 | Set in GOAL issue body |
452
+ | Per-goal token ceiling | 5M tokens | Set in GOAL issue body |
453
+ | Stuck detection | 3 identical errors or tool calls | Not configurable |
454
+ | Per-issue goal amendments | 2 | Not configurable |
455
+
456
+ ---
457
+
458
+ ## Artifact Flow
459
+
460
+ Every step produces an artifact. The next step consumes it. No step relies on conversation memory.
461
+
462
+ ```
463
+ GOAL → GitHub issue (system of record)
464
+ DISCOVERY → Structured GitHub issue comment with file:line citations for every constraint answer
465
+ RESEARCH → Findings comment on GitHub issue
466
+ PLANNING → ACs + brief comment on GitHub issue
467
+ EXECUTION → Committed code + deploy confirmation
468
+ VERIFICATION → Evidence per AC (completion report on issue)
469
+ ITERATION → Updated issue comments + new sub-issues (if any)
470
+ FEEDBACK → ratings.jsonl + memories + docs + closed issue
471
+ ```
472
+
473
+ ---
474
+
475
+ ## Skills Invoked Per Step
476
+
477
+ | Step | Skill | When |
478
+ |---|---|---|
479
+ | GOAL | `Skill("goal")` | Always — first step |
480
+ | DISCOVERY | (built into Ship SCOPE) | Always |
481
+ | RESEARCH | `Skill("Research")` / Context7 MCP | Only when unknowns exist |
482
+ | PLANNING | `Skill("grill-with-docs")` | M+ size |
483
+ | PLANNING | `Skill("to-prd")` → `Skill("to-issues")` | L size |
484
+ | EXECUTION | `Skill("ship")` → `Skill("tdd")` → `Skill("simplify")` → `npx fallow` | Always |
485
+ | VERIFICATION | verify workflow + Quinn + Rook | Always (Quinn/Rook conditional) |
486
+ | ITERATION | (built into this standard) | When verification fails |
487
+ | FEEDBACK | `Skill("doc-hygiene")` | Always — docs must match what shipped |
488
+ | FEEDBACK | (automatic — hooks) | Always |
@@ -0,0 +1,53 @@
1
+ ---
2
+ doc-type: spec
3
+ status: draft
4
+ owner: [name]
5
+ created: [YYYY-MM-DD]
6
+ updated: [YYYY-MM-DD]
7
+ governs: [what this spec governs — one line]
8
+ testable: false
9
+ ---
10
+
11
+ # [Spec Title]
12
+
13
+ ## Problem Statement
14
+
15
+ [What gap, risk, or need this spec addresses. 2-3 sentences max.]
16
+
17
+ ## Design Decisions
18
+
19
+ [Key decisions. Use a table for multiple:]
20
+
21
+ | Decision | What | Rationale |
22
+ |---|---|---|
23
+ | D-1 | [decision] | [why] |
24
+
25
+ ## Target State
26
+
27
+ [What the system looks like when this spec is fully implemented.]
28
+
29
+ ## Success Criteria
30
+
31
+ Each SC must be parseable by the conformity test generator. Use these patterns:
32
+
33
+ ```
34
+ File existence: - [ ] SC-N: {filename} exists at root, ≤{N} lines
35
+ Directory: - [ ] SC-N: {dirname}/ directory exists with ≥{N} {things}
36
+ Frontmatter: - [ ] SC-N: All specs have `testable: true/false` frontmatter
37
+ Path resolution: - [ ] SC-N: All paths referenced in {file} resolve to existing files
38
+ Root cleanliness: - [ ] SC-N: Root is clean (code: ≤{N} items)
39
+ Pointer: - [ ] SC-N: {file} exists with pointer to {target}
40
+ Anti-criterion: - [ ] SC-AN: {thing that must NOT happen}
41
+ ```
42
+
43
+ - [ ] SC-1: [first criterion]
44
+ - [ ] SC-2: [second criterion]
45
+ - [ ] SC-A1: [anti-criterion — must NOT happen]
46
+
47
+ ## Implementation
48
+
49
+ [Steps to implement. Optional — can reference issues instead.]
50
+
51
+ ## Cautions
52
+
53
+ [Things that could go wrong. What to verify before/after.]
Binary file