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
- [x] Existing page changed
- [x] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [x] Customer-facing surface changed
- [x] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] 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`
  - [x] `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`
  - [x] `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`