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

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:

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.