provision_worktree's exclude patterns are repo-wide and permanent: new files under .claude/skills silently stop being staged in the main checkout

[tjoignant]

provision_worktree shields a transient worktree by writing repo-wide, permanent exclude patterns. The patterns name directories that projects legitimately track (.claude/skills, .claude/settings.json), and nothing ever removes them — so long after the run, every new file under those paths is invisible to git add -A in the main checkout.

Observed on bmad-loop 0.9.0, git 2.30.0, macOS.

What happens

worktree_flow.py:286-293 builds the shield set from the CLI profiles:

patterns = {f"/{p.skill_tree}" for p in profiles}                              # -> /.claude/skills
patterns |= {f"/{p.hooks.config_path}" for p in profiles if not p.hookless}    # -> /.claude/settings.json
patterns |= {f"/{rel}" for rel in seeded}
reason = _worktree_local_exclude(worktree, sorted(patterns))

_worktree_local_exclude (install.py:734) resolves its target with git rev-parse --git-common-dir (install.py:787-793). From a linked worktree that answers with the main repo's .git, so the patterns are appended to the repository-wide .git/info/exclude.

The defaults in adapters/profile.py:50,62 are .claude/settings.json and .claude/skills, so a stock claude profile writes exactly:

/.claude/settings.json
/.claude/skills

Two properties combine badly:

1. Scope — the file is shared by the main checkout and every worktree, so a shield meant for one unit applies to the user's own working tree.
2. Lifetime — _worktree_local_exclude is the only writer and has no counterpart remover; gc_run_worktrees reclaims the worktree and leaves the lines behind. isolation back to "none" doesn't matter; the lines outlive the feature that wrote them.

The docstring argues the write is safe because it "does not affect already-tracked files." True, and that is precisely what makes it hard to notice: .claude/skills/ is full of tracked files that keep diffing normally, while every newly created sibling silently disappears from git status and git add -A.

Impact in my repo

/.claude/skills sat in .git/info/exclude across two BMAD-METHOD installer upgrades. Both upgrade commits captured only modifications to files that were already tracked; 51 new files were never staged, including three whole skills (bmad-review, bmad-editorial-review, bmad-deep-recon).

The merged result was an internally inconsistent repo: _bmad/_config/bmad-help.csv and files-manifest.csv referenced bmad-review, and the committed deprecation stubs (bmad-editorial-review-prose, bmad-review-adversarial-general, …) forwarded to it — but a fresh clone had no such skill. Nothing in the diff of either PR could reveal why, since .git/info/exclude is unversioned and unreviewable by construction.

.bmad-loop/runs/*/state.json records "isolation": "worktree" on 17 runs here, so this is the ordinary path, not an exotic configuration.

Two things I verified before filing

A per-worktree info/exclude does not exist. Writing /marker.txt into .git/worktrees/<id>/info/exclude has no effect — git only reads $GIT_COMMON_DIR/info/exclude:

$ git -C ../wt rev-parse --git-dir
.../main-repo/.git/worktrees/wt
$ printf '/marker.txt\n' > .../main-repo/.git/worktrees/wt/info/exclude
$ touch ../wt/marker.txt && git -C ../wt status --short
?? marker.txt

So the choice of the common dir is not the bug — it is the only exclude file git honors. Any fix that just redirects the write to the worktree's private git dir silently does nothing.

core.excludesFile scoped per-worktree does work. With extensions.worktreeConfig:

$ git config extensions.worktreeConfig true
$ git -C ../wt config --worktree core.excludesFile "$PWD/.git/worktrees/wt/info/exclude"
$ git -C ../wt status --short          # worktree: shielded
$ touch marker.txt && git status --short
?? marker.txt                          # main checkout: unaffected

Suggested fixes, roughly in order of preference

1. Scope the shield to the worktree via git config --worktree core.excludesFile <path> pointing at a private file, gated on extensions.worktreeConfig. Correct scope and correct lifetime (the config dies with the worktree). Caveats worth weighing: extensions.worktreeConfig is repo-wide state, it moves an existing core.excludesFile into the main worktree's config on first enable, and it would clobber a user's own per-worktree core.excludesFile — so it needs the same read-modify-write care the current helper already has.

2. If the shared file stays, make the block reversible. Fence it with markers and delete it on reclaim, e.g.

   # bmad-loop <run-id> — removed on reclaim
   /.claude/skills
   # end bmad-loop
   

   Claude Code writes its own runtime state into the same file behind a # claude-code-runtime marker, so the convention is already established there. This also gives Exclude helper's read-modify-write is unserialized: concurrent worktree provisioning silently loses patterns #381's interleaving a smaller blast radius.

3. Cheap mitigation, independent of the above: skip any pattern whose path already contains tracked files (git ls-files --error-unmatch <path>). For a tracked path the exclude cannot shield the files it names anyway — those are tracked, so git add -A stages them regardless — and its only real effect is hiding their untracked siblings. Dropping those patterns costs nothing and removes the surprising case entirely.

Happy to send a PR for whichever direction you prefer.

[coderabbitai]

🔗 Related PRs

#152 - fix(worktree): detach kept worktree so branch_per=run survives a kept failure (#138) [merged]
#155 - fix(worktree): survive the renderer-era bmad-dev-auto (BMAD-METHOD #2587/#2588) [open]
#182 - fix(worktree): degrade post-merge teardown failures instead of crashing the run (#139) [merged]
#233 - fix: report worktree_seed entries skipped as no-ops [merged]
#257 - feat(worktree): seed the absent children of an existing seed dir (#235) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[pbean]

Thank you for this @tjoignant — an unusually complete report, and the two things you verified before filing are what shaped the fix rather than just supporting it.

Specifically: your finding that a per-worktree info/exclude does not exist — that git only ever reads $GIT_COMMON_DIR/info/exclude — pre-empted the obvious wrong fix. Redirecting the write to .git/worktrees/<id>/info/exclude and stopping there looks correct, silently shields nothing, and would have shipped as a fix that quietly disabled the feature. Your marker.txt probe is the reason that didn't happen.

What shipped

Your option 1, in #385: the patterns go to a private <worktree gitdir>/info/exclude, activated with git config --worktree core.excludesFile <abs path>, gated on extensions.worktreeConfig. That gets both properties your report separated so cleanly — correct scope (the worktree only; the main checkout and siblings untouched) and correct lifetime (git worktree remove/prune deletes the whole per-worktree gitdir, taking the exclude and the config key pointing at it, so there is no remover to keep in step, which is what the old design lacked).

Three caveats you raised were taken as constraints on that option, not waived:

• The worktree-scoped core.excludesFile shadows an operator's own — git reads the key from the most specific scope and does not concatenate. Their file's lines are copied into the private exclude when it is created, falling back to git's documented $XDG_CONFIG_HOME/git/ignore.
• extensions.worktreeConfig is a permanent repo-format change (git < 2.20 refuses a repo carrying it). It is refused outright in the two shapes git's own docs say must be hand-migrated first (core.bare = true or core.worktree in the shared config); the shield degrades and the run continues unshielded rather than the repo getting rearranged behind the operator's back.
• The shared .git/info/exclude is never written again on any path. Every refusal or fault skips the shield and journals a reason — a fallback to the old behavior would reintroduce this bug.

Your option 3 (skip patterns whose path already contains tracked files) isn't needed once the scope is right, and option 2's marker fencing would have kept a remover to maintain.

The half your report is really about

Fixing the writer does nothing for repos already carrying the lines — including yours. Nothing removes them, and they keep hiding new files under those paths from git add -A indefinitely. #386 adds a bmad-loop validate warning (git.exclude-legacy-pollution) that names the file and the exact lines:

/repo/.git/info/exclude carries git-add shield patterns written by an older bmad-loop:
/.claude/skills, /_bmad/custom — new files under those paths never appear in `git status`
or `git add -A` in this checkout, however long ago the run that wrote them finished.

Warn only — it never removes them. A project that genuinely wants /.claude/skills ignored writes the byte-identical line, and after the fact the two are indistinguishable, so deleting one is a call only you can make. For the same reason only exact matches are reported: /.claude/skills-mine, a bare .claude/skills, or a ! negation are your lines, not ours.

For your repo the immediate remedy is still manual: delete those lines from .git/info/exclude, then git status will show the files that have been hidden. Given 51 went unstaged, git add -A after that is worth reviewing carefully rather than committing blind.

Both PRs are open (#386 stacked on #385).