HTTP API: gates

use majordomus_cli::gates::Completion;

// the document every surface reads, as `gates.completion` answers with it. The property
// that matters is the one asserted here: a gate that never reported leaves the task
// finishable and *unverified*, which is a different thing from a task that passed.
let c: Completion = serde_json::from_value(serde_json::json!({
    "present": true,
    "model": ".ai/repo/ci/gates.yaml",
    "plan": { "mode": "affected", "reason": "1 path in 1 class", "changed": ["docs/CLI.md"],
              "classes": [], "unclassified": [], "selected": {}, "excluded": {} },
    "finishable": true,
    "unverified": ["reference-check"],
    "tallies": { "queued": 1 },
    "gates": [],
    "obligations": [],
    "questions": []
}))
.unwrap();
assert!(c.finishable, "absence of a verdict does not refuse");
assert_eq!(c.unverified, ["reference-check"], "and it is never silently accepted");
assert!(c.blocking.is_empty());

Zda smí být aktivní úloha označena za hotovou, a vše, na čem odpověď stojí.

finishable je pole, podle kterého volající jedná, a jediná věc, kterou žádný povrch nesmí přepočítávat: čtou ho check a finish shellového nástroje, servíruje ho HTTP API, vykresluje ho Cockpit a všechny čtou tento jeden execution.

use majordomus_cli::gates::{DoneQuestion, GateStatus};

let q = DoneQuestion {
    id: "pushed".into(),
    question: "Has the commit reached the remote?".into(),
    status: GateStatus::Queued,
    evidence: "the obligation is owed".into(),
    source: "obligation push (obligations.closure)".into(),
    remediation: "git push".into(),
};
// every question names what answered it and what would settle it: a question with
// neither is a checklist line, which is the artifact this type exists instead of
assert!(!q.source.is_empty() && !q.remediation.is_empty());
assert!(q.status.unverified());

Jedna otázka invariantu hotovo a co na ni odpovědělo.

use majordomus_cli::gates::{Gate, GateStatus};

let gate = Gate {
    id: "rust-check".into(),
    title: "the crate builds, is formatted and passes its tests".into(),
    scope: "apps/majordomus-cli".into(),
    required: true,
    status: GateStatus::Queued,
    reason: "the plan selects it and no run has ever reported".into(),
    remediation: "majordomus evidence --gate rust-check --exit 0".into(),
    source: "the plan".into(),
    evidence: None,
    inputs: vec!["apps/majordomus-cli/**".into()],
    inputs_hash: "3f0a".into(),
    evaluated_at: "2026-01-01T00:00:00Z".into(),
};
// silence does not refuse and is not a pass either: it is a debt, reported as one
assert!(!gate.status.refuses());
assert!(gate.status.unverified());
assert!(gate.evidence.is_none());

Jedna kontrola dokončení: co je zač, zda se uplatní, co řekla a co dělat.

use majordomus_cli::gates::GateClass;

// one path class as the CI model declares it: which paths select which gates
let class: GateClass = serde_json::from_value(serde_json::json!({
    "id": "docs",
    "paths": ["docs/**"],
    "gates": ["reference-check"]
}))
.unwrap();
assert_eq!(class.id, "docs");
assert_eq!(class.paths, ["docs/**"]);

Jedna třída cest: cesty, které pokrývá, a kontroly, které změna v nich vybere.

use majordomus_cli::gates::GateClassMatch;

let hit = GateClassMatch { id: "docs".into(), paths: vec!["docs/CLI.md".into()] };
// the class, and the files of the change that put it in the plan — never the class alone,
// because a plan a reader cannot check is a plan a reader has to believe
assert_eq!(hit.paths.len(), 1);

Jedna třída, do které změna spadla, a cesty, které ji tam zařadily.

Co třída vybírá: slovo full, nebo kontroly, které jmenuje.

use majordomus_cli::capability::builtin::gates::GateModelEntry;
use majordomus_cli::gates::GateDecl;

let decl: GateDecl = serde_json::from_value(serde_json::json!({
    "id": "site-check",
    "job": "site",
    "runs": "scripts/site-check",
    "summary": "the site is whole"
}))
.unwrap();
let entry = GateModelEntry { declared: decl, inputs: vec!["site/**".into()] };
// the declaration as the file carries it, plus the paths its evidence is taken over —
// derived from the classes that select it, never written down a second time
assert_eq!(entry.declared.id, "site-check");
assert_eq!(entry.inputs, ["site/**"]);

Jedna kontrola modelu s tím, co o ní model implikuje.

Model CI, který tento repozitář deklaruje: co smí změnu odmítnout a co každou kontrolu vybírá.

Dvě věci o této zprávě je dobré vědět, než se přečte. count se měří z gates, ne zapisuje, takže se obojí nikdy nemůže rozejít tak, jak se rozchází ručně udržovaný součet. A unreadable je způsob, jak čtenář pozná „tento repozitář nedeklaruje žádný model CI“ od „volání selhalo“: repozitář vrstvy není povinen deklarovat kontroly, takže prázdný model je odpověď a říká, proč je prázdný.

use majordomus_cli::capability::builtin::gates::GateModelReport;
use serde_json::json;

// the shape every surface serves: `unreadable` is skipped when the model was read
let r: GateModelReport = serde_json::from_value(json!({
    "version": 1,
    "source": ".ai/repo/ci/gates.yaml",
    "count": 0,
    "on_demand": [],
    "gates": [],
    "classes": [],
})).unwrap();
assert_eq!(r.count, r.gates.len(), "the total is measured, never declared");
assert!(r.unreadable.is_none(), "read, and it declares nothing");

// and the other empty answer, which a reader must not confuse with that one
let absent: GateModelReport = serde_json::from_value(json!({
    "version": 0,
    "source": ".ai/repo/ci/gates.yaml",
    "count": 0,
    "on_demand": [],
    "gates": [],
    "classes": [],
    "unreadable": "no such file",
})).unwrap();
assert_eq!(absent.unreadable.as_deref(), Some("no such file"));

use majordomus_cli::gates::{GateClassMatch, GatePlan, GatePlanMode};
use std::collections::BTreeMap;

let plan = GatePlan {
    mode: GatePlanMode::Affected,
    reason: "3 path(s) fall in 1 class".into(),
    changed: vec!["docs/CLI.md".into()],
    classes: vec![GateClassMatch { id: "docs".into(), paths: vec!["docs/CLI.md".into()] }],
    unclassified: Vec::new(),
    selected: BTreeMap::from([("reference-check".to_string(), "class docs".to_string())]),
    excluded: BTreeMap::new(),
};
// the plan says what it selected and why, so a reader can check it rather than believe it
assert_eq!(plan.selected["reference-check"], "class docs");
assert!(!plan.selected.contains_key("rust-check"), "a document change cannot break the crate");

Které kontroly musí změna projít a proč je každá zahrnuta nebo vyloučena.

use majordomus_cli::gates::GatePlanMode;

// a plan is either the gates the change selects, or everything the runners allow
assert_eq!(GatePlanMode::Affected.as_str(), "affected");
assert_eq!(GatePlanMode::Full.as_str(), "full");
assert_ne!(GatePlanMode::Affected, GatePlanMode::Full);

Proč plán vybírá to, co vybírá.

use majordomus_cli::gates::GateRun;

// what `majordomus evidence --gate` writes: a run, and the tree it was taken over
let run = GateRun {
    recorded_at: "2026-01-01T00:00:00Z".into(),
    head: "9b1e2d4".into(),
    branch: "master".into(),
    exit: 0,
    command: "scripts/rust-check --ci".into(),
    inputs_hash: "3f0a".into(),
    session: "s-1".into(),
};
// the hash is what makes a run go stale rather than merely old: the same run read
// against a different tree is evidence about a tree that no longer exists
assert_eq!(run.exit, 0);
assert_ne!(run.inputs_hash, "0000");

Řádek knihy task.gate, který naposledy hlásil kontrolu, tak jak jej kniha drží.

use majordomus_cli::gates::GateStatus;

// the three answers a reader is entitled to, and they are different answers
assert!(GateStatus::Fail.refuses(), "a run that failed refuses");
assert!(GateStatus::Queued.unverified(), "asked and unanswered is a debt");
assert!(!GateStatus::Exempt.refuses() && !GateStatus::Exempt.unverified());

// and the one that is neither: a run whose tree has moved proves nothing about this one
assert!(GateStatus::Stale.refuses());
assert_eq!(GateStatus::Stale.as_str(), "stale");

Co je známo o jedné kontrole. Každé slovo už nesou designové tokeny tohoto repozitáře (share/design/tokens.yaml, status.states), takže ho plocha vykreslí, aniž by se musela učit šestý slovník, a kontrola designu ho neodmítne.

use majordomus_cli::gates::ImpliedObligation;

let owed = ImpliedObligation {
    id: "tests".into(),
    title: "The cases the change obliges were run".into(),
    applicable: true,
    declared: false,
    reason: "lib/check.sh is an input of this obligation".into(),
    because: vec!["lib/check.sh".into()],
    remediation: "majordomus start --requires tests".into(),
};
// applicable and undeclared is the gap nothing else reports: the change owes it and
// the task promised nothing, so no validator holds anybody to it
assert!(owed.applicable && !owed.declared);

Jedna povinnost, kterou sada změn implikuje, a zda ji úloha slíbila.

Použitelnost se odvozuje a nic jiného: vlastní inputs tokenu v share/obligations.yaml jmenují soubory, kterých se týká, takže změna jednoho z nich způsobí, že token je dlužen. Token bez inputs jmenuje fakt mimo strom — push, publikaci, nasazení — který žádná změna stromu nemůže implikovat, takže jsou dlužny, když je úloha deklaruje, a hlášeny jako nepoužitelné, když ne.