How Majordomus derives its surfaces

Majordomus is a control plane that lives inside the repository it governs. This document explains it as one system, not as a list of features. Facts are written down, discovered or observed. They become typed models. Those models are validated and checked against evidence. Then every interface a person or an agent uses is derived from them: the command line, the HTTP API, the OpenAPI document, Swagger UI, MCP, the Cockpit and this website.

Most of what follows is already described somewhere else, one subsystem at a time: CAPABILITIES.md covers the operation model, DYNAMICITY.md covers where a fact lives, DEVELOPMENT_RUNTIME.md covers where a semantic lives, DOCTRINE.md covers rules and proof, EVIDENCE.md covers recorded executions, GITHUB_PAGES_ARCHITECTURE.md covers the website, MESH.md covers discovery, and PLANNING.md covers the plan. This document connects them, and it says plainly where the code does not do what the design wants yet.

How to read the claims. Every structural claim was checked against the code and against the running executable, at the commit this document was written on. Claims carry labels in brackets, such as [C4], which point into the claim audit. The audit gives the file and line, or the command, that proves each one. Some statements are qualified with a word:

• partial: only part of the statement is implemented;
• not implemented: nothing in the tree does it;
• debt: the repository knows about the gap. It is listed in Architecture debt.

No numbers about the repository's contents appear here (project.no-counts-in-prose). Wherever a count matters, the command that measures it is given.

Contents

1. The invariant
2. Two programs share one name
3. Where the truth is: five kinds of fact
4. Discovery, and how it differs from inference
5. Typed registries, canonical ids and display names
6. Schemas: from a Rust type to OpenAPI and MCP
7. The surfaces are projections
8. The generation pipeline
9. Governance: doctrine, rule, policy, ADR
10. A rule existing is not the same as a rule being enforced
11. Evidence, freshness and claim drift
12. Publication: built, deployed, verified
13. Doctor and drift: detect, repair, regenerate
14. Tests that hold the surfaces together
15. Sessions, context, handover, planning, environment
16. Mesh and the peer board
17. Walkthroughs
18. What is not generated
19. Zero registration: the ideal and its exceptions
20. Why generation matters, and the theses

Appendices: A architecture map, B surface map, C generation matrix, D governance and mesh maps, E claim audit, F architecture debt.

1. The invariant

Discover and model a fact once, and derive every interface from it.

This is the mechanism that keeps the interfaces from drifting apart. A repository that describes itself in several places builds up descriptions that disagree: a README, an API reference, a tool list for an agent, a dashboard, a website. Each can be correct on the day it is written, and each goes stale on its own schedule. Majordomus avoids this by keeping one declaration and generating the other descriptions from it. Where it cannot generate a description, it checks that description against the declaration.

The repository names this invariant several times. It is project.interfaces-are-projections and project.rust-canonical-declaration in .ai/repo/rules/project/. It is ADR 2, ADR 4 and ADR 5 for operations, and ADR 40 for development semantics. What matters is how far the code actually honours it:

• Operations (capabilities) honour it best. MCP tools and resources, HTTP routes, the OpenAPI document, the benchmark targets, the generated reference and the site's registry pages are built by walking one registry [C1, C5, C6, C7].
• The command line is declared a second time, in clap. It is checked against the registry rather than derived from it [C8, C9].
• The Cockpit is partial. Its generic capability, object and graph pages are driven by the registry. Its area pages and the areas themselves are written by hand [C12, C13].
• Development semantics (tasks, sessions, handovers, checkpoints, ADR allocation) are still mostly owned by shell code under lib/. For the mutating half there is no capability at all, and a ratchet file records that debt [C30].

2. Two programs share one name

majordomus is two executables. This fact is easy to miss, and every later section depends on it.

For a command it does not know, the shell tool points you at the Rust executable. The registry, and so every derived surface, belongs to the Rust executable. Anything owned only by lib/ reaches no HTTP route, no MCP tool and no Cockpit page, unless a Rust capability reads its files. DEVELOPMENT_RUNTIME.md is the measured inventory of that boundary, and scripts/development-semantics-check enforces its ratchet.

3. Where the truth is: five kinds of fact

The source of truth is the tracked tree. The .ai/ layer is named by .ai/manifest.yaml and classified by .ai/repo/knowledge/sources.yaml. The Rust sources under apps/majordomus-cli/src/capability/builtin/ declare the operations, and share/ holds kinds, schemas and vocabularies. Everything else is one of the following:

Two consequences follow, and the rest of this document depends on them.

• Derived output never feeds back as input. scripts/derive states that no stage reads its own output [C15]. The shell dataset generator leaves its own documents out of its input list [C16].
• Observation never becomes permission. A peer's claim is advisory. A mesh node's trust verdict changes labels, not permissions [C40, C42].

4. Discovery, and how it differs from inference

Discovery is enumeration governed by a declaration. The Rust executable finds the repository root. It reads the manifest, loads the kinds and schemas (share/kinds.yaml, share/schemas/, and repository additions under .ai/repo/knowledge/), and then enumerates files through sources.yaml classes, from the version-control index by default (--discovery vcs). Each file becomes a typed object or a diagnostic with a stable code. An unreadable manifest or kinds file is an error. An object that does not validate is excluded, the index reports degraded, and the surfaces still serve; --strict refuses a degraded index. CAPABILITIES.md ("Lifecycle and failure policy") describes this, and test/cases/76_capabilities_projections.sh adds a repository-defined kind and asserts that it appears on every surface.

Inference is different. It guesses at relevance or intent. It lives in a few named places and marks itself:

• devcontext selection. Every selector except IntentMatch is declared() and carries confidence 1.0. The intent match scores the share of intent terms found in an object's title, description, identity or tags, and never in its body [C45].
• Derived handover bodies. They are built from git, the ledger and open questions, and they end with a footer saying that no model wrote them [C47].
• adr propose. It writes proposed and refuses any other status. Acceptance is a person's act [C34].

No surface runs a language model to produce a fact.

5. Typed registries, canonical ids and display names

Every addressable thing has a canonical identity that is not its display name.

• Capabilities. The id is namespace.local (rules.report). The title ("Every rule against the proof there is for it") is display text. The registry refuses duplicate ids, MCP tool names, MCP resource URIs, HTTP routes and CLI paths, stores entries in BTreeMaps and iterates by id [C4].
• Declarative objects. The id is <kind>.<identity>, and the identity comes from the kind's identity rule: id@version for a rule (project.english-only@1), a number for an ADR (adr-0044). The MCP resource is majordomus://<kind>/<identity>.
• Rules are referenced as id@version in depends_on. A new version is a new file (conventional-commits.v2.md).
• Worktrees are identified by their branch. The path <repo>-wt/<branch> is derived from git and never registered (WORKTREES.md).
• Peers get a board position (p1, p2) that is reassigned on reconnect. It is not an identity: the durable half of a peer's identity is the checkout it carries (ADR 44).

Ordering is canonical too. apps/majordomus-cli/src/order.rs defines one total order: group, rank, label compared naturally, then identity. scripts/ci/order-check refuses case-folded comparators outside it, sort keys that render, and unpinned shell sort. It also ratchets the remaining crate sort sites in .ai/repo/order-baseline.txt [C19].

6. Schemas: from a Rust type to OpenAPI and MCP

The schema chain for an executable capability is real code, and a person writes each piece of it only once:

flowchart TD
  ty["Rust input and output types<br>serde + schemars JsonSchema derive<br>doc comments become descriptions"]
  cs["CanonicalSchema::of<br>schemars::schema_for, $schema removed,<br>rustdoc translated to CommonMark"]
  mcp["MCP tool inputSchema and outputSchema<br>for_mcp: inline, $defs kept"]
  oas["OpenAPI 3.1 operation<br>for_openapi: $defs hoisted into components,<br>refs rewritten; a clash of names is refused"]
  sw["Swagger UI<br>loads /openapi.json, embeds nothing"]
  gen["docs/generated/openapi.json and openapi.yaml<br>site /docs/api/"]
  ty --> cs
  cs --> mcp
  cs --> oas
  oas --> sw
  oas --> gen

CanonicalSchema::of::<T>() calls schemars::schema_for! [C2]. OpenAPI component names come from the schema title. That namespace is flat, so two different types with the same title fail openapi::document with "schema component … is defined twice with different content" [C3]. The fix is to rename a type; nothing warns about it before that point (debt F-11).

A declarative kind starts one step earlier. Its document schema lives under share/schemas/majordomus/<kind>/. A .proto description there generates the JSON Schema, the front-matter allow-list under share/allow/ and the section requirements (DEVELOPMENT_RUNTIME.md, "The derivation chain"). Unknown front-matter keys are errors (project.unknown-keys-are-errors).

7. The surfaces are projections

7.1 One declaration

An executable capability is one capability! block in apps/majordomus-cli/src/capability/builtin/<module>.rs. It lists id, kind, title, description, input, output, stability, exposure, tags, cache, benchmark and handler. The macro also classifies availability, visibility and the execution policy from the kind and the exposure, and takes the benchmark cases from the input type's BenchmarkCases [C1]. exposure sets each surface explicitly: Exposure { mcp, http, cli }. None means the capability is not exposed there, and nothing infers an exposure [C4]. Modules are composed with module! and compose_modules! in builtin/mod.rs.

Two post-macro modifiers declare what the kind alone cannot say. .cancellable() marks a capability whose run can be cancelled. .writes_repository() marks one that writes a tracked record. Two capabilities served over HTTP and MCP carry it today, plan.transition and recover.orphans; list them with a search for .writes_repository() under builtin/ [C31].

7.2 MCP

src/mcp/surface.rs says of itself "Nothing is declared here". compute_tools() takes every capability with an mcp.tool exposure. compute_resources() takes every capability with an mcp.resource exposure, and every declarative object is one [C5]. A tool carries the canonical input and output schemas, _meta.majordomus.id and a readOnlyHint derived from the kind. A call resolves through by_mcp_tool and runs through the shared executor.

The tools agents use to coordinate are ordinary declared capabilities: majordomus_announce is peers.announce, majordomus_peers is peers.list, and majordomus_capabilities is capabilities.list. They are not hand-written tools. Three pieces of code still know about them by name, though: the initialize instructions text, the stdio-to-HTTP bridge (which replays an announcement after a reconnect), and the peers.announce handler (which refuses a caller that is not MCP) [C6].

7.3 HTTP API

The router resolves a capability route with registry.by_http(method, path). For GET it binds query parameters, coerced by schema type; for POST it parses a JSON body. It calls the executor and maps errors to 400, 404, 422 and 500 [C7]. The router adds transport behaviour and holds no business logic: coercion, error mapping, refusing cross-origin non-GET requests, the route index at /api/v1, and a per-generation cache of the OpenAPI document. Its non-capability routes are infrastructure: /, /openapi.json, /swagger, /mcp, the /events WebSocket, /cockpit/** and generated static mounts such as /docs/ (WEB.md). There is no hand-written peers route: /api/v1/peers is peers.list.

7.4 OpenAPI

src/http/openapi.rs builds OpenAPI 3.1 from the same registry. operationId is the capability id and the tags are the modules. Parameter examples are the capability's own benchmark cases, so a field no case sets has no example. The x-majordomus-* extensions carry id, kind, stability, provenance, benchmark, cache, MCP and CLI; infrastructure routes sit under x-majordomus.infrastructure [C7]. Maps are sorted and carry no timestamp. The live document and docs/generated/openapi.json are the same computation.

7.5 Swagger UI

src/http/swagger.rs renders one static HTML shell that points SwaggerUIBundle at /openapi.json. A unit test asserts that the shell embeds no paths, openapi or components. The UI's own JavaScript and CSS load from the pinned swagger-ui-dist on unpkg, so this is the one surface that is not offline [C10]. It is a pure UI projection.

7.6 The command line: declared twice, and checked

The clap tree in apps/majordomus-cli/src/cli.rs is written by hand. That is deliberate: clap owns parsing, help, defaults and value sets ("The one projection that can drift" in CAPABILITIES.md). A capability's CliExposure is therefore a claim about a command declared somewhere else, and the claim is checked in both directions:

• capability/closure.rs fails when a claim names a command clap does not have, or one that only groups other commands. It runs in tests/projections.rs and in capabilities validate [C8].
• cli::LOCAL (src/cli/local.rs) gives the reason for each command no capability claims. There are exactly four structural reasons: process lifecycle, writes the repository, session-local, or renders a named capability for a terminal. There is also an alias form. quality::parity checks it, and the projection-closure gate (scripts/ci/projection-check) fails on a command that gives no reason [C9]. capabilities projections lists both sets live: the CLI-only commands as unbacked, and commands with no reason as unclassified.

What a CLI command still takes by hand [C11]:

• a clap variant, and a dispatch arm in commands/mod.rs;
• a runner in commands/<name>.rs, which maps flags to the input JSON (--findings becomes findings_only) and calls ctx.execute(id, input) after registry.by_cli;
• a text renderer. --format json prints the capability's output unchanged; --format text is the command's own. Some exit semantics live only in the renderer: rules report --check exits 10 there, not in the handler;
• an entry in cli::EXAMPLES, a single hand-written CommandExamples const. cli::validate refuses a runnable command with no example, and tests/cli_examples.rs runs every example against the built binary.

Shell completion is not clap_complete. commands/completion.rs answers from the command graph, which composes the clap tree, the shell tool's share/commands.yaml and the workflows (COMMANDS.md).

7.7 The Cockpit

The Cockpit (src/cockpit/) is HTML rendered on the server in Rust; there is no template engine. The /cockpit path matters more than any feature, so this section separates what is derived from what is written:

• Derived. /cockpit/capabilities/<id> is one generic page for every capability, with a runner form built from the input schema. /cockpit/object?uri= renders any object; /cockpit/graphs/<id> renders any derivation. The sidebar's catalogues come from registry.modules(), grouped by the product model's module_area, plus index.kinds() and graph::ids(), all in canonical order [C12].
• Written by hand. The route table is a match in cockpit/mod.rs. The areas list (Overview, Capabilities, Mesh, …) is nav::areas(), and its module comment gives the reason. Area pages ask for a capability by its literal id, such as ask(ctx, "health.report", …) or ask(ctx, "mesh.status", …) [C13]. So the sentence in CAPABILITIES.md that "nothing in it names a capability" is not accurate (debt F-20).
• The frontend is not an authority. The JavaScript under share/cockpit/ does presentation and requests only. runner.js calls the capability's real route from data-mj-method/data-mj-path; palette.js and the graph views read /api/v1/*. Nothing in the browser computes readiness, status or proof. The development-semantics gate refuses any reference to .ai/repo, .ai/local or a majordomus executable inside the Cockpit trees [C14].

7.8 The surfaces compared

Coverage is uneven. Fewer capabilities have a CLI path than an HTTP route. peers.list, plan.*, objects.*, health.report and environment.status have no CLI projection of their own; the env commands are CLI renderings recorded in cli::LOCAL. Run majordomus-cli capabilities projections --format json and compare the cli and http fields (debt F-4).

8. The generation pipeline

8.1 The generators, in order

scripts/derive is the one command that brings every committed projection up to date. Its stages run in this order [C15]:

flowchart TD
  build["build step<br>cargo build, or MAJORDOMUS_BIN"]
  a["stage A: majordomus generate --strict<br>code-only projections: openapi, registry, cli,<br>capabilities.md, modules/*.md, share/allow, provider bootstraps"]
  b["stage B: scripts/generate-site-data<br>site/data/generated, site/content, docs/SITE_CLAIMS.md,<br>docs/PLAN_STATUS.md, docs/PAGES_STATUS.md"]
  c["stage C: majordomus generate<br>projections over the index stage B changed:<br>site/data/registry, benchmarks, artifacts manifest"]
  d["stage D: scripts/gitattributes<br>the merge=derived block, from the artifact manifest<br>and the published content tree"]
  check["scripts/derive-check<br>generate --check, generate-site-data --check,<br>gitattributes --check: 0 current, 10 stale, 15 refused"]
  build --> a --> b --> c --> d
  d -.-> check

• majordomus generate (src/generate.rs) writes to docs/generated/ and site/data/registry/ from one plan(). The same plan runs for writing and for --check. Its targets are the GenerateTarget enum in cli.rs, and the output manifest (docs/generated/artifacts.json) lists every artifact with its source, schema and hash.
• scripts/generate-site-data is the shell half. It hashes a declared list of inputs (INPUTS) under LC_ALL=C, writes into a staging directory and moves the results into place, so a failed run changes nothing. It projects docs/*.md into site/content/docs/ [C16].
• There are two writers of generated trees, src/generate.rs and the shell generator, and both write site content (debt F-14).

8.2 Freshness is enforced at commit time and in CI

• .githooks/pre-commit runs bin/majordomus doctor, the worktree guard and scripts/pages current. That last command compares generate-site-data --fingerprint with source_hash in site/data/generated/source.json, and then runs generate --check [C17]. If the executable is not built, the registry half of the check is skipped with a message rather than failed (debt F-16).
• In CI, core-check runs generate-site-data --check, and the generation-converges gate runs generate followed by generate --check: the generator must be a fixed point [C18].
• .gitattributes marks every derived path merge=derived. scripts/merge-derived keeps "ours" and prints that the file is now stale, so a merge never hand-merges a projection; derive regenerates it afterwards. doctor fails a clone that has not registered the driver.

8.3 How a document becomes a page

Each document is registered by one row in the first table of docs/README.md. The shell generator reads those rows and makes /docs/<slug>/. It generates the front matter: the title from the first heading, the description from the row, the weight from the row's position. It rewrites links, and it refuses any docs/*.md that is in no table [C16]. The site navigation (site/data/nav.toml) is authored, and scripts/ci/nav-check verifies that the navbar and footer templates derive from it. Nothing adds a document to the navigation automatically. That is by design: the file says the navbar is not a sitemap.

8.4 Generator and renderer

A generator turns canonical input into a committed or served artifact, and is judged by --check: majordomus generate, scripts/generate-site-data, majordomus update, scripts/gitattributes. A renderer turns a value that already exists into a presentation, and holds no fact: a CLI text renderer, a Cockpit page, a Zola template, the environment banner (src/environment/render.rs, "a pure view with no discovery"). When a renderer computes something a generator should own, it becomes a second implementation. The development-semantics gate says it cannot decide this mechanically, so a reviewer does.

8.5 Generators are tested

• tests/projections.rs: every declared projection exists and none is an orphan; a change to a type or description reaches MCP, OpenAPI and the reference; generated artifacts are byte-identical when generated twice and carry no absolute path [C18].
• tests/generate_check.rs: --check agrees with what a write would produce, detects tampering and never writes.
• test/cases/98_cli_reference.sh compares two generations with cmp. test/cases/28_no_hardcoded_values.sh asserts that input order does not depend on locale. test/cases/12b_site_data_transactional.sh asserts that a failed run leaves artifacts byte-identical. test/cases/51_derived_artifacts_committed.sh asserts that derive-check passes and that no derived file embeds the current commit.

9. Governance: doctrine, rule, policy, ADR

This repository defines the four terms as follows. The definitions come from DOCTRINE.md, the rule files and .ai/repo/policy.yaml.

The chain from a rule to evidence is:

flowchart TD
  rule["rule file<br>class, depends_on, x-majordomus"]
  mode["enforcement mode, from the block's shape<br>dispatched: validator / gated: tests / reviewed: reason"]
  val["validator<br>mj_validate_name in lib/, run by the dispatcher<br>at the commands enforced_by names"]
  gate["CI gate<br>.ai/repo/ci/gates.yaml: id, job, runs, path classes"]
  test["behavioural case or crate test<br>test/cases/*.sh, apps/majordomus-cli/tests/*.rs"]
  ledger["recorded execution<br>.ai/repo/evidence/ledger.json"]
  state["proof state per rule<br>crate::rules, rules report"]
  surf["surfaces<br>CLI rules report, GET /api/v1/rules,<br>majordomus_rules, generic Cockpit page"]
  rule --> mode
  mode --> val
  mode --> test
  test --> gate
  val --> test
  test --> ledger
  ledger --> state
  gate --> state
  state --> surf

One join in that chain is inferred rather than declared. gates.yaml does not say which rules a gate proves. crate::rules scans each gate's runs: line (a line reader, not a typed parse) and binds a rule's named path to a gate in three cases: the command is that path; the path is a test case and the command runs test/run.sh; or the path is a crate test and the command contains rust-check [C27]. A suite gate is assumed to run every case; nothing checks that it actually selected the case (debt F-7).

10. A rule existing is not the same as a rule being enforced

A rule can be in any of eight conditions, and each is a different claim. The table maps each condition to what the repository can actually show today.

The machine-readable form of this ladder is the rule proof graph (crate::rules, majordomus-cli rules report | show | proves, GET /api/v1/rules, MCP majordomus_rules). It gives each rule one of ten states: proven, inputs unchanged, stale, gated, failing, not run, reviewed, unrunnable, dangling, unproven. A rule's state is the weakest of its parts [C23].

• Enforcement modes come from the block's shape [C24]. A dispatched rule names a validator. A gated rule names tests and no validator. A reviewed rule names a reviewed_because sentence and neither. An executable proof always wins. scripts/ci/rule-proof-check, the rule-proof gate, refuses a dangling path outright and ratchets blocking rules that name nothing in .ai/repo/rule-proof-baseline.txt [C25].
• A finding is a class the state does not support. dangling is a finding for any class. For a blocking rule, unproven, failing and unrunnable are findings. gated, reviewed and not run are weaker states: they are counted but are not findings [C26].
• Nothing gates on the proof graph itself. No script, gate or workflow runs rules report --check (debt F-8).
• A failing run can be hidden. The per-rule state is max() over its tests, and the enum orders Failing before NotRun. A blocking rule with one failing case and one case that never ran therefore reports not run, which is not a finding. Reading the code shows this; it has not been observed in data (debt F-9) [C26].

project.never-reported-is-not-green shows the whole problem in one rule. Its statement is "a check that has not reported is unknown, never passing". It is class: advisory, has no x-majordomus block, and says it is decided "by review and by the record, not by a gate". The proof graph reports it as unproven, and that is not a finding, because an advisory rule owes no proof. The rule exists, its ideas shaped evidence-check (see EVIDENCE.md), and it is not mechanically enforced. The graph says exactly that.

To measure it yourself:

$ bin/majordomus-cli rules report --format json | jq '.states, .coverage'
$ scripts/ci/rule-proof-check
$ bin/majordomus-cli rules show project.never-reported-is-not-green

11. Evidence, freshness and claim drift

The ledger. .ai/repo/evidence/ledger.json holds the latest recorded execution of each test. Each entry records the test id, runner, source, outcome, seconds, commit, working-tree state, a sha256 digest of the test's own source, the time, the origin (local, ci or release) and the command that reproduces it. majordomus evidence record writes it from a report the run already produced. It keeps no history and no output (EVIDENCE.md).

Freshness is derived on every read [C28]:

• a run that did not pass is failing;
• when git cannot diff, the run is stale, because not knowing is not proof;
• when the test source or the rule file changed after the recorded commit, or the digest no longer matches, the run is stale;
• when nothing else changed apart from the ledger itself, the run is proven;
• otherwise the run is inputs unchanged, meaning no known invalidation but not proof against this commit.

Claims. docs/CLAIMS.yaml binds each public claim to a source, an implementation and a test, with an authored status from a vocabulary declared in the same file. Every claim has a page under docs/claims/. Three readers check for drift:

How proof reaches the Cockpit and the website, honestly. Rule and claim proof states are served as capabilities (rules.*, evidence.*) over the CLI, HTTP and MCP, and each has the generic Cockpit capability page. The Cockpit has no dedicated rules, evidence or peers area. The website's /evidence/ page renders data/generated/claims-graph.json, which is built from CLAIMS.yaml: it shows the authored links between claims, sources and tests, not ledger outcomes. Its guarantees pages show the authored status, not measured proof [C29]. CI does not record evidence either: EVIDENCE.md says "nothing runs that step today" [C29]. So proof of function reaches the API and MCP as a derived state. It does not yet reach a page a person browses as anything more than a mechanism (debt F-6, F-10).

12. Publication: built, deployed, verified

The website is a projection, and three different states can each be called "published":

This is project.never-reported-is-not-green in practice. A deploy job that reports cancelled because it waited too long for the CDN is not proof that nothing was published, so the question is answered by reading what the site serves.

13. Doctor and drift: detect, repair, regenerate

doctor has no --fix [C22]. Each finding names the command that fixes it. A finding that does not name one is refused by the finding-reproduce gate. Freshness of site/ and docs/generated/ is not checked by doctor; the pre-commit pages current and derive-check check it.

14. Tests that hold the surfaces together

Value equality across HTTP and MCP is tested for a sample of capabilities, not generated for each one. No test asserts that --format json from the CLI equals the HTTP value for each CLI-exposed capability (debt F-12).

15. Sessions, context, handover, planning, environment

Each of these follows the same pattern: an authored or recorded state, a derivation, and projections. The owner of each derivation differs, and that is where the debt is.

Sessions: a persistent record plus ephemeral presence. A session episode belongs to the provider session. It is recorded under .ai/local/state/sessions-open/ while open and closed into .ai/repo/sessions/ as a tracked record. That is the persistent half, written by lib/session.sh and lib/capture.sh, and triggered by the provider hooks in .claude/settings.json (session start, end, compact and prompt submission). Presence is the peer board, held in memory by the shared server and lost with the process (§16). CONTINUITY.md states the separation: "The episode file records no process, the peer board records no episode." The typed Rust session domain (src/session/) reads; the shell still writes (ADR 47, ADR 52).

Context compilation: two engines.

• majordomus context (lib/context.sh) is the briefing. It has fixed sections in authority order (git, peers, task, profile, context documents, questions, decisions, checkpoint, handover, files, history, prompt), a line budget from policy (context.builder_budget_lines), and a declared drop order. Git, the task, the profile and open questions are never dropped, and every dropped section is listed under EXCLUDED. It is deterministic, and no model is called.

• devcontext.compile (src/devcontext/) is the Rust compiler. It is a capability, so it reaches the CLI, HTTP and MCP [C44]. The algorithm:

  • discovery: seeds, a walk over the composed graph with edge weights multiplied along each path, the effective scope paths (including an issue's declared scope), governance, session records and local handovers and checkpoints, and unresolved references;
  • relevance: a floor (DEFAULT_FLOOR) and a depth limit (DEFAULT_MAX_DEPTH);
  • authority: tiers ordered Task, Governance, Source, Decision, Knowledge, History;
  • freshness: a local record whose git divergence is untrustworthy has its relevance halved and gets a stale_record diagnostic, and deprecated or superseded objects are excluded;
  • budget: tokens estimated as bytes divided by BYTES_PER_TOKEN, first fit in the order tier, then relevance, then URI; seeds and policy or scope objects are never dropped, and over_budget is reported if they alone exceed the budget [C45].

  Only the intent match is inferred (§4). Two engines for one concept is debt F-15.

Handover. The required sections come from policy (handover.required_sections: Objective, Current State, Next Action), and a missing or empty section is refused. The front-matter identity fields (branch, head, worktree, changed files, …) are always computed, and a body that tries to author one is refused. With --derive, each section is generated from the ledger, git and open questions by mj_derive_sec_<slug> in lib/derive.sh [C47]. --resolve picks the newest handover for the same worktree and branch, then for the same branch, never repository-wide, and labels its git divergence.

Planning. Milestones and issues are authored YAML under .ai/repo/project/. Status is derived and never stored: a status key is a validation error. Validation builds the dependency DAG with cycle detection, then execution waves; two ready issues in one wave whose scopes contain each other produce WARN scope_conflict and are serialised [C46]. lib/project.awk is the authoritative engine. src/plan.rs mirrors it and is held byte-identical by case 99; plan.* exposes it over HTTP and MCP, and plan.transition writes one record through the model (debt F-17). docs/PLAN_STATUS.md is generated by stage B.

RepositoryEnvironment. environment::RepositoryEnvironment (majordomus/repository-environment/v1) is one typed snapshot: project, repository, VCS, toolchains, layer, workflows, providers and services, with a provenance entry for each value. environment.status and environment.explain are capabilities (HTTP, MCP). The env commands and the shell banner are renderings of it; the banner "is a pure view with no discovery". One limit is honest to state: a service is drawn as available when a TCP connect succeeds, and nothing more [C48] (debt F-18).

16. Mesh and the peer board

There are two distinct mechanisms, and there is no third.

The peer board (src/peers.rs, ADR 44) holds the sessions working on this repository now. It is one in-memory board per shared server; peers.list gathers every checkout's board by reading the other checkouts' leases and asking each one once, and reports complete and boards. A peer is attached through an MCP session, and HTTP MCP sessions expire after SESSION_IDLE_TIMEOUT. majordomus_announce attaches a claim (intent, scope) to the connection. The board "enforces nothing", and a peer that reconnects loses its place on it [C41].

The mesh (src/mesh/, ADR 50, docs/MESH.md) discovers running Majordomus instances across machines. Its implemented providers are UDP multicast, UDP broadcast and HTTP rendezvous (POST /api/v1/mesh/register), each an implementation of MeshProvider that only hands bytes to the manager. The manager verifies Ed25519-signed envelopes on one path into one MeshRegistry, bounded by MAX_NODES, with presence from PRESENCE_TTL and records kept for RETENTION. Trust (deny_unknown by default) labels records and grants nothing. The mesh is off unless a committed declaration enables it, and this repository's declaration (.ai/repo/mesh/majordomus.yaml) says enabled: false [C42]. The governing sentence is "Discovery creates awareness, not authority."

What does not exist, so that nobody goes looking for it: a blackboard separate from the peer board; Tailscale, mDNS or DNS-SD discovery (named as possible future providers only); any cross-machine journal, link or claim replication on master; a Cockpit page for the peer board. ADR 50 keeps the two apart on purpose: "The peer board remains the only cooperation surface."

Scope overlap is derived, and advisory. Three mechanisms compute overlap, and none of them locks anything:

check --overlap reads task records only, not the board and not branches. It also has a defect you can reproduce: the loop runs on the right side of a pipe, so its finding counter is lost, and it prints "no other worktree claims an overlapping path" directly after listing overlaps [C43] (debt F-13). What actually refuses a commit is the task's own scope, checked at finish and by the pre-push hook.

17. Walkthroughs

17.1 One capability through every surface: rules.report

To reproduce: bin/majordomus-cli capabilities describe rules.report, curl -s localhost:8742/openapi.json | jq '.paths["/api/v1/rules"].get.operationId'.

17.2 One rule from its file to its evidence: project.conventional-commits

1. Source. .ai/repo/rules/project/conventional-commits.v2.md, class: blocking, with x-majordomus: tests: [test/cases/274_commit_policy.sh, scripts/ci/commit-policy]. It names tests and no validator, so its mode is gated.
2. Gate. commit-policy in .ai/repo/ci/gates.yaml, runs: scripts/ci/commit-policy. The judge inside is the executable's commit capability; the gate chooses a range and ratchets debt in .ai/repo/commit-policy-baseline.txt.
3. Mutation proof. test/cases/274_commit_policy.sh adds a non-conventional commit and asserts that both the command and the gate exit 10, that new debt fails after --write-baseline, and that --strict fails.
4. Evidence. The ledger holds a local passing run of suite:274_commit_policy. The rule's gate path is unrunnable as evidence, because no runner records a gate verdict, so the rule's state is gated: the mechanism is shown, not a result.
5. Surfaces. bin/majordomus-cli rules show project.conventional-commits, GET /api/v1/rules/rule?rule=project.conventional-commits, MCP majordomus_rule, and the generic Cockpit page for rules.show. The site's /doctrines/ pages are generated from the doctrine registry (doctrines.json in stage B) and do not show ledger state.

17.3 One doctrine: majordomus.use-case-coverage

It is vendored at .ai/repo/rules/vendor/majordomus/rules/use-case-coverage.v1.md. Its block names validator: use_case_coverage, enforced_by: [doctor, check, finish], policy_key: use_cases_covered, exit_code: 10 and a test (test/cases/94_use_cases.sh). The dispatcher runs mj_validate_use_case_coverage (lib/usecase.sh) whenever one of those commands runs, using the coverage policy in policy.yaml. finish selects doctrines by verification.finish_requires, and this repository's list does not name use_cases_covered, so here the doctrine is enforced at doctor and check but not at finish. The proof graph reports the validator present and the case not run.

17.4 One mesh example

The mesh is implemented and disabled in this repository, so the honest live example is the refusal:

$ curl -s localhost:8742/api/v1/mesh | jq '{active, reason}'
$ curl -s localhost:8742/api/v1/mesh/nodes | jq .count

The first answers active: false with the reason "the mesh declaration is disabled"; the second answers zero nodes. test/cases/130_mesh.sh and apps/majordomus-cli/tests/mesh.rs exercise the mesh in disposable fixture repositories rather than on this one.

17.5 Adding a feature: what actually happens

For a new read-only operation:

1. Write the input and output types with serde and JsonSchema, plus BenchmarkCases for the input (or declare a benchmark waiver). By hand.
2. Write one capability! block with its exposure. A new module also needs module! and a line in compose_modules!. By hand.
3. Make sure no schema title collides with another component name, or OpenAPI generation fails. By hand; nothing warns about it earlier.
4. If it has a CLI path: add a clap variant, a dispatch arm, a runner with argument mapping, a text renderer and a CommandExamples entry. If it is CLI-only, add a cli::LOCAL entry. By hand, and checked by cli::validate, tests/cli_examples.rs, closure and parity.
5. A dedicated Cockpit area needs a route arm, a page function and an areas() entry. By hand. The generic page needs nothing.
6. Special path classes in .ai/repo/ci/gates.yaml name specific files (commit, design, rules). A new builtin file is already covered by the rust class; a new subsystem directory may need a class. By hand, and not documented as a step.
7. Run scripts/derive and commit the projections. Automatic generation; staging them is by hand.
8. MCP, HTTP, OpenAPI, Swagger, the generic Cockpit page, benchmark targets, the reference and the registry pages follow. Automatic.

CAPABILITIES.md says a new capability is "one capability! block … Nothing else". That is true only for a capability without a CLI path and without a dedicated page.

17.6 Adding a rule: "every public capability has executable verification"

18. What is not generated

Generation stops where judgment begins. The following are canonical human input, and the machine derives nothing that could replace them:

• intent: an issue's acceptance criteria, a milestone's outcome, a task's scope, the objective of a handover;
• decisions: an ADR's context, decision and consequences, and its acceptance;
• rules: the statement, the class, and the choice between a validator, a test or a reviewed reason;
• policy: budgets, the finish requirements, what the mesh may do;
• prose: this document and every docs/*.md;
• declarations of taste: navigation groups, design tokens, the Cockpit's areas.

The machine derives what can be recomputed from those: status, waves, proof states, schemas, routes, references, the site, briefings and handover skeletons.

19. Zero registration: the ideal and its exceptions

The ideal is that adding a fact requires registering it nowhere else. It holds for: declarative objects (a file in a sources.yaml class), capability projections to MCP, HTTP, OpenAPI, Swagger and the generic Cockpit page, documents on the site (one index row, which the generator enforces), mesh providers, and graph derivations in the Cockpit sidebar.

The current exceptions are all recorded, and each is checked or ratcheted rather than silent: the clap tree, cli::EXAMPLES, CLI renderers, cli::LOCAL, the Cockpit route table and areas, site/data/nav.toml, gates.yaml path classes, and the shell commands in share/commands.yaml. Appendix F lists them with file references.

20. Why generation matters, and the theses

A repository that runs agents in parallel writes about itself faster than any person reads. If each surface had its own description, every merge would be a chance for them to disagree, and nobody would notice until an agent acted on the wrong one. Generation, a --check run and a ratchet turn that disagreement into a failing command.

The theses, each stated only as strongly as the evidence above allows:

1. Majordomus is a model native to the repository, and its surfaces are derived from it. This is true for operations and declarative objects. It is partial for the command line (checked, not derived) and the Cockpit (generic pages derived, areas by hand), and it is not yet true for the mutating development semantics that lib/ owns.
2. The surfaces are projections of one typed reality. HTTP, OpenAPI, Swagger and MCP are projections, and tests show that HTTP and MCP return equal values for sampled capabilities. The CLI and the Cockpit add renderers that hold no facts; a reviewer, not a gate, decides whether a renderer has started computing.
3. Rules matter when their relation to validators, execution and evidence can be inspected by a machine. It can here: the proof graph derives a state per rule from the rule, the tree, gates.yaml and the ledger. What the graph can show is still limited by what is recorded, and today that means local runs only and no gate verdicts.
4. The mesh makes distributed work visible. It is not magic orchestration. The peer board and the mesh registry observe; claims are advisory; overlap is reported, not locked; and the mesh is off in this repository.
5. Generation keeps one repository from accumulating incompatible descriptions of itself. This holds wherever a --check or a fixed-point gate exists. Where prose describes code without a check, it drifts: F-20 to F-24 below are examples found while writing this document.

Appendix A: architecture map

flowchart TD
  subgraph canonical["canonical: tracked, authored"]
    codeN["capability! blocks<br>apps/majordomus-cli/src/capability/builtin"]
    layerN[".ai/** objects<br>rules, ADRs, policy, plan, sessions, use cases"]
    shareN["share/: kinds, schemas, commands, events"]
    proseN["docs/*.md, site/content-src, nav.toml"]
    shellN["lib/*.sh: shell tool semantics"]
  end
  subgraph discovery["discovery"]
    manifestN["manifest and sources.yaml"]
    indexN["index of typed objects<br>fingerprinted"]
  end
  subgraph model["typed models"]
    registryN["CapabilityRegistry<br>builtin plus declarative, frozen"]
    rulesN["rule proof graph"]
    planN["plan model: status, DAG, waves"]
    envN["RepositoryEnvironment"]
    devctxN["devcontext selection"]
  end
  subgraph observed["observed, in process"]
    peersN["peer board"]
    meshN["MeshRegistry"]
    execN["executions"]
  end
  ledgerN["evidence ledger<br>.ai/repo/evidence/ledger.json"]
  gatesN["gates.yaml and scripts/ci"]
  executorN["one executor"]
  subgraph surfaces["projections"]
    mcpS["MCP"]
    httpS["HTTP API"]
    oasS["OpenAPI"]
    swS["Swagger UI"]
    cliS["CLI, checked by closure"]
    cockS["Cockpit"]
    genS["docs/generated"]
    siteS["site data and pages"]
  end
  codeN --> registryN
  shareN --> manifestN
  layerN --> manifestN --> indexN --> registryN
  indexN --> rulesN
  indexN --> planN
  ledgerN --> rulesN
  gatesN --> rulesN
  registryN --> executorN
  rulesN --> executorN
  planN --> executorN
  envN --> executorN
  devctxN --> executorN
  peersN --> executorN
  meshN --> executorN
  execN --> executorN
  executorN --> mcpS
  executorN --> httpS
  executorN --> cockS
  executorN --> cliS
  registryN --> oasS --> swS
  registryN --> genS --> siteS
  proseN --> siteS
  shellN --> layerN

Appendix B: surface map

To check any row, run bin/majordomus-cli capabilities projections --format json.

Appendix C: generation matrix

"Derived" means produced by a generator or computed on read. A dash means the entity is not on that surface.

Appendix D: governance and mesh maps

flowchart TD
  pol["policy.yaml<br>finish_requires, budgets, hook wiring"]
  vend["vendored rules<br>.ai/repo/rules/vendor/majordomus"]
  proj["project rules<br>.ai/repo/rules/project"]
  eff["effective rule set<br>additive, no override"]
  disp["doctrine dispatcher<br>lib/doctrine.sh, at doctor, check, finish, watch"]
  gy["gates.yaml<br>gates and path classes"]
  ci["validate.yml<br>planner selects gates by changed paths"]
  rpc["rule-proof-check<br>dangling refused, unproven ratcheted"]
  proofG["rule proof graph<br>ten states"]
  adr["ADRs<br>proposed, accepted by a person"]
  vend --> eff
  proj --> eff
  eff --> disp
  pol --> disp
  eff --> rpc
  gy --> ci
  eff --> proofG
  gy --> proofG
  adr -.-> proj

flowchart TD
  decl["mesh declaration<br>.ai/repo/mesh/majordomus.yaml, enabled false"]
  prov["providers<br>multicast, broadcast, rendezvous"]
  mgr["manager<br>one verification path, signatures, skew, trust label"]
  reg["MeshRegistry<br>presence TTL, retention, bound"]
  caps["mesh capabilities<br>status, nodes, identity, doctor, register"]
  board["peer board<br>per shared server, gathered across checkouts"]
  pcap["peers.list, peers.announce"]
  decl --> prov
  prov --> mgr --> reg --> caps
  board --> pcap

The two maps are separate on purpose. Nothing flows from the mesh registry into the peer board today.

Appendix E: claim audit

The references are to the tree at the commit this document was written on. A range such as :439-482 gives lines. A command in the last column is one you can run.

Downgraded while writing. Several claims were weakened after checking:

• "Nothing in the Cockpit names a capability": false (C13).
• "No kind writes to the repository" (CAPABILITIES.md), and the surfaces' own self-description saying the server "never writes to the repository" (about.rs:40, mcp/protocol.rs:312): contradicted by plan.transition and recover.orphans (C31).
• "Adding a capability is one block and nothing else": true only without a CLI path or a dedicated Cockpit page (§17.5).
• "Proof of function reaches Cockpit and docs": it reaches the API, MCP and generic pages as a state, not as a dedicated page (§11).
• "Cross-surface equality is tested": sampled, not generated (§14).
• "A gate proves a rule": inferred from runs:, and no gate verdict is recorded (§9, §10).

Appendix F: architecture debt

Each item is phrased so it can become an issue. The categories are: M manually registered, D duplicated, N not derived, E not exposed on every relevant surface, T not tested, V not evidenced, F not fully enforced, P prose that disagrees with code.