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.