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

Feature Specification: Spec 398 - Decision Page Contract Migration v1

Feature Branch: 398-decision-page-contract-migration Created: 2026-06-22 Status: Draft / Ready for preparation review Type: Product Surface Contract migration / decision-page runtime reduction Input: User-provided "Spec 398 - Decision Page Contract Migration v1" candidate, plus repo truth from Specs 336, 354, 390, 395, 397, docs/product/spec-candidates.md, docs/product/roadmap.md, and docs/product/standards/product-surface-contract.md.

Candidate Selection Context

• Selected candidate: Decision Page Contract Migration v1.
• Source: Direct user-provided Spec 398 draft. The active automatic queue in docs/product/spec-candidates.md remains empty, but Spec 395 explicitly recorded a "Decision Page Reduction Pass" follow-up covering Baseline Compare and Restore Preview.
• Why selected: This is the next explicit Product Surface Contract runtime-reduction slice after Spec 397 completed the receipt-page pass. It targets existing overloaded decision-family surfaces instead of adding new status models, persisted truth, or a runtime product-surface framework.
• Close alternatives deferred:
  • management-report-pdf-staging-runtime-validation: already represented by Spec 380 and not a decision-page migration.
  • governance-artifact-lifecycle-retention-runtime: manual-promotion only and broader than the selected page-archetype reduction.
  • provider-readiness-onboarding-productization: optional/manual provider-readiness work, not a decision-page contract pass.
  • cross-domain-indicator-runtime-follow-through: broader guardrail follow-through; this spec is page-archetype based and narrower.
  • Dashboard and Inbox Link Budget Pass: explicitly remains a later Product Surface Contract follow-up.
  • Review Publication Resolution / Decision Register work: already repo-real or completed context; not reopened here.
• Roadmap relationship: Supports the roadmap's UI/Product Maturity Polish lane and the Product Surface Contract runtime-reduction direction without reopening completed productization lanes.
• Completed-spec guardrail result: Specs 336, 354, 390, 395, and 397 are context only. Completed close-out, validation, screenshots, browser evidence, and checked task history must not be rewritten. Spec 395 deferred a Decision Page Reduction Pass, so this package is a new preparation target rather than a rewrite of Spec 395 or Spec 397.
• Smallest viable implementation slice: Migrate Baseline Compare and Restore Preview / Restore Readiness default decision surfaces to the existing Product Surface Contract. Include Risk Exception Detail only if discovery confirms the cleanup is narrow and does not compete with Spec 354's accepted-risk guidance work.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Several decision-family pages still ask operators to choose a safe action while also showing proof panels, readiness flows, diagnostics, long tables, raw evidence links, OperationRun proof, and multiple competing actions by default.
• Today's failure: Operators must reconstruct the primary decision from mixed technical sections. Baseline Compare can read like a workbench/proof explorer, Restore Preview can read like several readiness models at once, and Risk Exception Detail can expose raw accepted-risk evidence fields beside renewal/revocation actions.
• User-visible improvement: Operators see one primary decision question, one primary action, top material blockers or differences, and a compact impact summary. Full diagnostics remain available deliberately for authorized users.
• Smallest enterprise-capable version: A product-surface migration over existing pages and presenters only. Reduce default-visible technical detail, cap or move long tables, map top-level statuses to the existing Product Surface vocabulary, preserve restore/risk safety, and verify with focused Feature/Filament plus browser proof.
• Explicit non-goals: No new Product Surface runtime framework, no new presenter family, no new status enum family, no new persisted taxonomy, no restore execution redesign, no baseline engine rebuild, no review-publication rewrite, no Governance Inbox or Decision Register reopen, no broad dashboard/inbox reduction, and no compatibility mode for old overloaded layouts.
• Permanent complexity imported: Focused tests, browser proof, and possibly page-local helper cleanup if existing code becomes less reviewable. No new database table, migration, provider framework, status taxonomy, cross-domain UI framework, or broad abstraction is approved by this spec.
• Why now: Spec 395 installed the Product Surface Contract gate, Spec 397 completed the receipt-page reduction pass, and the user provided the next explicit decision-page migration candidate.
• Why not local: One-card or one-label tweaks would leave the same contract failure on adjacent decision pages. This spec keeps the migration cross-surface enough to enforce the Decision Page contract while still bounded to named pages.
• Approval class: Cleanup / Workflow Compression.
• Red flags triggered: Multiple surfaces and UI contract migration. Defense: the scope reduces visible complexity on existing surfaces, adds no new product truth, preserves existing safety controls, and forbids broad frameworks or compatibility paths.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve as a bounded Product Surface Contract decision-page migration slice.

Spec Scope Fields (mandatory)

• Scope: canonical-view over existing /admin workspace/environment decision-family surfaces.
• Primary Routes:
  • Baseline Compare: /admin/workspaces/{workspace}/environments/{environment}/baseline-compare
  • Restore Preview / Restore Readiness: /admin/workspaces/{workspace}/environments/{environment}/restore-runs/create
  • Optional Risk Exception Detail: /admin/workspaces/{workspace}/environments/{environment}/finding-exceptions/{record}
• Data Ownership:
  • Baseline Compare remains derived from existing ManagedEnvironment, BaselineProfile, BaselineTenantAssignment, OperationRun, Finding, InventoryItem, baseline snapshots, and existing compare diagnostics.
  • Restore Preview remains derived from existing wizard state, BackupSet, BackupItem, RestoreRun, restore safety/check/preview state, provider readiness, and existing OperationRun/evidence links.
  • Risk Exception remains owned by existing FindingException, FindingExceptionDecision, linked Finding, and existing evidence-reference records.
  • No new persisted decision-page state is introduced.
• RBAC:
  • Existing workspace membership, managed-environment entitlement, capabilities, policies, UiEnforcement, and deny-as-not-found behavior remain authoritative.
  • Technical/audit detail requires the same or stricter authorization as today.
  • UI visibility must not become the only security control.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Target pages remain route-owned by explicit workspace and managed environment route parameters. Hidden session or shell context must not change which environment or record is displayed.
• Explicit entitlement checks preventing cross-tenant leakage: All linked baselines, findings, operation runs, backup sets, restore runs, evidence references, and technical/audit paths must resolve through existing workspace/environment entitlement checks before display.

No Legacy / No Backward Compatibility Constraint (mandatory)

TenantPilot is pre-production for this product-surface behavior.

• Compatibility posture: canonical replacement.
• Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: no.
• Why clean replacement is safe now: There is no production customer-data compatibility requirement. Existing tests that assert old default-visible proof panels, broad diagnostics, all preview tables, or raw evidence payloads must be updated to the canonical decision-page behavior.

Forbidden implementation behavior:

• Keeping old overloaded layouts in parallel.
• Adding a toggle that switches between old and new decision models.
• Renaming proof panels while leaving them default-visible.
• Preserving broad tables because existing tests expect them.
• Adding compatibility helpers for old action labels, route aliases, or decision states.
• Treating OperationRun proof as default product content on decision pages.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• Existing table/form/state presentation changed
• Customer-facing surface changed
• Dangerous or high-impact action presentation changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

Route/page/surface	Current/new archetype	Design depth	Repo-truth level	Existing pattern reused	New pattern required	Screenshot/browser proof	Page audit required	Customer-safe review	Dangerous-action review
Baseline Compare Landing	Decision Page	Strategic Surface	repo-verified	BaselineCompareLanding, baseline-compare-landing Blade, Spec 336 flow pattern, Product Surface Contract	none expected; page-local reduction only	yes	no full page audit unless classification changes	no customer default; operator-safe copy required	yes for Compare now high-impact operation start
Restore Run Create preview/readiness decision section	Wizard Page with Decision Sub-Surface	Strategic Surface	repo-verified	RestoreRunResource, CreateRestoreRun, RestoreRunCreatePresenter, restore safety/resolution support from Specs 332/390	none expected; reuse existing presenter/wizard patterns	yes	no full page audit unless route/archetype changes	no	yes for restore execution/dry-run/confirmation controls
Risk Exception Detail (optional)	Decision Page	Strategic Surface	repo-verified	FindingExceptionResource, ViewFindingException, accepted-risk-guidance, Spec 354 accepted-risk guidance	none expected; include only if narrow	yes if touched	no full page audit unless UI-036 registry is inaccurate	yes for accepted-risk wording continuity	yes for renew/revoke

Coverage files to update or explicitly not needed during implementation:

• docs/ui-ux-enterprise-audit/route-inventory.md
• docs/ui-ux-enterprise-audit/design-coverage-matrix.md
• docs/ui-ux-enterprise-audit/page-reports/...
• docs/ui-ux-enterprise-audit/strategic-surfaces.md
• docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
• docs/ui-ux-enterprise-audit/unresolved-pages.md
• N/A - no reachable UI surface impact

Spec-level coverage registry decision:

Coverage artifact	Decision	Reason
docs/ui-ux-enterprise-audit/route-inventory.md	Update during implementation for each target surface whose default rendered UI changes.	Decision Page classification and Product Surface migration must be visible in durable route inventory.
docs/ui-ux-enterprise-audit/design-coverage-matrix.md	Update during implementation for each target surface whose default rendered UI changes.	The matrix must reflect the Decision Page migration and focused browser-proof expectation.
docs/ui-ux-enterprise-audit/page-reports/...	Not required by default.	Add or update page reports only if implementation changes archetype, expands default content, or discovers the existing page report is materially inaccurate.
docs/ui-ux-enterprise-audit/strategic-surfaces.md	Not required by default.	No new strategic surface or navigation prominence is introduced.
docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md	Not required by default.	Follow-up candidates are recorded in this active spec.
docs/ui-ux-enterprise-audit/unresolved-pages.md	Not required unless implementation cannot classify or render a touched surface.	Planned target surfaces are classifiable as Decision Page or Wizard Page with Decision Sub-Surface.

Product Surface Impact (mandatory for UI-affecting specs)

Reference: docs/product/standards/product-surface-contract.md.

• Product Surface Contract applies?: yes. This spec materially changes rendered product decision pages.
• Page archetype: Baseline Compare and Risk Exception Detail are Decision Pages. Restore Run Create remains a Wizard Page, but its preview/readiness section must behave as a Decision Sub-Surface.
• Primary user question:
  • Baseline Compare: Which baseline drift requires action, and what should I do next?
  • Restore Preview / Readiness: Is this restore safe to continue, and what must be resolved before execution?
  • Risk Exception Detail, if touched: Should this accepted risk remain active, be renewed, or be revoked?
• Primary action: Exactly one state-based product action per touched surface.
• Surface budget result: planned pass. Any exception must be documented in this spec before runtime UI edits continue.
• Technical Annex / deep-link demotion: OperationRun links, raw evidence links, source keys, detectors, fingerprints, UUIDs, JSON payloads, raw provider responses, low-level validation logs, full diff tables, and full diagnostics must be hidden, collapsed, capped, or moved to authorized detail/audit paths by default.
• Canonical status vocabulary: Use Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded, plus allowed severity states where needed.
• Visible complexity impact: decreased.
• Product Surface exceptions: none planned. Any unavoidable exception is a stop condition requiring spec and plan update.

UI Action Matrix

Surface	Primary action	Secondary actions	Technical/audit actions	Dangerous/high-impact actions	Mutation scope
Baseline Compare Landing	One state-based action such as Review material drift, Refresh comparison, Resolve blockers, Retry comparison, or Return to overview.	Up to two contextual actions such as View full comparison, Open baseline snapshot, or View audit trail.	View details, View full comparison, or View audit trail; not default-dominant and only when authorized.	Compare now remains a high-impact OperationRun start when present; it must stay confirmed, capability-gated, and audited/observable through existing paths.	Mostly read-only decision rendering; compare start queues existing TenantPilot operation only.
Restore Preview / Readiness	One next wizard action such as Continue to confirmation, Run readiness checks, Regenerate preview, Resolve blockers, or Review restore readiness.	Up to two contextual actions such as View restore details, View diagnostics, or Open backup set when relevant and authorized.	View restore diagnostics or View audit trail; raw payload/provider/log details hidden by default.	Restore execution remains high-impact and must retain dry-run default, acknowledgement, typed environment confirmation, confirmation protection, and capability checks.	Wizard preparation remains TenantPilot-owned until execution; real provider mutation remains existing restore execution path only.
Risk Exception Detail (optional)	One state-based action such as Review renewal, Review exception, Resolve blockers, or Return to accepted risk.	Up to two contextual actions such as Open finding or Return to queue.	View internal evidence details or View audit trail; raw evidence fields hidden by default.	Renew exception and Revoke exception remain confirmed, authorized, notification-backed, and visually separated; Revoke must not compete as a normal primary action.	Mutations affect existing FindingException lifecycle only through current service/audit paths.

Browser Verification Plan (mandatory)

• Browser proof required?: yes.
• No-browser rationale: N/A - rendered UI changes are the purpose of this spec.
• Focused path when required:
  • Baseline Compare route for at least one material drift or blocker state.
  • Restore Run Create wizard through the preview/readiness decision section.
  • Risk Exception Detail only if implementation includes the optional cleanup.
• Primary interaction to execute:
  • Render first viewport and confirm one primary decision question/action.
  • Expand the detail/audit disclosure where present and confirm technical detail is deliberate, not default-visible.
  • For Restore, verify dry-run/acknowledgement/typed confirmation controls remain visible or reachable in the correct step.
• Console, Livewire, Filament, network, and 500-error checks: required for focused browser smoke.
• Full-suite failure triage: If unrelated browser failures remain, implementation must document the command, affected failures, why they are unrelated, and prove no touched decision surface failed.

Human Product Sanity Check (mandatory)

• Required?: yes.
• No-human-sanity rationale: N/A - rendered product decision surfaces change.
• Reviewer questions:
  • Does the page feel like a decision page, not a dashboard/workbench?
  • Is the primary decision question obvious above the fold?
  • Is there exactly one dominant next action?
  • Are only the most material blockers/differences visible by default?
  • Are technical details demoted?
  • Are long tables hidden, capped, or moved?
  • Are restore safety controls still clear?
  • Are destructive/high-impact actions separated?
  • Does the page feel less complex than before?
  • Would an operator trust the recommendation?
• Planned result location: implementation report and PR close-out.

Product Surface Merge Gate Checklist (mandatory)

• No-legacy posture or approved exception recorded.
• Product Surface Impact is completed and exceptions are none or explicitly approved.
• Browser proof is completed for every rendered UI surface changed.
• Human Product Sanity is completed.
• Implementation report states Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, and visible complexity outcome.

Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction classes: status messaging, decision cards, action links, technical/audit links, table caps, restore readiness, accepted-risk actions, OperationRun evidence links.
• Systems touched:
  • App\Filament\Pages\BaselineCompareLanding
  • apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php
  • App\Filament\Resources\RestoreRunResource
  • App\Filament\Resources\RestoreRunResource\Pages\CreateRestoreRun
  • App\Filament\Resources\RestoreRunResource\Presenters\RestoreRunCreatePresenter
  • optional App\Filament\Resources\FindingExceptionResource
  • optional App\Filament\Resources\FindingExceptionResource\Pages\ViewFindingException
• Existing pattern(s) to extend: Product Surface Contract, Spec 336 Baseline Compare decision-first flow, Spec 390 Restore readiness guidance, Spec 354 accepted-risk guidance, existing BadgeCatalog / BadgeRenderer, UiEnforcement, WorkspaceUiEnforcement, OperationRun URL helpers, Filament sections/details.
• Shared contract / presenter / builder / renderer to reuse: existing page presenters/helpers first. New helper extraction is allowed only when it reduces real review burden inside a touched surface and does not become a generic decision-page framework.
• Why the existing shared path is sufficient or insufficient: The Product Surface Contract already supplies the vocabulary and budgets. Existing page presenters already compute much of the state. The remaining gap is default-visible hierarchy and demotion, not missing product truth.
• Allowed deviation and why: page-local collapsed detail or table cap helpers may be used if existing Filament/presenter structures cannot express the contract cleanly. No new cross-domain Product Surface runtime framework is approved.
• Consistency impact: decision question, primary action, status vocabulary, technical demotion, and high-impact action separation must stay consistent across Baseline Compare, Restore Preview, and optional Risk Exception Detail.
• Review focus: no point fixes, no default OperationRun proof, no raw evidence/payload leakage, no duplicate readiness summaries, no fake "all clear", no weakened restore/risk action safety.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, by demoting default OperationRun proof links on decision surfaces and preserving existing operation-start behavior.
• Shared OperationRun UX contract/layer reused: existing OperationRunLinks, OperationUxPresenter, OpsUxBrowserEvents, and current operation resource links.
• Delegated start/completion UX behaviors: existing queued toast, Open operation links, run-enqueued browser event, and tenant/workspace-safe operation URL resolution remain delegated to existing helpers.
• Local surface-owned behavior that remains: deciding whether an operation proof link is product-secondary/audit detail or hidden from default decision view.
• Queued DB-notification policy: unchanged.
• Terminal notification path: unchanged.
• Exception required?: none planned.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: no new shared provider/platform boundary.
• Boundary classification: N/A - UI hierarchy migration over existing provider-backed state.
• Seams affected: No contract registry, provider identity, target scope, compare strategy, or Graph endpoint semantics are changed.
• Neutral platform terms preserved or introduced: use provider, target environment, restore source, managed environment, and governed subject where those are already repo terms.
• Provider-specific semantics retained and why: Microsoft/Graph/Entra terminology may remain only where it is existing provider-owned technical/detail context.
• Why this does not deepen provider coupling accidentally: No new provider-shaped persisted truth, enum, route family, or platform-core taxonomy is introduced.
• Follow-up path: none planned.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no.
• New abstraction?: no broad abstraction approved. Page-local helper extraction is allowed only if it replaces scattered logic and stays inside the touched surface.
• New enum/state/reason family?: no. Use existing Product Surface Contract vocabulary as display contract.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: overloaded decision pages hide the one decision and next action behind proof, diagnostics, and competing tables/actions.
• Existing structure is insufficient because: the data exists, but default rendering violates Product Surface budgets and deep-link demotion rules.
• Narrowest correct implementation: reduce existing page defaults and tests; do not introduce new decision truth.
• Ownership cost: focused tests, browser proof, and page-specific cleanup only.
• Alternative intentionally rejected: a reusable Decision Page engine, persisted decision state, generic technical-annex framework, or broad dashboard/inbox migration.
• Release truth: current-release productization cleanup.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature/Filament for rendered page/action behavior, Unit only for pure local helpers if introduced, Browser for focused UI smoke.
• Validation lane(s): confidence + browser; fast-feedback for pure helper tests; git diff --check; Pint for touched PHP.
• Why this classification and these lanes are sufficient: The change is visible UI hierarchy over existing state and safety controls. Feature/Filament tests prove content/action visibility and browser smoke proves first-viewport decision clarity and runtime health.
• New or expanded test families: one focused Spec 398 browser smoke may be added; no broad visual regression family.
• Fixture / helper cost impact: Use existing workspace, managed environment, backup/restore, baseline, finding exception, and browser fixtures. Do not widen shared helpers with implicit provider/workspace/session defaults.
• Heavy-family visibility / justification: Browser coverage is explicit because rendered decision surfaces are the product change.
• Special surface test profile: Product Surface Decision Page migration.
• Reviewer handoff: Confirm lane fit, browser proof scope, no hidden helper cost, and no old overloaded expectations preserved.
• Budget / baseline / trend impact: none expected; document any material browser fixture expansion as document-in-feature.
• Escalation needed: none if implementation stays bounded; reject-or-split if it expands into dashboard/inbox, review-publication, or runtime framework scope.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec398
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec398DecisionPageContractMigrationSmokeTest.php if a new browser file is added
  • affected existing tests for Baseline Compare, Restore Create/Preview, and optional Finding Exception Detail
  • cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
  • git diff --check

User Stories & Testing (mandatory)

User Story 1 - Baseline Compare answers one drift decision (Priority: P1)

As a governance operator, I want Baseline Compare to show whether baseline drift requires action and what to do next, so that I do not have to read OperationRun proof, evidence-gap diagnostics, or full compare tables before deciding.

Independent Test: Render Baseline Compare with material drift, blocker/stale/failure, and no-material-drift states. The default view shows one decision question, one status, top material drift or blocker summary, one primary action, and no default OperationRun proof/raw diagnostics.

Acceptance Scenarios:

1. Given material drift exists, when an authorized operator opens Baseline Compare, then the page shows top material drift and a single dominant review action.
2. Given compare input is missing, stale, blocked, failed, or running, when the page renders, then the top state maps to the canonical status vocabulary and shows one next action.
3. Given full diagnostics exist, when the default view renders, then OperationRun proof, raw evidence links, source keys, detector output, raw payloads, and full diagnostics are not default-visible.

User Story 2 - Restore Preview answers one safety decision (Priority: P1)

As a restore operator, I want the Restore Preview / Readiness section to show whether the restore is safe to continue and which blockers must be resolved, so that restore execution remains clear and safe.

Independent Test: Render Restore Run Create wizard states for blocked, needs-attention, and ready paths. The default preview/readiness decision area shows source/target, top blockers or warnings, impact summary, one next wizard action, and preserves dry-run/acknowledgement/typed confirmation safety.

Acceptance Scenarios:

1. Given restore blockers exist, when the preview/readiness step renders, then the page shows top blockers and one safe next action without exposing raw restore payload, provider response, or OperationRun proof by default.
2. Given restore is ready to continue, when the preview/readiness step renders, then the page shows one continue/final-confirmation action and still requires existing final restore safety controls.
3. Given many changed/unchanged/reviewed items exist, when the default view renders, then long tables are capped to at most eight visible rows or moved behind details.

User Story 3 - Risk Exception Detail avoids raw evidence leakage if included (Priority: P2)

As an operator reviewing accepted risk, I want the detail page to show whether the risk should remain active, be renewed, or be revoked without exposing raw source IDs, fingerprints, or JSON payloads by default.

Independent Test: If included, render Risk Exception Detail and assert one accepted-risk decision question/action, demoted raw evidence fields, and preserved renew/revoke confirmation and authorization behavior.

Acceptance Scenarios:

1. Given an expiring accepted risk, when an authorized operator opens the detail page, then the page emphasizes renewal review and does not expose raw evidence fields by default.
2. Given renew/revoke are available, when the page renders, then those actions remain confirmation-protected, authorized, visually separated, and not both shown as equal primary actions.
3. Given the cleanup would require broader accepted-risk redesign, when discovery completes, then Risk Exception Detail is deferred with a documented rationale instead of expanding this spec.

User Story 4 - Technical detail remains available deliberately (Priority: P2)

As a senior engineer or support reviewer, I need authorized access to full diagnostics and audit evidence after the product decision is clear, so that product simplification does not remove auditability.

Independent Test: Feature/Filament tests assert authorized users can still reach existing detail/audit paths while default product views hide raw technical content.

Acceptance Scenarios:

1. Given a user lacks the required capability for technical/audit detail, when they access a decision page, then raw internal detail is not visible and scoped authorization remains enforced.
2. Given an authorized user opens the deliberate detail/audit path, then full comparison, restore diagnostics, or evidence detail remains reachable where existing routes/actions support it.

Functional Requirements

• FR-398-001: Baseline Compare MUST default to a Decision Page layout with one primary decision question, decision status, recommendation, top material drift or blocker summary, impact summary, and exactly one primary action.
• FR-398-002: Baseline Compare MUST NOT show OperationRun proof, raw evidence links, source keys, detector output, raw payloads, full candidate tables, full diff tables, full access diagnostics, or raw evidence-gap internals by default.
• FR-398-003: Baseline Compare MUST cap default material drift rows to at most eight visible rows, with top three preferred for summary.
• FR-398-004: Restore Preview / Readiness MUST default to one decision sub-surface with restore decision status, source backup, target environment, top blockers/warnings, impact summary, and exactly one next action.
• FR-398-005: Restore Preview / Readiness MUST NOT show all summary cards, all changed/unchanged/all-reviewed tables, raw restore payloads, OperationRun proof, internal job IDs, raw provider responses, low-level validation logs, raw backup metadata, or duplicate proof/readiness summaries by default.
• FR-398-006: Restore Preview / Readiness MUST preserve dry-run default behavior where applicable, acknowledgement, typed environment confirmation, confirmation protection, and capability checks.
• FR-398-007: If Risk Exception Detail is included, Source ID, Fingerprint, JSON summary payload, raw evidence references, detector output, and source keys MUST NOT be default-visible.
• FR-398-008: Every touched decision surface MUST have exactly one primary action and at most two default secondary actions.
• FR-398-009: Full diagnostics, full comparison, restore diagnostics, proof, and raw evidence MAY remain available only through deliberate secondary/detail/audit paths for authorized users.
• FR-398-010: Top-level decision statuses MUST map to the Product Surface Contract vocabulary.
• FR-398-011: Destructive/high-impact actions touched by this spec MUST execute through existing Filament action handlers, require confirmation, enforce server-side authorization, and preserve audit/notification behavior.
• FR-398-012: Implementation MUST NOT add a Product Surface runtime framework, decision presenter family, status enum family, component framework, persisted taxonomy, migration, provider abstraction, or compatibility shim.
• FR-398-013: Existing tests that assert old overloaded default UI MUST be updated to assert the new decision contract rather than preserving old behavior.
• FR-398-014: Focused browser smoke MUST cover every touched rendered decision surface.

Non-Functional Requirements

• NFR-398-001: Default-visible complexity must decrease or remain neutral; any increase requires a documented Product Surface exception before runtime edits continue.
• NFR-398-002: Page rendering must not introduce Graph calls or remote provider calls.
• NFR-398-003: Table caps and detail demotion must not hide safety blockers; top material blockers/differences must remain visible.
• NFR-398-004: Browser proof must remain focused and fixture-bounded, not a broad visual regression suite.
• NFR-398-005: Test fixture/helper cost must remain explicit and local to this spec.

RBAC / Security Requirements

• Workspace and managed-environment authorization remain non-negotiable and deny-as-not-found for out-of-scope records.
• Restore preparation/execution actions continue to require existing manage capabilities and server-side checks.
• Finding exception renew/revoke actions continue to require existing manage capabilities and service-layer authorization.
• Technical/audit detail links must not reveal inaccessible operation, evidence, backup, baseline, or finding records.
• Customer/read-only paths must not expose raw technical decision internals by default.

Auditability / Observability Requirements

• No audit trail is removed.
• Existing OperationRun, restore, compare, and finding-exception audit behavior remains authoritative.
• Demoting OperationRun proof from default product content must not remove the existing authorized path to technical proof.
• Implementation report must state whether any audit/logging behavior changed. The planned answer is none.

Data / Truth Requirements

• Existing domain truth remains authoritative:
  • execution truth: OperationRun and existing restore/compare execution paths
  • artifact truth: existing backup, baseline, evidence, restore, and risk records
  • backup/snapshot truth: existing BackupSet, BackupItem, baseline snapshot, and evidence snapshot state
  • recovery/evidence truth: existing restore preview/check/result/evidence data
  • operator next action: derived from current page state only
• No new persisted decision state, derived cache, or compatibility field is approved.

Out Of Scope

• Rewriting Spec 395 or Spec 397.
• Reopening Review Publication Resolution, Decision Register, Governance Inbox, Customer Review Workspace, Evidence Snapshot, Baseline Snapshot, or System Panel.
• Broad dashboard/inbox link-budget pass.
• Baseline compare engine rebuild, drift algorithm changes, snapshot generation changes, or new evidence generation.
• Restore execution redesign, provider-specific restore adapter expansion, or new restore functionality.
• Accepted-risk workflow redesign beyond optional narrow default-visible evidence demotion.
• New navigation, panel provider, route family, global search type, migration, queue family, scheduler, env var, storage behavior, package, or runtime framework.

Follow-Up Spec Candidates

• Dashboard and Inbox Link Budget Pass: Environment Dashboard, Workspace Overview, Governance Inbox, Findings, and Operations Hub.
• Review Publication Resolution decision-page check only if fresh evidence shows Product Surface regression after this spec.
• Decision Page Contract hardening for additional surfaces discovered during implementation, recorded separately rather than hidden in this slice.
• Cross-domain indicator runtime follow-through, if status/readiness drift remains after page-level reductions.

Acceptance Criteria

1. Baseline Compare default view shows one primary decision question, decision status, recommendation, top material drift or blockers, impact summary, and one primary action.
2. Baseline Compare default view does not show OperationRun proof, full diagnostics, raw evidence links, source keys, detector output, raw payloads, or long uncapped tables.
3. Restore Preview / Readiness default decision view shows source/target, restore decision status, top blockers/warnings, impact summary, and one next action.
4. Restore Preview / Readiness default view does not show all summary cards, all preview tables, raw restore payloads, OperationRun proof, raw provider responses, or duplicate readiness/proof summaries.
5. Restore execution safety controls remain intact.
6. Risk Exception Detail, if touched, hides raw source/fingerprint/JSON/evidence fields by default and keeps renew/revoke safe.
7. Every touched surface has exactly one primary action and at most two default secondary actions.
8. Technical details remain reachable only through deliberate authorized detail/audit paths.
9. Default tables show at most eight visible rows or are moved behind details.
10. Focused Feature/Filament tests and focused browser proof pass, or unrelated failures are documented honestly.
11. No new Product Surface runtime framework, status family, persisted truth, or compatibility mode is created.

Success Criteria

• Operators can identify the decision and next action within a few seconds on each touched surface.
• Product Surface Contract browser proof passes for Baseline Compare and Restore Preview / Readiness.
• Visible technical proof and raw-detail exposure decreases by default.
• Restore safety and risk-exception lifecycle safety remain intact.
• Implementation report confirms no legacy behavior, no point-fix-only implementation, and no runtime framework was introduced.

Risks And Mitigations

• Risk: Operators lose access to full diagnostics. Mitigation: retain authorized secondary/detail/audit paths and test their availability where supported.
• Risk: Restore safety weakens during UI simplification. Mitigation: make dry-run, acknowledgement, typed confirmation, confirmation protection, and capability checks explicit acceptance criteria and browser assertions.
• Risk: Tests preserve old overloaded defaults. Mitigation: update old expectations to assert the new contract; no compatibility behavior.
• Risk: Scope expands into broad redesign. Mitigation: keep primary scope to Baseline Compare and Restore Preview / Readiness; Risk Exception is optional only if narrow.
• Risk: Implementation creates a forbidden framework. Mitigation: proportionality review forbids new persisted truth, enum/status family, presenter family, or product-surface runtime framework.

Assumptions

• The repo remains pre-production under the constitution's no-legacy posture.
• Spec 395 Product Surface Contract is the source of truth for page budgets and deep-link demotion.
• Baseline Compare and Restore Preview have enough existing state to derive product decisions without new persistence.
• Risk Exception Detail may be skipped if implementing it safely would reopen Spec 354 or require broad accepted-risk redesign.

Open Questions

• None blocking preparation.
• Implementation discovery must decide whether Risk Exception Detail is included or explicitly deferred with rationale.