kimal3 0.2.0 → 0.2.1

package/dist/kontext-stand.js

@@ -42,6 +42,18 @@ import { createHash } from "node:crypto";
  * ⛔ 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",
@@ -117,6 +129,83 @@ export const LEER = "leer";
 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.
  *
@@ -333,24 +422,27 @@ export function bekannterStandAus(merkzettel) {
  * 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.*
+ * 🔴 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 = {}) {
+export function baueMerkzettel(dateien, staende, firmenId, vorlagenPruefsummen) {
     const raus = {};
     for (const pfad of VERWALTETE_DATEIEN) {
         const datei = dateien.find((d) => d.pfad === pfad);
@@ -454,15 +546,25 @@ export function merkzettelNachHoch(vomServer, lokal, gesendet) {
  * 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.
+ * 🔴 **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)
@@ -472,19 +574,76 @@ export function lageFuerDatei(a) {
         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;
+    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 || vorlageNeuer ? "beides" : "lokal-geaendert";
+        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}`;
@@ -564,6 +723,102 @@ export function arbeitsplatzAus(kandidaten) {
   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.
@@ -587,30 +842,29 @@ export function arbeitsplatzAus(kandidaten) {
  * 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.
+ * 🔴 **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) {
-    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.");
+    // 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]);
     }
-    return zeilen;
+    // 🔑 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));
 }

package/dist/nachricht.js

@@ -62,6 +62,21 @@ function teile(v) {
     }
     return zahlen;
 }
+/**
+ * Laesst sich das ueberhaupt als Versionsstand lesen?
+ *
+ * 🔴 **Gebraucht, weil `istAelter` unten bei Muell `false` sagt** -- und
+ * `false` heisst dort „nicht aelter", was ein Aufrufer als „neu genug" liest.
+ * Fuer den Update-Hinweis ist das richtig („im Zweifel schweigen"), fuer eine
+ * Faehigkeits-Frage (`cli/src/faehigkeiten.ts`) ist es genau verkehrt: Dort
+ * wuerde ein unlesbarer Kopf zur Auskunft „die Fassung kann alles".
+ *
+ * *Dieselbe Antwort `false` bedeutet an zwei Stellen Verschiedenes -- deshalb
+ * muss die Frage „ist das ueberhaupt eine Nummer" getrennt gestellt werden.*
+ */
+export function istVersionsstand(v) {
+    return teile(v) !== null;
+}
 /**
  * Ist `a` aelter als `b`? Zahl fuer Zahl, nicht als Text.
  *
@@ -100,9 +115,73 @@ export function heuteAus(d) {
     return new Intl.DateTimeFormat("sv-SE", { timeZone: "Europe/Berlin" }).format(d);
 }
 /**
- * Die ganze Entscheidung, als Funktion von vier Werten.
+ * Die Kennung eines FIRMENKONTEXT-Hinweises faengt hiermit an, und dahinter
+ * steht der Server-Stand, den er meint (`kontext-2026-08-26T09:00:00Z`).
+ *
+ * 🔑 Sie steht als eigener Name da, weil sie von ZWEI Seiten gebraucht wird:
+ * `firmenHinweisAus` baut die Kennung, `hinweisErledigt` liest sie wieder
+ * auseinander. Zwei getippte `"kontext-"` waeren zwei Wahrheiten -- und die
+ * zweite verrottete lautlos, weil ein Hinweis, der nicht mehr erkannt wird,
+ * einfach wieder erscheint, statt einen Fehler zu machen.
+ */
+export const KONTEXT_HINWEIS_PRAEFIX = "kontext-";
+/**
+ * Ist der ANLASS dieses Hinweises inzwischen erledigt?
+ *
+ * 🔴 DER FALL, DER DIESE FUNKTION RECHTFERTIGT (offener Punkt A-4, gemessen
+ * am 2026-08-26): Direkt nach `kimal3 kontext runter` stand da
+ *
+ *     Dein Firmenkontext ist aktuell.
+ *     Nordwind hat den Firmenkontext aktualisiert.  kimal3 kontext runter
+ *
+ * -- die zweite Zeile riet zu genau dem Befehl, der gerade gelaufen war. Kein
+ * Rechenfehler: Die CLI schickt ihren Stand VOR dem Herunterladen mit, der
+ * Server vergleicht ihn mit seinem eigenen und haengt den Hinweis an. Bis der
+ * Hinweis ausgegeben wird, hat der Befehl den lokalen Stand laengst
+ * nachgezogen. *Die Meldung kam einen Aufruf zu spaet.*
+ *
+ * Die Regel dagegen: **Ein Hinweis, dessen Stand der lokale Merkzettel JETZT
+ * traegt, ist erledigt und wird nicht ausgegeben.**
+ *
+ * ⚠️ NUR Kontext-Hinweise. Die globale Nachricht aus der Datenbank traegt eine
+ * UUID als Kennung und darf durch diese Regel NIE verstummen -- sie hat mit
+ * dem Firmenkontext nichts zu tun, und ein Kanal, der sich versehentlich selbst
+ * stilllegt, faellt niemandem auf.
+ *
+ * ⚠️ `null` und leer heissen "wir wissen es nicht", nicht "erledigt": Wer den
+ * lokalen Stand nicht kennt, darf keinen Hinweis unterdruecken. Im Zweifel
+ * zeigen -- eine Zeile zu viel ist harmlos, eine verschluckte Zeile nicht.
+ */
+export function hinweisErledigt(hinweisId, lokalerStandJetzt) {
+    if (!hinweisId)
+        return false;
+    if (!hinweisId.startsWith(KONTEXT_HINWEIS_PRAEFIX))
+        return false;
+    const gemeinterStand = hinweisId.slice(KONTEXT_HINWEIS_PRAEFIX.length);
+    if (gemeinterStand === "")
+        return false;
+    if (lokalerStandJetzt === null || lokalerStandJetzt === "")
+        return false;
+    return gemeinterStand === lokalerStandJetzt;
+}
+/**
+ * Die ganze Entscheidung, als Funktion von fuenf Werten.
+ *
+ * 🔴 `lokalerKontextStandJetzt` IST ABSICHTLICH PFLICHT, nicht optional
+ * (A-4). Am 2026-08-26 hat dieses Projekt gemessen, was ein optionales
+ * Argument anrichtet: `lageFuerDatei` konnte erkennen, dass sich unsere
+ * Vorlage geaendert hat -- die Aufrufstelle uebergab den noetigen Wert nie,
+ * und weil das Argument optional war, fehlte keine Zeile, meckerte kein
+ * Compiler und wurde kein Waechter rot. Die Rechnung war gebaut, geprueft,
+ * dokumentiert und in der Wirklichkeit tot. *Ein Pflicht-Argument ist die
+ * einzige Verdrahtung, die der Compiler fuer einen mitdenkt.*
+ *
+ * 🔑 UND ER MUSS FRISCH SEIN. Der Wert, den die CLI im Kopf mitschickt, wird
+ * VOR dem Netzaufruf gelesen; dieser hier gehoert an das ENDE des Befehls.
+ * Wer denselben Wert zweimal benutzt, baut den Fehler wieder ein, gegen den
+ * `hinweisErledigt` geschrieben ist.
  */
-export function sollZeigen(h, eigeneVersion, gesehen, heute) {
+export function sollZeigen(h, eigeneVersion, gesehen, heute, lokalerKontextStandJetzt) {
     if (!h.id)
         return false;
     if (!h.text || h.text.trim() === "")
@@ -110,6 +189,11 @@ export function sollZeigen(h, eigeneVersion, gesehen, heute) {
     // Leeres Feld = alle sehen es. Sonst nur, wer aelter ist als die Grenze.
     if (h.gilt_unter_version && !istAelter(eigeneVersion, h.gilt_unter_version))
         return false;
+    // Der Anlass ist erledigt -- der Befehl, zu dem geraten wird, ist gerade
+    // gelaufen. Bewusst VOR der Tagessperre: Ein Hinweis, der gar nicht mehr
+    // gilt, soll auch nicht den einen Platz des Tages verbrauchen.
+    if (hinweisErledigt(h.id, lokalerKontextStandJetzt))
+        return false;
     // Hoechstens einmal am Tag -- auch bei zwanzig Befehlen.
     if (gesehen[h.id] === heute)
         return false;
@@ -242,7 +326,7 @@ export function firmenHinweisAus(lokalerStand, serverStand, firmenName) {
     if (lokalerStand === serverStand)
         return null;
     return {
-        id: `kontext-${serverStand}`,
+        id: `${KONTEXT_HINWEIS_PRAEFIX}${serverStand}`,
         text: `${firmenName} hat den Firmenkontext aktualisiert.  kimal3 kontext runter`,
         gilt_unter_version: null,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kimal3",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Trag deine KI-Projekte dort ein, wo sie entstehen: im Terminal.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -43,6 +43,21 @@ Das ist meist richtig, aber nicht immer schön (`s.mueller@…` wird zu `werkban
 **Frag den Menschen nach seinem Vornamen und gib ihn mit**, statt es dem Server zu überlassen —
 er heißt selten so, wie seine Adresse aussieht.
 
+🔴 **Gehört der Mensch zu MEHREREN Firmen, fragen beide Befehle nach — mit `--firma`.**
+Sie legen dann nichts an, sondern nennen die Firmen als fertige Zeilen zum Kopieren. Das ist
+kein Fehler, sondern die Rückfrage: Der Ordner trägt den Namen der Firma, und raten darf der
+Befehl ihn nicht.
+
+```
+kimal3 arbeitsplatz neu sabine --firma "Nordwind Handel GmbH"
+kimal3 werkbank neu sabine --firma "Nordwind Handel GmbH"
+kimal3 werkbank neu sabine --firma-id "…"      # falls zwei Firmen GLEICH heissen
+```
+
+⚠️ Der Rückgabewert ist dann `1` und die Absage steht auf der Fehlerausgabe. **Nimm eine der
+angebotenen Zeilen, statt es unverändert zu wiederholen** — ohne `--firma` kommt dieselbe
+Rückfrage noch einmal.
+
 ⚠️ **`werkbank neu` verlangt ein eigenes Pro-Konto.** Die Route prüft den Plan **pro Person**
 (`konto_plan`), nicht über die Firmen-Mitgliedschaft. Ein Kollege ohne eigenes Pro bekommt
 Rückgabewert `4` — dann **nicht** wiederholen und nicht raten, sondern genau das sagen: Sein
@@ -106,10 +121,19 @@ Stelle.
    Anker, Frage, Hinweis. Sind alle beantwortet, sagt er das in einem Satz, und du bist fertig.
    Der Befehl liest nur; er braucht weder Netz noch Anmeldung.
 2. **Die Fragen EINZELN stellen.** Eine Frage, die Antwort abwarten, dann die nächste. Keine
-   Liste mit siebzehn Punkten und kein Fragebogen am Stück — es sind Fragen über die Firma
-   eines Menschen, und die beantwortet er nicht in einem Rutsch.
+   lange Liste und kein Fragebogen am Stück — es sind Fragen über die Firma eines Menschen, und
+   die beantwortet er nicht in einem Rutsch.
 3. **Die Antwort in die genannte Datei schreiben** — unter ihre `## `-Überschrift, über der der
    Anker steht. Die Hinweiszeilen mit `>` gehören uns; **lass sie stehen und schreib darunter.**
+
+   🔴 **Die Pfade zählen ab dem Ordner, den `kontext fragen` als `Arbeitsplatz:` nennt — nicht
+   ab deinem Arbeitsverzeichnis.** Der Normalfall ist, dass beides auseinanderfällt:
+   `kimal3 arbeitsplatz neu` rät ausdrücklich, in die **Werkbank** zu wechseln und dort Claude
+   zu starten; die fünf Dateien liegen dann eine Ebene höher. **Setz jeden Pfad an den
+   genannten Arbeitsplatz an, bevor du schreibst.**
+   ⚠️ Wer das übergeht, legt eine **neue** Datei am falschen Ort an. `kimal3 kontext hoch` liest
+   weiter die echten Dateien und schickt leere Antworten hoch — *beide Seiten melden Erfolg, und
+   die Arbeit des Menschen ist trotzdem weg.*
 4. **`kimal3 kontext hoch`** — schickt alle fünf Dateien an die Firma. **Nur der Firmen-Admin
    darf das.**
 
@@ -124,12 +148,24 @@ darüberkopiert wurde —, bricht `kontext hoch` ab und schickt gar nichts, auch
 nicht** (Rückgabewert `1`). Das ist **kein** „noch einmal versuchen": Sag dem Menschen, welche
 Datei gemeint ist, und hol sie mit `kimal3 kontext runter` zurück.
 
-🔴 **Die eine Regel, die du sonst falsch machst: Rückgabewert `1` bei `kontext hoch` heißt „du
-bist kein Admin dieser Firma" — nicht „noch einmal versuchen".** Das ist eine andere `1` als die
-üblichen Eingabefehler weiter unten. Ein zweiter Versuch ändert nichts, weil sich an der Rolle
-nichts ändert. **Sag dem Menschen, dass er kein Admin ist, und nenne, an wen er sich wendet** —
-lief vorher `kontext runter`, kennt dessen Ausgabe den Admin-Namen bereits; sonst frag, wer in
-der Firma Admin ist.
+🔴 **Bei `kontext hoch` sagt die Zahl `1` allein GAR NICHTS — die Meldung sagt es. LIES SIE.**
+
+⚠️ **Hier stand bis zum 2026-08-28: „Rückgabewert `1` heißt ‚du bist kein Admin dieser
+Firma'".** Das war falsch und gefährlich. `kontext hoch` hat **sechs** verschiedene Ausgänge
+auf dieser einen Zahl (`cli/src/befehle/kontext-hoch.ts`): unbekannte Option · kein
+Arbeitsplatz gefunden · eine Datei nicht lesbar · eine Datei ohne Fragen · „jemand anderes hat
+geändert" (Ausweg `--ueberschreiben`) · mehrere Firmen (Ausweg `--firma`) — und die Rolle.
+
+🔴 **Der teuerste davon steht in `kontext-hoch.ts` (Merkzettel-Zweig) und ist ein ERFOLG:** *„Die Firma hat
+deine Änderungen gespeichert — nur der lokale Merkzettel ließ sich nicht schreiben."* Auch das
+gibt `1` zurück. Wer die Zahl als „kein Admin" deutet, sagt einem Menschen, der gerade alle
+Fragen beantwortet und **erfolgreich hochgeschickt** hat, er solle sich an seinen Admin wenden.
+*Ein Erfolg, als Absage vorgelesen — und er tippt danach alles noch einmal.*
+
+**Also:** Nimm den Satz, den der Befehl geschrieben hat, und sag dem Menschen, was er bedeutet.
+Geht es wirklich um die Rolle, nenne den Admin — lief vorher `kontext runter`, kennt dessen
+Ausgabe den Namen bereits; sonst frag, wer in der Firma Admin ist. Ein zweiter Versuch hilft nur
+dort, wo die Meldung einen Ausweg nennt (`--ueberschreiben`, `--firma`), sonst nie.
 
 ⚠️ **Beide Befehle brauchen wie `werkbank neu` ein eigenes Pro-Konto** — ohne das kommt
 Rückgabewert `4`, dann **nicht wiederholen**.