TenantAtlas/specs/254-remove-acknowledged-compat/research.md

Research — Remove Legacy Acknowledged Finding Status Compatibility

Date: 2026-04-29
Spec: 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.