# 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 - [x] Existing page changed - [ ] New page/route added - [ ] Navigation changed - [ ] Filament panel/provider surface changed - [ ] New modal/drawer/wizard/action added - [x] New table/form/state added - [ ] Customer-facing surface changed - [ ] Dangerous action changed - [x] Status/evidence/review presentation changed - [x] Workspace/environment context presentation changed ## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact")* - **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.