Spustitelné případy užití

Případ užití je úloha, kterou někdo provádí s Majordomus, zapsaná jednou jako data a ověřená proti skutečnému nástroji. Není to tutoriál, seznam funkcí ani stránka: je to jeden soubor pod .ai/repo/use-cases/, jehož front matter jmenuje příkazy, pravidla, tvrzení, odpovědnosti a aplikace, kterých se dotýká, a nese scénář, a jehož tělo říká, jaká je situace a co vám zůstane v rukou. Každá jeho projekce je odvozená: stránka, kategorie, v níž leží, odkazy na něj a z něj, součet říkající, které schopnosti mají případ užití, a důkazy, které stránka ukazuje. Pravidla za tím jsou majordomus.catalogue-integrity a majordomus.use-case-coverage ve vendorované baseline a tvrzení jsou use-case-coverage, use-case-evidence a use-case-impact v CLAIMS.yaml.

Princip, řečený jednou: vše, co lze odvodit, se odvozuje; vše, co odvodit nelze, má jeden kanonický domov; vše, co se tvrdí jako zaručené, je podloženo spustitelnými důkazy.

Kde co žije

majordomus init naplní obě sekce jejich kontextovými dokumenty a taxonomií, takže první případ užití repozitáře je jediný soubor.

Objekt případu užití

---
id: prove-a-rule-is-enforced          # the file name, stable, the URL slug
kind: use-case
title: 'Prove a rule is actually enforced, not merely written down'
summary: 'One sentence.'
category: policy                       # an id of taxonomy.yaml
status: active                         # active | draft | deprecated (authored)
target: guaranteed                     # guaranteed | advisory: what the author aims at
actors: [maintainer, reviewer]
difficulty: intermediate
commands: [doctrine, doctor]           # bin/majordomus must dispatch each
mcp_tools: [majordomus_repository]     # optional; the executable's registry must project each
doctrines: [majordomus.enforcement-wiring]   # rules with an x-majordomus block
claims: [dispatcher-wiring]            # ids in docs/CLAIMS.yaml
responsibilities: [doctor]             # ids in docs/RESPONSIBILITIES.yaml
applications: [ci-gated-project]       # each names this use case back
---

# Situation
...

# Scenario

```yaml
setup: installed                       # test/fixtures/commands/setup/installed.sh
given:
  - 'Majordomus installed; no git hook invokes the tool yet'
steps:
  - id: find-the-gap
    run: ['doctor']
    note: 'the enforcement the policy declares reaches no hook'
    expect:
      exit: 10
      stdout_contains: ['^FAIL wiring', 'doctor-on-commit']
then:
  - 'a declared enforcement that nothing invokes is a failure, not a green line'
```

# Outcome
...

Co objekt nenese, protože se odvozuje: popis nebo syntaxi příkazu, text pravidla, znění tvrzení, shrnutí aplikace, zachycený výstup, související případy užití, titulek nebo počet kategorie a pozorovanou vyspělost. Schéma odmítne klíč, který nedeklaruje, a majordomus usecase validate odmítne odkaz, který se nevyřeší, kategorii, kterou taxonomie nemá, setup skript nebo tělo stdin, které neexistují, krok scénáře, který spouští příkaz, jejž případ užití neuvádí, tělo bez # Situation, # Scenario a # Outcome, id, které není názvem souboru, duplicitní id a aktivní případ užití, který míří na guaranteed bez scénáře.

Given, when, then

Scénář je spustitelná podoba vyprávění a je sekcí těla, ne polem hlavičky: front matter říká, čím objekt je — jeho identitu a klasifikaci — a dvacetiřádkový program není ani jedno. # Scenario drží přesně jeden ohraničený blok yaml, mezi # Situation a # Outcome, aby čtenář potkal situaci, důkaz a výsledek v pořadí, v jakém se dějí.

setup jmenuje připravený stav (shellový skript pod fixtures, sdílený s ukázkami příkazů, takže to, z čeho případ užití začíná, je to, co ukazuje stránka příkazu); given to říká slovy. Každý krok je jedno skutečné volání bin/majordomus, v jednorázovém repozitáři, popořadě, ve stejném repozitáři: run je argv, nikdy shellový řetězec; stdin jmenuje soubor s tělem; expect nese návratový kód a volitelně stdout_contains, stdout_not_contains, files_exist a files_contain (rozšířené regulární výrazy nad sloučeným výstupem nebo souborem). then říká slovy, co asercemi prokázáno.

Scénář fixture může také ukázat změnu, kterou nástroj posuzuje. Krok pracovníka je jeden shellový řádek, spuštěný s sh -c v jednorázovém repozitáři, mezi dvěma voláními:

  - id: the-worker-strays
    worker: 'echo "parser notes" >> docs/d'
    expect:
      exit: 0

Jeho důkazy nesou actor: worker (u každého jiného kroku actor: tool) a samotný řádek jako příkaz, takže stránka může ukázat, kdo co udělal. Existuje proto, aby jeden scénář mohl vyprávět celý příběh — pracovník zabloudí, nástroj odmítne, pracovník to vezme zpět, nástroj přijme — místo aby každý stav byl samostatný přípravný skript. usecase validate odmítne krok pracovníka v živém scénáři, který nesmí měnit repozitář, na který se ptá, a vedle run nebo obligation, protože krok je právě jedno ze tří. Výzva na webu je takový scénář: site/data/challenge.toml jej jmenuje a site/data/generated/challenge.json je jeho zaznamenaný běh.

Kde scénář běží

mode říká, o kterém repozitáři scénář je. Je to fixture, pokud se nezapíše jinak, a to je celý odstavec výše: skript přípravy, jednorázový repozitář, commitnuté důkazy, reprodukované CI.

mode: live je ten druhý. Živý scénář klade své otázky repozitáři, v němž byl příkaz vyvolán. Nepojmenovává žádnou přípravu, protože nic nepřipravuje, a smí spouštět jen vektory argumentů, které share/commands.yaml deklaruje jako jen pro čtení — class příkazu, zpřesněné effects, které registr deklaruje pro každý podpříkaz a příznak, takže knowledge edges je připuštěno a check --checkpoint ne. usecase validate zamítne cokoli jiného, takže živý scénář nemůže změnit to, na co se ptá, ať je napsán jakkoli. Mutace zůstává start, check a finish, které na ni dohlížejí.

Živý scénář může nést i krok, který nic nespouští:

  - id: the-cases-were-run
    obligation: tests

Krok závazku tvrdí, že jeden token z share/obligations.yaml byl splněn, týmž posouzením, které čte check (mj_obligation_judge v lib/evidence.sh): zjištěn živě tam, kde jej může rozhodnout git nebo publikovaný web, a čten z ledgeru tam, kde ne. Rozliší se na pass, unmet — dlužné a nesplněné — nebo stale, což znamená, že důkaz existuje a už nepopisuje tento strom. Kroky závazků jsou platné jen v režimu live; jednorázový repozitář nedluží nic.

To umožňuje třídě práce uvést, co dluží. check posuzuje povinnosti, které jedna úloha deklarovala na start; úloha, která nedeklarovala žádné, se to dozví, pravdivě a bezúčelně. Živý scénář říká, co dluží oprava vady nebo dokončená změna, ať už někdo nezapomněl slíbit cokoli, a protože oba čtou jedno posouzení, nemohou se kontrola a vlastní kontrakt úlohy rozejít o témže stromu.

Verdikt živého scénáře je unmet, ne fail. Selhávající scénář fixture je vada nástroje; živý scénář s nevyřízeným závazkem je nedokončená práce a není to tatáž zpráva. usecase run skončí kódem 10 pro obojí — kontrakt nesplněn — a počítá a vypisuje je zvlášť.

majordomus usecase run                 # the fixtures, and only the fixtures
majordomus usecase run --live          # the live scenarios as well
majordomus usecase run know-whether-this-work-is-finished   # by name, whatever its mode

Živé důkazy se ukládají pod .ai/local/evidence/live/ a nikdy se necommitují: popisují jeden strom, na jednom stroji, v jedné minutě, a odvozený soubor, jehož obsah závisí na tom, kdo ho odvodil, je přesně to, co ADR 5 zakazuje. Ze stejného důvodu usecase coverage počítá živý scénář jako pojmenování příkazu, nikdy jako jeho pokrytí: záruka, kterou CI nemůže znovu spustit, není záruka. Rozhodnutí je ADR 38.

Spuštění a důkazy

majordomus usecase run                     # every fixture scenario; exit 10 when a step fails
majordomus usecase run prove-a-rule-is-enforced --keep   # keep the repository for a look
majordomus usecase show prove-a-rule-is-enforced         # the file, and its last evidence

Každý běh zapisuje .ai/local/evidence/use-cases/<id>.json: případ užití, přípravu, výsledek a u každého kroku příkaz, argv, stdin, návratový kód, očekávaný návratový kód, normalizovaný výstup, každé tvrzení s jeho výsledkem a časování. Normalizovaný znamená, že cesta repozitáře scénáře, vlastní cesta nástroje, domovský adresář, časová razítka, id úloh a relací, hashe záznamů a trvání jsou nahrazeny zástupnými symboly; nic behaviorálního ne. Dva běhy jednoho scénáře na jednom nástroji jsou bajt po bajtu totožné, což umožňuje webu vložit důkazy a --check je znovu dokázat.

Důkazy jsou lokální stav. Generátor webu je nečte: každý scénář spouští sám, stejným příkazem, a výsledek vkládá do site/data/generated/catalogue.json. Stránka, která ukazuje, co příkaz vytiskl, ukazuje právě to; vložený přepis tam nemá kam jít.

Zralost se pozoruje

status se píše (active, draft, deprecated) a target se píše (guaranteed, advisory). Čím případ užití je, se počítá při generování dat webu, z důkazů a z toho, co uvádí:

Nikdo nezapisuje guaranteed do případu užití. Koncept lze spustit (usecase run jej přijímá) a validovat a nepočítá se za nic.

Pokrytí

majordomus usecase coverage [--json] [--check]

Cílem je každý veřejný příkaz registru příkazů, každé zaručené tvrzení s odpovědností a každý nástroj MCP, který spustitelný soubor promítá. U každého se počítají aktivní případy užití, které jej jmenují, ty, jejichž scénář jej spouští, a ty s prošlými důkazy; stav je covered, partial (jmenován, nikdy nespuštěn) nebo gap. Politika říká, co mezera znamená, podle třídy:

use_cases:
  coverage:
    commands: required     # a gap fails doctor, check, finish and --check
    claims: advisory       # a gap is reported
    mcp_tools: advisory

Kostrová politika dělá každou třídu poradní: čerstvý repozitář nemá žádné případy užití a je o tom informován, ne shozen. Tento repozitář vyžaduje každý veřejný příkaz. Doktrína majordomus.use-case-coverage provádí stejné sčítání pod doctor, check a přes klíč dokončení use_cases_covered v verification.finish_requires pod finish: vyžadovaná mezera odmítne dokončení, jmenuje schopnost a příkaz scaffoldu.

Dopad

majordomus usecase impact [--base <ref>] [--json]

Ze souborů změněných od --base (výchozí je upstream) plus pracovního stromu příkaz jmenuje, co je dotčeno: příkazy (lib/<command>.sh, soubory odpovědnosti nebo vše, když se změnilo bin/majordomus, lib/common.sh, registr, manifest nebo politika), pravidla (podle id front matter), případy užití (jejich vlastní soubor, jejich skript přípravy, jejich tělo stdin, příkaz nebo doktrína, které jmenují, tvrzení, když se změnilo docs/CLAIMS.yaml, nástroj MCP, když se změnil crate), mezi nimi scénáře a behaviorální případy, které deklarují pokrytí dotčeného příkazu nebo které pravidlo jmenuje jako své testy. Poslední řádek je příkaz, který spustit dál.

Lešení

majordomus usecase scaffold --missing              # one draft per required gap
majordomus usecase scaffold --for command:pack     # one draft
majordomus usecase scaffold --missing --dry-run

Návrh se zapíše do .ai/repo/use-cases/<command>-draft.md s tím, co je už známo: příkaz, kategorie podle fáze životního cyklu příkazu, odpovědnost, jejímž příkazem je, zaručená tvrzení této odpovědnosti a scénář převzatý z vlastní fixture příkazu (nastavení jeho prvního scénáře, argv a očekávaný exit). Všechno ostatní je TODO, status je draft a target je advisory. Návrh se validuje a spouští; nepokrývá nic, dokud člověk nebo agent nedokončí vyprávění, nezpřísní asserce a nenastaví status: active. Nic z toho nepotřebuje model a nic, co model napíše, není důkaz.

Co web ukazuje

Generátor vkládá pro každý případ užití: front matter, tělo, pozorovanou zralost, důkazy jeho scénáře (příkaz a normalizovaný výstup každého kroku), rozlišené příkazy, pravidla, tvrzení, odpovědnosti a aplikace a související případy užití spočítané z toho, co sdílejí (stejný workflow příkazů, sdílená tvrzení, sdílená pravidla, sdílené příkazy, stejná kategorie, sdílené aplikace, v tomto pořadí vah; případ užití smí boost nebo suppress id pod related). Kategorie pocházejí z taxonomie a nesou své počty. /use-cases/ vypisuje podle kategorie; /use-cases/<id>/ je stránka; scripts/site-check odmítne stránku, jejíž důkazy, odkazy nebo kategorie se nerozliší. Nic na stránce nebylo zapsáno do šablony ručně.

Kontroly na jednom místě

Jak ji rozšířit

Přidejte soubor. Pojmenujte, čeho se dotýká. Dejte mu scénář. Spusťte majordomus usecase validate, majordomus usecase run <id>, scripts/generate-site-data a commitněte s ním znovu vygenerovaná data. Není žádný registr k úpravě, žádný index k aktualizaci, žádná šablona k dotčení, žádné počitadlo k navýšení a související odkazy každé další stránky se přepočítají samy.