The development runtime

What owns the semantics of software development in this repository, where each one lives, which surface may decide what, and how far the code is from that boundary today.

The companion documents are DYNAMICITY.md, which decides where a fact lives, and CAPABILITIES.md, which decides how an operation is declared. This document is the third of that set: it decides where a semantic lives. The decision is ADR 0040; the rule is project.development-semantics-are-canonical@1.

Every count in this document was measured. The commands are in How this was measured; none of them is copied from prose, and a statement about behaviour that is not yet implemented is phrased as a target.

The invariant

The canonical development runtime is the capability registry of the Rust executable. Development semantics are capabilities of it. The Cockpit does not execute development semantics; it requests operations from the canonical runtime and subscribes to canonical state and events. The same sentence holds with "the CLI", "the HTTP API", "OpenAPI" or "MCP" in place of "the Cockpit".

A development semantic is any rule, derivation or transition over the plan, the active task, compiled context, a session, an execution, a peer, an event, evidence, an obligation or completion. "Is this issue ready?", "what does this task still owe?", "may this session close?", "which wave does this issue belong to?" — each has exactly one correct answer, and the runtime is where that answer is computed.

The measurement this rests on

Two executables serve this repository, and the line between them is not a layering.

bin/majordomus is a shell tool implemented under lib/. Its own help groups its commands as TASK, CONTEXT, MEMORY, RULES, PLAN and SYSTEM: start, check, finish, session, checkpoint, evidence, handover, decision, question, plan, adr, usecase. That list is the development lifecycle, and lib/ is the only writer of what it produces — lib/plan.sh:514-515 is the one place an issue or milestone YAML is written.

bin/majordomus-cli is the Rust executable. It owns the capability registry and every projection of it: MCP, HTTP, OpenAPI, Swagger, the Cockpit, the command line, the generated reference. Its help states the split in the negative: "The task lifecycle (init, start, check, finish, doctor, ...) is the shell tool bin/majordomus in the same repository; this executable does not implement those commands."

These are the measurements that make the consequence exact. Each states what is true, not how many; the command that reproduces the tally is in How this was measured.

The graph gives four withheld reasons: "asks the person something; a request/response surface would hang", "effect RepositoryMutation is above the machine ceiling LocalMutation", "no capability declares this command line, so no machine surface has a typed input schema to execute from", and "groups other commands; nothing to execute". Most of the graph is withheld from every machine surface, and the commonest reason is the third.

So the runtime, today, cannot change a single development object, and none of the lifecycle is reachable from the Cockpit, MCP or HTTP.

The Cockpit is not the offender. Its trees reference the layer exactly once, as a display label in apps/majordomus-cli/src/cockpit/pages.rs:1787; it reads no state and writes none. It is already the pure projection that COCKPIT.md and ADR 0013 require. The defect is on the other side: the runtime has no development semantics to offer, so a Cockpit asked to become a development surface has two options — reimplement the lifecycle, or shell out to bin/majordomus. Both create a second implementation, and the second one drifts.

The canonical model, in repository-native names

The repository already has a name for every stage a development surface needs. Introducing a synonym for one of them is a defect, not an extension. The mapping below is the model; a worker extending any stage converges on the name in the middle column.

Two stages the mandate's pipeline names separately are one thing here, and saying so matters more than the diagram: a development task is the existing task, not a new object beside it, and a workflow execution is an execution of a command of the command graph, not a third scheduler.

Ownership boundaries

                    ┌───────────────────────────────────────────────┐
                    │  THE LAYER  .ai/repo (shared) + .ai/local     │  storage
                    │  typed by share/kinds.yaml,                   │
                    │  discovered by .ai/repo/knowledge/sources.yaml│
                    └───────────────────────┬───────────────────────┘
                                            │  reads and writes
                    ┌───────────────────────▼───────────────────────┐
                    │  THE CANONICAL RUNTIME                        │
                    │  apps/majordomus-cli/src/capability/          │
                    │  one capability! per operation, typed in/out  │  semantics
                    │  exposure derived by command_graph/policy.rs  │
                    └──┬────────┬────────┬─────────┬────────┬───────┘
                       │        │        │         │        │         projections
                  ┌────▼──┐ ┌───▼───┐ ┌──▼───┐ ┌───▼───┐ ┌──▼─────┐
                  │Cockpit│ │HTTP+WS│ │OpenAPI│ │  MCP  │ │  CLI   │  surfaces
                  └───────┘ └───────┘ └───────┘ └───────┘ └────────┘

The layer owns storage. Every development object is a typed file of .ai/. Its kind is declared in share/kinds.yaml, whose declarative kinds the registry projection lists, its contract in share/schemas/majordomus/<kind>/<kind>.v1.schema.json, and its location in .ai/repo/knowledge/sources.yaml as a :(glob) pathspec. Three files agree or the object has no type and no authority.

The runtime owns semantics. One capability! declaration per operation, with a typed input and output. Where it is exposed is derived from its effect and interactivity by command_graph/policy.rs, never chosen per surface.

A surface owns presentation and nothing else. It renders capability output and posts capability input. It computes no status, decides no transition, reads and writes no file of the layer, and spawns no program to obtain a semantic. A surface that shells out owns the argument construction, the exit-code interpretation and the error rendering — three semantics, in the surface, undeclared.

Surface responsibilities

Storage: decided, and reused

No new datastore. Every decision below is the storage the repository already has.

The two event tiers, named. A durable state change is a ledger event whose name is registered in share/events.yaml. The typed execution stream is the live view of a runtime in motion and is never the record. A development capability that mutates state appends to the ledger; the stream carries the same change as it happens. Neither tier may hold a durable fact the other cannot see — which today it does, in both directions.

Executions stay non-durable. executions list visibly has nothing to read, and the temptation is a store. Rejected as written: the durable record already exists and is the ledger. The execution store stays bounded and in-process; durability is the ledger's job.

Data flow, mutation flow, event flow

Read. A surface asks a capability. The capability reads the index — objects discovered from sources.yaml, typed by kinds.yaml, validated against the kind's schema — or a derivation over it (plan.rs, graph.rs, product.rs, why.rs, obligations.rs). No surface reads a file.

.ai/** ──discovery──▶ index ──derivation──▶ capability ──projection──▶ surface

Mutate. Target flow. A surface posts a typed input to a capability of kind command. The capability validates against its input schema, applies the transition to the object in its canonical storage, appends a registered ledger event, and returns the new state. The same call over MCP, HTTP, the CLI and the Cockpit is one code path.

surface ──typed input──▶ capability ──▶ object in .ai/**  ──▶ ledger event ──▶ /events

Actual flow today. For the lifecycle's mutating commands, the surface is a terminal and the capability does not exist: bin/majordomus dispatches into lib/<name>.sh, which writes the object and appends the ledger line itself. That is the debt this document records, ratcheted in .ai/repo/development-semantics-baseline.txt.

Events. Durable: mj_ledger_append refuses a name that share/events.yaml does not declare and one missing a required field; history --event refuses to filter on an undeclared name; history --validate reports a stored line no reader recognises. Live: ExecutionStore::publish applies an event to the snapshot under one lock, refusing a transition ExecutionState::may_move_to does not allow, assigns the sequence, retains the event and hands it to subscribers — so a client reading the snapshot and a client reading the stream cannot disagree.

Consistency guarantees

What is not guaranteed today, stated so the list above is not read as more than it is: a development object written by lib/ is not validated against its capability's input schema, because there is no capability; and a fact that reaches the ledger does not reach the execution stream, or the reverse.

The derivation chain every exposed object follows

canonical declaration            capability!  under src/capability/builtin/<module>.rs
        │                        (or, for a layer object, its kind in share/kinds.yaml)
        ▼
serialization schema             CanonicalSchema from the typed input/output
        │                        (or share/schemas/majordomus/<kind>/<kind>.v1.schema.json)
        ▼
HTTP route + OpenAPI             src/http/router.rs, docs/generated/openapi.{json,yaml}
        │
        ▼
MCP tool or resource             majordomus://<kind>/<identity>, or a tool by capability id
        │
        ▼
Cockpit contract                 the page that renders that capability's JSON

Every link is generated. Nothing on the chain is written by hand, and a hand-written entry anywhere on it is a violation of project.rust-canonical-declaration@1 (ADR 0004) as much as of ADR 0040. The chain is checked by majordomus capabilities validate, majordomus generate --check, and the projection-closure and rust-generated gates.

For a layer object the chain begins one step earlier, at the document schema: a Markdown kind is described in <kind>.v1.proto (Header = front matter, Body = sections), from which the JSON Schema, the front-matter allow-list under share/allow/ and the body section requirements under share/sections/ are all generated.

Extensibility: adding a development semantic

Short by design. If this list grows, the architecture has regressed.

1. Declare one capability! in its module's file under apps/majordomus-cli/src/capability/builtin/, with its typed input, typed output and the input's BenchmarkCases. A new module is one module! plus one name in compose_modules!.
2. If it mutates, give it kind: command, and append a ledger event — adding its name to share/events.yaml with the command that writes it and the payload keys it requires.
3. Run majordomus generate, then majordomus capabilities validate. Every surface — HTTP, OpenAPI, MCP, the Cockpit page, the generated reference, the benchmark target — follows without a second registration.
4. Run majordomus usecase impact and close any coverage gap it names with a use case that executes.
5. If a shell command fronted the semantic, point it at the capability and remove its entry from .ai/repo/development-semantics-baseline.txt. The baseline may shrink and may not grow.

No other file is edited for the operation to exist everywhere it should.

The inventory

Measured, not recalled. Owner is who decides the semantic today; Mutation path is the only thing that may write it. A concept whose owner is lib/*.sh is debt against ADR 0040, not an architecture.

The development lifecycle

The runtime

Governance and surfaces

Gaps against the target pipeline

Ranked by what blocks a development surface most.

1. No mutating development capability exists. Only the execution and peer planes declare a capability of kind command. Every issue transition, session lifecycle event, checkpoint, handover, evidence attachment and completion decision is unreachable from MCP, HTTP and the Cockpit. Closing it: a kind: command capability per transition, ratcheted off .ai/repo/development-semantics-baseline.txt.
2. The command graph does not see the lifecycle's subcommands. Every tool node is a group at the first level; majordomus plan done <id> is not a node. So the exposure policy has nothing to judge and the completion engine nothing to offer. Closing it: declare the shell subcommands in share/commands.yaml, or make each one a capability and let the graph derive it.
3. Most lifecycle commands are interactive. The graph withholds them as "asks the person something; a request/response surface would hang". Interactivity is not a property a surface can work around. Closing it: project.commands-run-non-interactively@1, currently advisory.
4. Two disjoint event models. A durable ledger vocabulary and a live stream vocabulary, with no bridge between them. A Cockpit cannot show one activity feed. Closing it: a mutating development capability appends a registered ledger event and publishes the same change to the stream; neither tier holds a durable fact the other cannot see.
5. Completion is decided in two places. obligations.closure reads the contract; lib/finish.sh decides it. Two implementations of one contract. Closing it: the decision moves into the obligations module and finish asks it.
6. Compiled context has no capability. directories.list reports context contracts; the compiled, budgeted context a worker actually gets is lib/context.sh only, and DYNAMICITY.md already lists the provider table as an entity with no owner.
7. Executions are not durable. By decision, not by omission — but it means the Cockpit cannot show what ran before the current process. Closing it: the ledger, per §4.
8. Two writers of docs/generated/. src/generate.rs plus a shell set. Existing debt, already in HARDCODING_LEDGER.yaml territory, and it will bite any new generated development artifact.
9. The CLI is the least complete consumer, not the most. Fewer than half the built-in capabilities have a CLI projection — objects.get, repository.info, every plan.* and graph.* and health.report have none. So a person at a terminal reaches less of the canonical runtime than an MCP client does, which inverts the usual assumption that the CLI is the reference surface and the others catch up. Closing it: the exposure policy decides this from effect and interactivity; a query withheld from the CLI is either a policy decision worth stating or an omission worth fixing, and today nothing says which.
10. Concepts with a shell owner and no runtime capability at all: session contexts, knowledge, skills, prompts, questions, history, search.
11. ADR number allocation is unguarded. 0039 is claimed by two different files on two branches today. A development surface that proposes decisions makes this worse.

Enforcement

The rule is project.development-semantics-are-canonical@1, class: blocking. Per this repository's own doctrine — and consistent with every project rule, none of which carries an x-majordomus block — it is enforced by a CI gate rather than a lib/ validator.

scripts/development-semantics-check is the gate, wired as development-semantics in the structure job of .ai/repo/ci/gates.yaml. It reads tracked files only and needs no build. It decides two things:

• Backing. A public command of share/commands.yaml whose class mutates and whose writes names a development object tree, for which docs/generated/registry.json declares no capability of kind command in the matching module.
• Surface purity. A reference to .ai/repo, .ai/local or a majordomus executable inside apps/majordomus-cli/src/cockpit/** or share/cockpit/**, excluding a generator's own provenance header.

Every finding it reports today is in .ai/repo/development-semantics-baseline.txt: the unbacked mutating commands — adr, checkpoint, decision, evidence, finish, handover, init, migrate, plan, question, rules, session, start, update and usecase — and the one Cockpit display label. A finding not in the baseline fails; a baseline line matching nothing also fails, so the ratchet tightens instead of rotting.

Two things the gate does not decide, so that its silence is not read as a pass:

• Whether a derivation in a surface is a semantic or presentation. A template that pluralises a count is not a second implementation; one that computes readiness is. A gate that guessed would be unauditable. A reviewer decides, exactly as majordomus.decision-threshold@1 leaves its own threshold to a reviewer.
• Who writes a development object. A write in shell has no reliable syntactic shape, and a grep for the object trees would report every reader as a writer. Deciding it would take the writers declared as data — share/commands.yaml's writes field extended to name the writing function, reconciled against lib/ the way exit_codes already is. That is an open item, not a check.

How this was measured

# the two programs and the split between them
bin/majordomus --help
bin/majordomus-cli --help

# what the registry holds, which capabilities can mutate, and the module/kind breakdown
bin/majordomus-cli capabilities list --format json > caps.json
jq -r '{count, summary}' caps.json
jq -r '.capabilities[] | select(.provenance.source=="builtin")
        | "\(.id)\t\(.kind)\t\((.exposure|keys)|join(","))"' caps.json
jq -r '.capabilities | group_by(.module)
        | map("\(.[0].module)\t\(length)") | .[]' caps.json

# the commands, their origins, every withheld reason, and the depth per origin
bin/majordomus-cli commands graph --format json > cg.json
jq -r '.commands|group_by(.origin)|map("\(.[0].origin)\t\(length)")|.[]' cg.json
jq -r '[.commands[].projections.withheld|select(.)]
        | group_by(.)|map("\(length)\t\(.[0])")|.[]' cg.json
jq -r '.commands|group_by(.origin)
        | map({o:.[0].origin,
               d:(map(.path|length)|group_by(.)|map({d:.[0],n:length}))})|.[]' cg.json

# executions keep nothing across a process; the stream's message vocabulary
bin/majordomus-cli executions list
bin/majordomus-cli executions protocol

# the effective rules, the class split, and which of them the tool enforces
bin/majordomus rules list --json

# the durable ledger event names
grep -oE '^\s+- id: [a-z._]+' share/events.yaml

# the generation targets
bin/majordomus-cli generate --help

# the web surfaces and their mounts
bin/majordomus-cli web list

# who writes what
grep -rln 'project/issues\|project/milestones' lib/ bin/ scripts/
grep -rln 'docs/generated' lib/ bin/ scripts/
grep -rn '\.ai/\|bin/majordomus' apps/majordomus-cli/src/cockpit/ share/cockpit/*.js

# sizes and the test surface
cat lib/*.sh | wc -l ; ls test/cases/*.sh | wc -l
ls apps/majordomus-cli/tests/*.rs | wc -l

# the gate over this document's own rule
scripts/development-semantics-check

Counts of anything in this repository go stale; measure rather than trust a number written here, including these.