Hand work over with a question still open, and keep it blocking

setup: finish-blocker-open
given:
  - 'an active task with one unresolved question open against it'
steps:
  - id: hand-over
    run: ['handover', '--close']
    stdin: handover-body.md
    note: 'the record the next session resumes from; --close marks the task handed over so a new one may start'
    expect:
      exit: 0
      stdout_contains: ['\.ai/local/state/handovers/']
  - id: follow-up
    run: ['start', 'the follow-up', '--scope', 'lib']
    note: 'the next task; the prior handover for this worktree and branch is named on the way in'
    expect:
      exit: 0
      stdout_contains: ['^INFO handover', 'same_worktree_same_branch', 'next: majordomus context']
  - id: still-blocked
    run: ['check']
    note: 'the question opened under the previous task still blocks this branch'
    expect:
      exit: 10
      stdout_contains: ['^FAIL blockers', 'unresolved question', 'tabs']
  - id: still-listed
    run: ['question', 'list']
    note: 'the entry, numbered, with the task it was opened under'
    expect:
      exit: 0
      stdout_contains: ['^1  \[unresolved\]', 'tabs']
  - id: refused
    run: ['finish', '--outcome', 'completed', '--verify-command', 'test -d .ai']
    note: 'completion of the follow-up is refused by the same entry'
    expect:
      exit: 10
      stdout_contains: ['^FAIL blockers']
then:
  - 'the handover carries the branch and head it was written at'
  - 'a question is a fact of the branch, not of the task that happened to open it'
  - 'nothing was resolved by handing over; the next worker sees the same blocker'

The scenario

Executed against the real tool, in a repository prepared by finish-blocker-open, 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, 5 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 --close exit 0< handover-body.md

   the record the next session resumes from; --close marks the task handed over so a new one may start

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

   • exit 0
   • stdout_contains /\.ai/local/state/handovers//
2. 2$ majordomus start 'the follow-up' --scope lib exit 0

   the next task; the prior handover for this worktree and branch is named on the way in

   started t-<id>  profile=implementation  scope=lib
   INFO handover    .ai/local/state/handovers/<time>--main--<head>--<hash>.md — prior record, same_worktree_same_branch, exact, <age> ago  [reproduce: majordomus handover --resolve]
   next: majordomus context; checkpoint every 15m; majordomus check before claiming anything

   • exit 0
   • stdout_contains /^INFO handover/
   • stdout_contains /same_worktree_same_branch/
   • stdout_contains /next: majordomus context/
3. 3$ majordomus check exit 10

   the question opened under the previous task still blocks this branch

   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
   FAIL blockers    t-<id> — 1 unresolved question(s) on this branch; first: t-<id> — does the parser need to accept tabs?  [reproduce: majordomus question list]
   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: 12 finding(s), 1 failing

   • exit 10
   • stdout_contains /^FAIL blockers/
   • stdout_contains /unresolved question/
   • stdout_contains /tabs/
4. 4$ majordomus question list exit 0

   the entry, numbered, with the task it was opened under

   1  [unresolved] t-<id> — does the parser need to accept tabs? (<date>)

   • exit 0
   • stdout_contains /^1 \[unresolved\]/
   • stdout_contains /tabs/
5. 5$ majordomus finish --outcome completed --verify-command 'test -d .ai' exit 10

   completion of the follow-up is refused by the same entry

   FAIL blockers    t-<id> — 1 unresolved question(s) on this branch; first: t-<id> — does the parser need to accept tabs?  [reproduce: majordomus question list]
   FAIL note        t-<id> — no --note file and no handover for this task  [reproduce: majordomus handover < note.md]
   INFO regression  t-<id> — profile implementation adds no requirement beyond the shared contract
   OK   scope       t-<id> — 1 touched file(s), all within scope
   OK   state       t-<id> — exact (head <head>)
   INFO continuity  t-<id> — applies to partial and blocked
   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)
   OK   verification t-<id> — test -d .ai — exit 0, <s>s, tree <tree>
   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
   INFO gate        t-<id> — not in verification.finish_requires
   finish: refused, 2 unmet
   blocking doctrines:
   - majordomus.blocker-resolution
   - majordomus.note-integrity

   • exit 10
   • stdout_contains /^FAIL blockers/

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 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 questionOpen a question that blocks acceptance, resolve it, and list what is still open.
• majordomus finishEvaluate the finish contract and refuse the outcome if any line of it is unmet.

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 Blocker resolutionNo task can be completed while any question on this branch is unresolved; it can still be finished as blocked, partial, no_match or failed.
• ✕blocking Questions store integrityEvery entry in open-questions.md parses, because a gate that cannot read an entry can be bypassed by mistyping one.

Guarantees exercised

• ○guaranteed handover writes an append-only record with computed front matter and required sections
• ○guaranteed finish evaluates the finish contract line by line and refuses when any line is unmet
• ○guaranteed The right prior record is resolved by worktree and branch, and an unrelated one is never offered
• ○guaranteed An unresolved question blocks acceptance, and an entry the gate cannot parse is a failure rather than a silent pass
• ○guaranteed A blocking question keeps blocking after the work is handed to a new task

Related use cases

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

• Block acceptance on a question nobody has answeredOpen a question against the task, watch finish refuse completion while it is unresolved, resolve it with the answer, and only then complete.
• 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.
• Hand unfinished work to the next sessionStop mid-task and leave the next worker something to act on that is not a transcript.
• Decide whether finished work is actually finishedEvaluate a contract line by line instead of accepting a sentence that says the work is done.
• 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.