investigate: migrate agent-almanac repo to WSL2 ext4 filesystem for git performance

[pjt222]

Summary

Git operations (git status, git diff, git stash, git push) are significantly slow on the current NTFS-mounted path (/mnt/d/dev/p/agent-almanac/). With ~850 tracked .webp icon files, every git status requires ~850 stat() calls across the WSL2 9P bridge, causing multi-minute hangs. Moving the repo to the native WSL2 ext4 filesystem (~/dev/ or similar) would provide 10-50x faster I/O for all git operations.

This is a filesystem-level change that requires careful investigation before execution. Data loss or broken symlinks are real risks.

Findings

1. [HIGH] git status takes 30-60+ seconds on NTFS due to stat() overhead across 850+ icon files
2. [HIGH] git stash / git checkout hang for minutes because they write binary files to NTFS
3. [MEDIUM] git push with large changesets (100+ files) is unpredictably slow
4. [LOW] Git LFS was considered but would only help stash/push, not the core stat() bottleneck

Investigation Items (do before any migration)

• Audit all hardcoded paths referencing /mnt/d/dev/p/agent-almanac/ — CLAUDE.md files, symlinks, scripts, hooks, MCP server configs
• Inventory cross-project references from the parent /mnt/d/dev/p/ directory (20+ sibling projects may reference agent-almanac)
• Check global symlinks: ~/.claude/agents/ and ~/.claude/skills/* currently point to /mnt/d/dev/p/agent-almanac/...
• Verify ext4 storage capacity — the repo with icons is ~500MB+; check available space on WSL2 vhdx
• Test IDE access — VS Code/JetBrains accessing files on ext4 vs NTFS (WSL remote extensions handle this, but verify)
• Test MCP server paths — r-mcptools and hf-mcp-server configs may reference NTFS paths
• Evaluate hybrid approach: repo on ext4, symlink from /mnt/d/dev/p/agent-almanac for compatibility
• Check if Windows-side tools (GitHub Desktop, Explorer) need NTFS access to the repo
• Document rollback procedure before attempting any migration

Acceptance Criteria

• All investigation items above are completed and documented
• A migration plan is written with explicit steps, rollback procedure, and verification checklist
• No migration is attempted until the plan is reviewed and approved
• After migration (if approved): git status completes in <2 seconds, all symlinks work, all MCP servers connect, all hooks fire

Risk Assessment

Risk	Severity	Mitigation
Broken global symlinks (~267 skill + agent symlinks)	HIGH	Audit and rebuild script ready before migration
Broken MCP server paths	HIGH	Update configs in ~/.claude/settings.json and claude_desktop_config.json
Lost uncommitted work	CRITICAL	Ensure clean working tree, full backup before any move
Parent CLAUDE.md references break	MEDIUM	Update /mnt/d/dev/p/CLAUDE.md paths
Windows-side tool access lost	LOW	Evaluate if any Windows tools need direct NTFS access
WSL2 vhdx disk space	MEDIUM	Check available space first

Context

Discovered during icon pipeline audit and team-based bugfix session on 2026-04-01. Multiple git operations ran to background or hung during the session. The repo has grown from a docs-only project to include ~850 rendered icon files across 9 palettes.

Related: #168 (renv hangs on WSL/NTFS — same root cause)

[pjt222]

Investigation Complete — Migration Recommended

Performance Baseline (confirmed)

Metric	Current (NTFS)	Expected (ext4)
git status	13.7s (4.3s sys)	<1s
Tracked .webp files	7,779 (not 850 as estimated)	Same, but stat() is local
Repo size	1.2GB	Same

The 7,779 binary files are 10x the original estimate — every stat() call crosses the WSL2 9P bridge.

Investigation Items — All Completed

1. Hardcoded path audit: 19 CLAUDE.md files reference /mnt/d/dev/p/agent-almanac/:

• /mnt/d/dev/p/CLAUDE.md (parent)
• 18 sibling project CLAUDE.md files (agent-almanac-companion, jigsawR, putior, mediforce, etc.)

2. Global symlinks: 344 total

• ~/.claude/agents → /mnt/d/dev/p/agent-almanac/agents (1 directory symlink)
• ~/.claude/skills/* → 343 individual skill symlinks

3. ext4 storage: 861GB free — repo is 1.2GB, no concern

4. MCP servers: r-mcptools uses Windows R path (C:\Program Files\R\...), not affected by repo location. hf-mcp-server uses npm mcp-remote, not affected.

5. Cross-filesystem symlinks: Within WSL, a symlink at /mnt/d/dev/p/agent-almanac → ~/dev/agent-almanac works for all WSL tools. Windows-side tools (Explorer, GitHub Desktop) will NOT follow it — they'd need \\wsl$\Ubuntu\home\phtho\dev\agent-almanac\.

6. IDE access: VS Code Remote WSL extension handles ext4 paths natively. No issue expected.

Migration Plan

Phase 1: Prepare (5 min)

cd /mnt/d/dev/p/agent-almanac
git status  # confirm clean
bash scripts/validate-integrity.sh  # confirm baseline
mkdir -p ~/dev

Phase 2: Copy (2-5 min)

cp -a /mnt/d/dev/p/agent-almanac ~/dev/agent-almanac
cd ~/dev/agent-almanac && git status  # verify <2s
git log --oneline -5  # verify history intact

Phase 3: Update symlinks (2 min)

# Agents
rm ~/.claude/agents
ln -s ~/dev/agent-almanac/agents ~/.claude/agents

# Skills (rebuild all 343)
rm ~/.claude/skills/*
for dir in ~/dev/agent-almanac/skills/*/; do
  skill=$(basename "$dir")
  [ -f "$dir/SKILL.md" ] && ln -s "$dir" ~/.claude/skills/"$skill"
done

Phase 4: Compatibility symlink (after removing old dir)

rm -rf /mnt/d/dev/p/agent-almanac  # WARNING: destructive
ln -s ~/dev/agent-almanac /mnt/d/dev/p/agent-almanac

This preserves the old path for all WSL-side references (19 CLAUDE.md files, parent CLAUDE.md). No CLAUDE.md edits needed if the symlink works.

Phase 5: Verify

cd ~/dev/agent-almanac && time git status  # <2s
bash scripts/validate-integrity.sh  # all checks pass
ls -la ~/.claude/agents/  # resolves
ls -la ~/.claude/skills/commit-changes  # resolves

Rollback (if anything breaks)

rm /mnt/d/dev/p/agent-almanac  # remove symlink
cp -a ~/dev/agent-almanac /mnt/d/dev/p/agent-almanac  # restore
# Rebuild symlinks pointing back to /mnt/d/dev/p/agent-almanac

Risks Updated

Risk	Severity	Mitigation
Windows tools lose direct access	LOW	Use \\wsl$\Ubuntu\home\phtho\dev\agent-almanac\ or the NTFS symlink
Compatibility symlink doesn't work for all WSL tools	MEDIUM	Test thoroughly before deleting old dir; keep backup
7,779 .webp files slow the copy	LOW	cp -a handles this fine, just takes 2-5 min
CLAUDE.md paths break	LOW	Compatibility symlink preserves old path

Also fixes: #168 (renv hang on WSL/NTFS) — same 9P root cause.

Recommendation

Proceed with migration in a dedicated session. The compatibility symlink approach means zero CLAUDE.md edits. Total time: ~15 minutes including verification.