Deliver issues in waves the graph computes, and take the next one

setup: plan-model
given:
  - 'installed, with a canonical project model carrying one milestone and two issues'
steps:
  - id: validate
    run: ['plan', 'validate']
    note: 'schemas, references, the DAG and status consistency; a cycle or a dependency on a missing issue is refused by name'
    expect:
      exit: 0
      stdout_contains: ['0 failure']
  - id: waves
    run: ['plan', 'waves']
    note: 'topological execution waves; issues in one wave that touch the same paths are reported as serialised'
    expect:
      exit: 0
      stdout_contains: ['^Wave 0', 'I0001 +READY', '^Wave 1', 'I0002 +BLOCKED']
  - id: ready
    run: ['plan', 'ready']
    note: 'issues whose dependencies are all satisfied'
    expect:
      exit: 0
      stdout_contains: ['I0001']
      stdout_not_contains: ['I0002']
  - id: blocked
    run: ['plan', 'blocked']
    note: 'issues waiting on a dependency, and on which one'
    expect:
      exit: 0
      stdout_contains: ['I0002']
  - id: next
    run: ['plan', 'next']
    note: 'the one issue a worker should take now'
    expect:
      exit: 0
      stdout_contains: ['^I0001 ', 'scope:', 'next: majordomus plan start I0001']
  - id: take-it
    run: ['start', 'I0001', '--scope', 'src/I0001']
    note: 'the task under the scope the issue names; overlap with other worktrees is computed on claimed paths'
    expect:
      exit: 0
      stdout_contains: ['t-']
then:
  - 'status is derived from recorded facts and stored nowhere'
  - 'two issues in one wave with overlapping paths are named as serialised'
  - 'the task started carries the scope the issue claims'

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, 6 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 validate exit 0

   schemas, references, the DAG and status consistency; a cycle or a dependency on a missing issue is refused by name

   plan validate: 1 milestone(s), 2 issue(s), 0 failure(s), 0 warning(s)

   • exit 0
   • stdout_contains /0 failure/
2. 2$ majordomus plan waves exit 0

   topological execution waves; issues in one wave that touch the same paths are reported as serialised

   Wave 0
     I0001   READY     Issue I0001
   Wave 1
     I0002   BLOCKED   Issue I0002

   • exit 0
   • stdout_contains /^Wave 0/
   • stdout_contains /I0001 +READY/
   • stdout_contains /^Wave 1/
   • stdout_contains /I0002 +BLOCKED/
3. 3$ majordomus plan ready exit 0

   issues whose dependencies are all satisfied

   I0001   w0   Issue I0001
       scope: src/I0001

   • exit 0
   • stdout_contains /I0001/
   • stdout_not_contains /I0002/
4. 4$ majordomus plan blocked exit 0

   issues waiting on a dependency, and on which one

   I0002   w1   Issue I0002
       waiting on: I0001

   • exit 0
   • stdout_contains /I0002/
5. 5$ majordomus plan next exit 0

   the one issue a worker should take now

   I0001 — Issue I0001
   objective: Do the bounded piece of work called I0001.
   scope:     src/I0001
   profile:   implementation
   
   next: majordomus plan start I0001

   • exit 0
   • stdout_contains /^I0001 /
   • stdout_contains /scope:/
   • stdout_contains /next: majordomus plan start I0001/
6. 6$ majordomus start I0001 --scope src/I0001 exit 0

   the task under the scope the issue names; overlap with other worktrees is computed on claimed paths

   started t-<id>  profile=implementation  scope=src/I0001
   next: majordomus context; checkpoint every 15m; majordomus check before claiming anything

   • exit 0
   • stdout_contains /t-/

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.
• majordomus startBegin one scoped task under a profile, and refuse while another is active.

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 Dependency graph integrityThe issue dependency graph is acyclic, every edge names an issue that exists, and no issue is executing ahead of a dependency that is not done.
• ✕blocking Scope integrityA task touches only the paths it claimed; work found elsewhere is not accepted as done.

Guarantees exercised

• ○guaranteed A task is started with a declared file scope and a profile, and only one task is active per checkout
• ○guaranteed Overlap between parallel workers is computed on claimed paths in both containment directions
• ○guaranteed Issue and milestone status is derived from recorded facts and is stored nowhere
• ○guaranteed A cycle, a self-dependency and a dependency on an issue that does not exist are each refused by name
• ○guaranteed Execution waves are computed from the graph, and issues in one wave that touch the same paths are reported as serialised

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.
• 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.
• 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.
• 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.
• Work on a branch in the one worktree it belongs toStart a branch without choosing a path, find every checkout of the repository from any of them, and bring a stray one home with its uncommitted work intact.

The moments this answers

• → 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 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.
• → was asked how far the milestone had got and had to go and ask four people Progress is an aggregate that exists only in people, because the parts it aggregates were never recorded in a form anything can add up.