skills.explain

{
  "additionalProperties": false,
  "description": "Which skill to explain, by its id. An id the repository does not hold is a refusal\nnaming what was looked for, never an empty answer.\n\n```\nuse majordomus_cli::capability::builtin::skills::SkillExplainInput;\nlet input = SkillExplainInput { id: \"implement\".into() };\nassert_eq!(input.id, \"implement\");\n```",
  "properties": {
    "id": {
      "description": "The skill's id, which is also its directory name.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "SkillExplainInput",
  "type": "object"
}

{
  "$defs": {
    "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"
        }
      ]
    },
    "SkillDocumented": {
      "description": "The documented fact: the page the site projects for the skill.\n\n```\nuse majordomus_cli::skill::SkillDocumented;\nlet d = SkillDocumented { documented: true, page: \"site/content/skills/implement.md\".into() };\nassert!(d.page.ends_with(\"implement.md\"));\n```",
      "properties": {
        "documented": {
          "description": "Whether the page is a tracked file.",
          "type": "boolean"
        },
        "page": {
          "description": "Where the page is projected.",
          "type": "string"
        }
      },
      "required": [
        "documented",
        "page"
      ],
      "type": "object"
    },
    "SkillEnforced": {
      "description": "The enforced fact: the doctrine that validates skills and the gates a change to this one\nselects.\n\n```\nuse majordomus_cli::skill::SkillEnforced;\nlet e = SkillEnforced { enforced: false, doctrine: None, gates: vec![] };\nassert!(!e.enforced);\n```",
      "properties": {
        "doctrine": {
          "description": "The rule whose validator is `skills`, when the index holds one.",
          "type": [
            "string",
            "null"
          ]
        },
        "enforced": {
          "description": "A doctrine validates skills, and a gate running the verification covers this file.",
          "type": "boolean"
        },
        "gates": {
          "description": "The CI gates a change to the skill selects whose command runs `skills verify`.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "enforced",
        "gates"
      ],
      "type": "object"
    },
    "SkillEvidence": {
      "description": "What the evidence ledger can say about a skill's tests, as a whole: the weakest state of\nthe tests that name it, or `untested` when none does.\n\n```\nuse majordomus_cli::skill::SkillEvidence;\nassert!(SkillEvidence::Proven.current());\nassert!(SkillEvidence::InputsUnchanged.current());\nassert!(!SkillEvidence::Stale.current());\nassert!(SkillEvidence::Proven < SkillEvidence::Untested);\n```",
      "oneOf": [
        {
          "const": "proven",
          "description": "Every naming test has a passing run, and nothing but the ledger changed since.",
          "type": "string"
        },
        {
          "const": "inputs_unchanged",
          "description": "Every naming test passed, and neither the test nor the skill changed since.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "A passing run exists, and the test or the skill changed since.",
          "type": "string"
        },
        {
          "const": "failing",
          "description": "The latest recorded run of a naming test did not pass.",
          "type": "string"
        },
        {
          "const": "not_run",
          "description": "A test names the skill and no run of it was ever recorded.",
          "type": "string"
        },
        {
          "const": "unrunnable",
          "description": "A test names the skill from a path no runner drives.",
          "type": "string"
        },
        {
          "const": "untested",
          "description": "No test names the skill.",
          "type": "string"
        }
      ]
    },
    "SkillFinding": {
      "description": "One thing the derivation found wrong, with the command that settles or reproduces it.\n\n```\nuse majordomus_cli::skill::{SkillFinding, SkillFindingLevel};\nlet f = SkillFinding {\n    level: SkillFindingLevel::Fail,\n    code: \"untested\".into(),\n    skill: Some(\"implement\".into()),\n    subject: \".ai/repo/skills/implement/SKILL.md\".into(),\n    message: \"no test names this skill\".into(),\n    reproduce: \"majordomus skills explain implement\".into(),\n};\nassert!(f.reproduce.contains(\"explain\"));\n```",
      "properties": {
        "code": {
          "description": "A stable code: `contract`, `untested`, `unused`, `unevidenced`, `failing`,\n`undocumented`, `unenforced`, `unknown_skill_in_test`, `unknown_skill_invoked`.",
          "type": "string"
        },
        "level": {
          "$ref": "#/$defs/SkillFindingLevel",
          "description": "`fail` or `warn`."
        },
        "message": {
          "description": "What is wrong, and what to do about it.",
          "type": "string"
        },
        "reproduce": {
          "description": "The command that reproduces or settles it.",
          "type": "string"
        },
        "skill": {
          "description": "The skill concerned, when the finding is about one.",
          "type": [
            "string",
            "null"
          ]
        },
        "subject": {
          "description": "The file the finding is about, repository-relative.",
          "type": "string"
        }
      },
      "required": [
        "level",
        "code",
        "subject",
        "message",
        "reproduce"
      ],
      "type": "object"
    },
    "SkillFindingLevel": {
      "description": "How bad a finding is: a failure refuses, a warning is reported.\n\n```\nuse majordomus_cli::skill::SkillFindingLevel;\nassert_ne!(SkillFindingLevel::Fail, SkillFindingLevel::Warn);\n```",
      "oneOf": [
        {
          "const": "fail",
          "description": "Refuses: `skills verify` exits 10 and the doctrine fails.",
          "type": "string"
        },
        {
          "const": "warn",
          "description": "Reported, and does not refuse.",
          "type": "string"
        }
      ]
    },
    "SkillInvocation": {
      "description": "One place a skill is invoked from.\n\n```\nuse majordomus_cli::skill::SkillInvocation;\nlet i = SkillInvocation {\n    path: \".ai/repo/prompts/review.md\".into(),\n    line: 3,\n    reference: \"majordomus://skill/repo-review\".into(),\n};\nassert_eq!(i.line, 3);\n```",
      "properties": {
        "line": {
          "description": "The 1-based line the reference is on.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "path": {
          "description": "The invocation surface, repository-relative.",
          "type": "string"
        },
        "reference": {
          "description": "The reference as written.",
          "type": "string"
        }
      },
      "required": [
        "path",
        "line",
        "reference"
      ],
      "type": "object"
    },
    "SkillProvenance": {
      "description": "Where a skill came from, when it was not written here first: an opaque marker into a\nledger kept outside the repository. The committed half names no source; the ledger entry\nit points at does, locally.\n\n```\nuse majordomus_cli::skill::SkillProvenance;\nlet p = SkillProvenance {\n    origin: \"prior-art\".into(),\n    ledger: \"import-2026-09-09#1\".into(),\n    decision: \"adapted\".into(),\n};\nassert!(p.ledger.starts_with(\"import-\"));\n```",
      "properties": {
        "decision": {
          "description": "`adapted`, `reimplemented` or `merged`.",
          "type": "string"
        },
        "ledger": {
          "description": "`import-<date>#<n>`: the entry of the local import ledger that holds the mapping.",
          "type": "string"
        },
        "origin": {
          "description": "`prior-art`: the concept was studied elsewhere before this skill was written.",
          "type": "string"
        }
      },
      "required": [
        "origin",
        "ledger",
        "decision"
      ],
      "type": "object"
    },
    "SkillStanding": {
      "description": "Where a skill stands, derived from the four facts.\n\n```\nuse majordomus_cli::skill::SkillStanding;\nassert_eq!(SkillStanding::Orphan.label(), \"orphan\");\n```",
      "oneOf": [
        {
          "const": "proven",
          "description": "Active, and tested with current evidence, documented, enforced and used.",
          "type": "string"
        },
        {
          "const": "partial",
          "description": "Active, named by a test and invoked, with at least one debt a warning names.",
          "type": "string"
        },
        {
          "const": "orphan",
          "description": "Active, and no test names it or nothing invokes it.",
          "type": "string"
        },
        {
          "const": "invalid",
          "description": "Its file does not satisfy the skill contract; one the index refused outright is listed\nhere too, so a listing never silently shrinks.",
          "type": "string"
        },
        {
          "const": "not_required",
          "description": "Draft or deprecated: nothing is owed.",
          "type": "string"
        }
      ]
    },
    "SkillTest": {
      "description": "One test that names a skill, and what the ledger says about it.\n\n```\nuse majordomus_cli::evidence::ProofState;\nuse majordomus_cli::skill::SkillTest;\nlet t = SkillTest {\n    path: \"test/cases/95_skills.sh\".into(),\n    test: Some(\"suite:95_skills\".into()),\n    state: ProofState::NotRun,\n    reproduce: Some(\"bash test/run.sh 95_skills\".into()),\n    recorded_at: None,\n};\nassert_eq!(t.state, ProofState::NotRun);\n```",
      "properties": {
        "path": {
          "description": "The test's path.",
          "type": "string"
        },
        "recorded_at": {
          "description": "When the run behind the state was recorded.",
          "type": [
            "string",
            "null"
          ]
        },
        "reproduce": {
          "description": "The command that runs it again.",
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "$ref": "#/$defs/ProofState",
          "description": "What the ledger says about its latest run, for this skill."
        },
        "test": {
          "description": "Its identity in the ledger, when a runner owns the path.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "path",
        "state"
      ],
      "type": "object"
    },
    "SkillTested": {
      "description": "The tested fact: the tests that name the skill, and their weakest state.\n\n```\nuse majordomus_cli::skill::{SkillEvidence, SkillTested};\nlet t = SkillTested { state: SkillEvidence::Untested, tests: vec![] };\nassert!(!t.state.current());\n```",
      "properties": {
        "state": {
          "$ref": "#/$defs/SkillEvidence",
          "description": "The weakest state of the naming tests; `untested` when there are none."
        },
        "tests": {
          "description": "Every test that names the skill, in path order.",
          "items": {
            "$ref": "#/$defs/SkillTest"
          },
          "type": "array"
        }
      },
      "required": [
        "state",
        "tests"
      ],
      "type": "object"
    },
    "SkillUsed": {
      "description": "The used fact: every invocation surface that references the skill.\n\n```\nuse majordomus_cli::skill::SkillUsed;\nlet u = SkillUsed { used: false, invocations: vec![] };\nassert!(!u.used);\n```",
      "properties": {
        "invocations": {
          "description": "Every reference, in path and line order.",
          "items": {
            "$ref": "#/$defs/SkillInvocation"
          },
          "type": "array"
        },
        "used": {
          "description": "At least one invocation surface references the skill.",
          "type": "boolean"
        }
      },
      "required": [
        "used",
        "invocations"
      ],
      "type": "object"
    }
  },
  "description": "One skill with everything derived about it.\n\n```\nuse majordomus_cli::skill::SkillStatus;\n// every fact is always present in the answer, so a client never has to tell \"absent\"\n// from \"false\"; only the provenance is optional\nlet schema = serde_json::to_value(schemars::schema_for!(SkillStatus)).unwrap();\nlet required = schema[\"required\"].as_array().unwrap();\nfor field in [\"id\", \"valid\", \"tested\", \"documented\", \"enforced\", \"used\", \"standing\"] {\n    assert!(required.iter().any(|f| f == field), \"{field}\");\n}\nassert!(!required.iter().any(|f| f == \"provenance\"));\n```",
  "properties": {
    "description": {
      "description": "The description as authored.",
      "type": "string"
    },
    "documented": {
      "$ref": "#/$defs/SkillDocumented",
      "description": "The documented fact."
    },
    "enforced": {
      "$ref": "#/$defs/SkillEnforced",
      "description": "The enforced fact."
    },
    "findings": {
      "description": "The findings about this skill.",
      "items": {
        "$ref": "#/$defs/SkillFinding"
      },
      "type": "array"
    },
    "id": {
      "description": "The skill's id, which is its directory name.",
      "type": "string"
    },
    "path": {
      "description": "The file, repository-relative.",
      "type": "string"
    },
    "provenance": {
      "anyOf": [
        {
          "$ref": "#/$defs/SkillProvenance"
        },
        {
          "type": "null"
        }
      ],
      "description": "Where it came from, when it declares that."
    },
    "standing": {
      "$ref": "#/$defs/SkillStanding",
      "description": "Where it stands, derived from the four."
    },
    "status": {
      "description": "The lifecycle status as authored: `draft`, `active` or `deprecated`; `unknown` for a\nfile the index refused.",
      "type": "string"
    },
    "tested": {
      "$ref": "#/$defs/SkillTested",
      "description": "The tested fact."
    },
    "title": {
      "description": "The title as authored.",
      "type": "string"
    },
    "uri": {
      "description": "`majordomus://skill/<id>`.",
      "type": "string"
    },
    "used": {
      "$ref": "#/$defs/SkillUsed",
      "description": "The used fact."
    },
    "valid": {
      "description": "Whether the file satisfies the skill contract, as the index judged it.",
      "type": "boolean"
    },
    "version": {
      "description": "The version as authored.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "id",
    "uri",
    "title",
    "description",
    "status",
    "version",
    "path",
    "valid",
    "tested",
    "documented",
    "enforced",
    "used",
    "standing",
    "findings"
  ],
  "title": "SkillStatus",
  "type": "object"
}