revdeck 0.0.0-stage → 0.2.0

package/docs/ru/architecture.md

@@ -0,0 +1,92 @@
+# Архитектура
+
+[English](../architecture.md) | Русский
+
+## Цели
+
+1. Агент получает контекст ревью и правила проекта детерминированно, без ручных файлов и без доступа
+   к токенам платформ.
+2. Публикация в GitLab/GitHub происходит только после подтверждения человеком и идемпотентна.
+3. Один инструмент работает в любом харнессе: MCP для агентских клиентов, CLI как универсальный
+   слой, веб-интерфейс для человека.
+4. Правила проекта конфигурируются, а не зашиты в промпт.
+
+## Не цели
+
+- Замена нативного diff-вьюера GitLab/GitHub. UI оптимизирован под триаж и подтверждение.
+- Собственный статический анализ. Проверки делегируются линту, типам и тестам проекта.
+- Многопользовательский сервер. Модель — один пользователь, несколько ревью, демон на хосте.
+
+## Компоненты
+
+```text
+agent (MCP/CLI) ──▶ revdeck daemon ──glab/gh──▶ GitLab/GitHub
+                         │
+                   SQLite + UI ◀── human
+```
+
+- `src/core` — чистые функции и модели: парсер unified diff, правила, fingerprints замечаний,
+  санитайзер публикации, редакция секретов, безопасный запуск процессов.
+- `src/providers` — единственное место, знающее о платформах. `Provider` нормализует MR/PR, diff,
+  треды, ответы, резолв и создание комментариев.
+- `src/daemon/service.ts` — оркестратор: обновление ревью, черновики, решения, план публикации,
+  approval, идемпотентная запись, фоновый sync.
+- `src/daemon/store.ts` — SQLite (`node:sqlite`): ревью, снимок diff/тредов, черновики, замечания,
+  решения, комментарии, approvals, аудит.
+- `src/daemon/rpc.ts` — JSON-RPC поверх unix-сокета (0600) для CLI и MCP.
+- `src/daemon/http.ts` — UI и `/api/*`, SSE-события, cookie-сессия с одноразовым токеном.
+- `src/cli` — команды, `init`, `doctor`, экспорт/импорт старого файлового формата.
+- `src/mcp` — MCP-сервер: инструменты и промпты, тонкая обёртка над RPC.
+- `ui` — Svelte 5 SPA, собирается в `dist/ui`.
+
+## Поток данных
+
+1. `revdeck open 42` → RPC `reviews.open` с `root` рабочей копии.
+2. Демон определяет платформу/хост/проект (аргументы → конфиг → git remote), создаёт провайдер,
+   читает MR, diff и треды, сохраняет снимок и синтетические черновики.
+3. Агент запрашивает `revdeck_context`: демон собирает эффективные правила (документы и секции для
+   изменённых путей), сниппеты, треды и замечания.
+4. Агент пишет черновики (`drafts.put`, `findings.put`, `summary.put`, `notes.update`).
+5. Человек в UI вызывает `publish.preview` → видит точный план и хеш → `publish.approve` →
+   `publish.commit`. Демон выполняет только пункты, вошедшие в подтверждённый план.
+6. Фоновый sync раз в 2 минуты обновляет открытые ревью и рассылает SSE-события UI.
+
+## Модель данных
+
+- `ReviewRef` — платформа, хост, проект, номер. `reviewId` — `platform:host/project!number`.
+- `DiffFile`/`Hunk`/`DiffLine` — номера строк по старой и новой версии; `line` замечания всегда по
+  новому файлу.
+- `Thread`/`Note` — общая модель обсуждений.
+- `Finding` — замечание с `id`, `fingerprint`, уровнем, файлом/строкой, текстом и статусом
+  (`draft`, `accepted`, `rejected`, `published`, `fixed`, `stale`).
+- `Approval` — одноразовый id, привязанный к `hash = sha256(canonicalJson({reviewId, kind, items}))`,
+  TTL 10 минут.
+
+## Идемпотентность и конкурентность
+
+- Записи черновиков и замечаний идут через один процесс; SQLite в WAL.
+- Публикация помечает approval использованным до выполнения. Пункты, которые уже ушли (совпадающий
+  `posted`, `published`), пропускаются. Ошибка одного пункта не отменяет остальные и записывается в
+  черновик/замечание.
+- Хеш плана защищает от правки агентом между показом человеку и публикацией: изменился текст → хеш
+  не совпал → approve отклонён.
+- `findings.put` — замена набора с сохранением `id` и решения; исчезнувшие замечания помечаются
+  `stale`, а не удаляются.
+
+## Расширение
+
+- **Новая платформа**: реализовать `Provider` и добавить ветку в `createProvider`; всё остальное не
+  меняется.
+- **Новый харнесс**: `revdeck init --adapters <имя>` пишет MCP-конфиг или файл команды и ссылается на
+  канонический skill `.agents/skills/revdeck`. Для
+  харнессов без MCP используется CLI.
+- **Правила**: `rules.map`/`rules.sources` в `.revdeck.yml`; паки правил можно распространять как
+  обычный файл конфигурации.
+- **Проверки**: `checks` с argv без shell; запуск только по явному подтверждению.
+
+## Производительность
+
+- Diff парсится на сервере, UI получает файлы списком и hunks по одному файлу.
+- Состояние ревью не содержит полный diff; SSE сообщает об изменениях, UI перезапрашивает состояние.
+- Сниппеты для тредов и замечаний считаются на сервере и ограничены по размеру.
+- Контекст правил ограничен 320 КБ; MCP-контекст — параметром `max_bytes`.

package/docs/ru/configuration.md

@@ -0,0 +1,121 @@
+# Конфигурация
+
+[English](../configuration.md) | Русский
+
+Файл `.revdeck.yml` (или `.revdeck.yaml`) в корне репозитория. Схема проверяется через zod;
+неизвестное поле — ошибка с путём.
+
+```yaml
+version: 1
+provider:
+  type: auto            # auto | gitlab | github
+  host: gitlab.example.com
+  project: group/project
+  base: develop
+output:
+  language: auto        # auto | ru | en — язык замечаний и ответов
+rules:
+  sources: [AGENTS.md]
+  map:
+    - match: ["src/**", "lib/**"]
+      docs: ["docs/Architecture.md", "docs/Styleguide.md#Базовый стиль"]
+      note: "прикладной код"
+  ignore: ["**/generated/**"]
+checks:
+  - id: lint
+    name: ESLint
+    argv: [npm, run, lint]
+    when: ["src/**"]
+    consent: true
+    timeoutMs: 300000
+publish:
+  requireApproval: true
+  maxComments: 50
+```
+
+## provider
+
+| Поле | По умолчанию | Смысл |
+|---|---|---|
+| `type` | `auto` | `auto` — по git remote; иначе явная платформа |
+| `host` | из remote | хост без схемы |
+| `project` | из remote | GitLab `group/project`, GitHub `owner/repo` |
+| `base` | `develop`/`main` | база для локального diff |
+
+Явные аргументы CLI (`--platform`, `--project`, `--host`) важнее конфига, конфиг важнее git remote.
+Так подмена `.git/config` не перенаправит ревью на чужой проект.
+
+## output
+
+- `language: auto` — замечания и ответы пишутся на языке описания MR и обсуждений; если текста нет,
+  используется английский. `ru`/`en` фиксируют язык явно.
+- Язык правил и документов от этого не зависит: агент читает их как есть и цитирует в оригинале.
+- Это язык **результата ревью**, а не интерфейса CLI/UI. Интерфейс переключается `--lang ru|en`,
+  `REVDECK_LANG` или переключателем в UI.
+- `revdeck init --lang en` выбирает английский skill и пишет `REVDECK_LANG` в MCP-конфиг.
+
+## rules
+
+- `sources` — документы по умолчанию, если ни одна строка `map` не подошла. Пусто — автообнаружение
+  (`AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `docs/ARCHITECTURE.md`, `docs/Architecture.md`,
+  `docs/STYLEGUIDE.md`, `docs/Styleguide.md`, `docs/CONTRIBUTING.md`).
+- `map` — список правил: `match` (glob или массив glob) и `docs` (массив селекторов). Несколько
+  совпавших строк объединяются.
+- `ignore` — glob-исключения: файл не попадает в анализ правил.
+
+### Селекторы документов
+
+| Селектор | Что берётся |
+|---|---|
+| `docs/Architecture.md` | весь документ |
+| `docs/Styleguide.md#Базовый стиль` | секция заголовка (уровень и ниже, до заголовка того же уровня) |
+| `docs/File.md#L10-L25` | диапазон строк |
+| `docs/File.md#10-25` | то же |
+
+Заголовок нормализуется: регистр, пробелы и пунктуация не важны, `#Слои и зависимости` и
+`#layers` — разные секции, а `#Слои-и-зависимости` и `#Слои и зависимости` — одна. Если секция не
+найдена, revdeck пишет предупреждение и не подставляет весь документ.
+
+### Glob
+
+`*` — в пределах одного сегмента, `**` — любая глубина, `?` — один символ, `{a,b}` — альтернатива.
+Примеры: `src/**/*.ts`, `docs/{guides,adr}/**`, `**/*.test.ts`.
+
+## checks
+
+Проверки — argv-массивы, без shell-строк. Это важно: конфиг лежит в репозитории, и строка shell
+позволила бы исполнить произвольный код при ревью.
+
+| Поле | Смысл |
+|---|---|
+| `id` | стабильный идентификатор |
+| `name` | отображаемое имя |
+| `argv` | команда и аргументы; первым идёт исполняемый файл |
+| `when` | glob-пути: запускать, только если diff их затронул; пусто — всегда |
+| `consent` | требует явного подтверждения (по умолчанию `true`) |
+| `timeoutMs` | таймаут (по умолчанию 300 000) |
+
+Запуск: `revdeck checks <N> --run --yes`. MCP-инструмент только показывает план.
+
+## publish
+
+- `requireApproval` — оставлен для совместимости; approval требуется всегда, когда публикует не
+  интерактивный процесс.
+- `maxComments` — максимум комментариев за один план (1–200).
+
+## Переменные окружения
+
+| Переменная | Смысл |
+|---|---|
+| `REVDECK_STATE_DIR` | каталог состояния (по умолчанию `~/.local/state/revdeck`) |
+| `REVDECK_RUNTIME_DIR` | каталог сокета (по умолчанию `$XDG_RUNTIME_DIR/revdeck`) |
+| `REVDECK_URL` + `REVDECK_TOKEN` | подключение к демону по HTTP (контейнер/проброс порта) |
+| `REVDECK_DEV_CONTAINER=1` | не запускать локальный демон, а подсказать про демон хоста |
+| `REVDECK_UI_HOST` | хост для `revdeck ui` из контейнера (например, `host.docker.internal`) |
+| `REVDECK_ROOT` | корень проекта для MCP-сервера |
+| `REVDECK_LANG` | язык CLI/MCP/демона: `ru` или `en` (по умолчанию системная локаль) |
+
+## Валидация
+
+`revdeck config --json` показывает эффективный конфиг, найденный путь и предупреждения.
+`revdeck rules --explain src/app.ts` показывает, какие документы и секции выбраны для файла.

package/docs/ru/integrations.md

@@ -0,0 +1,122 @@
+# Интеграция с харнессами
+
+[English](../integrations.md) | Русский
+
+У revdeck два переносимых слоя и один адаптерный:
+
+- **MCP** (stdio) — инструменты `revdeck_*` работают в любом клиенте с MCP.
+- **CLI** — те же возможности без MCP: `revdeck open/context/findings/reply/publish`.
+- **`/`-команда** — у каждого харнесса своя; `revdeck init` создаёт нужный файл.
+
+Полноценная интеграция = MCP + skill (процедуры) + команда (точка входа). Без MCP остаются CLI и
+skill: агент вызывает команды через shell.
+
+## Матрица
+
+| Харнесс | `/`-команда | Что пишет `init` |
+|---|---|---|
+| Claude Code | `/revdeck` | `.claude/commands/revdeck.md`, `.claude/skills/revdeck` → `../../.agents/skills/revdeck`, `.mcp.json` |
+| Cursor | `/revdeck` | `.cursor/commands/revdeck.md`, `.cursor/mcp.json` |
+| Codex CLI | prompt `revdeck` | `.codex/prompts/revdeck.md`; MCP — в `~/.codex/config.toml` (вручную) |
+| Gemini CLI | `/revdeck` | `.gemini/commands/revdeck.toml`; MCP — в настройках Gemini (вручную) |
+| OpenCode | `/revdeck` | `.opencode/command/revdeck.md` |
+| GitHub Copilot | prompt-файл | `.github/prompts/revdeck.prompt.md` |
+| DSH | плагин (см. ниже) | `.agents/skills/revdeck/*` (включая `agents/openai.yaml`) + YAML-сниппет в выводе |
+| Универсальный | — | `.agents/skills/revdeck/*` (включая `agents/openai.yaml`) + MCP |
+
+`revdeck init --adapters dsh,claude` включает нужные явно. Повторный `init` не перезаписывает
+существующие командные файлы и не затирает чужие ключи `.mcp.json`.
+
+Скилл хранится в одном каноническом месте: `.agents/skills/revdeck` (включая `agents/openai.yaml`
+для OpenAI-харнессов). Харнессы со своим каталогом скиллов получают ссылку на него:
+`.claude/skills/revdeck` — симлинк на `../../.agents/skills/revdeck`; на Windows и ФС без симлинков
+используется копия. Старые копии, созданные предыдущим `init`, заменяются, если в них остался
+`name: revdeck`.
+
+Вложения комментариев загружает демон на хосте. GitLab использует project uploads и возвращает
+абсолютный URL; у GitHub публичного API загрузки нет, поэтому редактор просит вставить ссылку.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "revdeck": {
+      "command": "npx",
+      "args": ["-y", "revdeck", "mcp"],
+      "env": { "REVDECK_LANG": "en" }
+    }
+  }
+}
+```
+
+`init` пишет `npx -y revdeck mcp` в MCP-конфиг. Публикация через MCP
+требует `approval_id`: его выдаёт человек в UI или CLI с `--yes`, агент получить не может.
+
+## DSH
+
+MCP-клиент DSH подключается в профиле Cordis:
+
+```yaml
+- id: mcp-revdeck
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: revdeck
+    transport: stdio
+    command: npx
+    args: ['-y', 'revdeck', 'mcp']
+    env:
+      REVDECK_LANG: en
+```
+
+Инструменты появятся как `mcp__revdeck__*`. MCP prompt templates DSH не поддерживает, поэтому
+`/revdeck` требует host-команды (`ctx.commands.register`) или client action — это отдельный
+плагин-обёртка. До него используйте skill + MCP-инструменты: `/`-слэш не обязателен для работы.
+
+## Контейнер и devcontainer
+
+Демон, `glab` и `gh` остаются на хосте; контейнеру нужен только CLI или MCP-сервер revdeck.
+Настройки devcontainer генерируются из корня репозитория:
+
+```bash
+revdeck devcontainer          # показать mounts и окружение
+revdeck devcontainer --write  # добавить их в .devcontainer/devcontainer.json
+```
+
+`--write` монтирует runtime- и state-каталоги хоста по фиксированным путям и выставляет:
+
+```json
+{
+  "REVDECK_RUNTIME_DIR": "/run/revdeck",
+  "REVDECK_STATE_DIR": "/var/lib/revdeck",
+  "REVDECK_DEV_CONTAINER": "1",
+  "REVDECK_UI_HOST": "host.docker.internal"
+}
+```
+
+Runtime-каталог монтируется на запись (там сокет), state-каталог — только на чтение (клиент читает
+`daemon.json` с токеном). Чужие mounts, переменные окружения и `runArgs` сохраняются; revdeck
+управляет только двумя своими mounts и ключами `REVDECK_*`.
+
+После пересборки контейнера запустите демон на хосте (`revdeck daemon start`). В контейнере revdeck
+никогда не запускает свой демон: если сокет недоступен, команда падает с ошибкой `DEVCONTAINER` и
+подсказкой. `revdeck doctor` не ищет `glab`/`gh` в контейнере.
+
+Пользователь контейнера должен иметь доступ к сокету хоста (обычно совпадает UID; сокет 0600). Чтобы
+открыть UI из контейнера, запустите демон на хосте с `revdeck daemon start --host 0.0.0.0` и
+используйте `host.docker.internal`; иначе открывайте UI на хосте.
+
+Запасные варианты:
+
+1. `REVDECK_URL=http://host.docker.internal:<port>` и `REVDECK_TOKEN=<token>` — HTTP-транспорт,
+   демон на хосте запущен с `--host 0.0.0.0`.
+2. `revdeck export <N>` на хосте и `revdeck import <N>` в контейнере — файловый мост.
+
+## Проверка
+
+```bash
+revdeck doctor
+```
+
+Показывает найденные бинарники, авторизацию `glab`/`gh`, состояние демона и установленный адаптер. В
+devcontainer проверяет демон хоста, а не ищет `glab`/`gh` внутри.

package/docs/ru/protocol.md

@@ -0,0 +1,102 @@
+# Протокол
+
+[English](../protocol.md) | Русский
+
+## Транспорты
+
+1. **Unix-сокет** (основной): `$XDG_RUNTIME_DIR/revdeck/daemon.sock`, каталог 0700, сокет 0600.
+   Строки JSON, по одному запросу/ответу на строку.
+2. **HTTP**: `POST /api/rpc` на loopback с cookie-сессией. Нужен для контейнеров, куда сокет не
+   проброшен (`REVDECK_URL` + `REVDECK_TOKEN`).
+3. **UI HTTP**: `/api/*` и SSE `/api/events` для браузера.
+
+## Сообщения
+
+Запрос:
+
+```json
+{"id": 1, "method": "reviews.get", "params": {"review": "gitlab:gitlab.com/group/project!42"}}
+```
+
+Ответ:
+
+```json
+{"id": 1, "result": {"review": {"id": "...", "info": {}, "threads": []}}}
+```
+
+Ошибка:
+
+```json
+{"id": 1, "error": {"message": "...", "code": "APPROVAL", "hint": "..."}}
+```
+
+`id` — число. Соединение считается недоверенным до первого успешного запроса: авторизация — права
+файла сокета.
+
+## Методы
+
+| Метод | Параметры | Результат |
+|---|---|---|
+| `ping` | — | версия, протокол, pid |
+| `reviews.list` | — | сохранённые ревью |
+| `reviews.remoteList` | `root`, `scope`, `limit` | открытые ревью с платформы |
+| `reviews.open` | `root`, `input`/`platform`/`project`/`host`/`branch` | снимок ревью |
+| `reviews.refresh` | `review` | обновлённый снимок |
+| `reviews.get` | `review`, `refresh?` | снимок (без полного diff) |
+| `diff.get` | `review`, `file` | hunks файла |
+| `drafts.put` | `review`, `threadId`, `patch` | черновик |
+| `findings.put` | `review`, `findings[]` | замечания после merge |
+| `findings.list` | `review` | замечания |
+| `summary.put` | `review`, `summary` | выжимка |
+| `decisions.put` | `review`, `decisions` | решения человека |
+| `notes.add` | `review`, `file`, `line`, `text`, `toAgent` | комментарий к строке |
+| `notes.update` | `review`, `noteId`, `patch` | обновлённый комментарий |
+| `reactions.list` | `review`, `noteIds[]` | реакции, сгруппированные по id комментария |
+| `reactions.toggle` | `review`, `noteId`, `emoji` | `active` и актуальный список реакций |
+| `attachments.upload` | `review`, `name`, `contentType`, `data` (base64) | `name`, абсолютный `url`, `markdown` |
+| `notes.delete` | `review`, `noteId` | `{ok}` |
+| `publish.preview` | `review`, `kind`, `ids[]` | план + предупреждения |
+| `publish.approve` | `review`, `kind`, `ids[]`, `hash` | `approvalId`, `expiresAt` |
+| `publish.commit` | `review`, `approvalId` | результаты по пунктам |
+| `rules.get` | `review` | markdown правил, проверки, предупреждения |
+| `checks.run` | `review`, `allowRun`, `ids[]` | результаты проверок |
+| `audit.tail` | `limit` | последние действия |
+
+## Approval
+
+1. `publish.preview` строит `items` — точные тела, пути, строки, флаги резолва — и
+   `hash = sha256(canonicalJson({reviewId, kind, items}))`.
+2. Человек видит план. `publish.approve` пересчитывает план по тем же `ids`; если хеш не совпал,
+   возвращает ошибку. Иначе создаёт одноразовый `approval_id` с TTL 10 минут.
+3. `publish.commit` проверяет, что approval не использован и не истёк, помечает его использованным и
+   выполняет только `items`. Уже отправленные пункты пропускаются.
+
+Агент не может вызвать `publish.approve`: MCP-инструмент его не предоставляет. Человек подтверждает
+в UI или CLI с `--yes`.
+
+## HTTP API (UI)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/` | SPA; `?t=<token>` ставит cookie и редиректит |
+| GET | `/assets/*` | статика сборки |
+| GET | `/api/health` | живость |
+| GET | `/api/reviews` | список ревью |
+| GET | `/api/state?review=` | снимок для UI |
+| GET | `/api/diff?review=&file=` | hunks файла |
+| GET | `/api/rules?review=` | правила |
+| GET | `/api/events` | SSE: `review` |
+| POST | `/api/reviews/open`, `/api/reviews/refresh` | открыть/обновить |
+| POST | `/api/drafts`, `/api/findings`, `/api/summary`, `/api/decisions` | черновики |
+| POST | `/api/notes` | `action: add/update/delete` |
+| GET | `/api/reactions?review=&notes=` | реакции для id комментариев |
+| POST | `/api/reactions` | переключить реакцию |
+| POST | `/api/attachments` | загрузить картинку/видео и вернуть абсолютную ссылку |
+| POST | `/api/publish/preview`, `/approve`, `/commit` | публикация |
+| POST | `/api/checks` | проверки |
+| POST | `/api/rpc` | RPC-прокси для HTTP-транспорта |
+
+## Версионирование
+
+`PROTOCOL_VERSION` в `src/version.ts` сверяется при рукопожатии; клиент и демон одной версии пакета.
+Несовпадение методов возвращает `METHOD` с подсказкой обновить revdeck.

package/docs/ru/threat-model.md

@@ -0,0 +1,52 @@
+# Модель угроз
+
+[English](../threat-model.md) | Русский
+
+## Активы
+
+1. Токены GitLab/GitHub (в конфигурации `glab`/`gh` на хосте).
+2. Код и diff ревьюируемого репозитория, включая приватный.
+3. Треды и комментарии, включая персональные данные.
+4. Право публикации от имени пользователя.
+5. Токен запуска UI и токен сессии браузера.
+6. Локальная база SQLite с текстами комментариев и черновиков.
+
+## Доверенные границы
+
+1. **Агент (песочница/контейнер) ↔ демон на хосте.** Агент недоверенный: его вывод может быть
+   подменён содержимым MR.
+2. **Браузер ↔ демон.** Браузер доверенный, но на loopback может прийти чужая страница.
+3. **Репозиторий ↔ демон.** Конфиг и документы репозитория контролирует автор MR; они не должны
+   исполняться.
+4. **Демон ↔ `glab`/`gh`.** CLI — доверенный, но его окружение и рабочая копия могут быть подменены.
+
+## Угрозы и меры
+
+| Угроза | Мера | Остаточный риск |
+|---|---|---|
+| Агент вытягивает токен платформы | Токен не читается: `glab`/`gh` берут его из своей конфигурации. Агенту доступен только RPC; токены вычищаются из env дочерних процессов, редактируются в логах/ошибках | Процесс с чтением `$HOME` пользователя может прочитать конфиг CLI. Поэтому нужна изоляция агента |
+| Подмена проекта/хоста через `.git/config` | Явные `host`/`project` в конфиге и аргументах важнее remote; `glab`/`gh` вызываются с `cwd` вне рабочей копии | Если проект не закреплён, remote используется — UI показывает проект для сверки |
+| Prompt injection из комментариев/diff | Инструкции в тексте помечены как данные; агент не публикует сам; публикация требует approval человека; санитайзер блокирует скрытые символы и быстрые команды | Модель всё равно может предложить вредный текст — его увидит человек в плане |
+| Случайная публикация не того текста | План с точными телами и хешем; `approve` сверяет хеш; `commit` выполняет только пункты плана; повторная отправка пропускается | Человек может подтвердить не глядя — UI показывает полный текст |
+| Межсайтовые запросы к loopback (DNS rebinding, CSRF) | Только `127.0.0.1`/`localhost` в `Host`; проверка `Origin` для POST; cookie `HttpOnly`, `SameSite=Strict`; одноразовый токен в ссылке запуска; CSP | Локальный процесс другого пользователя с доступом к сокету — вне модели (права 0600/0700) |
+| Символическая ссылка/TOCTOU в рабочем каталоге | Состояние хранится в приватном каталоге, запись атомарная; чтение файлов репозитория только внутри корня, без следования ссылкам в служебных путях | Гонка на файлах репозитория возможна, но не даёт прав публикации |
+| Вредоносный `.revdeck.yml` исполняет код | `checks.argv` — массив без shell; запуск только по `--run --yes`; MCP не умеет запускать | Пользователь может подтвердить запуск вредоносной команды из чужого MR — читайте план |
+| Утечка через логи/ошибки | Редакция токенов, ANSI, управляющих символов; ограничение длины; логи в приватном каталоге | Текст комментариев может содержать секреты — не публикуйте их |
+| Supply chain | Минимум зависимостей, lock-файл, сборка esbuild/Vite, provenance при публикации npm | Как у любого npm-пакета |
+| Кража approval | Approval — случайные 16 байт, TTL 10 минут, одноразовый, привязан к review+hash, хранится только в SQLite на хосте | Доступ к сокету = доступ к RPC; защищён правами файла |
+
+## Что не является целью
+
+- Защита от администратора/пользователя, который уже имеет доступ к процессам хоста.
+- Скрытие кода ревью от платформы: он и так там.
+- Многопользовательская авторизация и роли.
+- Защита от вредоносного `glab`/`gh`: CLI считается доверенным, как и npm-пакет.
+
+## Проверки модели
+
+- Комментарии проходят `sanitizeBody`: управляющие и bidi-символы, HTML, быстрые команды GitLab,
+  `@all`/`@here`/`@everyone`, внешние картинки. Картинки разрешены только с хоста платформы
+  (или из GitLab `/uploads/`); вложения ограничены растровыми картинками и видео и проверяются по
+  расширению, MIME и сигнатуре файла.
+- Публикация невозможна без `approval_id`; MCP-инструмент публикации его не создаёт.
+- `revdeck doctor` показывает, какие права и адаптеры активны.

package/docs/threat-model.md

@@ -0,0 +1,53 @@
+# Threat model
+
+[English](threat-model.md) | [Русский](ru/threat-model.md)
+
+## Assets
+
+1. GitLab/GitHub tokens (in the `glab`/`gh` configuration on the host).
+2. The code and diff of the repository under review, including private repositories.
+3. Threads and comments, including personal data.
+4. The right to publish on the user's behalf.
+5. The UI launch token and the browser session token.
+6. The local SQLite database with the text of comments and drafts.
+
+## Trust boundaries
+
+1. **Agent (sandbox/container) ↔ daemon on the host.** The agent is untrusted: its output can be
+   subverted by MR content.
+2. **Browser ↔ daemon.** The browser is trusted, but a foreign page can reach loopback.
+3. **Repository ↔ daemon.** The MR author controls the repository's config and documents; they must
+   not be executed.
+4. **Daemon ↔ `glab`/`gh`.** The CLI is trusted, but its environment and working copy can be tampered
+   with.
+
+## Threats and mitigations
+
+| Threat | Mitigation | Residual risk |
+|---|---|---|
+| The agent extracts a platform token | The token is never read: `glab`/`gh` take it from their own configuration. The agent gets only RPC; tokens are scrubbed from child process env and redacted in logs/errors | A process that can read the user's `$HOME` can read the CLI config. That is why agent isolation is required |
+| Spoofing the project/host via `.git/config` | Explicit `host`/`project` in the config and arguments take precedence over the remote; `glab`/`gh` are invoked with a `cwd` outside the working copy | If the project is not pinned, the remote is used — the UI shows the project for verification |
+| Prompt injection from comments/diff | Instructions in the text are marked as data; the agent does not publish on its own; publishing requires human approval; the sanitizer blocks hidden characters and quick actions | The model can still propose harmful text — a human sees it in the plan |
+| Accidental publication of the wrong text | A plan with the exact bodies and a hash; `approve` verifies the hash; `commit` executes only the plan items; a repeat send is skipped | A human may approve without looking — the UI shows the full text |
+| Cross-site requests to loopback (DNS rebinding, CSRF) | Only `127.0.0.1`/`localhost` in `Host`; an `Origin` check for POST; `HttpOnly`, `SameSite=Strict` cookies; a one-time token in the launch link; CSP | A local process of another user with access to the socket is out of scope (permissions 0600/0700) |
+| Symlink/TOCTOU in the working directory | State is stored in a private directory, writes are atomic; repository files are read only inside the root, without following symlinks in its own paths | A race on repository files is possible but does not grant publish rights |
+| A malicious `.revdeck.yml` executes code | `checks.argv` is an array without a shell; execution only with `--run --yes`; MCP cannot run checks | A user may approve running a malicious command from someone else's MR — read the plan |
+| Leakage through logs/errors | Redaction of tokens, ANSI and control characters; length limits; logs in a private directory | Comment text may contain secrets — do not publish it |
+| Supply chain | Minimal dependencies, lockfile, esbuild/Vite build, provenance on npm publish | The same as for any npm package |
+| Approval theft | An approval is 16 random bytes, TTL 10 minutes, single-use, bound to review+hash, stored only in SQLite on the host | Socket access = RPC access; protected by file permissions |
+
+## Out of scope
+
+- Protection from an administrator/user who already has access to host processes.
+- Hiding the code under review from the platform: it is already there.
+- Multi-user authorization and roles.
+- Protection from a malicious `glab`/`gh`: the CLI is trusted, just like the npm package.
+
+## Model checks
+
+- Comments go through `sanitizeBody`: control and bidi characters, HTML, GitLab quick actions,
+  `@all`/`@here`/`@everyone`, external images. Images are allowed only from the platform host
+  (or GitLab project `/uploads/`); attachments are restricted to raster images and videos and are
+  checked by extension, MIME and file signature.
+- Publishing is impossible without an `approval_id`; the MCP publish tool does not create one.
+- `revdeck doctor` shows which permissions and adapters are active.

package/examples/monorepo.yml

@@ -0,0 +1,38 @@
+# Монорепозиторий: разные документы для разных пакетов.
+version: 1
+provider:
+  type: gitlab
+  host: gitlab.example.com
+  project: group/web-chat-core
+  base: develop
+rules:
+  sources:
+    - AGENTS.md
+  map:
+    - match: "**/package.json"
+      docs: [AGENTS.md, "docs/guides/Styleguide.md#Зависимости"]
+    - match: ["apps/*/src/**", "packages/*/src/**"]
+      docs:
+        - AGENTS.md
+        - docs/guides/Styleguide.md
+    - match: "apps/*/src/state/**"
+      docs: [docs/guides/StateManagement.md]
+    - match: "apps/*/docs/**"
+      docs:
+        - apps/*/docs/Architecture.md
+        - docs/guides/Styleguide.md#Документация
+    - match: ["packages/ui-kit/**", "packages/toolkit/**"]
+      docs: [packages/ui-kit/README.md, docs/guides/Styleguide.md]
+    - match: "docs/adr/**"
+      docs: [AGENTS.md#Размещение-технических-знаний, docs/adr/README.md]
+    - match: [".claude/**", ".codex/**", ".cursor/**", ".agents/**"]
+      docs: [AGENTS.md#Источники-и-приоритет-инструкций]
+checks:
+  - id: lint
+    argv: [npm, run, lint]
+    when: ["**/src/**"]
+  - id: types
+    argv: [npm, run, typecheck]
+    when: ["**/*.ts", "**/*.tsx"]
+publish:
+  maxComments: 40

package/examples/simple.yml

@@ -0,0 +1,36 @@
+# Простой проект: правила лежат рядом с кодом.
+# Скопируйте в корень репозитория как .revdeck.yml.
+version: 1
+provider:
+  type: auto
+  # Явно закрепите проект, если remote может быть подменён:
+  # host: gitlab.example.com
+  # project: group/project
+  base: main
+rules:
+  sources:
+    - AGENTS.md
+    - CONTRIBUTING.md
+  map:
+    - match: "src/**"
+      docs:
+        - AGENTS.md
+        - docs/Architecture.md
+    - match: "docs/**"
+      docs:
+        - AGENTS.md
+  ignore:
+    - "**/node_modules/**"
+    - "**/dist/**"
+checks:
+  - id: lint
+    name: lint
+    argv: [npm, run, lint]
+    when: ["src/**", "*.json", "*.ts"]
+  - id: test
+    name: tests
+    argv: [npm, test]
+    when: ["src/**"]
+publish:
+  requireApproval: true
+  maxComments: 50