# Policy Parity Migration Guide

> **Imposed rule:** Parity runs must use frozen inputs (SBOM, advisories, VEX, reachability, signals) and record hashes; activation is blocked until parity success is attested.

This guide describes how to dual-run old vs new policies and activate only after parity is proven.

## 1. Scope
- Applies to migration from legacy policy engine to SPL/DSL v1.
- Covers dual-run, comparison, rollback, and air-gap parity.

## 2. Dual-run process
1. **Freeze inputs**: snapshot SBOM/advisory/VEX/reachability feeds; record hashes.
2. **Shadow new policy**: run in shadow with same inputs; record findings and explain traces.
3. **Compare**: use `stella policy compare --base <legacy> --candidate <new>` to diff findings (status/severity) and rule hits.
4. **Thresholds**: parity passes when diff counts are zero or within approved budget (`--max-diff`); any status downgrade to `affected` must be reviewed.
5. **Attest**: generate parity report (hashes, diffs, runs) and DSSE-sign it; store in Evidence Locker.
6. **Promote**: activate new policy only after parity attestation verified and approvals captured.

## 3. CLI commands
- `stella policy compare --base policy-legacy@42 --candidate policy-new@3 --inputs frozen.inputs.json --max-diff 0`
- `stella policy parity report --base ... --candidate ... --output parity-report.json --sign`

## 4. Air-gap workflow
- Run compare offline using bundled inputs; export parity report + DSSE; import into Console/Authority when back online.

## 5. Rollback
- Keep legacy policy approved/archivable; rollback with `stella policy activate <legacy>` if parity regression discovered.

## 6. Checklist
- [ ] Inputs frozen and hashed.
- [ ] Shadow runs executed and stored.
- [ ] Diff computed and within budget.
- [ ] Parity report DSSE-signed and stored.
- [ ] Approvals recorded; two-person rule satisfied.
- [ ] Rollback path documented.

## References
- `docs/policy/runtime.md`
- `docs/policy/editor.md`
- `docs/policy/governance.md`
- `docs/policy/overview.md`