TenantAtlas/specs/365-operations-ui-operator-actions-regression-gate/plan.md

# Implementation Plan: Operations UI Operator Actions & Regression Gate

**Branch**: `365-operations-ui-operator-actions-regression-gate` | **Date**: 2026-06-07 | **Spec**: [spec.md](./spec.md)  
**Input**: Feature specification from `/specs/365-operations-ui-operator-actions-regression-gate/spec.md`

**Note**: This plan is a preparation artifact only. It defines the implementation path and validation gate; it does not implement application code.

## Summary

Spec 365 completes the OperationRun/Reconciliation program by making existing run truth operator-actionable in the existing Operations hub and OperationRun detail. The implementation approach is to add one central derived action eligibility resolver, reuse existing reconciliation and related-link seams, integrate safe actions into existing Filament surfaces, and add a final regression matrix across Specs 358-364.

The plan intentionally does not introduce a new adapter framework, a generic retry engine, a new persisted action table, or new top-level Operations pages. Retry is limited to operation families with a repo-verified safe retry/start seam; unsupported families fail closed with a disabled/deferred reason.

## 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, Laravel Sail 1.x  
**Storage**: PostgreSQL; existing `operation_runs` table/context JSON only. No new table planned.  
**Testing**: Pest 4 unit/feature/browser tests. Filament action tests must mount Livewire components/pages, not static resource classes.  
**Validation Lanes**: fast-feedback, confidence, browser.  
**Target Platform**: Laravel web application under `apps/platform`.  
**Project Type**: Laravel + Filament application.  
**Performance Goals**: Operations hub and detail remain DB-only render paths for run status; no Graph/provider calls during UI render.  
**Constraints**: Fail closed for uncertain actions; no high-risk retry; no force-success; no raw diagnostics by default; no asset changes unless proven necessary.  
**Scale/Scope**: Existing Operations hub/detail and related domain links. No new top-level IA.

## Repo Truth Captured During Prep

- Current branch at prep time: `365-operations-ui-operator-actions-regression-gate`
- Baseline HEAD: `3ce1cae7 feat: implement restore high risk operation reconciliation (#435)`
- Baseline status before artifacts: clean except the new Spec 365 directory.
- Spec 364 baseline context: restore high-risk reconciliation has completed task/checklist artifacts and is treated as the immediate completed predecessor.
- Current package baseline from Laravel Boost:
  - PHP 8.4.15
  - Laravel 12.52.0
  - Filament 5.2.1
  - Livewire 4.1.4
  - Pest 4.3.1

Relevant implementation files discovered:

```text
apps/platform/app/Models/OperationRun.php
apps/platform/app/Services/OperationRunService.php
apps/platform/app/Services/AdapterRunReconciler.php
apps/platform/app/Support/Operations/Reconciliation/OperationRunReconciliationRegistry.php
apps/platform/app/Support/Operations/Reconciliation/*
apps/platform/app/Support/OperationRunType.php
apps/platform/app/Support/OperationRunStatus.php
apps/platform/app/Support/OperationRunOutcome.php
apps/platform/app/Support/OperationCatalog.php
apps/platform/app/Support/OperationRunCapabilityResolver.php
apps/platform/app/Support/Auth/Capabilities.php
apps/platform/app/Policies/OperationRunPolicy.php
apps/platform/app/Support/OpsUx/OperationUxPresenter.php
apps/platform/app/Support/OpsUx/OperationRunProgressContract.php
apps/platform/app/Support/OperationRunLinks.php
apps/platform/app/Support/Navigation/RelatedNavigationResolver.php
apps/platform/app/Support/Navigation/RelatedActionLabelCatalog.php
apps/platform/app/Filament/Pages/Monitoring/Operations.php
apps/platform/app/Filament/Resources/OperationRunResource.php
apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
apps/platform/app/Services/Audit/AuditRecorder.php
apps/platform/app/Services/Audit/WorkspaceAuditLogger.php
```

Repo-specific decisions:

- `OperationRunService` remains the write seam for OperationRun state/outcome/reconciliation transitions.
- `AdapterRunReconciler` and `OperationRunReconciliationRegistry` are the only approved reconciliation execution path.
- `OperationRunLinks` / `RelatedNavigationResolver` are the preferred related-object navigation path.
- `OperationRunPolicy` and `OperationRunCapabilityResolver` remain the authorization entry points; do not use raw capability strings.
- `TenantlessOperationRunViewer::resumeCaptureAction()` is a narrow existing resume-like seam and must be reconciled into the central eligibility model if touched.
- No repo-wide generic retry seam was found during prep; broad retry must remain unavailable/deferred unless implementation verifies or adds a bounded safe seam per operation family.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/workspaces/{workspace}/operations`
  - tenantless OperationRun detail page
  - OperationRun detail header action groups
  - related domain object action links
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: mixed but Filament-native first. Reuse existing native table/detail actions and existing OperationRun detail sections; avoid new styling systems.
- **Shared-family relevance**: status messaging, header actions, related navigation, evidence/report/restore links, diagnostics disclosure.
- **State layers in scope**: page, table row, detail header, detail sections, action modal state.
- **Audience modes in scope**: operator-MSP and support-platform; customer-readable defaults must remain calm and non-technical.
- **Decision/diagnostic/raw hierarchy plan**: decision-first default, diagnostics second, support/raw third.
- **Raw/support gating plan**: collapsed and capability-gated.
- **One-primary-action / duplicate-truth control**: `OperationRunActionEligibility` output is the single source for primary action and disabled reasons consumed by list/detail/actions.
- **Handling modes by drift class or surface**: review-mandatory for high-risk action surface and raw leakage guard.
- **Repository-signal treatment**: report-only for existing Operations page audit docs unless implementation materially changes IA; review-mandatory for dangerous-action and customer-safe checks.
- **Special surface test profiles**: monitoring-state-page, shared-detail-family.
- **Required tests or manual smoke**: functional core + state-contract + browser smoke.
- **Exception path and spread control**: none planned. Any generic retry exception must be documented in this feature and covered by tests.
- **Active feature PR close-out entry**: Guardrail + Smoke Coverage.
- **UI/Productization coverage decision**: Existing strategic Operations page is materially changed; update existing coverage docs or record proportional no-update rationale during implementation close-out.
- **Coverage artifacts to update**: update `docs/ui-ux-enterprise-audit/page-reports/ui-003-operations.md` / design matrix when implementation changes layout, action hierarchy, state hierarchy, or screenshots materially. A no-update rationale is allowed only when changes are limited to existing pattern-compatible action/copy wiring, and that rationale must be recorded in `tasks.md` close-out.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: no panel provider or navigation change planned.
- **Screenshot or page-report need**: screenshot/browser artifact recommended for the final smoke; no new page report required during prep.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: OperationRun UX presenter/progress, related navigation, reconciliation registry/service, authorization policy/capability resolver, audit logging, localization.
- **Shared abstractions reused**: `OperationUxPresenter`, `OperationRunProgressContract`, `OperationRunLinks`, `RelatedNavigationResolver`, `AdapterRunReconciler`, `OperationRunService`, `OperationRunPolicy`.
- **New abstraction introduced? why?**: Yes, a narrow action eligibility resolver because no existing shared layer combines status/outcome/freshness/risk/adapter/RBAC/scope/related metadata into a single action contract.
- **Why the existing abstraction was sufficient or insufficient**: Existing presenters and services are sufficient for summaries, links, and writes, but insufficient for one-primary-action and action permission consistency.
- **Bounded deviation / spread control**: The resolver must not create a new operation taxonomy, adapter registry, or persisted action model.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes.
- **Central contract reused**: `OperationUxPresenter`, `OperationRunProgressContract`, `OperationRunLinks`, `OperationRunService`.
- **Delegated UX behaviors**: artifact links, run detail links, reconciliation result handling, lifecycle result display, tenant/workspace-safe URLs.
- **Surface-owned behavior kept local**: visible hierarchy and invocation of approved actions.
- **Queued DB-notification policy**: no new policy.
- **Terminal notification path**: existing central lifecycle mechanism.
- **Exception path**: Generic retry is not approved by this plan. If implemented, it must be through an existing or bounded safe start seam with explicit tests and audit.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes, bounded.
- **Provider-owned seams**: existing provider reason codes and provider failure summaries in canonical OperationRun context.
- **Platform-core seams**: OperationRun action eligibility, outcome summaries, high-risk classification, related action display.
- **Neutral platform terms / contracts preserved**: operation, outcome, attention, reconcile, retry, verification, partial, blocked, related evidence.
- **Retained provider-specific semantics and why**: Provider reason codes remain diagnostics only because they help operators/support understand blocked/partial states.
- **Bounded extraction or follow-up path**: none planned.

## Constitution Check

*GATE: Must pass before implementation. Re-check after design and before code merge.*

- Inventory-first: PASS. This spec reads existing OperationRun and related artifact truth only.
- Read/write separation: PASS with constraints. Reconcile/retry are explicit operator actions with authorization, confirmation where appropriate, and audit.
- Graph contract path: PASS. No Graph calls in UI render or action eligibility. Retry seam, if any, must use existing service/jobs and Graph abstractions.
- Deterministic capabilities: PASS. Use `Capabilities` constants and `OperationRunCapabilityResolver`/policies. Add no raw strings.
- RBAC-UX: PASS. Preserve non-member/not-entitled 404 and member-missing-capability 403 semantics.
- Workspace isolation: PASS. All actions must enforce workspace/environment scope.
- Destructive-like actions: PASS. This spec forbids destructive and force-success actions. State-changing reconcile/retry actions require confirmation/audit as appropriate.
- Global search: PASS. `OperationRunResource` remains not globally searchable unless separately changed with View/Edit contract.
- Run observability: PASS. Reconcile uses existing run write seam; retry creates a run only through safe start seam.
- OperationRun start UX: PASS with constraint. Retry must reuse central start UX if implemented.
- Ops-UX 3-surface feedback: PASS. No new terminal DB notification behavior planned.
- Ops-UX lifecycle: PASS. `OperationRunService` owns state/outcome/reconciliation writes.
- Ops-UX summary counts: PASS. No new summary count keys planned; any touched keys must use `OperationSummaryKeys`.
- Data minimization: PASS. Raw context hidden/gated; no secrets in audit.
- Test governance: PASS. Unit, feature, and browser lane plans are explicit.
- Proportionality: PASS. New resolver is justified by safety, RBAC, high-risk guard, and multiple current concrete run families.
- No premature abstraction: PASS. One resolver replaces scattered action decision logic and is not a registry/framework.
- Persisted truth: PASS. No new independent persisted truth.
- Behavioral state: PASS. No new status/outcome family.
- UI semantics: PASS. Derived summaries and actions map from existing domain/run truth.
- Shared pattern first: PASS. Existing presenters/links/services are reused.
- Provider boundary: PASS. Provider details remain diagnostics only.
- V1 explicitness / few layers: PASS. One narrow derived layer.
- Spec discipline / bloat check: PASS. Proportionality review complete.
- Badge semantics: PASS. Implementation must reuse badge/shared status rendering if status-like badges change.
- Filament-native UI: PASS. Use native Filament actions/sections and existing shared primitives.
- UI/UX surface taxonomy: PASS. Surfaces classified.
- Decision-first operating model: PASS. Required default-visible fields and hierarchy defined.
- Audience-aware disclosure: PASS. Raw/support content hidden/gated.
- Filament UI Action Surface Contract: PASS with implementation tasks.
- UI/Productization coverage: PASS. Impact classified; coverage update/no-update rationale required at close-out.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit for resolver/presenter; Feature for actions/RBAC/scope/audit/related links; Browser for Operations UI decision-first and raw leakage guard.
- **Affected validation lanes**: fast-feedback, confidence, browser.
- **Why this lane mix is the narrowest sufficient proof**: Action safety is mostly deterministic logic plus server-side enforcement; browser coverage is limited to the user-visible matrix and leakage guard.
- **Narrowest proving command(s)**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec365`
  - `cd apps/platform && ./vendor/bin/pint --dirty`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: Need canonical OperationRun fixtures for each matrix state; keep as explicit Spec365 helpers only.
- **Expensive defaults or shared helper growth introduced?**: no; browser fixtures must not become global defaults.
- **Heavy-family additions, promotions, or visibility changes**: one explicit browser smoke file.
- **Surface-class relief / special coverage rule**: monitoring-state-page/shared-detail-family special coverage applies.
- **Closing validation and reviewer handoff**: Run Spec365 plus Spec358-364 regression filters and browser smoke. Review retry deferrals explicitly.
- **Budget / baseline / trend follow-up**: none expected.
- **Review-stop questions**: Does any action bypass resolver/policy? Does any retry path lack a safe start seam? Does high-risk restore expose unsafe copy/action? Are raw diagnostics default-visible? Does every state-changing action disclose TenantPilot-only, Microsoft-tenant, or simulation-only scope before execution?
- **Escalation path**: document-in-feature for retry/acknowledge deferrals; follow-up-spec for a generic retry framework.
- **Active feature PR close-out entry**: Guardrail + Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: This completes the current OperationRun/Reconciliation program without introducing a larger governance inbox.

## Project Structure

### Documentation (this feature)

```text
specs/365-operations-ui-operator-actions-regression-gate/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── artifacts/
    ├── spec365-action-eligibility-matrix.md
    └── spec365-regression-gate-matrix.md
```

### Source Code (repository root)

Expected implementation paths:

```text
apps/platform/app/
├── Filament/
│   ├── Pages/Monitoring/Operations.php
│   ├── Pages/Operations/TenantlessOperationRunViewer.php
│   └── Resources/OperationRunResource.php
├── Policies/OperationRunPolicy.php
├── Services/OperationRunService.php
├── Services/AdapterRunReconciler.php
├── Support/
│   ├── Auth/Capabilities.php
│   ├── OperationRunCapabilityResolver.php
│   ├── OperationRunLinks.php
│   ├── OpsUx/
│   │   ├── OperationUxPresenter.php
│   │   └── OperationRunProgressContract.php
│   └── Operations/
│       ├── OperationRunActionEligibility.php
│       └── Reconciliation/
│           └── OperationRunReconciliationRegistry.php
└── Services/Audit/
    ├── AuditRecorder.php
    └── WorkspaceAuditLogger.php

apps/platform/lang/
├── en/localization.php
└── de/localization.php

apps/platform/tests/
├── Unit/Support/Operations/
├── Unit/Support/OpsUx/
├── Feature/Operations/
└── Browser/
```

## Phase 0 - Research

Completed during prep:

- Read repository governance and architecture docs required by `AGENTS.md`.
- Verified installed Laravel/Filament/Livewire/Pest versions with Laravel Boost.
- Searched current Filament/Livewire/Pest docs through Laravel Boost for action confirmation/testing/global search constraints.
- Audited OperationRun model/service/reconciliation registry/link/policy/presenter/UI files.
- Checked completed Specs 358-364 for baseline context and scope continuity.

Research conclusions:

- Central action eligibility is justified.
- Reconcile can reuse existing registry/reconciler/service seams.
- Related links should reuse existing link/navigation resolvers.
- Generic retry is not repo-real yet and must be explicitly bounded.
- OperationRun acknowledge should be deferred unless a clean existing seam is verified during implementation.

## Phase 1 - Design

Design artifacts:

- `artifacts/spec365-action-eligibility-matrix.md`
- `artifacts/spec365-regression-gate-matrix.md`

Primary design decisions:

1. Use one derived resolver for action decisions.
2. Keep writes service-owned.
3. Keep related navigation canonical and scope-safe.
4. Keep high-risk operations fail-closed.
5. Keep raw/support diagnostics hidden and gated.
6. Keep Operations as the central surface.

## Phase 2 - Implementation Approach

Implementation sequence:

1. Add resolver and DTO/presenter tests first.
2. Add high-risk guard and forbidden-action tests.
3. Wire related links and detail/list primary action display.
4. Add safe reconcile Filament action with policy/audit/scope enforcement.
5. Verify retry seams; implement only safe non-high-risk retry or document deferral.
6. Add localization and summary presenter copy.
7. Add feature tests for actions/RBAC/scope/audit.
8. Add browser smoke for representative Operations UI states.
9. Run Spec365 and Spec358-364 regression gate, including Spec363.

## Risk Register

| Risk | Impact | Mitigation |
|---|---|---|
| Generic retry grows into unsafe re-execution framework | High | Implement only repo-verified seams; otherwise disabled/deferred reason |
| UI action visibility diverges from direct action authorization | High | Central resolver plus policy checks plus direct-action feature tests |
| Restore/high-risk shows unsafe next action | High | High-risk guard unit/feature/browser tests |
| Raw provider/SQL/queue leakage appears in default UI | High | Presenter sanitization and browser leakage guard |
| Related links bypass scope checks | High | Reuse existing link/policy resolvers and add cross-scope tests |
| New resolver becomes taxonomy framework | Medium | Keep derived, non-persisted, no new enum/status family |

## Deployment / Ops Impact

- Migrations: none planned.
- Environment variables: none planned.
- Queue/cron workers: no new workers planned; retry, if implemented, must use existing queues/jobs for that operation family.
- Storage/volumes: none.
- Assets: none planned. If implementation unexpectedly registers Filament assets, deploy must include `cd apps/platform && php artisan filament:assets`.
- Staging validation: required before production because this touches operator action affordances and high-risk restore safety.

## Open Questions for Implementation

1. Which existing capability constants should govern `reconcile`, `retry`, and `view diagnostics` for each operation family?
2. Is there a clean existing OperationRun acknowledge/note/audit seam? If not, acknowledge is deferred.
3. Which non-high-risk operation families have a safe idempotent retry/start seam today?
4. Should action metadata live only in existing audit logs, or also in bounded `context.operator_actions` for UI display?
5. Does implementation materially change the Operations page enough to require updating the UI audit page report/design matrix?

## Implementation Stop Conditions

- Stop and update spec/plan before adding a generic retry framework.
- Stop and update spec/plan before adding a new table/entity/status/outcome family.
- Stop before introducing any restore retry/re-execute or force-success action.
- Stop if action execution cannot be made server-side RBAC/scope-safe.
- Stop if state-changing action copy cannot make mutation scope explicit before execution.
- Stop if raw diagnostics cannot be gated/collapsed without broader UI redesign.