@zigrivers/scaffold 3.27.0 → 3.28.0

package/content/knowledge/core/ai-memory-management.md

@@ -22,6 +22,23 @@ AI memory operates in layers, each with different persistence and token cost:
 | **MCP memory server** | Cross-session (structured) | Low (queried on demand) | Decisions, lessons, error patterns |
 | **External docs** | Always current | Zero until queried | Library APIs, framework docs |
 
+### When to use which: user-level vs project-level memory
+
+Two persistent memory mechanisms can coexist on one machine. They serve different scopes — pick the right one for each fact:
+
+| Scope | Mechanism | Lives in | Survives across | Shared with team? |
+|-------|-----------|----------|-----------------|-------------------|
+| **User-level** (per-user, cross-project) | Filesystem auto-memory (Claude Code client) | `~/.claude/projects/<encoded-cwd>/memory/*.md` | Sessions, projects | No — local to your machine |
+| **Project-level** (per-project, team-shareable) | `bd remember` (Beads) | `.beads/embeddeddolt/` | Sessions, repo clones | Yes — committed and synced via Dolt |
+
+Rule of thumb:
+- Facts about the **person** (role, expertise level, communication style, preferences) → filesystem auto-memory.
+- Facts about the **project** (in-flight context, team conventions, project-specific blockers, decisions) → `bd remember`.
+
+When `.beads/` exists in a project, prefer `bd remember` for project facts so teammates inherit the context. When working in a project without Beads, the filesystem layer is your only persistent memory.
+
+> Upstream Beads's AGENTS.md says "do not create MEMORY.md files" — that prescription is about project memory specifically. Filesystem auto-memory continues to be the right layer for *user* memory (facts about you, not the project).
+
 ### Core Principle: Signal Over Volume
 
 ETH Zurich research (2026) found that dumping context into AI sessions hurts more than it helps — 3% performance decrease with 20% cost increase for LLM-generated context files. The key insight: **only store what cannot be derived from the code itself.** Custom build commands, project-specific conventions, decision rationale, and team agreements are high-signal. Code patterns, file structure, and API shapes are low-signal (the agent can read the code).

package/content/knowledge/core/claude-md-patterns.md

@@ -41,7 +41,7 @@ Rules must be specific, actionable, and testable:
 **Good rules:**
 - "Run `make check` before every commit"
 - "Never push directly to main — always use branch + PR"
-- "Every commit message starts with `[BD-xxx]` task ID"
+- "Every commit message starts with `[bd-<id>]` task ID"
 
 **Bad rules:**
 - "Write clean code" — what does clean mean?
@@ -243,7 +243,7 @@ When updating a section, prefer additive changes over destructive ones:
 
 **Stale commands.** Key Commands table references `npm test` but the project switched to `bun test` two months ago. The agent runs the wrong command and wastes a cycle. Fix: keep Key Commands in sync with actual build tool configuration. The `claude-md-optimization` step verifies this.
 
-**Conflicting rules.** CLAUDE.md says "always use conventional commits" in one section and "use `[BD-xxx]` prefix" in another, with no guidance on which takes precedence. Fix: consolidate commit message rules in one place. If both apply, show the combined format: `[BD-42] feat(api): implement endpoint`.
+**Conflicting rules.** CLAUDE.md says "always use conventional commits" in one section and "use `[bd-<id>]` prefix" in another, with no guidance on which takes precedence. Fix: consolidate commit message rules in one place. If both apply, show the combined format: `[bd-a3f8] feat(api): implement endpoint`.
 
 **Redundant instructions.** The same rule appears in Core Principles, Workflow, and Rules sections with slightly different wording. The agent may follow one version and violate another. Fix: state each rule once in its canonical section. Other sections reference it.
 

package/content/knowledge/core/coding-conventions.md

@@ -39,7 +39,7 @@ If a convention cannot be checked by a tool, it will not be followed consistentl
 
 ### Comment Philosophy at a Glance
 
-Comments explain **why**, not **what**. If you need a comment to explain what code does, the code is too complex — refactor first. Extract well-named functions, use descriptive variables, replace magic numbers with constants. TODOs must include a task ID: `// TODO [BD-123]: Reason`. Bare TODOs are not allowed.
+Comments explain **why**, not **what**. If you need a comment to explain what code does, the code is too complex — refactor first. Extract well-named functions, use descriptive variables, replace magic numbers with constants. TODOs must include a task ID: `// TODO [bd-<id>]: Reason`. Bare TODOs are not allowed.
 
 ## Deep Guidance
 
@@ -106,7 +106,7 @@ Comments explain **why**, not **what**. If you need a comment to explain what co
 
 **Documentation comments**: Public APIs always need documentation comments. TypeScript uses JSDoc `/** */`. Python uses docstrings. Go uses comments above exported identifiers starting with the identifier name.
 
-**TODO format**: `// TODO [BD-123]: Reason for the TODO`. Also `FIXME [BD-456]` and `HACK [BD-789]`. Bare TODOs without task IDs accumulate without accountability and are not allowed.
+**TODO format**: `// TODO [bd-<id>]: Reason for the TODO`. Also `FIXME [bd-<id2>]` and `HACK [bd-<id3>]`. Bare TODOs without task IDs accumulate without accountability and are not allowed.
 
 ### Error Handling Patterns by Language
 

package/content/knowledge/core/task-decomposition.md

@@ -12,7 +12,7 @@ Expert knowledge for breaking user stories into implementable tasks with depende
 
 ### Story-to-Task Mapping
 
-User stories bridge PRD features and implementation tasks. Each story decomposes into tasks following the technical layers needed. Every task must trace back to a user story, and every story to a PRD feature (PRD Feature → US-xxx → Task BD-xxx).
+User stories bridge PRD features and implementation tasks. Each story decomposes into tasks following the technical layers needed. Every task must trace back to a user story, and every story to a PRD feature (PRD Feature → US-xxx → Task bd-<id>).
 
 ### Task Sizing
 
@@ -146,9 +146,9 @@ Every task must trace back to a user story, and every user story must trace to a
 ```
 PRD Feature: User Profile Management
   -> US-002: Edit display name and bio
-    -> Task BD-42: implement PATCH /api/v1/users/:id
-    -> Task BD-43: add profile edit form component
-    -> Task BD-44: add profile edit page with state management
+    -> Task bd-a3f8: implement PATCH /api/v1/users/:id
+    -> Task bd-a3f9: add profile edit form component
+    -> Task bd-a3fa: add profile edit page with state management
 ```
 
 This traceability ensures:

package/content/knowledge/core/task-tracking.md

@@ -18,7 +18,9 @@ Core properties:
 - **Repository-local** — Task data lives in `.beads/`, committed alongside code
 - **Git-hook synced** — Task state updates automatically on commit via data-sync hooks
 - **CLI-driven** — All operations via `bd` commands (create, list, status, ready)
-- **ID-prefixed commits** — Every commit message includes `[BD-xxx]` for traceability
+- **ID-prefixed commits** — Every commit message includes `[bd-<id>]` for traceability
+
+> IDs are hash-based and lowercase (e.g., `bd-a3f8`). The `bd-` prefix is configurable at `bd init` time. Hierarchical IDs for epic children: `bd-a3f8.1`, `bd-a3f8.1.1`. Older example IDs in this doc using `BD-42`-style uppercase digits reflect a pre-v1.0.0 convention; current upstream emits hash-based lowercase IDs.
 
 ### Task Hierarchy
 
@@ -34,18 +36,24 @@ Epics group related tasks. Tasks are the unit of work assignment — one task pe
 
 ### Progress Tracking
 
-Track task status through a simple state machine:
+Beads tracks task status through this state machine (upstream v1.0.4 enum):
 
+```text
+open → in_progress → closed       (happy path)
+            ↓
+        blocked | deferred         (off-path)
 ```
-ready → in-progress → review → done
-                  ↘ blocked
-```
 
-- **ready** — All dependencies met, can start immediately
-- **in-progress** — Agent is actively working on it
-- **review** — Implementation complete, awaiting PR merge
-- **done** — PR merged, tests passing on main
-- **blocked** — Cannot proceed, dependency or question unresolved
+- **open** — Not started.
+- **in_progress** — Atomically claimed via `bd update <id> --claim` or `bd ready --claim`.
+- **blocked** — Dependency unresolved (set automatically when a `blocks:` dep exists on an open issue).
+- **deferred** — Hidden from `bd ready` until `--defer` date passes.
+- **closed** — Completed (via `bd close <id>`). Reopen with `bd reopen <id>`.
+- **pinned** / **hooked** — Special states; rarely set manually.
+
+Beads also exposes a *status category* dimension (`active | wip | done | frozen`) for higher-level grouping. Use `bd state <id>` to query, `bd statuses` to list valid statuses.
+
+> Scaffold previously documented `ready → in-progress → review → done` — none of those (except via `ready` as a *query*) are upstream statuses. The `review` state, if needed, can be added per-project via `bd config set types.custom_statuses '[{"name":"review","category":"wip"}]'`.
 
 ### Lessons-Learned Workflow
 
@@ -70,7 +78,7 @@ bd init              # Creates .beads/ directory with data store and git hooks
 Initialization creates:
 - `.beads/` — Data directory (committed to git)
 - Git hooks for automatic data sync (these are Beads data hooks, not code-quality hooks like pre-commit linters)
-- Initial `[BD-0]` bootstrap convention
+- Initial `[bd-<id>]` bootstrap convention (lowercase hash-style)
 
 #### Core Commands
 
@@ -78,25 +86,26 @@ Initialization creates:
 |---------|---------|-------------|
 | `bd create "title"` | Create a new task | Starting new work |
 | `bd list` | Show all tasks | Session start, planning |
-| `bd status BD-xxx` | Check task state | Before picking up work |
-| `bd start BD-xxx` | Mark task in-progress | Beginning work on a task |
-| `bd done BD-xxx` | Mark task complete | After PR merged |
+| `bd show <id>` | Inspect full task (alias `bd view`) | Before picking up work |
+| `bd update <id> --claim` | Atomically claim (assigns to you + sets `in_progress`) | Beginning work on a task |
+| `bd ready --claim --json` | Find and claim first ready task in one call | Picking next task with no preference |
+| `bd close <id>` (alias `bd done`) | Mark task complete | After PR merged |
 | `bd ready` | List tasks ready to start | Picking next task |
-| `bd block BD-xxx "reason"` | Mark task blocked | When dependency is unmet |
+| `bd update <id> --status blocked` | Mark task blocked | When dependency is unmet |
 
 #### Commit Message Convention
 
 Every commit references its Beads task:
 
 ```
-[BD-42] feat(api): implement user registration endpoint
+[bd-a3f8] feat(api): implement user registration endpoint
 
 - Add POST /api/v1/auth/register
 - Add input validation with zod schema
 - Add integration tests for happy path and validation errors
 ```
 
-The `[BD-xxx]` prefix enables:
+The `[bd-<id>]` prefix enables:
 - Automatic task-to-commit traceability
 - Progress tracking based on commit activity
 - Session reconstruction (which commits belong to which task)
@@ -108,13 +117,13 @@ The `[BD-xxx]` prefix enables:
 1. Review `tasks/lessons.md` for recent patterns and corrections
 2. Run `bd ready` to see available tasks
 3. Pick the highest-priority ready task (or continue an in-progress task)
-4. Run `bd start BD-xxx` to claim the task
+4. Run `bd update <id> --claim` to atomically claim the task (or skip step 2-3 and just `bd ready --claim --json`)
 5. Read the task description and acceptance criteria before writing code
 
 #### Session End Protocol
 
-1. Commit all work with `[BD-xxx]` prefix
-2. If task is complete: create PR, run `bd done BD-xxx`
+1. Commit all work with `[bd-<id>]` prefix (lowercase hash-style)
+2. If task is complete: create PR, run `bd close <id>` (alias: `bd done`)
 3. If task is incomplete: leave clear notes about current state and next steps
 4. If lessons were learned: update `tasks/lessons.md`
 
@@ -124,7 +133,7 @@ A task is done when:
 - All acceptance criteria from the task description are met
 - Tests pass (`make check` or equivalent)
 - Code follows project coding standards
-- Changes are committed with proper `[BD-xxx]` message
+- Changes are committed with proper `[bd-<id>]` message
 - PR is created (or merged, depending on workflow)
 
 Do not mark a task done based on "it seems to work." Prove it works — tests pass, logs clean, behavior verified.
@@ -184,14 +193,14 @@ For complex projects, maintain a progress summary:
 # Progress
 
 ## Current Sprint
-- [x] BD-10: Database schema migration (done)
-- [x] BD-11: Auth middleware (done)
-- [ ] BD-12: User registration endpoint (in-progress)
-- [ ] BD-13: Login endpoint (ready)
-- [ ] BD-14: Profile management (blocked — needs BD-12)
+- [x] bd-a1b2: Database schema migration (done)
+- [x] bd-a1b3: Auth middleware (done)
+- [ ] bd-a3f8: User registration endpoint (in_progress)
+- [ ] bd-a3f9: Login endpoint (open, ready to pick up)
+- [ ] bd-a3fa: Profile management (blocked — needs bd-a3f8)
 
 ## Blocked
-- BD-14: Waiting on BD-12 (user model finalization)
+- bd-a3fa: Waiting on bd-a3f8 (user model finalization)
 ```
 
 #### Completion Criteria Checklists
@@ -199,7 +208,7 @@ For complex projects, maintain a progress summary:
 Each task should define explicit completion criteria, not vague goals:
 
 ```markdown
-## BD-12: User registration endpoint
+## bd-a3f8: User registration endpoint
 
 ### Done when:
 - [ ] POST /api/v1/auth/register endpoint exists
@@ -218,8 +227,90 @@ Each task should define explicit completion criteria, not vague goals:
 
 **Missing lessons.** The user corrects the same mistake three sessions in a row because nobody captured it in `tasks/lessons.md`. Fix: treat lesson capture as mandatory, not optional. After every correction, update the file before continuing with other work.
 
-**Task ID drift.** Commits stop including `[BD-xxx]` prefixes partway through the project. Traceability breaks down. Fix: make task ID inclusion a habit enforced by review. If using a pre-commit hook, validate the prefix.
+**Task ID drift.** Commits stop including `[bd-<id>]` prefixes partway through the project. Traceability breaks down. Fix: make task ID inclusion a habit enforced by review. If using a pre-commit hook, validate the prefix.
 
 **Overloaded tasks.** A single task covers "implement the API, write the UI, add tests, update docs." This overflows a single session and makes progress tracking meaningless. Fix: split into tasks that each fit in one agent session (30-90 minutes).
 
 **Lessons without rules.** A lesson says "we had trouble with X" but doesn't state a preventive rule. Future sessions read the lesson but don't know what to do differently. Fix: every lesson must include a concrete rule — "Always do Y" or "Never do Z" — not just a description of what went wrong.
+
+### Agent context: `bd prime` is the SSOT
+
+Beads ships `bd prime` as the single source of truth for workflow context injected into agent sessions. The default output is ~1-2k tokens and includes:
+- Current ready/in-progress task counts
+- The next 1-2 ready tasks with full descriptions
+- Recent activity (last few closed/updated)
+- Persistent memories set via `bd remember`
+
+Variants:
+- `bd prime` — full default
+- `bd prime --memories-only` — just persistent memories (very small)
+- `bd prime --full` — extended context (use sparingly; ~5k tokens)
+- `bd prime --hook-json` — Claude Code SessionStart hook envelope
+
+Override the default output by writing `.beads/PRIME.md` (Markdown, free-form). The `bd setup claude` / `bd setup gemini` recipes wire `bd prime --hook-json` into SessionStart hooks for you — you don't typically invoke it by hand.
+
+`bd onboard` emits a one-line snippet you can paste into any agent context file to remind it about `bd prime`.
+
+### Two memory scopes — when to use which
+
+Scaffold-generated projects have two persistent memory layers when `.beads/` exists:
+
+- **Filesystem auto-memory** (per-user, cross-project) — facts about you the developer. Stored under `~/.claude/projects/.../memory/` by the Claude Code client.
+- **`bd remember`** (per-project, team-shareable) — facts about this project. Stored in `.beads/embeddeddolt/`, committed with the repo.
+
+For project-level facts that should travel with the repo (in-flight context, team conventions, project-specific blockers, decisions), use `bd remember` instead of filesystem memory. See `content/knowledge/core/ai-memory-management.md` for the full scope split table.
+
+### Editor integration via `bd setup` recipes
+
+Beads ships built-in setup recipes that write the integration block into CLAUDE.md, AGENTS.md, GEMINI.md, or `.cursor/rules/` for you, using marker-managed format that survives re-runs:
+
+- `bd setup claude` — Claude Code (writes CLAUDE.md block + SessionStart/PreCompact hooks)
+- `bd setup codex` — Codex CLI (writes `.agents/skills/beads/SKILL.md` + AGENTS.md section)
+- `bd setup gemini` — Gemini CLI (writes GEMINI.md section + hooks)
+- `bd setup cursor` / `bd setup windsurf` / `bd setup aider` / `bd setup factory` / `bd setup mux` — other editors
+
+Each recipe is idempotent (re-running it does not duplicate content), reversible (`--remove`), and verifiable (`--check`). Recipe choice determines profile (claude/gemini default to `minimal` ~60% smaller; codex/factory/mux default to `full`). There is no runtime `--profile` flag in v1.0.4 — recipe choice is the knob.
+
+Custom recipes can be added via `bd setup --add <name> <path>`, persisted in `.beads/recipes.toml`.
+
+### Optional: enable custom issue types
+
+`bd create -t` supports `bug`, `feature`, `task`, `epic`, `chore`, `decision` out of the box. To use `story`, `milestone`, or `spike`, enable them via project config:
+
+```bash
+bd config set types.custom '["story", "milestone", "spike"]'
+```
+
+After that, `bd create -t story "US-XXX: …"` works as expected.
+
+### Production option: off-site backup
+
+Beads can push a versioned mirror to filesystem, S3, GCS, Azure Blob, or DoltHub:
+
+```bash
+bd backup init s3://my-bucket/beads-backup/
+bd backup sync     # push current DB
+bd backup restore  # bring it back if needed
+```
+
+Worth setting up for any project where task state matters beyond the developer's laptop.
+
+### When to use the MCP server (rarely)
+
+Beads ships a Python MCP server (`beads-mcp`) for clients that don't have shell access — e.g., Claude Desktop, some IDE plugins. Install:
+
+```bash
+uv tool install beads-mcp   # or: pip install beads-mcp
+```
+
+For Claude Code, Cursor, Windsurf, and any agent with shell access, **CLI + hooks is preferred** — it's ~1-2k tokens of context (via `bd prime`) vs 10-50k for the MCP tool schemas. Only reach for `beads-mcp` when shell access isn't available.
+
+### Safe re-initialization
+
+If you need to re-init a Beads database (e.g., migrating to a fresh prefix, recovering from corruption), use the explicit flags rather than `--force`:
+
+- `bd init --reinit-local` — bypass the local-exists guard
+- `bd init --discard-remote` — explicitly authorize discarding remote Dolt history
+- `bd init --destroy-token DESTROY-<prefix>` — required in non-interactive mode for destructive re-init
+
+Stable exit codes: `10` (remote divergence), `11` (local exists), `12` (destroy-token missing). The legacy `--force` flag still works but is deprecated.

package/content/knowledge/core/user-stories.md

@@ -293,7 +293,7 @@ Every PRD feature must map to at least one user story. This is a non-negotiable
 - Loading states, empty states, and offline behavior are often implied but not stated
 
 **Traceability notation:**
-- Use IDs to create a traceable chain: PRD-REQ-001 → US-001 → (downstream: Task BD-42)
+- Use IDs to create a traceable chain: PRD-REQ-001 → US-001 → (downstream: Task bd-a3f8)
 - Story IDs (US-001, US-002, ...) are stable — they persist through updates and are referenced by downstream phases
 
 ### Story Dependencies

package/content/knowledge/execution/multi-agent-coordination.md

@@ -0,0 +1,118 @@
+---
+name: multi-agent-coordination
+description: Upstream Beads primitives for coordinating parallel agents — bd merge-slot for serialized merge resolution and bd gate for async coordination
+topics: [beads, multi-agent, worktrees, merge-conflicts, coordination, parallel-execution]
+---
+
+# Multi-Agent Coordination (Beads Primitives)
+
+When multiple agents work in parallel worktrees and converge on `main`, two upstream Beads primitives prevent the most common coordination failures. Both are optional — scaffold's multi-agent flows work without them — but they meaningfully reduce coordination cost in active parallel workloads.
+
+## `bd merge-slot` — serialized merge resolution
+
+**Problem:** Two agents finish in-flight tasks at roughly the same time. Both rebase on `origin/main` and push. The second agent's push races with the first agent's merge — either gets `non-fast-forward` (retry) or merges a stale base (silent conflict).
+
+**Solution:** Acquire the project's merge slot before rebasing/pushing. Release it after the PR merges. There is **one** merge slot per project (stored as a bead with ID `<prefix>-merge-slot`); the slot uses `status=in_progress` + `metadata.holder` to track the current holder, and a priority-ordered `metadata.waiters` queue.
+
+### Commands
+
+```bash
+# First-time setup (once per project — usually done at bd init time):
+bd merge-slot create
+
+# Before rebasing your feature branch on main:
+bd merge-slot acquire --wait
+# Without --wait, acquire FAILS immediately if the slot is held. With --wait it
+# adds you to the waiters queue and blocks until the slot frees. Holder defaults
+# to $BEADS_ACTOR; pass --holder <name> to override.
+
+# Now safe to rebase and push:
+git fetch origin && git rebase origin/main
+git push -u origin HEAD
+
+# After your PR merges (or if you abandon the work):
+bd merge-slot release
+# --holder is optional (defaults to $BEADS_ACTOR) and is used for verification
+# that you're releasing your own hold, not someone else's.
+
+# To inspect current holder:
+bd merge-slot check
+```
+
+### When to use
+
+Use `bd merge-slot` in multi-agent flows (3+ agents, OR projects where a merge conflict requires careful manual resolution). Skip it for single-agent or two-agent workflows where collisions are rare and `git push` retries are acceptable.
+
+### Failure modes
+
+- **Stale slot** (agent crashes between acquire and release): `bd merge-slot check` reports the current holder. Manual recovery is `bd update <prefix>-merge-slot --status open` to clear the holder field (do this with care — verify the original holder is truly gone first).
+- **Slot held by yourself in a different worktree**: the `--holder` field is checked on release, so multiple worktrees with the same `$BEADS_ACTOR` cannot interfere. Different actors queue behind each other.
+
+## `bd gate` — async coordination gates
+
+**Problem:** Agent A's task can't start until something happens (a PR merges, a workflow completes, a human reviews). Without a gate, Agent A either polls (wasteful) or proceeds anyway and discovers the missing dependency the hard way.
+
+**Solution:** Create a gate issue that blocks the dependent task. The gate is itself a Beads issue with an auto-generated ID. Resolving the gate unblocks the task.
+
+Gate types:
+- `human` (default) — Requires a manual `bd gate resolve <gate-id>`.
+- `timer` — Auto-resolves after `--timeout` (e.g., `--timeout=2h`).
+- `gh:run` — Waits for a GitHub Actions run; `--await-id=<run-id>`.
+- `gh:pr` — Waits for a PR merge; `--await-id=<pr-number>`.
+
+### Commands
+
+```bash
+# When you discover that bd-xyz is blocked until something happens, create a gate.
+# The gate has an auto-generated ID; capture it via --json:
+GATE_ID=$(bd gate create \
+  --blocks bd-xyz \
+  --reason "Waiting for auth-middleware-v2 PR to merge" \
+  --type human \
+  --json | jq -r '.id')
+
+# Common variants:
+# - gh:pr gate (auto-resolves on PR merge)
+bd gate create --type=gh:pr --blocks bd-xyz --await-id=123 --reason "Blocked on PR #123"
+
+# - timer gate
+bd gate create --type=timer --blocks bd-xyz --timeout=2h --reason "Recheck in 2h"
+
+# When the underlying condition is met, resolve manually (human gates) or rely on
+# the type-specific watcher (gh:pr, gh:run, timer):
+bd gate resolve "$GATE_ID" --reason "PR #123 merged, middleware live"
+
+# Check what's gated:
+bd gate list           # open gates only
+bd gate list --all     # include closed
+bd gate check          # evaluate all open gates (resolves any whose condition is met)
+```
+
+### When to use
+
+Use gates for one-off async dependencies — "this task can't proceed until X happens, and X is identifiable as a run ID, a PR number, a timer, or a human decision." Skip them for plain "this task depends on that task" cases, which are covered by `bd dep add --blocks` (a dependency, not a gate).
+
+### Pattern: multiple downstream tasks share one underlying blocker
+
+If five downstream tasks all wait on the same PR merging, create five gh:pr gates (one per blocked issue) all pointing at the same `--await-id=<pr-number>`:
+
+```bash
+for ID in bd-aaa bd-bbb bd-ccc bd-ddd bd-eee; do
+  bd gate create --type=gh:pr --blocks "$ID" --await-id=123 --reason "Blocked on PR #123"
+done
+```
+
+`bd gate check` (or the automatic watcher) resolves all five at once when the PR merges.
+
+> The `bd gate add-waiter` subcommand is a different mechanism — it registers an agent's *wake address* (e.g., "my-project/workers/agent-1") to receive notifications. It's not for chaining issues to gates; use `--blocks` on `bd gate create` for that.
+
+## Composition
+
+Both primitives compose with the rest of the multi-agent flow:
+
+- `bd ready --claim` picks a non-gated, non-blocked task.
+- `bd preflight` validates task readiness before PR (already in scaffold's start prompts).
+- `bd merge-slot acquire` serializes the merge.
+- `bd gate resolve` unblocks downstream waiters when your work lands.
+
+For the canonical sequence in scaffold's multi-agent prompts, see `content/pipeline/build/multi-agent-start.md`.

package/content/knowledge/execution/task-claiming-strategy.md

@@ -66,7 +66,7 @@ Before starting a task, verify all its blockers are resolved. After completing e
 ### Multi-Agent Conflict Avoidance — Extended
 
 **Claiming a task:**
-- Creating a feature branch (e.g., `bd-42/add-user-endpoint`) is the claim signal
+- Creating a feature branch (e.g., `bd-a3f8/add-user-endpoint`) is the claim signal
 - Other agents should check for existing branches before claiming the same task
 - If two agents accidentally claim the same task, the one with fewer commits yields
 
@@ -100,9 +100,9 @@ Beads is an optional task-tracking tool. Detect its presence and adapt.
 
 **When `.beads/` directory exists:**
 - Use `bd ready` to list tasks that are ready for work
-- Use `bd claim <id>` to claim a task (if available)
+- Use `bd update <id> --claim` to atomically claim a task (or `bd ready --claim --json` to find and claim the first available in one call)
 - Use `bd close <id>` after PR is merged to mark task complete
-- Task IDs come from Beads (`bd-42`, `bd-43`, etc.)
+- Task IDs come from Beads (`bd-a3f8`, `bd-a3f9`, etc. — hash-based, lowercase)
 - Branch naming follows Beads convention: `bd-<id>/<short-desc>`
 
 **Without Beads:**
@@ -123,6 +123,18 @@ A task is complete when all of the following are true:
 
 Only after all five criteria are met should the task be marked as done.
 
+## Discovered Work
+
+While implementing a claimed task, you may discover bugs or follow-up tasks. Don't silently expand the current task's scope — file the new work as a separate Beads issue with `discovered-from`:
+
+```bash
+bd create "fix(parser): handle empty input edge case" \
+  --type bug -p 2 \
+  --deps discovered-from:$CURRENT_TASK_ID
+```
+
+`discovered-from` is metadata for traceability — the new issue appears in `bd ready` normally and does NOT block the current task. This preserves the audit trail of why the new task exists.
+
 ## See Also
 
 - [tdd-execution-loop](./tdd-execution-loop.md) — Red-green-refactor cycle and commit timing

package/content/knowledge/execution/worktree-management.md

@@ -179,16 +179,18 @@ git branch | grep "workspace" | xargs -r git branch -D
 
 Use `-D` here because workspace branches are not merged — they're disposable.
 
-### BD_ACTOR Environment Variable
+### BEADS_ACTOR Environment Variable
 
-When using Beads for task tracking, set `BD_ACTOR` per agent for attribution:
+When using Beads for task tracking, set `BEADS_ACTOR` per agent for attribution:
 
 ```bash
-export BD_ACTOR="agent-1"
+export BEADS_ACTOR="agent-1"
 ```
 
 This ensures that task claims, completions, and other Beads operations are attributed to the correct agent. Set it in the agent's shell environment before starting work.
 
+> Older Beads versions (<v1.0.0) used `BD_ACTOR`. It's still accepted as a deprecated alias — if you see it in legacy scripts, rename when you next edit.
+
 ### Listing Active Worktrees
 
 To see all active worktrees and their branches:

package/content/pipeline/build/multi-agent-resume.md

@@ -9,7 +9,7 @@ outputs: []
 conditional: null
 stateless: true
 category: pipeline
-knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management]
+knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management, multi-agent-coordination]
 reads: [coding-standards, tdd, git-workflow]
 argument-hint: "<agent-name>"
 ---
@@ -85,7 +85,7 @@ Before doing anything else, confirm the environment:
    - If NOT in a worktree, stop and instruct the user to set one up or navigate to the correct directory
 
 2. **Beads identity** (if `.beads/` exists)
-   - `echo $BD_ACTOR` — should show `$ARGUMENTS`
+   - `echo $BEADS_ACTOR` — should show `$ARGUMENTS`
    - If not set, the worktree setup may be incomplete
 
 ### State Recovery
@@ -114,14 +114,14 @@ Recover your context by checking the current state of work:
 ### Beads Recovery
 
 **If Beads is configured** (`.beads/` exists):
-- `bd list --actor $ARGUMENTS` — check for tasks with `in_progress` status owned by this agent
-- If a PR shows as merged, close the corresponding task: `bd close <id> && bd sync`
+- `bd list --assignee $ARGUMENTS` — check for tasks with `in_progress` status owned by this agent
+- If a PR shows as merged, close the corresponding task: `bd close <id>`
 - If there is in-progress work, finish it (see "Resume In-Progress Work" below)
 - Otherwise, clean up and start fresh:
   - `git fetch origin --prune && git clean -fd`
   - Run the install command from CLAUDE.md Key Commands
-  - `bd ready` to find the next available task
-- Continue working until `bd ready` shows no available tasks
+  - Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')` (sets `assignee=$BEADS_ACTOR` + `status=in_progress`; no race window between agents).
+- Continue working until `bd ready --claim --json` returns no task.
 
 **Without Beads:**
 - Read `docs/implementation-playbook.md` as the primary task reference.
@@ -171,8 +171,28 @@ Once in-progress work is complete (or if there was none):
    - Fix any findings at or above `fix_threshold` before proceeding
 
 3. **Create PR** (if not already created for in-progress work)
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding.
+   - **For 3+ parallel agents**, acquire the project's merge slot to serialize merge-time conflicts:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot acquire --wait    # blocks if held; queues you in priority order
+     fi
+     ```
+     There is one merge slot per project; `--wait` blocks until you have it. Skip for single-agent or two-agent runs. See `content/knowledge/execution/multi-agent-coordination.md`.
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
+   - After the PR merges (or if you abandon the work), release the slot:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot release   # holder verified via $BEADS_ACTOR
+     fi
+     ```
    - Include agent name in PR description for traceability
 
 4. **Run code reviews (MANDATORY)**
@@ -219,7 +239,7 @@ Once in-progress work is complete (or if there was none):
 - Push updates and re-request review
 
 **Task was completed by another agent:**
-- If Beads: `bd sync` will show updated task states
+- If Beads: A `git pull` (and `bd dolt pull` if a Dolt remote is configured) brings the local DB current; run `bd doctor --fix` if anything looks stale.
 - Without Beads: check the plan/playbook for recently completed tasks and open PRs
 - Skip to the next available task