Pack commands never staged into ~/.pai/commands/ — #113 migration has no source path

[virtualian]

Context

Follow-up surfaced during 2026-04-20 runtime-sync work.

engine/command-migration.ts from #113 converts ~/.claude/commands/<name>.md into symlinks pointing at ~/.pai/commands/<name>.md, treating ~/.pai/commands/ as the single source of truth. The module's ownership rule: if ~/.pai/commands/<name>.md does not exist, the corresponding ~/.claude/commands/<name>.md is treated as third-party and skipped.

This assumes pack installers populate ~/.pai/commands/ with their canonical command sources before command-migration runs. No such populator exists today.

Evidence on this laptop (2026-04-20)

• ~/.pai/commands/ — absent entirely.
• ~/.claude/commands/ — contains one real file: context-search.md, mtime 19 Mar.
• Repo source: Packs/ContextSearch/src/commands/ contains both context-search.md and cs.md. The runtime has neither, symlinked nor canonical — and cs.md is missing entirely.

So even with #113 closed, command-migration is a no-op on this laptop: no source for it to consume, no symlinks produced, and pack-added commands (cs.md) never reach the runtime at all. The context-search.md file sitting in ~/.claude/commands/ today was placed there by an older pack-install wizard at original install time and has been drifting since; #113's symlink scheme never touched it.

Problem

Two distinct gaps:

1. Canonical staging — ~/.pai/commands/<name>.md must be populated from Packs/<Pack>/src/commands/<name>.md before migratePerPackCommands can do anything useful. Today nothing does this.
2. Orphaned runtime file — existing ~/.claude/commands/<name>.md files that were placed there by pre-Slash commands forgotten by two-root architecture: no ~/.pai/commands/, installer never sees them, /cs missing on disk #113 pack-install wizards never migrate, because the ownership rule requires a ~/.pai/commands/ counterpart that was never created.

Scope (investigation)

Mechanism (or mechanisms) to bring runtime ~/.pai/commands/ into alignment with Packs/<Pack>/src/commands/ for PAI-owned packs. Candidate shapes:

1. Per-pack installer populates ~/.pai/commands/<name>.md from Packs/<Pack>/src/commands/ on install/upgrade, then command-migration takes over.
2. Extend command-migration to accept Packs/<Pack>/src/commands/ as fallback source when ~/.pai/commands/<name>.md is absent.
3. Sync tool invoked explicitly on demand.
4. Something else the investigation surfaces.

Acceptance

• ~/.pai/commands/ is populated with all pack-owned commands from Packs/<Pack>/src/commands/.
• ~/.claude/commands/<name>.md ends up as a symlink to ~/.pai/commands/<name>.md for all PAI-owned commands.
• Third-party commands preserved untouched.
• Idempotent, soft-fail per command.

Related

• Slash commands forgotten by two-root architecture: no ~/.pai/commands/, installer never sees them, /cs missing on disk #113 — commands canonicalisation (closed); its migration logic is correct but has no upstream source populator.
• Skills separation is documentation-only: Claude Code harness reads ~/.claude/skills/, not ~/.pai/skills/ #110 — skill canonicalisation (closed); analogue on the skills side, suffers from the same drift-vs-repo issue (Resync Research and Learning pack sources into ~/.pai/skills/ runtime #145).
• Resync Research and Learning pack sources into ~/.pai/skills/ runtime #145 — Resync Research and Learning pack sources into ~/.pai/skills/.
• Investigate: restructure two-root split to simplify absorbing upstream releases #144 — Upstream-absorption investigation. Same multi-copy drift family of problems.

Out of scope

• Implementation.