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
208 lines
13 KiB
Markdown
208 lines
13 KiB
Markdown
# 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.
|