TenantAtlas/specs/123-operations-auto-refresh/spec.md

Feature Specification: Operations Auto-Refresh Pass

Feature Branch: [123-operations-auto-refresh]
Created: 2026-03-08
Status: Draft
Input: User description: "Conditional polling for tenantless operation run viewer and tenant review pack generation so active operations update live without manual refresh and stop refreshing once they reach a terminal state."

Spec Scope Fields (mandatory)

• Scope: canonical-view
• Primary Routes: /admin/operations/{run} for the tenantless canonical Monitoring run detail view; intentionally reusable tenant-scoped embedded TenantReviewPackCard widget surfaces (component-scoped, with no standalone route of their own)
• Data Ownership: existing tenant-owned OperationRun operational artifacts viewed through the canonical Monitoring route, plus existing tenant-owned ReviewPack generation records; no new ownership rules are introduced
• RBAC: existing workspace membership and tenant entitlement checks remain unchanged; the canonical Monitoring route must continue to enforce workspace access and tenant entitlement before revealing tenant-bound runs, and every tenant-scoped host surface that renders the review pack widget must continue to honor tenant membership plus review-pack capability checks

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: No new list filtering is introduced. The canonical route remains record-specific at /admin/operations/{run}. If a user opens a run from tenant context, the viewer shows only that requested run and does not broaden the query to other tenant records.
• Explicit entitlement checks preventing cross-tenant leakage: The tenantless Monitoring route must continue to authorize against the run workspace and, for tenant-bound runs, against the referenced tenant scope before rendering any record details. Any tenant-scoped host surface that renders the review pack widget must continue to rely on the active tenant context and existing review-pack view/manage capability checks.

User Scenarios & Testing (mandatory)

User Story 1 - Watch an active operation complete (Priority: P1)

An operator viewing an in-progress operation run can keep the page open and trust that status, progress, and final outcome will update on their own while the run remains active.

Why this priority: This is the primary trust gap called out in the request. Operations monitoring loses credibility when active work looks stale.

Independent Test: Start with an active operation run, open the tenantless run viewer, and confirm the displayed state updates automatically until the run reaches a terminal outcome without any manual refresh.

Acceptance Scenarios:

1. Given an operator is viewing an active operation run, When the run status changes while the page remains open, Then the viewer refreshes automatically within the polling window and shows the updated status.
2. Given an operator is viewing an active operation run, When the run reaches a terminal state, Then the viewer stops auto-refreshing and the terminal state remains stable on screen.

---

User Story 2 - Monitor review pack generation from the card (Priority: P2)

A user who starts tenant review pack generation can stay on the card and see progress or completion without manually refreshing the page.

Why this priority: Review pack generation is another asynchronous workflow where stale feedback weakens confidence, but it is secondary to the core operation run viewer.

Independent Test: Trigger review pack generation, keep the card visible, and confirm the card refreshes automatically while work is active and stops once generation completes or fails.

Acceptance Scenarios:

1. Given review pack generation is in progress, When the generation state changes, Then the card refreshes automatically within the polling window and reflects the latest state.
2. Given review pack generation has completed or failed, When the user keeps the page open, Then the card remains stable and no longer auto-refreshes.

---

User Story 3 - Avoid noisy refresh behavior on completed work (Priority: P3)

An admin revisiting completed work sees a stable terminal state rather than a screen that keeps refreshing after the outcome is already known.

Why this priority: Stopping refresh at the right time is necessary to preserve perceived quality and avoid unnecessary noise or load.

Independent Test: Open one completed operation run and one completed review pack result, and confirm neither surface resumes automatic refresh behavior.

Acceptance Scenarios:

1. Given a user opens a surface for work that is already in a terminal state, When the screen loads, Then the surface shows the terminal state without entering an active polling cycle.

Edge Cases

• If a run or generation completes between polling cycles, the next refresh must show the terminal state and stop further polling.
• If the surface loads with an unrecognized or missing status, it must default to non-polling behavior rather than refreshing indefinitely.
• If a single refresh attempt fails while the work is still active, the current visible state should remain stable and the next scheduled refresh may try again without duplicating terminal messaging.
• If a user opens the surface after the work has already finished, the terminal state must appear immediately and remain stable.

Requirements (mandatory)

Constitution alignment (required): This feature does not introduce new outbound integrations, new change operations, new scheduled work, or new operation types. It improves freshness on existing progress surfaces only. Contract registry entries, safety gates, tenant isolation rules, and audit behavior remain unchanged.

Constitution alignment (OPS-UX): This feature reuses existing long-running operation feedback behavior and only changes how often the progress surfaces refresh while work is active. Toast intent behavior, progress surfaces, and terminal notifications remain unchanged. Operation run status and outcome transitions remain service-owned, and this feature only reads those states to decide whether automatic refresh continues. Summary-count rules and scheduled/system-run behavior are unchanged. Regression coverage must confirm active-versus-terminal refresh behavior on the affected surfaces.

Constitution alignment (RBAC-UX): No authorization rules change. The same workspace and tenant entitlements that already control visibility continue to apply. The canonical Monitoring route remains deny-as-not-found for users not entitled to the workspace or referenced tenant scope, while the tenant review widget keeps its existing tenant membership and capability checks. This feature adds no new actions, no new mutations, and no new 403 or 404 semantics.

Constitution alignment (OPS-EX-AUTH-001): Not applicable to this feature because it does not modify authentication handshake behavior.

Constitution alignment (BADGE-001): Existing centralized status and outcome semantics remain the source of truth. Auto-refresh must continue to display those centralized meanings consistently after each refresh cycle.

Constitution alignment (Filament Action Surfaces): The action surface contract remains satisfied because this feature does not add, remove, or change any user-triggered actions. It adds passive refresh behavior only.

Constitution alignment (UX-001 — Layout & Information Architecture): Existing layouts, cards, and terminal-state presentations remain in place. The only UX change is passive refresh while work is active, and it must preserve a stable, non-noisy presentation.

Functional Requirements

• FR-001: The system MUST automatically refresh the tenantless operation run viewer while the displayed run is in an active, non-terminal state.
• FR-002: The system MUST automatically refresh the tenant review pack card while review pack generation is in progress.
• FR-003: The system MUST stop automatic refresh as soon as the displayed work reaches a terminal state, including successful completion, failure, cancellation, or any equivalent final outcome already recognized by the product.
• FR-004: The default automatic refresh interval MUST be 10 seconds unless the established shared polling standard used by comparable operation surfaces already defines a different interval for consistency.
• FR-005: The system MUST reuse the established conditional polling pattern already trusted on comparable operation-monitoring surfaces so that users experience consistent behavior.
• FR-006: The system MUST avoid indefinite refresh cycles for work that is already terminal, unknown, or no longer actively progressing.
• FR-007: The system MUST preserve visible state stability during automatic refresh so that operators do not experience distracting flicker, duplicate progress messaging, or noisy terminal transitions.
• FR-008: The feature MUST not change existing permissions, routes, operation ownership semantics, or backend state-transition rules.
• FR-009: Automated coverage MUST verify that active states enable refresh behavior and terminal states disable it for both affected surfaces.

UI Action Matrix (mandatory when Filament is changed)

This feature changes passive refresh behavior on existing admin surfaces but does not change the available actions.

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
Tenantless operation run viewer	Operations monitoring surface	No action changes in scope	Existing inspect flow unchanged	None changed	None changed	Unchanged	No action changes in scope	Not applicable	No change	Passive auto-refresh only; no new mutation or destructive action
Tenant review pack card	Tenant review workflow surface	No action changes in scope	Existing card visibility unchanged	No action changes in scope	None changed	Unchanged	Not applicable	Not applicable	No change	Passive auto-refresh only; generation actions and audit behavior remain as-is

Key Entities (include if feature involves data)

• Operation Run: A long-running unit of work whose status and outcome determine whether the tenantless viewer should continue refreshing.
• Tenant Review Pack Generation: A review-pack production lifecycle whose current state determines whether the tenant review card should continue refreshing.

Assumptions

• The product already defines which run and generation states are considered active versus terminal.
• An existing polling pattern already exists on comparable monitoring surfaces and can be reused without redesigning global behavior.
• Users viewing these surfaces already have permission to see the underlying operation or review pack status.

Dependencies

• Reliable persisted status semantics for operation runs and review pack generation.
• Existing conditional polling behavior used elsewhere in the product as the consistency baseline.
• Existing QA ability to observe one active example and one terminal example for each affected surface.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In manual QA, users observing an active operation run see the displayed state update automatically within 10 seconds of the persisted status changing, without manually refreshing the page.
• SC-002: In manual QA, users observing active review pack generation see the displayed state update automatically within 10 seconds of the persisted generation state changing, without manually refreshing the page.
• SC-003: In automated and manual verification, 100% of covered terminal-state examples on the affected surfaces stop automatic refresh after the terminal state is recognized.
• SC-004: During manual observation of at least three consecutive refresh cycles on each active surface, reviewers observe no excessive flicker, duplicate state messages, or unstable terminal-state rendering.