Compare commits
7 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jon Chery
|
c91f3e754a | ||
|
Jon Chery
|
ebcae21630 | ||
|
Jon Chery
|
530ce3efed | ||
|
Jon Chery
|
2c15282ad4 | ||
|
Jon Chery
|
ae1a33028f | ||
|
Jon Chery
|
ce29a2a213 | ||
|
Jon Chery
|
b8c89f1a74 |
@@ -1,9 +1,8 @@
|
||||
{
|
||||
"phase": 7,
|
||||
"phase": 0,
|
||||
"stage": "complete",
|
||||
"milestone": "v0.1",
|
||||
"phase_role": "final",
|
||||
"phase_role": "pre_execution",
|
||||
"attempts": 0,
|
||||
"updated_at": "2026-08-05T00:05:00Z",
|
||||
"milestone_complete": true
|
||||
"updated_at": "2026-08-05T00:04:00Z"
|
||||
}
|
||||
@@ -7,38 +7,38 @@
|
||||
| ATELIER-01 | `.ciagent/atelier/` governance files created | P0 | 0 | covered |
|
||||
| ATELIER-02 | Milestone v0.1 branch hierarchy established | P0 | 0 | covered |
|
||||
| ATELIER-03 | Initial framework content committed (MANIFEST, matrix, 11 domain first-principles, uiux components+a11y) | P0 | 0 | covered |
|
||||
| ATELIER-04 | `core/first-principles.md` — 8 core principles (C1–C8) | P0 | 1 | covered |
|
||||
| ATELIER-05 | `core/conflict-resolution.md` — cross-document conflict rules | P0 | 1 | covered |
|
||||
| ATELIER-06 | `core/reading-order.md` — recommended consumption order | P0 | 1 | covered |
|
||||
| ATELIER-07 | `README.md` — repo entry point, quickstart | P0 | 1 | covered |
|
||||
| ATELIER-08 | `LICENSE` — MIT license | P0 | 1 | covered |
|
||||
| ATELIER-09 | `domains/uiux/first-principles.md` — 10 UI/UX principles | P0 | 2 | covered |
|
||||
| ATELIER-10 | `domains/errors/first-principles.md` — 10 error principles | P1 | 2 | covered |
|
||||
| ATELIER-11 | `domains/documentation/first-principles.md` | P1 | 2 | covered |
|
||||
| ATELIER-12 | `domains/concurrency/first-principles.md` | P1 | 2 | covered |
|
||||
| ATELIER-13 | `domains/devops/first-principles.md` | P1 | 2 | covered |
|
||||
| ATELIER-14 | `domains/api/` derived: rest, graphql, versioning, error-responses, pagination | P1 | 3 | covered |
|
||||
| ATELIER-15 | `domains/security/` derived: authentication, authorization, input-validation, secrets, supply-chain | P1 | 3 | covered |
|
||||
| ATELIER-16 | `domains/data/` derived: schema-design, migrations, indexing | P1 | 3 | covered |
|
||||
| ATELIER-17 | `domains/testing/` derived: pyramid, fixtures | P1 | 3 | covered |
|
||||
| ATELIER-18 | `domains/performance/` derived: frontend, backend | P1 | 3 | covered |
|
||||
| ATELIER-19 | `domains/observability/` derived: logging, metrics, tracing | P1 | 3 | covered |
|
||||
| ATELIER-20 | `domains/uiux/` derived: tokens, copywriting | P2 | 3 | covered |
|
||||
| ATELIER-21 | `matrix/principles-matrix.md` — full domain → core mapping | P0 | 4 | covered |
|
||||
| ATELIER-22 | `matrix/domain-coverage.md` | P1 | 4 | covered |
|
||||
| ATELIER-23 | `review/agent-checklist.md` | P0 | 4 | covered |
|
||||
| ATELIER-24 | `review/peer-review-checklist.md` | P1 | 4 | covered |
|
||||
| ATELIER-25 | `review/anti-patterns.md` | P1 | 4 | covered |
|
||||
| ATELIER-26 | `examples/good/api-endpoint.md` | P2 | 5 | covered |
|
||||
| ATELIER-27 | `examples/good/react-component.md` | P2 | 5 | covered |
|
||||
| ATELIER-28 | `examples/good/db-schema.md` | P2 | 5 | covered |
|
||||
| ATELIER-29 | `examples/good/error-handler.md` | P2 | 5 | covered |
|
||||
| ATELIER-30 | `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md` | P2 | 5 | covered |
|
||||
| ATELIER-31 | `languages/typescript.md`, `python.md`, `go.md`, `rust.md` | P2 | 6 | covered |
|
||||
| ATELIER-32 | `CHANGELOG.md` | P1 | 6 | covered |
|
||||
| ATELIER-33 | `CONTRIBUTING.md` | P1 | 6 | covered |
|
||||
| ATELIER-34 | Final review passes (all phases reviewed, audit clean) | P0 | 7 | covered |
|
||||
| ATELIER-35 | Milestone v0.1 released (tag v0.0.7, merged to main) | P0 | 7 | covered |
|
||||
| ATELIER-04 | `core/first-principles.md` — 8 core principles (C1–C8) | P0 | 1 | pending |
|
||||
| ATELIER-05 | `core/conflict-resolution.md` — cross-document conflict rules | P0 | 1 | pending |
|
||||
| ATELIER-06 | `core/reading-order.md` — recommended consumption order | P0 | 1 | pending |
|
||||
| ATELIER-07 | `README.md` — repo entry point, quickstart | P0 | 1 | pending |
|
||||
| ATELIER-08 | `LICENSE` — MIT license | P0 | 1 | pending |
|
||||
| ATELIER-09 | `domains/uiux/first-principles.md` — 10 UI/UX principles | P0 | 2 | pending |
|
||||
| ATELIER-10 | `domains/errors/first-principles.md` — 10 error principles | P1 | 2 | pending |
|
||||
| ATELIER-11 | `domains/documentation/first-principles.md` | P1 | 2 | pending |
|
||||
| ATELIER-12 | `domains/concurrency/first-principles.md` | P1 | 2 | pending |
|
||||
| ATELIER-13 | `domains/devops/first-principles.md` | P1 | 2 | pending |
|
||||
| ATELIER-14 | `domains/api/` derived: rest, graphql, versioning, error-responses, pagination | P1 | 3 | pending |
|
||||
| ATELIER-15 | `domains/security/` derived: authentication, authorization, input-validation, secrets, supply-chain | P1 | 3 | pending |
|
||||
| ATELIER-16 | `domains/data/` derived: schema-design, migrations, indexing | P1 | 3 | pending |
|
||||
| ATELIER-17 | `domains/testing/` derived: pyramid, fixtures | P1 | 3 | pending |
|
||||
| ATELIER-18 | `domains/performance/` derived: frontend, backend | P1 | 3 | pending |
|
||||
| ATELIER-19 | `domains/observability/` derived: logging, metrics, tracing | P1 | 3 | pending |
|
||||
| ATELIER-20 | `domains/uiux/` derived: tokens, copywriting | P2 | 3 | pending |
|
||||
| ATELIER-21 | `matrix/principles-matrix.md` — full domain → core mapping | P0 | 4 | pending |
|
||||
| ATELIER-22 | `matrix/domain-coverage.md` | P1 | 4 | pending |
|
||||
| ATELIER-23 | `review/agent-checklist.md` | P0 | 4 | pending |
|
||||
| ATELIER-24 | `review/peer-review-checklist.md` | P1 | 4 | pending |
|
||||
| ATELIER-25 | `review/anti-patterns.md` | P1 | 4 | pending |
|
||||
| ATELIER-26 | `examples/good/api-endpoint.md` | P2 | 5 | pending |
|
||||
| ATELIER-27 | `examples/good/react-component.md` | P2 | 5 | pending |
|
||||
| ATELIER-28 | `examples/good/db-schema.md` | P2 | 5 | pending |
|
||||
| ATELIER-29 | `examples/good/error-handler.md` | P2 | 5 | pending |
|
||||
| ATELIER-30 | `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md` | P2 | 5 | pending |
|
||||
| ATELIER-31 | `languages/typescript.md`, `python.md`, `go.md`, `rust.md` | P2 | 6 | pending |
|
||||
| ATELIER-32 | `CHANGELOG.md` | P1 | 6 | pending |
|
||||
| ATELIER-33 | `CONTRIBUTING.md` | P1 | 6 | pending |
|
||||
| ATELIER-34 | Final review passes (all phases reviewed, audit clean) | P0 | 7 | pending |
|
||||
| ATELIER-35 | Milestone v0.1 released (tag v0.0.7, merged to main) | P0 | 7 | pending |
|
||||
|
||||
## Traceability Matrix
|
||||
|
||||
@@ -51,8 +51,4 @@
|
||||
| 4 (Matrix + Review) | ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25 |
|
||||
| 5 (Examples) | ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30 |
|
||||
| 6 (Languages + Meta) | ATELIER-31, ATELIER-32, ATELIER-33 |
|
||||
| 7 (Final Review + Ship) | ATELIER-34, ATELIER-35 |
|
||||
|
||||
## Milestone Summary
|
||||
|
||||
All 35 requirements covered. 8 core principles, 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. NFR milestone, 7 patches (v0.0.0–v0.0.7), v0.0.7 is the v0.1.0 release.
|
||||
| 7 (Final Review + Ship) | ATELIER-34, ATELIER-35 |
|
||||
@@ -1,69 +0,0 @@
|
||||
# Atelier — Final Review + Audit (P7)
|
||||
|
||||
> Final phase review and audit for milestone v0.1. Conducted before milestone ship.
|
||||
|
||||
## Review (Multi-Persona, across all phases)
|
||||
|
||||
### Structural Review
|
||||
- **All 64 MANIFEST-listed documents exist:** ✓
|
||||
- 3 core, 11 domain first-principles, 27 derived, 2 matrix, 3 review, 4 good examples, 3 bad examples, 4 languages, 5 meta (README, LICENSE, CHANGELOG, CONTRIBUTING, MANIFEST)
|
||||
- **No unlisted docs:** the framework tree contains only docs in the manifest (plus `.ciagent/` governance, which is meta, not framework content).
|
||||
|
||||
### Behavioral Review
|
||||
- **Every domain has exactly 10 P-rules** (verified per domain: api 10, security 10, data 10, testing 10, performance 10, observability 10, errors 10, documentation 10, concurrency 10, devops 10, uiux 10).
|
||||
- **Matrix has exactly 110 rows** (11 domains × 10 principles).
|
||||
- **Every matrix row maps to a C-rule** that exists in `core/first-principles.md` (C1–C8 all present).
|
||||
- **Every example cites principles** (good: 10–18 citations; bad: 7–11 citations).
|
||||
|
||||
### Security Review
|
||||
- **No secret in git history:** the GITEA_API_TOKEN value does not appear in any committed file or commit message. `.ciagent/.env.secrets` is gitignored and never staged.
|
||||
- **No security anti-patterns in framework content:** the `review/anti-patterns.md` catalog is complete; examples/bad/* cite the security principles they violate.
|
||||
|
||||
### Quality Review
|
||||
- **Document structure consistent:** all first-principles docs follow the template (Manifesto → Principles → Conflict Resolution → What Violates → Relationship to Core).
|
||||
- **Reading order links resolve:** `core/reading-order.md` forward references to P2–P6 docs now resolve (all created).
|
||||
- **CHANGELOG follows Keep a Changelog format:** Added section, phases enumerated.
|
||||
|
||||
### P1+ Issues Found (post-hoc, not blocking)
|
||||
1. **Squash-merge commits lack `---ci---` blocks:** the 7 `docs(P0N): complete ...` commits (consolidation points) and the initial `chore: initialize` commit do not have `---ci---` blocks. The task commits on phase branches all have them. Per commit-discipline, consolidation commits could include a `---ci---` block. This is a P1 (post-hoc) issue, not blocking. The milestone ship commit below includes a comprehensive `---ci---` block covering the milestone.
|
||||
|
||||
**P0 fixes applied:** none required. No blocking issues found.
|
||||
|
||||
## Audit
|
||||
|
||||
### Reconstruction Test
|
||||
- **MANIFEST.md lists all framework documents:** ✓ (64 docs)
|
||||
- **Every listed document exists:** ✓
|
||||
- **Git log reconstructs project state:** the `---ci---` blocks in task commits record phase, milestone, status, and requirements covered. The git log + `.ciagent/` files reconstruct the full project state.
|
||||
|
||||
### Branch Hygiene
|
||||
- **Before ship:** `main`, `milestone/v0.1-atelier`, 7 phase branches (00–06), `phase/07-final-review-ship` (current).
|
||||
- **After ship:** all phase branches deleted; `main` + `milestone/v0.1-atelier` remain briefly, then milestone branch deleted after merge to main. Tags preserve all history.
|
||||
|
||||
### Commit Discipline
|
||||
- **Task commits** (on phase branches): all have `---ci---` blocks with project, phase, milestone, status, requirements. ✓
|
||||
- **Squash-merge commits** (on milestone branch): consolidation commits without `---ci---` blocks. P1 (post-hoc).
|
||||
- **Init commit**: has full `---ci---` block. ✓
|
||||
|
||||
### File Discipline
|
||||
- `.ciagent/` holds only governance files (config, PROJECT, ROADMAP, REQUIREMENTS, ARCHITECTURE, PERSONAS, PLAN, RESEARCH, CLARIFY, AUDIT-P2, CHECKPOINT). ✓
|
||||
- Framework content is in the repo root (`core/`, `domains/`, etc.). ✓
|
||||
- `.env.secrets` is gitignored, never committed. ✓
|
||||
|
||||
## Milestone Ship Checklist
|
||||
|
||||
- [x] All execution phases (P1–P6) shipped (v0.0.1–v0.0.6)
|
||||
- [x] Review passed (structural, behavioral, security, quality)
|
||||
- [x] Audit clean (reconstruction, branch hygiene, file discipline)
|
||||
- [x] REQUIREMENTS.md updated (all 35 requirements covered)
|
||||
- [x] ROADMAP.md updated (milestone complete)
|
||||
- [ ] Merge `phase/07` → `milestone/v0.1-atelier`
|
||||
- [ ] Merge `milestone/v0.1-atelier` → `main`
|
||||
- [ ] Tag `v0.0.7` (IS the v0.1 milestone release)
|
||||
- [ ] Create Gitea release for v0.0.7
|
||||
- [ ] Delete all phase branches + milestone branch
|
||||
- [ ] Clear checkpoint (milestone complete)
|
||||
|
||||
## Conclusion
|
||||
|
||||
The milestone v0.1 is complete and ready to ship. 35/35 requirements covered. 8 core principles, 11 domains, 110 domain principles, all traced via the matrix. The framework is internally consistent and ready for consumption.
|
||||
+18
-18
@@ -1,6 +1,6 @@
|
||||
# Atelier — Roadmap
|
||||
|
||||
## Milestone: v0.1 — Initial Framework (COMPLETE)
|
||||
## Milestone: v0.1 — Initial Framework
|
||||
|
||||
**Milestone type:** NFR (all phases produce docs/chore commits — no `feat` code)
|
||||
**Tag line:** v0.0.x (previous minor from v0.1)
|
||||
@@ -8,14 +8,14 @@
|
||||
|
||||
| Phase | Name | Type | Status | Key Deliverables |
|
||||
|-------|------|------|--------|------------------|
|
||||
| 0 | Pre-Execution | docs | complete | Spec, clarify, research, plan, PERSONAS.md |
|
||||
| 1 | Core Foundation | docs | complete | core/first-principles.md, core/conflict-resolution.md, core/reading-order.md, README.md, LICENSE |
|
||||
| 2 | Domain First Principles | docs | complete | uiux/first-principles.md, domain audit |
|
||||
| 3 | Domain Derived Docs | docs | complete | 27 derived docs across 11 domains |
|
||||
| 4 | Matrix + Review | docs | complete | matrix/domain-coverage.md, review/{agent,peer-review,anti-patterns}.md |
|
||||
| 5 | Examples | docs | complete | 4 good + 3 bad examples |
|
||||
| 6 | Languages + Meta | docs | complete | 4 language docs, CHANGELOG, CONTRIBUTING |
|
||||
| 7 | Final Review + Ship | docs | complete | Review passed, audit clean, milestone merged to main, tag v0.0.7 |
|
||||
| 0 | Pre-Execution | docs | in_progress | Spec, clarify, research, plan, PERSONAS.md |
|
||||
| 1 | Core Foundation | docs | pending | core/first-principles.md, core/conflict-resolution.md, core/reading-order.md, README.md, LICENSE |
|
||||
| 2 | Domain First Principles (remaining) | docs | pending | uiux/first-principles.md, errors/, documentation/, concurrency/, devops first-principles |
|
||||
| 3 | Domain Derived Docs | docs | pending | api/*, security/*, data/*, testing/*, performance/*, observability/* derived docs |
|
||||
| 4 | Matrix + Review | docs | pending | matrix/principles-matrix.md, matrix/domain-coverage.md, review/agent-checklist.md, review/peer-review-checklist.md, review/anti-patterns.md |
|
||||
| 5 | Examples | docs | pending | examples/good/*, examples/bad/* |
|
||||
| 6 | Languages + Meta | docs | pending | languages/*.md, CHANGELOG.md, CONTRIBUTING.md |
|
||||
| 7 | Final Review + Ship | docs | pending | Review, audit, milestone merge to main, tag v0.0.7, release |
|
||||
|
||||
## Phase Tag Mapping
|
||||
|
||||
@@ -36,15 +36,15 @@ NFR milestone: no separate minor tag. The final patch (v0.0.7) IS the v0.1 deliv
|
||||
|
||||
## Next
|
||||
|
||||
- Milestone v0.1 complete. All phases shipped.
|
||||
- Future: v0.2 could add `domains/ai-ml/`, `domains/i18n/`, `domains/compliance/` per spec Part 6 next-steps.
|
||||
- Phase 0: complete specify → clarify → research → plan → grill → ship
|
||||
- Phase 1: write core foundation documents
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] All 11 domains have first-principles.md
|
||||
- [x] Every domain P-rule traced to a core C-rule in matrix/principles-matrix.md
|
||||
- [x] MANIFEST.md lists all framework documents
|
||||
- [x] review/agent-checklist.md covers all core principles
|
||||
- [x] examples/ includes at least 4 good + 3 bad worked examples
|
||||
- [x] README.md provides quickstart for agents and humans
|
||||
- [x] Milestone v0.1 tagged and released
|
||||
- [ ] All 11 domains have first-principles.md
|
||||
- [ ] Every domain P-rule traced to a core C-rule in matrix/principles-matrix.md
|
||||
- [ ] MANIFEST.md lists all framework documents
|
||||
- [ ] review/agent-checklist.md covers all core principles
|
||||
- [ ] examples/ includes at least 4 good + 3 bad worked examples
|
||||
- [ ] README.md provides quickstart for agents and humans
|
||||
- [ ] Milestone v0.1 tagged and released
|
||||
@@ -1,45 +0,0 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the Atelier framework are documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [0.1.0] — 2026-08-05
|
||||
|
||||
### Added
|
||||
- Eight core principles (C1–C8) in `core/first-principles.md` with definitions, precedence, and violation tables.
|
||||
- Formal conflict resolution procedure in `core/conflict-resolution.md` (hierarchy, precedence, worked examples, non-tradeable declarations).
|
||||
- Canonical reading order in `core/reading-order.md` with paths for agents, humans, conflict resolution, and review.
|
||||
- README with quickstart for AI agents and humans.
|
||||
- MIT license.
|
||||
- Eleven domain first-principles (P1–P10 each): UI/UX, API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps.
|
||||
- Twenty-seven domain derived/topic docs (REST, GraphQL, versioning, error-responses, pagination, authentication, authorization, input-validation, secrets, supply-chain, schema-design, migrations, indexing, pyramid, fixtures, frontend, backend, logging, metrics, tracing, tokens, copywriting, patterns, doc-templates, patterns, ci-cd, environments).
|
||||
- `matrix/principles-matrix.md` — full mapping of all 110 domain principles to core derivations.
|
||||
- `matrix/domain-coverage.md` — inverse mapping of core principles to domains.
|
||||
- `review/agent-checklist.md` — pre-completion gate for AI agents.
|
||||
- `review/peer-review-checklist.md` — human review checklist.
|
||||
- `review/anti-patterns.md` — catalog of violations with principle citations.
|
||||
- Four good worked examples: `examples/good/api-endpoint.md`, `react-component.md`, `db-schema.md`, `error-handler.md`.
|
||||
- Three bad worked examples: `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md`.
|
||||
- Four language application docs: `languages/typescript.md`, `python.md`, `go.md`, `rust.md`.
|
||||
- `MANIFEST.md` — authoritative document index.
|
||||
- `CONTRIBUTING.md` — contribution guide.
|
||||
|
||||
### Framework Properties
|
||||
- 8 core principles, 11 domains, 110 domain principles, all traced via the matrix.
|
||||
- NFR milestone type (documentation only, no runtime code).
|
||||
- Tags: v0.0.0 (pre-execution) through v0.0.7 (final review + ship).
|
||||
- The v0.0.7 patch release IS the v0.1.0 milestone deliverable.
|
||||
|
||||
### Phases
|
||||
- Phase 0 (v0.0.0): pre-execution — specify, clarify, research, plan, ship.
|
||||
- Phase 1 (v0.0.1): core foundation — first-principles, conflict-resolution, reading-order, README, LICENSE.
|
||||
- Phase 2 (v0.0.2): domain first-principles — uiux first-principles + audit.
|
||||
- Phase 3 (v0.0.3): domain derived docs — 27 topic files.
|
||||
- Phase 4 (v0.0.4): matrix + review — domain-coverage, agent-checklist, peer-review-checklist, anti-patterns.
|
||||
- Phase 5 (v0.0.5): examples — 4 good + 3 bad.
|
||||
- Phase 6 (v0.0.6): languages + meta — typescript, python, go, rust, CHANGELOG, CONTRIBUTING.
|
||||
- Phase 7 (v0.0.7): final review + ship — milestone release.
|
||||
@@ -1,71 +0,0 @@
|
||||
# Contributing to Atelier
|
||||
|
||||
Thank you for considering a contribution to Atelier. This framework lives by its principles; contributions are expected to follow them.
|
||||
|
||||
## What We Accept
|
||||
|
||||
- **New domain first-principles** — if a domain is missing (e.g., `domains/ai-ml/`), propose it with 10 principles (P1–P10), each traced to a core principle (C1–C8) in `matrix/principles-matrix.md`.
|
||||
- **New domain derived docs** — topic docs under an existing domain (e.g., `domains/api/webhooks.md`), deriving from the domain's first-principles.
|
||||
- **New language application docs** — `languages/<lang>.md` showing how domain principles apply in a specific language.
|
||||
- **New examples** — `examples/good/*` (with principle citations) or `examples/bad/*` (with violation citations).
|
||||
- **Corrections** — to existing principles, derivations, or examples. A correction to a core principle is a major version change; treat with care.
|
||||
- **Improvements to the matrix** — if a derivation is missing or wrong, propose the fix with the rationale.
|
||||
|
||||
## What We Do Not Accept
|
||||
|
||||
- **Style rules** — Atelier is principles, not style. Use a linter for style.
|
||||
- **Tooling** — linters, analyzers, or enforcement code. Atelier is markdown.
|
||||
- **Unlisted docs** — every document must be in `MANIFEST.md`. An unlisted doc is not part of the framework.
|
||||
- **Principles without derivation** — a domain principle that does not trace to a core principle is orphaned and will be rejected.
|
||||
|
||||
## How to Contribute
|
||||
|
||||
### 1. Read the relevant docs first
|
||||
- `core/first-principles.md` — the eight axioms.
|
||||
- `core/conflict-resolution.md` — how conflicts are resolved.
|
||||
- The domain(s) you are contributing to.
|
||||
- `matrix/principles-matrix.md` — to see existing derivations.
|
||||
|
||||
### 2. Follow the document structure
|
||||
See `domains/documentation/doc-templates.md` for the canonical structure. Every first-principles doc has:
|
||||
- Manifesto
|
||||
- The Principles (P1–P10, named, defined, with "what violates it")
|
||||
- Conflict Resolution
|
||||
- What Violates These Principles (table)
|
||||
- Relationship to Core
|
||||
|
||||
### 3. Update the matrix
|
||||
If you add or change a principle, update `matrix/principles-matrix.md` with the derivation. A PR with a new principle but no matrix row is incomplete.
|
||||
|
||||
### 4. Update the manifest
|
||||
If you add a new document, add it to `MANIFEST.md` in the correct section. An unlisted document is not part of the framework.
|
||||
|
||||
### 5. Add examples
|
||||
If you add a principle, add at least one good example and one bad example in `examples/`. Examples are mandatory (Documentation P3).
|
||||
|
||||
### 6. Write a clear PR description
|
||||
- What principle or document you are adding/changing.
|
||||
- Why (the rationale, not just the what — Documentation P8 Why Over What).
|
||||
- Which core principle(s) it derives from.
|
||||
- What conflicts it might introduce (if any).
|
||||
|
||||
## Review Criteria
|
||||
|
||||
Reviewers will check (see `review/peer-review-checklist.md`):
|
||||
- Does the new principle trace to a core principle?
|
||||
- Is the matrix updated?
|
||||
- Is the manifest updated?
|
||||
- Are there examples?
|
||||
- Does the structure follow the template?
|
||||
- Does it conflict with existing principles? If so, is the conflict resolvable per `core/conflict-resolution.md`?
|
||||
|
||||
## Versioning
|
||||
|
||||
- A new domain or language doc is a minor version (e.g., v0.1 → v0.2).
|
||||
- A new topic doc or example is a patch version (e.g., v0.1.0 → v0.1.1).
|
||||
- A change to `core/first-principles.md` (adding, removing, or reordering a core principle) is a major version (e.g., v0.x → v1.0).
|
||||
- See `CHANGELOG.md` for the version history.
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions are licensed under the MIT license (see `LICENSE`).
|
||||
@@ -1,82 +0,0 @@
|
||||
# Go — Language Application
|
||||
|
||||
> How Atelier's domain principles apply in Go specifically. Derives from `domains/` docs.
|
||||
|
||||
## Type System (C1 Correctness, Data P7 Type Fidelity)
|
||||
|
||||
- **Named types for domain concepts:** `type UserId string`, not bare `string`.
|
||||
- **No `interface{}`/`any` without justification:** Go 1.18+ generics reduce the need.
|
||||
- **`any` requires a type assertion or switch:** never use the value without narrowing.
|
||||
|
||||
```go
|
||||
type UserId string
|
||||
type OrderId string
|
||||
// UserId and OrderId are distinct; cannot be mixed
|
||||
func GetUser(id UserId) (*User, error) { ... }
|
||||
```
|
||||
|
||||
## Error Handling (Errors P1 Errors are Data)
|
||||
|
||||
- **Errors are values:** `error` is an interface, not an exception. Handle explicitly.
|
||||
- **Sentinel errors with `errors.Is`:**
|
||||
```go
|
||||
var ErrNotFound = errors.New("not found")
|
||||
if errors.Is(err, ErrNotFound) { ... }
|
||||
```
|
||||
- **Wrap with context:** `fmt.Errorf("get user %d: %w", id, err)`.
|
||||
- **Never `_ = err`:** swallowed error (Errors P2). Handle or return.
|
||||
- **Custom error types with `errors.As`:**
|
||||
```go
|
||||
type ValidationError struct {
|
||||
Field string
|
||||
Msg string
|
||||
}
|
||||
func (e *ValidationError) Error() string { return e.Field + ": " + e.Msg }
|
||||
```
|
||||
|
||||
## Concurrency (Concurrency — Go's strength)
|
||||
|
||||
- **Goroutines + channels** for message passing (P5 Lock Minimization).
|
||||
- **`context.Context` for cancellation and timeout:** every function that does I/O takes a `ctx`.
|
||||
- **`sync.Mutex` scoped minimally:** not held across I/O (P3 Lock Scope).
|
||||
- **Bounded channels:** `make(chan T, N)`, not unbounded (P9 Bounded Queues).
|
||||
|
||||
```go
|
||||
func fetchWithTimeout(ctx context.Context, url string) (*Response, error) {
|
||||
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
|
||||
defer cancel()
|
||||
return doFetch(ctx, url)
|
||||
}
|
||||
```
|
||||
|
||||
## Immutability (Concurrency P1)
|
||||
|
||||
- **Pass by value for small structs; pass by pointer for large or mutable.**
|
||||
- **No mutation of method receivers:** use a value receiver, not a pointer receiver, for read-only methods.
|
||||
- **Copy-on-write for shared state:** return a new struct, not a mutated one.
|
||||
|
||||
## Nullability (C1)
|
||||
|
||||
- **Pointers can be nil; values cannot.** Be explicit: `*User` (nullable) vs `User` (not).
|
||||
- **`nil` check before deref:** a nil deref is a panic.
|
||||
- **Return `(T, error)`, not `(*T, nil)`:** avoid the "nil pointer" trap.
|
||||
|
||||
## Testing (Testing)
|
||||
|
||||
- **`testing` package + `testify/assert`** or stdlib only.
|
||||
- **Table-driven tests:** `[]struct{ name string; input X; want Y }`.
|
||||
- **`t.Parallel()`** for independent tests (P2 Independence).
|
||||
- **`httptest` for HTTP handlers; `sqlite` or testcontainers for DB.**
|
||||
|
||||
## Observability (Observability P1)
|
||||
|
||||
- **`slog` (stdlib, Go 1.21+) or `zap`/`zerolog`:** structured logs.
|
||||
- **`context.Context` carries `trace_id`:** propagated via middleware.
|
||||
- **No `fmt.Println`:** use the logger.
|
||||
|
||||
## Tooling (DevOps P2)
|
||||
|
||||
- **`go vet` + `golangci-lint`:** lint.
|
||||
- **`gofmt`/`goimports`:** format (automated, not debated).
|
||||
- **`go test -race` in CI:** race detector (Concurrency P6 No Silent Races).
|
||||
- **`go mod tidy` + committed `go.sum`:** reproducible builds.
|
||||
@@ -1,77 +0,0 @@
|
||||
# Python — Language Application
|
||||
|
||||
> How Atelier's domain principles apply in Python specifically. Derives from `domains/` docs.
|
||||
|
||||
## Type System (C1 Correctness, Data P7 Type Fidelity)
|
||||
|
||||
- **Type hints on every function:** `def get_user(id: UUID) -> User | None:`.
|
||||
- **`mypy --strict` or `pyright` in CI:** type check is not optional.
|
||||
- **No `Any` without justification:** `Any` disables the type checker. Use `object` + narrowing.
|
||||
- **Pydantic for runtime validation:** schemas validate and type at the boundary.
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from uuid import UUID
|
||||
|
||||
class UserCreate(BaseModel):
|
||||
email: str
|
||||
name: str
|
||||
# additionalProperties: false by default (extra='forbid')
|
||||
```
|
||||
|
||||
## Error Handling (Errors P1 Errors are Data)
|
||||
|
||||
- **Exceptions for exceptional cases,** not control flow. `raise` not `return None` for errors.
|
||||
- **Custom exception hierarchy:**
|
||||
```python
|
||||
class AppError(Exception): pass
|
||||
class ValidationError(AppError): pass
|
||||
class NotFoundError(AppError): pass
|
||||
```
|
||||
- **Never bare `except:`:** `except Exception as e:` (catch specific, not everything).
|
||||
- **Never `except: pass`:** log and re-raise or handle, never swallow (Errors P2).
|
||||
|
||||
## Async (Concurrency P7, P8)
|
||||
|
||||
- **`asyncio` for I/O-bound:** `async def`, `await`. Not threads for I/O.
|
||||
- **`anyio` for portability** if you may switch runtimes (trio compatibility).
|
||||
- **Timeout on every `await`:** `asyncio.wait_for(coro, timeout=5)`, not bare `await`.
|
||||
- **Cancellation propagated:** `asyncio.CancelledError` is not caught; it propagates.
|
||||
|
||||
## Immutability (Concurrency P1)
|
||||
|
||||
- **`frozen=True` dataclasses** for value objects:
|
||||
```python
|
||||
from dataclasses import dataclass
|
||||
@dataclass(frozen=True)
|
||||
class UserId:
|
||||
value: str
|
||||
```
|
||||
- **Tuples over lists** for fixed-length, immutable sequences.
|
||||
- **No in-place mutation of shared state:** return new objects.
|
||||
|
||||
## Nullability (C1)
|
||||
|
||||
- **`Optional[T]` is `T | None`:** explicit, must be checked.
|
||||
- **`None` is not "not found":** raise `NotFoundError` or return `Result`, not `None`.
|
||||
- **`assert` is for invariants,** not for runtime checks (stripped with `-O`).
|
||||
|
||||
## Testing (Testing)
|
||||
|
||||
- **pytest** with fixtures (factories, not shared state).
|
||||
- **`pytest --randomly`** to catch order-dependent tests (P2 Independence).
|
||||
- **`freezegun` for time:** no `datetime.now()` in tests; inject the clock.
|
||||
- **`factory_boy` or `pytest-factoryboy`** for realistic factories.
|
||||
|
||||
## Observability (Observability P1)
|
||||
|
||||
- **`structlog` or `python-json-logger`:** JSON logs, not `print`.
|
||||
- **`logging` with structured formatter:** every log has `request_id`, `user_id`, `event`.
|
||||
- **No secrets in logs:** `mask_secret()` helper, or `structlog` processors.
|
||||
|
||||
## Tooling (DevOps P2)
|
||||
|
||||
- **`ruff` for lint + format:** replaces flake8 + black + isort.
|
||||
- **`mypy --strict` in CI:** type check.
|
||||
- **`pip-tools` or `poetry` for lockfile:** pinned dependencies.
|
||||
- **`pip install --no-deps -r requirements.txt`:** reproducible install.
|
||||
@@ -1,79 +0,0 @@
|
||||
# Rust — Language Application
|
||||
|
||||
> How Atelier's domain principles apply in Rust specifically. Derives from `domains/` docs.
|
||||
|
||||
## Type System (C1 Correctness, Data P7 Type Fidelity)
|
||||
|
||||
- **Newtypes for domain concepts:** `struct UserId(String);` — zero-cost, type-safe.
|
||||
- **`enum` for finite domains:** `enum Status { Pending, Paid, Shipped }` — exhaustive.
|
||||
- **No `unsafe` without justification and review:** `unsafe` opts out of the compiler's guarantees.
|
||||
|
||||
```rust
|
||||
struct UserId(String);
|
||||
struct OrderId(String);
|
||||
// Cannot pass OrderId where UserId is expected
|
||||
fn get_user(id: UserId) -> Result<User, Error> { ... }
|
||||
```
|
||||
|
||||
## Error Handling (Errors P1 Errors are Data)
|
||||
|
||||
- **`Result<T, E>` for fallible operations:** errors are values, not exceptions.
|
||||
- **`thiserror` for error enums, `anyhow` for applications:**
|
||||
```rust
|
||||
#[derive(thiserror::Error)]
|
||||
enum AppError {
|
||||
#[error("not found: {0}")]
|
||||
NotFound(String),
|
||||
#[error("validation: {0}")]
|
||||
Validation(String),
|
||||
#[error(transparent)]
|
||||
Io(#[from] std::io::Error),
|
||||
}
|
||||
```
|
||||
- **`?` for propagation, not `unwrap()`:** `unwrap()` panics in production.
|
||||
- **No `panic::catch_unwind` for control flow:** panics are for bugs, not errors.
|
||||
|
||||
## Concurrency (Concurrency — Rust's ownership model)
|
||||
|
||||
- **`Send` and `Sync` traits enforced by the compiler:** data races are compile errors.
|
||||
- **`Arc<T>` for shared, `Mutex<T>`/`RwLock<T>` for mutation:** the lock is explicit.
|
||||
- **`tokio` for async:** `async fn`, `.await`. Bounded channels (`tokio::sync::mpsc::channel(N)`).
|
||||
- **`Drop` for cleanup:** no leaked resources (no `defer` needed; RAII).
|
||||
|
||||
```rust
|
||||
async fn fetch_with_timeout(url: &str) -> Result<Response, Error> {
|
||||
tokio::time::timeout(Duration::from_secs(5), fetch(url)).await??;
|
||||
}
|
||||
```
|
||||
|
||||
## Immutability (Concurrency P1 Immutability by Default)
|
||||
|
||||
- **Variables are immutable by default:** `let x = 5;` not `let mut x = 5;`.
|
||||
- **`&T` (shared ref) over `&mut T` (exclusive ref):** the compiler enforces aliasing rules.
|
||||
- **Interior mutability (`Cell`/`RefCell`) only when needed:** not as a default.
|
||||
|
||||
## Nullability (C1)
|
||||
|
||||
- **`Option<T>`, not nullable pointers:** `Some(x)` / `None`. The compiler enforces handling.
|
||||
- **No `null`:** Rust has no null. `Option::None` is the explicit absence.
|
||||
- **`?` on `Option` for propagation:** `fn get_name(user: User) -> Option<String> { user.profile?.name }`.
|
||||
|
||||
## Testing (Testing)
|
||||
|
||||
- **`#[test]` + `#[cfg(test)] mod tests`:** tests co-located.
|
||||
- **`proptest` or `quickcheck` for property-based tests:** edge case coverage (P9).
|
||||
- **`tokio::test` for async tests.**
|
||||
- **No `SystemTime::now()` in tests:** inject an `Instant` or a mock clock.
|
||||
|
||||
## Observability (Observability P1)
|
||||
|
||||
- **`tracing` crate:** structured logs + spans + traces. Not `println!`.
|
||||
- **`tracing::instrument` on functions:** automatic span context.
|
||||
- **`tracing-subscriber` with JSON format:** structured output for production.
|
||||
|
||||
## Tooling (DevOps P2)
|
||||
|
||||
- **`cargo clippy`:** lint. `cargo clippy -- -D warnings` in CI.
|
||||
- **`cargo fmt`:** format.
|
||||
- **`cargo test`:** tests. `cargo test --release` for perf-sensitive.
|
||||
- **Committed `Cargo.lock`:** reproducible builds (even for libraries, for CI).
|
||||
@@ -1,76 +0,0 @@
|
||||
# TypeScript — Language Application
|
||||
|
||||
> How Atelier's domain principles apply in TypeScript specifically. Derives from `domains/` docs; this file is the language-specific lens.
|
||||
|
||||
## Type System (C1 Correctness, Data P7 Type Fidelity)
|
||||
|
||||
- **Strict mode on:** `strict: true` in `tsconfig.json`. No `any` without justification.
|
||||
- **No `any`, no `unknown` without narrowing:** `any` disables the type checker. `unknown` requires narrowing before use.
|
||||
- **Discriminated unions over enums:** `type Status = { type: 'pending' } | { type: 'paid'; amount: number }` — exhaustive, type-safe.
|
||||
- **Branded types for domain IDs:** `type UserId = string & { __brand: 'UserId' }` — prevents passing a `PostId` where a `UserId` is expected.
|
||||
|
||||
```typescript
|
||||
type UserId = string & { readonly __brand: 'UserId' };
|
||||
function getUser(id: UserId): User { ... }
|
||||
// getUser("abc") // type error
|
||||
// getUser("abc" as UserId) // ok
|
||||
```
|
||||
|
||||
## Error Handling (Errors P1 Errors are Data)
|
||||
|
||||
- **Result type over exceptions for expected failures:**
|
||||
```typescript
|
||||
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
|
||||
```
|
||||
- **Exceptions for programmer errors:** null deref, invariant violation. Not for "user not found."
|
||||
- **Never `any` in catch:** `catch (e: unknown)` then narrow with `instanceof` or a type guard.
|
||||
|
||||
## Async (Concurrency P7 Cancellation Support, P8 Timeout Discipline)
|
||||
|
||||
- **`Promise` with `AbortSignal`:** every async function accepts an optional `AbortSignal` for cancellation.
|
||||
- **`Promise.race` with a timeout:** never `await` without a timeout for external calls.
|
||||
- **No `await` in a hot loop without batching:** use `Promise.all` for parallelism.
|
||||
|
||||
```typescript
|
||||
async function fetchWithTimeout(url: string, signal?: AbortSignal): Promise<Response> {
|
||||
const timeout = new AbortController();
|
||||
signal?.addEventListener('abort', () => timeout.abort());
|
||||
const timer = setTimeout(() => timeout.abort(), 5000);
|
||||
try {
|
||||
return await fetch(url, { signal: timeout.signal });
|
||||
} finally {
|
||||
clearTimeout(timer);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Immutability (Concurrency P1 Immutability by Default)
|
||||
|
||||
- **`readonly` on arrays and objects:** `readonly string[]`, `readonly { id: string }`.
|
||||
- **`as const` for literals:** `const status = 'pending' as const`.
|
||||
- **Immutable update patterns:** `spread` or `Immer` for nested updates, never mutation.
|
||||
|
||||
## Nullability (C1 Correctness)
|
||||
|
||||
- **`strictNullChecks: true`:** `null` and `undefined` are distinct and must be handled.
|
||||
- **No `!` (non-null assertion) without justification:** it disables the null check. Use narrowing.
|
||||
- **`optional chaining` over `&&`:** `user?.profile?.name` not `user && user.profile && user.profile.name`.
|
||||
|
||||
## Testing (Testing)
|
||||
|
||||
- **Jest or Vitest** with `ts-jest`/`vite`. Test files co-located: `user.ts` → `user.test.ts`.
|
||||
- **Factories over fixtures:** `makeUser()` returns a fresh object per test.
|
||||
- **No `Date.now()` in tests:** inject the clock. `jest.useFakeTimers()` or pass a `now` function.
|
||||
|
||||
## Observability (Observability P1 Structured by Default)
|
||||
|
||||
- **Structured logger:** `pino` or `winston` in JSON mode. Not `console.log`.
|
||||
- **`request_id` via middleware:** propagated on every log in the request.
|
||||
- **No secrets in logs:** the logger redacts known secret fields (`pino` redact option).
|
||||
|
||||
## Tooling (DevOps P2 Automation)
|
||||
|
||||
- **ESLint with `@typescript-eslint`** — strict ruleset.
|
||||
- **Prettier** — format, not debated.
|
||||
- **`tsc --noEmit` in CI** — type check without emitting.
|
||||
- **`npm ci`** — lockfile install, not `npm install`.
|
||||
Reference in New Issue
Block a user