TenantAtlas/specs/155-tenant-review-layer/spec.md

# Feature Specification: Tenant Review Layer

**Feature Branch**: `155-tenant-review-layer`  
**Created**: 2026-03-20  
**Status**: Draft  
**Input**: User description: "Executive Review Packs / Tenant Review Layer"

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant + canonical-view
- **Primary Routes**:
  - `/admin/t/{tenant}/reviews` as the tenant-scoped review library and entry point for recurring review preparation
  - `/admin/t/{tenant}/reviews/{review}` as the canonical tenant review inspection surface
  - `/admin/reviews` as the workspace-scoped canonical review register for entitled operators who manage recurring reviews across multiple tenants
  - Existing evidence, findings, baseline, and permissions surfaces remain linked drill-down destinations from the review detail when the operator is entitled to inspect them
- **Data Ownership**:
  - Tenant-owned: tenant review records, review composition metadata, review lifecycle state, executive summary content, and stakeholder-facing review-pack references for one tenant
  - Tenant-owned inputs: evidence snapshots, accepted-risk summaries, findings summaries, baseline or drift posture, permission posture, and operational health summaries that are consumed but not re-owned by the review layer
  - Workspace-owned but tenant-filtered: canonical review library filters, review schedule summaries, and cross-tenant list presentation state without changing tenant ownership of the review itself
  - Compliance or framework readiness interpretations remain outside this feature and are not stored as first-class review truth in this slice
- **RBAC**:
  - Workspace membership remains required for every review surface
  - Tenant entitlement remains required to inspect or mutate tenant-scoped review records
  - `tenant_review.view` permits listing and inspecting reviews within authorized scope
  - `tenant_review.manage` permits creating, refreshing, publishing, archiving, and exporting review packs within authorized scope
  - Non-members or users outside the relevant workspace or tenant scope remain deny-as-not-found, while in-scope members lacking the required capability remain forbidden

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: When an operator navigates from a tenant into the shared review register, the canonical workspace view opens prefiltered to that tenant. The operator may clear or change the filter only within their authorized tenant set.
- **Explicit entitlement checks preventing cross-tenant leakage**: Review queries, counts, tenant labels, filter options, executive summaries, and exported review-pack references must be assembled only after workspace and tenant entitlement checks. Unauthorized users must not learn whether another tenant has review history, stakeholder packs, or upcoming review work.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Prepare one tenant review from curated evidence (Priority: P1)

As a governance operator, I want to create a tenant review from an evidence snapshot and related governance signals, so that quarterly or ad hoc tenant reviews start from one stable, curated review record instead of manual page-by-page assembly.

**Why this priority**: This is the core product workflow. Without a first-class tenant review record, executive review packs are still ad hoc exports rather than a repeatable review motion.

**Independent Test**: Can be fully tested by selecting an eligible tenant evidence snapshot, creating a tenant review, and verifying that the resulting review preserves the chosen evidence basis, key governance sections, and summary state even if live source data changes later.

**Acceptance Scenarios**:

1. **Given** a tenant has at least one eligible evidence snapshot, findings summary, and posture inputs, **When** an authorized operator creates a tenant review, **Then** the system creates one review record that captures the selected evidence basis and generated review sections for that tenant.
2. **Given** a tenant review has been created from a specific evidence snapshot, **When** live findings or posture data later change, **Then** the existing review remains tied to its original evidence basis until the operator explicitly refreshes or creates a new review.
3. **Given** the chosen evidence basis is partial, **When** the operator creates the review, **Then** the review clearly records which sections are complete, partial, or unavailable rather than implying a fully complete review.

---

### User Story 2 - Present an executive-ready tenant review pack (Priority: P1)

As an MSP account manager or governance lead, I want a concise executive review surface and exportable review pack for one tenant, so that I can lead customer or management conversations with a stakeholder-ready output rather than raw operational artifacts.

**Why this priority**: This is the commercial value layer. The product stops being only an operator console when it can produce a readable, stakeholder-facing review output.

**Independent Test**: Can be fully tested by opening a prepared tenant review, confirming that it presents executive summary sections and drill-down links coherently, and generating a stakeholder-ready review pack from that review without rebuilding the evidence manually.

**Acceptance Scenarios**:

1. **Given** an authorized operator opens a prepared tenant review, **When** the review detail loads, **Then** it shows an executive summary, key risks, accepted-risk summary, posture highlights, and recommended next actions in one coherent inspection surface.
2. **Given** a tenant review is ready for stakeholder delivery, **When** the operator publishes or exports the executive review pack, **Then** the pack is generated from that review record and reflects the same section ordering and summary truth shown in the product.
3. **Given** a stakeholder-facing review pack omits one or more dimensions because the underlying evidence was partial, **When** the operator inspects or exports it, **Then** the omission is explained clearly instead of being silently hidden.

---

### User Story 3 - Manage recurring tenant reviews over time (Priority: P2)

As a workspace operator, I want a canonical review library across the tenants I manage, so that I can see which tenants were reviewed, which reviews are draft or published, and which tenants need the next review cycle.

**Why this priority**: Once the first tenant review exists, the product needs a repeatable operating model rather than one-off packs. This enables recurring review discipline and prepares the ground for the later portfolio dashboard.

**Independent Test**: Can be fully tested by creating reviews for multiple tenants, opening the workspace review register, and verifying that the register shows only entitled tenants with correct lifecycle, publish status, and recency signals.

**Acceptance Scenarios**:

1. **Given** an operator is entitled to multiple tenants with review history, **When** they open the workspace review register, **Then** they can filter by tenant, review state, publish status, and review date without seeing unauthorized tenant rows.
2. **Given** a tenant already has a published review, **When** the operator starts the next review cycle, **Then** the system creates a new draft review instead of mutating the historical published review.
3. **Given** no review matches the current filters, **When** the operator opens the canonical review register, **Then** the empty state explains that no review records match and offers exactly one clear next action.

### Edge Cases

- A tenant has eligible evidence snapshots but no valid accepted-risk records; the review must still generate and explicitly show that no governed accepted risks are currently active.
- A previously published review pack is revisited after the underlying evidence snapshot expires or is superseded; the historical review must remain intelligible from stored review metadata.
- A tenant has multiple evidence snapshots available; the operator must choose which one anchors the review rather than the system silently picking a different basis.
- An operator tries to publish or export a review that is still missing required summary sections; the product must fail with a clear readiness reason instead of producing a misleading finished pack.
- A workspace operator is entitled to some, but not all, tenants in a workspace; the canonical review register must suppress unauthorized tenant labels, counts, and filter values.
- A tenant review is created twice from the same evidence basis without meaningful changes; the system must prevent accidental duplicate published reviews while still allowing a deliberate new draft when needed.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces a new review-domain data model, user-driven write behavior, and optional long-running generation work for stakeholder-facing review packs, but it does not introduce new Microsoft Graph collection. It must describe the review contract with evidence snapshots, explicit publish/export safety gates, tenant isolation, run observability for any generated pack artifact, and tests. Security-relevant DB-only review lifecycle changes such as publish, archive, and unpublish equivalents must always emit audit history.

**Constitution alignment (OPS-UX):** If review-pack generation is asynchronous, this feature creates or reuses a dedicated `OperationRun` family for tenant review pack generation and must comply with the Ops-UX 3-surface feedback contract. Start actions may show intent-only feedback. Progress belongs only in the active-ops widget and Monitoring run detail. Review detail may link to the canonical run detail but must not create a parallel progress tracker. `OperationRun.status` and `OperationRun.outcome` remain service-owned through `OperationRunService`. Any `summary_counts` must use allowed numeric-only keys and values. Scheduled or system-initiated review generation must not create initiator-only terminal DB notifications.

**Constitution alignment (RBAC-UX):** This feature operates in the tenant/admin plane for tenant review detail and mutation surfaces and in the workspace-admin canonical view for the shared review register. Cross-plane access remains deny-as-not-found. Non-members or users outside workspace or tenant scope receive `404`. In-scope users lacking `tenant_review.view` or `tenant_review.manage` receive `403` according to the attempted action. Authorization must be enforced server-side for create, refresh, publish, archive, and export actions. The canonical capability registry remains the only capability source. Destructive-like actions such as archive require confirmation.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No authentication handshake behavior is changed.

**Constitution alignment (BADGE-001):** Review lifecycle state, publication state, completeness state, and export readiness are status-like values and must use centralized badge semantics rather than local page-specific mappings. Tests must cover all newly introduced values.

**Constitution alignment (UI-NAMING-001):** The target object is the tenant review. Operator-facing verbs are `Create review`, `Refresh review`, `Publish review`, `Export executive pack`, and `Archive review`. Source/domain disambiguation is needed only where the review references evidence dimensions such as findings, baseline posture, permissions, or operations health. The same review vocabulary must be preserved across action labels, modal titles, run titles, notifications, and audit prose. Implementation-first terms such as `render package`, `materialize review`, or `hydrate sections` must not become primary operator-facing labels.

**Constitution alignment (Filament Action Surfaces):** This feature adds or modifies Filament pages/resources for tenant review list and detail plus workspace canonical review register. The Action Surface Contract is satisfied if list inspection uses a canonical inspect affordance, pack generation remains an explicit action, destructive lifecycle actions require confirmation, and all mutations are capability-gated and auditable.

**Constitution alignment (UX-001 — Layout & Information Architecture):** Review list screens must provide search, sort, and filters for tenant, review state, publication state, evidence basis, and review date. Review detail must use an Infolist-style inspection surface rather than a disabled edit form. Any review-creation form or action must keep inputs inside sections. Empty states must include a specific title, explanation, and exactly one CTA.

### Functional Requirements

- **FR-001**: The system MUST provide a first-class tenant review record that represents one curated governance review for one tenant and one chosen evidence basis.
- **FR-002**: A tenant review MUST reference exactly one anchored evidence basis at creation time, with enough stored metadata to remain intelligible if downstream source artifacts later change, expire, or are superseded.
- **FR-003**: The first implementation slice MUST support review sections for executive summary, open-risk highlights, accepted-risk summary, permission posture summary, baseline or drift posture summary, and operational health summary.
- **FR-004**: The system MUST allow an authorized operator to create a tenant review from an eligible evidence snapshot without manually rebuilding each section from live source pages.
- **FR-005**: The system MUST preserve review immutability for published reviews. Refreshing a published review MUST create a new draft review or explicit successor review instead of mutating the published historical record.
- **FR-006**: The system MUST distinguish at least draft, ready, published, archived, and superseded review lifecycle states.
- **FR-007**: The system MUST record review completeness and section availability explicitly, including when a review is based on partial evidence.
- **FR-008**: The system MUST make it clear which evidence dimensions were included, omitted, partial, or stale in each review.
- **FR-009**: The system MUST provide one tenant-scoped review library where authorized operators can list, inspect, refresh, publish, archive, and export review records for the active tenant.
- **FR-010**: The system MUST provide one workspace-scoped canonical review register where authorized operators can review tenant review history across entitled tenants without leaking unauthorized tenant detail.
- **FR-011**: The system MUST provide one stakeholder-facing executive review surface for a prepared tenant review that presents summary content and recommended next steps without forcing the operator into raw source artifacts.
- **FR-012**: The system MUST support an exportable executive review pack derived from one prepared tenant review record rather than from ad hoc live assembly.
- **FR-013**: Exporting an executive review pack MUST use the selected tenant review as the source of truth for section ordering, summary content, and included dimensions.
- **FR-014**: The system MUST block publish or export actions when the review lacks required summary sections or required completeness thresholds for this slice, and it MUST explain the blocking reason clearly.
- **FR-015**: The system MUST define duplicate-prevention semantics so that accidental repeated publish or export attempts from the same unchanged review do not create duplicate final artifacts unintentionally.
- **FR-016**: The system MUST preserve historical published review records and exported pack references so prior reviews remain auditable and comparable over time.
- **FR-017**: Creating, refreshing, publishing, archiving, and exporting a review MUST be recorded in audit history with workspace scope, tenant scope, actor, action, and outcome.
- **FR-018**: The feature MUST explicitly exclude framework-oriented compliance scoring, certification claims, and BSI, NIS2, or CIS mapping from the first slice. Those remain a downstream Compliance Readiness feature.
- **FR-019**: The feature MUST introduce at least one positive and one negative authorization test for tenant-scoped review management and workspace-scoped canonical review visibility.
- **FR-020**: The feature MUST introduce regression tests proving evidence-basis anchoring, published-review immutability, executive-pack consistency, and cross-tenant isolation.

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Tenant Review Library | Tenant-context review list under `/admin/t/{tenant}/reviews` | `Create review` (`tenant_review.manage`) | Clickable row to review detail | `View review`, `Export executive pack` when ready | None in v1 | `Create first review` | None | N/A | Yes | Create may use an action modal because it selects an evidence basis and starts a review composition workflow |
| Tenant Review Detail | Canonical detail route under `/admin/t/{tenant}/reviews/{review}` | None | N/A | None | None | N/A | `Refresh review`, `Publish review`, `Export executive pack`, `Archive review` | N/A | Yes | Inspection surface only; no disabled edit form |
| Workspace Review Register | Workspace canonical view at `/admin/reviews` | `Clear filters` | Clickable row to review detail | `View review`, `Export executive pack` when authorized | None in v1 | `Clear filters` | None | N/A | Export yes | Must suppress unauthorized tenant rows and filter values |

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

- **Tenant Review**: A curated review record for one tenant anchored to a chosen evidence basis and used for recurring governance conversations.
- **Review Section**: One named portion of the tenant review, such as executive summary, risk highlights, posture summary, or operational health summary, including its completeness and source references.
- **Executive Review Pack**: A stakeholder-facing deliverable derived from one tenant review and preserving that review's section ordering, summary truth, and completeness disclosures.
- **Review Lifecycle State**: The normalized state of a tenant review, including draft, ready, published, archived, and superseded.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: An authorized operator can create a tenant review from an eligible evidence basis and open its executive summary in under 3 minutes without leaving the product.
- **SC-002**: Published tenant reviews remain unchanged in 100% of automated immutability tests after underlying live source records are modified.
- **SC-003**: In manual review flow validation, an operator can answer the tenant's top risks, current posture highlights, and next actions from one review detail surface without opening more than one optional drill-down page.
- **SC-004**: Exported executive review packs match their source tenant review's included dimensions and summary ordering in 100% of automated integration tests for the covered first-slice review sections.
- **SC-005**: Negative authorization tests prove that non-members or wrong-tenant users receive deny-as-not-found behavior and in-scope users without the required capability cannot create, publish, archive, or export tenant reviews.
- **SC-006**: Operators can distinguish draft, ready, published, archived, and superseded review states in one inspection step from list or detail surfaces.

## Assumptions

- Evidence snapshots are the primary source-of-truth input for review creation in the first slice.
- Findings summaries, accepted-risk lifecycle data, permission posture, and baseline or drift posture are mature enough to populate first-slice review sections.
- The first slice optimizes for tenant-by-tenant recurring reviews and executive packs, not for framework-oriented compliance mapping.
- Workspace-level review visibility is a register and management surface, not yet a portfolio dashboard with SLA analytics.

## Non-Goals

- Building a framework-oriented Compliance Readiness layer with BSI, NIS2, or CIS mapping
- Creating tenant portfolio rollups, SLA health dashboards, or fleet ranking views across tenants
- Implementing cross-tenant compare or promotion workflows
- Turning the tenant review layer into a generic BI reporting system
- Triggering new Microsoft Graph collection during review preparation