# Research: Finding Governance Health & Resolution Semantics Surface Hardening

## Decision 1: Reuse existing governance truth instead of introducing a new semantic layer

**Decision**: Drive surface hardening from existing `Finding.status`, `FindingException.current_validity_state`, `FindingRiskGovernanceResolver`, and centralized badge domains rather than introducing a new persisted governance-health field or a presenter framework.

**Rationale**: The codebase already distinguishes valid, expiring, expired, revoked, rejected, and missing-support governance states, and it already exposes warning messages through `FindingRiskGovernanceResolver`. The operator problem is primarily under-communication on major surfaces, not missing underlying truth. Reusing the current truth sources satisfies the constitution's proportionality and no-new-layer constraints.

**Alternatives considered**:
- Add a new stored `governance_health` field on findings: rejected because it would duplicate exception truth and require sync logic.
- Introduce a new presenter or explanation framework: rejected because this slice needs clearer surfaces, not another interpretation layer.

## Decision 2: Keep workflow lifecycle and governance validity as separate visible dimensions

**Decision**: Findings surfaces should show workflow lifecycle and governance validity as distinct operator-visible dimensions instead of collapsing them into a single synthetic super-status.

**Rationale**: A finding can be `risk_accepted` while governance is healthy, expiring, expired, revoked, or unsupported. A finding can also be `resolved` without proving permanent remediation. Separating lifecycle from governance validity prevents false calm and matches the constitution rule that distinct status dimensions should stay distinct when they matter.

**Alternatives considered**:
- Replace current states with one combined surface enum such as `accepted-risk-warning`: rejected because it would blur workflow truth and governance truth together.
- Leave lifecycle badges unchanged and hide governance only in detail: rejected because the list and summary surfaces are where prioritization happens.

## Decision 3: Harden finding detail by reordering existing infolist truth into a leading status zone

**Decision**: Implement the detail-page change as a leading status and governance zone built from existing infolist data, leaving raw identifiers, run links, diffs, and evidence in secondary sections.

**Rationale**: The current finding detail already contains most of the required truth, including status, severity, due date, owner, assignee, and risk-governance entries. The main change needed is information hierarchy. Reordering existing truth is narrower and safer than introducing a new detail-specific read model.

**Alternatives considered**:
- Build a separate read model or DTO for the view page: rejected because the current infolist already has the required fields.
- Leave the current section order and add more warnings lower on the page: rejected because it does not solve the 5 to 10 second operator-read requirement.

## Decision 4: Propagate governance attention to summary surfaces through existing DB-backed widget queries

**Decision**: Extend current tenant summary surfaces such as `NeedsAttention` and baseline-compare summary outputs with DB-backed aggregates for overdue findings, lapsed governance, and expiring governance instead of adding background jobs or a new tenant-governance dashboard.

**Rationale**: The dashboard widget and baseline-compare landing already compute DB-backed summaries without external calls. Adding a small set of operator-critical aggregates keeps these surfaces honest while preserving their glance-first character and avoiding a new subsystem.

**Alternatives considered**:
- Add scheduled reminder jobs or alerting in this slice: rejected because the spec explicitly leaves proactive automation to a follow-up spec.
- Create a dedicated governance-health dashboard: rejected because the current scope is surface hardening, not a new reporting domain.

## Decision 5: Communicate `resolved` and `closed` cautiously, with optional secondary observation context

**Decision**: Treat `resolved` and `closed` as historical workflow states in primary UI language, and only show `no longer observed` or similar context as secondary explanatory information when it can be derived from current truth.

**Rationale**: The spec's central risk is that operators may read `resolved` as technical proof. The safest narrow fix is copy and layout: make workflow meaning explicit and reserve any observation-based explanation for clearly secondary context.

**Alternatives considered**:
- Reinterpret `resolved` as `no longer observed` everywhere: rejected because it rewrites current workflow truth.
- Add a new persistence field to separate resolution origin immediately: rejected because the spec explicitly defers that to a follow-up if needed.

## Decision 6: Anchor testing in existing Livewire, Filament, Findings, and Badge suites

**Decision**: Extend the current Pest suites for findings list, finding detail, exception register, exception queue, dashboard widgets, baseline-compare summary, evidence integration, and badge semantics rather than creating a new presentation-only test framework.

**Rationale**: The repository already has strong coverage anchors for findings workflow, governance projection, exception lifecycle, needs-attention widgets, and baseline-compare explanation surfaces. Cross-surface consistency can be enforced most efficiently by extending those suites with operator-truth assertions.

**Alternatives considered**:
- Add screenshot-heavy UI snapshot coverage as the main protection: rejected because the business truth is semantic distinction, not pixel fidelity.
- Test a new intermediate presenter layer: rejected because the plan intentionally avoids creating one.