Module rules 

The rules module: a rule, and everything the repository can show that proves it.

A rule of this repository is a Markdown object under the rules section with YAML front matter: an id, a version, a class (blocking or advisory), a statement, and — since the proof relation became load-bearing — an x-majordomus block naming what enforces it. This module is the one typed reading of that object, and the one place the repository decides what a rule’s proof amounts to.

Why this exists rather than another list

Before it, “is this rule enforced?” was answered by o.metadata.get("x-majordomus") .is_some() — a green badge for the presence of a YAML key. A rule could name test/cases/28_no_hardcoded_values.sh after that case was deleted and still read as enforced on every surface that asked. The proof graph here answers the question the badge pretended to: the named validator is in the tree, the named cases are in the tree, a runner owns them, a run of them was recorded, and that run is not older than what it is about.

What it does not do

It does not re-implement evidence. crate::evidence already binds a test path to the executions recorded against it and already decides, with ProofState, what a passing run from an older commit is worth. A rule’s test-level proof is that vocabulary; this module joins rules to it rather than inventing a second one. Nor does it dispatch: the portable shell layer’s lib/doctrine.sh runs the validators, and scripts/ci/ rule-proof-check is the gate. This is the reading all of those project from.

The two enforcement modes

The canonical front matter allows exactly two shapes, and the distinction is not cosmetic:

• dispatched — the block names a validator, which lib/doctrine.sh calls at run time. It carries category, exit_code and enforced_by with it; a half-declaration (a category without a validator) is a defect the loader refuses rather than a rule with a missing field.
• gated — the block names tests and no validator. Nothing dispatches it; the behavioural cases are what prove it, and a CI gate is what runs them.

Either mode names at least one test. A blocking rule that names neither is Unproven, which is the state this module exists to make visible rather than absent.

Example

The vocabulary, without a repository: a class is read rather than guessed, the mode is whatever the block names, and every state ranks and says what it means.

use majordomus_cli::rules::{Class, Mode, RuleState};

assert_eq!(Class::parse("blocking"), Class::Blocking);
assert_eq!(Class::parse("strict"), Class::Unknown);
assert_eq!(Mode::Reviewed.label(), "reviewed");
assert!(RuleState::Proven < RuleState::Dangling);
assert!(!RuleState::Gated.passing());

Structs

Coverage

How much of the rule corpus carries each part of a proof.

Enforcement

The enforcement block of a rule, read from x-majordomus.

Finding

One rule whose declared class the proof does not support.

RuleDefinition

One rule, as the repository canonically declares it.

RuleProof

One rule, joined to everything the repository can show about it.

RulesReport

The whole rule corpus, verified.

TestProof

One test a rule names, joined to what was recorded against it.

ValidatorRef

The validator a dispatched rule names, and whether anything defines it.

Enums

ArtifactKind

What a path a rule names actually is, decided by what drives it rather than by where it sits.

Class

What a rule declares about how strongly it binds.

Mode

How a rule is enforced, as its own front matter declares it.

RuleState

What the repository can say about one rule’s proof, as a whole.

RulesVerdict

What the whole corpus can be said to prove, in one word, before any number is read.

Constants

GATES_PATH

Where the CI model of this repository is declared. Read to answer “which gate runs the case this rule names”, so that a rule’s gate coverage is derived from the planner’s own input rather than restated here.

RULES_URI

The URI under which the whole rule verification report is read as an MCP resource.

Functions

definitions

Every rule the index holds, as a canonical definition.

report

Join every rule of the index with the tree and the ledger, and decide, per rule, what the repository can honestly say.