@apralabs/apra-fleet 0.4.2 → 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 (370) hide show
  1. package/README.md +38 -5
  2. package/dist/agents/backlog-groomer.md +25 -0
  3. package/dist/agents/ci-watcher.md +11 -0
  4. package/dist/agents/deployer.md +37 -2
  5. package/dist/agents/doer.md +36 -12
  6. package/dist/agents/harvester.md +11 -0
  7. package/dist/agents/integ-test-runner.md +11 -0
  8. package/dist/agents/kb-reconciler.md +9 -0
  9. package/dist/agents/plan-reviewer.md +110 -22
  10. package/dist/agents/planner.md +125 -37
  11. package/dist/agents/regression-test-runner.md +11 -0
  12. package/dist/agents/reviewer.md +13 -2
  13. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  14. package/dist/cli/agent-transform.d.ts +83 -2
  15. package/dist/cli/agent-transform.d.ts.map +1 -1
  16. package/dist/cli/agent-transform.js +266 -21
  17. package/dist/cli/agent-transform.js.map +1 -1
  18. package/dist/cli/auth.d.ts.map +1 -1
  19. package/dist/cli/auth.js +28 -9
  20. package/dist/cli/auth.js.map +1 -1
  21. package/dist/cli/config.d.ts +7 -5
  22. package/dist/cli/config.d.ts.map +1 -1
  23. package/dist/cli/config.js +44 -34
  24. package/dist/cli/config.js.map +1 -1
  25. package/dist/cli/install.d.ts +33 -0
  26. package/dist/cli/install.d.ts.map +1 -1
  27. package/dist/cli/install.js +290 -23
  28. package/dist/cli/install.js.map +1 -1
  29. package/dist/cli/kb-directives.d.ts.map +1 -1
  30. package/dist/cli/kb-directives.js +2 -1
  31. package/dist/cli/kb-directives.js.map +1 -1
  32. package/dist/cli/register-member.d.ts.map +1 -1
  33. package/dist/cli/register-member.js +6 -2
  34. package/dist/cli/register-member.js.map +1 -1
  35. package/dist/commands/kb-server.d.ts +3 -0
  36. package/dist/commands/kb-server.d.ts.map +1 -1
  37. package/dist/commands/kb-server.js +43 -3
  38. package/dist/commands/kb-server.js.map +1 -1
  39. package/dist/index.js +3 -3
  40. package/dist/os/linux.d.ts +6 -0
  41. package/dist/os/linux.d.ts.map +1 -1
  42. package/dist/os/linux.js +35 -2
  43. package/dist/os/linux.js.map +1 -1
  44. package/dist/os/os-commands.d.ts +61 -2
  45. package/dist/os/os-commands.d.ts.map +1 -1
  46. package/dist/os/windows-gitbash.d.ts +5 -0
  47. package/dist/os/windows-gitbash.d.ts.map +1 -1
  48. package/dist/os/windows-gitbash.js +15 -0
  49. package/dist/os/windows-gitbash.js.map +1 -1
  50. package/dist/os/windows.d.ts +6 -0
  51. package/dist/os/windows.d.ts.map +1 -1
  52. package/dist/os/windows.js +46 -3
  53. package/dist/os/windows.js.map +1 -1
  54. package/dist/providers/agy.d.ts +115 -6
  55. package/dist/providers/agy.d.ts.map +1 -1
  56. package/dist/providers/agy.js +569 -53
  57. package/dist/providers/agy.js.map +1 -1
  58. package/dist/providers/claude.d.ts +81 -3
  59. package/dist/providers/claude.d.ts.map +1 -1
  60. package/dist/providers/claude.js +344 -10
  61. package/dist/providers/claude.js.map +1 -1
  62. package/dist/providers/codex.d.ts +4 -2
  63. package/dist/providers/codex.d.ts.map +1 -1
  64. package/dist/providers/codex.js +19 -2
  65. package/dist/providers/codex.js.map +1 -1
  66. package/dist/providers/copilot.d.ts +4 -2
  67. package/dist/providers/copilot.d.ts.map +1 -1
  68. package/dist/providers/copilot.js +20 -2
  69. package/dist/providers/copilot.js.map +1 -1
  70. package/dist/providers/none.d.ts +4 -2
  71. package/dist/providers/none.d.ts.map +1 -1
  72. package/dist/providers/none.js +17 -2
  73. package/dist/providers/none.js.map +1 -1
  74. package/dist/providers/opencode.d.ts +3 -1
  75. package/dist/providers/opencode.d.ts.map +1 -1
  76. package/dist/providers/opencode.js +22 -2
  77. package/dist/providers/opencode.js.map +1 -1
  78. package/dist/providers/provider.d.ts +201 -6
  79. package/dist/providers/provider.d.ts.map +1 -1
  80. package/dist/providers/provider.js +56 -0
  81. package/dist/providers/provider.js.map +1 -1
  82. package/dist/services/agy-project.d.ts +102 -0
  83. package/dist/services/agy-project.d.ts.map +1 -0
  84. package/dist/services/agy-project.js +356 -0
  85. package/dist/services/agy-project.js.map +1 -0
  86. package/dist/services/auth-socket.js +4 -4
  87. package/dist/services/auth-web.js +1 -1
  88. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  89. package/dist/services/cloud/lifecycle.js +33 -4
  90. package/dist/services/cloud/lifecycle.js.map +1 -1
  91. package/dist/services/credential-cleanup.d.ts.map +1 -1
  92. package/dist/services/credential-cleanup.js +35 -17
  93. package/dist/services/credential-cleanup.js.map +1 -1
  94. package/dist/services/exit-drain.d.ts +44 -0
  95. package/dist/services/exit-drain.d.ts.map +1 -0
  96. package/dist/services/exit-drain.js +52 -0
  97. package/dist/services/exit-drain.js.map +1 -0
  98. package/dist/services/github-app.d.ts.map +1 -1
  99. package/dist/services/github-app.js +32 -4
  100. package/dist/services/github-app.js.map +1 -1
  101. package/dist/services/http-transport.d.ts +1 -0
  102. package/dist/services/http-transport.d.ts.map +1 -1
  103. package/dist/services/http-transport.js +48 -1
  104. package/dist/services/http-transport.js.map +1 -1
  105. package/dist/services/knowledge/kb-config.d.ts +42 -0
  106. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  107. package/dist/services/knowledge/kb-config.js +54 -0
  108. package/dist/services/knowledge/kb-config.js.map +1 -0
  109. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  110. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  111. package/dist/services/knowledge/kb-providers.js +191 -17
  112. package/dist/services/knowledge/kb-providers.js.map +1 -1
  113. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  114. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  115. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  116. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  117. package/dist/services/model-pricing.d.ts.map +1 -1
  118. package/dist/services/model-pricing.js +7 -3
  119. package/dist/services/model-pricing.js.map +1 -1
  120. package/dist/services/secret-token.d.ts +38 -0
  121. package/dist/services/secret-token.d.ts.map +1 -0
  122. package/dist/services/secret-token.js +51 -0
  123. package/dist/services/secret-token.js.map +1 -0
  124. package/dist/services/service-manager/types.d.ts +3 -1
  125. package/dist/services/service-manager/types.d.ts.map +1 -1
  126. package/dist/services/service-manager/windows.d.ts +14 -2
  127. package/dist/services/service-manager/windows.d.ts.map +1 -1
  128. package/dist/services/service-manager/windows.js +65 -7
  129. package/dist/services/service-manager/windows.js.map +1 -1
  130. package/dist/services/ssh.d.ts.map +1 -1
  131. package/dist/services/ssh.js +58 -2
  132. package/dist/services/ssh.js.map +1 -1
  133. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  134. package/dist/services/stall/read-log-tail.js +20 -10
  135. package/dist/services/stall/read-log-tail.js.map +1 -1
  136. package/dist/services/stall/stall-detector.d.ts +53 -4
  137. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  138. package/dist/services/stall/stall-detector.js +212 -34
  139. package/dist/services/stall/stall-detector.js.map +1 -1
  140. package/dist/services/strategy.d.ts.map +1 -1
  141. package/dist/services/strategy.js +79 -2
  142. package/dist/services/strategy.js.map +1 -1
  143. package/dist/services/substitution-engine.js +2 -2
  144. package/dist/services/substitution-engine.js.map +1 -1
  145. package/dist/services/tool-registry.d.ts.map +1 -1
  146. package/dist/services/tool-registry.js +5 -3
  147. package/dist/services/tool-registry.js.map +1 -1
  148. package/dist/services/vcs/azure-devops.d.ts +66 -1
  149. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  150. package/dist/services/vcs/azure-devops.js +192 -21
  151. package/dist/services/vcs/azure-devops.js.map +1 -1
  152. package/dist/services/vcs/types.d.ts +1 -1
  153. package/dist/skills/fleet-sprint-cli/SKILL.md +18 -0
  154. package/dist/skills/pm/SKILL.md +1 -1
  155. package/dist/skills/pm/cost.md +0 -3
  156. package/dist/skills/pm/fleet-addendum.md +2 -2
  157. package/dist/tools/check-status.d.ts +7 -4
  158. package/dist/tools/check-status.d.ts.map +1 -1
  159. package/dist/tools/check-status.js +2 -0
  160. package/dist/tools/check-status.js.map +1 -1
  161. package/dist/tools/compose-permissions.d.ts +6 -0
  162. package/dist/tools/compose-permissions.d.ts.map +1 -1
  163. package/dist/tools/compose-permissions.js +182 -34
  164. package/dist/tools/compose-permissions.js.map +1 -1
  165. package/dist/tools/credential-store-set.js +1 -1
  166. package/dist/tools/execute-command.d.ts.map +1 -1
  167. package/dist/tools/execute-command.js +31 -20
  168. package/dist/tools/execute-command.js.map +1 -1
  169. package/dist/tools/execute-prompt.d.ts +15 -2
  170. package/dist/tools/execute-prompt.d.ts.map +1 -1
  171. package/dist/tools/execute-prompt.js +1196 -892
  172. package/dist/tools/execute-prompt.js.map +1 -1
  173. package/dist/tools/kb-capture.d.ts +2 -2
  174. package/dist/tools/kb-capture.d.ts.map +1 -1
  175. package/dist/tools/kb-capture.js +29 -5
  176. package/dist/tools/kb-capture.js.map +1 -1
  177. package/dist/tools/kb-export.d.ts +2 -2
  178. package/dist/tools/kb-export.d.ts.map +1 -1
  179. package/dist/tools/kb-export.js +3 -28
  180. package/dist/tools/kb-export.js.map +1 -1
  181. package/dist/tools/kb-feedback.d.ts.map +1 -1
  182. package/dist/tools/kb-feedback.js +3 -1
  183. package/dist/tools/kb-feedback.js.map +1 -1
  184. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  185. package/dist/tools/kb-freshness-sweep.js +3 -1
  186. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  187. package/dist/tools/kb-import.d.ts.map +1 -1
  188. package/dist/tools/kb-import.js +2 -1
  189. package/dist/tools/kb-import.js.map +1 -1
  190. package/dist/tools/kb-list.d.ts.map +1 -1
  191. package/dist/tools/kb-list.js +3 -1
  192. package/dist/tools/kb-list.js.map +1 -1
  193. package/dist/tools/kb-query.d.ts +2 -2
  194. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  195. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  196. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  197. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  198. package/dist/tools/kb-resolve-contradiction.js +3 -1
  199. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  200. package/dist/tools/kb-setup.d.ts.map +1 -1
  201. package/dist/tools/kb-setup.js +125 -20
  202. package/dist/tools/kb-setup.js.map +1 -1
  203. package/dist/tools/kb-stats.d.ts.map +1 -1
  204. package/dist/tools/kb-stats.js +64 -43
  205. package/dist/tools/kb-stats.js.map +1 -1
  206. package/dist/tools/list-members.d.ts +2 -2
  207. package/dist/tools/list-members.d.ts.map +1 -1
  208. package/dist/tools/list-members.js +1 -0
  209. package/dist/tools/list-members.js.map +1 -1
  210. package/dist/tools/member-detail.d.ts +2 -2
  211. package/dist/tools/member-detail.d.ts.map +1 -1
  212. package/dist/tools/member-detail.js +17 -0
  213. package/dist/tools/member-detail.js.map +1 -1
  214. package/dist/tools/member-reservation.d.ts +58 -1
  215. package/dist/tools/member-reservation.d.ts.map +1 -1
  216. package/dist/tools/member-reservation.js +61 -20
  217. package/dist/tools/member-reservation.js.map +1 -1
  218. package/dist/tools/provision-auth.d.ts +80 -1
  219. package/dist/tools/provision-auth.d.ts.map +1 -1
  220. package/dist/tools/provision-auth.js +142 -54
  221. package/dist/tools/provision-auth.js.map +1 -1
  222. package/dist/tools/provision-vcs-auth.d.ts +91 -1
  223. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  224. package/dist/tools/provision-vcs-auth.js +209 -49
  225. package/dist/tools/provision-vcs-auth.js.map +1 -1
  226. package/dist/tools/register-member.d.ts +12 -9
  227. package/dist/tools/register-member.d.ts.map +1 -1
  228. package/dist/tools/register-member.js +99 -12
  229. package/dist/tools/register-member.js.map +1 -1
  230. package/dist/tools/remove-member.d.ts.map +1 -1
  231. package/dist/tools/remove-member.js +27 -2
  232. package/dist/tools/remove-member.js.map +1 -1
  233. package/dist/tools/send-email.d.ts +2 -2
  234. package/dist/tools/setup-git-app.d.ts.map +1 -1
  235. package/dist/tools/setup-git-app.js +11 -7
  236. package/dist/tools/setup-git-app.js.map +1 -1
  237. package/dist/tools/shutdown-server.d.ts +2 -0
  238. package/dist/tools/shutdown-server.d.ts.map +1 -1
  239. package/dist/tools/shutdown-server.js +23 -1
  240. package/dist/tools/shutdown-server.js.map +1 -1
  241. package/dist/tools/update-member.d.ts +12 -9
  242. package/dist/tools/update-member.d.ts.map +1 -1
  243. package/dist/tools/update-member.js +43 -11
  244. package/dist/tools/update-member.js.map +1 -1
  245. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  246. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  247. package/dist/tools/vcs-credential-exec.js +197 -0
  248. package/dist/tools/vcs-credential-exec.js.map +1 -0
  249. package/dist/types.d.ts +13 -0
  250. package/dist/types.d.ts.map +1 -1
  251. package/dist/utils/log-helpers.d.ts.map +1 -1
  252. package/dist/utils/log-helpers.js +2 -2
  253. package/dist/utils/log-helpers.js.map +1 -1
  254. package/dist/utils/prompt-errors.d.ts.map +1 -1
  255. package/dist/utils/prompt-errors.js +7 -1
  256. package/dist/utils/prompt-errors.js.map +1 -1
  257. package/dist/utils/shell-escape.d.ts +16 -0
  258. package/dist/utils/shell-escape.d.ts.map +1 -1
  259. package/dist/utils/shell-escape.js +22 -2
  260. package/dist/utils/shell-escape.js.map +1 -1
  261. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  262. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  263. package/dist/utils/vcs-provider-detect.js +109 -0
  264. package/dist/utils/vcs-provider-detect.js.map +1 -0
  265. package/dist/utils/workspace-trust.d.ts +20 -17
  266. package/dist/utils/workspace-trust.d.ts.map +1 -1
  267. package/dist/utils/workspace-trust.js +87 -1
  268. package/dist/utils/workspace-trust.js.map +1 -1
  269. package/dist/workflows/auto-sprint.js +176 -15
  270. package/package.json +6 -4
  271. package/packages/apra-fleet-client/src/client/api.mjs +319 -17
  272. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  273. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  274. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +25 -0
  275. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +11 -0
  276. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -2
  277. package/packages/apra-fleet-se/apra-pm/agents/doer.md +36 -12
  278. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +11 -0
  279. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +11 -0
  280. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +9 -0
  281. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +110 -22
  282. package/packages/apra-fleet-se/apra-pm/agents/planner.md +125 -37
  283. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +11 -0
  284. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +13 -2
  285. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  286. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -1
  287. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
  288. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
  289. package/packages/apra-fleet-se/bin/cli.mjs +149 -1
  290. package/packages/apra-fleet-se/bin/serve.mjs +78 -4
  291. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  292. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  293. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  294. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  295. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  296. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  297. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  298. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  299. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +61 -14
  300. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  301. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  302. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  303. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  304. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  305. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +276 -0
  306. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
  307. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  308. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  309. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +996 -32
  310. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +267 -0
  311. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  312. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  313. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  314. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  315. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  316. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  317. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  318. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  319. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  320. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  321. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  322. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  323. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  324. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  325. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  326. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  327. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  328. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  329. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  330. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  331. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  332. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  333. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  334. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  335. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  336. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  337. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  338. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  339. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  340. package/packages/apra-fleet-se/fleet-sprint/runner.js +1467 -9798
  341. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +17 -12
  342. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  343. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +18 -0
  344. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  345. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  346. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  347. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  348. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  349. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  350. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  351. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +153 -19
  352. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +71 -21
  353. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  354. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +131 -0
  355. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +140 -16
  356. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +1 -0
  357. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +77 -2
  358. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  359. package/packages/apra-fleet-se/package.json +1 -1
  360. package/packages/apra-fleet-workflow/src/viewer/index.mjs +17 -6
  361. package/packages/apra-fleet-workflow/src/workflow/index.mjs +49 -7
  362. package/skills/fleet/SKILL.md +8 -8
  363. package/skills/fleet/auth-azdevops.md +14 -3
  364. package/skills/fleet/auth-bitbucket.md +2 -2
  365. package/skills/fleet/auth-github.md +5 -4
  366. package/skills/fleet/onboarding.md +3 -3
  367. package/skills/fleet/permissions.md +5 -1
  368. package/skills/fleet/profiles/node.json +1 -1
  369. package/skills/fleet/troubleshooting.md +3 -3
  370. package/version.json +1 -1
package/README.md CHANGED
@@ -111,6 +111,8 @@ apra-fleet install --llm agy # or --llm opencode / codex / copilot
111
111
  cd ~/.apra-fleet/bin && apra-fleet start # start the apra-fleet
112
112
  ```
113
113
 
114
+ The default install includes fleet-se (fleet-sprint, supervisor, bd), which requires a system Node.js 22.16+ and npm on PATH; the installer fails up front if they are missing. Use `apra-fleet install --workflows none` to install the core only.
115
+
114
116
  **2. Connect your agent.** Load the fleet server in Claude Code with
115
117
  `/mcp` (or restart your provider CLI). Your agent now has a fleet.
116
118
 
@@ -176,7 +178,7 @@ flowchart LR
176
178
  CP["Control Plane<br/>(Server, Engine, Supervisor)"] -->|Dispatch & Sync| M1["MacBook<br/>(Claude)"] & M2["Linux GPU<br/>(vLLM)"] & M3["Cloud VM<br/>(AGY)"] & M4["Windows<br/>(OpenCode)"]
177
179
  ```
178
180
 
179
- - **Fleet server**: the control plane. Registers members, dispatches commands and prompts, moves files, brokers credentials. Speaks MCP, so any MCP-capable agent can drive a fleet.
181
+ - **Fleet server**: the control plane. Registers members, dispatches commands and prompts, moves files, brokers credentials. Speaks MCP, so any MCP-capable agent can drive a fleet. `execute_prompt` supports session forking (`fork`) on fork-capable providers -- branch a new, independent session from an existing one's context (e.g. a primed session reused across per-task dispatches) without continuing to write into the source session. See [docs/mcp-tools.md](docs/mcp-tools.md#execute_prompt) for the parameter contract.
180
182
  - **Members**: real machines running provider CLIs. Composes provider-native permissions before every dispatch; unattended modes are scoped, never blanket.
181
183
  - **Workflow engine**: runs workflow programs with phases, retries, turn budgets, resumable sessions, per-activity persistent state, and a cooperative pause/resume gate any workflow can hook into.
182
184
  - **Supervisor**: always-on layer -- launch, pause/resume, & stop sprints over HTTP, member reservation ledger, crash watchdog (including a live "paused" state and base-branch-drift indicator), run history.
@@ -209,6 +211,21 @@ MCP tools that ship with the KB:
209
211
  | `kb_export` | Write live CONFIRMED entries to `.fleet/kb-canonical.json` -- the git-shareable team bible |
210
212
  | `kb_setup` | Install git hook, write provider config, store remote token encrypted |
211
213
 
214
+ `kb_setup --remote <url> --token <key>` takes effect immediately: the next
215
+ KB tool call resolves its project provider from this config, so a stock build
216
+ points at a remote KB server by configuration alone, with no code change and
217
+ no separate "server mode" build. A config with no remote, or any config the
218
+ reader cannot parse, always falls back to the local SQLite provider -- see
219
+ [Client-side provider selection](docs/knowledge-layer-design.md#client-side-provider-selection)
220
+ for the exact selection rule and its fallback-construction invariant.
221
+
222
+ **The provider config is install-wide, not per repo.** There is one
223
+ `knowledge/config.json` per fleet install, so pointing it at a remote KB
224
+ points EVERY repo that install serves -- every member, every project -- at
225
+ that server. `kb_setup`'s `repo_path` only chooses which repo gets the git
226
+ post-commit hook; it does not scope the config. On a shared fleet server,
227
+ treat `kb_setup --remote` as a change for all of its users.
228
+
212
229
  Every KB tool call is scoped to the repo it is about -- a fleet server
213
230
  handling many members across many repos never lets one repo's learnings land
214
231
  in another repo's KB. Scope is normally derived from the caller's repo path;
@@ -293,8 +310,9 @@ When NOT to use it: a one-off single-file change needs no fleet.
293
310
  ## Security model, in one paragraph
294
311
 
295
312
  Secrets are entered out-of-band into a credential store and referenced as
296
- `{{secure.NAME}}` -- resolved server-side at execution, never visible to
297
- any LLM or log. Credentials scope to members, expire on TTL, and can carry
313
+ `{{secret.NAME}}` -- resolved server-side at execution, never visible to
314
+ any LLM or log; see [docs/secret-variables.md](docs/secret-variables.md).
315
+ Credentials scope to members, expire on TTL, and can carry
298
316
  a network egress policy (allow / deny / confirm). Every member runs with
299
317
  composed, provider-native permission files -- allow-listed tools, not
300
318
  god-mode. VCS access is provisioned and revocable per member, across GitHub,
@@ -302,7 +320,12 @@ Bitbucket, and Azure DevOps -- host differences (URL shape, PR REST dialect,
302
320
  auth pattern, error vocabulary) are hidden behind a per-provider descriptor
303
321
  rather than leaking into shared code; see
304
322
  `docs/design-azure-devops-vcs-auth.md` for the Azure DevOps provider's
305
- credential-assembly and PAT-lifetime details. Permission
323
+ credential-assembly and PAT-lifetime details. A credential-requiring VCS
324
+ command can be handed to the server for execution (`vcs_credential_exec`)
325
+ rather than the orchestrator learning the plaintext token itself: the
326
+ server substitutes the credential into the command, runs it on the member,
327
+ and redacts the token from every field of the result -- the plaintext never
328
+ transits an orchestrator-readable output. Permission
306
329
  composition verifies its own delivery: a grant is read back off the target
307
330
  member and structurally compared against what was intended before it is
308
331
  reported as applied, so a failed or partial write is surfaced as an
@@ -423,12 +446,14 @@ third-party verticals.
423
446
  | Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
424
447
  | Keeping Fleet updated (`apra-fleet update`) | [docs/features/update.md](docs/features/update.md) |
425
448
  | Live member activity (`apra-fleet watch`, `logging.previewChars`) | [docs/features/watch.md](docs/features/watch.md) |
426
- | Secure credentials and passwords | [docs/features/oob-auth.md](docs/features/oob-auth.md) |
449
+ | Secret variables and passwords | [docs/secret-variables.md](docs/secret-variables.md) - [docs/features/oob-auth.md](docs/features/oob-auth.md) |
427
450
  | Member category and tags | [docs/features/member-tags.md](docs/features/member-tags.md) |
428
451
  | Enabling SSH on a remote machine (if it does not have it yet) | [docs/ssh-setup.md](docs/ssh-setup.md) |
429
452
  | Git authentication | [docs/design-git-auth.md](docs/design-git-auth.md) |
453
+ | GitHub App setup (exact permissions per git_access level) | [docs/github-app-setup.md](docs/github-app-setup.md) |
430
454
  | Cloud compute | [docs/cloud-compute.md](docs/cloud-compute.md) |
431
455
  | Architecture | [docs/architecture.md](docs/architecture.md) |
456
+ | Dispatch and orchestration reliability design (Windows completion-on-exit, stall detector, test-runner wall-clock bound) | [docs/dispatch-reliability-hardening.md](docs/dispatch-reliability-hardening.md) - [docs/stall-detector-resilience.md](docs/stall-detector-resilience.md) |
432
457
  | Windows shell selection (probe order, gitbash/pwsh7/powershell5, shell vs os) | [docs/windows-shell-selection.md](docs/windows-shell-selection.md) |
433
458
  | Cross-shell command construction for member-bound commands | [docs/cross-shell-command-construction.md](docs/cross-shell-command-construction.md) |
434
459
  | Knowledge Layer (setup, usage, provider swap) | [docs/knowledge-layer.md](docs/knowledge-layer.md) |
@@ -451,6 +476,9 @@ third-party verticals.
451
476
  | MCP client SDK overview (transports, `ApraFleet` API) | [packages/apra-fleet-client/docs/overview.md](packages/apra-fleet-client/docs/overview.md) |
452
477
  | MCP client SDK API reference | [packages/apra-fleet-client/docs/api-reference.md](packages/apra-fleet-client/docs/api-reference.md) |
453
478
  | MCP client SDK getting started | [packages/apra-fleet-client/docs/getting-started.md](packages/apra-fleet-client/docs/getting-started.md) |
479
+ | Memory contract v1 inventory findings and invariants (`kb_*`/`code_*` tool surface) | [docs/memory-contract-v1-inventory-notes.md](docs/memory-contract-v1-inventory-notes.md) |
480
+ | Memory contract v1 schema generation design (zod -> JSON Schema 2020-12) | [docs/memory-contract-v1-generator-design.md](docs/memory-contract-v1-generator-design.md) |
481
+ | Memory contract v1 round-trip validation, drift guard, and T1/T2/T3/T7 handoff design | [docs/memory-contract-v1-roundtrip-and-handoff.md](docs/memory-contract-v1-roundtrip-and-handoff.md) |
454
482
 
455
483
  ## Community
456
484
 
@@ -472,6 +500,11 @@ git clone https://github.com/Apra-Labs/apra-fleet && cd apra-fleet
472
500
  npm install && npm run build && npm test
473
501
  ```
474
502
 
503
+ `npm test` runs the full local suite: the root vitest suite, the
504
+ `apra-fleet-se` workspace suite, and the `apra-pm` suite (which is not an npm
505
+ workspace and is otherwise only reachable via an explicit `--prefix`
506
+ invocation) -- so a green local run and a green CI run see the same tests.
507
+
475
508
  See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute.
476
509
 
477
510
  ## License
@@ -12,7 +12,13 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
12
12
 
13
13
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any grooming decision)
14
14
 
15
+ <!-- if-tool: ToolSearch -->
15
16
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
17
+ <!-- else-tool: ToolSearch -->
18
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
19
+ tool it wants directly. Confirm your environment exposes those tools, then call
20
+ them as written.
21
+ <!-- end-tool: ToolSearch -->
16
22
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose backlog
17
23
  you are grooming, and `hint_modules` naming the subsystems the assigned beads touch.
18
24
  Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. This matters
@@ -22,7 +28,12 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
22
28
  items land unactionable -- call `mcp__apra-fleet__kb_capture` with type "knowledge".
23
29
  Do not capture per-sprint churn; capture what stays true.
24
30
 
31
+ <!-- if-tool: ToolSearch -->
25
32
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
33
+ <!-- else-tool: ToolSearch -->
34
+ If those KB tools are not available in your environment (MCP server not running), skip
35
+ these steps and proceed.
36
+ <!-- end-tool: ToolSearch -->
26
37
 
27
38
  ## Usage modes
28
39
 
@@ -189,6 +200,20 @@ Cross `priority`/urgency-language against content quality for every in-scope bea
189
200
  - **Priority x age**: compare `created_at`/`updated_at` to now, always jointly with
190
201
  priority. Old+low = noise; old+high = an explicit "still worth pursuing or stale?" call.
191
202
 
203
+ ## Step 6a -- Hygiene sweep (every time)
204
+
205
+ Same identity scope as everything else: beads assigned to other people are never touched.
206
+
207
+ - **Follow-ups under closed parents**: an open bead whose parent (epic or otherwise) is
208
+ closed is a leftover. Groom it -- close with evidence if landed or duplicate; otherwise
209
+ append the parent's context to its notes (parent title, goal, relevant decisions, key
210
+ files, originating branch/PR) so it stands alone, then detach it
211
+ (`bd update <id> --parent ""`) and label it `from-epic:<parent-id>`.
212
+ - **Fully closed epics** (epic and every descendant closed): list them as deletion
213
+ candidates with descendant counts. Never `bd delete` without operator confirmation.
214
+ - **No token-estimate memories**: never write per-bead or aggregate token/cost estimates
215
+ with `bd remember`; flag any found for `bd forget`.
216
+
192
217
  ## Step 7 -- Cohesive sprint-set proposal (1b)
193
218
 
194
219
  From the ready, verified, well-formed, non-duplicate subset only:
@@ -24,7 +24,13 @@ Your dispatch prompt must supply ONE of the two scoping forms:
24
24
 
25
25
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
26
26
 
27
+ <!-- if-tool: ToolSearch -->
27
28
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime"`
29
+ <!-- else-tool: ToolSearch -->
30
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
31
+ tool it wants directly. Confirm your environment exposes those tools, then call
32
+ them as written.
33
+ <!-- end-tool: ToolSearch -->
28
34
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose CI you
29
35
  are checking, and `hint_modules` naming its CI workflow files. Trust CONFIRMED entries
30
36
  fully. Use INFERRED entries as hints, not facts. Known-flaky tests and known CI failure
@@ -32,7 +38,12 @@ Your dispatch prompt must supply ONE of the two scoping forms:
32
38
  3. Do NOT capture. You poll a status API; you verify no claim about this repository, so you
33
39
  have no basis to write one down.
34
40
 
41
+ <!-- if-tool: ToolSearch -->
35
42
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
43
+ <!-- else-tool: ToolSearch -->
44
+ If those KB tools are not available in your environment (MCP server not running), skip
45
+ these steps and proceed.
46
+ <!-- end-tool: ToolSearch -->
36
47
 
37
48
  ## Step 1 -- List recent CI runs
38
49
 
@@ -11,6 +11,25 @@ code or modify project files. You do NOT run `integ-test-playbook.md` -- the
11
11
  test sandbox lifecycle (Setup / Reset / Teardown) and the tests themselves
12
12
  belong to `integ-test-runner`, which owns that playbook end to end.
13
13
 
14
+ ## Choose the right deploy mode FIRST
15
+
16
+ If `deploy.md` offers both a production deploy section and a sandbox /
17
+ test-isolated deploy section, decide which one applies before running
18
+ anything:
19
+
20
+ - **Dispatched for integration or regression testing** (a sprint-dispatched
21
+ deploy always is, and the dispatch prompt says so explicitly) -> use the
22
+ SANDBOX section. It stands up an isolated instance alongside whatever is
23
+ already running, so you never stop, kill, or restart live infrastructure.
24
+ - **A real production rollout** (an operator asked for one directly) -> use
25
+ the production section.
26
+
27
+ When in doubt, prefer the sandbox section and say so in `notes`: deploying in
28
+ isolation is recoverable, restarting a machine's shared production singleton
29
+ is not. Never stop or restart a running server just to make a test deploy
30
+ succeed -- if the runbook's production path seems to require that and you were
31
+ dispatched for testing, you are in the wrong section.
32
+
14
33
  ## Inputs
15
34
 
16
35
  Your dispatch prompt must supply:
@@ -71,7 +90,13 @@ Step 0a while any permission is missing.
71
90
 
72
91
  ## Step 0b -- Knowledge Bank (required -- do this BEFORE any deploy.md operation)
73
92
 
93
+ <!-- if-tool: ToolSearch -->
74
94
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
95
+ <!-- else-tool: ToolSearch -->
96
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
97
+ tool it wants directly. Confirm your environment exposes those tools, then call
98
+ them as written.
99
+ <!-- end-tool: ToolSearch -->
75
100
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being deployed,
76
101
  and `hint_modules` naming the deploy targets in `deploy.md`. Trust CONFIRMED entries
77
102
  fully. Use INFERRED entries as hints, not facts.
@@ -79,17 +104,27 @@ Step 0a while any permission is missing.
79
104
  be wrong or incomplete, call `mcp__apra-fleet__kb_capture` with type "runbook" or
80
105
  "learning". A deploy gotcha you had to discover is exactly what the next deploy needs.
81
106
 
107
+ <!-- if-tool: ToolSearch -->
82
108
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
109
+ <!-- else-tool: ToolSearch -->
110
+ If those KB tools are not available in your environment (MCP server not running), skip
111
+ these steps and proceed.
112
+ <!-- end-tool: ToolSearch -->
83
113
 
84
114
  ## deploy.md operations
85
115
 
86
116
  When asked to deploy:
87
117
 
88
118
  1. Read `deploy.md` -- understand the Deploy, Smoke test, and CI sections
89
- 2. Execute every command in the `## Deploy` section in order
90
- 3. Run the command in `## Smoke test`
119
+ 2. Execute every command in the section chosen above (`## Deploy`, or the
120
+ sandbox section) in order
121
+ 3. Run that section's smoke test
91
122
  - Exit 0 = healthy -> return `deployed: true`
92
123
  - Any other exit or error -> return `deployed: false`, include full error output in `notes`
124
+ 4. If the section says the deployed instance stays RUNNING for the test
125
+ phase that follows, leave it running -- do not tear it down after a
126
+ successful deploy. Report in `notes` whatever the runbook says a later
127
+ phase needs to locate it.
93
128
 
94
129
  If a command fails mid-deploy, stop immediately and return `deployed: false`
95
130
  with the failing command and its output in `notes`.
@@ -63,8 +63,14 @@ explicitly names an already-collected evidence artifact to verify against.
63
63
 
64
64
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
65
65
 
66
+ <!-- if-tool: ToolSearch -->
66
67
  1. Run ToolSearch with query
67
68
  `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback,mcp__apra-fleet__code_context,mcp__apra-fleet__code_graph,mcp__apra-fleet__code_impact,mcp__apra-fleet__code_query"`
69
+ <!-- else-tool: ToolSearch -->
70
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
71
+ tool it wants directly. Confirm your environment exposes those tools, then call
72
+ them as written.
73
+ <!-- end-tool: ToolSearch -->
68
74
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo you are
69
75
  working in, and `hint_symbols`/`hint_modules` relevant to the files and symbols you are
70
76
  about to touch. Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
@@ -86,19 +92,36 @@ explicitly names an already-collected evidence artifact to verify against.
86
92
  grep for symbol lookups, call-chain tracing, and impact analysis. If the repo is not
87
93
  indexed, fall back to grep; do not try to build an index yourself.
88
94
 
95
+ <!-- if-tool: ToolSearch -->
89
96
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
97
+ <!-- else-tool: ToolSearch -->
98
+ If those KB tools are not available in your environment (MCP server not running), skip
99
+ these steps and proceed.
100
+ <!-- end-tool: ToolSearch -->
90
101
 
91
102
  ## Step 1 -- Work only your assigned bead ids
92
103
 
93
104
  Do NOT run bare `bd ready` to discover work -- it returns ready beads from the entire
94
105
  database, including other concurrent sprints/tracks. Work exactly the bead ids listed in
95
106
  your dispatch prompt's "Assigned bead ids," in the order given if any depend on each
96
- other, and no others. If an assigned id turns out to HAVE OPEN CHILDREN
97
- (`bd list --parent <id> --json` -- no `--all` -- returns any bead; `bd show <id> --json`'s
98
- `dependent_count` is NOT this check, it counts closed children too), it is a decomposed
99
- container assigned to you in error: skip it, note why in your final report, and do not
100
- claim or close it. **`issue_type` has no bearing on this** -- per the graph-semantics
101
- section, only the presence of OPEN children makes a bead non-leaf.
107
+ other, and no others.
108
+
109
+ **Same-lane stop rule**: before starting Step 2's per-id loop, read `metadata.streak` for
110
+ every assigned id up front with `bd show <id> --json` (a cheap read, not a claim). If you
111
+ later leave an earlier assigned bead OPEN (a legitimate skip or a failure), check that map
112
+ for a later assigned bead sharing its `streak` value -- tasks in the same lane were planned
113
+ as one dependent increment. If one shares it, do NOT claim that later bead: stop, and
114
+ return VERIFY listing what you closed and why you stopped (this is a legal early VERIFY,
115
+ see Step 3). A later assigned bead in a DIFFERENT lane, or with no `streak` shared with the
116
+ skipped one, is unaffected -- keep working it normally; your assignment may bundle several
117
+ independent lanes into one session.
118
+
119
+ If an assigned id turns out to HAVE OPEN CHILDREN (`bd list --parent <id> --json` -- no
120
+ `--all` -- returns any bead; `bd show <id> --json`'s `dependent_count` is NOT this check,
121
+ it counts closed children too), it is a decomposed container assigned to you in error:
122
+ skip it, note why in your final report, and do not claim or close it. **`issue_type` has
123
+ no bearing on this** -- per the graph-semantics section, only the presence of OPEN
124
+ children makes a bead non-leaf.
102
125
 
103
126
  A bead whose children are ALL closed is NOT this case -- see Step 2.2's wrap-up handling
104
127
  below; do not skip it on that basis alone.
@@ -200,8 +223,9 @@ killed mid-work. Instead:
200
223
  **STOP RULE:** the instant `bd close` returns for your last assigned bead id (or your last remaining id is disposed of via an explicit skip exception), your ONLY next action is emitting the VERIFY JSON below. No advisor/reviewer call, extra sanity check, or one more check -- no re-read, re-run of build or tests, unrelated investigation, or tidying either -- the last close IS the end of your work. Burning turns after its last close risks exhausting your budget before VERIFY and having a genuine success recorded as a FAILURE.
201
224
 
202
225
  When every assigned bead id has been closed (or explicitly skipped per Step 1's
203
- has-open-children case, Step 2.2's ambiguous-wrap-up case, the scope/criteria-defect
204
- escape hatch, or the missing-input behavior above), you MUST stop and return:
226
+ has-open-children case, Step 1's same-lane stop rule, Step 2.2's ambiguous-wrap-up case,
227
+ the scope/criteria-defect escape hatch, or the missing-input behavior above), you MUST
228
+ stop and return:
205
229
  ```json
206
230
  { "status": "VERIFY", "closedIds": ["<id>", "..."], "notes": "string" }
207
231
  ```
@@ -247,10 +271,10 @@ or as prose if you are answering a human directly.
247
271
  returns any bead); `issue_type` has no bearing. All-children-closed is not this case --
248
272
  see Step 2.2.
249
273
  - NEVER skip an assigned bead id for convenience -- work them in dependency order. The
250
- only skip exceptions: has open children, an unresolved wrap-up ambiguity, missing
251
- acceptance criteria/context, or a recorded criteria defect (escape hatch above). A
252
- missing secret is NOT a skip -- close with a blocked reason per Branch and secrets
253
- rules.
274
+ only skip exceptions: has open children, the same-lane stop rule (Step 1) after an
275
+ earlier lane-mate was left open, an unresolved wrap-up ambiguity, missing acceptance
276
+ criteria/context, or a recorded criteria defect (escape hatch above). A missing secret
277
+ is NOT a skip -- close with a blocked reason per Branch and secrets rules.
254
278
  - Tests for the changed area must pass before each commit (Step 2.5)
255
279
  - No PLAN.md, no progress.json -- beads is the only work tracker
256
280
  - If the target repo replays `bd` from recorded fixtures in its tests, record any NEW
@@ -33,7 +33,13 @@ a missing `base-branch`/`branch`: do not guess which branch to diff.
33
33
 
34
34
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
35
35
 
36
+ <!-- if-tool: ToolSearch -->
36
37
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback"`
38
+ <!-- else-tool: ToolSearch -->
39
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
40
+ tool it wants directly. Confirm your environment exposes those tools, then call
41
+ them as written.
42
+ <!-- end-tool: ToolSearch -->
37
43
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being harvested,
38
44
  and `hint_symbols`/`hint_modules` relevant to the modules touched during the sprint.
39
45
  Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
@@ -45,7 +51,12 @@ a missing `base-branch`/`branch`: do not guess which branch to diff.
45
51
  4. If a retrieved KB entry proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
46
52
  with the entry id and what was wrong.
47
53
 
54
+ <!-- if-tool: ToolSearch -->
48
55
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
56
+ <!-- else-tool: ToolSearch -->
57
+ If those KB tools are not available in your environment (MCP server not running), skip
58
+ these steps and proceed.
59
+ <!-- end-tool: ToolSearch -->
49
60
 
50
61
  ## Step 1 -- Write sprint analysis artifact (FIRST, before anything else)
51
62
 
@@ -63,7 +63,13 @@ from and does not gate yours.
63
63
 
64
64
  ## Step 0c -- Knowledge Bank (required -- do this BEFORE working any feature)
65
65
 
66
+ <!-- if-tool: ToolSearch -->
66
67
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
68
+ <!-- else-tool: ToolSearch -->
69
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
70
+ tool it wants directly. Confirm your environment exposes those tools, then call
71
+ them as written.
72
+ <!-- end-tool: ToolSearch -->
67
73
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo under test, and
68
74
  `hint_symbols`/`hint_modules` relevant to the features you were handed. Trust CONFIRMED
69
75
  entries fully. Use INFERRED entries as hints, not facts. An entry recording that a test
@@ -72,7 +78,12 @@ from and does not gate yours.
72
78
  the playbook does not record, call `mcp__apra-fleet__kb_capture` with type "knowledge" or
73
79
  "learning".
74
80
 
81
+ <!-- if-tool: ToolSearch -->
75
82
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
83
+ <!-- else-tool: ToolSearch -->
84
+ If those KB tools are not available in your environment (MCP server not running), skip
85
+ these steps and proceed.
86
+ <!-- end-tool: ToolSearch -->
76
87
 
77
88
  ## Step 1 -- Work the features you were handed
78
89
 
@@ -31,11 +31,20 @@ yourself via `kb_query`/`kb_list`.
31
31
 
32
32
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
33
33
 
34
+ <!-- if-tool: ToolSearch -->
34
35
  1. Run ToolSearch with query
35
36
  `"select:mcp__apra-fleet__code_context,mcp__apra-fleet__code_impact,mcp__apra-fleet__code_query,mcp__apra-fleet__kb_resolve_contradiction,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_list,mcp__apra-fleet__kb_export"`
36
37
  2. If ToolSearch returns no KB tools (MCP server not running), stop and report that
37
38
  reconciliation cannot proceed -- do not guess winners without `kb_resolve_contradiction`
38
39
  available.
40
+ <!-- else-tool: ToolSearch -->
41
+ 1. No tool-discovery step is needed on this provider: the steps below name the tools
42
+ they want directly. Confirm your environment exposes `kb_resolve_contradiction`,
43
+ `kb_query`, `kb_list`, `kb_export`, and the code-reading tools.
44
+ 2. If those tools are not available (MCP server not running), stop and report that
45
+ reconciliation cannot proceed -- do not guess winners without `kb_resolve_contradiction`
46
+ available.
47
+ <!-- end-tool: ToolSearch -->
39
48
 
40
49
  ## The single write path (binding -- read this before resolving anything)
41
50
 
@@ -50,7 +50,13 @@ to satisfy a criterion as SETTLED for the rest of the cycle:
50
50
 
51
51
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
52
52
 
53
+ <!-- if-tool: ToolSearch -->
53
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 -->
54
60
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being planned
55
61
  for, and `hint_symbols`/`hint_modules` relevant to the features in the DAG under review.
56
62
  Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. An entry
@@ -59,7 +65,12 @@ to satisfy a criterion as SETTLED for the rest of the cycle:
59
65
  an invariant), call `mcp__apra-fleet__kb_capture` immediately with type "knowledge" or
60
66
  "learning".
61
67
 
68
+ <!-- if-tool: ToolSearch -->
62
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 -->
63
74
 
64
75
  ## Step 1 -- Inspect the DAG
65
76
 
@@ -76,8 +87,21 @@ For each open feature and its tasks, run `bd show <id>` to read the full descrip
76
87
  1. **Coverage**: every open sprint goal has at least one feature that directly addresses it
77
88
  2. **Test tasks**: every feature has at least one `[test]` task
78
89
  3. **Acceptance criteria**: every task description states concretely what done looks like
79
- 4. **Task size**: no task should require more than ~3 file changes; flag larger ones
80
- 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.
81
105
  6. **No scope creep**: tasks address only the original sprint goals and open bugs/features
82
106
  7. **No duplicate work**: no two tasks do the same thing
83
107
  8. **Feasibility**: no task assumes something that has not been built yet
@@ -106,26 +130,58 @@ For each open feature and its tasks, run `bd show <id>` to read the full descrip
106
130
  in `bd show <id>` -- the single location, per `planner.md` Step 3; never `--notes`
107
131
  or free text). A missing key is a criterion-10 failure; Step 3's fallback is for
108
132
  classification/reporting only.
109
- 11. **Lane cohesion**: every task carries `streak` and `streakOrder` in the same
110
- `--metadata` channel as `model` -- a task missing either key is a criterion-11
111
- finding. Beyond presence, check:
112
- - **Cohesive lanes**: the tasks sharing a `streak` id name overlapping files or the same
113
- component/module in their descriptions -- a lane grouping unrelated work areas is a
114
- finding.
115
- - **No cross-lane edges among open members**: no `blocks` edge exists between an open
116
- task in one lane and an open task in a different lane -- ordering across lanes must
117
- come from lane sequencing, not a raw dependency edge spanning two streaks.
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.
118
153
  - **Mutex resources co-laned**: tasks that contend for the same mutual-exclusion
119
154
  resource (a resource only one change may hold at a time -- e.g. the same submodule
120
155
  pointer, a shared version/manifest field, or the same test fixture) share one `streak`
121
156
  and are never split across lanes.
122
- - **Effort under threshold**: for each lane, `effort = (sum of size points over the
123
- lane's tasks, S=1/M=2/L=4) x (max model weight in the lane, cheap=1/standard=10/
124
- premium=20)` stays at or under the effort threshold constant (default `200`). A lane
125
- over threshold is a finding unless it was split at a `blocks`-edge boundary without
126
- separating mutex-resource members (per `planner.md`'s splitting math).
127
- A violation of any bullet above is CHANGES_NEEDED referencing "criterion 11" and the
128
- 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).
129
185
 
130
186
  ## Step 3 -- Classify each task
131
187
 
@@ -141,21 +197,48 @@ For each open `type=task` issue, determine:
141
197
  criterion 10 as a CHANGES_NEEDED finding -- the fallback lets you finish
142
198
  classification, it does not excuse the planner.
143
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.
204
+
144
205
  ## Step 4 -- Output verdict
145
206
 
146
207
  Return your verdict:
147
208
  - `verdict`: `"APPROVED"` or `"CHANGES_NEEDED"` (exact strings -- the machine-readable
148
209
  enum in the output schema uses the underscore form, never "CHANGES NEEDED" with a space)
149
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.
150
219
  - `taskAssignments`: array with one entry per open task -- `{ id, bucket, model }`
151
220
 
152
- **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.
153
226
 
154
227
  **CHANGES_NEEDED** means one or more criteria fail. Notes must name the specific beads ID
155
- 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.
156
231
 
157
232
  Always populate `taskAssignments` even on CHANGES_NEEDED -- cost estimation uses it regardless.
158
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
+
159
242
  ## Output schema
160
243
 
161
244
  The canonical machine-readable contract for this output lives in the sibling file
@@ -165,10 +248,15 @@ placeholder):
165
248
  ```json
166
249
  {
167
250
  "verdict": "CHANGES_NEEDED",
168
- "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
+ ],
169
256
  "taskAssignments": [
170
257
  { "id": "BD-10", "bucket": "M", "model": "standard" },
171
- { "id": "BD-14", "bucket": "S", "model": "cheap" }
258
+ { "id": "BD-14", "bucket": "S", "model": "cheap" },
259
+ { "id": "BD-22", "bucket": "S", "model": "standard" }
172
260
  ]
173
261
  }
174
262
  ```