TenantAtlas/specs/219-finding-ownership-semantics/tasks.md

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.

• 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
• 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
• 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.

• 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
• T005 [P] Create the focused Filament semantics test scaffold with explicit tenant-context setup in apps/platform/tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php
• 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.

• 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

• 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
• 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
• 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 ⚠️

• T011 [P] [US2] Add owner-only, assignee-only, combined, clear-owner, and clear-assignee change assertions in apps/platform/tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php
• 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

• 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
• 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 ⚠️

• 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

• 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
• 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.

• 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
• 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
• 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
• 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

# 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

# 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

# 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.