@apralabs/apra-fleet 0.4.0 → 0.4.1

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 (427) hide show
  1. package/README.md +145 -7
  2. package/dist/agents/backlog-groomer.md +17 -1
  3. package/dist/agents/ci-watcher.md +13 -1
  4. package/dist/agents/deployer.md +15 -3
  5. package/dist/agents/doer.md +35 -1
  6. package/dist/agents/harvester.md +22 -3
  7. package/dist/agents/integ-test-runner.md +18 -2
  8. package/dist/agents/kb-reconciler.md +216 -0
  9. package/dist/agents/plan-reviewer.md +14 -1
  10. package/dist/agents/planner.md +88 -5
  11. package/dist/agents/regression-test-runner.md +19 -1
  12. package/dist/agents/reviewer.md +104 -3
  13. package/dist/agents/schemas/doer-output.json +63 -3
  14. package/dist/agents/schemas/harvester-output.json +59 -2
  15. package/dist/agents/schemas/integ-test-runner-output.json +2 -2
  16. package/dist/agents/schemas/kb-reconciler-output.json +87 -0
  17. package/dist/agents/schemas/planner-output.json +65 -0
  18. package/dist/agents/schemas/reviewer-output.json +105 -8
  19. package/dist/cli/install.d.ts +1 -0
  20. package/dist/cli/install.d.ts.map +1 -1
  21. package/dist/cli/install.js +136 -5
  22. package/dist/cli/install.js.map +1 -1
  23. package/dist/cli/join.js +1 -1
  24. package/dist/cli/join.js.map +1 -1
  25. package/dist/cli/kb-commit.d.ts +12 -0
  26. package/dist/cli/kb-commit.d.ts.map +1 -0
  27. package/dist/cli/kb-commit.js +53 -0
  28. package/dist/cli/kb-commit.js.map +1 -0
  29. package/dist/cli/kb-directives.d.ts +17 -0
  30. package/dist/cli/kb-directives.d.ts.map +1 -0
  31. package/dist/cli/kb-directives.js +146 -0
  32. package/dist/cli/kb-directives.js.map +1 -0
  33. package/dist/cli/kb-import.d.ts +13 -0
  34. package/dist/cli/kb-import.d.ts.map +1 -0
  35. package/dist/cli/kb-import.js +56 -0
  36. package/dist/cli/kb-import.js.map +1 -0
  37. package/dist/cli/uninstall.d.ts.map +1 -1
  38. package/dist/cli/uninstall.js +11 -0
  39. package/dist/cli/uninstall.js.map +1 -1
  40. package/dist/cli/watch.d.ts +53 -4
  41. package/dist/cli/watch.d.ts.map +1 -1
  42. package/dist/cli/watch.js +118 -17
  43. package/dist/cli/watch.js.map +1 -1
  44. package/dist/commands/kb-server.d.ts +8 -0
  45. package/dist/commands/kb-server.d.ts.map +1 -0
  46. package/dist/commands/kb-server.js +221 -0
  47. package/dist/commands/kb-server.js.map +1 -0
  48. package/dist/index.js +77 -2
  49. package/dist/index.js.map +1 -1
  50. package/dist/os/linux.d.ts +1 -0
  51. package/dist/os/linux.d.ts.map +1 -1
  52. package/dist/os/linux.js +18 -1
  53. package/dist/os/linux.js.map +1 -1
  54. package/dist/os/os-commands.d.ts +5 -0
  55. package/dist/os/os-commands.d.ts.map +1 -1
  56. package/dist/os/windows.d.ts +35 -0
  57. package/dist/os/windows.d.ts.map +1 -1
  58. package/dist/os/windows.js +67 -31
  59. package/dist/os/windows.js.map +1 -1
  60. package/dist/providers/agy.d.ts +12 -1
  61. package/dist/providers/agy.d.ts.map +1 -1
  62. package/dist/providers/agy.js +134 -9
  63. package/dist/providers/agy.js.map +1 -1
  64. package/dist/providers/claude.d.ts +11 -1
  65. package/dist/providers/claude.d.ts.map +1 -1
  66. package/dist/providers/claude.js +47 -19
  67. package/dist/providers/claude.js.map +1 -1
  68. package/dist/providers/codex.d.ts +11 -1
  69. package/dist/providers/codex.d.ts.map +1 -1
  70. package/dist/providers/codex.js +29 -6
  71. package/dist/providers/codex.js.map +1 -1
  72. package/dist/providers/copilot.d.ts +11 -1
  73. package/dist/providers/copilot.d.ts.map +1 -1
  74. package/dist/providers/copilot.js +26 -6
  75. package/dist/providers/copilot.js.map +1 -1
  76. package/dist/providers/email/headers.d.ts +15 -0
  77. package/dist/providers/email/headers.d.ts.map +1 -0
  78. package/dist/providers/email/headers.js +42 -0
  79. package/dist/providers/email/headers.js.map +1 -0
  80. package/dist/providers/email/index.d.ts +18 -0
  81. package/dist/providers/email/index.d.ts.map +1 -0
  82. package/dist/providers/email/index.js +60 -0
  83. package/dist/providers/email/index.js.map +1 -0
  84. package/dist/providers/email/provider.d.ts +49 -0
  85. package/dist/providers/email/provider.d.ts.map +1 -0
  86. package/dist/providers/email/provider.js +2 -0
  87. package/dist/providers/email/provider.js.map +1 -0
  88. package/dist/providers/email/sendgrid.d.ts +12 -0
  89. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  90. package/dist/providers/email/sendgrid.js +67 -0
  91. package/dist/providers/email/sendgrid.js.map +1 -0
  92. package/dist/providers/email/smtp.d.ts +65 -0
  93. package/dist/providers/email/smtp.d.ts.map +1 -0
  94. package/dist/providers/email/smtp.js +373 -0
  95. package/dist/providers/email/smtp.js.map +1 -0
  96. package/dist/providers/gemini.d.ts +11 -1
  97. package/dist/providers/gemini.d.ts.map +1 -1
  98. package/dist/providers/gemini.js +38 -4
  99. package/dist/providers/gemini.js.map +1 -1
  100. package/dist/providers/none.d.ts +11 -1
  101. package/dist/providers/none.d.ts.map +1 -1
  102. package/dist/providers/none.js +21 -0
  103. package/dist/providers/none.js.map +1 -1
  104. package/dist/providers/opencode.d.ts +11 -1
  105. package/dist/providers/opencode.d.ts.map +1 -1
  106. package/dist/providers/opencode.js +55 -4
  107. package/dist/providers/opencode.js.map +1 -1
  108. package/dist/providers/provider.d.ts +77 -0
  109. package/dist/providers/provider.d.ts.map +1 -1
  110. package/dist/providers/provider.js +44 -0
  111. package/dist/providers/provider.js.map +1 -1
  112. package/dist/services/agent-provisioner.d.ts.map +1 -1
  113. package/dist/services/agent-provisioner.js +3 -6
  114. package/dist/services/agent-provisioner.js.map +1 -1
  115. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  116. package/dist/services/cloud/lifecycle.js +3 -0
  117. package/dist/services/cloud/lifecycle.js.map +1 -1
  118. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  119. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  120. package/dist/services/cloud/task-wrapper.js +157 -0
  121. package/dist/services/cloud/task-wrapper.js.map +1 -1
  122. package/dist/services/github-app.d.ts.map +1 -1
  123. package/dist/services/github-app.js +11 -2
  124. package/dist/services/github-app.js.map +1 -1
  125. package/dist/services/knowledge/audn.d.ts +37 -0
  126. package/dist/services/knowledge/audn.d.ts.map +1 -0
  127. package/dist/services/knowledge/audn.js +219 -0
  128. package/dist/services/knowledge/audn.js.map +1 -0
  129. package/dist/services/knowledge/file-hash.d.ts +11 -0
  130. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  131. package/dist/services/knowledge/file-hash.js +123 -0
  132. package/dist/services/knowledge/file-hash.js.map +1 -0
  133. package/dist/services/knowledge/http-provider.d.ts +46 -0
  134. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  135. package/dist/services/knowledge/http-provider.js +254 -0
  136. package/dist/services/knowledge/http-provider.js.map +1 -0
  137. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  138. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-providers.js +92 -0
  140. package/dist/services/knowledge/kb-providers.js.map +1 -0
  141. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  142. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  143. package/dist/services/knowledge/kb-scope-input.js +11 -0
  144. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  145. package/dist/services/knowledge/kb-service.d.ts +3 -0
  146. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  147. package/dist/services/knowledge/kb-service.js +2 -0
  148. package/dist/services/knowledge/kb-service.js.map +1 -0
  149. package/dist/services/knowledge/path-validation.d.ts +2 -0
  150. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  151. package/dist/services/knowledge/path-validation.js +13 -0
  152. package/dist/services/knowledge/path-validation.js.map +1 -0
  153. package/dist/services/knowledge/pre-init.d.ts +14 -0
  154. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  155. package/dist/services/knowledge/pre-init.js +147 -0
  156. package/dist/services/knowledge/pre-init.js.map +1 -0
  157. package/dist/services/knowledge/project-slug.d.ts +2 -0
  158. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  159. package/dist/services/knowledge/project-slug.js +49 -0
  160. package/dist/services/knowledge/project-slug.js.map +1 -0
  161. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  162. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  163. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  164. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  165. package/dist/services/knowledge/types.d.ts +163 -0
  166. package/dist/services/knowledge/types.d.ts.map +1 -0
  167. package/dist/services/knowledge/types.js +9 -0
  168. package/dist/services/knowledge/types.js.map +1 -0
  169. package/dist/services/member-home.d.ts +89 -0
  170. package/dist/services/member-home.d.ts.map +1 -0
  171. package/dist/services/member-home.js +256 -0
  172. package/dist/services/member-home.js.map +1 -0
  173. package/dist/services/member-remote-url.d.ts +34 -0
  174. package/dist/services/member-remote-url.d.ts.map +1 -0
  175. package/dist/services/member-remote-url.js +39 -0
  176. package/dist/services/member-remote-url.js.map +1 -0
  177. package/dist/services/orphan-recovery.d.ts +5 -2
  178. package/dist/services/orphan-recovery.d.ts.map +1 -1
  179. package/dist/services/orphan-recovery.js +19 -8
  180. package/dist/services/orphan-recovery.js.map +1 -1
  181. package/dist/services/preflight-check.d.ts +56 -0
  182. package/dist/services/preflight-check.d.ts.map +1 -0
  183. package/dist/services/preflight-check.js +277 -0
  184. package/dist/services/preflight-check.js.map +1 -0
  185. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  186. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  187. package/dist/services/stall/log-path-resolver.js +17 -40
  188. package/dist/services/stall/log-path-resolver.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +32 -0
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +149 -6
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts +34 -0
  194. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  195. package/dist/services/stall/stall-poller.js +134 -2
  196. package/dist/services/stall/stall-poller.js.map +1 -1
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +2 -2
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/tool-registry.d.ts.map +1 -1
  201. package/dist/services/tool-registry.js +87 -1
  202. package/dist/services/tool-registry.js.map +1 -1
  203. package/dist/services/vcs/github.d.ts.map +1 -1
  204. package/dist/services/vcs/github.js +32 -1
  205. package/dist/services/vcs/github.js.map +1 -1
  206. package/dist/services/version-check.d.ts +22 -0
  207. package/dist/services/version-check.d.ts.map +1 -0
  208. package/dist/services/version-check.js +103 -0
  209. package/dist/services/version-check.js.map +1 -0
  210. package/dist/skills/fleet-sprint-cli/SKILL.md +13 -2
  211. package/dist/skills/pm/beads.md +6 -0
  212. package/dist/skills/pm/fleet-addendum.md +6 -0
  213. package/dist/skills/pm/index.md +56 -0
  214. package/dist/skills/pm/kb-reconcile.md +132 -0
  215. package/dist/skills/pm/kb-review.md +109 -0
  216. package/dist/tools/check-status.d.ts +47 -0
  217. package/dist/tools/check-status.d.ts.map +1 -1
  218. package/dist/tools/check-status.js +242 -0
  219. package/dist/tools/check-status.js.map +1 -1
  220. package/dist/tools/child-id-allocator.d.ts +2 -2
  221. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  222. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  223. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  224. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  225. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  226. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  227. package/dist/tools/code-intelligence-freshness.js +26 -0
  228. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  229. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  230. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  231. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  232. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  233. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  234. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  235. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  236. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  237. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  238. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  239. package/dist/tools/code-intelligence-reindex.js +106 -0
  240. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  241. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  242. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  243. package/dist/tools/code-intelligence-telemetry.js +52 -0
  244. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  245. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  246. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  247. package/dist/tools/code-intelligence-tests.js +24 -0
  248. package/dist/tools/code-intelligence-tests.js.map +1 -0
  249. package/dist/tools/code-intelligence.d.ts +114 -0
  250. package/dist/tools/code-intelligence.d.ts.map +1 -0
  251. package/dist/tools/code-intelligence.js +124 -0
  252. package/dist/tools/code-intelligence.js.map +1 -0
  253. package/dist/tools/compose-permissions.d.ts +26 -0
  254. package/dist/tools/compose-permissions.d.ts.map +1 -1
  255. package/dist/tools/compose-permissions.js +244 -33
  256. package/dist/tools/compose-permissions.js.map +1 -1
  257. package/dist/tools/execute-command.d.ts +2 -0
  258. package/dist/tools/execute-command.d.ts.map +1 -1
  259. package/dist/tools/execute-command.js +86 -16
  260. package/dist/tools/execute-command.js.map +1 -1
  261. package/dist/tools/execute-prompt.d.ts +13 -1
  262. package/dist/tools/execute-prompt.d.ts.map +1 -1
  263. package/dist/tools/execute-prompt.js +257 -45
  264. package/dist/tools/execute-prompt.js.map +1 -1
  265. package/dist/tools/kb-capture.d.ts +53 -0
  266. package/dist/tools/kb-capture.d.ts.map +1 -0
  267. package/dist/tools/kb-capture.js +130 -0
  268. package/dist/tools/kb-capture.js.map +1 -0
  269. package/dist/tools/kb-context.d.ts +17 -0
  270. package/dist/tools/kb-context.d.ts.map +1 -0
  271. package/dist/tools/kb-context.js +29 -0
  272. package/dist/tools/kb-context.js.map +1 -0
  273. package/dist/tools/kb-export.d.ts +19 -0
  274. package/dist/tools/kb-export.d.ts.map +1 -0
  275. package/dist/tools/kb-export.js +344 -0
  276. package/dist/tools/kb-export.js.map +1 -0
  277. package/dist/tools/kb-feedback.d.ts +23 -0
  278. package/dist/tools/kb-feedback.d.ts.map +1 -0
  279. package/dist/tools/kb-feedback.js +43 -0
  280. package/dist/tools/kb-feedback.js.map +1 -0
  281. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  282. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  283. package/dist/tools/kb-freshness-sweep.js +29 -0
  284. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  285. package/dist/tools/kb-harvest.d.ts +20 -0
  286. package/dist/tools/kb-harvest.d.ts.map +1 -0
  287. package/dist/tools/kb-harvest.js +143 -0
  288. package/dist/tools/kb-harvest.js.map +1 -0
  289. package/dist/tools/kb-import.d.ts +44 -0
  290. package/dist/tools/kb-import.d.ts.map +1 -0
  291. package/dist/tools/kb-import.js +239 -0
  292. package/dist/tools/kb-import.js.map +1 -0
  293. package/dist/tools/kb-invalidate.d.ts +19 -0
  294. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  295. package/dist/tools/kb-invalidate.js +34 -0
  296. package/dist/tools/kb-invalidate.js.map +1 -0
  297. package/dist/tools/kb-list.d.ts +32 -0
  298. package/dist/tools/kb-list.d.ts.map +1 -0
  299. package/dist/tools/kb-list.js +43 -0
  300. package/dist/tools/kb-list.js.map +1 -0
  301. package/dist/tools/kb-promote.d.ts +20 -0
  302. package/dist/tools/kb-promote.d.ts.map +1 -0
  303. package/dist/tools/kb-promote.js +20 -0
  304. package/dist/tools/kb-promote.js.map +1 -0
  305. package/dist/tools/kb-query.d.ts +35 -0
  306. package/dist/tools/kb-query.d.ts.map +1 -0
  307. package/dist/tools/kb-query.js +111 -0
  308. package/dist/tools/kb-query.js.map +1 -0
  309. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  310. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  311. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  312. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  313. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  314. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  315. package/dist/tools/kb-resolve-contradiction.js +37 -0
  316. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  317. package/dist/tools/kb-session-prime.d.ts +26 -0
  318. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  319. package/dist/tools/kb-session-prime.js +392 -0
  320. package/dist/tools/kb-session-prime.js.map +1 -0
  321. package/dist/tools/kb-setup.d.ts +20 -0
  322. package/dist/tools/kb-setup.d.ts.map +1 -0
  323. package/dist/tools/kb-setup.js +49 -0
  324. package/dist/tools/kb-setup.js.map +1 -0
  325. package/dist/tools/kb-stats.d.ts +20 -0
  326. package/dist/tools/kb-stats.d.ts.map +1 -0
  327. package/dist/tools/kb-stats.js +115 -0
  328. package/dist/tools/kb-stats.js.map +1 -0
  329. package/dist/tools/member-detail.d.ts.map +1 -1
  330. package/dist/tools/member-detail.js +8 -0
  331. package/dist/tools/member-detail.js.map +1 -1
  332. package/dist/tools/monitor-task.d.ts.map +1 -1
  333. package/dist/tools/monitor-task.js +21 -3
  334. package/dist/tools/monitor-task.js.map +1 -1
  335. package/dist/tools/provision-auth.d.ts.map +1 -1
  336. package/dist/tools/provision-auth.js +10 -3
  337. package/dist/tools/provision-auth.js.map +1 -1
  338. package/dist/tools/register-member.d.ts +3 -0
  339. package/dist/tools/register-member.d.ts.map +1 -1
  340. package/dist/tools/register-member.js +30 -1
  341. package/dist/tools/register-member.js.map +1 -1
  342. package/dist/tools/remove-member.d.ts.map +1 -1
  343. package/dist/tools/remove-member.js +17 -3
  344. package/dist/tools/remove-member.js.map +1 -1
  345. package/dist/tools/report-status.d.ts.map +1 -1
  346. package/dist/tools/report-status.js +2 -1
  347. package/dist/tools/report-status.js.map +1 -1
  348. package/dist/tools/send-email.d.ts +69 -0
  349. package/dist/tools/send-email.d.ts.map +1 -0
  350. package/dist/tools/send-email.js +177 -0
  351. package/dist/tools/send-email.js.map +1 -0
  352. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  353. package/dist/tools/setup-ssh-key.js +2 -0
  354. package/dist/tools/setup-ssh-key.js.map +1 -1
  355. package/dist/tools/update-member.d.ts +3 -0
  356. package/dist/tools/update-member.d.ts.map +1 -1
  357. package/dist/tools/update-member.js +25 -1
  358. package/dist/tools/update-member.js.map +1 -1
  359. package/dist/types.d.ts +1 -0
  360. package/dist/types.d.ts.map +1 -1
  361. package/dist/utils/prompt-errors.js +1 -1
  362. package/dist/utils/prompt-errors.js.map +1 -1
  363. package/dist/utils/session-caller.d.ts +28 -0
  364. package/dist/utils/session-caller.d.ts.map +1 -0
  365. package/dist/utils/session-caller.js +24 -0
  366. package/dist/utils/session-caller.js.map +1 -0
  367. package/dist/utils/work-folder-validation.d.ts +39 -0
  368. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  369. package/dist/utils/work-folder-validation.js +60 -0
  370. package/dist/utils/work-folder-validation.js.map +1 -0
  371. package/dist/workflows/auto-sprint.js +546 -6
  372. package/package.json +7 -4
  373. package/packages/apra-fleet-client/src/client/api.mjs +118 -4
  374. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -1
  375. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +13 -1
  376. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +15 -3
  377. package/packages/apra-fleet-se/apra-pm/agents/doer.md +35 -1
  378. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +22 -3
  379. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +18 -2
  380. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +216 -0
  381. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +14 -1
  382. package/packages/apra-fleet-se/apra-pm/agents/planner.md +88 -5
  383. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +19 -1
  384. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +104 -3
  385. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
  386. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
  387. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +2 -2
  388. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  389. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  390. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
  391. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
  392. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -0
  393. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  394. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  395. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  396. package/packages/apra-fleet-se/bin/cli.mjs +7 -0
  397. package/packages/apra-fleet-se/bin/serve.mjs +14 -2
  398. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +31 -5
  399. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  400. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +23 -151
  401. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +256 -0
  402. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1482 -0
  403. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  404. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  405. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +972 -0
  406. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +167 -101
  407. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +50 -6
  408. package/packages/apra-fleet-se/fleet-sprint/runner.js +1416 -116
  409. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +13 -2
  410. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  411. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  412. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +30 -17
  413. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +62 -2
  414. package/packages/apra-fleet-se/package.json +1 -0
  415. package/packages/apra-fleet-workflow/src/viewer/index.mjs +127 -13
  416. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  417. package/packages/apra-fleet-workflow/src/workflow/index.mjs +8 -4
  418. package/skills/fleet/knowledge-agent.md +66 -0
  419. package/skills/fleet/permissions.md +28 -4
  420. package/skills/fleet/profiles/base-dev.json +10 -1
  421. package/skills/fleet/profiles/base-reviewer.json +8 -1
  422. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  423. package/version.json +1 -1
  424. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
  425. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
  426. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
  427. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@apralabs/apra-fleet",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "MCP server for orchestrating multiple agentic AI instances (Claude, Gemini, Codex, Copilot, AGY) across machines via SSH",
5
5
  "author": "Apra Labs",
6
6
  "homepage": "https://github.com/Apra-Labs/apra-fleet",
@@ -23,7 +23,7 @@
23
23
  "apra-fleet": "dist/index.js"
24
24
  },
25
25
  "engines": {
26
- "node": ">=22.0.0"
26
+ "node": ">=22.5.0"
27
27
  },
28
28
  "files": [
29
29
  "dist/",
@@ -47,7 +47,8 @@
47
47
  "access": "public"
48
48
  },
49
49
  "overrides": {
50
- "undici": "^7.29.0"
50
+ "undici": "^7.29.0",
51
+ "fast-uri": "4.1.2"
51
52
  },
52
53
  "scripts": {
53
54
  "build": "npm run build:contract && tsc",
@@ -61,7 +62,7 @@
61
62
  "start": "node dist/index.js",
62
63
  "dev": "tsc --watch",
63
64
  "pretest": "npm run build:contract",
64
- "test": "vitest run",
65
+ "test": "node scripts/run-all-tests.mjs",
65
66
  "test:watch": "vitest",
66
67
  "smoke": "tsc && node dist/smoke-test.js",
67
68
  "prepare": "node scripts/install-hooks.mjs",
@@ -89,6 +90,7 @@
89
90
  "@inquirer/password": "^5.0.11",
90
91
  "@modelcontextprotocol/sdk": "^1.27.0",
91
92
  "ajv": "^8.12.0",
93
+ "better-sqlite3": "^9.6.0",
92
94
  "pg": "^8.22.0",
93
95
  "smol-toml": "^1.6.1",
94
96
  "ssh2": "^1.17.0",
@@ -98,6 +100,7 @@
98
100
  },
99
101
  "devDependencies": {
100
102
  "@apralabs/fleet-api-contract": "^0.1.0",
103
+ "@types/better-sqlite3": "^7.6.13",
101
104
  "@types/node": "^22.0.0",
102
105
  "@types/pg": "^8.20.0",
103
106
  "@types/ssh2": "^1.15.0",
@@ -7,14 +7,29 @@
7
7
  * @property {string} [member_id] - UUID of the member
8
8
  * @property {string} [member_name] - Friendly name of the member
9
9
  * @property {string} [model] - Model tier ("cheap", "standard", "premium") or a specific model ID
10
- * @property {boolean} [resume] - Resume the previous session if one exists. Defaults to
10
+ * @property {boolean|string} [resume] - Resume the previous session if one exists. Defaults to
11
11
  * true at this client/transport layer when the field is omitted entirely. NOTE: the
12
12
  * FleetWorkflow.agent() workflow layer (packages/apra-fleet-workflow/src/workflow/index.mjs)
13
13
  * always sends this field explicitly, defaulting it to `false` for workflow-authored
14
14
  * prompts (see AgentOptions.resume there and apra-fleet-unw.3 / F10) -- so workflow
15
15
  * callers effectively opt out of this client-level default unless they ask for resume.
16
+ * @property {string} [session_id] - Optional explicit session ID to resume (shorthand alias for resume: "<sessionId>")
16
17
  * @property {Record<string, string>} [substitutions] - Optional map of token name to replacement value
17
18
  * @property {number} [timeout_s] - Inactivity timeout in seconds (default: 300)
19
+ * @property {number} [expected_context_tokens] - Optional estimate of how many
20
+ * tokens this dispatch will add to the target session's context. When set (or context_size is
21
+ * set), the server compares it against the session's remaining context-window headroom BEFORE
22
+ * invoking the LLM: too little headroom rejects the call with {reason:
23
+ * "insufficient_context_headroom", detail: {demand, headroom, window}} and no spawn; a fit that
24
+ * lands inside the safety margin still proceeds but attaches a structured contextWarning. Wins
25
+ * over context_size when both are set. Omitting both fields disables the check entirely --
26
+ * pre-existing behavior is unchanged. Matches src/tools/execute-prompt.ts's
27
+ * expected_context_tokens field exactly (number, optional).
28
+ * @property {'S'|'M'|'L'} [context_size] - Optional size-bucket shorthand for
29
+ * expected_context_tokens: S/M/L map to configured token estimates (fleet
30
+ * defaults, overridable via config.json's contextAdmission.sizeBucketTokens). Ignored when
31
+ * expected_context_tokens is also set. Matches src/tools/execute-prompt.ts's context_size field
32
+ * exactly (enum 'S'|'M'|'L', optional).
18
33
  * @property {number} [timeoutMs] - Client-side request timeout override (ms). Not sent to
19
34
  * the server; consumed locally by McpClient.request(). When omitted, a default is derived
20
35
  * from max_total_s/timeout_s (see deriveTimeoutMs in this file).
@@ -26,7 +41,12 @@
26
41
  /**
27
42
  * @typedef {Object} ExecuteCommandOptions
28
43
  * @property {string} command - The shell command to execute
29
- * @property {boolean} [long_running] - Run as background task
44
+ * @property {boolean} [long_running] - Run as background task. Supported on linux and windows
45
+ * members. Windows launches the task detached via `Invoke-CimMethod Win32_Process.Create`
46
+ * (WMI provider host / session 0), independent of the SSH session's job object, since a plain
47
+ * background launch dies with the SSH channel there. darwin gets an advisory warning (the
48
+ * wrapper script is designed for Linux) but is not blocked. Matches
49
+ * src/tools/execute-command.ts's long_running branch exactly.
30
50
  * @property {number} [max_retries] - Max crash retries (long_running only)
31
51
  * @property {string} [member_id] - UUID of the member
32
52
  * @property {string} [member_name] - Friendly name of the member
@@ -72,7 +92,7 @@
72
92
  /**
73
93
  * @typedef {Object} RegisterMemberOptions
74
94
  * @property {string} friendly_name - Human-friendly name for this member (required)
75
- * @property {string} work_folder - Working directory on the target machine (required)
95
+ * @property {string} work_folder - Working directory on the target machine (required). For remote members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected.
76
96
  * @property {"local" | "remote"} [member_type] - Member type (default: "remote")
77
97
  * @property {string} [host] - IP address or hostname of the remote machine
78
98
  * @property {string} [username] - SSH username
@@ -91,7 +111,7 @@
91
111
  * @property {string} [member_id] - UUID of the member
92
112
  * @property {string} [member_name] - Friendly name of the member
93
113
  * @property {string} [friendly_name] - New friendly name
94
- * @property {string} [work_folder] - New working directory
114
+ * @property {string} [work_folder] - New working directory. For non-local (remote/relay) members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected.
95
115
  * @property {string} [host] - New host
96
116
  * @property {string} [username] - New SSH username
97
117
  * @property {number} [port] - New SSH port
@@ -154,6 +174,12 @@
154
174
  * @property {string} [project_folder] - Local project folder containing the
155
175
  * permissions.json ledger. Omit to skip ledger merge.
156
176
  * @property {string[]} [grant] - Reactive mode: additional permissions to grant.
177
+ * Each entry is checked against the NEVER_AUTO_GRANT denylist, which is
178
+ * wildcard-matched (not exact-matched) against a normalized form of the
179
+ * request: sudo/su/doas, `bash -c`/`sh -c`/eval, env/printenv, nc/nmap,
180
+ * `chmod 777`, any catch-all such as `Bash(*)`, and any payload containing a
181
+ * shell-chaining metacharacter (| ; && backtick $() are rejected outright,
182
+ * for every caller.
157
183
  * @property {string} [grant_reason] - Reason for the grant (stored in ledger)
158
184
  */
159
185
 
@@ -163,6 +189,25 @@
163
189
  * @property {string} [member_name] - Friendly name of the member
164
190
  */
165
191
 
192
+ /**
193
+ * @typedef {Object} SendEmailOptions
194
+ * @property {"sendgrid" | "smtp"} [provider] - Email provider to use (default "sendgrid").
195
+ * Secrets are resolved server-side from the credential store ("sendgrid_api_key" / "smtp_password").
196
+ * @property {string} from - Sender email address (required)
197
+ * @property {string} [host] - SMTP server hostname (required for smtp provider)
198
+ * @property {number} [port] - SMTP server port (default 587, or 465 when secure is true)
199
+ * @property {string} [user] - SMTP username (required for smtp provider)
200
+ * @property {boolean} [secure] - Use implicit TLS, e.g. port 465 (default false).
201
+ * When false, STARTTLS is required; plaintext AUTH is refused.
202
+ * @property {string | string[]} to - Recipient email address, or list of addresses
203
+ * @property {string} subject - Email subject line
204
+ * @property {string} body - Plain-text email body
205
+ * @property {string} [html] - Optional HTML email body
206
+ * @property {string[]} [cc] - CC recipient addresses
207
+ * @property {string[]} [bcc] - BCC recipient addresses
208
+ * @property {{ filename: string, content: string, contentType?: string }[]} [attachments] - Optional file attachments (base64-encoded content)
209
+ */
210
+
166
211
 
167
212
  // Grace margin added on top of the payload's own timeout hint (timeout_s /
168
213
  // max_total_s) so the client doesn't race the server's own deadline -- the
@@ -204,6 +249,27 @@ export function deriveTimeoutMs(payload = {}) {
204
249
  return hintSeconds * 1000 + TIMEOUT_GRACE_MS;
205
250
  }
206
251
 
252
+ /**
253
+ * Extract the JSON payload from a raw MCP tool-call result.
254
+ *
255
+ * Every ApraFleet wrapper returns the raw callTool() result --
256
+ * `{ content: [{ type: 'text', text }, ...] }` -- NOT a JSON string, so
257
+ * `JSON.parse(result)` on it throws. Tool results can also carry
258
+ * display-only items (e.g. an `<apra-fleet-display>` onboarding block)
259
+ * AHEAD of the payload, so content[0] is not reliable either. This helper
260
+ * returns the first content item that parses as JSON.
261
+ *
262
+ * @param {{ content?: { text?: string }[] }} result - raw callTool() result
263
+ * @returns {any} the parsed JSON payload
264
+ * @throws {Error} when no content item contains valid JSON
265
+ */
266
+ export function parseToolJson(result) {
267
+ for (const item of result?.content ?? []) {
268
+ try { return JSON.parse(item.text); } catch { /* not the payload */ }
269
+ }
270
+ throw new Error('No JSON payload in tool result');
271
+ }
272
+
207
273
  export class ApraFleet {
208
274
  /**
209
275
  * @param {{ callTool: (name: string, args: Record<string, any>, opts?: { timeoutMs?: number, signal?: AbortSignal }) => Promise<any> }} mcpClient
@@ -342,6 +408,54 @@ export class ApraFleet {
342
408
  return this.mcpClient.callTool('setup_ssh_key', options);
343
409
  }
344
410
 
411
+ /**
412
+ * Send an email. Pass provider config inline (provider, from, and for
413
+ * SMTP: host, port, user, secure). Secrets resolve from the credential
414
+ * store (sendgrid_api_key / smtp_password).
415
+ * @param {SendEmailOptions} options
416
+ */
417
+ async sendEmail(options) {
418
+ return this.mcpClient.callTool('send_email', options);
419
+ }
420
+
421
+ /**
422
+ * Collect a secret from the user out-of-band and store it in the fleet
423
+ * credential store. The secret value never passes through the caller.
424
+ * @param {{ name: string, prompt: string, persist?: boolean,
425
+ * network_policy?: 'allow'|'confirm'|'deny', members?: string,
426
+ * ttl_seconds?: number }} options
427
+ */
428
+ async credentialStoreSet(options) {
429
+ return this.mcpClient.callTool('credential_store_set', options);
430
+ }
431
+
432
+ /**
433
+ * List stored credentials (names and metadata only -- no values).
434
+ * The result payload is a JSON array of { name, scope, ... } entries;
435
+ * extract it with parseToolJson().
436
+ */
437
+ async credentialStoreList() {
438
+ return this.mcpClient.callTool('credential_store_list', {});
439
+ }
440
+
441
+ /**
442
+ * Delete a named credential from the store.
443
+ * @param {{ name: string }} options
444
+ */
445
+ async credentialStoreDelete(options) {
446
+ return this.mcpClient.callTool('credential_store_delete', options);
447
+ }
448
+
449
+ /**
450
+ * Update metadata (members, TTL, network policy) on an existing
451
+ * credential without re-entering the secret.
452
+ * @param {{ name: string, members?: string, ttl_seconds?: number,
453
+ * network_policy?: 'allow'|'confirm'|'deny' }} options
454
+ */
455
+ async credentialStoreUpdate(options) {
456
+ return this.mcpClient.callTool('credential_store_update', options);
457
+ }
458
+
345
459
  /**
346
460
  * Fleet-server-hosted global dolt push mutex (apra-fleet-f34.2,
347
461
  * src/tools/dolt-push-mutex.ts). Serializes cross-sprint `bd dolt push`
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: backlog-groomer
3
3
  description: For one operator's assigned beads, finds what is ready/urgent to sprint next, proposes cohesive sprint sets from interdependencies, finds duplicates, and surfaces high-priority/urgent-sounding items whose content quality is too low to act on. Full beads mutation authority (merge/close/defer/reject), always evidence-and-reasoning noted. Never changes code.
4
- tools: [Read, Grep, Glob, Bash]
4
+ tools: [Read, Grep, Glob, Bash, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Backlog Groomer
@@ -10,6 +10,22 @@ You groom ONE operator's slice of the open beads backlog: what to pick up next,
10
10
  to sprint together, what's a duplicate, what needs fixing before it's actionable. You
11
11
  analyze AND mutate beads directly -- but you never touch code beyond reading it.
12
12
 
13
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any grooming decision)
14
+
15
+ 1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
16
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose backlog
17
+ you are grooming, and `hint_modules` naming the subsystems the assigned beads touch.
18
+ 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.
22
+ 3. When grooming turns up a durable backlog fact -- two ids that are genuinely the same
23
+ work, a dependency between beads that their text does not state, or a recurring reason
24
+ items land unactionable -- call `mcp__apra-fleet__kb_capture` with type "knowledge".
25
+ Do not capture per-sprint churn; capture what stays true.
26
+
27
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
28
+
13
29
  ## Usage modes
14
30
 
15
31
  - **"Define my sprint"** -> Responsibility 1: ready/urgent items + sprint-set groups.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ci-watcher
3
3
  description: Polls CI for the sprint HEAD SHA; returns green/red/not_configured/pending.
4
- tools: [Bash]
4
+ tools: [Bash, ToolSearch]
5
5
  ---
6
6
 
7
7
  # CI Status Check
@@ -22,6 +22,18 @@ Your dispatch prompt must supply ONE of the two scoping forms:
22
22
  `expectedHeadSha` missing), do not guess or check an arbitrary branch. Return
23
23
  `status: "pending"` with `notes` stating which input was missing.
24
24
 
25
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
26
+
27
+ 1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime"`
28
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose CI you
29
+ are checking, and `hint_modules` naming its CI workflow files. Trust CONFIRMED entries
30
+ fully. Use INFERRED entries as hints, not facts. Known-flaky tests and known CI failure
31
+ modes are the point here -- they change how you read a red run.
32
+ 3. Do NOT capture. You poll a status API; you verify no claim about this repository, so you
33
+ have no basis to write one down.
34
+
35
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
36
+
25
37
  ## Step 1 -- List recent CI runs
26
38
 
27
39
  Branch-scoped:
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: deployer
3
3
  description: Follows deploy.md to deploy the software onto the target environment and verify it with the smoke test.
4
- tools: [Read, Bash]
4
+ tools: [Read, Bash, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Deployment
@@ -28,7 +28,7 @@ playbook yourself. If `deploy.md` is entirely absent (not just missing a
28
28
  section), return `deployed: false` with `notes` naming the missing file -- do
29
29
  not improvise deploy steps that are not written down in the runbook.
30
30
 
31
- ## Step 0 -- Check permissions before running anything
31
+ ## Step 0a -- Check permissions before running anything
32
32
 
33
33
  Read `deploy.md`. Look for a `## Permissions` section. If found, verify each
34
34
  listed command prefix is covered by the MERGED effective permission set --
@@ -89,7 +89,19 @@ Do NOT attempt to add the permissions yourself, by editing any file directly:
89
89
  tool).
90
90
  The correct escalation when a required permission is missing from the merged
91
91
  effective set is: ask the orchestrator/operator to run `compose_permissions`
92
- with the missing grant. Do NOT proceed past Step 0 if any permissions are missing.
92
+ with the missing grant. Do NOT proceed past Step 0a if any permissions are missing.
93
+
94
+ ## Step 0b -- Knowledge Bank (required -- do this BEFORE any deploy.md operation)
95
+
96
+ 1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
97
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being deployed,
98
+ and `hint_modules` naming the deploy targets in `deploy.md`. Trust CONFIRMED entries
99
+ fully. Use INFERRED entries as hints, not facts.
100
+ 3. When a deploy step fails for a non-obvious reason, or a runbook instruction turns out to
101
+ be wrong or incomplete, call `mcp__apra-fleet__kb_capture` with type "runbook" or
102
+ "learning". A deploy gotcha you had to discover is exactly what the next deploy needs.
103
+
104
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
93
105
 
94
106
  ## deploy.md operations
95
107
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: doer
3
3
  description: Works assigned bead ids (task-type work, impl and test-dev), commits after each, stops at VERIFY checkpoint.
4
- tools: [Read, Edit, Write, Bash, Grep, Glob, Agent]
4
+ tools: [Read, Edit, Write, Bash, Grep, Glob, Agent, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Task Execution
@@ -58,6 +58,40 @@ persistent state in ways that abort the whole sprint. Instead leave the bead ope
58
58
  Closing such a bead is legitimate ONLY when your dispatch prompt explicitly names an
59
59
  already-collected evidence artifact for you to verify against.
60
60
 
61
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
62
+
63
+ 1. Run ToolSearch with query
64
+ `"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"`
65
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo you are
66
+ working in, and `hint_symbols`/`hint_modules` relevant to the files and symbols you are
67
+ about to touch. Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
68
+ 3. Retrieve first, then read source: before reading an unfamiliar file or function, run
69
+ `mcp__apra-fleet__kb_query({ query: "<name>" })` first. If it returns a CONFIRMED or
70
+ INFERRED entry, work from it and skip the full source read. Trust CONFIRMED fully; treat
71
+ INFERRED as a strong hint but verify against source when correctness matters (it may be
72
+ an unvalidated in-flight capture). Only fall back to a full source read if the KB is
73
+ cold (no entry), stale, or says "see source for details."
74
+ 4. When you discover something non-obvious and durable (a hidden constraint, a gotcha, an
75
+ invariant), decide whether it is capture-worthy: run `mcp__apra-fleet__kb_query` first to
76
+ check for a near-duplicate entry, and skip it if one already exists. If it is new, add it
77
+ to your structured output's `kb_captures` array (see `agents/schemas/doer-output.json` for
78
+ the exact shape -- `type`, `title`, `summary`, `content`, `source_files`, optional
79
+ `symbols`); the engine makes the actual `kb_capture` call and logs it with your evidence.
80
+ Do not call `mcp__apra-fleet__kb_capture` yourself unless your dispatch context has no
81
+ `kb_captures` output field to write to, in which case calling it directly is the fallback.
82
+ 5. If a KB entry you retrieved proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
83
+ with the entry id and what was wrong.
84
+ 6. You do not need to call `mcp__apra-fleet__kb_harvest` yourself -- the fleet auto-dispatches
85
+ it as a backstop after your session ends; it is not your job to invoke it.
86
+ 7. The `code_*` tools answer a different question from the KB: the KB tells you what was
87
+ learned about this code, the code index tells you what this code actually connects to.
88
+ Before editing a symbol, use `code_context`/`code_graph` for its callers and callees and
89
+ `code_impact` for the blast radius of the file you are changing -- prefer them over grep
90
+ for symbol lookups, call-chain tracing and impact analysis. If a call reports the repo is
91
+ not indexed, fall back to grep and move on; do not try to build an index yourself.
92
+
93
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
94
+
61
95
  ## Step 1 -- Work only your assigned bead ids
62
96
 
63
97
  Do NOT run bare `bd ready` to discover work -- it returns ready beads from the entire
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: harvester
3
3
  description: Extracts durable sprint knowledge into docs/, updates README/CHANGELOG (including pre-computed cost analysis block), defers low-priority issues, and returns OK.
4
- tools: [Read, Edit, Write, Bash, Grep, Glob]
4
+ tools: [Read, Edit, Write, Bash, Grep, Glob, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Sprint Harvest
@@ -31,6 +31,22 @@ pre-computed by the orchestrator in JavaScript and must be inserted byte-for-byt
31
31
  and return `status: "FAILED"` with `notes` naming exactly which input was missing. Same for
32
32
  a missing `base-branch`/`branch`: do not guess which branch to diff.
33
33
 
34
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
35
+
36
+ 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"`
37
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being harvested,
38
+ and `hint_symbols`/`hint_modules` relevant to the modules touched during the sprint.
39
+ Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
40
+ 3. When you extract durable knowledge during harvest -- anything non-obvious that future
41
+ sprints should know -- add it to the `kb_captures` array of your structured output (type
42
+ "knowledge" or "learning"; dedup against the KB with `kb_query` first). The engine makes
43
+ the actual `kb_capture` call from that field. Calling `mcp__apra-fleet__kb_capture`
44
+ directly is a fallback only, for dispatch contexts with no `kb_captures` output field.
45
+ 4. If a retrieved KB entry proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
46
+ with the entry id and what was wrong.
47
+
48
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
49
+
34
50
  ## Step 1 -- Write sprint analysis artifact (FIRST, before anything else)
35
51
 
36
52
  Your task context includes an `analysisArtifactFile` path and an `analysisText` block.
@@ -109,7 +125,7 @@ bd list --status=open --priority=4
109
125
  **Do NOT close these.** Leave every P3/P4 issue open and untouched -- a closed issue drops
110
126
  out of `bd list --status=open` and `bd ready`, which is exactly what would hide it from
111
127
  next sprint's planner. Deferred work stays visible by staying open at low priority under
112
- the sprint root (see `skills/pm/beads.md` "Backlog"); closing is only for issues that are actually
128
+ the sprint root; closing is only for issues that are actually
113
129
  resolved, stale, or superseded, and this step never makes that call. If a P3/P4 issue
114
130
  genuinely lacks enough detail to act on later without re-investigation, add that detail
115
131
  with `bd note <id> "..."` -- do not close it as a substitute for noting it.
@@ -142,10 +158,13 @@ placeholder):
142
158
  ```json
143
159
  {
144
160
  "status": "OK",
145
- "notes": "Wrote sprint analysis artifact, extracted durable docs, updated README/CHANGELOG, confirmed 2 P3 issues remain open as backlog, pushed branch."
161
+ "notes": "Wrote sprint analysis artifact, extracted durable docs, updated README/CHANGELOG, confirmed 2 P3 issues remain open as backlog, pushed branch.",
162
+ "kb_captures": []
146
163
  }
147
164
  ```
148
165
 
166
+ `kb_captures` is optional -- omit it or send `[]` when there is nothing to capture.
167
+
149
168
  **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
150
169
  authoritative -- respond with exactly that JSON and nothing else. It is expected to match
151
170
  this contract; if it differs, follow the dispatch prompt.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: integ-test-runner
3
3
  description: Runs integ-test-playbook.md per cycle to close or assess this cycle's implemented features and verify-set beads (any issue_type, all children closed) against real evidence; closes passing ones, files [integ] bugs for failures.
4
- tools: [Read, Bash, Grep, Glob]
4
+ tools: [Read, Bash, Grep, Glob, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Integration Test Execution
@@ -71,6 +71,19 @@ any more -- that is `regression-test-runner`'s job, via
71
71
  `regression-test-playbook.md`, once per sprint, and its result is separate
72
72
  from and does not gate yours.
73
73
 
74
+ ## Step 0c -- Knowledge Bank (required -- do this BEFORE working any feature)
75
+
76
+ 1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
77
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo under test, and
78
+ `hint_symbols`/`hint_modules` relevant to the features you were handed. Trust CONFIRMED
79
+ entries fully. Use INFERRED entries as hints, not facts. An entry recording that a test
80
+ is environment-sensitive changes how you read a single red run.
81
+ 3. When a test turns out to be flaky or environment-sensitive, or the sandbox needs a step
82
+ the playbook does not record, call `mcp__apra-fleet__kb_capture` with type "knowledge" or
83
+ "learning".
84
+
85
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
86
+
74
87
  ## Step 1 -- Work the features you were handed
75
88
 
76
89
  Your dispatch prompt hands you an **explicit list of feature ids** -- the open features in
@@ -94,7 +107,7 @@ a time.
94
107
  ### Scope discipline and turn economy (stay within budget)
95
108
 
96
109
  Your dispatch has a bounded turn budget, and historically this phase routinely
97
- exhausted it and burned 15-85 min in resume/repair (apra-fleet-63x). The budget is
110
+ exhausted it and burned 15-85 min in resume/repair. The budget is
98
111
  sized so a run that is making progress is bounded by wall-clock time, not by turn
99
112
  count -- exhausting the turn count means the run did too much work per feature or
100
113
  polled too fast. Keep the run within budget by holding scope tight:
@@ -225,6 +238,9 @@ Do NOT close the feature. Create a bug issue, parented under the sprint scope yo
225
238
  dispatch prompt named (grouping only -- see the graph-semantics section above; do NOT
226
239
  also `bd dep add` this bug to the feature or the scope root):
227
240
 
241
+ `--title` is plain text only -- letters, digits, space, and `. , : ; ! ? ( ) ' _ / [ ] -`.
242
+ No backticks, double quotes, `$`, or backslash; put formatted detail in `--description`.
243
+
228
244
  ```bash
229
245
  bd create \
230
246
  --title="[integ] <short description of failure>" \