intent_realization.work

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "intent": {
      "type": [
        "string",
        "null"
      ],
      "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."
    }
  },
  "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```",
  "title": "IntentRealizationInput"
}

{
  "type": "object",
  "properties": {
    "intents": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IntentRealizationView"
      },
      "description": "Every intent, in identity order."
    },
    "work": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IntentRealizedWork"
      },
      "description": "Every unit of work read, with its links."
    },
    "orphans": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many units of work realise no intent."
    },
    "findings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IntentFinding"
      },
      "description": "Every finding: each intent's drift, then the live work that serves no intent."
    }
  },
  "required": [
    "intents",
    "work",
    "orphans",
    "findings"
  ],
  "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```",
  "title": "IntentRealization",
  "$defs": {
    "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```"
    },
    "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```"
    },
    "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```"
    },
    "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```"
    },
    "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```"
    }
  }
}