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

Tasks: Spec 328 - Operations Hub Decision-First Workbench Productization

Input: Design documents from /specs/328-operations-hub-decision-first-workbench-productization/
Prerequisites: spec.md, plan.md, repo-truth-map.md

Tests: Required. This is a runtime UI/operator workbench Filament page productization with browser smoke.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and the browser addition is explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The declared surface test profile (global-context-shell plus monitoring-state-page) is explicit.
• Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Phase 1: Preparation And Repo Truth

Purpose: Confirm runtime truth and prevent invented claims before page edits.

• T001 Re-read specs/328-operations-hub-decision-first-workbench-productization/spec.md, plan.md, tasks.md, and repo-truth-map.md.
• T002 Re-read related completed context only: Specs 314-327. Do not modify their artifacts.
• T003 Verify current Operations route/class/view, OperationRunResource, TenantlessOperationRunViewer, OperationsKpiHeader, OperationRunLinks, progress contract, policies, and existing tests before editing.
• T004 Update repo-truth-map.md with any newly discovered source, capability, fallback, or classification before runtime changes.
• T005 Confirm no migration/package/env/queue/storage/deployment asset change is required; if one appears necessary, stop and update spec/plan first.
• T006 Confirm Filament v5 / Livewire v4.0+ compliance and no Livewire v3/Filament legacy API use.
• T007 Confirm panel provider registration remains apps/platform/bootstrap/providers.php.
• T008 Confirm OperationRunResource remains non-globally-searchable or has a safe View/Edit path if changed; no global search change is expected.

Phase 2: Feature Tests First

Purpose: Lock decision-first layout, scope, RBAC, progress, proof, and diagnostics behavior before the UI refactor.

• T009 Add or update a feature test asserting repo-truth-map.md exists and lists required data areas.
• T010 Add or update a Feature/Livewire/HTTP test for the decision-first layout text: Operations Hub, Which operation needs attention now?, Outcome, Reason, Impact, and Next action.
• T011 Add or update a Feature/Livewire/HTTP test asserting a highest-priority attention operation shows operation type/title, outcome/status, reason, impact, environment, proof/artifact state, timing, and primary next action.
• T012 Add or update a Feature/Livewire/HTTP test asserting the no-attention empty state says no operations need attention and avoids false health claims.
• T013 Add or update a Feature/Livewire/HTTP test asserting the right operation/proof panel contains Operation summary, Outcome, Environment, Proof or artifact/evidence state, primary next action, and collapsed diagnostics.
• T014 Add or update a test asserting existing operations table/history rows, tabs, filters, row links, and empty state remain available as secondary context.
• T015 Add or update a test that raw diagnostics are hidden by default: raw payload, stack trace, debug metadata, provider secret, internal exception, and raw OperationRun context text must not appear.
• T016 Add or update progress tests proving terminal failed/blocked/partial/succeeded runs do not show progress bars.
• T017 Add or update progress tests proving determinate progress appears only for active runs with trustworthy processed and total counts.
• T018 Add or update RBAC tests covering primary action visibility/unavailability for open operation, open artifact/evidence, open related source, open diagnostics, retry/resume/cancel if any existing action is shown.
• T019 Add or update canonical environment filter tests for ?environment_id=, visible chip, workspace shell only, clear filter, and provable filtered data.
• T020 Add or update legacy alias rejection tests for tenant, tenant_id, managed_environment_id, environment, tenant_scope, and tableFilters.
• T021 Add or update cross-workspace environment filter guard test returning safe 404/no-access.
• T022 Add or update tenant-copy guard asserting platform-context copy such as current tenant, tenant filter, entitled tenant, and all tenants is not visible on Operations Hub.

Phase 3: Page Skeleton Productization

Purpose: Refactor existing page layout without new backend foundation.

• T023 Update apps/platform/app/Filament/Pages/Monitoring/Operations.php to expose a repo-truth-bounded payload for header/scope, selected/highest-priority operation, summary cards, table context, detail/proof panel, actions, progress state, and diagnostics disclosure.
• T024 Update apps/platform/resources/views/filament/pages/monitoring/operations.blade.php to render the decision-first workbench before the secondary operations table.
• T025 Ensure the header/scope area shows workspace-wide vs environment-filtered context, visible environment chip when filtered, and concise execution-truth copy.
• T026 Ensure the main workbench shows the stable question, status/outcome badge, operation title/type, reason, impact, environment, timing, proof/artifact state, and one primary next action.
• T027 Ensure summary cards show only repo-backed posture such as needs attention, active operations, failed/blocked, follow-up required, completed recently, or artifact available; show unavailable or omit unsupported cards.
• T028 Ensure the right-side operation/proof panel shows operation summary, outcome, environment, timing, progress state if active/trustworthy, artifact/evidence/proof state, related links where available, primary next action, and diagnostics disclosure.
• T029 Ensure the right-side detail panel is visible on desktop and stacks below on smaller screens.
• T030 Keep the existing operations table/history as secondary content; it must not be the only default experience.
• T031 Ensure diagnostics/internal details are collapsed, hidden, or capability-gated by default.

Phase 4: Data Binding And Honest States

Purpose: Bind to repo-verified sources and avoid false claims.

• T032 Map selected/highest-priority operation state from existing OperationRun status, outcome, problem class, freshness, timestamps, and source links without creating persisted state.
• T033 Bind reason and impact to existing outcome, problem class, lifecycle/freshness guidance, failure summary summaries, OperationUxPresenter, ReasonPresenter, and artifact truth only where safe; show unavailable state otherwise.
• T034 Bind environment display to the existing ManagedEnvironment relation where accessible; show workspace-only or unavailable state for tenantless runs.
• T035 Bind proof/artifact/evidence display to existing OperationRunLinks::related(), artifact truth, and related resources only; show unavailable or omit unsupported proof paths.
• T036 Bind operation detail links only through existing OperationRunLinks and authorized source routes.
• T037 Ensure completed successful operations are described as execution results, not environment health or governance health.
• T038 Ensure no generic green success state appears without exact repo-backed proof.

Phase 5: Progress And Outcome Semantics

Purpose: Preserve OperationRun progress contract and terminal semantics.

• T039 Use OperationRunProgressContract or existing equivalent logic for progress display decisions.
• T040 Show determinate progress only for active runs with valid processed and total counts.
• T041 Show activity/status-only treatment for queued/running runs without trustworthy counts.
• T042 Show outcome guidance, not progress, for terminal succeeded/failed/blocked/partial/follow-up states.
• T043 Preserve existing summary_counts whitelist semantics through OperationSummaryKeys; do not add new keys.
• T044 Preserve OperationRun.status and OperationRun.outcome lifecycle ownership; do not mutate them from the page.

Phase 6: Actions, RBAC, And Safety

Purpose: Show only real, authorized actions and preserve read-first default behavior.

• T045 Keep primary action singular and context-aware for the selected/highest-priority operation.
• T046 Show open operation, open artifact, open evidence, open related source, review failure, open related alert/finding/review, view diagnostics, retry/resume, or cancel only when route/action and authorization are repo-real.
• T047 Ensure unauthorized actions are hidden or unavailable without leaking sensitive details.
• T048 Verify no default action restores, deletes, cancels, retries, reruns, or mutates provider state unless it already exists and is properly secondary.
• T049 If any high-impact action is unexpectedly required, update spec/plan first, then implement it with Action::make(...)->action(...), ->requiresConfirmation(), server-side authorization, audit, notification, and tests.

Phase 7: Workspace / Environment Scope Contract

Purpose: Preserve Specs 314-322.

• T050 Verify clean OperationRunLinks::index() does not read remembered environment shell state or persisted table filters.
• T051 Verify OperationRunLinks::index(... environment_id ...) filters only page data, shows visible chip, and keeps Workspace shell ownership.
• T052 Verify clear filter redirects to clean workspace URL and remains safe after reload.
• T053 Verify legacy aliases are removed/neutralized and do not set filter state.
• T054 Verify cross-workspace or unauthorized environment_id returns safe no-access/404.
• T055 Verify back/forward/reload behavior does not resurrect cleared environment filter state.

Phase 8: Browser Smoke And Screenshots

Purpose: Prove the user-facing contract in the integrated browser lane.

• T056 Create apps/platform/tests/Browser/Spec328OperationsHubProductizationSmokeTest.php using existing Pest Browser conventions.
• T057 Browser Flow A: clean workspace entry; assert Workspace shell only, no Environment chip, main decision question, right proof panel, diagnostics collapsed, screenshot.
• T058 Browser Flow B: filtered environment entry; assert Workspace shell only, visible chip, clear filter action, filtered scope copy, screenshot.
• T059 Browser Flow C: clear filter and reload; assert clean URL, chip does not return, no active Environment shell.
• T060 Browser Flow D: non-empty operation needing attention; assert outcome, reason, impact, environment, proof/artifact state, primary action, and diagnostics absent by default.
• T061 Browser Flow E: empty/no-attention state; assert clear empty state and no false success/health claim.
• T062 Browser Flow F: operations table/history remains visible lower/secondary and no platform-context tenant wording appears.
• T063 Browser Flow G: light mode readability check if supported; capture optional screenshot.
• T064 Save screenshots under specs/328-operations-hub-decision-first-workbench-productization/artifacts/screenshots/ when generated and ensure they contain no secrets.

Phase 9: UI Coverage And Documentation Artifacts

Purpose: Satisfy UI-COV without unrelated docs churn.

• T065 Decide after runtime diff whether docs/ui-ux-enterprise-audit/route-inventory.md or design-coverage-matrix.md needs an update.
• T066 If coverage docs are not changed, add a close-out note explaining why existing UI-003 report plus Spec 325 target artifacts remain sufficient for the unchanged route/archetype.
• T067 Update repo-truth-map.md final classifications for implemented/empty/deferred elements.
• T068 Do not create general documentation files outside required Spec Kit/UI coverage artifacts.

Phase 10: Validation

Purpose: Run narrow proof and report honestly.

• T069 Run 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.
• T070 Run cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec328OperationsHubProductizationSmokeTest.php --compact.
• T071 Run cd apps/platform && ./vendor/bin/sail artisan test --filter='Operations|OperationRun|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact.
• T072 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
• T073 Run git diff --check.
• T074 Report full-suite status honestly if not run.
• T075 Confirm no migrations, seeders, packages, env vars, queues, scheduler, storage, deployment assets, backwards compatibility layer, or legacy tenant alias support were added.

Phase 11: Follow-Up Summary Card Alignment

Purpose: Align the four Operations Workbench summary cards with compact Filament KPI/Stats-card visual density without changing execution-truth semantics.

• T076 Update spec.md and plan.md with the follow-up rule that summary cards are execution/attention signals, not generic business KPIs.
• T077 Refine the four summary cards to use compact native Filament Stats Overview hierarchy: title, large value, concise subline, optional description icon, and semantic status color.
• T078 Ensure Needs attention has the strongest warning emphasis only when actionable.
• T079 Ensure Active operations is neutral when its value is 0.
• T080 Ensure Completed recently remains muted success/secondary and does not imply environment or governance health.
• T081 Confirm no fake trends, fake sparklines, decorative charts, Total Operations, or Avg Duration cards appear before the workbench.
• T082 Verify the refined cards in the Integrated Browser in light and dark mode where supported.
• T083 Re-run the requested Feature, Browser, Pint, and diff validation commands.

Phase 12: Native Filament Stats Follow-Up

Purpose: Replace the custom Blade/Tailwind summary card rebuild with native Filament Stats Overview cards while preserving Spec 328 execution-truth semantics.

• T084 Add a narrow OperationsWorkbenchStats widget using StatsOverviewWidget and Stat::make(...).
• T085 Scope widget counts to the current workspace and canonical optional environment_id.
• T086 Render the widget above the decision workbench and remove the custom summary card loop/accent bars.
• T087 Update Feature and Browser smoke tests to assert the four native Stat labels/values and no fake charts/trends.
• T088 Update spec close-out and repo truth map to document native widget rendering.
• T089 Re-run requested Feature, Browser, navigation contract, Pint, and diff validation.
• T090 Refresh operations-hub-premium-summary-cards.png.

Non-Goals Checklist

• NT001 Do not rebuild OperationRun backend.
• NT002 Do not build a new queue engine or observability platform.
• NT003 Do not turn Operations Hub into a governance health dashboard.
• NT004 Do not redesign Governance Inbox, Customer Review Workspace, Evidence Overview, Environment Dashboard, Baseline Compare, Restore, Backup, or Provider Readiness.
• NT005 Do not add AI prioritization or summarization.
• NT006 Do not add migrations unless spec/plan are updated first with proof.
• NT007 Do not add new operation types, statuses, outcomes, priority enums, or summary-count keys.
• NT008 Do not rewrite completed Specs 314-327.
• NT009 Do not add legacy tenant query alias support.

Required Final Report Content

When implementation later completes, report:

• Changed behavior.
• Decision-first operations workbench details.
• OperationRun outcome/progress/proof coverage.
• Files changed.
• Repo truth map status.
• Tests run and results.
• Browser verification and screenshots path.
• Known gaps.
• Remaining follow-ups.
• Diagnostics default state.
• RBAC-visible/hidden actions.
• Repo-verified vs unavailable states.
• Full suite run/not run.
• Explicit no migrations/seeders/packages/env/queues/scheduler/storage/deployment assets/backcompat/legacy aliases statement.