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