From 29e3d0ff742711501ac2588084621c4e0cd34c11 Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 7 Sep 2026 08:25:20 +0200 Subject: [PATCH] Document the laptop-to-home transfer without moving personal data into git. SQLite restore stays wave 1; Docker and Postgres stay wave 2. Session bootstrap for the switch is environment_handover.md plus the laptop and home work orders. Co-authored-by: Cursor --- README.md | 12 + .../functional/Idea_seconmd_sclide.md | 430 ++++++++++++++++++ .../functional/documentation_index.md | 6 +- docs/architecture/functional/handover.md | 4 +- .../functional/mvp_freeze_candidate.md | 2 +- .../technical/documentation_index.md | 19 +- .../technical/environment_handover.md | 213 +++++++++ .../technical/runtime_and_deploy.md | 20 +- .../debug_diagnostics_perfection.md | 204 +++++++++ .../dialogue_memory_next_slice_handover.md | 229 ++++++++++ docs/work_orders/home_environment_setup.md | 158 +++++++ docs/work_orders/laptop_closeout.md | 87 ++++ 12 files changed, 1374 insertions(+), 10 deletions(-) create mode 100644 docs/architecture/functional/Idea_seconmd_sclide.md create mode 100644 docs/architecture/technical/environment_handover.md create mode 100644 docs/work_orders/debug_diagnostics_perfection.md create mode 100644 docs/work_orders/dialogue_memory_next_slice_handover.md create mode 100644 docs/work_orders/home_environment_setup.md create mode 100644 docs/work_orders/laptop_closeout.md diff --git a/README.md b/README.md index 2fab3f3..869729c 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ Fachliche Konzeption, technische Rahmenarchitektur und der erste **vertikale MVP Remote: [gitea.stommer.de/Lars/Kansho](https://gitea.stommer.de/Lars/Kansho.git) +Die Urlaubs-Laptop-Instanz lief ohne Docker auf SQLite. Heimtransfer, Backup und späterer Server-/Postgres-Pfad: `docs/architecture/technical/environment_handover.md`. + ## Dokumentation zuerst laden Nicht alle Kapitel gleichzeitig in den Kontext ziehen. Der Index beschreibt sinnvolle Bundles: @@ -87,6 +89,16 @@ Lokales Backup der Urlaubs-Testdaten (persönlich, unverschlüsselt, ohne `.env` Restore bestätigt ausdrücklich, legt vorher ein Sicherheitsbackup an und überschreibt nie still. Backend währenddessen beenden. +## Transfer auf die Heim-Umgebung + +Persönliche Daten liegen **nicht** in Git. Vor einem Rechnerwechsel: + +1. `.\scripts\backup-local.ps1 create` und das Zip plus `backend/.env` getrennt, verschlüsselt kopieren. +2. Zu Hause klonen, `.\scripts\dev-setup.ps1`, Restore mit `-Confirm -Replace`. +3. Docker/Postgres sind Welle 2, nicht der erste Restore. + +Details und Checklisten: `docs/architecture/technical/environment_handover.md`, `docs/work_orders/laptop_closeout.md`, `docs/work_orders/home_environment_setup.md`. + ## Lokal weiterarbeiten ```powershell diff --git a/docs/architecture/functional/Idea_seconmd_sclide.md b/docs/architecture/functional/Idea_seconmd_sclide.md new file mode 100644 index 0000000..91555fb --- /dev/null +++ b/docs/architecture/functional/Idea_seconmd_sclide.md @@ -0,0 +1,430 @@ +Du arbeitest im Kanshō-Repository als **fachlicher Konzept-Worker**. + +Deine Aufgabe ist ausdrücklich **nicht**, Slice 2 zu implementieren oder technische Detailarchitektur vorwegzunehmen. Du sollst auf Basis der bestehenden kanonischen Fachkonzepte einen **fachlich belastbaren Vorschlag und Anforderungsschnitt für den zweiten vertikalen Produktslice** erarbeiten, der anschließend als Grundlage für einen Coding Agent dienen kann. + +## Ausgangslage + +Der erste MVP-Slice ist abgeschlossen. + +Er realisiert einen journalzentrierten Anwendungsfall innerhalb eines Reflection Space: + +- Beispiel Reflection Space: `Veli Lošinj 2026` +- pro Tag kann es einen Journal Day geben +- pro Tag können mehrere Conversations/Chats geführt werden +- der Nutzer kann entscheiden, welcher Dialog bzw. welche Dialoge als Inputquelle für die Journalgenerierung verwendet werden +- der ausgewählte Dialog wird **nicht direkt als Tagebucheintrag übernommen** +- aus dem Dialog wird mehrstufig mit Hilfe der KI und des persönlichen Writing Profile ein persönlicher Journal Draft generiert +- dieser Draft kann anschließend redigiert und als Journal Entry übernommen werden +- das Ergebnis soll insbesondere bei Reise-/Urlaubstagebüchern eine zusammenhängende, menschenlesbare autobiografische Erinnerung ergeben + +Diese Fähigkeit ist wertvoll und darf durch Slice 2 **nicht verschlechtert oder fachlich entwertet** werden. + +Gleichzeitig bildet dieser MVP nur eine Teilmenge des Kanshō-Zielbilds ab. + +Kanshō soll langfristig ein **Personal Reflection Companion** sein und nicht auf Tagesjournal bzw. Tagebuch beschränkt bleiben. + +## Bestehendes fachliches Zielbild + +Die vorhandenen Fachkonzepte unterscheiden insbesondere: + +### Reflection Space + +Der Reflection Space beschreibt den Bedeutungs-, Lebens- oder Erfahrungskontext. + +Beispiele: + +- `Urlaub → Veli Lošinj 2026` +- persönliche Entwicklung +- Beruf +- Familie +- ein konkretes längerfristiges persönliches Thema + +Ein Reflection Space ist kein bloßer Ordner und kein Intent. Er bildet für den Nutzer einen verständlichen Denk- und Erfahrungsraum und soll ein wesentliches menschliches Ordnungsprinzip bleiben. + +### Nutzungssituation / Reflection Intent + +Die bestehende Fachkonzeption beschreibt elf vorläufig vollständige Nutzungssituationen: + +1. Erleben festhalten +2. Tagesreflexion +3. Spontaner Gedanke / Moment +4. Früheren Faden fortsetzen +5. Tiefe Reflexion / biografische Frage +6. Entscheidung / Orientierung +7. Inspiration / Vision / Kreativität +8. Achtsamkeit / Meditation / Check-in +9. Rückblick und persönliche Entwicklung +10. Geplante Reflexionszeit / Ritual +11. Wiederfinden und Revue passieren + +Diese Nutzungssituationen sind **keine elf Reflection Spaces und keine Verpflichtung zu elf technischen Intent Engines**. + +Sie beschreiben, was der Nutzer in einer konkreten Interaktion gerade erreichen möchte. + +Der Reflection Intent kann: + +- explizit durch den Nutzer gesetzt werden, +- von Kanshō aus Einstieg und Kontext erkannt werden, +- sich im Verlauf derselben Conversation verändern. + +Ein Intent-Wechsel soll einen natürlichen Dialog nicht automatisch in mehrere Chats zerlegen. + +### Threads + +Eine Conversation kann mehrere Reflexionsfäden enthalten. + +Threads dienen langfristiger inhaltlicher Kontinuität und können über Conversations, Tage und ggf. Reflection Spaces hinweg weiterlaufen. + +Nicht jedes Seitenthema soll automatisch einen sichtbaren oder langlebigen Thread erzeugen. + +### Memory und Context + +Die bestehende Baseline lautet insbesondere: + +- aktueller Dialog zuerst +- Primary Reflection Space vor globalem Langzeitgedächtnis +- Long-Term Memory nur bei tatsächlichem Bedarf +- Minimum sufficient context +- Retrieval findet Kandidaten; Context-Auswahl entscheidet Relevanz +- semantische Ähnlichkeit allein ist kein Relevanznachweis +- Source bleibt kanonisch +- Derived ersetzt Source nicht +- Current Validity und History bleiben getrennt +- Nutzerkorrekturen haben Vorrang +- langfristige Dialogkontinuität muss unter Kontrolle von Kanshō bleiben + +Die bestehende fachliche Eskalation ist sinngemäß: + +`Current Session → Primary Reflection Space → aktive Threads / offene Fragen → relevanter Reflection Context → relevantes Kanshō Long-Term Memory → mindnet → Original Sources / Re-Grounding` + +### Reflection Outputs + +Ein Dialog kann mehrere unterschiedliche Ergebnisse erzeugen. + +Beispielsweise: + +- Journal Entry +- Reflection Memory +- Knowledge Delta +- Action Candidate +- interne Kontinuitätsstrukturen wie Thread Memory oder offene Fragen + +Nicht jede Conversation muss ein sichtbares Output-Artefakt erzeugen. + +## Zentrale Fragestellung für Slice 2 + +Der nächste Slice soll das heute journalzentrierte System zu einem allgemeineren dialogischen Reflexionsbegleiter weiterentwickeln. + +Dabei muss insbesondere geprüft werden: + +> Wie kann ein Reflection Space unterschiedliche Reflection Intents und natürlich gemischte Conversations tragen, ohne dass dadurch die heute bereits gut funktionierende Fähigkeit verloren geht, aus einem oder mehreren ausgewählten Dialogen einen kohärenten persönlichen Tages- bzw. Reisetagebucheintrag zu generieren? + +Beispiel: + +Im Reflection Space `Veli Lošinj 2026` beginnt eine Conversation mit der Beschreibung des Urlaubstags. + +Während des Gesprächs sagt der Nutzer beispielsweise: + +> „Mir fällt auf, dass ich hier im Urlaub viel bewusster lebe als zu Hause.“ + +Daraus kann sich eine längere tiefere Reflexion entwickeln. + +Danach erzählt der Nutzer möglicherweise wieder weiter vom Tagesgeschehen. + +Die Conversation enthält damit mindestens: + +- autobiografisches Tageserleben +- persönliche Reflexion +- möglicherweise einen längerfristig relevanten Reflexionsfaden + +Trotzdem soll aus diesem Dialog weiterhin ein **guter zusammenhängender Journal Entry über den Urlaubstag** generiert werden können. + +Dabei darf weder gelten: + +- „der vollständige Dialog muss ungefiltert in den Journalentwurf einfließen“ + +noch: + +- „alles, was während eines anderen Reflection Intents gesagt wurde, darf grundsätzlich nicht in das Journal“ + +Denn eine persönliche Reflexion kann sehr wohl ein wichtiger Teil der autobiografischen Erinnerung dieses Tages sein. + +## Deine Aufgabe + +Erarbeite daraus einen **fachlichen Vorschlag für Slice 2**. + +Prüfe dabei insbesondere folgende Punkte. + +### 1. Produktthese des Slices + +Formuliere präzise: + +- welche neue Nutzerfähigkeit Slice 2 beweisen soll, +- warum diese nach dem Journal-MVP der sinnvollste nächste vertikale Schritt ist, +- welche Teile des Kanshō-Zielbilds dadurch erstmals real validiert werden. + +Vermeide einen rein technischen „Memory-Ausbau“ als Produktthese. + +### 2. Reflection Space als Ordnungsrahmen + +Prüfe und konkretisiere: + +- welche Rolle Reflection Spaces im Slice spielen, +- wie sie für den Nutzer als nachvollziehbares Ordnungsprinzip erhalten bleiben, +- wie Conversations mit unterschiedlichen Intents innerhalb desselben Space organisiert werden, +- wie verhindert wird, dass Threads, Memories, Intents und Derived Objects zu einer unübersichtlichen sichtbaren Struktur führen. + +Beachte dabei die bestehende Leitlinie: + +> interne Reichhaltigkeit darf deutlich größer sein als die sichtbare Nutzerstruktur. + +### 3. Multi-Intent Conversation + +Definiere fachlich: + +- wie der initiale Reflection Intent entsteht, +- wie expliziter Nutzer-Intent und automatische Erkennung zusammenspielen, +- wie sich Intent innerhalb derselben Conversation verändern darf, +- welche Auswirkungen Intent auf Dialogtiefe, Richtung, Initiative und Kontextnutzung besitzt, +- welche Zustände tatsächlich langlebig gespeichert werden müssen und welche nur operative Dialogsteuerung sein können. + +Lege **nicht vorschnell eine neue reduzierte Intent-Taxonomie** fest. + +Wenn mehrere fachliche Intents dieselbe technische Dialog-/Context-Policy verwenden könnten, darfst du dies als spätere technische Verdichtung benennen. Die elf fachlichen Nutzungssituationen sollen dadurch jedoch nicht stillschweigend ersetzt werden. + +### 4. Erhalt des Journal-Workflows + +Dies ist ein **zentrales Acceptance-Thema des Slices**. + +Beschreibe fachlich, wie der bestehende Workflow erhalten bleiben kann: + +`Reflection Space → Journal Day → ein oder mehrere Dialoge als Input auswählen → mehrstufige KI-Generierung mit Writing Profile → Journal Draft → Nutzerredaktion → Journal Entry` + +Berücksichtige dabei insbesondere gemischte Conversations. + +Klärungsbedarf: + +- Wie entscheidet sich fachlich, welche Inhalte eines gemischten Dialogs für einen konkreten Journal Draft relevant sind? +- Welche Rolle spielen Reflection Intent, Tagesbezug, Ereignisbezug, Nutzerwahl und andere Signale? +- Kann ein und derselbe Gesprächsabschnitt für mehrere fachliche Ergebnisse relevant sein? +- Wie bleibt der Originaldialog die Quelle? +- Welche fachliche Provenance zwischen Quelle und Output wird benötigt? +- Muss dafür ein eigenes langlebiges Segmentobjekt entstehen oder reicht fachlich zunächst die Fähigkeit, Outputs auf relevante Message-/Source-Bereiche zurückzuführen? +- Welche dieser Fragen muss Slice 2 tatsächlich lösen und welche darf offen bleiben? + +Wichtig: + +Der Nutzer soll weiterhin auf grober Ebene entscheiden können, welche Conversation(s) eines Tages als Inputquelle für den Journal Draft dienen. + +Kanshō darf innerhalb dieser Quellen eine feinere inhaltliche Relevanzbewertung übernehmen, ohne daraus eine komplexe Segmentverwaltungsoberfläche für den Nutzer zu machen. + +### 5. Threads und Kontinuität + +Bestimme den minimal notwendigen Umfang für Slice 2. + +Prüfe: + +- wann ein Nebenfaden lediglich temporärer Gesprächskontext bleibt, +- wann daraus ein Thread Candidate entstehen kann, +- wann ein langlebiger Thread erforderlich ist, +- wie ein bereits bestehender Thread später fortgesetzt werden kann, +- welches minimale Thread Memory dafür benötigt wird. + +Vermeide eine vollständige Thread-Ontologie oder umfangreiche automatische Thread-Verwaltung, wenn sie für diesen Slice nicht erforderlich ist. + +### 6. Memory und Context Builder + +Beschreibe den minimal notwendigen fachlichen Memory-Ausbau. + +Insbesondere: + +- welche Memory-/Context-Schichten Slice 2 tatsächlich benötigt, +- wie der Reflection Intent die Context-Auswahl beeinflusst, +- welche früheren Informationen bei unterschiedlichen Intents eher relevant sind, +- wie `Reflection Space first, Long-Term Memory on demand` erhalten bleibt, +- wie verhindert wird, dass globale autobiografische Suche zum Normalfall jedes Turns wird. + +Prüfe ausdrücklich, welche Fähigkeiten **noch nicht** notwendig sind. + +### 7. Persistenz und Outputs + +Klär fachlich, welche langlebigen Ergebnisse Slice 2 benötigt. + +Beispielsweise: + +- Journal Entry +- Thread Memory +- Open Question +- Reflection Memory / Insight +- ggf. andere Derived Objects + +Nicht jedes mögliche Target-Objekt soll automatisch Bestandteil des Slices werden. + +Für jedes vorgeschlagene langlebige Objekt beantworte: + +- Warum benötigt der aktuelle Slice dieses Objekt jetzt? +- Würde ein späteres Nachrüsten sonst eine grundlegende Refaktierung erzwingen? +- Ist es sichtbares Nutzerartefakt oder primär interne Kontinuitätsstruktur? + +Beachte die Implementation Foundation: + +> Neue Abstraktionen benötigen aktuellen Nutzen. + +### 8. Current Validity, Correction und Provenance + +Sobald Derived Memory produktiv für spätere Dialoge verwendet wird, müssen mindestens die bestehenden Foundation-Regeln eingehalten werden: + +- Source bleibt kanonisch +- Derived ersetzt Source nicht +- Zeit und Provenance +- Current Validity vs. History +- User Correction > Model Inference + +Prüfe, welcher **minimale fachliche Korrektur- und Re-Grounding-Umfang** für Slice 2 wirklich notwendig ist. + +Baue daraus nicht automatisch eine umfangreiche Provenance- oder Memory-Administration als Produktfeature. + +### 9. Auswahl der Nutzungssituationen für Slice 2 + +Mappe alle elf bestehenden Nutzungssituationen auf: + +- bereits durch MVP abgedeckt / Regression Case +- Bestandteil Slice 2 +- bewusst später + +Begründe die Auswahl. + +Prüfe insbesondere, ob für Slice 2 zusätzlich zum bestehenden Journalpfad folgende Situationen geeignet sind: + +- Spontaner Gedanke / Moment +- Früheren Faden fortsetzen +- Tiefe Reflexion / biografische Frage +- Entscheidung / Orientierung + +Übernimm diese Auswahl aber nicht ungeprüft. Wenn du einen engeren oder besseren vertikalen Schnitt begründen kannst, schlage ihn vor. + +### 10. Acceptance Scenarios + +Definiere wenige, aber harte End-to-End-Szenarien. + +Mindestens zu prüfen: + +#### A. Bestehendes Reisetagebuch als Regression + +Space `Veli Lošinj 2026`. + +Der Nutzer führt einen überwiegend autobiografischen Tagesdialog. + +Der bestehende Journalworkflow funktioniert weiterhin mindestens so gut wie im MVP. + +#### B. Gemischter Urlaubsdialog + +Ein Dialog beginnt mit Tageserleben, geht in tiefere persönliche Reflexion über und kehrt anschließend zum Tageserleben zurück. + +Aus dem Dialog kann weiterhin ein kohärenter persönlicher Journal Draft entstehen. + +Die tiefere Reflexion darf dabei weder ungeprüft vollständig in das Journal übernommen noch pauschal ausgeschlossen werden. + +#### C. Freie Nicht-Journal-Reflexion + +Der Nutzer beginnt innerhalb eines Reflection Space mit einer persönlichen Frage. + +Kein Journal Day ist zwingend erforderlich. + +Kanshō führt intentgerecht einen tieferen Reflexionsdialog. + +#### D. Früheren Faden fortsetzen + +Nach mehreren Tagen wird ein bestehender relevanter Reflexionsfaden fortgesetzt. + +Der Nutzer muss den bisherigen Denkstand nicht erneut vollständig erklären. + +#### E. Intent-Wechsel + +Der Intent verändert sich innerhalb derselben Conversation, ohne dass der Nutzer einen neuen Chat starten muss. + +#### F. Kein relevantes Memory + +Kanshō führt einen natürlichen Dialog, ohne künstlich frühere Erinnerungen oder Zusammenhänge anzudeuten. + +### 11. Explizite Non-Goals + +Grenze den Slice klar gegen das spätere Zielmodell ab. + +Prüfe insbesondere als Non-Goals: + +- vollständiges Self Model +- langfristige automatische Pattern-Erkennung +- globales semantisches Retrieval über die gesamte Biografie +- vollständiger Reflection Graph +- komplexes Resurfacing +- umfassende Thread-Ontologie +- automatische Promotion jedes Gedankens +- mindnet-/Kairo-/Obsidian-Vollintegration +- Meditation/Achtsamkeit als eigener großer Interaction Slice +- vollständiger Entwicklungsrückblick +- Revue-/Recall-System +- elf technische Intent Engines + +### 12. Auswirkungen auf bestehende Fachkonzepte + +Prüfe zum Abschluss: + +- welche bestehenden Fachentscheidungen der Slice lediglich konkretisiert, +- wo tatsächlich eine neue fachliche Entscheidung erforderlich ist, +- welche Dokumente später additiv aktualisiert werden müssten, +- ob irgendwo bestehende Konzepte widersprüchlich oder für den Slice noch unzureichend sind. + +Ändere keine kanonischen Dateien in diesem Arbeitsschritt. + +## Zu lesende kanonische Grundlage + +Lade mindestens: + +- `docs/architecture/functional/produktvision_und_produktidentitaet.md` +- `docs/architecture/functional/usage_situations.md` +- `docs/architecture/functional/reflection_spaces.md` +- `docs/architecture/functional/dialogue_model.md` +- `docs/architecture/functional/memory_and_context.md` +- `docs/architecture/functional/reflection_outputs.md` +- `docs/architecture/functional/implementation_foundation.md` + +Zusätzlich gezielt, soweit für konkrete Entscheidungen erforderlich: + +- `resurfacing_and_saturation.md` +- `context_fidelity_and_regrounding.md` +- `writing_profile_and_journaling.md` +- `mvp.md` +- aktuelle technische MVP-Dokumentation beziehungsweise Code nur zur Prüfung von Ist-Stand und Migrationsrisiko + +Verwende `mvp_stand_und_abgleich.md` nur mit Vorsicht als historischen Snapshot, falls der aktuelle Repo-Stand inzwischen weiterentwickelt wurde. + +## Erwartetes Ergebnis + +Liefere einen strukturierten fachlichen Slice-Vorschlag mit: + +1. Executive Summary +2. Produktthese +3. fachlichem Zielbild des Slices +4. Fit-Gap zum abgeschlossenen Journal-MVP +5. Mapping der elf Nutzungssituationen +6. Rollen von Space, Conversation, Intent, Thread, Memory und Output +7. Journal-Regressionsmodell einschließlich gemischter Conversations +8. minimalem Memory-/Continuity-Umfang +9. notwendigen fachlichen Objekten und Beziehungen +10. Acceptance Scenarios und Acceptance Criteria +11. expliziten Non-Goals +12. offenen Produktentscheidungen +13. empfohlenen Dokumentationsänderungen +14. klarer Empfehlung, ob dieser Slice der optimale nächste vertikale Schritt ist oder ob ein kleinerer/besserer Schnitt vorzuziehen ist + +Wichtig: + +- Keine Implementierung beginnen. +- Keine Dateien verändern. +- Keine Target Capabilities allein deshalb vorbauen, weil sie im Gesamtmodell existieren. +- Fachliche Anforderungen und technische mögliche Umsetzung klar trennen. +- Bestehende Entscheidungen nicht stillschweigend ersetzen. +- Bei Widersprüchen zwischen Dokumenten diese explizit benennen. +- Den bestehenden Reisetagebuch-Workflow als harte Regression behandeln. +- Ziel ist ein **umsetzbarer vertikaler Slice**, nicht eine neue vollständige Kanshō-Gesamtarchitektur. \ No newline at end of file diff --git a/docs/architecture/functional/documentation_index.md b/docs/architecture/functional/documentation_index.md index bf9987f..e036b54 100644 --- a/docs/architecture/functional/documentation_index.md +++ b/docs/architecture/functional/documentation_index.md @@ -1,7 +1,7 @@ --- title: "Kanshō – Dokumentationsindex und Context Bundles" status: "Arbeitsstand" - date: "2026-08-18" + date: "2026-09-07" product_family: "Jinkendo" document_role: "Documentation Index / Context Loading Guide" parent_document: "fachliche_zielarchitektur.md" @@ -13,7 +13,7 @@ Dieses Dokument dient dazu, für weitere Konzeptarbeit nur die tatsächlich ben ## 1. Root-Dokumente -- `handover.md` – Session-Bootstrap für die **Konzept-/Interviewarbeit**; nicht der Code-Stand. Implementierungsstand und Fit-Gap: `mvp_stand_und_abgleich.md`. +- `handover.md` – Session-Bootstrap für die **Konzept-/Interviewarbeit**; nicht der Code-Stand. Implementierungsstand und Fit-Gap: `mvp_stand_und_abgleich.md`. Umgebungswechsel Laptop → Heim/Server: `../technical/environment_handover.md`. - `fachliche_zielarchitektur.md` – Governance, Dokumentationsprinzipien, Querschnittsinvarianten, Dateistruktur. - `produktvision_und_produktidentitaet.md` – Vision, Identität, Scope, Produktprinzipien und Nicht-Ziele. - `interview_plan.md` – Kapitelplan, Interviewmethode, Fortschritt und nächster Interviewblock. @@ -103,6 +103,8 @@ Sie übernimmt den Produktrahmen **weitgehend von Mitai**. Datenschutz, Privacy Technische Umsetzung des gebauten Journal-Slices: `../technical/mvp_implementation.md`. Fit-Gap bleibt fachlich: `mvp_stand_und_abgleich.md`. +Arbeitsaufträge (kein Ersatz kanonischer Kapitel): `docs/work_orders/` – Laptop-Abschluss, Heim-Setup, Debug-Export, Dialog/Memory-Slice. Slice-2-Konzeptbrief derzeit `Idea_seconmd_sclide.md`. + ## 5. Ladeprinzip > **Nicht alle Kanshō-Dokumente gleichzeitig laden.** Root-Dokumente plus die 2–4 fachlich betroffenen Dateien bilden den Standardkontext. diff --git a/docs/architecture/functional/handover.md b/docs/architecture/functional/handover.md index 69f6d57..97204a9 100644 --- a/docs/architecture/functional/handover.md +++ b/docs/architecture/functional/handover.md @@ -15,7 +15,9 @@ canonical_docs_path: "docs/architecture/functional/" Dieses Dokument ist der **vollständige fachliche Aufsatzpunkt für eine neue Kanshō-Konzept-Session**. -**Implementierungsstand (Code)** steht nicht hier, sondern in `mvp_stand_und_abgleich.md` (2026-08-25): Slice gegen Foundation, MVP-Text und Gesamtziel. Dieses Handover bleibt der Konzept-/Interview-Bootstrap. +**Implementierungsstand (Code)** steht nicht hier, sondern in `mvp_stand_und_abgleich.md` (2026-08-25, Opening-Additiv 2026-09-03/07): Slice gegen Foundation, MVP-Text und Gesamtziel. Dieses Handover bleibt der Konzept-/Interview-Bootstrap. + +**Umgebungswechsel Laptop → Heim/Server (2026-09-07):** nicht hier, sondern `docs/architecture/technical/environment_handover.md` plus `docs/architecture/technical/runtime_and_deploy.md` §7.2. Opening-Invariante (kein Folgetag aus Entry-Prefix): `mvp.md` §6.1. Es soll ermöglichen, die Arbeit ohne Rückgriff auf den langen bisherigen Chat fortzusetzen und dabei insbesondere verhindern, dass: diff --git a/docs/architecture/functional/mvp_freeze_candidate.md b/docs/architecture/functional/mvp_freeze_candidate.md index 81f0a16..15f5104 100644 --- a/docs/architecture/functional/mvp_freeze_candidate.md +++ b/docs/architecture/functional/mvp_freeze_candidate.md @@ -43,7 +43,7 @@ Nicht durch Fake-Provider bewiesen: Kein Codefehler des Freeze Candidate, sondern Betriebsreife: -- PostgreSQL, Docker/Compose, TLS, Reverse Proxy +- PostgreSQL, Docker/Compose, TLS, Reverse Proxy — **nach** SQLite-Restore der Urlaubsdaten (`../technical/environment_handover.md`, `../technical/runtime_and_deploy.md` §7.2) - Gitea-Pipelines / CI - Ollama bzw. lokales Detect-Modell - Verschlüsselung at rest, DSFA, persistentes Audit ohne Prompts diff --git a/docs/architecture/technical/documentation_index.md b/docs/architecture/technical/documentation_index.md index 7d7aed9..ba4039e 100644 --- a/docs/architecture/technical/documentation_index.md +++ b/docs/architecture/technical/documentation_index.md @@ -2,7 +2,7 @@ title: "Kanshō – Technischer Dokumentationsindex und Context Bundles" version: "0.1" status: "Arbeitsstand" -date: "2026-08-19" +date: "2026-09-07" product_family: "Jinkendo" document_role: "Documentation Index / Technical Context Loading Guide" parent_document: "technische_zielarchitektur.md" @@ -33,7 +33,8 @@ Fachlich zusätzlich immer bei Querschnittsentscheidungen: | `auth_identity_and_roles.md` | Sessions, Rollen, Admin-Gate | | `frontend_pwa_shell.md` | PWA, Responsive Shell, Navigation | | `backend_and_api.md` | Router, API-First | -| `runtime_and_deploy.md` | Migrationen, Compose, Gitea | +| `runtime_and_deploy.md` | Migrationen, Compose, Gitea; Transfer Laptop → Heim §7.2 | +| `environment_handover.md` | **Session-Handover Umgebungswechsel** (SQLite-Ist, Backup, zwei Wellen, offene Host-Fragen) | | `platform_extensibility.md` | Registry, Prompt-Engine, Konfiguration | | `data_architecture.md` | Persistenzgrenzen, Entitäten | | `memory_storage_and_offline.md` | Dialogspeicher, Sync, Offline | @@ -126,6 +127,18 @@ Kanonisches Home **wie** der Slice gebaut ist: `mvp_implementation.md`. Fachlich 4. `privacy_gateway.md` (eigener Egress-Typ) 5. fachlich: `../functional/produktvision_und_produktidentitaet.md` §19.4–19.5 +### Umgebungswechsel Laptop → Heim / Server + +1. `environment_handover.md` +2. `runtime_and_deploy.md` +3. `product_frame_and_stack.md` +4. `mvp_implementation.md` §1 und §4 +5. `../../work_orders/laptop_closeout.md` +6. `../../work_orders/home_environment_setup.md` +7. fachlich: `../functional/guardrails.md` (Datenklassen beim Kopieren von Backup und `.env`) + +Arbeitsaufträge liegen unter `docs/work_orders/`. Sie ersetzen keine kanonischen Kapitel. + ## 4. Ladeprinzip > Root-Dokumente plus 2–4 betroffene Kapitel. Nicht den ganzen technischen und fachlichen Ordner gleichzeitig laden. @@ -134,5 +147,5 @@ Vor Vereinfachungen die Invariantenliste in `technische_zielarchitektur.md` §3. ## 5. Code-Gerüst -Lokaler Produktrahmen in `frontend/` und `backend/`. Zusammenhängende technische Umsetzung: `mvp_implementation.md`. Auth, Nutzerverwaltung, Prompt-DB, Platzhalter, Feature-Check, Privacy Gateway. **Dialog-Layer 0:** Conversations/Messages/`usage_sessions`, Thread-/Space-Identität, Derived-Hülle mit Provenance. **MVP-Journal-Slice:** nutzersichtbare Spaces, Journal Days, Dialogzug (ein Call), explizite Draft-Generierung, versionierte Entries (Übernehmen = neue Version, Dirty-Schutz im Editor), Inline-Medien, lokale Stichpunkte ohne Egress, Writing Profile (Hülle mit dynamischen Traits, Initial Profile Build). Fit-Gap: `../functional/mvp_stand_und_abgleich.md` (2026-08-25). Konfigurierbare Prompts `mvp.dialogue_turn`, `mvp.journal_reconstruct`, `mvp.journal_generate`, `mvp.entity_detect`, `mvp.profile_review`. Persönliche Folgestufen konsumieren ein lokal erzeugtes `VerifiedArtifact` (`provenance_verification.md`); der Journal-Adapter setzt die Policy. Journal-Generate: Stufe 1 lokal (`local_source_artifact`), Stufe 2 ein Narrations-Call (Faktentreue, eigenständige Journalprosa, nicht Wortlautkopie). Journalspezifische Ausgabeeinstellungen lokal kompiliert (`journal_generation_policy.py`); Anweisungstexte in `generation_instruction_fragments`, nicht im Code; das ist keine Modelltemperatur. **Additiv 2026-08-29:** Voice-Ausprägungen tragen `style_context_json` (Freigabe von Core/Facet/Traits/Style Examples). Opt-in-Vergleich: `backend/journal_eval.py` (nicht Produktionslauf; Live nur explizit über das Privacy Gateway). Request-scoped Maskierungsmanifest und Pre-Egress: `privacy_gateway.md` §9.4. Semantische Request-Detection und bestätigte Registry: `privacy_gateway.md` §9.5. Provider-URL/Modell/Policy unter Admin → Schnittstellen; Keys nur in `backend/.env`. Schichten: Maskierung, Dialogzug, Journalentwurf, explizite Profile-Review. Admin-Testspur am Dialogzug (Egress, Antwort, Operation). **Additiv 2026-08-28:** opt-in lokale Persistenz unter `/admin/debug` (Default aus, kein Mapping). Privacy-Pfad durchgängig, Security Layer nicht vollständig (`privacy_gateway.md` §9.2). Kein Stripe, keine Threads-UI, kein semantisches Retrieval. SQLite nur lokal. +Lokaler Produktrahmen in `frontend/` und `backend/`. Zusammenhängende technische Umsetzung: `mvp_implementation.md`. Auth, Nutzerverwaltung, Prompt-DB, Platzhalter, Feature-Check, Privacy Gateway. **Dialog-Layer 0:** Conversations/Messages/`usage_sessions`, Thread-/Space-Identität, Derived-Hülle mit Provenance. **MVP-Journal-Slice:** nutzersichtbare Spaces, Journal Days, Dialogzug (ein Call), explizite Draft-Generierung, versionierte Entries (Übernehmen = neue Version, Dirty-Schutz im Editor), Inline-Medien, lokale Stichpunkte ohne Egress, Writing Profile (Hülle mit dynamischen Traits, Initial Profile Build). Fit-Gap: `../functional/mvp_stand_und_abgleich.md` (2026-08-25). Konfigurierbare Prompts `mvp.dialogue_turn`, `mvp.journal_reconstruct`, `mvp.journal_generate`, `mvp.entity_detect`, `mvp.profile_review`. Persönliche Folgestufen konsumieren ein lokal erzeugtes `VerifiedArtifact` (`provenance_verification.md`); der Journal-Adapter setzt die Policy. Journal-Generate: Stufe 1 lokal (`local_source_artifact`), Stufe 2 ein Narrations-Call (Faktentreue, eigenständige Journalprosa, nicht Wortlautkopie). Journalspezifische Ausgabeeinstellungen lokal kompiliert (`journal_generation_policy.py`); Anweisungstexte in `generation_instruction_fragments`, nicht im Code; das ist keine Modelltemperatur. **Additiv 2026-08-29:** Voice-Ausprägungen tragen `style_context_json` (Freigabe von Core/Facet/Traits/Style Examples). Opt-in-Vergleich: `backend/journal_eval.py` (nicht Produktionslauf; Live nur explizit über das Privacy Gateway). Request-scoped Maskierungsmanifest und Pre-Egress: `privacy_gateway.md` §9.4. Semantische Request-Detection und bestätigte Registry: `privacy_gateway.md` §9.5. Provider-URL/Modell/Policy unter Admin → Schnittstellen; Keys nur in `backend/.env`. Schichten: Maskierung, Dialogzug, Journalentwurf, explizite Profile-Review. Admin-Testspur am Dialogzug (Egress, Antwort, Operation). **Additiv 2026-08-28:** opt-in lokale Persistenz unter `/admin/debug` (Default aus, kein Mapping). Privacy-Pfad durchgängig, Security Layer nicht vollständig (`privacy_gateway.md` §9.2). Kein Stripe, keine Threads-UI, kein semantisches Retrieval. SQLite nur lokal. **Additiv 2026-09-07:** Umgebungswechsel der Urlaubsinstanz: `environment_handover.md`. diff --git a/docs/architecture/technical/environment_handover.md b/docs/architecture/technical/environment_handover.md new file mode 100644 index 0000000..0ab8e41 --- /dev/null +++ b/docs/architecture/technical/environment_handover.md @@ -0,0 +1,213 @@ +--- +title: "Kanshō – Handover Laptop-Instanz → Heim-Entwicklung und Server" +status: "Aktiver Übergabestand" +date: "2026-09-07" +product_family: "Jinkendo" +document_role: "Session Handover / Environment Transfer / Implementation Bootstrap" +parent_document: "runtime_and_deploy.md" +canonical_concept_handover: "docs/architecture/functional/handover.md" +--- + +# Kanshō – Handover: Laptop-Urlaubsinstanz → normale Entwicklung und Server + +Dieses Dokument ist der **technische Aufsatzpunkt** für den Umgebungswechsel. Es ersetzt weder `runtime_and_deploy.md` noch das fachliche Konzept-Handover `../functional/handover.md`. + +**Stand:** 2026-09-07, erstellt auf dem Urlaubs-Laptop unter `C:\dev\Kansho`. + +Ziel: Code, Dokumentation und persönliche Testdaten so übergeben, dass zu Hause weiterentwickelt und später auf Docker/PostgreSQL umgestellt werden kann, ohne die Urlaubsdaten zu verlieren. + +--- + +## 1. Leitentscheidung für den Transfer + +**Zwei Wellen, nicht eine.** + +| Welle | Was | Warum | +|---|---|---| +| **1. Kontinuität** | Gitea-Stand klonen, lokale SQLite-Instanz wie bisher, Backup wiederherstellen, Dialog-/Journalqualität prüfen | Der gebaute Slice ist SQLite. Die persönlichen Daten liegen in `backend/data/`. Postgres ist Ziel, nicht Ist. | +| **2. Betriebsrahmen** | Docker Compose, eigenes Postgres, Deploy-Muster analog Mitai, Gitea-Runner | Entschiedenes Ziel in `product_frame_and_stack.md`. Nicht im selben Schritt wie der erste Daten-Restore. | + +Ein SQLite-Restore auf dem Heimrechner **vor** der Postgres-Migration ist die Restore-Übung, die `runtime_and_deploy.md` §7 Punkt 3 verlangt. Erst wenn Welle 1 grün ist, wird der Slice auf Compose/Postgres gehoben. + +Nicht tun: Urlaubs-SQLite in ein noch nicht existierendes Postgres-Schema laden, während uncommitteter Code nur auf dem Laptop liegt. + +--- + +## 2. Ist-Stand der Laptop-Instanz (2026-09-07) + +### 2.1 Laufzeit + +| Element | Ist | +|---|---| +| Host | Windows-Laptop, Pfad `C:\dev\Kansho` | +| Start | ohne Docker: Uvicorn **8018**, Vite **5188** (`strictPort`) | +| Persistenz | SQLite `backend/data/kansho.sqlite` (~11,3 MB) | +| Medien | `backend/data/media//` (70 Dateien, ~8,9 MB Nutzlast; zwei große JPEGs, viele Mini-WebM/PNG) | +| Secrets | `backend/.env` (nicht im Git, nicht im Backup-Archiv) | +| Python | 3.12, venv `backend/.venv` | +| Remote | `https://gitea.stommer.de/Lars/Kansho.git` | + +### 2.2 Git + +| Element | Ist | +|---|---| +| Branch | `main` | +| HEAD | `e42f751` Message `MVP 1.0` | +| Remote | `origin/main` ist **einen Commit hinter** HEAD (`ahead 1`) | +| `develop` | existiert **nicht** (Familienmuster Dev=`develop` / Prod=`main` ist entschieden, aber noch nicht angelegt) | + +Uncommittet (muss vor dem Verlassen des Laptops nach Gitea): + +- Opening-Fix: `backend/journal_opening.py`, `context_builder.py`, `retrieval.py`, `tests/test_journal_opening.py` +- Opening-Doku: `mvp.md` §6.1, `mvp_implementation.md` §17, `mvp_stand_und_abgleich.md` (Tabellen 5.4, §6.4, §7, Dateikarte), `memory_storage_and_offline.md` §6.2 +- Invariante: Vorhaben nur aus dem **user-Dialog des vorigen Kalendertags**; gespeicherte Journal-Entries sind kein Opening-Mandat; Opening-Call ohne Space-Recency. Fehlerbild: Nachsatz mit Morgenuhrzeit + 400-Zeichen-Prefix. Tests 2026-09-03/07 lokal grün. +- Transfer-Doku und Work Orders (siehe unten) + +Bewusst **nicht** in diesem Transfer schließen: Prefix-Recency im laufenden `dialogue_turn`. + +Unversioniert (gehören in denselben oder einen Dokumentations-Commit): + +- `docs/architecture/functional/Idea_seconmd_sclide.md` (Konzeptbrief Slice 2, Dateiname mit Tippfehler) +- `docs/work_orders/` (Debug-Diagnostik, Dialog/Memory-Slice, Laptop-Abschluss, Heim-Setup) +- dieses Handover und die Runtime-Ergänzungen + +Nicht in Git und **nicht** ins Backup: `backend/.env`. + +### 2.3 Persönlicher Datenbestand (Inventar, kein Inhalt) + +Ein Admin-Profil seit 2026-08-19. Zwei Spaces: `Kroatien 2026` (Urlaubsjournal) und `Test für Prosagenerierung`. 17 Journal Days, 17 Current-Entries, 20 Conversations, 379 Messages, Writing Profile vorhanden, Identity-Mappings lokal, Debug-Runs opt-in persistiert. + +Das ist **Klasse-A/B-Material**. Es darf nicht nach Gitea, nicht an Provider, nicht unverschlüsselt in die Cloud. + +### 2.4 Backup dieser Session + +Erzeugt: `local-backups/kansho-20260907-055703.zip` (gitignoriert). + +Enthält SQLite (Backup-API) + 70 Mediendateien + Manifest/Checksummen. Enthält **keine** `.env` und keine Keys. Das Archiv ist **unverschlüsselt** und persönlich. + +Vor dem Abschalten des Laptops: Archiv auf verschlüsselten USB-Stick, NAS-Share oder den Heimrechner kopieren. Zweite Kopie getrennt halten. Nicht committen. + +--- + +## 3. Was auf dem Laptop noch zu tun ist + +Siehe Arbeitsauftrag `../../work_orders/laptop_closeout.md`. + +Kurz: + +1. Opening-Fix und diese Dokumentation committen und nach Gitea pushen. +2. Backup-Archiv und `.env` **getrennt** physisch mitnehmen. +3. Backend beenden, keine weiteren Dialoge mehr als „führende Instanz“ führen, sobald Welle 1 zu Hause bestätigt ist. +4. Slice-2-Konzept, Debug-Export und Memory-Slice **nicht** auf dem Laptop zu Ende bauen. + +--- + +## 4. Offene Cursor-Sessions (Laptop) + +Diese Sessions sind Kontext, keine zweite Source of Truth. Kanonisch bleiben die Repository-Dateien. + +| Session | Thema | Status für den Transfer | +|---|---|---| +| [Opening-Impuls](d5e159cf-4d3c-4069-95f9-123a5500b1da) | Erster Impuls zog abgeschlossene Vortage / 400-Zeichen-Entry-Prefix | **Code und kanonische Doku fertig (2026-09-07).** Invariante in `mvp.md` §6.1, Fit-Gap §6.4, `mvp_implementation.md` §17. Bewusst offen: Prefix-Recency im laufenden Dialogzug. Persönliche Dialoginhalte nicht in Doku. | +| Diese Session | Umgebungswechsel | **Laptop-pflichtig.** Handover und Work Orders angelegt; kanonische Opening-Doku nachgezogen. Commit/Push und physisches Backup bleiben die Abnahme. | +| `docs/work_orders/debug_diagnostics_perfection.md` | Zentraler Admin-Export | **Verschieben.** Kein Laptop-Zwang. | +| `docs/work_orders/dialogue_memory_next_slice_handover.md` | Dialog + Langzeitgedächtnis | **Verschieben.** Konzept/Fit-Gap, keine Implementierung auf dem Laptop. | +| `docs/architecture/functional/Idea_seconmd_sclide.md` | Fachlicher Slice-2-Brief | **Verschieben.** Keine Dateien ändern, bis eine Konzept-Session ihn abarbeitet. | +| Ältere MVP-Sessions (Freeze, Editorial, Policy, Debug-Persistenz, Writing Style) | Journal-MVP 1.0 | **Abgeschlossen** im Commit `e42f751`, sofern nach Gitea gepusht. | + +Ältere Transcripts lokal unter Cursor; sie müssen nicht migriert werden, wenn Gitea den Code-Stand trägt. + +--- + +## 5. Welle 1 – Heim-Entwicklung mit SQLite + +Auftrag: `../../work_orders/home_environment_setup.md` Phase A. + +1. Auf dem Heimrechner (erwarteter Pfad analog `C:\dev\Kansho` oder später Linux-Checkout) `git clone https://gitea.stommer.de/Lars/Kansho.git`. +2. `.\scripts\dev-setup.ps1` (Windows) bzw. venv + `npm install`. +3. `backend/.env` aus der **separaten** Secret-Kopie anlegen, nicht aus dem Backup. +4. Backend **nicht** mit Produktionsdaten starten, bevor das Restore-Ziel leer oder bewusst überschrieben wird. +5. Restore: `.\scripts\backup-local.ps1 restore -Archive \kansho-20260907-055703.zip -Confirm -Replace`. +6. Start: Backend 8018, Frontend 5188. Login mit dem bestehenden Admin-Konto (Passwort-Hash steckt in der SQLite, nicht in `.env`). +7. Smoke: Space `Kroatien 2026` sichtbar, Journal Days vorhanden, ein Entry mit Medien, ein Dialogzug fail-closed ohne Key und mit Key über Gateway, Health `GET /api/health`. +8. `.\scripts\test-mvp.ps1` (isolierte Temp-DB, ändert die Restoredaten nicht). + +Erst wenn das gilt, ist der Laptop nicht mehr führend. + +--- + +## 6. Welle 2 – Docker, Postgres, Server + +Auftrag: `../../work_orders/home_environment_setup.md` Phase B–C. + +Mitai-Referenz auf dem Heimrechner: `C:\dev\mitai` (Compose, `.gitea/workflows/`, Hostpfade `/home/lars/docker/bodytrack` und `bodytrack-dev`). + +**Noch nicht im Kanshō-Repo:** Dockerfiles, Compose, Gitea-Workflows, Postgres-Adapter. `backend/db.py` ist SQLite (`sqlite3`, `PRAGMA`, `datetime('now')`). Das ist eine eigene Implementierungsarbeit, kein Copy-Paste von Mitai-Fachlogik. + +Entschieden (nicht neu verhandeln): + +- Docker Compose: Frontend, Backend, PostgreSQL 16 +- Branches: `develop` → Dev, `main` → Prod +- Secrets nur in Server-`.env` +- Persönlicher LLM-Egress nur über Privacy Gateway +- Kein Auto-Rollback der Datenbank +- Kanshō-Ports **nicht** Mitai `3002`/`8002`/`3099`/`8099` kopieren + +Offen, vor Compose festlegen: + +1. Läuft Kanshō auf demselben Pi wie Mitai, als **eigenes** Compose-Projekt? +2. Eigenes Postgres (bevorzugte Richtung: ja, eigene Instanz/DB `kansho`, kein Shared-Schema mit Mitai)? +3. Dev-Domain / Prod-Domain / Host-Pfade (Hypothese: `dev.kansho.jinkendo.de` / `kansho.jinkendo.de`)? +4. Dev-Ports auf dem Pi, lokal bleiben 5188/8018 für den Windows-Checkout ohne Docker. +5. Ob Welle 2 zuerst Compose **mit SQLite-Volume** als Zwischenstand nutzt oder direkt Postgres + Migrationsadapter. + +Empfohlene Reihenfolge in Welle 2: + +1. Offene Host-Fragen beantworten und in `runtime_and_deploy.md` §1/§6 eintragen. +2. `develop` anlegen, sobald Auto-Deploy gewünscht ist; bis dahin darf `main` der einzige Branch bleiben. +3. Compose-Gerüst analog Mitai, **eigene** Container-/Volumen-/Projektnamen (`kansho-*`, keine `bodytrack/`-Pfade). +4. Backend-Start: Postgres ready → nummerierte SQL-Migrationen → App. Fail-fast. +5. Datenübernahme SQLite → Postgres als **eigenes** Migrationsskript mit Probe-Restore, nicht still im Alltagspfad. +6. Gitea-Workflows erst, wenn Runner-Pfade existieren (`runtime_and_deploy.md` §4). +7. Watchtower später prüfen, nicht in diesem Transfer. + +--- + +## 7. Datenschutz beim Transfer + +- Backup und `.env` nie in Git, nie in Chat-Uploads, nie an OpenRouter. +- Identity-Mappings bleiben lokal (Klasse A). +- Das Zip ist Klartext-Journal. Transport verschlüsseln (BitLocker-Stick, verschlüsseltes NAS, `age`/`gpg` nach Wahl). +- Nach erfolgreichem Heim-Restore Laptop-Kopie als Archive behalten, nicht parallel weiterschreiben. +- Debug-Traces in der DB können Prompt-Ausschnitte enthalten; sie reisen im Backup mit. Auf dem Server den Schalter `debug.persist_traces` prüfen. + +--- + +## 8. Bewusst nicht Teil dieses Transfers + +- Slice 2 / Memory-Continuity implementieren +- Zentralen Debug-Export umbauen +- Voice, semantisches Retrieval, Self Model +- Mitai-Verzeichnisnamen, Mitai-Ports, Shared-Postgres-Schema +- Fachliche Produktentscheidungen aus dem Konzept-Handover + +--- + +## 9. Nächster Arbeitsschritt + +1. Auf dem Laptop: `laptop_closeout.md` abschließen (Commit/Push, Backup kopieren). +2. Zu Hause: neue Session mit diesem Dokument plus `runtime_and_deploy.md` und `home_environment_setup.md`. +3. Welle 1 bis Restore-Abnahme. +4. Erst dann Welle 2. + +--- + +## 10. Querverweise + +- Runtime: `runtime_and_deploy.md` +- Stack: `product_frame_and_stack.md` +- SQLite-Ist: `mvp_implementation.md` §1 und §4 +- Fachliches Session-Handover: `../functional/handover.md` +- Laptop-Abschluss: `../../work_orders/laptop_closeout.md` +- Heim-Setup: `../../work_orders/home_environment_setup.md` +- Mitai: `C:\dev\mitai\docker-compose.yml`, `docker-compose.dev.yml`, `.gitea/workflows/` diff --git a/docs/architecture/technical/runtime_and_deploy.md b/docs/architecture/technical/runtime_and_deploy.md index cc06932..309b962 100644 --- a/docs/architecture/technical/runtime_and_deploy.md +++ b/docs/architecture/technical/runtime_and_deploy.md @@ -2,7 +2,7 @@ title: "Kanshō – Runtime, Migrationen und Deploy" version: "0.1" status: "Arbeitsstand" -date: "2026-08-19" +date: "2026-09-07" product_family: "Jinkendo" document_role: "Technical Chapter / Runtime / Deploy / Migrations" parent_document: "technische_zielarchitektur.md" @@ -89,12 +89,14 @@ Kanshō-Repo liegt bereits auf Gitea (`Lars/Kansho`). HTTPS-Push ist eingerichte | Ports/Domains/Hostpfade | Prod offen; lokal Frontend 5188 / Backend 8018 | lokal festgelegt, Prod offen | | Gitea Workflows | Mitai-Muster | bevorzugte Richtung | | Auto-Rollback | nein | verworfen | +| Urlaubs-Laptop ohne Docker/SQLite | Ist bis Transfer Welle 1 | dokumentiert 2026-09-07 | +| Transfer vor Postgres | SQLite-Restore auf dem Heimrechner zuerst | entschieden als Reihenfolge | ## 7. Offene Fragen 1. Läuft Kanshō auf demselben Raspberry-Pi-Host wie Mitai, mit eigenen Compose-Projekten? 2. Gemeinsames oder separates Postgres? -3. Backup-Rhythmus und Restore-Übung vor erstem persönlichen Dialogdatenbestand. +3. Backup-Rhythmus und Restore-Übung vor erstem persönlichen Dialogdatenbestand. Die Urlaubs-SQLite-Restore auf dem Heimrechner (Welle 1) ist diese Übung für den bestehenden Datenbestand; Produktions-Backup für Postgres bleibt offen. ### 7.1 Lokales Backup für die Urlaubs-Testphase (2026-08-25) @@ -105,8 +107,20 @@ Kein Ersatz für Produktions-Backup, Docker oder Verschlüsselung. - Wiederherstellen: `.\scripts\backup-local.ps1 restore -Archive -Confirm`; bestehender Stand nur mit `--replace` nach automatischem Sicherheitsbackup - SQLite-Backup-API, Journalmedien, Manifest mit Checksummen. Keine `.env` oder Keys. Das Archiv kann persönliche unverschlüsselte Daten enthalten. +### 7.2 Transfer Laptop → Heim-Entwicklung und Server (2026-09-07) + +Die Urlaubsinstanz lief ohne Docker auf SQLite (`backend/data/kansho.sqlite`, Ports 5188/8018). Persönliche Dialog- und Journaldaten liegen nicht in Gitea. + +**Reihenfolge entschieden:** zuerst Kontinuität (Clone + SQLite-Restore + Smoke), danach Betriebsrahmen (Compose, Postgres 16, Gitea-Runner). Postgres bleibt Ziel; `backend/db.py` ist weiterhin SQLite. Ein direkter Sprung „Laptop-SQLite nach Prod-Postgres“ ohne Zwischen-Restore ist verworfen. + +Kanonisches Session-Handover: `environment_handover.md`. Aufträge: `../../work_orders/laptop_closeout.md`, `../../work_orders/home_environment_setup.md`. + +Laptop-Backup dieser Session: `local-backups/kansho-20260907-055703.zip` (nur lokal, gitignoriert). `.env` reist getrennt. + +Noch nicht im Repository: Dockerfiles, Compose, `.gitea/workflows/`, Postgres-Adapter. Mitai unter `C:\dev\mitai` bleibt Muster, nicht Quelle für Ports oder `bodytrack/`-Pfade. + ## 8. Querverweise -- Technisch: `product_frame_and_stack.md`, `security.md` +- Technisch: `product_frame_and_stack.md`, `security.md`, `environment_handover.md`, `mvp_implementation.md` §1 - Fachlich: Offline und Sync bleiben `memory_storage_and_offline.md`; Deploy löst Offline nicht. - Mitai: `MIGRATIONS.md`, `.gitea/workflows/` diff --git a/docs/work_orders/debug_diagnostics_perfection.md b/docs/work_orders/debug_diagnostics_perfection.md new file mode 100644 index 0000000..e95cefe --- /dev/null +++ b/docs/work_orders/debug_diagnostics_perfection.md @@ -0,0 +1,204 @@ +--- +title: "Kanshō – Arbeitsauftrag Debug-Diagnostik und Export" +status: "Arbeitsauftrag" +date: "2026-08-31" +document_role: "Cursor Implementation Brief" +canonical_architecture: "docs/architecture/technical/admin_diagnostics.md" +--- + +# Arbeitsauftrag: Debug-Diagnostik und Export konsolidieren + +Arbeite im aktiven Repository `C:\dev\Kansho`. + +Dieses Dokument ist ein Umsetzungsauftrag. Es ersetzt keine kanonische Fach- oder Technikdokumentation. Neue Entscheidungen und der tatsächliche Implementierungsstand sind additiv in den jeweils zuständigen Dateien unter `docs/architecture/` zu dokumentieren. + +## Ausgangslage + +Die bestehende Diagnostik enthält bereits viele wertvolle Informationen. Sie ist aber über verschiedene Seiten und Exportwege verteilt. Je nachdem, ob ein Export aus einem Dialog, einem Tag oder einer Generierung gestartet wird, entsteht ein anderer und teilweise sehr großer JSON-Export. + +Dadurch ist oft unklar: + +- welche Läufe im Export enthalten sind, +- welche Dialoge und Generierungen zu einem Tag gehören, +- warum ein Lauf fehlgeschlagen ist, +- welche Fassung tatsächlich angezeigt oder gespeichert wurde, +- und an welcher Stelle der passende Export ausgelöst werden muss. + +Teilweise werden dieselben Daten mehrfach eingebettet. Das macht Exporte unnötig groß und ihre Analyse schwierig. + +Die bereits ergänzte Speicherung fehlgeschlagener Detect- und Journal-Läufe muss erhalten bleiben. + +## Ziel + +Baue eine zentrale, verständliche Admin-Diagnostik mit einem einheitlichen Exportverfahren. + +Ein Administrator soll gezielt auswählen können: + +1. welchen Reflection Space, +2. welchen Tag oder Zeitraum, +3. welche Dialoge, +4. welche Generierungsläufe – auch mehrere, +5. welche Laufarten und Status, +6. und welche Detailinformationen + +der Export enthalten soll. + +Die Diagnose soll sowohl für eine schnelle Sichtprüfung in der Oberfläche als auch für eine genaue externe Analyse des JSON geeignet sein. + +## Vor der Umsetzung + +Lies zunächst: + +- `docs/architecture/functional/documentation_index.md`, +- `docs/architecture/technical/documentation_index.md`, +- `docs/architecture/technical/admin_diagnostics.md`, +- `docs/architecture/technical/privacy_gateway.md`, +- die bestehenden Debug-Routen, Datenmodelle und Frontend-Komponenten. + +Prüfe die tatsächliche Implementierung und beschreibe kurz: + +- die aktuellen Exportwege, +- vorhandene Doppelungen, +- fehlende Beziehungen, +- und welche Informationen bei Fehlern noch verloren gehen. + +Leite die konkrete technische Lösung daraus ab. Übernimm nicht ungeprüft Annahmen aus diesem Auftrag. + +## Anforderungen + +### Zentrale Auswahl + +Unter `/admin/debug` soll es einen zentralen Exportdialog geben. + +Filter: + +- Reflection Space, +- einzelner Tag oder Zeitraum, +- Dialoge als Mehrfachauswahl, +- Laufart beziehungsweise Purpose, +- Status, +- einzelne Run-IDs, +- optional Generierungszeitraum. + +Vor dem Export soll sichtbar sein, wie viele Dialoge und Läufe durch die Auswahl erfasst werden. + +### Auswählbare Inhalte + +Der Administrator soll bestimmen können, welche Bereiche enthalten sind: + +- kompakte Zusammenfassung, +- chronologische Ereignis- und Aufrufübersicht, +- Modell, Provider, Token, Kosten und Laufzeiten, +- Generierungsrichtlinien und wirksame Auswahl, +- wirksame Stilanwendung einschließlich tatsächlich eingebundener Profilbestandteile, +- verwendete Quellen, +- Privacy- und Detection-Diagnostik, +- Validierung und Fehlerursachen, +- Provideranfrage und Providerantwort, +- sichtbare und gespeicherte Ausgabe, +- vollständige Prompts und maskierter Provider-Egress. + +Sensible Inhalte wie vollständige Prompts, Quellen und Rohantworten müssen ausdrücklich zugeschaltet werden. Zeige dabei einen klaren Warnhinweis. + +Lokale Mappingtabellen, Secrets, Zugangsdaten und andere nicht benötigte Identitätsdaten dürfen niemals exportiert werden. + +### Einheitliches Datenmodell + +Erzeuge ein versioniertes, kanonisches Exportformat, beispielsweise Version 3. + +Eine Information soll nur einmal enthalten sein. Beziehungen werden über IDs dargestellt, nicht durch wiederholtes Einbetten desselben Laufes unter Tag, Dialog und Generierung. + +Eine mögliche oberste Struktur ist: + +- `manifest`, +- `selection`, +- `entities`, +- `runs`. + +Die konkrete Struktur soll aus dem bestehenden Datenmodell abgeleitet werden. + +Bestehende Exportwege dürfen entweder kompatibel weiterlaufen oder müssen kontrolliert auf das neue Format umgestellt werden. Dokumentiere die Entscheidung. + +### Vollständige Laufhistorie + +Ein diagnostischer Lauf muss möglichst ab Beginn der Anfrage eine stabile Run-ID besitzen. Auch frühe Fehler sollen nachvollziehbar sein. + +Unterscheide mindestens: + +- laufend, +- erfolgreich, +- vor dem Provider fehlgeschlagen, +- Providerfehler, +- Detection fehlgeschlagen, +- Validierung fehlgeschlagen, +- Timeout, +- Clientabbruch, +- unvollständig beziehungsweise verwaist. + +Vorhandene Statusbezeichnungen können weiterverwendet werden, wenn sie diese Fälle eindeutig abdecken. + +Kosten oder Tokenwerte, die der Provider nicht geliefert hat, müssen als „nicht verfügbar“ beziehungsweise `null` erscheinen und dürfen nicht geschätzt als tatsächliche Werte ausgegeben werden. + +### Einheitliche Einstiegspunkte + +Export-Schaltflächen auf Dialog-, Tages- oder Generierungsseiten sollen keine eigenen Exportlogiken mehr besitzen. Sie öffnen denselben zentralen Exportdialog mit sinnvoll vorbelegten Filtern. + +### Übersichtlichkeit + +Die Adminoberfläche soll zuerst eine kompakte Übersicht zeigen. Technische Details werden erst bei Bedarf aufgeklappt. + +Wichtig sind insbesondere: + +- Status und Abbruchgrund, +- Dauer, +- Anzahl der Provideraufrufe, +- verwendetes Modell, +- Kosten und Token, +- Generate tatsächlich aufgerufen: ja/nein, +- Fallback verwendet: ja/nein, +- sichtbare und gespeicherte Fassung identisch: ja/nein. + +## Grenzen + +- Keine Änderung an Journal-Prompts oder Generierungsrichtlinien. +- Keine Änderung der semantischen Detection. +- Keine Lockerung der Privacy-Regeln. +- Keine journal-spezifische Sonderarchitektur für allgemeine Runs. +- Keine zukünftige Memory-Architektur vorwegnehmen. +- Keine echten Provideraufrufe. +- Kein Commit und kein Tag. +- Bestehende uncommittete Änderungen erhalten. + +## Tests und Abnahme + +Ergänze Regressionstests für mindestens: + +1. Export eines einzelnen Dialogs. +2. Export eines Tages mit mehreren Dialogen. +3. Auswahl mehrerer Generierungsläufe. +4. Kombination erfolgreicher und fehlgeschlagener Läufe. +5. Persistenz eines Fehlers vor dem Generate-Aufruf. +6. Exakte Anwendung aller Filter. +7. Keine doppelte Einbettung eines Runs. +8. Sensible Inhalte nur nach ausdrücklicher Auswahl. +9. Niemals Secrets oder Identitäts-Mappingtabellen im Export. +10. Nicht-Admins erhalten keinen Zugriff. +11. Seitenspezifische Schaltflächen öffnen den zentralen Export mit korrekter Vorbelegung. +12. Bestehende MVP-Tests und Frontend-Build bleiben erfolgreich. + +Dokumentiere die Änderung additiv in der bestehenden technischen Diagnostik-Dokumentation. + +## Abschlussbericht + +Berichte anschließend: + +1. bestätigte Ursachen, +2. fachliches Bedienkonzept, +3. neues Exportmodell und Versionsstrategie, +4. geänderte Dateien, +5. Behandlung erfolgreicher und fehlgeschlagener Läufe, +6. Datenschutzgrenzen, +7. ausgeführte Tests, +8. bewusst verbleibende MVP-Grenzen. + +Nenne ausdrücklich, was nur durch Tests bewiesen wurde und was noch interaktiv im Browser geprüft werden sollte. diff --git a/docs/work_orders/dialogue_memory_next_slice_handover.md b/docs/work_orders/dialogue_memory_next_slice_handover.md new file mode 100644 index 0000000..8dc16c7 --- /dev/null +++ b/docs/work_orders/dialogue_memory_next_slice_handover.md @@ -0,0 +1,229 @@ +--- +title: "Kanshō – Handover Dialogfähigkeit und Langzeitgedächtnis" +status: "Arbeitsauftrag für neue Konzept-Session" +date: "2026-08-31" +document_role: "ChatGPT Session Brief / Next-Slice Handover" +canonical_handover: "docs/architecture/functional/handover.md" +--- + +# Handover: Kanshō als persönlicher Reflexionspartner mit Langzeitgedächtnis + +Wir beginnen einen neuen Entwicklungsslice für Kanshō. + +Dieses Dokument ist ein thematischer Arbeitsauftrag für die nächste Session. Es ersetzt weder `docs/architecture/functional/handover.md` noch die kanonischen Fachkapitel. Bei Abweichungen haben die aktuellen kanonischen Repository-Dateien Vorrang. + +## Produktverständnis + +Kanshō ist kein Tagebuchtool. Die Journalgenerierung ist lediglich eine mögliche Ausgabe eines Reflexionsprozesses. + +Kanshō soll ein persönlicher, langfristiger Reflexionspartner werden, der Menschen dabei unterstützt, Erlebtes wahrzunehmen, zu reflektieren, zu verstehen und einzuordnen. + +Die zentrale Produktfrage lautet: + +> Was bedeutet das Erlebte für die Person? + +Kanshō ist ausdrücklich kein generischer Chatbot, Therapeut, Aufgabenmanager, Fitness-Tracker oder still arbeitendes Persönlichkeitsprofil. + +Die Dialogfähigkeit ist die zentrale Produktschnittstelle. Langzeitgedächtnis soll der Kontinuität und Tiefe des Dialogs dienen – nicht möglichst viele alte Informationen in jeden Prompt laden. + +## Bestehender Stand + +Der bisherige MVP konzentrierte sich stark auf Dialogerfassung, Journalgenerierung, Writing Profile, Privacy Gateway, Provenienz und konfigurierbare Generierungsrichtlinien. + +Dieser Journal-MVP wird praktisch getestet und soll durch den neuen Slice nicht destabilisiert werden. + +Aus den bisherigen Arbeiten sind besonders wichtig: + +- Identität bleibt lokal. +- Externe Modelle erhalten persönlichen Kontext nur über das Privacy Gateway. +- Quellen bleiben autoritativ; Zusammenfassungen und Interpretationen sind abgeleitet. +- KI-Hypothesen sind keine bestätigten Erinnerungen. +- Aktueller Zustand ist nicht automatisch stabile Identität. +- Nutzerkorrekturen müssen gespeicherte Annahmen wirksam korrigieren können. +- Kontext soll relevant und ausreichend sein, nicht maximal. +- Der Normalfall soll möglichst einen wesentlichen generativen Modellaufruf pro Dialogzug behalten. +- Reflection Spaces und Intents dürfen nicht mit der Journalfunktion gleichgesetzt werden. + +## Verbindliche Dokumentationsbasis + +Arbeite im Repository `C:\dev\Kansho`. + +Lies zuerst vollständig: + +- `docs/architecture/functional/handover.md`, +- `docs/architecture/functional/documentation_index.md`, +- bei technischer Prüfung zusätzlich `docs/architecture/technical/documentation_index.md`. + +Lade danach gezielt die passenden Context Bundles. Relevant sind insbesondere: + +- `produktvision_und_produktidentitaet.md`, +- `fachliche_zielarchitektur.md`, +- `dialogue_model.md`, +- `usage_situations.md`, +- `reflection_spaces.md`, +- `resurfacing_and_saturation.md`, +- `memory_and_context.md`, +- `context_fidelity_and_regrounding.md`, +- `self_model_and_lived_experience.md`, +- `guardrails.md`. + +Lade nicht unkritisch den gesamten Dokumentationsbaum. Die fachliche Dokumentation ist führend. Unterscheide konsequent zwischen „Entschieden“, „Bevorzugte Richtung“, „Hypothese“, „Offen“ und „Verworfen“. + +Dokumente dürfen nicht stillschweigend gekürzt oder durch neue Paralleldokumente ersetzt werden. + +## Fachliches Ziel des nächsten Slices + +Der nächste Slice soll erstmals belastbar zeigen, dass Kanshō über einzelne Sitzungen hinaus als persönlicher Reflexionspartner funktioniert. + +Kanshō soll: + +- den gegenwärtigen Reflexionsraum erkennen und halten, +- unterschiedliche Reflection Intents unterscheiden, +- frühere relevante Gedanken gezielt wieder aufnehmen, +- mehrere offene Reflexionsfäden erkennen, parken und fortsetzen, +- historische Aussagen von der heutigen Sicht unterscheiden, +- Veränderungen über die Zeit sichtbar machen, +- Unsicherheit und widersprüchliche Aussagen aushalten, +- Erinnerungen mit Herkunft und zeitlichem Bezug verwenden, +- Korrekturen des Nutzers beachten, +- und Impulse geben, die über generische Rückfragen hinausgehen. + +**Additiv 2026-09-07 (Opening, Code-Stand):** Der erste Impuls eines Journal-Dialogs darf abgeschlossene Vortage nicht als offenen Faden führen. Ursache war Recency: 400-Zeichen-Prefix eines Journal-Entries plus Plan-Regex, oft nach einem nachgetragenen Morgenanker. Invariante: Vorhaben nur aus dem user-Dialog von gestern; Entries sind kein Mandat; Opening ohne Space-Recency. Der laufende Dialogzug lädt Prefix-Recency weiter – das bleibt eine Lücke für Relevanz/Memory, nicht für den Opening-Adapter. Details: `mvp.md` §6.1, `mvp_implementation.md` §17, `mvp_stand_und_abgleich.md` §6 Punkt 4. + +Dabei darf das System keine künstliche Gewissheit, Diagnose oder festgeschriebene Persönlichkeit erzeugen. + +## Reflection Spaces und Intents + +Reflection Spaces beantworten, in welchem Lebens- oder Bedeutungskontext eine Reflexion stattfindet. Intents beschreiben, was der Nutzer in diesem Moment erreichen möchte. + +Der Dialog muss unterschiedliche Formen unterstützen, beispielsweise: + +- ein Erlebnis zunächst nur erzählen, +- einen spontanen Gedanken festhalten, +- ein früheres Thema fortsetzen, +- ein Erlebnis tiefer verstehen, +- wiederkehrende Muster betrachten, +- eine Entscheidung oder Orientierung reflektieren, +- mit einem Konflikt oder einer emotionalen Reaktion arbeiten, +- eine tägliche Reflexion führen, +- Meditation oder Aufmerksamkeit reflektieren. + +Es darf keinen einzigen starren Dialogmodus und keinen universellen Prompt geben, der alle Situationen gleich behandelt. + +Ebenso darf das System den Nutzer nicht ständig zwingen, einen Modus, Space oder Intent manuell auszuwählen. Die Adaptive Entry bleibt maßgeblich: + +1. kontextuell fortsetzen, wenn der Bezug klar ist, +2. freie Reflexion ermöglichen, +3. nur bei echter Mehrdeutigkeit explizit navigieren. + +Gemischte oder sich während eines Dialogs verändernde Intents müssen möglich bleiben. + +## Arbeitsauftrag für diesen Chat + +### Phase 1: Bestehenden Stand verstehen + +Prüfe fachliche Dokumentation und aktuelle Implementierung. Untersuche insbesondere: + +- aktuellen Dialogprompt und Dialog-Orchestrierung, +- Speicherung von Nachrichten, Dialogen und Reflection Spaces, +- Context Builder und Retrieval, +- vorhandene Thread-, Episoden- und Memory-Strukturen, +- Status, Provenienz und Korrekturmöglichkeiten gespeicherter Inhalte, +- Privacy-Pfad für angereicherten Kontext, +- aktuelle Tests und dokumentierte Fit-Gaps. + +Trenne danach klar: + +1. fachlich bereits entschiedene Zielarchitektur, +2. technisch bereits belastbar umgesetzt, +3. nur als MVP-Annäherung vorhanden, +4. offen oder widersprüchlich, +5. für den nächsten Slice wirklich erforderlich. + +### Phase 2: Nächsten vertikalen Slice entwerfen + +Schlage keinen vollständigen Ausbau des gesamten Langzeitgedächtnisses vor. Definiere den kleinsten vertikalen Slice, der einen echten qualitativen Fortschritt im Dialog nachweist. + +Der Slice soll mindestens umfassen: + +- Intent-sensitive Dialogführung, +- Fortsetzung eines früheren Reflexionsfadens, +- gezieltes lokales Retrieval relevanter Erinnerungen, +- Unterscheidung historischer und aktueller Aussagen, +- sichtbare Herkunft beziehungsweise Re-Grounding, +- Nutzerkorrektur einer früheren Annahme, +- und eine normale Unterhaltung ohne relevante Erinnerung als Kontrollfall. + +Der allgemeine Kern muss intent-neutral sein. Intent-spezifische Regeln gehören in Adapter oder Policies und nicht als Sonderfälle in die allgemeine Memory-Infrastruktur. + +### Phase 3: Eval- und Abnahmekonzept + +Entwickle vor der Implementierung reproduzierbare Dialogszenarien für mindestens: + +1. autobiografisches Erzählen ohne Reflexionsdruck, +2. spontanen Gedanken, +3. Fortsetzung eines Themas nach mehreren Tagen, +4. tiefere biografische Reflexion, +5. Entscheidung oder Orientierung, +6. Konflikt beziehungsweise emotionale Reaktion, +7. Kontrollfall ohne relevante Erinnerung. + +Bewerte dabei nicht nur Faktenabruf, sondern: + +- Natürlichkeit des Dialogs, +- Qualität und Tiefe der Impulse, +- passende Intensität der Reflexion, +- relevante statt maximale Erinnerung, +- keine unpassenden historischen Einwürfe, +- korrekte zeitliche Einordnung, +- Umgang mit Unsicherheit und Widerspruch, +- Reaktion auf Nutzerkorrekturen, +- Vermeidung repetitiver oder generischer Fragen, +- Datenschutz, +- Latenz und Kosten. + +### Phase 4: Entscheidungsvorlage + +Erstelle zunächst: + +1. eine kompakte Fit-Gap-Matrix, +2. den vorgeschlagenen nächsten Slice, +3. dessen fachliche und technische Grenzen, +4. konkrete Abnahmekriterien, +5. notwendige offene Produktentscheidungen, +6. und eine empfohlene Umsetzungsreihenfolge. + +Eine bereits bekannte offene Frage ist die Positionierung bei Entscheidungsdialogen: Darf Kanshō nach ausreichender Reflexion eine begründete Einschätzung oder Empfehlung geben, oder soll es bewusst neutral bleiben? Behandle dies als intent-spezifische Produktentscheidung, nicht als Grundsatz für alle Dialoge. + +Beginne noch nicht mit einer großen Implementierung. Stelle zuerst den tatsächlichen Stand und den vorgeschlagenen Slice zur gemeinsamen Entscheidung vor. Frage nur bei Punkten nach, die sich weder aus Dokumentation noch Code zuverlässig beantworten lassen. + +## Architekturgrenzen + +Vermeide insbesondere: + +- das vollständige Langzeitgedächtnis in jeden Prompt zu laden, +- semantische Ähnlichkeit mit fachlicher Relevanz gleichzusetzen, +- jeden Dialogzug durch mehrere teure Analyseaufrufe zu schicken, +- Journallogik zum allgemeinen Dialog- oder Memory-Kern zu machen, +- unbestätigte Modellinterpretationen als Nutzerwissen zu speichern, +- aus aktuellen Aussagen stabile Persönlichkeitsmerkmale abzuleiten, +- Reflection Spaces unnötig zu vervielfachen, +- für einzelne Tests hardcodierte Regeln einzubauen, +- und die bestehende Privacy-Architektur für bessere Modellqualität zu umgehen. + +Der Kontextaufbau soll grundsätzlich lokal erfolgen: + +> Reflection Space zuerst, Langzeitgedächtnis gezielt bei Bedarf, minimal ausreichender Kontext, danach Privacy Gateway. + +## Erwartete erste Antwort + +Antworte nach der Einarbeitung zunächst mit: + +1. den tatsächlich gelesenen Dokumenten, +2. dem bereits entschiedenen Produkt- und Architekturstand, +3. dem ermittelten Ist-Stand der Dialog- und Memory-Implementierung, +4. den wichtigsten Lücken, +5. einem Vorschlag für den ersten vertikalen Slice, +6. den Punkten, die wir gemeinsam entscheiden müssen. + +Kanshō soll in diesem neuen Slice nicht zu einem besseren Tagebuchgenerator werden, sondern erstmals erkennbar zu einem kontinuierlichen, persönlichen und verlässlichen Reflexionspartner. diff --git a/docs/work_orders/home_environment_setup.md b/docs/work_orders/home_environment_setup.md new file mode 100644 index 0000000..729575d --- /dev/null +++ b/docs/work_orders/home_environment_setup.md @@ -0,0 +1,158 @@ +--- +title: "Kanshō – Arbeitsauftrag Heim-Entwicklung, Server, Docker, Postgres" +status: "Arbeitsauftrag für die Session nach dem Laptop-Transfer" +date: "2026-09-07" +document_role: "Cursor Implementation Brief / Home Environment Setup" +canonical_handover: "docs/architecture/technical/environment_handover.md" +--- + +# Arbeitsauftrag: Heim-Entwicklungsumgebung, Server und Datenübernahme + +Arbeite **nicht** auf der Urlaubs-SQLite als führende Instanz. Voraussetzung: `laptop_closeout.md` ist erfüllt (Gitea aktuell, Backup und `.env` liegen vor). + +Lies zuerst: + +- `docs/architecture/technical/environment_handover.md` +- `docs/architecture/technical/documentation_index.md` +- `docs/architecture/technical/runtime_and_deploy.md` +- `docs/architecture/technical/product_frame_and_stack.md` +- `docs/architecture/technical/mvp_implementation.md` §1 und §4 +- fachlich nur `docs/architecture/functional/guardrails.md`, falls Egress oder Mapping berührt wird + +Mitai-Muster liegen unter `C:\dev\mitai` (Compose, Workflows). Kanshō-Ports, Host-Pfade und Datenbanken nicht aus Mitai kopieren. + +Keine Slice-2- oder Memory-Implementierung in diesem Auftrag. Kein Commit, bis der Nutzer ihn verlangt. + +--- + +## Offene Host-Fragen, vor Phase B klären + +In `runtime_and_deploy.md` §1/§6/§7 eintragen, nicht nur im Chat lassen: + +1. Derselbe Raspberry-Pi wie Mitai, eigenes Compose-Projekt? +2. Eigenes Postgres (empfohlen) oder gemeinsame Instanz mit getrennter Database? +3. Host-Pfade analog `/home/lars/docker/…` – konkrete Kanshō-Verzeichnisse? +4. Dev-/Prod-Domains und **Kanshō-Ports** (lokal bleiben 5188/8018)? +5. Welle 2 zuerst SQLite im Volume oder direkt Postgres? + +Solange 1–4 offen sind: nur Phase A ausführen. + +--- + +## Phase A – Kontinuität (SQLite, ohne Docker) + +Ziel: Dieselbe Anwendung wie auf dem Laptop, mit den Urlaubsdaten, auf dem Heimrechner. + +1. `git clone https://gitea.stommer.de/Lars/Kansho.git` (Windows-Pfadempfehlung `C:\dev\Kansho`, wenn frei). +2. `git log -1` muss den Opening-Fix und die Transfer-Doku enthalten. Fehlt das, zuerst Laptop-Push nachholen. +3. `.\scripts\dev-setup.ps1` +4. `backend/.env` aus der Secret-Kopie. Nicht aus dem Backup-Zip. +5. Backend aus, dann Restore: + +```powershell +.\scripts\backup-local.ps1 restore -Archive \kansho-20260907-055703.zip -Confirm -Replace +``` + +6. Start: Backend `--port 8018`, Frontend `npm run dev` (5188). +7. Abnahme Phase A: + + - [ ] `GET /api/health` + - [ ] Login mit bestehendem Admin + - [ ] Space `Kroatien 2026` und Test-Space sichtbar + - [ ] Journal Days und mindestens ein Entry mit Medien + - [ ] Identity-Mappings unter Admin vorhanden, Keys nicht in der DB + - [ ] Ein Dialogzug: ohne gültige Policy fail-closed; mit konfiguriertem Generate über Privacy Gateway + - [ ] `.\scripts\test-mvp.ps1` grün (Temp-Isolation) + +Danach ist der Laptop nicht mehr Source of Truth. Weitere Dialoge nur noch hier. + +--- + +## Phase B – Docker-Gerüst (noch ohne fachliche Postgres-Migration, falls so entschieden) + +Erst nach beantworteten Host-Fragen. + +Muster Mitai, eigene Namen: + +- `docker-compose.yml` (Prod-ähnlich: Frontend-Nginx, Backend, Postgres 16) +- `docker-compose.dev.yml` / `docker-compose.dev-env.yml` nach Familienbrauch +- `backend/Dockerfile`, `frontend/Dockerfile` +- Root-`.env.example` für Compose-Secrets (DB-Passwort, Provider-Keys). Bestehendes `backend/.env.example` nicht stillschweigend ersetzen. +- Volumes für App-Daten und Medien. Keine Mitai-Volume-Namen (`bodytrack_*`). +- Healthcheck Backend; Startup: DB ready → Migrationen → Uvicorn. +- Lokale Ports **nicht** 3002/8002/5173/8000. + +Zwischenstand zulässig: Compose startet Backend weiterhin auf SQLite im Volume, Postgres-Container schon mitlaufen, App noch nicht umgestellt. Das muss in `runtime_and_deploy.md` explizit stehen. + +Abnahme Phase B: + +- [ ] `docker compose up` startet die drei Dienste +- [ ] Frontend erreicht Backend über `/api` +- [ ] Secrets nur in Host-`.env` +- [ ] Re-Restore oder Volume-Mount der Phase-A-Daten dokumentiert +- [ ] `scripts/test-mvp.ps1` bleibt der lokale Nicht-Docker-Weg + +--- + +## Phase C – PostgreSQL als App-Persistenz + +Eigene Implementierung, kein stilles Umbenennen von `db.py`. + +1. Adapter oder Dual-Backend: SQLite bleibt für Laptop/Tests zulässig, bis Postgres abgenommen ist. +2. `schema.sql` und die bestehenden `schema_migrations` nach Postgres-Dialekt führen (kein `PRAGMA`, `datetime('now')` prüfen, Typen). +3. Startpfad wie entschieden: Postgres ready → nummerierte SQL-Dateien → App. Fail-fast. +4. Einmaliges Migrationsskript SQLite → Postgres (Profile, Spaces, Journal, Medien-Metadaten, Mappings, Prompts). Medien-Dateien separat ins Volume. +5. Probe auf Kopie, nicht auf dem einzigen Backup. +6. Danach Backup-Strategie für Postgres (nicht nur `backup-local.ps1`). Restore-Übung wiederholen. + +Abnahme Phase C: + +- [ ] Leere Instanz startet und migriert +- [ ] Übernommene Urlaubsdaten: Entry-Anzahl, Message-Anzahl, ein Medien-GET +- [ ] Privacy Gateway unverändert fail-closed +- [ ] Tests gegen Postgres oder klar getrennte SQLite-Testmatrix +- [ ] Additive Doku in `runtime_and_deploy.md`, `mvp_implementation.md` §1/§4, `data_architecture.md` nur soweit Persistenzgrenzen betroffen sind + +--- + +## Phase D – Gitea CI/CD + +Erst wenn Runner und Host-Pfade existieren (`runtime_and_deploy.md` §4). + +Vorlage: `C:\dev\mitai\.gitea\workflows\` (`deploy-dev.yml`, `deploy-prod.yml`, `test.yml`). + +- Branch `develop` anlegen, wenn Dev-Deploy gewünscht +- Kanshō-Pfade, nicht `/home/lars/docker/bodytrack` +- Healthcheck auf Kanshō-Ports +- Testjob: Backend-Tests + Frontend-Build; keine Live-Provider-Keys im Runner + +--- + +## Phase E – Transfer testen (Ende-zu-Ende) + +Nach Phase A zwingend, nach B/C erneut: + +1. Neues Backup auf der Heiminstanz erzeugen und an einem Temp-Pfad wiederherstellen. +2. Einen Journal Day öffnen, kurzen Dialog, Generate nur wenn Keys gesetzt. +3. Opening-Invariante: abgeschlossener Vortag erzeugt keinen falschen Plan-Impuls. +4. Admin → Schnittstellen: Keys aus `.env`, nicht aus der DB. +5. Kein Klartext-Detect in `KANSHO_ENV=production`. +6. Regression: `.\scripts\test-mvp.ps1` + +--- + +## Grenzen + +- Keine Mitai-Körperlogik, keine gemeinsamen Tabellen mit Mitai. +- Keine Lockerung der Guardrails „weil Docker intern ist“. +- Keine Produktiv-Domain erfinden. +- Watchtower nicht still einschalten. +- `Idea_seconmd_sclide.md` und Memory-Handover nicht in diesem Auftrag implementieren. + +## Abschlussbericht + +1. Welche Phasen tatsächlich gelaufen sind +2. Gewählte Host-Pfade, Ports, Compose-Projektnamen +3. Ob Daten SQLite oder Postgres führen +4. Restore-Nachweis (Anzahlen, ein Medienbeispiel ohne Inhalt zu zitieren) +5. Offene Punkte für die nächste Session diff --git a/docs/work_orders/laptop_closeout.md b/docs/work_orders/laptop_closeout.md new file mode 100644 index 0000000..d85daea --- /dev/null +++ b/docs/work_orders/laptop_closeout.md @@ -0,0 +1,87 @@ +--- +title: "Kanshō – Arbeitsauftrag Laptop-Abschluss vor dem Heimtransfer" +status: "Arbeitsauftrag / teilweise erledigt" +date: "2026-09-07" +document_role: "Cursor Implementation Brief / Laptop Closeout" +canonical_handover: "docs/architecture/technical/environment_handover.md" +--- + +# Arbeitsauftrag: Laptop-Abschluss + +Arbeite im Repository `C:\dev\Kansho` auf dem **Urlaubs-Laptop**. Ziel ist, alles zu sichern und nach Gitea zu bringen, was zu Hause nicht mehr aus Cursor-Sessions rekonstruierbar ist. + +Dieses Dokument ersetzt nicht `docs/architecture/technical/environment_handover.md`. Docker, Postgres und Server-Deploy gehören **nicht** hierher, sondern nach `home_environment_setup.md`. + +## Bereits in der Transfer-Session erledigt (2026-09-07) + +- Opening-Fix gegen veraltete Recency-Impulse: Code vorhanden, `python tests/test_journal_opening.py` grün. +- Kanonische Doku nachgezogen (2026-09-07): `mvp.md` §6.1 Fehlerbild Nachsatz/Prefix, Fit-Gap `mvp_stand_und_abgleich.md`, `mvp_implementation.md` §17, `memory_storage_and_offline.md`. Bewusst offen dokumentiert: 400-Zeichen-Recency im laufenden Dialogzug. +- Inventar der lokalen SQLite-Instanz (1 Profil, 2 Spaces, 17 Days/Entries, 379 Messages). +- Inventar der lokalen SQLite-Instanz (1 Profil, 2 Spaces, 17 Days/Entries, 379 Messages). +- Lokales Backup: `local-backups/kansho-20260907-055703.zip` (~10,1 MB, SHA256 `2D1E160F6DF95FA0C46B8F3FE69C1681827DE0DF304A2E955304A5C56CC7854F`). SQLite + 70 Medien, keine Secrets. +- `.\scripts\test-mvp.ps1` Exit 0 (isolierte Temp-Daten, Produktions-SQLite unangetastet). +- Technisches Handover und Heim-Setup-Auftrag angelegt. + +## Noch auf dem Laptop, bevor die Instanz aufhört führend zu sein + +### 1. Keine neuen Produktfeatures + +Nicht auf dem Laptop beginnen oder zu Ende bauen: + +- `docs/work_orders/debug_diagnostics_perfection.md` +- `docs/work_orders/dialogue_memory_next_slice_handover.md` +- `docs/architecture/functional/Idea_seconmd_sclide.md` (Slice-2-Konzeptbrief) + +Diese Dateien versionieren, nicht ausführen. + +### 2. Git nach Gitea + +Ohne Push bleibt `e42f751 MVP 1.0` und der Opening-Fix nur auf dem Laptop. + +Vorschlag zwei Commits (dieser Abschluss darf committen, wenn der Nutzer den Transfer schließt): + +1. Opening-Fix + kanonische Opening-Doku (`mvp.md`, `mvp_implementation.md`, `mvp_stand_und_abgleich.md`, `memory_storage_and_offline.md`, Tests) +2. Transfer-Dokumentation, Work Orders, Slice-2-Brief + +Remote: `origin` = `https://gitea.stommer.de/Lars/Kansho.git`, Branch `main`. Nach dem Push `git status` muss „up to date with origin/main“ zeigen. + +`develop` auf dem Laptop **nicht** anlegen, solange kein Dev-Host existiert. + +### 3. Daten und Secrets physisch kopieren + +| Artefakt | Wohin | Nicht | +|---|---|---| +| `local-backups/kansho-20260907-055703.zip` | verschlüsselter Stick / NAS / Heimrechner | Git, Chat, Cloud-Klartext | +| `backend/.env` | separate Secret-Notiz oder Passwortmanager | Backup-Zip, Git | +| Login-Passwort des Admin-Profils | Kopf / Passwortmanager | Doku-Repo | + +Nach dem Kopieren Checksumme des Zip notieren (`Get-FileHash`). Restore prüft Manifest-Checksummen zusätzlich. + +Wenn nach dem Backup noch Dialoge auf dem Laptop laufen: neues Backup erzeugen und **dieses** Archiv mitnehmen. + +### 4. Instanz stilllegen + +- Uvicorn/Vite beenden. +- Keine parallelen Schreibzugriffe Laptop + Heimrechner auf denselben persönlichen Bestand. +- Laptop-Ordner als Archive behalten, bis Welle 1 zu Hause bestätigt ist. + +### 5. Kurzer lokaler Smoke (optional, wenn Zeit) + +Nur wenn der Opening-Fix committet werden soll und der Dev-Server ohnehin läuft: + +- Neuen Journal Day im Space `Kroatien 2026` starten: erster Impuls darf keine abgeschlossene Vortags-Episode als offenen Faden nehmen. +- `.\scripts\test-mvp.ps1` rührt die Produktions-SQLite nicht an. + +Kein Live-OpenRouter-Zwang für den Abschluss. + +## Abnahme Laptop + +- [ ] Opening-Fix und Transfer-Doku auf `origin/main` +- [ ] Backup-Zip außerhalb des Laptops +- [ ] `.env` außerhalb des Laptops +- [ ] Slice-2 / Debug / Memory-Aufträge nur versioniert, nicht implementiert +- [ ] Persönliche SQLite nicht in Git + +## Abschlussbericht + +Nennen: Commit-Hashes, Backup-Dateiname, ob nach dem Backup noch geschrieben wurde, was bewusst offen bleibt.