# Implementation Plan: Governance Decision Surface Convergence v1

**Branch**: `257-governance-decision-convergence` | **Date**: 2026-04-29 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from [spec.md](spec.md)

## Summary

Tighten TenantPilot's decision-first operating model by converging onto the existing `GovernanceInbox` as the canonical workspace decision home, extending it with the still-missing finding-exceptions lane, and aligning the specialist findings, exceptions, and customer-review pages behind one truthful arrival and return model. The slice is intentionally read-only and reuses existing page, builder, and navigation seams instead of adding a new page shell, workflow state, or task engine.

Filament remains on Livewire v4, no panel-provider registration changes are required (`apps/platform/bootstrap/providers.php` remains authoritative), no globally searchable resource is added, and no new asset bundle is expected.

## Technical Context

**Language/Version**: PHP 8.4, Laravel 12  
**Primary Dependencies**: Filament v5, Livewire v4, Pest v4, existing governance inbox and navigation helpers  
**Storage**: PostgreSQL via existing findings, finding-exceptions, reviews, packs, alerts, and operation-run truth only  
**Testing**: Pest v4 `Unit` plus `Feature` coverage  
**Validation Lanes**: fast-feedback, confidence  
**Target Platform**: Laravel monolith in `apps/platform`, admin panel only (`/admin`)  
**Project Type**: Web application (Laravel monolith with Filament pages)  
**Performance Goals**: derived DB-only page rendering, no new remote calls, and no queue or `OperationRun` start in v1  
**Constraints**: no new persistence, no new page shell, no new mutation lane, no customer portal scope, no duplicate truth across equal-priority cards  
**Scale/Scope**: 1 existing canonical page, 4 specialist page classes plus their Blade views, and 1 bounded section-builder extension

## Likely Affected Repo 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`
- `apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php`
- `apps/platform/resources/views/filament/pages/findings/my-findings-inbox.blade.php`
- `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php`
- `apps/platform/resources/views/filament/pages/findings/findings-intake-queue.blade.php`
- `apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php`
- `apps/platform/resources/views/filament/pages/monitoring/finding-exceptions-queue.blade.php`
- `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
- `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`
- `apps/platform/app/Support/Navigation/CanonicalNavigationContext.php`
- `apps/platform/app/Support/OperateHub/OperateHubShell.php`
- `apps/platform/app/Support/Badges/BadgeRenderer.php`

## UI / Filament & Livewire Fit

- Reuse the existing `GovernanceInbox` Filament page instead of introducing a new page class or a utility shell.
- Keep the governance home as a section-based read-only page. Add one derived exception lane and adjust review-consumption handoff copy and arrival context, but keep diagnostics and proof on the existing specialist or detail routes.
- Preserve specialist-page ownership. `MyFindingsInbox`, `FindingsIntakeQueue`, `FindingExceptionsQueue`, and `CustomerReviewWorkspace` remain the pages where lane-specific truth and existing safe actions live.
- Any state that must survive navigation or Livewire requests stays on public, query-backed, or existing session-backed state. Do not move convergence state into private page properties.
- No new resource, global-search result, or panel asset registration is planned.

## RBAC / Policy Fit

- Workspace membership remains the first gate for the governance home and all converged routes.
- Findings lanes continue to reuse `Capabilities::TENANT_FINDINGS_VIEW`; existing inline safe actions such as claim remain on the owning specialist pages and continue to require their existing capabilities such as `Capabilities::TENANT_FINDINGS_ASSIGN`.
- The exception lane must reuse the existing `FindingExceptionsQueue` visibility contract based on `Capabilities::FINDING_EXCEPTION_APPROVE` rather than inventing a second exception-view capability.
- The review-consumption handoff must reuse the current review and review-pack access rules instead of adding a new customer-review-workspace capability family.
- `404` applies to non-members and out-of-scope tenant targets. `403` applies only to in-scope members who still cannot see any converged family.

## Audit / Logging Fit

- The convergence layer stays read-only and should not add a new page-view audit stream.
- Existing mutations and downloads remain audited on their current owning surfaces.
- No new `OperationRun`, notification stream, or navigation-event ledger is required.

## Data & Query Fit

- Extend `GovernanceInboxSectionBuilder` rather than creating a new persistence or projection layer.
- The new exception lane must derive from existing `FindingException` truth and the current queue semantics, not from a copied workflow summary.
- Review-consumption handoff should keep using the current latest-published-review vs customer-review-workspace fallback logic.
- Family counts, previews, and empty-state decisions must be computed only after tenant and capability filtering, so hidden tenants and hidden lanes do not leak through aggregate counts.
- Keep any new family key local to the page and builder; do not introduce a new domain enum or persisted state family.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: native Filament
- **Shared-family relevance**: governance decision home, specialist queues, customer-review routing, navigation continuity
- **State layers in scope**: page, URL-query, table/session restore
- **Audience modes in scope**: operator-MSP, customer-read-only on the existing review workspace
- **Decision/diagnostic/raw hierarchy plan**: decision-first on the governance home, diagnostics-second on specialist pages, raw/support detail remains on existing detail paths only
- **Raw/support gating plan**: hidden by default on the governance home; existing gating remains on source/detail surfaces
- **One-primary-action / duplicate-truth control**: governance home keeps one dominant CTA per section; specialist pages keep their existing lane-owned primary action and must not duplicate the governance-home summary
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory
- **Special surface test profiles**: global-context-shell
- **Required tests or manual smoke**: functional-core, state-contract
- **Exception path and spread control**: none planned
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: `GovernanceInbox`, `GovernanceInboxSectionBuilder`, `CanonicalNavigationContext`, `OperateHubShell`, `BadgeRenderer`, and the specialist findings, exception, and review pages listed above
- **Shared abstractions reused**: `GovernanceInboxSectionBuilder`, `CanonicalNavigationContext`, `OperateHubShell`, `BadgeRenderer`, and existing source-page action-surface declarations
- **New abstraction introduced? why?**: at most one bounded convergence helper for arrival and return semantics if the existing navigation-context helper needs a thin extension; no new framework or registry is justified
- **Why the existing abstraction was sufficient or insufficient**: existing abstractions are sufficient for page ownership and current routing, but not yet sufficient to make the governance home the single truthful start surface across the missing exception and review-consumption lanes
- **Bounded deviation / spread control**: no new shell or workflow engine; all implementation stays inside existing governance, findings, monitoring, reviews, and navigation seams

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no new `OperationRun` contract change
- **Central contract reused**: the already-existing stale-operations deep-link behavior remains unchanged
- **Delegated UX behaviors**: `N/A`
- **Surface-owned behavior kept local**: the governance home continues to list stale operations through the existing family, but this spec does not change that family's start or completion semantics
- **Queued DB-notification policy**: `N/A`
- **Terminal notification path**: `N/A`
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no
- **Provider-owned seams**: `N/A`
- **Platform-core seams**: existing governance and navigation vocabulary only
- **Neutral platform terms / contracts preserved**: `Governance inbox`, `finding exceptions`, `customer review workspace`, `Open lane`, and `Back to governance inbox`
- **Retained provider-specific semantics and why**: none new
- **Bounded extraction or follow-up path**: `N/A`

## Constitution Check

*GATE: Must pass before implementation preparation continues.*

- Inventory-first: PASS. All sections remain derived from existing findings, exceptions, reviews, alerts, and operation-run truth.
- Read/write separation: PASS. The convergence layer remains read-only and keeps mutations on existing source surfaces.
- Graph contract path: PASS. No new Graph or provider calls are introduced.
- Deterministic capabilities: PASS. Existing capability registries remain authoritative.
- Workspace and tenant isolation: PASS. Workspace membership remains first, and tenant/family omission happens before counts are exposed.
- RBAC-UX plane separation: PASS. Everything stays in `/admin`; no `/system` expansion.
- Destructive action discipline: PASS by non-use. No new destructive or risky actions are introduced.
- Global search: PASS. No new resource or search result is added.
- OperationRun / Ops-UX: PASS by non-use. No new run start or completion behavior exists.
- Data minimization: PASS. Default-visible content stays limited to family summaries, lane scope, and next action.
- Test governance: PASS. Proof remains in focused `Unit` and `Feature` lanes.
- Proportionality / no premature abstraction: PASS. The design extends an existing page and builder instead of introducing a new shell or engine.
- Persisted truth: PASS. No new table, artifact, or cached projection is introduced.
- Behavioral state: PASS. Any additional family key remains derived page state only.
- Shared pattern first / UI semantics / Filament-native UI: PASS. Existing page and navigation patterns are extended rather than bypassed.
- Provider boundary: PASS. No provider/platform seam widens.
- Filament/Laravel panel safety: PASS. Filament v5 stays on Livewire v4, provider registration remains in `apps/platform/bootstrap/providers.php`, and no new assets are planned.

**Gate evaluation**: PASS.

## Test Governance Check

- **Test purpose / classification by changed surface**: `Unit` for section assembly and convergence routing, `Feature` for page visibility, family omission, and navigation continuity
- **Affected validation lanes**: fast-feedback, confidence
- **Why this lane mix is the narrowest sufficient proof**: unit coverage proves derived-family assembly cheaply; feature coverage proves route access, family omission, tenant-prefilter continuity, and duplicate-truth prevention on existing pages
- **Narrowest proving command(s)**:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/GovernanceInboxPageTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/GovernanceInboxNavigationContextConvergenceTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/FindingExceptionsQueueNavigationContextTest.php`
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php`
- **Fixture / helper / factory / seed / context cost risks**: moderate; reuse existing workspace, tenant, finding, exception, and review fixtures without widening into browser or heavy-governance families
- **Expensive defaults or shared helper growth introduced?**: no
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: `global-context-shell` coverage is required because return context and tenant-filter continuity are part of the contract
- **Closing validation and reviewer handoff**: rerun the focused commands above, verify the governance home stays read-only, and confirm specialist surfaces preserve lane-specific truth without duplicating the workspace summary
- **Budget / baseline / trend follow-up**: none expected beyond a small feature-local increase
- **Review-stop questions**: lane fit, hidden fixture growth, accidental new shell, accidental new mutation lane, hidden leakage through counts
- **Escalation path**: `document-in-feature` for contained navigation-context notes; `reject-or-split` for any new shell or workflow-engine drift
- **Active feature PR close-out entry**: Guardrail / Smoke Coverage
- **Test-governance outcome**: keep
- **Why no dedicated follow-up spec is needed**: the bounded convergence work remains feature-local unless future work demands a broader dashboard or portfolio action-center spec

## Rollout & Risk Controls

- Keep the governance inbox as the only primary start surface touched by this slice.
- Keep all specialist mutations on their existing pages.
- Do not widen the exception or review lane into new workflow state.
- Prefer extending the current section builder and navigation helper over adding a new orchestrator.
- Treat any attempt to add a second workspace summary banner on the specialist pages as out-of-scope drift.

## Project Structure

### Documentation (this feature)

```text
specs/257-governance-decision-convergence/
├── checklists/
│   └── requirements.md
├── spec.md
├── plan.md
└── tasks.md
```

This preparation package intentionally stays on the core artifacts plus the review checklist. The repo truth is already known, the slice adds no new persistence or external contract, and no extra research/data-model/contracts package is required to make the implementation bounded.

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/Pages/
│   │   ├── Findings/
│   │   │   ├── MyFindingsInbox.php
│   │   │   └── FindingsIntakeQueue.php
│   │   ├── Governance/
│   │   │   └── GovernanceInbox.php
│   │   ├── Monitoring/
│   │   │   └── FindingExceptionsQueue.php
│   │   └── Reviews/
│   │       └── CustomerReviewWorkspace.php
│   └── Support/
│       ├── GovernanceInbox/
│       │   └── GovernanceInboxSectionBuilder.php
│       ├── Navigation/
│       │   └── CanonicalNavigationContext.php
│       └── OperateHub/
│           └── OperateHubShell.php
└── resources/views/filament/pages/
    ├── findings/
    │   ├── my-findings-inbox.blade.php
    │   └── findings-intake-queue.blade.php
    ├── governance/
    │   └── governance-inbox.blade.php
    ├── monitoring/
    │   └── finding-exceptions-queue.blade.php
    └── reviews/
        └── customer-review-workspace.blade.php
```

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| One additional derived family in `GovernanceInboxSectionBuilder` | the exception lane still sits outside the canonical decision home | leaving exceptions on a standalone specialist page keeps the current fragmented start state |
| One bounded convergence contract for arrival and return context | specialist pages need a truthful way back to the same governance scope | page-local ad hoc back links would drift across surfaces and duplicate navigation logic |

## Proportionality Review

- **Current operator problem**: operators still have to decide between several repo-real specialist surfaces before they can begin work.
- **Existing structure is insufficient because**: the current governance home does not yet own all high-signal lanes and the specialist pages do not clearly behave as secondary contexts.
- **Narrowest correct implementation**: extend the existing governance inbox and navigation continuity instead of adding a new shell or persisted workflow engine.
- **Ownership cost created**: maintain one more derived family, one bounded convergence helper, and focused tests.
- **Alternative intentionally rejected**: a new action-center page or persisted cross-family work queue was rejected as unnecessary structure for current-release truth.
- **Release truth**: current-release workflow compression.

## Implementation Strategy

### Suggested MVP Scope

MVP = **User Story 1 + User Story 2 together**. The convergence slice only becomes meaningful once the governance home shows the missing lanes and the specialist surfaces preserve truthful return context.

### Incremental Delivery

1. Extend the governance inbox family assembly and page rendering.
2. Add convergence-aware arrival and return semantics on the specialist pages.
3. Tighten duplicate-truth prevention and calm secondary-context copy.
4. Finish with focused validation and formatting.

### Team Strategy

1. Settle the governance inbox family extension and navigation-context contract first.
2. Parallelize unit coverage for builder behavior and feature coverage for navigation continuity.
3. Serialize merges around the shared governance inbox and specialist page views so the decision-home language stays coherent.