# Tasks: Intune RBAC Inventory & Backup v1 (127)

**Input**: Design documents from `specs/127-rbac-inventory-backup/` (spec.md, plan.md, research.md, data-model.md, contracts/)
**Prerequisites**: `specs/127-rbac-inventory-backup/plan.md` (required), `specs/127-rbac-inventory-backup/spec.md` (required for user stories)

**Tests**: REQUIRED (Pest) for all runtime behavior changes in this repo.
**Operations**: Reuse existing `OperationRun` flows for inventory sync and backup capture; do not add ad-hoc operation feedback or notification patterns.
**RBAC**: Preserve tenant/admin plane enforcement, deny-as-not-found 404 for non-members, 403 for in-scope members missing capability, and canonical capability registry usage only.
**Filament UI**: No new Filament resource/page is added; existing coverage, backup/version, and provider verification surfaces are extended only.

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Reconfirm the relevant existing architecture and validation surfaces before changing config-driven foundation behavior.

- [X] T001 Review existing foundation type registration in `config/tenantpilot.php`
- [X] T002 Review existing RBAC-related Graph contracts in `config/graph_contracts.php`
- [X] T003 [P] Review foundation inventory sync flow in `app/Services/Inventory/InventorySyncService.php`
- [X] T004 [P] Review foundation backup and version capture flow in `app/Services/Intune/FoundationSnapshotService.php`, `app/Services/Intune/BackupService.php`, and `app/Services/Intune/VersionService.php`
- [X] T005 [P] Review RBAC permission warning patterns in `app/Support/Verification/TenantPermissionCheckClusters.php`, `app/Support/Providers/ProviderReasonCodes.php`, and `app/Services/Graph/ScopeTagResolver.php`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Shared config and registry work that must exist before inventory, backup, or safety behavior can be implemented.

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

- [X] T006 Add `intuneRoleDefinition` and `intuneRoleAssignment` foundation metadata in `config/tenantpilot.php`
- [X] T007 Add inventory-grade RBAC Graph contract entries in `config/graph_contracts.php`
- [X] T008 Update RBAC contract helper coverage for the new inventory-grade keys in `app/Services/Graph/GraphContractRegistry.php`
- [X] T009 [P] Extend foundation metadata resolution for RBAC category and preview-only semantics in `app/Support/Inventory/InventoryPolicyTypeMeta.php`
- [X] T010 [P] Add or extend Graph contract sanitization coverage for RBAC foundation keys in `tests/Unit/GraphContractRegistryTest.php`
- [X] T011 [P] Add config registration coverage for RBAC foundations in `tests/Feature/Filament/InventoryCoverageTableTest.php` and `tests/Feature/RestoreUnknownPolicyTypeSafetyTest.php`

**Checkpoint**: Foundation type config, contract registry, and metadata resolution are ready; user stories can now proceed.

---

## Phase 3: User Story 1 - Capture Intune RBAC Inventory (Priority: P1) 🎯 MVP

**Goal**: Tenant inventory sync captures RBAC Role Definitions and Role Assignments as first-class foundation inventory items and reports them in coverage under RBAC.

**Independent Test**: Run tenant inventory sync with mocked RBAC responses and verify `InventoryItem` rows plus `coverage.foundation_types` entries for both RBAC types without needing backup capture.

### Tests for User Story 1

- [X] T012 [P] [US1] Add inventory sync coverage for RBAC foundation upserts in `tests/Feature/Inventory/InventorySyncServiceTest.php`
- [X] T013 [P] [US1] Add coverage page assertions for RBAC foundation rows and category labeling in `tests/Feature/Filament/InventoryCoverageTableTest.php`
- [X] T014 [P] [US1] Add foundation snapshot paging and payload-shape coverage for RBAC types in `tests/Unit/FoundationSnapshotServiceTest.php`

### Implementation for User Story 1

- [X] T015 [US1] Extend foundation inventory sync persistence for `intuneRoleDefinition` and `intuneRoleAssignment` in `app/Services/Inventory/InventorySyncService.php`
- [X] T016 [US1] Add RBAC-specific sanitized metadata shaping for observed inventory rows in `app/Services/Inventory/InventorySyncService.php`
- [X] T017 [US1] Extend foundation snapshot fetch behavior for full-fidelity RBAC capture in `app/Services/Intune/FoundationSnapshotService.php`
- [X] T018 [US1] Surface RBAC foundation metadata in inventory coverage presentation using `app/Support/Inventory/InventoryPolicyTypeMeta.php` and `app/Filament/Pages/InventoryCoverage.php`

**Checkpoint**: User Story 1 is complete when sync creates RBAC inventory rows and coverage shows both RBAC foundation types under the RBAC category.

---

## Phase 4: User Story 2 - Review Immutable RBAC History (Priority: P1)

**Goal**: Backup set detail and policy version history/detail surfaces show immutable RBAC snapshots with readable normalized content for both role definitions and assignments.

**Independent Test**: Create a backup set with foundations enabled and verify RBAC backup items and policy version entries exist with full payloads and readable normalized content in backup set detail and policy version detail surfaces.

### Tests for User Story 2

- [X] T019 [P] [US2] Add backup foundation capture coverage for RBAC role definitions and assignments in `tests/Feature/FoundationBackupTest.php`
- [X] T020 [P] [US2] Add Role Definition normalizer coverage for built-in and custom roles in `tests/Unit/IntuneRoleDefinitionNormalizerTest.php`
- [X] T021 [P] [US2] Add Role Assignment normalizer coverage for role, principals, scopes, and fallback identifiers in `tests/Unit/IntuneRoleAssignmentNormalizerTest.php`
- [X] T022 [P] [US2] Add version capture and reuse coverage for RBAC foundations in `tests/Feature/BackupServiceVersionReuseTest.php` and `tests/Feature/VersionCaptureMetadataOnlyTest.php`
- [X] T023 [P] [US2] Add backup set and policy version surface assertions for readable RBAC history in `tests/Feature/Rbac/BackupItemsRelationManagerSemanticsTest.php` and `tests/Feature/Filament/PolicyVersionTest.php`

### Implementation for User Story 2

- [X] T024 [US2] Capture RBAC foundation backup items and aligned version history entries through `app/Services/Intune/BackupService.php` and `app/Services/Intune/VersionService.php`
- [X] T025 [P] [US2] Implement `IntuneRoleDefinitionNormalizer` in `app/Services/Intune/IntuneRoleDefinitionNormalizer.php`
- [X] T026 [P] [US2] Implement `IntuneRoleAssignmentNormalizer` in `app/Services/Intune/IntuneRoleAssignmentNormalizer.php`
- [X] T027 [US2] Register RBAC normalizers in `app/Providers/AppServiceProvider.php`
- [X] T028 [US2] Extend normalized backup set and policy version rendering for RBAC foundation items in `app/Services/Intune/PolicyNormalizer.php`, `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`, and `app/Filament/Resources/PolicyVersionResource.php`

**Checkpoint**: User Story 2 is complete when RBAC backup items and policy version history entries are created and render readable, immutable snapshot content for audit review.

---

## Phase 5: User Story 3 - Preserve Safe Read-Only Governance Posture (Priority: P2)

**Goal**: RBAC remains clearly preview-only for restore, permission gaps are surfaced gracefully, and tenant/workspace isolation remains enforced for RBAC coverage and history surfaces.

**Independent Test**: Verify restore-adjacent surfaces mark both RBAC types as preview-only, missing `DeviceManagementRBAC.Read.All` yields a clear warning or reason, and unauthorized access remains 404 or 403 as appropriate.

### Tests for User Story 3

- [X] T029 [P] [US3] Add preview-only restore guard coverage for RBAC foundation types in `tests/Feature/RestoreUnknownPolicyTypeSafetyTest.php` and `tests/Feature/Filament/RestoreExecutionTest.php`
- [X] T030 [P] [US3] Add verification or permission-warning coverage for missing `DeviceManagementRBAC.Read.All` in `tests/Feature/Verification/IntuneRbacPermissionCoverageTest.php`
- [X] T031 [P] [US3] Add tenant/workspace isolation coverage for RBAC backup or coverage visibility in `tests/Feature/WorkspaceIsolation/TenantOwnedWorkspaceInvariantTest.php`, `tests/Feature/Filament/InventoryCoverageTableTest.php`, and `tests/Feature/Filament/PolicyVersionTest.php`
- [X] T032 [P] [US3] Add badge or restore-mode mapping coverage for preview-only RBAC foundations in `tests/Unit/Badges/PolicyBadgesTest.php`

### Implementation for User Story 3

- [X] T033 [US3] Preserve preview-only RBAC restore semantics in `app/Services/Intune/RestoreRiskChecker.php` and `app/Services/Intune/RestoreService.php`
- [X] T034 [US3] Add graceful RBAC permission-warning clustering and next-step messaging in `app/Support/Verification/TenantPermissionCheckClusters.php`
- [X] T035 [US3] Extend provider reason mapping for RBAC read gaps where needed in `app/Support/Providers/ProviderReasonCodes.php` and related verification helpers under `app/Support/Verification/`
- [X] T036 [US3] Ensure backup set, policy version, coverage, and verification surfaces present RBAC support state without bypassing existing tenant/admin authorization in `app/Filament/Pages/InventoryCoverage.php`, `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, and related policies or helpers already backing those surfaces

**Checkpoint**: User Story 3 is complete when RBAC is clearly read-only and safe, permission gaps are operator-readable, and no scope leakage is introduced.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final verification, formatting, and cross-story regression protection.

- [X] T037 [P] Add or update targeted contract documentation examples in `specs/127-rbac-inventory-backup/contracts/rbac-foundation.openapi.yaml` and `specs/127-rbac-inventory-backup/contracts/foundation-rbac-snapshot.schema.json` if implementation shape changed
- [X] T038 [P] Add reused `OperationRun` notification and summary-count regression coverage for RBAC inventory and backup/version flows in `tests/Feature/Notifications/OperationRunNotificationTest.php` and `tests/Feature/OpsUx/OperationRunSummaryCountsIncrementTest.php`
- [X] T039 Run formatting for changed files via `specs/127-rbac-inventory-backup/quickstart.md`
- [X] T040 Run focused Pest verification from `specs/127-rbac-inventory-backup/quickstart.md`
- [ ] T041 Validate manual QA checklist from `specs/127-rbac-inventory-backup/quickstart.md`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies; start immediately.
- **Foundational (Phase 2)**: Depends on Setup; blocks all user stories.
- **User Story 1 (Phase 3)**: Depends on Foundational completion.
- **User Story 2 (Phase 4)**: Depends on Foundational completion and benefits from US1 because the same RBAC type metadata and contracts are already in place.
- **User Story 3 (Phase 5)**: Depends on Foundational completion and should run after US1/US2 touch the relevant coverage and backup surfaces.
- **Polish (Phase 6)**: Depends on all desired user stories being complete.

### User Story Dependencies

- **US1 (P1)**: First deliverable and MVP. No dependency on other user stories.
- **US2 (P1)**: Depends on the same shared config/contract work as US1, but can proceed once foundational work is done.
- **US3 (P2)**: Builds on the RBAC types being visible in coverage and backup flows, so it should follow US1 and US2.

### Within Each User Story

- Tests should be added before or alongside implementation and must fail before the feature code is considered complete.
- Config/registry changes precede service changes.
- Service changes precede Filament presentation adjustments.
- Story-specific implementation is complete only when its focused tests pass.

### Parallel Opportunities

- Setup review tasks marked `[P]` can be done in parallel.
- In Phase 2, metadata and test tasks `T009` to `T011` can run in parallel after the core config/contract additions begin.
- In US1, `T012` to `T014` can run in parallel, and `T017` can proceed in parallel with metadata work once contracts are defined.
- In US2, the two normalizer implementations `T025` and `T026` can run in parallel with their test files, and version capture coverage `T022` can proceed in parallel with surface assertions `T023`.
- In US3, warning, isolation, and badge tests `T029` to `T032` can run in parallel.

---

## Parallel Example: User Story 1

```bash
# Launch US1 test work in parallel:
T012 tests/Feature/Inventory/InventorySyncServiceTest.php
T013 tests/Feature/Filament/InventoryCoverageTableTest.php
T014 tests/Unit/FoundationSnapshotServiceTest.php

# Launch US1 implementation work in parallel after config/contracts are ready:
T016 app/Services/Inventory/InventorySyncService.php
T017 app/Services/Intune/FoundationSnapshotService.php
```

## Parallel Example: User Story 2

```bash
# Launch RBAC normalizer work in parallel:
T020 tests/Unit/IntuneRoleDefinitionNormalizerTest.php + T025 app/Services/Intune/IntuneRoleDefinitionNormalizer.php
T021 tests/Unit/IntuneRoleAssignmentNormalizerTest.php + T026 app/Services/Intune/IntuneRoleAssignmentNormalizer.php

# Launch version-history work in parallel:
T022 tests/Feature/BackupServiceVersionReuseTest.php
T023 tests/Feature/Filament/PolicyVersionTest.php
```

## Parallel Example: User Story 3

```bash
# Launch safety and permission tasks in parallel:
T030 tests/Feature/Verification/IntuneRbacPermissionCoverageTest.php
T031 tests/Feature/WorkspaceIsolation/TenantOwnedWorkspaceInvariantTest.php
T032 tests/Unit/Badges/PolicyBadgesTest.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 focused inventory sync and coverage behavior.

### Incremental Delivery

1. Ship US1 to establish RBAC inventory visibility.
2. Add US2 to make immutable RBAC history readable and auditable.
3. Add US3 to harden preview-only messaging, permission warnings, and scope safety.

### Suggested MVP Scope

- MVP = Phases 1 through 3, then run `vendor/bin/sail artisan test --compact tests/Feature/Inventory/InventorySyncServiceTest.php` and `vendor/bin/sail artisan test --compact tests/Feature/Filament/InventoryCoverageTableTest.php`.

---

## Format Validation

- Every task follows the checklist format `- [ ] T### [P?] [US?] Description with file path`.
- Setup, Foundational, and Polish phases intentionally omit story labels.
- User story phases use `[US1]`, `[US2]`, and `[US3]` labels.
- Parallel markers are applied only where tasks can proceed independently on different files or clearly separable work.
