HTTP API: skills

The documented fact: the page the site projects for the skill.

use majordomus_cli::skill::SkillDocumented;
let d = SkillDocumented { documented: true, page: "site/content/skills/implement.md".into() };
assert!(d.page.ends_with("implement.md"));

The enforced fact: the doctrine that validates skills and the gates a change to this one selects.

use majordomus_cli::skill::SkillEnforced;
let e = SkillEnforced { enforced: false, doctrine: None, gates: vec![] };
assert!(!e.enforced);

What the evidence ledger can say about a skill's tests, as a whole: the weakest state of the tests that name it, or untested when none does.

use majordomus_cli::skill::SkillEvidence;
assert!(SkillEvidence::Proven.current());
assert!(SkillEvidence::InputsUnchanged.current());
assert!(!SkillEvidence::Stale.current());
assert!(SkillEvidence::Proven < SkillEvidence::Untested);

One thing the derivation found wrong, with the command that settles or reproduces it.

use majordomus_cli::skill::{SkillFinding, SkillFindingLevel};
let f = SkillFinding {
    level: SkillFindingLevel::Fail,
    code: "untested".into(),
    skill: Some("implement".into()),
    subject: ".ai/repo/skills/implement/SKILL.md".into(),
    message: "no test names this skill".into(),
    reproduce: "majordomus skills explain implement".into(),
};
assert!(f.reproduce.contains("explain"));

How bad a finding is: a failure refuses, a warning is reported.

use majordomus_cli::skill::SkillFindingLevel;
assert_ne!(SkillFindingLevel::Fail, SkillFindingLevel::Warn);

One place a skill is invoked from.

use majordomus_cli::skill::SkillInvocation;
let i = SkillInvocation {
    path: ".ai/repo/prompts/review.md".into(),
    line: 3,
    reference: "majordomus://skill/repo-review".into(),
};
assert_eq!(i.line, 3);

Where a skill came from, when it was not written here first: an opaque marker into a ledger kept outside the repository. The committed half names no source; the ledger entry it points at does, locally.

use majordomus_cli::skill::SkillProvenance;
let p = SkillProvenance {
    origin: "prior-art".into(),
    ledger: "import-2026-09-09#1".into(),
    decision: "adapted".into(),
};
assert!(p.ledger.starts_with("import-"));

Where a skill stands, derived from the four facts.

use majordomus_cli::skill::SkillStanding;
assert_eq!(SkillStanding::Orphan.label(), "orphan");

One skill with everything derived about it.

use majordomus_cli::skill::SkillStatus;
// every fact is always present in the answer, so a client never has to tell "absent"
// from "false"; only the provenance is optional
let schema = serde_json::to_value(schemars::schema_for!(SkillStatus)).unwrap();
let required = schema["required"].as_array().unwrap();
for field in ["id", "valid", "tested", "documented", "enforced", "used", "standing"] {
    assert!(required.iter().any(|f| f == field), "{field}");
}
assert!(!required.iter().any(|f| f == "provenance"));

Every skill with its derived standing, and how many stand where: what majordomus skills status, GET /api/v1/skills and the majordomus_skills tool answer.

use majordomus_cli::capability::builtin::skills::SkillStatusList;
let empty = SkillStatusList {
    count: 0,
    standings: std::collections::BTreeMap::new(),
    skills: vec![],
};
assert_eq!(empty.count, 0);

One test that names a skill, and what the ledger says about it.

use majordomus_cli::evidence::ProofState;
use majordomus_cli::skill::SkillTest;
let t = SkillTest {
    path: "test/cases/95_skills.sh".into(),
    test: Some("suite:95_skills".into()),
    state: ProofState::NotRun,
    reproduce: Some("bash test/run.sh 95_skills".into()),
    recorded_at: None,
};
assert_eq!(t.state, ProofState::NotRun);

The tested fact: the tests that name the skill, and their weakest state.

use majordomus_cli::skill::{SkillEvidence, SkillTested};
let t = SkillTested { state: SkillEvidence::Untested, tests: vec![] };
assert!(!t.state.current());

The used fact: every invocation surface that references the skill.

use majordomus_cli::skill::SkillUsed;
let u = SkillUsed { used: false, invocations: vec![] };
assert!(!u.used);

The verdict over every skill: valid when no finding refuses.

use majordomus_cli::capability::builtin::skills::SkillVerification;
let v = SkillVerification { valid: true, skills: 3, failures: 0, warnings: 2, findings: vec![] };
// warnings are debts, reported; they do not make the verdict false
assert!(v.valid);