@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
@@ -25,7 +25,7 @@ apra-fleet workflow fleet-sprint \
25
25
  [--role-map <json|@file>] # {"doer":["m1","m2"], ...}
26
26
  [--viewer-port <port>] # default 8080
27
27
  [--budget <usd>] # default unlimited
28
- [--dispatch-timeout-s <s>] # default 3600
28
+ [--dispatch-timeout-s <s>] # default 9000
29
29
  [--sync] # synced-topology mode
30
30
  ```
31
31
 
@@ -43,6 +43,12 @@ on this list -- flags evolve and this skill can drift.
43
43
  `packages/apra-fleet-se/fleet-sprint/docs/README.md`.
44
44
  - `--branch` is created from `--base` if it does not already exist. If it
45
45
  does exist (e.g. you are resuming), it is reused as-is.
46
+ - **`--base` is resolved against the remote, not your local checkout.** A new
47
+ sprint branch is cut from `origin/<base>`, so any local commit on `<base>`
48
+ that you have not pushed is invisible to the run. Push `<base>` first --
49
+ otherwise the sprint silently starts from an older tree, and work that
50
+ depends on those commits (a `.beads/config.yaml` from `bd init`, a new
51
+ package.json script) fails in ways that look unrelated.
46
52
  - `--role-map` assigns specific members to specific roles, e.g.
47
53
  `--role-map '{"doer":["m1","m2"],"reviewer":["m3"]}'`. Accepts inline JSON
48
54
  or `@path/to/file.json`.
@@ -51,7 +57,12 @@ on this list -- flags evolve and this skill can drift.
51
57
 
52
58
  ## Preconditions to check first
53
59
 
54
- 1. Every `--issue` target exists and is open: `bd show <id>`.
60
+ 1. Every `--issue` target exists and is open: `bd show <id>`, **and already has
61
+ children**: `bd list --parent <id>` must return at least one open bead.
62
+ Pre-sprint validation runs BEFORE the planner, so a childless epic aborts
63
+ the run ("No open/in-progress/blocked/deferred beads found for scope ...")
64
+ rather than being decomposed. The planner refines an existing DAG; it does
65
+ not create the first level of it.
55
66
  2. Every `--members` name is registered with the fleet (`list_members` /
56
67
  `mcp__apra-fleet__list_members`). An unregistered member aborts the
57
68
  sprint unless `--allow-missing-members` is passed.
@@ -0,0 +1,350 @@
1
+ ---
2
+ name: fleet-supervisor
3
+ description: How to start/smoke-test the supervisor process itself, and start, check, and kill fleet-sprints via its HTTP API only (POST /api/sprints on localhost:8787). Never call the fleet-sprint CLI directly. Trigger whenever asked to start/launch/check/stop/kill the supervisor or a sprint.
4
+ ---
5
+
6
+ # fleet-supervisor (supervisor API)
7
+
8
+ Sprints are started, checked, and killed through the supervisor's HTTP API.
9
+ Default port: **8787**. Never invoke `apra-fleet workflow fleet-sprint` or
10
+ `bin/cli.mjs` directly -- always go through this API.
11
+
12
+ ## 0. Start the supervisor (if not already running)
13
+
14
+ Check first: `curl -s -m 5 http://localhost:8787/api/sprints`. Connection
15
+ refused/timeout = not running. `{"sprints": [...]}` = already up, skip this.
16
+
17
+ Start it detached (it runs indefinitely -- exits only on `POST
18
+ /api/shutdown` or SIGINT/SIGTERM, never on its own):
19
+
20
+ ```bash
21
+ node packages/apra-fleet-se/bin/serve.mjs # background/detached, from repo root
22
+ ```
23
+
24
+ `--port <n>` overrides the default (8787). Self-logs to
25
+ `<dataDir>/logs/supervisor.log` in addition to stdout.
26
+
27
+ Smoke test (a few seconds after launch -- give it time to bind):
28
+ ```bash
29
+ curl -s -m 5 http://localhost:8787/api/sprints # expect {"sprints":[],...}
30
+ curl -s -m 5 http://localhost:8787/api/members # expect the registered fleet, non-empty
31
+ ```
32
+ Both must succeed before treating the supervisor as up -- a bound port with
33
+ a 500 on `/api/members` still means something is broken.
34
+
35
+ ## Stop the supervisor
36
+
37
+ Two paths: **graceful** (preferred -- lets in-flight requests finish and every
38
+ seam tear down cleanly) and **hard-stop** (only when the API itself is
39
+ unresponsive, e.g. a hung event loop). Resolve commands per the target
40
+ member's own OS (`agent.os`) -- do not assume the orchestrator's shell; some
41
+ members run PowerShell, not POSIX.
42
+
43
+ ### Graceful (preferred)
44
+
45
+ ```bash
46
+ curl -s -X POST http://localhost:8787/api/shutdown
47
+ ```
48
+ Returns `{"status":"shutting-down"}` immediately; the process then finishes
49
+ tearing down every seam (ledger, watchdog, dashboard, etc) and exits on its
50
+ own a moment later. Confirm it is actually gone:
51
+ ```bash
52
+ curl -s -m 5 http://localhost:8787/api/sprints # expect connection refused
53
+ ```
54
+ If that still connects after a few seconds, fall through to hard-stop below.
55
+
56
+ ### Find the supervisor's PID/port (when the API is unresponsive)
57
+
58
+ `GET /api/health` normally reports the running `pid` directly (`curl -s -m 5
59
+ http://localhost:8787/api/health`), but if the API itself is unresponsive
60
+ that call will hang or refuse -- fall back to an OS-level lookup by port
61
+ (default **8787**) or process name (`serve.mjs`):
62
+
63
+ **macOS / Linux:**
64
+ ```bash
65
+ lsof -i :8787 # shows the PID (COMMAND, PID columns) bound to the port
66
+ lsof -ti:8787 # PID only, convenient for command substitution
67
+ # or, by process name if the port lookup finds nothing (already unbound but
68
+ # the process is still alive/hung):
69
+ pgrep -f 'bin/serve.mjs'
70
+ ```
71
+
72
+ **Windows (PowerShell):**
73
+ ```powershell
74
+ Get-NetTCPConnection -LocalPort 8787 | Select-Object OwningProcess
75
+ Get-Process -Id <pid> # confirm it is the supervisor before killing it
76
+ # or, by process name:
77
+ Get-Process | Where-Object { $_.Path -like '*serve.mjs*' -or $_.CommandLine -like '*serve.mjs*' }
78
+ ```
79
+
80
+ **Windows (cmd.exe, if PowerShell is unavailable):**
81
+ ```cmd
82
+ netstat -ano | findstr :8787
83
+ tasklist /FI "PID eq <pid>"
84
+ ```
85
+
86
+ ### Hard-stop (PID-based kill)
87
+
88
+ Only once you have confirmed the PID above is actually the supervisor
89
+ process. Try a graceful signal first, then force:
90
+
91
+ **macOS / Linux:**
92
+ ```bash
93
+ kill <pid> # SIGTERM -- gives it a chance to exit cleanly
94
+ sleep 2
95
+ kill -0 <pid> 2>/dev/null && kill -9 <pid> # still alive? force it
96
+ ```
97
+
98
+ **Windows (PowerShell):**
99
+ ```powershell
100
+ Stop-Process -Id <pid> # graceful-ish first attempt
101
+ Stop-Process -Id <pid> -Force # still running? force-kill
102
+ ```
103
+
104
+ **Windows (cmd.exe):**
105
+ ```cmd
106
+ taskkill /PID <pid>
107
+ taskkill /PID <pid> /F
108
+ ```
109
+
110
+ After either path, verify the port is free before restarting:
111
+ `curl -s -m 5 http://localhost:8787/api/sprints` must refuse the connection
112
+ (macOS/Linux), or the port-lookup command above must return nothing
113
+ (Windows).
114
+
115
+ ## Restart the supervisor
116
+
117
+ A discrete stop-then-start procedure -- use this instead of assuming a bare
118
+ restart command exists:
119
+
120
+ 1. **Stop** it: graceful shutdown above; if that does not actually stop it
121
+ (still answering after a few seconds), fall back to the hard-stop path
122
+ above.
123
+ 2. **Confirm it is down**: `curl -s -m 5 http://localhost:8787/api/sprints`
124
+ must refuse the connection (or the per-OS port lookup above returns
125
+ nothing).
126
+ 3. **Start** it again: see section 0 ("Start the supervisor") above, then
127
+ run its smoke test (`GET /api/sprints`, `GET /api/members`) to confirm the
128
+ new process is actually serving before treating the restart as done.
129
+
130
+ ## Auto-start on login/boot
131
+
132
+ Instead of a human running `node bin/serve.mjs` by hand each session, the
133
+ supervisor can be registered with the OS to start automatically on
134
+ login/boot. Resolve commands per the target member's own OS (`agent.os`) --
135
+ do not assume the orchestrator's shell; some members run PowerShell, not
136
+ POSIX. Every example below assumes the repo root is
137
+ `/path/to/apra-fleet` (POSIX) or `C:\path\to\apra-fleet` (Windows) --
138
+ substitute the real path on the target member. After registering (any OS),
139
+ run the same-process smoke test from section 0 above (`GET /api/sprints`,
140
+ `GET /api/members`) against the newly auto-started instance to confirm it is
141
+ actually serving, not just that the OS accepted the registration.
142
+
143
+ ### Windows
144
+
145
+ **Option A -- Task Scheduler, "At log on" trigger** (simplest; runs in the
146
+ user's own session):
147
+
148
+ Register:
149
+ ```cmd
150
+ schtasks /Create /TN "ApraFleetSupervisor" /TR "node C:\path\to\apra-fleet\packages\apra-fleet-se\bin\serve.mjs" /SC ONLOGON /RL LIMITED
151
+ ```
152
+ De-register:
153
+ ```cmd
154
+ schtasks /Delete /TN "ApraFleetSupervisor" /F
155
+ ```
156
+ Confirm it registered:
157
+ ```cmd
158
+ schtasks /Query /TN "ApraFleetSupervisor"
159
+ ```
160
+
161
+ **Option B -- a Windows service via NSSM** (runs even with nobody logged
162
+ in; requires NSSM installed and on PATH):
163
+
164
+ Register:
165
+ ```cmd
166
+ nssm install ApraFleetSupervisor node "C:\path\to\apra-fleet\packages\apra-fleet-se\bin\serve.mjs"
167
+ nssm set ApraFleetSupervisor AppDirectory "C:\path\to\apra-fleet"
168
+ nssm start ApraFleetSupervisor
169
+ ```
170
+ De-register:
171
+ ```cmd
172
+ nssm stop ApraFleetSupervisor
173
+ nssm remove ApraFleetSupervisor confirm
174
+ ```
175
+
176
+ ### macOS (launchd user LaunchAgent)
177
+
178
+ Create `~/Library/LaunchAgents/com.apra-fleet.supervisor.plist`:
179
+ ```xml
180
+ <?xml version="1.0" encoding="UTF-8"?>
181
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
182
+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
183
+ <plist version="1.0">
184
+ <dict>
185
+ <key>Label</key>
186
+ <string>com.apra-fleet.supervisor</string>
187
+ <key>ProgramArguments</key>
188
+ <array>
189
+ <string>/usr/local/bin/node</string>
190
+ <string>/path/to/apra-fleet/packages/apra-fleet-se/bin/serve.mjs</string>
191
+ </array>
192
+ <key>RunAtLoad</key>
193
+ <true/>
194
+ <key>KeepAlive</key>
195
+ <false/>
196
+ <key>StandardOutPath</key>
197
+ <string>/tmp/apra-fleet-supervisor.log</string>
198
+ <key>StandardErrorPath</key>
199
+ <string>/tmp/apra-fleet-supervisor.log</string>
200
+ </dict>
201
+ </plist>
202
+ ```
203
+ `RunAtLoad` starts it at login; `KeepAlive` is deliberately `false` -- the
204
+ supervisor already runs indefinitely on its own (see section 0), so it does
205
+ not need launchd to respawn it on exit (an explicit `POST /api/shutdown`
206
+ should stay stopped, not bounce back up). launchd runs with a minimal PATH
207
+ (`/usr/bin:/bin:/usr/sbin:/sbin`), so a bare `node` command will not resolve
208
+ if node is installed via Homebrew or a version manager. Use the real path to
209
+ `node` on your system (`which node`) if it differs from `/usr/local/bin/node`.
210
+
211
+ Register (load) and start now:
212
+ ```bash
213
+ launchctl load ~/Library/LaunchAgents/com.apra-fleet.supervisor.plist
214
+ launchctl start com.apra-fleet.supervisor
215
+ ```
216
+ De-register (stop and unload, so it no longer starts at login):
217
+ ```bash
218
+ launchctl stop com.apra-fleet.supervisor
219
+ launchctl unload ~/Library/LaunchAgents/com.apra-fleet.supervisor.plist
220
+ ```
221
+
222
+ ### Linux (systemd --user unit)
223
+
224
+ Create `~/.config/systemd/user/apra-fleet-supervisor.service`:
225
+ ```ini
226
+ [Unit]
227
+ Description=Apra Fleet supervisor
228
+
229
+ [Service]
230
+ ExecStart=/usr/bin/node /path/to/apra-fleet/packages/apra-fleet-se/bin/serve.mjs
231
+ Restart=no
232
+ WorkingDirectory=/path/to/apra-fleet
233
+
234
+ [Install]
235
+ WantedBy=default.target
236
+ ```
237
+ `Restart=no` matches the launchd `KeepAlive=false` choice above: the
238
+ supervisor is already self-persistent (section 0), and an explicit `POST
239
+ /api/shutdown` should stay stopped rather than being auto-respawned by the
240
+ unit. Use the real path to `node` on the target member (`which node`) if it
241
+ differs from `/usr/bin/node`.
242
+
243
+ Register and start:
244
+ ```bash
245
+ systemctl --user daemon-reload
246
+ systemctl --user enable apra-fleet-supervisor.service
247
+ systemctl --user start apra-fleet-supervisor.service
248
+ ```
249
+ De-register (stop and disable, so it no longer starts at login/boot):
250
+ ```bash
251
+ systemctl --user stop apra-fleet-supervisor.service
252
+ systemctl --user disable apra-fleet-supervisor.service
253
+ ```
254
+ A user unit only starts at login unless lingering is enabled for boot-time
255
+ start with no login (`loginctl enable-linger <username>`).
256
+
257
+ ## 1. Before you launch a sprint
258
+
259
+ 1. If you just created/edited beads locally, push them first:
260
+ `bd dolt commit` then `bd dolt push`. Members pull their own copy; a
261
+ sprint launched before the push works from stale scope.
262
+ 2. Check no conflicting sprint is already running: `GET /api/sprints`.
263
+ 3. Multi-member sprints need all members on the SAME git HEAD, or the
264
+ launch crashes immediately with a topology error. If unsure, use ONE
265
+ member. Don't guess a member list -- ask, or default to one.
266
+
267
+ ## 2. Start a sprint
268
+
269
+ ```bash
270
+ curl -s -X POST http://localhost:8787/api/sprints \
271
+ -H "Content-Type: application/json" \
272
+ -d '{
273
+ "issue": "<id[,id2,...]>",
274
+ "branch": "<new-or-existing-branch>",
275
+ "base": "<base-branch>",
276
+ "members": ["<member-name>"],
277
+ "goal": "P1/P2"
278
+ }'
279
+ ```
280
+
281
+ Field names, exactly as the API expects them:
282
+
283
+ | Field | Required | Notes |
284
+ |---|---|---|
285
+ | `issue` | yes | comma-separated bead root IDs (parent/epic OR a standalone leaf bead). Alias: `target_issue`. |
286
+ | `branch` | yes | created from `base` if it doesn't exist yet. |
287
+ | `base` | yes | alias: `base_branch`. This is what the sprint branches FROM -- pass the branch you actually want, not always `main`. |
288
+ | `members` | yes | array of registered member names. One member = safest default. |
289
+ | `goal` | no | `P1`, `P1/P2` (default), or `P1/P2/P3`. |
290
+ | `maxCycles` | no | default 5. |
291
+ | `allowMissingMembers` | no | bool. |
292
+ | `requirementsFile` | no | path. |
293
+ | `roleMap` | no | `{"doer":["m1","m2"], "reviewer":["m3"]}`. |
294
+ | `budget` | no | USD cap. |
295
+ | `overrideRelaunchGate` | no | bool. See below. |
296
+
297
+ Response has `sprintId`, `pid`, `port` (its own dashboard), `logPath`.
298
+ **A 201 response does NOT mean the sprint is alive** -- it can crash in the
299
+ first few seconds (bad topology, bad member, etc). Always verify (step 3)
300
+ a few seconds after launch.
301
+
302
+ ## 3. Check status
303
+
304
+ All live sprints:
305
+ ```bash
306
+ curl -s http://localhost:8787/api/sprints
307
+ ```
308
+ Empty `sprints: []` after a launch = it already died. Check its `logPath`.
309
+
310
+ One sprint (live state, or its terminal record if it finished/crashed):
311
+ ```bash
312
+ curl -s http://localhost:8787/api/sprints/<sprintId>
313
+ ```
314
+
315
+ Sprint-scoped dashboard (per-role activity, bead DAG, cost, PR link):
316
+ `http://localhost:<port>` (the `port` from the launch response).
317
+
318
+ ## 4. Kill a sprint
319
+
320
+ ```bash
321
+ curl -s -X POST http://localhost:8787/api/sprints/<sprintId>/stop
322
+ ```
323
+
324
+ ## Relaunch gate
325
+
326
+ If a prior run of the SAME issue root ended in a deterministic, unaddressed
327
+ failure (crash, sync conflict, etc), a relaunch is refused with a 409. Once
328
+ you understand and have actually fixed the cause, retry with
329
+ `"overrideRelaunchGate": true` in the body. This is not a silent bypass --
330
+ only use it once you know why the prior run died.
331
+
332
+ ## Common launch-time crashes
333
+
334
+ - **Topology mismatch**: members are on different git commits. Fix: use one
335
+ member, or align them first (`git fetch && git checkout <branch>` on
336
+ each), or pass whatever sync option the engine currently exposes -- check
337
+ `docs/architecture.md` "Multi-member topology" section, don't guess.
338
+ - **Unregistered member**: `GET /api/members` to see valid names.
339
+ - **Stale LLM auth**: dispatch fails with `empty_response`. Re-run
340
+ `provision_llm_auth` for that member.
341
+
342
+ ## Member layout: isolate deploy/test roles from dev roles
343
+
344
+ For projects where the deployed software runs and is verified LOCALLY on the
345
+ member, give `deployer`, `integ-test-runner`, and `regression-test-runner` a
346
+ dedicated member with its own independent git clone (not a worktree),
347
+ separate from `planner`/`plan-reviewer`/`doer`/`reviewer`, via `roleMap`:
348
+ `{"deployer": ["<deploy-member>"], "integ-test-runner": ["<deploy-member>"],
349
+ "regression-test-runner": ["<deploy-member>"], "doer": ["<dev-member>"], ...}`.
350
+ Dev roles can all safely share one generic member.
@@ -0,0 +1,101 @@
1
+ // apra-fleet-x8r.1: closed/required bead-count derivation for the
2
+ // beads-closed/required progress-bar widget.
3
+ //
4
+ // Deliberately does NOT re-walk the parent-edge BFS runner.js's
5
+ // bdListScoped()/decomposedParentIds() already perform to discover "what is
6
+ // in scope for this sprint" -- that would be a second, independently
7
+ // maintained definition of "in scope" that could silently drift from the
8
+ // completion gate's own. Instead this takes the ALREADY-SCOPED bead list the
9
+ // caller already has on hand (dashboard.mjs's `sprintTasks`, itself built
10
+ // from `bdListScoped('')` -- see runner.js's updateDashboard()) and only
11
+ // derives the two counts a viewer needs from it: how many of those beads are
12
+ // closed, and how many total. Pure/sync, no I/O -- takes data, returns data.
13
+ //
14
+ // apra-fleet-4p5-style: also embedded verbatim (via `.toString()`) into
15
+ // viewer-extensions.mjs's browser-side `<script>` alongside renderBeadsHtml,
16
+ // so the exact function under test here is the exact function that renders
17
+ // the widget in the browser -- never a hand-duplicated copy.
18
+ //
19
+ // apra-fleet-x8r.4: `required` originally defaulted to `beads.length` --
20
+ // EVERY bead in the sprint's scope, regardless of priority or structure. But
21
+ // runner.js's real completion gate (~line 8134) computes
22
+ // `openAtGoal = bdListScoped('--status=<NOT_DONE> --priority-max=<goalMax>')
23
+ // MINUS decomposedParentIds()`: below-goal-priority beads and decomposed
24
+ // parent (grouping) nodes are NOT part of the required-to-close set that
25
+ // actually gates sprint exit. Left unfiltered, a sprint whose scope contains
26
+ // either could legitimately complete while this widget still showed less
27
+ // than N/N -- the opposite of "how much of this sprint's required work is
28
+ // done". `opts` is ADDITIVE-OPTIONAL (a bare `computeSprintProgress(beads)`
29
+ // call -- e.g. a caller that has not been plumbed a goalMax/decomposed set
30
+ // yet -- keeps its original all-of-scope behavior) so every existing/future
31
+ // call site stays valid without redesigning this signature again.
32
+ //
33
+ // Both fields are plumbed in from the SAME server-side sources runner.js's
34
+ // gate itself uses (goalPriorityMax(validated.goal), decomposedParentIds())
35
+ // -- never re-derived here or client-side, so there is exactly one
36
+ // "what does this sprint still need to close" definition in the package.
37
+
38
+ // apra-fleet-x8r.8: runner.js's partitionByGoalMembership() (eft.52.1.3) can
39
+ // place a below-goal-priority bead in the Sprint section via a documented
40
+ // blocks-edge exception -- a bead that BLOCKS an in-goal bead is admitted
41
+ // into 'sprint' placement even though its own priority is below goalMax. That
42
+ // server-computed decision is tagged verbatim onto the row as `placement`
43
+ // ('sprint' | 'backlog') and is exactly what the beads TREE (renderBeadsHtml)
44
+ // honors when deciding which section a row renders in. Before this fix,
45
+ // computeSprintProgress() re-derived membership from raw numeric priority
46
+ // alone (`priority > goalMax` -> excluded), ignoring `placement` -- so a
47
+ // blocks-exception bead could render as an open Sprint row in the tree while
48
+ // being silently excluded from the 'M/N' count directly above it (the bar
49
+ // reads N/N while a visibly-open row sits right below). Reusing `placement`
50
+ // when present (rather than re-deriving from priority) makes the bar and the
51
+ // tree agree on exactly the same admitted set.
52
+ /**
53
+ * @param {Array<{id?: string, status?: string, priority?: number, placement?: string}>} beads the
54
+ * sprint's already-scoped bead list (e.g. dashboard.mjs's `sprintTasks`,
55
+ * sourced from `bdListScoped('')`)
56
+ * @param {{ goalMax?: number, decomposedParentIds?: Iterable<string> }} [opts]
57
+ * `goalMax` is the NUMERIC worst priority tier named in the sprint's goal
58
+ * (e.g. `goalPriorityMax('P1/P2')` -> `'P2'` -> `goalMax: 2`) -- a bead
59
+ * whose `priority` is a finite number strictly greater than `goalMax` is
60
+ * below-goal and excluded from `required`/`closed`, UNLESS that bead
61
+ * carries a server-computed `placement` field (apra-fleet-eft.52.1.3),
62
+ * in which case `placement` decides membership instead (`'backlog'` ->
63
+ * excluded, anything else, e.g. `'sprint'` -> included) so the bar can
64
+ * never disagree with the tree it sits above (apra-fleet-x8r.8). Rows with
65
+ * no `placement` field (dashboard.mjs's listAllBeads-sourced rows never
66
+ * carry one) fall back to the plain numeric filter, unchanged.
67
+ * `decomposedParentIds` is the set of bead ids that are themselves someone
68
+ * else's `.parent` (any status) -- excluded the same way runner.js's exit
69
+ * gate excludes them, regardless of `placement`.
70
+ * Omitting `opts` (or either field) applies no filtering on that axis,
71
+ * preserving the pre-x8r.4 "every bead in scope" behavior.
72
+ * @returns {{ closed: number, required: number, fraction: number }}
73
+ * `fraction` is `closed / required`, clamped to 0 when `required` is 0
74
+ * (never NaN/Infinity from a divide-by-zero).
75
+ */
76
+ export function computeSprintProgress(beads, opts) {
77
+ const list = Array.isArray(beads) ? beads : [];
78
+ const goalMax = opts && typeof opts.goalMax === 'number' && Number.isFinite(opts.goalMax)
79
+ ? opts.goalMax
80
+ : null;
81
+ const decomposedParentIds = opts && opts.decomposedParentIds
82
+ ? new Set(opts.decomposedParentIds)
83
+ : null;
84
+ const filtered = list.filter((b) => {
85
+ if (!b) return false;
86
+ if (decomposedParentIds && decomposedParentIds.has(b.id)) return false;
87
+ if (typeof b.placement === 'string') {
88
+ // Server-computed placement already decided which section this
89
+ // bead belongs to (including the blocks-edge exception) -- reuse
90
+ // it verbatim instead of re-deriving from priority, so the bar
91
+ // agrees with the tree exactly.
92
+ return b.placement !== 'backlog';
93
+ }
94
+ if (goalMax !== null && typeof b.priority === 'number' && b.priority > goalMax) return false;
95
+ return true;
96
+ });
97
+ const required = filtered.length;
98
+ const closed = filtered.filter((b) => String(b.status).toLowerCase() === 'closed').length;
99
+ const fraction = required > 0 ? closed / required : 0;
100
+ return { closed, required, fraction };
101
+ }
@@ -31,9 +31,22 @@ const GITHUB_API = 'https://api.github.com';
31
31
  const REDACTED = '***REDACTED***';
32
32
  const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
33
33
 
34
- /** Single-quote a string for embedding in a POSIX shell command,
35
- * closing/reopening the quote around any embedded single quotes. */
36
- function shQuote(value) {
34
+ /** Single-quote a string for embedding in a shell command. The built curl
35
+ * command is dispatched through the member's own shell -- POSIX sh/bash
36
+ * closes/reopens the quote around an embedded single quote ('\''), but
37
+ * Windows PowerShell (the shell every Windows member's commands actually
38
+ * run through -- see wrapPowerShellEncoded()/isWindows in
39
+ * src/tools/remove-member.ts) escapes an embedded single quote inside a
40
+ * single-quoted string by DOUBLING it (''), not by backslash-closing. Using
41
+ * the POSIX form on a Windows member breaks the quoting outright (observed
42
+ * live: Publish PR crashing on any title/body containing an apostrophe).
43
+ * `os` is one of resolveMemberOs()'s return values ('windows'/'linux'/
44
+ * 'darwin'); anything other than 'windows' keeps the POSIX behavior
45
+ * byte-identical to before this branch existed. */
46
+ function shQuote(value, os) {
47
+ if (os === 'windows') {
48
+ return `'${String(value).replace(/'/g, "''")}'`;
49
+ }
37
50
  return `'${String(value).replace(/'/g, `'\\''`)}'`;
38
51
  }
39
52
 
@@ -56,7 +69,7 @@ function assertToken(token) {
56
69
  /** Build the GitHub REST "create pull request" curl command.
57
70
  * POST /repos/{owner}/{repo}/pulls -- see
58
71
  * https://docs.github.com/en/rest/pulls/pulls#create-a-pull-request */
59
- function buildGitHubCreatePrCommand({ repo, base, head, title, body, token }) {
72
+ function buildGitHubCreatePrCommand({ repo, base, head, title, body, token, os }) {
60
73
  const safeRepo = assertRepo(repo);
61
74
  const safeToken = assertToken(token);
62
75
  if (!base) throw new Error('ERROR: VCSModule: "base" branch is required to build a create-pull-request command.');
@@ -70,12 +83,12 @@ function buildGitHubCreatePrCommand({ repo, base, head, title, body, token }) {
70
83
 
71
84
  const buildCurl = (authToken) => [
72
85
  'curl -sS -X POST',
73
- `-H ${shQuote(`Authorization: Bearer ${authToken}`)}`,
74
- `-H ${shQuote('Accept: application/vnd.github+json')}`,
75
- `-H ${shQuote('Content-Type: application/json')}`,
76
- `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28')}`,
77
- `-d ${shQuote(payloadJson)}`,
78
- `-w ${shQuote('\n%{http_code}')}`,
86
+ `-H ${shQuote(`Authorization: Bearer ${authToken}`, os)}`,
87
+ `-H ${shQuote('Accept: application/vnd.github+json', os)}`,
88
+ `-H ${shQuote('Content-Type: application/json', os)}`,
89
+ `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28', os)}`,
90
+ `-d ${shQuote(payloadJson, os)}`,
91
+ `-w ${shQuote('\n%{http_code}', os)}`,
79
92
  url,
80
93
  ].join(' ');
81
94
 
@@ -103,7 +116,7 @@ function buildGitHubCreatePrCommand({ repo, base, head, title, body, token }) {
103
116
  * raised (rather than opening a second PR for the same head).
104
117
  * POST /repos/{owner}/{repo}/issues/{issue_number}/comments -- see
105
118
  * https://docs.github.com/en/rest/issues/comments#create-an-issue-comment */
106
- function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, token }) {
119
+ function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, token, os }) {
107
120
  const safeRepo = assertRepo(repo);
108
121
  const safeToken = assertToken(token);
109
122
  if (!issueNumber) throw new Error('ERROR: VCSModule: "issue_number" is required to build a comment command.');
@@ -114,12 +127,12 @@ function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, toke
114
127
 
115
128
  const buildCurl = (authToken) => [
116
129
  'curl -sS -X POST',
117
- `-H ${shQuote(`Authorization: Bearer ${authToken}`)}`,
118
- `-H ${shQuote('Accept: application/vnd.github+json')}`,
119
- `-H ${shQuote('Content-Type: application/json')}`,
120
- `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28')}`,
121
- `-d ${shQuote(payloadJson)}`,
122
- `-w ${shQuote('\n%{http_code}')}`,
130
+ `-H ${shQuote(`Authorization: Bearer ${authToken}`, os)}`,
131
+ `-H ${shQuote('Accept: application/vnd.github+json', os)}`,
132
+ `-H ${shQuote('Content-Type: application/json', os)}`,
133
+ `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28', os)}`,
134
+ `-d ${shQuote(payloadJson, os)}`,
135
+ `-w ${shQuote('\n%{http_code}', os)}`,
123
136
  url,
124
137
  ].join(' ');
125
138
 
@@ -1,4 +1,34 @@
1
1
  import { escapeHtml } from '@apralabs/apra-fleet-workflow/viewer/html-utils';
2
+ import { computeSprintProgress } from './sprint-progress.mjs';
3
+
4
+ /**
5
+ * apra-fleet-x8r.1: pure HTML-string builder for the beads-closed/required
6
+ * progress-bar widget in the single-sprint viewer's extension area. Takes
7
+ * the ALREADY-COMPUTED `{ closed, required, fraction }` shape
8
+ * `computeSprintProgress()` returns -- never re-derives scope or counts
9
+ * itself -- and renders a horizontal bar that fills left-to-right by
10
+ * `fraction`, plus the numeric 'M/N' text. Styled with the viewer's existing
11
+ * `--bg`/`--bg-glass`/`--accent` CSS variables. `required === 0` renders a
12
+ * flat, empty bar and '0/0' text rather than dividing by zero or throwing.
13
+ *
14
+ * @param {{ closed: number, required: number, fraction: number }} progress
15
+ * @returns {string}
16
+ */
17
+ export function renderProgressBarHtml(progress) {
18
+ const p = progress || { closed: 0, required: 0, fraction: 0 };
19
+ const closed = typeof p.closed === 'number' && Number.isFinite(p.closed) ? p.closed : 0;
20
+ const required = typeof p.required === 'number' && Number.isFinite(p.required) ? p.required : 0;
21
+ const fraction = typeof p.fraction === 'number' && Number.isFinite(p.fraction) ? p.fraction : 0;
22
+ const pct = Math.max(0, Math.min(1, fraction)) * 100;
23
+ return (
24
+ '<div class="sprint-progress" style="display: flex; align-items: center; gap: 8px; padding: 8px; font-size: 12px;">' +
25
+ '<div style="flex: 1; height: 8px; background: var(--bg); border: 1px solid var(--bg-glass); border-radius: 4px; overflow: hidden;">' +
26
+ '<div style="width: ' + pct + '%; height: 100%; background: var(--accent);"></div>' +
27
+ '</div>' +
28
+ '<div style="color: #a1a1aa; white-space: nowrap;">' + closed + '/' + required + '</div>' +
29
+ '</div>'
30
+ );
31
+ }
2
32
 
3
33
  /**
4
34
  * Pure HTML-string builder for the beads task tree (apra-fleet-unw.10,
@@ -535,7 +565,22 @@ export function renderBeadsHtml(sprintTasks, backlogTasks, collapsedIds) {
535
565
  return html;
536
566
  }
537
567
 
538
- let html = '<table style="width: 100%; border-collapse: collapse; text-align: left; font-size: 13px;">';
568
+ // apra-fleet-eft.90: a persistent 'M/N' item count at the top of the
569
+ // panel -- N = every rendered bead across BOTH sections (Sprint +
570
+ // Backlog), M = how many of those are not closed (open, in_progress,
571
+ // blocked, etc). Parent and child beads each count as their own item
572
+ // toward both numbers -- these are flat counts over the input arrays
573
+ // themselves, never deduped/collapsed by tree hierarchy (a bead present
574
+ // in `sprintTasks`/`backlogTasks` counts exactly once regardless of how
575
+ // many descendants it has). An empty panel (both lists empty) renders
576
+ // '0/0', never NaN/throwing.
577
+ const countedTasks = sprintTasks.concat(backlogTasks);
578
+ const totalBeadCount = countedTasks.length;
579
+ const openBeadCount = countedTasks.filter((t) => t && (t.status || '').toString().toLowerCase() !== 'closed').length;
580
+ const countHtml = '<div class="beads-count" style="padding: 4px 8px; font-size: 12px; color: #a1a1aa;">' +
581
+ openBeadCount + '/' + totalBeadCount + '</div>';
582
+
583
+ let html = countHtml + '<table style="width: 100%; border-collapse: collapse; text-align: left; font-size: 13px;">';
539
584
  html += '<tr style="border-bottom: 1px solid rgba(255,255,255,0.1);">' +
540
585
  '<th style="padding: 8px;">ID</th><th style="padding: 8px;">Title</th><th style="padding: 8px;">Type</th>' +
541
586
  '<th style="padding: 8px;">Status</th><th style="padding: 8px;">Pri</th><th style="padding: 8px;">Model</th></tr>';
@@ -715,6 +760,8 @@ export const beadsExtension = {
715
760
  ${escapeHtml.toString()}
716
761
  ${renderBeadsHtml.toString()}
717
762
  ${renderResultExtrasHtml.toString()}
763
+ ${computeSprintProgress.toString()}
764
+ ${renderProgressBarHtml.toString()}
718
765
 
719
766
  // apra-fleet-eft.37.3: mounts the auto-sprint verdict badge + PR
720
767
  // link into the header, next to core's generic (unstyled)
@@ -841,7 +888,20 @@ export const beadsExtension = {
841
888
  function renderBeadsPanel() {
842
889
  const container = document.getElementById('extension-beads');
843
890
  if (!container) return;
844
- container.innerHTML = renderBeadsHtml(lastBeadsData.sprintTasks || [], lastBeadsData.backlogTasks || [], collapsedBeadIds);
891
+ // apra-fleet-x8r.1: the progress bar reflects THIS sprint's own
892
+ // scope (sprintTasks -- already the bdListScoped('') scope walk
893
+ // threaded through by runner.js/dashboard.mjs, never re-derived
894
+ // here), not the Backlog list alongside it.
895
+ // apra-fleet-x8r.4: goalMax/decomposedParentIds are runner.js-
896
+ // computed (updateDashboard()'s payload -- the SAME two axes its
897
+ // own completion gate filters on) and threaded through verbatim,
898
+ // never re-derived client-side.
899
+ const progress = computeSprintProgress(lastBeadsData.sprintTasks || [], {
900
+ goalMax: lastBeadsData.goalMax,
901
+ decomposedParentIds: lastBeadsData.decomposedParentIds,
902
+ });
903
+ container.innerHTML = renderProgressBarHtml(progress)
904
+ + renderBeadsHtml(lastBeadsData.sprintTasks || [], lastBeadsData.backlogTasks || [], collapsedBeadIds);
845
905
  }
846
906
 
847
907
  // Single document-level click-delegation listener (same rationale
@@ -18,6 +18,7 @@
18
18
  "test:unit": "node scripts/run-tests.mjs mock",
19
19
  "test:integration": "node scripts/run-tests.mjs real",
20
20
  "test:record": "node scripts/run-tests.mjs record",
21
+ "test:dolt-settle-integration": "node scripts/dolt-settle-integration.mjs",
21
22
  "update-golden": "node -e \"require('child_process').execFileSync(process.execPath,['--test','test/golden-transcript.test.mjs'],{stdio:'inherit',env:{...process.env,UPDATE_GOLDEN:'1'}})\""
22
23
  },
23
24
  "dependencies": {