kimal3 0.1.5 → 0.2.0

package/dist/kontext-stand.js

@@ -0,0 +1,616 @@
+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).
+ */
+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: {} };
+/**
+ * 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` ist das vierte, LETZTE und OPTIONALE
+ * Argument (Default `{}`) -- bewusst ans Ende gehaengt, nicht dazwischen. Der
+ * einzige heutige Aufrufer (`ausliefern.ts`) reicht die echten
+ * Vordruck-Pruefsummen noch nicht durch (das wiederum durchzuziehen ist Sache
+ * einer spaeteren Aufgabe -- diese hier baut nur die Rechnung, s. Auftrag);
+ * ein PFLICHT-Argument haette genau diesen bestehenden Aufruf sofort zum
+ * Kompilierfehler gemacht, und diese Aufgabe darf ausschliesslich in dieser
+ * Datei und in `check-kontext.mts` etwas aendern. 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.*
+ *
+ * 🔑 `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".
+ *
+ * 🔴 `aktuelleVorlage` ist OPTIONAL, NICHT weil die dritte Dimension optional
+ * waere, sondern weil das Verdrahten mit echten Vordruck-Pruefsummen an den
+ * Aufrufstellen (`kontext-runter.ts`) NICHT zu dieser Aufgabe gehoert (s.
+ * Auftrag: "Bau die Lage, nicht ihre Ausgabe") -- und diese Aufgabe darf
+ * ausschliesslich in dieser Datei und in `check-kontext.mts` etwas aendern.
+ * Bleibt das Argument weg, verhaelt sich diese Funktion BUCHSTAeBLICH wie vor
+ * dieser Aufgabe: `vorlage-neuer` kann dann gar nicht entstehen. Das ist kein
+ * Kompromiss an der Rechnung, sondern die Rechnung UND der bestehende,
+ * unveraenderte Aufrufer bleiben beide wahr.
+ */
+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.aktuelleVorlage === undefined
+        ? false
+        : a.eintrag === null
+            ? true
+            : a.eintrag.vorlage !== a.aktuelleVorlage;
+    if (lokalGeaendert)
+        return serverNeuer || vorlageNeuer ? "beides" : "lokal-geaendert";
+    if (serverNeuer)
+        return "server-neuer";
+    if (vorlageNeuer)
+        return "vorlage-neuer";
+    return "schon-aktuell";
+}
+/** `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`.
+*/
+/**
+ * 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.
+ *
+ * ⚠️ ECHTE UMLAUTE -- das liest ein Kunde. Die ASCII-Umschrift dieser Datei
+ * gilt nur fuer Kommentare.
+ */
+export function ratNachUnberuehrt(unberuehrt, rolle, adminName) {
+    const zeilen = [];
+    // Fuer alles, was `kontext hoch` wirklich tragen kann.
+    if (unberuehrt.some((p) => FIRMEN_TEXTE.some((t) => t.pfad === p))) {
+        if (rolle === "admin") {
+            zeilen.push("  Deine Fassung ist die neuere? Dann schick sie hoch:  kimal3 kontext hoch");
+        }
+        else {
+            const wer = adminName ? ` an ${adminName}` : " an euren Firmen-Admin";
+            zeilen.push("  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.");
+        }
+    }
+    // Und fuer die eine Datei, die er nicht tragen kann.
+    if (unberuehrt.includes("CLAUDE.md")) {
+        zeilen.push("  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.");
+    }
+    return zeilen;
+}