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:

```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.