docs(P02): complete domain-first-principles phase

docs(P01): complete core-foundation phase
docs(P00): complete pre-execution phase — ship v0.0.0
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
32 changed files with 2192 additions and 0 deletions
@@ -0,0 +1,8 @@
 {
  "phase": 0,
  "stage": "complete",
  "milestone": "v0.1",
  "phase_role": "pre_execution",
  "attempts": 0,
  "updated_at": "2026-08-05T00:04:00Z"
 }
@@ -0,0 +1,71 @@
 # Atelier — Architecture
 ## System Overview
 Atelier is a **documentation-only framework** — no runtime code, no build artifacts. The "system" is the document tree itself and the relationships between documents.
 ## Component Boundaries
 ```
 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)
 ```
 **Dependency direction (enforced):**
 - `core/` depends on nothing
 - `domains/` depend on `core/` (each domain's P-rules trace to core C-rules)
 - `languages/` depend on `domains/` (language rules apply domain rules)
 - `matrix/` depends on `core/` + `domains/` (it's the join table)
 - `review/` depends on everything (it evaluates compliance)
 - `examples/` depend on everything (they illustrate)
 No document may reference a sibling at the same level as authoritative — conflict resolution always goes UP to core.
 ## Data Flow
 There is no runtime data flow. The "flow" is the **reading order**:
 1. `core/first-principles.md` (required first)
 2. `core/conflict-resolution.md` (required)
 3. `domains/<relevant>/first-principles.md` (per task)
 4. `domains/<relevant>/<topic>.md` (as needed)
 5. `matrix/principles-matrix.md` (reference)
 ## Conflict Resolution Architecture
 When two documents disagree:
 1. Higher in the hierarchy wins (`core` > `domains` > `languages`)
 2. Within a level, the more specific document wins for its scope
 3. If still ambiguous, the core principle with the highest precedence (C1 Correctness > C2 Clarity > ...) wins
 4. The `matrix/principles-matrix.md` is the arbiter — it records which core principle each domain rule derives from
 ## Technology
 - **Format:** Markdown (CommonMark + GitHub Flavored)
 - **Versioning:** Whole-framework semantic versioning (one version per release, not per-doc)
 - **Distribution:** Git repository (consumed by reading markdown)
 - **No build step** — markdown is the artifact
 ## Governance
 - `.ciagent/` holds project management artifacts (config, PROJECT.md, ROADMAP.md, REQUIREMENTS.md, ARCHITECTURE.md, PERSONAS.md, PLAN)
 - The framework content lives in the repo root (`README.md`, `core/`, `domains/`, etc.)
 - `MANIFEST.md` is the authoritative index — unlisted documents are not part of the framework
 ## Research-Refined Decisions
 - **8 core principles (not 10):** The spec's matrix key names exactly 8 (C1–C8). Each domain has 10 (P1–P10). Asymmetry is intentional — core is minimal, domains are specific.
 - **Numeric precedence C1 > C2 > ... > C8:** Correctness is non-negotiable; Economy is the most tradeable.
 - **Strict hierarchy enforcement:** No lateral authority. Conflicts go UP, never sideways.
 - **No build step:** Markdown is the artifact. A build step would violate docs-as-code simplicity.
 ## Prior Art Position
 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).
@@ -0,0 +1,51 @@
 # Atelier — Domain First-Principles Audit (P2)
 > Conducted during phase 2. Domain-expert persona validated all 11 domain first-principles files and the matrix.
 ## Audit Results
 ### Principle Count Per Domain (target: 10)
 | Domain | Count | Status |
 |--------|-------|--------|
 | api | 10 | ✓ |
 | security | 10 | ✓ |
 | data | 10 | ✓ |
 | testing | 10 | ✓ |
 | performance | 10 | ✓ |
 | observability | 10 | ✓ |
 | errors | 10 | ✓ |
 | documentation | 10 | ✓ |
 | concurrency | 10 | ✓ |
 | devops | 10 | ✓ |
 | uiux | 10 | ✓ (newly authored in P2) |
 **Total: 110 principles across 11 domains. No gaps.**
 ### Matrix Completeness
 - Total P-rule rows in `matrix/principles-matrix.md`: 110 (11 domains × 10 principles)
 - Every row maps to at least one C-rule
 - Core principle distribution (derivation counts):
  - C1 Correctness: 46 derivations (most common — correctness is the floor)
  - C2 Clarity: 23
  - C3 Simplicity: 18
  - C7 Observability: 22
  - C8 Economy: 16
  - C5 Reversibility: 11
  - C6 Composability: 9
  - C4 Locality: 3 (least — locality is domain-specific)
 **No orphaned P-rules.** Every domain principle traces to a core principle.
 ### Observations
 1. C1 (Correctness) is the most-derived principle (46/110) — expected, as correctness is the floor.
 2. C4 (Locality) has only 3 derivations — it is the most domain-specific (testing independence, concurrency boundaries). Not a gap; locality is inherently narrow.
 3. Security domain declares 8 of 10 principles non-tradeable — these are promoted to C1-equivalent per `core/conflict-resolution.md` §6.
 4. UI/UX declares 3 non-tradeable (P2 Accessibility, P3 Clarity, P1 User Primacy) — promoted to C1-equivalent.
 5. No domain has a P-rule without a matrix entry. No matrix row lacks a corresponding section in the domain's first-principles.md.
 ### Conclusion
 The framework's principle hierarchy is complete and traceable. Phase 2 deliverable (uiux/first-principles.md) fills the last gap. The matrix is the arbiter and is consistent with all domain documents.
@@ -0,0 +1,34 @@
 # Atelier — Clarify Decisions
 > Generated during P0 CLARIFY stage. Autonomy level: `full` (defaults auto-accepted).
 > Initial decisions D-001..D-010 recorded in init commit; this file consolidates the full clarify log.
 ## Ambiguities Identified and Resolved
 | ID | Ambiguity | Default (Accepted) | Confidence | Rationale |
 |----|-----------|--------------------|------------|-----------|
 | D-001 | License type unspecified | MIT | 0.70 | Standard permissive license for docs frameworks; deferred to P1 |
 | D-002 | README/CHANGELOG/CONTRIBUTING content not pasted | Defer to execute phase 1+6 | 0.80 | Referenced in spec tree but text not provided |
 | D-003 | `core/first-principles.md` content not pasted (referenced as "already drafted") | Defer to P1; author from scratch using 8 principles (C1–C8) referenced in matrix | 0.70 | Matrix names C1..C8 explicitly; enough to reconstruct |
 | D-004 | `domains/uiux/first-principles.md` not pasted (referenced as "already drafted") | Defer to P2; author from components.md + accessibility.md which imply P1..P10 | 0.70 | components.md and accessibility.md reference the principles |
 | D-005 | `examples/`, `languages/`, `review/`, `matrix/domain-coverage.md` in scope for init? | Out of scope — execute-phase deliverables | 0.90 | Spec Part 6 build order places them after first-principles |
 | D-006 | Token env var name | `GITEA_API_TOKEN` | 0.80 | Matches existing /root/.ciagent/config.json convention |
 | D-007 | Milestone version | v0.1 (user override) | 0.95 | User explicitly required v0.1, not computed v1.0 |
 | D-008 | Number of execution phases | 6 (P1–P6) + final P7 | 0.88 | Mirrors spec Part 6 Recommended Build Order |
 | D-009 | Milestone type | NFR (all phases are docs/chore) | 0.92 | No `feat` code; patch-line versioning per branch-strategy.md |
 | D-010 | Tag patch line | v0.0.x (prev minor from v0.1) | 0.90 | Per branch-strategy.md: milestone 0.1 → tags v0.0.0..v0.0.7 |
 | D-011 | `core/first-principles.md` — exact C1..C8 names | Use the 8 named in matrix key: Correctness, Clarity, Simplicity, Locality, Reversibility, Composability, Observability, Economy | 0.95 | matrix/principles-matrix.md explicitly names them in the key |
 | D-012 | `core/conflict-resolution.md` — precedence order of C1..C8 | Numeric order C1 > C2 > ... > C8 (Correctness highest, Economy lowest) | 0.85 | Standard convention; matrix lists them in this order |
 | D-013 | `core/reading-order.md` — exact order | core/first-principles → core/conflict-resolution → core/reading-order → domains/<x>/first-principles → domains/<x>/<topic> → matrix/principles-matrix | 0.92 | MANIFEST.md Reading Order section defines this |
 | D-014 | Should `examples/bad/*` be real anti-patterns or fictional? | Real anti-patterns from the field (god-object, silent-error, leaky-abstraction as named in spec) | 0.90 | Spec explicitly names these three |
 | D-015 | `languages/*.md` — which languages? | typescript, python, go, rust minimum (spec shows these + "...") | 0.85 | Spec tree lists typescript, python, go, rust, "..." |
 | D-016 | Versioning scheme for the framework itself | Whole-framework semver (one version per release) | 0.90 | ARCHITECTURE.md decided this; no per-doc versioning |
 | D-017 | Should `domains/uiux/tokens.md` and `copywriting.md` content come from spec? | Defer to P3; spec tree lists them but no content pasted | 0.80 | Spec Part 1 tree lists them; Part 4 only gives components + accessibility |
 | D-018 | Are domain P1..P10 numbers fixed or can domains have fewer? | Fixed at 10 per domain (matrix shows 10 per domain consistently) | 0.92 | matrix/principles-matrix.md has exactly 10 rows per domain |
 ## Notes
 - 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).
@@ -0,0 +1,55 @@
 # Atelier — Persona Configuration
 > Generated during P0 RESEARCH. Atelier is a documentation-only project;
 > the default runtime persona roster is deactivated. Custom personas
 > reflect the docs-as-code nature of the work.
 ## Active Personas
 ### lead-developer
 - **active:** true
 - **domain:** coordination
 - **frameworks:** []
 - **constraints:** ["pragmatic", "docs-as-code discipline", "manifest is authoritative"]
 - **territory:** [".ciagent/**", "MANIFEST.md", "README.md"]
 - **reason:** Decomposes doc-writing tasks by domain across phases; coordinates phase execution; owns governance files and the manifest.
 ### tech-writer
 - **active:** true
 - **domain:** documentation
 - **frameworks:** []
 - **constraints:** ["markdown-first", "examples are mandatory", "why over what", "audience awareness"]
 - **territory:** ["**/*.md", "LICENSE", "CHANGELOG.md", "CONTRIBUTING.md"]
 - **reason:** Primary author of all framework markdown content. Owns docs-as-code discipline (Documentation P1). Excludes `.ciagent/**` governance files (owned by lead-developer).
 ### domain-expert
 - **active:** true
 - **domain:** cross-cutting
 - **frameworks:** []
 - **constraints:** ["every principle traces to core", "10 principles per domain", "no orphans in matrix"]
 - **territory:** ["core/**", "domains/**", "matrix/**", "review/**", "examples/**"]
 - **reason:** Validates domain principle correctness and traceability to core principles. Ensures the matrix is complete and no domain rule is orphaned.
 ## Inactive Personas (from default roster)
 ### data-engineer
 - **active:** false
 - **reason:** No database, schema, or migrations in this docs-only project.
 ### backend-engineer
 - **active:** false
 - **reason:** No API server, routes, services, or middleware in this docs-only project.
 ### frontend-engineer
 - **active:** false
 - **reason:** No React/Next components, pages, or hooks in this docs-only project.
 ## Phase-Specific Personas
 None. All three active personas span the full milestone. No phase-scoped personas needed — the work is uniformly markdown authoring with domain validation.
 ## 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.
@@ -0,0 +1,207 @@
 # Atelier — Plan (v0.1)
 > Vertical-slice plans with wave ordering. Each phase is a vertical slice delivering a usable subset of the framework. Plans reference REQ-IDs from `.ciagent/atelier/REQUIREMENTS.md`.
 ## Phase 0 — Pre-Execution (COMPLETE)
 Stages: SPECIFY ✓ → CLARIFY ✓ → RESEARCH ✓ → PLAN ✓ → SHIP
 Tag: v0.0.0
 ## Phase 1 — Core Foundation
 **Goal:** Establish the 8 core principles + entry docs. The foundation everything else depends on.
 **Branch:** `phase/01-core-foundation` (from `milestone/v0.1-atelier`)
 **Persona:** tech-writer (author), domain-expert (validate traceability)
 **Tag:** v0.0.1
 **Requirements:** ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08
 ### Wave 1 (sequential — foundation must exist before anything else)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 01-01-01 | `core/first-principles.md` | tech-writer | ATELIER-04 | 8 principles (C1–C8) named exactly per matrix key, each with definition + "what violates" |
 | 01-01-02 | `core/conflict-resolution.md` | tech-writer | ATELIER-05 | Precedence order C1>...>C8, cross-doc conflict rules, hierarchy enforcement |
 | 01-01-03 | `core/reading-order.md` | tech-writer | ATELIER-06 | Reading order per MANIFEST.md, guided tour for agents + humans |
 ### Wave 2 (parallel — entry docs, independent)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 01-02-01 | `README.md` | tech-writer | ATELIER-07 | What/who/quickstart, links to MANIFEST + reading-order |
 | 01-02-02 | `LICENSE` | tech-writer | ATELIER-08 | MIT license full text (D-001) |
 **Verify (P1):**
 - Structural: all 3 core files + README + LICENSE exist
 - Behavioral: every C-rule name in matrix matches a section in `core/first-principles.md`
 - Security: LICENSE present (legal)
 - Quality: reading-order.md links resolve to existing files
 ## Phase 2 — Domain First Principles (Missing Ones)
 **Goal:** Author the 5 domain first-principles not yet written (uiux, errors already done? No — errors IS done in P0. Check: P0 wrote api, security, data, testing, performance, observability, errors, documentation, concurrency, devops. Missing: **uiux** only. Plus uiux first-principles was deferred D-004.)
 Wait — recount. P0 init wrote first-principles for: api, security, data, testing, performance, observability, errors, documentation, concurrency, devops (10). Missing: **uiux** (deferred D-004). So P2 is small — just uiux first-principles. But also need to validate the other 10 exist and are complete.
 Actually, re-examining: P0 already wrote 10 domain first-principles. Only `domains/uiux/first-principles.md` is missing. So P2 = uiux first-principles + a completeness audit of the other 10.
 **Goal (revised):** Author `domains/uiux/first-principles.md` (P1–P10) and audit the 10 existing first-principles for completeness.
 **Branch:** `phase/02-domain-first-principles`
 **Persona:** tech-writer (author), domain-expert (audit)
 **Tag:** v0.0.2
 **Requirements:** ATELIER-09
 ### Wave 1
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 02-01-01 | `domains/uiux/first-principles.md` | tech-writer | ATELIER-09 | 10 principles (P1–P10) matching matrix UI/UX rows; P1 User Primacy, P2 Accessibility, etc. |
 | 02-01-02 | Audit 10 existing first-principles | domain-expert | (meta) | Each has 10 principles, each traces to matrix; log gaps to RESEARCH.md |
 **Verify (P2):** Structural (11/11 first-principles exist), Behavioral (each P-rule in matrix has a section), Quality (no orphaned rules).
 ## Phase 3 — Domain Derived Docs
 **Goal:** Author the derived/topic docs for each domain (the non-first-principles files in the spec tree).
 **Branch:** `phase/03-domain-derived-docs`
 **Persona:** tech-writer
 **Tag:** v0.0.3
 **Requirements:** ATELIER-14..ATELIER-20
 ### Wave 1 (parallel — domains are independent)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 03-01-01 | `domains/api/rest.md` | tech-writer | ATELIER-14 | REST-specific rules deriving from api first-principles |
 | 03-01-02 | `domains/api/graphql.md` | tech-writer | ATELIER-14 | GraphQL-specific rules |
 | 03-01-03 | `domains/api/versioning.md` | tech-writer | ATELIER-14 | API evolution rules |
 | 03-01-04 | `domains/api/error-responses.md` | tech-writer | ATELIER-14 | Error contract design |
 | 03-01-05 | `domains/api/pagination.md` | tech-writer | ATELIER-14 | Pagination patterns |
 | 03-01-06 | `domains/security/authentication.md` | tech-writer | ATELIER-15 | Auth rules |
 | 03-01-07 | `domains/security/authorization.md` | tech-writer | ATELIER-15 | Authz rules |
 | 03-01-08 | `domains/security/input-validation.md` | tech-writer | ATELIER-15 | Input validation rules |
 | 03-01-09 | `domains/security/secrets.md` | tech-writer | ATELIER-15 | Secret management rules |
 | 03-01-10 | `domains/security/supply-chain.md` | tech-writer | ATELIER-15 | Supply chain rules |
 | 03-01-11 | `domains/data/schema-design.md` | tech-writer | ATELIER-16 | Schema design rules |
 | 03-01-12 | `domains/data/migrations.md` | tech-writer | ATELIER-16 | Migration rules |
 | 03-01-13 | `domains/data/indexing.md` | tech-writer | ATELIER-16 | Indexing rules |
 | 03-01-14 | `domains/testing/pyramid.md` | tech-writer | ATELIER-17 | Test pyramid rules |
 | 03-01-15 | `domains/testing/fixtures.md` | tech-writer | ATELIER-17 | Fixture rules |
 | 03-01-16 | `domains/performance/frontend.md` | tech-writer | ATELIER-18 | Frontend perf rules |
 | 03-01-17 | `domains/performance/backend.md` | tech-writer | ATELIER-18 | Backend perf rules |
 | 03-01-18 | `domains/observability/logging.md` | tech-writer | ATELIER-19 | Logging rules |
 | 03-01-19 | `domains/observability/metrics.md` | tech-writer | ATELIER-19 | Metrics rules |
 | 03-01-20 | `domains/observability/tracing.md` | tech-writer | ATELIER-19 | Tracing rules |
 | 03-01-21 | `domains/uiux/tokens.md` | tech-writer | ATELIER-20 | Design token rules |
 | 03-01-22 | `domains/uiux/copywriting.md` | tech-writer | ATELIER-20 | UI microcopy rules |
 | 03-01-23 | `domains/errors/patterns.md` | tech-writer | (derived) | Error patterns |
 | 03-01-24 | `domains/documentation/doc-templates.md` | tech-writer | (derived) | Doc templates |
 | 03-01-25 | `domains/concurrency/patterns.md` | tech-writer | (derived) | Concurrency patterns |
 | 03-01-26 | `domains/devops/ci-cd.md` | tech-writer | (derived) | CI/CD rules |
 | 03-01-27 | `domains/devops/environments.md` | tech-writer | (derived) | Environment rules |
 **Verify (P3):** Structural (all derived docs in spec tree exist), Behavioral (each derives from its domain's first-principles), Quality (no contradictions with core).
 ## Phase 4 — Matrix + Review
 **Goal:** Complete the cross-reference matrix and review tooling.
 **Branch:** `phase/04-matrix-review`
 **Persona:** domain-expert (matrix), tech-writer (review)
 **Tag:** v0.0.4
 **Requirements:** ATELIER-21..ATELIER-25
 ### Wave 1 (matrix must be complete before review references it)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 04-01-01 | `matrix/principles-matrix.md` (verify complete) | domain-expert | ATELIER-21 | All 11 domains × 10 principles mapped to C-rules (already written in P0; verify) |
 | 04-01-02 | `matrix/domain-coverage.md` | domain-expert | ATELIER-22 | Where each principle applies across the codebase |
 ### Wave 2 (parallel — review docs independent)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 04-02-01 | `review/agent-checklist.md` | tech-writer | ATELIER-23 | Pre-completion checklist covering all 8 core principles + domain triggers |
 | 04-02-02 | `review/peer-review-checklist.md` | tech-writer | ATELIER-24 | Human review checklist |
 | 04-02-03 | `review/anti-patterns.md` | tech-writer | ATELIER-25 | Catalog of violations (from each domain's "what violates" tables) |
 **Verify (P4):** Structural (matrix complete, 3 review docs exist), Behavioral (every matrix row references an existing P-rule and C-rule), Security (agent-checklist covers security domain), Quality (anti-patterns cross-reference principles).
 ## Phase 5 — Examples
 **Goal:** Worked examples showing the framework in action.
 **Branch:** `phase/05-examples`
 **Persona:** tech-writer
 **Tag:** v0.0.5
 **Requirements:** ATELIER-26..ATELIER-30
 ### Wave 1 (parallel — examples independent)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 05-01-01 | `examples/good/api-endpoint.md` | tech-writer | ATELIER-26 | Good REST endpoint example, references API P-rules |
 | 05-01-02 | `examples/good/react-component.md` | tech-writer | ATELIER-27 | Good component example, references UI/UX P-rules |
 | 05-01-03 | `examples/good/db-schema.md` | tech-writer | ATELIER-28 | Good schema example, references Data P-rules |
 | 05-01-04 | `examples/good/error-handler.md` | tech-writer | ATELIER-29 | Good error handler, references Errors P-rules |
 | 05-01-05 | `examples/bad/god-object.md` | tech-writer | ATELIER-30 | Bad example with violated principles cited |
 | 05-01-06 | `examples/bad/silent-error.md` | tech-writer | ATELIER-30 | Bad example with violated principles cited |
 | 05-01-07 | `examples/bad/leaky-abstraction.md` | tech-writer | ATELIER-30 | Bad example with violated principles cited |
 **Verify (P5):** Structural (7 example files), Behavioral (good examples cite P-rules they follow; bad examples cite P-rules they violate), Quality (examples are realistic, not strawmen).
 ## Phase 6 — Languages + Meta
 **Goal:** Language-specific application docs + meta documents.
 **Branch:** `phase/06-languages-meta`
 **Persona:** tech-writer
 **Tag:** v0.0.6
 **Requirements:** ATELIER-31..ATELIER-33
 ### Wave 1 (parallel)
 | Task | File | Persona | REQ-ID | Must-have |
 |------|------|---------|--------|-----------|
 | 06-01-01 | `languages/typescript.md` | tech-writer | ATELIER-31 | TS-specific application of domain principles |
 | 06-01-02 | `languages/python.md` | tech-writer | ATELIER-31 | Python-specific application |
 | 06-01-03 | `languages/go.md` | tech-writer | ATELIER-31 | Go-specific application |
 | 06-01-04 | `languages/rust.md` | tech-writer | ATELIER-31 | Rust-specific application |
 | 06-01-05 | `CHANGELOG.md` | tech-writer | ATELIER-32 | Version history of the framework (v0.1.0 entry) |
 | 06-01-06 | `CONTRIBUTING.md` | tech-writer | ATELIER-33 | How to propose changes to the framework |
 **Verify (P6):** Structural (4 language docs + CHANGELOG + CONTRIBUTING), Behavioral (language docs reference domain rules they apply), Quality (CHANGELOG follows Keep a Changelog format).
 ## Phase 7 — Final Review + Ship (Milestone Release)
 **Goal:** Review all phases, audit project health, ship the milestone.
 **Branch:** `phase/07-final-review-ship` (from `milestone/v0.1-atelier`)
 **Tag:** v0.0.7 (IS the v0.1 milestone release)
 **Requirements:** ATELIER-34, ATELIER-35
 ### Wave 1 — Review (ciagent-review)
 | Task | Persona | Must-have |
 |------|---------|-----------|
 | 07-01-01 | ci-reviewer | Multi-persona review across all phases; auto-apply P0 fixes; flag P1+ for post-hoc |
 | 07-01-02 | ci-reviewer | Verify every P-rule in matrix has a corresponding section in its domain first-principles |
 ### Wave 2 — Audit (ciagent-audit)
 | Task | Persona | Must-have |
 |------|---------|-----------|
 | 07-02-01 | ci-auditor | Reconstruction test: MANIFEST.md lists all framework docs; every listed doc exists |
 | 07-02-02 | ci-auditor | Branch hygiene: only `main` + `milestone/v0.1-atelier` after phase branches merged |
 | 07-02-03 | ci-auditor | Commit discipline: every commit has `---ci---` block |
 ### Wave 3 — Ship (ciagent-ship)
 | Task | Persona | Must-have |
 |------|---------|-----------|
 | 07-03-01 | ship | Merge `phase/07` → `milestone/v0.1-atelier` |
 | 07-03-02 | ship | Merge `milestone/v0.1-atelier` → `main` |
 | 07-03-03 | ship | Tag `v0.0.7` (IS the v0.1 release) |
 | 07-03-04 | ship | Create Gitea release for v0.0.7 with full milestone summary |
 | 07-03-05 | ship | Delete all milestone branches; tags preserve history |
 ## Milestone Type: NFR
 Per branch-strategy.md, this is an NFR milestone (all phases are docs/chore — no `feat` code). NFR milestones produce progressive patches; the final patch (v0.0.7) IS the deliverable. No separate minor tag.
 ## Wave Ordering Summary
 | Phase | Waves | Parallelism |
 |-------|-------|-------------|
 | P1 | 2 | Wave 1 sequential (foundation), Wave 2 parallel (entry docs) |
 | P2 | 1 | Single wave (small phase) |
 | P3 | 1 | Single large parallel wave (27 independent docs) |
 | 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 |
@@ -0,0 +1,73 @@
 # Atelier — Project Vision
 ## Objective
 Build **Atelier** — a first-principles, docs-as-code engineering framework for AI agents and humans, organized as a hierarchical document tree: `core → domains → languages → review → matrix → examples`. Each domain defines its own first principles derived from a small set of core principles, with every rule traced back via a principles matrix. The framework is consumed by AI agents as pre-completion guidance and by humans as engineering canon.
 ## Core Value
 **Principles over rules.** A small set of universal core principles (Correctness, Clarity, Simplicity, Locality, Reversibility, Composability, Observability, Economy) govern every domain. Domain rules derive from these and never contradict them. The principles matrix is the connective tissue — no domain rule is orphaned, and conflicts resolve upward to core.
 ## Requirements
 - Hierarchical document tree: `core/`, `domains/`, `languages/`, `review/`, `matrix/`, `examples/`
 - `core/first-principles.md` — 8 universal principles (C1–C8)
 - `core/conflict-resolution.md` — formal cross-document conflict rules
 - `core/reading-order.md` — recommended consumption order
 - 11 domain folders, each with `first-principles.md` (P1–P10) plus derived docs
 - Domains: uiux, api, security, data, testing, performance, observability, errors, documentation, concurrency, devops
 - UI/UX derived: components, accessibility, tokens, copywriting
 - API derived: rest, graphql, versioning, error-responses, pagination
 - Security derived: authentication, authorization, input-validation, secrets, supply-chain
 - Data derived: schema-design, migrations, indexing
 - Testing derived: pyramid, fixtures
 - Performance derived: frontend, backend
 - Observability derived: logging, metrics, tracing
 - Errors derived: patterns
 - Documentation derived: doc-templates
 - Concurrency derived: patterns
 - DevOps derived: ci-cd, environments
 - `matrix/principles-matrix.md` — every domain P-rule → core C-rule mapping
 - `matrix/domain-coverage.md` — where each principle applies
 - `review/agent-checklist.md` — pre-completion checklist for agents
 - `review/peer-review-checklist.md` — human review checklist
 - `review/anti-patterns.md` — catalog of violations
 - `examples/good/*` and `examples/bad/*` — worked examples
 - `languages/*.md` — language-specific application (typescript, python, go, rust, ...)
 - `MANIFEST.md` — authoritative index (unlisted = not part of framework)
 - `README.md`, `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`
 ## Constraints
 - Docs-as-code: versioned, reviewed, tested, owned (Documentation P1)
 - Every domain principle MUST trace to a core principle via the matrix
 - The manifest is authoritative — unlisted documents are not part of the framework
 - Security principles are non-tradeable (8 of 10 are never sacrificed)
 - Manifest reading order: core first-principles → core conflict-resolution → domain first-principles → domain topic → matrix reference
 - No runtime code — Atelier is a documentation-only framework
 ## Out of Scope
 - Tooling to enforce the rules (linters, analyzers) — future work
 - Translation/localization of the framework docs
 - Automated agent integration adapters beyond markdown consumption
 - Versioned per-domain release artifacts (the whole framework versions together)
 ## Key Decisions
 | ID | Decision | Rationale | Confidence |
 |----|----------|-----------|------------|
 | D-001 | MIT license (deferred to P1) | Not pasted in spec; standard permissive choice for docs frameworks | 0.70 |
 | D-002 | Defer README/CHANGELOG/CONTRIBUTING to execute phase | Referenced in spec tree but content not pasted | 0.80 |
 | D-003 | core/* first-principles deferred to P1 | Referenced as "already drafted" but not pasted | 0.70 |
 | D-004 | domains/uiux/first-principles.md deferred to P2 | Referenced as "already drafted" but not pasted | 0.70 |
 | D-005 | examples/, languages/, review/, matrix/domain-coverage.md deferred to later phases | Execute-phase deliverables per spec build order | 0.90 |
 | D-006 | GITEA_API_TOKEN as token env var name | Matches existing /root/.ciagent/config.json convention | 0.80 |
 | D-007 | Milestone v0.1 (user override) | User explicitly required first milestone = v0.1, not v1.0 | 0.95 |
 | 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 |
 ## Cross-Project References
 None yet. Atelier is a standalone docs framework.
@@ -0,0 +1,54 @@
 # Atelier — Requirements
 ## v0.1 Requirements
 | REQ-ID | Requirement | Priority | Phase | Status |
 |--------|-------------|----------|-------|--------|
 | 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 | 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
 | Phase | Requirements |
 |-------|-------------|
 | 0 (Pre-Execution) | ATELIER-01, ATELIER-02, ATELIER-03 |
 | 1 (Core Foundation) | ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08 |
 | 2 (Domain First Principles) | ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13 |
 | 3 (Domain Derived Docs) | ATELIER-14..ATELIER-20 |
 | 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 |
@@ -0,0 +1,93 @@
 # Atelier — Research Findings (P0)
 > Research conducted during phase 0 RESEARCH stage. Conclusions inform ARCHITECTURE.md, PERSONAS.md, and the plan.
 ## Domain: Engineering-Principles Frameworks
 ### Prior Art Surveyed
 1. **ThoughtWorks Technology Radar** — opinionated tech assessments, but no first-principles derivation. Adopts positions, not axioms.
 2. **Google Engineering Practices** — review checklists and style guides; lacks cross-domain principle tracing.
 3. **Microsoft Azure Design Principles** — cloud-architecture-focused; not generalizable across domains.
 4. **12-Factor App** — narrow (deployment/config), but a model for "small set of universal rules" pattern.
 5. **SOLID / GRASP** — OO-specific principles; good model for "principles over rules" but language-bound.
 6. **WCAG 2.1 AA** — the canonical a11y reference; Atelier's `domains/uiux/accessibility.md` already mirrors it.
 7. **OWASP Top 10 / ASVS** — security control catalog; Atelier's security domain derives principles, not controls.
 8. **Clean Code / Pragmatic Programmer** — book-level principles; not machine-consumable, no traceability matrix.
 ### Key Insight
 Atelier's differentiation: **traceable principle hierarchy with a join table**. Existing frameworks state principles; none provide a `matrix/principles-matrix.md` that maps every domain rule back to a core rule. This is the framework's unique value — conflict resolution has an arbiter.
 ### Atelier's Position
 - **Not** a style guide (no code formatting rules)
 - **Not** a linter (no enforcement tooling)
 - **Is** a principle hierarchy with cross-references, consumed by AI agents and humans
 - **Is** docs-as-code (versioned, reviewed, owned)
 ## Ecosystem & Distribution
 - **Format:** Markdown (CommonMark + GFM) — universally readable, agent-friendly
 - **Distribution:** Git repository (consumed by reading)
 - **Agent consumption:** Agents read `MANIFEST.md` → `core/` → relevant `domains/` before completing a task. The `review/agent-checklist.md` is the pre-completion gate.
 - **Human consumption:** `README.md` → `MANIFEST.md` → `core/reading-order.md` for guided tour
 ## Architectural Decisions (Refined from RESEARCH)
 | Decision | Rationale |
 |----------|-----------|
 | 8 core principles (not 10) | The spec's matrix key names exactly 8 (C1–C8). Each domain has 10 (P1–P10). Asymmetry is intentional: core is minimal, domains are specific. |
 | Numeric precedence C1 > C2 > ... > C8 | Correctness is non-negotiable; Economy is the most tradeable. Matches intuition and the matrix ordering. |
 | Strict hierarchy: core > domains > languages | No lateral authority. Conflicts go UP, never sideways. |
 | MANIFEST.md is the authoritative index | Unlisted docs aren't part of the framework — prevents drift. |
 | No build step | Markdown is the artifact. A build step would violate "docs-as-code" simplicity. |
 ## Persona Assessment
 Atelier is a **documentation-only** project. The default persona roster (lead-developer, data-engineer, backend-engineer, frontend-engineer) is wrong for this project — there is no runtime code, no database, no API server, no UI components.
 ### Active Personas (Custom for Atelier)
 | Persona | Domain | Why Active |
 |---------|--------|-----------|
 | lead-developer | coordination | Decomposes doc-writing tasks by domain; coordinates phase execution |
 | tech-writer | documentation | Author of all framework markdown; owns docs-as-code discipline |
 | domain-expert | cross-cutting | Validates domain principle correctness (security, data, api, etc.); ensures traceability to core |
 ### Inactive Personas (from default roster)
 | Persona | Why Inactive |
 |---------|--------------|
 | data-engineer | No database, schema, migrations in this project |
 | backend-engineer | No API server, routes, services, middleware |
 | frontend-engineer | No React/Next components, pages, hooks |
 ### Frameworks
 None. Atelier produces markdown only. No `package.json`, no runtime dependencies.
 ### Territories
 | Persona | Territory globs |
 |---------|-----------------|
 | lead-developer | `.ciagent/**`, `MANIFEST.md`, `README.md` |
 | tech-writer | `**/*.md` (excluding `.ciagent/**`), `LICENSE` |
 | domain-expert | `core/**`, `domains/**`, `matrix/**`, `review/**`, `examples/**` |
 ## Risks
 | Risk | Mitigation |
 |------|-----------|
 | Domain principles drift from core (orphaned rules) | matrix/principles-matrix.md is the arbiter; every P-rule must trace to a C-rule. P4 verifies this. |
 | Inconsistent principle numbering across domains | Enforce 10 principles per domain (D-018); CI check in P4. |
 | Anti-patterns examples contradict principles | examples/bad/* must reference the principle they violate (P5 task). |
 | Manifest drift (unlisted docs appear) | P4 review/anti-patterns.md documents this; MANIFEST is regenerated from the tree. |
 ## Conclusions
 1. Atelier's unique value is the **traceable principle matrix** — not the individual docs.
 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).
@@ -0,0 +1,50 @@
 # Atelier — Roadmap
 ## 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)
 **Phases:** P0 (pre-execution) + P1–P6 (execution) + P7 (final review+ship)
 | Phase | Name | Type | Status | Key Deliverables |
 |-------|------|------|--------|------------------|
 | 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
 Per branch-strategy.md, milestone `v0.1` tags run on the `v0.0.x` patch line:
 | Phase | Tag | Notes |
 |-------|-----|-------|
 | P0 | v0.0.0 | Pre-execution release |
 | P1 | v0.0.1 | Core foundation |
 | P2 | v0.0.2 | Domain first-principles |
 | P3 | v0.0.3 | Domain derived docs |
 | P4 | v0.0.4 | Matrix + review |
 | P5 | v0.0.5 | Examples |
 | P6 | v0.0.6 | Languages + meta |
 | P7 | v0.0.7 | Final review + ship — **IS the v0.1 milestone release** |
 NFR milestone: no separate minor tag. The final patch (v0.0.7) IS the v0.1 deliverable.
 ## Next
 - Phase 0: complete specify → clarify → research → plan → grill → ship
 - Phase 1: write core foundation documents
 ## Success Criteria
 - [ ] 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
@@ -0,0 +1,70 @@
 {
  "projects": [
    {
      "slug": "atelier",
      "name": "Atelier",
      "milestone": "v0.1",
      "status": "specify"
    }
  ],
  "active_project": "atelier",
  "active_projects": ["atelier"],
  "autonomy": {
    "level": "full",
    "escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
    "clarify_budget": 10,
    "decision_confidence_threshold": 0.6,
    "max_revision_iterations": 3,
    "max_verification_retries": 2,
    "escalation_timeout_ms": 300000
  },
  "model_profile": "quality",
  "parallelization": {
    "enabled": true,
    "max_concurrent_agents": 5,
    "min_plans_for_parallel": 2,
    "max_concurrent_projects": 3
  },
  "verification": {
    "automated_only": true,
    "escalate_visual": true,
    "escalate_external_integration": true,
    "test_first": false
  },
  "security": {
    "auto_accept_low_severity": true,
    "auto_mitigate_medium_severity": true,
    "escalate_high_severity": true
  },
  "git": {
    "branching_strategy": "phase",
    "auto_commit": true,
    "auto_push": true
  },
  "sessions": {
    "max_concurrent_sessions": 3,
    "session_timeout_ms": 3600000,
    "session_isolation": "branch"
  },
  "personas": {
    "enabled": true,
    "territory_enforcement": "warn"
  },
  "release": {
    "forge": "gitea",
    "base_url": "https://git.cloudinit.dev",
    "owner": "cloudinit-bot",
    "repo": "atelier"
  },
  "gitea": {
    "base_url": "https://git.cloudinit.dev",
    "api_token_env": "GITEA_API_TOKEN",
    "owner": "cloudinit-bot",
    "repo": "atelier"
  },
  "ship": {
    "per_phase": true,
    "allow_skip": false,
    "max_release_retries": 3
  }
 }
@@ -0,0 +1,3 @@
 .env
 .env.secrets
 .env.*
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2026 Atelier contributors
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -0,0 +1,44 @@
 # Atelier — Document Manifest
 > Authoritative index. If a document is not listed here, it is not
 > part of the framework.
 ## Reading Order
 1. `core/first-principles.md`              — Required first
 2. `core/conflict-resolution.md`           — Required
 3. `domains/<relevant>/first-principles.md`— Per task
 4. `domains/<relevant>/<topic>.md`         — As needed
 5. `matrix/principles-matrix.md`           — Reference
 ## Core
 | Document                                | Status   | Audience |
 |-----------------------------------------|----------|----------|
 | `core/first-principles.md`              | Stable   | All      |
 | `core/conflict-resolution.md`           | Stable   | All      |
 | `core/reading-order.md`                 | Stable   | All      |
 ## Domains
 | Domain        | First Principles | Derived Documents                |
 |---------------|------------------|----------------------------------|
 | UI / UX       | ✓                | components, accessibility, tokens, copywriting |
 | API Design    | ✓                | rest, graphql, versioning, error-responses, pagination |
 | Security      | ✓                | authentication, authorization, input-validation, secrets, supply-chain |
 | Data          | ✓                | schema-design, migrations, indexing |
 | Testing       | ✓                | pyramid, fixtures |
 | Performance   | ✓                | frontend, backend |
 | Observability | ✓                | logging, metrics, tracing |
 | Errors        | ✓                | patterns |
 | Documentation | ✓                | doc-templates |
 | Concurrency   | ✓                | patterns |
 | DevOps        | ✓                | ci-cd, environments |
 ## Cross-Cutting
 | Document                          | Purpose                          |
 |-----------------------------------|----------------------------------|
 | `matrix/principles-matrix.md`     | Maps domain → core principles    |
 | `review/agent-checklist.md`       | Pre-completion agent checklist   |
 | `review/anti-patterns.md`         | Catalog of violations            |
@@ -0,0 +1,90 @@
 # Atelier
 A first-principles, docs-as-code engineering framework for AI agents and humans.
 ## What This Is
 Atelier is a hierarchical document tree of engineering principles. Eight universal **core principles** (C1–C8) govern eleven **domains** (API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps, UI/UX), each with ten derived principles (P1–P10). A **principles matrix** maps every domain rule back to the core rule it derives from, making conflict resolution deterministic.
 This is not a style guide. This is not a linter. This is a principle hierarchy with cross-references, consumed by AI agents as pre-completion guidance and by humans as engineering canon.
 ## Who It's For
 - **AI agents** — read `core/` then the relevant `domains/` before completing a coding task. Run `review/agent-checklist.md` before finishing.
 - **Human engineers** — read `README.md` → `MANIFEST.md` → `core/` for onboarding, then the domains relevant to your work.
 - **Reviewers** — use `review/peer-review-checklist.md` and `review/anti-patterns.md`.
 ## Quickstart
 ### For Agents
 1. Read `core/first-principles.md` (the 8 axioms)
 2. Read `core/conflict-resolution.md` (how to resolve rule conflicts)
 3. Read `domains/<your-task-domain>/first-principles.md`
 4. Read `domains/<your-task-domain>/<topic>.md` as needed
 5. Run `review/agent-checklist.md` before completing
 ### For Humans
 1. Read this README
 2. Read `MANIFEST.md` (the authoritative document index)
 3. Read `core/first-principles.md` → `core/conflict-resolution.md` → `core/reading-order.md`
 4. Pick a domain of interest and read its `first-principles.md`
 5. Skim `matrix/principles-matrix.md` to see how everything connects
 ## The Eight Core Principles
 | # | Principle | One-line |
 |---|-----------|----------|
 | C1 | Correctness | The system does what it is supposed to do, and nothing else. |
 | C2 | Clarity | The intent of the code is obvious to its reader. |
 | C3 | Simplicity | The solution is as simple as possible, and no simpler. |
 | C4 | Locality | Decisions and their consequences live near each other. |
 | C5 | Reversibility | Every decision can be undone, and the cost of undoing is known. |
 | C6 | Composability | Parts combine into wholes, and the parts are reusable. |
 | C7 | Observability | The system's behavior is visible to those who must understand it. |
 | C8 | Economy | The system uses no more resources than the task requires. |
 Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never sacrificed.
 ## The Domains
 | Domain | First Principles | Derived Docs |
 |--------|------------------|--------------|
 | UI/UX | ✓ | components, accessibility, tokens, copywriting |
 | API | ✓ | rest, graphql, versioning, error-responses, pagination |
 | Security | ✓ | authentication, authorization, input-validation, secrets, supply-chain |
 | Data | ✓ | schema-design, migrations, indexing |
 | Testing | ✓ | pyramid, fixtures |
 | Performance | ✓ | frontend, backend |
 | Observability | ✓ | logging, metrics, tracing |
 | Errors | ✓ | patterns |
 | Documentation | ✓ | doc-templates |
 | Concurrency | ✓ | patterns |
 | DevOps | ✓ | ci-cd, environments |
 ## Repository Structure
 ```
 atelier/
 ├── core/           # The 8 universal principles (read first)
 ├── domains/        # 11 domains, each with first-principles + derived docs
 ├── languages/      # Language-specific application of domain rules
 ├── review/         # Checklists and anti-patterns
 ├── matrix/         # Cross-reference: domain ↔ core
 ├── examples/       # Worked examples (good + bad)
 ├── MANIFEST.md     # Authoritative document index
 └── README.md       # This file
 ```
 ## License
 MIT. See `LICENSE`.
 ## Contributing
 See `CONTRIBUTING.md`.
 ## Version
 This is v0.1. See `CHANGELOG.md` for version history.
@@ -0,0 +1,105 @@
 # Core — Conflict Resolution
 **Status:** Foundational
 **Audience:** All agents and humans. Read after `first-principles.md`.
 ## 1. Why Conflict Resolution Exists
 Atelier has eight core principles and eleven domains, each with ten principles. Rules will conflict. When they do, there must be a deterministic procedure to resolve the conflict — not a debate. This document is that procedure.
 ## 2. The Hierarchy (Strict)
 ```
 core/first-principles.md          ← highest authority
  └── domains/<x>/first-principles.md
        └── domains/<x>/<topic>.md
              └── languages/<lang>.md
                    └── examples/<x>.md   ← lowest authority
 ```
 **Rules:**
 1. A higher document overrides a lower document when they conflict.
 2. `core/first-principles.md` is never overridden.
 3. Within a level, the more specific document wins for its specific scope.
 4. If two documents at the same level conflict with equal specificity, the core principle they each derive from decides — the higher-precedence core principle wins.
 ## 3. Core Principle Precedence (Total Order)
 ```
 C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
 C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
 ```
 - **C1 is never sacrificed.** No other principle, domain rule, or convenience overrides correctness.
 - **C2 is sacrificed only for C1.** Clarity gives way only when making code correct makes it unavoidably unclear (rare; usually clarity and correctness align).
 - **C3 is sacrificed only for C1 or C2.** Simplicity yields to correctness and clarity.
 - **C4–C8 are tradeable** among themselves, but always below C1–C3. Their relative order is: Locality > Reversibility > Composability > Observability > Economy.
 - The precedence is **total**: a violation of a higher principle is never justified by appeal to a lower one.
 ## 4. Conflict Resolution Procedure
 When two rules conflict:
 ### Step 1 — Identify the level of each rule
 - Is it core, domain-first-principles, domain-topic, language, or example?
 ### Step 2 — Apply the hierarchy
 - The higher-level rule wins. Done.
 - If same level, proceed to Step 3.
 ### Step 3 — Identify the core derivation
 - Look up each rule in `matrix/principles-matrix.md`.
 - Each rule derives from one or more core principles (e.g., Security P2 derives from C3 and C8).
 ### Step 4 — Apply core precedence
 - Compare the highest-precedence core principle each rule derives from.
 - The rule deriving from the higher-precedence core principle wins.
 - Example: a rule deriving from C1 (Correctness) beats a rule deriving from C8 (Economy), always.
 ### Step 5 — If still tied, the more specific scope wins
 - A rule scoped to "API endpoints" wins over a rule scoped to "all code" for API endpoint conflicts.
 - A rule scoped to "TypeScript" wins over a rule scoped to "all languages" for TypeScript conflicts.
 ### Step 6 — If still tied, the conflict is a defect
 - File an issue. One of the rules is wrong. Do not silently pick one.
 - The matrix should not produce ties. If it does, the matrix is incomplete.
 ## 5. Worked Examples
 ### Example A: Security P9 (Secret Hygiene) vs DevOps P9 (Documentation in Pipeline)
 - Both are domain-level. Same level → Step 3.
 - Security P9 derives from C6, C7 (per matrix).
 - DevOps P9 derives from C2 (per matrix).
 - C2 > C6 and C7? **No** — C2 is precedence 2, C6 is 6, C7 is 7. C2 is higher.
 - But wait: Security P9 is **non-tradeable** per the security domain's own conflict resolution. Security's manifesto says 8 of 10 principles are never sacrificed.
 - **Resolution:** Security domain's non-tradeable declaration is a domain-level rule that itself derives from C1 (Correctness — security failures are correctness failures). So Security P9 effectively derives from C1. C1 > C2. **Security P9 wins.** Do not log secrets in the pipeline.
 - **Lesson:** A domain's "never sacrificed" declaration promotes those rules to C1-equivalent.
 ### Example B: Performance P8 (Budget Discipline) vs Clarity (C2)
 - Performance P8 is domain-level, derives from C8 (Economy).
 - Clarity is core-level (C2).
 - Core > domain. **C2 Clarity wins.** Clear code that is slightly over budget beats opaque code that is under budget.
 - **Exception:** if the budget is a correctness requirement (e.g., real-time system), the budget derives from C1, and C1 > C2. Then the budget wins.
 ### Example C: API P5 (Versioning) vs API P10 (Stability)
 - Both are in the same domain (api), same level.
 - API P5 derives from C5 (Reversibility). API P10 derives from C5 (Reversibility). Same core derivation — tied.
 - API's own conflict resolution (in `domains/api/first-principles.md` §3): "Versioning — never sacrificed." So P5 wins.
 - **Resolution:** Versioning wins. You version the change rather than break stability, because versioning is the mechanism that enables stability. They are not actually in conflict — versioning is how you preserve stability.
 ## 6. Non-Tradeable Declarations
 Some domains declare certain principles non-tradeable (e.g., Security: 8 of 10). These declarations are binding:
 - A non-tradeable domain rule is treated as deriving from C1 (Correctness), regardless of its matrix entry.
 - This is because the domain has asserted that violating the rule is a correctness failure in that domain's scope.
 - Non-tradeable rules can still conflict with each other (e.g., two security rules). The domain's own precedence (in its §3) resolves those.
 ## 7. The Matrix is the Arbiter
 `matrix/principles-matrix.md` is the single source of truth for derivations. If a rule is not in the matrix, it is not part of the framework. If the matrix and a domain document disagree, **the matrix wins** — the domain document must be corrected to match the matrix, or the matrix must be updated with a new derivation (a docs change, not a silent edit).
 ## 8. Conflicts with This Document
 If `core/conflict-resolution.md` conflicts with `core/first-principles.md`, `first-principles.md` wins. This document is the procedure; the principles are the authority.
@@ -0,0 +1,114 @@
 # Core — First Principles
 **Version:** 1.0.0
 **Status:** Foundational
 **Audience:** All agents and humans. Read this first.
 ## 1. Manifesto
 There are eight principles from which all other principles derive. Every domain rule, every language rule, every review checklist traces back to one or more of these. When two rules conflict, the higher-precedence core principle wins. When a rule has no derivation here, it is orphaned and must be removed or re-derived.
 These principles are universal. They apply to every language, every domain, every system. They are not opinions; they are the axioms of quality software.
 ## 2. The Principles
 ### C1. Correctness
 The system does what it is supposed to do, and nothing else.
 - Correctness is the highest principle. No other principle overrides it.
 - A correct system handles the specified cases, the edge cases, and the failure cases — all defined by the domain.
 - Incorrect code that is fast, clear, or simple is still wrong.
 - Security is a subset of correctness: code that is exploitable does not do what it was supposed to do.
 - Correctness includes temporal correctness: a late answer is a wrong answer when the deadline mattered.
 ### C2. Clarity
 The intent of the code is obvious to its reader.
 - Code is read more than it is written. Optimize for the reader.
 - Names reveal intent. Comments explain why, not what.
 - A stranger should understand the code without reading the documentation. The documentation should make the code unnecessary to read.
 - Clarity serves correctness: unclear code is where bugs hide.
 ### C3. Simplicity
 The solution is as simple as possible, and no simpler.
 - Complexity is the enemy of correctness. Every line of code is a liability.
 - Simplicity is not laziness. It is the result of removing everything unnecessary.
 - A simple solution handles the requirement completely. A simpler-than-necessary solution does not.
 - Simplicity serves economy: less code, less to test, less to maintain.
 ### C4. Locality
 Decisions and their consequences live near each other.
 - State, logic, and side effects that depend on each other live near each other.
 - Locality serves clarity: to understand a piece of code, you should not need to read the whole system.
 - Locality serves correctness: coupling that is far apart is coupling you cannot see.
 - A change that requires touching many distant files is a locality violation.
 ### C5. Reversibility
 Every decision can be undone, and the cost of undoing is known.
 - Reversibility serves safety: an irreversible decision is a bet you cannot hedge.
 - Migrations, deployments, schema changes, and API changes are reversible by default.
 - A decision that cannot be reversed is made with the maximum of evidence and the minimum of haste.
 - Versioning, feature flags, and rollback paths are the mechanisms of reversibility.
 ### C6. Composability
 Parts combine into wholes, and the parts are reusable in new wholes.
 - Composability serves scale: complex systems are built from simple, composable parts.
 - A part that does one thing well composes. A part that does many things configures.
 - The boundary of a part is its contract. Contracts are explicit and stable.
 - Composability serves clarity: composable parts are understandable in isolation.
 ### C7. Observability
 The system's behavior is visible to the people who must understand it.
 - Observability serves correctness: you cannot fix what you cannot see.
 - Logs, metrics, and traces are first-class. They are designed in, not bolted on.
 - Observability serves clarity: the system explains itself in production.
 - An observable system answers "what happened, why, and what next?" without reading the source.
 ### C8. Economy
 The system uses no more resources than the task requires.
 - Resources include time, memory, attention, money, and complexity.
 - Economy serves simplicity: the cheapest solution is often the simplest.
 - Economy is the most tradeable principle: it is sacrificed for correctness, clarity, and reversibility.
 - But unbounded economy is a bug: unbounded growth in any resource is a defect.
 ## 3. Precedence
 When principles conflict, the lower-numbered principle wins:
 ```
 C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
 C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
 ```
 - C1 (Correctness) is never sacrificed.
 - C2 (Clarity) is sacrificed only for C1 (Correctness).
 - C3 (Simplicity) is sacrificed only for C1 or C2.
 - C4–C8 are tradeable among themselves, but always below C1–C3.
 - The precedence is total: a violation of C1 is never justified by an appeal to C8.
 See `core/conflict-resolution.md` for the formal conflict resolution procedure.
 ## 4. What Violates These Principles
 | Violation | Principle Breached |
 |-----------|-------------------|
 | Code that "mostly works" | C1 Correctness |
 | A function named `doStuff` | C2 Clarity |
 | A 500-line function that could be 50 | C3 Simplicity |
 | Config in a distant repo, code reads it silently | C4 Locality |
 | A migration with no rollback | C5 Reversibility |
 | A component that reads global state implicitly | C6 Composability |
 | A service with no logs | C7 Observability |
 | Loading all records into memory | C8 Economy |
 ## 5. Relationship to Domains
 Every domain in Atelier derives its own P1–P10 principles from these eight. The mapping is recorded in `matrix/principles-matrix.md`. A domain rule that cannot be traced to a core principle is orphaned and must be removed.
 The eight principles are the floor. The domain principles are the ceiling for their scope. Within a domain, the domain's precedence applies; across domains, the core precedence applies.
@@ -0,0 +1,103 @@
 # Core — Reading Order
 **Status:** Foundational
 **Audience:** New readers (agents and humans). Read after `first-principles.md` and `conflict-resolution.md`.
 ## 1. The Canonical Order
 This is the order in which the framework is designed to be consumed. Following it ensures you build the mental model before the details.
 ### For All Readers
 1. **`core/first-principles.md`** — The eight axioms. Everything derives from these. Read first, always.
 2. **`core/conflict-resolution.md`** — How to resolve disagreements between rules. Read second, always.
 3. **`core/reading-order.md`** — This document. You are here.
 ### For a Specific Task
 4. **`domains/<relevant>/first-principles.md`** — The domain's ten principles. Read the domain(s) relevant to your task.
 5. **`domains/<relevant>/<topic>.md`** — The domain's derived topic docs. Read only what your task needs.
 ### For Reference
 6. **`matrix/principles-matrix.md`** — The full mapping of every domain principle to its core derivation. Consult when a rule's authority is unclear or a conflict arises.
 7. **`MANIFEST.md`** — The authoritative index of all framework documents. If a document is not here, it is not part of the framework.
 ### For Evaluation
 8. **`review/agent-checklist.md`** — The pre-completion checklist. Agents run this before finishing a task.
 9. **`review/peer-review-checklist.md`** — The human review checklist.
 10. **`review/anti-patterns.md`** — Catalog of known violations.
 ### For Language-Specific Application
 11. **`languages/<lang>.md`** — How the domain principles apply in a specific language. Read only for the language you are working in.
 ### For Illustration
 12. **`examples/good/*`** — Worked examples of the framework applied correctly.
 13. **`examples/bad/*`** — Worked examples of violations, with the breached principles cited.
 ## 2. Reading Paths
 ### Path A: New Agent (Pre-Task)
 ```
 core/first-principles.md
  → core/conflict-resolution.md
    → core/reading-order.md
      → domains/<task-domain>/first-principles.md
        → domains/<task-domain>/<topic>.md
          → review/agent-checklist.md (run before completing)
 ```
 Estimated time: 15–25 minutes depending on domain depth.
 ### Path B: New Human (Onboarding)
 ```
 README.md
  → MANIFEST.md
    → core/first-principles.md
      → core/conflict-resolution.md
        → core/reading-order.md
          → one domain of personal interest (e.g., domains/api/first-principles.md)
            → matrix/principles-matrix.md (skim)
 ```
 Estimated time: 30–45 minutes for a full pass.
 ### Path C: Conflict Resolution
 ```
 core/conflict-resolution.md (procedure)
  → matrix/principles-matrix.md (look up both rules' derivations)
    → core/first-principles.md (apply precedence)
 ```
 Estimated time: 5 minutes per conflict.
 ### Path D: Review
 ```
 review/agent-checklist.md (or peer-review-checklist.md)
  → for each failed checklist item, follow Path C
    → examples/bad/* for the relevant violation pattern
 ```
 ## 3. What Not to Read First
 - **Do not** start with `examples/`. Examples illustrate principles you have not yet read.
 - **Do not** start with `languages/`. Language rules derive from domain rules you have not yet read.
 - **Do not** start with `matrix/`. The matrix is a reference, not a tutorial.
 - **Do not** skip `core/`. Everything depends on it.
 ## 4. Skipping is Allowed After Core
 After reading `core/` (the three foundational documents), you may skip freely. The domains are independent of each other. You do not need to read `domains/security/` to use `domains/api/`. You only need the domain relevant to your task.
 The one exception: `matrix/principles-matrix.md` references all domains. You do not need to read all domains to use the matrix, but the matrix is most useful when you have read at least one domain.
 ## 5. Versioning
 The framework versions as a whole (semantic versioning). A change to `core/first-principles.md` is a major version. A new domain is a minor version. A new topic doc is a patch. See `CHANGELOG.md` for the version history.
@@ -0,0 +1,84 @@
 # API Design — First Principles
 **Version:** 1.0.0
 **Status:** Foundational
 **Audience:** AI agents and humans designing APIs (REST, GraphQL,
 gRPC, RPC, libraries).
 ## 1. Manifesto
 An API is a contract between systems and the people who build on
 them. The cost of an API is paid by every consumer, forever. The
 highest quality API is one that a stranger can use correctly without
 reading the source.
 ## 2. The Principles
 ### P1. Contract Fidelity
 The API does what its documentation says, and the documentation says
 what the API does. Nothing more, nothing less.
 ### P2. Clarity
 Endpoints, methods, parameters, and responses are named and structured
 for the consumer — not for the implementer.
 ### P3. Predictability
 Consumers can guess behavior without reading docs. Patterns repeat.
 Surprises are bugs.
 ### P4. Composability
 Resources and operations combine cleanly. The whole is greater than
 the sum of its parts, and the parts are reusable in new wholes.
 ### P5. Versioning
 Changes are managed explicitly, not implicitly. Consumers know what
 will break, and when.
 ### P6. Idempotency
 Repeated identical calls have the same effect as a single call. Retry
 is a first-class operation.
 ### P7. Performance
 Latency, payload size, and call count are designed in — not optimized
 out.
 ### P8. Security
 Authentication, authorization, validation, and rate limiting are
 defaults, not add-ons.
 ### P9. Error Transparency
 Failures are communicated specifically, structurally, and actionably.
 ### P10. Stability
 Consumers can build on the API without fear of breakage. Backward
 compatibility is a default.
 ## 3. Conflict Resolution
 1. Contract Fidelity — never sacrificed.
 2. Security — never sacrificed.
 3. Stability — sacrificed only with a documented deprecation cycle.
 4. Clarity — sacrificed only for Performance with evidence.
 5. Predictability — sacrificed for Composability when patterns diverge.
 6. Composability — sacrificed for Clarity when abstractions confuse.
 7. Idempotency — sacrificed only for genuinely non-idempotent operations.
 8. Performance — sacrificed only with measurement.
 9. Error Transparency — sacrificed only for security-sensitive errors.
 10. Versioning — never sacrificed (always have a version policy).
 ## 4. What Violates These Principles
 | Violation                          | Principle Breached    |
 |------------------------------------|----------------------|
 | Endpoint name exposes DB schema    | P2 Clarity           |
 | Breaking change without deprecation | P10 Stability       |
 | Generic 500 with stack trace       | P9 Error Transparency|
 | Auth as opt-in                     | P8 Security          |
 | Non-idempotent POST without key    | P6 Idempotency       |
 | Inconsistent naming across endpoints | P3 Predictability  |
 | Required response field undocumented | P1 Contract Fidelity |
 | 10MB response payload by default   | P7 Performance       |
 ## 5. Relationship to Core
 Subordinate to `core/first-principles.md`. See `matrix/principles-matrix.md`.
@@ -0,0 +1,41 @@
 # Concurrency — First Principles
 ## 1. The Principles
 ### P1. Immutability by Default
 Mutable shared state is the enemy. The default is immutable; mutation
 is justified.
 ### P2. Single Responsibility for Threads
 Each unit of work has one owner. No "anyone can touch this" state.
 ### P3. Boundaries are Locks
 Synchronization happens at well-defined places. Lock scope is
 minimal and explicit.
 ### P4. Determinism Over Speed
 Correct concurrent code is faster than incorrect concurrent code.
 Race conditions are not "fast enough" — they are wrong.
 ### P5. Lock Minimization
 Locks are expensive and dangerous. Lock-free, wait-free, and
 message-passing are preferred where possible.
 ### P6. No Silent Races
 Race conditions are caught, not hidden. Tools (TSan, Go race
 detector) are part of CI.
 ### P7. Cancellation Support
 Every async operation can be cancelled. Cancellation is fast and
 complete.
 ### P8. Timeout Discipline
 Every blocking call has a timeout. Forever is not a duration.
 ### P9. Bounded Queues
 Unbounded queues are memory leaks in disguise. Bounded queues
 expose backpressure.
 ### P10. Test for Race Conditions
 Concurrent code is tested under concurrent load, not just happy-path
 correctness.
@@ -0,0 +1,43 @@
 # Data — First Principles
 ## 1. The Principles
 ### P1. Truth
 The schema reflects the domain, not the application. If the data
 model lies, every query lies.
 ### P2. Normalization Discipline
 Duplication is a bug waiting to happen. The same fact lives in one
 place.
 ### P3. Invariants in the Schema
 Constraints live where the data lives. Application-layer checks are
 defense, not enforcement.
 ### P4. Migration Safety
 Schema changes are reversible, non-destructive, and tested. Production
 data is sacred.
 ### P5. Indexing with Intent
 Indexes exist for known query patterns. Every index earns its write
 cost.
 ### P6. Naming Consistency
 Same concept, same name, always. Across tables, columns, code, and
 APIs.
 ### P7. Type Fidelity
 Types match domain meaning. A `string` is rarely the right type for
 an email, an ID, or a status.
 ### P8. Lifecycle Awareness
 Data has a creation, a lifetime, and an end. Archival and deletion
 are first-class.
 ### P9. Referential Integrity
 Relationships are enforced, not assumed. Foreign keys exist. CASCADE
 is intentional.
 ### P10. Performance Awareness
 Schema choices have cost. Query plans are reviewed. Cardinality is
 understood.
@@ -0,0 +1,43 @@
 # DevOps — First Principles
 ## 1. The Principles
 ### P1. Reproducibility
 Any environment can be rebuilt from source. Configuration is
 declarative and versioned.
 ### P2. Automation
 Manual steps are bugs waiting to happen. Everything is scripted,
 testable, repeatable.
 ### P3. Observability
 You cannot operate what you cannot see. Logs, metrics, and traces
 are first-class.
 ### P4. Rollback First
 Every deploy has a known-good rollback path. Rollback is rehearsed,
 not improvised.
 ### P5. Progressive Delivery
 Changes go out gradually — canary, blue-green, feature flags.
 Big-bang deploys are for prototypes.
 ### P6. Configuration as Code
 No snowflake servers. No "this one is different". Configuration is
 in the repo.
 ### P7. Immutability
 Build once, deploy many. Artifacts are immutable. Servers are not
 mutated in place.
 ### P8. Security at Every Layer
 Scanning, signing, SBOM, and supply chain integrity are part of the
 pipeline, not bolt-ons.
 ### P9. Documentation in the Pipeline
 The pipeline is the documentation. Reading the pipeline tells you
 how the system ships.
 ### P10. Failure as Expected
 Design for the failure mode, not the happy path. Chaos engineering
 is a discipline.
@@ -0,0 +1,37 @@
 # Documentation — First Principles
 ## 1. The Principles
 ### P1. Documentation is Code
 It is versioned, reviewed, tested, and owned. Unowned docs rot.
 ### P2. Audience Awareness
 Different readers need different docs. A new user, an operator, and
 a contributor are different audiences.
 ### P3. Examples are Mandatory
 Code without examples is incomplete. Show, then explain.
 ### P4. Currency
 Docs that lie are worse than no docs. Stale docs are technical debt.
 ### P5. Discoverability
 The right doc is findable in under a minute. Structure, search, and
 indexing are part of the doc.
 ### P6. Conciseness
 Say what is needed, no more. Verbose docs are skimmed, then ignored.
 ### P7. Structure
 Consistent structure aids scanning. Headings, ordering, and
 formatting follow conventions.
 ### P8. Why Over What
 Document intent, decisions, and tradeoffs. The "what" is in the code.
 ### P9. Living Documents
 Docs evolve with code, not after. Doc PRs ship with code PRs.
 ### P10. Public by Default
 If it is not documented, it does not exist. The absence of docs is
 a feature gap.
@@ -0,0 +1,41 @@
 # Error Handling — First Principles
 ## 1. The Principles
 ### P1. Errors are Data
 Errors are structured, typed, and intentional. They are values, not
 exceptions to the flow of code.
 ### P2. Fail Loudly
 Never swallow an error. Silent failure is worse than visible failure.
 ### P3. Fail Specifically
 Generic errors are debugging enemies. "Something went wrong" is
 never acceptable.
 ### P4. Preserve Context
 Errors carry where (file, line, function), when (timestamp, request),
 why (cause), and what (user-facing message).
 ### P5. Recoverable When Possible
 Retry, fallback, or degrade. Do not crash what can be salvaged.
 ### P6. Unrecoverable Means Stop
 When recovery is impossible or unsafe, fail fast. Do not limp on
 after fatal errors.
 ### P7. Errors are Boundaries
 Define how errors cross API, service, and module boundaries. Translation
 is explicit, not accidental.
 ### P8. User-Facing Errors are UX
 Error messages are a feature. They are written for the user, not the
 developer.
 ### P9. Errors are Logged
 Even when handled, errors are recorded. The handling is the recovery;
 the log is the memory.
 ### P10. Errors Don't Lie
 Never catch what you cannot handle. Never claim success on failure.
 Never claim failure on success.
@@ -0,0 +1,43 @@
 # Observability — First Principles
 ## 1. The Principles
 ### P1. Structured by Default
 Logs, metrics, and traces are structured. Free-form text is for
 humans; machines need fields.
 ### P2. Correlation
 Every event is traceable to a request, a user, an action, a trace ID.
 Context flows through the system.
 ### P3. Sufficient Context
 The information needed to debug is in the event itself, not in tribal
 knowledge. "What was the user doing?" is answerable from logs.
 ### P4. Cardinality Discipline
 Labels and tags have bounded cardinality. Unbounded labels are an
 unbounded bill.
 ### P5. Sampling with Intent
 Sampling is deliberate, documented, and consistent. Head-based,
 tail-based, or none — chosen with reason.
 ### P6. No Secrets in Observability
 Observability data is not a secrets channel. Tokens, passwords, and
 PII do not enter logs, metrics, or traces.
 ### P7. Actionable Alerts
 Alerts are for things humans must act on. Every alert has a runbook.
 Alert fatigue is a defect.
 ### P8. SLI/SLO Awareness
 "Good enough" is defined. SLOs are targets, not aspirations.
 Error budgets are real.
 ### P9. Cost Awareness
 Observability has a cost — storage, compute, attention. Spend it on
 what earns it.
 ### P10. Debuggability Over Coverage
 A few high-cardinality traces beat millions of low-context logs.
 Signal beats volume.
@@ -0,0 +1,40 @@
 # Performance — First Principles
 ## 1. The Principles
 ### P1. Measure First
 No optimization without measurement. Intuition about performance is
 usually wrong.
 ### P2. Critical Path Focus
 Optimize what users actually wait for. The 95th percentile matters
 more than the average.
 ### P3. Complexity Awareness
 Algorithmic cost is known. Big-O is a design conversation, not an
 afterthought.
 ### P4. Resource Bounds
 Memory, CPU, I/O, network — all bounded. Unbounded growth is a bug.
 ### P5. Caching with Intent
 Cache what is expensive, stable, and read often. Invalidation is
 designed, not bolted on.
 ### P6. Lazy by Default
 Compute only when needed. Pay only for what is used.
 ### P7. Async When Independent
 Work that does not depend on other work runs in parallel.
 ### P8. Budget Discipline
 Performance is a design constraint. The budget is set, not negotiated
 after the fact.
 ### P9. Perceived Performance
 What the user feels is what matters. A 200ms perceived response beats
 a 50ms measured one with no feedback.
 ### P10. Regression Prevention
 Performance tests catch what functional tests miss. The slow path
 is tested as a path.
@@ -0,0 +1,102 @@
 # Security — First Principles
 **Version:** 1.0.0
 **Status:** Foundational
 **Audience:** AI agents and humans handling authentication, data,
 trust boundaries, or any security-relevant code.
 ## 1. Manifesto
 Security is not a feature. It is a property of correct code. The
 highest quality code is code that does what it is supposed to do —
 and nothing else, no matter who asks.
 An AI agent using this framework does not "add security". It writes
 secure code by default. There is no version of correct code that is
 insecure.
 ## 2. The Principles
 ### P1. Zero Trust
 No request, user, system, or input is trusted by default. Trust is
 earned at every boundary, every time.
 ### P2. Least Privilege
 Every actor — user, service, process — gets the minimum access
 required to do its job, for the minimum time required.
 ### P3. Defense in Depth
 Security is layered. No single control is load-bearing. The failure
 of one control does not compromise the system.
 ### P4. Input Validation
 All input is untrusted until proven otherwise. Validation happens at
 the boundary, against a schema, with explicit failure modes.
 ### P5. Output Safety
 All output is encoded, escaped, or filtered for its destination
 context. The system never trusts its callers, including itself.
 ### P6. Cryptographic Correctness
 Crypto is hard. Use vetted, maintained libraries. Never roll your
 own. Never invent your own primitives. Never bypass a primitive to
 "make it work".
 ### P7. Auditability
 Security-relevant events — auth attempts, authz decisions, data
 access, configuration changes — are logged with sufficient context
 to investigate.
 ### P8. Fail Securely
 When security fails, it fails closed. The default state is denied,
 disabled, or safe. Errors never grant access by accident.
 ### P9. Secret Hygiene
 Secrets are not in code, configs, logs, error messages, URLs, or
 screenshots. Secrets are loaded from a secrets manager and treated
 as transient.
 ### P10. Surface Minimization
 The smaller the attack surface, the smaller the risk. Dependencies
 are minimized. Endpoints are minimized. Features are minimized. Code
 that does not exist cannot be exploited.
 ## 3. Conflict Resolution
 1. Zero Trust — never sacrificed.
 2. Least Privilege — never sacrificed.
 3. Defense in Depth — never sacrificed.
 4. Input Validation — never sacrificed.
 5. Output Safety — never sacrificed.
 6. Cryptographic Correctness — never sacrificed.
 7. Fail Securely — never sacrificed.
 8. Auditability — sacrificed only when logging itself is the threat.
 9. Secret Hygiene — never sacrificed.
 10. Surface Minimization — sacrificed only when a feature is required.
 Eight of ten principles are non-tradeable. Security does not
 trade-off. It is either present or it is not.
 ## 4. What Violates These Principles
 | Violation                          | Principle Breached    |
 |------------------------------------|----------------------|
 | `SELECT *` from user input         | P4 Input Validation  |
 | `eval()` of any string             | P4, P5               |
 | Hardcoded API key in source        | P9 Secret Hygiene    |
 | Catch-all `catch (e) {}`           | P7 Auditability, P8 Fail Securely |
 | `md5` or `sha1` for security       | P6 Crypto Correctness |
 | Open CORS to `*` in production     | P1 Zero Trust, P10   |
 | Detailed error to end user         | P7 Auditability, P5  |
 | `chmod 777`                        | P2 Least Privilege   |
 | Long-lived session token           | P1, P2               |
 | Logging the request body           | P9 Secret Hygiene    |
 These are never acceptable. They are not "to be reviewed later".
 They are rejected on sight.
 ## 5. Relationship to Core
 Subordinate to `core/first-principles.md`. Note: security principles
 overlap heavily with core Correctness (C1) and Observability (C7).
 See `matrix/principles-matrix.md`.
@@ -0,0 +1,44 @@
 # Testing — First Principles
 ## 1. The Principles
 ### P1. Tests as Specification
 Tests document what the code should do. Reading the tests is reading
 the contract.
 ### P2. Independence
 Tests do not depend on each other. Order does not matter. Parallelism
 is the default.
 ### P3. Determinism
 Same input, same output, every time. No time, randomness, network, or
 filesystem in the test path unless explicitly modeled.
 ### P4. Fast Feedback
 Tests run in seconds, not minutes. Slow tests are skipped, then
 deleted.
 ### P5. Coverage of Behavior
 Cover what the code does, not what it is. Lines covered is not the
 goal. Behaviors exercised is the goal.
 ### P6. Failure Specificity
 A failing test names the file, the function, the input, the
 expectation, and the actual. A test that fails unhelpfully is
 broken.
 ### P7. Realism
 Test data resembles production data in shape, distribution, and
 edge cases. Toy data hides bugs.
 ### P8. Maintainability
 Tests are first-class code. They are read, reviewed, and refactored.
 Test code is not throwaway.
 ### P9. Edge Case Coverage
 Boundaries, nulls, empty sets, maximums, minimums, and invalid inputs
 are tested. The middle of the range is the easy part.
 ### P10. No Test Theater
 A test that cannot fail is not a test. A test that asserts nothing
 is a lie. Tests earn their place by being able to catch real bugs.
@@ -0,0 +1,50 @@
 # Accessibility Requirements
 > Detailed, enforceable accessibility rules. Every component, page,
 > and flow must pass these. Failure is disqualifying — see
 > `first-principles.md` P2.
 ## Perceivable
 - [ ] Every image has `alt` text or is marked `alt=""` if decorative.
 - [ ] Every video has captions. Every audio has transcripts.
 - [ ] Color contrast meets WCAG 2.1 AA (4.5:1 text, 3:1 UI).
 - [ ] Information is not conveyed by color alone.
 - [ ] Text resizes to 200% without loss of content or function.
 ## Operable
 - [ ] Every interactive element is keyboard-reachable.
 - [ ] Focus order is logical and matches visual order.
 - [ ] Focus is always visible (≥ 3:1 contrast).
 - [ ] No keyboard traps.
 - [ ] Touch targets are ≥ 44×44 CSS pixels.
 - [ ] Motion can be disabled via `prefers-reduced-motion`.
 - [ ] No flashing content > 3 flashes per second.
 ## Understandable
 - [ ] Page language is declared.
 - [ ] Form fields have associated labels.
 - [ ] Error messages identify the field and the problem.
 - [ ] Navigation is consistent across pages.
 - [ ] Abbreviations and jargon are explained on first use.
 ## Robust
 - [ ] HTML validates.
 - [ ] ARIA is used correctly (roles, states, properties).
 - [ ] Components work across assistive technologies.
 - [ ] No ARIA is used where native HTML would suffice.
 ## Testing
 Every accessibility requirement is verified by:
 1. Automated tool (axe-core, Lighthouse, etc.)
 2. Keyboard-only navigation
 3. Screen reader (NVDA, VoiceOver) walkthrough
 4. Zoom to 200%
 5. Reduced motion enabled
 All five must pass. Automated-only is not acceptance.
@@ -0,0 +1,87 @@
 # Component Design Principles
 > Sibling to `first-principles.md` in this domain. These rules govern
 > how individual UI components are designed, named, composed, and
 > evolved.
 ## 1. Single Responsibility
 A component does one thing, completely.
 - If a component's name contains "And", split it.
 - If a component has more than one primary action, split it.
 - If a component's props cannot be described in one sentence, split it.
 ## 2. Composition Over Configuration
 Components combine. They do not configure.
 - Prefer small, composable primitives over large, configurable ones.
 - Variants are separate components, not boolean props.
 - Layout is composition. The component owns its content, not its
  position.
 - A `Button` is not `Button primary large loading disabled`. It is
  `Button` composed with `<Icon>`, `<Spinner>`, and styled by context.
 ## 3. Explicit Boundaries
 A component's contract is its props and its events.
 - All inputs are typed. Required inputs are required.
 - All outputs are typed. Events are named for what happened, not what
  was clicked.
 - A component never reads from global state implicitly.
 - A component never mutates its inputs.
 ## 4. Predictable State
 A component's state is owned at the lowest level that can manage it.
 - If only the component cares, the component owns it.
 - If siblings care, the parent owns it.
 - If the world cares, the application owns it.
 - State is never duplicated across levels.
 ## 5. Render Purity
 Given the same props and state, a component renders the same output.
 - No hidden inputs (time, randomness, network) inside the render path.
 - Side effects are in effects, event handlers, or data loaders — not
  in render.
 - A component's render is safe to call repeatedly.
 ## 6. Accessible by Default
 A component is not finished until it is accessible.
 - Every interactive component is keyboard-reachable and screen-reader
  announced.
 - Every form control has a label.
 - Every image has alt text or is marked decorative.
 - Every focusable element has a visible focus state.
 - Accessibility is in the component contract, not a wrapper.
 ## 7. Style via Tokens
 A component references design tokens, never raw values.
 - No hardcoded colors, sizes, or fonts in component code.
 - Tokens are the API to the design system.
 - A component without a token is a design debt.
 ## 8. Stable Identity
 A component's identity is its public name, not its implementation.
 - Renaming a component is a breaking change.
 - Removing a prop is a breaking change.
 - Changing a prop's semantics is a breaking change.
 - Deprecate before you delete. Migrate before you rename.
 ## 9. Testable in Isolation
 A component can be rendered, interacted with, and verified in isolation.
 - Components ship with stories, examples, or fixtures.
 - Tests cover behavior, not implementation.
 - Visual regression is part of the contract.
 ## 10. Documented Intent
 A component is shipped with a "why" and a "when".
 - What is it for?
 - When should it be used?
 - When should it NOT be used?
 - What are the common mistakes with it?
@@ -0,0 +1,115 @@
 # UI / UX — First Principles
 **Version:** 1.0.0
 **Status:** Foundational
 **Audience:** AI agents and humans designing user interfaces, components, pages, and flows.
 ## 1. Manifesto
 A user interface is a contract between a system and a person. The cost of a bad interface is paid by every user, every time they use it. The highest quality interface is one that a stranger can use correctly without instructions, regardless of their abilities.
 ## 2. The Principles
 ### P1. User Primacy
 The user's goal is the system's goal. The system never optimizes for itself at the user's expense.
 - A loading indicator exists because the user is waiting, not because the system is busy.
 - A default exists because the user would choose it, not because it is easiest to implement.
 - The system never makes the user do work the system could do.
 ### P2. Accessibility
 Every user can use the interface, regardless of ability or context.
 - Accessibility is not a feature; it is a property of correct interfaces.
 - Failure to be accessible is disqualifying — see `domains/uiux/accessibility.md`.
 - Every interactive element is keyboard-reachable and screen-reader announced.
 ### P3. Clarity
 The interface communicates what it does, what it did, and what will happen next.
 - Labels are nouns. Actions are verbs. States are adjectives.
 - The user should never wonder "what will this do?"
 - A confused user is a defect, not a user error.
 ### P4. Feedback
 Every user action produces an immediate, visible response.
 - The system always acknowledges input, even before it processes it.
 - Feedback is for the user, not the developer. A console log is not feedback.
 - See `domains/observability/` for the system-side complement.
 ### P5. Forgiveness
 User actions are reversible. Mistakes are recoverable.
 - Destructive actions require confirmation. Irreversible actions require double confirmation.
 - Undo is a first-class operation, not an afterthought.
 - The system never traps the user in a state they did not choose.
 ### P6. Performance
 The interface responds in the time the user expects, not the time the system takes.
 - Perceived performance beats measured performance when they diverge.
 - A 200ms response with feedback feels faster than a 50ms response without.
 - See `domains/performance/frontend.md` for the technical complement.
 ### P7. Hierarchy
 The interface communicates priority through structure, not decoration.
 - The most important thing is the most visible.
 - Hierarchy is visual: size, weight, position, contrast. Not noise.
 - A flat interface hides priority. A cluttered interface invents false priority.
 ### P8. Consistency
 The same action has the same result, the same name, and the same location, everywhere.
 - Consistency serves predictability: the user learns once, applies everywhere.
 - Inconsistency is a tax on the user's attention.
 - See `domains/uiux/components.md` for component-level consistency rules.
 ### P9. Simplicity
 The interface shows the user what they need, when they need it, and nothing more.
 - Progressive disclosure: show the common path, hide the rare path.
 - A simple interface is complete for its purpose. A simpler-than-necessary interface is not.
 - Simplicity serves clarity: a cluttered interface is unclear.
 ### P10. Reversibility
 The user can always go back, undo, or cancel.
 - Navigation is reversible. Data changes are reversible. Sessions are resumable.
 - The "back" button always works. The "cancel" button always cancels.
 - Reversibility serves forgiveness (P5): the cost of a mistake is bounded.
 ## 3. Conflict Resolution
 1. Accessibility (P2) — never sacrificed.
 2. Clarity (P3) — never sacrificed.
 3. User Primacy (P1) — never sacrificed.
 4. Forgiveness (P5) — sacrificed only when an action is genuinely irreversible by domain.
 5. Feedback (P4) — sacrificed only for Performance (P6) with perceived-performance evidence.
 6. Consistency (P8) — sacrificed for Clarity (P3) when a context demands a different pattern.
 7. Hierarchy (P7) — sacrificed for Simplicity (P9) when an interface is simple enough to need no hierarchy.
 8. Simplicity (P9) — sacrificed for Clarity (P3) when simplifying would obscure.
 9. Performance (P6) — sacrificed for Feedback (P4) when the user needs to know the system is working.
 10. Reversibility (P10) — sacrificed only for genuinely irreversible operations (e.g., account deletion), with explicit confirmation.
 Three of ten principles are non-tradeable: Accessibility, Clarity, User Primacy. These derive from core C1 (Correctness) and C2 (Clarity).
 ## 4. What Violates These Principles
 | Violation | Principle Breached |
 |-----------|-------------------|
 | A button that does nothing on click | P4 Feedback |
 | An image without alt text | P2 Accessibility |
 | A "delete" with no confirmation | P5 Forgiveness |
 | A 5-second spinner with no progress | P6 Performance, P4 Feedback |
 | Two "save" buttons that do different things | P8 Consistency |
 | A settings page with 50 options visible at once | P9 Simplicity |
 | A form that cannot be navigated by keyboard | P2 Accessibility |
 | An action that cannot be undone or cancelled | P10 Reversibility |
 | A label that says "Submit" when it deletes | P3 Clarity |
 | A system that optimizes its own load time over the user's wait | P1 User Primacy |
 ## 5. Relationship to Core
 Subordinate to `core/first-principles.md`. The three non-tradeable principles (P2, P3, P1) are promoted to C1-equivalent. See `matrix/principles-matrix.md` for the full derivation. Sibling to `domains/uiux/components.md` and `domains/uiux/accessibility.md`.
@@ -0,0 +1,176 @@
 # Principles Matrix
 > Maps every domain principle to the core principle(s) it derives
 > from. Used to verify that no domain rule is orphaned and to resolve
 > conflicts.
 **Core principles key:**
 C1=Correctness · C2=Clarity · C3=Simplicity · C4=Locality ·
 C5=Reversibility · C6=Composability · C7=Observability · C8=Economy
 ---
 ## UI / UX
 | UI/UX Principle           | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 User Primacy           | C2   | Clarity serves the user               |
 | P2 Accessibility          | C1   | Correctness for all abilities         |
 | P3 Clarity                | C2   | Direct derivation                     |
 | P4 Feedback               | C7   | Observability for humans              |
 | P5 Forgiveness            | C5   | Reversibility of user actions         |
 | P6 Performance            | C1   | Correctness includes temporal correctness |
 | P7 Hierarchy              | C2   | Clarity of priority                   |
 | P8 Consistency            | C2   | Clarity through uniformity            |
 | P9 Simplicity             | C3   | Direct derivation                     |
 | P10 Reversibility         | C5   | Direct derivation                     |
 ## API Design
 | API Principle             | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Contract Fidelity      | C1   | Correctness of the public contract    |
 | P2 Clarity                | C2   | Direct derivation                     |
 | P3 Predictability         | C3   | Simplicity of mental model            |
 | P4 Composability          | C6   | Direct derivation                     |
 | P5 Versioning             | C5   | Reversibility for consumers           |
 | P6 Idempotency            | C1   | Correctness under retry               |
 | P7 Performance            | C1   | Correctness includes latency          |
 | P8 Security               | C1   | Correctness includes safety           |
 | P9 Error Transparency     | C7   | Observability of failures             |
 | P10 Stability             | C5   | Reversibility of changes              |
 ## Security
 | Security Principle        | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Zero Trust             | C1   | Correctness requires no false trust   |
 | P2 Least Privilege       | C3, C8 | Simplicity of access; economy of trust |
 | P3 Defense in Depth       | C1   | Correctness under partial failure     |
 | P4 Input Validation       | C1   | Correctness of inputs                 |
 | P5 Output Safety          | C1   | Correctness of outputs                |
 | P6 Crypto Correctness     | C1   | Crypto failures = correctness failures |
 | P7 Auditability           | C7   | Observability of security events      |
 | P8 Fail Securely          | C1   | Correctness of failure modes          |
 | P9 Secret Hygiene         | C6, C7 | Composability of secrets; observability |
 | P10 Surface Minimization  | C3, C8 | Simplicity; economy of code          |
 ## Data
 | Data Principle            | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Truth                  | C1   | Schema must match domain              |
 | P2 Normalization          | C1, C3 | Correctness without duplication; simplicity |
 | P3 Invariants in Schema   | C1   | Correctness enforced                  |
 | P4 Migration Safety       | C5   | Reversibility of changes              |
 | P5 Indexing with Intent   | C7   | Observability of query patterns       |
 | P6 Naming Consistency     | C2   | Direct derivation                     |
 | P7 Type Fidelity          | C1, C2 | Correctness; clarity                 |
 | P8 Lifecycle Awareness    | C1   | Correctness includes lifecycle        |
 | P9 Referential Integrity  | C1   | Correctness of relationships          |
 | P10 Performance Awareness | C1   | Correctness includes cost             |
 ## Testing
 | Testing Principle         | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Tests as Specification | C2   | Tests document intent                 |
 | P2 Independence           | C4   | Locality of test execution            |
 | P3 Determinism            | C1   | Correctness is reproducible           |
 | P4 Fast Feedback          | C3, C8 | Simplicity; economy of time         |
 | P5 Coverage of Behavior   | C1   | Correctness of behavior               |
 | P6 Failure Specificity    | C7   | Observability of failures             |
 | P7 Realism                | C1   | Correctness in real conditions        |
 | P8 Maintainability        | C3, C8 | Simplicity; economy of maintenance   |
 | P9 Edge Case Coverage     | C1   | Correctness at boundaries             |
 | P10 No Test Theater       | C1, C8 | Correctness; economy of test code    |
 ## Performance
 | Perf Principle            | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Measure First          | C7   | Observability precedes optimization   |
 | P2 Critical Path Focus    | C3   | Simplicity of scope                   |
 | P3 Complexity Awareness   | C1   | Correctness includes cost             |
 | P4 Resource Bounds        | C1, C8 | Correctness; economy of resources   |
 | P5 Caching with Intent    | C3, C6 | Simplicity; composability           |
 | P6 Lazy by Default        | C8   | Economy of computation                |
 | P7 Async When Independent | C3   | Simplicity of flow                    |
 | P8 Budget Discipline      | C8   | Economy of resources                  |
 | P9 Perceived Performance  | C1   | Correctness from user's view          |
 | P10 Regression Prevention | C7   | Observability of regressions          |
 ## Observability
 | Obs Principle             | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Structured by Default  | C2, C7 | Clarity; observability              |
 | P2 Correlation            | C7   | Direct derivation                     |
 | P3 Sufficient Context     | C7, C2 | Observability; clarity              |
 | P4 Cardinality Discipline | C8   | Economy of storage/cost              |
 | P5 Sampling with Intent   | C8   | Economy of observability budget       |
 | P6 No Secrets in Obs      | C1, C6 | Correctness; composability          |
 | P7 Actionable Alerts      | C7, C8 | Observability; economy of attention |
 | P8 SLI/SLO Awareness      | C1   | Correctness defined                   |
 | P9 Cost Awareness         | C8   | Direct derivation                     |
 | P10 Debuggability         | C2, C7 | Clarity; observability              |
 ## Errors
 | Error Principle           | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Errors are Data        | C2, C7 | Clarity; observability              |
 | P2 Fail Loudly            | C7   | Direct derivation                     |
 | P3 Fail Specifically       | C2, C7 | Clarity; observability              |
 | P4 Preserve Context       | C7   | Direct derivation                     |
 | P5 Recoverable When Possible | C1, C5 | Correctness; reversibility        |
 | P6 Unrecoverable Means Stop | C1  | Correctness of failure mode           |
 | P7 Errors are Boundaries  | C6   | Composability                         |
 | P8 User-Facing Errors are UX | C2 | Clarity for users                     |
 | P9 Errors are Logged      | C7   | Direct derivation                     |
 | P10 Errors Don't Lie      | C1, C2 | Correctness; clarity                |
 ## Documentation
 | Doc Principle             | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Documentation is Code  | C3, C8 | Simplicity; economy of process      |
 | P2 Audience Awareness     | C2   | Direct derivation                     |
 | P3 Examples are Mandatory | C2   | Direct derivation                     |
 | P4 Currency                | C1   | Correctness of docs                   |
 | P5 Discoverability        | C2   | Direct derivation                     |
 | P6 Conciseness            | C3, C2 | Simplicity; clarity                 |
 | P7 Structure              | C2   | Direct derivation                     |
 | P8 Why Over What          | C2   | Direct derivation                     |
 | P9 Living Documents       | C1, C5 | Correctness; reversibility          |
 | P10 Public by Default     | C6   | Composability                         |
 ## Concurrency
 | Concurrency Principle     | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Immutability by Default | C1, C3 | Correctness; simplicity            |
 | P2 Single Responsibility  | C3, C6 | Simplicity; composability          |
 | P3 Boundaries are Locks   | C4, C6 | Locality; composability            |
 | P4 Determinism Over Speed | C1   | Correctness precedes performance     |
 | P5 Lock Minimization      | C3   | Simplicity                            |
 | P6 No Silent Races        | C7   | Observability of races               |
 | P7 Cancellation Support   | C5   | Reversibility of work                 |
 | P8 Timeout Discipline     | C1   | Correctness of blocking              |
 | P9 Bounded Queues         | C1, C8 | Correctness; economy of memory     |
 | P10 Test for Races        | C1   | Correctness verification             |
 ## DevOps
 | DevOps Principle          | Core | Why                                   |
 |---------------------------|------|---------------------------------------|
 | P1 Reproducibility        | C1   | Correctness of environments          |
 | P2 Automation             | C3, C8 | Simplicity; economy of effort      |
 | P3 Observability          | C7   | Direct derivation                     |
 | P4 Rollback First         | C5   | Direct derivation                     |
 | P5 Progressive Delivery   | C5, C1 | Reversibility; correctness gradually |
 | P6 Configuration as Code  | C1, C3 | Correctness; simplicity            |
 | P7 Immutability           | C1   | Correctness of deploys               |
 | P8 Security at Every Layer | C1  | Correctness includes security        |
 | P9 Documentation in Pipeline | C2 | Clarity of operations                |
 | P10 Failure as Expected   | C1, C7 | Correctness; observability          |
Author	SHA1	Message	Date
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