docs: the cutover checklist under the open design

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY

docs/CUTOVER.md

@@ -0,0 +1,58 @@
+# Cutover: shipping the Rust engine (the maintainer's checklist)
+
+State as of 2026-09-03. Everything below `rust-swap` is verified and pushed;
+nothing irreversible has happened: no engine tag, no npm publish, no merge.
+The detector is open source (the closed-core mechanism was built, measured,
+and removed the same week; the private `impeccable-detector` repo is archived
+as the record). The old `impeccable-dist` channel is archived too.
+
+## Steps, in order
+
+1. **Rebase and final drift check.** `git fetch && git log --oneline
+   94b7f34f..origin/main -- skill/scripts scripts/lib` (nothing had landed
+   as of 2026-09-03). Rebase `rust-swap` onto `origin/main`.
+2. **Engine release.** `bun run release:engine` (clean tree, pushed, tag
+   free, `package.json` platform pins equal `ENGINE_VERSION`). It tags
+   `engine-v<ENGINE_VERSION>`; `.github/workflows/release-engine.yml` builds
+   the five binaries (darwin-arm64, darwin-x64 on the arm64 runner, linux-x64
+   and linux-arm64 musl, windows-x64) and publishes them with `.sha256`
+   sidecars on this repo's Releases. Check: `bun run check:engine-release`
+   passes its binary half.
+3. **npm.** Create the `@impeccable` scope if it does not exist, `npm login`,
+   then publish the five `@impeccable/cli-<os>-<arch>` platform packages from
+   the release assets (`cli/platform-packages/` holds the templates at
+   version `0.0.0-engine`; stamp `ENGINE_VERSION`, put the binary at `bin/`,
+   `npm publish --access public`). Then the `impeccable` shim through
+   `bun run release:cli` plus `npm publish`. `bun run check:engine-release`
+   is fully green after this.
+4. **Clean-HOME launcher check.** `rm -rf ~/.impeccable/bin`, then run
+   `skill/scripts/impeccable context` from any project: it must download from
+   `engine-v<X>` and run.
+5. **Merge** `rust-swap` into `main`. The sync workflow regenerates the
+   provider directories (they still carry copies of the retired JS engine;
+   the sync rewrites them). CI's `rust`, `rust-windows` and `oracle` jobs are
+   required already.
+6. **Version bumps and changelog** for skill, CLI and extension. The
+   extension is the wasm-core shell now (manifest held at 1.3.3; the bump
+   plus a Web Store resubmission for the new `offscreen` permission are
+   yours). Flip `engine-release-ready` to required.
+7. **Housekeeping.** Revoke the fine-grained PAT `impeccable-detector-release`
+   in your GitHub settings (created for the closed-core release flow; its
+   secret is already deleted).
+
+## What to know
+
+- `cargo xtask bundle` regenerates `crates/live/assets/detect-antipatterns-browser.js`
+  (tracked) and `extension/detector/` (vendored at build). `bun run
+  build:extension` runs it; CI installs `wasm-pack` for that.
+- The oracle replays byte-for-byte on macOS and Linux (795 cases on macOS,
+  794 plus one platform skip on Linux). `tests/oracle/DELTAS.md` records the
+  two goldens re-recorded when the harness started staging workspaces at
+  their real path.
+- The Firefox extension zip is packaged and lint-clean but cannot run the
+  offscreen-document design; a Gecko fallback is future work before an AMO
+  release.
+- Pristine runs the engine inside Cloudflare Workers as the npm
+  `impeccable@3` package. `impeccable@4` is a native-binary shim, so Pristine
+  stays on `^3.5.0` until it moves to the wasm `detect` surface and its own
+  rule pack (`docs/ENGINE.md`, "Rule packs").