kimal3 0.1.6 → 0.2.1

package/dist/kontext-stand.js

@@ -0,0 +1,870 @@
+import { createHash } from "node:crypto";
+/*
+  Die reine Rechnung hinter `kimal3 kontext runter` -- und die einzige Stelle,
+  an der Server und CLI sich einig sein muessen.
+
+  🔁 WARUM SIE IN `cli/src/` WOHNT UND NICHT IN `src/lib/arbeitsplatz/`:
+  Beide Seiten brauchen sie. Der Server schreibt den Merkzettel beim Ausliefern,
+  die CLI rechnet die Pruefsummen auf der Platte des Kunden nach. Die CLI kann
+  aber nichts aus `src/` importieren -- eigenes Paket, eigenes tsconfig. An der
+  anderen Stelle entstuende also zwangslaeufig eine zweite Kopie, und dann
+  hiesse derselbe Ordner je nach Weg "geaendert" oder "unveraendert".
+  Dasselbe Muster wie bei `werkbank-name.ts`, aus demselben Grund.
+
+  ⚠️ DIESE DATEI IMPORTIERT NUR `node:crypto`. Kommt hier je ein Import aus
+  `./api.js` oder `./anmeldung.js` hinzu, ist sie aus der App nicht mehr lesbar
+  -- und die zweite Kopie ist wieder da.
+*/
+/**
+ * Die Dateien, die der Firma gehoeren und von `kimal3 kontext runter`
+ * nachgezogen werden -- die fuenf Fragedateien in `kontext/` und die
+ * Firmen-`CLAUDE.md`.
+ *
+ * 🔑 `CLAUDE.md` ist bewusst dabei (Spec §7c): Aendert die Firma ihre drei
+ * Saetze, erreichten sie einen bestehenden Ordner sonst NIE. Und der
+ * Nebengewinn ist groesser als der Anlass -- Verbesserungen an unserer eigenen
+ * Vorlage erreichen damit auch Ordner, die laengst beim Kunden liegen.
+ *
+ * 🔴 **`kontext/kurzprofil.md` steht seit Ruling K-24 (Task 7) hier -- und ohne
+ * sie war ein Satz unwahr, den wir bereits an Kunden ausliefern.** Die Datei
+ * wurde beim ERSTEN Ausliefern gefuellt, ein spaeteres `kimal3 kontext runter`
+ * frischte sie aber nie auf. Wer die drei Saetze in der App aenderte und danach
+ * den Ordner abglich, bekam still den alten Stand -- waehrend die Datei selbst
+ * ihm zusicherte, sie werde „zentral in der App gepflegt". *Ein Abgleich, der
+ * eine Datei auslaesst, meldet trotzdem Erfolg.*
+ *
+ * ⚠️ Ein Merkzettel, der VOR dieser Aenderung geschrieben wurde, fuehrt fuenf
+ * Eintraege bei sechs verwalteten Dateien. Der fehlende Eintrag ist KEIN
+ * Konflikt: `lageFuerDatei` liest `eintrag: null` als "wir wissen nichts" und
+ * sichert, bevor sie ueberschreibt (s. dort). Ist die lokale Datei ohnehin
+ * unveraendert, greift die Abkuerzung ganz oben und es passiert gar nichts.
+ *
+ * ⛔ Die Werkbank-`CLAUDE.md` steht NICHT hier. Sie traegt einen Namen im
+ * Ordner und gehoert einem Menschen (Spec §4).
+ */
+/**
+ * Die oberste `CLAUDE.md` des Firmen-Ordners -- die einzige verwaltete Datei,
+ * die den Firmennamen im Klartext traegt (seit A-11) UND den Weg zum zweiten
+ * Menschen mitgeht (sie steht in der Positiv-Liste der `.gitignore`).
+ * Deshalb ist sie das Erkennungszeichen in `firmennameAusClaudeMd`.
+ *
+ * ⚠️ Sie ist zugleich der erste Eintrag von `VERWALTETE_DATEIEN` darunter --
+ * dass beide dieselbe Datei meinen, prueft `check:cli`. Dort haengt auch die
+ * Pruefung, dass die ECHTE Vorlage ihre Ueberschrift noch so schreibt, wie
+ * `firmennameAusClaudeMd` sie liest.
+ */
+export const FIRMEN_CLAUDE_MD = "CLAUDE.md";
+export const VERWALTETE_DATEIEN = [
+    "CLAUDE.md",
+    "kontext/kurzprofil.md",
+    "kontext/firma.md",
+    "kontext/marke.md",
+    "kontext/systeme.md",
+    "kontext/sicherheit.md",
+];
+/**
+ * Die FUENF Texte, die eine Firma selbst pflegt -- welche Datei welches Feld
+ * der App fuellt, wie sie dort heisst, und woran man sie wiedererkennt.
+ *
+ * 🔑 **Warum es diese Tabelle gibt.** `kimal3 kontext hoch` muss jede Datei dem
+ * Feld zuordnen, das `/api/cli/kontext` (POST) erwartet. Bis Task 7 leitete
+ * eine Funktion den Feldnamen aus dem Dateinamen ab (`marke.md` -> `marke_md`)
+ * -- fuer vier Dateien richtig und fuer die fuenfte falsch: `kurzprofil.md`
+ * fuellt `drei_saetze`. Eine Ableitung, die einen Sonderfall braucht, ist
+ * keine Ableitung mehr, sondern eine Tabelle mit einem Loch.
+ *
+ * 🔴 **Sie ist NICHT der Fragenkatalog.** Hier stehen fuenf Dateinamen, fuenf
+ * Feldnamen, fuenf Anzeigenamen und fuenf Praefixe -- kein einziger Fragetext.
+ * Die 17 Fragen wohnen genau einmal, in `arbeitsplatz/vorlage/`, und erreichen
+ * die CLI ueber die ausgelieferte Datei selbst (s. `fragen-lesen.ts`).
+ *
+ * ⚠️ **`titel` ist ANZEIGETEXT und traegt deshalb echte Umlaute** -- ein Mensch
+ * liest ihn im Abbruch von `kontext hoch` („Diese Datei sieht nicht aus wie
+ * …"). Die ASCII-Umschrift dieser Datei gilt nur fuer Kommentare.
+ *
+ * 🔴 **`ankerPraefix` ist keine Verabredung, sondern eine gemessene Zusage.**
+ * `check:kontext` haelt jeden Anker aus `FRAGEN` (der App) gegen den Praefix
+ * seiner Datei und prueft ausserdem, dass kein Praefix im Anfang eines anderen
+ * steckt. Wer eine 18. Frage `firma_neu` in `marke.md` schreibt, wird dort rot
+ * -- nicht erst beim Kunden, dem `kontext hoch` seine Marke verweigert.
+ *
+ * ⚠️ **`FELDER` (`src/app/firma/kontext-felder.ts`) fuehrt dieselben fuenf
+ * Zuordnungen.** Die App darf diese Datei lesen, die CLI aber nicht die
+ * App -- deshalb steht die Tabelle hier und die Uebereinstimmung ist eine
+ * Pruefung in `check:kontext`, keine Hoffnung.
+ */
+export const FIRMEN_TEXTE = [
+    { pfad: "kontext/kurzprofil.md", feld: "drei_saetze", titel: "Die Firma in drei Sätzen", ankerPraefix: "kurz_" },
+    { pfad: "kontext/firma.md", feld: "firma_md", titel: "Die Firma", ankerPraefix: "firma_" },
+    { pfad: "kontext/marke.md", feld: "marke_md", titel: "Die Marke", ankerPraefix: "marke_" },
+    { pfad: "kontext/systeme.md", feld: "systeme_md", titel: "Die Systeme", ankerPraefix: "systeme_" },
+    { pfad: "kontext/sicherheit.md", feld: "sicherheit_md", titel: "Sicherheit", ankerPraefix: "sicher_" },
+];
+/**
+ * Der Merkzettel liegt im WURZELVERZEICHNIS des Arbeitsplatzes, eine Ebene
+ * ueber `kontext/`.
+ *
+ * ⚠️ Das ist kein Schoenheitsfehler: Er fuehrt alle verwalteten Dateien, und
+ * eine davon -- die Firmen-`CLAUDE.md` -- liegt gar nicht in `kontext/`. Ein
+ * Merkzettel in `kontext/`, der eine Datei ausserhalb verwaltet, waere die Sorte
+ * stiller Falschaussage, die niemand bemerkt, bis sie schadet.
+ */
+export const MERKZETTEL_PFAD = ".kimal3-stand.json";
+/** Wo die Sicherungen hinkommen. Siehe die Frage am Kopf des Bauplans. */
+export const SICHERUNG_BASIS = "kontext";
+/**
+ * Der Stand einer Firma, die nichts gepflegt hat.
+ *
+ * 🔴 Ohne diesen Wert saehe JEDE frische Installation aus wie "lokal
+ * geaendert" -- und das ist der haeufigste Fall ueberhaupt.
+ */
+export const LEER = "leer";
+/**
+ * Die aktuelle Fassung des MERKZETTEL-FORMATS selbst (Task 2, Spec US-B4) --
+ * NICHT die Fassung eines einzelnen Vordrucks (das ist `MerkEintrag.vorlage`).
+ * Sie steht hier als eigene, benannte Zahl, damit ein kuenftiger Umbau des
+ * Merkzettel-AUFBAUS (nicht seines Inhalts) einen Ankerpunkt hat, an dem er
+ * unterscheiden kann, was er vor sich hat.
+ */
+export const FORMAT_AKTUELL = 1;
+/** Der leere Merkzettel -- weder Datei-Eintraege noch eine bekannte Firma. */
+const LEERER_MERKZETTEL = { firma_id: null, dateien: {} };
+/**
+ * Den Firmennamen aus der obersten `CLAUDE.md` lesen -- ihre erste Zeile
+ * lautet `# CLAUDE.md — <Firma> · KI-Arbeitsplatz`.
+ *
+ * 🔴 **Warum es diese zweite Quelle ueberhaupt braucht** (Befund 2 der DRITTEN
+ * Review-Runde, 2026-08-27, und er trifft die Reparatur der zweiten):
+ * `firmenAbgleich` verglich zuerst nur die IDs aus den Merkzetteln. Der
+ * Merkzettel steht aber in der `.gitignore` der Firmenvorlage -- bewusst, er
+ * ist Maschinenzustand. **Genau der Fall, fuer den die Wache gebaut wurde, hat
+ * ihn deshalb nie:** Wer den Firmenordner als Kopie oder ueber das Repo der
+ * Firma bekommt -- also der zweite Mensch, fuer den `werkbank neu` da ist --
+ * hat kein `.kimal3-stand.json`. `firma_id` war `null`, die Antwort lautete
+ * `unbekannt`, und die Wache liess durch.
+ * *Eine Wache, die ihr Erkennungszeichen aus einer Datei liest, die den Weg
+ * zum Kunden gar nicht mitgeht, leuchtet fuer immer gruen.*
+ *
+ * 🔑 Die `CLAUDE.md` geht den Weg mit: Sie steht ausdruecklich in der
+ * Positiv-Liste der `.gitignore` (`!/CLAUDE.md`), und seit A-11 traegt sie den
+ * echten Firmennamen statt eines Platzhalters.
+ *
+ * ⚠️ Ein unersetzter `[FIRMA]`-Platzhalter zaehlt als **kein** Name: Er steht
+ * genau dann da, wenn der Server die Firma nicht kannte -- also im
+ * Vordruck-Fall, in dem es nichts zu vergleichen gibt.
+ */
+export function firmennameAusClaudeMd(inhalt) {
+    if (inhalt === null)
+        return null;
+    const treffer = /^#\s*CLAUDE\.md\s*—\s*(.+?)\s*·\s*KI-Arbeitsplatz\s*$/m.exec(inhalt);
+    if (treffer === null)
+        return null;
+    const name = treffer[1].trim();
+    return name === "" || name === "[FIRMA]" ? null : name;
+}
+/**
+ * 🔑 **ZWEI Erkennungszeichen, in dieser Reihenfolge -- die ID schlaegt den
+ * Namen.** Zwei Firmen duerfen gleich heissen (dafuer gibt es `--firma-id`),
+ * aber nie dieselbe ID haben. Wo beide Seiten eine ID kennen, ist die Antwort
+ * also sicher; der Name ist der Rueckfall fuer den geklonten Ordner, der
+ * keinen Merkzettel hat.
+ *
+ * ⚠️ **Der Name ist die schwaechere Auskunft und wird nur gefragt, wenn die
+ * ID schweigt** -- nicht zusaetzlich. Sonst widersprechen sich zwei Quellen
+ * bei zwei gleichnamigen Firmen, und die staerkere verloere.
+ */
+export function firmenAbgleich(lokal, geliefert) {
+    if (lokal.id !== null && geliefert.id !== null) {
+        return lokal.id === geliefert.id ? { art: "passt" } : { art: "andere-firma" };
+    }
+    if (lokal.name !== null && geliefert.name !== null) {
+        if (lokal.name === geliefert.name)
+            return { art: "passt" };
+        /*
+          🔴 **EIN VERSCHIEDENER NAME IST EIN VERDACHT, KEIN BEWEIS** (Befund 1
+          der vierten Review-Runde, 2026-08-27 -- und er trifft die Reparatur der
+          dritten).
+    
+          Die `CLAUDE.md` ist ausdruecklich eine Datei, die der Kunde AENDERN
+          darf: `kontext runter` sagt ihm woertlich „Ich fasse nichts an -- du
+          hast lokal geaendert". Schreibt eine Admin in die erste Zeile den vollen
+          Firmennamen („Nordwind Handel GmbH"), waehrend die App noch „Nordwind"
+          fuehrt, und legt den Ordner ins Firmen-Repo, dann liest ihr Kollege beim
+          Klonen einen Namen, der nicht zum gelieferten passt.
+    
+          Mit `andere-firma` waere er damit HART GESPERRT worden -- mit einem Satz,
+          der falsch ist („eine andere Firma") und keinen gangbaren Ausweg nennt.
+          *Und gesperrt worden waere genau der Mensch, fuer den `werkbank neu`
+          ueberhaupt gebaut ist.*
+    
+          🔑 Deshalb `zweifel`: Der Name ist das SCHWAECHERE Erkennungszeichen und
+          bekommt die schwaechere Folge. Sperren darf nur, was sicher ist -- die
+          ID. *Wer auf einen Verdacht hin zusperrt, schadet oefter dem Unschuldigen
+          als dem Fall, den er treffen wollte.*
+        */
+        return { art: "zweifel", hier: lokal.name, gewaehlt: geliefert.name };
+    }
+    return { art: "unbekannt" };
+}
+/**
+ * Kurz-Pruefsumme des Inhalts. Zwoelf Hexzeichen aus SHA-256.
+ *
+ * 🔑 Warum gekuerzt: Der Merkzettel wird von Menschen aufgemacht, wenn etwas
+ * schiefgeht. Sechzig Zeichen pro Zeile machen ihn unlesbar, und 48 Bit reichen
+ * fuer eine Handvoll Dateien um Groessenordnungen.
+ *
+ * ⚠️ Der Text wird NICHT normalisiert -- kein `trim`, keine Zeilenenden-
+ * Angleichung. Ein Leerzeichen am Zeilenende IST eine Aenderung; wer sie
+ * wegrechnet, ueberschreibt eines Tages die Arbeit eines Menschen und meldet
+ * dabei "unveraendert".
+ */
+export function pruefsumme(inhalt) {
+    return createHash("sha256").update(inhalt, "utf8").digest("hex").slice(0, 12);
+}
+/**
+ * Ist `wert` sicher genug fuer einen HTTP-Kopf -- druckbares ASCII, keine
+ * Steuerzeichen? (Task 10, Fix-Runde 1, Fund 1.)
+ *
+ * 🔴 DER MERKZETTEL IST EINE DATEI, DIE EIN MENSCH VON HAND OEFFNEN UND
+ * BEARBEITEN KANN -- das ist ausdruecklich ihr Zweck (s. Kopf-Kommentar oben:
+ * "wird von Menschen aufgemacht, wenn etwas schiefgeht"). `leseMerkzettel`
+ * prueft `firma_id` und jeden `stand` nur auf `typeof === "string"`, NIE auf
+ * den Inhalt. Ein einziges Nicht-ASCII-Zeichen darin -- von Hand eingetippt,
+ * aus einem anderen Editor hereinkopiert -- reicht, damit `headers.set(...)`
+ * in `ruf()` (`api.ts`) WIRFT ("Cannot convert argument to a ByteString"),
+ * und zwar fuer JEDEN folgenden CLI-Befehl, nicht nur fuer `kontext`-Befehle.
+ * Der Kunde saehe "kimal3 ist gerade nicht erreichbar" und suchte den Fehler
+ * im Netz, waehrend er auf seiner eigenen Platte sitzt.
+ *
+ * ⚠️ ECHTES DRUCKBARES ASCII (0x20-0x7E), NICHT NUR "unter 256": Der
+ * ByteString-Fehler selbst kippt erst jenseits von Codepunkt 255 -- aber
+ * dieselbe Grenze wuerde "ä" (0xE4 = 228) noch durchlassen, und CLAUDE.md
+ * zieht sie bewusst enger ("ein Kopf traegt kein ... ä"). Druckbares ASCII
+ * ist ausserdem die einzige Menge, die auch Steuerzeichen (Zeilenumbrueche,
+ * Tabs) ausschliesst -- die in einem HTTP-Kopf ohnehin nichts verloren haben.
+ */
+export function istKopfwertSicher(wert) {
+    return /^[\x20-\x7E]*$/.test(wert);
+}
+/**
+ * Den Merkzettel aus dem rohen Dateiinhalt lesen. Wirft nie.
+ *
+ * 🔴 Ein Eintrag ohne BEIDE Felder faellt raus. Ohne diese Bedingung truege
+ * `eintrag.pruef` spaeter `undefined`, und `undefined !== summe` ist wahr --
+ * also hielte die Rechnung jede Datei fuer lokal geaendert und legte bei jedem
+ * Lauf eine neue Sicherung an.
+ *
+ * 🔴 **ZWEI FORMATE, ABSICHTLICH (Task 10a).** Vor dieser Aufgabe war ein
+ * Merkzettel eine FLACHE Zuordnung Pfad -> Eintrag, ohne eigenes Feld fuer die
+ * Firma -- und genau solche Dateien liegen schon auf Platten von heute
+ * Nachmittag, geschrieben vom Ausliefer-Weg, bevor es diese Aufgabe gab. Das
+ * neue Format erkennt sich an einem eigenen `dateien`-Feld (Objekt, keine
+ * Liste); fehlt es, wird das GANZE Objekt wie bisher als flache
+ * Pfad-Zuordnung gelesen und `firma_id` bleibt `null`. *Ein Werkzeug, das an
+ * seiner eigenen aelteren Datei abstuerzt, ist schlimmer als eines, das sie
+ * ignoriert.*
+ *
+ * 🔴 **TASK 2, US-B4: `format` UND `vorlage` WERDEN NUR UEBERNOMMEN, NIE
+ * ERFUNDEN.** Beide Felder sind auf ihrem Typ optional (s. dort) -- ein
+ * Merkzettel von VOR dieser Aufgabe hat sie nicht, und das ist die "alte
+ * Fassung" aus dem Acceptance-Kriterium, kein Fehler. Steht `format` nicht
+ * oder nicht als Zahl im Objekt, bleibt es im Ergebnis schlicht weg; dasselbe
+ * gilt je Eintrag fuer `vorlage`. Ein Wert, der nicht im Text stand, wird hier
+ * nicht geraten -- das waere genau die Sorte stiller Falschaussage, die
+ * anderswo in dieser Datei schon einmal Schaden angerichtet hat (s.
+ * `bekannterStandAus`).
+ */
+export function leseMerkzettel(roh) {
+    if (roh === null)
+        return LEERER_MERKZETTEL;
+    try {
+        const daten = JSON.parse(roh);
+        if (!daten || typeof daten !== "object" || Array.isArray(daten))
+            return LEERER_MERKZETTEL;
+        const objekt = daten;
+        const hatNeueForm = "dateien" in objekt &&
+            typeof objekt.dateien === "object" &&
+            objekt.dateien !== null &&
+            !Array.isArray(objekt.dateien);
+        const dateienRoh = (hatNeueForm ? objekt.dateien : objekt);
+        const firmenIdRoh = hatNeueForm ? objekt.firma_id : undefined;
+        const formatRoh = hatNeueForm ? objekt.format : undefined;
+        const dateien = {};
+        for (const [pfad, wert] of Object.entries(dateienRoh)) {
+            if (!wert || typeof wert !== "object")
+                continue;
+            const e = wert;
+            if (typeof e.stand !== "string" || typeof e.pruef !== "string")
+                continue;
+            const eintrag = { stand: e.stand, pruef: e.pruef };
+            if (typeof e.vorlage === "string")
+                eintrag.vorlage = e.vorlage;
+            dateien[pfad] = eintrag;
+        }
+        // 🔑 `format` steht per Spread VOR `firma_id`, wenn es da ist -- dieselbe
+        // Feldreihenfolge wie bei `alsMerkzettel` und `baueMerkzettel`. Reine
+        // Kosmetik fuer Menschen, die die Datei aufmachen -- aber genau deshalb
+        // WICHTIG fuer `check-kontext.mts`: Die dortige Pruefung vergleicht per
+        // `JSON.stringify`, und das ist reihenfolge-empfindlich.
+        return {
+            ...(typeof formatRoh === "number" ? { format: formatRoh } : {}),
+            firma_id: typeof firmenIdRoh === "string" ? firmenIdRoh : null,
+            dateien,
+        };
+    }
+    catch {
+        return LEERER_MERKZETTEL;
+    }
+}
+/** Der Merkzettel als Dateiinhalt -- eingerueckt, weil ihn Menschen aufmachen. */
+export function schreibeMerkzettel(m) {
+    return `${JSON.stringify(m, null, 2)}\n`;
+}
+/**
+ * Prueft, ob `wert` (aus einer bereits geparsten JSON-ANTWORT der App) ein
+ * gueltiger Merkzettel ist -- die Form-Pruefung, die `kontext-runter.ts` und
+ * `kontext-hoch.ts` sonst je einmal von Hand nachbauen wuerden (Task 10a).
+ *
+ * ⚠️ ANDERS STRENG ALS `leseMerkzettel`: Die App liefert ab dieser Aufgabe
+ * IMMER das neue Format (`dateien` + `firma_id`) -- Stufe 2 ist nicht
+ * veroeffentlicht, es gibt also keine Antwort einer AELTEREN Version, gegen
+ * die sich diese Funktion abfedern muesste. Nur das neue Format wird
+ * akzeptiert; alles andere ist `null` ("nicht lesbar"), nicht "leer geraten".
+ *
+ * 🔴 TASK 2: Aus demselben Grund werden jetzt AUCH `format` und je Eintrag
+ * `vorlage` verlangt. `baueMerkzettel` (unten) setzt beide seit dieser
+ * Aufgabe IMMER -- jede Antwort, die durch diese Rechnung entstanden ist,
+ * traegt sie also. Fehlt eines trotzdem, ist das keine aeltere Version,
+ * sondern eine kaputte Antwort -- `null`, nicht geraten.
+ */
+export function alsMerkzettel(wert) {
+    if (!wert || typeof wert !== "object" || Array.isArray(wert))
+        return null;
+    const objekt = wert;
+    if (typeof objekt.format !== "number")
+        return null;
+    const dateienRoh = objekt.dateien;
+    if (!dateienRoh || typeof dateienRoh !== "object" || Array.isArray(dateienRoh))
+        return null;
+    const firmenIdRoh = objekt.firma_id;
+    if (firmenIdRoh !== null && typeof firmenIdRoh !== "string")
+        return null;
+    const dateien = {};
+    for (const [pfad, eintragRoh] of Object.entries(dateienRoh)) {
+        if (!eintragRoh || typeof eintragRoh !== "object")
+            continue;
+        const e = eintragRoh;
+        if (typeof e.stand !== "string" || typeof e.pruef !== "string" || typeof e.vorlage !== "string")
+            continue;
+        dateien[pfad] = { stand: e.stand, pruef: e.pruef, vorlage: e.vorlage };
+    }
+    return { format: objekt.format, firma_id: firmenIdRoh, dateien };
+}
+/**
+ * Der lokal bekannte Firmenstand aus einem Merkzettel als EINE Zeichenkette --
+ * **Fix-Runde 1, Review-Fund 1 (Important)**, hierher gezogen fuer Task 10.
+ *
+ * 🔴 **URSPRUENGLICHER FEHLER (bei `kontext hoch`):** Eine Rechnung, die nur
+ * die VIER `kontext/*.md`-Eintraege des Merkzettels ansah, uebersah, dass
+ * `CLAUDE.md` den Stand des FUeNFTEN Feldes traegt, `drei_saetze` (s.
+ * `setzeKontextEin` in `ausliefern.ts`). Eine Firma, die bisher NUR die drei
+ * Saetze ueber das Formular auf `/firma` gepflegt hat -- ein ganz normaler
+ * erster Schritt --, hatte deshalb alle vier `kontext/*.md`-Eintraege auf
+ * `LEER`, waehrend der Server einen echten Stand fuehrte.
+ *
+ * 🔑 **WARUM „DER EINE NICHT-LEERE STAND GEWINNT" RICHTIG IST:** Die
+ * Firmenzeile traegt GENAU EIN `geaendert_am` fuer alle fuenf Felder. Jede
+ * Lieferung stempelt dieses EINE `zeitpunkt` auf jedes gepflegte Feld und
+ * `LEER` auf jedes ungepflegte -- es gibt also nie zwei verschiedene,
+ * gleichzeitig gueltige NICHT-leere Staende in einer einzigen Lieferung.
+ *
+ * ⚠️ **TROTZDEM, DIE GEGENPROBE:** Der Merkzettel ist eine Datei auf der
+ * Platte des Kunden, keine Datenbank mit Integritaetsregel. Findet diese
+ * Funktion mehr als einen unterschiedlichen nicht-leeren Stand, liefert sie
+ * `LEER` -- derselbe Wert wie "noch nie heruntergeladen". Sie RAET nicht,
+ * welcher stimmt.
+ *
+ * 🔁 **Task 10:** Wohnte bis hierher in `befehle/kontext-hoch.ts` und wird
+ * jetzt auch von `api.ts` gebraucht (fuer den Kopf `X-Kimal3-Kontext-Stand`).
+ * `kontext-hoch.ts` importiert `ruf` aus `./api.js` -- ein Umzug hierher, in
+ * die Datei ohne jeden Import ausser `node:crypto`, ist der einzige Weg, der
+ * `api.ts` nicht in einen Kreisimport mit sich selbst zwingt.
+ */
+export function bekannterStandAus(merkzettel) {
+    const staende = new Set();
+    for (const pfad of VERWALTETE_DATEIEN) {
+        const stand = merkzettel.dateien[pfad]?.stand;
+        if (stand !== undefined && stand !== LEER)
+            staende.add(stand);
+    }
+    if (staende.size === 1) {
+        const [einziger] = staende;
+        return einziger;
+    }
+    return LEER;
+}
+/**
+ * Der Merkzettel zu einer Lieferung.
+ *
+ * 🔴 ER ENTSTEHT MIT DEM INHALT, NICHT DANACH. Wer ihn spaeter schreibt, baut
+ * denselben Fehler wie Runde 5 des Update-Kanals: Der Stempel stand am Ende und
+ * behauptete taeglich, der Skill sei veraltet.
+ *
+ * ⚠️ `staende` nennt je Datei den Stand der FIRMA (`geaendert_am`) oder `leer`.
+ * Fehlt eine verwaltete Datei in der Lieferung, entsteht kein Eintrag -- ein
+ * Eintrag mit `undefined` waere schlimmer als keiner.
+ *
+ * 🔴 `firmenId` ist ABSICHTLICH PFLICHT, nicht optional (Task 10a). Ohne die
+ * ID muesste der Server spaeter raten, welche Firma gemeint ist -- wer zu
+ * ZWEI Firmen gehoert, staende im Ordner von A und laese "B hat etwas
+ * geaendert". `null` ist ein gueltiger, ausdruecklicher Wert ("keine
+ * eindeutige Firma bekannt", z. B. beim Vordruck ohne Kontext) -- ein
+ * vergessenes Argument ist das nicht: Wer diese Funktion aufruft, muss sich
+ * entscheiden, nicht stillschweigend `null` bekommen.
+ *
+ * 🔴 TASK 2: `vorlagenPruefsummen` traegt je Datei den Fingerabdruck UNSERER
+ * VORLAGE -- nicht den des ausgelieferten Inhalts (das ist `pruef`). Fehlt
+ * eine Pruefsumme fuer eine Datei, traegt ihr `vorlage`-Feld `LEER` --
+ * derselbe Sicherheitswert wie beim ungepflegten `stand` zwei Zeilen weiter
+ * unten, aus demselben Grund: *wer nichts weiss, behauptet nichts.*
+ *
+ * 🔴 **PUNKT A-1 (2026-08-26): DIESES ARGUMENT IST JETZT PFLICHT.** Es war
+ * optional, mit Default `{}` -- und genau deshalb hat es ein halbes Jahr lang
+ * niemand uebergeben. `ausliefern.ts` rief die Funktion mit drei Werten auf,
+ * jeder ausgelieferte Merkzettel trug bei allen sechs Dateien
+ * `"vorlage": "leer"`, und die Lage `vorlage-neuer` unten konnte in der
+ * Wirklichkeit nie entstehen: *keine fehlende Zeile, kein Compiler-Fehler,
+ * kein roter Waechter.* Ein Pflicht-Argument ist die einzige Absicherung, die
+ * auch den erwischt, der diesen Kommentar nie liest.
+ *
+ * 🔑 `format` wird HIER, beim NEU-Bauen einer Lieferung, immer gesetzt --
+ * anders als beim blossen LESEN einer womoeglich alten Datei
+ * (`leseMerkzettel` oben). Jede Lieferung, die durch diese Funktion entsteht,
+ * ist per Definition die aktuelle Fassung.
+ */
+export function baueMerkzettel(dateien, staende, firmenId, vorlagenPruefsummen) {
+    const raus = {};
+    for (const pfad of VERWALTETE_DATEIEN) {
+        const datei = dateien.find((d) => d.pfad === pfad);
+        if (!datei)
+            continue;
+        raus[pfad] = {
+            stand: staende[pfad] ?? LEER,
+            pruef: pruefsumme(datei.inhalt),
+            vorlage: vorlagenPruefsummen[pfad] ?? LEER,
+        };
+    }
+    return { format: FORMAT_AKTUELL, firma_id: firmenId, dateien: raus };
+}
+/**
+ * Der Merkzettel, den `kimal3 kontext hoch` nach einem gelungenen Lauf auf die
+ * Platte schreibt.
+ *
+ * 🔴 **DER FUND, DEN DIE KUNDENSTRECKE AM 2026-08-25 GEFUNDEN HAT.** Vorher
+ * wurde die Antwort des Servers eins zu eins hingeschrieben. Der Merkzettel ist
+ * aber eine Aussage darueber, WAS AUF DER PLATTE LIEGT -- und `kontext hoch`
+ * schreibt keine einzige Datei. Fuer die fuenf gesendeten Texte geht das
+ * trotzdem auf: Was der Server zurueckgibt, entsteht aus dem, was die CLI ihm
+ * gerade geschickt hat, und dasselbe steht auf der Platte.
+ *
+ * ⚠️ **Fuer die Firmen-`CLAUDE.md` geht es NICHT auf, seit Ruling K-6.** Sie
+ * wird nicht mehr gesendet, aber der Server BAUT sie neu (er setzt die frischen
+ * drei Saetze ein). Die Pruefsumme in seiner Antwort gehoert damit zu einem
+ * Text, den niemand auf die Platte geschrieben hat.
+ *
+ * 🔴 **Was das anrichtete, gemessen:** Direkt nach einem erfolgreichen
+ * `kontext hoch` meldete `kimal3 kontext runter` „Ich fasse nichts an -- du
+ * hast lokal geaendert: CLAUDE.md" und riet: *„Deine Fassung ist die neuere?
+ * Dann schick sie hoch: kimal3 kontext hoch"* -- ein Rat auf einen Befehl, der
+ * die `CLAUDE.md` gar nicht mehr mitnimmt. Der Admin haette das beliebig oft
+ * wiederholen koennen. *Das ist woertlich die Form von Fund F: ein Befehl
+ * schickt den Menschen zu einem zweiten, der seine Lage nicht aendern kann,
+ * und beide melden Erfolg.*
+ *
+ * 🔑 **Die Regel: Ueber eine Datei, die wir nicht gesendet haben, uebernehmen
+ * wir nichts Neues.** Ihr Eintrag bleibt der lokale von vorher. Der naechste
+ * `kontext runter` sieht dann sauber „Server neuer" -- der Stand weicht ab, die
+ * Pruefsumme passt zur Platte -- und holt die Datei ohne Sicherung. Genau das
+ * soll passieren: Die Firma hat ihre drei Saetze geaendert, also gehoert die
+ * abgeleitete Kopie in der `CLAUDE.md` aufgefrischt.
+ *
+ * ⚠️ Gibt es lokal gar keinen Eintrag, entsteht auch keiner. `null` heisst
+ * „wir wissen nichts" und fuehrt beim naechsten Holen zur Sicherung -- der
+ * sichere Weg, nicht der bequeme.
+ *
+ * 🔑 `format` und `firma_id` kommen weiterhin vom SERVER: Beide sagen nichts
+ * ueber den Inhalt einer Datei, und bei der Firma ist der Server die Wahrheit.
+ */
+export function merkzettelNachHoch(vomServer, lokal, gesendet) {
+    const dateien = {};
+    for (const pfad of VERWALTETE_DATEIEN) {
+        const eintrag = gesendet.includes(pfad) ? vomServer.dateien[pfad] : lokal.dateien[pfad];
+        if (eintrag)
+            dateien[pfad] = eintrag;
+    }
+    return { ...vomServer, dateien };
+}
+/**
+ * Die Entscheidungstabelle aus Spec §7b -- fuer EINE Datei.
+ *
+ * 🔑 DIE ABKUERZUNG STEHT ZUERST, und sie nimmt den haeufigsten Aerger weg: Ist
+ * der lokale Text identisch mit dem, was der Server liefert, lautet die Antwort
+ * "schon aktuell" -- egal was der Merkzettel sagt oder ob es ihn gibt. Wer
+ * frisch klont, hat die Dateien aus dem Repo, aber keinen Merkzettel; ohne diese
+ * Zeile bekaeme er eine sinnlose Sicherung seiner eigenen, unveraenderten Dateien.
+ *
+ * 🔴 "SERVER NEUER" HEISST HIER **ANDERS**, NICHT **SPAETER** (Bauplan D-2). Ein
+ * echter Zeitvergleich haette zwei Uhren und einen Sonderwert (`leer`) zu
+ * bewaeltigen. Weil laut E-4 ohnehin die Firma gewinnt, reicht die Ungleichheit
+ * -- und ein Zurueckrollen in der App erreicht den Kunden damit ebenfalls.
+ *
+ * 🔑 KEIN MERKZETTEL = BEIDES UNBEKANNT = der sichere Fall. Eine Datei ohne
+ * Eintrag kann von Hand angelegt, aus einer alten Fassung kopiert oder muehsam
+ * ausgefuellt worden sein. *Wer nichts weiss, loescht nichts* -- also wird
+ * gesichert, bevor ueberschrieben wird.
+ *
+ * 🔴 **TASK 2 (Spec US-B1/US-B4): DIE FUeNFTE LAGE, `vorlage-neuer`.** Das ist
+ * die Reparatur des schwersten Befundes des ganzen Umbaus: Bis hierher
+ * verglich diese Funktion nur, OB sich der ausgelieferte Text geaendert hat --
+ * nie, WESHALB. Verbessern wir unseren eigenen Vordruck, aendert sich der
+ * ausgelieferte Text bei jeder Firma, die ihn nicht selbst gepflegt hat, genau
+ * so wie bei einer echten Firmen-Aenderung -- und `serverStand` (der Stand DER
+ * FIRMA) bleibt dabei unveraendert `leer`. Ohne die dritte Dimension gab es
+ * daher zwei falsche Wege: Entweder mass die Funktion den Inhalt direkt (dann
+ * riss die Abkuerzung ganz oben nie, und ein reiner Vordruck-Wechsel landete
+ * unter "schon-aktuell" -- die Firma saehe die Verbesserung NIE) oder sie
+ * ignorierte den Vordruck-Stand komplett (dann waere jede Vordruck-Aenderung
+ * unsichtbar). `aktuelleVorlage` traegt deshalb die Pruefsumme des Vordrucks
+ * HEUTE herein; verglichen wird sie gegen `eintrag.vorlage` -- die Pruefsumme
+ * des Vordrucks, aus dem die Datei beim letzten Holen stammte.
+ *
+ * 🔑 DIE PRIORITAET, WENN MEHRERES ZUTRIFFT: Hat die FIRMA inzwischen etwas
+ * gesagt (`serverNeuer`), gewinnt das IMMER -- ob sich der Vordruck ebenfalls
+ * geaendert hat, spielt dann keine Rolle mehr; ihr Text ersetzt ohnehin den
+ * Vordruck. Hat dagegen der KUNDE lokal geaendert (`lokalGeaendert`), zaehlt
+ * eine geaenderte Vorlage genauso als Grund zu sichern wie eine geaenderte
+ * Firmen-Zeile -- in beiden Faellen wuerde ein sang- und klangloses
+ * Ueberschreiben echte Arbeit verlieren, also wird "beides".
+ *
+ * 🔴 **PUNKT A-1 (2026-08-26): `aktuelleVorlage` IST JETZT PFLICHT.** Es war
+ * optional -- mit der Begruendung, das Verdrahten gehoere zu einer spaeteren
+ * Aufgabe. Zurueckgekommen ist danach nie jemand: `kontext-runter.ts` rief
+ * diese Funktion ohne den Wert auf, `vorlage-neuer` konnte in der
+ * Wirklichkeit nicht entstehen, und der Kunde las weiter „Dein Firmenkontext
+ * ist aktuell". *Die Rechnung war gebaut, geprueft, dokumentiert -- und tot.*
+ * Wer den Wert jetzt weglaesst, bekommt einen Kompilierfehler.
+ *
+ * ⚠️ **Ein Merkzettel-Eintrag OHNE `vorlage` gilt als „unbekannt", und
+ * unbekannt zaehlt als GEAeNDERT.** Solche Eintraege liegen echt auf Platten:
+ * Sie stammen von einer Auslieferung, bevor es dieses Feld gab. Der Vergleich
+ * `undefined !== aktuelleVorlage` ist wahr, es entsteht also einmalig
+ * `vorlage-neuer` bzw. `beides` -- dieselbe Antwort wie bei einem fehlenden
+ * Eintrag, aus demselben Grund: *wer nichts weiss, sichert, bevor er
+ * ueberschreibt.* Die Gegenrichtung waere schlimmer: Wuerde „unbekannt" als
+ * „unveraendert" gelesen, bekaeme der Kunde die Verbesserung nicht -- und der
+ * naechste Lauf haette obendrein einen Merkzettel, der den Server-Text
+ * beschreibt, waehrend die alte Datei danebenliegt, und meldete faelschlich
+ * „du hast lokal geaendert".
+ */
+export function lageFuerDatei(a) {
+    if (a.lokalerInhalt === a.serverInhalt)
+        return "schon-aktuell";
+    // Es gibt nichts zu verlieren -- also holen, ohne zu sichern.
+    if (a.lokalerInhalt === null)
+        return "server-neuer";
+    const lokalGeaendert = a.eintrag === null ? true : pruefsumme(a.lokalerInhalt) !== a.eintrag.pruef;
+    const serverNeuer = a.eintrag === null ? true : a.eintrag.stand !== a.serverStand;
+    const vorlageNeuer = a.eintrag === null ? true : a.eintrag.vorlage !== a.aktuelleVorlage;
+    /*
+      🔴 **`vorlageNeuer` zaehlt hier BEWUSST nicht mit** (Review-Befund 1 zu
+      Punkt A-1, 2026-08-26 -- gemessen, nicht vermutet).
+  
+      Hier stand einen Nachmittag lang `serverNeuer || vorlageNeuer`. Die Folge:
+      Wer seine Datei lokal geaendert hatte, um sie spaeter mit `kimal3 kontext
+      hoch` zu schicken, verlor beim naechsten `runter` seinen Arbeitsstand,
+      sobald WIR irgendeine Frage umformuliert hatten -- gesichert zwar, aber
+      aus der Datei verschwunden, und ohne dass er danach gefragt haette.
+      *Eine Verbesserung an unserem Text darf nicht die Arbeit von jemandem
+      wegraeumen, der gerade an seiner sitzt.*
+  
+      🔑 Der richtige Weg ist der, den `lokal-geaendert` ohnehin nennt: erst
+      hochschicken, dann herunterladen. Dann liegen seine Antworten auf dem
+      Server, der Stand aendert sich, und der naechste `runter` bringt seine
+      Antworten UND unsere neuen Fragen -- zusammengefuehrt statt eines gegen
+      das andere. Wer nie hochschickt, behaelt seine Datei; sie gehoert ihm.
+  
+      ⚠️ `vorlage-neuer` unten bleibt davon unberuehrt. Genau dafuer wurde A-1
+      gebaut, und es ist der haeufige Fall: eine Datei, die unangetastet so
+      dasteht, wie wir sie geliefert haben.
+    */
+    if (lokalGeaendert)
+        return serverNeuer ? "beides" : "lokal-geaendert";
+    if (serverNeuer)
+        return "server-neuer";
+    if (vorlageNeuer)
+        return "vorlage-neuer";
+    return "schon-aktuell";
+}
+/**
+ * Dieselbe Entscheidung wie {@link lageFuerDatei} -- aber gefuettert aus den
+ * ZWEI Merkzetteln, zwischen denen `kimal3 kontext runter` steht: dem auf der
+ * Platte und dem aus der Antwort des Servers.
+ *
+ * 🔴 **WARUM ES DIESE FUNKTION GIBT (Punkt A-1, 2026-08-26).** Der eigentliche
+ * Fehler war nicht die Rechnung -- die stimmte. Er war, WOHER ihre Eingaben
+ * kommen: `kontext-runter.ts` gab ihr den Vordruck-Abdruck gar nicht erst mit.
+ * Genau dieser Schritt ("aus welchem der beiden Merkzettel kommt welcher
+ * Wert?") liess sich von keiner Wache sehen, weil er mitten im Befehl wohnte
+ * -- zwischen `fetch` und Dateisystem, wo `check:kontext` nie hinkommt.
+ *
+ * 🔴 **DIE ZUORDNUNG, DIE HIER ABGESICHERT WIRD -- sie ist nicht offensichtlich
+ * und in beide Richtungen falsch machbar:**
+ * - `eintrag` kommt aus dem LOKALEN Merkzettel. Er sagt, was beim letzten
+ *   Holen galt: die eine Seite des Vergleichs.
+ * - `serverStand` UND `aktuelleVorlage` kommen aus dem Merkzettel DES SERVERS.
+ *   Sie sagen, was heute gilt: die andere Seite.
+ *
+ * ⚠️ **Nimmt man beide Seiten aus derselben Datei, vergleicht die Rechnung
+ * eine Zahl mit sich selbst und findet NIE einen Unterschied** -- kein Fehler,
+ * keine Meldung, der Kunde liest „Dein Firmenkontext ist aktuell". Gemessen:
+ * Mit `aktuelleVorlage` aus dem lokalen Merkzettel blieb die verbesserte
+ * Datei liegen, und der naechste Lauf behauptete obendrein „du hast lokal
+ * geaendert". *Das ist derselbe Schaden wie vorher, nur eine Zeile weiter.*
+ *
+ * 🔑 Fehlt die Datei im Merkzettel des Servers, gilt fuer beide Werte `LEER`
+ * -- „wir wissen nichts", derselbe Rueckfall wie ueberall in dieser Datei.
+ */
+export function lageAusMerkzetteln(a) {
+    const vomServer = a.vomServer.dateien[a.pfad] ?? null;
+    return lageFuerDatei({
+        lokalerInhalt: a.lokalerInhalt,
+        serverInhalt: a.serverInhalt,
+        eintrag: a.lokal.dateien[a.pfad] ?? null,
+        serverStand: vomServer?.stand ?? LEER,
+        aktuelleVorlage: vomServer?.vorlage ?? LEER,
+    });
+}
+/** `kontext/vorher-2026-08-21` */
+export function sicherungsOrdner(datum) {
+    return `${SICHERUNG_BASIS}/vorher-${datum}`;
+}
+/**
+ * Wohin die lokale Fassung gesichert wird.
+ *
+ * ⚠️ FLACH, mit dem Basisnamen -- `CLAUDE.md` und `kontext/systeme.md` landen
+ * nebeneinander. Dass sich dabei nichts ueberschreiben kann, sichert der
+ * Waechter: Er prueft, dass alle verwalteten Dateien verschiedene
+ * Basisnamen haben. Eine kuenftige sechste faellt damit auf, bevor sie eine
+ * Sicherung ueberschreibt.
+ */
+export function sicherungsZiel(datum, pfad) {
+    const name = pfad.split("/").pop() ?? pfad;
+    return `${sicherungsOrdner(datum)}/${name}`;
+}
+/**
+ * Von welchem Ordner aus `kimal3 kontext runter` ueberhaupt wissen kann,
+ * welche Firma gemeint ist -- **ohne** das Dateisystem selbst anzufassen.
+ *
+ * 🔑 WARUM DIESE FUNKTION HIER UND NICHT ERST IN EINER SPAETEREN AUFGABE
+ * WOHNT: Diese Datei importiert bewusst nur `node:crypto` (s. Kopf). Die
+ * Fundregel selbst braucht kein Dateisystem -- nur eine Liste von Kandidaten,
+ * die der Aufrufer (spaeter) mit `readdirSync`/`existsSync` gefuellt hat.
+ * Die eigentliche Suche gehoert deshalb woanders hin (zieht Umgebung und
+ * Heimverzeichnis hoch); ein Waechter fuer eine reine Pfadregel soll das
+ * nicht mit auslösen.
+ *
+ * Fundregel: Vom aktuellen Verzeichnis aufwaerts suchen, bis ein Ordner
+ * gefunden ist, der `kontext/` UND `CLAUDE.md` enthaelt.
+ *
+ * 🔴 DER ERSTE TREFFER GEWINNT, NICHT DER OBERSTE. Die Kandidaten kommen von
+ * UNTEN NACH OBEN (aktuelles Verzeichnis zuerst) -- wer in
+ * `Kunden/ARNO/KI-Arbeitsplatz` steht, meint ARNO, nicht `Kunden/`. Wuerde
+ * stattdessen der oberste Treffer gewinnen, faende der Befehl bei jedem
+ * verschachtelten Arbeitsplatz den falschen.
+ *
+ * 🔑 BEIDES MUSS STIMMEN. Ein Ordner mit `kontext/`, aber ohne `CLAUDE.md`,
+ * ist kein Arbeitsplatz -- sonst traefe der Befehl irgendeinen Ordner, in dem
+ * jemand zufaellig etwas "kontext" genannt hat.
+ *
+ * Kein Treffer -> `null`.
+ */
+export function arbeitsplatzAus(kandidaten) {
+    for (const k of kandidaten) {
+        if (k.hatKontext && k.hatClaude)
+            return k.pfad;
+    }
+    return null;
+}
+/*
+  🪦 **Hier wohnten `DREI_SAETZE_UEBERSCHRIFT`, der Typ `DreiSaetzeSchnitt` und
+  `dreiSaetzeAus` -- ersatzlos gestrichen mit Ruling K-6 (Task 7).**
+
+  Was sie taten: Sie schnitten den Abschnitt „Die Firma in drei Saetzen" aus
+  dem Text der Firmen-`CLAUDE.md`, damit `kimal3 kontext hoch` ihn als
+  `drei_saetze` mitschicken konnte. Sie waren die Antwort auf Fund F -- der
+  Befehl liess dieses eine Feld aus und meldete trotzdem einen Haken.
+
+  🔴 **Warum ihr Fall nicht mehr entstehen kann:** Seit Ruling K-18 hat „Die
+  Firma in drei Saetzen" eine EIGENE Datei, `kontext/kurzprofil.md`, und seit
+  Task 6 stehen in der `CLAUDE.md` nur noch die drei ANTWORTEN -- ohne Anker,
+  ohne Ueberschriften. Der Umweg schnitt also ab Task 6 einen Text heraus, den
+  die App nicht mehr als beantwortete Fragen lesen kann: EIN `kontext hoch`
+  haette drei ankerlose Zeilen in die Spalte geschrieben, `alsStand` haette sie
+  als ungepflegt gelesen, und das Formular haette wieder das leere
+  Fragengeruest gezeigt -- mit den Saetzen der Firma unsichtbar dahinter.
+
+  🔑 **Was ihre Aufgabe uebernommen hat:** `kontext/kurzprofil.md` ist seither
+  eine Datei wie die vier anderen. Sie steht in {@link FIRMEN_TEXTE} und wird
+  gelesen, hochgeschickt und nachgezogen wie `marke.md` auch. *Fuenf
+  gleichrangige Dateien, kein Sonderfall, keine Extra-Meldung.*
+
+  ⚠️ Die Ueberschrift steht weiterhin in der Vorlage -- sie ist jetzt aber
+  blosser Fliesstext. Kein Code sucht sie mehr; `ausliefern.ts` setzt die drei
+  Antworten an der Stelle von `EINSETZ_MARKE_DREI_SAETZE` ein, und dass DIESE
+  Marke woertlich in der Vorlage steht, prueft `check:arbeitsplatz`.
+*/
+/**
+ * Die ARTEN von Rat, die es gibt -- **in der Reihenfolge, in der sie im
+ * Terminal stehen.**
+ *
+ * 🔑 Diese Liste ist zugleich die Quelle des Typs {@link RatArt}. Wer eine
+ * dritte Art erfindet, muss sie hier eintragen -- und bekommt danach vom
+ * Compiler gesagt, dass {@link RAT_TEXT} noch keinen Text dafuer hat. *Eine
+ * Reihenfolge, die nebenher den Typ traegt, kann nicht unvollstaendig sein.*
+ *
+ * ⚠️ Die Reihenfolge ist nicht Geschmack: `kimal3 kontext runter` druckt seit
+ * Befund F-3 erst den Rat fuer die Firmen-Texte und darunter den fuer unsere
+ * Vorlage. Wer sie dreht, dreht die Ausgabe beim Kunden.
+ */
+const RAT_REIHENFOLGE = ["hochschickbar", "nicht-hochschickbar"];
+/**
+ * 🔴 **PUNKT A-7 (2026-08-26): DIESE TABELLE IST DIE ABSICHERUNG, NICHT NUR
+ * EINE AUFRAEUMAKTION.**
+ *
+ * Bis hierher zaehlte {@link ratNachUnberuehrt} ihre Faelle auf: ein `if` fuer
+ * „irgendetwas aus {@link FIRMEN_TEXTE}" und ein zweites fuer den woertlichen
+ * Dateinamen `"CLAUDE.md"`. {@link VERWALTETE_DATEIEN} hat aber SECHS
+ * Eintraege, und eine kuenftige SIEBTE waere durch beide `if`s gefallen --
+ * ohne Fehler, ohne Meldung, ohne Rat. *Der Mensch haette gelesen, dass seine
+ * Datei in Ruhe gelassen wurde, und nirgends, was er jetzt tun soll.*
+ *
+ * 🔑 **Warum ein `Record` und keine zweite Liste:** Der Schluesseltyp ist die
+ * Vereinigung aller Pfade aus {@link VERWALTETE_DATEIEN}. Eine siebte Datei
+ * dort weitet ihn -- und dieses Objekt hat dann einen Schluessel zu wenig,
+ * *also uebersetzt die CLI nicht mehr*. Das ist die einzige Absicherung, die
+ * auch den erwischt, der diesen Kommentar nie liest.
+ *
+ * ⚠️ **Warum die Zuordnung nicht IN {@link VERWALTETE_DATEIEN} steht**, wo sie
+ * inhaltlich hingehoerte: Diese Liste ist an sechs Stellen ausserhalb dieser
+ * Datei eine reine Pfadliste (`ausliefern.ts`, `route.ts`,
+ * `kontext-runter.ts`, `kontext-dateien.ts`, zwei Waechter). Aus ihr eine
+ * Liste von Objekten zu machen, haette all das angefasst -- fuer denselben
+ * Schutz, den der `Record` hier ohne einen einzigen fremden Eingriff gibt.
+ *
+ * ⚠️ **Sie sagt dasselbe wie {@link FIRMEN_TEXTE}, und das ist eine
+ * Doppelung** -- gehalten wird sie von einer Pruefung in `check:kontext`
+ * („der `hoch`-Rat geht an genau die Dateien, die `kontext hoch` wirklich
+ * traegt"). Die konnte vor diesem Umbau gar nicht rot werden, weil der Rat
+ * SELBST aus {@link FIRMEN_TEXTE} entstand; jetzt sind es zwei Tabellen, und
+ * ihr Auseinanderlaufen ist messbar.
+ */
+const RAT_ART_JE_DATEI = {
+    "CLAUDE.md": "nicht-hochschickbar",
+    "kontext/kurzprofil.md": "hochschickbar",
+    "kontext/firma.md": "hochschickbar",
+    "kontext/marke.md": "hochschickbar",
+    "kontext/systeme.md": "hochschickbar",
+    "kontext/sicherheit.md": "hochschickbar",
+};
+/**
+ * Der Wortlaut je Art und Rolle.
+ *
+ * ⚠️ ECHTE UMLAUTE -- das liest ein Kunde. Die ASCII-Umschrift dieser Datei
+ * gilt nur fuer Kommentare.
+ *
+ * 🔑 `wer` ist die fertige Anrede (` an Lena` oder ` an euren Firmen-Admin`),
+ * damit der Rueckfall auf den Sammelbegriff an EINER Stelle steht und nicht in
+ * jedem Zweig neu. Ruling T7-1: nie `null` im Klartext.
+ */
+const RAT_TEXT = {
+    hochschickbar: (rolle, wer) => rolle === "admin"
+        ? "  Deine Fassung ist die neuere? Dann schick sie hoch:  kimal3 kontext hoch"
+        : "  Deine Fassung bleibt stehen — hochschicken darf nur der Firmen-Admin.\n" +
+            `  Gib deine Ergänzung${wer} weiter; von dort geht sie in der App unter\n` +
+            "  Firma → Kontext oder mit `kimal3 kontext hoch` an alle.",
+    /*
+      🔴 **Auch dieser Zweig kennt die ROLLE -- Punkt A-5, 2026-08-26.** Er tat
+      es bis dahin nicht und riet jedem dasselbe: „Aendere sie dort", also im
+      Formular unter Firma → Kontext. Ein MITGLIED kann das nicht. `kimal3
+      kontext hoch` weist es ab, und den Firmenkontext der Firma darf es in der
+      App nicht schreiben. *Ein Rat, der die Lage nicht aendern kann, ist keiner*
+      -- er schickt einen Menschen an eine Tuer, vor der er keinen Schluessel
+      hat, und laesst ihn den Fehler bei sich suchen.
+  
+      🔑 Was das Mitglied stattdessen liest: WAS es weitergeben soll (die drei
+      Saetze aus `kontext/kurzprofil.md`) und AN WEN -- genau die Form, die der
+      Zweig fuer die fuenf `kontext/`-Dateien oben schon hat.
+    */
+    "nicht-hochschickbar": (rolle, wer) => rolle === "admin"
+        ? "  Die `CLAUDE.md` kann `kimal3 kontext hoch` nicht mitnehmen — der Befehl schickt nur\n" +
+            "  die fünf Dateien aus `kontext/`. Die drei Sätze in dieser Datei kommen aus\n" +
+            "  `kontext/kurzprofil.md`, der Firmenname aus der App: Ändere sie dort, dann holt\n" +
+            "  der nächste `kimal3 kontext runter` sie hierher.\n" +
+            "  Alles Übrige darin ist unsere Vorlage — dafür gibt es keinen Weg zurück."
+        : "  Die `CLAUDE.md` kann `kimal3 kontext hoch` nicht mitnehmen — der Befehl schickt nur\n" +
+            "  die fünf Dateien aus `kontext/`. Deine Änderung bleibt stehen.\n" +
+            "  Die drei Sätze in dieser Datei kommen aus `kontext/kurzprofil.md`, und die ändert\n" +
+            `  nur der Firmen-Admin. Gib deinen Wunsch${wer} weiter; von dort geht\n` +
+            "  `kontext/kurzprofil.md` in der App unter Firma → Kontext oder mit\n" +
+            "  `kimal3 kontext hoch` an alle.\n" +
+            "  Alles Übrige darin ist unsere Vorlage — dafür gibt es keinen Weg zurück.",
+};
+/**
+ * Was ein Mensch lesen soll, wenn `kimal3 kontext runter` Dateien in Ruhe
+ * laesst, weil er sie lokal geaendert hat -- je nach Rolle und je nach DATEI.
+ *
+ * 🔴 **DAS IST FUND F, ZUM ZWEITEN MAL -- und diesmal die echte Fassung
+ * (Review-Befund F-3, 2026-08-25).** Der Rat lautete fuer die ganze Liste auf
+ * einmal: „Deine Fassung ist die neuere? Dann schick sie hoch: kimal3 kontext
+ * hoch". Fuer `CLAUDE.md` ist dieser Satz eine Sackgasse: Sie steht in
+ * {@link VERWALTETE_DATEIEN} und landet deshalb in der Liste -- aber
+ * `kontext hoch` liest ausschliesslich die fuenf Dateien aus
+ * {@link FIRMEN_TEXTE} und meldet danach Erfolg, ohne sie. *Der Mensch tippt
+ * den geratenen Befehl, sieht einen Haken, und seine Aenderung steht weiter
+ * allein auf seiner Platte.*
+ *
+ * 🔑 Die ausgelieferte `CLAUDE.md` laedt diese Bearbeitung foermlich ein: Sie
+ * sagt selbst, aendern muesse man sie nur, wenn sich die Firma aendert.
+ *
+ * 🔴 **Der Rat wohnt hier und nicht im Befehl, damit ihn eine Wache sehen
+ * kann.** Die spurious Fassung desselben Fehlers (`merkzettelNachHoch`) war
+ * behoben, die echte lag vier Runden lang offen -- *ein Satz ueber das
+ * Verhalten eines Befehls wohnte im Befehl selbst, wo keine Vorlagen-Wache je
+ * hinsieht.* `check:kontext` prueft jetzt genau diese Zuordnung.
+ *
+ * 🔴 **PUNKT A-7 (2026-08-26): DER RAT WIRD ERZEUGT, NICHT AUFGEZAEHLT.** Diese
+ * Funktion hatte zwei `if`s -- eines fuer „irgendetwas aus
+ * {@link FIRMEN_TEXTE}", eines fuer den woertlichen Namen `"CLAUDE.md"`. Eine
+ * siebte verwaltete Datei waere durch beide gefallen und haette schweigend gar
+ * keinen Rat bekommen. Jetzt laeuft die Schleife ueber
+ * {@link VERWALTETE_DATEIEN} selbst und schlaegt die Art in
+ * {@link RAT_ART_JE_DATEI} nach -- eine Datei ohne Zuordnung uebersetzt nicht.
+ *
+ * ⚠️ **Eine ART, ein Satz -- auch wenn drei ihrer Dateien betroffen sind.** Das
+ * war vorher so (ein `if` feuerte einmal) und bleibt so: Der Rat spricht ueber
+ * den Weg, nicht ueber die einzelne Datei; dreimal derselbe Absatz waere
+ * Laerm.
+ */
+export function ratNachUnberuehrt(unberuehrt, rolle, adminName) {
+    // Ruling T7-1: kein `null` im Klartext, sondern der Sammelbegriff.
+    const wer = adminName ? ` an ${adminName}` : " an euren Firmen-Admin";
+    const betroffeneArten = new Set();
+    for (const pfad of VERWALTETE_DATEIEN) {
+        if (unberuehrt.includes(pfad))
+            betroffeneArten.add(RAT_ART_JE_DATEI[pfad]);
+    }
+    // 🔑 Die Reihenfolge kommt aus RAT_REIHENFOLGE, NICHT aus der Einfuegereihen-
+    // folge des `Set` -- sonst haenge die Ausgabe beim Kunden davon ab, in
+    // welcher Reihenfolge VERWALTETE_DATEIEN zufaellig steht.
+    return RAT_REIHENFOLGE.filter((art) => betroffeneArten.has(art)).map((art) => RAT_TEXT[art](rolle, wer));
+}