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

# Feature Specification: Operations Lifecycle Alignment & Cross-Surface Truth Consistency

**Feature Branch**: `178-ops-truth-alignment`  
**Created**: 2026-04-05  
**Status**: Proposed  
**Input**: User description: "Spec 178 - Operations Lifecycle Alignment & Cross-Surface Truth Consistency"

## Spec Scope Fields *(mandatory)*

- **Scope**: tenant + workspace + canonical-view + platform
- **Primary Routes**:
  - `/admin` as the workspace overview surface where workspace attention and workspace recent operations appear
  - `/admin/t/{tenant}` as the tenant dashboard surface where tenant attention, recent operations, and active progress affordances appear
  - `/admin/operations` as the canonical monitoring hub and drill-through destination from admin-plane summaries
  - `/admin/operations/{run}` as the canonical run detail surface
  - `/system/ops/runs`, `/system/ops/failures`, and `/system/ops/stuck` as the platform-plane monitoring registry surfaces
  - `/system/ops/runs/{run}` as the platform-plane operation detail surface
- **Data Ownership**:
  - Existing `OperationRun` records remain the only canonical lifecycle source of truth for queued, running, completed, stale, and automatically reconciled runs
  - Existing workspace-owned monitoring truth with optional tenant linkage remains in place; the feature does not add a second summary record, mirror lifecycle store, or notification-specific state model
  - Freshness interpretation, stale or reconciled visibility, terminal follow-up grouping, and cross-surface drill-through continuity remain derived views over existing `OperationRun` truth
  - No schema migration, no new persisted lifecycle state, and no enum rewrite are introduced
- **RBAC**:
  - Admin-plane summary and canonical-view surfaces continue to require workspace membership, and any tenant-bound summary or run detail continues to require tenant entitlement for the referenced tenant
  - Platform-plane system surfaces continue to rely on existing system operations view and manage capabilities without broadening `/system` access
  - Non-members or users outside the relevant workspace or tenant scope remain `404`; in-scope users lacking a capability for a guarded follow-up affordance remain `403`
  - Cross-plane navigation must remain explicit and must not leak tenant truth from admin surfaces into system surfaces or vice versa

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: `/admin/operations` may continue to prefilter to the active tenant, but dashboard, attention, recent-operations, and notification drill-throughs MUST also preserve the originating problem class so operators land on the same issue family they clicked. Operators may broaden filters only within already entitled scope.
- **Explicit entitlement checks preventing cross-tenant leakage**: Every admin-plane summary claim, pre-applied filter, run detail page, and related drill-through MUST resolve only after workspace membership and tenant entitlement checks against the referenced run. Reconciled, stale, terminal-failure, and follow-up states must not reveal another tenant's existence or activity to unauthorized users.

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Surface Type | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard operations attention | Embedded attention summary | One explicit problem-class CTA per summary bucket | forbidden | none | none | `/admin/operations` | `/admin/operations/{run}` | Active tenant context and tenant-preserving destination state | Operations / Operation | Separate terminal issues from stale active issues | Multi-bucket summary surface |
| Tenant dashboard recent operations | Diagnostic recency table | Row open to canonical operation detail | required | header link only | none | `/admin/operations` with tenant prefilter | `/admin/operations/{run}` | Active tenant context and tenant-scoped recent activity | Operations / Operation | Fresh active, likely stale, and terminal follow-up states remain distinguishable per row | none |
| Bulk operation progress | Live progress indicator | Compact item open to canonical operation detail plus collection fallback | compact item link only | collection link only | none | `/admin/operations` with tenant prefilter | `/admin/operations/{run}` | Active tenant context and active-run-only framing | Operations / Operation | Only truly active or still-problematic runs remain visible | Compact progress surface |
| Workspace operations attention | Embedded attention summary | One explicit problem-class CTA per summary bucket | forbidden | none | none | `/admin/operations` | `/admin/operations/{run}` | Workspace scope plus tenant counts where relevant | Operations / Operation | Separate terminal issues from stale active issues across the workspace | Multi-bucket summary surface |
| Workspace recent operations | Diagnostic recency table | Row open to canonical operation detail | required | header link only | none | `/admin/operations` | `/admin/operations/{run}` | Workspace scope with tenant identity per row | Operations / Operation | Recent operations do not hide stale or reconciled truth behind generic recency language | none |
| Operations hub | Read-only Registry / Report | Full-row click to canonical operation detail | required | filters, tabs, and header-level context only | none on the list | `/admin/operations` | `/admin/operations/{run}` | Workspace scope, tenant filter state, and problem-class filter state | Operations / Operation | Lifecycle truth, freshness truth, and problem class are visible before opening detail | none |
| Canonical operation detail | Detail-first operational surface | Dedicated detail page | forbidden | detail header links only | none introduced by this spec | `/admin/operations` | `/admin/operations/{run}` | Workspace context, tenant context when relevant, and run identity | Operations / Operation | Decision-zone lifecycle truth and next step are visible without opening diagnostics | none |
| System failed operations | Read-only Registry / Report | Full-row click to system operation detail | required | header CTA only | none | `/system/ops/failures` | `/system/ops/runs/{run}` | Platform scope only | Operations / Operation | Terminal-problem truth remains aligned with admin-plane canonical truth | none |
| System stuck operations | Read-only Registry / Report | Full-row click to system operation detail | required | header CTA only | none | `/system/ops/stuck` | `/system/ops/runs/{run}` | Platform scope only | Operations / Operation | Active stale or stuck truth and reconciled visibility remain operator-legible | none |

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

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard operations attention | Tenant operator | Embedded attention summary | Do I have a terminal issue to follow up or an active run that is likely stale? | Separate counts or labels for terminal follow-up and stale active attention, with one matching destination each | Detailed failure payloads, count internals, and infrastructure evidence | problem class, urgency, tenant scope | none | Open terminal issues, open stale active issues | none |
| Tenant dashboard recent operations | Tenant operator | Diagnostic recency table | Which recent tenant operation should I inspect next? | Operation label, lifecycle truth, outcome, freshness truth, and recency | Failure internals, raw summary counts, extended diagnostics | execution status, execution outcome, freshness | none | Open operation detail, open operations list | none |
| Bulk operation progress | Tenant operator | Live progress indicator | Is this run really still active, or has its truth changed since enqueue time? | Active run identity, current visible lifecycle truth, and quick path to detail | Low-level progress internals and failure metadata | execution status, freshness, active visibility | none | Open operation detail, open operations list | none |
| Workspace operations attention | Workspace operator | Embedded attention summary | Which operation problem class needs workspace-level follow-up first? | Separate terminal issues from stale active issues, with workspace-safe destination semantics | Deep diagnostics remain on operations views | problem class, urgency, workspace spread | none | Open terminal issues, open stale active issues | none |
| Workspace recent operations | Workspace operator | Diagnostic recency table | Which operation across the workspace changed meaning recently? | Run identity, tenant, lifecycle truth, and recency | Deeper failure and reconciliation detail remain secondary | execution status, freshness, tenant scope | none | Open operation detail, open operations list | none |
| Operations hub | Workspace operator | Read-only Registry / Report | Is this run fresh active, likely stale, reconciled, or a terminal issue, and which bucket am I looking at? | Explicit problem-class framing, lifecycle truth, freshness truth, outcome, tenant or workspace scope | Queue internals, raw context, and extended traces | execution status, execution outcome, freshness, problem class | none | Open operation detail, adjust filter or tab | none |
| Canonical operation detail | Workspace operator | Detail-first operational surface | What happened, is the run still active, was it automatically reconciled, and what do I do next? | Primary decision zone with lifecycle assessment, active or not-active answer, reconciliation state, and one primary next step | Raw payloads, detailed failure arrays, and artifact-deep diagnostics | execution status, execution outcome, freshness, operator next action | none | Return to operations, open related artifact or follow-up destination | none introduced by this spec |
| System failed operations | Platform operator | Read-only Registry / Report | Which terminal operation issue needs platform investigation first? | Terminal problem class, operation identity, workspace, tenant, and recency | Deep diagnostics remain on system detail | execution outcome, terminal problem class, recency | none | Open operation detail, show all operations | none |
| System stuck operations | Platform operator | Read-only Registry / Report | Which active run crossed the stuck threshold or was recently auto-reconciled for that reason? | Stuck or stale class, operation identity, workspace, tenant, and recency | Deep diagnostics remain on system detail | freshness, lifecycle stall state, recency | none | Open operation detail, show all operations | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: No
- **New persisted entity/table/artifact?**: No
- **New abstraction?**: No
- **New enum/state/reason family?**: No
- **New cross-domain UI framework/taxonomy?**: Yes, but only as a narrow derived monitoring split between `terminal follow-up` and `active stale/stuck attention`, built from existing lifecycle truth rather than new stored state
- **Current operator problem**: Operators can currently see the same run framed as normal active progress on one surface, terminal or reconciled on another, invisible on system stuck surfaces, and mixed into a generic follow-up bucket elsewhere
- **Existing structure is insufficient because**: Existing surfaces already have valid local logic, but their aggregation, drill-through, and attention language do not consistently tell the same operator story for stale, reconciled, and terminal problem runs
- **Narrowest correct implementation**: Reuse the current `OperationRun`, status, outcome, freshness, and reconciliation model, then align summary buckets, filters, drill-throughs, and decision-zone emphasis across existing surfaces without adding persistence or a new lifecycle engine
- **Ownership cost**: The codebase takes on shared cross-surface classification rules, copy alignment, and regression coverage to keep dashboard, recent, bulk, admin monitoring, and system monitoring semantics locked together
- **Alternative intentionally rejected**: A new persisted problem-state model, an enum rewrite, a notification redesign, or a full operations architecture refactor were rejected because the present issue is truth drift between existing surfaces, not missing core domain structure
- **Release truth**: Current-release truth. The feature hardens already shipped lifecycle semantics before more triage or monitoring slices depend on them

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Recover The Same Truth From Every Entry Point (Priority: P1)

As an operator, I want dashboard, attention, recent-operations, monitoring, and system surfaces to describe the same run with the same problem class, so that I do not have to guess which screen is telling the truth.

**Why this priority**: Cross-surface truth drift is the core trust problem. If the same run reads differently across entry points, every later triage decision becomes suspect.

**Independent Test**: Can be fully tested by seeding fresh active, likely stale, reconciled-failed, and terminal problem runs, then verifying that tenant, workspace, canonical, and system surfaces classify the same run consistently and drill through into matching destinations.

**Acceptance Scenarios**:

1. **Given** a run is canonically `likely_stale`, **When** an operator sees it on tenant attention, workspace attention, recent operations, the operations hub, and canonical detail, **Then** none of those surfaces frame it as an unremarkable normal active run.
2. **Given** a run is terminal with a blocked, partial, or failed outcome, **When** an operator reaches it from dashboard or monitoring summaries, **Then** the destination confirms a terminal follow-up problem rather than an active stale issue.
3. **Given** a run was automatically reconciled after becoming stale, **When** an operator checks admin monitoring and system monitoring surfaces, **Then** the stale or reconciled history remains discoverable instead of disappearing from the truth chain.

---

### User Story 2 - Trust Live Progress Without Waiting For A New Event (Priority: P1)

As a tenant operator, I want local progress and recent-activity surfaces to stop implying that a finished or reconciled run is still active, even when no new enqueue event occurs, so that I can trust what is on screen.

**Why this priority**: Bulk progress and recent activity are the most immediate trust surfaces. If they lag behind canonical truth, operators see false liveness first.

**Independent Test**: Can be fully tested by opening active-progress and recent-operations surfaces, changing the underlying run to terminal or reconciled truth without dispatching a new enqueue event, and verifying that local surfaces update within the allowed refresh window and then stop behaving like live active surfaces.

**Acceptance Scenarios**:

1. **Given** BulkOperationProgress is open for an active run, **When** the run completes or is automatically reconciled, **Then** the surface stops presenting it as active within the next refresh cycle even if no new enqueue event fires.
2. **Given** Recent Operations is visible on a tenant or workspace surface, **When** a displayed run becomes likely stale or terminal, **Then** the row updates to the new truth instead of continuing to imply healthy progress.
3. **Given** no relevant active runs remain, **When** the surface reaches that state, **Then** live refresh stops or becomes inactive instead of polling indefinitely.

---

### User Story 3 - Decide What To Do From The Canonical Detail Surface (Priority: P2)

As an operator opening canonical run detail, I want the primary decision zone to tell me immediately whether the run is still active, likely stale, already reconciled, or terminal and what the next step is, so that I do not have to derive action from scattered diagnostics.

**Why this priority**: Canonical detail is the highest-trust surface. If it makes lifecycle attention secondary, summary surfaces cannot reliably inherit the right operator interpretation.

**Independent Test**: Can be fully tested by opening stale, reconciled, partial, failed, and healthy active runs and verifying that the decision zone makes lifecycle truth and next action visible without relying on banners or secondary panels alone.

**Acceptance Scenarios**:

1. **Given** a run is likely stale but not yet reconciled, **When** the canonical detail page loads, **Then** the primary decision zone states that the run is still non-terminal but likely unhealthy and names the next investigation step.
2. **Given** a run has already been automatically reconciled, **When** the canonical detail page loads, **Then** the primary decision zone states that the run is no longer active, that reconciliation already happened, and what follow-up is appropriate.
3. **Given** a run type has deeper artifact truth, **When** the canonical detail page loads, **Then** lifecycle truth and next action remain visible before artifact-deep diagnostics.

---

### User Story 4 - Preserve Problem-Class Continuity In System And Notification Entry Points (Priority: P3)

As a system or workspace operator, I want notifications and platform monitoring entry points to confirm the same problem class that brought me there, so that I never land on a calmer or differently framed destination than the one I clicked.

**Why this priority**: Link continuity is where trust drift becomes obvious. If the destination tells a different story, operators stop trusting the product's routing and labels.

**Independent Test**: Can be fully tested by navigating from dashboard KPIs, attention items, recent operations, and operation notifications into admin and system monitoring destinations, then verifying that the originating problem class is visible and recoverable on arrival.

**Acceptance Scenarios**:

1. **Given** a notification frames a run as needing terminal follow-up, **When** the operator opens the linked destination, **Then** the destination visibly confirms that terminal-problem framing.
2. **Given** a dashboard or workspace attention link frames a run as stale active attention, **When** the operator opens the monitoring destination, **Then** the destination visibly confirms the stale active problem class instead of a generic mixed bucket.

### Edge Cases

- A run may move from `likely_stale` to `reconciled_failed` while an operator keeps a local progress surface open; the UI must not continue showing healthy activity after reconciliation.
- A run may be removed from the active stuck list after reconciliation; the system truth chain must still expose that it was recently stale or auto-reconciled rather than making the issue disappear.
- A run may be terminal with a poor outcome and also belong to an artifact-heavy domain; the page must not bury the lifecycle answer behind artifact diagnostics.
- A tenant-scoped summary may link into the canonical operations hub while tenant context is stale or absent; the destination must preserve the correct tenant-safe problem filter or fall back to workspace-safe scope without changing the run's problem class.
- Notifications may be generated before a stale run is later reconciled; entry-point language and destinations must not stay calmer than the current run truth.
- Run types may differ in artifact richness, but none may diverge on the base question of fresh active, likely stale, reconciled, or terminal follow-up.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph calls, no new write workflow, no new queued operation type, and no new persisted operations record. It hardens the truth alignment of existing operations and monitoring surfaces over existing `OperationRun`, freshness, and reconciliation semantics.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature stays deliberately narrow. It adds no new persistence, no new lifecycle table, no new orchestration layer, and no new enum family. The only new semantic split is a derived operator-facing distinction between terminal follow-up and active stale or stuck attention, built from existing status, outcome, freshness, and reconciliation truth.

**Constitution alignment (OPS-UX):** Existing `OperationRun` records remain subject to the three-surface feedback contract. Toasts remain intent-only. Active awareness remains on allowed progress and monitoring surfaces only. Terminal state transitions remain service-owned. This feature may change how active progress surfaces refresh and how summaries classify runs, but it must not add ad-hoc status mutation or a second terminal lifecycle model. Summary counts remain numeric-only and scheduled or system-run notification rules remain unchanged. Regression coverage MUST prove progress freshness, truth alignment, and reconciled visibility without reintroducing direct state mutation on render surfaces.

**Constitution alignment (RBAC-UX):** This feature spans the admin plane and the platform plane. Admin-plane tenant and workspace surfaces continue to use deny-as-not-found for non-members or non-entitled users, and canonical operation routes continue to authorize from workspace and tenant entitlement before revealing run truth. Platform-plane system monitoring continues to rely on platform capability checks. The feature adds no new mutation, no new destructive action, and no cross-plane bypass. Any in-scope destination affordance that is visible but capability-gated must remain helper-texted or disabled rather than turning into a misleading dead-end link.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. Authentication handshake exceptions remain unrelated to operations monitoring and cannot be used to justify stale or reconciled truth drift.

**Constitution alignment (BADGE-001):** Existing centralized semantics for operation status, outcome, freshness, and related attention labels remain authoritative. The feature MUST not allow dashboard widgets, recent-operation surfaces, operations hub rows, or notifications to invent page-local meanings for stale, reconciled, blocked, partial, or failed states.

**Constitution alignment (UI-FIL-001):** The feature reuses existing Filament widgets, tables, detail sections, alerts, tabs, and shared UI primitives. It should strengthen semantic emphasis through existing components and shared mappings, not through page-local markup or a new local status language.

**Constitution alignment (UI-NAMING-001):** The target objects are operations summary buckets, operation rows, run detail labels, and notification or entry-point copy. `Needs follow-up` may remain as an umbrella concept, but operator-facing copy MUST differentiate the two problem classes it currently mixes: terminal follow-up and active stale or stuck attention. Copy MUST not use a generic `blocked` or `needs follow-up` label for a mixed bucket unless the visible sub-class is also made explicit.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001):** Each changed surface keeps one primary inspect or drill-through model. Attention summaries use explicit problem-class destinations. Recent-operation tables keep row-click inspection. The operations hub remains a scan-first registry with explicit problem-class filtering. The canonical detail page remains the highest-trust detail surface. System failed and system stuck lists remain row-click-only registry surfaces. No new destructive action is introduced, and no exception to the action-surface contract is required.

**Constitution alignment (OPSURF-001):** Default-visible content must stay operator-first. Summary surfaces answer whether the operator is dealing with terminal follow-up or active stale attention. The operations hub answers which bucket the operator is in and what it means. Canonical detail answers what happened, whether the run is still active, and what to do next before showing diagnostics. System surfaces answer which platform-visible failure or stuck class is being surfaced without requiring the operator to infer it from raw context.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** Direct mapping from canonical run truth to UI remains preferred. The feature may add a thin derived problem-class split, but it must not create redundant truth across persisted records, presenters, summaries, notifications, and system surfaces. Tests MUST focus on operator-visible consequences: whether the same run tells the same story across surfaces and whether drill-through preserves that story.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract remains satisfied. No new View actions, no empty action groups, and no list-level destructive controls are introduced. Changed dashboard and monitoring surfaces remain inspection or drill-through surfaces only. UI-FIL-001 remains satisfied with no exemption.

**Constitution alignment (UX-001 — Layout & Information Architecture):** The canonical run detail page keeps one primary decision zone and must elevate stale or reconciled lifecycle truth inside that decision zone rather than only in side banners or lower sections. Summary surfaces keep operator priority order: problem class first, recency and diagnostics second. Existing tables continue to support search, sort, and filtering on core lifecycle dimensions.

### Functional Requirements

- **FR-178-001**: The system MUST treat canonical `OperationRun` lifecycle and freshness truth as authoritative for every summary, list, detail, and notification surface covered by this feature.
- **FR-178-002**: The same run MUST NOT appear as fresh normal activity on one covered surface and as likely stale, reconciled, or terminal problem truth on another covered surface at the same time.
- **FR-178-003**: Covered admin and system monitoring surfaces MUST use one shared derived lifecycle interpretation that distinguishes at least `fresh_active`, `likely_stale`, `reconciled_failed`, and `terminal_normal` without introducing a new persisted state model.
- **FR-178-004**: Reconciliation behavior and system stuck monitoring MUST remain semantically aligned so stale runs do not disappear from operator truth once they are auto-reconciled.
- **FR-178-005**: Automatically reconciled stale runs MUST remain semantically discoverable for operators on admin monitoring or system monitoring surfaces within one navigation step.
- **FR-178-006**: Bulk operation progress surfaces MUST refresh while relevant active runs exist and MUST stop presenting a run as active once canonical truth becomes terminal or reconciled.
- **FR-178-007**: Bulk operation progress surfaces MUST remove or reclassify terminal or reconciled runs within one refresh cycle even when no new enqueue event occurs.
- **FR-178-008**: Recent Operations surfaces on tenant and workspace pages MUST distinguish fresh active runs, likely stale active runs, and terminal follow-up runs rather than flattening them into generic recency.
- **FR-178-009**: Tenant and workspace attention surfaces MUST separate terminal follow-up from active stale or stuck attention instead of mixing them into one undifferentiated bucket.
- **FR-178-010**: The operations hub MUST expose an explicit monitoring view, filter, or tab for active but likely stale runs and an explicit view, filter, or tab for terminal follow-up runs.
- **FR-178-011**: Dashboard, attention, KPI, and recent-operation drill-throughs into the operations hub MUST preserve the originating problem class in visible destination framing.
- **FR-178-012**: The canonical run detail page MUST present stale, reconciled, and terminal-problem lifecycle truth inside the primary decision zone rather than only in secondary banners, side panels, or lower diagnostic sections.
- **FR-178-013**: For likely stale and reconciled runs, the primary decision zone MUST answer whether the run is still active, whether automatic reconciliation already happened, and what the primary next step is.
- **FR-178-014**: Local summary and progress surfaces MUST reuse centralized status, outcome, freshness, and problem-class semantics rather than page-local mappings.
- **FR-178-015**: Notification and in-app entry-point language MUST NOT frame a run more calmly than its current lifecycle or freshness truth.
- **FR-178-016**: Cross-links from dashboard KPIs, attention surfaces, recent operations, and notifications MUST land on destination surfaces that visibly confirm the same problem class that initiated the navigation.
- **FR-178-017**: The feature MUST use the existing `OperationRun`, status, outcome, freshness, and reconciliation model without introducing a schema migration, a new persisted lifecycle artifact, or an enum rewrite.
- **FR-178-018**: Run-type differences MAY preserve deeper artifact truth, but they MUST NOT change the base lifecycle answers of fresh active, likely stale, reconciled, or terminal follow-up.
- **FR-178-019**: Regression coverage MUST prove that the same seeded runs are classified consistently across tenant dashboard, workspace overview, operations hub, canonical run detail, and system failed or stuck surfaces.
- **FR-178-020**: Regression coverage MUST prove bulk-progress freshness, reconciliation visibility, drill-through continuity, and decision-zone emphasis for stale or reconciled runs.

## UI Action Matrix *(mandatory when Filament is changed)*

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard operations attention | `/admin/t/{tenant}` dashboard | none | Explicit problem-class CTA per bucket | none | none | Existing healthy fallback remains read-only reassurance only when no operations issue exists | n/a | n/a | no new audit behavior | Summary surface only; must not render mixed problem buckets |
| Tenant dashboard recent operations | `/admin/t/{tenant}` dashboard | `Open operations` | Row click to canonical operation detail | none | none | Existing diagnostic empty state remains non-primary | n/a | n/a | no new audit behavior | Recency surface; no destructive actions |
| Workspace operations attention | `/admin` workspace overview | none | Explicit problem-class CTA per bucket | none | none | Existing healthy fallback remains read-only reassurance only when no operations issue exists | n/a | n/a | no new audit behavior | Summary surface only; must not render mixed problem buckets |
| Workspace recent operations | `/admin` workspace overview | `Open operations` | Row click to canonical operation detail | none | none | Existing diagnostic empty state remains non-primary | n/a | n/a | no new audit behavior | Recency surface; no destructive actions |
| Operations hub | `/admin/operations` | Filter or tab controls only; no new destructive actions | Full-row click to canonical operation detail | none | none | Existing empty state remains explanatory and filter-aware | n/a | n/a | no new audit behavior | Scan-first registry surface; problem-class filters must align with summary entry points |
| Canonical operation detail | `/admin/operations/{run}` | `Back to operations` plus existing related navigation only | n/a | n/a | n/a | n/a | Existing related navigation only; no new destructive action introduced by this spec | n/a | no new audit behavior | Decision-zone truth is the hardening target |
| System failed operations | `/system/ops/failures` | `Show all operations` | Full-row click to system operation detail | none | none | `Show all operations` | n/a | n/a | no new audit behavior | Must confirm terminal-problem semantics, not generic follow-up |
| System stuck operations | `/system/ops/stuck` | `Show all operations` | Full-row click to system operation detail | none | none | `Show all operations` | n/a | n/a | no new audit behavior | Must preserve stale or reconciled visibility for platform operators |

### Key Entities *(include if feature involves data)*

- **Operation Run**: The canonical operational record whose status, outcome, freshness, and reconciliation context define the authoritative lifecycle truth.
- **Freshness State**: The derived lifecycle interpretation that distinguishes fresh active work, likely stale work, reconciled failure, and normal terminal completion without adding new persisted state.
- **Problem Class**: The operator-facing split between terminal follow-up and active stale or stuck attention, derived from existing lifecycle truth and used to align summary surfaces and drill-throughs.
- **Drill-through Contract**: The promise that a summary count, notification, or attention label can be visibly rediscovered on the destination surface it opens.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-178-001**: In covered regression scenarios, 100% of runs seeded as `likely_stale` are shown as stale or otherwise problematic on every covered summary and monitoring surface, and 0 are shown as unremarkable fresh activity.
- **SC-178-002**: In covered regression scenarios, 100% of automatically reconciled stale runs remain semantically recoverable for operators through admin monitoring or system monitoring within one navigation step.
- **SC-178-003**: In covered freshness regression scenarios, local progress surfaces stop showing terminal or reconciled runs as active within one refresh cycle and without requiring a new enqueue event.
- **SC-178-004**: In covered navigation regression scenarios, 100% of dashboard, attention, recent-operation, and notification drill-throughs land on destinations whose visible framing matches the originating problem class.
- **SC-178-005**: In operator review on seeded scenarios, an operator can determine within 10 seconds whether the run is fresh active, likely stale, reconciled, or terminal follow-up from every covered entry surface.
- **SC-178-006**: The feature ships without a schema migration, a new persisted lifecycle artifact, or a new status or outcome family.

## Assumptions

- Existing lifecycle freshness and reconciliation semantics from the operation lifecycle guarantees work remain the authoritative base truth for this hardening slice.
- Existing run-detail decision-zone structure remains the correct place to elevate stale and reconciled lifecycle truth.
- Existing tenant and workspace dashboard truth alignment work remains the baseline grammar for admin-plane summary surfaces.
- Existing system operations surface alignment remains the baseline interaction model for `/system/ops/failures` and `/system/ops/stuck`.

## Non-Goals

- Introducing tenant-admin retry or cancel capabilities
- Rebuilding the operations domain, run schema, or lifecycle engine
- Adding a new persisted problem-state model, enum rewrite, or schema migration
- Redesigning all notification behavior across the product
- Performing deep non-governance result-quality analysis for every run type
- Replacing run-type-specific artifact truth with a uniform artifact model

## Dependencies

- Existing operations auto-refresh behavior and active-run polling patterns
- Existing operation lifecycle guarantees, freshness thresholds, and reconciliation behavior
- Existing canonical run detail hierarchy and decision-zone structure
- Existing tenant dashboard and workspace overview truth-alignment semantics
- Existing system operations surface alignment for row-click-only platform monitoring pages

## Risks

- If stale thresholds are too aggressive, legitimate long-running work could be surfaced as stale too early.
- If summary and monitoring surfaces share labels but not the same underlying filter meaning, operators will continue to mistrust drill-throughs.
- If reconciled stale visibility is over-corrected without hierarchy, system surfaces could become noisy instead of trustworthy.
- If local progress polling is too eager, the product could gain freshness at the cost of unnecessary load.

## Definition of Done

Spec 178 is complete when:

- BulkOperationProgress no longer leaves trust-damaging stale residue that keeps terminal or reconciled runs looking active.
- stale or stuck semantics are consistent between lifecycle reconciliation, tenant and workspace summaries, the operations hub, canonical run detail, and system stuck or failure surfaces.
- tenant and workspace summary surfaces visibly separate terminal problem runs from active stale or stuck runs.
- the operations hub no longer distorts dashboard semantics through mixed or misleading tabs, filters, or bucket names.
- the canonical run detail page prioritizes stale or reconciled lifecycle truth inside the primary decision zone.
- cross-surface links preserve the same operator-visible problem class from origin to destination.
- focused regression coverage proves truth alignment, stale visibility, drill-through continuity, and progress freshness.

## Summary

This feature is a late-foundation hardening slice for the operations domain. The underlying lifecycle model is already strong: `OperationRun` is canonical, status and outcome are separated, stale reconciliation exists, system stuck surfaces exist, and canonical run detail already owns the deepest operational truth. The remaining problem is not missing architecture; it is trust drift between surfaces that summarize or relabel that truth.

Spec 178 closes that gap by making every covered surface tell the same story about whether a run is still active, likely stale, already reconciled, or terminal and in need of follow-up. It keeps the model narrow by reusing existing lifecycle and freshness truth, then aligning summaries, live progress, drill-throughs, and decision-zone emphasis so operators do not have to reconcile conflicting screens by hand.