TenantAtlas/specs/232-operation-run-link-contract/spec.md

Feature Specification: Operation Run Link Contract Enforcement

Feature Branch: 232-operation-run-link-contract
Created: 2026-04-23
Status: Draft
Input: User description: "schau in spec-candidate und roadmap rein und wähle das nächste sinnvolle spec"

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: Platform-owned admin and system surfaces still emit OperationRun collection and detail links through raw route assembly instead of the shared helper families, so the same canonical operations destinations have two parallel generation paths.
• Today's failure: Operators can reach the right pages through URLs that ignore tenant-prefilter or plane semantics, while contributors can keep adding raw operation routes in shared UI code without tripping a contract failure.
• User-visible improvement: Operation links behave consistently across dashboards, resources, monitoring pages, and shared related-navigation so operators land in the canonical destination with the expected plane and scope continuity.
• Smallest enterprise-capable version: Inventory all platform-owned operation collection/detail link producers, migrate raw admin-plane producers to OperationRunLinks, verify already-helper-backed system producers stay on SystemOperationRunLinks, record the narrow allowlisted exceptions, and add one automated guard that blocks new raw bypasses.
• Explicit non-goals: No operations IA redesign, no page-content rewrite, no status-semantics change, no new tenant-specific operations route family, and no platform-wide routing cleanup beyond OperationRun collection/detail links.
• Permanent complexity imported: One explicit allowlist for legitimate infrastructure-only exceptions, narrow regression coverage for admin-plane and system-plane link producers, and small helper-contract extensions only if current canonical context parameters are incomplete.
• Why now: Governance & Architecture Hardening is the active roadmap block, and the 2026-04-22 drift audit identified this as the first high-leverage contract-enforcement slice before more operations surfaces or navigation retrofits land.
• Why not local: The drift exists across shared navigation and multiple platform-owned surfaces. A one-off fix on one widget or resource would leave the same contract bypass available everywhere else.
• Approval class: Cleanup
• Red flags triggered: Cross-cutting interaction-class scope and repository guardrail addition. Defense: the helper families already exist, the feature only makes them mandatory on platform-owned paths, and the guard stays bounded to explicit allowlisted exceptions instead of introducing a new framework.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 2 | Produktnähe: 1 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace + canonical-view + system
• Primary Routes:
  • /admin/operations
  • /admin/operations/{run}
  • /system/ops/runs
  • /system/ops/runs/{run}
  • Existing platform-owned source surfaces that drill into those canonical destinations, including tenant recency widgets, inventory coverage follow-up links, review-pack operation links, panel navigation shortcuts, and shared related-navigation builders
• Data Ownership:
  • No new persisted entity or ownership model is introduced.
  • operation_runs remain the existing operational source of truth, tenant-owned in the admin plane with workspace-scoped canonical viewing rules and platform-plane visibility through existing system monitoring surfaces.
  • Workspace- or system-page filter state remains derived navigation state only; this feature does not persist copied link state or introduce a second run-navigation record.
• RBAC:
  • Admin-plane monitoring links continue to require workspace membership; tenant-linked destinations continue to enforce tenant entitlement and existing operations-view capabilities server-side.
  • System-plane monitoring links continue to require authenticated platform users with existing system operations access.
  • Cross-plane access remains deny-as-not-found; this feature does not introduce new capabilities or raw capability strings.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Admin-plane collection links may preserve the active entitled tenant through the canonical OperationRunLinks collection contract. Admin-plane run detail remains record-authoritative and may carry canonical navigation context, but must not invent a tenant-specific duplicate detail route. System-plane links never inherit tenant-context filters from /admin.
• Explicit entitlement checks preventing cross-tenant leakage: Helper-generated links may carry only entitled tenant/query context; destination pages re-check workspace membership, tenant entitlement, and plane-specific access before rendering. A link from a covered surface must never make a foreign-tenant run or system route newly observable.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): navigation, action links, related links, deep links
• Systems touched: admin monitoring surfaces, system operations surfaces, shared related-navigation builders, panel shortcuts, and tenant/workspace drill-through links from recency and evidence-oriented surfaces
• Existing pattern(s) to extend: canonical operation link helpers, canonical navigation context propagation, and existing operations row-click/detail conventions
• Shared contract / presenter / builder / renderer to reuse: App\Support\OperationRunLinks, App\Support\System\SystemOperationRunLinks, and App\Support\Navigation\CanonicalNavigationContext
• Why the existing shared path is sufficient or insufficient: The shared path is already sufficient for collection/detail labels, tenant-prefilter continuity, active-tab/problem-class query semantics, and plane separation. The current gap is not missing capability but incomplete adoption where raw route('admin.operations...') or direct system page URLs still bypass the contract.
• Allowed deviation and why: Bounded infrastructure-only exceptions may remain when the producer cannot depend on the helper family without introducing the wrong runtime dependency or hiding a deliberate redirect contract. Every retained exception must be explicit and allowlisted.
• Consistency impact: Operations / Operation nouns, Open operations / Open operation labels, admin versus system plane routing, tenant-prefilter continuity, canonical back-link behavior, and shared related-link structure must stay aligned across all covered producers.
• Review focus: Reviewers must verify that new or changed platform-owned operation links use the correct helper family for their plane and that no new raw collection/detail route assembly appears outside the explicit allowlist.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Use this section to classify UI and surface risk once. If the feature does not change an operator-facing surface, write N/A - no operator-facing surface change here and do not invent duplicate prose in the downstream surface tables.

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Admin monitoring collection/detail link contract enforcement	yes	Native Filament + shared helpers	navigation / related links	table, detail header, linked widgets	no	Destination pages stay the same; only link generation is standardized
System operations collection/detail link contract enforcement	yes	Native Filament + shared helpers	navigation / related links	table, detail header	no	Destination pages stay the same; plane separation becomes explicit
Shared operation drill-through links from tenant/workspace surfaces	yes	Native Filament widgets/resources + shared helpers	navigation	widget, table cell, infolist/detail supporting links	no	Low-impact UI change; same destinations, stricter continuity semantics

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

If this feature adds or materially changes an operator-facing surface, fill out one row per affected surface. This role is orthogonal to the Action Surface Class / Surface Type below. Reuse the exact surface names and classifications from the UI / Surface Guardrail Impact section above.

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Admin monitoring collection and run detail	Secondary Context Surface	Open canonical monitoring after a tenant/workspace surface signals follow-up	Correct destination family, preserved tenant scope when valid, stable canonical operation identity	Full run diagnostics, raw context, related artifacts	Secondary because the decision to inspect happens on the source surface; monitoring remains the canonical context surface for follow-up and diagnosis	Follows existing dashboard/resource-to-monitoring workflow instead of creating duplicate run pages	Removes operator guesswork about which operations page and which scope a link should open
System operations collection and run detail	Secondary Context Surface	Open platform-plane run monitoring from system runbooks or system registries	Correct system destination, preserved platform plane, stable run identity	Full system run diagnostics and runbook context	Secondary because it supports platform triage after a runbook or system list already framed the operator task	Follows existing /system triage workflow and keeps system links out of /admin	Removes plane confusion and manual route reconstruction for platform operators

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

If this feature adds or materially changes an operator-facing list, detail, queue, audit, config, or report surface, fill out one row per affected surface. Declare the broad Action Surface Class first, then the detailed Surface Type. Keep this table in sync with the Decision-First Surface Role section above and avoid renaming the same surface a second time.

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	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 / Justification
Admin monitoring collection	Read-only Registry / Report	Canonical monitoring registry	Open operation detail or inspect filtered run history	Full-row click or canonical helper-generated open link	required	Header/context filters and source-surface link affordances only	No new destructive placement; existing detail-only interventions remain unchanged	/admin/operations	/admin/operations/{run}	Workspace scope, optional entitled tenant filter, canonical navigation context	Operations / Operation	The operator can tell they are entering canonical admin monitoring and whether tenant context was preserved	none
Admin operation run detail	Canonical detail	Diagnostic run detail	Inspect one run without losing canonical plane semantics	Direct route-resolved detail page	forbidden	Related links and back-navigation remain secondary in the header/body	No new destructive actions in this feature	/admin/operations	/admin/operations/{run}	Workspace scope, entitled tenant context if present, run identity	Operations / Operation	The canonical run identity and plane are obvious without interpreting source-surface hacks	none
System operations collection	Read-only Registry / Report	Platform monitoring registry	Open system run detail	Full-row click or canonical helper-generated open link	required	Header filters or runbook follow-up only	Existing system interventions remain separately governed	/system/ops/runs	/system/ops/runs/{run}	Platform scope only	Operations / Operation	The operator can tell they are staying in the system plane	none
System run detail	Detail / Decision	Platform run triage detail	Inspect one platform run in the correct plane	Direct route-resolved detail page	forbidden	Header/context links only	Existing system-detail interventions remain separately governed	/system/ops/runs	/system/ops/runs/{run}	Platform scope, run identity, system context	Operations / Operation	The canonical system-run destination is explicit and not silently downgraded to admin monitoring	none

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. The contract MUST show how one governance case or operator task becomes decidable without unnecessary cross-page reconstruction.

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Admin monitoring collection and run detail	Workspace operator	Follow a source-surface signal into canonical operation history or one canonical run detail	Registry + detail	Did I land on the right canonical operations surface with the right scope, and can I inspect the run from here?	Canonical collection/detail destination, run identity, workspace scope, entitled tenant continuity where applicable	Raw context payloads, error traces, and extended related links	lifecycle, outcome, problem class, scope continuity	No new mutation in this slice	Open operation, Open operations	None added by this feature
System operations collection and run detail	Platform operator	Follow runbook or system registry context into platform-plane run history or one system run detail	Registry + detail	Am I staying in the system plane, and am I opening the correct run history/detail surface?	Canonical system destination, run identity, platform scope	Raw run context, failure payloads, runbook lineage	lifecycle, outcome, platform scope	No new mutation in this slice	Open operation, Open operations	None added by this feature

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?: no
• Current operator problem: Covered surfaces can bypass the existing canonical operation-link contract, which makes plane and scope continuity drift across the same operations destinations.
• Existing structure is insufficient because: The helpers exist but are not enforced. Without one explicit enforcement slice and guardrail, every new platform-owned surface can keep choosing local route assembly.
• Narrowest correct implementation: Reuse the existing helper families, migrate all in-scope producers, and add one bounded allowlist guard instead of inventing a broader routing framework or new navigation model.
• Ownership cost: Small ongoing allowlist review, targeted regression maintenance, and occasional helper extensions when new canonical query semantics are introduced.
• Alternative intentionally rejected: A one-off cleanup of currently known raw routes without a guardrail was rejected because it would not stop the same drift from reappearing on the next surface.
• Release truth: current-release contract enforcement and cleanup, not future-platform preparation

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

For docs-only or template-only changes, state concise N/A or none. For runtime- or test-affecting work, classification MUST follow the proving purpose of the change rather than the file path or folder name.

• Test purpose / classification: Feature
• Validation lane(s): fast-feedback + confidence
• Why this classification and these lanes are sufficient: This change is proved by end-to-end URL generation and plane/scope outcomes on real admin/system surfaces, not by isolated string helpers alone. Fast-feedback covers representative admin/system surfaces and the guard. Confidence reruns the broader operations link-contract coverage already present in the monitoring family.
• New or expanded test families: Extend existing canonical run-link coverage for admin and system surfaces; add one focused guard test that blocks new raw platform-owned operation routes outside the allowlist.
• Fixture / helper cost impact: Minimal. Existing OperationRun factories, workspace/tenant membership helpers, and platform-user fixtures are sufficient.
• Heavy-family visibility / justification: none
• Special surface test profile: monitoring-state-page
• Standard-native relief or required special coverage: Requires shared-link contract coverage on representative widgets/resources plus one repository guard check; no browser or heavy-governance suite is needed.
• Reviewer handoff: Reviewers must confirm that each migrated producer emits helper-generated URLs for the correct plane, that allowlisted exceptions are explicitly justified, and that the guard pattern cannot be trivially bypassed.
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/CanonicalViewRunLinksTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php tests/Feature/Filament/InventoryCoverageRunContinuityTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php tests/Feature/078/RelatedLinksOnDetailTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php tests/Feature/System/Spec113/AuthorizationSemanticsTest.php tests/Feature/Guards/OperationRunLinkContractGuardTest.php

User Scenarios & Testing (mandatory)

User Story 1 - Follow Admin Operations Links Consistently (Priority: P1)

As a workspace operator, I want platform-owned admin surfaces to open canonical operations collection/detail links through one shared contract so that tenant-prefilter and run-detail continuity are consistent.

Why this priority: This is the direct operator-facing path. If admin-plane drill-through links remain inconsistent, the canonical monitoring experience stays fragile even when the destination pages themselves are correct.

Independent Test: Can be fully tested by opening operations links from covered tenant/workspace surfaces such as recency widgets, inventory coverage, and review-pack detail and confirming that the links land on the canonical admin collection/detail destinations with the expected scope continuity.

Acceptance Scenarios:

1. Given an active entitled tenant context, When an operator opens operations from a covered admin-plane surface, Then the link resolves to /admin/operations or /admin/operations/{run} with the expected tenant/context continuity and without inventing a duplicate route family.
2. Given no tenant context is active, When a covered admin-plane surface links to operations, Then it opens workspace-wide admin monitoring rather than inventing or leaking tenant scope.
3. Given a run belongs to a tenant the actor is not entitled to inspect, When the actor requests the destination, Then the destination still resolves as deny-as-not-found.

---

User Story 2 - Keep System-Plane Run Links in the System Plane (Priority: P1)

As a platform operator, I want system run lists and runbooks to open canonical system operations URLs so that platform monitoring never silently routes me through the admin plane.

Why this priority: Plane correctness is a core trust requirement. A system operator following a run link to the wrong plane is both confusing and authorization-sensitive.

Independent Test: Can be fully tested by opening run history and run detail from covered /system surfaces and confirming that the destination remains /system/ops/runs or /system/ops/runs/{run} for platform users while tenant/admin users still cannot access those routes.

Acceptance Scenarios:

1. Given a system-plane list or follow-up link, When the platform operator opens a run, Then the URL is /system/ops/runs/{run} rather than an admin-plane monitoring route.
2. Given a system-plane collection link, When the platform operator opens history, Then the URL is /system/ops/runs.
3. Given a tenant/admin user session, When that user requests a system-plane destination, Then the response remains deny-as-not-found.

---

User Story 3 - Prevent New Raw Operation-Link Bypasses (Priority: P2)

As a maintainer, I want a guardrail that fails when platform-owned UI introduces new raw operation routes outside allowlisted exceptions so that the contract stays enforced after cleanup.

Why this priority: The cleanup only holds if the next contributor cannot quietly reintroduce the same drift on a new surface.

Independent Test: Can be fully tested by introducing a representative raw route bypass in a covered area, observing the guard fail, then moving the same producer to the helper family or explicit allowlist and observing the guard pass.

Acceptance Scenarios:

1. Given a new platform-owned UI producer assembles route('admin.operations...') or direct system page URLs outside the allowlist, When the guard runs, Then the build fails with an actionable message.
2. Given an infrastructure-only exception is explicitly allowlisted, When the guard runs, Then it passes without forcing fake helper usage.
3. Given a new covered surface needs an additional canonical query semantic, When the contributor extends the helper family, Then the surface adopts the helper rather than adding a second local route pattern.

Edge Cases

• A source surface has stale or absent tenant context; the admin collection link must degrade to workspace-wide canonical monitoring rather than carrying invalid tenant state.
• A source surface wants to prefilter by problem class or active tab; query semantics must be emitted through the helper contract only, not handwritten per surface.
• A run detail link is built from a tenant surface but the run belongs to a tenant the current actor can no longer access; opening the destination must still fail as 404.
• A boot-time panel item or controller redirect cannot safely depend on view-context objects; if it remains raw, it must be explicitly allowlisted and justified.
• System-plane and admin-plane links for the same run ID must never resolve through the wrong plane by helper accident or local override.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no new mutation workflow, and no new OperationRun type. It standardizes link generation to already-shipped canonical operations destinations and must therefore make tenant isolation, plane separation, shared-link reuse, and regression coverage explicit.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature does not introduce new persistence, a new abstraction family, or new states. It deliberately reuses the existing helper families and adds only the narrowest enforcement mechanism needed to stop repeated drift on a current-release operator path.

Constitution alignment (XCUT-001): This is a cross-cutting navigation and action-link feature. The shared path is OperationRunLinks for the admin plane and SystemOperationRunLinks for the system plane, with CanonicalNavigationContext carrying canonical admin query state where needed. Any retained raw-route exception must be explicit, justified, and reviewable.

Constitution alignment (TEST-GOV-001): The proving purpose is runtime link behavior on real admin/system surfaces plus one repository guard. Feature tests and a focused guard are the narrowest sufficient proof. Existing factories and membership fixtures remain enough, and no heavy-governance or browser family is justified.

Constitution alignment (OPS-UX): Not applicable. This feature does not create, start, or mutate OperationRun records. Existing operations destinations remain the canonical Ops-UX surfaces and keep their current service-owned lifecycle semantics.

Constitution alignment (RBAC-UX): The feature spans the admin /admin plane and the platform /system plane. Cross-plane access remains 404. Admin-plane destinations continue to enforce workspace membership first and tenant entitlement when the run is tenant-bound. System-plane destinations continue to enforce platform-user access only. The feature must add at least one positive and one negative authorization-path regression covering the affected link destinations.

Constitution alignment (OPS-EX-AUTH-001): Not applicable. No authentication handshake behavior changes.

Constitution alignment (BADGE-001): Not applicable. No badge semantics are introduced or changed.

Constitution alignment (UI-FIL-001): The affected surfaces remain native Filament pages, widgets, and resources. No local replacement markup is needed. Semantic emphasis stays in existing tables, related-link areas, and header affordances while the destination URLs are delegated to the shared helper families.

Constitution alignment (UI-NAMING-001): The target object is the canonical operation destination. Operator verbs remain Open operations, Open operation, and View in Operations where those labels are already defined by the helper family. Source/domain disambiguation is only plane-based: admin-plane links open admin monitoring, system-plane links open system monitoring.

Constitution alignment (DECIDE-001): The affected surfaces are Secondary Context Surfaces. Their responsibility is not to create a new decision queue but to preserve a calm, predictable path from source surfaces into canonical monitoring without forcing operators to reconstruct plane or scope by hand.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): This feature does not add new visible row or header actions. It preserves one primary inspect/open model per affected surface, keeps pure navigation in row click or supporting related links, leaves destructive actions where existing destinations already govern them, and does not introduce a second operations route family.

Constitution alignment (ACTSURF-001 - action hierarchy): No new action hierarchy is introduced. Navigation remains separate from mutation, existing detail-only interventions remain where they are, and the feature does not turn route cleanup into a new action chrome pattern.

Constitution alignment (OPSURF-001): The default-visible operator experience remains operator-first because the change is to destination continuity, not content density. Raw route tokens and local path assembly must not leak into surface-specific logic. Diagnostics remain on the destination detail pages, not in the link producers.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): No new UI-semantic or presenter layer is introduced. Direct helper reuse is preferred over another interpretation layer, and tests focus on business consequences: correct plane, correct destination, correct scope continuity, and blocked drift.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract remains satisfied. Each affected surface keeps exactly one primary inspect/open model, redundant View actions are not introduced by this feature, empty placeholder groups remain forbidden, and destructive actions remain governed by the existing destination pages. UI-FIL-001 is satisfied with no exception.

Constitution alignment (UX-001 — Layout & Information Architecture): Existing operations pages, widgets, and resources keep their current layouts, infolists, table search/sort/filter behavior, and empty-state structure. No layout exemption is needed because this slice changes destination generation only.

Functional Requirements

• FR-232-001: The system MUST treat App\Support\OperationRunLinks as the canonical admin-plane generator for platform-owned links to /admin/operations and /admin/operations/{run}.
• FR-232-002: The system MUST treat App\Support\System\SystemOperationRunLinks as the canonical system-plane generator for platform-owned links to /system/ops/runs and /system/ops/runs/{run}.
• FR-232-003: The first implementation slice MUST inventory all platform-owned collection/detail link producers for OperationRun destinations and classify each producer as migrated, verified helper-backed, or explicit exception.
• FR-232-004: Covered admin-plane producers MUST stop assembling raw route('admin.operations.index') or route('admin.operations.view') URLs locally.
• FR-232-005: Covered system-plane producers MUST remain on SystemOperationRunLinks, and any direct system operations page URL assembly outside explicit allowlisted infrastructure-only cases MUST be removed.
• FR-232-006: Admin-plane collection links originating from tenant-aware surfaces MUST preserve only valid canonical context supported by OperationRunLinks, including entitled tenant prefilter, active tab, problem class, and canonical navigation context when applicable.
• FR-232-007: Admin-plane run-detail links MUST use the canonical admin detail helper and MUST NOT invent tenant-prefixed or surface-specific duplicate detail routes.
• FR-232-008: System-plane links MUST never route platform operators to admin-plane monitoring pages as the default destination for system operations history or detail.
• FR-232-009: The helper contract MUST remain the only source for the canonical operator-facing nouns and open labels used by covered admin-plane operation links.
• FR-232-010: Existing admin-plane and system-plane destination pages MUST keep their current authorization and plane semantics; this feature MUST NOT widen access or weaken 404 versus 403 behavior.
• FR-232-011: Explicit exceptions to helper-family reuse MUST be documented, narrowly scoped, and justified by infrastructure or bootstrapping constraints rather than convenience.
• FR-232-012: The repository MUST provide one automated guard that fails when new platform-owned operation collection/detail links bypass the canonical helper families outside the explicit allowlist.
• FR-232-013: The guard MUST target platform-owned UI and shared navigation layers only and MUST NOT force helper use inside the helper classes themselves, unrelated tests, or non-operator infrastructure code outside the declared boundary.
• FR-232-014: Shared navigation builders that produce operation_run links, including audit- or related-navigation paths in scope, MUST use the canonical helper family for the destination plane instead of local route assembly.
• FR-232-015: Representative tenant/workspace source surfaces in scope, including at least one tenant recency surface, one evidence- or review-oriented surface, and one shared resolver path, MUST be migrated in the first rollout.
• FR-232-016: Regression coverage MUST prove correct admin-plane destination continuity, correct system-plane destination continuity, and guard failure on a representative bypass.
• FR-232-017: The feature MUST NOT introduce a new operations collection/detail route family, a second link presenter stack, or a separate tenant-local operations page.

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), whether the mutation writes an audit log, and any exemption or exception used.

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
Admin Operations index	apps/platform/app/Filament/Pages/Monitoring/Operations.php	Existing filter/context actions only	Full-row click and helper-generated incoming links to the canonical list	none added by this feature	none added by this feature	Existing clear-filter or empty-state CTA unchanged	n/a	n/a	no new audit behavior	Link contract only; no redundant View action added
Admin operation run detail	apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php	Existing back/refresh/context actions only	Direct route-resolved detail plus helper-generated incoming links	none added by this feature	none	n/a	Existing header navigation and related links only	n/a	no new audit behavior	Incoming links and related links must use the canonical admin helper
System operations runs	apps/platform/app/Filament/System/Pages/Ops/Runs.php	Existing filters or context actions only	Full-row click and helper-generated incoming links	none added by this feature	none added by this feature	Existing clear-filter CTA unchanged	n/a	n/a	no new audit behavior	Collection destination must stay in system plane
System operation run detail	apps/platform/app/Filament/System/Pages/Ops/ViewRun.php	Existing refresh/contextual actions only	Direct route-resolved detail plus helper-generated incoming links	none added by this feature	none	n/a	Existing detail actions unchanged	n/a	no new audit behavior	Incoming links must use the canonical system helper

Key Entities (include if feature involves data)

• Admin Operation Link Contract: The canonical helper-generated admin monitoring destination, including collection/detail route choice and any allowed tenant- or navigation-context query semantics.
• System Operation Link Contract: The canonical helper-generated system monitoring destination for platform-plane run history and run detail.
• Allowlisted Link Producer Exception: A narrowly justified infrastructure-only producer that is explicitly permitted to bypass the helper family without becoming a general precedent for platform-owned UI code.

Success Criteria (mandatory)

Measurable Outcomes

• SC-232-001: In automated regression coverage, 100% of covered admin-plane operation links open the canonical admin collection or detail destination with the expected tenant/workspace continuity.
• SC-232-002: In automated regression coverage, 100% of covered system-plane operation links open /system/ops/runs or /system/ops/runs/{run}, and 0 covered system links fall back to admin-plane monitoring.
• SC-232-003: The guardrail fails on a representative raw-route bypass and passes only for explicitly allowlisted exceptions in automated review coverage.
• SC-232-004: Negative authorization coverage confirms that covered links do not convert foreign-tenant or wrong-plane destinations into successful opens for unauthorized actors.

Assumptions

• OperationRunLinks and SystemOperationRunLinks remain the chosen canonical helper families for this release rather than being replaced by a broader navigation framework.
• Existing admin-plane and system-plane operations destination pages already enforce the correct authorization and scope semantics; this feature fixes link production, not destination legitimacy.
• The known drift is concentrated in platform-owned UI and shared navigation layers rather than external integrations or public API contracts.

Non-Goals

• Redesigning operations list/detail layout, action hierarchy, or lifecycle semantics
• Reworking failures or stuck route families into a broader system monitoring link framework beyond the canonical runs collection/detail seam
• Cleaning every historical test literal or non-operator infrastructure route string unrelated to platform-owned UI or shared navigation layers