# Phase 7 Execution Checklist (Compliance, Risk Maturity, Audit Readiness)

Reference artifacts:
- `docs/wallet-implementation-plan-apps-mode.md`
- `docs/phase-tracker.md`
- `docs/adr/0011-compliance-and-data-governance-controls.md`
- `docs/adr/0007-observability-and-audit-traceability-standard.md`
- `docs/adr/0009-data-partitioning-and-retention-policy.md`
- `docs/adr/0012-testing-strategy-and-quality-gates.md`

## 1. Phase Objective
Establish a regulated-operational baseline by implementing compliance workflows, risk decision traceability, and audit evidence export readiness.

Phase status:
- Start: `not-started`
- End: `done` — 2026-03-15
- KYC/KYB and AML/SAR workflows operational, risk decision evidence is traceable, internal audit dry-run passed.

## 2. Scope
In scope:
- `wallet_compliance` and `wallet_risk` app foundations.
- KYC/KYB case lifecycle and evidence tracking.
- AML screening hooks and SAR workflow scaffolding.
- Risk scoring/case escalation interfaces with transfer events.
- Audit evidence export model and dry-run readiness.

Out of scope:
- Production-scale ML model operations and advanced model lifecycle (Phase 8+).
- External regulator submission automation beyond baseline scaffolding.
- Live compliance/risk dashboards (telemetry emission done; full dashboard tooling deferred to Phase 8).
- Formal exception/waiver governance UI workflow (baseline SAR/AML audit trail done; governance workflow deferred to Phase 8).

## 3. Work Breakdown

## Track A: App Foundations
1. Create `wallet_compliance` OTP app with public interfaces.
- Owner: Compliance Team
- Output: app scaffold, supervision tree, README.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/mix.exs` — umbrella app config, deps: shared_kernel + observability + events + jason + phoenix_pubsub.
  - `apps/wallet_compliance/lib/wallet_compliance/application.ex` — supervision tree starts KycCaseStore, AmlAlertStore, SarStore, ControlCatalog.
  - `apps/wallet_compliance/README.md` — public interface contract, state machines, boundary rules, control catalog.

2. Create `wallet_risk` OTP app with public interfaces.
- Owner: Risk Team
- Output: app scaffold, supervision tree, README.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_risk/mix.exs` — umbrella app config.
  - `apps/wallet_risk/lib/wallet_risk/application.ex` — supervision tree starts RiskProfileStore, RiskSignalStore, RiskCaseStore.
  - `apps/wallet_risk/README.md` — public interface contract, scoring bands, state machines, boundary rules, compliance-risk contract table.

3. Define compliance-risk boundary contracts.
- Owner: Compliance + Risk + Architecture
- Output: clear event/command ownership and cross-app call contracts.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_risk/README.md` § Compliance-Risk Boundary Contract table: `RiskScored.v1` → AML alert creation; `EscalateCase` auto_escalate_to_compliance flag; `KycCaseApproved.v1` → risk score reduction.
  - `apps/wallet_compliance/README.md` § Boundary Rules: peer domain, event-based cross-domain contract, no direct DB cross-app writes.

## Track B: KYC/KYB Workflow
1. Implement KYC/KYB case model and state machine.
- Owner: Compliance Team
- Output: statuses (`submitted`, `under_review`, `approved`, `rejected`, `expired`) with transition guards.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/kyc_case.ex`
  - States: `:submitted` → `:under_review` → `:approved` | `:rejected`; `:submitted` | `:under_review` → `:expired`.
  - `KycCase.terminal?/1` guard; terminal states block all further transitions with `{:error, :terminal_state}`.
  - `KycCaseStore` — ETS GenServer with case_id table + user_id bag index.

2. Implement core commands.
- Owner: Compliance Team
- Output: `SubmitKycCase`, `ReviewKycCase`.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/commands/submit_kyc_case.ex` — builds KycCase, stores, emits `KycCaseSubmitted.v1` + AuditEvent.
  - `apps/wallet_compliance/lib/wallet_compliance/commands/review_kyc_case.ex` — fetches case, applies `KycCase.transition/3`, updates store, emits approved/rejected event + AuditEvent.
  - Both commands carry `correlation_id` through the full call chain.

3. Implement KYC queries and events.
- Owner: Compliance Team
- Output: `GetKycStatus`, events: `KycCaseSubmitted.v1`, `KycCaseApproved.v1`, `KycCaseRejected.v1`.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/queries/get_kyc_status.ex` — `by_case_id/1` and `by_user_id/1`.
  - `apps/wallet_compliance/lib/wallet_compliance/events/kyc_case_submitted.ex`
  - `apps/wallet_compliance/lib/wallet_compliance/events/kyc_case_approved.ex` — includes `reviewer_id`, `reviewer_source` (CTRL-KYC-001).
  - `apps/wallet_compliance/lib/wallet_compliance/events/kyc_case_rejected.ex` — includes `decision_reason`.
  - All events implement `@behaviour WalletEvents.DomainEvent`.

## Track C: AML/SAR Scaffolding
1. Implement AML alert/case model.
- Owner: Compliance + Risk
- Output: suspicious activity alert lifecycle and assignment workflow.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/aml_alert.ex`
  - States: `:open` → `:under_review` → `:resolved` | `:escalated_to_sar` (both terminal).
  - `AmlAlert.assign/2`, `AmlAlert.resolve/2`, `AmlAlert.escalate_to_sar/1` with terminal state guards.
  - `AmlAlertStore` — ETS GenServer with alert_id table, user_id bag index, status bag index.

2. Implement SAR scaffolding command.
- Owner: Compliance Team
- Output: `FileSuspiciousActivityReport` with mandatory evidence fields.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/sar_record.ex` — `SarRecord.new/2` validates all mandatory fields (`subject_user_id`, `reporting_officer_id`, `activity_description`, `activity_period_start`, `activity_period_end`, `evidence_refs` ≥ 1); returns `{:error, :missing_mandatory_fields}` on violation.
  - `apps/wallet_compliance/lib/wallet_compliance/commands/file_suspicious_activity_report.ex` — stores SAR, auto-escalates linked AML alert to `:escalated_to_sar`, emits `SarFiled.v1` + AuditEvent.
  - `apps/wallet_compliance/lib/wallet_compliance/events/sar_filed.ex`

3. Implement compliance alert queries.
- Owner: Compliance Team
- Output: `ListComplianceAlerts`.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/queries/list_compliance_alerts.ex` — `all/0`, `by_status/1`, `by_user/1`.

## Track D: Risk Decision and Escalation
1. Implement risk score interface.
- Owner: Risk Team
- Output: `ScoreTransferRisk` and `GetRiskProfile` query paths.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_risk/lib/wallet_risk/queries/score_transfer_risk.ex` — deterministic, read-only; returns score, band, signal_count, `exceeds_review_threshold`, `exceeds_block_threshold`, `correlation_id`, `transfer_id`.
  - `apps/wallet_risk/lib/wallet_risk/queries/get_risk_profile.ex` — returns profile_id, score, status, signal_count, case_count, last_scored_at, open_case_ids.
  - `apps/wallet_risk/lib/wallet_risk/scoring_engine.ex` — stateless; score = min(sum of signal contributions, 100); bands: normal (0–29), flagged (30–59), under_review (60–84), blocked (85–100).

2. Implement risk signal and escalation commands.
- Owner: Risk Team
- Output: `FlagRiskSignal`, `EscalateCase`.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_risk/lib/wallet_risk/commands/flag_risk_signal.ex` — builds `RiskSignal`, stores, upserts `RiskProfile` via `ScoringEngine.compute/1`, emits `RiskScored.v1` + AuditEvent.
  - `apps/wallet_risk/lib/wallet_risk/commands/escalate_case.ex` — builds `RiskCase`, optionally assigns investigator, auto-escalates to compliance when score ≥ 85 (block threshold), stores, emits `RiskEscalated.v1` + AuditEvent.
  - `RiskProfileStore.upsert_for_user/3` — atomic get-or-create-then-update with update_fn.
  - Signal types with default contributions: `manual_flag` (40), `pattern_match` (35), `failed_auth_spike` (30), `unusual_velocity` (25), `high_value_transfer` (20), `geo_anomaly` (15), `device_change` (10).

3. Emit risk events.
- Owner: Risk Team
- Output: `RiskScored.v1`, `RiskEscalated.v1`, `RiskCleared.v1`.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_risk/lib/wallet_risk/events/risk_scored.ex` — payload: profile_id, user_id, score, band, signal_count.
  - `apps/wallet_risk/lib/wallet_risk/events/risk_escalated.ex` — payload: case_id, user_id, profile_id, score_at_creation, escalation_reason.
  - `apps/wallet_risk/lib/wallet_risk/events/risk_cleared.ex` — payload: case_id, user_id, resolution_note.
  - All events implement `@behaviour WalletEvents.DomainEvent`; carry `correlation_id` for trace linkage.

## Track E: Audit Evidence and Export Readiness
1. Define evidence package format.
- Owner: Compliance + Observability
- Output: control ID mapping, actor/action/outcome fields, time window, correlation IDs.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/evidence_package.ex`
  - Fields: `package_id`, `control_id`, `actor_type` (user|service|admin|system), `actor_id`, `action`, `outcome` (success|failure|denied), `resource_type`, `resource_id`, `occurred_at`, `correlation_id`, `request_id`, `time_window_start`, `time_window_end`, `metadata`.
  - `EvidencePackage.to_map/1` — ISO 8601 timestamp serialization for JSON/CSV export.

2. Implement evidence export service.
- Owner: Compliance + Platform
- Output: export endpoint/process for audit-ready reports (JSON/CSV).
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/evidence_export.ex`
  - `export_kyc/1` — maps all KYC cases to CTRL-KYC-001 evidence packages with optional `from:`/`to:` time-window filter.
  - `export_sar/1` — maps all SAR records to CTRL-AML-001 packages with evidence_count in metadata.
  - `export_aml/1` — maps all AML alerts to CTRL-AML-002 packages.
  - All exports return `[map()]` — directly serializable to JSON or CSV.

3. Add audit completeness checks.
- Owner: Compliance + SRE
- Output: required-event coverage checks for high-risk workflows.
- Status: **done** — 2026-03-15
- Evidence:
  - `EvidenceExport.completeness_check/0` — validates: (1) no SAR records with empty `evidence_refs` (CTRL-AML-001); (2) all required control IDs present in ControlCatalog.
  - Returns `%{status: :pass | :fail, issues: [String.t()]}`.

## Track F: Controls, Monitoring, and Governance
1. Implement control catalog and mapping.
- Owner: Compliance Team
- Output: policy-to-control mapping with technical evidence source links.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/lib/wallet_compliance/control_catalog.ex` — ETS-backed GenServer, seeded at startup.
  - 6 controls cataloged:

  | Control ID | Domain | Policy Ref | Evidence Source |
  |---|---|---|---|
  | CTRL-KYC-001 | kyc | ADR-0011/Identity | KycCaseApproved/Rejected events |
  | CTRL-KYC-002 | kyc | ADR-0011/Identity | KycCase.terminal?/1 |
  | CTRL-AML-001 | aml | ADR-0011/AML | SarRecord.evidence_refs |
  | CTRL-AML-002 | aml | ADR-0011/AML | RiskScored.v1 → AmlAlert |
  | CTRL-AUD-001 | audit | ADR-0007/Audit | WalletObservability.AuditEvent |
  | CTRL-AUD-002 | audit | ADR-0007/Audit | WalletCompliance.EvidenceExport |

  - `ControlCatalog.list_all/0`, `get/1`, `list_by_domain/1` query interfaces.

2. Add compliance/risk dashboards.
- Owner: SRE + Compliance + Risk
- Output: KYC status funnel, AML alert backlog, SAR workflow SLAs, control failure trends.
- Status: **deferred-to-phase-8**
- Notes: Telemetry events emitted from all commands via `:telemetry.execute([:wallet_compliance, :audit], ...)` and `:telemetry.execute([:wallet_risk, :audit], ...)`. Full dashboard definitions (Grafana/LiveView) deferred to Phase 8 observability gate.

3. Define exception/waiver governance workflow.
- Owner: Compliance + Security
- Output: exception submission, approval, expiry, compensating controls, and audit trail.
- Status: **deferred-to-phase-8**
- Notes: Baseline audit trail for exceptions is established through `SarRecord` (mandatory evidence), `AmlAlert` resolution workflow, and `AuditEvent` emission on all compliance actions. Formal exception submission/approval/expiry governance UI workflow deferred to Phase 8.

## Track G: Testing and Audit Dry Run
1. KYC/KYB workflow tests.
- Owner: QA + Compliance
- Output: state transition and rejection/expiry edge-case coverage.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/test/wallet_compliance/kyc_workflow_test.exs` — **20 tests**
  - Coverage: all valid state transitions (submitted→under_review→approved, →rejected, →expired); invalid transition rejection; terminal state guards (approved/rejected/expired block further transitions); `SubmitKycCase` command (happy path, KYB type, unique case IDs); `ReviewKycCase` command (full approval path, rejection with decision_reason, not_found error, invalid transition error); `GetKycStatus` query (by_case_id, by_user_id, not_found).

2. AML/SAR tests.
- Owner: QA + Compliance + Risk
- Output: alert generation, case escalation, SAR evidence completeness tests.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_compliance/test/wallet_compliance/aml_sar_test.exs` — **16 tests**
  - Coverage: AML alert new/assign/resolve/escalate_to_sar; terminal state guards (resolved, escalated_to_sar); `SarRecord.new/2` happy path, missing mandatory field, empty evidence_refs; `FileSuspiciousActivityReport` valid params, missing fields error, auto-escalation of linked AML alert to `:escalated_to_sar`; `ListComplianceAlerts` all/by_status/by_user; `completeness_check/0` pass case.

3. Risk scoring/decision traceability tests.
- Owner: QA + Risk
- Output: deterministic score path and event trace tests.
- Status: **done** — 2026-03-15
- Evidence:
  - `apps/wallet_risk/test/wallet_risk/risk_scoring_test.exs` — **18 tests**
  - Coverage: `ScoringEngine` zero signals, single signal, score bands (30/60/85/100 boundaries), cap at 100, `scored_at` set, `exceeds_review_threshold?` and `exceeds_block_threshold?` boundary cases; `FlagRiskSignal` signal stored + profile created, multi-signal accumulation, band assignment, per-user isolation; `ScoreTransferRisk` with correlation_id, zero signals, transfer_id propagation; `GetRiskProfile` not_found and post-signal summary.
  - `apps/wallet_risk/test/wallet_risk/risk_escalation_test.exs` — **14 tests**
  - Coverage: `RiskCase` new/assign/resolve/escalate_to_compliance; terminal state guards (resolved, escalated_to_compliance); `EscalateCase` creates case for new user, assigns investigator, auto-escalates at block threshold, case stored and retrievable, profile updated with case_id; correlation_id traceability across `FlagRiskSignal`, `EscalateCase`, and `ScoreTransferRisk`.

4. Internal audit dry-run.
- Owner: Compliance + Internal Audit + SRE
- Output: evidence retrieval walkthrough with findings log and remediation actions.
- Status: **done** — 2026-03-15
- Evidence:
  - `EvidenceExport.completeness_check/0` passes: no SAR evidence gaps, all 6 required control IDs present in ControlCatalog.
  - `export_kyc/1`, `export_sar/1`, `export_aml/1` return complete evidence packages for all compliance records.
  - All packages carry `control_id`, `correlation_id`, `actor_id`, `action`, `outcome`, `occurred_at`, `time_window_start/end` — fully queryable per ADR 0007 evidence standard.
  - Findings log: no critical findings. Known deferred items: dashboards and formal exception/waiver governance UI (logged under Track F, deferred-to-phase-8).

## 4. Deliverables

| # | Deliverable | Status | Location |
|---|---|---|---|
| 1 | `wallet_compliance` app integrated into umbrella | done | `apps/wallet_compliance/` — 19 lib files, 25 total |
| 2 | `wallet_risk` app integrated into umbrella | done | `apps/wallet_risk/` — 15 lib files, 20 total |
| 3 | KYC/KYB workflows operational with auditable decisions | done | `KycCase` state machine, SubmitKycCase/ReviewKycCase commands, GetKycStatus query, 3 events |
| 4 | AML/SAR scaffolding operational with evidence capture | done | `AmlAlert` lifecycle, `SarRecord` mandatory evidence, FileSuspiciousActivityReport command, ListComplianceAlerts query, SAR→AML alert linkage |
| 5 | Risk scoring/escalation paths integrated with transfer lifecycle | done | `ScoringEngine`, FlagRiskSignal/EscalateCase commands, ScoreTransferRisk/GetRiskProfile queries, 3 risk events |
| 6 | Audit evidence export capability | done | `EvidencePackage`, `EvidenceExport` (export_kyc/sar/aml + completeness_check), `ControlCatalog` (6 controls) |
| 7 | Audit dry-run report | done | `completeness_check/0` passes; Track G.4 evidence above |

## 5. Entry and Exit Criteria

Entry criteria:
- Phase 6 integration baseline completed. ✓ (2026-03-14)
- ADR 0011 and ADR 0007 controls available and accepted. ✓

Exit criteria:

| # | Criterion | Status |
|---|---|---|
| 1 | Phase 7 milestone checklist in `docs/phase-tracker.md` completed | ✓ done |
| 2 | KYC/KYB and AML/SAR workflow tests pass | ✓ 36 tests (20 kyc + 16 aml_sar), 0 failures |
| 3 | Risk decision and escalation traces queryable with correlation IDs | ✓ all commands carry correlation_id; ScoreTransferRisk returns it; RiskScored/Escalated events embed it |
| 4 | Audit evidence export operational and complete for required control set | ✓ 6 controls cataloged, export functions returning ADR 0007-compliant packages |
| 5 | Internal audit dry-run completed with remediation plan logged | ✓ completeness_check passes; deferred items logged under Track F |

## 6. Risks and Mitigations

1. Risk: incomplete evidence for regulatory controls.
- Mitigation: control catalog mapping and mandatory evidence field validation.
- Outcome: **mitigated** — ControlCatalog enforces 6 control IDs; SarRecord.new/2 rejects missing evidence_refs; completeness_check/0 runs coverage scan.

2. Risk: false-positive risk alerts overwhelm operations.
- Mitigation: threshold tuning, severity classes, SLA-based queueing and triage.
- Outcome: **partially mitigated** — severity classes (:low/:medium/:high/:critical) on AmlAlert; score bands and thresholds in ScoringEngine; SLA queueing deferred to Phase 8 operational tooling.

3. Risk: compliance workflow divergence across teams.
- Mitigation: strict command/event contracts and shared control governance reviews.
- Outcome: **mitigated** — explicit boundary contracts documented in both READMEs; event-based cross-domain interface defined; domain map updated.

4. Risk: audit export gaps discovered late.
- Mitigation: run periodic dry-run exports during implementation, not only at phase end.
- Outcome: **mitigated** — completeness_check/0 available as a callable utility at any time; audit_evidence_test.exs verifies it continuously.

## 7. Sprint Execution Summary

Sprint A (completed 2026-03-15):
- Scaffolded `wallet_compliance` and `wallet_risk` apps.
- Implemented KYC/KYB state machine and commands.
- Implemented risk signal interface and ScoringEngine.
- Defined control mapping and evidence schemas.

Sprint B (completed 2026-03-15):
- Implemented AML/SAR scaffolding and escalation flows.
- Added EvidenceExport pipeline and ControlCatalog.
- Implemented risk case escalation with auto-compliance escalation.
- Executed internal audit dry-run via completeness_check/0.

## 8. Evidence Checklist

- [x] `wallet_compliance` scaffold + README/public contracts — `apps/wallet_compliance/README.md`
- [x] `wallet_risk` scaffold + README/public contracts — `apps/wallet_risk/README.md`
- [x] KYC/KYB test report and transition coverage — `kyc_workflow_test.exs` (20 tests, 0 failures, 2026-03-15)
- [x] AML/SAR test report and evidence completeness checks — `aml_sar_test.exs` (16 tests, 0 failures, 2026-03-15)
- [x] Risk scoring/escalation traceability report — `risk_scoring_test.exs` (18 tests) + `risk_escalation_test.exs` (14 tests), 0 failures, 2026-03-15
- [x] Compliance control mapping and evidence source matrix — `ControlCatalog` (6 controls, policy→implementation→evidence_source), `audit_evidence_test.exs` (12 tests)
- [x] Audit export sample package and validation report — `EvidenceExport.export_kyc/sar/aml/1`, `completeness_check/0` passes
- [x] Internal audit dry-run report — completeness_check: `%{status: :pass, issues: []}`, deferred items logged
- [x] Phase 7 exit approval note — `docs/phase-tracker.md` Phase 7 row: `done`, 2026-03-15; total 80 tests (48 wallet_compliance + 32 wallet_risk), 0 failures; boundary check: 0 violations