@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.
- package/README.md +49 -4
- package/dist/agents/backlog-groomer.md +5 -0
- package/dist/agents/ci-watcher.md +5 -0
- package/dist/agents/deployer.md +20 -2
- package/dist/agents/doer.md +38 -2
- package/dist/agents/harvester.md +12 -9
- package/dist/agents/integ-test-runner.md +5 -0
- package/dist/agents/kb-reconciler.md +6 -0
- package/dist/agents/plan-reviewer.md +5 -0
- package/dist/agents/planner.md +5 -0
- package/dist/agents/regression-test-runner.md +5 -0
- package/dist/agents/reviewer.md +67 -15
- package/dist/agents/schemas/deployer-output.json +5 -0
- package/dist/agents/schemas/doer-output.json +78 -2
- package/dist/agents/schemas/reviewer-output.json +104 -2
- package/dist/cli/auth.js +5 -1
- package/dist/cli/beads-pin.js +6 -7
- package/dist/cli/claude-mod.d.ts +75 -0
- package/dist/cli/claude-mod.js +288 -0
- package/dist/cli/dolt-install.d.ts +1 -1
- package/dist/cli/dolt-install.js +5 -1
- package/dist/cli/fleet-se-guard.d.ts +8 -0
- package/dist/cli/fleet-se-guard.js +19 -3
- package/dist/cli/install-guard.d.ts +9 -0
- package/dist/cli/install-guard.js +24 -0
- package/dist/cli/install.d.ts +12 -0
- package/dist/cli/install.js +180 -20
- package/dist/cli/kb-profile.d.ts +16 -0
- package/dist/cli/kb-profile.js +81 -0
- package/dist/cli/start.js +3 -0
- package/dist/cli/uninstall.js +13 -3
- package/dist/cli/update.d.ts +4 -0
- package/dist/cli/update.js +19 -3
- package/dist/commands/kb-server.d.ts +10 -1
- package/dist/commands/kb-server.js +285 -11
- package/dist/index.js +22 -1
- package/dist/os/git-executable.d.ts +57 -0
- package/dist/os/git-executable.js +85 -0
- package/dist/os/go-concurrency.d.ts +44 -0
- package/dist/os/go-concurrency.js +53 -0
- package/dist/os/index.d.ts +1 -0
- package/dist/os/index.js +1 -0
- package/dist/os/linux.d.ts +2 -0
- package/dist/os/linux.js +10 -1
- package/dist/os/os-commands.d.ts +25 -0
- package/dist/os/os-commands.js +2 -0
- package/dist/os/windows-executable.d.ts +53 -0
- package/dist/os/windows-executable.js +185 -0
- package/dist/os/windows-gitbash.d.ts +23 -14
- package/dist/os/windows-gitbash.js +40 -16
- package/dist/os/windows.d.ts +2 -0
- package/dist/os/windows.js +37 -6
- package/dist/paths.d.ts +10 -1
- package/dist/paths.js +19 -2
- package/dist/services/agy-project.d.ts +7 -1
- package/dist/services/agy-project.js +7 -2
- package/dist/services/auth-socket.d.ts +18 -0
- package/dist/services/auth-socket.js +30 -4
- package/dist/services/credential-store.d.ts +33 -0
- package/dist/services/credential-store.js +79 -2
- package/dist/services/http-transport.d.ts +29 -0
- package/dist/services/http-transport.js +166 -37
- package/dist/services/kb-tool-profile.d.ts +36 -0
- package/dist/services/kb-tool-profile.js +88 -0
- package/dist/services/knowledge/bible-blob-id.js +10 -1
- package/dist/services/knowledge/bible-import.d.ts +108 -0
- package/dist/services/knowledge/bible-import.js +137 -4
- package/dist/services/knowledge/file-hash.js +6 -5
- package/dist/services/knowledge/http-provider.d.ts +303 -20
- package/dist/services/knowledge/http-provider.js +795 -125
- package/dist/services/knowledge/kb-config.d.ts +65 -1
- package/dist/services/knowledge/kb-config.js +143 -3
- package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
- package/dist/services/knowledge/kb-http-auth-state.js +40 -0
- package/dist/services/knowledge/kb-providers.d.ts +9 -2
- package/dist/services/knowledge/kb-providers.js +67 -37
- package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
- package/dist/services/knowledge/kb-self.d.ts +122 -9
- package/dist/services/knowledge/kb-self.js +196 -36
- package/dist/services/knowledge/member-bible-view.js +16 -3
- package/dist/services/knowledge/path-validation.d.ts +7 -0
- package/dist/services/knowledge/path-validation.js +11 -0
- package/dist/services/knowledge/project-slug.js +3 -2
- package/dist/services/knowledge/repository-header.d.ts +77 -0
- package/dist/services/knowledge/repository-header.js +233 -0
- package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
- package/dist/services/knowledge/require-sqlite-project.js +1 -1
- package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
- package/dist/services/knowledge/sqlite-provider.js +416 -4
- package/dist/services/knowledge/types.d.ts +15 -2
- package/dist/services/member-busy.d.ts +12 -0
- package/dist/services/member-busy.js +20 -0
- package/dist/services/member-config-io.d.ts +3 -2
- package/dist/services/member-config-io.js +7 -4
- package/dist/services/member-fleet-install.js +1 -0
- package/dist/services/member-tool-allowlist.d.ts +1 -1
- package/dist/services/member-tool-allowlist.js +8 -4
- package/dist/services/port-holder.js +2 -1
- package/dist/services/service-manager/types.d.ts +17 -1
- package/dist/services/service-manager/windows.d.ts +7 -2
- package/dist/services/service-manager/windows.js +28 -11
- package/dist/services/service-notice.d.ts +7 -0
- package/dist/services/service-notice.js +19 -0
- package/dist/services/session-registry.d.ts +13 -0
- package/dist/services/session-registry.js +13 -0
- package/dist/services/session-roots.d.ts +67 -0
- package/dist/services/session-roots.js +126 -0
- package/dist/services/statusline.d.ts +21 -0
- package/dist/services/statusline.js +97 -1
- package/dist/services/supervisor-service-cleanup.js +2 -1
- package/dist/services/tool-registry.js +108 -20
- package/dist/services/tool-scope.d.ts +34 -1
- package/dist/services/tool-scope.js +27 -2
- package/dist/services/vcs/azure-devops.js +10 -0
- package/dist/services/vcs/bitbucket.d.ts +22 -1
- package/dist/services/vcs/bitbucket.js +163 -17
- package/dist/services/vcs/types.d.ts +25 -2
- package/dist/services/watch/project-resolver.js +2 -1
- package/dist/skills/pm/cost.md +5 -1
- package/dist/skills/pm/index.md +9 -9
- package/dist/skills/pm/sprint.md +2 -1
- package/dist/tools/check-status.d.ts +51 -0
- package/dist/tools/check-status.js +124 -12
- package/dist/tools/code-intelligence-freshness.js +1 -1
- package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
- package/dist/tools/code-intelligence-gitnexus.js +166 -9
- package/dist/tools/code-intelligence-readiness.d.ts +58 -1
- package/dist/tools/code-intelligence-readiness.js +93 -8
- package/dist/tools/code-intelligence-reindex.d.ts +25 -1
- package/dist/tools/code-intelligence-reindex.js +76 -4
- package/dist/tools/code-intelligence.d.ts +1 -1
- package/dist/tools/code-intelligence.js +1 -1
- package/dist/tools/execute-command.js +14 -8
- package/dist/tools/execute-prompt.js +6 -2
- package/dist/tools/fleet-snapshot.d.ts +21 -0
- package/dist/tools/fleet-snapshot.js +78 -0
- package/dist/tools/kb-bible-commit.d.ts +25 -11
- package/dist/tools/kb-bible-commit.js +142 -33
- package/dist/tools/kb-capture.d.ts +2 -2
- package/dist/tools/kb-context.js +47 -27
- package/dist/tools/kb-demote.d.ts +27 -0
- package/dist/tools/kb-demote.js +37 -0
- package/dist/tools/kb-export.d.ts +35 -3
- package/dist/tools/kb-export.js +56 -13
- package/dist/tools/kb-feedback.d.ts +2 -0
- package/dist/tools/kb-feedback.js +17 -7
- package/dist/tools/kb-harvest.js +28 -9
- package/dist/tools/kb-import.d.ts +18 -2
- package/dist/tools/kb-import.js +24 -9
- package/dist/tools/kb-invalidate.d.ts +11 -3
- package/dist/tools/kb-invalidate.js +80 -7
- package/dist/tools/kb-list.js +38 -10
- package/dist/tools/kb-promote.js +6 -4
- package/dist/tools/kb-query.d.ts +3 -0
- package/dist/tools/kb-query.js +181 -37
- package/dist/tools/kb-session-prime.d.ts +4 -4
- package/dist/tools/kb-session-prime.js +89 -9
- package/dist/tools/kb-setup.d.ts +20 -0
- package/dist/tools/kb-setup.js +149 -11
- package/dist/tools/list-members.js +1 -1
- package/dist/tools/member-detail.js +7 -3
- package/dist/tools/provision-vcs-auth.d.ts +28 -3
- package/dist/tools/provision-vcs-auth.js +53 -7
- package/dist/tools/receive-files.js +7 -4
- package/dist/tools/send-files.js +5 -4
- package/dist/tools/send-message.d.ts +3 -0
- package/dist/tools/send-message.js +15 -2
- package/dist/tools/stop-prompt.js +3 -1
- package/dist/tools/vcs-credential-exec.d.ts +45 -3
- package/dist/tools/vcs-credential-exec.js +90 -11
- package/dist/utils/process-utils.js +5 -1
- package/dist/utils/redact-known-secrets.d.ts +17 -0
- package/dist/utils/redact-known-secrets.js +70 -0
- package/dist/utils/skill-matrix.js +1 -1
- package/dist/utils/vcs-provider-detect.js +2 -2
- package/dist/workflows/auto-sprint.js +245 -9
- package/package.json +10 -7
- package/packages/apra-fleet-client/package.json +1 -1
- package/packages/apra-fleet-client/src/client/api.mjs +172 -19
- package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
- package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
- package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
- package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
- package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
- package/packages/apra-fleet-se/bin/cli.mjs +104 -31
- package/packages/apra-fleet-se/bin/serve.mjs +46 -8
- package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
- package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
- package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
- package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
- package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
- package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
- package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
- package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
- package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
- package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
- package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
- package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
- package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
- package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
- package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
- package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
- package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
- package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
- package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
- package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
- package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
- package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
- package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
- package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
- package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
- package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
- package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
- package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
- package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
- package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
- package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
- package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
- package/packages/apra-fleet-workflow/package.json +2 -1
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
- package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
- package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
- package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
- package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
- package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
- package/skills/fleet/auth-bitbucket.md +47 -20
- package/skills/fleet/onboarding.md +1 -1
- package/skills/fleet/skill-matrix.md +3 -3
- package/version.json +1 -1
package/README.md
CHANGED
|
@@ -18,6 +18,7 @@ workforce -- on any machine, anywhere, using every LLM provider at once.
|
|
|
18
18
|
[](https://github.com/Apra-Labs/apra-fleet/releases)
|
|
19
19
|
[](https://modelcontextprotocol.io)
|
|
20
20
|
[](https://deepwiki.com/Apra-Labs/apra-fleet)
|
|
21
|
+
[](https://www.skillsdirectory.com/skills/apra-labs-apra-fleet)
|
|
21
22
|
|
|
22
23
|
[Quick Start](#quick-start-5-minutes) - [Live Demo](#watch-a-fleet-work) - [How It Works](#how-it-works) - [fleet-sprint Getting Started Guide](docs/fleet-sprint-getting-started.md) - [Website](https://apra-labs.github.io/apra-fleet)
|
|
23
24
|
|
|
@@ -84,6 +85,11 @@ It is not a toy. It builds apra-fleet itself:
|
|
|
84
85
|
- Every sprint's raw child stdout/stderr is captured to a per-sprint log
|
|
85
86
|
and linked from the dashboard, so a run's output is traceable even if it
|
|
86
87
|
crashes before reporting anything back
|
|
88
|
+
- Asks a human when it must: a doer or reviewer that needs an operator
|
|
89
|
+
decision files a decision bead, the run pauses (not stalls), you are
|
|
90
|
+
notified once by message and email, and your answer on the dashboard or
|
|
91
|
+
via `bd human respond` resumes it
|
|
92
|
+
([details](docs/fleet-sprint-set-aside.md))
|
|
87
93
|
|
|
88
94
|
A fleet that has run in production:
|
|
89
95
|
|
|
@@ -119,6 +125,16 @@ The standalone installer instead registers and starts a user-level service
|
|
|
119
125
|
|
|
120
126
|
The default install includes fleet-se (fleet-sprint, supervisor, bd), which requires a system Node.js 22.16+ and npm on PATH; the installer fails up front if they are missing. Use `apra-fleet install --workflows none` to install the core only.
|
|
121
127
|
|
|
128
|
+
For Claude Code, `install` also adds the **fleet-status mod** -- a Claude Code
|
|
129
|
+
plugin that shows every member's state in the status line and opens a
|
|
130
|
+
`/fleet-status` pane where you can also remove a member and list, add,
|
|
131
|
+
replace or delete secrets (a secret's value is typed in another terminal or
|
|
132
|
+
the server's one-time form, never in Claude Code). It is installed through the `claude` CLI from a local
|
|
133
|
+
marketplace in `~/.apra-fleet/claude-plugins/` and replaces the old statusLine
|
|
134
|
+
script. If the `claude` CLI is missing or too old to install plugins, install
|
|
135
|
+
says why and keeps the statusLine script instead. A statusLine of your own is
|
|
136
|
+
never overwritten. See [docs/install.md](docs/install.md#the-fleet-status-mod-claude-code).
|
|
137
|
+
|
|
122
138
|
**2. Connect your agent.** Load the fleet server in Claude Code with
|
|
123
139
|
`/mcp` (or restart your provider CLI). Your agent now has a fleet. To check
|
|
124
140
|
from a shell, `claude mcp list` should show a line like
|
|
@@ -217,11 +233,14 @@ MCP tools that ship with the KB:
|
|
|
217
233
|
| `kb_context` | Batch file freshness check (single git call for N files) |
|
|
218
234
|
| `kb_invalidate` | Mark files stale immediately (also called by the git hook), or discard own entries by `ids` |
|
|
219
235
|
| `kb_promote` | Advance confidence: UNVERIFIED -> INFERRED -> CONFIRMED (FULL session, or the sprint's kb_maintainer member session only) |
|
|
236
|
+
| `kb_demote` | Withdraw trust: lower a CONFIRMED entry back to INFERRED (the one reversible rung; never a ladder in its own direction) |
|
|
220
237
|
| `kb_harvest` | Extract learnings from a session transcript (auto-fires after execute_prompt) |
|
|
221
238
|
| `kb_export` | Additively merge live CONFIRMED entries whose cited files still match their recorded hashes into `.fleet/kb-canonical.json` -- the git-shareable team bible (FULL session only) |
|
|
222
|
-
| `kb_bible_commit` | Merge confirmed entry ids into the bible (format v3, per-entry file hashes), remove superseded or invalidated entries, and commit locally with base-branch provenance (used by the sprint kb_maintainer) |
|
|
239
|
+
| `kb_bible_commit` | Merge confirmed entry ids into the bible (format v3, per-entry file hashes), remove superseded or invalidated entries, and commit locally with base-branch provenance (used by the sprint kb_maintainer); on an http KB project it is a no-op that returns `bible_skipped: true` |
|
|
223
240
|
| `kb_setup` | Install git hook, write provider config, store remote token encrypted (FULL session only) |
|
|
224
241
|
|
|
242
|
+
`kb_query` accepts `own_scope: true` so a MEMBER session can read its own CONFIRMED rows from the per-repo database instead of the bible view. The fleet-sprint reviewer uses this to offer demotion candidates; the loop is on by default and `--kb-demotion-loop off` disables it. See [docs/kb-member-view-and-maintainer.md](docs/kb-member-view-and-maintainer.md).
|
|
243
|
+
|
|
225
244
|
`code_*` tools resolve the calling session's own folder, refuse with typed
|
|
226
245
|
`E-CODE-INDEX-NOT-READY` / `E-CODE-INTEL-DISABLED` errors when the index is not
|
|
227
246
|
usable, and report `indexedCommit` on every result; `code_reindex` and
|
|
@@ -240,13 +259,34 @@ no separate "server mode" build. A config with no remote, or any config the
|
|
|
240
259
|
reader cannot parse, always falls back to the local SQLite provider -- see
|
|
241
260
|
[Client-side provider selection](docs/knowledge-layer-design.md#client-side-provider-selection)
|
|
242
261
|
for the exact selection rule and its fallback-construction invariant.
|
|
262
|
+
`--token {{secret.NAME}}` stores a reference to a refreshable fleet secret instead of a token, so an
|
|
263
|
+
expiring server token can be rotated with `apra-fleet secret --set NAME --persist -y` and no restart (see
|
|
264
|
+
[Named credentials](docs/knowledge-layer.md#named-credentials-and-refreshers)).
|
|
265
|
+
`--request_timeout_ms <ms>` (1000-120000, default 5000) sets the socket idle
|
|
266
|
+
timeout for each request to the remote KB server. It is not a per-request
|
|
267
|
+
deadline: a call can wait up to about twice the value when it first reads
|
|
268
|
+
the server capabilities. See
|
|
269
|
+
[docs/knowledge-layer.md](docs/knowledge-layer.md).
|
|
243
270
|
|
|
244
271
|
**The provider config is install-wide, not per repo.** There is one
|
|
245
272
|
`knowledge/config.json` per fleet install, so pointing it at a remote KB
|
|
246
273
|
points EVERY repo that install serves -- every member, every project -- at
|
|
247
274
|
that server. `kb_setup` only places the git post-commit hook (in the calling
|
|
248
|
-
session's own repo
|
|
249
|
-
|
|
275
|
+
session's own repo, including linked worktrees and custom `core.hooksPath`);
|
|
276
|
+
it does not scope the config. On a shared fleet server, treat
|
|
277
|
+
`kb_setup --remote` as a change for all of its users.
|
|
278
|
+
|
|
279
|
+
**KB tool profiles.** `apra-fleet kb profile developer` (or `kb_setup` with
|
|
280
|
+
`tool_profile`) trims the `kb_*` tools an interactive (non-member) session
|
|
281
|
+
lists to `kb_session_prime`, `kb_query`, `kb_context`, `kb_capture` and
|
|
282
|
+
`kb_feedback`; `custom <a,b>` lists exactly the named `kb_*` tools and `full`
|
|
283
|
+
(the default) lists them all. The profile is install-wide, applies to FULL
|
|
284
|
+
sessions only (member sessions and sprint roles are unaffected), and takes
|
|
285
|
+
effect when a session reconnects. It is a usability control, not a security
|
|
286
|
+
boundary. `developer` hides `kb_setup` and the tools the PM skills `kb-review`,
|
|
287
|
+
`kb-reconcile` and `knowledge-agent` need, so get back with
|
|
288
|
+
`apra-fleet kb profile full` (and reconnect) before running those. See
|
|
289
|
+
[KB tool profiles](docs/knowledge-layer.md#5-kb-tool-profiles-which-kb_-tools-interactive-sessions-see).
|
|
250
290
|
|
|
251
291
|
Every KB tool call is scoped to the calling session's own repo -- a fleet
|
|
252
292
|
server handling many members across many repos never lets one repo's
|
|
@@ -400,7 +440,7 @@ your config however you prefer (JSON file, hardcoded, etc.):
|
|
|
400
440
|
import { parseToolJson } from '@apralabs/apra-fleet-client';
|
|
401
441
|
import { connectFleet } from '@apralabs/apra-fleet-client/server-resolution';
|
|
402
442
|
|
|
403
|
-
const { fleetApi } = await connectFleet({ env: process.env });
|
|
443
|
+
const { fleetApi, transport } = await connectFleet({ env: process.env });
|
|
404
444
|
|
|
405
445
|
// fleetApi wrappers return the raw MCP tool result ({ content: [...] });
|
|
406
446
|
// parseToolJson extracts the JSON payload.
|
|
@@ -415,6 +455,9 @@ const result = parseToolJson(await fleetApi.sendEmail({
|
|
|
415
455
|
body: 'All tasks completed.'
|
|
416
456
|
}));
|
|
417
457
|
console.log(`Sent: ${result.messageId}`);
|
|
458
|
+
|
|
459
|
+
// Release the server session when done (stop() alone leaves it open).
|
|
460
|
+
await transport.close();
|
|
418
461
|
```
|
|
419
462
|
|
|
420
463
|
The SMTP password resolves from the credential store automatically. It never
|
|
@@ -469,6 +512,7 @@ third-party verticals.
|
|
|
469
512
|
| Topic | Link |
|
|
470
513
|
|-------|------|
|
|
471
514
|
| **fleet-sprint Getting Started Guide (start here, plain English)** | [Website](https://apra-labs.github.io/apra-fleet/fleet-sprint-getting-started.html) - [Markdown](docs/fleet-sprint-getting-started.md) |
|
|
515
|
+
| fleet-sprint set-aside rules (BLOCKED beads, deploy Permissions failure, immediate stall) | [docs/fleet-sprint-set-aside.md](docs/fleet-sprint-set-aside.md) |
|
|
472
516
|
| Codebase wiki (architecture, internals, AI Q&A) | [DeepWiki](https://deepwiki.com/Apra-Labs/apra-fleet) |
|
|
473
517
|
| Install, uninstall, the `--llm` flag | [docs/install.md](docs/install.md) |
|
|
474
518
|
| Choosing a provider (roles, gotchas, mixing providers, OpenCode/local models) | [docs/provider-guide.md](docs/provider-guide.md) |
|
|
@@ -478,6 +522,7 @@ third-party verticals.
|
|
|
478
522
|
| The PM skill (doer-reviewer sprints, `/pm` commands) | [docs/pm-skill-overview.md](docs/pm-skill-overview.md) |
|
|
479
523
|
| FAQ | [docs/FAQ.md](docs/FAQ.md) |
|
|
480
524
|
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
|
525
|
+
| Supervisor/viewer request guard | [docs/supervisor-request-guard.md](docs/supervisor-request-guard.md) |
|
|
481
526
|
| Keeping Fleet updated (`apra-fleet update`) | [docs/features/update.md](docs/features/update.md) |
|
|
482
527
|
| Live member activity (`apra-fleet watch`, `logging.previewChars`) | [docs/features/watch.md](docs/features/watch.md) |
|
|
483
528
|
| Secret variables and passwords | [docs/secret-variables.md](docs/secret-variables.md) - [docs/features/oob-auth.md](docs/features/oob-auth.md) |
|
|
@@ -25,6 +25,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
25
25
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
26
26
|
your tool-loading tool first, before concluding they are unavailable.
|
|
27
27
|
|
|
28
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
29
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
30
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
31
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
32
|
+
|
|
28
33
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
29
34
|
subsystems the assigned beads touch. KB knowledge matters most for duplicate
|
|
30
35
|
detection and sprint-set grouping.
|
|
@@ -37,6 +37,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
37
37
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
38
38
|
your tool-loading tool first, before concluding they are unavailable.
|
|
39
39
|
|
|
40
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
41
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
42
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
43
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
44
|
+
|
|
40
45
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
41
46
|
repo's CI workflow files. Known-flaky tests and known CI failure modes are the point
|
|
42
47
|
here -- they change how you read a red run.
|
package/dist/agents/deployer.md
CHANGED
|
@@ -80,8 +80,11 @@ console.log(JSON.stringify([...allow], null, 2));
|
|
|
80
80
|
|
|
81
81
|
Check every required prefix against this one merged list. If any prefix has
|
|
82
82
|
no covering entry, STOP immediately and return `deployed: false`, listing
|
|
83
|
-
every missing entry in `notes
|
|
84
|
-
`compose_permissions` with the missing grant(s), then
|
|
83
|
+
every missing entry in `notes`, and set `failedStep: "permissions"`, asking the
|
|
84
|
+
orchestrator/operator to run `compose_permissions` with the missing grant(s), then
|
|
85
|
+
re-trigger the sprint. `failedStep` is how the orchestrator knows no deploy command
|
|
86
|
+
ran -- set it only for this Step 0a stop, never for a failure after a deploy command
|
|
87
|
+
ran.
|
|
85
88
|
NEVER add permissions yourself: `.claude/settings.json` changes require a
|
|
86
89
|
team PR, and `.claude/settings.local.json` must be provisioned via the
|
|
87
90
|
`compose_permissions` MCP tool (the provider-agnostic delivery mechanism
|
|
@@ -103,6 +106,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
103
106
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
104
107
|
your tool-loading tool first, before concluding they are unavailable.
|
|
105
108
|
|
|
109
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
110
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
111
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
112
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
113
|
+
|
|
106
114
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
107
115
|
deploy targets in `deploy.md`.
|
|
108
116
|
2. Any judgment that depends on what the KB does or does not record is made from the
|
|
@@ -161,6 +169,16 @@ placeholder):
|
|
|
161
169
|
}
|
|
162
170
|
```
|
|
163
171
|
|
|
172
|
+
A Step 0a stop (missing permissions, no deploy command ran):
|
|
173
|
+
|
|
174
|
+
```json
|
|
175
|
+
{
|
|
176
|
+
"deployed": false,
|
|
177
|
+
"failedStep": "permissions",
|
|
178
|
+
"notes": "Missing permission grant(s): <entries>. Run compose_permissions with them, then re-trigger the sprint."
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
164
182
|
**Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
|
|
165
183
|
authoritative -- respond with exactly that JSON and nothing else. It is expected to match
|
|
166
184
|
this contract; if it differs, follow the dispatch prompt.
|
package/dist/agents/doer.md
CHANGED
|
@@ -51,6 +51,23 @@ your final `notes`, naming the bead id and the defect. This is a legitimate skip
|
|
|
51
51
|
exception (see Step 3 and Rules); it lets the reviewer route the bead to re-planning in
|
|
52
52
|
the same round.
|
|
53
53
|
|
|
54
|
+
**Needs an operator decision**: when a bead cannot go on until a human chooses between
|
|
55
|
+
real alternatives -- for example the criteria can only be met by upgrading a dependency,
|
|
56
|
+
patching it, or accepting a weaker check, and nothing in the bead, its parent or the code
|
|
57
|
+
says which -- do not guess and do not keep retrying. Leave the bead open and return
|
|
58
|
+
`status: "NEEDS-DECISION"` with a `decision` object: `beadId` (that one open bead),
|
|
59
|
+
`question` (self-contained: what you found, why it blocks the bead, what must be
|
|
60
|
+
decided), `options` (at least two, each `{ "id": "a", "text": "..." }` with what it
|
|
61
|
+
means and costs) and `recommendation` (the option id you recommend, and why). The
|
|
62
|
+
orchestrator files the question for an operator verbatim, sets the bead aside for the
|
|
63
|
+
rest of the run without re-dispatching it, and keeps working other beads; the answer
|
|
64
|
+
reaches a later dispatch through the bead's notes. Use it instead of the
|
|
65
|
+
criteria-defect escape hatch only when the fix is a choice an operator must make, not a
|
|
66
|
+
criteria rewrite a planner can make. Use BLOCKED, not NEEDS-DECISION, for a missing
|
|
67
|
+
secret, missing access, or an unmet prerequisite: those have one fix, not a choice. The
|
|
68
|
+
same-lane stop rule (Step 1) applies to a NEEDS-DECISION bead exactly as to any other
|
|
69
|
+
bead left open.
|
|
70
|
+
|
|
54
71
|
**CI is not yours**: never trigger, wait for or poll a CI run. A criterion that can only
|
|
55
72
|
be met by a CI run is a criteria defect: do the locally checkable work and report the CI
|
|
56
73
|
part under "criteria defects" (see above).
|
|
@@ -80,6 +97,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
80
97
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
81
98
|
your tool-loading tool first, before concluding they are unavailable.
|
|
82
99
|
|
|
100
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
101
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
102
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
103
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
104
|
+
|
|
83
105
|
The `kb_query` and `code_impact` calls below are EXPECTED, not optional, whenever the
|
|
84
106
|
tools are present. If a tool is genuinely not present (or the KB or code index is not set
|
|
85
107
|
up for this repo), record that in `toolUse` (Output schema) and continue -- never skip
|
|
@@ -105,7 +127,8 @@ silently.
|
|
|
105
127
|
fixture-only files are exempt. Prefer these over grep for symbol lookups, call-chain
|
|
106
128
|
tracing, and impact analysis. If they are absent, fail, or report the repo is not
|
|
107
129
|
indexed, fall back to grep and record it in `toolUse`; do not try to build an index
|
|
108
|
-
yourself.
|
|
130
|
+
yourself. On `E-CODE-INDEX-NOT-READY`, wait once for its `retry_after_ms`, retry
|
|
131
|
+
once, then fall back to grep -- never poll `code_status` in a loop.
|
|
109
132
|
5. Report in `toolUse`: `kb` and `code` are each `used`, `unavailable` or `not_needed`;
|
|
110
133
|
`note` says why for anything not `used`. `used` means the expected call was made
|
|
111
134
|
(`kb_query` for kb -- `kb_session_prime` alone is not `used`; `code_impact`/
|
|
@@ -262,6 +285,18 @@ stop and return:
|
|
|
262
285
|
orchestrator can verify your closes against beads instead of trusting the summary alone.
|
|
263
286
|
Do NOT continue past VERIFY.
|
|
264
287
|
|
|
288
|
+
Whenever you return `status: "BLOCKED"`, also return `blockedIds`: the assigned bead ids
|
|
289
|
+
you left open BECAUSE of the block. Leave out ids you merely did not reach (for example
|
|
290
|
+
lane-mates skipped under the same-lane stop rule) -- the orchestrator sets each
|
|
291
|
+
`blockedIds` bead and everything depending on it aside for the rest of the run, and
|
|
292
|
+
re-dispatches the unreached ones. Example:
|
|
293
|
+
`{ "status": "BLOCKED", "closedIds": ["<id-1>"], "blockedIds": ["<id-2>"], "notes": "..." }`.
|
|
294
|
+
|
|
295
|
+
When a bead needs an operator decision (see "Needs an operator decision" above), stop
|
|
296
|
+
there and return `status: "NEEDS-DECISION"` with its `decision` object, listing in
|
|
297
|
+
`closedIds` whatever you closed before it. Example:
|
|
298
|
+
`{ "status": "NEEDS-DECISION", "closedIds": ["<id-1>"], "notes": "...", "decision": { "beadId": "<id-2>", "question": "...", "options": [{ "id": "a", "text": "..." }, { "id": "b", "text": "..." }], "recommendation": "a, because ..." } }`.
|
|
299
|
+
|
|
265
300
|
|
|
266
301
|
## Branch and secrets rules
|
|
267
302
|
|
|
@@ -303,7 +338,8 @@ or as prose if you are answering a human directly.
|
|
|
303
338
|
- NEVER skip an assigned bead id for convenience -- work them in dependency order. The
|
|
304
339
|
only skip exceptions: has open children, the same-lane stop rule (Step 1) after an
|
|
305
340
|
earlier lane-mate was left open, an unresolved wrap-up ambiguity, missing acceptance
|
|
306
|
-
criteria/context,
|
|
341
|
+
criteria/context, a recorded criteria defect (escape hatch above), or a bead that needs
|
|
342
|
+
an operator decision (returned as NEEDS-DECISION). A missing secret
|
|
307
343
|
is NOT a skip -- close with a blocked reason per Branch and secrets rules.
|
|
308
344
|
- Tests for the changed area must pass before each commit (Step 2.5)
|
|
309
345
|
- No PLAN.md, no progress.json -- beads is the only work tracker
|
package/dist/agents/harvester.md
CHANGED
|
@@ -18,7 +18,7 @@ wired and queried; do not restate or improvise those rules here.
|
|
|
18
18
|
Your dispatch prompt must supply:
|
|
19
19
|
|
|
20
20
|
- `analysisArtifactFile` (required) -- relative path (under the repo) to write the sprint
|
|
21
|
-
analysis artifact to, e.g. `sprint-
|
|
21
|
+
analysis artifact to, e.g. `docs/sprint-analysis-<slug>.md`. Written, never committed.
|
|
22
22
|
- `analysisText` (required) -- the exact, pre-formatted analysis content to write verbatim.
|
|
23
23
|
- `base-branch` (required) -- for `git log`/`git diff` in Step 2.
|
|
24
24
|
- `branch` (required) -- the sprint branch being harvested.
|
|
@@ -44,6 +44,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
44
44
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
45
45
|
your tool-loading tool first, before concluding they are unavailable.
|
|
46
46
|
|
|
47
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
48
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
49
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
50
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
51
|
+
|
|
47
52
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
48
53
|
relevant to the modules touched during the sprint.
|
|
49
54
|
2. When you extract durable knowledge during harvest -- anything non-obvious that future
|
|
@@ -70,17 +75,15 @@ search also matches value text, so apply only entries whose KEY contains `+all+`
|
|
|
70
75
|
|
|
71
76
|
Your task context includes an `analysisArtifactFile` path and an `analysisText` block.
|
|
72
77
|
|
|
73
|
-
Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
mkdir -p "<repo>/sprint-logs"
|
|
77
|
-
# Write analysisText content to <repo>/<analysisArtifactFile>
|
|
78
|
-
git -C "<repo>" add "<repo>/<analysisArtifactFile>"
|
|
79
|
-
git -C "<repo>" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: sprint-analysis <branch> <startedAt>"
|
|
80
|
-
```
|
|
78
|
+
Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite
|
|
79
|
+
if it exists; create its parent directory if missing).
|
|
81
80
|
|
|
82
81
|
Do NOT reformat or modify the analysisText -- write it exactly as provided.
|
|
83
82
|
|
|
83
|
+
**Do NOT `git add` or commit this file.** It is a local record that stays untracked in the
|
|
84
|
+
working tree; the orchestrator keeps it out of `git status` and out of every commit. Never
|
|
85
|
+
force-add it (`git add -f`), and do not stage it in any later step.
|
|
86
|
+
|
|
84
87
|
## Step 2 -- Read sprint context
|
|
85
88
|
|
|
86
89
|
Read the following to understand what was built:
|
|
@@ -76,6 +76,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
76
76
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
77
77
|
your tool-loading tool first, before concluding they are unavailable.
|
|
78
78
|
|
|
79
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
80
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
81
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
82
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
83
|
+
|
|
79
84
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
80
85
|
relevant to the features you were handed.
|
|
81
86
|
2. Any judgment that depends on what the KB does or does not record (e.g. whether a test
|
|
@@ -105,6 +105,12 @@ code_impact({ target: "<symbol>", direction: "upstream" | "downstream" })
|
|
|
105
105
|
code_query({ query: "<concept or pattern>" })
|
|
106
106
|
```
|
|
107
107
|
|
|
108
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
109
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
110
|
+
not help), retry that call ONCE, and if it still fails fall back to reading the cited
|
|
111
|
+
files directly and say so in the evidence note. Never poll `code_status` in a loop
|
|
112
|
+
waiting for the index.
|
|
113
|
+
|
|
108
114
|
Decide which entry's claim the CURRENT merged code actually supports. Note the exact
|
|
109
115
|
file + symbol you read that settled it.
|
|
110
116
|
|
|
@@ -63,6 +63,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
63
63
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
64
64
|
your tool-loading tool first, before concluding they are unavailable.
|
|
65
65
|
|
|
66
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
67
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
68
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
69
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
70
|
+
|
|
66
71
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
67
72
|
relevant to the features in the DAG under review.
|
|
68
73
|
2. Any judgment that depends on KB coverage (e.g. whether a task touches unexplored code
|
package/dist/agents/planner.md
CHANGED
|
@@ -43,6 +43,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
43
43
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
44
44
|
your tool-loading tool first, before concluding they are unavailable.
|
|
45
45
|
|
|
46
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
47
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
48
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
49
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
50
|
+
|
|
46
51
|
1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
|
|
47
52
|
derived from the sprint goals / requirements you are about to decompose.
|
|
48
53
|
2. From whichever source you have (a live `kb_session_prime` result, the injected
|
|
@@ -21,6 +21,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
|
|
|
21
21
|
If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
|
|
22
22
|
your tool-loading tool first, before concluding they are unavailable.
|
|
23
23
|
|
|
24
|
+
If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
|
|
25
|
+
`retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
|
|
26
|
+
not help), retry that call ONCE, and if it still fails fall back to text search and
|
|
27
|
+
record the fallback. Never poll `code_status` in a loop waiting for the index.
|
|
28
|
+
|
|
24
29
|
1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
|
|
25
30
|
subsystems `regression-test-playbook.md` exercises.
|
|
26
31
|
2. Known-flaky tests and known environment setup/teardown gotchas are the point here -- they
|
package/dist/agents/reviewer.md
CHANGED
|
@@ -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
|
|
184
|
+
## Step 5 -- Promote, discard, or demote knowledge you verified
|
|
174
185
|
|
|
175
|
-
This step covers judgements on existing
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
|
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
|
|
218
|
-
the "never mutate beads" rule below. Report what you promoted
|
|
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 "
|
|
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 --
|
|
298
|
-
`[]`, when you have nothing to promote, discard or capture
|
|
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
|
}
|