plan.status

Every milestone with its derived status and its issues counted by status, the milestone a worker is executing now, the next ready issue in full, and the plan's own totals. The counts are keyed by the declared vocabulary, which travels with the answer, so a status added to the engine appears here without anything being edited.

query
behaviorally_verified
module plan
#plan
#project
#status

Exposure

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

surface	as
MCP	tool majordomus_plan_status
HTTP	GET /api/v1/plan/status operationId plan.status
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 · PlanStatusReport

Where the plan stands: every milestone's progress, the milestone being executed, and the one issue to take next.

property	type	required	description
counts	reference	yes	Every issue of the plan, counted by derived status.
milestones	array	yes	Every milestone, in id order.
next_ready	one of 2	no	The next ready issue, when there is one.
project	reference	yes	The plan's header, with the active milestone derived.
statuses	reference	yes	The declared status vocabularies.

JSON Schema

{
  "$defs": {
    "PlanCounts": {
      "description": "A milestone's issues counted: the two denominators, then one entry per declared status.",
      "properties": {
        "by_status": {
          "additionalProperties": {
            "format": "uint32",
            "minimum": 0,
            "type": "integer"
          },
          "description": "One entry per declared issue status, keyed by the vocabulary.",
          "type": "object"
        },
        "required": {
          "description": "The denominator the milestone's own status derivation uses: total less cancelled, so\nno surface prints \"n of total\" for a milestone the engine calls DONE.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "total": {
          "description": "Every issue naming this milestone.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "total",
        "required",
        "by_status"
      ],
      "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"
    },
    "PlanMilestoneProgress": {
      "description": "One milestone's progress, without its prose.",
      "properties": {
        "counts": {
          "$ref": "#/$defs/PlanCounts",
          "description": "Its issues, counted by derived status."
        },
        "id": {
          "description": "The identity.",
          "type": "string"
        },
        "status": {
          "description": "The derived status.",
          "type": "string"
        },
        "title": {
          "description": "One line naming the outcome.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "status",
        "title",
        "counts"
      ],
      "type": "object"
    },
    "PlanProject": {
      "description": "The plan's header: what this repository is, plus the one field nobody authors.",
      "properties": {
        "active_milestone": {
          "description": "The milestone a worker is executing now: the lowest-ranked unblocked milestone that\nis ACTIVE, else the lowest-ranked unblocked one not finished. Derived on every read,\nstored nowhere, and never authored — the plan cannot nominate a milestone whose\nprerequisites are not real.",
          "type": "string"
        },
        "default_branch": {
          "description": "The branch the plan is executed on.",
          "type": "string"
        },
        "name": {
          "description": "The project's name, from `project.yaml`.",
          "type": "string"
        },
        "repository": {
          "description": "The repository it belongs to, `owner/name`.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "repository",
        "default_branch",
        "active_milestone"
      ],
      "type": "object"
    },
    "PlanVocabulary": {
      "description": "The status vocabularies, so a reader never has to know which statuses exist.",
      "properties": {
        "issue": {
          "description": "The issue statuses, in derivation order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "milestone": {
          "description": "The milestone statuses, in derivation order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "issue",
        "milestone"
      ],
      "type": "object"
    }
  },
  "description": "Where the plan stands: every milestone's progress, the milestone being executed, and the\none issue to take next.",
  "properties": {
    "counts": {
      "$ref": "#/$defs/PlanCounts",
      "description": "Every issue of the plan, counted by derived status."
    },
    "milestones": {
      "description": "Every milestone, in id order.",
      "items": {
        "$ref": "#/$defs/PlanMilestoneProgress"
      },
      "type": "array"
    },
    "next_ready": {
      "anyOf": [
        {
          "$ref": "#/$defs/PlanIssue"
        },
        {
          "type": "null"
        }
      ],
      "description": "The next ready issue, when there is one."
    },
    "project": {
      "$ref": "#/$defs/PlanProject",
      "description": "The plan's header, with the active milestone derived."
    },
    "statuses": {
      "$ref": "#/$defs/PlanVocabulary",
      "description": "The declared status vocabularies."
    }
  },
  "required": [
    "project",
    "statuses",
    "milestones",
    "counts"
  ],
  "title": "PlanStatusReport",
  "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