@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
@@ -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