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
• 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
• Status/evidence/review presentation changed
• 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
  • 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.