TenantAtlas/specs/389-governance-inbox-resolution-intake-v1/spec.md

# Feature Specification: Governance Inbox Resolution Intake v1

**Feature Branch**: `389-governance-inbox-resolution-intake-v1`
**Created**: 2026-06-19
**Status**: Draft / Ready for implementation planning after Spec 388 stabilization
**Input**: User-provided consolidated Spec 389 draft: "Governance Inbox Resolution Intake v1"

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: Active Review Publication Resolution Cases created by Specs 386-388 are discoverable mainly from the specific Environment Review detail page, so operators must already know which review is blocked before they can continue safe preparation.
- **Today's failure**: Failed, waiting, stale, blocked, or ready-to-continue review publication preparation work can remain hidden from the central Governance Inbox. Teams lack one prioritized triage surface for unresolved publication blockers across visible environments.
- **User-visible improvement**: Operators open the existing Governance Inbox and see active review publication preparation work with a decision-first title, reason, affected review/environment, current safe status, owner when known, and one safe next place to continue.
- **Smallest enterprise-capable version**: Add one concrete `review_publication_resolution` intake family/section over existing Review Publication Resolution Cases, reuse Spec 388 proof/currentness semantics and existing resolution/review/operation pages, and fall back to `Needs re-check` whenever list-view state cannot be validated cheaply and safely.
- **Explicit non-goals**: No generic workflow engine, task system, ticketing/PSA system, adapter registry, top-level navigation, global search resource, customer-facing inbox, inline execution, auto-publish, restore/provider/baseline/report-delivery intake, or second proof/currentness evaluator.
- **Permanent complexity imported**: A narrow Governance Inbox provider or builder extension, display-only mapping contract, focused tests, and optional contract artifacts. No new persistence, migration, global registry, or broad status enum is approved by default.
- **Why now**: Spec 386 created the workflow, Spec 387 made the resolution page decision-first, and Spec 388 hardened proof/currentness. The next operational gap is visibility in the existing operator decision surface without reopening the workflow engine.
- **Why not local**: The Resolution Page remains the source-owned execution context, but discovery must be central because the operator cannot triage hidden cases one review at a time.
- **Approval class**: Workflow Compression.
- **Red flags triggered**: Governance Inbox scope and status mapping could drift into a generic task system. Defense: v1 is limited to one concrete item type, no persisted inbox status, no registry, no inline mutation, and no new top-level surface.
- **Score**: Value: 2 | Urgency: 2 | Scope: 2 | Complexity: 1 | Product fit: 2 | Reuse: 2 | **Total: 11/12**
- **Decision**: approve for preparation; implementation waits on Spec 388 stabilization and focused review.
- **Candidate source**: Direct user-provided Spec 389 draft, manually promoted. `docs/product/spec-candidates.md` currently reports no safe automatic next-best-prep target.
- **Close alternatives deferred**: Restore readiness intake, provider onboarding readiness intake, evidence/baseline readiness intake, report delivery readiness intake, cross-tenant promotion intake, notification routing, and assignment/SLA workflows remain follow-up specs only.
- **Completed-spec guardrail**: Specs 386, 387, and 388 contain completion/validation/checklist signals and are dependency context only. They must not be rewritten by Spec 389.

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view / workspace-wide Governance Inbox with environment-scoped items.
- **Primary Routes**: Existing admin Governance Inbox at `GovernanceInbox` (`/admin/governance/inbox`), existing Environment Review Resolution Page, existing Environment Review detail page, existing OperationRun detail page where allowed.
- **Data Ownership**: Read-only consumption of existing workspace-owned and environment-owned records: `review_publication_resolution_cases`, `review_publication_resolution_steps`, `environment_reviews`, `operation_runs`, and source artifacts used only through safe summaries/currentness semantics.
- **RBAC**: Workspace membership is required. Environment entitlement and review/case view permission are required per item. Execution capability affects viewer-relative status and action label but is not persisted. Operation links require OperationRun view authorization plus case/step/scope/currentness/context validation.

For canonical-view specs:

- **Default filter behavior when tenant-context is active**: Governance Inbox keeps its explicit `environment_id` filter semantics. If an environment filter is active, only cases for that environment may appear.
- **Explicit entitlement checks preventing cross-tenant leakage**: Every case query is constrained by workspace and authorized environment IDs before mapping. Non-entitled workspace/environment/review/case rows are hidden with deny-as-not-found behavior where existing policies require it.

## UI Surface Impact *(mandatory - UI-COV-001)*

Does this spec add, remove, rename, or materially change any reachable UI surface?

- [ ] No UI surface impact
- [x] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] Workspace/environment context presentation changed

## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write `N/A - no reachable UI surface impact` plus rationale)*

- **Route/page/surface**: Existing Governance Inbox page `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php` and view `apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php`.
- **Current or new page archetype**: Existing operator workbench / Primary Decision Surface from Specs 327 and 346.
- **Design depth**: Strategic Surface, pattern-reusing extension only.
- **Repo-truth level**: repo-verified through existing page, `GovernanceInboxSectionBuilder`, Specs 327/346, and browser smoke artifacts.
- **Existing pattern reused**: Existing section/family entries, operator lanes, source-detail disclosure, environment filter chip, native Filament badges/buttons, `OperationRunLinks`, `EnvironmentReviewResource::environmentScopedUrl()`, policies, and the resolution page.
- **New pattern required**: none. A concrete provider/section for one source family may be needed, but no generic UI framework.
- **Screenshot required**: yes if browser harness is available, stored under `specs/389-governance-inbox-resolution-intake-v1/artifacts/screenshots/`; otherwise document fixture limitations.
- **Page audit required**: no new page report by default; update existing Governance Inbox coverage artifacts if implementation materially changes the page beyond a pattern-reusing source family.
- **Customer-safe review required**: yes as negative coverage. Customer-facing workspace must not show internal resolution intake items.
- **Dangerous-action review required**: yes as a negative review. The inbox must not add publish, cancel, or step execution actions.
- **Coverage files updated or explicitly not needed**:
  - [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
  - [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
  - [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
  - [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
  - [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
  - [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
  - [x] No coverage artifact update required during preparation: Spec 389 reuses the existing Governance Inbox page archetype, route, and source-family pattern. Implementation must update the registry artifacts if runtime work materially changes page archetype, route inventory, strategic-surface classification, or design coverage beyond a pattern-reusing source-family extension.
  - [ ] `N/A - no reachable UI surface impact`
- **No-impact rationale when applicable**: N/A. Existing reachable UI surface changes.

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes.
- **Interaction class(es)**: Governance Inbox status messaging, operator action links, OperationRun links, review/evidence status summaries, source-family filters, environment scope signals.
- **Systems touched**: Existing Governance Inbox page/builder, Review Publication Resolution service/proof resolver, Environment Review resource page links, OperationRun links/policy, customer no-leakage boundary.
- **Existing pattern(s) to extend**: `GovernanceInboxSectionBuilder` family/entry arrays and `GovernanceInbox` lane normalization; `OperationRunLinks` only after validation; `ReviewPublicationResolutionCasePolicy`; `OperationRunPolicy`; Spec 388 proof/currentness safe summaries.
- **Shared contract / presenter / builder / renderer to reuse**: Existing Governance Inbox section/entry shape. If implementation adds a new class, it must be a concrete `ReviewPublicationResolutionInboxProvider` or equivalent, not a registry or generic adapter.
- **Why the existing shared path is sufficient or insufficient**: The existing builder already composes source families into a single decision-first inbox. It is sufficient for v1 if extended with a concrete family/provider; it lacks only the Review Publication Resolution case source.
- **Allowed deviation and why**: A small concrete provider is allowed to keep Review Publication Resolution mapping isolated and testable without bloating the main builder.
- **Consistency impact**: Titles, reasons, status labels, primary/secondary actions, environment labels, and source-detail disclosure must match existing inbox structure.
- **Review focus**: no generic task model, no second proof evaluator, no raw IDs/payloads, no inline mutation, no customer leakage.

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

- **Touches OperationRun start/completion/link UX?**: yes, link display only. It must not create, queue, resume, reconcile, or complete OperationRuns.
- **Shared OperationRun UX contract/layer reused**: `OperationRunLinks` for URL labels/URLs after scope/context/currentness/RBAC validation; `OperationRunPolicy` for permission; existing resolution proof/currentness semantics for whether a linked run is current.
- **Delegated start/completion UX behaviors**: N/A for starts/completion. No queued toast, browser event, terminal notification, or dedupe behavior is introduced.
- **Local surface-owned behavior that remains**: Read-only decision copy and whether to hide/show a safe operation link.
- **Queued DB-notification policy**: N/A. No notifications.
- **Terminal notification path**: N/A.
- **Exception required?**: none.

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: no new provider/platform boundary.
- **Boundary classification**: existing Review Publication Resolution is review-publication-owned and environment-scoped.
- **Seams affected**: only display of existing resolution, proof, and OperationRun references in Governance Inbox.
- **Neutral platform terms preserved or introduced**: `workspace`, `environment`, `review`, `operation`, `proof`, `preparation`, `governance inbox`.
- **Provider-specific semantics retained and why**: existing report/evidence/review-pack step meanings remain inside Review Publication Resolution semantics; no Microsoft Graph or provider payload semantics are surfaced by default.
- **Why this does not deepen provider coupling accidentally**: the inbox consumes safe summaries and existing review-publication-specific state; it does not add Graph endpoints, provider registries, or provider-shaped platform-core contracts.
- **Follow-up path**: future adapters for restore/provider/baseline/report delivery require separate specs after those domains produce trustworthy readiness state.

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Governance Inbox source family and lane entries for review publication resolution | yes | Existing custom Blade page using Filament primitives | Governance Inbox section family, status messaging, action links | page, source family, lane classification, filters | no | Pattern-reusing extension to existing strategic surface |
| OperationRun link disclosure from inbox item | yes | Existing link helper and policy | OperationRun link UX | linked-record/secondary-action display | no | Link only; no run start/completion UX |
| Customer Review Workspace boundary | no material customer feature change | N/A | customer-safe negative boundary | negative visibility tests | no | Customer workspace must not show internal intake |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Governance Inbox review publication resolution items | Primary Decision Surface | Operator triages blocked, failed, waiting, stale, or ready review publication preparation | Status, environment, review, reason, next safe action, owner if known, last update | Safe proof summary and operation/review/source links only when validated | Primary because the existing inbox is the operator work queue | Follows active governance work, not storage objects | Removes search across individual reviews and operation pages |

## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)*

| Surface | Audience Modes In Scope | Decision-First Default-Visible Content | Operator Diagnostics | Support / Raw Evidence | One Dominant Next Action | Hidden / Gated By Default | Duplicate-Truth Prevention |
|---|---|---|---|---|---|---|---|
| Governance Inbox review publication resolution item | operator-MSP, read-only operator, support via existing admin policies | What needs attention, why, environment/review, safe status, continue/inspect action | Collapsed source detail: current step human label, safe proof summary, linked operation if validated | Not shown in inbox; remains on existing authorized source/detail pages | Continue preparation or Inspect preparation; Open operation only when safest and validated | raw payloads, proof reason codes, readiness fingerprints, operation IDs unless link-valid, exception messages | The inbox summarizes the blocker once; resolution page/source pages own detailed proof |
| Customer Review Workspace | customer-read-only | No internal resolution item | none | none | Existing customer-safe review actions only | all internal resolution/proof/OperationRun data | negative boundary only |

## UI/UX Surface Classification *(mandatory when operator-facing list, detail, queue, audit, config, or report surface changes)*

| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | 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 / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Governance Inbox review publication resolution items | Queue / Workbench / Read-only | Decision-first intake queue | Continue preparation | Primary button to existing Resolution Page | Existing page pattern; no new row contract required | Existing source-detail/secondary actions | none in inbox | existing Governance Inbox route | existing Resolution Page / Review / Operation pages | Workspace badge and Environment badge/filter | Review publication work | status, reason, review/environment, next safe action, current proof availability only as safe label | none |

## UI Action Matrix *(mandatory when operator-facing surfaces are changed)*

| Surface / Slot | Allowed Action(s) | Placement | Behavior | Authorization / Confirmation / Audit |
|---|---|---|---|---|
| Governance Inbox header actions | No new header action for Spec 389 | Existing page header only | No mutation and no new workflow entry point | Existing page authorization only; no confirmation or audit event because no new action |
| Review publication item primary action | `Continue preparation` or `Inspect preparation`; `Open operation` only when item status is validated `waiting` and opening the operation is the safest next action | Existing item primary button | Navigate only to the existing Resolution Page or validated OperationRun detail | Case/review visibility required; operation link also requires workspace/environment/review/case/step/type/currentness/RBAC validation; no confirmation or audit event because navigation only |
| Review publication item secondary actions | `Open review`; optional `Open operation` | Existing source-detail/secondary-action area | Navigate only to authorized existing pages | Hide when RBAC/scope/currentness/context validation fails; no confirmation or audit event because navigation only |
| Row click / identifier click | Existing Governance Inbox row/source-link pattern only | Existing source entry link behavior | Inspect/open source context, no inline execution | Same authorization as destination page; no confirmation or audit event because navigation only |
| Bulk actions | None | N/A | Not supported | N/A |
| Empty-state CTA | No new mutating CTA; optional existing navigation/filter-reset affordance only | Existing empty-state area | Calm empty state or non-mutating navigation | No confirmation or audit event |
| Destructive or mutating actions | None | Forbidden in Governance Inbox | No publish, cancel, step execution, provider check, Entra scan, report update, evidence collection, review refresh, or export preparation | Mutations remain source-owned on existing pages with their own authorization, confirmation, audit, and tests |

## Operator Surface Contract *(mandatory when operator-facing page changes)*

| Surface | Primary Persona | Decision / Operator Action Supported | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|---|
| Governance Inbox | MSP operator / workspace operator / read-only inspector | Decide which review publication preparation needs attention and where to continue safely | Read-only decision queue | Which review publication work needs attention now? | item type, status, severity/lane, environment, review label, reason, next safe action, last update, owner | step key, readiness fingerprint, proof reason codes, raw run/artifact metadata, raw payloads | inbox actionability, proof/currentness safety, operation running/failure only when validated | none; navigation only | Continue preparation / Inspect preparation; Open operation only if validated; Open review if allowed | none |

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

- **New source of truth?**: no.
- **New persisted entity/table/artifact?**: no. Spec artifacts only; runtime should prefer no migration.
- **New abstraction?**: yes, possibly one concrete provider/query class for Review Publication Resolution intake only.
- **New enum/state/reason family?**: no persisted family. Inbox statuses are derived viewer-relative labels for this surface only.
- **New cross-domain UI framework/taxonomy?**: no.
- **Current operator problem**: active review publication resolution work is hidden unless an operator already opens the specific review.
- **Existing structure is insufficient because**: the existing Governance Inbox has no source family for Review Publication Resolution Cases, while the Resolution Page is intentionally a detail/continuation context.
- **Narrowest correct implementation**: one concrete read-only source family/provider that maps existing cases/steps/safe summaries into existing inbox entries.
- **Ownership cost**: focused mapping logic and tests for status, scope, RBAC, operation-link disclosure, and stale-safe fallback.
- **Alternative intentionally rejected**: generic task/workflow item model, adapter registry, generic resolution-type registry, new resource, or top-level page.
- **Release truth**: current-release truth for a single existing workflow.

### Compatibility posture

This feature assumes a pre-production environment. Backward compatibility shims are out of scope. Existing completed/cancelled/superseded cases are hidden by default rather than migrated.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Feature for provider/query mapping, RBAC/scope, and no-mutation assertions; Filament/Livewire Feature for Governance Inbox rendering; Browser smoke for visual/user workflow checks if harness is available.
- **Validation lane(s)**: fast-feedback + confidence; browser optional but expected if the page rendering changes; no PostgreSQL lane unless implementation adds indexes/migrations after updating this spec.
- **Why this classification and these lanes are sufficient**: The change is read-only UI/query mapping over existing records. Focused Feature/Filament tests prove state mapping and safety; browser smoke proves the operator surface is clear.
- **New or expanded test families**: one focused Spec 389 Governance Inbox feature family; optional browser smoke file.
- **Fixture / helper cost impact**: ReviewPublicationResolutionCase, Step, EnvironmentReview, OperationRun, and user capability fixtures. Helpers must stay explicit and local to Spec 389 or reuse existing Spec 386-388 factories without widening defaults.
- **Heavy-family visibility / justification**: Browser coverage is explicit because the Governance Inbox is a strategic decision surface and mobile clarity/customer non-leakage matter.
- **Special surface test profile**: governance workbench / standard-native-filament with read-only operation-link disclosure.
- **Standard-native relief or required special coverage**: ordinary Feature/Filament tests for most mapping; browser for representative visible states if fixtures are available.
- **Reviewer handoff**: verify no generic engine, no inline mutation, no stale operation disclosure, correct 404/403 semantics, no customer leakage, no raw proof/payload metadata, and no full-suite claim unless actually run.
- **Budget / baseline / trend impact**: low expected; document-in-feature if browser fixture scope or governance-lane runtime grows materially.
- **Escalation needed**: document-in-feature for contained fixture cost; follow-up-spec only if a generic inbox-source system becomes unavoidable.
- **Active feature PR close-out entry**: Guardrail + Smoke Coverage if browser is run.
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/GovernanceInbox/Spec389GovernanceInboxResolutionIntakeTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec386ReviewPublicationResolutionWorkflowTest.php tests/Feature/EnvironmentReview/Spec387ReviewPublicationResolutionDecisionUxTest.php tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec389GovernanceInboxResolutionIntakeTest.php` if browser test exists
  - `cd apps/platform && ./vendor/bin/pint --dirty --format agent`
  - `git diff --check`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Triage Active Resolution Work (Priority: P1)

As an operator, I can open the existing Governance Inbox and see active Review Publication Resolution work that needs attention, waiting, re-check, or continuation.

**Why this priority**: This is the core value: hidden resolution cases become visible without creating a new workflow center.

**Independent Test**: Seed active Review Publication Resolution Cases for an accessible workspace/environment and verify the Governance Inbox shows operator-friendly items, hides completed/cancelled/superseded cases by default, and sorts failed/blocked ahead of waiting/ready items.

**Acceptance Scenarios**:

1. **Given** an active resolution case with a missing required report step, **When** an authorized operator opens Governance Inbox, **Then** the item appears with a review-publication label, affected environment/review, "Required reports are missing", and "Continue preparation".
2. **Given** completed, cancelled, and superseded resolution cases, **When** the default inbox is rendered, **Then** those cases do not appear in active work.
3. **Given** failed, blocked, needs-attention, needs-recheck, ready, and waiting cases, **When** the inbox renders active work, **Then** failed and blocked items are prioritized before ordinary waiting items.

---

### User Story 2 - Continue Safely Without Inline Execution (Priority: P1)

As an operator, I can continue or inspect preparation from the inbox, but the inbox never executes a resolution step, starts a provider check, refreshes a review, prepares an export, cancels a resolution, or publishes a review.

**Why this priority**: The inbox must not bypass the decision context and confirmation model hardened by Specs 386 and 387.

**Independent Test**: Render the Governance Inbox for executable and read-only users and verify links navigate only to existing authorized pages while no mutating buttons or publish/cancel actions are present.

**Acceptance Scenarios**:

1. **Given** an operator can execute the current step, **When** they see the inbox item, **Then** the primary action is "Continue preparation" and navigates to the Resolution Page.
2. **Given** a read-only operator can inspect the case but cannot execute the step, **When** they see the inbox item, **Then** the action is "Inspect preparation" or a safe continue link and no executable step action is shown in the inbox.
3. **Given** any resolution item, **When** the inbox renders actions, **Then** there is no "Publish review", "Update required reports", "Collect evidence", "Refresh review", "Prepare export", or "Cancel resolution" action.

---

### User Story 3 - Enforce Scope, RBAC, and Customer Safety (Priority: P1)

As a workspace operator, I only see resolution items, review links, and operation links for environments and cases I am entitled to inspect; customer-facing users see none of this internal intake.

**Why this priority**: The inbox aggregates work across environments, so leakage risk is higher than on a single review detail page.

**Independent Test**: Seed foreign workspace/environment/review/case/operation combinations and customer-facing users, then verify hidden items and hidden operation links without counts or IDs leaking.

**Acceptance Scenarios**:

1. **Given** a resolution case belongs to another workspace or environment, **When** the user opens Governance Inbox, **Then** no item, count, operation ID, or link is disclosed.
2. **Given** a linked OperationRun exists but belongs to another case, review, environment, workspace, unexpected type, stale step, or inaccessible viewer, **When** the inbox renders, **Then** no operation URL or ID is shown.
3. **Given** a customer-facing workspace user opens customer surfaces, **When** internal resolution cases exist, **Then** no internal resolution item, proof state, operation link, or preparation metadata appears.

---

### User Story 4 - Fall Back Conservatively For Unsafe Currentness (Priority: P2)

As an operator, I would rather see "Needs re-check" than a stale failed/waiting/ready state presented as current truth.

**Why this priority**: Spec 388 exists because false readiness is dangerous. Inbox list rendering must not become a second proof engine.

**Independent Test**: Create stale failed/running/cross-scope/unknown proof scenarios and verify the inbox maps them to "Needs re-check" with a continuation link rather than optimistic failed/waiting/ready states.

**Acceptance Scenarios**:

1. **Given** a failed step references an operation that may be stale, **When** the inbox cannot validate currentness cheaply and safely, **Then** the item status is "Needs re-check".
2. **Given** a running operation link is not current/scope-valid/context-valid for the displayed case/step, **When** the inbox renders, **Then** it does not show "Open operation" and falls back to "Needs re-check" or non-linked safe text.
3. **Given** proof is hidden, operator-limited, inspection-only, failed, stale, or unknown, **When** the item is mapped, **Then** it does not produce "Ready to continue".

## Functional Requirements *(mandatory)*

- **FR-389-001**: The existing Governance Inbox MUST include active Review Publication Resolution Cases as work items using the item type `review_publication_resolution`.
- **FR-389-002**: The implementation MUST NOT add a new top-level navigation item, global search resource, generic CRUD resource, workflow engine, generic task model, adapter registry, or generic resolution-type registry.
- **FR-389-003**: The Governance Inbox MUST be read-only for this intake. It MUST NOT execute resolution steps, start provider checks, start Entra scans, collect evidence, refresh reviews, prepare exports, cancel resolution cases, mutate OperationRuns, or publish reviews.
- **FR-389-004**: The default active view MUST show `needs_attention`, `needs_recheck`, `waiting`, `ready_to_continue`, `failed`, and `blocked` items when visible to the viewer.
- **FR-389-005**: The default active view MUST hide `completed`, `cancelled`, and `superseded` cases unless an explicit completed/history filter is implemented.
- **FR-389-006**: Item status MUST be viewer-relative and MUST NOT be persisted back to `ReviewPublicationResolutionCase` or `ReviewPublicationResolutionStep`.
- **FR-389-007**: The inbox MUST use existing Spec 388 proof/currentness semantics, safe summaries, or persisted safe case/step state only when not contradicted by currentness rules.
- **FR-389-008**: The inbox MUST NOT infer readiness directly from raw OperationRun, StoredReport, EvidenceSnapshot, ReviewOutput, ReviewPack, persisted proof summary, operation IDs, readiness fingerprints, or internal step keys.
- **FR-389-009**: If the provider cannot cheaply and safely validate state currentness for list rendering, the item MUST show "Needs re-check" and link to the Resolution Page.
- **FR-389-010**: A failed step MUST map to `failed` only when the failure is current, scope-valid, context-valid, and safe for the displayed case/step/viewer; otherwise it MUST map to `needs_recheck`.
- **FR-389-011**: A running operation MUST map to `waiting` only when the OperationRun is current, scope-valid, context-valid, expected type, belongs to the current case/step, and is visible to the viewer; otherwise it MUST map to `needs_recheck` or non-linked safe waiting copy.
- **FR-389-012**: Ready-to-continue MUST NOT be shown when proof is unknown, hidden, operator-limited, stale, failed, inspection-only, or otherwise not usable to complete the relevant step.
- **FR-389-013**: Every query MUST be constrained by workspace, authorized environment IDs where applicable, and current user access before mapping.
- **FR-389-014**: A user may see an item only when they can access the workspace, the environment, the Environment Review, and the safe resolution summary.
- **FR-389-015**: Customer-facing users and customer workspace surfaces MUST NOT see internal resolution intake items, proof state, OperationRun details, internal reason codes, or internal preparation metadata.
- **FR-389-016**: Every actionable item MUST expose one primary next action. The default primary action is "Continue preparation"; read-only users may see "Inspect preparation".
- **FR-389-017**: `Continue preparation` and `Inspect preparation` MUST navigate to the existing Review Publication Resolution Page and MUST NOT execute a step from the inbox.
- **FR-389-018**: `Open review` may appear only when the viewer can access the review under existing RBAC/scope rules.
- **FR-389-019**: `Open operation` may appear only when operation disclosure passes workspace, environment, review, case, current step, expected operation/action type, currentness, and RBAC checks. It may be the primary action only for a validated `waiting` item where opening the operation is the safest next action; otherwise it must be secondary or hidden.
- **FR-389-020**: The implementation MUST NOT build operation URLs directly from persisted step metadata without revalidating the OperationRun relationship.
- **FR-389-021**: If operation disclosure fails, the inbox MUST hide operation IDs and URLs and show safe non-linked text such as "Operation is running" or "Preparation status needs to be refreshed".
- **FR-389-022**: Item copy MUST be operator-facing: "Review can't be published yet", "Required reports are missing", "Continue preparation", "Waiting for operation", and "Needs re-check" are valid; raw step keys, proof reason codes, `readiness_fingerprint`, and model names are not valid default copy.
- **FR-389-023**: Safe metadata MUST be display-oriented and MUST NOT include raw provider payloads, Graph responses, raw evidence/report contents, exception messages, secrets, tokens, readiness fingerprints, proof reason codes by default, internal step keys by default, or unvalidated operation IDs.
- **FR-389-024**: Default sorting MUST prioritize failed, blocked, needs-attention, needs-recheck, ready-to-continue, waiting, then newest updated item within each group.
- **FR-389-025**: The inbox MUST provide bounded filters for status, environment, type/source family, and updated date using the existing Governance Inbox pattern where possible, without introducing a generic resolution-type registry. Updated-date v1 options MUST be bounded presets: `Any time`, `Last 24 hours`, `Last 7 days`, and `Last 30 days`.
- **FR-389-026**: Empty states MUST cover no active resolution work, no accessible review publication work, and filter no results without revealing inaccessible counts.
- **FR-389-027**: Viewing inbox items MUST NOT emit audit events by default.
- **FR-389-028**: No schema migration should be added unless implementation proves an existing index is insufficient and this spec is updated with the justification.

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

- **ReviewPublicationResolutionCase**: Existing review-publication-specific workflow state from Spec 386. It remains source state for active/completed/cancelled/superseded lifecycle and current step reference.
- **ReviewPublicationResolutionStep**: Existing ordered step state with safe summaries, proof metadata, and optional OperationRun/artifact references.
- **EnvironmentReview**: Existing subject review affected by publication preparation.
- **OperationRun**: Existing execution truth. It may be linked only after scope/context/currentness/RBAC validation.
- **Governance Inbox Item**: Derived display item only. It is not persisted and must not become canonical readiness truth.

## Status and Severity Model

Allowed v1 inbox statuses:

- `needs_attention`
- `needs_recheck`
- `waiting`
- `ready_to_continue`
- `failed`
- `blocked`
- `completed`
- `cancelled`
- `superseded`

Recommended severity mapping:

- `failed` -> `high`
- `blocked` -> `high`
- `needs_attention` -> `medium`
- `needs_recheck` -> `medium`
- `ready_to_continue` -> `medium`
- `waiting` -> `info`
- `completed` -> `info`
- `cancelled` -> `info`
- `superseded` -> `info`

Critical severity is reserved for platform-wide or security-impacting issues and is not a normal review-preparation status.

## Out of Scope

- Generic workflow engine, generic adapter registry, generic provider system, generic task queue, or PSA/ticketing replacement.
- New top-level navigation, new global search resource, new Review Publication Resolution data model, new proof/currentness model, or customer-facing resolution inbox.
- Restore resolution intake, provider onboarding resolution intake, evidence/baseline readiness intake, report delivery readiness intake, cross-tenant promotion intake, notifications, email/Teams routing, assignment workflow, SLA/escalation engine, auto-publish, or inline mutating actions.
- Raw provider/evidence/report payload display, raw Graph payload display, raw exception messages, token/secret display, readiness-fingerprint display, and default proof reason-code display.

## Edge Cases

- Case has no current step: show `Needs re-check` and link to Resolution Page if visible.
- Step references an OperationRun that no longer exists: hide operation link and show `Needs re-check`.
- Step references an OperationRun from another workspace/environment/review/case: hide ID/link and show `Needs re-check`.
- Case status is completed but proof became stale after the last evaluation: hide from default if completed, or show `Needs re-check` if still active and unsafe.
- User can inspect but not execute: item remains visible only if the case/review is visible, but action label becomes inspection-safe.
- Selected environment filter excludes visible work elsewhere: reuse existing calm filtered empty-state behavior.
- User can access Governance Inbox but no Review Publication Resolution cases: show no active resolution work without implying inaccessible counts.

## Success Criteria *(mandatory)*

- **SC-389-001**: Operators can identify active review publication preparation work from the Governance Inbox without first opening the affected Review detail page.
- **SC-389-002**: In focused tests, completed, cancelled, and superseded cases are absent from the default active inbox.
- **SC-389-003**: In focused tests, no inline publish, cancel, provider-check, Entra scan, evidence collection, review refresh, report update, or export preparation action is rendered in the inbox.
- **SC-389-004**: In focused RBAC/scope tests, foreign workspace/environment/review/case records and invalid OperationRun links are hidden without ID or count leakage.
- **SC-389-005**: In currentness tests, stale/unknown/unsafe proof maps to `Needs re-check` rather than false `Failed`, `Waiting`, or `Ready to continue`.
- **SC-389-006**: In safe-metadata tests, rendered/default item metadata contains no readiness fingerprint, proof reason code by default, raw payload, raw exception, secret, token, or unvalidated operation ID.
- **SC-389-007**: Browser smoke, if available, shows desktop and mobile inbox items with decision-first copy and no customer-facing leakage.

## Acceptance Criteria

- **AC-389-01**: Active Review Publication Resolution Cases appear in the existing Governance Inbox.
- **AC-389-02**: Completed, cancelled, and superseded cases are hidden by default.
- **AC-389-03**: Inbox items use decision-first labels and not internal case terminology, step keys, proof reason codes, or currentness internals.
- **AC-389-04**: Each item has one primary next action.
- **AC-389-05**: Governance Inbox does not directly execute resolution steps.
- **AC-389-06**: Governance Inbox does not show or trigger Publish Review.
- **AC-389-07**: Foreign workspace/environment cases are hidden.
- **AC-389-08**: Users only see cases, operation links, and review links they are allowed to inspect.
- **AC-389-09**: Customer-facing workspace does not show internal Resolution Inbox items.
- **AC-389-10**: No workflow engine, adapter registry, generic tasks system, global search resource, or top-level navigation is introduced.
- **AC-389-11**: Governance Inbox does not independently infer proof/currentness from raw metadata and falls back to `Needs re-check` when unsafe.
- **AC-389-12**: OperationRun links are shown only when current, scope-valid, context-valid, expected type, and RBAC-authorized.
- **AC-389-13**: Inbox safe metadata contains no raw provider/evidence/report payloads, tokens, secrets, raw exception messages, readiness fingerprints, proof reason codes by default, or unvalidated operation IDs.

## Assumptions

- Spec 388 behavior is stable enough for read-only consumption before Spec 389 implementation starts.
- Existing Governance Inbox source-family patterns can support one concrete additional family without creating a generic registry.
- Existing Review Publication Resolution Page remains the only execution context for preparation steps.
- Existing `ReviewPublicationResolutionCasePolicy`, `OperationRunPolicy`, `OperationRunLinks`, and Environment Review resource URLs remain the baseline for navigation and authorization checks.
- No database migration is needed for v1 because Spec 386 already added status/assigned/index coverage.

## Open Questions

- No blocker open question. Implementation should verify whether the existing `GovernanceInboxSectionBuilder` should be extended directly or delegated to a concrete `ReviewPublicationResolutionInboxProvider`; either is acceptable if it remains concrete and non-generic.

## Follow-up Spec Candidates

- Restore Readiness Resolution Intake v1.
- Provider Onboarding & Permissions Resolution Intake v1.
- Evidence/Baseline Readiness Resolution Intake v1.
- Report Delivery Readiness Resolution v1.
- Cross-Tenant Promotion Resolution Intake v1.
- Notification or assignment workflows for governance work, only after source-specific intake proves trustworthy.

## Done Definition

Spec 389 is done when active Review Publication Resolution Cases appear in the Governance Inbox with correct scope/RBAC/currentness behavior; default active view hides completed/cancelled/superseded cases; failed/blocked cases sort before waiting/ready; `Needs re-check` is used for stale/unknown/unsafe states; labels are decision-first; actions only navigate; operation links are revalidated; no customer leakage, inline mutation, publish action, generic engine, global search resource, or top-level navigation exists; focused tests pass; browser smoke and screenshots are captured if available; and the git diff contains only Spec 389-related files.