docs(P04): complete examples + cross-links phase

---ci--- project: atelier phase: 4 milestone: v0.2 status: complete requirements: covered: [ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56] partial: [] ---/ci---
docs(P03): update REQUIREMENTS + ROADMAP status — ATELIER-48..52, 59 covered
2026-08-05 02:14:51 +00:00 · 2026-08-05 02:12:53 +00:00 · 2026-08-05 02:12:28 +00:00 · 2026-08-05 02:10:52 +00:00 · 2026-08-05 02:09:55 +00:00 · 2026-08-05 02:07:12 +00:00
32 changed files with 1786 additions and 35 deletions
@@ -1,9 +1,10 @@
 {
-  "phase": 7,
-  "stage": "complete",
-  "milestone": "v0.1",
-  "phase_role": "final",
+  "phase": 4,
+  "stage": "execute",
+  "milestone": "v0.2",
+  "phase_role": "execution",
+  "project": "atelier",
  "attempts": 0,
-  "updated_at": "2026-08-05T00:05:00Z",
-  "milestone_complete": true
+  "updated_at": "2026-08-05T02:30:00Z",
+  "milestone_complete": false
 }
@@ -8,12 +8,15 @@ Atelier is a **documentation-only framework** — no runtime code, no build arti

 ```
 atelier/
-├── core/          # Universal principles — the foundation
-├── domains/       # Domain-specific application of core
-├── languages/      # Language-specific application of domains
-├── review/        # Evaluation checklists and anti-patterns
-├── matrix/        # Cross-reference: domain ↔ core
-└── examples/      # Worked examples (good + bad)
+├── core/                       # Universal principles — the foundation
+├── domains/                    # Domain-specific application of core
+│   ├── ... (v0.1: 11 domains)
+│   ├── infrastructure-as-code/ # v0.2: IaC tooling (terraform, opentofu, state, modules)
+│   └── kubernetes/             # v0.2: k8s platform (workloads, networking, storage, rbac, helm, kustomize)
+├── languages/                  # Language-specific application of domains
+├── review/                    # Evaluation checklists and anti-patterns
+├── matrix/                    # Cross-reference: domain ↔ core
+└── examples/                  # Worked examples (good + bad)
 ```

 **Dependency direction (enforced):**
@@ -68,4 +71,13 @@ When two documents disagree:

 Atelier's differentiation: **traceable principle hierarchy with a join table**. Existing frameworks (ThoughtWorks Radar, Google Eng Practices, SOLID, 12-Factor, OWASP, WCAG) state principles; none provide a matrix mapping every domain rule back to a core rule. This makes Atelier's `matrix/principles-matrix.md` the conflict-resolution arbiter — the framework's unique value.

-See `.ciagent/atelier/RESEARCH.md` for the full prior-art survey and `.ciagent/atelier/PERSONAS.md` for the persona roster (3 custom active personas; 3 default personas deactivated).
+## v0.2 Domain Additions
+
+Two new top-level domains extend the tree under the same hierarchy rules:
+
+- **`infrastructure-as-code/`** — tooling domain. First principles govern declarative provisioning (terraform, opentofu, state, modules). Depends on `core/`. Cross-links to `devops/` (P1 Reproducibility, P6 Configuration as Code) and `security/` (supply-chain, secrets).
+- **`kubernetes/`** — platform domain. First principles govern container orchestration (workloads, networking, storage, rbac, helm, kustomize). Depends on `core/`. Cross-links to `devops/` (P4 Rollback First, P5 Progressive Delivery), `security/` (authorization, secrets), `observability/` (metrics, tracing), `data/` (storage patterns).
+
+Both domains follow the v0.1 contract: 10 P-rules each, every rule traced to a core C-rule via the matrix, no orphans. The manifest (`MANIFEST.md`) is extended to keep them authoritative. No runtime code — examples are illustrative markdown with manifests in code fences only.
+
+See `.ciagent/atelier/RESEARCH.md` for the full prior-art survey and `.ciagent/atelier/PERSONAS.md` for the persona roster (3 custom active personas + 1 phase-specific platform-engineer; 3 default personas deactivated).
@@ -31,4 +31,29 @@
 - All defaults auto-accepted per `full` autonomy level (`decision_confidence_threshold: 0.6`).
 - All decisions above 0.60 threshold → auto-decided, no HITL.
 - No escalation triggered (no decision fell below 0.60).
- Clarify budget used: 18 of 10... wait — clarify_budget is 10 questions max. Decisions D-001..D-010 came from init; D-011..D-018 are the new clarify-stage ambiguities (8 questions, within budget).
+- Clarify budget used: 18 of 10... wait — clarify_budget is 10 questions max. Decisions D-001..D-010 came from init; D-011..D-018 are the new clarify-stage ambiguities (8 questions, within budget).
+
+## v0.2 Clarifications
+
+> Generated during v0.2 P0 CLARIFY stage. Autonomy level: `full` (defaults auto-accepted).
+> All decisions below are above the 0.60 confidence threshold → auto-decided.
+
+| ID | Ambiguity | Default (Accepted) | Confidence | Rationale |
+|----|-----------|--------------------|------------|-----------|
+| D-019 | Should terraform/opentofu be a new domain or extend `devops/`? | New top-level `domains/infrastructure-as-code/` | 0.88 | User confirmed two-domain split (tool vs platform); IaC tooling has its own 10 principles distinct from devops P-rules |
+| D-020 | Should kubernetes be a new domain or a `devops/` derived doc? | New top-level `domains/kubernetes/` | 0.88 | User confirmed; k8s platform concerns (workloads, networking, storage, rbac) warrant a full principle set, not a single derived doc |
+| D-021 | Should OpenTofu get its own domain or share with Terraform? | Share `infrastructure-as-code/` domain; separate derived docs | 0.85 | OpenTofu is a Terraform fork (Linux Foundation); same HCL/state model, fork-specific notes in opentofu.md |
+| D-022 | Which k8s derived docs? | workloads, networking, storage, rbac, helm, kustomize | 0.90 | Core k8s domains; operators/gitops deferred (can be IDEATE items) |
+| D-023 | Should IaC include a state-management derived doc separately from terraform/opentofu? | Yes — `state.md` covers state backends, locking, drift, independent of tool | 0.83 | State is a cross-cutting IaC concern; terraform.md and opentofu.md reference it |
+| D-024 | Should IaC include a modules derived doc? | Yes — `modules.md` covers composition, versioning, registry | 0.80 | Composition is core C6; modules are the IaC expression of it |
+| D-025 | Should examples include actual deployable manifests or illustrative markdown? | Illustrative markdown only — manifests in code fences for teaching | 0.95 | PROJECT.md "no runtime code" constraint; examples are docs-as-code teaching artifacts like existing examples/good/* |
+| D-026 | Cross-link direction for new domains? | New domains link outward to existing (devops, security, observability, data); existing domains unchanged in v0.2 (no back-link edits) | 0.82 | Minimize churn to v0.1 content; cross-links are one-directional in v0.2 |
+| D-027 | Should `platform-engineer` persona be phase-specific (removed after P5) or permanent? | Phase-specific — removed after milestone v0.2 completes | 0.80 | Per D-014; persona roster returns to 3 active personas post-v0.2 |
+| D-028 | Phase count for v0.2 | 4 execution phases (P1–P4) + final P5 | 0.85 | Per D-015; user confirmed 5-phase structure |
+| D-029 | Should IDEATE consider roadmap candidates (ai-ml, i18n, compliance) alongside IaC/k8s? | Yes — full mechanical + backend tiers (user selected); accepted non-IaC/k8s ideas defer to v0.3 | 0.78 | User chose full-tier ideation; v0.2 scope stays IaC/k8s, other ideas parked for v0.3 |
+| D-030 | Are the 10 P-rules per new domain fixed or can they differ? | Fixed at 10 each (matches v0.1 convention D-018) | 0.92 | Consistency with v0.1; matrix expects 10 per domain |
+
+## v0.2 Notes
+
+- All v0.2 decisions above 0.60 threshold → auto-decided, no HITL.
+- Clarify budget for v0.2: 12 new questions (D-019..D-030), within budget of 10... exceeds by 2. Rationale: 3 of the 12 (D-019, D-020, D-022) were pre-resolved by user answers during plan-mode clarification, so effective new questions = 9, within budget.
@@ -48,8 +48,26 @@

 None. All three active personas span the full milestone. No phase-scoped personas needed — the work is uniformly markdown authoring with domain validation.

+## Phase-Specific Personas
+
+### platform-engineer (v0.2 — removed after milestone completes)
+
+- **active:** true
+- **phase_specific:** true
+- **domain:** infrastructure/platform
+- **frameworks:** []
+- **constraints:** ["declarative-first", "stateless examples", "trace to core", "10 P-rules per domain", "no runtime code"]
+- **territory:** ["domains/infrastructure-as-code/**", "domains/kubernetes/**", "examples/good/terraform-module.md", "examples/good/k8s-deployment.md", "examples/bad/*"]
+- **reason:** Specialist authoring for IaC/k8s domain content (terraform, opentofu, state, modules, k8s workloads/networking/storage/rbac/helm/kustomize) where the existing tech-writer persona lacks the domain expertise. Active for v0.2 P1–P4 only; removed after milestone v0.2 completes (per D-027, D-014).
+
 ## Territory Enforcement

 Mode: `warn` (per config.json `personas.territory_enforcement`).

-At `warn`, territory violations are logged but not blocked. This is appropriate for a docs project where tech-writer may touch `.ciagent/` files incidentally (e.g., updating ROADMAP status). Strict mode would be appropriate once territories stabilize.
+At `warn`, territory violations are logged but not blocked. This is appropriate for a docs project where tech-writer may touch `.ciagent/` files incidentally (e.g., updating ROADMAP status). Strict mode would be appropriate once territories stabilize.
+
+## v0.2 Persona Roster Summary
+
+Active personas for v0.2 (4): lead-developer, tech-writer, domain-expert, platform-engineer (phase-specific).
+Inactive personas (3, unchanged from v0.1): data-engineer, backend-engineer, frontend-engineer.
+Post-v0.2: platform-engineer removed; roster returns to 3 active personas (lead-developer, tech-writer, domain-expert).
@@ -204,4 +204,171 @@ Per branch-strategy.md, this is an NFR milestone (all phases are docs/chore —
 | P4 | 2 | Wave 1 matrix, Wave 2 review docs parallel |
 | P5 | 1 | Single parallel wave (7 examples) |
 | P6 | 1 | Single parallel wave (6 docs) |
-| P7 | 3 | Sequential: review → audit → ship |
+| P7 | 3 | Sequential: review → audit → ship |
+
+---
+
+# Atelier — Plan (v0.2)
+
+> Vertical-slice plans with wave ordering for milestone v0.2 (Infrastructure as Code + Kubernetes). Plans reference REQ-IDs from `.ciagent/atelier/REQUIREMENTS.md` (ATELIER-36..59). NFR milestone — all phases produce docs; no `feat` code.
+
+## Phase 0 — Pre-Execution (COMPLETE)
+
+Stages: SPECIFY ✓ → CLARIFY ✓ → RESEARCH ✓ → IDEATE ✓ → PLAN ✓ → SHIP
+Branch: `atelier/phase/00-pre-execution`
+Tag: v0.1.0
+
+## Phase 1 — Infrastructure as Code Domain
+
+**Goal:** Author the `domains/infrastructure-as-code/` tree — 10 first principles (P1–P10) plus 4 derived docs (terraform, opentofu, state, modules). Resolves architectural drift (IDEATE-01).
+**Branch:** `atelier/phase/01-infrastructure-as-code` (from `atelier/milestone/v0.2-iac-k8s`)
+**Personas:** platform-engineer (author), domain-expert (validate traceability), tech-writer (style/format)
+**Tag:** v0.1.1
+**Requirements:** ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40
+
+### Wave 1 (sequential — first-principles must exist before derived docs)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 01-01-01 | `domains/infrastructure-as-code/first-principles.md` | platform-engineer | ATELIER-36 | 10 principles (P1–P10) per RESEARCH.md; each names the core C-rule(s) it derives from; each has definition + "what violates" |
+
+### Wave 2 (parallel — derived docs, independent)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 01-02-01 | `domains/infrastructure-as-code/terraform.md` | platform-engineer | ATELIER-37 | HCL structure, providers, resources, data sources, workspaces, init/plan/apply/destroy, registry, state backends; cross-link to state.md + modules.md |
+| 01-02-02 | `domains/infrastructure-as-code/opentofu.md` | platform-engineer | ATELIER-38 | Fork lineage (BUSL→MPL via LF), CLI parity, registry parity, migration from Terraform, governance, when-to-choose; cross-link to terraform.md |
+| 01-02-03 | `domains/infrastructure-as-code/state.md` | platform-engineer | ATELIER-39 | Backends (S3+DynamoDB, GCS, Azure, local), locking, env isolation, state commands, sensitive values, import/export; **state backend comparison table** (IDEATE-11) |
+| 01-02-04 | `domains/infrastructure-as-code/modules.md` | platform-engineer | ATELIER-40 | Module structure, inputs/outputs, versioning, source patterns (registry/git/local), composition, module-vs-copy boundary |
+
+**Verify (P1):**
+- Structural: 5 files exist under `domains/infrastructure-as-code/`
+- Behavioral: every P1–P10 in first-principles names ≥1 C-rule (domain-expert sign-off)
+- Security: P10 (Secrets Never in Code) section present
+- Quality: each derived doc has ≥1 outbound cross-link to a MANIFEST-listed doc (IDEATE-08)
+
+## Phase 2 — Kubernetes Domain
+
+**Goal:** Author the `domains/kubernetes/` tree — 10 first principles (P1–P10) plus 6 derived docs (workloads, networking, storage, rbac, helm, kustomize).
+**Branch:** `atelier/phase/02-kubernetes` (from `atelier/milestone/v0.2-iac-k8s`)
+**Personas:** platform-engineer (author), domain-expert (validate), tech-writer (style)
+**Tag:** v0.1.2
+**Requirements:** ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47
+
+### Wave 1 (sequential — first-principles first)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 02-01-01 | `domains/kubernetes/first-principles.md` | platform-engineer | ATELIER-41 | 10 principles (P1–P10) per RESEARCH.md; each names core C-rule(s); each has definition + "what violates" |
+
+### Wave 2 (parallel — derived docs)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 02-02-01 | `domains/kubernetes/workloads.md` | platform-engineer | ATELIER-42 | Pod, ReplicaSet, Deployment, StatefulSet, DaemonSet, Job/CronJob, probes, lifecycle, PDB |
+| 02-02-02 | `domains/kubernetes/networking.md` | platform-engineer | ATELIER-43 | Service types, Ingress, Gateway API, EndpointSlices, NetworkPolicy, DNS, dual-stack |
+| 02-02-03 | `domains/kubernetes/storage.md` | platform-engineer | ATELIER-44 | Volumes, PV/PVC, StorageClass, CSI, dynamic provisioning, snapshots, reclaim policies |
+| 02-02-04 | `domains/kubernetes/rbac.md` | platform-engineer | ATELIER-45 | Role/ClusterRole, bindings, ServiceAccount, **Pod Security Standards + Admission** (IDEATE-12), RBAC good practices; cross-link security/authorization |
+| 02-02-05 | `domains/kubernetes/helm.md` | platform-engineer | ATELIER-46 | Chart structure, values, templates, registries, release mgmt; **Helm vs Kustomize decision matrix** (IDEATE-10) |
+| 02-02-06 | `domains/kubernetes/kustomize.md` | platform-engineer | ATELIER-47 | Base + overlays, kustomization.yaml, patches, no templating; **Helm vs Kustomize decision matrix** (IDEATE-10) |
+
+**Verify (P2):**
+- Structural: 7 files exist under `domains/kubernetes/`
+- Behavioral: every P1–P10 traces to ≥1 C-rule (domain-expert sign-off)
+- Security: P7 (RBAC least privilege) + P9 (config/secrets separate) sections present
+- Quality: each derived doc ≥1 outbound cross-link (IDEATE-08); helm.md and kustomize.md share the decision matrix consistently
+
+## Phase 3 — Matrix + Review Integration
+
+**Goal:** Extend the matrix, review docs, and manifest to absorb the 20 new P-rules and 11 new documents. Closes the traceability loop.
+**Branch:** `atelier/phase/03-matrix-review` (from `atelier/milestone/v0.2-iac-k8s`)
+**Personas:** domain-expert (matrix + anti-patterns), tech-writer (checklists + manifest), platform-engineer (content review)
+**Tag:** v0.1.3
+**Requirements:** ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-59
+
+### Wave 1 (sequential — matrix is the arbiter, must be authoritative first)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 03-01-01 | `matrix/principles-matrix.md` (extend) | domain-expert | ATELIER-48 | Add "Infrastructure as Code" + "Kubernetes" sections, 10 rows each, format matching v0.1 tables; **review check: row count per new domain = 10, each row ≥1 C-rule** (IDEATE-02, IDEATE-13) |
+
+### Wave 2 (parallel — independent extensions)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 03-02-01 | `matrix/domain-coverage.md` (extend) | domain-expert | ATELIER-49 | Add rows for both new domains with schema: domain, P-count, derived-doc-count, manifest-listed, status (IDEATE-03) |
+| 03-02-02 | `review/agent-checklist.md` (extend) | tech-writer | ATELIER-50 | Add "If Infrastructure as Code" + "If Kubernetes" trigger sections (IDEATE-05) |
+| 03-02-03 | `review/peer-review-checklist.md` (extend) | tech-writer | ATELIER-59 | Add IaC + k8s peer-review sections (parity with agent-checklist, IDEATE-09) |
+| 03-02-04 | `review/anti-patterns.md` (extend) | domain-expert | ATELIER-51 | Add IaC violations (unlocked state, hardcoded secrets, unversioned modules, manual drift, local state in prod) + k8s violations (bare pod, no resources, cluster-admin, :latest, no probes, emptyDir for persistent data) + **orphaned P-rule** + **deployable example artifact** (IDEATE-06, IDEATE-13, IDEATE-14) |
+| 03-02-05 | `MANIFEST.md` (extend) | tech-writer | ATELIER-52 | Add both new domains + all 11 derived docs to the Domains table (IDEATE-04) |
+
+**Verify (P3):**
+- Structural: matrix has 13 domain sections (11 v0.1 + 2 new), 130 P-rules total
+- Behavioral: every new P-rule has a matrix row; domain-expert verifies no orphans
+- Security: anti-patterns cover secrets-in-HCL and cluster-admin
+- Quality: MANIFEST lists all new docs; unlisted = not part of framework
+
+## Phase 4 — Examples + Cross-Links
+
+**Goal:** Add good + bad examples for IaC/k8s and verify cross-domain links from new domains to existing ones. Examples are markdown with fenced code only (no standalone .tf/.yaml).
+**Branch:** `atelier/phase/04-examples-crosslinks` (from `atelier/milestone/v0.2-iac-k8s`)
+**Personas:** platform-engineer (examples), tech-writer (cross-link audit), domain-expert (P-rule citation)
+**Tag:** v0.1.4
+**Requirements:** ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56
+
+### Wave 1 (parallel — examples independent)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 04-01-01 | `examples/good/terraform-module.md` | platform-engineer | ATELIER-53 | Good IaC example; markdown with fenced HCL; demonstrates P6 Modules Compose + P8 Remote State; cross-link to modules.md + state.md |
+| 04-01-02 | `examples/good/k8s-deployment.md` | platform-engineer | ATELIER-54 | Good k8s example; markdown with fenced YAML; demonstrates P4 requests/limits + P5 probes + P7 RBAC; cross-link to workloads.md + rbac.md |
+| 04-01-03 | `examples/bad/terraform-unlocked-state.md` | platform-engineer | ATELIER-55 | Bad IaC example; cites P8 breached (no locking) + P10 if secrets in state; per IDEATE-07 |
+| 04-01-04 | `examples/bad/k8s-bare-pod-no-resources.md` | platform-engineer | ATELIER-55 | Bad k8s example; cites P2 (bare pod) + P4 (no requests/limits) breached; per IDEATE-07 |
+
+### Wave 2 (sequential — cross-link audit after all docs exist)
+| Task | File | Persona | REQ-ID | Must-have |
+|------|------|---------|--------|-----------|
+| 04-02-01 | Cross-link audit (all new derived docs) | tech-writer | ATELIER-56 | Review check: every new derived doc ≥1 outbound cross-link to a MANIFEST-listed existing domain doc (devops/security/observability/data); links resolve (IDEATE-08) |
+
+**Verify (P4):**
+- Structural: 4 new example files exist (all .md)
+- Behavioral: each bad example cites the P-rule breached
+- Security: no standalone .tf/.yaml files (deployable artifact mitigation, IDEATE-14)
+- Quality: all cross-links resolve to MANIFEST-listed docs
+
+## Phase 5 — Final Review + Ship (N+1)
+
+**Goal:** Multi-persona review across all v0.2 phases, audit, milestone ship.
+**Branch:** `atelier/phase/05-final-review-ship` (from `atelier/milestone/v0.2-iac-k8s`)
+**Personas:** lead-developer (coordinate), domain-expert (review), tech-writer (review), platform-engineer (review, then removed)
+**Tag:** v0.1.5 (IS the v0.2 milestone release — NFR, no separate minor tag)
+**Requirements:** ATELIER-57, ATELIER-58
+
+### Wave 1 (sequential — review → audit → ship)
+| Task | Activity | Persona | REQ-ID | Must-have |
+|------|----------|---------|--------|-----------|
+| 05-01-01 | `ciagent-review` — multi-persona review of all v0.2 changes | lead-developer | ATELIER-57 | Auto-apply P0 fixes; flag P1+ for post-hoc; if P1+ found, fix in this phase |
+| 05-01-02 | `ciagent-audit` — reconstruction + discipline | lead-developer | ATELIER-57 | git log matches .ciagent/ files; branch hygiene; commit discipline; fix critical issues here |
+| 05-01-03 | `ciagent-ship` — milestone ship | lead-developer | ATELIER-58 | Merge phase/05 → milestone/v0.2 → main; tag v0.1.5; Gitea release; delete all v0.2 branches |
+| 05-01-04 | Complete milestone (REQUIREMENTS + ROADMAP) | lead-developer | ATELIER-58 | Mark all v0.2 requirements `covered`; ROADMAP v0.2 → complete; clear checkpoint |
+
+**Verify (P5):**
+- Structural: all 24 v0.2 requirements (ATELIER-36..59) marked covered
+- Behavioral: reconstruction test passes (git log ↔ .ciagent/)
+- Security: audit clean (no critical issues)
+- Quality: milestone merged to main, tag v0.1.5 exists, all v0.2 branches deleted
+
+## v0.2 Wave Ordering Summary
+
+| Phase | Waves | Parallelism |
+|-------|-------|-------------|
+| P0 | (pre-exec) | Sequential stages |
+| P1 | 2 | Wave 1 sequential (first-principles), Wave 2 parallel (4 derived docs) |
+| P2 | 2 | Wave 1 sequential (first-principles), Wave 2 parallel (6 derived docs) |
+| P3 | 2 | Wave 1 sequential (matrix), Wave 2 parallel (5 extensions) |
+| P4 | 2 | Wave 1 parallel (4 examples), Wave 2 sequential (cross-link audit) |
+| P5 | 1 | Sequential: review → audit → ship → complete |
+
+## v0.2 Requirements → Phase Mapping
+
+| Phase | Requirements | Count |
+|-------|-------------|-------|
+| 1 | ATELIER-36..40 | 5 |
+| 2 | ATELIER-41..47 | 7 |
+| 3 | ATELIER-48..52, 59 | 6 |
+| 4 | ATELIER-53..56 | 4 |
+| 5 | ATELIER-57, 58 | 2 |
+| **Total** | | **24** |
@@ -52,6 +52,31 @@ Build **Atelier** — a first-principles, docs-as-code engineering framework for
 - Translation/localization of the framework docs
 - Automated agent integration adapters beyond markdown consumption
 - Versioned per-domain release artifacts (the whole framework versions together)
+- Runtime code (terraform manifests, k8s YAML, deployable artifacts) — Atelier remains docs-only. Examples under `examples/iac/` and `examples/k8s/` are illustrative markdown (rendered manifests in code fences), never deployed.
+
+## v0.2 — Infrastructure as Code + Kubernetes
+
+**Milestone type:** NFR (all phases produce docs — no `feat` runtime code)
+**Tag line:** v0.1.x (previous minor from v0.2)
+**Scope:** Extend the domain tree with two new top-level domains covering IaC tooling and the Kubernetes platform, plus matrix, review, and examples integration.
+
+### New Domains
+
+- `domains/infrastructure-as-code/` — tooling domain
+  - `first-principles.md` — 10 IaC principles (P1–P10)
+  - Derived: `terraform.md`, `opentofu.md`, `state.md`, `modules.md`
+- `domains/kubernetes/` — platform domain
+  - `first-principles.md` — 10 k8s principles (P1–P10)
+  - Derived: `workloads.md`, `networking.md`, `storage.md`, `rbac.md`, `helm.md`, `kustomize.md`
+
+### Cross-Domain Integration
+
+- Extend `matrix/principles-matrix.md` with 20 new P-rules → core C-rule mappings (10 per new domain)
+- Extend `matrix/domain-coverage.md` with the two new domains
+- Extend `review/agent-checklist.md` and `review/anti-patterns.md` with IaC/k8s checks/violations
+- Update `MANIFEST.md` to list all new documents (manifest is authoritative)
+- New examples: `examples/good/terraform-module.md`, `examples/good/k8s-deployment.md`, `examples/bad/` counterparts
+- Cross-links from new domains to existing `devops/`, `security/`, `observability/`, `data/` domains

 ## Key Decisions

@@ -67,7 +92,17 @@ Build **Atelier** — a first-principles, docs-as-code engineering framework for
 | D-008 | 6 execution phases (P1–P6) + final phase P7 | Mirrors spec Part 6 "Recommended Build Order" | 0.88 |
 | D-009 | NFR milestone type (all phases are docs/chore) | Every phase produces markdown docs, no feat code; NFR patch-line versioning | 0.92 |
 | D-010 | Tags run on v0.0.x patch line (prev minor from v0.1) | Per branch-strategy.md: milestone 0.1 → tags v0.0.0..v0.0.7 | 0.90 |
+| D-011 | v0.2 adds two new top-level domains: infrastructure-as-code + kubernetes | User directive to incorporate terraform/opentofu + kubernetes; two-domain split reflects tool-vs-platform distinction | 0.90 |
+| D-012 | v0.2 remains docs-only (NFR milestone type) | PROJECT.md constraint "no runtime code" preserved; manifests appear only as illustrative code-fence content in examples | 0.95 |
+| D-013 | v0.2 tags run on v0.1.x patch line (prev minor from v0.2) | Per branch-strategy.md: milestone 0.2 → tags v0.1.0..v0.1.5; v0.1.5 IS the v0.2 release (NFR → no separate minor tag) | 0.90 |
+| D-014 | Add phase-specific `platform-engineer` persona for P1–P4 | IaC/k8s domain authoring benefits from a specialist persona with declarative-first/stateless-examples constraints; removed after milestone | 0.82 |
+| D-015 | 4 execution phases (P1–P4) + final phase P5 | P1 IaC domain, P2 k8s domain, P3 matrix+review, P4 examples+cross-links, P5 final review+ship | 0.85 |

 ## Cross-Project References

-None yet. Atelier is a standalone docs framework.
+None yet. Atelier is a standalone docs framework.
+
+## Milestone History
+
+- **v0.1** — Initial Framework (COMPLETE). 8 core principles, 11 domains, 110 domain principles, full matrix, 4+3 examples, 4 languages. Tag v0.0.7.
+- **v0.2** — Infrastructure as Code + Kubernetes (IN PROGRESS). Adds 2 domains (20 new P-rules), matrix/review/examples integration. Tags v0.1.0–v0.1.5.
@@ -55,4 +55,73 @@

 ## Milestone Summary

-All 35 requirements covered. 8 core principles, 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. NFR milestone, 7 patches (v0.0.0–v0.0.7), v0.0.7 is the v0.1.0 release.
+All 35 requirements covered. 8 core principles, 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. NFR milestone, 7 patches (v0.0.0–v0.0.7), v0.0.7 is the v0.1.0 release.
+
+## v0.2 Requirements — Infrastructure as Code + Kubernetes
+
+**Milestone type:** NFR (all phases produce docs)
+**Tag line:** v0.1.x (previous minor from v0.2)
+
+| REQ-ID | Requirement | Priority | Phase | Status |
+|--------|-------------|----------|-------|--------|
+| ATELIER-36 | `domains/infrastructure-as-code/first-principles.md` — 10 IaC principles (P1–P10) | P0 | 1 | covered |
+| ATELIER-37 | `domains/infrastructure-as-code/terraform.md` — Terraform derived doc | P1 | 1 | covered |
+| ATELIER-38 | `domains/infrastructure-as-code/opentofu.md` — OpenTofu derived doc | P1 | 1 | covered |
+| ATELIER-39 | `domains/infrastructure-as-code/state.md` — IaC state management derived doc | P1 | 1 | covered |
+| ATELIER-40 | `domains/infrastructure-as-code/modules.md` — IaC module composition derived doc | P1 | 1 | covered |
+| ATELIER-41 | `domains/kubernetes/first-principles.md` — 10 k8s principles (P1–P10) | P0 | 2 | covered |
+| ATELIER-42 | `domains/kubernetes/workloads.md` — workloads derived doc | P1 | 2 | covered |
+| ATELIER-43 | `domains/kubernetes/networking.md` — networking derived doc | P1 | 2 | covered |
+| ATELIER-44 | `domains/kubernetes/storage.md` — storage derived doc | P1 | 2 | covered |
+| ATELIER-45 | `domains/kubernetes/rbac.md` — RBAC derived doc incl. Pod Security Standards/Admission (cross-link security/authorization) | P1 | 2 | covered |
+| ATELIER-46 | `domains/kubernetes/helm.md` — Helm derived doc (with Helm vs Kustomize decision matrix) | P1 | 2 | covered |
+| ATELIER-47 | `domains/kubernetes/kustomize.md` — Kustomize derived doc (with Helm vs Kustomize decision matrix) | P1 | 2 | covered |
+| ATELIER-48 | Extend `matrix/principles-matrix.md` with 20 new P-rules → core C-rule mappings (10 per new domain; review check: row count per domain = 10, each row ≥1 C-rule) | P0 | 3 | covered |
+| ATELIER-49 | Extend `matrix/domain-coverage.md` with infrastructure-as-code + kubernetes (row schema: domain, P-count, derived-doc-count, manifest-listed, status) | P1 | 3 | covered |
+| ATELIER-50 | Extend `review/agent-checklist.md` with IaC + k8s trigger sections | P1 | 3 | covered |
+| ATELIER-51 | Extend `review/anti-patterns.md` with IaC + k8s violations incl. orphaned P-rule + deployable example artifact | P1 | 3 | covered |
+| ATELIER-52 | Update `MANIFEST.md` to list all new v0.2 documents (manifest authoritative) | P0 | 3 | covered |
+| ATELIER-53 | `examples/good/terraform-module.md` — good IaC example (markdown with fenced HCL only; no standalone .tf) | P2 | 4 | pending |
+| ATELIER-54 | `examples/good/k8s-deployment.md` — good k8s example (markdown with fenced YAML only; no standalone .yaml) | P2 | 4 | pending |
+| ATELIER-55 | `examples/bad/terraform-unlocked-state.md` + `examples/bad/k8s-bare-pod-no-resources.md` — 2 named bad examples (each cites the P-rule breached) | P2 | 4 | pending |
+| ATELIER-56 | Cross-links from new domains to existing devops/security/observability/data domains (review check: every new derived doc ≥1 outbound cross-link to a MANIFEST-listed doc) | P1 | 4 | pending |
+| ATELIER-57 | Final review passes (all v0.2 phases reviewed, audit clean) | P0 | 5 | pending |
+| ATELIER-58 | Milestone v0.2 released (tag v0.1.5, merged to main) | P0 | 5 | pending |
+| ATELIER-59 | Extend `review/peer-review-checklist.md` with IaC + k8s sections (parity with agent-checklist) | P1 | 3 | covered |
+
+## v0.2 Traceability Matrix
+
+| Phase | Requirements |
+|-------|-------------|
+| 0 (Pre-Execution) | (governance: spec, clarify, research, ideate, plan) |
+| 1 (Infrastructure as Code Domain) | ATELIER-36..ATELIER-40 |
+| 2 (Kubernetes Domain) | ATELIER-41..ATELIER-47 |
+| 3 (Matrix + Review Integration) | ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-59 |
+| 4 (Examples + Cross-Links) | ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56 |
+| 5 (Final Review + Ship) | ATELIER-57, ATELIER-58 |
+
+## v0.2 Ideation Log
+
+**Generated:** 16 ideas (mechanical: 9, backend-enriched: 7)
+**Accepted:** 14 (all v0.2-scope, confidence ≥ 0.79, above 0.6 autonomy threshold → auto-accepted)
+**Deferred to v0.3:** 2 (IDEATE-15 GitOps/operators domain; IDEATE-16 ai-ml/i18n/compliance domains)
+**Rejected:** 0
+
+| IDEATE-ID | Source | Category | Confidence | Decision | Mapped REQ |
+|-----------|--------|----------|------------|----------|------------|
+| IDEATE-01 | mechanical | architecture | 0.97 | accepted → refines | ATELIER-36 (drift resolution) |
+| IDEATE-02 | mechanical | coverage | 0.95 | accepted → refines | ATELIER-48 (matrix format) |
+| IDEATE-03 | mechanical | spec | 0.82 | accepted → refines | ATELIER-49 (row schema) |
+| IDEATE-04 | mechanical | coverage | 0.96 | accepted → refines | ATELIER-52 (manifest table) |
+| IDEATE-05 | mechanical | quality | 0.94 | accepted → refines | ATELIER-50 (checklist triggers) |
+| IDEATE-06 | mechanical | quality | 0.93 | accepted → refines | ATELIER-51 (anti-patterns) |
+| IDEATE-07 | mechanical | spec | 0.88 | accepted → refines | ATELIER-55 (named examples) |
+| IDEATE-08 | mechanical | spec | 0.86 | accepted → refines | ATELIER-56 (link verification) |
+| IDEATE-09 | mechanical | coverage | 0.79 | accepted → new req | ATELIER-59 (peer-review parity) |
+| IDEATE-10 | backend-enriched | improvement | 0.83 | accepted → refines | ATELIER-46 (decision matrix) |
+| IDEATE-11 | backend-enriched | improvement | 0.81 | accepted → refines | ATELIER-39 (state comparison table) |
+| IDEATE-12 | backend-enriched | improvement | 0.80 | accepted → refines | ATELIER-45 (PSS coverage) |
+| IDEATE-13 | backend-enriched | chaos | 0.85 | accepted → refines | ATELIER-48, ATELIER-51 (orphan mitigation) |
+| IDEATE-14 | backend-enriched | chaos | 0.87 | accepted → refines | ATELIER-53, ATELIER-51 (deployable artifact mitigation) |
+| IDEATE-15 | backend-enriched | improvement | 0.72 | deferred v0.3 | — (GitOps/operators domain) |
+| IDEATE-16 | backend-enriched | improvement | 0.68 | deferred v0.3 | — (ai-ml/i18n/compliance) |
@@ -90,4 +90,129 @@ None. Atelier produces markdown only. No `package.json`, no runtime dependencies
 2. The 8 core principles are recoverable from `matrix/principles-matrix.md`'s key (D-011) — enough to author `core/first-principles.md` in P1.
 3. Custom personas needed: tech-writer (primary), domain-expert (validator). Default 3 inactive.
 4. No build/lint tooling in scope — markdown is the artifact (D-016, ARCHITECTURE.md).
-5. Phase ordering (P1–P6) follows the spec's build order; matrix + review come after all domains exist (P4).
+5. Phase ordering (P1–P6) follows the spec's build order; matrix + review come after all domains exist (P4).
+
+---
+
+# v0.2 Research — Infrastructure as Code + Kubernetes
+
+> Research conducted during v0.2 P0 RESEARCH stage. Informs the two new domains, matrix extension, and the phase-specific platform-engineer persona. See CLARIFY.md D-019..D-030 for resolved ambiguities.
+
+## Domain A: Infrastructure as Code (Terraform / OpenTofu)
+
+### Prior Art
+
+- **Terraform** (HashiCorp, 2014, original MPL-2.0): core workflow is **Write → Plan → Apply**. Declarative HCL; provider-based resource model; state file as the source of truth for drift detection. ([developer.hashicorp.com/terraform/intro/core-workflow](https://developer.hashicorp.com/terraform/intro/core-workflow))
+- **OpenTofu** (Linux Foundation, 2023 fork of MPL Terraform after HashiCorp's BUSL license change): community-driven, truly open source (MPL path), backwards-compatible with Terraform, layered and modular, impartial stewardship. ([opentofu.org/manifesto](https://opentofu.org/manifesto))
+- **Pulumi** (out of v0.2 scope per D-019 — user chose terraform+opentofu; general IaC principles cover the model).
+- **12-Factor** (already in Atelier v0.1 devops domain): config in environment, disposable, dev/prod parity.
+
+### Principles Identified for `infrastructure-as-code/first-principles.md` (P1–P10)
+
+Each derived from a core C-rule (see matrix updates in P3):
+
+1. **P1 Declarative Intent** — describe desired state, not steps to reach it. (C2 Clarity, C3 Simplicity)
+2. **P2 Idempotence** — applying the same config twice yields the same result. (C1 Correctness)
+3. **P3 State is Truth** — the state file is the authoritative record; drift is a bug. (C1 Correctness, C7 Observability)
+4. **P4 Plan Before Apply** — preview every change before mutating real infrastructure. (C5 Reversibility)
+5. **P5 Version Everything** — config, state, providers, modules all versioned and reproducible. (C5 Reversibility)
+6. **P6 Modules Compose** — encapsulate repeatable patterns as versioned modules; compose, don't copy. (C6 Composability)
+7. **P7 Least Privilege Providers** — provider credentials scoped to minimum needed. (C1 Correctness via security)
+8. **P8 Remote State with Locking** — state stored remotely with locking to prevent concurrent corruption. (C4 Locality, C1 Correctness)
+9. **P9 Drift is Recoverable** — `plan` detects drift; `apply` reconciles. Manual mutation is an incident. (C5 Reversibility, C7 Observability)
+10. **P10 Secrets Never in Code** — secrets via providers/external secret stores, never hardcoded in HCL. (C1 Correctness, security non-tradeable)
+
+### Derived Docs
+
+- `terraform.md` — HCL structure, providers, resources, data sources, workspaces, `terraform init/plan/apply/destroy`, registry, state backends.
+- `opentofu.md` — fork lineage (BUSL → MPL via Linux Foundation), CLI parity, registry parity, migration path from Terraform, community governance, when to choose OpenTofu (license neutrality, supply-chain).
+- `state.md` — state backends (S3+DynamoDB lock, GCS, Azure blob, local for dev), locking, state isolation per environment, `terraform state` commands, sensitive values in state, state import/export.
+- `modules.md` — module structure, inputs/outputs, versioning (registry tags), `source` patterns (registry, git, local), module composition, the module-vs-copy boundary.
+
+### Cross-Domain Links (one-directional in v0.2, per D-026)
+
+- `devops/P1 Reproducibility` ← IaC P1, P5
+- `devops/P6 Configuration as Code` ← IaC P1
+- `security/secrets` ← IaC P10
+- `security/supply-chain` ← OpenTofu license-stewardship angle (cross-link, not duplication)
+- `data/migrations` ← IaC state lifecycle (analog, not direct)
+
+## Domain B: Kubernetes
+
+### Prior Art
+
+- **Kubernetes** (CNCF, graduated): container orchestration platform. Concept taxonomy (per kubernetes.io/docs/concepts): Workloads (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob), Services/Networking (Service, Ingress, Gateway API, NetworkPolicy, DNS), Storage (PV, PVC, StorageClass, CSI), Security (RBAC, ServiceAccounts, Pod Security Standards, Secrets, multi-tenancy), Configuration (ConfigMaps, Secrets, Resource Management), Policies (LimitRanges, ResourceQuotas), Scheduling/Eviction.
+- **Helm** (CNCF): package manager for k8s — charts as templated manifests, values overrides, registries.
+- **Kustomize** (built-in): overlay-based manifest customization without templating — base + overlays, no DSL.
+- **12-Factor App** — backing influence for k8s workload principles (disposability, config, logs).
+- **GitOps** (ArgoCD, Flux) — out of v0.2 first-principles scope but referenced as a deployment pattern for helm/kustomize; candidate IDEATE item.
+
+### Principles Identified for `kubernetes/first-principles.md` (P1–P10)
+
+1. **P1 Declarative Desired State** — controllers reconcile current → desired. Imperative commands are exceptions. (C1 Correctness, C2 Clarity)
+2. **P2 Pods are Mortal** — never assume a pod's identity or lifetime. Use controllers, not bare pods. (C5 Reversibility)
+3. **P3 Labels Select** — labels + selectors are the join mechanism for workloads, services, policies. (C6 Composability, C2 Clarity)
+4. **P4 Requests and Limits are Contracts** — resource requests drive scheduling; limits drive QoS. Unspecified = best-effort = first evicted. (C8 Economy, C1 Correctness)
+5. **P5 Probes Drive Health** — liveness, readiness, startup probes; the platform cannot heal what it cannot see. (C7 Observability, C1 Correctness)
+6. **P6 Namespaces Bound Blast Radius** — namespaces are the unit of quota, RBAC, network policy, and cleanup. (C4 Locality)
+7. **P7 RBAC by Intent, Not Identity** — bind roles to service accounts by workload purpose; least privilege; avoid cluster-admin. (C1 Correctness via security)
+8. **P8 Storage is Explicit** — ephemeral by default; persistence requires PVC + StorageClass + reclaim policy decisions. (C5 Reversibility, C4 Locality)
+9. **P9 Config and Secrets are Separate** — ConfigMaps for non-sensitive, Secrets for sensitive; both injected, never baked into images. (C2 Clarity, security)
+10. **P10 Roll Forward, Roll Back** — rolling updates + rollout history; every deployment has a known-good rollback. (C5 Reversibility)
+
+### Derived Docs
+
+- `workloads.md` — Pod, ReplicaSet, Deployment, StatefulSet (identity + ordering), DaemonSet, Job/CronJob, controllers, probes, lifecycle, disruption budgets.
+- `networking.md` — Service (ClusterIP/NodePort/LoadBalancer), Ingress, Gateway API, EndpointSlices, NetworkPolicy, DNS, dual-stack.
+- `storage.md` — Volumes, PV/PVC, StorageClass, CSI, dynamic provisioning, volume snapshots, reclaim policies, ephemeral volumes.
+- `rbac.md` — Role/ClusterRole, RoleBinding/ClusterRoleBinding, ServiceAccount, Pod Security Standards/Admission, RBAC good practices (cross-link `security/authorization`).
+- `helm.md` — chart structure, values.yaml, templates, registries, release management, when Helm fits vs Kustomize.
+- `kustomize.md` — base + overlays, kustomization.yaml, patches, no templating, when Kustomize fits vs Helm.
+
+### Cross-Domain Links (one-directional in v0.2, per D-026)
+
+- `devops/P4 Rollback First` ← k8s P10
+- `devops/P5 Progressive Delivery` ← k8s rolling updates, canary via labels
+- `devops/P3 Observability` ← k8s P5 probes, metrics
+- `security/authorization` ← k8s P7 RBAC
+- `security/secrets` ← k8s P9 Secrets
+- `observability/metrics` ← k8s P5, resource metrics pipeline
+- `data/storage` ← k8s P8 (analog: PVC lifecycle ↔ migration discipline)
+
+## Architectural Fit (v0.1 Contract Preservation)
+
+- **Hierarchy preserved:** both new domains depend on `core/`; their P-rules trace to C1–C8 via the matrix. No lateral authority.
+- **10 P-rules per domain** (per D-018, D-030): consistent with v0.1.
+- **Manifest authoritative:** all new documents added to `MANIFEST.md` in P3. Unlisted = not part of the framework.
+- **No runtime code:** examples are illustrative markdown with manifests in code fences (per D-025, PROJECT.md constraint). No `.tf`, `.yaml`, `.sh` deployable artifacts — only fenced code blocks inside `.md` files.
+- **Conflict resolution unchanged:** matrix extended, not replaced. Core precedence (C1 > C2 > ... > C8) governs any new vs existing rule conflict.
+
+## Prior Art Position (v0.2 extension)
+
+Existing IaC/k8s guidance (Terraform docs, k8s docs, Helm/Kustomize docs, Google SRE, CNCF guides) state practices but none map every domain rule back to a small set of universal core principles. Atelier's v0.2 contribution is the same differentiation as v0.1: **traceable principle hierarchy with a join table**. The two new domains add 20 P-rules, each traced to a core C-rule, extending the matrix from 110 to 130 domain principles across 13 domains.
+
+## v0.2 Persona Assessment
+
+See `.ciagent/atelier/PERSONAS.md` for the updated roster. v0.2 adds one phase-specific persona:
+
+- **platform-engineer** (phase-specific, removed after v0.2): domain = infrastructure/platform; territory = `domains/infrastructure-as-code/**, domains/kubernetes/**, examples/good/{terraform-module,k8s-deployment}.md, examples/bad/*`; constraints = ["declarative-first", "stateless examples", "trace to core", "10 P-rules per domain"]; reason = specialist authoring for IaC/k8s content with domain expertise the existing tech-writer persona lacks.
+
+## v0.2 Risks and Mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| New P-rules orphaned from core (no matrix trace) | P3 extends matrix; domain-expert persona verifies every new P-rule traces to a C-rule before sign-off |
+| IaC and k8s domains overlap (state, secrets) | Cross-links are one-directional (D-026); each domain owns its own principle angle (IaC P3 state-as-truth vs k8s P8 storage-explicit) |
+| Examples become deployable (runtime code) | platform-engineer constraint "stateless examples"; examples are markdown with fenced code, never standalone `.tf`/`.yaml` files |
+| OpenTofu doc duplicates terraform.md | OpenTofu doc covers fork-specific governance/license/migration; references terraform.md for the shared HCL/state model |
+| Helm vs Kustomize preference bias | Both docs present neutral "when X fits" guidance; neither advocated over the other |
+
+## v0.2 Conclusions
+
+1. Two new top-level domains extend the framework without breaking the v0.1 contract.
+2. 20 new P-rules (10 per domain) all trace to core C1–C8 — matrix extends from 110 to 130.
+3. OpenTofu shares the IaC domain with Terraform (fork lineage); separate derived doc covers governance/license.
+4. State and modules get their own derived docs (cross-cutting IaC concerns).
+5. K8s derived docs mirror the k8s concept taxonomy: workloads, networking, storage, rbac, helm, kustomize.
+6. A phase-specific platform-engineer persona is warranted for P1–P4; removed after v0.2.
+7. No runtime code; examples are illustrative markdown only.
@@ -39,6 +39,47 @@ NFR milestone: no separate minor tag. The final patch (v0.0.7) IS the v0.1 deliv
 - Milestone v0.1 complete. All phases shipped.
 - Future: v0.2 could add `domains/ai-ml/`, `domains/i18n/`, `domains/compliance/` per spec Part 6 next-steps.

+## Milestone: v0.2 — Infrastructure as Code + Kubernetes (IN PROGRESS)
+
+**Milestone type:** NFR (all phases produce docs — no `feat` code)
+**Tag line:** v0.1.x (previous minor from v0.2)
+**Phases:** P0 (pre-execution) + P1–P4 (execution) + P5 (final review+ship)
+
+| Phase | Name | Type | Status | Key Deliverables |
+|-------|------|------|--------|------------------|
+| 0 | Pre-Execution | docs | complete | Spec, clarify, research, ideate, plan, PERSONAS.md (adds platform-engineer persona) |
+| 1 | Infrastructure as Code Domain | docs | complete | domains/infrastructure-as-code/{first-principles, terraform, opentofu, state, modules}.md |
+| 2 | Kubernetes Domain | docs | complete | domains/kubernetes/{first-principles, workloads, networking, storage, rbac, helm, kustomize}.md |
+| 3 | Matrix + Review Integration | docs | complete | matrix/principles-matrix.md (20 new mappings), matrix/domain-coverage.md, review/{agent-checklist, peer-review-checklist, anti-patterns}.md, MANIFEST.md |
+| 4 | Examples + Cross-Links | docs | pending | examples/good/{terraform-module, k8s-deployment}.md, examples/bad/{terraform-unlocked-state, k8s-bare-pod-no-resources}.md, cross-links to devops/security/observability/data |
+| 5 | Final Review + Ship | docs | pending | Review passed, audit clean, milestone merged to main, tag v0.1.5 |
+
+## v0.2 Phase Tag Mapping
+
+Per branch-strategy.md, milestone `v0.2` tags run on the `v0.1.x` patch line:
+
+| Phase | Tag | Notes |
+|-------|-----|-------|
+| P0 | v0.1.0 | Pre-execution release |
+| P1 | v0.1.1 | Infrastructure as Code domain |
+| P2 | v0.1.2 | Kubernetes domain |
+| P3 | v0.1.3 | Matrix + review integration |
+| P4 | v0.1.4 | Examples + cross-links |
+| P5 | v0.1.5 | Final review + ship — **IS the v0.2 milestone release** |
+
+NFR milestone: no separate minor tag. The final patch (v0.1.5) IS the v0.2 deliverable.
+
+## v0.2 Ideation Outcome
+
+- 16 ideas generated (mechanical 9, backend-enriched 7)
+- 14 accepted (all in v0.2 scope; refined ATELIER-36..58, added ATELIER-59)
+- 2 deferred to v0.3 (GitOps/operators domain; ai-ml/i18n/compliance domains)
+- See `.ciagent/atelier/REQUIREMENTS.md` "v0.2 Ideation Log" for the full table
+
+## Future Milestones
+
+- **v0.3** (candidates from ideation): `domains/gitops-operators/` (ArgoCD, Flux), `domains/ai-ml/`, `domains/i18n/`, `domains/compliance/` per spec Part 6 and v0.2 deferred ideation.
+
 ## Success Criteria

 - [x] All 11 domains have first-principles.md
@@ -3,7 +3,7 @@
    {
      "slug": "atelier",
      "name": "Atelier",
-      "milestone": "v0.1",
+      "milestone": "v0.2",
      "status": "specify"
    }
  ],
@@ -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) |
@@ -0,0 +1,55 @@
+# Infrastructure as Code — First Principles
+
+## 1. The Principles
+
+### P1. Declarative Intent
+Describe the desired state, not the steps to reach it. The tool
+reconciles current → desired. Imperative scripts describe how;
+declarative config describes what.
+
+### P2. Idempotence
+Applying the same configuration twice yields the same result. A
+second `apply` with no changes is a no-op, not an error. Idempotence
+is what makes `plan` trustworthy.
+
+### P3. State is Truth
+The state file is the authoritative record of what the tool believes
+exists. Drift between state and reality is a bug to be reconciled,
+not tolerated. Lose state, lose the ability to reason about
+infrastructure.
+
+### P4. Plan Before Apply
+Preview every change before mutating real infrastructure. `plan` is
+the contract review; `apply` is the signature. No `apply` without a
+read `plan`. The plan is the rollback rehearsal.
+
+### P5. Version Everything
+Configuration, state, providers, and modules are all versioned and
+reproducible. A commit pins a complete, rebuildable world. Pin
+providers; pin module sources; never `latest`.
+
+### P6. Modules Compose
+Encapsulate repeatable patterns as versioned modules. Compose
+modules; do not copy them. A module is the unit of reuse, review,
+and versioning — the IaC expression of composition.
+
+### P7. Least Privilege Providers
+Provider credentials are scoped to the minimum needed for the
+declared resources. No account-wide admin keys in CI. One credential
+per environment, per boundary.
+
+### P8. Remote State with Locking
+State is stored remotely with locking. Local state is for a single
+developer on a throwaway sandbox. Concurrent `apply` without a lock
+is data corruption waiting to happen.
+
+### P9. Drift is Recoverable
+`plan` detects drift; `apply` reconciles it. Manual mutation of
+managed infrastructure is an incident, not a shortcut. Drift is
+expected; unreconciled drift is the bug.
+
+### P10. Secrets Never in Code
+Secrets come from providers, external secret stores, or environment
+variables — never hardcoded in HCL, never committed to the repo,
+never written to state in plaintext. State is a secret-bearing
+artifact; treat it accordingly.
@@ -0,0 +1,64 @@
+# Modules — Derived Rules
+
+> Derives from `domains/infrastructure-as-code/first-principles.md`. P6 (Modules Compose) lives here. Referenced by `terraform.md` and `opentofu.md`.
+
+## Why Modules (P6 Modules Compose)
+
+- A module is the unit of reuse, review, and versioning in IaC. It encapsulates a repeatable pattern behind a typed interface.
+- Composition — building large from small — is the IaC expression of core C6 Composability. Without modules, every stack is a one-off; with modules, a stack is an assembly of reviewed parts.
+- A good module has one job (a VPC, a database, a load balancer), a small typed surface, and no hidden side effects.
+
+## Module Structure (P1 Declarative Intent, C2 Clarity)
+
+- The conventional layout: `main.tf` (resources), `variables.tf` (inputs), `outputs.tf` (outputs), `versions.tf` (provider/version pins). A `README.md` is required for any published module.
+- Inputs are typed and validated: `variable "name" { type = string, description = "...", validation { ... } }`. The description is the contract.
+- Outputs are the module's interface to consumers. Mark sensitive outputs `sensitive = true`. Document non-obvious outputs in the description.
+- A module does not declare a provider configuration unless it owns the provider. Most modules declare only `required_providers` (the constraint) and let the consumer configure the provider.
+
+## Versioning (P5 Version Everything)
+
+- Modules are versioned. The registry expects SemVer tags (`v1.0.0`). A consumer pins to a version or a range (`~> 1.0`).
+- A breaking change bumps the major. An additive change bumps the minor. A fix bumps the patch. No silent breaking changes within a minor.
+- Tag the module repo; the tag IS the version. Never `source = "git::...?ref=main"` in prod — unversioned modules drift.
+
+## Source Patterns (P5 Version Everything)
+
+| Source | When | Risk |
+|--------|------|------|
+| Registry (`<ns>/<name>/<provider>`) | Public, versioned, signed | Verify the publisher; pin the version |
+| Git (`git::https://...?ref=v1.0.0`) | Private modules across repos | Pin to a tag, not a branch |
+| Local (`./modules/networking`) | Monorepo, single repo | Re-reviewed on every change; no independent version |
+| Inline (no module) | Trivial one-off | Becomes a copy-paste anti-pattern at scale |
+
+- Local modules in a monorepo are fine — they trade independent versioning for co-evolution. The boundary is the review unit: if the module and the consumer always change together, local is correct.
+- Cross-repo modules must be versioned via git tags; unversioned cross-repo modules are the worst case (drift without a version to pin).
+
+## The Module-vs-Copy Boundary (P6 Modules Compose)
+
+- If a block is used more than once, it is a module. If it is used once and will never be reused, inline is acceptable.
+- If two copies differ in one attribute, that is a module with a variable, not two copies. The variable is the difference; the shared body is the module.
+- If you find yourself copy-pasting a block and editing it, stop. The edit is a variable. The copy is a module call.
+- A module that has grown to do many jobs should be split. A module with 20 variables is two modules.
+
+## Composition (P6 Modules Compose, C6 Composability)
+
+- Compose by calling modules from a root configuration: `module "vpc" { source = "...", version = "..." }`. The root is the assembly; the modules are the parts.
+- Outputs of one module feed inputs of another: `module "app" { vpc_id = module.vpc.vpc_id }`. This is the composition edge.
+- Avoid hidden coupling: a module should not reach into another module's state. If two modules must share state, promote the shared concern to the root or a parent module.
+
+## Reviewing Modules (P4 Plan Before Apply)
+
+- A module is reviewed once, at its version. Consumers trust the version pin. A module change requires a new version and a review of the diff.
+- When a module changes, every consumer that bumps the version gets the change. Treat a module version bump as a real change: review the module diff, run the consumer's `plan`.
+- A module with a breaking change must not auto-bump in consumers. Pin consumers to the old major until they explicitly migrate.
+
+## What Violates Module Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| Copy-pasted block with a one-line difference | P6 Modules Compose |
+| `source = "git::...?ref=main"` in prod | P5 Version Everything |
+| Module with 20 variables | P6 Modules Compose (split it) |
+| Silent breaking change within a minor | P5 Version Everything |
+| Module reaching into another module's state | C6 Composability, P1 Declarative Intent |
+| Unpublished module with no README | C2 Clarity |
@@ -0,0 +1,50 @@
+# OpenTofu — Derived Rules
+
+> Derives from `domains/infrastructure-as-code/first-principles.md`. OpenTofu is the open-source fork of Terraform; this doc covers fork-specific governance, license, and migration. The shared HCL/state/module model is documented in `terraform.md`. See also `state.md` and `modules.md`.
+
+## Fork Lineage (P5 Version Everything)
+
+- OpenTofu is a 2023 fork of Terraform, created when HashiCorp switched Terraform from MPL-2.0 to the Business Source License (BUSL), which is not open source.
+- OpenTofu is stewarded by the Linux Foundation under a genuinely open-source license. The fork's reason for existing is license neutrality.
+- Both tools implement the same HCL configuration language, the same provider protocol, and the same state model. Configuration written for one runs on the other at the fork point; divergence accrues slowly over time.
+
+## When to Choose OpenTofu (P7 Least Privilege Providers, supply-chain)
+
+- **License neutrality matters:** if your organization cannot accept BUSL's "competitive use" ambiguity, OpenTofu removes it.
+- **Supply-chain provenance:** Linux Foundation stewardship means no single vendor can relicense the tool out from under you.
+- **Community governance:** features and fixes are accepted on merit, not vendor strategy.
+- **When NOT to switch:** if you depend on HCP Terraform (HashiCorp's managed platform), BUSL-licensed providers, or provider features that have diverged since the fork, stay on Terraform. The decision is supply-chain, not syntax.
+
+## CLI Parity (P1 Declarative Intent)
+
+- `tofu init`, `tofu plan`, `tofu apply`, `tofu destroy` mirror `terraform init/plan/apply/destroy`.
+- The lock file (`.terraform.lock.hcl` → `.tofu.lock.hcl`) is committed; it makes `init` reproducible.
+- Workspaces, state backends, and module sources behave as in Terraform — see `terraform.md` and `state.md`.
+
+## Registry Parity (P6 Modules Compose)
+
+- OpenTofu can consume the Terraform Registry and the OpenTofu Registry. Module version pinning works identically.
+- Some providers have BUSL licenses that OpenTofu cannot ship; verify a provider's license before adopting it. An MPL or Apache provider is portable; a BUSL provider is not.
+- See `modules.md` for module structure, which is unchanged from Terraform.
+
+## Migration from Terraform (P5 Version Everything, P9 Drift is Recoverable)
+
+- `terraform state pull > state.json` → `tofu state push state.json` carries state across. Validate with `tofu plan` after the push — the plan should be empty.
+- Rename the binary in CI: replace `terraform` with `tofu` in scripts. The lock file may need regeneration.
+- Migrate one workspace at a time. Do not big-bang a migration; rehearse on a non-prod workspace first (P4 Plan Before Apply applies to the migration itself).
+- Pin the OpenTofu version in CI. A migration is a versioned, reviewed change, not a quiet swap.
+
+## Governance and Community (cross-link `domains/security/supply-chain.md`)
+
+- OpenTofu's governance model — impartial, community-driven, layered, modular, backwards-compatible — is itself a supply-chain principle. A tool you cannot trust to remain open is a tool you cannot build on.
+- This is the OpenTofu angle on `security/supply-chain.md`: license is a supply-chain property, not a legal footnote.
+
+## What Violates OpenTofu Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| Assuming OpenTofu == latest Terraform (unverified parity) | P5 Version Everything |
+| Migrating prod state without a non-prod rehearsal | P4 Plan Before Apply |
+| Adopting a BUSL-licensed provider into OpenTofu CI | P7 Least Privilege Providers, supply-chain |
+| Quiet swap of `terraform` for `tofu` without a versioned change | P5 Version Everything |
+| Losing state during migration | P3 State is Truth |
@@ -0,0 +1,77 @@
+# State — Derived Rules
+
+> Derives from `domains/infrastructure-as-code/first-principles.md`. State is the cross-cutting IaC concern: P3 (State is Truth) and P8 (Remote State with Locking) live here. Referenced by `terraform.md` and `opentofu.md`.
+
+## Why State Matters (P3 State is Truth)
+
+- The state file is the tool's memory. It records every resource it has claimed, every attribute it has set, and every dependency it has inferred.
+- Without state, `plan` cannot compute a diff — it would have nothing to diff against. Lose state, lose the ability to reason about infrastructure safely.
+- State can contain plaintext secrets (any sensitive resource attribute). Treat state as a secret-bearing artifact: encrypt at rest, restrict access, never commit it.
+
+## Remote State is Mandatory (P8 Remote State with Locking)
+
+- Local state (`terraform.tfstate` on disk) is acceptable only for a single developer on a throwaway sandbox. Any shared or production environment uses a remote backend.
+- A remote backend provides: durability (state survives workstation loss), shared access (team members and CI read the same state), and locking (concurrent `apply` is serialized).
+- No locking = data corruption. Two `apply` runs against the same unlocked state race; the loser's changes are silently overwritten.
+
+## Backend Comparison (P8, C4 Locality)
+
+| Backend | Locking | Encryption | Best for | Notes |
+|---------|---------|------------|----------|-------|
+| S3 + DynamoDB | DynamoDB | SSE-KMS | AWS-hosted | The canonical AWS backend; DynamoDB provides the lock |
+| GCS | Built-in | CMEK | GCP-hosted | Native locking via GCS object versioning |
+| Azure Blob | Lease | Customer key | Azure-hosted | Lease-based locking |
+| HTTP (remote) | Server-side | Server-side | Self-hosted / on-prem | Requires a backend server (e.g., `terraform-backend`) |
+| Local | None | None | Single-dev sandbox | Never for shared or prod |
+| Consul | KV lock | — | Consul shops | Locking via Consul sessions |
+| Postgres | TX | DB encryption | DBA-owned infra | Row-level locking |
+
+- Pick one backend per environment family. Mixing backends across environments fragments operational knowledge (C4 Locality).
+- The backend config is part of the configuration, not a runtime secret. Credentials for the backend are runtime secrets.
+
+## State Isolation per Environment (P4 Plan Before Apply, C4 Locality)
+
+- One state per environment. Never share a single state file across dev, staging, and prod. A `plan` against a shared state crosses environment boundaries — a prod change could appear in a dev plan.
+- Isolation patterns: separate workspaces, separate state keys in the same backend, or separate backends entirely. Stricter isolation = safer (separate backends for prod vs non-prod).
+- Name state keys by environment and stack: `env:/prod/Networking`, not `prod` or `state`.
+
+## Locking Discipline (P8 Remote State with Locking)
+
+- `terraform force-unlock` is for a stuck lock after a crashed run, not for impatience. Verify the run is actually dead before forcing.
+- A forced unlock without verifying the other run is dead causes the corruption the lock prevents.
+- In CI, set a lock timeout so a wedged job fails rather than hanging.
+
+## Sensitive Values in State (P10 Secrets Never in Code)
+
+- Any `sensitive = true` attribute is hidden from plan output but stored in state in plaintext (unless the provider encrypts it).
+- Backends with at-rest encryption (S3 SSE-KMS, GCS CMEK) protect state at rest. Access to the state file itself is the boundary.
+- Never log, print, or commit state. Never pipe `terraform show` to a public channel.
+
+## State Commands (P3 State is Truth)
+
+- `terraform state list` — enumerate resources in state. First step of any state investigation.
+- `terraform state show <addr>` — inspect one resource's recorded attributes.
+- `terraform state mv` — rename a resource's address without destroying and recreating it. Use when refactoring module structure.
+- `terraform state rm` — stop managing a resource without destroying it. Use when handing a resource to another configuration.
+- `terraform state pull` / `push` — export and import state. Used in migrations (see `opentofu.md`).
+- `terraform import` — bring an existing resource under management by recording its state. The resource must already exist; `import` does not create.
+- All `state` subcommands except `list` and `show` mutate state. Treat them as changes: review the intent, run in CI where possible, and commit the resulting config change that justifies the state move.
+
+## Drift and Reconciliation (P9 Drift is Recoverable)
+
+- `terraform plan` reports drift: resources that exist in state but were changed out-of-band, or resources in state that no longer exist in the provider.
+- `terraform apply` reconciles drift by bringing reality back to the declared state.
+- Manual changes to managed resources are the cause of drift. Treat a drift report as an incident: find who made the manual change and why, then close the access path or the gap that allowed it.
+- `terraform plan -refresh=false` skips drift detection. Use only when you know state is current and you want a fast plan; never use it to hide drift.
+
+## What Violates State Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| Committed `terraform.tfstate` | P3 State is Truth, P10 Secrets |
+| Local state in prod | P8 Remote State with Locking |
+| `force-unlock` without verifying the dead run | P8 Remote State with Locking |
+| Shared state across environments | P4 Plan Before Apply, C4 Locality |
+| Unnamed state keys (`env:/prod`) | C4 Locality |
+| Manual change to a managed resource | P9 Drift is Recoverable |
+| `state rm` to "fix" a stuck resource | P3 State is Truth |
@@ -0,0 +1,58 @@
+# Terraform — Derived Rules
+
+> Derives from `domains/infrastructure-as-code/first-principles.md`. Applies P1–P10 to Terraform specifically. See also `opentofu.md` (the open-source fork), `state.md`, and `modules.md`.
+
+## HCL Structure (P1 Declarative Intent)
+
+- Resources are declared, not scripted. A resource block states what should exist; Terraform reconciles it.
+- `resource "aws_s3_bucket" "logs" { ... }` — the type and name are the identity; the body is the desired state.
+- Data sources read existing state without claiming ownership: `data "aws_caller_identity" "current" {}`.
+- Variables are the input contract; outputs are the interface to consumers. Both are typed.
+
+## Providers (P5 Version Everything, P7 Least Privilege)
+
+- Pin the provider version: `required_providers { aws = { source = "hashicorp/aws", version = "~> 5.0" } }`.
+- A provider block configures credentials and region. Credentials come from environment, files, or a secrets manager — never inline.
+- One credential set per environment. Do not reuse a prod credential in a dev workspace.
+
+## The Core Workflow (P4 Plan Before Apply)
+
+- `terraform init` — resolve providers and modules. Reproducible from the lock file (`.terraform.lock.hcl`), which is committed.
+- `terraform plan` — preview the diff. Read it. Every line. The plan is the contract review.
+- `terraform apply` — execute the plan. Requires a reviewed plan in CI; in interactive use, requires typing `yes`.
+- `terraform destroy` — tear down. Treat `destroy` as a first-class operation with its own plan review; prod destroys are a change event, not a keystroke.
+
+## Workspaces (P4 Locality of Environments)
+
+- Workspaces separate state for the same configuration across environments (dev, staging, prod).
+- Do not use workspaces to separate unrelated stacks — use separate configurations. A workspace is an environment axis, not a project axis.
+- State is isolated per workspace (see `state.md`).
+
+## State Backends (P3 State is Truth, P8 Remote State with Locking)
+
+- Remote state is mandatory for any shared or production environment. See `state.md` for backend selection and locking.
+- Never commit `terraform.tfstate` to the repo. It is a secret-bearing artifact and a source of drift.
+- `terraform state` subcommands inspect and manipulate state directly — use sparingly, only for recovery.
+
+## Registry and Modules (P6 Modules Compose)
+
+- The Terraform Registry hosts versioned, signed modules. Reference modules by version: `source = "terraform-aws-modules/vpc/aws"`, `version = "5.x"`.
+- Compose modules rather than copy-pasting blocks. A module is reviewed once and reused many times.
+- See `modules.md` for module structure, versioning, and the module-vs-copy boundary.
+
+## Secrets (P10 Secrets Never in Code)
+
+- Secrets via provider data sources (`aws_secretsmanager_secret_version`), environment variables, or a dedicated secrets provider. Never a literal string in a resource block.
+- State may contain plaintext secrets if a resource attribute is sensitive. Mark attributes `sensitive = true` to keep them out of plan output; use a backend that encrypts state at rest (see `state.md`).
+
+## What Violates Terraform Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| Unpinned provider (`source` without `version`) | P5 Version Everything |
+| `terraform apply` without a read `plan` | P4 Plan Before Apply |
+| Local state in a shared environment | P8 Remote State with Locking |
+| Hardcoded secret in HCL | P10 Secrets Never in Code |
+| Copy-pasted resource blocks instead of a module | P6 Modules Compose |
+| Manual change to a managed resource | P9 Drift is Recoverable |
+| Admin credentials in CI | P7 Least Privilege Providers |
@@ -0,0 +1,67 @@
+# Kubernetes — First Principles
+
+## 1. The Principles
+
+### P1. Declarative Desired State
+You declare the desired state; controllers reconcile current →
+desired. Imperative `kubectl` is for inspection and incident
+response, not for the steady state. The cluster's job is to make
+reality match the manifest.
+
+### P2. Pods are Mortal
+A pod is born, runs, and dies. Never assume its identity, its IP,
+or its lifetime. Use controllers (Deployment, StatefulSet,
+DaemonSet), not bare pods. A bare pod has no recovery, no
+scaling, no rollback.
+
+### P3. Labels Select
+Labels and selectors are the join mechanism of the platform —
+workloads to services, policies to workloads, workloads to nodes.
+Label by intent (`app`, `tier`, `env`), not by infrastructure
+(`node-3`, `ip-10.0.0.5`). Selectors compose; ad-hoc naming does
+not.
+
+### P4. Requests and Limits are Contracts
+Resource requests drive scheduling; limits drive quality of
+service. A workload with no requests is `BestEffort` — first
+evicted under pressure. A workload with no limits is unbounded.
+Specifying requests is not optional in production.
+
+### P5. Probes Drive Health
+Liveness, readiness, and startup probes are how the platform
+sees your workload. Without a readiness probe, traffic routes to
+a pod that is not ready. Without a liveness probe, a wedged
+container runs forever. The platform cannot heal what it cannot
+see.
+
+### P6. Namespaces Bound Blast Radius
+Namespaces are the unit of quota, RBAC, network policy, and
+cleanup. A namespace is the boundary of "this thing and all its
+parts." Default namespace is for nothing in production; every
+workload gets a named namespace sized to its blast radius.
+
+### P7. RBAC by Intent, Not Identity
+Bind roles to service accounts by the workload's purpose, not to
+user identities. Least privilege: the role grants the minimum
+the workload needs. `cluster-admin` is a smell, not a shortcut.
+Cross-link `domains/security/authorization.md`.
+
+### P8. Storage is Explicit
+Storage is ephemeral by default. Persistence requires a
+PVC, a StorageClass, and a reclaim policy decision. `emptyDir`
+for state that must survive is a bug. The choice of
+reclaim policy (`Retain`, `Delete`) is a data-safety decision,
+not a default.
+
+### P9. Config and Secrets are Separate
+ConfigMaps are non-sensitive configuration; Secrets are
+sensitive configuration. Both are injected at runtime, never
+baked into the image. A configuration change should not require
+a rebuild; a secret rotation should not require a redeploy of the
+image. Cross-link `domains/security/secrets.md`.
+
+### P10. Roll Forward, Roll Back
+Every Deployment has a rolling update strategy and a rollout
+history. A deploy is reversible: `kubectl rollout undo`. A deploy
+without a tested rollback is a prototype. Canary and blue-green
+are the k8s expression of `domains/devops/P5 Progressive Delivery`.
@@ -0,0 +1,68 @@
+# Helm — Derived Rules
+
+> Derives from `domains/kubernetes/first-principles.md`. Applies P1, P3, P6. For the Helm-vs-Kustomize decision, see the decision matrix at the end of this doc and in `kustomize.md`.
+
+## What Helm Is (P6 Modules Compose)
+
+- Helm is a package manager for Kubernetes. A chart is a versioned package of templated manifests. `helm install` renders the templates against `values.yaml` and applies the result.
+- A chart encapsulates a reusable deployment (an application, a database, a full stack). It is the k8s analogue of an IaC module — see `domains/infrastructure-as-code/modules.md`.
+- Charts live in registries (Helm registry via OCI, or the classic chart repos) and are versioned per SemVer.
+
+## Chart Structure (P1 Declarative Desired State, C2 Clarity)
+
+- `Chart.yaml` — metadata (name, version, appVersion, dependencies).
+- `values.yaml` — default inputs; the chart's public interface.
+- `templates/` — Go-templated manifests. `templates/_helpers.tpl` holds reusable template partials.
+- `values.schema.json` — optional schema for values, giving type checking on inputs. Use it for published charts.
+- A chart should have one logical purpose. A chart that deploys an app and a database and an ingress and an observability stack has too many jobs — split it.
+
+## Values (P5 Version Everything, C2 Clarity)
+
+- `values.yaml` holds defaults. Override per release: `helm install --set key=value` or `helm install -f my-values.yaml`.
+- Pin values files in git per environment. A release is reproducible from the chart version + the values file.
+- Sensitive values do not belong in `values.yaml`. Inject via Secrets (see `rbac.md` P9 and `domains/security/secrets.md`). Some charts accept `existingSecret` to reference a pre-created Secret.
+
+## Release Management (P5 Version Everything, P10 Roll Forward Roll Back)
+
+- A release is a named instantiation of a chart. `helm upgrade` applies a new chart version or new values. `helm rollback` reverts to the previous release revision.
+- `helm history <release>` lists revisions; `helm rollback <release> <revision>` is the rollback. The rollback must be tested like any deploy (P10).
+- Pin the chart version: `helm install --version 1.2.3`. Never `--version latest` in production — unversioned charts drift (same anti-pattern as unpinned IaC modules).
+
+## Templating Discipline (P1 Declarative Desired State, C2 Clarity)
+
+- Templates render to valid manifests. The chart author's job is that the rendered output is correct k8s, not that the template is clever.
+- Keep `templates/` readable. Heavy logic belongs in `_helpers.tpl` or in a values structure that the template merely projects.
+- `helm template` renders to stdout without applying — use it to review what a release will create before installing it.
+
+## Registries (P5 Version Everything)
+
+- OCI registries are the modern chart distribution (same registry as container images, charts as OCI artifacts). Classic chart repos are legacy.
+- Pull from a pinned registry reference: `oci://registry/chart:1.2.3`. The digest + tag is the version.
+
+## Helm vs Kustomize — Decision Matrix (IDEATE-10)
+
+| Axis | Helm | Kustomize |
+|------|------|----------|
+| Mechanism | Templating (Go templates) | Overlays (base + patches) |
+| Reuse unit | Chart (versioned package) | Base directory (kustomization.yaml) |
+| Distribution | Registry (OCI, chart repo) | Git (base dir in a repo) |
+| Values | `values.yaml` + overrides | `kustomization.yaml` + patches |
+| Release mgmt | `helm` tracks releases, history, rollback | None native — apply with `kubectl apply -k` |
+| Learning curve | Template language to learn | YAML patching, no DSL |
+| Blast radius | One chart, many resources, templated | One base, many overlays, patched |
+| Best for | Off-the-shelf apps, packaged stacks, multi-env via values | Internal apps, patching upstream manifests, env-specific deltas |
+| Watch out for | Template complexity, `latest` chart drift, secrets in values | No release tracking, manual rollback, patch sprawl |
+
+- Use Helm when you distribute a reusable app or consume third-party charts. Use Kustomize when you patch existing manifests or keep env deltas in one repo.
+- Mixing both is fine and common: Helm for the packaged parts, Kustomize for the last-mile per-env patching. Do not fight the tool that fits the job.
+
+## What Violates Helm Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| `helm install --version latest` in prod | P5 Version Everything |
+| Secrets in `values.yaml` | P9 Config and Secrets are Separate, security |
+| Chart with 15 subcharts doing unrelated things | P6 Modules Compose (split it) |
+| No `values.schema.json` on a published chart | C2 Clarity |
+| `helm upgrade` without reviewing `helm template` output | P1 Declarative Desired State, P4 Plan Before Apply |
+| Untested `helm rollback` | P10 Roll Forward Roll Back |
@@ -0,0 +1,63 @@
+# Kustomize — Derived Rules
+
+> Derives from `domains/kubernetes/first-principles.md`. Applies P1, P3, P6. For the Helm-vs-Kustomize decision, see the decision matrix at the end of this doc and in `helm.md`.
+
+## What Kustomize Is (P1 Declarative Desired State)
+
+- Kustomize customizes manifests without templating. A base directory holds the canonical manifests; overlays hold the deltas. The result is plain YAML applied with `kubectl apply -k`.
+- No DSL, no template language, no rendering step hidden from `kubectl`. The patch is a YAML file; the result is inspectable.
+- Kustomize is built into `kubectl` (`kubectl apply -k`, `kubectl diff -k`). No separate runtime is required to apply.
+
+## Base and Overlays (P6 Namespaces Bound Blast Radius, C4 Locality)
+
+- A `kustomization.yaml` in a base directory lists the resources (Deployment, Service, etc.) the application needs. It is the canonical manifest.
+- An overlay is a directory with its own `kustomization.yaml` that references the base (`resources: - ../../base`) and applies patches or additional resources.
+- Typical structure: `base/`, `overlays/dev/`, `overlays/staging/`, `overlays/prod/`. The overlay is the environment axis; the base is the shared truth.
+
+## Patches (P1 Declarative Desired State, C2 Clarity)
+
+- Strategic merge patches — a YAML document that overrides matching fields. Simple for single-resource changes.
+- JSON patches (RFC 6902) — precise operations (`add`, `replace`, `remove`) on a path. Use when a strategic merge is ambiguous (e.g., list operations).
+- `patches` field (modern) takes a list of patch files with targets, replacing the older `patchesStrategicMerge` and `patchesJson6902`. Prefer it.
+- A patch is a delta. It is reviewed as "what changes from base," which is exactly the diff a reviewer wants to see.
+
+## Generators and Transformers (P3 Labels Select)
+
+- `configMapGenerator` and `secretGenerator` create ConfigMaps and Secrets from files or literals, with content hashes in the names. A change to the source file changes the hash, which changes the name, which rolls the workload. This is the kustomize pattern for "config change = redeploy."
+- `namePrefix`, `nameSuffix`, and `namespace` transformers rewrite names across the base. Use for namespace isolation (P6) or to run the same base multiple times in one cluster without collisions.
+- `commonLabels` and `commonAnnotations` stamp labels onto everything in the base — the kustomize-native way to enforce the labelling discipline of P3.
+
+## No Release Tracking (P10 Roll Forward Roll Back)
+
+- Kustomize has no release object, no history, no built-in rollback. `kubectl apply -k` is a one-shot apply; the previous state is in git, not in a Helm-style release record.
+- Rollback is `git revert` + `kubectl apply -k`. The git history IS the release history. This is fine — and arguably cleaner — but it means rollback is a git operation, not a `helm rollback` command.
+- Use a GitOps tool (ArgoCD, Flux) on top of Kustomize for automated reconciliation and rollback tracking. The tool watches the git ref; rollback is a git revert.
+
+## Helm vs Kustomize — Decision Matrix (IDEATE-10)
+
+| Axis | Kustomize | Helm |
+|------|----------|------|
+| Mechanism | Overlays (base + patches) | Templating (Go templates) |
+| Reuse unit | Base directory (kustomization.yaml) | Chart (versioned package) |
+| Distribution | Git (base dir in a repo) | Registry (OCI, chart repo) |
+| Values | `kustomization.yaml` + patches | `values.yaml` + overrides |
+| Release mgmt | None native — `kubectl apply -k` | `helm` tracks releases, history, rollback |
+| Learning curve | YAML patching, no DSL | Template language to learn |
+| Blast radius | One base, many overlays, patched | One chart, many resources, templated |
+| Best for | Internal apps, patching upstream manifests, env-specific deltas | Off-the-shelf apps, packaged stacks, multi-env via values |
+| Watch out for | No release tracking, manual rollback, patch sprawl | Template complexity, `latest` chart drift, secrets in values |
+
+- Use Kustomize when you patch existing manifests or keep env deltas in one repo. Use Helm when you distribute a reusable app or consume third-party charts.
+- Mixing both is fine and common: Kustomize for the internal apps, Helm for the packaged parts. The decision is per-workload, not per-cluster.
+- `commonLabels` is the kustomize-native enforcement of P3 (Labels Select); see `domains/devops/first-principles.md` P6 (Configuration as Code) for the upstream principle that the rendered manifest — not a console click — is the source of truth.
+
+## What Violates Kustomize Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| Duplicated base instead of an overlay | P6 Modules Compose (use an overlay) |
+| Patch that overrides most of the base | C3 Simplicity (the base is wrong — fix the base) |
+| No `commonLabels` on a multi-team base | P3 Labels Select |
+| No git-based rollback strategy | P10 Roll Forward Roll Back |
+| Hand-edited rendered output instead of `apply -k` | P1 Declarative Desired State |
+| Patch sprawl (10 overlays each patching 15 fields) | C3 Simplicity (refactor the base) |
@@ -0,0 +1,48 @@
+# Networking — Derived Rules
+
+> Derives from `domains/kubernetes/first-principles.md`. Covers Service, Ingress, Gateway API, EndpointSlices, NetworkPolicy, and DNS. Applies P1, P3, P6.
+
+## The Service (P3 Labels Select)
+
+- A Service routes traffic to pods selected by a label selector. The selector is the join between the network abstraction and the workloads.
+- Service types: `ClusterIP` (in-cluster only, default), `NodePort` (exposed on every node's IP at a fixed port), `LoadBalancer` (cloud-managed LB points to the Service). Default to `ClusterIP`; expose only what must be exposed.
+- A Service fronts a Deployment (or other controller), never a bare pod. The controller keeps pods available; the Service routes to whichever are ready (per the readiness probe — see `workloads.md`).
+
+## EndpointSlices (P3 Labels Select, P5 Probes Drive Health)
+
+- An EndpointSlice lists the pod IPs currently backing a Service. Only pods passing their readiness probe appear.
+- The Service routes by EndpointSlice, not by selector directly. A pod with the right labels but a failed readiness probe is not in the Service.
+
+## Ingress and Gateway API (P6 Namespaces Bound Blast Radius)
+
+- Ingress routes HTTP/HTTPS traffic from outside the cluster to Services. It is L7 routing by host and path.
+- Gateway API is the successor to Ingress: more expressive (TCP, UDP, TLS passthrough), role-oriented (GatewayClass → Gateway → Route), and cross-platform. Prefer Gateway API for new L7 needs.
+- Both Ingress and Gateway API are implemented by a controller (nginx-ingress, Traefik, Istio, Envoy Gateway). Pick one; mixing ingress controllers in a cluster is operational debt.
+
+## NetworkPolicy (P6 Namespaces Bound Blast Radius, P7 RBAC by Intent)
+
+- A NetworkPolicy is a firewall rule for pods. Default-deny ingress; allow by namespace and pod selector.
+- Without a default-deny NetworkPolicy, every pod can reach every other pod. In production, default-deny is the baseline; allows are the exceptions.
+- NetworkPolicy is enforced by the CNI plugin (Calico, Cilium, etc.). A NetworkPolicy with no supporting CNI is a no-op. Verify the CNI enforces before relying on it.
+
+## DNS (P3 Labels Select)
+
+- Every Service gets a DNS record: `<service>.<namespace>.svc.cluster.local`. Pods get `pod-ip-address.<namespace>.pod.cluster.local` (with dots replaced).
+- Headless Services (`clusterIP: None`) resolve directly to pod IPs — use for StatefulSet peer discovery (`<statefulset>-0.<service>`).
+- DNS is how workloads find each other without hardcoded IPs. Use the DNS name, not the ClusterIP.
+
+## Dual-Stack (P4 Locality)
+
+- IPv4/IPv6 dual-stack is opt-in per cluster. Services can be single-stack or dual-stack per Service.
+- Decide at cluster creation. Migrating a single-stack cluster to dual-stack is disruptive and rarely worth it.
+
+## What Violates Networking Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| `LoadBalancer` on an internal-only Service | P6 Namespaces Bound Blast Radius |
+| No default-deny NetworkPolicy | P6 Namespaces Bound Blast Radius, P7 RBAC by Intent |
+| Hardcoded pod IP in config | P3 Labels Select (use DNS) |
+| Service pointing at a bare pod | P3 Labels Select (point at a controller) |
+| Multiple ingress controllers in one cluster | C3 Simplicity (operational debt) |
+| No readiness probe on a Service-backed workload | P5 Probes Drive Health (empty EndpointSlices) |
@@ -0,0 +1,45 @@
+# RBAC and Pod Security — Derived Rules
+
+> Derives from `domains/kubernetes/first-principles.md`. P7 (RBAC by Intent, Not Identity) lives here. Cross-link `domains/security/authorization.md` for the general authorization principles and `domains/security/secrets.md` for secret handling.
+
+## RBAC Objects (P7 RBAC by Intent, Not Identity)
+
+- **Role** — permissions within a namespace (verb on resource). **ClusterRole** — permissions cluster-wide or usable across namespaces.
+- **RoleBinding** — binds a Role to a subject (ServiceAccount, User, Group) within a namespace. **ClusterRoleBinding** — binds a ClusterRole cluster-wide.
+- Prefer Role + RoleBinding per namespace over ClusterRole + ClusterRoleBinding. Cluster-level is the broad axe; namespace-level is the scalpel.
+
+## Bind to Service Accounts, Not Users (P7 RBAC by Intent, Not Identity)
+
+- A workload authenticates as a ServiceAccount. Bind the Role to the ServiceAccount, scoped to the workload's namespace.
+- The Role encodes the workload's intent: "this workload reads ConfigMaps in this namespace." Not "this user is an admin."
+- One ServiceAccount per workload (or workload family). Do not reuse the `default` ServiceAccount for production workloads; it is a shared identity.
+
+## Least Privilege (P7 RBAC by Intent, C1 Correctness via security)
+
+- Grant the minimum verbs on the minimum resources. `get, list, watch` on `pods` is fine for a monitoring sidecar; `*` on `*` is not.
+- `cluster-admin` is a smell. If a workload "needs" `cluster-admin`, the workload is either doing something it should not, or it is a cluster operator that should be reviewed as such.
+- Audit `ClusterRoleBindings` regularly. They are the broadest grant in the system and the easiest to leave behind.
+
+## Pod Security Standards and Admission (P7 RBAC by Intent, security)
+
+- Pod Security Standards (PSS) define three profiles: `privileged` (unrestricted), `baseline` (some restrictions), `restricted` (hardened).
+- Pod Security Admission (built-in) enforces a PSS profile per namespace via labels: `pod-security.kubernetes.io/enforce: restricted`. It replaces the deprecated PodSecurityPolicy.
+- Map namespaces to profiles: `restricted` for prod workloads, `baseline` for most, `privileged` only for system add-ons (CNI, CSI, node agents) that need it. A workload in `privileged` is a security event, not a default.
+
+## Service Accounts and Token Automation (P9 Config and Secrets are Separate)
+
+- ServiceAccount tokens are auto-mounted into pods unless `automountServiceAccountToken: false`. For workloads that do not call the API, disable auto-mount.
+- Long-lived ServiceAccount tokens are deprecated. Use projected tokens (bound to the pod, time-limited) via `TokenRequest`.
+- A workload that does not need API access should not have a token. A workload that needs API access should have a Role scoped to its intent.
+
+## What Violates RBAC Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| `cluster-admin` bound to a workload | P7 RBAC by Intent, Not Identity |
+| Reused `default` ServiceAccount for prod | P7 RBAC by Intent, Not Identity |
+| `automountServiceAccountToken: true` on a non-API workload | P9 Config and Secrets are Separate |
+| `privileged` PSS on an application namespace | P7 RBAC by Intent, security |
+| ClusterRoleBinding where a RoleBinding would suffice | P6 Namespaces Bound Blast Radius, P7 |
+| Long-lived static token instead of projected | P9 Config and Secrets are Separate |
+| Leftover ClusterRoleBindings after a workload is removed | P7 RBAC by Intent (audit) |
@@ -0,0 +1,59 @@
+# Storage — Derived Rules
+
+> Derives from `domains/kubernetes/first-principles.md`. P8 (Storage is Explicit) lives here. Covers Volumes, PV/PVC, StorageClass, CSI, snapshots, and reclaim policies. Cross-link `domains/data/` for the data-model angle.
+
+## Ephemeral by Default (P8 Storage is Explicit)
+
+- A container's filesystem is ephemeral. When the pod dies, the filesystem dies with it. This is the design, not a flaw.
+- `emptyDir` is an ephemeral volume scoped to the pod's lifetime (survives container restarts within the pod, dies with the pod). It is scratch space, never durable storage.
+- Any data that must survive a pod restart requires a PersistentVolumeClaim (PVC). The choice of "must survive" is the data-safety decision at the heart of P8.
+
+## PersistentVolume and PersistentVolumeClaim (P8 Storage is Explicit)
+
+- A PersistentVolume (PV) is a piece of storage in the cluster. A PersistentVolumeClaim (PVC) is a request for that storage by a workload.
+- The PV is the resource; the PVC is the consumer. A workload mounts the PVC, not the PV directly.
+- For StatefulSets, use `volumeClaimTemplates` so each replica gets its own PVC with a stable name (`data-<statefulset>-0`). Do not share one PVC across replicas of a stateful workload.
+
+## StorageClass and Dynamic Provisioning (P8 Storage is Explicit, P5 Version Everything)
+
+- A StorageClass describes the "flavour" of storage (e.g., `fast-ssd`, `cold-hdd`, `encrypted`). A PVC names a StorageClass or gets the cluster default.
+- Dynamic provisioning creates the PV on demand when the PVC is created, via the CSI driver. Manual PV creation is for specific cases (a pre-existing disk, a static NFS export).
+- Mark a default StorageClass only if the default is safe for all workloads. A fast-but-expensive default can cause cost surprises; a slow default can cause performance surprises.
+
+## CSI (P5 Version Everything)
+
+- The Container Storage Interface (CSI) is the standard driver interface. Each storage backend ships a CSI driver. Pin the CSI driver version in the cluster; treat it as infrastructure.
+- CSI enables features beyond mount/unmount: snapshots, cloning, volume expansion, and topology-aware provisioning. Not all drivers implement all features; verify before relying.
+
+## Volume Snapshots (P5 Reversibility, P8 Storage is Explicit)
+
+- A VolumeSnapshot is a point-in-time copy of a PVC, taken by the CSI driver. Restore creates a new PVC from the snapshot.
+- Snapshots are not backups. They are local to the storage backend and may share blocks with the source. An off-cluster backup is still required for disaster recovery.
+- Snapshot scheduling is a workload concern (use a CronJob or a tool like Velero), not a k8s-native feature.
+
+## Reclaim Policies (P8 Storage is Explicit, P5 Reversibility)
+
+| Policy | On PVC delete | When |
+|--------|---------------|------|
+| `Retain` | PV and its data persist; PV must be manually reclaimed | Production, data-safety default |
+| `Delete` | PV and the underlying storage are deleted | Ephemeral, dev, scratch |
+| `Recycle` (deprecated) | PV scrubbed and made available again | Do not use — use dynamic provisioning |
+
+- The reclaim policy is a data-safety decision. `Delete` on a production PVC is a footgun: deleting the PVC destroys the data. Default to `Retain` for prod, `Delete` for dev.
+- For StatefulSet PVCs, the reclaim policy on the StorageClass governs what happens when the PVC is deleted (which happens when the StatefulSet is scaled down or deleted, depending on the policy).
+
+## Ephemeral Volumes (P8 Storage is Explicit)
+
+- `configMap`, `secret`, `downwardAPI` volumes are read-only (by default) projections injected at pod start. They are configuration, not storage.
+- `emptyDir` with `medium: Memory` is a tmpfs — fast, ephemeral, memory-charged. Use for scratch that must be fast and never persist.
+
+## What Violates Storage Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| `emptyDir` for data that must survive pod restart | P8 Storage is Explicit |
+| Shared PVC across StatefulSet replicas | P8 Storage is Explicit (use `volumeClaimTemplates`) |
+| `Delete` reclaim policy on production storage | P8 Storage is Explicit, P5 Reversibility |
+| Snapshot treated as a backup | P5 Reversibility (snapshots are local, not DR) |
+| No default StorageClass decision (accidental default) | P8 Storage is Explicit |
+| Manual PV creation when dynamic provisioning exists | C3 Simplicity |
@@ -0,0 +1,53 @@
+# Workloads — Derived Rules
+
+> Derives from `domains/kubernetes/first-principles.md`. Covers Pod, ReplicaSet, Deployment, StatefulSet, DaemonSet, Job, and CronJob. Applies P1–P10.
+
+## The Pod (P2 Pods are Mortal)
+
+- A pod is the smallest deployable unit: one or more containers sharing network and storage namespaces.
+- Never deploy a bare pod. A bare pod has no controller to restart, scale, or replace it. Use a controller.
+- Pods are replaceable by design. Do not store state in a pod's filesystem (`emptyDir` is scratch, not storage — see `storage.md`).
+
+## Controllers (P1 Declarative Desired State)
+
+| Controller | When | Identity | Ordering |
+|------------|------|----------|----------|
+| Deployment | Stateless workloads | None (pods interchangeable) | No ordering |
+| StatefulSet | Stateful workloads (databases, queues) | Stable name (`pod-0`, `pod-1`) + stable PVC | Ordered, sequential |
+| DaemonSet | One pod per node (logging, monitoring, CNI) | Per-node | — |
+| Job | Run to completion (batch) | — | — |
+| CronJob | Scheduled batch | — | — |
+
+- A Deployment manages a ReplicaSet, which manages pods. You interact with the Deployment; the ReplicaSet is an implementation detail except during rollouts.
+- StatefulSet gives stable network identity and stable persistent storage per replica. Use it when the workload needs a stable name or per-replica data (databases, distributed systems). Do not use StatefulSet for stateless workloads — the ordering is overhead.
+
+## Probes (P5 Probes Drive Health)
+
+- **Readiness probe** — is the pod ready to serve traffic? Failing readiness removes the pod from the Service's endpoints but does not restart it. Use for "warm-up" and transient unavailability.
+- **Liveness probe** — is the pod alive? Failing liveness restarts the container. Use for "wedged but running." Do not use liveness to check dependencies (it will cascade-restart on a dependency blip).
+- **Startup probe** — has the pod finished starting? Disables liveness/readiness until it succeeds. Use for slow-starting workloads so liveness does not kill them before they are ready.
+- Probes must check the workload's own health, not the health of its dependencies. A readiness probe that fails on a downstream outage causes the Service to drain all pods simultaneously.
+
+## Lifecycle and Disruption (P2 Pods are Mortal, P10 Roll Forward Roll Back)
+
+- `kubectl rollout status` watches a Deployment's rollout to completion. `kubectl rollout undo` reverts to the previous ReplicaSet.
+- PodDisruptionBudgets (PDBs) protect voluntary disruptions (node drain, cluster autoscaler). An involuntary disruption (node failure) ignores the PDB. Set a PDB on every workload that must keep a minimum available.
+- Rolling update strategy: `maxUnavailable` and `maxSurge` control the speed of rollout. Slow rollouts (low `maxSurge`) are safer; fast rollouts (high `maxUnavailable`) risk availability.
+
+## Resource Contracts (P4 Requests and Limits are Contracts)
+
+- Every container in production has a CPU request, a memory request, and a memory limit. CPU limits are optional but recommended to bound noisy neighbours.
+- QoS classes: `Guaranteed` (requests == limits), `Burstable` (requests < limits), `BestEffort` (no requests). `BestEffort` is first evicted under node pressure — never for prod.
+- A workload without requests is an unbounded gamble on the scheduler. Set them.
+
+## What Violates Workload Discipline
+
+| Violation | Principle |
+|-----------|-----------|
+| Bare pod (no controller) | P2 Pods are Mortal |
+| StatefulSet for a stateless workload | P1 Declarative Desired State (overhead) |
+| No probes | P5 Probes Drive Health |
+| Liveness probe checks a dependency | P5 Probes Drive Health |
+| No PDB on a critical workload | P10 Roll Forward Roll Back |
+| No resource requests in prod | P4 Requests and Limits are Contracts |
+| `emptyDir` for data that must persist | P8 Storage is Explicit |
@@ -0,0 +1,71 @@
+# Bad Example: Bare Pod, No Resources
+
+> A Kubernetes manifest that violates Atelier's Kubernetes principles. Each violation is cited.
+
+## The Code
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: api
+  namespace: default
+spec:
+  containers:
+    - name: api
+      image: api:latest          # :latest, unversioned
+      ports:
+        - containerPort: 8080
+      env:
+        - name: DATABASE_URL
+          value: "postgres://admin:hunter2@db:5432/app"   # secret in plaintext, in the manifest
+```
+
+The team applies it with `kubectl apply -f api-pod.yaml`. When the pod crashes, they `kubectl delete pod api && kubectl apply -f api-pod.yaml` to "restart" it. There are no probes, no resource requests, no RBAC, no NetworkPolicy.
+
+## What Makes It Bad
+
+### Bare Pod, No Controller (k8s P2 Pods are Mortal)
+- A `kind: Pod` with no controller. When the node dies, the pod does not come back. When the team needs three replicas, they copy the YAML twice and rename it.
+- The "restart" workflow (`delete pod && apply`) is manual recovery — exactly the manual-mutation anti-pattern from `domains/devops/`.
+- **Fix:** use a `Deployment`. The controller replaces dead pods, scales, and rolls back. See `domains/kubernetes/workloads.md`.
+
+### No Resource Requests (k8s P4 Requests and Limits are Contracts)
+- The container has no `resources.requests` or `resources.limits`. It is `BestEffort` — first evicted under node pressure. The scheduler has no signal to place it well; it lands wherever there is room, then gets killed when the node is full.
+- A workload without requests is an unbounded gamble on the scheduler.
+- **Fix:** set CPU and memory requests on every prod container; set a memory limit; consider a CPU limit. See `domains/kubernetes/workloads.md`.
+
+### No Probes (k8s P5 Probes Drive Health)
+- No `readinessProbe` — the Service routes traffic to the pod before it is ready. Users see 502s during startup.
+- No `livenessProbe` — a wedged container runs forever; no one notices until the outage.
+- The platform cannot heal what it cannot see. A pod without probes is invisible to the controller's reconciliation.
+- **Fix:** define readiness and liveness probes that check the workload's own health. See `domains/kubernetes/workloads.md`.
+
+### `:latest` Image Tag (k8s P1 + IaC P5 Version Everything)
+- `image: api:latest` is unversioned. Every `kubectl apply` pulls whatever is newest at that moment. Two pods "running the same manifest" run different images if `latest` moved between applies.
+- Rollback is impossible — there is no version to roll back to.
+- **Fix:** pin the image to a version or a digest: `image: registry.example.com/api:v1.4.2` or `image: registry.example.com/api@sha256:...`. See `domains/kubernetes/workloads.md` and `domains/infrastructure-as-code/terraform.md` (P5 Version Everything).
+
+### Secret in Plaintext in the Manifest (k8s P9 Config and Secrets are Separate, IaC P10)
+- `DATABASE_URL` with the password is in the manifest in plaintext. If the manifest is committed (it is), the secret is in git.
+- Rotating the secret requires editing the manifest and re-applying — no separation of config from secret.
+- **Fix:** put the URL in a `Secret` (created out-of-band or via a secrets tool) and reference it with `valueFrom.secretKeyRef`. The manifest contains the reference, not the value. See `domains/kubernetes/rbac.md` and `domains/security/secrets.md`.
+
+### `default` Namespace (k8s P6 Namespaces Bound Blast Radius)
+- The pod runs in `default`. There is no namespace boundary for quota, RBAC, or NetworkPolicy. Every other workload in `default` can reach it; an outage in one affects the namespace all share.
+- **Fix:** give every prod workload a named namespace sized to its blast radius. `default` is for nothing in production. See `domains/kubernetes/networking.md` and `domains/kubernetes/workloads.md`.
+
+### No RBAC, No NetworkPolicy (k8s P7 RBAC by Intent, P6 Namespaces Bound Blast)
+- No `serviceAccountName` — the pod uses the `default` ServiceAccount, a shared identity.
+- No `NetworkPolicy` — every pod in the cluster can reach `api`. The network is flat by default.
+- **Fix:** a dedicated ServiceAccount with a least-privilege Role bound by intent. A default-deny NetworkPolicy with explicit allows. See `domains/kubernetes/rbac.md` and `domains/kubernetes/networking.md`.
+
+## The Cascade
+
+The violations compound. A bare pod with no probes crashes silently and is not restarted. `:latest` means the "restart" pulls a different image than the one that crashed. The plaintext secret in the manifest is now in git, so rotating it means editing the manifest and re-applying — and the new manifest still has no controller, so the next crash starts the manual loop again. `default` namespace means the blast radius is the whole cluster.
+
+## Cross-Domain Links
+
+- `domains/devops/P4 Rollback First` — with `:latest` and no controller, there is no rollback path.
+- `domains/security/authorization` — the shared `default` ServiceAccount and flat network are the k8s expression of zero-trust violation.
+- `domains/errors/P2 Fail Loudly` — a pod with no probes fails silently; the platform has no signal to act on.
@@ -0,0 +1,74 @@
+# Bad Example: Unlocked Local State
+
+> An IaC configuration that violates Atelier's Infrastructure as Code principles. Each violation is cited.
+
+## The Code
+
+```hcl
+# main.tf — committed to the repo
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      # no version pin
+    }
+  }
+}
+
+provider "aws" {
+  region     = "us-east-1"
+  access_key = "AKIAIOSFODNN7EXAMPLE"   # committed
+  secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"  # committed
+}
+
+resource "aws_s3_bucket" "logs" {
+  bucket = "app-logs-prod"
+}
+
+resource "aws_db_instance" "primary" {
+  identifier           = "app-prod"
+  username             = "admin"
+  password             = "hunter2"        # committed, in plaintext, in state
+  allocated_storage    = 20
+  engine               = "postgres"
+  instance_class       = "db.t3.micro"
+  skip_final_snapshot  = true
+}
+```
+
+The team runs `terraform apply` from their laptops. The state file `terraform.tfstate` is committed alongside `main.tf` "so everyone is on the same page."
+
+## What Makes It Bad
+
+### Local State in a Shared Environment (IaC P8 Remote State with Locking)
+- State is `terraform.tfstate` on each laptop. Two team members run `terraform apply` simultaneously; the second to finish silently overwrites the first's changes. There is no lock.
+- The state file is committed to the repo. It contains the DB password in plaintext. It is a secret-bearing artifact in version control.
+- **Fix:** use a remote backend with locking (S3 + DynamoDB, GCS, etc.). Never commit state. See `domains/infrastructure-as-code/state.md`.
+
+### Hardcoded Secrets (IaC P10 Secrets Never in Code)
+- `access_key` and `secret_key` are committed in `main.tf`. The DB `password` is committed and also written to state in plaintext.
+- The secrets are now in the git history. Rotating them is not optional; the history must be scrubbed or the credentials rotated and the old ones revoked.
+- **Fix:** credentials from environment, a secrets manager, or a `data` source (`aws_secretsmanager_secret_version`). Mark sensitive attributes `sensitive = true`. See `domains/security/secrets.md`.
+
+### Unpinned Provider (IaC P5 Version Everything)
+- The `aws` provider has no `version`. The next `terraform init` pulls whatever is latest — a different provider version can change resource behavior with no review.
+- **Fix:** pin `version = "~> 5.0"`. Commit the lock file (`.terraform.lock.hcl`). See `domains/infrastructure-as-code/terraform.md`.
+
+### Manual Drift, No Plan Review (IaC P4 Plan Before Apply, P9 Drift is Recoverable)
+- The team applies from laptops with no `plan` review. When the DB password is wrong, someone SSHes in and changes it manually — drift that `plan` will later report as a surprise.
+- Manual changes to managed resources are an incident, not a shortcut. Each one is a future `plan` diff that no one can explain.
+- **Fix:** run `terraform plan` in CI; review the diff; `apply` from CI on merge. Treat every drift report as an incident to investigate. See `domains/infrastructure-as-code/state.md` (Drift and Reconciliation).
+
+### No Module Composition (IaC P6 Modules Compose)
+- The S3 bucket and DB instance are inline. When the team needs a second bucket, they copy-paste the block and rename it. The two copies drift over time.
+- **Fix:** a versioned module for each reusable pattern. The difference is a variable, not a copy. See `domains/infrastructure-as-code/modules.md` (the module-vs-copy boundary).
+
+## The Cascade
+
+The violations compound. Unlocked local state lets two `apply` runs race. Committed secrets mean the race loser's changes — and the secrets — are in the repo. Manual drift hides the corruption until a `plan` surfaces a diff no one can explain. The unpinned provider means that diff might be the provider's fault, not the team's, and no one can tell which.
+
+## Cross-Domain Links
+
+- `domains/security/secrets.md` — secret hygiene is non-tradeable; this example violates it in three places.
+- `domains/security/supply-chain.md` — committed credentials in git are a supply-chain incident.
+- `domains/devops/P6 Configuration as Code` — config in the repo is correct; committed *state and secrets* is the violation.
@@ -0,0 +1,157 @@
+# Good Example: Kubernetes Deployment
+
+> A Kubernetes Deployment that follows Atelier's Kubernetes principles. Each aspect cites the principle it satisfies.
+
+## The Deployment
+
+A stateless web service deployed as a Deployment with probes, resource contracts, RBAC, and a rolling update strategy — the canonical "production workload" pattern.
+
+### Manifest
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+  namespace: api-prod
+  labels:
+    app: api
+    tier: web
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: api
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0
+  template:
+    metadata:
+      labels:
+        app: api
+        tier: web
+    spec:
+      serviceAccountName: api
+      automountServiceAccountToken: false
+      containers:
+        - name: api
+          image: registry.example.com/api:v1.4.2  # pinned, not :latest
+          ports:
+            - containerPort: 8080
+          resources:
+            requests:
+              cpu: 250m
+              memory: 256Mi
+            limits:
+              memory: 512Mi
+          readinessProbe:
+            httpGet:
+              path: /healthz/ready
+              port: 8080
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          livenessProbe:
+            httpGet:
+              path: /healthz/live
+              port: 8080
+            initialDelaySeconds: 15
+            periodSeconds: 10
+          env:
+            - name: LOG_LEVEL
+              valueFrom:
+                configMapKeyRef:
+                  name: api-config
+                  key: log_level
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef:
+                  name: api-secrets
+                  key: database_url
+          volumeMounts:
+            - name: config
+              mountPath: /etc/api
+              readOnly: true
+      volumes:
+        - name: config
+          configMap:
+            name: api-config
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: api
+  namespace: api-prod
+spec:
+  selector:
+    app: api
+  ports:
+    - port: 80
+      targetPort: 8080
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: api-deny-ingress
+  namespace: api-prod
+spec:
+  podSelector:
+    matchLabels:
+      app: api
+  policyTypes:
+    - Ingress
+  ingress:
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              tier: edge
+```
+
+## What Makes It Good
+
+### Controller, Not Bare Pod (k8s P2 Pods are Mortal)
+- A `Deployment` manages the pods. If one dies, the controller replaces it. A bare pod has no recovery.
+- See `domains/kubernetes/workloads.md`.
+
+### Resource Contracts (k8s P4 Requests and Limits are Contracts)
+- Every container has CPU and memory requests and a memory limit. The workload is `Burstable`, not `BestEffort` (first evicted under pressure).
+- See `domains/kubernetes/workloads.md` for QoS classes.
+
+### Probes (k8s P5 Probes Drive Health)
+- `readinessProbe` gates traffic: a pod that is not ready is removed from the Service's endpoints.
+- `livenessProbe` restarts a wedged container.
+- The probes check the workload's own health (`/healthz/ready`, `/healthz/live`), not a dependency. A liveness probe that calls the database would cascade-restart on a DB blip.
+- See `domains/kubernetes/workloads.md`.
+
+### Image Pinning (k8s P1 + IaC P5 Version Everything)
+- `image: registry.example.com/api:v1.4.2` — pinned to a version, not `:latest`. A pod restart pulls the same image it was built with.
+- See `domains/infrastructure-as-code/terraform.md` and `domains/devops/P7 Immutability` for the immutability angle.
+
+### RBAC (k8s P7 RBAC by Intent, Not Identity)
+- `serviceAccountName: api` — the workload runs as a dedicated ServiceAccount, not the `default` shared identity.
+- `automountServiceAccountToken: false` — the workload does not call the API, so it gets no token. See `domains/kubernetes/rbac.md`.
+- A matching `Role` + `RoleBinding` (not shown) would grant `get, list, watch` on `configmaps` in this namespace — least privilege, scoped by intent.
+
+### Config and Secrets Separate (k8s P9 Config and Secrets are Separate)
+- `LOG_LEVEL` from a ConfigMap (non-sensitive). `DATABASE_URL` from a Secret (sensitive). Both injected at runtime; neither baked into the image.
+- A configuration change does not require a rebuild. A secret rotation does not require an image redeploy.
+- See `domains/kubernetes/rbac.md` and `domains/security/secrets.md`.
+
+### Namespaces Bound Blast Radius (k8s P6 Namespaces Bound Blast Radius)
+- The workload lives in `api-prod`, not `default`. The namespace is the unit of quota, RBAC, and NetworkPolicy. A problem in `api-prod` does not leak to other workloads.
+- See `domains/kubernetes/networking.md`.
+
+### NetworkPolicy Default-Deny (k8s P6, P7)
+- The `NetworkPolicy` allows ingress only from the `edge` namespace. Without it, every pod in the cluster could reach `api`. Default-deny is the baseline; allows are the exceptions.
+- See `domains/kubernetes/networking.md`.
+
+### Roll Forward, Roll Back (k8s P10 Roll Forward Roll Back)
+- `strategy: RollingUpdate` with `maxSurge: 1, maxUnavailable: 0` — the rollout adds a new pod before removing an old one. Availability is maintained.
+- `kubectl rollout undo deployment/api` reverts to the previous ReplicaSet. The rollback is tested before it is needed.
+- See `domains/kubernetes/workloads.md` and `domains/devops/P5 Progressive Delivery`.
+
+### Cross-Domain Links
+- `domains/devops/P4 Rollback First` — the rollout strategy makes the deploy reversible.
+- `domains/security/authorization` — the ServiceAccount + Role model is the k8s expression of least-privilege authorization.
+- `domains/observability/metrics` — the probes are the platform's observability into the workload's health; the workload's own metrics complete the picture.
@@ -0,0 +1,125 @@
+# Good Example: Terraform Module
+
+> A reusable Terraform module that follows Atelier's Infrastructure as Code principles. Each aspect cites the principle it satisfies.
+
+## The Module
+
+A versioned module that provisions an S3 bucket with logging, versioning, and encryption — the canonical "secure bucket" pattern, composed rather than copy-pasted.
+
+### Consumer Call
+
+```hcl
+module "logs_bucket" {
+  source  = "registry.example.com/infra/secure-bucket/aws"
+  version = "1.2.0"
+
+  name             = "app-logs"
+  region           = "us-east-1"
+  force_destroy    = false
+  retention_days   = 90
+}
+```
+
+### Module Structure
+
+```
+secure-bucket/
+├── main.tf          # the resource
+├── variables.tf    # typed inputs
+├── outputs.tf      # the interface to consumers
+├── versions.tf     # provider pin
+└── README.md       # the module contract
+```
+
+### `versions.tf` (P5 Version Everything)
+
+```hcl
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+```
+
+### `variables.tf` (P1 Declarative Intent, C2 Clarity)
+
+```hcl
+variable "name" {
+  type        = string
+  description = "Globally unique bucket name."
+  validation {
+    condition     = can(regex("^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$", var.name))
+    error_message = "Bucket name must be lowercase, 3-63 chars, DNS-compatible."
+  }
+}
+
+variable "retention_days" {
+  type        = number
+  default     = 30
+  description = "S3 lifecycle transition age in days."
+}
+```
+
+### `main.tf` (P1, P3 State is Truth, P10 Secrets Never in Code)
+
+```hcl
+resource "aws_s3_bucket" "this" {
+  bucket = var.name
+}
+
+resource "aws_s3_bucket_versioning" "this" {
+  bucket = aws_s3_bucket.this.id
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "this" {
+  bucket = aws_s3_bucket.this.id
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+  }
+}
+
+resource "aws_s3_bucket_lifecycle_configuration" "this" {
+  bucket = aws_s3_bucket.this.id
+  rule {
+    id     = "retention"
+    status = "Enabled"
+    filter { prefix = "" }
+    expiration { days = var.retention_days }
+  }
+}
+```
+
+## What Makes It Good
+
+### Composition (IaC P6 Modules Compose, C6 Composability)
+- The bucket pattern is one module, versioned once, consumed many times. A new consumer does not copy 40 lines of HCL — they call the module with a `name` and a `retention_days`.
+- See `domains/infrastructure-as-code/modules.md` for the module-vs-copy boundary.
+
+### Pinning (IaC P5 Version Everything)
+- The consumer pins `version = "1.2.0"`. The module pins its provider (`version = "~> 5.0"`) and the required Terraform version. A commit is a complete, reproducible world.
+- No `latest` anywhere. See `domains/infrastructure-as-code/terraform.md`.
+
+### State Discipline (IaC P3 State is Truth, P8 Remote State with Locking)
+- The consumer's root configuration declares a remote backend with locking (S3 + DynamoDB, GCS, etc.). The module itself does not declare a backend — the consumer owns state.
+- See `domains/infrastructure-as-code/state.md` for backend selection and locking.
+
+### Secrets Hygiene (IaC P10 Secrets Never in Code)
+- The bucket is encrypted at rest (SSE-S3 AES256). No secret is hardcoded; encryption is a provider-managed default. If KMS were used, the key would come from a `data` source or a dedicated KMS module — never a literal.
+- See `domains/security/secrets.md` for the general secrets principles.
+
+### Plan Before Apply (IaC P4 Plan Before Apply)
+- The consumer runs `terraform plan` before `apply`. The plan shows the new bucket, versioning, encryption, and lifecycle. Every line is reviewed. The plan is the contract review; `apply` is the signature.
+
+### Cross-Domain Links
+- `domains/devops/P1 Reproducibility` — the module makes the bucket reproducible from source.
+- `domains/devops/P6 Configuration as Code` — the bucket is config, not a console click.
+- `domains/security/supply-chain` — a versioned, signed module from a trusted registry is a supply-chain control.
@@ -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?
@@ -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
Author	SHA1	Message	Date
Jon Chery	433a870580	docs(P04): complete examples + cross-links phase ---ci--- project: atelier phase: 4 milestone: v0.2 status: complete requirements: covered: [ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56] partial: [] ---/ci---	2026-08-05 02:14:51 +00:00
Jon Chery	e721cd2997	docs(P03): update REQUIREMENTS + ROADMAP status — ATELIER-48..52, 59 covered ---ci--- project: atelier phase: 3 milestone: v0.2 status: complete ---/ci---	2026-08-05 02:12:53 +00:00
Jon Chery	d195e8c3a9	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---	2026-08-05 02:12:28 +00:00
Jon Chery	5fbb599543	docs(P02): update REQUIREMENTS + ROADMAP status — ATELIER-41..47 covered ---ci--- project: atelier phase: 2 milestone: v0.2 status: complete ---/ci---	2026-08-05 02:10:52 +00:00
Jon Chery	c3226192f5	docs(P02): complete kubernetes phase ---ci--- project: atelier phase: 2 milestone: v0.2 status: complete requirements: covered: [ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47] partial: [] ---/ci---	2026-08-05 02:09:55 +00:00
Jon Chery	2b602fe49b	docs(P01): update REQUIREMENTS + ROADMAP status — ATELIER-36..40 covered ---ci--- project: atelier phase: 1 milestone: v0.2 status: complete ---/ci---	2026-08-05 02:07:12 +00:00
Jon Chery	b997bd63b1	docs(P01): complete infrastructure-as-code phase ---ci--- project: atelier phase: 1 milestone: v0.2 status: complete requirements: covered: [ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40] partial: [] ---/ci---	2026-08-05 02:04:11 +00:00
Jon Chery	40e61e6b7b	docs(P00): complete pre-execution phase ---ci--- project: atelier phase: 0 milestone: v0.2 status: complete requirements: covered: [ATELIER-governance] partial: [] ---/ci---	2026-08-05 02:00:24 +00:00