@apralabs/apra-fleet 0.4.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (476) hide show
  1. package/README.md +53 -12
  2. package/dist/agents/backlog-groomer.md +42 -21
  3. package/dist/agents/ci-watcher.md +14 -0
  4. package/dist/agents/deployer.md +59 -46
  5. package/dist/agents/doer.md +157 -134
  6. package/dist/agents/harvester.md +31 -32
  7. package/dist/agents/integ-test-runner.md +92 -113
  8. package/dist/agents/kb-reconciler.md +40 -42
  9. package/dist/agents/plan-reviewer.md +139 -63
  10. package/dist/agents/planner.md +176 -100
  11. package/dist/agents/regression-test-runner.md +77 -81
  12. package/dist/agents/reviewer.md +69 -85
  13. package/dist/agents/schemas/integ-test-runner-output.json +1 -1
  14. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  15. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  16. package/dist/cli/agent-transform.d.ts +83 -2
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +266 -21
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +29 -11
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +7 -5
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +44 -43
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +33 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +294 -61
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/kb-directives.d.ts.map +1 -1
  32. package/dist/cli/kb-directives.js +2 -1
  33. package/dist/cli/kb-directives.js.map +1 -1
  34. package/dist/cli/register-member.d.ts.map +1 -1
  35. package/dist/cli/register-member.js +7 -3
  36. package/dist/cli/register-member.js.map +1 -1
  37. package/dist/cli/start.d.ts.map +1 -1
  38. package/dist/cli/start.js +7 -0
  39. package/dist/cli/start.js.map +1 -1
  40. package/dist/cli/uninstall.d.ts.map +1 -1
  41. package/dist/cli/uninstall.js +5 -3
  42. package/dist/cli/uninstall.js.map +1 -1
  43. package/dist/cli/watch.d.ts +26 -3
  44. package/dist/cli/watch.d.ts.map +1 -1
  45. package/dist/cli/watch.js +41 -9
  46. package/dist/cli/watch.js.map +1 -1
  47. package/dist/commands/kb-server.d.ts +3 -0
  48. package/dist/commands/kb-server.d.ts.map +1 -1
  49. package/dist/commands/kb-server.js +43 -3
  50. package/dist/commands/kb-server.js.map +1 -1
  51. package/dist/index.js +3 -3
  52. package/dist/os/git-bash-candidates.d.ts +35 -0
  53. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  54. package/dist/os/git-bash-candidates.js +46 -0
  55. package/dist/os/git-bash-candidates.js.map +1 -0
  56. package/dist/os/index.d.ts +13 -4
  57. package/dist/os/index.d.ts.map +1 -1
  58. package/dist/os/index.js +17 -2
  59. package/dist/os/index.js.map +1 -1
  60. package/dist/os/linux.d.ts +6 -0
  61. package/dist/os/linux.d.ts.map +1 -1
  62. package/dist/os/linux.js +36 -3
  63. package/dist/os/linux.js.map +1 -1
  64. package/dist/os/os-commands.d.ts +68 -2
  65. package/dist/os/os-commands.d.ts.map +1 -1
  66. package/dist/os/os-commands.js.map +1 -1
  67. package/dist/os/windows-gitbash.d.ts +98 -0
  68. package/dist/os/windows-gitbash.d.ts.map +1 -0
  69. package/dist/os/windows-gitbash.js +259 -0
  70. package/dist/os/windows-gitbash.js.map +1 -0
  71. package/dist/os/windows.d.ts +6 -0
  72. package/dist/os/windows.d.ts.map +1 -1
  73. package/dist/os/windows.js +73 -8
  74. package/dist/os/windows.js.map +1 -1
  75. package/dist/providers/agy.d.ts +118 -8
  76. package/dist/providers/agy.d.ts.map +1 -1
  77. package/dist/providers/agy.js +580 -55
  78. package/dist/providers/agy.js.map +1 -1
  79. package/dist/providers/claude.d.ts +83 -4
  80. package/dist/providers/claude.d.ts.map +1 -1
  81. package/dist/providers/claude.js +365 -12
  82. package/dist/providers/claude.js.map +1 -1
  83. package/dist/providers/codex.d.ts +7 -4
  84. package/dist/providers/codex.d.ts.map +1 -1
  85. package/dist/providers/codex.js +24 -4
  86. package/dist/providers/codex.js.map +1 -1
  87. package/dist/providers/copilot.d.ts +7 -4
  88. package/dist/providers/copilot.d.ts.map +1 -1
  89. package/dist/providers/copilot.js +27 -4
  90. package/dist/providers/copilot.js.map +1 -1
  91. package/dist/providers/index.d.ts +0 -1
  92. package/dist/providers/index.d.ts.map +1 -1
  93. package/dist/providers/index.js +0 -3
  94. package/dist/providers/index.js.map +1 -1
  95. package/dist/providers/none.d.ts +7 -4
  96. package/dist/providers/none.d.ts.map +1 -1
  97. package/dist/providers/none.js +22 -4
  98. package/dist/providers/none.js.map +1 -1
  99. package/dist/providers/opencode.d.ts +6 -3
  100. package/dist/providers/opencode.d.ts.map +1 -1
  101. package/dist/providers/opencode.js +27 -4
  102. package/dist/providers/opencode.js.map +1 -1
  103. package/dist/providers/provider.d.ts +215 -11
  104. package/dist/providers/provider.d.ts.map +1 -1
  105. package/dist/providers/provider.js +58 -2
  106. package/dist/providers/provider.js.map +1 -1
  107. package/dist/services/agent-provisioner.js +2 -2
  108. package/dist/services/agent-provisioner.js.map +1 -1
  109. package/dist/services/agy-project.d.ts +102 -0
  110. package/dist/services/agy-project.d.ts.map +1 -0
  111. package/dist/services/agy-project.js +356 -0
  112. package/dist/services/agy-project.js.map +1 -0
  113. package/dist/services/auth-socket.js +4 -4
  114. package/dist/services/auth-web.js +1 -1
  115. package/dist/services/cloud/activity.js +2 -2
  116. package/dist/services/cloud/activity.js.map +1 -1
  117. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  118. package/dist/services/cloud/lifecycle.js +33 -4
  119. package/dist/services/cloud/lifecycle.js.map +1 -1
  120. package/dist/services/context-admission.d.ts.map +1 -1
  121. package/dist/services/context-admission.js +9 -7
  122. package/dist/services/context-admission.js.map +1 -1
  123. package/dist/services/credential-cleanup.d.ts.map +1 -1
  124. package/dist/services/credential-cleanup.js +47 -10
  125. package/dist/services/credential-cleanup.js.map +1 -1
  126. package/dist/services/exit-drain.d.ts +44 -0
  127. package/dist/services/exit-drain.d.ts.map +1 -0
  128. package/dist/services/exit-drain.js +52 -0
  129. package/dist/services/exit-drain.js.map +1 -0
  130. package/dist/services/github-app.d.ts.map +1 -1
  131. package/dist/services/github-app.js +32 -4
  132. package/dist/services/github-app.js.map +1 -1
  133. package/dist/services/http-transport.d.ts +1 -0
  134. package/dist/services/http-transport.d.ts.map +1 -1
  135. package/dist/services/http-transport.js +48 -1
  136. package/dist/services/http-transport.js.map +1 -1
  137. package/dist/services/knowledge/kb-config.d.ts +42 -0
  138. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-config.js +54 -0
  140. package/dist/services/knowledge/kb-config.js.map +1 -0
  141. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  142. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  143. package/dist/services/knowledge/kb-providers.js +191 -17
  144. package/dist/services/knowledge/kb-providers.js.map +1 -1
  145. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  146. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  147. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  148. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  149. package/dist/services/member-home.d.ts +1 -1
  150. package/dist/services/member-home.d.ts.map +1 -1
  151. package/dist/services/member-home.js +15 -12
  152. package/dist/services/member-home.js.map +1 -1
  153. package/dist/services/model-pricing.d.ts.map +1 -1
  154. package/dist/services/model-pricing.js +7 -8
  155. package/dist/services/model-pricing.js.map +1 -1
  156. package/dist/services/orphan-recovery.d.ts +6 -3
  157. package/dist/services/orphan-recovery.d.ts.map +1 -1
  158. package/dist/services/orphan-recovery.js +17 -14
  159. package/dist/services/orphan-recovery.js.map +1 -1
  160. package/dist/services/preflight-check.js +2 -2
  161. package/dist/services/preflight-check.js.map +1 -1
  162. package/dist/services/secret-token.d.ts +38 -0
  163. package/dist/services/secret-token.d.ts.map +1 -0
  164. package/dist/services/secret-token.js +51 -0
  165. package/dist/services/secret-token.js.map +1 -0
  166. package/dist/services/service-manager/types.d.ts +3 -1
  167. package/dist/services/service-manager/types.d.ts.map +1 -1
  168. package/dist/services/service-manager/windows.d.ts +14 -2
  169. package/dist/services/service-manager/windows.d.ts.map +1 -1
  170. package/dist/services/service-manager/windows.js +65 -7
  171. package/dist/services/service-manager/windows.js.map +1 -1
  172. package/dist/services/shell-probe.d.ts +131 -0
  173. package/dist/services/shell-probe.d.ts.map +1 -0
  174. package/dist/services/shell-probe.js +210 -0
  175. package/dist/services/shell-probe.js.map +1 -0
  176. package/dist/services/singleton.d.ts +2 -0
  177. package/dist/services/singleton.d.ts.map +1 -1
  178. package/dist/services/singleton.js +1 -1
  179. package/dist/services/singleton.js.map +1 -1
  180. package/dist/services/ssh.d.ts.map +1 -1
  181. package/dist/services/ssh.js +60 -4
  182. package/dist/services/ssh.js.map +1 -1
  183. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  184. package/dist/services/stall/find-log-file.js +22 -16
  185. package/dist/services/stall/find-log-file.js.map +1 -1
  186. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  187. package/dist/services/stall/read-log-tail.js +26 -15
  188. package/dist/services/stall/read-log-tail.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +53 -4
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +212 -34
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  194. package/dist/services/stall/stall-poller.js +35 -42
  195. package/dist/services/stall/stall-poller.js.map +1 -1
  196. package/dist/services/strategy.d.ts +9 -0
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +119 -8
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/substitution-engine.js +2 -2
  201. package/dist/services/substitution-engine.js.map +1 -1
  202. package/dist/services/tool-registry.d.ts.map +1 -1
  203. package/dist/services/tool-registry.js +5 -3
  204. package/dist/services/tool-registry.js.map +1 -1
  205. package/dist/services/user-config.js +1 -1
  206. package/dist/services/user-config.js.map +1 -1
  207. package/dist/services/vcs/azure-devops.d.ts +67 -2
  208. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  209. package/dist/services/vcs/azure-devops.js +281 -15
  210. package/dist/services/vcs/azure-devops.js.map +1 -1
  211. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  212. package/dist/services/vcs/bitbucket.js +16 -0
  213. package/dist/services/vcs/bitbucket.js.map +1 -1
  214. package/dist/services/vcs/github.d.ts.map +1 -1
  215. package/dist/services/vcs/github.js +24 -0
  216. package/dist/services/vcs/github.js.map +1 -1
  217. package/dist/services/vcs/types.d.ts +123 -2
  218. package/dist/services/vcs/types.d.ts.map +1 -1
  219. package/dist/skills/fleet-sprint-cli/SKILL.md +20 -1
  220. package/dist/skills/pm/SKILL.md +1 -2
  221. package/dist/skills/pm/cost.md +0 -4
  222. package/dist/skills/pm/fleet-addendum.md +2 -3
  223. package/dist/tools/check-status.d.ts +7 -4
  224. package/dist/tools/check-status.d.ts.map +1 -1
  225. package/dist/tools/check-status.js +5 -3
  226. package/dist/tools/check-status.js.map +1 -1
  227. package/dist/tools/cloud-control.js +2 -2
  228. package/dist/tools/cloud-control.js.map +1 -1
  229. package/dist/tools/compose-permissions.d.ts +6 -0
  230. package/dist/tools/compose-permissions.d.ts.map +1 -1
  231. package/dist/tools/compose-permissions.js +211 -50
  232. package/dist/tools/compose-permissions.js.map +1 -1
  233. package/dist/tools/credential-store-set.js +1 -1
  234. package/dist/tools/execute-command.d.ts.map +1 -1
  235. package/dist/tools/execute-command.js +56 -29
  236. package/dist/tools/execute-command.js.map +1 -1
  237. package/dist/tools/execute-prompt.d.ts +15 -2
  238. package/dist/tools/execute-prompt.d.ts.map +1 -1
  239. package/dist/tools/execute-prompt.js +1214 -873
  240. package/dist/tools/execute-prompt.js.map +1 -1
  241. package/dist/tools/kb-capture.d.ts +2 -2
  242. package/dist/tools/kb-capture.d.ts.map +1 -1
  243. package/dist/tools/kb-capture.js +29 -5
  244. package/dist/tools/kb-capture.js.map +1 -1
  245. package/dist/tools/kb-export.d.ts +2 -2
  246. package/dist/tools/kb-export.d.ts.map +1 -1
  247. package/dist/tools/kb-export.js +3 -28
  248. package/dist/tools/kb-export.js.map +1 -1
  249. package/dist/tools/kb-feedback.d.ts.map +1 -1
  250. package/dist/tools/kb-feedback.js +3 -1
  251. package/dist/tools/kb-feedback.js.map +1 -1
  252. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  253. package/dist/tools/kb-freshness-sweep.js +3 -1
  254. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  255. package/dist/tools/kb-import.d.ts.map +1 -1
  256. package/dist/tools/kb-import.js +2 -1
  257. package/dist/tools/kb-import.js.map +1 -1
  258. package/dist/tools/kb-list.d.ts.map +1 -1
  259. package/dist/tools/kb-list.js +3 -1
  260. package/dist/tools/kb-list.js.map +1 -1
  261. package/dist/tools/kb-query.d.ts +2 -2
  262. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  263. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  264. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  265. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  266. package/dist/tools/kb-resolve-contradiction.js +3 -1
  267. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  268. package/dist/tools/kb-setup.d.ts.map +1 -1
  269. package/dist/tools/kb-setup.js +125 -20
  270. package/dist/tools/kb-setup.js.map +1 -1
  271. package/dist/tools/kb-stats.d.ts.map +1 -1
  272. package/dist/tools/kb-stats.js +64 -43
  273. package/dist/tools/kb-stats.js.map +1 -1
  274. package/dist/tools/list-members.d.ts +2 -2
  275. package/dist/tools/list-members.d.ts.map +1 -1
  276. package/dist/tools/list-members.js +7 -2
  277. package/dist/tools/list-members.js.map +1 -1
  278. package/dist/tools/member-detail.d.ts +2 -2
  279. package/dist/tools/member-detail.d.ts.map +1 -1
  280. package/dist/tools/member-detail.js +22 -3
  281. package/dist/tools/member-detail.js.map +1 -1
  282. package/dist/tools/member-reservation.d.ts +58 -1
  283. package/dist/tools/member-reservation.d.ts.map +1 -1
  284. package/dist/tools/member-reservation.js +71 -18
  285. package/dist/tools/member-reservation.js.map +1 -1
  286. package/dist/tools/monitor-task.d.ts.map +1 -1
  287. package/dist/tools/monitor-task.js +17 -2
  288. package/dist/tools/monitor-task.js.map +1 -1
  289. package/dist/tools/provision-auth.d.ts +80 -1
  290. package/dist/tools/provision-auth.d.ts.map +1 -1
  291. package/dist/tools/provision-auth.js +147 -59
  292. package/dist/tools/provision-auth.js.map +1 -1
  293. package/dist/tools/provision-vcs-auth.d.ts +96 -3
  294. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  295. package/dist/tools/provision-vcs-auth.js +254 -88
  296. package/dist/tools/provision-vcs-auth.js.map +1 -1
  297. package/dist/tools/register-member.d.ts +21 -12
  298. package/dist/tools/register-member.d.ts.map +1 -1
  299. package/dist/tools/register-member.js +141 -16
  300. package/dist/tools/register-member.js.map +1 -1
  301. package/dist/tools/remove-member.d.ts.map +1 -1
  302. package/dist/tools/remove-member.js +29 -4
  303. package/dist/tools/remove-member.js.map +1 -1
  304. package/dist/tools/revoke-vcs-auth.js +2 -2
  305. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  306. package/dist/tools/send-email.d.ts +2 -2
  307. package/dist/tools/setup-git-app.d.ts.map +1 -1
  308. package/dist/tools/setup-git-app.js +11 -7
  309. package/dist/tools/setup-git-app.js.map +1 -1
  310. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  311. package/dist/tools/setup-ssh-key.js +2 -1
  312. package/dist/tools/setup-ssh-key.js.map +1 -1
  313. package/dist/tools/shutdown-server.d.ts +2 -0
  314. package/dist/tools/shutdown-server.d.ts.map +1 -1
  315. package/dist/tools/shutdown-server.js +23 -1
  316. package/dist/tools/shutdown-server.js.map +1 -1
  317. package/dist/tools/stop-prompt.js +2 -2
  318. package/dist/tools/stop-prompt.js.map +1 -1
  319. package/dist/tools/update-agent-cli.js +2 -2
  320. package/dist/tools/update-agent-cli.js.map +1 -1
  321. package/dist/tools/update-member.d.ts +21 -12
  322. package/dist/tools/update-member.d.ts.map +1 -1
  323. package/dist/tools/update-member.js +61 -12
  324. package/dist/tools/update-member.js.map +1 -1
  325. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  326. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  327. package/dist/tools/vcs-credential-exec.js +197 -0
  328. package/dist/tools/vcs-credential-exec.js.map +1 -0
  329. package/dist/types.d.ts +24 -1
  330. package/dist/types.d.ts.map +1 -1
  331. package/dist/utils/agent-helpers.d.ts +36 -0
  332. package/dist/utils/agent-helpers.d.ts.map +1 -1
  333. package/dist/utils/agent-helpers.js +39 -1
  334. package/dist/utils/agent-helpers.js.map +1 -1
  335. package/dist/utils/log-helpers.d.ts.map +1 -1
  336. package/dist/utils/log-helpers.js +2 -2
  337. package/dist/utils/log-helpers.js.map +1 -1
  338. package/dist/utils/platform.d.ts +7 -0
  339. package/dist/utils/platform.d.ts.map +1 -1
  340. package/dist/utils/platform.js +11 -1
  341. package/dist/utils/platform.js.map +1 -1
  342. package/dist/utils/prompt-errors.d.ts.map +1 -1
  343. package/dist/utils/prompt-errors.js +7 -1
  344. package/dist/utils/prompt-errors.js.map +1 -1
  345. package/dist/utils/shell-escape.d.ts +16 -0
  346. package/dist/utils/shell-escape.d.ts.map +1 -1
  347. package/dist/utils/shell-escape.js +22 -2
  348. package/dist/utils/shell-escape.js.map +1 -1
  349. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  350. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  351. package/dist/utils/vcs-provider-detect.js +109 -0
  352. package/dist/utils/vcs-provider-detect.js.map +1 -0
  353. package/dist/utils/workspace-trust.d.ts +20 -17
  354. package/dist/utils/workspace-trust.d.ts.map +1 -1
  355. package/dist/utils/workspace-trust.js +91 -1
  356. package/dist/utils/workspace-trust.js.map +1 -1
  357. package/dist/workflows/auto-sprint.js +180 -32
  358. package/package.json +7 -5
  359. package/packages/apra-fleet-client/src/client/api.mjs +403 -12
  360. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  361. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  362. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +42 -21
  363. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +14 -0
  364. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +59 -46
  365. package/packages/apra-fleet-se/apra-pm/agents/doer.md +157 -134
  366. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +31 -32
  367. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +92 -113
  368. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +40 -42
  369. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +139 -63
  370. package/packages/apra-fleet-se/apra-pm/agents/planner.md +176 -100
  371. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +77 -81
  372. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +69 -85
  373. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
  374. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  375. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  376. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -2
  377. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -4
  378. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -3
  379. package/packages/apra-fleet-se/bin/cli.mjs +280 -3
  380. package/packages/apra-fleet-se/bin/serve.mjs +114 -5
  381. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  382. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  383. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  384. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  385. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  386. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  387. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  388. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  389. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +199 -34
  390. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  391. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  392. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  393. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  394. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  395. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
  396. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +285 -4
  397. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +3 -3
  398. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  399. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
  400. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  401. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  402. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
  403. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1054 -39
  404. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +308 -0
  405. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  406. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  407. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  408. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  409. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  410. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  411. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  412. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  413. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  414. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  415. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  416. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  417. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  418. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  419. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  420. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  421. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  422. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  423. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  424. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  425. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  426. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  427. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  428. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  429. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  430. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  431. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  432. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  433. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  434. package/packages/apra-fleet-se/fleet-sprint/runner.js +1672 -9072
  435. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  436. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +159 -0
  437. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  438. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  439. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  440. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +20 -1
  441. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  442. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  443. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  444. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  445. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  446. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  447. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  448. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +204 -19
  449. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +707 -12
  450. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  451. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  452. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +191 -43
  453. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +333 -6
  454. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +165 -0
  455. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +167 -37
  456. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  457. package/packages/apra-fleet-se/package.json +1 -1
  458. package/packages/apra-fleet-workflow/src/viewer/index.mjs +178 -1
  459. package/packages/apra-fleet-workflow/src/workflow/index.mjs +478 -32
  460. package/skills/fleet/SKILL.md +27 -16
  461. package/skills/fleet/auth-azdevops.md +57 -7
  462. package/skills/fleet/auth-bitbucket.md +5 -5
  463. package/skills/fleet/auth-github.md +7 -6
  464. package/skills/fleet/beads-conflict-resolution.md +141 -0
  465. package/skills/fleet/beads.md +16 -12
  466. package/skills/fleet/onboarding.md +6 -6
  467. package/skills/fleet/permissions.md +11 -7
  468. package/skills/fleet/profiles/node.json +1 -1
  469. package/skills/fleet/skill-matrix.md +1 -1
  470. package/skills/fleet/troubleshooting.md +4 -3
  471. package/version.json +1 -1
  472. package/dist/providers/gemini.d.ts +0 -52
  473. package/dist/providers/gemini.d.ts.map +0 -1
  474. package/dist/providers/gemini.js +0 -236
  475. package/dist/providers/gemini.js.map +0 -1
  476. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
package/README.md CHANGED
@@ -59,7 +59,7 @@ One control plane. Any device. Any model. Any workflow. Any domain.
59
59
  | Pillar | Concretely |
60
60
  |---|---|
61
61
  | **Any device** | Register any Windows / macOS / Linux machine (local or over SSH) as a fleet member in one command. Cloud members auto-start on demand. Windows members are fully supported for dispatch, command execution, and background long-running tasks (launched detached via WMI). |
62
- | **Any model** | Claude, Codex, Gemini, Copilot, Antigravity, local models (any OpenAI-compatible endpoint via OpenCode) -- mixed freely. Tier-based routing (cheap / standard / premium) keeps cost governance built in. Cross-provider review is a quality mechanism: a different model, with different blind spots, checks every change. |
62
+ | **Any model** | Claude, Codex, Copilot, Antigravity, local models (any OpenAI-compatible endpoint via OpenCode) -- mixed freely. Tier-based routing (cheap / standard / premium) keeps cost governance built in. Cross-provider review is a quality mechanism: a different model, with different blind spots, checks every change. |
63
63
  | **Any workflow** | Workflows are durable programs, not prompt chains: multi-hour, resumable, observable, with member reservations and atomic state. Write your own; ship it to the fleet. |
64
64
  | **Any domain** | Not just software development. The pattern fits wherever work decomposes into agent-sized pieces that need orchestration and an audit trail: nightly retail replenishment (reconcile inventory deltas, draft purchase orders for sign-off), logistics exception handling (triage a delayed shipment, re-book, notify), healthcare intake (summarize referrals, check completeness, route), back-office runs (invoice matching, compliance evidence collection). Software engineering is the vertical running today -- your domain is a workflow away. |
65
65
 
@@ -106,11 +106,13 @@ double-click it (installation is the default action):
106
106
 
107
107
  ```bash
108
108
  npm install -g @apralabs/apra-fleet
109
- apra-fleet # installs for Claude Code (default)
110
- apra-fleet --llm agy # or OpenCode/Codex/Copilot/Gemini
109
+ apra-fleet install # installs for Claude Code (default)
110
+ 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,10 +178,10 @@ 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
- - **Workflow engine**: runs workflow programs with phases, retries, turn budgets, resumable sessions, and per-activity persistent state.
182
- - **Supervisor**: always-on layer -- launch & stop sprints over HTTP, member reservation ledger, crash watchdog, run history.
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.
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.
183
185
 
184
186
  ## Knowledge Layer
185
187
 
@@ -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,11 +310,22 @@ 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
- god-mode. VCS access is provisioned and revocable per member. Permission
318
+ god-mode. VCS access is provisioned and revocable per member, across GitHub,
319
+ Bitbucket, and Azure DevOps -- host differences (URL shape, PR REST dialect,
320
+ auth pattern, error vocabulary) are hidden behind a per-provider descriptor
321
+ rather than leaking into shared code; see
322
+ `docs/design-azure-devops-vcs-auth.md` for the Azure DevOps provider's
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
301
329
  composition verifies its own delivery: a grant is read back off the target
302
330
  member and structurally compared against what was intended before it is
303
331
  reported as applied, so a failed or partial write is surfaced as an
@@ -418,18 +446,24 @@ third-party verticals.
418
446
  | Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
419
447
  | Keeping Fleet updated (`apra-fleet update`) | [docs/features/update.md](docs/features/update.md) |
420
448
  | Live member activity (`apra-fleet watch`, `logging.previewChars`) | [docs/features/watch.md](docs/features/watch.md) |
421
- | 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) |
422
450
  | Member category and tags | [docs/features/member-tags.md](docs/features/member-tags.md) |
423
451
  | Enabling SSH on a remote machine (if it does not have it yet) | [docs/ssh-setup.md](docs/ssh-setup.md) |
424
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) |
425
454
  | Cloud compute | [docs/cloud-compute.md](docs/cloud-compute.md) |
426
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) |
457
+ | Windows shell selection (probe order, gitbash/pwsh7/powershell5, shell vs os) | [docs/windows-shell-selection.md](docs/windows-shell-selection.md) |
458
+ | Cross-shell command construction for member-bound commands | [docs/cross-shell-command-construction.md](docs/cross-shell-command-construction.md) |
427
459
  | Knowledge Layer (setup, usage, provider swap) | [docs/knowledge-layer.md](docs/knowledge-layer.md) |
428
460
  | Code intelligence provider abstraction | [docs/code-intelligence-providers.md](docs/code-intelligence-providers.md) |
429
461
  | Hub-spoke cloud migration plan (historical; see tier-3 ownership ADR) | [docs/hub-spoke-master-plan.md](docs/hub-spoke-master-plan.md) |
430
462
  | Tier-3 ownership decision (fleet-dashboard vs `src/hub-service/`) | [docs/adr-tier3-ownership.md](docs/adr-tier3-ownership.md) |
431
463
  | Shared hub/dashboard API contract package | [packages/fleet-api-contract/README.md](packages/fleet-api-contract/README.md) |
432
- | Workflow engine internals (`agent()`/`parallel()`/`pipeline()`, journal, budget) | [packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md](packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md) |
464
+ | Workflow engine internals (`agent()`/`parallel()`/`pipeline()`, journal, budget, pause/resume) | [packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md](packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md) |
465
+ | Cooperative workflow pause/resume (engine, viewer, supervisor, fleet-sprint) | [docs/features/workflow-pause-resume.md](docs/features/workflow-pause-resume.md) |
466
+ | Supervisor dashboard live-refresh (`/state` + `/events` SSE, tab-activation refresh, in-memory scope expansion) | [docs/features/supervisor-dashboard-live-refresh.md](docs/features/supervisor-dashboard-live-refresh.md) |
433
467
  | Writing and running workflow scripts | [packages/apra-fleet-workflow/docs/workflow-guide.md](packages/apra-fleet-workflow/docs/workflow-guide.md) |
434
468
  | Authoring a SEA-embedded `apra-fleet workflow` (manifest, entry contract, launcher env vars) | [docs/authoring-workflows.md](docs/authoring-workflows.md) |
435
469
  | Workflow launcher fleet-server resolution order (HTTP singleton vs. stdio) | [docs/adr-workflow-server-resolution.md](docs/adr-workflow-server-resolution.md) |
@@ -439,10 +473,12 @@ third-party verticals.
439
473
  | Auto-sprint internals (cycle loop, stall detection, budget, topology) | [packages/apra-fleet-se/docs/architecture.md](packages/apra-fleet-se/docs/architecture.md) |
440
474
  | Auto-sprint agent role contracts | [packages/apra-fleet-se/docs/role-contracts.md](packages/apra-fleet-se/docs/role-contracts.md) |
441
475
  | fleet-supervisor skill (start/stop/restart/auto-start-on-boot, sprint launch via HTTP API) | [packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md](packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md) |
442
- | fleet-supervisor packaging self-containment audit | [packages/apra-fleet-se/docs/supervisor-selfcontainment-audit.md](packages/apra-fleet-se/docs/supervisor-selfcontainment-audit.md) |
443
476
  | MCP client SDK overview (transports, `ApraFleet` API) | [packages/apra-fleet-client/docs/overview.md](packages/apra-fleet-client/docs/overview.md) |
444
477
  | MCP client SDK API reference | [packages/apra-fleet-client/docs/api-reference.md](packages/apra-fleet-client/docs/api-reference.md) |
445
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) |
446
482
 
447
483
  ## Community
448
484
 
@@ -464,6 +500,11 @@ git clone https://github.com/Apra-Labs/apra-fleet && cd apra-fleet
464
500
  npm install && npm run build && npm test
465
501
  ```
466
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
+
467
508
  See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute.
468
509
 
469
510
  ## License
@@ -12,19 +12,28 @@ 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
19
- most for duplicate detection and sprint-set grouping: two beads that read as unrelated
20
- are often the same underlying issue, and the KB is where that has already been written
21
- down.
25
+ most for duplicate detection and sprint-set grouping.
22
26
  3. When grooming turns up a durable backlog fact -- two ids that are genuinely the same
23
27
  work, a dependency between beads that their text does not state, or a recurring reason
24
28
  items land unactionable -- call `mcp__apra-fleet__kb_capture` with type "knowledge".
25
29
  Do not capture per-sprint churn; capture what stays true.
26
30
 
31
+ <!-- if-tool: ToolSearch -->
27
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 -->
28
37
 
29
38
  ## Usage modes
30
39
 
@@ -94,24 +103,23 @@ The canonical machine-readable contract lives in the sibling file
94
103
 
95
104
  ## Beads semantics
96
105
 
97
- - `parent-child` = GROUPING. `blocks` = ORDERING. Never conflate them. One parent only.
106
+ Graph semantics (`parent-child` = grouping, `blocks` = ordering, epic rules, `bd epic
107
+ status` gotchas) are canonical in `_shared/GRAPH-SEMANTICS.md`, the sibling file
108
+ installed alongside this one -- read it; do not restate or improvise those rules here.
109
+ Semantics specific to this role:
110
+
98
111
  - `assignee` is set explicitly (`bd update <id> --assignee <identity>`) or via
99
112
  `bd update <id> --claim` (also flips status to `in_progress`). Fall back to `owner`
100
- (static, set once at creation) only when `assignee` is empty.
101
- - `issue_type` does NOT affect ready/dispatch eligibility. Only three things hide a bead
102
- from ready work: an unclosed child, an unmet `blocks` dependency, or status not
103
- `open`/`in_progress`.
104
- - `epic -> feature -> task` is a loose convention. The one hard rule: an epic may
105
- `blocks` only another epic -- bd does not enforce same-type pairs.
106
- - `bd epic status <id>` only rolls up correctly when `<id>` is actually typed `epic`;
107
- on a non-epic id it silently returns unrelated epics.
113
+ (static, set at creation) only when `assignee` is empty.
114
+ - Only three things hide a bead from ready work: an unclosed child, an unmet `blocks`
115
+ dependency, or status not `open`/`in_progress`. `issue_type` never does.
108
116
  - `gate` (`bd create --type=gate --await-type=<kind> --await-id=<id>`) blocks dependents
109
117
  until an external condition resolves. Documented await-types are GitHub-shaped; when
110
118
  recommending a gate, describe the pattern and let the operator pick an await-type
111
119
  matching their actual VCS/CI.
112
- - Title prefixes are convention, not schema, but widely matched on: `[test]` = verification
113
- work for a sibling/parent; `[impl]` = implementation; `[integ]` = filed by an
114
- integration/re-verification pass; `[regression][carry-over]` = rolled-over regression bug.
120
+ - Title prefixes are convention, not schema, but widely matched on: `[test]` =
121
+ verification work; `[impl]` = implementation; `[integ]` = filed by an integration
122
+ pass; `[regression][carry-over]` = rolled-over regression bug.
115
123
 
116
124
  ## Step 1 -- Load the backlog, scoped to identity
117
125
 
@@ -127,9 +135,8 @@ Fall back to non-`--json`/non-`--assignee` forms if unsupported, then filter cli
127
135
  visibly separate. `bd show <id> --json` before any judgment call -- never flag
128
136
  description quality from a summary line alone.
129
137
 
130
- If a `bd` JSON payload is too large to read directly, redirect it under a scratch dir
131
- instead of the repo root -- e.g. `.beads/tmp/<name>.json` (already covered by the
132
- existing `.beads/` gitignore entry) -- never write scratch JSON to the repo root.
138
+ If a `bd` JSON payload is too large to read directly, redirect it to a gitignored
139
+ scratch path (e.g. `.beads/tmp/<name>.json`) -- never to the repo root.
133
140
 
134
141
  ## Step 2 -- Structural deadlock scan (every time)
135
142
 
@@ -193,6 +200,20 @@ Cross `priority`/urgency-language against content quality for every in-scope bea
193
200
  - **Priority x age**: compare `created_at`/`updated_at` to now, always jointly with
194
201
  priority. Old+low = noise; old+high = an explicit "still worth pursuing or stale?" call.
195
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
+
196
217
  ## Step 7 -- Cohesive sprint-set proposal (1b)
197
218
 
198
219
  From the ready, verified, well-formed, non-duplicate subset only:
@@ -241,10 +262,10 @@ The canonical machine-readable contract for this output lives in the sibling fil
241
262
  ```json
242
263
  {
243
264
  "status": "OK",
244
- "identity": "akhil.kumar@gmail.com",
265
+ "identity": "dev@example.com",
245
266
  "notes": "12 ready, 2 sprint sets proposed, 1 duplicate merged, 3 needing grooming.",
246
267
  "ready": [
247
- { "id": "BD-14", "type": "task", "priority": "P1", "status": "open", "assignee": "akhil.kumar@gmail.com", "ageDays": 4, "size": "M", "rationale": "No blockers, clear AC, feeds the auth epic." }
268
+ { "id": "BD-14", "type": "task", "priority": "P1", "status": "open", "assignee": "dev@example.com", "ageDays": 4, "size": "M", "rationale": "No blockers, clear AC, feeds the auth epic." }
248
269
  ],
249
270
  "sprintSets": [
250
271
  { "label": "auth-hardening", "beadIds": ["BD-14", "BD-15"], "reason": "Shared parent BD-10, sequential blocks edge." }
@@ -263,7 +284,7 @@ The canonical machine-readable contract for this output lives in the sibling fil
263
284
  ],
264
285
  "notYours": [],
265
286
  "stale": [
266
- { "id": "BD-60", "type": "bug", "priority": "P1", "status": "open", "assignee": "akhil.kumar@gmail.com", "ageDays": 95, "size": "S", "rationale": "P1, 95 days untouched -- likely dropped, confirm before continuing to carry it." }
287
+ { "id": "BD-60", "type": "bug", "priority": "P1", "status": "open", "assignee": "dev@example.com", "ageDays": 95, "size": "S", "rationale": "P1, 95 days untouched -- likely dropped, confirm before continuing to carry it." }
267
288
  ],
268
289
  "structuralIssues": [
269
290
  { "kind": "deadlock", "description": "BD-70 blocks its own parent BD-71", "beadIds": ["BD-70", "BD-71"] }
@@ -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
 
@@ -48,6 +59,9 @@ gh run list --pr <prNumber> --limit 5 --json databaseId,status,conclusion,headSh
48
59
  (In PR-scoped mode, apply Step 2 to the runs for the PR's head commit instead of
49
60
  `expectedHeadSha`.)
50
61
 
62
+ If `gh` is unavailable or the repo's remote is not GitHub, do not guess at another CI
63
+ system: return `status: "not_configured"` with `notes` naming what was found.
64
+
51
65
  ## Step 2 -- Interpret the result
52
66
 
53
67
  **No runs returned**: CI has never been triggered on this branch.
@@ -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:
@@ -30,27 +49,19 @@ not improvise deploy steps that are not written down in the runbook.
30
49
 
31
50
  ## Step 0a -- Check permissions before running anything
32
51
 
33
- Read `deploy.md`. Look for a `## Permissions` section. If found, verify each
34
- listed command prefix is covered by the MERGED effective permission set --
35
- on Claude Code that means SOME entry in `permissions.allow` of EITHER
36
- `.claude/settings.json` (the team-committed, shared baseline) OR
37
- `.claude/settings.local.json` (the per-checkout, individual/gitignored file;
38
- this is the ONLY file the fleet's `compose_permissions` tool ever writes to
39
- for Claude Code members -- see `skills/fleet/permissions.md`). Claude Code
40
- merges `permissions.allow` from both files, so a grant in EITHER one counts
41
- as coverage; checking only `settings.json` misses every grant
42
- `compose_permissions` delivered. A broader prefix entry counts as coverage
43
- too -- e.g. `Bash(docker:*)` covers `docker compose`. Other providers keep
44
- the equivalent allowlist in their own native config file (see
45
- `src/providers/*.ts`).
46
-
47
- Run the merge MECHANICALLY, in one command, rather than reading each file
48
- separately and merging by eye -- two sequential `cat`s invite stopping at the
49
- first (often-empty) file and never getting to the second, which silently
50
- reports a real grant as missing (observed live, apra-fleet: `settings.json`
51
- legitimately carries no `permissions.allow` in this repo's convention -- every
52
- grant lives in `settings.local.json` -- so a by-eye read that stops at the
53
- first empty file always concludes "nothing is granted" even when it is):
52
+ Read `deploy.md`. If it has a `## Permissions` section, verify each listed
53
+ command prefix is covered by the MERGED effective permission set -- on
54
+ Claude Code, the union of `permissions.allow` from BOTH
55
+ `.claude/settings.json` (team-committed baseline) AND
56
+ `.claude/settings.local.json` (per-checkout, gitignored -- the only file the
57
+ fleet's `compose_permissions` tool writes to; see
58
+ `skills/fleet/permissions.md`). A grant in either file counts; a broader
59
+ prefix counts too (e.g. `Bash(docker:*)` covers `docker compose`). Other
60
+ providers keep the equivalent allowlist in their own native config file.
61
+
62
+ Compute the union MECHANICALLY, in one command -- reading the files
63
+ separately and merging by eye reliably misses grants when the first file is
64
+ empty:
54
65
 
55
66
  ```bash
56
67
  node -e '
@@ -67,33 +78,25 @@ console.log(JSON.stringify([...allow], null, 2));
67
78
  # use your provider's native config file(s) otherwise
68
79
  ```
69
80
 
70
- Check every required command prefix against this one merged list. If any
71
- required command prefix has no covering entry in it, STOP immediately and
72
- return `deployed: false` with notes listing every missing entry, e.g.:
73
-
74
- Missing permissions in the merged CLI permission settings (.claude/settings.json
75
- + .claude/settings.local.json on Claude Code -- neither file covers these):
76
- Bash(docker *)
77
- Bash(docker-compose *)
78
- Ask the orchestrator/operator to run compose_permissions with the missing
79
- grant(s), then re-trigger the sprint.
80
-
81
- Do NOT attempt to add the permissions yourself, by editing any file directly:
82
- - `.claude/settings.json` is the team-committed baseline -- changes there
83
- require the team/a PR, never a self-edit.
84
- - `.claude/settings.local.json` is the correct target for an individual/local
85
- grant, but it must be provisioned via the `compose_permissions` MCP tool
86
- (grant mode), NOT hand-edited either -- that tool is the provider-agnostic
87
- delivery mechanism (this repo supports non-Claude providers too: Gemini,
88
- AGY, OpenCode, Codex -- each has its own native config path via the same
89
- tool).
90
- The correct escalation when a required permission is missing from the merged
91
- effective set is: ask the orchestrator/operator to run `compose_permissions`
92
- with the missing grant. Do NOT proceed past Step 0a if any permissions are missing.
81
+ Check every required prefix against this one merged list. If any prefix has
82
+ no covering entry, STOP immediately and return `deployed: false`, listing
83
+ every missing entry in `notes` and asking the orchestrator/operator to run
84
+ `compose_permissions` with the missing grant(s), then re-trigger the sprint.
85
+ NEVER add permissions yourself: `.claude/settings.json` changes require a
86
+ team PR, and `.claude/settings.local.json` must be provisioned via the
87
+ `compose_permissions` MCP tool (the provider-agnostic delivery mechanism
88
+ across all supported providers), never hand-edited. Do NOT proceed past
89
+ Step 0a while any permission is missing.
93
90
 
94
91
  ## Step 0b -- Knowledge Bank (required -- do this BEFORE any deploy.md operation)
95
92
 
93
+ <!-- if-tool: ToolSearch -->
96
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 -->
97
100
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being deployed,
98
101
  and `hint_modules` naming the deploy targets in `deploy.md`. Trust CONFIRMED entries
99
102
  fully. Use INFERRED entries as hints, not facts.
@@ -101,17 +104,27 @@ with the missing grant. Do NOT proceed past Step 0a if any permissions are missi
101
104
  be wrong or incomplete, call `mcp__apra-fleet__kb_capture` with type "runbook" or
102
105
  "learning". A deploy gotcha you had to discover is exactly what the next deploy needs.
103
106
 
107
+ <!-- if-tool: ToolSearch -->
104
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 -->
105
113
 
106
114
  ## deploy.md operations
107
115
 
108
116
  When asked to deploy:
109
117
 
110
118
  1. Read `deploy.md` -- understand the Deploy, Smoke test, and CI sections
111
- 2. Execute every command in the `## Deploy` section in order
112
- 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
113
122
  - Exit 0 = healthy -> return `deployed: true`
114
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.
115
128
 
116
129
  If a command fails mid-deploy, stop immediately and return `deployed: false`
117
130
  with the failing command and its output in `notes`.