Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
# Core — First Principles
|
||
|
||
**Version:** 1.0.0
|
||
**Status:** Foundational
|
||
**Audience:** All agents and humans. Read this first.
|
||
|
||
## 1. Manifesto
|
||
|
||
There are eight principles from which all other principles derive. Every domain rule, every language rule, every review checklist traces back to one or more of these. When two rules conflict, the higher-precedence core principle wins. When a rule has no derivation here, it is orphaned and must be removed or re-derived.
|
||
|
||
These principles are universal. They apply to every language, every domain, every system. They are not opinions; they are the axioms of quality software.
|
||
|
||
## 2. The Principles
|
||
|
||
### C1. Correctness
|
||
The system does what it is supposed to do, and nothing else.
|
||
|
||
- Correctness is the highest principle. No other principle overrides it.
|
||
- A correct system handles the specified cases, the edge cases, and the failure cases — all defined by the domain.
|
||
- Incorrect code that is fast, clear, or simple is still wrong.
|
||
- Security is a subset of correctness: code that is exploitable does not do what it was supposed to do.
|
||
- Correctness includes temporal correctness: a late answer is a wrong answer when the deadline mattered.
|
||
|
||
### C2. Clarity
|
||
The intent of the code is obvious to its reader.
|
||
|
||
- Code is read more than it is written. Optimize for the reader.
|
||
- Names reveal intent. Comments explain why, not what.
|
||
- A stranger should understand the code without reading the documentation. The documentation should make the code unnecessary to read.
|
||
- Clarity serves correctness: unclear code is where bugs hide.
|
||
|
||
### C3. Simplicity
|
||
The solution is as simple as possible, and no simpler.
|
||
|
||
- Complexity is the enemy of correctness. Every line of code is a liability.
|
||
- Simplicity is not laziness. It is the result of removing everything unnecessary.
|
||
- A simple solution handles the requirement completely. A simpler-than-necessary solution does not.
|
||
- Simplicity serves economy: less code, less to test, less to maintain.
|
||
|
||
### C4. Locality
|
||
Decisions and their consequences live near each other.
|
||
|
||
- State, logic, and side effects that depend on each other live near each other.
|
||
- Locality serves clarity: to understand a piece of code, you should not need to read the whole system.
|
||
- Locality serves correctness: coupling that is far apart is coupling you cannot see.
|
||
- A change that requires touching many distant files is a locality violation.
|
||
|
||
### C5. Reversibility
|
||
Every decision can be undone, and the cost of undoing is known.
|
||
|
||
- Reversibility serves safety: an irreversible decision is a bet you cannot hedge.
|
||
- Migrations, deployments, schema changes, and API changes are reversible by default.
|
||
- A decision that cannot be reversed is made with the maximum of evidence and the minimum of haste.
|
||
- Versioning, feature flags, and rollback paths are the mechanisms of reversibility.
|
||
|
||
### C6. Composability
|
||
Parts combine into wholes, and the parts are reusable in new wholes.
|
||
|
||
- Composability serves scale: complex systems are built from simple, composable parts.
|
||
- A part that does one thing well composes. A part that does many things configures.
|
||
- The boundary of a part is its contract. Contracts are explicit and stable.
|
||
- Composability serves clarity: composable parts are understandable in isolation.
|
||
|
||
### C7. Observability
|
||
The system's behavior is visible to the people who must understand it.
|
||
|
||
- Observability serves correctness: you cannot fix what you cannot see.
|
||
- Logs, metrics, and traces are first-class. They are designed in, not bolted on.
|
||
- Observability serves clarity: the system explains itself in production.
|
||
- An observable system answers "what happened, why, and what next?" without reading the source.
|
||
|
||
### C8. Economy
|
||
The system uses no more resources than the task requires.
|
||
|
||
- Resources include time, memory, attention, money, and complexity.
|
||
- Economy serves simplicity: the cheapest solution is often the simplest.
|
||
- Economy is the most tradeable principle: it is sacrificed for correctness, clarity, and reversibility.
|
||
- But unbounded economy is a bug: unbounded growth in any resource is a defect.
|
||
|
||
## 3. Precedence
|
||
|
||
When principles conflict, the lower-numbered principle wins:
|
||
|
||
```
|
||
C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
|
||
C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
|
||
```
|
||
|
||
- C1 (Correctness) is never sacrificed.
|
||
- C2 (Clarity) is sacrificed only for C1 (Correctness).
|
||
- C3 (Simplicity) is sacrificed only for C1 or C2.
|
||
- C4–C8 are tradeable among themselves, but always below C1–C3.
|
||
- The precedence is total: a violation of C1 is never justified by an appeal to C8.
|
||
|
||
See `core/conflict-resolution.md` for the formal conflict resolution procedure.
|
||
|
||
## 4. What Violates These Principles
|
||
|
||
| Violation | Principle Breached |
|
||
|-----------|-------------------|
|
||
| Code that "mostly works" | C1 Correctness |
|
||
| A function named `doStuff` | C2 Clarity |
|
||
| A 500-line function that could be 50 | C3 Simplicity |
|
||
| Config in a distant repo, code reads it silently | C4 Locality |
|
||
| A migration with no rollback | C5 Reversibility |
|
||
| A component that reads global state implicitly | C6 Composability |
|
||
| A service with no logs | C7 Observability |
|
||
| Loading all records into memory | C8 Economy |
|
||
|
||
## 5. Relationship to Domains
|
||
|
||
Every domain in Atelier derives its own P1–P10 principles from these eight. The mapping is recorded in `matrix/principles-matrix.md`. A domain rule that cannot be traced to a core principle is orphaned and must be removed.
|
||
|
||
The eight principles are the floor. The domain principles are the ceiling for their scope. Within a domain, the domain's precedence applies; across domains, the core precedence applies. |