# Implementation Plan: TenantPilot v1

**Branch**: `tenantpilot-v1`  
**Date**: 2025-12-12  
**Spec Source**: `.specify/spec.md` (scope/restore matrix unchanged)

## Summary
TenantPilot v1 already delivers tenant-scoped Intune inventory, immutable backups, version history with diffs, defensive restore flows, tenant setup/permissions health, settings normalization/display, and Highlander enforcement. Remaining priority work is the delegated Intune RBAC onboarding wizard. All Graph calls stay behind the abstraction with audit logging; snapshots remain JSONB with safety gates for high-risk types (preview-only).

## Status Snapshot (tasks.md is source of truth)
- **Done**: US1 inventory, US2 backups, US3 versions/diffs, US4 restore preview/exec, scope config, soft-deletes/housekeeping, Highlander single current tenant, tenant setup & verify (US6), permissions/health overview (US7), table ActionGroup UX, settings normalization/display (US1b), Dokploy/Sail runbooks.  
- **Next up**: US8 (formerly labeled “User Story 7” in spec) Intune RBAC onboarding wizard (delegated, synchronous Filament flow).

## Technical Baseline
- Laravel 12, Filament 4, PHP 8.4; Sail-first with PostgreSQL.  
- JSONB for policy/backup/version payloads; FK/time indexes, GIN where needed.  
- Graph abstraction with standardized error mapping/retries; no secrets in logs.  
- Audit trail across backup/restore/version/tenant/permission/wizard steps; tenant isolation enforced.  
- Restore matrix and supported types remain config-driven single sources of truth.  
- Safety: preview/dry-run, confirmation gates, warnings for high-risk types; no implicit tenants (Highlander).

## Completed Workstreams (no new action needed)
- **US1 Inventory (Phase 3)**: Filament policy listing with type/category/platform filters; tenant-scoped.  
- **US2 Backups (Phase 4)**: Backup sets/items in JSONB, immutable snapshots, audit logging, relation manager UX for attaching policies, soft-delete rules with restore-run guard.  
- **US3 Versions/Diffs (Phase 5)**: Version capture, timelines, human+JSON diffs, soft-deletes with audit.  
- **US4 Restore (Phase 6)**: Preview, selective execution, conflict warnings, per-type restore level (enabled vs preview-only), PowerShell decode/encode respected, audit of outcomes.  
- **US6 Tenant Setup & Highlander (Phases 8 & 12)**: Tenant CRUD/verify, INTUNE_TENANT_ID override, `is_current` unique enforcement, “Make current” action, block deactivated tenants.  
- **US7 Permissions/Health (Phase 9)**: Required permissions list, compare/check service, Verify action updates status and audit, permissions panel in Tenant detail.  
- **US1b Settings Display (Phase 13)**: PolicyNormalizer + SnapshotValidator, warnings for malformed/@odata mismatches, normalized settings and pretty JSON on policy/version detail, list badges, README section.  
- **Housekeeping/UX (Phases 10–12)**: Soft/force deletes for tenants/backups/versions/restore runs with guards; table actions in ActionGroup per UX guideline.  
- **Ops (Phase 7)**: Sail runbook and Dokploy staging→prod guidance captured.

## Next Up: US8 Intune RBAC Onboarding Wizard (delegated, synchronous)
- Entry: Tenant detail ActionGroup “Setup Intune RBAC”; gated to active tenants with `app_client_id`.  
- Flow: explain/preconditions (role/scope/group mode, least-privilege warning), delegated login, synchronous execution in Filament (no queue for grant), post-check via Verify + canary reads.
  - Canary reads (read-only): `GET /deviceManagement/deviceConfigurations?$top=1` and `GET /deviceManagement/deviceCompliancePolicies?$top=1` (and `GET /identity/conditionalAccess/policies?$top=1` only if CA is enabled for the tenant/scope).
- Execution steps (idempotent): resolve service principal; ensure/create security group; add SP member; create/update role assignment with chosen scope; log audit for start/login/group/member/assignment/verify.  
- Optional jobs/CLI limited to CHECK/REPORT only (no grant).  
- Tests: happy path, rerun idempotent, missing permissions error mapping, scope-limited warning.  
- Documentation: add wizard behavior, audit expectations, and least-privilege guidance once implemented.
- Operational note: After admin-consent or RBAC changes, force a fresh token acquisition (e.g., clear app token cache) before re-trying sync/backup/restore; Verify should run with a non-stale token.
- Note: This is **Intune RBAC** for the **Enterprise App (service principal)**. No “App roles” need to be added in the App Registration; Graph API permissions + Intune role assignment are separate concerns.

## Testing & Quality Gates
- Continue using targeted Pest runs per change set; add/extend tests for US8 accordingly.  
- Run Pint on touched files before finalizing.  
- Maintain tenant isolation, audit logging, and restore safety gates; validate @odata.type and malformed snapshots prior to restore execution.
- Safety gate: `@odata.type` mismatches MUST block restore execution (preview may still show details + warnings), to prevent applying payloads to the wrong policy type/platform.

## Coordination
- Update `.specify/tasks.md` to reflect progress on remaining US8 tasks; no new entities or scope changes introduced here.  
- Stage validation required before production for any migration or restore-impacting change.  
- Keep Graph integration behind abstraction; no secrets in logs; follow existing UX patterns (ActionGroup, warnings for risky ops).