Rulebearing

Deterministic guardrails for agentic engineering. Architecture rules your coding agent cannot talk its way past, with the fix attached to every finding, for TypeScript (TypeScript 7 included), JavaScript, .NET and Python in one rule file.

Status: waves 1 and 2 built, first release in progress. Wave 1, the drop-in for repositories already using dependency-cruiser, builds and runs from source and supports TypeScript 7 (how it is proven); its v0.1.0 release is being cut. Wave 2, .NET and Python, is built, with its nightly evidence and the NuGet and PyPI packages still to finish. If the problem below is yours, star or watch the repository; the roadmap says what lands when.

The problem with telling an agent the rules

Most teams working with coding agents have written the same file. It is called AGENTS.md or CLAUDE.md, it started as a page, and it is now forty kilobytes of prose rules, each one recording a mistake that already cost something. "Apps only talk to each other over HTTP." "Nothing in Domain may reference Infrastructure." "Features must not import each other."

Prose rules do not hold. Not because agents ignore them, but because of how agents actually work:

• They follow what fails fast and locally. A rule that fails only in CI after merge documents drift; it does not prevent it. A rule the agent never sees fail is not a rule.
• They act on the message, not the rule. Given from -> to and a line number, an agent fixes the import. Given a rule name, it goes searching. Given a paragraph in a Markdown file, it does what the paragraph mostly seems to say.
• They take the cheapest path to green. Widen a pattern, raise a budget, add an exception. Every one of those is a legitimate edit unless something refuses it.
• They write rules when asked, and the rules match nothing. In the monorepo this project comes from, four architecture rules sat for months matching zero files, reading as standing fences and guarding nothing.

The tools that could enforce these rules already exist, one per language, and none of them was built with an agent as the reader of its findings. A finding names two files and no line. The fix-it advice lives in a comment only one output mode prints. Asking "may this file import that one" costs a thirteen-second full run. And a rule that matches nothing passes.

What a deterministic guardrail looks like

Rulebearing turns the paragraph into a fence the agent runs into before it finishes its turn, with the way out attached.

# rulebearing.yaml
rules:
  dependencies:
    forbidden:
      - name: no-cross-app-imports
        comment: "Apps share only packages/* and HTTP. adr:0003"
        fix: "Call the other app over its API, or move the shared code into packages/*."
        severity: error
        from: { path: "^apps/([^/]+)/" }
        to:   { path: "^apps/([^/]+)/", pathNot: "^apps/$1/" }
        examples:
          forbidden: ["apps/web/src/x.ts -> apps/worker/src/y.ts"]
          allowed:   ["apps/web/src/x.ts -> packages/format/src/index.ts"]

Every part of that rule is load-bearing for an agent:

And when it fires, the agent gets something it can act on rather than a paragraph to interpret:

// rulebearing cruise --affected HEAD --output-type agent   (shape, illustrative)
{
  "violations": [{
    "id": "RB-4f2a9c1e",
    "rule": "no-cross-app-imports",
    "from": "apps/web/src/checkout/total.ts", "line": 3, "column": 1,
    "to": "apps/worker/src/pricing/index.ts",
    "fix": "Call the other app over its API, or move the shared code into packages/*.",
    "decision": "adr:0003"
  }],
  "inspected": { "files": 212, "modules": 212 }
}

A line and a column. A stable id, so "fix RB-4f2a9c1e" means the same thing on every run. The fix text. The decision it serves. A receipt of what was looked at, so "the check passed" is distinguishable from "the check looked at nothing". Token-budgeted with --max-findings, grouped by rule, no prose to parse.

Inside the loop, not beside it

A check the agent has to remember to run is a check that gets skipped. Rulebearing installs itself into the loops agents already run.

rulebearing hooks install --claude-code

That writes three hooks for Claude Code:

For pipelines and editors, the same rules and the same graph feed a pre-commit hook, one test case per rule in xUnit, NUnit, pytest or vitest, an ESLint rule that flags a boundary violation inline as the agent types, a Roslyn analyzer that fails dotnet build with the line, an MCP server so the architecture is available as tools rather than as a document the agent may not have read (rulebearing hooks install --claude-code --mcp), and a language server that shows each finding in the editor with its fix as the quick-fix title (serve.md).

Before it writes the import, the agent can ask:

rulebearing can-import apps/web/src/x.ts apps/worker/src/y.ts   # yes or no, and which rule decides, in milliseconds
rulebearing place --imports a,b --imported-by c --language ts    # where would a new module with these edges be legal
rulebearing impact src/Domain/Entities/Order.cs                  # what depends on this, what rules mention it, is it on a cycle
rulebearing explain no-cross-app-imports                         # the rule, its fix, what it matches today, the first ten edges

Guardrails on the guardrails

An agent asked to "stop Domain from reaching Web" will write the regex. The tool makes that safe rather than trusting it.

• A rule that matches nothing fails. Every rule of every kind, by default. The four dead rules mentioned above would have failed the pull request that orphaned them. This check is what the tool is named for: a rule that bears nothing is not a rule.
• A rule needs a decision. --require-comment-token refuses a fence that does not name the decision record it serves.
• A rule ships with proof. examples are required for a new rule and rulebearing test runs them against a synthetic graph, so a rule cannot merge without evidence that it fires.
• propose drafts the rule from evidence. Give it globs, a selector or one forbidden edge, and it returns the narrowest rule that covers it with the current match counts on both sides. The agent starts from that, not from a blank regex.
• config lint catches the mistakes agents make by hand. A pattern that matches nothing, a rule shadowed by an earlier one, an allow-list that admits everything, a predicate the language cannot answer.
• Ratchets only fall. A budget file records a ceiling that count --write may lower and refuses to raise. An agent clearing a check by editing the budget gets a failure, not a green build.
• Runs are hermetic. No network, no code execution outside a sandboxed config evaluator, deterministic output. The agent's local run and CI agree byte for byte, and attest writes a receipt CI verifies, which answers the recurring review question on agent-authored pull requests: did it actually run the check it says it ran.

One rule file for the whole repository

The rules above work the same way whether the edge is a TypeScript import, a .NET type reference read from the compiled assembly, or a Python import. Rulebearing is a strict superset of dependency-cruiser for TypeScript and JavaScript and of ArchUnitNET for .NET, with import-linter's contract kinds mapped one to one for Python. Every rule attribute, option, flag and reporter of the incumbents is accounted for; nothing is dropped, and the claim is proven by running their own test suites against this tool as required checks (conformance).

So a repository with a TypeScript front end, a .NET service and a Python pipeline keeps one rule file, one gate, one graph other scripts can read, and one answer to "may this file import that one". If you already have a .dependency-cruiser.js, it runs unchanged on day one.

Try it

Now, from source. Wave 1, the TypeScript drop-in, is built: dependency-cruiser's whole rule language and option set, both configuration formats, the wave 1 reporters, and the agent commands. It matches dependency-cruiser with zero differences on dependency-cruiser's own repository, langfuse and FluidFramework (conformance). Until the first release is published:

cargo build --release                               # target/release/rulebearing
./target/release/rulebearing init                   # reads the repo and proposes rules that already pass
./target/release/rulebearing cruise src             # or: replace `depcruise` with it in your pipeline
./target/release/rulebearing hooks install --claude-code

From the first release, v0.1.0. In a TypeScript repository:

npm install --save-dev rulebearing
npx rulebearing init
npx rulebearing cruise --output-type agent

or in GitHub Actions, uses: benbahrenburg/rulebearing@v0.1.0 with args: --config rulebearing.yaml src. A repository already on dependency-cruiser keeps its configuration: replace depcruise with rulebearing cruise and change nothing else, or run rulebearing adopt for a baseline, a CI step and one green pull request.

The guides: configuration, rules, reporters, the command line and Rulebearing for coding agents.

.NET and Python (wave 2). The .NET extractor reads the compiled assemblies and their portable PDBs, so build first; the Python extractor reads the source, without running an interpreter. Once the wave 2 release is published, install with dotnet tool install -g Rulebearing or pip install rulebearing; from source, use ./target/release/rulebearing as above.

dotnet build -p:DebugType=portable                  # .NET: the assemblies and PDBs the extractor reads
rulebearing init                                    # finds the solution or pyproject.toml and proposes rules that pass
rulebearing cruise --output-type agent

Existing rules come across as a command, not a rewrite, with the original kept as a comment beside each rule:

rulebearing import archunit tests/Architecture.Tests --out rulebearing.yaml      # ArchUnitNET or NetArchTest chains
rulebearing import import-linter --from pyproject.toml --out rulebearing.yaml     # or .importlinter, setup.cfg
rulebearing import eslint --from eslint.config.js --out rulebearing.yaml          # no-restricted-paths, eslint-plugin-boundaries

The same rules run as tests in the suite you already have: Rulebearing.TestAdapter for xUnit, NUnit, MSTest and TUnit, pytest-rulebearing, and rulebearing/vitest, one test per rule with the fix in the failure message; eslint-plugin-rulebearing flags a boundary in the editor. ArchUnitNET's predicates are keys of element rules, with each key's meaning in every language in the generated reference.

TypeScript 7

TypeScript 7 is supported. Rulebearing parses with oxc and resolves with oxc_resolver; it never loads the typescript package, so the compiler version a repository installs does not matter to it. What TypeScript 7 changes for an extractor is the tsconfig, and that is what is tested:

dependency-cruiser cannot load TypeScript 7 itself (its manifest accepts typescript >=2.0.0 <7.0.0), so a repository that keeps it beside Rulebearing installs TypeScript 6 for it, as langfuse does with @typescript/typescript6. Two resolutions follow TypeScript rather than dependency-cruiser, whose tsconfig-paths 4.2.0 departs from the compiler once baseUrl is gone: inherited paths resolve (dependency-cruiser leaves them unresolved), and a bare src/x with no baseUrl stays unresolved (dependency-cruiser resolves it against the tsconfig's folder). module: amd, umd, system and none, which TypeScript 7 removes, stop a run with exit 2 unless tsPreCompilationDeps is true. The reasoning is ADR-0040.

Roadmap

Five waves of part-time work, TypeScript first because that is where the largest set of validation repositories is.

Beside the waves, five tracks. Two run alongside waves 1 and 2. The other three add languages and incumbents once wave 2 is done, under the same promise: each incumbent's own test suite becomes a conformance gate before its row says Parity.

This is measured, not believed. From wave 1, six signals are tracked on the repositories where agent-authored pull requests can be seen: the share that pass the boundary check on their first CI run (target above 90%), the median turns from a violation to green (target one), rules caught by the authoring guardrails, Stop-hook latency, the share of rules carrying fix text, and budget raises merged (target zero). If the first two do not move, the agent surface is cut back to the reporter and the hook, and what remains is a faster dependency-cruiser that also covers .NET and Python. Saying that in advance is cheaper than discovering it later.

Validated nightly against real repositories

Every night the repositories in testbeds/manifest.yaml are cloned at a pinned commit and their incumbent tool runs with its own configuration: dependency-cruiser, NetArchTest, ArchUnitNET or import-linter. From wave 1 Rulebearing runs beside it, and the table shows whether the two agree to the finding and how long each took (testbeds/README.md). The latest full run is on the testbeds-results branch; the table below is refreshed from it by pull request. In it, failed means the incumbent itself reports failing tests or broken contracts at the pinned commit, and error means the repository does not build there. From wave 2 the table has two more kinds of row with a Rulebearing time and no incumbent: the greenfield init proof on microsoft/semantic-kernel and microsoft/autogen, ok when the configuration init writes cruises back with exit 0 and matches its committed fixture, and the scale rows n8n-io/n8n, grafana/grafana, elastic/kibana, dotnet/aspnetcore, jellyfin/jellyfin and home-assistant/core, timed in the scale table below.

Rows: 52; error 2, failed 4, idle 19, ok 27. Zero-diff and the Rulebearing timings start in wave 1.

Scale: wall-clock and peak memory on large repositories

Each night the scale repositories are built at their pinned commits, given the configuration rulebearing init writes, and cruised three times; the median run's wall-clock time and peak resident memory are below, aspnetcore read both from its compiled assemblies and from source, with the Stop hook's p95 on aspnetcore (testbeds/bench/scale_table.py, plan 0003 Step 24). The runner is GitHub's standard Linux runner: 4 CPUs, 16 GB of memory. A row more than 20% slower or larger than the previous published one, on the same commit, fails the night; a row that did not complete keeps its last measurement, marked. The nightly rewrites this table by pull request.

Stop hook on dotnet/aspnetcore in source mode: p95 1.818 s over 200 edits on 4 CPUs, run 38109169995.

Oracle agreement: migrated rules against the incumbent

For the .NET and Python oracles the question is sharper than whether the tools agree on a graph: does a team's existing rule set, migrated with rulebearing import archunit or rulebearing import import-linter, give the verdict the incumbent gives, test by test and contract by contract. The harness in testbeds/oracles runs both sides at the pinned commit and writes one file per repository; stays is a test or contract the importer leaves with the incumbent (a custom predicate or contract type), not imported one it could not translate, each with its reason in the file. The table is generated from those files by python3 testbeds/oracles/table.py --readme README.md, and CI fails when it is stale.

Built the way it asks you to build

This repository holds itself to the bar it proposes for yours. Every gate below was required and green before the first extractor line was written, so the extractors were built against the finished harness rather than alongside it.

The reasoning behind each is a numbered decision record in docs/adr/, and the repository's own rulebearing.yaml cites them the way it asks yours to.

Repository map

Building

cargo build --release          # target/release/rulebearing
cargo test --workspace --all-features
cargo lint                     # all four languages, plus documentation links
cargo mutants --package rb-model --package rb-rules --package xtask
git config core.hooksPath .githooks   # formatting, links and tests before each commit and push

Contributing and licence

CONTRIBUTING.md is short and points at the four documents that govern everything else. One person builds this in evenings; the reviewer of record is a pair of upstream test suites anyone can run, and a second maintainer is the goal by the end of wave 2.

MIT. Security reports go through the security policy.