feat: v5.2.3 — zero-friction install + automatic worktree support

[emredursun]

Summary

• v5.2.2: Remove .claude/commands/ git tracking — bridge files are now local-only. Adds cleanupLegacyClaudeTracking() migration for existing installs. Users no longer see confusing local changes after kit init.
• v5.2.3: Automatic worktree support via .worktreeinclude + post-checkout hook. Kit workflows work seamlessly in git worktrees without manual re-initialization.
• Documentation updated across README, architecture, CLI reference, IDE support, CHANGELOG, CheatSheet, help.md, and manifest.

Key Changes

• New lib/worktree.js module with generateWorktreeInclude() and installPostCheckoutHook()
• IDE_BRIDGE_DIRS constant in lib/constants.js for shared bridge directory mapping
• --skip-worktree CLI flag for opt-out
• Hook uses cp -RP for symlink safety, provenance markers for idempotent operation
• 15 new worktree tests, all 1000 tests passing

Test plan

• All 1000 tests passing (npx vitest run)
• Version sync tests green (package.json, manifest, CheatSheet, help.md, architecture.md, package-lock.json)
• Manual: npx @devran-ai/kit init in fresh project — no unexpected local changes
• Manual: git worktree add — verify .agent/ and bridge dirs auto-copied
• Manual: --skip-worktree flag skips worktree setup

[gemini-code-assist]

Code Review

This pull request updates Devran AI Kit to version 5.2.3, introducing automatic git worktree support via .worktreeinclude generation and a post-checkout hook. It also transitions IDE bridge files to be local-only, removing them from git tracking and cleaning up legacy .gitignore patterns. Review feedback recommends improving the robustness of the directory copying logic in the git hook to prevent potential nesting and suggests dynamically generating the list of bridge directories from existing constants to ensure consistency.

[gemini-code-assist]

The cp -RP command might behave unexpectedly if the .agent/ directory already exists in the destination (e.g., if it was partially created or exists due to a previous failed run). In some cp implementations, this could result in a nested .agent/.agent/ directory. It is safer to ensure the directory exists and then copy the contents using the /. source pattern, consistent with how bridge directories are handled below.

Suggested change

	' cp -RP "$MAIN_ROOT/.agent" .agent/ 2>/dev/null || true',
	' mkdir -p .agent 2>/dev/null',
	' cp -RP "$MAIN_ROOT/.agent/." .agent/ 2>/dev/null || true',

[gemini-code-assist]

The list of bridge directories is hardcoded here, which creates a maintenance burden and risk of drift if IDE_BRIDGE_DIRS in lib/constants.js is updated. It's better to generate this list dynamically from the IDE_BRIDGE_DIRS constant.

Suggested change

	' for dir in .claude/commands .cursor/commands .opencode/commands .windsurf/workflows .github/prompts; do',
	' for dir in ' + Object.values(IDE_BRIDGE_DIRS).map(d => d.replace(/\/$/, '')).join(' ') + '; do',

[emredursun]

🔧 ✅ PR Fix Complete

Findings addressed: 2 (0 human · 2 bot)
Commits: 1 · Verification: All 1000 tests passed

Fix Summary

#	Priority	Reviewer	File:Line	Finding	Fix Applied	Commit
1	P2 MEDIUM	@gemini-code-assist	lib/worktree.js:141	cp -RP may nest .agent/.agent/ if dir exists	Use mkdir -p .agent && cp -RP "$MAIN_ROOT/.agent/." .agent/ pattern	053fa3b
2	P2 MEDIUM	@gemini-code-assist	lib/worktree.js:144	Hardcoded bridge dirs — drift risk from IDE_BRIDGE_DIRS	Generate list dynamically from Object.values(IDE_BRIDGE_DIRS)	053fa3b

Diffs

Fix #1 — lib/worktree.js:141 (@gemini-code-assist: "cp -RP might nest .agent/.agent/")

-    '    cp -RP "$MAIN_ROOT/.agent" .agent/ 2>/dev/null || true',
+    '    mkdir -p .agent 2>/dev/null',
+    '    cp -RP "$MAIN_ROOT/.agent/." .agent/ 2>/dev/null || true',

Fix #2 — lib/worktree.js:144 (@gemini-code-assist: "hardcoded bridge dirs — drift risk")

-    '  for dir in .claude/commands .cursor/commands .opencode/commands .windsurf/workflows .github/prompts; do',
+    '  for dir in ' + Object.values(IDE_BRIDGE_DIRS).map(d => d.replace(/\/$/, '')).join(' ') + '; do',

Verification

Gate	Status
Tests	✅ 1000/1000 passed
Version Sync	✅ All versioned files in sync (5.2.3)

Next: Ready for merge. Bots re-analyze automatically on push.