docs(P04): complete matrix-review phase

docs(P03): complete domain-derived-docs phase
docs(P02): complete domain-first-principles phase
2026-08-05 00:31:47 +00:00 · 2026-08-05 00:30:31 +00:00 · 2026-08-05 00:26:32 +00:00 · 2026-08-05 00:25:07 +00:00 · 2026-08-05 00:23:54 +00:00 · 2026-08-05 00:22:53 +00:00
24 changed files with 69 additions and 1762 deletions
@@ -1,10 +1,8 @@
 {
  "phase": 0,
-  "stage": "plan",
-  "milestone": "v0.2",
+  "stage": "complete",
+  "milestone": "v0.1",
  "phase_role": "pre_execution",
-  "project": "atelier",
  "attempts": 0,
-  "updated_at": "2026-08-05T01:30:00Z",
-  "milestone_complete": false
+  "updated_at": "2026-08-05T00:04:00Z"
 }
@@ -8,15 +8,12 @@ Atelier is a **documentation-only framework** — no runtime code, no build arti

 ```
 atelier/
-├── 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)
+├── 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)
 ```

 **Dependency direction (enforced):**
@@ -71,13 +68,4 @@ 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.

-## 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).
+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).
@@ -31,29 +31,4 @@
 - 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).
-
-## 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.
+- 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).
@@ -48,26 +48,8 @@

 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.
-
-## 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).
+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.
@@ -204,171 +204,4 @@ 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 |
-
---
-
-# 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** |
+| P7 | 3 | Sequential: review → audit → ship |
@@ -52,31 +52,6 @@ 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

@@ -92,17 +67,7 @@ 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.
-
-## 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.
+None yet. Atelier is a standalone docs framework.
@@ -7,38 +7,38 @@
 | ATELIER-01 | `.ciagent/atelier/` governance files created | P0 | 0 | covered |
 | ATELIER-02 | Milestone v0.1 branch hierarchy established | P0 | 0 | covered |
 | ATELIER-03 | Initial framework content committed (MANIFEST, matrix, 11 domain first-principles, uiux components+a11y) | P0 | 0 | covered |
-| ATELIER-04 | `core/first-principles.md` — 8 core principles (C1–C8) | P0 | 1 | covered |
-| ATELIER-05 | `core/conflict-resolution.md` — cross-document conflict rules | P0 | 1 | covered |
-| ATELIER-06 | `core/reading-order.md` — recommended consumption order | P0 | 1 | covered |
-| ATELIER-07 | `README.md` — repo entry point, quickstart | P0 | 1 | covered |
-| ATELIER-08 | `LICENSE` — MIT license | P0 | 1 | covered |
-| ATELIER-09 | `domains/uiux/first-principles.md` — 10 UI/UX principles | P0 | 2 | covered |
-| ATELIER-10 | `domains/errors/first-principles.md` — 10 error principles | P1 | 2 | covered |
-| ATELIER-11 | `domains/documentation/first-principles.md` | P1 | 2 | covered |
-| ATELIER-12 | `domains/concurrency/first-principles.md` | P1 | 2 | covered |
-| ATELIER-13 | `domains/devops/first-principles.md` | P1 | 2 | covered |
-| ATELIER-14 | `domains/api/` derived: rest, graphql, versioning, error-responses, pagination | P1 | 3 | covered |
-| ATELIER-15 | `domains/security/` derived: authentication, authorization, input-validation, secrets, supply-chain | P1 | 3 | covered |
-| ATELIER-16 | `domains/data/` derived: schema-design, migrations, indexing | P1 | 3 | covered |
-| ATELIER-17 | `domains/testing/` derived: pyramid, fixtures | P1 | 3 | covered |
-| ATELIER-18 | `domains/performance/` derived: frontend, backend | P1 | 3 | covered |
-| ATELIER-19 | `domains/observability/` derived: logging, metrics, tracing | P1 | 3 | covered |
-| ATELIER-20 | `domains/uiux/` derived: tokens, copywriting | P2 | 3 | covered |
-| ATELIER-21 | `matrix/principles-matrix.md` — full domain → core mapping | P0 | 4 | covered |
-| ATELIER-22 | `matrix/domain-coverage.md` | P1 | 4 | covered |
-| ATELIER-23 | `review/agent-checklist.md` | P0 | 4 | covered |
-| ATELIER-24 | `review/peer-review-checklist.md` | P1 | 4 | covered |
-| ATELIER-25 | `review/anti-patterns.md` | P1 | 4 | covered |
-| ATELIER-26 | `examples/good/api-endpoint.md` | P2 | 5 | covered |
-| ATELIER-27 | `examples/good/react-component.md` | P2 | 5 | covered |
-| ATELIER-28 | `examples/good/db-schema.md` | P2 | 5 | covered |
-| ATELIER-29 | `examples/good/error-handler.md` | P2 | 5 | covered |
-| ATELIER-30 | `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md` | P2 | 5 | covered |
-| ATELIER-31 | `languages/typescript.md`, `python.md`, `go.md`, `rust.md` | P2 | 6 | covered |
-| ATELIER-32 | `CHANGELOG.md` | P1 | 6 | covered |
-| ATELIER-33 | `CONTRIBUTING.md` | P1 | 6 | covered |
-| ATELIER-34 | Final review passes (all phases reviewed, audit clean) | P0 | 7 | covered |
-| ATELIER-35 | Milestone v0.1 released (tag v0.0.7, merged to main) | P0 | 7 | covered |
+| ATELIER-04 | `core/first-principles.md` — 8 core principles (C1–C8) | P0 | 1 | pending |
+| ATELIER-05 | `core/conflict-resolution.md` — cross-document conflict rules | P0 | 1 | pending |
+| ATELIER-06 | `core/reading-order.md` — recommended consumption order | P0 | 1 | pending |
+| ATELIER-07 | `README.md` — repo entry point, quickstart | P0 | 1 | pending |
+| ATELIER-08 | `LICENSE` — MIT license | P0 | 1 | pending |
+| ATELIER-09 | `domains/uiux/first-principles.md` — 10 UI/UX principles | P0 | 2 | pending |
+| ATELIER-10 | `domains/errors/first-principles.md` — 10 error principles | P1 | 2 | pending |
+| ATELIER-11 | `domains/documentation/first-principles.md` | P1 | 2 | pending |
+| ATELIER-12 | `domains/concurrency/first-principles.md` | P1 | 2 | pending |
+| ATELIER-13 | `domains/devops/first-principles.md` | P1 | 2 | pending |
+| ATELIER-14 | `domains/api/` derived: rest, graphql, versioning, error-responses, pagination | P1 | 3 | pending |
+| ATELIER-15 | `domains/security/` derived: authentication, authorization, input-validation, secrets, supply-chain | P1 | 3 | pending |
+| ATELIER-16 | `domains/data/` derived: schema-design, migrations, indexing | P1 | 3 | pending |
+| ATELIER-17 | `domains/testing/` derived: pyramid, fixtures | P1 | 3 | pending |
+| ATELIER-18 | `domains/performance/` derived: frontend, backend | P1 | 3 | pending |
+| ATELIER-19 | `domains/observability/` derived: logging, metrics, tracing | P1 | 3 | pending |
+| ATELIER-20 | `domains/uiux/` derived: tokens, copywriting | P2 | 3 | pending |
+| ATELIER-21 | `matrix/principles-matrix.md` — full domain → core mapping | P0 | 4 | pending |
+| ATELIER-22 | `matrix/domain-coverage.md` | P1 | 4 | pending |
+| ATELIER-23 | `review/agent-checklist.md` | P0 | 4 | pending |
+| ATELIER-24 | `review/peer-review-checklist.md` | P1 | 4 | pending |
+| ATELIER-25 | `review/anti-patterns.md` | P1 | 4 | pending |
+| ATELIER-26 | `examples/good/api-endpoint.md` | P2 | 5 | pending |
+| ATELIER-27 | `examples/good/react-component.md` | P2 | 5 | pending |
+| ATELIER-28 | `examples/good/db-schema.md` | P2 | 5 | pending |
+| ATELIER-29 | `examples/good/error-handler.md` | P2 | 5 | pending |
+| ATELIER-30 | `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md` | P2 | 5 | pending |
+| ATELIER-31 | `languages/typescript.md`, `python.md`, `go.md`, `rust.md` | P2 | 6 | pending |
+| ATELIER-32 | `CHANGELOG.md` | P1 | 6 | pending |
+| ATELIER-33 | `CONTRIBUTING.md` | P1 | 6 | pending |
+| ATELIER-34 | Final review passes (all phases reviewed, audit clean) | P0 | 7 | pending |
+| ATELIER-35 | Milestone v0.1 released (tag v0.0.7, merged to main) | P0 | 7 | pending |

 ## Traceability Matrix

@@ -51,77 +51,4 @@
 | 4 (Matrix + Review) | ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25 |
 | 5 (Examples) | ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30 |
 | 6 (Languages + Meta) | ATELIER-31, ATELIER-32, ATELIER-33 |
-| 7 (Final Review + Ship) | ATELIER-34, ATELIER-35 |
-
-## 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.
-
-## 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) |
+| 7 (Final Review + Ship) | ATELIER-34, ATELIER-35 |
@@ -90,129 +90,4 @@ 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).
-
---
-
-# 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.
+5. Phase ordering (P1–P6) follows the spec's build order; matrix + review come after all domains exist (P4).
@@ -1,69 +0,0 @@
-# Atelier — Final Review + Audit (P7)
-
-> Final phase review and audit for milestone v0.1. Conducted before milestone ship.
-
-## Review (Multi-Persona, across all phases)
-
-### Structural Review
- **All 64 MANIFEST-listed documents exist:** ✓
-  - 3 core, 11 domain first-principles, 27 derived, 2 matrix, 3 review, 4 good examples, 3 bad examples, 4 languages, 5 meta (README, LICENSE, CHANGELOG, CONTRIBUTING, MANIFEST)
- **No unlisted docs:** the framework tree contains only docs in the manifest (plus `.ciagent/` governance, which is meta, not framework content).
-
-### Behavioral Review
- **Every domain has exactly 10 P-rules** (verified per domain: api 10, security 10, data 10, testing 10, performance 10, observability 10, errors 10, documentation 10, concurrency 10, devops 10, uiux 10).
- **Matrix has exactly 110 rows** (11 domains × 10 principles).
- **Every matrix row maps to a C-rule** that exists in `core/first-principles.md` (C1–C8 all present).
- **Every example cites principles** (good: 10–18 citations; bad: 7–11 citations).
-
-### Security Review
- **No secret in git history:** the GITEA_API_TOKEN value does not appear in any committed file or commit message. `.ciagent/.env.secrets` is gitignored and never staged.
- **No security anti-patterns in framework content:** the `review/anti-patterns.md` catalog is complete; examples/bad/* cite the security principles they violate.
-
-### Quality Review
- **Document structure consistent:** all first-principles docs follow the template (Manifesto → Principles → Conflict Resolution → What Violates → Relationship to Core).
- **Reading order links resolve:** `core/reading-order.md` forward references to P2–P6 docs now resolve (all created).
- **CHANGELOG follows Keep a Changelog format:** Added section, phases enumerated.
-
-### P1+ Issues Found (post-hoc, not blocking)
-1. **Squash-merge commits lack `---ci---` blocks:** the 7 `docs(P0N): complete ...` commits (consolidation points) and the initial `chore: initialize` commit do not have `---ci---` blocks. The task commits on phase branches all have them. Per commit-discipline, consolidation commits could include a `---ci---` block. This is a P1 (post-hoc) issue, not blocking. The milestone ship commit below includes a comprehensive `---ci---` block covering the milestone.
-
-**P0 fixes applied:** none required. No blocking issues found.
-
-## Audit
-
-### Reconstruction Test
- **MANIFEST.md lists all framework documents:** ✓ (64 docs)
- **Every listed document exists:** ✓
- **Git log reconstructs project state:** the `---ci---` blocks in task commits record phase, milestone, status, and requirements covered. The git log + `.ciagent/` files reconstruct the full project state.
-
-### Branch Hygiene
- **Before ship:** `main`, `milestone/v0.1-atelier`, 7 phase branches (00–06), `phase/07-final-review-ship` (current).
- **After ship:** all phase branches deleted; `main` + `milestone/v0.1-atelier` remain briefly, then milestone branch deleted after merge to main. Tags preserve all history.
-
-### Commit Discipline
- **Task commits** (on phase branches): all have `---ci---` blocks with project, phase, milestone, status, requirements. ✓
- **Squash-merge commits** (on milestone branch): consolidation commits without `---ci---` blocks. P1 (post-hoc).
- **Init commit**: has full `---ci---` block. ✓
-
-### File Discipline
- `.ciagent/` holds only governance files (config, PROJECT, ROADMAP, REQUIREMENTS, ARCHITECTURE, PERSONAS, PLAN, RESEARCH, CLARIFY, AUDIT-P2, CHECKPOINT). ✓
- Framework content is in the repo root (`core/`, `domains/`, etc.). ✓
- `.env.secrets` is gitignored, never committed. ✓
-
-## Milestone Ship Checklist
-
- [x] All execution phases (P1–P6) shipped (v0.0.1–v0.0.6)
- [x] Review passed (structural, behavioral, security, quality)
- [x] Audit clean (reconstruction, branch hygiene, file discipline)
- [x] REQUIREMENTS.md updated (all 35 requirements covered)
- [x] ROADMAP.md updated (milestone complete)
- [ ] Merge `phase/07` → `milestone/v0.1-atelier`
- [ ] Merge `milestone/v0.1-atelier` → `main`
- [ ] Tag `v0.0.7` (IS the v0.1 milestone release)
- [ ] Create Gitea release for v0.0.7
- [ ] Delete all phase branches + milestone branch
- [ ] Clear checkpoint (milestone complete)
-
-## Conclusion
-
-The milestone v0.1 is complete and ready to ship. 35/35 requirements covered. 8 core principles, 11 domains, 110 domain principles, all traced via the matrix. The framework is internally consistent and ready for consumption.
@@ -1,6 +1,6 @@
 # Atelier — Roadmap

-## Milestone: v0.1 — Initial Framework (COMPLETE)
+## Milestone: v0.1 — Initial Framework

 **Milestone type:** NFR (all phases produce docs/chore commits — no `feat` code)
 **Tag line:** v0.0.x (previous minor from v0.1)
@@ -8,14 +8,14 @@

 | Phase | Name | Type | Status | Key Deliverables |
 |-------|------|------|--------|------------------|
-| 0 | Pre-Execution | docs | complete | Spec, clarify, research, plan, PERSONAS.md |
-| 1 | Core Foundation | docs | complete | core/first-principles.md, core/conflict-resolution.md, core/reading-order.md, README.md, LICENSE |
-| 2 | Domain First Principles | docs | complete | uiux/first-principles.md, domain audit |
-| 3 | Domain Derived Docs | docs | complete | 27 derived docs across 11 domains |
-| 4 | Matrix + Review | docs | complete | matrix/domain-coverage.md, review/{agent,peer-review,anti-patterns}.md |
-| 5 | Examples | docs | complete | 4 good + 3 bad examples |
-| 6 | Languages + Meta | docs | complete | 4 language docs, CHANGELOG, CONTRIBUTING |
-| 7 | Final Review + Ship | docs | complete | Review passed, audit clean, milestone merged to main, tag v0.0.7 |
+| 0 | Pre-Execution | docs | in_progress | Spec, clarify, research, plan, PERSONAS.md |
+| 1 | Core Foundation | docs | pending | core/first-principles.md, core/conflict-resolution.md, core/reading-order.md, README.md, LICENSE |
+| 2 | Domain First Principles (remaining) | docs | pending | uiux/first-principles.md, errors/, documentation/, concurrency/, devops first-principles |
+| 3 | Domain Derived Docs | docs | pending | api/*, security/*, data/*, testing/*, performance/*, observability/* derived docs |
+| 4 | Matrix + Review | docs | pending | matrix/principles-matrix.md, matrix/domain-coverage.md, review/agent-checklist.md, review/peer-review-checklist.md, review/anti-patterns.md |
+| 5 | Examples | docs | pending | examples/good/*, examples/bad/* |
+| 6 | Languages + Meta | docs | pending | languages/*.md, CHANGELOG.md, CONTRIBUTING.md |
+| 7 | Final Review + Ship | docs | pending | Review, audit, milestone merge to main, tag v0.0.7, release |

 ## Phase Tag Mapping

@@ -36,56 +36,15 @@ NFR milestone: no separate minor tag. The final patch (v0.0.7) IS the v0.1 deliv

 ## Next

- 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.
+- Phase 0: complete specify → clarify → research → plan → grill → ship
+- Phase 1: write core foundation documents

 ## Success Criteria

- [x] All 11 domains have first-principles.md
- [x] Every domain P-rule traced to a core C-rule in matrix/principles-matrix.md
- [x] MANIFEST.md lists all framework documents
- [x] review/agent-checklist.md covers all core principles
- [x] examples/ includes at least 4 good + 3 bad worked examples
- [x] README.md provides quickstart for agents and humans
- [x] Milestone v0.1 tagged and released
+- [ ] All 11 domains have first-principles.md
+- [ ] Every domain P-rule traced to a core C-rule in matrix/principles-matrix.md
+- [ ] MANIFEST.md lists all framework documents
+- [ ] review/agent-checklist.md covers all core principles
+- [ ] examples/ includes at least 4 good + 3 bad worked examples
+- [ ] README.md provides quickstart for agents and humans
+- [ ] Milestone v0.1 tagged and released
@@ -3,7 +3,7 @@
    {
      "slug": "atelier",
      "name": "Atelier",
-      "milestone": "v0.2",
+      "milestone": "v0.1",
      "status": "specify"
    }
  ],
@@ -53,13 +53,13 @@
  "release": {
    "forge": "gitea",
    "base_url": "https://git.cloudinit.dev",
-    "owner": "coreci",
+    "owner": "cloudinit-bot",
    "repo": "atelier"
  },
  "gitea": {
    "base_url": "https://git.cloudinit.dev",
    "api_token_env": "GITEA_API_TOKEN",
-    "owner": "coreci",
+    "owner": "cloudinit-bot",
    "repo": "atelier"
  },
  "ship": {
@@ -1,45 +0,0 @@
-# Changelog
-
-All notable changes to the Atelier framework are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.1.0] — 2026-08-05
-
-### Added
- Eight core principles (C1–C8) in `core/first-principles.md` with definitions, precedence, and violation tables.
- Formal conflict resolution procedure in `core/conflict-resolution.md` (hierarchy, precedence, worked examples, non-tradeable declarations).
- Canonical reading order in `core/reading-order.md` with paths for agents, humans, conflict resolution, and review.
- README with quickstart for AI agents and humans.
- MIT license.
- Eleven domain first-principles (P1–P10 each): UI/UX, API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps.
- Twenty-seven domain derived/topic docs (REST, GraphQL, versioning, error-responses, pagination, authentication, authorization, input-validation, secrets, supply-chain, schema-design, migrations, indexing, pyramid, fixtures, frontend, backend, logging, metrics, tracing, tokens, copywriting, patterns, doc-templates, patterns, ci-cd, environments).
- `matrix/principles-matrix.md` — full mapping of all 110 domain principles to core derivations.
- `matrix/domain-coverage.md` — inverse mapping of core principles to domains.
- `review/agent-checklist.md` — pre-completion gate for AI agents.
- `review/peer-review-checklist.md` — human review checklist.
- `review/anti-patterns.md` — catalog of violations with principle citations.
- Four good worked examples: `examples/good/api-endpoint.md`, `react-component.md`, `db-schema.md`, `error-handler.md`.
- Three bad worked examples: `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md`.
- Four language application docs: `languages/typescript.md`, `python.md`, `go.md`, `rust.md`.
- `MANIFEST.md` — authoritative document index.
- `CONTRIBUTING.md` — contribution guide.
-
-### Framework Properties
- 8 core principles, 11 domains, 110 domain principles, all traced via the matrix.
- NFR milestone type (documentation only, no runtime code).
- Tags: v0.0.0 (pre-execution) through v0.0.7 (final review + ship).
- The v0.0.7 patch release IS the v0.1.0 milestone deliverable.
-
-### Phases
- Phase 0 (v0.0.0): pre-execution — specify, clarify, research, plan, ship.
- Phase 1 (v0.0.1): core foundation — first-principles, conflict-resolution, reading-order, README, LICENSE.
- Phase 2 (v0.0.2): domain first-principles — uiux first-principles + audit.
- Phase 3 (v0.0.3): domain derived docs — 27 topic files.
- Phase 4 (v0.0.4): matrix + review — domain-coverage, agent-checklist, peer-review-checklist, anti-patterns.
- Phase 5 (v0.0.5): examples — 4 good + 3 bad.
- Phase 6 (v0.0.6): languages + meta — typescript, python, go, rust, CHANGELOG, CONTRIBUTING.
- Phase 7 (v0.0.7): final review + ship — milestone release.
@@ -1,71 +0,0 @@
-# Contributing to Atelier
-
-Thank you for considering a contribution to Atelier. This framework lives by its principles; contributions are expected to follow them.
-
-## What We Accept
-
- **New domain first-principles** — if a domain is missing (e.g., `domains/ai-ml/`), propose it with 10 principles (P1–P10), each traced to a core principle (C1–C8) in `matrix/principles-matrix.md`.
- **New domain derived docs** — topic docs under an existing domain (e.g., `domains/api/webhooks.md`), deriving from the domain's first-principles.
- **New language application docs** — `languages/<lang>.md` showing how domain principles apply in a specific language.
- **New examples** — `examples/good/*` (with principle citations) or `examples/bad/*` (with violation citations).
- **Corrections** — to existing principles, derivations, or examples. A correction to a core principle is a major version change; treat with care.
- **Improvements to the matrix** — if a derivation is missing or wrong, propose the fix with the rationale.
-
-## What We Do Not Accept
-
- **Style rules** — Atelier is principles, not style. Use a linter for style.
- **Tooling** — linters, analyzers, or enforcement code. Atelier is markdown.
- **Unlisted docs** — every document must be in `MANIFEST.md`. An unlisted doc is not part of the framework.
- **Principles without derivation** — a domain principle that does not trace to a core principle is orphaned and will be rejected.
-
-## How to Contribute
-
-### 1. Read the relevant docs first
- `core/first-principles.md` — the eight axioms.
- `core/conflict-resolution.md` — how conflicts are resolved.
- The domain(s) you are contributing to.
- `matrix/principles-matrix.md` — to see existing derivations.
-
-### 2. Follow the document structure
-See `domains/documentation/doc-templates.md` for the canonical structure. Every first-principles doc has:
- Manifesto
- The Principles (P1–P10, named, defined, with "what violates it")
- Conflict Resolution
- What Violates These Principles (table)
- Relationship to Core
-
-### 3. Update the matrix
-If you add or change a principle, update `matrix/principles-matrix.md` with the derivation. A PR with a new principle but no matrix row is incomplete.
-
-### 4. Update the manifest
-If you add a new document, add it to `MANIFEST.md` in the correct section. An unlisted document is not part of the framework.
-
-### 5. Add examples
-If you add a principle, add at least one good example and one bad example in `examples/`. Examples are mandatory (Documentation P3).
-
-### 6. Write a clear PR description
- What principle or document you are adding/changing.
- Why (the rationale, not just the what — Documentation P8 Why Over What).
- Which core principle(s) it derives from.
- What conflicts it might introduce (if any).
-
-## Review Criteria
-
-Reviewers will check (see `review/peer-review-checklist.md`):
- Does the new principle trace to a core principle?
- Is the matrix updated?
- Is the manifest updated?
- Are there examples?
- Does the structure follow the template?
- Does it conflict with existing principles? If so, is the conflict resolvable per `core/conflict-resolution.md`?
-
-## Versioning
-
- A new domain or language doc is a minor version (e.g., v0.1 → v0.2).
- A new topic doc or example is a patch version (e.g., v0.1.0 → v0.1.1).
- A change to `core/first-principles.md` (adding, removing, or reordering a core principle) is a major version (e.g., v0.x → v1.0).
- See `CHANGELOG.md` for the version history.
-
-## License
-
-By contributing, you agree that your contributions are licensed under the MIT license (see `LICENSE`).
@@ -1,107 +0,0 @@
-# Bad Example: God Object
-
-> A component that violates Atelier principles. Each violation is cited.
-
-## The Code
-
-```typescript
-// UserManager.ts — 1,200 lines
-class UserManager {
-  private users: User[] = [];
-  private cache: Map<string, User> = new Map();
-  private db: Database;
-  private emailService: EmailService;
-  private logger: Logger;
-  private auditLog: AuditLog;
-
-  constructor(db: Database, email: EmailService, logger: Logger, audit: AuditLog) {
-    this.db = db;
-    this.emailService = email;
-    this.logger = logger;
-    this.auditLog = audit;
-  }
-
-  // CRUD
-  async createUser(data: UserData): Promise<User> { /* 80 lines */ }
-  async getUser(id: string): Promise<User> { /* 40 lines */ }
-  async updateUser(id: string, data: Partial<UserData>): Promise<User> { /* 60 lines */ }
-  async deleteUser(id: string): Promise<void> { /* 50 lines */ }
-  async listUsers(page: number): Promise<User[]> { /* 40 lines */ }
-
-  // Email
-  async sendWelcomeEmail(user: User): Promise<void> { /* 50 lines */ }
-  async sendPasswordReset(user: User): Promise<void> { /* 50 lines */ }
-  async sendDeletionNotice(user: User): Promise<void> { /* 40 lines */ }
-
-  // Auth
-  async authenticate(email: string, password: string): Promise<boolean> { /* 70 lines */ }
-  async authorize(userId: string, action: string): Promise<boolean> { /* 60 lines */ }
-  async hashPassword(password: string): Promise<string> { /* 20 lines */ }
-
-  // Cache
-  private cacheGet(id: string): User | null { /* 20 lines */ }
-  private cacheSet(user: User): void { /* 20 lines */ }
-  private cacheInvalidate(id: string): void { /* 20 lines */ }
-
-  // Audit
-  private logAudit(action: string, userId: string): void { /* 30 lines */ }
-
-  // Validation
-  private validateEmail(email: string): boolean { /* 20 lines */ }
-  private validatePassword(password: string): boolean { /* 20 lines */ }
-
-  // Serialization
-  toJSON(user: User): Record<string, unknown> { /* 30 lines */ }
-  fromJSON(data: Record<string, unknown>): User { /* 30 lines */ }
-
-  // ... 200 more lines of helper methods
-}
-```
-
-## Violations
-
-### C3 Simplicity (Core)
- A 1,200-line class doing 8 different things (CRUD, email, auth, cache, audit, validation, serialization).
- The class cannot be understood in one read. Complexity is the liability.
- **Fix:** Split into `UserRepository` (CRUD), `UserEmailService` (email), `UserAuthService` (auth), `UserCache` (cache), `UserAuditLogger` (audit), `UserValidator` (validation), `UserSerializer` (serialization).
-
-### C6 Composability (Core)
- The class takes 4 dependencies and does 8 jobs. It is not composable; it is monolithic.
- You cannot reuse the email logic without the DB, the cache, the audit log.
- **Fix:** Each responsibility is its own class. Compose them: `UserEmailService` takes only `EmailService`.
-
-### components.md §1 Single Responsibility (UI/UX, applies to code)
- The class name is `UserManager`. "Manager" is a smell — it manages what? Everything.
- If the name is "Manager," it has no single responsibility.
- **Fix:** Name by responsibility: `UserRepository`, `UserAuthService`. Names that cannot be "And"-ed.
-
-### C4 Locality (Core)
- Cache logic is in the same class as email logic. A change to cache touches the email methods' neighbor.
- Related logic (cache get/set/invalidate) is grouped, but unrelated logic (email) is adjacent.
- **Fix:** `UserCache` is its own class. Cache changes are local to cache.
-
-### C2 Clarity (Core)
- A reader cannot answer "what does `UserManager` do?" in one sentence.
- The class has 20+ methods. The reader must scan all of them to find the one they need.
- **Fix:** Smaller classes with clear names. The name is the documentation.
-
-### Security P2 Least Privilege (Security)
- The class has `db`, `emailService`, `logger`, `auditLog` — all available to all methods.
- `sendWelcomeEmail` has access to `db.delete`. Least privilege is violated.
- **Fix:** Each service has only the dependencies it needs. `UserEmailService` has `EmailService`, not `Database`.
-
-### Testing P2 Independence (Testing)
- To test `sendWelcomeEmail`, you must construct `UserManager` with a real/mock DB, email, logger, audit.
- The test setup is 4 mocks for one method. Independence is violated.
- **Fix:** Test `UserEmailService` with one mock (`EmailService`).
-
-## What This Example Reveals
-
-The "God Object" is the cardinal sin of OOP. It violates C3 (Simplicity), C6 (Composability), C4 (Locality), and C2 (Clarity) simultaneously. Every other principle suffers downstream:
-
- Testing is hard (T2 Independence).
- Security is loose (S2 Least Privilege).
- Evolution is brittle (a change to email risks cache).
- Review is exhausting (a 1,200-line diff).
-
-The fix is always the same: **decompose by responsibility**. The class name is the test: if it is "Manager," "Handler," or "Helper," it has no single responsibility.
@@ -1,87 +0,0 @@
-# Bad Example: Leaky Abstraction
-
-> An abstraction that leaks its implementation details, violating Atelier principles. Each violation is cited.
-
-## The Code
-
-```typescript
-// UserRepository — "abstracts" the database
-class UserRepository {
-  async findAll(): Promise<UserRow[]> {
-    // Leaks: returns the raw DB row type, not a domain User
-    return db.query('SELECT id, email, password_hash, created_at, deleted_at FROM users');
-  }
-
-  async findByEmail(email: string): Promise<UserRow | null> {
-    // Leaks: the caller must know to filter deleted_at
-    const rows = await db.query('SELECT * FROM users WHERE email = $1', [email]);
-    return rows[0] || null;
-  }
-
-  async save(user: UserRow): Promise<void> {
-    // Leaks: the caller must know the column names and the SQL
-    await db.query(
-      'UPDATE users SET email = $1, password_hash = $2, updated_at = now() WHERE id = $3',
-      [user.email, user.password_hash, user.id]
-    );
-  }
-}
-
-// Usage — the leak is visible
-const repo = new UserRepository();
-const user = await repo.findByEmail('jane@example.com');
-if (user && !user.deleted_at) {  // caller must know about soft delete
-  user.password_hash = await hash(newPassword);  // caller must know the column
-  await repo.save(user);  // caller must know it's an UPDATE
-}
-```
-
-## Violations
-
-### C6 Composability (Core)
- The abstraction is supposed to hide the database. It does not.
- The caller must know: the row type (`UserRow`), the soft-delete column (`deleted_at`), the password column (`password_hash`), the SQL operation (`UPDATE`).
- The abstraction is a thin wrapper. It composes nothing; it leaks everything.
- **Fix:** Return a domain `User` (no `password_hash`, no `deleted_at`). Hide soft delete (the repo filters it). Hide persistence (the caller calls `save`, not `UPDATE`).
-
-### C2 Clarity (Core)
- The caller's code is unclear: `if (user && !user.deleted_at)` — what is `deleted_at`? Why does the caller check it?
- The abstraction was supposed to clarify. It muddied.
- **Fix:** `repo.findByEmail()` returns `User | null` (already filtered). The caller does not know soft delete exists.
-
-### API P2 Clarity (API, by analogy)
- The repo's API exposes the DB schema in its return types. `UserRow` is a DB concept, not a domain concept.
- The public contract (return type) leaks the private implementation (the table).
- **Fix:** The return type is `User`, a domain type. `UserRow` is internal.
-
-### Data P8 Lifecycle Awareness (Data)
- The soft-delete lifecycle (`deleted_at`) is the repo's concern. The caller should not manage it.
- By exposing `deleted_at`, the repo forces every caller to remember the filter. A forgotten filter is a soft-delete leak.
- **Fix:** The repo filters `deleted_at IS NULL` in every query. The caller never sees `deleted_at`.
-
-### Security P9 Secret Hygiene (Security)
- `password_hash` is in the returned `UserRow`. The caller now has access to the password hash.
- A caller that logs `user` logs the hash. A caller that serializes `user` serializes the hash.
- **Fix:** `User` does not include `password_hash`. Only `UserRepository` and `AuthService` (internal) see it.
-
-### C4 Locality (Core)
- The SQL is in the repo, but the column knowledge (`password_hash`, `deleted_at`) is in the caller.
- A column rename touches the repo AND every caller. Locality is violated.
- **Fix:** Column names are local to the repo. The caller knows only the domain `User`.
-
-### C5 Reversibility (Core)
- Changing the database (e.g., from SQL to NoSQL, or renaming a column) requires touching every caller.
- The abstraction was supposed to make the change local. It does not.
- **Fix:** The repo's interface (`findByEmail`, `save`) is stable. The implementation changes; the callers do not.
-
-## What This Example Reveals
-
-The leaky abstraction is the false promise of encapsulation. The class is named `UserRepository` (suggesting it abstracts persistence), but it returns raw DB rows, exposes lifecycle columns, and leaks secret fields. The abstraction exists in name only.
-
-The cost:
- Every caller must know the DB schema (C6 violated).
- A schema change touches every caller (C5 violated, C4 violated).
- Secret fields leak to callers (Security P9 violated).
- The lifecycle is the caller's burden (Data P8 violated).
-
-The fix is always the same: **the abstraction's public type is the domain type, not the implementation type**. `UserRepository.findByEmail()` returns `User | null`, where `User` has `id`, `email`, `name` — and nothing else. `password_hash`, `deleted_at`, `UserRow` are internal. The caller knows nothing about the database.
@@ -1,88 +0,0 @@
-# Bad Example: Silent Error
-
-> An error-handling pattern that violates Atelier principles. Each violation is cited.
-
-## The Code
-
-```typescript
-async function getUser(id: string): Promise<User | null> {
-  try {
-    const user = await db.query('SELECT * FROM users WHERE id = $1', [id]);
-    return user;
-  } catch (e) {
-    return null;
-  }
-}
-
-async function processOrder(orderId: string): Promise<void> {
-  const order = await getOrder(orderId);
-  if (!order) {
-    return;  // silently do nothing
-  }
-  // ... process
-}
-
-// Usage in a route
-router.get('/users/:id', async (req, res) => {
-  const user = await getUser(req.params.id);
-  if (!user) {
-    res.status(404).json({ error: 'Not found' });
-  } else {
-    res.json({ data: user });
-  }
-});
-```
-
-## Violations
-
-### Errors P2 Fail Loudly (Errors)
- `catch (e) { return null }` swallows the error. The caller cannot distinguish "user not found" from "database down."
- A database outage returns 404s. The operator never knows. Silent failure.
- **Fix:** Catch and re-throw with context, or return a typed error (`Result<User, Error>`). Never `null` for "an error happened."
-
-### Errors P3 Fail Specifically (Errors)
- `return null` is the least specific response. It could mean: not found, db error, network error, permission error.
- The caller's `if (!user)` cannot distinguish these. The 404 is a lie if the real cause was a 500.
- **Fix:** Return `Result` or throw. The error type/code carries the specificity.
-
-### Errors P1 Errors are Data (Errors)
- `null` is not data. It is the absence of data. Conflating "error" with "absence" loses information.
- The error (a database failure) was data; it was thrown away and replaced with `null`.
- **Fix:** Errors are values. Return the error value, not a sentinel absence.
-
-### Errors P4 Preserve Context (Errors)
- The catch block discards `e`. The stack trace, the error message, the cause — all gone.
- The log has no record. The operator cannot debug.
- **Fix:** Log the error with context. Wrap and re-throw: `throw new Error('getUser failed', { cause: e })`.
-
-### Errors P9 Errors are Logged (Errors)
- The error is not logged. The handling (return null) is the entire response. The log is missing.
- An error that is not logged is an error that cannot be investigated.
- **Fix:** `logger.error({ err: e, userId: id })` before returning/rethrowing.
-
-### Errors P10 Errors Don't Lie (Errors)
- `return null` claims "no user" when the truth may be "database down." The function lies.
- The 404 response claims "not found" when the truth may be "internal error." The API lies.
- **Fix:** The response status must match the actual condition. 500 for server errors, 404 for not found.
-
-### Observability P2 Correlation, P3 Context (Observability)
- No `request_id`. No correlation across services.
- No context in the (missing) log. "What was the user doing?" is unanswerable.
- **Fix:** Propagate `request_id`. Log with path, method, user_id.
-
-### Security P8 Fail Securely (Security)
- The silent failure is fail-open in disguise. If `getUser` fails due to an authz check throwing, the catch returns `null`.
- The caller treats `null` as "not found" and may proceed, or may 404. Either way, the security failure is hidden.
- **Fix:** Distinguish "not found" (404) from "authz error" (403) from "db error" (500). Never collapse them into `null`.
-
-## What This Example Reveals
-
-The silent error is the most common and most damaging anti-pattern. It violates Errors P2 (Fail Loudly), P3 (Fail Specifically), P1 (Errors are Data), P4 (Preserve Context), P9 (Errors are Logged), P10 (Errors Don't Lie) — six of ten error principles in one catch block.
-
-The downstream effects:
- Operators cannot debug (no log, no context).
- Users see wrong errors (404 for a 500).
- Security failures hide (authz error becomes "not found").
- The system appears healthy when it is not (no metrics, no logs).
-
-The fix is always the same: **never swallow an error**. Log it, wrap it, rethrow it, or return it as a typed value. Never `return null` for "something went wrong."
@@ -1,79 +0,0 @@
-# Good Example: API Endpoint
-
-> A REST endpoint that follows Atelier's API principles. Each aspect cites the principle it satisfies.
-
-## The Endpoint
-
-```typescript
-// POST /v1/orders — create an order
-router.post('/v1/orders', auth, validate(CreateOrderSchema), async (req, res) => {
-  const { userId, items } = req.body;
-
-  const order = await orderService.create({ userId, items });
-
-  res.status(201).location(`/v1/orders/${order.id}`).json({
-    data: order,
-  });
-});
-```
-
-## What Makes It Good
-
-### Resource Naming (API P2 Clarity, P3 Predictability)
- `/v1/orders` — noun, plural, lowercase, hyphenated.
- Versioned (`/v1`) — P5 Versioning.
- No verb in the URL; the HTTP method is the verb.
-
-### Method Semantics (API P1 Contract Fidelity, P6 Idempotency)
- POST for creation. 201 on success (not 200). `Location` header for the new resource.
- Idempotency key supported via middleware (omitted for brevity) — P6.
-
-### Authentication (API P8 Security, Security P1 Zero Trust)
- `auth` middleware runs on every endpoint by default. No opt-in auth.
- The endpoint does not re-implement auth; it relies on the boundary check.
-
-### Input Validation (API P8, Security P4 Input Validation)
- `validate(CreateOrderSchema)` — schema-based validation at the boundary.
- The schema (zod, joi, etc.) defines types, ranges, required fields.
- Unknown fields rejected (`additionalProperties: false` in the schema).
-
-### Response Shape (API P2 Clarity)
- `{ data: order }` — wrapped, not a bare object. Allows adding pagination/metadata without breaking.
- The shape is consistent across all endpoints in the API.
-
-### Error Handling (API P9 Error Transparency, Errors P1 Errors are Data)
- Errors thrown in `orderService.create` are caught by centralized middleware.
- Errors are structured: `{ error: { code, message, request_id } }`.
- 404 → `ORDER_NOT_FOUND`, 409 → `DUPLICATE_ORDER`, 422 → `VALIDATION_FAILED`.
-
-### Observability (Observability P2 Correlation, P3 Sufficient Context)
- `request_id` propagated via middleware. Every log in the request includes it.
- Significant events logged: "order created", "order creation failed".
-
-### Economy (Core C8, Performance P4 Resource Bounds)
- The order creation is bounded in time (the service has a timeout).
- No unbounded query; no loading all products into memory.
-
-## The Schema (for completeness)
-
-```typescript
-const CreateOrderSchema = z.object({
-  userId: z.string().uuid(),
-  items: z.array(z.object({
-    productId: z.string().uuid(),
-    quantity: z.number().int().positive().max(100),
-  })).min(1).max(50),
-}).strict();  // additionalProperties: false
-```
-
- `userId` is a UUID (Data P7 Type Fidelity).
- `quantity` is bounded (Performance P4).
- `items` is bounded (1–50) (Performance P4, Security P10 Surface Minimization).
- `.strict()` rejects unknown fields (Security P4).
-
-## What This Example Does NOT Do (And Why That's Good)
-
- Does not return 200 on error — the status code is the first signal (API P9).
- Does not log the request body — may contain PII (Observability P6, Security P9).
- Does not construct SQL by string interpolation — uses a service layer (Security P5 Output Safety).
- Does not skip auth for "internal" callers — Zero Trust (Security P1).
@@ -1,88 +0,0 @@
-# Good Example: Database Schema
-
-> A SQL schema that follows Atelier's Data principles. Each aspect cites the principle it satisfies.
-
-## The Schema
-
-```sql
-- Users table
-CREATE TABLE users (
-  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  email       VARCHAR(255) NOT NULL,
-  name        VARCHAR(100) NOT NULL,
-  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
-  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
-  deleted_at  TIMESTAMPTZ,
-
-  CONSTRAINT users_email_unique UNIQUE (email),
-  CONSTRAINT users_email_format CHECK (email ~ '^[^@]+@[^@]+\.[^@]+$')
-);
-
-CREATE INDEX users_email_idx ON users (email) WHERE deleted_at IS NULL;
-CREATE INDEX users_created_at_idx ON users (created_at DESC);
-
-- Orders table
-CREATE TABLE orders (
-  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id     UUID NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
-  status      VARCHAR(20) NOT NULL DEFAULT 'pending',
-  total_cents INTEGER NOT NULL,
-  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
-
-  CONSTRAINT orders_status_valid CHECK (status IN ('pending', 'paid', 'shipped', 'cancelled')),
-  CONSTRAINT orders_total_positive CHECK (total_cents >= 0)
-);
-
-CREATE INDEX orders_user_id_idx ON orders (user_id);
-CREATE INDEX orders_status_created_idx ON orders (status, created_at DESC);
-```
-
-## What Makes It Good
-
-### Truth (Data P1)
- The schema reflects the domain: `users` have `email`, `name`, lifecycle timestamps. `orders` have `status`, `total`.
- No column named after a feature (`is_active_for_X`). No application state in the schema.
-
-### Invariants in the Schema (Data P3)
- `NOT NULL` where required: `email`, `name`, `user_id`, `status`, `total_cents`.
- `UNIQUE (email)` — emails are unique. Enforced in the DB, defended in the app.
- `CHECK (status IN (...))` — status is a finite domain. Enforced in the DB.
- `CHECK (total_cents >= 0)` — totals are non-negative. Enforced in the DB.
- `REFERENCES users(id) ON DELETE RESTRICT` — you cannot delete a user with orders. Referential integrity (P9).
-
-### Type Fidelity (Data P7)
- `id` is `UUID`, not `VARCHAR(36)`. The type matches the domain.
- `created_at` is `TIMESTAMPTZ`, not `VARCHAR` or `INTEGER`. Timezone-aware.
- `total_cents` is `INTEGER`, not `FLOAT`. Money in cents avoids floating point (P1 Truth).
- `status` is `VARCHAR(20)` with a CHECK, not a free `TEXT`. Bounded.
-
-### Naming Consistency (Data P6)
- snake_case: `users`, `orders`, `user_id`, `created_at`.
- Foreign key: `user_id` (singular table + `_id`), not `uid` or `user`.
- Timestamps: `created_at`, `updated_at`, `deleted_at` — consistent suffix `_at`.
-
-### Lifecycle Awareness (Data P8)
- `deleted_at` for soft delete. Lifecycle is first-class.
- The unique index on email is partial: `WHERE deleted_at IS NULL` — allows re-registration after soft delete.
- Every query must filter `deleted_at IS NULL` (a discipline, not a schema property).
-
-### Indexing with Intent (Data P5, P10)
- `users_email_idx` — queries by email (login, lookup). Partial (excludes soft-deleted).
- `users_created_at_idx` — list users by recency. DESC matches the typical query.
- `orders_user_id_idx` — list a user's orders. FK index (join performance).
- `orders_status_created_idx` — composite for "open orders by recency" (`WHERE status = 'pending' ORDER BY created_at DESC`).
- No index on every column. Each index serves a query.
-
-### Migration Safety (Data P4)
- This schema is created via a migration with an `up` and a `down`.
- The `down` drops the tables in reverse order (orders, then users) to respect FKs.
- Adding a column later uses expand-contract (nullable first, then constrained).
-
-## What This Example Does NOT Do (And Why That's Good)
-
- Does not use `FLOAT` for money — floating point errors (P7, P1).
- Does not use `VARCHAR` for the UUID — wrong type (P7).
- Does not omit the FK on `orders.user_id` — unenforced relationship (P9).
- Does not index every column — write amplification (P10, C8).
- Does not use `is_deleted BOOLEAN` without a timestamp — loses the deletion time (P8).
- Does not allow `status` to be free text — would lose the finite domain (P3).
@@ -1,139 +0,0 @@
-# Good Example: Error Handler
-
-> An error handler that follows Atelier's Errors principles. Each aspect cites the principle it satisfies.
-
-## The Handler
-
-```typescript
-// Centralized error middleware
-import { v4 as uuidv4 } from 'uuid';
-
-type AppError = {
-  code: string;
-  message: string;
-  statusCode: number;
-  details?: Record<string, unknown>;
-  cause?: unknown;
-};
-
-function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction) {
-  const requestId = req.headers['x-request-id'] as string || uuidv4();
-
-  const appError = normalizeError(err, requestId);
-
-  // Log with full context (server-side only)
-  logger.error({
-    request_id: requestId,
-    code: appError.code,
-    message: appError.message,
-    details: appError.details,
-    path: req.path,
-    method: req.method,
-    user_id: req.user?.id,
-    stack: err instanceof Error ? err.stack : undefined,
-  });
-
-  // Respond with safe, structured error
-  res.status(appError.statusCode).json({
-    error: {
-      code: appError.code,
-      message: appError.message,
-      request_id: requestId,
-      ...(appError.details ? { details: appError.details } : {}),
-    },
-  });
-}
-
-function normalizeError(err: unknown, requestId: string): AppError {
-  // Known error types — preserve their code and status
-  if (err instanceof ValidationError) {
-    return {
-      code: err.code,
-      message: err.message,
-      statusCode: 422,
-      details: err.details,
-    };
-  }
-  if (err instanceof NotFoundError) {
-    return { code: err.code, message: err.message, statusCode: 404 };
-  }
-  if (err instanceof AuthError) {
-    return { code: 'AUTH_REQUIRED', message: 'Authentication required', statusCode: 401 };
-  }
-
-  // Unknown error — fail securely, do not leak internals
-  return {
-    code: 'INTERNAL_ERROR',
-    message: 'An internal error occurred',
-    statusCode: 500,
-    cause: err,
-  };
-}
-```
-
-## What Makes It Good
-
-### Errors are Data (Errors P1)
- Errors are normalized into a structured `AppError` type. They are values, not raw exceptions.
- The `code` is a stable, machine-consumable string (`VALIDATION_FAILED`, not a free message).
- The handler treats every error as data to be transformed, not a flow to be caught.
-
-### Fail Loudly (Errors P2)
- No `catch (e) {}`. Every error reaches the handler.
- No silent swallowing. The error is logged and responded to.
- The middleware is centralized — every route uses it. No route can "forget" to handle errors.
-
-### Fail Specifically (Errors P3)
- `ValidationError` → 422 with `code: err.code` (specific, e.g., `INVALID_EMAIL`).
- `NotFoundError` → 404 with `code: err.code` (e.g., `USER_NOT_FOUND`).
- Unknown → 500 with `INTERNAL_ERROR` (generic only when truly unknown).
- Never "Something went wrong" — always a specific code.
-
-### Preserve Context (Errors P4)
- Server-side log includes: `request_id`, `code`, `message`, `details`, `path`, `method`, `user_id`, `stack`.
- Client-side response includes: `code`, `message`, `request_id`, `details`.
- The `request_id` ties the client response to the server log. Debuggable.
-
-### Recoverable When Possible (Errors P5)
- 422 (validation) — the client can fix and retry.
- 401 (auth) — the client can re-auth and retry.
- 404 (not found) — the client can correct the ID.
- Only 500 is "the server has a bug" — not recoverable by the client.
-
-### Unrecoverable Means Stop (Errors P6)
- A 500 does not limp on. It logs and returns.
- The server does not try to "recover" from an unknown error by guessing. It fails fast.
-
-### Errors are Boundaries (Errors P7)
- The middleware is the boundary. Internal error types (`ValidationError`, `NotFoundError`) are translated to HTTP responses here.
- Internal code throws domain errors; the boundary translates to HTTP. No internal error type leaks to the client.
-
-### User-Facing Errors are UX (Errors P8)
- `message` is for the developer (log + response). The client UI renders a user-facing message based on `code`.
- `INTERNAL_ERROR` → "Something went wrong. We're on it." (user-facing), not the stack.
-
-### Errors are Logged (Errors P9)
- Every error is logged at ERROR level with full context.
- The handling is the recovery (return a response); the log is the memory (investigate later).
-
-### Errors Don't Lie (Errors P10)
- The status code matches the error type. 422 for validation, not 200.
- `INTERNAL_ERROR` is returned only for unknown errors. Known errors get their specific code.
- Never claim success on failure. Never claim failure on success.
-
-### Security (Security P5 Output Safety, P9 Secret Hygiene)
- Unknown errors return `INTERNAL_ERROR` with no internal details. No stack trace to the client.
- The stack is logged server-side, never sent to the client.
- The error message does not echo the input (which may contain a token).
-
-### Observability (Observability P2 Correlation, P3 Context)
- `request_id` on every error. Correlatable across services.
- Sufficient context in the log: path, method, user_id. "What was the user doing?" is answerable.
-
-## What This Example Does NOT Do (And Why That's Good)
-
- Does not `catch (e) { return null }` — silent failure (P2).
- Does not return 200 with `{ error: ... }` — the status code lies (API P9).
- Does not send the stack trace to the client — information leak (Security P5).
- Does not log the request body — may contain secrets (Security P9, Observability P6).
- Does not use a generic `Error("error")` — not specific (P3).
@@ -1,108 +0,0 @@
-# Good Example: React Component
-
-> A UI component that follows Atelier's UI/UX principles. Each aspect cites the principle it satisfies.
-
-## The Component
-
-```tsx
-import { useId, useState } from 'react';
-import { Button } from './Button';
-import { Spinner } from './Spinner';
-
-type DeleteButtonProps = {
-  /** The resource name to display in the confirmation */
-  resourceName: string;
-  /** Called when the user confirms deletion */
-  onDelete: () => Promise<void>;
-};
-
-export function DeleteButton({ resourceName, onDelete }: DeleteButtonProps) {
-  const [isConfirming, setIsConfirming] = useState(false);
-  const [isDeleting, setIsDeleting] = useState(false);
-  const confirmId = useId();
-
-  const handleConfirm = async () => {
-    setIsDeleting(true);
-    try {
-      await onDelete();
-    } finally {
-      setIsDeleting(false);
-      setIsConfirming(false);
-    }
-  };
-
-  if (isConfirming) {
-    return (
-      <span role="group" aria-labelledby={confirmId}>
-        <span id={confirmId}>Delete {resourceName}? This cannot be undone.</span>
-        <Button variant="danger" onClick={handleConfirm} disabled={isDeleting}>
-          {isDeleting ? <Spinner label="Deleting" /> : 'Yes, delete'}
-        </Button>
-        <Button variant="ghost" onClick={() => setIsConfirming(false)} disabled={isDeleting}>
-          Cancel
-        </Button>
-      </span>
-    );
-  }
-
-  return (
-    <Button variant="danger" onClick={() => setIsConfirming(true)}>
-      Delete
-    </Button>
-  );
-}
-```
-
-## What Makes It Good
-
-### Single Responsibility (components.md §1)
- The component does one thing: confirm and trigger a deletion. No "And" in the name.
- The `onDelete` callback is the single output. The component owns the confirmation UI, not the deletion logic.
-
-### Explicit Boundaries (components.md §3)
- Props are typed (`DeleteButtonProps`). Required props are required.
- `onDelete` returns a `Promise<void>` — the caller knows it's async.
- The component never reads global state. It receives `resourceName` and `onDelete`.
-
-### Predictable State (components.md §4)
- `isConfirming` and `isDeleting` are owned by the component (only it cares).
- State is not duplicated. The parent does not know about confirmation.
- The component transitions: idle → confirming → deleting → idle.
-
-### Render Purity (components.md §5)
- Given the same props and state, the component renders the same output.
- Side effects (`onDelete`) are in the event handler, not in render.
- `useId()` is deterministic per component instance (React guarantee).
-
-### Accessible by Default (components.md §6, uiux P2)
- The confirmation group has `role="group"` and `aria-labelledby`.
- The Spinner has a `label` (screen reader announces "Deleting").
- Buttons have text labels (not icon-only).
- Focus order is logical (confirm → cancel).
- Keyboard-reachable (buttons are natively focusable).
-
-### Forgiveness (UI/UX P5, P10 Reversibility)
- Destructive action requires confirmation (P5).
- "This cannot be undone" names the consequence (P3 Clarity).
- "Cancel" is offered and is not disabled during deletion (the user can cancel the *next* action).
- The state is reversible: `isConfirming` can be set back to `false` (P10).
-
-### Style via Tokens (components.md §7)
- `variant="danger"` and `variant="ghost"` reference design tokens, not raw colors.
- No `style={{ color: 'red' }}` — the token system owns the visual.
-
-### Feedback (UI/UX P4)
- The button shows a Spinner while deleting (P4, P6 Performance perception).
- The button is disabled while deleting (prevents double-click).
- The label changes: "Yes, delete" → Spinner (state is communicated).
-
-### Clarity (UI/UX P3)
- "Delete {resourceName}? This cannot be undone." — specific, names the resource and the consequence.
- No "Are you sure?" — vague. No "Submit" — wrong verb.
-
-## What This Example Does NOT Do (And Why That's Good)
-
- Does not use a `window.confirm()` dialog — not accessible, not styled, not composable.
- Does not render a modal — the inline confirmation is lighter and less disruptive (P9 Simplicity).
- Does not auto-delete on click — forgiveness (P5).
- Does not hardcode "Project" — the resource name is a prop (composability, components.md §3).
@@ -1,82 +0,0 @@
-# Go — Language Application
-
-> How Atelier's domain principles apply in Go specifically. Derives from `domains/` docs.
-
-## Type System (C1 Correctness, Data P7 Type Fidelity)
-
- **Named types for domain concepts:** `type UserId string`, not bare `string`.
- **No `interface{}`/`any` without justification:** Go 1.18+ generics reduce the need.
- **`any` requires a type assertion or switch:** never use the value without narrowing.
-
-```go
-type UserId string
-type OrderId string
-// UserId and OrderId are distinct; cannot be mixed
-func GetUser(id UserId) (*User, error) { ... }
-```
-
-## Error Handling (Errors P1 Errors are Data)
-
- **Errors are values:** `error` is an interface, not an exception. Handle explicitly.
- **Sentinel errors with `errors.Is`:**
-```go
-var ErrNotFound = errors.New("not found")
-if errors.Is(err, ErrNotFound) { ... }
-```
- **Wrap with context:** `fmt.Errorf("get user %d: %w", id, err)`.
- **Never `_ = err`:** swallowed error (Errors P2). Handle or return.
- **Custom error types with `errors.As`:**
-```go
-type ValidationError struct {
-    Field string
-    Msg  string
-}
-func (e *ValidationError) Error() string { return e.Field + ": " + e.Msg }
-```
-
-## Concurrency (Concurrency — Go's strength)
-
- **Goroutines + channels** for message passing (P5 Lock Minimization).
- **`context.Context` for cancellation and timeout:** every function that does I/O takes a `ctx`.
- **`sync.Mutex` scoped minimally:** not held across I/O (P3 Lock Scope).
- **Bounded channels:** `make(chan T, N)`, not unbounded (P9 Bounded Queues).
-
-```go
-func fetchWithTimeout(ctx context.Context, url string) (*Response, error) {
-    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
-    defer cancel()
-    return doFetch(ctx, url)
-}
-```
-
-## Immutability (Concurrency P1)
-
- **Pass by value for small structs; pass by pointer for large or mutable.**
- **No mutation of method receivers:** use a value receiver, not a pointer receiver, for read-only methods.
- **Copy-on-write for shared state:** return a new struct, not a mutated one.
-
-## Nullability (C1)
-
- **Pointers can be nil; values cannot.** Be explicit: `*User` (nullable) vs `User` (not).
- **`nil` check before deref:** a nil deref is a panic.
- **Return `(T, error)`, not `(*T, nil)`:** avoid the "nil pointer" trap.
-
-## Testing (Testing)
-
- **`testing` package + `testify/assert`** or stdlib only.
- **Table-driven tests:** `[]struct{ name string; input X; want Y }`.
- **`t.Parallel()`** for independent tests (P2 Independence).
- **`httptest` for HTTP handlers; `sqlite` or testcontainers for DB.**
-
-## Observability (Observability P1)
-
- **`slog` (stdlib, Go 1.21+) or `zap`/`zerolog`:** structured logs.
- **`context.Context` carries `trace_id`:** propagated via middleware.
- **No `fmt.Println`:** use the logger.
-
-## Tooling (DevOps P2)
-
- **`go vet` + `golangci-lint`:** lint.
- **`gofmt`/`goimports`:** format (automated, not debated).
- **`go test -race` in CI:** race detector (Concurrency P6 No Silent Races).
- **`go mod tidy` + committed `go.sum`:** reproducible builds.
@@ -1,77 +0,0 @@
-# Python — Language Application
-
-> How Atelier's domain principles apply in Python specifically. Derives from `domains/` docs.
-
-## Type System (C1 Correctness, Data P7 Type Fidelity)
-
- **Type hints on every function:** `def get_user(id: UUID) -> User | None:`.
- **`mypy --strict` or `pyright` in CI:** type check is not optional.
- **No `Any` without justification:** `Any` disables the type checker. Use `object` + narrowing.
- **Pydantic for runtime validation:** schemas validate and type at the boundary.
-
-```python
-from pydantic import BaseModel
-from uuid import UUID
-
-class UserCreate(BaseModel):
-    email: str
-    name: str
-    # additionalProperties: false by default (extra='forbid')
-```
-
-## Error Handling (Errors P1 Errors are Data)
-
- **Exceptions for exceptional cases,** not control flow. `raise` not `return None` for errors.
- **Custom exception hierarchy:**
-```python
-class AppError(Exception): pass
-class ValidationError(AppError): pass
-class NotFoundError(AppError): pass
-```
- **Never bare `except:`:** `except Exception as e:` (catch specific, not everything).
- **Never `except: pass`:** log and re-raise or handle, never swallow (Errors P2).
-
-## Async (Concurrency P7, P8)
-
- **`asyncio` for I/O-bound:** `async def`, `await`. Not threads for I/O.
- **`anyio` for portability** if you may switch runtimes (trio compatibility).
- **Timeout on every `await`:** `asyncio.wait_for(coro, timeout=5)`, not bare `await`.
- **Cancellation propagated:** `asyncio.CancelledError` is not caught; it propagates.
-
-## Immutability (Concurrency P1)
-
- **`frozen=True` dataclasses** for value objects:
-```python
-from dataclasses import dataclass
-@dataclass(frozen=True)
-class UserId:
-    value: str
-```
- **Tuples over lists** for fixed-length, immutable sequences.
- **No in-place mutation of shared state:** return new objects.
-
-## Nullability (C1)
-
- **`Optional[T]` is `T | None`:** explicit, must be checked.
- **`None` is not "not found":** raise `NotFoundError` or return `Result`, not `None`.
- **`assert` is for invariants,** not for runtime checks (stripped with `-O`).
-
-## Testing (Testing)
-
- **pytest** with fixtures (factories, not shared state).
- **`pytest --randomly`** to catch order-dependent tests (P2 Independence).
- **`freezegun` for time:** no `datetime.now()` in tests; inject the clock.
- **`factory_boy` or `pytest-factoryboy`** for realistic factories.
-
-## Observability (Observability P1)
-
- **`structlog` or `python-json-logger`:** JSON logs, not `print`.
- **`logging` with structured formatter:** every log has `request_id`, `user_id`, `event`.
- **No secrets in logs:** `mask_secret()` helper, or `structlog` processors.
-
-## Tooling (DevOps P2)
-
- **`ruff` for lint + format:** replaces flake8 + black + isort.
- **`mypy --strict` in CI:** type check.
- **`pip-tools` or `poetry` for lockfile:** pinned dependencies.
- **`pip install --no-deps -r requirements.txt`:** reproducible install.
@@ -1,79 +0,0 @@
-# Rust — Language Application
-
-> How Atelier's domain principles apply in Rust specifically. Derives from `domains/` docs.
-
-## Type System (C1 Correctness, Data P7 Type Fidelity)
-
- **Newtypes for domain concepts:** `struct UserId(String);` — zero-cost, type-safe.
- **`enum` for finite domains:** `enum Status { Pending, Paid, Shipped }` — exhaustive.
- **No `unsafe` without justification and review:** `unsafe` opts out of the compiler's guarantees.
-
-```rust
-struct UserId(String);
-struct OrderId(String);
-// Cannot pass OrderId where UserId is expected
-fn get_user(id: UserId) -> Result<User, Error> { ... }
-```
-
-## Error Handling (Errors P1 Errors are Data)
-
- **`Result<T, E>` for fallible operations:** errors are values, not exceptions.
- **`thiserror` for error enums, `anyhow` for applications:**
-```rust
-#[derive(thiserror::Error)]
-enum AppError {
-    #[error("not found: {0}")]
-    NotFound(String),
-    #[error("validation: {0}")]
-    Validation(String),
-    #[error(transparent)]
-    Io(#[from] std::io::Error),
-}
-```
- **`?` for propagation, not `unwrap()`:** `unwrap()` panics in production.
- **No `panic::catch_unwind` for control flow:** panics are for bugs, not errors.
-
-## Concurrency (Concurrency — Rust's ownership model)
-
- **`Send` and `Sync` traits enforced by the compiler:** data races are compile errors.
- **`Arc<T>` for shared, `Mutex<T>`/`RwLock<T>` for mutation:** the lock is explicit.
- **`tokio` for async:** `async fn`, `.await`. Bounded channels (`tokio::sync::mpsc::channel(N)`).
- **`Drop` for cleanup:** no leaked resources (no `defer` needed; RAII).
-
-```rust
-async fn fetch_with_timeout(url: &str) -> Result<Response, Error> {
-    tokio::time::timeout(Duration::from_secs(5), fetch(url)).await??;
-}
-```
-
-## Immutability (Concurrency P1 Immutability by Default)
-
- **Variables are immutable by default:** `let x = 5;` not `let mut x = 5;`.
- **`&T` (shared ref) over `&mut T` (exclusive ref):** the compiler enforces aliasing rules.
- **Interior mutability (`Cell`/`RefCell`) only when needed:** not as a default.
-
-## Nullability (C1)
-
- **`Option<T>`, not nullable pointers:** `Some(x)` / `None`. The compiler enforces handling.
- **No `null`:** Rust has no null. `Option::None` is the explicit absence.
- **`?` on `Option` for propagation:** `fn get_name(user: User) -> Option<String> { user.profile?.name }`.
-
-## Testing (Testing)
-
- **`#[test]` + `#[cfg(test)] mod tests`:** tests co-located.
- **`proptest` or `quickcheck` for property-based tests:** edge case coverage (P9).
- **`tokio::test` for async tests.**
- **No `SystemTime::now()` in tests:** inject an `Instant` or a mock clock.
-
-## Observability (Observability P1)
-
- **`tracing` crate:** structured logs + spans + traces. Not `println!`.
- **`tracing::instrument` on functions:** automatic span context.
- **`tracing-subscriber` with JSON format:** structured output for production.
-
-## Tooling (DevOps P2)
-
- **`cargo clippy`:** lint. `cargo clippy -- -D warnings` in CI.
- **`cargo fmt`:** format.
- **`cargo test`:** tests. `cargo test --release` for perf-sensitive.
- **Committed `Cargo.lock`:** reproducible builds (even for libraries, for CI).
@@ -1,76 +0,0 @@
-# TypeScript — Language Application
-
-> How Atelier's domain principles apply in TypeScript specifically. Derives from `domains/` docs; this file is the language-specific lens.
-
-## Type System (C1 Correctness, Data P7 Type Fidelity)
-
- **Strict mode on:** `strict: true` in `tsconfig.json`. No `any` without justification.
- **No `any`, no `unknown` without narrowing:** `any` disables the type checker. `unknown` requires narrowing before use.
- **Discriminated unions over enums:** `type Status = { type: 'pending' } | { type: 'paid'; amount: number }` — exhaustive, type-safe.
- **Branded types for domain IDs:** `type UserId = string & { __brand: 'UserId' }` — prevents passing a `PostId` where a `UserId` is expected.
-
-```typescript
-type UserId = string & { readonly __brand: 'UserId' };
-function getUser(id: UserId): User { ... }
-// getUser("abc")          // type error
-// getUser("abc" as UserId) // ok
-```
-
-## Error Handling (Errors P1 Errors are Data)
-
- **Result type over exceptions for expected failures:**
-```typescript
-type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
-```
- **Exceptions for programmer errors:** null deref, invariant violation. Not for "user not found."
- **Never `any` in catch:** `catch (e: unknown)` then narrow with `instanceof` or a type guard.
-
-## Async (Concurrency P7 Cancellation Support, P8 Timeout Discipline)
-
- **`Promise` with `AbortSignal`:** every async function accepts an optional `AbortSignal` for cancellation.
- **`Promise.race` with a timeout:** never `await` without a timeout for external calls.
- **No `await` in a hot loop without batching:** use `Promise.all` for parallelism.
-
-```typescript
-async function fetchWithTimeout(url: string, signal?: AbortSignal): Promise<Response> {
-  const timeout = new AbortController();
-  signal?.addEventListener('abort', () => timeout.abort());
-  const timer = setTimeout(() => timeout.abort(), 5000);
-  try {
-    return await fetch(url, { signal: timeout.signal });
-  } finally {
-    clearTimeout(timer);
-  }
-}
-```
-
-## Immutability (Concurrency P1 Immutability by Default)
-
- **`readonly` on arrays and objects:** `readonly string[]`, `readonly { id: string }`.
- **`as const` for literals:** `const status = 'pending' as const`.
- **Immutable update patterns:** `spread` or `Immer` for nested updates, never mutation.
-
-## Nullability (C1 Correctness)
-
- **`strictNullChecks: true`:** `null` and `undefined` are distinct and must be handled.
- **No `!` (non-null assertion) without justification:** it disables the null check. Use narrowing.
- **`optional chaining` over `&&`:** `user?.profile?.name` not `user && user.profile && user.profile.name`.
-
-## Testing (Testing)
-
- **Jest or Vitest** with `ts-jest`/`vite`. Test files co-located: `user.ts` → `user.test.ts`.
- **Factories over fixtures:** `makeUser()` returns a fresh object per test.
- **No `Date.now()` in tests:** inject the clock. `jest.useFakeTimers()` or pass a `now` function.
-
-## Observability (Observability P1 Structured by Default)
-
- **Structured logger:** `pino` or `winston` in JSON mode. Not `console.log`.
- **`request_id` via middleware:** propagated on every log in the request.
- **No secrets in logs:** the logger redacts known secret fields (`pino` redact option).
-
-## Tooling (DevOps P2 Automation)
-
- **ESLint with `@typescript-eslint`** — strict ruleset.
- **Prettier** — format, not debated.
- **`tsc --noEmit` in CI** — type check without emitting.
- **`npm ci`** — lockfile install, not `npm install`.
Author	SHA1	Message	Date
Jon Chery	ebcae21630	docs(P04): complete matrix-review phase	2026-08-05 00:31:47 +00:00
Jon Chery	530ce3efed	docs(P03): complete domain-derived-docs phase	2026-08-05 00:30:31 +00:00
Jon Chery	2c15282ad4	docs(P02): complete domain-first-principles phase	2026-08-05 00:26:32 +00:00
Jon Chery	ae1a33028f	docs(P01): complete core-foundation phase	2026-08-05 00:25:07 +00:00
Jon Chery	ce29a2a213	docs(P00): complete pre-execution phase — ship v0.0.0 ---ci--- project: atelier phase: 0 milestone: v0.1 status: complete phase_role: pre_execution ship: tag: v0.0.0 merge: phase/00-pre-execution -> milestone/v0.1-atelier release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.0 ---/ci--- Config owner corrected: coreci -> cloudinit-bot (actual token owner). Phase 0 complete: 10 domain first-principles + matrix + MANIFEST + uiux docs shipped as v0.0.0.	2026-08-05 00:23:54 +00:00
Jon Chery	b8c89f1a74	docs(P00): complete pre-execution phase	2026-08-05 00:22:53 +00:00