TenantAtlas/specs/255-enforce-finding-creation-invariants/quickstart.md

Quickstart — Enforce Creation-Time Finding Invariants

Prereqs

• Docker running
• Laravel Sail dependencies installed
• Existing compare and generator feature fixtures available
• Existing tenant/workspace helpers available for targeted findings tests

Run locally after implementation

• Start containers: cd apps/platform && ./vendor/bin/sail up -d
• Use the normal repo baseline before running tests: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan migrate --no-interaction
• Run the focused validation suites for this slice:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareFindingsTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EntraAdminRoles/EntraAdminRolesFindingGeneratorTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PermissionPosture/PermissionPostureFindingGeneratorTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingRecurrenceTest.php tests/Feature/Findings/FindingAutomationWorkflowTest.php tests/Feature/Findings/FindingWorkflowServiceTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/MyWorkInboxTest.php tests/Feature/Findings/FindingsIntakeQueueTest.php tests/Feature/Rbac/BaselineCompareMatrixAuthorizationTest.php tests/Feature/EntraAdminRoles/AdminRolesSummaryWidgetTest.php
• Format any implementation changes: export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

The two additional commands are the only bounded adjacent proof beyond the three writer suites. They cover shared recurrence/workflow semantics plus unchanged downstream consumer and trigger-authorization contracts.

Manual smoke after implementation

1. Trigger one baseline compare drift finding and confirm the newly created record appears immediately usable on /admin/t/{tenant}/findings, including due-state and seen-history cues where current UI already renders them.
2. Trigger one permission posture and one Entra admin roles finding and confirm the first persisted record has the expected lifecycle-ready fields without any maintenance action.
3. Resolve an in-scope finding, re-observe the same issue, and confirm the same finding identity reopens with refreshed due or SLA truth and existing history retained.
4. Re-run the same baseline compare operation identity and confirm times_seen does not double count on retry.
5. Review the diff and confirm no file under apps/platform/database/migrations/ changed and no new repair surface, capability, or operator-facing workflow branch was introduced.

Notes

• Filament v5 remains on Livewire v4.0+ in this repo; this feature does not add or redesign an operator-facing Filament surface.
• FindingResource already has a view page, so there is no new global-search compliance work.
• No new destructive action is planned; existing destructive-like findings actions stay outside this slice and keep their current confirmation and authorization behavior.
• No panel or provider change is planned; apps/platform/bootstrap/providers.php remains the relevant provider-registration location for Filament work in Laravel 12.
• No asset change is expected, so there is no additional filament:assets deployment work for this slice.
• This prep package intentionally leaves repo-wide agent-context regeneration outside scope so changes stay inside specs/255-enforce-finding-creation-invariants/ only.