ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c17255f854
TenantAtlas/specs/163-baseline-subject-resolution/quickstart.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

3.4 KiB
Raw Blame History

Quickstart: Baseline Subject Resolution and Evidence Gap Semantics Foundation

Prerequisites

  1. Start the local stack.
vendor/bin/sail up -d
  1. Clear stale cached state if you have been switching branches or configs.
vendor/bin/sail artisan optimize:clear

Focused Verification Pack

Run the minimum targeted regression pack for this foundation:

vendor/bin/sail artisan test --compact tests/Unit/Support/Baselines tests/Feature/Baselines tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php

If the implementation introduces dedicated new files, narrow the pack further to the new subject-resolution, compare, capture, and development-cleanup tests.

Format touched files before final review:

vendor/bin/sail bin pint --dirty --format agent

Manual Verification Flow

  1. Ensure a tenant has fresh inventory data for at least one policy-backed type and one baseline-supported foundation type.
  2. Trigger or locate a baseline capture run and a baseline compare run for that tenant and profile.
  3. Open the canonical run detail at /admin/operations/{run}.
  4. Confirm the page distinguishes:
    • structural cases
    • operational or missing-local-data cases
    • transient retryable cases
  5. Confirm inventory-only foundation subjects no longer surface as a new generic policy_not_found gap.
  6. Confirm policy-backed missing-local-record cases still surface as an operational missing-record outcome.

Development Cleanup Verification

  1. Remove or invalidate old local compare or capture runs that still contain broad legacy gap reasons. Dry-run:
vendor/bin/sail artisan tenantpilot:baselines:purge-legacy-gap-runs

Apply deletion:

vendor/bin/sail artisan tenantpilot:baselines:purge-legacy-gap-runs --force
  1. Regenerate fresh runs under the new structured contract.
  2. Confirm the product and targeted tests no longer depend on the broad legacy shape being preserved in runtime code.

Runtime Capability Guard Verification

  1. Configure or seed one baseline-supported type whose runtime resolver path is valid.
  2. Configure or seed one type whose support claim would be structurally invalid without the new guard.
  3. Start compare or capture preparation.
  4. Confirm the valid type enters execution with a truthful path.
  5. Confirm the invalid type is limited, excluded, or explicitly classified as invalid support configuration before misleading gap output is produced.

Determinism Verification

  1. Run the same compare scenario twice against unchanged tenant-local data.
  2. Confirm both runs persist the same subject_class, resolution_outcome, and operator_action_category values for the same subject.

Render-Safety Verification

  1. Bind the fail-hard Graph client in affected UI tests.
  2. Verify canonical run detail and tenant baseline compare landing render without triggering Graph calls.
  3. Verify the richer semantics are derived solely from persisted run context and local metadata.

Deployment Notes

  • No new panel provider is required; Laravel 12 continues to register providers in bootstrap/providers.php.
  • Filament remains on Livewire v4-compatible patterns and does not require view publishing.
  • No new shared or panel assets are required, so this slice adds no new filament:assets deployment step beyond the existing deployment baseline.
  • Existing compare and capture operations remain on current OperationRun types and notification behavior.