TenantAtlas/specs/355-platform-sellable-smoke-matrix/spec.md

Feature Specification: Spec 355 - Platform Sellable Smoke Matrix

Feature Branch: 355-platform-sellable-smoke-matrix
Created: 2026-06-05
Status: Draft
Type: Productization gate / browser smoke matrix / sellable readiness / operator-flow verification
Depends on: Specs 351, 352, 353, 354
Runtime posture: Verification-first. Browser/readiness gate with minimal fixes only when a verified P0/P1 issue is directly in scope. No new product surface, no new framework, no customer portal, no PDF renderer, no AI lane, and no broad navigation rewrite.
Input: Direct user-provided Spec 355 draft plus repo truth from current operator/productization surfaces, existing browser smoke tests, and adjacent Specs 351-354.

Dependencies And Repo-Truth Adjustments

Spec 355 is a bounded readiness gate over already repo-real operator surfaces:

• App\Filament\Pages\EnvironmentDashboard
• App\Filament\Resources\ProviderConnectionResource
• App\Filament\Pages\EnvironmentRequiredPermissions
• App\Filament\Pages\Reviews\CustomerReviewWorkspace
• App\Filament\Resources\EnvironmentReviewResource\Pages\ViewEnvironmentReview
• App\Filament\Pages\Monitoring\FindingExceptionsQueue
• App\Filament\Resources\FindingExceptionResource\Pages\ViewFindingException
• App\Filament\Pages\Governance\GovernanceInbox
• App\Filament\Pages\Monitoring\EvidenceOverview
• App\Filament\Resources\EvidenceSnapshotResource\Pages\ViewEvidenceSnapshot
• App\Filament\Resources\OperationRunResource

Repo-truth adjustments against the user draft:

• Specs 351-354 are commit-backed on platform-dev, but the close-out metadata is not perfectly uniform across their spec packages. Spec 355 must treat dependency verification as an explicit first-phase gate instead of assuming all neighboring packages are perfectly normalized.
• Spec 351 has checked implementation tasks and a commit (d4e4d2d1), but its spec header still says Draft and its browser-flow audit records residual P2 observations. Spec 355 may depend on the implemented runtime truth, but must not silently treat historical P2 notes as already closed.
• Spec 352 is the cleanest dependency signal: repo-truth and page-report artifacts both describe the dashboard guidance slice as implemented.
• Spec 353 marks itself Implemented (close-out audit pending) and has a commit (d2876af9), but some checklist language still reflects prep wording. Spec 355 should rely on runtime truth plus committed tests/screenshots, not on any single metadata field alone.
• Spec 354 has a commit (a9c54205), checked implementation tasks, screenshots, and an existing browser smoke test file, but the spec header still says Draft and the spec package does not yet contain a dedicated browser-flow audit report. Spec 355 must verify whether the specific named dependency concerns are actually closed before issuing a sellable-readiness verdict.
• Existing browser smoke assets already exist for Governance Inbox, review-output guidance, provider-readiness guidance, accepted-risk guidance, and dashboard guidance. Spec 355 should reuse that repo history as context, but the sellable-readiness claim must come from a fresh cross-surface matrix rather than from neighboring spec assertions alone.
• docs/ui-ux-enterprise-audit/route-inventory.md already covers most in-scope surfaces. Evidence Overview (UI-044) and workspace operation detail (UI-017) still lack the same durable page-report depth as other strategic surfaces, so Spec 355 should use its own artifacts first and only expand the audit registry if a minimal P0/P1 fix materially changes those surfaces.

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

• Problem: TenantPilot now has several productized operator flows, but they were implemented across separate specs. The platform can still feel fragmented if the first blocker, next action, scope boundary, customer-safe boundary, and proof path do not line up across dashboard, provider, review, risk, evidence, governance, and operations surfaces.
• Today's failure: An MSP operator can still land in a troubleshooting maze where one page says "provider blocked", another says "review blocked", a detail page promotes the wrong CTA, accepted-risk wording drifts from review wording, or proof links and environment scope feel disconnected.
• User-visible improvement: A sellable smoke matrix proves whether the current platform feels like one governed MSP operating system: one dominant next action, correct scope continuity, conservative customer-safe boundaries, and coherent evidence/proof paths across the most important workflows.
• Smallest enterprise-capable version: Verify the existing surfaces end-to-end in a browser, capture screenshots, classify failures, and allow only direct P0/P1 fixes on the owning surfaces when absolutely necessary to make the platform coherent enough for operator demo/sellable-readiness use.
• Explicit non-goals: No customer portal, no PDF/HTML renderer, no AI guidance, no PSA/ITSM handoff, no new provider execution logic, no new resolution-adapter rollout, no dashboard rewrite, no Governance Inbox rewrite, no EvidenceSnapshot generation rewrite, no new database table, and no broad localization initiative.
• Permanent complexity imported: One spec-local smoke matrix, one readiness report, optional blocked-fixture notes, screenshots, and at most targeted regression tests for direct P0/P1 fixes. No new persisted product truth, no new enum family, no new framework, and no new workflow engine are intended.
• Why now: Specs 351-354 created a strong operator-guidance foundation, but the next sellability question is cross-surface coherence, not another isolated feature. This is the bounded gate before broader follow-up lanes such as renderers, customer portal contracts, or private AI assistance.
• Why not local: A page-local review on only dashboard, only provider readiness, or only accepted risk would miss the actual productization risk, which is cross-surface contradiction and broken continuity. The smallest honest slice is one integrated browser matrix across the existing owner surfaces.
• Approval class: Core Enterprise.
• Red flags triggered: Strategic operator surfaces, cross-surface workflow assertions, customer-safe boundary verification, and browser-heavy proof. Defense: the slice is verification-first, forbids broad runtime expansion, reuses existing product truth, and allows only minimal P0/P1 fixes.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 1 | Gesamt: 10/12
• Decision: approve with strict dependency-gate and no-new-surface guardrails.

Candidate Source And Completed-Spec Guardrail

• Candidate source:
  • direct user-provided Spec 355 draft
  • immediate follow-through over Specs 351-354
  • existing UI audit registry, route inventory, and browser smoke coverage across the affected operator surfaces
• Completed-spec guardrail result:
  • no specs/355-* package existed before this preparation run
  • Specs 351-354 are adjacent historical/runtime context only and must not be rewritten back into preparation-only wording
  • no completed task markers, screenshots, or historical findings are being removed from any earlier spec package
• Close alternatives deferred:
  • Spec 356 - Review Pack PDF/HTML Renderer v1
  • Spec 357 - Customer Portal Boundary Contract
  • Spec 358 - Private AI Resolution Suggestion Foundation
  • Spec 359 - Localization v1
  • Spec 360 - Portfolio / Cross-Tenant Action Readiness
• Smallest viable implementation slice: browser-verify the current productized operator surfaces, record a defensible pass/fail/blocked matrix, and only patch direct P0/P1 issues on the owning surfaces when the issue is clearly in scope and cheaply provable.

Spec Scope Fields (mandatory)

• Scope: workspace-wide hubs plus environment-bound owner surfaces, verified as one integrated operator flow.
• Primary Routes:
  • /admin/workspaces/{workspace}/environments/{environment}
  • /admin/provider-connections
  • /admin/workspaces/{workspace}/environments/{environment}/required-permissions
  • /admin/reviews/workspace
  • /admin/workspaces/{workspace}/environments/{environment}/environment-reviews/{record}
  • /admin/finding-exceptions/queue
  • /admin/workspaces/{workspace}/environments/{environment}/finding-exceptions/{record}
  • /admin/governance/inbox
  • /admin/evidence/overview
  • /admin/workspaces/{workspace}/operations
  • /admin/workspaces/{workspace}/operations/{run}
• Data Ownership:
  • existing dashboard, provider, review, accepted-risk, evidence, and OperationRun truth remain authoritative
  • smoke matrix, readiness report, blocked-fixture notes, and screenshots are spec-package artifacts only
  • no new database persistence is introduced
• RBAC:
  • existing workspace membership, environment entitlement, and capability checks remain authoritative
  • no new authorization plane or capability family is introduced
  • any minimal fix must preserve 404 for out-of-scope access and current capability-enforced mutation behavior

For mixed workspace-hub and environment-owner verification:

• Default filter behavior when environment-context is active: workspace hubs may use explicit environment_id filters where already repo-real, but they must not depend on hidden shell/session scope or stale tenant query behavior.
• Explicit entitlement checks preventing cross-tenant leakage: all deep links and proof routes must continue to resolve through the current workspace membership plus entitled environment scope only.

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

• No UI surface impact
• Existing page changed
• 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:
  • Environment Dashboard top guidance and CTA continuity
  • Provider Connections and Required Permissions
  • Customer Review Workspace and Environment Review detail
  • Finding Exceptions Queue and Exception Detail
  • Governance Inbox
  • Evidence Overview and evidence-basis drill-through
  • Operations hub / operation proof detail
• Current or new page archetype:
  • existing strategic workspace or environment operator surfaces only
  • no new page archetype is introduced
• Design depth:
  • Environment Dashboard, Provider Connections, Governance Inbox, Customer Review Workspace, Evidence Overview, and Operations are Strategic Surfaces
  • Environment Review detail, Exception Detail, and Required Permissions remain existing detail/domain surfaces with high productization sensitivity
• Repo-truth level: repo-verified runtime surfaces
• Existing pattern reused:
  • Specs 351-354 operator-guidance patterns
  • current page reports for dashboard, provider connections, required permissions, customer review workspace, environment review detail, governance inbox, operations, finding exceptions queue, and exception detail
  • current route inventory for Evidence Overview and operation detail
• New pattern required: none in the product. The only new artifact pattern is the spec-local smoke matrix and readiness report.
• Screenshot required: yes, under specs/355-platform-sellable-smoke-matrix/artifacts/screenshots/
• Page audit required:
  • no broad UI audit rewrite by default
  • use existing page reports plus Spec 355 artifacts as the primary verification package
  • if a minimal P0/P1 fix materially changes Evidence Overview or operation detail, record the audit follow-up explicitly during close-out
• Customer-safe review required: yes, because review-output, evidence, accepted-risk, and operation-proof flows may otherwise overclaim customer-ready or shareable output
• Dangerous-action review required: yes; publish, approve/reject, renew/revoke, and other state-changing actions must remain confirmation- and authorization-safe even when the smoke matrix evaluates prominence or disabled state
• 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

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): dashboard signals, next-action guidance, status messaging, proof links, evidence/report viewers, governance queue routing, and customer-safe review messaging
• Systems touched:
  • App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder
  • App\Support\ResolutionGuidance\ResolutionCase
  • App\Support\ResolutionGuidance\ResolutionAction
  • App\Support\ReviewPacks\ReviewPackOutputResolutionGuidance
  • App\Services\Findings\FindingRiskGovernanceResolver
  • App\Support\GovernanceInbox\GovernanceInboxSectionBuilder
  • App\Support\OperationRunLinks
  • App\Support\OpsUx\OperationRunUrl
  • existing provider-readiness summary and required-permissions builders
• Existing pattern(s) to extend:
  • Specs 351-354 guidance hierarchy and owner-surface continuity
  • existing OperationRun proof-link helpers
  • current page-report and route-inventory productization registry
• Shared contract / presenter / builder / renderer to reuse:
  • ResolutionCase / ResolutionAction
  • GovernanceActionCatalog
  • EnvironmentDashboardSummaryBuilder
  • GovernanceInboxSectionBuilder
  • OperationRunUrl / OperationRunLinks
• Why the existing shared path is sufficient or insufficient: the repo already has the operator-guidance and proof-link paths needed for this gate. Spec 355 should verify and minimally align them, not invent a second integration framework.
• Allowed deviation and why: none inside product runtime. Spec-local matrix/report artifacts are allowed because the product itself has no current sellable-readiness artifact surface.
• Consistency impact: one dominant next action, conservative customer-safe claims, stable canonical nouns, consistent deep-link behavior, and diagnostics-secondary disclosure must stay aligned across all tested surfaces.
• Review focus: prevent duplicate local CTA rails, fake remediation actions, raw-first detail defaults, broken proof links, and cross-surface terminology drift.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: deep-link and proof continuity only
• Shared OperationRun UX contract/layer reused:
  • existing OperationRunUrl
  • existing OperationRunLinks
  • existing workspace operation hub and operation detail resource routes
• Delegated start/completion UX behaviors:
  • Open operation / View run link continuity
  • tenant/workspace-safe URL resolution
  • proof/deep-link behavior only
• Local surface-owned behavior that remains: deciding whether operation proof is the right secondary follow-up or whether it should remain tertiary diagnostics beneath a more important next action
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes, as verification-only mixed context
• Boundary classification: mixed
• Seams affected:
  • provider-owned readiness surfaces: Provider Connections, Required Permissions
  • platform-core operator surfaces: Environment Dashboard, Customer Review Workspace, Governance Inbox, Evidence Overview, accepted-risk owner surfaces, Operations
• Neutral platform terms preserved or introduced:
  • provider blocker
  • review output blocker
  • accepted risk
  • evidence basis
  • operation proof
  • customer-safe boundary
• Provider-specific semantics retained and why: Microsoft/provider-specific permission and consent wording remains only on the provider-owned surfaces where current repo truth already requires it.
• Why this does not deepen provider coupling accidentally: Spec 355 does not add new shared taxonomy, persistence, or provider abstraction. It only verifies the current provider-owned and platform-core seams behave coherently.
• Follow-up path: document-in-feature if the smoke matrix uncovers a provider/platform drift that is out of scope for a minimal direct fix

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Environment Dashboard top guidance and CTA continuity	yes	Native Filament dashboard plus shared guidance payload	dashboard signals, proof links, next-action guidance	page, header, URL	no	existing route only
Provider Connections / Required Permissions	yes	Native Filament resource + page	provider-readiness guidance, blocker routing	page, table/filter, detail	no	existing routes only
Customer Review Workspace / Environment Review detail	yes	Native Filament page + resource detail	review-output guidance, customer-safe disclosure, action hierarchy	page, detail, URL	no	existing routes only
Finding Exceptions Queue / Exception Detail	yes	Native Filament page + resource detail	accepted-risk guidance, governance continuity	page, detail, URL	no	existing routes only
Governance Inbox	yes	Native Filament page	cross-domain queue routing, next-action labels	page, URL	no	existing route only
Evidence Overview / Evidence basis drill-through	yes	Native Filament page + resource detail	evidence/proof disclosure, customer-safe boundary	page, detail, table/filter	no	current page-report depth is lighter than other strategic surfaces
Operations hub / operation proof	yes	Native Filament route + resource detail	proof links, monitoring detail, diagnostics hierarchy	page, detail, URL	no	current route-inventory coverage exists; close-out may need extra note

Decision-First Surface Role (mandatory)

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
Environment Dashboard	Primary Decision Surface	Decide what blocks the environment first	blocker, reason, impact, one next action	proof rails, diagnostics, secondary links	primary because it is the environment command surface	environment-first operating flow	avoids opening multiple admin pages before understanding the blocker
Provider Connections / Required Permissions	Primary Decision Surface	Resolve provider readiness blocker safely	blocker category, why it matters, one next action	matrix, verification detail, technical disclosure	primary when provider readiness is the top blocker	provider-owner flow	avoids badge/count interpretation work
Customer Review Workspace	Primary Decision Surface	Decide what is needed before customer-safe output	output readiness, limitation boundary, one next action	deeper review/evidence context	primary when review output is the top blocker	review-owner flow	avoids review-detail reconstruction
Environment Review detail	Secondary Context	Validate the selected review and perform source-owned actions	readiness state, limitations, source-owned action hierarchy	evidence, history, proof	secondary because the workspace owns the overview decision	review-owner detail flow	avoids duplicate equal-weight decision homes
Finding Exceptions Queue	Primary Decision Surface	Decide which accepted risk needs governance action now	risk state, why it matters, one next action	deeper evidence/history	primary because it owns accepted-risk triage	accepted-risk owner flow	avoids status-badge translation
Governance Inbox	Primary Decision Surface	Clear cross-domain governance follow-up	queue summary, why it matters, one next action	deeper owner-surface context after click	primary as the cross-domain workbench, but not the owner for every domain action	daily operator queue	avoids hunting across many hubs
Evidence Overview	Secondary Context	Decide whether evidence is sufficient to trust or share an output	readiness/proof summary, stale/missing evidence state	raw evidence rows and detail	secondary because evidence supports other owner surfaces	evidence/proof support flow	avoids raw-report-first reading
Operations hub / operation proof	Tertiary Evidence / Diagnostics	Verify truth of a referenced operation or follow-up	run status, outcome, environment/source linkage	full operation context and technical detail	tertiary because proof should not compete with the primary workflow CTA	proof-verification flow	keeps monitoring detail out of first-decision space unless needed

Audience-Aware Disclosure (mandatory)

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
Dashboard and provider/review/risk owner surfaces	operator-MSP, manager	blocker, impact, next action, scope	related proof, secondary links	raw payloads, technical diagnostics	yes	raw/support detail remains secondary	the blocker is stated once and not restated as a competing CTA rail
Customer Review Workspace and review detail	operator-MSP, customer-safe operator handoff	release/readiness state, customer-safe boundary, next action	evidence basis, accepted-risk summary	internal rationale, raw metadata, debug detail	yes	internal-only detail remains secondary	customer-ready claim is kept distinct from internal draft/proof detail
Governance Inbox	operator-MSP	queue summary, why it matters, one next step	lane-specific detail after inspection	raw/support data belongs on owner surfaces	yes	deep diagnostics stay off the first screen	inbox routes into owner surfaces rather than duplicating their truths
Evidence Overview	operator-MSP, support where authorized	missing/stale/ready evidence state and what it blocks	evidence source detail, row-level artifact state	raw payload detail, fingerprints, support-only data	yes, if blocked	raw/support detail remains secondary	evidence supports a blocker; it does not restate every owner-surface summary
Operations hub / operation proof	operator-MSP, support-platform	run status, outcome, environment/source association	full run context, summary counts, timestamps	raw support details and deep technical context	no new primary beyond proof verification	deep diagnostics remain tertiary	proof answers "did it happen?" without becoming the default action rail

UI/UX Surface Classification (mandatory)

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
Environment Dashboard	Dashboard / Workbench	Command surface	Open the dominant owner surface	page-level CTA	N/A	compact subordinate links	none in this spec	environment dashboard route	owner surface route	workspace + environment	Environment Dashboard	top blocker and next action	none
Provider Connections	List / Table / Bulk	Strategic integration list	Open required permissions, grant consent, or run verification	table inspect/open	existing	More / supporting links	existing grouped actions only	/admin/provider-connections	current record/detail routes	workspace + optional environment filter	Provider Connections	blocker category and next action	none
Required Permissions	Detail / Guidance	Guidance-first diagnostic detail	Review missing permission category or verification blocker	page-level sections	N/A	supporting diagnostic sections	none introduced	required-permissions route	N/A	workspace + environment	Required Permissions	blocker and why it matters	none
Customer Review Workspace	Dashboard / Workbench	Customer-safe operator hub	Create/open/refresh/publish only when repo-backed and safe	page-level CTA	existing list/detail entry points	supporting actions below dominant CTA	source-owned destructive actions stay secondary	/admin/reviews/workspace	review detail route	workspace + explicit environment filter	Customer Review Workspace	output readiness and next action	none
Environment Review Detail	Detail / Record	Review-owner detail	Validate or execute the source-owned action	existing detail/open model	existing	contextual detail only	existing header actions only	environment review list	current detail route	workspace + environment + record	Environment Review	readiness, limitations, primary owner action	none
Finding Exceptions Queue / Detail	Queue + Record Detail	Accepted-risk owner surfaces	Review accepted risk or execute source-owned lifecycle action	queue inspect/open then detail	existing	supporting context	existing approve/reject/renew/revoke placement	queue route	current detail route	workspace or environment + record	Accepted Risk / Exception	governance state and next action	none
Governance Inbox	Queue	Cross-domain operator queue	Open the owning surface for the active case	queue inspect/open	existing	secondary context only	none introduced	/admin/governance/inbox	owner surface route	workspace + optional environment filter	Governance Inbox	why this item matters and what to open	none
Evidence Overview / Operation proof	List / Detail	Evidence / diagnostics support	Inspect evidence or verify operation proof	current list/detail model	existing where available	diagnostics and technical detail remain secondary	none introduced	/admin/evidence/overview, /admin/workspaces/{workspace}/operations	current detail routes	workspace + optional environment filter	Evidence / Operation	readiness or run truth needed for trust	none

Operator Surface Contract (mandatory)

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
Environment Dashboard	MSP operator / manager	Decide what to do first in this environment	command surface	What blocks this environment first?	top blocker, impact, one next step	proof and secondary diagnostics	provider, review, governance, evidence, operations	navigation-only in this spec	open owner surface	none introduced
Provider readiness owner surfaces	MSP operator / manager	Resolve provider blocker safely	strategic list/detail	What provider readiness issue matters now?	blocker category, effect on TenantPilot, one next action	permission matrix, technical verification detail	consent, permission, verification freshness	existing source-owned provider actions only	grant consent, run verification, open permissions	existing provider actions remain guarded
Review owner surfaces	MSP operator / manager	Resolve blocked output or confirm ready output	workspace hub + detail	What is preventing customer-safe output?	readiness, limitations, one next action	deeper evidence and lifecycle detail	publication, output readiness, evidence completeness	existing review actions only	create/open/refresh/publish when safe	existing publish/refresh/create actions stay source-owned
Accepted-risk owner surfaces	MSP operator / manager	Review accepted-risk governance coverage	queue + detail	Which accepted risk needs action and why?	governance state, impact, one next action	history, deeper evidence, related context	expiry, freshness, governance support	existing exception actions only	review accepted risk	approve/reject/renew/revoke remain guarded
Governance Inbox	MSP operator / manager	Route cross-domain work to the right owner surface	queue	What governance item should I clear next?	queue summary, reason, one next step	full owner-surface detail after open	queue state, severity, follow-up need	navigation-only in this spec	open owner surface	none introduced
Evidence / Operations proof	MSP operator / support	Verify proof and trust boundaries	evidence/monitoring support	Is the referenced evidence or run trustworthy and in scope?	readiness/proof summary, environment/source association	raw detail, technical context, timestamps	evidence completeness, run status, run outcome	none	inspect evidence or run	none introduced

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no product persistence; spec artifacts only
• New abstraction?: no
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: the platform may still feel fragmented across already-productized flows even when each individual flow works in isolation.
• Existing structure is insufficient because: isolated specs and page-local tests do not prove the integrated sellable operator experience.
• Narrowest correct implementation: one browser smoke matrix, one readiness report, and only minimal direct P0/P1 fixes on current owner surfaces.
• Ownership cost: artifact upkeep, screenshots, and regression verification only.
• Alternative intentionally rejected: broad navigation or workflow redesign, new portal, or new guidance engine.
• Release truth: current-release truth.

Compatibility posture

This feature assumes the repo's current pre-production posture.

Backward compatibility, migration shims, data-shape aliases, and legacy fixtures are out of scope unless a minimal direct fix explicitly proves they are needed, which is not expected for this verification gate.

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

• Livewire version contract: unchanged; current repo truth remains Livewire v4.x.
• Filament panel/provider registration: unchanged; apps/platform/bootstrap/providers.php remains authoritative and is not part of this slice.
• Global search: unchanged; no resource is made globally searchable by this spec.
• Test purpose / classification:
  • Browser for the integrated sellable smoke matrix
  • Feature/Livewire and/or Unit only if a direct P0/P1 fix needs targeted proof
• Validation lane(s): browser + confidence + fast-feedback
• Why this lane mix is the narrowest sufficient proof: the primary question is cross-surface operator trust and workflow continuity. Browser verification must lead; code-level tests are only needed to guard a direct in-scope fix.
• New or expanded test families: none by default; one bounded Spec355 browser smoke or targeted regression additions only if needed
• Fixture / helper cost impact: may reuse existing smoke-login and local/testing fixture commands; no new persisted product fixture truth is planned
• Heavy-family visibility / justification: browser coverage is explicit because this is a sellable-readiness gate over strategic operator surfaces
• Special surface test profile:
  • monitoring-state-page for Operations proof
  • shared-detail-family for review and exception detail
  • standard-native-filament elsewhere
• Reviewer handoff: reviewers must confirm that blocked flows are not misclassified as pass, that dependency caveats are documented, and that any fix stayed direct and owner-surface-local.
• Budget / baseline / trend impact: none expected beyond one bounded browser verification/reporting slice
• Escalation needed: document-in-feature if dependency close-out or fixture blockers remain; follow-up-spec only if repeated structural drift appears
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec351
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec352
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec353
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec354
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=CustomerReviewWorkspace
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentDashboard
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProviderConnection
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=FindingException
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ResolutionGuidance
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

Functional Requirements

• FR-355-001: Spec 355 must produce artifacts/platform-sellable-smoke-matrix.md with the required matrix columns and one row per required smoke flow.
• FR-355-002: Spec 355 must verify at least these flows when fixture truth exists: Environment Dashboard -> provider blocker, Environment Dashboard -> review-output blocker, Customer Review Workspace resolve loop, Environment Review detail in customer-workspace context, Provider Connections / Required Permissions, accepted-risk owner surfaces, Governance Inbox, Evidence Overview / evidence basis, operation proof, and calm no-urgent-action state.
• FR-355-003: Each tested surface must answer, within one first-screen decision view, what the state is, why it matters, and what the next action is.
• FR-355-004: Each tested flow must verify one dominant primary action and no competing duplicate CTA rails.
• FR-355-005: Each tested flow must verify workspace/environment/source-record scope continuity and document any stale query or hidden-context dependency.
• FR-355-006: Each tested flow must verify customer-safe boundaries and explicitly fail if blocked/internal/limited output is shown as customer-safe or shareable.
• FR-355-007: Each tested flow must record browser-visible errors, console errors, and network/server errors when present.
• FR-355-008: Required screenshots must be saved under artifacts/screenshots/ or marked blocked with a concrete reason in the matrix.
• FR-355-009: The readiness report must classify the platform as demo-ready, near-demo-ready, not demo-ready, sellable foundation-ready, or blocked.
• FR-355-010: Blocked flows must remain BLOCKED and must not be re-labeled as pass because the operator guessed what the page should have done.
• FR-355-011: Only verified P0/P1 issues may be fixed in-spec, and only when the fix is direct, narrow, and covered by targeted proof.
• FR-355-012: If a direct P0/P1 fix is applied, the affected flow must be re-run and the matrix/report must reflect the post-fix result.
• FR-355-013: The final close-out for Spec 355 must state clearly whether full-suite validation was or was not run.

Non-Functional Requirements

• NFR-355-001: Verification-first. The spec must prefer browser evidence and artifact honesty over optimistic product claims.
• NFR-355-002: No new runtime architecture, persistence, or workflow engine may be introduced.
• NFR-355-003: Existing RBAC, audit, confirmation, and OperationRun ownership must remain authoritative.
• NFR-355-004: No live provider or Graph call may be introduced during render as part of any minimal smoke-fix.
• NFR-355-005: The smoke package must stay reviewable and bounded: one spec directory, one matrix, one readiness report, targeted screenshots, and optional blocked-fixture notes only.
• NFR-355-006: The readiness verdict must remain conservative whenever dependencies or fixtures are incomplete.
• NFR-355-007: No claim of sellable readiness may be made without browser-backed evidence stored in the spec package.

UX Requirements

• The first visible state on each tested surface must be decision-first, not diagnostics-first.
• Exactly one action may be visually primary per tested case.
• Raw diagnostics, matrices, JSON-like detail, and support-only context must remain secondary or collapsed by default.
• Calm/no-urgent-action states must not read as empty or broken.
• Navigation continuity must feel intentional: the operator should not wonder why the CTA landed on a different story than the source page suggested.

RBAC / Security Requirements

• Existing workspace membership and environment entitlement remain authoritative and must be smoke-verified where relevant.
• Customer-safe output must not overclaim when evidence is incomplete, publication is blocked, accepted risk is expired/incomplete, or the export is limited/internal-only.
• Dangerous actions must keep current confirmation and authorization posture even if Spec 355 changes their prominence, disabled state, or label.
• The smoke matrix must classify wrong-scope, wrong-workspace, or unauthorized-link exposure as P0.

Auditability / Observability Requirements

• Existing OperationRun, audit-log, and verification ownership remain authoritative.
• The smoke matrix and readiness report must explicitly state whether console, network, or server errors were observed.
• Any minimal fix must preserve existing audit and proof-link behavior; Spec 355 is not allowed to create a second proof path.

Data / Truth-Source Requirements

• Existing surface truth remains derived from the current repo runtime only.
• Smoke artifacts under specs/355-platform-sellable-smoke-matrix/artifacts/ are the only new durable artifacts.
• No database table, snapshot, or persisted readiness classifier may be introduced.

Acceptance Criteria

• AC1: artifacts/platform-sellable-smoke-matrix.md exists and lists all required flows with result/status fields.
• AC2: Required screenshots exist or each missing screenshot is explicitly explained.
• AC3: No open P0/P1 remains at close unless the user explicitly chooses to defer it.
• AC4: Customer-safe boundary handling is browser-verified on the relevant review/evidence/risk flows.
• AC5: Workspace/environment continuity is browser-verified on the relevant dashboard/provider/review/governance/evidence/operations flows.
• AC6: Each key surface in the matrix shows one dominant next action or is explicitly failed for not doing so.
• AC7: No fake remediation or unsupported execution action is introduced as part of a smoke-driven fix.
• AC8: artifacts/platform-sellable-readiness-report.md exists and states a conservative readiness classification.
• AC9: The targeted regression commands named in this spec remain green after any direct in-scope fix.
• AC10: No migration, new package, new panel/provider change, new queue family, or new persisted truth is introduced by this spec.

Success Criteria

• An MSP operator can move from first blocker to owning surface to proof/follow-up without hitting a contradictory or diagnostics-first product path.
• The platform no longer requires hidden context knowledge to understand which page owns the next step.
• Customer-safe output claims stay conservative and truthful across the tested flows.
• The readiness report gives a defensible close/fix/defer recommendation without hand-waving over blocked fixtures or open critical findings.

User Scenarios & Testing (mandatory)

User Story 1 - Follow the dominant blocker path (Priority: P1)

As an MSP operator, I can open an environment, understand the highest-priority blocker, and land on the owning surface that shows the same story and one safe next step.

Independent Test: Browser verification of dashboard -> provider blocker and dashboard -> review-output blocker continuity with matching blocker language, preserved scope, and one dominant CTA.

User Story 2 - Resolve review and accepted-risk follow-up without CTA conflict (Priority: P1)

As an MSP operator, I can use the review-output and accepted-risk owner surfaces without competing action rails, fake buttons, or diagnostics overtaking the main next step.

Independent Test: Browser verification of Customer Review Workspace, Environment Review detail, Finding Exceptions Queue, and Exception Detail with one dominant next action and conservative secondary disclosure.

User Story 3 - Verify evidence and proof before trusting customer-safe output (Priority: P1)

As an MSP operator, I can verify whether evidence and operation proof support the current claim before I treat the output as ready or shareable.

Independent Test: Browser verification of Evidence Overview/evidence-basis links and operation proof links, plus explicit checks that blocked or limited outputs do not present themselves as customer-ready.

User Story 4 - See a calm no-urgent-action state and a defensible readiness verdict (Priority: P2)

As a product owner or demo operator, I can distinguish a calm ready state from a broken/empty page and get a final readiness classification that honestly reflects what was and was not proven.

Independent Test: Browser verification of at least one no-urgent-action state when fixture truth exists, plus a completed readiness report that counts pass/fail/blocked flows conservatively.

Risks

• Risk 1 - Dependency ambiguity: neighboring spec packages do not all carry identical close-out metadata. Mitigation: explicit dependency gate in Phase 1 and conservative blocked/readiness language.
• Risk 2 - Fixture incompleteness: one or more target states may not exist in current local/demo data. Mitigation: inventory fixtures first, record blocked states explicitly, and avoid false pass claims.
• Risk 3 - Scope creep into redesign: productization pain across many surfaces can tempt a broad rewrite. Mitigation: allow only direct P0/P1 fixes on owner surfaces.
• Risk 4 - Customer-safe overclaim: a smoke flow may accidentally trust internal-only detail, stale evidence, or expired accepted risk. Mitigation: treat any such case as at least P1 and usually P0 when output safety is affected.
• Risk 5 - Browser-only proof drift: manual browser success without stored artifacts can become unreviewable. Mitigation: save screenshots and fill the matrix/report as the source of truth.

Follow-Up Candidates

• Spec 356 - Review Pack PDF/HTML Renderer v1
• Spec 357 - Customer Portal Boundary Contract
• Spec 358 - Private AI Resolution Suggestion Foundation
• Spec 359 - Localization v1
• Spec 360 - Portfolio / Cross-Tenant Action Readiness

Assumptions

• Existing dashboard/provider/review/risk/evidence/operations surfaces already contain enough repo-real behavior to make a meaningful integrated sellable-readiness call without inventing new flows.
• Existing smoke-login and local/testing fixture helpers are sufficient to exercise at least the core required flows, or blocked states can be documented honestly without widening scope.
• Any direct P0/P1 fix will be local to an existing owner surface and will not require new persistence or framework work.
• The user wants preparation artifacts only in this turn; no application implementation is performed as part of the prep.

Open Questions

No blocking preparation questions remain.

Implementation should still verify two runtime gates before declaring the platform ready:

• whether Spec 354's specifically named dependency concerns are demonstrably closed on the current repo truth
• whether all required smoke states can be exercised with current local/testing fixtures or whether some flows must remain BLOCKED