@apralabs/apra-fleet 0.4.2 → 0.4.3
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 +38 -5
- package/dist/agents/backlog-groomer.md +25 -0
- package/dist/agents/ci-watcher.md +11 -0
- package/dist/agents/deployer.md +37 -2
- package/dist/agents/doer.md +36 -12
- package/dist/agents/harvester.md +11 -0
- package/dist/agents/integ-test-runner.md +11 -0
- package/dist/agents/kb-reconciler.md +9 -0
- package/dist/agents/plan-reviewer.md +110 -22
- package/dist/agents/planner.md +125 -37
- package/dist/agents/regression-test-runner.md +11 -0
- package/dist/agents/reviewer.md +13 -2
- package/dist/agents/schemas/plan-reviewer-output.json +37 -0
- package/dist/cli/agent-transform.d.ts +83 -2
- package/dist/cli/agent-transform.d.ts.map +1 -1
- package/dist/cli/agent-transform.js +266 -21
- package/dist/cli/agent-transform.js.map +1 -1
- package/dist/cli/auth.d.ts.map +1 -1
- package/dist/cli/auth.js +28 -9
- package/dist/cli/auth.js.map +1 -1
- package/dist/cli/config.d.ts +7 -5
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +44 -34
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/install.d.ts +33 -0
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +290 -23
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/kb-directives.d.ts.map +1 -1
- package/dist/cli/kb-directives.js +2 -1
- package/dist/cli/kb-directives.js.map +1 -1
- package/dist/cli/register-member.d.ts.map +1 -1
- package/dist/cli/register-member.js +6 -2
- package/dist/cli/register-member.js.map +1 -1
- package/dist/commands/kb-server.d.ts +3 -0
- package/dist/commands/kb-server.d.ts.map +1 -1
- package/dist/commands/kb-server.js +43 -3
- package/dist/commands/kb-server.js.map +1 -1
- package/dist/index.js +3 -3
- package/dist/os/linux.d.ts +6 -0
- package/dist/os/linux.d.ts.map +1 -1
- package/dist/os/linux.js +35 -2
- package/dist/os/linux.js.map +1 -1
- package/dist/os/os-commands.d.ts +61 -2
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/windows-gitbash.d.ts +5 -0
- package/dist/os/windows-gitbash.d.ts.map +1 -1
- package/dist/os/windows-gitbash.js +15 -0
- package/dist/os/windows-gitbash.js.map +1 -1
- package/dist/os/windows.d.ts +6 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +46 -3
- package/dist/os/windows.js.map +1 -1
- package/dist/providers/agy.d.ts +115 -6
- package/dist/providers/agy.d.ts.map +1 -1
- package/dist/providers/agy.js +569 -53
- package/dist/providers/agy.js.map +1 -1
- package/dist/providers/claude.d.ts +81 -3
- package/dist/providers/claude.d.ts.map +1 -1
- package/dist/providers/claude.js +344 -10
- package/dist/providers/claude.js.map +1 -1
- package/dist/providers/codex.d.ts +4 -2
- package/dist/providers/codex.d.ts.map +1 -1
- package/dist/providers/codex.js +19 -2
- package/dist/providers/codex.js.map +1 -1
- package/dist/providers/copilot.d.ts +4 -2
- package/dist/providers/copilot.d.ts.map +1 -1
- package/dist/providers/copilot.js +20 -2
- package/dist/providers/copilot.js.map +1 -1
- package/dist/providers/none.d.ts +4 -2
- package/dist/providers/none.d.ts.map +1 -1
- package/dist/providers/none.js +17 -2
- package/dist/providers/none.js.map +1 -1
- package/dist/providers/opencode.d.ts +3 -1
- package/dist/providers/opencode.d.ts.map +1 -1
- package/dist/providers/opencode.js +22 -2
- package/dist/providers/opencode.js.map +1 -1
- package/dist/providers/provider.d.ts +201 -6
- package/dist/providers/provider.d.ts.map +1 -1
- package/dist/providers/provider.js +56 -0
- package/dist/providers/provider.js.map +1 -1
- package/dist/services/agy-project.d.ts +102 -0
- package/dist/services/agy-project.d.ts.map +1 -0
- package/dist/services/agy-project.js +356 -0
- package/dist/services/agy-project.js.map +1 -0
- package/dist/services/auth-socket.js +4 -4
- package/dist/services/auth-web.js +1 -1
- package/dist/services/cloud/lifecycle.d.ts.map +1 -1
- package/dist/services/cloud/lifecycle.js +33 -4
- package/dist/services/cloud/lifecycle.js.map +1 -1
- package/dist/services/credential-cleanup.d.ts.map +1 -1
- package/dist/services/credential-cleanup.js +35 -17
- package/dist/services/credential-cleanup.js.map +1 -1
- package/dist/services/exit-drain.d.ts +44 -0
- package/dist/services/exit-drain.d.ts.map +1 -0
- package/dist/services/exit-drain.js +52 -0
- package/dist/services/exit-drain.js.map +1 -0
- package/dist/services/github-app.d.ts.map +1 -1
- package/dist/services/github-app.js +32 -4
- package/dist/services/github-app.js.map +1 -1
- package/dist/services/http-transport.d.ts +1 -0
- package/dist/services/http-transport.d.ts.map +1 -1
- package/dist/services/http-transport.js +48 -1
- package/dist/services/http-transport.js.map +1 -1
- package/dist/services/knowledge/kb-config.d.ts +42 -0
- package/dist/services/knowledge/kb-config.d.ts.map +1 -0
- package/dist/services/knowledge/kb-config.js +54 -0
- package/dist/services/knowledge/kb-config.js.map +1 -0
- package/dist/services/knowledge/kb-providers.d.ts +7 -1
- package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
- package/dist/services/knowledge/kb-providers.js +191 -17
- package/dist/services/knowledge/kb-providers.js.map +1 -1
- package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
- package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
- package/dist/services/knowledge/require-sqlite-project.js +38 -0
- package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
- package/dist/services/model-pricing.d.ts.map +1 -1
- package/dist/services/model-pricing.js +7 -3
- package/dist/services/model-pricing.js.map +1 -1
- package/dist/services/secret-token.d.ts +38 -0
- package/dist/services/secret-token.d.ts.map +1 -0
- package/dist/services/secret-token.js +51 -0
- package/dist/services/secret-token.js.map +1 -0
- package/dist/services/service-manager/types.d.ts +3 -1
- package/dist/services/service-manager/types.d.ts.map +1 -1
- package/dist/services/service-manager/windows.d.ts +14 -2
- package/dist/services/service-manager/windows.d.ts.map +1 -1
- package/dist/services/service-manager/windows.js +65 -7
- package/dist/services/service-manager/windows.js.map +1 -1
- package/dist/services/ssh.d.ts.map +1 -1
- package/dist/services/ssh.js +58 -2
- package/dist/services/ssh.js.map +1 -1
- package/dist/services/stall/read-log-tail.d.ts.map +1 -1
- package/dist/services/stall/read-log-tail.js +20 -10
- package/dist/services/stall/read-log-tail.js.map +1 -1
- package/dist/services/stall/stall-detector.d.ts +53 -4
- package/dist/services/stall/stall-detector.d.ts.map +1 -1
- package/dist/services/stall/stall-detector.js +212 -34
- package/dist/services/stall/stall-detector.js.map +1 -1
- package/dist/services/strategy.d.ts.map +1 -1
- package/dist/services/strategy.js +79 -2
- package/dist/services/strategy.js.map +1 -1
- package/dist/services/substitution-engine.js +2 -2
- package/dist/services/substitution-engine.js.map +1 -1
- package/dist/services/tool-registry.d.ts.map +1 -1
- package/dist/services/tool-registry.js +5 -3
- package/dist/services/tool-registry.js.map +1 -1
- package/dist/services/vcs/azure-devops.d.ts +66 -1
- package/dist/services/vcs/azure-devops.d.ts.map +1 -1
- package/dist/services/vcs/azure-devops.js +192 -21
- package/dist/services/vcs/azure-devops.js.map +1 -1
- package/dist/services/vcs/types.d.ts +1 -1
- package/dist/skills/fleet-sprint-cli/SKILL.md +18 -0
- package/dist/skills/pm/SKILL.md +1 -1
- package/dist/skills/pm/cost.md +0 -3
- package/dist/skills/pm/fleet-addendum.md +2 -2
- package/dist/tools/check-status.d.ts +7 -4
- package/dist/tools/check-status.d.ts.map +1 -1
- package/dist/tools/check-status.js +2 -0
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/compose-permissions.d.ts +6 -0
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +182 -34
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/credential-store-set.js +1 -1
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +31 -20
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts +15 -2
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +1196 -892
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/kb-capture.d.ts +2 -2
- package/dist/tools/kb-capture.d.ts.map +1 -1
- package/dist/tools/kb-capture.js +29 -5
- package/dist/tools/kb-capture.js.map +1 -1
- package/dist/tools/kb-export.d.ts +2 -2
- package/dist/tools/kb-export.d.ts.map +1 -1
- package/dist/tools/kb-export.js +3 -28
- package/dist/tools/kb-export.js.map +1 -1
- package/dist/tools/kb-feedback.d.ts.map +1 -1
- package/dist/tools/kb-feedback.js +3 -1
- package/dist/tools/kb-feedback.js.map +1 -1
- package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
- package/dist/tools/kb-freshness-sweep.js +3 -1
- package/dist/tools/kb-freshness-sweep.js.map +1 -1
- package/dist/tools/kb-import.d.ts.map +1 -1
- package/dist/tools/kb-import.js +2 -1
- package/dist/tools/kb-import.js.map +1 -1
- package/dist/tools/kb-list.d.ts.map +1 -1
- package/dist/tools/kb-list.js +3 -1
- package/dist/tools/kb-list.js.map +1 -1
- package/dist/tools/kb-query.d.ts +2 -2
- package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
- package/dist/tools/kb-reconcile-prefilter.js +3 -1
- package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
- package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
- package/dist/tools/kb-resolve-contradiction.js +3 -1
- package/dist/tools/kb-resolve-contradiction.js.map +1 -1
- package/dist/tools/kb-setup.d.ts.map +1 -1
- package/dist/tools/kb-setup.js +125 -20
- package/dist/tools/kb-setup.js.map +1 -1
- package/dist/tools/kb-stats.d.ts.map +1 -1
- package/dist/tools/kb-stats.js +64 -43
- package/dist/tools/kb-stats.js.map +1 -1
- package/dist/tools/list-members.d.ts +2 -2
- package/dist/tools/list-members.d.ts.map +1 -1
- package/dist/tools/list-members.js +1 -0
- package/dist/tools/list-members.js.map +1 -1
- package/dist/tools/member-detail.d.ts +2 -2
- package/dist/tools/member-detail.d.ts.map +1 -1
- package/dist/tools/member-detail.js +17 -0
- package/dist/tools/member-detail.js.map +1 -1
- package/dist/tools/member-reservation.d.ts +58 -1
- package/dist/tools/member-reservation.d.ts.map +1 -1
- package/dist/tools/member-reservation.js +61 -20
- package/dist/tools/member-reservation.js.map +1 -1
- package/dist/tools/provision-auth.d.ts +80 -1
- package/dist/tools/provision-auth.d.ts.map +1 -1
- package/dist/tools/provision-auth.js +142 -54
- package/dist/tools/provision-auth.js.map +1 -1
- package/dist/tools/provision-vcs-auth.d.ts +91 -1
- package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
- package/dist/tools/provision-vcs-auth.js +209 -49
- package/dist/tools/provision-vcs-auth.js.map +1 -1
- package/dist/tools/register-member.d.ts +12 -9
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +99 -12
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/remove-member.d.ts.map +1 -1
- package/dist/tools/remove-member.js +27 -2
- package/dist/tools/remove-member.js.map +1 -1
- package/dist/tools/send-email.d.ts +2 -2
- package/dist/tools/setup-git-app.d.ts.map +1 -1
- package/dist/tools/setup-git-app.js +11 -7
- package/dist/tools/setup-git-app.js.map +1 -1
- package/dist/tools/shutdown-server.d.ts +2 -0
- package/dist/tools/shutdown-server.d.ts.map +1 -1
- package/dist/tools/shutdown-server.js +23 -1
- package/dist/tools/shutdown-server.js.map +1 -1
- package/dist/tools/update-member.d.ts +12 -9
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +43 -11
- package/dist/tools/update-member.js.map +1 -1
- package/dist/tools/vcs-credential-exec.d.ts +127 -0
- package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
- package/dist/tools/vcs-credential-exec.js +197 -0
- package/dist/tools/vcs-credential-exec.js.map +1 -0
- package/dist/types.d.ts +13 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/log-helpers.d.ts.map +1 -1
- package/dist/utils/log-helpers.js +2 -2
- package/dist/utils/log-helpers.js.map +1 -1
- package/dist/utils/prompt-errors.d.ts.map +1 -1
- package/dist/utils/prompt-errors.js +7 -1
- package/dist/utils/prompt-errors.js.map +1 -1
- package/dist/utils/shell-escape.d.ts +16 -0
- package/dist/utils/shell-escape.d.ts.map +1 -1
- package/dist/utils/shell-escape.js +22 -2
- package/dist/utils/shell-escape.js.map +1 -1
- package/dist/utils/vcs-provider-detect.d.ts +65 -0
- package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
- package/dist/utils/vcs-provider-detect.js +109 -0
- package/dist/utils/vcs-provider-detect.js.map +1 -0
- package/dist/utils/workspace-trust.d.ts +20 -17
- package/dist/utils/workspace-trust.d.ts.map +1 -1
- package/dist/utils/workspace-trust.js +87 -1
- package/dist/utils/workspace-trust.js.map +1 -1
- package/dist/workflows/auto-sprint.js +176 -15
- package/package.json +6 -4
- package/packages/apra-fleet-client/src/client/api.mjs +319 -17
- package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
- package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +25 -0
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +11 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -2
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +36 -12
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +11 -0
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +11 -0
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +9 -0
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +110 -22
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +125 -37
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +11 -0
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +13 -2
- package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
- package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
- package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
- package/packages/apra-fleet-se/bin/cli.mjs +149 -1
- package/packages/apra-fleet-se/bin/serve.mjs +78 -4
- package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
- package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
- package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
- package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +61 -14
- package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
- package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +276 -0
- package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
- package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +996 -32
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +267 -0
- package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
- package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
- package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
- package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
- package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
- package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
- package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
- package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
- package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
- package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
- package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
- package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
- package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
- package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
- package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
- package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
- package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
- package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
- package/packages/apra-fleet-se/fleet-sprint/runner.js +1467 -9798
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +17 -12
- package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +18 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
- package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
- package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
- package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
- package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +153 -19
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +71 -21
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +131 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +140 -16
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +1 -0
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +77 -2
- package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
- package/packages/apra-fleet-se/package.json +1 -1
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +17 -6
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +49 -7
- package/skills/fleet/SKILL.md +8 -8
- package/skills/fleet/auth-azdevops.md +14 -3
- package/skills/fleet/auth-bitbucket.md +2 -2
- package/skills/fleet/auth-github.md +5 -4
- package/skills/fleet/onboarding.md +3 -3
- package/skills/fleet/permissions.md +5 -1
- package/skills/fleet/profiles/node.json +1 -1
- package/skills/fleet/troubleshooting.md +3 -3
- package/version.json +1 -1
package/README.md
CHANGED
|
@@ -111,6 +111,8 @@ apra-fleet install --llm agy # or --llm opencode / codex / copilot
|
|
|
111
111
|
cd ~/.apra-fleet/bin && apra-fleet start # start the apra-fleet
|
|
112
112
|
```
|
|
113
113
|
|
|
114
|
+
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.
|
|
115
|
+
|
|
114
116
|
**2. Connect your agent.** Load the fleet server in Claude Code with
|
|
115
117
|
`/mcp` (or restart your provider CLI). Your agent now has a fleet.
|
|
116
118
|
|
|
@@ -176,7 +178,7 @@ flowchart LR
|
|
|
176
178
|
CP["Control Plane<br/>(Server, Engine, Supervisor)"] -->|Dispatch & Sync| M1["MacBook<br/>(Claude)"] & M2["Linux GPU<br/>(vLLM)"] & M3["Cloud VM<br/>(AGY)"] & M4["Windows<br/>(OpenCode)"]
|
|
177
179
|
```
|
|
178
180
|
|
|
179
|
-
- **Fleet server**: the control plane. Registers members, dispatches commands and prompts, moves files, brokers credentials. Speaks MCP, so any MCP-capable agent can drive a fleet.
|
|
181
|
+
- **Fleet server**: the control plane. Registers members, dispatches commands and prompts, moves files, brokers credentials. Speaks MCP, so any MCP-capable agent can drive a fleet. `execute_prompt` supports session forking (`fork`) on fork-capable providers -- branch a new, independent session from an existing one's context (e.g. a primed session reused across per-task dispatches) without continuing to write into the source session. See [docs/mcp-tools.md](docs/mcp-tools.md#execute_prompt) for the parameter contract.
|
|
180
182
|
- **Members**: real machines running provider CLIs. Composes provider-native permissions before every dispatch; unattended modes are scoped, never blanket.
|
|
181
183
|
- **Workflow engine**: runs workflow programs with phases, retries, turn budgets, resumable sessions, per-activity persistent state, and a cooperative pause/resume gate any workflow can hook into.
|
|
182
184
|
- **Supervisor**: always-on layer -- launch, pause/resume, & stop sprints over HTTP, member reservation ledger, crash watchdog (including a live "paused" state and base-branch-drift indicator), run history.
|
|
@@ -209,6 +211,21 @@ MCP tools that ship with the KB:
|
|
|
209
211
|
| `kb_export` | Write live CONFIRMED entries to `.fleet/kb-canonical.json` -- the git-shareable team bible |
|
|
210
212
|
| `kb_setup` | Install git hook, write provider config, store remote token encrypted |
|
|
211
213
|
|
|
214
|
+
`kb_setup --remote <url> --token <key>` takes effect immediately: the next
|
|
215
|
+
KB tool call resolves its project provider from this config, so a stock build
|
|
216
|
+
points at a remote KB server by configuration alone, with no code change and
|
|
217
|
+
no separate "server mode" build. A config with no remote, or any config the
|
|
218
|
+
reader cannot parse, always falls back to the local SQLite provider -- see
|
|
219
|
+
[Client-side provider selection](docs/knowledge-layer-design.md#client-side-provider-selection)
|
|
220
|
+
for the exact selection rule and its fallback-construction invariant.
|
|
221
|
+
|
|
222
|
+
**The provider config is install-wide, not per repo.** There is one
|
|
223
|
+
`knowledge/config.json` per fleet install, so pointing it at a remote KB
|
|
224
|
+
points EVERY repo that install serves -- every member, every project -- at
|
|
225
|
+
that server. `kb_setup`'s `repo_path` only chooses which repo gets the git
|
|
226
|
+
post-commit hook; it does not scope the config. On a shared fleet server,
|
|
227
|
+
treat `kb_setup --remote` as a change for all of its users.
|
|
228
|
+
|
|
212
229
|
Every KB tool call is scoped to the repo it is about -- a fleet server
|
|
213
230
|
handling many members across many repos never lets one repo's learnings land
|
|
214
231
|
in another repo's KB. Scope is normally derived from the caller's repo path;
|
|
@@ -293,8 +310,9 @@ When NOT to use it: a one-off single-file change needs no fleet.
|
|
|
293
310
|
## Security model, in one paragraph
|
|
294
311
|
|
|
295
312
|
Secrets are entered out-of-band into a credential store and referenced as
|
|
296
|
-
`{{
|
|
297
|
-
any LLM or log
|
|
313
|
+
`{{secret.NAME}}` -- resolved server-side at execution, never visible to
|
|
314
|
+
any LLM or log; see [docs/secret-variables.md](docs/secret-variables.md).
|
|
315
|
+
Credentials scope to members, expire on TTL, and can carry
|
|
298
316
|
a network egress policy (allow / deny / confirm). Every member runs with
|
|
299
317
|
composed, provider-native permission files -- allow-listed tools, not
|
|
300
318
|
god-mode. VCS access is provisioned and revocable per member, across GitHub,
|
|
@@ -302,7 +320,12 @@ Bitbucket, and Azure DevOps -- host differences (URL shape, PR REST dialect,
|
|
|
302
320
|
auth pattern, error vocabulary) are hidden behind a per-provider descriptor
|
|
303
321
|
rather than leaking into shared code; see
|
|
304
322
|
`docs/design-azure-devops-vcs-auth.md` for the Azure DevOps provider's
|
|
305
|
-
credential-assembly and PAT-lifetime details.
|
|
323
|
+
credential-assembly and PAT-lifetime details. A credential-requiring VCS
|
|
324
|
+
command can be handed to the server for execution (`vcs_credential_exec`)
|
|
325
|
+
rather than the orchestrator learning the plaintext token itself: the
|
|
326
|
+
server substitutes the credential into the command, runs it on the member,
|
|
327
|
+
and redacts the token from every field of the result -- the plaintext never
|
|
328
|
+
transits an orchestrator-readable output. Permission
|
|
306
329
|
composition verifies its own delivery: a grant is read back off the target
|
|
307
330
|
member and structurally compared against what was intended before it is
|
|
308
331
|
reported as applied, so a failed or partial write is surfaced as an
|
|
@@ -423,12 +446,14 @@ third-party verticals.
|
|
|
423
446
|
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
|
424
447
|
| Keeping Fleet updated (`apra-fleet update`) | [docs/features/update.md](docs/features/update.md) |
|
|
425
448
|
| Live member activity (`apra-fleet watch`, `logging.previewChars`) | [docs/features/watch.md](docs/features/watch.md) |
|
|
426
|
-
|
|
|
449
|
+
| Secret variables and passwords | [docs/secret-variables.md](docs/secret-variables.md) - [docs/features/oob-auth.md](docs/features/oob-auth.md) |
|
|
427
450
|
| Member category and tags | [docs/features/member-tags.md](docs/features/member-tags.md) |
|
|
428
451
|
| Enabling SSH on a remote machine (if it does not have it yet) | [docs/ssh-setup.md](docs/ssh-setup.md) |
|
|
429
452
|
| Git authentication | [docs/design-git-auth.md](docs/design-git-auth.md) |
|
|
453
|
+
| GitHub App setup (exact permissions per git_access level) | [docs/github-app-setup.md](docs/github-app-setup.md) |
|
|
430
454
|
| Cloud compute | [docs/cloud-compute.md](docs/cloud-compute.md) |
|
|
431
455
|
| Architecture | [docs/architecture.md](docs/architecture.md) |
|
|
456
|
+
| Dispatch and orchestration reliability design (Windows completion-on-exit, stall detector, test-runner wall-clock bound) | [docs/dispatch-reliability-hardening.md](docs/dispatch-reliability-hardening.md) - [docs/stall-detector-resilience.md](docs/stall-detector-resilience.md) |
|
|
432
457
|
| Windows shell selection (probe order, gitbash/pwsh7/powershell5, shell vs os) | [docs/windows-shell-selection.md](docs/windows-shell-selection.md) |
|
|
433
458
|
| Cross-shell command construction for member-bound commands | [docs/cross-shell-command-construction.md](docs/cross-shell-command-construction.md) |
|
|
434
459
|
| Knowledge Layer (setup, usage, provider swap) | [docs/knowledge-layer.md](docs/knowledge-layer.md) |
|
|
@@ -451,6 +476,9 @@ third-party verticals.
|
|
|
451
476
|
| MCP client SDK overview (transports, `ApraFleet` API) | [packages/apra-fleet-client/docs/overview.md](packages/apra-fleet-client/docs/overview.md) |
|
|
452
477
|
| MCP client SDK API reference | [packages/apra-fleet-client/docs/api-reference.md](packages/apra-fleet-client/docs/api-reference.md) |
|
|
453
478
|
| MCP client SDK getting started | [packages/apra-fleet-client/docs/getting-started.md](packages/apra-fleet-client/docs/getting-started.md) |
|
|
479
|
+
| Memory contract v1 inventory findings and invariants (`kb_*`/`code_*` tool surface) | [docs/memory-contract-v1-inventory-notes.md](docs/memory-contract-v1-inventory-notes.md) |
|
|
480
|
+
| Memory contract v1 schema generation design (zod -> JSON Schema 2020-12) | [docs/memory-contract-v1-generator-design.md](docs/memory-contract-v1-generator-design.md) |
|
|
481
|
+
| Memory contract v1 round-trip validation, drift guard, and T1/T2/T3/T7 handoff design | [docs/memory-contract-v1-roundtrip-and-handoff.md](docs/memory-contract-v1-roundtrip-and-handoff.md) |
|
|
454
482
|
|
|
455
483
|
## Community
|
|
456
484
|
|
|
@@ -472,6 +500,11 @@ git clone https://github.com/Apra-Labs/apra-fleet && cd apra-fleet
|
|
|
472
500
|
npm install && npm run build && npm test
|
|
473
501
|
```
|
|
474
502
|
|
|
503
|
+
`npm test` runs the full local suite: the root vitest suite, the
|
|
504
|
+
`apra-fleet-se` workspace suite, and the `apra-pm` suite (which is not an npm
|
|
505
|
+
workspace and is otherwise only reachable via an explicit `--prefix`
|
|
506
|
+
invocation) -- so a green local run and a green CI run see the same tests.
|
|
507
|
+
|
|
475
508
|
See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute.
|
|
476
509
|
|
|
477
510
|
## License
|
|
@@ -12,7 +12,13 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
|
|
|
12
12
|
|
|
13
13
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any grooming decision)
|
|
14
14
|
|
|
15
|
+
<!-- if-tool: ToolSearch -->
|
|
15
16
|
1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
|
|
17
|
+
<!-- else-tool: ToolSearch -->
|
|
18
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
19
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
20
|
+
them as written.
|
|
21
|
+
<!-- end-tool: ToolSearch -->
|
|
16
22
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose backlog
|
|
17
23
|
you are grooming, and `hint_modules` naming the subsystems the assigned beads touch.
|
|
18
24
|
Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. This matters
|
|
@@ -22,7 +28,12 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
|
|
|
22
28
|
items land unactionable -- call `mcp__apra-fleet__kb_capture` with type "knowledge".
|
|
23
29
|
Do not capture per-sprint churn; capture what stays true.
|
|
24
30
|
|
|
31
|
+
<!-- if-tool: ToolSearch -->
|
|
25
32
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
33
|
+
<!-- else-tool: ToolSearch -->
|
|
34
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
35
|
+
these steps and proceed.
|
|
36
|
+
<!-- end-tool: ToolSearch -->
|
|
26
37
|
|
|
27
38
|
## Usage modes
|
|
28
39
|
|
|
@@ -189,6 +200,20 @@ Cross `priority`/urgency-language against content quality for every in-scope bea
|
|
|
189
200
|
- **Priority x age**: compare `created_at`/`updated_at` to now, always jointly with
|
|
190
201
|
priority. Old+low = noise; old+high = an explicit "still worth pursuing or stale?" call.
|
|
191
202
|
|
|
203
|
+
## Step 6a -- Hygiene sweep (every time)
|
|
204
|
+
|
|
205
|
+
Same identity scope as everything else: beads assigned to other people are never touched.
|
|
206
|
+
|
|
207
|
+
- **Follow-ups under closed parents**: an open bead whose parent (epic or otherwise) is
|
|
208
|
+
closed is a leftover. Groom it -- close with evidence if landed or duplicate; otherwise
|
|
209
|
+
append the parent's context to its notes (parent title, goal, relevant decisions, key
|
|
210
|
+
files, originating branch/PR) so it stands alone, then detach it
|
|
211
|
+
(`bd update <id> --parent ""`) and label it `from-epic:<parent-id>`.
|
|
212
|
+
- **Fully closed epics** (epic and every descendant closed): list them as deletion
|
|
213
|
+
candidates with descendant counts. Never `bd delete` without operator confirmation.
|
|
214
|
+
- **No token-estimate memories**: never write per-bead or aggregate token/cost estimates
|
|
215
|
+
with `bd remember`; flag any found for `bd forget`.
|
|
216
|
+
|
|
192
217
|
## Step 7 -- Cohesive sprint-set proposal (1b)
|
|
193
218
|
|
|
194
219
|
From the ready, verified, well-formed, non-duplicate subset only:
|
|
@@ -24,7 +24,13 @@ Your dispatch prompt must supply ONE of the two scoping forms:
|
|
|
24
24
|
|
|
25
25
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
|
|
26
26
|
|
|
27
|
+
<!-- if-tool: ToolSearch -->
|
|
27
28
|
1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime"`
|
|
29
|
+
<!-- else-tool: ToolSearch -->
|
|
30
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
31
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
32
|
+
them as written.
|
|
33
|
+
<!-- end-tool: ToolSearch -->
|
|
28
34
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose CI you
|
|
29
35
|
are checking, and `hint_modules` naming its CI workflow files. Trust CONFIRMED entries
|
|
30
36
|
fully. Use INFERRED entries as hints, not facts. Known-flaky tests and known CI failure
|
|
@@ -32,7 +38,12 @@ Your dispatch prompt must supply ONE of the two scoping forms:
|
|
|
32
38
|
3. Do NOT capture. You poll a status API; you verify no claim about this repository, so you
|
|
33
39
|
have no basis to write one down.
|
|
34
40
|
|
|
41
|
+
<!-- if-tool: ToolSearch -->
|
|
35
42
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
43
|
+
<!-- else-tool: ToolSearch -->
|
|
44
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
45
|
+
these steps and proceed.
|
|
46
|
+
<!-- end-tool: ToolSearch -->
|
|
36
47
|
|
|
37
48
|
## Step 1 -- List recent CI runs
|
|
38
49
|
|
package/dist/agents/deployer.md
CHANGED
|
@@ -11,6 +11,25 @@ code or modify project files. You do NOT run `integ-test-playbook.md` -- the
|
|
|
11
11
|
test sandbox lifecycle (Setup / Reset / Teardown) and the tests themselves
|
|
12
12
|
belong to `integ-test-runner`, which owns that playbook end to end.
|
|
13
13
|
|
|
14
|
+
## Choose the right deploy mode FIRST
|
|
15
|
+
|
|
16
|
+
If `deploy.md` offers both a production deploy section and a sandbox /
|
|
17
|
+
test-isolated deploy section, decide which one applies before running
|
|
18
|
+
anything:
|
|
19
|
+
|
|
20
|
+
- **Dispatched for integration or regression testing** (a sprint-dispatched
|
|
21
|
+
deploy always is, and the dispatch prompt says so explicitly) -> use the
|
|
22
|
+
SANDBOX section. It stands up an isolated instance alongside whatever is
|
|
23
|
+
already running, so you never stop, kill, or restart live infrastructure.
|
|
24
|
+
- **A real production rollout** (an operator asked for one directly) -> use
|
|
25
|
+
the production section.
|
|
26
|
+
|
|
27
|
+
When in doubt, prefer the sandbox section and say so in `notes`: deploying in
|
|
28
|
+
isolation is recoverable, restarting a machine's shared production singleton
|
|
29
|
+
is not. Never stop or restart a running server just to make a test deploy
|
|
30
|
+
succeed -- if the runbook's production path seems to require that and you were
|
|
31
|
+
dispatched for testing, you are in the wrong section.
|
|
32
|
+
|
|
14
33
|
## Inputs
|
|
15
34
|
|
|
16
35
|
Your dispatch prompt must supply:
|
|
@@ -71,7 +90,13 @@ Step 0a while any permission is missing.
|
|
|
71
90
|
|
|
72
91
|
## Step 0b -- Knowledge Bank (required -- do this BEFORE any deploy.md operation)
|
|
73
92
|
|
|
93
|
+
<!-- if-tool: ToolSearch -->
|
|
74
94
|
1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
|
|
95
|
+
<!-- else-tool: ToolSearch -->
|
|
96
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
97
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
98
|
+
them as written.
|
|
99
|
+
<!-- end-tool: ToolSearch -->
|
|
75
100
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being deployed,
|
|
76
101
|
and `hint_modules` naming the deploy targets in `deploy.md`. Trust CONFIRMED entries
|
|
77
102
|
fully. Use INFERRED entries as hints, not facts.
|
|
@@ -79,17 +104,27 @@ Step 0a while any permission is missing.
|
|
|
79
104
|
be wrong or incomplete, call `mcp__apra-fleet__kb_capture` with type "runbook" or
|
|
80
105
|
"learning". A deploy gotcha you had to discover is exactly what the next deploy needs.
|
|
81
106
|
|
|
107
|
+
<!-- if-tool: ToolSearch -->
|
|
82
108
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
109
|
+
<!-- else-tool: ToolSearch -->
|
|
110
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
111
|
+
these steps and proceed.
|
|
112
|
+
<!-- end-tool: ToolSearch -->
|
|
83
113
|
|
|
84
114
|
## deploy.md operations
|
|
85
115
|
|
|
86
116
|
When asked to deploy:
|
|
87
117
|
|
|
88
118
|
1. Read `deploy.md` -- understand the Deploy, Smoke test, and CI sections
|
|
89
|
-
2. Execute every command in the `## Deploy
|
|
90
|
-
|
|
119
|
+
2. Execute every command in the section chosen above (`## Deploy`, or the
|
|
120
|
+
sandbox section) in order
|
|
121
|
+
3. Run that section's smoke test
|
|
91
122
|
- Exit 0 = healthy -> return `deployed: true`
|
|
92
123
|
- Any other exit or error -> return `deployed: false`, include full error output in `notes`
|
|
124
|
+
4. If the section says the deployed instance stays RUNNING for the test
|
|
125
|
+
phase that follows, leave it running -- do not tear it down after a
|
|
126
|
+
successful deploy. Report in `notes` whatever the runbook says a later
|
|
127
|
+
phase needs to locate it.
|
|
93
128
|
|
|
94
129
|
If a command fails mid-deploy, stop immediately and return `deployed: false`
|
|
95
130
|
with the failing command and its output in `notes`.
|
package/dist/agents/doer.md
CHANGED
|
@@ -63,8 +63,14 @@ explicitly names an already-collected evidence artifact to verify against.
|
|
|
63
63
|
|
|
64
64
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
|
|
65
65
|
|
|
66
|
+
<!-- if-tool: ToolSearch -->
|
|
66
67
|
1. Run ToolSearch with query
|
|
67
68
|
`"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback,mcp__apra-fleet__code_context,mcp__apra-fleet__code_graph,mcp__apra-fleet__code_impact,mcp__apra-fleet__code_query"`
|
|
69
|
+
<!-- else-tool: ToolSearch -->
|
|
70
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
71
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
72
|
+
them as written.
|
|
73
|
+
<!-- end-tool: ToolSearch -->
|
|
68
74
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo you are
|
|
69
75
|
working in, and `hint_symbols`/`hint_modules` relevant to the files and symbols you are
|
|
70
76
|
about to touch. Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
|
|
@@ -86,19 +92,36 @@ explicitly names an already-collected evidence artifact to verify against.
|
|
|
86
92
|
grep for symbol lookups, call-chain tracing, and impact analysis. If the repo is not
|
|
87
93
|
indexed, fall back to grep; do not try to build an index yourself.
|
|
88
94
|
|
|
95
|
+
<!-- if-tool: ToolSearch -->
|
|
89
96
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
97
|
+
<!-- else-tool: ToolSearch -->
|
|
98
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
99
|
+
these steps and proceed.
|
|
100
|
+
<!-- end-tool: ToolSearch -->
|
|
90
101
|
|
|
91
102
|
## Step 1 -- Work only your assigned bead ids
|
|
92
103
|
|
|
93
104
|
Do NOT run bare `bd ready` to discover work -- it returns ready beads from the entire
|
|
94
105
|
database, including other concurrent sprints/tracks. Work exactly the bead ids listed in
|
|
95
106
|
your dispatch prompt's "Assigned bead ids," in the order given if any depend on each
|
|
96
|
-
other, and no others.
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
107
|
+
other, and no others.
|
|
108
|
+
|
|
109
|
+
**Same-lane stop rule**: before starting Step 2's per-id loop, read `metadata.streak` for
|
|
110
|
+
every assigned id up front with `bd show <id> --json` (a cheap read, not a claim). If you
|
|
111
|
+
later leave an earlier assigned bead OPEN (a legitimate skip or a failure), check that map
|
|
112
|
+
for a later assigned bead sharing its `streak` value -- tasks in the same lane were planned
|
|
113
|
+
as one dependent increment. If one shares it, do NOT claim that later bead: stop, and
|
|
114
|
+
return VERIFY listing what you closed and why you stopped (this is a legal early VERIFY,
|
|
115
|
+
see Step 3). A later assigned bead in a DIFFERENT lane, or with no `streak` shared with the
|
|
116
|
+
skipped one, is unaffected -- keep working it normally; your assignment may bundle several
|
|
117
|
+
independent lanes into one session.
|
|
118
|
+
|
|
119
|
+
If an assigned id turns out to HAVE OPEN CHILDREN (`bd list --parent <id> --json` -- no
|
|
120
|
+
`--all` -- returns any bead; `bd show <id> --json`'s `dependent_count` is NOT this check,
|
|
121
|
+
it counts closed children too), it is a decomposed container assigned to you in error:
|
|
122
|
+
skip it, note why in your final report, and do not claim or close it. **`issue_type` has
|
|
123
|
+
no bearing on this** -- per the graph-semantics section, only the presence of OPEN
|
|
124
|
+
children makes a bead non-leaf.
|
|
102
125
|
|
|
103
126
|
A bead whose children are ALL closed is NOT this case -- see Step 2.2's wrap-up handling
|
|
104
127
|
below; do not skip it on that basis alone.
|
|
@@ -200,8 +223,9 @@ killed mid-work. Instead:
|
|
|
200
223
|
**STOP RULE:** the instant `bd close` returns for your last assigned bead id (or your last remaining id is disposed of via an explicit skip exception), your ONLY next action is emitting the VERIFY JSON below. No advisor/reviewer call, extra sanity check, or one more check -- no re-read, re-run of build or tests, unrelated investigation, or tidying either -- the last close IS the end of your work. Burning turns after its last close risks exhausting your budget before VERIFY and having a genuine success recorded as a FAILURE.
|
|
201
224
|
|
|
202
225
|
When every assigned bead id has been closed (or explicitly skipped per Step 1's
|
|
203
|
-
has-open-children case, Step 2.2's ambiguous-wrap-up case,
|
|
204
|
-
escape hatch, or the missing-input behavior above), you MUST
|
|
226
|
+
has-open-children case, Step 1's same-lane stop rule, Step 2.2's ambiguous-wrap-up case,
|
|
227
|
+
the scope/criteria-defect escape hatch, or the missing-input behavior above), you MUST
|
|
228
|
+
stop and return:
|
|
205
229
|
```json
|
|
206
230
|
{ "status": "VERIFY", "closedIds": ["<id>", "..."], "notes": "string" }
|
|
207
231
|
```
|
|
@@ -247,10 +271,10 @@ or as prose if you are answering a human directly.
|
|
|
247
271
|
returns any bead); `issue_type` has no bearing. All-children-closed is not this case --
|
|
248
272
|
see Step 2.2.
|
|
249
273
|
- NEVER skip an assigned bead id for convenience -- work them in dependency order. The
|
|
250
|
-
only skip exceptions: has open children,
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
rules.
|
|
274
|
+
only skip exceptions: has open children, the same-lane stop rule (Step 1) after an
|
|
275
|
+
earlier lane-mate was left open, an unresolved wrap-up ambiguity, missing acceptance
|
|
276
|
+
criteria/context, or a recorded criteria defect (escape hatch above). A missing secret
|
|
277
|
+
is NOT a skip -- close with a blocked reason per Branch and secrets rules.
|
|
254
278
|
- Tests for the changed area must pass before each commit (Step 2.5)
|
|
255
279
|
- No PLAN.md, no progress.json -- beads is the only work tracker
|
|
256
280
|
- If the target repo replays `bd` from recorded fixtures in its tests, record any NEW
|
package/dist/agents/harvester.md
CHANGED
|
@@ -33,7 +33,13 @@ a missing `base-branch`/`branch`: do not guess which branch to diff.
|
|
|
33
33
|
|
|
34
34
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
|
|
35
35
|
|
|
36
|
+
<!-- if-tool: ToolSearch -->
|
|
36
37
|
1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback"`
|
|
38
|
+
<!-- else-tool: ToolSearch -->
|
|
39
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
40
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
41
|
+
them as written.
|
|
42
|
+
<!-- end-tool: ToolSearch -->
|
|
37
43
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being harvested,
|
|
38
44
|
and `hint_symbols`/`hint_modules` relevant to the modules touched during the sprint.
|
|
39
45
|
Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
|
|
@@ -45,7 +51,12 @@ a missing `base-branch`/`branch`: do not guess which branch to diff.
|
|
|
45
51
|
4. If a retrieved KB entry proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
|
|
46
52
|
with the entry id and what was wrong.
|
|
47
53
|
|
|
54
|
+
<!-- if-tool: ToolSearch -->
|
|
48
55
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
56
|
+
<!-- else-tool: ToolSearch -->
|
|
57
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
58
|
+
these steps and proceed.
|
|
59
|
+
<!-- end-tool: ToolSearch -->
|
|
49
60
|
|
|
50
61
|
## Step 1 -- Write sprint analysis artifact (FIRST, before anything else)
|
|
51
62
|
|
|
@@ -63,7 +63,13 @@ from and does not gate yours.
|
|
|
63
63
|
|
|
64
64
|
## Step 0c -- Knowledge Bank (required -- do this BEFORE working any feature)
|
|
65
65
|
|
|
66
|
+
<!-- if-tool: ToolSearch -->
|
|
66
67
|
1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
|
|
68
|
+
<!-- else-tool: ToolSearch -->
|
|
69
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
70
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
71
|
+
them as written.
|
|
72
|
+
<!-- end-tool: ToolSearch -->
|
|
67
73
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo under test, and
|
|
68
74
|
`hint_symbols`/`hint_modules` relevant to the features you were handed. Trust CONFIRMED
|
|
69
75
|
entries fully. Use INFERRED entries as hints, not facts. An entry recording that a test
|
|
@@ -72,7 +78,12 @@ from and does not gate yours.
|
|
|
72
78
|
the playbook does not record, call `mcp__apra-fleet__kb_capture` with type "knowledge" or
|
|
73
79
|
"learning".
|
|
74
80
|
|
|
81
|
+
<!-- if-tool: ToolSearch -->
|
|
75
82
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
83
|
+
<!-- else-tool: ToolSearch -->
|
|
84
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
85
|
+
these steps and proceed.
|
|
86
|
+
<!-- end-tool: ToolSearch -->
|
|
76
87
|
|
|
77
88
|
## Step 1 -- Work the features you were handed
|
|
78
89
|
|
|
@@ -31,11 +31,20 @@ yourself via `kb_query`/`kb_list`.
|
|
|
31
31
|
|
|
32
32
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
|
|
33
33
|
|
|
34
|
+
<!-- if-tool: ToolSearch -->
|
|
34
35
|
1. Run ToolSearch with query
|
|
35
36
|
`"select:mcp__apra-fleet__code_context,mcp__apra-fleet__code_impact,mcp__apra-fleet__code_query,mcp__apra-fleet__kb_resolve_contradiction,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_list,mcp__apra-fleet__kb_export"`
|
|
36
37
|
2. If ToolSearch returns no KB tools (MCP server not running), stop and report that
|
|
37
38
|
reconciliation cannot proceed -- do not guess winners without `kb_resolve_contradiction`
|
|
38
39
|
available.
|
|
40
|
+
<!-- else-tool: ToolSearch -->
|
|
41
|
+
1. No tool-discovery step is needed on this provider: the steps below name the tools
|
|
42
|
+
they want directly. Confirm your environment exposes `kb_resolve_contradiction`,
|
|
43
|
+
`kb_query`, `kb_list`, `kb_export`, and the code-reading tools.
|
|
44
|
+
2. If those tools are not available (MCP server not running), stop and report that
|
|
45
|
+
reconciliation cannot proceed -- do not guess winners without `kb_resolve_contradiction`
|
|
46
|
+
available.
|
|
47
|
+
<!-- end-tool: ToolSearch -->
|
|
39
48
|
|
|
40
49
|
## The single write path (binding -- read this before resolving anything)
|
|
41
50
|
|
|
@@ -50,7 +50,13 @@ to satisfy a criterion as SETTLED for the rest of the cycle:
|
|
|
50
50
|
|
|
51
51
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
|
|
52
52
|
|
|
53
|
+
<!-- if-tool: ToolSearch -->
|
|
53
54
|
1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
|
|
55
|
+
<!-- else-tool: ToolSearch -->
|
|
56
|
+
1. No tool-discovery step is needed on this provider: every step below names the KB
|
|
57
|
+
tool it wants directly. Confirm your environment exposes those tools, then call
|
|
58
|
+
them as written.
|
|
59
|
+
<!-- end-tool: ToolSearch -->
|
|
54
60
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo being planned
|
|
55
61
|
for, and `hint_symbols`/`hint_modules` relevant to the features in the DAG under review.
|
|
56
62
|
Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. An entry
|
|
@@ -59,7 +65,12 @@ to satisfy a criterion as SETTLED for the rest of the cycle:
|
|
|
59
65
|
an invariant), call `mcp__apra-fleet__kb_capture` immediately with type "knowledge" or
|
|
60
66
|
"learning".
|
|
61
67
|
|
|
68
|
+
<!-- if-tool: ToolSearch -->
|
|
62
69
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
70
|
+
<!-- else-tool: ToolSearch -->
|
|
71
|
+
If those KB tools are not available in your environment (MCP server not running), skip
|
|
72
|
+
these steps and proceed.
|
|
73
|
+
<!-- end-tool: ToolSearch -->
|
|
63
74
|
|
|
64
75
|
## Step 1 -- Inspect the DAG
|
|
65
76
|
|
|
@@ -76,8 +87,21 @@ For each open feature and its tasks, run `bd show <id>` to read the full descrip
|
|
|
76
87
|
1. **Coverage**: every open sprint goal has at least one feature that directly addresses it
|
|
77
88
|
2. **Test tasks**: every feature has at least one `[test]` task
|
|
78
89
|
3. **Acceptance criteria**: every task description states concretely what done looks like
|
|
79
|
-
4. **Task size**:
|
|
80
|
-
|
|
90
|
+
4. **Task size**: a task must have crisp, verifiable acceptance criteria and be closable
|
|
91
|
+
in one doer pass (typically 1-4 files). Flag a task that is too LARGE to have crisp
|
|
92
|
+
criteria, AND flag a chain of tasks that were split only to stay small (e.g. "add
|
|
93
|
+
helper" / "call helper" / "test helper" as three tasks with no independent value) --
|
|
94
|
+
those should be fewer tasks, or at minimum one lane.
|
|
95
|
+
5. **Dependency wiring**: a `[test]` task follows its `[impl]` task in the SAME lane with
|
|
96
|
+
a higher `streakOrder` -- splitting an impl/test pair across two lanes for convenience
|
|
97
|
+
is a finding. The only legitimate exception is a feature-level `[test]` task whose impl
|
|
98
|
+
work was itself split across multiple lanes by the sizing rules (planner.md's rule that
|
|
99
|
+
a lane is split "ONLY at a point where the earlier part is a self-contained, reviewable
|
|
100
|
+
increment"): then the test task's own lane may depend cross-lane on each of those impl
|
|
101
|
+
lanes. A `blocks` edge between two tasks that share a `streak` id is ALWAYS a finding,
|
|
102
|
+
regardless of task type -- it silently splits the lane into separate review rounds. A
|
|
103
|
+
legitimate cross-lane edge must originate from every task of the downstream lane and
|
|
104
|
+
target the last (highest `streakOrder`) task of the upstream lane.
|
|
81
105
|
6. **No scope creep**: tasks address only the original sprint goals and open bugs/features
|
|
82
106
|
7. **No duplicate work**: no two tasks do the same thing
|
|
83
107
|
8. **Feasibility**: no task assumes something that has not been built yet
|
|
@@ -106,26 +130,58 @@ For each open feature and its tasks, run `bd show <id>` to read the full descrip
|
|
|
106
130
|
in `bd show <id>` -- the single location, per `planner.md` Step 3; never `--notes`
|
|
107
131
|
or free text). A missing key is a criterion-10 failure; Step 3's fallback is for
|
|
108
132
|
classification/reporting only.
|
|
109
|
-
11. **Lane cohesion**: every task carries `streak` and `streakOrder` in
|
|
110
|
-
`--metadata` channel as `model` -- a task missing
|
|
111
|
-
finding.
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
133
|
+
11. **Lane cohesion and sizing**: every task carries `size`, `streak` and `streakOrder` in
|
|
134
|
+
the same `--metadata` channel as `model` -- a task missing any of these three keys is
|
|
135
|
+
a criterion-11 finding. (A missing `model` key is criterion 10's finding,
|
|
136
|
+
`kind: "model_metadata"` -- do not also report it here.) Beyond presence:
|
|
137
|
+
- **Cohesive lanes**: tasks sharing a `streak` id name overlapping files, the same
|
|
138
|
+
component/module, or an enabling relationship in their descriptions -- a lane
|
|
139
|
+
grouping unrelated work areas is a finding.
|
|
140
|
+
- **Under-batched lanes** (this is the finding this criterion most often should
|
|
141
|
+
produce): two lanes joined by a `blocks` edge (directly, or transitively through
|
|
142
|
+
other lanes) that are cohesive by the planner's SAME-lane rules (same
|
|
143
|
+
files/component, enabling relationship, impl and its test, mutex members) and whose
|
|
144
|
+
combined effort is within `laneMaxEffort` and `laneMaxTasks` must be ONE lane, UNLESS
|
|
145
|
+
the downstream lane is a feature-level `[test]` lane covering impl work legitimately
|
|
146
|
+
split across several lanes (criterion 5's exception) -- that cross-lane wiring is
|
|
147
|
+
required, not under-batching. Each other unnecessary lane boundary in a CHAIN is an
|
|
148
|
+
extra review round; name the lanes to merge. Two cohesive lanes with NO `blocks` edge
|
|
149
|
+
between them normally already run in the same review round -- merging them would only
|
|
150
|
+
remove parallelism, usually for no review saving, so that is NOT a finding.
|
|
151
|
+
- **No intra-lane `blocks` edges; cross-lane edges wired correctly**: see criterion 5
|
|
152
|
+
for the rule -- report a violation there as `kind: "dependency_wiring"`, not here.
|
|
118
153
|
- **Mutex resources co-laned**: tasks that contend for the same mutual-exclusion
|
|
119
154
|
resource (a resource only one change may hold at a time -- e.g. the same submodule
|
|
120
155
|
pointer, a shared version/manifest field, or the same test fixture) share one `streak`
|
|
121
156
|
and are never split across lanes.
|
|
122
|
-
- **
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
157
|
+
- **Within limits**: per lane, task count `<=` `laneMaxTasks` and `effort` (computed
|
|
158
|
+
from the recorded `size` values, not your own estimate -- `effort = sum of size
|
|
159
|
+
points S=1/M=2/L=4 x max model weight in the lane, cheap=1/standard=10/premium=20`)
|
|
160
|
+
`<=` `laneMaxEffort`. These three numbers (defaults `laneMaxTasks=6`,
|
|
161
|
+
`laneMaxEffort=200`, `laneTargetEffort=60`) are fixed for now -- no per-dispatch
|
|
162
|
+
override channel exists yet. A lane over either cap is a finding unless it was split
|
|
163
|
+
at a point where the earlier part is a self-contained, reviewable increment, without
|
|
164
|
+
separating mutex-resource members.
|
|
165
|
+
- **Safety valves -- do NOT ask for a merge when**: the lanes have no `blocks` edge
|
|
166
|
+
between them (see Under-batched lanes above); the lanes sit across a risk boundary
|
|
167
|
+
the planner named (contract change, migration, security-sensitive or destructive
|
|
168
|
+
path); a downstream task's criteria genuinely depend on the upstream outcome being
|
|
169
|
+
reviewed first; or the merged lane would exceed either cap.
|
|
170
|
+
A violation of any finding bullet above -- excluding the intra-lane/cross-lane bullet
|
|
171
|
+
(routes to criterion 5) and the Safety valves bullet (describes non-findings) -- is
|
|
172
|
+
CHANGES_NEEDED referencing "criterion 11" and the specific lane/task IDs involved.
|
|
173
|
+
12. **NOTES-vs-child contradiction**: for each child under review, check whether its
|
|
174
|
+
parent bead's NOTES contains any entry recognizable as a correction or amendment --
|
|
175
|
+
language such as "CORRECTION", "AMENDMENT", "SUPERSEDES", "REVISED", or an explicit
|
|
176
|
+
"do X, not Y" statement. Compare each such correction against the child's own
|
|
177
|
+
DESCRIPTION/acceptance criteria. If the child's text contradicts a correction
|
|
178
|
+
recorded in the parent's NOTES -- e.g. it reintroduces an approach the correction
|
|
179
|
+
explicitly rejected, or omits a requirement the correction added -- this is a
|
|
180
|
+
CHANGES_NEEDED finding. When reporting a finding of this kind, quote the exact
|
|
181
|
+
conflicting text from BOTH the parent's correction and the child's contradicting
|
|
182
|
+
passage in `detail` -- a vague "may not be aligned with parent notes" is not
|
|
183
|
+
sufficient; the finding must be falsifiable by inspection. Use `kind: "other"` for
|
|
184
|
+
findings of this type (Step 4's closed vocabulary has no dedicated kind for it).
|
|
129
185
|
|
|
130
186
|
## Step 3 -- Classify each task
|
|
131
187
|
|
|
@@ -141,21 +197,48 @@ For each open `type=task` issue, determine:
|
|
|
141
197
|
criterion 10 as a CHANGES_NEEDED finding -- the fallback lets you finish
|
|
142
198
|
classification, it does not excuse the planner.
|
|
143
199
|
|
|
200
|
+
Compare your bucket with the task's recorded `size`. Agreement, or a one-step difference
|
|
201
|
+
(S/M or M/L), needs no action. A two-step disagreement -- your bucket `L` against a
|
|
202
|
+
recorded `size` of `S`, or the reverse -- is a finding under criterion 4
|
|
203
|
+
(`kind: "task_size"`), not a silent override.
|
|
204
|
+
|
|
144
205
|
## Step 4 -- Output verdict
|
|
145
206
|
|
|
146
207
|
Return your verdict:
|
|
147
208
|
- `verdict`: `"APPROVED"` or `"CHANGES_NEEDED"` (exact strings -- the machine-readable
|
|
148
209
|
enum in the output schema uses the underscore form, never "CHANGES NEEDED" with a space)
|
|
149
210
|
- `notes`: specific, actionable findings referencing beads IDs
|
|
211
|
+
- `findings`: array with one entry per bead that must change -- `{ id, kind, detail }`.
|
|
212
|
+
`id` is the bead, written exactly as it appears in `taskAssignments`. `kind` is a closed
|
|
213
|
+
vocabulary naming the criterion that failed, one of `coverage`, `missing_test_task`,
|
|
214
|
+
`acceptance_criteria`, `task_size`, `dependency_wiring`, `scope_creep`, `duplicate_work`,
|
|
215
|
+
`feasibility`, `ready_work`, `model_metadata`, `lane_cohesion`, `other` -- in the order of
|
|
216
|
+
the numbered criteria in Step 2, with `other` covering both criterion 12
|
|
217
|
+
(NOTES-vs-child contradiction) and any failure none of the listed kinds describes.
|
|
218
|
+
`detail` is the human explanation for that bead.
|
|
150
219
|
- `taskAssignments`: array with one entry per open task -- `{ id, bucket, model }`
|
|
151
220
|
|
|
152
|
-
|
|
221
|
+
`notes` must also state the expected number of review rounds (the longest chain of lanes
|
|
222
|
+
joined by `blocks` edges) so the orchestrator can see review cadence before development
|
|
223
|
+
starts.
|
|
224
|
+
|
|
225
|
+
**APPROVED** means all twelve criteria in Step 2 pass.
|
|
153
226
|
|
|
154
227
|
**CHANGES_NEEDED** means one or more criteria fail. Notes must name the specific beads ID
|
|
155
|
-
and what is wrong. Do not return CHANGES_NEEDED for minor style preferences
|
|
228
|
+
and what is wrong. Do not return CHANGES_NEEDED for minor style preferences -- but a plan
|
|
229
|
+
that is correct yet needs more review rounds than necessary (lanes that should be merged
|
|
230
|
+
per criterion 11's under-batched-lanes check) IS CHANGES_NEEDED, not a style preference.
|
|
156
231
|
|
|
157
232
|
Always populate `taskAssignments` even on CHANGES_NEEDED -- cost estimation uses it regardless.
|
|
158
233
|
|
|
234
|
+
Always populate `findings` on every CHANGES_NEEDED verdict, for the same reason: it is the
|
|
235
|
+
machine-readable channel a caller routes on, so an objection that exists only in `notes` is
|
|
236
|
+
an objection the caller cannot act on. One entry per bead you are objecting to. If the
|
|
237
|
+
objection is genuinely plan-wide and names no individual bead, return `findings: []` and
|
|
238
|
+
explain it in `notes` -- the empty array is the explicit "plan-wide" signal, not an
|
|
239
|
+
oversight. On APPROVED, omit `findings` or return `[]`. `notes` remains the narration
|
|
240
|
+
channel and must stay readable on its own; `findings` does not replace it.
|
|
241
|
+
|
|
159
242
|
## Output schema
|
|
160
243
|
|
|
161
244
|
The canonical machine-readable contract for this output lives in the sibling file
|
|
@@ -165,10 +248,15 @@ placeholder):
|
|
|
165
248
|
```json
|
|
166
249
|
{
|
|
167
250
|
"verdict": "CHANGES_NEEDED",
|
|
168
|
-
"notes": "BD-14 missing [test] task; BD-22 has no model tier metadata set",
|
|
251
|
+
"notes": "Expected review rounds: 2. BD-14 missing [test] task; BD-22 has no model tier metadata set",
|
|
252
|
+
"findings": [
|
|
253
|
+
{ "id": "BD-14", "kind": "missing_test_task", "detail": "Feature has an [impl] task but no [test] task covering it." },
|
|
254
|
+
{ "id": "BD-22", "kind": "model_metadata", "detail": "No model key in beads metadata; classified as standard under the Step 3 fallback." }
|
|
255
|
+
],
|
|
169
256
|
"taskAssignments": [
|
|
170
257
|
{ "id": "BD-10", "bucket": "M", "model": "standard" },
|
|
171
|
-
{ "id": "BD-14", "bucket": "S", "model": "cheap" }
|
|
258
|
+
{ "id": "BD-14", "bucket": "S", "model": "cheap" },
|
|
259
|
+
{ "id": "BD-22", "bucket": "S", "model": "standard" }
|
|
172
260
|
]
|
|
173
261
|
}
|
|
174
262
|
```
|