Doctrine states the invariant. Policy applies it. A rule makes it decidable. Enforcement makes ignoring it impossible. Everything below is this repository's own governance, measured.
Most repositories that "adopt AI" write down how they would like to work. The writing is the whole intervention: a file of conventions, a paragraph in a README, a prompt that asks nicely. Nothing decides anything, so nothing changes, and six months later the document describes a project that no longer exists.
A rule that nothing enforces is a wish with syntax highlighting.
Majordomus separates three things that are usually one pile of Markdown, and gives only the last of them any authority.
01 / the layers
Each layer answers a different question and lives on a different clock. Mixing them is what produces a governance document that is simultaneously too vague to check and too specific to survive a refactor. The counts are this repository's, measured when the page was built.
| layer | the question it answers | what it is, here | lifetime | today |
|---|---|---|---|---|
| Doctrine | What must remain true? | a principle in the portable rule package; technology-neutral, and checked by nothing | years | 10principles |
| Policy | How is the invariant applied here? | one policy file, projected into the instruction file of every worker that opens the repository | months to years | 3projections |
| Rule | What exactly must, or must not, be? | a rule file with a class, a validator, the commands that run it and the test that proves it | months | 40rules |
| Enforcement | How does a machine decide it? | a validator, dispatched from a command, wired to a git hook and to CI | the implementation that answers it | 40validators |
| Diagnostic | What broke, and what fixes it? | a finding naming the rule, the file, the reason and the exit code the command leaves with | one run | 4reporting commands |
flowchart TD
L0["Doctrine<br/><small>10 principles · years</small>"]
L1["Policy<br/><small>3 projections · months to years</small>"]
L2["Rule<br/><small>40 rules · months</small>"]
L3["Enforcement<br/><small>40 validators · the implementation that answers it</small>"]
L4["Diagnostic<br/><small>4 reporting commands · one run</small>"]
L0 --> L1 --> L2 --> L3 --> L4
L4 -. "exit 10 · the commit does not land" .-> L2The last edge is the whole argument. A diagnostic that a worker may ignore is documentation; one that leaves the command non-zero, fails the hook and stops the commit is governance.
02 / one chain, end to end
The repository's AI layer is real: the manifest declares a format this executable reads and names sections that exist, the local half is ignored by git with nothing under it tracked, and no project data remains under the pre-.ai path.
03 / the whole thing
124 nodes and 202 edges, projected from the rule package and the wiring the validators declare. Turn an edge kind off to ask a narrower question: which rules descend from which invariant, which rules depend on another being true first, what a single command actually decides.
Select a node to see what it is and what it touches.
The interactive view could not load. The list below is the same graph.
Define done before executing principle
An invariant of the standard package. It is not checked; the rules under it are.
Escalate capability and effort only when justified principle
An invariant of the standard package. It is not checked; the rules under it are.
Externalise decisions and durable state principle
An invariant of the standard package. It is not checked; the rules under it are.
Handovers transfer state, not transcripts principle
An invariant of the standard package. It is not checked; the rules under it are.
Load minimum sufficient context principle
An invariant of the standard package. It is not checked; the rules under it are.
One worker, one clear scope principle
An invariant of the standard package. It is not checked; the rules under it are.
Sessions are workers, not memory principle
An invariant of the standard package. It is not checked; the rules under it are.
Verify outcomes, not activity principle
An invariant of the standard package. It is not checked; the rules under it are.
ai-layout-integrity rule · blocking
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.
checkpoint-freshness rule · advisory
A task whose last checkpoint is older than its profile's interval is reported, not stopped.
layout-integrity rule · advisory
The directories the durable commands write into are installed rather than created on first use.
ledger-integrity rule · blocking
Every line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.
policy-completeness rule · blocking
Every policy value the code reads is declared in the skeleton policy, and no reader carries its own default for one.
bootstrap-integrity rule · blocking
The path from a human reader to the AI layer is unbroken — README.md names AGENTS.md, every generated instruction file points at .ai/README.md, and none of them carries a rule of its own.
catalogue-integrity rule · blocking
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.
context-integrity rule · blocking
Every directory of the AI layer carries a context document, each one carries the contract, they compose into one deterministic chain for every path, and a tree that does not validate resolves nothing.
policy-integrity rule · blocking
The policy and every profile parse, declare version 1, and carry no key the schema does not define.
adr-integrity rule · blocking
Every architecture decision the repository holds parses against the decision contract, claims an identity nothing else claims, and every relation and reference it makes resolves.
blocker-resolution rule · blocking
No task can be completed while any question on this branch is unresolved; it can still be finished as blocked, partial, no_match or failed.
decision-records rule · advisory
Every entry in decisions.md carries the task, the head and the reason, so a decision can be found by the worker who needs it.
dag-integrity rule · blocking
The issue dependency graph is acyclic, every edge names an issue that exists, and no issue is executing ahead of a dependency that is not done.
command-surface rule · blocking
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.
doctrine-wiring-integrity rule · blocking
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.
enforcement-wiring rule · blocking
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.
command-coverage rule · blocking
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.
handover-integrity rule · blocking
The resolver runs and reports either the record for this worktree and branch or its clean absence; a malformed record is never silently skipped, and a record describing a history this checkout no longer has is reported.
note-integrity rule · blocking
Every outcome needs a note carrying the sections that outcome requires, and no transcript.
profile-requirements rule · blocking
A profile may demand more than the shared contract — a regression test, a decision record — and finish refuses without it.
project-integrity rule · blocking
Every milestone and issue file parses, carries the id its filename claims, and contains no key nobody reads.
projection-integrity rule · blocking
Every generated instruction file exists, matches the stamp it carries, and is never silently overwritten after a hand edit.
context-budget rule · blocking
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.
deployment-contract rule · blocking
A deployment of the executable is a canonical object of the layer against a closed contract; the container definition and the provider configuration are projections of it, never a second description.
prompt-capture rule · blocking
A repository that declares prompt capture has it wired below the model and proven by running it; the archive stays ignored and untracked, every prompt is present as both a record and a rendering, and neither carries anything the model said.
prompt-integrity rule · blocking
Every repository-local prompt asset renders, and every token in it is one the renderer knows.
questions-store-integrity rule · blocking
Every entry in open-questions.md parses, because a gate that cannot read an entry can be bypassed by mistyping one.
retention-caps rule · blocking
The ledger and the handover directory stay under the caps the policy sets, so durable state does not grow without bound.
roadmap-integrity rule · blocking
No document is a second authority for the roadmap. While a hand-written roadmap table exists, it can neither list a version no milestone declares nor hide one the model does.
rule-package-integrity rule · blocking
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.
schema-integrity rule · blocking
The order the rules apply in is written down rather than left in the code; every kind the tool reads declares a schema, every schema is named by a kind, and every path under the repository's AI layer is claimed by a source so that nothing is carried through unvalidated.
scope-integrity rule · blocking
A task touches only the paths it claimed; work found elsewhere is not accepted as done.
session-records rule · blocking
A closed execution episode is written once, into the layer's sessions section, against a schema that admits what the repository can prove and nothing else.
session-lifecycle rule · blocking
Where a provider fires session events, the episode is opened and closed by that provider's hook rather than by the model, the start event hands the worker the bounded briefing the policy declares, and the working context each open freezes stays under the ignored half of the layer, carries the declared keys, and never carries a conversation.
skill-integrity rule · blocking
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.
state-consistency rule · blocking
The task record still describes this checkout — same branch, and HEAD at or ahead of the recorded commit.
task-continuity rule · advisory
A task finished as partial or blocked should leave a handover record, not only a note section.
use-case-coverage rule · blocking
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.
verification-integrity rule · blocking
Completion requires a verification command that actually ran and exited 0; its exit code and duration are recorded.
obligation-closure rule · blocking
A task that declares obligations reaches the outcome completed only when each one is established by the tool or has evidence, and that evidence still describes the tree or the commit it was taken over.
mj_validate_adr validator
Decides the rule. Declared in lib/adr.sh.
mj_validate_ai_layout validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_blockers validator
Decides the rule. Declared in lib/check.sh.
mj_validate_bootstrap validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_budget validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_catalogue validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_checkpoint validator
Decides the rule. Declared in lib/check.sh.
mj_validate_command_coverage validator
Decides the rule. Declared in lib/commands.sh.
mj_validate_command_surface validator
Decides the rule. Declared in lib/commands.sh.
mj_validate_context validator
Decides the rule. Declared in lib/context_docs.sh.
mj_validate_continuity validator
Decides the rule. Declared in lib/finish.sh.
mj_validate_dag validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_decisions validator
Decides the rule. Declared in lib/check.sh.
mj_validate_deployments validator
Decides the rule. Declared in lib/deployment.sh.
mj_validate_doctrine_wiring validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_layout validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_ledger validator
Decides the rule. Declared in lib/check.sh.
mj_validate_note validator
Decides the rule. Declared in lib/finish.sh.
mj_validate_obligations validator
Decides the rule. Declared in lib/evidence.sh.
mj_validate_policy validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_policy_defaults validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_profile_requirements validator
Decides the rule. Declared in lib/finish.sh.
mj_validate_project validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_projection validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_prompt_capture validator
Decides the rule. Declared in lib/capture.sh.
mj_validate_prompts validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_questions_store validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_resolver validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_retention validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_roadmap validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_rule_package validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_schema_integrity validator
Decides the rule. Declared in lib/doctor.sh.
mj_validate_scope validator
Decides the rule. Declared in lib/check.sh.
mj_validate_session_lifecycle validator
Decides the rule. Declared in lib/session_context.sh.
mj_validate_session_records validator
Decides the rule. Declared in lib/session.sh.
mj_validate_skills validator
Decides the rule. Declared in lib/skills.sh.
mj_validate_state validator
Decides the rule. Declared in lib/check.sh.
mj_validate_use_case_coverage validator
Decides the rule. Declared in lib/usecase.sh.
mj_validate_verification validator
Decides the rule. Declared in lib/finish.sh.
mj_validate_wiring validator
Decides the rule. Declared in lib/doctor.sh.
majordomus check enforcer
A command a worker or a git hook runs. It dispatches the validators wired to it.
majordomus doctor enforcer
A command a worker or a git hook runs. It dispatches the validators wired to it.
majordomus finish enforcer
A command a worker or a git hook runs. It dispatches the validators wired to it.
majordomus watch enforcer
A command a worker or a git hook runs. It dispatches the validators wired to it.
test/cases/01_init.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/02_doctor_basic.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/03_update.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/04_start_check.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/06_finish.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/103_obligations.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/14_wiring_dispatcher.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/16_profiles.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/17_doctrine_enforcement.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/18_doctrine_wiring.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/19_end_to_end.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/21_decision_question.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/22_history.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/23_context.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/24_prompt_search.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/25_continuity_lifecycle.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/28_catalogue.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/28_no_hardcoded_values.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/29_prompt_capture.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/30_command_registry.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/31_command_coverage.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/32_schema_integrity.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/44_model_doctrine.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/49_roadmap_doctrine.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/54_session_lifecycle_hooks.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/63_session_records.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/67_rule_dag.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/69_context_documents.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/84_deployment_contract.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/94_use_cases.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/95_skills.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
test/cases/99_adr.sh test
A behavioural case. It proves the validator answers, not that the rule is written down.
04 / what it costs to be honest
A model that only ever renders its successes is a brochure. These come out of the same join as everything above, and there is nowhere to put them where they would not show.
Advisory: the command reports and carries on. 36 of the 40 stop it instead. An advisory rule is a rule whose enforcement is not finished, and saying so is cheaper than pretending.
05 / next
A profile is not a workflow, a workflow is not an interface, and none of them is a model. Four independent axes, one declaration each, every projection derived.
Read more → referenceAll the rules, each with the validator that decides it, the commands that run it and the test that proves it.
Read more →