Skip to content
Orix Platform

Orix Engineering Standards

Orix Engineering Standards

Status: GOVERNING Version: 2.0 (Consolidated from LES v1) Violations: ERROR or BLOCKING

Practical standards for implementing Orix systems that comply with certification requirements.

Quick Reference

SectionPurposeKey Rules
CODESource CodeSingle responsibility, explicit ownership
TESTTestingRepeatable, deterministic, contracts
BUILDCompilationReproducible, deterministic
GENCode GenerationSame rules as handwritten
DOCDocumentationLiving, traceable, intent preserved
AGENTAI AgentsMechanical, no guessing, halt on ambiguity
DECDecisionsFormal records, rationale preserved

CODE: Source Code Standards

File Standards

LES-CODE-001: File Ownership Every file declares owning module and responsibility.

Forbidden: orphan files, misc, utils, helpers.

LES-CODE-002: Single Responsibility One file = one responsibility. No mixed concerns.

LES-CODE-003: Deterministic Compilation No conditional compilation based on environment unless declared.

Naming Standards

LES-CODE-010: Names Are Contracts Identifiers encode role, scope, and stability.

Forbidden: Manager, Utils, Helper, Thing, Data2.

LES-CODE-011: No Semantic Overloading A name means one thing. Different meaning = different name.

LES-CODE-012: Abbreviation Ban No abbreviations except universal standards (ID, URL) or documented.

State & Ownership

LES-CODE-020: Explicit State All mutable state explicitly declared.

Forbidden: implicit globals, hidden static state.

LES-CODE-021: Single Owner Every mutable state has single owner with declared mutation rights.

Forbidden: shared mutable ownership.

LES-CODE-022: No Ambient State No global clocks, thread-local state, or process-wide mutable config.

Control Flow

LES-CODE-030: Explicit Control Flow Control flow must be explicit and readable.

Forbidden: hidden callbacks, operator overloading for logic, exceptions for normal flow.

LES-CODE-031: No Implicit Ordering Any ordering affecting behavior must be explicit.

TEST: Testing Standards

Core Requirements

LES-TEST-001: Tests Are Contracts Tests are executable contract assertions, not “coverage”.

LES-TEST-002: Deterministic Tests All tests must be:

  • Repeatable
  • Order-independent
  • Identical across runs

Flaky tests indicate determinism failure, not test instability.

LES-TEST-003: Isolated Tests No shared mutable state between tests.

Test Structure

LES-TEST-010: Given-When-Then

// Given: setup
// When: action
// Then: assertion

LES-TEST-011: Single Assertion Focus Each test verifies one behavior.

LES-TEST-012: No Test Logic Tests should not contain complex logic. If branching, split test.

Evidence Requirements

LES-TEST-020: Trace Artifacts Tests produce evidence that can be reviewed later.

LES-TEST-021: Failure Diagnostics Test failures must include sufficient context for diagnosis.

BUILD: Build Standards

Reproducibility

LES-BUILD-001: Reproducible Builds Same source → same binary across:

  • Machines
  • Time
  • Builds

LES-BUILD-002: No Build Machine State Build must not depend on build machine specific state.

LES-BUILD-003: Locked Dependencies All dependencies version-locked and verifiable.

Configuration

LES-BUILD-010: TreatWarningsAsErrors All warnings are errors. No exceptions.

LES-BUILD-011: Zero Warnings Build produces zero warnings or fails.

GEN: Code Generation Standards

Core Rule

LES-GEN-001: Same Rules Apply Generated code must follow all LES-CODE rules. Generated code is not exempt from any standard.

Generation Requirements

LES-GEN-010: Schema First All generated types come from Axion schemas.

LES-GEN-011: Traceable Generation Generated code includes:

  • Source schema reference
  • Schema hash
  • Generation timestamp
  • Generator version

LES-GEN-012: No Manual Modification Generated files must not be manually modified. Use partial classes for extensions.

DOC: Documentation Standards

Living Documentation

LES-DOC-001: Synchronized Documentation must stay synchronized with implementation.

LES-DOC-002: Preserve Intent Document “why” alongside “what”.

LES-DOC-003: No Context Dependence Documents must be interpretable without chat history or personal memory.

Document Types

TypePurposeFormat
SpecComponent behaviorMarkdown
DECDecision recordTemplate
APIInterface contractGenerated
GuideHow-toMarkdown

Requirements

LES-DOC-010: Claims Linked to Evidence Every claim references evidence or marks as unverified.

LES-DOC-011: Versioned Documents Significant documents are versioned.

AGENT: AI Agent Standards

Authority Model

LES-AGENT-001: No Inherent Authority Agents have zero inherent authority. All authority from:

  • Explicit user instruction
  • Explicit standards
  • Decision artifacts

LES-AGENT-002: Instruction Precedence When conflicts:

  1. Laws (LAWS.md)
  2. Principles (PRINCIPLES.md)
  3. Certification (CERTIFICATION.md)
  4. Engineering (this file)
  5. User instruction

Agents refuse instructions violating higher layers.

Permitted Actions

LES-AGENT-010: Explicit Actions Only Agents MAY:

  • Generate artifacts when instructed
  • Validate compliance
  • Surface violations
  • Refuse to proceed
  • Request missing artifacts
  • Apply mechanical transformations

All actions must be traceable.

Forbidden Actions

LES-AGENT-020: No Decision Making Agents MUST NOT choose between alternatives or resolve tradeoffs.

LES-AGENT-021: No Guessing If information is missing, halt and ask.

LES-AGENT-022: No Scope Expansion “While we’re here…” is forbidden.

LES-AGENT-023: No Interpretation Apply rules mechanically, not interpretively.

Ambiguity Protocol

  1. Surface ambiguity explicitly
  2. Halt work
  3. Request clarification
  4. Never assume or infer

DEC: Decision Standards

When Required

Decisions required for:

  • Architectural changes
  • Breaking changes
  • Tradeoffs
  • New dependencies
  • Standard amendments

Decision Record Format

# DEC-YYYY-NNN: Title


**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Rejected | Deprecated


## Context
What is the situation?


## Decision
What was decided?


## Consequences
What are the implications?


## References
Links to relevant documents/code.

Requirements

LES-DEC-001: Permanent Record Decisions are never deleted, only deprecated.

LES-DEC-002: Rationale Required Every decision includes rationale.

LES-DEC-003: Alternatives Documented Rejected alternatives documented with reasoning.

Violation Handling

LevelDescriptionAction
ERRORLocal riskFix before merge
BLOCKINGUncertaintyHalt until resolved

Aggregation

  • 3+ ERRORs in same file → BLOCKING
  • Unresolved BLOCKING → Escalate to CRITICAL

See Also

Consolidated from LES v1 (12 sections) - see docs/archive/standards-v1/LES-INDEX.md for original