Investigate: restructure two-root split to simplify absorbing upstream releases

[virtualian]

Context

This fork runs a two-root split: ~/.claude/ = CC config, ~/.pai/ = PAI code. Upstream (danielmiessler/PAI) runs single-root: everything under ~/.claude/.

This asymmetry creates friction every time we absorb an upstream release or cherry. References to ~/.claude/<thing> in upstream-shaped source have to be translated per-occurrence to ~/.pai/<thing> in our layout — in hooks, skills, agents, docs, installer templates, and release-tree mirrors.

Recent evidence:

• Sweep: 433+ stale ~/.claude/ doc-text refs across ~/.pai/skills/ and ~/.pai/agents/ markdown #114 was scoped for 433+ doc-text refs; real repo-side surface turned out to be 16 across 5 files, with the runtime tree self-correcting on install — but only after manual sweep and classification work landed.
• Two-root separation incomplete: stale ~/.claude/PAI/ tree and residual ~/.claude/PAI/ references in canonical ~/.pai/PAI/ #108, Residual .claude/PAI literals in Releases/v4.0.3+/.claude/skills/ tree #116, Residual .claude/skills literals in Releases/v4.0.3+/.claude/skills/Agents/Tools/ComposeAgent.ts #129, PAI_DIR fallback drift: 9 files still fall back to ~/.claude instead of ~/.pai #130 — follow-on cleanups for residual ~/.claude/... literals missed during the initial split migration.
• Upstream sync: adopt recommended patches from 2026-03-18 scan #91, Bundle upstream cherries: statusline spacing + AlgorithmTab dead docs (#91 partial, #83 verified) #137 — upstream-sync bundles where per-occurrence translation was part of the review cost.

Problem

The split is an invariant we impose. Upstream doesn't know about it. Each upstream release carries references written in upstream's single-root worldview, and we pay translation cost proportional to release size — not because the semantics changed, but because the path strings disagree.

We want upstream absorption to be predominantly mechanical: apply the diff, let one boundary layer handle the translation, done. Not a bespoke per-file audit every time.

Possible directions (for investigation, non-exhaustive)

1. Canonical shape in repo = upstream's. Keep repo paths upstream-shaped under .claude/.... Installer translates to two-root at install time. Cherries apply as-is. Cost: any doc/comment text that doesn't go through the installer keeps the upstream worldview indefinitely, or we accept a post-install doc-rewrite pass.

2. Path-indirection layer. Replace literal path strings in source with an abstraction that resolves identically on both upstream and fork. Requires a naming convention, or a rewrite step at sync time.

3. Inverted canonical layout with sync-time rewriter. Keep .pai/... shape as source-of-truth in repo; translate upstream paths at sync time via scripted rewriter. Sync becomes automated rather than manual review. Cost: tooling to maintain and verify; round-trip cherries (upstream → us → upstream) become harder.

4. Plugin distribution (Investigate distributing PAI as a Claude Code plugin #102). Sidesteps the whole thing by exiting the ~/.claude/ namespace entirely. Long-term answer, scoped separately.

5. Hybrid / other framings the investigation surfaces.

Success criteria

• Absorbing a typical upstream release requires at most one translation pass, either automated or confined to a single well-defined boundary.
• Residual per-occurrence cleanup issues of the Two-root separation incomplete: stale ~/.claude/PAI/ tree and residual ~/.claude/PAI/ references in canonical ~/.pai/PAI/ #108 / Residual .claude/PAI literals in Releases/v4.0.3+/.claude/skills/ tree #116 / Residual .claude/skills literals in Releases/v4.0.3+/.claude/skills/Agents/Tools/ComposeAgent.ts #129 / PAI_DIR fallback drift: 9 files still fall back to ~/.claude instead of ~/.pai #130 shape stop happening for path divergence — they either disappear by design or are caught by tooling before merge.
• The chosen restructure remains compatible with Investigate distributing PAI as a Claude Code plugin #102 (plugin distribution) as a future step, so this work isn't thrown away if we later adopt the plugin model.
• The split's existing guarantees (two-root filesystem, PAI_DIR=~/.pai, CC config at ~/.claude/) are preserved at runtime.

Out of scope

• Implementation. This issue is investigation and recommendation.
• Memory-ownership concerns (System prompt memory instructions override PAI's own memory system #97, Investigate: Claude Code harness auto-memory directive still routes agent writes to per-cwd ~/.claude/projects/.../memory/, independent of Learning skill (plus runtime-drift on #109 Part 2) #140) — separate layer.
• Plugin distribution (Investigate distributing PAI as a Claude Code plugin #102) — complementary long-term track.

Prior art

• Separate PAI installation from CC config: CLAUDE_CONFIG_DIR + PAI_DIR=~/.pai #98 (closed) — two-root split umbrella.
• feat(UpstreamScan): expand scope to include file-level diffs across all four environments #88, Upstream sync: adopt recommended patches from 2026-03-18 scan #91, Bundle upstream cherries: statusline spacing + AlgorithmTab dead docs (#91 partial, #83 verified) #137 — recent upstream-sync bundles.
• Two-root separation incomplete: stale ~/.claude/PAI/ tree and residual ~/.claude/PAI/ references in canonical ~/.pai/PAI/ #108, Skills separation is documentation-only: Claude Code harness reads ~/.claude/skills/, not ~/.pai/skills/ #110, Slash commands forgotten by two-root architecture: no ~/.pai/commands/, installer never sees them, /cs missing on disk #113, Sweep: 433+ stale ~/.claude/ doc-text refs across ~/.pai/skills/ and ~/.pai/agents/ markdown #114, Residual .claude/PAI literals in Releases/v4.0.3+/.claude/skills/ tree #116, Residual .claude/skills literals in Releases/v4.0.3+/.claude/skills/Agents/Tools/ComposeAgent.ts #129, PAI_DIR fallback drift: 9 files still fall back to ~/.claude instead of ~/.pai #130 — post-split literal-sweep and canonicalisation work.
• Investigate distributing PAI as a Claude Code plugin #102 — PAI-as-plugin investigation.

[virtualian]

Concrete sighting — three stale copies on local runtime (2026-04-20)

A direct instance of the drift hazard this investigation addresses.

Running skill-migration (#110's engine/skill-migration.ts) on my laptop surfaced a three-stale-copies situation for the Research and Learning packs:

Copy	Path token convention	Voice pattern
~/.claude/skills/<Pack> (pre-#110 symlink, now the canonical winner)	~/.claude/MEMORY/... literals	"Workflow Announcement" (text-only, older style)
~/.pai/skills/<Pack> (pre-migration, now backed up)	${PAI_DIR}/MEMORY/... tokens (post-#114)	bun ~/.claude/PAI/Tools/Notify.ts ... invocations
Packs/<Pack>/src/ (repo, authoritative)	${PAI_DIR}/MEMORY/... tokens	bun ~/.pai/PAI/Tools/Notify.ts ... invocations (two-root-aware)

Each copy is one migration-step behind the next. The "CC side wins on drift" rule in #110 picked the most stale copy as canonical, which isn't a bug in the rule itself — it's a sign that the rule has no pointer to what "current" means. The authoritative reference (Packs/<Pack>/src/) isn't in the rule's input at all.

This is exactly the economic cost #144 names: upstream-shaped content changes (~/.claude/ literals, voice invocation locations) have to translate through intermediate runtimes, and each hop introduces a potential drift point. The three-copies situation is structural, not incidental — nothing was forcing the copies back into alignment.

Filed a companion issue for the runtime-side remediation: pack-resync mechanism that treats Packs/<Pack>/src/ as authority when both runtime copies are older than source. That issue is about operator runtime hygiene; this one (#144) is about absorbing upstream releases without creating these multi-copy situations in the first place. The two investigations are complementary — whichever restructure #144 converges on probably eliminates or simplifies the need for per-pack resync.