ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c0f4587d90
TenantAtlas/specs/197-shared-detail-contract/tasks.md
ahmido c0f4587d90 Spec 197: standardize shared detail family contracts (#237) 
## Summary
- standardize the shared verification report family across operation detail, onboarding, and tenant verification widget hosts
- standardize normalized settings and normalized diff family wrappers across policy, policy version, and finding detail hosts
- add parity and guard coverage plus the full Spec 197 artifacts, including recorded manual smoke evidence

## Testing
- focused Sail regression pack from `specs/197-shared-detail-contract/quickstart.md`
- local integrated-browser manual smoke for SC-197-003 and SC-197-004

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #237
2026-04-15 09:51:42 +00:00

19 KiB
Raw Blame History

Tasks: Shared Detail Micro-UI Contract

Input: Design documents from /specs/197-shared-detail-contract/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this feature. Use Pest feature coverage and Livewire-safe Filament tests via Laravel Sail. Operations: No new OperationRun, queue, scheduler, or notification lifecycle is introduced by this feature. RBAC: No new capability or authorization plane is introduced; all hosts must preserve existing deny-as-not-found and capability enforcement behavior. Release Artifact: specs/197-shared-detail-contract/migration-note.md records migrated hosts, bounded variations, manual smoke evidence, and out-of-scope follow-ups.

Organization: Tasks are grouped by user story so each family can be implemented and verified independently.

Phase 1: Setup (Shared Scaffolding)

Purpose: Create the new support, view, and test entry points that later phases will fill.

  • T001 [P] Create shared-detail support class skeletons in apps/platform/app/Filament/Support/NormalizedSettingsSurface.php and apps/platform/app/Filament/Support/NormalizedDiffSurface.php
  • T002 [P] Create family partial entry points in apps/platform/resources/views/filament/components/verification-report/summary.blade.php, apps/platform/resources/views/filament/components/verification-report/issues.blade.php, apps/platform/resources/views/filament/infolists/entries/normalized-settings/wrapper.blade.php, and apps/platform/resources/views/filament/infolists/entries/normalized-diff/wrapper.blade.php
  • T003 [P] Create focused contract-test shells in apps/platform/tests/Feature/Filament/SharedVerificationReportFamilyContractTest.php, apps/platform/tests/Feature/Filament/NormalizedDetailFamilyContractTest.php, and apps/platform/tests/Feature/Guards/SharedDetailFamilyContractGuardTest.php

Checkpoint: The new files and entry points exist so the implementation can proceed without inventing paths mid-stream.

Phase 2: Foundational (Blocking Contract Seams)

Purpose: Establish the shared support builders that every story relies on.

⚠️ CRITICAL: No user story work should start before these support seams exist.

  • T004 [P] Extend apps/platform/app/Filament/Support/VerificationReportViewer.php to build an explicit verification surface contract with shared zones and host-variation metadata
  • T005 [P] Implement normalized settings contract shaping in apps/platform/app/Filament/Support/NormalizedSettingsSurface.php for subtype, warning, and empty-state ownership
  • T006 [P] Implement normalized diff contract shaping in apps/platform/app/Filament/Support/NormalizedDiffSurface.php for availability, zero-diff, partial-state, and grouped-render ownership

Checkpoint: Verification, normalized settings, and normalized diff each have a single contract seam that hosts can consume.

Phase 3: User Story 1 - Recognize The Same Verification Surface Everywhere (Priority: P1) 🎯 MVP

Goal: Make operation detail, onboarding, and tenant verification render the same verification-family core while keeping only bounded host-specific actions and framing.

Independent Test: Render equivalent verification data through the operation detail, onboarding, and tenant widget hosts and confirm the same summary, issue/pass grouping, diagnostics contract, unavailable semantics, and authorization boundaries are recognizable everywhere.

Tests for User Story 1

  • T007 [P] [US1] Add cross-host parity assertions in apps/platform/tests/Feature/Filament/SharedVerificationReportFamilyContractTest.php for operation detail, onboarding, and tenant widget verification hosts
  • T008 [P] [US1] Extend DB-only and widget regressions in apps/platform/tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php and apps/platform/tests/Feature/Filament/TenantVerificationReportWidgetTest.php
  • T009 [P] [US1] Extend onboarding verification regressions in apps/platform/tests/Feature/Onboarding/OnboardingVerificationTest.php and apps/platform/tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
  • T010 [P] [US1] Extend workspace-context and onboarding entitlement regressions in apps/platform/tests/Feature/MonitoringOperationsTest.php, apps/platform/tests/Feature/Spec085/DenyAsNotFoundSemanticsTest.php, and apps/platform/tests/Feature/Onboarding/OnboardingDraftAccessTest.php so the verification-family refactor preserves 404-for-non-members and 403-for-in-scope-capability-denial behavior

Implementation for User Story 1

  • T011 [US1] Refactor apps/platform/resources/views/filament/components/verification-report-viewer.blade.php and the partials under apps/platform/resources/views/filament/components/verification-report/ to own the shared summary, issues, passed, diagnostics, next-step, and unavailable zones
  • T012 [US1] Rebuild apps/platform/resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php around the shared verification-family core while keeping assist, acknowledge, and technical-details controls host-scoped
  • T013 [US1] Route operation-detail and onboarding host context through the verification contract in apps/platform/app/Filament/Resources/OperationRunResource.php and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T014 [US1] Route tenant-widget host context through the verification contract in apps/platform/app/Filament/Widgets/Tenant/TenantVerificationReport.php and apps/platform/resources/views/filament/widgets/tenant/tenant-verification-report.blade.php

Checkpoint: Verification-family hosts share one recognizable micro-UI contract and remain DB-only, host-authorized, and operator-first.

Phase 4: User Story 2 - Inspect Normalized Settings And Diffs Consistently (Priority: P1)

Goal: Make policy, policy-version, and finding detail surfaces use one normalized settings family and one normalized diff family with explicit subtype and availability semantics.

Independent Test: Render representative policy, policy-version, and finding hosts and confirm that normalized settings and normalized diff use consistent family-owned wrappers, view behavior, subtype handling, unavailable-state semantics, and existing tenant-scope authorization behavior.

Tests for User Story 2

  • T015 [P] [US2] Add family parity assertions in apps/platform/tests/Feature/Filament/NormalizedDetailFamilyContractTest.php for policy settings, policy-version settings, policy-version diff, and finding diff hosts
  • T016 [P] [US2] Extend normalized settings regressions in apps/platform/tests/Feature/Filament/PolicyVersionSettingsTest.php and apps/platform/tests/Feature/Filament/SettingsCatalogPolicyNormalizedDiffTest.php
  • T017 [P] [US2] Extend normalized diff availability regressions in apps/platform/tests/Feature/Filament/GroupPolicyConfigurationNormalizedDiffTest.php and apps/platform/tests/Feature/Drift/DriftFindingDiffUnavailableTest.php
  • T018 [P] [US2] Extend tenant-scope authorization regressions in apps/platform/tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php, apps/platform/tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php, and apps/platform/tests/Feature/Findings/FindingRbacTest.php so normalized-detail hosts preserve deny-as-not-found and capability-safe behavior after family wiring

Implementation for User Story 2

  • T019 [US2] Refactor apps/platform/resources/views/filament/infolists/entries/normalized-settings.blade.php and subtype partials under apps/platform/resources/views/filament/infolists/entries/normalized-settings/ to own warnings, wrapper structure, subtype selection, and empty-state behavior
  • T020 [US2] Absorb or retire apps/platform/resources/views/filament/infolists/entries/policy-settings-standard.blade.php as a direct host-facing sibling so standard settings render only as a normalized-settings subtype
  • T021 [US2] Route policy and policy-version settings hosts through NormalizedSettingsSurface in apps/platform/app/Filament/Resources/PolicyResource.php and apps/platform/app/Filament/Resources/PolicyVersionResource.php
  • T022 [P] [US2] Adapt apps/platform/app/Livewire/SettingsCatalogSettingsTable.php so the settings-catalog table stays a subtype renderer under the normalized-settings family wrapper
  • T023 [US2] Refactor apps/platform/resources/views/filament/infolists/entries/normalized-diff.blade.php and the partials under apps/platform/resources/views/filament/infolists/entries/normalized-diff/ to own summary, grouped rendering, and unavailable or zero-diff states
  • T024 [US2] Route policy-version and finding diff hosts through NormalizedDiffSurface in apps/platform/app/Filament/Resources/PolicyVersionResource.php and apps/platform/app/Filament/Resources/FindingResource.php

Checkpoint: Normalized settings and diff surfaces read as one family across policy, policy-version, and finding detail hosts.

Phase 5: User Story 3 - Add Or Update A Host Without Re-Forking The Family (Priority: P2)

Goal: Make future host work extend the documented family variation points instead of silently reintroducing host-local forks.

Independent Test: Run the guard suite and verify it fails on forbidden verification tab ownership or direct top-level policy-settings-standard host usage while the contract docs enumerate the approved consumers and allowed variations.

Tests for User Story 3

  • T025 [P] [US3] Implement fork-guard coverage in apps/platform/tests/Feature/Guards/SharedDetailFamilyContractGuardTest.php for forbidden verification tab ownership and direct host-level policy-settings-standard usage

Implementation for User Story 3

  • T026 [US3] Sync approved consumers, required markers, and forbidden host patterns in specs/197-shared-detail-contract/contracts/verification-report-family.openapi.yaml and specs/197-shared-detail-contract/contracts/normalized-detail-family.openapi.yaml
  • T027 [US3] Record the migrated host inventory, bounded variations, smoke-review evidence, and out-of-scope follow-ups in specs/197-shared-detail-contract/migration-note.md

Checkpoint: Reviewers and future implementers have an executable guard and a written inventory that block ad hoc family forks.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Validate the full feature slice and record release acceptance evidence.

  • T028 [P] Run formatting for touched PHP files including apps/platform/app/Filament/Support/VerificationReportViewer.php, apps/platform/app/Filament/Support/NormalizedSettingsSurface.php, and apps/platform/app/Filament/Support/NormalizedDiffSurface.php with ./vendor/bin/sail bin pint --dirty --format agent
  • T029 Run the focused Sail validation pack from specs/197-shared-detail-contract/quickstart.md against apps/platform/tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php, apps/platform/tests/Feature/Filament/TenantVerificationReportWidgetTest.php, apps/platform/tests/Feature/Onboarding/OnboardingVerificationTest.php, apps/platform/tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php, apps/platform/tests/Feature/MonitoringOperationsTest.php, apps/platform/tests/Feature/Spec085/DenyAsNotFoundSemanticsTest.php, apps/platform/tests/Feature/Onboarding/OnboardingDraftAccessTest.php, apps/platform/tests/Feature/Filament/PolicyVersionSettingsTest.php, apps/platform/tests/Feature/Filament/SettingsCatalogPolicyNormalizedDiffTest.php, apps/platform/tests/Feature/Filament/GroupPolicyConfigurationNormalizedDiffTest.php, apps/platform/tests/Feature/Drift/DriftFindingDiffUnavailableTest.php, apps/platform/tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php, apps/platform/tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php, apps/platform/tests/Feature/Findings/FindingRbacTest.php, apps/platform/tests/Feature/Filament/SharedVerificationReportFamilyContractTest.php, apps/platform/tests/Feature/Filament/NormalizedDetailFamilyContractTest.php, and apps/platform/tests/Feature/Guards/SharedDetailFamilyContractGuardTest.php
  • T030 Execute the Manual Smoke Check in specs/197-shared-detail-contract/quickstart.md and capture SC-197-003 and SC-197-004 evidence in specs/197-shared-detail-contract/migration-note.md

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; can start immediately.
  • Foundational (Phase 2): Depends on Setup completion; blocks all user story implementation.
  • User Story 1 (Phase 3): Depends on Foundational completion.
  • User Story 2 (Phase 4): Depends on Foundational completion.
  • User Story 3 (Phase 5): Depends on User Story 1 and User Story 2 completion because the guard and inventory must reflect the final family boundaries.
  • Polish (Phase 6): Depends on all targeted user stories being complete.

User Story Dependencies

  • US1: Independent after Phase 2; no dependency on US2.
  • US2: Independent after Phase 2; no dependency on US1.
  • US3: Depends on US1 and US2 because it locks the final approved host patterns for both families.

Within Each User Story

  • Write or extend the listed tests before finishing implementation.
  • Complete support or wrapper ownership before wiring host files to the new family contracts.
  • Keep host framing and host-owned actions bounded to the variation points defined in the contracts.
  • Validate each story independently before moving to the next story or polish phase.

Parallel Opportunities

  • T001, T002, and T003 can run in parallel.
  • T004, T005, and T006 can run in parallel.
  • After Phase 2, US1 and US2 can proceed in parallel if separate implementers avoid the shared PolicyVersionResource.php touchpoint.
  • Within US1, T007, T008, T009, and T010 can run in parallel.
  • Within US2, T015, T016, T017, and T018 can run in parallel.
  • Within US3, T026 and T027 can run in parallel after T025 is in place.

Parallel Example: User Story 1

# Start the verification-family test extensions together:
Task: "T007 Add cross-host parity assertions in apps/platform/tests/Feature/Filament/SharedVerificationReportFamilyContractTest.php"
Task: "T008 Extend DB-only and widget regressions in apps/platform/tests/Feature/Verification/VerificationReportViewerDbOnlyTest.php and apps/platform/tests/Feature/Filament/TenantVerificationReportWidgetTest.php"
Task: "T009 Extend onboarding verification regressions in apps/platform/tests/Feature/Onboarding/OnboardingVerificationTest.php and apps/platform/tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php"
Task: "T010 Extend workspace-context and onboarding entitlement regressions in apps/platform/tests/Feature/MonitoringOperationsTest.php, apps/platform/tests/Feature/Spec085/DenyAsNotFoundSemanticsTest.php, and apps/platform/tests/Feature/Onboarding/OnboardingDraftAccessTest.php"

# After the shared verification wrapper is in place, these can proceed side by side:
Task: "T012 Rebuild apps/platform/resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php"
Task: "T014 Route tenant-widget host context through the verification contract in apps/platform/app/Filament/Widgets/Tenant/TenantVerificationReport.php and apps/platform/resources/views/filament/widgets/tenant/tenant-verification-report.blade.php"

Parallel Example: User Story 2

# Start the normalized-detail test extensions together:
Task: "T015 Add family parity assertions in apps/platform/tests/Feature/Filament/NormalizedDetailFamilyContractTest.php"
Task: "T016 Extend normalized settings regressions in apps/platform/tests/Feature/Filament/PolicyVersionSettingsTest.php and apps/platform/tests/Feature/Filament/SettingsCatalogPolicyNormalizedDiffTest.php"
Task: "T017 Extend normalized diff availability regressions in apps/platform/tests/Feature/Filament/GroupPolicyConfigurationNormalizedDiffTest.php and apps/platform/tests/Feature/Drift/DriftFindingDiffUnavailableTest.php"
Task: "T018 Extend tenant-scope authorization regressions in apps/platform/tests/Feature/Filament/PolicyResourceAdminTenantParityTest.php, apps/platform/tests/Feature/Filament/PolicyVersionAdminTenantParityTest.php, and apps/platform/tests/Feature/Findings/FindingRbacTest.php"

# Once the family builders exist, these can proceed in parallel without touching the same files:
Task: "T022 Adapt apps/platform/app/Livewire/SettingsCatalogSettingsTable.php"
Task: "T023 Refactor apps/platform/resources/views/filament/infolists/entries/normalized-diff.blade.php and partials under apps/platform/resources/views/filament/infolists/entries/normalized-diff/"

Parallel Example: User Story 3

# After the guard exists, finish the enforcement artifacts together:
Task: "T026 Sync approved consumers and forbidden host patterns in specs/197-shared-detail-contract/contracts/verification-report-family.openapi.yaml and specs/197-shared-detail-contract/contracts/normalized-detail-family.openapi.yaml"
Task: "T027 Record the migrated host inventory and bounded variations in specs/197-shared-detail-contract/migration-note.md"

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 the verification family independently across operation detail, onboarding, and tenant widget hosts.
  5. Demo or merge the MVP slice if the repo strategy allows partial delivery.

Incremental Delivery

  1. Finish Setup + Foundational once.
  2. Deliver US1 and validate verification-family sameness.
  3. Deliver US2 and validate normalized-detail sameness.
  4. Deliver US3 to lock the boundaries with a guard and final inventory.
  5. Finish with polish, the focused Sail pack from quickstart.md, and the manual smoke evidence recorded in migration-note.md.

Parallel Team Strategy

  1. One implementer completes Phase 1 and Phase 2.
  2. After that, one implementer can take US1 while another takes US2.
  3. US3 starts once both family implementations settle.
  4. Finish with one shared cleanup and validation pass.

Notes

  • [P] means the task can run in parallel because it touches different files and has no dependency on incomplete work.
  • [US1], [US2], and [US3] map each task back to the spec’s user stories.
  • This feature must stay inside Filament v5 + Livewire v4; no provider registration change is required because bootstrap/providers.php remains unchanged.
  • No globally searchable resource is added or removed by this feature; existing host resources continue to own their Edit or View surfaces.
  • No destructive action is introduced inside either shared family; any existing host mutation remains host-owned and must keep existing confirmation and authorization behavior.
  • No new assets are introduced, so no filament:assets deployment step changes are needed.