fix(store): pin the board to its repo's beads workspace — no walk-up escape (v0.20.1) (#52)

When `project_board.repo` points at a git repo with NO `.beads/` workspace, `br`'s
auto-discovery walks UP the tree and silently adopts an ancestor's `.beads/` — so the
board reads/writes the wrong (often shared parent) db, with the wrong id prefix, and
its state never lives with the intended repo. Especially bad for the federated
multi-team model (ADR 0055), where each team-agent is meant to own an isolated board.

Add a lazy `_ensure_workspace()` (run once before the first `br` op):
  • an explicit `db_path` is the hard pin — nothing to do (and never walk up)
  • a repo that already has `.beads/` resolves locally — nothing to do
  • a repo with NO `.beads/` → `br init` it (matches the operator's manual workaround),
    so cwd-discovery resolves to the repo's own workspace instead of escaping upward
  • if `br init` can't create one → a clear, actionable BoardError ("run `br init`
    there, or set project_board.db_path") rather than a silent cross-repo bleed

Reproduced the escape + verified the fix against real `br` 0.1.23; unit-tested the
four branches with subprocess/fs stubbed (the suite needs no real `br`).

Closes #48

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mabry1985

protoagent.plugin.yaml

@@ -1,6 +1,6 @@
 id: project_board
 name: Project Board (coding orchestration)
-version: 0.20.0
+version: 0.20.1
 description: >-
   A board-driven coding-orchestration plugin: a lean 6-state board (backlog → ready
   → in_progress → in_review → done, + a blocked flag) backed by **beads** (`br`), an

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "project-board"
-version = "0.20.0"
+version = "0.20.1"
 description = "Board-driven coding-orchestration plugin for protoAgent (beads board + ACP spawn loop + planning layer + console view)."
 requires-python = ">=3.11"
 

store.py

@@ -75,9 +75,46 @@ def __init__(self, db: str | None = None, actor: str = "agent", repo: str = ".",
         self.actor = actor
         self.repo = repo
         self.base_branch = base_branch
+        self._workspace_ready = False  # lazily pinned on first _run (see _ensure_workspace)
+
+    # ── workspace pin (ADR 0055 P0, #48) ──────────────────────────────────────
+    def _ensure_workspace(self) -> None:
+        """Pin the board to THIS repo's beads workspace so `br` can't walk UP the tree
+        and silently adopt a parent/ancestor `.beads/` (the cross-repo bleed of #48).
+
+        `br` discovers `.beads/` by walking UP from cwd. With `cwd=self.repo` it stops at
+        the repo's own `.beads/` when one exists — but a repo with NONE escapes to whatever
+        ancestor happens to have one, polluting a shared db with the wrong id prefix. So:
+        an explicit `db` is the hard pin (nothing to do); otherwise, if the repo has no
+        `.beads/`, run `br init` there to give it its own — after which cwd-discovery
+        resolves locally and never walks up (matches the operator's manual workaround).
+        Lazy + idempotent (runs once, guarded by `_workspace_ready`)."""
+        if self._workspace_ready or self.db:
+            self._workspace_ready = True
+            return
+        repo = self.repo or "."
+        if not os.path.isdir(os.path.join(repo, ".beads")):
+            log.warning(
+                "[project_board] repo %r has no .beads/ workspace — running `br init` to pin the "
+                "board here (else `br` walks up and adopts a parent db, polluting it with the wrong "
+                "id prefix; ADR 0055 isolation)",
+                repo,
+            )
+            # NB: a direct subprocess, NOT self._run — that would recurse here, and we want
+            # a precise error rather than the generic `br … failed` wrapper.
+            proc = subprocess.run(
+                [BR, "init", "--actor", self.actor], cwd=repo, capture_output=True, text=True, timeout=30
+            )
+            if proc.returncode != 0 and not os.path.isdir(os.path.join(repo, ".beads")):
+                raise BoardError(
+                    f"repo {repo!r} has no beads workspace and `br init` failed "
+                    f"({proc.stderr.strip()[:200]}) — run `br init` there, or set project_board.db_path"
+                )
+        self._workspace_ready = True
 
     # ── br invocation ─────────────────────────────────────────────────────────
     def _run(self, *args: str, want_json: bool = False):
+        self._ensure_workspace()  # pin to the repo's own .beads/ before any br op (#48)
         cmd = [BR, *args, "--actor", self.actor]
         if self.db:
             cmd += ["--db", self.db]

tests/test_store.py

@@ -9,6 +9,8 @@
 
 from __future__ import annotations
 
+import types
+
 import pytest
 
 from project_board import store
@@ -71,6 +73,68 @@ def test_escalation_enabled_needs_two_distinct_coders(cfg, expected):
     assert escalation_enabled(cfg) is expected
 
 
+# ── _ensure_workspace: pin to the repo's own .beads/ (no walk-up escape, #48) ────
+
+
+def _ok():
+    return types.SimpleNamespace(returncode=0, stdout="", stderr="")
+
+
+def _board(monkeypatch, *, db=None, repo="/repo"):
+    """A BeadsBoard with the `br` PATH check stubbed (so __init__ passes) but the REAL
+    _ensure_workspace intact — for exercising the workspace-pin logic directly."""
+    monkeypatch.setattr(store.shutil, "which", lambda *_a, **_k: "/usr/bin/br")
+    return BeadsBoard(db=db, repo=repo)
+
+
+def test_ensure_workspace_noop_with_explicit_db(monkeypatch):
+    """An explicit db_path is the hard pin — never br-init, never walk up."""
+    calls = []
+    monkeypatch.setattr(store.subprocess, "run", lambda *a, **k: calls.append(a) or _ok())
+    b = _board(monkeypatch, db="/somewhere/.beads/beads.db")
+    b._ensure_workspace()
+    assert calls == [] and b._workspace_ready  # no init shelled
+
+
+def test_ensure_workspace_noop_when_repo_has_beads(monkeypatch):
+    """Repo already has its own .beads/ → cwd-discovery resolves locally; no init."""
+    monkeypatch.setattr(store.os.path, "isdir", lambda p: p.endswith(".beads"))
+    calls = []
+    monkeypatch.setattr(store.subprocess, "run", lambda *a, **k: calls.append(a) or _ok())
+    _board(monkeypatch)._ensure_workspace()
+    assert calls == []
+
+
+def test_ensure_workspace_br_inits_a_repo_with_no_beads(monkeypatch):
+    """Repo with no .beads/ → `br init` it ONCE, then the pin is ready and not re-run."""
+    state = {"beads": False}
+    monkeypatch.setattr(store.os.path, "isdir", lambda p: state["beads"] and p.endswith(".beads"))
+    inits = []
+
+    def _run(cmd, **k):
+        inits.append(cmd)
+        state["beads"] = True  # init created .beads/
+        return _ok()
+
+    monkeypatch.setattr(store.subprocess, "run", _run)
+    b = _board(monkeypatch, repo="/fresh")
+    b._ensure_workspace()
+    assert len(inits) == 1 and inits[0][:2] == [store.BR, "init"] and b._workspace_ready
+    b._ensure_workspace()  # idempotent — guarded by _workspace_ready, no second init
+    assert len(inits) == 1
+
+
+def test_ensure_workspace_raises_a_clear_error_when_init_fails(monkeypatch):
+    """No .beads/ and `br init` fails (still none) → an actionable BoardError, NOT a
+    silent escape to a parent db."""
+    monkeypatch.setattr(store.os.path, "isdir", lambda p: False)
+    monkeypatch.setattr(
+        store.subprocess, "run", lambda *a, **k: types.SimpleNamespace(returncode=1, stdout="", stderr="denied")
+    )
+    with pytest.raises(BoardError, match="has no beads workspace"):
+        _board(monkeypatch, repo="/ro")._ensure_workspace()
+
+
 def test_next_tier_walks_then_stops_at_the_top(make_board):
     b = make_board(Br())
     # Ladder: smart → reasoning → opus (fast dropped — protolabs/fast too weak).