TenantAtlas/specs/423-security-compliance-readiness-pack/plan.md

# Implementation Plan: Spec 423 - Security and Compliance Readiness Pack

**Branch**: `423-security-compliance-readiness-pack` | **Date**: 2026-06-30 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `specs/423-security-compliance-readiness-pack/spec.md`

## Summary

Promote selected Security and Compliance Coverage v2 evidence into typed, deterministic compare/render/readiness support for internal operators. The implementation is bounded to existing content-backed evidence and the existing Coverage v2 read/inspect surface: no restore, no apply, no certification, no legal attestation, no customer-facing output, no new source contracts, no new routes/navigation/dashboards, no migrations, no remote calls, and no Purview or Security mini-platform.

Mandatory first support is evidence-gated for `retentionCompliancePolicy`, `labelPolicy`, and `dlpCompliancePolicy`. `autoSensitivityLabelPolicy`, `protectionAlert`, and `complianceTag` may be promoted only when implementation preflight proves content-backed evidence exists and focused tests remain bounded.

## Technical Context

**Language/Version**: PHP 8.4.15; Laravel 12; Laravel Sail-first local workflow.
**Primary Dependencies**: Filament v5, Livewire v4, Pest v4, existing TenantConfiguration Coverage v2 services (`ResourceTypeRegistry`, `SupportedScopeResolver`, `ClaimGuard`, `CoveragePayloadRedactor`, `CoverageV2ReadinessReadModel`, `GenericPayloadNormalizer`, `CanonicalIdentityResolver`, Entra and Exchange/Teams comparable/renderable support).
**Storage**: PostgreSQL via existing Coverage v2 tables/models only. No schema change is planned.
**Testing**: Pest 4 unit and feature tests, plus focused browser proof only if rendered UI output changes.
**Validation Lanes**: fast-feedback and confidence for normalizers/comparators/readiness/claims/RBAC/redaction/no-remote; browser-if-rendered for existing Coverage v2 inspect/readiness output; pgsql lane only if implementation unexpectedly requires persistence changes, which should trigger a stop-and-amend.
**Target Platform**: `apps/platform` Laravel monolith on Sail locally; Dokploy container deployment for staging/production.
**Project Type**: Web application / Laravel monolith.
**Performance Goals**: DB-only compare/render/readiness; no render-time provider/API/HTTP/documentation calls; no N+1 remote work.
**Constraints**: No restore/apply/certification/legal/customer claims; no new routes/navigation/capture/source contracts/tables; no `tenant_id`; no completed-spec rewrites; no mini-platform or global taxonomy; no raw payload exposure by default.
**Scale/Scope**: Focused resource-type family support for selected Security and Compliance Coverage v2 evidence rows in one existing internal/operator surface.

## UI / Surface Guardrail Plan

- **Guardrail scope**: Changed data-driven status/evidence/review presentation on the existing internal/operator Coverage v2 readiness/inspect surface only.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: Existing Coverage v2 readiness/resource/evidence inspect surface if rendered data changes. No new routes, navigation entries, actions, modals, dashboards, panels, or provider registrations.
- **No-impact class, if applicable**: N/A because status/evidence/review presentation changes are expected when evidence is rendered.
- **Native vs custom classification summary**: Existing shared/native Coverage v2 surface; no new custom UI system.
- **Shared-family relevance**: Coverage v2 evidence/readiness/inspect family, status badge vocabulary, Claim Guard wording family.
- **State layers in scope**: Page/detail evidence state only; no shell or URL-query changes.
- **Audience modes in scope**: Operator-MSP/internal operator only.
- **Decision/diagnostic/raw hierarchy plan**: Decision first (`manual_review_required`, readiness state, material change summary), diagnostics second (field-level diff labels and reasons), raw/support evidence third and gated/collapsed.
- **Raw/support gating plan**: Raw JSON, provider responses, sensitive values, incident/content details, fingerprints, and internal debug fields stay hidden from default-visible summaries and are exposed only through existing gated support/inspect mechanics if already available.
- **One-primary-action / duplicate-truth control**: No new action; the existing inspect/read flow remains the primary path.
- **Handling modes by drift class or surface**: Review-mandatory for high-risk retention/DLP/labeling changes; blocked for missing identity/evidence/permission/unsupported fields.
- **Repository-signal treatment**: Report-only in this prep package; implementation must use current repo tests and services as truth.
- **Special surface test profiles**: Existing Coverage v2 technical-annex/evidence-inspection surface; focused browser smoke if rendered output changes.
- **Required tests or manual smoke**: Functional-core, redaction/claim/state-contract tests, and browser-if-rendered proof.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Smoke Coverage if rendered output changes; otherwise exact `N/A - no rendered UI surface changed`.
- **UI/Productization coverage decision**: Existing internal surface only; update audit coverage artifacts only if runtime UI files/routes/navigation change.
- **Coverage artifacts to update**: none expected.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: Checked no-impact; no panel/provider/navigation changes planned.
- **Screenshot or page-report need**: Focused screenshot/browser proof only if implementation changes rendered output; no standalone page report unless runtime UI structure changes.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: Canonical Coverage v2 extension; no compatibility aliases, old labels, duplicate surfaces, fallback readers, or historical fixtures.
- **Page archetype and surface budget plan**: Technical Annex / read-only evidence inspection; default-visible information limited to operator decision needs.
- **Technical Annex and deep-link demotion plan**: Evidence IDs, raw source keys, raw JSON, provider payloads, fingerprints, incident/content details, and internal reason ownership remain diagnostics/support-only.
- **Canonical status vocabulary plan**: Reuse existing badge/status rendering. Derived compare labels are limited to `added`, `removed`, `changed`, `unchanged`, `ignored_volatile`, `redacted`, `unsupported_field`, and `manual_review_required`. Derived readiness labels are limited to `readiness_not_assessed`, `readiness_ready_for_operator_review`, `readiness_requires_manual_review`, `readiness_blocked_identity`, `readiness_blocked_evidence`, `readiness_blocked_permission`, and `readiness_blocked_unsupported`.
- **Product Surface exceptions**: none.
- **Browser verification plan**: Focused existing Coverage v2 readiness/inspect route smoke when rendered output changes; otherwise record `N/A - no rendered UI surface changed`.
- **Human Product Sanity plan**: Verify an internal operator can decide whether Security/Compliance evidence needs manual review without seeing raw payloads and without any customer/certification/legal/restore claim.
- **Visible complexity outcome target**: Neutral to decreased; raw payload dependence decreases while no new page/action/navigation complexity is added.
- **Implementation report target**: `specs/423-security-compliance-readiness-pack/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire v4.x is the repo baseline for Filament v5 and remains required.
- **Panel provider registration location**: `apps/platform/bootstrap/providers.php`; no panel provider change is planned.
- **Global search posture**: No Filament Resource/global search behavior changes.
- **Destructive/high-impact action posture**: none; this feature is read-only and must not add restore/apply/mutate actions.
- **Asset strategy**: No new assets expected; no `filament:assets` deployment requirement unless future implementation amends the plan to register assets.
- **Testing plan**: Pest unit tests for normalization/compare/render/readiness; feature tests for Claim Guard, RBAC/404/403, redaction, no raw payload, no remote calls, no restore/certification/customer/legal claims; browser smoke if rendered output changes.
- **Deployment impact**: No env vars, migrations, queues, scheduler changes, storage changes, or asset changes expected. Staging validation still required before production because Security and Compliance evidence is high risk.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: TenantConfiguration Coverage v2 registry/read model, typed payload normalization, compare/render summary generation, readiness/manual-review derivation, redaction, identity resolution, Claim Guard.
- **Shared abstractions reused**: `ResourceTypeRegistry`, `SupportedScopeResolver`, `GenericPayloadNormalizer`, `CoveragePayloadRedactor`, `CanonicalIdentityResolver`, `CoverageV2ReadinessReadModel`, existing Entra and Exchange/Teams comparator/builder patterns, existing badge/status rendering.
- **New abstraction introduced? why?**: Focused Security/Compliance typed helpers may be introduced only when the existing Entra and Exchange/Teams helpers cannot express resource-specific retention/label/DLP semantics without unsafe branching.
- **Why the existing abstraction was sufficient or insufficient**: Existing generic support can store and render raw evidence but cannot safely classify Security/Compliance materiality, manual-review blockers, unsupported fields, or overclaim boundaries.
- **Bounded deviation / spread control**: New helpers are scoped to the selected Security/Compliance type list and must not become a generic Purview/Security platform, framework, or persistence layer.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: none.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: Microsoft Security and Compliance/Purview resource type semantics, provider payload keys, source aliases, Graph/TCM evidence provenance.
- **Platform-core seams**: Coverage v2 evidence ownership, read authorization, redaction, derived readiness state, operator-safe compare/render summaries, Claim Guard wording.
- **Neutral platform terms / contracts preserved**: `workspace_id`, `managed_environment_id`, `provider_connection_id`, canonical resource type keys, coverage/readiness states, manual review, redaction, unsupported-field handling.
- **Retained provider-specific semantics and why**: Resource type keys and selected field names remain provider-specific because they are needed to produce accurate retention/label/DLP compare semantics.
- **Bounded extraction or follow-up path**: No speculative multi-provider abstraction. If a second provider or customer-facing compliance output appears, create a separate spec.

## Constitution Check

*GATE: Must pass before implementation and be re-checked after design drift.*

- **Inventory-first**: PASS. This pack reads existing Coverage v2 evidence; it does not create backup/restore truth.
- **Read/write separation**: PASS. No Microsoft tenant writes, no restore, no apply, no destructive action.
- **Graph/provider contract path**: PASS. Render/compare/readiness is DB-only; any need for new Graph/TCM/source contracts is a stop condition requiring spec amendment.
- **Deterministic capabilities**: PASS with planned tests for fixed payloads, compare labels, readiness states, redaction, and no remote calls.
- **RBAC/workspace isolation**: PASS with planned feature tests for existing workspace/environment/provider-connection scope, non-member 404, missing-capability 403.
- **Data minimization**: PASS with planned redaction and no-default-raw-payload tests.
- **Test governance (TEST-GOV-001)**: PASS with unit/feature/browser-if-rendered lane split and no broad seed/helper growth.
- **Proportionality (PROP-001)**: PASS. New derived states/importance labels are feature-local and non-persisted; no tables/enums/global taxonomy.
- **No premature abstraction (ABSTR-001)**: PASS if helpers stay local to selected concrete type families and reuse existing patterns.
- **Persisted truth (PERSIST-001)**: PASS. No new persisted entity/table/artifact.
- **Behavioral state (STATE-001)**: PASS because derived readiness labels change operator review behavior but remain non-persisted and bounded.
- **UI semantics (UI-SEM-001)**: PASS if labels remain direct domain-to-UI summaries and do not become a mandatory broad framework.
- **Shared pattern first (XCUT-001)**: PASS via Coverage v2, redaction, identity, Claim Guard, and existing compare/render families.
- **Provider boundary (PROV-001)**: PASS with explicit provider-owned/platform-core split.
- **V1 explicitness / few layers**: PASS if implementation avoids registries/factories/orchestrators beyond focused helpers.
- **Spec discipline / bloat check**: PASS with bloat risk documented and constrained.
- **Badge semantics / Filament-native UI**: PASS if implementation reuses existing badge/status primitives and avoids ad-hoc UI.
- **Product Surface Contract**: PASS with Technical Annex, no customer output, no new surface, browser-if-rendered proof, and Human Product Sanity requirements.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for normalizer/comparator/render/readiness helpers; Feature for Claim Guard, RBAC, redaction, no-remote, no-restore/no-certification/no-customer/legal claim posture; Browser only if existing rendered output changes.
- **Affected validation lanes**: fast-feedback, confidence, browser-if-rendered. No heavy-governance default lane unless implementation adds broad fixtures or persistence, which is a stop condition.
- **Why this lane mix is the narrowest sufficient proof**: Core risk is deterministic classification and wording over DB evidence; unit/feature tests prove behavior without live providers, and browser proof is needed only for rendered surface changes.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec423`
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=ClaimGuard`
  - focused browser smoke for Coverage v2 inspect/readiness only if rendered output changes.
- **Fixture / helper / factory / seed / context cost risks**: Keep fixtures fake, minimal, and local to Spec 423 tests. Do not add global seed defaults.
- **Expensive defaults or shared helper growth introduced?**: no; any helper must be explicit and local.
- **Heavy-family additions, promotions, or visibility changes**: Security/Compliance evidence classification is high-risk but not a heavy suite by default; escalate if optional types require broad fixtures.
- **Surface-class relief / special coverage rule**: Technical Annex focused browser proof is enough unless runtime UI files/routes/navigation change.
- **Closing validation and reviewer handoff**: Reviewer should verify promoted/deferred type matrix, claim restrictions, redaction proof, RBAC proof, no-remote proof, Product Surface proof/N/A, and no completed-spec rewrites.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: Did implementation add persistence, live provider calls, routes/navigation, customer output, restore/certification/legal claims, raw payload default visibility, or broad optional type coverage without evidence?
- **Escalation path**: reject-or-split and amend spec/plan before implementation proceeds.
- **Active feature PR close-out entry**: Smoke Coverage if rendered output changes; otherwise explicit N/A.
- **Why no dedicated follow-up spec is needed**: This is a bounded readiness/compare/render pack. Customer reports, certification, restore/apply, and broader Security/Purview productization are already follow-up candidates.

## Project Structure

### Documentation (this feature)

```text
specs/423-security-compliance-readiness-pack/
+-- spec.md
+-- plan.md
+-- tasks.md
+-- checklists/
    +-- requirements.md
```

### Source Code (expected implementation touch points)

```text
apps/platform/app/Services/TenantConfiguration/
+-- ClaimGuard.php
+-- CoverageV2ReadinessReadModel.php
+-- CoveragePayloadRedactor.php
+-- SecurityComplianceComparablePayloadNormalizer.php
+-- SecurityComplianceCoverageComparator.php
+-- SecurityComplianceRenderableSummaryBuilder.php
+-- SecurityComplianceReadinessEvaluator.php

apps/platform/tests/Unit/Support/TenantConfiguration/
+-- Spec423SecurityComplianceComparablePayloadNormalizerTest.php
+-- Spec423SecurityComplianceCoverageComparatorTest.php
+-- Spec423SecurityComplianceRenderableSummaryBuilderTest.php
+-- Spec423SecurityComplianceReadinessEvaluatorTest.php
+-- Spec423SecurityComplianceClaimGuardTest.php

apps/platform/tests/Feature/TenantConfiguration/
+-- Spec423SecurityComplianceCoverageReadinessTest.php
+-- Spec423SecurityComplianceCoverageRedactionTest.php
+-- Spec423SecurityComplianceCoverageAuthorizationTest.php
```

**Structure Decision**: Reuse the existing TenantConfiguration service/test layout. Names may be adjusted to match sibling conventions, but implementation must not introduce new base folders, new modules, or a separate Security/Purview subsystem.

## Complexity Tracking

| Violation/Risk | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Derived readiness/status family for high-risk Security and Compliance evidence | Operators need to distinguish operator-review-ready, manual-review-required, and blocked evidence without legal/certification overclaim | Generic raw evidence rendering would either expose payloads or hide material compliance risk |
| Focused typed helper family | Retention, label, and DLP fields have resource-specific materiality and redaction rules | A large generic strategy registry would be premature; embedding all logic in the read model would make overclaim/redaction behavior harder to test |

## Proportionality Review

- **Current operator problem**: Internal operators need to review selected Security and Compliance evidence without inspecting raw payloads and without mistaking evidence readiness for legal, restore, certification, or customer readiness.
- **Existing structure is insufficient because**: Generic Coverage v2 evidence can store and expose content-backed data but cannot safely explain retention/label/DLP materiality, manual-review blockers, unsupported fields, or Security/Compliance overclaim boundaries.
- **Narrowest correct implementation**: Focused normalizer/comparator/render/readiness helpers for the selected concrete types, wired into the existing Coverage v2 read model and Claim Guard.
- **Ownership cost created**: Additional helper tests, fixture payloads, claim phrases, and a type-promotion matrix in the implementation report.
- **Alternative intentionally rejected**: Raw JSON/operator-only display, because it leaks sensitive payload shape and forces manual interpretation; broad Purview/Security platform, because it imports routes, persistence, capture, and legal/product claims outside the current need.
- **Release truth**: Current-release truth for internal operator readiness over existing Coverage v2 evidence; not future customer/certification/legal readiness.

## Implementation Phases

### Phase 0 - Preflight

Confirm branch, HEAD, dirty state, hard-gate skills, existing Security/Compliance registry rows, evidence availability for all six candidate types, related completed spec read-only posture, and no duplicate 423 branch/spec directory. Stop if implementation requires new capture contracts, new persistence, live provider calls, customer output, or completed-spec rewrites.

### Phase 1 - Tests First

Add focused failing tests for mandatory type normalization, compare labels, render summaries, readiness states, redaction, Claim Guard allowed/blocked phrases, RBAC scope, and no remote calls. Optional type tests must be added only after evidence is confirmed.

### Phase 2 - Typed Normalization

Implement the smallest Security/Compliance normalizer needed for selected evidence fields. Drop volatile fields, redact sensitive values, preserve stable identifiers only when operator-safe, and mark unsupported/high-risk fields for manual review.

### Phase 3 - Compare and Render

Implement deterministic compare labels and render summaries with domain-safe materiality. Summaries must show operator decisions first and must not surface raw provider payloads by default.

### Phase 4 - Readiness and Claim Guard

Derive bounded readiness states and importance labels. Harden Claim Guard so scoped internal/operator comparable/renderable claims are allowed while restore-ready, certified, customer-ready, legal/regulatory, broad Purview/Security, and 100 percent coverage claims are blocked.

### Phase 5 - Integration

Wire selected helpers into `CoverageV2ReadinessReadModel` or the repo-equivalent dispatch path without new registries or frameworks unless implementation evidence proves the existing dispatch pattern requires it.

### Phase 6 - Product Surface Proof

If rendered output changes, run a focused browser smoke on the existing Coverage v2 readiness/inspect route and record Human Product Sanity. If no rendered output changes, record exact N/A proof in the implementation report.

### Phase 7 - Validation and Report

Run the narrowest sufficient Sail/Pest validation, record commands/results, promoted/deferred type matrix, Product Surface Contract fields, Filament/Livewire posture, deployment impact, no-tenant-id proof, no-remote proof, and no completed-spec rewrite assertion.

## Stop Conditions

- A source contract, capture contract, live Graph/TCM/docs call, or Microsoft tenant write is needed.
- A migration, new table, new persisted enum/status taxonomy, new route/navigation/dashboard, or mini-platform appears necessary.
- A customer-facing report/output, certification, legal/regulatory attestation, restore/apply, or Review Pack claim is needed.
- Optional type support requires broad fixtures or evidence that is not already content-backed and bounded.
- Raw payloads, incident/content details, secrets, fingerprints, or internal debug fields must be default-visible to make the feature useful.
- Completed specs 414, 415, or 417-422 would need to be rewritten.