Bootstrap-BareRepo.ps1 for fresh-clone onboarding (#420)

[PolyphonyRequiem]

Summary

Closes #420.

Adds scripts/Bootstrap-BareRepo.ps1, the sister script to Migrate-ToBareRepo.ps1. Migrate converts an existing operator clone; Bootstrap starts from nothing and produces the canonical bare-repo + per-run-worktree layout in a single step.

This closes a long-standing onboarding gap: the polyphony-bootstrap skill checklist and docs/onboarding-guide.md § 2 both assumed the operator already had a normal clone they could migrate. Fresh onboardings ("clone a repo for the first time and set it up bare") had to follow the manual recipe in docs/per-run-worktree-layout.md — and that recipe trips on safe.bareRepository=explicit on Windows unless the operator already knows the --git-dir workaround.

Signature

Bootstrap-BareRepo.ps1 -RemoteUrl <url>
  [-ParentDir <path>]   # default: ~/projects
  [-RepoName <name>]    # default: derived from URL leaf
  [-MainBranch <name>]  # default: remote HEAD (queried post-clone)
  [-Commit]             # default: dry-run

Design highlights

State classification up front. Every invocation computes one of full_bootstrap | recover_missing_main | recover_missing_runs | already_bootstrapped | refused before doing anything destructive. Dry-run prints the classification + the plan. Tests assert each classification's output.

Idempotency. Re-running on a canonical layout is a no-op success. Narrow partial-state recovery is supported:

• bare present + main missing → git fetch --prune origin then add the missing worktree on the bare's HEAD branch
• bare + main present + runs missing → mkdir the runs root

Both recovery paths are gated on the existing bare's origin URL matching -RemoteUrl (conservative normalization: strip trailing / and trailing .git, case-insensitive; does not equate https with ssh forms).

Identity verification. Main-worktree validity is double-checked: git -C $main rev-parse --path-format=absolute --git-common-dir must point at the bare, AND the bare's worktree list --porcelain must include the main path. Both directions must agree.

Refusals (exit 3, no -Force override).

• bare path exists but isn't a bare repo
• existing bare has no origin or a mismatched origin
• main path exists but isn't backed by our bare
• target branch is already checked out in another worktree
• remote is empty / unborn HEAD (refuse before worktree add so the error is clear)
• runs path exists but isn't a directory

There is no -Force switch — unlike Migrate-ToBareRepo there's no legacy-clone-preserved fallback that would justify bypassing identity checks.

Windows safety. Every probe against the bare uses git --git-dir=<bare> rather than git -C <bare>. Works under git config --global safe.bareRepository explicit (the global default on my box, and the upstream-recommended hardening).

Tests

31 Pester tests in scripts/Bootstrap-BareRepo.Tests.ps1, real git init in temp directories — no mocks for git itself. Mirrors the pattern in Migrate-ToBareRepo.Tests.ps1. Covers:

• URL parsing: https / https with .git / https with trailing / / git@host: ssh shortcut / ssh:// / ADO /_git/ / Windows file paths / empty
• Test-RemoteUrlMatch equivalence (positive + negative cases, including the deliberate https-vs-ssh non-equivalence)
• Happy path: full bootstrap creates bare + main + runs
• Parent dir is created if missing
• RepoName derivation when -RepoName is omitted
• Non-main default branch detection (master)
• Explicit -MainBranch override beats auto-detect (develop)
• Idempotency: re-run reports "already bootstrapped"
• Recovery: missing main worktree
• Recovery: missing runs root
• Refusal: pre-existing non-bare at bare path
• Refusal: existing bare with mismatched origin
• Refusal: main path exists but isn't a worktree
• Refusal: target branch already checked out elsewhere
• Refusal: empty/unborn remote
• Dry-run: prints plan, creates nothing, classifies correctly
• Preflight: RepoName with path separators, ParentDir pointing at a file

All 31 pass locally (~40s).

Other wiring

• install.ps1 — added to both the download loop and the $expectedLaunchers verification list so it lands in ~/.polyphony/bin/ alongside the rest.
• .github/skills/polyphony-bootstrap/SKILL.md § 2 — one-line addition pointing at Bootstrap-BareRepo.ps1 for the fresh-clone case (and at Migrate-ToBareRepo.ps1 for the existing-clone case).
• docs/onboarding-guide.md § 2 — new "Fresh clone (no existing local checkout)" subsection with the canonical invocation and a note about safe.bareRepository=explicit.

Out of scope

• Friction-report items feat: Phase Detection, Routing Engine, and Command Implementations (PG-3) AB#2593 AB#2594 #2–[PG-2] Phase Detection Engine #9 are tracked separately under the parent Epic: First-run friction for newly-onboarded repos (May 2026 dogfood) #414 epic.
• No workflow YAML changes; no C# changes; no version bumps.

Verification

• 31/31 Pester tests pass locally.
• No conductor / jinja / version-drift lints touched (the change is launcher + docs only).
• install.ps1 is structurally unchanged — same loop, one extra string in two lists.