ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

chore/docs-constitution-v1.1.0 (#40)

Browse Source 
changed constition

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local>
Reviewed-on: #40
This commit is contained in:
ahmido 2026-01-07 13:43:21 +00:00
parent d63bce7b54
commit 3465076a04
5 changed files with 150 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
.specify/memory/constitution.md
View File

@ -1,24 +1,63 @@
<!--
Sync Impact Report
- Version change: 1.0.0 → 1.1.0
- Modified principles:
- Safety-First Restore → Read/Write Separation by Default
- Auditability & Tenant Isolation → Tenant Isolation is Non-negotiable (+ Least Privilege)
- Graph Abstraction & Contracts → Single Contract Path to Graph
- Added principles:
- Inventory-first, Snapshots-second
- Deterministic Capabilities
- Automation must be Idempotent & Observable
- Data Minimization & Safe Logging
- Templates requiring updates:
- ✅ .specify/templates/plan-template.md
- ✅ .specify/templates/tasks-template.md
- ✅ .specify/templates/spec-template.md
- Follow-up TODOs:
- TODO(DELETED_STATUS): Keep “deleted” reserved for Feature 900 / Policy Lifecycle.
-->
# TenantPilot Constitution # TenantPilot Constitution
## Core Principles ## Core Principles
### Safety-First Restore ### Inventory-first, Snapshots-second
- Any destructive action MUST support preview/dry-run, explicit confirmation, and a clear pre-execution summary. - All modules MUST operate primarily on Inventory as “last observed” state.
- High-risk policy types default to `preview-only` restore unless explicitly enabled by a feature spec + tests + checklist. - Inventory is the source of truth for what TenantPilot last observed; Microsoft Intune remains the external truth.
- Restore must be defensive: validate inputs, detect conflicts, allow selective restore, and record outcomes per item. - Snapshots/Backups MUST be explicit actions (manual or scheduled) and MUST remain immutable.
### Auditability & Tenant Isolation ### Read/Write Separation by Default
- Every operation is tenant-scoped and MUST write an audit log entry (no secrets, no tokens). - Analysis, reporting, and monitoring features MUST be read-only by default.
- Snapshots are immutable JSONB and MUST remain reproducible (who/when/what/source tenant). - Any write/change function (restore, remediation, promotion) MUST include preview/dry-run, explicit confirmation, audit logging, and tests.
- High-risk policy types default to `preview-only` restore unless explicitly enabled by a feature spec + tests.
### Graph Abstraction & Contracts ### Single Contract Path to Graph
- All Microsoft Graph calls MUST go through `GraphClientInterface`. - All Microsoft Graph calls MUST go through `GraphClientInterface`.
- Contract assumptions are config-driven (`config/graph_contracts.php`); do not hardcode endpoints in feature code. - Object types and endpoints MUST be modeled first in the contract registry (`config/graph_contracts.php`).
- Unknown/missing policy types MUST fail safe (preview-only / no Graph calls) rather than calling `deviceManagement/{type}`. - Feature code MUST NOT hardcode “quick endpoints” or bypass contracts.
- Unknown/missing policy types MUST fail safe (preview-only / no Graph calls) rather than guessing endpoints.
### Least Privilege ### Deterministic Capabilities
- Backup/restore/risk/support flags MUST be derived deterministically from config/contracts via a Capabilities Resolver.
- The resolver output MUST be programmatically testable (snapshot/golden tests) so config changes cannot silently break behavior.
### Tenant Isolation is Non-negotiable
- Every read/write MUST be tenant-scoped.
- Cross-tenant views (MSP/Platform) MUST be explicit, access-checked, and aggregation-based (no ID-based shortcuts).
- Prefer least-privilege roles/scopes; surface warnings when higher privileges are selected. - Prefer least-privilege roles/scopes; surface warnings when higher privileges are selected.
- Never store secrets in code/config; never log credentials or tokens.
### Automation must be Idempotent & Observable
- Scheduled/queued operations MUST use locks + idempotency (no duplicates).
- Long-running operations MUST create run records with status, counts, and stable error codes.
- Graph throttling and transient failures MUST be handled with backoff + jitter (e.g., 429/503).
- Failures MUST be visible and actionable (no silent best-effort).
### Data Minimization & Safe Logging
- Inventory MUST store only metadata + whitelisted `meta_jsonb`.
- Payload-heavy content belongs in immutable snapshots/backup storage, not Inventory.
- Logs MUST not contain secrets/tokens; monitoring MUST rely on run records + error codes (not log parsing).
### Spec-First Workflow ### Spec-First Workflow
- For any feature that changes runtime behavior, include or update `specs/<NNN>-<slug>/` with `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`. - For any feature that changes runtime behavior, include or update `specs/<NNN>-<slug>/` with `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
@ -29,7 +68,19 @@ ## Quality Gates
- Run `./vendor/bin/pint --dirty` before finalizing. - Run `./vendor/bin/pint --dirty` before finalizing.
## Governance ## Governance
- This constitution applies across the repo. Feature specs may add stricter constraints but not weaker ones.
- Restore semantics changes require: spec update, checklist update, and tests proving safety.
**Version**: 1.0.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-03 ### Scope & Compliance
- This constitution applies across the repo. Feature specs may add stricter constraints but not weaker ones.
- Restore semantics changes require: spec update, checklist update (if applicable), and tests proving safety.
### Amendment Procedure
- Propose changes as a PR that updates `.specify/memory/constitution.md`.
- The PR MUST include a short rationale and list of impacted templates/specs.
- Amendments MUST update **Last Amended** date.
### Versioning Policy (SemVer)
- **PATCH**: clarifications/typos/non-semantic refinements.
- **MINOR**: new principle/section or materially expanded guidance.
- **MAJOR**: removing/redefining principles in a backward-incompatible way.
**Version**: 1.1.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-07

10
.specify/templates/plan-template.md
View File

@ -3,7 +3,7 @@ # Implementation Plan: [FEATURE]
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md` **Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow. **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.
## Summary ## Summary
@ -31,7 +31,13 @@ ## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
[Gates determined based on constitution file] - Inventory-first: clarify what is “last observed” vs snapshots/backups
- Read/write separation: any writes require preview + confirmation + audit + tests
- Graph contract path: Graph calls only via `GraphClientInterface` + `config/graph_contracts.php`
- Deterministic capabilities: capability derivation is testable (snapshot/golden tests)
- Tenant isolation: all reads/writes tenant-scoped; cross-tenant views are explicit and access-checked
- Automation: queued/scheduled ops are locked, idempotent, observable; handle 429/503 with backoff+jitter
- Data minimization: Inventory stores metadata + whitelisted meta; logs contain no secrets/tokens
## Project Structure ## Project Structure

3
.specify/templates/spec-template.md
View File

@ -77,6 +77,9 @@ ### Edge Cases
## Requirements *(mandatory)* ## Requirements *(mandatory)*
**Constitution alignment (required):** If this feature introduces any Microsoft Graph calls or any write/change behavior,
the spec MUST describe contract registry updates, safety gates (preview/confirmation/audit), tenant isolation, and tests.
<!-- <!--
ACTION REQUIRED: The content in this section represents placeholders. ACTION REQUIRED: The content in this section represents placeholders.
Fill them out with the right functional requirements. Fill them out with the right functional requirements.

2
.specify/templates/tasks-template.md
View File

@ -8,7 +8,7 @@ # Tasks: [FEATURE NAME]
**Input**: Design documents from `/specs/[###-feature-name]/` **Input**: Design documents from `/specs/[###-feature-name]/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. **Tests**: For runtime behavior changes in this repo, tests are REQUIRED (Pest). Only docs-only changes may omit tests.
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

72
PROJECT_SUMMARY.md Normal file
View File

@ -0,0 +1,72 @@
**TenantPilot / TenantAtlas — Project Summary**
---
**Overview:**
- **Purpose:** Intune management tool (backup, restore, policy versioning, safe change management) built with Laravel + Filament.
- **Primary goals:** policy version control (diff/history/rollback), reliable backup & restore of Microsoft Intune configuration, admin-focused productivity features, auditability and least-privilege operations.
**Tech Stack & Key Libraries:**
- **Backend:** Laravel 12 (PHP 8.4)
- **Admin UI:** Filament v4
- **Realtime/UI:** Livewire v3
- **Testing:** Pest v4, PHPUnit
- **Local dev:** Laravel Sail (Docker)
- **Styling/tooling:** Tailwind v4, Vite
**Repository Layout (high level):**
- `app/` — application code (Services, Models, Filament resources, Livewire components)
- `config/` — runtime configuration (important: `tenantpilot.php`, `graph_contracts.php`)
- `specs/` — SpecKit feature specs (feature-by-feature directories, e.g. `011-restore-run-wizard`)
- `tests/` — Pest tests (Feature / Unit)
- `resources/`, `routes/`, `database/` — standard Laravel layout
**Core Features (implemented / status):**
- **Policy Backup & Versioning:** implemented — captures immutable snapshots (JSONB), tracks metadata (tenant, type, created_by, timestamps). (See `app/Services/Intune/*`, `database/migrations`.)
- **Restore Preview (dry-run) / Restore Wizard:** implemented — preview/dry-run mode that validates snapshots and highlights conflicts and risks. Feature tracked in `specs/011-restore-run-wizard` and Filament UI resources. Recent fixes improved OData @odata.type handling so derived Graph types validate correctly.
- **Assignments & Foundation Mappings:** implemented — mapping and selective restore of assignments, scope tags, and assignment filters (AssignmentRestoreService, FoundationMappingService).
- **Settings Catalog / Configuration Policies:** implemented — Settings Catalog and related configuration policy flows (`settingsCatalogPolicy`, `endpointSecurityPolicy`, `securityBaselinePolicy`) with subresource hydration for settings.
- **Windows Update Profiles:** implemented — Windows Update Rings + Feature/Quality/Driver update profiles (`windowsUpdateRing`, `windowsFeatureUpdateProfile`, etc.).
- **Endpoint Security + App Management:** implemented — Endpoint Security Intents/Policies, App Protection (MAM), Managed App Configurations, mobile app metadata capture.
- **Scripts & Autopilot:** implemented — device management scripts, proactive remediations, Autopilot profiles.
- **Conditional Access & High-risk types:** partially supported — `conditionalAccessPolicy` is backed up but marked `preview-only` for restore (see `tenantpilot.supported_policy_types`).
**Policy Type Restore/Backup Surface (from `config/tenantpilot.php`):**
- Restore `enabled` (full backup & restore): many configuration, compliance, endpoint security, scripts, Autopilot, MAM types (examples: `deviceConfiguration`, `groupPolicyConfiguration`, `settingsCatalogPolicy`, `deviceCompliancePolicy`, `appProtectionPolicy`, `endpointSecurityPolicy`, `deviceManagementScript`, etc.)
- Restore `preview-only` (backup available but live restore disabled / preview only): `conditionalAccessPolicy`, `deviceEnrollmentLimitConfiguration`, `deviceEnrollmentPlatformRestrictionsConfiguration`, `deviceEnrollmentNotificationConfiguration`, `enrollmentRestriction`, `securityBaselinePolicy`.
- Backup `metadata-only`: `mobileApp` (apps captured as metadata only)
**Graph Contract Registry & OData handling:**
- Centralized contract registry in `config/graph_contracts.php` defines endpoints, allowed selects/expands, `type_family` (accepted @odata.type values), subresources, and CRUD paths per policy type.
- OData validation is used during preview/restore (see `app/Support/Concerns/InteractsWithODataTypes.php`). Recent work broadened `type_family` entries to accept derived Graph @odata.type values for several policy types to avoid false `odata_mismatch` failures.
**Testing & Quality:**
- Unit and feature tests exist (Pest). Recent adjustments ensure unit tests run with the Laravel TestCase/IOC container (fixes issues like `Target class [config] does not exist`).
- Code formatting via Laravel Pint is used in CI and local flows.
**Specs & Process:**
- Uses Spec Kit convention: each feature in `specs/<NNN>-<slug>/` (spec.md, plan.md, tasks.md). Branching conventions documented in `Agents.md`/`.specify`.
- Default integration branch: `dev`. Feature branches are `feat/<NNN>-<slug>`.
**Recent Notable Work (context):**
- Fixed false `@odata.type mismatch` errors by updating `graph_contracts` `type_family` lists and adding unit tests (`tests/Unit/ODataTypeValidationTest.php`).
- Resolved merge conflicts between `feat/011-restore-run-wizard` and `dev` by merging `origin/dev` into a session branch and reconciling spec/test additions.
- Added `Agents.md` section for a “Solo + Copilot Workflow” and created a small `chore/solo-copilot-workflow` branch/PR for that documentation change.
**Where to look first (entry points):**
- Restore flows: `app/Services/Intune/RestoreService.php`, `app/Services/Intune/RestoreRiskChecker.php`, `app/Services/Intune/RestoreDiffGenerator.php`.
- Graph contracts: `config/graph_contracts.php` and `app/Services/Graph/GraphContractRegistry.php`.
- Policy type catalog and UX metadata: `config/tenantpilot.php` and `specs/*` for feature intentions.
- Filament UI: `app/Filament/Resources/*` (PolicyVersionResource, restore wizard pages).
**Short list of known limitations / next work items:**
- Convert more `preview-only` types to `enabled` where safe (requires implementation of restore flows and risk mitigation, e.g., Conditional Access, Enrollment subtypes, Security Baselines).
- Improve app restore for `mobileApp` beyond metadata-only (complex due to package/artifact handling).
- Add broader OData type families as Microsoft Graph evolves; consider automated discovery/updates to `graph_contracts`.
- Expand test coverage for edge-case restores (multi-tenant mapping, assignment conflicts, scope tag drift).
---
If you want, I can:
- open a PR that adds this file to `dev` (I can create a small `chore/` branch and push it), or
- expand any section above into a more detailed README or developer onboarding doc.