TenantAtlas/specs/163-baseline-subject-resolution/tasks.md

# Tasks: Baseline Subject Resolution and Evidence Gap Semantics Foundation

**Input**: Design documents from `/specs/163-baseline-subject-resolution/`
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/openapi.yaml`, `quickstart.md`

**Tests**: Tests are REQUIRED for this feature because it changes runtime behavior in compare, capture, and operator surfaces.
**Organization**: Tasks are grouped by user story so each story can be implemented and verified independently where practical.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Create shared test support and optional cleanup-command scaffolding needed by later story work.

- [X] T001 Scaffold the development-only cleanup command entry point in `app/Console/Commands/PurgeLegacyBaselineGapRuns.php`
- [X] T002 [P] Create shared compare and capture fixture builders for subject-resolution scenarios in `tests/Feature/Baselines/Support/BaselineSubjectResolutionFixtures.php`
- [X] T003 [P] Create shared assertion helpers for structured gap payloads in `tests/Feature/Baselines/Support/AssertsStructuredBaselineGaps.php`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Build the shared subject-resolution contract and runtime capability foundation before user story work begins.

**⚠️ CRITICAL**: No user story work should begin until this phase is complete.

- [X] T004 [P] Create subject-resolution enums in `app/Support/Baselines/SubjectClass.php`, `app/Support/Baselines/ResolutionPath.php`, `app/Support/Baselines/ResolutionOutcome.php`, and `app/Support/Baselines/OperatorActionCategory.php`
- [X] T005 [P] Create subject-resolution value objects in `app/Support/Baselines/SubjectDescriptor.php`, `app/Support/Baselines/ResolutionOutcomeRecord.php`, and `app/Support/Baselines/SupportCapabilityRecord.php`
- [X] T006 Implement the shared resolver and capability services in `app/Support/Baselines/SubjectResolver.php` and `app/Support/Baselines/BaselineSupportCapabilityGuard.php`
- [X] T007 Update metadata derivation for subject classes and support capability in `app/Support/Inventory/InventoryPolicyTypeMeta.php` and `config/tenantpilot.php`
- [X] T008 Update shared scope and service wiring for the new resolver contract in `app/Support/Baselines/BaselineScope.php`, `app/Services/Baselines/BaselineCompareService.php`, and `app/Services/Baselines/BaselineCaptureService.php`
- [X] T009 [P] Add foundational unit coverage for enums, metadata rules, and resolver behavior in `tests/Unit/Support/Baselines/SubjectResolverTest.php` and `tests/Unit/Support/Inventory/InventoryPolicyTypeMetaResolutionContractTest.php`

**Checkpoint**: Subject-resolution foundation and runtime capability guard are ready.

---

## Phase 3: User Story 1 - Distinguish structural from missing-local-data gaps (Priority: P1) 🎯 MVP

**Goal**: Ensure compare and capture can tell structural inventory or foundation limitations apart from missing local policy or inventory records.

**Independent Test**: Run compare and capture flows that include both policy-backed and foundation-backed subjects and verify the resulting gaps separate structural resolver limits from missing local records without relying on raw diagnostics.

### Tests for User Story 1

- [X] T010 [P] [US1] Add compare gap classification and ambiguity-preservation coverage for structural versus missing-local-data cases in `tests/Feature/Baselines/BaselineCompareGapClassificationTest.php`
- [X] T011 [P] [US1] Add capture gap classification coverage for policy-backed and foundation-backed subjects in `tests/Feature/Baselines/BaselineCaptureGapClassificationTest.php`
- [X] T012 [P] [US1] Add deterministic replay coverage for unchanged compare and capture inputs in `tests/Feature/Baselines/BaselineResolutionDeterminismTest.php`

### Implementation for User Story 1

- [X] T013 [US1] Refactor subject lookup and outcome emission in `app/Services/Baselines/BaselineContentCapturePhase.php` to use `SubjectResolver` instead of raw policy-only lookup
- [X] T014 [US1] Update compare-side subject persistence and deterministic subject keys in `app/Jobs/CompareBaselineToTenantJob.php` and `app/Support/Baselines/BaselineSubjectKey.php`
- [X] T015 [US1] Replace broad gap taxonomy handling with structured structural versus operational semantics while preserving ambiguity-related reason families in `app/Support/Baselines/BaselineCompareReasonCode.php` and `app/Support/Baselines/BaselineCompareEvidenceGapDetails.php`
- [X] T016 [US1] Update compare summary aggregation for structural, operational, and transient counts in `app/Support/Baselines/BaselineCompareStats.php`

**Checkpoint**: User Story 1 is functional and testable on its own.

---

## Phase 4: User Story 2 - Keep support promises truthful at runtime (Priority: P2)

**Goal**: Prevent baseline-supported types from entering compare or capture on a resolver path that cannot classify them truthfully.

**Independent Test**: Evaluate supported subject types against runtime resolver capability and verify each type either enters execution with a valid path and meaningful outcome set or is limited or excluded before misleading gaps are produced.

### Tests for User Story 2

- [X] T017 [P] [US2] Add feature coverage for runtime support-capability guard decisions in `tests/Feature/Baselines/BaselineSupportCapabilityGuardTest.php`
- [X] T018 [P] [US2] Add unit coverage for subject-class and support-mode derivation in `tests/Unit/Support/Inventory/InventoryPolicyTypeMetaBaselineSupportTest.php`

### Implementation for User Story 2

- [X] T019 [US2] Extend baseline support metadata with subject-class and capability truth in `config/tenantpilot.php` and `app/Support/Inventory/InventoryPolicyTypeMeta.php`
- [X] T020 [US2] Enforce capability guard decisions before compare execution in `app/Support/Baselines/BaselineScope.php` and `app/Services/Baselines/BaselineCompareService.php`
- [X] T021 [US2] Enforce the same capability guard before capture execution in `app/Services/Baselines/BaselineCaptureService.php` and `app/Jobs/CaptureBaselineSnapshotJob.php`
- [X] T022 [US2] Persist operator-safe capability and support outcomes in `app/Jobs/CompareBaselineToTenantJob.php` and `app/Services/Baselines/BaselineContentCapturePhase.php`

**Checkpoint**: User Story 2 is functional and testable on its own.

---

## Phase 5: User Story 3 - Replace dev-era broad reasons with the new contract cleanly (Priority: P3)

**Goal**: Move existing operator surfaces, tests, and development fixtures to the new structured gap contract without preserving the old broad reason shape in runtime code.

**Independent Test**: Remove or regenerate old development runs, create a new run under the updated contract, and verify the existing surfaces expose subject class, resolution meaning, and action category without fallback to the old broad reason contract.

### Tests for User Story 3

- [X] T023 [P] [US3] Add canonical run-detail regression coverage for structured gap semantics in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
- [X] T024 [P] [US3] Add tenant landing regression coverage for structured gap semantics in `tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php`
- [X] T025 [P] [US3] Add DB-only render regression coverage for gap surfaces in `tests/Feature/Filament/BaselineGapSurfacesDbOnlyRenderTest.php`
- [X] T026 [P] [US3] Add development cleanup and regeneration coverage for stale run payloads in `tests/Feature/Baselines/BaselineGapContractCleanupTest.php`

### Implementation for User Story 3

- [X] T027 [US3] Update run-detail semantics for structured gap records in `app/Filament/Resources/OperationRunResource.php` and `resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php`
- [X] T028 [US3] Update tenant landing semantics for structured gap records in `app/Filament/Pages/BaselineCompareLanding.php` and `resources/views/filament/pages/baseline-compare-landing.blade.php`
- [X] T029 [US3] Implement the cleanup command logic and run-selection criteria in `app/Console/Commands/PurgeLegacyBaselineGapRuns.php` and `app/Models/OperationRun.php`
- [X] T030 [US3] Remove broad-reason dev fixture usage and regenerate structured payload fixtures in `tests/Feature/Baselines/Support/BaselineSubjectResolutionFixtures.php`, `tests/Feature/Baselines`, and `tests/Feature/Filament`
- [X] T031 [US3] Finalize projection states and empty-state semantics for development cleanup in `app/Support/Baselines/BaselineCompareEvidenceGapDetails.php` and `app/Support/Baselines/BaselineCompareStats.php`

**Checkpoint**: User Story 3 is functional and testable on its own.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final consistency, documentation alignment, and focused validation across all stories.

- [X] T032 [P] Document the implemented cleanup command and final contract examples in `specs/163-baseline-subject-resolution/contracts/openapi.yaml`, `specs/163-baseline-subject-resolution/data-model.md`, and `specs/163-baseline-subject-resolution/quickstart.md`
- [X] T033 Run the focused validation pack and the cleanup command flow documented in `specs/163-baseline-subject-resolution/quickstart.md`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: T002 and T003 start immediately; T001 is optional early scaffolding for US3 and does not block semantic work.
- **Foundational (Phase 2)**: Depends on shared support where needed for tests, but is not blocked by T001 cleanup-command scaffolding; blocks all user stories once started.
- **User Story 1 (Phase 3)**: Depends on Foundational completion; delivers the MVP semantic contract.
- **User Story 2 (Phase 4)**: Depends on Foundational completion; can proceed after Phase 2 and integrate with US1 outputs.
- **User Story 3 (Phase 5)**: Depends on US1 structured gap contract and benefits from US2 capability guard outputs.
- **Polish (Phase 6)**: Depends on all desired user stories being complete.

### User Story Dependencies

- **US1 (P1)**: Starts after Phase 2; no dependency on later stories.
- **US2 (P2)**: Starts after Phase 2; shares foundational components but remains independently testable.
- **US3 (P3)**: Starts after US1 because surface adoption depends on the new structured gap payload; it consumes T001 if the cleanup command scaffold was created early.

### Within Each User Story

- Tests must be written and fail before the implementation tasks they cover.
- Resolver or metadata changes must land before surface or projection updates that consume them.
- Story-level verification must pass before moving to the next dependent story.

### Parallel Opportunities

- T002 and T003 can run in parallel.
- T004 and T005 can run in parallel.
- T009 can run in parallel with the end of T006 through T008 once the foundational interfaces stabilize.
- T010, T011, and T012 can run in parallel.
- T017 and T018 can run in parallel.
- T023, T024, T025, and T026 can run in parallel.
- T032 can run in parallel with final validation prep once implementation stabilizes.

---

## Parallel Example: User Story 1

```bash
# Launch the independent US1 tests together:
Task: "Add compare gap classification coverage in tests/Feature/Baselines/BaselineCompareGapClassificationTest.php"
Task: "Add capture gap classification coverage in tests/Feature/Baselines/BaselineCaptureGapClassificationTest.php"
```

## Parallel Example: User Story 2

```bash
# Launch the independent US2 tests together:
Task: "Add feature coverage for runtime support-capability guard decisions in tests/Feature/Baselines/BaselineSupportCapabilityGuardTest.php"
Task: "Add unit coverage for subject-class and support-mode derivation in tests/Unit/Support/Inventory/InventoryPolicyTypeMetaBaselineSupportTest.php"
```

## Parallel Example: User Story 3

```bash
# Launch the independent US3 regression tests together:
Task: "Add canonical run-detail regression coverage in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php"
Task: "Add tenant landing regression coverage in tests/Feature/Filament/BaselineCompareLandingAdminTenantParityTest.php"
Task: "Add DB-only render regression coverage in tests/Feature/Filament/BaselineGapSurfacesDbOnlyRenderTest.php"
Task: "Add development cleanup and regeneration coverage in tests/Feature/Baselines/BaselineGapContractCleanupTest.php"
```

---

## Implementation Strategy

### MVP First

Deliver Phase 3 (US1) first after the foundational phase. That provides the core semantic win: structural versus missing-local-data gaps become distinguishable in persisted run context.

### Incremental Delivery

1. Finish Setup and Foundational phases.
2. Deliver US1 to establish the new structured resolution and gap contract.
3. Deliver US2 to stop support metadata from overpromising runtime capability.
4. Deliver US3 to move existing surfaces and development fixtures fully onto the new contract.
5. Finish with Polish to align the design docs and validation steps with the implemented behavior.

### Suggested MVP Scope

US1 only is the smallest valuable slice. It fixes the primary trust problem and creates the contract that US2 and US3 build on.