# Migration 3.0.0-hardened-core-loop

**From:** versions < 3.0.0   **To:** 3.0.0

## Why

3.0.0 replaces the recorded review-loop machinery (review-ledger / fold-completeness /
verification-profile) with a COMPUTED core: red-proof custody + changed-line coverage inside
`run-gates --final`, ship-class review receipts with self-declared probe AND posture markers,
and an optional pre-commit guard that binds a commit to the latest green final-run receipt.
The retired tools no longer exist; a declaration or receipt that references them stops working
loudly, never silently.

## Steps

1. **Node floor:** ensure Node **>= 22** (the built-in lcov reporter the loop consumes).
2. **Gates declaration:** preview the consented migration —
   `node <installed-kit>/references/scripts/migrate-gates.mjs --kit-tools <installed-kit>/tools --cwd <project>`
   — then re-run with `--apply` on an explicit yes. It removes retired ledger/fold gates,
   wires the lcov reporters into the canonical `unit-tests` cmd, appends the canonical
   `coverage-check` gate LAST, and cleans retired git-dir stores. CUSTOMIZED entries are
   reported with a paste-ready recovery — resolve them by hand.
3. **Review receipts:** receipts minted by pre-3.0.0/4.0.0 bridge wrappers carry no `posture`
   field and STOP satisfying the review-state gate (fail-closed, the probe-marker precedent).
   Refresh the placed bridges (init/upgrade does this), then re-run the required reviews.
4. **Commit guard (optional, consented):** a 2.x deployment's project-local
   `scripts/install-git-hooks.mjs` PREDATES the arm and the upgrade preserves existing scripts —
   refresh it FIRST, classified deterministically:
   `cmp -s scripts/install-git-hooks.mjs <installed-kit>/references/scripts/install-git-hooks.mjs`
   — identical ⇒ already current; DIFFERING ⇒ the copy is UNKNOWN (older deploy or customized —
   a consumer cannot enumerate shipped priors) ⇒ STOP and merge/replace by hand, never
   overwrite unasked (an explicit "my copy is an unmodified older deploy" answer is the one
   auto-replace lane). Then, once the declaration is final-run-capable, arm it:
   `node scripts/install-git-hooks.mjs --commit-guard "<installed-kit>/tools/commit-guard.mjs"`
   (the Recommendations advisor surfaces the exact one-liner) — and VERIFY the arm took:
   `grep -Fx 'node "<installed-kit>/tools/commit-guard.mjs" --check' "$(git rev-parse --git-path hooks)/pre-commit"`
   (the FIXED-STRING resolved line, exactly as the installer writes it) — absent ⇒ the arm did
   not take; re-run the installer refresh above before re-arming.
5. **Re-stamp:** init/upgrade re-stamps `docs/ai/.workflow-version` to 3.0.0.

## Verification

`node <installed-kit>/tools/run-gates.mjs --final` exits 0 and records a green receipt;
`node <installed-kit>/tools/review-state.mjs --check` names any remaining obligation.