@apralabs/apra-fleet 0.4.4 → 0.4.5

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 (268) hide show
  1. package/README.md +49 -4
  2. package/dist/agents/backlog-groomer.md +5 -0
  3. package/dist/agents/ci-watcher.md +5 -0
  4. package/dist/agents/deployer.md +20 -2
  5. package/dist/agents/doer.md +38 -2
  6. package/dist/agents/harvester.md +12 -9
  7. package/dist/agents/integ-test-runner.md +5 -0
  8. package/dist/agents/kb-reconciler.md +6 -0
  9. package/dist/agents/plan-reviewer.md +5 -0
  10. package/dist/agents/planner.md +5 -0
  11. package/dist/agents/regression-test-runner.md +5 -0
  12. package/dist/agents/reviewer.md +67 -15
  13. package/dist/agents/schemas/deployer-output.json +5 -0
  14. package/dist/agents/schemas/doer-output.json +78 -2
  15. package/dist/agents/schemas/reviewer-output.json +104 -2
  16. package/dist/cli/auth.js +5 -1
  17. package/dist/cli/beads-pin.js +6 -7
  18. package/dist/cli/claude-mod.d.ts +75 -0
  19. package/dist/cli/claude-mod.js +288 -0
  20. package/dist/cli/dolt-install.d.ts +1 -1
  21. package/dist/cli/dolt-install.js +5 -1
  22. package/dist/cli/fleet-se-guard.d.ts +8 -0
  23. package/dist/cli/fleet-se-guard.js +19 -3
  24. package/dist/cli/install-guard.d.ts +9 -0
  25. package/dist/cli/install-guard.js +24 -0
  26. package/dist/cli/install.d.ts +12 -0
  27. package/dist/cli/install.js +180 -20
  28. package/dist/cli/kb-profile.d.ts +16 -0
  29. package/dist/cli/kb-profile.js +81 -0
  30. package/dist/cli/start.js +3 -0
  31. package/dist/cli/uninstall.js +13 -3
  32. package/dist/cli/update.d.ts +4 -0
  33. package/dist/cli/update.js +19 -3
  34. package/dist/commands/kb-server.d.ts +10 -1
  35. package/dist/commands/kb-server.js +285 -11
  36. package/dist/index.js +22 -1
  37. package/dist/os/git-executable.d.ts +57 -0
  38. package/dist/os/git-executable.js +85 -0
  39. package/dist/os/go-concurrency.d.ts +44 -0
  40. package/dist/os/go-concurrency.js +53 -0
  41. package/dist/os/index.d.ts +1 -0
  42. package/dist/os/index.js +1 -0
  43. package/dist/os/linux.d.ts +2 -0
  44. package/dist/os/linux.js +10 -1
  45. package/dist/os/os-commands.d.ts +25 -0
  46. package/dist/os/os-commands.js +2 -0
  47. package/dist/os/windows-executable.d.ts +53 -0
  48. package/dist/os/windows-executable.js +185 -0
  49. package/dist/os/windows-gitbash.d.ts +23 -14
  50. package/dist/os/windows-gitbash.js +40 -16
  51. package/dist/os/windows.d.ts +2 -0
  52. package/dist/os/windows.js +37 -6
  53. package/dist/paths.d.ts +10 -1
  54. package/dist/paths.js +19 -2
  55. package/dist/services/agy-project.d.ts +7 -1
  56. package/dist/services/agy-project.js +7 -2
  57. package/dist/services/auth-socket.d.ts +18 -0
  58. package/dist/services/auth-socket.js +30 -4
  59. package/dist/services/credential-store.d.ts +33 -0
  60. package/dist/services/credential-store.js +79 -2
  61. package/dist/services/http-transport.d.ts +29 -0
  62. package/dist/services/http-transport.js +166 -37
  63. package/dist/services/kb-tool-profile.d.ts +36 -0
  64. package/dist/services/kb-tool-profile.js +88 -0
  65. package/dist/services/knowledge/bible-blob-id.js +10 -1
  66. package/dist/services/knowledge/bible-import.d.ts +108 -0
  67. package/dist/services/knowledge/bible-import.js +137 -4
  68. package/dist/services/knowledge/file-hash.js +6 -5
  69. package/dist/services/knowledge/http-provider.d.ts +303 -20
  70. package/dist/services/knowledge/http-provider.js +795 -125
  71. package/dist/services/knowledge/kb-config.d.ts +65 -1
  72. package/dist/services/knowledge/kb-config.js +143 -3
  73. package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
  74. package/dist/services/knowledge/kb-http-auth-state.js +40 -0
  75. package/dist/services/knowledge/kb-providers.d.ts +9 -2
  76. package/dist/services/knowledge/kb-providers.js +67 -37
  77. package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
  78. package/dist/services/knowledge/kb-self.d.ts +122 -9
  79. package/dist/services/knowledge/kb-self.js +196 -36
  80. package/dist/services/knowledge/member-bible-view.js +16 -3
  81. package/dist/services/knowledge/path-validation.d.ts +7 -0
  82. package/dist/services/knowledge/path-validation.js +11 -0
  83. package/dist/services/knowledge/project-slug.js +3 -2
  84. package/dist/services/knowledge/repository-header.d.ts +77 -0
  85. package/dist/services/knowledge/repository-header.js +233 -0
  86. package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
  87. package/dist/services/knowledge/require-sqlite-project.js +1 -1
  88. package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
  89. package/dist/services/knowledge/sqlite-provider.js +416 -4
  90. package/dist/services/knowledge/types.d.ts +15 -2
  91. package/dist/services/member-busy.d.ts +12 -0
  92. package/dist/services/member-busy.js +20 -0
  93. package/dist/services/member-config-io.d.ts +3 -2
  94. package/dist/services/member-config-io.js +7 -4
  95. package/dist/services/member-fleet-install.js +1 -0
  96. package/dist/services/member-tool-allowlist.d.ts +1 -1
  97. package/dist/services/member-tool-allowlist.js +8 -4
  98. package/dist/services/port-holder.js +2 -1
  99. package/dist/services/service-manager/types.d.ts +17 -1
  100. package/dist/services/service-manager/windows.d.ts +7 -2
  101. package/dist/services/service-manager/windows.js +28 -11
  102. package/dist/services/service-notice.d.ts +7 -0
  103. package/dist/services/service-notice.js +19 -0
  104. package/dist/services/session-registry.d.ts +13 -0
  105. package/dist/services/session-registry.js +13 -0
  106. package/dist/services/session-roots.d.ts +67 -0
  107. package/dist/services/session-roots.js +126 -0
  108. package/dist/services/statusline.d.ts +21 -0
  109. package/dist/services/statusline.js +97 -1
  110. package/dist/services/supervisor-service-cleanup.js +2 -1
  111. package/dist/services/tool-registry.js +108 -20
  112. package/dist/services/tool-scope.d.ts +34 -1
  113. package/dist/services/tool-scope.js +27 -2
  114. package/dist/services/vcs/azure-devops.js +10 -0
  115. package/dist/services/vcs/bitbucket.d.ts +22 -1
  116. package/dist/services/vcs/bitbucket.js +163 -17
  117. package/dist/services/vcs/types.d.ts +25 -2
  118. package/dist/services/watch/project-resolver.js +2 -1
  119. package/dist/skills/pm/cost.md +5 -1
  120. package/dist/skills/pm/index.md +9 -9
  121. package/dist/skills/pm/sprint.md +2 -1
  122. package/dist/tools/check-status.d.ts +51 -0
  123. package/dist/tools/check-status.js +124 -12
  124. package/dist/tools/code-intelligence-freshness.js +1 -1
  125. package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
  126. package/dist/tools/code-intelligence-gitnexus.js +166 -9
  127. package/dist/tools/code-intelligence-readiness.d.ts +58 -1
  128. package/dist/tools/code-intelligence-readiness.js +93 -8
  129. package/dist/tools/code-intelligence-reindex.d.ts +25 -1
  130. package/dist/tools/code-intelligence-reindex.js +76 -4
  131. package/dist/tools/code-intelligence.d.ts +1 -1
  132. package/dist/tools/code-intelligence.js +1 -1
  133. package/dist/tools/execute-command.js +14 -8
  134. package/dist/tools/execute-prompt.js +6 -2
  135. package/dist/tools/fleet-snapshot.d.ts +21 -0
  136. package/dist/tools/fleet-snapshot.js +78 -0
  137. package/dist/tools/kb-bible-commit.d.ts +25 -11
  138. package/dist/tools/kb-bible-commit.js +142 -33
  139. package/dist/tools/kb-capture.d.ts +2 -2
  140. package/dist/tools/kb-context.js +47 -27
  141. package/dist/tools/kb-demote.d.ts +27 -0
  142. package/dist/tools/kb-demote.js +37 -0
  143. package/dist/tools/kb-export.d.ts +35 -3
  144. package/dist/tools/kb-export.js +56 -13
  145. package/dist/tools/kb-feedback.d.ts +2 -0
  146. package/dist/tools/kb-feedback.js +17 -7
  147. package/dist/tools/kb-harvest.js +28 -9
  148. package/dist/tools/kb-import.d.ts +18 -2
  149. package/dist/tools/kb-import.js +24 -9
  150. package/dist/tools/kb-invalidate.d.ts +11 -3
  151. package/dist/tools/kb-invalidate.js +80 -7
  152. package/dist/tools/kb-list.js +38 -10
  153. package/dist/tools/kb-promote.js +6 -4
  154. package/dist/tools/kb-query.d.ts +3 -0
  155. package/dist/tools/kb-query.js +181 -37
  156. package/dist/tools/kb-session-prime.d.ts +4 -4
  157. package/dist/tools/kb-session-prime.js +89 -9
  158. package/dist/tools/kb-setup.d.ts +20 -0
  159. package/dist/tools/kb-setup.js +149 -11
  160. package/dist/tools/list-members.js +1 -1
  161. package/dist/tools/member-detail.js +7 -3
  162. package/dist/tools/provision-vcs-auth.d.ts +28 -3
  163. package/dist/tools/provision-vcs-auth.js +53 -7
  164. package/dist/tools/receive-files.js +7 -4
  165. package/dist/tools/send-files.js +5 -4
  166. package/dist/tools/send-message.d.ts +3 -0
  167. package/dist/tools/send-message.js +15 -2
  168. package/dist/tools/stop-prompt.js +3 -1
  169. package/dist/tools/vcs-credential-exec.d.ts +45 -3
  170. package/dist/tools/vcs-credential-exec.js +90 -11
  171. package/dist/utils/process-utils.js +5 -1
  172. package/dist/utils/redact-known-secrets.d.ts +17 -0
  173. package/dist/utils/redact-known-secrets.js +70 -0
  174. package/dist/utils/skill-matrix.js +1 -1
  175. package/dist/utils/vcs-provider-detect.js +2 -2
  176. package/dist/workflows/auto-sprint.js +245 -9
  177. package/package.json +10 -7
  178. package/packages/apra-fleet-client/package.json +1 -1
  179. package/packages/apra-fleet-client/src/client/api.mjs +172 -19
  180. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
  181. package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
  182. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
  183. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
  184. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
  185. package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
  186. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
  187. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
  188. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
  189. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
  190. package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
  191. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
  192. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
  193. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
  194. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
  195. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
  196. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
  197. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
  198. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
  199. package/packages/apra-fleet-se/bin/cli.mjs +104 -31
  200. package/packages/apra-fleet-se/bin/serve.mjs +46 -8
  201. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
  202. package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
  203. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
  204. package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
  205. package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
  206. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
  207. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
  208. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
  209. package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
  210. package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
  211. package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
  212. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
  213. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
  214. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
  215. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
  216. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
  217. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
  218. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
  219. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
  220. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
  221. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
  222. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
  223. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
  224. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
  225. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
  226. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
  227. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
  228. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
  229. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
  230. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
  231. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
  232. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
  233. package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
  234. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
  235. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
  236. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
  237. package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
  238. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
  239. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
  240. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
  241. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
  242. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
  243. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
  244. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
  245. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
  246. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
  247. package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
  248. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
  249. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
  250. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
  251. package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
  252. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
  253. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
  254. package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
  255. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
  256. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
  257. package/packages/apra-fleet-workflow/package.json +2 -1
  258. package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
  259. package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
  261. package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
  262. package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
  263. package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
  264. package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
  265. package/skills/fleet/auth-bitbucket.md +47 -20
  266. package/skills/fleet/onboarding.md +1 -1
  267. package/skills/fleet/skill-matrix.md +3 -3
  268. package/version.json +1 -1
@@ -203,9 +203,13 @@ export async function runPlanPhase({
203
203
  // prior-round session by explicit session id so a re-plan keeps
204
204
  // warm context. False on the first round of any cycle
205
205
  // (roundSessions never resumes across cycles). The
206
- // max_turns-exhaustion path overrides this to `resume: true` --
207
- // an in-dispatch continuation of the session just run,
208
- // orthogonal to cross-round resume.
206
+ // max_turns-exhaustion path does not use this value: its
207
+ // secondary dispatch resumes the EXHAUSTED attempt's own session
208
+ // by the explicit id reported on its error (resume:
209
+ // "<exhausted session id>"), or starts a fresh session with the
210
+ // full prompt when no id was reported or the server answers
211
+ // session_not_found -- an in-dispatch continuation, orthogonal
212
+ // to cross-round resume.
209
213
  resumeArg: roundSessions.resumeArgFor('planner', cycle),
210
214
  onSessionId: (id, meta) => roundSessions.record('planner', cycle, id, meta),
211
215
  attemptOptions: ({ attempt }) => ({
@@ -77,7 +77,7 @@ import { buildSprintPrBody, buildSprintPrTitle } from '../pr-body.mjs';
77
77
  * issue(s) directly when the verdict passed.
78
78
  *
79
79
  * @param {object} state Explicit phase state; see this file's header.
80
- * @returns {Promise<{ pushed: boolean }>} Whether the sprint branch actually
80
+ * @returns {Promise<{ pushed: boolean, prSkipped?: { reason: string, message: string } }>} Whether the sprint branch actually
81
81
  * reached the remote. runner.js folds this straight into runSprintCycle's
82
82
  * return value -- it never overrides the sprint's own computed verdict.
83
83
  */
@@ -102,6 +102,12 @@ export async function runPublishPrPhase({
102
102
  finalVerdictResult,
103
103
  // Engine-computed cost block from ./harvest.mjs, rendered in the PR body.
104
104
  costAnalysis = '',
105
+ // The run's set-aside records (../set-aside.mjs collectSetAsideEntries),
106
+ // rendered as the "Set aside this run" section; omitted when empty.
107
+ setAside = [],
108
+ // The run's wait records (../set-aside.mjs collectWaitEntries), rendered
109
+ // as one "Waited this run" line; omitted when empty.
110
+ waited = [],
105
111
  }) {
106
112
  phase(`Publish PR C${finalCycleLabel}`);
107
113
  // The branch push is the LAST step of a sprint that has already done all of
@@ -202,25 +208,27 @@ export async function runPublishPrPhase({
202
208
  const publishPrCapabilities = vcsCapabilities(originUrl);
203
209
  const hostedRemote = publishPrCapabilities.canOpenPullRequest;
204
210
 
205
- if (!hostedRemote) {
206
- log(`Publish PR: origin remote '${originUrl || '(unresolved)'}' cannot open a pull request (host: ${publishPrCapabilities.host || 'unknown'}) -- ` +
207
- 'skipping PR creation entirely (no dependency on any VCS provider\'s auth for this path).');
208
- // A non-hosted remote can never complete PR creation, so target-issue
209
- // closure cannot be gated on it -- close the target issue(s) directly,
210
- // but only when the sprint's own final verdict actually passed. A FAIL
211
- // verdict must never be masked by closing the issue anyway; it still
212
- // ends the sprint 'failed' via the return value below, same as the
213
- // hosted-remote path.
211
+ // With no PR possible, target-issue closure cannot be gated on one --
212
+ // close the target issue(s) directly, but only when the sprint's own final
213
+ // verdict actually passed. A FAIL verdict must never be masked by closing
214
+ // the issue anyway; it still ends the sprint 'failed' via the return value
215
+ // below, same as the PR path. `why` names the no-PR cause in the log.
216
+ // Typed marker (field `prSkipped`) for a push that succeeded but whose PR
217
+ // was not raised because of a VCS auth failure (the credentialAbsent branch
218
+ // closes targets directly by design and stays unmarked); runner.js folds it
219
+ // into the run result (verdict untouched) and the final summary line.
220
+ let prSkipped = null;
221
+ const closeTargetsDirectly = async (why) => {
214
222
  if (finalVerdictResult.verdict === 'PASS') {
215
223
  for (const id of targetIssues) {
216
224
  const closeRes = await command(`bd close ${id}`, {
217
225
  member_name: backlogMember,
218
226
  silent: true,
219
227
  failSoft: true,
220
- label: `Close target issue '${id}' directly (non-hosted remote, no PR gate)`,
228
+ label: `Close target issue '${id}' directly (${why}, no PR gate)`,
221
229
  });
222
230
  if (closeRes.ok) {
223
- log(`Publish PR: closed target issue '${id}' directly (non-hosted remote, PASS verdict).`);
231
+ log(`Publish PR: closed target issue '${id}' directly (${why}, PASS verdict).`);
224
232
  } else {
225
233
  log(`Publish PR: failed to close target issue '${id}' directly (non-fatal, continuing): ${closeRes.error}`);
226
234
  }
@@ -229,6 +237,12 @@ export async function runPublishPrPhase({
229
237
  } else {
230
238
  log('Publish PR: final verdict is FAIL -- leaving target issue(s) open (not closing on a non-PASS verdict).');
231
239
  }
240
+ };
241
+
242
+ if (!hostedRemote) {
243
+ log(`Publish PR: origin remote '${originUrl || '(unresolved)'}' cannot open a pull request (host: ${publishPrCapabilities.host || 'unknown'}) -- ` +
244
+ 'skipping PR creation entirely (no dependency on any VCS provider\'s auth for this path).');
245
+ await closeTargetsDirectly('non-hosted remote');
232
246
  } else {
233
247
  // finalVerdictResult.notes is LLM-authored free text. It used to go
234
248
  // through sanitizePrText() (a single-line shell-argument sanitizer
@@ -254,6 +268,8 @@ export async function runPublishPrPhase({
254
268
  validated.skipRegression ? 'Regression pass: skipped by launch option -- not run this sprint.' : null,
255
269
  lowerQualityBanner || null,
256
270
  ],
271
+ setAside,
272
+ waited,
257
273
  costAnalysis,
258
274
  previousBody,
259
275
  });
@@ -315,7 +331,15 @@ export async function runPublishPrPhase({
315
331
  updateExisting: ({ body: oldBody }) => ({ title: prTitle, body: buildBody(oldBody) }),
316
332
  });
317
333
  if (!prResult.ok) {
318
- if (prResult.authFailure) {
334
+ if (prResult.credentialAbsent) {
335
+ // No PR credential is deployed at all for a provider whose
336
+ // credential is out-of-band only, so no PR is possible:
337
+ // keep the no-PR behaviour (close targets directly on
338
+ // PASS) instead of leaving them open with nothing to gate
339
+ // on. A deployed-but-failing credential is the branch below.
340
+ log(`[Publish PR Skipped] NO pull request was opened for branch '${validated.branch}' -> '${validated.baseBranch}' (branch is pushed): no PR credential is deployed -- closing target issue(s) directly on PASS as for a remote that cannot open a PR. Deploy a credential to get PRs: ${prResult.error}`);
341
+ await closeTargetsDirectly('no PR credential deployed');
342
+ } else if (prResult.authFailure) {
319
343
  // apra-fleet-5co8.15: an auth failure raiseVcsPrForMember
320
344
  // could not clear -- including one that never got past
321
345
  // credential provisioning, e.g. a missing Azure DevOps PAT
@@ -325,6 +349,7 @@ export async function runPublishPrPhase({
325
349
  // outcome (see ../abort.mjs). The branch is already pushed; only
326
350
  // the PR itself is skipped.
327
351
  log(`[Publish PR Skipped] could not raise a PR for branch '${validated.branch}' -> '${validated.baseBranch}' (branch is pushed) due to an unrecoverable VCS auth failure: ${prResult.error}`);
352
+ prSkipped = { reason: 'auth-failure', message: 'PR not opened: VCS auth failure' };
328
353
  } else {
329
354
  throw new CommandError(
330
355
  `[Publish PR Failed] VCSModule create-pull-request failed for branch '${validated.branch}' -> '${validated.baseBranch}': ${prResult.error}`,
@@ -341,5 +366,5 @@ export async function runPublishPrPhase({
341
366
  }
342
367
  }
343
368
 
344
- return { pushed: true };
369
+ return prSkipped ? { pushed: true, prSkipped } : { pushed: true };
345
370
  }
@@ -74,6 +74,7 @@ import { applyGuardedReopens, ensureRedBranchFixTask, isInGoalPriority } from '.
74
74
  import {
75
75
  validateNewTask, appendRejectedFindingToParentNotes, persistNewTaskBestEffort,
76
76
  } from '../abort.mjs';
77
+ import { applyReviewerDecision, reviewerReopenEntries } from '../decisions.mjs';
77
78
 
78
79
  /**
79
80
  * Runs the Re-Review phase: one fresh review of the CURRENT state, plus the
@@ -100,6 +101,9 @@ export async function runReReviewPhase({
100
101
  // The git/beads sync bracket this phase's post-mutation D-push goes
101
102
  // through.
102
103
  gitSync,
104
+ // Per-sprint resolved state (../sprint-state.mjs): a NEEDS-DECISION
105
+ // verdict records its pending decision and set-aside here.
106
+ sprintState,
103
107
  // Mutated in place; never reassigned by this phase (see header).
104
108
  rejectedNewTasks,
105
109
  // Reassigned, so passed in and returned (see header).
@@ -145,6 +149,9 @@ export async function runReReviewPhase({
145
149
  // verdict in; acceptanceCriteriaJson still carries the full scope
146
150
  // for context.
147
151
  const reReviewVerdict = await dispatchReview({ beadIds: targetIssues, acceptanceCriteriaJson: JSON.stringify(reReviewScope) });
152
+ // The re-review covers the whole sprint scope: a NEEDS-DECISION may name
153
+ // any bead in it.
154
+ const reReviewScopeIds = [...targetIssues, ...(Array.isArray(reReviewScope) ? reReviewScope.map((b) => b && b.id).filter(Boolean) : [])];
148
155
  lastReviewVerdict = reReviewVerdict.verdict;
149
156
  reviewedThisCycle = true;
150
157
 
@@ -162,7 +169,8 @@ export async function runReReviewPhase({
162
169
  // "deferred scope, not reopened" outcome instead of being pulled
163
170
  // back into a sprint that no longer targets it.
164
171
  const reopenedIds = new Set(await applyGuardedReopens({
165
- entries: reReviewVerdict.reopenIds,
172
+ // reopenIds, plus a NEEDS-DECISION bead (../decisions.mjs).
173
+ entries: reviewerReopenEntries(reReviewVerdict, reReviewScopeIds),
166
174
  bdListScoped, goalMax, goal: validated.goal, log, command,
167
175
  member: backlogMember,
168
176
  workedOnIds,
@@ -174,6 +182,14 @@ export async function runReReviewPhase({
174
182
  // Track per-bead reopen counts for reopen-thrash detection.
175
183
  onReopened: ({ id }) => recordReopen(id),
176
184
  }));
185
+ // A NEEDS-DECISION verdict: same handling as the per-round Review phase
186
+ // (../decisions.mjs); a closed bead was reopened just above through the
187
+ // same guarded reopen call (reviewerReopenEntries).
188
+ await applyReviewerDecision({
189
+ verdict: reReviewVerdict, scopeIds: reReviewScopeIds, reopenedIds,
190
+ sprintState, command, member: backlogMember, bdListScoped, cycle, round: null,
191
+ site: `Re-Review C${cycle}`, log,
192
+ });
177
193
  let inGoalNewTaskCount = 0;
178
194
  for (const newTask of reReviewVerdict.newTasks) {
179
195
  const validation = validateNewTask(newTask);
@@ -69,6 +69,7 @@ import { applyGuardedReopens, foldReplanIds, ensureRedBranchFixTask, isInGoalPri
69
69
  import {
70
70
  validateNewTask, appendRejectedFindingToParentNotes, persistNewTaskBestEffort,
71
71
  } from '../abort.mjs';
72
+ import { applyReviewerDecision, reviewerReopenEntries } from '../decisions.mjs';
72
73
 
73
74
  /**
74
75
  * The bead ids a round's Review covers: the union of every streak outcome's
@@ -120,6 +121,9 @@ export async function runReviewPhase({
120
121
  // The git/beads sync bracket this phase's post-mutation D-push goes
121
122
  // through.
122
123
  gitSync,
124
+ // Per-sprint resolved state (../sprint-state.mjs): a NEEDS-DECISION
125
+ // verdict records its pending decision and set-aside here.
126
+ sprintState,
123
127
  // Per-cycle state. `replanIds`, `replannedThisCycle`, `perBeadFeedback` and
124
128
  // `rejectedNewTasks` are mutated in place (see header).
125
129
  replanIds,
@@ -169,7 +173,8 @@ export async function runReviewPhase({
169
173
  ? await command(`bd show ${assignedBeadIds.join(' ')} --json`, { member_name: backlogMember, silent: true })
170
174
  : '[]';
171
175
 
172
- // Empty-guard: when EVERY streak this round failed, assignedBeadIds
176
+ // Empty-guard: when no bead was verified closed this round (every
177
+ // streak failed before closing anything), assignedBeadIds
173
178
  // is [] and there is nothing for the Reviewer to look at. Skip the
174
179
  // dispatch entirely rather than sending an empty-scope review: an
175
180
  // empty review is prone to returning CHANGES_NEEDED with empty
@@ -180,7 +185,7 @@ export async function runReviewPhase({
180
185
  // still runs, so the loop correctly continues instead of prematurely
181
186
  // treating the cycle as organically complete.
182
187
  if (assignedBeadIds.length === 0) {
183
- log(`Develop C${cycle} R${devRounds}: all streaks this round failed with no beadIds assigned -- skipping Review dispatch (nothing to review). Failed-streak beads remain ready for the next Develop round.`);
188
+ log(`Develop C${cycle} R${devRounds}: all streaks this round failed with no beadIds assigned -- skipping Review dispatch (nothing to review: no bead was verified closed this round). Failed-streak beads remain ready for the next Develop round.`);
184
189
  } else {
185
190
  // dispatchReview() applies the shared contract-violation
186
191
  // retry-once-then-throw rule (see its own doc comment and
@@ -221,7 +226,8 @@ export async function runReviewPhase({
221
226
  // reopened (out of scope, or simply absent from reopenIds) can
222
227
  // never short-circuit the loop.
223
228
  const reopenedIds = new Set(await applyGuardedReopens({
224
- entries: verdict.reopenIds,
229
+ // reopenIds, plus a NEEDS-DECISION bead (../decisions.mjs).
230
+ entries: reviewerReopenEntries(verdict, assignedBeadIds),
225
231
  bdListScoped, goalMax, goal: validated.goal, log, command,
226
232
  member: backlogMember,
227
233
  workedOnIds,
@@ -239,6 +245,15 @@ export async function runReviewPhase({
239
245
  perBeadFeedback.set(id, verdict.notes);
240
246
  },
241
247
  }));
248
+ // A NEEDS-DECISION verdict: record the decision for an operator and set
249
+ // the named bead aside -- see ../decisions.mjs. A closed bead was
250
+ // reopened just above, through the same guarded reopen call
251
+ // (reviewerReopenEntries).
252
+ await applyReviewerDecision({
253
+ verdict, scopeIds: assignedBeadIds, reopenedIds, sprintState, command,
254
+ member: backlogMember, bdListScoped, cycle, round: devRounds,
255
+ site: `Review C${cycle} R${devRounds}`, log,
256
+ });
242
257
  // Fold this round's reviewer `replanIds` (absent/undefined on
243
258
  // verdicts that do not use it, so a no-op then) into the cycle's
244
259
  // running union, consulted at the top of the next iteration's
@@ -23,6 +23,7 @@
23
23
  // ASCII only.
24
24
 
25
25
  import { PR_DESCRIPTION_MAX_LENGTH } from './vcs-module.mjs';
26
+ import { formatSetAsideItems, formatWaitedLine } from './set-aside.mjs';
26
27
 
27
28
  /** Opening token of the hidden run-history block. Versioned so a future
28
29
  * format change can tell its own blocks from this one. */
@@ -197,6 +198,12 @@ function inline(text) {
197
198
  * @param {string} [opts.notes] untrusted free text (reviewer notes / abort detail)
198
199
  * @param {string} [opts.notesHeading]
199
200
  * @param {string[]} [opts.details] engine-authored detail lines, rendered as list items
201
+ * @param {object[]} [opts.setAside] the run's set-aside records (./set-aside.mjs
202
+ * collectSetAsideEntries), rendered as a "Set aside this run" section; the
203
+ * section is omitted when empty
204
+ * @param {object[]} [opts.waited] the run's wait records (./set-aside.mjs
205
+ * collectWaitEntries), rendered as one "Waited this run" line after the
206
+ * set-aside section; omitted when empty
200
207
  * @param {string} [opts.costAnalysis] engine-computed cost block, rendered in a fenced Cost section
201
208
  * @param {string} [opts.previousBody] the existing PR's body, for history carry-forward
202
209
  * @param {number} [opts.maxLength]
@@ -204,7 +211,7 @@ function inline(text) {
204
211
  */
205
212
  export function buildSprintPrBody({
206
213
  verdict, goal, branch, baseBranch, runId, now = new Date(),
207
- notes, notesHeading = 'Reviewer notes', details = [], costAnalysis = '', previousBody = '',
214
+ notes, notesHeading = 'Reviewer notes', details = [], setAside = [], waited = [], costAnalysis = '', previousBody = '',
208
215
  maxLength = PR_DESCRIPTION_MAX_LENGTH,
209
216
  }) {
210
217
  const v = VERDICTS.has(verdict) ? verdict : 'FAIL';
@@ -229,12 +236,18 @@ export function buildSprintPrBody({
229
236
  ].filter((l) => l !== null).join('\n');
230
237
 
231
238
  const detailLines = (details || []).filter(Boolean).map((d) => `- ${inline(d)}`);
239
+ const setAsideLines = formatSetAsideItems(setAside).map((d) => `- ${inline(d)}`);
240
+ const waitedLine = formatWaitedLine(waited);
232
241
  // The cost block replaces the per-sprint CHANGELOG entry the harvester used
233
242
  // to write (a shared prepend-only file that conflicted on every merge).
234
243
  const cost = sanitizePrMarkdown(costAnalysis);
235
244
  const costFence = '`'.repeat(Math.max(3, ...(cost.match(/`+/g) || []).map((r) => r.length + 1)));
236
245
  const tail = [
237
246
  '',
247
+ setAsideLines.length ? '### Set aside this run\n' : null,
248
+ setAsideLines.length ? setAsideLines.join('\n') : null,
249
+ setAsideLines.length ? '' : null,
250
+ waitedLine ? `${inline(waitedLine)}\n` : null,
238
251
  detailLines.length ? '### Details\n' : null,
239
252
  detailLines.length ? detailLines.join('\n') : null,
240
253
  detailLines.length ? '' : null,
@@ -15,7 +15,7 @@
15
15
  import { wrapUntrustedBlock } from './contracts.mjs';
16
16
  import { PR_DESCRIPTION_MAX_LENGTH } from './vcs-module.mjs';
17
17
  import { formatStalenessBlock } from './parent-notes-staleness.mjs';
18
- import { buildRejectedNewTaskResurfaceLines, kbKnowledgeBlock, kbPromotionBlock } from './runner.js';
18
+ import { buildRejectedNewTaskResurfaceLines, kbKnowledgeBlock, kbPromotionBlock, kbDemotionBlock } from './runner.js';
19
19
 
20
20
  /**
21
21
  * Deterministic hard cap on the code-reviewer findings text threaded into a
@@ -398,7 +398,31 @@ export function buildDoerPrompt({ beadIds, branch, feedback, kbKnowledge, kbBloc
398
398
  return lines.join('\n\n');
399
399
  }
400
400
 
401
- export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranch, branch, goal, kbCandidates, kbKnowledge, kbBlock }) {
401
+ /**
402
+ * The review diff range `<merge-base-sha>..<branch>`. The SHA is the fork point
403
+ * the engine computed on the reviewer's member after fetching the base branch
404
+ * (resolveReviewMergeBase in git-topology.mjs); a bare `<base>..<branch>` would
405
+ * name the member's local base branch, which the engine never updates. A
406
+ * missing or malformed SHA throws -- a reviewer prompt is never built without it.
407
+ * @param {string} mergeBaseSha
408
+ * @param {string} branch
409
+ * @returns {string}
410
+ */
411
+ export function reviewDiffRange(mergeBaseSha, branch) {
412
+ if (typeof mergeBaseSha !== 'string' || !/^[0-9a-f]{40,64}$/i.test(mergeBaseSha)) {
413
+ throw new Error(`review prompt requires the merge-base commit SHA of the base branch and '${branch}' (got ${JSON.stringify(mergeBaseSha)}).`);
414
+ }
415
+ return `${mergeBaseSha}..${branch}`;
416
+ }
417
+
418
+ function reviewDiffRangeLine(range, baseBranch) {
419
+ return `Diff range to review: ${range} (the merge base of origin/${baseBranch} and the sprint branch, up to the branch). ` +
420
+ `Use exactly this range for every git diff and git log you run (for example: git diff ${range}, git log ${range}); ` +
421
+ `do not diff against the local '${baseBranch}' branch or origin/${baseBranch} directly.`;
422
+ }
423
+
424
+ export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranch, branch, mergeBaseSha, goal, kbCandidates, kbDemoteCandidates, kbKnowledge, kbBlock }) {
425
+ const range = reviewDiffRange(mergeBaseSha, branch);
402
426
  const ids = Array.isArray(beadIds) ? beadIds : [];
403
427
  const scopeWide = ids.length === 0;
404
428
  // Scope-wide re-reviews are fed `bd list --json` (the whole remaining
@@ -416,7 +440,7 @@ export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranc
416
440
  ? 'The full sprint scope, from `bd list --json`:'
417
441
  : 'Full task detail (including acceptance criteria), from `bd show --json`:',
418
442
  wrapUntrustedBlock(scopeCommand, acceptanceCriteriaJson),
419
- `Diff range to review: ${baseBranch}..${branch} (base_branch..branch).`,
443
+ reviewDiffRangeLine(range, baseBranch),
420
444
  // Without an explicit scope clause a reviewer can withhold APPROVED
421
445
  // over below-goal work the sprint deliberately defers, which starves
422
446
  // the completion gate (zero open goal beads AND an APPROVED verdict).
@@ -446,6 +470,7 @@ export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranc
446
470
  // which of this sprint's captures earned CONFIRMED.
447
471
  ...(Array.isArray(kbBlock) ? kbBlock : kbKnowledgeBlock(kbKnowledge)),
448
472
  ...kbPromotionBlock(kbCandidates),
473
+ ...kbDemotionBlock(kbDemoteCandidates),
449
474
  'Do NOT run any `bd` command yourself and do NOT mutate beads directly in any way ' +
450
475
  '(no bd update, bd close, bd create, etc.) -- the orchestrator applies your ' +
451
476
  '`reopenIds` via `bd update <id> --status=open` and creates your `newTasks` via ' +
@@ -479,12 +504,13 @@ export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranc
479
504
  * }} opts
480
505
  * @returns {string}
481
506
  */
482
- export function buildFinalVerdictPrompt({ targetIssues, branch, baseBranch, goal, cyclesRun, closedCount, openAtGoalCount, deployFailures, integFailures, rejectedNewTasks = [], unclosedVerifyIds = [], deferredAtGoalIds = [], kbCandidates, kbKnowledge, kbBlock }) {
507
+ export function buildFinalVerdictPrompt({ targetIssues, branch, baseBranch, mergeBaseSha, goal, cyclesRun, closedCount, openAtGoalCount, deployFailures, integFailures, rejectedNewTasks = [], unclosedVerifyIds = [], deferredAtGoalIds = [], kbCandidates, kbDemoteCandidates, kbKnowledge, kbBlock }) {
508
+ const range = reviewDiffRange(mergeBaseSha, branch);
483
509
  const lines = [
484
510
  `Final review for sprint scope issue id(s): ${targetIssues.join(', ')}.`,
485
511
  `Branch: ${branch} (base: ${baseBranch}). Goal priority: ${goal}. The sprint ran ${cyclesRun} cycle(s).`,
486
512
  `Evidence: ${closedCount} bead(s) closed in scope; ${openAtGoalCount} bead(s) still open at or above goal priority ${goal}.`,
487
- `The evidence above (bead counts, deploy/integ outcomes) is a summary, not proof -- it reflects what the sprint claims, not what the code does. You MUST review the actual net diff yourself before returning PASS; a PASS grounded only in bead-closure counts is not acceptable. Diff range: ${baseBranch}..${branch} (base_branch..branch). Review it as a whole against what closed -- net changes vs. the beads claimed done, not a commit-by-commit walk.`,
513
+ `The evidence above (bead counts, deploy/integ outcomes) is a summary, not proof -- it reflects what the sprint claims, not what the code does. You MUST review the actual net diff yourself before returning PASS; a PASS grounded only in bead-closure counts is not acceptable. ${reviewDiffRangeLine(range, baseBranch)} Review it as a whole against what closed -- net changes vs. the beads claimed done, not a commit-by-commit walk.`,
488
514
  ];
489
515
  if (deployFailures.length > 0) {
490
516
  lines.push(
@@ -588,6 +614,7 @@ export function buildFinalVerdictPrompt({ targetIssues, branch, baseBranch, goal
588
614
  // and was stranded at INFERRED forever.
589
615
  lines.push(...(Array.isArray(kbBlock) ? kbBlock : kbKnowledgeBlock(kbKnowledge)));
590
616
  lines.push(...kbPromotionBlock(kbCandidates));
617
+ lines.push(...kbDemotionBlock(kbDemoteCandidates));
591
618
  return lines.join('\n\n');
592
619
  }
593
620