docs(acfs): add swarm coordination lesson

Author: Dicklesworthstone

.beads/issues.jsonl

@@ -301,7 +301,7 @@
 {"id":"bd-39ye","title":"NO_COLOR environment variable support","description":"## Overview\nRespect the NO_COLOR environment variable across all ACFS scripts per https://no-color.org/ standard.\n\n## Current Problem\n- Scripts use colors unconditionally\n- Users with accessibility needs can't disable colors\n- Piped output includes ANSI codes\n- Some terminals render colors poorly\n\n## NO_COLOR Standard\n- If NO_COLOR env var is set (any value), disable colors\n- Also disable for non-TTY output (pipes, redirects)\n- Simple, widely adopted convention\n\n## Implementation Details\n1. Create color helper functions in logging.sh\n2. Check NO_COLOR and TTY status once at startup\n3. All color output goes through these helpers\n\n## Color Helper Functions\n```bash\n# scripts/lib/colors.sh\n_init_colors() {\n  if [[ -n \"${NO_COLOR:-}\" ]] || [[ ! -t 1 ]]; then\n    RED='' GREEN='' YELLOW='' BLUE='' RESET=''\n  else\n    RED='\\033[0;31m' GREEN='\\033[0;32m'\n    YELLOW='\\033[0;33m' BLUE='\\033[0;34m' RESET='\\033[0m'\n  fi\n}\n\ncolor_print() {\n  local color=\"$1\" msg=\"$2\"\n  printf '%b%s%b\\n' \"${!color}\" \"$msg\" \"$RESET\"\n}\n```\n\n## Files to Audit\n- scripts/lib/logging.sh (main color usage)\n- scripts/lib/tui.sh (interactive elements)\n- scripts/install.sh (progress output)\n- All scripts that use printf with ANSI codes\n\n## Test Plan\n- [ ] Test NO_COLOR=1 disables all colors\n- [ ] Test piped output has no ANSI codes\n- [ ] Test colors work normally when NO_COLOR unset\n- [ ] Grep for raw ANSI codes to ensure none slip through\n\n## Files to Modify\n- scripts/lib/logging.sh (add color helpers)\n- All files using hardcoded ANSI codes","status":"closed","priority":3,"issue_type":"task","created_at":"2026-01-25T23:01:49.345301724Z","created_by":"ubuntu","updated_at":"2026-01-27T04:01:25.739562837Z","closed_at":"2026-01-27T04:01:25.739539473Z","close_reason":"done","source_repo":".","compaction_level":0,"original_size":0,"dependencies":[{"issue_id":"bd-39ye","depends_on_id":"bd-3y1n","type":"blocks","created_at":"2026-01-25T23:04:01.194662910Z","created_by":"ubuntu","metadata":"{}","thread_id":""}]}
 {"id":"bd-3a81","title":"Add nightly strict installer canary + alert on checksum mismatch","status":"closed","priority":1,"issue_type":"task","owner":"jeff141421@gmail.com","created_at":"2026-01-15T15:21:29.878094357Z","created_by":"Dicklesworthstone","updated_at":"2026-01-15T15:38:29.528321876Z","closed_at":"2026-01-15T15:38:29.528321876Z","close_reason":"Added strict nightly canary workflow with checksum-mismatch alerting + log artifact","source_repo":".","compaction_level":0,"original_size":0}
 {"id":"bd-3aa6","title":"Prevent gcloud 'bv' from ever shadowing beads_viewer","description":"Summary\n- gcloud SDK installs a `bv` binary in `/home/ubuntu/google-cloud-sdk/bin`.\n- The SDK’s `path.zsh.inc` is sourced in `~/.zshrc.local`, so PATH can include gcloud’s `bv`.\n- User requirement: **gcloud’s `bv` must never, under any circumstances, intercept/be invoked instead of beads_viewer `bv`.**\n\nImpact\n- High risk of running the wrong `bv` in interactive shells, non-interactive shells, CI, or cron jobs.\n- Mis-executed `bv` can break bead workflows and cause confusion during incident response.\n\nEvidence (current environment)\n- `which -a bv` shows multiple `bv` binaries including gcloud’s:\n  - `/home/ubuntu/google-cloud-sdk/bin/bv`\n  - `/home/ubuntu/.local/bin/bv`\n  - `/home/ubuntu/.bun/bin/bv`\n  - `/home/ubuntu/go/bin/bv`\n- PATH is mutated by gcloud SDK via `path.zsh.inc` (sourced in `~/.zshrc.local`).\n\nRoot Cause\n- gcloud SDK ships a `bv` command (BigQuery-related) that collides with beads_viewer’s `bv`.\n- PATH ordering is not explicitly pinned to prefer user `bv` binaries.\n\nProposed Remediation (must enforce precedence)\n1) Prepend user bins ahead of gcloud in shell init:\n   - `~/bin`, `~/.local/bin`, `~/.bun/bin`, `~/go/bin` must come before the SDK.\n2) Add an explicit `bv` shim at `~/bin/bv` that delegates to the preferred beads_viewer binary.\n3) Add a hard alias in shell init to force `bv` -> `~/.local/bin/bv` (or preferred).\n4) Add a health check command (or script) that fails if `command -v bv` resolves to gcloud.\n\nAcceptance Criteria\n- `command -v bv` resolves to user beads_viewer (not gcloud) in:\n  - interactive shells\n  - non-interactive shells (`zsh -lc`, cron)\n- `which -a bv` shows gcloud’s `bv` only after user paths.\n- Running `bv --version` matches beads_viewer’s version, not gcloud’s.\n\nNotes\n- The collision warning appears after `gcloud components update`.\n- This is a safety/operations issue, not a GA4 issue.","status":"closed","priority":1,"issue_type":"bug","created_at":"2026-01-25T00:42:06.371685930Z","created_by":"ubuntu","updated_at":"2026-01-26T23:22:24.883957326Z","closed_at":"2026-01-26T23:22:24.883935966Z","close_reason":"Implemented bv() protection function in acfs.zshrc that bypasses gcloud bv, added ~/bin to PATH, and enhanced doctor.sh to detect gcloud shadowing. Shellcheck passes.","source_repo":".","compaction_level":0,"original_size":0}
-{"id":"bd-3b1l8","title":"Write hands-on swarm coordination lesson and landing-plane workflow","description":"## Parent program\n`bd-nlb8w`; depends on coordinate doctor `bd-p3nxh` so the lesson can teach the actual command surface.\n\n## What\nAdd an onboarding/Learning Hub lesson that walks users through a realistic multi-agent loop: run coordination preflight, check Beads with robot commands, register Agent Mail identity, reserve files, send a start message, use RCH for builds, run UBS before commit, close/sync Beads, release reservations, and post a final handoff.\n\n## Why\nACFS installs powerful coordination tools, but users still need a muscle-memory workflow. Teaching the end-to-end loop reduces collisions and makes the flywheel feel intentional.\n\n## How\nReuse existing Learning Hub/onboard patterns. Include copyable commands, expected outputs, common mistakes, and a no-network/local simulation path. Keep the language beginner-friendly while preserving the exact agent rules from AGENTS.md.\n\n## Risks\nDo not teach bare `bv`, stale `bd` commands, or local CPU-heavy cargo builds. Do not imply force-release or destructive cleanup is normal.\n\n## Success criteria\n- Lesson includes a complete start-to-finish coordination scenario.\n- Commands use `br`, `bv --robot-*`, Agent Mail, `rch exec --`, and UBS correctly.\n- Unit/E2E or content tests verify no stale command forms or destructive cleanup guidance.","status":"open","priority":3,"issue_type":"task","created_at":"2026-05-08T04:33:46.043179599Z","created_by":"ubuntu","updated_at":"2026-05-08T04:41:29.985118209Z","source_repo":".","compaction_level":0,"original_size":0,"labels":["docs","idea-wizard","onboarding","swarm"],"dependencies":[{"issue_id":"bd-3b1l8","depends_on_id":"bd-oky34","type":"blocks","created_at":"2026-05-08T04:37:14.117747421Z","created_by":"ubuntu","metadata":"{}","thread_id":""},{"issue_id":"bd-3b1l8","depends_on_id":"bd-p3nxh","type":"blocks","created_at":"2026-05-08T04:37:05.995848437Z","created_by":"ubuntu","metadata":"{}","thread_id":""},{"issue_id":"bd-3b1l8","depends_on_id":"bd-r86ef","type":"blocks","created_at":"2026-05-08T04:41:29.984635054Z","created_by":"ubuntu","metadata":"{}","thread_id":""}]}
+{"id":"bd-3b1l8","title":"Write hands-on swarm coordination lesson and landing-plane workflow","description":"## Parent program\n`bd-nlb8w`; depends on coordinate doctor `bd-p3nxh` so the lesson can teach the actual command surface.\n\n## What\nAdd an onboarding/Learning Hub lesson that walks users through a realistic multi-agent loop: run coordination preflight, check Beads with robot commands, register Agent Mail identity, reserve files, send a start message, use RCH for builds, run UBS before commit, close/sync Beads, release reservations, and post a final handoff.\n\n## Why\nACFS installs powerful coordination tools, but users still need a muscle-memory workflow. Teaching the end-to-end loop reduces collisions and makes the flywheel feel intentional.\n\n## How\nReuse existing Learning Hub/onboard patterns. Include copyable commands, expected outputs, common mistakes, and a no-network/local simulation path. Keep the language beginner-friendly while preserving the exact agent rules from AGENTS.md.\n\n## Risks\nDo not teach bare `bv`, stale `bd` commands, or local CPU-heavy cargo builds. Do not imply force-release or destructive cleanup is normal.\n\n## Success criteria\n- Lesson includes a complete start-to-finish coordination scenario.\n- Commands use `br`, `bv --robot-*`, Agent Mail, `rch exec --`, and UBS correctly.\n- Unit/E2E or content tests verify no stale command forms or destructive cleanup guidance.","status":"closed","priority":3,"issue_type":"task","created_at":"2026-05-08T04:33:46.043179599Z","created_by":"ubuntu","updated_at":"2026-05-08T09:33:37.923284688Z","closed_at":"2026-05-08T09:33:37.923012007Z","close_reason":"Added hands-on swarm coordination lesson and command-policy lint","source_repo":".","compaction_level":0,"original_size":0,"labels":["docs","idea-wizard","onboarding","swarm"],"dependencies":[{"issue_id":"bd-3b1l8","depends_on_id":"bd-oky34","type":"blocks","created_at":"2026-05-08T04:37:14.117747421Z","created_by":"ubuntu","metadata":"{}","thread_id":""},{"issue_id":"bd-3b1l8","depends_on_id":"bd-p3nxh","type":"blocks","created_at":"2026-05-08T04:37:05.995848437Z","created_by":"ubuntu","metadata":"{}","thread_id":""},{"issue_id":"bd-3b1l8","depends_on_id":"bd-r86ef","type":"blocks","created_at":"2026-05-08T04:41:29.984635054Z","created_by":"ubuntu","metadata":"{}","thread_id":""}]}
 {"id":"bd-3bll","title":"Fix Ubuntu upgrade pre-reboot resume stage + target version handling","description":"Bug: pre-upgrade reboot flow stored .ubuntu_upgrade.stage (wrong key) without enabled/target info, so upgrade_resume.sh could not detect the reboot marker and could crash when state lacked upgrade_path. Also upgrade_resume.sh and ubuntu_upgrade.sh hardcoded target 25.10, ignoring --target-ubuntu.\\n\\nFix: write .ubuntu_upgrade.current_stage=pre_upgrade_reboot + enabled/target_version in install.sh; have upgrade_resume.sh read target_version from state and short-circuit on pre_upgrade_reboot to launch continue_install.sh; make ubuntu_upgrade.sh default target overridable.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-25T06:56:10.854463Z","updated_at":"2025-12-25T06:57:38.519714Z","closed_at":"2025-12-25T06:57:38.519714Z","close_reason":"Fixed pre-upgrade reboot marker + target version propagation across install.sh, ubuntu_upgrade.sh, and upgrade_resume.sh; added safe short-circuit in resume script.","source_repo":".","compaction_level":0,"original_size":0}
 {"id":"bd-3bx4v","title":"Fix onboarding CLI aliases and info zero-lessons edge case","status":"closed","priority":2,"issue_type":"bug","created_at":"2026-03-12T20:16:29.520886601Z","created_by":"ubuntu","updated_at":"2026-03-13T00:43:59Z","closed_at":"2026-03-13T00:43:59Z","close_reason":"Fixed onboard noun-style aliases (help/list/version) and made acfs info render a no-lessons state without misleading onboarding prompts; added regression coverage.","source_repo":".","compaction_level":0,"original_size":0}
 {"id":"bd-3ci","title":"Fix acfs doctor --json output (pure JSON + correct counts)","description":"scripts/lib/doctor.sh --json currently prints section headings before JSON, doesn’t increment pass/warn/fail counters in JSON mode, and doesn’t escape strings. Make --json emit only valid JSON on stdout with correct summary counts (and handle missing /etc/os-release).","status":"closed","priority":1,"issue_type":"bug","assignee":"FuchsiaCreek","created_at":"2025-12-20T18:44:19.646755Z","updated_at":"2025-12-20T18:49:30.854595Z","closed_at":"2025-12-20T18:49:30.854595Z","close_reason":"Fixed scripts/lib/doctor.sh --json to emit pure valid JSON (no headings), increment counters in JSON mode, and JSON-escape strings; also handles missing /etc/os-release.","source_repo":".","compaction_level":0,"original_size":0}

acfs/onboard/lessons/21_git_strategy.md

@@ -148,10 +148,10 @@ When you create a project with `acfs newproj`, this is set up automatically.
 
 ## Next
 
-Learn about SRPS (Structured Repository Problem Solving):
+Learn the hands-on coordination loop for a real multi-agent task:
 
 ```bash
-onboard 23
+onboard 22
 ```
 
 ---

acfs/onboard/lessons/22_swarm_coordination.md

@@ -0,0 +1,228 @@
+# Swarm Coordination: From Claim to Handoff
+
+**Goal:** Run one realistic multi-agent task loop without stale commands, local build storms, or file conflicts.
+
+---
+
+## The Shape of a Safe Swarm Session
+
+A good swarm session is boring in the best way:
+
+1. Pick ready work from Beads.
+2. Register with Agent Mail.
+3. Reserve the exact files you will edit.
+4. Announce the start in the Beads thread.
+5. Work in a narrow slice.
+6. Run quality gates with the right offload wrapper.
+7. Scan changed files with UBS.
+8. Close and sync the Bead.
+9. Release reservations and hand off the result.
+
+The commands below use `br` for issue state and `bv --robot-*` for graph-aware recommendations. Agents should not launch the interactive Beads viewer during automated work.
+
+---
+
+## 1. Pick the Next Ready Task
+
+Start from robot output so an agent can parse it deterministically:
+
+```bash
+bv --robot-next
+bv --robot-triage
+br ready --json
+```
+
+Pick one unblocked Bead, then inspect it:
+
+```bash
+br show bd-1234 --json
+br update bd-1234 --status in_progress
+```
+
+Use the Bead ID everywhere else in the session: Agent Mail thread ID, reservation reason, commit message, and closeout note.
+
+---
+
+## 2. Register With Agent Mail
+
+Agent Mail is exposed to agents as MCP tools. Register a unique identity in the project before reserving files or sending messages:
+
+```text
+ensure_project(human_key="/data/projects/my-app")
+
+register_agent(
+  project_key="/data/projects/my-app",
+  program="codex-cli",
+  model="gpt-5",
+  task_description="bd-1234 checkout validation"
+)
+```
+
+Agent names are generated adjective+noun identifiers such as `BlueLake` or `GreenCastle`. Use the actual registered name in every later Agent Mail call.
+
+---
+
+## 3. Reserve the Edit Surface
+
+Reserve only the files or tight globs you expect to touch:
+
+```text
+file_reservation_paths(
+  project_key="/data/projects/my-app",
+  agent_name="BlueLake",
+  paths=[
+    "src/checkout/session.ts",
+    "tests/checkout/session.test.ts"
+  ],
+  ttl_seconds=3600,
+  exclusive=true,
+  reason="bd-1234: checkout validation"
+)
+```
+
+If the reservation conflicts, choose a different ready Bead or narrow the path set. Do not edit files held by another active agent.
+
+---
+
+## 4. Announce the Start
+
+Use the Bead ID as the Agent Mail thread ID:
+
+```text
+send_message(
+  project_key="/data/projects/my-app",
+  sender_name="BlueLake",
+  to=["GreenCastle"],
+  thread_id="bd-1234",
+  subject="[bd-1234] Start: checkout validation",
+  body_md="Claimed bd-1234. Reserved src/checkout/session.ts and tests/checkout/session.test.ts. Plan: add server-side validation and focused tests."
+)
+```
+
+For solo work, a self-addressed start note is still useful because it leaves an auditable trail.
+
+---
+
+## 5. Work in One Narrow Slice
+
+Keep the slice small enough that another agent can understand it from the Bead, the reservation, and the final diff.
+
+Good swarm slices:
+
+- One failing test plus the production fix.
+- One docs page plus its static lint.
+- One installer phase hardening change plus a fixture.
+
+Risky swarm slices:
+
+- Broad refactors across unrelated modules.
+- Generated files edited by hand.
+- Cleanups mixed into feature work.
+
+---
+
+## 6. Run Quality Gates Without Local Build Storms
+
+For Rust-heavy checks, use RCH so swarms do not overload the local machine:
+
+```bash
+rch exec -- cargo test
+rch exec -- cargo clippy
+```
+
+For Bash and web work, use the repo's local gates:
+
+```bash
+shellcheck install.sh scripts/**/*.sh
+
+cd apps/web
+bun run type-check
+bun run lint
+bun run build
+```
+
+Run the smallest useful gate first, then widen when the change touches shared behavior.
+
+---
+
+## 7. Scan Changed Files With UBS
+
+UBS is the last bug-focused check before commit:
+
+```bash
+ubs src/checkout/session.ts tests/checkout/session.test.ts
+```
+
+If UBS reports a real issue, fix the cause and rerun it on the changed files.
+
+---
+
+## 8. Close and Sync the Bead
+
+Close the Bead only after the change is implemented and verified:
+
+```bash
+br close bd-1234 --reason "Implemented checkout validation and focused tests"
+br sync --flush-only
+```
+
+`br sync --flush-only` only exports Beads data. You still stage and commit the `.beads/` changes yourself.
+
+---
+
+## 9. Commit, Push, Release, and Handoff
+
+Keep the commit focused and include the Bead ID:
+
+```bash
+git status
+git add src/checkout/session.ts tests/checkout/session.test.ts .beads/
+git commit -m "fix(checkout): validate checkout sessions"
+git push origin main
+```
+
+Then release reservations and post the final note:
+
+```text
+release_file_reservations(
+  project_key="/data/projects/my-app",
+  agent_name="BlueLake"
+)
+
+send_message(
+  project_key="/data/projects/my-app",
+  sender_name="BlueLake",
+  to=["GreenCastle"],
+  thread_id="bd-1234",
+  subject="[bd-1234] Completed: checkout validation",
+  body_md="Landed commit abc123. Gates: type-check, lint, build, UBS. Reservations released."
+)
+```
+
+Your final handoff should say what changed, which gates ran, what was not run, and whether any follow-up Beads remain.
+
+---
+
+## Quick Reference
+
+| Step | Command or Tool |
+|------|-----------------|
+| Find work | `bv --robot-next`, `bv --robot-triage`, `br ready --json` |
+| Claim | `br update bd-1234 --status in_progress` |
+| Reserve | `file_reservation_paths(...)` |
+| Announce | `send_message(..., thread_id="bd-1234")` |
+| Rust gates | `rch exec -- cargo test` |
+| Scan | `ubs <changed-files>` |
+| Close | `br close bd-1234 --reason "..."` |
+| Sync | `br sync --flush-only` |
+| Release | `release_file_reservations(...)` |
+
+---
+
+## Next
+
+Learn how ACFS keeps the machine responsive under heavy agent load:
+
+```bash
+onboard 23
+```