M000 — Milestone and DAG driven development

DONE 15 of 15 issues done

ready

0

blocked

0

active

0

verify

0

done

15

cancelled

0

Problem

Work in this repository was planned in conversation and in task records that describe one session at a time. There was no executable specification of an outcome, no dependency graph between pieces of work, and no way for a fresh worker to ask the repository what to do next. The tool supervises a task; nothing supervised the plan the task belonged to.

Outcome

Every non-trivial change in this repository belongs to a milestone specification and to one dependency-linked issue execution contract, validated as a DAG, with status derived rather than asserted, and projected to GitHub and to the website from that one canonical model.

Current state

The canonical model, its engine, its CLI, its projections, its doctrines and its tests exist and are exercised by this milestone's own issues. GitHub carried no issues and no milestones before this work.

Desired state

A fresh worker with no conversation history runs `majordomus plan next`, receives one issue, executes it inside its declared scope, attaches evidence, and the graph recomputes what is ready without anybody editing a status field.

Scope

• .majordomus/project
• lib/project.sh
• lib/project.awk
• lib/plan.sh
• share/allow
• share/doctrines.yaml
• scripts/github-sync
• scripts/generate-site-data
• site
• test/cases
• docs

Out of scope

• A hosted planning backend or database
• A second project-management vocabulary; milestones and issues are the only new nouns
• Bidirectional GitHub write-back into the canonical files
• Estimation, burndown, velocity or any scheduling model

Acceptance criteria

• The canonical model parses, rejects unknown keys, and refuses a duplicate id
• A dependency cycle, a self-dependency and an unknown dependency are each rejected with a named finding
• READY, BLOCKED, ACTIVE, VERIFY, DONE and CANCELLED are derived from recorded facts and stored nowhere
• Execution waves are computed from the graph, and overlapping scope inside one wave is reported
• The Mermaid DAG is generated from the same graph the CLI reads
• GitHub milestones and issues are created and updated from the canonical model, and drift between them is reported
• The website renders the roadmap, every milestone, every issue and the DAG from generated data
• Every surface agrees: the CLI, the site data and the GitHub projection report the same issue set and the same READY set
• Changing one dependency changes every surface
• CI refuses a push whose canonical model is invalid or whose generated artifacts are stale

Validation

• bash test/run.sh
• bin/majordomus plan validate
• scripts/generate-site-data --check

Evidence required

• suite
• cross_surface
• mutation
• github

Risks

• The engine is shell and awk; a graph large enough to make that slow would need a different implementation. Measured, not assumed.
• GitHub is a projection. If a human edits a generated issue body, the next sync reports drift rather than silently overwriting it, which means drift can accumulate unattended.

Evidence

A milestone is never done because its issues are; the last step is its own acceptance, and it is gated on the rows below.

Issues

Each one is an execution contract with its own acceptance criteria, validation command and required evidence. The wave column is the layer of the dependency graph it sits in.

The graph

flowchart LR
    I0001["I0001<br/>Audit what actually plans work in this repository"]:::done
    I0002["I0002<br/>Define the canonical milestone and issue schema"]:::done
    I0003["I0003<br/>Implement the model loader and the status derivation engine"]:::done
    I0004["I0004<br/>Implement DAG validation and execution waves"]:::done
    I0005["I0005<br/>Implement the plan command surface"]:::done
    I0006["I0006<br/>Generate the Mermaid DAG from the graph"]:::done
    I0007["I0007<br/>Enforce the canonical model as doctrine"]:::done
    I0008["I0008<br/>Project the model to GitHub milestones and issues"]:::done
    I0009["I0009<br/>Project the model into the website"]:::done
    I0010["I0010<br/>Behavioural tests for schema, status, graph and command"]:::done
    I0011["I0011<br/>Cross-surface consistency and mutation tests"]:::done
    I0012["I0012<br/>Make CI refuse an invalid model or a stale projection"]:::done
    I0013["I0013<br/>Document the semantics and the dogfooding rule"]:::done
    I0014["I0014<br/>Make the worker instructions require the model"]:::done
    I0015["I0015<br/>Open the first real milestone and execute one issue through it"]:::done
    I0001 --> I0002
    I0002 --> I0003
    I0003 --> I0004
    I0004 --> I0005
    I0004 --> I0006
    I0004 --> I0010
    I0005 --> I0007
    I0005 --> I0008
    I0005 --> I0009
    I0005 --> I0013
    I0005 --> I0014
    I0006 --> I0009
    I0008 --> I0011
    I0009 --> I0011
    I0010 --> I0011
    I0011 --> I0012
    I0012 --> I0015
    I0013 --> I0014
    I0014 --> I0015
    classDef done stroke:#16a34a,fill:#052e16,stroke-width:2px
    classDef active stroke:#2563eb,fill:#eff6ff,stroke-width:2px
    classDef verify stroke:#7c3aed,fill:#f5f3ff,stroke-width:2px
    classDef ready stroke:#0891b2,fill:#ecfeff,stroke-width:2px
    classDef blocked stroke:#b45309,fill:#fffbeb,stroke-width:2px
    classDef cancelled stroke:#6b7280,fill:#f9fafb,stroke-width:2px

Canonical record: .ai/repo/project/milestones/M000.yaml. Read it back with majordomus plan show M000.