@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
@@ -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
  }
@@ -15,7 +15,8 @@
15
15
  "type": "string",
16
16
  "enum": [
17
17
  "VERIFY",
18
- "BLOCKED"
18
+ "BLOCKED",
19
+ "NEEDS-DECISION"
19
20
  ]
20
21
  },
21
22
  "closedIds": {
@@ -27,6 +28,62 @@
27
28
  "notes": {
28
29
  "type": "string"
29
30
  },
31
+ "decision": {
32
+ "type": "object",
33
+ "description": "REQUIRED when status is \"NEEDS-DECISION\", otherwise omit. The decision only a human operator can make before the named bead can go on. The orchestrator files it for an operator verbatim (never truncated), sets the bead aside for the rest of the run without re-dispatching it, and keeps working other ready beads. Use it only for a real choice between alternatives you cannot settle from the bead, its parent or the code -- not for a missing secret or an unmet prerequisite (BLOCKED), and not for an ordinary failure.",
34
+ "required": [
35
+ "beadId",
36
+ "question",
37
+ "options",
38
+ "recommendation"
39
+ ],
40
+ "properties": {
41
+ "beadId": {
42
+ "type": "string",
43
+ "minLength": 1,
44
+ "description": "The one open bead id that cannot go on until the decision is made."
45
+ },
46
+ "question": {
47
+ "type": "string",
48
+ "minLength": 1,
49
+ "description": "The full question, self-contained: what was found, why it blocks the bead, and what must be decided. An operator reads only this and the options."
50
+ },
51
+ "options": {
52
+ "type": "array",
53
+ "minItems": 2,
54
+ "description": "At least two concrete alternatives, each with a short stable id (for example \"a\", \"b\") and its full text: what it means and what it costs.",
55
+ "items": {
56
+ "type": "object",
57
+ "required": [
58
+ "id",
59
+ "text"
60
+ ],
61
+ "properties": {
62
+ "id": {
63
+ "type": "string",
64
+ "minLength": 1
65
+ },
66
+ "text": {
67
+ "type": "string",
68
+ "minLength": 1
69
+ }
70
+ }
71
+ }
72
+ },
73
+ "recommendation": {
74
+ "type": "string",
75
+ "minLength": 1,
76
+ "description": "The option id you recommend, followed by why."
77
+ }
78
+ }
79
+ },
80
+ "blockedIds": {
81
+ "type": "array",
82
+ "description": "With status BLOCKED: the assigned bead ids you left open BECAUSE of the block -- not ids you merely did not reach (e.g. same-lane stop rule). The engine sets these beads, and every open bead depending on them, aside for the rest of the run. Optional -- omitted on a single-bead assignment it means that bead; omit or send [] with status VERIFY.",
83
+ "items": {
84
+ "type": "string"
85
+ }
86
+ },
30
87
  "kb_captures": {
31
88
  "type": "array",
32
89
  "description": "Durable knowledge this role verified during its run. The engine makes the kb_capture calls; the role only decides. Optional -- omit or send [] to capture nothing.",
@@ -110,5 +167,24 @@
110
167
  }
111
168
  }
112
169
  }
113
- }
170
+ },
171
+ "allOf": [
172
+ {
173
+ "if": {
174
+ "properties": {
175
+ "status": {
176
+ "const": "NEEDS-DECISION"
177
+ }
178
+ },
179
+ "required": [
180
+ "status"
181
+ ]
182
+ },
183
+ "then": {
184
+ "required": [
185
+ "decision"
186
+ ]
187
+ }
188
+ }
189
+ ]
114
190
  }
@@ -16,12 +16,62 @@
16
16
  "type": "string",
17
17
  "enum": [
18
18
  "APPROVED",
19
- "CHANGES_NEEDED"
19
+ "CHANGES_NEEDED",
20
+ "NEEDS-DECISION"
20
21
  ]
21
22
  },
22
23
  "notes": {
23
24
  "type": "string"
24
25
  },
26
+ "decision": {
27
+ "type": "object",
28
+ "description": "REQUIRED when verdict is \"NEEDS-DECISION\", otherwise omit. The decision only a human operator can make before the named bead can go on. The orchestrator files it for an operator verbatim (never truncated), sets the bead aside for the rest of the run without re-dispatching it, and keeps working other ready beads. Use it only for a real choice between alternatives you cannot settle from the bead, its parent or the code -- not for a missing secret or an unmet prerequisite (BLOCKED), and not for an ordinary failure.",
29
+ "required": [
30
+ "beadId",
31
+ "question",
32
+ "options",
33
+ "recommendation"
34
+ ],
35
+ "properties": {
36
+ "beadId": {
37
+ "type": "string",
38
+ "minLength": 1,
39
+ "description": "The one bead under review that cannot be approved or sent back for rework until the decision is made. The orchestrator reopens it if it is closed and sets it aside."
40
+ },
41
+ "question": {
42
+ "type": "string",
43
+ "minLength": 1,
44
+ "description": "The full question, self-contained: what was found, why it blocks the bead, and what must be decided. An operator reads only this and the options."
45
+ },
46
+ "options": {
47
+ "type": "array",
48
+ "minItems": 2,
49
+ "description": "At least two concrete alternatives, each with a short stable id (for example \"a\", \"b\") and its full text: what it means and what it costs.",
50
+ "items": {
51
+ "type": "object",
52
+ "required": [
53
+ "id",
54
+ "text"
55
+ ],
56
+ "properties": {
57
+ "id": {
58
+ "type": "string",
59
+ "minLength": 1
60
+ },
61
+ "text": {
62
+ "type": "string",
63
+ "minLength": 1
64
+ }
65
+ }
66
+ }
67
+ },
68
+ "recommendation": {
69
+ "type": "string",
70
+ "minLength": 1,
71
+ "description": "The option id you recommend, followed by why."
72
+ }
73
+ }
74
+ },
25
75
  "reopenIds": {
26
76
  "type": "array",
27
77
  "items": {
@@ -107,6 +157,39 @@
107
157
  }
108
158
  }
109
159
  },
160
+ "kb_demotions": {
161
+ "type": "array",
162
+ "description": "CONFIRMED entries a re-check during this review shows do not hold -- whether you are now less certain of the claim or have shown it wrong -- demoted back to INFERRED. Not for a drifted or removed basis. Reviewer-only, with the same evidence bar as kb_promotions and kb_discards. An id may appear in only one of kb_promotions, kb_discards and kb_demotions -- the engine refuses it in all lists it appears in. The engine makes the demotion calls.",
163
+ "items": {
164
+ "type": "object",
165
+ "required": [
166
+ "id",
167
+ "reason",
168
+ "evidence_files"
169
+ ],
170
+ "properties": {
171
+ "id": {
172
+ "type": "string",
173
+ "description": "The entry id, copied verbatim from the 'KNOWLEDGE BANK -- demotion candidates' block in your dispatch prompt. That block is the ONLY source of demotable ids -- do not call a kb_* tool to find one, and never invent one.",
174
+ "minLength": 1
175
+ },
176
+ "reason": {
177
+ "type": "string",
178
+ "description": "What you re-checked this review that the claim does not hold up against.",
179
+ "minLength": 20
180
+ },
181
+ "evidence_files": {
182
+ "type": "array",
183
+ "description": "The repo-relative files you re-checked -- at least one, each a real file in the repo.",
184
+ "minItems": 1,
185
+ "items": {
186
+ "type": "string",
187
+ "minLength": 1
188
+ }
189
+ }
190
+ }
191
+ }
192
+ },
110
193
  "kb_captures": {
111
194
  "type": "array",
112
195
  "description": "Durable knowledge this role verified during its run. The engine makes the kb_capture calls; the role only decides. Optional -- omit or send [] to capture nothing.",
@@ -190,5 +273,24 @@
190
273
  }
191
274
  }
192
275
  }
193
- }
276
+ },
277
+ "allOf": [
278
+ {
279
+ "if": {
280
+ "properties": {
281
+ "verdict": {
282
+ "const": "NEEDS-DECISION"
283
+ }
284
+ },
285
+ "required": [
286
+ "verdict"
287
+ ]
288
+ },
289
+ "then": {
290
+ "required": [
291
+ "decision"
292
+ ]
293
+ }
294
+ }
295
+ ]
194
296
  }
@@ -111,7 +111,11 @@ At sprint close, after the harvester runs:
111
111
  2. **Build summary**: run `buildSprintSummary(analysis, quote, calibration, opts)`
112
112
  where `opts = { branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen,
113
113
  startedAt }`. Write the returned `summaryText` to
114
- `sprint-logs/<branch>-<startedAt>.analysis.md` and commit it.
114
+ `sprint-logs/<branch>-<startedAt>.analysis.md`. Do NOT `git add` or commit it: it is a
115
+ local record. Before writing it, make sure the line `sprint-logs/*.analysis.md` is in
116
+ the repo's local git exclude file (the path `git rev-parse --git-path info/exclude`
117
+ prints; add the line only if it is not already there) so no later `git add -A` or
118
+ `git add sprint-logs/` stages it.
115
119
  3. **Update calibration**: run `computeUpdatedCalibration(calibration, analysis,
116
120
  startedAt, taskAssignments, logEntries)` and write the result back to
117
121
  `sprint-logs/calibration.json`. Commit it. This blends the actual token counts
@@ -11,12 +11,14 @@ code_graph, code_impact, code_query, and code_context tools.
11
11
  the repo path.
12
12
  3. Run via `execute_command` (wrap in background Agent per fleet rules):
13
13
  ```
14
- npx gitnexus analyze --index-only --embeddings
14
+ npx gitnexus analyze --index-only --force --embeddings
15
15
  ```
16
16
  - `run_from`: project repo root
17
- - `timeout_s`: 300 (indexing large repos can take a minute)
17
+ - `timeout_s`: 900 (a full build of a large repo can take several minutes)
18
18
  - `--index-only` keeps the repo work tree clean: without it gitnexus
19
19
  writes an AGENTS.md/CLAUDE.md block and skills folders into the repo.
20
+ - `--force` is required: an incremental analyze can corrupt the index, so
21
+ symbols that exist answer "not found".
20
22
  4. Report the result: nodes indexed, edges, flows (gitnexus prints this on
21
23
  completion). If gitnexus is not installed, it will be fetched automatically
22
24
  via npx.
@@ -31,9 +33,8 @@ code_graph, code_impact, code_query, and code_context tools.
31
33
  - One-time cost: the first `--embeddings` run on a machine downloads the
32
34
  model (~87 MB) from HuggingFace and caches it at `~/.cache/huggingface`;
33
35
  every run after that is offline.
34
- - Embeddings are OFF by default and PRESERVED across a plain `analyze`
35
- (only `--drop-embeddings` removes them), so passing `--embeddings` here is
36
- additive and safe to run repeatedly.
36
+ - Embeddings are OFF by default, and passing `--embeddings` here is safe to
37
+ run repeatedly.
37
38
  - win32 caveat: on Windows, LadybugDB's VECTOR index is unavailable, so
38
39
  semantic search falls back to an exact scan (capped at 10000 chunks) --
39
40
  this still works, it is just brute-force rather than an ANN index. Not a
@@ -44,15 +45,14 @@ code_graph, code_impact, code_query, and code_context tools.
44
45
 
45
46
  - **Automatically inside `/pm init`** -- runs as the final step of project initialization.
46
47
  The worktree must exist before indexing (gitnexus needs files on disk to analyze).
47
- - **Automatically at VERIFY checkpoints** -- checkpoints re-run npx gitnexus analyze --index-only to keep
48
- mid-sprint symbols visible to later phases (incremental via fileHashes in .gitnexus/meta.json,
49
- takes seconds).
48
+ - **Automatically at VERIFY checkpoints** -- checkpoints re-run npx gitnexus analyze --index-only --force to keep
49
+ mid-sprint symbols visible to later phases (a full rebuild, minutes on a large repo).
50
50
  - After a large merge or rebase that changes many files
51
51
  - When `kb_session_prime` returns many stale entries
52
52
  - Any time the user asks to re-index (run `/pm index` explicitly)
53
53
 
54
54
  ## Notes
55
55
 
56
- - Indexing is per-repo and persists on disk -- subsequent runs are incremental.
56
+ - Indexing is per-repo and persists on disk. Always pass `--force`: never run an incremental analyze.
57
57
  - The index is used by the gitnexus provider behind code_graph/impact/query/context.
58
58
  - Fleet members never call gitnexus directly -- they use the fleet tools.
@@ -211,7 +211,8 @@ MANDATORY CHECKLIST -- verify each before exiting:
211
211
  from `<skillDir>/cost.js` (the extracted module installed alongside this skill on
212
212
  every provider -- see `cost.md`) to produce `sprint-logs/<branch>-<startedAt>.analysis.md` and
213
213
  update `sprint-logs/calibration.json` with actual token data from this sprint.
214
- Commit both. See `cost.md` Harvest.
214
+ Commit `calibration.json` only; the `.analysis.md` stays local and git-excluded,
215
+ never committed. See `cost.md` Harvest.
215
216
  5. **Close the sprint root and the delivered issues** -- `bd close <sprint-id>`; also close
216
217
  any source beads issues this sprint implemented -- the ready backlog items the
217
218
  requirement was drawn from -- with `bd close <issue-id> ...`. Closing the sprint root