@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
package/README.md CHANGED
@@ -18,6 +18,7 @@ workforce -- on any machine, anywhere, using every LLM provider at once.
18
18
  [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](https://github.com/Apra-Labs/apra-fleet/releases)
19
19
  [![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
20
20
  [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Apra-Labs/apra-fleet)
21
+ [![Security: A - Skills Directory](https://www.skillsdirectory.com/api/skills/apra-labs-apra-fleet/badge)](https://www.skillsdirectory.com/skills/apra-labs-apra-fleet)
21
22
 
22
23
  [Quick Start](#quick-start-5-minutes) - [Live Demo](#watch-a-fleet-work) - [How It Works](#how-it-works) - [fleet-sprint Getting Started Guide](docs/fleet-sprint-getting-started.md) - [Website](https://apra-labs.github.io/apra-fleet)
23
24
 
@@ -84,6 +85,11 @@ It is not a toy. It builds apra-fleet itself:
84
85
  - Every sprint's raw child stdout/stderr is captured to a per-sprint log
85
86
  and linked from the dashboard, so a run's output is traceable even if it
86
87
  crashes before reporting anything back
88
+ - Asks a human when it must: a doer or reviewer that needs an operator
89
+ decision files a decision bead, the run pauses (not stalls), you are
90
+ notified once by message and email, and your answer on the dashboard or
91
+ via `bd human respond` resumes it
92
+ ([details](docs/fleet-sprint-set-aside.md))
87
93
 
88
94
  A fleet that has run in production:
89
95
 
@@ -119,6 +125,16 @@ The standalone installer instead registers and starts a user-level service
119
125
 
120
126
  The default install includes fleet-se (fleet-sprint, supervisor, bd), which requires a system Node.js 22.16+ and npm on PATH; the installer fails up front if they are missing. Use `apra-fleet install --workflows none` to install the core only.
121
127
 
128
+ For Claude Code, `install` also adds the **fleet-status mod** -- a Claude Code
129
+ plugin that shows every member's state in the status line and opens a
130
+ `/fleet-status` pane where you can also remove a member and list, add,
131
+ replace or delete secrets (a secret's value is typed in another terminal or
132
+ the server's one-time form, never in Claude Code). It is installed through the `claude` CLI from a local
133
+ marketplace in `~/.apra-fleet/claude-plugins/` and replaces the old statusLine
134
+ script. If the `claude` CLI is missing or too old to install plugins, install
135
+ says why and keeps the statusLine script instead. A statusLine of your own is
136
+ never overwritten. See [docs/install.md](docs/install.md#the-fleet-status-mod-claude-code).
137
+
122
138
  **2. Connect your agent.** Load the fleet server in Claude Code with
123
139
  `/mcp` (or restart your provider CLI). Your agent now has a fleet. To check
124
140
  from a shell, `claude mcp list` should show a line like
@@ -217,11 +233,14 @@ MCP tools that ship with the KB:
217
233
  | `kb_context` | Batch file freshness check (single git call for N files) |
218
234
  | `kb_invalidate` | Mark files stale immediately (also called by the git hook), or discard own entries by `ids` |
219
235
  | `kb_promote` | Advance confidence: UNVERIFIED -> INFERRED -> CONFIRMED (FULL session, or the sprint's kb_maintainer member session only) |
236
+ | `kb_demote` | Withdraw trust: lower a CONFIRMED entry back to INFERRED (the one reversible rung; never a ladder in its own direction) |
220
237
  | `kb_harvest` | Extract learnings from a session transcript (auto-fires after execute_prompt) |
221
238
  | `kb_export` | Additively merge live CONFIRMED entries whose cited files still match their recorded hashes into `.fleet/kb-canonical.json` -- the git-shareable team bible (FULL session only) |
222
- | `kb_bible_commit` | Merge confirmed entry ids into the bible (format v3, per-entry file hashes), remove superseded or invalidated entries, and commit locally with base-branch provenance (used by the sprint kb_maintainer) |
239
+ | `kb_bible_commit` | Merge confirmed entry ids into the bible (format v3, per-entry file hashes), remove superseded or invalidated entries, and commit locally with base-branch provenance (used by the sprint kb_maintainer); on an http KB project it is a no-op that returns `bible_skipped: true` |
223
240
  | `kb_setup` | Install git hook, write provider config, store remote token encrypted (FULL session only) |
224
241
 
242
+ `kb_query` accepts `own_scope: true` so a MEMBER session can read its own CONFIRMED rows from the per-repo database instead of the bible view. The fleet-sprint reviewer uses this to offer demotion candidates; the loop is on by default and `--kb-demotion-loop off` disables it. See [docs/kb-member-view-and-maintainer.md](docs/kb-member-view-and-maintainer.md).
243
+
225
244
  `code_*` tools resolve the calling session's own folder, refuse with typed
226
245
  `E-CODE-INDEX-NOT-READY` / `E-CODE-INTEL-DISABLED` errors when the index is not
227
246
  usable, and report `indexedCommit` on every result; `code_reindex` and
@@ -240,13 +259,34 @@ no separate "server mode" build. A config with no remote, or any config the
240
259
  reader cannot parse, always falls back to the local SQLite provider -- see
241
260
  [Client-side provider selection](docs/knowledge-layer-design.md#client-side-provider-selection)
242
261
  for the exact selection rule and its fallback-construction invariant.
262
+ `--token {{secret.NAME}}` stores a reference to a refreshable fleet secret instead of a token, so an
263
+ expiring server token can be rotated with `apra-fleet secret --set NAME --persist -y` and no restart (see
264
+ [Named credentials](docs/knowledge-layer.md#named-credentials-and-refreshers)).
265
+ `--request_timeout_ms <ms>` (1000-120000, default 5000) sets the socket idle
266
+ timeout for each request to the remote KB server. It is not a per-request
267
+ deadline: a call can wait up to about twice the value when it first reads
268
+ the server capabilities. See
269
+ [docs/knowledge-layer.md](docs/knowledge-layer.md).
243
270
 
244
271
  **The provider config is install-wide, not per repo.** There is one
245
272
  `knowledge/config.json` per fleet install, so pointing it at a remote KB
246
273
  points EVERY repo that install serves -- every member, every project -- at
247
274
  that server. `kb_setup` only places the git post-commit hook (in the calling
248
- session's own repo); it does not scope the config. On a shared fleet server,
249
- treat `kb_setup --remote` as a change for all of its users.
275
+ session's own repo, including linked worktrees and custom `core.hooksPath`);
276
+ it does not scope the config. On a shared fleet server, treat
277
+ `kb_setup --remote` as a change for all of its users.
278
+
279
+ **KB tool profiles.** `apra-fleet kb profile developer` (or `kb_setup` with
280
+ `tool_profile`) trims the `kb_*` tools an interactive (non-member) session
281
+ lists to `kb_session_prime`, `kb_query`, `kb_context`, `kb_capture` and
282
+ `kb_feedback`; `custom <a,b>` lists exactly the named `kb_*` tools and `full`
283
+ (the default) lists them all. The profile is install-wide, applies to FULL
284
+ sessions only (member sessions and sprint roles are unaffected), and takes
285
+ effect when a session reconnects. It is a usability control, not a security
286
+ boundary. `developer` hides `kb_setup` and the tools the PM skills `kb-review`,
287
+ `kb-reconcile` and `knowledge-agent` need, so get back with
288
+ `apra-fleet kb profile full` (and reconnect) before running those. See
289
+ [KB tool profiles](docs/knowledge-layer.md#5-kb-tool-profiles-which-kb_-tools-interactive-sessions-see).
250
290
 
251
291
  Every KB tool call is scoped to the calling session's own repo -- a fleet
252
292
  server handling many members across many repos never lets one repo's
@@ -400,7 +440,7 @@ your config however you prefer (JSON file, hardcoded, etc.):
400
440
  import { parseToolJson } from '@apralabs/apra-fleet-client';
401
441
  import { connectFleet } from '@apralabs/apra-fleet-client/server-resolution';
402
442
 
403
- const { fleetApi } = await connectFleet({ env: process.env });
443
+ const { fleetApi, transport } = await connectFleet({ env: process.env });
404
444
 
405
445
  // fleetApi wrappers return the raw MCP tool result ({ content: [...] });
406
446
  // parseToolJson extracts the JSON payload.
@@ -415,6 +455,9 @@ const result = parseToolJson(await fleetApi.sendEmail({
415
455
  body: 'All tasks completed.'
416
456
  }));
417
457
  console.log(`Sent: ${result.messageId}`);
458
+
459
+ // Release the server session when done (stop() alone leaves it open).
460
+ await transport.close();
418
461
  ```
419
462
 
420
463
  The SMTP password resolves from the credential store automatically. It never
@@ -469,6 +512,7 @@ third-party verticals.
469
512
  | Topic | Link |
470
513
  |-------|------|
471
514
  | **fleet-sprint Getting Started Guide (start here, plain English)** | [Website](https://apra-labs.github.io/apra-fleet/fleet-sprint-getting-started.html) - [Markdown](docs/fleet-sprint-getting-started.md) |
515
+ | fleet-sprint set-aside rules (BLOCKED beads, deploy Permissions failure, immediate stall) | [docs/fleet-sprint-set-aside.md](docs/fleet-sprint-set-aside.md) |
472
516
  | Codebase wiki (architecture, internals, AI Q&A) | [DeepWiki](https://deepwiki.com/Apra-Labs/apra-fleet) |
473
517
  | Install, uninstall, the `--llm` flag | [docs/install.md](docs/install.md) |
474
518
  | Choosing a provider (roles, gotchas, mixing providers, OpenCode/local models) | [docs/provider-guide.md](docs/provider-guide.md) |
@@ -478,6 +522,7 @@ third-party verticals.
478
522
  | The PM skill (doer-reviewer sprints, `/pm` commands) | [docs/pm-skill-overview.md](docs/pm-skill-overview.md) |
479
523
  | FAQ | [docs/FAQ.md](docs/FAQ.md) |
480
524
  | Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
525
+ | Supervisor/viewer request guard | [docs/supervisor-request-guard.md](docs/supervisor-request-guard.md) |
481
526
  | Keeping Fleet updated (`apra-fleet update`) | [docs/features/update.md](docs/features/update.md) |
482
527
  | Live member activity (`apra-fleet watch`, `logging.previewChars`) | [docs/features/watch.md](docs/features/watch.md) |
483
528
  | Secret variables and passwords | [docs/secret-variables.md](docs/secret-variables.md) - [docs/features/oob-auth.md](docs/features/oob-auth.md) |
@@ -25,6 +25,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
25
25
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
26
26
  your tool-loading tool first, before concluding they are unavailable.
27
27
 
28
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
29
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
30
+ not help), retry that call ONCE, and if it still fails fall back to text search and
31
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
32
+
28
33
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
29
34
  subsystems the assigned beads touch. KB knowledge matters most for duplicate
30
35
  detection and sprint-set grouping.
@@ -37,6 +37,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
37
37
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
38
38
  your tool-loading tool first, before concluding they are unavailable.
39
39
 
40
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
41
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
42
+ not help), retry that call ONCE, and if it still fails fall back to text search and
43
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
44
+
40
45
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
41
46
  repo's CI workflow files. Known-flaky tests and known CI failure modes are the point
42
47
  here -- they change how you read a red run.
@@ -80,8 +80,11 @@ console.log(JSON.stringify([...allow], null, 2));
80
80
 
81
81
  Check every required prefix against this one merged list. If any prefix has
82
82
  no covering entry, STOP immediately and return `deployed: false`, listing
83
- every missing entry in `notes` and asking the orchestrator/operator to run
84
- `compose_permissions` with the missing grant(s), then re-trigger the sprint.
83
+ every missing entry in `notes`, and set `failedStep: "permissions"`, asking the
84
+ orchestrator/operator to run `compose_permissions` with the missing grant(s), then
85
+ re-trigger the sprint. `failedStep` is how the orchestrator knows no deploy command
86
+ ran -- set it only for this Step 0a stop, never for a failure after a deploy command
87
+ ran.
85
88
  NEVER add permissions yourself: `.claude/settings.json` changes require a
86
89
  team PR, and `.claude/settings.local.json` must be provisioned via the
87
90
  `compose_permissions` MCP tool (the provider-agnostic delivery mechanism
@@ -103,6 +106,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
103
106
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
104
107
  your tool-loading tool first, before concluding they are unavailable.
105
108
 
109
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
110
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
111
+ not help), retry that call ONCE, and if it still fails fall back to text search and
112
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
113
+
106
114
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
107
115
  deploy targets in `deploy.md`.
108
116
  2. Any judgment that depends on what the KB does or does not record is made from the
@@ -161,6 +169,16 @@ placeholder):
161
169
  }
162
170
  ```
163
171
 
172
+ A Step 0a stop (missing permissions, no deploy command ran):
173
+
174
+ ```json
175
+ {
176
+ "deployed": false,
177
+ "failedStep": "permissions",
178
+ "notes": "Missing permission grant(s): <entries>. Run compose_permissions with them, then re-trigger the sprint."
179
+ }
180
+ ```
181
+
164
182
  **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
165
183
  authoritative -- respond with exactly that JSON and nothing else. It is expected to match
166
184
  this contract; if it differs, follow the dispatch prompt.
@@ -51,6 +51,23 @@ your final `notes`, naming the bead id and the defect. This is a legitimate skip
51
51
  exception (see Step 3 and Rules); it lets the reviewer route the bead to re-planning in
52
52
  the same round.
53
53
 
54
+ **Needs an operator decision**: when a bead cannot go on until a human chooses between
55
+ real alternatives -- for example the criteria can only be met by upgrading a dependency,
56
+ patching it, or accepting a weaker check, and nothing in the bead, its parent or the code
57
+ says which -- do not guess and do not keep retrying. Leave the bead open and return
58
+ `status: "NEEDS-DECISION"` with a `decision` object: `beadId` (that one open bead),
59
+ `question` (self-contained: what you found, why it blocks the bead, what must be
60
+ decided), `options` (at least two, each `{ "id": "a", "text": "..." }` with what it
61
+ means and costs) and `recommendation` (the option id you recommend, and why). The
62
+ orchestrator files the question for an operator verbatim, sets the bead aside for the
63
+ rest of the run without re-dispatching it, and keeps working other beads; the answer
64
+ reaches a later dispatch through the bead's notes. Use it instead of the
65
+ criteria-defect escape hatch only when the fix is a choice an operator must make, not a
66
+ criteria rewrite a planner can make. Use BLOCKED, not NEEDS-DECISION, for a missing
67
+ secret, missing access, or an unmet prerequisite: those have one fix, not a choice. The
68
+ same-lane stop rule (Step 1) applies to a NEEDS-DECISION bead exactly as to any other
69
+ bead left open.
70
+
54
71
  **CI is not yours**: never trigger, wait for or poll a CI run. A criterion that can only
55
72
  be met by a CI run is a criteria defect: do the locally checkable work and report the CI
56
73
  part under "criteria defects" (see above).
@@ -80,6 +97,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
80
97
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
81
98
  your tool-loading tool first, before concluding they are unavailable.
82
99
 
100
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
101
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
102
+ not help), retry that call ONCE, and if it still fails fall back to text search and
103
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
104
+
83
105
  The `kb_query` and `code_impact` calls below are EXPECTED, not optional, whenever the
84
106
  tools are present. If a tool is genuinely not present (or the KB or code index is not set
85
107
  up for this repo), record that in `toolUse` (Output schema) and continue -- never skip
@@ -105,7 +127,8 @@ silently.
105
127
  fixture-only files are exempt. Prefer these over grep for symbol lookups, call-chain
106
128
  tracing, and impact analysis. If they are absent, fail, or report the repo is not
107
129
  indexed, fall back to grep and record it in `toolUse`; do not try to build an index
108
- yourself.
130
+ yourself. On `E-CODE-INDEX-NOT-READY`, wait once for its `retry_after_ms`, retry
131
+ once, then fall back to grep -- never poll `code_status` in a loop.
109
132
  5. Report in `toolUse`: `kb` and `code` are each `used`, `unavailable` or `not_needed`;
110
133
  `note` says why for anything not `used`. `used` means the expected call was made
111
134
  (`kb_query` for kb -- `kb_session_prime` alone is not `used`; `code_impact`/
@@ -262,6 +285,18 @@ stop and return:
262
285
  orchestrator can verify your closes against beads instead of trusting the summary alone.
263
286
  Do NOT continue past VERIFY.
264
287
 
288
+ Whenever you return `status: "BLOCKED"`, also return `blockedIds`: the assigned bead ids
289
+ you left open BECAUSE of the block. Leave out ids you merely did not reach (for example
290
+ lane-mates skipped under the same-lane stop rule) -- the orchestrator sets each
291
+ `blockedIds` bead and everything depending on it aside for the rest of the run, and
292
+ re-dispatches the unreached ones. Example:
293
+ `{ "status": "BLOCKED", "closedIds": ["<id-1>"], "blockedIds": ["<id-2>"], "notes": "..." }`.
294
+
295
+ When a bead needs an operator decision (see "Needs an operator decision" above), stop
296
+ there and return `status: "NEEDS-DECISION"` with its `decision` object, listing in
297
+ `closedIds` whatever you closed before it. Example:
298
+ `{ "status": "NEEDS-DECISION", "closedIds": ["<id-1>"], "notes": "...", "decision": { "beadId": "<id-2>", "question": "...", "options": [{ "id": "a", "text": "..." }, { "id": "b", "text": "..." }], "recommendation": "a, because ..." } }`.
299
+
265
300
 
266
301
  ## Branch and secrets rules
267
302
 
@@ -303,7 +338,8 @@ or as prose if you are answering a human directly.
303
338
  - NEVER skip an assigned bead id for convenience -- work them in dependency order. The
304
339
  only skip exceptions: has open children, the same-lane stop rule (Step 1) after an
305
340
  earlier lane-mate was left open, an unresolved wrap-up ambiguity, missing acceptance
306
- criteria/context, or a recorded criteria defect (escape hatch above). A missing secret
341
+ criteria/context, a recorded criteria defect (escape hatch above), or a bead that needs
342
+ an operator decision (returned as NEEDS-DECISION). A missing secret
307
343
  is NOT a skip -- close with a blocked reason per Branch and secrets rules.
308
344
  - Tests for the changed area must pass before each commit (Step 2.5)
309
345
  - No PLAN.md, no progress.json -- beads is the only work tracker
@@ -18,7 +18,7 @@ wired and queried; do not restate or improvise those rules here.
18
18
  Your dispatch prompt must supply:
19
19
 
20
20
  - `analysisArtifactFile` (required) -- relative path (under the repo) to write the sprint
21
- analysis artifact to, e.g. `sprint-logs/<branch>-<startedAt>.md`.
21
+ analysis artifact to, e.g. `docs/sprint-analysis-<slug>.md`. Written, never committed.
22
22
  - `analysisText` (required) -- the exact, pre-formatted analysis content to write verbatim.
23
23
  - `base-branch` (required) -- for `git log`/`git diff` in Step 2.
24
24
  - `branch` (required) -- the sprint branch being harvested.
@@ -44,6 +44,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
44
44
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
45
45
  your tool-loading tool first, before concluding they are unavailable.
46
46
 
47
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
48
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
49
+ not help), retry that call ONCE, and if it still fails fall back to text search and
50
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
51
+
47
52
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
48
53
  relevant to the modules touched during the sprint.
49
54
  2. When you extract durable knowledge during harvest -- anything non-obvious that future
@@ -70,17 +75,15 @@ search also matches value text, so apply only entries whose KEY contains `+all+`
70
75
 
71
76
  Your task context includes an `analysisArtifactFile` path and an `analysisText` block.
72
77
 
73
- Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite if it exists):
74
-
75
- ```bash
76
- mkdir -p "<repo>/sprint-logs"
77
- # Write analysisText content to <repo>/<analysisArtifactFile>
78
- git -C "<repo>" add "<repo>/<analysisArtifactFile>"
79
- git -C "<repo>" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: sprint-analysis <branch> <startedAt>"
80
- ```
78
+ Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite
79
+ if it exists; create its parent directory if missing).
81
80
 
82
81
  Do NOT reformat or modify the analysisText -- write it exactly as provided.
83
82
 
83
+ **Do NOT `git add` or commit this file.** It is a local record that stays untracked in the
84
+ working tree; the orchestrator keeps it out of `git status` and out of every commit. Never
85
+ force-add it (`git add -f`), and do not stage it in any later step.
86
+
84
87
  ## Step 2 -- Read sprint context
85
88
 
86
89
  Read the following to understand what was built:
@@ -76,6 +76,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
76
76
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
77
77
  your tool-loading tool first, before concluding they are unavailable.
78
78
 
79
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
80
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
81
+ not help), retry that call ONCE, and if it still fails fall back to text search and
82
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
83
+
79
84
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
80
85
  relevant to the features you were handed.
81
86
  2. Any judgment that depends on what the KB does or does not record (e.g. whether a test
@@ -105,6 +105,12 @@ code_impact({ target: "<symbol>", direction: "upstream" | "downstream" })
105
105
  code_query({ query: "<concept or pattern>" })
106
106
  ```
107
107
 
108
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
109
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
110
+ not help), retry that call ONCE, and if it still fails fall back to reading the cited
111
+ files directly and say so in the evidence note. Never poll `code_status` in a loop
112
+ waiting for the index.
113
+
108
114
  Decide which entry's claim the CURRENT merged code actually supports. Note the exact
109
115
  file + symbol you read that settled it.
110
116
 
@@ -63,6 +63,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
63
63
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
64
64
  your tool-loading tool first, before concluding they are unavailable.
65
65
 
66
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
67
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
68
+ not help), retry that call ONCE, and if it still fails fall back to text search and
69
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
70
+
66
71
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
67
72
  relevant to the features in the DAG under review.
68
73
  2. Any judgment that depends on KB coverage (e.g. whether a task touches unexplored code
@@ -43,6 +43,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
43
43
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
44
44
  your tool-loading tool first, before concluding they are unavailable.
45
45
 
46
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
47
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
48
+ not help), retry that call ONCE, and if it still fails fall back to text search and
49
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
50
+
46
51
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
47
52
  derived from the sprint goals / requirements you are about to decompose.
48
53
  2. From whichever source you have (a live `kb_session_prime` result, the injected
@@ -21,6 +21,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
21
21
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
22
22
  your tool-loading tool first, before concluding they are unavailable.
23
23
 
24
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
25
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
26
+ not help), retry that call ONCE, and if it still fails fall back to text search and
27
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
28
+
24
29
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
25
30
  subsystems `regression-test-playbook.md` exercises.
26
31
  2. Known-flaky tests and known environment setup/teardown gotchas are the point here -- they
@@ -44,6 +44,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
44
44
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
45
45
  your tool-loading tool first, before concluding they are unavailable.
46
46
 
47
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
48
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
49
+ not help), retry that call ONCE, and if it still fails fall back to text search and
50
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
51
+
47
52
  The `code_impact` and `kb_query` calls below are EXPECTED, not optional, whenever the
48
53
  tools are present. If a tool is genuinely not present (or the KB or code index is not set
49
54
  up for this repo), record that in `toolUse` (Output schema) and continue -- never skip
@@ -58,7 +63,9 @@ silently.
58
63
  exempt -- and `code_context`/`code_graph`/`code_query` to trace callers before
59
64
  accepting a signature or behaviour change -- prefer them over grep for structural
60
65
  questions. If they are absent, fail, or report the repo is not indexed, fall back to
61
- reading the diff and grep and record it in `toolUse`; do not build an index.
66
+ reading the diff and grep and record it in `toolUse`; do not build an index. On
67
+ `E-CODE-INDEX-NOT-READY`, wait once for its `retry_after_ms`, retry once, then fall
68
+ back -- never poll `code_status` in a loop.
62
69
  3. Call `kb_query` at least once per review, on the changed files' topics, to check the
63
70
  doer's claims and the diff against what the KB already records, and to dedupe your
64
71
  captures (item 4). This is for verification only; promotion candidates still come
@@ -96,6 +103,10 @@ search also matches value text, so apply only entries whose KEY contains `+all+`
96
103
 
97
104
  ## Step 1 -- Context recovery
98
105
 
106
+ If your dispatch prompt gives a diff range (`<commit-sha>..<branch>`), use exactly that
107
+ range wherever `<base-branch>..<branch>` appears below, for every `git diff` and
108
+ `git log`. Never diff against a local base branch in that case: it may be stale.
109
+
99
110
  ```bash
100
111
  git log --oneline <base-branch>..<branch>
101
112
  git diff <base-branch>..<branch> --stat
@@ -170,13 +181,17 @@ foreground command, treat it as if you backgrounded it yourself; do not chain sh
170
181
  sleeps to route around the sleep-block. Do not return a verdict while the suite is
171
182
  still running -- a backgrounded run with no reported outcome is not a completed step.
172
183
 
173
- ## Step 5 -- Promote or discard knowledge you verified
184
+ ## Step 5 -- Promote, discard, or demote knowledge you verified
174
185
 
175
- This step covers judgements on existing INFERRED candidates: promote one to CONFIRMED,
176
- or discard one you showed to be wrong. Fresh findings go in `kb_captures` (Step 0,
177
- item 4) -- the fields are independent and can all be returned. You are the only role
178
- permitted to mint CONFIRMED. **You do not call any `kb_*` tool for this** -- the
179
- orchestrator hands you the candidates and executes your decisions.
186
+ This step covers judgements on existing candidates: promote an INFERRED one to
187
+ CONFIRMED, discard an INFERRED one you showed to be wrong, or demote a CONFIRMED one
188
+ back to INFERRED. Fresh findings go in `kb_captures` (Step 0, item 4) -- the fields are
189
+ independent and can all be returned. You are the only role permitted to mint CONFIRMED
190
+ or to demote it. **You do not call any `kb_*` tool for any of promotion, discard or
191
+ demotion** -- for all three, you RETURN your judgement in the named field of your
192
+ structured output (`kb_promotions`, `kb_discards`, `kb_demotions`), and the orchestrator
193
+ reads that output and executes your judgement on your behalf; you never touch the KB
194
+ directly.
180
195
 
181
196
  1. Read the **KNOWLEDGE BANK -- promotion candidates** block in your dispatch prompt. It
182
197
  lists every INFERRED entry for the repo under review as `{id, title, summary,
@@ -197,6 +212,26 @@ orchestrator hands you the candidates and executes your decisions.
197
212
  confirm is not wrong: leave it INFERRED. Never list the same id in both
198
213
  `kb_promotions` and `kb_discards` -- the orchestrator refuses both.
199
214
  `kb_discards: []` is a valid, common answer.
215
+ 6. **Demote** a CONFIRMED entry when re-checking it during THIS review shows the claim
216
+ does not hold -- whether you are now less certain of it or have shown it wrong, it is
217
+ one judgement and one route. Read the **KNOWLEDGE BANK -- demotion candidates** block
218
+ in your dispatch prompt (if absent, there is nothing to demote: return
219
+ `kb_demotions: []`). A drifted or removed basis (the cited code changed or vanished)
220
+ is NOT a demote case -- the freshness sweep and the bible basis predicate already
221
+ handle that without you. Discarding an unconfirmed (INFERRED) capture you showed wrong
222
+ is `kb_discards` above, never a demotion, since demotion only ever applies to an
223
+ already-CONFIRMED entry. Return demotions in the `kb_demotions` field as
224
+ `[{id, reason, evidence_files}]`: the same reason bar (minimum 20 characters, stating
225
+ what you re-checked this review that the claim does not hold up against), and
226
+ `evidence_files` naming the files you re-checked -- at least one, each a real file in
227
+ the repo. A demotion without one is refused. Demoting nothing is a valid, common answer: `kb_demotions: []`.
228
+ Never list the same id in more than one of `kb_promotions`, `kb_discards` and
229
+ `kb_demotions` -- the orchestrator refuses it in every list it appears in.
230
+ A team can turn the demotion loop off (a sprint launch setting); then no
231
+ demotion candidates block appears and any `kb_demotions` you return are dropped.
232
+ Re-promotion limit: a demoted entry returns to INFERRED, but the promotion window is
233
+ entries whose `created_at` falls inside the current sprint, so an entry created in an
234
+ earlier sprint that gets demoted is never re-offered for promotion by the engine.
200
235
 
201
236
  Hard limits:
202
237
 
@@ -210,13 +245,13 @@ Hard limits:
210
245
  - **User-directives are off limits.** Activation is human-only; the orchestrator filters
211
246
  them from your candidate list. If one appears anyway, leave it alone.
212
247
  - **Never invent an id.** Only ids from the candidate block in THIS dispatch are
213
- promotable or discardable. The orchestrator refuses any other id, so an id from
214
- anywhere else -- including one you remember from an earlier round -- is dropped
248
+ promotable, discardable or demotable. The orchestrator refuses any other id, so an id
249
+ from anywhere else -- including one you remember from an earlier round -- is dropped
215
250
  and logged, never applied.
216
251
 
217
- Promotion and discard are KB decisions, not beads mutations -- they do not conflict with
218
- the "never mutate beads" rule below. Report what you promoted or discarded in `notes` as
219
- well.
252
+ Promotion, discard and demotion are KB decisions, not beads mutations -- they do not
253
+ conflict with the "never mutate beads" rule below. Report what you promoted, discarded
254
+ or demoted in `notes` as well.
220
255
 
221
256
  ## Step 6 -- Verdict
222
257
 
@@ -233,7 +268,7 @@ judgement.
233
268
  Return your structured output ONLY. You never call `bd update`, `bd close`, `bd create`,
234
269
  or any other beads mutation yourself -- the orchestrator reads your structured output and
235
270
  applies the reopen/create transitions:
236
- - `verdict`: "APPROVED" or "CHANGES_NEEDED"
271
+ - `verdict`: "APPROVED", "CHANGES_NEEDED" or "NEEDS-DECISION"
237
272
  - `notes`: specific findings with file and line references where possible
238
273
  - `reopenIds`: array of beads task IDs that need rework (empty array if none)
239
274
  - `replanIds`: optional array of ids among `reopenIds` whose ACCEPTANCE CRITERIA are
@@ -261,6 +296,19 @@ applies the reopen/create transitions:
261
296
  yourself. The orchestrator runs `bd update <id> --status=open` for each ID in `reopenIds`.
262
297
  Notes must be specific: "auth_test.ts line 42: no test for expired token path".
263
298
 
299
+ **NEEDS-DECISION**: when a bead under review can be neither approved nor sent back for
300
+ rework until a human chooses between real alternatives (for example two acceptable
301
+ designs with different costs, or criteria that can only be met by an option the bead
302
+ does not authorize), return `verdict: "NEEDS-DECISION"` with a `decision` object:
303
+ `beadId` (the one bead the decision is about, from the beads you were asked to review),
304
+ `question` (self-contained: what you found and what must be decided), `options` (at
305
+ least two, each `{ "id": "a", "text": "..." }`) and `recommendation` (the option id you
306
+ recommend, and why). The orchestrator reopens that bead if needed, files the question
307
+ for an operator verbatim and sets the bead aside for the rest of the run; any other
308
+ `reopenIds` and `newTasks` on the same verdict are still applied. Do not use it for
309
+ ordinary rework (CHANGES_NEEDED) or for defective criteria a planner can rewrite
310
+ (`replanIds`).
311
+
264
312
  ## Output schema
265
313
 
266
314
  The canonical machine-readable contract for this output lives in the sibling file
@@ -281,6 +329,9 @@ placeholder):
281
329
  "kb_discards": [
282
330
  { "id": "kb-0051", "reason": "src/auth/session.ts:40 refreshes eagerly; the entry's lazy-refresh claim is wrong" }
283
331
  ],
332
+ "kb_demotions": [
333
+ { "id": "kb-0033", "reason": "re-ran the reopen test this entry cites and it now fails", "evidence_files": ["test/reopen.test.mjs"] }
334
+ ],
284
335
  "kb_captures": [
285
336
  {
286
337
  "type": "knowledge",
@@ -294,8 +345,9 @@ placeholder):
294
345
  }
295
346
  ```
296
347
 
297
- `kb_promotions`, `kb_discards` and `kb_captures` are all optional -- omit them, or send
298
- `[]`, when you have nothing to promote, discard or capture this round. `toolUse` is
348
+ `kb_promotions`, `kb_discards`, `kb_demotions` and `kb_captures` are all optional --
349
+ omit them, or send `[]`, when you have nothing to promote, discard, demote or capture
350
+ this round. `toolUse` is
299
351
  optional in the schema but expected: see Step 0.
300
352
 
301
353
  **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
@@ -12,6 +12,11 @@
12
12
  },
13
13
  "notes": {
14
14
  "type": "string"
15
+ },
16
+ "failedStep": {
17
+ "type": "string",
18
+ "enum": ["permissions"],
19
+ "description": "Set to \"permissions\" ONLY when you returned deployed: false because you stopped at Step 0a (the deploy.md Permissions check) before running any deploy command. The orchestrator then does not dispatch the deploy again this run. Omit it for every other outcome, including any failure after a deploy command ran."
15
20
  }
16
21
  }
17
22
  }