Jon Chery
d195e8c3a9
---ci--- project: atelier phase: 3 milestone: v0.2 status: complete requirements: covered: [ATELIER-48, ATELIER-49, ATELIER-50, ATELIER-51, ATELIER-52, ATELIER-59] partial: [] ---/ci---
212 lines
12 KiB
Markdown
212 lines
12 KiB
Markdown
# 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 |
|
||
|
||
## Infrastructure as Code
|
||
|
||
| IaC Principle | Core | Why |
|
||
|---------------------------|------|---------------------------------------|
|
||
| P1 Declarative Intent | C2, C3 | Clarity; simplicity of declaration |
|
||
| P2 Idempotence | C1 | Correctness of repeated apply |
|
||
| P3 State is Truth | C1, C7 | Correctness; observability of reality |
|
||
| P4 Plan Before Apply | C5 | Reversibility of changes |
|
||
| P5 Version Everything | C5 | Reversibility of reproduction |
|
||
| P6 Modules Compose | C6 | Composability of infrastructure |
|
||
| P7 Least Privilege Providers | C1 | Correctness via security |
|
||
| P8 Remote State with Locking | C1, C4 | Correctness; locality of state |
|
||
| P9 Drift is Recoverable | C5, C7 | Reversibility; observability of drift |
|
||
| P10 Secrets Never in Code | C1 | Correctness includes secret safety |
|
||
|
||
## Kubernetes
|
||
|
||
| K8s Principle | Core | Why |
|
||
|---------------------------|------|---------------------------------------|
|
||
| P1 Declarative Desired State | C1, C2 | Correctness; clarity of intent |
|
||
| P2 Pods are Mortal | C5 | Reversibility of workloads |
|
||
| P3 Labels Select | C2, C6 | Clarity; composability of selection |
|
||
| P4 Requests and Limits | C1, C8 | Correctness; economy of resources |
|
||
| P5 Probes Drive Health | C1, C7 | Correctness; observability of health |
|
||
| P6 Namespaces Bound Blast | C4 | Locality of blast radius |
|
||
| P7 RBAC by Intent | C1 | Correctness via security |
|
||
| P8 Storage is Explicit | C4, C5 | Locality; reversibility of data |
|
||
| P9 Config and Secrets Sep | C2 | Clarity of configuration |
|
||
| P10 Roll Forward, Roll Back | C5 | Reversibility of deploys |
|
||
|
||
## Coverage Summary (post-v0.2)
|
||
|
||
- 13 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes)
|
||
- 130 domain principles total (110 v0.1 + 20 v0.2)
|
||
- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans. |