intent_realization.explain

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The intent's id."
    }
  },
  "required": [
    "id"
  ],
  "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```",
  "title": "IntentExplainInput"
}

{
  "type": "object",
  "properties": {
    "intent": {
      "$ref": "#/$defs/IntentView",
      "description": "The intent, derived."
    },
    "because": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One sentence per fact the stage rests on: the stage, each criterion, the work."
    },
    "coverage": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CriterionCoverage"
      },
      "description": "The plan's coverage of each of its criteria."
    },
    "realization": {
      "$ref": "#/$defs/IntentRealizationView",
      "description": "Its realization."
    },
    "work": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IntentRealizedWork"
      },
      "description": "Every unit of work linked to it, with its links."
    }
  },
  "required": [
    "intent",
    "because",
    "coverage",
    "realization",
    "work"
  ],
  "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```",
  "title": "IntentExplanation",
  "$defs": {
    "IntentView": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The identity, which is also the file name."
        },
        "title": {
          "type": "string",
          "description": "One line."
        },
        "statement": {
          "type": "string",
          "description": "What must become true."
        },
        "invariants": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What must stay true."
        },
        "stage": {
          "$ref": "#/$defs/IntentStage",
          "description": "Derived: the stage."
        },
        "milestones": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentMilestone"
          },
          "description": "The milestones, each with its derived status."
        },
        "satisfaction": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentCriterion"
          },
          "description": "The criteria, each with its evidence state."
        },
        "met": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Derived: how many criteria are met."
        },
        "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."
        },
        "governance": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The governance a worker on this intent loads."
        },
        "non_goals": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What is deliberately not required."
        },
        "superseded_by": {
          "type": [
            "string",
            "null"
          ],
          "description": "The replacement, when the record names one."
        },
        "source": {
          "type": "string",
          "description": "Repository-relative path of the record."
        }
      },
      "required": [
        "id",
        "title",
        "statement",
        "invariants",
        "stage",
        "milestones",
        "satisfaction",
        "met",
        "verdict",
        "governance",
        "non_goals",
        "source"
      ],
      "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```"
    },
    "IntentStage": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "IntentMilestone": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The id the intent names."
        },
        "resolved": {
          "type": "boolean",
          "description": "Whether the plan holds a milestone with that id."
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "description": "The status the plan derives for it; absent when it does not resolve."
        }
      },
      "required": [
        "id",
        "resolved"
      ],
      "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```"
    },
    "IntentCriterion": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique within the intent."
        },
        "criterion": {
          "type": "string",
          "description": "What is observably true when it is met."
        },
        "evidence": {
          "type": "string",
          "description": "`test`, `claim`, `command` or `deployment`."
        },
        "ref": {
          "type": "string",
          "description": "What the evidence names, as authored."
        },
        "state": {
          "$ref": "#/$defs/IntentEvidenceState",
          "description": "Derived: what the evidence says."
        },
        "met": {
          "type": "boolean",
          "description": "Derived: the state is `current`."
        },
        "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."
        },
        "reproduce": {
          "type": [
            "string",
            "null"
          ],
          "description": "The command that produces the evidence again, when one is known."
        }
      },
      "required": [
        "id",
        "criterion",
        "evidence",
        "ref",
        "state",
        "met"
      ],
      "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```"
    },
    "IntentEvidenceState": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "ProofState": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "IntentVerdict": {
      "type": "object",
      "properties": {
        "state": {
          "$ref": "#/$defs/IntentVerdictState",
          "description": "Derived: what the evidence says."
        },
        "reasons": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentVerdictReason"
          },
          "description": "Every criterion that is not met, with the state of its evidence."
        }
      },
      "required": [
        "state",
        "reasons"
      ],
      "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```"
    },
    "IntentVerdictState": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "IntentVerdictReason": {
      "type": "object",
      "properties": {
        "criterion": {
          "type": "string",
          "description": "The criterion's id."
        },
        "evidence": {
          "type": "string",
          "description": "Its kind of evidence: `test`, `claim`, `command` or `deployment`."
        },
        "state": {
          "$ref": "#/$defs/IntentEvidenceState",
          "description": "The state of that evidence, as the criterion reports it."
        }
      },
      "required": [
        "criterion",
        "evidence",
        "state"
      ],
      "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```"
    },
    "CriterionCoverage": {
      "type": "object",
      "properties": {
        "intent": {
          "type": "string",
          "description": "The intent."
        },
        "criterion": {
          "type": "string",
          "description": "The criterion id inside it."
        },
        "strength": {
          "$ref": "#/$defs/CoverageStrength",
          "description": "The strength derived from the serving issues."
        },
        "issues": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/CoveringIssue"
          },
          "description": "Every live issue that serves it, in id order."
        },
        "milestones": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The milestones those issues belong to, sorted and unique."
        }
      },
      "required": [
        "intent",
        "criterion",
        "strength",
        "issues",
        "milestones"
      ],
      "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```"
    },
    "CoverageStrength": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "CoveringIssue": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The issue id."
        },
        "milestone": {
          "type": "string",
          "description": "Its milestone."
        },
        "status": {
          "type": "string",
          "description": "Its derived status."
        },
        "evidence_need": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "How many evidence tokens it requires before it may be DONE."
        }
      },
      "required": [
        "id",
        "milestone",
        "status",
        "evidence_need"
      ],
      "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```"
    },
    "IntentRealizationView": {
      "type": "object",
      "properties": {
        "intent": {
          "type": "string",
          "description": "The intent."
        },
        "title": {
          "type": "string",
          "description": "Its title."
        },
        "stage": {
          "$ref": "#/$defs/IntentStage",
          "description": "Its derived stage."
        },
        "criteria": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many criteria it declares."
        },
        "met": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many have current evidence."
        },
        "unmet": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentUnmetCriterion"
          },
          "description": "Every criterion without current evidence."
        },
        "work": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentWorkRef"
          },
          "description": "Every unit of work linked to it, strongest link first."
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Every provider that ran work linked to it, each once."
        },
        "findings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentFinding"
          },
          "description": "Drift between the plan's closure and the evidence."
        }
      },
      "required": [
        "intent",
        "title",
        "stage",
        "criteria",
        "met",
        "unmet",
        "work",
        "providers",
        "findings"
      ],
      "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```"
    },
    "IntentUnmetCriterion": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The criterion id."
        },
        "criterion": {
          "type": "string",
          "description": "What must be observably true."
        },
        "evidence": {
          "type": "string",
          "description": "The kind of evidence that settles it."
        },
        "state": {
          "$ref": "#/$defs/IntentEvidenceState",
          "description": "Why it is not met."
        },
        "reproduce": {
          "type": [
            "string",
            "null"
          ],
          "description": "The command that produces its evidence, when one is known."
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The issues declaring they serve it, in plan order."
        }
      },
      "required": [
        "id",
        "criterion",
        "evidence",
        "state"
      ],
      "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```"
    },
    "IntentWorkRef": {
      "type": "object",
      "properties": {
        "kind": {
          "$ref": "#/$defs/IntentWorkKind",
          "description": "Which record."
        },
        "id": {
          "type": "string",
          "description": "Its identity there."
        },
        "outcome": {
          "type": "string",
          "description": "Where it stands."
        },
        "provenance": {
          "$ref": "#/$defs/IntentLinkProvenance",
          "description": "The strongest of its links to this intent."
        },
        "providers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The providers that ran it."
        },
        "handovers": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "How many handovers carried it."
        }
      },
      "required": [
        "kind",
        "id",
        "provenance",
        "handovers"
      ],
      "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```"
    },
    "IntentWorkKind": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "IntentLinkProvenance": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    },
    "IntentFinding": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "description": "`FAIL` or `WARN`. A failure means the intent model is invalid."
        },
        "code": {
          "type": "string",
          "description": "The stable code a reader greps for."
        },
        "subject": {
          "type": "string",
          "description": "The intent or milestone the finding is about."
        },
        "message": {
          "type": "string",
          "description": "What is wrong, in one line."
        },
        "reproduce": {
          "type": "string",
          "description": "The command that shows it again."
        }
      },
      "required": [
        "level",
        "code",
        "subject",
        "message",
        "reproduce"
      ],
      "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```"
    },
    "IntentRealizedWork": {
      "type": "object",
      "properties": {
        "work": {
          "$ref": "#/$defs/IntentWorkUnit",
          "description": "The work, as recorded."
        },
        "links": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentLink"
          },
          "description": "Every intent it realises, strongest link per issue."
        },
        "unlinked": {
          "type": [
            "string",
            "null"
          ],
          "description": "When it realises none: the first link that is missing."
        }
      },
      "required": [
        "work",
        "links"
      ],
      "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```"
    },
    "IntentWorkUnit": {
      "type": "object",
      "properties": {
        "kind": {
          "$ref": "#/$defs/IntentWorkKind",
          "description": "Which record it was read from."
        },
        "id": {
          "type": "string",
          "description": "Its identity in that record: a task id, a session id, or `<peer>/<claim>`."
        },
        "title": {
          "type": "string",
          "description": "What it says it is, in its own words."
        },
        "outcome": {
          "type": "string",
          "description": "Where it stands: a task's outcome, a session's, or `attached`/`departed` for a claim."
        },
        "branches": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The branches it ran on, in first-seen order."
        },
        "scope": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The paths it claims."
        },
        "episodes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntentEpisode"
          },
          "description": "Every episode that worked on it, in first-seen order."
        },
        "handovers": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The handovers that carried it from one episode to the next, repository-relative."
        },
        "named_issues": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Issue ids its own words cite."
        },
        "moved_issues": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Issue ids a recorded event shows it moving."
        }
      },
      "required": [
        "kind",
        "id"
      ],
      "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```"
    },
    "IntentEpisode": {
      "type": "object",
      "properties": {
        "session": {
          "type": "string",
          "description": "The episode id, `s-...`; empty for a peer's connection, which is not an episode."
        },
        "provider": {
          "type": "string",
          "description": "The provider, as its own events or the peer's client name it; empty when unknown."
        },
        "provider_session": {
          "type": "string",
          "description": "The provider's own session identity, when recorded."
        }
      },
      "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```"
    },
    "IntentLink": {
      "type": "object",
      "properties": {
        "intent": {
          "type": "string",
          "description": "The intent."
        },
        "stage": {
          "$ref": "#/$defs/IntentStage",
          "description": "Its derived stage."
        },
        "milestone": {
          "type": "string",
          "description": "The milestone that links the issue to it."
        },
        "issue": {
          "type": "string",
          "description": "The issue that links the work to that milestone."
        },
        "criteria": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The criteria of this intent the issue declares it serves; empty when it declares none."
        },
        "via": {
          "$ref": "#/$defs/IntentLinkVia",
          "description": "The fact the link was read from."
        },
        "provenance": {
          "$ref": "#/$defs/IntentLinkProvenance",
          "description": "How the link is known, from `via`."
        }
      },
      "required": [
        "intent",
        "stage",
        "milestone",
        "issue",
        "via",
        "provenance"
      ],
      "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```"
    },
    "IntentLinkVia": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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```"
    }
  }
}