Resume in the right worktree, never against somebody else’s task

setup: two-worktrees
given:
  - 'installed and wired, with a second worktree on another branch holding an active task scoped to lib'
steps:
  - id: nothing-here
    run: ['handover', '--resolve']
    note: 'no handover was written for this worktree and branch; absence is reported, never a record from elsewhere'
    expect:
      exit: 0
      stdout_contains: ['No relevant handover']
  - id: not-my-task
    run: ['check']
    note: 'the other worktree’s task is not this checkout’s; check reports no active task here instead of holding this checkout to a scope it never claimed'
    expect:
      exit: 12
      stdout_contains: ['no active task']
  - id: read-only-view
    run: ['context']
    note: 'what this worktree knows: its own git identity and no task'
    expect:
      exit: 0
      stdout_contains: ['^## GIT', 'none active']
then:
  - 'handover --resolve never offered a record from another branch'
  - 'check did not enforce the other worktree’s scope here'
  - 'local state under .ai/local/ is this checkout’s own and untracked'

The scenario

Executed against the real tool, in a repository prepared by two-worktrees, 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, 3 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 handover --resolve exit 0

   no handover was written for this worktree and branch; absence is reported, never a record from elsewhere

   No relevant handover.

   • exit 0
   • stdout_contains /No relevant handover/
2. 2$ majordomus check exit 12

   the other worktree’s task is not this checkout’s; check reports no active task here instead of holding this checkout to a scope it never claimed

   majordomus: no active task (.ai/local/state/current.yaml); run: majordomus start

   • exit 12
   • stdout_contains /no active task/
3. 3$ majordomus context exit 0

   what this worktree knows: its own git identity and no task

   # 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 clean
   
   ## TASK
   none active — run: majordomus start "<task>" --scope <paths>
   
   ## 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.
   
   ## EXCLUDED
   - context documents — no active task names a scope; run: majordomus context resolve <path>
   - handover — no record for this worktree and branch — absence, not a stale match
   
   ## BUDGET
   21 of 300 lines

   • exit 0
   • stdout_contains /^## GIT/
   • stdout_contains /none active/

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 handoverWrite an append-only continuation record, and resolve the most relevant prior one.
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?
• majordomus contextWhat the next worker needs to know now, in authority order and within a budget.

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 State consistencyThe task record still describes this checkout — same branch, and HEAD at or ahead of the recorded commit.
• ✕blocking Scope integrityA task touches only the paths it claimed; work found elsewhere is not accepted as done.

Guarantees exercised

• ○guaranteed State read back is labelled exact, advanced, diverged or different_context against git
• ○guaranteed The right prior record is resolved by worktree and branch, and an unrelated one is never offered
• ○guaranteed Checkout-local state lives under .ai/local/, is ignored by git, and is absent on a fresh clone or worktree
• ○guaranteed A task record names the checkout it belongs to, and another checkout is never held to its scope

Related use cases

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

• Hand unfinished work to the next sessionStop mid-task and leave the next worker something to act on that is not a transcript.
• 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.
• 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.
• Run several workers in one repository without them collidingGive each worker a declared scope, and find out immediately when two of them claim the same paths.
• 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.

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 two agents fixing the same bug in two branches Two workers spend a day each on one defect because ownership was implicit and neither could see the other.
• → 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.
• → 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.
• → had two sessions writing into one checkout without either knowing Two workers in one working tree see each other only as unexplained file changes, and each treats the other as noise.