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

Inizia leggendo src/bmad_loop/workspace.py e src/bmad_loop/bmadconfig.py, quindi segui i risultati della validazione di git.probe, git.worktree-clean e policy.isolation-repo-root. Confronta il lavoro correlato a #414 e #443 prima di decidere dove debbano risiedere lo stato multi-root e il coordinamento dei commit. Il lavoro è concluso quando sono stati concordati l’ambito e il design, con fixture o casi di test che coprano un workspace non-git e più repository fratelli.

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.