State

Where it lives

The command that acts on it

majordomus start "<task>" --scope <path>[,<path>...] [--profile <name>] [--owner <who>]

See it refuse, and accept

start records what you are about to do and which paths it may touch. The scope is a claim you will be held to by check and by finish.

# 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 start narrow the parser --scope lib

# ... and an active task scoped to lib, with work done inside that scope.
. "$FIXTURE_SETUP/installed.sh"
"$MJ" start "narrow the parser" --scope lib >/dev/null
echo work >> lib/a

$ majordomus start something else --scope lib

What enforces it

• 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.ledger-integrity blocking enforced by check, doctor, watch Every line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.
• majordomus.decision-records advisory enforced by check, doctor, watch 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.
• majordomus.handover-integrity blocking enforced by doctor, watch 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.
• majordomus.state-consistency blocking enforced by check, finish, watch The task record still describes this checkout — same branch, and HEAD at or ahead of the recorded commit.

What is guaranteed

• guaranteed Every line of the append-only ledger is a well-formed event, and a malformed line is a failure rather than a skipped recordproved by test/cases/22_history.sh
• advisory A decision record without a task, a head and a reason is reported, and does not blockproved by test/cases/21_decision_question.sh
• guaranteed Identity fields on every state record are computed from git and never authoredproved by test/cases/04_start_check.sh
• guaranteed State read back is labelled exact, advanced, diverged or different_context against gitproved by test/cases/04_start_check.sh
• guaranteed A checkpoint is a capped progress record with computed identity, and a body over the cap is refused rather than truncatedproved by test/cases/20_checkpoint.sh
• guaranteed A decision is recorded with its reason and its task, and is superseded by a later entry rather than editedproved by test/cases/21_decision_question.sh
• guaranteed Checkout-local state lives under .ai/local/, is ignored by git, and is absent on a fresh clone or worktreeproved by test/cases/01_init.sh
• guaranteed The ledger's event vocabulary is closed, on the way in and on the way outproved by test/cases/33_event_registry.sh
• rejected A task record has no dependencies; sequencing between sessions is not represented

The moments this answers

• → re-explained the same context to a brand-new session Repository knowledge that only ever existed in a conversation has to be re-transmitted by hand to every worker that follows.
• → watched a session undo last week's decision, for the reason it was made A decision whose reason lived in a conversation cannot be reviewed, only re-argued — by a worker with less information than the first one had.
• → found a task "in progress" that nobody had touched for three weeks A status that was authored rather than computed is true at the moment of writing and decays silently from then on.
• → 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.
• → spent an hour discovering something the repository already knew, twice A worker learns something expensive about the codebase, uses it once, and it dies with the session because nothing turned it into a durable record.
• → watched one worker revert another worker's change, on purpose A worker sees an unexplained change in its path, judges it wrong, and removes it — correctly, on the evidence it had.
• → found five worktrees and could not say which of them still mattered Isolation is cheap to create and expensive to reason about: nothing records what a worktree was for or whether its work landed.
• → 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 a substantial change that no issue, ticket or plan ever asked for Work arrives with no bounded contract behind it, so its scope, its acceptance criteria and its ownership are all decided after the fact.
• → let a fast, cheap session make a decision the whole codebase now lives with Capability is dialled down for cost and nothing distinguishes the tasks where that is prudent from the ones where it is expensive.
• → lost a failure a worker had already reproduced, because the session ended A failure observed inside a session is described in that session and nowhere else, so the next one starts from the report rather than the evidence.
• → watched a worker spend a day on an approach that had already been ruled out Negative results are the majority of experimental output and the part nobody records, so the search space is re-explored.
• → 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.