intent_realization.work

{
  "additionalProperties": false,
  "description": "Which intent to answer the realization of; every intent when absent.\n\n```\nuse majordomus_cli::capability::builtin::intent_realization::IntentRealizationInput;\nlet all = IntentRealizationInput::default();\nassert!(all.intent.is_none());\n```",
  "properties": {
    "intent": {
      "description": "An intent id. When given, only that intent, the work linked to it and its findings are\nanswered; the unlinked work is left out.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "IntentRealizationInput",
  "type": "object"
}

{
  "$defs": {
    "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"
        }
      ]
    },
    "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"
    },
    "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"
    }
  },
  "description": "Every intent, realised, and every unit of work, joined: what `majordomus intent realization`\nanswers.\n\n```\nuse majordomus_cli::intent_realization::IntentRealization;\nlet r = IntentRealization { intents: vec![], work: vec![], orphans: 0, findings: vec![] };\nassert_eq!(r.orphans, 0);\n```",
  "properties": {
    "findings": {
      "description": "Every finding: each intent's drift, then the live work that serves no intent.",
      "items": {
        "$ref": "#/$defs/IntentFinding"
      },
      "type": "array"
    },
    "intents": {
      "description": "Every intent, in identity order.",
      "items": {
        "$ref": "#/$defs/IntentRealizationView"
      },
      "type": "array"
    },
    "orphans": {
      "description": "How many units of work realise no intent.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "work": {
      "description": "Every unit of work read, with its links.",
      "items": {
        "$ref": "#/$defs/IntentRealizedWork"
      },
      "type": "array"
    }
  },
  "required": [
    "intents",
    "work",
    "orphans",
    "findings"
  ],
  "title": "IntentRealization",
  "type": "object"
}