Skip to content

intent_realization.explain

One intent explained from the derivations alone: a sentence for its stage naming each milestone's derived status, a sentence per criterion naming its evidence state, the plan's coverage of it and the command that reproduces it, a sentence for the work and providers realising it, and each drift finding; beside them the derived intent, the coverage of its criteria, its realization and the work linked to it.

One intent explained from the derivations alone: a sentence for its stage naming each milestone's derived status, a sentence per criterion naming its evidence state, the plan's coverage of it and the command that reproduces it, a sentence for the work and providers realising it, and each drift finding; beside them the derived intent, the coverage of its criteria, its realization and the work linked to it.

Exposure

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

surfaceas
MCPtool majordomus_intent_explain
HTTPGET /api/v1/intents/explain operationId intent_realization.explain
command linemajordomus intent explain

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

Which intent to explain, by the id that is also its file name.

use majordomus_cli::capability::builtin::intent_realization::IntentExplainInput;
let input = IntentExplainInput { id: "intent-lifecycle".into() };
assert_eq!(input.id, "intent-lifecycle");
propertytyperequireddescription
id string yes The intent's id.
JSON Schema 
{
  "additionalProperties": false,
  "description": "Which intent to explain, by the id that is also its file name.\n\n```\nuse majordomus_cli::capability::builtin::intent_realization::IntentExplainInput;\nlet input = IntentExplainInput { id: \"intent-lifecycle\".into() };\nassert_eq!(input.id, \"intent-lifecycle\");\n```",
  "properties": {
    "id": {
      "description": "The intent's id.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "IntentExplainInput",
  "type": "object"
}

output · IntentExplanation

Why an intent stands where it stands: the record, each sentence that explains the stage and each criterion, the plan's coverage of its criteria, and the work realising it.

use majordomus_cli::intent_realization::IntentExplanation;
// every sentence is derived; an explanation holds no authored status
let fields = serde_json::to_value(schemars::schema_for!(IntentExplanation)).unwrap();
assert!(fields["properties"]["because"].is_object());
propertytyperequireddescription
because array yes One sentence per fact the stage rests on: the stage, each criterion, the work.
coverage array yes The plan's coverage of each of its criteria.
intent reference yes The intent, derived.
realization reference yes Its realization.
work array yes Every unit of work linked to it, with its links.
JSON Schema 
{
  "$defs": {
    "CoverageStrength": {
      "description": "How well a criterion is carried by the plan: whether work exists for it, whether that work\nis gated by evidence, and whether the recorded gap already saw it true.\n\n```\nuse majordomus_cli::intent_plan::CoverageStrength;\n// the wire spelling every surface answers with\nassert_eq!(serde_json::to_string(&CoverageStrength::Weak).unwrap(), \"\\\"weak\\\"\");\n// the order is the one a reader ranks by: uncovered is the worst\nassert!(CoverageStrength::Uncovered < CoverageStrength::Covered);\n```",
      "oneOf": [
        {
          "const": "uncovered",
          "description": "No live issue serves it.",
          "type": "string"
        },
        {
          "const": "observed",
          "description": "No live issue serves it, and none needs to: the recorded gap observed it already true.\nWhether it is *met* is still the evidence's question, never this one's.",
          "type": "string"
        },
        {
          "const": "weak",
          "description": "Every live issue serving it requires no evidence, so nothing gates its completion.",
          "type": "string"
        },
        {
          "const": "covered",
          "description": "At least one live issue serving it requires evidence before it is DONE.",
          "type": "string"
        }
      ]
    },
    "CoveringIssue": {
      "description": "One issue as coverage sees it: which milestone carries it, the status the plan derived for\nit, and how much evidence it owes before it may be DONE.\n\n```\nuse majordomus_cli::intent_plan::CoveringIssue;\nlet issue = CoveringIssue {\n    id: \"I1901\".into(),\n    milestone: \"intent-planning\".into(),\n    status: \"READY\".into(),\n    evidence_need: 2,\n};\n// an issue that owes no evidence covers a criterion only weakly\nassert!(issue.evidence_need > 0);\n```",
      "properties": {
        "evidence_need": {
          "description": "How many evidence tokens it requires before it may be DONE.",
          "format": "uint32",
          "minimum": 0,
          "type": "integer"
        },
        "id": {
          "description": "The issue id.",
          "type": "string"
        },
        "milestone": {
          "description": "Its milestone.",
          "type": "string"
        },
        "status": {
          "description": "Its derived status.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "milestone",
        "status",
        "evidence_need"
      ],
      "type": "object"
    },
    "CriterionCoverage": {
      "description": "One criterion of one intent, and the work that carries it: the live issues that serve it,\nthe milestones those issues sit under, and the strength derived from them.\n\n```\nuse majordomus_cli::intent_plan::{CoverageStrength, CriterionCoverage};\nlet c = CriterionCoverage {\n    intent: \"intent-planning\".into(),\n    criterion: \"gap-is-recorded\".into(),\n    strength: CoverageStrength::Uncovered,\n    issues: vec![],\n    milestones: vec![],\n};\n// nothing serves it, so nothing in the plan will make it true\nassert_eq!(c.strength, CoverageStrength::Uncovered);\nassert!(c.issues.is_empty());\n```",
      "properties": {
        "criterion": {
          "description": "The criterion id inside it.",
          "type": "string"
        },
        "intent": {
          "description": "The intent.",
          "type": "string"
        },
        "issues": {
          "description": "Every live issue that serves it, in id order.",
          "items": {
            "$ref": "#/$defs/CoveringIssue"
          },
          "type": "array"
        },
        "milestones": {
          "description": "The milestones those issues belong to, sorted and unique.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "strength": {
          "$ref": "#/$defs/CoverageStrength",
          "description": "The strength derived from the serving issues."
        }
      },
      "required": [
        "intent",
        "criterion",
        "strength",
        "issues",
        "milestones"
      ],
      "type": "object"
    },
    "IntentCriterion": {
      "description": "One criterion with the evidence behind it: what the record declared, what the ledger says\nabout it, whether that meets it, and the command that would produce the evidence again.\n\n```\nuse majordomus_cli::evidence::ProofState;\nuse majordomus_cli::intent::{IntentCriterion, IntentEvidenceState};\nlet c = IntentCriterion {\n    id: \"stage-is-derived\".into(),\n    criterion: \"the stage follows the plan\".into(),\n    evidence: \"test\".into(),\n    reference: \"apps/majordomus-cli/tests/intent.rs\".into(),\n    state: IntentEvidenceState::NotRun,\n    met: false,\n    proof: Some(ProofState::NotRun),\n    reproduce: None,\n};\n// nothing recorded is not a pass\nassert!(!c.met);\n```",
      "properties": {
        "criterion": {
          "description": "What is observably true when it is met.",
          "type": "string"
        },
        "evidence": {
          "description": "`test`, `claim`, `command` or `deployment`.",
          "type": "string"
        },
        "id": {
          "description": "Unique within the intent.",
          "type": "string"
        },
        "met": {
          "description": "Derived: the state is `current`.",
          "type": "boolean"
        },
        "proof": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProofState"
            },
            {
              "type": "null"
            }
          ],
          "description": "Derived: the evidence module's own verdict behind `state`, for a `test` or `claim`\ncriterion whose reference resolves. A met criterion rests on `proven` (a pass at this\nrevision) or `inputs_unchanged` (a pass whose named inputs have not moved since, which\nis not proof at this revision), and every surface shows which, so `met` is never the\none tick for both."
        },
        "ref": {
          "description": "What the evidence names, as authored.",
          "type": "string"
        },
        "reproduce": {
          "description": "The command that produces the evidence again, when one is known.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/IntentEvidenceState",
          "description": "Derived: what the evidence says."
        }
      },
      "required": [
        "id",
        "criterion",
        "evidence",
        "ref",
        "state",
        "met"
      ],
      "type": "object"
    },
    "IntentEpisode": {
      "description": "One execution episode of a piece of work, and the provider that ran it when a record says.\nA provider is never guessed: an episode opened by hand has none.\n\n```\nuse majordomus_cli::intent_realization::IntentEpisode;\nlet e = IntentEpisode {\n    session: \"s-1\".into(),\n    provider: \"codex\".into(),\n    provider_session: String::new(),\n};\nassert_eq!(e.provider, \"codex\");\n```",
      "properties": {
        "provider": {
          "description": "The provider, as its own events or the peer's client name it; empty when unknown.",
          "type": "string"
        },
        "provider_session": {
          "description": "The provider's own session identity, when recorded.",
          "type": "string"
        },
        "session": {
          "description": "The episode id, `s-...`; empty for a peer's connection, which is not an episode.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "IntentEvidenceState": {
      "description": "What the evidence behind one criterion says, as a word. Only `Current` meets a criterion:\na stale, failing, unrecorded or underivable reference never does, and neither does one that\nresolves to nothing.\n\nWhether a recorded run is current is not decided here. A `test` or `claim` criterion is\njudged by the evidence module's one truth table (`evidence::freshness()`) at the working\ntree and read through `evidence::current`, the same judgement the claim report and the\nsubject pages make; `IntentEvidenceState::judged` is the whole of the translation. So\nthe state follows the evidence both ways: a criterion met today reads stale or failing\nthe moment the ledger or the tree says so, and met again once a current pass is recorded.\n\n```\nuse majordomus_cli::intent::IntentEvidenceState;\nassert_eq!(serde_json::to_string(&IntentEvidenceState::NotRun).unwrap(), \"\\\"not_run\\\"\");\nassert_ne!(IntentEvidenceState::Stale, IntentEvidenceState::Current);\n```",
      "oneOf": [
        {
          "const": "current",
          "description": "A passing run that is current evidence at the working tree: its commit is in this\nhistory, it measured a tree that was its commit, the test still hashes to what ran,\nand nothing the criterion names has changed since — for a test, its source and the\nsource and implementation of every claim that test proves; for a claim, what the\nclaim names. A change the criterion does not name, the evidence ledger's own included,\nleaves it current. A test that proves no claim naming an implementation names no code\nunder test, so for it nothing but the ledger may have changed since the run. The only\nstate that meets a criterion; the criterion's `proof` says whether it rests on\n`proven` or on `inputs_unchanged`.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "A pass that is not current evidence: something the criterion names has changed since\nit, it names no code under test and anything but the ledger and the plan's own records\nhas changed since, the\ntest no longer hashes to what ran, the run's commit is not in this history (or git\ncould not compare it), or the run measured a tree that was not its commit — a run on a\ndirty tree, which no later tree can be matched against.",
          "type": "string"
        },
        {
          "const": "failing",
          "description": "The latest recorded run failed, timed out or errored.",
          "type": "string"
        },
        {
          "const": "not_run",
          "description": "The reference resolves and no run counts for it: none was recorded, the latest run\ndeclined to run (a skip), or the claim names no test a runner drives.",
          "type": "string"
        },
        {
          "const": "not_derivable",
          "description": "The reference resolves, and this kind of evidence (`command`, `deployment`) is not\nderivable from the ledger, so it never meets a criterion by itself.",
          "type": "string"
        },
        {
          "const": "unresolved",
          "description": "The reference is empty or names nothing this repository holds.",
          "type": "string"
        }
      ]
    },
    "IntentFinding": {
      "description": "One validation finding: its level, a stable code a reader greps for, the intent or milestone\nit is about, one line of what is wrong, and the command that shows it again.\n\n```\nuse majordomus_cli::intent::{IntentFinding, FAIL};\nlet f = IntentFinding {\n    level: FAIL.into(),\n    code: \"unknown_milestone\".into(),\n    subject: \"intent-lifecycle\".into(),\n    message: \"`no-such` is not a milestone\".into(),\n    reproduce: \"majordomus intent validate\".into(),\n};\nassert_eq!(f.level, \"FAIL\");\nassert_eq!(f.reproduce, \"majordomus intent validate\");\n```",
      "properties": {
        "code": {
          "description": "The stable code a reader greps for.",
          "type": "string"
        },
        "level": {
          "description": "`FAIL` or `WARN`. A failure means the intent model is invalid.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong, in one line.",
          "type": "string"
        },
        "reproduce": {
          "description": "The command that shows it again.",
          "type": "string"
        },
        "subject": {
          "description": "The intent or milestone the finding is about.",
          "type": "string"
        }
      },
      "required": [
        "level",
        "code",
        "subject",
        "message",
        "reproduce"
      ],
      "type": "object"
    },
    "IntentLink": {
      "description": "One link from a piece of work to an intent: through which issue and milestone, serving\nwhich of its criteria, read from which fact, known how.\n\n```\nuse majordomus_cli::intent::IntentStage;\nuse majordomus_cli::intent_realization::{IntentLink, IntentLinkProvenance, IntentLinkVia};\nlet l = IntentLink {\n    intent: \"intent-lifecycle\".into(), stage: IntentStage::Executing,\n    milestone: \"intent-lifecycle\".into(), issue: \"I1900\".into(),\n    criteria: vec![\"stage-is-derived\".into()],\n    via: IntentLinkVia::BranchIssue, provenance: IntentLinkProvenance::Derived,\n};\nassert_eq!(l.provenance, l.via.provenance());\n```",
      "properties": {
        "criteria": {
          "description": "The criteria of this intent the issue declares it serves; empty when it declares none.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "intent": {
          "description": "The intent.",
          "type": "string"
        },
        "issue": {
          "description": "The issue that links the work to that milestone.",
          "type": "string"
        },
        "milestone": {
          "description": "The milestone that links the issue to it.",
          "type": "string"
        },
        "provenance": {
          "$ref": "#/$defs/IntentLinkProvenance",
          "description": "How the link is known, from `via`."
        },
        "stage": {
          "$ref": "#/$defs/IntentStage",
          "description": "Its derived stage."
        },
        "via": {
          "$ref": "#/$defs/IntentLinkVia",
          "description": "The fact the link was read from."
        }
      },
      "required": [
        "intent",
        "stage",
        "milestone",
        "issue",
        "via",
        "provenance"
      ],
      "type": "object"
    },
    "IntentLinkProvenance": {
      "description": "How a link from a piece of work to an issue is known, strongest first.\n\n```\nuse majordomus_cli::intent_realization::IntentLinkProvenance;\nassert_eq!(\n    serde_json::to_string(&IntentLinkProvenance::Inferred).unwrap(),\n    \"\\\"inferred\\\"\"\n);\nassert!(IntentLinkProvenance::Observed < IntentLinkProvenance::Derived);\n```",
      "oneOf": [
        {
          "const": "declared",
          "description": "The work names the issue itself.",
          "type": "string"
        },
        {
          "const": "observed",
          "description": "A recorded event shows the work's episode moving the issue.",
          "type": "string"
        },
        {
          "const": "derived",
          "description": "The branch the work ran on names the issue, by the worktree naming rule.",
          "type": "string"
        },
        {
          "const": "inferred",
          "description": "Nothing stronger exists, and an open issue's scope overlaps the work's scope.",
          "type": "string"
        }
      ]
    },
    "IntentLinkVia": {
      "description": "The fact a link was read from.\n\n```\nuse majordomus_cli::intent_realization::IntentLinkVia;\nassert_eq!(serde_json::to_string(&IntentLinkVia::BranchIssue).unwrap(), \"\\\"branch_issue\\\"\");\nassert_eq!(IntentLinkVia::ScopeOverlap.provenance().as_str(), \"inferred\");\n```",
      "oneOf": [
        {
          "const": "named_issue",
          "description": "The claim or the task's own words cite the issue by id.",
          "type": "string"
        },
        {
          "const": "moved_issue",
          "description": "A plan transition in the work's episode, or the session record's `issues`.",
          "type": "string"
        },
        {
          "const": "branch_issue",
          "description": "The branch name carries the issue id.",
          "type": "string"
        },
        {
          "const": "scope_overlap",
          "description": "An open issue's scope overlaps the work's scope.",
          "type": "string"
        }
      ]
    },
    "IntentMilestone": {
      "description": "One milestone an intent names, as the plan derives it. A milestone that does not resolve is\ncarried with `resolved: false` rather than dropped, because a name that points at nothing is\na finding and not an absence.\n\n```\nuse majordomus_cli::intent::IntentMilestone;\nlet named = IntentMilestone { id: \"no-such\".into(), resolved: false, status: None };\nassert!(!named.resolved);\nassert!(named.status.is_none());\n```",
      "properties": {
        "id": {
          "description": "The id the intent names.",
          "type": "string"
        },
        "resolved": {
          "description": "Whether the plan holds a milestone with that id.",
          "type": "boolean"
        },
        "status": {
          "description": "The status the plan derives for it; absent when it does not resolve.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "resolved"
      ],
      "type": "object"
    },
    "IntentRealizationView": {
      "description": "One intent, realised: how far reality is from it, the work realising it and by whom, and the\ndrift between closed work and current evidence.\n\n```\nuse majordomus_cli::intent::IntentStage;\nuse majordomus_cli::intent_realization::IntentRealizationView;\nlet v = IntentRealizationView {\n    intent: \"x\".into(), title: \"X\".into(), stage: IntentStage::Verifying,\n    criteria: 2, met: 1, unmet: vec![], work: vec![], providers: vec![], findings: vec![],\n};\nassert!(v.met < v.criteria);\n```",
      "properties": {
        "criteria": {
          "description": "How many criteria it declares.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "findings": {
          "description": "Drift between the plan's closure and the evidence.",
          "items": {
            "$ref": "#/$defs/IntentFinding"
          },
          "type": "array"
        },
        "intent": {
          "description": "The intent.",
          "type": "string"
        },
        "met": {
          "description": "How many have current evidence.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "providers": {
          "description": "Every provider that ran work linked to it, each once.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "stage": {
          "$ref": "#/$defs/IntentStage",
          "description": "Its derived stage."
        },
        "title": {
          "description": "Its title.",
          "type": "string"
        },
        "unmet": {
          "description": "Every criterion without current evidence.",
          "items": {
            "$ref": "#/$defs/IntentUnmetCriterion"
          },
          "type": "array"
        },
        "work": {
          "description": "Every unit of work linked to it, strongest link first.",
          "items": {
            "$ref": "#/$defs/IntentWorkRef"
          },
          "type": "array"
        }
      },
      "required": [
        "intent",
        "title",
        "stage",
        "criteria",
        "met",
        "unmet",
        "work",
        "providers",
        "findings"
      ],
      "type": "object"
    },
    "IntentRealizedWork": {
      "description": "A unit of work with every intent it realises, or the reason it realises none.\n\n```\nuse majordomus_cli::intent_realization::{IntentRealizedWork, IntentWorkKind, IntentWorkUnit};\nlet w = IntentRealizedWork {\n    work: IntentWorkUnit::new(IntentWorkKind::Task, \"t-1\"),\n    links: vec![],\n    unlinked: Some(\"it names no issue\".into()),\n};\nassert!(w.links.is_empty() && w.unlinked.is_some());\n```",
      "properties": {
        "links": {
          "description": "Every intent it realises, strongest link per issue.",
          "items": {
            "$ref": "#/$defs/IntentLink"
          },
          "type": "array"
        },
        "unlinked": {
          "description": "When it realises none: the first link that is missing.",
          "type": [
            "string",
            "null"
          ]
        },
        "work": {
          "$ref": "#/$defs/IntentWorkUnit",
          "description": "The work, as recorded."
        }
      },
      "required": [
        "work",
        "links"
      ],
      "type": "object"
    },
    "IntentStage": {
      "description": "Where an intent stands, derived on every read and stored nowhere.\n\n```\nuse majordomus_cli::intent::IntentStage;\n// one word every surface prints, and an order that follows the work\nassert_eq!(IntentStage::Executing.as_str(), \"executing\");\nassert!(IntentStage::Declared < IntentStage::Satisfied);\n```",
      "oneOf": [
        {
          "const": "declared",
          "description": "A named milestone does not resolve, or none is named.",
          "type": "string"
        },
        {
          "const": "planned",
          "description": "Every milestone resolves and none has started.",
          "type": "string"
        },
        {
          "const": "executing",
          "description": "A milestone is under way.",
          "type": "string"
        },
        {
          "const": "verifying",
          "description": "Every milestone that counts is DONE; satisfaction is not yet evidenced.",
          "type": "string"
        },
        {
          "const": "satisfied",
          "description": "Verifying, and every criterion has current evidence.",
          "type": "string"
        },
        {
          "const": "cancelled",
          "description": "The record says it was abandoned.",
          "type": "string"
        },
        {
          "const": "superseded",
          "description": "The record names the intent that replaced it.",
          "type": "string"
        }
      ]
    },
    "IntentUnmetCriterion": {
      "description": "A criterion an intent still lacks, with the issues that declare they serve it.\n\n```\nuse majordomus_cli::intent::IntentEvidenceState;\nuse majordomus_cli::intent_realization::IntentUnmetCriterion;\nlet c = IntentUnmetCriterion {\n    id: \"surfaces-agree\".into(), criterion: \"the surfaces agree\".into(),\n    evidence: \"test\".into(), state: IntentEvidenceState::Stale,\n    reproduce: None, issues: vec![\"I1900\".into()],\n};\nassert_eq!(c.state, IntentEvidenceState::Stale);\n```",
      "properties": {
        "criterion": {
          "description": "What must be observably true.",
          "type": "string"
        },
        "evidence": {
          "description": "The kind of evidence that settles it.",
          "type": "string"
        },
        "id": {
          "description": "The criterion id.",
          "type": "string"
        },
        "issues": {
          "description": "The issues declaring they serve it, in plan order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "reproduce": {
          "description": "The command that produces its evidence, when one is known.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/IntentEvidenceState",
          "description": "Why it is not met."
        }
      },
      "required": [
        "id",
        "criterion",
        "evidence",
        "state"
      ],
      "type": "object"
    },
    "IntentVerdict": {
      "description": "Whether the evidence alone settles an intent, and which criteria hold it back: every\nunmet criterion, in the order the record declares them. Empty when the verdict is\n`satisfied`, and when it is `unknown` because the intent declares no criterion.\n\n```\nuse majordomus_cli::intent::{verdict, IntentVerdict, IntentVerdictState};\n// an intent that declares no criterion cannot be settled by evidence\nlet v: IntentVerdict = verdict(&[]);\nassert_eq!(v.state, IntentVerdictState::Unknown);\nassert!(v.reasons.is_empty());\n```",
      "properties": {
        "reasons": {
          "description": "Every criterion that is not met, with the state of its evidence.",
          "items": {
            "$ref": "#/$defs/IntentVerdictReason"
          },
          "type": "array"
        },
        "state": {
          "$ref": "#/$defs/IntentVerdictState",
          "description": "Derived: what the evidence says."
        }
      },
      "required": [
        "state",
        "reasons"
      ],
      "type": "object"
    },
    "IntentVerdictReason": {
      "description": "One criterion that holds a verdict back from `satisfied`: which one, the kind of evidence\nit names, and the state that evidence is in — the criterion's own words, not new ones.\n\n```\nuse majordomus_cli::intent::{IntentEvidenceState, IntentVerdictReason};\nlet r = IntentVerdictReason {\n    criterion: \"probe-passes\".into(),\n    evidence: \"test\".into(),\n    state: IntentEvidenceState::NotRun,\n};\nassert_eq!(r.state, IntentEvidenceState::NotRun);\n```",
      "properties": {
        "criterion": {
          "description": "The criterion's id.",
          "type": "string"
        },
        "evidence": {
          "description": "Its kind of evidence: `test`, `claim`, `command` or `deployment`.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/IntentEvidenceState",
          "description": "The state of that evidence, as the criterion reports it."
        }
      },
      "required": [
        "criterion",
        "evidence",
        "state"
      ],
      "type": "object"
    },
    "IntentVerdictState": {
      "description": "What the evidence alone says about an intent, as a word: derived from its criteria and\nnever from the plan, so it can read `satisfied` while a milestone is still open (ADR 0107).\n\n```\nuse majordomus_cli::intent::IntentVerdictState;\nlet word = serde_json::to_string(&IntentVerdictState::Unsatisfied).unwrap();\nassert_eq!(word, \"\\\"unsatisfied\\\"\");\nassert_eq!(IntentVerdictState::Satisfied.as_str(), \"satisfied\");\n```",
      "oneOf": [
        {
          "const": "satisfied",
          "description": "Every criterion has current evidence.",
          "type": "string"
        },
        {
          "const": "unsatisfied",
          "description": "A criterion the ledger or the claim join can settle (`test`, `claim`) is not met.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Every unmet criterion is of a kind the ledger cannot yet settle (`command`,\n`deployment`), or the intent declares no criterion: the evidence cannot answer.",
          "type": "string"
        }
      ]
    },
    "IntentView": {
      "description": "One intent, as its record declares it and as the plan and the ledger derive it: the\nstatement and invariants as authored, each milestone with its derived status, each criterion\nwith the state of its evidence, the stage that follows from both, and the verdict that\nfollows from the evidence alone.\n\n```\nuse majordomus_cli::intent::{verdict, IntentStage, IntentVerdictState, IntentView};\nlet view = IntentView {\n    id: \"intent-lifecycle\".into(),\n    title: \"Work is traceable to the intent it serves\".into(),\n    statement: \"A reader can ask what work is for.\".into(),\n    invariants: vec![\"no intent status is stored\".into()],\n    stage: IntentStage::Declared,\n    milestones: vec![],\n    satisfaction: vec![],\n    met: 0,\n    verdict: verdict(&[]),\n    governance: vec![\"adr:adr-0070\".into()],\n    non_goals: vec![],\n    superseded_by: None,\n    source: \".ai/repo/project/intents/intent-lifecycle.yaml\".into(),\n};\n// a record naming no milestone that resolves has not been planned\nassert_eq!(view.stage, IntentStage::Declared);\n// and one declaring no criterion cannot be settled by evidence\nassert_eq!(view.verdict.state, IntentVerdictState::Unknown);\n```",
      "properties": {
        "governance": {
          "description": "The governance a worker on this intent loads.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "description": "The identity, which is also the file name.",
          "type": "string"
        },
        "invariants": {
          "description": "What must stay true.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "met": {
          "description": "Derived: how many criteria are met.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "milestones": {
          "description": "The milestones, each with its derived status.",
          "items": {
            "$ref": "#/$defs/IntentMilestone"
          },
          "type": "array"
        },
        "non_goals": {
          "description": "What is deliberately not required.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "satisfaction": {
          "description": "The criteria, each with its evidence state.",
          "items": {
            "$ref": "#/$defs/IntentCriterion"
          },
          "type": "array"
        },
        "source": {
          "description": "Repository-relative path of the record.",
          "type": "string"
        },
        "stage": {
          "$ref": "#/$defs/IntentStage",
          "description": "Derived: the stage."
        },
        "statement": {
          "description": "What must become true.",
          "type": "string"
        },
        "superseded_by": {
          "description": "The replacement, when the record names one.",
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "description": "One line.",
          "type": "string"
        },
        "verdict": {
          "$ref": "#/$defs/IntentVerdict",
          "description": "Derived from the criteria alone, never from the plan: whether the evidence settles the\nintent, and which criteria hold it back."
        }
      },
      "required": [
        "id",
        "title",
        "statement",
        "invariants",
        "stage",
        "milestones",
        "satisfaction",
        "met",
        "verdict",
        "governance",
        "non_goals",
        "source"
      ],
      "type": "object"
    },
    "IntentWorkKind": {
      "description": "Which record a unit of work was read from.\n\n```\nuse majordomus_cli::intent_realization::IntentWorkKind;\nassert_eq!(serde_json::to_string(&IntentWorkKind::PeerClaim).unwrap(), \"\\\"peer_claim\\\"\");\n```",
      "oneOf": [
        {
          "const": "task",
          "description": "A task of this checkout's ledger: the durable unit a handover continues, across every\nepisode that worked on it.",
          "type": "string"
        },
        {
          "const": "peer_claim",
          "description": "A claim a peer announced on the shared server's board.",
          "type": "string"
        },
        {
          "const": "session_record",
          "description": "A closed session record of the shared layer whose episode this checkout's ledger does\nnot hold — another machine's or another checkout's work.",
          "type": "string"
        }
      ]
    },
    "IntentWorkRef": {
      "description": "A unit of work as one intent sees it: which record, how it stands, and the strongest link.\n\n```\nuse majordomus_cli::intent_realization::{IntentLinkProvenance, IntentWorkKind, IntentWorkRef};\nlet r = IntentWorkRef {\n    kind: IntentWorkKind::Task, id: \"t-1\".into(), outcome: \"active\".into(),\n    provenance: IntentLinkProvenance::Observed, providers: vec![\"codex\".into()],\n    handovers: 1,\n};\nassert_eq!(r.handovers, 1);\n```",
      "properties": {
        "handovers": {
          "description": "How many handovers carried it.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "id": {
          "description": "Its identity there.",
          "type": "string"
        },
        "kind": {
          "$ref": "#/$defs/IntentWorkKind",
          "description": "Which record."
        },
        "outcome": {
          "description": "Where it stands.",
          "type": "string"
        },
        "provenance": {
          "$ref": "#/$defs/IntentLinkProvenance",
          "description": "The strongest of its links to this intent."
        },
        "providers": {
          "description": "The providers that ran it.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "kind",
        "id",
        "provenance",
        "handovers"
      ],
      "type": "object"
    },
    "IntentWorkUnit": {
      "description": "One unit of work as its records describe it, before it is joined to any intent.\n\n```\nuse majordomus_cli::intent_realization::{IntentWorkKind, IntentWorkUnit};\nlet unit = IntentWorkUnit::new(IntentWorkKind::Task, \"t-1\");\nassert!(unit.episodes.is_empty());\nassert_eq!(unit.id, \"t-1\");\n```",
      "properties": {
        "branches": {
          "description": "The branches it ran on, in first-seen order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "episodes": {
          "description": "Every episode that worked on it, in first-seen order.",
          "items": {
            "$ref": "#/$defs/IntentEpisode"
          },
          "type": "array"
        },
        "handovers": {
          "description": "The handovers that carried it from one episode to the next, repository-relative.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "id": {
          "description": "Its identity in that record: a task id, a session id, or `<peer>/<claim>`.",
          "type": "string"
        },
        "kind": {
          "$ref": "#/$defs/IntentWorkKind",
          "description": "Which record it was read from."
        },
        "moved_issues": {
          "description": "Issue ids a recorded event shows it moving.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "named_issues": {
          "description": "Issue ids its own words cite.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "outcome": {
          "description": "Where it stands: a task's outcome, a session's, or `attached`/`departed` for a claim.",
          "type": "string"
        },
        "scope": {
          "description": "The paths it claims.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "title": {
          "description": "What it says it is, in its own words.",
          "type": "string"
        }
      },
      "required": [
        "kind",
        "id"
      ],
      "type": "object"
    },
    "ProofState": {
      "description": "What the repository can say about one claim's proof, right now.\n\nOrdered from strongest to weakest, so a summary that sorts by this reads as a ranking.\n\n```\nuse majordomus_cli::evidence::ProofState;\n\nlet mut states = vec![ProofState::NotRun, ProofState::Stale, ProofState::Proven];\nstates.sort();\nassert_eq!(\n    states,\n    vec![ProofState::Proven, ProofState::Stale, ProofState::NotRun]\n);\n\n// the two strongest are deliberately not one state: `inputs unchanged` is the absence\n// of a known invalidation, and collapsing it into `proven` is the unaccountable badge\nassert_ne!(ProofState::Proven, ProofState::InputsUnchanged);\nassert!(ProofState::Proven < ProofState::InputsUnchanged);\nassert!(ProofState::InputsUnchanged.passing());\n```\n# Example\n\n```\nuse majordomus_cli::evidence::ProofState;\nassert!(ProofState::Proven.passing());\nassert!(!ProofState::NotRun.passing());\nassert!(!ProofState::InputsUnchanged.meaning().is_empty());\n```",
      "oneOf": [
        {
          "const": "proven",
          "description": "A passing run, and nothing has changed since it — the diff against the execution's\nown commit is empty but for the ledger. Proof of the tree in front of you.",
          "type": "string"
        },
        {
          "const": "inputs_unchanged",
          "description": "A passing run, and nothing this claim names has changed since. Not proof at HEAD:\nsomething the claim does not name may have broken it.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "A passing run, but something this claim names has changed since. The proof is older\nthan its subject.",
          "type": "string"
        },
        {
          "const": "failing",
          "description": "The latest run of this claim's test did not pass.",
          "type": "string"
        },
        {
          "const": "not_run",
          "description": "The claim names a test a runner owns, and no run of it has ever been recorded.",
          "type": "string"
        },
        {
          "const": "unrunnable",
          "description": "The claim names a path no runner in this repository drives. Nothing can record it,\nso nothing can prove it this way.",
          "type": "string"
        },
        {
          "const": "no_test",
          "description": "The claim names no test at all. Correct for a `planned` or `rejected` claim, and a\ndefect for any other.",
          "type": "string"
        }
      ]
    }
  },
  "description": "Why an intent stands where it stands: the record, each sentence that explains the stage and\neach criterion, the plan's coverage of its criteria, and the work realising it.\n\n```\nuse majordomus_cli::intent_realization::IntentExplanation;\n// every sentence is derived; an explanation holds no authored status\nlet fields = serde_json::to_value(schemars::schema_for!(IntentExplanation)).unwrap();\nassert!(fields[\"properties\"][\"because\"].is_object());\n```",
  "properties": {
    "because": {
      "description": "One sentence per fact the stage rests on: the stage, each criterion, the work.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "coverage": {
      "description": "The plan's coverage of each of its criteria.",
      "items": {
        "$ref": "#/$defs/CriterionCoverage"
      },
      "type": "array"
    },
    "intent": {
      "$ref": "#/$defs/IntentView",
      "description": "The intent, derived."
    },
    "realization": {
      "$ref": "#/$defs/IntentRealizationView",
      "description": "Its realization."
    },
    "work": {
      "description": "Every unit of work linked to it, with its links.",
      "items": {
        "$ref": "#/$defs/IntentRealizedWork"
      },
      "type": "array"
    }
  },
  "required": [
    "intent",
    "because",
    "coverage",
    "realization",
    "work"
  ],
  "title": "IntentExplanation",
  "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.

transportstatecasestargets
directcovered1first-intent
mcpcovered1first-intent
httpcovered1first-intent

Searches the titles and descriptions of every page this site publishes.