@apralabs/apra-fleet 0.4.1 → 0.4.2
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 +16 -8
- package/dist/agents/backlog-groomer.md +17 -21
- package/dist/agents/ci-watcher.md +3 -0
- package/dist/agents/deployer.md +22 -44
- package/dist/agents/doer.md +131 -132
- package/dist/agents/harvester.md +20 -32
- package/dist/agents/integ-test-runner.md +81 -113
- package/dist/agents/kb-reconciler.md +31 -42
- package/dist/agents/plan-reviewer.md +32 -44
- package/dist/agents/planner.md +51 -63
- package/dist/agents/regression-test-runner.md +65 -80
- package/dist/agents/reviewer.md +56 -83
- package/dist/agents/schemas/integ-test-runner-output.json +1 -1
- package/dist/agents/schemas/regression-test-runner-output.json +4 -17
- package/dist/cli/auth.d.ts.map +1 -1
- package/dist/cli/auth.js +1 -2
- package/dist/cli/auth.js.map +1 -1
- package/dist/cli/config.d.ts +3 -3
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +4 -13
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +5 -39
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/register-member.js +1 -1
- package/dist/cli/start.d.ts.map +1 -1
- package/dist/cli/start.js +7 -0
- package/dist/cli/start.js.map +1 -1
- package/dist/cli/uninstall.d.ts.map +1 -1
- package/dist/cli/uninstall.js +5 -3
- package/dist/cli/uninstall.js.map +1 -1
- package/dist/cli/watch.d.ts +26 -3
- package/dist/cli/watch.d.ts.map +1 -1
- package/dist/cli/watch.js +41 -9
- package/dist/cli/watch.js.map +1 -1
- package/dist/os/git-bash-candidates.d.ts +35 -0
- package/dist/os/git-bash-candidates.d.ts.map +1 -0
- package/dist/os/git-bash-candidates.js +46 -0
- package/dist/os/git-bash-candidates.js.map +1 -0
- package/dist/os/index.d.ts +13 -4
- package/dist/os/index.d.ts.map +1 -1
- package/dist/os/index.js +17 -2
- package/dist/os/index.js.map +1 -1
- package/dist/os/linux.js +1 -1
- package/dist/os/linux.js.map +1 -1
- package/dist/os/os-commands.d.ts +7 -0
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/os-commands.js.map +1 -1
- package/dist/os/windows-gitbash.d.ts +93 -0
- package/dist/os/windows-gitbash.d.ts.map +1 -0
- package/dist/os/windows-gitbash.js +244 -0
- package/dist/os/windows-gitbash.js.map +1 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +27 -5
- package/dist/os/windows.js.map +1 -1
- package/dist/providers/agy.d.ts +3 -2
- package/dist/providers/agy.d.ts.map +1 -1
- package/dist/providers/agy.js +11 -2
- package/dist/providers/agy.js.map +1 -1
- package/dist/providers/claude.d.ts +3 -2
- package/dist/providers/claude.d.ts.map +1 -1
- package/dist/providers/claude.js +22 -3
- package/dist/providers/claude.js.map +1 -1
- package/dist/providers/codex.d.ts +3 -2
- package/dist/providers/codex.d.ts.map +1 -1
- package/dist/providers/codex.js +5 -2
- package/dist/providers/codex.js.map +1 -1
- package/dist/providers/copilot.d.ts +3 -2
- package/dist/providers/copilot.d.ts.map +1 -1
- package/dist/providers/copilot.js +7 -2
- package/dist/providers/copilot.js.map +1 -1
- package/dist/providers/index.d.ts +0 -1
- package/dist/providers/index.d.ts.map +1 -1
- package/dist/providers/index.js +0 -3
- package/dist/providers/index.js.map +1 -1
- package/dist/providers/none.d.ts +3 -2
- package/dist/providers/none.d.ts.map +1 -1
- package/dist/providers/none.js +5 -2
- package/dist/providers/none.js.map +1 -1
- package/dist/providers/opencode.d.ts +3 -2
- package/dist/providers/opencode.d.ts.map +1 -1
- package/dist/providers/opencode.js +5 -2
- package/dist/providers/opencode.js.map +1 -1
- package/dist/providers/provider.d.ts +16 -7
- package/dist/providers/provider.d.ts.map +1 -1
- package/dist/providers/provider.js +2 -2
- package/dist/providers/provider.js.map +1 -1
- package/dist/services/agent-provisioner.js +2 -2
- package/dist/services/agent-provisioner.js.map +1 -1
- package/dist/services/cloud/activity.js +2 -2
- package/dist/services/cloud/activity.js.map +1 -1
- package/dist/services/context-admission.d.ts.map +1 -1
- package/dist/services/context-admission.js +9 -7
- package/dist/services/context-admission.js.map +1 -1
- package/dist/services/credential-cleanup.d.ts.map +1 -1
- package/dist/services/credential-cleanup.js +22 -3
- package/dist/services/credential-cleanup.js.map +1 -1
- package/dist/services/member-home.d.ts +1 -1
- package/dist/services/member-home.d.ts.map +1 -1
- package/dist/services/member-home.js +15 -12
- package/dist/services/member-home.js.map +1 -1
- package/dist/services/model-pricing.d.ts.map +1 -1
- package/dist/services/model-pricing.js +0 -5
- package/dist/services/model-pricing.js.map +1 -1
- package/dist/services/orphan-recovery.d.ts +6 -3
- package/dist/services/orphan-recovery.d.ts.map +1 -1
- package/dist/services/orphan-recovery.js +17 -14
- package/dist/services/orphan-recovery.js.map +1 -1
- package/dist/services/preflight-check.js +2 -2
- package/dist/services/preflight-check.js.map +1 -1
- package/dist/services/shell-probe.d.ts +131 -0
- package/dist/services/shell-probe.d.ts.map +1 -0
- package/dist/services/shell-probe.js +210 -0
- package/dist/services/shell-probe.js.map +1 -0
- package/dist/services/singleton.d.ts +2 -0
- package/dist/services/singleton.d.ts.map +1 -1
- package/dist/services/singleton.js +1 -1
- package/dist/services/singleton.js.map +1 -1
- package/dist/services/ssh.js +2 -2
- package/dist/services/ssh.js.map +1 -1
- package/dist/services/stall/find-log-file.d.ts.map +1 -1
- package/dist/services/stall/find-log-file.js +22 -16
- package/dist/services/stall/find-log-file.js.map +1 -1
- package/dist/services/stall/read-log-tail.d.ts.map +1 -1
- package/dist/services/stall/read-log-tail.js +6 -5
- package/dist/services/stall/read-log-tail.js.map +1 -1
- package/dist/services/stall/stall-poller.d.ts.map +1 -1
- package/dist/services/stall/stall-poller.js +35 -42
- package/dist/services/stall/stall-poller.js.map +1 -1
- package/dist/services/strategy.d.ts +9 -0
- package/dist/services/strategy.d.ts.map +1 -1
- package/dist/services/strategy.js +40 -6
- package/dist/services/strategy.js.map +1 -1
- package/dist/services/user-config.js +1 -1
- package/dist/services/user-config.js.map +1 -1
- package/dist/services/vcs/azure-devops.d.ts +1 -1
- package/dist/services/vcs/azure-devops.d.ts.map +1 -1
- package/dist/services/vcs/azure-devops.js +105 -10
- package/dist/services/vcs/azure-devops.js.map +1 -1
- package/dist/services/vcs/bitbucket.d.ts.map +1 -1
- package/dist/services/vcs/bitbucket.js +16 -0
- package/dist/services/vcs/bitbucket.js.map +1 -1
- package/dist/services/vcs/github.d.ts.map +1 -1
- package/dist/services/vcs/github.js +24 -0
- package/dist/services/vcs/github.js.map +1 -1
- package/dist/services/vcs/types.d.ts +123 -2
- package/dist/services/vcs/types.d.ts.map +1 -1
- package/dist/skills/fleet-sprint-cli/SKILL.md +2 -1
- package/dist/skills/pm/SKILL.md +0 -1
- package/dist/skills/pm/cost.md +0 -1
- package/dist/skills/pm/fleet-addendum.md +0 -1
- package/dist/tools/check-status.js +3 -3
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/cloud-control.js +2 -2
- package/dist/tools/cloud-control.js.map +1 -1
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +37 -24
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +28 -12
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +55 -18
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/list-members.d.ts.map +1 -1
- package/dist/tools/list-members.js +6 -2
- package/dist/tools/list-members.js.map +1 -1
- package/dist/tools/member-detail.d.ts.map +1 -1
- package/dist/tools/member-detail.js +5 -3
- package/dist/tools/member-detail.js.map +1 -1
- package/dist/tools/member-reservation.d.ts.map +1 -1
- package/dist/tools/member-reservation.js +13 -1
- package/dist/tools/member-reservation.js.map +1 -1
- package/dist/tools/monitor-task.d.ts.map +1 -1
- package/dist/tools/monitor-task.js +17 -2
- package/dist/tools/monitor-task.js.map +1 -1
- package/dist/tools/provision-auth.js +5 -5
- package/dist/tools/provision-auth.js.map +1 -1
- package/dist/tools/provision-vcs-auth.d.ts +5 -2
- package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
- package/dist/tools/provision-vcs-auth.js +58 -52
- package/dist/tools/provision-vcs-auth.js.map +1 -1
- package/dist/tools/register-member.d.ts +18 -12
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +42 -4
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/remove-member.js +2 -2
- package/dist/tools/remove-member.js.map +1 -1
- package/dist/tools/revoke-vcs-auth.js +2 -2
- package/dist/tools/revoke-vcs-auth.js.map +1 -1
- package/dist/tools/setup-ssh-key.d.ts.map +1 -1
- package/dist/tools/setup-ssh-key.js +2 -1
- package/dist/tools/setup-ssh-key.js.map +1 -1
- package/dist/tools/stop-prompt.js +2 -2
- package/dist/tools/stop-prompt.js.map +1 -1
- package/dist/tools/update-agent-cli.js +2 -2
- package/dist/tools/update-agent-cli.js.map +1 -1
- package/dist/tools/update-member.d.ts +18 -12
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +18 -1
- package/dist/tools/update-member.js.map +1 -1
- package/dist/types.d.ts +11 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-helpers.d.ts +36 -0
- package/dist/utils/agent-helpers.d.ts.map +1 -1
- package/dist/utils/agent-helpers.js +39 -1
- package/dist/utils/agent-helpers.js.map +1 -1
- package/dist/utils/platform.d.ts +7 -0
- package/dist/utils/platform.d.ts.map +1 -1
- package/dist/utils/platform.js +11 -1
- package/dist/utils/platform.js.map +1 -1
- package/dist/utils/workspace-trust.d.ts.map +1 -1
- package/dist/utils/workspace-trust.js +5 -1
- package/dist/utils/workspace-trust.js.map +1 -1
- package/dist/workflows/auto-sprint.js +4 -17
- package/package.json +2 -2
- package/packages/apra-fleet-client/src/client/api.mjs +92 -3
- package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -21
- package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +3 -0
- package/packages/apra-fleet-se/apra-pm/agents/deployer.md +22 -44
- package/packages/apra-fleet-se/apra-pm/agents/doer.md +131 -132
- package/packages/apra-fleet-se/apra-pm/agents/harvester.md +20 -32
- package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +81 -113
- package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +31 -42
- package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +32 -44
- package/packages/apra-fleet-se/apra-pm/agents/planner.md +51 -63
- package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +65 -80
- package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +56 -83
- package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
- package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
- package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
- package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +0 -1
- package/packages/apra-fleet-se/bin/cli.mjs +132 -3
- package/packages/apra-fleet-se/bin/serve.mjs +36 -1
- package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +151 -33
- package/packages/apra-fleet-se/fleet-sprint/docs/README.md +22 -7
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
- package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +9 -4
- package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +2 -2
- package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
- package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
- package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
- package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +67 -16
- package/packages/apra-fleet-se/fleet-sprint/errors.mjs +41 -0
- package/packages/apra-fleet-se/fleet-sprint/runner.js +1140 -209
- package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
- package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
- package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
- package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
- package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +2 -1
- package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -43
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
- package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
- package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +92 -37
- package/packages/apra-fleet-workflow/src/viewer/index.mjs +167 -1
- package/packages/apra-fleet-workflow/src/workflow/index.mjs +435 -31
- package/skills/fleet/SKILL.md +20 -9
- package/skills/fleet/auth-azdevops.md +44 -5
- package/skills/fleet/auth-bitbucket.md +3 -3
- package/skills/fleet/auth-github.md +2 -2
- package/skills/fleet/beads-conflict-resolution.md +141 -0
- package/skills/fleet/beads.md +16 -12
- package/skills/fleet/onboarding.md +4 -4
- package/skills/fleet/permissions.md +6 -6
- package/skills/fleet/skill-matrix.md +1 -1
- package/skills/fleet/troubleshooting.md +2 -1
- package/version.json +1 -1
- package/dist/providers/gemini.d.ts +0 -52
- package/dist/providers/gemini.d.ts.map +0 -1
- package/dist/providers/gemini.js +0 -236
- package/dist/providers/gemini.js.map +0 -1
- package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
package/README.md
CHANGED
|
@@ -59,7 +59,7 @@ One control plane. Any device. Any model. Any workflow. Any domain.
|
|
|
59
59
|
| Pillar | Concretely |
|
|
60
60
|
|---|---|
|
|
61
61
|
| **Any device** | Register any Windows / macOS / Linux machine (local or over SSH) as a fleet member in one command. Cloud members auto-start on demand. Windows members are fully supported for dispatch, command execution, and background long-running tasks (launched detached via WMI). |
|
|
62
|
-
| **Any model** | Claude, Codex,
|
|
62
|
+
| **Any model** | Claude, Codex, Copilot, Antigravity, local models (any OpenAI-compatible endpoint via OpenCode) -- mixed freely. Tier-based routing (cheap / standard / premium) keeps cost governance built in. Cross-provider review is a quality mechanism: a different model, with different blind spots, checks every change. |
|
|
63
63
|
| **Any workflow** | Workflows are durable programs, not prompt chains: multi-hour, resumable, observable, with member reservations and atomic state. Write your own; ship it to the fleet. |
|
|
64
64
|
| **Any domain** | Not just software development. The pattern fits wherever work decomposes into agent-sized pieces that need orchestration and an audit trail: nightly retail replenishment (reconcile inventory deltas, draft purchase orders for sign-off), logistics exception handling (triage a delayed shipment, re-book, notify), healthcare intake (summarize referrals, check completeness, route), back-office runs (invoice matching, compliance evidence collection). Software engineering is the vertical running today -- your domain is a workflow away. |
|
|
65
65
|
|
|
@@ -106,8 +106,8 @@ double-click it (installation is the default action):
|
|
|
106
106
|
|
|
107
107
|
```bash
|
|
108
108
|
npm install -g @apralabs/apra-fleet
|
|
109
|
-
apra-fleet
|
|
110
|
-
apra-fleet --llm agy
|
|
109
|
+
apra-fleet install # installs for Claude Code (default)
|
|
110
|
+
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
|
|
|
@@ -178,8 +178,8 @@ flowchart LR
|
|
|
178
178
|
|
|
179
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.
|
|
180
180
|
- **Members**: real machines running provider CLIs. Composes provider-native permissions before every dispatch; unattended modes are scoped, never blanket.
|
|
181
|
-
- **Workflow engine**: runs workflow programs with phases, retries, turn budgets, resumable sessions,
|
|
182
|
-
- **Supervisor**: always-on layer -- launch & stop sprints over HTTP, member reservation ledger, crash watchdog, run history.
|
|
181
|
+
- **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
|
+
- **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.
|
|
183
183
|
|
|
184
184
|
## Knowledge Layer
|
|
185
185
|
|
|
@@ -297,7 +297,12 @@ Secrets are entered out-of-band into a credential store and referenced as
|
|
|
297
297
|
any LLM or log. Credentials scope to members, expire on TTL, and can carry
|
|
298
298
|
a network egress policy (allow / deny / confirm). Every member runs with
|
|
299
299
|
composed, provider-native permission files -- allow-listed tools, not
|
|
300
|
-
god-mode. VCS access is provisioned and revocable per member
|
|
300
|
+
god-mode. VCS access is provisioned and revocable per member, across GitHub,
|
|
301
|
+
Bitbucket, and Azure DevOps -- host differences (URL shape, PR REST dialect,
|
|
302
|
+
auth pattern, error vocabulary) are hidden behind a per-provider descriptor
|
|
303
|
+
rather than leaking into shared code; see
|
|
304
|
+
`docs/design-azure-devops-vcs-auth.md` for the Azure DevOps provider's
|
|
305
|
+
credential-assembly and PAT-lifetime details. Permission
|
|
301
306
|
composition verifies its own delivery: a grant is read back off the target
|
|
302
307
|
member and structurally compared against what was intended before it is
|
|
303
308
|
reported as applied, so a failed or partial write is surfaced as an
|
|
@@ -424,12 +429,16 @@ third-party verticals.
|
|
|
424
429
|
| Git authentication | [docs/design-git-auth.md](docs/design-git-auth.md) |
|
|
425
430
|
| Cloud compute | [docs/cloud-compute.md](docs/cloud-compute.md) |
|
|
426
431
|
| Architecture | [docs/architecture.md](docs/architecture.md) |
|
|
432
|
+
| Windows shell selection (probe order, gitbash/pwsh7/powershell5, shell vs os) | [docs/windows-shell-selection.md](docs/windows-shell-selection.md) |
|
|
433
|
+
| Cross-shell command construction for member-bound commands | [docs/cross-shell-command-construction.md](docs/cross-shell-command-construction.md) |
|
|
427
434
|
| Knowledge Layer (setup, usage, provider swap) | [docs/knowledge-layer.md](docs/knowledge-layer.md) |
|
|
428
435
|
| Code intelligence provider abstraction | [docs/code-intelligence-providers.md](docs/code-intelligence-providers.md) |
|
|
429
436
|
| Hub-spoke cloud migration plan (historical; see tier-3 ownership ADR) | [docs/hub-spoke-master-plan.md](docs/hub-spoke-master-plan.md) |
|
|
430
437
|
| Tier-3 ownership decision (fleet-dashboard vs `src/hub-service/`) | [docs/adr-tier3-ownership.md](docs/adr-tier3-ownership.md) |
|
|
431
438
|
| Shared hub/dashboard API contract package | [packages/fleet-api-contract/README.md](packages/fleet-api-contract/README.md) |
|
|
432
|
-
| Workflow engine internals (`agent()`/`parallel()`/`pipeline()`, journal, budget) | [packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md](packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md) |
|
|
439
|
+
| Workflow engine internals (`agent()`/`parallel()`/`pipeline()`, journal, budget, pause/resume) | [packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md](packages/apra-fleet-workflow/docs/apra-fleet-workflow-architecture.md) |
|
|
440
|
+
| Cooperative workflow pause/resume (engine, viewer, supervisor, fleet-sprint) | [docs/features/workflow-pause-resume.md](docs/features/workflow-pause-resume.md) |
|
|
441
|
+
| Supervisor dashboard live-refresh (`/state` + `/events` SSE, tab-activation refresh, in-memory scope expansion) | [docs/features/supervisor-dashboard-live-refresh.md](docs/features/supervisor-dashboard-live-refresh.md) |
|
|
433
442
|
| Writing and running workflow scripts | [packages/apra-fleet-workflow/docs/workflow-guide.md](packages/apra-fleet-workflow/docs/workflow-guide.md) |
|
|
434
443
|
| Authoring a SEA-embedded `apra-fleet workflow` (manifest, entry contract, launcher env vars) | [docs/authoring-workflows.md](docs/authoring-workflows.md) |
|
|
435
444
|
| Workflow launcher fleet-server resolution order (HTTP singleton vs. stdio) | [docs/adr-workflow-server-resolution.md](docs/adr-workflow-server-resolution.md) |
|
|
@@ -439,7 +448,6 @@ third-party verticals.
|
|
|
439
448
|
| Auto-sprint internals (cycle loop, stall detection, budget, topology) | [packages/apra-fleet-se/docs/architecture.md](packages/apra-fleet-se/docs/architecture.md) |
|
|
440
449
|
| Auto-sprint agent role contracts | [packages/apra-fleet-se/docs/role-contracts.md](packages/apra-fleet-se/docs/role-contracts.md) |
|
|
441
450
|
| fleet-supervisor skill (start/stop/restart/auto-start-on-boot, sprint launch via HTTP API) | [packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md](packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md) |
|
|
442
|
-
| fleet-supervisor packaging self-containment audit | [packages/apra-fleet-se/docs/supervisor-selfcontainment-audit.md](packages/apra-fleet-se/docs/supervisor-selfcontainment-audit.md) |
|
|
443
451
|
| MCP client SDK overview (transports, `ApraFleet` API) | [packages/apra-fleet-client/docs/overview.md](packages/apra-fleet-client/docs/overview.md) |
|
|
444
452
|
| MCP client SDK API reference | [packages/apra-fleet-client/docs/api-reference.md](packages/apra-fleet-client/docs/api-reference.md) |
|
|
445
453
|
| MCP client SDK getting started | [packages/apra-fleet-client/docs/getting-started.md](packages/apra-fleet-client/docs/getting-started.md) |
|
|
@@ -16,9 +16,7 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
|
|
|
16
16
|
2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose backlog
|
|
17
17
|
you are grooming, and `hint_modules` naming the subsystems the assigned beads touch.
|
|
18
18
|
Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. This matters
|
|
19
|
-
most for duplicate detection and sprint-set grouping
|
|
20
|
-
are often the same underlying issue, and the KB is where that has already been written
|
|
21
|
-
down.
|
|
19
|
+
most for duplicate detection and sprint-set grouping.
|
|
22
20
|
3. When grooming turns up a durable backlog fact -- two ids that are genuinely the same
|
|
23
21
|
work, a dependency between beads that their text does not state, or a recurring reason
|
|
24
22
|
items land unactionable -- call `mcp__apra-fleet__kb_capture` with type "knowledge".
|
|
@@ -94,24 +92,23 @@ The canonical machine-readable contract lives in the sibling file
|
|
|
94
92
|
|
|
95
93
|
## Beads semantics
|
|
96
94
|
|
|
97
|
-
|
|
95
|
+
Graph semantics (`parent-child` = grouping, `blocks` = ordering, epic rules, `bd epic
|
|
96
|
+
status` gotchas) are canonical in `_shared/GRAPH-SEMANTICS.md`, the sibling file
|
|
97
|
+
installed alongside this one -- read it; do not restate or improvise those rules here.
|
|
98
|
+
Semantics specific to this role:
|
|
99
|
+
|
|
98
100
|
- `assignee` is set explicitly (`bd update <id> --assignee <identity>`) or via
|
|
99
101
|
`bd update <id> --claim` (also flips status to `in_progress`). Fall back to `owner`
|
|
100
|
-
(static, set
|
|
101
|
-
-
|
|
102
|
-
|
|
103
|
-
`open`/`in_progress`.
|
|
104
|
-
- `epic -> feature -> task` is a loose convention. The one hard rule: an epic may
|
|
105
|
-
`blocks` only another epic -- bd does not enforce same-type pairs.
|
|
106
|
-
- `bd epic status <id>` only rolls up correctly when `<id>` is actually typed `epic`;
|
|
107
|
-
on a non-epic id it silently returns unrelated epics.
|
|
102
|
+
(static, set at creation) only when `assignee` is empty.
|
|
103
|
+
- Only three things hide a bead from ready work: an unclosed child, an unmet `blocks`
|
|
104
|
+
dependency, or status not `open`/`in_progress`. `issue_type` never does.
|
|
108
105
|
- `gate` (`bd create --type=gate --await-type=<kind> --await-id=<id>`) blocks dependents
|
|
109
106
|
until an external condition resolves. Documented await-types are GitHub-shaped; when
|
|
110
107
|
recommending a gate, describe the pattern and let the operator pick an await-type
|
|
111
108
|
matching their actual VCS/CI.
|
|
112
|
-
- Title prefixes are convention, not schema, but widely matched on: `[test]` =
|
|
113
|
-
work
|
|
114
|
-
|
|
109
|
+
- Title prefixes are convention, not schema, but widely matched on: `[test]` =
|
|
110
|
+
verification work; `[impl]` = implementation; `[integ]` = filed by an integration
|
|
111
|
+
pass; `[regression][carry-over]` = rolled-over regression bug.
|
|
115
112
|
|
|
116
113
|
## Step 1 -- Load the backlog, scoped to identity
|
|
117
114
|
|
|
@@ -127,9 +124,8 @@ Fall back to non-`--json`/non-`--assignee` forms if unsupported, then filter cli
|
|
|
127
124
|
visibly separate. `bd show <id> --json` before any judgment call -- never flag
|
|
128
125
|
description quality from a summary line alone.
|
|
129
126
|
|
|
130
|
-
If a `bd` JSON payload is too large to read directly, redirect it
|
|
131
|
-
|
|
132
|
-
existing `.beads/` gitignore entry) -- never write scratch JSON to the repo root.
|
|
127
|
+
If a `bd` JSON payload is too large to read directly, redirect it to a gitignored
|
|
128
|
+
scratch path (e.g. `.beads/tmp/<name>.json`) -- never to the repo root.
|
|
133
129
|
|
|
134
130
|
## Step 2 -- Structural deadlock scan (every time)
|
|
135
131
|
|
|
@@ -241,10 +237,10 @@ The canonical machine-readable contract for this output lives in the sibling fil
|
|
|
241
237
|
```json
|
|
242
238
|
{
|
|
243
239
|
"status": "OK",
|
|
244
|
-
"identity": "
|
|
240
|
+
"identity": "dev@example.com",
|
|
245
241
|
"notes": "12 ready, 2 sprint sets proposed, 1 duplicate merged, 3 needing grooming.",
|
|
246
242
|
"ready": [
|
|
247
|
-
{ "id": "BD-14", "type": "task", "priority": "P1", "status": "open", "assignee": "
|
|
243
|
+
{ "id": "BD-14", "type": "task", "priority": "P1", "status": "open", "assignee": "dev@example.com", "ageDays": 4, "size": "M", "rationale": "No blockers, clear AC, feeds the auth epic." }
|
|
248
244
|
],
|
|
249
245
|
"sprintSets": [
|
|
250
246
|
{ "label": "auth-hardening", "beadIds": ["BD-14", "BD-15"], "reason": "Shared parent BD-10, sequential blocks edge." }
|
|
@@ -263,7 +259,7 @@ The canonical machine-readable contract for this output lives in the sibling fil
|
|
|
263
259
|
],
|
|
264
260
|
"notYours": [],
|
|
265
261
|
"stale": [
|
|
266
|
-
{ "id": "BD-60", "type": "bug", "priority": "P1", "status": "open", "assignee": "
|
|
262
|
+
{ "id": "BD-60", "type": "bug", "priority": "P1", "status": "open", "assignee": "dev@example.com", "ageDays": 95, "size": "S", "rationale": "P1, 95 days untouched -- likely dropped, confirm before continuing to carry it." }
|
|
267
263
|
],
|
|
268
264
|
"structuralIssues": [
|
|
269
265
|
{ "kind": "deadlock", "description": "BD-70 blocks its own parent BD-71", "beadIds": ["BD-70", "BD-71"] }
|
|
@@ -48,6 +48,9 @@ gh run list --pr <prNumber> --limit 5 --json databaseId,status,conclusion,headSh
|
|
|
48
48
|
(In PR-scoped mode, apply Step 2 to the runs for the PR's head commit instead of
|
|
49
49
|
`expectedHeadSha`.)
|
|
50
50
|
|
|
51
|
+
If `gh` is unavailable or the repo's remote is not GitHub, do not guess at another CI
|
|
52
|
+
system: return `status: "not_configured"` with `notes` naming what was found.
|
|
53
|
+
|
|
51
54
|
## Step 2 -- Interpret the result
|
|
52
55
|
|
|
53
56
|
**No runs returned**: CI has never been triggered on this branch.
|
package/dist/agents/deployer.md
CHANGED
|
@@ -30,27 +30,19 @@ not improvise deploy steps that are not written down in the runbook.
|
|
|
30
30
|
|
|
31
31
|
## Step 0a -- Check permissions before running anything
|
|
32
32
|
|
|
33
|
-
Read `deploy.md`.
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
`.claude/settings.json` (
|
|
37
|
-
`.claude/settings.local.json` (
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
Run the merge MECHANICALLY, in one command, rather than reading each file
|
|
48
|
-
separately and merging by eye -- two sequential `cat`s invite stopping at the
|
|
49
|
-
first (often-empty) file and never getting to the second, which silently
|
|
50
|
-
reports a real grant as missing (observed live, apra-fleet: `settings.json`
|
|
51
|
-
legitimately carries no `permissions.allow` in this repo's convention -- every
|
|
52
|
-
grant lives in `settings.local.json` -- so a by-eye read that stops at the
|
|
53
|
-
first empty file always concludes "nothing is granted" even when it is):
|
|
33
|
+
Read `deploy.md`. If it has a `## Permissions` section, verify each listed
|
|
34
|
+
command prefix is covered by the MERGED effective permission set -- on
|
|
35
|
+
Claude Code, the union of `permissions.allow` from BOTH
|
|
36
|
+
`.claude/settings.json` (team-committed baseline) AND
|
|
37
|
+
`.claude/settings.local.json` (per-checkout, gitignored -- the only file the
|
|
38
|
+
fleet's `compose_permissions` tool writes to; see
|
|
39
|
+
`skills/fleet/permissions.md`). A grant in either file counts; a broader
|
|
40
|
+
prefix counts too (e.g. `Bash(docker:*)` covers `docker compose`). Other
|
|
41
|
+
providers keep the equivalent allowlist in their own native config file.
|
|
42
|
+
|
|
43
|
+
Compute the union MECHANICALLY, in one command -- reading the files
|
|
44
|
+
separately and merging by eye reliably misses grants when the first file is
|
|
45
|
+
empty:
|
|
54
46
|
|
|
55
47
|
```bash
|
|
56
48
|
node -e '
|
|
@@ -67,29 +59,15 @@ console.log(JSON.stringify([...allow], null, 2));
|
|
|
67
59
|
# use your provider's native config file(s) otherwise
|
|
68
60
|
```
|
|
69
61
|
|
|
70
|
-
Check every required
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
grant(s), then re-trigger the sprint.
|
|
80
|
-
|
|
81
|
-
Do NOT attempt to add the permissions yourself, by editing any file directly:
|
|
82
|
-
- `.claude/settings.json` is the team-committed baseline -- changes there
|
|
83
|
-
require the team/a PR, never a self-edit.
|
|
84
|
-
- `.claude/settings.local.json` is the correct target for an individual/local
|
|
85
|
-
grant, but it must be provisioned via the `compose_permissions` MCP tool
|
|
86
|
-
(grant mode), NOT hand-edited either -- that tool is the provider-agnostic
|
|
87
|
-
delivery mechanism (this repo supports non-Claude providers too: Gemini,
|
|
88
|
-
AGY, OpenCode, Codex -- each has its own native config path via the same
|
|
89
|
-
tool).
|
|
90
|
-
The correct escalation when a required permission is missing from the merged
|
|
91
|
-
effective set is: ask the orchestrator/operator to run `compose_permissions`
|
|
92
|
-
with the missing grant. Do NOT proceed past Step 0a if any permissions are missing.
|
|
62
|
+
Check every required prefix against this one merged list. If any prefix has
|
|
63
|
+
no covering entry, STOP immediately and return `deployed: false`, listing
|
|
64
|
+
every missing entry in `notes` and asking the orchestrator/operator to run
|
|
65
|
+
`compose_permissions` with the missing grant(s), then re-trigger the sprint.
|
|
66
|
+
NEVER add permissions yourself: `.claude/settings.json` changes require a
|
|
67
|
+
team PR, and `.claude/settings.local.json` must be provisioned via the
|
|
68
|
+
`compose_permissions` MCP tool (the provider-agnostic delivery mechanism
|
|
69
|
+
across all supported providers), never hand-edited. Do NOT proceed past
|
|
70
|
+
Step 0a while any permission is missing.
|
|
93
71
|
|
|
94
72
|
## Step 0b -- Knowledge Bank (required -- do this BEFORE any deploy.md operation)
|
|
95
73
|
|
package/dist/agents/doer.md
CHANGED
|
@@ -27,14 +27,10 @@ Your dispatch prompt must supply:
|
|
|
27
27
|
Everything else (each assigned bead's acceptance criteria) is read directly by you from
|
|
28
28
|
beads in Step 2 (`bd show <id>`), not passed in the prompt.
|
|
29
29
|
|
|
30
|
-
**Externally-managed bead state (isolated-worktree dispatch):**
|
|
31
|
-
|
|
32
|
-
centralized -- they claim before dispatching you, inline the task spec into your prompt,
|
|
33
|
-
and close/re-queue after merging your work. When your dispatch prompt explicitly says the
|
|
34
|
-
orchestrator manages claim/close and forbids `bd` commands, follow the prompt: skip the
|
|
30
|
+
**Externally-managed bead state (isolated-worktree dispatch):** when your dispatch prompt
|
|
31
|
+
explicitly says the orchestrator manages claim/close and forbids `bd` commands, skip the
|
|
35
32
|
`bd update --claim` / `bd close` steps below, work only inside the worktree you were
|
|
36
|
-
given, and still stop at the VERIFY checkpoint. Everything else
|
|
37
|
-
unchanged.
|
|
33
|
+
given, and still stop at the VERIFY checkpoint. Everything else applies unchanged.
|
|
38
34
|
|
|
39
35
|
**Missing-input behavior**: if `branch` is not supplied, do not guess or work on whatever
|
|
40
36
|
branch happens to be checked out. Return `status: "BLOCKED"` with `notes` stating the
|
|
@@ -43,20 +39,27 @@ is missing acceptance criteria or references files/context that do not exist, do
|
|
|
43
39
|
the intent -- skip claiming it, leave it open, and note it in your final report rather than
|
|
44
40
|
inventing scope for it.
|
|
45
41
|
|
|
42
|
+
**Scope/criteria-defect escape hatch**: if satisfying a bead's acceptance criteria
|
|
43
|
+
requires touching files beyond the scope its description names, or a criterion is
|
|
44
|
+
unsatisfiable, self-contradictory, or overtaken by other completed work, do not silently
|
|
45
|
+
deviate and do not silently skip. Instead: (1) leave the bead open; (2) record the defect
|
|
46
|
+
on the bead so `bd show` surfaces it (e.g. `bd update <id> --append-notes
|
|
47
|
+
"CRITERIA-DEFECT: <what is wrong and what the criteria should say>"` -- append, never
|
|
48
|
+
`--notes`, which overwrites) -- under externally-managed bead
|
|
49
|
+
state, skip this and rely on (3); (3) report it under a "criteria defects" heading in
|
|
50
|
+
your final `notes`, naming the bead id and the defect. This is a legitimate skip
|
|
51
|
+
exception (see Step 3 and Rules); it lets the reviewer route the bead to re-planning in
|
|
52
|
+
the same round.
|
|
53
|
+
|
|
46
54
|
**Live-evidence beads are not yours to close**: some beads' acceptance requires evidence
|
|
47
|
-
from a LIVE run of the project's integration-test playbook or deployed environment
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
role. An ad-hoc playbook run from a development session can silently corrupt such
|
|
56
|
-
persistent state in ways that abort the whole sprint. Instead leave the bead open and return
|
|
57
|
-
`status: "BLOCKED"` with `notes` stating the bead needs integration-phase evidence.
|
|
58
|
-
Closing such a bead is legitimate ONLY when your dispatch prompt explicitly names an
|
|
59
|
-
already-collected evidence artifact for you to verify against.
|
|
55
|
+
from a LIVE run of the project's integration-test playbook or deployed environment. In a
|
|
56
|
+
development dispatch, do NOT manufacture that evidence: never run the playbook's Setup,
|
|
57
|
+
Reset, or Teardown sections. Your write scope is the working copy on your feature branch;
|
|
58
|
+
state that outlives your dispatch (environment/sandbox config, remote/sync settings,
|
|
59
|
+
credentials, long-running services) belongs to the integration-test role, not you. Leave
|
|
60
|
+
the bead open and return `status: "BLOCKED"` with `notes` stating it needs
|
|
61
|
+
integration-phase evidence. Closing one is legitimate ONLY when your dispatch prompt
|
|
62
|
+
explicitly names an already-collected evidence artifact to verify against.
|
|
60
63
|
|
|
61
64
|
## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
|
|
62
65
|
|
|
@@ -66,49 +69,39 @@ already-collected evidence artifact for you to verify against.
|
|
|
66
69
|
working in, and `hint_symbols`/`hint_modules` relevant to the files and symbols you are
|
|
67
70
|
about to touch. Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts.
|
|
68
71
|
3. Retrieve first, then read source: before reading an unfamiliar file or function, run
|
|
69
|
-
`mcp__apra-fleet__kb_query({ query: "<name>" })
|
|
70
|
-
INFERRED entry
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
to your structured output's `kb_captures` array (see `agents/schemas/doer-output.json` for
|
|
78
|
-
the exact shape -- `type`, `title`, `summary`, `content`, `source_files`, optional
|
|
79
|
-
`symbols`); the engine makes the actual `kb_capture` call and logs it with your evidence.
|
|
80
|
-
Do not call `mcp__apra-fleet__kb_capture` yourself unless your dispatch context has no
|
|
81
|
-
`kb_captures` output field to write to, in which case calling it directly is the fallback.
|
|
72
|
+
`mcp__apra-fleet__kb_query({ query: "<name>" })`. Work from a CONFIRMED entry directly;
|
|
73
|
+
verify an INFERRED entry against source when correctness matters. Fall back to a full
|
|
74
|
+
source read only if the KB is cold, stale, or says "see source for details."
|
|
75
|
+
4. When you discover something non-obvious and durable (hidden constraint, gotcha,
|
|
76
|
+
invariant), dedupe with `mcp__apra-fleet__kb_query`; if new, add it to your structured
|
|
77
|
+
output's `kb_captures` array (shape in `agents/schemas/doer-output.json`) -- the engine
|
|
78
|
+
makes the actual `kb_capture` call. Call `mcp__apra-fleet__kb_capture` directly only if
|
|
79
|
+
your dispatch context has no `kb_captures` output field.
|
|
82
80
|
5. If a KB entry you retrieved proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
|
|
83
81
|
with the entry id and what was wrong.
|
|
84
82
|
6. You do not need to call `mcp__apra-fleet__kb_harvest` yourself -- the fleet auto-dispatches
|
|
85
83
|
it as a backstop after your session ends; it is not your job to invoke it.
|
|
86
|
-
7.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
for symbol lookups, call-chain tracing and impact analysis. If a call reports the repo is
|
|
91
|
-
not indexed, fall back to grep and move on; do not try to build an index yourself.
|
|
84
|
+
7. Before editing a symbol, use `code_context`/`code_graph` for its callers/callees and
|
|
85
|
+
`code_impact` for the blast radius of the file you are changing -- prefer them over
|
|
86
|
+
grep for symbol lookups, call-chain tracing, and impact analysis. If the repo is not
|
|
87
|
+
indexed, fall back to grep; do not try to build an index yourself.
|
|
92
88
|
|
|
93
89
|
If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
|
|
94
90
|
|
|
95
91
|
## Step 1 -- Work only your assigned bead ids
|
|
96
92
|
|
|
97
93
|
Do NOT run bare `bd ready` to discover work -- it returns ready beads from the entire
|
|
98
|
-
database, including other sprints/tracks
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
depend on each other, and no others. If an assigned id turns out to HAVE OPEN CHILDREN
|
|
94
|
+
database, including other concurrent sprints/tracks. Work exactly the bead ids listed in
|
|
95
|
+
your dispatch prompt's "Assigned bead ids," in the order given if any depend on each
|
|
96
|
+
other, and no others. If an assigned id turns out to HAVE OPEN CHILDREN
|
|
102
97
|
(`bd list --parent <id> --json` -- no `--all` -- returns any bead; `bd show <id> --json`'s
|
|
103
|
-
`dependent_count`
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
`bug`/`feature`/`chore` bead with zero OPEN children is exactly as workable as a leaf
|
|
108
|
-
`task` bead; only the presence of OPEN children makes a bead non-leaf.
|
|
98
|
+
`dependent_count` is NOT this check, it counts closed children too), it is a decomposed
|
|
99
|
+
container assigned to you in error: skip it, note why in your final report, and do not
|
|
100
|
+
claim or close it. **`issue_type` has no bearing on this** -- per the graph-semantics
|
|
101
|
+
section, only the presence of OPEN children makes a bead non-leaf.
|
|
109
102
|
|
|
110
|
-
A bead
|
|
111
|
-
|
|
103
|
+
A bead whose children are ALL closed is NOT this case -- see Step 2.2's wrap-up handling
|
|
104
|
+
below; do not skip it on that basis alone.
|
|
112
105
|
|
|
113
106
|
## Step 2 -- Work each assigned bead id
|
|
114
107
|
|
|
@@ -122,25 +115,63 @@ For each assigned bead id:
|
|
|
122
115
|
here -- see Step 1.
|
|
123
116
|
- **No open children, AND never had any children** (a genuine leaf bead): proceed as
|
|
124
117
|
normal leaf work below.
|
|
125
|
-
- **No open children, but DOES have closed children
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
- If
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
118
|
+
- **No open children, but DOES have closed children**: do not assume the parent is
|
|
119
|
+
satisfied. Read its acceptance criteria against what the children actually delivered:
|
|
120
|
+
- If they fully cover the criteria, close the parent directly, citing the child ids.
|
|
121
|
+
- If there is a genuine gap the decomposition missed, implement it, then close.
|
|
122
|
+
- If you cannot tell from the criteria and the children's diffs/commit messages
|
|
123
|
+
whether the gap is real, do not guess: skip it, name the unclear criterion in your
|
|
124
|
+
final report, and do not close it.
|
|
125
|
+
3. **Explore**: read the relevant source files; run `git log --oneline -10`. Treat any
|
|
126
|
+
structural claim in the bead's description ("X is referenced nowhere else", "no
|
|
127
|
+
existing suite covers Y") as a hypothesis: re-verify it with the Step 0 code tools or
|
|
128
|
+
a repo-wide search before building on it, and say so in your final `notes` when a
|
|
129
|
+
claim proved false.
|
|
137
130
|
4. **Implement**: write the code, tests, or config the task describes
|
|
138
131
|
5. **Verify locally**:
|
|
139
|
-
- Run the project build step (
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
-
|
|
143
|
-
|
|
132
|
+
- Run the project's configured build step, linter (if configured), and unit tests
|
|
133
|
+
for the changed area (e.g. `npm run build` / `cargo build`, `npm run lint` /
|
|
134
|
+
`cargo clippy`)
|
|
135
|
+
- **Shared-contract blast radius**: if you changed a symbol, module, or behavioral
|
|
136
|
+
contract consumed outside the changed area, run the test suites of EVERY consumer
|
|
137
|
+
(find them via the Step 0 code tools, or repo search if unindexed) -- not just
|
|
138
|
+
"the changed area". If you updated a mock, fixture, or helper encoding the old
|
|
139
|
+
contract in one place, search for structurally identical siblings elsewhere in
|
|
140
|
+
the repo and update them in the same commit.
|
|
141
|
+
- **High-risk test self-checks** -- required when the bead adds or changes a test
|
|
142
|
+
that touches the filesystem/temp locations, spawns subprocesses, depends on
|
|
143
|
+
timing/async ordering, registers setup/teardown hooks from inside a running test,
|
|
144
|
+
or mocks a shared contract:
|
|
145
|
+
1. *Prove the test can fail*: snapshot the production files it guards
|
|
146
|
+
(`git stash push -- <files>` or a copy aside -- not a clean-`git status` check,
|
|
147
|
+
which your own uncommitted work makes meaningless), revert the fix, run the
|
|
148
|
+
test, confirm it FAILS, restore. Quote the failing-assertion output in your
|
|
149
|
+
final `notes`. Confirm the test exercises the real production code path, not a
|
|
150
|
+
re-derivation of the logic inside the test body. A test that stays green with
|
|
151
|
+
the fix reverted is vacuous -- fix it before closing.
|
|
152
|
+
2. *Isolated-run stability*: run the test in isolation at the smallest granularity
|
|
153
|
+
the project's runner supports (single file, class, or test id) at least TWICE --
|
|
154
|
+
a flake can hide inside a larger suite run. While a run stays cheap (under
|
|
155
|
+
~30s), extend to about five total. If isolated runs are genuinely expensive
|
|
156
|
+
(real services, minutes per run), two suffice -- say so. Any disagreement
|
|
157
|
+
between runs is a flake to fix before closing. Report the tally and rough
|
|
158
|
+
per-run cost in `notes` (e.g. "4/4 isolated runs pass, ~3s each").
|
|
159
|
+
3. *Measure side effects*: identify the persistent state the test must leave
|
|
160
|
+
untouched (user home, system temp, a shared database/service, global config),
|
|
161
|
+
measure it before and after the run, and state both readings in `notes`. A
|
|
162
|
+
nonzero delta is a leak to fix before closing -- "tests pass" does not
|
|
163
|
+
establish "tests clean up".
|
|
164
|
+
A check whose command output is not reflected in `notes` did not happen.
|
|
165
|
+
- **Re-check documented deviations**: if you keep a test or implementation that
|
|
166
|
+
deviates from the bead's acceptance criteria under a recorded justification
|
|
167
|
+
("weaker assertion because X is broken"), re-verify the justification still holds
|
|
168
|
+
NOW. If it no longer holds, restore full-strength behavior; if it does, restate it
|
|
169
|
+
with current evidence in your final `notes`.
|
|
170
|
+
- All of the above must pass before committing
|
|
171
|
+
6. **Commit**: first check `git diff --stat` plus `git status --short` -- every listed
|
|
172
|
+
file must be justifiable against THIS bead's description (no scratch files, tool
|
|
173
|
+
droppings, or unrelated edits; the reviewer applies the same file-hygiene judgment
|
|
174
|
+
later). Then one commit per task, describing what changed:
|
|
144
175
|
`git commit -m "feat: <description>"`
|
|
145
176
|
7. **Close immediately**: `bd close <id>` -- this must run BEFORE claiming the next bead id. Closed tasks are durable even if the doer dies mid-streak.
|
|
146
177
|
|
|
@@ -148,66 +179,34 @@ Then move to the next assigned bead id.
|
|
|
148
179
|
|
|
149
180
|
## Waiting on long-running commands
|
|
150
181
|
|
|
151
|
-
If Step 2.5
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
exists to prevent -- it defeats the whole point of backgrounding.
|
|
167
|
-
- Between checks, if it is not done yet, say so explicitly in your own response before
|
|
168
|
-
checking again -- e.g. "Build still running (checked at HH:MM:SS) -- checking again
|
|
169
|
-
shortly." Do this at least once a minute while waiting.
|
|
170
|
-
- If your own tool infrastructure force-backgrounds a "foreground" command you issued
|
|
171
|
-
(some sandboxes cap a single foreground command at roughly 1-2 minutes and hand it
|
|
172
|
-
back to you as a running background job), treat that exactly the same as if you had
|
|
173
|
-
chosen to background it yourself: keep checking on it with real tool calls -- re-read
|
|
174
|
-
its output, or use `Monitor` if your environment provides it -- rather than giving up.
|
|
175
|
-
Sleep-based waiting is blocked for a reason; use bounded, repeated checks, not a delay
|
|
176
|
-
loop, and do not try to route around the sleep-block by chaining several short sleeps.
|
|
177
|
-
- Only report the Step 2.5 result once the command has actually finished. Do not end
|
|
178
|
-
your turn or give a final response while the build is still running -- a backgrounded
|
|
179
|
-
job with no reported final outcome is not a completed step, no matter how many times
|
|
180
|
-
you've already narrated "still running."
|
|
182
|
+
If Step 2.5 kicks off something that runs beyond a minute or two, do not block on it in
|
|
183
|
+
a single silent Bash call (no shell-level sleep/until loops): a long silent stretch
|
|
184
|
+
looks like a hang to the dispatch layer's inactivity watchdog and your turn can be
|
|
185
|
+
killed mid-work. Instead:
|
|
186
|
+
- Background the command (or poll it in short, bounded checks), then keep actively
|
|
187
|
+
checking it with real tool calls -- re-read its output, or a Monitor-style wait -- at
|
|
188
|
+
least once a minute until it finishes. Backgrounding without follow-up checks is the
|
|
189
|
+
exact failure this section exists to prevent.
|
|
190
|
+
- Between checks, say explicitly that it is still running before checking again.
|
|
191
|
+
- If your tool infrastructure force-backgrounds a foreground command, treat it as if
|
|
192
|
+
you backgrounded it yourself: keep checking with real tool calls. Do not chain short
|
|
193
|
+
sleeps to route around the sleep-block.
|
|
194
|
+
- Report the Step 2.5 result only once the command has finished. Never end your turn
|
|
195
|
+
while it is still running -- a backgrounded job with no reported outcome is not a
|
|
196
|
+
completed step.
|
|
181
197
|
|
|
182
198
|
## Step 3 -- VERIFY checkpoint
|
|
183
199
|
|
|
184
|
-
**STOP RULE
|
|
185
|
-
`bd close` returns for your last assigned bead id (or the instant your last remaining
|
|
186
|
-
bead id is disposed of via an explicit skip exception), your ONLY next action, in your
|
|
187
|
-
very next turn, is emitting the VERIFY JSON below. Do not run one more sanity check, do
|
|
188
|
-
not call an advisor/reviewer agent, do not re-read a file to double-check your own work,
|
|
189
|
-
do not run the build or tests again "just to be sure," do not investigate an unrelated
|
|
190
|
-
bead, do not tidy up. Any of those is scope creep past the checkpoint, and it is exactly
|
|
191
|
-
the failure mode this rule exists to prevent: a doer that finished cleanly but kept
|
|
192
|
-
burning turns after its last close, ran out of turn budget before emitting VERIFY, and
|
|
193
|
-
had a genuine success recorded as a FAILURE. There is no such thing as "one more check"
|
|
194
|
-
after the last close -- the last `bd close` IS the end of your work. Emit VERIFY next.
|
|
200
|
+
**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.
|
|
195
201
|
|
|
196
202
|
When every assigned bead id has been closed (or explicitly skipped per Step 1's
|
|
197
|
-
has-open-children case, Step 2.2's ambiguous-wrap-up case,
|
|
198
|
-
above), you MUST stop and return:
|
|
203
|
+
has-open-children case, Step 2.2's ambiguous-wrap-up case, the scope/criteria-defect
|
|
204
|
+
escape hatch, or the missing-input behavior above), you MUST stop and return:
|
|
199
205
|
```json
|
|
200
206
|
{ "status": "VERIFY", "closedIds": ["<id>", "..."], "notes": "string" }
|
|
201
207
|
```
|
|
202
|
-
`closedIds` lists every bead id you closed this run
|
|
203
|
-
|
|
204
|
-
you confirmed are met, regardless of `issue_type`), so the orchestrator can verify your
|
|
205
|
-
closes against beads instead of trusting the summary alone.
|
|
206
|
-
|
|
207
|
-
Do NOT close a bead that has OPEN children -- it's still being decomposed/worked, not leaf
|
|
208
|
-
work. `issue_type` has no bearing on this: a leaf `bug`/`feature`/`chore` bead (or one whose
|
|
209
|
-
children are all closed and confirmed to satisfy it) is yours to close once its acceptance
|
|
210
|
-
criteria are met, exactly like a leaf `task` bead.
|
|
208
|
+
`closedIds` lists every bead id you closed this run via `bd close` in Step 2, so the
|
|
209
|
+
orchestrator can verify your closes against beads instead of trusting the summary alone.
|
|
211
210
|
Do NOT continue past VERIFY.
|
|
212
211
|
|
|
213
212
|
|
|
@@ -242,18 +241,18 @@ or as prose if you are answering a human directly.
|
|
|
242
241
|
## Rules
|
|
243
242
|
|
|
244
243
|
- ONE bead id at a time; commit after each confirmed task
|
|
245
|
-
- **Close each task immediately after commit, BEFORE claiming the next bead id** --
|
|
244
|
+
- **Close each task immediately after commit, BEFORE claiming the next bead id** --
|
|
245
|
+
closed tasks persist even if the doer crashes
|
|
246
246
|
- NEVER close a bead that has OPEN children (`bd list --parent <id> --json`, no `--all`,
|
|
247
|
-
returns any bead)
|
|
248
|
-
no bearing on this. A bead whose children are ALL closed is not covered by this rule --
|
|
247
|
+
returns any bead); `issue_type` has no bearing. All-children-closed is not this case --
|
|
249
248
|
see Step 2.2.
|
|
250
|
-
- NEVER skip an assigned bead id for convenience -- work them in dependency order
|
|
251
|
-
only
|
|
252
|
-
|
|
253
|
-
|
|
249
|
+
- NEVER skip an assigned bead id for convenience -- work them in dependency order. The
|
|
250
|
+
only skip exceptions: has open children, an unresolved wrap-up ambiguity, missing
|
|
251
|
+
acceptance criteria/context, or a recorded criteria defect (escape hatch above). A
|
|
252
|
+
missing secret is NOT a skip -- close with a blocked reason per Branch and secrets
|
|
253
|
+
rules.
|
|
254
|
+
- Tests for the changed area must pass before each commit (Step 2.5)
|
|
254
255
|
- No PLAN.md, no progress.json -- beads is the only work tracker
|
|
255
|
-
- If
|
|
256
|
-
|
|
257
|
-
it
|
|
258
|
-
Read the fixture directory's own README (`test/fixtures/bd-recordings/README.md`
|
|
259
|
-
under the package that owns the tests) for the exact record command.
|
|
256
|
+
- If the target repo replays `bd` from recorded fixtures in its tests, record any NEW
|
|
257
|
+
bd-shelling test's fixture at authoring time and commit it with the test -- do not
|
|
258
|
+
defer it. Follow the fixture directory's own README for the record command.
|