Feature: multi-git / polyrepo workspace support (project root is not a git repo)

Bắt đầu bằng cách đọc src/bmad_loop/workspace.py và src/bmad_loop/bmadconfig.py, sau đó lần theo các kết quả xác thực của git.probe, git.worktree-clean và policy.isolation-repo-root. So sánh phần công việc liên quan đến #414 và #443 trước khi quyết định trạng thái multi-root và việc điều phối commit nên thuộc về đâu. Hoàn thành nghĩa là đã thống nhất phạm vi và thiết kế, với các fixture hoặc trường hợp kiểm thử bao quát một workspace không phải git và nhiều repository anh em.

Summary

Request first-class support for polyrepo / multi-git workspaces: a BMAD project whose workspace root is not a git repository, with several sibling git repos under it that a single story may touch and that must be committed separately (per repo, with path allowlists).

Today bmad-loop appears to assume one git root (Workspace.root / repo_root: Path). That model fits monorepos and single-repo projects, but blocks using bmad-loop as the unattended orchestrator for multi-repo product workspaces.

Context / motivation

We run a multi-product workspace roughly like:

quest/                    # workspace root — NOT a git repo
├── _bmad/                # BMAD install + custom (shared)
├── AGENTS.md
├── quest-api/            # git repo (.NET / ABP backend)
├── quest-admin/          # git repo (Vue admin monorepo)
├── quest-mobile/         # git repo (Taro + Vue mobile)
└── docs/                 # git repo (product docs + BMAD artifacts:
                          #   sprint-status, stories, specs under docs/_bmad-output/)

Realities that matter for orchestration:

1. Agents and humans work from the workspace root (shared _bmad/, shared sprint board, cross-repo stories), not from a single child repo.
2. One story often spans 2–3 repos (e.g. API + OpenAPI client regen in admin + story/sprint updates in docs).
3. Commits must be split by host repo with strict stage allowlists (never git add . at workspace root; no mixing unrelated dirty trees).
4. Sprint / implementation artifacts live in docs/, while code lives in other repos — not under a single git tree that also holds the code.

We already use BMAD Method (planning + implementation skills) and maintain a custom unattended Goal orchestrator for multi-repo serial story execution. We want to align with official bmad-build-auto + bmad-loop where possible, but today the loop’s SCM model does not match this layout.

What we understand works today (and what does not)

Supported (as documented / implemented on main)

• Single git repository as project (or project == git root).
• Monorepo path split via optional repo_root in _bmad/bmm/config.yaml: one git root, project dir may differ (e.g. package subdirectory). Documented as monorepo / “git root differs from project dir”.
• repo_root is a single Path (ProjectPaths.repo_root), not a list.
• Worktree isolation, baseline match, squash-to-one-story-commit, and git.worktree-clean / git.probe all operate on that one repo.
• repo_root ≠ project is incompatible with isolation = "worktree" (#414 / #443 track plumbing for monorepo+worktree, not multi-git).

Not supported (gap for us)

Workarounds we considered and rejected as primary path:

1. Point --project at quest-api only → loses admin/mobile/docs in the same loop.
2. Four independent loop installs → four boards, no cross-repo hard gates.
3. Collapse into one monorepo → incompatible with our release/ownership model.

Desired outcomes (product)

Minimal viable multi-git support would let us:

1. Set project = workspace root (may have no git).
2. Declare one or more git roots (sibling repos) that the orchestrator may touch.
3. Run the usual pick story → build-auto → verify → review → commit loop with sessions still cwd’d at the workspace root (so agents see all trees + _bmad).
4. On commit boundary:
   • detect which configured roots have changes for this story,
   • commit per root (optional message template still OK),
   • never require the workspace root itself to be a git repo,
   • optionally enforce per-root path allowlists / ignore patterns.
5. Preflight:
   • each configured root is a git repo and (policy-dependent) clean enough to start,
   • missing root or non-git path is a clear validate finding.

Nice-to-have (later):

• Per-story or per-epic primary repo + optional secondary roots.
• Worktree isolation per root (or only for roots that are dirty / opted in).
• Verify commands with cwd per root (e.g. dotnet test in api, pnpm test in admin).
• Documented guidance for “BMAD artifacts in a docs-only repo”.

Non-goals (for this request)

• Replacing multi-package monorepos (already covered by repo_root).
• Automatic PR creation across remotes.
• Parallel multi-root fan-out (serial per story is fine).

Suggested design sketch (for discussion, not a demand)

Something like (names illustrative only):

# .bmad-loop/policy.toml or _bmad/bmm/config.yaml
[scm]
# project may be a non-git workspace root
mode = "polyrepo"   # or isolation remains "none"|"worktree" per root later

[[scm.repos]]
id = "api"
path = "quest-api"          # relative to project
# optional: verify_commands, commit_message_template, path_allowlist

[[scm.repos]]
id = "admin"
path = "quest-admin"

[[scm.repos]]
id = "docs"
path = "docs"

Engine changes (high level):

• Workspace / commit / baseline APIs become multi-root-aware (or a thin coordinator over N single-root workspaces).
• git.probe / clean checks iterate configured roots.
• Story completion records N SHAs (or a map id→sha) instead of one commit_sha.
• bmad-build-auto can keep writing specs under implementation_artifacts (often in the docs repo); the loop only needs to accept multi-root dirty trees without treating “workspace root is not git” as fatal.

Happy to adjust this to whatever fits the existing Workspace seam better.

Environment

• BMAD-METHOD: planning upgrade to ≥ 6.11 (bmad-build-auto); currently on 6.10 with bmad-dev-auto.
• bmad-loop: module present in project (bmad-loop-setup / skills); not adopted as main orchestrator because of multi-git gap.
• Host OS: macOS.
• Coding agents: Grok Build CLI / Claude / Codex as available.

References (upstream)

• README: Worktree isolation + repo_root monorepo note (“decouples where git/code work happens from where run state lives”)
• src/bmad_loop/workspace.py: single root / repo_root
• src/bmad_loop/bmadconfig.py: repo_root: Path; worktree+repo_root refusal
• Validate findings: git.probe, git.worktree-clean, policy.isolation-repo-root
• Issues #414 / #443 (monorepo + worktree plumbing) — related but not multi-git

Ask

1. Is multi-git / polyrepo on the roadmap, or intentionally out of scope?
2. If in scope, would you prefer a policy-driven [[scm.repos]] model vs requiring a synthetic parent git (submodules/subtree) that we do not want?
3. Any recommended interim pattern for “artifacts in docs repo + code in sibling repos” that still uses official build-auto under a thin external orchestrator?

Thanks — happy to supply a minimal public fixture layout or test cases if useful.