TenantAtlas/specs/328-operations-hub-decision-first-workbench-productization/spec.md

Feature Specification: Spec 328 - Operations Hub Decision-First Workbench Productization

Feature Branch: 328-operations-hub-decision-first-workbench-productization
Created: 2026-05-18
Status: Implemented / Validated
Type: Runtime UI productization / OperationRun workbench / execution-truth surface
Runtime posture: Narrow runtime UI implementation. Repo-based. No invented backend foundation.
Input: User-provided full Spec 328 draft.

Dependencies And Historical Context

Depends on:

• Spec 314 - Workspace Hub Navigation Context Contract.
• Spec 315 - Environment CTA Explicit Filter Contract.
• Spec 316 - Workspace Hub Clear Filter Contract.
• Spec 317 - Legacy Tenant / Environment Context Cleanup.
• Spec 318 - Admin Surface Scope & Shell Context Audit.
• Spec 319 - Environment-Owned Surface Routing & Shell Context Contract.
• Spec 320 - Workspace-Owned Analysis Surface Registration & Shell Cutover.
• Spec 321 - Alerts / Audit Log Environment Filter Contract Decision.
• Spec 322 - Browser No-Drift Regression Guard.
• Spec 325 - Screenshot-Anchored Strategic Target Images.
• Spec 326 - Customer Review Workspace v1 Productization.
• Spec 327 - Governance Inbox Decision-First Workbench Productization.

Repo truth adjustment: the user draft allowed /admin/operations or the existing canonical route. Current repository truth is admin.operations.index at /admin/workspaces/{workspace}/operations, generated through OperationRunLinks::index(). Spec 328 productizes that existing route, Operations Filament page, and OperationRunResource table. It must not create a new operations route, operation engine, queue backend, monitoring backend, or OperationRun status family.

Spec 325 target images are visual calibration only. They are not runtime truth for counts, metrics, actions, artifact links, RBAC, evidence, or health claims.

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

• Problem: Operations Hub is repo-real and execution-truth rich, but the default surface still reads as a monitoring landing plus chronological run table instead of a decision-first workbench that answers which operation needs attention now.
• Today's failure: Failed, blocked, partial, stale, or follow-up runs can compete visually with successful history and diagnostic table controls. Operators must infer reason, impact, affected environment, proof/artifact state, and safe next action from table rows, tabs, and run detail links.
• User-visible improvement: Operations responders get a focused workbench that prioritizes attention-needed OperationRuns, explains outcome/reason/impact, keeps progress truthful, shows proof availability, and points to one safe next action while raw diagnostics stay secondary.
• Smallest enterprise-capable version: Productize only the existing workspace Operations page and related table payloads. Derive all states from existing OperationRun, OperationRunResource, OperationRunLinks, OperationRunProgressContract, badges, related links, capabilities, and workspace environment-filter mechanisms.
• Explicit non-goals: No new operation engine, queue system, monitoring platform, alert routing, governance health dashboard, AI summarization, operation type, persisted run item, status/outcome enum, migration, package, env var, scheduler, queue, storage, deployment asset, compatibility route, or legacy query alias.
• Permanent complexity imported: Feature-local page composition, feature tests, one browser smoke, screenshot artifacts, and repo-truth-map.md. No new persisted truth, public abstraction, enum/status family, cross-domain UI framework, or backend service foundation.
• Why now: Specs 314-322 stabilized workspace/environment scope. Specs 326 and 327 established the decision-first productization pattern for strategic surfaces. Operations Hub is the next explicit follow-up and already has the OperationRun foundations needed for a bounded runtime UI pass.
• Why not local: A title or column tweak would not solve the first decision problem. A new observability engine would overbuild. The narrow correct slice is a repo-truth-bounded productization pass on the existing Operations page.
• Approval class: Workflow Compression.
• Red flags triggered: Strategic UI productization and cross-family OperationRun outcome presentation. Defense: scope is bounded to one existing page/table/detail-link ecosystem, uses existing truth sources, and explicitly forbids new backend/state frameworks.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source: Direct user-provided manual promotion for Spec 328, aligned with the OperationRun / execution-truth maturity queue in docs/product/spec-candidates.md, the Operations Hub target brief from Spec 325, and the follow-up list in Spec 327.
• Current package check: specs/328-operations-hub-decision-first-workbench-productization/ existed before this preparation with template spec.md and plan.md only. No completion, implementation close-out, validation, browser smoke, or completed task markers existed in the Spec 328 package.
• Related completed-spec check: Specs 314-327 include historical/completed foundation and productization signals. They are dependency context only and must not be rewritten by Spec 328.
• Close alternatives deferred: Evidence / Audit Log Disclosure Productization, Environment Dashboard / Baseline Compare Productization, and Restore Safety Workflow Productization remain follow-up specs 329-331.
• Smallest viable implementation slice: Existing Operations Hub only: header/scope, main decision workbench, summary cards, right operation/proof panel, operations table as secondary context, diagnostics disclosure, RBAC-aware links/actions, canonical environment_id filter behavior, terminal/progress semantics, and tests/browser smoke.

Spec Scope Fields (mandatory)

• Scope: workspace canonical-view operations workbench, optionally filtered by canonical environment_id.
• Primary Routes:
  • Existing route: /admin/workspaces/{workspace}/operations.
  • Existing route name: admin.operations.index.
  • Existing detail route: /admin/workspaces/{workspace}/operations/{run}.
  • Existing detail route name: admin.operations.view.
  • Existing index page class: apps/platform/app/Filament/Pages/Monitoring/Operations.php.
  • Existing index view: apps/platform/resources/views/filament/pages/monitoring/operations.blade.php.
  • Existing table/detail resource: apps/platform/app/Filament/Resources/OperationRunResource.php.
  • Existing detail page class: apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php.
• Data Ownership:
  • Execution truth: OperationRun.status, outcome, type, summary_counts, failure_summary, context, started_at, completed_at, initiator_name, workspace_id, and managed_environment_id.
  • Status/outcome vocabulary: OperationRunStatus and OperationRunOutcome.
  • Problem class truth: OperationRun::problemClass(), PROBLEM_CLASS_ACTIVE_STALE_ATTENTION, PROBLEM_CLASS_TERMINAL_FOLLOW_UP, activeStaleAttention(), terminalFollowUp(), and dashboardNeedsFollowUp().
  • Progress truth: OperationRunProgressContract, SummaryCountsNormalizer, OperationSummaryKeys.
  • Operation labels and related context: OperationCatalog, OperationRunLinks::related(), canonical run URLs, and related resource routes.
  • Artifact/proof truth: existing ArtifactTruthPresenter, related evidence/review/backup/restore links where already derived from OperationRun context or relations.
  • Workspace/environment scope: WorkspaceContext, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, CanonicalAdminEnvironmentFilterState, and the workspace hub filter chip partial.
• RBAC:
  • Workspace membership required.
  • Managed-environment entitlement required for environment-bound runs.
  • Existing OperationRunPolicy and OperationRunCapabilityResolver remain authoritative for run visibility.
  • Existing source policies/capabilities remain authoritative for evidence, artifact, related record, support diagnostics, retry/resume, support request, and related links.
  • Non-member or cross-workspace environment access remains deny-as-not-found.
  • Member with missing capability must not see unauthorized details or actionable controls.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Clean OperationRunLinks::index() / /admin/workspaces/{workspace}/operations remains workspace-wide and must not inherit remembered environment context, Filament tenant context, session table filters, or legacy query aliases.
• Explicit entitlement checks preventing cross-tenant leakage: ?environment_id= must resolve through the current workspace and actor entitlement. Cross-workspace or inaccessible IDs return safe no-access / 404.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

• Route/page/surface: /admin/workspaces/{workspace}/operations, Operations, operations.blade.php, OperationRunResource table and canonical run detail links.
• Current or new page archetype: Strategic Surface / Operations Monitoring Workbench, matching docs/ui-ux-enterprise-audit/page-reports/ui-003-operations.md.
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified page/table/detail foundation; individual runtime elements are classified in repo-truth-map.md.
• Existing pattern reused: Filament Page, Filament table, header widgets, badges, shared operation links, workspace hub environment filter chip, EnterpriseDetail run detail, OperationRun progress contract, existing policies/capabilities.
• New pattern required: no new runtime framework; page-local workbench composition only.
• Screenshot required: yes, Browser smoke screenshots under specs/328-operations-hub-decision-first-workbench-productization/artifacts/screenshots/.
• Page audit required: no new full audit unless implementation materially changes route inventory; active spec artifacts and screenshots are sufficient if route/archetype remains UI-003.
• Customer-safe review required: not customer-facing by default. If any customer-readable copy is introduced later, raw diagnostics and provider payloads remain hidden.
• Dangerous-action review required: no new dangerous action expected. If implementation unexpectedly exposes retry/cancel/rerun/restore-related execution, spec/plan must be updated first and the action must use Action::make(...)->action(...), confirmation where relevant, authorization, audit, notification, and tests.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
  • No registry update needed; route and archetype remain covered by UI-003 and Spec 325 target artifacts.
• Coverage decision for implementation: implementation must either update UI coverage registry artifacts or document in this spec's close-out why UI-003 and Spec 325 target artifacts remain sufficient for the unchanged route/archetype.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): status messaging, action links, OperationRun links, evidence/artifact proof links, workspace/environment filter chip, summary cards, diagnostics disclosure, navigation/back context.
• Systems touched: Operations, operations.blade.php, OperationRunResource, TenantlessOperationRunViewer, OperationsKpiHeader, OperationRunLinks, OperationRunProgressContract, OperationUxPresenter, ArtifactTruthPresenter, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, CanonicalAdminEnvironmentFilterState, OperationRunPolicy, OperationRunCapabilityResolver.
• Existing pattern(s) to extend: existing operations table, existing problem-class tabs, existing OperationRun badges, existing run detail EnterpriseDetail sections, existing workspace hub filter chip, existing operation related links and progress contract.
• Shared contract / presenter / builder / renderer to reuse: OperationRunLinks, OperationCatalog, OperationRunProgressContract, OperationUxPresenter, BadgeCatalog / BadgeRenderer, OperationRunPolicy, OperationRunCapabilityResolver, existing related-resource routes.
• Why the existing shared path is sufficient or insufficient: Existing paths are sufficient for execution truth, links, badges, progress semantics, authorization, and detail diagnostics. They are insufficient only in first-read page hierarchy on the operations index.
• Allowed deviation and why: bounded page-local payload/view helpers are allowed if needed to reduce Blade complexity. New public cross-domain status, priority, presenter, or monitoring frameworks are not allowed.
• Consistency impact: Labels, badges, progress language, operation URLs, diagnostics labels, and related links must stay aligned with existing OperationRun and EnterpriseDetail vocabulary.
• Review focus: Verify no fake progress, no false green health, no raw diagnostics by default, no unauthorized action, no shell-scope regression, and no duplicate local operation truth.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: link and presentation semantics only. No new OperationRun creation, queueing, dedupe, lifecycle transition, summary-count writer, or terminal notification behavior.
• Shared OperationRun UX contract/layer reused: OperationRunLinks, OperationRunProgressContract, OperationUxPresenter, OperationStatusNormalizer, SummaryCountsNormalizer, and OperationSummaryKeys.
• Delegated start/completion UX behaviors: N/A - no operation start.
• Local surface-owned behavior that remains: derive index-page focus, reason, impact, proof availability, and primary next action from existing run truth and related links.
• Queued DB-notification policy: unchanged / N/A.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam.
• Boundary classification: platform-core operations workbench over existing provider-backed execution records.
• Seams affected: display and routing over OperationRuns, environment-bound related records, evidence/artifact proof, restore/backup/provider operation links, and diagnostic disclosure.
• Neutral platform terms preserved or introduced: workspace, environment filter, operation, execution outcome, proof, artifact, diagnostics, follow-up.
• Provider-specific semantics retained and why: existing Microsoft/Intune/Entra terms may appear only where the underlying operation type or related resource already uses them. Do not surface raw provider IDs, Graph payloads, or provider diagnostics by default.
• Why this does not deepen provider coupling accidentally: no Graph calls, no provider contracts, no provider connection changes, no new provider-shaped persistence, and no new operation taxonomy.
• Follow-up path: Evidence/Audit disclosure, Environment Dashboard/Baseline Compare, and Restore Safety Workflow remain separate specs.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Operations Hub page	yes	Native Filament page plus existing Blade composition	operations monitoring, status messaging, proof links	page, URL-query, table state, derived payload	no	Existing route only
Header / scope area	yes	Filament header actions / Blade	workspace/environment context presentation	page, URL-query	no	Must keep Workspace shell ownership
Main operation workbench	yes	Filament section/cards/badges	execution outcome and next action	page payload	no	Derived labels only
Summary cards	yes	Filament widget/cards	execution posture counts	query payload	no	Only repo-backed counts or unavailable states
Right operation/proof panel	yes	native layout / Blade	proof, artifact, related links, diagnostics	page payload	no	Desktop aside, stacked on small screens
Operations table/history	yes	existing Filament table	run log / secondary context	table state	no	Table remains available
Diagnostics disclosure	yes	collapsed/progressive disclosure only	support/raw detail	detail links/action visibility	no	Authorized and collapsed by default

Decision-First Surface Role

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
Operations Hub	Primary Decision Surface for execution follow-up	Operator decides which operation needs attention and what is safe to inspect next	highest-priority operation, outcome, reason, impact, progress/proof state, environment, one next action	run detail, artifact/evidence, related resource, diagnostics	Primary because it is the canonical workspace operations workbench	Follows execution follow-up, not raw history	Prevents scanning all runs before first action
Operations table/history	Secondary Context	Operator scans remaining runs after the top operation is clear	operation, environment, status/outcome, timing, table filters	canonical detail route and related links	Secondary because table supports investigation/history	Keeps existing monitoring power	Reduces raw-table dominance
Diagnostics disclosure	Tertiary Evidence / Diagnostics	Support/operator inspects technical data after decision path	collapsed availability only	raw context, failure summary, support diagnostics where authorized	Not primary; diagnostics support execution truth	Preserves audit/debug depth	Prevents default raw-console experience

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Operations Hub	operator-MSP, manager, support reviewer, auditor	outcome, reason, impact, environment, timing, proof/artifact availability, active progress only when trustworthy, next action	related run detail and collapsed diagnostic sections	raw context, failure summary, stack traces, provider payloads, provider secrets, debug metadata	Review/open operation unless a stronger authorized proof link exists	raw diagnostics, unsupported proof claims, unauthorized links	top workbench states the execution blocker once; table/panel add proof/source context
Right operation/proof panel	operator-MSP, support reviewer where authorized	operation summary, outcome, environment, timing, proof/artifact state, primary next action	operation detail sections and support diagnostics links	raw/support sections stay collapsed or routed to existing authorized surfaces	same selected-operation primary action	raw JSON and support diagnostics	panel expands selected operation rather than creating another decision

UI/UX Surface Classification

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
Operations Hub	Workbench / Monitoring	Decision-first operations queue	Review highest-priority operation	explicit primary action plus table row detail	existing table row click remains	right/detail panel and related links	none introduced; future retry/cancel in More/detail only	/admin/workspaces/{workspace}/operations	/admin/workspaces/{workspace}/operations/{run}	active workspace, optional environment_id chip	Operations / Operation	outcome, reason, impact, environment, proof/progress, next action	none
Operations table/history	List / Table / Read-only run log	Secondary monitoring context	Open operation detail	existing row click	yes	table filters/secondary links	none	same page	canonical run detail route	workspace + environment filter	OperationRun	status/outcome/type/timing	none
Diagnostics disclosure	Diagnostics / Support Raw	Collapsed diagnostic context	Expand or open diagnostics if authorized	disclosure/detail action	N/A	below/inside detail panel	none	same page	existing support diagnostics action/run detail	authorized-only label	Diagnostics	collapsed status only	none

Operator Surface Contract

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
Operations Hub	Operations responder / MSP operator	Decide which execution record needs attention and open the safest existing proof/action path	Workspace operations workbench	Which operation needs attention now?	operation title/type, outcome/status, reason, impact, environment, started/completed time, proof/artifact state, trustworthy active progress, next action	raw context, raw failure summaries, provider payloads, stack traces, support diagnostic bundle	execution status, terminal outcome, freshness/problem class, progress capability, proof/artifact availability	none on the page by default; existing source surfaces own mutations	review/open operation, open artifact/evidence/related record when authorized	none introduced

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no. repo-truth-map.md is a Spec Kit preparation artifact, not runtime truth.
• New abstraction?: no public abstraction. Page-local private helpers are allowed only when they reduce Blade complexity and stay feature-local.
• New enum/state/reason family?: no domain state. Priority and display guidance must derive from existing status, outcome, problem class, progress contract, timestamps, context, related links, and artifact truth.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: The operations index needs to answer the next execution follow-up question without forcing operators through a raw run table.
• Existing structure is insufficient because: Current page provides table, tabs, KPI header, scope cards, lifecycle counts, and run detail pages, but does not consistently elevate the highest-priority operation with outcome/reason/impact/proof/next action first.
• Narrowest correct implementation: Refactor the existing page layout and derived payloads, bind to existing OperationRun sources, keep diagnostics collapsed, and add targeted tests/browser smoke.
• Ownership cost: Feature-local layout/payload tests, one Browser smoke, screenshots, and spec truth map. No durable backend model or new framework cost.
• Alternative intentionally rejected: new observability platform, new queue monitor, new operation priority engine, new status enum, new artifact store, AI summary, broad design system work, or raw log viewer.
• Release truth: current-release runtime UI productization over existing OperationRun foundations.

Compatibility posture

This feature assumes pre-production runtime posture. Backward compatibility, historical aliases, migration shims, dual-write logic, legacy route redirects, and legacy query aliases are out of scope. Existing legacy query aliases (tenant, tenant_id, managed_environment_id, environment, tenant_scope, tableFilters) must not be supported for Operations Hub filtering.

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

• Test purpose / classification: Feature, Filament/Livewire/HTTP, Browser.
• Validation lane(s): confidence plus browser for critical workspace/environment UI/scope smoke.
• Why this classification and these lanes are sufficient: The change is a user-facing Filament page productization with RBAC, operation truth, progress semantics, scope, and disclosure behavior. Feature tests prove data/scope/action rules; Browser smoke proves shell/filter/reload/disclosure/table hierarchy behavior.
• New or expanded test families: additions under tests/Feature/Monitoring/* and tests/Browser/Spec328OperationsHubProductizationSmokeTest.php.
• Fixture / helper cost impact: reuse existing OperationRun factory, workspace/environment helpers, and current navigation test helpers. Do not widen expensive defaults.
• Heavy-family visibility / justification: browser addition is explicit and named for Spec 328.
• Special surface test profile: global-context-shell plus monitoring-state-page.
• Standard-native relief or required special coverage: special coverage required for canonical filter, clear/reload, highest-priority operation, right proof panel, progress/terminal semantics, diagnostics default-hidden, and no platform-context tenant copy.
• Reviewer handoff: confirm diagnostics are collapsed, RBAC actions hide/disable correctly, no false green, clean workspace entry, canonical filter, clear filter, cross-workspace guard, terminal runs do not show progress, and table/history remains available as secondary context.
• Budget / baseline / trend impact: no expected material lane-cost shift beyond one targeted browser smoke.
• Escalation needed: document-in-feature if browser coverage becomes too expensive or requires fixture broadening.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Monitoring tests/Feature/Operations tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec328OperationsHubProductizationSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='Operations|OperationRun|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

Summary

Productize the existing Operations Hub into a decision-first OperationRun workbench.

The page must answer:

Which operation needs attention now?

It must lead with outcome, reason, impact, trustworthy progress/proof, affected environment, and primary next action. The existing operations table remains available as secondary context. OperationRuns remain execution truth and must not be presented as governance or environment health.

Product Context

TenantPilot uses OperationRuns as execution truth for queued, running, completed, failed, blocked, partial, stale, and follow-up operational work. The Operations Hub is the workspace-wide place to understand execution posture and inspect operation proof. It should help operators decide which operation requires attention without turning the page into a raw queue monitor or governance health dashboard.

OperationRuns answer what ran, what is running, what completed, what failed, what is blocked, what needs follow-up, and which artifact or proof may exist. They do not prove that an environment is healthy, governance is complete, or customer review evidence is ready.

Problem Statement

The current Operations page is technically useful but still table-first and monitor-like. It has scope cards, tabs, KPI header, lifecycle warning copy, and the OperationRun table. The current page does not yet consistently elevate the highest-priority operation needing attention with reason, impact, proof state, and next action.

Known repo-verified starting points:

• Operations page exists and uses OperationRunResource::table().
• OperationRunResource has badge-backed status/outcome columns, table filters, canonical row URL, and empty state.
• OperationRun has problem-class helpers for stale active and terminal follow-up states.
• OperationRunProgressContract already prevents terminal progress and derives determinate progress only from trustworthy processed/total counts.
• TenantlessOperationRunViewer already provides rich run detail, related links, support diagnostics actions, and collapsed technical sections.
• Workspace/environment filter contracts are already implemented around environment_id.

User Scenarios & Testing (mandatory)

User Story 1 - Decide which operation needs attention now (Priority: P1)

As an operations responder, I want Operations Hub to show the highest-priority operation needing attention with outcome, reason, impact, environment, proof state, and one next action so I can act without scanning raw history first.

Why this priority: This is the core productization promise and delivers value independently.

Independent Test: Seed runs with failed, blocked, partial, stale/running, and successful states; open Operations Hub; verify the top workbench prioritizes attention-needed runs and shows outcome, reason, impact, environment, proof state, and primary action.

Acceptance Scenarios:

1. Given a blocked or follow-up operation exists, When the operator opens clean Operations Hub, Then the workbench asks Which operation needs attention now? and shows the attention operation above successful history.
2. Given reason, impact, artifact, or evidence data is absent, When the operation is rendered, Then the page shows an honest unavailable state rather than invented proof.
3. Given no attention-needed operation exists, When the page renders, Then the primary state says no operations need attention without claiming environment or governance health.

User Story 2 - Preserve truthful OperationRun progress and terminal outcomes (Priority: P1)

As an operator, I want active progress to be shown only when trustworthy and terminal outcomes to show guidance instead of progress so I do not misread a failed or completed run as still processing.

Why this priority: Misleading progress creates false calm and undermines OperationRun trust.

Independent Test: Render active counted, active uncounted, failed, blocked, partial, and completed runs; assert progress displays only for active trustworthy counts and terminal runs show outcome guidance.

Acceptance Scenarios:

1. Given a running operation has valid processed and total, When the workbench renders, Then determinate progress appears from those counts.
2. Given a queued/running operation lacks trustworthy counts, When the workbench renders, Then only activity/status guidance appears.
3. Given failed, blocked, partial, or succeeded terminal operations exist, When they render, Then no progress bar appears for terminal outcomes.

User Story 3 - Keep workspace/environment scope explicit (Priority: P1)

As a workspace operator, I want Operations Hub to stay workspace-owned while accepting a canonical environment filter so clean, filtered, clear, reload, and cross-workspace behavior remain predictable.

Why this priority: Specs 314-322 made this a hard product contract for workspace hub surfaces.

Independent Test: Open clean OperationRunLinks::index(), filtered ?environment_id=, clear filter, reload, legacy aliases, and cross-workspace IDs; verify workspace shell and chip behavior.

Acceptance Scenarios:

1. Given clean Operations Hub URL, When the page loads, Then no Environment chip or remembered Environment filter appears.
2. Given ?environment_id={id} for an entitled environment, When the page loads, Then Workspace shell remains active and a visible Environment filter chip appears.
3. Given a cross-workspace environment ID or legacy query alias, When the page loads, Then the cross-workspace ID is denied as not found and aliases do not create filter state.

User Story 4 - Inspect proof without raw diagnostics by default (Priority: P1)

As an operator or support reviewer, I want proof/artifact links and operation detail to be easy to reach while raw diagnostics remain collapsed and capability-gated.

Why this priority: Operations need proof, but raw details should not dominate or leak.

Independent Test: Render runs with related artifact/evidence links and diagnostic payloads; assert proof state/link appears where authorized while raw payload, stack trace, provider secret, debug metadata, and internal exception text are absent by default.

Acceptance Scenarios:

1. Given an operation has a related artifact or evidence route, When the detail panel renders, Then proof state/link appears only if repo-real and authorized.
2. Given diagnostics are available, When the page first renders, Then raw diagnostics are collapsed or absent by default.
3. Given the actor lacks diagnostics/proof capability, When the page renders, Then protected links/actions are hidden or unavailable without sensitive hints.

User Story 5 - Preserve operations table as secondary context (Priority: P2)

As an operations responder, I want the existing operations table/history to remain available below or beside the workbench so I can scan history after the top decision is clear.

Why this priority: The workbench must not regress existing monitoring and filtering power.

Independent Test: Render the existing OperationRun table fixtures and assert rows, filters, tabs, row links, and empty state still appear as secondary context.

Acceptance Scenarios:

1. Given multiple visible OperationRuns exist, When the workbench renders, Then existing table context remains available and is not replaced by a generic dashboard.
2. Given an operations tab or table filter is selected, When the page renders, Then the workbench and table align to current scope without losing clear-filter behavior.

Functional Requirements

• FR-001: Operations Hub MUST remain on the existing admin.operations.index route.
• FR-002: The page MUST render a decision-first workbench before the secondary operations table/history.
• FR-003: The workbench MUST include the question Which operation needs attention now? or stable equivalent final copy.
• FR-004: The selected/highest-priority operation MUST show operation title/type, outcome/status, reason, impact, environment, timing, proof/artifact state, and primary next action.
• FR-005: Missing reason, impact, environment, artifact, evidence, or proof data MUST render honest unavailable/missing states or be omitted; it MUST NOT be invented.
• FR-006: Priority MUST derive from existing status/outcome/problem-class/freshness truth only. No new persisted priority engine is allowed.
• FR-007: Summary cards MUST use only repo-supported execution posture counts/states, such as needs attention, active operations, failed/blocked, follow-up required, completed recently, or artifact available where proven.
• FR-007A: Summary cards MUST use native Filament StatsOverviewWidget / Stat rendering where feasible while remaining Operations execution/attention signals, not generic business KPIs.
• FR-007B: The four top workbench summary cards MUST be Needs attention, Active operations, Failed or blocked, and Completed recently; no Total Operations or Avg Duration card may appear before the workbench.
• FR-007C: Summary-card visual emphasis MUST follow execution risk: Needs attention strongest when non-zero, Active operations neutral when zero, Failed or blocked danger/warning, and Completed recently muted success/secondary without implying environment or governance health.
• FR-007D: Summary cards MUST NOT show fake trends, fake sparklines, decorative charts, or chart-like areas unless repo-backed time-series data exists.
• FR-008: Existing OperationRun table/history MUST remain available as secondary context.
• FR-009: A right-side operation/proof panel MUST be visible on desktop and stack on smaller screens.
• FR-010: Proof/artifact/evidence must be shown as proof state/link, not raw payload.
• FR-011: Diagnostics/raw details MUST be collapsed, hidden, or capability-gated by default.
• FR-012: Primary action MUST be singular and repo-real for the selected/highest-priority operation.
• FR-013: Unauthorized actions MUST be hidden, disabled with existing helper text convention, or replaced by unavailable state; UI visibility is not security.
• FR-014: No new destructive or high-impact action may be added without updating spec/plan first and applying confirmation, server authorization, audit, notification, and tests.
• FR-015: Determinate progress MUST appear only when OperationRunProgressContract or equivalent existing trusted-count semantics allow it.
• FR-016: Terminal completed, failed, blocked, partial, or follow-up runs MUST NOT show progress bars.
• FR-017: Completed successful operations MUST NOT be described as environment health, governance health, or customer-safe evidence readiness.
• FR-018: Clean entry MUST remain workspace-wide with no active Environment shell and no remembered Environment fallback.
• FR-019: Filtered entry MUST use only ?environment_id={id} with a visible chip and clear action.
• FR-020: Legacy query aliases (tenant, tenant_id, managed_environment_id, environment, tenant_scope, tableFilters) MUST NOT create filter state.
• FR-021: Cross-workspace or unauthorized environment_id MUST be rejected as safe not-found/no-access.
• FR-022: Runtime copy MUST avoid tenant as platform context copy. Provider-specific use remains allowed only when explicitly provider-bound.
• FR-023: repo-truth-map.md MUST exist before runtime changes and be updated if implementation discovers new source gaps.
• FR-024: No migrations, seeders, packages, env vars, queues, scheduler, storage, deployment asset changes, backwards compatibility layer, or legacy alias support are expected.

Non-Functional Requirements

• NFR-001: Page render MUST remain DB-only and MUST NOT perform Microsoft Graph or external provider calls.
• NFR-002: The layout MUST remain Filament v5 / Livewire v4 compatible and use native Filament/Tailwind primitives before custom UI.
• NFR-003: The workbench MUST remain responsive enough for the Filament shell; desktop gets a right-side panel and smaller viewports stack it below.
• NFR-004: Operation priority, status, and proof meaning MUST NOT rely on color alone.
• NFR-005: Raw diagnostics, provider payloads, stack traces, provider secrets, raw OperationRun context, and internal exception/debug metadata MUST NOT be default-visible.
• NFR-006: Queries and summary counts MUST be scoped by workspace, environment entitlement, and capability before rendering.
• NFR-007: Implementation MUST avoid broad fixture/helper defaults or hidden heavy-governance test cost.

Auditability / Observability Requirements

• AOR-001: No new audit event is required for read-only page productization unless implementation introduces a new mutation or extends an existing repo audit convention.
• AOR-002: Any unexpected mutating/high-impact action MUST be added only after spec/plan update and must include server-side authorization, confirmation when destructive/high-impact, audit logging, user feedback, and tests.
• AOR-003: Operation proof links must use existing OperationRun truth and link helpers; this spec must not create or transition OperationRuns.
• AOR-004: Evidence, artifact, and proof states must distinguish available proof from unavailable/missing proof without implying audit success or governance health.

Data / Truth Requirements

Each visible runtime element must be classified as one of:

• repo-verified
• foundation-real
• derived from existing model
• empty state / unavailable
• deferred future capability

The authoritative map is repo-truth-map.md in this spec directory. If implementation discovers that a planned element has no safe source, no authorization path, or would require new persisted truth, the element must become empty state / unavailable or deferred future capability.

RBAC / Capability Requirements

At minimum, implementation must verify existing capabilities/policies for:

• view Operations Hub / workspace membership
• view operation runs
• view operation run detail
• view evidence/artifacts
• view support diagnostics/raw detail
• retry/re-run/resume operation if an existing action is shown
• cancel operation if an existing action is shown
• open related alert/finding/review/restore/backup/provider context if existing links are shown

Do not introduce new permission semantics unless repo analysis proves an existing capability cannot express the action and spec/plan are updated first.

Assumptions

• The existing OperationRun problem-class helpers and freshness scopes can provide enough priority truth for a first implementation without creating a new priority engine.
• Existing OperationRunResource and TenantlessOperationRunViewer provide enough detail/proof/diagnostic patterns to reuse or link from the index workbench.
• Existing OperationRunProgressContract is the authoritative v1 progress semantics path.
• Existing OperationRunPolicy, OperationRunCapabilityResolver, and source-resource policies are sufficient for v1 action visibility and source-link access.
• Spec 325 target images remain visual calibration and must not be treated as runtime data truth.

Risks

• Implementation could accidentally create a new priority taxonomy instead of a local derived ordering.
• Completed successful runs could be overclaimed as environment health or governance health.
• Artifact/evidence labels could become false proof claims if unavailable links are not rendered honestly.
• Progress could regress if terminal runs show determinate or indeterminate progress.
• Capability-limited actors could learn hidden run or artifact existence through counts, empty states, or disabled labels if scoping is applied too late.
• Browser coverage could become expensive if fixtures grow beyond the targeted smoke path.

Open Questions

• None blocking preparation. Implementation must update repo-truth-map.md and spec/plan before runtime edits if it discovers a selected UI element requires new persisted truth, a new capability, or an unsupported source route.

Non-Goals

• No new operation engine, queue engine, or monitoring backend.
• No new observability platform or raw logs page.
• No governance health dashboard.
• No alert routing redesign.
• No Evidence/Audit, Governance Inbox, Customer Review Workspace, Restore, Backup, or Provider Readiness redesign.
• No AI summarization or recommendation engine.
• No new operation types, statuses, outcomes, progress keys, priority enums, persisted workbench items, or backend foundations.
• No migrations by default.
• No packages, env vars, queues, scheduler, storage, or deployment asset changes.
• No backwards compatibility layer or legacy tenant query alias support.

Acceptance Criteria

Productization

• Operations Hub has a decision-first layout.
• Main decision question is visible.
• Highest-priority operation needing attention is visible where fixture data exists.
• Empty/no-attention state is clear where no operation needs attention.
• Outcome/status is visible.
• Reason and impact are visible.
• Affected Environment is visible where applicable.
• Artifact/evidence/proof state is visible.
• Primary next action is clear.
• Diagnostics are secondary/collapsed.
• Operations table/history remains available as secondary context.

OperationRun Semantics

• OperationRun remains execution truth, not governance health.
• Completed successful runs are not overclaimed as environment health.
• Failed/blocked/follow-up runs show outcome guidance.
• Terminal runs do not show misleading progress.
• Determinate progress appears only with trustworthy counts.
• Artifact/evidence links shown only where repo-supported.

Operator Safety

• Raw diagnostics hidden by default.
• Provider secrets not visible.
• Internal exception/debug text not visible.
• No false green success state.
• Copy avoids tenant as platform context.
• Empty/unavailable states are honest.

Scope

• Clean URL is workspace-wide.
• Shell is Workspace-only.
• Environment filter uses environment_id.
• Visible Environment chip appears when filtered.
• Clear filter works.
• Reload after clear is safe.
• Legacy aliases do not create filter state.
• Cross-workspace Environment is rejected.

RBAC

• Unauthorized user cannot access protected operation data.
• Unauthorized actions are hidden/disabled.
• Operation detail access respects capability.
• Evidence/artifact access respects capability.
• Diagnostics access respects capability.
• Retry/cancel/resume actions, if present, respect capability and confirmation conventions.

UI / Visual

• Layout uses premium direction from Spec 325 without treating target images as runtime truth.
• Filament light mode remains readable.
• No heavy one-off CSS.
• Right-side operation/proof panel exists on desktop.
• Operations table is not the only default experience.
• Page remains responsive enough for Filament shell.
• Summary cards visually align with compact Filament KPI/Stats-card density while staying execution/attention signals.
• Summary cards use a clear title, large value, concise subline, and subtle accent line/status color.
• Needs attention is visually strongest when actionable; Active operations is neutral when zero; Completed recently stays muted and does not imply health.
• No fake trends, fake sparklines, or unsupported chart affordances appear.

Spec 328 Follow-up - Filament Summary Card Alignment

The Operations summary cards should visually read like high-quality compact Filament KPI/Stats cards, but their product semantics remain Operations execution and attention signals. They are not generic business KPIs and must not imply environment health, governance health, revenue, adoption, or customer readiness.

Required cards:

1. Needs attention
2. Active operations
3. Failed or blocked
4. Completed recently

Design rules:

• Use compact native Filament Stats Overview hierarchy with clear label, large numeric value, short supporting text, description/status icon where useful, and Stat::color(...) semantic emphasis.
• Do not hand-roll a custom Blade/Tailwind stats-card design system or explicit custom accent bars unless native widget embedding is proven infeasible and the reason is documented in repo-truth-map.md.
• Use no sparkline or chart area unless the data is repo-backed. No fake trends or decorative chart placeholders.
• Needs attention carries the strongest warning emphasis when its value is non-zero.
• Active operations must not look stronger than attention cards when the value is 0.
• Completed recently must remain muted success/secondary and must not read as an environment-health claim.
• The old generic pre-workbench cards such as Total Operations and Avg Duration must not return.
• Implementation should use Filament\Widgets\StatsOverviewWidget, Filament\Widgets\StatsOverviewWidget\Stat, Stat::make(...), description(...), optional descriptionIcon(...), and color(...); polling stays disabled unless the Operations page requires live updating.

Tests / Validation

• Repo truth map exists.
• Required Feature tests pass.
• Required Browser smoke passes.
• Relevant Spec 314-322 guards still pass.
• pint --dirty passes.
• git diff --check passes.
• Full suite status is honestly reported if run/not run.

Follow-Up Spec Candidates

• Spec 329 - Evidence / Audit Log Disclosure Productization.
• Spec 330 - Environment Dashboard / Baseline Compare Productization.
• Spec 331 - Restore Safety Workflow Productization.

Do not start these inside Spec 328.

Implementation Close-Out

• Changed behavior: the existing Operations Hub now opens with a decision-first execution follow-up workbench before the operations history table.
• Runtime truth: selected operation, reason, impact, environment, timing, summary cards, and progress are derived from existing OperationRun state, existing problem classes, OperationCatalog, OperationRunLinks, and OperationRunProgressContract.
• Summary-card follow-up: the decision-first cards own the first viewport; generic Total Operations / Avg Duration KPI cards are not rendered before the workbench.
• Native summary-card follow-up: the four top summary cards now render through a narrow native Filament StatsOverviewWidget using Stat::make(...), descriptions, description icons, and semantic color(...) values. The previous custom Blade/Tailwind card loop and explicit bottom accent bars were removed. No fake charts, sparklines, trends, or health overclaims were added.
• Unavailable/deferred truth: raw diagnostics, provider payloads, artifact/evidence specifics, retry/cancel/rerun, and stronger proof actions remain on existing authorized detail/source surfaces or unavailable in the index.
• Scope contract: clean entry remains workspace-wide; explicit filtering uses only environment_id; legacy aliases stay rejected/neutralized; cross-workspace filters return safe not-found/no-access.
• UI coverage decision: no registry files were changed because the route and archetype remain the existing UI-003 Operations strategic surface; Spec 328 browser screenshots provide the implementation evidence.
• Screenshots: stored under specs/328-operations-hub-decision-first-workbench-productization/artifacts/screenshots/, including operations-hub-premium-summary-cards.png.
• Validation:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Monitoring tests/Feature/Operations tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact - passed, 182 tests / 1544 assertions.
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec328OperationsHubProductizationSmokeTest.php --compact - passed, 3 tests / 67 assertions.
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='Operations|OperationRun|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact - passed, 482 tests / 4713 assertions.
  • cd apps/platform && ./vendor/bin/sail pint --dirty - passed.
  • git diff --check - passed.
• Deployment impact: no migrations, seeders, packages, env vars, queues, scheduler, storage, deployment assets, backwards compatibility layer, or legacy alias support were added.