Shellová automatizace — Prismatic Majordomus

Automatizace tohoto repozitáře se stěhuje ze shellu. ADR 0069 určuje směr: chování, které patří programu, se stane typovanou schopností a orchestrace nad schopnostmi se stane skriptem Rhai — skriptovanou schopností — místo shellového skriptu. Migrace tohoto tvaru konverguje, jen pokud přestane přicházet nový shell, zatímco se starý stěhuje, a o tom tato stránka je: o inventáři, který migraci sleduje, a o kontrole, která odmítne shell, jejž nikdo nedeklaroval.

Kontrola

majordomus shell check                  # every finding with its remedy; exit 10 on any
majordomus shell check --format json    # the same answer as a document
majordomus shell check --canonical      # put the inventory in canonical order, then check

shell.check je schopnost spustitelného souboru, takže tentýž verdikt se servíruje přes MCP (majordomus_shell_check) i HTTP (GET /api/v1/shell/check). Čte index gitu a prvních pár bajtů každého souboru; nic nebuilduje a nepoužívá síť. V CI je to kontrola shell-inventory jobu structure, vybraná jakoukoli změnou pod spravovaným adresářem, inventářem nebo modulem, který jej posuzuje (.ai/repo/ci/gates.yaml).

Shell jednotka je soubor pod bin/, lib/, scripts/, share/, .githooks/ nebo .claude/hooks/, jehož první řádek jmenuje shell (#!/bin/sh, #!/usr/bin/env bash, #!/usr/bin/env zsh, #!/usr/bin/env -S bash -eu, ...) nebo jehož název končí na .sh. Posuzují se soubory, které by git commitnul — sledované soubory a nesledované soubory, které žádné pravidlo ignorování nevylučuje — takže nový skript je odmítnut dřív, než je přidán. Symbolický odkaz není jednotka; jednotkou je to, na co ukazuje, pokud to leží tam.

test/ není řízeno. Každý behaviorální případ je podle kontraktu runneru shellový skript, takže jejich zamítnutí by zamítlo každý nový test, dokud se nepohne samotný harness; harness je místo toho jedním záznamem inventáře.

kód	odmítnuto, když
`shell.undeclared`	shellová jednotka nemá záznam, nebo její záznam nenese výjimku
`shell.stale`	záznam jmenuje jednotku, kterou strom už nemá
`shell.missing_field`	záznam nemá `disposition` ani `reason`, nebo výjimka nemá `why` ani `removal`
`shell.invalid_disposition`	dispozice není jedna z A-F
`shell.exemption_not_shell`	výjimka je na souboru, který není řízenou shellovou jednotkou, nebo na kotvě
`shell.invalid_unit`	jednotka je absolutní, vylézá ze stromu, nebo je pod `.ai/local/`
`shell.duplicate`	dva záznamy sdílejí jednotku a kotvu
`shell.out_of_order`	záznamy nejsou v kanonickém pořadí
`shell.malformed`	řádek není záznam (včetně neznámého pole)

Kód 0 je čisto, 10 je nález, 12 je strom, který nešlo změřit — což není úspěch.

Inventář

.ai/repo/automation/inventory.jsonl drží jeden JSON objekt na řádek: každou jednotku automatizace, kterou audit migrace našel — shell soubory, ale také awk, jq a JavaScript, které volají, shell vložený ve workflow, receptech a hookách a místa, kde executable spouští shell. Záznam je:

{"unit":"scripts/ci/order-check","disposition":"A","reason":"…","exemption":{"why":"…","removal":"…"},"facts":{"purpose":"…","callers":["…"]}}

pole	platí
`unit`	cesta, relativní ke kořeni repozitáře
`anchor`	volitelné: místo uvnitř jednotky (`deploy :: publish`, `recipe build`) pro vložený shell
`disposition`	`A` základní schopnost → typovaná schopnost; `B` orchestrace → skriptovaná schopnost; `C` bootstrapové lepidlo; `D` mrtvé; `E` generované; `F` adaptér platformy
`reason`	proč právě toto rozhodnutí
`exemption`	vyžadováno u řízeného souboru shellu, jinde odmítnuto: dnes se vyžaduje shell `why` a podmínka `removal`
`facts`	popisná fakta auditu; nesená a nikdy nesouzená

Nic mechanického se nezaznamenává. Počet řádků nebo interpret zapsaný do souboru by po další úpravě zastaral, aniž by to cokoli říkalo; kontrola odvozuje obojí ze stromu. Soupis a seznam výjimek jsou záměrně jeden soubor: dispozice shellové jednotky se zapisuje jednou a druhý seznam výjimek vedle soupisu by byla opakovaná definice, kterou ADR 0004 označuje za vadu.

Přidání shellu

Nejprve ne. Nová automatizace repozitáře je typovaná schopnost executable (docs/CAPABILITIES.md), když něco rozhoduje, nebo skriptovaná schopnost, když orchestruje schopnosti. Když je shell opravdu nutný — hook, který poskytovatel volá dřív, než executable existuje, instalátor spuštěný jako curl | sh — přidejte záznam s dispozicí, důvodem a výjimkou a spusťte majordomus shell check --canonical, aby se zavedl. Výjimka se čte při review; je to celý argument pro soubor.

Migrace jednotky ven

Přesuňte chování: typovanou schopnost pro A, skriptovanou schopnost pro B.
Přesměrujte každého volajícího, kterého jmenuje facts.callers záznamu, na náhradu a zkontrolujte strom, zda neobsahuje ty, které audit minul.
Smažte soubor i jeho záznam v téže změně. Smazání samotného souboru kontrolu neprojde jako shell.stale; to je ratchet a on brání tomu, aby seznam přežil jednotky, které popisuje.

Jednotka, která přestane být shellem, aniž by byla smazána — přepsaná na místě jako něco jiného — si ponechá záznam pro historii migrace, ale ztratí výjimku, kterou kontrola jinak odmítne jako shell.exemption_not_shell.