TenantAtlas/specs/164-run-detail-hardening/quickstart.md

Quickstart: Operation Run Detail Hierarchy, Deduplication, and Decision Guidance Hardening

Goal

Validate that the canonical operation-run detail page now behaves as a decision-first surface without changing route semantics, authorization, or underlying OperationRun meaning.

Prerequisites

1. Start Sail if it is not already running.
2. Ensure the workspace has representative OperationRun fixtures for:
   • completed success
   • completed partial or follow-up required
   • failed
   • blocked
   • stale or reconciled
   • artifact-heavy baseline capture or baseline compare
3. Ensure the acting user is a valid workspace member and, for tenant-bound runs, entitled to the referenced tenant.

Focused Automated Verification

Run only the tests that guard this surface first:

vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Operations/TenantlessOperationRunViewerTest.php
vendor/bin/sail artisan test --compact tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php

If new spec-scoped tests are added during implementation, run them alongside the existing files with --filter or direct file paths.

Manual Validation Pass

For each representative run, open the canonical detail page and check the following in order.

1. First-screen decision quality

Confirm the first visible page height answers:

• what run this is
• how it ended
• whether the visible result is trustworthy enough to use
• what the operator should do next

2. Next-step singularity

Confirm there is exactly one leading next-step statement in the decision zone.

Confirm that:

• the same next-step text is not repeated in a sidebar card
• the same next-step text is not repeated in a run summary section
• any extra guidance is visibly secondary

3. Count deduplication

Confirm there is no duplicate count block in main content.

Allowed:

• one primary count summary
• one clearly diagnostic count breakdown with a different purpose

Not allowed:

• the same normalized counts shown twice as equal-priority summary content

4. Semantic separation

For artifact-heavy runs, confirm the page still distinguishes:

• execution status
• outcome
• artifact truth
• result trust
• next action

A successful execution outcome must still be able to coexist with limited trust or weak artifact usability.

5. Special-state behavior

For blocked, stale, or reconciled runs, confirm:

• the exceptional state is visible
• the explanation is understandable without opening JSON
• the same lifecycle warning is not repeated as equal-priority content across banner, decision zone, and supporting facts

6. Type-specific coexistence

For baseline compare, baseline capture, or verification-heavy runs, confirm:

• the generic decision zone appears first
• type-specific detail appears afterward
• raw payloads and JSON remain secondary

Non-Regression Checks

Confirm the feature did not change:

• canonical route identity for /admin/operations/{run}
• workspace or tenant authorization behavior
• 404 versus 403 semantics
• DB-only render behavior on the page
• existing related-context links and canonical navigation patterns

Formatting And Final Verification

Before finalizing implementation work:

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

Then rerun the smallest affected test set. If the user wants a broader confidence pass afterward, offer the full suite.