---
name: tenantpilot-provider-freshness-semantics
description: Hard-gate provider readiness, permission freshness, target scope, and provider-diagnostic semantics.
---

## Purpose

Use this skill to keep provider readiness and permission semantics truthful, fresh, scoped, and customer-safe without leaking provider internals into platform-core truth.

## Activate When

- Touching provider connection readiness, verification, consent, credentials, permissions, freshness, provider operation starts, target scope, provider diagnostics, or provider action guidance.
- Adding or changing provider status labels, badges, next steps, capability/permission checks, or provider health UI.
- Reviewing provider-specific semantics at a platform boundary.

## Do Not Activate When

- The task has no provider, credential, permission, freshness, or provider-boundary behavior.
- Microsoft/Graph is mentioned only as historical context in a docs-only task.

## Maturity

L4 hard gate.

## Gate Type

hard-gate.

## Source Evidence

- `.specify/memory/constitution.md`
- `docs/product/standards/product-surface-contract.md`
- `docs/security-guidelines.md`
- `specs/394-provider-freshness-permission-semantics/spec.md`
- `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`
- `apps/platform/app/Support/Providers/Readiness/ProviderReadinessResolver.php`
- `apps/platform/app/Support/Providers/Readiness/ProviderReadinessState.php`
- `apps/platform/app/Support/Providers/Readiness/ProviderPermissionReadinessState.php`
- `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php`
- `apps/platform/app/Support/Providers/Capabilities/ProviderCapabilityRegistry.php`
- `apps/platform/tests/Feature/ProviderConnections/Spec394ProviderFreshnessProductSanityTest.php`
- `apps/platform/tests/Unit/Providers/Spec394ProviderReadinessResolverTest.php`

## External Anchors

Not applicable.

## Required Repo Context

- Provider connection, credential, consent, permission, and freshness models/support classes.
- Provider readiness resolver and badge mappings.
- Target scope normalizer and provider boundary catalog.
- Product Surface canonical status vocabulary.
- Tests for stale, missing permission, disabled credential, readonly actor, and scoped target behavior.

## Execution Checklist

- Use resolver-backed provider readiness rather than page-local status logic.
- Map provider internals into canonical product-facing states before display.
- Preserve provider-specific values as provider-owned metadata or diagnostics, not platform-core ownership truth.
- Attach permission/readiness rows to workspace, managed environment, and provider connection scope.
- Show stale/expired/unknown readiness distinctly from ready.
- Keep raw provider payloads and credentials out of default UI, logs, audits, and notifications.
- Add tests for freshness, permission, target scope, and high-impact action gating where runtime behavior changes.

## Stop Conditions

- Stale provider state is labeled Healthy or Ready.
- Readiness labels lack freshness proof or last-checked semantics.
- Permission rows are unscoped or can be read across workspace/environment/provider boundaries.
- Page-local readiness logic bypasses the shared resolver.
- Raw provider payloads, credential material, or provider diagnostics become default-visible product content.
- Readonly users receive privileged repair CTAs or callable provider operations.
- Provider-specific identifiers become platform-core ownership or routing truth without a spec decision.

## Required Evidence After Use

- Resolver and state mapping path.
- Freshness timestamp/source proof.
- Scope proof for permission/readiness rows.
- Product-facing labels and technical diagnostic demotion.
- Tests or static proof for stale/ready and readonly/high-impact behavior.

## Common Failure Modes

- Showing old successful verification as current readiness.
- Using Healthy/OK/Warning as top-level product states.
- Exposing provider request/response detail in default panels.
- Treating Microsoft-specific scope labels as platform taxonomy.
- Adding per-page provider next-step logic instead of shared guidance.

## Quarantined Rules

Full Spec 416 quarantine list applies. Especially quarantined here: stale provider Healthy/Ready semantics; raw provider/evidence payload default display; `tenant_id` as platform-core ownership truth; historical audits as current truth.

## Review / Expiry

Review whenever provider readiness, provider capability, credential, consent, target-scope, or provider-boundary semantics change. No planned expiry.