# Research — Remove Legacy Acknowledged Finding Status Compatibility

**Date**: 2026-04-29  
**Spec**: [spec.md](spec.md)

This document records the repo-grounded planning decisions for the acknowledged-compatibility cleanup slice. All decisions assume the current pre-production LEAN-001 posture.

## Decision 1 — Remove acknowledged semantics at shared seams, not through page-local relabeling

**Decision**: Delete productive `acknowledged` compatibility from the shared findings seams that currently define status truth, query truth, badge vocabulary, filter vocabulary, workflow eligibility, and capability language. Do not treat this as a page-local label replacement.

**Rationale**:
- The drift is cross-surface today: `Finding::STATUS_ACKNOWLEDGED`, `Finding::openStatusesForQuery()`, `FilterOptionCatalog`, `BadgeCatalog`, `FindingWorkflowService`, `Capabilities::TENANT_FINDINGS_ACKNOWLEDGE`, and multiple summary consumers all preserve the old vocabulary.
- A list-only or badge-only rename would leave summary counts, disabled helper text, and RBAC wording inconsistent.
- XCUT-001 requires converging on the existing shared path instead of adding local exceptions.

**Evidence**:
- `apps/platform/app/Models/Finding.php`
- `apps/platform/app/Services/Findings/FindingWorkflowService.php`
- `apps/platform/app/Support/Filament/FilterOptionCatalog.php`
- `apps/platform/app/Support/Badges/Domains/FindingStatusBadge.php`
- `apps/platform/app/Support/Auth/Capabilities.php`
- `apps/platform/app/Services/Auth/RoleCapabilityMap.php`

**Alternatives considered**:
- Relabel `acknowledged` to `triaged` only on findings pages.
  - Rejected: shared queries, summaries, and capability guidance would still preserve conflicting truth.
- Keep a read-side compatibility mapper indefinitely.
  - Rejected: LEAN-001 forbids preserving a pre-production legacy branch without a current-release need.

## Decision 2 — Treat stale acknowledged rows and columns as pre-production residue, not as a runtime compatibility contract

**Decision**: Keep the cleanup code-only by default. Remove productive semantics first and do not add migration shims, fallback readers, or preserved UI labels just because `acknowledged_at` or `acknowledged_by_user_id` columns still exist locally.

**Rationale**:
- The repo is explicitly pre-production, and LEAN-001 prefers replacement or deletion over historical compatibility behavior.
- The current problem is active workflow semantics in code and tests, not an unavoidable database constraint.
- The narrowest correct implementation is to stop writing, querying, and presenting `acknowledged` as current findings truth.

**Evidence**:
- `apps/platform/app/Models/Finding.php`
- `.specify/memory/constitution.md` (LEAN-001, PERSIST-001)
- `docs/product/spec-candidates.md`

**Alternatives considered**:
- Add a migration or fallback reader now.
  - Rejected: widens scope into persistence work not justified by current release truth.
- Preserve `legacy acknowledged` UI labels until later.
  - Rejected: keeps the removed semantics productized.

## Decision 3 — Keep findings-derived review, report, and support-diagnostic consumers in scope where they surface current open-work truth

**Decision**: Include review/report and support-diagnostic consumers in this cleanup only where they derive current findings-open counts, disclosure text, or issue grouping from the same shared status helpers as canonical summaries.

**Rationale**:
- Repo truth shows `TenantReviewSectionFactory` and `SupportDiagnosticBundleBuilder` still depend on acknowledged-aware status logic.
- Leaving those consumers out would preserve productive status drift even if the findings register and canonical `/admin` summaries were cleaned.
- This remains bounded because the slice is limited to findings-derived open-work semantics, not broader review-pack, evidence, or diagnostic redesign.

**Evidence**:
- `apps/platform/app/Services/TenantReviews/TenantReviewSectionFactory.php`
- `apps/platform/app/Support/SupportDiagnostics/SupportDiagnosticBundleBuilder.php`
- `apps/platform/app/Support/CustomerHealth/WorkspaceHealthSummaryQuery.php`
- `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php`

**Alternatives considered**:
- Defer review/report and diagnostics entirely.
  - Rejected: current productive consumers would still present split workflow truth.
- Broaden into review-pack or diagnostic domain redesign.
  - Rejected: outside the smallest cleanup slice.

## Decision 4 — Keep non-finding acknowledgement domains explicitly out of scope

**Decision**: Do not rename or remove acknowledgement semantics outside the findings domain, including verification-check acknowledgement, onboarding-verification acknowledgement, and restore impact acknowledgement.

**Rationale**:
- Those domains carry different user intent and do not prove that findings status compatibility must remain.
- Mixing them into this slice would widen terminology cleanup into unrelated workflows.
- The spec already depends on maintaining bounded ownership and avoiding accidental cross-domain churn.

**Evidence**:
- `apps/platform/app/Services/Verification/VerificationCheckAcknowledgementService.php`
- `apps/platform/app/Filament/Support/VerificationReportViewer.php`
- `apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`
- `apps/platform/app/Filament/Resources/RestoreRunResource.php`

**Alternatives considered**:
- Normalize every `acknowledge*` term in the repo at once.
  - Rejected: too broad and not required for the findings cleanup to be correct.

## Decision 5 — Keep validation in focused Feature, Unit, and retained guard lanes only

**Decision**: Prove the cleanup with focused findings workflow tests, focused summary-consumer tests, focused capability cleanup tests, and the already-retained heavy-governance guard coverage. Do not add browser coverage.

**Rationale**:
- The business risk is shared-seam drift, not browser choreography or async execution.
- The repo already has meaningful findings, generator, summary, and guard test families that can be narrowed or rewritten.
- TEST-GOV-001 prefers the smallest proving lane mix that guards business truth.

**Evidence**:
- `apps/platform/tests/Feature/PermissionPosture/PermissionPostureFindingGeneratorTest.php`
- `apps/platform/tests/Feature/EntraAdminRoles/EntraAdminRolesFindingGeneratorTest.php`
- `apps/platform/tests/Feature/Findings/FindingsIntakeQueueTest.php`
- `apps/platform/tests/Feature/Guards/NoAdHocStatusBadgesTest.php`
- `apps/platform/tests/Feature/Guards/FilamentTableStandardsGuardTest.php`

**Alternatives considered**:
- Add browser smoke coverage.
  - Rejected: low additional value for this cleanup.
- Preserve broad acknowledged-compatibility fixture families.
  - Rejected: would keep the removed semantics alive in the suite.

## Decision 6 — Remove the stale findings capability alias instead of translating it forever

**Decision**: Delete `tenant_findings.acknowledge` from the canonical capability registry and role mappings, and converge disabled helper text and authorization expectations on the surviving findings permissions.

**Rationale**:
- The acknowledged alias keeps RBAC language inconsistent with the canonical triage action.
- Capability drift is part of the user-visible problem in this slice, not a separate concern.
- RBAC-UX requires server-side truth to stay on the canonical capability set, not parallel aliases.

**Evidence**:
- `apps/platform/app/Support/Auth/Capabilities.php`
- `apps/platform/app/Services/Auth/RoleCapabilityMap.php`
- `apps/platform/app/Policies/FindingPolicy.php`

**Alternatives considered**:
- Keep the alias as an undocumented backward-compatibility seam.
  - Rejected: preserves the exact semantics blocker this feature is intended to remove.