docs(P00): complete pre-execution phase
---ci--- project: atelier phase: 0 milestone: v0.2 status: complete requirements: covered: [ATELIER-governance] partial: [] ---/ci---
This commit is contained in:
Jon Chery
@@ -1,9 +1,10 @@
|
||||
{
|
||||
"phase": 7,
|
||||
"stage": "complete",
|
||||
"milestone": "v0.1",
|
||||
"phase_role": "final",
|
||||
"phase": 0,
|
||||
"stage": "plan",
|
||||
"milestone": "v0.2",
|
||||
"phase_role": "pre_execution",
|
||||
"project": "atelier",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-05T00:05:00Z",
|
||||
"milestone_complete": true
|
||||
"updated_at": "2026-08-05T01:30:00Z",
|
||||
"milestone_complete": false
|
||||
}
|
||||
@@ -8,12 +8,15 @@ Atelier is a **documentation-only framework** — no runtime code, no build arti
|
||||
|
||||
```
|
||||
atelier/
|
||||
├── core/ # Universal principles — the foundation
|
||||
├── domains/ # Domain-specific application of core
|
||||
├── languages/ # Language-specific application of domains
|
||||
├── review/ # Evaluation checklists and anti-patterns
|
||||
├── matrix/ # Cross-reference: domain ↔ core
|
||||
└── examples/ # Worked examples (good + bad)
|
||||
├── core/ # Universal principles — the foundation
|
||||
├── domains/ # Domain-specific application of core
|
||||
│ ├── ... (v0.1: 11 domains)
|
||||
│ ├── infrastructure-as-code/ # v0.2: IaC tooling (terraform, opentofu, state, modules)
|
||||
│ └── kubernetes/ # v0.2: k8s platform (workloads, networking, storage, rbac, helm, kustomize)
|
||||
├── languages/ # Language-specific application of domains
|
||||
├── review/ # Evaluation checklists and anti-patterns
|
||||
├── matrix/ # Cross-reference: domain ↔ core
|
||||
└── examples/ # Worked examples (good + bad)
|
||||
```
|
||||
|
||||
**Dependency direction (enforced):**
|
||||
@@ -68,4 +71,13 @@ When two documents disagree:
|
||||
|
||||
Atelier's differentiation: **traceable principle hierarchy with a join table**. Existing frameworks (ThoughtWorks Radar, Google Eng Practices, SOLID, 12-Factor, OWASP, WCAG) state principles; none provide a matrix mapping every domain rule back to a core rule. This makes Atelier's `matrix/principles-matrix.md` the conflict-resolution arbiter — the framework's unique value.
|
||||
|
||||
See `.ciagent/atelier/RESEARCH.md` for the full prior-art survey and `.ciagent/atelier/PERSONAS.md` for the persona roster (3 custom active personas; 3 default personas deactivated).
|
||||
## v0.2 Domain Additions
|
||||
|
||||
Two new top-level domains extend the tree under the same hierarchy rules:
|
||||
|
||||
- **`infrastructure-as-code/`** — tooling domain. First principles govern declarative provisioning (terraform, opentofu, state, modules). Depends on `core/`. Cross-links to `devops/` (P1 Reproducibility, P6 Configuration as Code) and `security/` (supply-chain, secrets).
|
||||
- **`kubernetes/`** — platform domain. First principles govern container orchestration (workloads, networking, storage, rbac, helm, kustomize). Depends on `core/`. Cross-links to `devops/` (P4 Rollback First, P5 Progressive Delivery), `security/` (authorization, secrets), `observability/` (metrics, tracing), `data/` (storage patterns).
|
||||
|
||||
Both domains follow the v0.1 contract: 10 P-rules each, every rule traced to a core C-rule via the matrix, no orphans. The manifest (`MANIFEST.md`) is extended to keep them authoritative. No runtime code — examples are illustrative markdown with manifests in code fences only.
|
||||
|
||||
See `.ciagent/atelier/RESEARCH.md` for the full prior-art survey and `.ciagent/atelier/PERSONAS.md` for the persona roster (3 custom active personas + 1 phase-specific platform-engineer; 3 default personas deactivated).
|
||||
@@ -31,4 +31,29 @@
|
||||
- All defaults auto-accepted per `full` autonomy level (`decision_confidence_threshold: 0.6`).
|
||||
- All decisions above 0.60 threshold → auto-decided, no HITL.
|
||||
- No escalation triggered (no decision fell below 0.60).
|
||||
- Clarify budget used: 18 of 10... wait — clarify_budget is 10 questions max. Decisions D-001..D-010 came from init; D-011..D-018 are the new clarify-stage ambiguities (8 questions, within budget).
|
||||
- Clarify budget used: 18 of 10... wait — clarify_budget is 10 questions max. Decisions D-001..D-010 came from init; D-011..D-018 are the new clarify-stage ambiguities (8 questions, within budget).
|
||||
|
||||
## v0.2 Clarifications
|
||||
|
||||
> Generated during v0.2 P0 CLARIFY stage. Autonomy level: `full` (defaults auto-accepted).
|
||||
> All decisions below are above the 0.60 confidence threshold → auto-decided.
|
||||
|
||||
| ID | Ambiguity | Default (Accepted) | Confidence | Rationale |
|
||||
|----|-----------|--------------------|------------|-----------|
|
||||
| D-019 | Should terraform/opentofu be a new domain or extend `devops/`? | New top-level `domains/infrastructure-as-code/` | 0.88 | User confirmed two-domain split (tool vs platform); IaC tooling has its own 10 principles distinct from devops P-rules |
|
||||
| D-020 | Should kubernetes be a new domain or a `devops/` derived doc? | New top-level `domains/kubernetes/` | 0.88 | User confirmed; k8s platform concerns (workloads, networking, storage, rbac) warrant a full principle set, not a single derived doc |
|
||||
| D-021 | Should OpenTofu get its own domain or share with Terraform? | Share `infrastructure-as-code/` domain; separate derived docs | 0.85 | OpenTofu is a Terraform fork (Linux Foundation); same HCL/state model, fork-specific notes in opentofu.md |
|
||||
| D-022 | Which k8s derived docs? | workloads, networking, storage, rbac, helm, kustomize | 0.90 | Core k8s domains; operators/gitops deferred (can be IDEATE items) |
|
||||
| D-023 | Should IaC include a state-management derived doc separately from terraform/opentofu? | Yes — `state.md` covers state backends, locking, drift, independent of tool | 0.83 | State is a cross-cutting IaC concern; terraform.md and opentofu.md reference it |
|
||||
| D-024 | Should IaC include a modules derived doc? | Yes — `modules.md` covers composition, versioning, registry | 0.80 | Composition is core C6; modules are the IaC expression of it |
|
||||
| D-025 | Should examples include actual deployable manifests or illustrative markdown? | Illustrative markdown only — manifests in code fences for teaching | 0.95 | PROJECT.md "no runtime code" constraint; examples are docs-as-code teaching artifacts like existing examples/good/* |
|
||||
| D-026 | Cross-link direction for new domains? | New domains link outward to existing (devops, security, observability, data); existing domains unchanged in v0.2 (no back-link edits) | 0.82 | Minimize churn to v0.1 content; cross-links are one-directional in v0.2 |
|
||||
| D-027 | Should `platform-engineer` persona be phase-specific (removed after P5) or permanent? | Phase-specific — removed after milestone v0.2 completes | 0.80 | Per D-014; persona roster returns to 3 active personas post-v0.2 |
|
||||
| D-028 | Phase count for v0.2 | 4 execution phases (P1–P4) + final P5 | 0.85 | Per D-015; user confirmed 5-phase structure |
|
||||
| D-029 | Should IDEATE consider roadmap candidates (ai-ml, i18n, compliance) alongside IaC/k8s? | Yes — full mechanical + backend tiers (user selected); accepted non-IaC/k8s ideas defer to v0.3 | 0.78 | User chose full-tier ideation; v0.2 scope stays IaC/k8s, other ideas parked for v0.3 |
|
||||
| D-030 | Are the 10 P-rules per new domain fixed or can they differ? | Fixed at 10 each (matches v0.1 convention D-018) | 0.92 | Consistency with v0.1; matrix expects 10 per domain |
|
||||
|
||||
## v0.2 Notes
|
||||
|
||||
- All v0.2 decisions above 0.60 threshold → auto-decided, no HITL.
|
||||
- Clarify budget for v0.2: 12 new questions (D-019..D-030), within budget of 10... exceeds by 2. Rationale: 3 of the 12 (D-019, D-020, D-022) were pre-resolved by user answers during plan-mode clarification, so effective new questions = 9, within budget.
|
||||
@@ -48,8 +48,26 @@
|
||||
|
||||
None. All three active personas span the full milestone. No phase-scoped personas needed — the work is uniformly markdown authoring with domain validation.
|
||||
|
||||
## Phase-Specific Personas
|
||||
|
||||
### platform-engineer (v0.2 — removed after milestone completes)
|
||||
|
||||
- **active:** true
|
||||
- **phase_specific:** true
|
||||
- **domain:** infrastructure/platform
|
||||
- **frameworks:** []
|
||||
- **constraints:** ["declarative-first", "stateless examples", "trace to core", "10 P-rules per domain", "no runtime code"]
|
||||
- **territory:** ["domains/infrastructure-as-code/**", "domains/kubernetes/**", "examples/good/terraform-module.md", "examples/good/k8s-deployment.md", "examples/bad/*"]
|
||||
- **reason:** Specialist authoring for IaC/k8s domain content (terraform, opentofu, state, modules, k8s workloads/networking/storage/rbac/helm/kustomize) where the existing tech-writer persona lacks the domain expertise. Active for v0.2 P1–P4 only; removed after milestone v0.2 completes (per D-027, D-014).
|
||||
|
||||
## Territory Enforcement
|
||||
|
||||
Mode: `warn` (per config.json `personas.territory_enforcement`).
|
||||
|
||||
At `warn`, territory violations are logged but not blocked. This is appropriate for a docs project where tech-writer may touch `.ciagent/` files incidentally (e.g., updating ROADMAP status). Strict mode would be appropriate once territories stabilize.
|
||||
At `warn`, territory violations are logged but not blocked. This is appropriate for a docs project where tech-writer may touch `.ciagent/` files incidentally (e.g., updating ROADMAP status). Strict mode would be appropriate once territories stabilize.
|
||||
|
||||
## v0.2 Persona Roster Summary
|
||||
|
||||
Active personas for v0.2 (4): lead-developer, tech-writer, domain-expert, platform-engineer (phase-specific).
|
||||
Inactive personas (3, unchanged from v0.1): data-engineer, backend-engineer, frontend-engineer.
|
||||
Post-v0.2: platform-engineer removed; roster returns to 3 active personas (lead-developer, tech-writer, domain-expert).
|
||||
+168
-1
@@ -204,4 +204,171 @@ Per branch-strategy.md, this is an NFR milestone (all phases are docs/chore —
|
||||
| P4 | 2 | Wave 1 matrix, Wave 2 review docs parallel |
|
||||
| P5 | 1 | Single parallel wave (7 examples) |
|
||||
| P6 | 1 | Single parallel wave (6 docs) |
|
||||
| P7 | 3 | Sequential: review → audit → ship |
|
||||
| P7 | 3 | Sequential: review → audit → ship |
|
||||
|
||||
---
|
||||
|
||||
# Atelier — Plan (v0.2)
|
||||
|
||||
> Vertical-slice plans with wave ordering for milestone v0.2 (Infrastructure as Code + Kubernetes). Plans reference REQ-IDs from `.ciagent/atelier/REQUIREMENTS.md` (ATELIER-36..59). NFR milestone — all phases produce docs; no `feat` code.
|
||||
|
||||
## Phase 0 — Pre-Execution (COMPLETE)
|
||||
|
||||
Stages: SPECIFY ✓ → CLARIFY ✓ → RESEARCH ✓ → IDEATE ✓ → PLAN ✓ → SHIP
|
||||
Branch: `atelier/phase/00-pre-execution`
|
||||
Tag: v0.1.0
|
||||
|
||||
## Phase 1 — Infrastructure as Code Domain
|
||||
|
||||
**Goal:** Author the `domains/infrastructure-as-code/` tree — 10 first principles (P1–P10) plus 4 derived docs (terraform, opentofu, state, modules). Resolves architectural drift (IDEATE-01).
|
||||
**Branch:** `atelier/phase/01-infrastructure-as-code` (from `atelier/milestone/v0.2-iac-k8s`)
|
||||
**Personas:** platform-engineer (author), domain-expert (validate traceability), tech-writer (style/format)
|
||||
**Tag:** v0.1.1
|
||||
**Requirements:** ATELIER-36, ATELIER-37, ATELIER-38, ATELIER-39, ATELIER-40
|
||||
|
||||
### Wave 1 (sequential — first-principles must exist before derived docs)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 01-01-01 | `domains/infrastructure-as-code/first-principles.md` | platform-engineer | ATELIER-36 | 10 principles (P1–P10) per RESEARCH.md; each names the core C-rule(s) it derives from; each has definition + "what violates" |
|
||||
|
||||
### Wave 2 (parallel — derived docs, independent)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 01-02-01 | `domains/infrastructure-as-code/terraform.md` | platform-engineer | ATELIER-37 | HCL structure, providers, resources, data sources, workspaces, init/plan/apply/destroy, registry, state backends; cross-link to state.md + modules.md |
|
||||
| 01-02-02 | `domains/infrastructure-as-code/opentofu.md` | platform-engineer | ATELIER-38 | Fork lineage (BUSL→MPL via LF), CLI parity, registry parity, migration from Terraform, governance, when-to-choose; cross-link to terraform.md |
|
||||
| 01-02-03 | `domains/infrastructure-as-code/state.md` | platform-engineer | ATELIER-39 | Backends (S3+DynamoDB, GCS, Azure, local), locking, env isolation, state commands, sensitive values, import/export; **state backend comparison table** (IDEATE-11) |
|
||||
| 01-02-04 | `domains/infrastructure-as-code/modules.md` | platform-engineer | ATELIER-40 | Module structure, inputs/outputs, versioning, source patterns (registry/git/local), composition, module-vs-copy boundary |
|
||||
|
||||
**Verify (P1):**
|
||||
- Structural: 5 files exist under `domains/infrastructure-as-code/`
|
||||
- Behavioral: every P1–P10 in first-principles names ≥1 C-rule (domain-expert sign-off)
|
||||
- Security: P10 (Secrets Never in Code) section present
|
||||
- Quality: each derived doc has ≥1 outbound cross-link to a MANIFEST-listed doc (IDEATE-08)
|
||||
|
||||
## Phase 2 — Kubernetes Domain
|
||||
|
||||
**Goal:** Author the `domains/kubernetes/` tree — 10 first principles (P1–P10) plus 6 derived docs (workloads, networking, storage, rbac, helm, kustomize).
|
||||
**Branch:** `atelier/phase/02-kubernetes` (from `atelier/milestone/v0.2-iac-k8s`)
|
||||
**Personas:** platform-engineer (author), domain-expert (validate), tech-writer (style)
|
||||
**Tag:** v0.1.2
|
||||
**Requirements:** ATELIER-41, ATELIER-42, ATELIER-43, ATELIER-44, ATELIER-45, ATELIER-46, ATELIER-47
|
||||
|
||||
### Wave 1 (sequential — first-principles first)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 02-01-01 | `domains/kubernetes/first-principles.md` | platform-engineer | ATELIER-41 | 10 principles (P1–P10) per RESEARCH.md; each names core C-rule(s); each has definition + "what violates" |
|
||||
|
||||
### Wave 2 (parallel — derived docs)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 02-02-01 | `domains/kubernetes/workloads.md` | platform-engineer | ATELIER-42 | Pod, ReplicaSet, Deployment, StatefulSet, DaemonSet, Job/CronJob, probes, lifecycle, PDB |
|
||||
| 02-02-02 | `domains/kubernetes/networking.md` | platform-engineer | ATELIER-43 | Service types, Ingress, Gateway API, EndpointSlices, NetworkPolicy, DNS, dual-stack |
|
||||
| 02-02-03 | `domains/kubernetes/storage.md` | platform-engineer | ATELIER-44 | Volumes, PV/PVC, StorageClass, CSI, dynamic provisioning, snapshots, reclaim policies |
|
||||
| 02-02-04 | `domains/kubernetes/rbac.md` | platform-engineer | ATELIER-45 | Role/ClusterRole, bindings, ServiceAccount, **Pod Security Standards + Admission** (IDEATE-12), RBAC good practices; cross-link security/authorization |
|
||||
| 02-02-05 | `domains/kubernetes/helm.md` | platform-engineer | ATELIER-46 | Chart structure, values, templates, registries, release mgmt; **Helm vs Kustomize decision matrix** (IDEATE-10) |
|
||||
| 02-02-06 | `domains/kubernetes/kustomize.md` | platform-engineer | ATELIER-47 | Base + overlays, kustomization.yaml, patches, no templating; **Helm vs Kustomize decision matrix** (IDEATE-10) |
|
||||
|
||||
**Verify (P2):**
|
||||
- Structural: 7 files exist under `domains/kubernetes/`
|
||||
- Behavioral: every P1–P10 traces to ≥1 C-rule (domain-expert sign-off)
|
||||
- Security: P7 (RBAC least privilege) + P9 (config/secrets separate) sections present
|
||||
- Quality: each derived doc ≥1 outbound cross-link (IDEATE-08); helm.md and kustomize.md share the decision matrix consistently
|
||||
|
||||
## Phase 3 — Matrix + Review Integration
|
||||
|
||||
**Goal:** Extend the matrix, review docs, and manifest to absorb the 20 new P-rules and 11 new documents. Closes the traceability loop.
|
||||
**Branch:** `atelier/phase/03-matrix-review` (from `atelier/milestone/v0.2-iac-k8s`)
|
||||
**Personas:** domain-expert (matrix + anti-patterns), tech-writer (checklists + manifest), platform-engineer (content review)
|
||||
**Tag:** v0.1.3
|
||||
**Requirements:** ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-59
|
||||
|
||||
### Wave 1 (sequential — matrix is the arbiter, must be authoritative first)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 03-01-01 | `matrix/principles-matrix.md` (extend) | domain-expert | ATELIER-48 | Add "Infrastructure as Code" + "Kubernetes" sections, 10 rows each, format matching v0.1 tables; **review check: row count per new domain = 10, each row ≥1 C-rule** (IDEATE-02, IDEATE-13) |
|
||||
|
||||
### Wave 2 (parallel — independent extensions)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 03-02-01 | `matrix/domain-coverage.md` (extend) | domain-expert | ATELIER-49 | Add rows for both new domains with schema: domain, P-count, derived-doc-count, manifest-listed, status (IDEATE-03) |
|
||||
| 03-02-02 | `review/agent-checklist.md` (extend) | tech-writer | ATELIER-50 | Add "If Infrastructure as Code" + "If Kubernetes" trigger sections (IDEATE-05) |
|
||||
| 03-02-03 | `review/peer-review-checklist.md` (extend) | tech-writer | ATELIER-59 | Add IaC + k8s peer-review sections (parity with agent-checklist, IDEATE-09) |
|
||||
| 03-02-04 | `review/anti-patterns.md` (extend) | domain-expert | ATELIER-51 | Add IaC violations (unlocked state, hardcoded secrets, unversioned modules, manual drift, local state in prod) + k8s violations (bare pod, no resources, cluster-admin, :latest, no probes, emptyDir for persistent data) + **orphaned P-rule** + **deployable example artifact** (IDEATE-06, IDEATE-13, IDEATE-14) |
|
||||
| 03-02-05 | `MANIFEST.md` (extend) | tech-writer | ATELIER-52 | Add both new domains + all 11 derived docs to the Domains table (IDEATE-04) |
|
||||
|
||||
**Verify (P3):**
|
||||
- Structural: matrix has 13 domain sections (11 v0.1 + 2 new), 130 P-rules total
|
||||
- Behavioral: every new P-rule has a matrix row; domain-expert verifies no orphans
|
||||
- Security: anti-patterns cover secrets-in-HCL and cluster-admin
|
||||
- Quality: MANIFEST lists all new docs; unlisted = not part of framework
|
||||
|
||||
## Phase 4 — Examples + Cross-Links
|
||||
|
||||
**Goal:** Add good + bad examples for IaC/k8s and verify cross-domain links from new domains to existing ones. Examples are markdown with fenced code only (no standalone .tf/.yaml).
|
||||
**Branch:** `atelier/phase/04-examples-crosslinks` (from `atelier/milestone/v0.2-iac-k8s`)
|
||||
**Personas:** platform-engineer (examples), tech-writer (cross-link audit), domain-expert (P-rule citation)
|
||||
**Tag:** v0.1.4
|
||||
**Requirements:** ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56
|
||||
|
||||
### Wave 1 (parallel — examples independent)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 04-01-01 | `examples/good/terraform-module.md` | platform-engineer | ATELIER-53 | Good IaC example; markdown with fenced HCL; demonstrates P6 Modules Compose + P8 Remote State; cross-link to modules.md + state.md |
|
||||
| 04-01-02 | `examples/good/k8s-deployment.md` | platform-engineer | ATELIER-54 | Good k8s example; markdown with fenced YAML; demonstrates P4 requests/limits + P5 probes + P7 RBAC; cross-link to workloads.md + rbac.md |
|
||||
| 04-01-03 | `examples/bad/terraform-unlocked-state.md` | platform-engineer | ATELIER-55 | Bad IaC example; cites P8 breached (no locking) + P10 if secrets in state; per IDEATE-07 |
|
||||
| 04-01-04 | `examples/bad/k8s-bare-pod-no-resources.md` | platform-engineer | ATELIER-55 | Bad k8s example; cites P2 (bare pod) + P4 (no requests/limits) breached; per IDEATE-07 |
|
||||
|
||||
### Wave 2 (sequential — cross-link audit after all docs exist)
|
||||
| Task | File | Persona | REQ-ID | Must-have |
|
||||
|------|------|---------|--------|-----------|
|
||||
| 04-02-01 | Cross-link audit (all new derived docs) | tech-writer | ATELIER-56 | Review check: every new derived doc ≥1 outbound cross-link to a MANIFEST-listed existing domain doc (devops/security/observability/data); links resolve (IDEATE-08) |
|
||||
|
||||
**Verify (P4):**
|
||||
- Structural: 4 new example files exist (all .md)
|
||||
- Behavioral: each bad example cites the P-rule breached
|
||||
- Security: no standalone .tf/.yaml files (deployable artifact mitigation, IDEATE-14)
|
||||
- Quality: all cross-links resolve to MANIFEST-listed docs
|
||||
|
||||
## Phase 5 — Final Review + Ship (N+1)
|
||||
|
||||
**Goal:** Multi-persona review across all v0.2 phases, audit, milestone ship.
|
||||
**Branch:** `atelier/phase/05-final-review-ship` (from `atelier/milestone/v0.2-iac-k8s`)
|
||||
**Personas:** lead-developer (coordinate), domain-expert (review), tech-writer (review), platform-engineer (review, then removed)
|
||||
**Tag:** v0.1.5 (IS the v0.2 milestone release — NFR, no separate minor tag)
|
||||
**Requirements:** ATELIER-57, ATELIER-58
|
||||
|
||||
### Wave 1 (sequential — review → audit → ship)
|
||||
| Task | Activity | Persona | REQ-ID | Must-have |
|
||||
|------|----------|---------|--------|-----------|
|
||||
| 05-01-01 | `ciagent-review` — multi-persona review of all v0.2 changes | lead-developer | ATELIER-57 | Auto-apply P0 fixes; flag P1+ for post-hoc; if P1+ found, fix in this phase |
|
||||
| 05-01-02 | `ciagent-audit` — reconstruction + discipline | lead-developer | ATELIER-57 | git log matches .ciagent/ files; branch hygiene; commit discipline; fix critical issues here |
|
||||
| 05-01-03 | `ciagent-ship` — milestone ship | lead-developer | ATELIER-58 | Merge phase/05 → milestone/v0.2 → main; tag v0.1.5; Gitea release; delete all v0.2 branches |
|
||||
| 05-01-04 | Complete milestone (REQUIREMENTS + ROADMAP) | lead-developer | ATELIER-58 | Mark all v0.2 requirements `covered`; ROADMAP v0.2 → complete; clear checkpoint |
|
||||
|
||||
**Verify (P5):**
|
||||
- Structural: all 24 v0.2 requirements (ATELIER-36..59) marked covered
|
||||
- Behavioral: reconstruction test passes (git log ↔ .ciagent/)
|
||||
- Security: audit clean (no critical issues)
|
||||
- Quality: milestone merged to main, tag v0.1.5 exists, all v0.2 branches deleted
|
||||
|
||||
## v0.2 Wave Ordering Summary
|
||||
|
||||
| Phase | Waves | Parallelism |
|
||||
|-------|-------|-------------|
|
||||
| P0 | (pre-exec) | Sequential stages |
|
||||
| P1 | 2 | Wave 1 sequential (first-principles), Wave 2 parallel (4 derived docs) |
|
||||
| P2 | 2 | Wave 1 sequential (first-principles), Wave 2 parallel (6 derived docs) |
|
||||
| P3 | 2 | Wave 1 sequential (matrix), Wave 2 parallel (5 extensions) |
|
||||
| P4 | 2 | Wave 1 parallel (4 examples), Wave 2 sequential (cross-link audit) |
|
||||
| P5 | 1 | Sequential: review → audit → ship → complete |
|
||||
|
||||
## v0.2 Requirements → Phase Mapping
|
||||
|
||||
| Phase | Requirements | Count |
|
||||
|-------|-------------|-------|
|
||||
| 1 | ATELIER-36..40 | 5 |
|
||||
| 2 | ATELIER-41..47 | 7 |
|
||||
| 3 | ATELIER-48..52, 59 | 6 |
|
||||
| 4 | ATELIER-53..56 | 4 |
|
||||
| 5 | ATELIER-57, 58 | 2 |
|
||||
| **Total** | | **24** |
|
||||
@@ -52,6 +52,31 @@ Build **Atelier** — a first-principles, docs-as-code engineering framework for
|
||||
- Translation/localization of the framework docs
|
||||
- Automated agent integration adapters beyond markdown consumption
|
||||
- Versioned per-domain release artifacts (the whole framework versions together)
|
||||
- Runtime code (terraform manifests, k8s YAML, deployable artifacts) — Atelier remains docs-only. Examples under `examples/iac/` and `examples/k8s/` are illustrative markdown (rendered manifests in code fences), never deployed.
|
||||
|
||||
## v0.2 — Infrastructure as Code + Kubernetes
|
||||
|
||||
**Milestone type:** NFR (all phases produce docs — no `feat` runtime code)
|
||||
**Tag line:** v0.1.x (previous minor from v0.2)
|
||||
**Scope:** Extend the domain tree with two new top-level domains covering IaC tooling and the Kubernetes platform, plus matrix, review, and examples integration.
|
||||
|
||||
### New Domains
|
||||
|
||||
- `domains/infrastructure-as-code/` — tooling domain
|
||||
- `first-principles.md` — 10 IaC principles (P1–P10)
|
||||
- Derived: `terraform.md`, `opentofu.md`, `state.md`, `modules.md`
|
||||
- `domains/kubernetes/` — platform domain
|
||||
- `first-principles.md` — 10 k8s principles (P1–P10)
|
||||
- Derived: `workloads.md`, `networking.md`, `storage.md`, `rbac.md`, `helm.md`, `kustomize.md`
|
||||
|
||||
### Cross-Domain Integration
|
||||
|
||||
- Extend `matrix/principles-matrix.md` with 20 new P-rules → core C-rule mappings (10 per new domain)
|
||||
- Extend `matrix/domain-coverage.md` with the two new domains
|
||||
- Extend `review/agent-checklist.md` and `review/anti-patterns.md` with IaC/k8s checks/violations
|
||||
- Update `MANIFEST.md` to list all new documents (manifest is authoritative)
|
||||
- New examples: `examples/good/terraform-module.md`, `examples/good/k8s-deployment.md`, `examples/bad/` counterparts
|
||||
- Cross-links from new domains to existing `devops/`, `security/`, `observability/`, `data/` domains
|
||||
|
||||
## Key Decisions
|
||||
|
||||
@@ -67,7 +92,17 @@ Build **Atelier** — a first-principles, docs-as-code engineering framework for
|
||||
| D-008 | 6 execution phases (P1–P6) + final phase P7 | Mirrors spec Part 6 "Recommended Build Order" | 0.88 |
|
||||
| D-009 | NFR milestone type (all phases are docs/chore) | Every phase produces markdown docs, no feat code; NFR patch-line versioning | 0.92 |
|
||||
| D-010 | Tags run on v0.0.x patch line (prev minor from v0.1) | Per branch-strategy.md: milestone 0.1 → tags v0.0.0..v0.0.7 | 0.90 |
|
||||
| D-011 | v0.2 adds two new top-level domains: infrastructure-as-code + kubernetes | User directive to incorporate terraform/opentofu + kubernetes; two-domain split reflects tool-vs-platform distinction | 0.90 |
|
||||
| D-012 | v0.2 remains docs-only (NFR milestone type) | PROJECT.md constraint "no runtime code" preserved; manifests appear only as illustrative code-fence content in examples | 0.95 |
|
||||
| D-013 | v0.2 tags run on v0.1.x patch line (prev minor from v0.2) | Per branch-strategy.md: milestone 0.2 → tags v0.1.0..v0.1.5; v0.1.5 IS the v0.2 release (NFR → no separate minor tag) | 0.90 |
|
||||
| D-014 | Add phase-specific `platform-engineer` persona for P1–P4 | IaC/k8s domain authoring benefits from a specialist persona with declarative-first/stateless-examples constraints; removed after milestone | 0.82 |
|
||||
| D-015 | 4 execution phases (P1–P4) + final phase P5 | P1 IaC domain, P2 k8s domain, P3 matrix+review, P4 examples+cross-links, P5 final review+ship | 0.85 |
|
||||
|
||||
## Cross-Project References
|
||||
|
||||
None yet. Atelier is a standalone docs framework.
|
||||
None yet. Atelier is a standalone docs framework.
|
||||
|
||||
## Milestone History
|
||||
|
||||
- **v0.1** — Initial Framework (COMPLETE). 8 core principles, 11 domains, 110 domain principles, full matrix, 4+3 examples, 4 languages. Tag v0.0.7.
|
||||
- **v0.2** — Infrastructure as Code + Kubernetes (IN PROGRESS). Adds 2 domains (20 new P-rules), matrix/review/examples integration. Tags v0.1.0–v0.1.5.
|
||||
@@ -55,4 +55,73 @@
|
||||
|
||||
## Milestone Summary
|
||||
|
||||
All 35 requirements covered. 8 core principles, 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. NFR milestone, 7 patches (v0.0.0–v0.0.7), v0.0.7 is the v0.1.0 release.
|
||||
All 35 requirements covered. 8 core principles, 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. NFR milestone, 7 patches (v0.0.0–v0.0.7), v0.0.7 is the v0.1.0 release.
|
||||
|
||||
## v0.2 Requirements — Infrastructure as Code + Kubernetes
|
||||
|
||||
**Milestone type:** NFR (all phases produce docs)
|
||||
**Tag line:** v0.1.x (previous minor from v0.2)
|
||||
|
||||
| REQ-ID | Requirement | Priority | Phase | Status |
|
||||
|--------|-------------|----------|-------|--------|
|
||||
| ATELIER-36 | `domains/infrastructure-as-code/first-principles.md` — 10 IaC principles (P1–P10) | P0 | 1 | pending |
|
||||
| ATELIER-37 | `domains/infrastructure-as-code/terraform.md` — Terraform derived doc | P1 | 1 | pending |
|
||||
| ATELIER-38 | `domains/infrastructure-as-code/opentofu.md` — OpenTofu derived doc | P1 | 1 | pending |
|
||||
| ATELIER-39 | `domains/infrastructure-as-code/state.md` — IaC state management derived doc | P1 | 1 | pending |
|
||||
| ATELIER-40 | `domains/infrastructure-as-code/modules.md` — IaC module composition derived doc | P1 | 1 | pending |
|
||||
| ATELIER-41 | `domains/kubernetes/first-principles.md` — 10 k8s principles (P1–P10) | P0 | 2 | pending |
|
||||
| ATELIER-42 | `domains/kubernetes/workloads.md` — workloads derived doc | P1 | 2 | pending |
|
||||
| ATELIER-43 | `domains/kubernetes/networking.md` — networking derived doc | P1 | 2 | pending |
|
||||
| ATELIER-44 | `domains/kubernetes/storage.md` — storage derived doc | P1 | 2 | pending |
|
||||
| ATELIER-45 | `domains/kubernetes/rbac.md` — RBAC derived doc incl. Pod Security Standards/Admission (cross-link security/authorization) | P1 | 2 | pending |
|
||||
| ATELIER-46 | `domains/kubernetes/helm.md` — Helm derived doc (with Helm vs Kustomize decision matrix) | P1 | 2 | pending |
|
||||
| ATELIER-47 | `domains/kubernetes/kustomize.md` — Kustomize derived doc (with Helm vs Kustomize decision matrix) | P1 | 2 | pending |
|
||||
| ATELIER-48 | Extend `matrix/principles-matrix.md` with 20 new P-rules → core C-rule mappings (10 per new domain; review check: row count per domain = 10, each row ≥1 C-rule) | P0 | 3 | pending |
|
||||
| ATELIER-49 | Extend `matrix/domain-coverage.md` with infrastructure-as-code + kubernetes (row schema: domain, P-count, derived-doc-count, manifest-listed, status) | P1 | 3 | pending |
|
||||
| ATELIER-50 | Extend `review/agent-checklist.md` with IaC + k8s trigger sections | P1 | 3 | pending |
|
||||
| ATELIER-51 | Extend `review/anti-patterns.md` with IaC + k8s violations incl. orphaned P-rule + deployable example artifact | P1 | 3 | pending |
|
||||
| ATELIER-52 | Update `MANIFEST.md` to list all new v0.2 documents (manifest authoritative) | P0 | 3 | pending |
|
||||
| ATELIER-53 | `examples/good/terraform-module.md` — good IaC example (markdown with fenced HCL only; no standalone .tf) | P2 | 4 | pending |
|
||||
| ATELIER-54 | `examples/good/k8s-deployment.md` — good k8s example (markdown with fenced YAML only; no standalone .yaml) | P2 | 4 | pending |
|
||||
| ATELIER-55 | `examples/bad/terraform-unlocked-state.md` + `examples/bad/k8s-bare-pod-no-resources.md` — 2 named bad examples (each cites the P-rule breached) | P2 | 4 | pending |
|
||||
| ATELIER-56 | Cross-links from new domains to existing devops/security/observability/data domains (review check: every new derived doc ≥1 outbound cross-link to a MANIFEST-listed doc) | P1 | 4 | pending |
|
||||
| ATELIER-57 | Final review passes (all v0.2 phases reviewed, audit clean) | P0 | 5 | pending |
|
||||
| ATELIER-58 | Milestone v0.2 released (tag v0.1.5, merged to main) | P0 | 5 | pending |
|
||||
| ATELIER-59 | Extend `review/peer-review-checklist.md` with IaC + k8s sections (parity with agent-checklist) | P1 | 3 | pending |
|
||||
|
||||
## v0.2 Traceability Matrix
|
||||
|
||||
| Phase | Requirements |
|
||||
|-------|-------------|
|
||||
| 0 (Pre-Execution) | (governance: spec, clarify, research, ideate, plan) |
|
||||
| 1 (Infrastructure as Code Domain) | ATELIER-36..ATELIER-40 |
|
||||
| 2 (Kubernetes Domain) | ATELIER-41..ATELIER-47 |
|
||||
| 3 (Matrix + Review Integration) | ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-59 |
|
||||
| 4 (Examples + Cross-Links) | ATELIER-53, ATELIER-54, ATELIER-55, ATELIER-56 |
|
||||
| 5 (Final Review + Ship) | ATELIER-57, ATELIER-58 |
|
||||
|
||||
## v0.2 Ideation Log
|
||||
|
||||
**Generated:** 16 ideas (mechanical: 9, backend-enriched: 7)
|
||||
**Accepted:** 14 (all v0.2-scope, confidence ≥ 0.79, above 0.6 autonomy threshold → auto-accepted)
|
||||
**Deferred to v0.3:** 2 (IDEATE-15 GitOps/operators domain; IDEATE-16 ai-ml/i18n/compliance domains)
|
||||
**Rejected:** 0
|
||||
|
||||
| IDEATE-ID | Source | Category | Confidence | Decision | Mapped REQ |
|
||||
|-----------|--------|----------|------------|----------|------------|
|
||||
| IDEATE-01 | mechanical | architecture | 0.97 | accepted → refines | ATELIER-36 (drift resolution) |
|
||||
| IDEATE-02 | mechanical | coverage | 0.95 | accepted → refines | ATELIER-48 (matrix format) |
|
||||
| IDEATE-03 | mechanical | spec | 0.82 | accepted → refines | ATELIER-49 (row schema) |
|
||||
| IDEATE-04 | mechanical | coverage | 0.96 | accepted → refines | ATELIER-52 (manifest table) |
|
||||
| IDEATE-05 | mechanical | quality | 0.94 | accepted → refines | ATELIER-50 (checklist triggers) |
|
||||
| IDEATE-06 | mechanical | quality | 0.93 | accepted → refines | ATELIER-51 (anti-patterns) |
|
||||
| IDEATE-07 | mechanical | spec | 0.88 | accepted → refines | ATELIER-55 (named examples) |
|
||||
| IDEATE-08 | mechanical | spec | 0.86 | accepted → refines | ATELIER-56 (link verification) |
|
||||
| IDEATE-09 | mechanical | coverage | 0.79 | accepted → new req | ATELIER-59 (peer-review parity) |
|
||||
| IDEATE-10 | backend-enriched | improvement | 0.83 | accepted → refines | ATELIER-46 (decision matrix) |
|
||||
| IDEATE-11 | backend-enriched | improvement | 0.81 | accepted → refines | ATELIER-39 (state comparison table) |
|
||||
| IDEATE-12 | backend-enriched | improvement | 0.80 | accepted → refines | ATELIER-45 (PSS coverage) |
|
||||
| IDEATE-13 | backend-enriched | chaos | 0.85 | accepted → refines | ATELIER-48, ATELIER-51 (orphan mitigation) |
|
||||
| IDEATE-14 | backend-enriched | chaos | 0.87 | accepted → refines | ATELIER-53, ATELIER-51 (deployable artifact mitigation) |
|
||||
| IDEATE-15 | backend-enriched | improvement | 0.72 | deferred v0.3 | — (GitOps/operators domain) |
|
||||
| IDEATE-16 | backend-enriched | improvement | 0.68 | deferred v0.3 | — (ai-ml/i18n/compliance) |
|
||||
@@ -90,4 +90,129 @@ None. Atelier produces markdown only. No `package.json`, no runtime dependencies
|
||||
2. The 8 core principles are recoverable from `matrix/principles-matrix.md`'s key (D-011) — enough to author `core/first-principles.md` in P1.
|
||||
3. Custom personas needed: tech-writer (primary), domain-expert (validator). Default 3 inactive.
|
||||
4. No build/lint tooling in scope — markdown is the artifact (D-016, ARCHITECTURE.md).
|
||||
5. Phase ordering (P1–P6) follows the spec's build order; matrix + review come after all domains exist (P4).
|
||||
5. Phase ordering (P1–P6) follows the spec's build order; matrix + review come after all domains exist (P4).
|
||||
|
||||
---
|
||||
|
||||
# v0.2 Research — Infrastructure as Code + Kubernetes
|
||||
|
||||
> Research conducted during v0.2 P0 RESEARCH stage. Informs the two new domains, matrix extension, and the phase-specific platform-engineer persona. See CLARIFY.md D-019..D-030 for resolved ambiguities.
|
||||
|
||||
## Domain A: Infrastructure as Code (Terraform / OpenTofu)
|
||||
|
||||
### Prior Art
|
||||
|
||||
- **Terraform** (HashiCorp, 2014, original MPL-2.0): core workflow is **Write → Plan → Apply**. Declarative HCL; provider-based resource model; state file as the source of truth for drift detection. ([developer.hashicorp.com/terraform/intro/core-workflow](https://developer.hashicorp.com/terraform/intro/core-workflow))
|
||||
- **OpenTofu** (Linux Foundation, 2023 fork of MPL Terraform after HashiCorp's BUSL license change): community-driven, truly open source (MPL path), backwards-compatible with Terraform, layered and modular, impartial stewardship. ([opentofu.org/manifesto](https://opentofu.org/manifesto))
|
||||
- **Pulumi** (out of v0.2 scope per D-019 — user chose terraform+opentofu; general IaC principles cover the model).
|
||||
- **12-Factor** (already in Atelier v0.1 devops domain): config in environment, disposable, dev/prod parity.
|
||||
|
||||
### Principles Identified for `infrastructure-as-code/first-principles.md` (P1–P10)
|
||||
|
||||
Each derived from a core C-rule (see matrix updates in P3):
|
||||
|
||||
1. **P1 Declarative Intent** — describe desired state, not steps to reach it. (C2 Clarity, C3 Simplicity)
|
||||
2. **P2 Idempotence** — applying the same config twice yields the same result. (C1 Correctness)
|
||||
3. **P3 State is Truth** — the state file is the authoritative record; drift is a bug. (C1 Correctness, C7 Observability)
|
||||
4. **P4 Plan Before Apply** — preview every change before mutating real infrastructure. (C5 Reversibility)
|
||||
5. **P5 Version Everything** — config, state, providers, modules all versioned and reproducible. (C5 Reversibility)
|
||||
6. **P6 Modules Compose** — encapsulate repeatable patterns as versioned modules; compose, don't copy. (C6 Composability)
|
||||
7. **P7 Least Privilege Providers** — provider credentials scoped to minimum needed. (C1 Correctness via security)
|
||||
8. **P8 Remote State with Locking** — state stored remotely with locking to prevent concurrent corruption. (C4 Locality, C1 Correctness)
|
||||
9. **P9 Drift is Recoverable** — `plan` detects drift; `apply` reconciles. Manual mutation is an incident. (C5 Reversibility, C7 Observability)
|
||||
10. **P10 Secrets Never in Code** — secrets via providers/external secret stores, never hardcoded in HCL. (C1 Correctness, security non-tradeable)
|
||||
|
||||
### Derived Docs
|
||||
|
||||
- `terraform.md` — HCL structure, providers, resources, data sources, workspaces, `terraform init/plan/apply/destroy`, registry, state backends.
|
||||
- `opentofu.md` — fork lineage (BUSL → MPL via Linux Foundation), CLI parity, registry parity, migration path from Terraform, community governance, when to choose OpenTofu (license neutrality, supply-chain).
|
||||
- `state.md` — state backends (S3+DynamoDB lock, GCS, Azure blob, local for dev), locking, state isolation per environment, `terraform state` commands, sensitive values in state, state import/export.
|
||||
- `modules.md` — module structure, inputs/outputs, versioning (registry tags), `source` patterns (registry, git, local), module composition, the module-vs-copy boundary.
|
||||
|
||||
### Cross-Domain Links (one-directional in v0.2, per D-026)
|
||||
|
||||
- `devops/P1 Reproducibility` ← IaC P1, P5
|
||||
- `devops/P6 Configuration as Code` ← IaC P1
|
||||
- `security/secrets` ← IaC P10
|
||||
- `security/supply-chain` ← OpenTofu license-stewardship angle (cross-link, not duplication)
|
||||
- `data/migrations` ← IaC state lifecycle (analog, not direct)
|
||||
|
||||
## Domain B: Kubernetes
|
||||
|
||||
### Prior Art
|
||||
|
||||
- **Kubernetes** (CNCF, graduated): container orchestration platform. Concept taxonomy (per kubernetes.io/docs/concepts): Workloads (Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet, Job, CronJob), Services/Networking (Service, Ingress, Gateway API, NetworkPolicy, DNS), Storage (PV, PVC, StorageClass, CSI), Security (RBAC, ServiceAccounts, Pod Security Standards, Secrets, multi-tenancy), Configuration (ConfigMaps, Secrets, Resource Management), Policies (LimitRanges, ResourceQuotas), Scheduling/Eviction.
|
||||
- **Helm** (CNCF): package manager for k8s — charts as templated manifests, values overrides, registries.
|
||||
- **Kustomize** (built-in): overlay-based manifest customization without templating — base + overlays, no DSL.
|
||||
- **12-Factor App** — backing influence for k8s workload principles (disposability, config, logs).
|
||||
- **GitOps** (ArgoCD, Flux) — out of v0.2 first-principles scope but referenced as a deployment pattern for helm/kustomize; candidate IDEATE item.
|
||||
|
||||
### Principles Identified for `kubernetes/first-principles.md` (P1–P10)
|
||||
|
||||
1. **P1 Declarative Desired State** — controllers reconcile current → desired. Imperative commands are exceptions. (C1 Correctness, C2 Clarity)
|
||||
2. **P2 Pods are Mortal** — never assume a pod's identity or lifetime. Use controllers, not bare pods. (C5 Reversibility)
|
||||
3. **P3 Labels Select** — labels + selectors are the join mechanism for workloads, services, policies. (C6 Composability, C2 Clarity)
|
||||
4. **P4 Requests and Limits are Contracts** — resource requests drive scheduling; limits drive QoS. Unspecified = best-effort = first evicted. (C8 Economy, C1 Correctness)
|
||||
5. **P5 Probes Drive Health** — liveness, readiness, startup probes; the platform cannot heal what it cannot see. (C7 Observability, C1 Correctness)
|
||||
6. **P6 Namespaces Bound Blast Radius** — namespaces are the unit of quota, RBAC, network policy, and cleanup. (C4 Locality)
|
||||
7. **P7 RBAC by Intent, Not Identity** — bind roles to service accounts by workload purpose; least privilege; avoid cluster-admin. (C1 Correctness via security)
|
||||
8. **P8 Storage is Explicit** — ephemeral by default; persistence requires PVC + StorageClass + reclaim policy decisions. (C5 Reversibility, C4 Locality)
|
||||
9. **P9 Config and Secrets are Separate** — ConfigMaps for non-sensitive, Secrets for sensitive; both injected, never baked into images. (C2 Clarity, security)
|
||||
10. **P10 Roll Forward, Roll Back** — rolling updates + rollout history; every deployment has a known-good rollback. (C5 Reversibility)
|
||||
|
||||
### Derived Docs
|
||||
|
||||
- `workloads.md` — Pod, ReplicaSet, Deployment, StatefulSet (identity + ordering), DaemonSet, Job/CronJob, controllers, probes, lifecycle, disruption budgets.
|
||||
- `networking.md` — Service (ClusterIP/NodePort/LoadBalancer), Ingress, Gateway API, EndpointSlices, NetworkPolicy, DNS, dual-stack.
|
||||
- `storage.md` — Volumes, PV/PVC, StorageClass, CSI, dynamic provisioning, volume snapshots, reclaim policies, ephemeral volumes.
|
||||
- `rbac.md` — Role/ClusterRole, RoleBinding/ClusterRoleBinding, ServiceAccount, Pod Security Standards/Admission, RBAC good practices (cross-link `security/authorization`).
|
||||
- `helm.md` — chart structure, values.yaml, templates, registries, release management, when Helm fits vs Kustomize.
|
||||
- `kustomize.md` — base + overlays, kustomization.yaml, patches, no templating, when Kustomize fits vs Helm.
|
||||
|
||||
### Cross-Domain Links (one-directional in v0.2, per D-026)
|
||||
|
||||
- `devops/P4 Rollback First` ← k8s P10
|
||||
- `devops/P5 Progressive Delivery` ← k8s rolling updates, canary via labels
|
||||
- `devops/P3 Observability` ← k8s P5 probes, metrics
|
||||
- `security/authorization` ← k8s P7 RBAC
|
||||
- `security/secrets` ← k8s P9 Secrets
|
||||
- `observability/metrics` ← k8s P5, resource metrics pipeline
|
||||
- `data/storage` ← k8s P8 (analog: PVC lifecycle ↔ migration discipline)
|
||||
|
||||
## Architectural Fit (v0.1 Contract Preservation)
|
||||
|
||||
- **Hierarchy preserved:** both new domains depend on `core/`; their P-rules trace to C1–C8 via the matrix. No lateral authority.
|
||||
- **10 P-rules per domain** (per D-018, D-030): consistent with v0.1.
|
||||
- **Manifest authoritative:** all new documents added to `MANIFEST.md` in P3. Unlisted = not part of the framework.
|
||||
- **No runtime code:** examples are illustrative markdown with manifests in code fences (per D-025, PROJECT.md constraint). No `.tf`, `.yaml`, `.sh` deployable artifacts — only fenced code blocks inside `.md` files.
|
||||
- **Conflict resolution unchanged:** matrix extended, not replaced. Core precedence (C1 > C2 > ... > C8) governs any new vs existing rule conflict.
|
||||
|
||||
## Prior Art Position (v0.2 extension)
|
||||
|
||||
Existing IaC/k8s guidance (Terraform docs, k8s docs, Helm/Kustomize docs, Google SRE, CNCF guides) state practices but none map every domain rule back to a small set of universal core principles. Atelier's v0.2 contribution is the same differentiation as v0.1: **traceable principle hierarchy with a join table**. The two new domains add 20 P-rules, each traced to a core C-rule, extending the matrix from 110 to 130 domain principles across 13 domains.
|
||||
|
||||
## v0.2 Persona Assessment
|
||||
|
||||
See `.ciagent/atelier/PERSONAS.md` for the updated roster. v0.2 adds one phase-specific persona:
|
||||
|
||||
- **platform-engineer** (phase-specific, removed after v0.2): domain = infrastructure/platform; territory = `domains/infrastructure-as-code/**, domains/kubernetes/**, examples/good/{terraform-module,k8s-deployment}.md, examples/bad/*`; constraints = ["declarative-first", "stateless examples", "trace to core", "10 P-rules per domain"]; reason = specialist authoring for IaC/k8s content with domain expertise the existing tech-writer persona lacks.
|
||||
|
||||
## v0.2 Risks and Mitigations
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|-----------|
|
||||
| New P-rules orphaned from core (no matrix trace) | P3 extends matrix; domain-expert persona verifies every new P-rule traces to a C-rule before sign-off |
|
||||
| IaC and k8s domains overlap (state, secrets) | Cross-links are one-directional (D-026); each domain owns its own principle angle (IaC P3 state-as-truth vs k8s P8 storage-explicit) |
|
||||
| Examples become deployable (runtime code) | platform-engineer constraint "stateless examples"; examples are markdown with fenced code, never standalone `.tf`/`.yaml` files |
|
||||
| OpenTofu doc duplicates terraform.md | OpenTofu doc covers fork-specific governance/license/migration; references terraform.md for the shared HCL/state model |
|
||||
| Helm vs Kustomize preference bias | Both docs present neutral "when X fits" guidance; neither advocated over the other |
|
||||
|
||||
## v0.2 Conclusions
|
||||
|
||||
1. Two new top-level domains extend the framework without breaking the v0.1 contract.
|
||||
2. 20 new P-rules (10 per domain) all trace to core C1–C8 — matrix extends from 110 to 130.
|
||||
3. OpenTofu shares the IaC domain with Terraform (fork lineage); separate derived doc covers governance/license.
|
||||
4. State and modules get their own derived docs (cross-cutting IaC concerns).
|
||||
5. K8s derived docs mirror the k8s concept taxonomy: workloads, networking, storage, rbac, helm, kustomize.
|
||||
6. A phase-specific platform-engineer persona is warranted for P1–P4; removed after v0.2.
|
||||
7. No runtime code; examples are illustrative markdown only.
|
||||
@@ -39,6 +39,47 @@ NFR milestone: no separate minor tag. The final patch (v0.0.7) IS the v0.1 deliv
|
||||
- Milestone v0.1 complete. All phases shipped.
|
||||
- Future: v0.2 could add `domains/ai-ml/`, `domains/i18n/`, `domains/compliance/` per spec Part 6 next-steps.
|
||||
|
||||
## Milestone: v0.2 — Infrastructure as Code + Kubernetes (IN PROGRESS)
|
||||
|
||||
**Milestone type:** NFR (all phases produce docs — no `feat` code)
|
||||
**Tag line:** v0.1.x (previous minor from v0.2)
|
||||
**Phases:** P0 (pre-execution) + P1–P4 (execution) + P5 (final review+ship)
|
||||
|
||||
| Phase | Name | Type | Status | Key Deliverables |
|
||||
|-------|------|------|--------|------------------|
|
||||
| 0 | Pre-Execution | docs | in_progress | Spec, clarify, research, ideate, plan, PERSONAS.md (adds platform-engineer persona) |
|
||||
| 1 | Infrastructure as Code Domain | docs | pending | domains/infrastructure-as-code/{first-principles, terraform, opentofu, state, modules}.md |
|
||||
| 2 | Kubernetes Domain | docs | pending | domains/kubernetes/{first-principles, workloads, networking, storage, rbac, helm, kustomize}.md |
|
||||
| 3 | Matrix + Review Integration | docs | pending | matrix/principles-matrix.md (20 new mappings), matrix/domain-coverage.md, review/{agent-checklist, peer-review-checklist, anti-patterns}.md, MANIFEST.md |
|
||||
| 4 | Examples + Cross-Links | docs | pending | examples/good/{terraform-module, k8s-deployment}.md, examples/bad/{terraform-unlocked-state, k8s-bare-pod-no-resources}.md, cross-links to devops/security/observability/data |
|
||||
| 5 | Final Review + Ship | docs | pending | Review passed, audit clean, milestone merged to main, tag v0.1.5 |
|
||||
|
||||
## v0.2 Phase Tag Mapping
|
||||
|
||||
Per branch-strategy.md, milestone `v0.2` tags run on the `v0.1.x` patch line:
|
||||
|
||||
| Phase | Tag | Notes |
|
||||
|-------|-----|-------|
|
||||
| P0 | v0.1.0 | Pre-execution release |
|
||||
| P1 | v0.1.1 | Infrastructure as Code domain |
|
||||
| P2 | v0.1.2 | Kubernetes domain |
|
||||
| P3 | v0.1.3 | Matrix + review integration |
|
||||
| P4 | v0.1.4 | Examples + cross-links |
|
||||
| P5 | v0.1.5 | Final review + ship — **IS the v0.2 milestone release** |
|
||||
|
||||
NFR milestone: no separate minor tag. The final patch (v0.1.5) IS the v0.2 deliverable.
|
||||
|
||||
## v0.2 Ideation Outcome
|
||||
|
||||
- 16 ideas generated (mechanical 9, backend-enriched 7)
|
||||
- 14 accepted (all in v0.2 scope; refined ATELIER-36..58, added ATELIER-59)
|
||||
- 2 deferred to v0.3 (GitOps/operators domain; ai-ml/i18n/compliance domains)
|
||||
- See `.ciagent/atelier/REQUIREMENTS.md` "v0.2 Ideation Log" for the full table
|
||||
|
||||
## Future Milestones
|
||||
|
||||
- **v0.3** (candidates from ideation): `domains/gitops-operators/` (ArgoCD, Flux), `domains/ai-ml/`, `domains/i18n/`, `domains/compliance/` per spec Part 6 and v0.2 deferred ideation.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] All 11 domains have first-principles.md
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
{
|
||||
"slug": "atelier",
|
||||
"name": "Atelier",
|
||||
"milestone": "v0.1",
|
||||
"milestone": "v0.2",
|
||||
"status": "specify"
|
||||
}
|
||||
],
|
||||
|
||||
Reference in New Issue
Block a user