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

Quickstart: Baseline Subject Resolution and Evidence Gap Semantics Foundation

Prerequisites

1. Start the local stack.

vendor/bin/sail up -d

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

2. Regenerate fresh runs under the new structured contract.
3. 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.