Orix Engineering Principles

Orix Engineering Principles

Status: GOVERNING Version: 2.0 (Consolidated from LEP v1) Violations: BLOCKING by default

Principles constrain engineering choices when multiple legal paths exist. They are binding constraints, not preferences.

---

Normative Semantics

• Principles constrain decisions, not replace laws
• Conflicts with LAWS must be resolved in favor of laws
• Principles MUST be referenced in Decision Records when relevant
• Trend-based or fashionable principles are forbidden

---

Category A: Determinism & Truth

ID	Principle	Statement
P01	Determinism First	Determinism wins over convenience
P02	Truth Over Narrative	Provably true > sounds correct
P03	Conservative Uncertainty	Preserve invariants, reduce blast radius
P04	No “Probably”	Defined conditions or halt
P05	Designed Determinism	Design determinism explicitly, don’t discover it

---

Category B: Explicitness & Reasoning

ID	Principle	Statement
P06	Explicit Over Implicit	No inference, defaults, or ambient context
P07	Local Reasoning	Component understood from own artifacts
P08	Single Meaning	One concept = one meaning in context
P09	Clear Ownership	Ownership trivially identifiable
P10	Boundaries Are Features	Boundaries are correctness, not overhead

---

Category C: Verification & Evidence

ID	Principle	Statement
P11	Proof Before Dependence	Don’t depend on unproven claims
P12	Tests Are Contracts	Tests are executable contract assertions
P13	Fail Fast	Detect invalid states early with diagnostics
P14	Regression Sensitivity	Easy to detect, hard to hide
P15	Evidence First-Class	Evidence is permanent system state

---

Category D: Safety & Robustness

ID	Principle	Statement
P16	Safe Failure	Correct halt > continued incorrect operation
P17	Narrow Blast Radius	Failures contained, don’t cascade
P18	Defensive Boundaries	Strict at boundaries, simple inside
P19	Unrepresentable Invalids	Types prevent invalid states
P20	Predictable Degradation	Defined degradation under stress

---

Category E: Design & Architecture

ID	Principle	Statement
P21	Contracts First	Define contracts before implementations
P22	Composition > Cleverness	Simple composable parts > monolithic clever
P23	Data Shapes Behavior	Layout-aware, data-driven design
P24	Minimize Coupling	Explicit dependencies over shared state
P25	Layer Purity	Lower layers never depend on higher

---

Category F: Performance & Resources

ID	Principle	Statement
P26	Predictable Costs	Explicit, bounded worst-case costs
P27	Hot Path Discipline	Allocation-free, measurable hot paths
P28	Boring Performance	Easy to prove and maintain
P29	Measure First	Evidence over intuition
P30	Justified Optimization	Evidence and documented tradeoffs required

---

Category G: Evolution & Compatibility

ID	Principle	Statement
P31	Contracts > Convenience	Stability even if refactoring harder
P32	Explicit Versions	Version impact clear and detectable
P33	Migration by Design	Explicit upgrade paths, not ad-hoc
P34	Backward Compatible	Default unless breakage justified
P35	Deprecation Contract	Explicit deprecation over silent replacement

---

Category H: Collaboration & Agents

ID	Principle	Statement
P36	Enforce, Not Invent	Mechanical enforcement, not helpful guessing
P37	Clarity > Speed	Correctness even if slower
P38	Reviewable	Changes reviewable from repo alone
P39	No Heroics	Correct without extraordinary diligence
P40	Explicit Decisions	Visible decision-making over “obvious”

---

Category I: Documentation & Continuity

ID	Principle	Statement
P41	Living Docs	Documentation evolves with system
P42	Future Reader	Interpretable under context reset
P43	Preserve Intent	”Why” alongside “what”
P44	No Context Dependence	No reliance on chat history or memory
P45	Continuity > Completion	Resumable progress over rushed completion

---

Category J: Governance & Integrity

ID	Principle	Statement
P46	Standards Are Law	Treat standards as law, not suggestion
P47	Rare Amendments	Stability; amend with strong justification
P48	Consistency > Style	Project consistency over personal preference
P49	Integrity > Optics	Truth and proof over looking impressive
P50	Survive Successors	Maintainable by unknown future maintainers

---

Application Rules

Decision Records Must Reference Principles

Any decision touching a principle category MUST explicitly reference relevant principle IDs.

Conflicts Must Be Explicit

When principles conflict:

1. Record the conflict
2. Explicit resolution required
3. Cite why and how harm is minimized

Principles Cannot Override Laws

Principles cannot justify breaking Laws or Certification requirements.

---

Quick Reference: Top 10 for Daily Use

1. P01 Determinism First - When in doubt, choose determinism
2. P06 Explicit Over Implicit - No magic, no inference
3. P16 Safe Failure - Stop correctly rather than continue wrong
4. P19 Unrepresentable Invalids - Make bad states impossible
5. P21 Contracts First - Define interface before implementation
6. P27 Hot Path Discipline - No allocations in critical paths
7. P36 Enforce, Not Invent - Agents apply rules, don’t create them
8. P38 Reviewable - Everything reviewable from repo artifacts
9. P43 Preserve Intent - Document the “why”
10. P46 Standards Are Law - Treat all standards as mandatory

---

See Also

• CLAUDE.md - Single source of governance truth
• LAWS.md - Immutable engineering laws
• CERTIFICATION.md - Compliance requirements
• ENGINEERING.md - Implementation practices

---

Consolidated from LEP v1 (50 principles) - see docs/archive/standards-v1/LEP.md for original