1741b22203
- Add LEAN-001 to constitution after BIAS-001: forbids legacy aliases, migration shims, dual-write logic, and compatibility fixtures in a pre-production codebase - Add compatibility posture default block to spec template - Add pre-production compatibility check to agent instructions - Unify backup_set operation type to canonical backup_set.update - Remove all legacy backup_set.add_policies/remove_policies references - Add finding ownership semantics (responsibility/accountability labels) - Clean up roadmap.md and spec-candidates.md
81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 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. |