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

- [X] T001 [P] Create the derived tenant coverage truth scaffolding in `app/Support/Inventory/TenantCoverageTruth.php` and `app/Support/Inventory/TenantCoverageTruthResolver.php`
- [X] T002 [P] Create the focused regression scaffolding in `tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php`, `tests/Unit/Badges/InventoryCoverageStateBadgesTest.php`, and `tests/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.

- [X] T003 [P] Extend basis-run and mixed-outcome payload coverage assertions in `tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php` and `tests/Feature/Inventory/RunInventorySyncJobTest.php`
- [X] T004 [P] Add centralized inventory coverage badge mapping assertions in `tests/Unit/Badges/BadgeCatalogTest.php` and `tests/Unit/Badges/InventoryCoverageStateBadgesTest.php`
- [X] T005 [P] Implement the latest completed coverage-bearing inventory-sync selection helper in `app/Models/OperationRun.php`
- [X] T006 [P] Implement the derived runtime fields and row contract in `app/Support/Inventory/TenantCoverageTruth.php`
- [X] T007 Implement tenant coverage resolution, item-count joins, follow-up classification, and basis-run metadata in `app/Support/Inventory/TenantCoverageTruthResolver.php`
- [X] T008 Implement the centralized inventory coverage state badge domain and mapper in `app/Support/Badges/BadgeDomain.php`, `app/Support/Badges/BadgeCatalog.php`, and `app/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

- [X] T009 [P] [US1] Rewrite summary-surface expectations for truthful count-based coverage on the inventory items list in `tests/Feature/Filament/InventoryPagesTest.php` and `tests/Feature/Filament/InventoryItemResourceTest.php`
- [X] 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 in `tests/Feature/Filament/InventoryCoverageTableTest.php` and `tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php`

### Implementation for User Story 1

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`, and `tests/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

- [X] 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.php` and `tests/Feature/Filament/InventoryCoverageRunContinuityTest.php`
- [X] 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.php` and `tests/Feature/Filament/InventoryCoverageRunContinuityTest.php`

### Implementation for User Story 2

- [X] 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.php` and `resources/views/filament/pages/inventory-coverage.blade.php`
- [X] T019 [P] [US2] Surface basis-run continuity and safe link rendering in the inventory KPI summary using `app/Filament/Widgets/Inventory/InventoryKpiHeader.php` and `app/Support/Inventory/TenantCoverageTruthResolver.php`
- [X] T020 [US2] Run the focused continuity pack in `tests/Feature/Filament/InventoryCoverageRunContinuityTest.php`, `tests/Feature/Filament/InventoryPagesTest.php`, and `tests/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

- [X] T021 [P] [US3] Add human-readable inventory-sync section assertions, including provider or permission follow-up guidance, in `tests/Feature/Operations/TenantlessOperationRunViewerTest.php` and `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
- [X] T022 [P] [US3] Extend mixed-outcome payload expectations for per-type coverage rows in `tests/Feature/Inventory/InventorySyncServiceTest.php` and `tests/Feature/Inventory/RunInventorySyncJobTest.php`

### Implementation for User Story 3

- [X] T023 [US3] Add the inventory-sync per-type coverage enterprise-detail section with explicit next-step guidance in `app/Filament/Resources/OperationRunResource.php`
- [X] 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`
- [X] 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`, and `tests/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.

- [X] 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`, and `app/Filament/Resources/OperationRunResource.php`
- [X] T027 Run `vendor/bin/sail bin pint --dirty --format agent` for touched files under `app/`, `resources/views/`, and `tests/`
- [X] T028 Run the focused Sail verification pack from `specs/177-inventory-coverage-truth/quickstart.md` against `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`
- [X] 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`, and `specs/177-inventory-coverage-truth/plan.md` against the final diff
- [X] T030 [P] Review `app/Filament/Resources/InventoryItemResource/Pages/ListInventoryItems.php` and `app/Filament/Pages/InventoryCoverage.php` against `docs/product/standards/list-surface-review-checklist.md` before 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

- `T001` and `T002` can run in parallel during Setup.
- `T003`, `T004`, `T005`, and `T006` can run in parallel during Foundational work.
- `T009` and `T010` can run in parallel for User Story 1.
- `T011` and `T012` can run in parallel for User Story 1 after the foundational resolver is ready.
- `T016` and `T017` can run in parallel for User Story 2.
- `T018` and `T019` can run in parallel for User Story 2 after basis-run continuity metadata is available.
- `T021` and `T022` can run in parallel for User Story 3.
- `T023` and `T024` can run in parallel for User Story 3.
- `T026` and `T030` can run in parallel during Polish.

---

## Parallel Example: User Story 1

```bash
# 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

```bash
# 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

```bash
# 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)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. 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

1. Finish Setup and Foundational work.
2. Deliver User Story 1 and validate truthful tenant coverage at a glance.
3. Deliver User Story 2 and validate run continuity plus safe degradation.
4. Deliver User Story 3 and validate human-readable inventory-sync run detail.
5. Finish with formatting, the focused Sail pack, and the no-new-persistence review.

### Parallel Team Strategy

1. One developer can complete Phase 1 and the model or resolver side of Phase 2 while another prepares the badge and feature regressions.
2. After Phase 2, one developer can take User Story 1 while another prepares User Story 3 run-detail tests.
3. After User Story 1 stabilizes, one developer can handle User Story 2 continuity while another completes User Story 3 UI wiring.
4. 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.
