PTSRaiAgent/docs/dev/WORKFLOW.md

Регламент работы: зоны, задачи, git, коммиты

Основан на регламенте TenVex/vobot, облегчён под хакатон (ADR-009). Дедлайн: пн 05.10.2026, 13:00 МСК.

Зоны и файлы

Зона (label)	Пути	Отвечает за	Владелец
core	app/core/	privacy, шкалы и скоринг, safety, движок правил, демо-часы	dev
bot	app/dialog/, app/channels/, app/llm/	FSM диалога, Telegram-адаптер, LLM-шлюз (GigaChat/mock)	Егор
backend	app/db/, app/api/, app/scheduler/, app/integrations/	БД, API, шедулер, моки МИС/ЕСИА/ГРЛС, уведомления	dev
dashboard	dashboard/	дашборд врача, демо-консоль (Streamlit)	dev
devops	docker-compose.yml, Dockerfile, Makefile, .gitea/, pyproject.toml	окружение, CI, запуск на чистой машине	dev
clinical	config/ (содержимое), data/eval/	шкалы, пороги, тексты, лексикон, кризисный скрипт	психиатр
pitch	docs/pitch/	презентация, клинико-экономика, CJM, правовые слайды	медик
docs	docs/, README.md, CLAUDE.md	регламенты, ADR, README	все

Замок зоны: пока на зону есть открытый issue с активной веткой, файлы зоны принадлежат ему до мержа. Перед правкой: git fetch origin && git branch -r. Схемы config/*.yaml задаёт core (pydantic-модели), а значения в них — clinical.

---

Откуда задачи

• Только из Gitea $GITEA_REPO. Нет issue — нет кода. Нет подходящего issue — заведи его на себя.
• Атрибуты: метка зоны, тип (feature/fix/refactor/docs/chore), размер (size/0.5 ≈ 2 ч, size/1 ≈ 4 ч, size/2 ≈ день), milestone (M1/M2/M3), приоритет P0/P1/P2.
• Одна задача = одна зона. Нужно несколько зон → несколько issue, связанных зависимостью через API (GITEA_API.md).
• Тело issue — по шаблону ISSUE_TEMPLATE.md.

Milestones

Milestone	Срок	Смысл
M1 Каркас	сб 03.10, 23:59	ядро, БД, LLM-шлюз, конфиги; тесты зелёные
M2 Демо-сценарий	вс 04.10, 23:59	весь сценарий проходит end-to-end в демо-консоли
M3 Сдача	пн 05.10, 13:00	README, презентация PDF, репетиция, dev → main

---

Жизненный цикл задачи

1. Взял issue (assignee = $GITEA_USER), зона свободна
2. git fetch origin
3. git worktree add .claude/worktrees/<issue#>-<slug> -b <type>/<issue#>-<slug> origin/dev   ← ДО первого изменения
4. cp .env в worktree; uv sync
5. Код по модулям; коммиты с Refs #N
6. git ls-remote --heads origin <ветка>     ← пусто после первого пуша = PR смержен, стоп
7. git fetch && git rebase origin/dev
8. make lint && make test
9. Лог в тело issue: ### YYYY-MM-DD
10. PR в dev с Closes #N → после зелёного CI мержит автор (облегчение хакатона)
11. git worktree remove .claude/worktrees/<issue#>-<slug>

Задача завершена → сам: коммит → push → PR. Не запушено — не сделано.

Git

main  ← сдаваемая версия, мержит только человек (пн утром)
dev   ← интеграция, сюда все PR
<type>/<issue#>-<slug>  ← от dev

Коммиты — Conventional Commits

feat(core): add PHQ-9 scoring with item-9 escalation

Refs #3

scope = зона. Closes #N — только в описании PR.

Шаблон PR

## Что меняется
1–3 предложения.

Closes #<N>

## Зона
core | bot | backend | dashboard | devops | clinical | pitch | docs

## Как проверить
шаги/команды

## Чек-лист
- [ ] rebase на origin/dev
- [ ] make lint + make test зелёные
- [ ] лог в issue (### YYYY-MM-DD)
- [ ] нет ПДн в логах, нет реальных данных, нет секретов
- [ ] общие файлы (CLAUDE.md, docker-compose, pyproject) — отдельный мелкий PR с пингом

---

Guardrails (проверяются в каждом PR)

1. В LLM — только scrub()-текст. Прямой вызов клиента GigaChat в обход app/llm/gateway.py запрещён.
2. Safety до LLM. При acute LLM не вызывается вообще.
3. Алерты и скоринг детерминированы — LLM не решает (ADR-007).
4. Время — только из app.core.clock (ADR-005).
5. identity ↔ clinical — только через токен. Модули clinical не импортируют app.db.identity.
6. Доступ врача → audit_log.
7. Пороги, тексты и лексикон — в config/, не в коде.
8. Только синтетика. Логи без ПДн и без сырого текста.
9. Никаких зарубежных API в контуре.

Факапы

Ситуация	Действие
Начал в основной копии	git stash → worktree → git stash pop
git push дал [new branch] после мержа	удалить ветку через API, новый issue + cherry-pick
Конфликт при rebase в чужой зоне	спросить владельца
Утёк секрет	отозвать ключ, вычистить историю
Битая кириллица в issue/PR	см. GITEA_API.md: только --data-binary @файл