docs/development/tasks.md

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/, README.md, 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

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

✅ 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

✅ 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

---

💡 Při řešení problému vždy nejdříve zkontroluj docs/lessons-learned.md - pravděpodobně už byl vyřešen!

Další dokumentace

• README.md — architektura, onboarding, best practices
• ARCHITECTURE.md — detailní architektura, doménový model, agentní vrstva
• deployment/huggingface-spaces.md — runbook pro nasazení na HF Spaces
• .github/copilot-instructions.md — workflow pro Copilot, best practices
• Instrukce — governance, testy, infra, obsah