docs/CONCEPTS.md

What it is

URI

majordomus://document/docs/CONCEPTS.md

Kind

document

Identity

docs/CONCEPTS.md

Path

docs/CONCEPTS.md

Provenance

declared

Media type

text/markdown

As a capability

document.docs/CONCEPTS.md

Front matter

{}

Content

# Concepts

The vocabulary, in ordinary engineering language. Everything Majordomus prints, and
every file it writes, uses these words and no others.

| Term | Meaning | Where it lives |
|---|---|---|
| **policy** | the one canonical, provider-neutral operating policy | `.ai/repo/policy.yaml` |
| **profile** | a named bundle fixing capability class, effort, verbosity, presentation, context toggles, verification, checkpoint interval, and output contract for a task class | `.ai/repo/profiles/<name>.yaml` |
| **projection** | a provider-specific instruction file generated from the policy, headed with a stamp naming the command that regenerates it, the policy hash and the hash of its own content | `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or any target the policy names |
| **stamp** | the first line of a generated file, or the begin marker of a generated region: the policy hash it was rendered from and the hash of the content it covers; content that differs from its stamp was hand-edited | `<!-- generated by \`majordomus update\` ... (policy ..., content ...) -->` |
| **task** | the one active unit of work in a checkout | `.ai/local/state/current.yaml` |
| **session** | one execution episode of one worker: it opens, it may touch several tasks, and it closes into an immutable record that references what the episode produced and copies none of it | `.ai/local/state/sessions-open/<provider session>.yaml` while open — one episode per provider session, with `session-current.yaml` pointing at this checkout's — then `.ai/repo/sessions/` once closed |
| **knowledge record** | one assertion about the repository with a class, a status, an epistemic stance and provenance that resolves; a `candidate` is what the tool derived from the ledger and git at an episode boundary, `verified` is what a person promoted with evidence, and neither is ever a conversation | `.ai/repo/knowledge/candidates/<id>.md`, `.ai/repo/knowledge/curated/<id>.md`, `knowledge derive`, `knowledge promote`, `majordomus://knowledge/<id>` |
| **observation** | one line a worker writes about friction it met — its kind (friction, workaround, defect, drift, repetition), what it is about, the statement and typed evidence — which the episode boundary turns into a candidate saying what it is `about` and its `route` (platform, enforcement, generator, documentation, project), read from the subject's structure; recurrence is the candidates about one subject, grouped on read | `knowledge observe`, `observation.recorded`, `knowledge candidates` (groups) |
| **envelope** | what a closed session record is: identity, a temporal boundary, and references — never a copy of the records it names | `.ai/repo/sessions/<file>.md` |
| **scope** | the normalised set of repository paths a task may touch, or that a context document applies to; and, for the repository as a whole, what a worker reads of it and what it never reads, declared once, out over in, a path matching nothing out | `scope:` in the task record; `scope:` and `paths:` in a context document; `.ai/repo/scope.yaml`, read by `scope` and `majordomus://scope` |
| **claim** | the same scope, seen from another worktree; overlap is reported, never blocked | reported by `start` and `check --overlap` |
| **use case** | a task a person performs with the tool, as one object: the commands, rules, claims, responsibilities and applications it names, and a scenario the tool executes against itself; its maturity is observed from the evidence, never written | `.ai/repo/use-cases/<id>.md`, `usecase`, `majordomus://use-case/<id>`, `/use-cases/<id>/` |
| **application** | a context the tool suits: when it fits, when it does not, and the use cases it composes | `.ai/repo/applications/<id>.md` |
| **checkpoint** | a compact progress record inside an active task, capped by policy so that it stays quotable rather than becoming a report; also updates `checkpoint_at`, from which staleness is measured | `.ai/local/state/checkpoints/`, `checkpoint`, `check --checkpoint` |
| **handover** | an append-only continuation record with computed front matter and required sections, written when a worker stops; published for another machine as a signed record that carries only portable state, and resumed there on a plan that checked its trust, lineage and source | `.ai/local/state/handovers/`; published: `refs/majordomus/continuity`, `continuity publish`, `sync`, `plan`, `resume` |
| **decision** | what was decided, why, what was rejected, and which task decided it; superseded by a later entry naming it, never edited | `.ai/local/state/decisions.md` |
| **open question** | something unresolved, recorded as state rather than prose; any entry naming the active task refuses `finish --outcome completed` | `.ai/local/state/open-questions.md` |
| **rule** | a portable Markdown document with YAML front matter: identity, class, dependencies, and for the ones the tool enforces an `x-majordomus` block; the effective set is the vendored baseline plus the repository's own | `.ai/repo/rules/vendor/majordomus/rules/*.md`, `.ai/repo/rules/project/*.md`, read by `rules list` |
| **doctrine** | a rule the tool enforces: its `x-majordomus` block names the validator that decides it, the commands that run it, and the tests that prove it; `blocking` stops a command, `advisory` reports and does not | the resolved rule set, read by `doctrine`, `check --rule`, and every enforcing command |
| **validator** | the function that decides one doctrine; it reports findings and never decides their level, because the doctrine's class does that | `mj_validate_<name>` in `lib/` |
| **history event** | one line of the ledger: what happened, when, for which task, at which head | `.ai/local/state/ledger.jsonl`, read by `history` |
| **context** | the assembled briefing for whoever works next: durable state in authority order, within a line budget, with every exclusion named | printed by `context`; never stored |
| **context document** | a Markdown file under the `.ai/` tree whose front matter declares `schema: context/v1` and `kind: context`: an identity that survives a move, a scope (its directory, its subtree, or listed paths), the providers and audience it addresses, and how it composes with its ancestors | `.ai/**/README.md`; the file names the manifest's `context.documents` requires |
| **effective context** | the documents that apply to one path, computed: the ancestor chain admitted by each document's scope, least specific first, then `order`, then path; filtered by provider, audience and status; superseded documents dropped, `final` ones never superseded | `context resolve <path>`; `context explain` says why |
| **authority order** | git, then task and profile, then blockers, then authored records, then history — the order sections appear in and the reverse of the order they are dropped in | `context` |
| **skill** | a provider-neutral procedure for one bounded kind of work: front matter under the skill schema over a body with a purpose, a procedure and an output contract; discovered by the source class `skill`, never registered, loaded only when the task is about it | `.ai/repo/skills/<id>/SKILL.md`, `skills` |
| **working context** | the bounded context of one execution episode, composed on every read from the episode's open record, git now against git at the open, and the checkpoints, decisions and questions its own ledger lines carry; beside it, the opening snapshot of what the builder resolved when the episode opened, frozen as evidence. Local and stays local — it names one machine — and never a transcript | `session context`; the snapshot `.ai/local/session-contexts/<stamp>--<session-id>.md`, `session context --path` |
| **prompt asset** | a small, versioned, provider-neutral framing in the repository, rendered against a closed set of state tokens | `.ai/repo/prompts/<name>.md`, `prompt` |
| **record resolution** | choosing the right prior record: same worktree and branch, else same branch, else nothing — never repository-wide | `handover --resolve`, `checkpoint --show`, `context` |
| **outcome** | one of `active`, `completed`, `partial`, `blocked`, `no_match`, `failed`, `handed_over`; the only field a command changes after `start` | `outcome:` in the task record |
| **finish contract** | the checklist `finish` evaluates before accepting `completed`; every line printed pass or fail | `verification.finish_requires` in the policy |
| **ledger** | append-only events written only by Majordomus; retention-capped | `.ai/local/state/ledger.jsonl` |
| **wired** | an enforcement whose executable resolves and is invoked, without a swallowed exit code, by the hook or CI file the policy names | checked by `doctor` |
| **drift** | a deterministic disagreement between policy, projection, state, and git | reported by `watch` |
| **divergence label** | `exact`, `advanced`, `diverged`, `different_context`: how a recorded head relates to the current one | computed at read time from git |
| **capability class** | `fast`, `standard`, `strong`, `strongest`; never a vendor model name | `capability:` in a profile |
| **effort** | `low`, `medium`, `high`, `xhigh`, `max`; reasoning depth, independent of everything else | `effort:` in a profile |
| **verbosity** | `terse`, `concise`, `detailed`; how much the worker says, independent of how hard it thinks | `verbosity:` in a profile |
| **presentation** | `machine`, `engineering`, `summary`; the final layer, chosen by the profile | `presentation:` in a profile |
| **capability** | one thing the Rust executable exposes: a typed query with one handler, or a declarative object of the layer read as a resource; defined once, with a canonical id, and projected to MCP, HTTP, OpenAPI, the command line and the generated reference | `apps/majordomus-cli/src/capability/`, `majordomus capabilities list` |
| **execution** | one call of one capability that was given an identity so that it can be watched rather than waited for: a lifecycle, an input as it was stored, typed events, and an output or an error. It lives in the process that accepted it and does not outlive it | `majordomus run`, `majordomus executions`, `/api/v1/executions*`, `/cockpit/executions` |
| **execution event** | one typed fact about an execution — created, started, a step, progress, a log line, a diagnostic, cancelled, completed, failed — in an envelope with a protocol version and a dense sequence number; the same value whether it is read over the live channel, over HTTP or on the command line | `majordomus executions events`, `GET /events` |
| **preflight** | what is proven about a checkout, as opposed to what it is: a verdict per claim — git, episode, briefing, task, handover, policy, rules, ADRs, the shared server and its surfaces, peers, recorded test runs, rule enforcement, projections, generated docs, the deployment — each with the evidence it rests on; the value every entry surface renders | `majordomus env preflight`, `/api/v1/environment/preflight`, `majordomus://environment/preflight`, the Cockpit overview |
| **verdict** | `verified`, `active`, `fresh`, `stale`, `degraded`, `unavailable`, `failed`, `unknown`, `not_applicable`: what the repository can show about one claim; the first three cannot be produced without evidence | `verdict:` of a preflight check |

| **enforcement mode** | how a rule is enforced, derived from what its `x-majordomus` block names and never declared: `dispatched` (a validator a command runs), `gated` (tests a CI gate runs), `reviewed` (only a stated reason no machine can check it), `declarative` (nothing) | `majordomus-cli rules report`, ADR 0048 |
| **rule proof** | where one rule's enforcement actually stands: `proven`, `inputs_unchanged`, `stale`, `gated`, `failing`, `not_run`, `reviewed`, `unrunnable`, `dangling`, `unproven`; a failing test makes it `failing`, and otherwise it is the weakest of the tests that can carry proof; a named proof that does not exist is `dangling` and fails the `rule-proof` gate | `majordomus-cli rules show <id>`, `GET /api/v1/rules/rule` |
| **guarantee** | a public statement of what the tool does, with its source, implementation, test and status, published on the site; the file calls each one a claim | `docs/CLAIMS.yaml`, `docs/claims/`, `/guarantees/` |
| **evidence** | a recorded execution of a test: runner, outcome, commit, working-tree state, digest and origin, the latest per test; its state against the tree being asked about is derived, never stored | `.ai/repo/evidence/ledger.json`, `majordomus-cli evidence record`, `evidence show` |
| **proof state** | what a guarantee's evidence says about this tree: `proven` (nothing changed since the run), `inputs_unchanged` (something changed, not its own inputs), `stale` (its inputs changed), `failing`, `not_run`, `unrunnable`, `no_test`; freshness is a relation to the tree, not a timestamp | `majordomus-cli evidence claim <id>` |
| **gate** | a repository-owned check with the path classes that select it; a gate that has never reported for a change is `queued`, never a pass | `.ai/repo/ci/gates.yaml`, listed by `check` |
| **obligation** | something a task promises to prove (`tests`, `docs`, `generated`, `commit`, `pages`, …), declared at `start` and required by `finish`; some are established from git or the published site rather than recorded | `start --requires`, `share/obligations.yaml` |
| **milestone** / **issue** | an outcome specification and an execution contract: dependencies, scope, acceptance criteria, required evidence and transition timestamps — and no status field | `.ai/repo/project/milestones/`, `.ai/repo/project/issues/` |
| **derived status** | an issue's `DONE`, `VERIFY`, `ACTIVE`, `BLOCKED` or `READY`, computed from its timestamps, its dependencies and whether its required evidence is covered; a status ahead of its blockers is reported | `majordomus plan status` |
| **execution wave** | the Kahn layer of an issue in the dependency graph; ready issues in one wave that share paths are a scope conflict, because dependencies say what could run together and scope says what safely can | `majordomus plan waves` |
| **worktree topology** | a branch's canonical checkout path, `<repository>-wt/<branch>`, derived from its name and never registered; a feature-branch commit from anywhere else is refused | `majordomus-cli worktree status`, the pre-commit hook |
| **shared server** | the one server a checkout runs for every client, elected through a lease; serves MCP, HTTP, OpenAPI, Swagger UI and the Cockpit | `majordomus-cli serve status`, `.ai/local/state/mcp/server.json` |
| **peer** | one attached MCP client on a checkout's board: a position id (`p1`), a client name, a transport and its announcements; the checkout it carries is the durable half of its identity | `majordomus_peers`, `GET /api/v1/peers` |
| **announcement** | a peer's stated intent and scope, optionally under a name; replaced by announcing again under the same name, kept in the server's memory only | `majordomus_announce` |
| **overlap** | two scopes that are equal or contain one another on a path boundary, reported between announcements and between active tasks; awareness, never a lock | `majordomus_peers`, `start`, `check --overlap`, `context` |
| **mesh node** | a Majordomus instance identified by an Ed25519 key, seen through multicast, broadcast or a rendezvous endpoint with a presence TTL; observed, never authoritative, off by default | `majordomus-cli mesh status`, `.ai/repo/mesh/majordomus.yaml` |
| **repository environment** | one typed snapshot of what a checkout is — project, version control, toolchains, layer, workflows, providers, services, diagnostics — with provenance for every value; the shell banner is one renderer of it | `majordomus-cli env`, `GET /api/v1/environment` |
| **effect** | what running a capability changes: `read`, `process_state` or `repository_mutation`; the last is always a command reached by `POST`, named in the MCP instructions and in OpenAPI's `x-majordomus-effect` | `docs/generated/registry.json` |
| **feature** | a product capability as an object of the layer, naming the modules, commands, kinds, rules, claims and use cases it is made of; the site's feature pages and the interface matrix are derived from it | `.ai/repo/features/`, `majordomus-cli product matrix` |
| **domain** | one of the few things the product controls, as an object of the layer with its promise and the failure it answers; a feature names exactly one, and the domain's members, surfaces and evidence are derived from the features that name it | `.ai/repo/features/domains/`, `majordomus-cli product domains` |
| **intent** | what must become true, as a typed record above the milestones that realise it; its stage is derived from the plan, each criterion is met only by current evidence, an issue names the criterion it serves, and closed work the evidence contradicts is refused | `majordomus intent list`, `intent validate`, `intent realization`, `/cockpit/intents`, `.ai/repo/project/intents/` |

## Four kinds of state

Every value the tool shows is one of these, and the kind decides who may write it and what may overwrite it.

| Kind | What it is | Examples | May it overwrite canonical state? |
|---|---|---|---|
| **canonical** | written by a person or a worker in a commit | a rule, an ADR, the policy, an issue's dependencies, a capability declaration | — |
| **derived** | computed deterministically from canonical and observed inputs, never edited | issue status, waves, rule proof, proof state, `docs/generated/` | no: regenerated, and a hand edit fails the drift check |
| **observed** | measured now, true only at its timestamp | HEAD, a dirty tree, attached peers, a mesh node's presence, whether a service answers | no: it expires |
| **inferred** | a heuristic's best guess | keyword relevance in the ranked working set | no: capped below every declared relation |

## What each concept saves

The concepts exist because each one replaces something a worker would otherwise have to redo in every session. The saving is repeated work avoided, not storage.

| Concept | What it saves every later worker from | What it compresses | Authored or derived |
|---|---|---|---|
| rule | being told the same constraint again, and checking it by eye | a paragraph of instructions into an identity with an enforcement mode | authored once |
| doctrine | rediscovering why a family of rules exists, and running their checks by hand | a principle plus the validator that decides it | authored once |
| ADR | re-deciding an architecture question | a debate into decision, alternatives and consequences | authored, accepted by a person |
| decision | re-asking a smaller settled question | one line of what, why and what was rejected | authored |
| context document | reading every instruction to find the ones for these paths | the instructions that apply to one path | authored, resolved per path |
| compiled context | reconstructing the project from history | git, task, rules, decisions and the last handover into one budgeted document | derived per session |
| checkpoint | losing the last hour when a session dies | recent progress into a capped note | authored or derived |
| handover | replaying a transcript | a session into objective, state and next action, with its commit | body authored, identity derived |
| issue and waves | working out what can run next | a dependency graph into ready sets and safe parallel layers | authored records, derived status |
| scope and overlap | discovering a collision in a merge | who claims which paths | authored scope, derived overlap |
| evidence | re-establishing whether something was tested against this code | a run into outcome and commit | recorded, state derived |
| finish contract | a reviewer checking everything by hand | the conditions of "done" into lines that pass or fail | policy authored, verdict derived |
| one capability declaration | updating the CLI, API, MCP, Cockpit and docs separately | one operation into every interface | authored once, projections derived |

How much each saves is measurable, and none of it is measured here. That would take a benchmark comparing workers on the same task with and without the record: time to the first correct change, input size, corrective prompts, repeated file reads and outcome quality. A number belongs in this table only after that has been run and recorded.

## Words with two meanings

Two words are used for two different things in this repository, and each is kept because renaming it would break published identities.

- **claim** means an overlapping scope seen from another worktree (the row above) and also an entry of `docs/CLAIMS.yaml`, a public guarantee. On the site the second is always called a guarantee.
- **projection** means a provider instruction file rendered from the policy (the row above) and, more broadly, any surface derived from a canonical declaration: the HTTP routes, the OpenAPI document, the MCP tools and the generated reference are projections of the capability registry.

## The two outcomes people confuse

`no_match` means the work was done and the thing sought does not exist.
`failed` means the work could not be done.

"We searched and found nothing" and "the source could not be searched" look alike in
a transcript. A supervisor that cannot tell them apart cannot decide whether to retry,
escalate, or accept. The typed field decides; prose never does.

## Two words that are one word

**task** is the active unit of work in a checkout, and nothing else. A capability that
takes long enough to watch is not "a task": it is a capability whose handler reports as it
goes and stops when it is asked to, and one call of it is an **execution**. The word was
available and was not taken, because a vocabulary with one word for two things is the thing
this table exists to prevent.

## What is deliberately not a concept

No agent, persona, role, tier, or registry or catalogue of workers. A supervisory
tool that adds nouns becomes the thing it supervises. The only actor Majordomus knows is
`owner`, a free-form string on the task record. The capability registry of the Rust
executable indexes the tool's own surface, never a worker, and is derived from the layer
and the code on every start.

## Task, session, handover: three objects, three questions

They overlap in time and are easy to collapse into one, and each collapse loses something
specific.

A **task** answers *what is being worked on, under what constraints, within which paths*.
It is scoped, it has a profile, and it outlives the worker: a task begun on Tuesday can be
continued on Thursday by somebody else.

A **session** answers *what one worker did between sitting down and stopping*. It is not
scoped and it constrains nothing. It may span several tasks, and one task may be spanned
by several sessions. It is the only object that can answer which work happened together
and in what order.

A **handover** answers *what the next person needs in order to continue this work*. It is
authored, deliberate, rare, and it has required sections.

Collapse the session into the task and you lose the episode: two decisions recorded an
hour apart under different tasks look unrelated, because nothing records that one worker
made both in one sitting. Collapse the session into the handover and you get a
transcript — a narrative of an episode rather than a set of pointers to what it produced,
which is the failure mode this whole design exists to avoid. Collapse the task into the
session and scope becomes meaningless, because an episode does not have one.

## The two records people confuse

`checkpoint` and `handover` look alike — both are append-only Markdown with computed
front matter — and treating them as one thing costs you both.

A checkpoint is written often and read whole. It says what was true a few minutes ago and
what comes next, in a few lines, so that the next briefing can quote it verbatim. The
policy caps its length, and a body over the cap is refused rather than truncated.

A handover is written rarely and read deliberately. It has required sections, it is
refused if any is empty, and it is the package another worker resumes from.

The cap is what keeps them distinct. Without it, checkpoints grow into reports, reports
are too long to include in a briefing, and the briefing degrades to a pointer — which is
where the tool started before either record existed.

## Absence is a concept

`No relevant handover.` is an answer, not a failure. Resolution considers the same
worktree and branch, then the same branch, then stops. A record from an unrelated branch
is never offered, because a worker cannot tell that borrowed context is wrong until it has
acted on it. Absence is better than incorrect memory.

## What is deliberately not a concept, still

No agent, persona, role, tier, registry, or catalogue of prompts. `prompts/` holds a few
reusable framings, not a library; nothing ranks them, and nothing loads one unless asked.
No summariser, no embedding, no vector store, no transcript. Majordomus stores, validates,
resolves, projects and verifies. It never calls a model.