Concept 7
Navigation and context
Finding where to make a change should be routing, not exploration. This is the part of Ordo with the most ambition and the least evidence, and this page says which is which.
In plain language
An engineer or an agent who does not know where a decision lives reads until they find it. That cost is real, it scales with the codebase rather than with the change, and it is invisible in every measure of output.
Ordo's answer is two small navigation artifacts: a repository-level map from semantic areas to their locations, and per-feature manifests declaring what a feature owns, what it depends on, and where its tests live. Neither is authority. Both are routing.
Why the distinction matters
A manifest that starts deciding rules becomes a second source of truth that nothing keeps in agreement with the first. Ordo is explicit that a manifest declares by reference only — it points at the authority; it does not restate it.
Status: adopted as an execution contract, with effectiveness recorded as EXPERIMENTAL (CL-015). There is no outcome trial. Manifest maintenance and staleness may offset the benefit entirely, and a small repository may not need per-feature manifests at all. This repository does not have them: its architecture document says so and explains that separate manifests would only duplicate indexes that already exist.
What was measured, and what it showed
The one experiment that measured navigation cost measured it as search operations, and found 38 to 14Search operations between the baseline and hardened architectures — a 63% reduction.
Two things stop that from being the clean result it looks like. The two conditions were run by agents with materially different strategies: one worked in a tight edit-then-compile loop, the other invested more in reading before editing. And unique files inspected did not drop the way search operations did — roughly 27 against 30.
So: fewer searches, not obviously less reading. The proposition is classified provisional for exactly that reason (CL-005).
Diagnostics, not scores
Ordo proposes three measures for this area — Context Surface, the Context Expansion Ratio between declared and actual context, and Discovery Expansion for files read outside a declared boundary. All three are proposed and unvalidated (CL-018).
Two rules attach to them, and both are about resisting a natural temptation. The counting unit must be fixed before measuring, or the number means whatever the measurer wants. And conformance must never be gated on them, because cross-cutting changes legitimately expand context, and a team scored on a ratio will optimise the ratio.
What an agent should do differently
- Read the repository map first. Route to the semantic area, then to its authority. Do not start with a repository-wide search.
- Prefer a mechanical signal over a search where one exists. A compiler error naming a site beats a grep guessing at one — in the tiers the architecture actually guards.
- When a change reaches outside its declared boundary, record it. That is a finding about the manifest or the architecture, and it is the only way either gets corrected.
How this is most often got wrong
Manifests that drift. A manifest nobody updates is worse than none, because it is confidently wrong and a reader trusts it.
Navigation metadata that starts deciding. The moment a manifest lists rules rather than pointing at them, it is an authority nobody declared.
Treating a discovery diagnostic as a target. Explicitly warned against in the method, because the failure mode is obvious: the cheapest way to improve the ratio is to declare more, not to need less.