TenantAtlas/specs/196-hard-filament-nativity-cleanup/quickstart.md

Quickstart: Hard Filament Nativity Cleanup

Goal

Implement Spec 196 by replacing three pseudo-native UI contracts with native Filament or Livewire interaction models while preserving current scope, summaries, empty states, and drilldown behavior.

Implementation Sequence

1. Prepare shared test and guard scaffolding

Touch:

• apps/platform/tests/Feature/Filament/InventoryItemDependencyEdgesTableTest.php
• apps/platform/tests/Feature/Filament/TenantRequiredPermissionsPageTest.php
• apps/platform/tests/Feature/Guards/FilamentTableStandardsGuardTest.php
• apps/platform/tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php
• apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php

Do:

• create the new focused surface-test entry points before story implementation starts
• perform the setup audit that decides whether any optional same-class extra hit passes every FR-196-015 admission check before any extra hit begins; otherwise lock scope to the three named surfaces
• add the shared guard expectations for new native page-table and faux-control regressions
• add the shared mount-only query-seeding regression coverage that later story work depends on

2. Replace the inventory dependency GET form with an embedded TableComponent

Touch:

• apps/platform/app/Filament/Resources/InventoryItemResource.php
• apps/platform/app/Livewire/InventoryItemDependencyEdgesTable.php
• apps/platform/resources/views/filament/components/dependency-edges.blade.php

Do:

• extend the focused dependency tests before landing implementation changes
• embed a native Filament TableComponent inside the existing inventory detail section
• move direction and relationship state into the component
• fetch dependency rows through current dependency services
• keep missing-target rendering and target-link behavior intact

Do not:

• create a new standalone route for dependencies
• convert the surface into a RelationManager
• keep request() as the primary interaction-state source

3. Convert TenantRequiredPermissions to a native page-owned filter and table contract

Touch:

• apps/platform/app/Filament/Pages/TenantRequiredPermissions.php
• apps/platform/resources/views/filament/pages/tenant-required-permissions.blade.php
• apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php only if a small adapter is needed

Do:

• extend the focused required-permissions tests before landing implementation changes
• add HasTable and InteractsWithTable
• replace pseudo-native filter controls with native filters and native search
• derive the summary, guidance, and copy payload blocks from the same normalized filter state that drives the table rows
• keep the route tenant authoritative and allow query values only as initial seed state

Do not:

• let query values redefine tenant scope
• split the page into a new resource or standalone workflow
• introduce a wrapper abstraction that merely hides the old filter bar

4. Convert EvidenceOverview to a native page-owned table

Touch:

• apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
• apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php

Do:

• extend the focused evidence overview tests before landing implementation changes
• add HasTable and InteractsWithTable
• move current row construction into a native table records callback
• convert the current tenant query prefilter into a native filter seeded from entitled query input only
• add native search across tenant-facing row labels
• keep row inspect behavior pointed at the existing tenant evidence drilldown
• keep empty-state behavior explicit and native

Do not:

• introduce a new read model or persistence layer
• widen the workspace-context route into a tenant-context route
• make remote calls during render

5. Run the final focused verification pack and formatting

Touch:

• apps/platform/tests/Feature/InventoryItemDependenciesTest.php
• apps/platform/tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php
• apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php
• apps/platform/tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php
• apps/platform/tests/Feature/Filament/InventoryItemDependencyEdgesTableTest.php
• apps/platform/tests/Feature/Filament/TenantRequiredPermissionsPageTest.php
• apps/platform/tests/Feature/Guards/FilamentTableStandardsGuardTest.php if newly applicable

Do:

• preserve current scope and authorization assertions
• replace GET-form assumptions with native Livewire or table-state assertions
• keep DB-only and no-Graph render guarantees
• keep unit tests for permission filtering and copy payload logic as domain-truth guards
• run the full focused Sail pack and pint only after the three story slices are complete

6. Stop on scope boundaries

If implementation touches any of the following, stop and defer instead of half-solving them here:

• shared detail micro-UI contract work
• monitoring page-state architecture
• global context shell behavior
• verification report viewer families
• diff, settings, restore preview, or enterprise-detail layout families

7. Record the release close-out in this quickstart

When implementation is complete, update this file with a short close-out note that records:

• which surfaces were actually cleaned
• whether any optional same-class extra hit was included or explicitly rejected, and if included, which FR-196-015 admission checks it satisfied
• which related themes stayed out of scope and were deferred
• which follow-up specs or artifacts were touched

Suggested Test Pack

Run the minimum targeted verification pack through Sail.

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/InventoryItemDependenciesTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/InventoryItemDependencyEdgesTableTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRequiredPermissionsPageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceOverviewPageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/FilamentTableStandardsGuardTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantRequiredPermissionsFilteringTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantRequiredPermissionsCopyPayloadTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantRequiredPermissionsOverallStatusTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantRequiredPermissionsFeatureImpactTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/TenantRequiredPermissionsFreshnessTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Manual Smoke Checklist

1. Open an inventory item detail page and confirm current record context stays visible, dependency direction and relationship changes happen in place without a foreign apply-and-reload workflow, missing-target markers remain visible where applicable, and empty-state copy still explains the no-results case.
2. Open tenant required permissions and confirm current tenant scope and active filter state remain visible, the filter surface feels native, summary counts and freshness stay consistent with the visible rows, guidance remains available, and copy flows still use the same filtered state.
3. Open evidence overview and confirm workspace scope and any active entitled-tenant filter remain visible, the table behaves like a native Filament report, artifact truth, freshness, and next-step context remain visible by default, Clear filters behaves correctly, and each authorized row still has one workspace-safe inspect path.
4. Confirm no cleaned surface leaks scope, rows, counts, or drilldown targets through query manipulation.
5. Confirm no implementation expanded into monitoring-state, shell, shared micro-UI redesign work, new wrapper layers, or new persistence created only to support the native controls.

Deployment Notes

• No migration is expected.
• No polling change is expected.
• No provider registration change is expected.
• No new assets are expected.
• Existing cd apps/platform && php artisan filament:assets deployment handling remains sufficient and unchanged.

Release Close-Out

• Cleaned surfaces: inventory item dependency edges now run through the embedded InventoryItemDependencyEdgesTable component; tenant required permissions now uses one page-owned native table contract; evidence overview now uses one page-owned native workspace table.
• Optional same-class extra hit decision: rejected. No additional nativity-bypass candidate passed every FR-196-015 admission check during setup, so scope remained frozen to the three named surfaces.
• Deferred themes kept out of scope: monitoring page-state architecture, global shell or context redesign, shared micro-UI or wrapper abstractions, verification viewer families, and any new persistence or asset work.
• Follow-up artifacts touched: this quickstart note, the Spec 196 task ledger, and the existing logical contract remained aligned without widening consumer scope.
• Focused Sail verification pack: passed on 2026-04-14 with 45 tests and 177 assertions across the Spec 196 feature, guard, and unit coverage set.
• Integrated-browser smoke sign-off: passed on http://localhost against tenant 19000000-0000-4000-8000-000000000191, including an inventory detail fixture (inventory-items/383) and evidence fixture (evidence/20). Verified in-place dependency filters with visible active filter chips and missing-target hints, native required-permissions search plus technical-details matrix continuity, and evidence overview tenant prefilter plus Clear filters behavior with workspace-safe drilldown links.
• Browser-log note: the integrated-browser session still contains old historical 419 and aborted-request noise from prior sessions, but no new Spec 196 surface-specific JavaScript failure blocked the smoke flow above.