Decide whether finished work is actually finished

setup: finish-ready
given:
  - 'an active task with its completion note written'
steps:
  - id: open-a-question
    run: ['question', 'add', 'should tabs be an error or a warning?']
    note: 'an unresolved question naming the task'
    expect:
      exit: 0
      stdout_contains: ['^opened for t-']
  - id: refused-while-open
    run: ['finish', '--outcome', 'completed', '--verify-command', 'test -d .ai']
    note: 'an open question is a blocker; completed is refused'
    expect:
      exit: 10
      stdout_contains: ['^FAIL blockers', 'refused']
  - id: resolve-it
    run: ['question', 'resolve', '1', '--answer', 'an error']
    note: 'the question is answered as state, not in prose'
    expect:
      exit: 0
      stdout_contains: ['resolved']
  - id: accepted
    run: ['finish', '--outcome', 'completed', '--verify-command', 'test -d .ai']
    note: 'every line of the finish contract passes and the outcome is recorded'
    expect:
      exit: 0
      stdout_contains: ['completed']
then:
  - 'finish writes nothing while any line of the contract fails'
  - 'the verification command, its exit code, its duration and the tree it ran over are recorded'

The scenario

Executed against the real tool, in a repository prepared by finish-ready, 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 question add 'should tabs be an error or a warning?' exit 0

   an unresolved question naming the task

   opened for t-<id>: should tabs be an error or a warning?

   • exit 0
   • stdout_contains /^opened for t-/
2. 2$ majordomus finish --outcome completed --verify-command 'test -d .ai' exit 10

   an open question is a blocker; completed is refused

   FAIL blockers    t-<id> — 1 unresolved question(s) on this branch; first: t-<id> — should tabs be an error or a warning?  [reproduce: majordomus question list]
   OK   note        t-<id> — <time>--main--<head>--<hash>.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, 1 unmet
   blocking doctrines:
   - majordomus.blocker-resolution

   • exit 10
   • stdout_contains /^FAIL blockers/
   • stdout_contains /refused/
3. 3$ majordomus question resolve 1 --answer 'an error' exit 0

   the question is answered as state, not in prose

   resolved for t-<id>: should tabs be an error or a warning?

   • exit 0
   • stdout_contains /resolved/
4. 4$ majordomus finish --outcome completed --verify-command 'test -d .ai' exit 0

   every line of the finish contract passes and the outcome is recorded

   OK   blockers    t-<id> — none open
   OK   note        t-<id> — <time>--main--<head>--<hash>.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: t-<id> completed

   • exit 0
   • stdout_contains /completed/

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 finishEvaluate the finish contract and refuse the outcome if any line of it is unmet.
• majordomus questionOpen a question that blocks acceptance, resolve it, and list what is still open.
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?

The rules that make it hold

• ✕blocking Verification integrityCompletion requires a verification command that actually ran and exited 0 over a tree that did not change under it; its exit code, duration and tree are recorded.
• ✕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 Profile requirementsA profile may demand more than the shared contract — a regression test, a decision record — and finish refuses without it.
• ✕blocking Note integrityEvery outcome needs a note carrying the sections that outcome requires, and no transcript.

Guarantees exercised

• ○guaranteed check reports whether state, scope, blockers and checkpoint age are consistent right now
• ○guaranteed finish evaluates the finish contract line by line and refuses when any line is unmet
• ○guaranteed An outcome is a value from a closed vocabulary, not free text

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.
• 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.
• 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.
• Complete an issue only when its evidence existsSee an issue refuse completion while a required piece of evidence is missing, read the roadmap the milestone state derives, and keep the GitHub projection a projection.

The moments this answers

• → accepted "done" because the model said so, and paid for it the next morning A fluent completion claim is accepted as evidence because nothing wrote down, beforehand, what would have to be true.
• → found finished work on a branch that nobody ever merged Workers produce far more than integration absorbs, and nothing distinguishes work that is done from work that is done and landed.
• → found a substantial change that no issue, ticket or plan ever asked for Work arrives with no bounded contract behind it, so its scope, its acceptance criteria and its ownership are all decided after the fact.
• → closed an issue whose acceptance criteria nothing had actually checked Completion is recorded as a state change in a tracker rather than as evidence in the repository, so the two drift immediately.
• → looked at the bill and could not say which of it produced anything Consumption is measured per account and outcomes are recorded per person, so the two can never be joined.