git.stella-ops.org/docs/migration/policy-parity.md

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