Crate majordomus_cli 

Majordomus control-plane CLI.

The library half of the executable. Dependencies flow inward toward the domain model:

cli / commands  ->  mcp (surface, protocol, stdio)  ->  index / model
                    discovery, metadata, repository, git  ->  model, error

Nothing below commands knows about clap; nothing below mcp knows about JSON-RPC; and the model knows nothing about either.

Re-exports

pub use index::Index;

pub use model::Diagnostic;

pub use model::Object;

pub use model::Provenance;

pub use model::Severity;

pub use repository::Repository;

Modules

about

What the executable says about itself, written once. The OpenAPI document’s info, the MCP initialize instructions, the HTTP index and the generated reference all read these sentences from here, so that no projection describes the surface in words of its own and none can drift from the others. Prose only: counts, URLs of a running server and anything else that is measured are added by the projection that measures it.

app

The application context every command starts from: the repository, its index, and the capability registry composed once from the builtin executables and the index. Commands differ in what they do with it; none of them builds it differently.

bench

The benchmark projection: every externally callable operation of the registry, as a target, derived and never listed by hand. A capability with a required benchmark policy is a target directly and through every transport its exposure declares; the inputs come from its input type’s BenchmarkCases; the transports’ own operations (initialize, tools/list, /openapi.json, …) are system targets declared once in system. Coverage is covered / required with a generated denominator; the runners time targets through the executor, a real loopback socket and a real child process; the results are a versioned document; the accepted baseline is compared against a policy that is data.

build_identity

Which commit an executable was built from, and whether that tree was dirty: the decision build.rs makes once, at build time, and compiles in as MAJORDOMUS_COMMIT and MAJORDOMUS_DIRTY (read back as crate::COMMIT and crate::DIRTY).

capability

The canonical capability model and its registry: the one place a capability is defined. MCP, HTTP, OpenAPI, the CLI’s introspection and the generated documentation are projections of what lives here and define nothing of their own.

cli

The command line, declared with clap’s derive API. Every command starts from the same RepoArgs; capabilities reaches the registry through the registry’s own introspection capabilities, so no list of capabilities lives here.

cockpit

The Cockpit: the human-facing projection of the registry, server-rendered.

command_graph

The canonical command graph: every command this repository offers, from whichever program offers it, with where each one is projected.

commands

Command dispatch: the one place a parsed command line becomes a call.

commit

The commit as a value: one grammar, one policy, one verdict, one plan.

convergence

Where the work of this repository is being held, and whether any of it is held somewhere it can be lost.

deploy

The deployment objects of the layer, typed: .ai/repo/deployments/*.yaml parsed into values that cannot hold nonsense, and validated against what this repository actually contains before anything is built from them.

devcontext

The context compiler: what a development session should be given, derived from the repository rather than composed by hand.

devtask

The executable development task: one issue or one milestone read as work to be done, with the origin of every value on the value.

diagram

Diagrams, canonically: nodes, edges and groups in Rust, derived from whatever already states the topology, and rendered to Mermaid by a function that is one reader among several.

discovery

Discovery: which files of the repository are declarative sources, and of which kind.

economics

Token economics, measured rather than claimed.

entity

Entities: the one projection that makes every object of the layer addressable.

environment

The repository environment: one typed snapshot of what this checkout is right now — the project, the repository, version control, the toolchains it declares, what the layer holds, the workflows a person can run, the provider projections and the local services — with a provenance entry for every fact in it.

episodes

Episodes: the execution episode of a client that has no provider hooks, drawn by the MCP connection itself (ADR 0103).

evidence

Evidence: what actually ran, against which commit, and whether it still proves anything.

execution

Executions: watching a capability call that takes longer than a request should be held open for.

gates

Completion as a provable state: which gates a task’s own change set must pass, what each one said, whether that verdict still describes the tree, and therefore whether the task may be called finished.

generate

Generated projections that are committed for review: the OpenAPI document, the capability reference, the benchmark matrix, the registry manifest, and the shell tool’s key allow-lists derived from the JSON Schemas. All come through this one pipeline; the committed files are caches of it, never sources, and --check says when they are stale.

generation

The generation of an executable: which revision of the crate it was built from.

git

A minimal, optional, read-only view of git.

graph

Graphs, canonically: a node and edge model in Rust, derived from the registry and the index, and projected to whatever a reader wants. Nothing here knows about Cytoscape, Mermaid or Graphviz; a rendering library is a consumer of Graph, never its shape.

guard

The edit guard (I2735): before a provider’s tool writes a file of this checkout, is the path claimed?

http

The HTTP projection: the surfaces this repository exposes, resolved once and served.

index

The index: every declarative object the repository declares, read, validated and identified, plus every diagnostic about what could not be read. Built once per invocation from a discovery pass; the MCP surface is a projection of it.

intent

Intents: what must become true above the milestones that realise it, and whether the recorded evidence says it has.

intent_binding

The binding: what a piece of work serves, resolved once, before it starts (ADR 0111).

intent_plan

Intent coverage: which work makes which intent criterion true, derived from the plan.

intent_realization

Intent realization: which work realises which intent, through which sessions and providers, how each link is known, and what the intent still lacks.

intent_review

The two planning records an intent is held to before execution: the gap and the critique.

lease

One shared server per checkout: the lease that decides who it is. The first majordomus mcp (or serve) to create state/mcp/server.json under the checkout’s local half owns the server and publishes its URL there; every later process reads the file, checks that the server answers for this root, and attaches to it. A lease whose server does not answer is stale, and the next process takes it over; so is a file that is not a lease document, an empty one, or one whose owner never published a URL. A server that is slow to answer while its process is alive is busy, not stale: the election waits for it for BUSY_GRACE before it takes anything over. The file lives under .ai/local/ (never tracked, by the layer’s contract), and it is removed when the server stops — including when SIGTERM, SIGINT or SIGHUP asks it to — but only by the process that still holds it: every removal and every rewrite re-reads the file under the lock beside it (server.lock) and acts only on a lease that carries the actor’s own token (take_over_with says why it is a lock).

ledger

The ledger: the append-only record of what happened to this checkout, and the one writer of it in this executable.

live

The repository as a long-lived process must see it: current, not as it was when the process started.

logging

Where diagnostics go, and where they must never go.

mcp

The MCP capability: a projection of the index into resources and tools (surface), the JSON-RPC and MCP method handling over it (protocol), the one local transport (stdio), and the bridge that forwards a stdio session to the shared server of another process (bridge). Only protocol knows the wire shapes; only stdio knows about file descriptors; surface knows neither.

mesh

The mesh: how one running Majordomus learns that others exist, and proves which one it is. ADR 0050 is the decision; this module is the whole implementation, and its boundaries are the point:

metadata

Metadata: the kind schema (kinds.yaml) and one JSON Schema per kind, both read at run time from the tool distribution’s share directory and, when a repository adds its own, from .ai/repo/knowledge/; and the YAML helpers shared by every reader. The contract is documented in docs/CAPABILITIES.md and in share/kinds.yaml itself.

model

The domain model: what an object is, where it came from, and what was wrong with what could not become one.

models

The model catalogue: which AI models exist for this tool’s world, what each can do, and which one a stated need selects — as declared data, never as a live client. ADR 0044 is the decision; ADR 0032’s boundary stands untouched: this crate calls no model, holds no SDK, and reads no credential’s value. The catalogue is share/models.yaml — one declaration, exactly like share/providers.yaml — and models.list / models.route project it to the CLI, HTTP, OpenAPI, MCP and the Cockpit, so no consumer keeps a model name of its own.

order

Canonical presentation order.

pack

The source pack: the tracked tree as a few text files a language model’s file search can index, with nothing in it that is not source.

peers

Peers: the clients attached to one shared server. Every MCP session, the owner’s stdio one and every one that arrived over HTTP, is a peer from the moment it attaches; initialize gives it a name (the client’s own clientInfo), and peers.announce lets it say what it is working on. The board lives in the server’s memory and nowhere else: it ends with the process, and nothing here touches the repository.

perf

Performance truth: process-wide counters of the work that must happen once (a repository scan, an index build, a registry build, a schema generation, a projection build) and of the work that happens per call (executions, handler invocations, cache hits and misses), plus phase timings on a monotonic clock. They are what the structural tests read after hundreds of requests to prove that no request rebuilt canonical state, what perf.counters answers over every transport, and what the benchmark evidence carries beside its latencies. Atomics only: reading them costs nothing worth measuring, and nothing here allocates on a hot path.

plan

The plan: milestones, issues, the two graphs between them, and everything derived from them — execution waves, issue status, milestone status, the roadmap order, the active milestone, the next executable issue and every validation finding.

policy

The canonical policy, typed: .ai/repo/policy.yaml and the profiles beside it. The policy is the one canonical input of the provider projections; the shell tool reads the same file with the same subset reader, so the two agree byte for byte on what a projection is and which hash it carries.

product

The product model: what this repository’s product does for a person, as the features under the layer’s features section declare it, with every fact a surface may say about a feature derived from the registries that own those facts.

proto

The reader for the layer’s Markdown document schemas.

providers

The provider projections: AGENTS.md, CLAUDE.md, GEMINI.md and whatever else the policy’s projections[] declares, rendered from the provider templates and the canonical policy. They are one-way: the policy and the templates are the sources, the targets are caches that generate --check compares and generate rewrites.

quality

What this executable’s own public surface is held to, measured by the executable.

reasoning

Reasoning: how a session turns material engineering uncertainty into a recorded, evidence-backed conclusion — with independent advisors when some are present, and without them when none are. ADR 0098 is the decision; docs/REASONING.md the manual.

redaction

The one rule set that makes text a run printed fit to publish.

release

The release: what this project has shipped, what it would ship next, and the changelog that is a projection of both rather than a file somebody remembered to update.

repository

Repository discovery: the nearest ancestor of the start directory that carries .ai/manifest.yaml is the root, and the manifest is the only thing read to find it.

rules

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

scope

The repository scope: what a worker reads of the repository, and what it never reads.

served

What a deployment actually serves, observed from outside and judged against the commit that was meant to be there.

session

The session domain: one typed account of what an episode is, what identifies it, how it moves, and how it is closed exactly once.

share

The tool distribution’s data directory: share/kinds.yaml and share/schemas/<kind>.schema.json, read at run time. Nothing about kinds or keys is compiled into the executable; the directory is located per invocation, explicitly or by convention, and named in every error when it is not.

site

The site’s registry dataset: what GitHub Pages renders about the executable, derived from the registry, the index, the command line, the benchmark projection and the accepted baselines, and nothing else. The site has no content model of its own for any of it; its templates read site/data/registry/registry.json and lay it out, and the shell site generator reads docs/generated/registry.json for the ids it turns into routes.

skill

Skills as proven capabilities: what the repository can show about each skill, derived.

synthetic

A synthetic repository: the layer majordomus init writes, with as many rules and documents as a test or a benchmark asks for, in a fresh temporary directory that is removed on drop. One generator for the property tests, the scaling benchmarks and the registry benchmarks, so that they measure and test the same shape of repository. Not a git repository: discovery goes through the filesystem, which is what a benchmark wants to measure and a property test wants to control.

ui

majordomus ui: the primary surface, a product of its own, server-rendered (ADR 0135).

web

The repository’s web surfaces: one model, discovered once, read by everything that serves, publishes, validates or describes them.

why

The Why catalogue: the operational moments this tool is a response to, the audiences that recognise them and the areas they fall under, read from the index and answered as one immutable typed model.

worktree

The branch-to-worktree topology: where every linked worktree of a repository belongs, derived from git and from nothing else, and everything that follows from it.

Macros

capability

The one canonical declaration of an executable capability. From it every projection is derived: the MCP tool and its schemas, the HTTP route and its OpenAPI operation, the Swagger UI entry, the command line’s introspection, the benchmark targets for every transport it is exposed on, the cache policy the executor applies, and the generated reference. Nothing is declared a second time anywhere.

compose_modules

Compose the application from its modules: each name is a Rust module with a module() function. This list is the one composition a person maintains at the root; a capability added inside a module needs no edit here.

module

Build a ModuleDescriptor: the module’s identity and metadata once, and the executables it composes, each a capability! value.

Enums

Error

Everything that stops a command.

Constants

COMMIT

The commit this executable was built from, or unknown outside a work tree. Read at build time: nothing here shells out to git, and an installed binary needs no repository in order to say what it is.

DIRTY

Whether the tree COMMIT names carried uncommitted changes when this executable was built: Some(true) or Some(false) when the build knew, None when it did not — a commit handed in through MAJORDOMUS_BUILD_COMMIT without MAJORDOMUS_BUILD_DIRTY, or a build outside a work tree. It covers the crate’s directory as the build script last saw it; build_identity::identify is the decision and holds its table.

GENERATION

The generation this executable was built from: the digest generation::crate_generation takes over the crate sources, compiled in by build.rs, or unknown when the build could not read them.

PROFILE

The cargo profile this executable was built with.

TARGET

The Rust target triple this executable was built for, from build.rs. The same string the distribution model names a target by, so that a build can say which artifact it is.

VERSION

The executable’s version, from the crate manifest.