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

# Tasks: Finding Outcome Taxonomy & Verification Semantics

**Input**: Design documents from `/specs/231-finding-outcome-taxonomy/`
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/finding-outcome-taxonomy.logical.openapi.yaml`, `quickstart.md`, `checklists/requirements.md`

**Tests**: Required. This feature changes runtime behavior in the tenant findings workflow, terminal-outcome presentation, and findings-derived review/report buckets, so Pest coverage must be added or updated in `apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php`, `apps/platform/tests/Feature/Findings/FindingRecurrenceTest.php`, `apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php`, `apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php`, `apps/platform/tests/Feature/Findings/FindingOutcomeSummaryReportingTest.php`, and `apps/platform/tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php`.
**Operations**: No new `OperationRun` is introduced. Existing `operation_run_id` provenance remains in scope only for trusted system clear and system reopen audit context; no new monitoring surface, queued notification surface, or run lifecycle contract may be introduced.
**RBAC**: This feature stays on the tenant `/admin/t/{tenant}/findings` plane plus existing tenant-scoped review consumers. The implementation must preserve non-member or cross-tenant `404`, in-scope missing-capability `403`, current server-side authorization in `FindingWorkflowService`, and existing tenant-safe review visibility semantics.
**UI / Surface Guardrails**: The existing tenant findings list, finding detail surface, and findings-derived review readers remain the only changed surfaces. This is a `standard-native-filament` slice with `review-mandatory` treatment; no new queue, no second detail shell, and no page-local outcome language may be introduced.
**Filament UI Action Surfaces**: `FindingResource` remains the only mutated Filament action surface, and `ReviewRegister` plus `TenantReviewResource` remain read-only consumers of the shared outcome semantics. No new page family, no second inspect model, no new global search entry point, and no empty action groups may be introduced.
**Badges**: Existing `BadgeCatalog` and `BadgeRenderer` semantics remain authoritative. Any terminal-outcome emphasis must extend shared finding presentation rules instead of adding page-local badge or color mappings.

**Organization**: Tasks are grouped by user story so each slice remains independently testable once the shared outcome seam exists. Recommended delivery order is `US1 -> US2 -> US3` because manual canonical reasons must stabilize before trusted system-clear semantics and downstream reporting buckets can converge.

## Test Governance Checklist

- [X] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- [X] New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit.
- [X] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented.
- [X] Planned validation commands cover the change without pulling in unrelated lane cost.
- [X] The declared surface test profile or `standard-native-filament` relief is explicit.
- [X] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

## Phase 1: Setup (Focused Findings Outcome Test Surfaces)

**Purpose**: Prepare the narrow regression surfaces that will prove manual terminal reasons, trusted verification, and findings-derived report buckets.

- [X] T001 [P] Extend the canonical workflow transition test scaffold in `apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php`
- [X] T002 [P] Extend the trusted recurrence and verification-failure scaffold in `apps/platform/tests/Feature/Findings/FindingRecurrenceTest.php`
- [X] T003 [P] Extend the terminal-outcome filter scaffold in `apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php`
- [X] T004 [P] Extend the findings detail presentation scaffold in `apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php`
- [X] T005 [P] Create the findings-derived summary bucket scaffold in `apps/platform/tests/Feature/Findings/FindingOutcomeSummaryReportingTest.php`
- [X] T006 [P] Extend the accepted-risk projection scaffold in `apps/platform/tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php`

**Checkpoint**: Focused findings workflow, presentation, and reporting test surfaces are ready for implementation work.

---

## Phase 2: Foundational (Blocking Canonical Outcome Seam)

**Purpose**: Establish the canonical outcome seam and pre-production reason-key normalization before any user story implementation begins.

**CRITICAL**: No user story work should begin until this phase is complete.

- [X] T007 Implement canonical resolve, close, and reopen reason-key families in `apps/platform/app/Models/Finding.php`
- [X] T008 Create the shared derived terminal-outcome mapper in `apps/platform/app/Support/Findings/FindingOutcomeSemantics.php`
- [X] T009 Update canonical historical-context interpretation in `apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php`
- [X] T010 Normalize canonical finding outcome fixture states in `apps/platform/database/factories/FindingFactory.php`
- [X] T011 Replace pre-production legacy reason keys in `apps/platform/app/Jobs/BackfillFindingLifecycleJob.php`
- [X] T012 Replace workspace-run legacy reason keys in `apps/platform/app/Jobs/BackfillFindingLifecycleTenantIntoWorkspaceRunJob.php`
- [X] T013 Add baseline canonical-outcome and audit-metadata contract assertions in `apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php`

**Checkpoint**: The canonical outcome seam exists, historical context is aligned to canonical keys, and all supporting fixtures and backfill paths use one pre-production key family.

---

## Phase 3: User Story 1 - End A Finding With The Correct Terminal Meaning (Priority: P1) 🎯

**Goal**: Give operators bounded resolve and close reasons so manual terminal outcomes are explicit instead of prose-driven.

**Independent Test**: Resolve and close open findings through the existing actions, then verify the workflow response, detail narrative, and terminal-outcome filters show `Resolved pending verification` or the correct administrative closure outcome without depending on free-form text.

### Tests for User Story 1

- [X] T014 [P] [US1] Add canonical manual resolve, close, risk-accept, and reopen validation plus audit-entry assertions in `apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php`
- [X] T015 [P] [US1] Add manual terminal-outcome detail assertions in `apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php`
- [X] T016 [P] [US1] Add manual terminal-outcome filter assertions in `apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php`

### Implementation for User Story 1

- [X] T017 [US1] Enforce canonical manual resolve, close, risk-accept, and reopen reason keys plus structured audit outcome copy in `apps/platform/app/Services/Findings/FindingWorkflowService.php`
- [X] T018 [US1] Align close-action labels, modal copy, and field contract in `apps/platform/app/Support/Ui/GovernanceActions/GovernanceActionCatalog.php`
- [X] T019 [US1] Replace single-record resolve and close inputs with canonical selections in `apps/platform/app/Filament/Resources/FindingResource.php`
- [X] T020 [US1] Replace bulk resolve and close inputs plus completion copy with canonical selections in `apps/platform/app/Filament/Resources/FindingResource.php`
- [X] T021 [US1] Surface manual terminal-outcome summaries on the finding detail surface in `apps/platform/app/Filament/Resources/FindingResource.php`

**Checkpoint**: User Story 1 is independently functional and operators can end findings with bounded manual terminal meanings.

---

## Phase 4: User Story 2 - See Whether A Terminal Finding Was Actually Verified Clear (Priority: P1)

**Goal**: Distinguish operator-declared resolution from later trusted verified-clear outcomes and structured recurrence reopen paths.

**Independent Test**: Resolve a finding manually, then apply trusted system clear and trusted recurrence paths and verify the result becomes `Verified cleared` or reopens with a structured reason without adding a new primary status.

### Tests for User Story 2

- [X] T022 [P] [US2] Add verified-clear transition and audit assertions for direct and post-manual system clears in `apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php`
- [X] T023 [P] [US2] Add recurrence and verification-failure reopen plus audit assertions in `apps/platform/tests/Feature/Findings/FindingRecurrenceTest.php`
- [X] T024 [P] [US2] Add verified-cleared detail presentation assertions in `apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php`

### Implementation for User Story 2

- [X] T025 [US2] Widen trusted system clear and reopen handling for verified-clear semantics and audit context in `apps/platform/app/Services/Findings/FindingWorkflowService.php`
- [X] T026 [US2] Normalize baseline auto-close system-clear reason keys in `apps/platform/app/Services/Baselines/BaselineAutoCloseService.php`
- [X] T027 [US2] Normalize Entra admin-role system clear and reopen reason keys in `apps/platform/app/Services/EntraAdminRoles/EntraAdminRolesFindingGenerator.php`
- [X] T028 [US2] Normalize permission-posture system clear and reopen reason keys in `apps/platform/app/Services/PermissionPosture/PermissionPostureFindingGenerator.php`
- [X] T029 [US2] Align recurrence-driven system reopen keys in `apps/platform/app/Jobs/CompareBaselineToTenantJob.php`
- [X] T030 [US2] Surface verified-cleared summaries and historical context on the finding resource in `apps/platform/app/Filament/Resources/FindingResource.php`

**Checkpoint**: User Story 2 is independently functional and terminal findings can now distinguish manual resolution from trusted verified clearance.

---

## Phase 5: User Story 3 - Filter And Summarize Terminal Outcomes Consistently (Priority: P2)

**Goal**: Apply one canonical taxonomy across queue filters, review readers, and findings-derived reporting buckets.

**Independent Test**: Seed mixed terminal outcomes and verify the queue filters, default open backlog, review views, executive-pack export cues, and findings-derived summaries keep `Resolved pending verification`, `Verified cleared`, administrative closures, and `Risk accepted` in distinct buckets.

### Tests for User Story 3

- [X] T031 [P] [US3] Add queue filter coverage for all canonical manual and verified terminal buckets plus default open-backlog regression assertions in `apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php`
- [X] T032 [P] [US3] Add findings-derived review, reporting, and export-summary bucket coverage in `apps/platform/tests/Feature/Findings/FindingOutcomeSummaryReportingTest.php`
- [X] T033 [P] [US3] Add accepted-risk governance-bucket separation coverage in `apps/platform/tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php`

### Implementation for User Story 3

- [X] T034 [US3] Implement terminal-outcome filters and default-visible queue summaries while preserving existing open-backlog defaults in `apps/platform/app/Filament/Resources/FindingResource.php`
- [X] T035 [US3] Reuse shared outcome semantics in review register findings summaries in `apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php`
- [X] T036 [US3] Reuse shared outcome semantics in tenant review outcome presentation and executive-pack export cues in `apps/platform/app/Filament/Resources/TenantReviewResource.php`

**Checkpoint**: User Story 3 is independently functional and downstream readers no longer invent their own terminal-outcome taxonomy.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Finish copy review, formatting, and the narrow proving workflow for the full feature.

- [X] T037 Review operator-facing outcome labels and modal helper copy in `apps/platform/app/Filament/Resources/FindingResource.php`
- [X] T038 Run formatting for the touched findings outcome files referenced in `specs/231-finding-outcome-taxonomy/quickstart.md` with `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- [X] T039 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingWorkflowServiceTest.php tests/Feature/Findings/FindingRecurrenceTest.php` and `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` for `apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php`, `apps/platform/tests/Feature/Findings/FindingRecurrenceTest.php`, `apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php`, `apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php`, `apps/platform/tests/Feature/Findings/FindingOutcomeSummaryReportingTest.php`, and `apps/platform/tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: Starts immediately and prepares the focused test surfaces.
- **Foundational (Phase 2)**: Depends on Setup and blocks all user story work until the canonical outcome seam and pre-production key normalization are in place.
- **User Story 1 (Phase 3)**: Depends on Foundational completion and is the first shippable behavior slice.
- **User Story 2 (Phase 4)**: Depends on User Story 1 because trusted verification semantics build on the manual canonical reason contract.
- **User Story 3 (Phase 5)**: Depends on User Story 1 and User Story 2 because queue filters and review/report buckets must consume the settled shared taxonomy.
- **Polish (Phase 6)**: Depends on all desired user stories being complete.

### User Story Dependencies

- **US1**: No dependencies beyond Foundational.
- **US2**: Requires the canonical manual reason contract from US1.
- **US3**: Requires the settled manual and trusted verification semantics from US1 and US2.

### Within Each User Story

- Write the story tests first and confirm they fail before implementation is considered complete.
- Keep `apps/platform/app/Support/Findings/FindingOutcomeSemantics.php` authoritative for derived terminal meaning instead of duplicating page-local mappings.
- Finish story-level verification before moving to the next priority slice.

### Parallel Opportunities

- `T001` through `T006` can run in parallel during Setup.
- `T014`, `T015`, and `T016` can run in parallel for User Story 1.
- `T022`, `T023`, and `T024` can run in parallel for User Story 2.
- `T031`, `T032`, and `T033` can run in parallel for User Story 3.

---

## Parallel Example: User Story 1

```bash
# User Story 1 tests in parallel
T014 apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php
T015 apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php
T016 apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php
```

## Parallel Example: User Story 2

```bash
# User Story 2 tests in parallel
T022 apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php
T023 apps/platform/tests/Feature/Findings/FindingRecurrenceTest.php
T024 apps/platform/tests/Feature/Filament/FindingResolvedReferencePresentationTest.php
```

## Parallel Example: User Story 3

```bash
# User Story 3 tests in parallel
T031 apps/platform/tests/Feature/Findings/FindingsListFiltersTest.php
T032 apps/platform/tests/Feature/Findings/FindingOutcomeSummaryReportingTest.php
T033 apps/platform/tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php
```

---

## Implementation Strategy

### MVP First

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Complete Phase 4: User Story 2.
5. Validate the feature against the focused US1 and US2 tests before widening to downstream review/report consumers.

### Incremental Delivery

1. Ship US1 to replace free-form terminal reasons with bounded manual outcomes.
2. Add US2 to close the roadmap gap between operator-declared resolution and trusted verified clearance.
3. Add US3 to converge queue filters and findings-derived review/report buckets on the same taxonomy.
4. Finish with copy review, formatting, and the focused validation pack.

### Parallel Team Strategy

1. One contributor can prepare the shared helper and canonical key normalization while another extends the focused test scaffolds.
2. After Foundational work lands, manual findings actions and trusted system-clear producer paths can progress in parallel across different files.
3. Review-register and tenant-review consumers can be updated in parallel once the settled outcome seam and queue filters are complete.

---

## Notes

- `[P]` tasks target different files and can be worked independently once upstream blockers are cleared.
- `[US1]`, `[US2]`, and `[US3]` map directly to the feature specification user stories.
- The suggested MVP scope is Phase 1 through Phase 4 because the feature promise is incomplete without the verified-clear slice.
- All implementation tasks above follow the required checklist format with task ID, optional parallel marker, story label where applicable, and exact file paths.