Declare a project-wide git version floor and move the shield's 2.20 gate into validate

[pbean]

Raised while triaging a #385 review round, where the question "why not just require a newer git?" turned out to have a real answer that is separate from that round's finding.

Today

The project documents no git prerequisite version. The only floor that exists is local to the #384 shield — _WORKTREE_CONFIG_GIT = (2, 20) in src/bmad_loop/install.py, enforced at runtime by _git_version_at_least against git version, and described in docs/FEATURES.md and CHANGELOG.md as a property of the shield. README.md and docs/setup-guide.md name no version.

Why it is worth revisiting

Servicing the 2.20 floor is a standing tax on any change to that area, and most of it is invisible until you are in it:

• every git fact has to be measured at both 2.20.4 and current before it can be asserted, in Docker, non-root;
• flags cannot be used freely — --show-scope is 2.26, --type= is 2.18, GIT_CONFIG_COUNT is 2.31 — and per the --type= finding on fix(install): scope the worktree git-add shield per-worktree (#384) #385, a probe flag with its own version floor silently turns every rc-branch below it into a default rather than a gate;
• the version gate itself has to sit above the probes rather than next to the write it guards, purely because of that.

What raising it would NOT buy

Worth recording so this isn't mistaken for a fix to the round that prompted it: the command-scope override finding on #385 is not a version gap. command scope outranks worktree scope by documented design at every release including 2.55.0, the newest, and a newer floor would add injection channels (GIT_CONFIG_COUNT is 2.31) rather than remove them.

The real gains are narrower: --show-scope becomes usable for better diagnostics, and the dual-version measurement obligation goes away.

Shape

1. Pick a number — this needs checking what git the realistic target distros ship, not a guess.
2. Declare it in docs/setup-guide.md under platform prerequisites, and in README.md.
3. Add a validate preflight check for it (new id in checks.VALIDATE_CHECKS), so it is reported once at setup rather than as a per-run shield degrade.
4. Then the shield's own gate can be simplified, though probably not deleted — it guards a permanent, irreversible repo-format change, so refusing to make it on a git that cannot use it is worth keeping regardless of what the docs promise.

Deliberately not bundled into #385.

[coderabbitai]

🔗 Related PRs

#174 - fix(verify): git timeouts become GitError; rollback dirty check degrades instead of crashing the run (#156) [merged]
#237 - fix(verify): force LC_ALL=C at the git chokepoint so rollback stops matching English (#236) [merged]
#373 - fix(install): guard the worktree exclude's filesystem tail (#359) [merged]
#376 - fix(install): close the exclude helper's two residual holes (#374, #375) [merged]
#385 - fix(install): scope the worktree git-add shield per-worktree (#384) [open]

---

📝 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!