TenantAtlas/specs/421-entra-core-comparable-renderable-pack/tasks.md

Tasks: Spec 421 - Entra Core Comparable / Renderable Pack

Input: Design documents from /specs/421-entra-core-comparable-renderable-pack/ Prerequisites: spec.md, plan.md, checklists/requirements.md, completed Specs 414, 415, 417, 418, 419, and 420 as read-only context Tests: Required. Runtime compare/render behavior must be covered with focused Pest unit and feature tests. Browser proof is required if rendered Coverage v2 output changes.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for typed normalization, compare/render, redaction, claims, scope, and Product Surface behavior.
• New or changed tests stay in the smallest honest family; browser coverage is explicit because rendered output changed.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling unrelated lane cost.
• Browser proof is completed with focused rendered UI coverage because rendered output changed.
• Human Product Sanity and Product Surface implementation-report close-out are planned where applicable.
• Any optional Entra type blocker is documented in the active spec or implementation report.

Phase 1: Preflight And Repo Truth

Purpose: Confirm current repo truth before implementation and prevent completed-spec rewrite.

• T001 Capture branch, HEAD, dirty state, activated skills, and hard-gate stop conditions in specs/421-entra-core-comparable-renderable-pack/implementation-report.md.
• T002 Verify Specs 414, 415, 417, 418, 419, and 420 are completed dependency context only and do not edit any files under their spec directories.
• T003 Inspect apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php, CoverageSourceContractResolver.php, GenericContentEvidenceCaptureService.php, CoverageIdentityStrategyRegistry.php, CanonicalIdentityResolver.php, ClaimGuard.php, and CoverageV2ReadinessReadModel.php to confirm current Coverage v2 service names before editing.
• T004 Build the Entra evidence matrix in specs/421-entra-core-comparable-renderable-pack/implementation-report.md for conditionalAccessPolicy, securityDefaults, application, servicePrincipal, roleDefinition, and administrativeUnit, classifying each as content-backed, missing-contract, unsupported, identity-blocked, or deferred.
• T005 Confirm no runtime task needs new capture/source contracts, restore/apply, certification, customer output, new OperationRun type, new route/navigation/action, new table, or tenant_id; stop and amend the spec if any is required.

Phase 2: Tests First - Typed Semantics And Claim Safety

Purpose: Lock the business truth before implementation.

• T006 [P] Add Conditional Access typed normalization tests in apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraConditionalAccessNormalizerTest.php.
• T007 [P] Add deterministic compare tests in apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraComparableDiffTest.php covering volatile-only no-change, state change, target change, grant control change, session control change, stable ordering, null/empty handling, redacted values, and unsupported fields.
• T008 [P] Add render summary tests in apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraRenderableSummaryTest.php covering operator-safe Conditional Access summaries and no raw payload dependency.
• T009 [P] Add redaction tests in apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraRedactionTest.php proving secrets, credentials, tokens, authorization headers, cookies, raw payload, provider response bodies, unsafe OperationRun diagnostic context, and unsafe audit metadata do not appear in render/compare summaries or any default-visible diagnostic output.
• T010 [P] Add Claim Guard tests in apps/platform/tests/Unit/Support/TenantConfiguration/Spec421EntraClaimGuardTest.php allowing scoped internal comparable/renderable wording and blocking certified, restore-ready, customer-ready, full, all-resource, and 100 percent Entra/M365 claims.
• T011 [P] Add evidence-gated promotion tests in apps/platform/tests/Feature/TenantConfiguration/Spec421EntraCoverageLevelPromotionTest.php proving conditionalAccessPolicy can promote only with content-backed evidence and missing-evidence Entra types remain unpromoted.
• T012 [P] Add no-restore/no-certification tests in apps/platform/tests/Feature/TenantConfiguration/Spec421EntraNoRestoreNoCertificationTest.php.
• T013 [P] Add no-tenant-id/no-mini-platform tests or static guards in apps/platform/tests/Feature/TenantConfiguration/Spec421EntraNoTenantIdTest.php and apps/platform/tests/Feature/TenantConfiguration/Spec421EntraNoMiniPlatformTest.php.
• T014 [P] Add read authorization, provider-scope, and no-remote-render tests in apps/platform/tests/Feature/TenantConfiguration/Spec421EntraComparableRenderableTest.php proving non-member/wrong-scope denial, member-missing-capability denial, same-scope provider connection requirements, and no Graph/TCM/provider calls during render/compare.

Phase 3: Evidence-Gated Promotion Path

Purpose: Promote only proven evidence-backed types.

• T015 Update or extend apps/platform/app/Services/TenantConfiguration/ResourceTypeRegistry.php only if needed to keep selected Entra comparable/renderable support internal and claim-safe; do not set restore/certified/customer defaults.
• T016 Update or extend the existing Coverage v2 promotion/read path in apps/platform/app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php or repo-equivalent service so comparable/renderable state is derived only from content-backed typed evidence.
• T017 Ensure securityDefaults, application, servicePrincipal, roleDefinition, and administrativeUnit stay unpromoted unless Phase 1 proves content-backed evidence and corresponding tests exist; record blockers in specs/421-entra-core-comparable-renderable-pack/implementation-report.md.
• T018 Confirm apps/platform/app/Support/TenantConfiguration/CoverageLevel.php existing values are reused and no new persisted coverage/status/importance enum is added.

Phase 4: Typed Entra Normalization

Purpose: Produce deterministic typed payloads for evidence-backed Entra types.

• T019 Add or extend a bounded typed normalizer in apps/platform/app/Services/TenantConfiguration/EntraComparablePayloadNormalizer.php or the repo-equivalent Tenant Configuration service path.
• T020 [P] Implement Conditional Access normalization for display name, state, included/excluded users/groups/roles, included apps/resources, conditions, grant controls, session controls, source version/schema, redacted diagnostics, and unsupported fields in the normalizer path from T019.
• T021 [P] Implement Security Defaults normalization only if Phase 1 proves content-backed evidence; otherwise keep a blocker path and corresponding tests. Deferred because current repo evidence does not prove a content-backed source contract.
• T022 [P] Implement optional application, servicePrincipal, roleDefinition, and administrativeUnit normalization only if Phase 1 proves content-backed evidence and the scope remains bounded; otherwise defer them in the implementation report. Deferred because current repo evidence does not prove content-backed source contracts.
• T023 Ensure typed normalization reuses apps/platform/app/Services/TenantConfiguration/CoveragePayloadRedactor.php or its repo-equivalent redaction path before render/compare output.

Phase 5: Deterministic Compare

Purpose: Compare selected Entra evidence without volatile noise or unsafe claims.

• T024 Add or extend a bounded comparator in apps/platform/app/Services/TenantConfiguration/EntraCoverageComparator.php or the repo-equivalent Tenant Configuration service path.
• T025 Implement change classification added, removed, changed, unchanged, ignored_volatile, redacted, and unsupported_field in the comparator path from T024.
• T026 Implement Conditional Access material change rules for enabled/state, included/excluded actors, app/resource targeting, conditions, grant controls, and session controls in the comparator path from T024.
• T027 Implement derived importance labels critical, important, and informational only inside compare output; do not add a persisted enum/status family.
• T028 Ensure compare ordering is deterministic for arrays where order is not semantically meaningful and null/empty handling is explicit.
• T029 Implement Security Defaults and optional type compare rules only when corresponding evidence-backed normalization exists; otherwise leave documented blockers.

Phase 6: Operator-Safe Render Summaries

Purpose: Let operators understand selected Entra resources without raw payloads.

• T030 Add or extend a render summary builder in apps/platform/app/Services/TenantConfiguration/EntraRenderableSummaryBuilder.php or the repo-equivalent Tenant Configuration service path.
• T031 Implement Conditional Access render summary fields: display name, state, included/excluded actor summary, included app/resource summary, conditions summary, grant/session control summary, claim state, identity state, last captured, unsupported fields, and redaction markers.
• T032 Implement Security Defaults render summary only if Phase 1 proves content-backed evidence; otherwise keep a blocker/deferred summary in the implementation report.
• T033 Ensure render summaries never expose raw payload, raw Graph response, tokens, credential values, private keys, certificate material, authorization headers, cookies, or unneeded PII.
• T034 If application/service principal rendering is promoted, summarize credentials only as safe presence/count/expiration/partial-key metadata according to repo convention. Not promoted; deferred in the implementation report.

Phase 7: Existing Surface Integration And Product Safety

Purpose: Reuse the existing read-only Coverage v2 surface without adding product-surface risk.

• T035 If rendered output changes, update apps/platform/app/Services/TenantConfiguration/CoverageV2ReadinessReadModel.php to expose typed summaries through existing inspect details while keeping raw/technical evidence demoted.
• T036 If rendered output changes, update existing inspect modal views under apps/platform/resources/views/filament/modals/tenant-configuration/ only as needed to display typed summaries with native/shared Filament semantics.
• T037 Confirm apps/platform/app/Filament/Pages/TenantConfiguration/CoverageV2Readiness.php, CoverageV2ResourceTypesTable.php, and CoverageV2ResourceInstancesTable.php expose no new action, route, navigation, start/capture, restore, certify, export, report, or customer output.
• T038 Confirm global search posture is unchanged because no Filament Resource is added or changed for global search.
• T039 Confirm no new assets are registered and no filament:assets requirement is introduced beyond existing deployment practice.
• T040 Ensure rendered labels do not include Entra covered, certified, restore-ready, customer-ready, full Entra coverage, 100% Entra, or broad M365 readiness wording.

Phase 8: Browser Proof If Rendered Output Changes

Purpose: Prove the existing surface remains safe when summaries render.

• T041 Add apps/platform/tests/Browser/Spec421EntraComparableRenderableOperatorSurfaceSmokeTest.php if rendered output changes.
• T042 In the browser smoke, seed a workspace, managed environment, provider connection, and Conditional Access content-backed evidence row with comparable/renderable summary data.
• T043 In the browser smoke, load the existing Coverage v2 readiness route, open the inspect flow, and assert comparable/renderable state, operator-readable Conditional Access summary, no raw payload, no secrets, no unsafe OperationRun/audit diagnostic metadata if diagnostics render, no restore/certified/customer-ready claim, no new high-impact action, no provider/network call during render, and no console/Livewire/Filament errors.
• T044 If no rendered output changes, document N/A - no rendered UI surface changed proof in specs/421-entra-core-comparable-renderable-pack/implementation-report.md instead of adding a browser test. Not applicable because rendered output changed and focused browser proof was added.

Phase 9: Validation And Close-Out

Purpose: Complete the implementation loop with explicit proof.

• T045 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T046 Run focused Spec 421 unit tests for normalization, compare, render, redaction, and Claim Guard.
• T047 Run focused Spec 421 feature tests for promotion, RBAC/scope, no restore/certification, no tenant_id, no mini-platform, and no overclaim.
• T048 Run focused Spec 421 browser test if rendered output changed, or record no-browser proof if not.
• T049 Run git diff --check.
• T050 Complete specs/421-entra-core-comparable-renderable-pack/implementation-report.md with candidate gate, dirty state before/after, files changed, Entra evidence matrix, promoted/deferred types, normalizer matrix, compare matrix, render matrix, Claim Guard proof, redaction proof including OperationRun diagnostic context and audit metadata posture, no restore/certification proof, no tenant_id proof, no mini-platform proof, Product Surface proof, tests run, browser/no-browser, deployment impact, and deferred work.
• T051 Confirm no completed historical spec was rewritten, normalized, reopened, or stripped of validation/task/browser/review history.

Dependencies

• Phase 1 blocks all implementation.
• Phase 2 tests should be written before or alongside Phases 3-7.
• Phase 3 promotion path depends on Phase 1 evidence matrix.
• Phase 4 typed normalization blocks Phases 5 and 6.
• Phase 7 depends on Phases 3-6 only if rendered output changes.
• Phase 8 depends on Phase 7 rendered output changes.
• Phase 9 closes after all relevant implementation and validation tasks.

Stop Conditions

• New capture/source contract work is needed for Security Defaults or optional types.
• Restore/apply, certification, customer output, report/download/export, or broad Entra/M365 claim is proposed.
• A new route, navigation entry, dashboard, action, OperationRun type, persisted compare table, or Entra-specific table family is proposed without amending this spec.
• Raw payloads, secrets, credentials, tokens, provider response bodies, source keys, or provider IDs become default-visible.
• tenant_id appears as Coverage v2 ownership truth.
• Render/compare performs provider/Graph/TCM/HTTP work during page render.

Implementation Strategy

Deliver the MVP first: Conditional Access content-backed evidence comparable/renderable, plus Claim Guard/redaction/no-overclaim proof. Treat every other Entra type as evidence-gated follow-through, not required scope. Stop and split if the implementation needs new capture contracts or broader product-surface work.