fix(gh): enforce peer roots for Base-created worktrees #2635

Goal

Ensure every Base-supported worktree creation path keeps implementation and review worktrees outside the primary repository root, using the canonical peer-directory layout.

Background

Base's normal convention is:

../<repo>-worktrees/<slug>

However, explicit or older worktree creation paths can produce layouts such as:

~/work/base-cli/base-cli-worktrees/<slug>

A nested linked worktree is independently isolated at the Git level, but its directory is visible to the primary checkout as an untracked path. That makes the primary checkout appear dirty and can unnecessarily block basectl workspace update.

Nine nested base-cli worktrees were relocated to the peer directory on 2026-10-30. This issue adds creation-time guardrails so the problem does not recur.

Related work:

• fix(workspace): separate blocked roots from pull failures and nested worktrees #2633/fix(workspace): distinguish blocked roots from pull failures #2634: distinguish workspace-update blocked roots from Git pull failures and filter registered nested worktree paths during status inspection.
• feat(gh): surface and automate worktree hygiene #2575: surface and automate worktree hygiene.
• feat(gh): use detached review worktrees and prune review refs #2623: detached review worktrees and review-ref cleanup.

Scope

• Add one canonical path-containment validator for Base-owned worktree creation.
• Keep default issue and review worktree roots as sibling directories next to the primary checkout.
• Reject any requested worktree root that resolves to the repository root or a descendant, including symlinked paths, before Git or network mutation.
• Apply the validator to issue/worktree creation and review-fetch --root handling.
• Ensure future stack worktree materialization uses the same validator.
• Add diagnostics and remediation guidance for pre-existing nested linked worktrees without moving or deleting them automatically.
• Update generated guidance and command documentation where necessary.
• Add focused unit, BATS, and real-Git integration coverage.

Acceptance Criteria

• Base-supported creation commands never create a worktree inside its primary repository.
• The default issue-worktree path is ../<repo>-worktrees/<slug>.
• The default review-worktree path is ../<repo>-review-worktrees/pr-<number>-<slug>.
• Explicit nested roots fail before any GitHub fetch, ref creation, or worktree creation.
• Symlink and canonical-path containment cases are covered.
• Existing nested worktrees are reported with their exact path and a safe git worktree move remediation, but are not moved, deleted, stashed, reset, or switched automatically.
• A clean primary checkout with peer linked worktrees remains eligible for basectl workspace update.
• Genuine primary-checkout changes continue to block updates and are reported as such.
• The published command/help and test contracts remain valid.

Validation

Run the focused worktree and workspace-update tests, real-Git nested-worktree integration fixtures, command/help and schema contracts, git diff --check, and the repository validation gate.

Non-Goals

• Do not automatically migrate existing worktrees.
• Do not delete worktrees, branches, or stale Git metadata.
• Do not change issue branch naming or PR merge policy.
• Do not make raw manual git worktree add invocations enforceable outside Base.
• Do not merge or reset the primary workspace checkouts.

Project Fields

• Status: In Progress
• Priority: P1
• Area: CLI
• Initiative: Workspace Handling
• Size: M
• Category: bug

Agent Assignment

Assignee: codeforester. Use the canonical issue-backed worktree. Preserve user-owned primary-checkout changes and open a reviewable PR without merging it.