Migrate v8.1 → v9

v9.0.0 succeeded v8.1.0; there was no v8.2 release. Install the current patch, v9.0.2. This migration changes the database and removes built-in execution, so keep a restorable copy instead of relying on a successful exit code.

Breaking change: built-in execution is gone

v9 removes:

haft run and haft harness;
the bundled Open-Sleigh source and runtime;
the Elixir/OTP/BEAM build, installer, CI, and archive dependency.

There are no compatibility stubs for those commands. Runner-neutral WorkCommission and RuntimeRunRecord history remains, along with haft commission, haft_commission, and haft commission complete-external. Perform work in the host agent or use an independently operated runner.

1. Stop writers and back up both state locations

Quit every host process that can run haft serve. Back up:

the project-local .haft/ directory;
~/.haft/projects/<project-id>/haft.db, where the ID comes from .haft/project.yaml.

Use SQLite's online backup API or .backup command if the database may still be open. If every writer is stopped, copy haft.db together with any -wal and -shm sidecars. Keep the backup outside the original directories and record its checksum.

2. Install and identify v9.0.2

curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash
haft version

Record the version, commit, and binary checksum. They must identify the same release that the host later loads.

A successful v9 install removes only the exact managed legacy path ~/.haft/runtimes/open-sleigh/current. It preserves ~/.open-sleigh/ user data and ~/.haft/runtimes/haft-embed/.

3. Re-run init for each selected host

haft init --claude
haft init --codex

Run only the targets you use. --mcp-only deliberately omits skills and managed instructions. --core-only migrates project core without publishing host files.

Re-init refreshes Haft-owned skills and only the marked Haft section in project instructions. It removes recognized legacy skills. A foreign file collision fails before writes.

Re-init also applies database migration 58. This removes old affected_files rows with absolute or traversing paths that v9 cannot represent. Haft automatically advances the bundled project-memory model only when it is compatible with the current project. Otherwise it keeps the current model and reports the blocker instead of asking you to choose an internal schema.

4. Remove stale command references

Removed surface	v9 surface
`haft run`, `haft harness`	Work in the host agent or a separately operated runner
`/h-search`	Use FPF search, code exploration, project-memory read, or an exact record query
`/h-problems`	`/h-status` and its explicit drill-downs
`/h-view`	Typed projection and query actions for the exact object
`haft fpf search`	`haft fpf query\|lookup\|inspect`
five-mode workflow instructions	Use the capability that matches the current situation

Fresh v9 init does not create .haft/config.yaml. Recognized obsolete Haft-owned files may be removed; modified or unrecognized files are preserved and reported instead of being silently overwritten.

5. Restart and verify

Completely restart each host. Verify that its MCP server runs the binary recorded in step 2. On a copied project, check status, read an existing record, and exercise one explicitly authorized v9 write before migrating the working project.

A complete rehearsal also checks legacy record counts and content, exact project binding, typed-memory reads, one new write, idempotent retry, and restoration from backup.

Downgrade boundary

Do not write a v9-migrated ledger with v8.1. Database startup migrations are forward migrations. Installing the old binary over v9 without restoring state is not a supported rollback.

Stop all v9 hosts and MCP servers.
Move the migrated .haft/ and global project-ledger directory aside without deleting them.
Restore both locations from the pre-upgrade backup.
Reinstall v8.1.0 and re-run its host initialization.
Verify the restored project before resuming work.

Older installations

The v5-to-v6 rename from quint-code to haft and the v7-to-v8 surface pivot remain historical migration steps. See the v8 release documentation when rehearsing those boundaries; do not treat its execution harness or skill workflow as v9.