# Implementation Plan: Governance Inbox Resolution Intake v1 **Branch**: `389-governance-inbox-resolution-intake-v1` | **Date**: 2026-06-19 | **Spec**: `specs/389-governance-inbox-resolution-intake-v1/spec.md` **Input**: Feature specification from `/specs/389-governance-inbox-resolution-intake-v1/spec.md` ## Summary Add active Review Publication Resolution Cases to the existing Governance Inbox as a concrete, read-only source family. The inbox should show operator-friendly review publication work items, map existing case/step/proof state into conservative viewer-relative statuses, and navigate only to existing authorized Resolution, Review, or Operation pages. It must reuse Spec 388 proof/currentness semantics or fail closed to `Needs re-check`, and it must not introduce a generic workflow/task engine, inline execution, publish action, customer-facing leakage, or a second proof evaluator. ## Technical Context **Language/Version**: PHP 8.4.15 **Primary Dependencies**: Laravel 12.52.0, Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Laravel Sail **Storage**: PostgreSQL; no migration expected for v1 **Testing**: Pest 4 Feature, Filament/Livewire Feature, optional Browser smoke **Validation Lanes**: fast-feedback + confidence; browser when UI smoke is available; PostgreSQL only if a later spec update adds schema/index work **Target Platform**: Laravel monolith under `apps/platform`, Sail-first locally, Dokploy/container deployment for staging/production **Project Type**: Web application, existing Filament admin panel **Performance Goals**: Governance Inbox list rendering remains DB-only and bounded to the existing inbox page limit/profile; no per-row Graph/provider calls **Constraints**: Read-only intake, no inline mutations, no raw payloads, no customer leakage, no unvalidated operation IDs or links, no generic registry/engine **Scale/Scope**: One concrete Review Publication Resolution intake source over existing workspace/environment-scoped cases ## UI / Surface Guardrail Plan - **Guardrail scope**: changed existing operator-facing Governance Inbox surface. - **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: - `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php` - `apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php` - `apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php` only if the existing rendering shape cannot express required labels/actions - Existing Environment Review Resolution Page links through `EnvironmentReviewResource::environmentScopedUrl('resolve-publication', ...)` - Existing OperationRun detail links through `OperationRunLinks` after validation - **No-impact class, if applicable**: N/A. - **Native vs custom classification summary**: Existing custom Governance Inbox Blade page using Filament components; reuse current layout and source-family/lanes pattern. - **Shared-family relevance**: Governance Inbox source family, status messaging, action links, OperationRun links, review/evidence status summaries. - **State layers in scope**: page source-family data, lane classification, source-detail disclosure, environment filter, query/provider mapping. - **Audience modes in scope**: operator-MSP, read-only operator/inspector, customer-safe negative boundary. - **Decision/diagnostic/raw hierarchy plan**: default item copy answers what/why/where/next safe action; operation/proof/source details stay collapsed or linked to existing authorized pages; raw payloads are absent. - **Raw/support gating plan**: no raw/support detail in inbox. Use existing source detail pages for authorized technical depth. - **One-primary-action / duplicate-truth control**: each item has one dominant primary action: `Continue preparation`, `Inspect preparation`, or in narrowly validated waiting cases `Open operation`. - **Handling modes by drift class or surface**: review-mandatory for operation-link disclosure; hard-stop if inline mutation or customer leakage appears. - **Repository-signal treatment**: existing Governance Inbox and Resolution Page are repo-real; no new navigation/page report unless implementation materially changes UI patterns. - **Special surface test profiles**: governance workbench / standard-native-filament; browser smoke for representative states where harness exists. - **Required tests or manual smoke**: functional-core mapping, RBAC/scope negative cases, operation-link disclosure, no inline mutation, no customer leakage, mobile/readability smoke where available. - **Exception path and spread control**: none. A concrete provider class is allowed; a generic registry is not. - **Active feature PR close-out entry**: Guardrail + Smoke Coverage if browser smoke runs. - **UI/Productization coverage decision**: existing strategic surface changed; update audit registry only if runtime implementation materially changes page archetype, route, or design coverage beyond a source-family extension. - **Coverage artifacts to update**: no coverage artifact update is required during preparation because Spec 389 reuses the existing Governance Inbox route, archetype, and source-family pattern. Implementation must re-check `docs/ui-ux-enterprise-audit/route-inventory.md` and `design-coverage-matrix.md` and update them if runtime work materially changes page archetype, route inventory, strategic-surface classification, or design coverage. - **No-impact rationale**: N/A. - **Navigation / Filament provider-panel handling**: no panel provider or navigation registration changes. - **Screenshot or page-report need**: screenshots recommended under this spec if browser harness is available; no new page report by default. ## Shared Pattern & System Fit - **Cross-cutting feature marker**: yes. - **Systems touched**: - Governance Inbox page and source-family builder. - Review Publication Resolution case/step/proof state. - Environment Review resource URLs. - OperationRun link and policy systems. - Capability-first RBAC and workspace/environment scope enforcement. - **Shared abstractions reused**: - Existing `GovernanceInboxSectionBuilder` entry shape and `GovernanceInbox` lane normalization. - Existing `ReviewPublicationResolutionCasePolicy`. - Existing `ReviewPublicationResolutionStepAuthorizer`. - Existing Spec 388 `ResolutionProofEvaluation`/currentness metadata. - Existing `OperationRunLinks` and `OperationRunPolicy`. - **New abstraction introduced? why?**: Prefer a small concrete `ReviewPublicationResolutionInboxProvider` if direct builder growth would make scope/currentness mapping hard to review. It must not be a registry, interface hierarchy, or generic adapter framework. - **Why the existing abstraction was sufficient or insufficient**: Existing Governance Inbox builder is sufficient for rendering and lane normalization; it lacks only a concrete source of Review Publication Resolution Cases. - **Bounded deviation / spread control**: provider may return normalized display arrays or a lightweight DTO only for this source family. Future adapters need separate specs. ## OperationRun UX Impact - **Touches OperationRun start/completion/link UX?**: yes, link display only. - **Central contract reused**: `OperationRunLinks` for labels/URLs and `OperationRunPolicy` for authorization after additional context/currentness validation. - **Delegated UX behaviors**: tenant/workspace-safe URL resolution only; no queued toast, artifact link, browser event, dedupe/start failure, or terminal notification changes. - **Surface-owned behavior kept local**: deciding whether a validated operation link is shown for an inbox item. - **Queued DB-notification policy**: N/A. - **Terminal notification path**: N/A. - **Exception path**: none. ## Provider Boundary & Portability Fit - **Shared provider/platform boundary touched?**: no new shared provider boundary. - **Provider-owned seams**: existing report/evidence/review-pack preparation remains owned by Review Publication Resolution and source services. - **Platform-core seams**: Governance Inbox consumes safe work item summaries and links only. - **Neutral platform terms / contracts preserved**: workspace, environment, review, operation, proof, preparation, governance inbox. - **Retained provider-specific semantics and why**: required report dimensions may originate in Microsoft/Entra workflows, but the inbox presents human labels only and does not expose provider payloads. - **Bounded extraction or follow-up path**: future restore/provider/baseline/report delivery intakes are follow-up specs only. ## Constitution Check *GATE: Must pass before implementation. Re-check after implementation design is finalized.* - Inventory-first: N/A for new inventory; consumes existing review/resolution artifacts only. - Read/write separation: PASS. Governance Inbox remains read-only; all writes stay on source-owned Resolution/Review pages with existing confirmation/audit. - Graph contract path: PASS. No Graph calls may occur during inbox render. - Deterministic capabilities: PASS. Use existing capability resolvers/policies; no raw role strings. - RBAC-UX: PASS. Workspace membership, environment entitlement, review/case permission, 404/403 semantics, and server-side policies stay authoritative. - Workspace isolation: PASS. Queries must scope by workspace before mapping. - Tenant/environment isolation: PASS. Environment-specific cases must not appear outside authorized environments or another environment filter. - Run observability: PASS. No new operation starts; linked OperationRuns remain execution truth. - OperationRun start UX: PASS. Only safe links are displayed; no start UX added. - Ops-UX lifecycle: PASS. No OperationRun status/outcome changes. - Summary counts contract: N/A. - Ops-UX guards: N/A unless implementation touches operation guard patterns. - Data minimization: PASS. Safe metadata is display-only and excludes raw payloads/secrets/tokens/exceptions/fingerprints/reason codes by default. - Test governance: PASS if tasks add focused Feature/Filament/browser tests with explicit lane classification. - Proportionality: PASS. One concrete provider/mapping is justified by an existing workflow visibility gap. - No premature abstraction: PASS. No registry/engine/generic adapter is approved. - Persisted truth: PASS. No new persistence. - Behavioral state: PASS. Inbox status is derived viewer-relative display only. - UI semantics: PASS if direct mapping from canonical case/step/safe proof state is used without a new taxonomy framework. - Shared pattern first: PASS. Existing Governance Inbox and OperationRun links are reused. - Provider boundary: PASS. No platform-core provider coupling added. - V1 explicitness / few layers: PASS. Direct source-specific mapping preferred. - Spec discipline / bloat check: PASS. Scope is one coherent, narrow spec. - Filament-native UI: PASS. Existing Filament primitives and page pattern reused. - Decision-first operating model: PASS. Existing Governance Inbox remains the primary decision surface; no new navigation. - Audience-aware disclosure: PASS. Customer-facing surfaces do not receive internal resolution intake. - UI/Productization coverage: PASS. Existing strategic surface change is classified. ## Test Governance Check - **Test purpose / classification by changed surface**: Feature for mapping and RBAC/scope; Filament/Livewire Feature for page rendering; Browser for representative visual/user workflow and mobile/customer no-leakage if harness exists. - **Affected validation lanes**: fast-feedback, confidence, optional browser. - **Why this lane mix is the narrowest sufficient proof**: Runtime change is read-only mapping/UI. It does not need PostgreSQL unless indexes/migrations are later added. - **Narrowest proving command(s)**: - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/GovernanceInbox/Spec389GovernanceInboxResolutionIntakeTest.php` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/EnvironmentReview/Spec386ReviewPublicationResolutionWorkflowTest.php tests/Feature/EnvironmentReview/Spec387ReviewPublicationResolutionDecisionUxTest.php tests/Feature/EnvironmentReview/Spec388ReviewPublicationProofCurrentnessTest.php` - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec389GovernanceInboxResolutionIntakeTest.php` if added - `cd apps/platform && ./vendor/bin/pint --dirty --format agent` - `git diff --check` - **Fixture / helper / factory / seed / context cost risks**: Review/resolution/operation fixtures can be expensive. Keep helpers explicit and local; do not broaden global defaults. - **Expensive defaults or shared helper growth introduced?**: no planned shared default growth. - **Heavy-family additions, promotions, or visibility changes**: optional browser smoke must be explicit in file name and validation notes. - **Surface-class relief / special coverage rule**: existing governance workbench surface; browser only for representative states and mobile clarity. - **Closing validation and reviewer handoff**: verify no inline mutation, no publish, no generic engine, no operation ID leakage, no customer leakage, and correct needs-recheck fallback. - **Budget / baseline / trend follow-up**: none expected; document-in-feature if browser fixture scope grows materially. - **Review-stop questions**: Did every operation link pass more than permission? Did stale state fail closed? Did read-only users avoid execution? Did customers see nothing internal? - **Escalation path**: document-in-feature for contained fixture cost; follow-up-spec for repeated generic-intake pressure. - **Active feature PR close-out entry**: Guardrail / Smoke Coverage. - **Why no dedicated follow-up spec is needed**: v1 is source-specific and bounded. Generic intake for future adapters is explicitly rejected. ## Project Structure ### Documentation (this feature) ```text specs/389-governance-inbox-resolution-intake-v1/ |-- artifacts/ | `-- current-governance-inbox-inventory.md |-- checklists/ | `-- requirements.md |-- contracts/ | |-- review-publication-resolution-inbox-item.md | `-- status-mapping.md |-- plan.md |-- spec.md `-- tasks.md ``` ### Source Code (repository root) Likely runtime surfaces for later implementation: ```text apps/platform/ |-- app/ | |-- Filament/ | | |-- Pages/Governance/GovernanceInbox.php | | `-- Resources/EnvironmentReviewResource/ | | `-- Pages/ResolveReviewPublication.php | |-- Models/ | | |-- ReviewPublicationResolutionCase.php | | `-- ReviewPublicationResolutionStep.php | |-- Policies/ | | |-- OperationRunPolicy.php | | `-- ReviewPublicationResolutionCasePolicy.php | `-- Support/ | |-- GovernanceInbox/ | | |-- GovernanceInboxSectionBuilder.php | | `-- ReviewPublicationResolutionInboxProvider.php (candidate) | |-- OperationRunLinks.php | `-- ReviewPublicationResolution/ | |-- ReviewPublicationProofResolver.php | |-- ReviewPublicationResolutionCaseStatus.php | |-- ReviewPublicationResolutionStepAuthorizer.php | `-- ReviewPublicationResolutionStepStatus.php |-- resources/views/filament/pages/governance/governance-inbox.blade.php `-- tests/ |-- Feature/GovernanceInbox/Spec389GovernanceInboxResolutionIntakeTest.php `-- Browser/Spec389GovernanceInboxResolutionIntakeTest.php (if browser coverage is added) ``` ## Technical Approach 1. Extend the existing Governance Inbox data pipeline with a concrete Review Publication Resolution source family. 2. Query `ReviewPublicationResolutionCase` records scoped by workspace and authorized environment IDs before any item mapping. 3. Eager-load only display-safe relationships: `tenant`, `environmentReview`, `assignee`, `creator`, `steps.operationRun`, and current step data as needed. 4. Map each visible case into the existing Governance Inbox entry shape or a lightweight display DTO that is immediately normalized by the existing page. 5. Add bounded status, environment, type/source-family, and updated-date filtering using the existing Governance Inbox query-string and filter conventions. Updated-date v1 presets are `Any time`, `Last 24 hours`, `Last 7 days`, and `Last 30 days`. 6. Compute viewer-relative inbox status from existing case status, current step status, StepAuthorizer result, and Spec 388 proof/currentness metadata. 7. Revalidate any OperationRun link with: - same workspace - same environment - same EnvironmentReview context where available - same Resolution Case and current Step - expected operation/action type for the step - Spec 388 currentness/usability/visibility rules - `OperationRunPolicy::view` 8. If validation cannot be done cheaply and safely in list rendering, show `Needs re-check` and link to the Resolution Page. 9. Render default item copy through existing Governance Inbox lanes/source detail without exposing internal keys or raw metadata. ## Domain / Model Implications - No new persisted model is planned. - `ReviewPublicationResolutionCase` remains workflow state, not inbox truth. - `ReviewPublicationResolutionStep` remains step/proof state, not inbox truth. - Inbox status is derived per viewer and must not be written back. - `completed`, `cancelled`, and `superseded` are hidden by default. - Existing `assigned_to_user_id`, `status`, `updated_at`, and `managed_environment_id` indexes from Spec 386 should be used before adding schema churn. ## UI / Filament Implications - Livewire v4.0+ compliance: the app runs Livewire 4.1.4 and no Livewire v3 APIs are planned. - Provider registration location: no panel provider changes; Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`. - Global search: no new Resource and no new global-search surface. Existing global search rules remain unchanged. - Destructive/high-impact actions: none added to Governance Inbox. Existing Resolution Page actions keep confirmation, authorization, audit, and tests. - Asset strategy: no new registered Filament assets expected; `filament:assets` is not newly required by this spec. - Testing plan: Feature/Filament tests for the Governance Inbox item mapping/rendering and optional browser smoke for representative states. ## RBAC / Policy Implications - Use existing workspace membership and environment entitlement patterns. - Use `ReviewPublicationResolutionCasePolicy::view` for case visibility. - Use `ReviewPublicationResolutionStepAuthorizer` only to derive viewer-relative `ready_to_continue` versus `blocked`/inspection behavior. - Use `OperationRunPolicy::view` as necessary but not sufficient for operation disclosure. - Hide inaccessible rows instead of exposing counts. - Preserve read-only inspection behavior for users who can view cases but cannot execute steps. ## Audit / Logging / Evidence Implications - Inbox list rendering does not emit audit events. - Clicking a navigation link may rely on existing page-level behavior; no new audit event is required unless implementation adds persisted state, which is not planned. - No raw provider, Graph, evidence, report, exception, token, secret, readiness fingerprint, proof reason code, or operation metadata should be logged or rendered from the inbox. ## Data / Migration Implications - Preferred: no migration. - Existing Spec 386 migration already added: - `review_publication_cases_status_idx` - `review_publication_cases_review_action_idx` - `review_publication_cases_assigned_to_idx` - step `operation_run_id` index - active-current partial unique index - summary GIN indexes - A new index may be considered only if implementation proves the current query path is too slow and the spec/plan are updated first. ## Performance Plan - Scope by workspace first. - Filter active statuses by default. - Filter environment IDs before mapping. - Eager-load required references in one query path. - Avoid per-row Graph/provider/API calls. - Avoid full readiness recomputation for every row. - Limit default result count to the existing inbox pattern or 25 if a new provider pagination boundary is required. - Use `Needs re-check` when currentness validation would be expensive or unsafe. ## Implementation Phases ### Phase 1 - Inventory and Contract Verification Re-read the existing Governance Inbox, Review Publication Resolution, policy, OperationRun link, and Spec 388 proof/currentness surfaces. Verify the mapping contracts in this package match current repo truth before code edits. ### Phase 2 - Provider / Mapping Core Implement a concrete provider or builder extension that queries visible active cases, maps case/step/proof state into inbox entries, hides default inactive states, and sorts by severity/status. ### Phase 3 - Operation Link and Currentness Hardening Add operation-link validation beyond `OperationRunPolicy::view`, including scope/context/current step/expected type/currentness checks. Fall back to `Needs re-check` when unsafe. ### Phase 4 - Governance Inbox UI Integration Add the source family/filter/section to the existing inbox rendering with decision-first labels and existing lane/source-detail behavior. Keep customer-facing surfaces untouched. ### Phase 5 - Tests, Browser Smoke, and Close-Out Add focused Feature/Filament tests, optional browser smoke/screenshots, run focused regression commands, run Pint/diff checks, and record implementation close-out without claiming unrun suite coverage. ## Risk Controls - **Generic engine risk**: only one concrete item type and provider/family; no registry. - **Inline action risk**: no step/publish/cancel actions in inbox; links only. - **Currentness risk**: use Spec 388 semantics or `Needs re-check`. - **Operation ID disclosure risk**: hide ID/link unless every validation passes. - **Customer leakage risk**: add negative tests; customer workspace remains separate. - **Performance risk**: DB-only scoped query, eager loading, no full recomputation loop. - **Viewer-relative confusion risk**: never persist inbox status; label read-only users as inspect/blocked where appropriate. ## Spec Readiness Gate This plan is ready for a later implementation loop when: - `spec.md`, `plan.md`, `tasks.md`, contracts, checklist, and inventory artifacts exist. - No unresolved clarification markers remain. - The tasks cover mapping, UI integration, RBAC/scope, operation-link hardening, currentness fallback, safe metadata, empty states, tests, browser smoke, and validation. - The implementation scope remains a bounded source-specific intake over existing Review Publication Resolution truth.