Decisions and knowledge that compound instead of evaporating

What was decided, why, and what was rejected is recorded where the next session reads it, and a durable decision becomes an architecture record with typed links to what it put in force.

status

stable

exposed through

• ✓cli
• ✓api
• ✓mcp
• ✓cockpit
• ✓docs

area

decisions

context

What it does

majordomus decision add records what was decided, why, what was rejected and which task decided it, superseded later by an entry that names it and never edited. majordomus adr lists, shows, proposes and checks the architecture decision records under the layer; a record extracted from a local decision is proposed, never accepted in the same act, and its related field carries typed references — a rule, a claim, a file, a test — that the graph turns into edges, so the reverse question, what decided this rule, is derived rather than written twice.

Knowledge is declared, not collected: the source classes say which files carry it, the index reads them through git, and search, knowledge and history answer over that index without anyone reading everything.

What it does not do

Nothing is promoted automatically. A decision recorded while working stays in the checkout's local state until a person judges it durable enough to write down as a record. There is no embedding, no vector store and no summariser; retrieval is over declared identities and text, and a reference that resolves to nothing is a finding, not a phantom node.

The capabilities behind it

The capability modules of the executable this feature names, each with the capabilities it composes. The command line, the HTTP route, the MCP tool and the reference beside every row are projections of one declaration, not four registrations.

The commands that run it

• majordomus decision work

  Record a decision that was made between real alternatives, with its reason, and read them back.

• majordomus adr conclude

  The repository's architecture decisions as objects: list, show, propose one with provenance, and validate the whole set.

• majordomus knowledge inspect · read-only

  The compiled index over what this repository states.

• majordomus search inspect · read-only

  Find a durable record without reading all of them, in authority order.

• majordomus history inspect · read-only

  Read the append-only ledger back, filtered by task, event or time.

• majordomus question work

  Open a question that blocks acceptance, resolve it, and list what is still open.

The objects it is made of

Kinds of the layer. Each is a schema, a source class and a file on disk; the number beside it is what this repository holds today, counted at build time.

• adr33
• knowledge1
• document210

What it answers

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

• →watched a session undo last week's decision, for the reason it was made
• →asked what the workers did last night and had only transcripts to grep
• →read three roadmaps for one project and believed none of them
• →spent an hour discovering something the repository already knew, twice
• →watched one worker revert another worker's change, on purpose
• →found finished work on a branch that nobody ever merged
• →went looking for why we chose this and found a chat log
• →found code that contradicted a decision the repository had written down
• →closed an issue whose acceptance criteria nothing had actually checked
• →was asked how far the milestone had got and had to go and ask four people
• →let a fast, cheap session make a decision the whole codebase now lives with
• →could not say why one provider was used for that work and another for this
• →looked at the bill and could not say which of it produced anything
• →lost a failure a worker had already reproduced, because the session ended
• →found the same thing explained three times, slightly differently
• →watched a worker spend a day on an approach that had already been ruled out
• →was asked who made a change and under what policy, and had only a commit

The rules that hold it

• blockingArchitecture decision integritymajordomus.adr-integrity
• advisoryDecision recordsmajordomus.decision-records
• blockingThe decision thresholdmajordomus.decision-threshold
• advisoryExternalise decisions and durable statemajordomus.externalise-decisions

What is guaranteed

• guaranteed A decision is recorded with its reason and its task, and is superseded by a later entry rather than edited
• advisory A decision record without a task, a head and a reason is reported, and does not block
• 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 resolving
• 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 time
• 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 from
• guaranteed Durable records are searchable literally, across kinds, without an index
• rejected Ranked or semantic retrieval over durable records is deliberately not implemented
• guaranteed The ledger is readable back as operational history, filtered by task, event and time

Executable use cases

• knowledgeRecord a decision as data, and prove the tool cannot accept it for you
• continuityRecord a decision so the next worker can find it
• knowledgeRead back what happened, and keep the ledger within its cap
• mcpFind an object of the layer without reading everything