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.
This commit is contained in:
Ahmed Darrazi
parent
78467a76ac
commit
f9b6856f2c
@ -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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user