TenantAtlas/specs/231-finding-outcome-taxonomy/spec.md

Feature Specification: Finding Outcome Taxonomy & Verification Semantics

Feature Branch: 231-finding-outcome-taxonomy
Created: 2026-04-22
Status: Draft
Input: User description: "Finding Outcome Taxonomy & Verification Semantics"

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

• Problem: Findings can currently end in materially different ways, but the product does not communicate those differences with one bounded, structured meaning. Resolved, closed, auto-cleared, false-positive, duplicate, and no-longer-applicable paths can all collapse into ambiguous operator or reporting language.
• Today's failure: An operator, reviewer, or auditor cannot reliably tell whether a finding was fixed by an operator, later verified as cleared by the system, closed as non-actionable, or still only waiting for confirmation. Filters, summaries, and review outputs therefore drift away from the real governance meaning.
• User-visible improvement: Findings surfaces show one honest terminal-outcome language: operators can choose bounded terminal reasons, lists and detail views distinguish Resolved pending verification from Verified cleared, and reporting can separate remediation outcomes from administrative closure outcomes.
• Smallest enterprise-capable version: Keep the existing findings lifecycle from Spec 111, add one bounded structured outcome taxonomy plus one bounded verification layer on top of existing findings, and apply that contract consistently to action forms, detail summaries, list filters, reopen reasons, audit copy, and downstream reporting consumers.
• Explicit non-goals: No comments or case-notes system, no attachments, no new findings queue, no external ticket handoff, no risk-exception redesign, no generic case-management engine, and no new primary lifecycle status family for findings.
• Permanent complexity imported: One bounded findings outcome taxonomy, one bounded verification-outcome vocabulary, one bounded reopen-reason family, focused action and filter updates on existing findings surfaces, and regression coverage for action, filter, audit, and reporting semantics.
• Why now: The roadmap's Findings Workflow v2 / Execution Layer already has ownership, inbox, intake, notifications, and hygiene slices specced. The remaining hardening point is exactly resolved-versus-verified outcome semantics, and downstream review and reporting quality depends on it.
• Why not local: A local wording fix in one modal or one report would still leave detail views, reopen behavior, filters, audit events, and review outputs speaking different terminal-outcome languages.
• Approval class: Core Enterprise
• Red flags triggered: One new structured reason family and one new verification interpretation layer. Scope remains acceptable because the feature reuses the existing finding lifecycle, existing exception validity semantics, and existing finding records instead of adding a new entity or queue.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitat: 1 | Produktnahe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: tenant
• Primary Routes:
  • /admin/t/{tenant}/findings as the existing tenant findings queue and filter surface
  • /admin/t/{tenant}/findings/{finding} as the existing finding detail and transition surface
  • Existing findings-derived review, summary, and export consumers that already aggregate terminal findings outcomes, without introducing a new primary route in this slice
• Data Ownership:
  • Tenant-owned findings remain the only source of truth for workflow status, outcome meaning, verification meaning, and reopen semantics.
  • Existing review, export, and governance summary consumers remain derived read models over finding and exception truth; no second outcome register or reporting-only persistence layer is introduced.
  • Existing audit events remain the durable mutation trail for resolve, close, and reopen transitions.
• RBAC:
  • Tenant membership is required for read or mutation behavior on tenant findings surfaces.
  • Existing findings view permission gates read access.
  • Existing findings transition or management permissions gate resolve, close, and reopen mutations.
  • Existing review and export consumers must remain tenant-entitlement filtered; users must not learn terminal-outcome counts or labels for unauthorized tenants.
  • Non-members and cross-tenant requests remain deny-as-not-found. In-scope users lacking the required mutation capability remain explicitly forbidden for protected actions.

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, action-modal semantics, filters, reporting and export summaries, audit prose
• Systems touched:
  • Existing findings lifecycle action surfaces on the tenant findings list and finding detail page
  • Existing findings list filters and terminal-state presentation
  • Existing findings-derived review, report, and export summaries
  • Existing audit or history rendering for finding workflow transitions
• Existing pattern(s) to extend:
  • Findings lifecycle contract from Spec 111
  • Risk-acceptance validity semantics from Spec 154
  • Operator-language and reason-translation foundations from Specs 156, 157, 161, and 214
• Shared contract / presenter / builder / renderer to reuse:
  • Reuse the existing findings workflow lifecycle as the primary status layer
  • Reuse the existing findings list and detail surface families as the primary operator surfaces
  • Reuse existing findings-derived summary and reporting consumers as downstream readers of the new outcome taxonomy rather than inventing a second summary path
• Why the existing shared path is sufficient or insufficient: The existing findings lifecycle is sufficient as the main status layer and should remain unchanged. It is insufficient on its own because status plus free-form reason text does not separate operator-resolved, system-verified, and non-remediation closure outcomes in a stable way.
• Allowed deviation and why: none. Read-only reporting consumers may compress the wording for stakeholder readability, but they must preserve the same taxonomy and bucket boundaries as the operator surfaces.
• Consistency impact: Resolve, close, and reopen labels; modal help text; default-visible terminal outcome summaries; filters; audit prose; and review or export buckets must all use the same canonical outcome language.
• Review focus: Reviewers must confirm that one structured taxonomy drives actions, detail summaries, filters, audit copy, and reporting rollups, and that no page-local synonym or free-text-only outcome path remains the primary source of meaning.

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
Tenant findings list and grouped bulk actions	yes	Native Filament resource table, grouped actions, filters, and existing shared findings primitives	Same findings workflow family as Spec 219, 221, 222, 224, and 225	workflow status, terminal outcome, verification meaning, risk-governance validity	no	Existing queue surface only; no new queue
Finding detail and terminal action modals	yes	Native Filament record page, infolist or detail primitives, and existing action modals	Same findings workflow family as the tenant list	workflow status, terminal outcome, verification meaning, audit-facing summary	no	Existing detail surface only; no new detail shell

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
Tenant findings list and grouped bulk actions	Primary Decision Surface	A tenant operator decides how an open finding should end and later scans whether terminal findings were resolved, verified, or administratively closed	Lifecycle status, severity, due state, owner, assignee, terminal outcome summary, and verification meaning for terminal rows	Full evidence, raw payloads, audit trail, and exception history after opening the finding	Primary because this is where operators scan and route work at backlog scale	Follows the findings workflow instead of forcing report-first reconstruction	Removes the need to open each terminal finding just to learn whether it was actually fixed, only claimed fixed, or closed as non-actionable
Finding detail and terminal action modals	Secondary Context Surface	A tenant operator confirms the correct terminal meaning for one finding before resolving, closing, or reopening it	Finding summary, current workflow state, current outcome summary, exception validity when relevant, and the exact action choice	Extended evidence, history, and full audit context	Secondary because it resolves one case after the list already identified the record	Preserves the single-finding workflow without inventing a separate governance case page	Avoids cross-page reconstruction when choosing between remediation, non-actionable closure, and reopen paths

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
Tenant findings list and grouped bulk actions	List / Table / Bulk	Workflow queue / list-first resource	Open a finding or apply a bounded terminal action	Finding	required	Structured More action group and grouped bulk actions	Existing dangerous actions remain grouped and confirmed where already required	/admin/t/{tenant}/findings	/admin/t/{tenant}/findings/{finding}	Tenant context, severity, due state, workflow filters, terminal outcome filters	Findings / Finding	Whether a terminal finding is resolved pending verification, verified cleared, closed for a non-remediation reason, or governed accepted risk	none
Finding detail and terminal action modals	Record / Detail / Actions	View-first operational detail	Resolve, close, or reopen one finding with the correct meaning	Finding	N/A - detail surface	Structured existing header actions and bounded transition modals	Existing dangerous actions remain grouped and confirmed	/admin/t/{tenant}/findings	/admin/t/{tenant}/findings/{finding}	Tenant breadcrumb, workflow status, severity, outcome summary, and risk-governance context	Findings / Finding	Why this finding is terminal right now and whether that terminal state is operator-declared, system-confirmed, or administratively closed	none

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
Tenant findings list and grouped bulk actions	Tenant operator or tenant manager	Route findings to the correct terminal meaning and scan the existing backlog honestly	Workflow queue	Was this finding fixed, only marked fixed, system-confirmed clear, or closed as non-actionable?	Severity, lifecycle state, due state, owner, assignee, terminal outcome summary, and verification summary for terminal findings	Raw evidence, provider details, long audit history, and related run metadata	lifecycle, severity, terminal outcome, verification meaning, risk-governance validity	TenantPilot only	Open finding, Resolve, Close, Reopen	Risk accept remains dangerous and governed separately; existing dangerous transitions stay confirmed
Finding detail and terminal action modals	Tenant operator or tenant manager	Choose the correct terminal path for one finding and verify current terminal meaning	Detail/action surface	Am I resolving this issue, confirming it was later cleared, closing it as non-actionable, or reopening it because the issue persists?	Finding summary, current state, current terminal outcome summary, current exception validity when relevant, and the next transition choices	Raw evidence payloads, historical audit entries, and related governance context	lifecycle, terminal outcome, verification meaning, risk-governance validity	TenantPilot only	Resolve, Close, Reopen	Request exception remains governed by Spec 154 and stays separately confirmed where required

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes - one bounded findings outcome taxonomy and verification interpretation contract over existing finding records, action forms, filters, audit entries, and reporting consumers
• New enum/state/reason family?: yes - one bounded resolve-reason family, one bounded close-reason family, one bounded reopen-reason family, and one bounded verification-outcome vocabulary
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Terminal findings can currently look similar even when the underlying meaning is very different, which weakens operator trust and corrupts reporting quality.
• Existing structure is insufficient because: The existing lifecycle from Spec 111 tells whether a finding is open or terminal, but not whether a terminal finding was remediated, only declared remediated, system-confirmed clear, or closed as non-actionable. Free-form reason text cannot safely carry that distinction across filters, reports, and audit views.
• Narrowest correct implementation: Preserve the existing lifecycle, add structured bounded reasons and one verification layer, and apply them only to existing findings actions and readers.
• Ownership cost: Ongoing maintenance for the bounded reason vocabularies, audit and reporting mapping discipline, and focused regression coverage.
• Alternative intentionally rejected: Introducing a new primary findings status such as verified, or a generic case-management framework, was rejected because both would import broader workflow complexity than the actual operator problem requires.
• Release truth: Current-release truth. This feature makes the current findings workflow and reporting honest now instead of preparing a speculative later platform.

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: Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: The proving burden is operator-visible and report-visible semantics on existing findings workflow surfaces. Focused feature coverage is sufficient to prove structured terminal-action behavior, verification or reopen behavior, filter rollups, audit copy, and downstream summary meaning without requiring browser or heavy-governance tests.
• New or expanded test families: Add focused finding transition tests for structured resolve, close, and reopen reasons; finding detail and list rendering tests for terminal-outcome summaries; filter and reporting summary tests for distinct terminal buckets; and audit-entry tests for structured outcome keys.
• Fixture / helper cost impact: Moderate. Tests need open, resolved, closed, reopened, and risk-accepted findings; trusted detection or verification inputs for confirm-clear and recurrence cases; valid and invalid exception coverage; and mixed tenant-visibility scenarios for report consumers.
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament
• Standard-native relief or required special coverage: Ordinary feature coverage is sufficient, plus explicit proof that open-backlog defaults remain unchanged, that verified-cleared and operator-resolved outcomes stay distinct, and that review or export buckets do not collapse non-remediation closures into remediation outcomes.
• Reviewer handoff: Reviewers must confirm that the feature does not create a new primary findings status, that free-form text is no longer the primary reporting key, that risk-accepted findings remain governed by exception validity instead of merging into verified-clear semantics, and that the same taxonomy appears in actions, list filters, detail summaries, audit prose, and downstream rollups.
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingWorkflowServiceTest.php tests/Feature/Findings/FindingRecurrenceTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListFiltersTest.php tests/Feature/Filament/FindingResolvedReferencePresentationTest.php tests/Feature/Findings/FindingOutcomeSummaryReportingTest.php tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php

User Scenarios & Testing (mandatory)

User Story 1 - End a finding with the correct terminal meaning (Priority: P1)

As a tenant operator, I want bounded resolve and close reasons instead of free-form terminal outcomes, so that I can end a finding honestly and downstream reporting keeps the same meaning.

Why this priority: This is the smallest operator-visible slice and the source of all later reporting quality. If the transition itself stays ambiguous, no summary or report can fix the semantics afterward.

Independent Test: Can be fully tested by executing resolve and close transitions on open findings, then verifying that the workflow response, detail narrative, and terminal-outcome filters show the structured meaning without relying on free-form text.

Acceptance Scenarios:

1. Given an open finding, When an authorized operator resolves it as remediated work, Then the finding becomes terminal with the meaning Resolved pending verification rather than Closed.
2. Given an open finding, When an authorized operator closes it as False positive, Then the finding becomes closed and all operator surfaces show the non-remediation closure meaning rather than a remediation outcome.
3. Given an open finding, When an authorized operator closes it as Duplicate or No longer applicable, Then list filters and detail summaries use that canonical close reason instead of free-form prose.

---

User Story 2 - See whether a terminal finding was actually verified clear (Priority: P1)

As a reviewer or accountable owner, I want to distinguish operator-resolved findings from system-verified cleared findings, so that I can trust whether the issue was only declared fixed or later confirmed gone.

Why this priority: This is the roadmap's explicit unresolved gap. Without it, the product cannot honestly answer whether terminal findings are truly cleared or only awaiting verification.

Independent Test: Can be fully tested by resolving a finding, then simulating a later trusted verification-clear event and a later recurrence event, and verifying that one path becomes verified clear while the other reopens with a structured reason.

Acceptance Scenarios:

1. Given a finding is already resolved, When later trusted system evidence confirms that the issue is no longer present, Then the finding remains terminal and surfaces as Verified cleared rather than plain unresolved resolved wording.
2. Given a finding is already resolved, When later trusted system evidence shows the issue is present again, Then the finding reopens with a structured reopen reason and does not remain reported as verified clear.
3. Given a finding was system-cleared without an operator transition, When the finding is shown on detail or reporting surfaces, Then the product distinguishes that system-confirmed terminal outcome from a manually declared resolution.

---

User Story 3 - Filter and summarize terminal outcomes consistently (Priority: P2)

As a reviewer or report consumer, I want terminal findings filters and summaries to use one canonical taxonomy, so that review packs, exports, and list filters separate remediation outcomes from administrative closure outcomes.

Why this priority: Once transitions are honest, summaries must preserve that meaning. This is the smallest slice that makes the taxonomy operationally useful beyond the single record.

Independent Test: Can be fully tested by seeding mixed terminal findings and verifying that list filters and reporting consumers keep Resolved pending verification, Verified cleared, Closed as false positive, Closed as duplicate, Closed as no longer applicable, and governed Risk accepted in distinct buckets.

Acceptance Scenarios:

1. Given a tenant has terminal findings across multiple outcome meanings, When an operator filters or summarizes terminal findings, Then the buckets remain distinct instead of collapsing into one generic resolved or closed group.
2. Given a report or review summary consumes findings outcomes, When it renders terminal findings, Then operator-resolved pending verification and verified-cleared findings are counted separately.
3. Given an operator opens the default open findings queue, When no terminal-outcome filter is intentionally applied, Then the existing open-backlog behavior from Spec 111 remains unchanged.

Edge Cases

• A finding may be auto-cleared by trusted system evidence without a prior manual resolve action; that path must not be reported as operator-resolved.
• A finding in risk_accepted status without a currently valid governing exception must remain a separate governance-validity problem and must not be counted as verified clear.
• A manually reopened closed or risk_accepted finding must record an explicit reopen reason and must not inherit any prior verified-clear meaning.
• Domains that do not yet have trustworthy system verification signals must remain Resolved pending verification until such a signal exists; the product must not imply silent verification.
• Free-form notes may still exist as secondary context, but filters and reporting must not depend on note wording to determine terminal meaning.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no Microsoft Graph calls, no new long-running job, no new scheduler, and no new OperationRun. It changes how existing finding transitions, findings filters, detail summaries, audit entries, and findings-derived reporting consumers interpret terminal outcomes.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature introduces new bounded reason families and one bounded verification vocabulary because the current product truth cannot honestly separate operator-declared resolution from system-confirmed clearance or non-remediation closure. It reuses existing finding records and existing lifecycle statuses instead of adding a new entity or status family.

Constitution alignment (XCUT-001): The feature is cross-cutting within the findings workflow family. It must extend one shared outcome taxonomy across actions, detail, filters, audit prose, and reporting consumers rather than allowing each surface to invent local wording.

Constitution alignment (TEST-GOV-001): Focused feature tests are the narrowest sufficient proof. The tests must prove transition semantics, verification or reopen behavior, filter and reporting buckets, and audit-entry meaning. No browser or heavy-governance lane is justified.

Constitution alignment (RBAC-UX): The feature operates on tenant findings surfaces and downstream tenant-entitlement-filtered reporting consumers. Existing tenant-safe 404 versus 403 behavior remains unchanged. Non-members and cross-tenant viewers receive 404. In-scope users lacking the relevant finding transition capability receive 403 for protected mutations. Reporting consumers must not expose terminal-outcome counts or labels for unauthorized tenants.

Constitution alignment (BADGE-001): Findings workflow status remains the primary centralized status family. Any added terminal-outcome or verification emphasis must reuse centralized presentation rules and must not introduce page-local color semantics.

Constitution alignment (UI-FIL-001): The feature must use existing Filament table filters, grouped actions, detail surfaces, and action modals on the tenant findings resource. No custom badge markup, custom workflow shell, or page-local status component may be introduced.

Constitution alignment (UI-NAMING-001): The canonical operator-facing vocabulary is Resolve, Resolved pending verification, Verified cleared, Close, False positive, Duplicate, No longer applicable, and Reopen. The term risk accepted remains governed by Spec 154 and must not be used as a synonym for verified clearance or closure.

Constitution alignment (DECIDE-001): The tenant findings list remains the primary decision surface for scanning work and understanding terminal meaning at backlog scale. Finding detail remains the focused single-record decision context for choosing resolve, close, or reopen.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / HDR-001): This feature changes the meaning and form content of existing actions only. It does not add a second findings queue, a second detail page, or a second inspect model. Row click remains the primary inspect affordance on the list. Existing dangerous actions stay grouped and confirmed where already required.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): Direct mapping from status plus free-form text is insufficient because it cannot safely express terminal outcome meaning across operator surfaces and reports. This feature adds one bounded interpretation layer and must prove business consequences rather than only raw field storage.

Functional Requirements

• FR-001: The system MUST preserve the findings lifecycle statuses from Spec 111. This feature MUST NOT introduce a new primary workflow status solely to represent verified clearance.
• FR-002: The system MUST define one bounded findings outcome taxonomy that distinguishes at minimum: operator-resolved pending verification, system-verified cleared, and closed non-remediation outcomes.
• FR-003: The single-record and bulk Resolve actions MUST require a structured resolve reason from a canonical bounded list. Optional explanatory notes MAY remain secondary context but MUST NOT be the primary reporting key.
• FR-004: The single-record and bulk Close actions MUST require a structured close reason from a canonical bounded list that includes at minimum False positive, Duplicate, and No longer applicable.
• FR-005: The system MUST define a bounded reopen-reason family for manual and automatic reopen paths. It MUST distinguish at minimum recurrence after prior resolution from manual reassessment or verification failure.
• FR-006: A finding in resolved status MUST surface by default as Resolved pending verification until later trusted evidence confirms the issue is actually clear.
• FR-007: When later trusted system evidence confirms that a previously resolved issue is no longer present, the system MUST surface that finding as Verified cleared without requiring a new primary findings status.
• FR-008: When later trusted system evidence shows that a previously resolved issue persists or recurs, the system MUST reopen the existing finding with a structured reopen reason and MUST remove any verified-clear classification.
• FR-009: System-cleared findings that become terminal through trusted automation or detection logic MUST remain distinguishable from manually resolved findings on detail, filters, and reporting consumers.
• FR-010: Closed findings MUST remain semantically separate from remediation-complete outcomes. They MUST NOT be counted or presented as verified clear or remediated unless a future explicit feature changes that rule.
• FR-011: Findings in risk_accepted status MUST remain governed by exception validity semantics from Spec 154 and MUST NOT collapse into resolved, verified-cleared, or closed-non-remediation buckets.
• FR-012: Tenant findings list and detail surfaces MUST show default-visible terminal outcome summaries whenever a finding is not open. Operators MUST NOT need to inspect raw audit payloads to learn the primary terminal meaning.
• FR-013: Terminal findings filters MUST allow operators to distinguish at minimum Resolved pending verification, Verified cleared, False positive, Duplicate, No longer applicable, and Risk accepted when those outcomes are present in scope.
• FR-014: Existing open-backlog defaults for the tenant findings list, My Findings, and intake-oriented workflow surfaces MUST remain based on the open status set from Spec 111 and MUST NOT be widened or redefined by terminal-outcome semantics.
• FR-015: Findings-derived reporting, review, and export consumers that summarize findings outcomes MUST consume the canonical taxonomy instead of free-form reason text or local labels.
• FR-016: Reporting and review consumers MUST count operator-resolved pending verification separately from verified-cleared findings whenever both are present.
• FR-017: Audit or history entries for resolve, close, and reopen transitions MUST record the structured outcome key and readable operator copy so later reviewers can reconstruct terminal meaning without parsing free-form prose alone.
• FR-018: Existing manual reopen paths from resolved, closed, and risk_accepted MUST continue to exist per Spec 111, but they MUST now require an explicit reopen reason that makes the cause of reopening reviewable.
• FR-019: This feature MUST NOT introduce comments, attachments, a second workflow state store, or a new canonical findings queue.
• FR-020: This feature MUST NOT redefine the exception approval or validity model from Spec 154. It only consumes that validity model to keep risk_accepted semantically separate from other terminal outcomes.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Tenant findings list and grouped bulk actions	/admin/t/{tenant}/findings	No new header actions; existing filters gain terminal-outcome semantics	Full-row open into finding detail	Existing primary inspect behavior only; terminal actions remain inside the structured existing row or grouped action path	Existing grouped Resolve, Close, and Reopen flows now require structured reasons; other grouped actions remain unchanged and out of scope	Existing empty-state behavior remains; no new CTA required in this slice	n/a	n/a	Yes for resolve, close, and reopen transitions through existing audit paths	Action Surface Contract remains satisfied. No new queue, no second inspect affordance, no empty action groups, and no page-local action family introduced.
Finding detail and terminal action modals	/admin/t/{tenant}/findings/{finding}	Existing detail actions remain; updated actions in scope are Resolve, Close, and Reopen	Detail surface	Existing bounded detail actions only	n/a	n/a	Existing Resolve, Close, and Reopen action modals now require structured reasons and show canonical terminology	n/a	Yes for resolve, close, and reopen transitions through existing audit paths	UI-FIL-001 satisfied through existing native detail and action-modal primitives. No exemption needed.

Key Entities (include if feature involves data)

• Finding terminal outcome: The bounded operator-facing meaning of how a finding became terminal, distinct from the primary workflow status.
• Verification outcome: A bounded distinction between operator-declared resolution and later trusted system-confirmed clearance.
• Reopen reason: The bounded explanation for why a previously terminal finding re-entered the open workflow.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In acceptance review, an operator can identify from the tenant findings list or detail page whether a terminal finding is Resolved pending verification, Verified cleared, or closed for a non-remediation reason without opening raw audit detail.
• SC-002: 100% of covered transition tests show that resolve, close, and reopen actions persist structured outcome semantics and do not rely on free-form text as the primary meaning.
• SC-003: 100% of covered filter and reporting tests keep Resolved pending verification, Verified cleared, False positive, Duplicate, No longer applicable, and governed Risk accepted in distinct outcome buckets when present.
• SC-004: 100% of covered queue tests show that the default open findings backlog remains unchanged and excludes terminal findings regardless of their terminal-outcome bucket.

Assumptions

• Existing finding records and audit paths can carry the structured outcome metadata needed by this slice without introducing a new top-level entity.
• The first release limits Verified cleared semantics to finding families where the product already has trustworthy system evidence for clearance or recurrence.
• Free-form explanatory text may remain as optional secondary context, but it is not the canonical key for filters, summaries, or reports.
• Risk-acceptance validity continues to derive from the exception workflow defined in Spec 154.

Non-Goals

• Introduce a new primary findings status such as verified or confirmed_cleared.
• Add comments, decision logs, attachments, or case-note collaboration.
• Add external ticket handoff, team workboards, or a new personal queue.
• Redesign risk-acceptance approvals, expiry, or revocation semantics.
• Build a generic evidence-attestation engine or universal governance case framework.

Dependencies

• Spec 111 remains the source of truth for the core findings lifecycle, open-status defaults, and allowed reopen paths.
• Spec 154 remains the source of truth for exception validity and governed risk_accepted semantics.
• Spec 155 remains the downstream review-layer consumer that should inherit this taxonomy instead of inventing local terminal buckets.
• Specs 156, 157, 161, and 214 remain the semantic foundation for operator-safe language and explanation patterns across outcome-bearing surfaces.