@apralabs/apra-fleet 0.4.1 → 0.4.3

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 (476) hide show
  1. package/README.md +53 -12
  2. package/dist/agents/backlog-groomer.md +42 -21
  3. package/dist/agents/ci-watcher.md +14 -0
  4. package/dist/agents/deployer.md +59 -46
  5. package/dist/agents/doer.md +157 -134
  6. package/dist/agents/harvester.md +31 -32
  7. package/dist/agents/integ-test-runner.md +92 -113
  8. package/dist/agents/kb-reconciler.md +40 -42
  9. package/dist/agents/plan-reviewer.md +139 -63
  10. package/dist/agents/planner.md +176 -100
  11. package/dist/agents/regression-test-runner.md +77 -81
  12. package/dist/agents/reviewer.md +69 -85
  13. package/dist/agents/schemas/integ-test-runner-output.json +1 -1
  14. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  15. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  16. package/dist/cli/agent-transform.d.ts +83 -2
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +266 -21
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +29 -11
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +7 -5
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +44 -43
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +33 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +294 -61
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/kb-directives.d.ts.map +1 -1
  32. package/dist/cli/kb-directives.js +2 -1
  33. package/dist/cli/kb-directives.js.map +1 -1
  34. package/dist/cli/register-member.d.ts.map +1 -1
  35. package/dist/cli/register-member.js +7 -3
  36. package/dist/cli/register-member.js.map +1 -1
  37. package/dist/cli/start.d.ts.map +1 -1
  38. package/dist/cli/start.js +7 -0
  39. package/dist/cli/start.js.map +1 -1
  40. package/dist/cli/uninstall.d.ts.map +1 -1
  41. package/dist/cli/uninstall.js +5 -3
  42. package/dist/cli/uninstall.js.map +1 -1
  43. package/dist/cli/watch.d.ts +26 -3
  44. package/dist/cli/watch.d.ts.map +1 -1
  45. package/dist/cli/watch.js +41 -9
  46. package/dist/cli/watch.js.map +1 -1
  47. package/dist/commands/kb-server.d.ts +3 -0
  48. package/dist/commands/kb-server.d.ts.map +1 -1
  49. package/dist/commands/kb-server.js +43 -3
  50. package/dist/commands/kb-server.js.map +1 -1
  51. package/dist/index.js +3 -3
  52. package/dist/os/git-bash-candidates.d.ts +35 -0
  53. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  54. package/dist/os/git-bash-candidates.js +46 -0
  55. package/dist/os/git-bash-candidates.js.map +1 -0
  56. package/dist/os/index.d.ts +13 -4
  57. package/dist/os/index.d.ts.map +1 -1
  58. package/dist/os/index.js +17 -2
  59. package/dist/os/index.js.map +1 -1
  60. package/dist/os/linux.d.ts +6 -0
  61. package/dist/os/linux.d.ts.map +1 -1
  62. package/dist/os/linux.js +36 -3
  63. package/dist/os/linux.js.map +1 -1
  64. package/dist/os/os-commands.d.ts +68 -2
  65. package/dist/os/os-commands.d.ts.map +1 -1
  66. package/dist/os/os-commands.js.map +1 -1
  67. package/dist/os/windows-gitbash.d.ts +98 -0
  68. package/dist/os/windows-gitbash.d.ts.map +1 -0
  69. package/dist/os/windows-gitbash.js +259 -0
  70. package/dist/os/windows-gitbash.js.map +1 -0
  71. package/dist/os/windows.d.ts +6 -0
  72. package/dist/os/windows.d.ts.map +1 -1
  73. package/dist/os/windows.js +73 -8
  74. package/dist/os/windows.js.map +1 -1
  75. package/dist/providers/agy.d.ts +118 -8
  76. package/dist/providers/agy.d.ts.map +1 -1
  77. package/dist/providers/agy.js +580 -55
  78. package/dist/providers/agy.js.map +1 -1
  79. package/dist/providers/claude.d.ts +83 -4
  80. package/dist/providers/claude.d.ts.map +1 -1
  81. package/dist/providers/claude.js +365 -12
  82. package/dist/providers/claude.js.map +1 -1
  83. package/dist/providers/codex.d.ts +7 -4
  84. package/dist/providers/codex.d.ts.map +1 -1
  85. package/dist/providers/codex.js +24 -4
  86. package/dist/providers/codex.js.map +1 -1
  87. package/dist/providers/copilot.d.ts +7 -4
  88. package/dist/providers/copilot.d.ts.map +1 -1
  89. package/dist/providers/copilot.js +27 -4
  90. package/dist/providers/copilot.js.map +1 -1
  91. package/dist/providers/index.d.ts +0 -1
  92. package/dist/providers/index.d.ts.map +1 -1
  93. package/dist/providers/index.js +0 -3
  94. package/dist/providers/index.js.map +1 -1
  95. package/dist/providers/none.d.ts +7 -4
  96. package/dist/providers/none.d.ts.map +1 -1
  97. package/dist/providers/none.js +22 -4
  98. package/dist/providers/none.js.map +1 -1
  99. package/dist/providers/opencode.d.ts +6 -3
  100. package/dist/providers/opencode.d.ts.map +1 -1
  101. package/dist/providers/opencode.js +27 -4
  102. package/dist/providers/opencode.js.map +1 -1
  103. package/dist/providers/provider.d.ts +215 -11
  104. package/dist/providers/provider.d.ts.map +1 -1
  105. package/dist/providers/provider.js +58 -2
  106. package/dist/providers/provider.js.map +1 -1
  107. package/dist/services/agent-provisioner.js +2 -2
  108. package/dist/services/agent-provisioner.js.map +1 -1
  109. package/dist/services/agy-project.d.ts +102 -0
  110. package/dist/services/agy-project.d.ts.map +1 -0
  111. package/dist/services/agy-project.js +356 -0
  112. package/dist/services/agy-project.js.map +1 -0
  113. package/dist/services/auth-socket.js +4 -4
  114. package/dist/services/auth-web.js +1 -1
  115. package/dist/services/cloud/activity.js +2 -2
  116. package/dist/services/cloud/activity.js.map +1 -1
  117. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  118. package/dist/services/cloud/lifecycle.js +33 -4
  119. package/dist/services/cloud/lifecycle.js.map +1 -1
  120. package/dist/services/context-admission.d.ts.map +1 -1
  121. package/dist/services/context-admission.js +9 -7
  122. package/dist/services/context-admission.js.map +1 -1
  123. package/dist/services/credential-cleanup.d.ts.map +1 -1
  124. package/dist/services/credential-cleanup.js +47 -10
  125. package/dist/services/credential-cleanup.js.map +1 -1
  126. package/dist/services/exit-drain.d.ts +44 -0
  127. package/dist/services/exit-drain.d.ts.map +1 -0
  128. package/dist/services/exit-drain.js +52 -0
  129. package/dist/services/exit-drain.js.map +1 -0
  130. package/dist/services/github-app.d.ts.map +1 -1
  131. package/dist/services/github-app.js +32 -4
  132. package/dist/services/github-app.js.map +1 -1
  133. package/dist/services/http-transport.d.ts +1 -0
  134. package/dist/services/http-transport.d.ts.map +1 -1
  135. package/dist/services/http-transport.js +48 -1
  136. package/dist/services/http-transport.js.map +1 -1
  137. package/dist/services/knowledge/kb-config.d.ts +42 -0
  138. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-config.js +54 -0
  140. package/dist/services/knowledge/kb-config.js.map +1 -0
  141. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  142. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  143. package/dist/services/knowledge/kb-providers.js +191 -17
  144. package/dist/services/knowledge/kb-providers.js.map +1 -1
  145. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  146. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  147. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  148. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  149. package/dist/services/member-home.d.ts +1 -1
  150. package/dist/services/member-home.d.ts.map +1 -1
  151. package/dist/services/member-home.js +15 -12
  152. package/dist/services/member-home.js.map +1 -1
  153. package/dist/services/model-pricing.d.ts.map +1 -1
  154. package/dist/services/model-pricing.js +7 -8
  155. package/dist/services/model-pricing.js.map +1 -1
  156. package/dist/services/orphan-recovery.d.ts +6 -3
  157. package/dist/services/orphan-recovery.d.ts.map +1 -1
  158. package/dist/services/orphan-recovery.js +17 -14
  159. package/dist/services/orphan-recovery.js.map +1 -1
  160. package/dist/services/preflight-check.js +2 -2
  161. package/dist/services/preflight-check.js.map +1 -1
  162. package/dist/services/secret-token.d.ts +38 -0
  163. package/dist/services/secret-token.d.ts.map +1 -0
  164. package/dist/services/secret-token.js +51 -0
  165. package/dist/services/secret-token.js.map +1 -0
  166. package/dist/services/service-manager/types.d.ts +3 -1
  167. package/dist/services/service-manager/types.d.ts.map +1 -1
  168. package/dist/services/service-manager/windows.d.ts +14 -2
  169. package/dist/services/service-manager/windows.d.ts.map +1 -1
  170. package/dist/services/service-manager/windows.js +65 -7
  171. package/dist/services/service-manager/windows.js.map +1 -1
  172. package/dist/services/shell-probe.d.ts +131 -0
  173. package/dist/services/shell-probe.d.ts.map +1 -0
  174. package/dist/services/shell-probe.js +210 -0
  175. package/dist/services/shell-probe.js.map +1 -0
  176. package/dist/services/singleton.d.ts +2 -0
  177. package/dist/services/singleton.d.ts.map +1 -1
  178. package/dist/services/singleton.js +1 -1
  179. package/dist/services/singleton.js.map +1 -1
  180. package/dist/services/ssh.d.ts.map +1 -1
  181. package/dist/services/ssh.js +60 -4
  182. package/dist/services/ssh.js.map +1 -1
  183. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  184. package/dist/services/stall/find-log-file.js +22 -16
  185. package/dist/services/stall/find-log-file.js.map +1 -1
  186. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  187. package/dist/services/stall/read-log-tail.js +26 -15
  188. package/dist/services/stall/read-log-tail.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +53 -4
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +212 -34
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  194. package/dist/services/stall/stall-poller.js +35 -42
  195. package/dist/services/stall/stall-poller.js.map +1 -1
  196. package/dist/services/strategy.d.ts +9 -0
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +119 -8
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/substitution-engine.js +2 -2
  201. package/dist/services/substitution-engine.js.map +1 -1
  202. package/dist/services/tool-registry.d.ts.map +1 -1
  203. package/dist/services/tool-registry.js +5 -3
  204. package/dist/services/tool-registry.js.map +1 -1
  205. package/dist/services/user-config.js +1 -1
  206. package/dist/services/user-config.js.map +1 -1
  207. package/dist/services/vcs/azure-devops.d.ts +67 -2
  208. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  209. package/dist/services/vcs/azure-devops.js +281 -15
  210. package/dist/services/vcs/azure-devops.js.map +1 -1
  211. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  212. package/dist/services/vcs/bitbucket.js +16 -0
  213. package/dist/services/vcs/bitbucket.js.map +1 -1
  214. package/dist/services/vcs/github.d.ts.map +1 -1
  215. package/dist/services/vcs/github.js +24 -0
  216. package/dist/services/vcs/github.js.map +1 -1
  217. package/dist/services/vcs/types.d.ts +123 -2
  218. package/dist/services/vcs/types.d.ts.map +1 -1
  219. package/dist/skills/fleet-sprint-cli/SKILL.md +20 -1
  220. package/dist/skills/pm/SKILL.md +1 -2
  221. package/dist/skills/pm/cost.md +0 -4
  222. package/dist/skills/pm/fleet-addendum.md +2 -3
  223. package/dist/tools/check-status.d.ts +7 -4
  224. package/dist/tools/check-status.d.ts.map +1 -1
  225. package/dist/tools/check-status.js +5 -3
  226. package/dist/tools/check-status.js.map +1 -1
  227. package/dist/tools/cloud-control.js +2 -2
  228. package/dist/tools/cloud-control.js.map +1 -1
  229. package/dist/tools/compose-permissions.d.ts +6 -0
  230. package/dist/tools/compose-permissions.d.ts.map +1 -1
  231. package/dist/tools/compose-permissions.js +211 -50
  232. package/dist/tools/compose-permissions.js.map +1 -1
  233. package/dist/tools/credential-store-set.js +1 -1
  234. package/dist/tools/execute-command.d.ts.map +1 -1
  235. package/dist/tools/execute-command.js +56 -29
  236. package/dist/tools/execute-command.js.map +1 -1
  237. package/dist/tools/execute-prompt.d.ts +15 -2
  238. package/dist/tools/execute-prompt.d.ts.map +1 -1
  239. package/dist/tools/execute-prompt.js +1214 -873
  240. package/dist/tools/execute-prompt.js.map +1 -1
  241. package/dist/tools/kb-capture.d.ts +2 -2
  242. package/dist/tools/kb-capture.d.ts.map +1 -1
  243. package/dist/tools/kb-capture.js +29 -5
  244. package/dist/tools/kb-capture.js.map +1 -1
  245. package/dist/tools/kb-export.d.ts +2 -2
  246. package/dist/tools/kb-export.d.ts.map +1 -1
  247. package/dist/tools/kb-export.js +3 -28
  248. package/dist/tools/kb-export.js.map +1 -1
  249. package/dist/tools/kb-feedback.d.ts.map +1 -1
  250. package/dist/tools/kb-feedback.js +3 -1
  251. package/dist/tools/kb-feedback.js.map +1 -1
  252. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  253. package/dist/tools/kb-freshness-sweep.js +3 -1
  254. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  255. package/dist/tools/kb-import.d.ts.map +1 -1
  256. package/dist/tools/kb-import.js +2 -1
  257. package/dist/tools/kb-import.js.map +1 -1
  258. package/dist/tools/kb-list.d.ts.map +1 -1
  259. package/dist/tools/kb-list.js +3 -1
  260. package/dist/tools/kb-list.js.map +1 -1
  261. package/dist/tools/kb-query.d.ts +2 -2
  262. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  263. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  264. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  265. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  266. package/dist/tools/kb-resolve-contradiction.js +3 -1
  267. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  268. package/dist/tools/kb-setup.d.ts.map +1 -1
  269. package/dist/tools/kb-setup.js +125 -20
  270. package/dist/tools/kb-setup.js.map +1 -1
  271. package/dist/tools/kb-stats.d.ts.map +1 -1
  272. package/dist/tools/kb-stats.js +64 -43
  273. package/dist/tools/kb-stats.js.map +1 -1
  274. package/dist/tools/list-members.d.ts +2 -2
  275. package/dist/tools/list-members.d.ts.map +1 -1
  276. package/dist/tools/list-members.js +7 -2
  277. package/dist/tools/list-members.js.map +1 -1
  278. package/dist/tools/member-detail.d.ts +2 -2
  279. package/dist/tools/member-detail.d.ts.map +1 -1
  280. package/dist/tools/member-detail.js +22 -3
  281. package/dist/tools/member-detail.js.map +1 -1
  282. package/dist/tools/member-reservation.d.ts +58 -1
  283. package/dist/tools/member-reservation.d.ts.map +1 -1
  284. package/dist/tools/member-reservation.js +71 -18
  285. package/dist/tools/member-reservation.js.map +1 -1
  286. package/dist/tools/monitor-task.d.ts.map +1 -1
  287. package/dist/tools/monitor-task.js +17 -2
  288. package/dist/tools/monitor-task.js.map +1 -1
  289. package/dist/tools/provision-auth.d.ts +80 -1
  290. package/dist/tools/provision-auth.d.ts.map +1 -1
  291. package/dist/tools/provision-auth.js +147 -59
  292. package/dist/tools/provision-auth.js.map +1 -1
  293. package/dist/tools/provision-vcs-auth.d.ts +96 -3
  294. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  295. package/dist/tools/provision-vcs-auth.js +254 -88
  296. package/dist/tools/provision-vcs-auth.js.map +1 -1
  297. package/dist/tools/register-member.d.ts +21 -12
  298. package/dist/tools/register-member.d.ts.map +1 -1
  299. package/dist/tools/register-member.js +141 -16
  300. package/dist/tools/register-member.js.map +1 -1
  301. package/dist/tools/remove-member.d.ts.map +1 -1
  302. package/dist/tools/remove-member.js +29 -4
  303. package/dist/tools/remove-member.js.map +1 -1
  304. package/dist/tools/revoke-vcs-auth.js +2 -2
  305. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  306. package/dist/tools/send-email.d.ts +2 -2
  307. package/dist/tools/setup-git-app.d.ts.map +1 -1
  308. package/dist/tools/setup-git-app.js +11 -7
  309. package/dist/tools/setup-git-app.js.map +1 -1
  310. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  311. package/dist/tools/setup-ssh-key.js +2 -1
  312. package/dist/tools/setup-ssh-key.js.map +1 -1
  313. package/dist/tools/shutdown-server.d.ts +2 -0
  314. package/dist/tools/shutdown-server.d.ts.map +1 -1
  315. package/dist/tools/shutdown-server.js +23 -1
  316. package/dist/tools/shutdown-server.js.map +1 -1
  317. package/dist/tools/stop-prompt.js +2 -2
  318. package/dist/tools/stop-prompt.js.map +1 -1
  319. package/dist/tools/update-agent-cli.js +2 -2
  320. package/dist/tools/update-agent-cli.js.map +1 -1
  321. package/dist/tools/update-member.d.ts +21 -12
  322. package/dist/tools/update-member.d.ts.map +1 -1
  323. package/dist/tools/update-member.js +61 -12
  324. package/dist/tools/update-member.js.map +1 -1
  325. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  326. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  327. package/dist/tools/vcs-credential-exec.js +197 -0
  328. package/dist/tools/vcs-credential-exec.js.map +1 -0
  329. package/dist/types.d.ts +24 -1
  330. package/dist/types.d.ts.map +1 -1
  331. package/dist/utils/agent-helpers.d.ts +36 -0
  332. package/dist/utils/agent-helpers.d.ts.map +1 -1
  333. package/dist/utils/agent-helpers.js +39 -1
  334. package/dist/utils/agent-helpers.js.map +1 -1
  335. package/dist/utils/log-helpers.d.ts.map +1 -1
  336. package/dist/utils/log-helpers.js +2 -2
  337. package/dist/utils/log-helpers.js.map +1 -1
  338. package/dist/utils/platform.d.ts +7 -0
  339. package/dist/utils/platform.d.ts.map +1 -1
  340. package/dist/utils/platform.js +11 -1
  341. package/dist/utils/platform.js.map +1 -1
  342. package/dist/utils/prompt-errors.d.ts.map +1 -1
  343. package/dist/utils/prompt-errors.js +7 -1
  344. package/dist/utils/prompt-errors.js.map +1 -1
  345. package/dist/utils/shell-escape.d.ts +16 -0
  346. package/dist/utils/shell-escape.d.ts.map +1 -1
  347. package/dist/utils/shell-escape.js +22 -2
  348. package/dist/utils/shell-escape.js.map +1 -1
  349. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  350. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  351. package/dist/utils/vcs-provider-detect.js +109 -0
  352. package/dist/utils/vcs-provider-detect.js.map +1 -0
  353. package/dist/utils/workspace-trust.d.ts +20 -17
  354. package/dist/utils/workspace-trust.d.ts.map +1 -1
  355. package/dist/utils/workspace-trust.js +91 -1
  356. package/dist/utils/workspace-trust.js.map +1 -1
  357. package/dist/workflows/auto-sprint.js +180 -32
  358. package/package.json +7 -5
  359. package/packages/apra-fleet-client/src/client/api.mjs +403 -12
  360. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  361. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  362. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +42 -21
  363. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +14 -0
  364. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +59 -46
  365. package/packages/apra-fleet-se/apra-pm/agents/doer.md +157 -134
  366. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +31 -32
  367. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +92 -113
  368. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +40 -42
  369. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +139 -63
  370. package/packages/apra-fleet-se/apra-pm/agents/planner.md +176 -100
  371. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +77 -81
  372. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +69 -85
  373. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
  374. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  375. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  376. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -2
  377. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -4
  378. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -3
  379. package/packages/apra-fleet-se/bin/cli.mjs +280 -3
  380. package/packages/apra-fleet-se/bin/serve.mjs +114 -5
  381. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  382. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  383. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  384. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  385. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  386. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  387. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  388. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  389. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +199 -34
  390. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  391. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  392. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  393. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  394. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  395. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
  396. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +285 -4
  397. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +3 -3
  398. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  399. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
  400. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  401. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  402. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
  403. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1054 -39
  404. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +308 -0
  405. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  406. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  407. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  408. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  409. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  410. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  411. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  412. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  413. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  414. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  415. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  416. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  417. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  418. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  419. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  420. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  421. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  422. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  423. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  424. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  425. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  426. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  427. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  428. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  429. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  430. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  431. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  432. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  433. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  434. package/packages/apra-fleet-se/fleet-sprint/runner.js +1672 -9072
  435. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  436. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +159 -0
  437. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  438. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  439. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  440. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +20 -1
  441. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  442. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  443. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  444. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  445. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  446. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  447. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  448. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +204 -19
  449. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +707 -12
  450. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  451. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  452. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +191 -43
  453. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +333 -6
  454. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +165 -0
  455. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +167 -37
  456. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  457. package/packages/apra-fleet-se/package.json +1 -1
  458. package/packages/apra-fleet-workflow/src/viewer/index.mjs +178 -1
  459. package/packages/apra-fleet-workflow/src/workflow/index.mjs +478 -32
  460. package/skills/fleet/SKILL.md +27 -16
  461. package/skills/fleet/auth-azdevops.md +57 -7
  462. package/skills/fleet/auth-bitbucket.md +5 -5
  463. package/skills/fleet/auth-github.md +7 -6
  464. package/skills/fleet/beads-conflict-resolution.md +141 -0
  465. package/skills/fleet/beads.md +16 -12
  466. package/skills/fleet/onboarding.md +6 -6
  467. package/skills/fleet/permissions.md +11 -7
  468. package/skills/fleet/profiles/node.json +1 -1
  469. package/skills/fleet/skill-matrix.md +1 -1
  470. package/skills/fleet/troubleshooting.md +4 -3
  471. package/version.json +1 -1
  472. package/dist/providers/gemini.d.ts +0 -52
  473. package/dist/providers/gemini.d.ts.map +0 -1
  474. package/dist/providers/gemini.js +0 -236
  475. package/dist/providers/gemini.js.map +0 -1
  476. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: plan-reviewer
3
- description: Reviews beads DAG structure for coverage, task size, and acceptance criteria; classifies each task complexity bucket and reads its assigned model; returns APPROVED or CHANGES NEEDED.
3
+ description: Reviews beads DAG structure for coverage, task size, and acceptance criteria; classifies each task complexity bucket and reads its assigned model; returns APPROVED or CHANGES_NEEDED.
4
4
  tools: [Read, Grep, Glob, Bash, Write, ToolSearch]
5
5
  ---
6
6
 
@@ -48,13 +48,15 @@ to satisfy a criterion as SETTLED for the rest of the cycle:
48
48
  - This binds within the current review cycle only. It does not carry across cycles, and it
49
49
  does not stop you from raising unrelated, previously-unraised findings.
50
50
 
51
- This rule exists because each review round otherwise runs blind to earlier rounds' own
52
- rulings, letting the goalposts move round to round on the same criterion even though the
53
- plan correctly implemented what a prior round said was acceptable.
54
-
55
51
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
56
52
 
53
+ <!-- if-tool: ToolSearch -->
57
54
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
55
+ <!-- else-tool: ToolSearch -->
56
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
57
+ tool it wants directly. Confirm your environment exposes those tools, then call
58
+ them as written.
59
+ <!-- end-tool: ToolSearch -->
58
60
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being planned
59
61
  for, and `hint_symbols`/`hint_modules` relevant to the features in the DAG under review.
60
62
  Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. An entry
@@ -63,7 +65,12 @@ plan correctly implemented what a prior round said was acceptable.
63
65
  an invariant), call `mcp__apra-fleet__kb_capture` immediately with type "knowledge" or
64
66
  "learning".
65
67
 
68
+ <!-- if-tool: ToolSearch -->
66
69
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
70
+ <!-- else-tool: ToolSearch -->
71
+ If those KB tools are not available in your environment (MCP server not running), skip
72
+ these steps and proceed.
73
+ <!-- end-tool: ToolSearch -->
67
74
 
68
75
  ## Step 1 -- Inspect the DAG
69
76
 
@@ -80,62 +87,101 @@ For each open feature and its tasks, run `bd show <id>` to read the full descrip
80
87
  1. **Coverage**: every open sprint goal has at least one feature that directly addresses it
81
88
  2. **Test tasks**: every feature has at least one `[test]` task
82
89
  3. **Acceptance criteria**: every task description states concretely what done looks like
83
- 4. **Task size**: no task should require more than ~3 file changes; flag larger ones
84
- 5. **Dependency wiring**: test tasks are downstream of implementation tasks (not parallel)
90
+ 4. **Task size**: a task must have crisp, verifiable acceptance criteria and be closable
91
+ in one doer pass (typically 1-4 files). Flag a task that is too LARGE to have crisp
92
+ criteria, AND flag a chain of tasks that were split only to stay small (e.g. "add
93
+ helper" / "call helper" / "test helper" as three tasks with no independent value) --
94
+ those should be fewer tasks, or at minimum one lane.
95
+ 5. **Dependency wiring**: a `[test]` task follows its `[impl]` task in the SAME lane with
96
+ a higher `streakOrder` -- splitting an impl/test pair across two lanes for convenience
97
+ is a finding. The only legitimate exception is a feature-level `[test]` task whose impl
98
+ work was itself split across multiple lanes by the sizing rules (planner.md's rule that
99
+ a lane is split "ONLY at a point where the earlier part is a self-contained, reviewable
100
+ increment"): then the test task's own lane may depend cross-lane on each of those impl
101
+ lanes. A `blocks` edge between two tasks that share a `streak` id is ALWAYS a finding,
102
+ regardless of task type -- it silently splits the lane into separate review rounds. A
103
+ legitimate cross-lane edge must originate from every task of the downstream lane and
104
+ target the last (highest `streakOrder`) task of the upstream lane.
85
105
  6. **No scope creep**: tasks address only the original sprint goals and open bugs/features
86
106
  7. **No duplicate work**: no two tasks do the same thing
87
107
  8. **Feasibility**: no task assumes something that has not been built yet
88
- 9. **Ready-work check -- scoped to the UNION of this review's roots, not each root alone**
89
- (see the graph-semantics section above): run `bd list --parent <scope> --ready
90
- --type=task --json` for EACH sprint root and reason over the COMBINED result. The
91
- invariant is that the UNION of ready work across all roots is non-empty whenever open
92
- tasks remain anywhere in scope -- NOT that every root independently has ready work. Do
93
- NOT use bare `bd ready`, which lists ready work across the entire database and is not a
94
- signal about this DAG.
108
+ 9. **Ready-work check -- scoped to the UNION of this review's roots** (see the
109
+ graph-semantics section): run `bd list --parent <scope> --ready --type=task --json`
110
+ for EACH sprint root and reason over the COMBINED result. The invariant: the UNION of
111
+ ready work across all roots is non-empty whenever open tasks remain anywhere in
112
+ scope -- NOT that every root independently has ready work. Do NOT use bare
113
+ `bd ready` (whole-database output, not a signal about this DAG).
95
114
  - A single root whose scoped `--ready` list is EMPTY is NOT a failure when its open
96
- tasks are blocked (directly or transitively) by an open task in a DIFFERENT root that
97
- is itself ready now or reachable from the union ready-set. That is legitimate
98
- cross-goal sequencing (a seeded or intended cross-root `blocks` edge), not a cycle --
99
- do NOT tear out the edge and do NOT hard-fail for it.
100
- - Hard CHANGES NEEDED only when EITHER (a) the union of `--ready` across every root is
101
- empty while open tasks remain anywhere in scope (the whole sprint cannot start -- a
102
- true deadlock), OR (b) a root's blocked chain traces back into its OWN subtree (a
103
- self-cycle -- a `blocks` edge to a `--parent` ancestor/descendant). Diagnose with `bd
104
- blocked --parent <scope>` and `bd dep list <id>` on the suspicious issues; list every
105
- ID in the cycle. Do NOT assume a self-cycle is structurally impossible for any
106
- scope-root type except `epic` -- bd's protection is narrower than that.
107
- Epic-level completion tracking (has everything under this epic actually finished) is a
108
- separate question -- use `bd epic status <scope>` for that ONLY when `<scope>` is itself
109
- `issue_type=epic` (check via `bd show <scope> --json` first: on a non-epic scope, `bd
110
- epic status` silently lists unrelated epics instead of erroring) -- fall back to
111
- `dependent_count`/manual child inspection for non-epic scopes.
112
- 10. **Model metadata**: every task has a model tier set as beads metadata, i.e.
113
- `--metadata '{"model": "..."}'` at creation (visible as the `model` key in `bd show <id>`'s
114
- metadata output). This is the single location the tier lives in -- `planner.md` Step 3
115
- writes it here and nowhere else (not `--notes`, not free text). A task missing this
116
- metadata key is a Step 2 criterion-10 failure, not a fallback case for this step; see
117
- Step 3 for the read-time fallback used only when classifying/reporting.
118
- 11. **Lane cohesion**: every task carries `streak` and `streakOrder` lane metadata via the
119
- same `--metadata` channel as `model` (visible as the `streak`/`streakOrder` keys in `bd
120
- show <id>`'s metadata output) -- a task missing either key is a criterion-11 finding.
121
- Beyond presence, check:
122
- - **Cohesive lanes**: the tasks sharing a `streak` id name overlapping files or the same
123
- component/module in their descriptions -- a lane grouping unrelated work areas is a
124
- finding.
125
- - **No cross-lane edges among open members**: no `blocks` edge exists between an open
126
- task in one lane and an open task in a different lane -- ordering across lanes must
127
- come from lane sequencing, not a raw dependency edge spanning two streaks.
115
+ tasks are blocked (directly or transitively) by an open task in a DIFFERENT root
116
+ reachable from the union ready-set -- legitimate cross-goal sequencing, not a
117
+ cycle; do NOT tear out the edge and do NOT hard-fail.
118
+ - Hard CHANGES_NEEDED only when EITHER (a) the union of `--ready` across every root
119
+ is empty while open tasks remain anywhere in scope (true deadlock), OR (b) a
120
+ root's blocked chain traces back into its OWN subtree (a self-cycle -- a `blocks`
121
+ edge to a `--parent` ancestor/descendant). Diagnose with `bd blocked --parent
122
+ <scope>` and `bd dep list <id>`; list every ID in the cycle. Do NOT assume a
123
+ self-cycle is structurally impossible except for `epic` scope roots -- bd's
124
+ protection is narrower than that.
125
+ Epic-level completion tracking is separate -- use `bd epic status <scope>` ONLY when
126
+ `<scope>` is itself `issue_type=epic` (check `bd show <scope> --json` first: on a
127
+ non-epic scope it silently lists unrelated epics instead of erroring); otherwise
128
+ fall back to `dependent_count`/manual child inspection.
129
+ 10. **Model metadata**: every task has a model tier in beads metadata (the `model` key
130
+ in `bd show <id>` -- the single location, per `planner.md` Step 3; never `--notes`
131
+ or free text). A missing key is a criterion-10 failure; Step 3's fallback is for
132
+ classification/reporting only.
133
+ 11. **Lane cohesion and sizing**: every task carries `size`, `streak` and `streakOrder` in
134
+ the same `--metadata` channel as `model` -- a task missing any of these three keys is
135
+ a criterion-11 finding. (A missing `model` key is criterion 10's finding,
136
+ `kind: "model_metadata"` -- do not also report it here.) Beyond presence:
137
+ - **Cohesive lanes**: tasks sharing a `streak` id name overlapping files, the same
138
+ component/module, or an enabling relationship in their descriptions -- a lane
139
+ grouping unrelated work areas is a finding.
140
+ - **Under-batched lanes** (this is the finding this criterion most often should
141
+ produce): two lanes joined by a `blocks` edge (directly, or transitively through
142
+ other lanes) that are cohesive by the planner's SAME-lane rules (same
143
+ files/component, enabling relationship, impl and its test, mutex members) and whose
144
+ combined effort is within `laneMaxEffort` and `laneMaxTasks` must be ONE lane, UNLESS
145
+ the downstream lane is a feature-level `[test]` lane covering impl work legitimately
146
+ split across several lanes (criterion 5's exception) -- that cross-lane wiring is
147
+ required, not under-batching. Each other unnecessary lane boundary in a CHAIN is an
148
+ extra review round; name the lanes to merge. Two cohesive lanes with NO `blocks` edge
149
+ between them normally already run in the same review round -- merging them would only
150
+ remove parallelism, usually for no review saving, so that is NOT a finding.
151
+ - **No intra-lane `blocks` edges; cross-lane edges wired correctly**: see criterion 5
152
+ for the rule -- report a violation there as `kind: "dependency_wiring"`, not here.
128
153
  - **Mutex resources co-laned**: tasks that contend for the same mutual-exclusion
129
154
  resource (a resource only one change may hold at a time -- e.g. the same submodule
130
155
  pointer, a shared version/manifest field, or the same test fixture) share one `streak`
131
156
  and are never split across lanes.
132
- - **Effort under threshold**: for each lane, `effort = (sum of size points over the
133
- lane's tasks, S=1/M=2/L=4) x (max model weight in the lane, cheap=1/standard=10/
134
- premium=20)` stays at or under the effort threshold constant (default `200`). A lane
135
- over threshold is a finding unless it was split at a `blocks`-edge boundary without
136
- separating mutex-resource members (per `planner.md`'s splitting math).
137
- A violation of any bullet above is CHANGES_NEEDED referencing "criterion 11" and the
138
- specific lane/task IDs involved.
157
+ - **Within limits**: per lane, task count `<=` `laneMaxTasks` and `effort` (computed
158
+ from the recorded `size` values, not your own estimate -- `effort = sum of size
159
+ points S=1/M=2/L=4 x max model weight in the lane, cheap=1/standard=10/premium=20`)
160
+ `<=` `laneMaxEffort`. These three numbers (defaults `laneMaxTasks=6`,
161
+ `laneMaxEffort=200`, `laneTargetEffort=60`) are fixed for now -- no per-dispatch
162
+ override channel exists yet. A lane over either cap is a finding unless it was split
163
+ at a point where the earlier part is a self-contained, reviewable increment, without
164
+ separating mutex-resource members.
165
+ - **Safety valves -- do NOT ask for a merge when**: the lanes have no `blocks` edge
166
+ between them (see Under-batched lanes above); the lanes sit across a risk boundary
167
+ the planner named (contract change, migration, security-sensitive or destructive
168
+ path); a downstream task's criteria genuinely depend on the upstream outcome being
169
+ reviewed first; or the merged lane would exceed either cap.
170
+ A violation of any finding bullet above -- excluding the intra-lane/cross-lane bullet
171
+ (routes to criterion 5) and the Safety valves bullet (describes non-findings) -- is
172
+ CHANGES_NEEDED referencing "criterion 11" and the specific lane/task IDs involved.
173
+ 12. **NOTES-vs-child contradiction**: for each child under review, check whether its
174
+ parent bead's NOTES contains any entry recognizable as a correction or amendment --
175
+ language such as "CORRECTION", "AMENDMENT", "SUPERSEDES", "REVISED", or an explicit
176
+ "do X, not Y" statement. Compare each such correction against the child's own
177
+ DESCRIPTION/acceptance criteria. If the child's text contradicts a correction
178
+ recorded in the parent's NOTES -- e.g. it reintroduces an approach the correction
179
+ explicitly rejected, or omits a requirement the correction added -- this is a
180
+ CHANGES_NEEDED finding. When reporting a finding of this kind, quote the exact
181
+ conflicting text from BOTH the parent's correction and the child's contradicting
182
+ passage in `detail` -- a vague "may not be aligned with parent notes" is not
183
+ sufficient; the finding must be falsifiable by inspection. Use `kind: "other"` for
184
+ findings of this type (Step 4's closed vocabulary has no dedicated kind for it).
139
185
 
140
186
  ## Step 3 -- Classify each task
141
187
 
@@ -146,12 +192,15 @@ For each open `type=task` issue, determine:
146
192
  - **M**: 2-3 files, moderate logic (new endpoint, test suite, small refactor)
147
193
  - **L**: 3+ files or non-trivial design (auth flow, migration, cross-cutting change)
148
194
 
149
- **Model** -- read from the task's beads metadata (`model` key, set via `--metadata`) in
150
- `bd show <id>` output. This is the same location `planner.md` Step 3 writes to -- do not
151
- look in `--notes` or anywhere else. If no `model` metadata key is set on a task, use the
152
- fallback tier: `standard`, AND flag it under Step 2 criterion 10 as a CHANGES_NEEDED
153
- finding (the fallback lets you finish classification/reporting in the same pass; it does
154
- not excuse the planner from setting the metadata).
195
+ **Model** -- read from the task's beads metadata (`model` key in `bd show <id>`; never
196
+ `--notes`). If missing, use fallback tier `standard` AND flag it under Step 2
197
+ criterion 10 as a CHANGES_NEEDED finding -- the fallback lets you finish
198
+ classification, it does not excuse the planner.
199
+
200
+ Compare your bucket with the task's recorded `size`. Agreement, or a one-step difference
201
+ (S/M or M/L), needs no action. A two-step disagreement -- your bucket `L` against a
202
+ recorded `size` of `S`, or the reverse -- is a finding under criterion 4
203
+ (`kind: "task_size"`), not a silent override.
155
204
 
156
205
  ## Step 4 -- Output verdict
157
206
 
@@ -159,15 +208,37 @@ Return your verdict:
159
208
  - `verdict`: `"APPROVED"` or `"CHANGES_NEEDED"` (exact strings -- the machine-readable
160
209
  enum in the output schema uses the underscore form, never "CHANGES NEEDED" with a space)
161
210
  - `notes`: specific, actionable findings referencing beads IDs
211
+ - `findings`: array with one entry per bead that must change -- `{ id, kind, detail }`.
212
+ `id` is the bead, written exactly as it appears in `taskAssignments`. `kind` is a closed
213
+ vocabulary naming the criterion that failed, one of `coverage`, `missing_test_task`,
214
+ `acceptance_criteria`, `task_size`, `dependency_wiring`, `scope_creep`, `duplicate_work`,
215
+ `feasibility`, `ready_work`, `model_metadata`, `lane_cohesion`, `other` -- in the order of
216
+ the numbered criteria in Step 2, with `other` covering both criterion 12
217
+ (NOTES-vs-child contradiction) and any failure none of the listed kinds describes.
218
+ `detail` is the human explanation for that bead.
162
219
  - `taskAssignments`: array with one entry per open task -- `{ id, bucket, model }`
163
220
 
164
- **APPROVED** means all eleven criteria in Step 2 pass.
221
+ `notes` must also state the expected number of review rounds (the longest chain of lanes
222
+ joined by `blocks` edges) so the orchestrator can see review cadence before development
223
+ starts.
224
+
225
+ **APPROVED** means all twelve criteria in Step 2 pass.
165
226
 
166
227
  **CHANGES_NEEDED** means one or more criteria fail. Notes must name the specific beads ID
167
- and what is wrong. Do not return CHANGES_NEEDED for minor style preferences.
228
+ and what is wrong. Do not return CHANGES_NEEDED for minor style preferences -- but a plan
229
+ that is correct yet needs more review rounds than necessary (lanes that should be merged
230
+ per criterion 11's under-batched-lanes check) IS CHANGES_NEEDED, not a style preference.
168
231
 
169
232
  Always populate `taskAssignments` even on CHANGES_NEEDED -- cost estimation uses it regardless.
170
233
 
234
+ Always populate `findings` on every CHANGES_NEEDED verdict, for the same reason: it is the
235
+ machine-readable channel a caller routes on, so an objection that exists only in `notes` is
236
+ an objection the caller cannot act on. One entry per bead you are objecting to. If the
237
+ objection is genuinely plan-wide and names no individual bead, return `findings: []` and
238
+ explain it in `notes` -- the empty array is the explicit "plan-wide" signal, not an
239
+ oversight. On APPROVED, omit `findings` or return `[]`. `notes` remains the narration
240
+ channel and must stay readable on its own; `findings` does not replace it.
241
+
171
242
  ## Output schema
172
243
 
173
244
  The canonical machine-readable contract for this output lives in the sibling file
@@ -177,10 +248,15 @@ placeholder):
177
248
  ```json
178
249
  {
179
250
  "verdict": "CHANGES_NEEDED",
180
- "notes": "BD-14 missing [test] task; BD-22 has no model tier metadata set",
251
+ "notes": "Expected review rounds: 2. BD-14 missing [test] task; BD-22 has no model tier metadata set",
252
+ "findings": [
253
+ { "id": "BD-14", "kind": "missing_test_task", "detail": "Feature has an [impl] task but no [test] task covering it." },
254
+ { "id": "BD-22", "kind": "model_metadata", "detail": "No model key in beads metadata; classified as standard under the Step 3 fallback." }
255
+ ],
181
256
  "taskAssignments": [
182
257
  { "id": "BD-10", "bucket": "M", "model": "standard" },
183
- { "id": "BD-14", "bucket": "S", "model": "cheap" }
258
+ { "id": "BD-14", "bucket": "S", "model": "cheap" },
259
+ { "id": "BD-22", "bucket": "S", "model": "standard" }
184
260
  ]
185
261
  }
186
262
  ```