# Tasks: Finding Ownership Semantics Clarification **Input**: Design documents from `/specs/219-finding-ownership-semantics/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/finding-responsibility.openapi.yaml, quickstart.md **Tests**: Tests are REQUIRED for this runtime behavior change. Use focused Pest feature and Livewire tests via Sail. **Test Governance Outcome**: `document-in-feature` **Operations**: No new `OperationRun` work is required for this feature; responsibility changes remain tenant-local audited writes. **RBAC**: No new authorization model is introduced; tasks must preserve existing tenant membership isolation, `404` versus `403` semantics, and canonical findings capability enforcement. **Filament UI Action Surfaces**: Tasks must keep `FindingResource` compliant with the Action Surface Contract while clarifying owner, assignee, and exception-owner semantics. **Filament UI UX-001**: Tasks must preserve the existing view-first findings detail layout and keep list/detail surfaces operator-first with explicit ownership truth. **Organization**: Tasks are grouped by user story so each story remains independently testable. ## Phase 1: Setup (Shared Context) **Purpose**: Align implementation with the approved responsibility contract and current codebase patterns before editing runtime code. - [X] T001 [P] Review the approved contract and story goals in specs/219-finding-ownership-semantics/spec.md, specs/219-finding-ownership-semantics/plan.md, and specs/219-finding-ownership-semantics/contracts/finding-responsibility.openapi.yaml - [X] T002 [P] Inspect the current responsibility surfaces in apps/platform/app/Filament/Resources/FindingResource.php, apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php, and apps/platform/app/Services/Findings/FindingExceptionService.php - [X] T003 [P] Review the existing findings workflow and Filament test patterns in apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php, apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php, and specs/219-finding-ownership-semantics/quickstart.md --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Establish the shared derived semantics and focused test harness that all user stories depend on. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T004 Implement the shared derived responsibility-state helper in apps/platform/app/Models/Finding.php so owner, assignee, and `orphaned_accountability` state rules come from one local source - [X] T005 [P] Create the focused Filament semantics test scaffold with explicit tenant-context setup in apps/platform/tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php - [X] T006 [P] Create the focused workflow/audit semantics test scaffold in apps/platform/tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php **Checkpoint**: Derived responsibility semantics and dedicated test entry points are ready; user story implementation can now begin. --- ## Phase 3: User Story 1 - Route accountable ownership clearly (Priority: P1) 🎯 MVP **Goal**: Make owner, assignee, and `orphaned accountability` visible on the existing findings list and detail surfaces. **Independent Test**: Load the tenant findings list and detail surfaces with owner-only, owner-plus-assignee, assignee-only, same-user, and both-null findings and verify the operator can tell accountability versus active assignment without leaving the resource, including one-interaction owner-work versus assignee-work isolation when personal-work cues are present. ### Tests for User Story 1 ⚠️ > **NOTE**: Add or update these tests first and ensure they fail before implementation. - [X] T007 [US1] Add list/detail rendering, personal-work filter isolation, and authorization assertions for owner-only, owner-plus-assignee, assignee-only, same-user, both-null, positive access, and deny-as-not-found cases in apps/platform/tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php ### Implementation for User Story 1 - [X] T008 [US1] Update the findings list hierarchy, responsibility summary, and personal-work filter behavior and naming in apps/platform/app/Filament/Resources/FindingResource.php so owner and assignee are explicitly distinct at first scan and can be isolated separately in one interaction each - [X] T009 [US1] Update the finding detail infolist and default-visible ownership sections in apps/platform/app/Filament/Resources/FindingResource.php so responsibility state and owner versus assignee meaning stay explicit on record view - [X] T010 [US1] Align `orphaned accountability` and next-step wording with the derived responsibility rules in apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php **Checkpoint**: User Story 1 should now make finding accountability and active assignment understandable from the existing findings resource alone. --- ## Phase 4: User Story 2 - Reassign work without losing accountability (Priority: P2) **Goal**: Let operators update assignee, owner, or both without ambiguous mutation feedback or audit wording. **Independent Test**: Perform responsibility updates on open findings and verify that owner-only, assignee-only, combined, clear-owner, and clear-assignee changes are differentiated in the action flow, response feedback, and audit-facing expectations. ### Tests for User Story 2 ⚠️ - [X] T011 [P] [US2] Add owner-only, assignee-only, combined, clear-owner, and clear-assignee change assertions in apps/platform/tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php - [X] T012 [P] [US2] Extend assignment action and service expectations for help text, member validation, explicit `403` versus `404` semantics, and unchanged-role preservation in apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php and apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php ### Implementation for User Story 2 - [X] T013 [US2] Update the row and bulk assignment actions in apps/platform/app/Filament/Resources/FindingResource.php with explicit owner/assignee help text and differentiated success feedback for owner-only, assignee-only, combined, clear-owner, and clear-assignee changes - [X] T014 [US2] Update the responsibility mutation wording and audit-facing classification in apps/platform/app/Services/Findings/FindingWorkflowService.php so assignment changes and clears no longer read as one ambiguous action **Checkpoint**: User Story 2 should now preserve the accountability contract when responsibility changes are made from existing findings actions. --- ## Phase 5: User Story 3 - Keep exception ownership separate (Priority: P3) **Goal**: Preserve a clear boundary between finding owner and exception owner wherever exception context appears on a finding surface. **Independent Test**: Open a finding with exception context and verify that finding owner remains distinct from exception owner on the detail surface and in the exception-request flow. ### Tests for User Story 3 ⚠️ - [X] T015 [US3] Extend apps/platform/tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php with exception-owner distinction and finding-context exception-request wording coverage ### Implementation for User Story 3 - [X] T016 [US3] Update the risk-governance display and exception-request action copy in apps/platform/app/Filament/Resources/FindingResource.php so `Exception owner` remains separate from finding owner on list/detail/action flows - [X] T017 [US3] Align finding-context exception-request wording and related feedback in apps/platform/app/Services/Findings/FindingExceptionService.php so exception ownership never reuses finding-owner semantics **Checkpoint**: User Story 3 should now keep exception governance ownership visibly separate from finding accountability. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Final verification, formatting, lane validation, and review readiness across all stories. - [X] T018 Reconcile any final lane or proof-depth changes against specs/219-finding-ownership-semantics/plan.md so the documented fast-feedback and confidence strategy still matches the implemented test surface and preserves the explicit `document-in-feature` outcome - [X] T019 Run focused Pest coverage with `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php tests/Feature/Findings/FindingWorkflowRowActionsTest.php tests/Feature/Findings/FindingWorkflowServiceTest.php` - [X] T020 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` for apps/platform/app/Models/Finding.php, apps/platform/app/Filament/Resources/FindingResource.php, apps/platform/app/Services/Findings/FindingWorkflowService.php, apps/platform/app/Services/Findings/FindingExceptionService.php, and apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php - [X] T021 Validate the final implementation against specs/219-finding-ownership-semantics/quickstart.md and record the active feature PR close-out entry as `Guardrail` with test-governance outcome `document-in-feature` --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies; can start immediately. - **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories. - **User Story 1 (Phase 3)**: Depends on Foundational completion; this is the MVP. - **User Story 2 (Phase 4)**: Depends on Foundational completion and is safest after User Story 1 because it refines the same findings resource/action surface. - **User Story 3 (Phase 5)**: Depends on Foundational completion and User Story 1 because exception-owner distinction builds on the clarified base ownership surface. - **Polish (Phase 6)**: Depends on completion of the desired user stories. ### User Story Dependencies - **US1**: No dependency on other stories; delivers the core operator truth. - **US2**: Depends on the shared derived responsibility contract from Phase 2 and integrates with the surfaces clarified in US1. - **US3**: Depends on the shared derived responsibility contract from Phase 2 and the explicit owner/assignee rendering from US1. ### Within Each User Story - Tests should be added or updated first and observed failing before implementation. - The shared `Finding` helper should remain the source for responsibility-state derivation. - Resource surface changes should land before service wording is finalized so copy and behavior stay aligned. - Story-specific verification should complete before moving to the next priority. ### Parallel Opportunities - T001, T002, and T003 can run in parallel. - T005 and T006 can run in parallel. - T011 and T012 can run in parallel. - After Phase 2, one contributor can work on US1 surface rendering while another prepares US2 audit semantics tests. --- ## Parallel Example: User Story 1 ```bash # Launch the shared ownership-surface work together after Phase 2: Task: "Add list/detail rendering and authorization assertions in apps/platform/tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php" Task: "Align orphaned accountability and next-step wording in apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php" ``` --- ## Parallel Example: User Story 2 ```bash # Launch mutation-behavior coverage together: Task: "Add owner-only, assignee-only, and combined change assertions in apps/platform/tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php" Task: "Extend assignment action and service expectations in apps/platform/tests/Feature/Findings/FindingWorkflowRowActionsTest.php and apps/platform/tests/Feature/Findings/FindingWorkflowServiceTest.php" ``` --- ## Parallel Example: User Story 3 ```bash # Launch exception-owner boundary work together: Task: "Extend apps/platform/tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php with exception-owner distinction coverage" Task: "Align finding-context exception-request wording in apps/platform/app/Services/Findings/FindingExceptionService.php" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational 3. Complete Phase 3: User Story 1 4. Validate the clarified owner/assignee semantics on list and detail surfaces 5. Stop and review before mutation-flow or exception-boundary refinements if needed ### Incremental Delivery 1. Ship the shared derived responsibility contract and visibility semantics in US1 2. Add differentiated reassignment feedback and audit wording in US2 3. Add exception-owner boundary protection in US3 4. Finish with focused Sail tests, Pint, and quickstart/guardrail validation ### Parallel Team Strategy With multiple contributors: 1. One contributor owns `FindingResource` surface clarity for US1 2. One contributor prepares the workflow/audit test surfaces for US2 3. One contributor prepares the exception-owner wording and verification path for US3 4. Recombine for focused regression runs, formatting, and guardrail close-out --- ## Notes - [P] tasks touch different files and can be executed in parallel. - User story labels map each task to the corresponding story in spec.md. - No migrations, no new capabilities, and no new abstraction layers are expected. - Preserve explicit tenant-context setup in Filament tests to avoid false routing regressions.