# Feature Specification: Portfolio Triage Review State and Operator Progress

**Feature Branch**: `[189-portfolio-triage-review-state]`  
**Created**: 2026-04-10  
**Status**: Draft  
**Input**: User description: "Spec 189 - Portfolio Triage Review State / Operator Progress Tracking"

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**:
  - `/admin` as the workspace overview where backup-attention and recovery-attention surfaces gain current-set progress semantics
  - `/admin/tenants` as the canonical portfolio triage list that shows review state, supports review-state filtering, and preserves concern-family focus
  - `/admin/tenants/{tenant}` as the existing tenant-registry inspect route that remains the canonical registry detail path
  - `/admin/t/{tenant}` as the canonical tenant dashboard arrival surface where the triage continuity block shows current review state and exposes lightweight progress actions
  - `/admin/t/{tenant}/backup-sets` and `/admin/t/{tenant}/restore-runs` as deeper existing backup and recovery follow-up surfaces that remain authoritative for domain truth after the triage action is recorded
- **Data Ownership**:
  - Existing backup-health and recovery-evidence posture remain derived tenant truth built from current backup, restore, and workspace overview aggregation layers
  - A new persisted triage-review record becomes the source of truth for whether one workspace has already reviewed one tenant for one concern family, because that operational truth must survive navigation and time
  - The new record is workspace-shared but tenant-owned in storage terms because it is attached to one tenant and one concern family inside one workspace; it is not a formal review artifact, evidence artifact, or policy-governance record
  - Workspace progress summaries and registry badges remain derived views over the combination of current concern truth and the persisted triage-review record; this feature does not create a second posture model or a formal review workflow layer
- **RBAC**:
  - Workspace membership remains required to render `/admin` and `/admin/tenants`, and tenant membership remains required for `/admin/t/{tenant}` and deeper tenant surfaces
  - Review-state visibility follows the same visible-tenant and visible-concern boundaries as portfolio triage; out-of-scope tenants and concern hints remain hidden under deny-as-not-found rules
  - Members with view access may see review-state badges and progress, but only members with the canonical server-side capability to update portfolio triage review state, or an equivalent existing operator-level capability mapped through the capability registry, may mark reviewed or follow-up needed
  - Non-members remain `404`; in-scope members lacking the mutation capability receive `403` on review-state mutations

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Surface Type | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Workspace overview current-set progress summary | Embedded status summary / drill-in surface | Explicit stat or summary CTA to a filtered tenant-registry slice | forbidden | Inline summary links only | none | `/admin` | `/admin/tenants` | Active workspace, concern family, visible affected-set scope | Triage progress / Review state | Reviewed `X/Y`, follow-up-needed count, and changed-since-review count for the current affected set | additive summary strip |
| Tenant registry triage list | CRUD / list-first resource | Full-row click remains the canonical inspect path for registry detail, while the existing tenant-open shortcut remains the fast triage continuation | required | One inline safe shortcut plus More, with review-state mutations inside More to preserve the action-surface contract | none | `/admin/tenants` | `/admin/tenants/{tenant}` | Active workspace, current concern-family focus, backup posture, recovery evidence, review state | Tenants / Tenant | Current concern truth and current review state stay visible together without merging | working-surface augmentation |
| Tenant dashboard arrival continuity block | Embedded arrival and progress control surface | Explicit inline actions inside the continuity block for review-state mutation and return-to-triage | forbidden | Inline actions and helper copy inside the block | none | `/admin/t/{tenant}` | Existing next-step surfaces remain `/admin/t/{tenant}/backup-sets` or `/admin/t/{tenant}/restore-runs` | Workspace context, tenant context, arrival source, concern family, review state | Triage review / Review state | Why the operator is here, whether it was already reviewed, and whether it changed since review | additive continuity control |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| Workspace overview current-set progress summary | Workspace operator | Embedded portfolio summary | How far through the current affected set are we, and which bucket still needs attention? | Concern-family label, reviewed count, affected-set total, follow-up-needed count, changed-since-review count | Raw fingerprints, low-level resolver inputs, inactive historical rows | concern family, current affected-set size, review state, portfolio urgency | none; read-only summary surface | Open filtered registry slices for not reviewed, follow-up needed, or changed since review | none |
| Tenant registry triage list | Workspace operator | List-first working surface | Which visible affected tenants are untouched, already checked, still needing follow-up, or changed since review? | Tenant identity, backup posture, recovery evidence, review state, current slice focus, bounded reviewer or timestamp context when available | Raw snapshot JSON, fingerprint ingredients, inactive state history | backup posture, recovery evidence, review state, triage priority | TenantPilot only for review-state mutations; read-only for posture truth | Open tenant, keep triage filters, mark reviewed, mark follow-up needed | none |
| Tenant dashboard arrival continuity block | Workspace operator arriving from triage | Embedded continuity and mutation surface | Why was this tenant opened, has this concern already been checked, and can I close or park it now? | Arrival reason, triggering concern family, current review state, last reviewed actor or time when available, return target | Fingerprint delta detail, low-level concern payloads, inactive prior records | arrival reason, concern family, review state, current-vs-reviewed drift | TenantPilot only for review-state mutation; deeper next-step links stay read-only navigation | Mark reviewed, Mark follow-up needed, Return to triage, Open next-step follow-up surface | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes
- **New persisted entity/table/artifact?**: yes
- **New abstraction?**: yes
- **New enum/state/reason family?**: yes
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: The product can already identify affected tenants and explain why one tenant was opened, but it still cannot tell the operator which affected tenants were already checked, which ones still need follow-up, or which ones became relevant again after a prior review.
- **Existing structure is insufficient because**: Current posture truth and arrival context are intentionally read-first and request-scoped. They can explain concern state, but they do not persist lightweight operator progress across sessions, registry revisits, or team handoff.
- **Narrowest correct implementation**: Introduce one lightweight persisted triage-review record per workspace, tenant, and concern family, derive `not reviewed` and `changed since review` around that record, and reuse existing overview, registry, and arrival surfaces rather than creating notes, assignments, review packs, or a workflow engine.
- **Ownership cost**: One small persisted review-state model, a stable fingerprint rule, bounded preloading and derivation logic, additive UI badges and actions on existing surfaces, and focused regression coverage for state derivation, progress counts, and RBAC.
- **Alternative intentionally rejected**: Reusing formal `TenantReview` or `ReviewPack` artifacts, introducing user-specific queues, or adding a broader case-management workflow were rejected because they overshoot the immediate portfolio-triage need and would create a heavier governance layer than this release requires.
- **Release truth**: current-release portfolio-triage workflow hardening

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Record That A Concern Was Checked (Priority: P1)

As a workspace operator, I want to mark the current tenant concern as reviewed or follow-up needed from the tenant context so that the portfolio queue reflects work I already did.

**Why this priority**: Without a persisted action at the point of review, the operator still has to track progress outside the product.

**Independent Test**: Can be fully tested by opening a tenant from portfolio triage, marking the current concern reviewed or follow-up needed, and verifying that the registry and overview immediately reflect the new state for the same concern family.

**Acceptance Scenarios**:

1. **Given** a tenant is currently affected for backup health and has no active review record, **When** an authorized operator opens the `Mark reviewed` preview, confirms the `TenantPilot only` scope, and submits it from the arrival continuity block, **Then** the tenant shows `Reviewed` for backup health and stores the current fingerprint and review timestamp.
2. **Given** a tenant is currently affected for recovery evidence and still needs additional work, **When** an authorized operator opens the `Mark follow-up needed` preview, confirms the `TenantPilot only` scope, and submits it, **Then** the tenant shows `Follow-up needed` for that recovery concern while the underlying posture remains unchanged.

---

### User Story 2 - Work The Remaining Set From The Registry (Priority: P1)

As a workspace operator, I want the tenant registry to show and filter review state so that I can quickly focus on untouched or reappeared tenants.

**Why this priority**: Portfolio triage becomes operationally useful only if the registry can separate completed work from the remaining work.

**Independent Test**: Can be fully tested by seeding affected tenants with mixed review states, opening `/admin/tenants`, and verifying the review-state column, state filters, and concern-family focus behavior.

**Acceptance Scenarios**:

1. **Given** the current tenant-registry slice is focused on backup health, **When** the operator filters for `Not reviewed`, **Then** only backup-affected tenants without an active matching review record remain.
2. **Given** the current tenant-registry slice is mixed across backup and recovery concerns, **When** the review-state column renders, **Then** each row identifies which concern family its displayed review state refers to instead of showing an ambiguous shared state.

---

### User Story 3 - Re-review Tenants When The Concern Changes (Priority: P1)

As a workspace operator, I want a previously reviewed tenant to become visibly changed since review when the relevant concern changes so that stale review state does not hide renewed risk.

**Why this priority**: Review progress is unsafe if an old reviewed badge can survive a materially different current concern.

**Independent Test**: Can be fully tested by recording a review, changing the current concern fingerprint while the tenant remains affected, and verifying that the registry and dashboard show `Changed since review` until a new review is recorded.

**Acceptance Scenarios**:

1. **Given** a tenant was reviewed when backup health was `stale`, **When** the current backup concern changes to a different stable reason or state while the tenant remains affected, **Then** the system shows `Changed since review` instead of `Reviewed`.
2. **Given** a tenant was marked `Follow-up needed` for recovery evidence, **When** the current recovery fingerprint changes, **Then** the changed-since-review state overrides the prior manual state until the operator reviews the new situation.

---

### User Story 4 - See Honest Progress For The Current Affected Set (Priority: P2)

As a workspace operator, I want the workspace overview to show progress only for the tenants that are currently affected so that the product tells me what is left right now rather than what was reviewed historically.

**Why this priority**: Progress is misleading if calm or resolved tenants keep inflating reviewed counts or if reviewed badges are mistaken for fixed posture.

**Independent Test**: Can be fully tested by mixing currently affected tenants, resolved tenants, and stale-review tenants, then verifying that the overview summary counts only current affected tenants and keeps posture separate from review state.

**Acceptance Scenarios**:

1. **Given** a workspace has nine currently affected tenants, **When** the overview progress summary renders, **Then** the reviewed total and bucket counts are derived only from those nine tenants and exclude calm or resolved tenants.
2. **Given** a tenant remains weak but is marked `Reviewed`, **When** the registry or overview renders, **Then** the product still shows the weak posture separately and does not imply that the issue is fixed.

### Edge Cases

- A tenant can be affected in both `backup_health` and `recovery_evidence` at the same time; the product must keep one review state per concern family and must not let one family's review mark the other family reviewed.
- The registry can be opened without a single concern-family focus; in that mixed slice the displayed review state must name the concern family it refers to instead of pretending there is one global tenant review state, and it must choose that family by reusing the existing worst-first portfolio concern priority rules already used for mixed registry triage.
- A concern can disappear after review and later reappear; prior resolved or inactive review records must not make the tenant count as reviewed for the new current affected set unless the current fingerprint matches an active record.
- Two operators may update the same workspace-shared review state close together; V1 uses one coherent active state with last-write-wins semantics and does not introduce per-change collaboration workflows.
- Cosmetic text or volatile timestamps may change while the material concern remains the same; fingerprinting must not mark the tenant changed since review unless stable concern inputs changed.
- A user may be allowed to view the registry and dashboard but not mutate review state; review-state truth remains visible while mutation actions degrade safely or fail with `403`.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature adds lightweight TenantPilot-only DB mutations and one new persisted review-state truth, but it introduces no Microsoft Graph calls, no remote writes, and no long-running work. Review-state updates are internal triage-progress writes only, so they do not require an `OperationRun`. Each mutation still uses a bounded pre-execution preview plus explicit confirmation that shows the concern family, current review state, target manual state, and `TenantPilot only` scope. V1 also does not introduce a dedicated per-change audit timeline for these updates because the product decision is to stay lightweight and non-governance-oriented.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** New persistence is justified because current operator workflow now requires progress that survives navigation and time, while request-scoped posture truth and arrival context do not. The persisted addition remains narrow: one active triage-review record per workspace, tenant, and concern family plus derived `not reviewed` and `changed since review` states. No review-pack layer, no generic workflow engine, and no formal evidence model are introduced.

**Constitution alignment (OPS-UX):** No `OperationRun`, progress widget for execution, or terminal operation notification is introduced. These are quick internal DB writes whose effect is immediately reflected in existing portfolio surfaces.

**Constitution alignment (Read/Write Separation):** Because these writes are local, reversible, and sub-2-second, the required preview or dry-run is implemented as a bounded pre-execution summary plus explicit confirmation on the existing Filament actions rather than as a separate remote dry-run pipeline.

**Constitution alignment (RBAC-UX):** Authorization spans the workspace plane at `/admin` and `/admin/tenants` plus the tenant plane at `/admin/t/{tenant}`. Non-members or actors outside workspace or tenant scope remain `404`. Established members without the review-state mutation capability receive `403` on `Mark reviewed` and `Mark follow-up needed`. Server-side authorization remains the source of truth for every mutation. Existing tenant resource global search behavior remains tenant-safe and unchanged; review state is not added as a new cross-tenant search hint.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No auth-handshake behavior changes.

**Constitution alignment (BADGE-001):** The new status-like labels `Not reviewed`, `Reviewed`, `Follow-up needed`, and `Changed since review` must use centralized badge and label semantics rather than page-local color decisions. Tests must cover any new centralized mappings so review-state meaning stays consistent across overview, registry, and arrival surfaces.

**Constitution alignment (UI-FIL-001):** The feature reuses existing Filament tables, filters, actions, stats, sections, and badge-like shared primitives. It must avoid local replacement markup for review-state badges or action blocks. Semantic emphasis comes from existing Filament primitives and central label mappings rather than page-specific border or color language.

**Constitution alignment (UI-NAMING-001):** Operator-facing vocabulary stays explicit and narrow: `Review state`, `Mark reviewed`, `Mark follow-up needed`, and `Changed since review`. The wording must not borrow formal-governance language such as `Tenant review complete`, `approved`, `resolved`, or `evidence accepted`.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001):** The tenant registry remains the canonical collection route and keeps full-row click as its one primary inspect model. Review-state mutations on the registry live in overflow, not as competing primary opens. The tenant dashboard arrival continuity block is an additive mutation surface with explicit inline actions. No redundant view affordance, no destructive control, and no new cross-domain review page are introduced.

**Constitution alignment (OPSURF-001):** Default-visible content on `/admin` and `/admin/tenants` remains operator-first: current concern truth, current review state, and remaining work. Diagnostics such as fingerprints and snapshots stay secondary. Every review-state mutation must communicate that it changes TenantPilot-only portfolio progress, not Microsoft tenant posture or configuration.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** Direct mapping from current posture alone to operator progress is insufficient because posture truth answers what is wrong, not whether someone already checked it. The new triage-review layer is therefore allowed, but it must stay narrow, concern-family-bound, and clearly secondary to posture truth. Tests must focus on business consequences such as wrong counts, stale reviewed badges, family conflation, and false fixed semantics.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract remains satisfied. `TenantResource` keeps exactly one primary inspect model, retains its existing safe tenant-open shortcut, and places the new review-state mutations in overflow. `TenantDashboard` gets additive inline actions inside the existing continuity block, not redundant header actions. No empty action groups or destructive placements are introduced. UI-FIL-001 remains satisfied with no exception required.

**Constitution alignment (UX-001 - Layout & Information Architecture):** No new create or edit forms are introduced. The tenant registry continues to provide search, sort, filters, and meaningful empty states for core dimensions. The tenant dashboard uses existing cards or sections for the continuity block rather than introducing a new standalone screen. View or detail surfaces remain operator-first and do not turn review state into a full workflow board.

### Functional Requirements

- **FR-189-001**: The system MUST persist one active triage-review record per workspace, tenant, and concern family and MUST allow prior records to become inactive instead of overwriting historical continuity in place.
- **FR-189-002**: Persisted manual review states MUST be limited to `reviewed` and `follow_up_needed`; `not_reviewed` and `changed_since_review` MUST remain derived states.
- **FR-189-003**: When a currently affected tenant has no active triage-review record for the current concern family, the system MUST derive `not_reviewed`.
- **FR-189-004**: Authorized operators MUST be able to mark a currently affected tenant concern as `reviewed` from portfolio triage context.
- **FR-189-005**: Authorized operators MUST be able to mark a currently affected tenant concern as `follow_up_needed` from portfolio triage context.
- **FR-189-006**: Setting either manual state MUST store the current concern family, the current stable concern fingerprint, the review timestamp, the reviewing actor when available, and a lightweight bounded snapshot sufficient to explain what was reviewed without becoming a formal evidence artifact.
- **FR-189-007**: The stored fingerprint MUST be based only on stable concern inputs such as concern family, concern state, stable reason code, and stable supporting keys; it MUST NOT depend on cosmetic labels, free-text notes, or volatile timestamps.
- **FR-189-008**: When the current concern still exists but the current fingerprint differs from the stored review fingerprint, the system MUST derive `changed_since_review` (`stale_review`) for that workspace, tenant, and concern family.
- **FR-189-009**: `changed_since_review` MUST override displayed `reviewed` or `follow_up_needed` until an authorized operator records a new review against the current fingerprint.
- **FR-189-010**: Review state MUST never overwrite, hide, or downgrade the separately displayed backup posture or recovery evidence truth; a tenant may remain weak and reviewed at the same time.
- **FR-189-011**: Backup-health and recovery-evidence review states MUST be stored and resolved independently. Reviewing one concern family MUST NOT mark the other family reviewed.
- **FR-189-012**: The tenant registry MUST display the resolved review state for each currently affected row and MUST identify the concern family that state refers to whenever the current view is not already family-specific.
- **FR-189-013**: When `/admin/tenants` is in a family-specific triage slice, whether from workspace drilldown or explicit filters, the review-state column and review-state mutations MUST operate on that same concern family.
- **FR-189-014**: When `/admin/tenants` is in a mixed slice with more than one active concern family, the review-state presentation MUST follow the row's highest-priority active concern family according to the existing worst-first portfolio concern priority rules and MUST label that family explicitly.
- **FR-189-015**: The tenant registry MUST support filtering the current visible affected set by `not_reviewed`, `reviewed`, `follow_up_needed`, and `changed_since_review`.
- **FR-189-016**: Workspace overview surfaces MUST show minimal progress summary for each current concern family or active triage slice, including at least `Reviewed X/Y`, `Follow-up needed`, and `Changed since review`, and those counts MUST be derived only from the current visible affected set.
- **FR-189-017**: Tenants whose relevant concern no longer exists MUST NOT remain counted inside current-set progress or current review-state buckets for that concern family.
- **FR-189-018**: The tenant dashboard arrival continuity block MUST show the current review state for the triggering concern family and MUST offer `Mark reviewed` and `Mark follow-up needed` actions when the current session arrived from portfolio triage with valid concern context.
- **FR-189-019**: Before any review-state mutation executes, the product MUST show a bounded pre-execution preview and explicit confirmation describing the concern family, current review state, target manual state, and `TenantPilot only` mutation scope.
- **FR-189-020**: Generic tenant browsing sessions without portfolio-triage context MUST NOT show triage-review actions, mutation affordances, or progress language that implies a queue.
- **FR-189-021**: When an active triage-review record exists, the product MUST expose the last reviewed time and, when known, the last reviewing actor in a bounded way that supports workspace-shared progress without turning into a comment thread or audit timeline.
- **FR-189-022**: Review-state visibility MUST remain available to entitled viewers even when they lack mutation capability; mutation attempts from non-members MUST resolve as `404`, and mutation attempts from in-scope members without capability MUST resolve as `403`.
- **FR-189-023**: Review-state loading for the registry and workspace progress summaries MUST remain query-bounded and MUST avoid uncontrolled per-row resolver fanout or per-row fingerprint recomputation that would cause list-level N+1 behavior.
- **FR-189-024**: Review-state mutation MUST be a TenantPilot-only workflow mutation that does not start an `OperationRun`, does not call Microsoft Graph, and does not create a formal `TenantReview`, `ReviewPack`, comment thread, assignment, or workflow ticket.
- **FR-189-025**: The feature MUST ship without person-specific queues, collaboration conflict resolution, notes, due dates, SLAs, or per-episode review history beyond the minimal active and inactive triage-review record needed to keep current state honest.
- **FR-189-026**: Regression coverage MUST prove persistence semantics, fingerprint stability, changed-since-review derivation, family separation, registry badging, registry filtering, workspace progress counts, arrival-block actions, generic-session suppression, preview-and-confirmation semantics, honest posture-plus-review coexistence, and RBAC-safe view-versus-mutate behavior.

## Review-State Semantics

- **Active triage-review record**: The current workspace-shared progress record for one tenant and one concern family. It stores the operator's last manual state plus the fingerprint that was current when the review was recorded.
- **Inactive triage-review record**: A prior record whose concern no longer matches the current affected set or was intentionally superseded. It exists only to keep continuity lightweight and does not create an operator-visible review timeline.
- **Current affected set**: The visible tenants whose current backup-health or recovery-evidence posture still matches the concern-family attention rules used by workspace overview and tenant registry triage.
- **Derived state precedence**: `changed_since_review` overrides `follow_up_needed`, which overrides `reviewed`, which overrides `not_reviewed` for currently affected tenants.
- **Current-set progress**: The overview summary over the current visible affected set for one concern family or active triage slice; calm or resolved tenants are excluded.

## Fingerprint Boundaries

- The fingerprint must stay stable across repeated reads of the same material concern situation.
- The fingerprint must change when the current concern family, material concern state, stable reason code, or stable supporting posture keys change.
- The fingerprint must ignore cosmetic wording, translated copy, timestamps, and other volatile display-only values.
- Backup-health fingerprints may include stable posture values such as `absent`, `stale`, `degraded`, `healthy`, schedule-follow-up family, or freshness family.
- Recovery-evidence fingerprints may include stable posture values such as `weakened`, `unvalidated`, `no_recent_issues_visible`, primary concern reason, or restore-evidence concern family.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Workspace overview progress summary | `app/Filament/Pages/WorkspaceOverview.php`, `app/Filament/Widgets/Workspace/WorkspaceSummaryStats.php`, `app/Filament/Widgets/Workspace/WorkspaceNeedsAttention.php` | none added | Explicit stat or summary CTA to a filtered registry slice | none | none | Existing calm-state CTA behavior remains unchanged | n/a | n/a | no dedicated triage-review audit requirement | Read-only summary only. No destructive action or new action-group exception is introduced. |
| Tenant registry triage list | `app/Filament/Resources/TenantResource.php`, `app/Filament/Resources/TenantResource/Pages/ListTenants.php` | Existing header actions remain unchanged | Full-row click remains the canonical inspect affordance | Existing `openTenant` safe shortcut remains visible; `Mark reviewed` and `Mark follow-up needed` live in More or equivalent overflow | No new bulk mutation required in V1 | Existing empty-state CTA remains unchanged | Existing tenant detail header actions remain unchanged | Existing create or edit flows remain unchanged | no dedicated triage-review audit requirement | Action Surface Contract remains satisfied because review-state mutations do not compete with the primary open model, are not destructive, and open a bounded preview-and-confirmation step before the write executes. |
| Tenant dashboard arrival continuity block | `app/Filament/Pages/TenantDashboard.php` plus the existing arrival continuity surface introduced by Spec 187 | none added | Explicit inline `Return to triage` and next-step links only | n/a | n/a | none | n/a | n/a | no dedicated triage-review audit requirement | `Mark reviewed` and `Mark follow-up needed` live inside the continuity block as additive inline actions, open a bounded preview-and-confirmation step before write, and stay suppressed for generic browsing sessions without valid triage context. |

## Key Entities *(include if feature involves data)*

- **Triage-review record**: The persisted workspace-shared progress record for one tenant and one concern family, including manual state, review fingerprint, bounded snapshot, and active or inactive lifecycle.
- **Concern fingerprint**: The stable representation of the current material concern situation used to decide whether a prior review still applies.
- **Concern-family focus**: The backup-health or recovery-evidence slice that tells the registry and tenant arrival block which review state they are resolving or mutating.
- **Current affected set**: The visible tenant population currently matching one concern family's triage rules.
- **Progress summary**: The derived count view over the current affected set showing how many items are reviewed, need follow-up, or changed since review.

## Assumptions

- Existing workspace overview, tenant registry triage, and tenant dashboard arrival-context slices already expose enough stable concern-family and reason context to support bounded fingerprint generation without inventing a second posture model.
- V1 review-state scope is limited to the current portfolio-triage concern families `backup_health` and `recovery_evidence`. Extending the concept to other domains requires a follow-up spec.
- Workspace-shared review state uses one coherent active record with last-write-wins behavior rather than a multi-operator merge or conflict-resolution layer.
- A lightweight bounded snapshot is sufficient for V1; rich notes, comments, evidence attachments, and long-form review rationale remain intentionally out of scope.

## Dependencies

- Existing workspace overview backup-attention and recovery-attention semantics from the current portfolio-triage work
- Existing tenant registry triage filters, worst-first ordering, and tenant-open continuity
- Existing tenant dashboard arrival continuity block introduced by Spec 187
- Existing backup-health and recovery-evidence truth used by workspace overview and tenant registry triage
- Existing RBAC helpers, capability registry, and tenant-safe route resolution patterns

## Out of Scope and Follow-up

- No formal `TenantReview`, `ReviewPack`, or evidence-artifact workflow
- No notes, comments, or rich-text rationale on review-state records
- No assignments, owner queues, or team delegation workflow
- No due dates, reminders, SLAs, or escalation mechanics
- No automatic ticket creation or external task synchronization
- No multi-operator conflict-resolution layer or per-episode review history beyond active and inactive continuity records
- No broader workflow engine with `in progress`, `blocked`, `done`, or other cross-domain states

## Risks

- If review state is rendered more prominently than posture truth, operators may misread `Reviewed` as `Fixed`.
- If fingerprint rules are too sensitive, tenants will churn into `Changed since review` because of cosmetic differences instead of meaningful posture change.
- If fingerprint rules are too weak, materially different concern situations will keep stale `Reviewed` or `Follow-up needed` badges.
- If workspace-shared state lacks reviewer and timestamp context, team handoff can become confusing even in a lightweight model.
- If registry loading resolves review state per row without batching, portfolio triage performance can regress under moderate affected-set sizes.

## Definition of Done

This feature is complete when:

- a persisted portfolio triage review state exists for workspace, tenant, and concern-family combinations,
- the tenant registry shows review state beside posture truth without conflating the two,
- the tenant registry can filter by review state for the current visible affected set,
- authorized operators can mark `Reviewed` and `Follow-up needed` from tenant triage context,
- fingerprint-based `Changed since review` derivation works and overrides stale prior manual states,
- workspace overview surfaces show lightweight progress for the current affected set,
- backup-health and recovery-evidence review state remain separate,
- formal review, notes, assignments, and workflow-engine behavior remain absent,
- targeted regression coverage is green, and
- the shipped UI remains honest that `Reviewed` does not mean `Fixed`.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-189-001**: In acceptance review, a workspace operator can determine within 10 seconds from `/admin/tenants` which currently affected tenants are `Not reviewed`, `Reviewed`, `Follow-up needed`, or `Changed since review`.
- **SC-189-002**: In 100% of covered mutation scenarios, marking `Reviewed` or `Follow-up needed` from tenant triage context updates the matching registry row and current-set progress summary without requiring an external note-taking step.
- **SC-189-003**: In 100% of covered fingerprint-change scenarios, a previously reviewed or follow-up-needed tenant shows `Changed since review` until a new review is recorded against the current fingerprint.
- **SC-189-004**: In 100% of covered overview and registry scenarios, current-set progress counts include only currently affected visible tenants and exclude calm or resolved tenants.
- **SC-189-005**: In 100% of covered truthfulness scenarios, posture truth and review state appear together without any label or layout implying that review state means the tenant is fixed, approved, or recovery-proven.
- **SC-189-006**: In RBAC regression coverage, entitled viewers can see review-state truth while non-members receive `404` and in-scope members without mutation capability receive `403` for review-state mutations.
- **SC-189-007**: Targeted query-bounded regression coverage shows that representative affected-set registry rendering does not degrade into uncontrolled per-row review-state query fanout.
