TenantAtlas/specs/336-baseline-compare-product-process-flow-alignment/spec.md

Feature Specification: Spec 336 - Baseline Compare Product Process Flow Alignment

Feature Branch: 336-baseline-compare-product-process-flow-alignment
Created: 2026-05-29
Status: Draft
Type: Runtime UX alignment / Product Process Flow consumer / Baseline Compare productization hardening
Runtime posture: Reuse existing Spec 332 Product Process Flow system. No backend compare engine rewrite. No new persisted truth.
Input: User-provided Spec 335 draft (repo-truth reconciled to Spec 336 because 335-* already exists in this repo).

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

• Problem: Baseline Compare is an operator-facing decision surface, but its readiness/proof/evidence language is not yet consistently aligned to the shared Product Process Flow vocabulary introduced in Spec 332, especially across non-trivial repo-backed states (snapshot blocked, compare run required/running/failed, evidence gaps, decision output availability).
• Today's failure: Operators must infer “what blocks compare” and “what proof exists” from mixed page sections and state-specific copy, instead of one consistent flow-based contract (complete/missing/blocked, proof/evidence separation, one primary next action).
• User-visible improvement: Baseline Compare answers in the first screen: Status, Reason, Impact, Primary next action, Compare readiness flow, Available inputs, Compare proof, Decision output, Evidence state, with diagnostics collapsed by default.
• Smallest enterprise-capable version: Reuse Spec 332’s Product Process Flow pattern and adapt Baseline Compare Landing to render the same flow contract across repo-backed states without changing compare logic, persistence, or OperationRun semantics.
• Explicit non-goals: New compare engine, new snapshot generation engine, new drift detection algorithm, new evidence generator backend, OperationRun model changes, new migrations, new packages, new queues/scheduler/env/storage requirements, Restore flow changes, cross-tenant promotion, bulk governance workflow engine.
• Permanent complexity imported: A small Baseline Compare presenter/view-model (only if required), a reusable flow render primitive if already justified by 2+ consumers (Restore + Baseline Compare), focused Pest Feature tests + browser smoke, spec artifacts (repo truth map, state contract, screenshots).
• Why now: Spec 332 established the shared Product Process Flow system with Restore as the first consumer; Baseline Compare is the next highest-leverage consumer surface for vocabulary and governance consistency.
• Why not local: Copy tweaks alone do not align the step semantics, proof/evidence separation, and “next action” contract across the full state family; without a shared pattern, Baseline Compare will drift again as new states are productized.
• Approval class: Core Enterprise
• Red flags triggered: Reachable UI surface change (strategic surface), governance language/tone correctness, proof/evidence truth separation. Defense: reuse existing repo truth, no new backend foundation, tests + browser smoke required, no false “healthy/compliant/customer-safe” claims.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: tenant (environment-owned operator surface)
• Primary Routes:
  • Baseline Compare Landing route (environment-owned): /admin/workspaces/{workspace}/environments/{environment}/baseline-compare
  • Downstream surfaces referenced but not reworked: Baseline Compare Matrix, Findings, Baseline Profiles, Baseline Snapshots, Operation Run detail.
• Data Ownership:
  • Tenant/environment-owned: ManagedEnvironment, BaselineTenantAssignment, OperationRun, Finding, InventoryItem (observed state), evidence gap summaries (run context/diagnostics).
  • Workspace-owned: BaselineProfile, BaselineSnapshot (workspace-owned baseline artifacts).
  • No new tables or persisted truth introduced.
• RBAC:
  • Environment membership + existing environment access checks required to view.
  • Actions appear only when authorized:
    • Start compare: capability TENANT_SYNC (existing UiEnforcement + server-side enforcement).
    • View proofs/linked artifacts: existing policies/capabilities for OperationRuns, findings, baselines.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: N/A - environment-owned route.
• Explicit entitlement checks preventing cross-tenant leakage: Continue deny-as-not-found for non-members and ensure all linked artifacts remain workspace/environment scoped.

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

If any box except "No UI surface impact" is checked, complete the UI/Productization Coverage section below. "No UI surface impact" MUST NOT be checked together with another impact box; if a guarded file path changes for non-surface reasons, keep only "No UI surface impact" checked and explain the rationale below.

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

• Route/page/surface: Baseline Compare Landing (App\Filament\Pages\BaselineCompareLanding, filament.pages.baseline-compare-landing view).
• Current or new page archetype: Baseline Compare is an operator governance decision surface (existing strategic drift/compare surface; archetype unchanged).
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified (existing implementation + tests; see repo-truth-map.md).
• Existing pattern reused: Spec 332 Product Process Flow system v1 (Restore consumer) + existing Baseline Compare decision-first workbench (Spec 330 baseline).
• New pattern required: none (reuse shared flow pattern); bounded extraction only if required for true reuse.
• Screenshot required: yes, browser smoke screenshots saved under specs/336-baseline-compare-product-process-flow-alignment/artifacts/screenshots/.
• Page audit required: no (no route/archetype change; keep feature-local screenshots + tests as proof).
• Customer-safe review required: medium. This is operator UI, but copy must not imply “healthy/compliant/customer-safe” without repo proof; “matches baseline within available coverage” is the max claim.
• Dangerous-action review required: no destructive-action change. Existing “Compare Now” remains a high-impact operation start and must keep confirmation + capability enforcement + OperationRun proof semantics intact.
• Coverage files updated or explicitly not needed:
  • 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
• No-impact rationale when applicable: N/A (UI surface impact exists; coverage files unchanged because archetype/route family unchanged and feature-local artifacts serve as proof).

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): decision cards, status messaging, OperationRun proof links, flow gating, diagnostics disclosure, governance “next action” contract
• Systems touched: Spec 332 Product Process Flow system v1 + Baseline Compare Landing surface
• Existing pattern(s) to extend: Restore Run Create presenter + process flow render (Spec 332); Baseline Compare decision-first workbench (Spec 330)
• Shared contract / presenter / builder / renderer to reuse: reuse Spec 332 “flow model shape” and render conventions; reuse OperationRun deep links via OperationRunLinks (already used)
• Why the existing shared path is sufficient or insufficient: sufficient for vocabulary and gating model; Baseline Compare requires a horizontal readiness flow variant, so shared rendering may need a bounded extension (only if it reduces duplication vs 2 consumers).
• Allowed deviation and why: none by default; if a new shared horizontal flow renderer is introduced, it must be used by 2+ consumers (Baseline Compare + another consumer or extracted from Baseline Compare while preserving Restore behavior) and pass proportionality review.
• Consistency impact: Status/Reason/Impact/Next action ordering and copy rules stay consistent with Restore Safety; proof/evidence separation stays truthful; diagnostics remain collapsed by default.
• Review focus: no fake “all-clear” claims; no duplicate visible status blocks; capabilities gate action visibility; no raw/support disclosure by default.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: yes (existing Baseline Compare “Compare Now” + proof links)
• Shared OperationRun UX contract/layer reused: existing OperationUxPresenter, OperationRunLinks, OpsUxBrowserEvents (no new contract)
• Delegated start/completion UX behaviors: keep existing queued toast + “View run” deep link semantics; keep tenant/workspace-safe URL resolution through shared helpers.
• Local surface-owned behavior that remains: Baseline Compare-specific input selection (baseline snapshot selection) and state-specific next-action copy.
• Queued DB-notification policy: no change; no new DB notification.
• Terminal notification path: unchanged; stays via central lifecycle.
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• N/A - no shared provider/platform boundary touched (UI alignment only; compare strategy selection remains internal and unchanged).

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Use this section to classify UI and surface risk once. If the feature does not change an operator-facing surface, write N/A - no operator-facing surface change here and do not invent duplicate prose in the downstream surface tables.

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Baseline Compare Landing: process-flow alignment, state contract, proof/evidence separation	yes	Native Filament + shared primitives + existing Blade workbench	decision-first workbench + shared flow pattern	page	no	strategic surface, but bounded changes

Summary

Align Baseline Compare with the shared Product Process Flow system introduced in Spec 332.

Baseline Compare must answer, without operator inference:

• What is complete?
• What is missing or blocked?
• What proof exists?
• What is the next action?

This spec does not rebuild compare logic. It productizes and aligns the Baseline Compare surface across repo-backed states:

• no baseline assigned
• baseline assigned but compare snapshot missing/blocked
• compare run required
• compare in progress
• compare failed
• compare available with drift findings
• compare available with no open drift findings (with honest coverage/evidence constraints)
• evidence/coverage gaps present
• diagnostics available but collapsed

Repo-Truth First Requirement

Before runtime changes, this spec requires:

• specs/336-baseline-compare-product-process-flow-alignment/repo-truth-map.md
• specs/336-baseline-compare-product-process-flow-alignment/baseline-compare-state-contract.md

These documents classify sources as repo-verified, derived, not available, or deferred. No compare/evidence states may be invented.

Required Product Flow

Baseline Compare uses the Product Process Flow pattern (horizontal variant) with default steps:

1. Baseline assigned
2. Baseline snapshot
3. Environment snapshot / coverage proof
4. Compare run
5. Decision output

Step labels and user-facing states must remain repo-backed. If a “stale” concept is not repo-real, it must render as Unavailable with truthful copy.

Out Of Scope

• Any new compare engine, drift algorithm, snapshot generation engine, evidence generation backend, migrations, packages, queues/scheduler changes, env var/storage changes.
• Restore flow changes.
• Cross-surface Product Process Flow migrations beyond Baseline Compare.

Acceptance Criteria

• Baseline Compare renders a consistent decision-first surface with:
  • Status, Reason, Impact, Primary next action
  • Compare readiness flow visible across repo-backed states
  • Proof/input panel (repo-backed only)
  • Drift summary when repo-backed
  • Evidence/coverage gap state separated from “operation proof”
  • Diagnostics collapsed by default
• No false “healthy/compliant/customer-safe” claim is introduced.
• “No drift” claims are scoped to baseline-compare coverage truth and explicitly caveated when coverage/evidence gaps exist.
• Capability-first RBAC is respected for all actions and deep links.
• Feature tests + browser smoke exist for the declared state family.

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

If this feature adds or materially changes an operator-facing surface, fill out one row per affected surface. This role is orthogonal to the Action Surface Class / Surface Type below. Reuse the exact surface names and classifications from the UI / Surface Guardrail Impact section above.

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 Compare Landing	Primary Decision Surface	Operator decides whether baseline drift requires governance action, or what blocks compare	Status, Reason, Impact, Primary next action, Compare readiness flow, Available inputs/proof, Evidence/coverage status	Findings table/matrix, evidence gap buckets, OperationRun detail, raw compare diagnostics (collapsed)	Primary because it is the environment-owned compare decision surface	Follows baseline governance decision before matrix/detail	Prevents raw diff/zero findings from reading as an all-clear

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

If this feature adds or materially changes a detail or status surface, fill out one row per affected surface. Reuse the same surface names used above and make the disclosure hierarchy explicit instead of assuming it.

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 Compare Landing	operator-MSP, manager, support reviewer	Status, Reason, Impact, Primary next action, readiness flow, proof inputs, drift summary (repo-backed only)	Evidence gaps, coverage warnings, compare diagnostics disclosure, OperationRun proof link	Raw diff/payloads, deep provider diagnostics, stack traces (never default-visible)	One state-specific primary next action (assign baseline / resolve snapshot / run compare / open operation / review findings / review evidence gaps)	Raw/support sections collapsed and capability-aware; no raw diff by default	One top decision card; lower sections add proof/detail without repeating verdict blocks

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

If this feature adds or materially changes an operator-facing list, detail, queue, audit, config, or report surface, fill out one row per affected surface. Declare the broad Action Surface Class first, then the detailed Surface Type. Keep this table in sync with the Decision-First Surface Role section above and avoid renaming the same surface a second time.

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 Compare Landing	Workbench / Monitoring	Environment-owned drift/compare decision surface	Take the next governance action based on readiness + proof	Header action + explicit deep links (baselines, snapshot, run, findings)	N/A	Inside decision card/proof panel; no row actions	None introduced; Compare Now remains confirmation-required and capability-gated	/admin/workspaces/{workspace}/environments/{environment}/baseline-compare	N/A (page, not record detail)	Workspace + Environment are route-bound	Baseline Compare	Status/Reason/Impact/Next action + readiness flow + proof/evidence separation	N/A (existing surface, bounded alignment only)

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

If this feature adds a new operator-facing page or materially refactors one, fill out one row per affected page/surface. The contract MUST show how one governance case or operator task becomes decidable without unnecessary cross-page reconstruction.

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 Compare Landing	Workspace manager / governance operator	Decide whether drift requires review, or what blocks compare	Monitoring / decision-first workbench	Can this environment be compared against a baseline, and what action is required?	Decision card (Status/Reason/Impact/Next action), Compare readiness flow, Available inputs/proof, Drift summary when repo-backed, Evidence/coverage state	Raw compare diagnostics + raw diff/payload (collapsed; capability-aware)	assignment, snapshot truth, inventory coverage proof, run status/outcome, findings count/severity, evidence gaps	TenantPilot writes: OperationRun + drift Findings; may fetch provider content evidence depending on capture mode (no config mutation)	Open baseline profiles, Open baseline snapshot/proof, Compare now, Open operation, Review findings	Compare now (requires confirmation; capability-gated; OperationRun-backed)

Proportionality Review (mandatory when structural complexity is introduced)

Fill this section if the feature introduces any of the following:

• a new source of truth

• a new persisted entity, table, or artifact

• a new abstraction (interface, contract, registry, resolver, strategy, factory, orchestration layer)

• a new enum, status family, reason code family, or lifecycle category

• a new cross-domain UI framework, taxonomy, or classification system

• New source of truth?: no

• New persisted entity/table/artifact?: no

• New abstraction?: yes (small presenter/view-model to map repo-backed compare state to flow steps + decision card consistently)

• New enum/state/reason family?: no (reuse existing BaselineCompareStats state + baseline reason codes; no new taxonomy)

• New cross-domain UI framework/taxonomy?: no (reuse Spec 332 pattern; any shared renderer must stay a small primitive and be justified by 2+ consumers)

• Current operator problem: Baseline Compare readiness/proof/evidence state is not consistently expressed as a single “what is complete / what blocks / what proof exists / what next” contract across the full state family.

• Existing structure is insufficient because: current readiness flow is state-limited and relies on page-local composition; it encourages vocabulary drift and duplicative UI logic as more states are productized.

• Narrowest correct implementation: keep all domain truth as-is; add a thin presenter that computes decision/flow/proof panels from existing repo truth; render through one flow component/partial; update tests and browser smoke to lock the contract.

• Ownership cost: one presenter + one render partial (if needed), plus focused Feature tests + one browser smoke file + screenshot artifacts.

• Alternative intentionally rejected: new persisted readiness engine, new compare engine, new evidence backend, or “just copy tweaks” without a flow contract.

• Release truth: current-release productization and UX alignment over existing foundations.

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 this spec.

Canonical replacement is preferred over preservation.

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

For docs-only or template-only changes, state concise N/A or none. For runtime- or test-affecting work, classification MUST follow the proving purpose of the change rather than the file path or folder name.

• Test purpose / classification: Feature (Livewire render contract) + Browser (strategic surface smoke + disclosure guarantees).
• Validation lane(s): confidence + browser.
• Why this classification and these lanes are sufficient: This change is operator-facing UI contract alignment, state gating, and disclosure hierarchy. Feature tests prove the rendered contract per repo-backed state; Browser smoke proves the surface is framed correctly and raw/support sections remain collapsed by default.
• New or expanded test families: one new Feature test file + one new Browser smoke file for Spec 336 (existing Spec 330 baseline tests may be updated, not replaced).
• Fixture / helper cost impact: reuse existing tenant/workspace helpers (createUserWithTenant, setAdminPanelContext, existing baseline compare helpers). No new default-heavy factories or seeds.
• Heavy-family visibility / justification: Browser coverage is explicit because Baseline Compare is a strategic operator surface with high risk of “false all-clear” and disclosure regressions.
• Special surface test profile: monitoring-state-page + global-context-shell.
• Standard-native relief or required special coverage: special coverage required; this is not a plain CRUD resource.
• Reviewer handoff: Verify (1) no fake drift/evidence claims, (2) one primary next action, (3) readiness flow visible across states, (4) capability-gated actions, (5) diagnostics collapsed/no raw diff by default, (6) route/context isolation.
• Budget / baseline / trend impact: none expected; browser smoke remains single-file scoped.
• Escalation needed: none (document-in-feature only if a new shared renderer is introduced and needs explicit exception rationale).
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='BaselineCompare|ProductProcessFlow|EnvironmentOwned|Spec332|Spec330' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Baseline Compare Is Decidable (Priority: P1)

As a governance operator, I want Baseline Compare to answer whether compare is usable and which governance action is required without reading raw compare diagnostics.

Why this priority: Baseline Compare is a strategic decision surface and is easy to misread as “all clear” when evidence/coverage is missing.

Independent Test: Render Baseline Compare Landing for each repo-backed state and assert decision card + readiness flow + proof/evidence separation + collapsed diagnostics.

Acceptance Scenarios:

1. Given no baseline assignment (BaselineCompareStats.state = no_assignment), When the page renders, Then it shows Baseline not assigned, one primary next action (Open baseline profiles when authorized), readiness flow with Baseline assigned: Missing, and no raw diff by default.
2. Given baseline assigned but no usable snapshot (state = no_snapshot), When the page renders, Then it shows Baseline snapshot required (or equivalent truthful status), marks the snapshot step as missing/blocked, and does not present a drift “result”.
3. Given compare inputs exist but no run exists (state = idle), When the page renders, Then it shows Compare run required and a capability-gated Compare now action.
4. Given a compare run is queued/running (state = comparing), When the page renders, Then it shows Compare in progress plus OperationRun proof link, and keeps diagnostics collapsed.
5. Given a compare run failed (state = failed), When the page renders, Then it shows Compare failed plus OperationRun proof link, and does not imply usable drift evidence.
6. Given a compare run completed with drift findings (state = ready, findings > 0), When the page renders, Then it shows Drift requires review and offers Review drift findings as the primary next action when authorized.
7. Given a compare run completed with zero open findings (state = ready, findings = 0), When the page renders, Then it shows a scoped “no confirmed drift” outcome and does not claim “healthy/compliant/customer-safe”; if coverage/evidence gaps exist, the page must state that the outcome requires review.

---

User Story 2 - Proof And Evidence Are Separated (Priority: P2)

As an operator, I want OperationRun proof (execution truth) and evidence/coverage truth to be visible as separate panels so I don’t treat completion as evidence quality.

Independent Test: For a ready run with coverage warnings/evidence gaps, assert that the page shows evidence/coverage warnings and does not label the outcome as fully trustworthy.

---

User Story 3 - Context + RBAC Are Enforced (Priority: P2)

As a workspace admin, I need Baseline Compare to never leak cross-workspace or cross-environment baseline/run/finding data and to hide or disable actions when unauthorized.

Independent Test: Use fixtures that create baseline profiles/snapshots/runs/findings in a different workspace/environment and assert they are not visible; assert unauthorized actions are hidden/disabled.

Edge Cases

• Assigned baseline profile exists but is not active for compare start (COMPARE_PROFILE_NOT_ACTIVE): status becomes “Needs review” with truthful next action; no drift claim.
• Snapshot is building/incomplete/superseded: snapshot step reflects building/incomplete truth; compare start remains blocked; copy does not promise availability without proof.
• Invalid/unsupported/mixed scope: readiness flow shows baseline snapshot step as available but compare run step as blocked/unavailable with Needs review copy (no raw reason codes in primary UI).

Requirements (mandatory)

Constitution alignment (required): If this feature introduces any Microsoft Graph calls, any write/change behavior, or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates (preview/confirmation/audit), tenant isolation, run observability (OperationRun type/identity/visibility), and tests. If security-relevant DB-only actions intentionally skip OperationRun, the spec MUST describe AuditLog entries.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): If this feature introduces new persistence, new abstractions, new states, or new semantic layers, the spec MUST explain:

• which current operator workflow or current product truth requires the addition now,
• why a narrower implementation is insufficient,
• whether the addition is current-release truth or future-release preparation,
• what ownership cost it creates,
• and how the choice follows the default bias of deriving before persisting, replacing before layering, and being explicit before generic. If the feature introduces a new enum/status family, DTO/presenter/envelope, persisted entity/table, interface/contract/registry/resolver, or taxonomy/classification system, the Proportionality Review section above is mandatory.

Constitution alignment (XCUT-001): If this feature touches a cross-cutting interaction class such as notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, or evidence/report viewers, the spec MUST:

• state whether the feature is cross-cutting,
• name the existing shared pattern(s) and shared contract/presenter/builder/renderer to extend,
• explain why the existing shared path is sufficient or why it is insufficient for current-release truth,
• record any allowed deviation, the consistency it must preserve, and its ownership/spread-control cost,
• and make the reviewer focus explicit so parallel local UX paths do not appear silently.

Constitution alignment (UI-COV-001): Every spec MUST complete the UI Surface Impact block. If the feature adds, removes, renames, or materially changes any reachable UI surface, including navigation entries, Filament panel/provider surfaces, Livewire surfaces, Blade views, forms, tables, modals, drawers, actions, status/evidence/review presentation, customer-facing views, or workspace/environment context presentation, the spec MUST also complete UI/Productization Coverage and state:

• the affected route/page/surface,
• page archetype,
• design depth,
• repo-truth level,
• target pattern or mockup need,
• customer/operator safety review need,
• dangerous-action review need,
• and which docs/ui-ux-enterprise-audit/ artifacts were updated or why the surface is unresolved/manual review. If there is no reachable UI impact, the spec MUST check exactly No UI surface impact and provide a short rationale. Coverage is proportional: small non-material UI diffs may use a checked no-impact rationale, normal domain pages may reuse existing patterns, and only strategic, customer-facing, dangerous-action-bearing, or materially new surfaces require screenshots or full page reports.

Constitution alignment (DECIDE-AUD-001 / OPSURF-001): If this feature changes a detail or status surface, the spec MUST describe:

• how the surface separates customer-readable decision content, operator diagnostics, and support/raw evidence,
• which audience modes are in scope (customer/read-only, operator/MSP, support/platform),
• which content is hidden, collapsed, or capability-gated by default,
• how one dominant next action is preserved,
• and how duplicate visible truth is prevented.

Constitution alignment (PROV-001): If this feature touches a shared provider/platform seam, the spec MUST:

• classify each touched seam as provider-owned or platform-core,
• keep provider-specific semantics out of platform-core contracts, taxonomies, identifiers, compare semantics, and operator vocabulary unless explicitly justified,
• name the neutral platform terms or shared contracts being preserved,
• explain why any retained provider-specific semantics are the narrowest current-release truth,
• and state whether the remaining hotspot is resolved in-feature or escalated as a follow-up spec.

Constitution alignment (TEST-GOV-001): If this feature changes runtime behavior or tests, the spec MUST describe:

• the actual test-purpose classification (Unit, Feature, Heavy-Governance, or Browser) and why that classification matches the real proving purpose,
• the affected validation lane(s) and why they are the narrowest sufficient proof,
• any new or expanded heavy-governance or browser coverage,
• any fixture, helper, factory, seed, provider, workspace, membership, session, or default setup cost added or avoided,
• how any heavy family stays explicit rather than becoming accidental default breadth,
• the reviewer handoff for lane fit, hidden-cost checks, and the exact minimal validation commands,
• any expected budget, baseline, or trend impact,
• whether escalation stays inside this feature or resolves as document-in-feature, follow-up-spec, or reject-or-split,
• and the exact minimal validation commands reviewers should run.

Constitution alignment (OPS-UX): If this feature creates/reuses an OperationRun, the spec MUST:

• explicitly state compliance with the default Ops-UX 3-surface feedback contract (toast intent-only, progress surfaces, terminal DB notification) and whether any queued DB notification is explicitly opted into,
• state that OperationRun.status / OperationRun.outcome transitions are service-owned (only via OperationRunService),
• describe how summary_counts keys/values comply with OperationSummaryKeys::all() and numeric-only rules,
• clarify scheduled/system-run behavior (initiator null → no terminal DB notification; audit is via Monitoring),
• list which regression guard tests are added/updated to keep these rules enforceable in CI.

Constitution alignment (OPS-UX-START-001): If this feature creates, queues, deduplicates, resumes, blocks, completes, or links to an OperationRun, the spec MUST:

• include the OperationRun UX Impact section,
• name the shared OperationRun UX contract/layer being reused,
• delegate queued toast/link/artifact-link/browser-event/queued-DB-notification/dedupe-or-blocked messaging/tenant-safe URL resolution to that shared path,
• keep local surface code limited to initiation inputs and operation-specific data capture,
• keep queued DB notifications explicit opt-in unless the spec intentionally defines a different policy,
• route terminal notifications through the central lifecycle mechanism,
• and document any exception with an explicit spec decision, architecture note, test or guard-test rationale, and temporary follow-up migration decision.

Constitution alignment (RBAC-UX): If this feature introduces or changes authorization behavior, the spec MUST:

• state which authorization plane(s) are involved (tenant/admin /admin + tenant-context /admin/t/{tenant}/... vs platform /system),
• ensure any cross-plane access is deny-as-not-found (404),
• explicitly define 404 vs 403 semantics:
  • non-member / not entitled to workspace scope OR tenant scope → 404 (deny-as-not-found)
  • member but missing capability → 403
• describe how authorization is enforced server-side (Gates/Policies) for every mutation/operation-start/credential change,
• reference the canonical capability registry (no raw capability strings; no role-string checks in feature code),
• ensure global search is tenant-scoped and non-member-safe (no hints; inaccessible results treated as 404 semantics),
• ensure destructive-like actions require confirmation (->requiresConfirmation()),
• include at least one positive and one negative authorization test, and note any RBAC regression tests added/updated.

Constitution alignment (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP (e.g., token exchange) on /auth/* endpoints without an OperationRun. This MUST NOT be used for Monitoring/Operations pages.

Constitution alignment (BADGE-001): If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean), the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values.

Constitution alignment (UI-FIL-001): If this feature adds or changes Filament or Blade UI for admin/operator surfaces, the spec MUST describe:

• how the affected surface follows docs/ui/tenantpilot-enterprise-ui-standards.md,
• which native Filament components or shared UI primitives are used,
• whether any local replacement markup was avoided for badges, alerts, buttons, or status surfaces,
• how semantic emphasis is expressed through Filament props or central primitives rather than page-local color/border classes,
• how the feature avoids ad-hoc custom styling for cards, buttons, hovers, badges, icons, progress bars, empty states, and interactive rows,
• how any custom Blade, Livewire widget, page, or dashboard surface preserves Filament-native interaction semantics and avoids introducing an independent button, status-color, spacing, or card system,
• how each affected page or focused action area keeps at most one dominant primary action and keeps secondary actions neutral unless they are destructive or the semantic state change is the point of the action,
• how status is conveyed through BADGE-001 badges, labels, chips, or supporting text rather than arbitrary button colors or per-card custom action styling,
• how hover, pointer, focus, shadow, or similar interactive affordance is used only when a repo-real route/action and permitted capability exist, and how non-interactive rows remain visibly static,
• how any required local Blade/Tailwind cards still preserve dark mode correctness, spacing consistency, badge semantics, action hierarchy, progressive disclosure, accessibility, and Filament visual language, and are used to compose product-specific layout rather than a parallel local design system,
• and any exception where Filament or a shared primitive was insufficient, including why the exception is necessary and how it avoids introducing a new local status language.

Constitution alignment (UI-NAMING-001): If this feature adds or changes operator-facing buttons, header actions, run titles, notifications, audit prose, or related helper copy, the spec MUST describe:

• the target object,
• the operator verb,
• whether source/domain disambiguation is actually needed,
• how the same domain vocabulary is preserved across button labels, modal titles, run titles, notifications, and audit prose,
• and how implementation-first terms are kept out of primary operator-facing labels.

Constitution alignment (DECIDE-001): If this feature adds or changes operator-facing surfaces, the spec MUST describe:

• whether each affected surface is a Primary Decision Surface, Secondary Context Surface, or Tertiary Evidence / Diagnostics Surface, and why,
• which human-in-the-loop moment each primary surface supports,
• what MUST be visible immediately for the first decision,
• what is preserved but only revealed on demand,
• why any new primary surface cannot live inside an existing decision context,
• how navigation follows operator workflows rather than storage structures,
• how one governance case remains decidable in one focused context,
• how any new automation, notifications, or autonomous governance logic reduce search/review/click load,
• and how the resulting default experience is calmer and clearer rather than merely larger.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): If this feature adds or changes an operator-facing surface, the spec MUST describe:

• the chosen broad action-surface class and why it is the correct classification,
• the chosen detailed surface type and why it is the correct refinement,
• the one most likely next operator action,
• the one and only primary inspect/open model,
• whether row click is required, allowed, or forbidden,
• whether explicit View or Inspect is present, and why it is present or forbidden,
• where pure navigation lives and why it is not competing with mutation,
• where secondary actions live,
• where destructive actions live,
• how grouped actions are ordered by meaning, frequency, and risk,
• the canonical collection route and canonical detail route,
• the scope signals shown to the operator and what real effect each one has,
• the canonical noun used across routes, labels, runs, notifications, and audit prose,
• which critical operational truth is visible by default,
• and any catalogued exception type, rationale, and dedicated test coverage.

Constitution alignment (ACTSURF-001 - action hierarchy): If this feature adds or materially changes header actions, row actions, bulk actions, or workbench controls, the spec MUST describe:

• how navigation, mutation, context signals, selection actions, and dangerous actions are separated,
• why any visible secondary action deserves primary-plane placement,
• why any ActionGroup is structured rather than a mixed catch-all,
• and why any workflow-hub, wizard, system, or other special-type exception is genuine rather than a convenience shortcut.

Constitution alignment (OPSURF-001): If this feature adds or materially refactors an operator-facing surface, the spec MUST describe:

• how the default-visible content stays operator-first on /admin and avoids raw implementation detail,
• which diagnostics are secondary and how they are explicitly revealed,
• how the dominant next action stays primary and how duplicate visible truth is avoided,
• which status dimensions are shown separately (execution outcome, data completeness, governance result, lifecycle/readiness) and why,
• how each mutating action communicates its mutation scope before execution (TenantPilot only, Microsoft tenant, or simulation only),
• how dangerous actions follow the safe-execution pattern (configuration, safety checks/simulation, preview, hard confirmation where required, execute),
• how workspace and tenant context remain explicit in navigation, action copy, and page semantics,
• and the page contract for each new or materially refactored operator-facing page.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): If this feature adds UI semantics, presenters, explanation layers, status taxonomies, or other interpretation layers, the spec MUST describe:

• why direct mapping from canonical domain truth to UI is insufficient,
• which existing layer is replaced or why no existing layer can serve,
• how the feature avoids creating redundant truth across models, service results, presenters, summaries, wrappers, and persisted mirrors,
• and how tests focus on business consequences rather than thin indirection alone.

Constitution alignment (Filament Action Surfaces): If this feature adds or modifies any Filament Resource / RelationManager / Page, the spec MUST include a “UI Action Matrix” (see below) and explicitly state whether the Action Surface Contract is satisfied. The same section MUST state that each affected surface has exactly one primary inspect/open model, that redundant View actions are absent, that empty ActionGroup / BulkActionGroup placeholders are absent, and that destructive actions follow the required placement rules for the chosen surface type. If the contract is not satisfied, the spec MUST include an explicit exemption with rationale. The same section MUST also state whether UI-FIL-001 is satisfied and identify any approved exception. Constitution alignment (UX-001 — Layout & Information Architecture): If this feature adds or modifies any Filament screen, the spec MUST describe compliance with UX-001: Create/Edit uses Main/Aside layout (3-col grid), all fields inside Sections/Cards (no naked inputs), View pages use Infolists (not disabled edit forms), status badges use BADGE-001, empty states have a specific title + explanation + exactly 1 CTA, and tables provide search/sort/filters for core dimensions. If UX-001 is not fully satisfied, the spec MUST include an explicit exemption with documented rationale.

Functional Requirements

• FR-001: Baseline Compare Landing MUST render a decision card with Status, Reason, Impact, and exactly one Primary next action for every repo-backed compare state.
• FR-002: Baseline Compare Landing MUST render the Compare readiness flow (Product Process Flow horizontal variant) across repo-backed states using the default step set:
  1. Baseline assigned, 2) Baseline snapshot, 3) Environment snapshot / coverage proof, 4) Compare run, 5) Decision output.
• FR-003: Each readiness step MUST be derived from existing repository truth sources and MUST never show a fake “Available/Complete” state.
• FR-004: Operation proof (execution truth) MUST be separated from evidence/coverage truth; OperationRun completion MUST NOT be presented as “evidence-ready” by default.
• FR-005: Diagnostics MUST be collapsed by default; raw diff/payload MUST NOT be default-visible.
• FR-006: Baseline Compare MUST show drift summary and a “Review findings” path only when repo-backed findings exist and the user is authorized.
• FR-007: Compare now MUST remain ->requiresConfirmation(), capability-gated (TENANT_SYNC), and OperationRun-backed (existing behavior preserved).
• FR-008: “No drift” outcomes MUST be scoped: they may claim “no open drift findings for this baseline comparison” and must explicitly caveat when coverage/evidence gaps exist.
• FR-009: The page MUST remain environment-owned: no /admin/t routes, no legacy tenant query aliases as authority, no cross-workspace leakage via linked artifacts.

UX Requirements

• Decision-first ordering: Decision card → readiness flow → proof/inputs → drift summary → diagnostics (collapsed).
• One primary next action per state (no competing primary CTAs).
• No duplicate lower summary blocks repeating status/reason/impact.
• Horizontal readiness flow is the default; step badges are readable in dark mode; no clipped labels.

RBAC / Security Requirements

• Action visibility MUST follow capability-first RBAC (hide action or show unavailable state per existing conventions).
• Cross-workspace/environment artifacts (baseline profiles, snapshots, runs, findings) MUST not be visible via this page unless authorized and scoped.

Data / Truth-Source Requirements

• Readiness flow state MUST be derived from:
  • baseline assignment: BaselineTenantAssignment + BaselineProfile
  • snapshot truth: BaselineSnapshotTruthResolver
  • environment snapshot / coverage proof: latest inventory sync coverage + observed inventory presence (repo-backed)
  • compare run: OperationRunType::BaselineCompare
  • decision output: open drift findings + completed run outcome + coverage/evidence gap truth (repo-backed)
• No new persisted “readiness” or “decision” entities.

Required Tests

• Feature test: apps/platform/tests/Feature/Filament/Spec336BaselineCompareProductProcessFlowAlignmentTest.php
• Browser smoke: apps/platform/tests/Browser/Spec336BaselineCompareProductProcessFlowAlignmentSmokeTest.php
• Update existing Baseline Compare tests as needed to reflect the new readiness flow visibility across states (do not delete historical assertions without replacement coverage).

Required Screenshots

Save under specs/336-baseline-compare-product-process-flow-alignment/artifacts/screenshots/:

1. 01-no-baseline-assigned.png
2. 02-baseline-snapshot-required.png
3. 03-compare-run-required.png
4. 04-compare-result-available.png
5. 05-evidence-unavailable.png
6. 06-diagnostics-collapsed.png
7. 07-dark-mode.png

If a state is not reachable, implementation close-out MUST document why (repo-truth).

UI Action Matrix (mandatory when Filament is changed)

If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?), RBAC gating (capability + enforcement helper), whether the mutation writes an audit log, and any exemption or exception used.

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions | |---|---|---|---|---|---|---|---|---|---| | Baseline Compare Landing | apps/platform/app/Filament/Pages/BaselineCompareLanding.php | Compare now (confirmation + capability-gated), optional Back link | N/A | none | none | state-driven primary CTA inside decision card (e.g. Open baseline profiles) | N/A | N/A | yes (existing baseline compare OperationRun + audit logger; unchanged) | ActionSurfaceDeclaration is list-only read-only with explicit exemptions; no destructive actions introduced |

Key Entities (include if feature involves data)

• BaselineTenantAssignment: environment baseline assignment.
• BaselineProfile: workspace-owned baseline definition and scope/capture mode.
• BaselineSnapshot: workspace-owned immutable baseline snapshot (compare input).
• OperationRun: execution proof for baseline compare (OperationRunType::BaselineCompare).
• Finding: drift findings derived from compare (finding_type = drift, source = baseline.compare).

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A reviewer can open Baseline Compare and identify the visible status, reason, impact, proof basis, blocker, and primary next action within five seconds for each supported state.
• SC-002: The Compare readiness flow is visible across repo-backed states and does not show fake “Available/Complete” steps.
• SC-003: Diagnostics remain collapsed by default; raw diff/payload is not default-visible; no duplicate visible decision summary blocks exist.
• SC-004: Tests pass (Feature + Browser smoke), and the required screenshots are captured (or unreachable states documented with repo-truth reasons).