TenantAtlas/specs/170-system-operations-surface-alignment/research.md

Research: System Operations Surface Alignment

Decision 1: Keep the three system list pages as read-only registry surfaces

• Decision: Runs, Failures, and Stuck stay classified as ReadOnlyRegistryReport surfaces with recordUrl() full-row navigation as the only primary inspect model.
• Rationale: The pages already declare ActionSurfaceType::ReadOnlyRegistryReport, already use clickable rows, and the constitution requires exactly one primary inspect/open model for registry surfaces. Inline triage on these lists is the specific behavior drift the spec is correcting.
• Alternatives considered: Reclassify the lists as queue/review surfaces. Rejected because the pages are scan-first status registers split by run state, not in-place decision queues.

Decision 2: Keep triage ownership on the existing ViewRun page

• Decision: Retry, Cancel, and Mark investigated remain on app/Filament/System/Pages/Ops/ViewRun.php and are removed from the list rows.
• Rationale: The detail page already exposes all three actions, already loads tenant and workspace, and already provides the surrounding operational context the operator needs before acting. Repo analysis of the operation-run detail surface confirms that the page is already the rich context owner for run truth and next steps.
• Alternatives considered: Add a new dedicated triage modal or keep one “safe” triage action inline on the lists. Rejected because both options preserve split ownership and weaken the single-entry operational model.

Decision 3: Reuse the existing triage service and links without abstraction changes

• Decision: OperationRunTriageService and SystemOperationRunLinks remain the canonical implementation path for retry/cancel/investigate and detail navigation.
• Rationale: The service already encapsulates retryability/cancelability rules, audit logging, OperationRunService lifecycle transitions, and triage context writes. This spec changes action placement, not domain behavior.
• Alternatives considered: Introduce a new presenter, coordinator, or list-specific triage wrapper. Rejected under ABSTR-001 and LAYER-001 because there is only one existing triage behavior and the current service already fits it.

Decision 4: Move behavior guards from “direct row triage” to “detail-owned triage”

• Decision: Update tests/Feature/Guards/ActionSurfaceContractTest.php and tests/Feature/System/Spec114/OpsTriageActionsTest.php so they assert row-click-only lists and detail-header triage ownership.
• Rationale: The constitution explicitly prioritizes rendered behavior over declaration. The current guard suite still encodes the old hybrid interaction model by expecting retry, cancel, and mark_investigated on all three list pages.
• Alternatives considered: Leave the existing guards untouched and only rely on declarations, or delete the guards. Rejected because that would preserve declaration-only conformance and remove the regression protection this slice is supposed to strengthen.

Decision 5: Absorb visible Operations naming into Spec 170 while keeping route stability explicit

• Decision: The changed system surfaces standardize their visible collection and singular nouns to Operations and Operation in navigation labels, headings, empty-state copy, and return links, while existing internal class names and /system/ops/runs route paths may remain stable for compatibility.
• Rationale: The constitution treats Operations as the canonical collection noun for run records. Leaving the changed system surfaces on Runs would keep the spec itself in conflict with the constitution.
• Alternatives considered: Defer naming to Spec 171. Rejected because it leaves a known constitution conflict inside the active slice.

Decision 6: Give every changed list surface one explicit CTA and the detail page one explicit return path

• Decision: The Operations list uses Go to runbooks as its single header and empty-state CTA. Failed operations and Stuck operations use Show all operations as their single header and empty-state CTA. The detail page exposes Show all operations as the canonical return path and keeps Go to runbooks as secondary navigation.
• Rationale: The constitution requires changed list surfaces to define explicit empty-state CTA behavior and requires a clear canonical navigation model. These CTAs stay navigation-only and do not reintroduce inline row clutter.
• Alternatives considered: Keep explanation-only empty states or add multiple list CTAs. Rejected because the first violates the constitution and the second weakens scanability.

Decision 7: No new API surface; document the route/UI contract explicitly

• Decision: Capture the expected route and interaction contract in a small OpenAPI-style YAML file under contracts/ even though the feature does not add a public JSON API.
• Rationale: The implementation change is route-driven and operator-visible. A route contract that records surface type, inspect affordance, action placement, and capability boundaries gives later tasks and reviews a concrete artifact without inventing a new backend API.
• Alternatives considered: Skip contracts/ entirely. Rejected because the planning workflow expects a concrete contract artifact, and this feature benefits from a machine-readable record of its operator-visible contract.