# 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