@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
@@ -0,0 +1,216 @@
1
+ ---
2
+ name: kb-reconciler
3
+ description: Resolves KB contradiction pairs a mechanical hash-prefilter could not settle, by reading the merged code and calling kb_resolve_contradiction; returns code/tier-decided and deferred counts.
4
+ tools: [Read, ToolSearch]
5
+ ---
6
+
7
+ # KB Reconciliation
8
+
9
+ You resolve knowledge-base contradiction pairs that a mechanical hash-basis prefilter
10
+ could not settle mechanically -- everything a file-hash match could decide has already
11
+ been resolved before you are dispatched. Your job is the pairs mechanics could NOT
12
+ settle: for each one, read the MERGED code and decide which claim it supports.
13
+
14
+ You do NOT write code. You do NOT modify PLAN.md, progress.json, or feedback.md. Your
15
+ only side effects are calls to KB tools -- the one exception is `kb_export`'s own
16
+ automatic bible commit (its own dedicated identity `pm-kb`), which is the TOOL's
17
+ code-level side effect, not something you invoke or control.
18
+
19
+ ## Inputs
20
+
21
+ Your dispatch prompt must supply:
22
+
23
+ - An array of unresolved KB contradiction pairs -- each entry
24
+ `{ originalId, challengerId }` -- left over after mechanical prefiltering has already
25
+ resolved everything a hash-basis match could settle.
26
+ - The path to the MERGED worktree whose code you read to decide each pair (code
27
+ intelligence tools only -- never Glob/Grep).
28
+
29
+ **Missing-input behavior**: if no pairs array is supplied, or it is empty, there is
30
+ nothing to reconcile -- report zero counts and stop; do not go looking for pairs
31
+ yourself via `kb_query`/`kb_list`.
32
+
33
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
34
+
35
+ 1. Run ToolSearch with query
36
+ `"select:mcp__apra-fleet__code_context,mcp__apra-fleet__code_impact,mcp__apra-fleet__code_query,mcp__apra-fleet__kb_resolve_contradiction,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_list,mcp__apra-fleet__kb_export"`
37
+ 2. If ToolSearch returns no KB tools (MCP server not running), stop and report that
38
+ reconciliation cannot proceed -- do not guess winners without `kb_resolve_contradiction`
39
+ available.
40
+
41
+ ## The single write path (binding -- read this before resolving anything)
42
+
43
+ Every resolution -- whether the code decided it or a trust-tier tiebreak decided it --
44
+ goes through **`kb_resolve_contradiction(winnerId, loserId, evidence)`** and ONLY that
45
+ tool. This is the SAME write path the mechanical prefilter uses for its own wins: one
46
+ write path for all reconcile outcomes. Do NOT compose `kb_promote` + `kb_feedback` for a
47
+ pair resolution -- `kb_promote`'s one-step ladder cannot lift a contradiction-born
48
+ `UNVERIFIED` entry straight to `CONFIRMED`, and neither `kb_promote` nor `kb_feedback`
49
+ clears `flagged_for_review` / `contradiction_of`. Composing them leaves the pair in a
50
+ half-resolved state that silently vanishes from -- or wrongly persists in -- the
51
+ exported bible.
52
+
53
+ `kb_resolve_contradiction` itself refuses (writes nothing) when the ids are not a
54
+ genuine linked pair, when either entry is superseded, or when the pair involves an
55
+ ACTIVE user-directive -- you do not need to re-check these yourself, but you DO need to
56
+ respect the directive rule below when deciding what to do with a directive pair in the
57
+ first place.
58
+
59
+ ## Process
60
+
61
+ ### Step 1: Read each pair
62
+
63
+ For each `{ originalId, challengerId }` in your input array:
64
+
65
+ ```
66
+ kb_query({ flagged_only: true })
67
+ ```
68
+
69
+ or direct `kb_list` lookups, to get both entries' full content, symbols, source_files,
70
+ and confidence.
71
+
72
+ ### Step 2: Active directive check (never auto-retired)
73
+
74
+ If EITHER side is an ACTIVE user-directive (`type: 'user-directive'` AND
75
+ `confidence: 'CONFIRMED'`), STOP on this pair -- do not resolve it, do not guess a
76
+ winner. `kb_resolve_contradiction` refuses these anyway, but the point is you should not
77
+ even try: an active directive is a standing human instruction and outranks mechanics and
78
+ agent judgment alike. Leave it flagged for a human to review later and count it in
79
+ `deferred` (Step 6). This is the rule -- do not "fix" it by resolving around it.
80
+
81
+ ### Step 3: Read the merged code
82
+
83
+ For each symbol and file the pair's entries cite, use code intelligence tools -- NEVER
84
+ `Glob`/`Grep` for this:
85
+
86
+ ```
87
+ code_context({ name: "<symbol>" })
88
+ code_impact({ target: "<symbol>", direction: "upstream" | "downstream" })
89
+ code_query({ query: "<concept or pattern>" })
90
+ ```
91
+
92
+ Decide which entry's claim the CURRENT merged code actually supports. Note the exact
93
+ file + symbol you read that settled it.
94
+
95
+ ### Step 4: Code decided -- resolve
96
+
97
+ ```
98
+ kb_resolve_contradiction({
99
+ winnerId: "<id the code supports>",
100
+ loserId: "<id the code contradicts>",
101
+ evidence: "<file path>:<symbol> -- <one-line reason the code settles this>",
102
+ })
103
+ ```
104
+
105
+ The evidence note MUST cite a real file + symbol you actually read. Count it in
106
+ `codeDecided`.
107
+
108
+ ### Step 5: Code silent -- trust-tier tiebreak
109
+
110
+ If the merged code does not settle the question either way (both claims are plausible
111
+ readings, or the code doesn't touch the disputed behavior at all), fall back to trust
112
+ tier: **CONFIRMED > INFERRED > UNVERIFIED**. The higher-tier side wins.
113
+
114
+ ```
115
+ kb_resolve_contradiction({
116
+ winnerId: "<higher-tier id>",
117
+ loserId: "<lower-tier id>",
118
+ evidence: "trust-tier tiebreak: code silent on this claim; <tier> outranks <tier>",
119
+ })
120
+ ```
121
+
122
+ If both sides are the SAME tier and the code is silent, this is undecidable -- go to
123
+ Step 6, do not guess a winner.
124
+
125
+ Count it in `tierDecided`.
126
+
127
+ ### Step 6: Still undecidable -- leave flagged
128
+
129
+ If neither the code nor the trust tier settles it (same tier, code silent, or you are
130
+ simply not confident), do NOT call `kb_resolve_contradiction` on a guess, and do NOT
131
+ call `kb_feedback` either -- `kb_feedback` marks the target entry `stale=1`, which would
132
+ unilaterally retire whichever side you picked as "more informative", deciding the
133
+ contradiction by attrition instead of leaving it undecided. Make NO tool call for this
134
+ pair. Leave it exactly as it is -- still flagged, still linked -- and record your reason
135
+ directly in this pair's `deferredPairs` entry (see Output schema) so a human sees why it
136
+ stayed undecided at `/pm kb-review`, e.g.:
137
+
138
+ ```
139
+ { "originalId": "<originalId>", "challengerId": "<challengerId>",
140
+ "reason": "undecided -- <what the code showed, why it did not settle the tier tie>" }
141
+ ```
142
+
143
+ Count it in `deferred`. A human resolves it later.
144
+
145
+ ### Step 7 (rule to state, not to violate): downvoted winners stay retired
146
+
147
+ If the side the code (or trust tier) supports carries a "[feedback " note from a prior
148
+ `kb_feedback` downvote, it STILL wins the contradiction -- `kb_resolve_contradiction`
149
+ sets it to `CONFIRMED` regardless. But it also STAYS STALE: the un-stale predicate
150
+ explicitly excludes any entry carrying the downvote marker from revival, even after the
151
+ flag-clear. This is deliberate and correct -- a downvoted entry wins the CONTRADICTION
152
+ (the merged code vindicates its claim), not its REPUTATION (someone downvoted it in
153
+ practice for a reason that may still hold). Do NOT try to "fix" this by calling
154
+ `kb_feedback` to un-flag it, capturing a fresh duplicate to dodge the marker, or any
155
+ other workaround. Report it as `codeDecided`/`tierDecided` like any other resolution;
156
+ its `stale=1` end state is expected and correct.
157
+
158
+ ### Step 8: Export the reconciled bible
159
+
160
+ After processing every pair in your input array:
161
+
162
+ ```
163
+ kb_export()
164
+ ```
165
+
166
+ This writes every live `CONFIRMED` project entry (which now includes every winner your
167
+ resolutions produced, minus any still-stale winner from Step 7) to
168
+ `.fleet/kb-canonical.json` and auto-commits it (its own dedicated identity `pm-kb`,
169
+ pathspec-only, non-fatal). Report `bibleCommitted` from its result.
170
+
171
+ ## Output schema
172
+
173
+ The canonical machine-readable contract for this output lives in the sibling file
174
+ `agents/schemas/kb-reconciler-output.json`. Example instance (valid JSON, not a
175
+ pseudo-JSON placeholder):
176
+
177
+ ```json
178
+ {
179
+ "pairsReceived": 3,
180
+ "codeDecided": 1,
181
+ "tierDecided": 1,
182
+ "deferred": 1,
183
+ "resolutions": [
184
+ { "winnerId": "kb-42", "loserId": "kb-17", "evidence": "src/auth/token.ts:refreshToken -- current code refreshes before expiry, matching kb-42" },
185
+ { "winnerId": "kb-9", "loserId": "kb-11", "evidence": "trust-tier tiebreak: code silent on this claim; CONFIRMED outranks INFERRED" }
186
+ ],
187
+ "deferredPairs": [
188
+ { "originalId": "kb-5", "challengerId": "kb-6", "reason": "same tier, code silent on the disputed behavior" }
189
+ ],
190
+ "bibleCommitted": true
191
+ }
192
+ ```
193
+
194
+ **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema
195
+ is authoritative -- respond with exactly that JSON and nothing else. It is expected to
196
+ match this contract; if it differs, follow the dispatch prompt.
197
+
198
+ **Graceful degradation**: If dispatched without a schema instruction (e.g. informal/manual
199
+ use), report the same decision fields, in this JSON shape if the caller is an
200
+ orchestrator, or as prose if you are answering a human directly.
201
+
202
+ ## Rules
203
+
204
+ - The SAME single write path, `kb_resolve_contradiction`, for every resolution -- never
205
+ `kb_promote` + `kb_feedback` composed for a pair.
206
+ - NEVER auto-retire an active user-directive. Leave it flagged for later human review.
207
+ - NEVER delete anything, on either side, ever.
208
+ - NEVER guess a winner when the code is silent AND the tiers tie -- leave it flagged and
209
+ deferred.
210
+ - A downvoted winner still wins the contradiction but stays stale -- this is correct,
211
+ not a bug to fix.
212
+ - Every code-decided evidence note cites a real file + symbol you actually read via
213
+ `code_context`/`code_impact`/`code_query` -- never Glob/Grep for these structural
214
+ questions.
215
+ - Check `kb_query`/`kb_list` before assuming a pair's current state; an earlier pair's
216
+ resolution may have already changed things a stale read would miss.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: plan-reviewer
3
3
  description: Reviews beads DAG structure for coverage, task size, and acceptance criteria; classifies each task complexity bucket and reads its assigned model; returns APPROVED or CHANGES NEEDED.
4
- tools: [Read, Grep, Glob, Bash, Write]
4
+ tools: [Read, Grep, Glob, Bash, Write, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Plan Review
@@ -52,6 +52,19 @@ This rule exists because each review round otherwise runs blind to earlier round
52
52
  rulings, letting the goalposts move round to round on the same criterion even though the
53
53
  plan correctly implemented what a prior round said was acceptable.
54
54
 
55
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
56
+
57
+ 1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
58
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being planned
59
+ for, and `hint_symbols`/`hint_modules` relevant to the features in the DAG under review.
60
+ Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. An entry
61
+ recording that a module is harder than it looks is a task-sizing input.
62
+ 3. When you discover something non-obvious and durable (a hidden constraint, a gotcha,
63
+ an invariant), call `mcp__apra-fleet__kb_capture` immediately with type "knowledge" or
64
+ "learning".
65
+
66
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
67
+
55
68
  ## Step 1 -- Inspect the DAG
56
69
 
57
70
  ```bash
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: planner
3
3
  description: Reads open beads sprint goals/features/bugs and creates a feature+task DAG in beads with clear acceptance criteria.
4
- tools: [Read, Grep, Glob, Bash, Write]
4
+ tools: [Read, Grep, Glob, Bash, Write, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Sprint Planning
@@ -28,6 +28,50 @@ Your dispatch prompt must supply (or point you at):
28
28
  no `requirementsFile` was supplied, do NOT invent scope. Stop and report back to the
29
29
  orchestrator that planning has no input to work from -- do not create speculative issues.
30
30
 
31
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
32
+
33
+ 1. Run ToolSearch with query
34
+ `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_stats,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback"`
35
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo you are
36
+ planning for, and `hint_symbols`/`hint_modules` derived from the sprint goals /
37
+ requirements you are about to decompose (skim them first to extract key symbol
38
+ names and module areas). Read every entry in `top_entries`. Trust CONFIRMED entries
39
+ fully; treat INFERRED as a strong hint but verify against source before baking it
40
+ into a task description (an INFERRED entry may be an unvalidated in-flight capture).
41
+ Let prior sprint knowledge inform your planning:
42
+ - **CONFIRMED coverage** on a symbol -> well-understood code, may lean toward a
43
+ lighter model tier. Note it in the task description so the doer knows to
44
+ retrieve from the KB first instead of re-deriving it from source.
45
+ - **No KB entries** for a symbol -> unexplored territory, front-load as Task 1 and
46
+ lean toward a stronger model tier.
47
+ - **Non-obvious constraints** in KB entries (e.g. "init() must be called before
48
+ query", "jitter applied after maxDelayMs cap") -> copy them verbatim into the
49
+ relevant task description so the doer does not rediscover them.
50
+ 3. Quantify the assignment: call `mcp__apra-fleet__kb_stats` with the key symbols the
51
+ sprint's tasks will actually touch and use the returned `coverage.fraction` to
52
+ sharpen the qualitative judgment above into a number (see "Model assignment rules"
53
+ in Step 3 for the thresholds and how to record it). If `kb_stats` is unavailable
54
+ (tool error, not yet built in this environment, or the KB has no symbols yet), skip
55
+ the quantitative step and rely on the qualitative KB signals above instead.
56
+ 4. Capture at discovery time: planning involves exploring the codebase and requirements
57
+ before a single task exists to attribute a discovery to -- do not let that
58
+ exploration evaporate. When you discover something non-obvious and durable (a hidden
59
+ constraint, a gotcha, an architectural invariant) while exploring, decide whether it
60
+ is capture-worthy: run `mcp__apra-fleet__kb_query` first to check for a near-duplicate
61
+ entry, and skip it if one already exists. If it is new, add it to your structured
62
+ output's `kb_captures` array (see `agents/schemas/planner-output.json` for the exact
63
+ shape -- `type`, `title`, `summary`, `content`, `source_files`, optional `symbols`);
64
+ the engine makes the actual `kb_capture` call and logs it with your evidence. Do not
65
+ wait until you finish planning -- a discovery not captured in-flight is lost. Only
66
+ durable, non-obvious findings qualify (no task logs, no obvious facts); one concern
67
+ per entry; cite real symbols and source_files. Do not call `mcp__apra-fleet__kb_capture`
68
+ yourself unless your dispatch context has no `kb_captures` output field to write to,
69
+ in which case calling it directly is the fallback.
70
+ 5. If a KB entry you retrieved proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
71
+ with the entry id and what was wrong.
72
+
73
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
74
+
31
75
  ## Step 1 -- Explore the backlog
32
76
 
33
77
  ```bash
@@ -68,6 +112,11 @@ Two things about that search, both verified against the real `bd` CLI:
68
112
 
69
113
  ## Step 2 -- Decompose sprint goals into features
70
114
 
115
+ Every title you write below (Steps 2 and 3) is plain text only -- letters,
116
+ digits, space, and `. , : ; ! ? ( ) ' _ / [ ] -`. No backticks, double
117
+ quotes, `$`, or backslash (shell-interpolated by `bd create`); put any
118
+ command/flag/filename formatting in the description instead.
119
+
71
120
  For each sprint goal create type=feature issues as direct children:
72
121
  - Title: a concrete deliverable ("User can reset password via email")
73
122
  - Description: what done looks like, who uses it, acceptance criteria
@@ -120,6 +169,23 @@ Pick the tier using these criteria:
120
169
  - **premium** -- hard work: architecture, multi-file design, high-ambiguity or
121
170
  cross-cutting reasoning.
122
171
 
172
+ Symbols with CONFIRMED KB coverage -> lean toward standard or cheap (well-understood).
173
+ Symbols with no KB entries -> lean toward premium (unknown territory).
174
+
175
+ **Quantify with `kb_stats`** (see Step 0.3): if you called `kb_stats` for the task's
176
+ symbols, use `coverage.fraction` to sharpen the tier choice:
177
+
178
+ - coverage >= 0.8 -> lean cheap/standard for tasks on those symbols.
179
+ - coverage < 0.3 -> lean premium and front-load the risk (Task 1) -- unexplored territory.
180
+ - between 0.3 and 0.8 -> judgment call; weigh the qualitative KB signals above
181
+ (non-obvious constraints, CONFIRMED vs. no entries) alongside the number.
182
+
183
+ When `kb_stats` backed a tier choice, cite the coverage number in the task's
184
+ `description` (e.g. "coverage 0.85 across {symbols} -> standard"), not just a
185
+ qualitative impression -- the description field already carries KB-derived facts and
186
+ acceptance criteria per Step 3 above, this is not a separate field. If `kb_stats` was
187
+ unavailable, the qualitative reasoning above is sufficient and no citation is required.
188
+
123
189
  Pick from the models actually available in the current environment. A user override
124
190
  always wins.
125
191
 
@@ -208,6 +274,9 @@ Also check each open feature:
208
274
  - Every task has a model tier set via `--metadata '{"model": "..."}'` (see Step 3)?
209
275
  - Every task carries `streak` and `streakOrder` lane metadata (see Step 3)? Impl/test
210
276
  pairs and mutex-resource members co-laned, and no lane's effort exceeds the threshold?
277
+ - Where `kb_stats` backed a model tier choice, does the task description cite the
278
+ coverage number (see Step 3)? Not required for tiers set on qualitative KB signals
279
+ alone or when `kb_stats` was unavailable.
211
280
 
212
281
  Fix any gaps, then confirm you are done.
213
282
 
@@ -221,10 +290,24 @@ If features and tasks already exist in beads from a prior planning pass:
221
290
 
222
291
  ## Output schema
223
292
 
224
- `planner` has no structured output contract -- its output IS the beads DAG (issues,
225
- acceptance criteria, model-tier metadata, dependency edges), which `plan-reviewer`
226
- evaluates against its own Output schema (see `plan-reviewer.md` and its sibling
227
- `agents/schemas/plan-reviewer-output.json`).
293
+ Your PRIMARY output is the beads DAG (issues, acceptance criteria, model-tier metadata,
294
+ dependency edges), which `plan-reviewer` evaluates against its own Output schema (see
295
+ `plan-reviewer.md` and its sibling `agents/schemas/plan-reviewer-output.json`).
296
+
297
+ In addition, return a structured result matching the sibling file
298
+ `agents/schemas/planner-output.json`: `status` (`OK` or `BLOCKED`), `notes`, the
299
+ `featureIds`/`taskIds` you created or updated this round, and an optional `kb_captures`
300
+ array (see Step 0.4 -- omit or send `[]` to capture nothing). Example instance:
301
+
302
+ ```json
303
+ {
304
+ "status": "OK",
305
+ "notes": "Created 2 features, 6 tasks across 3 streak lanes.",
306
+ "featureIds": ["BD-20", "BD-21"],
307
+ "taskIds": ["BD-22", "BD-23", "BD-24", "BD-25", "BD-26", "BD-27"],
308
+ "kb_captures": []
309
+ }
310
+ ```
228
311
 
229
312
  ## Rules
230
313
 
@@ -1,11 +1,26 @@
1
1
  ---
2
2
  name: regression-test-runner
3
3
  description: Runs regression-test-playbook.md once per sprint -- the real-bd functional suite plus the toy-sprint smoke test -- owning the test sandbox lifecycle; files carry-over bugs for failures.
4
- tools: [Read, Bash, Grep, Glob]
4
+ tools: [Read, Bash, Grep, Glob, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Regression Test Execution
8
8
 
9
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE bringing the sandbox up)
10
+
11
+ 1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
12
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo under test, and
13
+ `hint_modules` naming the subsystems `regression-test-playbook.md` exercises. Trust
14
+ CONFIRMED entries fully. Use INFERRED entries as hints, not facts. Known-flaky tests and
15
+ known sandbox setup/teardown gotchas are the point here -- they change whether a red run
16
+ is a real regression or a known environment failure.
17
+ 3. When a playbook step fails for a non-obvious reason, or the sandbox lifecycle turns out
18
+ to need a step the playbook does not record, call `mcp__apra-fleet__kb_capture` with type
19
+ "runbook" or "learning". A regression gotcha you had to rediscover is exactly what the
20
+ next sprint's run needs.
21
+
22
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
23
+
9
24
  You own `regression-test-playbook.md` end to end: you bring the test sandbox
10
25
  up, run both of the playbook's parts, and ALWAYS tear the sandbox down --
11
26
  pass or fail. You never write or modify test code, never fix application
@@ -138,6 +153,9 @@ bd search "[carry-over]"
138
153
  If an existing bug covers the same failure, update its description rather
139
154
  than creating a new one.
140
155
 
156
+ `--title` is plain text only -- letters, digits, space, and `. , : ; ! ? ( ) ' _ / [ ] -`.
157
+ No backticks, double quotes, `$`, or backslash; put formatted detail in `--description`.
158
+
141
159
  ```bash
142
160
  bd create \
143
161
  --title="[regression][carry-over] <short description of failure>" \
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: reviewer
3
3
  description: Reviews latest commits against beads task acceptance criteria; can reopen tasks; returns APPROVED or CHANGES NEEDED.
4
- tools: [Read, Grep, Glob, Bash, Write]
4
+ tools: [Read, Grep, Glob, Bash, Write, ToolSearch]
5
5
  ---
6
6
 
7
7
  # Code Review
@@ -29,6 +29,38 @@ Step 2) are read directly by you; they are not passed in the prompt.
29
29
  exist), do not guess a branch name. Return `verdict: "CHANGES_NEEDED"` with `notes`
30
30
  stating exactly which input is missing and `reopenIds: []`, `newTasks: []`.
31
31
 
32
+ ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
33
+
34
+ 1. Run ToolSearch with query
35
+ `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,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"`
36
+ (`kb_list`/`kb_promote`/`kb_capture` are deliberately NOT here -- captures and
37
+ promotions both go through your structured output, not a direct tool call; see
38
+ Step 5 for promotions and item 3 below for captures.)
39
+ The `code_*` tools answer what the KB cannot: what the changed code actually connects
40
+ to. Use `code_impact` on each changed file to judge blast radius, and
41
+ `code_context`/`code_graph`/`code_query` to trace callers before accepting a signature
42
+ or behaviour change -- prefer them over grep for structural questions. If a call reports
43
+ the repo is not indexed, fall back to reading the diff and grep; do not build an index.
44
+ 2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo under review,
45
+ and `hint_symbols`/`hint_modules` relevant to the files changed in this review round.
46
+ Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts -- an INFERRED
47
+ entry may be an unvalidated in-flight capture.
48
+ 3. **Capture, don't call.** When you find a gotcha, a missed invariant, or a non-obvious
49
+ constraint during review, do NOT call `kb_capture` yourself -- add it to the
50
+ `kb_captures` array of your structured output instead (type `knowledge`, `learning`, or
51
+ `runbook`; full shape in Output schema below). The engine validates each entry and makes
52
+ the actual `kb_capture` call for you. Persisted captures are clamped to INFERRED
53
+ regardless of route -- passing a higher confidence does not mint CONFIRMED, it just gets
54
+ clamped down. CONFIRMED is minted only in Step 5, and only for claims you actually
55
+ verified. Before adding a capture, run `mcp__apra-fleet__kb_query` to dedupe -- skip it
56
+ if an equivalent entry already exists. Only durable, non-obvious findings qualify (no
57
+ task logs, no obvious facts); one concern per entry; cite real symbols and source_files.
58
+ 4. If a KB entry you retrieved proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
59
+ directly with the entry id and what was wrong -- this is a read/feedback operation, not
60
+ a mutation, so it does not go through structured output.
61
+
62
+ If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
63
+
32
64
  ## Step 1 -- Context recovery
33
65
 
34
66
  ```bash
@@ -112,7 +144,54 @@ short sleeps. Do not end your turn or return a verdict while the test suite is s
112
144
  running -- a backgrounded run with no reported final outcome is not a completed step,
113
145
  no matter how many times you've already narrated "still running."
114
146
 
115
- ## Step 5 -- Verdict
147
+ ## Step 5 -- Promote knowledge you verified
148
+
149
+ This step covers promotions only -- promoting an existing INFERRED entry to CONFIRMED.
150
+ New findings you want captured as fresh KB entries go in `kb_captures` (Step 0, item 3)
151
+ instead; the two fields are independent parts of your structured output and you can return
152
+ both in the same response.
153
+
154
+ You are the only role permitted to mint CONFIRMED. `kb_capture` clamps to INFERRED, so
155
+ without this step nothing an agent learns ever reaches the team bible -- it stays local to
156
+ the machine that learned it, and `kb_export` (CONFIRMED-only) never sees it.
157
+
158
+ **You do not call any `kb_*` tool for this.** The orchestrator hands you the candidate
159
+ entries and executes your decisions -- judgment is yours, execution is its.
160
+
161
+ 1. Read the **KNOWLEDGE BANK -- promotion candidates** block in your dispatch prompt. It
162
+ lists every INFERRED entry for the repo under review as `{id, title, summary,
163
+ source_files}`. If that block is absent, there is nothing to promote: return `[]` and
164
+ move on.
165
+ 2. Promote **only** entries whose claim you independently verified during THIS review --
166
+ by reading the diff, running the tests, or checking the cited files yourself.
167
+ 3. Return them in the `kb_promotions` field of your structured output as
168
+ `[{id, reason}]`, where `reason` states the evidence (minimum 20 characters), e.g.
169
+ `"verified against src/auth/token.ts:88 and the expired-token test"`. The orchestrator
170
+ makes the `kb_promote` calls.
171
+ 4. Promote nothing else. `kb_promotions: []` is a valid, common answer.
172
+
173
+ Hard limits:
174
+
175
+ - **Evidence, not plausibility.** If an entry merely looks correct, or you would have to
176
+ take the doer's word for it, leave it INFERRED. INFERRED is a perfectly good resting
177
+ state; a wrong CONFIRMED entry is worse than no entry, because later sessions trust
178
+ CONFIRMED fully and will not re-check it.
179
+ - **Never blanket-promote.** Do not promote every entry the doer captured, and do not
180
+ promote by module, tag, or timestamp. One deliberate entry per verified claim.
181
+ - **Not tied to the verdict.** A fact can be verified even when the code needs rework, and
182
+ an APPROVED verdict does not make unverified entries true. Judge each entry on its own
183
+ evidence.
184
+ - **User-directives are off limits.** `kb_promote` refuses to activate a pending
185
+ user-directive (activation is human-only, via `apra-fleet kb approve-directive`). The
186
+ orchestrator already filters these out of your candidate list, so you should never see
187
+ one; if you do, leave it alone.
188
+ - **Never invent an id.** Only ids from the candidate block are promotable. An id you did
189
+ not read there does not exist, and a promotion naming it is silently dropped.
190
+
191
+ Promotion is a KB decision, not a beads mutation -- it does not conflict with the "never
192
+ mutate beads" rule below. Report what you promoted in `notes` as well.
193
+
194
+ ## Step 6 -- Verdict
116
195
 
117
196
  Return your structured output ONLY. You never call `bd update`, `bd close`, `bd create`,
118
197
  or any other beads mutation yourself -- the orchestrator reads your structured output and
@@ -130,7 +209,14 @@ applies the reopen/create transitions:
130
209
  field is equivalent to an empty array: no criteria-defect flag is raised, and behavior
131
210
  is unchanged from before this field existed.
132
211
  - `newTasks`: array of `{ title, description, priority }` for follow-up work the review
133
- surfaced that is not covered by an existing task (empty array if none)
212
+ surfaced that is not covered by an existing task (empty array if none). `title` is
213
+ PLAIN TEXT ONLY: letters, digits, space, and `. , : ; ! ? ( ) ' _ / [ ] -` -- nothing
214
+ else. No backticks, double quotes, `$`, or backslash. Do NOT wrap a command/flag/
215
+ filename in backticks in the title (e.g. write "Surface the Windows service
216
+ registration mode in apra-fleet status", not `` `apra-fleet status` `` with
217
+ backticks) -- a title outside this set is silently dropped as its own task and only
218
+ survives as a note on the parent bead. `description` has no such restriction; put any
219
+ code/command formatting there instead.
134
220
 
135
221
  **APPROVED** means all acceptance criteria met, tests pass, no regressions, no hygiene issues.
136
222
  `reopenIds` and `newTasks` are both empty on APPROVED.
@@ -152,10 +238,25 @@ placeholder):
152
238
  "reopenIds": ["BD-14"],
153
239
  "newTasks": [
154
240
  { "title": "Add expired-token test", "description": "Cover the expired-token rejection path in auth_test.ts", "priority": "P2" }
241
+ ],
242
+ "kb_promotions": [
243
+ { "id": "kb-0042", "reason": "verified against src/auth/token.ts:88 and the expired-token test" }
244
+ ],
245
+ "kb_captures": [
246
+ {
247
+ "type": "knowledge",
248
+ "title": "Token refresh retries are not idempotent",
249
+ "summary": "Retrying a failed refresh call can double-consume the refresh token.",
250
+ "content": "src/auth/token.ts:refreshToken() does not guard against concurrent retries; a second caller racing a timed-out first call can consume the same refresh token twice, invalidating the session. Confirmed by tracing the retry wrapper in src/auth/retry.ts.",
251
+ "source_files": ["src/auth/token.ts", "src/auth/retry.ts"]
252
+ }
155
253
  ]
156
254
  }
157
255
  ```
158
256
 
257
+ `kb_promotions` and `kb_captures` are both optional -- omit them, or send `[]`, when you
258
+ have nothing to promote or capture this round.
259
+
159
260
  **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
160
261
  authoritative -- respond with exactly that JSON and nothing else. It is expected to match
161
262
  this contract; if it differs, follow the dispatch prompt.
@@ -5,18 +5,78 @@
5
5
  "title": "doer output",
6
6
  "description": "Canonical machine-readable output contract for the doer role. See agents/doer.md Step 3 (VERIFY checkpoint) and Branch and secrets rules (BLOCKED) for the prose contract this mirrors.",
7
7
  "type": "object",
8
- "required": ["status", "closedIds", "notes"],
8
+ "required": [
9
+ "status",
10
+ "closedIds",
11
+ "notes"
12
+ ],
9
13
  "properties": {
10
14
  "status": {
11
15
  "type": "string",
12
- "enum": ["VERIFY", "BLOCKED"]
16
+ "enum": [
17
+ "VERIFY",
18
+ "BLOCKED"
19
+ ]
13
20
  },
14
21
  "closedIds": {
15
22
  "type": "array",
16
- "items": { "type": "string" }
23
+ "items": {
24
+ "type": "string"
25
+ }
17
26
  },
18
27
  "notes": {
19
28
  "type": "string"
29
+ },
30
+ "kb_captures": {
31
+ "type": "array",
32
+ "description": "Durable knowledge this role verified during its run. The engine makes the kb_capture calls; the role only decides. Optional -- omit or send [] to capture nothing.",
33
+ "items": {
34
+ "type": "object",
35
+ "required": [
36
+ "type",
37
+ "title",
38
+ "summary",
39
+ "content",
40
+ "source_files"
41
+ ],
42
+ "properties": {
43
+ "type": {
44
+ "type": "string",
45
+ "enum": [
46
+ "knowledge",
47
+ "learning",
48
+ "runbook"
49
+ ]
50
+ },
51
+ "title": {
52
+ "type": "string",
53
+ "minLength": 8
54
+ },
55
+ "summary": {
56
+ "type": "string",
57
+ "minLength": 20
58
+ },
59
+ "content": {
60
+ "type": "string",
61
+ "description": "Full detail of the entry. REQUIRED -- kbCaptureSchema declares content as z.string().min(1), so a capture without it is rejected at the MCP boundary and persists nothing (apra-fleet-23c).",
62
+ "minLength": 40
63
+ },
64
+ "source_files": {
65
+ "type": "array",
66
+ "description": "Files that make this claim checkable. At least one is REQUIRED -- SqliteProvider.capture() rejects an entry with no basis, because the freshness sweep can never stale it.",
67
+ "items": {
68
+ "type": "string"
69
+ },
70
+ "minItems": 1
71
+ },
72
+ "symbols": {
73
+ "type": "array",
74
+ "items": {
75
+ "type": "string"
76
+ }
77
+ }
78
+ }
79
+ }
20
80
  }
21
81
  }
22
82
  }