# Exception Governance Migration Guide

Status: Draft (2025-11-26) — aligns with Excititor VEX/exception flows and Doc task DOCS-EXC-25-007.

## Why this migration
- Retire legacy suppressions/waivers and move to policy/VEX-first exceptions with provenance.
- Provide auditable, reversible exceptions with rollout/rollback plans and notifications.

## Target state
- Exceptions are recorded as:
  - VEX statements (OpenVEX) referencing findings and components.
  - Policy overrides (simulator) with scope, expiry, and rationale.
  - Optional authority approval attestation (DSSE) per exception bundle.
- Persistence: Excititor stores exception records with tenant, source, scope, expiry, approver, evidence links.
- Propagation:
  - Graph overlays surface exception status on nodes/edges.
  - Notify emits `exception.created/expired` events.
  - CLI/Console consume exception status via `/exceptions` API.

## Migration steps
1) **Freeze legacy inputs**
   - Disable new legacy suppressions in UI/CLI.
   - Mark existing suppressions read-only; export CSV/NDJSON snapshot.
2) **Export legacy suppressions**
   - Run `exc suppressions export --format ndjson --with-rationale --with-expiry`.
   - Store exports with SHA256 and DSSE envelope in `exceptions/export-YYYYMMDD/`.
3) **Transform to VEX/policy overrides**
   - Convert each suppression to OpenVEX statement:
     - `status`: `not_affected` or `under_investigation`.
     - `justification`: map legacy reason → VEX justification code.
     - `impact`: optional; include nearest safe version if known.
   - Generate policy override record with:
     - `scope` (component, environment, service).
     - `expiresAt` (carry forward or set 30/90d).
     - `rationale` from legacy note.
4) **Import**
   - Use Excititor `/exceptions/import` (or CLI `exc exceptions import`) to load transformed NDJSON.
   - Verify import report: counts by status, rejected items, conflicts.
5) **Notify & rollout**
   - Notify downstream systems: Graph overlays refresh, Scanner/Vuln Explorer respect VEX, Policy Engine caches reload.
   - Announce change freeze window and rollback plan.

## Rollback plan
- Keep legacy suppressions export.
- If import fails or downstream errors:
  - Disable new exception endpoints feature flag.
  - Re-enable legacy suppressions (read-only → writable) temporarily.
  - Investigate rejected items; re-run transform/import after fix.

## Notifications
- When migrating: send summary to tenants with counts per status and upcoming expiries.
- Ongoing: Notify events `exception.created`, `exception.expired`, `exception.rejected` with tenant + scope.

## Validation checklist
- [ ] Legacy suppressions export stored with SHA256 + DSSE.
- [ ] Transform script maps all legacy reasons → VEX justification codes.
- [ ] Import dry-run produces zero rejects or documented rejects with reasons.
- [ ] Overlay/Console shows exceptions on affected components.
- [ ] Rollback tested on staging.

## References
- Excititor module: `docs/modules/excititor/architecture.md`, `vex_observations.md`.
- Policy simulator: `docs/modules/policy/architecture.md` (POLICY-ENGINE-30-001..003).
- Graph overlays: `docs/modules/graph/architecture-index.md`.