docs: дополнить ARCHITECTURE.md из всех брейншторм-файлов

Добавлено: роли/permissions, git workflow, checkpoint pattern,
таймауты, связи задач, межагентная коммуникация, Telegram Bridge
детали, версионирование API, деплой, конкурентный анализ,
раздел 'Идеи на подумать'

ARCHITECTURE.md

@@ -1,5 +1,5 @@
 # Team Board — Архитектура
-Версия: 0.2 (драфт)
+Версия: 0.3 (драфт)
 Дата: 2026-02-21
 
 ## Что это
@@ -81,11 +81,32 @@ TaskComment: id, task_id, author_type (human|agent|system),
 ```
 Mentions (@slug) → уведомление агенту через WS.
 
+### Связи между задачами (Task Links)
+Помимо parent/child и depends_on, задачи поддерживают дополнительные связи:
+- **relates_to** — связанные задачи (информационно)
+- **duplicates** — дубликат другой задачи
+- **blocks / blocked_by** — блокировка (аналог depends_on, но для человеческого UI)
+
+Агенты используют `depends_on` для автоматики, остальные связи — для людей в UI.
+
+### Назначение задач
+1. Человек назначает вручную
+2. Архитектор создаёт и назначает
+3. Агент сам берёт из `todo` по capabilities (`task.take` — атомарная операция)
+4. Через чат с @mention: "ребята, новая задача"
+5. Auto-assign: Tracker предлагает задачу по capabilities + загрузке (HYBRID модель)
+
+### Приоритизация очереди
+- По приоритету задачи (critical → high → medium → low)
+- Если задача назначена на конкретного агента → он берёт первым
+- Label matching: лейблы задачи ∩ capabilities агента
+
 ### Особенности
 - Агент может **отклонить** задачу (reject_task) с обоснованием
 - **Автообнаружение блокеров**: зависимость застряла → пинг в чат
-- Задача-наблюдатель: мониторинг, не исполнение
+- **Задача-наблюдатель**: не на выполнение, а мониторинг ("следи за CI", "проверяй X раз в час"). Периодическая/фоновая задача.
 - Задача порождает подзадачи автоматически (агент создаёт через create_task)
+- Циклические зависимости запрещены (валидация при создании)
 
 ## Чаты
 
@@ -111,6 +132,24 @@ ChatMessage: id, chat_id, author_type, author_slug,
 
 ## Агенты (Picogent)
 
+### Роли
+| Роль | Описание | Права по умолчанию |
+|------|----------|-------------------|
+| `owner` | Владелец доски. Полные права. Один на инстанс. | Все |
+| `agent` | AI-агент. Выполняет задачи, пишет в чат. | send_messages, update_tasks |
+| `bridge` | Мост (Telegram, Slack). Пересылает сообщения, не берёт задачи. | send_messages |
+| `observer` | Только чтение. Получает события, но не может действовать. | — |
+
+### Права (permissions)
+| Право | Описание |
+|-------|----------|
+| `send_messages` | Отправка сообщений в чаты |
+| `create_tasks` | Создание новых задач |
+| `assign_tasks` | Назначение задач другим агентам |
+| `update_tasks` | Изменение статуса/описания задач |
+| `manage_agents` | Управление другими агентами |
+| `manage_projects` | Создание/изменение проектов |
+
 ### Конфигурация
 Один бинарник, роль = конфиг (`agent.json`):
 ```json
@@ -150,6 +189,37 @@ Per-agent + per-project. Агент дописывает findings после з
 ### Label Matching
 Задача имеет labels, агент поддерживает labels → автоматический matching для assign.
 
+### Проблема "глухого агента" (Checkpoint Pattern)
+LLM `query()` блокирующий — агент не слышит новых сообщений пока думает.
+
+**Решения:**
+- **Короткие задачи** — декомпозиция на шаги по 5-10 минут
+- **Checkpoint pattern** — агент проверяет входящие между шагами работы
+- **session.checkpoint** — агент сохраняет своё понимание контекста в Tracker, чтобы при сбое продолжить с того же места
+
+### Зависший агент / Таймауты
+- **Heartbeat** — агент шлёт `agent.heartbeat` каждые 30 секунд
+- Если heartbeat не пришёл 90 секунд → `agent.status = offline`
+- Уведомление в чат: "Агент X перестал отвечать"
+- **Grace period**: при дисконнекте статус сначала `away` (60 сек), потом `offline`
+- Незавершённые задачи: возвращаются в `todo` или ждут (зависит от политики)
+- **Рестарт**: systemd перезапускает picogent, агент делает session.resume
+
+### Reconnect и восстановление сессии
+При реконнекте агент отправляет `session.resume` с `last_seq` (последнее известное сообщение). Tracker возвращает `context_summary` + пропущенные сообщения. Агент продолжает работу.
+
+### Контракт агента (contract)
+Описывает capabilities, лимиты и разрешённые tools:
+```json
+{
+  "capabilities": ["coding", "review"],
+  "max_concurrent_tasks": 2,
+  "timeout_seconds": 600,
+  "tools": {"file_read": true, "git_commit": true, "shell_exec": false},
+  "limits": {"max_file_size_mb": 10, "max_files_per_task": 20}
+}
+```
+
 ## Протокол
 
 ### Принцип
@@ -189,6 +259,14 @@ Tracker → Agent: auth.ok, auth.error, event
 ### Router (в Picogent)
 Тупой relay: WS event → текст → единственная сессия агента. Агент сам вызывает tools.
 
+### Межагентная коммуникация
+Агенты общаются через чат (send_message с @mention). Для структурированных запросов — протокол `agent.request` / `agent.response`:
+```
+Кодер → Tracker: agent.request {target: "reviewer", type: "code_review", payload: {pr_url}}
+Tracker → Ревьюер: agent.request {from: "coder", request_id, payload}
+Ревьюер → Tracker: agent.response {request_id, result: {approved, comments}}
+```
+
 ## Файловое хранилище
 
 - Per-project директории
@@ -196,30 +274,121 @@ Tracker → Agent: auth.ok, auth.error, event
 - Связь с git repos (repo_urls[])
 - Версионирование файлов — TBD
 
+## Git Workflow
+
+### Принцип
+- Агент клонирует repo в свою рабочую директорию
+- Работает в отдельной ветке: `{type}/{task-id}-{slug}` (feat/fix/refactor/docs)
+- По завершении → **Merge Request** в Gitea
+- Ревью (агент/человек) → approve/reject
+- **Автомерж** после approve
+
+### Конфликты
+- Решает тот, чей MR. После разрешения — повторный review.
+- Lock на файлы — **не нужен**
+- Максимум 3 итерации ревью, потом эскалация к человеку
+
+### Gitea интеграция
+- Webhooks от Gitea → Tracker: push, PR opened/reviewed/merged
+- Tracker → Gitea API: создание веток, PR, комментирование
+- PR merged → задача автоматически в Done
+- CI/CD через Gitea Actions — автотесты на MR
+
+### Ревью
+- Автор ≠ ревьюер (всегда)
+- Не каждая задача требует PR (определяется лейблами: `coding` → PR, `analytics` → нет)
+- Все комментарии ревью в задаче (единый контекст)
+
 ## Telegram Bridge (MVP)
 
-- Один бот, подключается по WS к Tracker
+- Один бот, подключается по WS к Tracker как `client_type=bridge`
 - Дублирует сообщения из project chats в Telegram
-- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта
+- **Топики**: если в Telegram включены topics → бот пишет в топик с именем проекта (каждый проект = отдельный топик)
-- Форматирование: `[Кодер] текст сообщения`
+- Форматирование: `👤 Eugene: текст` / `🤖 Кодер: текст` / `⚙️ Задача #42 → in_progress`
+- **Telegram → Tracker**: сообщение из группы → `chat.send` с `sender_type=bridge`
+- **Упоминания**: парсит `@slug` из Telegram → `mentions` в `chat.send`
+- Системные события (task.created, task.updated) → уведомления в группу
+- ⚠️ Ограничение Telegram: боты НЕ видят сообщения других ботов → один бот = bridge для всех
 
 ## Безопасность
 
-- Агенту доступны определённые действия (allowed_paths, capabilities)
+- **Аутентификация**: токены (прописываются при регистрации агента). Каждый агент = уникальный токен.
-- Разные уровни доступа — TBD
+- **Роли и permissions**: owner / agent / bridge / observer (см. раздел Агенты)
-- Rate limiting — TBD
+- **Capabilities enforcement**: агент с capabilities=["code"] не получит задачи на review
-- Audit log — TBD
+- **Rate limiting** — планируется: chat.send 30/min, task.progress 10/min и т.д.
+- **Audit log** — планируется: логирование всех действий
+- **Token rotation** — планируется: ротация каждые 30 дней
+
+## Версионирование API
+
+- REST API: `/api/v1/`, `/api/v2/`
+- Обратная совместимость при обновлении
+- WS Protocol: версия в auth handshake
+
+## Деплой
+
+- **Tracker + BFF + Web Client**: Docker Compose
+- **Picogent**: systemd сервис (один процесс на агента)
+- Автоматический restart при падении (systemd)
+- CI/CD: Gitea Actions auto-deploy
+- Агент-DevOps возможен для CI/CD задач
 
 ## На будущее
 
-- **Web MCP Server** — отдельный пакет, любой LLM-клиент (Claude Code, Cursor) работает с трекером через MCP без Picogent
+- **Web MCP Server** — отдельный пакет (`team-board/mcp-server`), любой LLM-клиент (Claude Code, Cursor, Windsurf, Cline, OpenClaw) работает с трекером через MCP без WebSocket и без Picogent. Использует тот же REST API. Не автономный (нет push-событий), но полностью функциональный.
-- **Multi-instance агентов** — scaling, несколько кодеров
+- **Multi-instance агентов** — scaling, несколько кодеров одного типа. Вопрос: slug = роль, instance_id = отдельно? Требует продумывания.
-- **Аналитика** — метрики, дашборды
+- **Аналитика** — метрики, дашборды (tasks/hour, avg task duration, agent utilization)
 - **OAuth / Authentik** — мульти-пользователь
-- **Notification Bridge** — push-уведомления за пределами чата
+- **Notification Bridge** — отдельный bridge-агент, подключается по WS, пушит уведомления за пределы чата (email, push, webhooks)
+- **Agent SDK** — Python-пакет (`team-board-sdk`) с базовым классом Agent, обработчиками on_task/on_chat/on_reconnect, интеграцией с git
+- **Session Compaction** — при превышении контекста (50K токенов) сжатие истории в summary + recent window
+- **Event Sourcing** — вся работа агента как поток событий для воспроизведения и восстановления состояния
 
-## Референсы
+## Конкурентный анализ (референсы)
 
-- **MetaGPT** — промпты ролей (PM, Architect, Engineer, QA)
+| Система | Ключевые идеи | Что забираем |
-- **Claude Flow** — claims, swarm coordination
+|---------|---------------|-------------|
-- **BMAD Method** — brainstorming workflows
+| **MetaGPT** | Промпты ролей (PM, Architect, Engineer, QA), pub/sub между ролями, SOP | Промпты для назначения ролей агентам |
+| **Claude Flow / Ruflo** | Claims (атомарное взятие задач), swarm топологии, multi-provider | Паттерн claims для task.take |
+| **BMAD Method** | Brainstorming workflow, party mode (мульти-ролевой prompt) | Workflow для планирования |
+| **OpenHands** | Event sourcing, Docker sandbox, event log replay | Воспроизводимость сессий |
+| **LangGraph** | State machine + persistent checkpointing | Checkpoint pattern |
+| **CrewAI** | Role-based delegation, task routing по ролям | Capabilities matching |
+| **Devin** | VM-sandbox, persistent sessions (часы), полный git цикл | Долгие сессии с checkpoints |
+
+### Picogent vs Runner
+Picogent (Node.js, TypeScript, Pi Agent Core) **заменяет** runner/ — более зрелая реализация. In-process agent loop, dual transport (HTTP + WebSocket), skills, sessions, sandbox, directory mode.
+
+## Идеи на подумать
+
+### ⚠️ Требуют отдельного обсуждения
+- **Rollback файлов**: git revert очевиден, но файлы в хранилище **не версионированы**. Нужно ли версионирование файлов или хотя бы бэкап перед изменением?
+- **Реакции в чатах**: выглядит круто, но жрёт токены. Варианты: (a) не попадают в промпт агента, (b) агент ставит через MCP tool, (c) попадают только @mention-reactions. Решение TBD.
+- **Лейблы глобальные или per-project?** — не решено
+- **Формат скилла для Runner'ов** — как описать взаимодействие агента с Tracker
+- **Как агент определяет релевантность задачи для себя?** — auto-assign vs manual
+- **Workspace агентов: общий или изолированный?**
+- **Прогресс работы агента в реалтайме** (streaming в UI)
+
+### 💡 Идеи на будущее
+- **Agent SDK v1.0** — Python-пакет с базовым классом, git-хелперами, LLM-интерфейсом
+- **Redis Streams** для event bus (горизонтальное масштабирование Tracker)
+- **Structured inter-agent requests** (agent.request/response) для code review, delegation
+- **task.offer / task.accept / task.decline** — Tracker предлагает задачу, агент может отклонить (HYBRID модель)
+- **Compaction сессий** — server-side или agent-side сжатие контекста
+- **Grafana dashboard**: WS connections, task flow, agent utilization
+- **Token rotation** (30 дней) + per-agent capability enforcement
+- **Docker containers per agent** для sandbox isolation
+- **Gitea webhook handler** в Tracker для автоматизации git-событий
+- **HTTP Callback** как альтернативный транспорт (Tracker POST'ит события на URL агента)
+- **Агент создаёт проект** — Архитектор может создать проект через API
+- **Subscription modes**: `all` / `mentions` / `assigned` (разные уровни вовлечения)
+
+### ❌ Отклонено (из брейншторма)
+- Шаблоны задач / проектов — не нужны
+- Forking проектов — не нужен
+- Автостатус задач — не нужен
+- Оценка сложности / дедлайны — не нужны
+- Lock на файлы — не нужен
+- Бюджет в токенах — нет
+- Приватность проектов — агент не трогает чужое