Authored by Claude Opus 4.7 (Claude Code). Session 86b7a3a0-7b14-4bd1-b707-52c5741aaeeb.

Resolves #10591

Extends bootstrapWorktree.mjs with a per-file symlink primitive — symlinkGitignoredFiles() + GITIGNORED_FILES_TO_LINK allowlist — so gitignored single files outside .neo-ai-data/ (initial member: resources/content/sandman_handoff.md) can be symlinked from canonical → other clones under the same --link-data flag the data-subdir symlink uses.

Once Sandman runs reliably on a per-cycle cadence, all three trio members read the same handoff file at boot per AGENTS_STARTUP.md §6 step 4 — closing the cross-clone strategic-priming asymmetry @tobiu surfaced in the post-merge handoff for Epic #10311.

Deltas from ticket

None. All seven ACs satisfied:

• (AC1) GITIGNORED_FILES_TO_LINK constant exported with initial entry resources/content/sandman_handoff.md.
• (AC2) symlinkGitignoredFiles() exported. Per-file action map: {linked, alreadyLinked, skippedNoSource, skippedRealFile, mainCheckout}. Same mainCheckout short-circuit as symlinkDataDir.
• (AC3) CLI under --link-data invokes symlinkGitignoredFiles() after symlinkDataDir(). Summary line appended (File symlink: N linked, N already-linked, N skipped-no-source, N skipped-real-file).
• (AC4) Idempotency verified empirically + via test: re-running --link-data reports 'already-linked' on cycle 2.
• (AC5) Graceful absent-source verified: when canonical lacks the file (pre-Sandman state), reports skipped-no-source: 1 without erroring.
• (AC6) File-head JSDoc extended: new "Symlinking gitignored SINGLE FILES (per #10591)" sub-section explains the cross-clone substrate-unification rationale + sets the resources/content/-tracked-parent constraint as load-bearing. Plus @see cross-reference to #10591.
• (AC7) Test coverage: new #10591 symlinkGitignoredFiles (granular per-file) describe block in test/playwright/unit/ai/scripts/bootstrapWorktree.spec.mjs with 6 tests covering all 5 per-file states + the mainCheckout no-op + the load-bearing GITIGNORED_FILES_TO_LINK invariants.

Test Evidence

$ npx playwright test test/playwright/unit/ai/scripts/bootstrapWorktree.spec.mjs --reporter=line
  28 passed (1.2s)

22 existing tests + 6 new for #10591.

Empirical end-to-end verification from this worktree:

$ node ai/scripts/bootstrapWorktree.mjs --link-data
... (data symlinks already-linked) ...
file-symlinked: resources/content/sandman_handoff.md → /Users/Shared/github/neomjs/neo/resources/content/sandman_handoff.md
✓ File symlink: 1 linked, 0 already-linked, 0 skipped-no-source, 0 skipped-real-file

$ node ai/scripts/bootstrapWorktree.mjs --link-data   # second run
file-symlink skip (already linked): resources/content/sandman_handoff.md
✓ File symlink: 0 linked, 1 already-linked, 0 skipped-no-source, 0 skipped-real-file

$ ls -la resources/content/sandman_handoff.md
lrwxr-xr-x ... resources/content/sandman_handoff.md -> /Users/Shared/github/neomjs/neo/resources/content/sandman_handoff.md

Cross-clone read coherence empirically confirmed: my worktree now reads the same handoff content as canonical.

Post-Merge Validation

• Each trio member runs node ai/scripts/bootstrapWorktree.mjs --link-data from their respective clones (Antigravity-Gemini and Codex-GPT need --canonical-root <path> per #10435 since they're independent clones, not git worktrees).
• view_file resources/content/sandman_handoff.md succeeds from each clone.
• On next operator-triggered runSandman.mjs, all three trio members see the refreshed handoff at boot.

Cross-family mandate

Code change with runtime impact (extends a script that operators run during worktree bootstrap). Cross-family Approved review required for merge eligibility per .agents/skills/pull-request/references/pull-request-workflow.md §6.1. Single-peer review request follows.

Provenance

• Empirical anchor: @tobiu's post-merge handoff message (no public artifact reference; in-session A2A) — surfaced the cross-clone gap immediately after #10588 #10589 #10590 merged.
• Architectural lineage: #10095 (bootstrapWorktree origin) → #10432 (per-subdir granular refinement) → #10435 (independent-clone topology) → #10591 (per-file extension, this PR).
• Parent epic: #10311 Institutionalizing Swarm Autonomy — heartbeat substrate. This PR is a parallel enabler: even before the heartbeat fully shipped, cross-clone handoff visibility is independently valuable.

🤖 Generated with Claude Code