TenantAtlas/specs/425-entra-certified-compare-pack/plan.md

# Implementation Plan: Spec 425 - Entra Certified Compare Pack

**Branch**: `425-entra-certified-compare-pack` | **Date**: 2026-07-01 | **Spec**: [spec.md](./spec.md)  
**Input**: Feature specification from `specs/425-entra-certified-compare-pack/spec.md`

## Summary

Prepare the first internal/operator certified Coverage v2 pack: `entra_core_compare_certified`. The implementation should evaluate exactly two resource types, `conditionalAccessPolicy` and `securityDefaults`, against evidence, stable identity, deterministic compare, operator-safe render, redaction, and Claim Guard criteria. Certification is derived and DB-only by default. No restore/apply, customer output, full Entra claim, Microsoft 365 claim, new Entra dashboard, new route/navigation, `tenant_id`, or Entra-specific table family is in scope.

## Technical Context

**Language/Version**: PHP 8.4, Laravel 12, Filament v5, Livewire v4  
**Primary Dependencies**: Existing Coverage v2 Tenant Configuration services: `ResourceTypeRegistry`, `SupportedScopeResolver`, `CoverageSourceContractResolver`, `CoverageIdentityStrategyRegistry`, `CoverageV2ReadinessReadModel`, `CoveragePayloadRedactor`, `ClaimGuard`, `EntraComparablePayloadNormalizer`, `EntraCoverageComparator`, `EntraRenderableSummaryBuilder`  
**Storage**: PostgreSQL through existing Coverage v2 resource/evidence/supported-scope tables; no new table planned  
**Testing**: Pest 4, PHPUnit 12, focused Unit/Feature, Browser only if UI changes  
**Validation Lanes**: fast-feedback for unit/feature; browser conditional; Pint dirty; diff check  
**Target Platform**: Laravel Sail locally, Dokploy container deployment  
**Project Type**: Laravel web monolith under `apps/platform`  
**Performance Goals**: Certification evaluation is DB-only and bounded to the exact two-item denominator  
**Constraints**: no remote calls during evaluation, no restore/apply, no customer claim activation, no full Entra/M365 claim, no `tenant_id`, no new Entra table family, no v1 compatibility, no completed-spec rewrites  
**Scale/Scope**: exactly one certified compare/render pack with two mandatory resource types

## Preparation Preflight Result

- Current branch before creation: `platform-dev`.
- Current HEAD before creation: `2cd51291 feat: complete spec 424 security defaults content-backed comparable support (#491)`.
- Initial dirty state: clean.
- Spec 424 direct prerequisite: complete at current HEAD.
- Current source evidence:
  - `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php` maps both denominator types.
  - `apps/platform/config/graph_contracts.php` defines both denominator contracts.
  - `apps/platform/app/Services/TenantConfiguration/CoverageIdentityStrategyRegistry.php` requires stable non-derived identity for both types.
  - `apps/platform/app/Services/TenantConfiguration/EntraComparablePayloadNormalizer.php`, `EntraCoverageComparator.php`, and `EntraRenderableSummaryBuilder.php` support both types.
  - `apps/platform/app/Services/TenantConfiguration/CoverageEvidenceWriter.php` promotes renderable content-backed evidence through existing typed render builders.
  - `apps/platform/app/Services/TenantConfiguration/ClaimGuard.php` currently blocks broad certification/restore/customer/M365 claims and must be extended for exact pack wording.
- Direct related specs completed/read-only: 414, 415, 417, 418, 419, 420, 421, 424.
- Implementation must re-run hard preflight before runtime edits and stop if current source/tests contradict these findings.

## UI / Surface Guardrail Plan

- **Guardrail scope**: possible existing operator technical-annex status/evidence presentation change; no new surface.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: existing Coverage v2 readiness/operator surface only if implementation needs rendered certification display.
- **No-impact class, if applicable**: service/config/test-only if no runtime UI file changes are needed.
- **Native vs custom classification summary**: existing Filament/Coverage v2 surface; no custom UI pattern planned.
- **Shared-family relevance**: status messaging, evidence inspection, claim display, redaction.
- **State layers in scope**: read model / existing inspect details only if UI changes.
- **Audience modes in scope**: operator-MSP and support-platform; no customer/read-only output.
- **Decision/diagnostic/raw hierarchy plan**: pack state and denominator first; blockers second; raw/support evidence hidden or omitted.
- **Raw/support gating plan**: raw payloads, raw Graph response, raw permission context, and secrets remain absent from default output.
- **One-primary-action / duplicate-truth control**: one read-only inspect/blocker path; no mutation action.
- **Handling modes by drift class or surface**: UI changes require Product Surface proof and browser smoke; new route/navigation/customer output is a hard stop.
- **Repository-signal treatment**: review-mandatory for status/evidence presentation; hard-stop for new route/navigation/customer/restore scope.
- **Special surface test profiles**: technical-annex Coverage v2 surface if UI changes; N/A if service/config/test-only.
- **Required tests or manual smoke**: functional core tests always; browser smoke only if rendered UI changes.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **UI/Productization coverage decision**: `N/A - no rendered UI surface changed` by default; existing surface only after active artifacts are amended.
- **Coverage artifacts to update**: none unless implementation adds a new reachable surface, which is currently forbidden.
- **No-impact rationale**: Certification can be proven by services, supported-scope metadata, fixtures, and tests without adding a new page.
- **Navigation / Filament provider-panel handling**: no panel/provider/navigation change.
- **Screenshot or page-report need**: browser screenshot/proof only if rendered UI files change.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: canonical Coverage v2 extension; no compatibility exception.
- **Page archetype and surface budget plan**: Technical Annex if existing surface changes; pass because no new page/action/navigation and one read-only inspect path.
- **Technical Annex and deep-link demotion plan**: OperationRun, evidence IDs, source endpoint, source keys, raw payloads, permission context, provider diagnostics, and raw compare values remain hidden/collapsed/internal-only.
- **Canonical status vocabulary plan**: Product labels map to `Ready`, `Blocked`, `Needs attention`, or `Unknown` if rendered. Internal derived blocker states remain diagnostics.
- **Product Surface exceptions**: none.
- **Browser verification plan**: `N/A - no rendered UI surface changed` unless UI files change; otherwise focused existing Coverage v2 route smoke.
- **Human Product Sanity plan**: N/A unless UI changes; otherwise record in implementation report.
- **Visible complexity outcome target**: neutral or decreased.
- **Implementation report target**: `specs/425-entra-certified-compare-pack/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: unchanged; platform remains Filament v5 on Livewire v4. Must be stated in close-out.
- **Panel provider registration location**: no panel change planned. Laravel 12 provider registration remains `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no Resource or global search change planned.
- **Destructive/high-impact action posture**: none. No restore/apply/certify action may be introduced.
- **Asset strategy**: no new assets planned. `filament:assets` is not newly required unless implementation unexpectedly registers assets, which would require spec amendment.
- **Testing plan**: Unit/Feature for evaluator, denominator, claim guard, redaction, no restore/customer/tenant_id/mini-platform; Browser only if UI changes.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, or assets expected. If supported-scope defaults change, existing `tenant-configuration:sync-defaults` deployment step may be needed and must be documented.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: Coverage v2 resource type registry, supported scopes, evidence/read model, Entra compare/render helpers, redaction, Claim Guard.
- **Shared abstractions reused**: `SupportedScopeResolver`, `ClaimGuard`, `CoveragePayloadRedactor`, `CoverageV2ReadinessReadModel`, `EntraComparablePayloadNormalizer`, `EntraCoverageComparator`, `EntraRenderableSummaryBuilder`.
- **New abstraction introduced? why?**: A narrow derived evaluator service may be introduced if existing supported-scope evaluation cannot compose pack-level criteria. No persisted truth or generic certification framework.
- **Why the existing abstraction was sufficient or insufficient**: Existing helpers prove row-level evidence/identity/compare/render/redaction. They do not yet compose exact two-type denominator certification and exact claim wording.
- **Bounded deviation / spread control**: evaluator is pack-specific, internal/operator-only, and must not become an Entra mini-platform or cross-domain certification framework in this spec.

## 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**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

Certification evaluation must not create or mutate `OperationRun`. It may read existing operation-backed evidence linkage. If long-running/batch behavior becomes necessary, stop and amend the spec.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes.
- **Provider-owned seams**: Microsoft Entra canonical types, Graph/TCM source contracts, provider source identifiers.
- **Platform-core seams**: Coverage level, supported scope, evidence state, identity state, claim guard, redaction, workspace/managed-environment/provider scope.
- **Neutral platform terms / contracts preserved**: supported scope, resource type, evidence, identity, claim, provider connection, managed environment.
- **Retained provider-specific semantics and why**: The denominator is deliberately Microsoft Entra-specific and exact.
- **Bounded extraction or follow-up path**: document-in-feature for this pack; future workload packs require separate specs.

## Constitution Check

- Inventory-first / evidence truth: PASS. Certification derives from existing Coverage v2 evidence, not provider live state.
- Read/write separation: PASS. Read/evaluate/render only; no restore/apply or mutation action.
- Graph contract path: PASS. No new evaluation Graph calls; existing source contracts remain read-only dependency truth.
- Deterministic capabilities: PASS. Certification criteria and denominator are testable by fixtures.
- RBAC-UX: PASS with implementation requirement. Any invocation path must enforce non-member 404 and member missing capability 403.
- Workspace isolation: PASS with implementation requirement. Evaluation must remain same workspace/managed environment/provider connection scoped.
- Tenant isolation: PASS in current repo vocabulary; no `tenant_id` ownership truth.
- Run observability: PASS. Evaluation is DB-only and skips OperationRun by design.
- OperationRun start UX: N/A.
- Data minimization: PASS. Raw and permission payloads must not render.
- Test governance: PASS. Unit/Feature lane is sufficient unless UI changes.
- Proportionality: PASS. Derived evaluator avoids persistence and broad frameworkization.
- No premature abstraction: PASS only if evaluator stays pack-specific and no generic certification platform appears.
- Persisted truth: PASS. No new table.
- Behavioral state: PASS if certification blocker states remain derived and have clear reviewer consequences.
- UI semantics: PASS if existing Coverage v2 surface is reused and no runtime Product Surface framework is introduced.
- Shared pattern first: PASS. Existing Coverage v2/Claim Guard/redaction paths are reused.
- Provider boundary: PASS with bounded provider-owned denominator.
- V1 explicitness / few layers: PASS. Direct pack implementation only.
- Spec discipline / bloat check: PASS. Scope groups the certification semantics into one coherent spec.
- Filament-native UI: N/A unless existing UI changes.
- Product Surface Contract: PASS with conditional browser/Human Product Sanity requirements.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for pure evaluator/claim/compare/render/redaction; Feature for DB/scope/supported scope/no-overreach/no-tenant_id/no-mini-platform; Browser only if UI changes.
- **Affected validation lanes**: fast-feedback; browser conditional.
- **Why this lane mix is the narrowest sufficient proof**: Certification is derived from deterministic services and persisted evidence rows. Browser is only needed for rendered UI proof.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/EntraCertifiedPackEvaluatorTest.php tests/Unit/Support/TenantConfiguration/EntraCertifiedPackClaimGuardTest.php tests/Unit/Support/TenantConfiguration/ConditionalAccessCertifiedCompareTest.php tests/Unit/Support/TenantConfiguration/SecurityDefaultsCertifiedCompareTest.php tests/Unit/Support/TenantConfiguration/EntraCertifiedRenderRedactionTest.php tests/Unit/Support/TenantConfiguration/EntraCertifiedDenominatorTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec425EntraCertifiedComparePackTest.php tests/Feature/TenantConfiguration/Spec425EntraCertifiedClaimGuardFeatureTest.php tests/Feature/TenantConfiguration/Spec425EntraCertifiedNoRestoreTest.php tests/Feature/TenantConfiguration/Spec425EntraCertifiedNoCustomerClaimTest.php tests/Feature/TenantConfiguration/Spec425EntraCertifiedNoTenantIdTest.php tests/Feature/TenantConfiguration/Spec425EntraCertifiedNoMiniPlatformTest.php tests/Feature/TenantConfiguration/Spec425EntraCertifiedDenominatorFeatureTest.php`
- **Fixture / helper / factory / seed / context cost risks**: focused golden fixtures for two resource types; avoid broad default fixture setup.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none unless browser proof is triggered.
- **Surface-class relief / special coverage rule**: N/A if no rendered UI change; technical-annex focused browser if UI changes.
- **Closing validation and reviewer handoff**: verify denominator, blocker states, exact claim allowance/blocking, redaction, no restore/customer/tenant_id/mini-platform, and no remote calls.
- **Budget / baseline / trend follow-up**: none expected.
- **Review-stop questions**: Does any task create a generic certification framework, persisted table, customer output, restore action, or broad claim? If yes, split/stop.
- **Escalation path**: reject-or-split for restore/customer/full-workload scope; document-in-feature for bounded existing-surface UI proof.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: This is the dedicated exact-denominator certification slice; broader packs are deferred.

## Project Structure

### Documentation (this feature)

```text
specs/425-entra-certified-compare-pack/
├── checklists/
│   └── requirements.md
├── plan.md
├── spec.md
└── tasks.md
```

### Source Code (repository root)

Likely affected runtime/test paths for later implementation:

```text
apps/platform/app/Services/TenantConfiguration/
├── ClaimGuard.php
├── SupportedScopeResolver.php
├── EntraComparablePayloadNormalizer.php
├── EntraCoverageComparator.php
├── EntraRenderableSummaryBuilder.php
└── EntraCertifiedComparePackEvaluator.php        # only if needed

apps/platform/tests/Fixtures/TenantConfiguration/Spec425/
├── conditional-access/
└── security-defaults/

apps/platform/tests/Unit/Support/TenantConfiguration/
└── *Certified*.php

apps/platform/tests/Feature/TenantConfiguration/
└── Spec425*.php

apps/platform/tests/Browser/
└── Spec425EntraCertifiedComparePackOperatorSurfaceSmokeTest.php  # only if UI changes
```

**Structure Decision**: Use existing TenantConfiguration/Coverage v2 service and test directories. Do not create new base folders outside test fixtures unless implementation proves an existing location is insufficient.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|---|---|---|
| Derived certification evaluator | Pack-level certification needs denominator-wide evidence/identity/compare/render/redaction/claim composition | Resource-level `renderable` checks would allow one mandatory type or claim criterion to fail silently |
| Derived certification blocker states | Reviewers need actionable blocker reasons for withheld certification | A boolean pass/fail would hide whether evidence, identity, compare, render, redaction, or claim guard failed |

## Proportionality Review

- **Current operator problem**: Internal operators need safe exact certification wording after Specs 421 and 424 without implying restore, full Entra, Microsoft 365, or customer proof.
- **Existing structure is insufficient because**: Existing helpers prove individual resource behavior, not exact denominator integrity or pack-level claims.
- **Narrowest correct implementation**: Add exact supported-scope metadata and one derived evaluator or equivalent existing-scope evaluation; no persistence, no dashboard, no generic certification framework.
- **Ownership cost created**: A small fixture/test set must be maintained when Conditional Access or Security Defaults compare/render changes.
- **Alternative intentionally rejected**: Setting `allows_certified_claims` on each resource type and relying on current Claim Guard. That misses denominator integrity and exact wording controls.
- **Release truth**: Current-release internal/operator certification proof.

## Technical Approach

### Phase 0 - Hard Preflight

- Confirm branch, HEAD, dirty state, and active spec path.
- Confirm Spec 424 is present in current history and the Security Defaults runtime support still exists.
- Confirm `conditionalAccessPolicy` and `securityDefaults` have source contracts, content-backed evidence paths, stable identity strategies, deterministic compare, render builder support, redaction, and no-restore/customer/certified default posture.
- Stop before implementation if either type fails the hard prerequisites.

### Phase 1 - Certified Denominator And Supported Scope

- Add or confirm the supported scope key `entra_core_compare_certified` in the existing Coverage v2 supported-scope mechanism.
- Include exactly `conditionalAccessPolicy` and `securityDefaults`.
- Set required minimum level to `certified`.
- Set `customer_claims_allowed = false`.
- Set `allow_beta = false`.
- Allow Graph fallback only explicitly for `securityDefaults`, preferably through metadata allowlist plus evaluator enforcement because the existing scope model has a boolean `allow_graph_fallback`.
- Add tests proving no optional Entra resource can enter the denominator.

### Phase 2 - Certification Evaluator

- Implement a derived evaluator only if existing supported-scope evaluation cannot produce the certification matrix.
- Evaluate:
  - evidence criteria, including current same-scope evidence and no fallback-to-first/latest behavior
  - identity criteria
  - compare criteria
  - render criteria
  - redaction criteria
  - Claim Guard criteria
- Return derived blocker states:
  - `certification_not_evaluated`
  - `certification_passed`
  - `certification_blocked_missing_evidence`
  - `certification_blocked_identity`
  - `certification_blocked_compare`
  - `certification_blocked_render`
  - `certification_blocked_redaction`
  - `certification_blocked_claim_guard`
- Keep states local/derived unless the spec is amended.

### Phase 3 - Golden Fixtures

- Add focused golden fixtures for Conditional Access:
  - no change
  - state change
  - grant control change
  - included actor change
  - excluded actor change
  - app/resource targeting change
  - condition change
  - session control change
  - volatile ignored
  - unsupported field diagnostics
- Add focused golden fixtures for Security Defaults:
  - no change
  - enabled true/false change
  - volatile ignored
  - missing evidence
  - identity blocked
  - redaction proof

### Phase 4 - Claim Guard

- Allow exact internal/operator visible wording only when the denominator is included:
  - `Certified Entra Core Compare Pack: Conditional Access and Security Defaults`
  - `Certified compare support for Conditional Access and Security Defaults`
  - `Certified compare/render support for the Entra Core denominator: Conditional Access and Security Defaults`
- The bare label `Certified Entra Core Compare Pack` may exist as an internal scope label or diagnostic row heading only when the same visible context includes the denominator.
- Require exact denominator visibility when a certification claim is shown.
- Block broad/full Entra, 100 percent, Microsoft 365, restore-ready, customer-ready, legal/regulatory, full tenant proof, and Review Pack/report wording.

### Phase 5 - Product Surface Decision

- Prefer no runtime UI file changes if evaluator tests prove certification.
- If implementation changes rendered UI, amend active artifacts before editing UI files and add focused browser proof.
- Do not add route, navigation, dashboard, customer output, restore/apply, report, export, or Review Pack output.

### Phase 6 - Tests And Validation

- Add focused unit tests first.
- Add focused feature/static tests.
- Add browser test only if UI changes.
- Run Pint dirty, focused test lanes, and `git diff --check`.

### Phase 7 - Implementation Report

- Complete `specs/425-entra-certified-compare-pack/implementation-report.md`.
- Include required certification and claim matrices.
- Record no restore, no customer output, no `tenant_id`, no mini-platform, no remote calls, Product Surface result, tests, and deferred work.

## Data Model Impact

- No new persisted table.
- No new Entra-specific table family.
- No `tenant_id`.
- Existing supported-scope metadata may be updated.
- Certification result should remain derived unless an existing supported-scope evaluation summary already persists such results. If persistence is needed outside existing Coverage v2 supported-scope evaluation, stop and amend the spec.

## RBAC / Isolation Plan

- Any service/command/UI invocation must receive or resolve workspace, managed environment, and provider connection scope explicitly.
- Non-member workspace or managed-environment access returns 404.
- Member without view/evaluate capability returns 403.
- Provider connection must belong to the same workspace and managed environment.
- Evaluation must not fallback to first/latest records outside scope.
- Feature or service-level tests must cover wrong-scope and missing-capability behavior for any service, command, route, or UI invocation boundary. If no callable boundary is added beyond a pure injected service, the implementation report must record why route/command 404/403 proof is N/A and still prove explicit same-scope service inputs.

## OperationRun / Observability Plan

- No new `OperationRun`.
- No new job.
- No new queue/scheduler.
- Existing operation-backed evidence links may be read.
- No remote/provider call is allowed during certification evaluation.

## Claim And Redaction Plan

- Claim Guard is the authoritative claim safety layer.
- Raw payload, raw Graph response, raw permission context, secrets, tokens, cookies, authorization headers, private keys, certificate material, and credential values must not appear in render output, Claim Guard proof, UI, implementation report snippets, logs, notifications, or OperationRun context.
- Tests must fail if sensitive values appear in certification matrix or render summary output.

## Rollout Considerations

- Staging validation is required before production if runtime code changes.
- No environment variable changes expected.
- No migration expected.
- If supported scope defaults are updated, deployment notes must mention whether `cd apps/platform && php artisan tenant-configuration:sync-defaults` is required for existing environments.
- Rollback should be code/config/test only unless the implementation amends the spec to persist summaries.

## Stop Conditions

- Either denominator type lacks content-backed evidence, stable identity, deterministic compare, safe render, or redaction proof.
- Denominator changes from exactly two resource types.
- Restore/apply, customer output, full Entra, M365, Review Pack/report/PDF/export, or legal attestation scope appears.
- A new Entra dashboard, route, navigation item, primary surface, table family, or mini-platform appears.
- `tenant_id` is introduced as platform-core ownership truth or compatibility/fallback path.
- Evaluation requires remote calls or a long-running job.
- Raw payloads, provider response bodies, permission context, credentials, or secrets become default-visible.
- Implementation requires persistence outside existing Coverage v2 supported-scope/evaluation paths.