TenantAtlas/specs/371-core-operator-view-surfaces-productization/plan.md

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

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.