Doctor

Where it lives

The command that acts on it

majordomus doctor [--json]

See it refuse, and accept

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.

# 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

$ majordomus doctor

# 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

$ majordomus doctor

What enforces it

• majordomus.knowledge-integrity blocking enforced by check, doctor Every knowledge record is one evidenced, well-formed assertion. It is valid against its schema with no unknown key, its identity is unique and equals its file name, a verified record carries provenance, every reference it names resolves, a superseded record says what replaced it or why it was rejected, a candidate never claims to be verified, and no record carries a conversation.
• majordomus.candidates-reviewed advisory enforced by doctor A review queue that grows without bound is not reviewed. More candidates than the policy cap, a candidate that has waited longer than the policy age, or a candidate the tree does not track, is reported, not stopped; both numbers are declared once in the policy.
• majordomus.ai-layout-integrity blocking enforced by doctor, watch The repository's AI layer is real: the manifest declares a format this executable reads and every section it names exists, the checkout-local half is ignored by git and nothing under it is tracked, and no project data remains under the pre-.ai .majordomus/ path.
• majordomus.layout-integrity advisory enforced by doctor The directories the durable commands write into are installed rather than created on first use.
• majordomus.catalogue-integrity blocking enforced by doctor, watch Every use case and application describes the tool in terms the tool has — each command, doctrine and claim it names exists, and the two catalogues reference each other in both directions.
• majordomus.command-surface blocking enforced by doctor, watch Every command the binary dispatches is described by the shipped registry, every command the registry declares public is dispatched, and a command is public exactly when the usage text lists it.
• majordomus.doctrine-wiring-integrity blocking enforced by doctor Every doctrine in this registry resolves to a validator that exists, is reached from every command it names, propagates failure, is proved by a test, and is run by CI — and every validator in the source is declared here.
• majordomus.enforcement-wiring blocking enforced by doctor Every enforcement the policy declares is invoked by the hook it names, from a file the dispatcher will actually execute, without swallowing the exit code.
• majordomus.command-coverage blocking enforced by doctor, watch Every public command has a behavioural test and a negative test, computed from the registry and the coverage each case declares about itself rather than from a list someone maintains.
• majordomus.knowledge-observed blocking enforced by doctor, watch While episodes keep closing, the knowledge they produced must keep being derived. A closed episode no derivation followed, once it is older than the freshness threshold, is a stopped writer; a lifecycle whose close path never calls the deriver while the policy switch is on is a writer that was never started.
• majordomus.context-budget blocking enforced by doctor, watch The always-loaded projection stays within its line budget, every reference in it resolves, it states no count that will go stale, and the assembled context fits the builder's own budget.
• majordomus.retention-caps blocking enforced by doctor, watch The ledger, the handovers, the checkpoints and the session records stay under the caps the policy sets, so durable state does not grow without bound.
• majordomus.rule-package-integrity blocking enforced by doctor, watch The repository's effective rule set is real: the vendored baseline matches its manifest file for file, every rule resolves with its dependencies and no two claim one identity, and no project rule reuses the vendored namespace.
• majordomus.skill-integrity blocking enforced by doctor, watch Every skill the repository declares parses against the skill contract, names the directory it lives in, carries its sections, describes itself in terms no other skill uses, and every skill or example it refers to exists.
• majordomus.use-case-coverage blocking enforced by doctor, check, finish Every public command, and every guaranteed claim and MCP tool the policy asks for, is named and run by at least one active use case whose scenario executes against the real tool; a gap is a failure or a report according to the policy, never silence.

What is guaranteed

• ○guaranteed The installer verifies an artifact's digest and inspects its archive before anything is unpacked, and any failure leaves the previous installation workingproved by test/cases/85_installer.sh
• ○guaranteed Every enforcement the policy declares is reconciled against what actually runsproved by test/cases/03_update.sh
• ○guaranteed Wiring is found in a hook or in any subhook of the directory that hook dispatches toproved by test/cases/14_wiring_dispatcher.sh
• ○guaranteed Every rule the tool enforces is declared once, as a rule object in the repository's effective set, and doctor proves each one is reached by the command that claims to run itproved by test/cases/18_doctrine_wiring.sh
• ○guaranteed A use case or application cannot name a command, doctrine or claim that does not exist, and the two catalogues cannot disagree about which applies to whichproved by test/cases/28_catalogue.sh
• ○guaranteed Every repository-relative reference in the always-loaded file is proven to resolveproved by test/cases/03_update.sh
• ○guaranteed A hardcoded count in the always-loaded file is a failureproved by test/cases/03_update.sh
• ○guaranteed The append-only ledger and handover store have retention caps that are checkedproved by test/cases/02_doctor_basic.sh
• ○guaranteed Every continuity store is proven reachable through its own command, not merely present on diskproved by test/cases/25_continuity_lifecycle.sh
• ○guaranteed The rule baseline is vendored into the repository with a manifest naming every file and its hash, and a hand edit is detected and refusedproved by test/cases/67_rule_dag.sh
• ○guaranteed The effective rule set is resolved as a dependency graph in a deterministic order, and a set that does not resolve is applied by nothingproved by test/cases/67_rule_dag.sh
• ○guaranteed The tool runs read-only from any location, and two locations of one version agree about one repositoryproved by test/cases/65_tool_root_independence.sh
• ○guaranteed The public command surface is declared, and reconciled against the dispatcherproved by test/cases/30_command_registry.sh
• ○guaranteed Every public command has a behavioural test and a negative test, computed rather than rememberedproved by test/cases/31_command_coverage.sh
• ○guaranteed A quantity about tokens, context or cost typed into hand-written prose is refused, and a claim bound to a metric cannot be guaranteed while its evidence does not standproved by test/cases/431_economics_claims_gated.sh
• ○guaranteed Every public command is named and run by an active use case, a guaranteed claim or an MCP tool without one is a named gap, and the policy says which gaps fail doctor, check and finishproved by test/cases/94_use_cases.sh
• ○guaranteed A use case's scenario executes against the real tool in a disposable repository, every step's exit code and output are asserted, and the normalised evidence is what the site showsproved by test/cases/94_use_cases.sh
• ○guaranteed From the files a change touched, the tool names the commands, rules, use cases, scenarios and behavioural cases affected, and scaffolds a draft for a capability no use case coversproved by test/cases/94_use_cases.sh
• ○guaranteed A live scenario may only run commands share/commands.yaml declares read-only, names no setup, and asserts an obligation only where something owes one; every other shape is refused by usecase validate with exit 10proved by test/cases/359_live_scenarios.sh
• ○guaranteed A live scenario is not selected by a bare usecase run, its evidence is written under the ignored local half, and it never raises a command to covered; an undischarged obligation is reported unmet, never failedproved by test/cases/359_live_scenarios.sh
• ○guaranteed Every skill is validated against the allow-list generated from its schema, its directory, its sections and its references, a violation names the file and every reason, and a repository with no skills is reported rather than passedproved by test/cases/95_skills.sh
• ○guaranteed A provider's end event and its compaction event derive the knowledge the episode produced into candidate records under the tracked tree, from the ledger and git and never from a conversation, whether or not a task is active, and record that they did so in the ledgerproved by test/cases/563_knowledge_is_derived_at_the_boundary.sh
• ○guaranteed A policy switch that is off derives nothing and says so; a derivation that fails inside a provider hook is recorded as provider.event.failed and the hook still exits 0proved by test/cases/565_knowledge_switch_and_failure_leave_evidence.sh
• ○guaranteed Every knowledge record is schema-valid with no unknown key, uniquely identified, evidenced when verified, resolves every reference it names, and carries no conversation; check, doctor and `majordomus knowledge check` refuse a record that is notproved by test/cases/707_knowledge_check_refuses_malformed_records.sh
• ○guaranteed A repository in which episodes close and no knowledge derivation follows within the stale threshold is reported as a stopped writer by doctor and watch, and the finding clears when a derivation is writtenproved by test/cases/708_health_sees_a_stopped_knowledge_writer.sh
• ○guaranteed More candidates than the policy cap, or a candidate older than the policy age, is an advisory doctor finding that names them; both numbers are declared once in the policyproved by test/cases/711_candidates_are_reviewed_not_accumulated.sh

Rules this command runs

Doctrines whose enforced_by names doctor. Enforcing a rule and being governed by one are different relations, so they are listed separately.

• majordomus.knowledge-graph
• majordomus.knowledge-integrity
• majordomus.candidates-reviewed
• majordomus.ai-layout-integrity
• majordomus.layout-integrity
• majordomus.ledger-integrity
• majordomus.policy-completeness
• majordomus.bootstrap-integrity
• majordomus.catalogue-integrity
• majordomus.context-integrity
• majordomus.policy-integrity
• majordomus.adr-integrity
• majordomus.decision-records
• majordomus.dag-integrity
• majordomus.command-surface
• majordomus.doctrine-wiring-integrity
• majordomus.enforcement-wiring
• majordomus.command-coverage
• majordomus.handover-integrity
• majordomus.lifecycle-observed
• majordomus.knowledge-observed
• majordomus.project-integrity
• majordomus.projection-integrity
• majordomus.context-budget
• majordomus.deployment-contract
• majordomus.prompt-capture
• majordomus.prompt-continuity
• majordomus.prompt-integrity
• majordomus.questions-store-integrity
• majordomus.retention-caps
• majordomus.roadmap-integrity
• majordomus.rule-package-integrity
• majordomus.schema-integrity
• majordomus.session-records
• majordomus.record-changed-files
• majordomus.session-lifecycle
• majordomus.skill-integrity
• majordomus.use-case-coverage

The moments this answers

• → opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository Each provider reads its own hand-edited file, nothing relates them, and which contract applies depends on which tool is open.
• → asked what the workers did last night and had only transcripts to grep A conversation log records what was said, not what happened, so the operational question has to be answered by a person reading prose.
• → found the rule for that directory in a README no session ever loaded A local rule is either in the always-loaded file, where every session pays for it, or beside the code, where nothing relates it to the path being edited.
• → watched the always-loaded instruction file grow past a thousand lines Everything important gets appended to the always-loaded file, so every session pays for every rule and reads none of them carefully.
• → found a rule everyone believed was enforced and nothing ever invoked Every artefact of enforcement exists — the rule, the script, the test — and no path connects them, so the control is fiction.
• → found code that contradicted a decision the repository had written down The decision was recorded and the implementation went the other way, because nothing relates a decision to the paths it governs.
• → read a promise in the README that no test stood behind A sentence describing what the software does is written once and never connected to anything that would fail if it stopped being true.
• → pasted a command from the documentation and watched it fail Examples are written once, in prose, and nothing ever executes them again.
• → could not say why one provider was used for that work and another for this Provider and model selection is made implicitly, per session, and recorded nowhere, so it cannot be reviewed or repeated.
• → published a page that promised more than any test could support Public material is written by a different act from the code, so it drifts ahead of the behaviour and nothing brings it back.
• → reviewed a well-written contribution that broke a convention it had no way to discover Assistants let anybody produce plausible contributions at volume; the conventions that make one correct are still only in the maintainers.