@draht/coding-agent 2026.6.11 → 2026.7.7-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 (332) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +1 -4
  3. package/dist/bun/register-bedrock.d.ts.map +1 -1
  4. package/dist/bun/register-bedrock.js +1 -1
  5. package/dist/bun/register-bedrock.js.map +1 -1
  6. package/dist/bun/restore-sandbox-env.d.ts +4 -0
  7. package/dist/bun/restore-sandbox-env.d.ts.map +1 -1
  8. package/dist/bun/restore-sandbox-env.js +4 -0
  9. package/dist/bun/restore-sandbox-env.js.map +1 -1
  10. package/dist/cli/args.d.ts.map +1 -1
  11. package/dist/cli/args.js +4 -4
  12. package/dist/cli/args.js.map +1 -1
  13. package/dist/cli/config-selector.d.ts +4 -2
  14. package/dist/cli/config-selector.d.ts.map +1 -1
  15. package/dist/cli/config-selector.js +1 -1
  16. package/dist/cli/config-selector.js.map +1 -1
  17. package/dist/cli/file-processor.d.ts.map +1 -1
  18. package/dist/cli/file-processor.js +13 -25
  19. package/dist/cli/file-processor.js.map +1 -1
  20. package/dist/cli/session-picker.d.ts +2 -1
  21. package/dist/cli/session-picker.d.ts.map +1 -1
  22. package/dist/cli/session-picker.js +5 -4
  23. package/dist/cli/session-picker.js.map +1 -1
  24. package/dist/cli/startup-ui.d.ts +5 -1
  25. package/dist/cli/startup-ui.d.ts.map +1 -1
  26. package/dist/cli/startup-ui.js +94 -22
  27. package/dist/cli/startup-ui.js.map +1 -1
  28. package/dist/config.d.ts +6 -2
  29. package/dist/config.d.ts.map +1 -1
  30. package/dist/config.js +35 -16
  31. package/dist/config.js.map +1 -1
  32. package/dist/core/agent-session.d.ts +10 -4
  33. package/dist/core/agent-session.d.ts.map +1 -1
  34. package/dist/core/agent-session.js +124 -83
  35. package/dist/core/agent-session.js.map +1 -1
  36. package/dist/core/auth-storage.d.ts +11 -12
  37. package/dist/core/auth-storage.d.ts.map +1 -1
  38. package/dist/core/auth-storage.js +25 -26
  39. package/dist/core/auth-storage.js.map +1 -1
  40. package/dist/core/compaction/branch-summarization.d.ts +3 -1
  41. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  42. package/dist/core/compaction/branch-summarization.js +3 -3
  43. package/dist/core/compaction/branch-summarization.js.map +1 -1
  44. package/dist/core/compaction/compaction.d.ts +5 -4
  45. package/dist/core/compaction/compaction.d.ts.map +1 -1
  46. package/dist/core/compaction/compaction.js +23 -20
  47. package/dist/core/compaction/compaction.js.map +1 -1
  48. package/dist/core/export-html/vendor/marked.min.js +75 -3
  49. package/dist/core/extensions/index.d.ts +1 -1
  50. package/dist/core/extensions/index.d.ts.map +1 -1
  51. package/dist/core/extensions/index.js.map +1 -1
  52. package/dist/core/extensions/loader.d.ts +2 -3
  53. package/dist/core/extensions/loader.d.ts.map +1 -1
  54. package/dist/core/extensions/loader.js +77 -14
  55. package/dist/core/extensions/loader.js.map +1 -1
  56. package/dist/core/extensions/runner.d.ts +2 -1
  57. package/dist/core/extensions/runner.d.ts.map +1 -1
  58. package/dist/core/extensions/runner.js +33 -1
  59. package/dist/core/extensions/runner.js.map +1 -1
  60. package/dist/core/extensions/types.d.ts +29 -2
  61. package/dist/core/extensions/types.d.ts.map +1 -1
  62. package/dist/core/extensions/types.js.map +1 -1
  63. package/dist/core/http-dispatcher.d.ts +1 -0
  64. package/dist/core/http-dispatcher.d.ts.map +1 -1
  65. package/dist/core/http-dispatcher.js +45 -2
  66. package/dist/core/http-dispatcher.js.map +1 -1
  67. package/dist/core/index.d.ts +1 -1
  68. package/dist/core/index.d.ts.map +1 -1
  69. package/dist/core/index.js.map +1 -1
  70. package/dist/core/keybindings.d.ts +1 -1
  71. package/dist/core/keybindings.d.ts.map +1 -1
  72. package/dist/core/keybindings.js +3 -6
  73. package/dist/core/keybindings.js.map +1 -1
  74. package/dist/core/model-registry.d.ts +2 -1
  75. package/dist/core/model-registry.d.ts.map +1 -1
  76. package/dist/core/model-registry.js +32 -67
  77. package/dist/core/model-registry.js.map +1 -1
  78. package/dist/core/model-resolver.d.ts +11 -1
  79. package/dist/core/model-resolver.d.ts.map +1 -1
  80. package/dist/core/model-resolver.js +37 -19
  81. package/dist/core/model-resolver.js.map +1 -1
  82. package/dist/core/package-manager.d.ts +5 -2
  83. package/dist/core/package-manager.d.ts.map +1 -1
  84. package/dist/core/package-manager.js +99 -43
  85. package/dist/core/package-manager.js.map +1 -1
  86. package/dist/core/project-trust.d.ts.map +1 -1
  87. package/dist/core/project-trust.js +4 -3
  88. package/dist/core/project-trust.js.map +1 -1
  89. package/dist/core/provider-attribution.d.ts +2 -2
  90. package/dist/core/provider-attribution.d.ts.map +1 -1
  91. package/dist/core/provider-attribution.js.map +1 -1
  92. package/dist/core/provider-display-names.d.ts.map +1 -1
  93. package/dist/core/provider-display-names.js +1 -1
  94. package/dist/core/provider-display-names.js.map +1 -1
  95. package/dist/core/resolve-config-value.d.ts +7 -8
  96. package/dist/core/resolve-config-value.d.ts.map +1 -1
  97. package/dist/core/resolve-config-value.js +24 -26
  98. package/dist/core/resolve-config-value.js.map +1 -1
  99. package/dist/core/resource-loader.d.ts +3 -2
  100. package/dist/core/resource-loader.d.ts.map +1 -1
  101. package/dist/core/resource-loader.js +16 -6
  102. package/dist/core/resource-loader.js.map +1 -1
  103. package/dist/core/sdk.d.ts +9 -9
  104. package/dist/core/sdk.d.ts.map +1 -1
  105. package/dist/core/sdk.js +3 -1
  106. package/dist/core/sdk.js.map +1 -1
  107. package/dist/core/session-manager.d.ts +21 -2
  108. package/dist/core/session-manager.d.ts.map +1 -1
  109. package/dist/core/session-manager.js +121 -77
  110. package/dist/core/session-manager.js.map +1 -1
  111. package/dist/core/settings-manager.d.ts +10 -1
  112. package/dist/core/settings-manager.d.ts.map +1 -1
  113. package/dist/core/settings-manager.js +29 -3
  114. package/dist/core/settings-manager.js.map +1 -1
  115. package/dist/core/system-prompt.d.ts.map +1 -1
  116. package/dist/core/system-prompt.js +7 -7
  117. package/dist/core/system-prompt.js.map +1 -1
  118. package/dist/core/timings.d.ts +4 -2
  119. package/dist/core/timings.d.ts.map +1 -1
  120. package/dist/core/timings.js +24 -14
  121. package/dist/core/timings.js.map +1 -1
  122. package/dist/core/tools/bash.d.ts.map +1 -1
  123. package/dist/core/tools/bash.js +32 -8
  124. package/dist/core/tools/bash.js.map +1 -1
  125. package/dist/core/tools/edit-diff.d.ts +23 -4
  126. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  127. package/dist/core/tools/edit-diff.js +99 -20
  128. package/dist/core/tools/edit-diff.js.map +1 -1
  129. package/dist/core/tools/edit.d.ts.map +1 -1
  130. package/dist/core/tools/edit.js +2 -2
  131. package/dist/core/tools/edit.js.map +1 -1
  132. package/dist/core/tools/find.d.ts.map +1 -1
  133. package/dist/core/tools/find.js +19 -11
  134. package/dist/core/tools/find.js.map +1 -1
  135. package/dist/core/tools/read.d.ts.map +1 -1
  136. package/dist/core/tools/read.js +12 -25
  137. package/dist/core/tools/read.js.map +1 -1
  138. package/dist/core/trust-manager.d.ts +8 -3
  139. package/dist/core/trust-manager.d.ts.map +1 -1
  140. package/dist/core/trust-manager.js +26 -11
  141. package/dist/core/trust-manager.js.map +1 -1
  142. package/dist/index.d.ts +6 -4
  143. package/dist/index.d.ts.map +1 -1
  144. package/dist/index.js +5 -3
  145. package/dist/index.js.map +1 -1
  146. package/dist/main.d.ts +2 -2
  147. package/dist/main.d.ts.map +1 -1
  148. package/dist/main.js +47 -15
  149. package/dist/main.js.map +1 -1
  150. package/dist/migrations.d.ts.map +1 -1
  151. package/dist/migrations.js +1 -123
  152. package/dist/migrations.js.map +1 -1
  153. package/dist/modes/interactive/assets/clankolas.png +0 -0
  154. package/dist/modes/interactive/components/assistant-message.d.ts +3 -1
  155. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  156. package/dist/modes/interactive/components/assistant-message.js +23 -15
  157. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  158. package/dist/modes/interactive/components/config-selector.d.ts +34 -3
  159. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  160. package/dist/modes/interactive/components/config-selector.js +284 -29
  161. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  162. package/dist/modes/interactive/components/custom-entry.d.ts +19 -0
  163. package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -0
  164. package/dist/modes/interactive/components/custom-entry.js +52 -0
  165. package/dist/modes/interactive/components/custom-entry.js.map +1 -0
  166. package/dist/modes/interactive/components/extension-editor.d.ts +3 -1
  167. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  168. package/dist/modes/interactive/components/extension-editor.js +12 -3
  169. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  170. package/dist/modes/interactive/components/footer.d.ts +2 -2
  171. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  172. package/dist/modes/interactive/components/footer.js +4 -0
  173. package/dist/modes/interactive/components/footer.js.map +1 -1
  174. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  175. package/dist/modes/interactive/components/login-dialog.js +0 -1
  176. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  177. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  178. package/dist/modes/interactive/components/model-selector.js +2 -1
  179. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  180. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  181. package/dist/modes/interactive/components/scoped-models-selector.js +4 -1
  182. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  183. package/dist/modes/interactive/components/session-selector.d.ts +0 -1
  184. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  185. package/dist/modes/interactive/components/session-selector.js +14 -8
  186. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  187. package/dist/modes/interactive/components/settings-selector.d.ts +4 -0
  188. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  189. package/dist/modes/interactive/components/settings-selector.js +188 -16
  190. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  191. package/dist/modes/interactive/components/status-indicator.d.ts +28 -0
  192. package/dist/modes/interactive/components/status-indicator.d.ts.map +1 -0
  193. package/dist/modes/interactive/components/status-indicator.js +60 -0
  194. package/dist/modes/interactive/components/status-indicator.js.map +1 -0
  195. package/dist/modes/interactive/components/tree-selector.d.ts +1 -1
  196. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  197. package/dist/modes/interactive/components/tree-selector.js +130 -15
  198. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  199. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -1
  200. package/dist/modes/interactive/components/trust-selector.js +4 -4
  201. package/dist/modes/interactive/components/trust-selector.js.map +1 -1
  202. package/dist/modes/interactive/components/user-message.d.ts +6 -2
  203. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  204. package/dist/modes/interactive/components/user-message.js +19 -6
  205. package/dist/modes/interactive/components/user-message.js.map +1 -1
  206. package/dist/modes/interactive/interactive-mode.d.ts +13 -11
  207. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  208. package/dist/modes/interactive/interactive-mode.js +252 -233
  209. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  210. package/dist/modes/interactive/model-search.d.ts +12 -0
  211. package/dist/modes/interactive/model-search.d.ts.map +1 -0
  212. package/dist/modes/interactive/model-search.js +15 -0
  213. package/dist/modes/interactive/model-search.js.map +1 -0
  214. package/dist/modes/interactive/theme/theme-controller.d.ts +29 -0
  215. package/dist/modes/interactive/theme/theme-controller.d.ts.map +1 -0
  216. package/dist/modes/interactive/theme/theme-controller.js +102 -0
  217. package/dist/modes/interactive/theme/theme-controller.js.map +1 -0
  218. package/dist/modes/interactive/theme/theme-schema.json +2 -1
  219. package/dist/modes/interactive/theme/theme.d.ts +27 -8
  220. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  221. package/dist/modes/interactive/theme/theme.js +64 -42
  222. package/dist/modes/interactive/theme/theme.js.map +1 -1
  223. package/dist/modes/rpc/rpc-client.d.ts +19 -4
  224. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  225. package/dist/modes/rpc/rpc-client.js +14 -0
  226. package/dist/modes/rpc/rpc-client.js.map +1 -1
  227. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  228. package/dist/modes/rpc/rpc-mode.js +17 -1
  229. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  230. package/dist/modes/rpc/rpc-types.d.ts +26 -0
  231. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  232. package/dist/modes/rpc/rpc-types.js.map +1 -1
  233. package/dist/package-manager-cli.d.ts +2 -2
  234. package/dist/package-manager-cli.d.ts.map +1 -1
  235. package/dist/package-manager-cli.js +152 -48
  236. package/dist/package-manager-cli.js.map +1 -1
  237. package/dist/prompts/agents/build.md +38 -0
  238. package/dist/prompts/agents/plan.md +36 -0
  239. package/dist/prompts/agents/verify.md +36 -4
  240. package/dist/prompts/commands/brainstorm.md +162 -0
  241. package/dist/prompts/commands/discuss-phase.md +1 -1
  242. package/dist/prompts/commands/execute-phase.md +4 -1
  243. package/dist/prompts/commands/fix.md +12 -0
  244. package/dist/prompts/commands/init-project.md +1 -0
  245. package/dist/prompts/commands/map-codebase.md +1 -1
  246. package/dist/prompts/commands/new-project.md +1 -0
  247. package/dist/prompts/commands/next-milestone.md +2 -0
  248. package/dist/prompts/commands/orchestrate.md +4 -4
  249. package/dist/prompts/commands/plan-phase.md +5 -0
  250. package/dist/prompts/commands/quick.md +4 -0
  251. package/dist/prompts/commands/review.md +4 -1
  252. package/dist/prompts/commands/verify-work.md +10 -8
  253. package/dist/rpc-entry.d.ts +3 -0
  254. package/dist/rpc-entry.d.ts.map +1 -0
  255. package/dist/rpc-entry.js +10 -0
  256. package/dist/rpc-entry.js.map +1 -0
  257. package/dist/utils/child-process.d.ts +7 -4
  258. package/dist/utils/child-process.d.ts.map +1 -1
  259. package/dist/utils/child-process.js +23 -5
  260. package/dist/utils/child-process.js.map +1 -1
  261. package/dist/utils/image-convert.d.ts +1 -0
  262. package/dist/utils/image-convert.d.ts.map +1 -1
  263. package/dist/utils/image-convert.js +21 -15
  264. package/dist/utils/image-convert.js.map +1 -1
  265. package/dist/utils/image-process.d.ts +18 -0
  266. package/dist/utils/image-process.d.ts.map +1 -0
  267. package/dist/utils/image-process.js +83 -0
  268. package/dist/utils/image-process.js.map +1 -0
  269. package/dist/utils/mime.d.ts.map +1 -1
  270. package/dist/utils/mime.js +41 -0
  271. package/dist/utils/mime.js.map +1 -1
  272. package/dist/utils/shell.d.ts +1 -0
  273. package/dist/utils/shell.d.ts.map +1 -1
  274. package/dist/utils/shell.js +12 -5
  275. package/dist/utils/shell.js.map +1 -1
  276. package/dist/utils/version-check.d.ts.map +1 -1
  277. package/dist/utils/version-check.js +4 -27
  278. package/dist/utils/version-check.js.map +1 -1
  279. package/docs/extensions.md +55 -8
  280. package/docs/keybindings.md +1 -1
  281. package/docs/packages.md +2 -2
  282. package/docs/providers.md +2 -1
  283. package/docs/rpc.md +58 -0
  284. package/docs/sdk.md +50 -0
  285. package/docs/session-format.md +18 -8
  286. package/docs/settings.md +10 -0
  287. package/docs/usage.md +2 -2
  288. package/examples/extensions/README.md +1 -0
  289. package/examples/extensions/custom-compaction.ts +2 -1
  290. package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
  291. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  292. package/examples/extensions/custom-provider-anthropic/package.json +1 -1
  293. package/examples/extensions/custom-provider-gitlab-duo/index.ts +9 -5
  294. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  295. package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
  296. package/examples/extensions/entry-renderer.ts +41 -0
  297. package/examples/extensions/gondolin/package-lock.json +2 -2
  298. package/examples/extensions/gondolin/package.json +1 -1
  299. package/examples/extensions/handoff.ts +2 -2
  300. package/examples/extensions/plan-mode/index.ts +87 -37
  301. package/examples/extensions/preset.ts +10 -4
  302. package/examples/extensions/provider-payload.ts +5 -5
  303. package/examples/extensions/qna.ts +2 -2
  304. package/examples/extensions/question.ts +32 -18
  305. package/examples/extensions/questionnaire.ts +41 -28
  306. package/examples/extensions/sandbox/index.ts +2 -2
  307. package/examples/extensions/sandbox/package-lock.json +2 -2
  308. package/examples/extensions/sandbox/package.json +1 -1
  309. package/examples/extensions/subagent/agents.ts +2 -2
  310. package/examples/extensions/subagent/index.ts +9 -3
  311. package/examples/extensions/summarize.ts +2 -1
  312. package/examples/extensions/with-deps/package-lock.json +2 -2
  313. package/examples/extensions/with-deps/package.json +1 -1
  314. package/examples/sdk/02-custom-model.ts +1 -1
  315. package/examples/sdk/12-full-control.ts +2 -2
  316. package/package.json +14 -15
  317. package/prompts/agents/build.md +38 -0
  318. package/prompts/agents/plan.md +36 -0
  319. package/prompts/agents/verify.md +36 -4
  320. package/prompts/commands/brainstorm.md +162 -0
  321. package/prompts/commands/discuss-phase.md +1 -1
  322. package/prompts/commands/execute-phase.md +4 -1
  323. package/prompts/commands/fix.md +12 -0
  324. package/prompts/commands/init-project.md +1 -0
  325. package/prompts/commands/map-codebase.md +1 -1
  326. package/prompts/commands/new-project.md +1 -0
  327. package/prompts/commands/next-milestone.md +2 -0
  328. package/prompts/commands/orchestrate.md +4 -4
  329. package/prompts/commands/plan-phase.md +5 -0
  330. package/prompts/commands/quick.md +4 -0
  331. package/prompts/commands/review.md +4 -1
  332. package/prompts/commands/verify-work.md +10 -8
@@ -13,6 +13,33 @@ You are an execution agent. Your job is to implement plans precisely.
13
13
  4. Commit after each task: `draht commit-task N P T "description"`
14
14
  5. If verification fails, fix it before continuing
15
15
  6. Never skip a verify step — that's how quality dies
16
+ 7. If a plan instruction contradicts what you find in the code, STOP and report `NEEDS_CONTEXT` — do not silently obey either side
17
+
18
+ ## Evidence, Not Plausibility
19
+
20
+ A step is done when you have watched it be done.
21
+
22
+ **Procedure:**
23
+ 1. "Verified" means you ran the command and read the output in this session — not that the code looks right.
24
+ 2. Quote the decisive line of output in your summary: test counts, exit codes, the actual error text.
25
+ 3. If you did not run it, write "not verified" — never let a plausible claim wear a verified claim's clothes.
26
+
27
+ **Example:** after implementing a parser, "bun test parser: 14 pass, 0 fail" is evidence; "the parser now handles all cases" is a guess in a suit.
28
+
29
+ **Prevents:** reporting a green build nobody ever ran.
30
+
31
+ ## Competence Mimics
32
+
33
+ These feel like progress and are not:
34
+
35
+ | Looks like competence | Is actually |
36
+ |---|---|
37
+ | A test that passes on first run | Probably asserts nothing — break the code, watch it fail (red first) |
38
+ | A large diff | Unreviewable risk; the plan asked for the minimal green change |
39
+ | "Refactored while I was in there" | Scope drift that hides which change broke what |
40
+ | A confident summary of a file you skimmed | A guess — read it or say you didn't |
41
+ | Silencing a failing check to keep moving | Deleting the only warning you'll get |
42
+ | Obeying the plan where it contradicts the code | The code is reality — report the conflict |
16
43
 
17
44
  ## Tools Available
18
45
  - `draht read-plan N P` — read the plan to execute
@@ -35,6 +62,9 @@ You are an execution agent. Your job is to implement plans precisely.
35
62
  4. Fill in the summary with actual commits, files changed, notes
36
63
  5. After all plans in phase: `draht verify-phase N`
37
64
 
65
+ ## Summary Format
66
+ Verdict first (what state is the plan in), then evidence (quoted verify output per task), then remaining risk (what you did not verify, labeled as such). Never bury a failed task under completed ones.
67
+
38
68
  ## Checkpoint Handling
39
69
  - `type="auto"` → execute silently
40
70
  - `type="checkpoint:human-verify"` → STOP, show what was built, ask for confirmation
@@ -46,3 +76,11 @@ If a task fails 3 times:
46
76
  2. Mark task as failed
47
77
  3. Continue to next task (unless it depends on the failed one)
48
78
  4. Note the failure for fix planning
79
+
80
+ ## Send Gate — run before finishing
81
+
82
+ 1. **Asked** — did you build what the plan's <done> describes, not just what its literal steps said?
83
+ 2. **Evidence** — does every "done" claim quote the output that proves it, with unrun checks labeled "not verified"?
84
+ 3. **Attacked** — did each test fail before the implementation made it pass?
85
+ 4. **Ordered** — verdict first, evidence second, remaining risk last?
86
+ 5. **Wrongness** — if this work is broken, where is it most likely — and did you run that path?
@@ -12,6 +12,34 @@ You are a planning agent. Your job is to create atomic, executable plans.
12
12
  3. Maximum 5 tasks per plan
13
13
  4. Goal-backward: start from "what must be TRUE" not "what should we build"
14
14
  5. Every task needs <verify> and <done> — no ambiguity
15
+ 6. A task is atomic only if its <verify> can fail while every other task passes — if two tasks can only be checked together, they are one task
16
+ 7. Every assumption a plan rests on gets an explicit `Assumes:` line (with how to confirm it) in the plan header — unwritten assumptions become the executor's bugs
17
+
18
+ ## Read the Goal Beneath the Goal
19
+
20
+ The phase description says what to build; the plan must capture what must become true.
21
+
22
+ **Procedure:**
23
+ 1. Restate the phase goal as the change in the user's world: "after this phase, a user can X."
24
+ 2. If the goal names a mechanism ("add Redis caching"), find the outcome behind it ("p95 under 200ms") and plan toward the outcome — the mechanism is a candidate, not a requirement.
25
+ 3. If you cannot state the outcome, the phase is not plannable yet — report `NEEDS_CONTEXT` instead of planning the mechanism.
26
+
27
+ **Example:** "add retry logic to the sync job" → the outcome is "syncs recover from transient failures without human help." That truth may need idempotency more than retries; a plan built on the literal words ships retries that double-write.
28
+
29
+ **Prevents:** precisely executing the wrong plan.
30
+
31
+ ## Risk-First Ordering
32
+
33
+ Not all tasks deserve equal effort or the same position in the sequence.
34
+
35
+ **Procedure:**
36
+ 1. For each observable truth, score uncertainty (has this codebase done it before?) and blast radius (how much of the plan is invalid if it's wrong?).
37
+ 2. Order plans and tasks so the highest uncertainty × blast-radius truth is proven first.
38
+ 3. Boilerplate goes last — it never invalidates a plan; the risky part regularly does.
39
+
40
+ **Example:** a phase needs a third-party webhook plus a settings UI. The webhook contract is the risk: plan 1 proves an end-to-end webhook round-trip; the UI waits.
41
+
42
+ **Prevents:** discovering in task 9 that the foundation under tasks 1–8 cannot work.
15
43
 
16
44
  ## Tools Available
17
45
  - `draht load-phase-context N` — gather all context for a phase
@@ -41,3 +69,11 @@ You are a planning agent. Your job is to create atomic, executable plans.
41
69
  ```
42
70
 
43
71
  Task types: auto, checkpoint:human-verify, checkpoint:decision
72
+
73
+ ## Send Gate — run before finishing
74
+
75
+ 1. **Asked** — do the plans produce the outcome behind the request, not just its literal words?
76
+ 2. **Evidence** — is every claim about the codebase something you read, with assumptions written as `Assumes:` lines?
77
+ 3. **Attacked** — did you try to break your own decomposition (a truth with no task, a task with no independent check)?
78
+ 4. **Ordered** — does the riskiest truth get proven first?
79
+ 5. **Wrongness** — if these plans fail, where is it most likely — and does a task check exactly there?
@@ -12,6 +12,28 @@ You are a verification agent. Your job is to test completed work against accepta
12
12
  3. Be honest — if something doesn't work, say so
13
13
  4. Create fix plans for failures, don't just report them
14
14
 
15
+ ## Re-Derive, Don't Trust
16
+
17
+ A claim is verified when you have reproduced it, not when it sounds right.
18
+
19
+ **Procedure:**
20
+ 1. Never accept a summary's claim ("tests pass", "endpoint works") — re-run the command yourself and read the output.
21
+ 2. Every pass verdict cites its observed evidence: the command you ran and the decisive output line.
22
+ 3. For each pass, attempt one break: an input, sequence, or state the implementer probably didn't try. A pass you haven't tried to break is only "not yet failed".
23
+
24
+ **Example:** the summary says "auth middleware verified." You re-run the suite — it passes. Then you request a route with an expired token: 500 instead of 401. The claim was true and the work was still broken.
25
+
26
+ **Prevents:** rubber-stamp verification — trust laundered into evidence.
27
+
28
+ ## Known vs Guessed
29
+
30
+ Label every statement in your report:
31
+ - **observed** — you ran it and saw it
32
+ - **derived** — follows necessarily from something observed
33
+ - **assumed** — believed but unchecked, with what would check it
34
+
35
+ A verdict inherits the weakest label it rests on: an "assumed pass" is not a pass — test it or mark the deliverable partial.
36
+
15
37
  ## Tools Available
16
38
  - `draht extract-deliverables N` — list testable items
17
39
  - `draht create-fix-plan N P "issue"` — create fix plan for failures
@@ -31,7 +53,17 @@ You are a verification agent. Your job is to test completed work against accepta
31
53
  5. Update state: `draht update-state`
32
54
 
33
55
  ## Output
34
- Always end with a clear summary:
35
- - X/Y passed
36
- - Fix plans created (if any)
37
- - Recommended next action
56
+ Answer first, reasoning second, risk last:
57
+ 1. **Verdict** — X/Y passed, phase pass/fail, in the first line
58
+ 2. **Evidence** — per deliverable: what you ran, what you observed, its label (observed/derived/assumed)
59
+ 3. **Risk** — what was NOT tested and how it could bite; fix plans created; recommended next action
60
+
61
+ Never bury a failure under a list of passes.
62
+
63
+ ## Send Gate — run before finishing
64
+
65
+ 1. **Asked** — did you test what the user needs to be true, not just what the developer built?
66
+ 2. **Evidence** — is every pass backed by output you personally observed this session?
67
+ 3. **Attacked** — did you try to break each pass at least once?
68
+ 4. **Ordered** — verdict first, evidence second, risk last?
69
+ 5. **Wrongness** — if this UAT is wrong, which verdict is most likely the false one — and did you re-check it?
@@ -0,0 +1,162 @@
1
+ ---
2
+ description: "Refine a fuzzy idea into a written design spec before planning or coding"
3
+ ---
4
+
5
+ # /brainstorm
6
+
7
+ The pre-planning gate. Before draht's GSD cycle runs, before code is scaffolded, before `/new-project` or `/init-project`, converge on the idea through dialogue and write it to `.planning/specs/`. This command enforces design-first discipline.
8
+
9
+ ## Usage
10
+ ```
11
+ /brainstorm [idea or topic]
12
+ ```
13
+
14
+ Topic: $ARGUMENTS
15
+
16
+ ## Atomic Reasoning
17
+
18
+ Before asking anything, decompose the idea into atomic reasoning units:
19
+
20
+ 1. **State the logical component** — What problem does this solve? Who is it for? What changes for them when it ships?
21
+ 2. **Validate independence** — What bounded contexts will exist? What is core vs peripheral? What can be built independently?
22
+ 3. **Verify correctness** — What defines v1 success? What constraints exist (time, tech, team)? What is explicitly out of scope?
23
+
24
+ **Synthesize design strategy:**
25
+ - Ground questions in what is already on disk instead of asking what the user already told you
26
+ - Sequence questions foundational → detailed, one at a time
27
+ - Surface 2–3 approaches with trade-offs before committing
28
+ - Record decisions (not proposals) in a spec file
29
+
30
+ ## Hear the Problem Beneath the Ask
31
+
32
+ The user's words describe an artifact; the design must serve a need. They are rarely the same thing.
33
+
34
+ **Procedure:**
35
+ 1. Separate the stated artifact ("a dashboard") from the underlying need — what decision, pain, or moment does it serve?
36
+ 2. When the user names a solution, ask what it solves before refining it. Solutions stay candidates until the need is confirmed.
37
+ 3. State the need back in one sentence ("so the real problem is X — right?") and get an explicit yes before proposing any approach.
38
+
39
+ **Example:** "I want an admin dashboard" → questioning reveals they check one number, once a week → a scheduled email beats the dashboard by a month of build time.
40
+
41
+ **Prevents:** a polished spec for the wrong artifact.
42
+
43
+ ## The Hard Gate
44
+
45
+ > Do NOT invoke any planning command, write any code, scaffold any project, or take any implementation action until you have:
46
+ > 1. Asked clarifying questions one at a time
47
+ > 2. Proposed 2–3 approaches with trade-offs
48
+ > 3. Presented a structured design and the user has approved it
49
+ > 4. Written the design to `.planning/specs/YYYY-MM-DD-<slug>-design.md`
50
+
51
+ If the user pushes to skip ("just build it"), surface the trade-off: "I can scaffold something now, but skipping brainstorming usually means we throw out the first version. Are you sure?" If yes, proceed but make the assumption explicit in the spec.
52
+
53
+ ## The Process
54
+
55
+ ### 1. Explore Context
56
+
57
+ Before asking anything, read what's already on disk:
58
+ - `git log --oneline -30` — what has the user been working on recently?
59
+ - `ls -la` — what's in the project root?
60
+ - `.planning/` if it exists — is there an active project?
61
+ - `README.md`, `package.json`, any `*.md` in root — what does this codebase claim to do?
62
+
63
+ If an existing codebase is in play (extending a real project), run `draht-tools map-codebase` + `draht-tools graph-hotspots` first to ground ideation in the real structure — so brainstormed ideas don't contradict existing architecture.
64
+
65
+ Use this to ground questions in reality instead of asking things the user has already told you.
66
+
67
+ ### 2. Ask Clarifying Questions — ONE at a time
68
+
69
+ Most failed projects come from rushing past ambiguity. Ask **one focused question per message**, not a long list. Wait for the answer, then ask the next.
70
+
71
+ Question categories (sequence from foundational → detailed):
72
+ - **Goal** — who is this for? what changes for them when it ships?
73
+ - **Constraints** — deadline? budget? team size? language/stack preferences?
74
+ - **Scope** — what's in v1? what's explicitly NOT in v1?
75
+ - **Success criteria** — how do we know it works? what's the demoable outcome?
76
+ - **Domain** — what are the key nouns and verbs in this space? any existing glossary?
77
+ - **Risks** — what's the scariest part of this? what would make it fail?
78
+
79
+ If the project is obviously oversized for one cycle (e.g., "I want to build a social network"), flag it explicitly and propose decomposition into a v1 / v2 / out-of-scope split.
80
+
81
+ ### 3. Propose 2–3 Approaches With Trade-offs
82
+
83
+ Once you have enough context, propose multiple approaches:
84
+ - Approach A: the simplest path. What it sacrifices.
85
+ - Approach B: the most flexible. What it costs.
86
+ - (Optional) Approach C: the most ambitious. Why it's tempting and why it might be too much.
87
+
88
+ For each: list trade-offs in plain language (time, complexity, future flexibility, lock-in). Let the user pick — don't pre-pick for them.
89
+
90
+ ### 4. Present the Design in Sections, Each With an Approval Gate
91
+
92
+ Once an approach is chosen, present the design **section by section**, not all at once:
93
+ 1. Goal & non-goals
94
+ 2. User stories / observable truths
95
+ 3. Domain model (bounded contexts, key nouns)
96
+ 4. Architecture sketch (components, data flow)
97
+ 5. v1 scope (what ships) vs v2/out-of-scope (what doesn't)
98
+ 6. Open questions / risks
99
+
100
+ After each section, ask: "Does this match what you want, or should we adjust?" Only move to the next section once the current one is approved.
101
+
102
+ ### 5. Write the Spec to `.planning/specs/`
103
+
104
+ Once all sections are approved:
105
+
106
+ ```
107
+ .planning/specs/YYYY-MM-DD-<topic-slug>-design.md
108
+ ```
109
+
110
+ The file should include:
111
+ - Header with date and approver
112
+ - All approved sections
113
+ - Open questions section (the things you flagged but didn't resolve)
114
+ - Next step: which command picks this up (`/new-project` or `/init-project`)
115
+
116
+ ### 6. Self-Review the Written Spec
117
+
118
+ Before handing off, attack the spec as if you were paid to kill it:
119
+ - Contradictions between sections (the goal says X, the architecture implies not-X)
120
+ - Gaps (a user story with no architectural support)
121
+ - Premature commitments (specific tech choices made before they were needed)
122
+ - Domain language drift (different names for the same thing)
123
+ - The strongest case the whole design is wrong — wrong scope, wrong user, or already exists as a simpler tool. Write that case and why the design survives it into the spec's Open Questions.
124
+
125
+ Report any findings to the user and update before proceeding. A spec that was never attacked has never been tested.
126
+
127
+ ### 7. Hand Off
128
+
129
+ Direct the user to the next command:
130
+ - Greenfield with no codebase → `/new-project`
131
+ - Existing codebase → `/init-project`
132
+
133
+ The spec file becomes input to those commands.
134
+
135
+ ## Workflow
136
+
137
+ `/brainstorm` runs before any project initialization. Each later step runs in its own session (`/new` between steps):
138
+
139
+ ```
140
+ /brainstorm → /new → /new-project (or /init-project) → /new → /discuss-phase 1 → /new → /plan-phase 1 → ...
141
+ ```
142
+
143
+ ## Anti-Patterns — STOP
144
+
145
+ - **Asking multiple questions in one message** — splits the user's attention, lowers answer quality
146
+ - **Pre-deciding before they've answered** — "I'll just assume you mean X" is a failure mode
147
+ - **Skipping the alternatives** — proposing only one approach hides the trade-space
148
+ - **Writing the spec before approval** — the spec records *decisions*, not *proposals*. Get the decision first.
149
+ - **Brainstorming code** — this command is for the design, not the implementation. Resist the urge to start writing.
150
+
151
+ ## Rationalization Table
152
+
153
+ | Excuse | Reality |
154
+ |--------|---------|
155
+ | "It's a simple project, no need to brainstorm" | Simple projects also have ambiguous scope. The gate is fast for simple ones. |
156
+ | "User said 'just build it'" | They'll be unhappier when the wrong thing gets built. Surface the trade-off. |
157
+ | "I already know what they want" | Verify by stating it back and getting confirmation. |
158
+ | "Let's iterate after a first draft" | A first draft in code is more expensive to throw away than a first draft on paper. |
159
+
160
+ ## Output
161
+
162
+ Brainstorming ends with a written spec file in `.planning/specs/`. That file is the artifact. If no file is written, the command did not complete.
@@ -33,7 +33,7 @@ Before questioning, decompose this phase scope into atomic reasoning units:
33
33
  2. Identify gray areas based on what's being built
34
34
  3. Present 1-2 questions at a time about preferences
35
35
  4. If `.planning/DOMAIN.md` exists, load it and validate discovered terms against the glossary. Add any new domain terms found during discussion.
36
- 5. Record decisions with `draht-tools save-context $1`
36
+ 5. Record decisions with `draht-tools save-context $1` — label each entry **decided** (the user explicitly chose) or **assumed** (you inferred from context). Assumed entries are flagged for confirmation; a plan built on an unlabeled assumption fails silently later.
37
37
  6. Commit: `draht-tools commit-docs "capture phase $1 context"`
38
38
 
39
39
  ## Workflow
@@ -36,6 +36,7 @@ Before executing, decompose this phase execution into atomic reasoning units:
36
36
  **Synthesize execution strategy:**
37
37
  - Identify parallel execution groups (plans with no shared files/dependencies)
38
38
  - Order dependent plans (plan B depends on plan A's outputs)
39
+ - Within each group, dispatch the riskiest plan first (highest uncertainty × blast radius) — its failure invalidates the rest of the phase most cheaply, before effort has been sunk into work it would obsolete
39
40
  - Map each plan to a subagent task with clear success criteria
40
41
 
41
42
  ## Steps
@@ -46,7 +47,7 @@ Before executing, decompose this phase execution into atomic reasoning units:
46
47
 
47
48
  ### Stage 1 — Implementer
48
49
  Use the `subagent` tool in **single mode** with the `implementer` agent. Prompt includes the full plan content + the TDD cycle instructions (template below). Read the final `STATUS:` line:
49
- - `DONE` → go to Stage 2.
50
+ - `DONE` → **re-derive before trusting**: a `DONE` that does not quote its verification output (test counts, command output) is treated as `DONE_WITH_CONCERNS` — run the task's `<verify>` step yourself and read the result before Stage 2. Subagent claims are inputs, not verdicts.
50
51
  - `DONE_WITH_CONCERNS` → if concerns are correctness-related, re-dispatch with a fix instruction; otherwise note and proceed.
51
52
  - `NEEDS_CONTEXT` → provide the missing info and re-dispatch.
52
53
  - `BLOCKED` → STOP, report to the user.
@@ -86,6 +87,8 @@ For each <task> in the plan, follow this TDD cycle:
86
87
  Domain rules: Use ubiquitous language from .planning/DOMAIN.md (read it). Do not import across bounded context boundaries.
87
88
  Checkpoint handling: type="auto" → execute silently. type="checkpoint:human-verify" → stop and report back what was built. type="checkpoint:decision" → stop and report the options.
88
89
 
90
+ Evidence rule: quote the decisive output of every test run and <verify> step in your report (pass/fail counts, exit codes, error text). Unquoted claims will be re-run by the orchestrator. If a plan instruction contradicts what you find in the code, stop and report NEEDS_CONTEXT — do not silently obey either side.
91
+
89
92
  End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED` per the agent contract.
90
93
 
91
94
  Important: Do NOT run draht, draht-tools, draht help, or pi commands. Use only standard tools (read, bash, edit, write, grep, find, ls).
@@ -19,6 +19,14 @@ Issue: $ARGUMENTS
19
19
 
20
20
  Symptom fixes are failure. If you find yourself proposing a "quick fix for now, investigate later", STOP and return to Phase 1.
21
21
 
22
+ ## The Report Is a Symptom, Not a Diagnosis
23
+
24
+ **Procedure:** Restate the failure as observable behavior — "X happens when Y; expected Z" — before touching anything. If the user names a cause ("the cache is stale"), treat it as Hypothesis #0: it enters Phase 3 like any other hypothesis and does not skip Phase 1.
25
+
26
+ **Example:** "fix the stale cache bug" — Phase 1 traces the data flow and finds the cache is fine; the query behind it silently drops a filter. The fix lands in the query.
27
+
28
+ **Prevents:** shipping a correct fix to the wrong component.
29
+
22
30
  ## Red Flags — STOP
23
31
 
24
32
  Stop immediately if you catch yourself:
@@ -54,6 +62,7 @@ Walk through these steps and report on each:
54
62
  3. Check recent changes — `git log --oneline -20` and `git diff HEAD~5` against affected files.
55
63
  4. Trace data flow upward until you find the source. Fix at source, not at symptom.
56
64
  5. State the root cause as one sentence: "X happens because Y at <file:line>."
65
+ 6. Label every statement in your report: observed (you ran it and saw it), derived (follows necessarily from evidence), or assumed (unchecked — say what would check it). A root cause resting on an assumption is a hypothesis, not a diagnosis.
57
66
 
58
67
  End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
59
68
  Do NOT run draht, draht-tools, or pi commands.
@@ -105,6 +114,8 @@ If Phase 2 reveals a different root cause, go back to Phase 1.
105
114
  | "I'll write the test after I confirm the fix" | Untested fixes don't stick. |
106
115
  | "I'll just try things and see what works" | Can't isolate what worked. Creates new bugs. |
107
116
  | "I already manually tested it" | A reproducing test is the only durable proof. |
117
+ | "The user already told me the cause" | The reporter saw the symptom. Their diagnosis is Hypothesis #0, not a finding. |
118
+ | "The fix passed, so my diagnosis was right" | Fixes can mask. Verify the causal chain, not just the symptom's absence. |
108
119
 
109
120
  ## Rules
110
121
  - Always reproduce before fixing
@@ -112,3 +123,4 @@ If Phase 2 reveals a different root cause, go back to Phase 1.
112
123
  - Fix at source, not symptom
113
124
  - 3 failed attempts ⇒ architecture problem, stop and discuss
114
125
  - If the root cause spans multiple files, explain the chain in the commit message
126
+ - Final report order: verdict first (fixed / not fixed, root cause in one sentence), then evidence (reproducing test red→green, suite results), then risk (what the fix could regress, what stays assumed)
@@ -78,6 +78,7 @@ Each step runs in its own session (`/new` between steps). Do NOT suggest `/next-
78
78
  - Follow threads based on answers
79
79
  - Use examples ("Like Stripe Checkout, or custom?")
80
80
  - Confirm, don't assume
81
+ - When the focus names a solution ("migrate to X"), ask what problem it solves — the existing code may admit a smaller answer
81
82
  - 3-7 follow-up rounds typical
82
83
  - Respect what already exists — do not propose rewriting working code
83
84
  - Stop when you have: current state, goals, MVP scope, constraints, success criteria
@@ -45,7 +45,7 @@ Before analyzing, decompose codebase understanding into atomic reasoning units:
45
45
  - `verifier` agent: "Analyze the test infrastructure at $1. Discover: test framework(s) in use, test directory conventions, existing coverage configuration and goals, which layers have tests (unit, integration, e2e), gaps and recommendations. Output a structured test strategy report. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
46
46
 
47
47
  4. Read each subagent's `STATUS:` line. `BLOCKED` or `NEEDS_CONTEXT` from either means STOP — partial output here corrupts downstream phases. Collect subagent results and merge with the draht-tools output.
48
- 5. Create `.planning/DOMAIN.md` (if it doesn't exist) with:
48
+ 5. Create `.planning/DOMAIN.md` (if it doesn't exist). Everything in it is **inferred from code, not confirmed by the user** — mark uncertain context boundaries and ambiguous terms as `(inferred)` so later commands know to confirm rather than build on them. With:
49
49
  - `## Bounded Contexts` — one entry per discovered context with a brief description
50
50
  - `## Ubiquitous Language` — glossary of extracted domain terms
51
51
  - `## Context Map` — how bounded contexts relate (upstream/downstream, shared kernel, ACL)
@@ -70,5 +70,6 @@ Each step runs in its own session (`/new` between steps). Do NOT suggest `/next-
70
70
  - Follow threads based on answers
71
71
  - Use examples ("Like Stripe Checkout, or custom?")
72
72
  - Confirm, don't assume
73
+ - When the description names a solution ("an app with X"), ask what problem it solves — requirements record problems and outcomes; mechanisms stay candidates
73
74
  - 3-7 follow-up rounds typical
74
75
  - Stop when you have: problem, audience, MVP scope, constraints, success criteria
@@ -62,5 +62,7 @@ Before planning the next milestone, decompose progress into atomic reasoning uni
62
62
 
63
63
  ## Rules
64
64
  - Always review what was actually built, not just what was planned
65
+ - Distinguish **verified-complete** (a UAT report shows observed passes) from **believed-complete** (someone said so) — only the former counts toward requirement satisfaction; the latter goes back on the list
65
66
  - Be honest about requirements that slipped or changed scope
66
67
  - Each phase goal must be testable — "user can X" not "implement Y"
68
+ - Order the new phases risk-first: the phase carrying the highest uncertainty × blast radius comes earliest, so a wrong bet invalidates the least downstream work
@@ -15,9 +15,9 @@ Task: $ARGUMENTS
15
15
 
16
16
  Before delegating, decompose the task into atomic work units:
17
17
 
18
- 1. **State the logical components** — What sub-tasks make up this work? Which are independent?
18
+ 1. **State the logical components** — What sub-tasks make up this work? Which are independent? A sub-task is well-cut only if its success can be checked without reference to the others.
19
19
  2. **Match agents to work** — Which specialist is right for each sub-task?
20
- 3. **Determine order** — What can run in parallel vs what must be sequential?
20
+ 3. **Determine order** — What can run in parallel vs what must be sequential? Among independent sub-tasks, dispatch the riskiest first (highest uncertainty × blast radius): its failure invalidates the rest of the graph most cheaply, before effort is sunk into work it would obsolete.
21
21
  4. **Define success** — What does "done" look like for each sub-task, and for the whole?
22
22
 
23
23
  ## Agent Selection Guide
@@ -61,7 +61,7 @@ Never run quality review on a spec-non-compliant diff. This is the per-task loop
61
61
 
62
62
  Every draht agent ends its response with one of four status lines. Branch on it:
63
63
 
64
- - `STATUS: DONE` — proceed to the next step in the chain.
64
+ - `STATUS: DONE` — check the evidence before proceeding: a `DONE` that quotes no verification output (test counts, command results) is treated as `DONE_WITH_CONCERNS` — re-run the decisive check yourself. Subagent claims are inputs, not verdicts.
65
65
  - `STATUS: DONE_WITH_CONCERNS` — note the concerns. If correctness-related, address before moving on; otherwise log and continue.
66
66
  - `STATUS: NEEDS_CONTEXT` — provide the missing info and re-dispatch the same agent. Do NOT skip ahead with a guess.
67
67
  - `STATUS: BLOCKED` — STOP. Report the blocker. Do not retry the same agent on the same input — adjust inputs (more context, decompose further, different agent) or surface to the user.
@@ -72,7 +72,7 @@ Every draht agent ends its response with one of four status lines. Branch on it:
72
72
  3. Decide parallel vs chain vs fan-out vs two-stage based on dependencies
73
73
  4. Dispatch via the `subagent` tool accordingly
74
74
  5. Read each subagent's final `STATUS:` line and branch per the protocol above
75
- 6. Collect results, handle failures, report the final outcome to the user
75
+ 6. Collect results, handle failures, report to the user — outcome first (what happened, in one line), evidence second (what each agent verified, quoted), risk last (what remains unverified or assumed)
76
76
 
77
77
  ## Rules
78
78
  - Prefer parallel dispatch when possible — it's faster and each subagent has its own context
@@ -23,6 +23,7 @@ A plan is only as good as the tasks inside it. STOP and revise instead of saving
23
23
  - A task takes more than ~5 minutes — break it down further
24
24
  - The plan introduces new domain terms that are NOT in `.planning/DOMAIN.md` — update DOMAIN.md first
25
25
  - A plan touches more than one bounded context without explicit ACL — split per context
26
+ - The first plan is scaffolding/boilerplate while an unproven risk (new integration, unfamiliar API, untested pattern) sits in a later plan — reorder so the risk is proven first
26
27
 
27
28
  Run `draht-tools validate-plans $1` after saving. Fix any issues it reports before commit.
28
29
 
@@ -35,11 +36,15 @@ Before creating plans, decompose this phase goal into atomic reasoning units:
35
36
  2. **Validate independence** — Which artifacts (files, endpoints, schemas) prove this truth exists? Can it be built independently?
36
37
  3. **Verify correctness** — What test scenarios would prove this observable truth? What are the specific inputs → expected outputs?
37
38
 
39
+ **Atomicity test:** a task is atomic only if its `<verify>` can fail while every other task passes. If two tasks can only be checked together, they are one task.
40
+
38
41
  **Synthesize planning strategy:**
39
42
  - Group related observable truths into cohesive plans (2-5 tasks each)
40
43
  - Identify which plans can be created in parallel vs sequentially
41
44
  - Map each plan to specific bounded contexts and domain concepts
42
45
  - Ensure each plan produces testable, verifiable outcomes
46
+ - **Order risk-first**: score each truth by uncertainty (has this codebase done it before?) × blast radius (how much becomes invalid if it's wrong?). The plan proving the highest-scoring truth executes first; boilerplate goes last. Boilerplate never invalidates a phase — the risky part regularly does.
47
+ - Write every assumption a plan rests on as an explicit `Assumes:` line (with how to confirm it) in the plan header. Unwritten assumptions become the executor's bugs.
43
48
 
44
49
  ## Steps
45
50
  1. Run `draht-tools load-phase-context $1` to gather all context
@@ -13,6 +13,10 @@ Execute a small ad-hoc task with tracking.
13
13
 
14
14
  Task: $ARGUMENTS
15
15
 
16
+ ## "Small" Is a Claim, Not a Fact
17
+
18
+ Before planning, verify the task is actually quick: grep the blast radius (callers, imports, tests touching the target). If the change reaches further than the description implies, say so and recommend `/plan-phase`-level treatment instead of forcing it through. And if the description names a solution ("add a flag"), confirm the problem it solves — a smaller fix may exist. A "quick task" that silently grows is how untracked complexity enters a codebase.
19
+
16
20
  ## Atomic Reasoning
17
21
 
18
22
  Before executing, decompose this task into atomic reasoning units:
@@ -47,11 +47,14 @@ Before reviewing, decompose code changes into atomic reasoning units:
47
47
 
48
48
  5. Read each subagent's final `STATUS:` line.
49
49
  6. Collect and merge results.
50
- 7. Produce a unified, prioritized findings report:
50
+ 7. **Refute before reporting.** For each Critical or Important finding, attempt to kill it yourself before it reaches the report: read the code path that would make it a false positive — an upstream guard clause, a type constraint, an existing test that covers the case. A finding that survives an honest refutation attempt is **confirmed** (you traced the failing path); one you couldn't confirm is downgraded and labeled **suspected**. Reporting unattacked findings trains readers to ignore the report.
51
+ 8. Produce a unified, prioritized findings report. Verdict first: one line — mergeable or not, and why. Then findings:
51
52
  - **Critical** — must fix before merge (security `BLOCKED`, spec gaps for required deliverables, correctness issues that cause data loss / crashes)
52
53
  - **Important** — should fix (bugs, type issues, spec over-builds, missing error handling)
53
54
  - **Minor** — style, naming, optional improvements
54
55
 
56
+ Each finding carries its label (confirmed/suspected). End with residual risk: what the review did NOT cover (files skipped, paths not traced) — a review that claims total coverage it doesn't have is worse than a scoped one.
57
+
55
58
  ## Reading STATUS
56
59
  - Any `STATUS: BLOCKED` → its findings escalate to Critical in the merged report
57
60
  - `STATUS: NEEDS_CONTEXT` → provide missing info and re-dispatch that one agent
@@ -38,23 +38,25 @@ Before verifying, decompose phase acceptance into atomic reasoning units:
38
38
  - `reviewer` agent: "Review the recent code changes for this phase. Check domain language compliance against `.planning/DOMAIN.md` if it exists — scan for identifiers not in the glossary and cross-context boundary violations. Report Must fix / Should fix / Consider. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
39
39
  - `spec-reviewer` agent: "Phase-level spec compliance check for phase $1. The phase has these plan files (each is a spec): <list of .planning/phases/<N>-*/<N>-NN-PLAN.md paths>. For each plan, evaluate whether the phase's commits implement exactly what the plan's <task> elements asked — no missing tasks, no over-builds. Use git log and git diff against the phase commit range. Output a per-plan compliance verdict with omissions and over-builds. End with `STATUS: ...`."
40
40
 
41
- 4. **Read each subagent's `STATUS:` line.** Treat the phase as failed if any of these is `BLOCKED`:
41
+ 4. **Spot-check before aggregating.** Subagent claims are inputs, not verdicts. Before accepting the verifier's `DONE`, re-run the test suite headline yourself and read the counts. Before accepting the spec-reviewer's compliance verdict, read one plan's diff yourself. A pass you only heard about is an "assumed pass" — and an assumed pass is not a pass. This costs two commands and catches the most expensive failure mode this command has: trust laundered into evidence.
42
+
43
+ 5. **Read each subagent's `STATUS:` line.** Treat the phase as failed if any of these is `BLOCKED`:
42
44
  - `verifier` (tests / lint / typecheck failed)
43
45
  - `security-auditor` (Critical or High findings)
44
46
  - `spec-reviewer` (any plan non-compliant)
45
47
  - `reviewer` (Must-fix correctness issues)
46
48
 
47
- 5. Collect results and walk user through each deliverable, incorporating findings.
48
- 6. Record results (pass/fail/partially/skip).
49
- 7. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
49
+ 6. Collect results and walk user through each deliverable, incorporating findings.
50
+ 7. Record results (pass/fail/partially/skip). Label each: **observed** (you or a subagent ran it and quoted output), **derived** (follows necessarily from something observed), or **assumed** (unchecked). Verdicts inherit the weakest label they rest on.
51
+ 8. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
50
52
  - Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
51
53
  - Spec-reviewer omissions become explicit fix-plan tasks (one task per omission)
52
- 8. Write UAT report: `draht-tools write-uat $1`
53
- - Report must include: test health summary (pass/fail/coverage), security audit results, **spec compliance summary per plan**, domain model status (any glossary violations), deliverable results
54
- 9. If all passed: mark phase complete.
54
+ 9. Write UAT report: `draht-tools write-uat $1`
55
+ - Order: **verdict first** (phase pass/fail, X/Y deliverables, in the first line), **evidence second** (test health summary with pass/fail/coverage, security audit results, spec compliance summary per plan, domain model status, deliverable results with labels), **risk last** (what was NOT tested and how it could bite). Never bury a failure under passes.
56
+ 10. If all passed: mark phase complete.
55
57
  - If more phases remain in the milestone: tell the user to start a new session and run `/discuss-phase N+1`.
56
58
  - If ALL phases in the milestone are complete: tell the user to start a new session and run `/next-milestone`.
57
- 10. If failures: route to `execute-phase $1 --gaps-only`
59
+ 11. If failures: route to `execute-phase $1 --gaps-only`
58
60
 
59
61
  ## Why a phase-level spec-reviewer
60
62
 
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=rpc-entry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rpc-entry.d.ts","sourceRoot":"","sources":["../src/rpc-entry.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\nimport { APP_NAME } from \"./config.ts\";\nimport { configureHttpDispatcher } from \"./core/http-dispatcher.ts\";\nimport { main } from \"./main.ts\";\n\nprocess.title = `${APP_NAME}-rpc`;\nprocess.env.DRAHT_CODING_AGENT = \"true\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nconfigureHttpDispatcher();\n\nmain([\"--mode\", \"rpc\", ...process.argv.slice(2)]);\n"]}
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+ import { APP_NAME } from "./config.js";
3
+ import { configureHttpDispatcher } from "./core/http-dispatcher.js";
4
+ import { main } from "./main.js";
5
+ process.title = `${APP_NAME}-rpc`;
6
+ process.env.DRAHT_CODING_AGENT = "true";
7
+ process.emitWarning = (() => { });
8
+ configureHttpDispatcher();
9
+ main(["--mode", "rpc", ...process.argv.slice(2)]);
10
+ //# sourceMappingURL=rpc-entry.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rpc-entry.js","sourceRoot":"","sources":["../src/rpc-entry.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,CAAC,KAAK,GAAG,GAAG,QAAQ,MAAM,CAAC;AAClC,OAAO,CAAC,GAAG,CAAC,kBAAkB,GAAG,MAAM,CAAC;AACxC,OAAO,CAAC,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAA+B,CAAC;AAE/D,uBAAuB,EAAE,CAAC;AAE1B,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { APP_NAME } from \"./config.ts\";\nimport { configureHttpDispatcher } from \"./core/http-dispatcher.ts\";\nimport { main } from \"./main.ts\";\n\nprocess.title = `${APP_NAME}-rpc`;\nprocess.env.DRAHT_CODING_AGENT = \"true\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nconfigureHttpDispatcher();\n\nmain([\"--mode\", \"rpc\", ...process.argv.slice(2)]);\n"]}
@@ -6,10 +6,13 @@ export declare function spawnProcessSync(command: string, args: string[], option
6
6
  /**
7
7
  * Wait for a child process to terminate without hanging on inherited stdio handles.
8
8
  *
9
- * On Windows, daemonized descendants can inherit the child's stdout/stderr pipe
10
- * handles. In that case the child emits `exit`, but `close` can hang forever even
11
- * though the original process is already gone. We wait briefly for stdio to end,
12
- * then forcibly stop tracking the inherited handles.
9
+ * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr
10
+ * pipe open. We must not resolve and destroy the streams on a fixed deadline measured
11
+ * from `exit`, or output still being written past that deadline is silently lost
12
+ * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:
13
+ * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
14
+ * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
15
+ * that never lets `close` fire) still releases us after the grace elapses.
13
16
  */
14
17
  export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;
15
18
  //# sourceMappingURL=child-process.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"child-process.d.ts","sourceRoot":"","sources":["../../src/utils/child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAClE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;AAKnG,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,kCAAkC,GACzC,gBAAgB,CAAC,MAAM,CAAC,CAI1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyE/E","sourcesContent":["import {\n\ttype ChildProcess,\n\ttype ChildProcessByStdio,\n\tspawn as nodeSpawn,\n\tspawnSync as nodeSpawnSync,\n\ttype SpawnOptions,\n\ttype SpawnOptionsWithStdioTuple,\n\ttype SpawnSyncOptionsWithStringEncoding,\n\ttype SpawnSyncReturns,\n\ttype StdioNull,\n\ttype StdioPipe,\n} from \"node:child_process\";\nimport type { Readable } from \"node:stream\";\nimport crossSpawn from \"cross-spawn\";\n\nconst EXIT_STDIO_GRACE_MS = 100;\n\nexport function spawnProcess(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>,\n): ChildProcessByStdio<null, Readable, Readable>;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess {\n\treturn process.platform === \"win32\" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);\n}\n\nexport function spawnProcessSync(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnSyncOptionsWithStringEncoding,\n): SpawnSyncReturns<string> {\n\treturn process.platform === \"win32\"\n\t\t? crossSpawn.sync(command, args, options)\n\t\t: nodeSpawnSync(command, args, options);\n}\n\n/**\n * Wait for a child process to terminate without hanging on inherited stdio handles.\n *\n * On Windows, daemonized descendants can inherit the child's stdout/stderr pipe\n * handles. In that case the child emits `exit`, but `close` can hang forever even\n * though the original process is already gone. We wait briefly for stdio to end,\n * then forcibly stop tracking the inherited handles.\n */\nexport function waitForChildProcess(child: ChildProcess): Promise<number | null> {\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet exited = false;\n\t\tlet exitCode: number | null = null;\n\t\tlet postExitTimer: NodeJS.Timeout | undefined;\n\t\tlet stdoutEnded = child.stdout === null;\n\t\tlet stderrEnded = child.stderr === null;\n\n\t\tconst cleanup = () => {\n\t\t\tif (postExitTimer) {\n\t\t\t\tclearTimeout(postExitTimer);\n\t\t\t\tpostExitTimer = undefined;\n\t\t\t}\n\t\t\tchild.removeListener(\"error\", onError);\n\t\t\tchild.removeListener(\"exit\", onExit);\n\t\t\tchild.removeListener(\"close\", onClose);\n\t\t\tchild.stdout?.removeListener(\"end\", onStdoutEnd);\n\t\t\tchild.stderr?.removeListener(\"end\", onStderrEnd);\n\t\t};\n\n\t\tconst finalize = (code: number | null) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\tchild.stdout?.destroy();\n\t\t\tchild.stderr?.destroy();\n\t\t\tresolve(code);\n\t\t};\n\n\t\tconst maybeFinalizeAfterExit = () => {\n\t\t\tif (!exited || settled) return;\n\t\t\tif (stdoutEnded && stderrEnded) {\n\t\t\t\tfinalize(exitCode);\n\t\t\t}\n\t\t};\n\n\t\tconst onStdoutEnd = () => {\n\t\t\tstdoutEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onStderrEnd = () => {\n\t\t\tstderrEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onError = (err: Error) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(err);\n\t\t};\n\n\t\tconst onExit = (code: number | null) => {\n\t\t\texited = true;\n\t\t\texitCode = code;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t\tif (!settled) {\n\t\t\t\tpostExitTimer = setTimeout(() => finalize(code), EXIT_STDIO_GRACE_MS);\n\t\t\t}\n\t\t};\n\n\t\tconst onClose = (code: number | null) => {\n\t\t\tfinalize(code);\n\t\t};\n\n\t\tchild.stdout?.once(\"end\", onStdoutEnd);\n\t\tchild.stderr?.once(\"end\", onStderrEnd);\n\t\tchild.once(\"error\", onError);\n\t\tchild.once(\"exit\", onExit);\n\t\tchild.once(\"close\", onClose);\n\t});\n}\n"]}
1
+ {"version":3,"file":"child-process.d.ts","sourceRoot":"","sources":["../../src/utils/child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAClE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;AAKnG,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,kCAAkC,GACzC,gBAAgB,CAAC,MAAM,CAAC,CAI1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwF/E","sourcesContent":["import {\n\ttype ChildProcess,\n\ttype ChildProcessByStdio,\n\tspawn as nodeSpawn,\n\tspawnSync as nodeSpawnSync,\n\ttype SpawnOptions,\n\ttype SpawnOptionsWithStdioTuple,\n\ttype SpawnSyncOptionsWithStringEncoding,\n\ttype SpawnSyncReturns,\n\ttype StdioNull,\n\ttype StdioPipe,\n} from \"node:child_process\";\nimport type { Readable } from \"node:stream\";\nimport crossSpawn from \"cross-spawn\";\n\nconst EXIT_STDIO_GRACE_MS = 100;\n\nexport function spawnProcess(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>,\n): ChildProcessByStdio<null, Readable, Readable>;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess {\n\treturn process.platform === \"win32\" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);\n}\n\nexport function spawnProcessSync(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnSyncOptionsWithStringEncoding,\n): SpawnSyncReturns<string> {\n\treturn process.platform === \"win32\"\n\t\t? crossSpawn.sync(command, args, options)\n\t\t: nodeSpawnSync(command, args, options);\n}\n\n/**\n * Wait for a child process to terminate without hanging on inherited stdio handles.\n *\n * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr\n * pipe open. We must not resolve and destroy the streams on a fixed deadline measured\n * from `exit`, or output still being written past that deadline is silently lost\n * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:\n * the grace timer is re-armed on every chunk, so an actively writing descendant keeps\n * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant\n * that never lets `close` fire) still releases us after the grace elapses.\n */\nexport function waitForChildProcess(child: ChildProcess): Promise<number | null> {\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet exited = false;\n\t\tlet exitCode: number | null = null;\n\t\tlet postExitTimer: NodeJS.Timeout | undefined;\n\t\tlet stdoutEnded = child.stdout === null;\n\t\tlet stderrEnded = child.stderr === null;\n\n\t\tconst cleanup = () => {\n\t\t\tif (postExitTimer) {\n\t\t\t\tclearTimeout(postExitTimer);\n\t\t\t\tpostExitTimer = undefined;\n\t\t\t}\n\t\t\tchild.removeListener(\"error\", onError);\n\t\t\tchild.removeListener(\"exit\", onExit);\n\t\t\tchild.removeListener(\"close\", onClose);\n\t\t\tchild.stdout?.removeListener(\"end\", onStdoutEnd);\n\t\t\tchild.stderr?.removeListener(\"end\", onStderrEnd);\n\t\t\tchild.stdout?.removeListener(\"data\", onData);\n\t\t\tchild.stderr?.removeListener(\"data\", onData);\n\t\t};\n\n\t\tconst finalize = (code: number | null) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\tchild.stdout?.destroy();\n\t\t\tchild.stderr?.destroy();\n\t\t\tresolve(code);\n\t\t};\n\n\t\tconst maybeFinalizeAfterExit = () => {\n\t\t\tif (!exited || settled) return;\n\t\t\tif (stdoutEnded && stderrEnded) {\n\t\t\t\tfinalize(exitCode);\n\t\t\t}\n\t\t};\n\n\t\tconst armIdleTimer = () => {\n\t\t\tif (postExitTimer) clearTimeout(postExitTimer);\n\t\t\tpostExitTimer = setTimeout(() => finalize(exitCode), EXIT_STDIO_GRACE_MS);\n\t\t};\n\n\t\tconst onData = () => {\n\t\t\t// Output is still arriving after exit; defer finalizing so we don't\n\t\t\t// destroy the stream mid-write and truncate the tail.\n\t\t\tif (exited && !settled) armIdleTimer();\n\t\t};\n\n\t\tconst onStdoutEnd = () => {\n\t\t\tstdoutEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onStderrEnd = () => {\n\t\t\tstderrEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onError = (err: Error) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(err);\n\t\t};\n\n\t\tconst onExit = (code: number | null) => {\n\t\t\texited = true;\n\t\t\texitCode = code;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t\tif (!settled) {\n\t\t\t\tarmIdleTimer();\n\t\t\t}\n\t\t};\n\n\t\tconst onClose = (code: number | null) => {\n\t\t\tfinalize(code);\n\t\t};\n\n\t\tchild.stdout?.once(\"end\", onStdoutEnd);\n\t\tchild.stderr?.once(\"end\", onStderrEnd);\n\t\tchild.stdout?.on(\"data\", onData);\n\t\tchild.stderr?.on(\"data\", onData);\n\t\tchild.once(\"error\", onError);\n\t\tchild.once(\"exit\", onExit);\n\t\tchild.once(\"close\", onClose);\n\t});\n}\n"]}