Evolith runs architecture rules — layering, dependencies, security, CI/CD, ADRs — against your repository from CI, and fails the PR. Unlike the rest, it tells you how many rules it could not evaluate, and if any of them was blocking, it fails anyway.

npx -y @beyondnet/evolith-cli init --name my-sat --yes   # writes evolith.yaml right here
npx -y @beyondnet/evolith-cli validate --engine opa      # expect findings: this is a baseline

This is what it prints, with nothing rounded up:

**Status:** failed
**Rules Checked:** 133
**Rules Skipped:** 26
**Rules Errored:** 0
**Rules Total:** 159
...
| SEC-INJ-01 | MUST | security | Blocking rule did not run: No shell exec with user input | YES |
...
| GOV-RULE-NOT-APPLICABLE | COULD | governance | 253 corpus rules do not apply to this repository | no |
**Selection:** {"source":"core-default","rulesSelected":412,"corpusTotal":412}
$ echo $?
2

72 issue rows, 37 blocking, nine of them rules the engine could not decide — reported as failures because an undecided blocking rule is not a rule that passed. Measured on 2026-08-21 with @beyondnet/evolith-cli@1.3.2; it takes ~2 s. Full capture, all 72 rows and both denominators.

Quick Start · PR gate · What it governs · Documentation · Contribute · Interactive atlas

The idea, in one line

Every architecture linter paints the rules it never ran green: coverage and compliance end up the same colour. Evolith publishes the denominator and refuses to round it up. skipped is a first-class outcome; a blocking rule that ends skipped fails the run (invariant with its own test); and exit codes are a taxonomy: 0 pass · 1 the tool failed · 2 the gate blocked · 3 you invoked it wrong.

And we apply it to ourselves. Three things this front page could keep quiet and does not:

• The two engines do not cover the same ground today. --engine opa evaluates 133 of 159 rules; the default native evaluator evaluates 41 and skips 118, on the same repository. They are held to agreement over facts in CI, not over coverage — that part is by design; that the default command never says so is not (#628). This page uses --engine opa everywhere.
• Two infrastructure rules are in no denominator. The loader rejects three ruleset files from its own corpus, and as of 1.3.2 it no longer even says so on stderr (#575).
• The file count and the rule count answer different questions. The tree carries 182 *.rules.json files, of which four declare a non-ruleset schema and contribute no rules by design — they are named in every report, not dropped. That leaves 178 packs with 413 rules. The published CLI carries its own snapshot: 177 packs, 412 rules. evolith rulesets prints what your installation loads, pack by pack.

Full audit of our own claims: pending items, 2026-08-16.

Quick Start

Requirements: Node ≥ 18 for the CLI, ≥ 20 for the MCP server · no database, no server, no Docker. Installation is verified in CI on Linux; macOS and Windows are not covered by that gate.

npm install -g @beyondnet/evolith-cli   # or use `npx -y @beyondnet/evolith-cli` and install nothing

evolith init --name my-sat --yes        # configures the CURRENT directory; --name only names the project
evolith validate --engine opa           # same directory, no `cd` needed

evolith rulesets                        # what YOUR installation loads, pack by pack
evolith validate --engine opa --select rulesets/acl/anti-corruption-layer.rules.json
evolith validate --engine opa --phase qa
evolith adr create                      # manage Architecture Decision Records

--engine opa evaluates with the compiled Rego bundle; without the flag it runs the native evaluator, which covers less today. To create a new directory instead, pass it positionally: evolith init my-sat --yes. With --format json it never prompts and prints exactly one JSON object on stdout; --dry-run writes nothing.

Expect findings on the first run. A freshly configured repository is a baseline, not a pass: many rules assume a fuller layout. To start from what you have actually adopted, use --select with the refs evolith rulesets prints; bringing the default to zero is tracked as GT-571 on the gap board.

Configuration lives in evolith.yaml, which init writes for you:

coreRef: { version: "1.0.0", path: "../evolith" }
product: { name: my-sat, type: enterprise-application, phase: phase-0 }
tools:   { runtime: nodejs, architecture: clean, ci: github-actions }

What it inspects: repository structure, CI workflows, manifests and governance artifacts — not your code's AST. That makes it largely language-agnostic; the subset that looks at dependencies and linters assumes a Node/TypeScript repository. Reference: Evolith CLI hub · Quickstart guide

Use it as a PR gate

- uses: beyondnetcode/evolith_arch32@v1
  with:
    fail-on-violation: true

Outputs compliance-status, violations-count, issues-count, exit-code and report-path. error and invalid-input mean the repository was not evaluated — they are not weaker forms of non-compliant, and the job summary says so in words.

As live context for an AI agent, over stdio:

{ "mcpServers": { "evolith": { "command": "npx", "args": ["-y", "@beyondnet/evolith-mcp"] } } }

Why not ArchUnit, Conftest or dependency-cruiser

Use them. They are good, and Evolith replaces none of them.

Against dependency-cruiser, the scope is broader (phase gates, architecture styles, security standards) and it keeps why each rule failed.

What is NOT built yet, so you do not have to find out: the "LLM proposes, a deterministic verifier disposes" half is a documented direction, not shipped behaviour. No command in the installed CLI reaches an LLM.

What it governs

Eight architecture styles (we call them topologies) across five axes. The same rules follow you when the monolith splits into services.

On top runs a free, MIT library: in this tree, 142 ADRs, 178 ruleset packs carrying 413 rules across 182 files, and 50 phase schemas, plus the five SDLC phases (Discovery → Design → Construction → QA → Delivery) and the gates that block the move from one to the next. Those three counts are measured and verified by CI on every PR. What your installation actually evaluates is printed by evolith rulesets: today, 177 packs with 412 rules, 188 of them able to fail a run. The only paid product will be Evolith Tracker, not yet launched.

_{Open the interactive viewer — drag to pan, scroll to zoom}

Product ecosystem

Who it is for:

• Engineering teams that want their ADRs enforced in CI, not reviewed by hand.
• Platform teams blocking non-conformant artifacts before production.
• AI-assisted development that needs the agent to validate its output against the same rules.

Adoption, unvarnished: 1,109 npm downloads last month (2026-07-21 → 2026-08-19), no confirmed external adoption. The repository governs itself, and that is all the evidence there is.

Network egress

Local-first: the CLI, the rules, the OPA policies and the evaluation Core run on your machine, and your code is never uploaded. There is exactly one outbound integration (GeminiProvider, Google Gemini API), it is off by default, and no command in the published CLI reaches it today. The tarballs on the registry predate that hardening: treat the published GeminiProvider as ungoverned and do not wire it up.

Full disclosure — sub-processors, credential, limits, redaction, what leaves and what does not, and the known limitations of these controls: Network Egress and Data Handling. Report an egress defect there, never in a public issue.

Documentation

Contributing

Start here: issues that are good for a first contribution — most touch a single file. Unsure before opening a PR? Discussions.

Three ways to contribute without writing TypeScript: correct a count that disagrees between docs and code · translate a hub into Spanish · add a rule to src/rulesets/.

Before the PR: Contribution Guide · Security Policy · AGENTS.md · CHANGELOG

License

Released under the MIT License.