ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/346-governance-inbox-final-operator-workflow/plan.md
ahmido 8cffdbdb2c feat: governance inbox final operator workflow (spec 346) (#418) 
Implemented the final operator workflow for the Governance Inbox. This includes refactoring the inbox page, updating finding resources, adding UI enforcement policies, updating related blade views, and adding comprehensive tests for operator workflow and scope contracts.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #418
2026-06-02 14:58:39 +00:00

19 KiB
Raw Permalink Blame History

Implementation Plan: Spec 346 - Governance Inbox Final Operator Workflow

Branch: 346-governance-inbox-final-operator-workflow | Date: 2026-06-02 | Spec: specs/346-governance-inbox-final-operator-workflow/spec.md
Input: User-provided Spec 346 draft + Spec 345 next-spec recommendation + current Governance Inbox runtime truth.

Summary

Finalize the existing Governance Inbox as the daily operator queue.

This is a narrow runtime productization slice only:

  • no new governance engine
  • no new persisted inbox item state
  • no Decision Register rebuild
  • no customer portal
  • no shell/sidebar/topbar rewrite
  • no broad provider-readiness redesign
  • no new workflow mutation surface by default

The implementation should make the first screen answer:

What needs my attention, why does it matter, and what is the next action?

Status note: Spec 346 is not closed. The 2026-06-02 bounded density/productization polish is part of this same spec and must be validated before close-out is claimed.

Technical Context

  • Language/Version: PHP 8.4.15, Laravel 12.52.x.
  • Primary Dependencies: Filament v5.2.x, Livewire v4.1.x, Pest v4, Tailwind CSS v4.
  • Storage: PostgreSQL; no schema change expected.
  • Testing: Pest Feature tests plus one bounded Pest Browser smoke file.
  • Validation Lanes: confidence + browser.
  • Target Platform: apps/platform Laravel monolith; Sail-first locally; Dokploy/container posture unchanged.
  • Project Type: web application.
  • Performance Goals: DB-only page render, no Graph/provider calls during render, bounded lane counts/previews, eager loading only where relationship-backed labels or links require it.
  • Constraints: no hidden environment scope, no /admin/t resurrection, no retired query alias support, no new persisted state, no false customer-safe/legal/compliance claims, diagnostics-secondary ordering, and no cross-workspace leakage.
  • Scale/Scope: one existing strategic page, one existing section builder, one existing ledger surface, targeted Feature coverage, one Browser smoke, and spec-local prep artifacts.

UI / Surface Guardrail Plan

  • Guardrail scope: material change to an existing strategic operator surface (UI-028).
  • 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
    • linked existing routes for DecisionRegister, findings, finding exceptions, review workspace, evidence, review packs, operations, and provider-readiness destinations where repo-backed
  • No-impact class, if applicable: N/A
  • Native vs custom classification summary: native Filament page plus existing Blade composition; keep new UI on Filament/shared primitives first
  • Shared-family relevance: governance queue summaries, evidence/proof links, workspace hub filtering, review linkage, navigation continuity
  • State layers in scope: page payload, URL query filter, secondary diagnostics disclosure, current source-link actions
  • Audience modes in scope: operator-MSP, manager, support where authorized
  • Decision/diagnostic/raw hierarchy plan: summary and lanes first, linked proof second, diagnostics third
  • Raw/support gating plan: collapsed or clearly secondary; capability-gated where the current source surface requires it
  • One-primary-action / duplicate-truth control: each active item keeps one dominant next action; supporting links stay secondary
  • Repository-signal treatment: review-mandatory because this is a strategic operator surface with existing audit/report coverage
  • Special surface test profiles: global-context-shell plus decision-first disclosure
  • Required tests or manual smoke: functional-core + browser smoke
  • Exception path and spread control: no new runtime framework. Any page-local lane DTO/helper must stay bounded to GovernanceInbox
  • Active feature PR close-out entry: Guardrail / Smoke Coverage
  • UI/Productization coverage decision: update docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md; update route inventory or coverage matrix only if route/archetype classification changes materially

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes
  • Systems touched:
    • Governance Inbox page/view/builder
    • Decision Register linkage
    • current findings / exception queues and detail surfaces
    • current review workspace and related review artifacts
    • evidence/proof and operation-run link helpers
    • workspace hub environment filter and clear-filter contracts
  • Shared abstractions reused:
    • GovernanceInboxSectionBuilder
    • CanonicalNavigationContext
    • WorkspaceHubEnvironmentFilter
    • WorkspaceHubNavigation
    • OperationRunLinks
    • existing resource/page URL helpers and current policy/capability checks
  • New abstraction introduced? why?: none by default. A small page-local lane mapper or DTO is allowed only if it reduces scattered view/page logic and remains local to GovernanceInbox
  • Why the existing abstraction was sufficient or insufficient: current abstractions already provide truth and drill-through. They do not yet provide the final operator lane hierarchy, summary counts, or resolved/blocked segregation required by Spec 345.
  • Bounded deviation / spread control: do not create a generic governance queue framework, a new shared taxonomy layer, or a new persisted truth

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: existing proof links only
  • Central contract reused: OperationRunLinks and current operation URLs
  • Delegated UX behaviors: operation deep-link resolution stays shared; no new operation start/toast/notification lifecycle
  • Surface-owned behavior kept local: explicit blocker display and link selection for blocked items only
  • Queued DB-notification policy: N/A
  • Terminal notification path: unchanged
  • Exception path: none

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: no new provider seam
  • Provider-owned seams: N/A
  • Platform-core seams: governance queue, decision linkage, evidence/review/proof presentation over current workspace/environment artifacts
  • Neutral platform terms / contracts preserved: workspace, environment, governance inbox, decision, review-ready, blocked, evidence, accepted risk, diagnostics
  • Retained provider-specific semantics and why: only where underlying source content is already repo-backed
  • Bounded extraction or follow-up path: provider readiness remains a separate follow-up spec

Current Repo Truth Summary

  • GovernanceInbox already exists, is registered in the admin panel, and currently renders:
    • a decision workbench
    • secondary family filters
    • a detail aside
    • diagnostics disclosure
    • a queue context below
  • GovernanceInboxSectionBuilder already derives the current source families:
    • assigned findings
    • intake findings
    • finding exceptions
    • stale operations
    • alert delivery failures
    • review follow-up
  • DecisionRegister already exists as /admin/governance/decisions and should remain the historical/proof ledger
  • current Governance Inbox tests already verify:
    • rendered workbench copy and missing-state honesty
    • accepted-risk/exception visibility
    • environment filter behavior
    • diagnostics hidden by default
    • current browser smoke and screenshot artifact behavior
  • current UI audit docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md already records the remaining gap: one dominant queue-clearing model, better separation of evidence/status dimensions, and safer downstream wording

Implementation Approach

Phase 0 - Repo Truth Gate

  1. Re-read this spec, plan, tasks, and the related completed context only:
    • Specs 250, 257, 265, 306, 307, 308, 327, 342, 343, 344, 345
  2. Inspect current runtime files before editing:
    • GovernanceInbox.php
    • governance-inbox.blade.php
    • GovernanceInboxSectionBuilder.php
    • DecisionRegister.php
  3. Create specs/346-governance-inbox-final-operator-workflow/repo-truth-map.md documenting:
    • current families
    • current item fields
    • current proof/link destinations
    • current scope/filter contract
    • current gaps against Spec 346
  4. Do not invent unsupported states. If the repo cannot derive Review-ready or Recently resolved truthfully, document the limitation and keep the v1 lane set smaller.

Phase 1 - Tests First

  1. Add focused Feature coverage for:
    • summary-first hierarchy
    • operator lane headings
    • reason/impact/next-action rendering
    • visible environment_id state
    • empty state and blocked state
    • resolved items staying secondary
  2. Add focused Navigation coverage for:
    • canonical environment_id links only
    • no retired query alias usage
    • correct destination URLs for decision/review/evidence/operation links
  3. Reuse existing governance inbox fixtures/helpers where possible; do not widen suite defaults.

Phase 2 - Lane Classification Contract

  1. Create specs/346-governance-inbox-final-operator-workflow/contracts/lane-classification.md
  2. Define the smallest truthful mapping from current source families/item states into operator lanes
  3. Keep the mapping derived and local
  4. Prefer conservative omission or unsupported documentation over invented lane logic

Expected direction:

  • Needs triage
  • Requires decision
  • Risk / exception review
  • Blocked
  • Evidence required only when current truth supports it
  • Review-ready only when current truth supports it
  • Recently resolved only when current truth supports it

Phase 3 - Page Productization

  1. Move operator summary to the top and make it answer the first operator question immediately
  2. Refactor the primary page hierarchy around derived operator lanes rather than only source-family sections
  3. Keep one dominant next action per active item
  4. Keep diagnostics collapsed or secondary
  5. Keep queue/source context available as supporting context, not the dominant first-screen story

Phase 4 - Links, Scope, And Safety

  1. Reuse current link helpers/resources/routes for findings, decisions, evidence, review packs, operation proof, and readiness surfaces
  2. Preserve current workspace/environment filter contract and deny-as-not-found behavior
  3. Keep the page read-first by default
  4. If a new high-impact action becomes necessary, stop and update spec/plan before implementation

Phase 5 - Copy, Audit Artifact, And Screenshots

  1. Update copy/localization strings only where the runtime diff requires it
  2. Keep operator-safe, non-legalistic language
  3. Update docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md with before/after hierarchy, lane model, scope contract, and deferred follow-ups
  4. Capture screenshots under this spec package during browser smoke

Phase 6 - Browser Smoke And Validation

  1. Add one bounded Browser smoke proving:
    • summary first
    • visible lanes
    • filtered environment_id behavior
    • one representative primary action
    • return to inbox scope
    • empty or blocked state if fixtures support it
  2. Run focused validation commands
  3. Record known unreachable states honestly instead of faking fixtures

Phase 7 - Bounded Density / Productization Polish

  1. Harden the Governance Inbox page ViewModel contract so rendered actions, lanes, badges/counts, source entries, and links have consistent keys before Blade renders them.
  2. Replace indirect summary-level lane CTAs with a prioritized Next recommended action item in the first viewport when active work exists.
  3. Demote zero-count lanes into compact clear indicators while keeping active lanes prominent.
  4. Compress active item cards for mobile by keeping title, lane/status, environment, reason, impact, and primary action visible, with source/owner/evidence/decision/linked records/secondary actions behind secondary disclosure.
  5. Keep blocked-lane repetition bounded by compacting repeated detail boxes and moving repeated secondary context behind the same disclosure pattern.
  6. Verify emitted #lane-* hashes scroll to or visibly mark their lane in Browser smoke coverage.
  7. Do not add migrations, a new domain model, new mutating actions, PSA/ITSM, customer portal, or broader navigation scope.

Deployment / Ops Impact

  • Env vars: none expected
  • Migrations: none expected
  • Queues/scheduler: none expected
  • Storage/volumes: none expected
  • Filament assets: none expected; if any registered assets unexpectedly appear, deployment must include cd apps/platform && php artisan filament:assets

Test Governance Check

  • Test purpose / classification by changed surface: Feature for hierarchy/state/scope/link contracts; Browser for rendered first-screen scanability and screenshot proof
  • Affected validation lanes: confidence + browser
  • Why this lane mix is the narrowest sufficient proof: queue logic and scope are deterministic in Feature tests; first-screen scanability and operator hierarchy are user-facing product truth and need browser proof
  • Narrowest proving command(s):
cd apps/platform
./vendor/bin/sail artisan test tests/Feature/Governance/Spec346GovernanceInboxOperatorWorkflowTest.php tests/Feature/Navigation/Spec346GovernanceInboxScopeContractTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec346GovernanceInboxOperatorWorkflowSmokeTest.php --compact
./vendor/bin/sail artisan test tests/Feature/Governance/GovernanceInboxPageTest.php --compact
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec327GovernanceInboxProductizationSmokeTest.php --compact
./vendor/bin/sail artisan test tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact
./vendor/bin/sail pint --dirty
git diff --check
  • Fixture / helper / factory / seed / context cost risks: reuse existing Governance Inbox builders/fixtures and avoid creating a broad new browser fixture family
  • Expensive defaults or shared helper growth introduced?: none by default
  • Heavy-family additions, promotions, or visibility changes: one explicit browser smoke only
  • Surface-class relief / special coverage rule: no relief; this is a strategic operator surface
  • Closing validation and reviewer handoff: confirm summary-first hierarchy, truthful lane mapping, visible environment_id state, scope-correct links, no forbidden query aliases, diagnostics-secondary ordering, and no new mutation surface
  • Budget / baseline / trend follow-up: none expected beyond one explicit browser smoke
  • Review-stop questions:
    • Did the implementation invent a new workflow state or persistence?
    • Did the page silently inherit environment scope?
    • Did the page start behaving like a second Decision Register or a task engine?
    • Did diagnostics or raw details become first-screen content?
    • Did a link emit a retired public query alias?
  • Escalation path: document-in-feature for unreachable states; follow-up-spec for missing backend truth; reject-or-split for governance-engine scope creep
  • Active feature PR close-out entry: Guardrail / Smoke Coverage

Project Structure

Documentation (this feature)

specs/346-governance-inbox-final-operator-workflow/
├── spec.md
├── plan.md
├── tasks.md
├── repo-truth-map.md
├── contracts/
│   └── lane-classification.md
├── checklists/
│   └── requirements.md
└── artifacts/
    └── screenshots/

Expected implementation touch points

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/app/Filament/Pages/Governance/DecisionRegister.php
apps/platform/tests/Feature/Governance/Spec346GovernanceInboxOperatorWorkflowTest.php
apps/platform/tests/Feature/Navigation/Spec346GovernanceInboxScopeContractTest.php
apps/platform/tests/Browser/Spec346GovernanceInboxOperatorWorkflowSmokeTest.php
docs/ui-ux-enterprise-audit/page-reports/ui-004-governance-inbox.md

Supporting surfaces to inspect, not broadly redesign

apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
apps/platform/app/Filament/Resources/FindingResource.php
apps/platform/app/Filament/Resources/FindingExceptionResource.php
apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
apps/platform/app/Filament/Resources/ReviewPackResource.php
apps/platform/app/Support/Navigation/WorkspaceHubEnvironmentFilter.php
apps/platform/app/Support/Navigation/WorkspaceHubNavigation.php
apps/platform/app/Support/Navigation/CanonicalNavigationContext.php
apps/platform/app/Support/OperationRunLinks.php

Complexity Tracking

Violation Why Needed Simpler Alternative Rejected Because
Possible page-local lane mapper / DTO May be needed to keep lane grouping and item rendering testable without scattering logic across page and Blade Pure Blade-only grouping risks duplicated conditions, fragile tests, and false claims

Proportionality Review

  • New persisted truth: none
  • New abstraction: none by default; only a bounded page-local lane mapper if needed
  • New state/status family: no persisted family; lane keys remain derived
  • Ownership cost: repo-truth map, lane-classification artifact, focused tests, one browser smoke, screenshots, and page-report update
  • Rejected alternatives: new queue engine, persisted queue state, Decision Register expansion, provider-readiness merger, or cross-product workflow framework

Constitution Check

  • Inventory-first: pass; all lane and summary states derive from current records
  • Read/write separation: pass; default surface remains read-first and navigation-oriented
  • Graph contract path: pass; no Graph/provider calls during page render
  • Deterministic capabilities: pass; current policies/capabilities remain authoritative
  • Workspace/environment isolation: pass; visible environment_id contract remains central
  • Run observability: pass; operation links remain proof only
  • Data minimization: pass; raw diagnostics remain secondary
  • Test governance: pass; confidence + one browser smoke are explicit
  • Proportionality / no premature abstraction: pass with bounded local mapper guard
  • Persisted truth / behavioral state: pass; no new persistence or lifecycle family
  • Shared pattern first: pass; reuse current inbox/decision/review/evidence/link helpers
  • Provider boundary: pass; no provider seam change
  • UI/Productization coverage: pass; existing strategic surface is updated with explicit page-report maintenance
  • Filament v5 / Livewire v4 compliance: required and explicit
  • Provider registration: unchanged in apps/platform/bootstrap/providers.php
  • Global search posture: no resource global-search change is expected; existing sensitive resources stay disabled or unchanged