kimal3 0.5.0 → 0.6.0

package/README.md

@@ -42,6 +42,8 @@ kimal3 kontext fragen     Die Fragen über deine Firma beantworten — Claude f
 kimal3 kontext hoch       Deine lokalen Änderungen an den fünf Firmen-Texten hochschicken
 kimal3 projekt neu …      Ein Projekt ins Erfolgsprofil eintragen
 kimal3 projekt liste      Deine eingetragenen Projekte anzeigen
+kimal3 plan               Planung hochladen oder Rückmeldungen holen
+kimal3 plan hoch          Die Planung aus plan/stand.json hochschicken (--probe: nur prüfen)
 kimal3 kurs               Zeigen, wo du im Mini-Kurs stehst
 kimal3 firma daten        Die Daten deiner Firma holen, damit Claude sie auswerten kann
 kimal3 zeigen start       Eine Aufnahme starten, während du eine Aufgabe vormachst
@@ -182,6 +184,8 @@ kimal3 context questions  Answer the questions about your company — Claude tak
 kimal3 context upload     Upload your local changes to the five company texts
 kimal3 project new …      Add a project to your success profile
 kimal3 project list       Show the projects you've added
+kimal3 plan               Upload planning or fetch responses
+kimal3 plan upload        Upload the planning in plan/stand.json (--dry-run: only check)
 kimal3 course             Show where you are in the mini-course
 kimal3 company data       Fetch your company's data so Claude can analyse it
 kimal3 show start         Start a recording while you show a task

package/dist/befehle/plan-hoch.js

@@ -0,0 +1,114 @@
+import { feld, ruf } from "../api.js";
+import { schalterOhneWert, zerlege } from "../argumente.js";
+import { sprache } from "../sprache.js";
+import { ALLGEMEIN_TEXTE } from "../texte/allgemein.js";
+import { PLAN_TEXTE } from "../texte/plan.js";
+import { leseSpecTexte, schreibeNachHochladen, specKoepfeAus } from "../plan-datei.js";
+import { planAbsage, planDateiOderAbsage } from "./plan.js";
+const istZahl = (w) => typeof w === "number" && Number.isInteger(w) && w >= 0;
+function hochgeladenAus(koerper) {
+    if (!koerper || typeof koerper !== "object")
+        return null;
+    const k = koerper;
+    if (k.probe === true)
+        return null;
+    if (typeof k.projektId !== "string" || typeof k.titel !== "string" || typeof k.adresse !== "string" || typeof k.hochgeladenAm !== "string")
+        return null;
+    if (!istZahl(k.stories) || !istZahl(k.deinTest))
+        return null;
+    return { projektId: k.projektId, titel: k.titel, stories: k.stories, deinTest: k.deinTest, adresse: k.adresse, hochgeladenAm: k.hochgeladenAm, specTexte: istZahl(k.specTexte) ? k.specTexte : null };
+}
+function probeAus(koerper) {
+    if (!koerper || typeof koerper !== "object")
+        return null;
+    const k = koerper;
+    return k.probe === true && istZahl(k.stories) && istZahl(k.uebernommen) ? { stories: k.stories, uebernommen: k.uebernommen, specTexte: istZahl(k.specTexte) ? k.specTexte : null } : null;
+}
+/**
+ * Die Zeile aus US-16. `angekommen` kommt aus der Antwort des Servers (Eintraege mit Text), nicht aus dem, was
+ * die CLI geschickt hat: Eine alte App ohne das Feld antwortet ohne Zahl, und dann steht hier lieber keine Zeile
+ * als eine, die ein Hochladen behauptet, das nicht stattgefunden hat.
+ */
+function specTexteZeile(angekommen, gesamt, ohne, s) {
+    if (angekommen === null)
+        return null;
+    const t = PLAN_TEXTE[s];
+    return t.specTexte(angekommen, gesamt, ohne.map((o) => t.specTextOhneEintrag(o.titel, t.specTextOhneGrund(o.grund, o.pfad))));
+}
+export async function planHoch(argv) {
+    let s = sprache();
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(PLAN_TEXTE[s].uploadHelp);
+        return 0;
+    }
+    // ⚠️ `zerlege` kennt keine Schalter ohne Wert -- beide VOR der Zerlegung heraus, wie `--ueberschreiben` in kontext-hoch.ts.
+    // Was danach uebrig bleibt, ist ein Tippfehler: `zerlege` ohne erlaubte Optionen sagt dazu den passenden Satz.
+    const ueber = schalterOhneWert(argv, "ueberschreiben");
+    const probe = schalterOhneWert(ueber.rest, "probe");
+    const zerlegt = zerlege(probe.rest, [], s);
+    if (!zerlegt.ok) {
+        console.error(zerlegt.meldung);
+        return 1;
+    }
+    const datei = planDateiOderAbsage(s);
+    if (datei === null)
+        return 1;
+    const hatteNummer = typeof datei.json.projekt_id === "string";
+    // Der Text der Specs geht im selben Aufruf mit (US-16); pro Spec liegt entweder der Text oder der Grund vor.
+    const koepfe = specKoepfeAus(datei.json);
+    // Eine Funktion baut den Rumpf: an ihm misst `leseSpecTexte` die 4 MB, und genau er geht hinaus (US-16).
+    const rumpf = (specTexte) => ({ stand: datei.text, ueberschreiben: ueber.gesetzt, probe: probe.gesetzt, specTexte });
+    const texte = leseSpecTexte(process.cwd(), koepfe, rumpf);
+    const antwort = await ruf("/api/cli/projekt/plan", {
+        methode: "POST", // kein-anzeigetext: HTTP-Verb
+        mitAusweis: true,
+        koerper: rumpf(texte.eintraege),
+    });
+    // 🌐 Die Antwort kann die Kontosprache umgestellt haben: Was ab hier gedruckt wird, in der neuen.
+    s = sprache();
+    const t = PLAN_TEXTE[s];
+    if (antwort.status !== 200) {
+        const code = planAbsage(antwort, s);
+        // Ruling 10: `503 teilweise` -- gespeichert, aber die Rueckmeldungen noch nicht markiert. `basis` muss trotzdem
+        // nachgetragen werden, sonst lehnt der zweite Lauf als „veraltet" ab; `uebernommen` bleibt fuer genau diesen Lauf stehen.
+        // Fehlen Nummer oder Zeitpunkt in der Antwort, wird nichts geschrieben (geraten wird hier nie).
+        const projektId = feld(antwort.koerper, "projektId"); // kein-anzeigetext: Feldname der Antwort
+        const hochgeladenAm = feld(antwort.koerper, "hochgeladenAm"); // kein-anzeigetext: Feldname der Antwort
+        if (antwort.status === 503 && feld(antwort.koerper, "grund") === "teilweise" && projektId !== null && hochgeladenAm !== null &&
+            !schreibeNachHochladen(process.cwd(), projektId, hochgeladenAm, false)) {
+            console.error(t.writeBackFailed(projektId, hochgeladenAm, false));
+        }
+        return code;
+    }
+    if (probe.gesetzt) {
+        const p = probeAus(antwort.koerper);
+        if (p === null) {
+            console.error(ALLGEMEIN_TEXTE[s].unreadableAnswer);
+            return 3;
+        }
+        console.log(t.dryRun(p.stories, p.uebernommen));
+        const zeile = specTexteZeile(p.specTexte, koepfe.length, texte.ohne, s);
+        if (zeile !== null)
+            console.log(zeile);
+        return 0;
+    }
+    const h = hochgeladenAus(antwort.koerper);
+    if (h === null) {
+        console.error(ALLGEMEIN_TEXTE[s].unreadableAnswer);
+        return 3;
+    }
+    // Erst sagen, was oben angekommen ist, dann, was daneben schiefging (dieselbe Reihenfolge wie in kontext-hoch.ts).
+    console.log(t.uploaded(h.titel, h.stories, h.deinTest));
+    const zeile = specTexteZeile(h.specTexte, koepfe.length, texte.ohne, s);
+    if (zeile !== null)
+        console.log(zeile);
+    console.log(t.view(h.adresse));
+    if (!schreibeNachHochladen(process.cwd(), h.projektId, h.hochgeladenAm, true)) {
+        // `1`, nicht `0`: Ohne `basis` in der Datei lehnt das naechste Hochladen als „veraltet" ab -- hier ist noch etwas zu tun.
+        console.error(t.writeBackFailed(h.projektId, h.hochgeladenAm, true));
+        return 1;
+    }
+    if (!hatteNummer)
+        console.log(t.idNowInFile);
+    return 0;
+}

package/dist/befehle/plan.js

@@ -0,0 +1,110 @@
+import { feld, ruf } from "../api.js";
+import { sprache } from "../sprache.js";
+import { ALLGEMEIN_TEXTE } from "../texte/allgemein.js";
+import { PLAN_TEXTE } from "../texte/plan.js";
+import { schlussFehler } from "../fehler.js";
+import { lesePlanDatei } from "../plan-datei.js";
+const istZahl = (w) => typeof w === "number" && Number.isInteger(w);
+const textOderNull = (w) => typeof w === "string" || w === null;
+function offenAus(w) {
+    if (!w || typeof w !== "object")
+        return null;
+    const r = w;
+    if (!istZahl(r.nummer) || (r.art !== "passt_nicht" && r.art !== "thema") || typeof r.notiz !== "string")
+        return null;
+    if (!textOderNull(r.spec) || !textOderNull(r.story) || !(istZahl(r.runde) || r.runde === null))
+        return null;
+    // Ein „passt nicht" ohne Story und Runde waere eine Zeile, aus der Claude nichts machen kann.
+    if (r.art === "passt_nicht" && (r.spec === null || r.story === null || r.runde === null))
+        return null;
+    return { nummer: r.nummer, art: r.art, spec: r.spec, story: r.story, runde: r.runde, notiz: r.notiz };
+}
+function bestaetigtAus(w) {
+    if (!w || typeof w !== "object")
+        return null;
+    const r = w;
+    return typeof r.spec === "string" && typeof r.story === "string" && istZahl(r.runde) ? { spec: r.spec, story: r.story, runde: r.runde } : null;
+}
+/** `null`, wenn die Antwort nicht die erwartete Form hat (z. B. ein WLAN-Anmeldeportal mit `200`). */
+export function planAntwortAus(koerper) {
+    if (!koerper || typeof koerper !== "object")
+        return null;
+    const k = koerper;
+    if (typeof k.adresse !== "string" || !Array.isArray(k.offen) || !Array.isArray(k.bestaetigt))
+        return null;
+    const offen = k.offen.map((o) => offenAus(o));
+    const bestaetigt = k.bestaetigt.map((b) => bestaetigtAus(b));
+    if (offen.includes(null) || bestaetigt.includes(null))
+        return null;
+    return { adresse: k.adresse, offen: offen, bestaetigt: bestaetigt };
+}
+/** Reine Rechnung: die Zeilen, die Claude zu sehen bekommt. */
+export function planZeilen(a, s) {
+    const t = PLAN_TEXTE[s];
+    const zeilen = a.offen.length === 0
+        ? [t.noOpen]
+        : a.offen.map((o) => (o.art === "thema" ? t.openTopic(o.nummer, o.notiz) : t.openVerdict(o.nummer, o.spec ?? "", o.story ?? "", o.runde ?? 0, o.notiz)));
+    if (a.bestaetigt.length > 0)
+        zeilen.push(t.confirmed(a.bestaetigt.map((b) => t.confirmedItem(b.spec, b.story, b.runde)).join(", ")));
+    zeilen.push(t.view(a.adresse));
+    return zeilen;
+}
+/** Die Datei fehlt oder ist kein JSON -- Satz auf stderr, `null`. Sonst die gelesene Datei. */
+export function planDateiOderAbsage(s) {
+    const datei = lesePlanDatei(process.cwd());
+    if (datei.ok)
+        return datei;
+    console.error(datei.grund === "fehlt" ? PLAN_TEXTE[s].fileMissing : PLAN_TEXTE[s].noJson);
+    return null;
+}
+/**
+ * Was beide Befehle mit einer Absage tun. `409`/`422` tragen einen fertigen Satz in der Kontosprache
+ * (Projekt unbekannt oder mehrdeutig, Plan unlesbar, Runde kleiner, veraltet) -- woertlich ausgeben, `1`.
+ * `503 teilweise` heisst: gespeichert, aber nicht ganz -- `3`, denn ein zweiter Lauf hilft (Spec Abschnitt 5).
+ */
+export function planAbsage(antwort, s) {
+    const meldung = feld(antwort.koerper, "meldung") ?? ALLGEMEIN_TEXTE[s].genericFailure;
+    if (antwort.status === 402) {
+        console.error(meldung);
+        return 4;
+    }
+    if (antwort.status === 401) {
+        console.error(`${meldung}${ALLGEMEIN_TEXTE[s].pleaseSignIn}`);
+        return 2;
+    }
+    if (antwort.status === 409 || antwort.status === 422) {
+        console.error(meldung);
+        return 1;
+    }
+    // `503 teilweise` landet ueber `schlussFehler` auf derselben `3` wie jeder andere Aussetzer -- mit dem Satz des Servers.
+    const schluss = schlussFehler(antwort.status, meldung, s);
+    console.error(schluss.text);
+    return schluss.wert;
+}
+export async function plan(argv) {
+    let s = sprache();
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(PLAN_TEXTE[s].listHelp);
+        return 0;
+    }
+    const datei = planDateiOderAbsage(s);
+    if (datei === null)
+        return 1;
+    const suche = new URLSearchParams();
+    if (typeof datei.json.projekt_id === "string")
+        suche.set("projekt-id", datei.json.projekt_id);
+    if (typeof datei.json.projekt === "string")
+        suche.set("projekt", datei.json.projekt);
+    const antwort = await ruf(`/api/cli/projekt/plan?${suche.toString()}`, { methode: "GET", mitAusweis: true }); // kein-anzeigetext: Pfad und HTTP-Methode
+    // 🌐 Die Antwort kann die Kontosprache umgestellt haben: Was ab hier gedruckt wird, in der neuen.
+    s = sprache();
+    if (antwort.status !== 200)
+        return planAbsage(antwort, s);
+    const a = planAntwortAus(antwort.koerper);
+    if (a === null) {
+        console.error(ALLGEMEIN_TEXTE[s].unreadableAnswer);
+        return 3;
+    }
+    planZeilen(a, s).forEach((z) => console.log(z));
+    return 0;
+}

package/dist/befehle-katalog-en.js

@@ -118,6 +118,20 @@ export const BEFEHLE_EN = {
             "What it's really for: Claude looks here BEFORE adding a project. Without that check, the same project would sooner or later appear twice on a public page that carries your name.",
         ],
     },
+    "kimal3 plan": {
+        stempel: "5a366449",
+        befehl: "kimal3 plan",
+        tippen: "/k3plan",
+        terminal: "kimal3 plan",
+        beschreibung: "Upload planning or fetch responses",
+        rhythmusOderSatz: "check my planning",
+        details: [
+            "kimal3 plan fetches what you've said in the app since the last upload: every “doesn't work” and every noted topic with its number, plus the confirmed stories. Claude sorts them and enters them in plan/stand.json.",
+            "kimal3 plan upload sends plan/stand.json to your project and then enters projekt_id and basis in the file itself. With --dry-run it only checks and saves nothing.",
+            "If the plan can't be read, a round goes down or the app already holds a newer plan, it refuses and saves nothing at all — the message says what to do. Use --overwrite only if you really mean it.",
+            "You'll know it worked when it reports with ✓ how many stories were uploaded and how many are waiting for your test, and gives the link to the planning.",
+        ],
+    },
     "kimal3 kurs": {
         stempel: "3a5c7600",
         befehl: "kimal3 course",

package/dist/befehle-katalog.js

@@ -167,6 +167,24 @@ export const BEFEHLE = [
             "Wofür es wirklich da ist: Claude schaut hier VOR dem Eintragen nach. Ohne diesen Blick stünde dasselbe Projekt irgendwann zweimal auf einer öffentlichen Seite, die deinen Namen trägt.",
         ],
     },
+    /*
+      `kimal3 plan` und `kimal3 plan hoch` (Spec 2026-10-21-projektseite-planung) -- EIN Eintrag fuer beide: Claude
+      ruft sie nacheinander auf, und ein Mensch sucht hier nach der Planung, nicht nach zwei Befehlen.
+    */
+    {
+        befehl: "kimal3 plan",
+        beschreibung: "Planung hochladen oder Rückmeldungen holen",
+        wer: "claude",
+        ausloeser: "prüf meine Planung",
+        tippen: "/k3plan",
+        terminal: "kimal3 plan",
+        details: [
+            "kimal3 plan holt aus der App, was du seit dem letzten Hochladen gesagt hast: jedes „passt nicht“ und jedes notierte Thema mit seiner Nummer, dazu die bestätigten Stories. Claude ordnet sie ein und trägt sie in plan/stand.json ein.",
+            "kimal3 plan hoch schickt plan/stand.json an dein Projekt und trägt danach projekt_id und basis selbst in die Datei ein. Mit --probe prüft er nur und speichert nichts.",
+            "Ist der Plan nicht lesbar, wird eine Runde kleiner oder liegt in der App schon ein neuerer Plan, lehnt er ab und speichert gar nichts — die Meldung sagt, was zu tun ist. --ueberschreiben nur, wenn du es wirklich willst.",
+            "Geklappt hat es, wenn er mit ✓ meldet, wie viele Stories hochgeladen sind und wie viele auf deinen Test warten, und den Link zur Planung nennt.",
+        ],
+    },
     {
         befehl: "kimal3 kurs",
         beschreibung: "Zeigen, wo du im Mini-Kurs stehst",

package/dist/befehlswoerter.js

@@ -10,6 +10,9 @@ export const BEFEHLSWOERTER = {
     "kontext fragen": { de: "kontext fragen", en: "context questions" }, // kein-anzeigetext: Befehlswörter (Spec Abschnitt 6)
     "projekt neu": { de: "projekt neu", en: "project new" }, // kein-anzeigetext: Befehlswörter (Spec Abschnitt 6)
     "projekt liste": { de: "projekt liste", en: "project list" }, // kein-anzeigetext: Befehlswörter (Spec Abschnitt 6)
+    // `kimal3 plan` (Spec 2026-10-21-projektseite-planung, US-9): `plan` heisst in beiden Sprachen gleich.
+    plan: { de: "plan", en: "plan" },
+    "plan hoch": { de: "plan hoch", en: "plan upload" }, // kein-anzeigetext: Befehlswörter (Spec projektseite-planung)
     "firma daten": { de: "firma daten", en: "company data" }, // kein-anzeigetext: Befehlswörter (Spec Abschnitt 6)
     kurs: { de: "kurs", en: "course" }, // kein-anzeigetext: Befehlswörter (Spec Abschnitt 6)
     wache: { de: "wache", en: "watch" },
@@ -71,6 +74,8 @@ export const SCHALTER_EN = {
     "at-most": "hoechstens",
     language: "sprache",
     "without-typed": "ohne-getipptes",
+    // `kimal3 plan upload` (Spec 2026-10-21-projektseite-planung, US-11); `--overwrite` steht schon oben.
+    "dry-run": "probe",
 };
 /** `company` -> `firma`; ein deutscher (oder unbekannter) Name bleibt, wie er ist. */
 export function deutscherSchalter(getippt) {

package/dist/kimal3.js

@@ -36,6 +36,8 @@ import { logout } from "./befehle/logout.js";
 import { kurs } from "./befehle/kurs.js";
 import { projektListe } from "./befehle/projekt-liste.js";
 import { projektNeu } from "./befehle/projekt-neu.js";
+import { plan } from "./befehle/plan.js";
+import { planHoch } from "./befehle/plan-hoch.js";
 import { skillDatei, skillInstallBefehl } from "./befehle/skill-install.js";
 import { wache, wacheSchalten } from "./befehle/wache.js";
 import { zeigenAuswerten, zeigenBild, zeigenStatus, zeigenStopp } from "./befehle/zeigen.js";
@@ -487,6 +489,9 @@ async function fuehreAus(name, rest) {
         case "skill install": return allein ? skillInstallBefehl() : null;
         case "projekt neu": return projektNeu(rest);
         case "projekt liste": return allein ? projektListe() : null;
+        // `plan` nimmt nur `--help`; ein Wort dahinter (`plan muell`) bleibt unbekannt wie bei `login extra`.
+        case "plan": return allein || (rest.length === 1 && (rest[0] === "--help" || rest[0] === "-h")) ? plan(rest) : null;
+        case "plan hoch": return planHoch(rest);
         case "kurs": return allein ? kurs() : null;
         // ⚠️ Rest wird durchgereicht, nicht auf Gleichheit geprueft: `firma daten --firma X` gehoert dazu.
         case "firma daten": return firmaDaten(rest);

package/dist/plan-datei.js

@@ -0,0 +1,172 @@
+/**
+ * `plan/stand.json` lesen und nach dem Hochladen nachtragen (Spec 2026-10-21-projektseite-planung, Abschnitt 3).
+ *
+ * 🔑 Die Datei gehoert Claude und liegt unter Git -- diese Datei prueft sie NICHT. Ob ein Plan stimmt,
+ * entscheidet allein der Server (`lesePlanText`); hier geht es nur darum, ob es ueberhaupt ein JSON-Objekt
+ * ist, damit ein Tippfehler im Klammerwerk ohne Netz und ohne Anmeldung auffaellt.
+ *
+ * ⚠️ Ein BOM am Anfang (Windows-Editoren setzen eines) wird beim Lesen entfernt: `JSON.parse` lehnt es ab,
+ * und der Server meldete sonst „kein JSON" fuer eine Datei, die im Editor einwandfrei aussieht.
+ */
+import { readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+export const PLAN_PFAD = "plan/stand.json"; // kein-anzeigetext: Dateipfad
+const ohneBom = (text) => (text.startsWith("\uFEFF") ? text.slice(1) : text);
+function alsObjekt(text) {
+    try {
+        const json = JSON.parse(text);
+        return json !== null && typeof json === "object" && !Array.isArray(json) ? json : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function lesePlanDatei(ordner) {
+    let text;
+    try {
+        text = ohneBom(readFileSync(join(ordner, PLAN_PFAD), "utf8"));
+    }
+    catch {
+        return { ok: false, grund: "fehlt" };
+    }
+    const json = alsObjekt(text);
+    return json === null ? { ok: false, grund: "kein-json" } : { ok: true, text, json };
+}
+/**
+ * Traegt `projekt_id` und `basis` ein und leert `uebernommen` -- alles andere bleibt, wie es ist.
+ * 🔑 `uebernommenLeeren` ist PFLICHT, nicht optional: Nach `503 teilweise` ist der Plan gespeichert, die
+ * Rueckmeldungen aber noch nicht markiert (Ruling 10). Dann muss `basis` neu, `uebernommen` aber stehen
+ * bleiben -- sonst gingen sie beim zweiten Lauf verloren, und mit altem `basis` lehnte er als „veraltet" ab.
+ * Fehlen die beiden Felder, kommen sie hinter `projekt` (dort stehen sie im Beispiel der Spec), nicht ans Ende.
+ * Eingerueckt mit 2 Leerzeichen; Windows-Zeilenenden bleiben Windows-Zeilenenden.
+ * `false` heisst: nicht geschrieben (Datei weg, kein JSON mehr, Schreibschutz).
+ */
+export function schreibeNachHochladen(ordner, projektId, hochgeladenAm, uebernommenLeeren) {
+    const pfad = join(ordner, PLAN_PFAD);
+    try {
+        const roh = readFileSync(pfad, "utf8");
+        const alt = alsObjekt(ohneBom(roh));
+        if (alt === null)
+            return false;
+        const neu = {};
+        for (const [schluessel, wert] of Object.entries(alt)) {
+            neu[schluessel] = wert;
+            if (schluessel === "projekt") {
+                neu.projekt_id = projektId;
+                neu.basis = hochgeladenAm;
+            }
+        }
+        neu.projekt_id = projektId;
+        neu.basis = hochgeladenAm;
+        if (uebernommenLeeren)
+            neu.uebernommen = [];
+        const text = `${JSON.stringify(neu, null, 2)}\n`;
+        writeFileSync(pfad, roh.includes("\r\n") ? text.replace(/\n/g, "\r\n") : text, "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const SPEC_TEXT_GRENZE_JE = 300 * 1024; // kein-anzeigetext: Bytes
+export const SPEC_TEXT_GRENZE_ZUSAMMEN = 4 * 1024 * 1024; // kein-anzeigetext: Bytes
+/**
+ * Darf diese Datei gelesen werden? Nur ein relativer Pfad, der nach dem Aufloesen (auch einer Verknuepfung) im
+ * Projektordner bleibt und auf `.md` endet. 🔴 Positivliste: erst alles ausser dem Erlaubten abweisen -- die
+ * Schreibweisen fuer „woanders" (Laufwerk, Netzwerkpfad, Wurzel, `..`) sind nicht zu Ende aufzaehlbar.
+ * `wirklich` ist `realpathSync` (im Test ersetzt) und liefert `null`, wo es die Datei nicht gibt.
+ */
+export function specPfadPruefen(ordner, datei, wirklich) {
+    if (datei === null || datei.trim() === "")
+        return { ok: false, grund: "keine_datei" };
+    if (!/\.md$/i.test(datei))
+        return { ok: false, grund: "ausserhalb" };
+    // Laufwerk, Wurzel und Netzwerkpfad gelten auf JEDEM System als „woanders", auch wo `isAbsolute` sie nicht kennt.
+    if (isAbsolute(datei) || /^[A-Za-z]:/.test(datei) || /^[\\/]/.test(datei))
+        return { ok: false, grund: "ausserhalb" };
+    const innen = (wurzel, ziel) => {
+        const r = relative(wurzel, ziel);
+        return r !== "" && r.split(/[\\/]/)[0] !== ".." && !isAbsolute(r);
+    };
+    const ziel = resolve(ordner, datei);
+    if (!innen(resolve(ordner), ziel))
+        return { ok: false, grund: "ausserhalb" };
+    const echt = wirklich(ziel);
+    if (echt !== null && !innen(wirklich(resolve(ordner)) ?? resolve(ordner), echt))
+        return { ok: false, grund: "ausserhalb" };
+    return { ok: true, pfad: echt ?? ziel };
+}
+const wirklichOderNull = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+};
+/** `stand.json` -> die Koepfe der Specs; Unlesbares wird uebersprungen (ob der Plan stimmt, sagt allein der Server). */
+export function specKoepfeAus(json) {
+    if (!Array.isArray(json.specs))
+        return [];
+    return json.specs.flatMap((s) => {
+        if (!s || typeof s !== "object")
+            return [];
+        const r = s;
+        if (typeof r.schluessel !== "string")
+            return [];
+        return [{ schluessel: r.schluessel, titel: typeof r.titel === "string" ? r.titel : r.schluessel, datei: typeof r.datei === "string" ? r.datei : null }];
+    });
+}
+/** Wie gross der Text im JSON-Rumpf wird (mit Maskierung) -- danach wird der groesste gewaehlt, der herausfaellt. */
+const rumpfBytes = (text) => Buffer.byteLength(JSON.stringify(text), "utf8");
+/**
+ * Liest den Text jeder Spec. Jede Spec bekommt GENAU einen Eintrag: den Text oder den Grund, warum keiner da ist.
+ * Passt der fertige Anfrage-Rumpf nicht in 4 MB, werden die groessten Texte zu `zu_gross`, bis er passt (US-16:
+ * „am fertigen Anfrage-Rumpf"). `rumpf` baut genau den Rumpf, den `plan hoch` schickt (Stand, Schalter, Texte) --
+ * dieselbe Funktion baut ihn dort auch, damit gemessen wird, was hinausgeht (Befund M-3).
+ */
+export function leseSpecTexte(ordner, specs, rumpf) {
+    const keineTextdatei = new Set();
+    const eintraege = specs.map((s, i) => {
+        const ohne = (grund) => ({ schluessel: s.schluessel, grund, pfad: s.datei });
+        const pruefung = specPfadPruefen(ordner, s.datei, wirklichOderNull);
+        if (!pruefung.ok)
+            return ohne(pruefung.grund);
+        try {
+            const status = statSync(pruefung.pfad);
+            if (!status.isFile())
+                return ohne("fehlt");
+            if (status.size > SPEC_TEXT_GRENZE_JE)
+                return ohne("zu_gross");
+            const text = readFileSync(pruefung.pfad, "utf8");
+            if (Buffer.byteLength(text, "utf8") > SPEC_TEXT_GRENZE_JE)
+                return ohne("zu_gross");
+            // Ein Nullzeichen nimmt Postgres in `text` nicht an -- der Server lehnte den ganzen Aufruf ab (Befund M-1).
+            if (text.includes("\u0000")) {
+                keineTextdatei.add(i);
+                return ohne("fehlt");
+            }
+            return { schluessel: s.schluessel, text: ohneBom(text) };
+        }
+        catch {
+            return ohne("fehlt");
+        }
+    });
+    const groesse = () => Buffer.byteLength(JSON.stringify(rumpf(eintraege)), "utf8");
+    while (groesse() > SPEC_TEXT_GRENZE_ZUSAMMEN) {
+        let groesster = -1;
+        let groessterBytes = -1;
+        eintraege.forEach((e, i) => {
+            const b = "text" in e ? rumpfBytes(e.text) : -1;
+            if (b > groessterBytes) {
+                groesster = i;
+                groessterBytes = b;
+            }
+        });
+        if (groesster < 0)
+            break;
+        eintraege[groesster] = { schluessel: specs[groesster].schluessel, grund: "zu_gross", pfad: specs[groesster].datei };
+    }
+    const ohne = eintraege.flatMap((e, i) => "grund" in e ? [{ titel: specs[i].titel, grund: keineTextdatei.has(i) ? "keine_textdatei" : e.grund, pfad: e.pfad }] : []);
+    return { eintraege, ohne };
+}

package/dist/slash-befehle.js

@@ -5,6 +5,7 @@ export const SLASH_PAARE = [
     { de: "k3feierabend", en: "k3wrapup" }, // kein-anzeigetext: Befehlsname (Spec Teil 4, Abschnitt 6)
     { de: "k3kontext", en: "k3context" }, // kein-anzeigetext: Befehlsname
     { de: "k3projekt", en: "k3project" }, // kein-anzeigetext: Befehlsname
+    { de: "k3plan", en: "k3plan" }, // kein-anzeigetext: Befehlsname, in beiden Sprachen gleich (Spec 2026-10-21-projektseite-planung, C-7)
     { de: "k3liste", en: "k3list" }, // kein-anzeigetext: Befehlsname
     { de: "k3analyse", en: "k3analyse" }, // britisch, in beiden Sprachen gleich
     { de: "k3kurs", en: "k3course" }, // kein-anzeigetext: Befehlsname

package/dist/texte/plan.js

@@ -0,0 +1,93 @@
+const de = {
+    // ── plan.ts ──
+    listHelp: `
+  kimal3 plan
+
+  Holt die offenen Rückmeldungen zu deiner Planung aus der App: jedes
+  „passt nicht“ und jedes notierte Thema mit seiner Nummer, dazu die
+  bestätigten Stories der aktuellen Runden.
+
+  Liest plan/stand.json im Ordner, um das Projekt zu finden. Ändert nichts.
+`,
+    fileMissing: "Im Ordner liegt keine plan/stand.json. `/k3plan` legt sie an.",
+    noJson: "Der Plan ist nicht lesbar: plan/stand.json enthält kein gültiges JSON-Objekt.",
+    openVerdict: (nummer, spec, story, runde, notiz) => `#${nummer} · passt nicht · ${spec} / ${story} (Runde ${runde}): ${notiz}`,
+    openTopic: (nummer, notiz) => `#${nummer} · Thema: ${notiz}`,
+    noOpen: "Keine offenen Rückmeldungen.",
+    confirmed: (liste) => `Bestätigt: ${liste}`,
+    confirmedItem: (spec, story, runde) => `${spec} / ${story} (Runde ${runde})`,
+    view: (adresse) => `Ansehen: ${adresse}`,
+    // ── plan-hoch.ts ──
+    uploadHelp: `
+  kimal3 plan hoch [--ueberschreiben] [--probe]
+
+  Schickt plan/stand.json an dein Projekt in der App. Danach trägt es
+  projekt_id und basis in die Datei ein und leert uebernommen.
+
+  --probe            Prüft alles wie beim Hochladen und speichert nichts.
+
+  --ueberschreiben   Speichert auch dann, wenn in der App inzwischen ein
+                     neuerer Plan liegt (zwei Arbeitskopien).
+`,
+    uploaded: (titel, stories, deinTest) => `✓ Planung für „${titel}“ hochgeladen: ${stories === 1 ? "1 Story" : `${stories} Stories`}, ` +
+        `${deinTest === 1 ? "1 wartet" : `${deinTest} warten`} auf deinen Test.`,
+    dryRun: (stories, uebernommen) => `Probelauf: würde ${stories === 1 ? "1 Story" : `${stories} Stories`} hochladen, ` +
+        `${uebernommen === 1 ? "1 Rückmeldung" : `${uebernommen} Rückmeldungen`} als übernommen melden. Gespeichert wurde nichts.`,
+    // US-16: Eine Spec ohne Text ist ein Hinweis, kein Fehlschlag -- darum steht der Grund in Klammern hinter ihrem Namen.
+    specTextOhneGrund: (grund, pfad) => grund === "fehlt" ? `${pfad ?? ""} nicht gefunden`
+        : grund === "keine_datei" ? "keine Datei angegeben"
+            : grund === "ausserhalb" ? "Pfad außerhalb des Projekts"
+                : grund === "keine_textdatei" ? "keine Textdatei"
+                    : "größer als 300 KB",
+    specTexte: (angekommen, gesamt, ohne) => `Spec-Texte hochgeladen: ${angekommen} von ${gesamt}.${ohne.length === 0 ? "" : ` Ohne Text: ${ohne.join(", ")}.`}`,
+    specTextOhneEintrag: (titel, grundText) => `„${titel}“ (${grundText})`,
+    idNowInFile: "projekt_id und basis stehen jetzt in plan/stand.json.",
+    writeBackFailed: (projektId, hochgeladenAm, leeren) => "⚠ Die Planung ist gespeichert, aber plan/stand.json ließ sich nicht nachtragen. Trag selbst ein: " +
+        `"projekt_id": "${projektId}", "basis": "${hochgeladenAm}"${leeren ? ', "uebernommen": []' : ""}`,
+};
+const en = {
+    listHelp: `
+  kimal3 plan
+
+  Fetches the open responses to your planning from the app: every
+  “doesn't work” and every noted topic with its number, plus the
+  confirmed stories of the current rounds.
+
+  Reads plan/stand.json in this folder to find the project. Changes nothing.
+`,
+    fileMissing: "There's no plan/stand.json in this folder. `/k3plan` creates it.",
+    noJson: "The plan can't be read: plan/stand.json doesn't contain a valid JSON object.",
+    openVerdict: (nummer, spec, story, runde, notiz) => `#${nummer} · doesn't work · ${spec} / ${story} (round ${runde}): ${notiz}`,
+    openTopic: (nummer, notiz) => `#${nummer} · Topic: ${notiz}`,
+    noOpen: "No open responses.",
+    confirmed: (liste) => `Confirmed: ${liste}`,
+    confirmedItem: (spec, story, runde) => `${spec} / ${story} (round ${runde})`,
+    view: (adresse) => `View: ${adresse}`,
+    uploadHelp: `
+  kimal3 plan upload [--overwrite] [--dry-run]
+
+  Sends plan/stand.json to your project in the app. After that it enters
+  projekt_id and basis in the file and empties uebernommen.
+
+  --dry-run          Checks everything like an upload and saves nothing.
+
+  --overwrite        Saves even if the app already holds a newer plan
+                     (two working copies).
+
+  The German option names (--ueberschreiben, --probe) work too.
+`,
+    uploaded: (titel, stories, deinTest) => `✓ Planning for "${titel}" uploaded: ${stories === 1 ? "1 story" : `${stories} stories`}, ${deinTest} waiting for your test.`,
+    dryRun: (stories, uebernommen) => `Dry run: would upload ${stories === 1 ? "1 story" : `${stories} stories`} and mark ` +
+        `${uebernommen === 1 ? "1 response" : `${uebernommen} responses`} as handled. Nothing was saved.`,
+    specTextOhneGrund: (grund, pfad) => grund === "fehlt" ? `${pfad ?? ""} not found`
+        : grund === "keine_datei" ? "no file given"
+            : grund === "ausserhalb" ? "path outside the project"
+                : grund === "keine_textdatei" ? "not a text file"
+                    : "larger than 300 KB",
+    specTexte: (angekommen, gesamt, ohne) => `Spec texts uploaded: ${angekommen} of ${gesamt}.${ohne.length === 0 ? "" : ` Without text: ${ohne.join(", ")}.`}`,
+    specTextOhneEintrag: (titel, grundText) => `"${titel}" (${grundText})`,
+    idNowInFile: "projekt_id and basis are now in plan/stand.json.",
+    writeBackFailed: (projektId, hochgeladenAm, leeren) => "⚠ The planning is saved, but plan/stand.json couldn't be updated. Enter it yourself: " +
+        `"projekt_id": "${projektId}", "basis": "${hochgeladenAm}"${leeren ? ', "uebernommen": []' : ""}`,
+};
+export const PLAN_TEXTE = { de, en };