What applies here

Uptime is aliveness

If the system is not running, nothing else matters until it is. This axiom overrides all others. Production is survival. This is the arc reflex — it doesn't queue behind the other axioms, it interrupts them.

Behaviors must be traceable to cause

Every behavior should be traceable to its cause. Surprise is acceptable when the derivation chain is walkable. Surprise without traceability is a defect.

Observability is not logging

Observability is not logging. Observability is designing the system so that its internal state is externally legible without being asked. A system that requires debugging to understand is a system whose builder didn't finish the job.

Types are contracts not annotations

Types are contracts, not annotations. A type that doesn't prevent a wrong state is documentation pretending to be engineering. If the type system allows an invalid state to be represented, the type system isn't doing its job.

Name the implicit

Name the implicit. When something is operating unnamed in the system — an implicit state, an undocumented convention, a pattern everyone follows but nobody wrote down — naming it is almost always an improvement.

Premature compression is root failure

Premature compression is the root failure mode. The urge to simplify before understanding produces dashboards instead of substrates, summaries instead of derivations, clean abstractions that silently lost something load-bearing. Complexity is real and we need to sit with it. It may reveal what it wants to be — a state machine, a strategy pattern, a clean separation waiting to be found. Or it may genuinely be a mess not worth the time. But the decision to compress must come after the understanding, not instead of it.

Decisions are not meant to be easy

Decisions are not meant to be easy. We need to be able to decide even on the hard ones. Easy decisions are a consequence of clear thinking and good design, not a prerequisite for action.

Legibility is a design obligation

Legibility is not a byproduct of working code; it is a design obligation owed to future readers. A system that works but cannot be understood without archaeology is unfinished, regardless of its outputs. The builder's job includes leaving the meaning visible.

Software is a social act

Software is a social act. Code is written by humans for humans — including the engineers and AIs who join long after you have left. Functionality is the floor; consensus on direction, taste, and clarity is what makes the floor stand up. A team with bad dynamics writes code that reflects it; a team that talks well writes code others want to live in.

Elegance is not luxury

Simplicity and clarity — in short, what mathematicians call elegance — are not a dispensable luxury, but a crucial matter that decides between success and failure (Dijkstra).

Semantic additions must be justified

Adding something semantically new to the system must be justified. Convenience is not justification. If the new concept doesn't earn its keep by simplifying the whole, it's complexity disguised as help.

Hidden states emerge from unwatched software

Hidden states are a consequence of unwatched software. When conditions have three or more booleans we should evaluate deeply. Humans are not good at boolean math.

Semantic challenge trumps boolean gymnastics

Semantic challenge trumps boolean gymnastics. isUserOfAge is better than age > 18. Name the meaning, not the mechanism.

Abstraction exists for readability

Abstraction exists for readability. The code should not mix levels of abstraction. When it does, the reader is forced to hold two mental models simultaneously, and the details contaminate the intent.

Composition over creation

Composition over creation. The best primitive is one that, combined with another, produces a capability neither had alone. Before creating something new, ask whether two existing things composed would do the job. The answer is often yes and the result is often better.

One liner is a consequence not an achievement

A one-liner is a consequence, not an achievement. Compressing code into fewer lines is not simplification unless the compression also reduced the number of concepts. Density for its own sake is obfuscation wearing the mask of elegance.

The domain outlives the requirement

A requirement is only a slice through the domain. Model facts where they belong in the world, not where the current feature first notices them. Reducing the model to the requirement's minimum can silently create false claims: wrong owner, wrong cardinality, wrong lifecycle, wrong observability. Placement of a real domain fact is not elaboration; only invented behavior must justify itself.

Understanding precedes compression

Compression is the reward for understanding, not a substitute for it. Whether compressing code into fewer lines, states into fewer booleans, or concepts into abstractions — the act of compression must follow genuine comprehension of what's being compressed, or it destroys information while pretending to simplify.

Encode meaning in the structure

Push semantics into the structure that carries them. Names should denote intent rather than mechanism, and types should make invalid states unrepresentable rather than merely described. When meaning lives only in prose or convention, the system cannot defend it.

Better is a direction good is a threshold

A code change that makes something better doesn't have to make it good. Better is a direction, good is a threshold we rarely reach with one change. Progress is incremental. Perfectionism is a blocking condition that prevents shipping. The direction matters more than the distance covered in a single step.

Architecture shift 2026 05

A planned architectural shift is underway, moving Mycelium toward (observer, artifact, lens) primitives plus a JustifiedAction action layer. PRs introducing the justified-action claim kind, agent-initiated-impulse claims, observation cycles, gatekeeper logic, per-person substrate identity, the extract pass, role-weighted aggregation toward team-lenses, or conversationalist interaction-preference claims are implementing this plan, not violating the existing substrate. Treat these additions as the new floor; apply the new shape's axioms when they apply rather than flagging the novelty itself. Existing tier-zero axioms (uptime-is-aliveness, elegance-is-not-luxury) still apply unchanged. The full plan and tracking lives at mycelium-ai-labs/mycelium#97.

Compress freely keep the way back

Compression is the only move — deciding, naming, abstracting are all compression. A label names a whole room so you need only remember where the door is. The failure mode is never compressing; it is losing the door. Compress freely; keep the way back. This governs the other axioms: each is itself a compression of lived failures, and stays legitimate only while the way back to them is kept.