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

Tasks: Baseline Capture Truthful Outcomes and Upstream Guardrails

Input: Design documents from /specs/235-baseline-capture-truth/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md

Tests: Required. This feature changes runtime behavior and operator truth on an existing queued workflow, so Pest coverage must be added or updated in apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php, apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php, apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php, apps/platform/tests/Feature/Monitoring/AuditCoverageGovernanceTest.php, apps/platform/tests/Feature/Notifications/OperationRunNotificationTest.php, and apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php. apps/platform/tests/Feature/Baselines/BaselineSnapshotBackfillTest.php remains conditional and is only updated if implementation proves historical empty complete snapshots still affect current runtime truth. Operations: Existing baseline_capture OperationRun remains canonical. Tasks below explicitly preserve the Ops-UX 3-surface feedback contract, keep OperationRun.status and OperationRun.outcome service-owned through apps/platform/app/Services/OperationRunService.php, keep summary_counts flat and numeric-only, avoid any queued/running DB notification drift, and preserve initiator-null Monitoring-only behavior for scheduled/system runs. RBAC: No new authorization model is introduced, but the touched admin /admin, tenant-context /admin/t/{tenant}/baseline-compare, and Monitoring /admin/operations/{run} surfaces must preserve current capability enforcement and 404 versus 403 semantics through existing helpers and regression coverage in apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php. UI Naming: Operator-facing copy must remain baseline-domain specific and centralized through apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php, apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, and apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php. No task may introduce page-local copy branches for blocked or no-data baseline capture truth. Cross-Cutting Shared Pattern Reuse: This is a shared interaction slice. Extend apps/platform/app/Support/Baselines/BaselineReasonCodes.php, apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php, apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, and apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php before considering any local UI branching. UI / Surface Guardrails: review-mandatory slice. Surfaces stay native Filament plus shared baseline/Ops UX primitives. Required coverage is standard-native-filament plus monitoring-state-page; no exception path is planned. Filament UI Action Surfaces: No new Resource, Page, or destructive action is introduced. apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php, apps/platform/app/Filament/Pages/BaselineCompareLanding.php, and apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php keep their current action topology, existing confirmation-gated capture actions, and current global-search-disabled posture. Badges: No new badge domain or outcome family is introduced. Existing blocked and partially_succeeded semantics remain centralized through current outcome and Ops UX renderers; avoid ad-hoc badge/status mappings in Filament.

Organization: Tasks are grouped by user story so each slice stays independently testable. Recommended delivery order is US1 then US2 then US3, because zero-subject and Monitoring truth depend on the shared reason-code and run-context groundwork from the false-green capture fix.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared surface test profile or standard-native-filament relief is explicit.
• Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Phase 1: Setup (Shared Anchors)

Purpose: Lock the implementation anchors and proving commands before touching runtime truth.

• T001 [P] Verify the feature anchor inventory across apps/platform/app/Services/Baselines/BaselineCaptureService.php, apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php, apps/platform/app/Support/Baselines/BaselineReasonCodes.php, apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php, apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php, apps/platform/app/Filament/Pages/BaselineCompareLanding.php, and apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php
• T002 [P] Verify the narrow proving commands, guardrail class, and validation-lane expectations in specs/235-baseline-capture-truth/plan.md and specs/235-baseline-capture-truth/quickstart.md

Checkpoint: Runtime anchors and proof commands are locked before implementation begins.

---

Phase 2: Foundational (Blocking Truth Boundaries)

Purpose: Audit the shared boundaries that every story depends on so the implementation does not widen or drift into local fixes.

CRITICAL: No user story work should begin until this phase is complete.

• T003 [P] Audit latest relevant inventory lookup, terminal-outcome interpretation, and no-stale-fallback boundaries in apps/platform/app/Services/Baselines/BaselineCaptureService.php and apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php
• T004 [P] Audit current baseline promotion and consumability boundaries in apps/platform/app/Models/BaselineProfile.php, apps/platform/app/Models/BaselineSnapshot.php, and apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php
• T005 [P] Audit shared explanation and copy consumers across apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php, apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php, apps/platform/app/Filament/Pages/BaselineCompareLanding.php, and apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php
• T006 [P] Audit existing baseline_capture run-truth enforcement in apps/platform/app/Services/OperationRunService.php, apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php, apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php, and apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php so service-owned transitions, numeric summary_counts, and 404 versus 403 expectations are explicit before story work begins

Checkpoint: The shared inventory, artifact-truth, Ops-UX, and auth boundaries are explicit and safe to extend.

---

Phase 3: User Story 1 - Block False-Green Capture Starts (Priority: P1) 🎯 MVP

Goal: Prevent baseline capture from reporting success when the latest relevant inventory basis is missing, blocked, failed, or otherwise non-credible.

Independent Test: Seed no inventory, blocked latest inventory, failed latest inventory, unusable coverage, and after-enqueue drift scenarios, then prove capture start or execution never lands on succeeded and never advances effective baseline truth.

Tests for User Story 1

• T007 [P] [US1] Expand apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php for no inventory, blocked latest inventory, failed latest inventory, unusable coverage, after-enqueue prerequisite drift, older-success-does-not-fallback, and clean consumable-success scenarios including the success-path run-context and audit metadata contract
• T008 [P] [US1] Expand apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php for shared preflight blocking copy and preserved confirmation-gated capture action topology on Capture baseline and Capture baseline (full content) actions
• T009 [P] [US1] Expand apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php to preserve the authorized happy-path access proof plus 404 versus 403 semantics on the profile capture explanation path and related Monitoring/detail surfaces touched by blocked prerequisite truth

Implementation for User Story 1

• T010 [P] [US1] Extend apps/platform/app/Support/Baselines/BaselineReasonCodes.php with deterministic capture-prerequisite reason codes for missing inventory, blocked inventory, failed inventory, unusable coverage, and baseline.capture.zero_subjects
• T011 [P] [US1] Extend apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php with centralized operator-safe wording and next steps for Run tenant sync first, Latest inventory sync failed, Latest inventory sync was blocked, unusable-coverage outcomes, and No subjects were in scope
• T012 [US1] Implement latest relevant inventory eligibility preflight in apps/platform/app/Services/Baselines/BaselineCaptureService.php so known non-credible prerequisites short-circuit before OperationRun creation
• T013 [US1] Re-check latest relevant inventory inside apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php and resolve blocked terminal truth through apps/platform/app/Services/OperationRunService.php with numeric summary_counts, upstream inventory run reference, chosen eligibility decision, terminal reason code, current-baseline-change flag, and no queued/running DB-notification drift
• T014 [US1] Update apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php and any capture-result explanation consumers to use the shared translated prerequisite truth while preserving existing confirmation-gated action placement and capability enforcement

Checkpoint: User Story 1 is independently functional and capture can no longer false-green on non-credible latest inventory truth.

---

Phase 4: User Story 2 - Keep No-Data Captures Visible but Non-Authoritative (Priority: P2)

Goal: Let zero-subject captures remain auditable without allowing them to replace the current trustworthy baseline.

Independent Test: Capture against credible inventory that resolves zero in-scope subjects and verify partially_succeeded, no promotion of baseline truth, and clear no-data artifact messaging on affected surfaces.

Tests for User Story 2

• T015 [P] [US2] Expand apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php for zero-subject capture, preserved previous consumable snapshot, and absence of succeeded when no usable baseline was captured
• T016 [P] [US2] Expand apps/platform/tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php for no-data artifact messaging, current-versus-historical truth on profile and snapshot explanation surfaces, and profile-level compare affordance guidance after blocked or no-data capture outcomes
• T017 [P] [US2] Expand apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php for prior-trustworthy-baseline preservation versus no-current-baseline guidance after blocked latest-inventory and zero-subject capture outcomes

Implementation for User Story 2

• T018 [US2] Refactor zero-subject handling in apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php to short-circuit before existing consumable snapshot reuse or active_snapshot_id promotion, emit OperationRunOutcome::PartiallySucceeded, and record the no-data reason, baseline_capture.subjects_total, result.snapshot_lifecycle when present, plus effect on current baseline truth
• T019 [US2] Reuse existing lifecycle/usability semantics in apps/platform/app/Models/BaselineSnapshot.php and the finalization payloads from apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php so any zero-subject artifact stays non-consumable and stores no-data finalization metadata instead of a new lifecycle state
• T020 [US2] Preserve BaselineProfile::resolveCurrentConsumableSnapshot() behavior in apps/platform/app/Models/BaselineProfile.php and update apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php plus apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php to distinguish current trustworthy baseline from no-data evidence
• T021 [US2] Update apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Filament/Pages/BaselineCompareLanding.php, and profile-level compare affordances in apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php so compare availability derives from effective consumable baseline truth after blocked, failed, or no-data capture outcomes rather than latest capture completion or snapshot existence alone
• T022 [US2] If implementation proves historical empty complete snapshots still influence current runtime truth, adjust the relevant legacy finalization path and apps/platform/tests/Feature/Baselines/BaselineSnapshotBackfillTest.php inside the same slice; otherwise record in specs/235-baseline-capture-truth/quickstart.md and the active PR close-out note that no compatibility backfill change was required

Checkpoint: User Story 2 is independently functional and zero-subject capture remains visible without becoming authoritative baseline truth.

---

Phase 5: User Story 3 - Explain All-Zero Capture Truth On Monitoring Surfaces (Priority: P3)

Goal: Ensure Monitoring leads with the dominant blocked or no-data explanation before raw counts or JSON.

Independent Test: Open seeded blocked and zero-subject baseline capture runs in Monitoring and verify the dominant cause and next step appear before diagnostics.

Tests for User Story 3

• T023 [P] [US3] Expand apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php for blocked latest inventory, failed latest inventory, after-enqueue drift, and zero-subject no-usable-baseline headlines
• T024 [P] [US3] Expand apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php, apps/platform/tests/Feature/Monitoring/AuditCoverageGovernanceTest.php, and apps/platform/tests/Feature/Notifications/OperationRunNotificationTest.php for consistent blocked or partially_succeeded baseline-capture truth, audit summary wording including whether current baseline truth changed, and initiator-aware terminal notification behavior

Implementation for User Story 3

• T025 [P] [US3] Extend apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php with dominant explanation and next-step branches for blocked latest inventory, after-enqueue drift, failed inventory, unusable coverage, and zero-subject no-data capture
• T026 [US3] Reconcile shared run-detail and operator-explanation consumption across apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php, apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, and apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php so Monitoring, compare landing, and audit prose use the same baseline-domain vocabulary and explicitly communicate whether current baseline truth changed without page-local fallbacks
• T027 [US3] Update apps/platform/app/Notifications/OperationRunCompleted.php and any baseline-capture completion payload helpers so terminal notification copy reflects the same dominant reason, communicates whether current baseline truth changed, and preserves initiator-aware delivery rules for interactive versus initiator-null runs

Checkpoint: User Story 3 is independently functional and Monitoring explains blocked/no-data baseline truth before diagnostics.

---

Phase 6: Polish & Cross-Cutting Validation

Purpose: Finish formatting, verify there is no local truth drift, and run the narrow proving pack.

• T028 [P] Search the touched runtime and surface files apps/platform/app/Services/Baselines/BaselineCaptureService.php, apps/platform/app/Jobs/CaptureBaselineSnapshotJob.php, apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php, apps/platform/app/Support/Baselines/BaselineCompareStats.php, apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php, apps/platform/app/Filament/Pages/BaselineCompareLanding.php, apps/platform/app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php, apps/platform/app/Support/OpsUx/OperationUxPresenter.php, and apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php to confirm no page-local explanation branches or stale-success fallback logic remain
• T029 Run formatting for all touched PHP and test files with export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
• T030 [P] Run the baseline capture and Filament surface validation pack from specs/235-baseline-capture-truth/quickstart.md against apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php, apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php, apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php, and apps/platform/tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
• T031 [P] Run the Monitoring, audit/notification, and authorization validation pack from specs/235-baseline-capture-truth/quickstart.md against apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php, apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php, apps/platform/tests/Feature/Monitoring/AuditCoverageGovernanceTest.php, apps/platform/tests/Feature/Notifications/OperationRunNotificationTest.php, and apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php
• T032 [P] Run apps/platform/tests/Feature/Baselines/BaselineSnapshotBackfillTest.php only if T022 changed legacy empty-snapshot classification behavior
• T033 Record the Guardrail close-out entry in specs/235-baseline-capture-truth/quickstart.md and the active PR description for Guardrail status, standard-native-filament plus monitoring-state-page coverage, and whether T022 resolved as document-in-feature or required a follow-up

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Starts immediately and locks anchors plus proving commands.
• Foundational (Phase 2): Depends on Setup and blocks all story work until shared truth boundaries are explicit.
• User Story 1 (Phase 3): Depends on Foundational and is the MVP cut.
• User Story 2 (Phase 4): Depends on User Story 1 because zero-subject truth builds on the new reason-code and eligibility groundwork in the same capture workflow.
• User Story 3 (Phase 5): Depends on User Story 1 and User Story 2 because Monitoring must reflect the final blocked and no-data truth contract.
• Polish (Phase 6): Depends on all completed story work.

User Story Dependencies

• US1: No dependency beyond Foundational.
• US2: Depends on US1 shared reason-code, run-context, and preflight/runtime truth changes.
• US3: Depends on US1 and US2 shared truth being complete.

Within Each User Story

• Write the story tests first and confirm they fail before implementation is considered complete.
• Keep copy and explanation centralized through shared baseline and Ops UX helpers.
• Preserve current confirmation-gated action topology and existing capability enforcement.
• Preserve OperationRunService ownership of terminal status and outcome transitions.
• Finish story-level validation before moving to the next dependent story.

Parallel Opportunities

• T001 and T002 can run in parallel during Setup.
• T003, T004, T005, and T006 can run in parallel during Foundational work.
• T007, T008, and T009 can run in parallel for User Story 1; T010 and T011 can also proceed in parallel before T012 through T014.
• T015, T016, and T017 can run in parallel for User Story 2 before the implementation sequence T018 through T022.
• T023 and T024 can run in parallel for User Story 3 before T025 through T027.
• T030, T031, and T032 can run in parallel during final validation when their prerequisites are satisfied.

---

Parallel Example: User Story 1

# User Story 1 tests in parallel
T007 apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php
T008 apps/platform/tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php
T009 apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php

# Shared reason and translation groundwork in parallel
T010 apps/platform/app/Support/Baselines/BaselineReasonCodes.php
T011 apps/platform/app/Support/ReasonTranslation/ReasonTranslator.php

Parallel Example: User Story 2

# User Story 2 tests in parallel
T015 apps/platform/tests/Feature/Baselines/BaselineCaptureTest.php
T016 apps/platform/tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
T017 apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php

Parallel Example: User Story 3

# User Story 3 tests in parallel
T023 apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php
T024 apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Run T029 and T030 before widening the slice.

Incremental Delivery

1. Ship User Story 1 to eliminate false-green capture starts and runtime success on non-credible latest inventory.
2. Ship User Story 2 to keep zero-subject captures visible but non-authoritative.
3. Ship User Story 3 to align Monitoring with the hardened capture truth.
4. Finish with the final formatting, validation, and guardrail close-out tasks.

Parallel Team Strategy

1. One contributor can prepare the shared reason-code and translation groundwork while another prepares the User Story 1 proof surfaces.
2. After User Story 1 lands, one contributor can take the zero-subject runtime path while another prepares the User Story 2 surface tests.
3. User Story 3 can start once the blocked and no-data run-context truth is stable enough for Monitoring and Ops UX proof.

---

Notes

• [P] tasks target different files or independent proof surfaces and can be worked in parallel once upstream blockers are cleared.
• [US1], [US2], and [US3] map directly to the feature specification user stories.
• No contracts/ artifact is required for this feature because there is no external API or route contract change.
• The suggested MVP scope is Phase 1 through Phase 3 only.