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