diff --git a/.ciagent/CHECKPOINT.json b/.ciagent/CHECKPOINT.json new file mode 100644 index 0000000..e69ab41 --- /dev/null +++ b/.ciagent/CHECKPOINT.json @@ -0,0 +1,8 @@ +{ + "phase": 0, + "stage": "plan", + "milestone": "v0.1", + "phase_role": "pre_execution", + "attempts": 0, + "updated_at": "2026-08-05T00:03:00Z" +} \ No newline at end of file diff --git a/.ciagent/atelier/ARCHITECTURE.md b/.ciagent/atelier/ARCHITECTURE.md new file mode 100644 index 0000000..e0605df --- /dev/null +++ b/.ciagent/atelier/ARCHITECTURE.md @@ -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//first-principles.md` (per task) +4. `domains//.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). \ No newline at end of file diff --git a/.ciagent/atelier/CLARIFY.md b/.ciagent/atelier/CLARIFY.md new file mode 100644 index 0000000..4062fe2 --- /dev/null +++ b/.ciagent/atelier/CLARIFY.md @@ -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//first-principles → domains// → 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). \ No newline at end of file diff --git a/.ciagent/atelier/PERSONAS.md b/.ciagent/atelier/PERSONAS.md new file mode 100644 index 0000000..99cbdf5 --- /dev/null +++ b/.ciagent/atelier/PERSONAS.md @@ -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. \ No newline at end of file diff --git a/.ciagent/atelier/PLAN.md b/.ciagent/atelier/PLAN.md new file mode 100644 index 0000000..12c2af3 --- /dev/null +++ b/.ciagent/atelier/PLAN.md @@ -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 | \ No newline at end of file diff --git a/.ciagent/atelier/PROJECT.md b/.ciagent/atelier/PROJECT.md new file mode 100644 index 0000000..997f42e --- /dev/null +++ b/.ciagent/atelier/PROJECT.md @@ -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. \ No newline at end of file diff --git a/.ciagent/atelier/REQUIREMENTS.md b/.ciagent/atelier/REQUIREMENTS.md new file mode 100644 index 0000000..6e279f3 --- /dev/null +++ b/.ciagent/atelier/REQUIREMENTS.md @@ -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 | \ No newline at end of file diff --git a/.ciagent/atelier/RESEARCH.md b/.ciagent/atelier/RESEARCH.md new file mode 100644 index 0000000..bc936e6 --- /dev/null +++ b/.ciagent/atelier/RESEARCH.md @@ -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). \ No newline at end of file diff --git a/.ciagent/atelier/ROADMAP.md b/.ciagent/atelier/ROADMAP.md new file mode 100644 index 0000000..0247c2e --- /dev/null +++ b/.ciagent/atelier/ROADMAP.md @@ -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 \ No newline at end of file diff --git a/.ciagent/config.json b/.ciagent/config.json new file mode 100644 index 0000000..59c47d2 --- /dev/null +++ b/.ciagent/config.json @@ -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": "coreci", + "repo": "atelier" + }, + "gitea": { + "base_url": "https://git.cloudinit.dev", + "api_token_env": "GITEA_API_TOKEN", + "owner": "coreci", + "repo": "atelier" + }, + "ship": { + "per_phase": true, + "allow_skip": false, + "max_release_retries": 3 + } +} \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..81f088b --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.env +.env.secrets +.env.* \ No newline at end of file diff --git a/MANIFEST.md b/MANIFEST.md new file mode 100644 index 0000000..2702aac --- /dev/null +++ b/MANIFEST.md @@ -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//first-principles.md`— Per task +4. `domains//.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 | \ No newline at end of file diff --git a/domains/api/first-principles.md b/domains/api/first-principles.md new file mode 100644 index 0000000..2bf581c --- /dev/null +++ b/domains/api/first-principles.md @@ -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`. \ No newline at end of file diff --git a/domains/concurrency/first-principles.md b/domains/concurrency/first-principles.md new file mode 100644 index 0000000..f55963d --- /dev/null +++ b/domains/concurrency/first-principles.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. \ No newline at end of file diff --git a/domains/data/first-principles.md b/domains/data/first-principles.md new file mode 100644 index 0000000..82486c5 --- /dev/null +++ b/domains/data/first-principles.md @@ -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. \ No newline at end of file diff --git a/domains/devops/first-principles.md b/domains/devops/first-principles.md new file mode 100644 index 0000000..f860610 --- /dev/null +++ b/domains/devops/first-principles.md @@ -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. \ No newline at end of file diff --git a/domains/documentation/first-principles.md b/domains/documentation/first-principles.md new file mode 100644 index 0000000..0646b79 --- /dev/null +++ b/domains/documentation/first-principles.md @@ -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. \ No newline at end of file diff --git a/domains/errors/first-principles.md b/domains/errors/first-principles.md new file mode 100644 index 0000000..ba64213 --- /dev/null +++ b/domains/errors/first-principles.md @@ -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. \ No newline at end of file diff --git a/domains/observability/first-principles.md b/domains/observability/first-principles.md new file mode 100644 index 0000000..2fe2a14 --- /dev/null +++ b/domains/observability/first-principles.md @@ -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. \ No newline at end of file diff --git a/domains/performance/first-principles.md b/domains/performance/first-principles.md new file mode 100644 index 0000000..4d25042 --- /dev/null +++ b/domains/performance/first-principles.md @@ -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. \ No newline at end of file diff --git a/domains/security/first-principles.md b/domains/security/first-principles.md new file mode 100644 index 0000000..a62c1fd --- /dev/null +++ b/domains/security/first-principles.md @@ -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`. \ No newline at end of file diff --git a/domains/testing/first-principles.md b/domains/testing/first-principles.md new file mode 100644 index 0000000..edec7a2 --- /dev/null +++ b/domains/testing/first-principles.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. \ No newline at end of file diff --git a/domains/uiux/accessibility.md b/domains/uiux/accessibility.md new file mode 100644 index 0000000..379e35d --- /dev/null +++ b/domains/uiux/accessibility.md @@ -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. \ No newline at end of file diff --git a/domains/uiux/components.md b/domains/uiux/components.md new file mode 100644 index 0000000..b09cff4 --- /dev/null +++ b/domains/uiux/components.md @@ -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 ``, ``, 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? \ No newline at end of file diff --git a/matrix/principles-matrix.md b/matrix/principles-matrix.md new file mode 100644 index 0000000..06ab214 --- /dev/null +++ b/matrix/principles-matrix.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 | \ No newline at end of file