Vývojová sémantika jsou schopnosti jednoho runtime; každý povrch je spotřebitel

Kontext

Cockpit se má stát softwarovým vývojovým povrchem v prohlížeči: úkoly, milníky, relace, předávky, peeři, workflow, pravidla, rozhodnutí, git. Otázka, na kterou toto rozhodnutí odpovídá, není, co by Cockpit měl ukazovat. Je to, komu patří sémantika, kterou by ukazoval, protože odpověď, jak ji dnes měříme, zní: programu, na který Cockpit nedosáhne.

Tento repozitář provozuje dva spustitelné soubory a rozdělení mezi nimi není vrstvení, je to zlomová linie.

bin/majordomus je shellový nástroj. majordomus --help seskupuje své příkazy jako TASK, CONTEXT, MEMORY, RULES, PLAN a SYSTEM — start, check, finish, session, checkpoint, evidence, handover, decision, question, plan, adr, usecase. Tento seznam je vývojový životní cyklus. Jeho implementací je lib/*.sh a lib/ je jediný zapisovatel objektů, které životní cyklus vytváří: lib/plan.sh:514-515 je jediné místo, kde se zapisuje YAML úkolu nebo milníku; lib/session.sh je jediné místo, kde se zapisuje záznam relace; lib/evidence.sh je jediné místo, kde se plní závazek.

bin/majordomus-cli je spustitelný soubor v Rustu. Vlastní registr schopností a každou jeho projekci — MCP, HTTP, OpenAPI, Swagger, Cockpit, příkazovou řádku, vygenerovanou referenci. majordomus-cli --help uvádí rozdělení záporně: „Životní cyklus úlohy (init, start, check, finish, doctor, ...) je shellový nástroj bin/majordomus ve stejném repozitáři; tento spustitelný soubor tyto příkazy neimplementuje.“

Tři měření činí důsledek přesným.

majordomus-cli capabilities list --format json hlásí 1236 schopností, z nichž 78 je vestavěných. Z těch 78 má přesně tři kind: command — executions.start, executions.cancel a peers.announce. Každá další schopnost runtime je dotaz nebo zdroj. Žádný vývojový objekt nelze přes runtime vůbec mutovat.

majordomus-cli commands graph --format json hlásí 163 příkazů ze tří původů: 95 executable, 40 workflow, 28 tool. Všech 28 příkazů původu nástroje nese důvod projections.withheld — 21 jako „ptá se člověka na něco; povrch požadavek/odpověď by se zasekl“, čtyři jako „žádná schopnost tento příkazový řádek nedeklaruje“, tři jako „efekt RepositoryMutation je nad stropem stroje LocalMutation“. Ani jeden nedosáhne MCP, HTTP ani Cockpitu. Totéž měření ukazuje, že polovina grafu s nástroji je jednoúrovňová — 28 uzlů, všechny v hloubce 1 — zatímco polovina se spustitelným souborem dosahuje hloubky 3 u 77 z 95 uzlů. majordomus plan done <id> není uzlem grafu příkazů vůbec; jen skupina majordomus plan ano.

majordomus-cli executions list odpovídá „no server is serving this repository; an execution lives in the process that accepted it, so this command has nothing to read.“ Rovina provádění, kde žijí jediné měnící schopnosti runtime, si nic neuchovává přes proces.

Cockpit tu viníkem není. Jeho zdroje odkazují na .ai/ přesně jednou, jako zobrazovaný popisek v apps/majordomus-cli/src/cockpit/pages.rs; nečte žádný stav a žádný nezapisuje. Už je to čistá projekce výstupu schopností, což po něm žádá ADR 0013 a docs/COCKPIT.md. Chyba je na druhé straně: runtime, který promítá, nemá co nabídnout z vývojové sémantiky, takže Cockpit, který má být vývojovým povrchem, má právě dvě možnosti — znovu implementovat životní cyklus v prohlížeči nebo v src/cockpit, nebo zavolat bin/majordomus jako příkaz. Obě vytvoří druhou implementaci vývojové sémantiky a právě ta druhá se rozchází.

Dvě další duplikace už existují a při druhé implementaci by se znásobily. Trvalé události a živé události jsou disjunktní modely: share/events.yaml registruje 20 názvů událostí knihy zapisovaných lib/*.sh do .ai/local/state/ledger.jsonl, zatímco apps/majordomus-cli/src/execution/event.rs definuje 15 zpráv streamu (execution.created … stream.closing), které žádná kniha nezaznamenává. Ani jedno není nadmnožinou druhého a nic je nepropojuje. A docs/generated/ má dva zapisovače: apps/majordomus-cli/src/generate.rs s jeho 15 cíli a shellovou sadu včetně lib/usecase.sh, bin/majordomus, scripts/derive a scripts/generate-site-data.

Repozitář už má jméno pro každou fázi, kterou vývojový povrch potřebuje — issue, milestone, task, context, session, workflow, execution, peer, capability, event, evidence, obligation. Žádné není třeba vymýšlet. Chybí to, že runtime nemůže změnit žádné z nich.

Rozhodnutí

Kanonický vývojový runtime je registr schopností spustitelného souboru v Rustu a vývojová sémantika jsou jeho schopnosti. Každá plocha — Cockpit, CLI, HTTP API, OpenAPI, MCP — je konzument, který od runtime žádá operace a odebírá jeho stav a události. Žádná plocha neimplementuje vlastní vývojovou sémantiku.

Concretely:

1. Registr je hranice. Vývojová operace — přesun úkolu, otevření nebo uzavření relace, zaznamenání checkpointu nebo předávky, připojení důkazu, navržení rozhodnutí, vyhodnocení dokončení — existuje jako deklarace capability! pod apps/majordomus-cli/src/capability/builtin/ s typovaným vstupem a výstupem a zpřístupňuje ji politika v command_graph/policy.rs, ne ruční práce. To je project.rust-canonical-declaration@1 a ADR 0004 uplatněné na polovinu modelu, kterou dosud nepokrývají.

2. Žádná nová podstatná jména. Každý stupeň vývojového pipeline se mapuje na pojem, který repozitář už má. issue a milestone jsou plán; jednotkou přijaté práce je existující task, ne nová „vývojová úloha“; zkompilovaný kontext je existující builder context a jeho zmrazení .ai/local/session-contexts/; vývojová relace je existující epizoda session; běžící práce je existující execution; aktér je existující peer; dokončení je existující uzavření obligation a kontrakt finish. Zavedení synonyma pro kterékoli z nich je vada, ne rozšíření.

3. Shell nástroj se stává spotřebitelem, ne vlastníkem. lib/*.sh držící jediného zapisovatele vývojového objektu je přechodný dluh, zaznamenaný jako takový. Každý příkaz životního cyklu konverguje ke runtime schopnosti, kterou shell vyvolává, přesně jak lib/context.sh a lib/capture.sh už vyvolávají binárku v Rustu přes lib/rust_bin.sh. Graf příkazů je ledger této konvergence: důvod projections.withheld „žádná schopnost nedeklaruje tuto příkazovou řádku“ u vývojového příkazu je otevřená položka, uvedená měřením.

4. Úložiště se znovu používá, nikdy nevymýšlí. Žádný nový datastore. Úkoly a milníky zůstávají .ai/repo/project/{issues,milestones}/*.yaml; uzavřené relace zůstávají .ai/repo/sessions/*.md; otevřená relace, aktivní úloha, kontrolní body, předávky a otázky zůstávají pod .ai/local/state/; trvalý žurnál událostí zůstává .ai/local/state/ledger.jsonl pod slovníkem v share/events.yaml; důkazy o dokončení zůstávají polem evidence[] uvnitř objektu plánu, který splňují; původ kontextu zůstává .ai/local/session-contexts/; artefakty zůstávají docs/generated/** a site/data/** zapisované jen generate::Target. Schopnost, která potřebuje někam uložit něco nového, je samostatné rozhodnutí, zaznamenané před přistáním.

5. Dvě vrstvy událostí, pojmenované. Trvalá změna stavu je událost účetní knihy se jménem registrovaným v share/events.yaml — to je záznam. Typovaný proud provádění přes /events je živý pohled na runtime v pohybu a nikdy není záznamem. Vývojová schopnost, která mění stav, připisuje do knihy; proud nese tutéž změnu, jak se děje. Žádná vrstva nesmí držet trvalý fakt, který druhá nevidí.

6. Jeden odvozovací řetězec pro vše vystavené. Kanonický typ (deklarace capability!, nebo u objektu vrstvy jeho druh v share/kinds.yaml) → schéma serializace (share/schemas/majordomus/<kind>/<kind>.v1.schema.json nebo generované CanonicalSchema) → HTTP route a docs/generated/openapi.{json,yaml} → nástroj nebo zdroj MCP → stránka Cockpitu, která vykresluje JSON té schopnosti. Každý článek je generován a majordomus capabilities validate, majordomus generate --check a kontrola projection-closure odmítnou jeho přerušení.

Invariant jednoduše: Cockpit neprovádí vývojovou sémantiku. Žádá schopnosti kanonického běhového prostředí a odebírá kanonický stav a události. Stejná věta platí s „CLI“, „HTTP API“ nebo „MCP“ místo „Cockpitu“.

docs/DEVELOPMENT_RUNTIME.md nese architekturu, hranice vlastnictví a změřený inventář, na kterých toto rozhodnutí stojí. project.development-semantics-are-canonical@1 z něj dělá pravidlo, ratchetované proti dluhu výše, ne tvrzené nad ním.

Zamítnuté alternativy

Nechat Cockpit volat bin/majordomus. Nejrychlejší cesta a důvod, proč toto rozhodnutí existuje. Povrch, který spouští shell, vlastní sestavení argumentů, interpretaci návratových kódů, obejití interaktivity a vykreslení chyb — čtyři sémantiky, v povrchu, nedeklarované. Graf příkazů to už odmítá z uvedeného důvodu u všech 28 příkazů nástrojů a project.commands-run-non-interactively@1 odmítá polovinu o interaktivitě rovnou.

Implementovat vývojovou sémantiku v Cockpitu a nechat CLI dohnat. Je to přesně to selhání, které byl repozitář postaven zachytit, a už se tu jednou stalo: dvě relace paralelně postavily tentýž subsystém release. Druhá implementace vývojové sémantiky je zrcadlo ve smyslu docs/DYNAMICITY.md a zrcadla se rozejdou při první úpravě, která jednu stranu zapomene.

Nejdřív přenést lib/*.sh celé do Rustu, pak postavit plochu. 13 873 řádků s plánem, účetní knihou, dispatchem doktrín a kontraktem finish uvnitř. Přepis, který musí přistát dřív, než může cokoli jiného začít, je přepis, který blokuje práci, již měl umožnit, a pracovníci tyto abstrakce právě teď paralelně rozšiřují. Rozhodnutí jmenuje hranici a nechává každou schopnost přejít ji ve vlastním tempu; graf příkazů hlásí, jak daleko přechod došel.

Nový model „vývojového objektu“ vedle vrstvy. Zamítnuto z důvodu, který uvádí docs/DYNAMICITY.md: skutečnost se dvěma vlastníky nemá žádného. Vrstva už typuje každý dotčený objekt, share/kinds.yaml už deklaruje kontrakty a .ai/repo/knowledge/sources.yaml už váže pathspec na druh. Paralelní model by byl druhým kanonickým vlastníkem z podstaty.

Ukládat provedení do nového úložiště, aby Cockpit mohl zobrazit historii. Svádí k tomu, že executions list viditelně nemá co číst. Zamítnuto, jak je napsáno: trvalý záznam už existuje a je jím ledger, a druhý trvalý log událostí by zopakoval vadu share/events.yaml, kvůli které se slovník zavedl. Úložiště provedení zůstává omezené a v rámci procesu; trvanlivost je úkolem ledgeru.

Důsledky

Co se stane možným. Vývojový povrch lze postavit, aniž by se cokoli rozhodlo o sémantice vývoje. Stránka úkolu v Cockpitu, nástroj MCP plan, HTTP route a podpříkaz CLI jsou čtyři projekce jedné deklarace a přidání páté nestojí nic. Workeři, kteří paralelně rozšiřují úkoly, milníky, kompilátor kontextu a kontroly dokončení, mají jedno místo ke konvergenci a jedno jméno pro každý pojem, takže konvergence je ověřitelná, ne vyjednávaná.

Co se stane měřitelným. Vzdálenost, kterou je ještě třeba urazit, je číslo, které vypíše příkaz: vývojové příkazy, jejichž důvod projections.withheld je „žádná schopnost tuto příkazovou řádku nedeklaruje“, a uzly původu nástroje, které jsou stále hloubky 1. Pokrok je zmenšující se základní linie, ne tvrzení.

Co to stojí. Každá vývojová mutace, která se přesune do runtime, potřebuje typované vstupní schéma, měřicí případy, případ užití, který se provádí, a odstranění interaktivity z příkazu, který před ní stojí. To je trvalá cena project.rust-canonical-declaration@1 a proto pravidlo ratchetuje, místo aby blokovalo: dluh je široký 28 příkazů a pravidlo, které by v den přistání selhalo na všech, by se vypnulo do dne.

Co zůstává zatím rozbité. Zůstávají dva zapisovatelé docs/generated/. Ledger a proud provedení zůstávají disjunktní. Kontexty relací, znalosti, dovednosti, prompty, otázky, historie a vyhledávání mají vlastníka v shellu a žádnou runtime schopnost. Každé je položkou inventáře v docs/DEVELOPMENT_RUNTIME.md s tím, co by bylo třeba k jeho uzavření; žádné toto rozhodnutí neuzavírá a nepředstírá, že hranice, kterou kreslí, je tam, kde kód dnes stojí.

Co se nesmí stát. Povrch, který si vypěstuje vlastní vývojovou sémantiku — stav počítaný v šabloně, přechod rozhodnutý v JavaScriptu, pole úkolu zapsané čímkoli jiným než runtime. Pravidlo a jeho kontrola existují pro tento případ a rohatka znamená, že nové porušení selže, i když se staré tolerují.