Layer

Where it lives

The command that acts on it

majordomus init [--extend] [--personal | --shared]

See it refuse, and accept

init is the only command that runs before the .ai/ layer exists. It seeds the manifest, the policy, the profiles, the vendored rule baseline and the empty sections from the skeleton, and it never touches .ai/local/.

# An empty git repository: no AI layer at all.
git commit -q --allow-empty -m base 2>/dev/null || true

$ majordomus init

# 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 init

# 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 init --extend

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.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.context-integrity blocking enforced by doctor, watch 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.
• majordomus.adr-integrity blocking enforced by doctor, watch 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.
• majordomus.session-records blocking enforced by doctor, watch 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.
• 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.

What is guaranteed

• ○guaranteed The context that applies to a path is composed from the layer's scoped documents, root to target, in one deterministic order with provenance, and a tree that does not validate resolves nothingproved by test/cases/69_context_documents.sh
• ○guaranteed Every directory of the layer carries a context document, the exemption is declared by the contract that governs the subtree, and a descendant may narrow that requirement but never weaken itproved by test/cases/69_context_documents.sh
• ○guaranteed The impact of a change set on the scoped context is reported from git — the documents, the scopes below them, moves with their ancestry, tracked sources to review, and stale projections — and an unrelated change reports nothingproved by test/cases/70_context_impact.sh
• ○guaranteed The repository's AI layer is one directory whose manifest names every section, readable without the toolproved by test/cases/01_init.sh
• ○guaranteed A layer installed with --personal is one person's own in a shared repository: it changes no tracked file, no .gitignore line and nothing git status shows, and the command that makes the claim verifies itproved by test/cases/2979_a_personal_layer_changes_nothing_shared.sh
• ○guaranteed A repository on the pre-.ai layout is migrated once, explicitly, with a previewed plan and a verified backup of its local state, and the command is idempotent afterwardsproved by test/cases/66_migrate_legacy.sh
• ○guaranteed A skill is one directory under the layer's skills section holding SKILL.md, discovered by the source class `skill` the shell tool and the Rust executable both read, so that adding the file is the whole registration and the catalogue, the command, doctor, MCP and the site all derive from itproved by test/cases/95_skills.sh
• ○guaranteed An operational moment is one file under the layer, discovered rather than registered, and answered by the command line, the HTTP API, the OpenAPI document, MCP, the derived graph and the website with nothing else changedproved by apps/majordomus-cli/tests/why.rs
• ○guaranteed Every reference a moment makes resolves against the thing it names, and one that does not is an error carrying the nearest candidateproved by apps/majordomus-cli/tests/why.rs
• ○guaranteed A diagnosis of a reader's own symptoms is deterministic counting over the catalogue's metadata, and every recommendation names the moments that produced itproved by apps/majordomus-cli/tests/why.rs
• ○guaranteed A closed execution episode is a shared object of the layer, written by the tool from git and the ledger, valid against a contract that admits no conversation and no absolute path, and discovered rather than registeredproved by test/cases/63_session_records.sh
• ○guaranteed An architecture decision is one file under the layer's adrs section, validated against the decision contract, with an identity nothing else claims, reciprocal supersession, and every reference it makes resolvingproved by test/cases/99_adr.sh
• ○guaranteed A decision states what it put in force as typed references, each one validated, and the reverse direction — what a rule, a document, an implementation or a case was decided by — is read from the knowledge graph rather than written down a second timeproved by test/cases/99_adr.sh
• ○guaranteed majordomus adr propose writes a decision with status proposed and refuses to write any other status, allocates its identity under a lock so concurrent workers never collide, and records what the decision was derived fromproved by test/cases/99_adr.sh
• ○guaranteed A product feature is one file under the layer, discovered rather than registered, and answered by the command line, the HTTP API, the OpenAPI document, MCP, the derived graph, the capability matrix and the website's homepage and feature pages with nothing else changedproved by test/cases/97_product_features.sh
• ○guaranteed The product is filed under a few domains declared once as files of the layer; a feature names exactly one, and every domain's members, interfaces, guarantees and use cases are derived from the features that name it, so a stable feature cannot be left out of the product map without the model refusing itproved by test/cases/800_product_domains.sh
• ○guaranteed A second derivation over the same evidence writes nothing, says so, and leaves the working tree unchanged; the record id is derived from the episode and a digest of the evidence so the same fact always lands in the same fileproved by test/cases/564_knowledge_derivation_is_idempotent.sh
• ○guaranteed verified is written only by promote with evidence on stdin or by a person editing the file, never by the deriver; promotion moves the record to curated/ and rejection supersedes it with a reason, each leaving a ledger lineproved by test/cases/709_knowledge_promotion_is_an_act.sh
• ○guaranteed knowledge observe records one observation.recorded ledger line with its kind, subject, statement and typed evidence references, inside an open episode, inside a task or outside one, and refuses any other shape, or the absence of an episode, without writingproved by test/cases/980_a_session_records_what_it_observed.sh
• ○guaranteed Each observation an episode recorded becomes, at that episode's end and with no model, a candidate of its own that says what it is about, and knowledge candidates groups the records about one subject with the episodes behind them; an episode that observed nothing records that it found nothingproved by test/cases/981_an_observation_becomes_a_grouped_candidate.sh
• ○guaranteed Every candidate derived from an observation carries a route — platform, enforcement, generator, documentation or project — derived from its subject's structure and never from its wording, and in a repository that adopted the tool its own share/ routes projectproved by test/cases/982_a_candidate_is_routed_by_what_it_is_about.sh

The moments this answers

• → 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.
• → went looking for why we chose this and found a chat log A decision that was reached in a session is stored where only that session can read it, so it is neither reviewable nor discoverable.
• → 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.
• → 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.
• → looked at the bill and could not say which of it produced anything Consumption is measured per account and outcomes are recorded per person, so the two can never be joined.
• → found the same thing explained three times, slightly differently Every hand-maintained copy of a fact drifts on its own schedule, and a reader cannot tell which copy is the current one.
• → spent the first hour in an unfamiliar repository working out what was normal here What is conventional in a codebase is knowledge held by its regulars, so every arrival — human or machine — pays for it again.
• → 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.
• → could not reproduce a result because nothing recorded the state it came from The result is recorded and the conditions that produced it are not, so it is an anecdote rather than a measurement.
• → was asked who made a change and under what policy, and had only a commit Attribution stops at the commit, so what authorised a change, what verified it and what governed it are unrecoverable.