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

# Implementation Plan: Spec 328 - Operations Hub Decision-First Workbench Productization

**Branch**: `328-operations-hub-decision-first-workbench-productization` | **Date**: 2026-05-18 | **Spec**: `specs/328-operations-hub-decision-first-workbench-productization/spec.md`  
**Input**: User-provided Spec 328 and repo inspection.

## Summary

Productize the existing workspace-scoped Operations Hub into a decision-first OperationRun workbench. The implementation must keep the current route and OperationRun truth, introduce no backend foundation, and make the first viewport answer:

```text
Which operation needs attention now?
```

The workbench will elevate the highest-priority operation, outcome, reason, impact, affected environment, trustworthy progress/proof state, and a single next action, while keeping the existing OperationRun table as secondary context and diagnostics collapsed.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0.  
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Tailwind CSS 4.2.2.  
**Storage**: PostgreSQL; no schema change expected.  
**Testing**: Pest 4 Feature/Livewire/Browser tests.  
**Validation Lanes**: confidence and browser; targeted navigation guard tests.  
**Target Platform**: Laravel Sail locally; Dokploy/container deployment posture unchanged.  
**Project Type**: Laravel monolith under `apps/platform`.  
**Performance Goals**: DB-only page render; no Graph calls during render; no extra heavy query family beyond existing operations table/detail queries unless bounded and eager-loaded.  
**Constraints**: No new persisted truth, migration, package, queue/scheduler/storage/env change, deployment asset, compatibility route, or legacy alias support.  
**Scale/Scope**: One existing Filament page, its Blade view, existing OperationRun table/resource helpers, feature tests, browser smoke, and spec artifacts.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed existing operator-facing strategic surface.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/workspaces/{workspace}/operations`
  - `/admin/workspaces/{workspace}/operations/{run}` only as linked canonical detail context
  - `apps/platform/app/Filament/Pages/Monitoring/Operations.php`
  - `apps/platform/resources/views/filament/pages/monitoring/operations.blade.php`
  - `apps/platform/app/Filament/Resources/OperationRunResource.php`
  - `apps/platform/app/Filament/Widgets/Operations/OperationsKpiHeader.php` only if summary card/KPI wording must be adjusted
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: Native Filament page/table plus existing Blade composition; no new UI framework.
- **Shared-family relevance**: status messaging, OperationRun links, progress contract, proof/artifact links, workspace/environment filter chip, diagnostics disclosure.
- **State layers in scope**: page payload, URL query (`environment_id`, `activeTab`, `problemClass`), table filters/session state, highest-priority operation selection, diagnostics disclosure.
- **Audience modes in scope**: operator-MSP, manager, support reviewer, auditor.
- **Decision/diagnostic/raw hierarchy plan**: decision-first, proof/artifact second, diagnostics/support raw third.
- **Raw/support gating plan**: collapsed by default and capability-gated where existing capabilities support access.
- **One-primary-action / duplicate-truth control**: selected/highest-priority operation owns one primary next action; table rows and related links remain secondary.
- **Handling modes by drift class or surface**: review-mandatory for UI-003 strategic surface; document-in-feature for any UI coverage registry no-change decision.
- **Repository-signal treatment**: Spec 325 target image is visual direction only; runtime claims must be repo-verified or unavailable.

## Constitution Check

- **Inventory-first, snapshots-second**: N/A, no Graph, inventory, snapshot, backup, or restore data model change.
- **Read/write separation by default**: Page remains read-first. Any unexpected mutation requires spec/plan update, confirmation, authorization, audit, notification, and tests.
- **Single Contract Path to Graph**: No Graph calls may be added.
- **Deterministic Capabilities**: Reuse existing `OperationRunPolicy`, `OperationRunCapabilityResolver`, source policies, and capability resolvers.
- **Proportionality / anti-bloat**: No new source of truth, persisted entity, enum/status family, public abstraction, priority engine, or cross-domain UI framework.
- **Workspace isolation**: Clean workspace URL stays workspace-wide; `environment_id` is resolved through current workspace and actor entitlement.
- **Tenant/environment language**: Runtime copy must avoid tenant as platform context; provider-specific tenant wording only where explicitly provider-bound.
- **OperationRun UX**: Presentation/link semantics only. No operation start, queueing, lifecycle transition, notification, or summary-count writer changes.
- **Progress contract**: `OperationRunProgressContract` remains authoritative. Terminal runs show outcome guidance, not progress.
- **UI-COV-001**: Existing strategic surface UI-003 changes; active spec package carries repo-truth map, tests, and browser screenshots. Implementation close-out decides whether route inventory/coverage matrix updates are needed.
- **TEST-GOV-001**: Targeted Feature and Browser tests are explicit; no broad heavy-governance lane unless implementation reveals structural risk.

## Current Repo Truth Summary

Existing verified surfaces:

- `Operations` is a Filament `Page` rendered by `admin.operations.index`.
- `admin.operations.index` is `/admin/workspaces/{workspace}/operations`.
- The view currently renders `Monitoring landing`, scope/return/reset cards, tabs, lifecycle warning, and the OperationRun table.
- `OperationRunResource::table()` owns columns, row detail URL, filters, empty state, status/outcome badges, and no row/bulk actions.
- `OperationRun` owns `status`, `outcome`, problem classes, freshness/lifecycle helpers, workspace and managed-environment scope.
- `OperationRunProgressContract` already separates active counted/activity/phased/composite/none progress and returns `none` for terminal runs.
- `TenantlessOperationRunViewer` and `OperationRunResource::infolist()` already provide richer run detail, related links, proof/artifact sections, support diagnostics, and technical sections.
- `OperationRunLinks` provides canonical index/detail URLs and related resource links.
- `WorkspaceHubEnvironmentFilter::fromRequest()` accepts canonical `environment_id`, scopes to current workspace, and rejects inaccessible/cross-workspace IDs.
- Existing tests cover canonical operations URLs, workspace hub clean entry, environment filter behavior, detail access, DB-only rendering, and OperationRun authorization.

Known current productization gap:

- The page is still monitoring/table-first. It does not yet consistently promote an attention-needed operation with outcome, reason, impact, environment, progress/proof state, and one primary next action ahead of the table.

## Existing Repository Surfaces Likely Affected

Runtime files, only during later implementation:

- `apps/platform/app/Filament/Pages/Monitoring/Operations.php`
- `apps/platform/resources/views/filament/pages/monitoring/operations.blade.php`
- `apps/platform/app/Filament/Resources/OperationRunResource.php`
- `apps/platform/app/Filament/Widgets/Operations/OperationsKpiHeader.php` remains existing widget code, but it must not render before the Spec 328 workbench when the decision-first summary cards own the first viewport.
- `apps/platform/resources/lang/en/*` and `apps/platform/resources/lang/de/*` only if current project pattern requires localized strings for new stable copy.

Tests, only during later implementation:

- `apps/platform/tests/Feature/Monitoring/MonitoringOperationsTest.php`
- `apps/platform/tests/Feature/Monitoring/OperationsWorkspaceHubContractTest.php`
- `apps/platform/tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php`
- `apps/platform/tests/Feature/Monitoring/OperationsHeaderHierarchyTest.php`
- `apps/platform/tests/Feature/Monitoring/OperationsTenantScopeTest.php`
- `apps/platform/tests/Feature/Monitoring/OperationLifecycleFreshnessPresentationTest.php`
- `apps/platform/tests/Feature/Operations/TenantlessOperationRunViewerTest.php`
- `apps/platform/tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php`
- `apps/platform/tests/Unit/Support/OpsUx/OperationRunProgressContractTest.php`
- `apps/platform/tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php`
- `apps/platform/tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php`
- `apps/platform/tests/Browser/Spec328OperationsHubProductizationSmokeTest.php`

Spec/UI artifacts:

- `specs/328-operations-hub-decision-first-workbench-productization/repo-truth-map.md`
- screenshot artifacts under `specs/328-operations-hub-decision-first-workbench-productization/artifacts/screenshots/`
- optional UI coverage registry updates only if implementation materially changes route/archetype/coverage state.

## Domain / Model Implications

- No new model, table, migration, enum, status family, source of truth, or persisted display state.
- Workbench item state must derive from existing OperationRun truth:
  - `status`: queued, running, completed.
  - `outcome`: pending, succeeded, partially_succeeded, blocked, failed, reserved cancelled.
  - `problemClass()`: active stale attention, terminal follow-up, none.
  - `freshnessState()` and lifecycle reconciliation payload.
  - `summary_counts` through `OperationRunProgressContract` and `SummaryCountsNormalizer`.
  - `OperationCatalog::label()` for operation type labels.
  - `managed_environment_id` / `tenant` relation for affected environment.
  - `started_at`, `completed_at`, `created_at` for timing.
  - `context`, `failure_summary`, and related models only behind safe proof/diagnostic paths.
- If exact reason, impact, artifact, evidence, or next action is missing, render explicit unavailable/missing state.

## UI / Filament Implications

- Filament v5 and Livewire v4.0+ compliance must be preserved.
- Panel providers remain in `apps/platform/bootstrap/providers.php`; no panel provider changes expected.
- No globally searchable resource is added or changed. `OperationRunResource` remains `protected static bool $isGloballySearchable = false`.
- The layout should use Filament sections/cards/badges/buttons and Tailwind utility classes consistent with existing pages; no heavy one-off CSS.
- Header must stay short:
  - `Operations Hub`
  - workspace label
  - scope label: workspace-wide or filtered environment
  - visible filter chip and clear action when filtered
  - subtitle explaining execution truth and follow-up
- Main workbench must render before the operations table.
- Summary cards should be compact and action-relevant.
- Follow-up summary-card alignment: the four workbench summary cards should use native Filament `StatsOverviewWidget` / `Stat` rendering while remaining execution/attention signals. Use title, large value, concise subline, optional description/status icon, and semantic `Stat::color(...)`. Do not reintroduce custom Blade/Tailwind stat-card markup, explicit custom accent bars, generic `Total Operations` / `Avg Duration` cards, fake trends, fake sparklines, decorative charts, or health claims.
- Card emphasis should reflect execution risk: `Needs attention` strongest when actionable, `Active operations` neutral when zero, `Failed or blocked` danger/warning, and `Completed recently` muted success/secondary.
- Right-side detail/proof panel should be desktop aside and mobile stack.
- Diagnostics must be collapsed by default.

## Livewire / Page State Implications

- Existing internal methods/properties may keep legacy names only as implementation detail; runtime URL/filter language must be `environment_id` and `Environment`.
- Existing `activeTab` and `problemClass` query filters can remain if they do not conflict with `environment_id` contract.
- Highest-priority operation selection should be deterministic on page load. If interactive selection is implemented, it must not introduce persisted state or break reload/back/forward behavior.
- Clear filter must remove `environment_id` and any environment-like table/session filter state through existing helpers.

## OperationRun / Monitoring Implications

- No new `OperationRun` creation or lifecycle transition.
- No queued/running/terminal DB notification changes.
- No new summary-count writer, progress key, operation type, status, or outcome.
- Any operation proof link must use existing `OperationRunLinks`, `OperationRunResource`, related routes, and authorization.
- Raw `OperationRun.context`, `failure_summary`, stack traces, and payload-like data must not be default-visible.

## RBAC / Policy Implications

Reuse existing authorization:

- Workspace page access through current workspace membership checks and `WorkspaceCapabilityResolver::isMember()`.
- Environment access through `ManagedEnvironmentAccessScopeResolver` and current accessible environments.
- Run visibility through `OperationRunPolicy`.
- Run capability mapping through `OperationRunCapabilityResolver`.
- Evidence and artifacts through existing source policies/capabilities where links are shown.
- Support diagnostics through `Capabilities::SUPPORT_DIAGNOSTICS_VIEW` where diagnostics are exposed.
- Existing detail actions such as support diagnostics, support request, resume capture, retry/resume, or related links remain owned by the detail/source surfaces.

No new permission semantics should be added unless implementation proves existing capabilities cannot express the action and spec/plan are updated first.

## Audit / Evidence / Disclosure Implications

- No new audit event is required for read-only page rendering unless current page-open audit conventions are extended repo-wide.
- Evidence/proof should appear as state:
  - operation record available
  - artifact link available
  - evidence linked
  - proof unavailable
  - diagnostics hidden
- Do not show raw provider payloads, debug metadata, internal exception traces, provider secrets, raw OperationRun payloads, or stack traces by default.
- If diagnostics disclosure is present, it must be collapsed and capability-aware.

## Data / Migration Implications

Expected outcome:

- No migrations.
- No seeders.
- No data backfills.
- No packages.
- No env vars.
- No queues/scheduler/storage changes.
- No deployment asset changes.
- No backwards compatibility layer.
- No legacy tenant query alias support.

If implementation discovers an actual schema need, stop and update spec/plan/tasks/repo-truth-map first. Default decision remains no migration.

## Localization / Copy Implications

- Runtime copy must be concise and operator-safe.
- Avoid platform-context `tenant` wording. Use `Workspace` and `Environment` for shell/filter/product context.
- Provider-bound tenant wording may remain only when describing an external Microsoft/Entra tenant identifier or provider payload outside the default decision view.
- Add EN/DE localization only if the surrounding files already route stable page copy through language files; otherwise keep localized scope as implementation-local and document the decision.

## Implementation Phases

### Phase 1 - Repo Truth And Current UI Audit

- Re-read this spec, plan, tasks, and `repo-truth-map.md`.
- Inspect current `Operations`, Blade view, `OperationRunResource`, `TenantlessOperationRunViewer`, progress contract, links, policies, and tests.
- Update `repo-truth-map.md` before runtime changes if implementation discovers new source truth or gaps.
- Confirm no migration/package/env/queue/storage/deployment asset need.

### Phase 2 - Tests First

- Add tests for repo truth map existence.
- Add Feature/Livewire/HTTP tests for decision-first workbench, non-empty attention state, empty/no-attention state, right proof panel, table secondary context, diagnostics hidden, progress/terminal semantics, RBAC action visibility, environment filter, legacy aliases, cross-workspace guard, and tenant-copy guard.

### Phase 3 - Layout Productization

- Refactor the existing page into:
  - header/scope
  - main operations workbench
  - compact execution summary cards
  - right operation/proof panel
  - operations queue/history table
  - collapsed diagnostics disclosure
- Keep existing tabs/table filters and canonical row links.

### Phase 4 - Data Binding

- Bind workbench and panel to repo-verified sources.
- Render unavailable states for missing reason, impact, proof, artifact, evidence, or environment data.
- Do not create synthetic success, health, artifact, or governance claims.

### Phase 5 - Progress / Outcome Semantics

- Use existing progress contract semantics.
- Show determinate progress only when active counted progress is trustworthy.
- Show activity/status only for active uncounted runs.
- Show outcome guidance for terminal failed/blocked/partial/succeeded runs.
- Do not show terminal progress bars.

### Phase 6 - Action Hierarchy And RBAC

- Show one primary next action for the selected/highest-priority operation.
- Link only to existing, authorized operation/detail/artifact/evidence/source routes/actions.
- Keep rare/debug/source actions secondary.
- Do not introduce destructive actions.

### Phase 7 - Scope / Filter Integration

- Preserve clean workspace-wide entry.
- Preserve `?environment_id=` filter, visible chip, clear filter, reload/back/forward behavior.
- Preserve legacy alias rejection and cross-workspace guard.

### Phase 8 - Browser Smoke And Screenshots

- Add targeted Browser smoke for clean, filtered, clear/reload, non-empty workbench, empty/no-attention state, right detail/proof panel, diagnostics hidden, table secondary, light mode if feasible, and no platform-context tenant wording.
- Save screenshots under the spec artifacts path when generated.

### Phase 9 - Validation And Close-Out

- Run targeted Feature/navigation tests, Browser smoke, filtered guard tests, `pint --dirty`, and `git diff --check`.
- Report full suite status honestly if not run.
- Record no migrations/seeders/packages/env/queues/scheduler/storage/deployment asset/backcompat/legacy alias support.

## Testing Strategy

Required tests:

- `it('documents_operations_hub_repo_truth_map')`
- `it('renders_operations_hub_decision_first_workbench')`
- `it('renders_highest_priority_operation_needing_attention')`
- `it('renders_operations_hub_empty_attention_state')`
- `it('renders_operations_hub_operation_detail_proof_panel')`
- `it('keeps_operations_table_available_as_secondary_context')`
- `it('operations_hub_hides_raw_diagnostics_by_default')`
- `it('operations_hub_does_not_show_progress_for_terminal_outcomes')`
- `it('operations_hub_uses_determinate_progress_only_with_trustworthy_counts')`
- `it('operations_hub_supports_canonical_environment_filter')`
- `it('operations_hub_rejects_legacy_environment_aliases')`
- `it('operations_hub_rejects_cross_workspace_environment_filter')`
- `it('operations_hub_does_not_use_tenant_as_platform_context_copy')`
- `it('operations_hub_respects_capabilities_for_primary_actions')`

Required Browser smoke:

- `tests/Browser/Spec328OperationsHubProductizationSmokeTest.php`

Browser flows:

1. Clean workspace Operations Hub.
2. Environment-filtered Operations Hub.
3. Clear filter and reload.
4. Non-empty highest-priority operation needing attention.
5. Empty/no-attention state.
6. Right operation/proof panel visible.
7. Diagnostics hidden by default.
8. Operations table/history remains secondary.
9. No platform-context tenant wording.
10. Light mode readability if supported.

## Rollout Considerations

- No feature flag expected.
- No schema rollout.
- No queue or scheduler rollout.
- No env vars.
- No new Filament asset registration expected. If implementation registers assets unexpectedly, deployment must include `cd apps/platform && php artisan filament:assets`, but the expected path is no asset change.
- Staging validation should run the targeted feature/navigation/browser lanes before production promotion.

## Risk Controls

- Use `repo-truth-map.md` as the runtime claim gate.
- Keep priority derived and feature-local.
- Keep OperationRun detail/source surfaces as owners of deep diagnostics and mutations.
- Keep progress semantics delegated to the existing progress contract.
- Keep environment filtering delegated to existing workspace hub helpers.
- Keep all raw/support information collapsed and capability-aware.
- Keep final report explicit about unavailable states and full-suite status.

## Implementation Close-Out

- Implemented a page-local decision workbench in `Operations::decisionWorkbench()` and `operations.blade.php`.
- Follow-up: replaced the custom summary-card Blade loop with a narrow native `OperationsWorkbenchStats` Filament `StatsOverviewWidget` using four `Stat::make(...)` records, descriptions, description icons, semantic colors, disabled polling, and scoped OperationRun queries.
- Preserved existing route, table, tabs, row links, scope filter, and canonical detail route.
- Added focused feature coverage and a Spec 328 browser smoke with clean, filtered, clear/reload, and empty/no-attention flows.
- Adjusted canonical operation detail shell behavior so current/remembered environment context can be displayed as context while the canonical detail return action remains workspace-oriented.
- No public backend abstraction, persisted state, migration, env var, package, queue, scheduler, storage, deployment asset, or legacy alias support was added.
- Validation passed:
  - `./vendor/bin/sail artisan test tests/Feature/Monitoring tests/Feature/Operations tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact`
  - `./vendor/bin/sail artisan test tests/Browser/Spec328OperationsHubProductizationSmokeTest.php --compact`
  - `./vendor/bin/sail artisan test --filter='Operations|OperationRun|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact`
  - `./vendor/bin/sail pint --dirty`
  - `git diff --check`