docs consolidation and others

docs/technical/migration/exception-governance.md

@@ -0,0 +1,58 @@
+# Exception Governance Migration Guide
+
+> **Imposed rule:** All exceptions must be time-bound, tenant-scoped, and auditable; legacy perpetual suppressions are prohibited after cutover.
+
+This guide explains how to migrate from legacy suppressions/notifications to the unified Exception Governance model in Excititor and Console.
+
+## 1. What changes
+- **Unified exception object:** replaces ad-hoc suppressions. Fields: `tenant`, `scope` (purl/image/component), `vuln` (CVE/alias), `justification`, `expiration`, `owner`, `evidence_refs`, `policy_binding`, `status` (draft/staged/active/expired).
+- **Two-phase activation:** `draft → staged → active` with policy simulator snapshot; rollbacks produce a compensating exception marked `supersedes`.
+- **Notifications:** move from broad email hooks to route-specific notifications (policy events, expiring exceptions) using Notify service templates.
+- **Auditability:** each lifecycle change emits Timeline + Evidence Locker entries; exports include DSSE attestation of the exception set.
+
+## 2. Migration phases
+1. **Inventory legacy suppressions**
+   - Export current suppressions and notification rules (per tenant) to NDJSON.
+   - Classify by scope: package, image, repo, tenant-wide.
+2. **Normalize and enrich**
+   - Map each suppression to the unified schema; add `expiration` (default 30/90 days), `owner`, `justification` (use VEX schema categories when available).
+   - Attach evidence references (ticket URL, VEX claim ID, scan report digest) where missing.
+3. **Create staged exceptions**
+   - Import NDJSON via Console or `stella exceptions import --stage` (CLI guide: `docs/modules/cli/guides/exceptions.md`).
+   - Run policy simulator; resolve conflicts flagged by Aggregation-Only Contract (AOC) enforcement.
+4. **Activate with guardrails**
+   - Promote staged → active in batches; each promotion emits Timeline events and optional Rekor-backed attestation bundle (if Attestor is enabled).
+   - Configure Notify templates for expiring exceptions (T‑14/T‑3 days) and denied promotions.
+5. **Decommission legacy paths**
+   - Disable legacy suppression writes; keep read-only for 30 days with banner noting deprecation.
+   - Remove legacy notification hooks after confirming staged/active parity.
+
+## 3. Data shapes
+- **Import NDJSON record (minimal):** `{ tenant, vuln, scope:{type:'purl'|'image'|'component', value}, justification, expiration, owner }
+- **Export manifest:** `{ generated_at, tenant, count, sha256, aoc_enforced, source:'migration-legacy-suppressions' }`
+- **Attestation (optional):** DSSE over exception set digest; stored alongside manifest in Evidence Locker.
+
+## 4. Rollback plan
+- Keep legacy suppressions read-only for 30 days.
+- If a promotion batch causes regressions, mark affected exceptions `expired` and re-enable corresponding legacy suppressions for that tenant only.
+- Emit `rollback_notice` Timeline events and Notify operators.
+
+## 5. Air-gap considerations
+- Imports/exports are file-based (NDJSON + manifest); no external calls required.
+- Verification uses bundled attestations; Rekor proofs are optional offline.
+- Console shows AOC badge when Aggregation-Only Contract limits apply; exports record `aoc=true`.
+
+## 6. Checklists
+- [ ] All legacy suppressions exported to NDJSON per tenant.
+- [ ] Every exception has justification, owner, expiration.
+- [ ] Policy simulator run and results attached to exception batch.
+- [ ] Notify templates enabled for expiring/denied promotions.
+- [ ] Legacy write paths disabled; read-only banner present.
+- [ ] Attestation bundle stored (if Attestor available) and Evidence Locker entry created.
+
+## 7. References
+- `docs/modules/excititor/architecture.md`
+- `docs/modules/excititor/implementation_plan.md`
+- `docs/modules/cli/guides/exceptions.md`
+- `docs/security/export-hardening.md`
+- `docs/policy/ui-integration.md`