gates.state
Every gate the CI model declares with the standing of its last recorded run in this checkout, whichever task recorded it: `pass` or `fail` over the files as they stand now, `stale` when those files have changed since the run, `queued` when no run has ever reported — listed again under `never_reported`, because a missing verdict is the case an absent reader renders green — and `unknown` when a run exists and cannot be checked against this tree. Each run carries the commit it was taken at and whether that is the commit checked out now. Read offline from this checkout's own record; what it did not consult, the forge's CI runs, is named under `unreached` rather than left out.
Every gate the CI model declares with the standing of its last recorded run in this checkout, whichever task recorded it: `pass` or `fail` over the files as they stand now, `stale` when those files have changed since the run, `queued` when no run has ever reported — listed again under `never_reported`, because a missing verdict is the case an absent reader renders green — and `unknown` when a run exists and cannot be checked against this tree. Each run carries the commit it was taken at and whether that is the commit checked out now. Read offline from this checkout's own record; what it did not consult, the forge's CI runs, is named under `unreached` rather than left out.
- query
- behaviorally_verified
- module gates
- #gates
- #ci
- #evidence
- #introspection
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_gate_state resource majordomus://gates/state |
| HTTP | GET /api/v1/gates/state operationId gates.state |
| 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 · Empty
No input.
No properties: the capability takes no input.
JSON Schema
{
"additionalProperties": false,
"description": "No input.",
"title": "Empty",
"type": "object"
}output · GateStateReport
The declared gate set and the standing of each gate's last recorded run.
count, tallies and never_reported are measured from gates, never written down,
and unreached always names what was not consulted.
use majordomus_cli::gates::GateStateReport;
let r: GateStateReport = serde_json::from_value(serde_json::json!({
"source": ".ai/repo/ci/gates.yaml",
"ledger": ".ai/local/state/ledger.jsonl",
"count": 0,
"tallies": {},
"never_reported": [],
"gates": [],
"unreached": ["the forge's CI runs were not consulted"],
"findings": [],
"evaluated_at": "2026-10-15T00:00:00Z",
}))
.unwrap();
assert_eq!(r.count, r.gates.len());
assert!(r.head.is_none(), "a checkout without git still answers, and says so");
assert!(!r.unreached.is_empty());| property | type | required | description |
|---|---|---|---|
| count | integer | yes | How many gates the model declares; measured. |
| evaluated_at | string | yes | When this answer was taken, RFC 3339 UTC. |
| findings | array | yes | What could not be read, and what that means for the answer. |
| gates | array | yes | Every declared gate, in declaration order. |
| head | string | null | no | The commit this checkout is at, when git could say. |
| ledger | string | yes | Where the recorded runs were read from, repository-relative. |
| never_reported | array | yes | The gates no run has ever reported, in declaration order. |
| source | string | yes | Where the gate set was read from, repository-relative. |
| tallies | object | yes | How many gates stand in each status, by the status word. |
| unreached | array | yes | What this answer did not consult, so its silence about it is not read as a verdict. |
JSON Schema
{
"$defs": {
"GateRun": {
"description": "```\nuse majordomus_cli::gates::GateRun;\n\n// what `majordomus evidence --gate` writes: a run, and the tree it was taken over\nlet run = GateRun {\n recorded_at: \"2026-01-01T00:00:00Z\".into(),\n head: \"9b1e2d4\".into(),\n branch: \"master\".into(),\n exit: 0,\n command: \"scripts/rust-check --ci\".into(),\n inputs_hash: \"3f0a\".into(),\n session: \"s-1\".into(),\n};\n// the hash is what makes a run go stale rather than merely old: the same run read\n// against a different tree is evidence about a tree that no longer exists\nassert_eq!(run.exit, 0);\nassert_ne!(run.inputs_hash, \"0000\");\n```\nThe `task.gate` ledger line that last reported a gate, as the ledger holds it.",
"properties": {
"branch": {
"description": "The branch it was recorded on.",
"type": "string"
},
"command": {
"description": "The command that produced it — narrative is not evidence.",
"type": "string"
},
"exit": {
"description": "The exit status the gate reported. `0` is a pass.",
"format": "int64",
"type": "integer"
},
"head": {
"description": "The commit the ledger's envelope stamped on it.",
"type": "string"
},
"inputs_hash": {
"description": "The hash of the files that select the gate, as they stood when it ran.",
"type": "string"
},
"recorded_at": {
"description": "When it was recorded, RFC 3339 UTC.",
"type": "string"
},
"session": {
"description": "The session that recorded it.",
"type": "string"
}
},
"required": [
"recorded_at",
"head",
"branch",
"exit"
],
"type": "object"
},
"GateState": {
"description": "One declared gate and the standing of its last recorded run.\n\n```\nuse majordomus_cli::gates::{GateState, GateStatus};\n\nlet never: GateState = serde_json::from_value(serde_json::json!({\n \"id\": \"rust-check\",\n \"job\": \"rust\",\n \"always\": true,\n \"on_demand\": false,\n \"status\": \"queued\",\n \"reason\": \"no run of this gate has ever been recorded in this checkout\",\n}))\n.unwrap();\n// no run, no head, and a word that is not `pass`\nassert!(never.last_run.is_none() && never.on_head.is_none());\nassert_eq!(never.status, GateStatus::Queued);\n```",
"properties": {
"always": {
"description": "Whether every plan selects it.",
"type": "boolean"
},
"id": {
"description": "The gate's identity in the model.",
"type": "string"
},
"inputs_hash": {
"description": "The hash of the gate's inputs as they stand now, when it could be taken.",
"type": "string"
},
"job": {
"description": "The CI job that runs it.",
"type": "string"
},
"last_run": {
"anyOf": [
{
"$ref": "#/$defs/GateRun"
},
{
"type": "null"
}
],
"description": "The run that last reported, whichever task recorded it."
},
"on_demand": {
"description": "Whether its runner can be had only on demand, so no routine plan runs it.",
"type": "boolean"
},
"on_head": {
"description": "Whether that run was taken at the commit this checkout is at now. Absent when there\nis no run or when the current commit could not be read.",
"type": [
"boolean",
"null"
]
},
"reason": {
"description": "Why it is in that status, in words a person can act on.",
"type": "string"
},
"status": {
"$ref": "#/$defs/GateStatus",
"description": "What is known about its last run: `pass`, `fail`, `stale`, `queued` (never\nreported) or `unknown` (a run exists and cannot be checked against this tree)."
}
},
"required": [
"id",
"job",
"always",
"on_demand",
"status",
"reason"
],
"type": "object"
},
"GateStatus": {
"description": "```\nuse majordomus_cli::gates::GateStatus;\n\n// the three answers a reader is entitled to, and they are different answers\nassert!(GateStatus::Fail.refuses(), \"a run that failed refuses\");\nassert!(GateStatus::Queued.unverified(), \"asked and unanswered is a debt\");\nassert!(!GateStatus::Exempt.refuses() && !GateStatus::Exempt.unverified());\n\n// and the one that is neither: a run whose tree has moved proves nothing about this one\nassert!(GateStatus::Stale.refuses());\nassert_eq!(GateStatus::Stale.as_str(), \"stale\");\n```\nWhat is known about one gate. Every word is one this repository's design tokens already\ncarry (`share/design/tokens.yaml`, `status.states`), so a surface renders it without\nbeing taught a sixth vocabulary and the design gate does not refuse it.",
"oneOf": [
{
"const": "pass",
"description": "It ran over these inputs and succeeded. The only word that discharges anything.",
"type": "string"
},
{
"const": "fail",
"description": "It ran over these inputs and failed. Completion is refused.",
"type": "string"
},
{
"const": "stale",
"description": "It ran, and the files that select it have changed since; what it proved is about a\ntree that no longer exists. Completion is refused, because the alternative is\ntreating a claim about the past as a claim about the present.",
"type": "string"
},
{
"const": "blocked",
"description": "Something it cannot run without has not passed, so its own silence means nothing.",
"type": "string"
},
{
"const": "queued",
"description": "The plan selects it and no run has ever reported. Not `unknown`: the question was\nasked and no answer came, which is a debt somebody owes, and not `pass`, which is\nthe mistake this word exists to make impossible.",
"type": "string"
},
{
"const": "exempt",
"description": "The plan does not select it: nothing the task changed can make it true or false.",
"type": "string"
},
{
"const": "unknown",
"description": "It cannot be judged here at all — no model, no git, a ledger that would not read.\nAn honest gap, and never a pass.",
"type": "string"
}
]
}
},
"description": "The declared gate set and the standing of each gate's last recorded run.\n\n`count`, `tallies` and `never_reported` are measured from `gates`, never written down,\nand `unreached` always names what was not consulted.\n\n```\nuse majordomus_cli::gates::GateStateReport;\n\nlet r: GateStateReport = serde_json::from_value(serde_json::json!({\n \"source\": \".ai/repo/ci/gates.yaml\",\n \"ledger\": \".ai/local/state/ledger.jsonl\",\n \"count\": 0,\n \"tallies\": {},\n \"never_reported\": [],\n \"gates\": [],\n \"unreached\": [\"the forge's CI runs were not consulted\"],\n \"findings\": [],\n \"evaluated_at\": \"2026-10-15T00:00:00Z\",\n}))\n.unwrap();\nassert_eq!(r.count, r.gates.len());\nassert!(r.head.is_none(), \"a checkout without git still answers, and says so\");\nassert!(!r.unreached.is_empty());\n```",
"properties": {
"count": {
"description": "How many gates the model declares; measured.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"evaluated_at": {
"description": "When this answer was taken, RFC 3339 UTC.",
"type": "string"
},
"findings": {
"description": "What could not be read, and what that means for the answer.",
"items": {
"type": "string"
},
"type": "array"
},
"gates": {
"description": "Every declared gate, in declaration order.",
"items": {
"$ref": "#/$defs/GateState"
},
"type": "array"
},
"head": {
"description": "The commit this checkout is at, when git could say.",
"type": [
"string",
"null"
]
},
"ledger": {
"description": "Where the recorded runs were read from, repository-relative.",
"type": "string"
},
"never_reported": {
"description": "The gates no run has ever reported, in declaration order.",
"items": {
"type": "string"
},
"type": "array"
},
"source": {
"description": "Where the gate set was read from, repository-relative.",
"type": "string"
},
"tallies": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "How many gates stand in each status, by the status word.",
"type": "object"
},
"unreached": {
"description": "What this answer did not consult, so its silence about it is not read as a verdict.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"source",
"ledger",
"count",
"tallies",
"never_reported",
"gates",
"unreached",
"findings",
"evaluated_at"
],
"title": "GateStateReport",
"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.