Enola

What fails the build

Two separate things decide that, and confusing them is the fastest way to be surprised by this tool: what enola finds, and what your policy fails on. enola runs all nineteen of its checks - it calls them explainers - on every single run. The policy picks which of their findings are allowed to set the exit code.

Out of the box that policy is empty. Every finding is reported, the run exits 0, and the output says in as many words that nothing was enforced. Nothing breaks until you name what should break:

• code reaching across a layer order you declared, like storage talking straight to the delivery layer (layers)
• two modules that ended up depending on each other (cycles)
• a cross-repo seam nobody declared, or a declared one the graph never measured (intent)
• a single function or type that a large part of the codebase depends on (god-class)
• a function that nearly everything calls (hotspots)
• an import chain ten modules deep (dependency-depth)
• a function far more complicated than the rest of your code (complexity-outliers)
• a package that exports almost everything it contains, instead of a small surface (exported-surface)
• API routes that nothing in the code you loaded ever calls (unused-routes)
• outbound calls enola could not match to any route it loaded (coverage)
• messaging call sites without an AsyncAPI contract, and contract operations without detected code (messaging-coverage)
• which repositories in a cluster ended up depending on which (crossrepo)
• directories that look like vendored third-party code, reported so you can decide whether to ignore them (vendored-candidates — informational, so it can never fail a build)
• what import yourpackage executes in Python, and the package __init__.py files responsible for most of it (import-closure — the summary is informational; the barrels it names are gateable)

enola holds itself to this. This repository declares its own layer order in enola-intent.yaml - six layers, entrypoint down to the fact model - and its CI runs enola check --fail-on=layers against it. Not --fail-on=cycles: enola is written in Go, where the compiler already refuses an import cycle between packages, so gating on one would enforce a rule the toolchain enforces first. The layer order is the part the compiler cannot see. Nothing but that file stops internal/upgrade importing pkg/cli today, and the build is green either way until something says otherwise.

Why nothing is on by default. enola used to fail on a new dependency cycle out of the box. A cycle is exactly measurable - Tarjan's SCC algorithm, no estimate anywhere - and that made it a tempting default. But exactly measurable is not the same as unwanted: Go's compiler forbids import cycles between packages outright, so a Go team's answer to the finding is usually "the compiler already has this covered"; a Rails app wires most of its graph at runtime, and two app/ directories referencing each other is not something that community reads as a defect at all. A tool that arrives asserting otherwise spends its first impression being argued with, and the first thing those teams learn about it is which flag turns it off.

So enola states what it measured and stops there. The exception it makes for itself is the one above: an unenforced run must say it enforced nothing, because a silent green is exactly what a broken gate looks like.

Any of the nineteen can fail the build. --fail-on takes the names above as a comma-separated list, and --min-confidence sets the floor within them. Two more things can fail it that are not findings at all:

• scope spillover - packages your change reached outside the area you declared with --target, gated with --max-spillover=N. A change can trip this with zero failing findings.
• a gate that could not run. A missing baseline or a bad flag exits 2; a baseline that isn't comparable to the current code exits 3 and enola declines to grade rather than blaming your change. Neither is a judgement about the code, and neither is suppressed by --warn-only.

Which of them can actually fail at the default floor: three. cycles, intent, and layers when the order is declared in enola-intent.yaml are the ones enola computes with certainty, so only they reach 1.00. Everything else is an estimate measured against your own repository - "this file has unusually many dependents for this codebase" - and caps below 1.00 by design (MaxHeuristicConfidence is 0.95). Naming an inferred explainer in --fail-on and nothing else therefore changes nothing at all; it needs --min-confidence too.

Quickstart: close the loop around a coding agent

1. Install the binary. No Go toolchain, no C compiler - Linux, macOS (amd64/arm64) and Windows:

curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh

That drops one binary into ~/.local/bin. If the next command comes back enola: command not found, that directory isn't on your PATH yet:

export PATH="$HOME/.local/bin:$PATH"

Or install it from a package index. Every route delivers the same binary, and the command is always enola:

pip install enola-cli

gem "enola"   # then: bundle exec enola

The PyPI project is called enola-cli because enola was already taken there. The Ruby gems are maintained at enola-labs/enola-rb and fetch the same release on first use.

Ruby and Rails? There is a community-maintained gem that wraps the same release, fetches the binary on first use and forwards every command - and enola-rb adds a Rails generator plus enola:snapshot / enola:check rake tasks:

bundle add enola-rb
bin/rails generate enola:install
bin/rake enola:check

Both Ruby fact providers are on by default there. The gems are maintained by Muhamed Isabegović at misabegovic/enola-rb; issues and pull requests belong there. See docs/RAILS.md.

2. Tell your agents it exists, and close the loop automatically:

enola install --hooks

This writes enola's instructions into the files your agents already read - Claude Code, Cursor, Copilot, Codex, Pi, opencode - and --hooks adds the two hooks that grade each session for you. In opencode, which has no hook configuration of that shape, --hooks installs a plugin instead: the first grep, glob or list of a session is refused with the enola tool that answers it from the index, bounded to two refusals and dropped the moment any enola tool is called. Without --hooks you get instructions and nothing else, which an agent is free to read and then ignore - on a small local model it usually does. It previews every change and asks before writing, never creates a shared file like AGENTS.md that wasn't already there, and enola uninstall reverses everything byte-for-byte, including the files and directories it created itself.

3. Give your agent the graph over MCP. Pick your client:

<details> <summary>MCP config block</summary>

{
  "mcpServers": {
    "enola": {
      "command": "enola"
    }
  }
}

Copilot's .vscode/mcp.json uses servers as the top-level key instead of mcpServers. A config path in args is optional everywhere - omit it to run on built-in defaults. Full details and per-client restart instructions: docs/CLI.md.

</details>

4. Confirm it actually works. After your next session:

enola doctor

A report, not a gate - it always exits 0. It is the fastest way to find out that something has gone quietly wrong:

• whether the hooks fired. A hook configuration is a contract with your agent, and one it silently ignores looks exactly like one it honours, so doctor reports when each hook last ran rather than whether it is configured.
• whether your baseline still counts. One pinned by a different enola version, or under different ignore rules, is not comparable - and nothing is graded against it until you re-pin.
• whether there is a newer release - and specifically whether the extractors changed, which means your snapshots are missing facts a current build would find. enola upgrade installs it.

5. Explore the architecture visually. Once a snapshot exists, open the read-only local dashboard:

enola dashboard --open

It stays attached to the terminal until you press Ctrl-C. Use Refresh when you want to load a newer snapshot written for that repository, so the graph does not change while you inspect it. The opening screen prioritizes findings and architectural changes; lifetime usage has its own screen, while ports, processes, and paths live under Diagnostics. If no snapshot exists yet, the dashboard shows the exact generation command. Repository data never leaves your machine. See the dashboard user guide for a walkthrough of every tab.