plan.delivery

For every issue (or one), the furthest delivery stage proved — none, branch, pr_open, merged, released, deployed — each with the object that proved it and when it was observed: the branch that names the issue (by id, the I1405 rule, or by its slug), the open pull request in the recorded forge observation, the newest commit in the trunk's history that names it (a merge by its pull-request title or branch, any other commit by its subject, never by its body), the first release record (`.ai/repo/releases/v*.yaml`) whose commit contains that merge, and the published `latest.json` that names that release or a later one. Beside it, the issue's declared status, so a contradiction between the stamps and the work is one comparison away. Live by default: the trunk this clone knows, every branch, the forge observation `majordomus prs refresh` recorded, the release records, and the `latest.json` of the commit the last Pages deployment published. With `at`, the merges of that commit's history and the tree's release records and nothing live — every branch, forge and deployment source is reported unread — so only merged and released can be proved and the answer is a function of the commit alone. A source that was not read is reported unread with its reason, never as none: an issue it could have moved further is not settled and names it. Inferred on every call and stored nowhere; it never writes a stamp.

query
experimental
module plan
#plan
#project
#delivery
#git
#provenance

Exposure

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

surface	as
MCP	tool majordomus_plan_delivery
HTTP	GET /api/v1/plan/delivery operationId plan.delivery
command line	majordomus plan delivery

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 · PlanDeliveryInput

Which issues, and as of when: the input of plan.delivery.

Both fields are optional, and an unknown one is refused rather than ignored, so a caller who misspells at is not silently answered live.

use majordomus_cli::capability::builtin::plan::PlanDeliveryInput;

let every: PlanDeliveryInput = serde_json::from_str("{}").unwrap();
assert!(every.issue.is_none() && every.at.is_none(), "live, every issue");
let one: PlanDeliveryInput =
    serde_json::from_value(serde_json::json!({ "issue": "I2740", "at": "HEAD" })).unwrap();
assert_eq!((one.issue.as_deref(), one.at.as_deref()), (Some("I2740"), Some("HEAD")));
assert!(serde_json::from_str::<PlanDeliveryInput>(r#"{"commit":"HEAD"}"#).is_err());

property	type	required	description
at	string \| null	no	Observe as of this commit (`HEAD`, a sha, a ref): its history and the tree's release records, and nothing live — no branch, forge, deployment or clock. Default: live.
issue	string \| null	no	One issue id (`I2740`). Default: every issue of the plan. An id the plan does not declare is not found, never answered as `none`.

JSON Schema

{
  "additionalProperties": false,
  "description": "Which issues, and as of when: the input of `plan.delivery`.\n\nBoth fields are optional, and an unknown one is refused rather than ignored, so a caller\nwho misspells `at` is not silently answered live.\n\n```\nuse majordomus_cli::capability::builtin::plan::PlanDeliveryInput;\n\nlet every: PlanDeliveryInput = serde_json::from_str(\"{}\").unwrap();\nassert!(every.issue.is_none() && every.at.is_none(), \"live, every issue\");\nlet one: PlanDeliveryInput =\n    serde_json::from_value(serde_json::json!({ \"issue\": \"I2740\", \"at\": \"HEAD\" })).unwrap();\nassert_eq!((one.issue.as_deref(), one.at.as_deref()), (Some(\"I2740\"), Some(\"HEAD\")));\nassert!(serde_json::from_str::<PlanDeliveryInput>(r#\"{\"commit\":\"HEAD\"}\"#).is_err());\n```",
  "properties": {
    "at": {
      "description": "Observe as of this commit (`HEAD`, a sha, a ref): its history and the tree's release\nrecords, and nothing live — no branch, forge, deployment or clock. Default: live.",
      "type": [
        "string",
        "null"
      ]
    },
    "issue": {
      "description": "One issue id (`I2740`). Default: every issue of the plan. An id the plan does not\ndeclare is not found, never answered as `none`.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "PlanDeliveryInput",
  "type": "object"
}

output · IssueDeliveryReport

Every issue's delivery, with what it was read from.

property	type	required	description
issues	array	yes	The issues, in id order.
observed	reference	yes	Where and when.
schema	integer	yes	The version of this shape.
sources	array	yes	Every source, read or not.
stages	array	yes	The stage vocabulary, in order.
tallies	object	yes	How many issues are at each stage, keyed by every stage of the vocabulary.
unsettled	integer	yes	How many issues an unread source could have moved further.

JSON Schema

{
  "$defs": {
    "DeliveryBranch": {
      "description": "A branch that names the issue.",
      "properties": {
        "head": {
          "description": "The commit it points at.",
          "type": "string"
        },
        "name": {
          "description": "The ref, short: `feature/x`, or `origin/feature/x` for a remote-tracking one.",
          "type": "string"
        },
        "observed_at": {
          "description": "When the refs were read.",
          "type": "string"
        },
        "remote": {
          "description": "True for a remote-tracking ref.",
          "type": "boolean"
        },
        "via": {
          "description": "How the name names the issue: `id` or `slug`.",
          "type": "string"
        }
      },
      "required": [
        "name",
        "head",
        "remote",
        "via",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryDeployment": {
      "description": "The published release pointer that covers the issue's release.",
      "properties": {
        "latest_json": {
          "description": "Where that `latest.json` was read: `<commit>:site/static/releases/latest.json`, the\ncommit the observed Pages deployment published.",
          "type": "string"
        },
        "observed_at": {
          "description": "When the publication was observed.",
          "type": "string"
        },
        "version": {
          "description": "The version `latest.json` names.",
          "type": "string"
        }
      },
      "required": [
        "version",
        "latest_json",
        "observed_at"
      ],
      "type": "object"
    },
    "DeliveryMerge": {
      "description": "The newest commit in the trunk's history that names the issue: a merge, by its pull\nrequest's title or its branch, or a commit whose subject names it the way this\nrepository's commits do (`type(scope): description (I2740)`).",
      "properties": {
        "branch": {
          "description": "The branch it merged, when its subject names one.",
          "type": [
            "string",
            "null"
          ]
        },
        "commit": {
          "description": "The commit: a merge commit, or a commit whose subject names the issue.",
          "type": "string"
        },
        "merged_at": {
          "description": "When it was committed, RFC 3339.",
          "type": "string"
        },
        "merges": {
          "description": "How many commits in the history name the issue; this one is the newest.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "observed_at": {
          "description": "When the history was read.",
          "type": "string"
        },
        "pull_request": {
          "description": "The pull request it merged, when its subject names one.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "title": {
          "description": "The pull request's title, when the merge carries one, or the commit's subject.",
          "type": [
            "string",
            "null"
          ]
        },
        "via": {
          "description": "How it names the issue: `title_or_branch` or `slug` for a merge, `subject` for a\ncommit, `forge_title` for a merged pull request's title as the forge recorded it.",
          "type": "string"
        }
      },
      "required": [
        "commit",
        "via",
        "merged_at",
        "merges",
        "observed_at"
      ],
      "type": "object"
    },
    "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"
    },
    "DeliveryPullRequest": {
      "description": "An open pull request that names the issue.",
      "properties": {
        "draft": {
          "description": "True for a draft.",
          "type": "boolean"
        },
        "head_ref": {
          "description": "The branch it asks to merge.",
          "type": "string"
        },
        "number": {
          "description": "The number.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "observed_at": {
          "description": "When the forge was observed.",
          "type": "string"
        },
        "title": {
          "description": "The title.",
          "type": "string"
        },
        "via": {
          "description": "How it names the issue: `title_or_branch` or `slug`.",
          "type": "string"
        }
      },
      "required": [
        "number",
        "title",
        "head_ref",
        "draft",
        "via",
        "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"
        }
      ]
    },
    "DeliveryRelease": {
      "description": "The first release that contains the issue's newest merge.",
      "properties": {
        "commit": {
          "description": "The commit the tag names.",
          "type": "string"
        },
        "observed_at": {
          "description": "When the releases were read.",
          "type": "string"
        },
        "tag": {
          "description": "The tag: `v0.27.0`.",
          "type": "string"
        }
      },
      "required": [
        "tag",
        "commit",
        "observed_at"
      ],
      "type": "object"
    },
    "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"
        }
      ]
    },
    "IssueDelivery": {
      "description": "One issue's delivery.",
      "properties": {
        "branch": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryBranch"
            },
            {
              "type": "null"
            }
          ],
          "description": "The branch that names it, local first."
        },
        "deployed": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryDeployment"
            },
            {
              "type": "null"
            }
          ],
          "description": "The publication that covers that release."
        },
        "issue": {
          "description": "The issue id.",
          "type": "string"
        },
        "merged": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryMerge"
            },
            {
              "type": "null"
            }
          ],
          "description": "The newest merge that names it."
        },
        "milestone": {
          "description": "Its milestone.",
          "type": "string"
        },
        "pr_open": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryPullRequest"
            },
            {
              "type": "null"
            }
          ],
          "description": "The open pull request that names it, newest first."
        },
        "released": {
          "anyOf": [
            {
              "$ref": "#/$defs/DeliveryRelease"
            },
            {
              "type": "null"
            }
          ],
          "description": "The first release containing that merge."
        },
        "settled": {
          "description": "True when no unread source could have proved a further stage.",
          "type": "boolean"
        },
        "stage": {
          "$ref": "#/$defs/DeliveryStage",
          "description": "The furthest stage proved."
        },
        "status": {
          "description": "Its declared status, as the plan derives it from the stamps: the other half of the\ncomparison this answer exists for.",
          "type": "string"
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        },
        "unread": {
          "description": "The sources that were not read and could have proved a further stage.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "issue",
        "title",
        "milestone",
        "status",
        "stage",
        "settled",
        "unread"
      ],
      "type": "object"
    }
  },
  "description": "Every issue's delivery, with what it was read from.",
  "properties": {
    "issues": {
      "description": "The issues, in id order.",
      "items": {
        "$ref": "#/$defs/IssueDelivery"
      },
      "type": "array"
    },
    "observed": {
      "$ref": "#/$defs/DeliveryObservation",
      "description": "Where and when."
    },
    "schema": {
      "description": "The version of this shape.",
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    },
    "sources": {
      "description": "Every source, read or not.",
      "items": {
        "$ref": "#/$defs/DeliverySource"
      },
      "type": "array"
    },
    "stages": {
      "description": "The stage vocabulary, in order.",
      "items": {
        "$ref": "#/$defs/DeliveryStage"
      },
      "type": "array"
    },
    "tallies": {
      "additionalProperties": {
        "format": "uint",
        "minimum": 0,
        "type": "integer"
      },
      "description": "How many issues are at each stage, keyed by every stage of the vocabulary.",
      "type": "object"
    },
    "unsettled": {
      "description": "How many issues an unread source could have moved further.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "schema",
    "observed",
    "stages",
    "sources",
    "tallies",
    "unsettled",
    "issues"
  ],
  "title": "IssueDeliveryReport",
  "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	every-issue one-issue-at-head
mcp	covered	2	every-issue one-issue-at-head
http	covered	2	every-issue one-issue-at-head