# Quickstart: Portfolio Triage Review State and Operator Progress

## Goal

Implement one lightweight, workspace-shared triage-review state so operators can mark current concerns as reviewed or follow-up needed, see changed-since-review detection, and track current affected-set progress without changing posture truth or reusing formal review artifacts.

## Implementation Sequence

1. Add the persisted triage-review core.
   - Create the `tenant_triage_reviews` migration.
   - Add `TenantTriageReview` and `TenantTriageReviewFactory`.
   - Add the minimal stored-state enum or cast for `reviewed` and `follow_up_needed` only.

2. Add deterministic fingerprinting and batch state resolution.
   - Create `TenantTriageReviewFingerprint` under `apps/platform/app/Support/PortfolioTriage/`.
   - Create `TenantTriageReviewStateResolver` that batch-loads active rows for a visible tenant set and combines them with existing backup-health and recovery-evidence truth.
   - Keep `not_reviewed` and `changed_since_review` derived only.

3. Add one canonical mutation path.
   - Create `TenantTriageReviewService` for `markReviewed()` and `markFollowUpNeeded()`.
   - Add one capability constant to `Capabilities` and enforce it through `UiEnforcement` plus server-side authorization.
   - Add bounded `AuditActionId` values and record lightweight audit entries through `AuditRecorder`.
   - Require a bounded pre-execution preview plus explicit confirmation on dashboard and registry review-state actions before the write executes.

4. Bind the new state into existing operator surfaces.
   - Extend `WorkspaceOverviewBuilder`, `WorkspaceSummaryStats`, and `WorkspaceNeedsAttention` to show current-set progress counts.
   - Extend `TenantResource` and `ListTenants` with a review-state column, all four review-state filters, mixed-family selection driven by the existing worst-first concern priority rules, and overflow actions.
   - Extend `TenantTriageArrivalContinuity` and `TenantDashboard` so triage-arrival sessions can mark reviewed or follow-up needed inline after preview-and-confirmation, while generic tenant browsing suppresses queue-like review-state actions.
   - Add one new badge domain or mapper for centralized review-state labels.

5. Add regression coverage.
   - Add fingerprint and resolver unit tests.
   - Add registry rendering, filtering, and action tests.
   - Add tenant-dashboard arrival-action tests.
   - Add workspace-overview progress-count tests.
   - Add RBAC view-versus-mutate tests.

## Suggested Test Files

- `apps/platform/tests/Unit/Support/PortfolioTriage/TenantTriageReviewFingerprintTest.php`
- `apps/platform/tests/Unit/Support/PortfolioTriage/TenantTriageReviewStateResolverTest.php`
- `apps/platform/tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php`
- `apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextTest.php`
- `apps/platform/tests/Feature/Filament/WorkspaceOverviewTriageReviewProgressTest.php`
- `apps/platform/tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php`
- `apps/platform/tests/Feature/Guards/ActionSurfaceContractTest.php`

## Existing Suites To Extend Or Keep Green

- `apps/platform/tests/Feature/Concerns/BuildsPortfolioTriageFixtures.php`
- `apps/platform/tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php`
- `apps/platform/tests/Feature/Filament/TenantDashboardArrivalContextTest.php`

## Minimum Verification Commands

Run all commands through Sail from `apps/platform`.

```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioTriage/TenantTriageReviewFingerprintTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/PortfolioTriage/TenantTriageReviewStateResolverTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDashboardArrivalContextTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewTriageReviewProgressTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac/TriageReviewStateAuthorizationTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantRegistryRecoveryTriageTest.php
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```

## Manual Acceptance Checklist

1. Open a tenant from a backup-health triage slice, trigger `Mark reviewed`, and confirm the preview shows concern family, current review state, target state, and `TenantPilot only` scope before the registry shows `Reviewed` while backup posture remains unchanged.
2. Open a tenant from a recovery-evidence triage slice, trigger `Mark follow-up needed`, confirm the preview, and verify the workspace progress summary increments the correct bucket.
3. Change the underlying concern truth for a previously reviewed tenant and confirm the UI shows `Changed since review` instead of the prior manual state.
4. Open the registry in a mixed-family slice and confirm the review-state badge names the selected concern family and follows the existing worst-first concern priority rules.
5. Exercise all four registry review-state filters (`not_reviewed`, `reviewed`, `follow_up_needed`, `changed_since_review`) and confirm each filter only returns the current visible affected tenants in that bucket.
6. Open a tenant directly without portfolio-triage context and confirm no triage-review actions or queue-like review-state progress copy appears.
7. Use a viewer without mutation capability and confirm review-state truth stays visible while mutation actions are disabled or fail with `403`.

## Deployment Notes

- One migration is required for `tenant_triage_reviews`.
- No new assets are expected.
- No `OperationRun` orchestration or `filament:assets` changes are required beyond the repo's normal deployment process.