TenantAtlas/.specify/memory/constitution.md

TenantPilot Constitution

Core Principles

I. Safety-First Operations

Every destructive or high-impact action involving Intune configurations MUST implement safety mechanisms:

• Explicit confirmation UI for restore, rollback, and destructive operations
• Dry-run/preview modes where technically feasible, showing clear change summaries before execution
• Validation gates detecting conflicts, incompatible states, or invalid inputs
• Audit log entries for all critical operations (backup creation, restore execution, policy rollback)

Rationale: Intune configurations are critical production assets. A single misconfigured policy can affect thousands of devices. Safety gates prevent operational accidents and provide recovery visibility.

II. Immutable Versioning

Policy versions MUST be stored as immutable snapshots:

• Full payload capture in JSONB with metadata (who, when, source tenant, policy type)
• No in-place modifications to version records after creation
• Queryable history by policy, time range, and actor
• Diff capabilities between any two versions (human-readable summary + structured JSON where feasible)

Rationale: Immutable versions provide reliable rollback targets, accurate audit trails, and trustworthy diff outputs. Mutable history undermines auditability and introduces rollback risks.

III. Defensive Restore

Restore operations MUST be defensive and transparent:

• Preview/dry-run mode showing what changes will be applied before execution
• Selective restore allowing granular control over which items to restore
• Conflict detection flagging existing resources that may be overwritten or incompatible
• Pre-execution summary clearly communicating scope, risks, and affected resources
• Explicit confirmation required before executing any restore

Rationale: Restore operations can overwrite production configurations. Defensive workflows reduce risk of unintended changes and provide administrators with informed control.

IV. Auditability

All critical operations MUST produce comprehensive audit logs:

• Scope: backup creation, restore execution/attempts, policy rollback, policy version creation
• Content: actor, timestamp, operation type, affected resources, outcome (success/failure/partial)
• Tenant-scoped: logs MUST be queryable per tenant for multi-tenant future support
• RBAC-respecting: log access follows same permission model as operational access
• High-level Graph logging: log Graph API calls without exposing secrets or sensitive payloads

Rationale: Audit trails enable compliance verification, incident investigation, and operational transparency. They are non-negotiable for enterprise configuration management.

V. Tenant-Aware Architecture

Data models and business logic MUST be tenant-scoped from day one:

• Tenant entity present in schema even if v1 deploys single-tenant
• Foreign key relationships reference tenant_id where applicable
• Service layer logic accepts tenant context explicitly
• Isolation enforcement ensures no cross-tenant data leakage in queries or operations

Rationale: TenantPilot v1 is single-tenant per deployment, but the architecture must support multi-tenant evolution. Retrofitting tenant isolation later is expensive and error-prone.

VI. Graph Abstraction

Microsoft Graph integration MUST be isolated behind a dedicated abstraction layer:

• Domain services depend on GraphClient interface, not raw Graph SDK
• Responsibilities: auth token handling, rate-limit-friendly batching, standardized error mapping
• No direct Graph calls in controllers, Filament resources, or domain logic
• Testability: Graph layer must be mockable for integration tests

Rationale: Graph API complexity (auth, rate limits, versioning, error handling) should not bleed into domain logic. Abstraction enables cleaner testing, easier SDK upgrades, and centralized rate limit management.

VII. Spec-Driven Development

All features MUST follow the Spec Kit workflow:

1. Read .specify/constitution.md (this document)
2. Create/update .specify/spec.md defining user stories, acceptance criteria, and requirements
3. Produce .specify/plan.md with technical design, structure decisions, and constitution check
4. Break down into .specify/tasks.md organized by independently testable user stories
5. Implement in small, reviewable PRs aligned with tasks

Non-negotiable constraints:

• Constitution check in plan.md MUST pass before implementation
• User stories in spec.md MUST be prioritized and independently testable
• Requirements changes during implementation MUST update spec/plan before continuing
• Tasks MUST be organized by user story to enable incremental delivery

Rationale: Spec Kit enforces thoughtful design, prevents scope drift, and maintains alignment between requirements, design, and implementation. It provides checkpoints for validation before costly implementation work.

Security & Permissions

• Least privilege: Graph scopes and app permissions MUST request only necessary access
• Role-based access control: Admin vs. read-only auditor roles (v1 baseline)
• No secrets in code: Use Laravel encrypted storage or environment-based secret management
• Tenant identifier validation: All Graph operations MUST validate tenant context
• Encrypted storage: Sensitive fields (tokens, credentials) MUST use Laravel encryption where stored

Technology Stack

Core Stack:

• Backend: Laravel (latest stable)
• Admin UI: Filament (v3+)
• Database: PostgreSQL (via Sail locally, managed service in production)
• Auth: Microsoft Identity (Entra ID/Azure AD integration)
• External API: Microsoft Graph (Intune endpoints)

Development Environment:

• Local: Laravel Sail (Docker-based, PostgreSQL container)
• Tooling: Drizzle for local PostgreSQL workflows (if configured)
• Testing: Pest (PHPUnit-based)

Deployment:

• Repository: Gitea (self-hosted)
• Deployment: Dokploy on VPS (container-based)
• Environments: Staging (mandatory validation gate) → Production

Constraints:

• PHP: PSR-12 conventions
• Migrations: Reversible, validated on Staging before Production
• JSONB storage: Use for raw Graph payloads, policy snapshots, backup items
• Indexing: GIN indexes on JSONB fields requiring search/filter

Governance

This constitution supersedes all other development practices and guidelines. It defines the non-negotiable principles for TenantPilot development.

Amendment Process:

• Amendments require documentation in this file with version bump rationale
• Version follows semantic versioning:
  • MAJOR: Backward-incompatible governance changes (principle removal/redefinition)
  • MINOR: New principles added or materially expanded guidance
  • PATCH: Clarifications, wording improvements, non-semantic refinements
• Constitution changes MUST propagate to affected templates and guidance files
• All templates in .specify/templates/ MUST align with active principles

Compliance Enforcement:

• All specs MUST include a "Constitution Check" section in plan.md
• All PRs MUST verify compliance with relevant principles
• Violations MUST be justified in plan.md Complexity Tracking section
• Runtime development guidance lives in Agents.md, which MUST align with this constitution

Ratification: This constitution was established to formalize TenantPilot's architectural and operational principles based on v1 specification requirements and the Spec Kit workflow.

Version: 1.0.0 | Ratified: 2025-12-10 | Last Amended: 2025-12-10