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

Feature Specification: Operation Run Detail Hierarchy, Deduplication, and Decision Guidance Hardening

Feature Branch: 164-run-detail-hardening
Created: 2026-03-26
Status: Draft
Input: User description: "Spec 164 — Operation Run Detail Hierarchy, Deduplication, and Decision Guidance Hardening"

Spec Scope Fields (mandatory)

• Scope: canonical-view
• Primary Routes:
  • /admin/operations/{run}
  • Existing in-product deep links that resolve to the canonical operation-run detail page
• Data Ownership:
  • OperationRun remains the canonical workspace-owned execution record even when it references a tenant or related artifact
  • Related artifacts, tenant context, and operation-type-specific evidence remain owned by their existing domain records
  • This feature changes presentation hierarchy and operator guidance only; it does not change ownership, persistence, or route identity
• RBAC:
  • Existing workspace membership remains required to reach the canonical run detail page
  • Existing tenant entitlement rules continue to govern tenant-linked related context and any tenant-bound follow-up links
  • Existing operation history or monitoring capabilities remain authoritative for viewing the run detail experience

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Remembered tenant context may continue to influence the origin surface or back-navigation convenience, but it must not change the legitimacy, hierarchy, or visible decision contract of the canonical run detail page itself.
• Explicit entitlement checks preventing cross-tenant leakage: The page must continue to resolve from the run and authorized related records only. Non-members or actors without tenant entitlement for tenant-linked context must receive deny-as-not-found behavior for inaccessible targets, and the detail surface must not leak inaccessible related records, counts, or hints through summary, diagnostics, or navigation.

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

If this feature adds a new operator-facing page or materially refactors one, fill out one row per affected page/surface.

Surface	Primary Persona	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Canonical operation-run detail	Workspace operator or entitled tenant operator	Canonical detail	What happened in this run, is the result trustworthy enough to use, and what should I do next?	Run identity, execution state, outcome, artifact truth, result meaning or trust, one primary next step, high-signal lifecycle caveats, compact supporting facts	Detailed count breakdowns, raw failure fragments, large context blocks, JSON payloads, technical reason evidence, low-level reconciliation detail	execution status, outcome, artifact truth, trust or confidence, lifecycle or freshness, next-action readiness	Read-only surface; any contextual links continue to use their existing mutation-scope messaging outside this spec	View run, follow the primary next step, open related context, refresh the page	None introduced by this spec

User Scenarios & Testing (mandatory)

User Story 1 - Triage a run in one scan (Priority: P1)

As an operator opening a single operation run, I want the first visible area of the page to tell me what happened, whether the result is usable, and what I should do next, so that I do not need to assemble the answer from multiple sections.

Why this priority: The page is the canonical decision surface for a run. If the operator cannot answer the core triage questions quickly, the surface fails even when the domain model is correct.

Independent Test: Can be fully tested by opening completed, partial, and failed runs and verifying that execution state, outcome, artifact truth, trust meaning, and one primary next step are visible before diagnostic sections.

Acceptance Scenarios:

1. Given a completed run with follow-up required, When an operator opens the canonical run detail page, Then the first visible zone shows the run result, its trustworthiness, and exactly one primary next step without requiring scrolling.
2. Given a completed run with a trustworthy result and no urgent follow-up, When an operator opens the page, Then the first visible zone communicates that the result is usable and does not bury that message beneath counts or raw detail.
3. Given a failed or blocked run, When an operator opens the page, Then the first visible zone explains the failure character and the most sensible follow-up action before diagnostic evidence.

---

User Story 2 - Understand special-state caveats without confusion (Priority: P2)

As an operator reviewing a stale, reconciled, partial, or artifact-limited run, I want the page to explain why the result needs caution without repeating the same warning in multiple places, so that I can trust the page's interpretation.

Why this priority: Special states are operationally important, but they should sharpen the decision rather than flood the page with duplicate warnings.

Independent Test: Can be fully tested by opening runs with stale, reconciled, blocked, and limited-confidence states and verifying that caveats are visible, contextual, and not rendered as competing top-level truths.

Acceptance Scenarios:

1. Given a stale or lifecycle-reconciled run, When the page renders, Then the operator sees why the lifecycle is unusual and what follow-up is appropriate without the page repeating that state as equal-priority summary facts, banners, and duplicate cards.
2. Given a run whose artifact exists but has limited trust or incomplete evidence, When the page renders, Then artifact truth remains distinct from outcome and the operator can see the caution without opening diagnostics.
3. Given a run with no artifact or no trustworthy result to use, When the page renders, Then the page makes that limitation explicit and points the operator to the next reasonable action.

---

User Story 3 - Keep deep detail without losing the decision hierarchy (Priority: P3)

As an operator or support engineer, I want type-specific detail and diagnostics to remain available after the main decision summary, so that I can continue from triage into investigation without losing the canonical page structure.

Why this priority: The feature must improve scanability without flattening the strong domain depth that makes the page useful for investigation.

Independent Test: Can be fully tested by opening runs with baseline-compare or other type-specific sections and confirming that those sections still render, but only after the canonical decision and supporting context.

Acceptance Scenarios:

1. Given a run with type-specific evidence or findings, When the operator opens the page, Then the generic decision summary appears first and the type-specific detail appears afterwards as deeper context.
2. Given a run with extensive counts, reasons, or raw context, When the operator opens the page, Then diagnostics remain available but do not appear at the same priority as the decision summary.
3. Given a run with both high-signal summary facts and technical evidence, When the page renders, Then the page preserves a clear reading order of decision first, supporting detail second, diagnostics third.

Edge Cases

• A completed run may have an apparently successful execution outcome but an artifact-truth or trust statement that makes the result unsafe to use; the page must show both meanings without collapsing one into the other.
• A stale or lifecycle-reconciled run may require attention even when it is not technically failed; the page must explain the situation without duplicating the same message across multiple equal-priority sections.
• A run may contain large count sets, failure summaries, or raw payload context; the page must keep those details available without letting them crowd out the primary decision zone.
• A run may have no meaningful counts at all; the page must still present a coherent decision surface instead of reserving high-value space for empty or low-signal sections.
• A run may include operation-type-specific detail such as baseline compare evidence, restore outcomes, or artifact-heavy context; those details must remain usable without displacing the canonical summary-first hierarchy.
• A run may be opened from a tenant-related entry point while still being a canonical workspace run; the hierarchy and visible meaning must remain stable and permission-safe.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new Microsoft Graph calls, no new change workflow, and no new long-running job type. It hardens the presentation and operator guidance of an existing canonical monitoring record. Existing OperationRun creation, audit behavior, and safe-execution rules for any already-existing follow-up actions remain authoritative and unchanged.

Constitution alignment (OPS-UX): This feature reuses existing OperationRun records as a read surface only. The Ops-UX 3-surface feedback contract remains unchanged. OperationRun.status and OperationRun.outcome remain service-owned through the existing run service. summary_counts continues to honor OperationSummaryKeys::all() and numeric-only normalization. Scheduled or system-run behavior does not change. Regression coverage for this feature must protect decision hierarchy, next-step singularity, count deduplication, special-state clarity, type-specific coexistence, and navigation or authorization non-regression.

Constitution alignment (RBAC-UX): This feature stays in the admin canonical-view plane and may display tenant-linked context. Non-members or actors lacking tenant entitlement for tenant-linked context remain deny-as-not-found. Members who are otherwise in scope but lack the capability to inspect the run remain forbidden. Authorization continues to be enforced server-side through existing policies, Gates, and canonical capability registries. No raw capability strings or role-string shortcuts may be introduced. Global search behavior remains non-member-safe. This feature introduces no new destructive action; any existing destructive-like action exposed from the page must continue to require confirmation and existing authorization.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. Monitoring and canonical run detail remain outside any /auth/* exception path.

Constitution alignment (BADGE-001): Any status-like badges shown or elevated by this feature must continue to come from centralized badge semantics. Execution status, outcome, artifact truth, trust or confidence, and lifecycle or freshness meaning must not be mapped ad hoc on the page.

Constitution alignment (UI-NAMING-001): The target object is the operation run. Primary operator verbs remain consistent with the existing vocabulary, including View run and other established follow-up language. The page must preserve domain terms such as Outcome, Artifact truth, Trust, Follow-up, and Next step where they carry distinct meaning, and must avoid replacing them with vague implementation-first or oversimplified labels.

Constitution alignment (OPSURF-001): The default-visible content must remain operator-first and answer the decision questions before raw implementation detail. Diagnostics must be explicitly secondary. The page must continue to show execution outcome, artifact truth, trust or confidence, and lifecycle or freshness as separate status dimensions because operators need each dimension for sound decisions. No new mutation is introduced by this spec. Workspace and tenant context remain explicit in page meaning and related navigation. The surface contract is defined above for the canonical run detail page.

Constitution alignment (Filament Action Surfaces): This feature materially refactors an existing Filament-backed detail surface. The Action Surface Contract remains satisfied because the refactor changes hierarchy, grouping, and repetition rather than expanding the action inventory. The UI Action Matrix below documents the affected surface. No exemption is required.

Constitution alignment (UX-001 — Layout & Information Architecture): The canonical run detail page remains a structured view surface, not a disabled edit form. The page must keep information inside clearly named sections or cards, keep badges centralized, and use progressive disclosure for diagnostics. Because this is an existing custom enterprise detail view rather than a standard resource infolist, the current custom-view composition remains an explicit exemption from the default view-page pattern, but the feature must still satisfy the operator-first hierarchy intent of UX-001.

Functional Requirements

• FR-164-001: The system MUST give the canonical run detail page one explicit primary decision zone in the immediately visible upper portion of the page.
• FR-164-002: The primary decision zone MUST present execution or run state, outcome, artifact truth, result meaning or trust, and exactly one primary next step in one coherent reading path.
• FR-164-003: The primary decision zone MUST answer, without scrolling, what happened in the run, whether the result is usable, and what the operator should do next.
• FR-164-004: The page MUST show exactly one leading next-step statement as the authoritative operator action, and any additional guidance MUST appear only as secondary or context-specific guidance.
• FR-164-005: The page MUST NOT repeat the same next-step statement in multiple equal-priority sections, cards, or grids.
• FR-164-006: The page MUST provide one primary count presentation when summary_counts adds decision value, and any secondary count display MUST serve a clearly different purpose such as compact hinting or deeper diagnostics.
• FR-164-007: The page MUST NOT render identical or effectively identical count blocks more than once in the main content hierarchy.
• FR-164-008: Any run-summary section that remains on the page MUST add information not already adequately conveyed by the header and primary decision zone; otherwise that section MUST be removed or absorbed into another structure.
• FR-164-009: The supporting area MUST be reorganized from a flat fact dump into semantically grouped supporting information so that guidance, lifecycle caveats, and secondary metadata are distinguishable at a glance.
• FR-164-010: Artifact truth MUST remain a distinct first-class statement whenever result usability depends on it, and it MUST NOT be collapsed into outcome, execution lifecycle, or generic success or failure wording.
• FR-164-011: Artifact truth MAY be summarized in the primary decision zone and expanded later in the page, but the same artifact-truth meaning MUST NOT be repeated in multiple equal-priority areas.
• FR-164-012: Stale, reconciled, blocked, partial, or otherwise special lifecycle conditions MUST remain visible and must explain why the run landed in that state and what follow-up is sensible.
• FR-164-013: Special lifecycle conditions MUST be presented contextually and MUST NOT dominate the normal page layout through redundant repetition across banner, sidebar, and summary zones.
• FR-164-014: The page MUST follow a stable reading order of decision first, supporting operational detail second, and diagnostics or raw context third.
• FR-164-015: Large context blocks, raw payloads, JSON fragments, detailed reason evidence, and other low-frequency technical information MUST remain secondary to decision content and MUST be explicitly disclosed or placed later on the page.
• FR-164-016: The first visible page height MUST allow an operator to understand the run identity, how it ended, whether the visible result is trustworthy enough to use, and whether immediate action is needed within a short scan.
• FR-164-017: The page MUST preserve the semantic distinction between execution status, outcome, artifact truth, trust or confidence, and next action even while simplifying the visible hierarchy.
• FR-164-018: The page MUST continue to support operation-type-specific detail sections, but those sections MUST appear after the canonical decision and supporting summary layers.
• FR-164-019: The page MUST preserve the existing canonical run-detail route, deep-link behavior, and workspace-versus-tenant meaning of the record.
• FR-164-020: The page MUST preserve existing RBAC and visibility semantics and MUST NOT widen access through summary, diagnostics, or related-context presentation.
• FR-164-021: The page MUST use progressive disclosure or lower-priority placement for support and investigation detail rather than removing information that operators or support staff still need.

Non-Functional Requirements

• NFR-164-001: The feature SHOULD be deliverable without new tables, new domain entities, or required persistence-model changes.
• NFR-164-002: Operator-facing copy may become shorter or clearer, but it MUST NOT flatten or blur the existing domain semantics around follow-up, artifact truth, trust, or limited confidence.
• NFR-164-003: Existing canonical route identity and existing deep links to the page MUST remain stable.
• NFR-164-004: Existing RBAC and view-permission behavior MUST remain intact.
• NFR-164-005: De-prioritized technical content MUST remain available for investigation through lower-priority sections or progressive disclosure.

Non-Goals

• Redesigning the operations list, queue view, or monitoring filter logic
• Changing notification copy, toast behavior, or persistent notification flows
• Reworking dashboard widgets, floating progress surfaces, or global monitoring shells
• Introducing new outcome enums, execution-status enums, or new artifact-governance models
• Changing OperationRun persistence, record ownership, or the underlying domain state model
• Performing a broad Filament design-system overhaul beyond this single decision surface

Assumptions

• The current OperationRun domain model, outcome semantics, artifact-truth logic, and operator explanation layer are already strong enough that the primary need is surface hardening rather than conceptual redesign.
• The canonical run detail page already contains the necessary information for a stronger decision hierarchy, but currently presents too many facts at the same visual weight.
• Existing type-specific sections, related context, and diagnostic payloads remain valuable and should be preserved behind a better primary reading order.
• Existing navigation, canonical links, and authorization behavior remain the source of truth and should not be redefined by this feature.

Dependencies

• Existing canonical OperationRun model and its separation of execution status, outcome, and context
• Existing artifact-truth, trust or confidence, and operator-explanation semantics already available to the run detail experience
• Existing canonical operation-run navigation and tenant-safe related-context resolution
• Existing RBAC and visibility rules for workspace membership, tenant entitlement, and run inspection
• Existing type-specific operation detail content that must continue to coexist with the canonical page hierarchy

Risks

• The page could become calmer but less useful if diagnostic depth is removed instead of deliberately de-prioritized.
• A layout-driven simplification could blur the distinction between outcome, artifact truth, and trust, which would weaken operator judgment.
• A stronger generic decision zone could accidentally crowd out type-specific detail for artifact-heavy or evidence-heavy runs if the hierarchy is not enforced carefully.

UI Action Matrix (mandatory when Filament is changed)

If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?), RBAC gating (capability + enforcement helper), and whether the mutation writes an audit log.

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Canonical operation-run detail	Existing canonical operation-run detail page	Existing page-level navigation and non-destructive follow-up actions remain; no new destructive header action is introduced by this spec	Existing View run affordances from operations and related surfaces remain the entry point	View run remains the relevant row action on upstream list surfaces	None added by this spec	Not applicable on the detail page	Existing view-page actions remain, but the page must expose one primary next-step statement and demote secondary guidance	Not applicable	No new audit event introduced by this spec	Action Surface Contract satisfied. Any already-existing destructive or run-triggering follow-up action remains governed by existing confirmation, authorization, and audit rules outside this hierarchy-hardening change.

Key Entities (include if feature involves data)

• Operation Run: The canonical execution record whose detail page is the authoritative operator view for what happened, how it ended, and what to do next.
• Primary Decision Zone: The first visible summary area that expresses execution state, outcome, artifact truth, trust meaning, and one primary next step.
• Supporting Operational Context: Secondary page content that explains lifecycle caveats, timing, freshness, reconciliation, and compact supporting facts without competing with the primary decision.
• Diagnostic Surface: Lower-priority detail such as raw payloads, detailed counts, failure evidence, and technical context used for investigation after the initial decision is made.
• Type-Specific Detail Block: Operation-specific content that remains important for deeper understanding, but must sit below the canonical decision and supporting layers.

Success Criteria (mandatory)

Measurable Outcomes

• SC-164-001: In acceptance review, operators can identify the run result, its trustworthiness, and the primary next step from the first visible page height for every covered scenario in 10 seconds or less.
• SC-164-002: In covered scenarios, the page presents exactly one primary next-step statement and does not repeat the same next-step text in multiple equal-priority regions.
• SC-164-003: In covered scenarios, the main content hierarchy contains no duplicate or effectively duplicate count block.
• SC-164-004: In covered completed, partial, failed, stale or reconciled, and artifact-limited scenarios, operators can tell whether immediate action is needed without opening diagnostic sections.
• SC-164-005: Type-specific operation detail remains available for covered run types, but always appears after the canonical decision and supporting summary layers.
• SC-164-006: Navigation, RBAC behavior, and the semantic separation between execution status, outcome, artifact truth, trust, and next action remain unchanged in regression review.