Uvažování

Jak relace mění materiální inženýrskou nejistotu v rozhodnutí, které obhájí: nejdřív s důkazy, s nezávislými poradci, jsou-li přítomni, bez nich, nejsou-li, a se záznamem, který může pozdější relace číst, místo aby se ptala znovu. ADR 0098 je rozhodnutí; apps/majordomus-cli/src/reasoning/ model; scripts/lib/advisors/ transport.

Co to je

Uvažování nezávislé na poskytovateli. Provádějící agent vlastní každé inženýrské rozhodnutí. Shromažďuje důkazy, uvádí, co je nejisté a jak moc na tom záleží, a ptá se politiky, zda stojí za to nezávislou revizi mít. Pokud ano a poradci jsou k dispozici, konzultují se; jejich odpovědi jsou důkazy, které vykonavatel váží, nikdy verdikty. Výsledkem je typovaný závěr s jeho důkazy, zamítnutými alternativami, zbývajícími riziky a plánem validace, a pak práce pokračuje: implementace, testy, validace.

Externí modely dělají review hlubší. Nic nerozhodují a jejich absence není selhání. Checkout bez nainstalovaného poradce, bez přihlašovacích údajů a bez sítě uvažuje, rozhoduje a validuje přesně jako dřív a říká, že to udělal lokálně.

Proč

Nejistota rozhodnutá potichu je nejistota, kterou nikdo nemůže auditovat. Názor poradce vložený do chatu je pryč do příští relace. A protokol napsaný jako „zeptej se tohoto dodavatele, pak toho“ se rozbije v den, kdy chybí CLI nebo vyprší klíč. Tento návrh dělá z nejistoty, rady i rozhodnutí explicitní záznamy a drží dodavatele mimo logiku.

Tok

flowchart TD
  E[local evidence] --> A[assessment: subject, materiality, hypothesis, evidence]
  A --> P{plan: policy over capabilities and availability}
  P -->|trivial or low| L[decide locally]
  P -->|material, no suitable advisor| R[structured local review]
  P -->|a standing conclusion answers it| U[reuse the prior conclusion]
  P -->|material, advisors available| C[consult the selected advisors]
  C --> N[normalised consultation records]
  N -->|positions diverge| D[disagreement]
  D --> X[experiment: resolution with evidence]
  X --> K[conclusion]
  N --> K
  R --> K
  L --> K
  K --> I[implementation]
  I --> V[validation records]
  V --> H[state, report, context, handover]

Uvažování s prioritou lokálnosti

Důkazy předcházejí názoru a zapisovač to vynucuje: posouzení nejistoty material, high nebo critical je odmítnuto bez odkazů na důkazy — soubory, testy, ADR, pravidla, commity, příkazy, runtime pozorování. Když plán nevybere žádného poradce, nese místo toho strukturovanou lokální recenzi, kterou provádí executor: uveďte hypotézu a její nejsilnější alternativu, vypište každý předpoklad s důkazy za ním, jmenujte, co by hypotézu vyvrátilo, spusťte nejmenší rozlišující experiment a zaznamenejte závěr.

Nezávislost na poskytovateli

Politika jmenuje schopnosti, nikdy poradce. Kdo schopnost může poskytnout, je odpověď katalogu poradců a zda ji může poskytnout nyní, je odpověď dostupnosti. Test a reasoning check drží, že žádný zdrojový soubor nezávislý na poskytovateli — modul uvažování, jeho schopnost, jeho příkaz, jeho stránka Cockpitu, kontrakt a driver transportu — nepíše poradce, adaptér, spustitelný soubor, poskytovatele, dodavatele ani model z katalogu.

majordomus reasoning advisors              # every advisor, its status and why; capacity per capability
majordomus reasoning advisors --format json

Seznam patří katalogu; tato stránka jej neopakuje. Každý poradce v něm je volitelný.

Dostupnost je stav

Jistič je čistá funkce zaznamenaných konzultací a hodin: žádný jiný stav než záznamy, nic k ručnímu resetu. Po uplynutí cooldownu je poradce opět dostupný a označen recovering a jeho další odpověď jistič zavře. Poškozená nebo prázdná odpověď či zrušení se týká jedné výměny a poradci se nezapočítává. MAJORDOMUS_REASONING_COOLDOWN_SECONDS přebíjí každý cooldown, například po opravě přihlašovacího údaje.

Politika konzultací

Rozpočet je počet poradců, které může plán vybrat:

Vysoká jistota v lokální hypotéze jej o jedna snižuje. offline připouští jen poradce, kteří běží na tomto stroji; ci nepřipouští žádného, ať je nainstalováno cokoli. Režim je MAJORDOMUS_REASONING_MODE, jinak ci na runneru CI, jinak reasoning: aktivního profilu, jinak standard.

Výběr je chamtivý a vysvětlený: každý další advisor je ten, který pokrývá nejvíc požadovaných schopností, jež ještě nejsou pokryty, poté ten dosažený jiným adaptérem (dvě odpovědi z jednoho zdroje jsou jeden názor dvakrát), pak pořadí deklarace — a v něm žije preference repozitáře („nejdřív ChatGPT, pak Gemini nebo Codex“). Každý nevybraný advisor se v plánu objeví se svým důvodem.

majordomus reasoning plan --materiality high --capabilities independent_reasoning,code_review

Důkazy a záznamy

Jeden zapisovatel, reasoning record, ukládá jeden soubor JSON na záznam pod .ai/local/state/reasoning/<task>/ — stav checkoutu, nikdy sledovaný, nikdy publikovaný. Tvary tajemství a řídicí znaky terminálu se odstraní z každého řetězce před zápisem a odstraněné tvary jsou v záznamu jmenovány.

majordomus reasoning record --file assessment.json      # or JSON on standard input

Konzultace se přijímá proti snímku plánu, který ji vybral, takže odpověď, která dorazí poté, co jiný požadavek otevřel okruh poradce, je stále tím důkazem, kterým byla.

Neshoda

Neshoda advisorů mezi sebou nebo s executorem se zaznamenává jako rozpor: pozice, předpoklady, na kterých se dělí, a otázka, jejíž odpověď rozhoduje. Závěr nad tímto posouzením se odmítne, dokud ho rozřešení nevyřeší, a rozřešení se bez důkazu odmítne. Počet advisorů na každé straně do rozhodnutí nikdy nevstupuje. Shoda je důkaz o shodě; experiment je důkaz o kódu.

Relace a předávky

majordomus reasoning status odvozuje stav úlohy z jejích záznamů: každé posouzení a kde stojí (open, planned, disputed, concluded, validated), každou konzultaci, každý nesouhlas a jeho vyřešení, každý závěr s vypočteným review a validací, časovou osu a součty tokenů, které adaptéry hlásily. Táž zpráva se objevuje v majordomus context (sekce REASONING) a v každém majordomus handover --derive (sekce Reasoning). Nová relace čte rozhodnutí a kdo ho posoudil, místo aby ho znovu objevovala.

Když pozdější posouzení uvádí stejný předmět, plán znovu použije platný závěr a nikoho nekonzultuje — pokud posouzení nedeklaruje new_evidence; pak review proběhne znovu a nový závěr uvede starý v supersedes.

majordomus reasoning explain <conclusion-id>    # the whole provenance chain of a decision

Transport

Síťový kód zůstává mimo crate (ADR 0032). scripts/advisor-consult zaznamená plán přes crate, souběžně se zeptá toho, co vybral, a zaznamená každý výsledek zpět v pořadí plánu, ne v pořadí příchozích odpovědí:

scripts/advisor-consult --assessment <id> [--question "..."] [--timeout 90] [--prior-opinion "..."]

Každý adaptér mluví jedním kontraktem (scripts/lib/advisors/contract.mjs): typovanými chybami (timeout, rate_limited, auth_failed, malformed, empty, unavailable, cancelled, error), deadlinem a zrušením a normalizací odpovědi do polí konzultace. Otázka nese destilované důkazy, hypotézu executora i odpověď případného předchozího poradce označuje jako názory, nikoli fakta, a žádá o nejsilnější argument proti, skryté předpoklady a vyvracející experiment. Surové odpovědi se neukládají.

Mesh peeři

Propojené runtimy meshe nesoucí funkci reviews jsou také advisoři, objevení z meshe sdíleným serverem a nikdy neuvedení v katalogu. Požadavek jej dosáhne jako požadavek na review v meshi (ADR 0067), přes server jmenovaný MAJORDOMUS_SERVER_URL; jeho odpověď je první odpověď review replikovaná zpět. Žádný peer není potřeba, stejně jako žádný advisor. apps/majordomus-cli/tests/reasoning_mesh.rs dokazuje obě poloviny se dvěma skutečnými runtimy a všemi advisory katalogu vypnutými: propojený runtime je advisor, plán code-review jej vybere, review odeslané přes mesh je zodpovězeno a přečteno zpět, a jakmile runtime zmizí, advisor zmizí a tentýž plán rozhodne lokálně.

Offline a CI

MAJORDOMUS_REASONING_MODE=offline připouští jen poradce běžící na tomto počítači; s žádným běží cesta lokální revize. Runner CI je v režimu ci: žádný poradce a žádná vyžadovaná kontrola nesmí pojmenovat přihlašovací údaje modelu — reasoning check odmítne workflow nebo kontrolu, která to dělá, v repozitáři, který deklaruje project.advisors-are-optional. Workflow a dokumenty adoptujícího jsou jeho vlastním produktem, takže tam kontroly ci a claims neběží. Každý test uvažování běží proti atrapám: skriptované fixture adaptéry, falešný fetch, falešný proces.

Povrchy

Všechny jsou projekce šesti schopností modulu reasoning; žádná nedrží vlastní seznam poradců.

Řešení problémů

• Poradce je not_configured — proměnná s přihlašovacími údaji jeho dodavatele není nastavena v prostředí procesu, který se ptá. V linked worktree se .envrc.local primárního checkoutu nenačítá, pokud tam není propojeno.
• Poradce je temporarily_failed s authentication_failed — proměnná je nastavena a dodavatel ji odmítl. Opravte přihlašovací údaje a pak konzultujte s MAJORDOMUS_REASONING_COOLDOWN_SECONDS=0, abyste to zkusili hned znovu.
• Klientský nástroj skončí chybou — diagnostika v záznamu konzultace je poslední řádek jeho standardního chybového výstupu, s odstraněnými řídicími znaky.
• Nic se nekonzultuje — přečtěte si plán: každý vynechaný poradce nese svůj důvod a o rozpočtu rozhoduje režim a významnost.

Přidání poradce

Deklarujte ho v share/advisors.yaml: id, název, transport, adaptér, poskytovatele, dodavatele nebo model, na který odkazuje, spustitelný soubor, jehož přítomnost znamená, že je nainstalován, a jeho schopnosti. Je-li transport nový, přidejte jeden modul scripts/lib/advisors/<adapter>.mjs exportující exchange(advisor, prompt, io) a jeho případy do sady kontraktů. Nic jiného se nemění: příkazová řádka, HTTP, OpenAPI, MCP, Cockpit, prostředí i doctor následují, jak dokazuje test/cases/735_a_new_advisor_needs_no_consumer_edit.sh.