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

Research: Finding Outcome Taxonomy & Verification Semantics

Decision 1: Preserve the primary findings status family and derive verification meaning

• Decision: Keep the existing Finding lifecycle statuses (new, triaged, in_progress, reopened, resolved, closed, risk_accepted) and derive Resolved pending verification versus Verified cleared from bounded canonical reason keys plus existing audit history.
• Rationale: App\Models\Finding already defines open and terminal status sets, FindingWorkflowService and its tests assume that matrix, and the spec explicitly forbids a new primary status just to represent verification. The narrowest viable change is to make terminal meaning derive from bounded reason families instead of expanding the workflow state machine.
• Alternatives considered:
  • Add a new verified status: rejected because it widens queue semantics, transition rules, and operator routing for a problem that can remain derived.
  • Add a second outcome table or reporting-only register: rejected because there is no new independent source of truth or lifecycle to persist.

Decision 2: Reuse existing resolved_reason and closed_reason fields, and keep reopen reasons in audit metadata

• Decision: Reuse the existing resolved_reason and closed_reason columns as canonical stable keys, and keep reopened_reason as structured audit metadata instead of adding a new reopened_reason column.
• Rationale: FindingWorkflowService already writes resolved_reason, closed_reason, system_origin, and reopened_reason into current record state and audit metadata. The service only needs to stop accepting arbitrary free-form text and instead validate against bounded key families. This keeps the implementation inside existing persistence truth and matches the spec's no-new-entity posture.
• Alternatives considered:
  • Add a new JSON outcome payload on findings: rejected because it would create a second semantic store for data already represented by existing columns and audit events.
  • Keep free-form textarea input as the primary meaning: rejected because list filters, review consumers, and audit readers cannot safely depend on prose.

Decision 3: Use one findings-local semantics helper rather than page-local mappings or a generic framework

• Decision: Add one findings-local helper, such as App\Support\Findings\FindingOutcomeSemantics, to convert current finding truth into terminal-outcome labels, verification state, and report buckets.
• Rationale: Multiple readers already need the same meaning: FindingResource, FindingRiskGovernanceResolver, ReviewRegister, TenantReviewResource, and findings-derived summary or projection code. A single findings-local helper is justified because at least two real consumers already exist, while a generic governance-wide taxonomy engine would be broader than the current release truth.
• Alternatives considered:
  • Keep logic inside FindingResource only: rejected because review and reporting consumers would immediately drift.
  • Build a broad cross-domain governance taxonomy framework: rejected because the current scope is bounded to findings terminal outcomes.

Decision 4: Use canonical reason keys to make system-cleared outcomes row-visible, and keep audit history for path reconstruction

• Decision: Treat canonical resolve keys as the row-level source for pending-versus-verified meaning. Manual resolve uses a bounded operator key such as remediated, while trusted system-clear reasons continue to use bounded system keys such as no_longer_drifting, permission_granted, permission_removed_from_registry, role_assignment_removed, and ga_count_within_threshold.
• Rationale: resolveBySystem() currently writes system_origin into audit metadata, but that audit-only flag is not enough for list filters or report buckets. Using canonical resolve keys as the current-row truth makes terminal meaning queryable without adding a new column, while the audit trail still records whether the final verified-clear state came from a direct system clear or a later confirmation after manual resolution.
• Alternatives considered:
  • Add a persisted verification_state column: rejected because the same meaning can be derived from the current status plus canonical reason keys.
  • Depend only on audit metadata for verified-clear meaning: rejected because list filters and read models should not need audit log reconstruction to classify current records.

Decision 5: Widen the system resolve path narrowly enough to confirm already resolved findings

• Decision: Allow the system-clear path to update a finding that is already resolved when the purpose is to move it from operator-declared resolution to a trusted verified-clear reason.
• Rationale: FindingWorkflowService::resolveBySystem() currently only accepts open findings, which is too narrow for the spec requirement that a previously resolved finding may later be confirmed clear by trusted evidence. The narrowest fix is to widen the system path for this exact case instead of adding a new status or a second persistence field.
• Alternatives considered:
  • Force a reopen-then-resolve cycle to represent verification: rejected because it would falsify the user-visible history and generate unnecessary workflow churn.
  • Add a second workflow method dedicated to verification with separate persisted state: rejected because it adds more surface than the current release needs.

Decision 6: Keep risk_accepted separate from remediation and verification semantics

• Decision: Preserve risk_accepted as its own terminal class governed by exception validity, not as a close reason and not as a verified-clear outcome.
• Rationale: FindingRiskGovernanceResolver already interprets accepted_risk and exception validity separately, and the spec requires Spec 154 semantics to remain authoritative. This means the outcome taxonomy should expose risk_accepted as a distinct terminal bucket while continuing to compute governance validity independently.
• Alternatives considered:
  • Fold risk_accepted into generic closed outcomes: rejected because that would hide governance validity consequences.
  • Treat valid accepted risk as verified clear: rejected because risk acceptance is an administrative governance decision, not proof of remediation.

Decision 7: Replace existing ad hoc keys in one pass instead of preserving aliases

• Decision: Replace existing ad hoc or legacy-like reason strings inside current code, factories, and backfill jobs during implementation rather than preserving alias maps.
• Rationale: The repository is still pre-production, LEAN-001 explicitly rejects compatibility shims when there is no live production data, and current code already shows several ad hoc reason strings such as duplicate, accepted_risk, and consolidated_duplicate. The cleanest implementation is one canonical bounded family, updated everywhere in the same slice.
• Alternatives considered:
  • Maintain alias translation tables for old and new reason keys: rejected because it adds avoidable compatibility machinery.
  • Leave existing reasons mixed and normalize only in the UI: rejected because backend tests, report buckets, and audit semantics would remain ambiguous.