---
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.