TenantAtlas/specs/235-baseline-capture-truth/quickstart.md

Quickstart: Baseline Capture Truthful Outcomes and Upstream Guardrails

Purpose

Validate that baseline capture no longer reports green success when the upstream inventory basis is not credible or when the capture finds zero in-scope subjects, confirm that the previous consumable baseline remains the effective compare anchor until a new consumable snapshot exists, and verify that Monitoring, audit prose, and terminal notification copy stay aligned to the same dominant truth.

Preconditions

1. Sail services are running.
2. The workspace has a tenant, baseline profile, and inventory fixtures available for the targeted tests.
3. Baseline resources remain Filament v5 / Livewire v4 surfaces; no extra asset build is expected beyond standard PHP/test tooling.

Validation Flow

1. Start-surface preflight blocks non-credible inventory truth

Goal: Known upstream problems are rejected before enqueue and use the shared reason-code family.

Check:

• No latest relevant inventory sync exists.
• Latest relevant inventory sync is blocked or failed.
• Latest relevant inventory sync exists but does not provide usable in-scope coverage.

Expected result:

• Capture does not enqueue a run.
• The start surface shows the shared translated baseline-capture reason.
• No success wording appears.

2. Runtime recheck blocks prerequisite drift after enqueue

Goal: If the latest relevant inventory state changes after page load or after enqueue, the queued run still resolves truthfully.

Check:

• Enqueue capture with a credible latest inventory basis.
• Change the latest relevant inventory run to a blocked/failed/unusable-coverage/non-credible state before the job evaluates subjects.

Expected result:

• The run ends as completed + blocked.
• Monitoring and run-detail explanation lead with the upstream inventory reason.
• No snapshot becomes the current consumable baseline.

3. Consumable capture still produces succeeded baseline truth

Goal: A clean capture with at least one resolved in-scope subject still succeeds and advances effective baseline truth.

Check:

• Use a credible latest inventory run whose effective in-scope subject count is greater than zero.
• Ensure the capture completes without warning conditions that would intentionally downgrade the run to partially_succeeded.

Expected result:

• The run ends as completed + succeeded.
• A consumable snapshot is produced or reused consistently with the current truth contract.
• BaselineProfile.active_snapshot_id remains anchored to the consumable current snapshot after the run, whether that required a new pointer update or reuse of the already-current consumable snapshot.
• Run context and audit summary preserve the same metadata contract for success, including the eligibility decision, upstream inventory reference, and whether current baseline truth changed.

4. Zero-subject capture produces no-data truth, not a green refresh

Goal: A capture with zero in-scope subjects remains visible but cannot silently refresh current baseline truth.

Check:

• Use a credible latest inventory run whose effective in-scope subject count is zero.

Expected result:

• The run ends as completed + partially_succeeded.
• The dominant reason is the zero-subject/no-data capture code.
• Any retained snapshot artifact is non-consumable.
• BaselineProfile.active_snapshot_id remains on the previous consumable snapshot.

5. Compare readiness stays anchored to consumable baseline truth

Goal: Compare surfaces must reflect whether a usable baseline actually exists, not whether a capture was merely attempted.

Check:

• Trigger a blocked capture after a previously successful baseline exists.
• Trigger a zero-subject capture after a previously successful baseline exists.
• Trigger a blocked or zero-subject capture when no previous consumable baseline exists.

Expected result:

• With a previous consumable baseline, compare remains available against that prior truth and explains that the latest capture did not refresh baseline truth.
• The profile-level compare affordance reflects the same truthful availability state and guidance as compare landing.
• Without any consumable baseline, compare remains unavailable and explains why.

6. Monitoring summary stays explanation-first

Goal: Operators should immediately see whether the run was blocked upstream or completed with no usable baseline.

Check:

• Open the run detail for a blocked latest-inventory capture.
• Open the run detail for a failed latest-inventory capture.
• Open the run detail for a zero-subject capture.

Expected result:

• The summary headline differentiates blocked upstream prerequisites, failed latest inventory, and no-data capture.
• Raw numeric counts remain secondary diagnostics.

7. Audit prose and terminal notification stay aligned with run truth

Goal: Interactive runs, initiator-null runs, and audit coverage must preserve the same dominant baseline-capture reason without introducing notification drift.

Check:

• Complete an interactive blocked baseline-capture run and inspect the terminal OperationRunCompleted payload.
• Complete an interactive zero-subject baseline-capture run and inspect the terminal OperationRunCompleted payload.
• Complete an initiator-null or scheduled baseline-capture run with blocked or no-data truth.
• Inspect the governance audit coverage surface or assertions for the same runs.

Expected result:

• Interactive terminal notifications use the same dominant blocked or no-data reason vocabulary as Monitoring.
• Initiator-null runs emit no terminal DB notification while preserving Monitoring and audit truth.
• Audit prose records the same dominant cause and whether current baseline truth changed.

Commands

Run the narrowest proof set from repository root:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCaptureTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php tests/Feature/Monitoring/AuditCoverageGovernanceTest.php tests/Feature/Notifications/OperationRunNotificationTest.php tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php

Run the legacy edge check only if implementation touches historical empty-snapshot classification:

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineSnapshotBackfillTest.php

Manual Smoke Focus

If a manual UI check is needed after automated proof:

1. Open a baseline profile detail page and verify the capture header action shows the translated upstream block when inventory truth is not credible.
2. Open compare landing after a zero-subject capture and verify it explains whether the prior consumable baseline still anchors compare availability.
3. Open the Monitoring run detail and verify the headline distinguishes upstream block from no-data capture before showing counts.
4. Verify an interactive run shows aligned terminal notification wording, while an initiator-null run leaves notification delivery suppressed and keeps Monitoring as the audit surface.

Close-out Record

Record the feature close-out outcome here and mirror it into the active PR description:

1. Guardrail status for the changed native Filament surfaces.
2. Whether standard-native-filament and monitoring-state-page coverage both ran successfully.
3. Whether T022 stayed document-in-feature or required a follow-up for legacy empty-snapshot behavior.

Recorded Outcome

• Guardrail: pass
• standard-native-filament: pass
• monitoring-state-page: pass
• T022: implemented in feature; legacy empty complete snapshots are now backfilled as incomplete no-data captures with baseline.capture.zero_subjects