majordomus doctor

It checks governance only: is Majordomus itself healthy, and is every enforcement it declares actually wired here?

read-only
system
active task optional
--json

The primary guarantee is wiring reconciliation — a declared enforcement that no hook invokes, or whose exit code a hook swallows, is a failure rather than a passing line. It reads nothing of the checkout's server, its lease or the mesh: a stale server is reported by `majordomus serve status`, the mesh by `majordomus mesh doctor`, and the server's own health by GET /api/v1/health and GET /api/v1/ready.

Syntax

majordomus doctor [--json]

Lifecycle

Set up
Begin
Work
Verify
Conclude
Inspect

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

Reads

.ai/repo/policy.yaml
.ai/repo/profiles/
git hooks
.ai/local/state/
.ai/repo/rules/

Writes

Nothing. This command is read-only.

Exit codes

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

0 ok
2 usage
10 contract unmet
12 missing artifact

Is every declared enforcement actually wired?

doctor's primary guarantee is reconciliation: for each enforcement the policy declares, the path must exist, be executable, and be invoked by the artifact named in wired_by without its exit code being swallowed. Everything else it reports is secondary to that.

The policy declares enforcement that nothing runs

hooks installed: no

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 doctor

Output contains

FAIL wiring
doctor-on-commit

exit 10

This is the failure the tool exists to catch. The policy says a check runs on every commit; nothing runs it. Declared and unwired is worse than absent, because it reads as protection.

Both hooks in place and honouring the exit code

hooks installed: yes

Given this repository

# Installed, and the two enforcements the policy declares are actually in place as hooks.
. "$FIXTURE_SETUP/installed.sh"
mkdir -p .githooks
printf '#!/bin/sh\n%s doctor || exit $?\n' "$MJ" > .githooks/pre-commit
printf '#!/bin/sh\n%s finish --check || exit $?\n' "$MJ" > .githooks/pre-push
chmod +x .githooks/pre-commit .githooks/pre-push
git config core.hooksPath .githooks

Run

$ majordomus doctor

Output contains

OK wiring
doctor: 0 failure

exit 0

doctor names the file that does the wiring, so the report is checkable rather than reassuring. A hook that invoked the command and discarded its exit code would still be reported as unwired.

Reference

Is the supervisory layer real here? Read-only. Blocking by design: intended to run from a pre-commit hook and from CI.

It checks governance only — the policy, the profiles, the wiring of every declared enforcement, the projections, the records and their retention. It reads nothing of the checkout's server, its lease or the mesh, so a clean report says nothing about whether the server answering for this checkout is current (I2707). The runtime is read by:

Question	Where it is read
Is the server answering for this checkout current, or stale?	`majordomus serve status`
Is the mesh healthy here: identity, trust, link, runtime, journal?	`majordomus mesh doctor`
What does the server report about itself, the mesh included?	`GET /api/v1/health` (`health.report`)
Can this process answer: lease held, executable current?	`GET /api/v1/ready` (`health.ready`)

majordomus doctor --help prints the same before its usage.

Checks, in order:

policy.yaml parses; version supported; no unknown keys at any level.
Every profiles/*.yaml parses; every profile referenced by policy exists; no unknown keys.
Enforcement wiring. For every entry in policy.enforcement: path resolves (on PATH, repository-relative, absolute, or as an executable path on the hook line itself) and the artifact named by wired_by exists, is executable, invokes majordomus <first arg>, and does not swallow its exit code with || true or || exit 0. When the hook is a dispatcher, the invocation is looked for in the hook file and in every file in its <hook>.d/ directory; the finding names whichever file actually carries it. A subhook that carries the invocation but is not executable is reported as not wired, because the dispatcher skips it. wired_by: manual is reported as unverified, never as wired. Declared-but-not-wired is 10.
Every projections[].target exists, its provider has a template, and its entry in the content matches the stamp it carries. Missing or unstamped → 12; mismatch → 10 (hand-edited). For mode: region the hash is taken over the region alone; absent or malformed markers are reported as such.
The projection marked always_loaded: true is within context.always_loaded_budget_lines.
Every repository-relative path referenced from the always-loaded projection resolves.
No hardcoded counts in the always-loaded projection (a digit sequence adjacent to words like agents, files, apps, commands, skills, rules).

Checks 5 to 7 judge generated content only. For a region projection that is the region and never the host document, so that every failure doctor reports can be fixed by editing the policy.
Retention caps not exceeded on state/ledger.jsonl and state/handovers/.
Environment probes: bash version, git, jq and shellcheck if present. Reported as INFO. Nothing in doctor needs a tool beyond bash, git, and a checksum command.

$ majordomus doctor
OK   policy      .ai/repo/policy.yaml — parsed, version 1
OK   profiles    4 files — parsed
FAIL wiring      finish-contract — bin/majordomus is not invoked by .git/hooks/pre-push  [reproduce: grep -n 'majordomus finish' .git/hooks/pre-push]
OK   projection  CLAUDE.md — content matches its stamp
FAIL budget      CLAUDE.md — 212 lines, budget 150  [reproduce: wc -l CLAUDE.md]
OK   links       3 projections — all references resolve
OK   retention   ledger 412 lines, cap 5000
INFO env         bash 3.2.57, git 2.45, yq 4.44, jq 1.7
doctor: 2 failures
$ echo $?
10

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.

Behaviour

Implementation

Demonstration

fixtures/doctor.json

Tested by test/cases/34_command_fixtures.sh, which replays the fixture and compares it with what the command prints.