# Implementation Plan: Spec 371 - Core Operator View Surfaces Productization Pass v1

**Branch**: `371-core-operator-view-surfaces-productization` | **Date**: 2026-06-10 | **Spec**: `specs/371-core-operator-view-surfaces-productization/spec.md`
**Input**: Feature specification from `specs/371-core-operator-view-surfaces-productization/spec.md`

## Summary

Implement a bounded Backup Set list/detail productization pass that consumes Spec 370's decision-first IA contract and resolves the remaining Spec 368 Candidate B backup-set gap. The runtime work must make backup usability, included items, degradation/blocker state, and the safest next action visible before lifecycle metadata and technical context.

The plan intentionally narrows the user-provided six-page draft: Environment Dashboard, Operations Hub, OperationRun View, Restore Run View, and Baseline Profile View already have completed/validated productization specs and remain regression/context surfaces only. No completed spec package is edited.

## Technical Context

**Language/Version**: PHP 8.4, Laravel 12, Filament v5, Livewire v4.
**Primary Dependencies**: Existing Filament resources/pages, backup quality helpers, resource-level capability/UI enforcement, OperationRun link helpers, Pest 4, browser smoke harness.
**Storage**: Existing database only. No migration or new persistence expected.
**Testing**: Pest Feature/Livewire tests and bounded Browser smoke.
**Validation Lanes**: fast-feedback/confidence for Feature tests; browser for Backup Set list/detail smoke; `git diff --check`; Pint for touched PHP.
**Target Platform**: TenantPilot Laravel monolith under `apps/platform`.
**Project Type**: Laravel/Filament admin UI.
**Performance Goals**: No new per-row service calls or Graph calls during render; avoid N+1 regressions on backup item counts/quality.
**Constraints**: No restore/capture backend behavior changes, no Graph calls, no route additions, no completed-spec artifact edits, no broad UI framework, no migrations.
**Scale/Scope**: Existing Backup Sets list and Backup Set detail, plus spec-local artifacts and UI audit coverage updates.

## Candidate Selection Gate

- **Selected candidate exists in source material**: yes, user-provided Spec 371 draft and Spec 368 Candidate B.
- **Not already covered by active/completed spec**: partially. The broad six-page draft overlaps completed specs; the narrowed backup-set implementation slice is not covered by a completed productization spec.
- **Completed-spec guardrail**: PASS. Specs 328, 330, 335, 352, 367, 369, and 370 are context only and must not be modified.
- **Roadmap fit**: PASS. Backup/restore trust and operator productization are active product goals.
- **Smallest viable slice**: PASS. Backup Set list/detail only, with browser proof.
- **Deferred adjacent work**: customer/auditor surfaces, diagnostics, provider readiness, system panel, UI bloat guard, and completed-surface refreshes.
- **Gate result**: PASS.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed existing operator-facing backup/restore surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/workspaces/{workspace}/environments/{environment}/backup-sets`
  - `/admin/workspaces/{workspace}/environments/{environment}/backup-sets/{record}`
  - `BackupSetResource`, `ListBackupSets`, `ViewBackupSet`, `BackupItemsRelationManager`
- **No-impact class**: N/A.
- **Native vs custom classification summary**: Native Filament resource/table/infolist/action patterns first; optional small page-local helper only if it reduces review risk.
- **Shared-family relevance**: status messaging, backup quality/readiness, action links, OperationRun links, restore-adjacent safety copy, evidence/diagnostics disclosure.
- **State layers in scope**: route scope, page/detail derived display state, table/relation state.
- **Audience modes in scope**: operator-MSP, workspace manager, readonly reviewer, support reviewer.
- **Decision/diagnostic/raw hierarchy plan**: backup usability and included items first; operation context, timestamps, raw IDs, provider internals, raw payloads, and technical counters secondary/collapsed.
- **Raw/support gating plan**: raw/support detail collapsed, secondary, or capability-gated by default.
- **One-primary-action / duplicate-truth control**: one dominant action such as Review backup items, Open backup set, Open operation, or another already-existing safe action. No new restore-from-backup action/link is planned.
- **Handling modes by drift class or surface**: backup-surface changes are in scope; changes to completed context surfaces are hard-stop unless spec/plan are updated.
- **Repository-signal treatment**: Spec 368 backup-set finding is implementation input; UI-013/UI-052 fixture gaps are review-mandatory.
- **Special surface test profiles**: backup/restore strategic surface and shared-detail-family.
- **Required tests or manual smoke**: focused Feature/Livewire tests plus Browser smoke with screenshots.
- **Exception path and spread control**: any fixture expansion beyond Backup Set proof must be documented in `validation-report.md` and may require follow-up.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **Coverage artifacts to update**: `docs/ui-ux-enterprise-audit/page-reports/ui-013-environment-backup-sets.md` and coverage matrix/route inventory if status changes.
- **Navigation / Filament provider-panel handling**: no provider registration or navigation changes expected. Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: before screenshot from Spec 368, after screenshots under this package.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**:
  - `apps/platform/app/Filament/Resources/BackupSetResource.php`
  - `apps/platform/app/Filament/Resources/BackupSetResource/Pages/ListBackupSets.php`
  - `apps/platform/app/Filament/Resources/BackupSetResource/Pages/ViewBackupSet.php`
  - `apps/platform/app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`
  - existing backup quality and badge helpers
  - existing OperationRun link helpers
  - existing backup/restore action tests
  - UI audit registry/page report
- **Shared abstractions reused**: existing backup quality summary, badges, `UiEnforcement`/`WorkspaceUiEnforcement`, OperationRun link/presenter helpers.
- **New abstraction introduced? why?**: none expected. If page logic becomes hard to review, add one derived backup-local helper/presenter and justify it in the implementation close-out.
- **Why existing abstractions are sufficient**: backup quality, item inventory, operation links, and action safety already exist. The gap is display hierarchy and browser proof.
- **Bounded deviation / spread control**: no global component, presenter framework, status taxonomy, or persisted backup readiness truth.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: existing backup operation links and existing backup actions only.
- **Central contract reused**: existing OperationRun links/presenter/browser event paths.
- **Delegated UX behaviors**: queued/open operation/dedupe feedback remain delegated to existing action implementations.
- **Surface-owned behavior kept local**: backup usability explanation and item inventory hierarchy.
- **Queued DB-notification policy**: unchanged.
- **Terminal notification path**: unchanged.
- **Exception path**: none expected.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: display only.
- **Provider-owned seams**: raw provider IDs, Graph payloads, provider-specific policy metadata, provider error detail.
- **Platform-core seams**: backup set, backup item, restore point, operation, evidence, diagnostics, managed environment.
- **Neutral platform terms preserved**: yes.
- **Retained provider-specific semantics and why**: captured policy/provider labels may remain item-level truth; raw/provider internals are not default primary copy.
- **Bounded extraction or follow-up path**: provider payload disclosure issues become document-in-feature or follow-up-spec.

## Constitution Check

- Inventory-first / snapshots-second: PASS. Existing backup snapshot truth is preserved.
- Read/write separation: PASS. UI display changes only; existing write actions keep preview/confirmation/audit where applicable.
- Graph contract path: PASS / N/A. No Graph calls.
- Deterministic capabilities: PASS. Existing capability/UI enforcement remains authoritative.
- RBAC-UX and isolation: PASS. Route-scoped workspace/environment checks must remain tested.
- OperationRun observability: PASS. Existing links/feedback preserved; no lifecycle change.
- Evidence/result truth separation: PASS. Backup usability, operation trace, restore proof, and diagnostics stay separated.
- Test governance: PASS. Feature and Browser lanes are explicit and narrow.
- Proportionality: PASS. No new persistence/status/framework; optional local helper only if necessary.
- UI/Productization coverage: PASS. Existing page changed and coverage update required.
- Shared pattern first: PASS. Reuse existing helpers and Spec 370 contract.
- Provider boundary: PASS. Provider-specific detail remains technical/support detail.
- Filament v5 / Livewire v4: PASS. Runtime work must use Filament v5 and Livewire v4 APIs only.

## Project Structure

```text
specs/371-core-operator-view-surfaces-productization/
|-- spec.md
|-- plan.md
|-- tasks.md
|-- checklists/
|   `-- requirements.md
`-- artifacts/
    |-- source-audit-summary.md
    |-- affected-files.md
    |-- before-after-screenshot-index.md
    |-- page-contracts.md
    |-- implementation-notes.md
    |-- browser-verification-report.md
    |-- validation-report.md
    `-- screenshots/
```

Runtime implementation is expected under existing backup-surface files only unless the spec is updated.

## Implementation Phases

### Phase 0 - Repo Truth And Scope Lock

- Confirm branch, working tree, source artifacts, current backup-set implementation, current action safety, and completed-spec guardrails.
- Update `source-audit-summary.md`, `affected-files.md`, and `page-contracts.md` before runtime edits.

### Phase 1 - Test First

- Add focused Feature/Livewire tests for Backup Set detail usability states, metadata demotion, item inventory priority, RBAC/scope, and dangerous-action preservation.
- Add list tests for scan-first quality/item/degradation presentation and empty state.
- Add or update browser smoke fixture/test for Backup Sets list/detail reachability and screenshot capture.

### Phase 2 - Backup Set Detail Productization

- Recompose `ViewBackupSet`/`BackupSetResource` detail content so the first viewport leads with usability, reason, impact, item count, current degradation/blocker, and one primary next action.
- Make included backup items primary content.
- Demote lifecycle/timing/operation context/raw technical metadata into secondary/collapsed/detail sections.
- Preserve all existing action handlers, resource-level capability checks, confirmations, audit behavior, notifications, and OperationRun links.

### Phase 3 - Backup Sets List Productization

- Ensure the list is scan-first: backup quality/usability, item count, degradation state, open/inspect path, and contextual operation link.
- Suppress zero/no-issue noise when healthy state is already clear.
- Keep empty state specific and capability-aware.

### Phase 4 - Browser Proof And UI Coverage

- Run bounded browser smoke and capture after screenshots.
- Update `before-after-screenshot-index.md`, `browser-verification-report.md`, and `validation-report.md`.
- Update UI audit coverage artifacts or record why route/archetype counts did not change.

### Phase 5 - Final Validation

- Run focused tests, browser smoke, Pint dirty, and `git diff --check`.
- Confirm no completed spec packages or out-of-scope runtime files were modified.
- Record final Livewire/Filament/global-search/destructive-action/asset/deploy/test impact in implementation close-out.

## Data Model

N/A. No tables, migrations, casts, indexes, JSONB changes, persisted readiness fields, or data backfills are planned.

## API / Contracts

N/A. No HTTP API, Graph contract, queue contract, package, external integration, or operation type changes are planned.

## UI / Filament Implications

- Filament v5 with Livewire v4.0+ remains required.
- No panel provider registration change is expected; Laravel 12 providers remain in `apps/platform/bootstrap/providers.php`.
- No global search enablement is expected. If `BackupSetResource` global-search metadata is touched, its effective non-participation must either be preserved by explicitly disabling global search or changed only with safe View/Edit pages, scoped URLs, `$recordTitleAttribute`, and tests.
- Existing destructive/high-impact actions must continue to use `Action::make(...)->action(...)`, `->requiresConfirmation()`, server-side authorization/capability checks, audit logging, and tests.
- No Filament assets are expected. If registered assets appear, deployment must run `cd apps/platform && php artisan filament:assets`.
- Tables must keep meaningful empty states and query-safe visible relationships.

## Test Strategy

- Feature/Livewire:
  - `Spec371BackupSetProductizationTest` for detail/list hierarchy, RBAC/scope, raw metadata demotion, action safety, and item inventory.
  - Existing `BackupSet*` tests remain green.
- Browser:
  - `Spec371BackupSetProductizationSmokeTest` for list/detail reachability, no JS errors, first-viewport hierarchy, and screenshots.
- Validation commands:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec371`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=BackupSet`
  - `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec371BackupSetProductizationSmokeTest.php --compact`
  - `cd apps/platform && ./vendor/bin/sail pint --dirty`
  - `git diff --check`

## Rollout Considerations

- No env var changes.
- No migrations.
- No queue/scheduler/storage changes.
- No Graph permission changes.
- No Filament asset deployment step expected.
- Staging validation should include browser proof for Backup Sets list/detail because this is a strategic backup/restore trust surface.

## Risk Controls

- Do not edit completed context specs.
- Do not change restore execution or backup capture behavior.
- Do not create new backup/restore truth.
- Do not default-show raw payloads or provider/internal IDs.
- Do not make destructive/high-impact actions more prominent without confirmation/authorization/audit proof.
- Stop and update spec/plan if shared helper changes affect Environment Dashboard, Operations Hub, OperationRun, Restore Run, or Baseline Profile.

## Spec Readiness Gate

- `spec.md`, `plan.md`, `tasks.md`: required and present after preparation.
- `checklists/requirements.md`: required.
- Source and page-contract artifacts: required.
- Blocking open questions: none.
- Runtime implementation scope: bounded to Backup Set list/detail and backup-set browser proof.
- Gate result: PASS.