# Quickstart: Finding Ownership Semantics Clarification

**Goal**: Implement the clarified finding owner versus assignee contract on existing findings surfaces without introducing new persistence, capabilities, or workflow services.

## 1. Prepare the workspace

```bash
cd apps/platform
./vendor/bin/sail up -d
```

## 2. Update responsibility semantics on the existing findings resource

Primary file:

- `app/Filament/Resources/FindingResource.php`

Expected implementation steps:

1. Keep owner and assignee as separate roles on list and detail surfaces.
2. Add a derived responsibility-state label, badge, or equivalent summary based on current owner/assignee presence.
3. Adjust filters or personal-work shortcuts so assignee-driven work and owner-driven accountability are not collapsed into one ambiguous view.
4. Keep `Exception owner` explicitly distinct anywhere exception context is rendered from a finding.
5. Add help text to assignment and exception-request forms so operators understand the semantic difference between the two owner concepts.

## 3. Keep responsibility truth local and derived

Supporting files:

- `app/Models/Finding.php`
- `app/Services/Findings/FindingWorkflowService.php`
- `app/Services/Findings/FindingExceptionService.php`
- `app/Services/Findings/FindingRiskGovernanceResolver.php`

Guidance:

1. Prefer a small local derived helper on `Finding` if it simplifies repeated responsibility-state checks.
2. Do not add a new enum, table, or presenter for responsibility state.
3. Keep `FindingWorkflowService::assign()` as the canonical mutation boundary.
4. If feedback or audit wording changes, distinguish owner-only, assignee-only, clear-owner, clear-assignee, and combined changes explicitly.
5. If next-action copy is updated, treat missing owner as the visible state `orphaned accountability` even when an assignee exists.

## 4. Add focused regression tests

Primary test targets:

- `tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php`
- `tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php`

Potential supporting edits:

- `tests/Feature/Findings/FindingWorkflowRowActionsTest.php`
- `tests/Feature/Findings/FindingWorkflowServiceTest.php`

Coverage checklist:

1. Owner-only finding renders as owned but unassigned.
2. Owner-plus-assignee finding renders both roles distinctly.
3. Assignee-only and both-null findings render as `orphaned accountability`.
4. Exception owner remains separately labeled from finding owner.
5. Responsibility updates preserve tenant-member validation and clearly report owner-only, assignee-only, clear-owner, clear-assignee, and combined changes.
6. Tenant-route authorization assertions use explicit panel selection when needed.

## 5. Verify the feature

Run the narrowest proof set first:

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Resources/FindingResourceOwnershipSemanticsTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingAssignmentAuditSemanticsTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## 6. Review expectations

Before moving to tasks or implementation review, confirm:

1. Owner, assignee, and exception owner mean one stable thing each across list, detail, and action flows.
2. Responsibility state is derived from existing fields only.
3. No new persistence, capability split, or presenter/framework layer was introduced.
4. Tenant-safe Filament behavior remains intact on both admin canonical and tenant-panel test paths.