TenantAtlas/specs/178-ops-truth-alignment/quickstart.md

Quickstart: Operations Lifecycle Alignment & Cross-Surface Truth Consistency

Goal

Validate that tenant, workspace, canonical admin, and system operations surfaces now tell the same lifecycle story for fresh active runs, likely stale active runs, reconciled stale runs, and terminal problem runs, and that local progress surfaces stop implying false activity within one polling cycle.

Prerequisites

1. Start Sail.
2. Ensure you have one admin-plane user with workspace and tenant access and one platform user with system operations view access.
3. Seed or create run scenarios for:
   • fresh active run
   • likely stale active run
   • automatically reconciled stale run
   • terminal failed run
   • terminal blocked or partially succeeded run
   • healthy completed run
4. Ensure the seeded runs are visible through:
   • tenant dashboard operations summary and recent operations
   • workspace overview operations summary and recent operations
   • /admin/operations
   • /admin/operations/{run}
   • /system/ops/stuck
   • /system/ops/failures
   • /system/ops/runs/{run}
5. Prepare at least one scenario where canonical truth changes from active to terminal or reconciled without a new enqueue event so local progress freshness can be verified.

Implementation Validation Order

1. Run lifecycle and reconciliation baselines

vendor/bin/sail artisan test --compact tests/Feature/Console/ReconcileOperationRunsCommandTest.php
vendor/bin/sail artisan test --compact tests/Feature/Console/ReconcileBackupScheduleOperationRunsCommandTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/MonitoringOperationsTest.php

Expected outcome:

• Existing stale/reconciliation semantics remain stable.
• Canonical monitoring still renders DB-only and tenant-safe.

2. Run tenant/workspace summary and recency coverage

vendor/bin/sail artisan test --compact tests/Feature/Filament/DashboardKpisWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewOperationsTest.php

Expected outcome:

• Tenant and workspace summary surfaces separate terminal follow-up from active stale/stuck attention.
• Recent-operation rows distinguish fresh active, stale active, reconciled stale, and terminal follow-up truth.

3. Run local-progress freshness coverage

vendor/bin/sail artisan test --compact tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php

Expected outcome:

• The overlay polls only while relevant active runs exist.
• Terminal or reconciled runs disappear within one refresh cycle even without a new enqueue event.

4. Run canonical admin monitoring and drill-through coverage

vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsTenantScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/RunAuthorizationTenantIsolationTest.php

Expected outcome:

• /admin/operations preserves tenant-safe problem-class continuity from dashboard/workspace entry points.
• Canonical monitoring remains DB-only and authorization-safe.

5. Run system-panel visibility coverage

vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/CanonicalRunDetailTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsFailuresViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsStuckViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php

Expected outcome:

• /system/ops/stuck keeps active stale candidates visible.
• /system/ops/failures and system detail preserve stale/reconciled lineage for terminal runs that were auto-reconciled.

6. Run notification and surface-guard coverage

vendor/bin/sail artisan test --compact tests/Feature/Notifications/OperationRunNotificationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php

Expected outcome:

• Terminal notifications and linked destinations do not frame reconciled or stale-derived terminal runs more calmly than current truth.
• Changed surfaces still satisfy their action-surface contracts.

7. Format touched files

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

Expected outcome:

• Changed files conform to project formatting rules.

8. Re-run the final focused verification pack

vendor/bin/sail artisan test --compact tests/Feature/Filament/DashboardKpisWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewOperationsTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/MonitoringOperationsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDbOnlyRenderTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsDbOnlyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsTenantScopeTest.php
vendor/bin/sail artisan test --compact tests/Feature/RunAuthorizationTenantIsolationTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/CanonicalRunDetailTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsFailuresViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsStuckViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php
vendor/bin/sail artisan test --compact tests/Feature/Notifications/OperationRunNotificationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php

Expected outcome:

• Cross-surface truth alignment, stale-lineage visibility, local-progress freshness, and drill-through continuity all remain stable after formatting.

Manual Smoke Check

1. Open /admin/t/{tenant} for seeded tenant scenarios representing fresh active, likely stale active, reconciled stale, terminal failure, and healthy completion.
2. Confirm tenant summary surfaces do not mix terminal follow-up with active stale/stuck attention.
3. Leave BulkOperationProgress visible while one run transitions from active to terminal or reconciled without a new enqueue event and confirm the overlay stops showing it as active within one refresh cycle.
4. Click tenant and workspace operations-attention links and confirm /admin/operations opens with the same problem class visible on arrival.
5. Open a stale-active run in /admin/operations/{run} and confirm the decision zone answers whether the run is still active and what to do next.
6. Open an auto-reconciled run in /admin/operations/{run} and confirm the decision zone answers that the run is no longer active, that reconciliation already happened, and what follow-up is appropriate.
7. As a platform user, open /system/ops/stuck, /system/ops/failures, and /system/ops/runs/{run} and confirm stale/reconciled lineage stays discoverable across the system truth chain.
8. Open an operation completion notification for a reconciled stale run and confirm the linked destination visibly confirms the same problem class.
9. Time a seeded operator walkthrough across tenant dashboard, workspace overview, /admin/operations, /admin/operations/{run}, and /system/ops/runs/{run} and confirm each entry surface makes the run's fresh-active, likely-stale, reconciled, or terminal-follow-up state understandable within 10 seconds.

Non-Goals For This Slice

• No schema migration.
• No new lifecycle or problem-state table.
• No new route family for tenant-specific operations monitoring.
• No notification subsystem redesign.
• No tenant-admin retry/cancel capability expansion.