From 410626e5de48e2cfee3deaa984d1ee097d391a5f Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 3 Sep 2026 09:43:42 -0700 Subject: [PATCH] docs: the cutover checklist under the open design Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY --- docs/CUTOVER.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/CUTOVER.md diff --git a/docs/CUTOVER.md b/docs/CUTOVER.md new file mode 100644 index 000000000..7d09e0427 --- /dev/null +++ b/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`; `.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--` 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` 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").