gates.state

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$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"
}