Rozhodnutí uvádí, co uvedlo v platnost, jako typované odkazy, z nichž každý je validován, a opačný směr — čím bylo pravidlo, dokument, implementace či případ rozhodnuto — se čte z grafu znalostí, místo aby se zapisoval podruhé

Co to znamená

Rozhodnutí, které změnilo repozitář, je užitečné, jen když se čtenář může dostat od něj k tomu, co změnilo, a zpět. Záznam uvádí směr dopředu jednou, v related:

related:
  - rule:majordomus.context-integrity
  - claim:context-coverage
  - file:lib/context_docs.sh
  - test:test/cases/69_context_documents.sh

Opak — které rozhodnutí uvedlo toto pravidlo v platnost, které rozhodnutí tento případ dokazuje — není napsán nikde. Je to týž graf čtený pozpátku. Dvě ručně udržované hrany jsou jedna hrana a jedna věc k zapomenutí; nástroj drží dvojici poctivou tím, že druhou odvozuje.

Princip

related je seznam typovaných referencí a typ říká, kde cíl žije: rule:<id> v efektivní sadě pravidel, claim:<id> v docs/CLAIMS.yaml, file:<path> a test:<path> v repozitáři. majordomus adr check a doktrína adr odmítnou pravidlo, které sada nemá, tvrzení, které matice nemá, a cestu, která neexistuje, a jmenují záznam i referenci.

Extraktor mění každý odkaz na hranu grafu znalostí, přičemž klíč front matter, který jej uvedl, slouží jako provenience: pravidlo je declares, tvrzení je supports, případ je tested_by, soubor je references. Jsou to vlastní názvy relací grafu, ne druhý slovník vymyšlený pro rozhodnutí. Hrana, jejíž cíl neodpovídá žádný uzel, je nález, takže přejmenování, které rozbije odkaz, se nahlásí, místo aby se tiše zahodilo.

related je to, co rozhodnutí uvedlo v platnost. Odkud pochází, je provenance.derived_from — jiná otázka s vlastním slovníkem odkazů, a obojí se nesloučí.

Jak to vidět

majordomus adr show adr-0011                        # the record, with what it names
majordomus adr check                                # every reference resolves
majordomus knowledge edges --type declares          # decisions to the rules they put in force
majordomus knowledge edges | grep adr:adr-0011      # one decision's edges, with provenance

Co nepokrývá

Nic neověřuje, že rozhodnutí jmenuje všechno, čeho se dotýká: odkaz je tvrzení, které učinil člověk, a jeho absence není nález. Rozhodnutí lze také zaznamenat dříve, než jej cokoli implementuje, což je běžný případ návrhu, takže prázdné related je platné. Nástroj zaručuje, že to, co záznam jmenuje, existuje, a že opačný směr nikdy nesouhlasí s dopředným — protože existuje jen jeden.

Proč existuje

Repozitář měl rozhodnutí a měl pravidla, tvrzení, kód a případy a jediným spojením mezi nimi byla próza. Sledovat ji znamenalo grepovat. Dohledatelnost, která žije v paměti čtenáře, je dohledatelnost, kterou nikdo neauditoval, a první přejmenování ji tiše rozbije.