@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
@@ -0,0 +1,728 @@
1
+ // KB (Knowledge Bank) work for fleet-sprint: the URL-based repo scope
2
+ // selector, the per-dispatch relevance-ranked read (kb_query), the vetting
3
+ // and forwarding of a role's kb_captures/kb_promotions payload (kb_capture/
4
+ // kb_promote), the canonical-bible publish (kb_export), the once-per-sprint
5
+ // priming client (kb_session_prime/kb_import) and the prompt-construction
6
+ // helpers that hand a role's primed knowledge and promotion candidates to
7
+ // its dispatch prompt -- extracted move-only out of runner.js
8
+ // (apra-fleet-3swo.4.4 for the original KB work concern; apra-fleet-3swo.6.11
9
+ // for createKbPrimingClient, KB_SELF_INJECTING_ROLES, kbQueryTerms,
10
+ // kbKnowledgeBlock and kbPromotionBlock). runner.js re-exports every symbol
11
+ // it previously exported from this region, so existing importers of
12
+ // fleet-sprint/runner.js resolve unchanged.
13
+ //
14
+ // Every kb_* call here is BEST-EFFORT and NON-FATAL: a KB outage (cold KB,
15
+ // unreachable server, a rejected or throwing callTool) must only be logged,
16
+ // never fail a dispatch. Every call also spreads repo_path AND the scopeOf()
17
+ // URL-scope fields -- omitting either was a real defect (apra-fleet-23c
18
+ // zod-validation failures without repo_path/content, apra-fleet-tm7's
19
+ // repo-blindness without the URL scope) and both must keep flowing on every
20
+ // site this module owns.
21
+
22
+ import { ROLES, wrapUntrustedBlock } from './contracts.mjs';
23
+ import { toolErrorText } from './mcp-result.mjs';
24
+
25
+ // Local, validated role constant -- mirrors runner.js's own roleConst()
26
+ // pattern (kb.mjs does not import runner.js's private helper, to avoid a
27
+ // module import cycle) so a rename/typo in contracts.ROLES still throws
28
+ // here at module-load time instead of silently narrowing KB_PROMOTER_ROLES
29
+ // to nothing.
30
+ function kbRoleConst(name) {
31
+ if (!ROLES.includes(name)) {
32
+ throw new Error(`[Role Contract] '${name}' is not a member of contracts.ROLES: ${ROLES.join(', ')}`);
33
+ }
34
+ return name;
35
+ }
36
+ const ROLE_REVIEWER = kbRoleConst('reviewer');
37
+ // Same mirrored-local pattern as ROLE_REVIEWER above, needed by
38
+ // KB_SELF_INJECTING_ROLES below (moved verbatim from runner.js, which still
39
+ // keeps its own module-private ROLE_DOER for its other call sites).
40
+ const ROLE_DOER = kbRoleConst('doer');
41
+
42
+ /**
43
+ * Cap on primed entries carried into a dispatch prompt. kb_session_prime can
44
+ * return up to ~28 (10 direct FTS hits + 3 global + 5 graph-neighbour + 5
45
+ * project-bible + 5 global-bible); a dispatch prompt is not a place to spend
46
+ * that much budget on context the role may not need, and the entries are
47
+ * already returned in relevance order.
48
+ */
49
+ export const KB_MAX_KNOWLEDGE_ENTRIES = 12;
50
+
51
+ /**
52
+ * The URL-based KB scope selector, spread into a kb_* call's arguments.
53
+ *
54
+ * repo_path alone is only sufficient for a LOCAL member: resolveProjectSlug
55
+ * (src/services/knowledge/project-slug.ts) runs git in that directory to derive
56
+ * the project slug. A remote member's work folder is a path on another host, so
57
+ * both git probes fail and the slug degrades to 'default' -- collapsing every
58
+ * remote member's knowledge into one shared KB. repo_remote_url selects the DB
59
+ * directly (apra-fleet-b4g.1) and is what makes a sprint's kb_* calls land in
60
+ * the member's own project KB.
61
+ *
62
+ * Absent when no URL is known: an omitted scope is the honest pre-existing
63
+ * degradation, while a fabricated one routes writes into a slug that does not
64
+ * match the repo's real local-clone slug. The engine never derives a URL -- it
65
+ * forwards only what member_detail reports (knownRepoRemoteUrl's rule).
66
+ */
67
+ export function kbScope(remoteUrl) {
68
+ return (typeof remoteUrl === 'string' && remoteUrl.length > 0) ? { repo_remote_url: remoteUrl } : {};
69
+ }
70
+
71
+ /**
72
+ * KB trust pipeline Phase 2, execution half for this engine.
73
+ *
74
+ * The role output schemas are SHARED with apra-pm (contracts.mjs loads them from
75
+ * apra-pm/agents/schemas), so every role dispatched here is now asked for
76
+ * kb_captures, and the reviewer for kb_promotions. Without a consumer those
77
+ * fields would be silently dropped -- the knowledge would be gathered and
78
+ * thrown away. This is that consumer.
79
+ *
80
+ * Unlike apra-pm's auto-sprint.js -- a Claude Workflow script with no tool
81
+ * access, which must hand its vetted payload to an executor subagent -- this
82
+ * engine runs in-process with an injected callTool, so it makes the kb_capture
83
+ * and kb_promote calls DIRECTLY. Judgment still belongs to the role; execution
84
+ * belongs here.
85
+ *
86
+ * Validation mirrors lib/vet-kb-work.mjs in apra-pm and the provider invariants
87
+ * it reflects: a capture must cite at least one source file (SqliteProvider
88
+ * rejects an entry the freshness sweep can never stale), a promotion needs a
89
+ * recorded evidence string, and kb_promotions is refused from any role other
90
+ * than reviewer -- widening capture to four roles must not widen promotion.
91
+ *
92
+ * @param {{ callTool?: (name: string, args: object) => Promise<any>, log?: Function }} opts
93
+ * @returns {{ apply: (role: string, repoPath: string, result: any) => Promise<{captured: number, promoted: number, refused: number}> }}
94
+ */
95
+ export const KB_PROMOTER_ROLES = Object.freeze(new Set([ROLE_REVIEWER]));
96
+ export const KB_MIN_PROMOTE_REASON = 20;
97
+ export const KB_CAPTURE_TYPES = Object.freeze(['knowledge', 'learning', 'runbook']);
98
+
99
+ /**
100
+ * True when an MCP tool result represents a tool-level failure. The MCP client
101
+ * resolves such results instead of throwing (apra-fleet-23c), so callers that
102
+ * only catch exceptions silently treat failures as successes.
103
+ */
104
+ function isToolError(res) {
105
+ return !!(res && typeof res === 'object' && res.isError === true);
106
+ }
107
+
108
+ export function vetKbWork(role, result) {
109
+ const captures = [];
110
+ const promotions = [];
111
+ const refused = [];
112
+
113
+ const rawCaptures = (result && Array.isArray(result.kb_captures)) ? result.kb_captures : [];
114
+ for (const c of rawCaptures) {
115
+ if (!c || typeof c.title !== 'string' || typeof c.summary !== 'string') {
116
+ refused.push(`${role}: capture missing title/summary`);
117
+ continue;
118
+ }
119
+ if (!Array.isArray(c.source_files) || c.source_files.length === 0) {
120
+ refused.push(`${role}: capture "${c.title}" cites no source files`);
121
+ continue;
122
+ }
123
+ if (!KB_CAPTURE_TYPES.includes(c.type)) {
124
+ refused.push(`${role}: capture "${c.title}" has unsupported type ${String(c.type)}`);
125
+ continue;
126
+ }
127
+ // apra-fleet-23c: kbCaptureSchema requires content (z.string().min(1)).
128
+ // Omitting it here meant every kb_capture the engine sent failed zod
129
+ // validation at the MCP boundary and persisted nothing.
130
+ if (typeof c.content !== 'string' || c.content.trim().length === 0) {
131
+ refused.push(`${role}: capture "${c.title}" has no content`);
132
+ continue;
133
+ }
134
+ captures.push({
135
+ type: c.type,
136
+ title: c.title,
137
+ summary: c.summary,
138
+ content: c.content,
139
+ source_files: c.source_files,
140
+ symbols: Array.isArray(c.symbols) ? c.symbols : [],
141
+ });
142
+ }
143
+
144
+ const rawPromotions = (result && Array.isArray(result.kb_promotions)) ? result.kb_promotions : [];
145
+ if (rawPromotions.length > 0 && !KB_PROMOTER_ROLES.has(role)) {
146
+ refused.push(`${role}: kb_promotions refused -- promotion is reviewer-only`);
147
+ } else {
148
+ for (const p of rawPromotions) {
149
+ if (!p || typeof p.id !== 'string' || p.id.length === 0) {
150
+ refused.push(`${role}: promotion missing id`);
151
+ continue;
152
+ }
153
+ if (typeof p.reason !== 'string' || p.reason.trim().length < KB_MIN_PROMOTE_REASON) {
154
+ refused.push(`${role}: promotion ${p.id} has no recorded evidence`);
155
+ continue;
156
+ }
157
+ promotions.push({ id: p.id, reason: p.reason.trim() });
158
+ }
159
+ }
160
+
161
+ return { captures, promotions, refused };
162
+ }
163
+
164
+ /** Max promotion candidates offered to one reviewer, so the prompt stays bounded. */
165
+ export const KB_MAX_PROMOTION_CANDIDATES = 40;
166
+
167
+ export function createKbWorkClient(opts = {}) {
168
+ const { callTool, log = () => {}, remoteUrlFor } = opts;
169
+ const active = typeof callTool === 'function';
170
+
171
+ /**
172
+ * The URL-based KB scope for a repo path, resolved through the injected
173
+ * lookup (createKbPrimingClient's remoteUrlForPath). Deliberately NOT an
174
+ * extra parameter on the methods below: they are called from nine places
175
+ * across runSprintCycle/finalReview/harvest, and an omitted argument is
176
+ * indistinguishable from "no URL known" -- it would silently reinstate the
177
+ * repo-blindness this exists to fix. With no lookup injected (every
178
+ * construction site predating this, and direct unit calls) the scope is
179
+ * absent and behaviour is exactly as before.
180
+ */
181
+ function scopeOf(repoPath) {
182
+ return kbScope(typeof remoteUrlFor === 'function' ? remoteUrlFor(repoPath) : null);
183
+ }
184
+
185
+ /** Best-effort JSON out of an MCP result (string, content-block, or plain object). */
186
+ function parseResult(result) {
187
+ if (typeof result === 'string') { try { return JSON.parse(result); } catch { return null; } }
188
+ if (result && Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string') {
189
+ try { return JSON.parse(result.content[0].text); } catch { return null; }
190
+ }
191
+ return (result && typeof result === 'object') ? result : null;
192
+ }
193
+
194
+ return {
195
+ /**
196
+ * apra-fleet-0ef: the INFERRED entries this reviewer may promote.
197
+ *
198
+ * The engine's contract is "judgment belongs to the role, execution
199
+ * belongs here" -- the reviewer returns `kb_promotions:[{id, reason}]`
200
+ * and `apply()` calls kb_promote. But an entry id exists only inside
201
+ * the KB, and the reviewer subagent has no apra-fleet MCP tools to
202
+ * look one up, so it could never name an id: `kb_promotions` was
203
+ * structurally always empty and nothing was ever promoted. (kb_captures
204
+ * worked only because a capture needs no pre-existing id.) This is the
205
+ * missing input: the engine reads the candidates and hands them to the
206
+ * reviewer in its prompt.
207
+ *
208
+ * Best-effort by design -- a cold or unreachable KB must degrade to
209
+ * "nothing to promote", never fail the review dispatch.
210
+ */
211
+ async promotionCandidates(repoPath) {
212
+ // Without a repo path kb_list would resolve against the fleet
213
+ // server's cwd and offer entries from an unrelated project's KB
214
+ // (the apra-fleet-tm7 repo-blindness class). Refuse rather than guess.
215
+ if (!active || !repoPath) return [];
216
+ try {
217
+ const parsed = parseResult(await callTool('kb_list', {
218
+ repo_path: repoPath,
219
+ ...scopeOf(repoPath),
220
+ confidence: 'INFERRED',
221
+ limit: KB_MAX_PROMOTION_CANDIDATES,
222
+ }));
223
+ const results = parsed && Array.isArray(parsed.results) ? parsed.results : [];
224
+ return results
225
+ // promote() refuses type='user-directive' outright (activation
226
+ // is human-terminal, CLI-only), so offering one as a candidate
227
+ // can only produce a guaranteed refusal.
228
+ .filter((e) => e && typeof e.id === 'string' && e.type !== 'user-directive')
229
+ .slice(0, KB_MAX_PROMOTION_CANDIDATES);
230
+ } catch (err) {
231
+ log(`[kb-work] could not list promotion candidates for ${repoPath} (non-fatal): ${err.message}`);
232
+ return [];
233
+ }
234
+ },
235
+ /**
236
+ * KB audit follow-up: the per-dispatch, relevance-ranked read.
237
+ *
238
+ * primeAll() runs ONCE per member at sprint start with no hints, so
239
+ * every role received the same handful of entries no matter what it was
240
+ * about to work on -- and kb_query went unused by this engine entirely.
241
+ * This asks the KB what it knows about THIS dispatch, using the terms
242
+ * the engine already holds (bead ids and their titles).
243
+ *
244
+ * `expand_related` is what finally reads the KB's own graph. The KB has
245
+ * been writing `refines` and `contradiction_of` edges since AUDN
246
+ * shipped and traversing none of them: 554 edges, 0 reads. A role about
247
+ * to act on an entry is precisely who needs to know that entry has a
248
+ * newer framing or a standing dispute -- especially since confidence
249
+ * tier does NOT track correctness across a contradiction chain (the
250
+ * warehouse chain-A shape, where the incorrect entry outranks both of
251
+ * its corrections).
252
+ *
253
+ * Best-effort, like every other KB read here: no repo path, no terms, a
254
+ * cold KB or an unreachable one all degrade to "no knowledge", never to
255
+ * a failed dispatch.
256
+ */
257
+ async relevantKnowledge(repoPath, terms) {
258
+ if (!active || !repoPath || !Array.isArray(terms) || terms.length === 0) return [];
259
+ const query = terms.filter((t) => typeof t === 'string' && t.trim()).join(' ');
260
+ if (!query) return [];
261
+ try {
262
+ const res = await callTool('kb_query', {
263
+ repo_path: repoPath,
264
+ ...scopeOf(repoPath),
265
+ query,
266
+ limit: KB_MAX_KNOWLEDGE_ENTRIES,
267
+ expand_related: true,
268
+ });
269
+ // apra-fleet-23c: an MCP callTool RESOLVES with {isError:true}
270
+ // for a tool-level failure rather than throwing, so this was
271
+ // the one kb_* failure path in this module that stayed
272
+ // silent -- parseResult() returns null for that envelope,
273
+ // taking the `if (!parsed) return [];` branch below and never
274
+ // reaching the catch. Detect it explicitly so a cold or
275
+ // misconfigured KB degrades visibly, like every other kb_*
276
+ // call here.
277
+ if (isToolError(res)) {
278
+ log(`[kb-work] kb_query rejected for ${repoPath} (non-fatal): ${toolErrorText(res)}`);
279
+ return [];
280
+ }
281
+ const parsed = parseResult(res);
282
+ if (!parsed) return [];
283
+ const hits = Array.isArray(parsed.l1_results) ? parsed.l1_results : [];
284
+ const related = Array.isArray(parsed.related_claims) ? parsed.related_claims : [];
285
+ const seen = new Set();
286
+ const out = [];
287
+ for (const e of hits) {
288
+ if (!e || typeof e.id !== 'string' || seen.has(e.id)) continue;
289
+ seen.add(e.id);
290
+ out.push(e);
291
+ }
292
+ // Related claims sit BELOW every direct hit and carry a marker,
293
+ // so a role can tell "the KB matched this" from "the KB says
294
+ // something about what it matched".
295
+ for (const e of related) {
296
+ if (!e || typeof e.id !== 'string' || seen.has(e.id)) continue;
297
+ seen.add(e.id);
298
+ out.push({ ...e, via: 'kb-graph' });
299
+ }
300
+ return out.slice(0, KB_MAX_KNOWLEDGE_ENTRIES);
301
+ } catch (err) {
302
+ log(`[kb-work] kb_query failed for ${repoPath} (non-fatal): ${err.message}`);
303
+ return [];
304
+ }
305
+ },
306
+ async apply(role, repoPath, result) {
307
+ const { captures, promotions, refused } = vetKbWork(role, result);
308
+
309
+ for (const r of refused) log(`[kb-work] refused -- ${r}`);
310
+ // Log every promotion with its stated evidence BEFORE attempting it.
311
+ // This log is the audit trail the bible never had.
312
+ for (const p of promotions) log(`[kb-work] promote ${p.id} (${role}): ${p.reason}`);
313
+
314
+ // Without a repo path a capture would land in whichever KB the fleet
315
+ // server's cwd resolves to -- the tm7 defect. Refuse rather than guess.
316
+ if (!active || !repoPath) {
317
+ if ((captures.length || promotions.length) && !repoPath) {
318
+ log(`[kb-work] no repo path for ${role} -- ${captures.length} capture(s) and ${promotions.length} promotion(s) dropped`);
319
+ }
320
+ return { captured: 0, promoted: 0, refused: refused.length };
321
+ }
322
+
323
+ let captured = 0;
324
+ let promoted = 0;
325
+ for (const c of captures) {
326
+ try {
327
+ const res = await callTool('kb_capture', { ...c, repo_path: repoPath, ...scopeOf(repoPath) });
328
+ // apra-fleet-23c: an MCP client RESOLVES with {isError:true} on a
329
+ // tool-level failure rather than throwing, so counting every
330
+ // non-throwing call as a success reported captures that never
331
+ // persisted ("captured 3" against a KB that stayed empty).
332
+ if (isToolError(res)) {
333
+ log(`[kb-work] kb_capture rejected for "${c.title}" (non-fatal): ${toolErrorText(res)}`);
334
+ continue;
335
+ }
336
+ captured++;
337
+ } catch (err) {
338
+ log(`[kb-work] kb_capture failed for "${c.title}" (non-fatal): ${err.message}`);
339
+ }
340
+ }
341
+ for (const p of promotions) {
342
+ try {
343
+ // apra-fleet-0ef: repo_path is REQUIRED here, exactly as on
344
+ // the kb_capture call above. Omitting it resolved the
345
+ // promotion against the fleet server's cwd -- a different
346
+ // project's KB, where the id does not exist -- so every
347
+ // promotion would have failed "Entry not found" (the
348
+ // apra-fleet-tm7 repo-blindness class, fixed for capture
349
+ // but missed here).
350
+ const res = await callTool('kb_promote', { id: p.id, reason: p.reason, repo_path: repoPath, ...scopeOf(repoPath) });
351
+ if (isToolError(res)) {
352
+ log(`[kb-work] kb_promote rejected for ${p.id} (non-fatal): ${toolErrorText(res)}`);
353
+ continue;
354
+ }
355
+ promoted++;
356
+ } catch (err) {
357
+ log(`[kb-work] kb_promote failed for ${p.id} (non-fatal): ${err.message}`);
358
+ }
359
+ }
360
+ if (captured || promoted) log(`[kb-work] ${role}: captured ${captured}, promoted ${promoted}`);
361
+ return { captured, promoted, refused: refused.length };
362
+ },
363
+
364
+ /**
365
+ * KB audit 2026-08-11: publish this repo's CONFIRMED set to its
366
+ * canonical bible (<repo>/.fleet/kb-canonical.json).
367
+ *
368
+ * Nothing in the pipeline had ever called kb_export, so a bible existed
369
+ * only where an operator had run the tool by hand -- 1 of 17 repos on
370
+ * the audited machine. Promotion therefore ended at the local sqlite
371
+ * store: a teammate, a fresh clone, or a member on another host saw
372
+ * none of it, and kb_session_prime's cold-seed (which reads exactly
373
+ * this file) had nothing to fall back on. Promotion is the sprint's
374
+ * work; publishing it is the step that makes the work leave the
375
+ * machine.
376
+ *
377
+ * Called once, AFTER the final review's promotions have been applied,
378
+ * so the bible reflects everything this sprint confirmed. Best-effort
379
+ * like every other KB call here: a sprint must never fail over an
380
+ * export, and the tool itself is a no-op when the entry set is
381
+ * unchanged. Committing/pushing the file stays a separate, opt-in
382
+ * decision (kb_export's own autoCommit config) -- this does not widen
383
+ * the engine's git authority.
384
+ */
385
+ async exportBible(repoPath) {
386
+ // Same repo-blindness guard as every other call here: without a
387
+ // path kb_export would resolve against the fleet server's cwd and
388
+ // write an unrelated project's bible.
389
+ if (!active || !repoPath) return false;
390
+ try {
391
+ const res = await callTool('kb_export', { repo_path: repoPath, ...scopeOf(repoPath) });
392
+ if (isToolError(res)) {
393
+ log(`[kb-work] kb_export rejected for ${repoPath} (non-fatal): ${toolErrorText(res)}`);
394
+ return false;
395
+ }
396
+ log(`[kb-work] exported the canonical bible for ${repoPath}`);
397
+ return true;
398
+ } catch (err) {
399
+ log(`[kb-work] kb_export failed for ${repoPath} (non-fatal): ${err.message}`);
400
+ return false;
401
+ }
402
+ },
403
+ };
404
+ }
405
+
406
+ /**
407
+ * apra-fleet-e28 / KB trust pipeline Phase 2: KB priming for the fleet-sprint
408
+ * engine, which had none -- it lived only in the Claude workflow copy.
409
+ *
410
+ * `callTool` is injected exactly like `createMemberReservationClient`'s, so this
411
+ * stays transport-agnostic and unit-testable without a live fleet server.
412
+ *
413
+ * WHY PER MEMBER, NOT PER SPRINT: this engine has no repo path of its own. It
414
+ * coordinates members by name and branch; the repo lives on each member's side,
415
+ * possibly on a different host at a different path. `kb_session_prime` selects
416
+ * WHICH project KB is read from its `repo_path`, and omitting that argument
417
+ * falls back to the fleet server's own cwd -- collapsing every member's
418
+ * knowledge into whichever repo the server happens to sit in, which is exactly
419
+ * the apra-fleet-tm7 / apra-fleet-3zl repo-blindness defect. So the work folder
420
+ * is resolved per member via `member_detail` (which reports it as `folder`) and
421
+ * each member is primed against its own repo.
422
+ *
423
+ * Best-effort throughout, matching the reservation client's precedent: a member
424
+ * whose folder cannot be resolved, or whose prime call fails, is logged and
425
+ * skipped. A sprint must not fail because the KB is cold -- priming is an
426
+ * optimisation, and every role contract's Step 0 already degrades gracefully
427
+ * when the KB tools are unavailable.
428
+ *
429
+ * @param {{ callTool?: (name: string, args: object) => Promise<any>, members?: string[], log?: Function }} opts
430
+ * @returns {{ primeAll: () => Promise<{primed: number, skipped: number}> }}
431
+ */
432
+
433
+ export function createKbPrimingClient(opts = {}) {
434
+ const { callTool, members = [], log = () => {} } = opts;
435
+ const active = typeof callTool === 'function' && members.length > 0;
436
+
437
+ function parseResult(result) {
438
+ if (result && typeof result === 'string') { try { return JSON.parse(result); } catch { return null; } }
439
+ if (result && Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string') {
440
+ try { return JSON.parse(result.content[0].text); } catch { return null; }
441
+ }
442
+ return (result && typeof result === 'object') ? result : null;
443
+ }
444
+
445
+ async function scopeFor(member) {
446
+ // apra-fleet-n78: format:'json' is REQUIRED. member_detail defaults to
447
+ // 'compact', whose renderer emits no folder at all -- `folder` is set only
448
+ // on the json path (src/tools/member-detail.ts). Omitting it made this
449
+ // return null for every member, so the KB was never primed for anyone.
450
+ const detail = parseResult(await callTool('member_detail', { member_name: member, format: 'json' }));
451
+ // member_detail reports the work folder as `folder` and the repo origin
452
+ // URL as `repo_remote_url` (src/tools/member-detail.ts). The URL is
453
+ // reported only when the member's registration record proves it, so an
454
+ // absent one is normal and must stay absent rather than be derived here.
455
+ const folder = detail && (detail.folder || (detail.member && detail.member.folder));
456
+ const url = detail && (detail.repo_remote_url || (detail.member && detail.member.repo_remote_url));
457
+ return {
458
+ folder: (typeof folder === 'string' && folder.length > 0) ? folder : null,
459
+ remoteUrl: (typeof url === 'string' && url.length > 0) ? url : null,
460
+ };
461
+ }
462
+
463
+ // member -> work folder, populated by primeAll(). createKbWorkClient reads
464
+ // it so a capture lands in the repo the member actually worked in, rather
465
+ // than being resolved against the fleet server's cwd.
466
+ const folders = new Map();
467
+
468
+ // member -> the repo origin URL member_detail reported for it, when it
469
+ // reported one. This is what scopes a REMOTE member's kb_* calls to its own
470
+ // project KB instead of the shared 'default' one (see kbScope).
471
+ const remoteUrls = new Map();
472
+
473
+ // work folder -> that folder's origin URL, or CONFLICTING_URL when two
474
+ // members claim the same path string for DIFFERENT repos. The work client
475
+ // resolves its scope through this map rather than taking the URL as an
476
+ // extra argument at each of its nine call sites: threading the repo path is
477
+ // then the same act as threading the scope, so a site cannot forget one
478
+ // while remembering the other.
479
+ const urlByFolder = new Map();
480
+ const CONFLICTING_URL = Symbol('conflicting-remote-url');
481
+
482
+ // member -> the entries kb_session_prime returned for that member.
483
+ //
484
+ // KB audit 2026-08-11: primeAll() used to `await callTool(...)` and throw
485
+ // the result away, on the assumption that priming "warms" something the
486
+ // role's own Step 0 would later read. It does not: prime is a pure read,
487
+ // and the role CANNOT repeat it -- a member-dispatched subagent has the
488
+ // fleet MCP server disabled (src/providers/claude.ts
489
+ // composePermissionConfig), so every contract's Step 0 kb_session_prime is
490
+ // unreachable there. Nothing consumed the knowledge and nothing could, which
491
+ // is why six sprints retrieved zero entries. Retaining the result is what
492
+ // lets kbKnowledgeBlock() hand it to the role in its dispatch prompt --
493
+ // the same shape of fix that made kb_promotions reachable.
494
+ const knowledge = new Map();
495
+
496
+ return {
497
+ folderOf(member) {
498
+ return folders.get(member) || null;
499
+ },
500
+ remoteUrlOf(member) {
501
+ return remoteUrls.get(member) || null;
502
+ },
503
+ /**
504
+ * The URL scoping kb_* calls made against `repoPath`, or null.
505
+ *
506
+ * Null for an unknown path, for a local member (no URL was reported),
507
+ * and for a path two members claim with different URLs. Members on
508
+ * different hosts can share a work-folder path string while being
509
+ * clones of different repos; picking either URL there would route one
510
+ * member's captures into the other's KB, which is strictly worse than
511
+ * the 'default' degradation this scoping exists to remove. Refusing
512
+ * leaves that case exactly as it was before.
513
+ */
514
+ remoteUrlForPath(repoPath) {
515
+ if (typeof repoPath !== 'string' || repoPath.length === 0) return null;
516
+ const url = urlByFolder.get(repoPath);
517
+ return (typeof url === 'string') ? url : null;
518
+ },
519
+ knowledgeOf(member) {
520
+ return knowledge.get(member) || [];
521
+ },
522
+ async primeAll() {
523
+ if (!active) return { primed: 0, skipped: members.length };
524
+ let primed = 0;
525
+ let skipped = 0;
526
+ for (const member of members) {
527
+ try {
528
+ const { folder: repoPath, remoteUrl } = await scopeFor(member);
529
+ if (repoPath) folders.set(member, repoPath);
530
+ if (remoteUrl) remoteUrls.set(member, remoteUrl);
531
+ if (repoPath && remoteUrl) {
532
+ const known = urlByFolder.get(repoPath);
533
+ if (known !== undefined && known !== remoteUrl) {
534
+ urlByFolder.set(repoPath, CONFLICTING_URL);
535
+ log(`[kb-prime] work folder ${repoPath} is claimed by two different repos -- KB calls for it stay unscoped`);
536
+ } else {
537
+ urlByFolder.set(repoPath, remoteUrl);
538
+ }
539
+ }
540
+ if (!repoPath) {
541
+ // No folder means no repo to scope the KB to. Priming without
542
+ // one would read the fleet server's own KB, so skip instead.
543
+ log(`[kb-prime] no work folder for member '${member}' -- skipping (KB stays cold)`);
544
+ skipped++;
545
+ continue;
546
+ }
547
+ // Land the committed bible in the WARM KB before priming.
548
+ //
549
+ // Without this the bible is reachable only through
550
+ // kb_session_prime's cold-seed, which reads it as a FILE
551
+ // and caps at 5 entries -- apra-fleet's own bible holds 17,
552
+ // so a sprint could see at most 5 arbitrary ones and FTS
553
+ // could rank none of them, because they were never rows.
554
+ // Importing first is what gives the per-dispatch kb_query
555
+ // (see relevantKnowledge) anything to match against.
556
+ // Idempotent by id, and best-effort: a repo with no bible,
557
+ // or an import that rejects every entry, must not stop the
558
+ // prime it was meant to feed.
559
+ //
560
+ // skip_sweep IS LOAD-BEARING (audit 2026-08-12, caught by a
561
+ // live sprint). kb_import's post-import freshnessSweep
562
+ // re-judges the ENTIRE KB against this member's worktree. At
563
+ // sprint start that staled 16 of 17 CONFIRMED entries purely
564
+ // because the repo had moved on since capture, and the
565
+ // damage cascaded: retrieval fell to one matchable entry,
566
+ // kb_export attempted a 17 -> 9 bible truncation, and
567
+ // kb_list (stale=0) returned an EMPTY promotion candidate
568
+ // list -- reinstating apra-fleet-0ef, "kb_promote can never
569
+ // fire". This import exists to WARM the KB, never to audit
570
+ // it; prime()'s own bounded checkFreshness still guards each
571
+ // entry it actually returns.
572
+ try {
573
+ const imported = parseResult(await callTool('kb_import', { repo_path: repoPath, ...kbScope(remoteUrl), skip_sweep: true }));
574
+ if (imported && typeof imported.imported === 'number' && imported.imported > 0) {
575
+ log(`[kb-prime] imported ${imported.imported} bible entr(ies) into the warm KB for ${repoPath}`);
576
+ }
577
+ } catch (err) {
578
+ log(`[kb-prime] kb_import skipped for ${repoPath} (non-fatal): ${err.message}`);
579
+ }
580
+
581
+ const primeResult = parseResult(await callTool('kb_session_prime', { repo_path: repoPath, ...kbScope(remoteUrl) }));
582
+ const entries = (primeResult && Array.isArray(primeResult.top_entries))
583
+ ? primeResult.top_entries.filter((e) => e && typeof e.id === 'string')
584
+ : [];
585
+ if (entries.length > 0) knowledge.set(member, entries.slice(0, KB_MAX_KNOWLEDGE_ENTRIES));
586
+ primed++;
587
+ } catch (err) {
588
+ log(`[kb-prime] failed for member '${member}' (non-fatal): ${err.message}`);
589
+ skipped++;
590
+ }
591
+ }
592
+ if (primed > 0) log(`[kb-prime] primed ${primed} member repo(s)`);
593
+ return { primed, skipped };
594
+ },
595
+ };
596
+ }
597
+
598
+ /**
599
+ * apra-fleet-0ef / apra-fleet-nx7: the "KNOWLEDGE BANK -- promotion candidates"
600
+ * block, shared verbatim by the per-round reviewer prompt and the Final Review
601
+ * prompt.
602
+ *
603
+ * It lives in one function because the two prompts must state the SAME evidence
604
+ * bar. Duplicating the text invites them to drift, and a drifted bar is
605
+ * invisible: both sides would still "work", just to different standards, and the
606
+ * only symptom would be inconsistent CONFIRMED quality months later.
607
+ *
608
+ * Returns a single-element array (or an empty one) so callers can spread it into
609
+ * their prompt-section list.
610
+ *
611
+ * @param {object[]|undefined} kbCandidates
612
+ * @returns {string[]}
613
+ */
614
+ /**
615
+ * KB audit 2026-08-11: the "KNOWLEDGE BANK -- what this repo already knows"
616
+ * block, shared by the doer and reviewer dispatch prompts.
617
+ *
618
+ * WHY THIS EXISTS AT ALL. Every role contract's Step 0 tells the role to call
619
+ * kb_session_prime itself. On a fleet-member dispatch it cannot: the member's
620
+ * composed permission config disables the apra-fleet MCP server outright
621
+ * (src/providers/claude.ts composePermissionConfig), so the tool is not merely
622
+ * unlisted, it is unreachable. That is the same wall kb_promotions hit, and
623
+ * this is the same fix -- the engine performs the read and hands the result
624
+ * over as prompt content. Step 0 stays correct for the OTHER execution path
625
+ * (an apra-pm orchestrator session running these contracts as local subagents,
626
+ * where the MCP server is present), so both paths now get knowledge.
627
+ *
628
+ * The trust ladder is restated here rather than assumed: these entries are
629
+ * agent-authored claims from earlier sprints, and CONFIRMED means a reviewer
630
+ * verified the claim, not that it is currently true of this branch's tree.
631
+ *
632
+ * Returns a single-element array (or an empty one) so callers can spread it
633
+ * into their prompt-section list, matching kbPromotionBlock.
634
+ *
635
+ * @param {object[]|undefined} entries
636
+ * @returns {string[]}
637
+ */
638
+ /**
639
+ * Roles whose prompt BUILDER places the knowledge block itself, at a position
640
+ * that carries meaning. Everything else receives it from the agent() wrapper.
641
+ * Listing them here (rather than inside the wrapper) keeps the two halves of
642
+ * that split visible from the block's own definition -- a role added to one
643
+ * side and forgotten on the other either gets the block twice or never.
644
+ */
645
+ export const KB_SELF_INJECTING_ROLES = Object.freeze(new Set([ROLE_DOER, ROLE_REVIEWER]));
646
+
647
+ /**
648
+ * FTS terms for a dispatch's kb_query, drawn from what the engine already
649
+ * holds: the beads being worked and their ids.
650
+ *
651
+ * Bead TITLES are the useful half -- they are prose about the change ("stop
652
+ * collapsing unknown_zone into unbound_roi"), which is what matches an entry's
653
+ * title/summary/content. Ids are included because a bead id occasionally
654
+ * appears verbatim in a captured entry, and query() OR-joins its terms, so a
655
+ * term that matches nothing costs a little ranking noise rather than filtering
656
+ * the result to empty. Non-string and blank values are dropped so a partially
657
+ * populated bead cannot produce a malformed query.
658
+ *
659
+ * @param {Array<{id?: string, title?: string}>} beads
660
+ * @param {string[]} beadIds
661
+ * @returns {string[]}
662
+ */
663
+ export function kbQueryTerms(beads, beadIds) {
664
+ const terms = [];
665
+ for (const b of Array.isArray(beads) ? beads : []) {
666
+ if (b && typeof b.title === 'string' && b.title.trim()) terms.push(b.title.trim());
667
+ }
668
+ for (const id of Array.isArray(beadIds) ? beadIds : []) {
669
+ if (typeof id === 'string' && id.trim()) terms.push(id.trim());
670
+ }
671
+ return terms;
672
+ }
673
+
674
+ export function kbKnowledgeBlock(entries) {
675
+ if (!Array.isArray(entries) || entries.length === 0) return [];
676
+ return [
677
+ 'KNOWLEDGE BANK -- what this repo already knows. These entries were captured and '
678
+ + 'verified during earlier work on this repository, and are provided so you do not '
679
+ + 'rediscover them the hard way. Read them BEFORE you start.\n'
680
+ + 'CONFIRMED entries were independently verified by a reviewer: trust them. INFERRED '
681
+ + 'entries are unverified hints: treat them as leads to check, not as facts. An entry '
682
+ + 'describes the tree it was captured against, so if one contradicts what you actually '
683
+ + 'observe in the code right now, the code wins -- say so in your notes rather than '
684
+ + 'bending your work to fit the entry.\n'
685
+ + 'You do not need to call any kb_* tool to read these. If you discover something '
686
+ + 'non-obvious and durable while working, report it in the `kb_captures` field of your '
687
+ + 'structured output and the orchestrator will record it.\n'
688
+ + wrapUntrustedBlock('kb_session_prime --top_entries', JSON.stringify(
689
+ entries.map((e) => ({
690
+ confidence: e.confidence,
691
+ title: e.title,
692
+ summary: e.summary,
693
+ source_files: e.source_files,
694
+ })),
695
+ null,
696
+ 2
697
+ )),
698
+ ];
699
+ }
700
+
701
+ export function kbPromotionBlock(kbCandidates) {
702
+ if (!Array.isArray(kbCandidates) || kbCandidates.length === 0) return [];
703
+ return [
704
+ 'KNOWLEDGE BANK -- promotion candidates. These entries were captured during this '
705
+ + 'sprint and sit at INFERRED. You are the only role that can promote them to '
706
+ + 'CONFIRMED. Do NOT call any kb_* tool yourself: return your decisions in the '
707
+ + '`kb_promotions` field of your structured output as [{id, reason}] and the '
708
+ + 'orchestrator executes them.\n'
709
+ + 'Promote ONLY entries whose claim you independently verified during THIS review '
710
+ + '-- by reading the diff, running the tests, or checking the cited files yourself. '
711
+ + 'The `reason` must state that evidence (at least 20 characters, e.g. "verified '
712
+ + 'against server/transit.js:88 and the reopen test"). Evidence, not plausibility: '
713
+ + 'if an entry merely looks correct, leave it INFERRED -- that is a perfectly good '
714
+ + 'resting state, and a wrong CONFIRMED entry is worse than no entry. Never '
715
+ + 'blanket-promote, and never promote by module, tag or timestamp. Promoting '
716
+ + 'nothing is a valid outcome; return [] in that case.\n'
717
+ + wrapUntrustedBlock('kb_list --confidence INFERRED', JSON.stringify(
718
+ kbCandidates.map((e) => ({
719
+ id: e.id,
720
+ title: e.title,
721
+ summary: e.summary,
722
+ source_files: e.source_files,
723
+ })),
724
+ null,
725
+ 2
726
+ )),
727
+ ];
728
+ }