Případy užití jsou spustitelné kanonické objekty vrstvy

8. Případy užití jsou spustitelné kanonické objekty vrstvy

Rozšiřuje ADR 2 (jeden kanonický registr) na katalog.

Kontext

Katalog případů užití webu tvořilo šest položek v share/use-cases.yaml: próza o tom, co člověk s nástrojem dělá, každá jmenující příkazy, pravidla a tvrzení, na nichž stojí, kontrolovaná na visící odkazy a vykreslená do stránky. Odkazy se kontrolovaly; chování ne. Krok mohl být ve špatném pořadí, očekávání mohlo být nepravdivé a stránka by to s jistotou tvrdila, protože to nic neprovedlo. Soubor žil v distribuci nástroje, takže repozitář nemohl napsat vlastní případy užití bez úpravy nástroje. Operátor požádal, aby se katalog stal integrační páteří: každá navenek významná schopnost předvedená případem užití, který běží, každý příklad na stránce generovaný z provedení, kategorie, pokrytí, analýza dopadu, scaffolding a celé to tak, aby se na to nedalo při běžném vývoji zapomenout.

Invariant, který tento repozitář už drží pro tvrzení (docs/CLAIMS.yaml: záruka jmenuje test, který ji dokazuje), pro příkazy (share/commands.yaml: veřejný příkaz potřebuje fixturu se scénáři, stránku, případ chování a negativní případ) a pro registr v Rustu (schopnost bez případu měření výkonu se nezkompiluje), je ten, který je třeba rozšířit, ne nový.

Rozhodnutí

• Případ užití je soubor vrstvy: .ai/repo/use-cases/<id>.md, Markdown s front matter pod share/schemas/use-case.schema.json, objevený přes sekci use-cases manifestu a sources.yaml jako každý jiný objekt, servírovaný spustitelným souborem v Rustu jako majordomus://use-case/<id>. Aplikace stejně pod .ai/repo/applications/; kategorie v taxonomy.yaml vedle případů užití, jen metadata prezentace. share/use-cases.yaml a share/applications.yaml jsou pryč; spravovaný repozitář píše vlastní.
• Scénář je důkaz. Případ užití nese připravený stav (setup skript z fixtures, které už příkazové ukázky používají), příkazy, které spouští, s jejich argv, očekávané návratové kódy a výstup a to, co to dokazuje, slovy. majordomus usecase run ho provede proti bin/majordomus v jednorázovém repozitáři a zapíše normalizované důkazy pod .ai/local/evidence/. Generátor webu spouští každý scénář sám a vkládá důkazy, takže stránka ukazuje, co nástroj udělal, a generate-site-data --check to dokáže znovu; vložený přepis nemá kam jít.
• Zralost se pozoruje. status (active, draft, deprecated) a target (guaranteed, advisory) se píší ručně; co případ užití je (draft, described, executable, verified, guaranteed) se počítá z důkazů a objektů, které jmenuje, při generování dat webu. guaranteed nikdo nepíše.
• Pokrytí je doktrína. majordomus.use-case-coverage počítá každý veřejný příkaz, zaručené tvrzení a nástroj MCP proti aktivním případům užití, které je jmenují a spouštějí; use_cases.coverage politiky říká po třídách, zda mezera shodí doctor, check a finish (required), je hlášena (advisory), nebo se na ni nehledí. Kostra činí vše poradním; tento repozitář vyžaduje každý veřejný příkaz.
• Dopad a lešení jsou příkazy, ne paměť. majordomus usecase impact mapuje změněné soubory na příkazy, pravidla, případy užití, scénáře a případy, kterých se dotýkají; majordomus usecase scaffold napíše koncept pro mezeru z toho, co už registr, fixture a tvrzení vědí, a koncept se nikdy nepočítá.
• Web je projekce. Stránky, stránky kategorií, stránka pokrytí, související případy užití (deterministické skóre nad sdílenými tvrzeními, pravidly, příkazy, kategorií a aplikacemi) i každý počet pocházejí z catalogue.json; site-check odmítne stránku, jejíž důkazy neprošly nebo jejíž odkazy se nerozřeší.
• Jeden příkaz v shell nástroji. usecase je veřejný příkaz registru s vlastní fixture, sekcí docs/CLI.md a případem, protože scénáře spouští shell nástroj a generátor webu je shell; spustitelný soubor v Rustu objekty čte a servíruje a druhý runner nezískává.

Odmítnuté alternativy

• Ponechat katalog v share/ s polem group. Levné a ponechalo by to vlastní případy užití nástroje v distribuci, kam žádný jiný repozitář žádný nepřidá, a stránky by zůstaly prózou. Dodáno jako provizorium na jeden den a nahrazeno.
• Samostatný runner a formát důkazů v Rustu. Scénáře spouštějí shellový nástroj; runner v Rustu by ho stejně spustil a generátor webu, který důkazy konzumuje, je shell. Jeden runner, v nástroji, který scénáře cvičí.
• Commitnout důkazy jako sledovaný artefakt. Byl by to odvozený stav pod správou verzí, zastaralý při každém commitu, který změnil zprávu; vložit ho do vygenerovaných dat webu, jejichž čerstvost se už kontroluje, dává stejnou viditelnost bez druhé věci, kterou je třeba udržovat v souladu.
• Vyžadovat případ užití na každé zaručené tvrzení od prvního dne. Devadesát tvrzení, devět případů užití; kontrola by byla červená a ignorovaná. Politika činí tvrzení a nástroje MCP poradními, dokud je katalog nedosáhne, a pro příkazy je teď povinná.

Důsledky

• Přidání příkazu vytvoří jeho mezeru v pokrytí ve chvíli, kdy ho registr pojmenuje, a finish odmítne dokončení, dokud ho nespustí aktivní případ užití.
• Přidání případu užití je jeden soubor; stránka, kategorie, počty, související odkazy každé další stránky i tabulka pokrytí vzniknou z regenerace.
• Generátor webu provádí scénáře; generování trvá o minutu déle a je poctivé. Běhy jsou paralelní (MJ_UC_JOBS); cache klíčovaná vstupy je další krok, pokud to poroste.
• Vendorovaný balík pravidel získal majordomus.use-case-coverage; repozitář, který ho aktualizuje, dostane doktrínu s poradní politikou kostry.
• Důkazy se normalizují (cesty, časová razítka, id, hashe, doby trvání, řádek rozpočtu); chování, které se liší podle stroje, se neskrývá a kontrolu shodí, což je smyslem.