# Implementation Plan: Spec 327 - Governance Inbox Decision-First Workbench Productization **Branch**: `327-governance-inbox-decision-first-workbench-productization` | **Date**: 2026-05-18 | **Spec**: `specs/327-governance-inbox-decision-first-workbench-productization/spec.md` **Input**: User-provided Spec 327 and repo inspection. ## Summary Productize the existing workspace-scoped Governance Inbox into a decision-first operator workbench. The implementation must keep the current route and source-family truth, introduce no backend foundation, and make the first viewport answer: ```text What decision clears the highest-priority item? ``` The workbench will elevate selected/highest-priority item detail, reason, impact, owner/due, evidence state, accepted-risk/exception state, and a single next action, while keeping the existing queue/source sections as secondary context and diagnostics collapsed. ## Technical Context **Language/Version**: PHP 8.4.15, Laravel 12.52.0. **Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Tailwind CSS 4.2.2. **Storage**: PostgreSQL; no schema change expected. **Testing**: Pest 4 Feature/Livewire/Browser tests. **Validation Lanes**: confidence and browser; targeted navigation guard tests. **Target Platform**: Laravel Sail locally; Dokploy/container deployment posture unchanged. **Project Type**: Laravel monolith under `apps/platform`. **Performance Goals**: DB-only page render; no Graph calls during render; no extra heavy query family beyond existing inbox source queries unless bounded and eager-loaded. **Constraints**: No new persisted truth, no migration, no packages, no queue/scheduler/storage/env changes, no legacy alias support. **Scale/Scope**: One existing Filament page and its feature-local builder/view/tests. ## UI / Surface Guardrail Plan - **Guardrail scope**: changed existing operator-facing strategic surface. - **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: - `/admin/governance/inbox` - `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php` - `apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php` - `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php` - **No-impact class, if applicable**: N/A. - **Native vs custom classification summary**: Native Filament page plus existing Blade composition; no new UI framework. - **Shared-family relevance**: status messaging, action links, evidence/proof links, OperationRun links, workspace/environment filter chip, navigation context, diagnostics disclosure. - **State layers in scope**: page payload, URL query (`environment_id`, `family`), selected/highest-priority item state, diagnostics disclosure. - **Audience modes in scope**: operator-MSP, manager, auditor/support reviewer where authorized. - **Decision/diagnostic/raw hierarchy plan**: decision-first, proof/evidence second, diagnostics/support raw third. - **Raw/support gating plan**: collapsed by default and capability-gated where existing capabilities support access. - **One-primary-action / duplicate-truth control**: selected/highest-priority item owns one primary next action; queue rows/source links remain secondary. - **Handling modes by drift class or surface**: review-mandatory for UI-028 strategic surface; document-in-feature for any UI coverage registry no-change decision. - **Repository-signal treatment**: Spec 325 target image is visual direction only; runtime claims must be repo-verified or unavailable. ## Constitution Check - **Inventory-first, snapshots-second**: N/A, no Graph or snapshot changes. - **Read/write separation by default**: Page remains read-first. Any unexpected mutation requires spec/plan update, confirmation, authorization, audit, notification, and tests. - **Single Contract Path to Graph**: No Graph calls may be added. - **Deterministic Capabilities**: Reuse existing `Capabilities`, `CapabilityResolver`, `WorkspaceCapabilityResolver`, policies, and resource authorization. - **Proportionality / anti-bloat**: No new source of truth, persisted entity, enum/status family, public abstraction, or cross-domain UI framework. - **Workspace isolation**: Clean workspace URL stays workspace-wide; `environment_id` is resolved through current workspace and actor entitlement. - **Tenant/environment language**: Runtime copy must avoid tenant as platform context; provider-specific tenant wording only where explicitly provider-bound. - **OperationRun UX**: Deep links only through `OperationRunLinks`; no operation start or lifecycle changes. - **UI-COV-001**: Existing strategic surface UI-028 changes; active spec package must carry repo-truth map, tests, and browser screenshots, and implementation close-out must decide whether route inventory/coverage matrix updates are needed. - **TEST-GOV-001**: Targeted Feature and Browser tests are explicit; no broad heavy-governance lane unless implementation reveals structural risk. ## Current Repo Truth Summary Existing verified surfaces: - `GovernanceInbox` is a Filament `Page` with slug `governance/inbox`. - `governance-inbox.blade.php` currently renders header/scope chips, family filter pills, and section cards/entries. - `GovernanceInboxSectionBuilder` already assembles: - `assigned_findings` - `intake_findings` - `finding_exceptions` - `stale_operations` - `alert_delivery_failures` - `review_follow_up` - `WorkspaceHubEnvironmentFilter::fromRequest()` accepts canonical `environment_id`, scopes to current workspace, and rejects inaccessible/cross-workspace IDs. - Navigation tests already cover canonical environment filter, clear filter, legacy alias rejection, and workspace hub no-drift behavior. - Governance Inbox already uses `CanonicalNavigationContext` and `OperationRunLinks` for source handoff. Known current productization gap: - The page is still section/queue-first. It does not yet consistently promote a selected/highest-priority item with decision, reason, impact, owner/due, evidence path, exception state, and a single next action ahead of the queue. ## Existing Repository Surfaces Likely Affected Runtime files, only during later implementation: - `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php` - `apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php` - `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php` - `apps/platform/resources/lang/en/*` and `apps/platform/resources/lang/de/*` only if current project pattern requires localized strings for new stable copy. Tests, only during later implementation: - `apps/platform/tests/Feature/Governance/GovernanceInboxPageTest.php` - `apps/platform/tests/Feature/Governance/GovernanceInboxAuthorizationTest.php` - `apps/platform/tests/Feature/Governance/GovernanceInboxNavigationContextTest.php` - `apps/platform/tests/Feature/Governance/GovernanceInboxNavigationContextConvergenceTest.php` - `apps/platform/tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php` - `apps/platform/tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php` - `apps/platform/tests/Browser/Spec327GovernanceInboxProductizationSmokeTest.php` Spec/UI artifacts: - `specs/327-governance-inbox-decision-first-workbench-productization/repo-truth-map.md` - screenshot artifacts under `specs/327-governance-inbox-decision-first-workbench-productization/artifacts/screenshots/` - optional UI coverage registry updates only if implementation materially changes route/archetype/coverage state. ## Domain / Model Implications - No new model, table, migration, enum, status family, source of truth, or persisted display state. - Workbench item state must derive from existing source payloads: - `Finding`: title/subject, status, severity, owner/assignee, due date, operation/evidence JSON where available. - `FindingException`: status, current validity, owner, review due, request reason, current decision, evidence references. - `OperationRun`: problem class, status/outcome, run identifier, managed environment, canonical link. - `AlertDelivery`: failed status, event type/title/error text, managed environment/workspace. - `ManagedEnvironmentTriageReview` / `EnvironmentReview`: review follow-up state and customer review destination. - `EvidenceSnapshot` / `FindingExceptionEvidenceReference`: proof path only where linked and authorized. - If exact evidence or owner/due is missing for a family, render explicit unavailable/missing states. ## UI / Filament Implications - Filament v5 and Livewire v4.0+ compliance must be preserved. - Panel providers remain in `apps/platform/bootstrap/providers.php`; no panel provider changes expected. - No globally searchable resource is added or changed. Related resources must remain either disabled for global search or backed by safe View/Edit pages. - The layout should use Filament sections/cards/badges/buttons and Tailwind utility classes consistent with existing pages; no heavy one-off CSS. - Header must stay short: - `Governance Inbox` - workspace label - scope label: workspace-wide or filtered environment - visible filter chip and clear action when filtered - Main workbench must render before queue sections. - Summary cards should be compact and action-relevant. - Right-side detail panel should be desktop aside and mobile stack. - Diagnostics must be collapsed by default. ## Livewire / Page State Implications - Existing `tenantId` internal property may remain as implementation detail only; runtime URL/filter language must be `environment_id`. - Existing `family` query filter can remain if it does not conflict with `environment_id` contract. - Selected/highest-priority state should be deterministic on page load. If interactive selection is implemented, it must not introduce persisted state or break reload/back/forward behavior. - Clear filter must remove `environment_id` and any environment-like table/session filter state through existing helpers. ## OperationRun / Monitoring Implications - No new `OperationRun` creation or lifecycle transition. - No queued/running/terminal DB notification changes. - Any operation proof link must use existing `OperationRunLinks` and authorization. - Raw `OperationRun.context`, `failure_summary`, or payload-like data must not be default-visible. ## RBAC / Policy Implications Reuse existing authorization: - Workspace page access through `WorkspaceCapabilityResolver::isMember()`. - Environment access through `User::canAccessTenant()` and current accessible environments. - Findings through `Capabilities::TENANT_FINDINGS_VIEW` and `FindingPolicy`. - Assignment actions, if shown, through `Capabilities::TENANT_FINDINGS_ASSIGN` / policy. - Finding exceptions/accepted risks through `Capabilities::FINDING_EXCEPTION_VIEW`, `FINDING_EXCEPTION_MANAGE`, and `FINDING_EXCEPTION_APPROVE` as appropriate. - Evidence through `Capabilities::EVIDENCE_VIEW` and `EvidenceSnapshotPolicy`. - Alerts through `Capabilities::ALERTS_VIEW`. - Diagnostics through `Capabilities::SUPPORT_DIAGNOSTICS_VIEW` where any diagnostics UI is exposed. No new permission semantics should be added unless implementation proves existing capabilities cannot express the action and spec/plan are updated first. ## Audit / Evidence / Disclosure Implications - No new audit event is required for read-only page rendering unless current page-open audit conventions are extended repo-wide. - Evidence should appear as proof path/state: - linked - missing - stale - unavailable - not required - Do not show raw provider payloads, debug metadata, internal exception traces, provider secrets, raw OperationRun payloads, or stack traces by default. - If diagnostics disclosure is present, it must be collapsed and capability-aware. ## Data / Migration Implications Expected outcome: - No migrations. - No seeders. - No data backfills. - No packages. - No env vars. - No queues/scheduler/storage changes. - No deployment asset changes. - No backwards compatibility layer. - No legacy tenant query alias support. If implementation discovers an actual schema need, stop and update spec/plan/tasks/repo-truth-map first. Default decision remains no migration. ## Localization / Copy Implications - Runtime copy must be concise and operator-safe. - Avoid platform-context `tenant` wording. Use `Workspace` and `Environment` for shell/filter/product context. - Provider-bound tenant wording may remain only when describing an external Microsoft/Entra tenant identifier or provider payload outside the default decision view. - Add EN/DE localization only if the surrounding files already route stable page copy through language files; otherwise keep localized scope as implementation-local and document the decision. ## Implementation Phases ### Phase 1 - Repo Truth And Current UI Audit - Re-read this spec, plan, tasks, and `repo-truth-map.md`. - Inspect current `GovernanceInbox`, view, builder, related models, policies, and tests. - Update `repo-truth-map.md` before runtime changes if implementation discovers new source truth or gaps. - Confirm no migration/package/env/queue/storage need. ### Phase 2 - Tests First - Add tests for repo truth map existence. - Add Feature/Livewire tests for decision-first workbench, right detail panel, queue context, diagnostics hidden, evidence state, accepted-risk/exception state, RBAC action visibility, environment filter, legacy aliases, cross-workspace guard, and tenant-copy guard. ### Phase 3 - Layout Productization - Refactor the existing page into: - header/scope - main decision workbench - summary cards - queue/table context - right detail/decision panel - collapsed diagnostics disclosure - Keep existing family/queue context and source links. ### Phase 4 - Data Binding - Bind workbench and panel to repo-verified sources. - Render unavailable states for missing owner/due/evidence/decision data. - Do not create synthetic success, risk, evidence, or decision claims. ### Phase 5 - Action Hierarchy And RBAC - Show one primary next action per selected/highest-priority item. - Link only to existing, authorized source routes/actions. - Keep bulk/source actions secondary. - Do not introduce destructive actions. ### Phase 6 - Scope / Filter Integration - Preserve clean workspace-wide entry. - Preserve `?environment_id=` filter, visible chip, clear filter, reload/back/forward behavior. - Preserve legacy alias rejection and cross-workspace guard. ### Phase 7 - Browser Smoke And Screenshots - Add targeted Browser smoke for clean, filtered, clear/reload, selected item/detail panel, diagnostics hidden, table secondary, and no platform-context tenant wording. - Save screenshots under the spec artifacts path when generated. ### Phase 8 - Validation And Close-Out - Run targeted Feature/navigation tests, Browser smoke, filtered guard tests, `pint --dirty`, and `git diff --check`. - Report full suite status honestly if not run. - Record no migrations/seeders/packages/env/queues/scheduler/storage/deployment asset/backcompat/legacy alias support. ## Testing Strategy Required tests: - `it('documents_governance_inbox_repo_truth_map')` - `it('renders_governance_inbox_decision_first_workbench')` - `it('renders_governance_inbox_decision_detail_panel')` - `it('keeps_governance_inbox_queue_table_available_as_secondary_context')` - `it('governance_inbox_hides_raw_diagnostics_by_default')` - `it('governance_inbox_shows_accepted_risk_or_exception_state')` - `it('governance_inbox_shows_evidence_state_without_raw_payload')` - `it('governance_inbox_respects_capabilities_for_primary_actions')` - `it('governance_inbox_supports_canonical_environment_filter')` - `it('governance_inbox_rejects_legacy_environment_aliases')` - `it('governance_inbox_rejects_cross_workspace_environment_filter')` - `it('governance_inbox_does_not_use_tenant_as_platform_context_copy')` Required Browser smoke: - `tests/Browser/Spec327GovernanceInboxProductizationSmokeTest.php` Browser flows: 1. Clean workspace Governance Inbox. 2. Environment-filtered Governance Inbox. 3. Clear filter and reload. 4. Decision workbench and right detail panel visible. 5. Diagnostics hidden by default. 6. Queue/table context remains visible lower/secondary. 7. No platform-context tenant wording. ## Rollout Considerations - Runtime page-only productization; no deployment asset changes expected. - No `filament:assets` deployment change expected because no registered Filament assets are planned. - If implementation adds registered Filament assets unexpectedly, stop and update spec/plan first, then include `cd apps/platform && php artisan filament:assets` in deployment notes. - Staging validation should include targeted Browser smoke for light mode and workspace/environment filter behavior before production promotion. ## Risk Controls - **False green risk**: Use only repo-backed success/ready labels; otherwise render unavailable or attention states. - **RBAC leakage risk**: Derive counts after capability/environment scoping; hidden families must not leak counts. - **Scope drift risk**: Reuse existing `WorkspaceHubEnvironmentFilter` and clear-filter helpers; preserve Spec 314-322 tests. - **Diagnostics leakage risk**: Assert raw payload/debug/provider-secret/internal exception text absent by default. - **UI overbuild risk**: Keep composition page-local and Filament-native; no new framework. - **Test cost risk**: Use targeted Feature and Browser tests; avoid heavy fixture defaults. ## Gate Review Candidate Selection Gate: expected pass. Direct user-supplied Spec 327, roadmap-aligned, not previously specced as `327`, related completed specs preserved, scope is one existing page. Spec Readiness Gate: expected pass when `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, and `checklists/requirements.md` exist and preparation analysis has no blocking issues.