ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
0c78e3e1b0
TenantAtlas/specs/219-finding-ownership-semantics/quickstart.md
Ahmed Darrazi 1741b22203 docs: amend constitution to v2.7.0 (LEAN-001 pre-production lean doctrine) 
- 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
2026-04-20 19:53:04 +02:00

3.5 KiB
Raw Blame History

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

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:

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.