Authored by Claude Opus 4.7 (1M context) (Claude Code). Session b3c0bfb8-44e1-4646-9c62-110ef16b0fad.

Resolves #10435

Extends #10433's granular per-subdir symlinking to support independent clones (e.g., an Antigravity-side clone mirroring the canonical github-side clone) — same gitignore-boundary discipline, same per-subdir result map, same concepts/-protection invariant.

The Problem

bootstrapWorktree.mjs --link-data resolves canonical via git worktree list --porcelain, which works for git worktrees (the original #10095 use case). For independent clones — separate clones at sibling filesystem paths, not worktrees — git worktree list returns the clone itself, and the script correctly enters main-checkout mode (no-op). This left independent clones unable to opt into substrate unification through the script, despite needing the same architectural pattern.

Empirical anchor (2026-04-27): the antigravity/neomjs/neo clone had been hand-curated months ago with manual ln -s calls that mirror the exact #10433 pattern. When wake-daemon/ became a load-bearing subdir (per #10423/#10425), the clone needed it manually re-symlinked. This PR codifies what was previously hand-curated.

The Fix

• resolveMainCheckout(cwd, {explicitRoot}) accepts an optional explicitRoot parameter; returns it (path-resolved to absolute) when set, else falls through to the existing git-worktree-list logic.
• CLI mode supports --canonical-root <path> flag and NEO_AI_CANONICAL_ROOT env var (flag takes precedence).
• Per-subdir symlink logic (#10433's DATA_SUBDIRS_TO_LINK + symlinkDataDir) is already topology-agnostic — once canonical is resolved correctly, the existing logic does the right thing.
• File-head JSDoc broadened to enumerate the two supported topologies (worktrees vs independent clones) and link to #10435.

Usage

node ai/scripts/bootstrapWorktree.mjs --link-data

<h1 class="neo-h1" data-record-id="5">Independent-clone case (new)</h1>

node ai/scripts/bootstrapWorktree.mjs --link-data \\
    --canonical-root /Users/Shared/github/neomjs/neo

<h1 class="neo-h1" data-record-id="6">Or via env var (composable in CI / shell aliases)</h1>

NEO_AI_CANONICAL_ROOT=/Users/Shared/github/neomjs/neo \\
    node ai/scripts/bootstrapWorktree.mjs --link-data

What Stays Unchanged

• Worktree behavior (existing 21 tests pass without modification)
• concepts/-untouched invariant (worktree AND independent-clone cases)
• Per-subdir data-loss guard (force=false refuses to clobber non-symlink dirs)
• No DATA_FILES_TO_LINK allowlist (top-level memory-core.sqlite is unreferenced cruft per audit; symlinking it would propagate tech debt — see #10435 body)

Test Evidence

• 4 new tests for resolveMainCheckout explicit-root behavior:
  • returns explicitRoot verbatim when absolute
  • resolves a relative explicitRoot to absolute via path.resolve
  • falls through to git resolution when explicitRoot is undefined
  • falls through correctly on null/empty (boundary safety)
• 22/22 tests pass locally (5 existing config + 4 new for #10435 + 8 existing #10432 + 5 existing #10351)

Cross-Family Validation

@neo-gemini-pro (Antigravity) explicitly validated:

• Keep filename (option 1) over rename
• Add --canonical-root / NEO_AI_CANONICAL_ROOT as the right topological seam
• Recommendation: "file the ticket and sit on it; we don't need to implement instantly"

Implemented anyway since context budget allowed and the substrate now codifies what was previously hand-curated, removing the future per-clone manual-symlink ops burden.

Post-Merge Validation

• Run bootstrapWorktree.mjs --link-data --canonical-root <canonical> from an independent clone — expect per-subdir symlinks created
• concepts/ in the independent clone remains a regular dir (load-bearing safety check)
• Bridge daemon's PID-lock singleton enforcement now spans canonical+independent clones via the wake-daemon symlink

Out of Scope

• Renaming the script
• Sibling-clone heuristic auto-discovery via origin URL matching (too much magic)
• Migration tooling for already-curated independent clones
• Cleanup of unreferenced top-level memory-core.sqlite cruft (warrants its own tiny ticket if pursued)

Related

• Predecessor: #10433 (granular per-subdir symlinking — this extends to independent clones)
• Closed earlier predecessor: #10224 (coarse-grained parent-level symlink)
• Substrate-level coherence: #10424 (cross-process gap closed at substrate via #10433)
• Singleton enforcement that depends on wake-daemon/ symlinking: #10423, #10425

🤖 Generated with Claude Code