Ordo · State-Directed Engineering

Make the legal next move explicit.

Ordo is Echelon Foundry's engineering methodology for building software around explicit state, evidence, legal transitions, capabilities, obligations, and uncertainty. Instead of asking a human or an AI agent to infer what the system means, the domain states what is true, what may happen next, what is still unresolved, and what must be verified before work continues.

State is explicit What can be true is represented directly
Evidence is explicit What is known, from where, and with what coverage
Legal actions are derived The domain exposes what may happen next
Unresolved work stays visible Unknown effects and obligations are not collapsed away
Ordo reduces inference by moving decision-relevant meaning into structures the software can check.

In one sentence

Bound the reasoning before you ask for a decision.

Give the engineer or agent the smallest semantically complete state view, the evidence and coverage that support it, the authority already established by the host, and the legal choices the domain permits. Then verify the result through mechanisms with different failure sensitivities.

Ordo is not an AI wrapper, not a generic workflow engine, and not a fifth architecture tier. It is a method for making software semantics explicit and mechanically enforceable.
No state-machine background required

Think about ordering coffee.

You already reason about state in everyday life. Software becomes easier to understand when it makes those same rules explicit.

See the full C# example

What you ordered

Black, cream, sugar, or both

Cream and sugar describe the coffee. They are data about the order. They do not, by themselves, tell you what may happen next.

Coffee With cream + sugar

Where the order is

Taking Order → Preparing → Ready → Served

These are states because each one changes the legal next move. You cannot serve coffee before it is ready. You should not change the recipe after preparation has started.

Ordo applies that ordinary idea to software: make what is true now and what is legally allowed next explicit, then let people, UIs, APIs, and AI agents operate inside those rules instead of reconstructing them independently.

The core idea

Give the system a vocabulary for truth, action, and uncertainty.

Most codebases encode these ideas indirectly through nullable fields, duplicated checks, comments, conventions, exceptions, and tribal knowledge. Ordo makes them first-class.

State

Represent what can actually be true

A domain uses closed alternatives and state-specific data rather than asking every caller to reconstruct meaning from combinations of fields. A bounded decision operates on the smallest domain-defined state view that is semantically complete for that decision.

The view is versioned and fingerprinted as a whole. Ordo does not selectively ignore changed fields.

Evidence and coverage

Represent what is known and how completely it is known

Evidence carries provenance. Coverage says whether a named scope is Complete, Partial, or Unknown. Required coverage can stop a decision before a provider or model is called.

More context, provider confidence, or a successful call never silently becomes proof of complete coverage.

Capabilities

Expose semantic authority, not a second rulebook

A Capability is a semantic authority prerequisite that the host has already established and supplied for transition evaluation. It is not authentication and it cannot be created by model output or confidence.

The same predicates that guard a transition should also determine whether that transition is available.

Obligations

Make unresolved work part of the state

If something must still happen before the system can proceed safely, Ordo represents that as an obligation instead of leaving it in a comment, a log message, or someone's memory.

Obligations can block later transitions until the domain's required work is actually satisfied.

External effects

Unknown is not Failed

External work can Succeed, Fail, or be Unknown. If the system cannot tell whether a state-changing effect occurred, it retains that uncertainty and creates reconciliation work rather than pretending failure or retrying blindly.

Tier Three and Tier Four perform the observation. Tier One and Tier Two interpret what the result means.

Negative knowledge

"Not found" is only meaningful inside a complete scope

Ordo distinguishes absent from not searched, not compared, unsupported, unavailable, and unknown. A negative observation can support absence only when the method could detect the target and coverage for the matching scope is Complete.

This prevents missing information from being silently promoted into a fact.

A concrete state example

Explicit state turns business rules into visible routes.

The time-entry experiment is a small example: three named states, four legal transitions, and a terminal state with no route out. The important part is not the domain. It is that the legal graph is inspectable instead of reconstructed from incidental fields and conditionals.

Time entry lifecycle: three states and four legal transitions A time entry is created into the Recorded state. Recorded can move to Voided, and Voided back to Recorded. Recorded can move to Superseded when the entry is split or merged. Superseded is terminal: no transition leaves it. create void restore split or merge Recorded Voided Superseded terminal
The lifecycle implemented independently by three separate builds of the same requirements. Nothing leaves Superseded: every guard refuses it, and two acceptance criteria assert the refusal rather than relying on its absence from the code.
A bounded decision

The decision starts before the model or engineer chooses anything.

Ordo defines the semantic conditions under which a decision is allowed to exist.

  1. 1Semantically complete state viewThe domain projects the smallest authoritative view in which no omitted fact could change legality, evidence requirements, coverage, capability applicability, obligations, policy, or transition outcome.
  2. 2EvidenceTyped evidence identifies what was observed, where it came from, when it was observed, and what it depends on.
  3. 3Scoped coverageEach contract-defined scope is Complete, Partial, or Unknown. Required non-Complete coverage refuses the decision before provider execution.
  4. 4Capabilities and obligationsHost-established semantic authority is supplied as capabilities; unresolved required work remains explicit as obligations.
  5. 5Legal choice spacePolicy, guards, state, evidence, coverage, capabilities, and obligations determine which outcomes are actually legal.
  6. 6Compute, bounded decide, refuse, or escalateDeterministic work stays deterministic. Judgment happens only inside the legal choice space. Missing prerequisites do not force an answer.
  7. 7Result, requested effects, and auditThe result carries the state identity and decision facts forward; external work is requested as data and observations are recorded for later verification.
A bounded Ordo decision is legal only after the domain has established the state being judged, the evidence and coverage supporting it, the authority already granted, and the choices that remain legal. The model or engineer selects inside that envelope; it does not create the envelope.

The important shift is that provider output is never the source of authority. A model may help choose among legal alternatives, but it cannot invent a capability, waive missing coverage, erase an obligation, or make an illegal transition legal.

Architecture

Four tiers. One dependency direction.

Ordo strengthens the semantic core without pulling infrastructure concerns into it.

  1. 1Tier Four — Host / External EffectsDatabase, network, HTTP, browser, filesystem, clock, queues, provider SDKs, persistence and other external I/O. Reports Succeeded, Failed, or Unknown.
  2. 2Tier Three — Application / Projection / OrchestrationCoordinates use cases, projections, requested effects, and boundary translation without becoming a second semantic authority.
  3. 3Tier Two — State Transition / Domain ExecutionOwns decisions, guards, policy, invariants, evidence and capability requirements, legal transitions, obligations, and interpretation of effect results.
  4. 4Tier One — Semantic ModelOwns what can be true: domain values, closed alternatives, state-specific data, evidence, coverage, capabilities, obligations, and uncertainty.
Dependencies point toward the semantic core. Ordo refines Tier One and Tier Two semantics without moving infrastructure inward. ROS observes engineering execution from outside this stack; it is not a fifth tier.

Dependencies point toward the semantic core. ROS observes engineering execution from outside the application stack. It is not Tier Five, and application correctness must not depend on ROS being present.

AI-assisted engineering

Ordo changes what the agent has to reason about.

The goal is not a smarter prompt. The goal is a smaller, better-defined reasoning surface.

Less reconstruction

Semantic maps, structural locality, explicit state, and bounded context reduce how much of the repository must be rediscovered before a safe change can begin.

A narrower action space

Agents choose from domain-defined legal actions rather than inventing requests and relying on downstream validation to reject the wrong ones.

Explicit refusal and escalation

Missing authority, insufficient coverage, unresolved obligations, and unknown effects can stop work explicitly instead of forcing an answer.

Deterministic work stays deterministic

Where a result can be computed or mechanically verified, Ordo prefers that mechanism over open-ended model reasoning.

  1. 1Work item and acceptance criteriaThe requested change starts with explicit intent and conditions that can be checked.
  2. 2Semantic mapThe repository points to the semantic area and authority that own the decision.
  3. 3Declared feature contextState, transitions, contracts, effects, interfaces, and tests for the feature are locally discoverable.
  4. 4Mechanical feedback firstCompiler, architecture, contract, and structural checks expose required propagation before broad search.
  5. 5Expand only when evidence says context is insufficientSearch is an escalation mechanism, not the default navigation strategy.
  6. 6Heterogeneous verificationBehavioural, integration, and independent review cover failure classes the earlier mechanisms cannot.
  7. 7Record evidence and unresolved obligationsThe work leaves behind what ran, what was established, what remains open, and what the evidence does not prove.
Ordo treats repository context as something to route and verify, not something every engineer or agent should reconstruct by exploration.

Lower cost, fewer tokens, lower latency, and more safely autonomous work are current measurement objectives, not established Ordo results. The methodology is deliberately instrumented so those claims can be tested rather than assumed.

Evidence

What the evidence currently supports.

Ordo's strongest results are about how failures become discoverable, where mechanical feedback catches them, and how independently constructed implementations converge.

See the full evidence

0 of 5

Independent-verification findings the builder's own checks had already caught

Instrumented

Measures
Of five findings from a fresh agent with no knowledge of the construction, how many were already covered by the builder's own 90-test suite or its own adversarial self-review.
Collected by
An overlap analysis performed against the existing suite and self-review document after the verification findings were received.
Does not show
One verification pass on one codebase. It shows these mechanisms missed what that one found; it does not quantify how much any mechanism generally misses, and a different reviewer would have found a different set.
Sourcekemiller2002/SDE-Engineering-Trial-2-Greenfield-Construction / experiment-2b/INDEPENDENT-VERIFICATION.md at claude/greenfield-experiment-2b-replication-n8pgtqprivate repository

0

Mistakes caught by the language

Instrumented

Measures
Mistakes in the conventional JavaScript rebuild caught by the language or its tooling rather than by a test or a person.
Collected by
Classified per mistake as it was found. A property rename across two production files produced zero errors, zero warnings and zero crashes.
Does not show
A property of JavaScript with no type checker configured, not a claim about JavaScript projects that use one.
Sourcekemiller2002/time-entry-state-machine / effort-experiment/EFFORT-LOG.md at 73a63f1ac319 — Totals — the complete hodgepodge JavaScript buildprivate repository

58 / 58

Acceptance criteria implemented and traced

Self-reported

Measures
Acceptance criteria from the frozen requirements package with an implementation and a named test, mapped ID by ID.
Collected by
A traceability document mapping each criterion to the test covering it, written alongside the implementation.
Does not show
Traceability means every criterion has a test. It does not mean the tests are good: this build's own suite found zero new defects, and an independent reviewer of the replication found five things its equivalent suite missed.
Sourcekemiller2002/SDE-Engineering-Trial-2-Greenfield-Construction / experiment/REQUIREMENTS-TRACEABILITY.md at claude/greenfield-engineering-experiment-2-ee44qzprivate repository
Verification mechanisms and their blind spots
MechanismRefusesCannot refuse
Type and exhaustiveness checkingUnrepresentable states, unhandled cases, signature driftCode that type-checks and does the wrong thing
Architecture and dependency checksLayering violations, inverted dependenciesCorrect layering around incorrect behaviour
Contract and boundary checksRepresentation collapse at a declared boundaryBoundaries nobody declared
Behavioural testsBehaviour the author thought to assertA check that passes for the wrong reason
Integration against a real boundaryPresent-but-inert implementations, wire-format mismatchesConditions the integration environment never produces
Independent adversarial reviewDeclared-but-unreachable outcomes, vacuous assertionsAnything the reviewer also fails to imagine
Each row's right-hand column is what some later mechanism has to cover. This is why Ordo asks for several mechanisms with different sensitivities rather than a higher number from one.

Ordo does not currently establish that state-directed development produces fewer defects overall than conventional development. Some controlled comparisons showed no measurable difference for specific change classes. Those contradictions remain published because the boundary of the evidence matters as much as the positive result.

Start here

Ordo is a method for making the software explain its own rules.

Start with explicit state and legal transitions. Add evidence, coverage, capabilities, obligations, boundary preservation, structural locality, and heterogeneous verification as the system requires them.