Hand unfinished work to the next session

setup: active-task
given:
  - 'an active task scoped to lib, with work done inside that scope'
steps:
  - id: checkpoint
    run: ['checkpoint']
    stdin: checkpoint-body.md
    note: 'a short progress record inside the task'
    expect:
      exit: 0
      stdout_contains: ['\.ai/local/state/checkpoints/']
  - id: handover
    run: ['handover']
    stdin: handover-body.md
    note: 'the record the next session resumes from, with the sections the policy requires'
    expect:
      exit: 0
      stdout_contains: ['\.ai/local/state/handovers/']
  - id: resume
    run: ['context']
    note: 'what the next worker reads instead of a transcript'
    expect:
      exit: 0
      stdout_contains: ['^## GIT', '^## TASK', 'narrow the parser']
  - id: verify
    run: ['check']
    note: 'the task is still consistent with git'
    expect:
      exit: 0
      stdout_contains: ['0 failing']
then:
  - 'the handover carries the branch and head it was written at'
  - 'the next context names the task, the profile and the scope'

The scenario

Executed against the real tool, in a repository prepared by active-task, every time this site is generated. What follows is not a description of what should happen; it is what happened.

What the tool did

Evidence of the run this page was generated from: pass, 4 step(s). Output is normalised: the repository's path, timestamps, ids and durations are placeholders; nothing else is edited.

Tested by test/cases/94_use_cases.sh, which runs every scenario and refuses a step whose recorded output is not what it produced.

1. 1$ majordomus checkpoint exit 0< checkpoint-body.md

   a short progress record inside the task

   .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md

   • exit 0
   • stdout_contains /\.ai/local/state/checkpoints//
2. 2$ majordomus handover exit 0< handover-body.md

   the record the next session resumes from, with the sections the policy requires

   .ai/local/state/handovers/<time>--main--<head>--<hash>.md

   • exit 0
   • stdout_contains /\.ai/local/state/handovers//
3. 3$ majordomus context exit 0

   what the next worker reads instead of a transcript

   # Majordomus context — <time>
   # a projection of durable state, not a source of truth: validate every line against git
   
   ## GIT
   repository   <repo>
   branch       main
   head         <sha>
   working_tree dirty
   task_record  exact (recorded head <head>)
   
   ## TASK
   id           t-<id>
   task         narrow the parser
   profile      implementation
   owner        <owner>
   outcome      active
   scope        lib
   started      <time> (<age> ago)
   checkpoint   <time> (<age> ago, interval 15m)
   
   ## PROFILE implementation
   capability   standard
   effort       medium
   verbosity    concise
   presentation engineering
   verification verify command
   output       outcome, changes, verification, blockers, next_action
   
   ## CONTEXT DOCUMENTS (for the scope, root first; majordomus context explain <path>)
   lib  ai.layer
   
   ## KNOWLEDGE (candidates awaiting review on this branch; majordomus knowledge candidates)
   No knowledge candidates await review on this branch. That is an answer, not a gap: `majordomus knowledge candidates` lists every branch.
   
   ## DECISIONS (5 most recent for this task)
   (none)
   
   ## LATEST CHECKPOINT (.ai/local/state/checkpoints/<time>--main--<head>--<hash>.md, <age> ago, exact)
   the parser now refuses tabs; the message names the column
   
   ## LATEST COMPATIBLE HANDOVER (.ai/local/state/handovers/<time>--main--<head>--<hash>.md)
   match        same_worktree_same_branch
   git state    exact
   created      <time> (<age> ago)
   task         t-<id>
   # Objective
   narrow the parser
   # Current State
   tabs are refused with a message
   # Next Action
   none
   
   ## FILES TOUCHED IN SCOPE (1)
   lib/a
   
   ## EXCLUDED
   - history — profile implementation sets context.recent_history_depth: 0
   
   ## BUDGET
   60 of 300 lines

   • exit 0
   • stdout_contains /^## GIT/
   • stdout_contains /^## TASK/
   • stdout_contains /narrow the parser/
4. 4$ majordomus check exit 0

   the task is still consistent with git

   OK   knowledge   records — 0 record(s) valid against knowledge/v1; every reference resolves  [reproduce: majordomus knowledge check]
   ·    checkpoint  t-<id> — <timed against the checkpoint interval>
   INFO checkpoint  .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md — newest record, <age> ago  [reproduce: majordomus checkpoint --show]
   OK   records     ledger.jsonl — every line is a well-formed event
   OK   blockers    t-<id> — none open
   OK   records     decisions.md — every entry is attributable
   OK   scope       t-<id> — 1 touched file(s), all within scope
   OK   state       t-<id> — exact (head <head>)
   INFO mesh        t-<id> — the repository declares no enabled mesh
   INFO use-case    30 advisory gap(s) — not covered by an active use case, and the policy does not require it: command:init command:update command:doctor command:watch command:start command:context command:checkpoint command:handover command:check command:finish command:history command:decision command:question command:prompt command:evidence command:skills command:capture command:search command:doctrine command:plan command:version command:session command:knowledge command:adr command:usecase command:rules command:migrate command:recover command:bench command:archive  [reproduce: majordomus usecase coverage]
   OK   use-case    0 of 30 target(s) covered — every public command the policy requires is named and run by an active use case (policy use_cases.coverage)
   INFO obligation  t-<id> — the task declares no obligations
   INFO gate        t-<id> — this repository declares no CI model at .ai/repo/ci/gates.yaml; nothing can be planned
   check: 13 finding(s), 0 failing

   • exit 0
   • stdout_contains /0 failing/

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

• majordomus checkpointRecord compact progress inside the active task, so the next worker does not start over.
• majordomus handoverWrite an append-only continuation record, and resolve the most relevant prior one.
• majordomus contextWhat the next worker needs to know now, in authority order and within a budget.
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?

The rules that make it hold

• ✕blocking Handover integrityThe 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.
• ✕blocking Note integrityEvery outcome needs a note carrying the sections that outcome requires, and no transcript.
• !advisory Task continuityA task finished as partial or blocked should leave a handover record, not only a note section.
• ✕blocking Context budgetThe always-loaded projection stays within its line budget, every reference in it resolves, it states no count that will go stale, and the assembled context fits the builder's own budget.

Guarantees exercised

• ○guaranteed State read back is labelled exact, advanced, diverged or different_context against git
• ○guaranteed handover writes an append-only record with computed front matter and required sections
• ○guaranteed A handover is a state record, not a transcript - its required sections must be present and non-empty, a placeholder body is refused, and its identity is computed and refused when written into the body; a transcript pasted into a section is not detected
• !advisory A profile declares which context a worker should load and no more

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

• Resume in the right worktree, never against somebody else’s taskFind the handover that belongs to this worktree and branch, and see a task record from another checkout reported as foreign rather than enforced here.
• Hand work over with a question still open, and keep it blockingClose a task into a handover while a question is unresolved, start the follow-up task, and see the same question still refuse acceptance there.
• Start a session from a rendered framing, not a pasted transcriptList the prompt assets the repository ships, render one against the durable state, and read the context it embeds.
• Checkpoint long work so a stop costs minutes, not the dayRecord compact progress inside the active task at the profile interval, so a session that ends without warning leaves the next one a place to start.
• Catch an agent that says it is done when it is notOne task, start to finish: a worker strays outside its scope, claims it is finished, hands over, and is accepted only once the repository's own verification passes.

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.
• → 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.
• → 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.