Evolith Arch32

npm install -g @beyondnet/evolith-cli
evolith init --name my-sat --yes
evolith validate --engine opa

Quick Start · Interactive architecture atlas · How we audit our own claims

What just happened

That third command evaluated this repository's own rule corpus against a freshly initialized satellite, using the compiled Rego bundle. This is what @beyondnet/[email protected] printed in a container with nothing but Node installed:

**Status:** failed
**Rules Checked:** 133
**Rules Skipped:** 26
**Rules Errored:** 0
**Rules Total:** 159

### Issues
| Rule Id | Severity | Category | Title | Blocking |
| --- | --- | --- | --- | --- |
| ACL-01 | MUST | anti-corruption | Schema Validation Before Ingestion | YES |
...
| SEC-INJ-01 | MUST | security | Blocking rule did not run: No shell exec with user input | YES |
| SEC-INJ-02 | MUST | security | Blocking rule did not run: Parameter allowlists for scaffold tools | YES |
| SEC-PATH-01 | MUST | security | Blocking rule did not run: Path input sanitization | YES |
...
└  ❌ Validation failed. See the errors above.

$ echo $?
2

Every line above is the tool's own, character for character. The ... marks issue rows cut for length and nothing else -- there are 72 in all, 37 of them blocking. The run also opens with three [Nest] WARN Skipping non-standard ruleset lines: three ruleset files ship in the tarball that the shipped validator's own schema rejects. That is a real defect, and a README arguing that unevaluated is not the same as passing does not get to quietly drop it from the capture.

The Core carries 412 rules; the 159 above is what this one satellite's run selected from them. Two different denominators, and a report that blurred them would be the exact defect this project exists to stop.

Nine of those 37 blocking issues are rules that were skipped. Not rules that failed -- rules the engine could not decide, reported as failures because an undecided blocking rule is not a passing one. Among them are SEC-INJ-01, SEC-INJ-02 and SEC-PATH-01.

This is the whole idea. Every architecture and policy linter silently passes the rules it never evaluated, so coverage and compliance produce the same green. Evolith publishes the denominator and refuses to round it up:

• The compiled bundle declares which rule ids it can decide, and skipped is a first-class outcome rather than the absence of a violation.
• A blocking rule that ends skipped fails the run. That invariant has its own test, written against the code that did not have it: blocking-skipped-invariant.spec.ts.
• Two engines -- a native TypeScript evaluator and Rego/WASM -- must agree on fixtures, or CI fails.

Exit codes are a taxonomy, not a boolean: 0 pass, 1 the tool failed, 2 the gate blocked, 3 you invoked it wrong. A run that could not produce a verdict never reports one.

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 is not a replacement for any of them.

Where it is genuinely different: it reports what it could not evaluate. None of the tools above distinguishes "this rule passed" from "this rule never ran" in their exit status.

What is not built yet, so you do not have to discover it: the "LLM proposes, a deterministic verifier disposes" half is a documented direction, not shipped behaviour. No command in the installed CLI reaches an LLM. See Network Egress and Data Handling.

Menu

• What is Evolith?
• Why Evolith?
• Core Concepts
• Product Ecosystem
• How It Works
• Architecture Overview
• Main Components
• Quick Start
• Questions & Answers
• Network Egress and Data Handling
• Documentation
• Use Cases
• Roadmap
• Contributing
• License

What is Evolith?

Evolith is an executable architectural governance framework. It encodes how software is built — across multiple architecture styles — as verifiable rules, ADRs, and phase gates that teams, platforms, and AI agents can actually run.

Governance in Evolith is not a document. It is an operational capability exposed through a CLI, an MCP server, and a REST API.

Why Evolith?

Most projects accumulate ADRs and architecture docs that nobody reads and nobody enforces. Systems drift. Decisions are forgotten. Consistency breaks silently.

Evolith makes governance executable:

• Rules are validated automatically, not reviewed manually.
• Phase gates block progression until quality criteria are met.
• AI agents and CI pipelines consume the same governance artifacts as humans.
• Architecture decisions are traceable from ADR to production code.

Core Concepts

Full details: Core Concepts · Topologies

Product Ecosystem

Evolith ships as a suite of coordinated products built on a common foundation.

How It Works

Developer / AI Agent / External Trigger
        │
        ▼
  Evolith CLI  ──────────────────────────────► MCP Server
  (local enforcement)                        (AI agent context)
        │
        ▼
   Core API  ────────────────────────────►  Evolith Tracker
  (remote governance)                        (business lifecycle)
        │
        ▼
  Agent Runtime ───────────────────────────► Hermes (adapter)
  (agentic mediation, Ports & Adapters)       (.harness · OPA · Tracker · Memory)
        │
        ▼
  Rulesets · OPA Policies · ADRs · Blueprints
  (the shared governance artifacts)

1. Evolith CLI validates code locally against rulesets and runs phase gates.
2. Core API exposes the same governance remotely for CI pipelines and orchestrators.
3. MCP Server feeds governance context to LLMs and AI agents in real time.
4. Agent Runtime orchestrates Core capabilities through a Ports & Adapters model — Hermes is one replaceable adapter.
5. Evolith Tracker coordinates the business side — who owns what, what's funded, what ships when.

All products share the same artifacts defined in Evolith Core.

_{Evolith E2E Product Vision - Open interactive viewer - drag to pan, scroll to zoom, fullscreen}

Architecture Overview

Evolith governs 8 topologies across four axes:

Each topology has its own ADRs, OPA policies, AI rulesets, and UMS contracts. Systems migrate between topologies as the business scales — this is Progressive Architecture.

Full reference: Architecture hub · C4 Master Architecture

Main Components

evolith/
├── src/packages/agent-runtime/  # @beyondnet/evolith-agent-runtime — Ports & Adapters agentic layer
├── src/apps/agent-runtime-api/  # NestJS HTTP service wrapping the runtime (POST /v1/agent/handle)
├── reference/core/          # Engineering constitution and principles
├── reference/core/architecture/  # Topologies, blueprints, ADRs, and agent-runtime docs
├── reference/core/sdlc/    # SDLC phases, gates, standards, and glossary
├── product/products/      # Evolith CLI, Core API, MCP, Tracker, UMS
└── product/operations/    # SRE, infra, quality gates

Entry point for each area: Global Master Index

Quick Start

The npm package is @beyondnet/evolith-cli; it installs two equivalent bins, evolith (the documented name) and evolith-cli (compatibility). Both self-identify as evolith in --help.

# 1. Install the CLI
npm install -g @beyondnet/evolith-cli

# 2. Initialize the CURRENT directory as an Evolith satellite.
#    --name sets the project name written into evolith.yaml.
#    --yes runs without prompts (also implied by a non-TTY stdin or --format json).
evolith init --name my-sat --yes

# 3. Validate the satellite you just created — same directory, no `cd` needed
evolith validate

# Validate a specific SDLC phase
evolith validate --phase qa

# Manage Architecture Decision Records
evolith adr create
evolith adr list

# Serve governance as live context for AI agents — the MCP server ships as a
# separate package (@beyondnet/evolith-mcp) with its own bin:
evolith-mcp serve

To scaffold into a new directory instead of the current one, pass it as the positional argument (or via --dir); --name only ever names the project, it never creates a directory:

evolith init my-sat --yes && cd my-sat && evolith validate

Machine-readable runs (--format json) never prompt and print exactly one envelope on stdout; a failed init exits non-zero. evolith init --dry-run writes nothing.

Expect findings on the first validate. A freshly initialized satellite is a baseline, not a pass: some rules still assume a fuller repository layout and report blocking findings on a phase-0 project. Reducing that to zero is tracked on the Gap Tracking Board (GT-571).

Evolith CLI is configured via evolith.yaml; run evolith --help for the current command list. Full reference: Evolith CLI hub

Questions & Answers

npm install -g @beyondnet/evolith-cli
evolith init --name my-sat --yes   # initializes the CURRENT directory
evolith validate                   # same directory, no `cd`

Full Q&A: 64 questions across 12 categories →

Network Egress and Data Handling

Evolith is local-first: the CLI, the rulesets, the OPA policies and the stateless evaluation Core all run on your machine, and your source files are never uploaded — evaluation happens where the code is. There is exactly one outbound integration in the corpus, it is off by default, and this is its complete disclosure.

What leaves the machine

• Through the governed IAssistantTransport seam: the request intent, the optional tool id, the request parameters, the dryRun flag, and the governed skill catalog (id and description only).
• Through the deprecated ILLMProvider seam (generateStructuredJson): the caller's system prompt and user prompt, verbatim.
• Both are secret-redacted before serialization, over 8 pattern classes: PEM private keys, JWTs, AWS access key ids, Google API keys, GitHub PATs, Slack tokens, Bearer tokens, and generic KEY/SECRET/TOKEN/PASSWORD assignments.

What does not leave the machine

Tenant id, product id, initiative id, workspace reference and requester identity are excluded from the transport payload by construction (data minimization), as are repository contents.

Observability

Every attempt — including refusals — emits one content-free JSON line prefixed [evolith:llm-egress] with provider, endpoint, purpose, outcome, byte and token counts, redaction count, HTTP status, duration and correlation id. Prompt and response content are never logged.

Human-in-the-loop

The intended wiring injects GeminiProvider as the IAssistantTransport of SupervisedAssistantClient, which is itself off by default and requires an explicit human approval before the transport is reached.

Other outbound traffic

• OpenTelemetry export from the CLI is off unless OTEL_ENABLED=true, and then it goes only to the collector you configure.
• Core API / MCP HTTP transport are servers you host; the CLI contacts a remote Core only when you configure one.
• No telemetry, analytics or licence check is phoned home by any surface.

Honest current state

• Redaction is pattern-based, not a DLP control: it materially reduces accidental credential egress, it does not guarantee absence.
• The header, timeout, budget, redaction and schema-validation controls are covered by unit tests with an injected fetch; they have not been exercised against the live Google endpoint.
• The timeout and budget values are inherited from the repository's own CI reviewer and are not tuned for large interactive prompts, which fail closed rather than degrade.
• No command registered in the shipped CLI reaches this provider today, so a default CLI install performs no LLM egress at all.
• The npm tarballs currently published predate this hardening; the controls above are on develop and reach the registry with the next release, tracked as GT-570 on the Gap Tracking Board.

Report a suspected egress or disclosure defect through the Security Policy, never in a public issue.

Documentation

Use Cases

For engineering teams Enforce architecture decisions automatically. Run phase gates in CI. Keep ADRs alive and traceable.

For platform teams Query governance remotely via Core API. Integrate rulesets into deployment pipelines. Block non-compliant artifacts before they reach production.

For AI-assisted development Feed governance context to LLMs through MCP. Let AI agents validate their own outputs against architecture rulesets before committing.

For growing products Start with a modular monolith. Migrate to distributed modules or microservices when the business demands it — Evolith tracks the transition and enforces consistency at every step.

Roadmap

See the active gap tracking board for current priorities and open items:

• Gap Tracking Board
• Opportunities Board
• Maturity & Gaps hub

Contributing

Read these before opening a PR:

• Contributing Guide
• Security Policy
• AGENTS.md — conventions for AI agent contributors
• Repository Taxonomy — what goes where

License

Published under the MIT License.