Run several workers in one repository without them colliding

setup: two-worktrees
given:
  - 'a second worktree of the same repository with an active task scoped to lib'
steps:
  - id: claim-a-scope
    run: ['start', 'narrow the parser', '--scope', 'lib']
    note: 'the task starts, and the overlap with the other worktree is reported'
    expect:
      exit: 0
      stdout_contains: ['^started t-', 'overlap']
  - id: see-the-overlap
    run: ['check', '--overlap']
    note: 'scope containment against every other worktree, never blocking'
    expect:
      exit: 0
      stdout_contains: ['overlap']
  - id: nothing-to-refuse
    run: ['finish', '--check']
    note: 'no file outside the claimed scope has been touched'
    expect:
      exit: 0
      stdout_contains: ['0 failing']
then:
  - 'two workers on one repository see each other by scope, and the second is told before it starts'

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 start 'narrow the parser' --scope lib exit 0

   the task starts, and the overlap with the other worktree is reported

   started t-<id>  profile=implementation  scope=lib
   INFO overlap     repo-other — claims lib — contains your lib  [reproduce: majordomus check --overlap]
   next: majordomus context; checkpoint every 15m; majordomus check before claiming anything

   • exit 0
   • stdout_contains /^started t-/
   • stdout_contains /overlap/
2. 2$ majordomus check --overlap exit 0

   scope containment against every other worktree, never blocking

   INFO overlap     repo-other — claims lib — contains your lib  [reproduce: majordomus check --overlap]
   INFO overlap     t-<id> — no other worktree claims an overlapping path

   • exit 0
   • stdout_contains /overlap/
3. 3$ majordomus finish --check exit 0

   no file outside the claimed scope has been touched

   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>
   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> — 0 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
   finish --check: 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 startBegin one scoped task under a profile, and refuse while another is active.
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?
• majordomus finishEvaluate the finish contract and refuse the outcome if any line of it is unmet.

The rules that make it hold

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

Guarantees exercised

• ○guaranteed A task is started with a declared file scope and a profile, and only one task is active per checkout
• ○guaranteed Identity fields on every state record are computed from git and never authored
• ○guaranteed A touched file outside the claimed scope is a failure, not a warning
• ○guaranteed Overlap between parallel workers is computed on claimed paths in both containment directions

Related use cases

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

• 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.
• Deliver issues in waves the graph computes, and take the next oneValidate the plan, read the execution waves the dependency graph yields, see which issues are ready and which are blocked on what, and take the one issue a worker should do now.
• 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.
• 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.
• 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.

The moments this answers

• → 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.
• → watched one worker revert another worker's change, on purpose A worker sees an unexplained change in its path, judges it wrong, and removes it — correctly, on the evidence it had.
• → 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.