TenantAtlas/specs/221-findings-operator-inbox/quickstart.md

Quickstart: Findings Operator Inbox V1

Goal

Validate that /admin/findings/my-work gives the current user one trustworthy assigned-findings queue across visible tenants, and that /admin exposes a matching Assigned to me signal with one CTA into the inbox.

Prerequisites

1. Start Sail if it is not already running.
2. Use a test user who is a member of one workspace and at least two tenants inside that workspace.
3. Seed or create findings for these cases:
   • assigned open finding in tenant A
   • assigned overdue finding in tenant B
   • assigned reopened finding in tenant A

• assigned ordinary finding without a due date
• owner-only open finding where the user is not assignee
• assigned terminal finding
• assigned finding in a tenant the user is no longer entitled to inspect
• assigned finding in a tenant where the user remains a member but no longer has findings visibility capability

4. Ensure the workspace overview at /admin is reachable for the acting user.

Focused Automated Verification

Run formatting first:

cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Then run the focused proving set:

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/Findings/MyWorkInboxTest.php \
  tests/Feature/Authorization/MyWorkInboxAuthorizationTest.php \
  tests/Feature/Dashboard/MyFindingsSignalTest.php

Then run the required route-alignment regression for the workspace shell CTA:

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/Filament/WorkspaceOverviewNavigationTest.php

Manual Validation Pass

1. Workspace overview signal

Open /admin.

Confirm that:

• the page shows an Assigned to me signal,
• the signal exposes visible open count and overdue count,
• the wording stays calm only when both counts are zero,
• and the CTA is labeled Open my findings.

2. Canonical inbox route

Open /admin/findings/my-work.

Confirm that:

• the page title and copy use finding-first vocabulary,
• rows show tenant, finding summary, severity, lifecycle, and due urgency,
• owner context is shown when owner differs from assignee,
• the page reflects fixed assigned-to-me scope and summary counts that match the visible rows,
• and no queue-level mutation actions appear.

3. Assignee versus owner boundary

With fixtures where the acting user is owner-only on one finding and assignee on another:

Confirm that:

• the assignee row is visible,
• the owner-only row is absent,
• a finding where the user is both owner and assignee remains visible,
• and owner context is shown only when it differs from the assignee.

4. Active tenant prefilter

Set an active tenant context before opening the inbox.

Confirm that:

• the queue defaults to that tenant,
• the personal assignment scope remains fixed,
• the applied scope reflects that tenant-prefilter source correctly,
• a Clear tenant filter affordance is available,
• summary counts continue to match the visible rows,
• and clearing the tenant filter returns the queue to all visible tenants.

5. Hidden-tenant and capability suppression

Remove the acting user's entitlement from one tenant that still contains assigned findings, and remove findings visibility capability from another tenant where membership still remains.

Confirm that:

• those findings disappear from the inbox,
• they do not contribute to the workspace signal,
• neither tenant appears as a filter value or empty-state hint,
• and protected destinations still reject in-scope users without findings visibility.

6. Urgency ordering

With ordinary, reopened, overdue, and undated assigned findings:

Confirm that:

• overdue work appears ahead of reopened and ordinary work,
• reopened non-overdue work appears ahead of ordinary work,
• within the same urgency bucket, due-dated rows appear ahead of undated rows,
• reopened context is visible,
• and terminal findings do not appear.

7. Detail continuity

Open a row from the inbox.

Confirm that:

• the destination is the existing tenant finding detail route,
• the tenant scope is correct,
• and the page offers a Back to my findings return path.

8. Empty-state behavior

Validate two empty states:

• no visible assigned work anywhere
• no rows only because the active tenant prefilter narrows the queue

Confirm that:

• the zero-visible-work branch stays calm and offers a clear fallback CTA,
• the first state's CTA opens tenant findings when active tenant context exists and /admin/choose-tenant when it does not,
• the second state explains the tenant boundary instead of claiming there is no work anywhere,
• the second state's CTA clears the tenant prefilter back to all visible tenants,
• and neither state leaks hidden tenant information.

Final Verification Notes

• The inbox is read-first only. Assignment and workflow mutations stay on tenant finding detail.
• The workspace overview signal must remain a signal, not a second queue.
• If a reviewer can infer hidden tenant work from counts, filter options, or empty-state copy, treat that as a release blocker.