TenantAtlas/specs/394-provider-freshness-permission-semantics/tasks.md

Tasks: Spec 394 - Provider Freshness & Permission Semantics v1

Input: specs/394-provider-freshness-permission-semantics/spec.md and plan.md Prerequisites: Spec artifacts prepared; implementation must start from repo-truth verification and must not modify completed context specs. Tests: Required. This is a provider trust-boundary change with Unit, Feature/Filament, and bounded Browser proof.

Test Governance Checklist

• Lane assignment is confirmed as narrow: Unit for resolver logic, Feature/Filament for DB/scope/RBAC/UI action semantics, Browser for one focused visible provider-readiness smoke.
• New or changed tests stay in focused Spec394/provider families; no broad heavy-governance suite is added by default.
• Shared helpers, factories, provider setup, workspace membership, session state, and capability context stay explicit and cheap by default.
• Planned validation commands cover the changed behavior without pulling unrelated suite cost.
• PostgreSQL lane is added only if schema, partial indexes, locks, JSONB, or PostgreSQL-specific query behavior are introduced.
• Browser coverage is one named Spec394 smoke plus exact existing affected browser files where repo-real.
• Any material budget, baseline, trend, or escalation note is recorded in the implementation report.

Phase 1: Repo Truth And Provider Semantics Inventory

Purpose: Map current local provider truth before changing behavior.

• T001 Re-read specs/394-provider-freshness-permission-semantics/spec.md, plan.md, and tasks.md.
• T002 Re-read completed context specs as read-only inputs only: specs/281-provider-connection-scope, specs/283-provider-capability-registry, specs/294-provider-verification-runtime-semantics, specs/339-provider-connection-scope-hardening, specs/353-provider-connections-resolution-guidance-v1, and specs/381-provider-resource-identity-binding.
• T003 Confirm current branch and dirty state with git status --short --branch and git log -1 --oneline.
• T004 Inventory provider state selectors in apps/platform/app, apps/platform/resources, apps/platform/routes, apps/platform/tests, config, and localization files using search terms from the spec: provider health, healthy, readiness, required permissions, present, granted, missing, verification, stale, freshness, admin consent, Graph permission, OAuth scope, provider connection.
• T005 Record inventory in the implementation report: file, current logic, visible label, count source, provider scope, freshness source, permission source, authorization rule, stale-as-healthy risk, row/count mismatch risk, and migration decision.
• T006 Inspect apps/platform/app/Models/ProviderConnection.php and apps/platform/app/Models/ManagedEnvironmentPermission.php for existing fields and casts usable by the resolver.
• T007 Inspect apps/platform/app/Services/Intune/ManagedEnvironmentPermissionService.php and apps/platform/app/Services/Intune/ManagedEnvironmentRequiredPermissionsViewModelBuilder.php for count, grant, filter, freshness, and copy semantics.
• T008 Inspect apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php, apps/platform/app/Support/ResolutionGuidance/Adapters/ProviderReadinessResolutionAdapter.php, and apps/platform/app/Support/Providers/Capabilities/ProviderCapabilityEvaluator.php for current readiness/freshness duplication.
• T009 Inspect Provider Connections, Required Permissions, Environment Dashboard, Workspace Overview, Governance Inbox, restore/evidence/review readiness consumers, and support diagnostics for provider state display or action links.
• T010 Confirm no migration, package, env var, queue, scheduler, storage topology, Graph scope, panel-provider, route family, onboarding wizard, new dashboard/card, or customer-facing provider detail is required; stop and update spec/plan if false.
• T011 Confirm Filament v5 / Livewire v4.0+ compliance and no Filament v3/v4 or Livewire v3 APIs.
• T012 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.
• T013 Confirm ProviderConnectionResource remains non-globally-searchable and no global search participation is added.

Phase 2: Canonical Resolver Contract And Unit Tests

Purpose: Prove provider readiness semantics before replacing surfaces.

• T014 Add focused unit tests for the canonical provider readiness resolver under apps/platform/tests/Unit/Providers/Spec394ProviderReadinessResolverTest.php or the nearest repo-consistent provider test namespace.
• T015 [P] Test fresh verification plus all required permissions effective returns Ready.
• T016 [P] Test stale verification plus old grants returns Expired or non-ready, never Healthy or Ready.
• T017 [P] Test verification failed returns Failed and not ready.
• T018 [P] Test no verification returns Unknown and not ready.
• T019 [P] Test connected provider without verification returns Unknown or Needs attention, not ready.
• T020 [P] Test missing required permission returns Needs attention and not ready.
• T021 [P] Test blocked/admin consent denied returns Blocked.
• T022 [P] Test wrong workspace grant does not satisfy a permission.
• T023 [P] Test wrong environment grant does not satisfy a permission.
• T024 [P] Test wrong provider connection grant does not satisfy a permission.
• T025 [P] Test stale verification grant produces Expired permission row state.
• T026 [P] Test count invariant: required_count = granted + missing + blocked + expired + unknown.
• T027 [P] Test deterministic ordering when multiple grants exist.
• T028 [P] Test actor without manage capability receives no provider-changing action.
• T029 [P] Test actor without technical permission receives no raw technical payload/detail action.
• T030 Implement or consolidate ProviderReadinessResolver in the narrowest repo-consistent namespace, likely under apps/platform/app/Support/Providers or apps/platform/app/Services/Providers.
• T031 Implement resolver result, aggregate result, and permission row shapes as derived contracts without adding persisted state by default.
• T032 Ensure resolver performs DB-only scoped decisions and no Graph/provider calls during render.
• T033 Ensure resolver exposes canonical count fields and row states from the same result object/array.

Phase 3: Required Permissions Page Counts And Rows

Purpose: Replace ambiguous Present semantics with canonical row/count behavior.

• T034 Add or update Feature/Filament tests for EnvironmentRequiredPermissions canonical counts and row states.
• T035 Test Required Permissions page does not show Present 0 when grants are effective.
• T036 Test stale verification shows Expired rows or verification-needed copy and does not count stale grants as granted.
• T037 Test missing required permission produces actionable copy and correct next action.
• T038 Update ManagedEnvironmentRequiredPermissionsViewModelBuilder to consume or delegate to the canonical resolver for product-facing counts/rows.
• T039 Update apps/platform/resources/views/filament/pages/environment-required-permissions.blade.php labels from Present/ambiguous counts to canonical Required, Granted, Missing, Blocked, Expired, and Unknown labels.
• T040 Keep raw provider permission names secondary/technical, not primary product labels.
• T041 Ensure filter behavior remains useful without preserving old present product copy; update filter state only if needed and remove old tests/fixtures that assert misleading labels.
• T042 Ensure copy payloads still copy missing-only permission names and do not expose raw JSON or technical dumps.

Phase 4: Provider Connections And Provider Guidance Consumers

Purpose: Stop Provider Connections from mapping stale/partial state to Healthy or Ready.

• T043 Add or update Feature/Filament tests proving Provider Connection list/view/edit do not show Healthy or Ready for stale verification.
• T044 Add or update tests proving fresh verification plus full effective permissions shows Ready.
• T045 Add or update tests proving connected-only provider state is not enough for readiness.
• T046 Update ProviderConnectionSurfaceSummary to delegate readiness and primary provider capability summary to the canonical resolver or remove its independent readiness mapping.
• T047 Update ProviderReadinessResolutionAdapter to consume resolver output or delegate its stale/missing/failed decisions to the resolver while preserving Spec 353 guidance hierarchy.
• T048 Update Provider Connection Resource/Page display fields, badges, and action visibility to use resolver output.
• T049 Ensure provider verification primary action is shown only when actor has the correct capability and verification is the correct recommended action.
• T050 Ensure existing high-impact/destructive provider actions retain ->action(...), confirmation where required, authorization, audit logging, and tests.
• T051 Update ProviderVerificationStatusBadge or consuming code so stale healthy does not render as product Healthy; preserve internal status only where explicitly technical.

Phase 5: Dashboard, Workspace Overview, Governance Inbox, And Downstream Readiness

Purpose: Ensure direct provider readiness consumers share canonical provider truth.

• T052 Add or update Environment Dashboard tests proving stale provider cannot appear ready/healthy and dashboard primary action points to verification/remediation.
• T053 Add or update Workspace Overview tests where repo-real provider/readiness signals exist.
• T054 Add or update Governance Inbox tests where provider-related items exist.
• T055 Add or update restore/evidence/review readiness tests only where those surfaces directly consume provider state.
• T056 Update EnvironmentDashboardSummaryBuilder provider blocker/readiness logic to consume resolver output rather than local required-permission counts where applicable.
• T057 Update WorkspaceOverviewBuilder provider/readiness aggregation where repo-real to consume resolver aggregate child results, scoped only to actor-authorized environments.
• T058 Update GovernanceInboxSectionBuilder provider-related items where repo-real.
• T059 Update direct downstream readiness consumers such as restore/evidence/review readiness adapters only enough to prevent provider blockers from being overridden.
• T060 Document any remaining local provider logic path in the implementation report with reason, risk, and follow-up.

Phase 6: Scope Matching, RBAC, And Technical Detail Gating

Purpose: Make effective permissions scope-safe and action-safe.

• T061 Add tests proving wrong workspace/environment/provider connection/provider account/provider namespace grants are excluded, using the current ProviderConnection identity and same-provider verification context as the v1 provider-account/context source. If repo data cannot express a required provider-account distinction, stop and update spec/plan before implementation.
• T062 Add tests proving actor without view capability cannot view provider detail result or route.
• T063 Add tests proving readonly/view-only actors can see product-safe summary but cannot trigger verify/reconnect/manage provider actions.
• T064 Add tests proving manage-capable actors can access supported verify/reconnect actions.
• T065 Add tests proving raw provider payload, grant IDs, OAuth token details, and Graph/API dumps are not visible in default product UI.
• T066 Ensure resolver receives actor context and computes can_view_technical_detail and can_manage_provider from existing policy/capability paths.
• T067 Ensure UI surfaces use UiEnforcement or WorkspaceUiEnforcement where appropriate and server-side Gate/Policy checks still enforce actions.
• T068 Ensure technical detail falls back to stricter provider manage capability if no granular technical capability exists.
• T069 Ensure audit metadata for any touched provider-changing action remains redacted and contains no secrets or raw payloads.

Phase 7: Legacy Label, Fixture, Translation, And Guard Cleanup

Purpose: Remove old semantics rather than compatibility-shimming them.

• T070 Search for product-facing Present, Present 0, Provider Healthy, Healthy, Ready, OK, Current, permission count, and raw grant labels in provider/readiness surfaces.
• T071 Replace or remove legacy product labels and stale translation keys that preserve old semantics.
• T072 Update fixtures and factories that create granted rows without fresh verification semantics or correct scope.
• T073 Update old tests that assert misleading provider health, stale readiness, Present counts, or wrong-scope grants.
• T074 Add or update guard tests where practical to ensure stale verification does not map to healthy/ready through the resolver.
• T075 Add or update count-invariant guard tests where practical.
• T076 Add string guards for deprecated ambiguous labels only if they are not too noisy and do not block legitimate technical/admin documentation.
• T077 Do not add aliases, fallback readers, dual-write logic, compatibility shims, old route aliases, or tests preserving old behavior.

Phase 8: Browser Smoke

Purpose: Prove visible product behavior on real surfaces.

• T078 Add or update apps/platform/tests/Browser/Spec394ProviderFreshnessPermissionSmokeTest.php using existing provider/required-permission fixture helpers where practical.
• T079 Browser state: stale provider is not shown as Healthy or Ready.
• T080 Browser state: fresh fully-permissioned provider is shown as Ready.
• T081 Browser state: Required Permissions counts match visible rows.
• T082 Browser state: Present 0 or equivalent ambiguous legacy count is absent.
• T083 Browser state: missing permissions produce actionable copy.
• T084 Browser state: readonly user cannot trigger provider management actions.
• T085 Browser state: manage-capable user can access verify/reconnect where supported.
• T086 Browser state: no raw provider payload/default technical permission dump is visible.
• T087 Browser state: no 500/Livewire/Filament/console errors in affected flows.
• T088 Run existing affected browser tests if present: Spec353ProviderReadinessGuidanceSmokeTest, provider connection smoke tests, Required Permissions smoke tests, Environment Dashboard smoke tests, Workspace Overview smoke tests, Governance Inbox smoke tests.

Phase 9: Validation, UI Coverage, And Close-Out

Purpose: Prove the implementation and record the trust-boundary outcome.

• T089 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec394.
• T090 Run targeted provider/permission/verification feature tests: cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections tests/Feature/RequiredPermissions tests/Feature/Verification.
• T091 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec394ProviderFreshnessPermissionSmokeTest.php.
• T092 Run exact existing affected browser tests discovered during implementation when they cover changed flows.
• T093 Update docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md and ui-077-required-permissions.md only if visible page behavior materially changed, or document explicit no-route/no-archetype/no-count-impact decisions in the implementation report.
• T094 Run cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent.
• T095 Run git diff --check.
• T096 Confirm no migrations, packages, env vars, queues, scheduler, storage topology, Graph contracts/calls, panel providers, route family, onboarding wizard, dashboard/card, raw provider panel, or legacy compatibility path were added unless spec/plan were updated first.
• T097 Complete the required implementation report with files changed, resolver/API, replaced local logic, count source, tests, browser flows, stale-not-healthy evidence, count-row evidence, wrong-scope evidence, no compatibility shim, no UI complexity increase, and unrelated failures.
• T098 Complete human product sanity check over Provider Connections, Required Permissions, Environment Dashboard provider area, Workspace Overview provider area, and Governance Inbox provider-related item before marking Spec 394 done.

Dependencies

• Phase 1 must complete before runtime implementation.
• Phase 2 resolver tests should land before or alongside resolver implementation.
• Phase 3 and Phase 4 depend on resolver output.
• Phase 5 depends on resolver adoption in direct provider surfaces.
• Phase 6 can run alongside Phases 3-5 after the resolver accepts actor context.
• Phase 8 runs after targeted tests and UI label/action changes.
• Phase 9 closes the feature.

Parallel Execution Examples

• T006-T009 can be split by repo surface during inspection.
• T015-T029 can be implemented in parallel as independent resolver test cases.
• T034-T037 can run in parallel with T043-T045 after resolver result shape is stable.
• T052-T055 can be split by downstream surface once direct provider surfaces are updated.
• T061-T065 can run in parallel with UI adoption to lock RBAC and raw-detail boundaries.

Non-Goals / Stop Conditions

• Stop if implementation requires a new persisted verification batch, permission grant table, provider readiness table, provider-account identifier, or status ledger; update spec/plan first.
• Stop if a page-local product-facing provider health calculation appears necessary; fold it into the resolver or document a bounded exception.
• Stop if the only way to keep a test green is to preserve stale-as-healthy, Present, wrong-scope grant, or stale-grant behavior.
• Stop if scope expands into new provider integration, OAuth redesign, onboarding wizard, dashboard/card, customer-facing provider detail, raw permission panel, or broad Product Surface Contract Enforcement.
• Do not rewrite, normalize, uncheck, or remove implementation history from completed Specs 281, 283, 294, 339, 353, or 381.

Required Final Report Content For Later Implementation

When implementation later completes, report:

• Files changed.
• Resolver/API created or consolidated.
• Old local provider health/readiness logic removed or replaced.
• Required permission count logic source.
• Tests added/updated.
• Browser flows run.
• Evidence that stale verification no longer renders Healthy or Ready.
• Evidence that required permission counts match rows.
• Evidence that wrong-scope grants are excluded.
• Confirmation that no legacy compatibility shim was added.
• Confirmation that visible UI complexity did not increase.
• Remaining known unrelated failures, if any.