Complete two-root path separation (supersedes #103)

[virtualian]

Summary

Focused refactor completing the CLAUDE_CONFIG_DIR + PAI_DIR two-root separation. This PR supersedes #103 and is intentionally narrow: 20 files, +136/-128, all in the hooks layer plus the release README and one SYSTEM doc.

Background — why this replaces #103

Issue #100's two-root split landed on main in two pieces:

1. PR Implement CLAUDE_CONFIG_DIR + PAI_DIR two-root separation #101 squash-merged 4 commits from branch 100-claude-config-dir-pai-dir-separation. That squash silently bundled ebc8130, which also deleted ~606 lines of unrelated functionality: CorrectionMode fast-path, BehavioralSignal capture, and loadLatestSynthesis. No one noticed during review because the deletions were hidden inside a 400-file "refactor" commit.
2. PR Restore CorrectionMode fast-path and loadLatestSynthesis (hotfix) #104 (the hotfix) restored those 606 lines as a narrow 2-file PR.
3. PR Add CI symbol guard for critical hook files #105 added a CI symbol-presence guard to make silent deletions of those subsystems impossible in future PRs.

After #101, #104, and #105, PR #103's semantic delta collapsed from 403 files / +1712/-1658 (merge-base relative) to the 18-file correction set that genuinely differs from post-hotfix main. GitHub's PR UI couldn't show this because the merge base hadn't moved. #103 is also CONFLICTING — a naive rebase produces phantom conflicts because git's patch-ID matching cannot resolve the ebc8130 hunks against #101's squash.

This PR is the rebased outcome, produced via file-copy reconstruction + the 3 cleanup decisions documented below.

What this PR does

1. Path-separation fixes (18 files from #103's correction commits)

All of these are corrections to bugs introduced or left behind by ebc8130:

• settings.json — revert 13 hook command paths from ${CLAUDE_CONFIG_DIR}/hooks/* back to ${PAI_DIR}/hooks/*. Hooks physically live under PAI_DIR after the split.
• paths.ts — getHooksDir() now returns codePath('hooks') (not configPath('hooks')). Docstring rewrites for the two-root contract.
• LoadContext.hook.ts — eliminate the paiDir parameter chain across 5 helpers. 5 raw join(paiDir, ...) calls routed through codePath(). Rename misleading loadSettings parameter. Extract sessionProgressPath.
• UpdateCounts.ts — countHooks and refreshUsageCache now read MEMORY from the PAI root. After Implement CLAUDE_CONFIG_DIR + PAI_DIR two-root separation #101's MEMORY move, the CONFIG-root reads silently returned empty data.
• RelationshipMemory.hook.ts — ensureRelationshipDir fixed for the split.
• LastResponseCache.hook.ts — mkdirSync before writeFileSync (silent ENOENT on fresh install).
• prd-utils.ts — correct .replace() prefix from configPath to codePath.
• VoiceCompletion.hook.ts — replace hardcoded ~/.claude/settings.json with getSettingsPath().
• VoiceNotification.ts, tab-setter.ts — drop dead configPath imports.
• DocCrossRefIntegrity.ts, change-detection.ts, identity.ts, notifications.ts, SessionCleanup.hook.ts, KittyEnvPersist.hook.ts, WorkCompletionLearning.hook.ts — small codePath / configPath cleanups.
• .pai-protected.json — correct stale comment.

2. Delete paiPath() alias outright

paths.ts previously kept paiPath() as a deprecated alias for codePath() to preserve backward compatibility. This PR removes it entirely.

Rationale. The semantic flip in v4.0.3 (pre-split paiPath(x) → ~/.claude/x, post-split paiPath(x) → ~/.pai/x) is exactly the class of change where a silent alias is a landmine, not a safety net. A caller that survives the grep would silently write to a different directory, and the failure mode is "files appear in an unexpected location" — one of the worst bugs to diagnose. Deleting the function forces the compiler to catch any revenant caller. Zero code callers existed when this commit was written.

SYSTEM_USER_EXTENDABILITY.md had 4 documentation examples using paiPath() — those are updated to codePath() in the same commit so the documentation matches the public API.

3. MEMORY migration release note

Releases/v4.0.3+/README.md gains a "Breaking Changes" subsection explaining the two-root split and — crucially — a required manual migration step for v4.0.2 upgraders:

if [ -d ~/.claude/MEMORY ]; then
  mkdir -p ~/.pai
  mv ~/.claude/MEMORY ~/.pai/MEMORY
fi

This is a deliberate decision to ship the migration as documentation + manual command rather than as automated installer logic. Reasoning:

• The current user base is solo (myself) plus whoever forks from here. A release-note + explicit command is sufficient coverage without adding installer complexity under time pressure.
• An automated migrator belongs in a focused follow-up PR that can be reviewed on its own merits (idempotency, error handling, rollback semantics) rather than bundled inside a refactor.
• I will open a tracking issue immediately after this PR for the automator work.

What this PR does not do (deliberately deferred)

• statusLine.command still points at ${CLAUDE_CONFIG_DIR}/statusline-command.sh. The physical script lives at ~/.claude/statusline-command.sh. Relocating it under PAI_DIR is a one-file move + one settings line + one installer template update — a valid change, but it doesn't belong inside this refactor because it's a separate decision about which root owns the statusline script. Tracked as a follow-up.
• Automated MEMORY migrator — see above, covered by a follow-up issue.

Verification

Run against this commit locally before pushing:

• ✅ bun build --target=bun clean on all 17 touched hook TypeScript files (paths.ts, prd-utils.ts, LoadContext.hook.ts, LastResponseCache.hook.ts, VoiceCompletion.hook.ts, RelationshipMemory.hook.ts, WorkCompletionLearning.hook.ts, KittyEnvPersist.hook.ts, SessionCleanup.hook.ts, learning-readback.ts, tab-setter.ts, change-detection.ts, identity.ts, notifications.ts, UpdateCounts.ts, VoiceNotification.ts, DocCrossRefIntegrity.ts)
• ✅ settings.json parses as valid JSON
• ✅ Env-var resolution test (CLAUDE_CONFIG_DIR=/tmp/ctest PAI_DIR=/tmp/ptest): 10/10 assertions pass — getConfigDir(), getPaiDir(), configPath('hooks'), codePath('MEMORY'), codePath('PAI','Tools'), getSettingsPath(), getHooksDir(), getMemoryDir(), getSkillsDir() all resolve to the expected roots
• ✅ settings.json hook-command audit: 0 references to ${CLAUDE_CONFIG_DIR}/hooks, 24 references to ${PAI_DIR}/hooks
• ✅ MEMORY routing audit: 0 configPath('MEMORY', 45 codePath('MEMORY', 0 raw ~/.claude/MEMORY references in hook sources
• ✅ paiPath search in Releases/v4.0.3+/: zero matches after deletion + doc substitution
• ✅ CI symbol guard (from merged Add CI symbol guard for critical hook files #105) passes all 13 required-symbol checks against this commit

Next for the #100 series

1. Close CLAUDE_CONFIG_DIR + PAI_DIR two-root split (v4.0.3+) #103 with a comment pointing at this PR.
2. Open a tracking issue for the automated MEMORY migrator (will reference this PR's documentation-only approach as the temporary measure).
3. Leave the statusLine.command relocation and the ebc8130 scope-creep post-mortem for separate follow-ups — neither belongs in this refactor.