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---
docs(P00): complete pre-execution phase
2026-08-05 02:04:11 +00:00 · 2026-08-05 02:00:24 +00:00
15 changed files with 817 additions and 20 deletions
@@ -1,9 +1,10 @@
 {
-  "phase": 7,
-  "stage": "complete",
-  "milestone": "v0.1",
-  "phase_role": "final",
+  "phase": 1,
+  "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-05T01:40: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 | pending |
+| ATELIER-37 | `domains/infrastructure-as-code/terraform.md` — Terraform derived doc | P1 | 1 | pending |
+| ATELIER-38 | `domains/infrastructure-as-code/opentofu.md` — OpenTofu derived doc | P1 | 1 | pending |
+| ATELIER-39 | `domains/infrastructure-as-code/state.md` — IaC state management derived doc | P1 | 1 | pending |
+| ATELIER-40 | `domains/infrastructure-as-code/modules.md` — IaC module composition derived doc | P1 | 1 | pending |
+| ATELIER-41 | `domains/kubernetes/first-principles.md` — 10 k8s principles (P1–P10) | P0 | 2 | pending |
+| ATELIER-42 | `domains/kubernetes/workloads.md` — workloads derived doc | P1 | 2 | pending |
+| ATELIER-43 | `domains/kubernetes/networking.md` — networking derived doc | P1 | 2 | pending |
+| ATELIER-44 | `domains/kubernetes/storage.md` — storage derived doc | P1 | 2 | pending |
+| ATELIER-45 | `domains/kubernetes/rbac.md` — RBAC derived doc incl. Pod Security Standards/Admission (cross-link security/authorization) | P1 | 2 | pending |
+| ATELIER-46 | `domains/kubernetes/helm.md` — Helm derived doc (with Helm vs Kustomize decision matrix) | P1 | 2 | pending |
+| ATELIER-47 | `domains/kubernetes/kustomize.md` — Kustomize derived doc (with Helm vs Kustomize decision matrix) | P1 | 2 | pending |
+| 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 | pending |
+| 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 | pending |
+| ATELIER-50 | Extend `review/agent-checklist.md` with IaC + k8s trigger sections | P1 | 3 | pending |
+| ATELIER-51 | Extend `review/anti-patterns.md` with IaC + k8s violations incl. orphaned P-rule + deployable example artifact | P1 | 3 | pending |
+| ATELIER-52 | Update `MANIFEST.md` to list all new v0.2 documents (manifest authoritative) | P0 | 3 | pending |
+| 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 | pending |
+
+## 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 | in_progress | Spec, clarify, research, ideate, plan, PERSONAS.md (adds platform-engineer persona) |
+| 1 | Infrastructure as Code Domain | docs | pending | domains/infrastructure-as-code/{first-principles, terraform, opentofu, state, modules}.md |
+| 2 | Kubernetes Domain | docs | pending | domains/kubernetes/{first-principles, workloads, networking, storage, rbac, helm, kustomize}.md |
+| 3 | Matrix + Review Integration | docs | pending | 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"
    }
  ],
@@ -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 |