Znalosti

Epizoda zaznamenává rozhodnutí, řeší otázky a dokončuje úlohy a každé z toho je typovaný řádek v knize jednoho stroje. Kniha má omezenou retenci a je lokální; poznámka, kterou zanechá blokovaná úloha, je lokální; rozhodnutí je viditelné v majordomus history, dokud ho omezení neodstraní. Každé je důkazem čehosi pravdivého o repozitáři a do tohoto subsystému se nic z toho nedostalo do sledovaného stromu, jiného checkoutu ani povrchu, který registr krmí.

Majordomus to odvozuje. V okamžiku, kdy to, co epizoda ví, přestane být dosažitelné — koncová událost poskytovatele a jeho událost kompakce — se řádky registru, které epizoda označila, přemění na kandidátní záznamy znalostí pod .ai/repo/knowledge/candidates/, z registru a gitu, deterministicky, bez modelu a bez čtení konverzace. Člověk frontu projde a povýší, co si to zaslouží. Nic z toho nezávisí na tom, že si pracovník pamatuje příkaz, a repozitář, ve kterém se epizody uzavírají a žádné znalosti nepřibývají, se hlásí jako zastavený zapisovatel. Rozhodnutí je .ai/repo/adrs/0091-knowledge-is-derived-at-the-episode-boundary-and-a-person-promotes-it.md.

Co je záznam

Znalostní báze je druh knowledge, schéma knowledge/v1, pod .ai/repo/knowledge/ a nic jiného: žádný nový druh, žádné druhé úložiště, žádná paměťová služba, žádný agent (ADR 0010, project.no-new-nouns). Záznam je jedno tvrzení o repozitáři na jednom řádku, s:

Provenience záznamu přežije soubory, které cituje (I1987). Odkaz file: nebo test:, který strom už nedrží, se vyřeší přes historii gitu — nejnovější commit dosažitelný z HEAD, který se cesty dotkl a který ji stále drží nebo ji smazal — a file:<path>@<commit> jej připne na jeden commit. knowledge check takový odkaz označí za historický, místo aby jej mlčky propustilo (--json je vypisuje pod historical), a knowledge record jej vyřeší jako historical s blobem, který odpovídá, <commit>:<path>, jako cílem; shellová kontrola (mj_knowledge_file_in_history) a resolver v Rustu (file_in_history) odpovídají stejně. Cesta, kterou žádný commit této historie nikdy nedržel, se stále nevyřeší na nic, stejně jako připnutí na commit, který ji nedržel. Mělký klon, kterému commit chybí, za něj nemůže ručit, stejně jako u odkazu commit:. test/cases/3023 smaže citovaný soubor a commitne smazání.

Záznam nikdy není shrnutím konverzace a nikdy necituje prompt ani tah; kontrola, která drží project.never-store-transcripts, se vztahuje na jeho titulek, popis i tělo. ADR, pravidlo a dokument jsou samostatné zdroje: záznam se na ně odkazuje a nikdy je neopakuje. SCHEMAS.md obsahuje formát souboru s příkladem.

curated/ a candidates/ drží záznamy, o jeden stav od sebe. curated/ je to, co se tento repozitář rozhodl napsat sám o sobě, status: verified. candidates/ je to, co nástroj odvodil a nikdo neposoudil, status: candidate; je sledováno z téhož důvodu jako každý uzavřený záznam relace: záznam, který přečte jen jeden stroj, nečte nikdo (ADR 0014). Obojí jsou třídy zdrojů v .ai/repo/knowledge/sources.yaml, objevované přes git index jako každý druh, a obojí nese kontrakt README.md.

Na trunku záznamy čekají ve výstupní schránce

Kmen, který se mění jen přes pull requesty, nemůže commitnout, co tam zapisuje hranice epizody, takže kandidát zapsaný do candidates/ na kmeni by kmen nechal trvale špinavý. Dodatek ADR 0091 z 2026-10-15 (I1984) mění, kam epizoda kmene zapisuje, ne co zapisuje.

Kam jdou. Trunk je výchozí větev remote, jak ji čte mj_git_trunk_ref (refs/remotes/<remote>/HEAD); checkout je na ní, když HEAD je lokální větev tohoto názvu (mj_on_trunk). Tam knowledge derive zapisuje každého nového kandidáta do .ai/local/state/outbox/candidates/<id>.md a session close a recover episodes zapisují záznam uzavřené relace do .ai/local/state/outbox/sessions/ místo sledovaných sekcí. Outbox je lokální pro checkout a nikdy se nesleduje, takže uzavření epizody na trunku nechá git status --porcelain prázdné. Kandidát, jehož id je už povýšeno nebo nahrazeno, se přeskakuje jako dřív, a ten, který už je sledován se stejnými bajty, se hlásí unchanged a není staged. Repozitář bez remote nebo bez výchozí větve remote a odpojený HEAD nejsou na trunku: tam záznamy jdou, kam vždy šly.

Kdy odcházejí. Příští session close na jakékoli jiné větvi téhož klonu vyprázdní outbox (mj_session_outbox_drain), po záznamu vlastní epizody a před jejím odvozením. Každý soubor se přesune do .ai/repo/sessions/ nebo .ai/repo/knowledge/candidates/ beze změny a pod vlastním jménem, takže záznam stále jmenuje epizodu a větev, která ho napsala, nikdy tu, která ho nesla, a pull request té větve ho přenese do trunku. Přesun se stane jednou na záznam: záznam relace, který sekce už drží podle session_id, a kandidát již povýšený, nahrazený nebo sledovaný se stejnými bajty se z outboxu vyřadí, nezapisuje se znovu. Každý přesun je jeden řádek na standardním chybovém výstupu (outbox: carried <path>, outbox: <id> is already tracked; the staged copy is retired), protože standardní výstup uzavření je cesta jeho vlastního záznamu.

Co to mezitím říká. Dokud je nenese větev, nejsou připravení kandidáti ve frontě revize: knowledge candidates, index a povrchy čtou candidates/ a majordomus.candidates-reviewed je ani nepočítá, ani nehlásí jako nesledované. Neprázdný outbox je tedy jmenován tam, kam se člověk podívá jako první. context vytiskne jeden řádek, outbox <n> session record(s), <m> knowledge candidate(s) in .ai/local/state/outbox/, waiting for a branch episode to carry them; doctor hlásí zjištění INFO outbox v kategorii clone se stejnými počty a ls .ai/local/state/outbox/*/ jako jeho reprodukce. Žádné z toho není selhání: outbox je místo, kam záznamy epizody na trunku patří, a klon, který už nikdy nevětví, stále říká, co drží. Prázdný outbox neříká nic.

Soubor, který není záznam. Soubor relace bez front matter session/v1 pojmenovávajícího session_id, nebo kandidát bez front matter knowledge/v1, jehož id je jeho název souboru, se pojmenuje na standardním chybovém výstupu a ponechá se, kde je: jeho přesun by vložil neplatný soubor do sledované sekce a jeho odstranění by ztratilo cokoli, čím byl. Stejně tak soubor relace, jehož jméno už zabírá záznam jiné epizody ve sledované sekci. Odvod končí s outbox: <n> file(s) stay in .ai/local/state/outbox/ (run: majordomus doctor) a doctor a context soubor dál počítají, dokud ho člověk nepřesune nebo neodstraní. Případ 3060 dokládá polovinu trunku a případ 3063 odvod.

Co se odvozuje a z čeho

Důkazem jsou řádky ledgeru, které epizoda označila, a commity, které vytvořila. Mapování je tato tabulka a deriver implementuje přesně tuto tabulku; ADR 0118 přidalo její řádek pozorování.

Každé odvozené rozhodnutí je convention. Číst formulace, aby se rozhodlo, zda rozhodnutí zavazuje, by byl druh odvozený z prózy, což kompilátor znalostí všude jinde odmítá, a je to přesně úsudek, který povýšení zaznamenává: --class při povýšení je místo, kde z něj člověk udělá constraint nebo lesson. task.finished s jakýmkoli jiným výsledkem nebo completed bez verifikace nedá žádný záznam. Next Action předávky je stav pokračování, ne znalost, a nikdy se z ní neodvozuje.

Stejný ledger, stejný git, stejné bajty. Id záznamu je id epizody následované otiskem kanonického řetězce důkazu, takže stejný fakt vždy skončí ve stejném souboru a dva worktree nikdy nezapíšou jedno jméno pro různý obsah. date je den řádku důkazu, nikdy hodiny, a do souboru nevstupuje žádná náhodná hodnota. Volný text řádku ledgeru se při čtení jednou odescapuje a při skládání záznamu jednou escapuje, takže uvozovka uvnitř rozhodnutí záznam ani neukrátí, ani nezmění jeho identitu. Řádek, jehož text nese značku přepisu, nedá žádný záznam; hlásí se jako přeskočený, místo aby se zapsal, aby ho kontrola integrity odmítla. Žádná síť, žádný model, žádné eval (project.no-network-no-eval).

Co relace pozorovala

Worker zaznamenává tření, na které narazil, pomocí majordomus knowledge observe --kind <kind> --subject <ref> [--evidence <ref>]... "<statement>" (ADR 0118). Druhy jsou friction, workaround, defect, drift a repetition; předmětem je cesta v repozitáři nebo capability:, rule:, command:, gate: s identifikátorem; odkazy na důkazy jsou file:, test:, commit:, issue: nebo claim:. Příkaz zapíše jeden řádek observation.recorded a nic nesoudí; chybně formovaný vstup je odmítnut s exit 2 a nic se nezapíše.

Kam se pozorování směruje. V tomto pořadí: subjekt command:, capability: nebo rule:majordomus.*, cesta pod vendorovanými pravidly nebo cesta pod vlastním share/ nástroje, jen když ten adresář leží uvnitř repozitáře, směruje platform; jiný rule: nebo gate: směruje enforcement; cesta, kterou rozsah deklaruje jako generovanou nebo kterou .gitattributes označuje merge=derived, směruje generator; cesta pod docs/ směruje documentation; cokoli jiného směruje project. Slova se nikdy nečtou a trasa o ničem nerozhoduje: povýšení a odmítnutí zůstávají úkony. V repozitáři, který nástroj přijal, je share/ vlastní projektu a směruje project.

Opakování se čte. Každý kandidát pozorování je soubor své vlastní epizody, takže dvě epizody, worktree či stroje nikdy nezapíšou jedno jméno a merge přidá soubory bez konfliktu. knowledge candidates seskupí kandidáty a zamítnuté záznamy o jednom subjektu s epizodami za nimi — stejná odpověď z shellu i z knowledge_base.candidates. Epizoda, která nic nepozorovala, nezapíše žádného kandidáta a přesto připojí knowledge.derived s written: 0: vyhodnoceno, nic nenalezeno.

Dva okamžiky

Deriver běží, když běží checkpoint, z důvodu checkpointu: koncová událost providera a jeho událost compaction jsou okamžiky, kdy to, co epizoda ví, přestává být dosažitelné.

Cesta uzavření je jedna. mj_session_close v lib/session.sh spouští odvozovač po publikování záznamu relace a před připojením session.closed, kdykoli session.knowledge_on_end není vypnuto. Za každým uzavřením — koncovým adaptérem poskytovatele, majordomus session close zadaným člověkem, jakýmkoli budoucím volajícím — proto následuje jeho řádek knowledge.derived a odvození předchází uzavření v pořadí registru. Koncový adaptér v lib/capture.sh čte výsledek uzavření a selhání odvození hlásí přes mj_capture_session_failed; neodvozuje podruhé.

Adaptér kompakce nemá žádné uzavření, na které by se mohl navézt, proto volá deriver sám, přepínaný pomocí session.knowledge_on_compact a nezávislý na checkpoint_on_compact: kompakce, která vynechá svůj checkpoint, přesto odvozuje.

Běží bez ohledu na to, zda je aktivní úloha. Životní cyklus patří epizodě (ADR 0052) a úloha je volitelný vztah, který záznam jmenuje, pokud nějaký má. Na požádání totéž udělá majordomus knowledge derive pro otevřenou epizodu nebo tu, kterou pojmenuje --episode.

Přepínače žijí vedle těch, které existují, s důvodem, proč tam jsou, napsaným jako jejich komentář:

.ai/repo/policy.yaml a share/skeleton/policy.yaml je nesou; schéma politiky a regenerovaný povolený seznam je přijímají; mj_validate_policy_defaults a mj_validate_policy_completeness je vidí tak, jak vidí každý klíč.

Důkaz, že proběhl

Každé odvození je řádek ledgeru, registrovaný v share/events.yaml dřív, než se kdy zapíše, protože neznámé jméno události je chyba.

Odvození, které selže uvnitř hooku providera, se zaznamená jako provider.event.failed přes mj_capture_session_failed a hook skončí 0: provider není nikdy blokován a selhání není nikdy tiché. Vypnutý přepínač se řekne na stderr a nezanechá řádek odvození, což kontrola zastaveného zapisovatele bere jako záměr.

Akt povýšení

verified zapisuje akt, nikdy deriver.

majordomus knowledge promote <id> [--class <c>] < evidence.md přesune kandidáta do curated/, nastaví status: verified, nastaví třídu, kterou osoba zvolila, datuje jej dneškem, ponechá derived_from a přidá povyšující epizodu, pokud je nějaká otevřená, připojí důkazy pod # Evidence, odstraní kandidáta, připojí knowledge.promoted a nakonec vypíše kurátorovanou cestu. Prázdný stdin je odmítnut, protože akt bez důkazů je jen tvrzení; stdin nesoucí značku přepisu je odmítnut z důvodu, proč ji záznam nesmí nést.

majordomus knowledge reject <id> --reason "<why>" [--by <id>] přepíše kandidáta na místě jako superseded, jmenuje superseded_by, když --by udává záznam, který jej nahrazuje, připojí důvod pod # Rejected, připojí knowledge.rejected a vytiskne cestu jako poslední. Nahrazený záznam zůstává pod candidates/ jako odmítnutí, které provedl člověk, a nepočítá se ani do limitu, ani do stáří.

Člověk upravující soubor je ten druhý úkon. Deriver přeskočí id, které bylo povýšeno nebo nahrazeno, takže žádný z úkonů příští hranice epizody nezruší.

Co se říká dalšímu pracovníkovi

Úvodní briefing (ADR 0017) získává jednu omezenou sekci, za otevřenými otázkami a před předávkou: kandidáti čekající na posouzení na této větvi, počet na jednom řádku a pod ním id, omezené stejně jako blok otevřených otázek a uvnitř session.briefing_budget_lines. Větev kandidáta je větev epizody, kterou pojmenovává jeho derived_from, čtená ze sledovaného záznamu relace, nebo dokud není tento záznam zapsán, z knihy. Kandidát, jehož epizodu tento checkout nedokáže rozřešit, je pojmenován na zvláštním řádku jako nepřiřazený místo skrytí, protože záznam, který briefing neumí zařadit, je stále záznam, který někdo musí posoudit. Absence se vypisuje, nevynechává.

Příkazy

majordomus knowledge už není read-only; share/commands.yaml to říká a CLI.md má prózu. Každý zápis je atomický — dočasný soubor ve stejném adresáři, přejmenovaný přes cíl — nikdy se nestaguje a na posledním řádku vytiskne zapsanou cestu, jako to dělají handover a checkpoint.

Výstupem derive je jeden řádek na záznam — written <path>, unchanged <path>, skipped <path> (promoted|superseded|transcript) nebo would write <path> pod --dry-run — pak souhrnný řádek jmenující počty a epizodu; když není epizoda, ze které odvozovat, řekne to a skončí s exit 0 bez řádku knihy. --json u každého podpříkazu je jeden objekt se stejným obsahem jako text.

Čtecí stranu obsluhuje Rust exekutor: bin/majordomus-cli knowledge candidates, knowledge record <id> a knowledge status, každý je příkazovořádková projekce schopnosti deklarované jednou v apps/majordomus-cli/src/capability/builtin/knowledge_base.rs a obsluhované stejně přes HTTP, OpenAPI, MCP, katalog Cockpitu a inventář měření (CAPABILITIES.md). record rozliší každý odkaz, který záznam jmenuje, na objekt indexu, externí fakt knihy nebo gitu, historický soubor, nebo chybějící; status hlásí poslední derivaci, nejnovější uzavření, aktuálnost vůči politice a posouzení zastaveného zapisovače. Nic nezapisuje a absenci hlásí jako absenci.

Vynucování

Níže uvedená pravidla patří standardnímu balíčku, vendorovanému do každého repozitáře, který nástroj inicializuje, a dispatchovanému z registru doktrín (DOCTRINE.md). Dodávají se s nástrojem, a ne jako projektová pravidla, protože doctor v každém repozitáři odmítne validátor, který nedeklaruje žádné pravidlo efektivní sady, a jednorázový testovací repozitář nese jen vendorovaný balíček; ADR 0052 narazilo na stejné omezení a odpovědělo na ně stejně.

Posouzení zastaveného zapisovatele je hlídáno tak, jak ADR 0052 hlídal svůj vlastní: checkout, jehož registr nedrží žádný řádek knowledge.derived, se hlásí jako přeskočený, takže v den, kdy odvozovač dorazí, nezčervená žádný checkout, a první odvození přeskočení ukončí. Jeho reprodukce je jen pro čtení — majordomus history --event session.closed a majordomus history --event knowledge.derived — a náprava následuje po fix: ve zprávě. Blokující validátory zahrnují zapisovatele v shellu i čtečku v Rustu: polovina posouzení týkající se čerstvosti se dělá na obou stranách ze stejného registru a stejných čísel politiky a polovina týkající se zapojení patří jen validátoru v shellu, protože jen nástroj shellu přečte svůj vlastní zdroj.

Poradní pravidlo frontu měří a nic nevyprazdňuje. Stáří review je stáří položky fronty — nejstarší řádek knowledge.derived jmenující soubor, pak commit, který ho přidal, pak date záznamu — a zjištění říká, který zdroj použilo. Spouští se jen z doctor: pod watch je poradní zjištění drift a plná fronta review nesmí v hooku zčervenat watch. Kandidát staged v outboxu trunku je mimo candidates/ a mimo toto pravidlo; doctor místo toho jmenuje outbox pod clone.

Pravidlo grafu posuzuje to, co kompilátor sestavil, ne to, co záznam tvrdí, a má jednoho soudce: každé zjištění je takové, které kompilátor vydá při extrakci, a knowledge validate, doctor a watch ho jen klasifikují. O tom, které porušení selže, rozhoduje to, kde byl vztah uveden. Co Majordomus odvodí ze strukturovaného pole — milestone a depends_on úkolu, source, implementation a test tvrzení, závislost pravidla — je vlastní a rozbité selže příkaz (exit 10), varuje pod doctor, kde je pravidlo doporučující, a pod watch je driftem. Odkaz, který autor napsal v próze, může záměrně mířit mimo repozitář, takže cíl, který pojmenovává a který se na nic nerozřeší, se hlásí a nikdy neselže; doctor a watch je shrnují na jednom řádku. Sledovaný zdroj, který pracovní strom už nedrží, se hlásí jako source_missing — probíhající smazání — a pod watch je driftem. Žádný generovaný graf se neukládá (I0810 byl zrušen, protože žádný neexistuje), takže není index, který by zastaral, ani uložený hash, který by se neshodoval; příkaz to říká při každém běhu a doctor odpovídá, zda lze graf zde sestavit, tím, že ho zkompiluje do dočasného souboru, který odstraní. Nic se nepřestavuje ani neopravuje.

Každé pravidlo jmenuje své testy a svá tvrzení; scripts/ci/rule-proof-check a scripts/ci/claim-proof-check odmítnou pravidlo, jehož důkaz chybí, a tvrzení, jehož test ho nejmenuje. CLAIMS.yaml nese jedno tvrzení na každé vynucované chování.

Od důkazů k povrchu

flowchart TD
  work["work happens: decision add, question resolve, finish"]
  ledger["the ledger: decision.recorded, question.resolved,<br>task.finished, stamped with the episode"]
  git["git: the episode's commits and the rules<br>and decision records they touched"]
  pc["provider fires PreCompact"]
  se["provider fires SessionEnd, or a person<br>runs session close"]
  derive["majordomus knowledge derive<br>deterministic, no model, no network"]
  cand[".ai/repo/knowledge/candidates/&lt;episode&gt;-&lt;digest&gt;.md<br>TRACKED, status candidate, origin extracted"]
  event["knowledge.derived in the ledger:<br>episode, written, unchanged, paths"]
  brief["the next start briefing:<br>candidates awaiting review on this branch"]
  promote["majordomus knowledge promote &lt;id&gt; &lt; evidence<br>a person's act"]
  reject["majordomus knowledge reject &lt;id&gt; --reason<br>superseded in place"]
  curated[".ai/repo/knowledge/curated/&lt;id&gt;.md<br>status verified"]
  index["the index: source classes curated and candidates"]
  surfaces["CLI · HTTP · OpenAPI · Swagger UI · MCP · cockpit · site<br>knowledge_base.candidates · record · status"]
  doctor["doctor and watch:<br>knowledge-observed · knowledge-integrity · candidates-reviewed"]

  work --> ledger
  work --> git
  pc --> derive
  se --> derive
  ledger --> derive
  git --> derive
  derive --> cand
  derive --> event
  cand --> brief
  cand --> promote --> curated
  cand --> reject
  cand --> index
  curated --> index
  index --> surfaces
  event --> doctor
  cand --> doctor

Co nedělá

Nevolá model, síť ani eval a nečte konverzaci, prompt ani předávku. Nepřidává druh, rodinu adresářů, agenta, roli ani registr; význam nese druh knowledge s třídou a stavem. Nekontroluje, zda je úloha aktivní, dokončená nebo předaná. Nezapisuje verified, nestaguje a necommituje. Nerozhoduje, které kandidáty si zaslouží povýšení; poradní pravidlo existuje proto, aby byla fronta vidět, ne aby ji stroj vyprázdnil.

Související

CONTINUITY.md pro epizodu a záznamy, které ji přežijí · CLI.md pro každý příkaz · SCHEMAS.md pro formát záznamu a události · DOCTRINE.md pro to, jak se tři pravidla rozesílají a dokazují · CAPABILITIES.md pro to, jak čtečka v Rustu dosáhne každého povrchu · CLAIMS.yaml pro tvrzení a jejich testy.