# Quickstart: Assignment Hygiene & Stale Work Detection

## Prerequisites

1. Start the local platform stack.

   ```bash
   cd apps/platform && ./vendor/bin/sail up -d
   ```

2. Work with a workspace that has at least two visible tenants, several open findings, and at least two tenant users.

3. Ensure at least one scenario can represent each hygiene state:
   - a finding assigned to a user who later loses tenant access or is soft-deleted
   - a finding left `in_progress` beyond the stale window without later workflow movement

4. Remember that `/admin/findings/hygiene` is a workspace-context canonical page, so tenant selection should not be required to open it.

## Automated Validation

Run formatting and the narrowest proving suites for this feature:

```bash
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsAssignmentHygieneReportTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsAssignmentHygieneClassificationTest.php tests/Feature/Findings/FindingsAssignmentHygieneOverviewSignalTest.php
```

## Manual Validation Flow

### 1. Confirm the canonical report opens in workspace context

1. Open `/admin/findings/hygiene` without selecting an active tenant.
2. Confirm the page opens as a workspace-context findings surface.
3. Confirm row drilldown still lands on the existing tenant finding detail page.

### 2. Validate broken-assignment detection

1. Start with an open assigned finding in a visible tenant.
2. Remove the assignee's tenant membership or soft-delete the assigned user.
3. Reload the hygiene report.
4. Confirm the finding appears once with `Broken assignment` and still shows owner context.

### 3. Validate stale in-progress detection

1. Start with an open finding moved to `In progress` more than seven days ago.
2. Ensure no later assignment or reopen workflow activity exists for that finding.
3. Reload the hygiene report.
4. Confirm the finding appears with `Stale in progress`.
5. Move a comparable finding to `In progress` recently or reassign it recently and confirm it does not appear as stale.
6. Reopen a comparable finding after it would otherwise qualify as stale and confirm it no longer appears as stale until seven days pass from the reopen activity.

### 4. Validate multi-reason and unique-count behavior

1. Prepare one finding that is both assigned to an unworkable assignee and stale in progress.
2. Reload the report and workspace overview.
3. Confirm:
   - the report shows one row with both reasons visible
   - the workspace overview counts one unique hygiene issue, not two separate rows

### 5. Validate overview discoverability

1. Open `/admin` with visible hygiene issues present.
2. Confirm the findings hygiene signal appears with one CTA into the report.
3. Confirm the signal description is a short summary derived from broken-assignment and stale-in-progress counts rather than an undefined severity ordering.
4. Open the CTA and verify the canonical report reflects the same visible issue truth.
5. Repeat the check with no visible hygiene issues and confirm the same signal remains visible in a calm state with zero issues and the canonical CTA into the report.

### 6. Validate tenant-prefilter and hidden-tenant safety

1. Open the report with an active tenant selected.
2. Confirm the report is prefiltered to that tenant while keeping the fixed hygiene scope.
3. If the prefilter hides issues that exist in other visible tenants, confirm the empty state explains that boundary and offers exactly one `Clear tenant filter` CTA.
4. Confirm hidden-tenant findings never appear in rows, counts, filter values, or empty-state hints.

## Reviewer Notes

- The feature is Livewire v4.0+ compatible and stays on existing Filament v5 primitives.
- Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`.
- No globally searchable resource behavior changes in this feature.
- No new destructive action is introduced on the hygiene report, so no new confirmation flow is required there.
- Asset strategy is unchanged: no new panel or shared assets, and the existing deploy `filament:assets` step remains sufficient.