18 KiB
Tasks: Inventory Coverage Truth
Input: Design documents from /specs/177-inventory-coverage-truth/
Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md
Tests: Required. Use Pest coverage in tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php, tests/Unit/Badges/BadgeCatalogTest.php, tests/Unit/Badges/InventoryCoverageStateBadgesTest.php, tests/Feature/Filament/InventoryCoverageTableTest.php, tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php, tests/Feature/Filament/InventoryPagesTest.php, tests/Feature/Filament/InventoryItemResourceTest.php, tests/Feature/Filament/InventoryCoverageRunContinuityTest.php, tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php, tests/Feature/Inventory/InventorySyncServiceTest.php, tests/Feature/Inventory/InventorySyncStartSurfaceTest.php, tests/Feature/Inventory/RunInventorySyncJobTest.php, tests/Feature/Operations/TenantlessOperationRunViewerTest.php, and tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php.
Operations: This feature reuses the existing inventory_sync OperationRun and does not introduce a new run type or change lifecycle ownership. Tasks must keep canonical run links and read-time rendering aligned without changing queued execution semantics.
RBAC: Existing workspace membership, tenant entitlement, and 404 vs 403 semantics remain authoritative. Tasks must preserve tenant-safe rendering and ensure basis-run links degrade safely when the current user cannot open the run.
Operator Surfaces: The inventory items list KPI header, the inventory coverage page, and canonical inventory-sync run detail must become tenant-coverage-first while keeping low-level diagnostics secondary.
Filament UI Action Surfaces: No new destructive actions or new action inventories are added. The existing Run Inventory Sync header action remains capability-gated and non-destructive, and the InventoryCoverage page keeps its derived-row no-detail exception.
Filament UI UX-001: No new create or edit screens are introduced. The inventory coverage page remains a searchable, filterable table with a single clear empty-state CTA, and run detail remains an enterprise-detail view surface.
Badges: Coverage-state semantics must stay centralized through BadgeDomain, BadgeCatalog, and BadgeRenderer; no page-local badge mappings are allowed.
Organization: Tasks are grouped by user story so each story can be implemented and validated as an independent increment once the shared tenant coverage contract is in place.
Phase 1: Setup (Shared Coverage Truth Scaffolding)
Purpose: Create the narrow runtime and regression entry points required for tenant coverage truth.
- T001 [P] Create the derived tenant coverage truth scaffolding in
app/Support/Inventory/TenantCoverageTruth.phpandapp/Support/Inventory/TenantCoverageTruthResolver.php - T002 [P] Create the focused regression scaffolding in
tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php,tests/Unit/Badges/InventoryCoverageStateBadgesTest.php, andtests/Feature/Filament/InventoryCoverageRunContinuityTest.php
Phase 2: Foundational (Blocking Coverage Contract)
Purpose: Build the shared derived coverage contract, basis-run selection, and centralized badge semantics that all user stories depend on.
⚠️ CRITICAL: No user story work should begin until this phase is complete.
- T003 [P] Extend basis-run and mixed-outcome payload coverage assertions in
tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.phpandtests/Feature/Inventory/RunInventorySyncJobTest.php - T004 [P] Add centralized inventory coverage badge mapping assertions in
tests/Unit/Badges/BadgeCatalogTest.phpandtests/Unit/Badges/InventoryCoverageStateBadgesTest.php - T005 [P] Implement the latest completed coverage-bearing inventory-sync selection helper in
app/Models/OperationRun.php - T006 [P] Implement the derived runtime fields and row contract in
app/Support/Inventory/TenantCoverageTruth.php - T007 Implement tenant coverage resolution, item-count joins, follow-up classification, and basis-run metadata in
app/Support/Inventory/TenantCoverageTruthResolver.php - T008 Implement the centralized inventory coverage state badge domain and mapper in
app/Support/Badges/BadgeDomain.php,app/Support/Badges/BadgeCatalog.php, andapp/Support/Badges/Domains/InventoryCoverageStateBadge.php
Checkpoint: A single derived tenant coverage contract now exists for all supported types, with centralized badge semantics and deterministic basis-run selection.
Phase 3: User Story 1 - Read Truthful Coverage At A Glance (Priority: P1) 🎯 MVP
Goal: Make the inventory KPI header and coverage page answer the tenant coverage question directly instead of implying completeness from restorable-item share or support metadata.
Independent Test: Seed a tenant with a coverage-bearing inventory-sync run that includes succeeded, failed, skipped, and omitted types plus current inventory items, then verify the inventory items list and coverage page show truthful counts, Unknown rows, and follow-up emphasis.
Tests for User Story 1
- T009 [P] [US1] Rewrite summary-surface expectations for truthful count-based coverage on the inventory items list in
tests/Feature/Filament/InventoryPagesTest.phpandtests/Feature/Filament/InventoryItemResourceTest.php - T010 [P] [US1] Add coverage-table assertions for
Succeeded,Failed,Skipped,Unknown, deterministic follow-up priority, no-basis-run messaging, and secondary support, restore, and compare metadata intests/Feature/Filament/InventoryCoverageTableTest.phpandtests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php
Implementation for User Story 1
- T011 [P] [US1] Replace the misleading coverage percentage with count-based tenant coverage facts, explicit no-basis-run messaging, and coverage-only terminology in
app/Filament/Widgets/Inventory/InventoryKpiHeader.php - T012 [P] [US1] Rewrite KPI supporting badge copy around follow-up counts, top-priority follow-up types, and observed-item counts without implying restore or compare readiness in
app/Support/Inventory/InventoryKpiBadges.php - T013 [US1] Refactor tenant coverage row assembly, deterministic follow-up ranking, and default-visible columns while keeping support, restore, and compare metadata secondary in
app/Filament/Pages/InventoryCoverage.php - T014 [US1] Rewrite the coverage page intro and summary copy to tenant-coverage-first language with explicit no-sync fallback guidance in
resources/views/filament/pages/inventory-coverage.blade.php - T015 [US1] Run the focused truthful-at-a-glance pack in
tests/Feature/Filament/InventoryCoverageTableTest.php,tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php,tests/Feature/Filament/InventoryPagesTest.php, andtests/Feature/Filament/InventoryItemResourceTest.php
Checkpoint: The inventory items list and coverage page now show tenant coverage truth first, with capability metadata clearly secondary.
Phase 4: User Story 2 - Move Cleanly From Coverage Truth To Run Truth (Priority: P1)
Goal: Make coverage surfaces cite the exact basis run, provide safe drill-through when authorized, and degrade cleanly when the run cannot be opened.
Independent Test: Seed a tenant with a coverage-bearing basis run and verify the inventory summary surfaces show the basis timestamp and run continuity, then verify a user without run access receives explanatory guidance instead of a dead-end link.
Tests for User Story 2
- T016 [P] [US2] Add basis-run continuity assertions for linked coverage summaries, explicit no-basis-run fallback, and tenant-scoped operations fallback in
tests/Feature/Filament/InventoryPagesTest.phpandtests/Feature/Filament/InventoryCoverageRunContinuityTest.php - T017 [P] [US2] Add safe degradation assertions for viewers who can see inventory truth but cannot open the basis run in
tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.phpandtests/Feature/Filament/InventoryCoverageRunContinuityTest.php
Implementation for User Story 2
- T018 [P] [US2] Surface basis-run summary, continuity actions, no-sync fallback, and provider or permission follow-up guidance on the coverage report in
app/Filament/Pages/InventoryCoverage.phpandresources/views/filament/pages/inventory-coverage.blade.php - T019 [P] [US2] Surface basis-run continuity and safe link rendering in the inventory KPI summary using
app/Filament/Widgets/Inventory/InventoryKpiHeader.phpandapp/Support/Inventory/TenantCoverageTruthResolver.php - T020 [US2] Run the focused continuity pack in
tests/Feature/Filament/InventoryCoverageRunContinuityTest.php,tests/Feature/Filament/InventoryPagesTest.php, andtests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php
Checkpoint: Coverage claims are now auditable through the basis run and remain safe when the current user cannot open the run detail.
Phase 5: User Story 3 - Diagnose Per-Type Inventory Sync Results Without Raw JSON (Priority: P2)
Goal: Make canonical inventory-sync run detail render human-readable per-type results and keep execution outcome separate from tenant coverage follow-up.
Independent Test: Seed an inventory-sync run with mixed per-type outcomes and verify the canonical run viewer shows a readable coverage section without relying on raw JSON.
Tests for User Story 3
- T021 [P] [US3] Add human-readable inventory-sync section assertions, including provider or permission follow-up guidance, in
tests/Feature/Operations/TenantlessOperationRunViewerTest.phpandtests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php - T022 [P] [US3] Extend mixed-outcome payload expectations for per-type coverage rows in
tests/Feature/Inventory/InventorySyncServiceTest.phpandtests/Feature/Inventory/RunInventorySyncJobTest.php
Implementation for User Story 3
- T023 [US3] Add the inventory-sync per-type coverage enterprise-detail section with explicit next-step guidance in
app/Filament/Resources/OperationRunResource.php - T024 [P] [US3] Create the human-readable per-type run coverage view with provider or permission follow-up cues in
resources/views/filament/infolists/entries/inventory-coverage-truth.blade.php - T025 [US3] Run the focused inventory-sync run-detail pack in
tests/Feature/Operations/TenantlessOperationRunViewerTest.php,tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php,tests/Feature/Inventory/InventorySyncServiceTest.php, andtests/Feature/Inventory/RunInventorySyncJobTest.php
Checkpoint: Inventory-sync run detail now explains per-type outcomes directly and no longer forces operators into raw JSON for core coverage truth.
Phase 6: Polish & Cross-Cutting Concerns
Purpose: Align copy, run focused verification, and confirm the feature stayed within the intended no-new-persistence boundary.
- T026 [P] Align operator-facing coverage labels, restore or compare separation, and helper copy across
app/Filament/Widgets/Inventory/InventoryKpiHeader.php,app/Support/Inventory/InventoryKpiBadges.php,app/Filament/Pages/InventoryCoverage.php, andapp/Filament/Resources/OperationRunResource.php - T027 Run
vendor/bin/sail bin pint --dirty --format agentfor touched files underapp/,resources/views/, andtests/ - T028 Run the focused Sail verification pack from
specs/177-inventory-coverage-truth/quickstart.mdagainsttests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php,tests/Unit/Badges/BadgeCatalogTest.php,tests/Unit/Badges/InventoryCoverageStateBadgesTest.php,tests/Feature/Filament/InventoryCoverageTableTest.php,tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php,tests/Feature/Filament/InventoryPagesTest.php,tests/Feature/Filament/InventoryItemResourceTest.php,tests/Feature/Filament/InventoryCoverageRunContinuityTest.php,tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php,tests/Feature/Inventory/InventorySyncServiceTest.php,tests/Feature/Inventory/InventorySyncStartSurfaceTest.php,tests/Feature/Inventory/RunInventorySyncJobTest.php,tests/Feature/Operations/TenantlessOperationRunViewerTest.php, andtests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php - T029 Validate that the final implementation introduces no schema migration, no inventory-sync backend rewrite, and no new persisted truth by reviewing
database/migrations/,app/Services/Inventory/InventorySyncService.php,app/Jobs/RunInventorySyncJob.php, andspecs/177-inventory-coverage-truth/plan.mdagainst the final diff - T030 [P] Review
app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.phpandapp/Filament/Pages/InventoryCoverage.phpagainstdocs/product/standards/list-surface-review-checklist.mdbefore final sign-off
Dependencies & Execution Order
Phase Dependencies
- Setup (Phase 1): No dependencies; start immediately.
- Foundational (Phase 2): Depends on Setup completion and blocks all user story work.
- User Story 1 (Phase 3): Depends on Foundational completion and delivers the MVP truth-correction slice.
- User Story 2 (Phase 4): Depends on User Story 1 because it extends the same summary surfaces with basis-run continuity and safe drill-through.
- User Story 3 (Phase 5): Depends on Foundational completion and can proceed in parallel with User Story 2 if staffed, since it focuses on canonical run detail.
- Polish (Phase 6): Depends on all desired user stories being complete.
User Story Dependencies
- User Story 1 (P1): Depends only on the shared derived coverage contract from Phase 2 and is the recommended MVP.
- User Story 2 (P1): Depends on User Story 1 because the same inventory summary surfaces must first speak truthful coverage before adding run continuity.
- User Story 3 (P2): Depends only on the foundational contract and existing canonical run detail infrastructure; it can be delivered after User Story 1 or in parallel with User Story 2, but is lower priority.
Within Each User Story
- Story tests should be written before or alongside implementation and should fail for the intended reason before the story is considered complete.
- Shared resolver or badge changes should land before surface refactors that consume them.
- Surface refactors should land before the focused story-level verification run.
Parallel Opportunities
T001andT002can run in parallel during Setup.T003,T004,T005, andT006can run in parallel during Foundational work.T009andT010can run in parallel for User Story 1.T011andT012can run in parallel for User Story 1 after the foundational resolver is ready.T016andT017can run in parallel for User Story 2.T018andT019can run in parallel for User Story 2 after basis-run continuity metadata is available.T021andT022can run in parallel for User Story 3.T023andT024can run in parallel for User Story 3.T026andT030can run in parallel during Polish.
Parallel Example: User Story 1
# Launch the inventory truth regressions together before changing summary surfaces:
Task: T009 tests/Feature/Filament/InventoryPagesTest.php and tests/Feature/Filament/InventoryItemResourceTest.php
Task: T010 tests/Feature/Filament/InventoryCoverageTableTest.php and tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php
# Split KPI and helper refactors once the shared resolver is ready:
Task: T011 app/Filament/Widgets/Inventory/InventoryKpiHeader.php
Task: T012 app/Support/Inventory/InventoryKpiBadges.php
Parallel Example: User Story 2
# Write the continuity and degradation assertions together before adding links:
Task: T016 tests/Feature/Filament/InventoryCoverageRunContinuityTest.php and tests/Feature/Filament/InventoryPagesTest.php
Task: T017 tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php and tests/Feature/Filament/InventoryCoverageRunContinuityTest.php
# Split page and widget continuity work after the tests exist:
Task: T018 app/Filament/Pages/InventoryCoverage.php and resources/views/filament/pages/inventory-coverage.blade.php
Task: T019 app/Filament/Widgets/Inventory/InventoryKpiHeader.php and app/Support/Inventory/TenantCoverageTruthResolver.php
Parallel Example: User Story 3
# Lock the run-detail expectations and payload assertions together:
Task: T021 tests/Feature/Operations/TenantlessOperationRunViewerTest.php and tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
Task: T022 tests/Feature/Inventory/InventorySyncServiceTest.php and tests/Feature/Inventory/RunInventorySyncJobTest.php
# Build the section view and enterprise-detail wiring in parallel:
Task: T023 app/Filament/Resources/OperationRunResource.php
Task: T024 resources/views/filament/infolists/entries/inventory-coverage-truth.blade.php
Implementation Strategy
MVP First (User Story 1 Only)
- Complete Phase 1: Setup.
- Complete Phase 2: Foundational.
- Complete Phase 3: User Story 1.
- Validate the inventory items list and coverage page with the User Story 1-focused subset of
specs/177-inventory-coverage-truth/quickstart.md.
Incremental Delivery
- Finish Setup and Foundational work.
- Deliver User Story 1 and validate truthful tenant coverage at a glance.
- Deliver User Story 2 and validate run continuity plus safe degradation.
- Deliver User Story 3 and validate human-readable inventory-sync run detail.
- Finish with formatting, the focused Sail pack, and the no-new-persistence review.
Parallel Team Strategy
- One developer can complete Phase 1 and the model or resolver side of Phase 2 while another prepares the badge and feature regressions.
- After Phase 2, one developer can take User Story 1 while another prepares User Story 3 run-detail tests.
- After User Story 1 stabilizes, one developer can handle User Story 2 continuity while another completes User Story 3 UI wiring.
- Rejoin for Phase 6 formatting and verification.
Notes
- Every task follows the required checklist format: checkbox, task ID, optional parallel marker, required story label for story phases, and exact file paths.
- The suggested MVP scope is Phase 1 through Phase 3 only.
- No task in this plan introduces new persistence, a new Graph contract, a new Filament panel or provider registration change, or a new destructive action.