ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
25e0dcc353
TenantAtlas/specs/142-rbac-role-definition-diff-ux-upgrade/tasks.md
Ahmed Darrazi 25e0dcc353 feat: refine onboarding draft flow and RBAC diff UX
2026-03-14 21:08:32 +01:00

14 KiB
Raw Blame History

Tasks: RBAC Role Definition Diff UX Upgrade

Input: Design documents from /specs/142-rbac-role-definition-diff-ux-upgrade/
Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/rbac-finding-diff-view.openapi.yaml, quickstart.md

Tests: Tests are REQUIRED for this feature because it changes runtime presentation behavior on the Findings detail screen and adds a new RBAC-specific shaping adapter. Operations: No new OperationRun, queued workflow, remote call, or audit-log mutation flow is introduced. RBAC: Existing workspace and tenant authorization remain unchanged. The RBAC diff consumer must render only already-authorized finding evidence and must not add any new scope behavior. Filament UI: This feature modifies an existing Findings View infolist entry only. No new header, row, bulk, or destructive actions are introduced. Badges: Diff-state badges must continue to use centralized semantics through BadgeCatalog and the shared Spec 141 diff foundation.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare the feature-specific test anchors and implementation file stubs for RBAC consumer adoption.

  • T001 Create the RBAC builder test scaffold in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php
  • T002 [P] Expand the RBAC finding detail test fixture coverage scaffold in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the RBAC-specific shaping adapter that every user story depends on.

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

  • T003 Create the RBAC consumer adapter skeleton in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Diff/RbacRoleDefinitionDiffBuilder.php
  • T004 [P] Add shared RBAC payload fixture helpers for the new adapter in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php

Checkpoint: RBAC-specific shaping infrastructure exists and user-story work can begin.

Phase 3: User Story 1 - Spot Real RBAC Changes Fast (Priority: P1) 🎯 MVP

Goal: Make changed RBAC rows immediately obvious, keep unchanged rows quieter, and align the summary badges with the detailed rows.

Independent Test: Open a representative RBAC finding detail page and verify that changed, unchanged, added, and removed rows are visually distinct, summary counts match the rendered rows, and unchanged context no longer dominates the screen.

Tests for User Story 1

  • T005 [P] [US1] Add row-state, summary-count, and deterministic-order coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php
  • T006 [P] [US1] Extend changed-versus-unchanged rendering assertions in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php
  • T007 [P] [US1] Extend shared changed and unchanged row partial coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Support/Diff/SharedDiffRowPartialTest.php
  • T008 [P] [US1] Extend summary-badge coherence coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Support/Diff/SharedDiffSummaryPartialTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php

Implementation for User Story 1

  • T009 [US1] Implement baseline/current normalization, field-label mapping, and stable field ordering in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Diff/RbacRoleDefinitionDiffBuilder.php
  • T010 [US1] Refactor the RBAC infolist entry to render shared summary badges and shared row partials in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/rbac-role-definition-diff.blade.php
  • T011 [US1] Tighten changed-row emphasis and unchanged-row de-emphasis in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/partials/diff/row-changed.blade.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/partials/diff/row-unchanged.blade.php

Checkpoint: The RBAC finding detail screen makes material changes obvious and summary-to-detail coherence is in place.

Phase 4: User Story 2 - Understand Permission List Differences (Priority: P2)

Goal: Render Allowed Actions and similar RBAC list fields as meaningful add/remove diffs instead of broad text blobs.

Independent Test: Open an RBAC finding whose Allowed Actions changed and verify that added, removed, and optionally unchanged actions are readable as inline list chips without raw side-by-side blob comparison.

Tests for User Story 2

  • T012 [P] [US2] Add Allowed Actions added, removed, and unchanged rendering assertions in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php
  • T013 [P] [US2] Extend RBAC-style inline list partial coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Support/Diff/SharedInlineListDiffPartialTest.php
  • T014 [P] [US2] Add explicit RBAC value-formatting expectations for null, boolean, scalar, and empty-list cases in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/ValueStringifierTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php

Implementation for User Story 2

  • T015 [US2] Mark Allowed Actions and approved simple RBAC list fields for inline list rendering in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Diff/RbacRoleDefinitionDiffBuilder.php
  • T016 [US2] Route RBAC list-like rows through the shared inline diff partial in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/rbac-role-definition-diff.blade.php

Checkpoint: Allowed Actions renders as an inline add/remove diff and permission review is materially easier.

Phase 5: User Story 3 - Reuse the Shared Diff Language Safely (Priority: P3)

Goal: Validate RBAC as the first consumer of Spec 141 while keeping no-change states safe and unrelated diff consumers untouched.

Independent Test: Render sparse and no-change RBAC findings and verify stable empty-state messaging, explicit one-sided semantics, and no regressions in the shared adoption guidance.

Tests for User Story 3

  • T017 [P] [US3] Add no-change, sparse-payload, and one-sided row assertions in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php
  • T018 [P] [US3] Add empty-input and missing-metadata fallback coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php

Implementation for User Story 3

  • T019 [US3] Finalize added-only, removed-only, and no-data summary behavior in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Diff/RbacRoleDefinitionDiffBuilder.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/rbac-role-definition-diff.blade.php
  • T020 [US3] Update shared consumer guidance to document RBAC as the first adopter, its list-field conventions, the no-toggle first-pass decision, and any remaining consumer-local rendering choices in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/docs/ui/shared-diff-presentation-foundation.md

Checkpoint: RBAC is a documented first consumer of the shared diff foundation and renders safe no-change and sparse states.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Run focused verification, formatting, and quickstart validation across the completed feature.

  • T021 [P] Run the focused RBAC diff test pack covering /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/ValueStringifierTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Support/Diff/SharedDiffSummaryPartialTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Support/Diff/SharedDiffRowPartialTest.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Support/Diff/SharedInlineListDiffPartialTest.php
  • T022 [P] Run formatting for changes in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Diff/RbacRoleDefinitionDiffBuilder.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/rbac-role-definition-diff.blade.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/partials/diff/row-changed.blade.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/partials/diff/row-unchanged.blade.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/Support/Diff/ValueStringifierTest.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Filament/FindingViewRbacEvidenceTest.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/docs/ui/shared-diff-presentation-foundation.md with vendor/bin/sail bin pint --dirty --format agent
  • T023 [P] Validate the implementation against /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/142-rbac-role-definition-diff-ux-upgrade/quickstart.md and confirm /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/assignments-diff.blade.php, /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/scope-tags-diff.blade.php, and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/infolists/entries/normalized-diff.blade.php remain outside scope

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; can start immediately.
  • Foundational (Phase 2): Depends on Setup completion; blocks all user stories.
  • User Story 1 (Phase 3): Depends on Foundational completion and is the MVP slice.
  • User Story 2 (Phase 4): Depends on User Story 1 because list rendering builds on the adopted shared row and summary flow.
  • User Story 3 (Phase 5): Depends on User Stories 1 and 2 because fallback behavior and guidance should reflect the final consumer behavior.
  • Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

  • User Story 1 (P1): No dependency on other stories after Foundational.
  • User Story 2 (P2): Builds on the RBAC consumer and shared partial adoption completed in US1.
  • User Story 3 (P3): Builds on the consumer behavior completed in US1 and US2.

Within Each User Story

  • Tests should be written or updated first and observed failing before implementation is finalized.
  • Builder logic should be completed before final Blade rendering changes.
  • Consumer documentation should follow the implemented behavior, not precede it.

Parallel Opportunities

  • T002 can run in parallel with T001.
  • T004 can run in parallel with T003 once the file exists.
  • T005, T006, T007, and T008 can run in parallel inside US1.
  • T012, T013, and T014 can run in parallel inside US2.
  • T017 and T018 can run in parallel inside US3.
  • T021, T022, and T023 can run in parallel in the polish phase.

Parallel Example: User Story 1

# Launch the US1 test updates together:
Task: "Add row-state, summary-count, and deterministic-order coverage in tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php"
Task: "Extend changed-versus-unchanged rendering assertions in tests/Feature/Filament/FindingViewRbacEvidenceTest.php"
Task: "Extend shared changed and unchanged row partial coverage in tests/Feature/Support/Diff/SharedDiffRowPartialTest.php"
Task: "Extend summary-badge coherence coverage in tests/Feature/Support/Diff/SharedDiffSummaryPartialTest.php and tests/Feature/Filament/FindingViewRbacEvidenceTest.php"

Parallel Example: User Story 2

# Launch the US2 verification work together:
Task: "Add Allowed Actions added, removed, and unchanged rendering assertions in tests/Feature/Filament/FindingViewRbacEvidenceTest.php"
Task: "Extend RBAC-style inline list partial coverage in tests/Feature/Support/Diff/SharedInlineListDiffPartialTest.php"
Task: "Add explicit RBAC value-formatting expectations for null, boolean, scalar, and empty-list cases in tests/Unit/Support/Diff/ValueStringifierTest.php and tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.php"

Parallel Example: User Story 3

# Launch the US3 fallback-safety work together:
Task: "Add no-change, sparse-payload, and one-sided row assertions in tests/Feature/Filament/FindingViewRbacEvidenceTest.php"
Task: "Add empty-input and missing-metadata fallback coverage in tests/Unit/Support/Diff/RbacRoleDefinitionDiffBuilderTest.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 the RBAC finding detail screen independently before moving on.

Incremental Delivery

  1. Deliver US1 to establish RBAC as a working consumer of the shared diff foundation.
  2. Deliver US2 to make permission-list diffs meaningfully readable.
  3. Deliver US3 to harden empty and sparse states and document RBAC adoption boundaries.

Parallel Team Strategy

  1. One engineer can own the builder and unit tests while another extends the feature and shared partial tests.
  2. After US1 lands, one engineer can focus on RBAC list-field shaping while another validates shared inline list behavior.
  3. Finish with focused Sail tests, Pint, and quickstart validation.