fix(beads): harden worktree identity checks

.agents/workflow.md

@@ -9,8 +9,7 @@ This file expands [AGENTS.md](../AGENTS.md) for day-to-day repo work: tracker ha
 - Keep private launcher names, local paths, session aliases, dispatch policy, and operator workspace details outside this public repository.
 - GitHub remains the PR, CI, review, and merge surface. Use GitHub Issues or Projects for external collaboration only when the user or operator explicitly asks for that workflow.
 - Do not add repo-local tracker directories, tracker JSONL exports, dispatch logs, cross-repo research records, or operator decision records to AgentV commits unless the user explicitly asks for repository-local tracker artifacts.
-- The only repo-local Beads files intentionally tracked are `.beads/config.yaml`, `.beads/metadata.json`, and `.beads/.gitignore`. Never commit the embedded Dolt database, JSONL exports, backups, locks, logs, or runtime state.
-- Do not commit project-local coordination config files. The safe Beads defaults above are the exception.
+- Do not commit project-local coordination config files.
 - Do not use `git stash` on shared checkouts. Inspect `git status`, stage only your files, use a dedicated worktree, or ask before moving uncommitted changes.
 
 ## Worktree Setup
@@ -20,6 +19,7 @@ This file expands [AGENTS.md](../AGENTS.md) for day-to-day repo work: tracker ha
 - When working in the primary checkout, stage explicit paths only. Do not commit another agent's files, project-local coordination config, generated evidence, or unrelated tracker or doc state.
 - Use a dedicated git worktree based on the latest `origin/main` for non-trivial, risky, cross-cutting, long-running, or parallel implementation, or whenever the primary checkout is stale or dirty in paths you need.
 - Before starting implementation in a dedicated worktree, verify its `HEAD` is based on the current `origin/main` commit.
+- Before Beads bootstrap, copy `.beads/config.yaml.example` to `.beads/config.yaml` and run `bun run beads:check`. Keep `.beads/metadata.json` tracked; it preserves AgentV's `av` embedded Dolt identity. See [docs/runbooks/beads-worktree-recovery.md](../docs/runbooks/beads-worktree-recovery.md).
 
 Manual setup:
 

.beads/.gitignore

@@ -73,7 +73,13 @@ backup/
 *.db-shm
 db.sqlite
 bd.db
+
+# Checkout-local config. Copy config.yaml.example when using Beads.
+config.yaml
+
+# metadata.json is intentionally tracked. It preserves the embedded Dolt
+# database identity for AgentV's av Beads workspace.
+
 # NOTE: Do NOT add negation patterns here.
 # They would override fork protection in .git/info/exclude.
-# Config files (metadata.json, config.yaml) are tracked by git by default
-# since no pattern above ignores them.
+# config.yaml.example is the tracked template for the AgentV Beads remote.

.beads/config.yaml → .beads/config.yaml.example

@@ -1,4 +1,6 @@
 # Beads Configuration File
+# Copy this file to .beads/config.yaml when using Beads in this checkout.
+# Keep .beads/config.yaml local; do not commit it.
 # This file configures default behavior for all bd commands in this repository
 # All settings can also be set via environment variables (BD_* prefix)
 # or overridden with command-line flags
@@ -53,4 +55,7 @@
 # - github.org
 # - github.repo
 
+# AgentV code lives in EntityProcess/agentv. Beads coordination data lives in
+# EntityProcess/agentv-beads. Keep both Beads remotes pointed at agentv-beads.
+sync.remote: "git+https://github.com/EntityProcess/agentv-beads.git"
 federation.remote: "git+https://github.com/EntityProcess/agentv-beads.git"

AGENTS.md

@@ -72,6 +72,7 @@ Common entry points:
 
 - Product or architecture decisions: start with [STRATEGY.md](STRATEGY.md), [ROADMAP.md](ROADMAP.md), and [.agents/product-boundary.md](.agents/product-boundary.md).
 - Tracker, worktree, or PR flow questions: read [.agents/workflow.md](.agents/workflow.md).
+- Beads bootstrap or recovery questions: read [docs/runbooks/beads-worktree-recovery.md](docs/runbooks/beads-worktree-recovery.md).
 - Dashboard, docs, CLI UX, or grader verification work: read [.agents/verification.md](.agents/verification.md).
 - Wire-format, naming, or grader-type changes: read [.agents/conventions.md](.agents/conventions.md).
 - Version bumps or npm publishing: read [.agents/publish.md](.agents/publish.md).

docs/runbooks/beads-worktree-recovery.md

@@ -0,0 +1,83 @@
+# AgentV Beads Worktree Recovery
+
+AgentV keeps code and tracker data in separate repositories:
+
+- Code repository: `EntityProcess/agentv`
+- Beads coordination repository: `EntityProcess/agentv-beads`
+
+Do not point Beads, Dolt, bootstrap, or federation data at the code repository.
+The tracked `.beads/metadata.json` preserves AgentV's embedded Dolt identity:
+database `av` and project `a7aea826-0087-45fc-93f5-9084e9924e8b`.
+
+`.beads/config.yaml` is checkout-local. Copy `.beads/config.yaml.example`
+before running `bd bootstrap`; the example pins both `sync.remote` and
+`federation.remote` to `EntityProcess/agentv-beads`.
+
+## Preflight
+
+Run the guard before `bd bootstrap`, `bd dolt push`, or `bd federation sync`:
+
+```bash
+bun run beads:check
+```
+
+For static repository checks only:
+
+```bash
+bun run beads:check -- --skip-bd
+```
+
+For a disposable fresh-bootstrap fixture:
+
+```bash
+bun run beads:check -- --fixture
+```
+
+A healthy setup reports database `av`, project
+`a7aea826-0087-45fc-93f5-9084e9924e8b`, and bootstrap `sync_remote`
+`git+https://github.com/EntityProcess/agentv-beads.git`.
+
+## Fresh Worktree
+
+After creating an AgentV worktree:
+
+```bash
+bun install
+cp "$(git worktree list --porcelain | head -1 | sed 's/worktree //')/.env" .env
+cp .beads/config.yaml.example .beads/config.yaml
+bun run beads:check
+bd bootstrap --dry-run
+bd bootstrap
+```
+
+Stop if `bd bootstrap --dry-run` plans to sync from
+`git+https://github.com/EntityProcess/agentv.git` or database `beads`.
+
+## Recovery
+
+If `bd --readonly context --json` reports database `beads`, no project ID, or a
+project ID other than `a7aea826-0087-45fc-93f5-9084e9924e8b`, restore the tracked
+identity and local config first:
+
+```bash
+git restore -- .beads/metadata.json
+cp .beads/config.yaml.example .beads/config.yaml
+bun run beads:check
+```
+
+If the Dolt origin or bootstrap plan still points at the code repository,
+re-point the Dolt remote before pushing:
+
+```bash
+bd dolt remote list
+bd dolt remote remove origin
+bd dolt remote add origin git+https://github.com/EntityProcess/agentv-beads.git
+bd bootstrap --dry-run
+bd bootstrap
+bd federation status
+```
+
+Do not delete `.beads/embeddeddolt/`, `.beads/dolt/`, or backups as the first
+recovery step. They may contain local coordination data. If the guard still
+reports a metadata or project mismatch after restoring metadata and re-pointing
+the remote, preserve the checkout and hand the guard output to the coordinator.

package.json

@@ -18,6 +18,7 @@
     "test:watch": "bun --filter @agentv/core test:watch & bun --filter agentv test:watch",
     "agentv": "bun apps/cli/src/cli.ts",
     "agentv:buildrun": "bun run build && bun apps/cli/dist/cli.js",
+    "beads:check": "bun scripts/check-beads-context.ts",
     "validate:examples": "EVAL_CRITERIA=placeholder CUSTOM_SYSTEM_PROMPT=placeholder bun scripts/validate-example-evals.ts",
     "eval:baseline-check": "bun scripts/check-eval-baselines.ts",
     "release": "bun scripts/release.ts",