Zaznamenat rozhodnutí jako data a dokázat, že ho nástroj nemůže přijmout za vás

setup: adr-related
given:
  - 'Majordomus installed, with one decision proposed and committed'
  - 'discovery is over the tracked tree, so a decision git does not hold is not yet part of the layer'
steps:
  - id: what-was-decided
    run: ['adr', 'list']
    note: 'one line per decision: identity, status, date, title'
    expect:
      exit: 0
      stdout_contains: ['adr-0001', 'proposed']
  - id: the-record-itself
    run: ['adr', 'show', 'adr-0001']
    note: 'the path, then the file as written: the provenance says the tool derived it'
    expect:
      exit: 0
      stdout_contains: ['schema: adr/v1', 'origin: extracted', 'file:docs/d']
  - id: the-set-is-sound
    run: ['adr', 'check']
    note: 'identities, statuses, supersession and every reference, in one pass'
    expect:
      exit: 0
      stdout_contains: ['every identity unique']
  - id: what-it-put-in-force
    run: ['adr', 'show', 'adr-0001']
    note: 'related is the forward edge: the rule the decision declares, the file it reaches'
    expect:
      exit: 0
      stdout_contains: ['related:', 'rule:majordomus.adr-integrity']
  - id: the-graph-reads-it-backwards
    run: ['knowledge', 'edges', '--type', 'declares']
    note: 'the same fact as an edge, with the front-matter key that stated it as provenance; nothing wrote the reverse direction down'
    expect:
      exit: 0
      stdout_contains: ['adr:adr-0001', 'rule:majordomus.adr-integrity', 'related.0']
  - id: what-a-change-reaches
    run: ['adr', 'affected']
    note: 'the same edges read from a change set: which decisions this work touches. A clean tree reaches nothing, and the exit code never says a decision stopped holding'
    expect:
      exit: 0
      stdout_contains: ['no decision names anything this change set touches']
  - id: not-yours-to-choose
    run: ['adr', 'propose', 'A decision that accepts itself', '--status', 'accepted']
    note: 'the refusal that matters: a tool that can write accepted turns its inference into repository truth'
    expect:
      exit: 15
      stdout_contains: ['not yours to choose']
  - id: evidence-must-resolve
    run: ['adr', 'propose', 'A decision derived from a file nobody has', '--from', 'file:docs/nosuch']
    note: 'an extracted record without evidence is an assertion, and is refused as one'
    expect:
      exit: 2
      stdout_contains: ['names a path that does not exist']
then:
  - 'a reference a decision makes is validated where its type says the target lives'
  - 'the reverse direction is the graph read backwards, never a second list'
  - 'a change set names the decisions it reaches; whether they still hold is a person to read, not an exit code'
  - 'a decision is one validated file under .ai/repo/adrs/, discovered as data'
  - 'no invocation of the tool writes status accepted'

Scénář

Provedeno proti skutečnému nástroji v repozitáři připraveném pomocí adr-related, při každém generování tohoto webu. To, co následuje, není popis toho, co by se mělo stát; je to to, co se stalo.

Co nástroj udělal

Důkaz běhu, z něhož byla tato stránka vygenerována: pass, 8 kroků. Výstup je normalizován: cesta repozitáře, časová razítka, id a doby trvání jsou zástupné hodnoty; nic dalšího se neupravuje.

Testováno v test/cases/94_use_cases.sh, který spouští každý scénář a odmítne krok, jehož zaznamenaný výstup není tím, co vyprodukoval.

1. 1$ majordomus adr list exit 0

   jeden řádek na rozhodnutí: identita, stav, datum, název

   adr-0001   proposed    <date>  The registry is the one canonical declaration

   • exit 0
   • stdout_contains /adr-0001/
   • stdout_contains /proposed/
2. 2$ majordomus adr show adr-0001 exit 0

   cesta, pak soubor tak, jak byl zapsán: provenience říká, že jej nástroj odvodil

   .ai/repo/adrs/0001-the-registry-is-the-one-canonical-declaration.md
   
   ---
   schema: adr/v1
   id: adr-0001
   kind: adr
   title: The registry is the one canonical declaration
   status: proposed
   related:
     - rule:majordomus.adr-integrity
     - file:docs/d
   date: <date>
   tags:
     - architecture
   provenance:
     origin: extracted
     derived_from:
       - file:docs/d
   ---
   
   # 1. The registry is the one canonical declaration
   
   ## Context
   
   What forced the decision. Derived from:  file:docs/d.
   
   ## Decision
   
   The registry is the one canonical declaration
   
   ## Alternatives rejected
   
   What else was considered, and why it was not taken.
   
   ## Consequences
   
   What this costs, what it forecloses, and what now has to be true.

   • exit 0
   • stdout_contains /schema: adr/v1/
   • stdout_contains /origin: extracted/
   • stdout_contains /file:docs/d/
3. 3$ majordomus adr check exit 0

   identity, stavy, nahrazení a každý odkaz, v jednom průchodu

   examined 1 decision(s) in .ai/repo/adrs/
   every identity unique, every status known, every reference resolves
   0 identities added here, measured against main and every other ref

   • exit 0
   • stdout_contains /every identity unique/
4. 4$ majordomus adr show adr-0001 exit 0

   related je dopředná hrana: pravidlo, které rozhodnutí deklaruje, soubor, ke kterému sahá

   .ai/repo/adrs/0001-the-registry-is-the-one-canonical-declaration.md
   
   ---
   schema: adr/v1
   id: adr-0001
   kind: adr
   title: The registry is the one canonical declaration
   status: proposed
   related:
     - rule:majordomus.adr-integrity
     - file:docs/d
   date: <date>
   tags:
     - architecture
   provenance:
     origin: extracted
     derived_from:
       - file:docs/d
   ---
   
   # 1. The registry is the one canonical declaration
   
   ## Context
   
   What forced the decision. Derived from:  file:docs/d.
   
   ## Decision
   
   The registry is the one canonical declaration
   
   ## Alternatives rejected
   
   What else was considered, and why it was not taken.
   
   ## Consequences
   
   What this costs, what it forecloses, and what now has to be true.

   • exit 0
   • stdout_contains /related:/
   • stdout_contains /rule:majordomus.adr-integrity/
5. 5$ majordomus knowledge edges --type declares exit 0

   týž fakt jako hrana, s klíčem front matter, který jej uvedl, jako proveniencí; opačný směr nezapsal nikdo

   declares        adr:adr-0001                                   rule:majordomus.adr-integrity                  .ai/repo/adrs/0001-the-registry-is-the-one-canonical-declaration.md:related.0
   knowledge edges: 1 in scope all, type declares
   INFO knowledge   . — the schema check was not asked for (MAJORDOMUS_KNOWLEDGE_SCHEMA=unasked), so no file was checked against the schema of its kind

   • exit 0
   • stdout_contains /adr:adr-0001/
   • stdout_contains /rule:majordomus.adr-integrity/
   • stdout_contains /related.0/
6. 6$ majordomus adr affected exit 0

   tytéž hrany čtené ze sady změn: kterých rozhodnutí se tato práce dotýká. Čistý strom se nedotýká ničeho a exit kód nikdy neřekne, že rozhodnutí přestalo platit

   adr affected: no decision names anything this change set touches

   • exit 0
   • stdout_contains /no decision names anything this change set touches/
7. 7$ majordomus adr propose 'A decision that accepts itself' --status accepted kód 15

   odmítnutí, na kterém záleží: nástroj, který smí zapisovat přijaté, mění svou inferenci v pravdu repozitáře

   majordomus: adr propose: the status is not yours to choose; a proposed decision is accepted by a person editing the record

   • kód 15
   • stdout_contains /not yours to choose/
8. 8$ majordomus adr propose 'A decision derived from a file nobody has' --from file:docs/nosuch exit 2

   extrahovaný záznam bez důkazu je tvrzení a jako takové se odmítá

   majordomus: adr propose: reference "file:docs/nosuch" names a path that does not exist

   • exit 2
   • stdout_contains /names a path that does not exist/

Proč to nástroj ví

Řetězec od této stránky ke kódu: případ užití jmenuje příkazy, pravidla a tvrzení; každé pravidlo se dispatchuje z registru a každé tvrzení jmenuje test, který ho dokazuje; scénář výše provedl příkazy. Nic v tomto řetězci není text o záměru.

• majordomus adrArchitektonická rozhodnutí repozitáře jako objekty: výpis, zobrazení, dotaz na další volnou identitu, navržení rozhodnutí s proveniencí a validace celé množiny proti tomuto stromu a každému dalšímu refu.
• majordomus knowledgeZkompilovaný index nad tím, co tento repozitář uvádí, a kandidátní záznamy, které odvozuje z toho, co epizoda udělala.

Pravidla, díky nimž platí

• ✕blokující Integrita architektonických rozhodnutíKaždé architektonické rozhodnutí, které repozitář drží, se parsuje podle kontraktu rozhodnutí, nárokuje identitu, kterou nenárokuje nic jiného, a každá relace a reference, kterou činí, se rozliší.

Uplatněné záruky

• ○zaručeno Architektonické rozhodnutí je jeden soubor v sekci adrs vrstvy, validovaný proti kontraktu rozhodnutí, s identitou, kterou si nic jiného nenárokuje, vzájemným nahrazováním a se všemi odkazy, které se dají vyřešit
• ○zaručeno Rozhodnutí uvádí, co uvedlo v platnost, jako typované odkazy, každý validovaný, a opačný směr — čím bylo rozhodnuto o pravidle, dokumentu, implementaci nebo případu — se čte z grafu znalostí, místo aby se zapisoval podruhé
• ○zaručeno majordomus adr propose zapíše rozhodnutí se stavem proposed a odmítne zapsat jakýkoli jiný stav, přidělí jeho identitu pod zámkem, aby se souběžní workeři nikdy nesrazili, a zaznamená, z čeho bylo rozhodnutí odvozeno

Související případy užití

Vypočteno z toho, co sdílejí: tvrzení, pravidla, příkazy, kategorie, aplikace. Tento seznam nikdo neudržuje.

• Určit jako data, co patří do AI kontextuPřečtěte si deklarovanou politiku rozsahu repozitáře, zjistěte, které cesty jsou v indexu a které mimo něj, a nechte ji uplatňovat doctor a index znalostí místo pevně zadaného seznamu.
• Uchovat, co se epizoda naučila, bez modelu a bez konverzaceZaznamenat rozhodnutí uvnitř epizody, odvodit ho z knihy do kandidátního záznamu znalostí, přečíst důkaz, že odvození proběhlo, a sledovat, jak druhé odvození nezmění nic.
• Zaznamenat, co jeden worker udělal za jedno sezeníOtevřete relaci, pracujte pod úlohami, kterých se dotkne, a zavřete ji do obálky, která odkazuje na to, co vytvořila, a nic nekopíruje.
• Vést plán jako milníky a úkoly, které nástroj umí validovatDeklarujte milníky jako výsledky a úkoly jako prováděcí kontrakty a nechte nástroj říct, co je připraveno a co blokováno.
• Přečíst si, co se stalo, a držet ledger v mezíchPřečte ledger jen pro připojování jako provozní historii, filtrovanou podle úlohy a události, zvaliduje každý řádek a nejstarší řádky přesune do archivu místo smazání.

Okamžiky, na které to odpovídá

• → sledoval, jak relace zrušila rozhodnutí z minulého týdne právě z toho důvodu, pro který vzniklo Rozhodnutí, jehož důvod žil v konverzaci, nelze posoudit, jen znovu rozebírat — workerem s méně informacemi, než měl ten první.
• → strávil hodinu zjišťováním něčeho, co repozitář už věděl, a to dvakrát Worker zjistí něco nákladného o kódové bázi, jednou to použije a s relací to zaniká, protože to nikdo nepřevedl na trvalý záznam.
• → sledoval, jak jeden worker záměrně vrátil změnu jiného workera Worker uvidí na své cestě nevysvětlenou změnu, usoudí, že je špatná, a odstraní ji — správně, podle důkazů, které měl.
• → hledal, proč jsme to zvolili, a našel chatový log Rozhodnutí učiněné v relaci je uloženo tam, kde ho přečte jen ta relace, takže ho nelze ani zrevidovat, ani objevit.
• → nechali rychlou a levnou relaci udělat rozhodnutí, se kterým teď žije celá kódová základna Schopnost se snižuje kvůli nákladům a nic neodlišuje úlohy, kde je to rozumné, od těch, kde je to drahé.
• → sledoval workera, jak tráví den postupem, který už byl vyloučen Negativní výsledky tvoří většinu experimentálního výstupu a nikdo je nezaznamenává, takže se prostor hledání prochází znovu.