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

# Implementation Plan: Spec 354 - Finding Exceptions / Accepted Risk Resolution Guidance v1

- Branch: `354-finding-exceptions-accepted-risk-resolution-guidance-v1`
- Date: 2026-06-05
- Spec: `specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/spec.md`
- Input: Spec 354 + repo inspection of Finding Exceptions queue/detail surfaces, accepted-risk governance resolver, Governance Inbox accepted-risk routing, and downstream review-output continuity.

## Summary

Add one derived accepted-risk guidance layer to the existing Finding Exceptions queue and detail owner surfaces so operators can see one dominant accepted-risk case, one dominant next-step affordance, and conservative owner-surface wording without reconstructing meaning from badges, dates, and grouped actions.

The implementation stays narrow:

- reuse existing `FindingException`, `FindingExceptionDecision`, `Finding`, `FindingRiskGovernanceResolver`, `ResolutionCase`, and current lifecycle actions
- keep queue/detail as the owning accepted-risk surfaces
- preserve current action confirmation, authorization, audit, and notification behavior
- reuse downstream customer-safe wording only where already repo-backed
- avoid new persistence, new provider seams, and new workflow frameworks

## Technical Context

- Language/Version: PHP 8.4.15, Laravel 12.52.x
- UI stack: Filament 5.2.x, Livewire 4.x
- Database: PostgreSQL, no schema change planned
- Testing: Pest unit + feature/Livewire + one strategic browser smoke
- Validation lanes: fast-feedback + confidence + browser
- Local runtime posture: Sail-first
- Deployment/runtime impact: no expected env, migration, queue-family, scheduler, storage, or panel/provider change
- Global search: unchanged; `FindingExceptionResource` remains not globally searchable

## Current Repo Truth That Constrains The Slice

- `FindingExceptionsQueue` already owns:
  - workspace-wide accepted-risk access
  - explicit `environment_id` filter behavior
  - selected-record inspect state
  - approve / reject actions with confirmation
  - related finding and queue/deep-link actions
- `ViewFindingException` already owns:
  - accepted-risk detail presentation
  - renew / revoke actions with confirmation
  - decision-register return-link continuity
- `FindingExceptionResource` already disables global search.
- `FindingRiskGovernanceResolver` already derives:
  - accepted-risk workflow family
  - governance warning text
  - primary narrative
  - next-action copy
  - validity / attention signals
  - the current repo-real fresh-decision-required warning path
- `GovernanceInboxSectionBuilder` already exposes accepted-risk lane text, due context, and the primary action label `Review accepted risk`.
- Customer-safe accepted-risk summaries already exist in review-output paths through `EnvironmentReviewComposer`, Customer Review Workspace, and review-pack summaries, but this slice should treat them as wording reference rather than a runtime mutation target.
- The queue audit (`ui-012`) already marks risk decision language, expiry visibility, and customer-safe wording as top issues.
- There is no need for a second accepted-risk model, a new accepted-risk page family, or a new review-output engine.

## Domain / Model Implications

- No schema or migration change is planned.
- No new persisted accepted-risk readiness entity, review-impact entity, or action-history model is allowed in this slice.
- The narrowest acceptable implementation shape is one derived accepted-risk guidance adapter or selector over:
  - current `FindingException`
  - current `FindingExceptionDecision`
  - current linked `Finding`
  - current `FindingRiskGovernanceResolver`
  - current queue/detail action availability
- Existing ownership boundaries remain unchanged:
  - exception lifecycle truth stays `FindingException` / `FindingExceptionDecision` owned
  - source finding truth stays `Finding` owned
  - customer-safe review truth stays review/output owned and unchanged by this slice
  - any new guidance state stays request-local and derived

## UI / Filament / Livewire Implications

- Filament v5 continues to run on Livewire v4.x; no version or API drift is permitted.
- No panel/provider registration change is allowed; `apps/platform/bootstrap/providers.php` remains untouched.
- `FindingExceptionResource` stays not globally searchable.
- Existing destructive or high-impact accepted-risk actions must keep their current confirmation, authorization, notification, and audit posture.
- No new asset registration is planned, so there is no expected `filament:assets` deployment change for this spec.

## RBAC / Policy Implications

- Workspace membership and entitled environment access remain the only scope authorities.
- Current capabilities continue to decide queue visibility, detail visibility, and lifecycle-action executability.
- Guidance selection itself must remain safe for unauthorized users by operating only on already-authorized page state.
- Queue and detail must keep deny-as-not-found semantics for out-of-scope workspace/environment access.

## Audit / Logging / Evidence Implications

- Existing approve / reject / renew / revoke handling and current audit emission remain authoritative.
- No new audit stream, notification family, or evidence artifact is planned.
- The implementation must keep accepted-risk render paths read-only and side-effect free.
- Existing related-context disclosure, decision history, and evidence references remain secondary and only appear when already repo-backed on the current owner surfaces.

## Data / Migration Implications

- No database migration, backfill, or persisted projection is planned.
- All derived guidance output must be request-local and DB-backed from already stored truth.
- Compatibility shims are not justified because no data shape replacement is proposed in this prep slice.

## Rollout Considerations

- No feature flag is expected because the slice is a bounded presentation improvement over existing repo truth.
- Staging validation should still prove four operator states explicitly:
  - expiring accepted risk
  - expired, revoked, or fresh-decision-required support
  - incomplete governance support (owner/rationale/review due missing on an existing exception record)
  - calm valid state
- Production risk is limited to guidance hierarchy, wrong-link regressions, and owner-surface wording drift, so focused tests and one bounded browser smoke remain the main rollout controls.

## UI / Surface Guardrail Plan

- **Guardrail scope**:
  - `FindingExceptionsQueue`
  - selected-record queue summary and action hierarchy
  - `ViewFindingException`
  - downstream accepted-risk wording continuity only where already repo-backed
- **Affected surfaces**:
  - `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`
  - `apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php`
  - `apps/platform/app/Filament/Resources/FindingExceptionResource.php`
  - `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php`
  - `apps/platform/resources/views/filament/pages/monitoring/partials/finding-exception-queue-sidebar.blade.php`
  - `apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php`
  - `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php`
- **Native vs custom**:
  - preserve native Filament queue/detail ownership
  - avoid new custom page families
  - allow one bounded derived guidance adapter or selector if necessary
- **Shared-family relevance**:
  - status messaging
  - next-action guidance
  - accepted-risk wording
  - evidence / decision-history disclosure
  - Governance Inbox to owner-surface continuity
- **Required tests / smoke**:
  - focused unit tests for accepted-risk guidance selection
  - feature/Livewire tests for queue/detail rendering and scope-safe action/link hierarchy
  - one bounded browser smoke for the strategic queue/detail surfaces
- **UI/Productization coverage**:
  - update `ui-012-finding-exceptions-queue.md`
  - create or update `ui-036-exception-detail.md`
  - update `route-inventory.md` coverage for `UI-036`
  - update `unresolved-pages.md` to remove or reclassify `UI-036` once durable coverage exists
  - update `design-coverage-matrix.md` only if classification or surface counts change

## Shared Pattern And System Fit

- **Preferred reuse path**:
  - current `FindingRiskGovernanceResolver` truth
  - current `ResolutionCase` / `ResolutionAction` contract
  - current `GovernanceActionCatalog`
  - current queue/detail links and navigation helpers
  - current review-output accepted-risk wording as conservative wording reference only
- **Likely implementation shape**:
  - one bounded `FindingExceptionResolutionAdapter` or page-local selector under the current `ResolutionGuidance` path
  - queue/detail-specific mapping stays local to the accepted-risk owner surfaces
  - existing paired lifecycle actions remain source-owned even when one dominant next-step affordance is promoted in the guidance summary
- **Avoid**:
  - new accepted-risk workflow engine
  - new persisted readiness or action state
  - new global review-impact framework
  - new provider/platform abstraction

## OperationRun UX Impact

Spec 354 does not create a new `OperationRun` type and does not require new `OperationRun` links on the accepted-risk owner surfaces.

Implementation responsibility is limited to preserving the current no-new-OperationRun-link posture unless an already-present owner-surface related-context path exists.

## Likely Runtime Files

| Area | Repo-real files |
|---|---|
| Queue runtime | `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`, `apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php` |
| Queue focused-review partial | `apps/platform/resources/views/filament/pages/monitoring/partials/finding-exception-queue-sidebar.blade.php` |
| Detail runtime | `apps/platform/app/Filament/Resources/FindingExceptionResource.php`, `apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php` |
| Accepted-risk truth | `apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php`, `apps/platform/app/Services/Findings/FindingExceptionService.php` |
| Shared guidance contract | `apps/platform/app/Support/ResolutionGuidance/ResolutionCase.php`, `apps/platform/app/Support/ResolutionGuidance/ResolutionAction.php` |
| Adjacent routing / continuity | `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php`, current related-navigation helpers |
| Downstream wording reference only | `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`, `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`, current review-pack summary builders |
| UI audit docs | `docs/ui-ux-enterprise-audit/page-reports/ui-012-finding-exceptions-queue.md`, `docs/ui-ux-enterprise-audit/page-reports/ui-036-exception-detail.md`, `docs/ui-ux-enterprise-audit/route-inventory.md`, `docs/ui-ux-enterprise-audit/unresolved-pages.md` |

## Likely Test Files

| Layer | Planned file |
|---|---|
| Unit | `apps/platform/tests/Unit/ResolutionGuidance/Spec354AcceptedRiskResolutionAdapterTest.php` |
| Feature/Livewire | `apps/platform/tests/Feature/Monitoring/Spec354FindingExceptionsQueueGuidanceTest.php` |
| Feature/Livewire | `apps/platform/tests/Feature/Findings/Spec354FindingExceptionDetailGuidanceTest.php` |
| Browser | `apps/platform/tests/Browser/Spec354AcceptedRiskGuidanceSmokeTest.php` |

## Implementation Approach

### Phase 0 - Repo Truth Gate

1. Re-read `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, `contracts/accepted-risk-guidance-signal-map.md`, and `checklists/requirements.md`.
2. Re-verify the current runtime truth in the queue/detail/resolver/governance files listed below.
3. Keep draft mismatches explicit:
   - no new accepted-risk model
   - no global-search change
   - no standalone customer-facing accepted-risk surface
4. Confirm no migration, package, env var, queue-family, storage, panel/provider, or global-search change is required.

### Phase 1 - Tests First

1. Add unit coverage for deterministic guidance selection:
   - valid accepted risk
   - expiring accepted risk
   - expired support
   - revoked or rejected support
   - fresh decision required
   - pending or renewal-requested support
   - missing governance support on an existing exception record
   - incomplete owner/rationale/review support
   - conservative owner-surface wording reuse without downstream artifact mutation
2. Add feature/Livewire coverage for the queue:
   - one dominant case
   - one dominant next-step affordance
   - existing related context only when repo-backed
   - no fake remediation buttons
   - scope-safe links and explicit `environment_id` behavior
   - out-of-scope access stays 404 and member-but-missing-capability behavior stays aligned with current queue semantics
3. Add feature/Livewire coverage for detail:
   - one dominant case
   - current infolist hierarchy remains detail-owned
   - current high-impact actions remain state- and capability-bound
   - owner/rationale/review support is visible before deeper diagnostics
   - out-of-scope detail access stays 404 and action denial remains capability-bound
4. Add one browser smoke:
   - queue expiring state
   - queue or detail expired/revoked state
   - detail incomplete-governance state
   - calm valid state

### Phase 2 - Derived Guidance Contract

1. Choose the narrowest implementation shape:
   - prefer one bounded accepted-risk adapter or selector
   - avoid expanding review-output or provider adapters into a generic risk-workflow engine
2. Build one derived accepted-risk payload with:
   - key
   - title
   - status
   - severity
   - reason
   - impact
   - primary action or dominant next-step mapping
   - secondary actions
   - technical details
3. Keep priority ordering explicit and narrow.
4. Preserve the current fresh-decision-required signal from `requiresFreshDecisionForFinding()` and do not expand it into a broader stale-governance framework.

### Phase 3 - Queue Integration

1. Add a top guidance presentation to `FindingExceptionsQueue` without removing current queue/table/selected-record truth.
2. Reuse existing repo-backed actions and links:
   - inspect accepted risk
   - approve exception
   - reject exception
   - open finding
   - existing related context only when already available on the current surface
3. Keep destructive/high-impact actions unchanged:
   - confirmation
   - authorization
   - audit
   - notifications
4. Do not widen authorization because guidance is more visible.

### Phase 4 - Detail Integration

1. Add an explicit guidance summary to the detail surface through `FindingExceptionResource::infolist()` and `ViewFindingException`.
2. Reuse current owner/rationale/expiry/review data before inventing any new accepted-risk state.
3. Keep renew and revoke source-owned.
4. Keep decision history, evidence references, and related context secondary.

### Phase 5 - Downstream Continuity

1. Reuse current Governance Inbox accepted-risk deep-link and update it only if label or target continuity is inconsistent after queue/detail guidance becomes decision-first.
2. Reuse existing conservative accepted-risk wording as owner-surface reference only; do not mutate downstream review-output artifacts in this slice.
3. Avoid turning downstream review-output surfaces into second accepted-risk owner surfaces.

### Phase 6 - Copy, Audit, And Artifacts

1. Update only the copy required in `apps/platform/lang/en/localization.php`.
2. Update matching copy in `apps/platform/lang/de/localization.php`.
3. Update `docs/ui-ux-enterprise-audit/page-reports/ui-012-finding-exceptions-queue.md`.
4. Create or update `docs/ui-ux-enterprise-audit/page-reports/ui-036-exception-detail.md`.
5. Update `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/unresolved-pages.md` for `UI-036`.
6. Save screenshots under the Spec 354 artifact path, or record the host-visible artifact blocker honestly.

### Phase 7 - Validation

1. Run focused unit, feature, and browser coverage for this slice.
2. Re-run current queue/detail related acceptance and guard tests in the narrowest honest family.
3. Confirm final render paths remain DB-local and do not call `GraphClientInterface` or provider HTTP during page render.
4. Run `pint` and `git diff --check`.
5. Report broader-suite or unrelated browser-harness issues honestly if they remain outside this slice.