TenantAtlas/.agent/skills/repo-contracts/provider-freshness-semantics/SKILL.md

name	description
tenantpilot-provider-freshness-semantics	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.