Sessions, prompts and handovers that outlive the conversation

A session ends and the work does not: what the next worker needs is a typed record checked against git, not a transcript somebody hopes to find.

status

stable

exposed through

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

area

context

coordination

What it does

A handover is an append-only record whose identity fields — branch, head, working tree, changed files — are computed from git and refused when a body tries to author them, and whose required sections are refused when empty. The next session resolves the right one for its worktree and branch, never a repository-wide newest note, and reads how far git has moved since as a label rather than a guess. Checkpoints are small by policy so they can be quoted whole into the next briefing.

A session is the episode itself: it opens when the provider says so, may span several tasks, and closes into a record that references what the episode produced and copies none of it. The provider's own lifecycle hooks draw that boundary, capture the person's raw prompts into the checkout-local half of the layer, and hand the opening episode a briefing built from what the last one left. Prompt assets in the repository are reusable framings, rendered against the task's state.

What it does not do

It stores no transcript and summarises none; the schemas have no field for one. It does not hook the worker's runtime beyond the events the provider publishes, and it does not decide what is worth remembering: the worker writes the required sections.

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 context work · read-only

  What the next worker needs to know now, in authority order and within a budget.

• majordomus checkpoint work

  Record compact progress inside the active task, so the next worker does not start over.

• majordomus handover conclude

  Write an append-only continuation record, and resolve the most relevant prior one.

• majordomus session begin

  Open, inspect and close one execution episode.

• majordomus capture work

  Record the person's raw prompts from a provider hook as a record with its renderings, draw the episode boundary from the provider's own lifecycle hooks, install those hooks, and report what each provider actually does here.

• majordomus prompt work · read-only

  List, show and render the repository's own prompt assets, substituting known tokens only.

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.

• session11
• prompt4

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.

• →re-explained the same context to a brand-new session
• →watched a session undo last week's decision, for the reason it was made
• →found a task "in progress" that nobody had touched for three weeks
• →asked what the workers did last night and had only transcripts to grep
• →found the rule for that directory in a README no session ever loaded
• →spent an hour discovering something the repository already knew, twice
• →watched the always-loaded instruction file grow past a thousand lines
• →found five worktrees and could not say which of them still mattered
• →had two sessions writing into one checkout without either knowing
• →went looking for why we chose this and found a chat log
• →found code that contradicted a decision the repository had written down
• →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
• →spent the first hour in an unfamiliar repository working out what was normal here
• →reviewed a well-written contribution that broke a convention it had no way to discover
• →watched a worker spend a day on an approach that had already been ruled out
• →could not reproduce a result because nothing recorded the state it came from
• →was asked who made a change and under what policy, and had only a commit

The rules that hold it

• blockingHandover integritymajordomus.handover-integrity
• blockingThe episode boundary is drawn below the model, and its working context is localmajordomus.session-lifecycle
• blockingSession records are shared objects with a closed field setmajordomus.session-records
• blockingPrompt capture is proven, or reported unavailablemajordomus.prompt-capture
• advisoryTask continuitymajordomus.task-continuity
• advisoryCheckpoint freshnessmajordomus.checkpoint-freshness
• blockingNever store or summarise transcriptsproject.never-store-transcripts
• advisoryHandovers transfer state, not transcriptsmajordomus.handovers-carry-state

What is guaranteed

• guaranteed handover writes an append-only record with computed front matter and required sections
• guaranteed Handovers carry durable facts, never conversation transcripts
• guaranteed A checkpoint is a capped progress record with computed identity, and a body over the cap is refused rather than truncated
• guaranteed The right prior record is resolved by worktree and branch, and an unrelated one is never offered
• guaranteed The context a worker is given is assembled from durable state in authority order, and what a profile excludes is excluded
• guaranteed State read back is labelled exact, advanced, diverged or different_context against git
• 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 registered
• guaranteed A provider hook opens the episode below the model and hands the worker what the last one left, records what a compaction is about to discard, and closes the episode with a continuation record beside its envelope
• guaranteed A declared provider hook captures the person's raw prompts below the model, and doctor proves it by running it
• guaranteed Every repository-local prompt asset renders, and an unknown token is a failure
• guaranteed Every continuity store is proven reachable through its own command, not merely present on disk

Executable use cases

• continuityHand unfinished work to the next session
• continuityCheckpoint long work so a stop costs minutes, not the day
• continuityRecord what one worker did in one sitting
• continuityKeep the prompts that started the work, below the model rather than around it
• continuityHave the session opened and closed without anybody remembering to