TenantAtlas/specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/spec.md

Feature Specification: Spec 354 - Finding Exceptions / Accepted Risk Resolution Guidance v1

Feature Branch: 354-finding-exceptions-accepted-risk-resolution-guidance-v1
Created: 2026-06-05
Status: Draft
Type: Platform productization / accepted-risk operator guidance / finding-exception workflow consolidation
Runtime posture: Bounded operator-guidance follow-up over existing Finding Exception, Governance Inbox, Customer Review Workspace, Environment Review, Review Pack, and Resolution Guidance truth. No new GRC engine, no new persistence, no customer portal, no workflow replatform, and no provider-architecture change.
Input: Direct user-provided Spec 354 draft (attachment) + repo truth from Spec 353 follow-up notes, docs/ui-ux-enterprise-audit/page-reports/ui-012-finding-exceptions-queue.md, and current finding-exception runtime surfaces.

Dependencies And Repo-Truth Adjustments

This spec is a bounded follow-up over already repo-real accepted-risk, review, and operator-guidance foundations:

• Spec 343 - Customer Review Attestation / Accepted Risk Lifecycle
• Spec 346 - Governance Inbox Final Operator Workflow
• Spec 349 - Customer Review Workspace Output Resolution Guidance
• Spec 350 - Operator Resolution Guidance Framework v1
• Spec 351 - Review Output Resolve Actions v1
• Spec 352 - Environment Dashboard Operator Guidance Consolidation
• Spec 353 - Provider Connections Resolution Guidance v1

Repo-truth adjustments against the user draft:

• App\Filament\Pages\Monitoring\FindingExceptionsQueue already exists as the workspace-wide accepted-risk decision surface and already owns selected-record review state, explicit environment_id filtering, and approve/reject actions.
• App\Filament\Resources\FindingExceptionResource\Pages\ViewFindingException already exists as the environment-bound accepted-risk detail surface and already exposes renew_exception and revoke_exception with confirmation, authorization, and notification behavior.
• App\Services\Findings\FindingRiskGovernanceResolver already derives accepted-risk workflow family, warning text, narrative, and next-action guidance from existing Finding plus FindingException truth; Spec 354 must reuse or adapt that truth instead of inventing a second accepted-risk state machine.
• App\Support\GovernanceInbox\GovernanceInboxSectionBuilder already emits accepted-risk lane copy and already deep-links the operator to FindingExceptionsQueue with the action label Review accepted risk.
• App\Filament\Resources\FindingExceptionResource already disables global search. Spec 354 must preserve that state; no new global-search scope is needed.
• Customer-safe accepted-risk wording already exists in review-output surfaces through EnvironmentReviewComposer, CustomerReviewWorkspace, and current review-pack summaries. Spec 354 must reuse those downstream semantics rather than inventing a new customer-facing risk language.
• The real gap is not missing accepted-risk truth. The gap is that the owning accepted-risk queue/detail surfaces still spread operator guidance across badges, due dates, warning text, decision history, and grouped actions instead of answering one first-order question in five seconds: what needs review now, why it matters, and what the next safe action is.

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

• Problem: TenantPilot already stores and exposes accepted-risk and finding-exception truth, but the queue and detail surfaces still require operators to reconstruct which accepted risk needs action, why it matters to governance, and whether the next step is renewal, revocation, proof review, or customer-safe wording review.
• Today's failure: Expiring, expired, incomplete, or weakly governed accepted risks can remain visible only as mixed status badges, due labels, warning strings, and action groups. Operators still need to translate those fragments into one clear governance decision.
• User-visible improvement: Finding Exceptions Queue and Finding Exception detail become decision-first accepted-risk surfaces that show one dominant guidance case with title, reason, impact, one dominant next-step affordance, and only existing repo-backed secondary context.
• Smallest enterprise-capable version: Reuse existing FindingException, FindingExceptionDecision, Finding, FindingRiskGovernanceResolver, queue/detail actions, and current customer-safe review signals to derive one accepted-risk guidance case on the existing queue and detail surfaces. Keep Governance Inbox, Customer Review Workspace, Environment Review, Review Pack, and Dashboard continuity bounded to already repo-backed links or wording only.
• Explicit non-goals: No new accepted-risk table or audit artifact, no new approval engine, no new risk-scoring framework, no new portal, no review-pack renderer change, no customer-review architecture rewrite, no Governance Inbox rebuild, no provider readiness work, no new workflow engine, and no fake remediation actions.
• Permanent complexity imported: One bounded accepted-risk guidance adapter or selector over the existing ResolutionCase / ResolutionAction path, focused unit/feature/browser coverage, one repo-truth map, one signal-map artifact, and UI-audit follow-through. No new persisted entity, no new enum family, no new queue family, and no new provider/platform framework is intended.
• Why now: Spec 353 explicitly deferred accepted-risk / finding-exception resolution guidance as the next bounded follow-up, and ui-012-finding-exceptions-queue.md already marks the queue as a strategic accepted-risk decision surface with P0/P1 productization pressure.
• Why not local: Copy-only tweaks on the queue or detail page would leave accepted-risk guidance fragmented across queue/detail/review surfaces. A broad governance-workflow rebuild would be disproportionate. The narrow correct slice is one derived guidance layer on the existing accepted-risk owner surfaces.
• Approval class: Workflow Compression.
• Red flags triggered: #1 Neue Achsen (one additional derived accepted-risk guidance case layer) and #2 Neue Meta-Infrastruktur (bounded adapter/selector under the existing shared guidance path). Defense: the slice stays on existing owner surfaces, reuses current truth, forbids new persistence/frameworks, and keeps the adapter bounded to existing ResolutionCase / ResolutionAction reuse instead of creating a second workflow engine.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source:
  • direct user-provided Spec 354 draft
  • explicit follow-up candidate recorded in specs/353-provider-connections-resolution-guidance-v1/spec.md
  • docs/ui-ux-enterprise-audit/page-reports/ui-012-finding-exceptions-queue.md
  • current accepted-risk/productization truth in FindingExceptionsQueue, ViewFindingException, FindingRiskGovernanceResolver, and Governance Inbox accepted-risk routing
• Completed-spec guardrail result:
  • no specs/354-* package or branch existed before this preparation run
  • Spec 343 (Implemented) and Spec 353 (Implemented (close-out audit pending)) are completed historical context only and must not be reopened or normalized
  • Specs 346, 349, 350, 351, and 352 are adjacent draft/prepared context only and are not being converted back into a fresh prep target
  • no completed task checklist, validation history, smoke result, or close-out text is being removed from any related spec package
• Close alternatives deferred:
  • broader Governance Inbox follow-through beyond the existing accepted-risk deep-link path
  • customer-facing localization/copy hardening outside accepted-risk wording that already affects review output
  • broader provider/onboarding productization after Spec 353
  • wider dashboard or lifecycle-taxonomy follow-through beyond existing accepted-risk context links
• Smallest viable implementation slice: existing FindingExceptionsQueue plus ViewFindingException only: derive one dominant accepted-risk guidance case, keep one dominant next-step affordance, preserve current approval/renewal/revocation behavior as source-owned actions, and reuse only the existing queue/detail related context already present on those owner surfaces.

Spec Scope Fields (mandatory)

• Scope: workspace-wide accepted-risk queue plus environment-bound accepted-risk detail.
• Primary Routes:
  • /admin/finding-exceptions/queue
  • /admin/workspaces/{workspace}/environments/{environment}/finding-exceptions
  • /admin/workspaces/{workspace}/environments/{environment}/finding-exceptions/{record}
  • existing deep links from /admin/governance/inbox and current review/dashboards only when they already route into those accepted-risk surfaces
• Data Ownership:
  • FindingException remains accepted-risk / exception lifecycle truth
  • FindingExceptionDecision remains decision history and current-decision truth
  • Finding remains source finding truth and linked workflow state
  • EvidenceSnapshot, EnvironmentReview, ReviewPack, and AuditLog remain secondary proof or downstream-output truth where already linked
  • any new guidance case remains derived-only and request-scoped
• RBAC:
  • workspace membership remains required
  • FindingExceptionsQueue keeps its existing workspace-scoped access posture and continues to require the existing queue capability boundary
  • detail and mutation flows continue to use environment entitlement plus existing Capabilities::FINDING_EXCEPTION_VIEW, FINDING_EXCEPTION_APPROVE, and FINDING_EXCEPTION_MANAGE
  • non-member / out-of-scope workspace or environment access remains deny-as-not-found
  • member-but-missing-capability remains denied according to current policy and capability semantics

For canonical-view specs:

• Default filter behavior when tenant-context is active: FindingExceptionsQueue remains workspace-wide and uses explicit environment_id filtering only. No hidden shell/session environment state may become authority for accepted-risk guidance.
• Explicit entitlement checks preventing cross-tenant leakage: queue filters, detail links, related finding links, review/workspace links, and proof links must continue to resolve only through current workspace membership plus entitled environment scope.

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

• 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:
  • FindingExceptionsQueue
  • selected-record accepted-risk summary and related actions inside the queue
  • ViewFindingException
  • accepted-risk continuity from Governance Inbox, Customer Review Workspace, Environment Review, Review Pack, and Environment Dashboard only where the current repo already exposes those links or wording
• Current or new page archetype:
  • FindingExceptionsQueue: existing strategic workspace queue / accepted-risk decision surface (UI-026)
  • ViewFindingException: existing environment-bound accepted-risk detail surface (UI-036)
• Design depth:
  • queue: Strategic Surface
  • detail: Strategic Surface because it owns high-impact accepted-risk lifecycle actions
• Repo-truth level: repo-verified existing runtime surfaces
• Existing pattern reused:
  • docs/ui-ux-enterprise-audit/page-reports/ui-012-finding-exceptions-queue.md
  • current queue/detail action-surface contracts
  • existing ResolutionCase / ResolutionAction contract
  • existing accepted-risk wording in Governance Inbox and review-output surfaces
• New pattern required: one bounded accepted-risk guidance adapter or selector over current FindingRiskGovernanceResolver truth; no new workflow engine or new customer-facing contract family
• Screenshot required: yes, for both queue and detail under specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/artifacts/screenshots/
• Page audit required:
  • update docs/ui-ux-enterprise-audit/page-reports/ui-012-finding-exceptions-queue.md
  • create or update docs/ui-ux-enterprise-audit/page-reports/ui-036-exception-detail.md
  • update docs/ui-ux-enterprise-audit/route-inventory.md so UI-036 links to the durable detail-page report and screenshot path
• Customer-safe review required: yes, because accepted-risk wording flows into customer-facing review and review-pack surfaces even though Spec 354 itself remains operator-facing
• Dangerous-action review required: yes; approve, reject, renew, and revoke remain high-impact and must keep confirmation, authorization, audit, and conservative copy
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
• No-impact rationale when applicable: N/A

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, next-step guidance, accepted-risk wording, decision/evidence disclosure, action links, and Governance Inbox continuity
• Systems touched:
  • App\Filament\Pages\Monitoring\FindingExceptionsQueue
  • App\Filament\Resources\FindingExceptionResource
  • App\Filament\Resources\FindingExceptionResource\Pages\ViewFindingException
  • App\Services\Findings\FindingRiskGovernanceResolver
  • App\Support\ResolutionGuidance\ResolutionCase
  • App\Support\ResolutionGuidance\ResolutionAction
  • App\Support\Ui\GovernanceActions\GovernanceActionCatalog
  • App\Support\GovernanceInbox\GovernanceInboxSectionBuilder
  • existing queue/detail related-context helpers and existing review wording sources as read-only reference only
• Existing pattern(s) to extend:
  • current accepted-risk queue/detail action hierarchy
  • current Governance Inbox accepted-risk lane
  • current review-output customer-safe accepted-risk summaries as wording reference only
  • current FindingRiskGovernanceResolver narrative and next-action truth
• Shared contract / presenter / builder / renderer to reuse:
  • FindingRiskGovernanceResolver
  • ResolutionCase / ResolutionAction
  • GovernanceActionCatalog
  • BadgeRenderer
  • current queue/detail link builders and current related-navigation helpers
• Why the existing shared path is sufficient or insufficient: the repo already has accepted-risk truth and an existing guidance contract, but the owner surfaces do not yet consume that truth as one explicit accepted-risk decision case with one dominant next action.
• Allowed deviation and why: one bounded accepted-risk adapter or selector is allowed if it wraps existing truth and avoids pushing queue/detail mapping logic directly into Blade or action closures.
• Consistency impact: titles, reason/impact structure, accepted-risk wording, next-step labels, and queue/detail related-context disclosure must stay aligned between queue, detail, Governance Inbox, and existing customer-safe review-output wording.
• Review focus: prevent a second accepted-risk workflow engine, prevent fake remediation buttons, prevent raw internal rationale or provider diagnostics from becoming default-visible, and prevent queue/detail drift from the shared guidance contract.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: deep-link semantics only
• Shared OperationRun UX contract/layer reused: existing proof links where accepted-risk evidence or downstream review artifacts already point at OperationRun detail
• Delegated start/completion UX behaviors: unchanged; Spec 354 does not add any new start, dedupe, block, or completion behavior
• Local surface-owned behavior that remains: ranking the dominant accepted-risk guidance case and choosing which already repo-backed navigation or source-owned action is primary
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam
• Boundary classification: platform-core governance truth over existing finding / accepted-risk / review artifacts
• Seams affected: accepted-risk wording and proof-link routing only
• Neutral platform terms preserved or introduced: accepted risk, finding exception, governance follow-up, review impact, evidence basis, decision history, related context
• Provider-specific semantics retained and why: only where existing linked finding or evidence detail already contains provider-backed wording; Spec 354 does not add new provider-shaped platform-core terms
• Why this does not deepen provider coupling accidentally: no Graph call, provider connection state, provider credential seam, or provider-owned persistence is introduced
• Follow-up path: none; provider readiness remains the separate Spec 353 lane

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
Finding Exceptions Queue overview	yes	Native Filament page plus existing Blade composition	accepted-risk queue, next-action guidance, proof links	page, URL-query, selected-record state	no	Existing route only
Queue selected-record summary and actions	yes	Native page state over existing queue	accepted-risk decision hierarchy, action grouping	page, selected-record summary	no	Reuse current selected-record model
View Finding Exception detail	yes	Native Filament detail page	accepted-risk reasoning, lifecycle action hierarchy, evidence/audit disclosure	detail, header actions	no	Existing route only
Governance Inbox deep-link continuity	possible	Existing page linking into queue	accepted-risk work routing	URL only	no	Only if existing label/target continuity needs bounded adjustment
Customer-review / review-pack accepted-risk wording continuity	reference only	Existing downstream wording source	customer-safe accepted-risk wording	wording only	no	Used as conservative wording reference only; no downstream surface redesign or mutation in this slice

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
Finding Exceptions Queue	Primary Decision Surface	Operator decides whether an accepted risk needs review now and which existing decision path to enter	status, reason, impact, expiry/review due, one dominant next-step affordance	linked finding, decision history, evidence, existing related context	Primary because it is the workspace-wide accepted-risk queue	follows governance follow-up workflow	removes reconstruction across badges, dates, and grouped actions
View Finding Exception	Secondary Context and action-owning detail	Operator validates the selected accepted risk and performs the permitted source-owned action	current validity, owner/rationale, evidence summary, one dominant next-step affordance	full decision history, deeper evidence refs, related finding/queue links	Secondary because it deepens the chosen queue item and owns the lifecycle action	follows accepted-risk detail workflow	prevents a second equal-weight decision home
Governance Inbox	Secondary Context	Operator routes from broader governance attention into the accepted-risk owner surface	queue item reason, impact, primary action label	deeper queue/detail context after open	Secondary because it is the daily cross-domain workbench, not the accepted-risk owner	follows open the owning surface workflow	avoids duplicating accepted-risk lifecycle controls

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
Finding Exceptions Queue	operator-MSP, manager, support where authorized	title, reason, impact, owner/due context, one dominant next-step affordance	linked finding state, evidence basis summary, decision history summary	raw provider evidence, low-level metadata, fingerprints, internal-only rationale detail	yes	raw/support detail remains secondary or capability-gated	queue states the blocker once; later sections add proof
View Finding Exception	operator-MSP, manager, support where authorized	current validity, reason, impact, action-safe state, owner/rationale/expiry where repo-backed	decision history, evidence references, related context	raw copied context, low-level provider/debug detail	yes	raw/support detail remains secondary	detail deepens the chosen case instead of restating the queue summary
Downstream wording continuity	customer-safe reader, operator-MSP	existing conservative accepted-risk wording remains the wording reference only	operator diagnostics stay on owner surfaces	raw/internal queue/detail rationale hidden by default	no new owner-surface action added here	internal governance detail hidden from customer-safe defaults	owner-surface copy reuses conservative wording instead of changing downstream artifacts

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
Finding Exceptions Queue	Queue / Decision Surface	Accepted-risk workspace queue	review the selected accepted risk	explicit inspect action / selected-record panel	existing explicit inspect model remains authoritative	grouped below the dominant next-step affordance and queue summary	existing approve/reject actions stay grouped and confirmed	/admin/finding-exceptions/queue	selected-record detail or existing detail route	workspace shell + visible environment_id filter	Finding exceptions / accepted risk	current validity, reason, impact, next step	none
View Finding Exception	Detail / Governance Record	Accepted-risk lifecycle detail	renew, revoke, or review proof based on allowed state	existing detail route	N/A	contextual proof and related links stay secondary	renew/revoke remain confirmed and source-owned	/admin/workspaces/{workspace}/environments/{environment}/finding-exceptions	/admin/workspaces/{workspace}/environments/{environment}/finding-exceptions/{record}	workspace + environment route	Finding exception	current decision truth and next step	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
Finding Exceptions Queue	Workspace governance operator	decide which accepted risk needs action now	workspace accepted-risk queue	Which accepted risk needs review, and what should I do next?	status, reason, impact, owner/due, environment, one dominant next-step affordance	linked finding/evidence detail only after explicit open	accepted-risk validity, governance attention, owner/due completeness, owner-surface continuity only	none by default on queue summary; source-owned actions only	inspect accepted risk, open finding, open existing related context	approve and reject remain grouped, confirmed, and auditable
View Finding Exception	Environment governance operator	validate and act on the selected accepted risk	detail surface	Is this accepted risk still safe to rely on, and what action is allowed now?	current validity, reason, impact, owner/rationale/expiry, one dominant next-step affordance	decision history, deeper evidence refs, related queue/finding context	accepted-risk validity, pending/renewal posture, governance support completeness	existing exception lifecycle only	renew, revoke, open related context	renew and revoke remain high-impact and confirmation-gated

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: one bounded accepted-risk adapter or selector is allowed only inside the existing ResolutionGuidance path if it keeps queue/detail mapping derived and testable
• New enum/state/reason family?: no; reuse existing FindingException status and validity truth plus existing resolver output
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: accepted-risk follow-up still requires reconstructing meaning from fragmented queue/detail signals
• Existing structure is insufficient because: queue/detail surfaces already have state, warnings, and actions, but they do not yet present one explicit decision-first accepted-risk case
• Narrowest correct implementation: derive one guidance case over existing finding/exception truth on the current queue/detail surfaces and keep downstream links conservative and repo-backed
• Ownership cost: one adapter or selector, focused tests, copy updates, and page-audit maintenance
• Alternative intentionally rejected: new accepted-risk workflow engine, new persisted review state, new dashboard/workbench, or broad customer portal/GRC rebuild
• Release truth: current-release productization over repo-real finding-exception and review-output truth

Summary

Spec 354 turns accepted-risk owner surfaces into decision-first guidance surfaces.

The implementation remains narrow:

• reuse existing FindingException, FindingExceptionDecision, Finding, and FindingRiskGovernanceResolver truth
• keep queue and detail surfaces authoritative
• preserve current high-impact action ownership, confirmation, authorization, and audit behavior
• reuse downstream customer-safe wording where already repo-backed
• avoid new persistence, new frameworks, and fake remediation

Problem Statement

Accepted risks are governance-of-record artifacts, not passive labels.

TenantPilot already stores accepted-risk state, current decision, owner, expiry, review due dates, linked finding state, and downstream customer-safe summaries. The owner surfaces still require operators to infer what matters most from fragments:

• warning strings
• status badges
• due dates
• grouped header actions
• queue rows
• Governance Inbox routing

That fragmentation increases the chance of false calmness:

• expiring accepted risks may look merely informational
• missing owner or rationale may be noticed too late
• revoked or expired support may still be mentally treated as valid governance
• downstream customer-review output may rely on accepted-risk wording without a clear operator reminder that follow-up is needed

Primary Users And Operators

• MSP or workspace operators managing governance follow-up
• tenant/environment operators responsible for accepted-risk lifecycle actions
• support users with existing entitlement who need audit/evidence context after the primary decision is made

This slice does not target a customer portal or public audience directly.

Goals

G1 - Add accepted-risk resolution guidance on the owner surfaces

Finding Exceptions Queue and accepted-risk detail must show one dominant guidance case when accepted-risk follow-up is required.

G2 - Preserve existing exception and decision truth

Use existing records, resolver output, and current source-owned actions. Do not introduce a second accepted-risk model.

G3 - Keep one dominant next-step affordance

Each guidance case exposes one dominant next-step affordance. On source-owned lifecycle surfaces, that affordance may point to an existing paired action group rather than collapsing truthful action pairs into one synthetic button. Other supported links remain visibly secondary.

G4 - Keep customer-safe boundary conservative

Accepted-risk wording may flow into review-output surfaces, but raw internal rationale, provider diagnostics, copied context, and internal-only detail stay secondary or hidden where appropriate.

G5 - Reuse existing shared guidance and action contracts

Use the current ResolutionCase / ResolutionAction and current governance action catalog where they are already sufficient.

G6 - Keep evidence and related context on demand

Operators must be able to open existing related context that is already repo-backed on the owner surfaces, but the first-read queue/detail surface must remain calm and decision-first.

User Scenarios & Testing (mandatory)

User Story 1 - Review expiring or expired accepted risks quickly (Priority: P1)

As a workspace governance operator, I can open Finding Exceptions Queue and immediately see whether an accepted risk is expiring or already expired, why that matters, and what I should do next.

Why this priority: This is the core operator workflow gap described by the queue audit and by Spec 353's follow-up note.

Independent Test: Seed valid, expiring, and expired exceptions; open the queue; confirm one dominant guidance case, one dominant next-step affordance, and only existing repo-backed secondary context.

Acceptance Scenarios:

1. Given an accepted risk is expiring soon, When the queue renders, Then the page states that review is required, explains the impact, and offers one dominant next-step affordance.
2. Given an accepted risk already expired, When the queue or detail renders, Then the page states that the prior governance is no longer current and offers a repo-backed next action.

User Story 2 - Review or complete accepted-risk details from the owner surface (Priority: P1)

As an environment governance operator, I can open the accepted-risk detail and understand whether owner, rationale, expiry, or governance support is missing before I decide to renew or revoke.

Why this priority: Accepted-risk lifecycle actions are already repo-real, but their decision context still needs first-screen hierarchy.

Independent Test: Seed exceptions missing owner/rationale/review due dates or missing support states; open the detail page; confirm the page explains the issue before deeper diagnostics and preserves current action safety rules.

Acceptance Scenarios:

1. Given an accepted risk is missing owner or rationale, When detail renders, Then the page explains that customer-safe reliance is incomplete and routes the operator to the existing owner surface action path.
2. Given an accepted risk can be renewed or revoked, When detail renders, Then the page keeps those actions available only when the current capability and state permit them, with current confirmation behavior unchanged.

User Story 3 - Understand downstream review impact without exposing internal rationale (Priority: P2)

As an operator preparing customer-safe review output, I can tell whether an accepted risk affects downstream review wording or evidence trust without exposing internal-only detail by default.

Why this priority: Accepted risks are customer-relevant, but Spec 354 must not leak internal governance detail into customer-safe output paths.

Independent Test: Seed a review/output context with accepted-risk follow-up; verify queue/detail surfaces reuse conservative wording as owner-surface context only and do not require downstream artifact changes.

Acceptance Scenarios:

1. Given an accepted risk is included in current review-output truth, When the owner surfaces render, Then they expose a conservative downstream impact message without requiring a new downstream route or artifact change.
2. Given internal rationale or low-level diagnostics exist, When the operator views the accepted-risk guidance, Then those details remain secondary and are not treated as customer-safe summary text.

User Story 4 - Calm ready state when no accepted-risk action is required (Priority: P3)

As an operator, when the current accepted-risk record is governed and needs no urgent action, I want the surface to stay calm and not render another warning wall.

Why this priority: Guidance should reduce noise, not replace one alert stack with another.

Independent Test: Seed a governed, valid accepted risk and verify queue/detail show a calm ready state with non-urgent secondary context.

Acceptance Scenarios:

1. Given the accepted risk is valid, complete, and not near expiry, When the surface renders, Then it shows a calm ready state and no urgent warning copy.

Edge Cases

• No accepted risk needs action.
• Accepted risk is pending approval or pending renewal.
• Accepted risk is expiring.
• Accepted risk is expired.
• Accepted risk was revoked or rejected.
• Existing exception record carries missing_support or fresh-decision-required governance follow-up.
• Accepted risk is missing owner, rationale, or review due date.
• Conservative downstream wording reference exists, but the owner surface still keeps downstream artifacts unchanged in this slice.
• Environment filter is present and matches no accepted-risk records.
• Queue selection points at an out-of-scope or no-longer-visible exception.
• Finding changed after the exception decision only when the repo can prove it; unsupported stale-detection cases must be omitted rather than invented.

Requirements (mandatory)

Functional Requirements

• FR-354-001: The queue and detail owner surfaces MUST derive accepted-risk guidance from existing FindingException, FindingExceptionDecision, Finding, and resolver truth; no new persistence is allowed.
• FR-354-002: FindingExceptionsQueue MUST show one dominant accepted-risk guidance case with title, reason, impact, one dominant next-step affordance, and only existing repo-backed secondary context or links.
• FR-354-003: ViewFindingException MUST show one dominant accepted-risk guidance case while preserving the current source-owned approve/reject/renew/revoke lifecycle behavior, current confirmation rules, and current infolist-owned detail hierarchy.
• FR-354-004: Guidance MUST distinguish, where repo-backed on existing FindingException owner surfaces, between at least these operator-meaningful cases: valid, expiring, expired, revoked, rejected, pending, missing governance support on an existing exception record, fresh decision required, and missing owner/rationale/review support.
• FR-354-005: The surface MUST preserve the current repo-real fresh-decision warning path driven by FindingException::requiresFreshDecisionForFinding() and FindingRiskGovernanceResolver; this slice MUST NOT invent broader stale-governance semantics beyond that existing signal.
• FR-354-006: Primary and secondary actions MUST remain repo-backed and truthful. Unsupported auto-fix or synthetic remediation buttons are forbidden.
• FR-354-007: Queue and detail guidance MUST preserve current environment/workspace scope and current route ownership. No hidden context, legacy query alias, or cross-tenant shortcut may become authority.
• FR-354-008: Customer-safe wording reference used on the owner surfaces MUST remain conservative and MUST NOT expose raw internal rationale, copied context, provider diagnostics, or internal-only reason families by default.
• FR-354-009: Existing high-impact actions remain source-owned and MUST continue to use server-side authorization, explicit confirmation, audit logging, and current notification behavior.
• FR-354-010: FindingExceptionResource MUST remain not globally searchable.
• FR-354-011: Queue and detail surfaces SHOULD only expose related context or links that are already present and scope-safe on the current owner surfaces; this slice does not add new downstream review, audit, or operation-proof destinations.

Non-Functional Requirements

• NFR-354-001: No Graph or provider HTTP calls may be introduced during queue/detail render.
• NFR-354-002: No database migration, env var, queue family, scheduler, storage, or panel/provider change is allowed in this slice.
• NFR-354-003: Guidance copy must stay operator-first and conservative; when certainty is low, the UI must prefer requires review over safe language.
• NFR-354-004: The implementation must reuse the smallest honest test mix: unit for guidance selection, feature/Livewire for queue/detail integration, and one bounded browser smoke for the strategic queue/detail surfaces.

Acceptance Criteria

Product

• Queue renders one dominant accepted-risk guidance case with one dominant next-step affordance.
• Detail renders one dominant accepted-risk guidance case without replacing current source-owned lifecycle actions.
• Expiring, expired, missing-support, and incomplete accepted-risk states map to distinct operator guidance where repo-backed.
• Calm ready state remains calm and does not show urgent language when no action is required.

Truth / Safety

• No new persisted accepted-risk truth or workflow engine is introduced.
• No fake remediation or unsupported action is surfaced.
• Customer-safe downstream wording remains conservative and does not expose internal-only detail by default.
• Existing destructive/high-impact action safety posture remains intact.

RBAC / Isolation

• Queue and detail remain workspace/environment scoped and deny out-of-scope access as not found.
• Action visibility and executability continue to follow existing capability and policy boundaries.
• Secondary proof links remain scope-safe.

Validation

• Focused unit tests cover accepted-risk guidance selection cases, including the existing fresh-decision-required signal.
• Focused feature/Livewire tests cover queue/detail hierarchy, scope, and action truthfulness.
• One bounded browser smoke proves first-screen hierarchy for queue and detail.

Risks

• Risk 1 - Guidance duplication: queue and detail may drift from Governance Inbox and existing conservative review-output wording. Mitigation: reuse existing resolver/guidance contract and keep downstream review artifacts unchanged in this slice.
• Risk 2 - Customer-safe leakage: accepted-risk detail may accidentally expose internal-only rationale too early. Mitigation: keep raw/support detail secondary and test default-visible content explicitly.
• Risk 3 - Fake remediation pressure: productization may tempt unsupported "fix now" actions. Mitigation: restrict actions to current repo-backed routes and source-owned lifecycle actions only.
• Risk 4 - Scope creep into a governance workbench rebuild: mitigation is to keep queue/detail owner surfaces primary and defer any broader Governance Inbox or dashboard rethink.

Spec Artifacts (required for this package)

• specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/spec.md
• specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/plan.md
• specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/tasks.md
• specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/repo-truth-map.md
• specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/contracts/accepted-risk-guidance-signal-map.md
• specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/checklists/requirements.md

Follow-Up Candidates

• broader Governance Inbox follow-through after the accepted-risk owner surfaces are calm and decision-first
• customer-facing localization and copy hardening across review-output accepted-risk language
• wider governance artifact lifecycle follow-through once accepted-risk operator guidance is stable

Assumptions

• Existing FindingRiskGovernanceResolver plus current queue/detail state are sufficient to derive the dominant accepted-risk guidance case without new persistence.
• Existing queue/detail actions and current owner-surface related context are the authoritative safe action set for this slice.
• The current fresh-decision-required signal exposed by FindingException::requiresFreshDecisionForFinding() is in-scope and must be preserved, but broader stale-governance expansion remains out of scope.

Open Questions

No blocking preparation questions remain.

Implementation should still confirm one bounded runtime choice during tests-first work:

• whether any owner-surface wording needs a narrower local copy adjustment while leaving downstream review-output artifacts unchanged