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,382 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-08-27
6
+ ---
7
+
8
+ # Iteration Protocol — Outer Quality Loop
9
+
10
+ Ship handles one implementation pass (SCOPE→BUILD→VERIFY→CLOSE). This protocol wraps ship in an outer loop that iterates until a quality target is met — driven by a spec, goal SCs, or both.
11
+
12
+ **When this fires:** After ship's Step 1 (SCOPE), if the work has iteration config (output type `iteration` section or `## Iteration Mode` in issue body), follow this protocol instead of proceeding to BUILD directly.
13
+
14
+ ## Step 0: VALIDATION DESIGN (runs once, council-gated)
15
+
16
+ Before any implementation, define WHAT we're testing and verify it's sufficient.
17
+
18
+ ### 0a. Identify validation layers
19
+
20
+ Every iterable task has up to 3 layers. Identify which apply:
21
+
22
+ | Layer | When it applies | Artifact needed |
23
+ |---|---|---|
24
+ | Content/API | Always | Spec + validator script OR behavioral SCs with verification commands |
25
+ | UI | When UI component exists | New-user walkthrough script for Quinn |
26
+ | E2E | When crossing integration boundaries | Cross-layer verification commands |
27
+
28
+ ### 0b. Load or draft artifacts
29
+
30
+ **If artifacts exist** (repeat run): load from `docs/specs/`, `scripts/validate-*.ts`, `docs/specs/ui/`. Council reviews for gaps against THIS round's changes only.
31
+
32
+ **If artifacts don't exist** (first run): DA drafts:
33
+ - **Spec-driven:** read the governing spec, design validator checks (PASS/WARN/FAIL per field)
34
+ - **Goal-driven:** decompose goal into behavioral SCs. Each SC: user action → system result. NO grep-only SCs — must test through the system.
35
+ - **UI:** write new-user walkthrough. Each step: navigate → interact → verify visible result. Cover: happy path, empty state, error state, edge cases.
36
+ - **E2E:** write cross-boundary checks. Each: state change in layer A → verify effect in layer B.
37
+
38
+ ### 0c. Council reviews ALL artifacts (MANDATORY)
39
+
40
+ Council evaluates:
41
+ 1. **Sufficiency** — does this cover the goal?
42
+ 2. **False-pass check** — could these pass with the feature broken? Rewrite any that could.
43
+ 3. **Coverage matrix** — cross-layer gap analysis. Every testable behavior covered in at least 2 layers.
44
+ 4. **Edge cases** — empty state, error state, new user, stale data, concurrent access.
45
+ 5. **Module→concept mapping** — if the work touches multiple modules, is the boundary defined?
46
+ 6. **Entity sample selection** — which 3+ entities (customers, products, etc.) will be tested? Select for data diversity: one with full data, one with partial, one with none/edge case. Council approves the sample.
47
+ 7. **Global data masking** — does any shared/global data source mask per-entity results? Flag any module that returns data regardless of entity parameter.
48
+
49
+ Council also CREATES missing artifacts:
50
+ - No validator script? → council designs check list, Marcus builds it as prerequisite.
51
+ - No UI walkthrough? → council writes it from new-user perspective.
52
+ - No behavioral SCs? → council decomposes goal into testable assertions.
53
+
54
+ ### 0d. Gate
55
+
56
+ Cannot enter the loop until:
57
+ - [ ] All 3 layers identified (or explicitly marked N/A)
58
+ - [ ] Council has reviewed and approved
59
+ - [ ] Coverage matrix has no gaps
60
+ - [ ] False-pass check passed on every SC/assertion
61
+
62
+ ## The Loop
63
+
64
+ ### AUDIT
65
+
66
+ Run all verification commands. Record results per layer:
67
+
68
+ ```
69
+ ═══ ITERATION — AUDIT ═══
70
+ Pass: N
71
+ Layer: Content/API
72
+ SC-1: [PASS/FAIL] — [command output]
73
+ SC-2: [PASS/FAIL] — [command output]
74
+ Layer: UI
75
+ UI-1: [PASS/FAIL] — [Quinn result]
76
+ Layer: E2E
77
+ E2E-1: [PASS/FAIL] — [command output]
78
+ Baseline: X/Y passing (first pass only)
79
+ Delta: +N PASS, -N FAIL since last pass
80
+ ```
81
+
82
+ **For spec-driven work:** also run the validator script and quality checks from output type config.
83
+
84
+ ### DECIDE (mechanical — no judgment)
85
+
86
+ ```
87
+ All checks PASS on dev?
88
+ └─ YES → DEPLOY TO PROD (see below)
89
+ └─ NO →
90
+ Same check failed 2+ consecutive passes?
91
+ └─ YES → COUNCIL (architectural input needed)
92
+ └─ NO →
93
+ Failure is scope gap (missed integration point, wrong count)?
94
+ └─ YES → RE-AUDIT (re-run Step 0c council review)
95
+ └─ NO → SHIP (fix and retry)
96
+ ```
97
+
98
+ **After council:** if same check fails again → ESCALATE to Jason. 3 strikes maximum.
99
+
100
+ **NO OVERRIDES.** "Root cause is clear" is not a reason to skip council. If the mechanical trigger fires, council runs. Every time the agent thinks "I know the fix, no need for council" and skips it, the fix fails and wastes a pass. The trigger exists BECAUSE the agent's confidence doesn't correlate with fix success.
101
+
102
+ **Council → SHIP is automatic.** When council returns recommendations, file the issues and start shipping the highest priority immediately. No "Want me to file issues and start?" — YES, always yes. Council output IS the next SHIP input. AFK means the transition is seamless.
103
+
104
+ ### SHIP
105
+
106
+ Enter ship BUILD with:
107
+ - Failing checks as ACs
108
+ - Full scope from AUDIT (every file, every count)
109
+ - Verification commands to run
110
+
111
+ Ship runs SCOPE→BUILD→VERIFY→DURABILITY→CLOSE internally. No stops within ship — AFK mode applies.
112
+
113
+ ### VERIFY
114
+
115
+ After ship CLOSE, re-run ALL checks (not just the ones that were fixed). A fix for SC-3 can break SC-1.
116
+
117
+ ### LEARN (mandatory after every VERIFY, before looping)
118
+
119
+ After each SHIP→VERIFY cycle, reflect and produce artifacts before looping back to AUDIT:
120
+
121
+ 1. **What gap did we find?** — Name the specific failure that triggered this pass
122
+ 2. **Why wasn't it caught earlier?** — Root cause of the miss (narrow guard, wrong trigger, skipped step)
123
+ 3. **What mechanical change prevents this?** — Rule, guard, gate, validator check, or template update
124
+ 4. **Implement now** — Write the CLAUDE.md rule, update the gate script, add the validator check, or save the feedback memory IN THIS STEP. Not "later", not "follow-up". The learning is only real if it ships as an artifact in the same pass.
125
+
126
+ Output format:
127
+ ```
128
+ ═══ ITERATION — LEARN ═══
129
+ Pass: N
130
+ Gap: [what failed]
131
+ Root cause: [why it wasn't caught]
132
+ Mechanical fix: [what changed — file:line or rule name]
133
+ Artifact: [CLAUDE.md rule | gate script | validator check | feedback memory]
134
+ ```
135
+
136
+ This step is not optional reflection — it's a mechanical step that produces durable artifacts. Skip it and the same gap class recurs on the next campaign or the next customer.
137
+
138
+ **Post to issue:** After producing the LEARN output, post it as a GitHub issue comment. This creates a permanent audit trail — conversation context evaporates, issue comments don't.
139
+
140
+ **Final LEARN (all checks pass):** Run LEARN one more time before EXIT. The question shifts: "What did the full iteration teach us?" Not just the last pass — the entire arc. Capture meta-learning about the process itself (briefing gaps, wrong assumptions, wasted passes).
141
+
142
+ Back to DECIDE.
143
+
144
+ ## Dev → Prod → UI Progression
145
+
146
+ The loop runs in phases. Each phase must be clean before advancing:
147
+
148
+ ```
149
+ PHASE 1: LOCAL DEV (iterate until 0 failures)
150
+ Pass 1: AUDIT → DECIDE → SHIP → VERIFY (content/API)
151
+ Pass 1.5: UI SMOKE CHECK — Quinn verifies component renders in DOM
152
+ If not rendered → fix wiring BEFORE continuing API iteration
153
+ Not a full walkthrough — just "does it appear on the page?"
154
+ Pass 2+: AUDIT → DECIDE → SHIP → VERIFY (content/API + smoke re-check)
155
+ Dev server (7778) — no rebuild between passes
156
+ Exit: all content/API passing + component renders on dev
157
+
158
+ PHASE 2: PROD DEPLOY (one-time)
159
+ make rebuild → prod (7777)
160
+ DEPLOYMENT VERIFICATION: confirm container serves new build
161
+ Check: JS bundle hash changed, or grep for known-new string in response
162
+ If old build still served → rebuild failed silently → investigate
163
+ Re-run all content/API + behavioral checks against prod
164
+ If prod fails → back to PHASE 1 (new gaps on dev)
165
+
166
+ PHASE 3: UI ON DEV (if UI layer exists)
167
+ Quinn runs full walkthrough on dev (7778) — all entities in sample
168
+ If failures → fix on dev → Quinn re-runs on ALL entities (not just fixed one)
169
+ Exit: Quinn walkthrough 100% passing on dev for all sample entities
170
+
171
+ PHASE 4: UI ON PROD (one-time)
172
+ make rebuild → prod
173
+ DEPLOYMENT VERIFICATION (same as Phase 2)
174
+ Quinn runs walkthrough on prod — all entities in sample
175
+ If failures → back to PHASE 3
176
+
177
+ EXIT: all layers passing on all environments on all sample entities
178
+ ```
179
+
180
+ **UI smoke check rationale:** Catching "component doesn't render" on pass 1 costs one quick Quinn check. Missing it costs 4+ wasted passes iterating API against a UI that was never wired up. Cheapest to detect, most expensive to miss.
181
+
182
+ ## Circuit Breakers
183
+
184
+ - **Stall:** 2 consecutive passes with identical PASS/FAIL counts → council
185
+ - **Oscillation:** track WHICH checks fail, not just count. If the failing set changes but count doesn't decrease over 3 passes → council. (SC-1 passes while SC-2 fails, then reverses — count unchanged but different bugs)
186
+ - **Regression:** if a SHIP pass INCREASES total failures → immediate `git revert` of that pass + council. Compounding damage is worse than reverting.
187
+ - **Max passes (size-scaled):** XS: 3 max. S: 4. M: 6. L: 8. Not a flat number for all sizes.
188
+ - **Elapsed time:** XS > 1 hour, S > 2 hours, M > 4 hours, L > 8 hours → council. Exceeding time budget means something is structurally wrong.
189
+ - **Post-council limit:** 3 failures on same check after council → escalate to Jason
190
+ - **Cost:** stop if token spend exceeds issue budget
191
+
192
+ ## Spec-Driven Extras
193
+
194
+ When the output type has an `iteration` section with `regenerate` and `validate`:
195
+
196
+ - After SHIP, run the **regenerate** command (e.g., `curl POST .../generate`)
197
+ - Then run the **validate** command (e.g., `bun scripts/validate-*.ts`)
198
+ - Then run **quality checks** if defined (e.g., Sapling AI detection)
199
+ - Exit criteria from output type config (e.g., `validate_fail: "0"`)
200
+
201
+ This replaces manual "did you regenerate?" checks with mechanical execution.
202
+
203
+ ## EXIT
204
+
205
+ ```
206
+ ═══ ITERATION — COMPLETE ═══
207
+ Passes: N (Phase 1: X, Phase 2: Y, Phase 3: Z, Phase 4: W)
208
+ Baseline: A/B passing → Final: B/B passing
209
+ Environments: dev ✓, prod ✓, UI ✓
210
+ Council invocations: N
211
+ Issues shipped: #NNN, #NNN
212
+ Time: X hours
213
+ ```
214
+
215
+ ### Persist validated artifacts
216
+
217
+ After a successful exit:
218
+ - New spec/validator → already in repo (committed during ship)
219
+ - New UI walkthrough → save to `docs/specs/ui/{type}-walkthrough.md`
220
+ - New behavioral SCs → update output type JSON `iteration` section
221
+ - Coverage matrix → save to issue as closing comment
222
+
223
+ Next time this output type runs → Step 0 loads existing artifacts. Council reviews for NEW gaps only.
224
+
225
+ ## Verification Questionnaire (run at every AUDIT)
226
+
227
+ Before reporting AUDIT results, answer every question. Any NO without evidence = BLOCKED.
228
+
229
+ **Layer depth:**
230
+ - [ ] Did you verify via API (curl/command)?
231
+ - [ ] Did you verify the UI component renders (not just API)?
232
+ - [ ] For consumer outputs: did you generate through the UI and validate the output against spec?
233
+ - [ ] Did you check rendered output (Google Doc, email HTML) if applicable?
234
+
235
+ **Entity coverage:**
236
+ - [ ] Did you verify on the primary dev entity?
237
+ - [ ] Did you verify on 2+ additional entities from the council-approved sample?
238
+ - [ ] Did you verify on the edge-case entity (empty/minimal data)?
239
+
240
+ **Regression:**
241
+ - [ ] Did you re-run ALL checks, not just the fixed ones?
242
+ - [ ] Did fixing this increase total failure count? (If yes → revert)
243
+
244
+ **Tool verification:**
245
+ - [ ] Did every agent/skill invocation produce actual output (not "completed in 0s")?
246
+ - [ ] Does the deployed container serve the new build (check bundle hash)?
247
+
248
+ **Data integrity:**
249
+ - [ ] Does any "loaded" status reflect actual per-entity data (not global/shared counts)?
250
+ - [ ] Do percentages/values match between API and UI?
251
+
252
+ **Output-change Quinn trigger:**
253
+ - [ ] Did this change alter user-visible output (generated content, not just code structure)?
254
+ - [ ] If yes: did Quinn walk the UI flow where users see that output (preview modal, detail page, export)?
255
+ - [ ] "No .tsx changed" is NOT a valid Quinn skip — the test is "did the user experience change?"
256
+
257
+ **Quinn briefing completeness:**
258
+ - [ ] Does the Quinn brief include exact page location? (sidebar vs main, group name, expand action)
259
+ - [ ] Does the Quinn brief include the correct URL format? (display name vs slug — check the router)
260
+ - [ ] Does the Quinn brief include exact curl commands with correct identifiers for API verification?
261
+
262
+ This questionnaire grows with each iteration run. New failure patterns discovered during any session become new questions here.
263
+
264
+ ## API verification is NOT UI verification
265
+
266
+ Verifying an API endpoint via curl does NOT verify the UI works. The API can return perfect data while:
267
+ - The UI component doesn't render at all (import/wiring bug)
268
+ - The UI renders but shows stale/wrong data (fetch URL mismatch)
269
+ - The UI renders but the layout is broken (CSS/component structure)
270
+ - The UI renders on one route but the user navigates a different route
271
+
272
+ **Rule: Every UI AC requires Quinn to walk through the actual browser.** Marcus cannot claim a UI AC is done with "visual verification requires rebuild" or "component created." A component that exists in code but doesn't render is not done.
273
+
274
+ **Quinn trigger is "did the user experience change?" — NOT "did .tsx files change."** Backend changes that alter generated content (campaigns, account plans, briefs, emails) change what the user sees in preview modals, detail pages, and exports. Zero .tsx changes does NOT mean zero UI impact. If the output content changed, Quinn walks the UI flow where users see that content.
275
+
276
+ Examples of backend-only changes that require Quinn:
277
+ - Extraction logic changes → campaign content changes → preview modal shows different text
278
+ - Signal scoring changes → brief content changes → brief page shows different priorities
279
+ - Template changes → account plan structure changes → plan panel shows different sections
280
+ - Data source wiring → new data appears in existing UI components
281
+
282
+ **After every fix that changes user-visible output:** Quinn runs the full UI walkthrough on the flow where the output is consumed. Not optional. Not "if time permits." The walkthrough IS the verification. Verify the fix the same way the bug was found.
283
+
284
+ **curl ≠ UI.** curl verifies the API layer. Quinn verifies the UI layer. Both must pass independently. A passing curl test with no Quinn walkthrough means the UI layer is UNVERIFIED, not passing.
285
+
286
+ ## Verification must go ALL the way through
287
+
288
+ Three layers of "stopping too early" that keep recurring:
289
+
290
+ 1. **API check instead of UI** — curl returned clean data, declared done. But the UI renders it wrong or doesn't render at all.
291
+ 2. **UI rendered instead of output quality** — generation succeeded, declared done. But nobody read the actual output against the spec (orphaned words, truncated openers, metadata leaks).
292
+ 3. **One entity instead of all affected** — A10 was clean, declared done. But Illumio/Initech had different data that triggered different bugs.
293
+
294
+ **The rule: verification goes ALL the way down, ALL the way across.**
295
+
296
+ "All the way down" means: API → UI renders → output generated → output validated against spec. Every layer, not just the first that passes.
297
+
298
+ "All the way across" means: if the fix affects multiple customers/entities, verify on ALL of them (or a representative sample of 3+), not just the one used during development.
299
+
300
+ A passing check on one customer with one layer verified is not a passing check. It's one cell in the coverage matrix.
301
+
302
+ ## Mid-loop discoveries (NEW findings during verification)
303
+
304
+ When Quinn, Rook, or any verification step finds NEW bugs not in the original SCs:
305
+
306
+ 1. **Add them to the check list immediately** — they're new SCs now
307
+ 2. **SHIP the fix** — don't ask, don't file for later, don't present options
308
+ 3. **Re-verify ALL checks** (original + new)
309
+ 4. **Continue the loop**
310
+
311
+ **NEVER:** "Want me to fix this or save for next session?" — that's a stop. Fix it NOW.
312
+ **NEVER:** "Two paths forward: quick fix or file issues" — there's one path: fix and verify.
313
+ **EXCEPTION:** If the new finding is out of scope (different feature, different repo, unrelated system) → file as follow-up issue AND continue fixing in-scope findings. Don't stop to ask.
314
+
315
+ ## Verify tool invocations actually ran
316
+
317
+ When invoking council, workflows, or any agent:
318
+ - **"Completed in 0s" = did NOT run.** Re-launch with correct args.
319
+ - **"Successfully loaded skill" ≠ "skill executed."** Check for actual output.
320
+ - **Agent spawned ≠ agent completed.** Wait for the agent's report before claiming its findings.
321
+
322
+ Don't declare "council is running" after a Skill() call — verify the workflow/agent actually started and is producing output. Silent failures waste entire loop passes.
323
+
324
+ ## Compaction Durability (checkpoint every pass)
325
+
326
+ Context compaction can happen mid-loop. Persist iteration state so it survives.
327
+
328
+ ### What to checkpoint
329
+
330
+ After every AUDIT, write `MEMORY/WORK/{issue-slug}/ITERATION-STATE.json`:
331
+
332
+ ```json
333
+ {
334
+ "issue": 27,
335
+ "slug": "27-provenance-panel",
336
+ "currentPass": 3,
337
+ "phase": "DEV",
338
+ "timestamp": "2026-08-27T17:00:00Z",
339
+ "entitySample": ["a10-networks", "confluent", "fake-customer"],
340
+ "checks": {
341
+ "AC-1": { "history": ["FAIL", "FAIL", "PASS"], "lastResult": "PASS" },
342
+ "AC-2": { "history": ["FAIL", "PASS", "PASS"], "lastResult": "PASS" }
343
+ },
344
+ "baseline": { "pass": 2, "fail": 5, "total": 7 },
345
+ "current": { "pass": 5, "fail": 2, "total": 7 },
346
+ "councilInvocations": 1,
347
+ "councilDecisions": ["Rewrite cache detection to use file existence not signal registry"],
348
+ "circuitBreakers": { "consecutiveSameCount": 0, "postCouncilFailures": 0 },
349
+ "validationDesign": {
350
+ "layers": ["Content/API", "UI"],
351
+ "coverageMatrix": "docs/specs/coverage-27.md",
352
+ "questionnaire": ["API verified?", "UI renders?", "3+ entities?"]
353
+ }
354
+ }
355
+ ```
356
+
357
+ ### Recovery after compaction
358
+
359
+ On session start or after context compression, the recovery hook loads the latest `ITERATION-STATE.json` and injects:
360
+ - Current pass number and phase
361
+ - Which checks are passing/failing and their history (for stall/oscillation detection)
362
+ - Council decisions made (so they're not re-derived)
363
+ - Entity sample (so verification stays consistent)
364
+
365
+ **Rule:** If ITERATION-STATE.json exists but no ship checkpoint does, the iteration loop is the active work — resume from the last AUDIT, not from SCOPE.
366
+
367
+ ### What NOT to checkpoint
368
+
369
+ - Full AUDIT output (too large; re-run the checks)
370
+ - Council transcript (decisions captured, reasoning is in the issue comments)
371
+ - Code diffs (git has those)
372
+
373
+ ## Rules
374
+
375
+ - **Council at Step 0 is mandatory.** No skipping validation design. Bad tests = wasted iteration.
376
+ - **ALL checks every pass.** Never verify only the fixed checks.
377
+ - **Dev before prod.** No rebuilding between dev passes. Deploy only when dev is clean.
378
+ - **UI after API.** Don't test UI until the API layer is stable.
379
+ - **AFK throughout.** After Step 0 approval, zero AskUserQuestion calls until EXIT or circuit breaker. No "should I fix this?" — the answer is always yes.
380
+ - **Mechanical decisions only.** The DECIDE tree has no judgment branches. Counters and conditions decide, not the agent.
381
+ - **New findings are not options.** A bug found during verification is a failing check. Failing checks get fixed. There is no "file for later" path for in-scope failures.
382
+ - **Checkpoint every pass.** Write ITERATION-STATE.json after every AUDIT. Compaction without checkpoint = lost state.
@@ -0,0 +1,246 @@
1
+ # Pending Skill Patches
2
+
3
+ Generated by FailurePatternDetector.ts. Review during weekly optimize-rules.
4
+ Apply immediately if same pattern recurred across 2+ sessions.
5
+
6
+ ---
7
+
8
+ ## Patch: EXECUTION|process|rayford
9
+
10
+ - **Target:** `ship/SKILL.md`
11
+ - **Harness step:** EXECUTION
12
+ - **Category:** process
13
+ - **Occurrences:** 24
14
+ - **Generated:** 2026-06-20T23:53:01.012Z
15
+ - **Action:** Add mechanical check to ship SKILL.md at EXECUTION step to prevent: correction-validation-logic-analysis-was-inaccurate
16
+ - **Failures:**
17
+ - correction-validation-logic-analysis-was-inaccurate
18
+ - correction-incomplete-verification-missed-skills-tracking-page
19
+ - correcting-rayford-sourceredhatcom-not-viable-for-accounts
20
+ - correcting-inaccuracy-requesting-factual-consistency
21
+ - correction-analysis-was-incomplete-missed-data
22
+ - exasperated-fix-supposedly-deployed-but-still-broken
23
+ - deployed-blue-highlights-not-visible-in-ui
24
+ - missed-important-detail-in-analysis
25
+ - correction-incorrect-github-pat-requirement-stated
26
+ - claimed-demo-deployed-before-user-finished-running-commands
27
+ - correction-claimed-feature-doesnt-have-data
28
+ - direct-contradiction-of-assistants-claim-about-claudemd
29
+ - frustrated-workaround-created-new-blocker-not-resolved-root
30
+ - factual-error-in-token-reset-time-statement
31
+ - correction-incomplete-setup-instruction-missing-bash-wrapper
32
+ - behavioral-correction-stop-stating-false-vpn-requirement
33
+ - caught-inaccurate-data-rayford-said-zero-cases-jason
34
+ - frustrated-diagnosis-inaccurate-problem-unsolved-after-50-min
35
+ - frustratedfailed-to-follow-established-dev-loop-procedure
36
+ - verification-command-failed-dns-couldnt-resolve-hostname
37
+ - explicit-low-rating-310
38
+ - frustrated-server-immediately-failed-after-deploy
39
+ - cases-not-displaying-despite-rayford-claiming-they-cached
40
+ - partial-implementation-most-links-nonfunctional
41
+
42
+ ---
43
+
44
+ ## Patch: PLANNING|process|rayford
45
+
46
+ - **Target:** `ship/SKILL.md`
47
+ - **Harness step:** PLANNING
48
+ - **Category:** process
49
+ - **Occurrences:** 5
50
+ - **Generated:** 2026-06-20T23:53:01.012Z
51
+ - **Action:** Add mechanical check to ship SKILL.md at PLANNING step to prevent: frustrated-rayfords-explanation-left-jason-confused
52
+ - **Failures:**
53
+ - frustrated-rayfords-explanation-left-jason-confused
54
+ - confused-by-unclearincomplete-instruction-from-rayford
55
+ - pointing-out-discrepancy-in-system-state-vs-explanation
56
+ - backlog-lacked-verification-before-presentation
57
+ - correction-assistant-explained-wrong-flow
58
+
59
+ ---
60
+
61
+ ## Patch: DISCOVERY|process|rayford
62
+
63
+ - **Target:** `ship/SKILL.md`
64
+ - **Harness step:** DISCOVERY
65
+ - **Category:** process
66
+ - **Occurrences:** 5
67
+ - **Generated:** 2026-06-20T23:53:01.012Z
68
+ - **Action:** Add mechanical check to ship SKILL.md at DISCOVERY step to prevent: rayford-missed-that-issues-1-2-already-completed
69
+ - **Failures:**
70
+ - rayford-missed-that-issues-1-2-already-completed
71
+ - questioning-if-rayford-verified-sheets-exist-on-drive
72
+ - questioning-why-real-data-wasnt-bootstrapped-first
73
+ - correction-rayford-didnt-clarify-the-distinction-jason-made
74
+ - correction-rayford-misread-warning-jason-had-to-clarify
75
+
76
+ ---
77
+
78
+ ## Patch: EXECUTION|process|serena
79
+
80
+ - **Target:** `ship/SKILL.md`
81
+ - **Harness step:** EXECUTION
82
+ - **Category:** process
83
+ - **Occurrences:** 5
84
+ - **Generated:** 2026-06-20T23:53:01.012Z
85
+ - **Action:** Add mechanical check to ship SKILL.md at EXECUTION step to prevent: correction-rayfords-diagnosis-was-wrong-about-app-state
86
+ - **Failures:**
87
+ - correction-rayfords-diagnosis-was-wrong-about-app-state
88
+ - correction-fundamental-misunderstanding-of-waterfall-logic
89
+ - correction-subscriptions-source-is-sf-bookings-sheet
90
+ - correction-missed-that-prompt-uses-new-template
91
+ - correction-validate-against-code-before-claiming-certainty
92
+
93
+ ---
94
+
95
+ ## Patch: VERIFICATION|process|rayford
96
+
97
+ - **Target:** `ship/SKILL.md`
98
+ - **Harness step:** VERIFICATION
99
+ - **Category:** process
100
+ - **Occurrences:** 5
101
+ - **Generated:** 2026-06-20T23:53:01.012Z
102
+ - **Action:** Add mechanical check to ship SKILL.md at VERIFICATION step to prevent: behavioral-correction-verify-before-assuming
103
+ - **Failures:**
104
+ - behavioral-correction-verify-before-assuming
105
+ - skipped-test-deployment-stage-went-directly-to-main
106
+ - mild-correction-latest-image-not-deployed-as-stated
107
+ - pointing-out-that-test-success-doesnt-validate-current
108
+ - assumed-token-expiry-without-verifying-actual-status-first
109
+
110
+ ---
111
+
112
+ ## Patch: EXECUTION|process|marcus
113
+
114
+ - **Target:** `ship/SKILL.md`
115
+ - **Harness step:** EXECUTION
116
+ - **Category:** process
117
+ - **Occurrences:** 4
118
+ - **Generated:** 2026-06-20T23:53:01.012Z
119
+ - **Action:** Add mechanical check to ship SKILL.md at EXECUTION step to prevent: interruption-stop-before-proceeding-further
120
+ - **Failures:**
121
+ - interruption-stop-before-proceeding-further
122
+ - claimed-dashboard-live-but-data-not-actually-displaying
123
+ - correction-flag-was-in-makefile-i-should-have
124
+ - unclear-instruction-what-needs-confirming
125
+
126
+ ---
127
+
128
+ ## Patch: VERIFICATION|process|serena
129
+
130
+ - **Target:** `ship/SKILL.md`
131
+ - **Harness step:** VERIFICATION
132
+ - **Category:** process
133
+ - **Occurrences:** 2
134
+ - **Generated:** 2026-06-20T23:53:01.012Z
135
+ - **Action:** Add mechanical check to ship SKILL.md at VERIFICATION step to prevent: clarification-request-wants-to-verify-template-source-before
136
+ - **Failures:**
137
+ - clarification-request-wants-to-verify-template-source-before
138
+ - solution-incomplete-only-addresses-local-machine-not-multiuser
139
+
140
+ ---
141
+
142
+ ## Patch: EXECUTION|process|quinn
143
+
144
+ - **Target:** `ship/SKILL.md`
145
+ - **Harness step:** EXECUTION
146
+ - **Category:** process
147
+ - **Occurrences:** 2
148
+ - **Generated:** 2026-06-20T23:53:01.012Z
149
+ - **Action:** Add mechanical check to ship SKILL.md at EXECUTION step to prevent: seeking-clear-resolution-after-unclear-guidance-on-stale
150
+ - **Failures:**
151
+ - seeking-clear-resolution-after-unclear-guidance-on-stale
152
+ - pointing-out-omission-in-account-details-validation
153
+
154
+ ---
155
+
156
+ ## Patch: PLANNING|structural|serena
157
+
158
+ - **Target:** `ship/SKILL.md`
159
+ - **Harness step:** PLANNING
160
+ - **Category:** structural
161
+ - **Occurrences:** 1
162
+ - **Generated:** 2026-06-20T23:53:01.012Z
163
+ - **Action:** Add structural guard to HARNESS-STANDARD.md PLANNING section AND ship SKILL.md
164
+ - **Failures:**
165
+ - correction-presented-design-diverges-from-prd
166
+
167
+ ---
168
+
169
+ ## Patch: DISCOVERY|process|marcus
170
+
171
+ - **Target:** `ship/SKILL.md`
172
+ - **Harness step:** DISCOVERY
173
+ - **Category:** process
174
+ - **Occurrences:** 1
175
+ - **Generated:** 2026-06-20T23:53:01.012Z
176
+ - **Action:** Add mechanical check to ship SKILL.md at DISCOVERY step to prevent: frustrated-by-incompletefailed-message-needs-clarification
177
+ - **Failures:**
178
+ - frustrated-by-incompletefailed-message-needs-clarification
179
+
180
+ ---
181
+
182
+ ## Patch: PLANNING|process|rook
183
+
184
+ - **Target:** `ship/SKILL.md`
185
+ - **Harness step:** PLANNING
186
+ - **Category:** process
187
+ - **Occurrences:** 1
188
+ - **Generated:** 2026-06-20T23:53:01.012Z
189
+ - **Action:** Add mechanical check to ship SKILL.md at PLANNING step to prevent: assistant-misunderstood-scope-of-remaining-work-items-question
190
+ - **Failures:**
191
+ - assistant-misunderstood-scope-of-remaining-work-items-question
192
+
193
+ ---
194
+
195
+ ## Patch: DISCOVERY|process|serena
196
+
197
+ - **Target:** `ship/SKILL.md`
198
+ - **Harness step:** DISCOVERY
199
+ - **Category:** process
200
+ - **Occurrences:** 1
201
+ - **Generated:** 2026-06-20T23:53:01.012Z
202
+ - **Action:** Add mechanical check to ship SKILL.md at DISCOVERY step to prevent: correctionclarifying-folder-hierarchy-subscriptions-folder-parent-ae-folder
203
+ - **Failures:**
204
+ - correctionclarifying-folder-hierarchy-subscriptions-folder-parent-ae-folder
205
+
206
+ ---
207
+
208
+ ## Patch: VERIFICATION|process|marcus
209
+
210
+ - **Target:** `ship/SKILL.md`
211
+ - **Harness step:** VERIFICATION
212
+ - **Category:** process
213
+ - **Occurrences:** 1
214
+ - **Generated:** 2026-06-20T23:53:01.012Z
215
+ - **Action:** Add mechanical check to ship SKILL.md at VERIFICATION step to prevent: caught-rayford-in-contradictory-claims-about-test-verification
216
+ - **Failures:**
217
+ - caught-rayford-in-contradictory-claims-about-test-verification
218
+
219
+ ---
220
+
221
+ ## Patch: EXECUTION|process|rook
222
+
223
+ - **Target:** `ship/SKILL.md`
224
+ - **Harness step:** EXECUTION
225
+ - **Category:** process
226
+ - **Occurrences:** 1
227
+ - **Generated:** 2026-06-20T23:53:01.012Z
228
+ - **Action:** Add mechanical check to ship SKILL.md at EXECUTION step to prevent: correction-assistant-missed-named-agents-requirement
229
+ - **Failures:**
230
+ - correction-assistant-missed-named-agents-requirement
231
+
232
+ ---
233
+
234
+ ## Patch: PLANNING|process|serena
235
+
236
+ - **Target:** `ship/SKILL.md`
237
+ - **Harness step:** PLANNING
238
+ - **Category:** process
239
+ - **Occurrences:** 1
240
+ - **Generated:** 2026-06-20T23:53:01.012Z
241
+ - **Action:** Add mechanical check to ship SKILL.md at PLANNING step to prevent: questioning-salesforce-id-usage-in-finalized-plan
242
+ - **Failures:**
243
+ - questioning-salesforce-id-usage-in-finalized-plan
244
+
245
+ ---
246
+