@apralabs/apra-fleet 0.3.6 → 0.4.0

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 (569) hide show
  1. package/README.md +245 -257
  2. package/dist/agents/backlog-groomer.md +287 -0
  3. package/dist/agents/deployer.md +52 -11
  4. package/dist/agents/doer.md +32 -7
  5. package/dist/agents/integ-test-runner.md +151 -61
  6. package/dist/agents/plan-reviewer.md +74 -17
  7. package/dist/agents/planner.md +94 -14
  8. package/dist/agents/regression-test-runner.md +216 -0
  9. package/dist/agents/reviewer.md +21 -6
  10. package/dist/agents/schemas/backlog-groomer-input.json +35 -0
  11. package/dist/agents/schemas/backlog-groomer-output.json +164 -0
  12. package/dist/agents/schemas/integ-test-runner-output.json +34 -0
  13. package/dist/agents/schemas/regression-test-runner-input.json +15 -0
  14. package/dist/agents/schemas/regression-test-runner-output.json +50 -0
  15. package/dist/agents/schemas/reviewer-output.json +4 -0
  16. package/dist/cli/agent-transform.d.ts +1 -0
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +77 -0
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts +3 -0
  21. package/dist/cli/auth.d.ts.map +1 -1
  22. package/dist/cli/auth.js +181 -5
  23. package/dist/cli/auth.js.map +1 -1
  24. package/dist/cli/config.d.ts +5 -1
  25. package/dist/cli/config.d.ts.map +1 -1
  26. package/dist/cli/config.js +7 -1
  27. package/dist/cli/config.js.map +1 -1
  28. package/dist/cli/dolt-install.d.ts +91 -0
  29. package/dist/cli/dolt-install.d.ts.map +1 -0
  30. package/dist/cli/dolt-install.js +334 -0
  31. package/dist/cli/dolt-install.js.map +1 -0
  32. package/dist/cli/install-guard.d.ts +29 -0
  33. package/dist/cli/install-guard.d.ts.map +1 -0
  34. package/dist/cli/install-guard.js +153 -0
  35. package/dist/cli/install-guard.js.map +1 -0
  36. package/dist/cli/install.d.ts +44 -3
  37. package/dist/cli/install.d.ts.map +1 -1
  38. package/dist/cli/install.js +604 -108
  39. package/dist/cli/install.js.map +1 -1
  40. package/dist/cli/join.d.ts +12 -0
  41. package/dist/cli/join.d.ts.map +1 -0
  42. package/dist/cli/join.js +87 -0
  43. package/dist/cli/join.js.map +1 -0
  44. package/dist/cli/register-member.d.ts +2 -0
  45. package/dist/cli/register-member.d.ts.map +1 -0
  46. package/dist/cli/register-member.js +193 -0
  47. package/dist/cli/register-member.js.map +1 -0
  48. package/dist/cli/restart.d.ts +2 -0
  49. package/dist/cli/restart.d.ts.map +1 -0
  50. package/dist/cli/restart.js +7 -0
  51. package/dist/cli/restart.js.map +1 -0
  52. package/dist/cli/spoke.d.ts +35 -0
  53. package/dist/cli/spoke.d.ts.map +1 -0
  54. package/dist/cli/spoke.js +212 -0
  55. package/dist/cli/spoke.js.map +1 -0
  56. package/dist/cli/start.d.ts +2 -0
  57. package/dist/cli/start.d.ts.map +1 -0
  58. package/dist/cli/start.js +92 -0
  59. package/dist/cli/start.js.map +1 -0
  60. package/dist/cli/status.d.ts +2 -0
  61. package/dist/cli/status.d.ts.map +1 -0
  62. package/dist/cli/status.js +83 -0
  63. package/dist/cli/status.js.map +1 -0
  64. package/dist/cli/stop.d.ts +2 -0
  65. package/dist/cli/stop.d.ts.map +1 -0
  66. package/dist/cli/stop.js +51 -0
  67. package/dist/cli/stop.js.map +1 -0
  68. package/dist/cli/uninstall.d.ts.map +1 -1
  69. package/dist/cli/uninstall.js +109 -9
  70. package/dist/cli/uninstall.js.map +1 -1
  71. package/dist/cli/update.d.ts.map +1 -1
  72. package/dist/cli/update.js +10 -1
  73. package/dist/cli/update.js.map +1 -1
  74. package/dist/cli/workflow-assets.d.ts +37 -0
  75. package/dist/cli/workflow-assets.d.ts.map +1 -0
  76. package/dist/cli/workflow-assets.js +144 -0
  77. package/dist/cli/workflow-assets.js.map +1 -0
  78. package/dist/cli/workflow.d.ts +75 -0
  79. package/dist/cli/workflow.d.ts.map +1 -0
  80. package/dist/cli/workflow.js +397 -0
  81. package/dist/cli/workflow.js.map +1 -0
  82. package/dist/hub-service/activity.d.ts +30 -0
  83. package/dist/hub-service/activity.d.ts.map +1 -0
  84. package/dist/hub-service/activity.js +20 -0
  85. package/dist/hub-service/activity.js.map +1 -0
  86. package/dist/hub-service/audit-log.d.ts +19 -0
  87. package/dist/hub-service/audit-log.d.ts.map +1 -0
  88. package/dist/hub-service/audit-log.js +13 -0
  89. package/dist/hub-service/audit-log.js.map +1 -0
  90. package/dist/hub-service/db/pool.d.ts +19 -0
  91. package/dist/hub-service/db/pool.d.ts.map +1 -0
  92. package/dist/hub-service/db/pool.js +53 -0
  93. package/dist/hub-service/db/pool.js.map +1 -0
  94. package/dist/hub-service/enrollment.d.ts +29 -0
  95. package/dist/hub-service/enrollment.d.ts.map +1 -0
  96. package/dist/hub-service/enrollment.js +48 -0
  97. package/dist/hub-service/enrollment.js.map +1 -0
  98. package/dist/hub-service/envelope-routes.d.ts +46 -0
  99. package/dist/hub-service/envelope-routes.d.ts.map +1 -0
  100. package/dist/hub-service/envelope-routes.js +94 -0
  101. package/dist/hub-service/envelope-routes.js.map +1 -0
  102. package/dist/hub-service/handlers/installers.d.ts +14 -0
  103. package/dist/hub-service/handlers/installers.d.ts.map +1 -0
  104. package/dist/hub-service/handlers/installers.js +8 -0
  105. package/dist/hub-service/handlers/installers.js.map +1 -0
  106. package/dist/hub-service/http-server.d.ts +31 -0
  107. package/dist/hub-service/http-server.d.ts.map +1 -0
  108. package/dist/hub-service/http-server.js +711 -0
  109. package/dist/hub-service/http-server.js.map +1 -0
  110. package/dist/hub-service/hub-jwt.d.ts +30 -0
  111. package/dist/hub-service/hub-jwt.d.ts.map +1 -0
  112. package/dist/hub-service/hub-jwt.js +105 -0
  113. package/dist/hub-service/hub-jwt.js.map +1 -0
  114. package/dist/hub-service/jwt-revocation.d.ts +20 -0
  115. package/dist/hub-service/jwt-revocation.d.ts.map +1 -0
  116. package/dist/hub-service/jwt-revocation.js +18 -0
  117. package/dist/hub-service/jwt-revocation.js.map +1 -0
  118. package/dist/hub-service/machines.d.ts +16 -0
  119. package/dist/hub-service/machines.d.ts.map +1 -0
  120. package/dist/hub-service/machines.js +14 -0
  121. package/dist/hub-service/machines.js.map +1 -0
  122. package/dist/hub-service/main.d.ts +3 -0
  123. package/dist/hub-service/main.d.ts.map +1 -0
  124. package/dist/hub-service/main.js +64 -0
  125. package/dist/hub-service/main.js.map +1 -0
  126. package/dist/hub-service/member-tokens.d.ts +11 -0
  127. package/dist/hub-service/member-tokens.d.ts.map +1 -0
  128. package/dist/hub-service/member-tokens.js +49 -0
  129. package/dist/hub-service/member-tokens.js.map +1 -0
  130. package/dist/hub-service/member-view.d.ts +20 -0
  131. package/dist/hub-service/member-view.d.ts.map +1 -0
  132. package/dist/hub-service/member-view.js +76 -0
  133. package/dist/hub-service/member-view.js.map +1 -0
  134. package/dist/hub-service/members.d.ts +44 -0
  135. package/dist/hub-service/members.d.ts.map +1 -0
  136. package/dist/hub-service/members.js +25 -0
  137. package/dist/hub-service/members.js.map +1 -0
  138. package/dist/hub-service/presence.d.ts +40 -0
  139. package/dist/hub-service/presence.d.ts.map +1 -0
  140. package/dist/hub-service/presence.js +44 -0
  141. package/dist/hub-service/presence.js.map +1 -0
  142. package/dist/hub-service/project-view.d.ts +12 -0
  143. package/dist/hub-service/project-view.d.ts.map +1 -0
  144. package/dist/hub-service/project-view.js +34 -0
  145. package/dist/hub-service/project-view.js.map +1 -0
  146. package/dist/hub-service/projects.d.ts +48 -0
  147. package/dist/hub-service/projects.d.ts.map +1 -0
  148. package/dist/hub-service/projects.js +80 -0
  149. package/dist/hub-service/projects.js.map +1 -0
  150. package/dist/hub-service/relay-queue.d.ts +115 -0
  151. package/dist/hub-service/relay-queue.d.ts.map +1 -0
  152. package/dist/hub-service/relay-queue.js +148 -0
  153. package/dist/hub-service/relay-queue.js.map +1 -0
  154. package/dist/hub-service/session-jwt.d.ts +10 -0
  155. package/dist/hub-service/session-jwt.d.ts.map +1 -0
  156. package/dist/hub-service/session-jwt.js +69 -0
  157. package/dist/hub-service/session-jwt.js.map +1 -0
  158. package/dist/hub-service/usage.d.ts +40 -0
  159. package/dist/hub-service/usage.d.ts.map +1 -0
  160. package/dist/hub-service/usage.js +25 -0
  161. package/dist/hub-service/usage.js.map +1 -0
  162. package/dist/hub-service/users.d.ts +56 -0
  163. package/dist/hub-service/users.d.ts.map +1 -0
  164. package/dist/hub-service/users.js +72 -0
  165. package/dist/hub-service/users.js.map +1 -0
  166. package/dist/hub-service/workspaces.d.ts +20 -0
  167. package/dist/hub-service/workspaces.d.ts.map +1 -0
  168. package/dist/hub-service/workspaces.js +10 -0
  169. package/dist/hub-service/workspaces.js.map +1 -0
  170. package/dist/index.js +179 -132
  171. package/dist/index.js.map +1 -1
  172. package/dist/os/linux.d.ts +13 -0
  173. package/dist/os/linux.d.ts.map +1 -1
  174. package/dist/os/linux.js +62 -3
  175. package/dist/os/linux.js.map +1 -1
  176. package/dist/os/os-commands.d.ts +10 -0
  177. package/dist/os/os-commands.d.ts.map +1 -1
  178. package/dist/os/windows.d.ts +1 -0
  179. package/dist/os/windows.d.ts.map +1 -1
  180. package/dist/os/windows.js +21 -1
  181. package/dist/os/windows.js.map +1 -1
  182. package/dist/paths.d.ts +23 -0
  183. package/dist/paths.d.ts.map +1 -1
  184. package/dist/paths.js +29 -0
  185. package/dist/paths.js.map +1 -1
  186. package/dist/providers/agy.d.ts +9 -2
  187. package/dist/providers/agy.d.ts.map +1 -1
  188. package/dist/providers/agy.js +127 -14
  189. package/dist/providers/agy.js.map +1 -1
  190. package/dist/providers/claude.d.ts +6 -2
  191. package/dist/providers/claude.d.ts.map +1 -1
  192. package/dist/providers/claude.js +248 -9
  193. package/dist/providers/claude.js.map +1 -1
  194. package/dist/providers/codex.d.ts +3 -2
  195. package/dist/providers/codex.d.ts.map +1 -1
  196. package/dist/providers/codex.js +7 -0
  197. package/dist/providers/codex.js.map +1 -1
  198. package/dist/providers/copilot.d.ts +3 -2
  199. package/dist/providers/copilot.d.ts.map +1 -1
  200. package/dist/providers/copilot.js +8 -1
  201. package/dist/providers/copilot.js.map +1 -1
  202. package/dist/providers/gemini.d.ts +3 -2
  203. package/dist/providers/gemini.d.ts.map +1 -1
  204. package/dist/providers/gemini.js +11 -1
  205. package/dist/providers/gemini.js.map +1 -1
  206. package/dist/providers/index.d.ts +1 -0
  207. package/dist/providers/index.d.ts.map +1 -1
  208. package/dist/providers/index.js +3 -0
  209. package/dist/providers/index.js.map +1 -1
  210. package/dist/providers/none.d.ts +51 -0
  211. package/dist/providers/none.d.ts.map +1 -0
  212. package/dist/providers/none.js +103 -0
  213. package/dist/providers/none.js.map +1 -0
  214. package/dist/providers/opencode.d.ts +4 -2
  215. package/dist/providers/opencode.d.ts.map +1 -1
  216. package/dist/providers/opencode.js +49 -0
  217. package/dist/providers/opencode.js.map +1 -1
  218. package/dist/providers/provider.d.ts +79 -1
  219. package/dist/providers/provider.d.ts.map +1 -1
  220. package/dist/providers/provider.js +10 -0
  221. package/dist/providers/provider.js.map +1 -1
  222. package/dist/services/agent-provisioner.d.ts +3 -3
  223. package/dist/services/agent-provisioner.d.ts.map +1 -1
  224. package/dist/services/agent-provisioner.js +12 -5
  225. package/dist/services/agent-provisioner.js.map +1 -1
  226. package/dist/services/auth-socket.d.ts.map +1 -1
  227. package/dist/services/auth-socket.js +2 -0
  228. package/dist/services/auth-socket.js.map +1 -1
  229. package/dist/services/budget-awareness.d.ts +130 -0
  230. package/dist/services/budget-awareness.d.ts.map +1 -0
  231. package/dist/services/budget-awareness.js +129 -0
  232. package/dist/services/budget-awareness.js.map +1 -0
  233. package/dist/services/cloud-sync.d.ts +35 -0
  234. package/dist/services/cloud-sync.d.ts.map +1 -0
  235. package/dist/services/cloud-sync.js +90 -0
  236. package/dist/services/cloud-sync.js.map +1 -0
  237. package/dist/services/context-admission.d.ts +82 -0
  238. package/dist/services/context-admission.d.ts.map +1 -0
  239. package/dist/services/context-admission.js +136 -0
  240. package/dist/services/context-admission.js.map +1 -0
  241. package/dist/services/event-bus.d.ts +27 -0
  242. package/dist/services/event-bus.d.ts.map +1 -0
  243. package/dist/services/event-bus.js +20 -0
  244. package/dist/services/event-bus.js.map +1 -0
  245. package/dist/services/file-chunker.d.ts +38 -0
  246. package/dist/services/file-chunker.d.ts.map +1 -0
  247. package/dist/services/file-chunker.js +63 -0
  248. package/dist/services/file-chunker.js.map +1 -0
  249. package/dist/services/file-transfer-relay.d.ts +55 -0
  250. package/dist/services/file-transfer-relay.d.ts.map +1 -0
  251. package/dist/services/file-transfer-relay.js +115 -0
  252. package/dist/services/file-transfer-relay.js.map +1 -0
  253. package/dist/services/github-app.d.ts.map +1 -1
  254. package/dist/services/github-app.js +1 -0
  255. package/dist/services/github-app.js.map +1 -1
  256. package/dist/services/http-transport.d.ts +25 -0
  257. package/dist/services/http-transport.d.ts.map +1 -0
  258. package/dist/services/http-transport.js +371 -0
  259. package/dist/services/http-transport.js.map +1 -0
  260. package/dist/services/hub-client.d.ts +69 -0
  261. package/dist/services/hub-client.d.ts.map +1 -0
  262. package/dist/services/hub-client.js +217 -0
  263. package/dist/services/hub-client.js.map +1 -0
  264. package/dist/services/jwt.d.ts +17 -0
  265. package/dist/services/jwt.d.ts.map +1 -0
  266. package/dist/services/jwt.js +70 -0
  267. package/dist/services/jwt.js.map +1 -0
  268. package/dist/services/known-sessions.d.ts +8 -0
  269. package/dist/services/known-sessions.d.ts.map +1 -0
  270. package/dist/services/known-sessions.js +40 -0
  271. package/dist/services/known-sessions.js.map +1 -0
  272. package/dist/services/model-pricing.d.ts +36 -0
  273. package/dist/services/model-pricing.d.ts.map +1 -0
  274. package/dist/services/model-pricing.js +108 -0
  275. package/dist/services/model-pricing.js.map +1 -0
  276. package/dist/services/orphan-recovery.d.ts +56 -0
  277. package/dist/services/orphan-recovery.d.ts.map +1 -0
  278. package/dist/services/orphan-recovery.js +111 -0
  279. package/dist/services/orphan-recovery.js.map +1 -0
  280. package/dist/services/pending-responses.d.ts +23 -0
  281. package/dist/services/pending-responses.d.ts.map +1 -0
  282. package/dist/services/pending-responses.js +52 -0
  283. package/dist/services/pending-responses.js.map +1 -0
  284. package/dist/services/registry.d.ts +4 -1
  285. package/dist/services/registry.d.ts.map +1 -1
  286. package/dist/services/registry.js +3 -0
  287. package/dist/services/registry.js.map +1 -1
  288. package/dist/services/relay-context.d.ts +23 -0
  289. package/dist/services/relay-context.d.ts.map +1 -0
  290. package/dist/services/relay-context.js +8 -0
  291. package/dist/services/relay-context.js.map +1 -0
  292. package/dist/services/relay-executor.d.ts +68 -0
  293. package/dist/services/relay-executor.d.ts.map +1 -0
  294. package/dist/services/relay-executor.js +70 -0
  295. package/dist/services/relay-executor.js.map +1 -0
  296. package/dist/services/relay-request.d.ts +65 -0
  297. package/dist/services/relay-request.d.ts.map +1 -0
  298. package/dist/services/relay-request.js +129 -0
  299. package/dist/services/relay-request.js.map +1 -0
  300. package/dist/services/relay-strategy.d.ts +19 -0
  301. package/dist/services/relay-strategy.d.ts.map +1 -0
  302. package/dist/services/relay-strategy.js +111 -0
  303. package/dist/services/relay-strategy.js.map +1 -0
  304. package/dist/services/service-manager/index.d.ts +5 -0
  305. package/dist/services/service-manager/index.d.ts.map +1 -0
  306. package/dist/services/service-manager/index.js +66 -0
  307. package/dist/services/service-manager/index.js.map +1 -0
  308. package/dist/services/service-manager/linux.d.ts +10 -0
  309. package/dist/services/service-manager/linux.d.ts.map +1 -0
  310. package/dist/services/service-manager/linux.js +97 -0
  311. package/dist/services/service-manager/linux.js.map +1 -0
  312. package/dist/services/service-manager/macos.d.ts +10 -0
  313. package/dist/services/service-manager/macos.d.ts.map +1 -0
  314. package/dist/services/service-manager/macos.js +94 -0
  315. package/dist/services/service-manager/macos.js.map +1 -0
  316. package/dist/services/service-manager/types.d.ts +18 -0
  317. package/dist/services/service-manager/types.d.ts.map +1 -0
  318. package/dist/services/service-manager/types.js +5 -0
  319. package/dist/services/service-manager/types.js.map +1 -0
  320. package/dist/services/service-manager/windows.d.ts +10 -0
  321. package/dist/services/service-manager/windows.d.ts.map +1 -0
  322. package/dist/services/service-manager/windows.js +73 -0
  323. package/dist/services/service-manager/windows.js.map +1 -0
  324. package/dist/services/session-registry.d.ts +70 -0
  325. package/dist/services/session-registry.d.ts.map +1 -0
  326. package/dist/services/session-registry.js +91 -0
  327. package/dist/services/session-registry.js.map +1 -0
  328. package/dist/services/singleton.d.ts +15 -0
  329. package/dist/services/singleton.d.ts.map +1 -0
  330. package/dist/services/singleton.js +98 -0
  331. package/dist/services/singleton.js.map +1 -0
  332. package/dist/services/sprint-coordination.d.ts +168 -0
  333. package/dist/services/sprint-coordination.d.ts.map +1 -0
  334. package/dist/services/sprint-coordination.js +564 -0
  335. package/dist/services/sprint-coordination.js.map +1 -0
  336. package/dist/services/ssh.d.ts.map +1 -1
  337. package/dist/services/ssh.js +70 -3
  338. package/dist/services/ssh.js.map +1 -1
  339. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  340. package/dist/services/stall/log-path-resolver.js +8 -1
  341. package/dist/services/stall/log-path-resolver.js.map +1 -1
  342. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  343. package/dist/services/stall/stall-detector.js +39 -7
  344. package/dist/services/stall/stall-detector.js.map +1 -1
  345. package/dist/services/stall/stall-poller.d.ts +16 -0
  346. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  347. package/dist/services/stall/stall-poller.js +136 -18
  348. package/dist/services/stall/stall-poller.js.map +1 -1
  349. package/dist/services/strategy.d.ts.map +1 -1
  350. package/dist/services/strategy.js +55 -5
  351. package/dist/services/strategy.js.map +1 -1
  352. package/dist/services/substitution-engine.d.ts +20 -0
  353. package/dist/services/substitution-engine.d.ts.map +1 -0
  354. package/dist/services/substitution-engine.js +92 -0
  355. package/dist/services/substitution-engine.js.map +1 -0
  356. package/dist/services/task-cleanup.d.ts.map +1 -1
  357. package/dist/services/task-cleanup.js +1 -9
  358. package/dist/services/task-cleanup.js.map +1 -1
  359. package/dist/services/token-issuer.d.ts +47 -0
  360. package/dist/services/token-issuer.d.ts.map +1 -0
  361. package/dist/services/token-issuer.js +63 -0
  362. package/dist/services/token-issuer.js.map +1 -0
  363. package/dist/services/tool-registry.d.ts +3 -0
  364. package/dist/services/tool-registry.d.ts.map +1 -0
  365. package/dist/services/tool-registry.js +139 -0
  366. package/dist/services/tool-registry.js.map +1 -0
  367. package/dist/services/user-config.d.ts +14 -0
  368. package/dist/services/user-config.d.ts.map +1 -1
  369. package/dist/services/user-config.js +55 -0
  370. package/dist/services/user-config.js.map +1 -1
  371. package/dist/services/vcs/types.d.ts +44 -0
  372. package/dist/services/vcs/types.d.ts.map +1 -1
  373. package/dist/skills/fleet-sprint-cli/SKILL.md +103 -0
  374. package/dist/skills/pm/cost.md +3 -0
  375. package/dist/skills/pm/doer-reviewer-loop.md +3 -0
  376. package/dist/tools/check-status.d.ts.map +1 -1
  377. package/dist/tools/check-status.js +8 -2
  378. package/dist/tools/check-status.js.map +1 -1
  379. package/dist/tools/child-id-allocator.d.ts +45 -0
  380. package/dist/tools/child-id-allocator.d.ts.map +1 -0
  381. package/dist/tools/child-id-allocator.js +62 -0
  382. package/dist/tools/child-id-allocator.js.map +1 -0
  383. package/dist/tools/cloud-control.d.ts +2 -2
  384. package/dist/tools/compose-permissions.d.ts +12 -4
  385. package/dist/tools/compose-permissions.d.ts.map +1 -1
  386. package/dist/tools/compose-permissions.js +55 -4
  387. package/dist/tools/compose-permissions.js.map +1 -1
  388. package/dist/tools/dolt-push-mutex.d.ts +44 -0
  389. package/dist/tools/dolt-push-mutex.d.ts.map +1 -0
  390. package/dist/tools/dolt-push-mutex.js +83 -0
  391. package/dist/tools/dolt-push-mutex.js.map +1 -0
  392. package/dist/tools/execute-command.d.ts +11 -1
  393. package/dist/tools/execute-command.d.ts.map +1 -1
  394. package/dist/tools/execute-command.js +22 -5
  395. package/dist/tools/execute-command.js.map +1 -1
  396. package/dist/tools/execute-prompt.d.ts +72 -12
  397. package/dist/tools/execute-prompt.d.ts.map +1 -1
  398. package/dist/tools/execute-prompt.js +962 -71
  399. package/dist/tools/execute-prompt.js.map +1 -1
  400. package/dist/tools/get-member-model-pricing.d.ts +21 -0
  401. package/dist/tools/get-member-model-pricing.d.ts.map +1 -0
  402. package/dist/tools/get-member-model-pricing.js +29 -0
  403. package/dist/tools/get-member-model-pricing.js.map +1 -0
  404. package/dist/tools/list-members.d.ts.map +1 -1
  405. package/dist/tools/list-members.js +39 -7
  406. package/dist/tools/list-members.js.map +1 -1
  407. package/dist/tools/member-detail.d.ts +1 -1
  408. package/dist/tools/member-detail.d.ts.map +1 -1
  409. package/dist/tools/member-detail.js +8 -2
  410. package/dist/tools/member-detail.js.map +1 -1
  411. package/dist/tools/member-reservation.d.ts +29 -0
  412. package/dist/tools/member-reservation.d.ts.map +1 -0
  413. package/dist/tools/member-reservation.js +71 -0
  414. package/dist/tools/member-reservation.js.map +1 -0
  415. package/dist/tools/provision-vcs-auth.d.ts +7 -7
  416. package/dist/tools/provision-vcs-auth.js +1 -1
  417. package/dist/tools/provision-vcs-auth.js.map +1 -1
  418. package/dist/tools/register-member.d.ts +17 -5
  419. package/dist/tools/register-member.d.ts.map +1 -1
  420. package/dist/tools/register-member.js +144 -5
  421. package/dist/tools/register-member.js.map +1 -1
  422. package/dist/tools/remove-member.d.ts +1 -1
  423. package/dist/tools/report-status.d.ts +33 -0
  424. package/dist/tools/report-status.d.ts.map +1 -0
  425. package/dist/tools/report-status.js +44 -0
  426. package/dist/tools/report-status.js.map +1 -0
  427. package/dist/tools/respond-to-message.d.ts +21 -0
  428. package/dist/tools/respond-to-message.d.ts.map +1 -0
  429. package/dist/tools/respond-to-message.js +23 -0
  430. package/dist/tools/respond-to-message.js.map +1 -0
  431. package/dist/tools/send-files.d.ts +3 -0
  432. package/dist/tools/send-files.d.ts.map +1 -1
  433. package/dist/tools/send-files.js +88 -8
  434. package/dist/tools/send-files.js.map +1 -1
  435. package/dist/tools/send-message.d.ts +27 -0
  436. package/dist/tools/send-message.d.ts.map +1 -0
  437. package/dist/tools/send-message.js +46 -0
  438. package/dist/tools/send-message.js.map +1 -0
  439. package/dist/tools/shutdown-server.d.ts +2 -0
  440. package/dist/tools/shutdown-server.d.ts.map +1 -1
  441. package/dist/tools/shutdown-server.js +19 -0
  442. package/dist/tools/shutdown-server.js.map +1 -1
  443. package/dist/tools/update-member.d.ts +8 -8
  444. package/dist/tools/update-member.d.ts.map +1 -1
  445. package/dist/tools/update-member.js +11 -1
  446. package/dist/tools/update-member.js.map +1 -1
  447. package/dist/types.d.ts +15 -3
  448. package/dist/types.d.ts.map +1 -1
  449. package/dist/utils/agent-helpers.d.ts +2 -1
  450. package/dist/utils/agent-helpers.d.ts.map +1 -1
  451. package/dist/utils/agent-helpers.js +7 -2
  452. package/dist/utils/agent-helpers.js.map +1 -1
  453. package/dist/utils/pid-helpers.d.ts +15 -0
  454. package/dist/utils/pid-helpers.d.ts.map +1 -1
  455. package/dist/utils/pid-helpers.js +23 -0
  456. package/dist/utils/pid-helpers.js.map +1 -1
  457. package/dist/utils/process-utils.d.ts +3 -0
  458. package/dist/utils/process-utils.d.ts.map +1 -0
  459. package/dist/utils/process-utils.js +42 -0
  460. package/dist/utils/process-utils.js.map +1 -0
  461. package/dist/utils/prompt-errors.d.ts +2 -1
  462. package/dist/utils/prompt-errors.d.ts.map +1 -1
  463. package/dist/utils/prompt-errors.js +13 -3
  464. package/dist/utils/prompt-errors.js.map +1 -1
  465. package/dist/utils/workspace-trust.d.ts +24 -0
  466. package/dist/utils/workspace-trust.d.ts.map +1 -0
  467. package/dist/utils/workspace-trust.js +35 -0
  468. package/dist/utils/workspace-trust.js.map +1 -0
  469. package/dist/workflows/auto-sprint.js +450 -87
  470. package/package.json +35 -7
  471. package/packages/apra-fleet-client/package.json +26 -0
  472. package/packages/apra-fleet-client/src/client/api.mjs +396 -0
  473. package/packages/apra-fleet-client/src/client/client.mjs +146 -0
  474. package/packages/apra-fleet-client/src/client/errors.mjs +71 -0
  475. package/packages/apra-fleet-client/src/client/factory.mjs +65 -0
  476. package/packages/apra-fleet-client/src/client/server-resolution.mjs +265 -0
  477. package/packages/apra-fleet-client/src/client/transport.mjs +327 -0
  478. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +287 -0
  479. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +89 -0
  480. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +139 -0
  481. package/packages/apra-fleet-se/apra-pm/agents/doer.md +225 -0
  482. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +169 -0
  483. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +316 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +188 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/planner.md +239 -0
  486. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +216 -0
  487. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +174 -0
  488. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-input.json +35 -0
  489. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +164 -0
  490. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-input.json +26 -0
  491. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-output.json +18 -0
  492. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-input.json +19 -0
  493. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +17 -0
  494. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-input.json +25 -0
  495. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +22 -0
  496. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +31 -0
  497. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +18 -0
  498. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-input.json +20 -0
  499. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +61 -0
  500. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-input.json +15 -0
  501. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +30 -0
  502. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-input.json +15 -0
  503. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +50 -0
  504. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-input.json +25 -0
  505. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +38 -0
  506. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +402 -0
  507. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +142 -0
  508. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +157 -0
  509. package/packages/apra-fleet-se/apra-pm/skills/pm/doer-reviewer-loop.md +300 -0
  510. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +121 -0
  511. package/packages/apra-fleet-se/apra-pm/skills/pm/simple-sprint.md +65 -0
  512. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +327 -0
  513. package/packages/apra-fleet-se/apra-pm/skills/pm/worktrees.md +92 -0
  514. package/packages/apra-fleet-se/apra-pm/version.json +3 -0
  515. package/packages/apra-fleet-se/bin/cli.mjs +857 -0
  516. package/packages/apra-fleet-se/bin/serve.mjs +383 -0
  517. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +178 -0
  518. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +914 -0
  519. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +177 -0
  520. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +191 -0
  521. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +151 -0
  522. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +127 -0
  523. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +94 -0
  524. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +1125 -0
  525. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +72 -0
  526. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +339 -0
  527. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +360 -0
  528. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +363 -0
  529. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1244 -0
  530. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +572 -0
  531. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +118 -0
  532. package/packages/apra-fleet-se/fleet-sprint/runner.js +9447 -0
  533. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +103 -0
  534. package/packages/apra-fleet-se/fleet-sprint/sprint-lock.mjs +140 -0
  535. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +435 -0
  536. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +68 -0
  537. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +53 -0
  538. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +146 -0
  539. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/generic-git.mjs +176 -0
  540. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +222 -0
  541. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +218 -0
  542. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +882 -0
  543. package/packages/apra-fleet-se/package.json +28 -0
  544. package/packages/apra-fleet-se/workflow.json +1 -0
  545. package/packages/apra-fleet-workflow/package.json +30 -0
  546. package/packages/apra-fleet-workflow/src/viewer/command-output-cap.mjs +112 -0
  547. package/packages/apra-fleet-workflow/src/viewer/debounced-writer.mjs +153 -0
  548. package/packages/apra-fleet-workflow/src/viewer/html-utils.mjs +31 -0
  549. package/packages/apra-fleet-workflow/src/viewer/index.mjs +1325 -0
  550. package/packages/apra-fleet-workflow/src/viewer/lean-state.mjs +237 -0
  551. package/packages/apra-fleet-workflow/src/viewer/run-state-paths.mjs +130 -0
  552. package/packages/apra-fleet-workflow/src/viewer/sprint-state-paths.mjs +29 -0
  553. package/packages/apra-fleet-workflow/src/workflow/engine.mjs +200 -0
  554. package/packages/apra-fleet-workflow/src/workflow/errors.mjs +146 -0
  555. package/packages/apra-fleet-workflow/src/workflow/index.mjs +1723 -0
  556. package/packages/apra-fleet-workflow/src/workflow/journal.mjs +291 -0
  557. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +99 -0
  558. package/packages/apra-fleet-workflow/src/workflow/vetting.mjs +111 -0
  559. package/scripts/agy-transcript-reader.js +1 -0
  560. package/scripts/fleet-statusline.sh +17 -13
  561. package/skills/fleet/SKILL.md +37 -2
  562. package/skills/fleet/beads.md +14 -7
  563. package/skills/fleet/permissions.md +50 -0
  564. package/skills/fleet/profiles/base-dev.json +1 -0
  565. package/skills/fleet/profiles/base-reviewer.json +1 -0
  566. package/skills/fleet/profiles/node.json +2 -2
  567. package/version.json +1 -1
  568. package/scripts/agy-settings-merge.js +0 -27
  569. /package/{dist → packages/apra-fleet-se/apra-pm}/agents/_shared/GRAPH-SEMANTICS.md +0 -0
@@ -0,0 +1,327 @@
1
+ # Running a Sprint
2
+
3
+ Full lifecycle for a pm sprint on a single project, driven from one session.
4
+
5
+ A sprint is one or more **cycles**. Each cycle runs three phases -- **Plan**,
6
+ **Develop**, **Test** -- then checks the goal; a fourth phase, **Harvest**, runs
7
+ once at sprint close. Setup, requirements, and design happen once before the first
8
+ cycle.
9
+
10
+ ```
11
+ setup -> requirements -> design ->
12
+ repeat cycle (until goal met or cycle ceiling):
13
+ Plan (planner writes tasks to beads -> plan-reviewer loop to APPROVED)
14
+ Develop (doer-review loop: bd ready -> claim -> close, to a clean APPROVED)
15
+ Test (deploy + integration tests, if deploy.md + playbook present)
16
+ goal check -> exit | next cycle
17
+ Harvest (CI watch -> final review -> docs/CHANGELOG -> complete -> PR)
18
+ ```
19
+
20
+ State lives in **beads** (all task state -- the plan, what is open/in-progress/closed,
21
+ acceptance criteria, model tier, review findings) and **git** (the code, the branch
22
+ history, and the requirements/design narrative). There is no PLAN.md and no
23
+ progress.json. See `beads.md` for the task-DB backbone and `worktrees.md` for
24
+ worktree mechanics.
25
+
26
+ ## The cycle loop
27
+
28
+ Run cycles until the **goal** is met or the **cycle ceiling** is reached.
29
+
30
+ - **Goal** -- a priority threshold (default P1/P2; also P1 or P1/P2/P3). The sprint
31
+ is done when no open beads issue in the sprint-root subtree sits at or above it.
32
+ - **Cycle ceiling** -- a hard cap on cycles (default 5) so a sprint can never loop
33
+ unbounded.
34
+
35
+ Each cycle:
36
+
37
+ 1. **Plan** (Phase 3). If planning is already complete -- the sprint root has features and
38
+ every open feature's tasks carry acceptance criteria (`bd show <id>`) -- skip the
39
+ plan loop. First reset any task left `in_progress` by a crashed prior dispatch
40
+ back to `open` (`bd update <id> --status=open`) so no work is orphaned.
41
+ 2. **Develop** (Phase 4). Run the doer-review loop until `bd ready` is empty, no open
42
+ task remains at the goal priority, and the last reviewer verdict was APPROVED (see
43
+ `doer-reviewer-loop.md`).
44
+ 3. **Test** (Phase 5). Deploy and run integration tests, only if both `deploy.md`
45
+ and `integ-test-playbook.md` are present; otherwise skip.
46
+ 4. **Goal check.** Count open issues at or above the goal priority in the sprint-root
47
+ subtree. Zero -> goal met, exit the loop and go to Harvest. Otherwise: if this
48
+ cycle resolved none of the previous cycle's open issues, abort and flag the user
49
+ (no-progress); else start the next cycle.
50
+
51
+ After the loop exits, run **Harvest** once (see Completion).
52
+
53
+ ## Sprint selection
54
+
55
+ Choose the shape before starting:
56
+
57
+ | Condition | Shape |
58
+ |-----------|-------|
59
+ | 1-3 tasks, one sitting, low risk, no phasing | Lightweight (see Lightweight sprint) |
60
+ | Work splits into independent, low-coupling units | Parallel tracks (see Parallel tracks) |
61
+ | Default | Single track, full lifecycle below |
62
+
63
+ Tightly coupled work stays a single track -- splitting it costs more coordination
64
+ than it saves.
65
+
66
+ ## Setup (once per sprint)
67
+
68
+ 1. Detect transport: `git -C <repo> remote` (empty => local-only). This decides the
69
+ `<transport line>` in every dispatch prompt (see `worktrees.md`).
70
+ 2. **Check Node.js** (required for cost quoting): `node --version 2>/dev/null || echo MISSING`.
71
+ If `MISSING`: warn the user that cost quoting is unavailable and skip all cost
72
+ steps for this sprint; everything else runs normally. If present: load or bootstrap
73
+ `sprint-logs/calibration.json` (see `cost.md` Setup check).
74
+ 3. Create the beads sprint root and record its id:
75
+ `bd create "sprint: <name>" -p 1` -> `<sprint-id>` (see `beads.md`).
76
+ 4. Create the track worktree(s) off the base branch (one per track):
77
+ `git -C <repo> worktree add -b <branch> <repo>-wt/<track> <base-ref>`.
78
+
79
+ ## Phase 1 -- Requirements
80
+
81
+ Write `<worktree>/requirements.md` on the track branch. Quality bar: full detail
82
+ (code locations, root causes, impact), risk front-loaded (the riskiest assumption
83
+ must become Task 1 of the plan), no 2-3 line summaries. Commit it with the message
84
+ `plan: write requirements` -- the `plan:` prefix is required (it signals to the
85
+ independent gate checker that the Plan phase ran).
86
+
87
+ ## Phase 2 -- Design
88
+
89
+ When the work involves non-trivial architecture, shared interfaces, or a decision
90
+ with more than one reasonable answer, write `<worktree>/design.md` capturing the
91
+ architecture and the binding decisions, and commit it. The planner consumes it and
92
+ the reviewer checks code against it. For mechanical or single-obvious-path work,
93
+ skip design and note in `requirements.md` that none was needed.
94
+
95
+ ## Phase 3 -- Plan (loop)
96
+
97
+ 1. Dispatch `planner` (inline, premium-tier). It explores, drafts, self-critiques, then
98
+ writes the plan **directly into beads** -- one task per plan item under the sprint root,
99
+ each with `--acceptance="..."` (the reviewer's contract), `--metadata
100
+ '{"model": "<tier>"}'` (cheap-tier for mechanical work, standard-tier for standard implementation,
101
+ premium-tier for hard design), a priority matching the sprint goal, and dependencies
102
+ wired with `bd dep add` (see `beads.md`). It does NOT write PLAN.md.
103
+ 2. Loop, capped at three rounds: dispatch `plan-reviewer` (inline, standard-tier). It
104
+ inspects the beads DAG (`bd graph --compact <sprint-id>`, `bd ready`, `bd show <id>`)
105
+ for coverage, task size, acceptance criteria, dependency direction, and model-tier
106
+ assignment, classifying each task's complexity bucket (S/M/L). Read its returned
107
+ verdict (structured output only -- it never writes a file). `CHANGES NEEDED` ->
108
+ dispatch `planner` to revise the beads tasks -> re-review. `APPROVED` -> continue.
109
+ If three rounds leave the plan unapproved, abort and flag the user.
110
+
111
+ Beads now holds the full execution state -- the tasks, their acceptance criteria,
112
+ their model tiers, and their dependency order. There is no PLAN.md to commit and no
113
+ progress.json to generate; the doer loop reads `bd ready` directly.
114
+
115
+ **After APPROVED (if Node.js is available):** compute and log the sprint cost quote
116
+ using `computeSprintQuote` from `<skillDir>/cost.js` (installed alongside this
117
+ skill; see `cost.md` for the path per provider), then write per-task cost estimates
118
+ back to beads notes. See `cost.md` Phase 3.
119
+
120
+ ## Phase 4 -- Develop
121
+
122
+ Run the doer-review loop in `doer-reviewer-loop.md`. Each iteration: read the ready
123
+ tasks (`bd ready`), group them into model streaks (consecutive tasks sharing a model
124
+ tier, read from each task's beads metadata -- the `model` key in `bd show <id>`,
125
+ never `--notes`), dispatch one `doer` per streak
126
+ on that tier, then one `reviewer` over all worked tasks. The doer claims each task
127
+ (`bd update <id> --claim`), implements, commits, and closes it (`bd close <id>`); the
128
+ orchestrator does not touch beads between doer and reviewer. The reviewer runs
129
+ standard-tier, escalating to premium-tier if any streak this iteration ran premium-tier; on
130
+ CHANGES NEEDED it returns `reopenIds` and `newTasks` as structured output (it never
131
+ writes a file) and the orchestrator runs `bd update <id> --status=open` for each,
132
+ returning them to `bd ready` next iteration (see `beads.md` and
133
+ `doer-reviewer-loop.md`).
134
+
135
+ The Develop phase exits when `bd ready` returns nothing, `bd list --status=open` at
136
+ the goal priority is empty, **and** the last reviewer verdict was APPROVED -- a
137
+ single APPROVED suffices because beads tracks discrete tasks. A CHANGES NEEDED
138
+ reopens tasks; the doer fixes and the loop continues. Do not advance to Test (or
139
+ Harvest) while open tasks remain at the goal priority.
140
+
141
+ ## Phase 5 -- Test
142
+
143
+ Run only when both `deploy.md` and `integ-test-playbook.md` are present in the
144
+ worktree (or repo root / `docs/`); otherwise skip the phase and proceed to the goal
145
+ check. The phase has two steps:
146
+
147
+ 1. **Deploy** -- dispatch `deployer` (standard-tier) with `operation: deploy`. It
148
+ follows `deploy.md` only: deploys the build and runs the smoke test. On
149
+ smoke-test failure, PM skips integration tests this cycle and continues. The
150
+ deployer does NOT touch `integ-test-playbook.md` -- that playbook belongs to
151
+ `integ-test-runner`.
152
+ 2. **Integration tests.** First **enumerate the open features in the sprint-root
153
+ subtree** yourself -- the same subtree the goal-check uses (`bd graph --json
154
+ <sprint-id>` or `bd list --tree <sprint-id>`, then keep `issue_type == feature`,
155
+ `status != closed`). Then dispatch `integ-test-runner` (standard-tier), passing that
156
+ **explicit feature-id list** in the prompt -- not the sprint id for it to re-derive,
157
+ and never the whole DB. Scoping is the orchestrator's job (you have the full sprint
158
+ context); the runner only tests what it is handed. The runner owns
159
+ `integ-test-playbook.md` end to end: it runs the playbook's real functional
160
+ suite (part 1), brings the test sandbox up itself (playbook Setup on the first
161
+ cycle, Reset on later cycles), runs the playbook's smoke scenario and each
162
+ listed feature's tests inside it, closes passing features in beads, files a
163
+ priority-ranked bug for each failure (see `beads.md`), and ALWAYS runs the
164
+ playbook's Teardown before returning. An empty feature list does not skip the
165
+ dispatch: the runner still executes the playbook's two parts as the sprint's
166
+ standing confidence check.
167
+
168
+ If the project ships but has no runbook yet, write `deploy.md` capturing the exact
169
+ execute / verify / rollback steps and `integ-test-playbook.md` capturing Setup /
170
+ Reset / Teardown, and commit them. Deployment that needs remote machines,
171
+ credentials, or shell access beyond the local environment is out of scope for pm
172
+ itself -- note it as a manual or external step in `deploy.md`.
173
+
174
+ ## Completion (Harvest)
175
+
176
+ The cycle loop has exited (goal met or cycle ceiling reached) and every track's
177
+ Develop phase ended on an APPROVED review with no open tasks at the goal priority.
178
+ Run the Harvest phase once. **ALL steps below are mandatory and must complete before
179
+ calling the sprint done.**
180
+
181
+ ```
182
+ MANDATORY CHECKLIST -- verify each before exiting:
183
+ [ ] 1. CI watch dispatched
184
+ [ ] 2. Final reviewer dispatched + APPROVED
185
+ [ ] 3. Harvester dispatched (docs/ or CHANGELOG in branch diff)
186
+ [ ] 4. Cost analysis committed (or skipped if no Node.js)
187
+ [ ] 5. Sprint root + delivered issues closed
188
+ [ ] 6. bd export committed to branch (.beads/*.jsonl updated)
189
+ [ ] 7. Sprint scaffolding (requirements.md, design.md) removed from PR diff
190
+ [ ] 8. PR raised with gh pr create
191
+ ```
192
+
193
+ 1. **CI watch** -- dispatch `ci-watcher` (cheap-tier) to poll CI for the sprint HEAD
194
+ SHA: green / red / not configured / pending. If CI is not configured, file a
195
+ beads task to add it and flag the user. Carry red/not-configured into the PR body
196
+ rather than blocking the harvest.
197
+ 2. **Final review** -- dispatch `reviewer` (premium-tier) over the whole sprint output:
198
+ does it address the original sprint goals, are there gaps or regressions, is it in a
199
+ releasable state for what was completed? `CHANGES NEEDED` -> stop before harvest
200
+ and flag the user. `APPROVED` -> continue.
201
+ 3. **Documentation harvest** -- dispatch `harvester` to extract long-term knowledge
202
+ from requirements.md, design.md, and the beads task tree (`bd list --tree
203
+ <sprint-id>`, `bd show <id>`) into `docs/` and update `CHANGELOG`.
204
+ Structure inside `docs/` is content-driven (e.g. `docs/architecture.md`,
205
+ `docs/features/<name>.md`). Extract: architecture decisions, feature design, key
206
+ trade-offs, API contracts. Do NOT extract: task lists, code-line references, debug
207
+ notes, implementation steps. The harvester commits the `docs/` and `CHANGELOG`
208
+ output to the branch.
209
+ 4. **Cost analysis and calibration update** (if Node.js available) -- run
210
+ `computeSprintAnalysis`, `buildSprintSummary`, and `computeUpdatedCalibration`
211
+ from `<skillDir>/cost.js` (the extracted module installed alongside this skill on
212
+ every provider -- see `cost.md`) to produce `sprint-logs/<branch>-<startedAt>.analysis.md` and
213
+ update `sprint-logs/calibration.json` with actual token data from this sprint.
214
+ Commit both. See `cost.md` Harvest.
215
+ 5. **Close the sprint root and the delivered issues** -- `bd close <sprint-id>`; also close
216
+ any source beads issues this sprint implemented -- the ready backlog items the
217
+ requirement was drawn from -- with `bd close <issue-id> ...`. Closing the sprint root
218
+ alone leaves those open.
219
+ 6. **Persist beads state to branch** -- this step is REQUIRED for the PR to carry
220
+ durable issue-closure evidence. Run:
221
+ ```
222
+ bd export -o <track-worktree>/.beads/issues.jsonl
223
+ git -C <track-worktree> add .beads/issues.jsonl
224
+ git -C <track-worktree> -c user.name='pm' -c user.email='pm@pm.local' \
225
+ commit -m "chore: export beads state"
226
+ ```
227
+ (A bare `bd export` only prints to stdout; you MUST pass `-o <path>` to write the
228
+ file. This step carries the closed state into the PR regardless of backend type.)
229
+ Record the PR link on the sprint root with `bd update <sprint-id> --notes "pr: <url>"`
230
+ once the PR is raised (step 8).
231
+ 7. **Clean sprint scaffolding from the PR** -- the PR's net diff must be product
232
+ only. The tracking files (`requirements.md`, `design.md`) are sprint narrative,
233
+ not product; beads holds the durable task record, and the reviewer's verdict is
234
+ returned as structured output rather than written to a file, so these narrative
235
+ files stay visible in the branch history as proof the loop ran. For each such
236
+ file, decide by whether it existed on the base branch:
237
+ - **Sprint created it** (absent on base): `git rm` it.
238
+ - **The repo already had it** (present on base, the sprint only touched it):
239
+ restore it to base content -- `git checkout <base> -- <file>` -- so the diff
240
+ shows no change. Never delete a file the repo shipped.
241
+
242
+ Commit as the orchestrator identity `pm`. Then VERIFY:
243
+ `git diff --name-only <base>...<branch>` must list no tracking-file name in any
244
+ case. If one remains, repeat until the net diff is product only. (Same drop the
245
+ parallel-track flow does before integrating.)
246
+ 8. **Raise the PR** -- run the PR command directly: open a PR from the (integration)
247
+ branch to the base, then watch checks until CI is green. For a local-only sprint
248
+ there is no PR -- report the branch and its `git diff <base>...<branch>` instead.
249
+ Use `gh pr create --base <base_branch> --head <branch> --title "..." --body "..."`.
250
+ 9. **Do NOT merge.** Surface the PR URL and CI status; await explicit user
251
+ instruction to merge.
252
+ 10. **Remove worktrees** -- `git -C <repo> worktree remove <repo>-wt/<track>` for
253
+ each track once the PR is raised (or the branch is merged).
254
+
255
+ ## Parallel tracks
256
+
257
+ Use multiple tracks when the work splits into independent, low-coupling units. Each
258
+ track runs its OWN full pipeline (`planner` -> `plan-reviewer` -> `doer` ->
259
+ `reviewer`) in its OWN worktree and branch, concurrently with the others.
260
+
261
+ 1. **Contracts first.** Identify shared interfaces (APIs, data models, schemas) up
262
+ front; write them to `contracts.md`, commit to the base branch, and base every
263
+ track worktree on that commit. Contracts are immutable mid-sprint; if one must
264
+ change, that track stops and the orchestrator serializes the revision (one track
265
+ revises; dependents wait until it merges).
266
+ 2. **Fan out.** Create one worktree + branch per track. Run each track's plan loop
267
+ and execute loop independently. Dispatch one pipeline per track and poll them to
268
+ completion within the turn -- track A's reviewer may run while track B's doer
269
+ works -- keeping the turn alive until their results are in. In
270
+ beads, every task carries its track (assignee or label) so the tree shows which
271
+ track owns what.
272
+ 3. **Integrate.** When a track is APPROVED, merge its branch into the integration
273
+ base branch (never the trunk): `git -C <repo> merge <track-branch>`. Merge code
274
+ only -- the per-track narrative files (`requirements.md`, `design.md`) are sprint
275
+ scaffolding for that one track and stay on its branch. Drop them before the merge
276
+ (e.g. `git rm` on the track branch, or resolve the merge in favour of removing
277
+ them) so two tracks never collide on a same-named file. beads holds the
278
+ cross-track task record, so nothing durable is lost. Notify dependent tracks to
279
+ rebase on the updated base.
280
+ 4. **Finish.** When all tracks are merged: raise one PR from the integration branch,
281
+ confirm CI, remove all worktrees.
282
+
283
+ ## Lightweight sprint
284
+
285
+ For 1-3 tasks completable in one sitting, skip the full harness:
286
+
287
+ 1. Write a concise `requirements.md` on the branch and commit.
288
+ 2. Create a small beads sprint root + a task per item.
289
+ 3. Dispatch the `doer` (model sized to the work) for the task(s); it commits.
290
+ 4. Dispatch the `reviewer` (premium-tier); read the verdict. `CHANGES NEEDED` ->
291
+ doer fixes -> re-review. `APPROVED` -> close the beads tasks and the delivered
292
+ source issues, clean the sprint scaffolding from the PR (see Completion step 7 --
293
+ `git rm` sprint-created tracking files, restore any the repo already shipped, then
294
+ verify the net diff is product only) and commit as `pm`, raise the PR (or
295
+ report the diff for local-only), remove the worktree.
296
+
297
+ No harness files; beads + git carry the state. Promote to a full sprint if the work
298
+ turns out larger than expected.
299
+
300
+ ## Recovery after an orchestrator restart
301
+
302
+ State is in beads and git -- no status file, no memory, no progress.json. To
303
+ re-orient:
304
+
305
+ 1. `bd list --status=open` + `bd list --status=in_progress` + `bd ready` (or
306
+ `bd list --tree <sprint-id>`) -- what is open, claimed, and unblocked. Beads
307
+ reflects claim/close actions, not on-disk completion, so confirm against git next.
308
+ 2. Per track worktree: `git -C <repo> log --oneline <base>..<branch>` (what is
309
+ committed). The reviewer's verdict is returned as structured output, not written
310
+ to a file -- if the orchestrator crashed before applying it, there is no verdict
311
+ to recover; treat any task last known to be under review as needing a fresh
312
+ `reviewer` dispatch.
313
+ 3. `git -C <repo> -C <worktree> status` -- uncommitted changes?
314
+
315
+ Then act:
316
+
317
+ - **Task `in_progress` with no matching commits** -> orphaned claim from a crashed
318
+ dispatch; reset it (`bd update <id> --status=open`) and re-dispatch the doer.
319
+ - **VERIFY reached, no review yet** -> dispatch the reviewer now.
320
+ - **Ready tasks remain, working tree clean** -> dispatch the doer for the next ready
321
+ task (its model tier from `bd show <id>`).
322
+ - **Idle, no progress** -> re-dispatch from the next ready task.
323
+ - **Uncommitted work of unknown origin, or beads and git disagree** -> STOP and flag
324
+ the user; do not guess.
325
+
326
+ Each dispatch reads its context from beads + git, so recovery is just "read beads +
327
+ git, dispatch the right next role." Every dispatch starts fresh from that state.
@@ -0,0 +1,92 @@
1
+ # Worktrees -- topology, parallel tracks, lifecycle, transport
2
+
3
+ pm isolates parallel work with git worktrees. A worktree is a second checkout
4
+ of the same repository sharing one `.git` object database. That shared object DB is
5
+ what makes worktrees the right tool: a commit made in one worktree is instantly
6
+ visible from every other worktree and from the orchestrator.
7
+
8
+ ## Topology: one worktree per track
9
+
10
+ A track is one independent unit of work with its own branch, worktree, and full
11
+ pipeline (`planner` -> `plan-reviewer` -> `doer` -> `reviewer`).
12
+
13
+ ```
14
+ repo/ <- base checkout; the orchestrator runs git from here
15
+ .git/ <- shared object DB and refs
16
+ repo-wt/
17
+ track-1/ [feat/x-track-1] <- track 1's full pipeline runs here
18
+ track-2/ [feat/x-track-2] <- track 2's full pipeline runs here, concurrently
19
+ ```
20
+
21
+ Rules that fall out of how git works:
22
+
23
+ - **One branch per worktree.** Git forbids checking out the same branch in two
24
+ worktrees. Each track owns exactly one branch in exactly one worktree.
25
+ - **A track's four roles share its worktree, sequentially.** Planner, plan-reviewer,
26
+ doer, and reviewer for one track never run at the same instant -- the plan loop
27
+ precedes the execute loop, and within the execute loop the doer stops at a VERIFY
28
+ checkpoint before the reviewer is dispatched. Each reads the committed files in
29
+ place.
30
+ - **Parallelism is across tracks.** Two tracks = two worktrees = two full pipelines
31
+ running concurrently, unable to touch each other's files. This is the entire
32
+ reason to use worktrees: file isolation for concurrent work.
33
+
34
+ Use a single track unless the work splits into genuinely independent, low-coupling
35
+ units (see `sprint.md` Parallel tracks). A single track is one worktree and is the
36
+ common case.
37
+
38
+ ## Lifecycle (the orchestrator owns this via git)
39
+
40
+ Create, off the base branch, before dispatching a track:
41
+
42
+ ```
43
+ git -C <repo> fetch origin # if a remote exists; skip if local-only
44
+ git -C <repo> worktree add -b <branch> <repo>-wt/<track> <base-ref>
45
+ ```
46
+
47
+ `<base-ref>` is `origin/<base>` when a remote exists, or the local `<base>` branch
48
+ otherwise. For multiple tracks, create one worktree per track off the same base.
49
+
50
+ List / inspect at any time:
51
+
52
+ ```
53
+ git -C <repo> worktree list
54
+ git -C <repo> log --oneline <base>..<branch> # what a track's doer has committed
55
+ git -C <repo> diff <base>...<branch> # a track's review surface
56
+ ```
57
+
58
+ Remove at cleanup (after the PR is raised, or after the track merges into the
59
+ integration branch):
60
+
61
+ ```
62
+ git -C <repo> worktree remove <repo>-wt/<track>
63
+ git -C <repo> branch -d <branch> # after merge; -D to force-discard
64
+ ```
65
+
66
+ If a worktree's `.git` pointer gets corrupted (can happen when a POSIX shell layer
67
+ touches a Windows worktree), repair it: `git -C <repo> worktree repair`.
68
+
69
+ ## Transport between roles
70
+
71
+ Because all worktrees share the object DB, every handoff -- planner to plan-reviewer,
72
+ doer to reviewer, track to integration branch -- needs no network. An agent commits
73
+ to its track's branch; the orchestrator and the next agent see those commits
74
+ immediately via `git log <branch>` / `git diff <base>...<branch>`.
75
+
76
+ Tell each dispatched agent in its prompt whether a remote exists:
77
+
78
+ - **Remote present:** the agent may push its commits; pushing is harmless and gives
79
+ durability and a PR target.
80
+ - **Local-only:** the agent commits every turn and skips pushing; the shared object
81
+ DB already carries the work to every other worktree and to the orchestrator.
82
+
83
+ Detect once at the start: `git -C <repo> remote` (empty output means local-only).
84
+
85
+ ## Named, persistent worktrees
86
+
87
+ Each track's worktree is named and persistent: a stable path, an explicit lifecycle
88
+ (created before the track starts, removed at cleanup), and shared by the track's
89
+ four roles across the whole pipeline. This matters because a track is dispatched
90
+ many times -- the plan loop, then phase after phase, plus CHANGES NEEDED cycles --
91
+ and successive roles read the same working tree. The worktree lives for the whole
92
+ life of the track so each dispatch lands in the same place.
@@ -0,0 +1,3 @@
1
+ {
2
+ "version": "0.1.1"
3
+ }