plan.waves

The topological layering of the issue graph: an issue enters a wave only once every dependency has left it, so its wave is one past the longest path to it. Sharing a wave is a necessary condition for running two issues at once, not a sufficient one — overlapping scope serialises them, and every such overlap is reported beside the waves rather than left for two workers to discover in a merge conflict.

query
behaviorally_verified
module plan
#plan
#project
#graph
#waves

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_plan_waves
HTTP	GET /api/v1/plan/waves operationId plan.waves
command line	—

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · PlanMilestoneFilter

Which part of the plan to answer about.

property	type	required	description
milestone	string \| null	no	Restrict the answer to one milestone. Default: the whole plan, and for `next` the active milestone with the rest of the plan as the fallback.

JSON Schema

{
  "additionalProperties": false,
  "description": "Which part of the plan to answer about.",
  "properties": {
    "milestone": {
      "description": "Restrict the answer to one milestone. Default: the whole plan, and for `next` the\nactive milestone with the rest of the plan as the fallback.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "PlanMilestoneFilter",
  "type": "object"
}

output · PlanWaveReport

The execution waves, with the overlaps that serialise issues the graph would let run together.

property	type	required	description
serialised_by_scope	array	yes	Scope overlaps between two issues of one wave. Two issues sharing a wave is a necessary condition for running them at once, not a sufficient one: overlapping scope serialises them, and the overlap is reported here rather than left for two workers to discover in a conflict.
waves	array	yes	The waves, lowest first, with the issues of each.

JSON Schema

{
  "$defs": {
    "PlanFinding": {
      "description": "One validation finding, in the shape `project.finding-carries-reproduce` asks for.",
      "properties": {
        "code": {
          "description": "The stable code a reader greps for (`unknown_dependency`, `scope_conflict`, …).",
          "type": "string"
        },
        "level": {
          "description": "`FAIL` or `WARN`. A failure means the model is invalid.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "subject": {
          "description": "The record the finding is about, or `graph` when it is about the whole graph.",
          "type": "string"
        }
      },
      "required": [
        "level",
        "code",
        "subject",
        "message"
      ],
      "type": "object"
    },
    "PlanIssue": {
      "description": "One issue, as its record declares it and as the graph derives it.",
      "properties": {
        "blocked_by": {
          "description": "The dependencies that are not DONE, plus `milestone:<id>` when the milestone gate\nholds the whole outcome back.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "completed_at": {
          "description": "When completion was recorded.",
          "type": "string"
        },
        "dependents": {
          "description": "The issues that depend on this one.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "depends_on": {
          "description": "Every issue it declares a dependency on, as declared — including one that does not\nexist, which is a finding rather than a silent omission.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "evidence_have": {
          "description": "Evidence entries attached.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "evidence_need": {
          "description": "Evidence tokens the record requires before it may be DONE.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "id": {
          "description": "The identity, which is also the file name.",
          "type": "string"
        },
        "milestone": {
          "description": "The milestone it belongs to.",
          "type": "string"
        },
        "objective": {
          "description": "One line: what the issue is for.",
          "type": "string"
        },
        "parallel_safe": {
          "description": "Whether it may run beside another issue of its wave.",
          "type": "boolean"
        },
        "priority": {
          "description": "`p0` … `p3`.",
          "type": "string"
        },
        "profile": {
          "description": "The execution profile the issue is worked under.",
          "type": "string"
        },
        "scope": {
          "description": "The paths it touches; two issues of one wave that share a path are serialised.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "slug": {
          "description": "The slug, when the record carries one.",
          "type": "string"
        },
        "started_at": {
          "description": "When execution began, when it did.",
          "type": "string"
        },
        "status": {
          "description": "The derived status. Never stored: an issue records what happened to it and the\nstatus follows from that and from the state of its dependencies.",
          "type": "string"
        },
        "title": {
          "description": "One line naming the outcome.",
          "type": "string"
        },
        "verified_at": {
          "description": "When implementation was declared complete.",
          "type": "string"
        },
        "wave": {
          "description": "The execution wave: one past the longest path to it through the dependency graph.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "id",
        "milestone",
        "status",
        "wave",
        "priority",
        "profile",
        "parallel_safe",
        "title",
        "slug",
        "depends_on",
        "blocked_by",
        "dependents",
        "scope",
        "objective",
        "evidence_have",
        "evidence_need",
        "started_at",
        "verified_at",
        "completed_at"
      ],
      "type": "object"
    },
    "PlanWaveView": {
      "description": "One wave, with the issues in it.",
      "properties": {
        "issues": {
          "description": "The issues in it, in id order.",
          "items": {
            "$ref": "#/$defs/PlanIssue"
          },
          "type": "array"
        },
        "wave": {
          "description": "The layer, from zero.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "wave",
        "issues"
      ],
      "type": "object"
    }
  },
  "description": "The execution waves, with the overlaps that serialise issues the graph would let run\ntogether.",
  "properties": {
    "serialised_by_scope": {
      "description": "Scope overlaps between two issues of one wave. Two issues sharing a wave is a\nnecessary condition for running them at once, not a sufficient one: overlapping\nscope serialises them, and the overlap is reported here rather than left for two\nworkers to discover in a conflict.",
      "items": {
        "$ref": "#/$defs/PlanFinding"
      },
      "type": "array"
    },
    "waves": {
      "description": "The waves, lowest first, with the issues of each.",
      "items": {
        "$ref": "#/$defs/PlanWaveView"
      },
      "type": "array"
    }
  },
  "required": [
    "waves",
    "serialised_by_scope"
  ],
  "title": "PlanWaveReport",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	2	whole-plan one-milestone
mcp	covered	2	whole-plan one-milestone
http	covered	2	whole-plan one-milestone