TenantAtlas/specs/327-governance-inbox-decision-first-workbench-productization/spec.md

Feature Specification: Spec 327 - Governance Inbox Decision-First Workbench Productization

Feature Branch: 327-governance-inbox-decision-first-workbench-productization
Created: 2026-05-18
Status: Draft
Type: Runtime UI productization / decision workbench / governance triage surface
Runtime posture: Narrow runtime UI implementation. Repo-based. No invented backend foundation.
Input: User-provided full Spec 327 draft.

Dependencies And Historical Context

Depends on:

• Spec 250 - Decision-Based Governance Inbox v1, treated as historical inbox foundation.
• Spec 257 - Governance Decision Surface Convergence, treated as historical decision-home convergence foundation.
• Spec 314 - Workspace Hub Navigation Context Contract.
• Spec 315 - Environment CTA Explicit Filter Contract.
• Spec 316 - Workspace Hub Clear Filter Contract.
• Spec 317 - Legacy Tenant / Environment Context Cleanup.
• Spec 318 - Admin Surface Scope & Shell Context Audit.
• Spec 319 - Environment-Owned Surface Routing & Shell Context Contract.
• Spec 320 - Workspace-Owned Analysis Surface Registration & Shell Cutover.
• Spec 321 - Alerts / Audit Log Environment Filter Contract Decision.
• Spec 322 - Browser No-Drift Regression Guard.
• Spec 325 - Screenshot-Anchored Strategic Target Images.
• Spec 326 - Customer Review Workspace v1 Productization.

Repo truth adjustment: the user draft intentionally starts from Spec 325 target direction and the Spec 326 premium-layout lesson, but the repository already has a runtime GovernanceInbox page and a GovernanceInboxSectionBuilder. Spec 327 must productize that existing route and builder instead of creating a new workflow engine, ticket queue, Decision Register rebuild, persisted inbox item, or broad status taxonomy. Spec 325 premium references are visual calibration only; they are not runtime truth for counts, states, actions, RBAC, audit, evidence, or OperationRun behavior.

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

• Problem: Governance Inbox is repo-real and already aggregates findings, finding exceptions, stale or failed operations, alert delivery failures, and review follow-up, but the first-read experience still behaves like a sectioned queue rather than a decision-first workbench that answers which governance decision clears the highest-priority item.
• Today's failure: Operators can see attention families and source links, but they still need to infer reason, impact, owner, due date, evidence state, accepted-risk state, and one safest next action from section summaries and row sublines. Diagnostics/source routing can compete with the decision hierarchy.
• User-visible improvement: Governance operators get a polished workbench where the highest-priority or selected item leads with decision, reason, impact, owner/due, evidence, exception/accepted-risk state, and a single primary next action while raw diagnostics remain collapsed.
• Smallest enterprise-capable version: Productize only the existing /admin/governance/inbox page and its current builder/view payloads. Add a repo-truth map first, derive any display states from existing models/services, keep the current section/table context available, and add targeted Feature/Browser coverage for layout, scope, RBAC, diagnostics, and no tenant-context copy.
• Explicit non-goals: No backend workflow rebuild, no Decision Register rebuild, no helpdesk/PSA system, no AI prioritization, no new remediation automation, no new persisted inbox entity, no new decision taxonomy, no migrations, no packages, no env vars, no queues/scheduler/storage changes, no broad redesign of Customer Review Workspace, Operations Hub, Evidence Overview, Environment Dashboard, Baseline Compare, or Restore Safety Workflow.
• Permanent complexity imported: Feature-local page composition, feature-local display payloads if needed, targeted Feature tests, a Browser smoke test, screenshot artifacts, and repo-truth-map.md. No new persisted truth, no public abstraction, no enum/status family, no cross-domain UI framework.
• Why now: Spec 326 completed the customer review productization lane and explicitly deferred Governance Inbox as Spec 327. docs/product/spec-candidates.md, docs/product/roadmap.md, and Spec 325 all identify Governance Inbox decision experience as a P1/P0 strategic surface and the largest remaining operator workflow productization gap.
• Why not local: A copy-only patch or another section link would leave the primary operator question unresolved. A new task engine would overbuild. The narrow correct slice is a decision-first productization pass on the existing workspace-scoped Governance Inbox.
• Approval class: Workflow Compression.
• Red flags triggered: Cross-surface decision composition, evidence/action display, and strategic UI productization. Defense: scope is bounded to one existing page, existing truth sources, existing authorization, existing routes, existing workspace/environment filter contract, and explicit no-new-backend constraints.
• 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 manual promotion for Spec 327, aligned with decision-based-governance-inbox-v1 in docs/product/spec-candidates.md, the roadmap's Decision-Based Governance Inbox lane, and the Governance Inbox target brief from Spec 325.
• Completed-spec check: No specs/327-* package existed before generation. Related Specs 250, 257, and 314-326 contain historical/completed foundation or productization signals and must remain unchanged by this preparation.
• Close alternatives deferred: Operations Hub Decision-First Workbench, Evidence/Audit disclosure, Environment Dashboard/Baseline Compare, and Restore Safety Workflow productization are follow-up specs 328-331, not hidden scope.
• Smallest viable implementation slice: Existing Governance Inbox only, including header/scope clarity, main decision workbench, summary cards, queue/table context, right-side decision panel, diagnostics disclosure, RBAC-aware actions, canonical environment_id filter behavior, and tests/browser smoke.

Spec Scope Fields (mandatory)

• Scope: workspace canonical-view governance decision workbench, optionally filtered by canonical environment_id.
• Primary Routes:
  • Existing route: /admin/governance/inbox.
  • Existing page class: apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php.
  • Existing view: apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php.
  • Existing builder: apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php.
• Data Ownership:
  • Findings truth: Finding, including owner, assignee, due date, severity, status, subject display, and linked operation runs.
  • Finding exception / accepted-risk truth: FindingException, FindingExceptionDecision, FindingExceptionEvidenceReference.
  • Operation proof truth: OperationRun and existing OperationRunLinks.
  • Evidence proof truth: EvidenceSnapshot, EvidenceSnapshotItem, and existing evidence policies/resources where linked.
  • Review follow-up truth: ManagedEnvironmentTriageReview, EnvironmentReview, EnvironmentReviewRegisterService, Customer Review Workspace links.
  • Alert delivery truth: AlertDelivery, alert resource routes, and workspace alert capabilities.
  • Workspace / environment filter truth: WorkspaceContext, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, WorkspaceHubRegistry, and existing filter chip partial.
  • Audit truth: existing source surfaces and policies only; this spec introduces no new mutation/audit action unless spec/plan are updated first.
• RBAC:
  • Workspace membership required.
  • Managed-environment entitlement required when an environment_id filter is applied or environment-bound data is rendered.
  • Existing capabilities and policies remain authoritative for findings, finding exceptions/accepted risks, evidence, operation runs, reviews, alerts, diagnostics, assignment, and source actions.
  • Non-member or cross-workspace environment access remains deny-as-not-found.
  • Member with missing source capability must not see unauthorized actions or sensitive existence hints.

For canonical-view specs:

• Default filter behavior when tenant-context is active: Clean /admin/governance/inbox remains workspace-wide and must not inherit remembered environment context, Filament tenant context, session table filters, or legacy query aliases.
• Explicit entitlement checks preventing cross-tenant leakage: ?environment_id= must resolve through the current workspace and actor entitlement; cross-workspace or inaccessible IDs return 404/no-access.

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 Surface / Findings-Inbox Workbench, matching docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md.
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified page and foundation; individual runtime elements must be classified in repo-truth-map.md.
• Existing pattern reused: Filament Page, Filament sections, existing builder, existing source-surface links, existing workspace hub environment chip, existing capability resolvers, existing OperationRun links, existing resources/policies.
• New pattern required: no new runtime framework; page-local workbench composition only.
• Screenshot required: yes, Browser smoke screenshots under specs/327-governance-inbox-decision-first-workbench-productization/artifacts/screenshots/.
• Page audit required: no new full audit unless implementation materially changes route inventory; active spec artifacts and screenshots are sufficient if route/archetype remains UI-028.
• Customer-safe review required: operator-facing, but copy may feed customer review summaries. Keep customer/operator-safe labels and hide raw diagnostics.
• Dangerous-action review required: no new dangerous action expected. If implementation unexpectedly adds approve/reject/accept-risk/assign/close style mutations, spec/plan must be updated first and actions must use confirmation, server authorization, audit, notifications, and tests.
• 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
• Coverage decision for implementation: implementation must either update UI coverage registry artifacts or document in this spec's close-out why UI-004 and Spec 325 target artifacts remain sufficient for the unchanged route/archetype.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes.
• Interaction class(es): status messaging, action links, governance queue summaries, evidence/proof links, OperationRun links, workspace/environment filter chip, diagnostics disclosure, navigation/back context.
• Systems touched: GovernanceInbox, GovernanceInboxSectionBuilder, FindingResource, FindingExceptionsQueue, FindingExceptionResource, AlertDeliveryResource, CustomerReviewWorkspace, EnvironmentReviewResource, OperationRunLinks, CanonicalNavigationContext, WorkspaceHubEnvironmentFilter, capability resolvers, and policies.
• Existing pattern(s) to extend: existing Governance Inbox section payloads, existing workspace hub filter chip, existing navigation context, source-surface routes, existing policy/capability checks.
• Shared contract / presenter / builder / renderer to reuse: GovernanceInboxSectionBuilder, CanonicalNavigationContext, OperationRunLinks, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, CapabilityResolver, WorkspaceCapabilityResolver, existing Filament resources/routes.
• Why the existing shared path is sufficient or insufficient: Existing paths are sufficient for truth, authorization, and source routing. They are insufficient only in first-read page hierarchy; Spec 327 may add page-local payload shaping but must not create a new generic workflow or status framework.
• Allowed deviation and why: bounded page-local layout/view helper changes are allowed. New public cross-domain presenters, status taxonomies, or persisted item stores are not allowed.
• Consistency impact: Labels, badges, actions, and links must stay aligned with existing findings, exception, evidence, review, alert, and operation vocabulary.
• Review focus: Verify no fake metrics, no false green state, no raw diagnostics by default, no unauthorized action, no shell-scope regression, and no local duplicate of existing source-surface mutation semantics.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: secondary/deep-link semantics only; no new OperationRun creation, queueing, dedupe, completion, or lifecycle behavior.
• Shared OperationRun UX contract/layer reused: existing OperationRunLinks and existing operation resource routes only.
• Delegated start/completion UX behaviors: N/A - no operation start.
• Local surface-owned behavior that remains: show operation proof availability/unavailability and source links only when existing run records and authorization support 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 governance workbench over existing environment-bound artifacts.
• Seams affected: display and routing over findings, finding exceptions, evidence, review, alert, and operation proof.
• Neutral platform terms preserved or introduced: workspace, environment filter, governance decision, evidence path, accepted risk, operation proof, diagnostics.
• Provider-specific semantics retained and why: existing Microsoft/Intune terms may appear only where the underlying finding/review/resource already uses them. Do not surface raw provider IDs, Graph payloads, tenant aliases, or provider diagnostics by default.
• Why this does not deepen provider coupling accidentally: no Graph calls, no provider contracts, no provider connection changes, and no new provider-shaped persistence.
• Follow-up path: provider readiness, environment dashboard, baseline compare, restore safety, and evidence/audit productization remain separate specs.

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	decision queue, evidence/proof links, source routing	page, URL-query, derived payload	no	Existing route only
Header / scope area	yes	Filament section / Blade	workspace/environment context presentation	page, URL-query	no	Must keep Workspace shell ownership
Main decision workbench	yes	Filament section/cards/badges	status/readiness/action hierarchy	page payload	no	Derived labels only, no new persisted state
Summary cards	yes	Filament cards/badges	decision posture and count summaries	builder/page payload	no	Only repo-backed counts or unavailable states
Queue/table context	yes	existing sections/list; table-like queue may be refactored	specialist source surfaces	builder/page payload	no	Current table/queue remains secondary context
Right detail / decision panel	yes	native layout / Blade	evidence, accepted risk, decision summary, action links	page payload	no	Desktop aside, stacked on small screens
Diagnostics disclosure	yes	collapsed/progressive disclosure only	support/raw detail	page payload/action visibility	no	Authorized and collapsed by default

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 item should be cleared first and which source action is safest	highest-priority/selected item, decision, reason, impact, owner/due, evidence state, exception state, next action	source record, operation proof, evidence snapshot, audit/review context, diagnostics	Primary because it is the canonical workspace governance decision workbench	Follows pending governance decisions, not storage objects	Removes cross-page reconstruction before first action
Queue/list sections	Secondary Context	Operator scans remaining items after priority decision is visible	decision/finding label, environment, severity/priority, owner/due where available, evidence/exception state, next action	source page detail and diagnostics after open	Secondary because workbench leads with decision summary	Keeps source families visible without making table the only experience	Reduces equal-priority section overload
Diagnostics disclosure	Tertiary Evidence / Diagnostics	Support/operator confirms technical detail after the decision path	collapsed availability only	raw payloads/debug/support detail only if authorized and explicitly opened	Not primary; proof and diagnostics support decisions	Preserves audit depth without diagnostic dominance	Prevents default raw-console 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, auditor/support reviewer	decision title, reason, impact, owner/due, evidence state, accepted-risk state, environment scope, primary next action	collapsed source diagnostics and source-page detail	raw payloads, stack traces, provider secrets, internal exception traces, raw OperationRun payloads	context-aware source action such as review decision, open finding, review accepted risk, open evidence, or open operation proof	raw/support detail and unauthorized actions	main workbench states the blocker once; queue and panel add evidence/source proof
Right detail panel	operator-MSP, support reviewer where authorized	decision summary, proof path, accepted-risk state, owner/due, next action	operation/evidence/review context behind links/disclosure	raw/support details remain hidden or routed to existing authorized surfaces	same primary next action as selected item	raw diagnostics and unsupported links	panel expands the same selected item instead of creating another decision

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	Workbench / Workspace Decision	Decision-first governance queue	Review/open the highest-priority item	explicit primary action plus selected/row source link	optional row/select only if repo-real	right/detail panel and source links	none introduced; any future mutation must be confirmed/audited	/admin/governance/inbox	existing source routes only	active workspace, optional environment_id chip	Governance Inbox	decision, reason, impact, owner/due, evidence, exception, next action	none
Queue context	List / Table / Read-only decision queue	Secondary workbench context	Select/open source item	existing source route	allowed only if clear and accessible	row action or panel action	existing source surfaces only	/admin/governance/inbox	existing finding/exception/operation/alert/review routes	workspace + environment filter	Governance item	priority/severity/status, evidence/exception, owner/due	none
Diagnostics disclosure	Diagnostics / Support Raw	Collapsed diagnostic context	Expand proof detail if authorized	disclosure component	N/A	below/inside detail panel	none	same page	existing source diagnostics routes if any	authorized-only label	Diagnostics	collapsed status only	none

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	Workspace operator / MSP operator	Decide which governance item clears first and open the safest existing action path	Workspace decision workbench	What decision clears the highest-priority governance item?	decision, reason, impact, owner, due, evidence, exception, environment, next action	raw payloads, provider debug, stack traces, raw OperationRun payload, internal exception/debug metadata	decision urgency, evidence availability, risk/exception state, owner/due, source family, operation follow-up	none on the page by default; existing source surfaces own mutations	review decision/open finding/review accepted risk/open evidence/open operation proof as supported	none introduced

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no. repo-truth-map.md is a preparation artifact, not runtime truth.
• New abstraction?: no public abstraction. Page-local private helpers are allowed only when they reduce Blade complexity and stay feature-local.
• New enum/state/reason family?: no domain state. Display states must be derived from existing Finding, FindingException, EvidenceSnapshot, OperationRun, AlertDelivery, EnvironmentReview, and current builder truth.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Governance Inbox needs a decision-first runtime surface that consumes existing truth without making unsupported decision, owner, evidence, accepted-risk, or success claims.
• Existing structure is insufficient because: Current page foundations show attention families but do not consistently elevate the selected/highest-priority decision, proof path, owner/due state, accepted risk, and one primary next action above queue diagnostics.
• Narrowest correct implementation: Refactor the existing page layout and derived payloads, bind to existing sources, hide diagnostics, and add targeted tests/browser smoke.
• Ownership cost: Feature-local layout/payload tests, one Browser smoke, and screenshot artifacts. No durable backend model or new framework cost.
• Alternative intentionally rejected: new ticket/helpdesk system, new Decision Register foundation, new workflow engine, AI prioritization, broad design system work, and persisted inbox items.
• Release truth: current-release runtime UI productization over existing governance inbox foundations.

Compatibility posture

This feature assumes pre-production runtime posture. Backward compatibility, historical aliases, migration shims, dual-write logic, and legacy tenant query aliases are out of scope. Existing legacy query aliases (tenant, tenant_id, managed_environment_id, environment, tenant_scope, tableFilters) must not be supported for Governance Inbox filtering.

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

• Test purpose / classification: Feature, Filament/Livewire/HTTP, Browser.
• Validation lane(s): confidence plus browser for critical workspace/environment UI/scope smoke.
• Why this classification and these lanes are sufficient: The change is a user-facing Filament page productization with RBAC, source truth, scope, and disclosure behavior. Feature tests prove data/scope/action rules; Browser smoke proves shell/filter/reload/disclosure/selected-panel behavior.
• New or expanded test families: additions under tests/Feature/Governance/* and tests/Browser/Spec327GovernanceInboxProductizationSmokeTest.php.
• Fixture / helper cost impact: reuse existing helpers and factories in tests/Pest.php; do not widen expensive defaults.
• Heavy-family visibility / justification: browser addition is explicit and named for Spec 327.
• Special surface test profile: global-context-shell plus decision-first disclosure.
• Standard-native relief or required special coverage: special coverage required for environment filter, clear/reload, highest-priority/selected decision, right detail panel, diagnostics default-hidden, and no platform-context tenant copy.
• Reviewer handoff: confirm diagnostics are collapsed, RBAC actions hide/disable correctly, no false green, clean workspace entry, canonical filter, clear filter, cross-workspace guard, and table/queue remains available as secondary context.
• Budget / baseline / trend impact: no expected material lane-cost shift beyond one targeted browser smoke.
• Escalation needed: document-in-feature if browser coverage becomes too expensive or requires fixture broadening.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Governance tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec327GovernanceInboxProductizationSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='GovernanceInbox|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Decide the highest-priority governance item (Priority: P1)

As a governance operator, I want the inbox to show the highest-priority or selected item with decision, reason, impact, owner, due, evidence, accepted-risk state, and one next action so I can clear work without reconstructing context across sections.

Why this priority: This is the core productization promise and delivers value even before optional detail refinements.

Independent Test: Seed findings, finding exceptions, evidence/operation links, and review follow-up; open Governance Inbox; verify the workbench question, selected/highest-priority item, reason, impact, evidence, exception state, owner/due or unavailable state, and primary action.

Acceptance Scenarios:

1. Given visible governance attention exists, When the operator opens clean Governance Inbox, Then the page asks What decision clears the highest-priority item? and shows the top decision with reason, impact, evidence, exception, owner/due, and next action.
2. Given owner, due date, or evidence data is absent, When the item is rendered, Then the page shows an honest unavailable/missing state rather than invented data.
3. Given no visible attention exists, When the operator opens the page, Then the empty state says no governance decisions need action in the current scope without false green success claims.

User Story 2 - Keep workspace/environment scope explicit (Priority: P1)

As a workspace operator, I want Governance Inbox to stay workspace-owned while accepting a canonical environment filter so clean, filtered, clear, reload, and cross-workspace behavior remain predictable.

Why this priority: Specs 314-322 made this a hard product contract for workspace hub surfaces.

Independent Test: Open clean /admin/governance/inbox, filtered ?environment_id=, clear filter, reload, legacy aliases, and cross-workspace IDs; verify workspace shell and chip behavior.

Acceptance Scenarios:

1. Given clean Governance Inbox URL, When the page loads, Then no Environment chip or remembered Environment filter appears.
2. Given ?environment_id={id} for an entitled environment, When the page loads, Then Workspace shell remains active and a visible Environment filter chip appears.
3. Given a cross-workspace environment ID or legacy query alias, When the page loads, Then the cross-workspace ID is denied as not found and aliases do not create filter state.

User Story 3 - Inspect proof without raw diagnostics by default (Priority: P1)

As an operator or support reviewer, I want evidence path and operation proof to be visible as links/states while raw diagnostics remain secondary and capability-gated.

Why this priority: Governance decisions need proof, but default raw details create support-console drift and leakage risk.

Independent Test: Render items with linked evidence/operation proof and assert evidence state/path is visible while raw payload, stack trace, provider secret, debug metadata, and internal exception text are absent by default.

Acceptance Scenarios:

1. Given an item has linked evidence or operation proof, When the detail panel renders, Then the evidence path or operation proof state/link appears only if authorized.
2. Given diagnostics are available, When the page first renders, Then raw diagnostics are collapsed or absent by default.
3. Given the actor lacks diagnostics/evidence capability, When the page renders, Then protected links/actions are hidden/disabled without leaking sensitive details.

User Story 4 - Preserve queue context as secondary workbench content (Priority: P2)

As a governance operator, I want the existing queue/table context to remain available below or beside the workbench so I can scan other items after the top decision is clear.

Why this priority: The workbench must not regress existing routing and filter functionality.

Independent Test: Render the existing Governance Inbox fixtures and assert source families/rows still appear as secondary context with filters/search/source links intact.

Acceptance Scenarios:

1. Given multiple visible source families exist, When the workbench renders, Then existing family/queue context remains available and not replaced by an empty dashboard.
2. Given a family filter is selected, When the page renders, Then the workbench and secondary queue align to the filtered family without losing clear-filter behavior.

Functional Requirements

• FR-001: Governance Inbox MUST remain on the existing /admin/governance/inbox route.
• FR-002: The page MUST render a decision-first workbench before the secondary queue/table context.
• FR-003: The workbench MUST include the question What decision clears the highest-priority item? or stable equivalent final copy.
• FR-004: The selected/highest-priority item MUST show decision/title, reason, impact, owner/due state, evidence state, accepted-risk/exception state, and primary next action.
• FR-005: Missing owner, due, evidence, decision, or accepted-risk data MUST render honest unavailable/missing states or be omitted; it MUST NOT be invented.
• FR-006: Summary cards MUST use only repo-supported counts/states, such as open decisions, overdue, awaiting review, owner missing, evidence missing, or accepted-risk follow-up.
• FR-007: Existing source-family/queue context MUST remain available as secondary workbench content.
• FR-008: A right-side decision/detail panel MUST be visible on desktop and stack on smaller screens.
• FR-009: Evidence/proof must be shown as proof path/state, not raw payload.
• FR-010: Diagnostics/raw details MUST be collapsed, hidden, or capability-gated by default.
• FR-011: Primary action MUST be singular and repo-real for the selected/highest-priority item.
• FR-012: Unauthorized actions MUST be hidden, disabled with existing helper text convention, or replaced by unavailable state; UI visibility is not security.
• FR-013: No new destructive or governance-impacting action may be added without updating spec/plan first and applying confirmation, server authorization, audit, notification, and tests.
• FR-014: Clean entry MUST remain workspace-wide with no active Environment shell and no remembered Environment fallback.
• FR-015: Filtered entry MUST use only ?environment_id={id} with a visible chip and clear action.
• FR-016: Legacy query aliases (tenant, tenant_id, managed_environment_id, environment, tenant_scope, tableFilters) MUST NOT create filter state.
• FR-017: Cross-workspace or unauthorized environment_id MUST be rejected as safe not-found/no-access.
• FR-018: Runtime copy MUST avoid tenant as platform context copy. Provider-specific use remains allowed only when explicitly provider-bound.
• FR-019: Implementation MUST update repo-truth-map.md before runtime changes if new source gaps are discovered.
• FR-020: No migrations, seeders, packages, env vars, queues, scheduler, storage, deployment asset changes, backwards compatibility layer, or legacy alias support are expected.

Non-Functional Requirements

• NFR-001: Page render MUST remain DB-only and MUST NOT perform Microsoft Graph or external provider calls.
• NFR-002: The layout MUST remain Filament v5 / Livewire v4 compatible and use native Filament/Tailwind primitives before custom UI.
• NFR-003: The workbench MUST remain responsive enough for the Filament shell; desktop gets a right-side detail panel and smaller viewports stack it below.
• NFR-004: Decision priority MUST NOT rely on color alone; status/action meaning must also be expressed in text.
• NFR-005: Raw diagnostics, provider payloads, stack traces, provider secrets, raw OperationRun payloads, and internal exception/debug metadata MUST NOT be default-visible.
• NFR-006: Query and section counts MUST be scoped by workspace, environment entitlement, and capability before rendering.
• NFR-007: Implementation MUST avoid broad fixture/helper defaults or hidden heavy-governance test cost.

Auditability / Observability Requirements

• AOR-001: No new audit event is required for the read-first page productization unless implementation introduces a new mutation or extends an existing repo audit convention.
• AOR-002: Any unexpected mutating action MUST be added only after spec/plan update and must include server-side authorization, confirmation when destructive/high-impact, audit logging, user feedback, and tests.
• AOR-003: Operation proof links must use existing OperationRun truth and link helpers; this spec must not create or transition OperationRuns.
• AOR-004: Evidence, decision, and operation proof states must distinguish available proof from unavailable/missing proof without implying audit success.

Data / Truth Requirements

Each visible runtime element must be classified as one of:

• repo-verified
• foundation-real
• derived from existing model
• empty state / unavailable
• deferred future capability

The authoritative map is repo-truth-map.md in this spec directory. If implementation discovers that a planned element has no safe source, no authorization path, or would require new persisted truth, the element must become empty state / unavailable or deferred future capability.

RBAC / Capability Requirements

At minimum, implementation must verify existing capabilities/policies for:

• view Governance Inbox / workspace membership
• view findings
• assign owner where supported
• view/manage/approve finding exceptions or accepted risks
• view evidence
• view operation runs/proof
• open review/customer review context
• open decision record if supported
• view diagnostics/support detail

Do not introduce new permission semantics unless repo analysis proves an existing capability cannot express the action and spec/plan are updated first.

Assumptions

• The existing GovernanceInboxSectionBuilder can provide enough item-level source context for a first implementation without becoming a generic task engine.
• Existing source routes for findings, finding exceptions, operations, alerts, reviews, and Customer Review Workspace remain the owning surfaces for mutations and deep diagnostics.
• Existing capability resolvers and policies are sufficient for v1 action visibility and source-link access.
• The internal tenantId property may remain as implementation detail only; runtime URL/copy/filter language must stay environment_id and Environment.
• Spec 325 target images remain visual calibration and must not be treated as runtime data truth.

Risks

• Implementation could overreach into a new workflow engine or duplicate Decision Register state instead of deriving a page-local workbench.
• Cross-family priority mapping could imply a new decision taxonomy if it is not kept as derived display logic.
• Evidence or accepted-risk labels could become false green claims if unavailable proof is not rendered honestly.
• Capability-limited actors could learn hidden family existence through counts, empty states, or disabled action labels if scoping is applied too late.
• Browser coverage could become expensive if fixtures grow beyond the targeted smoke path.

Open Questions

• None blocking preparation. Implementation must update repo-truth-map.md and spec/plan before runtime edits if it discovers a selected UI element requires new persisted truth, a new capability, or an unsupported source route.

Non-Goals

• No backend workflow rebuild.
• No Decision Register rebuild.
• No new ticket/helpdesk/PSA system.
• No AI prioritization or recommendation engine.
• No new remediation automation.
• No broad redesign of findings pages, Customer Review Workspace, Operations Hub, Evidence Overview, Environment Dashboard, Baseline Compare, or Restore Safety Workflow.
• No migrations by default.
• No packages, env vars, queues, scheduler, storage, or deployment asset changes.
• No legacy tenant query alias support.

Acceptance Criteria

Productization

• Governance Inbox has a decision-first layout.
• Main decision question is visible.
• Highest-priority/selected item is visible.
• Reason and impact are visible.
• Owner/due state is visible or honestly unavailable.
• Evidence state is visible.
• Accepted-risk/exception state is visible.
• Primary next action is clear.
• Diagnostics are secondary/collapsed.
• Table/queue remains available as secondary workbench context.

Customer / Operator Safety

• Raw diagnostics hidden by default.
• Provider secrets not visible.
• Internal exception/debug text not visible.
• No false green success state.
• Copy avoids tenant as platform context.
• Empty/unavailable states are honest.

Scope

• Clean URL is workspace-wide.
• Shell is Workspace-only.
• Environment filter uses environment_id.
• Visible Environment chip appears when filtered.
• Clear filter works.
• Reload after clear is safe.
• Legacy aliases do not create filter state.
• Cross-workspace Environment is rejected.

RBAC

• Unauthorized user cannot access protected data.
• Unauthorized actions are hidden/disabled.
• Assign owner action respects capability if shown.
• Exception/accepted-risk action respects capability if shown.
• Evidence access respects capability.
• Diagnostics access respects capability.

UI / Visual

• Layout uses premium direction from Spec 325 without treating target images as runtime truth.
• Filament light mode remains readable.
• No heavy one-off CSS.
• Right-side detail panel exists on desktop.
• Workbench table/queue is not the only default experience.
• Page remains responsive enough for Filament shell.

Tests / Validation

• Repo truth map exists.
• Required Feature tests pass.
• Required Browser smoke passes.
• Relevant Spec 314-322 guards still pass.
• pint --dirty passes.
• git diff --check passes.
• Full suite status is honestly reported if run/not run.

Follow-Up Spec Candidates

• Spec 328 - Operations Hub Decision-First Workbench Productization.
• Spec 329 - Evidence / Audit Log Disclosure Productization.
• Spec 330 - Environment Dashboard / Baseline Compare Productization.
• Spec 331 - Restore Safety Workflow Productization.

Do not start these inside Spec 327.