[roodboi]

Linear: HACK-1132 (WU19, unit F16). Scoped migration with preview, replacement verification and rollback.

Final behavior

New hack setup migrate subcommand. It moves one scope at a time from standalone Hack skill and rule files to the skills-only hack plugin (the #305 layout).

• Preview (default, read-only). Lists every standalone target in the selected scope (--path, --global, --all-scopes) and clients (--claude, --codex, --cursor; default all) with one action:

  • remove: Hack-owned (W11 classifier: current or known earlier render) and the replacement plugin is verified or explicitly skipped.
  • blocked: Hack-owned, but the replacement is not verified.
  • preserve: customized, unknown, or reached through a symlink. Each has a closed, value-free reason.
  • absent.

  Targets: the Codex hack-cli/hack-init skills, the Claude Code hack-init skill, the Cursor hack.mdc rule, and the shared ~/.ai/skills/hack-cli. The shared skill follows Claude Code or Codex.

• Replacement verification reads configuration only (src/agents/plugin-replacement.ts):

  • Claude Code: the nearest settings file must enable hack@hack-dance (project settings.local.json, then project settings.json, then user). ~/.claude/plugins/installed_plugins.json must also list an installed copy that carries the hack-cli and hack-init skills.
  • Codex: [plugins."hack@hack-dance"] enabled = true in the project or user config.toml.
  • The global scope counts only user-level configuration.
  • Cursor is not-inspectable, so it needs --skip-plugin-check cursor. --skip-plugin-check <clients> accepts claude, codex, cursor or all.

• --apply is all or nothing.

  • It refuses with exit 1 and writes nothing when any target is blocked, a scope root is unresolved, or a file can't be read for backup.
  • Otherwise it first commits a 0600 manifest under $HACK_HOME/agent-migrations/<id>.json. The write is fsynced, then renamed into place. The manifest holds the exact bytes, sha256 and mode of each file.
  • It then removes each file only if its bytes still match the backup. Removal uses the W11 owned-remove path, and an empty skill directory goes with its file.
  • A file edited in between is reported as changed and left in place, with exit 1.
  • When nothing is Hack-owned, apply writes no manifest.

• --rollback-manifest <manifest>:

  • Restores each entry into an empty path with exclusive create, then sets the recorded mode.
  • Never overwrites. Identical bytes are reported as already-present; anything else is conflict (exit 1) and left unchanged.
  • Idempotent, and it recovers an interrupted apply.
  • Refuses the whole manifest, restoring nothing, if any entry's path is not exactly a known target under its root, its digest does not match, or its bytes are not a Hack render for that target.

• Claude primer hooks, MCP entries and AGENTS.md/CLAUDE.md sections are never touched.

• --json returns the usual {ok, data} envelope. Messages never include file contents.

• setup-sync.ts now exports listOwnedFileTargets so migration and sync share one path/surface table.

Docs: docs/integrations.md (new "Migrate standalone files to the plugin" section, and the switching guidance now points to it), docs/cli.md, the tests/e2e/README.md freeze description, and a regenerated docs/reference/cli.md. No consumer guidance or render changes, so there are no fingerprint or revision updates.

Validation (local, macOS, source CLI)

• tests/plugin-migration.test.ts (15 tests). Temp project and HOME roots are passed explicitly, so the process HOME is never touched. Covered:
  • preview leaves hashes and modes byte-identical
  • blocked apply refuses with no writes
  • verified apply, then rollback restores exact bytes and mode; a second rollback reports already-present
  • incomplete Claude install copy
  • project-local disable overrides a user enable
  • Codex disabled, malformed and other-plugin configs
  • project-only config does not verify user-scope duplicates (all-scopes apply refused)
  • Cursor skip
  • client filtering
  • symlinked skill dir preserved
  • interrupted apply recovered by rollback
  • edit between backup and removal reported as changed
  • rollback conflict leaves the user file alone
  • tampered manifests (path, bytes, target, digest, non-Hack bytes) and a missing manifest refused with no writes
  • unresolved scope root refused
• tests/setup-migrate-command.test.ts (4 tests). Runs the source CLI through privateCliEnv with private HOME and HACK_HOME, and covers preview JSON, refused apply, skip-verified apply, rollback, flag conflicts and --skip-plugin-check parsing.
• Flag name: the rollback flag is --rollback-manifest, not --rollback. The CLI parses argv once against the union of every command's options, keyed by long name. A value-typed setup migrate --rollback retyped the boolean config adopt --rollback, so config adopt --rollback --json took --json as its value and failed with a usage error. That failed all ten native-compose-adoption-*-worktrees docker E2E scenarios in CI run 39280939414. tests/cli-command.test.ts now requires each long option to keep one value type across the command tree, and checks that config adopt --rollback --json still parses as two booleans.
• agent-surface-freeze e2e: added setup migrate --all-scopes and setup migrate --all-scopes --apply --skip-plugin-check all, twice each. Ran locally with bun tests/e2e/run.ts --only=agent-surface-freeze: pass, all customized seeded surfaces byte-identical, positive control intact.
• Required local checks:
  • tests/integration-ownership.test.ts, tests/cli-spawn-env-isolation.test.ts, tests/cli-reference-docs.test.ts, tests/cli-help.test.ts and tests/integration-sync.test.ts pass.
  • bun run --cwd packages/cli typecheck: 0 errors.
  • bun run --cwd packages/cli check: 0 errors. Its 34 warnings come from files this PR does not change.
  • bunx ultracite check on the changed files is clean.
  • bun run privacy:check passes.

Negative controls (mutation proofs)

Each mutation below was applied alone. The named test file failed, and the source was then restored:

• apply ignores blocked targets
• Claude installed-copy check skipped
• Claude settings precedence reversed
• Codex enabled forced true
• global scope reads project Codex config
• symlink preservation removed
• byte recheck before removal removed
• rollback overwrites a conflict
• manifest path validation removed
• manifest digest validation removed
• rollback accepts non-Hack bytes
• restored mode ignored
• manifest not committed before removal (caught by the interrupted-apply test)
• customized files treated as owned
• --skip-plugin-check accepts unknown names
• refused apply exits 0
• --rollback-manifest accepts extra flags
• setup migrate flag named --rollback again (value-typed): both new tests/cli-command.test.ts guards fail

Remaining gaps (host-bound)

• Replacement verification is configuration evidence, not loading evidence. A verified status does not prove a fresh client session loads the plugin. The command and docs tell the operator to check that first.
• The Codex plugin cache layout is not inspected, so only config.toml enablement is checked. The Claude installed_plugins.json shape is the v2 registry form (array or object, both accepted), and this PR does not re-observe it against the current client release.
• Cursor plugin installs are not inspectable; Cursor migration always needs an explicit skip.
• No real client home or user/global migration was run; all evidence comes from temp fixtures. The new freeze rows also need their first hosted CI pass.
• Concurrent setup migrate --apply runs are not serialized. Each removal rechecks bytes and ownership, which leaves the same single read-then-unlink window documented for W11.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}