TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/spec.md

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
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

• Route/page/surface:
  • 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
  • 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 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