Zpráva o extrakci

Toto je záznam o tom, jak byl DESIGN.md odvozen. Existuje proto, aby každé designové rozhodnutí šlo vystopovat k pozorovanému selhání nebo pozorovanému úspěchu a aby čtenář viděl, co bylo zvažováno a zamítnuto, nejen co bylo ponecháno.

Zdrojovým materiálem bylo velké soukromé inženýrské prostředí: instrukční soubory napříč zhruba dvaceti repozitáři, jeden velmi velký monorepozitář se zralým korpusem politik a háčků, několik let poznámek z relací a retrospektiv a čtyři dřívější pokusy o dozorový nástroj. Nic z toho materiálu se zde nereprodukuje. Cesty, jména, citace a interní slovník byly odstraněny. Řádové velikosti zůstávají, protože jsou důkazem.

Metoda: prostudovat → abstrahovat → zpochybnit → syntetizovat. Ne kopírovat → přejmenovat → publikovat.

1. Definice produktu

Prismatic Majordomus je lehká řídicí dozorová vrstva pro práci asistovanou AI. Drží jednu kanonickou politiku, promítá ji do jakéhokoli formátu instrukcí, který čte každý AI pracovník, drží trvalý stav úloh mimo každou konverzaci, koordinuje rozsah mezi souběžnými pracovníky a odmítá označit práci za dokončenou, dokud není splněn kontrakt dokončení.

Není to model, framework pro agenty ani runtime. Dohlíží na pracovníky; nespouští je.

Jedna věta: AI pracovníci by neměli řídit sami sebe.

2. Jediná kořenová příčina

Každé vlákno extrakce konvergovalo k jednomu zjištění a to se uvádí první, protože zbytek návrhu je jeho důsledek.

Vynucování se deklaruje v próze a nikdy se neusmiřuje s tím, co skutečně běží.

Nezávislé instance nalezené ve zdrojovém materiálu, každá ověřena čtením zapojení, ne dokumentace:

Sedmnáct není vyčerpávající. Je to počet, při němž přestalo být zajímavé vzor dál rozšiřovat.

Důsledek pro návrh: hlavní deterministickou zárukou doctor je, že každé vynucování, které politika deklaruje, se vyřeší na artefakt, který existuje, je spustitelný a je dosažitelný z pojmenovaného dispečera. Ta kontrola má zhruba šedesát řádků. Zdrojové prostředí ji popsalo na pěti místech a neimplementovalo ji nikde.

3. Ledger vzorů

Sloupce: Proven znamená pozorováno, že funguje v produkci, nejen navrženo. Generalizable znamená použitelné běžným týmem s gitem a shellem, bez jiného runtime. Complexity je odhad pro implementaci v přenosném shellu.

4. Zamítnuté vzory

Rovnou zamítnuto, se selháním, které zamítnutí ospravedlňuje:

5. Navrhovaný strom souborů

.
├── README.md
├── LICENSE
├── SECURITY.md
├── CONTRIBUTING.md
├── AGENTS.md                    # canonical AI-readable contract for this repo
├── CLAUDE.md                    # pointer to AGENTS.md until `update` generates it
│
├── bin/
│   └── majordomus               # single portable-shell entry point
│
├── lib/                         # sourced shell modules, one per subcommand
│   ├── common.sh
│   ├── doctor.sh
│   ├── start.sh
│   ├── check.sh
│   ├── watch.sh
│   ├── update.sh
│   ├── handover.sh
│   └── finish.sh
│
├── share/
│   ├── skeleton/                # what `init` copies into a project's .majordomus/
│   │   ├── policy.yaml
│   │   ├── profiles/            # routine · implementation · debugging · deep-work
│   │   ├── templates/           # handover, completion, decisions, open-questions
│   │   └── providers/           # body.md + one wrapper template per provider
│   └── allow/                   # key allowlists: unknown keys are errors
│
├── .majordomus/                 # this repository supervising itself
├── .githooks/                   # pre-commit runs doctor, pre-push runs finish --check
│
├── test/
│   ├── run.sh
│   └── cases/                   # one script per behaviour, disposable repo each
│
├── examples/
│   └── minimal/                 # a scratch repo walked through start → finish
│
└── docs/
    ├── README.md                # index
    ├── DESIGN.md                # specification
    ├── CLI.md                   # commands, exit codes, target output
    ├── SCHEMAS.md               # every file, with a concrete example
    └── EXTRACTION_REPORT.md     # this document

Odstraněno z původního návrhu: principles/ (splývá s policy.yaml a README), workflows/ (lifecycle je CLI; adresář workflows by byl druhým popisem téhož), vějíř scripts/majordomus-* spustitelných souborů (jeden vstupní bod, sourcované moduly). Nic se nezachovalo jen proto, že to prompt navrhl.

6. Kanonické pojmy

Běžný inženýrský slovník. Žádný soud.

7. Hranice MVP

v0.1 umí: držet kanonickou politiku; definovat čtyři profily; spustit úlohu s rozsahem a normalizovaným tvrzením; uchovávat trvalý stav s identitou odvozenou z gitu; označit zastaralost stavu při čtení; zapisovat a rozřešit předávky; vyhodnotit kontrakt dokončení; detekovat třídy driftu v návrhu; generovat projekce s otiskem pro čtyři poskytovatele; prokázat, že jeho vlastní vynucování je zapojeno; běžet zcela offline v přenosném shellu.

v0.1 neumí: vyvolat model; měřit tokeny či cenu; dynamicky směrovat; hookovat runtime pracovníka; spouštět cokoli na pozadí; koordinovat napříč stroji; reprezentovat závislosti úloh.

Hranice je v README uvedena se stejnou důležitostí pro obě poloviny.

8. Audit extrakce / důvěrnosti

Provádí se nad obsahem tohoto repozitáře před každým pushem.

• Neobjevují se žádné interní cesty, názvy hostitelů, URL, identifikátory zákazníků či případů ani tajemství. Zkontrolováno grepem na názvy adresářů zdrojového prostředí, vzory hostitelů a slovník; nula zásahů.
• Neobjevuje se žádná citace ze soukromého materiálu. Hlásí se řády; věty ne.
• Slovník doktríny zdrojového prostředí (názvy pilířů, zkratky, divadelní štítky) se nevyskytuje.
• Jediná odkazovaná značka je „Prismatic“ v názvu produktu a v jednosměrném prohlášení o původu.
• Pracovní ledger použitý při extrakci žije v dočasném adresáři relace mimo tento repozitář a necommituje se.
• Směr závislosti: žádný. Tento repozitář nic neimportuje a na nic ve zdrojovém prostředí neodkazuje.

9. Rizika

10. Doporučený plán implementace

Pět fází, každá podmíněná realitou té předchozí, žádná nezačne dřív, než je předchozí zrevidována.

1. Návrh — tento dokument a DESIGN.md. Dokončeno.
2. Implementovat v0.1 — hotovo; viz CLI.md, SCHEMAS.md, test/cases/. Původní zadání: — strom souborů výše; behaviorální testy v jednorázových repozitářích pro: šťastnou cestu init, chybějící politiku, neplatné YAML, neznámý klíč, chybějící rozsah, nedokončenou úlohu, platné dokončení, zápis a rozlišení předávky, odmítnutí přepsání, každou třídu odchylky a zdravý případ bez zjištění. Každé tvrzení README se porovná s implementací dřív, než se fáze uzavře.
3. Udělat dozor skutečným — pro každou odpovědnost poctivě odpovědět dokumentováno / reprezentováno / validovatelné / vynucováno / měřitelné; uzavřít nejhodnotnější mezery v tomto pořadí: integrita stavu, integrita politiky, detekce driftu, integrita životního cyklu, integrita předávek, drift projekcí, viditelnost rozpočtu, viditelnost koordinace. Vytvořit dokument modelu dozoru, který odděluje zaručené od pozorovaného.
4. Nepřátelské posouzení — matice tvrzení/implementace; pokus smazat 30 % repozitáře; desetiminutový průchod novým uživatelem; sken čisté extrakce včetně historie gitu; audit bezpečnosti a přenositelnosti; audit terminologie. Vrací READY nebo NOT READY s blokátory.
5. Release — až po READY. Šablonový repozitář, minimální CI, v0.1.0, poznámky k release bez nafukování, vzdálená validace včetně čerstvého repozitáře vygenerovaného ze šablony.

Fáze 3 je další akce.

11. Druhý průchod — záznamy relací a kompilátor znalostí

První průchod zkoumal instrukční soubory, hooky, úložiště stavu a koordinaci. Nezkoumal dva podsystémy, které se ukazují jako důležité pro tentýž problém: souborovou disciplínu poznámek relace a bezstavový kompilátor Markdownu, který z vlastních dokumentů repozitáře vytvářel procházitelný generovaný trezor poznámek.

Byly znovu prozkoumány, když se plánovalo M003. Metoda je nezměněná — studovat, abstrahovat, zpochybnit, syntetizovat — a stejně tak pravidlo důvěrnosti: hlásí se mechanismy a řádové velikosti, nikoli kód a slovník.

Oba jsou velmi rozdílné kvality a ten rozdíl je sám zjištěním. Disciplína poznámek relace je tvarovaná podle názvu souboru: vynucuje jmennou gramatiku a nemá model toho, co záznam obsahuje. Kompilátor je postaven pořádně a téměř každá jeho pojistka nese komentář, který pojmenovává selhání, jemuž brání.

Co říkají důkazy

Adoptováno, přeodvozením

Každá z nich je nápad, znovu implementovaný od základu v přenosném shellu a awk proti vlastním záznamům Majordomus. Žádný kód, schéma ani slovník nebyl převzat.

Odmítnuto