TenantAtlas/specs/257-governance-decision-convergence/tasks.md

description
Task list for Governance Decision Surface Convergence v1

Tasks: Governance Decision Surface Convergence v1

Input: Design documents from specs/257-governance-decision-convergence/
Prerequisites: specs/257-governance-decision-convergence/plan.md (required), specs/257-governance-decision-convergence/spec.md (required)

Tests: REQUIRED (Pest) for runtime behavior changes. Keep proof in narrow Unit plus Feature lanes only; do not add browser or heavy-governance coverage for this read-only convergence slice. Operations: No new OperationRun, queue, retry, monitoring page, or execution ledger is introduced. Existing stale-operation links remain unchanged. RBAC: Workspace membership remains the first boundary. Non-members or out-of-scope tenant targets return 404; in-scope members with no visible family return 403. Findings lanes reuse Capabilities::TENANT_FINDINGS_VIEW, existing inline safe actions keep their current capability checks such as Capabilities::TENANT_FINDINGS_ASSIGN, the exception lane reuses Capabilities::FINDING_EXCEPTION_APPROVE, and review handoff reuses existing review and pack visibility checks. Shared Pattern Reuse: Reuse GovernanceInbox, GovernanceInboxSectionBuilder, CanonicalNavigationContext, OperateHubShell, BadgeRenderer, and the existing specialist page action-surface contracts. No new shell, task engine, or persistence layer is allowed. Organization: Tasks are grouped by user story so the governance-home extension, navigation convergence, and calm secondary-context rules remain independently testable after the shared groundwork is complete.

Test Governance Checklist

• Lane assignment stays Unit plus Feature and remains the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in focused apps/platform/tests/Unit/Support/GovernanceInbox/, apps/platform/tests/Feature/Governance/, apps/platform/tests/Feature/Findings/, apps/platform/tests/Feature/Monitoring/, and apps/platform/tests/Feature/Reviews/ families only.
• Shared helpers, fixtures, and context defaults stay cheap by default; do not add browser setup, queue scaffolding, or generic workflow fixtures.
• Planned validation commands cover governance-home assembly, authorization, and arrival/return continuity without widening scope.
• The declared surface test profile remains global-context-shell because arrival context and tenant-filter continuity are part of the contract.
• Any broader action-center, dashboard-entry, or cross-tenant follow-up resolves as document-in-feature or follow-up-spec, not hidden implementation growth.
• Test-governance outcome resolves as keep for this feature and does not widen the work into a heavier family.

Phase 1: Setup (Shared Context)

Purpose: Confirm the bounded convergence slice, the existing governance-home seams, and the reviewer stop conditions before implementation begins.

• T001 Review the bounded convergence slice in specs/257-governance-decision-convergence/spec.md and specs/257-governance-decision-convergence/plan.md together with docs/product/roadmap.md and docs/product/implementation-ledger.md.
• T002 [P] Confirm the current governance-home families and summary seams in apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php, and apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php.
• T003 [P] Confirm the specialist-page arrival, return, and filter-state seams in 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, and apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php.

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Extend the shared governance-home and navigation seams that every user story depends on.

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

• T004 [P] Define or extend the bounded family-aware arrival and return contract inside apps/platform/app/Support/Navigation/CanonicalNavigationContext.php and any minimal supporting helper under apps/platform/app/Support/GovernanceInbox/ without creating new persistence or a generic workflow framework.
• T005 [P] Tighten family omission and access evaluation in apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php and apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php so inaccessible tenants and families disappear before counts are derived and in-scope no-family access resolves as 403.
• T006 Implement the derived finding_exceptions family in apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php using existing FindingExceptionsQueue truth, current queue semantics, and existing capability rules.
• T007 Implement truthful review-consumption handoff logic in apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php and apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php so review-follow-up entries prefer existing latest review detail and fall back to CustomerReviewWorkspace only when that is the honest destination.
• T008 [P] Update apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php to keep one dominant CTA per section and avoid duplicate workspace-summary cards as the new family is added.

Checkpoint: The governance home can derive the new family, family counts stay capability-safe, and navigation context rules are settled before story-specific work begins.

---

Phase 3: User Story 1 - Use One Canonical Governance Home (Priority: P1)

Goal: Give the operator one governance home that includes the missing exception and review-consumption lanes without creating a new shell.

Independent Test: Seed visible findings, exceptions, and review-follow-up states, open the governance inbox, and verify that the page shows the converged lanes with calm summaries and one dominant CTA per section.

Tests for User Story 1

• T009 [P] [US1] Extend apps/platform/tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php to cover exception-family inclusion, family ordering, review-workspace fallback, and omission semantics for hidden tenants or families.
• T010 [P] [US1] Extend apps/platform/tests/Feature/Governance/GovernanceInboxPageTest.php to cover the visible exception lane, review-consumption handoff summary, tenant-filter empty-state truth, and one dominant CTA per section.
• T011 [P] [US1] Extend apps/platform/tests/Feature/Governance/GovernanceInboxAuthorizationTest.php to cover 404 vs 403 behavior when workspace access exists but all converged family visibility is removed.

Implementation for User Story 1

• T012 [US1] Update apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php and apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php to render the new convergence lane and family-aware summary or empty-state copy.
• T013 [US1] Align governance-home copy in apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php and apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php to the stable vocabulary Governance inbox, Open my findings, Open findings intake, Open finding exceptions, and Open customer review workspace.

Checkpoint: User Story 1 is independently functional when the governance inbox truthfully shows the missing lane and routes to the existing specialist destinations.

---

Phase 4: User Story 2 - Move Into A Specialist Lane And Back (Priority: P1)

Goal: Preserve tenant and family context when the operator opens a specialist page from the governance home and returns.

Independent Test: Open the governance inbox with tenant and family filters, jump into a specialist page, and verify that the specialist page exposes a truthful return path back to the same governance scope.

Tests for User Story 2

• T014 [P] [US2] Add or extend apps/platform/tests/Feature/Governance/GovernanceInboxNavigationContextConvergenceTest.php for tenant and family arrival/return continuity across governance-home launches.
• T015 [P] [US2] Add or extend apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueNavigationContextTest.php for governance-home arrival, preserved tenant context, and truthful Back to governance inbox continuity.
• T016 [P] [US2] Add or extend apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php for governance-home arrival and return continuity on review-follow-up launches, preferred latest-published-review destination when available, fallback to CustomerReviewWorkspace when not, preserved read-only state, and the absence of operator-only mutation controls.
• T017 [P] [US2] Add or extend apps/platform/tests/Feature/Findings/MyFindingsInboxNavigationContextTest.php and apps/platform/tests/Feature/Findings/FindingsIntakeQueueNavigationContextTest.php for governance-home launch and return continuity on the findings specialist pages.

Implementation for User Story 2

• T018 [US2] Wire governance-home arrival and return context through apps/platform/app/Support/Navigation/CanonicalNavigationContext.php, apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php, apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php, apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php, and apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php.
• T019 [US2] Expose truthful return affordances without adding a second primary CTA. Repo truth: these native Filament pages expose the affordance through page header actions in MyFindingsInbox, FindingsIntakeQueue, FindingExceptionsQueue, and CustomerReviewWorkspace; no specialist Blade edits were required.

Checkpoint: User Story 2 is independently functional when the operator can move between the governance home and the specialist pages without losing truthful context.

---

Phase 5: User Story 3 - Keep Specialist Surfaces Calm And Secondary (Priority: P2)

Goal: Ensure the specialist pages stay focused on lane-specific truth and do not duplicate the workspace-level summary once convergence context exists.

Independent Test: Open the governance home and then each specialist surface, and verify that the specialist page keeps lane-specific content while the workspace-level blocker summary remains on the governance home only.

Tests for User Story 3

• T020 [P] [US3] Add or extend apps/platform/tests/Feature/Findings/MyFindingsInboxNavigationContextTest.php, apps/platform/tests/Feature/Findings/FindingsIntakeQueueNavigationContextTest.php, apps/platform/tests/Feature/Monitoring/FindingExceptionsQueueNavigationContextTest.php, and apps/platform/tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php to assert duplicate-truth prevention, one dominant default action on each specialist surface, and secondary-context copy when the pages are opened from the governance home.

Implementation for User Story 3

• T021 [US3] Keep lane-specific summaries focused and avoid duplicating workspace-level blocker text. Repo truth: page classes now add secondary return context while existing specialist Blade views stay lane-focused; regression tests assert the governance-home summary text is absent from secondary pages.
• T022 [US3] Align action-surface declarations, header affordances, and empty-state recovery actions across apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php, apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php, apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php, and apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php so the canonical start surface remains obvious.

Checkpoint: User Story 3 is independently functional when specialist surfaces remain lane-specific secondary contexts instead of competing starts.

---

Phase 6: Polish & Cross-Cutting Concerns

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

• T023 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/GovernanceInbox/GovernanceInboxSectionBuilderTest.php.
• T024 [P] Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Governance/GovernanceInboxPageTest.php tests/Feature/Governance/GovernanceInboxAuthorizationTest.php tests/Feature/Governance/GovernanceInboxNavigationContextConvergenceTest.php tests/Feature/Monitoring/FindingExceptionsQueueNavigationContextTest.php tests/Feature/Reviews/CustomerReviewWorkspaceNavigationContextTest.php tests/Feature/Findings/MyFindingsInboxNavigationContextTest.php tests/Feature/Findings/FindingsIntakeQueueNavigationContextTest.php.
• T025 Run export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent for touched platform files.
• T026 [P] Confirm the slice introduced no new asset registration, no new globally searchable resource, and no new mutation lane; record any bounded follow-up for broader dashboard-entry or portfolio action-center work in the active implementation notes.
• T027 [P] Confirm the slice introduced no new Graph or remote calls, no queue or OperationRun start path, and no page-view audit or runtime logging stream; record any bounded follow-up if implementation uncovers a structural need outside this slice.

---

Dependencies & Execution Order

Phase Dependencies

• Phase 1 (Setup): no dependencies; start immediately.
• Phase 2 (Foundational): depends on Phase 1 and blocks all user stories.
• Phase 3 (US1): depends on Phase 2 and establishes the canonical governance-home truth.
• Phase 4 (US2): depends on Phase 2 and should ship with US1 so the governance home is not a dead-end report.
• Phase 5 (US3): depends on Phase 2 and is safest after US1 and US2 because specialist pages must already participate in the convergence flow.
• Phase 6 (Polish): depends on all desired user stories being complete.

User Story Dependencies

• US1 (P1): independently testable after Phase 2 and establishes the new canonical decision-home behavior.
• US2 (P1): independently testable after Phase 2 and should ship with US1 so the new home has truthful workflow continuity.
• US3 (P2): independently testable after Phase 2 and refines the specialist pages once the convergence contract exists.

Within Each User Story

• After the shared foundational contract work in Phase 2 is complete, write the listed Pest coverage first for each user story and make it fail for the intended gap.
• Land the shared builder and navigation contract before widening Blade or copy work.
• Re-run the narrowest affected validation command after each story checkpoint before moving to the next story.

---

Parallel Execution Examples

User Story 1

• T009, T010, and T011 can run in parallel before runtime edits begin.
• After the family contract settles, T012 and T013 can proceed in parallel because rendering and copy alignment touch different seams.

User Story 2

• T014, T015, T016, and T017 can run in parallel because they cover different destinations in the convergence flow.
• After T018 settles the shared navigation contract, T019 can follow to align the Blade affordances.

User Story 3

• T020 can start before implementation finishes because it only captures the expected secondary-context behavior.
• T021 and T022 can proceed together once the shared convergence path is stable.

---

Implementation Strategy

Suggested MVP Scope

• MVP = US1 + US2 together. The slice becomes product-meaningful only when the governance home shows the missing lanes and the specialist pages preserve truthful return context.

Incremental Delivery

1. Complete Phase 1 and Phase 2.
2. Deliver US1 and US2 together.
3. Add US3 secondary-context tightening.
4. Finish with focused validation and formatting in Phase 6.

Team Strategy

1. Settle the governance-home family extension and navigation-context contract first.
2. Parallelize unit and feature coverage inside each story before runtime edits widen.
3. Serialize merges around the governance inbox and specialist Blade views so the decision-home language stays coherent.