Jon Chery
61043dea1b
---ci--- project: atelier phase: 4 milestone: v0.3 status: complete requirements: covered: [ATELIER-80, ATELIER-81, ATELIER-82, ATELIER-83, ATELIER-84, ATELIER-85] partial: [] ---/ci---
272 lines
17 KiB
Markdown
272 lines
17 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 |
|
||
|
||
## GitOps + Operators
|
||
|
||
| GitOps Principle | Core | Why |
|
||
|---------------------------|------|---------------------------------------|
|
||
| P1 Git is the Source of Truth | C1, C5 | Correctness of source; reversibility via history |
|
||
| P2 Declarative Over Imperative | C2, C3 | Clarity of intent; simplicity of expression |
|
||
| P3 Pull, Don't Push | C1, C4 | Correctness via security; locality of credentials |
|
||
| P4 Continuous Reconciliation | C7, C1 | Observability of drift; correctness of converge loop |
|
||
| P5 State is Immutable and Versioned | C5 | Reversibility through history |
|
||
| P6 Operators Encode Domain Knowledge | C6, C2 | Composability of expertise; clarity of operations |
|
||
| P7 Progressive Delivery is Reversible | C5, C1 | Reversibility of promotion; correctness of abort |
|
||
| P8 Reconcile, Don't Mutate by Hand | C1, C7 | Correctness of source of truth; observability of drift |
|
||
| P9 Failure is Observable and Surfaced | C7 | Observability of sync/rollout health |
|
||
| P10 Least Privilege Reconciliation | C1, C8 | Correctness via security; economy of trust |
|
||
|
||
## AI / ML
|
||
|
||
| AI/ML Principle | Core | Why |
|
||
|---------------------------|------|---------------------------------------|
|
||
| P1 Reproducibility is the First Class | C1, C5 | Correctness of runs; reversibility of reproduction |
|
||
| P2 Data is Versioned, Not Just Code | C5, C7 | Reversibility of data; observability of dataset lineage |
|
||
| P3 Lineage is Traceable End-to-End | C7, C1 | Observability of predictions; correctness of provenance |
|
||
| P4 Evaluation is Defined Before Training | C1, C2 | Correctness of metrics; clarity of thresholds |
|
||
| P5 Models are Versioned Artifacts | C5, C6 | Reversibility of model rollbacks; composability of registry |
|
||
| P6 Serving is Observable | C7 | Observability of inference |
|
||
| P7 Drift is Expected and Detected | C7, C1 | Observability of drift; correctness of detection |
|
||
| P8 Inference Inputs are Validated | C1 | Correctness at serving boundary |
|
||
| P9 Pipelines Compose, Notebooks Don't | C6, C2 | Composability of steps; clarity of contracts |
|
||
| P10 Rollback Includes the Model | C5 | Reversibility at the model layer |
|
||
|
||
## i18n
|
||
|
||
| i18n Principle | Core | Why |
|
||
|---------------------------|------|---------------------------------------|
|
||
| P1 Source Language is a Locale, Not the Default | C2, C1 | Clarity; correctness of localization model |
|
||
| P2 Locale Identifiers are Standardized | C2, C6 | Clarity; composability of BCP 47 |
|
||
| P3 Resources are External, Not Inline | C4, C6 | Locality of strings; composability of resources |
|
||
| P4 Plural and Gender are Parameterized | C1, C6 | Correctness across locales; composability of message format |
|
||
| P5 Formatting is Locale-Aware | C1, C7 | Correctness of formats; observability of format correctness |
|
||
| P6 Text Direction is a Layout Primitive | C1, C4 | Correctness of RTL/bidi; locality of direction |
|
||
| P7 Layout Accommodates Expansion | C8, C3 | Economy of rework; simplicity of flexible layout |
|
||
| P8 Pseudo-Locales Test Early | C7, C5 | Observability of bugs early; reversibility of finding late |
|
||
| P9 Images and Icons are Cultural | C1, C2 | Correctness; clarity of cultural meaning |
|
||
| P10 Translation is Reversible and Versioned | C5 | Reversibility of localization changes |
|
||
|
||
## Compliance
|
||
|
||
| Compliance Principle | Core | Why |
|
||
|---------------------------|------|---------------------------------------|
|
||
| P1 Audit Logs are Append-Only | C1, C5 | Correctness of audit; reversibility of immutable record |
|
||
| P2 Every Significant Action is Logged | C7, C1 | Observability of actions; correctness of audit set |
|
||
| P3 Retention is Policy, Not Storage | C5, C8 | Reversibility of lifecycle; economy of storage |
|
||
| P4 Policy is Code | C6, C2 | Composability of policy; clarity of rules |
|
||
| P5 Policy is Evaluated as a Gate | C1, C5 | Correctness of enforcement; reversibility of block |
|
||
| P6 Evidence is Collected Continuously | C7, C3 | Observability of posture; simplicity of audit |
|
||
| P7 Identity is Attributable | C1, C7 | Correctness of attribution; observability of subject |
|
||
| P8 Subject Access is Honored | C1, C5 | Correctness of rights; reversibility of deletion/export |
|
||
| P9 Secrets and Sensitive Data are Redacted in Audit | C1, C3 | Correctness via security; simplicity of structural redaction |
|
||
| P10 Compliance Posture is Observable | C7, C1 | Observability of compliance; correctness of posture |
|
||
|
||
## Coverage Summary (post-v0.3)
|
||
|
||
- 17 domains (11 v0.1 + 2 v0.2: infrastructure-as-code, kubernetes; 4 v0.3: gitops-operators, ai-ml, i18n, compliance)
|
||
- 170 domain principles total (110 v0.1 + 20 v0.2 + 40 v0.3)
|
||
- Every domain P-rule traces to ≥1 core C-rule (C1–C8). No orphans. |