From d195e8c3a92611f554f9fd7930a3ed6eef818c4f Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Wed, 5 Aug 2026 02:12:28 +0000 Subject: [PATCH] docs(P03): complete matrix + review integration phase ---ci--- project: atelier phase: 3 milestone: v0.2 status: complete requirements: covered: [ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-59] partial: [] ---/ci--- --- .ciagent/CHECKPOINT.json | 10 ++++----- MANIFEST.md | 10 ++++++--- matrix/domain-coverage.md | 28 ++++++++++++++++-------- matrix/principles-matrix.md | 38 ++++++++++++++++++++++++++++++++- review/agent-checklist.md | 22 +++++++++++++++++++ review/anti-patterns.md | 36 ++++++++++++++++++++++++++++++- review/peer-review-checklist.md | 20 ++++++++++++++++- 7 files changed, 143 insertions(+), 21 deletions(-) diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json index ece2f31..64d7ebb 100644 --- a/.ciagent/CHECKPOINT.json +++ b/.ciagent/CHECKPOINT.json @@ -1,12 +1,10 @@ { - "phase": 2, - "stage": "complete", + "phase": 3, + "stage": "execute", "milestone": "v0.2", "phase_role": "execution", "project": "atelier", "attempts": 0, - "updated_at": "2026-08-05T02:15:00Z", - "milestone_complete": false, - "phase_tag": "v0.1.2", - "release_id": 464 + "updated_at": "2026-08-05T02:20:00Z", + "milestone_complete": false } \ No newline at end of file diff --git a/MANIFEST.md b/MANIFEST.md index 2702aac..0d6c919 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -34,11 +34,15 @@ | Documentation | ✓ | doc-templates | | Concurrency | ✓ | patterns | | DevOps | ✓ | ci-cd, environments | +| Infrastructure as Code | ✓ | terraform, opentofu, state, modules | +| Kubernetes | ✓ | workloads, networking, storage, rbac, helm, kustomize | ## Cross-Cutting | Document | Purpose | |-----------------------------------|----------------------------------| -| `matrix/principles-matrix.md` | Maps domain → core principles | -| `review/agent-checklist.md` | Pre-completion agent checklist | -| `review/anti-patterns.md` | Catalog of violations | \ No newline at end of file +| `matrix/principles-matrix.md` | Maps domain → core principles (13 domains, 130 P-rules post-v0.2) | +| `matrix/domain-coverage.md` | Maps core → domains; per-domain coverage | +| `review/agent-checklist.md` | Pre-completion agent checklist (incl. IaC + k8s triggers) | +| `review/peer-review-checklist.md` | Human peer-review checklist (incl. IaC + k8s sections) | +| `review/anti-patterns.md` | Catalog of violations (incl. IaC + k8s + chaos anti-patterns) | \ No newline at end of file diff --git a/matrix/domain-coverage.md b/matrix/domain-coverage.md index 6388c36..42e399e 100644 --- a/matrix/domain-coverage.md +++ b/matrix/domain-coverage.md @@ -6,14 +6,14 @@ | Core Principle | Domains that derive from it | Count | |----------------|---------------------------|-------| -| C1 Correctness | All 11 (security, data, api, testing, performance, observability, errors, uiux, documentation, concurrency, devops) | Universal | -| C2 Clarity | uiux, api, data, testing, observability, errors, documentation, devops | 8 | -| C3 Simplicity | security, data, testing, performance, documentation, concurrency, devops | 7 | -| C4 Locality | testing, concurrency | 2 | -| C5 Reversibility | api, data, uiux, concurrency, devops | 5 | -| C6 Composability | api, security, observability, errors, documentation, concurrency | 6 | -| C7 Observability | api, data, testing, performance, observability, errors, devops | 7 | -| C8 Economy | security, testing, performance, observability, concurrency | 5 | +| C1 Correctness | All 13 (v0.1: 11; v0.2: infrastructure-as-code, kubernetes) | Universal | +| C2 Clarity | v0.1: uiux, api, data, testing, observability, errors, documentation, devops; v0.2: infrastructure-as-code, kubernetes | 10 | +| C3 Simplicity | v0.1: security, data, testing, performance, documentation, concurrency, devops | 7 | +| C4 Locality | v0.1: testing, concurrency; v0.2: infrastructure-as-code, kubernetes | 4 | +| C5 Reversibility | v0.1: api, data, uiux, concurrency, devops; v0.2: infrastructure-as-code, kubernetes | 7 | +| C6 Composability | v0.1: api, security, observability, errors, documentation, concurrency; v0.2: infrastructure-as-code, kubernetes | 8 | +| C7 Observability | v0.1: api, data, testing, performance, observability, errors, devops; v0.2: infrastructure-as-code, kubernetes | 9 | +| C8 Economy | v0.1: security, testing, performance, observability, concurrency; v0.2: kubernetes | 6 | ## Interpretation @@ -37,10 +37,20 @@ | Documentation | C1, C2, C3, C5, C6 | Docs-as-code + living docs | | Concurrency | C1, C3, C4, C5, C6, C7, C8 | Broadest derivation; locality (C4) unique | | DevOps | C1, C2, C3, C5, C7 | Reproducibility + rollback | +| Infrastructure as Code | C1, C2, C3, C4, C5, C6, C7 | Declarative + state + composition; broadest derivation alongside Concurrency | +| Kubernetes | C1, C2, C4, C5, C6, C7, C8 | Declarative + reversibility + economy; broad derivation (7 C-rules) | + +## v0.2 Domain Coverage (per IDEATE-03 schema) + +| Domain | P-count | Derived-doc-count | Manifest-listed | Status | +|--------|---------|-------------------|-----------------|--------| +| Infrastructure as Code | 10 | 4 (terraform, opentofu, state, modules) | ✓ | complete | +| Kubernetes | 10 | 6 (workloads, networking, storage, rbac, helm, kustomize) | ✓ | complete | ## Gaps and Notes - No domain derives from only one C-rule. The minimum is 4 (UI/UX: C1, C2, C3, C5, C7 — actually 5). Every domain is multi-rooted. - **Concurrency** has the broadest derivation (7 C-rules) — it touches the most core concerns. - **UI/UX** and **API** are the most user-facing; they emphasize C2 (Clarity) heavily. -- **Security** is the only domain with explicit non-tradeable declarations; this promotes 8 of its rules to C1-equivalent per `core/conflict-resolution.md` §6. \ No newline at end of file +- **Security** is the only domain with explicit non-tradeable declarations; this promotes 8 of its rules to C1-equivalent per `core/conflict-resolution.md` §6. +- **v0.2 expansion:** C4 (Locality) grew from 2 to 4 domains (added infrastructure-as-code state locality, kubernetes namespace blast-radius). C6 (Composability) grew from 6 to 8. The two new domains are broad-derivation domains (7 C-rules each), consistent with Concurrency's breadth. \ No newline at end of file diff --git a/matrix/principles-matrix.md b/matrix/principles-matrix.md index 06ab214..41a4012 100644 --- a/matrix/principles-matrix.md +++ b/matrix/principles-matrix.md @@ -173,4 +173,40 @@ C5=Reversibility · C6=Composability · C7=Observability · C8=Economy | P7 Immutability | C1 | Correctness of deploys | | P8 Security at Every Layer | C1 | Correctness includes security | | P9 Documentation in Pipeline | C2 | Clarity of operations | -| P10 Failure as Expected | C1, C7 | Correctness; observability | \ No newline at end of file +| P10 Failure as Expected | C1, C7 | Correctness; observability | + +## Infrastructure as Code + +| IaC Principle | Core | Why | +|---------------------------|------|---------------------------------------| +| P1 Declarative Intent | C2, C3 | Clarity; simplicity of declaration | +| P2 Idempotence | C1 | Correctness of repeated apply | +| P3 State is Truth | C1, C7 | Correctness; observability of reality | +| P4 Plan Before Apply | C5 | Reversibility of changes | +| P5 Version Everything | C5 | Reversibility of reproduction | +| P6 Modules Compose | C6 | Composability of infrastructure | +| P7 Least Privilege Providers | C1 | Correctness via security | +| P8 Remote State with Locking | C1, C4 | Correctness; locality of state | +| P9 Drift is Recoverable | C5, C7 | Reversibility; observability of drift | +| P10 Secrets Never in Code | C1 | Correctness includes secret safety | + +## Kubernetes + +| K8s Principle | Core | Why | +|---------------------------|------|---------------------------------------| +| P1 Declarative Desired State | C1, C2 | Correctness; clarity of intent | +| P2 Pods are Mortal | C5 | Reversibility of workloads | +| P3 Labels Select | C2, C6 | Clarity; composability of selection | +| P4 Requests and Limits | C1, C8 | Correctness; economy of resources | +| P5 Probes Drive Health | C1, C7 | Correctness; observability of health | +| P6 Namespaces Bound Blast | C4 | Locality of blast radius | +| P7 RBAC by Intent | C1 | Correctness via security | +| P8 Storage is Explicit | C4, C5 | Locality; reversibility of data | +| P9 Config and Secrets Sep | C2 | Clarity of configuration | +| P10 Roll Forward, Roll Back | C5 | Reversibility of deploys | + +## Coverage Summary (post-v0.2) + +- 13 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes) +- 130 domain principles total (110 v0.1 + 20 v0.2) +- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans. \ No newline at end of file diff --git a/review/agent-checklist.md b/review/agent-checklist.md index 6055121..bd08d51 100644 --- a/review/agent-checklist.md +++ b/review/agent-checklist.md @@ -125,6 +125,28 @@ If the task touches a domain, run that domain's checklist: - [ ] Config is in code, not on the server - [ ] Environments are parity (dev = prod modulo data) +### If Infrastructure as Code (see `domains/infrastructure-as-code/`) +- [ ] Configuration is declarative, not scripted (P1) +- [ ] Provider versions are pinned, never `latest` (P5) +- [ ] State is remote with locking; never committed (P3, P8) +- [ ] `plan` is reviewed before every `apply` (P4) +- [ ] No secrets in HCL; secrets via providers/stores (P10) +- [ ] Modules are versioned; copy-paste replaced by module calls (P6) +- [ ] Drift is treated as an incident, not a shortcut (P9) +- [ ] Provider credentials scoped per environment, least privilege (P7) + +### If Kubernetes (see `domains/kubernetes/`) +- [ ] No bare pods; controllers used (P2) +- [ ] Resource requests set on every prod container (P4) +- [ ] Liveness/readiness/startup probes defined (P5) +- [ ] RBAC bound to ServiceAccounts by intent; no `cluster-admin` (P7) +- [ ] No `:latest` image tag in prod (P5 Version Everything) +- [ ] StatefulSet PVCs use `volumeClaimTemplates`; `emptyDir` only for scratch (P8) +- [ ] ConfigMaps and Secrets separate; secrets not in image (P9) +- [ ] Default-deny NetworkPolicy baseline (P6) +- [ ] Rollout history retained; rollback tested (P10) +- [ ] Namespaces used to bound blast radius; not `default` in prod (P6) + ## Final Gate - [ ] Have I read the relevant domain's first-principles? diff --git a/review/anti-patterns.md b/review/anti-patterns.md index e3b092f..de735af 100644 --- a/review/anti-patterns.md +++ b/review/anti-patterns.md @@ -121,6 +121,32 @@ When you see a pattern listed here, it is a defect. Cite the principle it violat | Rebuild per environment | P7 Immutability | Different artifacts | | Snowflake server | P1, P6 | Not reproducible | +### Infrastructure as Code +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Unpinned provider (`source` without `version`) | P5 Version Everything | Unversioned drift | +| `terraform apply` without a read `plan` | P4 Plan Before Apply | Unreviewed mutation | +| Local state in a shared environment | P8 Remote State with Locking | No lock = corruption | +| Hardcoded secret in HCL | P10 Secrets Never in Code | Committed secret | +| Copy-pasted block instead of a module | P6 Modules Compose | Bug duplicated | +| Manual change to a managed resource | P9 Drift is Recoverable | Unreconciled drift | +| Admin credentials in CI | P7 Least Privilege Providers | Overbroad grant | +| Committed `terraform.tfstate` | P3 State is Truth, P10 | Secret-bearing artifact in repo | + +### Kubernetes +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Bare pod (no controller) | P2 Pods are Mortal | No recovery/scale | +| No resource requests in prod | P4 Requests and Limits | BestEffort, first evicted | +| Liveness probe checks a dependency | P5 Probes Drive Health | Cascade restart | +| `cluster-admin` bound to a workload | P7 RBAC by Intent | Overbroad grant | +| `:latest` image tag in prod | P5 Version Everything | Unversioned drift | +| `emptyDir` for data that must persist | P8 Storage is Explicit | Data lost on pod death | +| Secrets baked into the image | P9 Config and Secrets Separate | No rotation without rebuild | +| `default` namespace in prod | P6 Namespaces Bound Blast Radius | No blast boundary | +| Shared PVC across StatefulSet replicas | P8 Storage is Explicit | Concurrent write corruption | +| `Delete` reclaim policy on prod storage | P8, P5 Reversibility | PVC delete = data delete | + ## Cross-Cutting Anti-Patterns | Anti-Pattern | Breaches | Why | @@ -129,4 +155,12 @@ When you see a pattern listed here, it is a defect. Cite the principle it violat | "It's just a prototype" | C5 (irreversible by default) | Prototypes go to prod | | Copy-paste code | C6 (no composition) | Bug duplicated | | God object | C3, C6 | One thing, many things | -| Leaky abstraction | C6, C2 | Hidden coupling | \ No newline at end of file +| Leaky abstraction | C6, C2 | Hidden coupling | + +## v0.2 Chaos Anti-Patterns (from IDEATE-13, IDEATE-14) + +| Anti-Pattern | Breaches | Why | +|--------------|----------|-----| +| Orphaned P-rule (a domain principle with no matrix row) | matrix completeness, C6 | Breaks the conflict-resolution arbiter; the rule has no core trace | +| Deployable example artifact (standalone `.tf`/`.yaml` under `examples/`) | PROJECT.md "no runtime code", D-025 | Violates the docs-only contract; examples must be `.md` with fenced code | +| Unlisted v0.2 doc (new doc not added to MANIFEST) | manifest rule | Not part of the framework by definition | \ No newline at end of file diff --git a/review/peer-review-checklist.md b/review/peer-review-checklist.md index 8a23bbe..807e1bd 100644 --- a/review/peer-review-checklist.md +++ b/review/peer-review-checklist.md @@ -59,7 +59,25 @@ A peer review is a second set of eyes on correctness, clarity, and completeness. ## Domain-Specific (if applicable) -Run the relevant domain section from `agent-checklist.md` (UI/UX, API, Security, Data, Testing, Performance, Observability, Errors, Concurrency, DevOps). The author ran it; the reviewer verifies. +Run the relevant domain section from `agent-checklist.md` (UI/UX, API, Security, Data, Testing, Performance, Observability, Errors, Concurrency, DevOps, Infrastructure as Code, Kubernetes). The author ran it; the reviewer verifies. + +### If Infrastructure as Code +- [ ] Are providers pinned and modules version-pinned? (no `latest`) +- [ ] Is state remote with locking, not committed? +- [ ] Is the `plan` diff reviewed, not just the config? +- [ ] Are secrets via providers/stores, not in HCL? +- [ ] Are credentials scoped per environment? +- [ ] Is drift being treated as an incident? + +### If Kubernetes +- [ ] Are controllers used, not bare pods? +- [ ] Are resource requests set on every prod container? +- [ ] Are probes defined and checking the workload, not its dependencies? +- [ ] Is RBAC least-privilege, bound to ServiceAccounts by intent? +- [ ] Are image tags pinned, not `:latest`? +- [ ] Is persistent storage explicit (PVC + reclaim policy decided)? +- [ ] Are ConfigMaps and Secrets separate? +- [ ] Is the rollback path tested, not assumed? ## Review Etiquette