TenantAtlas/specs/346-governance-inbox-final-operator-workflow/spec.md

Feature Specification: Spec 346 - Governance Inbox Final Operator Workflow

Feature Branch: 346-governance-inbox-final-operator-workflow
Created: 2026-06-02
Status: Draft
Type: Platform productization / operator workflow / governance inbox closeout
Runtime posture: Narrow runtime productization over an existing strategic surface. No new governance engine or new persisted workflow truth.
Close-out posture: Not closed. The bounded density/productization polish requested on 2026-06-02 remains part of Spec 346 before close-out is claimed.
Input: User-provided full Spec 346 draft + repo truth from Specs 250, 257, 265, 306, 307, 308, 327, 338-345.

Dependencies And Historical Context

Depends on the existing governance and scope line:

• Spec 250 - Decision-Based Governance Inbox v1
• Spec 257 - Governance Decision Surface Convergence
• Spec 265 - Decision Register & Approval Workflow v1
• Spec 306 - Decision Register Reconciliation
• Spec 307 - Decision Register Evidence / OperationRun Link Polish
• Spec 308 - Decision Register Summary / Review Pack Inclusion
• Spec 327 - Governance Inbox Decision-First Workbench Productization
• Specs 338-341 - workspace / environment scope and canonical-link contracts
• Specs 342-344 - customer review completion, accepted-risk productization, and audience polish
• Spec 345 - Platform Productization Readiness / Roadmap Reconciliation Gate

Repo truth adjustment:

• apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php already exists and is repo-real.
• apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php already composes the current families:
  • assigned_findings
  • intake_findings
  • finding_exceptions
  • stale_operations
  • alert_delivery_failures
  • review_follow_up
• apps/platform/app/Filament/Pages/Governance/DecisionRegister.php is already the historical/proof-oriented decision ledger.
• The current UI audit route inventory tracks Governance Inbox as UI-028, with page report docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md, not a new ui-008-* artifact.
• Existing test truth lives primarily under:
  • apps/platform/tests/Feature/Governance/*
  • apps/platform/tests/Feature/Navigation/*
  • apps/platform/tests/Browser/Spec327GovernanceInboxProductizationSmokeTest.php

Spec 346 must therefore productize the existing page, route, builder, and shared link/filter contracts instead of inventing a new queue family, a new persistence layer, or a second decision home.

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

• Problem: Governance Inbox is repo-real and already shows governance attention, but it still reads more like a dense admin queue than the calm daily operator worklist that answers what needs attention, why it matters, and what the next action is.
• Today's failure: Operators can see findings, exceptions, operations, alerts, and review follow-up, but still need to reconstruct whether an item needs triage, a decision, evidence, risk review, or review handoff. The page does not yet consistently separate active work from blocked, review-ready, or recently resolved context.
• User-visible improvement: /admin/governance/inbox becomes the central operator queue for governance work: summary first, actionable lanes, explicit reason and impact, one primary next action per item, clear downstream links, visible environment filter state, and calmer disclosure of diagnostics.
• Smallest enterprise-capable version: Rework only the existing Governance Inbox page, its view, and its derived payload composition over current repo-backed records. Add targeted Feature and Browser proof for lane classification, scope-correct links, empty/blocked/resolved states, and first-screen scanability.
• Explicit non-goals: No new governance engine, no new persisted inbox item, no Kanban board, no PSA/helpdesk handoff, no customer portal, no Decision Register rebuild, no broad Findings or Customer Review Workspace rewrite, no provider readiness redesign, no new workflow mutation surface by default, no new status family unless current repo truth proves one is unavoidable and proportional.
• Permanent complexity imported: One page-local operator lane contract, one repo-truth map, one lane-classification artifact, focused Feature tests, one bounded Browser smoke file, and screenshot artifacts. No new table, no global abstraction, no public framework, and no new persisted source of truth.
• Why now: Spec 345 explicitly identifies Governance Inbox Final Operator Workflow as the next central productization gap after shell/scope closure and customer-review maturity. The backlog wording is stale relative to current runtime truth; the operator queue itself is now the clearest remaining daily-use blocker.
• Why not local: Copy-only tweaks or one more summary card would leave the operator reconstruction problem intact. A new workboard would overbuild. The narrow correct slice is a derived, decision-oriented final workflow pass over the existing inbox runtime.
• Approval class: Core Enterprise.
• Red flags triggered: One strategic-surface and one cross-surface composition flag. Defense: the slice stays on one existing page, reuses existing truth and routes, forbids new persistence/frameworks, and explicitly preserves completed specs as context only.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source:
  • direct user-provided Spec 346 draft
  • docs/product/spec-candidates.md manual-promotion backlog item decision-based-governance-inbox-v1
  • docs/product/roadmap.md decision-based governance inbox priority lane
  • specs/345-platform-productization-readiness-roadmap-reconciliation-gate/next-spec-recommendation.md
• Completed-spec guardrail result:
  • no specs/346-* package existed before this prep
  • related Specs 250, 257, 265, 306, 307, 308, 327, 342, 343, 344, and 345 contain prepared, validated, completed-task, close-out, review-outcome, or implementation-history signals and are treated as historical context only
  • these related packages must not be rewritten, normalized, or converted back into preparation-only wording
• Close alternatives deferred:
  • provider readiness / onboarding productization
  • evidence and retained artifact lifecycle follow-through
  • localization and customer-safe copy hardening
  • PSA / ITSM handoff
• Smallest viable implementation slice: Existing Governance Inbox only: operator summary first, lane grouping over repo-real items, visible environment_id filter, scope-correct deep links into existing surfaces, calmer empty/blocked/resolved treatment, and focused tests/browser smoke.

Spec Scope Fields (mandatory)

• Scope: workspace canonical-view governance operator queue, optionally filtered by visible environment_id.
• Primary Routes:
  • existing route /admin/governance/inbox
  • related existing route /admin/governance/decisions
  • linked existing workspace or environment surfaces for findings, finding exceptions, evidence, reviews, operations, and provider/readiness destinations when repo-backed
• Data Ownership:
  • Finding remains the source of truth for findings, owner/due, severity, evidence summary, and current primary remediation/triage path
  • FindingException and FindingExceptionDecision remain the accepted-risk / exception truth
  • ManagedEnvironmentTriageReview, EnvironmentReview, EnvironmentReviewAcknowledgement, and ReviewPack remain the review/customer-safe handoff truth
  • EvidenceSnapshot and related artifact resources remain evidence truth
  • OperationRun plus existing run-link helpers remain operation proof truth
  • AlertDelivery remains alert-delivery failure truth
  • WorkspaceHubEnvironmentFilter, WorkspaceHubNavigation, and canonical navigation helpers remain scope/filter truth
  • the inbox itself remains a derived read surface only
• RBAC:
  • workspace membership is required
  • environment filtering must resolve only through current-workspace entitled environments
  • non-members and out-of-scope environment_id requests remain deny-as-not-found
  • existing family/resource policies and capabilities remain authoritative for which lanes, items, and actions are visible
  • the page must not hint at hidden work from invisible families or hidden environments

For canonical-view specs:

• Default filter behavior when tenant-context is active: clean /admin/governance/inbox must remain workspace-wide and must not inherit remembered environment shell state, hidden topbar environment context, legacy query aliases, or stale table filters.
• Explicit entitlement checks preventing cross-tenant leakage: ?environment_id= must be visible, local to the page, resolved through current workspace membership, and denied as not found when out of scope.

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")

• Route/page/surface: /admin/governance/inbox, GovernanceInbox, governance-inbox.blade.php, GovernanceInboxSectionBuilder
• Current or new page archetype: Strategic operator queue / governance inbox workbench, continuing UI-028
• Design depth: Strategic Surface
• Repo-truth level: repo-verified existing runtime surface
• Existing pattern reused: existing Governance Inbox page, workspace hub filter chip, Decision Register linkage, current shared navigation/link helpers, current page report ui-004-governance-inbox.md
• New pattern required: bounded page-local lane grouping and operator summary over existing truth; no new global runtime pattern
• Screenshot required: yes, under specs/346-governance-inbox-final-operator-workflow/artifacts/screenshots/
• Page audit required: update the existing Governance Inbox page report docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md if the runtime diff changes the documented hierarchy materially; do not invent ui-008-* by default
• Customer-safe review required: operator-facing surface only, but downstream wording must remain customer-safe where review-ready or accepted-risk states appear
• Dangerous-action review required: no new dangerous action is expected. If a new governance mutation appears necessary, the spec and plan must be updated first and the action must follow confirmation, authorization, audit, and test rules
• 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
  • N/A - no reachable UI surface impact
• No-impact rationale when applicable: N/A

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, action links, workspace hub filtering, evidence/proof links, review/review-pack links, navigation continuity, governance queue hierarchy
• Systems touched:
  • GovernanceInbox
  • GovernanceInboxSectionBuilder
  • DecisionRegister
  • findings / finding-exception queues and detail resources
  • CustomerReviewWorkspace
  • evidence and review-pack resources
  • OperationRunLinks
  • workspace hub filter and navigation helpers
• Existing pattern(s) to extend: current inbox family payloads, workspace hub filter chip, canonical navigation/back-link behavior, current source routes and policy checks
• Shared contract / presenter / builder / renderer to reuse: GovernanceInboxSectionBuilder, CanonicalNavigationContext, WorkspaceHubEnvironmentFilter, WorkspaceHubNavigation, OperationRunLinks, current resource/page URL helpers and policies
• Why the existing shared path is sufficient or insufficient: existing paths are sufficient for truth, authorization, and drill-through. They are insufficient only for the final operator queue hierarchy because they still present family-level attention more prominently than the queue-clearing decision model.
• Allowed deviation and why: one bounded page-local derived lane contract or DTO is allowed if it keeps summary and item rendering testable without becoming a reusable workflow engine
• Consistency impact: lane copy, next-action labels, environment scope, evidence/proof labels, and customer-safe wording must stay aligned with current findings, exception, evidence, review, and Decision Register language
• Review focus: block any second decision home, new persisted queue state, unauthorized hidden-work hinting, diagnostics-first hierarchy, or local mutation semantics that duplicate existing surfaces

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: deep-link semantics only
• Shared OperationRun UX contract/layer reused: existing OperationRunLinks and existing operations page/resource URLs
• Delegated start/completion UX behaviors: N/A - no new operation start or lifecycle
• Local surface-owned behavior that remains: show blocked/proof context and operation-link next action only where current repo truth already supports it
• Queued DB-notification policy: N/A
• Terminal notification path: unchanged
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: no new provider seam
• Boundary classification: platform-core operator workflow over existing environment-bound governance records
• Seams affected: presentation and routing only
• Neutral platform terms preserved or introduced: workspace, environment, governance inbox, decision, evidence, review-ready, accepted risk, blocked, proof, diagnostics
• Provider-specific semantics retained and why: any Microsoft/Intune wording remains only where the underlying repo-backed source item already uses it
• Why this does not deepen provider coupling accidentally: no Graph calls, no provider models, no provider connection changes, and no new provider-shaped persistence are introduced
• Follow-up path: provider readiness/onboarding productization remains a separate follow-up spec

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Governance Inbox page	yes	Native Filament page plus existing Blade composition	governance queues, evidence/proof links, review linkage, navigation continuity	page, URL-query, derived payload	no	Existing route only
Operator summary zone	yes	page-local composition	queue-clearing summary, lane counts, primary next action	page payload	no	Repo-backed counts only
Lane groups	yes	page-local composition	decision-first work grouping over current families	page payload	no	Derived only; no new persistence
Work item cards / rows	yes	page-local composition over existing sections/items	reason, impact, next action, linked context	page payload	no	Must stay source-backed
Recently resolved / diagnostics areas	yes	page-local composition	disclosure hierarchy and calmness	page payload	no	Secondary or collapsed only

Decision-First Surface Role

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	Primary Decision Surface	Operator decides what governance work to clear next	summary counts, lane, reason, impact, environment, age/state, primary next action	proof links, evidence detail, review context, decision history, technical diagnostics	Primary because it is the central operator queue	follows what needs my attention now? before what does this record contain?	removes cross-page reconstruction
Decision Register	Secondary Context	Operator verifies historical decision/proof truth for a selected governance item	decision ledger and proof context	deeper decision history and related proof	Secondary because it is the ledger, not the queue	complements the inbox without replacing it	keeps history visible without flattening queue work
Diagnostics disclosure	Tertiary Evidence / Diagnostics	Support or operator confirms technical detail after choosing a path	collapsed availability only	raw/source diagnostics where authorized	Not primary	preserves support depth without dominating queue hierarchy	prevents debug-first experience

Audience-Aware Disclosure

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	operator-MSP, manager, support where authorized	lane, reason, impact, source, environment, linked context, primary next action	blocked reason, proof path, review/evidence/decision linkage	raw payloads, debug metadata, secrets, stack traces, low-level provider diagnostics	context-aware navigation action	diagnostics and raw detail	summary tells the operator once what matters; later sections add proof only
Decision / proof context inside inbox	operator-MSP, support where authorized	customer-safe and operator-safe proof summary	linked review/evidence/operation detail	raw payloads and internal-only support detail	one dominant open/review action	raw detail and unauthorized links	no repeated queue-level summary in every linked section

UI/UX Surface Classification

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	Utility / Workspace Decision	Read-only workflow hub	review or clear the next governance item	explicit primary action per item or section	forbidden unless implementation proves a native pattern fits cleanly	secondary links beside or below the primary action	none by default	/admin/governance/inbox	existing source routes only	workspace shell, visible environment filter, lane, source, state	Governance inbox	why item appears, why it matters, what to do next	none
Decision Register	Utility / Evidence Ledger	Read-only register	open the related decision/proof context	explicit existing register affordance	current repo-real behavior only	existing secondary proof links	none	/admin/governance/decisions	existing decision detail path	workspace shell, visible environment filter, register state	Decision register	historical/proof truth	existing runtime contract remains authoritative

Operator Surface Contract

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/workspace operator	choose the next governance item and route into the owning surface	workspace operator queue	What needs my attention, why does it matter, and what should I do next?	operator summary, lanes, reason, impact, source, environment, linked context, next action	raw diagnostics, debug metadata, low-level support detail	queue lane, urgency, evidence state, accepted-risk/exception state, blocked/review-ready/resolved posture	none by default	review finding, open decision register, review exception, open evidence, open review workspace, open operation, open provider readiness	none by default

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: possibly one page-local derived lane/view-model helper only
• New enum/state/reason family?: no persisted family; lane keys stay derived and local unless current repo truth proves a reused constant set is already available
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: the repo-real Governance Inbox does not yet answer in one calm place whether an item needs triage, decision, risk review, evidence, customer review handoff, or support follow-up
• Existing structure is insufficient because: the current workbench and family sections still expose families more directly than the operator workflow, and active vs blocked vs recently resolved context is not clearly separated
• Narrowest correct implementation: derive operator lanes and a top summary over existing inbox sections/items, keep all routing on existing surfaces, and add tests/browser smoke
• Ownership cost: one lane contract artifact, page-local mapping logic, feature tests, browser smoke, and UI-report update
• Alternative intentionally rejected: a new governance work engine, persisted inbox-item table, new decision entity, or cross-domain queue framework
• Release truth: current-release operator workflow closure over existing governance truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility shims, legacy query aliases, or new compatibility paths are out of scope unless explicitly required by repo truth. Canonical environment_id behavior remains the only supported public filter contract.

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

• Test purpose / classification: Feature, Browser
• Validation lane(s): confidence, browser
• Why this classification and these lanes are sufficient: Feature tests can prove lane classification, environment scope, empty/blocked/resolved states, and scope-correct link contracts cheaply. One bounded Browser smoke is required because this is a strategic operator surface and first-screen scanability is part of the product promise.
• New or expanded test families:
  • apps/platform/tests/Feature/Governance/Spec346GovernanceInboxOperatorWorkflowTest.php
  • apps/platform/tests/Feature/Navigation/Spec346GovernanceInboxScopeContractTest.php
  • apps/platform/tests/Browser/Spec346GovernanceInboxOperatorWorkflowSmokeTest.php
  • focused updates to existing Governance Inbox and workspace-hub filter tests only when reuse is more proportional than new files
• Fixture / helper cost impact: moderate. Reuse existing governance inbox fixtures and current factories for findings, finding exceptions, review follow-up, and operation proof. Avoid broad suite-wide fixture widening.
• Heavy-family visibility / justification: one explicit Browser smoke only
• Special surface test profile: global-context-shell plus decision-first disclosure
• Standard-native relief or required special coverage: special coverage required for summary-first hierarchy, lane grouping, blocked/empty states, environment filter visibility, and downstream link continuity
• Reviewer handoff: reviewers must confirm no hidden environment context, no forbidden query aliases, no new mutation lane, no false calmness, diagnostics-secondary ordering, and unchanged panel-provider/global-search/destructive-action posture
• Budget / baseline / trend impact: one explicit browser smoke addition; no broader lane expansion expected
• Escalation needed: document-in-feature if an unreachable state cannot be proven without scope creep; follow-up-spec if the page reveals missing backend truth rather than a UI/productization gap
• Active feature PR close-out entry: Guardrail / Smoke Coverage
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Governance/Spec346GovernanceInboxOperatorWorkflowTest.php tests/Feature/Navigation/Spec346GovernanceInboxScopeContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec346GovernanceInboxOperatorWorkflowSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

Problem Statement

TenantPilot already has substantial governance building blocks:

• findings
• finding exceptions / accepted-risk truth
• evidence snapshots
• review packs and review workspace surfaces
• Decision Register
• operation proof
• workspace/environment filters
• audit records

The remaining product gap is not another backend foundation. It is the daily operator question:

What needs my attention, why does it matter, and what should I do next?

Governance Inbox must become the calm operator queue that connects current truth into actionable items without inventing a second governance system.

Product Intent

Governance Inbox is the operator command surface for governance work.

It is:

• not a raw table
• not a customer portal
• not a legal/compliance approval system
• not a new GRC engine

It is the workspace-owned queue that groups existing governance signals into clear next actions.

Current Repo Truth Summary

• The current page already has:
  • a decision workbench
  • a secondary queue context
  • visible environment_id filtering
  • existing navigation and proof links
  • current tests and browser smoke from Spec 327
• The current builder currently groups by source family, not final operator workflow lane.
• DecisionRegister already exists and should stay the ledger/proof context, not become the queue.
• Existing page audit ui-004-governance-inbox.md already states the unresolved issues this spec should close:
  1. one dominant queue-clearing action model
  2. clearer separation of decision evidence and status dimensions
  3. customer-safe downstream wording review

Goals

1. Make Governance Inbox action-oriented.
2. Group active work into clear operator lanes.
3. Keep workspace/environment scope explicit and local.
4. Reuse existing findings, exception, evidence, review, decision, and operation surfaces.
5. Make decision/risk/evidence/review states visible without opening three other pages first.
6. Preserve calm, operator-safe, non-legalistic wording.
7. Add focused Feature and Browser proof for operator workflow behavior.

Scope Boundaries

In Scope

• existing Governance Inbox page, view, and derived payload composition
• lane grouping over current repo-real governance items
• operator summary first
• visible environment_id filter state
• scope-correct links into existing findings, decision, evidence, review, operation, and readiness surfaces where repo-backed
• productized empty, blocked, and recently resolved treatment
• targeted tests, browser smoke, screenshots, and updated page-report coverage

Non-Goals

• new persisted queue state or workflow engine
• a new decision table or Decision Register rewrite
• customer portal or external customer routes
• PSA/ITSM handoff
• provider execution logic or provider readiness redesign
• broad shell/navigation rewrite
• review/evidence generation rewrite
• new legal approval/signature workflow
• broad notification platform work
• AI prioritization or autonomous governance behavior

Functional Requirements

• FR-346-001 Summary first: Governance Inbox must start with an operator summary that shows total visible governance work plus counts for the active lane model in the current scope.
• FR-346-002 Lane grouping: Governance Inbox must group active work into derived operator lanes instead of exposing source families alone as the primary hierarchy.
• FR-346-003 Minimal truthful lane set: The implementation must ship the smallest truthful lane set over existing runtime data. Needs triage, Requires decision, Risk / exception review, and Blocked are the minimum target lanes. Evidence required, Review-ready, and Recently resolved must appear only when current repo truth can derive them without inventing new persistence or state families.
• FR-346-004 Reason / impact / next action: Every visible active item must show why it appears, why it matters, and one primary next action.
• FR-346-005 Visible local environment filter: /admin/governance/inbox?environment_id={environment} must remain the visible public scope contract. No hidden topbar/session-only environment filtering is allowed.
• FR-346-006 Scope-correct links: Environment-owned detail links must preserve current scope rules and must not emit retired public query contracts such as tenant, tenant_id, managed_environment_id, or tableFilters.
• FR-346-007 Empty state: The empty state must explain that there are no governance items needing attention in the current scope and must not look like missing data.
• FR-346-008 Blocked state: Blocked items must show blocker reason and a truthful next action into the owning proof/readiness surface when available.
• FR-346-009 Resolved items stay secondary: recently resolved or acknowledged work may appear, but must not dominate active operator workload.
• FR-346-010 Decision Register linkage: items requiring decision must link to the existing Decision Register or existing decision-owning detail surfaces instead of inventing a new decision workflow.
• FR-346-011 Review linkage: review-ready or customer-safe follow-up items must link to current review surfaces using the visible environment_id contract when applicable.
• FR-346-012 Diagnostics secondary: technical diagnostics must remain secondary, collapsed, or otherwise de-emphasized relative to the queue-clearing decision hierarchy.
• FR-346-013 Render contract hardening: every rendered lane, badge/count, action, source entry, and link payload must expose consistent keys before Blade consumes it. Missing action URLs must become absent actions, not partial arrays.
• FR-346-014 First viewport recommended action: when active work exists, the first viewport must expose a prioritized recommended item with a direct primary action, not only a summary-level lane CTA.
• FR-346-015 Zero-lane weight reduction: lanes with zero items must be visually secondary as compact clear indicators or equivalent compact status, while active lanes remain prominent.
• FR-346-016 Mobile card compression: active item cards must keep title, lane/status, environment, reason, impact, and primary action visible; source, owner/due, evidence, accepted-risk/decision, linked records, and secondary actions must be secondary or collapsible.
• FR-346-017 Hash lane behavior: if the UI emits #lane-* links, the target lane must scroll/anchor correctly or be visibly marked. Unsupported hash behavior must be removed or deferred.

Non-Functional Requirements

• NFR-346-001 Enterprise calmness: first screen must be scannable and must not present equal-weight cards, repeated green success states, or raw diagnostic blocks as the primary story
• NFR-346-002 Operator-first language: use operator-safe language such as review, decision recorded, accepted risk, blocked, requires attention, and ready for review; avoid legal/compliance overclaims
• NFR-346-003 Performance: no unbounded workspace scan. Counts and lane previews must remain bounded and eager-load only what the current view needs
• NFR-346-004 Accessibility: semantic lane headings, text-backed badges, keyboard-reachable actions, readable empty states, and non-color-only status cues
• NFR-346-005 No hidden scope: no remembered environment or hidden shell state may silently alter page data

Assumptions

• current Governance Inbox section items contain enough repo-backed data to derive a calm operator-lane contract without new persistence
• Decision Register remains the correct historical/proof surface and does not need new lifecycle semantics for this slice
• current review/evidence/run links are sufficient for truthful handoff when they exist, and omission/unavailable states are acceptable when they do not
• current page-report and route-inventory entries are stable enough that updating ui-004-governance-inbox.md is more truthful than inventing a new page ID

Risks

• Scope creep into a task engine: mitigated by explicit prohibition on new persistence/frameworks
• Overconfident lane semantics: mitigated by repo-truth-first lane-classification artifact and conservative omission of unsupported lanes
• Noisy first screen: mitigated by summary-first hierarchy, bounded previews, and collapsed diagnostics
• Link drift: mitigated by reusing current navigation/filter contracts and rerunning existing workspace-hub tests
• Completed-spec churn: mitigated by explicit guardrail that related completed specs remain untouched

Acceptance Criteria

• AC-001: /admin/governance/inbox reads as the central operator queue, not only as a family queue/table
• AC-002: the first major section is the operator summary
• AC-003: items are grouped into clear operator lanes backed by repo truth
• AC-004: active items show reason, impact, source/environment context, and one primary next action
• AC-005: workspace-owned scope is preserved and environment_id remains visible and local
• AC-006: downstream links are scope-correct and do not emit forbidden public query aliases
• AC-007: empty and blocked states are productized and calm
• AC-008: Decision Register and Customer Review Workspace are linked, not rebuilt
• AC-009: focused Feature tests, Browser smoke, pint --dirty, and git diff --check are part of the implementation plan
• AC-010: no customer portal, no PSA handoff, no new governance engine, and no shell rewrite are introduced
• AC-011: the Undefined array key "label" failure is fixed by normalized ViewModel payload contracts, not only by defensive Blade checks
• AC-012: active work pages show Next recommended action with a direct item-level CTA in the first viewport
• AC-013: zero-count lanes are secondary clear chips/status, and item cards keep secondary detail collapsed on mobile
• AC-014: emitted lane hashes scroll to or visibly mark the lane in browser smoke coverage

Follow-up Candidates

• Evidence and retained artifact lifecycle follow-through
• Provider readiness / onboarding productization
• Localization and customer-safe copy hardening
• Sellable smoke matrix
• PSA / ITSM handoff

Open Questions

These do not block safe preparation, but implementation must resolve them from repo truth:

1. Should alert_delivery_failures and stale_operations remain first-class queue lanes, or should they be folded into a broader Blocked operator lane with source-family tags?
2. Can Recently resolved be derived honestly from current runtime timestamps/state, or should that lane be deferred until the repo truth proves a stable bounded rule?
3. Is Review-ready already derivable from current review/evidence/review-pack truth on the inbox page, or should it remain a linked supporting state rather than a first-class lane in v1?

User Scenarios & Testing (mandatory)

User Story 1 - See the governance work that matters first (Priority: P1)

As an MSP/operator user, I want Governance Inbox to show a summary first and group active work into operator lanes so I can decide what to clear next without reconstructing context across multiple pages.

Why this priority: This is the central operator workflow gap identified by Spec 345.

Independent Test: Seed visible findings, exceptions, blocked proof, and review follow-up states; open Governance Inbox; verify summary-first hierarchy, lane headings, and one dominant next action per visible item.

Acceptance Scenarios:

1. Given visible governance attention exists, When the operator opens /admin/governance/inbox, Then the summary appears before secondary queue context and the page groups work by operator lanes.
2. Given a visible active item exists, When the operator reads the lane item, Then the item shows reason, impact, source/environment context, and one primary next action.
3. Given no visible governance work exists, When the operator opens the page, Then the page shows a calm empty state and does not imply hidden work exists elsewhere.

User Story 2 - Keep environment scope explicit and safe (Priority: P1)

As a workspace operator, I want Governance Inbox to remain workspace-owned while using a visible environment_id filter so filtered and clean states stay predictable and leak-free.

Why this priority: Specs 338-341 make this a hard workspace hub contract.

Independent Test: Open clean and filtered URLs, clear the filter, reload, and try retired query aliases plus cross-workspace environment_id values.

Acceptance Scenarios:

1. Given the clean inbox URL, When the page loads, Then no hidden environment filter appears from remembered shell/session state.
2. Given an entitled ?environment_id= filter, When the page loads, Then the visible environment chip appears and only scoped data is shown.
3. Given a cross-workspace or retired query alias input, When the page loads, Then the request remains safe and no unsupported filter contract is applied.

User Story 3 - Route into the right downstream truth (Priority: P2)

As an operator, I want each governance item to lead me to the correct existing detail or proof surface so the inbox helps me finish work instead of duplicating it.

Why this priority: the inbox must stay a queue, not another ownership surface.

Independent Test: Click primary actions for representative decision, risk, review, evidence, and blocked items and verify canonical scope-correct targets.

Acceptance Scenarios:

1. Given an item requires decision, When the operator chooses its primary action, Then the target is the existing Decision Register or existing decision-owning surface.
2. Given an item is blocked on proof or provider state, When the operator chooses its primary action, Then the target is the current operation/proof/readiness surface and the blocker is explicit.
3. Given review-ready or customer-safe follow-up exists, When the operator chooses its primary action, Then the target is the existing review workspace or related review surface using environment_id where appropriate.