HTTP API: intents

Why a binding was refused, as a word a reader greps for. The first seven are the preflight's own causes, carried through unchanged; the rest are what only a binding can find.

use majordomus_cli::intent::IntentPreflightCause;
use majordomus_cli::intent_binding::BindingCause;
// a preflight cause keeps its word
assert_eq!(
    serde_json::to_string(&BindingCause::from(IntentPreflightCause::IntentNotCritiqued)).unwrap(),
    serde_json::to_string(&IntentPreflightCause::IntentNotCritiqued).unwrap(),
);

The exemption a binding accepted: the class as the policy declares it, and the reason the worker gave.

use majordomus_cli::intent_binding::BindingExemption;
let e = BindingExemption {
    class: "emergency".into(),
    description: "Restoring a broken trunk".into(),
    because: "master is red on case 500".into(),
};
assert_eq!(e.class, "emergency");

One reason a binding was refused.

use majordomus_cli::intent_binding::{BindingCause, BindingRefusal};
let r = BindingRefusal::new(None, BindingCause::NothingNamed, "name the work".into());
assert!(r.issue.is_none());
assert_eq!(r.cause, BindingCause::NothingNamed);

What a worker named when it asked what its work serves. Every field is optional and the combinations are judged, not assumed: an issue alone, an intent alone, an issue beside the intent it should serve, paths alone, or an exemption with its reason.

use majordomus_cli::intent_binding::BindingRequest;
let by_issue = BindingRequest { issue: Some("I0001".into()), ..Default::default() };
assert!(!by_issue.names_nothing());
// blanks are what a query string or a shell variable leaves behind, and name nothing
let blank = BindingRequest { issue: Some("  ".into()), ..Default::default() }.trimmed();
assert!(blank.names_nothing());

Where a piece of work stands against the intents: the one word a start decides on.

use majordomus_cli::intent_binding::BindingStanding;
assert_eq!(serde_json::to_string(&BindingStanding::Bound).unwrap(), "\"bound\"");
assert!(BindingStanding::Refused.refuses());
assert!(!BindingStanding::Maintenance.refuses());

The state of one criterion as the gap observed it. Four values, because "not determined" has to be writable: an omitted criterion is refused, and Unknown is never a pass.

use majordomus_cli::intent_review::ConditionState;
assert_eq!(serde_json::to_string(&ConditionState::Conflicting).unwrap(), "\"conflicting\"");
assert_ne!(ConditionState::Unknown, ConditionState::Satisfied);

The class of a critique finding: the question the adversarial pass asked. Closed, so that a review's findings can be counted by question rather than read as prose.

use majordomus_cli::intent_review::CritiqueClass;
assert_eq!(
    serde_json::to_string(&CritiqueClass::DeliveryVerification).unwrap(),
    "\"delivery_verification\""
);

One critique finding: what the review found, what it is about, whether it blocks execution, and how it was resolved. class and resolution are None when the record spells one this module does not know, and the _text fields keep what was written.

use majordomus_cli::intent_review::{CritiqueFinding, CritiqueRecord, ResolutionState};
let c = CritiqueRecord::from_metadata("c.yaml", &serde_json::json!({
    "intent": "x",
    "findings": [{"id": "f1", "class": "regression_risk", "subject": "x#a",
                  "blocking": true, "resolution": {"state": "planned", "issue": "I1"}}],
}));
let finding: &CritiqueFinding = &c.findings[0];
assert!(finding.blocking);
assert_eq!(finding.resolution, Some(ResolutionState::Planned));
assert_eq!(finding.issue, "I1");

One criterion's state against the observations, as the record spells it. state is None when the file names a state this module does not know, and state_text keeps what was written so the finding can quote it.

use majordomus_cli::intent_review::{ConditionState, GapCondition};
let c = GapCondition {
    criterion: "criteria-are-covered".into(),
    state: Some(ConditionState::Missing),
    state_text: "missing".into(),
    because: "nothing relates a criterion to an issue".into(),
    observations: vec!["no-serves-field".into()],
};
assert_eq!(c.state, Some(ConditionState::Missing));
assert!(!c.observations.is_empty());

What a piece of work is bound to: its standing, what was named, the issues and intents it resolved to with what each intent asks of the worker, the two pins, and every refusal.

use majordomus_cli::intent::Intents;
use majordomus_cli::intent_binding::{
    bind, BindingCause, BindingRequest, BindingStanding, IntentBinding,
};
use majordomus_cli::plan::Plan;
use majordomus_cli::policy::IntentPolicy;
#### let plan: Plan = serde_json::from_value(serde_json::json!({
####     "project": {"name": "p", "repository": "o/p", "default_branch": "master",
####                 "active_milestone": ""},
####     "statuses": {"issue": [], "milestone": []},
####     "milestones": [], "issues": [], "waves": [], "edges": [],
####     "milestone_edges": [], "findings": []})).unwrap();
let intents = Intents { intents: vec![], findings: vec![] };
let nothing: IntentBinding =
    bind(&intents, &plan, &[], &[], &IntentPolicy::default(), BindingRequest::default());
assert_eq!(nothing.standing, BindingStanding::Refused);
assert_eq!(nothing.refusals[0].cause, BindingCause::NothingNamed);
// nothing was reached, so there is nothing to pin
assert!(nothing.plan_revision.is_empty() && nothing.evidence_standing.is_empty());

The whole derived coverage: every criterion of every live intent, every issue with the reason it exists, and every finding the two produced. Nothing here is stored; it is derived on each read from the intents and the plan.

use majordomus_cli::intent_plan::{IntentCoverage, IssueOrigin, IssuePurpose};
let coverage = IntentCoverage {
    criteria: vec![],
    issues: vec![IssuePurpose {
        issue: "I0007".into(),
        milestone: "ops".into(),
        origin: IssueOrigin::Maintenance,
        serves: vec![],
        intents: vec![],
    }],
    findings: vec![],
};
assert_eq!(coverage.failures(), 0);
assert_eq!(coverage.purpose("I0007").unwrap().origin, IssueOrigin::Maintenance);

Every intent, with its derived stage and verdict, and how many there are in each: what majordomus intent list, GET /api/v1/intents and the majordomus_intents tool all answer with, out of one derivation.

use majordomus_cli::capability::builtin::intents::IntentList;
let empty = IntentList {
    count: 0,
    stages: std::collections::BTreeMap::new(),
    verdicts: std::collections::BTreeMap::new(),
    intents: vec![],
};
// a repository that declares no intent answers the route, with nothing in it
assert_eq!(empty.count, 0);

Which intent a piece of work serves, whether it is maintenance, or why it may not proceed: the issues it resolved to with a verdict each, every intent reached with its link, what those intents require of the worker, and every refusal with its cause.

use majordomus_cli::intent::{
    IntentPreflight, IntentPreflightCause, IntentPreflightRefusal, IntentPreflightVerdict,
};
let refused = IntentPreflight {
    verdict: IntentPreflightVerdict::Refused,
    issues: vec![],
    matches: vec![],
    intents: vec![],
    governance: vec![],
    refusals: vec![IntentPreflightRefusal::new(
        None,
        IntentPreflightCause::NoIssueCoversPaths,
        "no open issue's scope covers README.md".into(),
    )],
    refusal: Some("no open issue's scope covers README.md".into()),
};
assert_eq!(refused.verdict, IntentPreflightVerdict::Refused);
assert_eq!(refused.refusals[0].cause, IntentPreflightCause::NoIssueCoversPaths);

Why a preflight refused, as a word a reader greps for.

use majordomus_cli::intent::IntentPreflightCause;
assert_eq!(
    serde_json::to_string(&IntentPreflightCause::OpenBlockingFinding).unwrap(),
    "\"open_blocking_finding\""
);
assert_ne!(
    IntentPreflightCause::IntentNotCritiqued,
    IntentPreflightCause::IssueServesNothing
);

The critique of an intent as a preflight reads it: where it is, when and by whom the plan was reviewed, and the blocking findings still open.

use majordomus_cli::intent::IntentPreflightCritique;
let c = IntentPreflightCritique {
    source: ".ai/repo/project/critiques/x.yaml".into(),
    reviewed_at: "c3f20da".into(),
    reviewed_by: "another session".into(),
    open_blocking: vec![],
};
assert!(c.open_blocking.is_empty());

The recorded gap of an intent as a preflight reads it, bounded to the criteria the work serves: what was observed of each, at which commit, and the risks.

use majordomus_cli::intent::IntentPreflightGap;
let g = IntentPreflightGap {
    source: ".ai/repo/project/gaps/x.yaml".into(),
    observed_at: "c3f20da".into(),
    conditions: vec![],
    risks: vec!["the schema may refuse old records".into()],
};
assert_eq!(g.risks.len(), 1);

One intent the work is held to, with what a worker needs before touching it: the statement, the criteria the work serves with the live state of their evidence, the invariants and non-goals, the governance, the critique and the gap. Only the intents the work reaches are carried, never every intent.

use majordomus_cli::intent::{IntentPreflightIntent, IntentStage};
let i = IntentPreflightIntent {
    id: "x".into(),
    title: "X".into(),
    stage: IntentStage::Planned,
    statement: "It becomes true.".into(),
    criteria: vec![],
    invariants: vec![],
    non_goals: vec![],
    governance: vec![],
    critique: None,
    gap: None,
};
// no critique recorded is carried as an absence, never as an empty review
assert!(i.critique.is_none());

One issue the work resolved to, and what the preflight concluded about it.

use majordomus_cli::intent::{IntentPreflightIssue, IntentPreflightVerdict};
let i = IntentPreflightIssue {
    issue: "I0007".into(),
    milestone: "ops".into(),
    verdict: IntentPreflightVerdict::Maintenance,
    serves: vec![],
    intents: vec![],
};
// a milestone no intent names carries maintenance, which is not a refusal
assert_eq!(i.verdict, IntentPreflightVerdict::Maintenance);

One intent a piece of work serves, and the link that says so: issue to the criteria it declares in serves, each criterion's intent naming the issue's milestone.

use majordomus_cli::intent::{IntentPreflightMatch, IntentStage};
let m = IntentPreflightMatch {
    intent: "intent-lifecycle".into(),
    title: "Work is traceable to the intent it serves".into(),
    stage: IntentStage::Executing,
    milestone: "intent-lifecycle".into(),
    issue: "I1900".into(),
    criteria: vec!["stage-is-derived".into()],
};
assert_eq!(m.issue, "I1900");

One reason a preflight refused: which issue, the cause, and one sentence of what is wrong.

use majordomus_cli::intent::{IntentPreflightCause, IntentPreflightRefusal};
let r = IntentPreflightRefusal::new(
    Some("I1900"),
    IntentPreflightCause::IntentNotCritiqued,
    "intent x has no critique".into(),
);
assert_eq!(r.cause, IntentPreflightCause::IntentNotCritiqued);
assert_eq!(r.issue.as_deref(), Some("I1900"));

What a preflight concluded, about one issue or about the whole piece of work.

use majordomus_cli::intent::IntentPreflightVerdict;
// the words every surface answers with
assert_eq!(
    serde_json::to_string(&IntentPreflightVerdict::Maintenance).unwrap(),
    "\"maintenance\""
);
assert_ne!(IntentPreflightVerdict::Serves, IntentPreflightVerdict::Refused);

The input of intents.propose: what must become true, and optionally its title and id.

No milestone, criterion or invariant: a proposal says what is wanted, and planning it is a separate act (ADR 0144). No timestamp either: the record is dated when it is written.

use majordomus_cli::capability::builtin::intents::IntentProposeInput;
let i: IntentProposeInput =
    serde_json::from_str(r#"{"statement": "The UI answers within 100 ms warm"}"#).unwrap();
assert_eq!(i.title, None);
// a field the input does not have is refused, never ignored
assert!(serde_json::from_str::<IntentProposeInput>(r#"{"statement": "s", "stage": "x"}"#).is_err());

What the intent model refuses: whether it is valid, how many intents were examined, and every finding with its level. Warnings are reported and do not make it invalid.

use majordomus_cli::capability::builtin::intents::IntentValidation;
let v = IntentValidation {
    valid: true,
    intents: 2,
    failures: 0,
    warnings: 20,
    findings: vec![],
};
// twenty warnings and no failure is a valid model
assert!(v.valid);

Why an issue exists: because it serves a criterion, because it is maintenance under a milestone no intent names, or because nobody said — which is a failure under an intent.

use majordomus_cli::intent_plan::IssueOrigin;
assert_eq!(serde_json::to_string(&IssueOrigin::Maintenance).unwrap(), "\"maintenance\"");
// work under no intent is legitimate and says so; it is never given an invented intent
assert_ne!(IssueOrigin::Maintenance, IssueOrigin::Unexplained);

The answer to "why does this issue exist?": the criteria it declares it serves, the intents whose milestones contain it, and which of the three origins that adds up to.

use majordomus_cli::intent_plan::{IssueOrigin, IssuePurpose};
let purpose = IssuePurpose {
    issue: "I1901".into(),
    milestone: "intent-planning".into(),
    origin: IssueOrigin::Intent,
    serves: vec!["intent-planning#criteria-are-covered".into()],
    intents: vec!["intent-planning".into()],
};
assert_eq!(purpose.origin, IssueOrigin::Intent);
assert_eq!(purpose.serves.len(), 1);

What propose wrote: the identity, the file, and the record as it now reads.

use majordomus_cli::intent::Proposed;
let p: Proposed = serde_json::from_str(
    r#"{"id": "fast-ui", "path": ".ai/repo/project/intents/fast-ui.yaml",
        "title": "Fast UI", "statement": "The UI answers at once"}"#,
)
.unwrap();
// the path is the identity under the intents directory: one answer to where it lives
assert_eq!(p.path, format!(".ai/repo/project/intents/{}.yaml", p.id));

How a critique finding was resolved: not yet, by planning work that serves the intent, or by rejecting it with a reason. A blocking finding left Open refuses execution.

use majordomus_cli::intent_review::ResolutionState;
assert_eq!(serde_json::to_string(&ResolutionState::Planned).unwrap(), "\"planned\"");
assert_ne!(ResolutionState::Open, ResolutionState::Rejected);