TenantAtlas/specs/369-baseline-profile-decision-view/spec.md

Feature Specification: Spec 369 - Baseline Profile Decision View

Feature Branch: 369-baseline-profile-decision-view Created: 2026-06-09 Status: Draft Input: Spec 368 Platform UI Signal-to-Noise Browser Audit, Candidate B narrowed to the P1 Baseline Profile View finding.

Candidate Selection Summary

• Selected candidate: Baseline Profile View decision-first productization.
• Source: specs/368-platform-ui-signal-to-noise-browser-audit/findings.md finding UI-AUDIT-368-F03, audit.md prioritized refactor candidate 1, and spec-candidates.md Candidate B.
• Why selected: It is the highest-priority browser-verified reachable page from Spec 368: the Baseline Profile detail view is a governance source-of-truth page, but its first viewport emphasizes long names, capture mode, normalization lineage, foundations, and metadata before the operator can answer readiness and next action.
• Smallest viable slice: Productize only the existing BaselineProfileResource detail view (ViewBaselineProfile) so it leads with baseline readiness, snapshot truth, assignment usefulness, compare/capture availability, and one safe next action before technical scope and metadata.
• Deferred close alternatives:
  • Backup Set View: restore-critical but P2 and better handled after the baseline view pattern proves itself.
  • OperationRun View: strong current foundation and recently changed by Specs 358-367; avoid reopening OperationRun surfaces immediately.
  • Customer Review Workspace: materially covered by Specs 312, 326, 342, 343, 344, 349, and 351; only narrow polish remains.
  • Provider Connections and Diagnostics: valid later slices, but lower priority than the P1 Baseline Profile finding for this preparation.
  • Global Surface Information Architecture Contract v1: useful as a rule pack, but higher risk of over-generalization; this spec keeps the work page-local.
• Completed-spec guardrail: Related baseline truth and compare specs (116, 159, 336) are completed historical/runtime context and must not be rewritten. Spec 368 is an audit artifact with no application implementation and is used only as candidate source.

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

• Problem: Operators open a Baseline Profile detail page to decide whether a governance standard is usable, assigned, captured, comparable, and safe to act on, but the current default layout makes them parse technical scope and metadata before the decision.
• Today's failure: An operator can see status, capture mode, governed subject summary, normalization lineage, current snapshot, latest attempt, compare readiness, related context, and metadata as peer sections without a single first-read answer about readiness and the next safe action.
• User-visible improvement: The Baseline Profile detail page starts with a decision summary that states readiness, reason, impact, evidence/snapshot basis, assignment/usefulness, and one dominant next action. Technical details remain available but are secondary.
• Smallest enterprise-capable version: Reorder and lightly reshape the existing detail view using current Baseline Profile, Snapshot, Assignment, Compare readiness, and OperationRun link truth. Do not create new persistence, engines, statuses, Graph calls, or broad UI frameworks.
• Explicit non-goals: No Baseline engine rewrite, no compare algorithm changes, no new BaselineProfile table/columns, no new OperationRun type, no new Graph contract, no restore/backup UI work, no shell/sidebar work, no broad global UI standard, and no customer portal.
• Permanent complexity imported: Focused page-local presentation helpers may be added only if the existing resource methods become hard to review. Tests and one browser smoke may be added. No new persisted entity, enum/status family, cross-domain UI framework, or provider abstraction is expected.
• Why now: Spec 368 browser-verified this as the highest-priority reachable P1 productization gap after the platform-wide signal-to-noise audit.
• Why not local: A purely cosmetic reorder without explicit spec guardrails could leave dangerous actions, OperationRun links, snapshot truth, and technical metadata competing again. This spec defines the bounded decision-first contract and proof requirements.
• Approval class: Workflow Compression.
• Red flags triggered: UI framework risk (mitigated by page-local scope), high-impact action surface risk (mitigated by preserving existing confirmation/authorization/audit/OperationRun behavior).
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 1 | Gesamt: 10/12
• Decision: approve.

Spec Scope Fields (mandatory)

• Scope: workspace.
• Primary Routes: /admin/baseline-profiles/{record} (BaselineProfileResource view page).
• Secondary Routes For Regression Only: /admin/baseline-profiles, /admin/baseline-profiles/{record}/compare-matrix, /admin/workspaces/{workspace}/environments/{environment}/baseline-compare.
• Data Ownership: baseline_profiles, baseline_snapshots, and baseline assignments remain workspace-owned or existing tenant/environment-linked truth as currently modeled. No schema change is introduced.
• RBAC: Workspace membership plus existing baseline capabilities continue to govern view/manage actions. Non-member/wrong-workspace access remains deny-as-not-found; members missing capabilities remain forbidden or disabled according to existing policy/UI enforcement.

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
• New table/form/state added
• Customer-facing surface changed
• Dangerous action 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: /admin/baseline-profiles/{record}, apps/platform/app/Filament/Resources/BaselineProfileResource.php, apps/platform/app/Filament/Resources/BaselineProfileResource/Pages/ViewBaselineProfile.php.
• Current or new page archetype: Drift / Diff strategic detail surface, existing UI-057 Baseline Profile Detail/Edit.
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified and browser-verified by Spec 368 screenshot artifacts/screenshots/admin/008-decision-surface-view-baseline-profile.png.
• Existing pattern reused: Baseline Compare decision-first summary from Spec 336, existing ActionSurfaceDeclaration, WorkspaceUiEnforcement, BadgeCatalog/BadgeRenderer, OperationUxPresenter, and existing Baseline Profile truth helpers.
• New pattern required: none beyond a page-local decision summary if existing methods cannot express the hierarchy cleanly.
• Screenshot required: yes, before/after desktop; mobile or narrow viewport if the implementation materially changes responsive structure.
• Page audit required: yes, update docs/ui-ux-enterprise-audit/page-reports/ui-010-baseline-profiles.md and the relevant UI-057 coverage note if runtime changes are implemented.
• Customer-safe review required: no; this is an operator/MSP governance surface, not a customer-facing page.
• Dangerous-action review required: yes; capture, compare, compare assigned environments, and archive must retain confirmation, authorization, audit/OperationRun behavior, and action hierarchy.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md - no route change expected; implementation must document no route-inventory change or update only if classification changes.
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md - update only if coverage counts/screenshot references change.
  • docs/ui-ux-enterprise-audit/page-reports/... - update ui-010-baseline-profiles.md / UI-057 note after implementation.
  • 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
• No-impact rationale when applicable: N/A.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction class(es): status messaging, header actions, action links, evidence/snapshot viewer links, OperationRun links.
• Systems touched: Baseline Profile detail infolist, header actions, related context entries, compare/capture notifications, existing baseline action tests, browser smoke.
• Existing pattern(s) to extend: Baseline Compare decision-first flow, ActionSurfaceDeclaration, WorkspaceUiEnforcement, OperationUxPresenter, OperationRunLinks, BadgeCatalog/BadgeRenderer.
• Shared contract / presenter / builder / renderer to reuse: Existing resource methods first; use BadgeCatalog/BadgeRenderer for status-like badges; use OperationRunLinks/OperationUxPresenter for run links/toasts.
• Why the existing shared path is sufficient or insufficient: Existing helpers already know snapshot truth, compare readiness, next step, action authorization, and run linking. The gap is hierarchy, not missing domain truth.
• Allowed deviation and why: A small page-local derived summary helper is allowed if it replaces scattered inline logic and remains derived-only.
• Consistency impact: Baseline detail wording must stay aligned with Baseline Profiles list, Baseline Compare Landing, Baseline Snapshot detail, OperationRun detail, and audit/notification wording.
• Review focus: Verify no page-local status taxonomy, duplicate readiness model, or second action eligibility source is introduced.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, existing capture/compare start and links only.
• Shared OperationRun UX contract/layer reused: existing OperationUxPresenter, OperationRunLinks, OpsUxBrowserEvents, and OperationRunService-backed capture/compare flows.
• Delegated start/completion UX behaviors: queued toast, already-queued toast, Open operation link, run-enqueued browser event, and tenant/workspace-safe URL resolution remain delegated to existing shared paths.
• Local surface-owned behavior that remains: initiation inputs and page-level guidance only.
• Queued DB-notification policy: no new policy; preserve current capture/compare behavior.
• Terminal notification path: unchanged.
• Exception required?: none expected.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: no material boundary change.
• Boundary classification: Baseline Profile UI remains platform-core governance truth; provider-specific details remain under governed subject / Intune scope copy already present.
• Seams affected: Display wording for governed subject scope and normalization lineage only.
• Neutral platform terms preserved or introduced: workspace, managed environment, baseline, snapshot, compare readiness, governed subject, operation.
• Provider-specific semantics retained and why: Intune-specific policy/foundation scope terms remain where they describe current baseline subject support.
• Why this does not deepen provider coupling accidentally: The spec does not change contracts, persistence, provider adapters, Graph calls, or subject taxonomy.
• Follow-up path: none.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Baseline Profile detail decision summary	yes	Native Filament infolist/resource page, page-local helper if needed	status messaging, action links, evidence links	page, derived display state	no	Existing route and resource only
Header action hierarchy	yes	Native Filament actions	dangerous/high-impact action surface	page/action state	no	Preserve existing confirmation/authorization
Technical metadata demotion	yes	Native Sections/details/aside where possible	diagnostics/progressive disclosure	page display	no	No raw data removal, only default hierarchy

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Baseline Profile detail	Primary Decision Surface	Operator decides whether this baseline is ready to capture, compare, assign, or inspect	readiness, reason, impact, snapshot basis, assigned environment signal, one next action	governed subject scope, normalization lineage, metadata, detailed related links	Primary for one baseline's governance standard truth	Baseline setup, capture, compare, and drift workflow	Removes first-read parsing across scope, metadata, and action rows

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Baseline Profile detail	operator-MSP, workspace manager, readonly reviewer	readiness, reason, impact, current snapshot, latest attempt, assignment count/state, compare/capture availability	normalization lineage, governed subject detail, related context	operation proof, raw snapshot/detail pages through existing links	capture baseline, compare now, open snapshot, open compare matrix, or edit profile depending on state/capability	technical IDs/timestamps, normalization lineage, low-level scope payload	One summary states decision; existing sections add proof/detail without restating the same decision

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Baseline Profile detail	Detail / Header Actions	Drift / Diff decision detail	Capture, compare, open current snapshot, inspect compare matrix, or edit profile	Existing record view	N/A	More group or related context	Existing archive action remains in More/list flow with confirmation	/admin/baseline-profiles	/admin/baseline-profiles/{record}	workspace-owned profile, assigned managed environments	Baseline profile	readiness, reason, impact, snapshot basis, assignment/usefulness, one next action	none

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Baseline Profile detail	Workspace manager / governance operator	Decide if the baseline can be captured, compared, or needs setup	Baseline governance detail	Is this baseline ready and what should I do next?	readiness, reason, impact, current snapshot truth, latest attempt, assignment state, compare/capture availability	normalization lineage, technical metadata, raw snapshot/run diagnostics through existing related routes	lifecycle, snapshot usability, assignment coverage, compare readiness, operation availability	TenantPilot queues capture/compare OperationRuns; no Microsoft configuration mutation	Capture baseline, Compare now, Open current snapshot, Open compare matrix, Edit profile	Capture/compare/compare assigned remain high-impact confirmed actions; archive remains destructive and confirmed

Proportionality Review

• New source of truth?: no.
• New persisted entity/table/artifact?: no.
• New abstraction?: no expected; optional page-local helper only if it reduces current inline complexity.
• New enum/state/reason family?: no.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: The page does not answer readiness and next action before technical detail.
• Existing structure is insufficient because: Existing helper methods expose individual truths, but the page hierarchy still presents them as peer sections.
• Narrowest correct implementation: Recompose the existing detail view around a derived decision summary and demote technical detail; preserve all domain behavior.
• Ownership cost: Focused tests, screenshot evidence, and one page-report update.
• Alternative intentionally rejected: A global UI framework/rule system from Spec 368 Candidate A; this spec keeps the fix page-local.
• Release truth: current-release productization truth.

Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by the implementation loop.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature for Filament/Livewire rendering and action state; Browser for integrated first-viewport/screenshot proof.
• Validation lane(s): fast-feedback for focused Pest tests; browser for bounded smoke; git diff --check; Pint for touched PHP if implementation changes PHP.
• Why this classification and these lanes are sufficient: The change is a Filament detail-view hierarchy and action-affordance change. Feature tests prove server-rendered text/action behavior; browser smoke proves first-viewport signal-to-noise and no JS/layout regression.
• New or expanded test families: Spec369BaselineProfileDecisionViewTest and optional Spec369BaselineProfileDecisionViewSmokeTest.
• Fixture / helper cost impact: Use existing baseline profile, snapshot, assignment, and workspace helpers/factories. Do not introduce broad seeded demo fixtures.
• Heavy-family visibility / justification: Browser coverage is explicit and limited to the Baseline Profile detail page because the source finding is browser-verified UI signal-to-noise.
• Special surface test profile: shared-detail-family / strategic-surface.
• Standard-native relief or required special coverage: Native Filament components should carry layout; special coverage required for decision-first default visibility and dangerous-action preservation.
• Reviewer handoff: Reviewers must confirm no new readiness truth, no action authorization regression, no technical detail hidden from permitted users, and no raw metadata in the primary decision block.
• Budget / baseline / trend impact: none expected; record if browser smoke or fixture setup expands materially.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec369
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec369BaselineProfileDecisionViewSmokeTest.php --compact if browser test is added
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=BaselineProfile
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check
• Runtime impact: UI rendering and action hierarchy only; no migrations, env vars, queues, scheduler, storage, or external API changes expected.

User Stories & Testing

User Story 1 - Decide baseline readiness quickly (Priority: P1)

As a workspace manager, I want the Baseline Profile detail page to summarize whether the baseline is ready and what I should do next, so I can act without parsing technical scope and metadata first.

Independent Test: Render a profile with current snapshot, latest attempt, assignments, and compare readiness. Assert the first decision section contains readiness, reason, impact, snapshot basis, assignment signal, and one dominant next action before normalization lineage or metadata.

Acceptance Scenarios:

1. Given an active baseline profile with a consumable current snapshot and assigned environments, When the detail page renders, Then it shows a ready/comparable decision summary and the dominant safe action is compare-oriented when authorized.
2. Given an active profile without a consumable snapshot, When the detail page renders, Then it shows why compare is blocked and the dominant safe action is capture-oriented when authorized.
3. Given an invalid or unsupported governed-subject scope, When the detail page renders, Then it explains the blocker and points to profile review/edit without exposing raw scope JSON in the decision block.

User Story 2 - Preserve high-impact action safety (Priority: P1)

As a reviewer, I want capture/compare/archive actions to keep their confirmation, authorization, audit, and OperationRun behavior while the page layout changes, so productization does not weaken governance safety.

Independent Test: Use existing Livewire action tests plus new assertions to prove capture, compare, and compare assigned environments remain confirmed/capability-gated and keep Open operation links/toasts when a run starts or is already queued.

Acceptance Scenarios:

1. Given a readonly workspace member, When the detail page renders, Then high-impact actions are disabled or hidden exactly as existing policy requires and the decision summary does not imply the actor can mutate.
2. Given an owner starts capture or compare, When the action succeeds, Then the existing OperationRun queued/duplicate feedback and canonical operation link behavior remains unchanged.
3. Given an archive/destructive action remains available through existing placement, When it is inspected in tests, Then it still requires confirmation and authorization.

User Story 3 - Keep technical proof accessible but secondary (Priority: P2)

As a support-oriented operator, I want normalization lineage, timestamps, related context, and technical proof links available after the main decision, so I can diagnose without making every operator parse internals first.

Independent Test: Render the detail page and assert normalization lineage, metadata, related snapshot, compare matrix, and operation proof links remain accessible but are not the first decision content.

Acceptance Scenarios:

1. Given a profile with canonical governed-subject scope, When the detail page renders, Then normalization lineage is visible in a secondary section or disclosure, not in the main decision block.
2. Given a profile has a current snapshot or compare matrix route, When the page renders, Then related context links remain available and capability-safe.
3. Given browser smoke captures the page, When the first viewport is reviewed, Then technical metadata no longer competes with the primary readiness decision.

Functional Requirements

• FR-001: The Baseline Profile detail page MUST render a first-read decision summary above technical scope and metadata.
• FR-002: The decision summary MUST state baseline readiness, reason, impact, current snapshot basis, latest attempt state, assignment/usefulness signal, and one dominant next action when a safe action exists.
• FR-003: The summary MUST derive only from existing BaselineProfile, BaselineSnapshot, BaselineTenantAssignment, compare readiness, and OperationRun/link truth.
• FR-004: The page MUST NOT create a new persisted readiness field, status family, or source of truth.
• FR-005: Technical scope detail, normalization lineage, timestamps, raw IDs, and support diagnostics MUST be secondary to the primary decision.
• FR-006: Existing related context links to current snapshot and compare matrix MUST remain available and capability-safe.
• FR-007: Capture baseline, compare now, compare assigned environments, edit, and archive action availability MUST remain governed by existing server-side authorization and UI enforcement.
• FR-008: High-impact capture/compare actions MUST retain ->action(...), ->requiresConfirmation(), existing modal inputs, existing OperationRun queued/duplicate feedback, and canonical Open operation links.
• FR-009: No existing destructive action may move into a more prominent unsafe placement without explicit confirmation, authorization, and audit proof.
• FR-010: The implementation MUST keep BaselineProfileResource global search disabled unless a separate spec changes global search posture.
• FR-011: The page MUST remain workspace-owned and MUST not inherit hidden environment context for authorization or primary scope.
• FR-012: The implementation MUST update UI audit coverage notes or explicitly document why route/design-coverage counts are unchanged.

Non-Functional Requirements

• NFR-001: The change MUST remain page-local to Baseline Profile detail unless implementation proves a minimal shared helper is required.
• NFR-002: The decision summary MUST remain scan-first and avoid duplicating the same status/reason/next-action content across multiple first-viewport sections.
• NFR-003: No Graph calls may occur during UI rendering.
• NFR-004: The page MUST continue to render using Filament v5 / Livewire v4-compatible components and tests.
• NFR-005: Browser smoke MUST stay bounded to the Baseline Profile detail view and required before/after screenshot evidence.

Out Of Scope

• Baseline capture engine, compare engine, snapshot storage, assignment model, OperationRun lifecycle, provider contracts, migrations, queues, restore/backup workflows, system panel fixtures, global shell density work, and broad UI standards.

Acceptance Criteria

• AC-001: Baseline Profile detail first viewport answers "Is this baseline ready and what should I do next?" before showing normalization lineage or metadata.
• AC-002: Authorized and unauthorized users see action affordances consistent with existing policy/capability behavior.
• AC-003: Capture and compare actions still create or reuse OperationRun feedback through existing shared paths.
• AC-004: Current snapshot, latest attempt, compare readiness, assigned environments, and related context remain accurate and accessible.
• AC-005: UI audit/page-report coverage is updated or explicitly marked unchanged with a rationale.
• AC-006: Focused Pest/Livewire tests and bounded browser smoke pass or a non-run reason is documented.

Success Criteria

• Operators can identify readiness, blocker/reason, impact, and next action from the first decision block without reading normalization lineage.
• No new persisted truth, status family, or broad UI framework is introduced.
• Existing Baseline Profile action safety tests remain green.
• The page earns a materially better signal-to-noise assessment than Spec 368's 2.8 baseline in a follow-up browser review.

Risks

• Moving sections could hide technical evidence needed by support users.
• A derived summary helper could accidentally become a second readiness source.
• Header action hierarchy could regress existing high-impact action safety.
• Browser smoke may require a stable baseline fixture with snapshot and assignment state.

Assumptions

• The existing baseline helpers (currentSnapshotLabel, latestAttemptedSnapshotLabel, compareReadinessLabel, profileNextStep, related context entries) are sufficient starting points.
• No schema change is needed.
• BaselineProfileResource remains globally searchable disabled.
• Spec 368's browser screenshot is sufficient before-state evidence for candidate selection.

Open Questions

• None blocking preparation. Implementation should verify whether the decision summary can be expressed cleanly inside BaselineProfileResource::infolist() or needs one small page-local helper.

Follow-up Spec Candidates

• Backup Set View decision-first productization.
• OperationRun View metadata/proof separation polish, only after Spec 367 actionability settles.
• Global Surface Information Architecture Contract v1 if repeated bloat persists after page-local fixes.
• Diagnostic Surface Separation v1 for Environment Diagnostics, Required Permissions, and system panel fixture coverage.