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 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)

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

Source Code (expected implementation touch points)

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.