chore/docs-constitution-v1.1.0 (#40)
changed constition Co-authored-by: Ahmed Darrazi <ahmeddarrazi@adsmac.local> Reviewed-on: #40
This commit is contained in:
parent
d63bce7b54
commit
3465076a04
@ -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
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Safety-First Restore
|
||||
- Any destructive action MUST support preview/dry-run, explicit confirmation, and a clear pre-execution summary.
|
||||
- High-risk policy types default to `preview-only` restore unless explicitly enabled by a feature spec + tests + checklist.
|
||||
- Restore must be defensive: validate inputs, detect conflicts, allow selective restore, and record outcomes per item.
|
||||
### Inventory-first, Snapshots-second
|
||||
- All modules MUST operate primarily on Inventory as “last observed” state.
|
||||
- Inventory is the source of truth for what TenantPilot last observed; Microsoft Intune remains the external truth.
|
||||
- Snapshots/Backups MUST be explicit actions (manual or scheduled) and MUST remain immutable.
|
||||
|
||||
### Auditability & Tenant Isolation
|
||||
- Every operation is tenant-scoped and MUST write an audit log entry (no secrets, no tokens).
|
||||
- Snapshots are immutable JSONB and MUST remain reproducible (who/when/what/source tenant).
|
||||
### Read/Write Separation by Default
|
||||
- Analysis, reporting, and monitoring features MUST be read-only by default.
|
||||
- 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`.
|
||||
- Contract assumptions are config-driven (`config/graph_contracts.php`); do not hardcode endpoints in feature code.
|
||||
- Unknown/missing policy types MUST fail safe (preview-only / no Graph calls) rather than calling `deviceManagement/{type}`.
|
||||
- Object types and endpoints MUST be modeled first in the contract registry (`config/graph_contracts.php`).
|
||||
- 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.
|
||||
- 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
|
||||
- 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.
|
||||
|
||||
## 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
|
||||
|
||||
@ -3,7 +3,7 @@ # Implementation Plan: [FEATURE]
|
||||
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
|
||||
**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
|
||||
|
||||
@ -31,7 +31,13 @@ ## Constitution Check
|
||||
|
||||
*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
|
||||
|
||||
|
||||
@ -77,6 +77,9 @@ ### Edge Cases
|
||||
|
||||
## 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.
|
||||
Fill them out with the right functional requirements.
|
||||
|
||||
@ -8,7 +8,7 @@ # Tasks: [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/
|
||||
|
||||
**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.
|
||||
|
||||
|
||||
72
PROJECT_SUMMARY.md
Normal file
72
PROJECT_SUMMARY.md
Normal 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.
|
||||
Loading…
Reference in New Issue
Block a user