Keep the plan as milestones and issues the tool can validate

setup: plan-model
given:
  - 'a canonical project model with one milestone and two issues, the second depending on the first'
steps:
  - id: validate
    run: ['plan', 'validate']
    note: 'every record parses, every reference resolves, the dependency graph is acyclic'
    expect:
      exit: 0
      stdout_contains: ['milestone', 'issue', '0 failure']
  - id: what-is-ready
    run: ['plan', 'ready']
    note: 'the issues nothing blocks'
    expect:
      exit: 0
      stdout_contains: ['I0001']
  - id: what-is-blocked
    run: ['plan', 'blocked']
    note: 'the issues waiting on another'
    expect:
      exit: 0
      stdout_contains: ['I0002']
then:
  - 'status is derived from the records and git, never written into them'
  - 'an issue cannot be marked done without the evidence its milestone requires'

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

   every record parses, every reference resolves, the dependency graph is acyclic

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

   • exit 0
   • stdout_contains /milestone/
   • stdout_contains /issue/
   • stdout_contains /0 failure/
2. 2$ majordomus plan ready exit 0

   the issues nothing blocks

   I0001   w0   Issue I0001
       scope: src/I0001

   • exit 0
   • stdout_contains /I0001/
3. 3$ majordomus plan blocked exit 0

   the issues waiting on another

   I0002   w1   Issue I0002
       waiting on: I0001

   • exit 0
   • stdout_contains /I0002/

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 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.

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 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.

• 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.
• 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.
• 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.
• Read back what happened, and keep the ledger within its capRead the append-only ledger as operational history, filtered by task and event, validate every line, and rotate the oldest lines into an archive rather than deleting them.

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 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.
• → 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.