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

**Branch**: `398-decision-page-contract-migration`  
**HEAD**: `a5b7300c`  
**Implemented**: 2026-06-22  
**Selected slice**: Baseline Compare plus Restore Create / Restore Preview / Restore Readiness. Risk Exception Detail was inspected and deferred.
**Dirty state at close-out**: dirty working tree with Spec 398 runtime, test, and active-spec documentation changes only.

## Summary

Implemented the Product Surface Contract decision-page reduction over the required surfaces:

- Baseline Compare now uses canonical decision status vocabulary, one visible decision question/action, and closed technical details for OperationRun/audit proof, readiness flow, diagnostics, matrix path, RBAC detail, evidence-gap internals, and explanation detail.
- Restore Create / Preview now uses a canonical restore decision status, removes default duplicate readiness status badges from source and confirmation surfaces, reduces preview summary cards to four default cards, caps changed preview rows at eight, and moves readiness/proof/unchanged/all-reviewed details behind deliberate disclosures.
- Mobile polish keeps the Baseline decision action above summary/proof detail and uses Filament-native `columnSpanFull()` on Restore step-one schema components so the native backup selector and read-only decision/evidence fields span the wizard grid on all breakpoints.
- Existing safety controls were preserved: Baseline `Compare now`, restore dry-run/default confirmation, typed confirmation, capability checks, audit behavior, and execution gates remain in their existing handlers.

## Product Surface Contract Close-Out

- **No-legacy posture**: pass. Old proof-first/default-expanded decision content was replaced; no compatibility mode was added.
- **Product Surface Impact**: Baseline Compare remains a Decision Page. Restore Create remains a wizard with decision sub-surfaces.
- **UI Surface Impact**: rendered default UI changed for `/admin/workspaces/{workspace}/environments/{environment}/baseline-compare` and `/admin/workspaces/{workspace}/environments/{environment}/restore-runs/create`.
- **Runtime UI files changed**: yes. Baseline Compare Blade/page and Restore Create Blade/presenter surfaces changed.
- **Files changed**: Baseline Compare page/view/tests; Restore Create resource schema, presenter, safety decision, confirmation, preview, and safety evidence views/tests; active Spec 398 report/tasks; UI audit route inventory and design coverage matrix.
- **Page archetype**: Decision Page; Wizard Page with Decision Sub-Surface.
- **Surface budgets**: one primary decision/action per touched default surface. Baseline `Compare now` is no longer rendered as a header duplicate; it remains the same confirmed Filament action mounted from the decision card. Restore preview defaults to four summary cards; changed rows are capped at eight; readiness/proof/diagnostics move to closed details.
- **Technical Annex / deep-link demotion**: OperationRun/audit proof remains reachable for authorized users from closed technical details, not as default product content.
- **Canonical status vocabulary**: Baseline Compare uses `Ready`, `Needs attention`, `Blocked`, `Running`, `Failed`, `Not configured`, `Unknown`. Restore Create uses `Ready`, `Needs attention`, `Blocked`, `Not configured`, `Unknown`.
- **Product Surface exceptions**: none.
- **Human Product Sanity**: pass. Default-visible complexity decreased; safety blockers and material drift remain visible; technical/audit proof is still available through deliberate disclosures.
- **Visible complexity outcome**: decreased. Baseline removes default proof/readiness/action duplication; Restore Preview reduces nine default cards to four; Restore Create/Confirm no longer renders a second readiness badge by default; changed/unchanged/all-reviewed expansion is deliberate.
- **Completed-spec rewrite assertion**: no completed historical spec artifacts were rewritten to satisfy new Product Surface wording. Only the active Spec 398 artifacts and UI audit inventory/matrix were updated.

## Risk Exception Decision

Risk Exception Detail was deferred. Inspection confirmed it has raw evidence-style fields (`Source ID`, `Fingerprint`, JSON summary payload), but including it would reopen the Spec 354 accepted-risk detail surface beyond the required Baseline Compare and Restore scope. Renew/revoke actions were left unchanged and remain confirmation-protected in existing code.

## Filament / Safety Contract

- **Livewire v4**: compliant. No Livewire v3 APIs or Filament legacy APIs introduced.
- **Provider registration**: unchanged; Laravel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search**: unchanged. `RestoreRunResource` remains `protected static bool $isGloballySearchable = false`; Baseline Compare is a page, not a globally searchable resource; Risk Exception was not touched.
- **Destructive/high-impact actions**: existing `Compare now` action remains a Filament action with confirmation and capability gating. Restore execution/preview/confirmation gates remain in existing resource/page handlers with dry-run and typed confirmation behavior. Risk Exception renew/revoke were not changed.
- **Asset strategy**: no new assets, no panel asset registration, no Tailwind asset pipeline change. No additional `filament:assets` requirement was introduced beyond standard deploy practice.
- **Filament native posture**: no Filament internal Blade views were published or replaced. The wizard and backup selector remain native Filament schema/form components; mobile full-width behavior uses Filament's documented `columnSpanFull()` API. Existing scoped wizard-header CSS remains the only Filament hook-class styling override.
- **Deployment impact**: no migrations, env vars, routes, queues, cron, storage, provider scopes, or Graph render calls added.

## Browser Proof

Focused browser proof used existing seeded browser smokes rather than adding a new browser file:

- `cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php`
  - PASS: 1 test, 53 assertions.
  - Covered Baseline Compare no-baseline, missing snapshot, compare required, single visible `Compare now` trigger, drift available, evidence-gap states, closed readiness/technical/diagnostic disclosures, and no default raw payload/proof leakage.
- `cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php`
  - PASS: 6 tests, 187 assertions.
  - Covered Restore Create selected source, mapping, validation, preview, confirmation, execution-prerequisite lock, canonical source/quality/readiness vocabulary, closed readiness/proof disclosures, and responsive preview review cards/tables.
- `cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php`
  - PASS: 7 tests, 240 assertions.
  - Re-run after mobile polish and Filament-native full-span restore step changes.

Screenshots are produced by those existing browser tests under their historical spec artifact folders. Spec 398 records equivalent textual proof here instead of duplicating screenshots.

## Feature / Unit Proof

- `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec398`
  - PASS: 4 tests, 55 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter='Spec398|Spec336BaselineCompareProductProcessFlowAlignmentTest|BaselineCompareLandingStartSurfaceTest|Spec333RestoreCreateUxFinalProductizationTest|RestoreSelectionQualityTruthTest|RestoreRunCreatePresenterDeterminismTest'`
  - PASS: 38 tests, 425 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter='Spec336BaselineCompareProductProcessFlowAlignmentTest|BaselineCompareLandingStartSurfaceTest|Spec333RestoreCreateUxFinalProductizationTest|RestoreSelectionQualityTruthTest|RestoreRunCreatePresenterDeterminismTest|RestoreRunPreviewProductizationTest|Spec330EnvironmentDashboardBaselineCompareProductizationTest|Spec332ProductProcessFlowSystemTest|Spec398DecisionPageContractMigrationTest'`
  - PASS: 61 tests, 849 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter='Spec398DecisionPageContractMigrationTest|Spec333RestoreCreateUxFinalProductizationTest|Spec336BaselineCompareProductProcessFlowAlignmentTest|BaselineCompareLandingStartSurfaceTest|Spec332ProductProcessFlowSystemTest|RestoreRunCreatePresenterDeterminismTest'`
  - PASS: 53 tests, 652 assertions.
- `cd apps/platform && ./vendor/bin/sail artisan test --filter='Spec398DecisionPageContractMigrationTest|Spec333RestoreCreateUxFinalProductizationTest|Spec332ProductProcessFlowSystemTest|RestoreRunCreatePresenterDeterminismTest'`
  - PASS: 32 tests, 489 assertions.

## Formatting / Diff Checks

- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
  - PASS.
- `git diff --check`
  - PASS.

## Remaining Findings

- In-scope confirmed findings: none after the passing focused feature/unit and browser runs.
- Residual risk: Risk Exception Detail still has default raw evidence fields and should remain a separate bounded follow-up if desired.