Architektonický vztah ve zveřejněném dokumentu se kreslí, nikdy nepíše jako ASCII art

Zdůvodnění

Tento repozitář dává pozor na fakta zapsaná dvakrát. Diagram napsaný v ─│┌└┼ a --> je přesně takový případ a péči unikal dlouho, protože nevypadá jako data.

Je to projekce struktury systému, vytvořená ručně, a má všechna selhání ručně vytvořené projekce a jedno vlastní:

• Nic ho nedokáže přečíst. stateDiagram, který stroj umí zparsovat, lze porovnat s přechody, které kód skutečně deklaruje. Obrázek týchž stavů ne, takže se od nich potichu odchyluje, zatímco dál vypadá autoritativně — tvar, který pojmenovává DYNAMICITY.md.
• Nic ho nemůže překreslit. Stejný vztah na webu, v Cockpitu, v terminálu a v odpovědi API potřebuje čtyři vykreslení. Ručně naťukané box-art je jedním z nich, zmrazené, a ostatní tři se bez něj obejdou, nebo ho přepisují — a tak se jedna architektura udržuje ve čtyřech nezávislých obrázcích.
• Nelze zalomit. ASCII-art nemá kde zalomit. Diagram dost široký, aby byl na desktopu užitečný, je na telefonu vodorovný posuvník, a tento repozitář drží své povrchy na 320 px.
• Nelze ji tematizovat ani přečíst nahlas. Design system dodává barvy z tokenů a web se kontroluje na kontrast v obou tématech; obrázek složený ze znaků se neúčastní ani jednoho a čtečka obrazovky dostane stěnu interpunkce.

Mermaid opravuje poslední tři hned a činí první možným: parsovatelná topologie je něco, co může pozdější kontrola porovnat s registrem, který ji vlastní. Proto je cílem mermaid a ne obrázek — SVG by se vykreslilo a přesto zůstalo nečitelné.

Požadované chování

Architektonický vztah v čemkoli, co tento repozitář publikuje, je blok ```mermaid. To zahrnuje životní cykly, stavové automaty, pipeline, grafy závislostí a správy, projekce z deklarace na její povrchy a cokoli dalšího, jehož obsahem je co s čím souvisí.

Publikováno znamená v každé podobě, v jaké se s tím čtenář setkává, nejen v Markdownu. Kanonické stromy jsou:

• docs/**, stránky zapsané přímo do site/content-src/** a šablony, kterými se tyto stránky vykreslují, site/templates/**;
• rozhodnutí, .ai/repo/adrs/**, a pravidla, .ai/repo/rules/**. Obojí se publikuje jako stránky webu a čte se v čítárně příručky, takže kresba zapsaná do jednoho je kresbou na dvou površích;
• handbook/**, kapitoly a stránka, do které se skládají;
• markdown, který majordomus ui vykresluje: zdroje v Rustu pod apps/majordomus-cli/src/ui/**, jejichž dokumentační komentáře publikuje rustdoc a jejichž řetězce kreslí obrazovky, a skripty pod share/ui/**.

site/content/** je projekce docs/ a site/content-src/ a generátor ji přepisuje, takže nalezený problém by tam pojmenoval soubor, který jeho autor nemůže opravit.

A v každém z nich obě formy, ve kterých se blok píše — ```fenced blok a HTML blok <pre>/<code>. Ta druhá není formalita: nejpublikovanější dokument tohoto repozitáře je šablona a v prvních týdnech pravidla v ní seděla ručně nakreslená řídicí smyčka, v HTML, kde ji kontrola čtoucí jen fence neviděla na žádném rozsahu.

Blok HTML deklaruje svůj jazyk tak, jak to dělá HTML, v class nebo data-lang: class="console" je vyňat stejně jako fence ```console, language-bash a data-lang="mermaid" se čtou stejně a <pre> nesoucí jen třídy rozvržení nic nedeklaruje a posuzuje se podle obsahu.

Čtyři věci složené z týchž znaků nejsou diagramy nebo nejsou publikovány a jsou vyňaty deklarací:

• doslovný výstup terminálu — co příkaz skutečně vytiskl. Ohraničit jako console, bash, sh nebo shell-session. Překreslit terminál jako graf by byla lež o tom, co terminál ukázal, a tento repozitář ukazuje skutečný výstup, ne makety;
• výpis souborů — ├── lib/ říká, kde soubory jsou, ne jak spolu souvisejí, a čtenář ho porovnává s vlastním ls. Anotace # … ve stromu jsou text, takže šipka v nich je věta, ne hrana. Výpis drží všechny glyfy v odsazení před jménem položky; executor ──┬── MCP spojuje dvě věci za jménem a blok, který to dělá, je kresba, ať vypadá jeho levý okraj jakkoli jako strom;
• citovaný obsah souboru — blok ukazující, jak vypadá generovaná hlavička, obsahuje <!-- … --> a HTML komentář není šipka;
• kampaňové balíčky — campaigns/** obsahuje balíčky promptů operátora uchované bajt po bajtu jako provenience a zaznamenané v campaigns/MANIFEST.sha256. Nic z toho se nepublikuje ani nenačítá a přepsání zadání by zfalšovalo záznam o tom, co bylo požadováno.

Každý diagram je interaktivní prohlížeč a uzel se pojmenovává tím, čím je. Na webu blok mermaid dosáhne jediného prohlížeče z ADR 0152 (site/diagrams.js) a build (scripts/lib/diagrams.mjs) odkazuje každý uzel, jehož id nebo popisek je identitou objektu, pro který web má stránku: id pravidla, ADR 0152, úkol, schopnost jako executions.get, příkaz jako majordomus doctor, cesta dokumentu. Uzel, který je takovým objektem, tedy nese svou identitu v popisku a je klikatelný, aniž by kdokoli psal href. Příručka kreslí tytéž bloky vlastním Mermaid, v barvách stránky, a znovu při změně motivu; v kapitole příručky je blok <pre class="mermaid-src" data-lang="mermaid">.

Mermaid je renderer, ne druhý zdroj. Kde vztah už existuje jako data — výsledky, které workflow deklaruje, povrchy, na nichž je schopnost zpřístupněna, pravidla, která doktrína dispatchuje — diagram se generuje z těchto dat a nikdy se nepíše vedle. Ručně psaný blok mermaid je pro vysvětlující vztah, který žádný registr nedrží, a i tehdy se píše jednou, v dokumentu, který jej uvádí, a neopakuje se vedle v ASCII pro terminál.

Chování při selhání

scripts/ci/diagram-check, zaregistrovaná jako kontrola diagram-check, selže, když počet ručně kreslených diagramů v publikovaném stromu překročí .ai/repo/diagram-baseline.txt, a vypíše každý se souborem, řádkem a prvním řádkem obsahu. Selže také tehdy, když klesne pod základní hodnotu, aniž by byla základní hodnota snížena — západka nad pravdou je kontrola, která přestala hledat, a jediná cesta dolů je zaznamenat, že jste šli dolů.

Základní hodnota existuje, protože dluh předchází pravidlu. Má dosáhnout nuly; změna, která ji zvýší, je odmítnuta, ne přijata.

Ověření

scripts/ci/diagram-check          # the gate
scripts/ci/diagram-check --list   # every hand-drawn diagram, for converting
bash test/run.sh 272_diagrams_are_drawn 3106_every_published_tree_draws_its_diagrams

test/cases/272_diagrams_are_drawn.sh sestaví bloky, které musí kontrola rozlišit, ve vlastní fixture — architekturu z box artu, blok mermaid, přepis console, strom souborů, strom, jehož anotace obsahuje šipku, a blok citující HTML komentář — takže kontrola se měří tím, o čem rozhoduje, ne tím, co tento repozitář náhodou obsahuje. Každá z těchto otázek se klade znovu na HTML podobu: box art šablony <pre><code> a šipky zakódované jako entity se musí zachytit, a <pre class="console"> s reálným výstupem terminálu, <pre> se stromem souborů, <pre class="mermaid">, class="language-bash", inline <code> ve větě a ohrazený blok ```html citující značkování kresby ne.

test/cases/3106_every_published_tree_draws_its_diagrams.sh zasadí box art do každého stromu, který přidala verze 2 (rozhodnutí, pravidlo, kapitola příručky, doc komentář modulu UI a skript UI) a vyžaduje, aby kontrola pojmenovala každý z nich. Blok mermaid, výpis souborů a campaign pack na týchž místech zůstávají čisté a skutečný strom zůstává na nule.

Historie

Verze 1 pokrývala docs/**, site/content-src/** a site/templates/**. Box art přežil mimo ně, v rozhodnutí (ADR 0033), v příručce a v modulu UI. Uvnitř nich prošla jako výpis souborů kresba, jejímiž jedinými šipkami byly ▼ a ↓. Verze 2 (ADR 0166, rozhodnutí 6) přidává rozhodnutí, pravidla, příručku a markdown, který vykresluje majordomus ui. Čte ▼ ▲ ↓ ↑ ← ◄ ► jako šipky a blok přijme jako výpis jen tehdy, když glyfy zůstávají v odsazení.