| # Copilot Tasks — Breakup Assistant (one-space) | |
| --- | |
| ## Recent updates (2025-10-27) | |
| - Added a subtle entrance animation for new chat messages (frontend). Messages now get a short pop-in animation via the `.chat-bubble.enter` CSS class. | |
| - Added a backend debug option: set `VERBOSE_STREAM=1` to print raw token events and assembled responses from `/api/chat/stream` for easier debugging of stray tokens. | |
| - Fixes (2025-10-28): | |
| - Fixed a runtime issue where the app could fail to fetch a dynamically created chunk for the no-contact helper ("Failed to fetch dynamically imported module: .../noContact-*.js"). The helper now uses a static import so it is bundled with the main chunk and avoids runtime chunk fetch failures in some hosts (HF Spaces, restricted CDNs). | |
| - Moved the no-contact toggle into the profile header and implemented an optimistic UI: starting no-contact shows days = 0 immediately. Day counting is canonicalized to a floor-based 24h rule: days = Math.max(0, Math.floor((now - startISO) / 86_400_000)). | |
| - Added Vitest edge/integration tests for no-contact day calculation and awarding the "1 den bez kontaktu" medal. Tests running in Node must mock the `idb-keyval`/storage helpers; consider adding a global Vitest setup file to centralize this mock. | |
| Update (2025-11-03): Activity logging & medal UI | |
| - The frontend now centralizes assistant+journal emission via `emitAssistantAndJournalWithOptions` and emits each logged event as its own assistant message. This enables messages to carry `meta` (e.g. `{ type: 'medal', medal: 'První krok' }`) which the chat renderer uses to apply special visuals (medal badge, `.chat-bubble.medal`) and to improve auditability. | |
| - No‑Contact UI: consolidated controls (2025-11-03) | |
| - Removed the small circular quick-actions under the No‑Contact ticker (Reset / small toggle / progress) to avoid duplicate controls. | |
| - Added a visible primary toggle button next to "Upravit začátek" and "Nastavit na teď" that uses `noContact.startISO` as the canonical state and toggles label between "Zahájení Bez Kontaktu" and "Ukončit Bez kontaktu". This makes the UI deterministic and easier to test. | |
| - Testing guidance: prefer assertions on message content and `meta` rather than fragile ordering. Add a small Vitest DOM test that renders a chat message with `meta.type === 'medal'` and asserts the medal badge and `.chat-bubble.medal` class are present. | |
| - Styles consolidation (2025-11-03): safely merged duplicate `.purple-ticker` and `.medal-icon` rules in `frontend/src/styles.css`, removed an extra duplicate `.medal-icon` block, and added a top-of-file maintainer note to prevent accidental future duplication. This reduces CSS conflicts and stabilizes the No‑Contact ticker and medal UI. | |
| ## Copilot Best Practices (Quick Reference) | |
| - Vždy dodržuj privacy-by-default, governance, auditovatelnost, audit metadata v obsahu | |
| - Modularizuj kód i obsah, validuj versioning, manifest, i18n, varianty, audit | |
| - PR workflow: popiš změny, odkaž na architekturu/task, přidej testy, validuj coverage | |
| - Onboarding: README, architektura, troubleshooting, governance, testy, validace obsahu | |
| - CI/CD: testy, lint, golden scénáře, adherence dashboard, validace integrity obsahu | |
| - Replay mód: trace_log + Plan JSON → reprodukce běhu bez LLM | |
| - Zásadní změny konzultuj v týmu, dokumentuj v architektuře, validuj audit metadata | |
| - Odkazy na instrukce: [.github/instructions/](.github/instructions/), [README.md](README.md), [ARCHITECTURE.md](docs/ARCHITECTURE.md) | |
| ## Tasky & akceptační kritéria | |
| **Status:** ✅ **KOMPLETNÍ IMPLEMENTACE + VYČIŠTĚNO + MODERNÍ GAMIFIKAČNÍ UI + ROZŠÍŘENÁ TEST INFRASTRUKTURA + PROFESIONÁLNÍ ONBOARDING + ATTACHMENT STYLES ASSESSMENT** - **reálný chat s LLM orchestrátorem**, 228 testů (lokálně zelené, včetně 43 nových testů pro prevenci regresí medal/profile/journal/chat funkcionality + 4 testy pro attachment funkcionalitu), fetch() komunikace pro HF Spaces kompatibilitu, **lokální persistentní stav (profil, chat, deník, no-contact, medaile, attachment výsledky) v IndexedDB**, **konzistentní logování bez duplicit** (activityLogger jednotnost), **medal systém synchronizace** (backend používá statistiky pro kontrolu medailí, frontend zobrazuje medaile z obou zdrojů), **vylepšená syntéza odpovědí s emotikony a markdown formátováním**, **opravený no-contact stav v profilu** (správné zobrazení po restartu aplikace), **vyčištěný kód bez duplicit a nepoužívaných souborů**, **progres medailí s moderním UI** (progress bary, ikony, animace), **vyřešená Vite varování** (čistý build bez optimalizačních poznámek), **opravené testy s relativními cestami** (všechny 228 testů prochází spolehlivě v batch i individual módu), **opravené duplicitní medaile v profilu** (sjednocená ID medailí mezi journal a medalProgress), **profesionální 3-krokový onboarding modal** (místo jednoduchého pole pro jméno), **načítání posledního aktivního tabu** z IndexedDB při spuštění aplikace, **kompletní reset aplikace** přes tlačítko "Zapomenout vše" (maže všechna data včetně onboarding stavů), **interaktivní attachment styles assessment** s personalizovanými healing plány. | |
| ### 1) Frontend (FE) ✅ | |
| - **Moderní UI Design:** Glassmorphism efekty, smooth animace, micro-interactions, mobile-first responsive | |
| - Tabs: Chat / Deník / Podpora / Profil s interaktivní navigací | |
| - **Fetch klient** (`lib/sse.ts`): simulace token streamování přes fetch() pro HF Spaces kompatibilitu | |
| - Backend returns structured `tokens` array (objects with {agent, token}) and frontend simulates streaming by splitting tokens into words for UX. This allows UI to attribute message fragments to specific agents. | |
| - Zustand store: chat, journal, medals, noContact, traits, medalState | |
| - Storage: cookies (pointer), IndexedDB (data, log, medals, volitelné šifrování) | |
| - No-contact helper: streak engine, reset, denní pochvala, milestone medaile | |
| - **Medals helper: katalog, pravidla, XP, progress bar - všechny medaile v jedné sekci s dokončenými označenými 🏆 ikonou a zeleným pozadím** | |
| - Šifrování: WebCrypto AES-GCM, PIN, auto-lock (volitelné) | |
| - **Onboarding systém:** Automatická detekce prvního spuštění na základě existence dat (profil nebo chat), žádný `onboarding_completed` flag | |
| - **Automatický reset:** `handleForget` funkce kompletně maže všechna data a reloadne aplikaci s cache-busting pro čistý start | |
| ### 2) Backend (BE) ✅ | |
| - **`/api/chat/stream`**: JSON response with structured `tokens` and `response` from reálným LLM orchestrátorem (Google Gemini + Hugging Face). Canonical orchestrator: `backend/mcp/orchestrator/sse_orchestrator.py`. | |
| - `/api/content/*`: read-only JSON (tipy, aktivity, meditace, versionované, manifest, i18n, varianty, audit metadata) | |
| - **Orchestrátor: mcp-agent s reálnými LLM** (9 agentů), multi-agentní řízení, gating toolů, policy engine | |
| - MemoryPatch: návrhy změn, eventy, audit | |
| ### 3) Agentní Architektura ✅ IMPLEMENTOVÁNO | |
| Aplikace používá **multi-agentní orchestrátor** s 9 specializovanými agenty řízenými hlavním **Drafter agentem**: | |
| #### **Hlavní Agent: Drafter (Syntetizátor)** | |
| - **Role:** Koncentruje odpovědi od všech ostatních agentů do jedné koherentní odpovědi | |
| - **Vidí:** Historii chatu, dokončené aktivity, no-contact stav, zápisy do deníku | |
| - **Výstup:** Jedna empatická, podpůrná odpověď kombinující insights všech agentů | |
| #### **Specializovaní Agenti (všichni funkční):** | |
| | Agent | Role | Nástroje | Status | | |
| |-------|------|----------|--------| | |
| | **Coach** | Empatická komunikace, emocionální podpora | `get_user_profile`, `get_medals`, `get_daily_plan`, `tts` | ✅ | | |
| | **Planner** | Plánování aktivit a denních rutin | `search_tips`, `log_activity`, `award_medal`, `journal_append` | ✅ | | |
| | **Guardian** | No-contact podpora a hranice | `get_no_contact_status`, `praise_no_contact_if_new_day`, `journal_append` | ✅ | | |
| | **Curator** | Správa deníku a reflexe | `journal_list`, `journal_append`, `journal_redact`, `journal_export` | ✅ | | |
| | **Evaluator** | Hodnocení pokroku a medaile | `evaluate_medals`, `recalc_streaks` | ✅ | | |
| | **Strategist** | Dlouhodobé strategické plánování | `strategy_plan` | ✅ | | |
| | **Sentinel** | Moderace vstupů a detekce krizí | `moderate_input`, `crisis_contacts` | ✅ | | |
| | **Analyzer** | Analýza emocí a vzorců | Žádné (analýza textu) | ✅ | | |
| | **Drafter** | Syntéza finální odpovědi | Žádné (syntéza) | ✅ | | |
| #### **Jak Funguje Orchestrace:** | |
| 1. **Frontend posílá user state:** Historie chatu, aktivity, no-contact, deník, medaile | |
| 2. **Orchestrátor vybírá agenty:** Podle obsahu zprávy (např. "plan" → planner, "sad" → analyzer) | |
| 3. **Agenti generují odpovědi:** Každý pomocí svého LLM providera (Google Gemini/Hugging Face) | |
| 4. **Drafter syntetizuje:** Kombinuje všechny odpovědi do jedné koherentní odpovědi | |
| 5. **Uživatel dostane:** Empatickou, personalizovanou odpověď s kontextem | |
| #### **Kontext Awareness:** | |
| - **Vidí dokončené aktivity:** "Vidím, že jsi dokončil 'Ranní dýchání' a 'Procházku'" | |
| - **Sleduje no-contact:** "Držíš to už 5 dní, jsi silný/á!" | |
| - **Znají journal entries:** Reference na předchozí zápisy | |
| - **Pamatuje chat historii:** Kontinuita konverzace | |
| ### 3) Governance & policy ✅ | |
| - `capabilities.json`: role → povolené tooly (gating) | |
| - `policy.yaml`: pořadí agentů, limity tool-calls/turn, timeouty, gates, replay | |
| - `mcp_agent.config.yaml`: MCP servery, aggregator | |
| ### 4) Testování ✅ | |
| - Kompletní test infrastruktura: 228 testů (100% úspěch, včetně 43 nových regresních testů + 4 testy pro attachment funkcionalitu) | |
| - Modularizovaná struktura: | |
| - **Python testy v `tests/` adresáři:** 186 testů pro backend funkcionality (pytest framework) | |
| - Unit testy: všech 9 agentů, orchestrátorů, content API, reducerů (129 původních testů) | |
| - Contract testy: Pydantic modely (MEDAL, MPKT, MemoryPatch, AnalysisSummary, StrategyPlan) | |
| - Golden scénáře: 12+ YAML sekvence pro chat eventy, CI pipeline validace | |
| - Replay mód: trace_log + Plan JSON → reprodukce běhu bez LLM pro debugging | |
| - Integrace: orchestrace agentů, governance, memory patch, chat stream | |
| - End-to-end: kompletní chat flow, crisis detection, privacy enforcement | |
| - **Regresní testy:** 43 specializovaných testů pro prevenci problémů s medal/profile/journal/chat funkcionalitou: | |
| - `test_activity_logger_consistency.py` (15 testů) - activity logger jednotnost, checkAndLogMedals integrace, no-contact lastPraiseISO nastavení, journal callback pattern | |
| - `test_medal_profile_integration.py` (15 testů) - zobrazení medailí z journal záznamů, frontend state consistency, prevence duplicit v daily praise | |
| - `test_local_statistics_calculation.py` (13 testů) - lokální výpočet statistik z IndexedDB, nezávislost na backendu, progress výpočty pro UI | |
| - **Frontend testy v `frontend/tests/` adresáři:** 42 testů pro React/TypeScript komponenty a stores (Vitest framework) | |
| - **Attachment testy:** 4 specializované testy pro attachment styles funkcionalitu: | |
| - `AttachmentView.test.tsx` - interaktivní test komponenta, progress tracking, výsledky | |
| - `attachment.test.ts` - Zustand store s persist middleware, výsledky assessment | |
| - `attachment.integration.test.ts` - end-to-end flow assessmentu | |
| - `attachment.store.test.ts` - state management a persistence | |
| - **Onboarding testy:** Unit testy pro onboarding logiku (`test_onboarding.py`) a frontend testy (`unit.test.ts`) | |
| ### 5) Best practices ✅ | |
| - **Moderní UI/UX:** glassmorphism efekty, smooth animace, micro-interactions, mobile-first design, **markdown formátování v chatu** | |
| - Privacy-by-default: žádná PII na serveru, šifrování lokálně, auditovatelnost | |
| - Multi-agentní řízení: striktní kontrakty, gating, replay, fail-safes | |
| - Reaktivní UI: batchování renderů, virtuální listy, debounce, stavové přechody | |
| - Onboarding: README, architektura, role, governance, testy, troubleshooting | |
| - CI/CD: testy, lint, golden scénáře, adherence dashboard | |
| ## Role & návaznost na architekturu | |
| - Coach: empatická formulace, finální hlas, chvála, CTA | |
| - Planner: výběr/rozvrh mikro-aktivit, logování, medaile | |
| - Guardian: No-contact engine, pochvala, reset, deník | |
| - Curator: sumarizace, snippets, journal management | |
| - Evaluator: Hodnocení medailí, streak recalculation | |
| - Strategist: Dlouhodobé strategické plánování | |
| - Sentinel: Moderace vstupů, detekce krizí, privacy enforcement | |
| - Drafter: Empatické text streaming pro různé kontexty | |
| - Analyzer: Pokročilé analýzy a insights | |
| ## Activity Logging | |
| - **ActivityLogger jednotnost:** Všechno logování dokončených akcí (tipy, aktivity, meditace, noContact, **medaile**) probíhá přes `activityLogger.ts` pro konzistentní záznamy v chatu a deníku bez duplicit. **Medaile se nyní logují okamžitě při dosažení v ProfileView.tsx, ne až po odpovědi backendu.** | |
| - **Aktualizace (2025-11-03):** Centralizovaný logging | |
| - Implementován nový helper `emitAssistantAndJournal(agent, message, journalText, meta?, medalCategories?)` v `frontend/src/lib/activityLogger.ts`. | |
| - Všechny veřejné logovací funkce byly refaktorizovány tak, aby volaly tento helper a čekaly na dokončení persistence/journal zápisu a případné kontroly medailí. | |
| - Přidán unit test `frontend/tests/loggers.activityCompletion.test.ts` a upraveny testy tak, aby v Node prostředí před importem store mockovaly `frontend/src/lib/storage.ts` (idb wrapper), čímž se předešlo chybě `indexedDB is not defined`. | |
| - Doporučení: při dalších změnách loggingu používat helper a přidat testy, které mockují storage před importem store modulů. | |
| - Cleanup (2025-11-03): | |
| - Removed temporary debug instrumentation (console logs) from `SelfReturnView.tsx` and diagnostic console output in `frontend/src/lib/activityLogger.ts` to reduce runtime noise. | |
| - `emitAssistantAndJournal` now appends to the last assistant bubble only when that bubble was created by the same agent (`last.agent === agent`) to avoid invisible merges that hid new assistant messages. | |
| - `checkAndLogMedals` was updated with a guard/coalescing mechanism to prevent concurrent runs and coalesce rapid repeated calls; high-value medal-earned logs remain. | |
| ### Types & object-style API | |
| - The activity logger exports typed helpers in `frontend/src/lib/activityLogger.ts`: | |
| - `JournalMeta` — generic metadata type for journal entries (`Record<string, unknown>`). | |
| - `EmitOptions` — object-style options for the helper: `{ agent: string; message: string; journalText: string; meta?: JournalMeta; medalCategories?: string[] }`. | |
| - Preferred usage: `emitAssistantAndJournalWithOptions(opts: EmitOptions)` — this object-style overload is clearer, easier to extend and safer in tests. The function-style variant remains for compatibility. | |
| Test guidance: prefer importing and using the object-style overload in new code and tests; when writing Node/Vitest tests mock `frontend/src/lib/storage.ts` (the `idb-keyval` wrapper) before importing any store modules so tests do not require browser `indexedDB`. | |
| - Dokončené aktivity → chat + journal | |
| - **Získané medaile → chat + journal** (automaticky při dosažení v profilu) | |
| - No-contact milníky → chat + journal | |
| - Přečtené tipy → chat + journal | |
| - Dokončené meditace → chat + journal | |
| **Prevence duplicit:** Všechno logování probíhá centralizovaně, žádné přímé volání z komponent. | |
| ## Attachment Styles Assessment ✅ IMPLEMENTOVÁNO | |
| - **Interaktivní test:** 4 styly připoutání (secure/anxious/avoidant/disorganized) s 12 otázkami | |
| - **Personalizované healing plány:** Strategist agent generuje specifické rady pro každý styl | |
| - **Content struktura:** `content/attachment_styles.json` s otázkami, bodováním, charakteristikami, healing plány | |
| - **Frontend komponenta:** `AttachmentView.tsx` s progress tracking, výsledky, vizuální prvky (ikony, barvy) | |
| - **State management:** Zustand store `attachment.ts` s persist middleware pro výsledky assessmentu | |
| - **Backend integrace:** Strategist agent s `attachment_healing_plan` metodou pro 4 styly podpory | |
| - **Activity logging:** Dokončený assessment → chat + journal přes activityLogger | |
| - **Test pokrytí:** 4 specializované testy pro komponentu, store, integraci a state management | |
| ## Akceptační kritéria ✅ | |
| - Každý task má jasné vstupy/výstupy, testy, audit, adherence k privacy a governance | |
| - Onboarding pro nové vývojáře: README, architektura, troubleshooting | |
| - Testy: kompletní infrastruktura s 185 testy (100% úspěch, včetně 43 regresních testů + 4 testy pro attachment funkcionalitu), coverage, privacy-by-default, audit metadata v obsahu | |
| - **Kontrola integrity kódu:** Žádné duplicitní bloky, proměnné, funkce nebo soubory; čistý kód bez stray importů/volání | |
| - **Všechny funkcionality implementovány:** Content API, všech 9 agentů, orchestrátory, kompletní test pokrytí | |
| ## Lekce z vývoje | |
| **📚 Kompletní dokumentace všech lekcí: [docs/lessons-learned.md](docs/lessons-learned.md)** | |
| **Pro rychlou referenci zde jsou nejkritičtější pravidla:** | |
| ### ✅ ActivityLogger Jednotnost | |
| - Všechno logování přes `activityLogger.ts` - zakázané přímé volání `pushChat`/`addJournal` | |
| - **Detail:** [ActivityLogger Best Practices](docs/lessons-learned.md#activitylogger-jednotnost) | |
| ### ✅ Testování Essentials | |
| - Mock `storage.ts` před importem store modulů (Node testy) | |
| - useLayoutEffect pro synchronní DOM updates | |
| - Správné dependency arrays v useCallback/useEffect | |
| - **Detail:** [Testing & Debugging](docs/lessons-learned.md#testování--debugging) | |
| ### ✅ Code Integrity Checklist | |
| - Žádné duplicitní bloky/proměnné/soubory | |
| - Jeden main entrypoint (`app.py`) | |
| - Validace před commitem: `python -c "import app"` + `pytest -q` | |
| - **Detail:** [Code Integrity](docs/lessons-learned.md#kontrola-integrity-kódu) | |
| --- | |
| **💡 Při řešení problému vždy nejdříve zkontroluj [docs/lessons-learned.md](docs/lessons-learned.md) - pravděpodobně už byl vyřešen!** | |
| ## Další dokumentace | |
| - [README.md](README.md) — architektura, onboarding, best practices | |
| - [ARCHITECTURE.md](docs/ARCHITECTURE.md) — detailní architektura, doménový model, agentní vrstva | |
| - [deployment/huggingface-spaces.md](../deployment/huggingface-spaces.md) — runbook pro nasazení na HF Spaces | |
| - [.github/copilot-instructions.md](.github/copilot-instructions.md) — workflow pro Copilot, best practices | |
| - [Instrukce](.github/instructions/) — governance, testy, infra, obsah | |