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---
This commit is contained in:
Jon Chery
@@ -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
|
||||
}
|
||||
+7
-3
@@ -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 |
|
||||
| `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) |
|
||||
@@ -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.
|
||||
- **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.
|
||||
@@ -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 |
|
||||
| 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.
|
||||
@@ -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?
|
||||
|
||||
+35
-1
@@ -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 |
|
||||
| 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 |
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user