.agent/skills/README.md

@@ -0,0 +1,83 @@
+# TenantPilot Agent Skill Layer v1
+
+This directory contains repository-specific agent skills for TenantPilot/TenantAtlas work. The skills turn validated repo contracts into focused activation checklists for future implementation, review, and audit sessions.
+
+This layer is not a replacement for active specs, tests, code review, current repo truth, or the TenantPilot constitution. If a skill conflicts with the active spec, `.specify/memory/constitution.md`, current application code, or current tests, current repo truth wins and the skill must be updated.
+
+The corrected Spec 416 skill library lives under `.agent/skills/**`. `.codex/skills/**` is not the Spec 416 implementation target.
+
+## Progressive Disclosure
+
+Do not load all TenantPilot skills by default. Activate only the skill or skills that match the current task trigger, then read the active spec, plan, tasks, and source evidence named by that skill.
+
+Use this README as an index only. Individual `SKILL.md` files carry the gate/checklist details.
+
+## Maturity Model
+
+| Level | Meaning |
+| --- | --- |
+| L0 | Reference note only; never a gate. |
+| L1 | Advisory pattern; useful context but not blocking. |
+| L2 | Workflow checklist; use for bounded inspection or audit work. |
+| L3 | Review checklist gate; complete before claiming readiness. |
+| L4 | Hard gate; stop implementation or review when the stop conditions trigger. |
+
+## Gate Types
+
+| Gate type | Meaning |
+| --- | --- |
+| hard-gate | Blocks unsafe runtime or review work until the issue is resolved or the active spec is amended. |
+| checklist | Requires explicit evidence before completion, but may produce documented residual risk. |
+| workflow | Guides a bounded audit or non-mutating workflow. |
+| temporary-migration-gate | Applies only during a named migration/cutover window and must expire. |
+
+## V1 Skill Activation Table
+
+| Skill | Maturity | Gate type | Activate when |
+| --- | --- | --- | --- |
+| `workflows/spec-readiness-gate` | L3 | checklist | Implementing, reviewing, or validating an active Spec Kit package. |
+| `repo-contracts/workspace-scope-safety` | L4 | hard-gate | Touching workspace, managed environment, provider connection, tenant scope, route binding, queries, exports, downloads, jobs, or data ownership. |
+| `repo-contracts/rbac-action-safety` | L4 | hard-gate | Touching policies, gates, capabilities, Filament actions, destructive/high-impact actions, global search, or hidden/disabled UI affordances. |
+| `repo-contracts/operation-run-truth` | L4 | hard-gate | Creating, updating, reconciling, displaying, linking, deduplicating, retrying, or completing `OperationRun` records. |
+| `repo-contracts/customer-output-gate` | L4 | hard-gate | Touching review packs, customer/auditor output, report downloads, rendered reports, customer workspaces, or customer-safe labels. |
+| `repo-contracts/evidence-anchor-contract` | L4 | hard-gate | Touching evidence anchors, evidence snapshots, proof currentness, review evidence, baseline evidence, or evidence-backed customer claims. |
+| `repo-contracts/provider-freshness-semantics` | L4 | hard-gate | Touching provider readiness, provider verification, permissions, freshness, provider connection status, consent, credentials, or provider diagnostics. |
+| `repo-contracts/product-surface-gate` | L3 | checklist | Touching rendered UI, routes, navigation, actions, downloads, reports, readiness, evidence, restore flows, customer output, or Product Surface Contract behavior. |
+| `workflows/filament-livewire-v5-change-loop` | L3 | checklist | Touching Laravel 12, Filament v5, Livewire v4, panel providers, resources, pages, widgets, actions, tables, forms, global search, or Filament assets. |
+| `workflows/browser-readonly-audit` | L2/L3 | workflow | Running a read-only browser audit, smoke inspection, product-surface audit, or browser evidence collection without mutating state. |
+| `temporary-migrations/tcm-cutover-guard` | L3 | temporary-migration-gate | Touching Coverage v2, TCM kernel/capture, legacy coverage vocabulary, v1/v2 cutover, or customer/operator coverage claims. |
+
+## Quarantined Rules
+
+Do not preserve or reintroduce these historical or unsafe rules:
+
+- `tenant_id` as platform-core ownership truth.
+- Coverage v1 vocabulary as customer truth.
+- v1-v2 adapters.
+- fallback readers.
+- dual writes.
+- fallback-to-latest evidence.
+- OperationRun as default customer proof.
+- stale provider Healthy/Ready semantics.
+- limited customer download vocabulary.
+- raw provider/evidence payload default display.
+- Product Surface runtime framework.
+- historical audits as current truth.
+
+Current repo truth uses workspace, managed environment, provider connection, operation, evidence, and customer-safe output boundaries. Historical specs, audits, and prompts are evidence only when current code, active specs, and the constitution still agree with them.
+
+## Currentness
+
+Before relying on a skill, check the active spec package and current source evidence. Skills must be maintained when these change materially:
+
+- `.specify/memory/constitution.md`
+- `AGENTS.md`
+- `docs/ai-coding-rules.md`
+- `docs/*-guidelines.md`
+- `docs/product/standards/product-surface-contract.md`
+- relevant runtime source and tests
+- active `specs/<NNN>-<slug>/spec.md`, `plan.md`, and `tasks.md`
+
+## Temporary Skill Warning
+
+`tenantpilot-tcm-cutover-guard` is temporary. It expires after Coverage v2 / TCM activation and legacy coverage vocabulary cutover are complete. Once expired, replace it with current activation/cutover truth instead of carrying stale migration warnings forward.

.agent/skills/repo-contracts/customer-output-gate/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: tenantpilot-customer-output-gate
+description: Hard-gate customer-safe output, review/report downloads, and customer/auditor visibility boundaries.
+---
+
+## Purpose
+
+Use this skill to prevent internal evidence, permissions, OperationRun details, raw payloads, and technical diagnostics from being exposed as customer-safe output or product-default proof.
+
+## Activate When
+
+- Touching review packs, environment reviews, stored reports, rendered reports, management PDFs, customer review workspace, customer/auditor routes, report downloads, or review publication.
+- Adding output labels such as customer-safe, ready, blocked, publishable, downloadable, complete, or current.
+- Changing controller-backed downloads, signed links, streamed reports, or internal preview paths.
+
+## Do Not Activate When
+
+- The task has no customer/auditor output, report, download, review, or rendered product proof behavior.
+- The task is an internal-only docs/tooling change and cannot alter runtime output.
+
+## Maturity
+
+L4 hard gate.
+
+## Gate Type
+
+hard-gate.
+
+## Source Evidence
+
+- `docs/product/standards/product-surface-contract.md`
+- `docs/security-guidelines.md`
+- `specs/400-product-contract-spec-completeness-audit/spec.md`
+- `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`
+- `apps/platform/app/Support/ReviewPacks/CustomerOutputGate.php`
+- `apps/platform/app/Support/ReviewPacks/CustomerOutputGateDecision.php`
+- `apps/platform/app/Http/Controllers/ReviewPackDownloadController.php`
+- `apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php`
+- `apps/platform/app/Http/Controllers/ManagementReportPdfDownloadController.php`
+- `apps/platform/tests/Feature/ReviewPack/Spec392CustomerOutputRouteGateTest.php`
+- `apps/platform/tests/Unit/Support/ReviewPacks/Spec392CustomerOutputGateTest.php`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Output route/controller and authorization path.
+- `CustomerOutputGate` decision logic.
+- Source evidence and currentness contract for the output.
+- Audience mode: customer/read-only, operator/MSP, or support/platform.
+- Default-visible content and hidden technical detail boundaries.
+- Download/streaming tests and route tests.
+
+## Execution Checklist
+
+- Gate output through explicit customer-output decision logic, not permissions alone.
+- Confirm workspace/managed-environment scope before streaming or downloading.
+- Keep raw JSON, payloads, fingerprints, source keys, provider request details, and internal reason ownership out of customer defaults.
+- Demote OperationRun, raw evidence, and technical audit details to authorized internal paths.
+- Use canonical customer-safe status vocabulary from Product Surface Contract.
+- Preserve one dominant customer/operator next action.
+- Add tests for authorized output, denied output, blocked output, and internal-preview behavior where runtime output changes.
+
+## Stop Conditions
+
+- Output is allowed solely because the actor has permission.
+- Blocked output can still be streamed or downloaded.
+- Customer-safe label is applied without evidence/currentness proof.
+- Customer CTA points directly to internal-only technical detail as the primary path.
+- Page-local readiness logic duplicates or bypasses `CustomerOutputGate`.
+- Raw provider/evidence payloads are default-visible to customer/read-only users.
+
+## Required Evidence After Use
+
+- Route/controller and gate decision proof.
+- Scope and authorization proof.
+- Customer-visible default content summary.
+- Technical/internal detail demotion proof.
+- Tests or explicit N/A for docs-only work.
+
+## Common Failure Modes
+
+- Treating report existence as publishability.
+- Exposing internal preview links in customer paths.
+- Letting OperationRun or evidence snapshot IDs become customer proof.
+- Adding download verbs without blocked-state tests.
+- Using stale or internal readiness labels as customer-facing truth.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: OperationRun as default customer proof; limited customer download vocabulary; raw provider/evidence payload default display; fallback-to-latest evidence; historical audits as current truth.
+
+## Review / Expiry
+
+Review whenever customer output gates, review/report downloads, rendered reports, or customer/auditor boundary semantics change. No planned expiry.

.agent/skills/repo-contracts/evidence-anchor-contract/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: tenantpilot-evidence-anchor-contract
+description: Hard-gate evidence anchor currentness, scope, fallback behavior, and proof/customer-safety boundaries.
+---
+
+## Purpose
+
+Use this skill to ensure evidence anchors and evidence-backed claims point to scoped, current, explicit evidence instead of falling back to latest, unrelated, stale, or internal-only proof.
+
+## Activate When
+
+- Touching evidence snapshots, evidence anchors, evidence resolvers, baseline evidence, review pack evidence, evidence overview, currentness, proof links, or evidence-backed statuses.
+- Adding evidence source providers, anchor IDs, artifact references, evidence publication, or evidence currentness claims.
+- Changing customer/auditor evidence visibility.
+
+## Do Not Activate When
+
+- The task does not touch evidence, proof, currentness, review/report output, or evidence-backed UI/state.
+- The task only reads historical evidence as context.
+
+## Maturity
+
+L4 hard gate.
+
+## Gate Type
+
+hard-gate.
+
+## Source Evidence
+
+- `.specify/memory/constitution.md`
+- `docs/product/standards/product-surface-contract.md`
+- `specs/400-product-contract-spec-completeness-audit/spec.md`
+- `specs/415-generic-content-backed-capture/implementation-report.md`
+- `apps/platform/app/Services/Evidence/EvidenceAnchorResolver.php`
+- `apps/platform/app/Services/Evidence/EvidenceSnapshotResolver.php`
+- `apps/platform/app/Services/Evidence/EvidenceSnapshotService.php`
+- `apps/platform/app/Policies/EvidenceSnapshotPolicy.php`
+- `apps/platform/app/Models/TenantConfigurationResourceEvidence.php`
+- `apps/platform/tests/Unit/Evidence/Spec393EvidenceAnchorResolverTest.php`
+- `apps/platform/tests/Feature/Monitoring/Spec403EvidenceCurrentnessRuntimeClosureTest.php`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Evidence-producing source and lifecycle.
+- Scope columns and ownership for evidence and target subject.
+- Currentness and freshness contract.
+- Customer/operator/support visibility of proof.
+- Resolver fallback behavior.
+- Tests for missing, stale, wrong-scope, and current evidence.
+
+## Execution Checklist
+
+- Resolve evidence by explicit anchor and same workspace/managed-environment/provider scope.
+- Keep append-only evidence immutable unless the active spec explicitly permits a lifecycle transition.
+- Distinguish evidence payload truth from OperationRun execution truth.
+- Do not fallback to latest evidence unless the active spec explicitly approves and discloses the behavior.
+- Mark stale, expired, historical, or superseded evidence with Product Surface canonical vocabulary where rendered.
+- Keep raw evidence payloads hidden by default and capability-gated when exposed.
+- Add tests for wrong-scope, missing-anchor, stale, and current evidence behavior where runtime changes.
+
+## Stop Conditions
+
+- Resolver falls back to latest evidence when requested evidence is missing.
+- Evidence anchor can point to the wrong workspace, managed environment, provider connection, or subject.
+- Raw OperationRun/evidence is treated as customer-safe proof by default.
+- Released or historical evidence is claimed as live current.
+- Stale proof is displayed as current without disclosure.
+- Evidence payloads, secrets, or raw provider data leak into logs, notifications, OperationRun context, or customer output.
+
+## Required Evidence After Use
+
+- Anchor resolution path and scope proof.
+- Currentness/staleness behavior.
+- Customer/operator/support disclosure boundary.
+- Tests or static proof for fallback and wrong-scope behavior.
+- Confirmation that evidence proof does not rely on OperationRun alone.
+
+## Common Failure Modes
+
+- Reconstructing proof from whichever snapshot is newest.
+- Treating completed runs as evidence currentness.
+- Rendering raw JSON because it is convenient support proof.
+- Duplicating evidence status logic in a page instead of the evidence contract.
+- Linking customer users directly to technical evidence artifacts.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: fallback-to-latest evidence; OperationRun as default customer proof; raw provider/evidence payload default display; Coverage v1 vocabulary as customer truth; historical audits as current truth.
+
+## Review / Expiry
+
+Review whenever evidence resolver, publication, currentness, customer-proof, or evidence storage contracts change. No planned expiry.

.agent/skills/repo-contracts/operation-run-truth/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: tenantpilot-operation-run-truth
+description: Hard-gate OperationRun lifecycle, execution truth, summary counts, reconciliation, and customer-proof boundaries.
+---
+
+## Purpose
+
+Use this skill to keep `OperationRun` as execution truth for queued/remote/long-running work without turning it into customer-safe proof or duplicate domain truth.
+
+## Activate When
+
+- Creating, queuing, deduplicating, resuming, retrying, reconciling, completing, blocking, deep-linking, or displaying `OperationRun` records.
+- Adding jobs, provider/Graph work, restore/backup/sync/report/evidence operations, terminal notifications, or run actionability.
+- Touching `OperationRunService`, operation summary counts, queued execution gates, run notifications, or operation links.
+
+## Do Not Activate When
+
+- The change is DB-only and not security-relevant, remote, queued, long-running, observable, or user-facing.
+- The task only reads OperationRun history as context and does not change behavior or claims.
+
+## Maturity
+
+L4 hard gate.
+
+## Gate Type
+
+hard-gate.
+
+## Source Evidence
+
+- `.specify/memory/constitution.md`
+- `docs/architecture-guidelines.md`
+- `docs/performance-guidelines.md`
+- `docs/testing-guidelines.md`
+- `specs/415-generic-content-backed-capture/implementation-report.md`
+- `apps/platform/app/Services/OperationRunService.php`
+- `apps/platform/app/Support/OpsUx/OperationSummaryKeys.php`
+- `apps/platform/app/Notifications/OperationRunCompleted.php`
+- `apps/platform/app/Services/Operations/OperationRunOperatorActionService.php`
+- `apps/platform/tests/Feature/OperationRunServiceTest.php`
+- `apps/platform/tests/Feature/OpsUx/OperationRunSummaryCountsIncrementTest.php`
+- `apps/platform/tests/Feature/Operations/Spec367OperationRunActionabilityResolverTest.php`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Operation type and catalog entry.
+- Run ownership fields: workspace, managed environment, target scope, initiator.
+- Start surface and queued job path.
+- `OperationRunService` status/outcome transition methods.
+- Summary count key/value handling.
+- Notification and audit behavior.
+- Customer-facing proof/evidence surface, if any.
+
+## Execution Checklist
+
+- Use `OperationRunService` for status/outcome transitions.
+- Keep direct status/outcome writes out of feature code except approved context-only updates.
+- Route remote/provider work through jobs/services, not UI render.
+- Keep summary counts flat, numeric, and limited to `OperationSummaryKeys::all()`.
+- Use central OperationRun start UX/link/notification patterns when UI is involved.
+- Keep queued DB notifications explicit opt-in.
+- Keep raw payloads, secrets, credentials, and provider error bodies out of OperationRun context/messages.
+- Separate OperationRun execution truth from evidence payload truth and customer-safe proof.
+- Add tests for lifecycle, idempotency, stale active runs, summary counts, and authorization where runtime behavior changes.
+
+## Stop Conditions
+
+- Direct OperationRun status/outcome writes bypass service-owned lifecycle.
+- Remote provider or Graph calls happen during render.
+- A feature creates duplicate local run truth or competing status fields.
+- OperationRun is presented as default customer proof.
+- Stale active runs have no reconciliation or blocked-state path.
+- Summary counts include non-numeric values or unregistered keys.
+- Raw payloads, secrets, tokens, or sensitive provider details enter run context/messages/notifications.
+
+## Required Evidence After Use
+
+- Operation type and lifecycle path.
+- Service-owned transition proof.
+- Summary key proof.
+- Authorization and scope proof for run access/actionability.
+- Customer-proof boundary: evidence/report claims do not rely on OperationRun alone.
+- Tests or reasoned N/A for non-runtime/docs-only work.
+
+## Common Failure Modes
+
+- Treating a queued run as proof that evidence is current or customer-safe.
+- Local feature code composing its own run notifications and links.
+- Writing stale/failed reconciliation as UI-only labels.
+- Persisting provider payload snippets in run messages for debugging.
+- Creating run records without enough target scope to reauthorize the job.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: OperationRun as default customer proof; fallback-to-latest evidence; raw provider/evidence payload default display; historical audits as current truth.
+
+## Review / Expiry
+
+Review whenever OperationRun lifecycle, start UX, reconciliation, summary counts, notification policy, or customer proof semantics change. No planned expiry.

.agent/skills/repo-contracts/product-surface-gate/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: tenantpilot-product-surface-gate
+description: Checklist gate for TenantPilot Product Surface Contract compliance and no-runtime-framework drift.
+---
+
+## Purpose
+
+Use this skill to ensure rendered product-surface changes satisfy the Product Surface Contract without turning the contract into a runtime framework or new semantic layer.
+
+## Activate When
+
+- Touching rendered UI, routes, navigation, Filament panels/providers, Livewire/Blade surfaces, tables, forms, modals, drawers, actions, reports, downloads, readiness, evidence, provider state, restore flows, or customer output.
+- Preparing or reviewing Product Surface fields in a spec, plan, tasks, checklist, implementation report, or PR close-out.
+- Auditing visible complexity, one-primary-action discipline, technical demotion, or canonical product status vocabulary.
+
+## Do Not Activate When
+
+- The active spec is genuinely docs-only, tooling-only, template-only, or test-only and records `N/A - no rendered UI surface changed`.
+- The task only reads a completed historical UI spec as context.
+
+## Maturity
+
+L3 checklist.
+
+## Gate Type
+
+checklist.
+
+## Source Evidence
+
+- `docs/product/standards/product-surface-contract.md`
+- `.specify/README.md`
+- `.specify/memory/constitution.md`
+- `.specify/templates/spec-template.md`
+- `.specify/templates/plan-template.md`
+- `.specify/templates/tasks-template.md`
+- `specs/395-product-surface-gate/implementation-report.md`
+- `docs/ui/operator-ux-surface-standards.md`
+- `docs/ui/action-surface-contract.md`
+- `docs/ui-ux-enterprise-audit/README.md`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Active spec Product Surface Impact, UI Surface Impact, Browser Verification Plan, Human Product Sanity, and implementation-report target.
+- Affected route/page/resource/component/action paths.
+- Existing route inventory, design coverage, page reports, and standards where relevant.
+- Browser proof plan or justified no-browser rationale.
+
+## Execution Checklist
+
+- Confirm no-legacy posture or approved compatibility exception.
+- Confirm affected surfaces are named and classified.
+- Confirm one page archetype, one primary question, one primary action, and surface budget result.
+- Confirm Technical Annex/deep-link demotion for OperationRuns, raw evidence, IDs, source keys, detectors, payloads, and logs.
+- Confirm canonical status vocabulary or explicit mapping.
+- Confirm Product Surface exceptions are `none` or fully documented.
+- Confirm focused browser proof or `N/A - no rendered UI surface changed`.
+- Confirm Human Product Sanity result or no-surface rationale.
+- Confirm visible complexity outcome.
+- Confirm implementation report includes Livewire v4, provider registration, global search, destructive/high-impact actions, asset strategy, deployment impact, and completed-spec rewrite assertion.
+
+## Stop Conditions
+
+- Runtime UI changes start before the active spec/plan names affected surfaces and Product Surface decisions.
+- UI changes introduce competing primary statuses or actions.
+- Raw proof, OperationRun links, IDs, payloads, or provider diagnostics are default-visible on product-facing pages.
+- Product Surface guidance is implemented as a runtime presenter, enum/status family, persisted taxonomy, component framework, or broad redesign engine.
+- A page-local truth resolver duplicates canonical domain truth.
+- Completed specs are rewritten to retrofit newer wording.
+
+## Required Evidence After Use
+
+- Product Surface decision summary.
+- Browser proof or no-browser rationale.
+- Human Product Sanity outcome or N/A rationale.
+- Visible complexity result.
+- Exceptions or explicit `none`.
+- Files changed and no completed-spec rewrite assertion.
+
+## Common Failure Modes
+
+- Treating Product Surface as copy-only cleanup while leaving rendered behavior unchanged.
+- Adding another readiness/status layer rather than reducing visible complexity.
+- Keeping technical proof in default views because it is useful for support.
+- Recording `No UI surface impact` while changing routes/navigation/actions.
+- Creating a runtime Product Surface framework.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: Product Surface runtime framework; OperationRun as default customer proof; raw provider/evidence payload default display; stale provider Healthy/Ready semantics; historical audits as current truth.
+
+## Review / Expiry
+
+Review whenever the Product Surface Contract, UI standards, Spec Kit templates, or implementation-report close-out fields change. No planned expiry.

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

@@ -0,0 +1,98 @@
+---
+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.

.agent/skills/repo-contracts/rbac-action-safety/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: tenantpilot-rbac-action-safety
+description: Hard-gate TenantPilot RBAC, capability, global-search, and destructive/high-impact action safety.
+---
+
+## Purpose
+
+Use this skill to keep TenantPilot authorization server-side, capability-driven, tenant/workspace-safe, and tested for both visible UI affordances and direct execution.
+
+## Activate When
+
+- Adding or changing Filament actions, table actions, bulk actions, header actions, form actions, or controller mutations.
+- Touching policies, gates, capabilities, `UiEnforcement`, `WorkspaceUiEnforcement`, or global search.
+- Adding destructive or high-impact operations such as delete, force delete, restore, archive, retry, sync, snapshot, provider disable, credential rotation, publish, export, or evidence capture.
+
+## Do Not Activate When
+
+- The task has no runtime authorization, action, global search, or mutation surface.
+- The task only updates docs/tooling and explicitly cannot change runtime files.
+
+## Maturity
+
+L4 hard gate.
+
+## Gate Type
+
+hard-gate.
+
+## Source Evidence
+
+- `docs/security-guidelines.md`
+- `docs/filament-guidelines.md`
+- `docs/testing-guidelines.md`
+- `docs/research/filament-v5-notes.md`
+- `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`
+- `apps/platform/app/Support/Rbac/UiEnforcement.php`
+- `apps/platform/app/Support/Rbac/WorkspaceUiEnforcement.php`
+- `apps/platform/app/Policies/ProviderConnectionPolicy.php`
+- `apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php`
+- `apps/platform/tests/Feature/Rbac/AdminGlobalSearchContextSafetyTest.php`
+- `apps/platform/tests/Feature/Rbac/UiEnforcementDestructiveTest.php`
+
+## External Anchors
+
+- Filament v5 actions confirmation docs and global search docs cited in `docs/research/filament-v5-notes.md`.
+
+## Required Repo Context
+
+- The affected panel/resource/page/relation manager/action.
+- Existing policy and capability constants.
+- `UiEnforcement` or `WorkspaceUiEnforcement` usage.
+- Direct execution tests for action handlers.
+- Global search pages, title attributes, scoped queries, and View/Edit page posture.
+
+## Execution Checklist
+
+- Enforce authorization in the handler through policy/gate/service, not only via hidden UI.
+- Apply `UiEnforcement` or `WorkspaceUiEnforcement` for visible/disabled affordances.
+- Use canonical capability constants, not raw role strings.
+- Make destructive/high-impact actions execute through `->action(...)`.
+- Require `->requiresConfirmation()` for destructive/high-impact actions.
+- Write audit logs for mutating security/governance actions.
+- Add tests for allowed, denied/disabled, direct execution denial, side effects, audit, and scope where behavior changes.
+- Disable global search unless the resource has safe View/Edit pages, title attributes, scoped URLs, and non-member-safe results.
+
+## Stop Conditions
+
+- Missing server-side authorization for a mutation or operation start.
+- Destructive/high-impact action lacks `->action(...)` or `->requiresConfirmation()`.
+- Hidden UI remains directly callable through Livewire/action APIs.
+- Global search can reveal inaccessible records, labels, URLs, or relationship details.
+- Authorization uses role strings or unregistered capability strings in new code.
+- Mutating action lacks audit evidence where the domain requires auditability.
+
+## Required Evidence After Use
+
+- Policy/gate/capability path.
+- UI affordance path and direct execution path.
+- Tests proving allowed and denied behavior.
+- Confirmation of global search posture for changed resources.
+- Audit behavior for mutating or high-impact actions.
+
+## Common Failure Modes
+
+- Confusing action visibility with authorization.
+- Assuming confirmation works on URL-only actions.
+- Using per-record UI filters while leaving bulk/direct action paths open.
+- Enabling global search on tenant-sensitive resources without safe detail routes.
+- Returning 403 where deny-as-not-found 404 is required for non-member scope.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: stale provider Healthy/Ready semantics; limited customer download vocabulary; raw provider/evidence payload default display; historical audits as current truth.
+
+## Review / Expiry
+
+Review whenever RBAC planes, capabilities, Filament action rules, or global search posture change. No planned expiry.

.agent/skills/repo-contracts/workspace-scope-safety/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: tenantpilot-workspace-scope-safety
+description: Hard-gate workspace, managed-environment, provider-connection, and tenant-scope safety for TenantPilot changes.
+---
+
+## Purpose
+
+Use this skill to prevent workspace, managed-environment, provider-connection, or tenant-scope leakage in runtime code, specs, tests, jobs, routes, downloads, exports, and review surfaces.
+
+## Activate When
+
+- Touching models, migrations, policies, queries, route model binding, relation managers, exports, downloads, jobs, or services with workspace or managed-environment data.
+- Introducing or reading provider connection scope.
+- Handling user-supplied IDs, route parameters, signed links, queued job payloads, or background operation context.
+- Reviewing whether non-member access should be 404 and member-missing-capability should be 403.
+
+## Do Not Activate When
+
+- The task is docs-only and does not describe scope, ownership, authorization, or runtime data semantics.
+- The task only reads completed historical artifacts as context.
+
+## Maturity
+
+L4 hard gate.
+
+## Gate Type
+
+hard-gate.
+
+## Source Evidence
+
+- `.specify/memory/constitution.md`
+- `docs/security-guidelines.md`
+- `docs/architecture-guidelines.md`
+- `docs/ai-coding-rules.md`
+- `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`
+- `specs/415-generic-content-backed-capture/implementation-report.md`
+- `apps/platform/app/Policies/ProviderConnectionPolicy.php`
+- `apps/platform/app/Support/Rbac/UiEnforcement.php`
+- `apps/platform/app/Support/Rbac/WorkspaceUiEnforcement.php`
+- `apps/platform/tests/Feature/Rbac/ProviderConnectionAccessBoundaryTest.php`
+- `apps/platform/tests/Feature/TenantConfiguration/Spec415ProviderConnectionScopeTest.php`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Owning model relationships and casts.
+- Migrations and constraints for the touched tables.
+- Existing policies/gates and capability registry usage.
+- Query scopes, relation managers, route bindings, controller lookups, and queued job payloads.
+- Positive and negative tests for same-workspace and cross-workspace behavior.
+
+## Execution Checklist
+
+- Resolve workspace before managed environment and provider connection.
+- Verify provider connections are same-workspace and same-managed-environment when used for environment-owned work.
+- Use scoped lookups instead of `find()` or fallback-to-first/latest behavior.
+- Make non-member or wrong-scope access deny-as-not-found.
+- Keep provider-native tenant identifiers as metadata, not platform-core ownership truth.
+- Validate queued jobs re-resolve scope from trusted IDs before work.
+- Add or update negative tests for guessed IDs, wrong workspace, wrong managed environment, and wrong provider connection where runtime behavior changes.
+
+## Stop Conditions
+
+- Runtime code introduces `tenant_id` as platform-core ownership truth.
+- A lookup can resolve records outside the current workspace or managed environment.
+- A provider connection can be attached to or used for the wrong workspace/environment.
+- Code falls back to first, latest, default, or implicit records when scope cannot be resolved.
+- Cross-workspace data can be rendered, exported, downloaded, queued, mutated, or linked.
+- Scope-sensitive behavior lacks a negative test and the change is runtime/security-relevant.
+
+## Required Evidence After Use
+
+- Scoped lookup path and owner columns.
+- Authorization result semantics for wrong-scope and missing-capability cases.
+- Tests or static proof covering cross-workspace/cross-environment denial.
+- Confirmation that no `tenant_id` platform-core ownership path was added.
+
+## Common Failure Modes
+
+- Treating a visible tenant selector as authorization.
+- Reusing provider-native tenant IDs as database ownership.
+- Allowing relation managers to attach unrelated records.
+- Storing queue context that bypasses handle-time revalidation.
+- Letting global search leak inaccessible labels or URLs.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: `tenant_id` as platform-core ownership truth; fallback readers; dual writes; fallback-to-latest evidence; historical audits as current truth.
+
+## Review / Expiry
+
+Review whenever ownership schema, workspace routing, provider connection scope, or RBAC semantics change. No planned expiry.

.agent/skills/temporary-migrations/tcm-cutover-guard/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: tenantpilot-tcm-cutover-guard
+description: Temporary migration gate for Coverage v2 / TCM activation, legacy coverage vocabulary cutover, and customer-claim safety.
+---
+
+## Purpose
+
+Use this temporary skill to prevent incomplete Coverage v2 / TCM kernel or capture work from becoming customer/operator proof, legacy adapters, fallback readers, dual truth, or runtime activation before the cutover is explicitly complete.
+
+## Activate When
+
+- Touching Coverage v2, TCM kernel, tenant configuration resource types, supported scopes, concrete resources, evidence capture, TCM/Graph contract decisions, legacy coverage vocabulary, or v1/v2 cutover.
+- Adding customer/operator claims about Coverage v2, supported scope, capture completeness, or TCM readiness.
+- Reviewing specs that follow Specs 414 or 415.
+
+## Do Not Activate When
+
+- The task has no Coverage v2, TCM, coverage vocabulary, capture evidence, or customer/operator coverage claim behavior.
+- The Coverage v2 / TCM activation and legacy vocabulary cutover have been completed and this skill has been retired.
+
+## Maturity
+
+L3 temporary migration gate.
+
+## Gate Type
+
+temporary-migration-gate.
+
+## Source Evidence
+
+- `specs/414-tcm-first-coverage-core-cutover/implementation-report.md`
+- `specs/415-generic-content-backed-capture/implementation-report.md`
+- `specs/415-generic-content-backed-capture/spec.md`
+- `.specify/memory/constitution.md`
+- `apps/platform/app/Models/TenantConfigurationResourceType.php`
+- `apps/platform/app/Models/TenantConfigurationResource.php`
+- `apps/platform/app/Models/TenantConfigurationResourceEvidence.php`
+- `apps/platform/app/Support/TenantConfiguration/EvidenceState.php`
+- `apps/platform/tests/Feature/TenantConfiguration/Spec415NoLegacyNoUiActivationTest.php`
+- `apps/platform/tests/Feature/TenantConfiguration/TenantConfigurationKernelSchemaTest.php`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Spec 414 kernel status and inactive scope.
+- Spec 415 capture/evidence status and no-UI/no-legacy guard.
+- Tenant configuration migrations/models/services/tests.
+- Graph contract registry and provider gateway path if capture is touched.
+- Customer/operator surfaces that might display coverage claims.
+
+## Execution Checklist
+
+- Confirm whether Coverage v2 is still inactive for customer/operator proof.
+- Confirm no v1-to-v2 adapter, fallback reader, dual write, old snapshot promotion, or old gap taxonomy dependency is added.
+- Confirm no `.tenant_id` platform-core ownership field appears in Coverage v2 ownership schema.
+- Keep provider-native tenant IDs as metadata only.
+- Keep raw and normalized payloads as internal evidence storage, not default UI/report content.
+- Keep remote/provider capture queued and OperationRun-backed when used.
+- Use explicit Graph contracts; do not guess endpoints.
+- Stop before adding UI/start surfaces or customer claims unless the active spec is amended for Product Surface, browser proof, RBAC, and customer-output gates.
+
+## Stop Conditions
+
+- Remote capture is required but no Graph contract exists.
+- UI activation or customer/operator proof is added by a kernel/capture-only spec.
+- Legacy adapters, fallback readers, or dual truth paths are introduced.
+- `tenant_id` becomes Coverage v2 ownership truth.
+- Customer-facing claims depend on inactive TCM kernel or unactivated Coverage v2.
+- Raw provider/evidence payloads are rendered by default.
+- Capture bypasses same-scope provider connection or OperationRun/service lifecycle safeguards.
+
+## Required Evidence After Use
+
+- Whether Coverage v2 is inactive, active, or in explicit cutover.
+- Proof that no legacy adapter/fallback/dual write was added.
+- Ownership schema proof: workspace, managed environment, provider connection, and no `tenant_id` platform ownership.
+- Customer/operator UI impact or `N/A - no rendered UI surface changed`.
+- Tests or static guards for no-legacy/no-UI/no-customer-claim behavior.
+
+## Common Failure Modes
+
+- Treating Coverage v2 internal evidence as customer-ready coverage truth.
+- Reading old snapshots as v2 evidence.
+- Adding a convenience adapter to keep old and new outputs alive.
+- Letting beta or missing-contract capture outcomes look certified.
+- Building UI activation before proof and Product Surface gates exist.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: Coverage v1 vocabulary as customer truth; v1-v2 adapters; fallback readers; dual writes; fallback-to-latest evidence; `tenant_id` as platform-core ownership truth; raw provider/evidence payload default display; historical audits as current truth.
+
+## Review / Expiry
+
+Expires after Coverage v2 / TCM activation and legacy coverage vocabulary cutover are complete. At expiry, replace this temporary migration gate with current activation truth and remove stale cutover warnings from future prompts.

.agent/skills/workflows/browser-readonly-audit/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: tenantpilot-browser-readonly-audit
+description: Read-only browser audit workflow for TenantPilot product surfaces without mutating state.
+---
+
+## Purpose
+
+Use this skill to collect focused browser evidence for UI/product-surface audits while avoiding state mutation, destructive flows, fixture pollution, or overbroad readiness claims.
+
+## Activate When
+
+- Running a browser smoke check, visual inspection, product-surface audit, full browser audit, or read-only surface review.
+- Inspecting pages for console errors, Livewire/runtime failures, network failures, visible complexity, navigation, authorization presentation, or Product Surface conformance.
+- The user asks for browser proof and the intended path can be read-only.
+
+## Do Not Activate When
+
+- The task requires executing destructive/high-impact mutations.
+- The user asks to implement fixes rather than audit.
+- The relevant feature is backend/docs-only and browser proof is explicitly `N/A - no rendered UI surface changed`.
+
+## Maturity
+
+L2/L3 checklist workflow.
+
+## Gate Type
+
+workflow.
+
+## Source Evidence
+
+- `docs/product/standards/product-surface-contract.md`
+- `docs/testing-guidelines.md`
+- `.specify/README.md`
+- `specs/400-product-contract-spec-completeness-audit/spec.md`
+- `specs/407-full-browser-ux-runtime-audit/spec.md`
+- `apps/platform/tests/Browser/Spec402ResourcePolicyAuthorizationSmokeTest.php`
+- `apps/platform/tests/Browser/Spec412PilotReadinessRemediationSmokeTest.php`
+- `apps/platform/tests/Feature/Console/TenantpilotSeedBackupHealthBrowserFixtureCommandTest.php`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Audit target route/page/flow.
+- Authentication fixture or browser harness.
+- Whether fixtures are read-only or seeded for inspection.
+- Expected workspace/environment context.
+- Primary interaction to inspect, if any.
+- Console, network, and Livewire/runtime error capture method.
+
+## Execution Checklist
+
+- Define the exact read-only path and actor.
+- Confirm no state-changing action will be executed.
+- Open the relevant route or entry point.
+- Confirm workspace/environment context and expected surface labels.
+- Inspect the changed or audited UI element.
+- Check console/runtime errors.
+- Check failed network requests related to the tested path.
+- Record route, actor, context, observations, limitations, and screenshots only when useful.
+- Do not generalize a narrow read-only pass into full merge readiness.
+
+## Stop Conditions
+
+- The path requires destructive or high-impact execution to prove the claim.
+- A requested action would mutate state without a test fixture and explicit spec permission.
+- Browser audit discovers an in-scope blocker that requires implementation before readiness can be claimed.
+- The evidence is too narrow for the requested broad readiness claim.
+- The user asks for fixes during audit and the active spec/workflow does not include implementation.
+
+## Required Evidence After Use
+
+- Route/path tested.
+- Actor and workspace/environment context.
+- UI elements inspected.
+- Console/runtime/network result.
+- Mutations avoided.
+- Scope limitation and whether the evidence is smoke, audit sample, or full browser proof.
+
+## Common Failure Modes
+
+- Clicking a destructive action while trying to inspect its confirmation.
+- Treating seeded demo data as production readiness.
+- Reporting "browser passed" without route, actor, or context.
+- Ignoring console errors as development noise without evidence.
+- Expanding a read-only audit into implementation work.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: historical audits as current truth; raw provider/evidence payload default display; Product Surface runtime framework; OperationRun as default customer proof.
+
+## Review / Expiry
+
+Review when browser harnesses, fixture commands, Product Surface proof expectations, or browser lane governance change. No planned expiry.

.agent/skills/workflows/filament-livewire-v5-change-loop/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: tenantpilot-filament-livewire-v5-change-loop
+description: Checklist gate for Laravel 12, Filament v5, Livewire v4, and TenantPilot Filament safety changes.
+---
+
+## Purpose
+
+Use this skill to keep Filament and Livewire changes aligned with TenantPilot's Laravel 12, Filament v5, Livewire v4, RBAC, Product Surface, and testing contracts.
+
+## Activate When
+
+- Touching Filament resources, pages, widgets, relation managers, actions, tables, forms, infolists, navigation, panels, providers, render hooks, assets, global search, or Livewire components.
+- Adding or changing destructive/high-impact Filament actions.
+- Writing or reviewing Filament/Livewire tests.
+
+## Do Not Activate When
+
+- No Filament, Livewire, panel, route, navigation, action, table, form, UI, or asset behavior changes.
+- The active spec explicitly forbids runtime UI changes and only creates docs/tooling artifacts.
+
+## Maturity
+
+L3 checklist.
+
+## Gate Type
+
+checklist.
+
+## Source Evidence
+
+- `AGENTS.md`
+- `docs/filament-guidelines.md`
+- `docs/research/filament-v5-notes.md`
+- `docs/ui/tenantpilot-enterprise-ui-standards.md`
+- `docs/product/standards/product-surface-contract.md`
+- `docs/testing-guidelines.md`
+- `apps/platform/bootstrap/providers.php`
+- `apps/platform/app/Providers/Filament/AdminPanelProvider.php`
+- `apps/platform/app/Providers/Filament/SystemPanelProvider.php`
+- `apps/platform/app/Support/Rbac/UiEnforcement.php`
+- `apps/platform/app/Support/Rbac/WorkspaceUiEnforcement.php`
+
+## External Anchors
+
+- Filament v5 official docs cited in `docs/research/filament-v5-notes.md`.
+
+## Required Repo Context
+
+- Installed versions: Laravel 12, Filament v5, Livewire v4.
+- Panel provider registration.
+- Resource/page/global search posture.
+- Action surface and Product Surface classifications.
+- Existing tests for the affected page/resource/widget/action.
+- Asset registration and deploy implications.
+
+## Execution Checklist
+
+- Confirm Livewire v4.0+ compliance and no Livewire v3 APIs.
+- Register panel providers only in `apps/platform/bootstrap/providers.php` for Laravel 11+/12.
+- Do not change panel `path()` without route conflict review.
+- For global search, ensure safe View/Edit page and `$recordTitleAttribute`, or disable it.
+- Eager-load relationship-backed global search details.
+- Use native Filament components and shared primitives before custom Blade/Tailwind.
+- Use `UiEnforcement` or `WorkspaceUiEnforcement` for capability-aware actions.
+- Use `->action(...)` and `->requiresConfirmation()` for destructive/high-impact actions.
+- Keep business behavior in services/jobs/policies, not long Filament closures.
+- Test pages/relation managers/widgets as Livewire components and actions through Filament action helpers.
+- Record asset strategy and whether `filament:assets` is required.
+
+## Stop Conditions
+
+- Livewire v3 or Filament v3/v4 APIs are introduced.
+- Panel provider registration is moved to `bootstrap/app.php`.
+- Destructive/high-impact action lacks confirmation, server-side authorization, or audit/test coverage.
+- Global search is enabled without safe scoped View/Edit posture.
+- UI visibility is treated as authorization.
+- Graph/provider calls happen during render.
+- Custom markup replaces native Filament/shared primitives without an approved Product Surface/UI-FIL exception.
+
+## Required Evidence After Use
+
+- Livewire v4 compliance statement.
+- Provider registration location statement.
+- Global search posture for changed resources.
+- Destructive/high-impact action safety summary.
+- Asset strategy and deployment note.
+- Tests added/updated and run, or no-runtime/UI rationale.
+- Browser proof when rendered UI/user flow changes.
+
+## Common Failure Modes
+
+- Mounting non-Livewire resource classes in Livewire tests.
+- Assuming URL actions have confirmation modal behavior.
+- Adding page-local badges/status colors instead of `BadgeCatalog`/shared primitives.
+- Publishing Filament internals for small layout tweaks.
+- Registering heavy assets globally when on-demand loading fits.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies. Especially quarantined here: Product Surface runtime framework; raw provider/evidence payload default display; stale provider Healthy/Ready semantics; historical audits as current truth.
+
+## Review / Expiry
+
+Review when Filament, Livewire, Laravel panel structure, or TenantPilot Filament standards change. No planned expiry.

.agent/skills/workflows/spec-readiness-gate/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: tenantpilot-spec-readiness-gate
+description: Validate an active TenantPilot Spec Kit package before implementation or merge-readiness claims.
+---
+
+## Purpose
+
+Use this skill to check whether an active TenantPilot/TenantAtlas spec package is ready for implementation or review without inventing scope.
+
+## Activate When
+
+- Implementing an active or explicitly named spec.
+- Reviewing `spec.md`, `plan.md`, and `tasks.md` for implementation readiness.
+- A spec introduces new runtime behavior, tests, UI, persistence, abstractions, statuses, or workflow/tooling artifacts.
+
+## Do Not Activate When
+
+- The user asks for a simple code explanation with no implementation or readiness claim.
+- The active work is a tiny non-spec maintenance task and the repo rules do not require Spec Kit artifacts.
+- A completed historical spec is being read only as context.
+
+## Maturity
+
+L3 checklist.
+
+## Gate Type
+
+checklist.
+
+## Source Evidence
+
+- `AGENTS.md`
+- `.specify/README.md`
+- `.specify/memory/constitution.md`
+- `.specify/memory/spec-approval-rubric.md`
+- `.specify/templates/spec-template.md`
+- `.specify/templates/plan-template.md`
+- `.specify/templates/tasks-template.md`
+- `docs/ai-coding-rules.md`
+- `specs/416-tenantpilot-agent-skill-layer-v1/spec.md`
+- `specs/416-tenantpilot-agent-skill-layer-v1/plan.md`
+- `specs/416-tenantpilot-agent-skill-layer-v1/tasks.md`
+
+## External Anchors
+
+Not applicable.
+
+## Required Repo Context
+
+- Current branch and `git status --short`.
+- Active spec directory.
+- Active `spec.md`, `plan.md`, `tasks.md`, and checklist if present.
+- Constitution and relevant `.specify/templates/`.
+- Nearby related specs as read-only context.
+- Code and tests named by the active plan.
+
+## Execution Checklist
+
+- Confirm exactly one active spec directory is in scope.
+- Confirm required spec artifacts exist.
+- Confirm the spec has problem, user value, functional requirements, non-goals, acceptance criteria, assumptions, risks, and open questions.
+- Confirm the plan names affected repo surfaces and does not contradict architecture.
+- Confirm tasks are ordered, bounded, verifiable, and include validation.
+- Confirm Product Surface, RBAC, workspace/managed-environment scope, OperationRun, evidence, provider boundary, test governance, and proportionality sections are complete where relevant.
+- Confirm completed specs are read-only context.
+- Confirm dirty worktree entries are either active-spec artifacts or explicitly user-intended for this operation.
+
+## Stop Conditions
+
+- Active spec cannot be determined safely.
+- `spec.md`, `plan.md`, or `tasks.md` is missing.
+- Open questions block safe implementation.
+- New persisted truth, abstraction, enum/status family, taxonomy, or framework lacks proportionality review.
+- Runtime/UI changes are required but the spec says no runtime/UI impact.
+- The implementation would rewrite completed specs or historical close-out evidence.
+- Dirty unrelated work would be overwritten or mixed into the change.
+
+## Required Evidence After Use
+
+- Active spec path.
+- Gate result: pass, pass with conditions, or fail.
+- Blocking gaps or explicit statement that no blocking gaps remain.
+- Exact files used as source evidence.
+- Any residual risks with reason: out of scope, separate spec, existing unrelated debt, not reproducible, risky refactor, or blocked decision.
+
+## Common Failure Modes
+
+- Treating `.specify/spec.md` legacy content as the active feature spec.
+- Filling missing scope from assumptions instead of stopping.
+- Normalizing completed specs to satisfy newer templates.
+- Letting a docs-only spec drift into runtime changes.
+- Marking tasks complete before evidence exists.
+
+## Quarantined Rules
+
+Full Spec 416 quarantine list applies: `tenant_id` as platform-core ownership truth; Coverage v1 vocabulary as customer truth; v1-v2 adapters; fallback readers; dual writes; fallback-to-latest evidence; OperationRun as default customer proof; stale provider Healthy/Ready semantics; limited customer download vocabulary; raw provider/evidence payload default display; Product Surface runtime framework; historical audits as current truth.
+
+## Review / Expiry
+
+Review this skill whenever Spec Kit templates, the constitution, or the active Spec Kit workflow changes. No planned expiry.

Agents.md

@@ -401,6 +401,16 @@ ## AI Usage Note
 
 before proposing or implementing changes.
 
+## TenantPilot Agent Skill Router
+
+Before starting any repository task, inspect `.agent/skills/README.md`; this is the TenantPilot skill library, while `AGENTS.md` remains the activation/router entry point.
+Activate only skills relevant to the requested task. Do not load all skills by default.
+Before implementation or review, report activated skills, why each was activated, current branch, HEAD, dirty state, and any hard-gate stop conditions.
+Hard-gate skills are blocking. If a hard-gate stop condition is met, stop before implementation and report the blocker.
+Prefer current repo evidence, active specs, tests, and validated contracts over historical prompts or inventory-only specs.
+Inventory-only specs are hints, not hard evidence.
+Temporary migration skills must include expiry or review criteria.
+
 For the current enterprise best-practice baseline and the proposed compact addendum
 for this file, see `docs/stack-overview.md` and `docs/AGENTS-draft.md`.
 

specs/416-tenantpilot-agent-skill-layer-v1/checklists/requirements.md

@@ -0,0 +1,97 @@
+# Requirements Checklist: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration
+
+## Correction Completeness
+
+- [x] CHK001 `spec.md` is renamed conceptually to include Agent Skill Layer V1 and Router Integration.
+- [x] CHK002 `plan.md` identifies `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, and Spec 416 files as the only future implementation surfaces.
+- [x] CHK003 `tasks.md` is reset for future implementation and uses unchecked implementation tasks.
+- [x] CHK004 The spec correction itself is documentation/spec-only.
+- [x] CHK005 Runtime application files remain out of scope.
+
+## Candidate Selection Gate
+
+- [x] CHK010 The correction explicitly supersedes the earlier `.codex/skills/**`-only target.
+- [x] CHK011 `.agent/skills/**` is now the skill library.
+- [x] CHK012 `AGENTS.md` is now the activation/router entry point.
+- [x] CHK013 Basic router integration is not deferred to a future Spec 417.
+- [x] CHK014 Related Specs 395, 400, 402, 414, and 415 remain read-only context and not preparation targets.
+- [x] CHK015 The candidate is scoped as repository workflow/documentation only.
+- [x] CHK016 Candidate Selection Gate result: PASS.
+
+## Repo Truth And Scope
+
+- [x] CHK020 The corrected future implementation scope is limited to `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, and `specs/416-tenantpilot-agent-skill-layer-v1/**`.
+- [x] CHK021 `.codex/skills/**` is not the corrected Spec 416 implementation target.
+- [x] CHK022 Runtime application files are forbidden.
+- [x] CHK023 Tests, migrations, config, routes, resources, services, policies, jobs, package files, and lock files are forbidden.
+- [x] CHK024 Completed specs must not be rewritten.
+
+## Mandatory Spec Sections
+
+- [x] CHK030 Spec Candidate Check is complete with approval class, score, red flags, and decision.
+- [x] CHK031 Spec Scope Fields are complete.
+- [x] CHK032 Deliverables are complete.
+- [x] CHK033 Required Skill Structure is complete.
+- [x] CHK034 AGENTS.md Router Integration Requirements are complete.
+- [x] CHK035 UI Surface Impact is checked as `No UI surface impact` with rationale.
+- [x] CHK036 Product Surface Impact is `N/A - no rendered product surface changed`.
+- [x] CHK037 Browser Verification Plan is `N/A - no rendered UI surface changed`.
+- [x] CHK038 Human Product Sanity is N/A for rendered product UI.
+- [x] CHK039 Cross-Cutting / Shared Pattern Reuse is completed for repository workflow.
+- [x] CHK040 OperationRun UX Impact is N/A.
+- [x] CHK041 Provider Boundary / Platform Core Check is N/A for runtime seams.
+- [x] CHK042 Proportionality Review is complete because a workflow/skill abstraction and router are introduced.
+- [x] CHK043 Testing / Lane / Runtime Impact is complete with artifact/router-only validation.
+- [x] CHK044 Test Governance outcome is `keep` with no runtime/test/browser/heavy-governance lane expansion.
+
+## Requirements Coverage
+
+- [x] CHK050 README requirements are listed.
+- [x] CHK051 Required skill headings are listed.
+- [x] CHK052 All 11 V1 skill files are listed as functional requirements and tasks.
+- [x] CHK053 Router requirements are listed.
+- [x] CHK054 The quarantine list is explicit.
+- [x] CHK055 TCM temporary expiry requirement is explicit.
+- [x] CHK056 No generic standards-only skills requirement is explicit.
+- [x] CHK057 No runtime/application/test/migration/config/package changes requirement is explicit.
+- [x] CHK058 Implementation report requirements are explicit.
+- [x] CHK059 Allowed and forbidden final implementation paths are explicit.
+- [x] CHK060 Verification commands include AGENTS.md router checks.
+
+## Task Readiness
+
+- [x] CHK070 Tasks are grouped by phase.
+- [x] CHK071 Tasks are unchecked and suitable for the corrected implementation loop.
+- [x] CHK072 Tasks include preflight repo verification before writing skill files.
+- [x] CHK073 Tasks include `.agent/skills/README.md` creation.
+- [x] CHK074 Tasks include every repo-contract skill.
+- [x] CHK075 Tasks include every workflow skill.
+- [x] CHK076 Tasks include the temporary migration skill.
+- [x] CHK077 Tasks include AGENTS.md router integration.
+- [x] CHK078 Tasks include verification commands.
+- [x] CHK079 Tasks include implementation-report close-out.
+- [x] CHK080 Tasks include explicit non-goals.
+
+## Router Integration Readiness
+
+- [x] CHK090 AGENTS.md must contain a TenantPilot Agent Skill Router section.
+- [x] CHK091 Router must tell agents to read `.agent/skills/README.md`.
+- [x] CHK092 Router must tell agents to activate only relevant skills.
+- [x] CHK093 Router must tell agents not to load all skills by default.
+- [x] CHK094 Router must tell agents to report activated skills and reasons before implementation or review.
+- [x] CHK095 Router must treat hard-gate stop conditions as blockers.
+- [x] CHK096 Router must require branch, HEAD, and dirty state before file changes.
+- [x] CHK097 Router must say current repo evidence beats historical prompts.
+- [x] CHK098 Router must say inventory-only specs are hints, not hard evidence.
+- [x] CHK099 Router must say temporary skills require expiry/review criteria.
+
+## Spec Readiness Gate
+
+- [x] CHK100 `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` exist.
+- [x] CHK101 Problem statement, user value, functional requirements, non-goals, acceptance/success criteria, assumptions, risks, and open questions are present.
+- [x] CHK102 The plan identifies affected repo surfaces and avoids application runtime changes.
+- [x] CHK103 Tasks are small, ordered, and verifiable.
+- [x] CHK104 RBAC, workspace isolation, OperationRun, evidence/result truth, customer-output, provider freshness, Product Surface, Filament/Livewire, browser audit, temporary migration, and router concerns are addressed as skill/router content where relevant.
+- [x] CHK105 No open question blocks safe implementation.
+- [x] CHK106 Scope is small enough for a bounded implementation loop.
+- [x] CHK107 Spec Readiness Gate result: PASS.

specs/416-tenantpilot-agent-skill-layer-v1/implementation-report.md

@@ -0,0 +1,126 @@
+# Implementation Report: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration
+
+## A. Branch / HEAD / Dirty State
+
+- Branch: `416-tenantpilot-agent-skill-layer-v1`
+- HEAD: `ca0f5461 feat: add generic content-backed coverage capture (#482)`
+- Preflight dirty state: untracked corrected spec package and untracked `.codex/skills/tenantpilot-*` artifacts were already present before implementation.
+- Final dirty state: `Agents.md` modified; `.agent/skills/**` created; active Spec 416 package remains untracked. The excluded `.codex/skills/README.md` and `.codex/skills/tenantpilot-*` artifacts are no longer present in the working tree.
+
+## B. Files Created
+
+- `.agent/skills/README.md`
+- `.agent/skills/repo-contracts/workspace-scope-safety/SKILL.md`
+- `.agent/skills/repo-contracts/rbac-action-safety/SKILL.md`
+- `.agent/skills/repo-contracts/operation-run-truth/SKILL.md`
+- `.agent/skills/repo-contracts/customer-output-gate/SKILL.md`
+- `.agent/skills/repo-contracts/evidence-anchor-contract/SKILL.md`
+- `.agent/skills/repo-contracts/provider-freshness-semantics/SKILL.md`
+- `.agent/skills/repo-contracts/product-surface-gate/SKILL.md`
+- `.agent/skills/workflows/spec-readiness-gate/SKILL.md`
+- `.agent/skills/workflows/filament-livewire-v5-change-loop/SKILL.md`
+- `.agent/skills/workflows/browser-readonly-audit/SKILL.md`
+- `.agent/skills/temporary-migrations/tcm-cutover-guard/SKILL.md`
+
+## C. Files Modified
+
+- `Agents.md`
+- `specs/416-tenantpilot-agent-skill-layer-v1/tasks.md`
+- `specs/416-tenantpilot-agent-skill-layer-v1/implementation-report.md`
+
+## D. Skills Created
+
+- `workflows/spec-readiness-gate`
+- `repo-contracts/workspace-scope-safety`
+- `repo-contracts/rbac-action-safety`
+- `repo-contracts/operation-run-truth`
+- `repo-contracts/customer-output-gate`
+- `repo-contracts/evidence-anchor-contract`
+- `repo-contracts/provider-freshness-semantics`
+- `repo-contracts/product-surface-gate`
+- `workflows/filament-livewire-v5-change-loop`
+- `workflows/browser-readonly-audit`
+- `temporary-migrations/tcm-cutover-guard`
+
+## E. AGENTS.md Router Added: yes/no
+
+Yes. The tracked repository path is `Agents.md`; the section title is `TenantPilot Agent Skill Router`.
+
+## F. Maturity / Gate Type Summary
+
+- L4 hard gates: workspace scope safety, RBAC/action safety, OperationRun truth, customer output gate, evidence anchor contract, provider freshness semantics.
+- L3 checklist gates: spec readiness gate, product surface gate, Filament/Livewire v5 change loop.
+- L2/L3 workflow: browser read-only audit.
+- L3 temporary migration gate: TCM cutover guard.
+
+## G. Quarantine Rules Included
+
+Included in `.agent/skills/README.md` and relevant `SKILL.md` files:
+
+- `tenant_id` as platform-core ownership truth
+- Coverage v1 vocabulary as customer truth
+- v1-v2 adapters
+- fallback readers
+- dual writes
+- fallback-to-latest evidence
+- OperationRun as default customer proof
+- stale provider Healthy/Ready semantics
+- limited customer download vocabulary
+- raw provider/evidence payload default display
+- Product Surface runtime framework
+- historical audits as current truth
+
+## H. Verification Commands Run
+
+- `find .agent/skills -name 'SKILL.md' -print | sort` - passed; 11 required skill files listed.
+- `grep -n "TenantPilot Agent Skill Router" AGENTS.md` - passed at line 404.
+- `grep -n ".agent/skills/README.md" AGENTS.md` - passed at line 406.
+- `grep -n "Do not load all skills by default" AGENTS.md` - passed at line 407.
+- `grep -n "Hard-gate skills are blocking" AGENTS.md` - passed at line 409.
+- `grep -n "Inventory-only specs are hints" AGENTS.md` - passed at line 411.
+- Required `SKILL.md` heading validation - passed for all generated skills.
+- Generic standards-only path check for `soc2`, `gdpr`, `ssdf`, and `enterprise-best-practice` - passed; none found.
+- TCM expiry/review language check - passed.
+- Forbidden runtime/test/config/package path check - passed.
+- Excluded `.codex/skills/**` target check - passed; no corrected Spec 416 `.codex/skills/README.md` or `.codex/skills/tenantpilot-*` artifacts remain in `git status` or `git diff`.
+- `git diff --check -- Agents.md specs/416-tenantpilot-agent-skill-layer-v1` - passed for tracked modifications.
+- `.agent/skills/**` trailing-whitespace check - passed for untracked new files.
+- `specs/416-tenantpilot-agent-skill-layer-v1/**` trailing-whitespace check - passed for untracked active spec files.
+- `git status --short --untracked-files=all` - recorded; includes only allowed implementation paths: `Agents.md`, `.agent/skills/**`, and `specs/416-tenantpilot-agent-skill-layer-v1/**`.
+
+## I. Runtime Files Changed: yes/no
+
+No.
+
+- Runtime UI files changed: no.
+- UI impact / no-impact decision: `N/A - no rendered UI surface changed`.
+- Product Surface exceptions: none.
+- Browser proof: `N/A - no rendered UI surface changed`.
+- Human Product Sanity result: N/A for rendered product UI; workflow sanity is limited to router clarity, no load-all behavior, and no false authority over current repo truth.
+- Visible complexity outcome: neutral for rendered product UI; agent workflow selection is explicit and bounded.
+- No-legacy confirmation: corrected skill library is `.agent/skills/**`; `.codex/skills/**` is not a Spec 416 target.
+- Completed-spec rewrite assertion: no completed historical specs were rewritten, normalized, reopened, or stripped of validation/task/browser/review history.
+- Livewire v4 compliance: no Livewire code changed; app baseline remains Livewire v4.
+- Provider registration location: no panel provider change; Laravel panel providers remain in `apps/platform/bootstrap/providers.php`.
+- Global search posture: no Filament resources changed.
+- Destructive/high-impact action posture: no application actions changed.
+- Asset strategy: no assets registered; `filament:assets` is not required by this spec.
+- Deployment impact: none for env vars, migrations, queues, scheduler, storage, runtime assets, or Dokploy deployment.
+
+## J. Tests Changed: yes/no
+
+No.
+
+## K. Migrations Changed: yes/no
+
+No.
+
+## L. Config Changed: yes/no
+
+No.
+
+## M. PASS / PASS WITH CONDITIONS / FAIL
+
+PASS
+
+No unresolved merge-readiness conditions remain for the corrected Spec 416 scope. The final working tree contains only allowed implementation paths: `.agent/skills/**`, `Agents.md`, and `specs/416-tenantpilot-agent-skill-layer-v1/**`.

specs/416-tenantpilot-agent-skill-layer-v1/plan.md

@@ -0,0 +1,236 @@
+# Implementation Plan: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration
+
+**Branch**: `416-tenantpilot-agent-skill-layer-v1` | **Date**: 2026-06-25 | **Spec**: `specs/416-tenantpilot-agent-skill-layer-v1/spec.md`
+
+## Summary
+
+Create a minimal TenantPilot-specific agent skill library under `.agent/skills/**` and integrate a concise TenantPilot Agent Skill Router into `AGENTS.md`. The router makes the skill layer usable by future agents by requiring them to inspect `.agent/skills/README.md`, activate only relevant skills, report activated skills and reasons, and stop when hard-gate conditions trigger.
+
+This remains repository workflow/documentation work only. It must not alter TenantPilot Laravel runtime behavior, product UI behavior, tests, migrations, routes, config, package files, assets, lock files, or application code.
+
+## Technical Context
+
+**Language/Version**: Markdown repository artifacts; application baseline remains PHP 8.4.15, Laravel 12, Filament 5, Livewire 4.
+**Primary Dependencies**: Repository agent instructions in `AGENTS.md`; skill file convention (`SKILL.md`) under `.agent/skills/**`.
+**Storage**: Git-tracked markdown files only; no database/storage changes.
+**Testing**: Read-only shell verification; no Pest/runtime/browser tests unless implementation unexpectedly changes runtime files, which is out of scope.
+**Validation Lanes**: artifact checks, router grep checks, heading checks, final diff scope checks, `git diff --check`, `git status --short`.
+**Target Platform**: repository workflow for AI coding agents.
+**Project Type**: Laravel monorepo with Spec Kit and project-level agent instructions.
+**Performance Goals**: Skill files stay focused enough for progressive disclosure.
+**Constraints**: no runtime files, no generic standards-only skill zoo, no completed-spec rewrite, no load-all-by-default router, no huge duplicated `AGENTS.md`.
+**Scale/Scope**: one README, 11 V1 skills, one concise router section, optional workflow doc only if needed.
+
+## Existing Repo Truth
+
+- `AGENTS.md` is the repository entry point for agent instructions.
+- `.agent/skills/**` does not currently provide the corrected Spec 416 skill library and must be created by implementation.
+- Existing `.codex/skills/**` content is not the corrected implementation target for Spec 416.
+- Related specs 395, 400, 402, 414, and 415 are context/dependency artifacts and must not be rewritten.
+- Inventory-only specs are hints, not hard current evidence, unless validated by current repo source/tests/contracts.
+
+## Affected Surfaces
+
+- `.agent/skills/**`: new skill library and README.
+- `AGENTS.md`: concise router section.
+- `docs/agent-workflow.md`: optional only if the router section would exceed 12 lines or would need to duplicate skill details inside `AGENTS.md`.
+- `specs/416-tenantpilot-agent-skill-layer-v1/**`: active spec package and future close-out report.
+
+## UI / Surface Guardrail Plan
+
+- **Guardrail scope**: no operator-facing product surface change.
+- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A.
+- **No-impact class**: repository workflow/documentation only.
+- **Required tests or manual smoke**: `N/A - no rendered UI surface changed`.
+- **Exception path and spread control**: none.
+- **Active feature PR close-out entry**: Guardrail / `N/A - no rendered UI surface changed`.
+- **UI/Productization coverage decision**: No UI surface impact.
+- **Coverage artifacts to update**: none.
+- **Screenshot or page-report need**: no.
+
+## Product Surface Contract Plan
+
+- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
+- **No-legacy posture**: canonical corrected skill library under `.agent/skills/**`; no `.codex/skills/**` target for this spec.
+- **Page archetype and surface budget plan**: N/A.
+- **Technical Annex and deep-link demotion plan**: N/A.
+- **Canonical status vocabulary plan**: N/A.
+- **Product Surface exceptions**: none.
+- **Browser verification plan**: `N/A - no rendered UI surface changed`.
+- **Human Product Sanity plan**: N/A for rendered product UI; workflow sanity focuses on router clarity and no scope drift.
+- **Visible complexity outcome target**: rendered product UI neutral; agent workflow selection becomes explicit and bounded.
+
+## Filament / Livewire / Deployment Posture
+
+- **Livewire v4 compliance**: no Livewire code changed; app baseline remains Livewire v4.
+- **Panel provider registration location**: no panel provider change; Laravel panel providers remain in `apps/platform/bootstrap/providers.php`.
+- **Global search posture**: no Filament resources changed.
+- **Destructive/high-impact action posture**: no application actions changed.
+- **Asset strategy**: no assets; `filament:assets` not required by this spec.
+- **Testing plan**: no pages/widgets/relation managers/actions; artifact verification only.
+- **Deployment impact**: none for env vars, migrations, queues, scheduler, storage, runtime assets, or Dokploy deployment.
+
+## Shared Pattern & System Fit
+
+- **Cross-cutting feature marker**: yes, repository workflow/documentation only.
+- **Systems touched**: `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, active spec package.
+- **Shared abstractions reused**: existing `AGENTS.md` instruction entry point and skill `SKILL.md` convention.
+- **New abstraction introduced? why?**: A bounded agent skill layer plus a router rule is introduced to consolidate repeated repo-contract rules and make them discoverable before work.
+- **Bounded deviation / spread control**: no generic standards library, no 50+ skill zoo, no automatic all-skill loading, no runtime framework.
+
+## AGENTS.md Router Plan
+
+Add a concise section titled `TenantPilot Agent Skill Router` to `AGENTS.md` that requires agents to:
+
+- inspect `.agent/skills/README.md` before repository work
+- activate only relevant skills based on task triggers
+- not load all skills by default
+- report activated skills and reasons before implementation or review
+- report branch, HEAD, dirty state, and hard-gate stop conditions
+- treat hard-gate stop conditions as blocking
+- prefer current repo evidence, active specs, tests, and validated contracts over historical prompts or inventory-only specs
+- treat inventory-only specs as hints, not hard evidence
+- require temporary migration skills to include expiry or review criteria
+
+If this cannot remain within 12 lines in `AGENTS.md` without duplicating skill details, create `docs/agent-workflow.md` for supporting detail and keep `AGENTS.md` as the router.
+
+## OperationRun UX Impact
+
+- **Touches OperationRun start/completion/link UX?**: no.
+- **Central contract reused**: N/A.
+- **Delegated UX behaviors**: N/A.
+- **Queued DB-notification policy**: N/A.
+- **Terminal notification path**: N/A.
+- **Exception path**: none.
+
+## Provider Boundary & Portability Fit
+
+- **Shared provider/platform boundary touched?**: no runtime seam touched.
+- **Provider-owned seams**: N/A.
+- **Platform-core seams**: N/A.
+- **Neutral platform terms / contracts preserved**: workspace, managed environment, provider connection, provider metadata, operation, customer-safe output, evidence anchor.
+- **Retained provider-specific semantics and why**: Microsoft/Graph can appear only as current repo evidence or examples inside skills.
+- **Bounded extraction or follow-up path**: none for basic router integration.
+
+## Constitution Check
+
+- Inventory-first / snapshots-second: N/A - no product inventory or snapshot behavior.
+- Read/write separation: N/A - no application read/write flow.
+- Graph contract path: N/A - no Graph code.
+- Deterministic capabilities: N/A - no capability derivation changes.
+- RBAC/workspace/tenant isolation: encoded as future skill guidance; no runtime authorization changes.
+- OperationRun observability: encoded as future skill guidance; no OperationRun behavior changes.
+- Product Surface Contract: satisfied through no rendered product surface impact.
+- Test governance: runtime/app lanes are N/A; artifact verification commands are specified.
+- Proportionality: completed in `spec.md` because a new workflow/skill abstraction and router are introduced.
+- No premature abstraction: allowed as a small docs/workflow consolidation based on repeated validated repo contracts.
+- Provider boundary: no runtime boundary touched.
+- Completed-spec guardrail: related completed specs remain read-only context.
+
+## Test Governance Check
+
+- **Test purpose / classification by changed surface**: N/A for Laravel runtime; artifact checks only.
+- **Affected validation lanes**: N/A for app lanes.
+- **Why this lane mix is the narrowest sufficient proof**: Markdown skill files and `AGENTS.md` router text can be verified through file, heading, grep, and diff-scope checks without booting Laravel.
+- **Narrowest proving command(s)**:
+  - `find .agent/skills -name 'SKILL.md' -print | sort`
+  - heading validation for every `.agent/skills/**/SKILL.md`
+  - `grep -n "TenantPilot Agent Skill Router" AGENTS.md`
+  - `grep -n ".agent/skills/README.md" AGENTS.md`
+  - `grep -n "Do not load all skills by default" AGENTS.md`
+  - `grep -n "Hard-gate skills are blocking" AGENTS.md`
+  - `grep -n "Inventory-only specs are hints" AGENTS.md`
+  - no generic standards-only skill paths
+  - final diff contains only allowed paths
+  - forbidden runtime/test/config/package paths are absent from the diff
+  - `git diff --check`
+  - `git status --short`
+- **Fixture / helper / factory / seed / context cost risks**: none.
+- **Expensive defaults or shared helper growth introduced?**: no.
+- **Heavy-family additions, promotions, or visibility changes**: none.
+- **Budget / baseline / trend follow-up**: none.
+- **Test governance outcome**: `keep` - artifact/router checks remain the correct validation lane because this spec adds no runtime behavior, test lane, fixture/helper, browser, or heavy-governance cost.
+- **Review-stop questions**: Did implementation create the `.agent` library? Did it add the AGENTS router? Did it create generic standards-only skills? Did it change runtime files? Did it force all skills to load? Did it treat inventory-only specs as hard evidence?
+- **Why no dedicated follow-up spec is needed**: Spec 416 now includes basic router integration.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/416-tenantpilot-agent-skill-layer-v1/
+|-- spec.md
+|-- plan.md
+|-- tasks.md
+|-- implementation-report.md
+`-- checklists/
+    `-- requirements.md
+```
+
+### Repository artifacts to be created during implementation
+
+```text
+.agent/
+  skills/
+    README.md
+    repo-contracts/
+      workspace-scope-safety/SKILL.md
+      rbac-action-safety/SKILL.md
+      operation-run-truth/SKILL.md
+      customer-output-gate/SKILL.md
+      evidence-anchor-contract/SKILL.md
+      provider-freshness-semantics/SKILL.md
+      product-surface-gate/SKILL.md
+    workflows/
+      spec-readiness-gate/SKILL.md
+      filament-livewire-v5-change-loop/SKILL.md
+      browser-readonly-audit/SKILL.md
+    temporary-migrations/
+      tcm-cutover-guard/SKILL.md
+```
+
+**Structure Decision**: Use `.agent/skills/**` because the corrected feature requires a general skill library routed from `AGENTS.md`. Do not target `.codex/skills/**` for the corrected Spec 416 implementation.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|---|---|---|
+| New docs/workflow skill layer | Repeated validated repo contracts are spread across many files and prompts | Prompt-only repetition is fragile and not discoverable during long agent sessions |
+| Router section in `AGENTS.md` | Future agents must know to inspect the skill library before work | A standalone skill library can be missed without an entry point |
+| Maturity/gate taxonomy in skill files | Agents need to know when a skill is a hard gate versus checklist guidance | Free-form prose makes stop conditions and authority unclear |
+
+## Phase 0: Repo Verification
+
+Confirm current branch, HEAD, clean/dirty state, existing skill roots, no committed `.agent/skills/**` package for this spec, and completed-spec guardrail for related specs.
+
+## Phase 1: Skill Index
+
+Create `.agent/skills/README.md` with purpose, progressive disclosure, activation table, maturity model, gate definitions, V1 skill list, quarantine rules, currentness warning, inventory-only hint warning, and temporary-skill warning.
+
+## Phase 2: Skill Files
+
+Create the required L4 hard-gate, L3 checklist, L2/L3 workflow, and L3 temporary migration skills under the required `.agent/skills/**` structure.
+
+## Phase 3: Router Integration
+
+Update `AGENTS.md` with the TenantPilot Agent Skill Router section. Create `docs/agent-workflow.md` only if the router would exceed 12 lines or duplicate skill details inside `AGENTS.md`.
+
+## Phase 4: Verification And Report
+
+Run read-only artifact checks, router grep checks, final diff-scope checks, confirm no runtime files changed, and write the implementation report under the active spec package.
+
+## Out Of Scope
+
+- Laravel runtime code.
+- Filament/Livewire resources, pages, widgets, actions, views, assets, or providers.
+- Migrations, models, services, jobs, policies, commands, routes, seeders, factories, tests, config, package files, or lock files.
+- Generic enterprise standards skill library.
+- 50+ skill zoo.
+- Requiring agents to load every skill by default.
+- Completed-spec rewrites.
+
+## Suggested Commit Message
+
+```text
+docs: add TenantPilot agent skill layer and router
+```

specs/416-tenantpilot-agent-skill-layer-v1/spec.md

@@ -0,0 +1,438 @@
+# Feature Specification: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration
+
+**Feature Branch**: `416-tenantpilot-agent-skill-layer-v1`
+**Created**: 2026-06-25
+**Corrected**: 2026-06-25
+**Status**: Corrected / Ready for implementation
+**Input**: User correction request to include both TenantPilot Agent Skill Layer V1 and AGENTS.md router integration.
+
+## Purpose
+
+Spec 416 creates the first minimal reusable TenantPilot Agent Skill Layer V1 and integrates a router rule into `AGENTS.md` so agents know how to activate the correct skills before repository work.
+
+The corrected scope intentionally includes both:
+
+- Agent Skill Layer V1 under `.agent/skills/**`.
+- Router Integration in `AGENTS.md`.
+
+This is repository workflow/documentation work only. It must not implement Laravel runtime behavior, product UI behavior, tests, migrations, seeders, config, routes, resources, services, policies, jobs, package files, or application dependencies.
+
+## Correction Summary
+
+- The original draft targeted `.codex/skills/**` only.
+- This correction changes the implementation target to `.agent/skills/**` as the skill library.
+- `AGENTS.md` becomes the activation/router entry point.
+- The corrected spec must not split basic router integration into a future Spec 417.
+- Any previous implementation-report evidence for `.codex/skills/**` is superseded by this correction and must not be treated as merge evidence for the corrected scope.
+
+## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
+
+- **Problem**: TenantPilot agent rules are spread across `AGENTS.md`, the constitution, specs, audit findings, product-surface contracts, guidelines, and repeated prompts. Without a router entry point, agents can miss the skill layer entirely.
+- **Today's failure**: A skill layer without `AGENTS.md` routing is discoverable only when the current model/session already knows to look for it. Future agents need a mandatory lightweight entry point before repository work.
+- **User-visible improvement**: No product UI changes. The improvement is workflow safety: future agents are instructed to inspect the router, activate relevant hard gates, report activated skills, and stop before implementation when hard-gate stop conditions trigger.
+- **Smallest enterprise-capable version**: One `.agent/skills/README.md`, the scoped V1 `SKILL.md` files, and one concise `AGENTS.md` router section. Optional `docs/agent-workflow.md` is allowed only if `AGENTS.md` would otherwise become too large.
+- **Explicit non-goals**: No generic enterprise standards library, no 50+ skill zoo, no runtime behavior, no test/migration/config/product changes, no package changes, no huge duplicated `AGENTS.md`, and no requirement to load every skill by default.
+- **Permanent complexity imported**: A repository skill library, a router rule in `AGENTS.md`, a skill taxonomy/maturity vocabulary, and maintenance responsibility when repo truth changes.
+- **Why now**: The repo has accumulated validated contracts around workspace scope, RBAC, OperationRun truth, customer output, evidence anchors, provider freshness, Product Surface, Filament/Livewire, browser audit, and TCM cutover. These must be reusable without relying on long prompts.
+- **Approval class**: Cleanup / Consolidation.
+- **Red flags triggered**: New meta-infrastructure and foundation-like wording. Defense: the layer is repo-specific, bounded, documentation/workflow-only, and explicitly forbids broad standards skills or runtime frameworks.
+- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
+- **Decision**: approve as a bounded preparation package after this correction.
+
+## Spec Scope Fields *(mandatory)*
+
+- **Scope**: repository workflow/documentation only.
+- **Future implementation files allowed**: `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, and `specs/416-tenantpilot-agent-skill-layer-v1/**`.
+- **Primary Routes**: N/A - no application route or rendered UI surface is added or changed.
+- **Data Ownership**: N/A - no runtime data ownership or persistence changes.
+- **RBAC**: N/A for application authorization behavior. The skills must encode RBAC and workspace isolation guidance for future work.
+
+## Deliverables
+
+1. Create `.agent/skills/README.md`.
+2. Create the V1 skill files under `.agent/skills/**`.
+3. Update `AGENTS.md` with a TenantPilot Agent Skill Router section.
+4. Optionally create `docs/agent-workflow.md` only if the router section would exceed 12 lines or would need to duplicate skill details inside `AGENTS.md`.
+5. Keep the implementation documentation/workflow-only.
+6. Do not modify runtime behavior.
+
+## Required Skill Structure
+
+```text
+.agent/
+  skills/
+    README.md
+    repo-contracts/
+      workspace-scope-safety/
+        SKILL.md
+      rbac-action-safety/
+        SKILL.md
+      operation-run-truth/
+        SKILL.md
+      customer-output-gate/
+        SKILL.md
+      evidence-anchor-contract/
+        SKILL.md
+      provider-freshness-semantics/
+        SKILL.md
+      product-surface-gate/
+        SKILL.md
+    workflows/
+      spec-readiness-gate/
+        SKILL.md
+      filament-livewire-v5-change-loop/
+        SKILL.md
+      browser-readonly-audit/
+        SKILL.md
+    temporary-migrations/
+      tcm-cutover-guard/
+        SKILL.md
+```
+
+## AGENTS.md Router Integration Requirements
+
+`AGENTS.md` must include a concise router rule equivalent to:
+
+```markdown
+## TenantPilot Agent Skill Router
+
+Before starting any repository task, inspect `.agent/skills/README.md`.
+Activate only the skills relevant to the requested task.
+Do not load all skills by default.
+Before implementation or review, report:
+- activated skills
+- why each skill was activated
+- branch
+- HEAD
+- dirty state
+- hard-gate stop conditions, if any
+
+Hard-gate skills are blocking. If a hard-gate stop condition is met, stop before implementation and report the blocker.
+Prefer current repo evidence, active specs, tests, and validated contracts over historical prompts or inventory-only specs.
+Inventory-only specs are hints, not hard evidence.
+Temporary migration skills must include expiry or review criteria.
+```
+
+The router must make clear:
+
+- `.agent/skills/**` is the skill library.
+- `AGENTS.md` is the activation/router entry point.
+- Agents must not load all skills by default.
+- Agents must read `.agent/skills/README.md` before repository work.
+- Agents must activate only relevant skills based on task triggers.
+- Agents must report activated skills and reasons before implementation or review.
+- Hard-gate skill stop conditions block implementation.
+- Current repo evidence beats historical prompts.
+- Inventory-only specs are hints, not hard evidence.
+- Temporary skills require expiry or review conditions.
+
+## UI Surface Impact *(mandatory - UI-COV-001)*
+
+Does this spec add, remove, rename, or materially change any reachable product UI surface?
+
+- [x] No UI surface impact
+- [ ] Existing page changed
+- [ ] New page/route added
+- [ ] Navigation changed
+- [ ] Filament panel/provider surface changed
+- [ ] New modal/drawer/wizard/action added
+- [ ] New table/form/state added
+- [ ] Customer-facing surface changed
+- [ ] Dangerous action changed
+- [ ] Status/evidence/review presentation changed
+- [ ] Workspace/environment context presentation changed
+
+## UI/Productization Coverage
+
+N/A - no reachable product UI surface impact. This spec creates repository workflow/documentation artifacts only. It must not change Filament resources/pages, Livewire components, Blade views, routes, navigation, actions, modals, tables, forms, customer output, report surfaces, review/evidence surfaces, or provider/restore UI.
+
+## Product Surface Impact
+
+Reference: `docs/product/standards/product-surface-contract.md`.
+
+- **Product Surface Contract applies?**: no - no rendered product surface changes.
+- **Page archetype**: N/A.
+- **Primary user question**: N/A.
+- **Primary action**: N/A.
+- **Surface budget result**: N/A.
+- **Technical Annex / deep-link demotion**: N/A - no product view changes.
+- **Canonical status vocabulary**: N/A - no product-facing labels added.
+- **Visible complexity impact**: neutral for rendered product UI.
+- **Product Surface exceptions**: none.
+
+## Browser Verification Plan *(mandatory)*
+
+- **Browser proof required?**: no.
+- **No-browser rationale**: `N/A - no rendered UI surface changed`.
+- **Focused path when required**: N/A.
+- **Primary interaction to execute**: N/A.
+- **Console, Livewire, Filament, network, and 500-error checks**: N/A.
+- **Full-suite failure triage**: N/A unless implementation unexpectedly changes rendered UI, which is out of scope and requires spec amendment.
+
+## Human Product Sanity Check *(mandatory)*
+
+- **Required?**: no rendered product sanity.
+- **No-human-sanity rationale**: N/A - no product surface changed.
+- **Workflow sanity target**: Reviewers should verify the skill layer and router are smaller and clearer than repeated prompt blocks, do not create false authority over repo truth, and do not require agents to load every skill by default.
+
+## Cross-Cutting / Shared Pattern Reuse
+
+- **Cross-cutting feature?**: yes, repository-workflow only.
+- **Interaction class(es)**: agent skill activation, implementation/review guardrails, documentation workflow.
+- **Systems touched**: `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, and this spec package.
+- **Existing pattern(s) to extend**: existing repository-level agent instructions and skill `SKILL.md` convention.
+- **Allowed deviation and why**: `.agent/skills/**` is the corrected skill-library target for router integration. `.codex/skills/**` is not the corrected implementation target for Spec 416.
+- **Consistency impact**: Each skill must use the required section template and activation/stop-condition language to avoid parallel prompt styles.
+- **Review focus**: Confirm the implementation does not add runtime frameworks, generic standards-only skills, a huge `AGENTS.md`, or load-all-by-default behavior.
+
+## OperationRun UX Impact
+
+- **Touches OperationRun start/completion/link UX?**: no.
+- **Shared OperationRun UX contract/layer reused**: N/A.
+- **Delegated start/completion UX behaviors**: N/A.
+- **Queued DB-notification policy**: N/A.
+- **Terminal notification path**: N/A.
+- **Exception required?**: none.
+
+## Provider Boundary / Platform Core Check
+
+- **Shared provider/platform boundary touched?**: no runtime seam touched.
+- **Boundary classification**: N/A.
+- **Neutral platform terms preserved or introduced**: Skills must preserve current constitution language: workspace, managed environment, provider connection, provider-owned metadata, operation, governed subject, evidence, and customer-safe output.
+- **Provider-specific semantics retained and why**: Microsoft/Graph may appear only as current repo evidence or examples inside skills, not as platform-core truth.
+- **Why this does not deepen provider coupling accidentally**: No application code or platform-core runtime contract changes.
+- **Follow-up path**: none for basic router usage.
+
+## Proportionality Review *(mandatory when structural complexity is introduced)*
+
+- **New source of truth?**: no product/runtime source of truth. Yes, a repository workflow guidance source for agent activation is introduced.
+- **New persisted entity/table/artifact?**: no runtime persistence. Yes, repository documentation/workflow artifacts under `.agent/skills/**` and `AGENTS.md`.
+- **New abstraction?**: yes, a small agent skill layer plus a router rule for existing repo contracts.
+- **New enum/state/reason family?**: no runtime enum/state family. Skill maturity and gate type labels are documentation taxonomy only.
+- **New cross-domain UI framework/taxonomy?**: no runtime UI framework. Product Surface skill must explicitly forbid turning Product Surface guidance into runtime presenter/framework code.
+- **Current operator problem**: Future agents need a reliable way to activate the correct existing repo contract before repository work.
+- **Existing structure is insufficient because**: Rules exist but are distributed; a skill layer alone is not enough unless `AGENTS.md` routes agents to it.
+- **Narrowest correct implementation**: One `.agent/skills/README.md`, the listed V1 skills, and one concise `AGENTS.md` router section.
+- **Ownership cost**: Skills and router must be kept current when constitution, Product Surface Contract, Filament baseline, RBAC contracts, OperationRun contracts, provider freshness semantics, customer/evidence gates, or workflow rules materially change.
+- **Alternative intentionally rejected**: Generic enterprise standards library, 50+ skill zoo, automatic all-skill loading, runtime frameworks, and a separate future spec for basic router integration.
+- **Release truth**: current-release workflow truth based on completed/recent specs and current repo guidance.
+
+## Testing / Lane / Runtime Impact *(mandatory)*
+
+- **Test purpose / classification**: N/A for Laravel runtime; repository artifact verification only.
+- **Validation lane(s)**: N/A for app/Pest/browser/PostgreSQL lanes. Use read-only shell checks for files, headings, router text, quarantine/path constraints, and final diff scope.
+- **Why this classification and these lanes are sufficient**: The spec creates markdown workflow artifacts and updates `AGENTS.md`. Runtime test suites would not prove this docs/workflow behavior.
+- **New or expanded test families**: none.
+- **Fixture / helper cost impact**: none.
+- **Heavy-family visibility / justification**: none.
+- **Special surface test profile**: N/A.
+- **Test governance outcome**: `keep` - artifact/router verification remains the narrowest sufficient lane because no runtime behavior, tests, fixtures, helpers, browser coverage, or heavy-governance family changes.
+- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage - `N/A - no rendered UI surface changed`.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Select the right TenantPilot contract skill (Priority: P1)
+
+As an implementation or review agent, I want a compact skill README that tells me which TenantPilot skill to activate for a task so I do not load every historical spec or miss the relevant guardrail.
+
+**Independent Test**: Inspect `.agent/skills/README.md` and confirm it lists all V1 skills, activation triggers, maturity/gate types, quarantine warnings, currentness rules, and "do not load all skills by default".
+
+### User Story 2 - Route future agents through AGENTS.md (Priority: P1)
+
+As a future agent entering the repository, I want `AGENTS.md` to route me to `.agent/skills/README.md` before repository work so the skill layer is actually used.
+
+**Independent Test**: Inspect `AGENTS.md` and confirm the TenantPilot Agent Skill Router section includes the required router rules, branch/HEAD/dirty-state reporting, hard-gate blocking semantics, and current-evidence preference.
+
+### User Story 3 - Execute repo-contract hard gates honestly (Priority: P1)
+
+As an implementation or review agent, I want each hard-gate skill to state activation conditions, source evidence, required repo context, execution checklist, stop conditions, and required evidence after use.
+
+**Independent Test**: For every L4 hard-gate skill, verify all required headings exist and stop conditions include concrete failure modes from the current constitution, validated specs, and repo source evidence.
+
+### User Story 4 - Preserve quarantine and temporary-skill honesty (Priority: P2)
+
+As a reviewer, I want the skill layer and router to identify historical or temporary rules that must not be preserved as current truth.
+
+**Independent Test**: Inspect the README, relevant skills, and `AGENTS.md` router for the quarantine list, current-repo-evidence preference, inventory-only hint rule, and temporary skill expiry/review requirements.
+
+### Edge Cases
+
+- The implementation must stop if it would create a generic SOC2/GDPR/SSDF/enterprise-best-practice skill.
+- The implementation must stop if it would require agents to load all skills by default.
+- The implementation must stop if any runtime/app/test/migration/config/package file change is needed.
+- The implementation must document any missing source-evidence file instead of inventing support.
+- The implementation must stop if the router would turn `AGENTS.md` into a duplicated copy of all skills.
+
+## Functional Requirements
+
+- **FR-416-001**: The implementation MUST create `.agent/skills/README.md` as the V1 skill-layer index.
+- **FR-416-002**: The README MUST state that the skill layer is not a replacement for specs, tests, code review, current repo truth, or the TenantPilot constitution.
+- **FR-416-003**: The README MUST instruct agents not to load all skills by default and to activate skills by task trigger.
+- **FR-416-004**: The README MUST include the maturity model L0 through L4 and gate type definitions.
+- **FR-416-005**: The README MUST include a V1 activation table covering all required skills.
+- **FR-416-006**: The README and relevant skills MUST quarantine these rules: `tenant_id` as platform-core ownership truth, Coverage v1 vocabulary as customer truth, v1-v2 adapters, fallback readers, dual writes, fallback-to-latest evidence, OperationRun as default customer proof, stale provider Healthy/Ready semantics, limited customer download vocabulary, raw provider/evidence payload default display, Product Surface runtime framework, and historical audits as current truth.
+- **FR-416-007**: The implementation MUST use `.agent/skills/**` as the skill library.
+- **FR-416-008**: The implementation MUST update `AGENTS.md` with the TenantPilot Agent Skill Router section.
+- **FR-416-009**: The implementation MAY create `docs/agent-workflow.md` only if keeping the required router guidance inside `AGENTS.md` would make the router exceed 12 lines or require duplicated skill details inside `AGENTS.md`.
+- **FR-416-010**: Every generated `SKILL.md` MUST include these headings: Purpose, Activate When, Do Not Activate When, Maturity, Gate Type, Source Evidence, External Anchors, Required Repo Context, Execution Checklist, Stop Conditions, Required Evidence After Use, Common Failure Modes, Quarantined Rules, Review / Expiry.
+- **FR-416-011**: If a heading is not applicable for a skill, it MUST state `Not applicable.` rather than being omitted.
+- **FR-416-012**: Create `repo-contracts/workspace-scope-safety` as an L4 hard-gate skill.
+- **FR-416-013**: Create `repo-contracts/rbac-action-safety` as an L4 hard-gate skill.
+- **FR-416-014**: Create `repo-contracts/operation-run-truth` as an L4 hard-gate skill.
+- **FR-416-015**: Create `repo-contracts/customer-output-gate` as an L4 hard-gate skill.
+- **FR-416-016**: Create `repo-contracts/evidence-anchor-contract` as an L4 hard-gate skill.
+- **FR-416-017**: Create `repo-contracts/provider-freshness-semantics` as an L4 hard-gate skill.
+- **FR-416-018**: Create `repo-contracts/product-surface-gate` as an L3 checklist skill.
+- **FR-416-019**: Create `workflows/spec-readiness-gate` as an L3 checklist skill.
+- **FR-416-020**: Create `workflows/filament-livewire-v5-change-loop` as an L3 checklist skill.
+- **FR-416-021**: Create `workflows/browser-readonly-audit` as an L2/L3 checklist workflow skill.
+- **FR-416-022**: Create `temporary-migrations/tcm-cutover-guard` as an L3 temporary migration gate skill.
+- **FR-416-023**: The TCM cutover guard MUST state that it expires after Coverage v2 / TCM activation and legacy coverage vocabulary cutover are complete.
+- **FR-416-024**: The implementation MUST NOT create generic standards-only skills such as `soc2`, `gdpr`, `ssdf`, or `enterprise-best-practice`.
+- **FR-416-025**: The implementation MUST NOT change Laravel application code, Filament resources/pages, Livewire components, policies, services, jobs, migrations, seeders, tests, runtime config, routes, views, assets, package files, or lock files.
+- **FR-416-026**: The implementation report MUST use the final report format defined below and end with PASS, PASS WITH CONDITIONS, or FAIL.
+
+## Allowed Final Implementation Diff
+
+Allowed implementation changes are only:
+
+- `.agent/skills/**`
+- `AGENTS.md`
+- `docs/agent-workflow.md` (optional)
+- `specs/416-tenantpilot-agent-skill-layer-v1/**`
+
+Forbidden implementation changes include:
+
+- `app/**`
+- `bootstrap/**`
+- `config/**`
+- `database/**`
+- `routes/**`
+- `resources/**`
+- `tests/**`
+- `composer.json`
+- `composer.lock`
+- `package.json`
+- `package-lock.json`
+- `pnpm-lock.yaml`
+- `yarn.lock`
+- `vite.config.*`
+- `tailwind.config.*`
+
+## Non-Goals
+
+Spec 416 must not:
+
+- create a generic enterprise standards library
+- create a 50+ skill zoo
+- modify application/runtime behavior
+- change tests
+- change migrations
+- change config
+- change product behavior
+- change packages or lock files
+- turn `AGENTS.md` into a huge duplicated copy of all skills
+- require agents to load every skill by default
+- split basic router integration into a future Spec 417
+
+## Acceptance Criteria
+
+### Skill Layer
+
+- All required skill files exist under `.agent/skills/**`.
+- `.agent/skills/README.md` exists and functions as the skill-layer index.
+- The README states that active specs, tests, code review, current repo truth, and constitution override skill text.
+- The README tells agents not to load all skills by default.
+- Every required `SKILL.md` includes all required headings.
+- README and relevant skills include applicable quarantine rules.
+- No generic standards-only skill files are created.
+- `temporary-migrations/tcm-cutover-guard/SKILL.md` contains explicit expiry/review language.
+
+### Router Integration
+
+- `AGENTS.md` contains a TenantPilot Agent Skill Router section.
+- The router tells agents to read `.agent/skills/README.md`.
+- The router tells agents to activate only relevant skills.
+- The router tells agents not to load all skills by default.
+- The router tells agents to report activated skills and reasons before implementation or review.
+- The router treats hard-gate stop conditions as blockers.
+- The router requires branch, HEAD, and dirty state before file changes.
+- The router says current repo evidence beats historical prompts.
+- The router says inventory-only specs are hints, not hard evidence.
+- The router says temporary skills require expiry/review criteria.
+
+### Scope Safety
+
+- Final diff contains only allowed paths.
+- Runtime files changed: no.
+- Tests changed: no.
+- Migrations changed: no.
+- Config changed: no.
+- Routes/resources/services/policies/jobs/package files changed: no.
+- Browser proof remains `N/A - no rendered UI surface changed`.
+
+## Verification Requirements
+
+Required verification commands or equivalents:
+
+```bash
+find .agent/skills -name 'SKILL.md' -print | sort
+grep -n "TenantPilot Agent Skill Router" AGENTS.md
+grep -n ".agent/skills/README.md" AGENTS.md
+grep -n "Do not load all skills by default" AGENTS.md
+grep -n "Hard-gate skills are blocking" AGENTS.md
+grep -n "Inventory-only specs are hints" AGENTS.md
+```
+
+Additional required checks:
+
+- heading validation for every `.agent/skills/**/SKILL.md`
+- no generic standards-only skill paths such as `soc2`, `gdpr`, `ssdf`, or `enterprise-best-practice`
+- TCM expiry/review language exists
+- final diff contains only allowed paths
+- forbidden runtime/test/config/package paths are absent from the diff
+- `git diff --check` covers tracked or staged implementation files before close-out
+- `git status --short` is recorded in the report
+
+## Final Report Format
+
+The future implementation report MUST include:
+
+A. Branch / HEAD / Dirty State
+B. Files Created
+C. Files Modified
+D. Skills Created
+E. AGENTS.md Router Added: yes/no
+F. Maturity / Gate Type Summary
+G. Quarantine Rules Included
+H. Verification Commands Run
+I. Runtime Files Changed: yes/no
+J. Tests Changed: yes/no
+K. Migrations Changed: yes/no
+L. Config Changed: yes/no
+M. PASS / PASS WITH CONDITIONS / FAIL
+
+## Suggested Commit Message
+
+```text
+docs: add TenantPilot agent skill layer and router
+```
+
+## Risks
+
+- The router can become stale if the skill library moves or if the constitution changes.
+- `AGENTS.md` can become too long if it duplicates skill content instead of routing to the README.
+- Too many skills can encourage broad context loading. V1 mitigates this through a small list and progressive disclosure.
+- Skills can become false authority if they are not kept subordinate to current repo evidence, active specs, tests, validated contracts, and the constitution.
+
+## Assumptions
+
+- `.agent/skills/**` is the corrected implementation target for Spec 416.
+- `AGENTS.md` is the repository entry point that future agents are expected to read.
+- Runtime app behavior is not needed to make the skill router useful.
+- Optional `docs/agent-workflow.md` should be avoided unless the router section would exceed 12 lines or would need to duplicate skill details inside `AGENTS.md`.
+- Existing inventory-only specs are hints and must not be treated as hard current evidence without validation.
+
+## Open Questions
+
+None blocking implementation.

specs/416-tenantpilot-agent-skill-layer-v1/tasks.md

@@ -0,0 +1,151 @@
+# Tasks: Spec 416 - TenantPilot Agent Skill Layer V1 and Router Integration
+
+**Input**: Design documents from `/specs/416-tenantpilot-agent-skill-layer-v1/`
+**Prerequisites**: `spec.md`, `plan.md`, `checklists/requirements.md`
+**Implementation status**: Corrected spec implemented by the Spec Kit implementation loop. Artifact/router verification completed; see `implementation-report.md`.
+
+## Requirement Coverage Map
+
+- **FR-416-001**: covered by T006.
+- **FR-416-002**: covered by T006.
+- **FR-416-003**: covered by T007.
+- **FR-416-004**: covered by T008.
+- **FR-416-005**: covered by T009.
+- **FR-416-006**: covered by T010 and T018.
+- **FR-416-007**: covered by T002, T006-T025, and NT001.
+- **FR-416-008**: covered by T026-T034, T038-T042, and T049.
+- **FR-416-009**: covered by T035.
+- **FR-416-010**: covered by T018 and T037.
+- **FR-416-011**: covered by T018.
+- **FR-416-012**: covered by T011.
+- **FR-416-013**: covered by T012.
+- **FR-416-014**: covered by T013.
+- **FR-416-015**: covered by T014.
+- **FR-416-016**: covered by T015.
+- **FR-416-017**: covered by T016.
+- **FR-416-018**: covered by T017.
+- **FR-416-019**: covered by T020.
+- **FR-416-020**: covered by T021.
+- **FR-416-021**: covered by T022.
+- **FR-416-022**: covered by T023.
+- **FR-416-023**: covered by T024.
+- **FR-416-024**: covered by T019, T043, and NT002.
+- **FR-416-025**: covered by T044, T045, T050, and NT003.
+- **FR-416-026**: covered by T048-T052.
+
+## Test Governance Checklist
+
+- [x] Lane assignment remains N/A for Laravel runtime and uses artifact/router verification only.
+- [x] No Pest, browser, PostgreSQL, or heavy-governance test family is added unless runtime scope changes, which requires spec amendment.
+- [x] Planned validation commands cover `.agent/skills/**` and `AGENTS.md` without booting the application.
+- [x] Browser proof is explicitly `N/A - no rendered UI surface changed`.
+- [x] Human Product Sanity is explicitly N/A for rendered product UI and limited to workflow sanity.
+- [x] Implementation report records no runtime files, tests, migrations, config, routes, views, assets, package files, or lock files changed.
+- [x] Test governance outcome is `keep`: artifact/router checks remain the validation lane unless runtime scope changes by spec amendment.
+
+## Phase 1: Preflight And Repo Truth
+
+**Purpose**: Confirm the implementation target before writing skill files.
+
+- [x] T001 Capture branch, HEAD, and `git status --short` for the implementation report.
+- [x] T002 Confirm `.agent/skills/**` is the corrected Spec 416 target and `.codex/skills/**` is not part of the final implementation diff.
+- [x] T003 Confirm existing dirty/untracked work will not be overwritten or accidentally included outside allowed paths.
+- [x] T004 Re-read `AGENTS.md`, `.specify/memory/constitution.md`, `docs/ai-coding-rules.md`, relevant `docs/*-guidelines.md`, and `docs/product/standards/product-surface-contract.md` before authoring skill/router content.
+- [x] T005 Treat Specs 395, 400, 402, 414, and 415 as read-only context and do not modify their files.
+
+## Phase 2: Skill README
+
+**Purpose**: Create the progressive-disclosure entry point.
+
+- [x] T006 Create `.agent/skills/README.md` with purpose and the statement that the skill layer is not a replacement for active specs, tests, code review, current repo truth, or the constitution.
+- [x] T007 Add the progressive disclosure rule: do not load all skills by default; activate skills by task trigger.
+- [x] T008 Add the maturity model L0 through L4 and gate type definitions.
+- [x] T009 Add a V1 activation table for all Spec 416 skills with maturity, gate type, and trigger summary.
+- [x] T010 Add the quarantine list, currentness warning, inventory-only hint warning, and temporary-skill expiry/review warning.
+
+## Phase 3: Repo Contract Skills
+
+**Purpose**: Create the L4/L3 repo-contract skills with concrete stop conditions.
+
+- [x] T011 Create `.agent/skills/repo-contracts/workspace-scope-safety/SKILL.md` as an L4 hard-gate skill.
+- [x] T012 Create `.agent/skills/repo-contracts/rbac-action-safety/SKILL.md` as an L4 hard-gate skill.
+- [x] T013 Create `.agent/skills/repo-contracts/operation-run-truth/SKILL.md` as an L4 hard-gate skill.
+- [x] T014 Create `.agent/skills/repo-contracts/customer-output-gate/SKILL.md` as an L4 hard-gate skill.
+- [x] T015 Create `.agent/skills/repo-contracts/evidence-anchor-contract/SKILL.md` as an L4 hard-gate skill.
+- [x] T016 Create `.agent/skills/repo-contracts/provider-freshness-semantics/SKILL.md` as an L4 hard-gate skill.
+- [x] T017 Create `.agent/skills/repo-contracts/product-surface-gate/SKILL.md` as an L3 checklist skill.
+- [x] T018 For every generated `SKILL.md`, include all required headings and write `Not applicable.` for non-applicable sections.
+- [x] T019 Keep each skill repo-specific and bounded to TenantPilot/TenantAtlas evidence; do not create generic SOC2/GDPR/SSDF/enterprise-best-practice skills.
+
+## Phase 4: Workflow Skills
+
+**Purpose**: Create workflow skills that guide preparation, Filament/Livewire changes, and read-only browser audits.
+
+- [x] T020 Create `.agent/skills/workflows/spec-readiness-gate/SKILL.md` as an L3 checklist skill.
+- [x] T021 Create `.agent/skills/workflows/filament-livewire-v5-change-loop/SKILL.md` as an L3 checklist skill.
+- [x] T022 Create `.agent/skills/workflows/browser-readonly-audit/SKILL.md` as an L2/L3 workflow skill.
+
+## Phase 5: Temporary Migration Skill
+
+**Purpose**: Keep the TCM / Coverage v2 cutover guard temporary and explicit.
+
+- [x] T023 Create `.agent/skills/temporary-migrations/tcm-cutover-guard/SKILL.md` as an L3 temporary migration gate.
+- [x] T024 Include expiry/review language: expires after Coverage v2 / TCM activation and legacy coverage vocabulary cutover are complete.
+- [x] T025 Include stop conditions for remote capture requirements, UI activation, legacy adapters, fallback readers, dual truth, `tenant_id` platform ownership, and customer-facing claims depending on inactive TCM kernel.
+
+## Phase 6: AGENTS.md Router Integration
+
+**Purpose**: Make the skill layer discoverable before repository work.
+
+- [x] T026 Add `## TenantPilot Agent Skill Router` to `AGENTS.md`.
+- [x] T027 In the router, require agents to inspect `.agent/skills/README.md` before repository work.
+- [x] T028 In the router, require activating only relevant skills and not loading all skills by default.
+- [x] T029 In the router, require reporting activated skills and reasons before implementation or review.
+- [x] T030 In the router, require branch, HEAD, dirty state, and hard-gate stop conditions before file changes.
+- [x] T031 In the router, state that hard-gate skills are blocking and stop implementation when triggered.
+- [x] T032 In the router, state that current repo evidence, active specs, tests, and validated contracts beat historical prompts or inventory-only specs.
+- [x] T033 In the router, state that inventory-only specs are hints, not hard evidence.
+- [x] T034 In the router, state that temporary migration skills require expiry or review criteria.
+- [x] T035 Optionally create `docs/agent-workflow.md` only if the router would exceed 12 lines or duplicate skill details inside `AGENTS.md`.
+
+## Phase 7: Verification
+
+**Purpose**: Prove the docs/workflow artifact shape without running app tests.
+
+- [x] T036 Run `find .agent/skills -name 'SKILL.md' -print | sort` and record the result.
+- [x] T037 Run heading validation over every `.agent/skills/**/SKILL.md`.
+- [x] T038 Run `grep -n "TenantPilot Agent Skill Router" AGENTS.md`.
+- [x] T039 Run `grep -n ".agent/skills/README.md" AGENTS.md`.
+- [x] T040 Run `grep -n "Do not load all skills by default" AGENTS.md`.
+- [x] T041 Run `grep -n "Hard-gate skills are blocking" AGENTS.md`.
+- [x] T042 Run `grep -n "Inventory-only specs are hints" AGENTS.md`.
+- [x] T043 Run a negative generic-skill path check for `soc2`, `gdpr`, `ssdf`, and `enterprise-best-practice`.
+- [x] T044 Run a final diff-scope check confirming only `.agent/skills/**`, `AGENTS.md`, optional `docs/agent-workflow.md`, and Spec 416 files changed.
+- [x] T045 Run a forbidden-path check confirming no `app/**`, `bootstrap/**`, `config/**`, `database/**`, `routes/**`, `resources/**`, `tests/**`, package file, lock file, Vite config, or Tailwind config changed.
+- [x] T046 Run `git diff --check` after the implementation files are tracked or staged so new files are included in the check. Implementation note: tracked modifications passed `git diff --check`; new `.agent/skills/**` files are untracked and passed the separate trailing-whitespace check recorded in `implementation-report.md`.
+- [x] T047 Run `git status --short` and record the final dirty state.
+
+## Phase 8: Implementation Report
+
+**Purpose**: Close the implementation with precise evidence.
+
+- [x] T048 Create or update `specs/416-tenantpilot-agent-skill-layer-v1/implementation-report.md` using sections A through M from `spec.md`.
+- [x] T049 Record `AGENTS.md Router Added: yes/no`.
+- [x] T050 Record runtime files changed: no; tests changed: no; migrations changed: no; config changed: no.
+- [x] T051 Record browser proof as `N/A - no rendered UI surface changed`.
+- [x] T052 Record no completed historical spec was rewritten or stripped of close-out/validation/task/browser/review history.
+
+## Non-Goals
+
+- [x] NT001 Do not target `.codex/skills/**` for the corrected Spec 416 implementation.
+- [x] NT002 Do not create generic SOC2/GDPR/SSDF/enterprise-best-practice skill files.
+- [x] NT003 Do not modify application runtime files, tests, migrations, config, routes, resources, services, policies, jobs, assets, package files, lock files, or completed specs.
+- [x] NT004 Do not require agents to load all skills by default.
+- [x] NT005 Do not turn Product Surface guidance into runtime code, presenter layers, enum families, or broad UI frameworks.
+- [x] NT006 Do not split basic router integration into a future Spec 417.
+
+## Suggested Commit Message
+
+```text
+docs: add TenantPilot agent skill layer and router
+```