@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
@@ -119,6 +119,7 @@ export function vetKbWork(role, result) {
119
119
  const captures = [];
120
120
  const promotions = [];
121
121
  const refused = [];
122
+ const demotions = [];
122
123
 
123
124
  const rawCaptures = (result && Array.isArray(result.kb_captures)) ? result.kb_captures : [];
124
125
  for (const c of rawCaptures) {
@@ -189,22 +190,70 @@ export function vetKbWork(role, result) {
189
190
  }
190
191
  }
191
192
 
192
- // One output may not both CONFIRM and DISCARD the same entry: the two
193
- // judgements contradict each other, so neither is executed and both sides
194
- // are logged.
193
+ // kb_demotions: the reviewer's DEMOTE judgement -- a CONFIRMED entry a
194
+ // re-check shows does not hold (less certain, or shown wrong), sent back to
195
+ // INFERRED. Same role gate and reason bar as kb_promotions
196
+ // and kb_discards, plus at least one evidence file: kb_demote refuses a
197
+ // demotion without one, so it is refused here before any call.
198
+ const rawDemotions = (result && Array.isArray(result.kb_demotions)) ? result.kb_demotions : [];
199
+ if (rawDemotions.length > 0 && !KB_PROMOTER_ROLES.has(role)) {
200
+ refused.push(`${role}: kb_demotions refused -- demotion is reviewer-only`);
201
+ } else {
202
+ for (const d of rawDemotions) {
203
+ if (!d || typeof d.id !== 'string' || d.id.length === 0) {
204
+ refused.push(`${role}: demotion missing id`);
205
+ continue;
206
+ }
207
+ if (typeof d.reason !== 'string' || d.reason.trim().length < KB_MIN_PROMOTE_REASON) {
208
+ refused.push(`${role}: demotion ${d.id} has no recorded evidence`);
209
+ continue;
210
+ }
211
+ const evidenceFiles = Array.isArray(d.evidence_files)
212
+ ? d.evidence_files.filter((f) => typeof f === 'string' && f.length > 0)
213
+ : [];
214
+ if (evidenceFiles.length === 0) {
215
+ refused.push(`${role}: demotion ${d.id} names no evidence file`);
216
+ continue;
217
+ }
218
+ demotions.push({ id: d.id, reason: d.reason.trim(), evidence_files: evidenceFiles });
219
+ }
220
+ }
221
+
222
+ // One output may not judge the same entry more than one way: an id in
223
+ // more than one of kb_promotions, kb_discards and kb_demotions is refused
224
+ // in EVERY list it appears in, with a refusal logged per side naming the
225
+ // other judgements. The pre-existing two-way promote/discard behaviour is
226
+ // preserved exactly for the cases it already covered.
227
+ const promotionIds = new Set(promotions.map((p) => p.id));
195
228
  const discardIds = new Set(discards.map((d) => d.id));
196
- const conflicted = new Set(promotions.filter((p) => discardIds.has(p.id)).map((p) => p.id));
229
+ const demotionIds = new Set(demotions.map((d) => d.id));
230
+ const conflicted = new Set();
231
+ for (const id of promotionIds) if (discardIds.has(id) || demotionIds.has(id)) conflicted.add(id);
232
+ for (const id of discardIds) if (promotionIds.has(id) || demotionIds.has(id)) conflicted.add(id);
233
+ for (const id of demotionIds) if (promotionIds.has(id) || discardIds.has(id)) conflicted.add(id);
234
+
235
+ const otherSidesFor = (id, excludeKind) => {
236
+ const sides = [];
237
+ if (excludeKind !== 'promotion' && promotionIds.has(id)) sides.push('promotes');
238
+ if (excludeKind !== 'discard' && discardIds.has(id)) sides.push('discards');
239
+ if (excludeKind !== 'demotion' && demotionIds.has(id)) sides.push('demotes');
240
+ return sides;
241
+ };
197
242
  for (const p of promotions) {
198
- if (conflicted.has(p.id)) refused.push(`${role}: promotion ${p.id} refused -- the same output also discards it (promote reason: ${p.reason})`);
243
+ if (conflicted.has(p.id)) refused.push(`${role}: promotion ${p.id} refused -- the same output also ${otherSidesFor(p.id, 'promotion').join(' and ')} it (promote reason: ${p.reason})`);
199
244
  }
200
245
  for (const d of discards) {
201
- if (conflicted.has(d.id)) refused.push(`${role}: discard ${d.id} refused -- the same output also promotes it (discard reason: ${d.reason})`);
246
+ if (conflicted.has(d.id)) refused.push(`${role}: discard ${d.id} refused -- the same output also ${otherSidesFor(d.id, 'discard').join(' and ')} it (discard reason: ${d.reason})`);
247
+ }
248
+ for (const d of demotions) {
249
+ if (conflicted.has(d.id)) refused.push(`${role}: demotion ${d.id} refused -- the same output also ${otherSidesFor(d.id, 'demotion').join(' and ')} it (demote reason: ${d.reason})`);
202
250
  }
203
251
 
204
252
  return {
205
253
  captures,
206
254
  promotions: promotions.filter((p) => !conflicted.has(p.id)),
207
255
  discards: discards.filter((d) => !conflicted.has(d.id)),
256
+ demotions: demotions.filter((d) => !conflicted.has(d.id)),
208
257
  refused,
209
258
  };
210
259
  }
@@ -212,6 +261,142 @@ export function vetKbWork(role, result) {
212
261
  /** Max promotion candidates offered to one reviewer, so the prompt stays bounded. */
213
262
  export const KB_MAX_PROMOTION_CANDIDATES = 40;
214
263
 
264
+ /** Max demotion candidates offered to one reviewer, so the prompt stays bounded. */
265
+ export const KB_MAX_DEMOTION_CANDIDATES = 20;
266
+
267
+ /**
268
+ * How many owned CONFIRMED rows the demotion-candidate READ asks for, which is
269
+ * deliberately NOT the offer cap above.
270
+ *
271
+ * The cap is an OFFER cap -- how much of this prompt the candidate block may
272
+ * occupy. Using it as the read limit instead makes it a PRE-filter: a
273
+ * maintainer holding more owned CONFIRMED rows than the cap has an arbitrary
274
+ * 20 of them fetched, and the eligibility/changed-file filters then run over
275
+ * that arbitrary slice, so a genuinely relevant entry can be truncated away
276
+ * before anything ever looks at whether it is relevant. Read wide, filter,
277
+ * THEN cap.
278
+ */
279
+ export const KB_DEMOTION_READ_LIMIT = 500;
280
+
281
+ /**
282
+ * The EXACT kb_query arguments demotionCandidates issues, as a standalone
283
+ * pure function so the real read path can be exercised end-to-end against a
284
+ * real member session (tests/knowledge/) rather than only against a fake that
285
+ * re-states these arguments and therefore cannot catch them being wrong.
286
+ *
287
+ * Every field is load-bearing, and the previous shape of this read returned
288
+ * nothing in a real sprint:
289
+ *
290
+ * - `own_scope: true` is the whole fix. In a MEMBER session getSelfReadKb
291
+ * routes any read that does not explicitly name INFERRED/UNVERIFIED to the
292
+ * member's CHECKOUT BIBLE VIEW, and bible-import.ts stamps every row of
293
+ * that view `tags: []` -- so a CONFIRMED read filtered by a member tag can
294
+ * never match anything, in any sprint. own_scope forces the PER-REPO DB
295
+ * with the caller's own ownerTag applied, which is exactly the row set
296
+ * kb_demote's ownerTag check can act on.
297
+ * - `tag` is still required: kb_query refuses a call carrying neither
298
+ * `query`, `tag` nor `flagged_only`, and this is a listing, not a search.
299
+ * It names the same member tag own_scope's server-side ownerTag applies.
300
+ * - `confidence: ['CONFIRMED']` -- kb_demote refuses anything else
301
+ * (E-DEMOTE-NOT-CONFIRMED).
302
+ * - `include_stale: true` and `exclude_disputed: false` ADMIT the rows most
303
+ * worth demoting. SqliteProvider.demote() documents a STALE entry as
304
+ * demotable on purpose (staleness is a freshness verdict; trust is a
305
+ * separate axis), and a contradiction-flagged row is likewise demotable.
306
+ * The default read drops both, which silently excluded the best
307
+ * candidates.
308
+ * - include_stale ALSO admits SUPERSEDED rows (kb_query maps the one input
309
+ * flag onto both provider options), and kb_demote refuses those
310
+ * (E-DEMOTE-SUPERSEDED) -- so the caller must drop them itself. See
311
+ * isDemotableCandidate below.
312
+ *
313
+ * @param {string} memberId the maintainer member uuid whose session the read runs in
314
+ * @returns {object} kb_query arguments
315
+ */
316
+ export function buildDemotionCandidateQuery(memberId) {
317
+ return {
318
+ tag: `member:${memberId}`,
319
+ own_scope: true,
320
+ confidence: ['CONFIRMED'],
321
+ include_stale: true,
322
+ exclude_disputed: false,
323
+ limit: KB_DEMOTION_READ_LIMIT,
324
+ };
325
+ }
326
+
327
+ /**
328
+ * Whether kb_demote would ACCEPT this entry from its owner's session -- the
329
+ * eligibility set read off SqliteProvider.demote()'s refusals rather than
330
+ * guessed at, so the reviewer is never offered an id that can only produce a
331
+ * refusal:
332
+ *
333
+ * superseded_at set -> E-DEMOTE-SUPERSEDED
334
+ * type user-directive -> E-DEMOTE-REFUSED-DIRECTIVE
335
+ * confidence != CONFIRMED -> E-DEMOTE-NOT-CONFIRMED
336
+ *
337
+ * Ownership ("Entry not found" for a row without the caller's member tag) is
338
+ * enforced by the read itself (own_scope's ownerTag), not re-checked here.
339
+ *
340
+ * NOT a refusal, and deliberately NOT filtered: `stale` and
341
+ * `flagged_for_review`/`contradiction_of`. demote() permits a stale entry
342
+ * explicitly and calls those the ones most worth demoting.
343
+ *
344
+ * @param {object} entry
345
+ * @returns {boolean}
346
+ */
347
+ export function isDemotableCandidate(entry) {
348
+ if (!entry || typeof entry.id !== 'string' || !entry.id) return false;
349
+ if (entry.confidence !== 'CONFIRMED') return false;
350
+ if (entry.type === 'user-directive') return false;
351
+ if (entry.superseded_at) return false;
352
+ return true;
353
+ }
354
+
355
+ /**
356
+ * D6 in-sprint ping-pong guard: true when `entry` was demoted DURING THIS
357
+ * SPRINT -- i.e. its `demoted_at` (an INFERRED entry's kb_query row carries
358
+ * this when it was ever demoted, per rowToEntry) falls at or after the
359
+ * sprint's start. `since` is the sprint start in ms
360
+ * (createKbWorkClient's sprintStartMs()); when it is null the guard cannot
361
+ * tell "this sprint" from "ever demoted", so it answers false -- the SAME
362
+ * permissive default promotionCandidates' own created_at window filter uses
363
+ * for an unknown sprint start, never a reason to exclude.
364
+ *
365
+ * @param {object} entry
366
+ * @param {number|null} since
367
+ * @returns {boolean}
368
+ */
369
+ export function wasDemotedThisSprint(entry, since) {
370
+ if (!entry || typeof entry.demoted_at !== 'string' || since === null) return false;
371
+ const t = Date.parse(entry.demoted_at);
372
+ return Number.isFinite(t) && t >= since;
373
+ }
374
+
375
+ /**
376
+ * D6 in-sprint ping-pong guard: true when EVERY file `basis` (an entry's
377
+ * demoted_basis_hashes snapshot, taken AS THE FILES WERE ON DISK AT DEMOTE
378
+ * TIME) cites still hashes, in `current` (this moment's re-read), to the
379
+ * SAME value -- i.e. nothing the demotion was based on has changed since.
380
+ *
381
+ * NEVER A MATCH -- so the entry stays offered rather than silently
382
+ * ping-ponged out forever on an unprovable basis -- when: `basis` is
383
+ * missing or empty (a legacy row, or one demoted before this snapshot
384
+ * existed); `current` is missing (the disk-hash callback was never wired,
385
+ * or its read failed); or any cited file is absent from `current` (deleted,
386
+ * unreadable, or moved outside the checkout). This mirrors
387
+ * isDemotableCandidate's own "never falsely suppress" rule for an
388
+ * unparseable basis.
389
+ *
390
+ * @param {Record<string,string>|undefined} basis
391
+ * @param {Record<string,string>|undefined} current
392
+ * @returns {boolean}
393
+ */
394
+ export function demotionBasisUnchanged(basis, current) {
395
+ const files = basis ? Object.keys(basis) : [];
396
+ if (files.length === 0 || !current) return false;
397
+ return files.every((f) => typeof current[f] === 'string' && current[f] === basis[f]);
398
+ }
399
+
215
400
  /** Display label for a member record in log lines. */
216
401
  function memberLabel(member) {
217
402
  return (member && (member.name || member.id)) || 'unknown member';
@@ -249,6 +434,30 @@ function isUnreachableError(err) {
249
434
  return !!(err && typeof err.code === 'string' && err.code.length > 0 && !KB_TOOL_REJECTION_CODES.has(err.code));
250
435
  }
251
436
 
437
+ /**
438
+ * The error codes a remote (http) KB provider throws for a write the server
439
+ * never handled, each with the reason the engine logs:
440
+ * - E-KB-HTTP-UNREACHABLE: the KB server cannot be reached, or refused the
441
+ * request before handling it (429, 503);
442
+ * - E-KB-HTTP-AUTH: the KB server token (a named secret) is missing,
443
+ * expired or refused; the identical write succeeds once it is fixed.
444
+ * The provider queues nothing, so the engine owns the retry: a write that
445
+ * fails with one of these stays queued for the next flush.
446
+ */
447
+ const KB_SERVER_KEEP_CODES = Object.freeze([
448
+ ['E-KB-HTTP-UNREACHABLE', 'KB server unreachable'],
449
+ ['E-KB-HTTP-AUTH', 'KB server token refused'],
450
+ ]);
451
+
452
+ /** The keep-queued reason when a kb_* tool's error text carries one of KB_SERVER_KEEP_CODES, else null. */
453
+ function kbServerKeepReason(text) {
454
+ if (typeof text !== 'string') return null;
455
+ for (const [code, reason] of KB_SERVER_KEEP_CODES) {
456
+ if (new RegExp(`(^|[^A-Z-])${code}\\b`).test(text)) return reason;
457
+ }
458
+ return null;
459
+ }
460
+
252
461
  /** The member name a kb work call names (a member record or a bare name). */
253
462
  function memberNameOf(member) {
254
463
  if (typeof member === 'string') return member;
@@ -261,8 +470,8 @@ function memberNameOf(member) {
261
470
  * never through the member whose dispatch produced it, and never through the
262
471
  * orchestrator's own session.
263
472
  *
264
- * - apply() vets a role's kb_captures / kb_promotions, then QUEUES them per
265
- * repository and flushes that repository's queue.
473
+ * - apply() vets a role's kb_captures / kb_promotions / kb_demotions, then
474
+ * QUEUES them per repository and flushes that repository's queue.
266
475
  * - A flush runs the existing G-pull (opts.gPull -> git-sync's bracketed
267
476
  * syncMemberBefore) on the maintainer BEFORE the batch, so the
268
477
  * maintainer's checkout holds the files a capture cites and the KB's
@@ -277,29 +486,40 @@ function memberNameOf(member) {
277
486
  * maintainer and is dropped with a WARN.
278
487
  * - A write the maintainer cannot be reached for mid-batch is put back at
279
488
  * the head of the queue: nothing is lost and nothing is silently dropped.
489
+ * The same holds when the maintainer answers but its remote KB server
490
+ * cannot be reached or refuses the request before handling it
491
+ * (E-KB-HTTP-UNREACHABLE), or refuses its token (E-KB-HTTP-AUTH): the
492
+ * http provider queues nothing, so the engine keeps the write and
493
+ * retries it next flush.
280
494
  *
281
495
  * The bible commit (commitRound): every promotion the maintainer applied is
282
- * remembered per repository as a CONFIRMATION awaiting the bible. After each
283
- * review round (reviewer, final reviewer, harvester) the engine calls
284
- * commitRound(), which per repository with confirmations runs, on the
285
- * maintainer: G-pull, kb_bible_commit {ids, baseBranch, baseCommit}, G-push.
286
- * baseBranch is the sprint's TARGET BASE branch and baseCommit the base
287
- * commit the entries were verified against (opts.bibleBase resolves both on
288
- * the maintainer). A rejected G-push is retried exactly once: abort any
289
- * in-progress rebase, G-pull onto the new remote tip, kb_bible_commit again
290
- * with the same ids (it merges at entry level, so the concurrent change's
291
- * entries survive with no manual merge) and G-push again. A second failure
292
- * keeps the ids queued for the next round with a WARN. When kb_bible_commit
293
- * commits nothing (committed:false) the ids leave the queue only once origin
294
- * is shown to hold the bible (opts.bibleUnpushed): an earlier round's bible
295
- * commit still unpushed on the maintainer is G-pushed (same retry and reset
296
- * guards), and an undecidable check keeps the ids queued with a WARN. After
297
- * seal() (a FAIL verdict or an aborted sprint) nothing further is committed.
496
+ * remembered per repository as a CONFIRMATION, and every successful demotion
497
+ * as a pending DEMOTION, both awaiting the bible. After each review round
498
+ * (reviewer, final reviewer, harvester) the engine calls commitRound(), which
499
+ * per repository with confirmations and/or demotions runs, on the
500
+ * maintainer: G-pull, kb_bible_commit {ids, demoted_ids, baseBranch,
501
+ * baseCommit}, G-push -- ids and demoted_ids are ALWAYS sent in the same
502
+ * call, so a round that both confirms and demotes entries makes exactly one
503
+ * kb_bible_commit call. baseBranch is the sprint's TARGET BASE branch and
504
+ * baseCommit the base commit the entries were verified against (opts.bibleBase
505
+ * resolves both on the maintainer). A rejected G-push is retried exactly
506
+ * once: abort any in-progress rebase, G-pull onto the new remote tip,
507
+ * kb_bible_commit again with the same ids and demoted_ids (it merges at entry
508
+ * level, so the concurrent change's entries survive with no manual merge) and
509
+ * G-push again. A second failure keeps the ids/demoted_ids queued for the
510
+ * next round with a WARN. When kb_bible_commit commits nothing
511
+ * (committed:false) the ids leave the queue only once origin is shown to hold
512
+ * the bible (opts.bibleUnpushed): an earlier round's bible commit still
513
+ * unpushed on the maintainer is G-pushed (same retry and reset guards), and
514
+ * an undecidable check keeps the ids queued with a WARN. After seal() (a FAIL
515
+ * verdict or an aborted sprint) nothing further is committed.
298
516
  * An id kb_bible_commit skips with basis_mismatch stays queued and is offered
299
517
  * again next round (the mismatch can be transient), for at most
300
518
  * opts.bibleSkipRetryRounds (default KB_BIBLE_SKIP_RETRY_ROUNDS) skipped
301
519
  * rounds in a row, then is dropped with a WARN naming it and the reason; any
302
- * other skip reason drops the id at once.
520
+ * other skip reason drops the id at once. A skipped demotion
521
+ * (not_demoted_or_unknown) always leaves the queue: it never resolves itself
522
+ * without a new kb_demote.
303
523
  *
304
524
  * @param {{
305
525
  * memberCall?: (member: object, name: string, args: object, opts?: { kbMaintainer?: boolean }) => Promise<any>,
@@ -312,6 +532,8 @@ function memberNameOf(member) {
312
532
  * checkedOutBranch?: (memberName: string) => Promise<{ branch: string|null, sprintBranch: string|null }>,
313
533
  * bibleUnpushed?: (memberName: string, bibleFile: string) => Promise<{ unpushed: boolean|null, reason?: string }>,
314
534
  * unpushedOnlyBible?: (memberName: string, bibleFile: string) => Promise<{ onlyBible: boolean, reason?: string }>,
535
+ * roundChangedFiles?: (memberName: string) => Promise<string[]>,
536
+ * sprintChangedFiles?: (memberName: string) => Promise<string[]>,
315
537
  * sprintStartMs?: number|(() => number),
316
538
  * bibleSkipRetryRounds?: number,
317
539
  * log?: Function,
@@ -326,13 +548,57 @@ function memberNameOf(member) {
326
548
  export const KB_MAINTAINER_CALL = Object.freeze({ kbMaintainer: true });
327
549
 
328
550
  export function createKbWorkClient(opts = {}) {
329
- const { memberCall, gPull, gPush, abortRebase, bibleBase, canResetCheckout, checkedOutBranch, bibleUnpushed, unpushedOnlyBible, log = () => {} } = opts;
551
+ const {
552
+ memberCall, gPull, gPush, abortRebase, bibleBase, canResetCheckout, checkedOutBranch, bibleUnpushed, unpushedOnlyBible,
553
+ // THIS REVIEW ROUND's changed-file set for
554
+ // demotionCandidates() -- (memberName: string) => Promise<string[]>.
555
+ // Injected rather than computed here because the fetch/fast-forward
556
+ // merge and the git diff are git operations kb.mjs has no access to
557
+ // (every kb_* call here goes through memberCall, never a shell); see
558
+ // runner.js's wiring for how this fetches, merges and diffs from the
559
+ // previous round's tip (never the cumulative sprint diff diffFiles
560
+ // computes for the KB-injection hint context -- that caller and
561
+ // promotionCandidates are both left unchanged).
562
+ roundChangedFiles,
563
+ // The CUMULATIVE sprint changed-file set (baseBranch...branch) for a
564
+ // demotionCandidates({ scope: 'sprint' }) read -- the FINAL review's
565
+ // scope, because final review judges the whole sprint diff and so has
566
+ // no "this round" to speak of. Injected for the same reason
567
+ // roundChangedFiles is (the fetch/merge and git diff are git
568
+ // operations kb.mjs has no access to), and kept a SEPARATE injection
569
+ // rather than a flag on one callback so which diff a scope means is
570
+ // decided once, in runner.js's wiring, instead of inside a git helper.
571
+ sprintChangedFiles,
572
+ // D6 in-sprint ping-pong guard's disk-hash read --
573
+ // (memberName: string, files: string[]) => Promise<Record<string, string>>,
574
+ // the CURRENT sha256 of each file in `files` on `memberName`'s own
575
+ // checkout (absent files are simply missing from the result, never a
576
+ // fabricated hash). Injected for the same reason roundChangedFiles is:
577
+ // kb.mjs has no shell/fs access of its own, and this is the one disk
578
+ // fact kb_query cannot answer -- demoted_basis_hashes (surfaced on an
579
+ // INFERRED entry's kb_query row) is a demote-TIME snapshot, not a live
580
+ // one. MUST hash the SAME way SqliteProvider's demoteBasisHashes does
581
+ // (plain sha256 of the raw bytes) so the two sides compare like for
582
+ // like; see promotionCandidates' guard below. Optional: when not
583
+ // wired, the guard degrades to "never exclude" (see
584
+ // demotionBasisUnchanged), never to a failed or wrongly-filtered read.
585
+ currentFileHashes,
586
+ log = () => {},
587
+ } = opts;
330
588
  /** The sprint's start time (ms since epoch) from the sprint state, or null when unknown. */
331
589
  const sprintStartMs = () => {
332
590
  const v = typeof opts.sprintStartMs === 'function' ? opts.sprintStartMs() : opts.sprintStartMs;
333
591
  return (typeof v === 'number' && Number.isFinite(v)) ? v : null;
334
592
  };
335
593
  const active = typeof memberCall === 'function';
594
+ // Reviewer demotion loop switch (sprint arg kb_demotion_loop, CLI
595
+ // --kb-demotion-loop): 'on' (default when absent) or 'off'. Any other value
596
+ // fails loudly rather than silently falling back to a default.
597
+ const demotionLoopSetting = opts.demotionLoop === undefined ? 'on' : opts.demotionLoop;
598
+ if (demotionLoopSetting !== 'on' && demotionLoopSetting !== 'off') {
599
+ throw new Error(`[kb-work] Invalid demotionLoop ${JSON.stringify(demotionLoopSetting)}: must be 'on' (default) or 'off'.`);
600
+ }
601
+ const demotionLoopOn = demotionLoopSetting === 'on';
336
602
 
337
603
  /** The kb_maintainer selector (createKbMaintainerSelector), or null. */
338
604
  function selector() {
@@ -344,6 +610,8 @@ export function createKbWorkClient(opts = {}) {
344
610
  const queues = new Map();
345
611
  /** repo -> Set of candidate ids the latest promotionCandidates() call offered. */
346
612
  const offeredCandidates = new Map();
613
+ /** repo -> Set of candidate ids the latest demotionCandidates() call offered. */
614
+ const offeredDemotions = new Map();
347
615
  /** repo -> tail of the serialized flush chain for that repository. */
348
616
  const flushChains = new Map();
349
617
  /** member name -> open dispatch count (nested brackets count once each). */
@@ -352,6 +620,8 @@ export function createKbWorkClient(opts = {}) {
352
620
  const inFlight = new Map();
353
621
  /** repo -> ids the maintainer CONFIRMED that are not yet in a pushed bible commit (insertion order). */
354
622
  const confirmations = new Map();
623
+ /** repo -> ids the maintainer DEMOTED that are not yet in a pushed bible commit (insertion order). */
624
+ const demotedPending = new Map();
355
625
  /** repo -> (id -> rounds in a row kb_bible_commit skipped it with a retryable reason). */
356
626
  const skipRounds = new Map();
357
627
  const skipRetryRounds = Number.isInteger(opts.bibleSkipRetryRounds) && opts.bibleSkipRetryRounds > 0
@@ -483,7 +753,7 @@ export function createKbWorkClient(opts = {}) {
483
753
  }
484
754
  }
485
755
 
486
- const zeroCounts = () => ({ captured: 0, promoted: 0, discarded: 0 });
756
+ const zeroCounts = () => ({ captured: 0, promoted: 0, discarded: 0, demoted: 0 });
487
757
 
488
758
  const OPS = {
489
759
  capture: {
@@ -520,6 +790,12 @@ export function createKbWorkClient(opts = {}) {
520
790
  return true;
521
791
  },
522
792
  },
793
+ demote: {
794
+ tool: 'kb_demote',
795
+ args: (p) => ({ id: p.id, reason: p.reason, ...(Array.isArray(p.evidence_files) ? { evidence_files: p.evidence_files } : {}) }),
796
+ subject: (p) => p.id,
797
+ counter: 'demoted',
798
+ },
523
799
  };
524
800
 
525
801
  /**
@@ -561,6 +837,13 @@ export function createKbWorkClient(opts = {}) {
561
837
  }
562
838
  }
563
839
  const batch = queue.splice(0, queue.length);
840
+ // The KB server (not the maintainer) cannot be reached or refused the
841
+ // token: this write and every one behind it go back to the head of the
842
+ // queue for the next flush.
843
+ const keepForServer = (i, spec, op, text, reason) => {
844
+ queue.unshift(...batch.slice(i));
845
+ log(`[kb-work] WARN: ${reason} during ${spec.tool} for ${spec.subject(op.payload)} on maintainer '${maintainer}' (${text}) -- ${batch.length - i} KB write(s) for ${repo} stay queued`);
846
+ };
564
847
  for (let i = 0; i < batch.length; i++) {
565
848
  const op = batch[i];
566
849
  if (isBusy(maintainer)) {
@@ -592,6 +875,11 @@ export function createKbWorkClient(opts = {}) {
592
875
  log(`[kb-work] WARN: maintainer '${maintainer}' unreachable during ${spec.tool} for ${spec.subject(op.payload)} (${err.message}) -- ${batch.length - i} KB write(s) for ${repo} stay queued`);
593
876
  break;
594
877
  }
878
+ const thrownReason = kbServerKeepReason(err && err.message);
879
+ if (thrownReason) {
880
+ keepForServer(i, spec, op, err.message, thrownReason);
881
+ break;
882
+ }
595
883
  log(`[kb-work] ${spec.tool} failed for ${spec.subject(op.payload)} (non-fatal): ${err && err.message ? err.message : String(err)}`);
596
884
  continue;
597
885
  } finally {
@@ -601,7 +889,13 @@ export function createKbWorkClient(opts = {}) {
601
889
  // tool-level failure rather than throwing, so a non-throwing call
602
890
  // is not by itself a success.
603
891
  if (isToolError(res)) {
604
- log(`[kb-work] ${spec.tool} rejected for ${spec.subject(op.payload)} (non-fatal): ${toolErrorText(res)}`);
892
+ const text = toolErrorText(res);
893
+ const resultReason = kbServerKeepReason(text);
894
+ if (resultReason) {
895
+ keepForServer(i, spec, op, text, resultReason);
896
+ break;
897
+ }
898
+ log(`[kb-work] ${spec.tool} rejected for ${spec.subject(op.payload)} (non-fatal): ${text}`);
605
899
  continue;
606
900
  }
607
901
  if (typeof spec.accept === 'function' && !spec.accept(op.payload, res)) continue;
@@ -611,9 +905,13 @@ export function createKbWorkClient(opts = {}) {
611
905
  if (!confirmations.has(repo)) confirmations.set(repo, new Set());
612
906
  confirmations.get(repo).add(op.payload.id);
613
907
  }
908
+ if (op.kind === 'demote') {
909
+ if (!demotedPending.has(repo)) demotedPending.set(repo, new Set());
910
+ demotedPending.get(repo).add(op.payload.id);
911
+ }
614
912
  }
615
- if (counts.captured || counts.promoted || counts.discarded) {
616
- log(`[kb-work] maintainer '${maintainer}' (${repo}): captured ${counts.captured}, promoted ${counts.promoted}, discarded ${counts.discarded}`);
913
+ if (counts.captured || counts.promoted || counts.discarded || counts.demoted) {
914
+ log(`[kb-work] maintainer '${maintainer}' (${repo}): captured ${counts.captured}, promoted ${counts.promoted}, discarded ${counts.discarded}, demoted ${counts.demoted}`);
617
915
  }
618
916
  return counts;
619
917
  }
@@ -636,13 +934,29 @@ export function createKbWorkClient(opts = {}) {
636
934
  const errText = (err) => (err && err.message ? err.message : String(err));
637
935
 
638
936
  /**
639
- * What a bible commit carries, for its log lines: the confirmations, or
640
- * -- for a removal-only call (ids []) -- the pending bible removals.
937
+ * Log-message phrase for a (confirmation count, demotion count) pair,
938
+ * read naturally in every combination and -- critically -- IDENTICAL to
939
+ * the pre-existing "N confirmation(s)" wording when there are no pending
940
+ * demotions, so every pre-existing bible-commit log assertion (written
941
+ * before demotion support existed) keeps matching byte-for-byte.
942
+ */
943
+ const describeCounts = (n, m) => {
944
+ if (m === 0) return `${n} confirmation(s)`;
945
+ if (n === 0) return `${m} demotion(s)`;
946
+ return `${n} confirmation(s) and ${m} demotion(s)`;
947
+ };
948
+
949
+ /**
950
+ * What a bible commit carries, for its log lines: the confirmations and
951
+ * demotions, or -- for a removal-only call (no ids, no demotions) -- the
952
+ * pending bible removals.
641
953
  */
642
- const bibleLoad = (ids) => (ids.length > 0 ? `${ids.length} confirmation(s)` : 'the pending bible removal(s)');
643
- /** onSprintBranch for a bible commit carrying `ids` (see bibleLoad). */
644
- const bibleOnSprintBranch = (maintainer, repo, ids) => (ids.length > 0
645
- ? onSprintBranch(maintainer, repo, ids.length)
954
+ const bibleLoad = (ids, demoteIds) => (ids.length + demoteIds.length > 0
955
+ ? describeCounts(ids.length, demoteIds.length)
956
+ : 'the pending bible removal(s)');
957
+ /** onSprintBranch for a bible commit carrying `ids` and `demoteIds` (see bibleLoad). */
958
+ const bibleOnSprintBranch = (maintainer, repo, ids, demoteIds) => (ids.length + demoteIds.length > 0
959
+ ? onSprintBranch(maintainer, repo, ids.length + demoteIds.length)
646
960
  : onSprintBranch(maintainer, repo, 'the', 'pending bible removal'));
647
961
 
648
962
  /**
@@ -653,10 +967,15 @@ export function createKbWorkClient(opts = {}) {
653
967
  * maintainer holds a local bible commit the remote tip does not, so a
654
968
  * fast-forward pull would fail by construction; kb_bible_commit re-merges
655
969
  * the same ids at entry level on top of the new tip instead.
970
+ *
971
+ * `demoteIds` (defaulting to none) are this round's successful
972
+ * kb_demote() ids, passed as kb_bible_commit's `demoted_ids` in the SAME
973
+ * call as `ids` -- a round confirming some entries and demoting others
974
+ * produces exactly one kb_bible_commit call, never two.
656
975
  */
657
- async function bibleAttempt(target, repo, ids, { resetToRemoteTip = false } = {}) {
976
+ async function bibleAttempt(target, repo, ids, demoteIds = [], { resetToRemoteTip = false } = {}) {
658
977
  const maintainer = target.member;
659
- if (!(await bibleOnSprintBranch(maintainer, repo, ids))) return { ok: false, stage: 'branch check', error: 'the maintainer is not on the sprint branch', branchBlocked: true };
978
+ if (!(await bibleOnSprintBranch(maintainer, repo, ids, demoteIds))) return { ok: false, stage: 'branch check', error: 'the maintainer is not on the sprint branch', branchBlocked: true };
660
979
  try {
661
980
  await gPull(maintainer, resetToRemoteTip ? { resetToRemoteTip: true } : {});
662
981
  } catch (err) {
@@ -671,15 +990,24 @@ export function createKbWorkClient(opts = {}) {
671
990
  if (!base || typeof base.baseBranch !== 'string' || !base.baseBranch || typeof base.baseCommit !== 'string' || !base.baseCommit) {
672
991
  return { ok: false, stage: 'base resolution', error: 'the base branch or base commit could not be resolved on the maintainer' };
673
992
  }
674
- if (!(await bibleOnSprintBranch(maintainer, repo, ids))) return { ok: false, stage: 'branch check', error: 'the maintainer is not on the sprint branch', branchBlocked: true };
993
+ if (!(await bibleOnSprintBranch(maintainer, repo, ids, demoteIds))) return { ok: false, stage: 'branch check', error: 'the maintainer is not on the sprint branch', branchBlocked: true };
675
994
  let res;
676
995
  try {
677
- res = await memberCall(target.record, 'kb_bible_commit', { ids, baseBranch: base.baseBranch, baseCommit: base.baseCommit }, KB_MAINTAINER_CALL);
996
+ res = await memberCall(target.record, 'kb_bible_commit', {
997
+ ids,
998
+ ...(demoteIds.length > 0 ? { demoted_ids: demoteIds } : {}),
999
+ baseBranch: base.baseBranch,
1000
+ baseCommit: base.baseCommit,
1001
+ }, KB_MAINTAINER_CALL);
678
1002
  } catch (err) {
679
1003
  return { ok: false, stage: 'kb_bible_commit', error: errText(err), fleetTooOld: !!(err && err.code === E_MEMBER_FLEET_TOO_OLD) };
680
1004
  }
681
1005
  if (isToolError(res)) return { ok: false, stage: 'kb_bible_commit', error: toolErrorText(res) };
682
1006
  const result = parseResult(res) || {};
1007
+ // The tool skipped the whole call (e.g. the project KB is remote and has
1008
+ // no bible to commit to): nothing was committed, so there is nothing to
1009
+ // check or push. Return before the publication check and the G-push.
1010
+ if (result.bible_skipped === true) return { ok: true, result, pushed: false, bibleSkipped: true };
683
1011
  // Nothing committed (every id skipped, or the entry set unchanged).
684
1012
  // That alone does not mean the entries are published: an earlier
685
1013
  // round's bible commit may still sit unpushed on the maintainer (its
@@ -694,7 +1022,7 @@ export function createKbWorkClient(opts = {}) {
694
1022
  if (where.unpushed !== true) return { ok: false, stage: 'publication check', error: where.reason || 'whether origin holds the bible could not be established' };
695
1023
  log(`[kb-work] kb_bible_commit made no new commit on maintainer '${maintainer}', but an earlier bible commit is not on origin yet -- pushing it`);
696
1024
  }
697
- if (!(await bibleOnSprintBranch(maintainer, repo, ids))) return { ok: false, stage: 'branch check', error: 'the maintainer is not on the sprint branch', branchBlocked: true };
1025
+ if (!(await bibleOnSprintBranch(maintainer, repo, ids, demoteIds))) return { ok: false, stage: 'branch check', error: 'the maintainer is not on the sprint branch', branchBlocked: true };
698
1026
  // A bible push must publish the bible commit(s) only: never a doer
699
1027
  // commit that sits unpushed underneath them. Without an injected
700
1028
  // probe the push is allowed.
@@ -702,7 +1030,7 @@ export function createKbWorkClient(opts = {}) {
702
1030
  let verdict;
703
1031
  try { verdict = await unpushedOnlyBible(maintainer, BIBLE_FILE); } catch (err) { verdict = { onlyBible: false, reason: errText(err) }; }
704
1032
  if (!verdict || verdict.onlyBible !== true) {
705
- log(`[kb-work] WARN: not pushing the bible commit from maintainer '${maintainer}' (${repo}): ${(verdict && verdict.reason) || 'unknown'} -- a bible push must not publish other commits; ${bibleLoad(ids)} stay queued for the next round`);
1033
+ log(`[kb-work] WARN: not pushing the bible commit from maintainer '${maintainer}' (${repo}): ${(verdict && verdict.reason) || 'unknown'} -- a bible push must not publish other commits; ${bibleLoad(ids, demoteIds)} stay queued for the next round`);
706
1034
  return { ok: false, stage: 'push guard', error: (verdict && verdict.reason) || 'unpushed non-bible commits', branchBlocked: true };
707
1035
  }
708
1036
  }
@@ -773,70 +1101,88 @@ export function createKbWorkClient(opts = {}) {
773
1101
  }
774
1102
 
775
1103
  /**
776
- * Commit one repository's pending confirmations to the bible on its
777
- * maintainer. Never throws; ids that do not reach a pushed commit stay
778
- * pending for the next round.
1104
+ * Commit one repository's pending confirmations AND pending demotions to
1105
+ * the bible on its maintainer, in a single kb_bible_commit call (`ids` and
1106
+ * `demoted_ids` together -- see bibleAttempt). Never throws; ids that do
1107
+ * not reach a pushed commit stay pending for the next round.
779
1108
  * @returns {Promise<{ committed: number, pending: number }>}
780
1109
  */
781
1110
  async function commitRepo(repo) {
782
- const pending = confirmations.get(repo) || new Set();
783
- // No confirmations and no retirements: no call at all (no member
784
- // traffic). Retirements alone make a removal-only call with ids [].
785
- if (pending.size === 0 && !retirements.has(repo)) return { committed: 0, pending: 0 };
786
- const ids = [...pending];
787
- const load = bibleLoad(ids);
788
- if (sealedReason) return { committed: 0, pending: ids.length };
1111
+ const pending = confirmations.get(repo);
1112
+ const pendingDemoted = demotedPending.get(repo);
1113
+ const ids = pending ? [...pending] : [];
1114
+ const demoteIds = pendingDemoted ? [...pendingDemoted] : [];
1115
+ // No confirmations, no demotions and no retirements: no call at all (no
1116
+ // member traffic). Retirements alone make a removal-only call with ids [].
1117
+ if (ids.length === 0 && demoteIds.length === 0 && !retirements.has(repo)) return { committed: 0, pending: 0 };
1118
+ const totalPending = () => ids.length + demoteIds.length;
1119
+ const load = bibleLoad(ids, demoteIds);
1120
+ if (sealedReason) return { committed: 0, pending: totalPending() };
789
1121
  const sel = selector();
790
1122
  const target = sel && typeof sel.getKbMaintainer === 'function' ? sel.getKbMaintainer(repo) : null;
791
1123
  if (!target || !target.record) {
792
1124
  log(`[kb-work] WARN: repository ${repo} has no kb_maintainer -- ${load} stay queued for the bible`);
793
- return { committed: 0, pending: ids.length };
1125
+ return { committed: 0, pending: totalPending() };
794
1126
  }
795
1127
  const maintainer = target.member;
796
1128
  if (typeof gPull !== 'function' || typeof gPush !== 'function' || typeof bibleBase !== 'function') {
797
1129
  log(`[kb-work] WARN: no git sync wired for the bible commit -- ${load} for ${repo} stay queued`);
798
- return { committed: 0, pending: ids.length };
1130
+ return { committed: 0, pending: totalPending() };
799
1131
  }
800
1132
  if (isBusy(maintainer)) {
801
1133
  log(`[kb-work] WARN: maintainer '${maintainer}' is mid-dispatch -- ${load} for ${repo} stay queued for the next round's bible commit`);
802
- return { committed: 0, pending: ids.length };
1134
+ return { committed: 0, pending: totalPending() };
803
1135
  }
804
1136
  let release;
805
1137
  inFlight.set(maintainer, new Promise((r) => { release = r; }));
806
1138
  try {
807
- let outcome = await bibleAttempt(target, repo, ids);
1139
+ let outcome = await bibleAttempt(target, repo, ids, demoteIds);
808
1140
  if (!outcome.ok && outcome.stage === 'G-push') {
809
1141
  log(`[kb-work] G-push of the bible commit on maintainer '${maintainer}' (${repo}) was rejected (${outcome.error}) -- retrying once: rebase --abort, G-pull, kb_bible_commit, G-push`);
810
- if (typeof abortRebase === 'function' && (await bibleOnSprintBranch(maintainer, repo, ids))) {
1142
+ if (typeof abortRebase === 'function' && (await bibleOnSprintBranch(maintainer, repo, ids, demoteIds))) {
811
1143
  try { await abortRebase(maintainer); } catch (err) { log(`[kb-work] rebase --abort on maintainer '${maintainer}' failed (non-fatal): ${errText(err)}`); }
812
1144
  }
813
1145
  // The reset throws away the maintainer's local-only commits and
814
1146
  // uncommitted changes; it is usually also a doer, so only reset
815
1147
  // when that is the bible commit alone.
816
- if (!(await bibleOnSprintBranch(maintainer, repo, ids))) return { committed: 0, pending: ids.length };
817
- if (!(await resetIsSafe(maintainer, repo))) return { committed: 0, pending: ids.length };
818
- outcome = await bibleAttempt(target, repo, ids, { resetToRemoteTip: true });
1148
+ if (!(await bibleOnSprintBranch(maintainer, repo, ids, demoteIds))) return { committed: 0, pending: totalPending() };
1149
+ if (!(await resetIsSafe(maintainer, repo))) return { committed: 0, pending: totalPending() };
1150
+ outcome = await bibleAttempt(target, repo, ids, demoteIds, { resetToRemoteTip: true });
819
1151
  if (!outcome.ok && (outcome.stage === 'G-push' || outcome.stage === 'kb_bible_commit')) {
820
1152
  // Leave the checkout on the remote tip: an unpushed bible
821
1153
  // commit would make the maintainer's next fast-forward
822
1154
  // G-pull fail. The ids stay queued and are re-merged by
823
1155
  // the next round's kb_bible_commit.
824
- if (typeof abortRebase === 'function' && !outcome.branchBlocked && (await bibleOnSprintBranch(maintainer, repo, ids))) {
1156
+ if (typeof abortRebase === 'function' && !outcome.branchBlocked && (await bibleOnSprintBranch(maintainer, repo, ids, demoteIds))) {
825
1157
  try { await abortRebase(maintainer); } catch { /* best-effort */ }
826
1158
  }
827
- try { if ((await bibleOnSprintBranch(maintainer, repo, ids)) && (await resetIsSafe(maintainer, repo))) await gPull(maintainer, { resetToRemoteTip: true }); } catch (err) {
1159
+ try { if ((await bibleOnSprintBranch(maintainer, repo, ids, demoteIds)) && (await resetIsSafe(maintainer, repo))) await gPull(maintainer, { resetToRemoteTip: true }); } catch (err) {
828
1160
  log(`[kb-work] WARN: could not reset maintainer '${maintainer}' onto the remote tip after the failed bible commit: ${errText(err)}`);
829
1161
  }
830
1162
  }
831
1163
  }
832
- if (!outcome.ok && outcome.branchBlocked) return { committed: 0, pending: ids.length };
1164
+ if (!outcome.ok && outcome.branchBlocked) return { committed: 0, pending: totalPending() };
833
1165
  if (!outcome.ok && outcome.fleetTooOld) {
834
1166
  log(`[kb-work] WARNING: bible commit for ${repo} cannot run on maintainer '${maintainer}': ${outcome.error} -- ${load} stay queued for the next round`);
835
- return { committed: 0, pending: ids.length };
1167
+ return { committed: 0, pending: totalPending() };
836
1168
  }
837
1169
  if (!outcome.ok) {
838
1170
  log(`[kb-work] WARN: bible commit for ${repo} on maintainer '${maintainer}' failed at ${outcome.stage} (${outcome.error}) -- ${load} stay queued for the next round`);
839
- return { committed: 0, pending: ids.length };
1171
+ return { committed: 0, pending: totalPending() };
1172
+ }
1173
+ if (outcome.bibleSkipped) {
1174
+ // The skip is provider-wide, so a retry cannot succeed: drop the
1175
+ // repo's queue state (as for any non-retryable skip) so later
1176
+ // rounds do not repeat the call or warn about pending ids. The
1177
+ // demotion queue goes too: over a KB server the demotion already
1178
+ // happened on the server, and there is no bible to tombstone.
1179
+ const reason = typeof outcome.result.reason === 'string' && outcome.result.reason ? outcome.result.reason : 'no reason given';
1180
+ confirmations.delete(repo);
1181
+ demotedPending.delete(repo);
1182
+ skipRounds.delete(repo);
1183
+ retirements.delete(repo);
1184
+ log(`[kb-work] kb_bible_commit skipped for ${repo} on maintainer '${maintainer}': ${reason} -- ${ids.length} confirmation(s) and ${demoteIds.length} demotion(s) dropped from the bible queue.`);
1185
+ return { committed: 0, pending: 0 };
840
1186
  }
841
1187
  // The call succeeded: whatever retirements the maintainer held were
842
1188
  // removed by it (kb_bible_commit drops them at every call).
@@ -848,6 +1194,7 @@ export function createKbWorkClient(opts = {}) {
848
1194
  // and is offered again next round, for a bounded number of rounds.
849
1195
  // Any other skip (not CONFIRMED or unknown, no source files) cannot
850
1196
  // change by retrying and leaves the queue. Merged ids leave it too.
1197
+ // A round can carry demotions only, so pending may be absent.
851
1198
  if (!skipRounds.has(repo)) skipRounds.set(repo, new Map());
852
1199
  const rounds = skipRounds.get(repo);
853
1200
  const retained = [];
@@ -864,12 +1211,21 @@ export function createKbWorkClient(opts = {}) {
864
1211
  const keep = new Set(retained.map((x) => x.id));
865
1212
  for (const id of ids) {
866
1213
  if (keep.has(id)) continue;
867
- pending.delete(id);
1214
+ if (pending) pending.delete(id);
868
1215
  rounds.delete(id);
869
1216
  }
870
- if (pending.size === 0) confirmations.delete(repo);
1217
+ if (pending && pending.size === 0) confirmations.delete(repo);
871
1218
  if (rounds.size === 0) skipRounds.delete(repo);
872
- const merged = Array.isArray(outcome.result.merged) ? outcome.result.merged.length : ids.length - skipped.length;
1219
+ // Every demoted id leaves the queue, skipped ones included: a skipped
1220
+ // demotion (not_demoted_or_unknown) never resolves itself without a
1221
+ // new kb_demote.
1222
+ for (const id of demoteIds) if (pendingDemoted) pendingDemoted.delete(id);
1223
+ if (pendingDemoted && pendingDemoted.size === 0) demotedPending.delete(repo);
1224
+ const skippedIds = new Set(skipped.map((x) => x && x.id));
1225
+ const merged = Array.isArray(outcome.result.merged) ? outcome.result.merged.length
1226
+ : ids.length - ids.filter((id) => skippedIds.has(id)).length;
1227
+ const demoted = Array.isArray(outcome.result.demoted) ? outcome.result.demoted.length
1228
+ : demoteIds.length - demoteIds.filter((id) => skippedIds.has(id)).length;
873
1229
  const describe = (list) => list.map((x) => (x.reason ? `${x.id} (${x.reason})` : x.id)).join(', ');
874
1230
  if (dropped.length > 0) {
875
1231
  log(`[kb-work] kb_bible_commit skipped ${dropped.length} id(s) for ${repo} that cannot succeed on a retry (dropped from the queue, with the reason the tool returned): ${describe(dropped)}`);
@@ -887,18 +1243,70 @@ export function createKbWorkClient(opts = {}) {
887
1243
  if (removed.length > 0) {
888
1244
  log(`[kb-work] kb_bible_commit removed ${removed.length} superseded/invalidated entry(ies) from the bible for ${repo}: ${describe(removed)}`);
889
1245
  }
890
- if (ids.length === 0) {
1246
+ if (ids.length === 0 && demoteIds.length === 0) {
891
1247
  log(`[kb-work] removal-only bible commit for ${repo} on maintainer '${maintainer}': ${outcome.pushed ? `${removed.length} removal(s) committed and pushed` : 'nothing to remove -- nothing to push'}`);
892
1248
  } else {
893
- log(`[kb-work] bible commit for ${repo} on maintainer '${maintainer}': ${merged} confirmation(s) ${outcome.pushed ? 'committed and pushed' : 'already in the bible -- nothing to push'}`);
1249
+ log(`[kb-work] bible commit for ${repo} on maintainer '${maintainer}': ${describeCounts(merged, demoted)} ${outcome.pushed ? 'committed and pushed' : 'already in the bible -- nothing to push'}`);
894
1250
  }
895
- return { committed: outcome.pushed ? merged : 0, pending: pending.size };
1251
+ return { committed: outcome.pushed ? merged + demoted : 0, pending: (pending ? pending.size : 0) + (pendingDemoted ? pendingDemoted.size : 0) };
896
1252
  } finally {
897
1253
  inFlight.delete(maintainer);
898
1254
  release();
899
1255
  }
900
1256
  }
901
1257
 
1258
+ /**
1259
+ * The body of demotionCandidates(), run inside its isBusy/inFlight
1260
+ * bracket. Never throws.
1261
+ * @returns {Promise<object[]>}
1262
+ */
1263
+ async function readDemotionCandidates(target, changedFilesFor, scopeLabel) {
1264
+ // Same branch guard flushRepo/commitRepo apply before every G-pull
1265
+ // on the maintainer: a fast-forward merge does not care what
1266
+ // branch HEAD is currently on, only that HEAD is an ancestor of
1267
+ // the fetched tip, so pulling on a maintainer not actually on the
1268
+ // sprint branch could silently advance the wrong branch.
1269
+ if (!(await onSprintBranch(target.member, target.repo, 0, 'demotion candidate read'))) return [];
1270
+ let changed;
1271
+ try {
1272
+ changed = await changedFilesFor(target.member);
1273
+ } catch (err) {
1274
+ log(`[kb-work] could not compute ${scopeLabel} changed files on maintainer '${target.member}' (non-fatal): ${err.message}`);
1275
+ return [];
1276
+ }
1277
+ const files = Array.isArray(changed) ? changed.filter((f) => typeof f === 'string' && f.trim()) : [];
1278
+ if (files.length === 0) return [];
1279
+ try {
1280
+ const res = await memberCall(target.record, 'kb_query', buildDemotionCandidateQuery(target.record.id));
1281
+ if (isToolError(res)) {
1282
+ const text = toolErrorText(res);
1283
+ // A KB server that does not serve the optional demote route:
1284
+ // there is nothing the reviewer could demote, so offer nothing.
1285
+ if (/E-KB-HTTP-UNSUPPORTED/.test(text)) {
1286
+ log(`[kb-work] the KB server for ${target.repo} does not serve demote: offering no demotion candidates (${text})`);
1287
+ return [];
1288
+ }
1289
+ log(`[kb-work] kb_query for demotion candidates rejected on maintainer '${target.member}' (non-fatal): ${text}`);
1290
+ return [];
1291
+ }
1292
+ const parsed = parseResult(res);
1293
+ const results = parsed && Array.isArray(parsed.l1_results) ? parsed.l1_results
1294
+ : (parsed && Array.isArray(parsed.results) ? parsed.results : []);
1295
+ const fileSet = new Set(files);
1296
+ const touchesChangedFiles = (e) => Array.isArray(e.source_files) && e.source_files.some((f) => fileSet.has(f));
1297
+ // Filter the WHOLE read first (eligibility, then relevance),
1298
+ // and only cap the survivors -- see the method comment.
1299
+ const offered = results
1300
+ .filter((e) => isDemotableCandidate(e) && touchesChangedFiles(e))
1301
+ .slice(0, KB_MAX_DEMOTION_CANDIDATES);
1302
+ offeredDemotions.set(target.repo, new Set(offered.map((e) => e.id)));
1303
+ return offered;
1304
+ } catch (err) {
1305
+ log(`[kb-work] could not read demotion candidates from maintainer '${target.member}' (non-fatal): ${err.message}`);
1306
+ return [];
1307
+ }
1308
+ }
1309
+
902
1310
  function enqueue(repo, kind, role, payload) {
903
1311
  if (!queues.has(repo)) queues.set(repo, []);
904
1312
  queues.get(repo).push({ kind, role, payload });
@@ -955,26 +1363,29 @@ export function createKbWorkClient(opts = {}) {
955
1363
  for (const q of queues.values()) n += q.length;
956
1364
  return n;
957
1365
  },
958
- /** Log a WARN for every repository that still has queued writes or confirmations. */
1366
+ /** Log a WARN for every repository that still has queued writes, confirmations or demotions. */
959
1367
  warnPending() {
960
1368
  for (const [repo, q] of queues) {
961
- if (q.length > 0) log(`[kb-work] WARN: ${q.length} KB write(s) for ${repo} are still queued (maintainer busy or unreachable) -- not applied`);
1369
+ if (q.length > 0) log(`[kb-work] WARN: ${q.length} KB write(s) for ${repo} are still queued (maintainer busy or unreachable, or KB server unreachable or its token refused) -- not applied`);
962
1370
  }
963
1371
  for (const [repo, ids] of confirmations) {
964
1372
  if (ids.size > 0) log(`[kb-work] WARN: ${ids.size} confirmation(s) for ${repo} are not in a pushed bible commit${sealedReason ? ` (bible commits sealed: ${sealedReason})` : ''}`);
965
1373
  }
1374
+ for (const [repo, ids] of demotedPending) {
1375
+ if (ids.size > 0) log(`[kb-work] WARN: ${ids.size} demotion(s) for ${repo} are not in a pushed bible commit${sealedReason ? ` (bible commits sealed: ${sealedReason})` : ''}`);
1376
+ }
966
1377
  for (const repo of retirements) {
967
- if (!confirmations.has(repo)) log(`[kb-work] WARN: the pending bible removal(s) for ${repo} are not in a pushed bible commit${sealedReason ? ` (bible commits sealed: ${sealedReason})` : ''}`);
1378
+ if (!confirmations.has(repo) && !demotedPending.has(repo)) log(`[kb-work] WARN: the pending bible removal(s) for ${repo} are not in a pushed bible commit${sealedReason ? ` (bible commits sealed: ${sealedReason})` : ''}`);
968
1379
  }
969
1380
  },
970
1381
  /**
971
1382
  * The review-round bible commit: apply whatever is still queued, then
972
- * for every repository with confirmations, on its maintainer: G-pull,
973
- * kb_bible_commit, G-push (see the client header for the retry). A
974
- * repository with no confirmations but a discard applied since its
1383
+ * for every repository with confirmations and/or demotions, on its
1384
+ * maintainer: G-pull, kb_bible_commit (ids and demoted_ids together),
1385
+ * G-push (see the client header for the retry). A repository with neither
1386
+ * but a discard applied since its
975
1387
  * last bible commit gets a removal-only call (ids []). A round with
976
- * neither makes no call at all. A no-op once
977
- * sealed. Never throws.
1388
+ * neither makes no call at all. A no-op once sealed. Never throws.
978
1389
  * @param {string} [label] the round, for the log
979
1390
  * @returns {Promise<{ committed: number, pending: number }>}
980
1391
  */
@@ -984,13 +1395,14 @@ export function createKbWorkClient(opts = {}) {
984
1395
  if (sealedReason) {
985
1396
  let n = 0;
986
1397
  for (const ids of confirmations.values()) n += ids.size;
987
- if (n > 0) log(`[kb-work] ${label}: bible commits are sealed (${sealedReason}) -- ${n} confirmation(s) not committed`);
1398
+ for (const ids of demotedPending.values()) n += ids.size;
1399
+ if (n > 0) log(`[kb-work] ${label}: bible commits are sealed (${sealedReason}) -- ${n} confirmation(s)/demotion(s) not committed`);
988
1400
  return { committed: 0, pending: n };
989
1401
  }
990
1402
  for (const repo of [...queues.keys()]) {
991
1403
  if (queues.get(repo).length > 0) await flush(repo);
992
1404
  }
993
- for (const repo of new Set([...confirmations.keys(), ...retirements])) {
1405
+ for (const repo of new Set([...confirmations.keys(), ...demotedPending.keys(), ...retirements])) {
994
1406
  const r = await serialize(repo, () => commitRepo(repo));
995
1407
  out.committed += r.committed;
996
1408
  out.pending += r.pending;
@@ -999,15 +1411,16 @@ export function createKbWorkClient(opts = {}) {
999
1411
  },
1000
1412
  /**
1001
1413
  * Stop every further bible commit: a FAIL verdict or an aborted
1002
- * sprint commits nothing more, and the confirmation queue is not
1003
- * flushed. Idempotent; the first reason wins.
1414
+ * sprint commits nothing more, and the confirmation/demotion queues
1415
+ * are not flushed. Idempotent; the first reason wins.
1004
1416
  */
1005
1417
  seal(reason) {
1006
1418
  if (sealedReason) return;
1007
1419
  sealedReason = String(reason || 'sealed');
1008
1420
  let n = 0;
1009
1421
  for (const ids of confirmations.values()) n += ids.size;
1010
- log(`[kb-work] bible commits sealed (${sealedReason})${n > 0 ? ` -- ${n} confirmation(s) will not be committed` : ''}`);
1422
+ for (const ids of demotedPending.values()) n += ids.size;
1423
+ log(`[kb-work] bible commits sealed (${sealedReason})${n > 0 ? ` -- ${n} confirmation(s)/demotion(s) will not be committed` : ''}`);
1011
1424
  },
1012
1425
  /** Confirmations not yet in a pushed bible commit (all repositories, or one). */
1013
1426
  pendingConfirmations(repo) {
@@ -1051,6 +1464,22 @@ export function createKbWorkClient(opts = {}) {
1051
1464
  *
1052
1465
  * Best-effort by design -- a cold or unreachable KB must degrade to
1053
1466
  * "nothing to promote", never fail the review dispatch.
1467
+ *
1468
+ * D6 IN-SPRINT PING-PONG GUARD. Without this, an entry the reviewer
1469
+ * demoted in round N is offered right back for promotion in round
1470
+ * N+1 -- promotionCandidates' own in-window filter admits it (an
1471
+ * INFERRED entry created this sprint still matches, whether it got
1472
+ * there by a fresh capture or by a demotion of a CONFIRMED one), and
1473
+ * nothing has changed about it to re-judge. An entry wasDemotedThisSprint
1474
+ * (its demoted_at falls at or after sprintStartMs()) is excluded when
1475
+ * demotionBasisUnchanged is true for it -- i.e. unless at least one
1476
+ * of its cited files now hashes differently from the
1477
+ * demoted_basis_hashes snapshot taken at demote time (currentFileHashes,
1478
+ * read ONLY for the files these candidates actually cite, never
1479
+ * recomputed from scratch). A changed basis is new evidence, so that
1480
+ * entry stays offered. The guard runs HERE, at offering time -- a
1481
+ * ping-ponged id is never in the candidate block apply() later checks
1482
+ * offeredCandidates against, never merely refused there.
1054
1483
  */
1055
1484
  async promotionCandidates(member) {
1056
1485
  // The candidates live in the reviewer's repository MAINTAINER's KB
@@ -1088,12 +1517,36 @@ export function createKbWorkClient(opts = {}) {
1088
1517
  const t = typeof e.created_at === 'string' ? Date.parse(e.created_at) : NaN;
1089
1518
  return Number.isFinite(t) && t >= since;
1090
1519
  };
1091
- const offered = results
1520
+ const eligible = results
1092
1521
  // promote() refuses type='user-directive' outright (activation
1093
1522
  // is human-terminal, CLI-only), so offering one as a candidate
1094
1523
  // can only produce a guaranteed refusal.
1095
- .filter((e) => e && typeof e.id === 'string' && e.type !== 'user-directive' && inWindow(e))
1096
- .slice(0, KB_MAX_PROMOTION_CANDIDATES);
1524
+ .filter((e) => e && typeof e.id === 'string' && e.type !== 'user-directive' && inWindow(e));
1525
+ // D6 ping-pong guard (see the method comment): only entries
1526
+ // demoted THIS sprint are even candidates for exclusion, and
1527
+ // only a disk re-hash can tell whether their basis moved on
1528
+ // since. Reading is bounded to exactly the files THESE
1529
+ // candidates cite -- never every file in the repository --
1530
+ // and skipped entirely when there is nothing to check or no
1531
+ // callback wired, so the common case (no in-sprint demotion)
1532
+ // costs nothing extra.
1533
+ const pingPonged = eligible.filter((e) => wasDemotedThisSprint(e, since));
1534
+ let unchanged = new Set();
1535
+ if (pingPonged.length > 0 && typeof currentFileHashes === 'function') {
1536
+ const files = new Set();
1537
+ for (const e of pingPonged) for (const f of Object.keys(e.demoted_basis_hashes || {})) files.add(f);
1538
+ if (files.size > 0) {
1539
+ try {
1540
+ const current = await currentFileHashes(target.member, [...files]);
1541
+ for (const e of pingPonged) {
1542
+ if (demotionBasisUnchanged(e.demoted_basis_hashes, current)) unchanged.add(e.id);
1543
+ }
1544
+ } catch (err) {
1545
+ log(`[kb-work] could not re-hash the in-sprint ping-pong basis on maintainer '${target.member}' (non-fatal, nothing excluded): ${err.message}`);
1546
+ }
1547
+ }
1548
+ }
1549
+ const offered = eligible.filter((e) => !unchanged.has(e.id)).slice(0, KB_MAX_PROMOTION_CANDIDATES);
1097
1550
  offeredCandidates.set(target.repo, new Set(offered.map((e) => e.id)));
1098
1551
  return offered;
1099
1552
  } catch (err) {
@@ -1101,6 +1554,121 @@ export function createKbWorkClient(opts = {}) {
1101
1554
  return [];
1102
1555
  }
1103
1556
  },
1557
+ /**
1558
+ * The CONFIRMED entries this reviewer may demote back to INFERRED,
1559
+ * scoped to the review that is about to run.
1560
+ *
1561
+ * Mirrors promotionCandidates in every structural respect it shares
1562
+ * with it -- reviewMaintainerFor to resolve the reviewer's repository
1563
+ * MAINTAINER (refusing rather than reading some other KB when there is
1564
+ * none), replacing (never accumulating) the offered set up front so a
1565
+ * failed read leaves nothing offered from a prior round, and flushing
1566
+ * any writes still queued for that repository before the read -- and
1567
+ * reads the SAME owner-tagged rows at the OTHER confidence tier
1568
+ * (CONFIRMED rather than INFERRED). Every offered id is therefore one
1569
+ * kb_demote can actually apply: reviewMaintainerFor resolves exactly
1570
+ * the maintainer whose session kb_demote's ownerTag check requires.
1571
+ *
1572
+ * THE READ. buildDemotionCandidateQuery (above) is the whole of it,
1573
+ * and its `own_scope: true` is why this returns anything at all: a
1574
+ * MEMBER-session CONFIRMED read without it is answered from the
1575
+ * checkout bible view, whose rows are all untagged, so the owner
1576
+ * filter could never match and this offered nothing in every real
1577
+ * sprint. The read is also deliberately WIDE -- stale and
1578
+ * contradiction-flagged rows included, since kb_demote accepts both
1579
+ * and they are the ones most worth re-checking -- and limited to
1580
+ * KB_DEMOTION_READ_LIMIT rather than the offer cap.
1581
+ *
1582
+ * THEN FILTER, THEN CAP, in that order. Eligibility
1583
+ * (isDemotableCandidate: drops superseded, user-directive and any
1584
+ * non-CONFIRMED row the read let through) and changed-file relevance
1585
+ * run over the WHOLE read; only the survivors are capped at
1586
+ * KB_MAX_DEMOTION_CANDIDATES. Capping first would make the offer cap
1587
+ * a read pre-filter and let a maintainer with many owned CONFIRMED
1588
+ * rows have every genuinely relevant one truncated away before
1589
+ * anything checked whether it was relevant.
1590
+ *
1591
+ * SCOPE IS AN ARGUMENT, NOT A GUESS ABOUT THE CALLER. UNLIKE
1592
+ * promotionCandidates (windowed by sprint start time), an entry is
1593
+ * kept only when it touches a file in the changed-file set of the
1594
+ * review being prepared, and WHICH set that is comes from
1595
+ * `opts.scope`, never from inspecting who called:
1596
+ *
1597
+ * 'round' (default) -- a PER-ROUND review. `roundChangedFiles`
1598
+ * fetches and fast-forward-merges the maintainer's checkout, THEN
1599
+ * diffs from the previous round's merged tip (or, on the first
1600
+ * round, the sprint's base branch) to the new one. Computed AFTER
1601
+ * the merge so it reflects this round's commits rather than a
1602
+ * stale pre-merge snapshot.
1603
+ * 'sprint' -- the FINAL review, which judges the whole sprint diff
1604
+ * and therefore has no "this round": `sprintChangedFiles` gives
1605
+ * the CUMULATIVE baseBranch...branch diff.
1606
+ *
1607
+ * Neither is kbInjection's `diffFiles` (the KB-injection hint
1608
+ * context's own cumulative diff), and promotionCandidates is
1609
+ * unchanged by all of this.
1610
+ *
1611
+ * Demoting a CONFIRMED claim this review never re-checked is never
1612
+ * this review's to offer, so an empty changed-file set offers
1613
+ * nothing.
1614
+ *
1615
+ * Best-effort like every other KB read here: no maintainer, an
1616
+ * unreachable one, no changed-files callback wired for the requested
1617
+ * scope, a diff that could not be computed, or an erroring/rejecting
1618
+ * kb_query all degrade to [] and must never fail the review dispatch
1619
+ * -- per-round or final.
1620
+ *
1621
+ * @param {object} member
1622
+ * @param {{ scope?: 'round'|'sprint' }} [opts]
1623
+ * @returns {Promise<object[]>}
1624
+ */
1625
+ async demotionCandidates(member, { scope = 'round' } = {}) {
1626
+ // Explicit, and explicitly validated: an unknown scope is a wiring
1627
+ // bug, and silently falling back to the round diff at FINAL review
1628
+ // would offer the reviewer a set scoped to a round that does not
1629
+ // exist. Degrade to nothing rather than to the wrong scope.
1630
+ if (!demotionLoopOn) {
1631
+ log("[kb-work] reviewer demotion loop is disabled by the kb_demotion_loop setting ('off'): offering no demotion candidates.");
1632
+ offeredDemotions.clear();
1633
+ return [];
1634
+ }
1635
+ if (scope !== 'round' && scope !== 'sprint') {
1636
+ log(`[kb-work] demotion candidates requested with unknown scope '${scope}' (non-fatal): offering none.`);
1637
+ return [];
1638
+ }
1639
+ const changedFilesFor = scope === 'sprint' ? sprintChangedFiles : roundChangedFiles;
1640
+ const scopeLabel = scope === 'sprint' ? "this sprint's cumulative" : "this round's";
1641
+ const target = active ? reviewMaintainerFor(memberNameOf(member)) : null;
1642
+ if (!target) return [];
1643
+ // Replace (never accumulate) this review scope's offered set up
1644
+ // front, so a failed read leaves nothing offered from a prior
1645
+ // round -- and so the FINAL review's call cannot inherit the last
1646
+ // per-round call's offers either.
1647
+ offeredDemotions.set(target.repo, new Set());
1648
+ // Writes still queued for this repository (a capture or a
1649
+ // promotion/discard from this very round) get their chance to
1650
+ // land before the read, same as promotionCandidates.
1651
+ if (queues.has(target.repo)) await flush(target.repo);
1652
+ if (typeof changedFilesFor !== 'function') return [];
1653
+ // Same isBusy/inFlight bracket flushRepo and commitRepo use: the
1654
+ // read below G-pulls the maintainer's checkout and runs git and
1655
+ // kb_query there, so it must neither start while a dispatch is
1656
+ // running on the maintainer nor run concurrently with one that
1657
+ // starts mid-read (dispatchStarted() awaits the inFlight entry).
1658
+ // Taken AFTER flush() above, which brackets itself.
1659
+ if (isBusy(target.member)) {
1660
+ log(`[kb-work] maintainer '${target.member}' is mid-dispatch -- no pull and no demotion candidate read over ${scopeLabel} changed files for ${target.repo}; offering none`);
1661
+ return [];
1662
+ }
1663
+ let release;
1664
+ inFlight.set(target.member, new Promise((r) => { release = r; }));
1665
+ try {
1666
+ return await readDemotionCandidates(target, changedFilesFor, scopeLabel);
1667
+ } finally {
1668
+ inFlight.delete(target.member);
1669
+ release();
1670
+ }
1671
+ },
1104
1672
  /**
1105
1673
  * KB audit follow-up: the per-dispatch, relevance-ranked read.
1106
1674
  *
@@ -1183,23 +1751,30 @@ export function createKbWorkClient(opts = {}) {
1183
1751
  * record or a bare name); it decides WHICH repository, never which
1184
1752
  * session -- no write is ever sent to it unless it is the maintainer.
1185
1753
  *
1186
- * @returns {Promise<{captured: number, promoted: number, discarded: number, refused: number}>}
1754
+ * @returns {Promise<{captured: number, promoted: number, discarded: number, demoted: number, refused: number}>}
1187
1755
  * counts of the writes applied by this call's flush (writes left
1188
1756
  * queued for a busy or unreachable maintainer are not counted).
1189
1757
  */
1190
1758
  async apply(role, member, result) {
1191
- const { captures, promotions, discards, refused } = vetKbWork(role, result);
1759
+ const vetted = vetKbWork(role, result);
1760
+ const { captures, promotions, discards, refused } = vetted;
1761
+ let demotions = vetted.demotions;
1762
+ if (!demotionLoopOn && demotions.length > 0) {
1763
+ log(`[kb-work] reviewer demotion loop is disabled by the kb_demotion_loop setting ('off'): ${demotions.length} demotion(s) from ${role} dropped, no kb_demote issued.`);
1764
+ demotions = [];
1765
+ }
1192
1766
 
1193
1767
  for (const r of refused) log(`[kb-work] refused -- ${r}`);
1194
1768
  // Log every promotion with its stated evidence BEFORE attempting it.
1195
1769
  // This log is the audit trail the bible never had.
1196
1770
  for (const p of promotions) log(`[kb-work] promote ${p.id} (${role}): ${p.reason}`);
1197
1771
  for (const d of discards) log(`[kb-work] discard ${d.id} (${role}): ${d.reason}`);
1772
+ for (const d of demotions) log(`[kb-work] demote ${d.id} (${role}): ${d.reason}`);
1198
1773
 
1199
1774
  let extraRefused = 0;
1200
1775
  const done = (counts) => ({ ...counts, refused: refused.length + extraRefused });
1201
- if (captures.length === 0 && promotions.length === 0 && discards.length === 0) return done(zeroCounts());
1202
- const dropped = `${captures.length} capture(s), ${promotions.length} promotion(s) and ${discards.length} discard(s) dropped`;
1776
+ if (captures.length === 0 && promotions.length === 0 && discards.length === 0 && demotions.length === 0) return done(zeroCounts());
1777
+ const dropped = `${captures.length} capture(s), ${promotions.length} promotion(s), ${discards.length} discard(s) and ${demotions.length} demotion(s) dropped`;
1203
1778
 
1204
1779
  const producer = memberNameOf(member);
1205
1780
  // Without a resolved member there is no repository the writes
@@ -1212,9 +1787,10 @@ export function createKbWorkClient(opts = {}) {
1212
1787
  const nonRepo = !!(sel && typeof sel.isNonRepoMember === 'function' && sel.isNonRepoMember(producer));
1213
1788
  // A capture belongs to the PRODUCER's repository: a member whose
1214
1789
  // work folder is not a repository has none, so its captures are
1215
- // dropped. Review judgements (CONFIRM/DISCARD) act on candidates
1216
- // read from the reviewer's maintainer (reviewMaintainerFor), so
1217
- // they follow the same resolution as the candidate read.
1790
+ // dropped. Review judgements (CONFIRM/DISCARD/DEMOTE) act on
1791
+ // candidates read from the reviewer's maintainer
1792
+ // (reviewMaintainerFor), so they follow the same resolution as
1793
+ // the candidate read.
1218
1794
  let target = null;
1219
1795
  if (captures.length > 0) {
1220
1796
  if (nonRepo) {
@@ -1229,23 +1805,28 @@ export function createKbWorkClient(opts = {}) {
1229
1805
  }
1230
1806
  }
1231
1807
  const repos = new Set(target ? [target.repo] : []);
1232
- if (promotions.length > 0 || discards.length > 0) {
1808
+ if (promotions.length > 0 || discards.length > 0 || demotions.length > 0) {
1233
1809
  const review = reviewMaintainerFor(producer);
1234
1810
  if (review) {
1235
1811
  // Only ids offered in this dispatch's candidate block may be
1236
1812
  // judged; anything else is refused before any kb_* call.
1813
+ // Demotions are filtered against their OWN offered set
1814
+ // (offeredDemotions), never the promotion one -- an id
1815
+ // offered for promotion is not thereby offered for demotion.
1237
1816
  const offered = offeredCandidates.get(review.repo) || new Set();
1238
- const inBlock = (kind, x) => {
1239
- if (offered.has(x.id)) return true;
1817
+ const offeredToDemote = offeredDemotions.get(review.repo) || new Set();
1818
+ const inBlock = (kind, x, offeredSet) => {
1819
+ if (offeredSet.has(x.id)) return true;
1240
1820
  log(`[kb-work] refused -- ${role}: ${kind} ${x.id} not in this dispatch's candidate block`);
1241
1821
  extraRefused += 1;
1242
1822
  return false;
1243
1823
  };
1244
- for (const p of promotions) if (inBlock('promotion', p)) enqueue(review.repo, 'promote', role, p);
1245
- for (const d of discards) if (inBlock('discard', d)) enqueue(review.repo, 'discard', role, d);
1824
+ for (const p of promotions) if (inBlock('promotion', p, offered)) enqueue(review.repo, 'promote', role, p);
1825
+ for (const d of discards) if (inBlock('discard', d, offered)) enqueue(review.repo, 'discard', role, d);
1826
+ for (const d of demotions) if (inBlock('demotion', d, offeredToDemote)) enqueue(review.repo, 'demote', role, d);
1246
1827
  repos.add(review.repo);
1247
1828
  } else {
1248
- log(`[kb-work] WARN: no kb_maintainer for member '${producer}' (${role}) -- ${promotions.length} promotion(s) and ${discards.length} discard(s) dropped`);
1829
+ log(`[kb-work] WARN: no kb_maintainer for member '${producer}' (${role}) -- ${promotions.length} promotion(s), ${discards.length} discard(s) and ${demotions.length} demotion(s) dropped`);
1249
1830
  }
1250
1831
  }
1251
1832
  const counts = zeroCounts();
@@ -1484,7 +2065,11 @@ export function createKbPrimingClient(opts = {}) {
1484
2065
  } else {
1485
2066
  log(`[kb-prime] no base branch -- bible import skipped for '${member}' (the kb_maintainer imports only the base branch's committed bible)`);
1486
2067
  }
1487
- if (imported && typeof imported.imported === 'number' && imported.imported > 0) {
2068
+ if (imported && imported.bible_skipped === true) {
2069
+ // An http project KB: the KB server is the source of
2070
+ // truth, so the member imported nothing.
2071
+ log(`[kb-prime] no bible import for '${member}': ${imported.reason || 'the KB is served over http'}`);
2072
+ } else if (imported && typeof imported.imported === 'number' && imported.imported > 0) {
1488
2073
  log(`[kb-prime] imported ${imported.imported} bible entr(ies) into the warm KB for '${member}'`);
1489
2074
  }
1490
2075
  } catch (err) {
@@ -1648,6 +2233,56 @@ export function kbKnowledgeBlock(entries, { captureChannel = true, source = 'pri
1648
2233
  ];
1649
2234
  }
1650
2235
 
2236
+ /**
2237
+ * KNOWLEDGE BANK -- demotion candidates. Same bounded shape as
2238
+ * kbPromotionBlock (list the offered ids with enough context to judge, say
2239
+ * nothing when the list is empty) -- the two are read side by side in the
2240
+ * reviewer prompt and must not drift.
2241
+ *
2242
+ * Demotion is CONFIRMED -> INFERRED only, and only for an id actually
2243
+ * offered here (the engine refuses any other id, same as promotion/discard).
2244
+ * ONE judgement: a re-check during this review shows the claim does not hold
2245
+ * -- the reviewer is less certain of it, or has shown it wrong. A drifted or
2246
+ * removed basis is NOT a demote case -- the freshness sweep and the bible
2247
+ * basis predicate already handle that without reviewer judgment.
2248
+ *
2249
+ * @param {object[]|undefined} kbCandidates
2250
+ * @returns {string[]}
2251
+ */
2252
+ export function kbDemotionBlock(kbCandidates) {
2253
+ if (!Array.isArray(kbCandidates) || kbCandidates.length === 0) return [];
2254
+ return [
2255
+ 'KNOWLEDGE BANK -- demotion candidates. These entries are currently CONFIRMED. You are '
2256
+ + 'the only role that can demote one back to INFERRED. Do NOT call any '
2257
+ + 'kb_* tool yourself: return your decisions in your structured output and the '
2258
+ + 'orchestrator executes them -- `kb_demotions` as [{id, reason, evidence_files}] for '
2259
+ + 'entries to demote back to INFERRED.\n'
2260
+ + 'Demote when a re-check during THIS review shows the claim does not hold -- whether '
2261
+ + 'you are now less certain of it or have shown it wrong, it is the same judgement and '
2262
+ + 'the same route. `evidence_files` names the files you re-checked: at least one, each a '
2263
+ + 'real file in the repo; a demotion without one is refused. This is NOT the route for a '
2264
+ + 'drifted or removed basis (the cited code changed or vanished) -- freshness staling and '
2265
+ + 'the bible basis predicate already handle that case without you. Discarding an '
2266
+ + 'unconfirmed (INFERRED) capture you showed to be wrong is `kb_discards` (Step 5), never '
2267
+ + 'a demotion -- demotion only ever applies to an already-CONFIRMED entry.\n'
2268
+ + 'The `reason` must state what you checked this review that contradicts the claim '
2269
+ + '(at least 20 characters, e.g. "re-ran the reopen test cited by this entry and it now '
2270
+ + 'fails"). Demoting nothing is a valid outcome; return [] in that case. Never list the '
2271
+ + 'same id in more than one of `kb_promotions`, `kb_discards` and `kb_demotions`; the '
2272
+ + 'orchestrator refuses it in every list it appears in.\n'
2273
+ + wrapUntrustedBlock('kb_query --tag member:<maintainer> --confidence CONFIRMED', JSON.stringify(
2274
+ kbCandidates.map((e) => ({
2275
+ id: e.id,
2276
+ title: e.title,
2277
+ summary: e.summary,
2278
+ source_files: e.source_files,
2279
+ })),
2280
+ null,
2281
+ 2
2282
+ )),
2283
+ ];
2284
+ }
2285
+
1651
2286
  export function kbPromotionBlock(kbCandidates) {
1652
2287
  if (!Array.isArray(kbCandidates) || kbCandidates.length === 0) return [];
1653
2288
  return [