ahmido
c17255f854
## 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
88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
# Quickstart: Baseline Subject Resolution and Evidence Gap Semantics Foundation
|
|
|
|
## Prerequisites
|
|
|
|
1. Start the local stack.
|
|
|
|
```bash
|
|
vendor/bin/sail up -d
|
|
```
|
|
|
|
2. Clear stale cached state if you have been switching branches or configs.
|
|
|
|
```bash
|
|
vendor/bin/sail artisan optimize:clear
|
|
```
|
|
|
|
## Focused Verification Pack
|
|
|
|
Run the minimum targeted regression pack for this foundation:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
vendor/bin/sail artisan tenantpilot:baselines:purge-legacy-gap-runs
|
|
```
|
|
|
|
Apply deletion:
|
|
|
|
```bash
|
|
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.
|