plan.flight

The milestones with work in flight, the one the graph allows next, and the latest release as the releases themselves say it, read live on every call (ADR 0166, decision 4). Now is every open milestone holding an open issue with an open pull request that names it (`plan.delivery`'s `pr_open`), a live mesh claim made for it, or a declared ACTIVE status, each with those issues, why they are in flight, their declared status beside their inferred stage, and the objects that prove it (branch, pull request, merge commit, release tag, published `latest.json`, claim), linked on the forge where the forge has them. Next is the first open milestone in the plan's order that is not now and whose unfinished prerequisites are all now. The latest release is the highest stable version among the release records, the `v*` tags of this clone and the `latest.json` the last successful Pages deployment published, so a release whose record merged after its tag is not shown older than it is; `executable_tagged` says whether the answering executable's own version is tagged. `milestone` adds that milestone with every one of its issues. A source that was not read (the forge, the publication, the mesh outside a server) is named with its reason, never treated as empty.

query
experimental
module plan
#plan
#project
#delivery
#release
#mesh

Exposure

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

surface	as
MCP	tool majordomus_plan_flight
HTTP	GET /api/v1/plan/flight operationId plan.flight
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 · PlanFlightInput

Which milestone to inspect besides where the work is: the input of plan.flight.

use majordomus_cli::capability::builtin::plan::PlanFlightInput;

let plain: PlanFlightInput = serde_json::from_str("{}").unwrap();
assert!(plain.milestone.is_none());
assert!(serde_json::from_str::<PlanFlightInput>(r#"{"issue":"I1"}"#).is_err());

property	type	required	description
milestone	string \| null	no	A milestone id: the answer then carries it, with every one of its issues, as `inspected`. An id the plan does not declare is not found.

JSON Schema

{
  "additionalProperties": false,
  "description": "Which milestone to inspect besides where the work is: the input of `plan.flight`.\n\n```\nuse majordomus_cli::capability::builtin::plan::PlanFlightInput;\n\nlet plain: PlanFlightInput = serde_json::from_str(\"{}\").unwrap();\nassert!(plain.milestone.is_none());\nassert!(serde_json::from_str::<PlanFlightInput>(r#\"{\"issue\":\"I1\"}\"#).is_err());\n```",
  "properties": {
    "milestone": {
      "description": "A milestone id: the answer then carries it, with every one of its issues, as\n`inspected`. An id the plan does not declare is not found.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "PlanFlightInput",
  "type": "object"
}

output · PlanFlight

Where the work is: the answer of plan.flight.

property	type	required	description
inspected	one of 2	no	The milestone asked for with `milestone`, with every one of its issues.
milestones	array	yes	The milestones of `now`, each with its issues in flight.
next	string \| null	no	The first open milestone the graph allows once the work in flight lands.
now	array	yes	The milestones with work in flight, in the plan's order.
observed	reference	yes	Where and when the delivery half was observed.
release	reference	yes	The latest release.
schema	integer	yes	The version of this shape.
sources	array	yes	Every source, read or not: `plan.delivery`'s, then `mesh`.

JSON Schema

{
  "$defs": {
    "DeliveryObservation": {
      "description": "Where and when the answer was observed.",
      "properties": {
        "commit": {
          "description": "The commit that history ends at.",
          "type": "string"
        },
        "mode": {
          "description": "`live`, or `at` a named commit.",
          "type": "string"
        },
        "observed_at": {
          "description": "When: the clock in live mode, the commit's committer time at a commit.",
          "type": "string"
        },
        "trunk": {
          "description": "The history read: the trunk ref in live mode, the commit asked for otherwise.",
          "type": "string"
        }
      },
      "required": [
        "mode",
        "trunk",
        "commit",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryReading": {
      "description": "Whether one source of the answer was read.",
      "oneOf": [
        {
          "const": "read",
          "description": "It was read; what it holds is in the answer.",
          "type": "string"
        },
        {
          "const": "unread",
          "description": "It was not read, and `reason` says why. Nothing it could have proved is claimed or\ndenied.",
          "type": "string"
        }
      ]
    },
    "DeliverySource": {
      "description": "One source the answer is built from, and whether it was read.",
      "properties": {
        "detail": {
          "description": "What was read, or why nothing was: the ref, the file, the command that would record\nit.",
          "type": "string"
        },
        "name": {
          "description": "`branches`, `forge`, `history`, `releases` or `publication`.",
          "type": "string"
        },
        "observed_at": {
          "description": "When what was read was observed, RFC 3339, when it was read.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/DeliveryReading",
          "description": "Read or unread."
        }
      },
      "required": [
        "name",
        "state",
        "detail"
      ],
      "type": "object"
    },
    "DeliveryStage": {
      "description": "How far one issue's work has travelled, in order: each stage implies every one before it\nhas been passed through, so the furthest one proved is the issue's stage.",
      "oneOf": [
        {
          "const": "none",
          "description": "Nothing that was read names the issue.",
          "type": "string"
        },
        {
          "const": "branch",
          "description": "A branch names it.",
          "type": "string"
        },
        {
          "const": "pr_open",
          "description": "An open pull request names it.",
          "type": "string"
        },
        {
          "const": "merged",
          "description": "A merge in the trunk's history names it.",
          "type": "string"
        },
        {
          "const": "released",
          "description": "A `v*` release contains its newest merge.",
          "type": "string"
        },
        {
          "const": "deployed",
          "description": "The published `latest.json` names that release or a later one.",
          "type": "string"
        }
      ]
    },
    "FlightIssue": {
      "description": "One issue: its declared status beside its inferred stage, and what proves the stage.",
      "properties": {
        "in_flight": {
          "description": "Why it is in flight; empty for an issue that is not.",
          "items": {
            "$ref": "#/$defs/InFlight"
          },
          "type": "array"
        },
        "issue": {
          "description": "The issue id.",
          "type": "string"
        },
        "proofs": {
          "description": "The objects that prove the stage (and the claims that put it in flight), in stage\norder.",
          "items": {
            "$ref": "#/$defs/Proof"
          },
          "type": "array"
        },
        "settled": {
          "description": "True when no unread source could have proved a further stage.",
          "type": "boolean"
        },
        "stage": {
          "$ref": "#/$defs/DeliveryStage",
          "description": "Its inferred delivery stage, from `plan.delivery`."
        },
        "status": {
          "description": "Its declared status, from the stamps.",
          "type": "string"
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        },
        "unread": {
          "description": "The sources that were not read and could have moved it further.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "issue",
        "title",
        "status",
        "stage",
        "settled",
        "unread",
        "in_flight",
        "proofs"
      ],
      "type": "object"
    },
    "FlightMilestone": {
      "description": "One milestone with the issues an answer shows of it.",
      "properties": {
        "id": {
          "description": "The milestone id.",
          "type": "string"
        },
        "issues": {
          "description": "Its issues: the ones in flight for a milestone of `now`, every one for the inspected\nmilestone.",
          "items": {
            "$ref": "#/$defs/FlightIssue"
          },
          "type": "array"
        },
        "status": {
          "description": "Its declared status.",
          "type": "string"
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title",
        "status",
        "issues"
      ],
      "type": "object"
    },
    "FlightRelease": {
      "description": "The latest release, and every source that was asked for it.",
      "properties": {
        "executable": {
          "description": "The version of the executable that answered.",
          "type": "string"
        },
        "executable_tagged": {
          "description": "True when the executable's own version is tagged `v<version>`; the latest release is\nthen never older than it.",
          "type": "boolean"
        },
        "href": {
          "description": "Where it can be seen on the forge.",
          "type": [
            "string",
            "null"
          ]
        },
        "latest": {
          "description": "The highest stable version any read source names; absent when none names one.",
          "type": [
            "string",
            "null"
          ]
        },
        "readings": {
          "description": "Every source, read or not.",
          "items": {
            "$ref": "#/$defs/ReleaseReading"
          },
          "type": "array"
        },
        "source": {
          "description": "The source that named it (the first in `records`, `tags`, `publication` order when\nseveral agree).",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "executable",
        "executable_tagged",
        "readings"
      ],
      "type": "object"
    },
    "InFlight": {
      "description": "Why an issue is in flight.",
      "oneOf": [
        {
          "const": "pr_open",
          "description": "An open pull request names it.",
          "type": "string"
        },
        {
          "const": "claim",
          "description": "A live mesh claim was made for it.",
          "type": "string"
        },
        {
          "const": "active",
          "description": "Its declared status is ACTIVE.",
          "type": "string"
        }
      ]
    },
    "Proof": {
      "description": "One object that proves where an issue's work stands.",
      "properties": {
        "href": {
          "description": "Where the object is, on the forge; absent for an object only this clone holds (a\nlocal branch, a mesh claim), so a link is never drawn to nothing.",
          "type": [
            "string",
            "null"
          ]
        },
        "kind": {
          "description": "`branch`, `pull_request`, `merge`, `release`, `publication` or `claim`.",
          "type": "string"
        },
        "label": {
          "description": "What a reader is shown: `#1298`, a short commit, a tag, a branch.",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "label"
      ],
      "type": "object"
    },
    "ReleaseReading": {
      "description": "One source's answer to \"what is the latest release\".",
      "properties": {
        "detail": {
          "description": "What was read (`.ai/repo/releases/v0.27.0.yaml`, `refs/tags/v0.27.0`,\n`<commit>:site/static/releases/latest.json`), or why nothing was.",
          "type": "string"
        },
        "href": {
          "description": "Where it can be seen on the forge, when it can.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "`records`, `tags` or `publication`.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/DeliveryReading",
          "description": "Read or unread."
        },
        "version": {
          "description": "The version it names, when it was read and names one.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "source",
        "state",
        "detail"
      ],
      "type": "object"
    }
  },
  "description": "Where the work is: the answer of `plan.flight`.",
  "properties": {
    "inspected": {
      "anyOf": [
        {
          "$ref": "#/$defs/FlightMilestone"
        },
        {
          "type": "null"
        }
      ],
      "description": "The milestone asked for with `milestone`, with every one of its issues."
    },
    "milestones": {
      "description": "The milestones of `now`, each with its issues in flight.",
      "items": {
        "$ref": "#/$defs/FlightMilestone"
      },
      "type": "array"
    },
    "next": {
      "description": "The first open milestone the graph allows once the work in flight lands.",
      "type": [
        "string",
        "null"
      ]
    },
    "now": {
      "description": "The milestones with work in flight, in the plan's order.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "observed": {
      "$ref": "#/$defs/DeliveryObservation",
      "description": "Where and when the delivery half was observed."
    },
    "release": {
      "$ref": "#/$defs/FlightRelease",
      "description": "The latest release."
    },
    "schema": {
      "description": "The version of this shape.",
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    },
    "sources": {
      "description": "Every source, read or not: `plan.delivery`'s, then `mesh`.",
      "items": {
        "$ref": "#/$defs/DeliverySource"
      },
      "type": "array"
    }
  },
  "required": [
    "schema",
    "observed",
    "now",
    "milestones",
    "release",
    "sources"
  ],
  "title": "PlanFlight",
  "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	where-the-work-is one-milestone-inspected
mcp	covered	2	where-the-work-is one-milestone-inspected
http	covered	2	where-the-work-is one-milestone-inspected