Complete an issue only when its evidence exists

setup: plan-model
given:
  - 'installed, with a canonical project model carrying one milestone and two issues'
steps:
  - id: status
    run: ['plan', 'status']
    note: 'milestone progress and the next executable issue, derived from recorded facts'
    expect:
      exit: 0
      stdout_contains: ['^M000 +PLANNED', 'next ready issue: I0001']
  - id: show
    run: ['plan', 'show', 'I0001']
    note: 'the full record of one issue, including the evidence it requires before it may complete'
    expect:
      exit: 0
      stdout_contains: ['^# I0001', 'READY.*derived', 'wave']
  - id: roadmap
    run: ['plan', 'roadmap']
    note: 'milestones in derived order, with now and next; no document is a second authority for this'
    expect:
      exit: 0
      stdout_contains: ['^now:  M000']
  - id: body
    run: ['plan', 'body', 'I0001']
    note: 'the provider-neutral projection body of one record, the same one the GitHub projection renders'
    expect:
      exit: 0
      stdout_contains: ['^# I0001']
then:
  - 'completion is refused while a required evidence item is missing'
  - 'the roadmap is derived from milestone state, never written'
  - 'a hand edit inside a generated GitHub region is reported rather than kept'

The scenario

Executed against the real tool, in a repository prepared by plan-model, 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 plan status exit 0

   milestone progress and the next executable issue, derived from recorded facts

   ID     STATUS   DONE  TITLE
   M000   PLANNED   0/2  Milestone M000
   
   active milestone: M000
   next ready issue: I0001 — Issue I0001

   • exit 0
   • stdout_contains /^M000 +PLANNED/
   • stdout_contains /next ready issue: I0001/
2. 2$ majordomus plan show I0001 exit 0

   the full record of one issue, including the evidence it requires before it may complete

   # I0001 — Issue I0001
   
   | field | value |
   |---|---|
   | status | **READY** (derived) |
   | milestone | M000 |
   | wave | 0 |
   | priority | p1 |
   | profile | implementation |
   | parallel safe | true |
   | canonical | `.ai/repo/project/issues/I0001.yaml` |
   
   ## Objective
   
   Do the bounded piece of work called I0001.
   
   ## Scope
   
   - `src/I0001`
   
   ## Dependencies
   
   None. This issue is a root of the graph.
   
   ## Acceptance Criteria
   
   - [ ] The work is done
   
   ## Validation
   
   - `true`
   
   ## Evidence Required
   
   - proof
   
   ## Execution Notes
   
   Risk: 
   
   This body is generated from the canonical record by `majordomus plan body I0001`.
   Edit the YAML, not this text.
   
   ## Completion Report

   • exit 0
   • stdout_contains /^# I0001/
   • stdout_contains /READY.*derived/
   • stdout_contains /wave/
3. 3$ majordomus plan roadmap exit 0

   milestones in derived order, with now and next; no document is a second authority for this

   RELEASED    STATUS      MILESTONE                     TITLE
   -           PLANNED     M000                          Milestone M000
   
   now:  M000 — Milestone M000

   • exit 0
   • stdout_contains /^now: M000/
4. 4$ majordomus plan body I0001 exit 0

   the provider-neutral projection body of one record, the same one the GitHub projection renders

   # I0001 — Issue I0001
   
   | field | value |
   |---|---|
   | status | **READY** (derived) |
   | milestone | M000 |
   | wave | 0 |
   | priority | p1 |
   | profile | implementation |
   | parallel safe | true |
   | canonical | `.ai/repo/project/issues/I0001.yaml` |
   
   ## Objective
   
   Do the bounded piece of work called I0001.
   
   ## Scope
   
   - `src/I0001`
   
   ## Dependencies
   
   None. This issue is a root of the graph.
   
   ## Acceptance Criteria
   
   - [ ] The work is done
   
   ## Validation
   
   - `true`
   
   ## Evidence Required
   
   - proof
   
   ## Execution Notes
   
   Risk: 
   
   This body is generated from the canonical record by `majordomus plan body I0001`.
   Edit the YAML, not this text.
   
   ## Completion Report

   • exit 0
   • stdout_contains /^# I0001/

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 planThe milestone and issue model — validate it, read it, and move one issue through it.

The rules that make it hold

• ✕blocking Project model integrityEvery milestone and issue file parses, carries the id its filename claims, and contains no key nobody reads.
• ✕blocking The roadmap is a projection, never a documentNo document is a second authority for the roadmap, and no milestone types its own version. While a hand-written roadmap table exists, it can neither list a release no milestone was released in nor hide one that carried a milestone; a milestone's release (released_in) is inferred from the release records, never typed.
• ✕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.

Guarantees exercised

• ○guaranteed Milestones and issues are canonical repository files, and a key nobody reads is an error
• ○guaranteed Issue and milestone status is derived from recorded facts and is stored nowhere
• ○guaranteed An issue cannot be completed while a required piece of evidence is missing
• ○guaranteed The roadmap is derived from milestone state, and no document may be a second authority for it
• ○guaranteed GitHub milestones and issues are generated from the canonical model, and a hand-edited generated region is reported rather than overwritten

Related use cases

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

• Keep the plan as milestones and issues the tool can validateDeclare milestones as outcomes and issues as execution contracts, and let the tool say what is ready and what is blocked.
• 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.
• Decide whether finished work is actually finishedEvaluate a contract line by line instead of accepting a sentence that says the work is done.
• 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.
• Prove the tool is fast, not assume it, and refuse a regressionMeasure every public command and every capability of the executable against a committed baseline, and let the check fail on a regression rather than a reviewer noticing later.

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.
• → read three roadmaps for one project and believed none of them A plan kept in prose is a snapshot, and every copy of it drifts on its own schedule; stored status is an assertion that stays true after the world moves.
• → 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.
• → could not reproduce a result because nothing recorded the state it came from The result is recorded and the conditions that produced it are not, so it is an anecdote rather than a measurement.