Skip to content

majordomus rules

The effective rule set, vendored baseline plus project rules.

The effective rule set, vendored baseline plus project rules.

  • generated-output-mutating
  • rules
  • --json

Every subcommand is read-only except vendor update, which replaces the vendored baseline with the tool's shipped package and refuses a hand-edited copy unless forced.

Syntax

majordomus rules <list|show <id>|vendor status|vendor diff|vendor update [--force]> [--json]

Lifecycle

  1. Set up
  2. Begin
  3. Work
  4. Verify
  5. Conclude
  6. Inspect

Other commands at this stage:doctor, watch, history, search, doctrine, version, knowledge, bench.

Reads

  • .ai/repo/rules/
  • share/standard/majordomus/

Writes

  • .ai/repo/rules/vendor/majordomus/
  • .ai/local/state/ledger.jsonl

Exit codes

Only the codes this command can produce. The full contract is on the commands index.

  • 0 ok
  • 2 usage
  • 10 contract unmet
  • 11 drift found
  • 12 missing artifact
  • 13 internal error
  • 15 refused

The effective rule set, resolved

rules reads the vendored baseline and the project rules as one additive set, resolves their dependencies in a deterministic order, and shows any one of them whole.

The resolved order

installed
yes

Given this repository

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Run

$ majordomus rules list

Output contains

  • ^majordomus.scope-integrity +v1 +blocking +vendor:majordomus

exit 0

Every active rule, its version, its class and where it came from. A missing dependency or a cycle would refuse the whole set rather than apply part of it.

One rule, whole

installed
yes

Given this repository

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Run

$ majordomus rules show majordomus.scope-integrity

Output contains

  • ^id: majordomus.scope-integrity$
  • ^class: blocking$

exit 0

Front matter and body, from the file the repository carries. The rule is the document; the tool only finds it.

A rule that is not in the set

installed
yes

Given this repository

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Run

$ majordomus rules show nosuch.rule

Output contains

  • no rule 'nosuch.rule'

exit 12

Exit 12, a missing artifact, with the command that lists what exists.

Reference

The effective rule set: every active rule vendored under the repository's rules section plus every active rule the repository wrote, resolved as a dependency graph. Read-only in every subcommand except vendor update.

A rule is a Markdown file with YAML front matter. Its identity is the front matter's id and version, never the file name. docs/DOCTRINE.md describes the format, the x-majordomus block that binds a rule to a validator, and what is authoritative today.

$ majordomus rules list
majordomus.scope-integrity                 v1  blocking  vendor:majordomus enforced by check,finish,watch
majordomus.sessions-are-workers            v1  advisory  vendor:majordomus no validator; see the rule
project.english-only                       v1  blocking  project          no validator; see the rule
  • list [--json] prints the effective set in resolved order: identity, class, provenance (vendor:<name> or project), and whether the tool enforces it. A rule without an x-majordomus block is normative for whoever reads it and enforced by nobody, and the listing says no validator; see the rule rather than hiding it: the rule is normative for whoever reads it, and nothing checks it by machine.
  • show <id> prints one rule, front matter and body, with the repository-relative path it was read from as the first line. An id outside the effective set exits 12.
  • vendor status compares the vendored baseline with the package the running executable ships. It prints both revisions, then the manifest integrity of the vendored copy, then whether the two packages are the same.
  • vendor diff is the reviewable difference between the two, as a unified diff of the two directories. It exits 0 whether or not they differ; vendor status carries the exit code.
  • vendor update [--force] replaces the vendored baseline with the executable's package. The write is atomic: the new package is staged beside the target and swapped in. It never touches rules/project/.

Resolution fails closed. A missing dependency, a dependency on a deprecated rule, a cycle, one id@version claimed by two files, a project rule in the vendor namespace, malformed or incomplete front matter, an unknown front-matter key, or an x-majordomus block that names no validator, no enforcing command or no test — each stops list, show and every command that reads the set, with exit 10 and the reason. Nothing is applied partially. The order is deterministic: two runs agree, and every dependency is listed before the rule that depends on it.

The repository's vendored copy is authoritative. A newer executable reports a newer baseline through vendor status and vendor diff; it never applies one. update, doctor and check leave the vendored directory alone. The baseline changes only when vendor update is asked for.

A hand edit under vendor/ is detected. The package manifest names every rule file with its hash. A file whose hash no longer matches, a listed file that is absent, or a file present beside the manifest that it does not list, is reported by vendor status and refused by vendor update until --force.

exitmeaning
0the set resolves; the vendored baseline is current
2unknown subcommand or option; show without an id
10the set does not resolve, or the vendored copy fails its manifest
11vendor status: the executable ships a different package than the one vendored
12no rule with that id; nothing vendored yet; no rules section in this layout
13the executable ships no standard rule package: a broken install, not a repository fault
15vendor update refused over a hand-edited vendor directory (--force overrides)

test/cases/67_rule_dag.sh proves each refusal by mutation, and proves that a newer distribution's package is not applied until asked, that vendor update leaves rules/project/ byte for byte what it was, and that the resolved order is the same across runs.

Evidence

Every case below runs in CI on Linux and macOS. The site refuses to build if a public command has no behavioural case, no negative case, or no demonstration.

Guarantees this command carries