TenantAtlas/specs/398-decision-page-contract-migration/plan.md

# Implementation Plan: Spec 398 - Decision Page Contract Migration v1

**Branch**: `398-decision-page-contract-migration`
**Spec**: `specs/398-decision-page-contract-migration/spec.md`
**Created**: 2026-06-22
**Mode**: Product Surface Contract decision-page runtime reduction over existing surfaces

## Summary

Migrate the existing Baseline Compare and Restore Preview / Restore Readiness decision surfaces to the Product Surface Contract's Decision Page rules. The implementation must reduce default-visible proof, diagnostics, long tables, duplicate readiness summaries, and technical deep links while preserving RBAC, auditability, OperationRun evidence access, and restore safety controls.

Risk Exception Detail is optional. It may be included only if implementation remains a narrow default-visible evidence demotion over existing `FindingExceptionResource` / `ViewFindingException` behavior.

No application implementation is performed by this preparation package.

## Technical Context

- **Language/Version**: PHP 8.4.15
- **Framework**: Laravel 12.52.0
- **Admin UI**: Filament 5.2.1
- **Reactive UI**: Livewire 4.1.4
- **Testing**: Pest 4.3.1 / PHPUnit 12
- **Database**: PostgreSQL
- **Local dev**: Laravel Sail first
- **Package constraints**: Do not add dependencies without explicit approval.
- **Panel provider location**: Laravel providers remain registered in `apps/platform/bootstrap/providers.php`; this spec must not add a panel provider.
- **Livewire v4 compliance**: Filament work must use Filament v5 / Livewire v4 APIs only; no Livewire v3 references.

## Constitution Check

- **Workspace/tenant isolation**: Pass with implementation requirement. Existing workspace + managed environment route scoping remains authoritative; out-of-scope records remain deny-as-not-found.
- **RBAC first**: Pass with implementation requirement. UI visibility is not authorization; mutating actions keep server-side checks.
- **Audit first**: Pass. Audit and OperationRun evidence are demoted from default product view but not removed.
- **Read/write separation**: Pass. Baseline Compare rendering and restore preview decisions are read-oriented by default; restore execution and compare start remain existing high-impact operations with confirmation and capabilities.
- **Product Surface Contract Gate**: Pass by design. This spec is a Product Surface Contract migration and requires browser proof plus Human Product Sanity.
- **Proportionality**: Pass. No new persisted entity, enum/status family, runtime framework, provider abstraction, or broad presenter family is approved.

## Current Repo Truth

### Baseline Compare

Relevant surfaces:

- `apps/platform/app/Filament/Pages/BaselineCompareLanding.php`
- `apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php`
- `apps/platform/tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php`
- `apps/platform/tests/Feature/Filament/Spec330EnvironmentDashboardBaselineCompareProductizationTest.php`
- `apps/platform/tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php`

Repo observations:

- Route slug is `workspaces/{workspace}/environments/{environment}/baseline-compare`.
- The page already has decision-card, proof-panel, readiness-flow, and diagnostics concepts.
- Current code still contains default labels/copy such as `OperationRun proof`, evidence-gap diagnostics, RBAC summaries, and multiple proof/detail sections that can compete with the primary decision.
- `Compare now` uses a Filament action with `->requiresConfirmation()` and existing capability/OperationRun behavior. This safety posture must remain.

### Restore Preview / Readiness

Relevant surfaces:

- `apps/platform/app/Filament/Resources/RestoreRunResource.php`
- `apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php`
- `apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php`
- `apps/platform/tests/Feature/Filament/RestorePreviewTest.php`
- `apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php`
- `apps/platform/tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php`
- `apps/platform/tests/Feature/Filament/Spec390RestoreReadinessGuidanceTest.php`
- `apps/platform/tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php`
- `apps/platform/tests/Browser/Spec332RestoreRunWizardProductProcessFlowSmokeTest.php`

Repo observations:

- `RestoreRunResource` is not globally searchable.
- Restore create uses `CreateRestoreRun` with a Filament wizard and `RestoreRunCreatePresenter` contract.
- The presenter already distinguishes scope, checks, preview, provider readiness, proof items, diagnostics disclosure, dry-run/acknowledgement, and confirmation state.
- Implementation must reduce default duplication without weakening safety or execution gates.

### Risk Exception Detail (optional)

Relevant surfaces:

- `apps/platform/app/Filament/Resources/FindingExceptionResource.php`
- `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php`
- `apps/platform/resources/views/filament/infolists/entries/accepted-risk-guidance.blade.php`
- `apps/platform/tests/Feature/Findings/FindingExceptionDetailDecisionSummaryTest.php`
- `apps/platform/tests/Feature/Findings/Spec354FindingExceptionDetailGuidanceTest.php`
- `apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php`
- `apps/platform/tests/Browser/Spec354AcceptedRiskGuidanceSmokeTest.php`

Repo observations:

- `FindingExceptionResource` is not globally searchable.
- `ViewFindingException` exposes `renew_exception` and `revoke_exception` with `->requiresConfirmation()` and service-backed actions.
- `FindingExceptionResource` contains evidence-reference fields including Source ID, Fingerprint, and JSON summary payload. These are candidates for default demotion if the optional slice is included.
- Spec 354 already productized accepted-risk guidance; this spec must not reopen that workflow.

## Technical Approach

1. Start with discovery and failing/adjusted tests for default-visible hierarchy on Baseline Compare and Restore Preview.
2. For each target surface, identify the current default-visible sections and classify each as Product Layer or Technical Evidence Layer.
3. Update existing page/presenter output so the Product Layer is first and compact:
   - one primary decision question
   - one canonical status
   - one recommended next action
   - impact summary
   - top material blockers/differences
4. Move, collapse, cap, or relabel technical detail:
   - OperationRun proof
   - evidence/raw links
   - source keys, detectors, fingerprints, UUIDs
   - raw payloads/provider responses/logs
   - full diff/preview/diagnostic tables
5. Preserve existing service/action ownership for mutations. Do not move business logic into Blade.
6. If optional Risk Exception cleanup is included, only demote default-visible raw evidence/reference fields and preserve Spec 354 guidance and current renew/revoke behavior.
7. Update UI coverage registry artifacts for each rendered surface changed.
8. Run focused Feature/Filament tests, focused browser smoke, Human Product Sanity, Pint, and `git diff --check`.

## Domain / Model Implications

- No database migration is planned.
- No model ownership changes are planned.
- No new persisted decision state is approved.
- No new enum/status family is approved.
- No Graph/remote provider call may be introduced during UI render.
- Existing sources remain authoritative:
  - Baseline compare state from `BaselineCompareStats`, compare diagnostics, findings, baseline/snapshot truth, and OperationRun evidence.
  - Restore readiness from wizard state, `RestoreSafetyResolver`, `RestoreReadinessResolver`, backup quality, preview/check state, provider readiness, and existing OperationRun evidence.
  - Accepted-risk state from `FindingException`, `FindingExceptionDecision`, `FindingRiskGovernanceResolver`, and current evidence references.

## UI / Filament / Livewire Plan

- Use native Filament sections, actions, wizard steps, tables, infolists, and existing Blade partials where they already exist.
- Keep custom Blade passive. Presenter/page methods decide state; Blade renders.
- Keep one visually dominant primary action per touched decision surface.
- Keep secondary and technical/audit actions neutral and subordinate.
- Keep status colors in badges/labels, not primary buttons.
- Use existing `BadgeCatalog` / `BadgeRenderer` where status-like semantics are already connected.
- Avoid new CSS or JS assets.
- Do not publish Filament internal views.

## Filament v5 Contract

- **Livewire v4.0+ compliance**: required; project baseline is Livewire 4.1.4.
- **Provider registration**: unchanged in `apps/platform/bootstrap/providers.php`.
- **Global search posture**:
  - `RestoreRunResource`: currently `protected static bool $isGloballySearchable = false`; keep unchanged.
  - `FindingExceptionResource`: currently `protected static bool $isGloballySearchable = false`; keep unchanged if touched.
  - `BaselineCompareLanding`: page, not a globally searchable resource.
- **Destructive/high-impact actions**:
  - Baseline Compare `Compare now`: existing high-impact OperationRun start must remain `Action::make(...)->action(...)`, confirmation-protected, capability-gated, and observable.
  - Restore execution: dry-run default, acknowledgement, typed environment confirmation, confirmation protection, capability checks, and execution gates remain.
  - Risk Exception `renew_exception` / `revoke_exception`, if touched: both must remain `->requiresConfirmation()`, service-backed, authorized, and notification-backed.
- **Asset strategy**: no new assets expected. If implementation registers Filament assets unexpectedly, deployment must include `cd apps/platform && php artisan filament:assets`.

## RBAC / Policy Plan

- Baseline Compare remains environment-owned and must not reveal data outside the route workspace/environment.
- Restore Run Create remains environment-scoped and requires manage capability for creation/preparation mutation paths.
- Finding Exception Detail, if touched, remains environment-scoped with `FINDING_EXCEPTION_VIEW` / manage capability boundaries.
- Technical/audit/detail links must apply the same or stricter entitlement as the current default-visible content.
- Server-side action handlers remain authoritative for compare, restore, and exception lifecycle mutations.

## Audit / OperationRun / Evidence Plan

- No audit stream is removed.
- No OperationRun type, lifecycle, notification path, or evidence creation behavior changes.
- Default product views should not lead with OperationRun proof; authorized technical/detail paths may still expose it.
- Restore execution remains the only path that queues real restore execution.
- Baseline Compare `Compare now` remains the only compare-start path touched by this spec.

## Data / Migration Plan

- No migrations.
- No backfill.
- No data compatibility shim.
- No new cache/table/column.
- No new persisted source of truth.

If implementation discovers persistence is required, stop and update `spec.md`, `plan.md`, and `tasks.md` with a proportionality review before creating a migration.

## Testing Strategy

### Feature / Filament

Add or update focused tests to prove:

- Baseline Compare default view has one decision question/action and hides OperationRun proof/raw diagnostics by default.
- Baseline Compare shows top material drift/blockers and caps default rows.
- Restore Preview default view has one decision summary/action, hides raw payload/OperationRun proof/provider responses, and does not expand all changed/unchanged/reviewed tables by default.
- Restore safety controls remain present/reachable and server-side enforced.
- Risk Exception raw Source ID/Fingerprint/JSON/evidence references are hidden by default if optional slice is included.
- Authorized detail/audit paths remain reachable where repo-supported.

### Browser

Create or update a focused browser file such as:

- `apps/platform/tests/Browser/Spec398DecisionPageContractMigrationSmokeTest.php`

Browser proof must cover:

- Baseline Compare.
- Restore Preview / Readiness.
- Risk Exception Detail only if included.

Assertions:

- page loads without 500/Livewire/Filament/console errors
- purpose is clear above the fold
- one primary decision question visible
- one primary action visible
- top blockers/differences visible
- technical details not default-expanded
- OperationRun proof not default-visible
- raw evidence/source key/detector/payload not default-visible
- long tables capped or moved
- restore safety controls still present
- destructive/high-impact actions separated where present

### Validation Commands

Planned focused commands:

```bash
cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec398
cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec398DecisionPageContractMigrationSmokeTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
git diff --check
```

Affected existing test candidates:

```text
apps/platform/tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php
apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
apps/platform/tests/Feature/Filament/RestorePreviewTest.php
apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php
apps/platform/tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php
apps/platform/tests/Feature/Filament/Spec390RestoreReadinessGuidanceTest.php
apps/platform/tests/Feature/Findings/Spec354FindingExceptionDetailGuidanceTest.php
apps/platform/tests/Feature/Filament/FindingExceptionHeaderDisciplineTest.php
```

## Rollout / Deployment Considerations

- **Environment variables**: none expected.
- **Migrations**: none expected.
- **Queues / scheduler**: no new queue or scheduler behavior.
- **Storage / volumes**: no change.
- **Assets**: no new assets expected; `filament:assets` only if implementation unexpectedly registers assets.
- **Staging**: focused browser smoke and human sanity should be repeated on staging before production promotion once production exists.
- **Production safety**: pre-production no-legacy posture applies; replace old default UI behavior rather than preserving it.

## Implementation Phases

### Phase 0 - Discovery And Contract Mapping

- Confirm current default-visible sections for Baseline Compare, Restore Preview, and optional Risk Exception.
- Classify Product Layer vs Technical Evidence Layer for each section.
- Confirm exact existing tests that assert old overloaded behavior.
- Decide whether Risk Exception Detail is narrow enough to include.

### Phase 1 - Baseline Compare Migration

- Update tests for one decision question/action and default technical demotion.
- Rework `BaselineCompareLanding` / Blade output to keep decision status, scope, freshness, recommendation, top drift/blockers, impact, and one action first.
- Move OperationRun proof, raw diagnostics, evidence-gap internals, full tables, and matrix/proof paths behind secondary/detail/audit disclosure.
- Preserve compare-start confirmation/capability/OperationRun behavior.

### Phase 2 - Restore Preview / Readiness Migration

- Update tests for one restore safety decision, top blockers/warnings, table caps, and preserved safety controls.
- Rework `RestoreRunCreatePresenter` / `RestoreRunResource` wizard output to reduce duplicate readiness/proof cards and demote raw preview/provider/OperationRun detail.
- Keep final restore confirmation, acknowledgement, dry-run, typed environment confirmation, and capability checks intact.

### Phase 3 - Optional Risk Exception Cleanup

- Include only if discovery confirms narrow default-visible raw evidence demotion.
- Update tests to prove Source ID, Fingerprint, JSON summary payload, and raw evidence references are not default-visible.
- Preserve existing Spec 354 guidance and renew/revoke action safety.
- If not included, record the defer rationale in the implementation report.

### Phase 4 - UI Coverage, Browser, Human Sanity, Close-Out

- Update route inventory/design coverage matrix for changed surfaces.
- Run focused Feature/Filament tests.
- Run focused browser smoke.
- Complete Human Product Sanity.
- Complete implementation report with Product Surface Contract close-out fields.

## Risks And Controls

| Risk | Likelihood | Impact | Control |
|---|---:|---:|---|
| Baseline Compare loses needed diagnostics | Medium | Medium | Keep authorized detail/audit disclosure and tests. |
| Restore safety weakened by reducing visible sections | Low | High | Preserve existing final confirmation, dry-run, typed confirmation, capabilities, and server-side gates. |
| Risk Exception scope reopens Spec 354 | Medium | Medium | Optional slice with hard defer if broader redesign is required. |
| Implementation adds a generic decision framework | Low | High | Proportionality stop condition and tasks forbid new framework/persistence. |
| Browser fixture cost grows too much | Medium | Medium | Focused Spec 398 smoke only; document unrelated full-suite failures separately. |

## Stop Conditions

Stop and update spec/plan before continuing if implementation requires:

- a migration, new table, new persisted state, or compatibility shim
- a new Product Surface runtime framework, presenter family, enum/status family, or component system
- new routes, navigation, panel providers, global search behavior, packages, assets, queues, scheduler, or env vars
- changes to restore execution semantics
- a broad accepted-risk workflow redesign
- rewriting completed specs or removing historical validation/browser/close-out evidence

## Implementation Report Requirements

Implementation must create or update `specs/398-decision-page-contract-migration/implementation-report.md` with:

1. Files changed.
2. Target decision surfaces changed.
3. Primary decision question per touched surface.
4. Before/after summary of visible sections.
5. Primary action chosen per touched surface.
6. Technical details moved/collapsed/demoted.
7. Tables capped or moved.
8. Status labels normalized.
9. Destructive/high-impact actions separated where touched.
10. Tests added/updated.
11. Browser smokes run.
12. Human sanity check status.
13. No-legacy confirmation.
14. No point-fix-only implementation confirmation.
15. No Product Surface runtime framework confirmation.
16. Visible complexity outcome.
17. Livewire v4 compliance.
18. Provider registration location.
19. Global search posture.
20. Asset strategy and whether `filament:assets` is required.
21. Deployment impact.
22. Known unrelated failures.
23. Screenshot artifacts cleaned or intentionally retained.