ahmido
332f6325cb
Automated PR provided by Codex via Gitea API. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #483
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
---
|
|
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.
|