ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c17255f854
TenantAtlas/specs/163-baseline-subject-resolution/tasks.md
ahmido c17255f854 feat: implement baseline subject resolution semantics (#193) 
## Summary
- add the structured subject-resolution foundation for baseline compare and baseline capture, including capability guards, subject descriptors, resolution outcomes, and operator action categories
- persist structured evidence-gap subject records and update compare/capture surfaces, landing projections, and cleanup tooling to use the new contract
- add Spec 163 artifacts and focused Pest coverage for classification, determinism, cleanup, and DB-only rendering

## Validation
- `vendor/bin/sail bin pint --dirty --format agent`
- `vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Feature/Baselines tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`

## Notes
- verified locally that a fresh post-restart baseline compare run now writes structured `baseline_compare.evidence_gaps.subjects` records instead of the legacy broad payload shape
- excluded the separate `docs/product/spec-candidates.md` worktree change from this branch commit and PR

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #193
2026-03-25 12:40:45 +00:00

13 KiB
Raw Blame History

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.

  • T001 Scaffold the development-only cleanup command entry point in app/Console/Commands/PurgeLegacyBaselineGapRuns.php
  • T002 [P] Create shared compare and capture fixture builders for subject-resolution scenarios in tests/Feature/Baselines/Support/BaselineSubjectResolutionFixtures.php
  • 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.

  • 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
  • T005 [P] Create subject-resolution value objects in app/Support/Baselines/SubjectDescriptor.php, app/Support/Baselines/ResolutionOutcomeRecord.php, and app/Support/Baselines/SupportCapabilityRecord.php
  • T006 Implement the shared resolver and capability services in app/Support/Baselines/SubjectResolver.php and app/Support/Baselines/BaselineSupportCapabilityGuard.php
  • T007 Update metadata derivation for subject classes and support capability in app/Support/Inventory/InventoryPolicyTypeMeta.php and config/tenantpilot.php
  • 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
  • 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

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

Implementation for User Story 1

  • T013 [US1] Refactor subject lookup and outcome emission in app/Services/Baselines/BaselineContentCapturePhase.php to use SubjectResolver instead of raw policy-only lookup
  • T014 [US1] Update compare-side subject persistence and deterministic subject keys in app/Jobs/CompareBaselineToTenantJob.php and app/Support/Baselines/BaselineSubjectKey.php
  • 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
  • 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

  • T017 [P] [US2] Add feature coverage for runtime support-capability guard decisions in tests/Feature/Baselines/BaselineSupportCapabilityGuardTest.php
  • 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

  • T019 [US2] Extend baseline support metadata with subject-class and capability truth in config/tenantpilot.php and app/Support/Inventory/InventoryPolicyTypeMeta.php
  • T020 [US2] Enforce capability guard decisions before compare execution in app/Support/Baselines/BaselineScope.php and app/Services/Baselines/BaselineCompareService.php
  • T021 [US2] Enforce the same capability guard before capture execution in app/Services/Baselines/BaselineCaptureService.php and app/Jobs/CaptureBaselineSnapshotJob.php
  • 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

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

Implementation for User Story 3

  • 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
  • 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
  • T029 [US3] Implement the cleanup command logic and run-selection criteria in app/Console/Commands/PurgeLegacyBaselineGapRuns.php and app/Models/OperationRun.php
  • 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
  • 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.

  • 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
  • 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

# 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

# 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

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