@zigrivers/scaffold 3.26.0 → 3.28.0

package/README.md

@@ -29,7 +29,7 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 **Assembly engine** — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
 
-**Knowledge base** — 235 domain expertise entries in `content/knowledge/` organized in eighteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, data-science reproducibility and notebook discipline, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
+**Knowledge base** — 267 domain expertise entries in `content/knowledge/` organized in nineteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science, web3) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, data-science reproducibility and notebook discipline, smart-contract security and audit workflow, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
@@ -368,7 +368,7 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 | `--depth` | 1-5 | Custom methodology depth (requires `--methodology custom`) |
 | `--adapters` | comma-sep | AI adapters: claude-code, codex, gemini |
 | `--traits` | comma-sep | Project traits: web, mobile |
-| `--project-type` | string | web-app, mobile-app, backend, cli, library, game, data-pipeline, ml, browser-extension, research, data-science |
+| `--project-type` | string | web-app, mobile-app, backend, cli, library, game, data-pipeline, ml, browser-extension, research, data-science, web3 |
 | `--auto` | boolean | Non-interactive mode (uses Zod defaults for unset flags) |
 
 #### Web-App Config Flags (require `--project-type web-app` or auto-set it)
@@ -465,6 +465,14 @@ Data science has one forward-compatible config field in the schema, defaulted au
 |------|------|--------|
 | `dataScienceConfig.audience` | `solo` | Default (applied by the wizard and `--auto`). Covers the DS-1 audience (solo / small-team, local-first, prototyping). A future DS-2 release will extend the enum with `'platform'` (platform-engineered / larger-team DS) additively, without breaking existing configs. |
 
+#### Web3 Config (`--project-type web3`)
+
+Web3 has one forward-compatible config field in the schema, defaulted automatically — no CLI flags are needed in v1:
+
+| Config field | Values | Notes |
+|------|------|--------|
+| `web3Config.scope` | `contracts` | Default (applied by the wizard and `--auto`). Covers the W3-1 audience (smart-contract / protocol projects on EVM chains — Foundry / Hardhat). A future W3-2 release will extend the enum with `'dapp'` (web3 application / dApp) additively, without breaking existing configs. |
+
 #### Game Config Flags (require `--project-type game` or auto-set it)
 
 | Flag | Type | Values |
@@ -514,7 +522,7 @@ during assembly.
 
 - **Flag > auto > interactive**: Flags always take highest precedence. `--auto --engine unreal` uses defaults for everything except engine.
 - **Partial flags + interactive**: Provide some flags and the wizard asks only the remaining questions. `scaffold init --project-type game --engine unreal` prompts interactively for multiplayer, platforms, etc.
-- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`, `--pipeline-processing batch` sets `--project-type data-pipeline`, `--ml-phase training` sets `--project-type ml`, `--ext-manifest 3` sets `--project-type browser-extension`, `--research-driver code-driven` sets `--project-type research`. Error if conflicting type. (Data science currently has no dedicated CLI flags — pass `--project-type data-science` directly.)
+- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`, `--pipeline-processing batch` sets `--project-type data-pipeline`, `--ml-phase training` sets `--project-type ml`, `--ext-manifest 3` sets `--project-type browser-extension`, `--research-driver code-driven` sets `--project-type research`. Error if conflicting type. (Data science and web3 currently have no dedicated CLI flags — pass `--project-type data-science` or `--project-type web3` directly.)
 - **Cannot mix flag families**: `--web-rendering ssr --backend-api-style rest` is an error. Each flag family (`--web-*`, `--backend-*`, `--cli-*`, `--lib-*`, `--mobile-*`, `--pipeline-*`, `--ml-*`, `--research-*`, `--ext-*`, game) is exclusive.
 - **Validation**: `--depth` requires `--methodology custom`. `--online-services` requires `--multiplayer online` or `hybrid`. SSR/hybrid rendering is incompatible with static deploy target. Session auth requires server state (not static). ML inference projects must specify a serving pattern. Browser extensions must declare at least one capability (UI surface, content script, or background worker). Notebook-driven research cannot be fully autonomous.
 
@@ -610,6 +618,9 @@ scaffold init --auto --methodology deep --project-type research \
 # Solo / small-team data science project (reproducibility-first)
 scaffold init --auto --methodology deep --project-type data-science
 
+# Web3 smart-contract / protocol project (Foundry / Hardhat on EVM)
+scaffold init --auto --methodology deep --project-type web3
+
 # Multiplayer mobile game with Unity
 scaffold init --project-type game --methodology deep --auto \
   --engine unity --multiplayer online --target-platforms ios,android \
@@ -636,7 +647,7 @@ Scaffold supports **project-type overlays** — domain-specific knowledge and pi
 
 - **Injects domain knowledge** into existing pipeline steps (e.g., SSR caching strategies into `tech-stack`, API pagination patterns into `coding-standards`)
 
-The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, mobile-app, data-pipeline, ML, browser-extension, research, and data-science overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other. The research type additionally supports **domain sub-overlays** (quant-finance, ml-research, simulation) that layer domain-specific knowledge on top of the core research overlay, and the backend type supports a `fintech` sub-overlay. Both research and backend accept `domain` as either a single string or an array (e.g. `domain: ['quant-finance', 'simulation']`) for stacking multiple sub-overlays; the wizard and CLI flags remain single-select in v1, so multi-domain stacking requires hand-editing `.scaffold/config.yml`.
+The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, mobile-app, data-pipeline, ML, browser-extension, research, data-science, and web3 overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other. The research type additionally supports **domain sub-overlays** (quant-finance, ml-research, simulation) that layer domain-specific knowledge on top of the core research overlay, and the backend type supports a `fintech` sub-overlay. Both research and backend accept `domain` as either a single string or an array (e.g. `domain: ['quant-finance', 'simulation']`) for stacking multiple sub-overlays; the wizard and CLI flags remain single-select in v1, so multi-domain stacking requires hand-editing `.scaffold/config.yml`.
 
 Overlays are composable with methodology presets. An MVP web-app gets fewer steps at lower depth; a deep backend project gets exhaustive analysis of every architectural decision.
 
@@ -652,6 +663,7 @@ Overlays are composable with methodology presets. An MVP web-app gets fewer step
 | `browser-extension` | `browser-extension-overlay.yml` | 12 entries (architecture, manifest configuration, service workers, content scripts, cross-browser, store submission, testing, security) | Manifest version, UI surfaces, content script, background worker |
 | `research` | `research-overlay.yml` + domain sub-overlays | 25 entries (experiment loop, tracking, overfitting prevention, backtesting, risk metrics, architecture search, simulation) | Experiment driver, interaction mode, domain, experiment tracking |
 | `data-science` | `data-science-overlay.yml` | 13 entries (reproducibility, experiment tracking, notebook discipline, model evaluation, data versioning, dev environment, observability, project structure, conventions, requirements, security, testing, architecture) | Audience (`solo` default; `platform` reserved for DS-2) |
+| `web3` | `web3-overlay.yml` | 14 entries (Foundry tooling, smart-contract security, upgradeability, gas optimization, oracles, audit workflow, deployment, testing patterns, EVM fundamentals, ABI/interface design, event/log indexing, supply-chain) | Scope (`contracts` default; `dapp` reserved for W3-2) |
 | `game` | `game-overlay.yml` | 24 entries (engines, networking, audio, VR/AR, economy, save systems, certification) | Engine, multiplayer, platforms, economy, narrative, and 6 more |
 
 ### Game Development
@@ -737,7 +749,7 @@ These answers control which conditional steps activate. A single-player puzzle g
 
 #### Multi-type Detection
 
-`scaffold adopt` detects 11 project types from manifest files and directory layouts:
+`scaffold adopt` detects 12 project types from manifest files and directory layouts:
 
 | Type | Key Signals |
 |------|-------------|
@@ -752,6 +764,7 @@ These answers control which conditional steps activate. A single-player puzzle g
 | `browser-extension` | `manifest.json` with `manifest_version` field |
 | `research` | `program.md` + `results.tsv`, backtest/strategy files with trading deps, optimization deps + experiment dirs, simulation framework deps |
 | `data-science` | Marimo signals required (`marimo` dep or `.marimo.toml`); DVC (`dvc.yaml`, `.dvc/config`, `dvc` py dep) is supplementary evidence only. Low-tier; defers to `ml` / `research` / `data-pipeline` when those match at medium/high tier |
+| `web3` | `foundry.toml` or `hardhat.config.{ts,js,cjs,mjs}` (medium-tier); `remappings.txt`, `lib/forge-std` are supplementary low-tier signals. EVM-only scope. Library-collision boundary pinned by tiebreak (high-tier `library` wins over medium-tier `web3` for published-library Hardhat projects) |
 
 Each detector returns a confidence tier (high/medium/low) with evidence trails. Override detection with `--project-type <type>`.
 
@@ -1512,7 +1525,7 @@ scaffold dashboard
 
 ## Knowledge System
 
-Scaffold ships with 235 domain expertise entries organized in eighteen categories:
+Scaffold ships with 267 domain expertise entries organized in nineteen categories:
 
 - **core/** (26 entries) — eval craft, testing strategy, domain modeling, API design, database design, system architecture, ADR craft, security best practices, operations, task decomposition, user stories, UX specification, design system tokens, user story innovation, AI memory management, coding conventions, tech stack selection, project structure patterns, task tracking, CLAUDE.md patterns, multi-model review dispatch, review step template, dev environment, git workflow patterns, automated review tooling, vision craft
 - **product/** (5 entries) — PRD craft, PRD innovation, gap analysis, vision craft, vision innovation
@@ -1532,6 +1545,7 @@ Scaffold ships with 235 domain expertise entries organized in eighteen categorie
 - **browser-extension/** (12 entries) — Manifest V3, content scripts, service workers, cross-browser compatibility, extension security, store submission
 - **research/** (25 entries) — experiment loop architecture, parameter optimization, overfitting prevention, experiment tracking, security/sandboxing; domain knowledge for quant-finance (backtesting, risk metrics, market data, strategy patterns), ML-research (architecture search, ablation studies, evaluation), and simulation (engine integration, parameter spaces, compute management)
 - **data-science/** (13 entries) — reproducibility, experiment tracking, notebook discipline, model evaluation, data versioning, dev environment (Marimo/Jupyter/Hex), observability, project structure, conventions, requirements, security, testing, architecture
+- **web3/** (14 entries) — Foundry tooling and dev environment, smart-contract security and common vulnerabilities, upgradeability patterns, gas optimization, oracles and external data, audit workflow, deployment and verification, testing patterns, access control, EVM/contract architecture, conventions, project structure, requirements
 
 Each pipeline step declares which knowledge entries it needs in its frontmatter. The assembly engine injects them automatically. Knowledge files with a `## Deep Guidance` section are optimized for the CLI — only the deep guidance content is loaded into the assembled prompt, skipping the summary to avoid redundancy with the prompt text.
 
@@ -1740,7 +1754,7 @@ All build inputs live under `content/`:
 content/
 ├── pipeline/         # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
 ├── tools/            # 10 tool meta-prompts (stateless, category: tool)
-├── knowledge/        # 235 domain expertise entries (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science)
+├── knowledge/        # 267 domain expertise entries (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science, web3)
 ├── methodology/      # 3 YAML presets (deep, mvp, custom)
 └── skills/           # Skill templates with {{markers}} for multi-platform resolution (includes mmr)
 ```

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: