TenantAtlas/specs/250-decision-governance-inbox/tasks.md

description
Task list for Decision-Based Governance Inbox v1

Tasks: Decision-Based Governance Inbox v1

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/
Prerequisites: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/spec.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/checklists/requirements.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/data-model.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/contracts/governance-inbox.openapi.yaml, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md

Tests: Required (Pest). Keep proof in focused Unit and Feature lanes only, using the targeted Sail commands already captured in the feature artifacts.
Operations: The inbox introduces no new OperationRun, queue, or result ledger. It only deep-links into existing run detail surfaces through the shared operation-link contract.
RBAC: Workspace membership remains the first gate. Explicit out-of-scope tenant filters remain 404. Source-family rows and source-family destinations stay capability-gated through existing registries and policies.
Organization: Tasks are grouped by user story so the multi-family read surface, source-surface routing, and filter-safety behavior remain independently testable after the shared foundation is in place.

Test Governance Checklist

• Lane assignment stays Unit plus Feature and remains the narrowest sufficient proof for the changed behavior.
• New or changed tests stay under apps/platform/tests/Unit/Support/GovernanceInbox/ and apps/platform/tests/Feature/Governance/ only; no browser or heavy-governance lane is added.
• Shared helpers, factories, fixtures, and context defaults stay cheap by default; do not add a generic workflow fixture or seeded inbox-item state.
• Planned validation commands cover section assembly, page access, and navigation continuity without pulling in unrelated lane cost.
• The declared surface test profile remains global-context-shell because tenant-prefilter and navigation continuity are part of the page contract.
• Any bounded assembly-seam drift resolves as document-in-feature unless implementation proves a structural workflow-engine need.

Phase 1: Setup (Shared Context)

Purpose: Confirm the bounded slice, source seams, and reviewer stop conditions before runtime implementation begins.

• T001 Review the bounded slice, explicit non-goals, and guardrail expectations in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/spec.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/checklists/requirements.md
• T002 [P] Review the implementation-shaping decisions in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/data-model.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/contracts/governance-inbox.openapi.yaml, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md
• T003 [P] Confirm the source-page seams that must remain authoritative: apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php, apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php, apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/app/Filament/Pages/Monitoring/Alerts.php, apps/platform/app/Filament/Resources/AlertDeliveryResource.php, apps/platform/app/Filament/Resources/TenantReviewResource.php, and apps/platform/app/Services/PortfolioTriage/TenantTriageReviewService.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the read-only page shell, authorization boundaries, and bounded assembly seam that every user story depends on.

Critical: No user story work should begin until this phase is complete.

• T004 [P] Add focused authorization coverage for workspace membership, explicit out-of-scope tenant-prefilter 404 behavior, in-scope member 403 behavior when no qualifying family capability exists, and family-level omission rules in apps/platform/tests/Feature/Governance/GovernanceInboxAuthorizationTest.php
• T005 Create the native governance inbox page shell and Blade view in apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php and apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php, keeping the surface read-only and inside the admin plane
• T006 Resolve the section-assembly seam by reusing existing source-page query rules first; only if the page becomes unreadable, add a bounded helper under apps/platform/app/Support/GovernanceInbox/ and record the choice in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md
• T007 [P] Thread tenant and family filter state plus navigation context through apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, reusing CanonicalNavigationContext and CanonicalAdminTenantFilterState rather than introducing a page-local state system

Checkpoint: The inbox page shell, page access rules, and bounded assembly decision exist. User-story work can now proceed independently.

---

Phase 3: User Story 1 - See Multi-Family Attention In One Place (Priority: P1) MVP

Goal: Let a workspace operator see more than one visible signal family from one decision-first page without introducing a second workflow state.

Independent Test: Seed visible assigned findings, intake findings, stale operations, alert-delivery failures, and review follow-up, then verify the inbox shows calm section summaries and top previews from more than one family.

Tests for User Story 1

• T008 [P] [US1] Add unit coverage for derived section and preview-entry assembly in apps/platform/tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php
• T009 [P] [US1] Add feature coverage for multi-family page rendering, calm counts, and honest global empty-state behavior in apps/platform/tests/Feature/Governance/GovernanceInboxPageTest.php

Implementation for User Story 1

• T010 [US1] Derive the assigned-findings and intake sections from the existing query semantics in apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php and apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php without introducing new workflow-state constants
• T011 [US1] Derive the operations and alerts sections from apps/platform/app/Filament/Pages/Monitoring/Operations.php, apps/platform/app/Filament/Pages/Monitoring/Alerts.php, and apps/platform/app/Filament/Resources/AlertDeliveryResource.php, keeping the alert-family slice focused on delivery-failure attention rather than alert-rule configuration
• T012 [US1] Derive the review follow-up section from apps/platform/app/Services/PortfolioTriage/TenantTriageReviewService.php, apps/platform/app/Models/TenantTriageReview.php, and the existing review register truth, then render all visible sections on apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php

Checkpoint: User Story 1 is independently functional when more than one visible family can appear on the inbox page without new persisted workflow state.

---

Phase 4: User Story 2 - Open The Right Existing Source Surface With Context (Priority: P1)

Goal: Route every visible section and preview entry into the correct existing source surface so the inbox stays a decision hub rather than becoming a duplicate execution shell.

Independent Test: Open the inbox, use findings, operations, alerts, and review-follow-up CTAs, and verify each destination is an existing canonical source route with preserved return or source context.

Tests for User Story 2

• T013 [P] [US2] Add focused navigation-context coverage for source-surface CTAs and back-link continuity in apps/platform/tests/Feature/Governance/GovernanceInboxNavigationContextTest.php

Implementation for User Story 2

• T014 [US2] Route findings and review-follow-up sections through existing source pages using apps/platform/app/Support/Navigation/CanonicalNavigationContext.php, apps/platform/app/Support/Navigation/RelatedNavigationResolver.php, and the existing resource URL helpers on apps/platform/app/Filament/Resources/TenantReviewResource.php
• T015 [US2] Route operation attention entries through apps/platform/app/Support/OperationRunLinks.php and the canonical tenantless operation detail route /admin/operations/{run} instead of inventing a new inbox-local detail shell
• T016 [US2] Keep the inbox read-only by ensuring claim, triage, acknowledge, snooze, and follow-up mutations remain on their source surfaces; if any source surface needs small back-link hardening, change the smallest source page rather than adding local mutations on apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php

Checkpoint: User Story 2 is independently functional when every visible CTA lands on an existing source surface with preserved context and the inbox still owns no mutations.

---

Phase 5: User Story 3 - Filter The Inbox Honestly Without Leakage (Priority: P2)

Goal: Keep tenant and family filtering honest so the inbox never leaks hidden tenants, hidden families, or inaccessible source destinations.

Independent Test: Load the inbox with an active tenant context, a family filter, and an explicit hidden tenant query parameter, then verify the resulting counts, labels, and empty states are truthful.

Tests for User Story 3

• T017 [P] [US3] Extend feature coverage for tenant-prefilter state, family filters, hidden-family omission, and tenant-specific empty-state branches in apps/platform/tests/Feature/Governance/GovernanceInboxPageTest.php

Implementation for User Story 3

• T018 [US3] Add family and tenant filter handling to apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, keeping active tenant context durable and clearable without inventing a second filter persistence system
• T019 [US3] Ensure hidden tenants and hidden families never contribute to section counts, preview labels, or empty-state hints, and keep tenantless alert or operations entries truthful when rendered on apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php

Checkpoint: User Story 3 is independently functional when tenant and family filters remain capability-safe and globally honest.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Finish narrow validation, formatting, and reviewer close-out without widening scope.

• T020 [P] Run the focused unit validation command from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md against apps/platform/tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php
• T021 [P] Run the focused page and authorization validation commands from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md against apps/platform/tests/Feature/Governance/GovernanceInboxPageTest.php and apps/platform/tests/Feature/Governance/GovernanceInboxAuthorizationTest.php
• T022 [P] Run the focused navigation-context validation command from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md against apps/platform/tests/Feature/Governance/GovernanceInboxNavigationContextTest.php
• T023 Run dirty-only Pint for touched platform files using the command recorded in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md
• T024 Record the final Guardrail / Exception / Smoke Coverage close-out, including whether a bounded Support/GovernanceInbox/ seam was needed and whether any contained drift resolved as document-in-feature, in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/plan.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/quickstart.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/250-decision-governance-inbox/checklists/requirements.md

---

Dependencies & Execution Order

Phase Dependencies

• Phase 1 (Setup): no dependencies; start immediately.
• Phase 2 (Foundational): depends on Phase 1 and blocks all user-story work.
• Phase 3 (US1): depends on Phase 2 and establishes the first independently valuable slice.
• Phase 4 (US2): depends on Phase 2 and is safest after US1 because it reuses the same page and view files.
• Phase 5 (US3): depends on Phase 2 and is safest after US1 because filter and empty-state behavior depend on the final visible sections.
• Phase 6 (Polish): depends on the stories being complete.

User Story Dependencies

• US1 (P1): independently shippable as the minimal read-only decision surface once Phase 2 is complete.
• US2 (P1): independently testable after Phase 2, but should merge after US1 because the same page composition and routing files are shared hotspots.
• US3 (P2): independently testable after Phase 2, but should merge after US1 because family and tenant filters depend on the visible section set.

Within Each User Story

• Write the listed Pest coverage first and make it fail for the intended gap.
• Finish shared query or routing reuse before widening the page view.
• Re-run the narrowest relevant proof command after each story checkpoint before moving to the next story.

---

Implementation Strategy

Suggested MVP Scope

• First shippable slice = Phase 2 + User Story 1 + User Story 2. That delivers the canonical decision-first inbox page with the required multi-family attention surface and the required routing into existing source surfaces.

Incremental Delivery

1. Complete Phase 1 and Phase 2.
2. Deliver US1 and validate the multi-family read surface.
3. Deliver US2 and validate that all CTAs land on existing source surfaces.
4. Deliver US3 and validate filter honesty plus 404 handling.
5. Finish with Phase 6 validation, formatting, and close-out recording.

Team Strategy

1. Finish Phase 2 together before splitting story work.
2. Parallelize unit and feature test authoring inside each story first.
3. Serialize merges touching apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php and apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php, because they are the main conflict hotspots for this slice.

Notes

• [P] tasks should stay on different files or clearly isolated seams.
• Each story remains independently testable, but the first shippable slice includes both US1 and US2 because routing into existing source surfaces is part of the required product contract.
• Re-run the narrowest relevant Pest command after each story checkpoint before moving forward.
• Stop at each checkpoint if the page starts drifting toward a generic workflow engine or local mutation lane.