sliderule

# SlideRule

<!-- mcp-name: io.github.andypgray/sliderule -->

[![CI](https://github.com/andypgray/sliderule/actions/workflows/ci.yml/badge.svg)](https://github.com/andypgray/sliderule/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/andypgray/sliderule?label=openssf+scorecard)](https://scorecard.dev/viewer/?uri=github.com/andypgray/sliderule) [![NuGet](https://img.shields.io/nuget/v/SlideRule.Cli?logo=nuget&label=nuget)](https://www.nuget.org/packages/SlideRule.Cli) [![NuGet downloads](https://img.shields.io/nuget/dt/SlideRule.Cli?label=downloads)](https://www.nuget.org/packages/SlideRule.Cli)

SlideRule is a .NET architecture checker that enforces one C# spec and renders the same rules for coding agents.

A long-lived codebase has layers, boundaries and rules. They live in a few heads, no build step checks them, and the diagrams drift. A change can cross a boundary and the build still passes. A coding agent makes that change quickly and plausibly, and it cannot see which walls are structural. SlideRule's answer is architecture-as-code. The rules become one C# spec, and the spec produces every surface this page names.

1. **Enforcement.** One checker passes or fails the rules at the command line, in CI, in the build and as named xUnit tests. A Claude Code hook runs the same check when an agent's turn ends.
2. **Agent context.** The rules render to a managed `AGENTS.md` block, per-directory rule cards and MCP query tools for coding agents.

SlideRule is pre-alpha. Minor versions can still change the spec API before 1.0. [Status](#status) describes what exists today and the versioning rules.

Install the tool, build your solution, and check it:

```bash
dotnet tool install -g SlideRule.Cli
dotnet build MyApp.sln
sliderule check MyApp.sln
```

`check` reads the rules from a spec project, a C# class library in your solution. On a solution with no spec project yet, `check` stops and reports that it found none. The [Getting started](https://github.com/andypgray/sliderule/blob/main/GETTING-STARTED.md) page makes one with the `SlideRule` package, and `sliderule graph` surveys a solution before it has any rules.

A rule is one statement:

```csharp
arch.Rule("layering/domain-independent")
    .Enforce(domain.MustNotReference(application, infrastructure, api))
    .Because("The Domain holds the quote and rate model the rest of the subsystem is built on; it stays free of the layers that depend on it so it can be reasoned about and tested on its own.")
    .Fix("Move the dependency out of Domain: define an interface here and implement it in the outer layer that needs it.");
```

That is the whole rule. It has an ID, a posture, a constraint, a reason and a fix. Here the posture is `Enforce`, and `domain` and the three layers it must not reference are declared earlier in the spec by namespace pattern. The rule is committed in the [clean-architecture example](https://github.com/andypgray/sliderule/tree/main/examples/Meridian.Quoting), and CI keeps `check` green against the codebase it governs. A rule can also cite the page its reason rests on and name a type to copy, as [Writing specs](https://github.com/andypgray/sliderule/blob/main/WRITING-SPECS.md) shows.

## When an agent breaks a rule

Rules like the one above govern this repository too. One of them keeps the CLI off stdout, because the MCP server speaks JSON-RPC over that channel. Suppose an agent adds a progress printer to the CLI and reaches for `Console.WriteLine`. When it tries to end its turn, the Claude Code `Stop` hook in [`hooks/`](https://github.com/andypgray/sliderule/tree/main/hooks) runs `check` over the working tree. The rule goes red, and the hook blocks the stop with this report on the agent's stderr:

```text
FAIL cli/no-stdout — The Host layer must not use `Console.Out`, `Console.Write()` or `Console.WriteLine()`.
  because: Stdout is a protocol channel here — the MCP server speaks JSON-RPC over it and CLI output flows through System.CommandLine's console — so a direct Console write corrupts the wire and is invisible to the in-process tests.
  citation: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
  fix: Write CLI output through the command's InvocationConfiguration console; route server diagnostics to the logger or Console.Error.
  subject: 193 types, 1 generated
  src/SlideRule.Cli/Rendering/ProgressPrinter.cs:10 — SlideRule.Cli.Rendering.ProgressPrinter uses System.Console.WriteLine()
  src/SlideRule.Cli/Rendering/ProgressPrinter.cs:15 — SlideRule.Cli.Rendering.ProgressPrinter uses System.Console.WriteLine()
```

The report gives the rule, its reason, its citation, the fix and each offending line. The `subject:` line appears only when a rule's subject includes generated code, here 1 of its 193 types. The agent routes the output through the command's console instead, and the next stop is clean.

The [SlideRule on itself](https://github.com/andypgray/sliderule/blob/main/SELF-CHECK.md) page shows this repository's own spec on the other surfaces too, from the prose it renders to code scanning and the graph. It also explains how every excerpt on both pages is held to its source.

## The four postures

Every rule has one of the first two, and every scope one of the last two.

| Posture | What it is | What fails |
|---|---|---|
| `Enforce` | the law | every violation, even ones predating the rule |
| `Migrate` | a ratchet over a counted baseline | new violations; baselined sites stay quiet |
| `Quarantine` | containment for a scope | a new reference into the scope |
| `Caution` | dragons for code new callers may use | never fails; a change touching it warns |

`Migrate` is for a rule the code does not keep yet. `sliderule baseline init` records the rule's current violations, and any new violation fails from then on. As sites are fixed, `sliderule baseline accept-reductions` shrinks the baseline, and once it is empty, `status` suggests promoting the rule to `Enforce`.

A scope marks code that needs care. Its dragons are notes on why the code is fragile and how to call into it. `render` puts them on a card in the scope's directory. `Quarantine` also records the references into the scope on a baseline, and fails any new one except through the surface `BoundaryOnlyVia` names. Both kinds of scope warn when a change touches them, given `check --diff-base <ref>`. The [Writing specs](https://github.com/andypgray/sliderule/blob/main/WRITING-SPECS.md) page shows each posture in code, and [Operating SlideRule](https://github.com/andypgray/sliderule/blob/main/OPERATING.md) follows a ratchet from capture to promotion.

The three postures after `Enforce` each answer a way a coding agent goes wrong on an established codebase. `Enforce` is the law the code already keeps, and a change that crosses it fails wherever the check runs. The [Meridian example](https://github.com/andypgray/sliderule/blob/main/examples/Meridian/README.md#three-ways-an-agent-goes-wrong-here) walks three of those ways on real output.

- An agent copies the majority pattern, the statistical prior. Six of Meridian's eight controllers open a `SqlConnection`, so inline SQL reads as house style and an agent writes its next controller the same way. `Migrate` answers it. The rendered context calls that pattern debt, in words the agent reads before it writes.
- An agent tidies away a gateway, the helpful refactor. A public type inside a module invites a direct call that skips the gateway in front of it. A `Quarantine` scope makes the gateway the only sanctioned way in.
- An agent corrects structural weirdness. A check-digit table that skips values looks like a bug, and making it contiguous breaks every real container number. The dragons on a `Quarantine` or `Caution` scope answer it. The card on that scope's directory explains what the code does, which part is structural, and how to call in.

## What one spec produces

Each target below reads the same model. Every violation report gives the rule ID, the generated rule sentence, the reason and the exact `file:line`. A rule's fix, citation and exemplar appear there too when it has them.

| Target | What it is |
|---|---|
| [`sliderule check`](https://github.com/andypgray/sliderule/blob/main/CLI.md#check) | one pass-or-fail verdict for the command line and CI |
| [`check --sarif`](https://github.com/andypgray/sliderule/blob/main/CLI.md#sarif) | that verdict as SARIF 2.1.0, for code scanning |
| [xUnit adapter](https://github.com/andypgray/sliderule/blob/main/src/SlideRule.Xunit/README.md) | every rule an individually named test |
| [build analyzer](https://github.com/andypgray/sliderule/blob/main/src/SlideRule.Analyzers/README.md) | a broken rule as a squiggle in the editor and a compiler warning in the build |
| [`sliderule render`](https://github.com/andypgray/sliderule/blob/main/CLI.md#render) | the managed `AGENTS.md` block, per-directory rule cards, and the model as a JSON file |
| [`render --diagram`](https://github.com/andypgray/sliderule/blob/main/CLI.md#render) | two Mermaid diagrams: the projects and their references, and the spec's law |
| [`sliderule mcp`](https://github.com/andypgray/sliderule/blob/main/CLI.md#mcp) | `arch_check`, `arch_status`, `arch_explain`, `arch_context`, and `arch_graph`, plus a `derive_spec` prompt |
| [`sliderule hook`](https://github.com/andypgray/sliderule/blob/main/CLI.md#hook) | `check` when a Claude Code agent's turn ends; a red rule blocks the stop |

The adapter's failure text is byte-identical to the CLI's. The two share one renderer, and a product test pins them equal. The managed block plus `sliderule explain` are also the generated architecture documentation, written for agents first and readable by people. The [SlideRule on itself](https://github.com/andypgray/sliderule/blob/main/SELF-CHECK.md#the-prose-it-generates) page shows the gate that keeps it current.

The [Coding agents](https://github.com/andypgray/sliderule/blob/main/