pgserve 2.1.3 → 2.2.1

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 (235) hide show
  1. package/CHANGELOG.md +96 -0
  2. package/README.md +105 -1
  3. package/bin/autopg-wrapper.cjs +16 -0
  4. package/bin/pgserve-wrapper.cjs +32 -6
  5. package/bin/postgres-server.js +56 -0
  6. package/console/README.md +131 -0
  7. package/console/api.js +173 -0
  8. package/console/app.jsx +483 -0
  9. package/console/colors_and_type.css +227 -0
  10. package/console/components.jsx +167 -0
  11. package/console/console.css +1666 -0
  12. package/console/data.jsx +350 -0
  13. package/console/index.html +31 -0
  14. package/console/screens/databases.jsx +5 -0
  15. package/console/screens/health.jsx +5 -0
  16. package/console/screens/ingress.jsx +5 -0
  17. package/console/screens/optimizer.jsx +5 -0
  18. package/console/screens/rlm-sim.jsx +5 -0
  19. package/console/screens/rlm-trace.jsx +5 -0
  20. package/console/screens/security.jsx +5 -0
  21. package/console/screens/settings.jsx +611 -0
  22. package/console/screens/sql.jsx +5 -0
  23. package/console/screens/sync.jsx +5 -0
  24. package/console/screens/tables.jsx +5 -0
  25. package/console/tweaks-panel.jsx +425 -0
  26. package/package.json +14 -2
  27. package/scripts/postinstall.cjs +60 -0
  28. package/src/cli-config.cjs +310 -0
  29. package/src/cli-install.cjs +112 -11
  30. package/src/cli-restart.cjs +228 -0
  31. package/src/cli-ui.cjs +580 -0
  32. package/src/cluster.js +43 -38
  33. package/src/postgres.js +141 -19
  34. package/src/settings-loader.cjs +235 -0
  35. package/src/settings-migrate.cjs +212 -0
  36. package/src/settings-pg-args.cjs +146 -0
  37. package/src/settings-schema.cjs +422 -0
  38. package/src/settings-validator.cjs +416 -0
  39. package/src/settings-writer.cjs +288 -0
  40. package/src/upgrade/index.js +65 -0
  41. package/src/upgrade/runner.js +23 -0
  42. package/src/upgrade/steps/binary-cache-flush.js +67 -0
  43. package/src/upgrade/steps/consumer-signal.js +40 -0
  44. package/src/upgrade/steps/env-refresh.js +89 -0
  45. package/src/upgrade/steps/health-validate.js +53 -0
  46. package/src/upgrade/steps/plpgsql-resolve.js +66 -0
  47. package/src/upgrade/steps/port-reconcile.js +52 -0
  48. package/.claude/context/windows-debug.md +0 -119
  49. package/.genie/AGENTS.md +0 -15
  50. package/.genie/agents/README.md +0 -110
  51. package/.genie/agents/analyze.md +0 -176
  52. package/.genie/agents/forge.md +0 -290
  53. package/.genie/agents/garbage-cleaner.md +0 -324
  54. package/.genie/agents/garbage-collector.md +0 -596
  55. package/.genie/agents/github-issue-gc.md +0 -618
  56. package/.genie/agents/review.md +0 -380
  57. package/.genie/agents/semantic-analyzer/find-duplicates.md +0 -90
  58. package/.genie/agents/semantic-analyzer/find-orphans.md +0 -99
  59. package/.genie/agents/semantic-analyzer.md +0 -101
  60. package/.genie/agents/update.md +0 -182
  61. package/.genie/agents/wish.md +0 -357
  62. package/.genie/brainstorms/pgserve-v2/DESIGN.md +0 -174
  63. package/.genie/code/AGENTS.md +0 -694
  64. package/.genie/code/agents/audit/risk.md +0 -173
  65. package/.genie/code/agents/audit/security.md +0 -189
  66. package/.genie/code/agents/audit.md +0 -145
  67. package/.genie/code/agents/challenge.md +0 -230
  68. package/.genie/code/agents/change-reviewer.md +0 -295
  69. package/.genie/code/agents/code-garbage-collector.md +0 -425
  70. package/.genie/code/agents/code-quality.md +0 -410
  71. package/.genie/code/agents/commit-suggester.md +0 -255
  72. package/.genie/code/agents/commit.md +0 -124
  73. package/.genie/code/agents/consensus.md +0 -204
  74. package/.genie/code/agents/daily-standup.md +0 -722
  75. package/.genie/code/agents/docgen.md +0 -48
  76. package/.genie/code/agents/explore.md +0 -79
  77. package/.genie/code/agents/fix.md +0 -100
  78. package/.genie/code/agents/git/commit-advisory.md +0 -219
  79. package/.genie/code/agents/git/workflows/issue.md +0 -244
  80. package/.genie/code/agents/git/workflows/pr.md +0 -179
  81. package/.genie/code/agents/git/workflows/release.md +0 -460
  82. package/.genie/code/agents/git/workflows/report.md +0 -342
  83. package/.genie/code/agents/git.md +0 -432
  84. package/.genie/code/agents/implementor.md +0 -161
  85. package/.genie/code/agents/install.md +0 -515
  86. package/.genie/code/agents/issue-creator.md +0 -344
  87. package/.genie/code/agents/polish.md +0 -116
  88. package/.genie/code/agents/qa.md +0 -653
  89. package/.genie/code/agents/refactor.md +0 -294
  90. package/.genie/code/agents/release.md +0 -1129
  91. package/.genie/code/agents/roadmap.md +0 -885
  92. package/.genie/code/agents/tests.md +0 -557
  93. package/.genie/code/agents/tracer.md +0 -50
  94. package/.genie/code/agents/update/upstream-update.md +0 -85
  95. package/.genie/code/agents/update/versions/generic-update.md +0 -305
  96. package/.genie/code/agents/vibe.md +0 -1317
  97. package/.genie/code/spells/agent-configuration.md +0 -58
  98. package/.genie/code/spells/automated-rc-publishing.md +0 -106
  99. package/.genie/code/spells/branch-tracker-guidance.md +0 -28
  100. package/.genie/code/spells/debug.md +0 -320
  101. package/.genie/code/spells/emoji-naming-convention.md +0 -303
  102. package/.genie/code/spells/evidence-storage.md +0 -26
  103. package/.genie/code/spells/file-naming-rules.md +0 -35
  104. package/.genie/code/spells/forge-code-blueprints.md +0 -195
  105. package/.genie/code/spells/genie-integration.md +0 -153
  106. package/.genie/code/spells/publishing-protocol.md +0 -61
  107. package/.genie/code/spells/team-consultation-protocol.md +0 -284
  108. package/.genie/code/spells/tool-requirements.md +0 -20
  109. package/.genie/code/spells/triad-maintenance-protocol.md +0 -154
  110. package/.genie/code/teams/tech-council/council.md +0 -328
  111. package/.genie/code/teams/tech-council/jt.md +0 -352
  112. package/.genie/code/teams/tech-council/nayr.md +0 -305
  113. package/.genie/code/teams/tech-council/oettam.md +0 -375
  114. package/.genie/neurons/README.md +0 -193
  115. package/.genie/neurons/forge.md +0 -106
  116. package/.genie/neurons/genie.md +0 -63
  117. package/.genie/neurons/review.md +0 -106
  118. package/.genie/neurons/wish.md +0 -104
  119. package/.genie/product/README.md +0 -20
  120. package/.genie/product/cli-automation.md +0 -359
  121. package/.genie/product/environment.md +0 -60
  122. package/.genie/product/mission.md +0 -60
  123. package/.genie/product/roadmap.md +0 -44
  124. package/.genie/product/tech-stack.md +0 -34
  125. package/.genie/product/templates/context-template.md +0 -218
  126. package/.genie/product/templates/qa-done-report-template.md +0 -68
  127. package/.genie/product/templates/review-report-template.md +0 -89
  128. package/.genie/product/templates/wish-template.md +0 -120
  129. package/.genie/scripts/helpers/analyze-commit.js +0 -195
  130. package/.genie/scripts/helpers/bullet-counter.js +0 -194
  131. package/.genie/scripts/helpers/bullet-find.js +0 -289
  132. package/.genie/scripts/helpers/bullet-id.js +0 -244
  133. package/.genie/scripts/helpers/check-secrets.js +0 -237
  134. package/.genie/scripts/helpers/count-tokens.js +0 -200
  135. package/.genie/scripts/helpers/create-frontmatter.js +0 -456
  136. package/.genie/scripts/helpers/detect-markers.js +0 -293
  137. package/.genie/scripts/helpers/detect-todos.js +0 -267
  138. package/.genie/scripts/helpers/detect-unlabeled-blocks.js +0 -135
  139. package/.genie/scripts/helpers/embeddings.js +0 -344
  140. package/.genie/scripts/helpers/find-empty-sections.js +0 -158
  141. package/.genie/scripts/helpers/index.js +0 -319
  142. package/.genie/scripts/helpers/validate-frontmatter.js +0 -578
  143. package/.genie/scripts/helpers/validate-links.js +0 -207
  144. package/.genie/scripts/helpers/validate-paths.js +0 -373
  145. package/.genie/spells/README.md +0 -9
  146. package/.genie/spells/ace-protocol.md +0 -118
  147. package/.genie/spells/ask-one-at-a-time.md +0 -175
  148. package/.genie/spells/backup-analyzer.md +0 -542
  149. package/.genie/spells/blocker.md +0 -12
  150. package/.genie/spells/break-things-move-fast.md +0 -56
  151. package/.genie/spells/context-candidates.md +0 -72
  152. package/.genie/spells/context-critic.md +0 -51
  153. package/.genie/spells/defer-to-expertise.md +0 -278
  154. package/.genie/spells/delegate-dont-do.md +0 -292
  155. package/.genie/spells/error-investigation-protocol.md +0 -328
  156. package/.genie/spells/evidence-based-completion.md +0 -273
  157. package/.genie/spells/experiment.md +0 -65
  158. package/.genie/spells/file-creation-protocol.md +0 -229
  159. package/.genie/spells/forge-integration.md +0 -281
  160. package/.genie/spells/forge-orchestration.md +0 -514
  161. package/.genie/spells/gather-context.md +0 -18
  162. package/.genie/spells/global-health-check.md +0 -34
  163. package/.genie/spells/global-noop-roundtrip.md +0 -25
  164. package/.genie/spells/install-genie.md +0 -1232
  165. package/.genie/spells/install.md +0 -82
  166. package/.genie/spells/investigate-before-commit.md +0 -112
  167. package/.genie/spells/know-yourself.md +0 -288
  168. package/.genie/spells/learn.md +0 -828
  169. package/.genie/spells/mcp-diagnostic-protocol.md +0 -246
  170. package/.genie/spells/mcp-first.md +0 -124
  171. package/.genie/spells/multi-step-execution.md +0 -67
  172. package/.genie/spells/orchestration-boundary-protocol.md +0 -256
  173. package/.genie/spells/orchestrator-not-implementor.md +0 -189
  174. package/.genie/spells/prompt.md +0 -746
  175. package/.genie/spells/reflect.md +0 -404
  176. package/.genie/spells/routing-decision-matrix.md +0 -368
  177. package/.genie/spells/run-in-parallel.md +0 -12
  178. package/.genie/spells/session-state-updater-example.md +0 -196
  179. package/.genie/spells/session-state-updater.md +0 -220
  180. package/.genie/spells/track-long-running-tasks.md +0 -133
  181. package/.genie/spells/troubleshoot-infrastructure.md +0 -176
  182. package/.genie/spells/upgrade-genie.md +0 -415
  183. package/.genie/spells/url-presentation-protocol.md +0 -301
  184. package/.genie/spells/wish-initiation.md +0 -158
  185. package/.genie/spells/wish-issue-linkage.md +0 -410
  186. package/.genie/spells/wish-lifecycle.md +0 -100
  187. package/.genie/state/provider-status.json +0 -3
  188. package/.genie/state/version.json +0 -16
  189. package/.genie/wishes/canonical-pgserve-pm2-supervision/WISH.md +0 -290
  190. package/.genie/wishes/pgserve-v2/BRIEF-from-genie-pgserve.md +0 -99
  191. package/.genie/wishes/pgserve-v2/WISH.md +0 -442
  192. package/.genie/wishes/release-system-genie-pattern/WISH.md +0 -268
  193. package/.genie/wishes/release-system-genie-pattern/validation.md +0 -205
  194. package/.gitguardian.yaml +0 -29
  195. package/.gitguardianignore +0 -16
  196. package/.github/workflows/ci.yml +0 -122
  197. package/.github/workflows/release.yml +0 -289
  198. package/.github/workflows/version.yml +0 -228
  199. package/.husky/pre-commit +0 -2
  200. package/AGENTS.md +0 -433
  201. package/CLAUDE.md +0 -1
  202. package/Makefile +0 -285
  203. package/assets/icon.ico +0 -0
  204. package/bun.lock +0 -435
  205. package/bunfig.toml +0 -28
  206. package/ecosystem.config.cjs +0 -23
  207. package/eslint.config.js +0 -63
  208. package/examples/multi-tenant-demo.js +0 -104
  209. package/install.sh +0 -123
  210. package/knip.json +0 -9
  211. package/tests/audit.test.js +0 -189
  212. package/tests/backpressure.test.js +0 -167
  213. package/tests/benchmarks/runner.js +0 -1197
  214. package/tests/benchmarks/vector-generator.js +0 -368
  215. package/tests/cli-install.test.js +0 -322
  216. package/tests/control-db.test.js +0 -285
  217. package/tests/daemon-args.test.js +0 -86
  218. package/tests/daemon-control.test.js +0 -171
  219. package/tests/daemon-fingerprint-integration.test.js +0 -111
  220. package/tests/daemon-pr24-regression.test.js +0 -198
  221. package/tests/fingerprint.test.js +0 -263
  222. package/tests/fixtures/240-orphan-seed.sql +0 -30
  223. package/tests/multi-tenant.test.js +0 -374
  224. package/tests/orphan-cleanup.test.js +0 -390
  225. package/tests/pg-version-regex.test.js +0 -129
  226. package/tests/quick-bench.js +0 -135
  227. package/tests/router-handshake-retry.test.js +0 -119
  228. package/tests/router-handshake-watchdog.test.js +0 -110
  229. package/tests/sdk.test.js +0 -71
  230. package/tests/stale-postmaster-pid.test.js +0 -85
  231. package/tests/stress-test.js +0 -439
  232. package/tests/sync-perf-test.js +0 -150
  233. package/tests/tcp-listen.test.js +0 -368
  234. package/tests/tenancy.test.js +0 -403
  235. package/tests/wrapper-supervision.test.js +0 -107
@@ -1,292 +0,0 @@
1
- ---
2
- name: Delegate, Don't Do
3
- trigger: "Should I do this myself?"
4
- answer: "No, delegate to specialist"
5
- description: Orchestrators delegate, specialists implement - never do work yourself when orchestrating
6
- ---
7
-
8
- # Delegate, Don't Do
9
-
10
-
11
- **When to use:** You see work you CAN do, but you're in orchestrator mode
12
-
13
- **Trigger:** Thinking "I'll just do this myself" or "This is quick, I can handle it"
14
-
15
- **Action:** STOP → Check role → Delegate to specialist instead
16
-
17
- **Core Principle:** Orchestrators route, specialists implement. "Can do" ≠ "Should do"
18
-
19
- ## Forbidden Actions
20
-
21
- - [delegate-001] helpful=0 harmful=0: ❌ Using Edit tool for batch operations (>2 files)
22
- - [delegate-002] helpful=0 harmful=0: ❌ Manual implementation of cleanup/refactoring work
23
- - [delegate-003] helpful=0 harmful=0: ❌ Repetitive edits instead of delegating to implementor
24
- - [delegate-004] helpful=0 harmful=0: ❌ "I'll just fix this quickly" mindset for multi-file changes
25
-
26
- ## Required Workflow
27
-
28
- **If you ARE a coordinator (plan/genie/vibe):**
29
- - [delegate-005] helpful=0 harmful=0: ✅ Delegate to implementor: `mcp__genie__run with agent="implementor" and prompt="[clear spec with files, acceptance criteria]"`
30
- - [delegate-006] helpful=0 harmful=0: ✅ Use Edit tool ONLY for single surgical fixes (≤2 files)
31
- - [delegate-007] helpful=0 harmful=0: ✅ Track delegation vs manual work in context updates
32
-
33
- **If you ARE a specialist (implementor/tests/etc.):**
34
- - [delegate-008] helpful=0 harmful=0: ✅ Execute implementation directly using available tools
35
- - [delegate-009] helpful=0 harmful=0: ❌ NEVER delegate to yourself
36
- - [delegate-010] helpful=0 harmful=0: ❌ NEVER use mcp__genie__run to delegate to your own role
37
-
38
- ## Specialist Self-Awareness Check (Added 2025-10-21)
39
-
40
- **Before ANY action, specialists must ask:**
41
- 1. Am I a specialist or orchestrator? (check my role in prompt)
42
- 2. If specialist: Do I have Edit/Write/Bash/Read tools?
43
- 3. If yes: EXECUTE DIRECTLY, never delegate
44
- 4. If no: Report blocker (missing tools)
45
-
46
- **Warning signs of role confusion:**
47
- - [delegate-011] helpful=0 harmful=0: Tempted to use `mcp__genie__run` from within specialist session
48
- - [delegate-012] helpful=0 harmful=0: Thinking "I should delegate this to <my-own-role> agent"
49
- - [delegate-013] helpful=0 harmful=0: Creating sessions for work I can do directly
50
-
51
- **Evidence:** Learn agent session violated this by delegating to learn agent (RC 37 failure analysis, 2025-10-21)
52
-
53
- **When confused:**
54
- - [delegate-014] helpful=0 harmful=0: Read your own prompt file
55
- - [delegate-015] helpful=0 harmful=0: Check delegation protocol section
56
- - [delegate-016] helpful=0 harmful=0: If it says "Execution specialist" → NEVER delegate
57
- - [delegate-017] helpful=0 harmful=0: If it says "Orchestrator" → ALWAYS delegate
58
-
59
- **Pattern discovered:** Even specialists documenting delegation rules will violate them under pressure or confusion. Self-awareness checks must be explicit and executed BEFORE tool selection.
60
-
61
- ## Why This Matters
62
-
63
- - [delegate-018] helpful=0 harmful=0: **Token efficiency**: Delegation uses specialist context, not bloated coordinator context
64
- - [delegate-019] helpful=0 harmful=0: **Separation of concerns**: Orchestrators route, specialists implement
65
- - [delegate-020] helpful=0 harmful=0: **Evidence trail**: Specialist sessions = documentation
66
- - [delegate-021] helpful=0 harmful=0: **Scalability**: Parallel specialist work vs sequential manual edits
67
-
68
- ## Delegation Instinct Pattern
69
-
70
- **Core principle:** "Can do" ≠ "Should do"
71
-
72
- **Pattern discovered:** When coordinator sees work it CAN do directly (create issues, make edits), immediate instinct is "I'll just do this - I know how, it's faster."
73
-
74
- **Why this instinct is WRONG:**
75
- - [delegate-022] helpful=0 harmful=0: Role confusion (coordinator implementing)
76
- - [delegate-023] helpful=0 harmful=0: Bypasses specialist knowledge (git agent knows ALL patterns)
77
- - [delegate-024] helpful=0 harmful=0: No evidence trail (missing Done Reports)
78
- - [delegate-025] helpful=0 harmful=0: Context bloat (coordinator context vs specialist context)
79
- - [delegate-026] helpful=0 harmful=0: No scalability (sequential vs parallel work)
80
-
81
- **Correct behavior:**
82
- ```
83
- See work I can do → STOP → Check role → Delegate to specialist
84
- ```
85
-
86
- **Validation command before ANY implementation:**
87
- 1. Am I coordinator? → Delegate to specialist
88
- 2. Am I specialist? → Implement directly
89
- 3. If unsure, check SESSION-STATE.md for active agents
90
-
91
- ## State Tracking Before Deployment
92
-
93
- When delegating to implementor, ALWAYS update SESSION-STATE.md BEFORE launching the session:
94
- 1. Update SESSION-STATE.md with pending session entry
95
- 2. Launch implementor with prompt.md framework (Discovery → Implementation → Verification)
96
- 3. Update SESSION-STATE.md with actual session ID after launch
97
- 4. Pattern ensures session tracking discipline
98
-
99
- **Why:**
100
- - [delegate-027] helpful=0 harmful=0: Session coordination: SESSION-STATE.md stays current
101
- - [delegate-028] helpful=0 harmful=0: Resume capability: Can resume after restart
102
- - [delegate-029] helpful=0 harmful=0: Visibility: Human knows what's running
103
- - [delegate-030] helpful=0 harmful=0: Prompt discipline: Forces clear Discovery/Implementation/Verification structure
104
-
105
- ## Recent Violations
106
-
107
- **2025-10-16:**
108
- - [delegate-031] helpful=0 harmful=0: Made 11 Edit calls for path reference cleanup manually
109
- - [delegate-032] helpful=0 harmful=0: Should have delegated to implementor with clear spec
110
- - [delegate-033] helpful=0 harmful=0: Burned 13K tokens on repetitive edits
111
- - [delegate-034] helpful=0 harmful=0: Pattern: See cleanup work → bypass delegation → implement directly
112
- - [delegate-035] helpful=0 harmful=0: **Result**: Context bloat, poor separation of concerns
113
- - [delegate-036] helpful=0 harmful=0: **Evidence**: Session 2025-10-16 22:30 UTC
114
-
115
- **2025-10-18 - CRITICAL: Bypassed Forge for Implementation**
116
- - [delegate-037] helpful=0 harmful=0: Forge executed 2 discovery tasks correctly (commits 131af786, 0b4114c6)
117
- - [delegate-038] helpful=0 harmful=0: User said "proceed" after discoveries completed
118
- - [delegate-039] helpful=0 harmful=0: **VIOLATION**: Directly edited view.ts and resume.ts myself (commit caf65641)
119
- - [delegate-040] helpful=0 harmful=0: Should have created Forge implementation task and delegated
120
- - [delegate-041] helpful=0 harmful=0: Pattern: "Proceed" after discovery → self-execute instead of creating next Forge task
121
- - [delegate-042] helpful=0 harmful=0: **Root cause**: Perceived simplicity (2 files) led to delegation bypass
122
- - [delegate-043] helpful=0 harmful=0: **Spells violated**: @.genie/spells/forge-integration.md, @.genie/spells/delegate-dont-do.md, @.genie/spells/orchestration-boundary-protocol.md
123
- - [delegate-044] helpful=0 harmful=0: **Evidence**: Commit caf65641, wish #120-A, learn session 4b35e28c-f64e-48e3-aeb8-549e90718f21
124
-
125
- **Evidence timeline (learning progression):**
126
- 1. **2025-10-16:** Made 11 Edit calls for cleanup work (didn't catch instinct before acting)
127
- 2. **2025-10-17 22:45:** Started reading AGENTS.md to extract sections myself (caught after start)
128
- 3. **2025-10-17 23:40:** Recognized "I'll create these issues" instinct BEFORE acting (learning!)
129
- 4. **2025-10-18:** Bypassed Forge for implementation despite using it correctly for discoveries (REGRESSION!)
130
-
131
- ## Validation
132
-
133
- When encountering cleanup/refactoring/multi-file work, immediately create implementor session with clear spec, never use Edit tool for batch operations.
134
-
135
- ---
136
-
137
- ## 🔴 CRITICAL LEARNING: 2025-10-18 - Orchestration Simplification
138
-
139
- **Teaching from Felipe:** Stop over-engineering orchestration. The model is dead simple.
140
-
141
- ### The Mistake
142
- Created parallel genie sessions for task coordination, complex SESSION-STATE.md tracking, multiple orchestrator layers. Over-complicated what should be straightforward.
143
-
144
- ### The Truth (FINAL)
145
- **Three-tier model - NO EXTRA LAYERS:**
146
- 1. **Forge Tasks** = Task orchestrators (via Forge MCP)
147
- 2. **Me (Genie)** = Execute what Forge tells me
148
- 3. **Felipe** = Make decisions
149
-
150
- **That's it. Nothing else.**
151
-
152
- ### Simple Pattern (What I MUST Do)
153
- ```
154
- Forge task exists
155
-
156
- Read task requirements
157
-
158
- Do the work (assess/implement/test)
159
-
160
- Blocker? → Ask Felipe
161
-
162
- Work complete → Update Forge task + Push PR
163
- ```
164
-
165
- ### "Proceed" Interpretation Rules (Added 2025-10-18)
166
-
167
- **When user says "proceed" after discoveries complete:**
168
- - [delegate-045] helpful=0 harmful=0: ❌ WRONG: "Proceed = implement the changes yourself"
169
- - [delegate-046] helpful=0 harmful=0: ✅ CORRECT: "Proceed = create Forge implementation task"
170
-
171
- **Pattern:**
172
- ```
173
- Discovery tasks complete
174
-
175
- User says "proceed"
176
-
177
- Create NEW Forge implementation task (reference discoveries)
178
-
179
- Forge executor implements
180
-
181
- Forge executor creates commit + PR
182
- ```
183
-
184
- **Exception:** User explicitly says "bypass Forge" or "do it yourself"
185
-
186
- ### Pre-Execution Checklist (Added 2025-10-18)
187
-
188
- **Before editing ANY code file, ask:**
189
- 1. ✅ Is this part of an active Forge task?
190
- 2. ✅ If not, should I create one?
191
- 3. ✅ Am I orchestrating or implementing?
192
- 4. ✅ Is this work covered by a wish document?
193
-
194
- **Before creating ANY commit, ask:**
195
- 1. ✅ Was this work delegated to Forge?
196
- 2. ✅ Or am I the Forge executor for this task?
197
-
198
- **Size is NOT an exception:**
199
- - [delegate-078] helpful=0 harmful=0: 1 file = Forge task
200
- - [delegate-079] helpful=0 harmful=0: 10 files = Forge task
201
- - [delegate-080] helpful=0 harmful=0: 100 files = Forge task
202
- - [delegate-081] helpful=0 harmful=0: **Delegation discipline matters more than size**
203
-
204
- ### Forbidden (After 2025-10-18)
205
- - [delegate-047] helpful=0 harmful=0: ❌ Creating parallel genie sessions for "coordination"
206
- - [delegate-048] helpful=0 harmful=0: ❌ Complex SESSION-STATE.md tracking for orchestration
207
- - [delegate-049] helpful=0 harmful=0: ❌ Multiple "orchestrator" layers
208
- - [delegate-050] helpful=0 harmful=0: ❌ Thinking I need to manage parallel work
209
- - [delegate-051] helpful=0 harmful=0: ❌ SESSION-STATE tracking beyond simple Forge task status
210
-
211
- ### Required (After 2025-10-18)
212
- - [delegate-052] helpful=0 harmful=0: ✅ Read Forge task (GitHub issue linked in Forge MCP)
213
- - [delegate-053] helpful=0 harmful=0: ✅ Execute work directly (implement/test/commit)
214
- - [delegate-054] helpful=0 harmful=0: ✅ Update Forge task when complete
215
- - [delegate-055] helpful=0 harmful=0: ✅ Push PR back to main
216
- - [delegate-056] helpful=0 harmful=0: ✅ Trust Forge MCP as orchestrator
217
-
218
- ### Evidence
219
- - Learn session: f2da8704-de61-4d56-8f14-67e7b529d049 (captured learning)
220
- - Commit: 6147fff (architectural reset)
221
- - Deleted: session state file (clean MCP state)
222
-
223
- **This is CRITICAL. No more complex orchestration layers.**
224
-
225
- ---
226
-
227
- ## Role Clarity: Orchestrator vs Implementor
228
-
229
- **Core Distinction:**
230
- - [delegate-082] helpful=0 harmful=0: **Orchestrator:** Human interface, routes work, coordinates specialists, maintains conversation
231
- - [delegate-083] helpful=0 harmful=0: **Implementor/Specialist:** Executes tasks, makes file changes, implements solutions
232
-
233
- **Principle:** Orchestrator = human interface + coordinator. Implementor = file changes + execution.
234
-
235
- ### Forbidden Actions When Orchestrating
236
-
237
- - [delegate-057] helpful=0 harmful=0: ❌ Creating TodoWrite and starting execution when SESSION-STATE.md shows active agents
238
- - [delegate-058] helpful=0 harmful=0: ❌ Bypassing mcp__genie__view when resuming with active sessions
239
- - [delegate-059] helpful=0 harmful=0: ❌ Implementing work manually when implementor session exists
240
- - [delegate-060] helpful=0 harmful=0: ❌ Assuming "no messages" means "work not done" (could be MCP bug)
241
-
242
- ### Required Workflow When Resuming
243
-
244
- **When resuming session with SESSION-STATE.md references:**
245
- 1. [delegate-061] helpful=0 harmful=0: **FIRST ACTION:** Check each session: `mcp__genie__view with sessionId="<id>"`
246
- 2. [delegate-062] helpful=0 harmful=0: **Sessions found:** Resume or continue work via `mcp__genie__resume`
247
- 3. [delegate-063] helpful=0 harmful=0: **Sessions not found:** Report to Felipe, ask for guidance
248
- 4. [delegate-064] helpful=0 harmful=0: **NEVER:** Create TodoWrite + start execution when agents referenced
249
-
250
- **When Felipe says "execute directly":**
251
- - [delegate-065] helpful=0 harmful=0: ✅ Use Edit/Write/Read tools directly
252
- - [delegate-066] helpful=0 harmful=0: ✅ Create TodoWrite for tracking
253
- - [delegate-067] helpful=0 harmful=0: ✅ Execute implementation yourself
254
-
255
- **When Felipe does NOT say "execute directly":**
256
- - [delegate-068] helpful=0 harmful=0: ✅ Check sessions FIRST
257
- - [delegate-069] helpful=0 harmful=0: ✅ Delegate to implementor via MCP
258
- - [delegate-070] helpful=0 harmful=0: ❌ NEVER execute implementation yourself
259
-
260
- ### Evidence of Role Confusion
261
-
262
- **2025-10-17 22:45 UTC:**
263
- - [delegate-084] helpful=0 harmful=0: Felipe resumed with SESSION-STATE.md showing 2 active agents (implementor, learn)
264
- - [delegate-085] helpful=0 harmful=0: Both showed "completed" but "No messages yet" (suspected MCP bug)
265
- - [delegate-086] helpful=0 harmful=0: Instead of checking sessions first, I: Created TodoWrite immediately, Started reading AGENTS.md to extract sections MYSELF, Bypassed implementor session entirely, Began manual implementation work
266
- - [delegate-087] helpful=0 harmful=0: **Pattern:** See SESSION-STATE.md → ignore it → implement manually
267
- - [delegate-088] helpful=0 harmful=0: **Root cause:** Confusion between coordinator role (route) and implementor role (execute)
268
- - [delegate-089] helpful=0 harmful=0: **Result:** Bypassed specialist work, violated human interface principle
269
- - [delegate-090] helpful=0 harmful=0: **Felipe's feedback:** "you have subagents running with genie.... stop trying to execute tasks yourself, you're the human interface only, you can ONLY EXECUTE directly when I say so"
270
-
271
- ---
272
-
273
- ## TDD Enforcement and Done Reports
274
-
275
- **Execution patterns governing sequencing and validation:**
276
-
277
- ### TDD Protocol
278
- - [delegate-071] helpful=0 harmful=0: ✅ TDD: RED → GREEN → REFACTOR enforced for features
279
- - [delegate-072] helpful=0 harmful=0: ✅ Approval gates explicit in wishes/forge plans
280
-
281
- ### Strategic Orchestration Rules
282
- - [delegate-073] helpful=0 harmful=0: Orchestrate; don't implement. Delegate to the appropriate agents and collect evidence
283
- - [delegate-074] helpful=0 harmful=0: Approved wish → forge execution groups → implementation via subagents → review → commit advisory
284
- - [delegate-075] helpful=0 harmful=0: Each subagent produces a Done Report and references it in the final reply
285
-
286
- ### Done Report Format
287
- - [delegate-076] helpful=0 harmful=0: **Location:** `.genie/wishes/<slug>/reports/done-<agent>-<slug>-<YYYYMMDDHHmm>.md` (UTC)
288
- - [delegate-077] helpful=0 harmful=0: **Contents:** scope, files touched, commands (failure → success), risks, human follow-ups
289
-
290
- ---
291
-
292
- **Evidence:** Merged orchestrator-not-implementor.md and orchestration-protocols.md into delegate-dont-do.md on 2025-10-23 during duplicate cleanup initiative.
@@ -1,328 +0,0 @@
1
- ---
2
- name: Error Investigation Protocol
3
- trigger: "Agent shows error but unclear if real failure"
4
- answer: "Investigate with monitoring tools before panicking"
5
- description: Proper response pattern when agent feedback seems broken or unclear
6
- ---
7
-
8
- # Error Investigation Protocol
9
-
10
-
11
- **When to use:** Agent tool (Genie MCP, Forge MCP) shows error messages but system state is unclear
12
-
13
- **Trigger:** Seeing "unreachable" / "failed" / "error" messages in agent output
14
-
15
- **Action:** INVESTIGATE → VERIFY → DECIDE (never panic and bypass)
16
-
17
- ---
18
-
19
- ## The Anti-Pattern (NEVER DO THIS)
20
-
21
- ```
22
- See error message
23
-
24
- Assume system is broken
25
-
26
- Try to do work directly
27
-
28
- Create redundant sessions
29
-
30
- Bypass delegation
31
-
32
- Create chaos and lose work
33
- ```
34
-
35
- **Evidence:** RC 37 release failure (2025-10-21)
36
- - [error-001] helpful=0 harmful=0: Saw "Forge backend unreachable" in `genie view`
37
- - [error-002] helpful=0 harmful=0: Panicked and tried to execute release manually
38
- - [error-003] helpful=0 harmful=0: Created 3 redundant release agent sessions
39
- - [error-004] helpful=0 harmful=0: Meanwhile, agents ACTUALLY COMPLETED SUCCESSFULLY
40
- - [error-005] helpful=0 harmful=0: RC 37 published WITHOUT uncommitted changes
41
- - [error-006] helpful=0 harmful=0: Lost work due to panic response
42
-
43
- ---
44
-
45
- ## The Correct Pattern (ALWAYS DO THIS)
46
-
47
- ```
48
- See error message
49
-
50
- INVESTIGATE with monitoring tools
51
-
52
- Check actual system state
53
-
54
- Verify agent/process is running
55
-
56
- Trust delegation if state is healthy
57
-
58
- Wait with patience (use sleep intervals)
59
-
60
- Check results when complete
61
- ```
62
-
63
- ---
64
-
65
- ## Investigation Toolkit
66
-
67
- ### When `genie view` Shows Errors
68
-
69
- **1. Check Genie MCP connectivity:**
70
- ```
71
- mcp__genie__list_sessions
72
- ```
73
- If this works, backend is fine (ignore "unreachable" message from genie view)
74
-
75
- **2. Check session status:**
76
- ```
77
- mcp__genie__list_sessions
78
- ```
79
- Look for your session in "running" or "completed" state
80
-
81
- **3. Check process list:**
82
- ```bash
83
- ps aux | grep <executor-name>
84
- # Examples: opencode, claude, cursor, gemini
85
- ```
86
- Verify executor is running
87
-
88
- **4. Check Forge process:**
89
- ```bash
90
- ps aux | grep forge
91
- netstat -tlnp | grep 8887 # Forge default port
92
- ```
93
- Verify Forge backend is running and listening
94
-
95
- **5. Wait with monitoring intervals:**
96
- ```bash
97
- sleep 30 # Don't poll every second - be patient
98
- # Then check status again
99
- ```
100
-
101
- **6. View session details:**
102
- ```
103
- mcp__genie__view(sessionId="...", full=true)
104
- ```
105
- (Get full transcript and status details)
106
-
107
- ---
108
-
109
- ## Decision Tree
110
-
111
- ```
112
- Error message appears
113
-
114
- Check Genie MCP (list_sessions)
115
-
116
- ├─ Works → Backend is fine, trust delegation
117
- │ ↓
118
- │ Check session status
119
- │ ↓
120
- │ ├─ running → Wait patiently with sleep intervals
121
- │ ├─ completed → Work complete, check results
122
- │ ├─ success → Success, verify output
123
- │ └─ failed → Investigate failure (read logs, check diffs)
124
-
125
- └─ Fails → Backend is actually broken
126
-
127
- Check backend process
128
-
129
- ├─ Running → WebSocket/config issue
130
- │ ↓
131
- │ Check MCP server health
132
-
133
- └─ Not running → Report blocker, restart Genie MCP
134
- ```
135
-
136
- ---
137
-
138
- ## Trust But Verify Protocol
139
-
140
- ### Trust
141
- - [error-007] helpful=0 harmful=0: Agent sessions continue running even when view is broken
142
- - [error-008] helpful=0 harmful=0: Genie backend executes tasks even when CLI shows errors
143
- - [error-009] helpful=0 harmful=0: Executors (OpenCode/Claude/etc.) complete work autonomously
144
- - [error-010] helpful=0 harmful=0: System is more robust than display suggests
145
-
146
- ### Verify
147
- - [error-011] helpful=0 harmful=0: Use monitoring tools to check actual state
148
- - [error-012] helpful=0 harmful=0: Check process list to confirm execution
149
- - [error-013] helpful=0 harmful=0: Use Genie MCP to get real session status
150
- - [error-014] helpful=0 harmful=0: Wait for completion before assuming failure
151
-
152
- ### Never
153
- - [error-015] helpful=0 harmful=0: Bypass delegation due to display bugs
154
- - [error-016] helpful=0 harmful=0: Create redundant sessions without investigating
155
- - [error-017] helpful=0 harmful=0: Attempt direct execution when agents are working
156
- - [error-018] helpful=0 harmful=0: Panic and lose uncommitted work
157
-
158
- ---
159
-
160
- ## Common Display Bugs vs Real Failures
161
-
162
- ### Display Bug: "Forge backend unreachable"
163
-
164
- **Symptoms:**
165
- - [error-019] helpful=0 harmful=0: `genie view` shows "backend unreachable"
166
- - [error-020] helpful=0 harmful=0: But `mcp__genie__list_sessions` WORKS
167
- - [error-021] helpful=0 harmful=0: Process list shows executors running
168
- - [error-022] helpful=0 harmful=0: Session status shows "running"
169
-
170
- **Diagnosis:** Genie CLI display bug, not real failure
171
-
172
- **Action:** Ignore "unreachable" message, trust delegation
173
-
174
- **Root cause:** WebSocket connection issue or HTTP health check instead of MCP connectivity check
175
-
176
- ### Display Bug: "No logs available"
177
-
178
- **Symptoms:**
179
- - [error-023] helpful=0 harmful=0: `genie view` shows "(No logs available)"
180
- - [error-024] helpful=0 harmful=0: But task status shows "in-progress"
181
- - [error-025] helpful=0 harmful=0: Executor process is running
182
-
183
- **Diagnosis:** Log streaming issue, not execution failure
184
-
185
- **Action:** Monitor via Forge MCP task status instead
186
-
187
- ### Real Failure: Task Status "failed"
188
-
189
- **Symptoms:**
190
- - [error-026] helpful=0 harmful=0: Task status shows "failed"
191
- - [error-027] helpful=0 harmful=0: Executor process not running
192
- - [error-028] helpful=0 harmful=0: No recent activity in worktree
193
-
194
- **Diagnosis:** Actual execution failure
195
-
196
- **Action:** Investigate failure (read logs, check diffs, review error messages)
197
-
198
- ---
199
-
200
- ## Monitoring Best Practices
201
-
202
- ### Patience Over Polling
203
-
204
- **❌ Wrong:**
205
- ```bash
206
- while true; do
207
- check_status
208
- sleep 1 # Polling every second
209
- done
210
- ```
211
-
212
- **✅ Correct:**
213
- ```bash
214
- # Check once, then wait
215
- check_status
216
-
217
- # If in-progress, wait longer
218
- sleep 30 # or 60 seconds
219
-
220
- # Check again
221
- check_status
222
- ```
223
-
224
- ### Progressive Intervals
225
-
226
- **Pattern:**
227
- ```
228
- First check: Immediate
229
- Second check: 30 seconds later
230
- Third check: 60 seconds later
231
- Ongoing: 60-120 second intervals
232
- ```
233
-
234
- **Why:** Reduce system load, avoid spam, respect execution time
235
-
236
- ### State-Based Decisions
237
-
238
- **Don't decide based on:**
239
- - [error-029] helpful=0 harmful=0: Error messages in view output
240
- - [error-030] helpful=0 harmful=0: Missing logs
241
- - [error-031] helpful=0 harmful=0: Display timeouts
242
-
243
- **Do decide based on:**
244
- - [error-032] helpful=0 harmful=0: Task status from Forge MCP
245
- - [error-033] helpful=0 harmful=0: Process existence in `ps aux`
246
- - [error-034] helpful=0 harmful=0: Actual file changes in worktree
247
- - [error-035] helpful=0 harmful=0: Commit history in git log
248
-
249
- ---
250
-
251
- ## Evidence
252
-
253
- ### Session Demonstrating Correct Pattern (2025-10-21)
254
-
255
- **Scenario:** While analyzing RC 37 failure, encountered same "unreachable" error
256
-
257
- **Investigation:**
258
- ```bash
259
- # Checked Genie MCP connectivity
260
- mcp__genie__list_sessions
261
- # Result: SUCCESS - full session list returned
262
-
263
- # Checked session status
264
- Session 1d824e13-936b-4182-a49f-9198eb2fd087: "running"
265
-
266
- # Checked processes
267
- ps aux | grep opencode
268
- # Result: OpenCode executor running (PID 1002766)
269
-
270
- # Checked Forge
271
- ps aux | grep forge
272
- netstat -tlnp | grep 8887
273
- # Result: Forge running on port 8887
274
-
275
- # Conclusion: Display bug, not real failure
276
- # Action: Trusted delegation, waited patiently
277
- ```
278
-
279
- **Outcome:** Work continued successfully despite error messages
280
-
281
- ---
282
-
283
- ## Integration with Other Spells
284
-
285
- ### Combine with:
286
- - [error-054] helpful=0 harmful=0: `@.genie/spells/delegate-dont-do.md` - Don't bypass delegation due to errors
287
- - [error-055] helpful=0 harmful=0: `@.genie/code/spells/genie-integration.md` - Monitoring patterns for Genie MCP
288
- - [error-056] helpful=0 harmful=0: `@.genie/spells/forge-integration.md` - Forge task status checking
289
-
290
- ### When to escalate:
291
- - [error-036] helpful=0 harmful=0: Forge MCP actually fails (not just display error)
292
- - [error-037] helpful=0 harmful=0: Process definitely not running
293
- - [error-038] helpful=0 harmful=0: Task status stuck for >10 minutes with no activity
294
- - [error-039] helpful=0 harmful=0: Repeated failures with clear error patterns
295
-
296
- ---
297
-
298
- ## Future Improvements
299
-
300
- **Genie CLI fixes needed:**
301
- 1. [error-040] helpful=0 harmful=0: Fix "Forge backend unreachable" false positives
302
- 2. [error-041] helpful=0 harmful=0: Add real-time status polling to `genie view`
303
- 3. [error-042] helpful=0 harmful=0: Create `genie status` command for health checks
304
- 4. [error-043] helpful=0 harmful=0: Implement session→task→attempt mapping
305
- 5. [error-044] helpful=0 harmful=0: Use Forge advanced APIs for monitoring
306
-
307
- **See:** `.genie/reports/rc37-failure-analysis-20251021.md` for detailed recommendations
308
-
309
- ---
310
-
311
- ## Validation
312
-
313
- **Before panicking about errors, validate:**
314
- - [error-045] helpful=0 harmful=0: [ ] Checked Genie MCP connectivity (list_sessions)
315
- - [error-046] helpful=0 harmful=0: [ ] Checked session status (running vs failed)
316
- - [error-047] helpful=0 harmful=0: [ ] Checked process existence (ps aux)
317
- - [error-048] helpful=0 harmful=0: [ ] Waited appropriate interval (30-60 seconds)
318
- - [error-049] helpful=0 harmful=0: [ ] Verified this is NOT just a display bug
319
-
320
- **Only bypass delegation if:**
321
- - [error-050] helpful=0 harmful=0: [ ] Genie MCP actually fails (not display bug)
322
- - [error-051] helpful=0 harmful=0: [ ] Process confirmed not running
323
- - [error-052] helpful=0 harmful=0: [ ] Session status confirmed failed
324
- - [error-053] helpful=0 harmful=0: [ ] Blocker documented and reported
325
-
326
- ---
327
-
328
- **Remember:** Display bugs ≠ System failures. Investigate before acting. Trust but verify. 🧞🔍✅