TenantAtlas/specs/259-compliance-evidence-mapping/research.md

# Research — Compliance Evidence Mapping v1

**Date**: 2026-04-30  
**Spec**: [spec.md](spec.md)

This document resolves the planning decisions for the smallest safe versioned interpretation overlay over the repo's existing canonical control references and released review truth.

## Decision 1 — Keep the existing customer review workspace and released-review detail flow as the only primary and secondary surfaces

**Decision**: Reuse [../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php](../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php) as the primary decision surface and [../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php](../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php) under the existing `customer_workspace` query flag as the only secondary context surface.

**Rationale**:
- The repo already has the admin-plane route, tenant-safe prefilter behavior, customer-workspace query context, and bounded feature and browser tests for these surfaces.
- The missing piece is shared interpretation, not new routing, a new panel, or a portal shell.
- Reusing the existing surfaces keeps the feature aligned with the authoritative spec and avoids a second customer-review UX vocabulary.

**Alternatives considered**:
- Add a dedicated compliance portal or a second customer-only page.
  - Rejected: duplicates the current review-consumption path and widens scope into shell-level IA.
- Push all explanation into the workspace only.
  - Rejected: would leave the first drilldown without the detailed control explanation the spec requires.

## Decision 2 — Derive the interpretation once during tenant review composition and reuse it through existing review payloads

**Decision**: Materialize the mapped control/readiness contract during tenant review composition by extending [../../apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php](../../apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php) and [../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php](../../apps/platform/app/Services/TenantReviews/TenantReviewComposer.php), then reuse that stored result in both workspace and detail surfaces.

**Rationale**:
- The spec requires the same mapped control meaning and interpretation version to remain consistent between workspace and released-review detail.
- Carrying the result inside existing `TenantReview` and `TenantReviewSection` payloads preserves traceability for older released reviews without a new persistence table.
- A single compose-time pass is the narrowest way to prevent page-level drift.

**Alternatives considered**:
- Compute the interpretation separately in each page.
  - Rejected: two local mappers would drift and would not preserve older review history against the version used at release time.
- Add a new projection table or report artifact for the overlay.
  - Rejected: violates the no-new-persistence constraint.

## Decision 3 — Keep canonical control identity on the existing catalog and resolver seams

**Decision**: Reuse [../../apps/platform/app/Support/Governance/Controls/CanonicalControlCatalog.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlCatalog.php), [../../apps/platform/app/Support/Governance/Controls/CanonicalControlDefinition.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlDefinition.php), and [../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php](../../apps/platform/app/Support/Governance/Controls/CanonicalControlResolver.php) as the only control identity and resolution path.

**Rationale**:
- The catalog already exposes provider-neutral control keys, names, summaries, and domain metadata suitable for customer-safe labels.
- The resolver already maps Microsoft-owned evidence signals onto canonical controls upstream in evidence collection.
- The feature needs an interpretation overlay over canonical controls, not a second control taxonomy or framework registry.

**Alternatives considered**:
- Add a second customer-facing control catalog.
  - Rejected: duplicates platform-core control truth and increases drift risk.
- Move provider-specific signal mapping into the UI.
  - Rejected: deepens provider coupling in the wrong layer and violates the one-shared-path requirement.

## Decision 4 — Carry one explicit version label inside existing review truth and audit metadata

**Decision**: Use one explicit overlay version key, carried inside existing review payloads and surfaced anywhere the mapped control/readiness view appears. The planning baseline is a single v1 key such as `compliance_evidence_mapping.v1`.

**Rationale**:
- FR-003 and FR-014 require the interpretation version to be visible and traceable.
- Embedding the version into current review payloads preserves what an older released review meant at the time it was composed.
- The existing audit pipeline can carry the same version context without a new audit store.

**Alternatives considered**:
- Recompute the current version at render time only.
  - Rejected: older released reviews could silently change meaning after later rule updates.
- Add a dedicated database column or separate version-history model.
  - Rejected: broader persistence change than the current release truth needs.

## Decision 5 — Use a bounded readiness contract with explicit limitation flags instead of pass/fail or certification language

**Decision**: Keep the customer-safe interpretation contract bounded to a small readiness vocabulary plus explicit limitation flags. The planned primary readiness buckets are:

- `follow_up_required`
- `review_recommended`
- `evidence_on_record`

The planned limitation flags are:

- `accepted_risk_influenced`
- `partial_mapping`
- `stale_evidence`
- `supporting_evidence_unavailable`
- `unmapped`

**Rationale**:
- The feature must help a customer decide what needs follow-up without implying formal certification or legal compliance.
- A small readiness vocabulary with explicit limitation modifiers is easier to localize, easier to test, and less likely to overstate the evidence basis than a large scoring system.
- Keeping accepted risk as a modifier preserves the distinction between a governed exception and a fully positive readiness claim.

**Alternatives considered**:
- Use compliant / non-compliant / certified language.
  - Rejected: overstates what the product can legitimately claim.
- Add a larger scorecard or framework-specific status ladder.
  - Rejected: imports framework-engine complexity that the spec explicitly defers.

## Decision 6 — Keep supporting proof on the existing evidence routes and current capability checks

**Decision**: Reuse [../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php](../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php) and existing evidence detail pages as the only supporting-proof routes for this slice.

**Rationale**:
- Existing evidence resources already enforce tenant scope, capability checks, and audit semantics.
- The spec calls for deeper proof only after explicit drilldown, not a new proof viewer or raw payload surface.
- Keeping proof access secondary preserves one dominant workspace action and avoids export/package redesign.

**Alternatives considered**:
- Add a new customer-only proof viewer.
  - Rejected: duplicates evidence routing and widens scope.
- Put raw proof details directly on the workspace row.
  - Rejected: violates the decision-first disclosure hierarchy.

## Decision 7 — Reuse existing audit action IDs and enrich metadata before creating new audit concepts

**Decision**: Keep the audit path on [../../apps/platform/app/Support/Audit/AuditActionId.php](../../apps/platform/app/Support/Audit/AuditActionId.php) and [../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php](../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php), reusing `customer_review_workspace.opened`, `tenant_review.opened`, and `evidence_snapshot.opened` with interpretation-version metadata where needed.

**Rationale**:
- The required access moments already exist as auditable actions in the repo.
- The remaining requirement is traceability of the interpretation version and source surface, which fits shared metadata better than a new event family.
- Reusing the current audit path preserves consistent redaction and workspace or tenant context handling.

**Alternatives considered**:
- Create a new compliance-evidence audit stream.
  - Rejected: unnecessary persistence and ownership cost for a read-only slice.
- Leave version context unaudited.
  - Rejected: weakens FR-014 traceability.

## Decision 8 — Keep validation inside the current review and evidence feature families plus the single existing browser smoke

**Decision**: Expand the existing review and evidence feature tests and keep [../../apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php](../../apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php) as the only browser proof.

**Rationale**:
- The repo already has narrow feature files for canonical control references, workspace behavior, detail explanation, authorization, navigation context, and evidence routes.
- Those files are the cheapest honest proof for isolation, consistent wording, and cross-surface reuse.
- One bounded smoke is enough to catch rendered disclosure regressions without creating a new heavy test family.

**Alternatives considered**:
- Add a broader browser suite for every control state and evidence path.
  - Rejected: too expensive for the bounded value of this slice.
- Rely only on unit tests around a new helper.
  - Rejected: feature behavior and tenant-safe disclosure still need surface-level proof.

## Decision 9 — Keep Governance-as-a-Service Packaging and framework-specific overlays explicitly deferred

**Decision**: Treat this package as the foundational shared interpretation contract only. Governance-as-a-Service Packaging and framework-specific overlays remain follow-up work after the v1 overlay is stable.

**Rationale**:
- The spec explicitly defers both areas.
- Packaging work should consume a proven shared interpretation contract rather than shaping it prematurely.
- Framework-specific overlays would force broader taxonomy and copy decisions before one customer-safe path is validated.

**Alternatives considered**:
- Fold packaging-ready exports into this feature.
  - Rejected: broadens scope into report-system territory.
- Add BSI, NIS2, CIS, or ISO-specific overlay semantics now.
  - Rejected: imports a framework engine before the base interpretation path is proven.