Každý adresář vrstvy nese kontextový dokument, výjimku deklaruje kontrakt, který podstrom řídí, a potomek může tento požadavek zúžit, ale nikdy oslabit

Co to znamená

Adresář, který o sobě nic neříká, není neutrální. Nepřispívá nic do řetězce, který worker rozřeší, nepojmenuje žádný formát souborů, které drží, a kdo tam přistane, čte jeho předky a zbytek hádá. Pokrytí mění zvyk psát README.md v invariant: každý adresář stromu vrstvy nese kontextový dokument a adresář, který ho nemá, je nález missing-contract, jenž jmenuje adresář a — kde předek učinil požadavek výslovným — smlouvu, která tak učinila.

Strom je ten, který už řešitel čte: adresář manifestu minus polovina, kterou sám manifest deklaruje jako netrackovanou (local.tracked: false). Nic dalšího se nepřeskakuje podle jména — podstrom, který nedluží kontrakt, to říká v kontraktu nad sebou.

Princip

Výjimka jsou data na kontraktu, který řídí podstrom, nikdy seznam v kořeni, takže se pohybuje se stromem, který popisuje:

scope: subtree
children:
  require_contract: false

Hodnota, která platí pro adresář, je ta z nejbližšího předka, jehož kontrakt ji deklaruje; kde ji nedeklaruje nikdo, dokument se dluží. Pole se skládá jen zužováním: potomek může pro svůj podstrom zvýšit false na true a snížení zděděného true je illegal-override — stejná třída, jakou potomek získá za nahrazení dokumentu final. Říká, co dluží potomci, takže se přijímá jen na dokumentu subtree a jeho hodnotou je true nebo false a nic jiného.

Podstrom vyjměte pomocí require_contract: false, když adresáře pod ním jsou instance druhu, a ne sekce vrstvy: dovednost je SKILL.md a její příklady a kontrakt v každém instančním adresáři by opakoval, jednou na instanci, formát, který sekce uvádí jednou.

Podstrom, který vrstva nese, ale nepíše, se uvolní jménem:

scope: subtree
children:
  require_contract: true
  exempt: [.ai/repo/rules/vendor]

Vše na jmenovaném adresáři a pod ním nic nedluží. Záznam musí ležet uvnitř rozsahu dokumentu, který jej zapisuje, a nesmí být vlastním adresářem tohoto dokumentu: kontrakt uvolňuje adresáře, které řídí, a žádné jiné, takže zužující pravidlo nelze obejít vynětím podstromu z boku. Převzatý balíček pravidel je takto vyňat — je nainstalován, ne zde napsán, a jeho integrita je věcí jeho vlastního manifestu — zatímco každý adresář, který tento repozitář zapisuje, stále kontrakt dluží.

Jak to vidět

majordomus context validate                 # the whole tree; missing-contract names the directory
majordomus context explain .ai/repo/rules   # the chain that applies, and why each document is in
majordomus doctor                           # the same check through majordomus.context-integrity

test/cases/69_context_documents.sh to dokazuje mutací: adresář bez dokumentu selže, po přidání jednoho projde, adresář pod ním selže zase, výjimka řídicí smlouvy dosáhne celého podstromu, potomek ji zúží zpět na true, potomek, který se pokusí snížit zděděné true, je odmítnut jménem a klíč na dokumentu s rozsahem directory nebo s hodnotou, která není boolean, je invalid-front-matter. Případ užití document-every-directory-of-the-layer provádí odmítnutí od začátku do konce.

Co nepokrývá

Nic zde nesoudí, zda je smlouva dobrá. Nástroj kontroluje, že dokument existuje, parsuje se a potomek ho neoslabuje; zda jeho text skutečně říká workerovi, co do adresáře patří, posoudí recenzent. Pokrytí také končí u vrstvy: docs/ a zdrojový strom popisují dokumenty, které tracks, ne smlouva v každém adresáři.

Proč existuje

Osmnáct adresářů pod .ai/ zapadlo do ticha, zatímco strom, který je držel, se čistě validoval, protože nástroj kontroloval jen dokumenty, které existovaly. Povinnost, kterou nikdo nevynucuje, je zvyk, a zvyk je to první, o co repozitář přichází. .ai/repo/adrs/0011-every-directory-in-the-layer-carries-a-contract.md zaznamenává rozhodnutí a to, co odmítlo.