From f9b6856f2c04c1ee4033a60b46b80118a815836d Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Wed, 7 Jan 2026 14:41:34 +0100 Subject: [PATCH 1/2] docs: amend constitution to v1.1.0 Add suite design rules as core principles and sync SpecKit templates (plan/spec/tasks) to match new gates. --- .specify/memory/constitution.md | 81 ++++++++++++++++++++++------ .specify/templates/plan-template.md | 10 +++- .specify/templates/spec-template.md | 3 ++ .specify/templates/tasks-template.md | 2 +- 4 files changed, 78 insertions(+), 18 deletions(-) diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 8670192..3df8c1e 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,24 +1,63 @@ + + # 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/-/` 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 diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 6a8bfc6..0c59577 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -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 diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index c67d914..84c1682 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -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. +