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,250 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-18
6
+ ---
7
+
8
+ # Ship — Reference Material
9
+
10
+ ## Size Definitions
11
+
12
+ | Size | Scope | Time | Ceremony |
13
+ |------|-------|------|----------|
14
+ | **XS** | Single file, obvious fix, clear root cause | <30 min | None — straight to BUILD |
15
+ | **S** | 1-2 files, some diagnosis, clear target | <2 hours | None — straight to BUILD |
16
+ | **M** | 3+ files, crosses boundaries, architectural | 2-8 hours | grill-with-docs → BUILD |
17
+ | **L** | 6+ user stories, new capability | 1-3 days | grill → PRD → issues → triage |
18
+
19
+ **Boundary crossing = M:** lib/ → dashboard/, scraper → consumer, new external dependency, new API endpoint, new config file.
20
+
21
+ ## Evidence Types
22
+
23
+ Every acceptance criterion (AC-N) must have exactly one evidence citation in the completion report:
24
+
25
+ | Type | Format | When to use |
26
+ |------|--------|-------------|
27
+ | **Code presence** | `→ file.ts:L## [description]` | Asserting code exists at a location |
28
+ | **Absence** | `→ grep: "pattern" returned 0 matches in src/` | Asserting something does NOT exist |
29
+ | **Screenshot** | `→ screenshot: /tmp/qa-feature.png [description]` | UI/visual assertions |
30
+ | **API response** | `→ API: GET /endpoint returned { key: value }` | Behavior assertions |
31
+ | **Test pass** | `→ test: test-file.test.ts "test name" PASS` | Test-verified assertions |
32
+
33
+ ## Acceptance Criteria Template
34
+
35
+ ```
36
+ ## Acceptance Criteria
37
+
38
+ - [ ] AC-1: [specific, verifiable statement]
39
+ - [ ] AC-2: [specific, verifiable statement]
40
+ - [ ] AC-A1: [anti-criterion — must NOT happen]
41
+ ```
42
+
43
+ Rules:
44
+ - One verifiable thing per AC
45
+ - If it contains "and" joining two verifiable things → split
46
+ - If "all" or "every" → enumerate what "all" means
47
+ - Anti-criteria (AC-A prefix): what must NOT happen
48
+
49
+ **Garbage Test (MANDATORY for every AC):**
50
+ After writing each AC, ask: "Could garbage data pass this?" If yes, tighten the AC until the answer is no.
51
+
52
+ | Bad AC (presence check) | Good AC (measurable threshold) |
53
+ |---|---|
54
+ | "signals exist for product" | "signal count ≥ 4, each with headline + detail + ≥1 link" |
55
+ | "endpoint returns data" | "endpoint returns ≥ 3 items, each with name + non-empty detail" |
56
+ | "_enriched.json is produced" | "enrichment extracts ≥ 10 kits with ≥ 80% having actionable steps" |
57
+ | "download completes" | "download rate ≥ 50% of page-visible items" |
58
+ | "component renders" | "component shows correct data for 3 real customers, no empty sections" |
59
+
60
+ **Scaling/extending work:** When extending a feature to new data (product #2, customer #2, etc.), ACs must include comparative metrics: "new instance meets or exceeds original's quality bar on [coverage %, signal count, download rate, field completeness]."
61
+
62
+ ## Consumer Output Verification (MANDATORY for consumer changes)
63
+
64
+ If the change touches any consumer output (morning brief, campaigns, meeting prep, playbooks, email outreach, account plans), run ALL 4 layers:
65
+
66
+ ### Layer 1: API Output
67
+ Deploy, hit the endpoint, READ the JSON response.
68
+ ```bash
69
+ curl -s http://localhost:7777/api/morning-summary | python3 -m json.tool
70
+ ```
71
+ Verify: correct field counts, no empty sections, no internal noise, no hallucinated data.
72
+
73
+ ### Layer 2: UI Screenshot
74
+ Take a Playwright screenshot of the component rendering the data.
75
+ ```bash
76
+ node -e "const {chromium}=require('playwright'); ..."
77
+ ```
78
+ Verify: labels readable, no broken layout, badges display correctly, no noise items visible.
79
+
80
+ ### Layer 3: Rendered Output
81
+ If the change feeds into email HTML, Google Docs, or rendered templates — generate and READ the actual output. Not just the data feeding into it.
82
+
83
+ ### Layer 4: Goal Statement Check
84
+ Re-read `project_application_mission.md`. For each output item ask: "Does this help the AE walk into a room with a solution that connects to a business problem?" 100% must be actionable intelligence. Any item that's data without a conversation = not done.
85
+
86
+ Unit tests verify code structure. These 4 layers verify the product.
87
+
88
+ ## GitHub Issue Templates (standard for all sizes)
89
+
90
+ ### XS/S/M — Direct issue
91
+
92
+ ```markdown
93
+ ## Context
94
+ [1-3 sentences: what exists, what's wrong or missing, why it matters]
95
+
96
+ ## Acceptance Criteria
97
+ - [ ] AC-1: [measurable statement] → evidence: [code|grep|screenshot|api|test]
98
+ - [ ] AC-2: [measurable statement] → evidence: [type]
99
+ - [ ] AC-A1: [anti-criterion — must NOT happen] → evidence: [grep absence]
100
+
101
+ ## Files to modify
102
+ - [explicit file list]
103
+
104
+ ## Size: [XS|S|M|L]
105
+ ```
106
+
107
+ ### L — User story (one per vertical slice, created by `Skill("to-issues")`)
108
+
109
+ ```markdown
110
+ ## User Story
111
+ As a [role], I want [what] so that [why].
112
+
113
+ ## Context
114
+ [How this slice fits into the larger goal. Link to parent issue.]
115
+
116
+ ## Acceptance Criteria
117
+ - [ ] AC-1: [measurable statement] → evidence: [type]
118
+ - [ ] AC-2: [measurable statement] → evidence: [type]
119
+ - [ ] AC-A1: [must NOT happen] → evidence: [type]
120
+
121
+ ## Files to modify
122
+ - [explicit file list]
123
+
124
+ ## Size: [XS|S|M] (each slice should be independently shippable)
125
+ ## Parent: #[parent issue number]
126
+ ```
127
+
128
+ ### Rules (all sizes)
129
+ - Title format: `[verb] [what] — [where/context]`
130
+ - Every AC gets the garbage test: "Could garbage pass this?" → tighten until no
131
+ - Evidence type declared per AC at writing time, not after
132
+ - Anti-criteria (AC-A) for anything that must NOT change
133
+ - Files to modify = explicit allowlist for Marcus brief
134
+ - Post to GitHub via `gh issue comment` before BUILD starts
135
+
136
+ ## Completion Report Template
137
+
138
+ ```
139
+ ## Done
140
+
141
+ ### Evidence
142
+ - AC-1: → file.ts:L45 [function added with correct signature]
143
+ - AC-2: → grep: "templateSalesAlignment" returned 0 matches in src/customer.ts
144
+ - AC-3: → test: saleshub-filters.test.ts "rejects template text" PASS
145
+ - AC-A1: → grep: "HMRC" returned 1 match in config-templates/saleshub-knowledge.json [preserved]
146
+
147
+ ### Consumer output (if applicable)
148
+ - API: GET /api/morning-summary → 20 signals, 0 internal noise, 0 generic competitor
149
+ - [paste relevant excerpt showing fix works]
150
+
151
+ ### Tests
152
+ - `bun test --isolate test/unit/` — 1609 pass, 0 failures (zero tolerance — no "pre-existing" exemptions)
153
+ - `npx playwright test test/api/ --project=test` — 36 pass on 7776
154
+
155
+ ### Files changed
156
+ - src/lib/foo.ts:L45-L67 — added bar function
157
+ - test/unit/foo.test.ts — 4 new tests
158
+
159
+ ### Docs updated
160
+ - [x] ARCHITECTURE.md — no update needed
161
+ - [x] PROJECT-STATE.md — no update needed
162
+ ```
163
+
164
+ ## DISCOVERY Artifact Template (MANDATORY — post to GitHub issue before PLANNING)
165
+
166
+ Post this as a `gh issue comment` after completing DISCOVERY. Every fact must cite a file and line — never DA memory.
167
+
168
+ ```
169
+ ## Discovery — [issue title]
170
+
171
+ ### Docs read (with last-modified)
172
+ - PRINCIPLES.md (modified: YYYY-MM-DD) — [key constraints found]
173
+ - ARCHITECTURE.md (modified: YYYY-MM-DD) — [key patterns found]
174
+ - PROJECT-STATE.md (modified: YYYY-MM-DD) — [current state relevant to issue]
175
+ - [checkpoint if resuming] — [stopped at / next step]
176
+
177
+ ### Constraints (file:line citation required for each)
178
+ - [constraint 1] → [file.md:L##]
179
+ - [constraint 2] → [file.md:L##]
180
+
181
+ ### Domain-specific (answer ALL that apply)
182
+
183
+ **Scraper/infrastructure:**
184
+ - Where does this run? → [host/container] → [file.md:L##]
185
+ - What auth is needed? → [SSO/token/key] → [file.md:L##]
186
+ - What prerequisites? → [services/connections] → [file.md:L##]
187
+ - Where does output go? → [cache/Drive/both] → [file.md:L##]
188
+
189
+ **UI:**
190
+ - Which component? → [file path] → [file.md:L##]
191
+ - What data feeds it? → [API endpoint/source] → [file.md:L##]
192
+ - What consumers read it? → [list] → [PRINCIPLES.md:L##]
193
+
194
+ ### Related issues
195
+ - #N — [open/closed] — [relationship]
196
+
197
+ ### Unknowns (if any — each becomes RESEARCH input or new issue)
198
+ - [unknown 1] → [will research / logged as #N]
199
+
200
+ ### Doc gaps found (if any — logged immediately)
201
+ - [gap description] → logged as #N
202
+ ```
203
+
204
+ ---
205
+
206
+ ## Checkpoint Format (MANDATORY for multi-step work)
207
+
208
+ `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md` must include:
209
+ ```
210
+ **Project root:** [path]
211
+ **Session:** [date]
212
+ **Status:** [current state]
213
+ **Start timestamp:** [ISO-8601 — used by circuit breaker wall clock check]
214
+
215
+ ## Current work
216
+ - Issue: #N
217
+ - Phase: [GOAL|DISCOVERY|RESEARCH|PLANNING|EXECUTION|VERIFICATION|ITERATION]
218
+ - Iteration: [N of max]
219
+
220
+ ## Stopped at
221
+ [Exact description of where work stopped and what the next step is]
222
+ ```
223
+
224
+ ## Stuck Detection Storage
225
+
226
+ `$RUNGATE_WORK_DIR/{slug}/stuck-detection.json` — updated at each iteration boundary, read at each iteration start:
227
+ ```json
228
+ {
229
+ "iteration_count": 0,
230
+ "start_timestamp": "2026-06-19T16:00:00-04:00",
231
+ "stderr_hashes": [],
232
+ "tool_call_hashes": [],
233
+ "acs_passed_per_iteration": [],
234
+ "goal_audit_events": [],
235
+ "goal_audit_count": 0,
236
+ "baseline_values": {}
237
+ }
238
+ ```
239
+
240
+ ## Diagnostic Template (bugs only)
241
+
242
+ ```
243
+ ## Diagnosis
244
+ - Environment: [read project CLAUDE.md for test/prod ports]
245
+ - Logs: [what the logs show]
246
+ - State: [cache/config file contents]
247
+ - Source: [relevant code at file:line]
248
+ - Hypothesis: [single hypothesis]
249
+ - Fix: [minimal change]
250
+ ```
@@ -0,0 +1,347 @@
1
+ ---
2
+ name: Ship
3
+ description: Unified implementation — bugs, enhancements, features. SCOPE -> BUILD -> VERIFY with 31 machine-state gate checks.
4
+ version: 2.0.0
5
+ doc-type: reference
6
+ status: active
7
+ owner: jason
8
+ updated: 2026-09-06
9
+ contract:
10
+ input: "GitHub issue number with ACs"
11
+ gateIn: "Issue exists with ACs (from /goal)"
12
+ gateOut: "verify-gate PASS, code on main, mergeCommitSha set in workflow-state.json"
13
+ artifact: "Merged code + workflow-state.json with gate results"
14
+ outputSchema: "schemas/ship-evidence.schema.json"
15
+ telemetry: "harness-telemetry.jsonl with skill=ship"
16
+ errorRecovery:
17
+ timeout_seconds: 3600
18
+ failure_mode: BLOCK
19
+ cleanup_action: "Worktree cleanup, partial commits reverted"
20
+ resumable: true
21
+ ---
22
+
23
+ # Ship v2
24
+
25
+ One loop. One JSON file. Config-driven ceremony.
26
+
27
+ ## Trigger conditions
28
+
29
+ - When: `/ship`, "ship issue #N", "implement this", "fix this bug"
30
+ - Standalone: yes — can self-bootstrap from GitHub issue if no /goal ran
31
+ - Chain position: after /goal, before /prove
32
+ - Skip when: no issue exists (run /goal first)
33
+
34
+ ## Workflow
35
+
36
+ See phases below for the full workflow. GOAL -> DISCOVERY -> SCOPE GATE -> BUILD -> VERIFY -> SHIP GATE -> DONE.
37
+
38
+ ```
39
+ GOAL → DISCOVERY → scope-gate ⛩→ BUILD → verify-gate ⛩→ ship-gate ⛩→ DONE
40
+ ↑ |
41
+ └── iterate on failure ────┘
42
+ ```
43
+
44
+ **State file:** `$RUNGATE_WORK_DIR/{slug}/workflow-state.json` — the single source of truth. All gates read it. All phases write to it. Schema: `skills/ship/workflow-schema.json`.
45
+
46
+ **Ceremony profiles:** `skills/ship/ceremony-profiles.json` — LIGHT/STANDARD/THOROUGH tiers. The harness selects the tier mechanically based on size + unknowns + file count.
47
+
48
+ **Project config:** `.claude/rungate.json` in each project repo — dev/prod environments, commands, consumers.
49
+
50
+ **Gates:** `bun run gates/run-gate.ts --gate scope|verify|ship --slug {slug}`
51
+
52
+ **Briefs:** The DA hand-writes Marcus briefs with these 5 required fields:
53
+ 1. **Goal** — issue goal verbatim from workflow-state.json
54
+ 2. **ACs** — acceptance criteria with thresholds and evidence commands
55
+ 3. **Files** — specific files to read/modify with line numbers
56
+ 4. **Scope boundaries** — what NOT to touch
57
+ 5. **Verify commands** — exact commands to run after changes
58
+
59
+ ## Phase 1: GOAL
60
+
61
+ The GitHub issue is read and the goal is extracted.
62
+
63
+ **Initialize workflow-state.json:**
64
+ ```bash
65
+ mkdir -p "$RUNGATE_WORK_DIR/{slug}"
66
+ cat > "$RUNGATE_WORK_DIR/{slug}/workflow-state.json" << EOF
67
+ {
68
+ "schemaVersion": 2,
69
+ "issue": NUM,
70
+ "repo": "owner/repo",
71
+ "issueRepo": "",
72
+ "projectRoot": "",
73
+ "slug": "{slug}",
74
+ "phase": "GOAL",
75
+ "issueGoal": "",
76
+ "acs": [],
77
+ "gates": {},
78
+ "changelog": []
79
+ }
80
+ EOF
81
+ ```
82
+
83
+ **Issue goal capture:** The issue goal is extracted verbatim from `gh issue view NUM --json body` and written to the `issueGoal` field. The goal is never paraphrased.
84
+
85
+ ### Standalone Bootstrap (when no /goal ran)
86
+
87
+ When `/ship N` is invoked and `$RUNGATE_WORK_DIR/{slug}/workflow-state.json` does NOT exist:
88
+
89
+ 1. The slug is resolved from the repo name (e.g., `pai-config` → `pai`, `asaCommandCenter` → `ddb`)
90
+ 2. The issue is read: `gh issue view N --json title,body,labels`
91
+ 3. The issueGoal is extracted from issue title + first paragraph of body
92
+ 4. ACs are extracted from issue body (looking for `## Success Criteria` or `- [ ]` patterns)
93
+ 5. workflow-state.json is created with extracted data:
94
+ ```json
95
+ {
96
+ "schemaVersion": 2,
97
+ "issue": N,
98
+ "repo": "owner/repo",
99
+ "issueRepo": "",
100
+ "projectRoot": "",
101
+ "slug": "{slug}",
102
+ "phase": "GOAL",
103
+ "issueGoal": "[extracted from issue]",
104
+ "acs": [/* extracted from issue body */],
105
+ "gates": {},
106
+ "changelog": [],
107
+ "bootstrappedFrom": "github-issue"
108
+ }
109
+ ```
110
+ 6. A warning is logged: `echo "WARN: Self-bootstrapped from GitHub issue — no /goal ran. ACs may need garbage testing." >&2`
111
+ 7. DISCOVERY proceeds as normal
112
+
113
+ **Key constraint:** The bootstrapped workflow-state.json conforms to the same schema the Bun gate tests validate. The `bootstrappedFrom` field is informational — gates don't check it.
114
+
115
+ ### Chain Detection
116
+
117
+ At skill entry, the runner checks for upstream artifacts in the slug directory:
118
+
119
+ 1. **GoalRecord check:**
120
+ ```bash
121
+ GOAL_RECORD="$RUNGATE_WORK_DIR/{slug}/goal-record.json"
122
+ if [[ -f "$GOAL_RECORD" ]]; then
123
+ echo "INFO: Chain mode — GoalRecord found. Inheriting success criteria."
124
+ # Read successCriteria from GoalRecord and use as AC source
125
+ # GoalRecords are TTL-exempt — no staleness check needed here
126
+ else
127
+ echo "INFO: Standalone mode — no GoalRecord. ACs from issue body."
128
+ fi
129
+ ```
130
+ 2. Chain mode benefits: SCs have structured thresholds + evidenceType. Standalone mode: ACs extracted from issue markdown (less structured).
131
+ 3. **File presence only** — `test -f`, no parsing until confirmed present. No env vars, no flags.
132
+
133
+ ## Phase 2: DISCOVERY
134
+
135
+ **Project docs gate:** The project root is checked for a DOCS.md routing table. Only the pointed-to doc is loaded. Fallback: MODEL.md -> PRINCIPLES.md + ARCHITECTURE.md.
136
+
137
+ **rungate.json** is read from the project root — it provides dev/prod environments, test commands, consumers.
138
+
139
+ **Auto-scaffold:** If `.claude/rungate.json` does not exist, `bun ~/.claude/scripts/scaffold-rungate-config.ts "$PROJECT_ROOT"` runs automatically to generate a starter config. The generated config is reviewed and paths adjusted before proceeding.
140
+
141
+ **issueRepo:** If `rungate.json` has `issueRepo` different from `repo`, it is written to `issueRepo` in workflow-state.json. If not present, `repo` is copied to `issueRepo`.
142
+
143
+ **Source specs.** If the issue references visual specs (HTML, screenshots, Figma), design docs, or architecture files:
144
+ 1. **The DA reads the spec** and describes its structure in 3 sentences.
145
+ 2. The spec is written to `sourceSpecs[]` with path, `citedInDiscovery: true`, and `specElements[]` listing key structural elements.
146
+
147
+ **Sizing:**
148
+ - **XS** — single file, clear target, <30 min -> ceremony tier: LIGHT
149
+ - **S** — 1-3 files, clear target, <2 hours -> ceremony tier: STANDARD
150
+ - **M** — multi-file, crosses boundaries -> ceremony tier: STANDARD, `Skill("grill-with-docs")` runs first
151
+ - **L** — 6+ stories -> ceremony tier: THOROUGH, grill -> PRD -> sub-issues
152
+
153
+ `sizing.predicted` and `sizing.ceremonyTier` are written to workflow-state.json.
154
+
155
+ **Escalation:** XS/S that crosses a feature boundary is re-scoped as M.
156
+
157
+ **Research gate:** External API/library/pattern not in codebase triggers a researcher spawn before BUILD.
158
+
159
+ **Acceptance criteria** are written to `acs[]` in workflow-state.json. Each AC has:
160
+ - `id`, `type` (CODE/OUTCOME), `statement`
161
+ - `threshold` with op/value/unit
162
+ - `evidenceMethod` with type enum + command
163
+ - `specElement` tracing to a sourceSpec element (if spec exists)
164
+
165
+ **Anti-rationalization check:** Before ACs are written, evidence is verified for each claim. "The logic does X" -> cite file:line. "X doesn't exist" -> grep output.
166
+
167
+ **GitHub issue post:** DISCOVERY + ACs are posted as a single comment. For LIGHT tier: inline ACs only (no separate DISCOVERY comment).
168
+
169
+ **Phase update:** `phase: "SCOPE"` is set in workflow-state.json.
170
+
171
+ ## Phase 3: SCOPE GATE
172
+
173
+ ```bash
174
+ bun run gates/run-gate.ts --gate scope --slug {slug}
175
+ ```
176
+
177
+ LIGHT tier: scope gate is skipped (checks run inside ship-gate instead).
178
+
179
+ On FAIL -> `gates.scope.failures[]` is read from JSON, the specific issue is fixed, and the gate is re-run.
180
+
181
+ On PASS -> phase advances to BUILD automatically.
182
+
183
+ ## Phase 4: BUILD
184
+
185
+ **Context isolation rule:** The DA does NOT run implementation tools directly (Read source, Edit, Write, Bash for tests). All implementation goes through Marcus via Agent(). The DA may only: (1) generate the brief, (2) run gates, (3) read Marcus's report.
186
+
187
+ **Brief generation:**
188
+ The DA hand-writes the Marcus brief with: issueGoal verbatim, sourceSpecs paths, ACs with thresholds, dev/prod environments from rungate.json, specific files to modify with line numbers, scope boundaries (what NOT to touch), and verify commands. Marcus is then spawned.
189
+
190
+ **Brief capture (ADR-009 C2):** Before spawning Marcus, the DA writes the brief text to `~/.rungate/{slug}/marcus-brief.md`. The verify gate reads this file for brief-AC alignment validation.
191
+
192
+ **Marcus spawn rules:**
193
+ - `.claude` repo -> `isolation: "worktree"`, `mode: "bypassPermissions"`
194
+ - External project -> `mode: "bypassPermissions"`, NO worktree
195
+ - `mode: "bypassPermissions"` is MANDATORY for all Marcus spawns
196
+
197
+ **Build steps** (Marcus executes, exemptions apply for non-code output types):
198
+ 1. **TDD** — red-green-refactor. *Exempt:* config-only, pure doc, JSON data, UI copy.
199
+ 2. **Architecture check** (M+ only)
200
+ 3. **Simplify** — 3-agent code review
201
+ 4. **Fallow** — runs automatically on commit via hook
202
+
203
+ **`make rebuild`** is run by the DA only — agents never run it. The command comes from rungate.json `prod.rebuild`.
204
+
205
+ **Agent tracking:** `agents.marcus.spawned`, `agents.marcus.verdict`, `agents.marcus.branch` are written to JSON.
206
+
207
+ **Auto-verify trigger:** Immediately after `agents.marcus.verdict` is written to workflow-state.json, the verify gate runs mechanically:
208
+ ```bash
209
+ bun run gates/run-gate.ts --gate verify --slug {slug}
210
+ ```
211
+ This is automatic — no waiting, no prompting. The orchestrator advances the phase automatically on PASS.
212
+ If verify-gate FAILs, the ITERATION loop is entered (failures are read, fixed, and the gate re-run).
213
+ This replaces the manual "Phase 5: VERIFY" step — the gate call IS the verify step.
214
+
215
+ **Environment tracking:** After local testing, `environments.local.api`, `environments.local.ui`, `environments.local.tests` are written to JSON.
216
+
217
+ ## Phase 5: VERIFY
218
+
219
+ **Quinn and Rook are spawned in parallel** (STANDARD/THOROUGH tiers):
220
+ Quinn/Rook briefs are written inline with: what to test, which URLs/ports, what to compare against (sourceSpec paths), pass/fail criteria. Both are launched simultaneously via parallel Agent() calls.
221
+
222
+ **Quinn URL routing (#481):** The DA reads `rungate.json` `pages` map and provides the exact URL as line 1 of Quinn's test plan (`Navigate to: {url}`). Quinn must never guess which page to test — the harness tells it.
223
+
224
+ Quinn receives sourceSpec paths and compares built output against them. If structural mismatch -> FAIL regardless of AC results.
225
+
226
+ Rook scans changed files for security issues.
227
+
228
+ **Agent tracking:** quinn/rook spawned, verdict, comparedToSpec, screenshots are written to JSON.
229
+
230
+ **Environment (prod) tracking:** After container rebuild + smoke tests, `environments.prod.rebuild`, `environments.prod.smoke`, `environments.prod.quinn` are written to JSON.
231
+
232
+ **DA edit tracking:** The harness tracks direct DA edits to project source files in `daDirectEdits`. Delegating to Marcus is preferred; direct edits above 3 trigger a WARN at verify-gate.
233
+
234
+ **AC updates:** For each AC, `evidence` and `verdict` (PASS/FAIL) are written to JSON.
235
+
236
+ **Verify gate:**
237
+ ```bash
238
+ bun run gates/run-gate.ts --gate verify --slug {slug}
239
+ ```
240
+
241
+ On FAIL -> `gates.verify.failures[]` is read, failures are fixed, and the gate iterates. Circuit breaker at 3 iterations.
242
+
243
+ On PASS -> phase advances to SHIP.
244
+
245
+ ## Phase 6: SHIP GATE
246
+
247
+ ```bash
248
+ bun run gates/run-gate.ts --gate ship --slug {slug}
249
+ ```
250
+
251
+ Ship gate checks: all gates pass, branch merged, prod validated, docs updated, follow-ups created.
252
+
253
+ On PASS -> phase advances to DONE. The issue is closed.
254
+
255
+ ### Artifact Output
256
+
257
+ After ship-gate passes (phase = DONE), the ship evidence artifact is written:
258
+
259
+ 1. `~/.rungate/{slug}/ship-evidence.json` is created with:
260
+ ```json
261
+ {
262
+ "contractVersion": "1.0",
263
+ "issueNumber": N,
264
+ "gateOut": {
265
+ "status": "PASS",
266
+ "evidence": [/* one entry per AC: {criterion, result, detail} */]
267
+ },
268
+ "mergeCommitSha": "[from workflow-state.json]",
269
+ "capturedAt": "[ISO timestamp]",
270
+ "iterationCount": N,
271
+ "sizing": {"predicted": "S", "actual": "S"}
272
+ }
273
+ ```
274
+ 2. Validation runs via Zod schema in `gates/schema.ts` — `writeWorkflowState()` validates at write time.
275
+ 3. If validation fails, the error lists valid enum values — fix and re-write.
276
+
277
+ **Post-ship:**
278
+ 1. A completion summary is posted to the GitHub issue (using issueRepo from workflow-state.json)
279
+ 2. Follow-up issues are created for any gaps found during verify
280
+ 3. **Close behavior depends on chain mode:**
281
+ - **Chain mode** (goal-record.json exists in slug directory): The issue is NOT closed. The `shipped` label is added only. The issue stays open for `/prove` to verify and close.
282
+ - **Standalone mode** (no goal-record.json): The issue is closed: `gh issue close NUM --repo {issueRepo}` + `shipped` label added
283
+ 4. Sizing outcome is recorded: `sizing.actualFiles`, `sizing.actualMinutes`
284
+
285
+ ## ITERATION (when gates fail)
286
+
287
+ When verify-gate or ship-gate FAILs:
288
+
289
+ 1. `gates.{gate}.failures[]` is read from JSON — exact failure reasons
290
+ 2. `iterationCount` is incremented in JSON
291
+ 3. The specific failures are fixed (Marcus is re-briefed, or fixed directly for XS)
292
+ 4. The gate is re-run
293
+ 5. Circuit breaker: `iterationCount > 3` -> escalation (Context7, Research, council, or stop)
294
+ 6. Hard stop at 6 iterations — issue stays open with full report
295
+
296
+ **AFK enforcement:** After initial approval, the loop runs autonomously. Zero AskUserQuestion calls. The loop iterates until gates pass or circuit breaker fires.
297
+
298
+ **Convergence budget (council loops):** When running ship->council->ship cycles, findings count is tracked per round. The loop stops if findings don't decline after 3 rounds. See `skills/ship/convergence.md`.
299
+
300
+ ## Ceremony Tier Summary
301
+
302
+ | | LIGHT (XS) | STANDARD (S/M) | THOROUGH (L) |
303
+ |---|---|---|---|
304
+ | Gates | 1 (ship only) | 3 (scope+verify+ship) | 3 (scope+verify+ship) |
305
+ | Agents | Marcus optional | Marcus + Quinn | Marcus + Quinn + Rook |
306
+ | Quinn+Rook | skip | Quinn only | Quinn + Rook parallel |
307
+ | GitHub comments | 2 | 3 | 5 |
308
+ | STOP markers | 0 | 0 | 0 |
309
+ | Read() calls | 2 | 4 | 6 |
310
+ | Anti-gaming | skip | WARN | required |
311
+
312
+ ## Bug Protocol
313
+
314
+ 1. Batch diagnostic read — environment is confirmed (using rungate.json ports), all logs + errors + source are read
315
+ 2. Single hypothesis -> single change
316
+ 3. Regression test required
317
+ 4. Wrong hypothesis? -> batch-read with failed-fix context
318
+
319
+ ## Mid-session Bugs
320
+
321
+ New bug found during work -> re-enters ship:
322
+ 1. The bug is logged (GitHub issue or BACKLOG.md)
323
+ 2. Sizing: 1-line typo (inline OK) or real fix (ship required)
324
+ 3. If >1 line of logic -> ACs are written and the fix is sent to Marcus through ship
325
+
326
+ **The 1-line rule:** Only exempt: single character fixes, config value swaps, obvious typos.
327
+
328
+ ## User-Opened Issue Protocol
329
+
330
+ User-reported bugs require a different approach than internally-filed issues:
331
+
332
+ 1. **Reproduce first** — The user's configuration is set up and their exact experience is reproduced BEFORE code is read. "Code exists" does not mean "feature works."
333
+ 2. **Enumerate every sentence** — Each sentence in the issue body becomes a test case. The title alone is not sufficient scope.
334
+ 3. **Screenshots are visual specs** — Screenshots in user issues go into `sourceSpecs[]`. Quinn compares current UI against them.
335
+ 4. **Test with user's data shape** — If they have 5 pods, testing uses 5 pods. 1-pod local data does not verify a multi-pod bug.
336
+ 5. **Council when uncertain** — If the DA is not confident about root cause, council runs BEFORE ACs are written. Prompt: "Here's what the user reported. Here's what the code does. Does the code actually solve the user's complaint?"
337
+ 6. **User impact statement at close** — Required field in completion report: "What the user does to see the fix" (e.g., run upgrade.sh, refresh page, etc.).
338
+
339
+ ## Anti-patterns
340
+
341
+ - Chain-calling other implementation skills — Ship is the only implementation skill
342
+ - Reporting done without evidence for every AC
343
+ - Skipping TDD for code changes
344
+ - Running `make rebuild` from agents — only the DA runs it
345
+ - Fixing bugs inline without re-entering ship (1-line rule is the only exception)
346
+ - Running individual gate scripts — `bun run gates/run-gate.ts` is the single entry point
347
+ - Editing workflow-state.json manually — the ship skill and Bun gate orchestrator handle it mechanically