Skip to content

majordomus doctor

Is Majordomus itself healthy, and is every enforcement it declares actually wired here?

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.

Syntax

majordomus doctor [--json]

Lifecycle

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

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

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.

Checks, in order:

  1. policy.yaml parses; version supported; no unknown keys at any level.

  2. Every profiles/*.yaml parses; every profile referenced by policy exists; no unknown keys.

  3. 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.

  4. 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.

  5. The projection marked always_loaded: true is within context.always_loaded_budget_lines.

  6. Every repository-relative path referenced from the always-loaded projection resolves.

  7. 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.

  8. Retention caps not exceeded on state/ledger.jsonl and state/handovers/.

  9. 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

Failure modes

Implementation

Demonstration

Guarantees this command carries