Most organizations have a set of engineering principles – stated values that describe how software should be built. Things like “fail early and loudly,” “no undocumented dependencies,” “security is everyone’s responsibility.” These principles typically live in documentation, onboarding guides, and the institutional knowledge of experienced engineers. What they rarely do is run.
Ethosure’s enforcement core is built around one central insight: engineering principles should not just be stated, they should be executable. This article traces the path from a named principle to a running enforcement rule, and explains why that path matters.
The principles file
The foundation of coding-ethos is a YAML file called `coding_ethos.yml`. This file holds approximately 29 named engineering principles. Each principle is not a vague statement of intent; it is a structured record with:
- A stable ID (e.g., `security-by-design`, `fail-fast-fail-hard`, `one-path-for-critical-operations`).
- A short directive – the actionable one-liner that defines what the principle requires.
- A summary explaining why the principle matters.
- Tags for discovery and grouping.
- A pointer to the detailed guidance document in `.agents/ethos/`.
- Agent hints for specific AI agent providers, showing how each agent type should interpret the principle.
This structure is not documentation for its own sake. It is the input to the policy compiler – the raw material from which running enforcement rules are derived.
A look at real principles
Some examples from the coding-ethos principle set illustrate how concrete these definitions are:
`fail-fast-fail-hard`: Systems should detect problems immediately and terminate clearly, rather than continuing in a degraded or ambiguous state. In practice, this becomes policies that block error-suppression patterns (catching exceptions and logging nothing, optional returns that hide failures) and require startup validation.
`security-by-design`: Security requirements are built in from the start, not added as an afterthought. This principle owns the sandbox capability contract – policies like `runtime.network_requires_approval` (network access requires explicit approval) and `runtime.managed_tool_capability_contract` (tools must declare their capabilities honestly) are grounded in this principle.
`one-path-for-critical-operations`: Critical operations – Git commits, policy evaluations, enforcement actions – should have exactly one governed path. This principle owns the hook-bypass policy: if there are multiple ways to commit code, agents and developers will find the ones that skip checks. One path, always governed.
`radical-visibility`: The system should make its behavior observable and auditable. This principle is reflected in the SARIF evidence system, the append-only ledger, and the requirement that every enforcement decision be traceable to a policy and a principle.
`evidence-based-engineering`: Decisions should be backed by observable evidence, not assumptions. This drives the code-intelligence memory system – storing prior failures, remediation outcomes, and policy check results so that future decisions can be grounded in what actually happened.
Principles own their policies
The key architectural decision is that principles own their policies. A policy rule does not exist in isolation – it is always linked to the principle it enforces. When the `git.hook_bypass` policy fires and blocks a `git commit –no-verify` attempt, the evidence record includes not just the policy ID but the principle (`one-path-for-critical-operations`) and a quick reference to why that principle matters.
This linkage has practical consequences:
- For agents: repair guidance comes with context. An agent that receives a block is not just told what it cannot do; it is pointed to the principle that explains why.
- For developers: code review discussions can reference principles rather than ad hoc personal preferences. “This violates `security-by-design` policy `runtime.network_requires_approval`” is a more grounded objection than “I don’t like that this tool makes network requests.”
- For compliance teams: every enforcement event is traceable to a named organizational value, not just a technical rule. That traceability is what makes the evidence pack meaningful rather than just voluminous.
Principles own their skills
Beyond policies, principles also own skill playbooks – generated repair guidance documents that agents receive when a policy fires. A skill for `one-path-for-critical-operations` might contain step-by-step instructions for using the managed Git wrapper correctly. A skill for `security-by-design` might contain a checklist for reviewing a proposed tool capability declaration.
Skills are generated from the same compiled model, which means they stay synchronized with the policies they support. When the policy changes, the skill guidance changes too.
Principles own their agent hints
Each principle entry in `coding_ethos.yml` can include agent-specific hints. For example, a principle might specify different framing for Claude versus Codex – not different rules, but different ways of presenting the same rule to agents that have different default behaviors or context windows.
This multi-agent awareness is designed in from the start: the system expects to govern heterogeneous fleets of agents, each with different capabilities and tendencies. The principles provide the stable, agent-neutral foundation; the hints adapt the presentation.
From YAML to running enforcement
The complete flow from principle to enforcement runs:
- `coding_ethos.yml` defines the principle with its ID, directive, and metadata.
- `config.yaml` and `repo_config.yaml` define the enforcement configuration – which evaluators to use, which policies are enabled, repo-specific overrides.
- The policy compiler reads both and produces `policy-bundle.json` – a versioned, graph-shaped JSON file that contains principles, policies, evaluators, and dispatch indexes.
- Hooks, the MCP server, the unified linter, and the Git wrapper all read the bundle at runtime. The same principles that were YAML text now drive executable enforcement.
- Every enforcement event records the principle IDs alongside the policy ID, so the evidence trail shows not just what was blocked but why, all the way back to a named organizational value.
