TenantAtlas/specs/354-finding-exceptions-accepted-risk-resolution-guidance-v1/repo-truth-map.md

# Repo Truth Map: Spec 354 - Finding Exceptions / Accepted Risk Resolution Guidance v1

## Scope

Bounded accepted-risk guidance follow-up over the existing queue and detail owner surfaces.

This prep package must not reopen completed customer-review, provider-readiness, or broad governance-workbench packages.

## Candidate Selection Summary

- **Selected candidate**: direct user-provided Spec 354 draft
- **Why selected**:
  - explicit user-provided next slice
  - explicit follow-up note in Spec 353
  - strategic queue audit `ui-012-finding-exceptions-queue.md`
  - existing repo-real accepted-risk foundations already exist, so the narrow next step is productization on the owning surfaces
- **Why not the older backlog items**:
  - the active candidate queue says no safe automatic next-best-prep target remains
  - earlier customer-review/provider/governance lanes already have newer spec packages
  - this user-provided candidate is a bounded direct follow-up rather than a duplicate refresh of an older manual-promotion item

## Completed-Spec Guardrail Result

| Related spec | Status in repo | Guardrail handling |
|---|---|---|
| Spec 343 - Customer Review Attestation / Accepted Risk Lifecycle | Implemented | context only |
| Spec 346 - Governance Inbox Final Operator Workflow | Draft | adjacent context only |
| Spec 349 - Customer Review Workspace Output Resolution Guidance | Draft | adjacent context only |
| Spec 350 - Operator Resolution Guidance Framework v1 | Draft | shared-contract context only |
| Spec 351 - Review Output Resolve Actions v1 | Draft | adjacent action-mapping context only |
| Spec 352 - Environment Dashboard Operator Guidance Consolidation | Draft | adjacent routing/wiring context only |
| Spec 353 - Provider Connections Resolution Guidance v1 | Implemented (close-out audit pending) | context only; do not reopen |

No completed spec package is being normalized back into preparation-only wording.

## Primary Runtime Surfaces

| Surface | Repo truth | Why it matters to Spec 354 |
|---|---|---|
| `FindingExceptionsQueue` | workspace-wide accepted-risk queue with selected-record review state, explicit `environment_id` filter, approve/reject actions, and related links | primary operator owner surface |
| `ViewFindingException` | environment-bound accepted-risk detail with renew/revoke actions and decision-register return-link support | action-owning detail surface |
| `FindingExceptionResource` | accepted-risk resource with global search disabled | keep global search unchanged and preserve current resource contract |
| `FindingRiskGovernanceResolver` | derives workflow family, warnings, narrative, next action, validity, and governance attention | primary existing truth source for guidance selection |
| `GovernanceInboxSectionBuilder` | emits accepted-risk lane labels, due context, and `Review accepted risk` deep link | continuity source, not owner surface |
| `EnvironmentReviewComposer` and current review-pack summaries | already emit customer-safe accepted-risk wording | wording reference only; downstream artifacts stay unchanged in this slice |

## Runtime Signals Already Available

| Signal family | Existing repo-backed inputs |
|---|---|
| Exception lifecycle | `status`, `current_validity_state`, `expires_at`, `review_due_at`, `revoked_at`, `currentDecisionType()` |
| Governance support completeness | owner, request reason, evidence refs, pending-renewal state, valid exception presence |
| Finding relationship | linked `Finding`, workflow family, accepted-risk status, stale-governance warning text |
| Queue/detail action truth | approve, reject, renew, revoke, inspect/open links, and current related-context disclosure |
| Downstream review impact | current review-output accepted-risk wording exists as reference truth, but downstream artifacts are not in-scope mutation targets for this slice |

## Draft-To-Repo Corrections

1. The queue already exists and is already the accepted-risk workbench. Spec 354 must productize it rather than inventing a new queue or register.
2. The detail page already owns renew/revoke actions. Spec 354 must keep those actions source-owned.
3. `FindingRiskGovernanceResolver` already contains accepted-risk narrative and next-action truth. Spec 354 must adapt or wrap it instead of writing a second lifecycle interpreter from scratch.
4. Governance Inbox already routes accepted-risk work into the queue with a repo-real label. Spec 354 only needs continuity, not a new inbox lane.
5. Customer-safe accepted-risk wording already exists in downstream review surfaces. Spec 354 must keep those surfaces secondary.

## Current Gaps This Spec May Close

| Gap | Repo evidence |
|---|---|
| No single dominant guidance case on queue owner surface | queue audit `ui-012` and current queue/detail runtime split |
| Accepted-risk explanation still distributed across badges, warnings, and grouped actions | current queue/detail structure plus resolver copy |
| Existing fresh-decision-required warning is not yet promoted into a decision-first summary on the owner surfaces | `requiresFreshDecisionForFinding()` plus resolver warning copy already exist, but remain embedded inside secondary warning treatment |

## Out Of Scope Confirmed By Repo Truth

- No new accepted-risk or attestation table
- No new review-pack format or export renderer
- No new provider-readiness work
- No new Governance Inbox or dashboard rebuild
- No new portal or customer-facing standalone accepted-risk page
- No new global-search enablement for `FindingExceptionResource`

## Likely Narrow Implementation Shape

- one bounded accepted-risk adapter or selector under the existing resolution-guidance support path
- queue summary integration
- detail summary integration
- continuity fixes only where current Governance Inbox deep links or owner-surface wording would otherwise contradict the new guidance