195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
# 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.
|