Policy Parity Migration Guide

Purpose. Migrate from the legacy policy engine to SPL/DSL v1 safely by dual-running both policies against identical, frozen inputs and activating the new revision only after parity is proven.

Audience. Policy owners and release engineers performing a controlled policy cutover (online or air-gapped).

Golden rule. Parity runs must use frozen inputs (SBOM, advisories, VEX, reachability, signals) and record their hashes. Activation is blocked until parity is proven and the result is attested.

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: stage the candidate revision and simulate it against the frozen SBOM set; record the diff and explain traces.
3. Diff: use stella policy simulate <policy-id> --base <legacyVersion> --candidate <newVersion> --sbom <id> --explain to diff findings (added/removed/unchanged, severity up/down) and rule-hit deltas. The same diff is available over the API at POST /api/policy/policies/{policyId}/simulate (scope policy:simulate).
4. Thresholds: gate on the diff. --fail-on-diff exits with code 20 when findings are added or removed, so parity passes only when the diff is empty. There is no numeric diff-budget flag today (see §7).
5. Capture evidence: persist the simulation output (diff plus explainUri) alongside the recorded input hashes for the parity record. There is no first-class CLI-generated, DSSE-signed parity report yet (see §7).
6. Promote: activate the new revision only after the parity diff is reviewed and approvals captured.

3. CLI commands

• Diff/shadow run: stella policy simulate P-7 --base 42 --candidate 43 --sbom sbom:S-42 --explain --fail-on-diff
  • --base / --candidate take integer revision versions (not name@version refs); --candidate defaults to the latest approved revision when omitted.
  • Useful flags: --env key=value (repeatable), --format table|json|markdown, --output <file>, --mode quick|batch, --sbom-selector <pattern>, --heatmap, --with-exception / --without-exception, --reachability-state / --reachability-score.
• Activate the approved revision: stella policy activate P-7 --version 43 --note "<reason>" (scope policy:activate; --run-now, --scheduled-at, --priority, --rollback, --incident are also supported).
• Sign a policy revision (not a parity report): stella policy sign <policy-id> ....

Not implemented: stella policy compare, a stella policy parity subcommand, and a --max-diff flag do not exist in src/Cli. The supported parity mechanism is stella policy simulate --base/--candidate with --fail-on-diff.

4. Air-gap workflow

• Run the simulate-based diff offline against bundled SBOMs; export the simulation output with the frozen inputs and import findings into Console/Authority when back online.
• Policy packs (not parity reports) can be moved across an air gap with stella policy export-bundle --policy <file> --output <bundle.tar.gz> and stella policy import-bundle --bundle <bundle.tar.gz>.

5. Rollback

• Keep the legacy revision approved/archivable. Roll back with stella policy rollback <policy-id> --target-version <legacyVersion> (defaults to the previous version; supports --env, --reason, --incident). stella policy activate <policy-id> --version <legacyVersion> --rollback is an equivalent activation-side path.

6. Checklist

• [ ] Inputs frozen and hashed.
• [ ] Shadow simulate runs executed and stored.
• [ ] Diff computed; --fail-on-diff clean (or residual diff explicitly reviewed/approved).
• [ ] Simulation output (diff + explainUri) stored with input hashes.
• [ ] Approvals recorded; two-person rule satisfied.
• [ ] Rollback path documented.

7. Roadmap (not yet implemented)

These capabilities are referenced by the parity narrative but are not present in src/Cli/src/Policy today. Track before relying on them.

• A numeric diff-budget threshold (the prose --max-diff <n> concept). Today the only gate is the binary --fail-on-diff (exit 20).
• A first-class, CLI-generated parity report artefact that bundles hashes/diffs/runs and is DSSE-signed end-to-end. stella policy sign signs a policy revision, not a parity report.

References

• docs/modules/policy/architecture.md
• docs/api/policy.md
• docs/contracts/policy-studio.md
• docs/features/checked/cli/cli-policy-lifecycle-commands.md