ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a4f2629493
TenantAtlas/specs/155-tenant-review-layer/tasks.md
ahmido a4f2629493 feat: add tenant review layer (#185) 
## Summary
- add the tenant review domain with tenant-scoped review library, canonical workspace review register, lifecycle actions, and review-derived executive pack export
- extend review pack, operations, audit, capability, and badge infrastructure to support review composition, publication, export, and recurring review cycles
- add product backlog and audit documentation updates for tenant review and semantic-clarity follow-up candidates

## Testing
- `vendor/bin/sail bin pint --dirty --format agent`
- `vendor/bin/sail artisan test --compact --filter="TenantReview"`
- `CI=1 vendor/bin/sail artisan test --compact`

## Notes
- Livewire v4+ compliant via existing Filament v5 stack
- panel providers remain in `bootstrap/providers.php` via existing Laravel 12 structure; no provider registration moved to `bootstrap/app.php`
- `TenantReviewResource` is not globally searchable, so the Filament edit/view global-search constraint does not apply
- destructive review actions use action handlers with confirmation and policy enforcement

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #185
2026-03-21 22:03:01 +00:00

19 KiB
Raw Blame History

Tasks: Tenant Review Layer

Input: Design documents from /specs/155-tenant-review-layer/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

Tests: For runtime behavior changes in this repo, tests are REQUIRED (Pest). Only docs-only changes may omit tests. Operations: Review composition and executive-pack export reuse the canonical OperationRun flow. Publish and archive remain synchronous DB-backed mutations and must emit audit history. RBAC: Tenant review detail/mutations run in the tenant/admin plane; the workspace review register runs in the workspace-admin canonical plane. Non-members or wrong-scope users must receive 404; in-scope users lacking capability must receive 403. UI Naming: Primary operator-facing verbs remain Create review, Refresh review, Publish review, Export executive pack, and Archive review. Filament UI Action Surfaces: Tenant review list/detail and workspace register must honor the spec action matrix, clickable inspection affordances, confirmation for destructive actions, and audit coverage for relevant mutations. Filament UI UX-001: Create flows must keep inputs inside sections, detail must use an Infolist-style inspection surface, and empty states must provide exactly one CTA. Badges: Review lifecycle state and completeness state must use BadgeCatalog / BadgeRenderer with mapping tests.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Phase 1: Setup (Shared Infrastructure)

Purpose: Introduce the shared enums, capability vocabulary, and operation metadata that every review flow depends on.

  • T001 Add tenant review state enums and derived publication/export-readiness badge mappings in app/Support/TenantReviewStatus.php, app/Support/TenantReviewCompletenessState.php, app/Support/Badges/Domains/TenantReviewStatusBadge.php, app/Support/Badges/Domains/TenantReviewCompletenessStateBadge.php, and app/Support/Badges/BadgeCatalog.php
  • T002 [P] Register tenant_review.view and tenant_review.manage in app/Support/Auth/Capabilities.php and app/Services/Auth/RoleCapabilityMap.php
  • T003 [P] Reserve tenant-review operation metadata in app/Support/OperationRunType.php, app/Support/OperationCatalog.php, and app/Services/SystemConsole/OperationRunTriageService.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Build the data model, policy enforcement, and composition services that block all user stories.

⚠️ CRITICAL: No user story work can begin until this phase is complete.

  • T004 Create tenant review persistence schema in database/migrations/2026_03_20_000000_create_tenant_reviews_table.php, database/migrations/2026_03_20_000100_create_tenant_review_sections_table.php, and database/migrations/2026_03_20_000200_add_tenant_review_id_to_review_packs_table.php
  • T005 [P] Add review aggregate models and relationships in app/Models/TenantReview.php, app/Models/TenantReviewSection.php, app/Models/ReviewPack.php, app/Models/EvidenceSnapshot.php, and app/Models/Tenant.php
  • T006 [P] Enforce tenant review authorization in app/Policies/TenantReviewPolicy.php and app/Providers/AuthServiceProvider.php
  • T007 [P] Register tenant review ownership with workspace-isolation helpers in app/Support/WorkspaceIsolation/TenantOwnedModelFamilies.php
  • T008 Implement core review composition services in app/Services/TenantReviews/TenantReviewService.php, app/Services/TenantReviews/TenantReviewComposer.php, and app/Services/TenantReviews/TenantReviewSectionFactory.php
  • T009 Implement fingerprinting and readiness rules in app/Services/TenantReviews/TenantReviewFingerprint.php and app/Services/TenantReviews/TenantReviewReadinessGate.php

Checkpoint: Foundation ready. User story work can now proceed.

Phase 3: User Story 1 - Prepare one tenant review from curated evidence (Priority: P1)

Goal: Allow an entitled operator to create and inspect a tenant review anchored to one chosen evidence snapshot, with explicit completeness and immutable evidence-basis semantics.

Independent Test: Create a review from an eligible evidence snapshot, verify the review stores the anchored evidence basis and section completeness, then change live source data and confirm the review remains tied to its original basis until explicitly refreshed.

Tests for User Story 1

  • T010 [P] [US1] Add anchored-review creation coverage in tests/Feature/TenantReview/TenantReviewCreationTest.php
  • T011 [P] [US1] Add review composition and badge mapping coverage in tests/Unit/TenantReview/TenantReviewComposerTest.php and tests/Unit/TenantReview/TenantReviewBadgeTest.php
  • T012 [P] [US1] Add compose-run Ops-UX regression coverage in tests/Feature/TenantReview/TenantReviewOperationsUxTest.php
  • T013 [P] [US1] Add tenant-scope authorization coverage for create, view, and refresh in tests/Feature/TenantReview/TenantReviewRbacTest.php

Implementation for User Story 1

  • T014 [US1] Implement create and refresh orchestration with immutable evidence anchoring in app/Services/TenantReviews/TenantReviewService.php, app/Services/TenantReviews/TenantReviewComposer.php, and app/Jobs/ComposeTenantReviewJob.php
  • T015 [US1] Create the tenant-scoped Filament resource and list/detail pages in app/Filament/Resources/TenantReviewResource.php, app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php, and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
  • T016 [US1] Build the review detail infolist, section completeness rendering, and evidence drill-down links in app/Filament/Resources/TenantReviewResource.php
  • T017 [US1] Implement the Create review modal, Refresh review action, row inspection affordance, and tenant-library empty state in app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
  • T018 [US1] Wire review composition runs to canonical operations UX in app/Jobs/ComposeTenantReviewJob.php, app/Services/OperationRunService.php, app/Support/OpsUx/OperationUxPresenter.php, and app/Notifications/OperationRunCompleted.php
  • T019 [US1] Record create and refresh audit events plus stored evidence-basis metadata in app/Services/TenantReviews/TenantReviewService.php and app/Models/TenantReview.php

Checkpoint: User Story 1 is independently functional when a tenant review can be created, inspected, refreshed, and audited without leaking live-source changes into the anchored review.

Phase 4: User Story 2 - Present an executive-ready tenant review pack (Priority: P1)

Goal: Present a stakeholder-ready review detail and exportable executive pack derived from the prepared tenant review, with clear readiness gates and immutable published history.

Independent Test: Open a prepared tenant review, verify the executive sections and disclosures, publish the review, export the executive pack, and confirm the exported artifact matches the same section ordering and summary truth shown in the product.

Tests for User Story 2

  • T020 [P] [US2] Add executive detail and pack-consistency coverage in tests/Feature/TenantReview/TenantReviewExecutivePackTest.php
  • T021 [P] [US2] Add publish, archive, and readiness-gate coverage in tests/Feature/TenantReview/TenantReviewLifecycleTest.php
  • T022 [P] [US2] Add review-derived export integration coverage in tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php
  • T023 [P] [US2] Add export-run Ops-UX guard coverage for lifecycle ownership, summary counts, and terminal notifications in tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php

Implementation for User Story 2

  • T024 [US2] Implement publish, archive, successor, and duplicate-prevention lifecycle rules in app/Services/TenantReviews/TenantReviewLifecycleService.php, app/Services/TenantReviews/TenantReviewReadinessGate.php, and app/Models/TenantReview.php
  • T025 [P] [US2] Extend review-derived review-pack generation and download flow in app/Services/ReviewPackService.php, app/Jobs/GenerateReviewPackJob.php, app/Http/Controllers/ReviewPackDownloadController.php, and app/Models/ReviewPack.php
  • T026 [P] [US2] Add executive summary, disclosure sections, and detail-page header actions in app/Filament/Resources/TenantReviewResource.php and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
  • T027 [US2] Reuse canonical export-run messaging, monitoring links, and summary-count keys for Export executive pack in app/Support/OperationCatalog.php, app/Support/OpsUx/OperationUxPresenter.php, app/Support/OpsUx/OperationSummaryKeys.php, and app/Services/SystemConsole/OperationRunTriageService.php
  • T028 [US2] Record publish, archive, and export audit history with aligned operator-facing copy in app/Services/TenantReviews/TenantReviewLifecycleService.php and app/Services/ReviewPackService.php
  • T029 [US2] Surface review-derived export metadata and navigation in app/Filament/Widgets/Tenant/TenantReviewPackCard.php and app/Filament/Resources/ReviewPackResource.php

Checkpoint: User Story 2 is independently functional when an operator can inspect a stakeholder-ready review, publish it safely, and export a matching executive pack with readiness failures explained clearly.

Phase 5: User Story 3 - Manage recurring tenant reviews over time (Priority: P2)

Goal: Provide a canonical workspace review register and recurring-cycle workflow that shows only entitled tenants while preserving published review history.

Independent Test: Create reviews for multiple tenants, open the workspace register, confirm only entitled tenants appear with correct lifecycle and recency signals, then start a new cycle from a published review and verify a successor draft is created instead of mutating history.

Tests for User Story 3

  • T030 [P] [US3] Add workspace review register filtering, positive visibility, and empty-state coverage in tests/Feature/TenantReview/TenantReviewRegisterTest.php
  • T031 [P] [US3] Add tenant-context prefilter and authorized filter-option scoping coverage in tests/Feature/TenantReview/TenantReviewRegisterPrefilterTest.php
  • T032 [P] [US3] Add canonical register deny-as-not-found and capability coverage in tests/Feature/TenantReview/TenantReviewRegisterRbacTest.php
  • T033 [P] [US3] Add successor-cycle history coverage in tests/Feature/TenantReview/TenantReviewCycleTest.php

Implementation for User Story 3

  • T034 [US3] Implement workspace-scoped register queries, entitled-tenant filtering, and tenant-context prefilter initialization in app/Services/TenantReviews/TenantReviewRegisterService.php and app/Models/TenantReview.php
  • T035 [P] [US3] Create the canonical workspace review register page in app/Filament/Pages/Reviews/ReviewRegister.php
  • T036 [P] [US3] Register tenant-review navigation and page discovery in app/Providers/Filament/TenantPanelProvider.php and app/Providers/Filament/AdminPanelProvider.php
  • T037 [US3] Implement register table filters, authorized filter-option scoping, row navigation, and one-CTA empty-state behavior in app/Filament/Pages/Reviews/ReviewRegister.php
  • T038 [US3] Add Create next review successor flow on published reviews in app/Services/TenantReviews/TenantReviewLifecycleService.php and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php

Checkpoint: User Story 3 is independently functional when the workspace register safely lists entitled tenant reviews and operators can start the next cycle without mutating published history.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final hardening, performance, and verification across all stories.

  • T039 [P] Add global-search and record-title decisions for tenant reviews in app/Filament/Resources/TenantReviewResource.php and app/Models/TenantReview.php
  • T040 [P] Add cross-story audit-log and UI-contract regression coverage in tests/Feature/TenantReview/TenantReviewAuditLogTest.php and tests/Feature/TenantReview/TenantReviewUiContractTest.php
  • T041 Harden eager loading, list performance, and review-pack query paths in app/Services/TenantReviews/TenantReviewRegisterService.php, app/Filament/Resources/TenantReviewResource.php, and app/Jobs/GenerateReviewPackJob.php
  • T042 Run the feature validation scenarios in specs/155-tenant-review-layer/quickstart.md

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; can start immediately.
  • Foundational (Phase 2): Depends on Phase 1; blocks all user stories.
  • User Story 1 (Phase 3): Depends on Phase 2 only.
  • User Story 2 (Phase 4): Depends on Phase 2 and consumes the review aggregate delivered in User Story 1.
  • User Story 3 (Phase 5): Depends on Phase 2 and should land after User Story 1 because it surfaces recurring-cycle state from real review records.
  • Polish (Phase 6): Depends on all desired stories being complete.

User Story Dependencies

  • US1: Starts after Foundational; no dependency on other stories.
  • US2: Starts after Foundational but is most valuable once US1 review creation/detail is working.
  • US3: Starts after Foundational but depends on existing review records from US1 for meaningful validation.

Within Each User Story

  • Tests must be written first and fail before implementation.
  • Models/services before Filament surfaces where practical.
  • Operation-run wiring before exposing async actions broadly.
  • Audit and authorization coverage must ship with each mutation workflow.

Parallel Opportunities

  • T002 and T003 can run in parallel after T001.
  • T005, T006, and T007 can run in parallel after T004.
  • In US1, T010 through T013 can run in parallel.
  • In US2, T020 through T023 can run in parallel, and T025 plus T026 can run in parallel after T024.
  • In US3, T030 through T033 can run in parallel, and T035 plus T036 can run in parallel after T034.

Parallel Example: User Story 1

# Launch the US1 tests together:
Task: "Add anchored-review creation coverage in tests/Feature/TenantReview/TenantReviewCreationTest.php"
Task: "Add review composition and badge mapping coverage in tests/Unit/TenantReview/TenantReviewComposerTest.php and tests/Unit/TenantReview/TenantReviewBadgeTest.php"
Task: "Add compose-run Ops-UX regression coverage in tests/Feature/TenantReview/TenantReviewOperationsUxTest.php"
Task: "Add tenant-scope authorization coverage for create, view, and refresh in tests/Feature/TenantReview/TenantReviewRbacTest.php"

# Build the tenant review Filament surface in parallel after orchestration exists:
Task: "Create the tenant-scoped Filament resource and list/detail pages in app/Filament/Resources/TenantReviewResource.php, app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php, and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php"
Task: "Build the review detail infolist, section completeness rendering, and evidence drill-down links in app/Filament/Resources/TenantReviewResource.php"

Parallel Example: User Story 2

# Launch the US2 tests together:
Task: "Add executive detail and pack-consistency coverage in tests/Feature/TenantReview/TenantReviewExecutivePackTest.php"
Task: "Add publish, archive, and readiness-gate coverage in tests/Feature/TenantReview/TenantReviewLifecycleTest.php"
Task: "Add review-derived export integration coverage in tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php"
Task: "Add export-run Ops-UX guard coverage for lifecycle ownership, summary counts, and terminal notifications in tests/Feature/TenantReview/TenantReviewExportOperationsUxTest.php"

# Implement export surfaces in parallel after lifecycle rules exist:
Task: "Extend review-derived review-pack generation and download flow in app/Services/ReviewPackService.php, app/Jobs/GenerateReviewPackJob.php, app/Http/Controllers/ReviewPackDownloadController.php, and app/Models/ReviewPack.php"
Task: "Add executive summary, disclosure sections, and detail-page header actions in app/Filament/Resources/TenantReviewResource.php and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php"

Parallel Example: User Story 3

# Launch the US3 tests together:
Task: "Add workspace review register filtering, positive visibility, and empty-state coverage in tests/Feature/TenantReview/TenantReviewRegisterTest.php"
Task: "Add tenant-context prefilter and authorized filter-option scoping coverage in tests/Feature/TenantReview/TenantReviewRegisterPrefilterTest.php"
Task: "Add canonical register deny-as-not-found and capability coverage in tests/Feature/TenantReview/TenantReviewRegisterRbacTest.php"
Task: "Add successor-cycle history coverage in tests/Feature/TenantReview/TenantReviewCycleTest.php"

# Build the canonical register in parallel after register queries exist:
Task: "Create the canonical workspace review register page in app/Filament/Pages/Reviews/ReviewRegister.php"
Task: "Register tenant-review navigation and page discovery in app/Providers/Filament/TenantPanelProvider.php and app/Providers/Filament/AdminPanelProvider.php"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational.
  3. Complete Phase 3: User Story 1.
  4. Validate anchored review creation, completeness rendering, RBAC, and audit history.
  5. Demo tenant review creation/detail before layering exports or workspace register views.

Incremental Delivery

  1. Finish Setup + Foundational to establish the review aggregate.
  2. Deliver US1 for review creation and anchored inspection.
  3. Deliver US2 for publication and executive-pack export.
  4. Deliver US3 for recurring-cycle management and canonical register visibility.
  5. Finish with polish, performance, and regression hardening.

Parallel Team Strategy

  1. One developer handles persistence/policies/services in Phases 1-2.
  2. After Phase 2, one developer can take US1 Filament surfaces while another prepares US2 export integration tests.
  3. Once US1 data flows exist, a third developer can build US3 register surfaces and RBAC coverage.

Notes

  • [P] tasks touch different files and can run in parallel once their dependencies are complete.
  • [US1], [US2], and [US3] map directly to the user stories in spec.md.
  • Global search should only remain enabled if TenantReviewResource keeps a View page; otherwise disable it explicitly.
  • Filament v5 work here remains compatible with Livewire v4, and panel-provider changes belong in bootstrap/providers.php only if a new provider is introduced. This feature reuses the existing panel providers.