@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
@@ -30,8 +30,14 @@ orchestrator that planning has no input to work from -- do not create speculativ
30
30
 
31
31
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
32
32
 
33
+ <!-- if-tool: ToolSearch -->
33
34
  1. Run ToolSearch with query
34
35
  `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_stats,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback"`
36
+ <!-- else-tool: ToolSearch -->
37
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
38
+ tool it wants directly. Confirm your environment exposes those tools, then call
39
+ them as written.
40
+ <!-- end-tool: ToolSearch -->
35
41
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo you are
36
42
  planning for, and `hint_symbols`/`hint_modules` derived from the sprint goals /
37
43
  requirements you are about to decompose (skim them first to extract key symbol
@@ -53,24 +59,23 @@ orchestrator that planning has no input to work from -- do not create speculativ
53
59
  in Step 3 for the thresholds and how to record it). If `kb_stats` is unavailable
54
60
  (tool error, not yet built in this environment, or the KB has no symbols yet), skip
55
61
  the quantitative step and rely on the qualitative KB signals above instead.
56
- 4. Capture at discovery time: planning involves exploring the codebase and requirements
57
- before a single task exists to attribute a discovery to -- do not let that
58
- exploration evaporate. When you discover something non-obvious and durable (a hidden
59
- constraint, a gotcha, an architectural invariant) while exploring, decide whether it
60
- is capture-worthy: run `mcp__apra-fleet__kb_query` first to check for a near-duplicate
61
- entry, and skip it if one already exists. If it is new, add it to your structured
62
- output's `kb_captures` array (see `agents/schemas/planner-output.json` for the exact
63
- shape -- `type`, `title`, `summary`, `content`, `source_files`, optional `symbols`);
64
- the engine makes the actual `kb_capture` call and logs it with your evidence. Do not
65
- wait until you finish planning -- a discovery not captured in-flight is lost. Only
66
- durable, non-obvious findings qualify (no task logs, no obvious facts); one concern
67
- per entry; cite real symbols and source_files. Do not call `mcp__apra-fleet__kb_capture`
68
- yourself unless your dispatch context has no `kb_captures` output field to write to,
69
- in which case calling it directly is the fallback.
62
+ 4. Capture at discovery time: when you find something non-obvious and durable (hidden
63
+ constraint, gotcha, architectural invariant) while exploring, dedupe with
64
+ `mcp__apra-fleet__kb_query`; if new, add it to your structured output's `kb_captures`
65
+ array (shape in `agents/schemas/planner-output.json`) as you go -- do not wait until
66
+ planning ends. Only durable, non-obvious findings qualify (no task logs, no obvious
67
+ facts); one concern per entry; cite real symbols and source_files. Call
68
+ `mcp__apra-fleet__kb_capture` directly only if your dispatch context has no
69
+ `kb_captures` output field.
70
70
  5. If a KB entry you retrieved proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
71
71
  with the entry id and what was wrong.
72
72
 
73
+ <!-- if-tool: ToolSearch -->
73
74
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
75
+ <!-- else-tool: ToolSearch -->
76
+ If those KB tools are not available in your environment (MCP server not running), skip
77
+ these steps and proceed.
78
+ <!-- end-tool: ToolSearch -->
74
79
 
75
80
  ## Step 1 -- Explore the backlog
76
81
 
@@ -90,25 +95,34 @@ Also check for carry-over regression failures left by a previous sprint:
90
95
  bd search "[carry-over]"
91
96
  ```
92
97
 
93
- A prior sprint's Regression Test phase files its failures as STANDALONE,
94
- PARENT-LESS beads titled `[regression][carry-over] <description>` -- deliberately
95
- outside any sprint's scope tree, so a regression failure never blocks the sprint
96
- that found it. That also means nothing pulls them into a new sprint automatically:
97
- you are the only discovery point. Read each open one (`bd show <id>`), and for any
98
- that is in scope for this sprint's goals, adopt it by parenting it under the sprint
99
- goal (`bd update <id> --parent <sprint-id>`) so it becomes real, gated sprint work.
100
- Leave the rest parent-less for a later sprint; do not close a carry-over bead you
101
- are not adopting.
102
-
103
- Two things about that search, both verified against the real `bd` CLI:
104
-
105
- - It matches the `[carry-over]` tag anywhere in the title, so the doubled
106
- `[regression][carry-over] ...` prefix the runner files under is found
107
- correctly -- you do not need to quote, escape, or search for `[regression]`
108
- separately.
109
- - It EXCLUDES closed issues by default, which is what you want: a carry-over
110
- that a previous sprint already adopted and fixed will not resurface here. Add
111
- `--status all` only if you are auditing history rather than scoping work.
98
+ A prior sprint's Regression Test phase files its failures as STANDALONE, PARENT-LESS
99
+ beads titled `[regression][carry-over] <description>` -- outside any sprint's scope
100
+ tree, so nothing pulls them into a new sprint automatically: you are the only discovery
101
+ point. Read each open one (`bd show <id>`); adopt any that is in scope by parenting it
102
+ under the sprint goal (`bd update <id> --parent <sprint-id>`). Leave the rest
103
+ parent-less; do not close a carry-over bead you are not adopting.
104
+
105
+ About that search (verified against the real `bd` CLI): it matches `[carry-over]`
106
+ anywhere in the title, so the doubled `[regression][carry-over]` prefix is found without
107
+ extra quoting; and it EXCLUDES closed issues by default -- add `--status all` only when
108
+ auditing history.
109
+
110
+ **Read NOTES before decomposing.** Before decomposing any bead -- sprint goal, feature,
111
+ or task -- that has a non-empty NOTES section, read NOTES in full, in chronological
112
+ order, as part of understanding the bead's current scope, not merely as optional
113
+ background context. A bead's NOTES section functions as an append-only changelog:
114
+ corrections, amendments, and design-review findings accumulate there over the bead's
115
+ lifetime, often after its DESCRIPTION was written. Treat a NOTES entry that explicitly
116
+ corrects, amends, or supersedes something in DESCRIPTION -- recognizable by language such
117
+ as "CORRECTION", "AMENDMENT", "SUPERSEDES", "REVISED", or an explicit "do X, not Y"
118
+ statement -- as authoritative over the DESCRIPTION passage it contradicts. When writing a
119
+ child's own DESCRIPTION/acceptance criteria (Steps 2 and 3 below), do not copy stale
120
+ DESCRIPTION language verbatim if a later NOTES entry corrected it -- write the child from
121
+ the corrected understanding. It is fine, and often preferable, for the child to
122
+ explicitly cite which correction it incorporates, so a later reader does not need to
123
+ cross-reference the parent's full history. This does not change how you decompose a bead
124
+ whose NOTES is empty or purely procedural (e.g. claim/close log lines) -- it applies only
125
+ when NOTES contains substantive corrections to DESCRIPTION.
112
126
 
113
127
  ## Step 2 -- Decompose sprint goals into features
114
128
 
@@ -125,29 +139,42 @@ For each sprint goal create type=feature issues as direct children:
125
139
  `bd dep add <sprint-id> <feature-id>`; see the graph-semantics section above)
126
140
 
127
141
  Each feature must be independently verifiable: integration tests either pass or fail.
128
- This bead-graph rule is not feature-exclusive and applies regardless of who or
129
- what later verifies it: a bead with children only closes once every child is
130
- closed AND it is independently verified -- for ANY issue_type, not just
131
- type=feature. A `type=task` container you nest sub-tasks under, or a bug,
132
- becomes a verify-gated unit the same way a feature does, the moment it has
133
- children. Only true leaf beads (no children) close directly. Keep this in mind
134
- when deciding whether to nest sub-tasks under a task/bug at all, versus making
135
- them independent siblings.
142
+ A bead with children -- ANY issue_type, not just feature -- only closes once every child
143
+ is closed AND its own acceptance criteria are confirmed met; only true leaf beads close
144
+ directly. Weigh this when deciding whether to nest sub-tasks under a task/bug versus
145
+ making them independent siblings.
136
146
 
137
147
  ## Step 3 -- Decompose features into tasks
138
148
 
139
149
  For each feature create two classes of tasks:
140
150
 
141
151
  **Implementation tasks** (`[impl]` prefix optional but helpful):
142
- - One task per cohesive code change (1-3 file changes max)
152
+ - One task per independently verifiable change. A task is the unit the doer commits and
153
+ closes; the LANE (below) is the unit the reviewer reviews. Keep a task small enough to
154
+ have crisp acceptance criteria (typically 1-4 files), but do NOT split a change into
155
+ several tasks just to keep each one small -- a chain of tiny dependent tasks is more
156
+ expensive to review than one lane that holds them together.
143
157
  - Title: specific and imperative ("Add password reset endpoint to auth router")
144
- - Description includes: files to change, expected behaviour, "done" criteria
158
+ - Description includes: expected files to change, expected behaviour, acceptance
159
+ criteria. The file list is a best-effort scope estimate, NOT an allowlist -- phrase it
160
+ as "expected files"; the doer flags work that spills outside it as a criteria defect,
161
+ which routes the bead back to you for a criteria rewrite.
162
+ - Verify any structural claim you bake into a description ("X is referenced nowhere
163
+ else", "no existing test covers Y") this pass, and cite the check next to the claim
164
+ (e.g. "searched repo for <symbol>: no references outside <area>"). If unchecked,
165
+ write "unverified" explicitly.
145
166
  - Priority: P2 or P3
146
167
 
147
168
  **Integration test tasks** (`[test]` prefix in title):
148
169
  - One task per feature verifying the feature end-to-end
149
170
  - Title: "[test] <feature description>" e.g. "[test] password reset email flow"
150
- - Description: what to test, how to assert pass/fail, which tool/framework to use
171
+ - Description: what to test, how to assert pass/fail, which tool/framework to use.
172
+ State acceptance criteria as observable properties, not "the suite is green" -- e.g.
173
+ "no leftover artifacts outside the test sandbox", "the endpoint rejects an expired
174
+ token", "reverting the fix makes this test fail" (include that last one explicitly
175
+ for any [test] task guarding a bug fix). Prefer command-falsifiable criteria for
176
+ mechanical work; plain-language criteria are correct for qualitative work
177
+ (architecture, docs, UX judgment).
151
178
  - Priority: same as its feature
152
179
 
153
180
  **Model tier** (required on every task, both impl and test): set the model tier as beads
@@ -155,10 +182,9 @@ metadata at creation time, not in `--notes`:
155
182
  ```bash
156
183
  bd create ... --metadata '{"model": "<cheap|standard|premium>"}'
157
184
  ```
158
- This is the ONLY location the model tier is recorded. Any consumer -- including
159
- `plan-reviewer.md` (Step 3) and the orchestrator that dispatches doers -- reads the model
160
- tier back from this same metadata field via `bd show <id>` (the `model` key) -- do not
161
- also (or instead) put it in `--notes`, a METADATA-section comment, or anywhere else.
185
+ This is the ONLY location the tier is recorded -- consumers (plan-reviewer, the
186
+ orchestrator) read the `model` key back via `bd show <id>`. Never put it in `--notes`,
187
+ a METADATA-section comment, or anywhere else.
162
188
 
163
189
  Pick the tier using these criteria:
164
190
 
@@ -181,46 +207,82 @@ symbols, use `coverage.fraction` to sharpen the tier choice:
181
207
  (non-obvious constraints, CONFIRMED vs. no entries) alongside the number.
182
208
 
183
209
  When `kb_stats` backed a tier choice, cite the coverage number in the task's
184
- `description` (e.g. "coverage 0.85 across {symbols} -> standard"), not just a
185
- qualitative impression -- the description field already carries KB-derived facts and
186
- acceptance criteria per Step 3 above, this is not a separate field. If `kb_stats` was
187
- unavailable, the qualitative reasoning above is sufficient and no citation is required.
210
+ description (e.g. "coverage 0.85 across {symbols} -> standard"). If `kb_stats` was
211
+ unavailable, the qualitative reasoning above suffices -- no citation required.
188
212
 
189
213
  Pick from the models actually available in the current environment. A user override
190
214
  always wins.
191
215
 
192
216
  **Streak lane metadata** (required on every task, both impl and test): in addition to
193
- `model`, record two lane fields through the SAME beads metadata channel at creation time --
217
+ `model`, record three lane fields through the SAME beads metadata channel at creation time --
194
218
  never in `--notes`, a METADATA-section comment, or anywhere else:
195
219
  ```bash
196
- bd create ... --metadata '{"model": "<cheap|standard|premium>", "streak": "<lane-id>", "streakOrder": <n>}'
220
+ bd create ... --metadata '{"model": "<cheap|standard|premium>", "size": "<S|M|L>", "streak": "<lane-id>", "streakOrder": <n>}'
197
221
  ```
198
- - `streak` -- a stable lane identifier (any short opaque string) shared by every task the
199
- planner wants dispatched together, as one cohesive unit, to a single doer. Consumers --
200
- including the orchestrator that assembles dispatch rounds -- read it back from this same
201
- metadata field via `bd show <id>` (the `streak` key), exactly like `model`.
222
+ - `streak` -- a stable lane identifier (any short opaque string) shared by every task to
223
+ be dispatched together to a single doer; read back via `bd show <id>` like `model`.
202
224
  - `streakOrder` -- an integer giving this task's intended position within its lane. Lower
203
- runs first; ties fall back to the existing `blocks` edges (see the graph-semantics
204
- section above).
205
-
206
- Group tasks into lanes for high cohesion, following these rules:
207
- - An `[impl]` task and its paired `[test]` task co-streak by default (they share one
208
- `streak`), so the doer that writes the code also runs its test in the same session.
209
- - Tasks that contend for a **mutex resource** -- a resource only one change may hold at a
210
- time, e.g. the same submodule pointer, a shared version/manifest field, or the same test
211
- fixture -- MUST share a lane and MUST NOT be separated into different streaks.
212
-
213
- **Effort-point splitting math.** Before finalizing a lane, size it so a single streak stays
214
- within one doer's reach:
215
- - size points per task: `S=1`, `M=2`, `L=4`
216
- - model weight per tier: `cheap=1`, `standard=10`, `premium=20`
217
- - `effort = (sum of size points over the lane's tasks) x (max model weight in the lane)`
218
-
219
- If a lane's `effort` exceeds the effort threshold constant (default `200`), split it into
220
- two or more streaks. Split ONLY at a `blocks`-edge boundary -- so each resulting streak is a
221
- contiguous prefix/suffix of the dependency order, never an arbitrary mid-lane cut -- and
222
- NEVER separate mutex-resource members (above) across the split, even if honoring that leaves
223
- a streak over threshold. Give each split streak a fresh `streak` id and renumber
225
+ runs first; ties break by insertion order -- do NOT use a `blocks` edge to break an
226
+ intra-lane tie (see the dependency-wiring rules below).
227
+ - `size` -- `S`/`M`/`L`, used for lane sizing below.
228
+
229
+ **Lanes are review units.** The engine dispatches every task in one lane to ONE doer in
230
+ `streakOrder`, and the reviewer reviews a whole Develop ROUND at once -- every lane
231
+ dispatched in that round together. A lane is therefore the SMALLEST thing a review can
232
+ cover: never split one coherent increment across two lanes joined by a `blocks` edge,
233
+ because each extra link in that chain costs a full review round (diff read + full test
234
+ run). Lanes with no `blocks` edge between them dispatch and review in the SAME round
235
+ whenever the round's doer count and effort budget allow (unlaned-but-independent lanes
236
+ overflow to the next round only under doer/budget pressure, not because they were kept
237
+ separate), so normally that costs nothing extra -- keep genuinely independent work in
238
+ separate lanes rather than merging it for size alone; merging removes parallelism without
239
+ reliably saving a review.
240
+
241
+ Put tasks in the SAME lane when they are highly coupled or cohesive -- any of:
242
+ - they touch the same files, module, or component, or the same test suite;
243
+ - one exists to enable the next (add a helper, then use it; change a schema, then its
244
+ consumer; implement, then its `[test]` task) -- an `[impl]` task and its paired `[test]`
245
+ task ALWAYS share a lane, UNLESS the feature's impl work itself had to span multiple
246
+ lanes under the sizing rules below -- then the feature's `[test]` task takes the LAST
247
+ impl lane, or ends its own final lane wired cross-lane to every impl lane it verifies;
248
+ - they contend for a **mutex resource** -- a resource only one change may hold at a time,
249
+ e.g. the same submodule pointer, a shared version/manifest field, or the same test
250
+ fixture -- these MUST share a lane and MUST NOT be separated into different streaks;
251
+ - reviewing one without the other would leave the reviewer unable to judge whether the
252
+ feature actually works.
253
+
254
+ Put tasks in DIFFERENT lanes only when at least one of these holds:
255
+ - they are genuinely independent (different feature areas, no shared files, no enabling
256
+ relationship) -- so multiple doers can run them in parallel;
257
+ - they sit on different sides of a RISK BOUNDARY: a change the reviewer must sign off
258
+ before further work is safe to build on (a public contract change, a data migration, a
259
+ security-sensitive path, a destructive operation);
260
+ - a later task cannot be reviewed until the earlier one's outcome has been judged (true
261
+ design uncertainty) -- write the later task's criteria as conditional on that outcome,
262
+ not left blank, and state the dependency explicitly in its description so the criteria
263
+ are never read as unconditional; the earlier task ends its lane, and the later one
264
+ starts a new lane in the next round;
265
+ - the lane would exceed the sizing limits below.
266
+
267
+ **Sizing a lane.** Size buckets are the same ones the plan reviewer classifies with:
268
+ S = 1 file/narrow, M = 2-3 files/moderate logic, L = 3+ files or non-trivial design (see
269
+ the `bd create ... --metadata` example above -- `size` is recorded there, alongside
270
+ `model`/`streak`/`streakOrder`, not as a separate call). Then check each lane against
271
+ these LANE SIZING PARAMETERS (fixed defaults for now -- no per-dispatch override channel
272
+ exists yet):
273
+ - `laneMaxTasks` (default `6`): hard cap on tasks per lane -- a reviewer must be able to
274
+ verify the whole lane in one pass.
275
+ - `laneMaxEffort` (default `200`): `effort = (sum of size points S=1/M=2/L=4) x (max model
276
+ weight in the lane, cheap=1/standard=10/premium=20)`; caps one doer session's load.
277
+ - `laneTargetEffort` (default `60`): a lane BELOW this that has a cohesive neighbour (per
278
+ the SAME-lane rules above) should be MERGED with it, not left as its own review round.
279
+ State in the lane's first task description why a lane was left below target if it was.
280
+
281
+ A lane over either cap is split ONLY at a point where the earlier part is a self-contained,
282
+ reviewable increment (never mid-refactor, never between mutex-resource members). An
283
+ `[impl]` lane may be split from its feature's `[test]` task ONLY as the exception above
284
+ describes -- the test task then ends the chain, cross-lane blocked on every impl lane it
285
+ verifies; it is never itself mid-split. Give each part its own `streak` id and renumber
224
286
  `streakOrder` from the start within it.
225
287
 
226
288
  Wire dependencies (semantics: `bd dep add A B` means A is blocked by B -- B must finish before A can close):
@@ -228,9 +290,16 @@ Wire dependencies (semantics: `bd dep add A B` means A is blocked by B -- B must
228
290
  do NOT `bd dep add <feature-id> <impl-task>` or `<feature-id> <test-task>`; a feature's
229
291
  "not done until its tasks close" status comes from its children, never from a `blocks`
230
292
  edge back onto them)
231
- - `bd dep add <test-task> <impl-task>` (test task blocked until impl task is done -- this
232
- IS correct: impl-task and test-task are siblings, not ancestor/descendant)
233
- - For tasks that depend on a prior sibling task: `bd dep add <later-task> <earlier-task>`
293
+ - INSIDE a lane, order comes from `streakOrder` ONLY. Do NOT add a `blocks` edge between
294
+ two tasks in the same lane -- the engine dispatches only currently-unblocked tasks, so an
295
+ intra-lane edge would push the later task into a separate review round and silently
296
+ defeat the lane. This includes the `[test]` task: it follows its `[impl]` task by
297
+ `streakOrder`, not by an edge.
298
+ - BETWEEN lanes, order comes from `blocks` edges: when lane B must not start until lane A
299
+ is done, add `bd dep add <B-task> <A-last-task>` for EVERY task in lane B against the
300
+ LAST (highest `streakOrder`) task of lane A. Wiring only B's first task would let B's
301
+ later tasks become ready out of order.
302
+ - Sibling tasks in different lanes with no enabling relationship get no edge.
234
303
 
235
304
  ## Step 4 -- Validate your own DAG
236
305
 
@@ -246,14 +315,12 @@ bd list --parent <root-id> --ready --type=task --json
246
315
 
247
316
  **Acyclicity check (mandatory):** A correct DAG has no cycles. The invariant is on the
248
317
  UNION of ready work across all roots, NOT each root alone. Verify:
249
- 1. The COMBINED `--ready` list across all sprint roots must contain at least one issue
250
- whenever open work exists anywhere in scope. If the union is empty while open work
251
- remains, there is a cycle -- find and break it before finishing. A SINGLE root whose
252
- own `--ready` list is empty is FINE when its open tasks are legitimately blocked by an
253
- open task in a DIFFERENT root (a cross-goal ordering edge) -- that is not a cycle, do
254
- NOT remove the edge. (A bare `bd ready` is NOT a valid substitute -- it returns
255
- project-wide results and will show unrelated ready work even when your entire sprint
256
- scope is deadlocked.)
318
+ 1. The COMBINED `--ready` list across all sprint roots must be non-empty whenever open
319
+ work exists anywhere in scope; if empty, there is a cycle -- find and break it before
320
+ finishing. A SINGLE root with an empty `--ready` list is FINE when its open tasks are
321
+ blocked by an open task in a DIFFERENT root (cross-goal ordering, not a cycle -- do
322
+ NOT remove the edge). Bare `bd ready` is NOT a substitute -- it shows unrelated
323
+ project-wide work even when your entire scope is deadlocked.
257
324
  2. A feature/task must NEVER have a `blocks` edge to or from its own `--parent`
258
325
  ancestor/descendant -- see the graph-semantics section above. Only `parent-child` edges
259
326
  (via `--parent`) should exist between a bead and its parent; `blocks` edges belong only
@@ -269,11 +336,18 @@ direction, and re-run the scoped `--ready` query to confirm issues are unblocked
269
336
  Also check each open feature:
270
337
  - Has at least one [impl] task AND one [test] task?
271
338
  - Every task description has clear acceptance criteria?
272
- - No task spans more than ~3 file changes?
273
- - Test tasks are downstream of implementation tasks?
274
- - Every task has a model tier set via `--metadata '{"model": "..."}'` (see Step 3)?
275
- - Every task carries `streak` and `streakOrder` lane metadata (see Step 3)? Impl/test
276
- pairs and mutex-resource members co-laned, and no lane's effort exceeds the threshold?
339
+ - Every task carries `model`, `size`, `streak`, `streakOrder` metadata via `--metadata`
340
+ (see Step 3) -- never `--notes`?
341
+ - Does every lane hold ONE reviewable increment (impl + its test, all mutex members, all
342
+ enabling chains), within `laneMaxTasks` / `laneMaxEffort`?
343
+ - Is every lane below `laneTargetEffort` either justified in its first task description or
344
+ merged with a cohesive neighbour?
345
+ - Is there NO `blocks` edge between two tasks that share a `streak` id?
346
+ - Does every cross-lane `blocks` edge target the upstream lane's LAST task and originate
347
+ from EVERY task of the downstream lane?
348
+ - Expected review rounds (= longest chain of lanes joined by `blocks` edges): state the
349
+ number in your `notes`. If it exceeds 3 for one sprint goal, re-examine whether the
350
+ chain can be shortened by merging lanes.
277
351
  - Where `kb_stats` backed a model tier choice, does the task description cite the
278
352
  coverage number (see Step 3)? Not required for tiers set on qualitative KB signals
279
353
  alone or when `kb_stats` was unavailable.
@@ -302,7 +376,7 @@ array (see Step 0.4 -- omit or send `[]` to capture nothing). Example instance:
302
376
  ```json
303
377
  {
304
378
  "status": "OK",
305
- "notes": "Created 2 features, 6 tasks across 3 streak lanes.",
379
+ "notes": "Created 2 features, 6 tasks across 3 streak lanes; expected review rounds: 2.",
306
380
  "featureIds": ["BD-20", "BD-21"],
307
381
  "taskIds": ["BD-22", "BD-23", "BD-24", "BD-25", "BD-26", "BD-27"],
308
382
  "kb_captures": []
@@ -316,7 +390,9 @@ array (see Step 0.4 -- omit or send `[]` to capture nothing). Example instance:
316
390
  - NEVER add scope beyond the sprint goals you were given and open bugs/features
317
391
  - Every task must be completable in one agent session
318
392
  - A task with no acceptance criteria is incomplete -- fix it before finishing
319
- - Every task must carry a model tier in `--metadata '{"model": "..."}'` -- fix before finishing
320
- - Every task must carry `streak`/`streakOrder` lane metadata alongside `model` in the same
321
- `--metadata` channel; lanes must respect the effort threshold and never split
322
- mutex-resource members apart -- fix before finishing
393
+ - Every task must carry `model`, `size`, `streak` and `streakOrder` in the SAME
394
+ `--metadata` channel at creation time -- never `--notes` -- fix before finishing
395
+ - Lanes must respect `laneMaxEffort`/`laneMaxTasks` and never split mutex-resource members
396
+ apart
397
+ - Never place a `blocks` edge between two tasks that share a `streak` id -- it silently
398
+ defeats the lane by pushing the later task into a separate review round