TenantAtlas/specs/189-portfolio-triage-review-state/quickstart.md

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.

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.