# Feature Specification: Spec 350 - Operator Resolution Guidance Framework v1

**Feature Branch**: `350-operator-resolution-guidance-framework-v1`  
**Created**: 2026-06-03  
**Status**: Draft  
**Type**: Platform productization / operator guidance / derived resolution contract / future AI-ready extension point  
**Runtime posture**: Reuse-first and bounded. This spec standardizes operator guidance over existing repo-backed truth. It does not introduce a workflow engine, ticket system, portal, AI execution path, or new persisted resolution state.  
**Input**: User-provided full Spec 350 draft + repo truth from Specs 161, 312, 338, 346, 347, 349 and current guidance-producing runtime paths.

## Dependencies And Repo-Truth Adjustments

This spec is a follow-up over already repo-real guidance foundations:

- Spec 161 - Operator Explanation Layer
- Spec 312 - Customer Review Workspace v1 Completion
- Spec 338 - Workspace / Environment Resource Scope Contract
- Spec 346 - Governance Inbox Final Operator Workflow
- Spec 347 - Review Pack Output Contract & Readiness Semantics
- Spec 349 - Customer Review Workspace Output Resolution Guidance

Repo-truth adjustment against the user draft:

- `App\Support\ReviewPacks\ReviewPackOutputResolutionGuidance` already exists and covers the review-pack/output path; Spec 350 must reuse it, not replace it.
- `App\Support\OpsUx\OperationUxPresenter`, `App\Support\Ui\OperatorExplanation\OperatorExplanationPattern`, and `App\Support\Ui\EnterpriseDetail\EnterpriseDetailSectionFactory::primaryNextStep()` already provide operator-guidance primitives.
- `GovernanceInbox`, `EnvironmentDashboardSummaryBuilder`, `ProviderConnectionSurfaceSummary`, and `EnvironmentRequiredPermissions` already contain repo-real next-step/readiness/guidance behavior.
- The problem is no longer "no guidance exists". The real gap is that cross-surface guidance does not share one traceable, scope-explicit, action-safe case contract.
- Spec 347 contains a speculative follow-up note naming "Spec 350" as a sellable smoke matrix, but no real `specs/350-*` package or branch existed before this prep. That speculative note is not a reserved number.

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

- **Problem**: Multiple strategic surfaces already expose repo-real blocker or readiness truth, but they still translate that truth into page-local guidance differently. Operators can get a reason on one page, a raw warning wall on another, a text-only next step on a third, and no traceable source/action contract across them.
- **Today's failure**: TenantPilot risks becoming diagnostics-heavy again whenever review output, evidence basis, provider readiness, or operation follow-up require the operator to infer the next safe step from inconsistent local copy and local link logic.
- **User-visible improvement**: A bounded shared `ResolutionCase` contract makes the product answer the same first-order questions consistently: what is wrong, why it matters, what the dominant next step is, and which source records prove the guidance.
- **Smallest enterprise-capable version**: Introduce one derived `ResolutionCase` / `ResolutionAction` contract over repo-real guidance producers, prove it first on Customer Review Workspace and Environment Review detail through the existing review-output path, and allow provider-readiness or operation-follow-up adoption only where the reuse cost stays bounded. Evidence-basis guidance remains embedded in the review-output path for v1 instead of becoming a standalone adapter.
- **Explicit non-goals**: No workflow engine, no ticketing, no portal, no AI execution, no new persistence, no broad dashboard rewrite, no Governance Inbox rebuild, no new provider framework, no PDF/HTML renderer, no new review lifecycle state machine, and no legal/signature semantics.
- **Permanent complexity imported**: One bounded support-layer contract, one required review-output adapter, up to two optional bounded adapters if they are actually consumed in-scope, focused unit/feature/browser tests, one reusable rendering path if needed, and new shared terminology around resolution cases and resolution actions. No new table, model, persisted enum, or queue family.
- **Why now**: Specs 346, 347, and 349 created the first clear set of real consumers. The codebase now has enough concrete guidance producers to justify a shared contract, and enough drift risk to make local copy-only fixes insufficient.
- **Why not local**: Local fixes would deepen existing drift between `ReviewPackOutputResolutionGuidance`, Governance Inbox next-action presentation, provider readiness guidance, and operation follow-up semantics. The same cross-surface problem would continue to reappear.
- **Approval class**: Core Enterprise.
- **Red flags triggered**: new meta-infrastructure, many touched surfaces, and foundation-style naming. Defense: the contract is justified by at least four real consumers, stays derived-only, and is explicitly forbidden from becoming a workflow engine or persisted taxonomy.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve with reuse-first and bounded-contract constraints.

## Candidate Source And Completed-Spec Guardrail

- **Candidate source**:
  - direct user-provided Spec 350 draft
  - roadmap alignment: customer-safe review consumption, decision-centered governance workflow, provider readiness productization, and environment/dashboard next-step clarity
- **Completed-spec guardrail result**:
  - no `specs/350-*` package existed before this prep
  - Specs 161, 312, 338, 346, 347, and 349 already carry prepared, validated, checked-off-task, screenshot, browser-smoke, or historical implementation signals and are treated as context only
  - this prep must not rewrite or normalize those completed or active historical artifacts
  - the speculative Spec-347 follow-up number is treated as non-binding repo commentary, not as a claimed package
- **Close alternatives deferred**:
  - sellable smoke matrix for governance/review/export flows
  - provider readiness deep productization as a standalone surface spec
  - customer portal boundary contract
  - private AI runtime consumer or AI suggestion delivery
- **Smallest viable implementation slice**: one traceable resolution-case contract, one bounded resolution-action contract, one required review-output adapter, one reusable rendering path if it clearly reduces duplication, and first visible integration on the review-output path before any broader cross-surface adoption.

## Spec Scope Fields *(mandatory)*

- **Scope**: review-output-first across workspace, environment, review, and review-pack surfaces, with provider-connection or operation follow-up surfaces included only when a concrete same-slice consumer can reuse the contract without broadening scope.
- **Primary Routes**:
  - `/admin/reviews/workspace`
  - existing Environment Review detail route(s)
  - `/admin/governance/inbox` for bounded follow-through only if reuse remains local and non-disruptive
  - existing Provider Connections and Required Permissions surfaces only if a bounded provider-readiness consumer is adopted
  - existing Environment Dashboard readiness/recommended-action surfaces only if a bounded optional consumer is adopted
  - existing OperationRun proof/detail destinations only as linked follow-up context
- **Data Ownership**:
  - `EnvironmentReview`, `ReviewPack`, `EvidenceSnapshot`, `ProviderConnection`, `OperationRun`, `Finding`, and `FindingException` remain the source-of-truth records
  - any `ResolutionCase` or `ResolutionAction` stays derived-only and request-scoped unless a later spec proves independent persistence is necessary
- **RBAC**:
  - workspace membership, managed-environment entitlement, and existing capability checks remain authoritative
  - executable actions must continue to route through existing policies, services, confirmation rules, audit behavior, and `OperationRun` flows where already required
  - cross-workspace or cross-environment access remains deny-as-not-found through the current scoped routes and policies

For canonical-view specs:

- **Default filter behavior when tenant-context is active**: workspace-wide surfaces keep visible local `environment_id` filtering or route-owned environment context only. No hidden shell/sidebar/topbar scope may be introduced.
- **Explicit entitlement checks preventing cross-tenant leakage**: each resolution case must carry explicit scope, and any linked source or action destination must continue to resolve through existing workspace/environment-scoped URLs and policies.

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

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

- [ ] No UI surface impact
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [x] Customer-facing surface changed
- [ ] 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**:
  - `CustomerReviewWorkspace`
  - Environment Review detail output-guidance summary (`UI-040`)
  - existing Governance Inbox next-recommended item when a bounded consumer is added
  - existing provider readiness / required-permissions guidance surfaces (`UI-072` / `UI-077`) when a bounded consumer is added
  - existing environment readiness/recommended-action cards when a bounded consumer is added
- **Current or new page archetype**: existing strategic workspace/customer-review surface plus existing strategic operator surfaces; no new route archetype
- **Design depth**: Strategic Surface for review workspace, governance inbox, provider connections, and environment dashboard; Domain Pattern Surface for review detail and required-permissions guidance
- **Repo-truth level**: repo-verified runtime surfaces with existing guidance islands; no conceptual-future-state page creation required
- **Existing pattern reused**:
  - `docs/ui-ux-enterprise-audit/page-reports/ui-006-customer-review-workspace.md`
  - `docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md`
  - `docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md`
  - `docs/ui-ux-enterprise-audit/route-inventory.md` entries `UI-040` and `UI-077`
  - existing target-experience briefs for customer review workspace, governance inbox, provider readiness, and environment dashboard
- **New pattern required**: one bounded review-output-first resolution-guidance contract plus a reusable card/list rendering path only if it removes real duplication; no new global UI framework or taxonomy
- **Screenshot required**: yes, under `specs/350-operator-resolution-guidance-framework-v1/artifacts/screenshots/`
- **Page audit required**: yes, update the relevant existing page reports for any surfaces actually touched during implementation. Because `UI-040` is currently unresolved in the registry, implementation must update `docs/ui-ux-enterprise-audit/unresolved-pages.md` unless it adds a dedicated review-detail page report.
- **Customer-safe review required**: yes, because review-output guidance is the first required visible consumer
- **Dangerous-action review required**: conditional only. V1 default bias is navigation, qualified download, or disclosure. If an existing source-owned executable action is surfaced, it must preserve its current confirmation, authorization, and audit behavior.
- **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 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)**: status messaging, next-action guidance, readiness cards, decision-first summaries, proof links, evidence/report viewers, customer-safe disclosure, and cross-surface resolution actions
- **Systems touched**:
  - `App\Support\ReviewPacks\ReviewPackOutputResolutionGuidance`
  - `App\Support\OpsUx\OperationUxPresenter`
  - `App\Support\Ui\OperatorExplanation\OperatorExplanationPattern`
  - `App\Support\Ui\EnterpriseDetail\EnterpriseDetailSectionFactory`
  - `App\Filament\Pages\Governance\GovernanceInbox`
  - `App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder`
  - `App\Support\Providers\TargetScope\ProviderConnectionSurfaceSummary`
  - `App\Filament\Pages\EnvironmentRequiredPermissions`
- **Existing pattern(s) to extend**: existing output-guidance, operator-explanation, primary-next-step, next-recommended-item, readiness-card, and required-permissions guidance paths
- **Shared contract / presenter / builder / renderer to reuse**:
  - `ReviewPackOutputResolutionGuidance`
  - `OperationUxPresenter::surfaceGuidance()` and related detail helpers
  - `OperatorExplanationPattern`
  - `EnterpriseDetailSectionFactory::primaryNextStep()`
  - current scoped URL helpers and `OperationRunLinks`
- **Why the existing shared path is sufficient or insufficient**: the repo already has strong local guidance producers, but they do not share one explicit, scope-carrying, source-traceable, action-safe case envelope that later consumers can reuse without copying logic
- **Allowed deviation and why**: one bounded `ResolutionCase` / `ResolutionAction` normalizer plus adapter layer is allowed if it wraps current truth and avoids creating a third independent explanation framework
- **Consistency impact**: the same issue class should expose the same reading direction: title, reason, impact, one dominant action, secondary actions, and source references
- **Review focus**: prevent a parallel workflow engine, prevent new persisted state, prevent a second generic explanation taxonomy, and verify reuse over the existing guidance producers instead of replacement-by-rewrite

## 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, but only by standardizing follow-up guidance and deep-link metadata over existing run detail/proof surfaces
- **Shared OperationRun UX contract/layer reused**:
  - `OperationRunLinks`
  - `OperationUxPresenter`
  - existing run-detail and proof-link destinations
- **Delegated start/completion UX behaviors**: unchanged; queueing, dedupe, toasts, and terminal notification behavior remain owned by existing OperationRun UX flows
- **Local surface-owned behavior that remains**: dominant resolution ranking, action selection, and grouped supporting details per resolution case
- **Queued DB-notification policy**: unchanged
- **Terminal notification path**: unchanged
- **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`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: mixed
- **Seams affected**: provider readiness, required-permissions guidance, verification follow-up, and shared operator vocabulary for cross-surface resolution cases
- **Neutral platform terms preserved or introduced**: provider, workspace, environment, evidence basis, operation, resolution case, resolution action, source reference
- **Provider-specific semantics retained and why**: provider-owned adapters may still reference provider-specific permission or verification details where the underlying surface is already provider-owned and repo-real
- **Why this does not deepen provider coupling accidentally**: the framework core names neutral case/action fields and keeps provider-specific labels inside the provider adapter, provider surface, and existing verification/required-permissions truth
- **Follow-up path**: deeper provider readiness productization remains a follow-up slice, not part of the core contract

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

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Customer Review Workspace output guidance | yes | Native Filament page + existing Blade composition | review/output guidance, customer-safe disclosure | page, detail, URL-query | no | first required visible consumer; preserve current findings and accepted-risk follow-up overrides |
| Environment Review detail output-guidance summary | yes | Native Filament resource/detail | review/output guidance, qualified download | detail | no | paired with workspace handoff; preserve customer-workspace detail-mode CTA suppression |
| Governance Inbox next-recommended item | possible | Native Filament page | next recommended action, queue-clearing guidance | page | yes | only if reuse remains bounded |
| Provider readiness / required permissions guidance | possible | Native Filament resource/page | readiness, permission gap, safe next action | page, detail | yes | only if current truth can map cleanly |
| Environment dashboard readiness cards | possible | Existing builder + dashboard view | readiness, blocker, next action | page | yes | only if no new dashboard taxonomy is needed |

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

| 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 |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace | Primary Decision Surface | Decide whether the current output is customer-safe, limited, or blocked | title, reason, impact, one primary action | evidence basis, technical details, operation proof | primary because this is the first review-output handoff surface | review consumption and handoff | removes warning-wall interpretation |
| Environment Review detail | Secondary Context | Understand why the current review cannot be repaired directly or can be shared | review status, output readiness, publication/sharing state, next action | sections, truth details, proof links | secondary because it deepens the chosen review | detail follow-up | avoids duplicate status dialects |
| Governance Inbox | Primary Decision Surface when consumed | Decide which governance item to clear next | lane, reason, impact, dominant action | source detail, diagnostics, decision history | primary for internal queue work | queue-clearing | keeps source-family detail secondary |
| Provider readiness | Primary Decision Surface when consumed | Decide whether readiness is blocked and what safe step resolves it | readiness posture, gap, one action | verification detail, permission matrix, audit trace | primary for integration readiness | provider recovery | reduces raw integration-detail scanning |
| Environment dashboard | Secondary Context when consumed | Decide which blocked domain deserves the next drilldown | blocker, impact, one next action | backup, recovery, operations, provider detail | secondary because it routes into domain owners | environment command surface | avoids equal-weight dashboard signals |

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

| 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 |
|---|---|---|---|---|---|---|---|
| Review-output surfaces | customer-safe, operator-MSP | title, reason, impact, action, boundary | technical details, evidence basis, operation proof | raw payloads, internal diagnostics | one explicit next step | raw/support detail hidden or secondary | workspace states the issue once; detail adds proof |
| Internal operator surfaces | operator-MSP, manager, support | title, reason, impact, dominant action, scope | source refs, verification detail, run detail | raw provider/runtime payloads | one explicit next step | raw/support detail stays secondary or capability-gated | top card/lane explains first; later sections add evidence |

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

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Customer Review Workspace | Utility / Workspace Decision | Customer-safe workspace hub | create/open draft, refresh inputs, open evidence, or download pack depending on case | explicit CTA in decision card | forbidden | grouped secondary links/disclosure | none in spec core | `/admin/reviews/workspace` | existing Environment Review and Review Pack detail/download | workspace + visible environment filter | Review output | issue, reason, impact, primary action | none |
| Environment Review detail | Detail / Artifact + Review Context | Existing review detail | inspect current review or follow next action | existing detail view | current repo-real behavior only | secondary links/disclosures | existing lifecycle actions stay separate | existing review collection route | existing review detail route | workspace/environment + customer-workspace context | Environment review | issue, status dimensions, primary action | none |
| Governance Inbox | Queue / Decision Surface | Existing governance queue | review the top open item | existing lane card / top recommendation | existing repo-real behavior | source detail / more context | existing mutations remain source-owned | `/admin/governance/inbox` | existing finding/exception/decision/review destinations | workspace + visible environment filter | Governance item | reason, impact, primary action | only if consumed |
| Provider readiness | Readiness / Configuration Surface | Existing provider list/detail or required-permissions page | open required permissions, rerun verification, or review readiness | explicit CTA in summary card | existing resource behavior | grouped links/disclosure | existing high-impact actions stay separately governed | existing provider routes | existing provider detail/required-permissions routes | workspace/environment | Provider readiness | gap, impact, primary action | only if consumed |

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

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Resolution-guided review output | Customer-safe reader / MSP operator | Understand whether output is trustworthy and what next step is allowed | review workspace + review detail | What is wrong, why, and what do I do next? | title, reason, impact, one action, explicit scope | technical details, source refs, proof links | review status, output readiness, sharing boundary | existing review or evidence flows only | open review, open evidence, qualified download, existing follow-up override targets | existing publish/archive remain separate |
| Resolution-guided internal follow-up | Operator / manager | Review readiness, provider, or operation blockers without diagnostics-first scanning | queue/dashboard/readiness summary when an optional consumer is explicitly adopted | What blocks progress now, and which safe path should I take? | title, reason, impact, one action, explicit scope | run detail, verification detail, source detail | readiness, evidence, operation follow-up | existing domain actions only | open required permissions, open operation proof, open review context | existing high-impact actions remain source-owned |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes, one bounded derived resolution-case/action contract plus thin adapters
- **New enum/state/reason family?**: not by default. If presentation-only vocabularies are still needed after implementation review, they must stay non-persisted and narrower than the current source truth.
- **New cross-domain UI framework/taxonomy?**: no. This spec allows one bounded case/action envelope over already-existing guidance producers, not a new UI framework.
- **Current operator problem**: different strategic surfaces already know something is blocked, risky, stale, or follow-up-required, but they do not all tell the operator the next safe action in the same traceable way
- **Existing structure is insufficient because**: current guidance producers are local and incompatible in shape; cross-surface reuse currently means copy/paste mapping or divergent local heuristics
- **Narrowest correct implementation**: add a thin derived contract and bounded adapters that wrap existing truth and existing actions instead of replacing existing explanation/guidance systems
- **Ownership cost**: new support-layer vocabulary, adapter tests, cross-surface review burden, and care to avoid a parallel framework
- **Alternative intentionally rejected**: local copy-only fixes, a new workflow engine, a fully generic issue taxonomy, new persistence, and a broad provider-neutral execution framework
- **Release truth**: current-release productization and trust hardening over already-existing guidance paths; AI remains documentation-only

### 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)*

- **Test purpose / classification**: Unit + Feature + Browser
- **Validation lane(s)**: fast-feedback + confidence + browser
- **Why this classification and these lanes are sufficient**: the central risk is deterministic mapping and first-screen operator behavior, not DB engine semantics or heavy suite discovery
- **New or expanded test families**: one small `ResolutionGuidance` unit family plus focused integrations for review/workspace/detail consumers
- **Fixture / helper cost impact**: reuse existing review, evidence, provider, and operation fixtures where possible; do not widen default helpers
- **Heavy-family visibility / justification**: browser coverage is explicit because this spec changes first-screen decision hierarchy on strategic surfaces
- **Special surface test profile**: `global-context-shell` + `shared-detail-family` + bounded strategic surface smoke
- **Standard-native relief or required special coverage**: special coverage required because this feature changes one-primary-action, grouped disclosure, and action-safe next-step behavior across shared surfaces
- **Reviewer handoff**: verify the new contract stays derived-only, that each adapter reuses existing truth, and that validation commands stay focused
- **Budget / baseline / trend impact**: low to moderate; one new focused browser smoke, a small unit family, and several focused feature tests
- **Escalation needed**: document-in-feature if a proposed consumer needs a broader dashboard or provider rewrite
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **Planned validation commands**:
  - focused Spec 350 unit/feature tests for contract + adapters
  - focused review/workspace/detail integration tests
  - one bounded browser smoke
  - filtered regressions for Specs 347/349, plus Spec 346 only if a Governance Inbox consumer or shared inbox-facing helper is adopted
  - `pint --dirty`
  - `git diff --check`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - See one safe next step for blocked review output (Priority: P1)

An operator opening Customer Review Workspace or review detail must understand immediately whether the current review output is customer-safe, limited, or blocked, and which repo-real next step is safest.

**Why this priority**: This is the clearest current sellability and trust surface, and it already has real guidance logic from Specs 347 and 349.

**Independent Test**: Seed published-blocked, draft-blocked, and customer-safe-ready review states and confirm the surface shows one dominant action with scope-safe secondary proof.

**Acceptance Scenarios**:

1. **Given** a published review whose evidence basis is incomplete, **When** the operator opens the workspace, **Then** the page explains that the output is not customer-ready and recommends the correct next repo-real step instead of a warning wall.
2. **Given** a current draft review that can still be refreshed, **When** the operator opens the same surface, **Then** the page recommends refreshing review inputs or opening the draft instead of claiming the published review can be fixed directly.

---

### User Story 2 - Reuse the same issue/action structure across bounded additional consumers (Priority: P2)

An operator working across review output and any additional bounded provider-readiness or operation-follow-up consumer needs the same reading direction: issue, reason, impact, one action, supporting proof.

**Why this priority**: The product already has multiple real guidance islands; consistency is the current productization gap, not raw missing data.

**Independent Test**: Confirm the required review-output contract shape is deterministic, and if an additional provider-readiness or operation-follow-up adapter is adopted in-scope, confirm it emits the same contract shape with explicit scope, source refs, and one primary action.

**Acceptance Scenarios**:

1. **Given** a provider permission gap or an operation follow-up-required run is adopted as an in-scope consumer, **When** the adapter builds a resolution case, **Then** the case contains exactly one primary action, explicit scope, and source references.
2. **Given** a consumer surface lacks the safety fields required to expose an existing executable path safely, **When** the case is rendered, **Then** the primary action degrades to navigation, qualified download, disclosure, or `none` instead of exposing a fake fix button.

---

### User Story 3 - Keep execution safe and AI deferred (Priority: P3)

A workspace owner or reviewer needs resolution actions to remain capability-aware, confirmation-aware, auditable, and clearly human-approved when they reuse existing executable flows, with any future AI connection documented but not active.

**Why this priority**: A shared guidance contract becomes dangerous if it implies executable authority without preserving the existing safe-execution rules.

**Independent Test**: Review mutating and non-mutating action cases, confirm safety metadata is present or the action degrades, and confirm no AI call or AI-visible runtime field is introduced.

**Acceptance Scenarios**:

1. **Given** a case whose primary action reuses an existing source-owned executable path, **When** the contract is built, **Then** the action includes capability, confirmation, audit, and `OperationRun` hints where applicable, or becomes non-executable.
2. **Given** the future AI extension document, **When** a reviewer inspects the package, **Then** they can see the reserved extension fields and mandatory gates without any active AI execution path in scope.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-350-001**: The system MUST define a shared derived `ResolutionCase` contract for operator guidance and a shared derived `ResolutionAction` contract for the dominant next step.
- **FR-350-002**: The contract MUST be scope-explicit and traceable to repo-backed source records; no hidden session or shell scope is allowed.
- **FR-350-003**: Each resolution case MUST expose exactly one primary resolution action.
- **FR-350-004**: V1 primary actions MUST default to navigation, qualified download, disclosure, or `none` unless the action is reusing an existing source-owned executable path that already has a repo-real safety envelope.
- **FR-350-005**: If a primary action reuses an existing source-owned executable path, it MUST carry the safety metadata required to preserve existing capability, confirmation, audit, and `OperationRun` behavior.
- **FR-350-006**: If full safe-execution metadata cannot be provided, the action MUST degrade to navigation, qualified download, disclosure, or `none` instead of rendering a fake fix path.
- **FR-350-007**: The required v1 adapter set MUST cover review-pack output guidance, including evidence-basis gaps already surfaced through `ReviewPackOutputResolutionGuidance`; v1 MUST NOT introduce a standalone evidence-basis adapter.
- **FR-350-008**: Customer Review Workspace and Environment Review detail MUST be the first required visible consumers of the shared contract, while preserving current `findings_follow_up_required`, `accepted_risk_follow_up_required`, and customer-workspace detail-mode CTA-suppression behavior.
- **FR-350-009**: If operation follow-up is adopted as an in-scope consumer, the adapter MUST reuse existing `OperationUxPresenter`, `OperatorExplanationPattern`, and existing proof-link destinations where applicable.
- **FR-350-010**: If provider readiness is adopted as an in-scope consumer, the adapter MUST reuse existing required-permissions, verification, and provider-surface truth instead of inventing a new provider readiness engine.
- **FR-350-011**: Governance Inbox, provider readiness surfaces, required-permissions surfaces, and environment readiness cards MAY consume the same contract only when the reuse remains bounded and does not require a broader surface redesign.
- **FR-350-012**: Technical details, source references, and supporting evidence MUST remain secondary to issue, reason, impact, and primary action.
- **FR-350-013**: The framework MUST not introduce persistence unless a later spec proves independent lifecycle truth is necessary.
- **FR-350-014**: The framework MUST not introduce a workflow engine, approval engine, queue family, or mandatory standalone evidence-guidance subsystem.
- **FR-350-015**: The framework MUST document a future AI/HITL extension point, but MUST NOT render or execute AI suggestions in v1.

### Non-Functional Requirements

- **NFR-350-001**: Default-visible guidance must be calm, enterprise-safe, and decision-first: one issue, one reason, one impact, one primary action.
- **NFR-350-002**: The core contract must remain provider-neutral even when a provider-owned adapter exposes provider-specific detail.
- **NFR-350-003**: Guidance derivation must stay bounded to the already-loaded or already-scoped records of the current surface wherever possible.
- **NFR-350-004**: The contract must be testable as deterministic data without requiring browser-only proof for every adapter.
- **NFR-350-005**: Existing workspace/environment isolation, signed-download safety, and authorization boundaries must remain unchanged.

## Risks

- **Risk 1 - A third parallel guidance framework appears**: Mitigation: require reuse of existing guidance producers and forbid replacement-by-rewrite.
- **Risk 2 - The spec becomes too abstract**: Mitigation: keep the required proof on already-productized review surfaces, keep evidence-basis guidance inside the review-output adapter, and defer any broader provider/dashboard/gov adoption unless it stays bounded.
- **Risk 3 - Provider surfaces force a broader rewrite**: Mitigation: make deeper provider readiness adoption optional and bounded inside this spec; escalate broader gaps as follow-up work.
- **Risk 4 - Suggested actions imply authority the runtime does not actually have**: Mitigation: degrade to navigation/disclosure when safety metadata is incomplete.

## Deferred Follow-Up Candidates

- Sellable smoke matrix for governance, review, evidence, and export flows
- Provider readiness deeper productization
- Customer portal output-boundary contract
- Private AI resolution suggestion runtime consumer