kodu 2.1.2 → 2.2.0

package/skills/audit-concurrency/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: audit-concurrency
+description: >
+  Аудит управления состоянием и конкурентности: race conditions, deadlocks, shared mutable state,
+  неатомарные операции. Запускай при /audit-concurrency.
+---
+
+## Правило применимости (Relevance Rule)
+
+Применим к коду с параллельными операциями, shared state, кэшированием, транзакциями БД, очередями, WebSocket. Для однопоточных скриптов без параллелизма — верни пустой ответ.
+
+## Runtime Detection & Stack Profile
+
+Этот аудит стек-агностичен: проверки сформулированы нейтрально, а конкретика
+(инструменты, идиомы, анти-паттерны, примеры) берётся из профиля стека.
+
+1. **Профиль передан контекстом?** Если оркестратор `/audit` передал
+   `runtime=<id>` и/или содержимое профиля — используй его, шаги 2–3 пропусти.
+
+2. **Иначе определи РОВНО ОДИН рантайм** этого каталога:
+   ```bash
+   if   [ -f package.json ]; then echo "runtime=node"
+   elif [ -f go.mod ]; then echo "runtime=go"
+   elif [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then echo "runtime=python"
+   elif [ -f Cargo.toml ]; then echo "runtime=rust"
+   elif [ -f pom.xml ] || ls build.gradle* settings.gradle* >/dev/null 2>&1; then echo "runtime=java"
+   else echo "runtime=generic"; fi
+   ```
+   Один запуск = один рантайм; не миксуй backend и frontend. Если найдено
+   несколько маркеров (монорепо) — выбери соответствующий текущему scope/анализируемым
+   файлам и зафиксируй выбор в разделе Audit Coverage.
+
+3. **Загрузи профиль** через Read: `./skills/audit/stacks/<runtime>.md`
+   (fallback `./skills/audit/stacks/_generic.md`, если файл не найден).
+
+Дальше используй профиль:
+- **Инструменты** — из секции «Tooling by category» профиля (раздел
+  «Инструментальная поддержка» ниже ссылается на категории, а не на команды).
+- **Ожидания PASS** — из «Idioms»; **формулировки FAIL** — из «Anti-patterns».
+- **Точечные подсказки** — из «Check-ID hints» по префиксу `CON-`.
+- Если профиль `tier: general` или `runtime=generic` → стек-специфичные находки
+  без однозначного evidence помечай `🔍 UNVERIFIED`, а не `❌ FAIL`. Проверки,
+  чей механизм в рантайме отсутствует, помечай `N/A`.
+
+## Severity Guide
+
+| Severity | Критерий назначения |
+|----------|---------------------|
+| 🔴 Critical | RCE, auth bypass, data corruption, необратимый финансовый риск |
+| 🟠 High | Падение production, privilege escalation, утечка данных |
+| 🟡 Medium | Деградация производительности или поддерживаемости без immediate outage |
+| 🟢 Low | Стиль, читаемость, слабое нарушение конвенции |
+
+Правило: severity = impact × exploitability × blast radius. Одинаковый паттерн → одинаковый severity между аудитами.
+
+## Чеклист
+
+| Check ID | Проверка |
+|----------|----------|
+| CON-01 | Параллельные операции запускаются и синхронизируются корректно; результаты дожидаются, фоновые задачи не утекают |
+| CON-02 | Read-modify-write операции выполняются в транзакциях [⚡ dynamic] |
+| CON-03 | Разделяемое изменяемое состояние защищено синхронизацией (синглтоны, кэши, переменные уровня модуля) |
+| CON-04 | Module-level кэш имеет механизм инвалидации |
+| CON-05 | Обработчики событий и webhook-handlers идемпотентны [⚡ dynamic] |
+| CON-06 | Фоновые операции имеют механизм отмены и не блокируют graceful shutdown |
+
+## Правила верификации
+
+1. **Только чеклист**: оценивай ТОЛЬКО проверки выше. Не добавляй новые.
+2. **Явная верификация = PASS**: ставь `✅ PASS` только если явно проверил механизм (нашёл схему, конфиг, guard) и подтвердил отсутствие нарушения — укажи что именно проверено.
+3. **Нет доказательства = UNVERIFIED**: не можешь указать `файл:строка` ни для нарушения, ни для подтверждения — ставь `🔍 UNVERIFIED`.
+   - Проверки с `[⚡ dynamic]` нельзя статически подтвердить — только `🔍 UNVERIFIED` или `❌ FAIL` (при явном evidence), но не `✅ PASS`
+4. **Baseline приоритетен**: check_id есть в `docs/audit-baseline.yml` → `⏸ ACCEPTED`.
+5. **Только 🔴/🟠 FAIL требуют решения**: 🟡/🟢 — решение необязательно.
+
+## Evidence Quality Rules
+
+Любой `❌ FAIL` обязан содержать:
+- Точный `file:line`
+- Минимальный код-фрагмент (1–3 строки)
+- Causal chain: почему именно это нарушение → какой риск возникает
+
+Запрещено:
+- Предполагать runtime behavior без evidence в коде
+- Предполагать prod-конфигурацию по dev-конфигу
+- Предполагать отсутствие middleware без проверки всей router chain
+- Если вывод основан на предположении — только `🔍 UNVERIFIED`
+
+## Language Rule
+
+Результаты аудита должны быть написаны простым и понятным языком. Избегай сложных терминов, жаргона и абстрактных понятий без необходимости. Общепринятые технические термины (Docker, HTTP, API, JSON, URL) допустимы. Описывай проблемы так, чтобы они были понятны разработчику любого уровня, а не только узкому специалисту в данной области.
+
+## Baseline
+
+До анализа:
+```bash
+if [ ! -f ./docs/audit-baseline.yml ]; then
+  mkdir -p ./docs
+  cp ./skills/audit/audit-baseline-template.yml ./docs/audit-baseline.yml 2>/dev/null || \
+    printf "accepted: []\n" > ./docs/audit-baseline.yml
+fi
+cat ./docs/audit-baseline.yml
+```
+
+## Контекст анализа
+
+> Примеры ниже — иллюстративные (Node/TS). Конкретику текущего рантайма бери из
+> загруженного профиля (`stacks/<runtime>.md`, секции Idioms/Anti-patterns/Check-ID hints).
+
+**CON-01 — Параллельные операции запускаются и синхронизируются корректно:**
+- Параллельная операция запущена, но её результат не дожидается (теряется)
+- Фоновая задача утекает — нет пути её завершения
+- Shared state между параллельными операциями без синхронизации
+- В Node: `await` внутри `forEach` (итерация не ждёт промисов); `async` в `Array.map` без `Promise.all` (промисы не ожидаются)
+- В Go: goroutine без `WaitGroup`/`errgroup`/`ctx` → потеря результата или goroutine leak; захват loop-переменной в `for { go f(loopVar) }` (до Go 1.22); незакрытый канал блокирует получателей
+
+**CON-02 — Read-modify-write в транзакциях:**
+- SELECT + UPDATE без транзакции (TOCTOU — time-of-check to time-of-use)
+- Двойное списание/начисление без транзакции с блокировкой
+- Check-then-act без атомарности (читаем → проверяем → пишем без lock)
+- Optimistic locking без retry при конфликте версий
+- Кэш-инвалидация между чтением и записью
+
+**CON-03 — Разделяемое изменяемое состояние защищено синхронизацией:**
+- Глобальные переменные, изменяемые из нескольких мест без синхронизации
+- Синглтоны с mutable state без синхронизации
+- Closure над изменяемой переменной в async callback
+- Конкурентная запись в один файл/ресурс без координации
+- В Go: map/переменная уровня пакета без `sync.Mutex`/atomic при конкурентном доступе → data race; ловится `go test -race`
+
+**CON-04 — Module-level кэш инвалидируется:**
+- Module-level кэш без механизма инвалидации при обновлении данных
+- Кэш без TTL (stale data не обновляется никогда)
+- Нет стратегии обновления кэша при изменении исходных данных
+
+**CON-05 — Идемпотентность обработчиков:**
+- Обработчики событий/сообщений без идемпотентности (повторная доставка не безопасна)
+- Нет защиты от дублирующихся webhook-вызовов (нет проверки event_id)
+- Финансовые или критические операции без идемпотентного ключа
+
+**CON-06 — Фоновые операции с механизмом отмены:**
+- Фоновая операция запущена без механизма отмены — при shutdown процесс не завершается чисто
+- Background job без timeout и без механизма принудительной остановки
+- Graceful shutdown не ожидает завершения фоновых задач
+- В Node: Promise-цепочка в фоне без `AbortController`/`signal`; `setInterval`/`setImmediate` в request handler без очистки; `Promise.all` с неотменяемыми задачами
+- В Go: фоновая goroutine не слушает `ctx.Done()` → не завершается при shutdown; нужен `context.Context` с проверкой отмены
+
+## Граница с другими аудитами
+
+- **Идемпотентность** — этот скилл первичный (CON-05). `audit-errors` ссылается сюда.
+- **async/await в forEach** — первичный: `audit-bugs` (BUG-02). `audit-concurrency` (CON-01) фокусируется на параллелизме, а не на синтаксической ошибке.
+
+## Формат вывода
+
+| Check ID | Проверка | Статус | Уверенность | Доказательство | Решение | Исправлено |
+|----------|----------|--------|-------------|----------------|---------|------------|
+| CON-01 | Параллельные операции запускаются и синхронизируются корректно; результаты дожидаются, фоновые задачи не утекают | ✅ PASS | High | `src/` — async forEach не найден | — | — |
+| CON-02 | Read-modify-write операции выполняются в транзакциях | ❌ FAIL 🔴 | High | `services/wallet.ts:67` | **1. Обернуть в db.transaction() с SELECT FOR UPDATE** \\ 2. Использовать optimistic locking с retry \\ 3. Добавить уникальное ограничение на уровне БД [⚡ dynamic] | Нет |
+| CON-05 | Обработчики событий и webhook-handlers идемпотентны | ⏸ ACCEPTED | Medium | `handlers/stripe.ts:12` | В baseline: идемпотентность обеспечена через event_id [⚡ dynamic] | — |
+
+Статусы: `✅ PASS` / `❌ FAIL 🔴` / `❌ FAIL 🟠` / `❌ FAIL 🟡` / `❌ FAIL 🟢` / `⏸ ACCEPTED` / `🔍 UNVERIFIED`
+
+Уверенность: `High` — проверил несколько ключевых файлов, паттерн очевиден / `Medium` — проверил выборочно, паттерн вероятен / `Low` — ограниченный контекст, полная уверенность невозможна
+
+Для `❌ FAIL`: ровно 3 варианта решения, разделитель `\\`, вариант 1 жирным.
+
+`Исправлено`: FAIL → `Нет` (разработчик меняет на `✅ Да` вручную после фикса). PASS / ACCEPTED / UNVERIFIED → `—`.
+
+Требования к решениям:
+- Взаимно исключающие (не перефразировки одного и того же)
+- Соответствуют текущему стеку проекта (не предлагать смену фреймворка)
+- Не требуют переписать всю систему — realistic migration cost
+- Вариант 3 может быть «оставить, задокументировать причину» при наличии обоснования
+
+В конце отчёта добавь раздел покрытия:
+```
+## Audit Coverage
+Проверено: src/module1/**, src/module2/**
+Пропущено: scripts/**, migrations/**, tests/**
+Файлов проверено: N | Пропущено: N
+```
+
+Если все PASS — выведи: `✅ Проблем с конкурентностью не обнаружено.`
+
+## Сохранение результатов
+
+1. Найди папку сессии:
+   ```bash
+   ls -dt ./docs/audits/[0-9]*/ 2>/dev/null | head -1 | sed 's|/$||'
+   ```
+   Если пусто — создай: `mkdir -p ./docs/audits/$(date +"%Y-%m-%d_%H-%M")`
+2. Сохрани через Write: `<AUDIT_DIR>/audit-concurrency.md`
+
+```
+# Audit Report: State & Concurrency — <YYYY-MM-DD HH:MM>
+<таблица>
+```

package/skills/audit-deployment/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: audit-deployment
+description: >
+  Аудит сборки и деплоя: оптимизация Dockerfile, переменные окружения, CI/CD конфигурации,
+  secrets в конфигах, non-root пользователи. Запускай при /audit-deployment.
+---
+
+## Правило применимости (Relevance Rule)
+
+Применим при наличии Dockerfile, docker-compose.yml, CI/CD конфигов (`.github/workflows`, `gitlab-ci.yml`, `Jenkinsfile`), `.env` файлов, Kubernetes манифестов. Для проектов без deployment конфигурации — верни пустой ответ.
+
+## Runtime Detection & Stack Profile
+
+Этот аудит стек-агностичен: проверки сформулированы нейтрально, а конкретика
+(инструменты, идиомы, анти-паттерны, примеры) берётся из профиля стека.
+
+1. **Профиль передан контекстом?** Если оркестратор `/audit` передал
+   `runtime=<id>` и/или содержимое профиля — используй его, шаги 2–3 пропусти.
+
+2. **Иначе определи РОВНО ОДИН рантайм** этого каталога:
+   ```bash
+   if   [ -f package.json ]; then echo "runtime=node"
+   elif [ -f go.mod ]; then echo "runtime=go"
+   elif [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then echo "runtime=python"
+   elif [ -f Cargo.toml ]; then echo "runtime=rust"
+   elif [ -f pom.xml ] || ls build.gradle* settings.gradle* >/dev/null 2>&1; then echo "runtime=java"
+   else echo "runtime=generic"; fi
+   ```
+   Один запуск = один рантайм; не миксуй backend и frontend. Если найдено
+   несколько маркеров (монорепо) — выбери соответствующий текущему scope/анализируемым
+   файлам и зафиксируй выбор в разделе Audit Coverage.
+
+3. **Загрузи профиль** через Read: `./skills/audit/stacks/<runtime>.md`
+   (fallback `./skills/audit/stacks/_generic.md`, если файл не найден).
+
+Дальше используй профиль:
+- **Инструменты** — из секции «Tooling by category» профиля (раздел
+  «Инструментальная поддержка» ниже ссылается на категории, а не на команды).
+- **Ожидания PASS** — из «Idioms»; **формулировки FAIL** — из «Anti-patterns».
+- **Точечные подсказки** — из «Check-ID hints» по префиксу `DEP-`.
+- Если профиль `tier: general` или `runtime=generic` → стек-специфичные находки
+  без однозначного evidence помечай `🔍 UNVERIFIED`, а не `❌ FAIL`. Проверки,
+  чей механизм в рантайме отсутствует, помечай `N/A`.
+
+## Severity Guide
+
+| Severity | Критерий назначения |
+|----------|---------------------|
+| 🔴 Critical | RCE, auth bypass, data corruption, необратимый финансовый риск |
+| 🟠 High | Падение production, privilege escalation, утечка данных |
+| 🟡 Medium | Деградация производительности или поддерживаемости без immediate outage |
+| 🟢 Low | Стиль, читаемость, слабое нарушение конвенции |
+
+Правило: severity = impact × exploitability × blast radius. Одинаковый паттерн → одинаковый severity между аудитами.
+
+## Чеклист
+
+| Check ID | Проверка |
+|----------|----------|
+| DEP-01 | Docker images используют pinned versions (нет :latest) |
+| DEP-02 | Контейнеры запускаются от непривилегированного пользователя (USER nonroot) |
+| DEP-03 | Multi-stage build: финальный образ без инструментов сборки и dev-артефактов |
+| DEP-04 | .dockerignore исключает артефакты сборки/зависимости, VCS-каталог и секреты |
+| DEP-05 | HEALTHCHECK определён в Dockerfile |
+| DEP-06 | Секреты не hardcoded в Dockerfile (нет в ENV) |
+| DEP-07 | .env исключён из VCS |
+| DEP-08 | .env.example документирует все переменные окружения |
+| DEP-09 | Окружение переключено в production-режим: dev-артефакты выключены в проде |
+| DEP-10 | Детерминированная установка по локфайлу с проверкой целостности |
+| DEP-11 | Ограничения ресурсов контейнера определены (CPU limits, Memory limits) |
+| DEP-12 | Возможность запуска с read-only root filesystem проверена |
+
+## Правила верификации
+
+1. **Только чеклист**: оценивай ТОЛЬКО проверки выше. Не добавляй новые.
+2. **Явная верификация = PASS**: ставь `✅ PASS` только если явно проверил механизм (нашёл схему, конфиг, guard) и подтвердил отсутствие нарушения — укажи что именно проверено.
+3. **Нет доказательства = UNVERIFIED**: не можешь указать `файл:строка` ни для нарушения, ни для подтверждения — ставь `🔍 UNVERIFIED`.
+4. **Baseline приоритетен**: check_id есть в `docs/audit-baseline.yml` → `⏸ ACCEPTED`.
+5. **Только 🔴/🟠 FAIL требуют решения**: 🟡/🟢 — решение необязательно.
+
+## Evidence Quality Rules
+
+Любой `❌ FAIL` обязан содержать:
+- Точный `file:line`
+- Минимальный код-фрагмент (1–3 строки)
+- Causal chain: почему именно это нарушение → какой риск возникает
+
+Запрещено:
+- Предполагать runtime behavior без evidence в коде
+- Предполагать prod-конфигурацию по dev-конфигу
+- Предполагать отсутствие middleware без проверки всей router chain
+- Если вывод основан на предположении — только `🔍 UNVERIFIED`
+
+## Language Rule
+
+Результаты аудита должны быть написаны простым и понятным языком. Избегай сложных терминов, жаргона и абстрактных понятий без необходимости. Общепринятые технические термины (Docker, HTTP, API, JSON, URL) допустимы. Описывай проблемы так, чтобы они были понятны разработчику любого уровня, а не только узкому специалисту в данной области.
+
+## Baseline
+
+До анализа:
+```bash
+if [ ! -f ./docs/audit-baseline.yml ]; then
+  mkdir -p ./docs
+  cp ./skills/audit/audit-baseline-template.yml ./docs/audit-baseline.yml 2>/dev/null || \
+    printf "accepted: []\n" > ./docs/audit-baseline.yml
+fi
+cat ./docs/audit-baseline.yml
+```
+
+## Контекст анализа
+
+> Примеры ниже — иллюстративные. Конкретные инструменты, идиомы и анти-паттерны
+> сборки/деплоя для текущего рантайма бери из загруженного профиля
+> (`stacks/<runtime>.md`, секции Idioms/Anti-patterns/Check-ID hints по префиксу
+> `DEP-`). Node: `npm ci`/`package-lock.json`, `NODE_ENV`, `node_modules`.
+> Go: builder→distroless, `go.mod`+`go.sum`, `CGO_ENABLED=0`, нет `net/http/pprof`.
+
+**DEP-01 — Pinned versions:**
+- Базовый образ `:latest` без pinning версии (непредсказуемые обновления)
+- Тег `:alpine` без конкретной версии
+- Digest-based pinning отсутствует для критичных образов
+
+**DEP-02 — Непривилегированный пользователь:**
+- Запуск контейнера как root без переключения на non-root (Node: `USER node`; Go: distroless `nonroot`)
+- Отсутствие создания non-root пользователя перед переключением (или образа со встроенным nonroot)
+
+**DEP-03 — Multi-stage build: финальный образ без инструментов сборки и dev-артефактов:**
+- Отсутствие multi-stage build (инструменты сборки/dev-зависимости в финальном образе)
+- Node: `devDependencies` устанавливаются в production stage
+- Go: компилятор/тесты в финальном образе вместо `builder → distroless`
+- Build artifacts не копируются из builder stage
+
+**DEP-04 — .dockerignore:**
+- Нет `.dockerignore` или он не исключает зависимости/артефакты сборки (Node: `node_modules`; Go: локальный `vendor/`, build-кэш) и VCS-каталог `.git`
+- `.env` и прочие секреты не исключены из Docker build context
+- Тесты и документация попадают в production образ
+
+**DEP-05 — HEALTHCHECK:**
+- HEALTHCHECK отсутствует в Dockerfile
+- Health check endpoint не существует в приложении
+
+**DEP-06 — Секреты не в Dockerfile ENV:**
+- Secrets в `ENV` директивах Dockerfile (видны в docker inspect и слоях образа)
+- Credentials в `ARG` без использования build secrets (`--secret`)
+
+**DEP-07 — .env исключён из VCS:**
+- `.env` файл с реальными credentials закоммичен в репозиторий
+- Отсутствие `.env*` в `.gitignore`
+
+**DEP-08 — .env.example документирует переменные:**
+- `.env.example` отсутствует
+- `.env.example` содержит реальные credentials
+- Не все обязательные переменные задокументированы
+
+**DEP-09 — Окружение переключено в production-режим:**
+- Dev-артефакты не выключены в проде: debug-эндпоинты, verbose-логи, dev-зависимости
+- Node: `NODE_ENV` не выставлен или `development` в prod образе (ведёт к загрузке devDependencies в runtime)
+- Go: нет признаков prod-режима (нет `APP_ENV`/собственного флага), `net/http/pprof` и debug-роуты доступны в проде, нет `-ldflags "-s -w"`, нет `CGO_ENABLED=0`
+
+**DEP-10 — Детерминированная установка по локфайлу с проверкой целостности:**
+- Node: `npm install` вместо `npm ci` (не детерминированная, медленнее); отсутствие `package-lock.json`
+- Go: `go.mod`/`go.sum` не закоммичены; в Dockerfile `go get` вместо `go mod download` по локфайлу; нет `GOFLAGS=-mod=readonly` / `go mod verify`
+
+**Ограничения ресурсов:**
+- `docker-compose.yml` без `deploy.resources.limits.memory` и `cpus`
+- Kubernetes Deployment без `resources.limits` в контейнере
+- Нет ограничений → один контейнер с memory leak роняет весь хост
+- Go-доп.: при memory-лимите контейнера выставить `GOMEMLIMIT`/`GOMAXPROCS` под cgroup-квоты (иначе GC видит память/CPU хоста)
+
+**Read-only filesystem:**
+- Контейнер без `read_only: true` (docker-compose) или `readOnlyRootFilesystem: true` (K8s)
+- Если приложение пишет во временные файлы — проверить наличие tmpfs mount для `/tmp`
+
+## Формат вывода
+
+| Check ID | Проверка | Статус | Уверенность | Доказательство | Решение | Исправлено |
+|----------|----------|--------|-------------|----------------|---------|------------|
+| DEP-01 | Docker images используют pinned versions (нет :latest) | ✅ PASS | High | `Dockerfile:1` — pinned version указана | — | — |
+| DEP-02 | Контейнеры запускаются от непривилегированного пользователя (USER nonroot) | ❌ FAIL 🟠 | High | `Dockerfile:12` | **1. Добавить `RUN addgroup -S app && adduser -S app -G app` и `USER app`** \\ 2. Использовать образ со встроенным nonroot (Node: node:alpine; Go: distroless nonroot) \\ 3. Добавить `USER node` если базовый образ node | Нет |
+| DEP-05 | HEALTHCHECK определён в Dockerfile | ⏸ ACCEPTED | Medium | — | В baseline: health check управляется Kubernetes liveness probe | — |
+
+Статусы: `✅ PASS` / `❌ FAIL 🔴` / `❌ FAIL 🟠` / `❌ FAIL 🟡` / `❌ FAIL 🟢` / `⏸ ACCEPTED` / `🔍 UNVERIFIED`
+
+Уверенность: `High` — проверил несколько ключевых файлов, паттерн очевиден / `Medium` — проверил выборочно, паттерн вероятен / `Low` — ограниченный контекст, полная уверенность невозможна
+
+Для `❌ FAIL`: ровно 3 варианта решения, разделитель `\\`, вариант 1 жирным.
+
+`Исправлено`: FAIL → `Нет` (разработчик меняет на `✅ Да` вручную после фикса). PASS / ACCEPTED / UNVERIFIED → `—`.
+
+Требования к решениям:
+- Взаимно исключающие (не перефразировки одного и того же)
+- Соответствуют текущему стеку проекта (не предлагать смену фреймворка)
+- Не требуют переписать всю систему — realistic migration cost
+- Вариант 3 может быть «оставить, задокументировать причину» при наличии обоснования
+
+В конце отчёта добавь раздел покрытия:
+```
+## Audit Coverage
+Проверено: src/module1/**, src/module2/**
+Пропущено: scripts/**, migrations/**, tests/**
+Файлов проверено: N | Пропущено: N
+```
+
+Если все PASS — выведи: `✅ Конфигурация сборки и деплоя в порядке.`
+
+## Сохранение результатов
+
+1. Найди папку сессии:
+   ```bash
+   ls -dt ./docs/audits/[0-9]*/ 2>/dev/null | head -1 | sed 's|/$||'
+   ```
+   Если пусто — создай: `mkdir -p ./docs/audits/$(date +"%Y-%m-%d_%H-%M")`
+2. Сохрани через Write: `<AUDIT_DIR>/audit-deployment.md`
+
+```
+# Audit Report: Build & Deployment Configuration — <YYYY-MM-DD HH:MM>
+<таблица>
+```

package/skills/audit-docs/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: audit-docs
+description: >
+  Аудит документации: расхождение README/инструкций с реальным кодом, битые ссылки,
+  рассинхрон env-переменных, комментарии и JSDoc, противоречащие сигнатурам, устаревшие
+  упоминания удалённых сущностей. Запускай при /audit-docs или запросе проверить документацию.
+---
+
+## Правило применимости (Relevance Rule)
+
+Применим к любому проекту, где есть документация (README, `docs/**`, JSDoc, инструкции запуска) или комментарии в коде. Для проектов без документации вообще — проверяй только DOC-01 (минимум для онбординга) и DOC-04 (комментарии).
+
+**Фокус — только верифицируемые расхождения.** Этот аудит НЕ оценивает «достаточно ли документации» субъективно. `❌ FAIL` ставится только когда документация **противоречит** коду или ссылается на то, чего нет — и это доказуемо `file:line`. «Хорошо бы добавить описание» без конкретного противоречия — не находка.
+
+**Граница с соседними аудитами** (чтобы не дублировать находки):
+- `audit-api-contracts` — владеет «документация API vs реализация» (эндпоинты, формы ответов, OpenAPI/GraphQL-схема). REST/GraphQL-контракты отдавай туда.
+- `audit-yagni` (YAGNI-05) — владеет устаревшими TODO/FIXME без прогресса. Здесь TODO не проверяем.
+- `audit-naming` — владеет самодокументирующимися именами. Здесь не оцениваем «понятность имён».
+- `audit-deployment` (DEP-08) — владеет полнотой `.env.example`. DOC-02 фокусируется на **рассинхроне** «код ↔ документация», а не на наличии файла.
+
+## Runtime Detection & Stack Profile
+
+Этот аудит стек-агностичен: проверки сформулированы нейтрально, а конкретика
+(инструменты, идиомы, анти-паттерны, примеры) берётся из профиля стека.
+
+1. **Профиль передан контекстом?** Если оркестратор `/audit` передал
+   `runtime=<id>` и/или содержимое профиля — используй его, шаги 2–3 пропусти.
+
+2. **Иначе определи РОВНО ОДИН рантайм** этого каталога:
+   ```bash
+   if   [ -f package.json ]; then echo "runtime=node"
+   elif [ -f go.mod ]; then echo "runtime=go"
+   elif [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then echo "runtime=python"
+   elif [ -f Cargo.toml ]; then echo "runtime=rust"
+   elif [ -f pom.xml ] || ls build.gradle* settings.gradle* >/dev/null 2>&1; then echo "runtime=java"
+   else echo "runtime=generic"; fi
+   ```
+   Один запуск = один рантайм; не миксуй backend и frontend. Если найдено
+   несколько маркеров (монорепо) — выбери соответствующий текущему scope/анализируемым
+   файлам и зафиксируй выбор в разделе Audit Coverage.
+
+3. **Загрузи профиль** через Read: `./skills/audit/stacks/<runtime>.md`
+   (fallback `./skills/audit/stacks/_generic.md`, если файл не найден).
+
+Дальше используй профиль:
+- **Инструменты** — из секции «Tooling by category» профиля (раздел
+  «Инструментальная поддержка» ниже ссылается на категории, а не на команды).
+- **Ожидания PASS** — из «Idioms»; **формулировки FAIL** — из «Anti-patterns».
+- **Точечные подсказки** — из «Check-ID hints» по префиксу `DOC-`.
+- Если профиль `tier: general` или `runtime=generic` → стек-специфичные находки
+  без однозначного evidence помечай `🔍 UNVERIFIED`, а не `❌ FAIL`. Проверки,
+  чей механизм в рантайме отсутствует, помечай `N/A`.
+
+## Severity Guide
+
+| Severity | Критерий назначения |
+|----------|---------------------|
+| 🔴 Critical | Документация направляет на небезопасное действие: инструкция отключить security-механизм, опубликованный реальный секрет «для примера», команда с разрушительным побочным эффектом без предупреждения |
+| 🟠 High | Инструкция, ломающая онбординг/деплой: неверная команда установки/запуска, отсутствующая обязательная env-переменная, из-за которой прод падает или конфигурируется неверно |
+| 🟡 Medium | Дрейф: README/комментарий/JSDoc противоречит текущему коду, битые внутренние ссылки, упоминание удалённых сущностей |
+| 🟢 Low | Незначительная нехватка: публичный экспорт без doc-комментария, мелкая неактуальность без риска |
+
+Правило: severity = impact × вероятность ввести разработчика/оператора в заблуждение × blast radius. Одинаковый паттерн → одинаковый severity между аудитами.
+
+## Чеклист
+
+| Check ID | Проверка |
+|----------|----------|
+| DOC-01 | README/онбординг документирует установку, запуск, тесты, сборку; команды совпадают с манифестом задач проекта (package.json scripts / Makefile / Taskfile) |
+| DOC-02 | Env-переменные синхронизированы: каждая используемая в коде переменная задокументирована, нет задокументированных, но неиспользуемых |
+| DOC-03 | Внутренние ссылки и пути в Markdown-документации ведут на существующие файлы и секции |
+| DOC-04 | Комментарии и JSDoc/docstring не противоречат коду (сигнатура, имена параметров, типы, описанное поведение) |
+| DOC-05 | Публичная поверхность (экспортируемое API библиотеки/пакета) имеет doc-комментарий назначения и параметров |
+| DOC-06 | Проектная/архитектурная документация не ссылается на удалённые или переименованные сущности и неактуальные факты |
+
+## Правила верификации
+
+1. **Только чеклист**: оценивай ТОЛЬКО проверки выше. Не добавляй новые.
+2. **Расхождение, не отсутствие**: `❌ FAIL` валиден только при доказуемом противоречии «документация ↔ код» или ссылке на несуществующее. Субъективное «мало документации» — не FAIL.
+3. **Два якоря на находку**: каждый FAIL обязан указывать И место в документации (`file:line`), И место в коде, которое его опровергает (`file:line`).
+4. **Явная верификация = PASS**: ставь `✅ PASS`, только если сверил документ с кодом и подтвердил соответствие — укажи что именно сверено.
+5. **Нет доказательства = UNVERIFIED**: не можешь указать оба якоря — ставь `🔍 UNVERIFIED`.
+6. **Baseline приоритетен**: check_id есть в `docs/audit-baseline.yml` → `⏸ ACCEPTED`.
+7. **Только 🔴/🟠 FAIL требуют решения**: 🟡/🟢 — решение необязательно.
+
+## Evidence Quality Rules
+
+Любой `❌ FAIL` обязан содержать:
+- Якорь в документации: `file:line` + цитата утверждения (1–2 строки)
+- Якорь в коде: `file:line`, опровергающий утверждение
+- Causal chain: почему расхождение → кого и как введёт в заблуждение (разработчик при онбординге / оператор при деплое / читатель API)
+
+Запрещено:
+- Считать FAIL отсутствие комментария там, где код самоочевиден (это не противоречие)
+- Проверять внешние URL на доступность (сеть нестабильна) — только внутренние ссылки/пути и якоря внутри репозитория
+- Предполагать, что команда/переменная «вероятно устарела» без сверки с кодом — только `🔍 UNVERIFIED`
+- Дублировать находки, принадлежащие `audit-api-contracts`/`audit-yagni`/`audit-naming` (см. границы выше)
+
+## Language Rule
+
+Результаты аудита должны быть написаны простым и понятным языком. Избегай сложных терминов, жаргона и абстрактных понятий без необходимости. Общепринятые технические термины (Docker, HTTP, API, JSON, URL) допустимы. Описывай проблемы так, чтобы они были понятны разработчику любого уровня, а не только узкому специалисту в данной области.
+
+## Baseline
+
+До анализа:
+```bash
+if [ ! -f ./docs/audit-baseline.yml ]; then
+  mkdir -p ./docs
+  cp ./skills/audit/audit-baseline-template.yml ./docs/audit-baseline.yml 2>/dev/null || \
+    printf "accepted: []\n" > ./docs/audit-baseline.yml
+fi
+cat ./docs/audit-baseline.yml
+```
+
+## Контекст анализа
+
+**DOC-01 — Инструкции совпадают с реальностью:**
+- README ссылается на скрипт/команду, которой нет в манифесте задач проекта (package.json scripts / Makefile / Taskfile)
+- Документированы шаги установки с неверным менеджером пакетов или версией рантайма (несовпадение с `engines`/lock-файлом)
+- Отсутствует базовый онбординг (как установить / запустить / прогнать тесты) при наличии этих скриптов в проекте
+
+**DOC-02 — Синхронизация env-переменных:**
+- Переменная используется в коде, но отсутствует в `.env.example`/README — оператор не узнает о ней
+- Переменная задокументирована, но больше нигде не читается (устаревшая инструкция)
+- Описание переменной противоречит коду (дефолт, формат, обязательность)
+- Синтаксис извлечения env-переменных из кода бери из профиля стека (`process.env` / `import.meta.env` / `os.Getenv`)
+
+**DOC-03 — Валидные ссылки и пути:**
+- Относительная ссылка в Markdown ведёт на несуществующий файл
+- Якорь (`#section`) указывает на отсутствующий заголовок
+- Путь к файлу/папке в инструкции не существует в репозитории
+
+**DOC-04 — Комментарии не лгут:**
+- JSDoc/TSDoc `@param`/`@returns` не совпадает с фактической сигнатурой (имя, число, тип параметров)
+- Комментарий описывает поведение, противоположное коду («возвращает null, если...» — а код кидает исключение)
+- Docstring/комментарий ссылается на параметр/шаг, которого в функции уже нет
+
+**DOC-05 — Документация публичной поверхности:**
+- Применять ТОЛЬКО если проект является публикуемой библиотекой/пакетом (по манифесту проекта)
+- Экспортируемая публичная функция/класс/тип без doc-комментария назначения
+- Для приложений (не публикуемая библиотека) — DOC-05 = `N/A`, не FAIL
+
+**DOC-06 — Актуальность проектной документации:**
+- Архитектурный документ описывает модуль/сервис/эндпоинт, удалённый или переименованный в коде
+- Диаграмма/схема упоминает технологию, которой больше нет в зависимостях
+- Версия в документации расходится с `package.json`/тегом (если документация декларирует версию)
+
+## Инструментальная поддержка
+
+Env-переменные — код vs документация (DOC-02): извлеки имена env-переменных из кода
+инструментом категории **env-extraction** из профиля стека (секция «Tooling by
+category»; синтаксис зависит от рантайма — Node: `process.env`/`import.meta.env`;
+Go: `os.Getenv`). Сравни полученный список с задокументированными переменными
+(`.env.example`/README); разница между списками — кандидаты в DOC-02. Верифицируй
+каждую вручную (бывают переменные из CI/инфраструктуры, не из `.env`).
+
+Команды README vs манифест задач (DOC-01): возьми список задач/скриптов из
+**манифеста задач проекта** (по профилю стека: `package.json` scripts / `Makefile` /
+`Taskfile`). Команды, упомянутые в README, сверь с этим манифестом — команда из
+README, которой нет в манифесте, → кандидат в DOC-01.
+
+Внутренние ссылки в Markdown (DOC-03): извлеки относительные ссылки `[...](./path)` и проверь существование путей через `Read`/`ls`. Внешние `http(s)://`-ссылки НЕ проверяй на доступность.
+
+## Формат вывода
+
+| Check ID | Проверка | Статус | Уверенность | Доказательство | Решение | Исправлено |
+|----------|----------|--------|-------------|----------------|---------|------------|
+| DOC-01 | README документирует установку/запуск/тесты, команды совпадают со scripts | ❌ FAIL 🟠 | High | `README.md:24` — `npm run start:dev`; в `package.json` есть только `dev` | **1. Исправить README на `npm run dev`** \\ 2. Добавить алиас `start:dev` в scripts \\ 3. Сгенерировать раздел команд из scripts автоматически | Нет |
+| DOC-02 | Env-переменные синхронизированы | ❌ FAIL 🟠 | High | `src/config.ts:9` читает `REDIS_URL`; нет в `.env.example` | **1. Добавить `REDIS_URL` в `.env.example` с описанием** \\ 2. Валидировать env при старте (zod/envalid) \\ 3. Удалить чтение переменной, если она не нужна | Нет |
+| DOC-04 | Комментарии и JSDoc не противоречат коду | ❌ FAIL 🟡 | Medium | `src/user.ts:40` JSDoc `@returns User`; функция возвращает `User | null` | **1. Поправить `@returns` на `User \| null`** \\ 2. Удалить устаревший JSDoc \\ 3. Включить `eslint-plugin-jsdoc` для авто-проверки | Нет |
+| DOC-05 | Публичная поверхность задокументирована | ✅ PASS | Medium | по манифесту — приложение, не публикуемая библиотека → N/A | — | — |
+
+Статусы: `✅ PASS` / `❌ FAIL 🔴` / `❌ FAIL 🟠` / `❌ FAIL 🟡` / `❌ FAIL 🟢` / `⏸ ACCEPTED` / `🔍 UNVERIFIED` / `N/A`
+
+Уверенность: `High` — сверил утверждение документации с кодом, расхождение однозначно / `Medium` — расхождение вероятно, контекст проверен выборочно / `Low` — ограниченный контекст, полная уверенность невозможна
+
+Для `❌ FAIL`: ровно 3 варианта решения, разделитель `\\`, вариант 1 жирным.
+
+`Исправлено`: FAIL → `Нет` (разработчик меняет на `✅ Да` вручную после фикса). PASS / ACCEPTED / UNVERIFIED / N/A → `—`.
+
+Требования к решениям:
+- Взаимно исключающие (не перефразировки одного и того же)
+- Минимум один вариант — «исправить документ», минимум один — «исправить/удалить код или автоматизировать сверку»
+- Реалистичная стоимость, без «переписать всю документацию»
+- Вариант 3 может быть «удалить устаревший раздел/комментарий», если он больше не нужен
+
+В конце отчёта добавь раздел покрытия:
+```
+## Audit Coverage
+Проверено: README.md, docs/**, src/**/*.ts (JSDoc), .env.example
+Пропущено: CHANGELOG.md (auto-generated), node_modules/**
+Файлов проверено: N | Пропущено: N
+```
+
+Если все PASS — выведи: `✅ Расхождений документации с кодом не обнаружено.`
+
+## Сохранение результатов
+
+1. Найди папку сессии:
+   ```bash
+   ls -dt ./docs/audits/[0-9]*/ 2>/dev/null | head -1 | sed 's|/$||'
+   ```
+   Если пусто — создай: `mkdir -p ./docs/audits/$(date +"%Y-%m-%d_%H-%M")`
+2. Сохрани через Write: `<AUDIT_DIR>/audit-docs.md`
+
+```
+# Audit Report: Documentation — <YYYY-MM-DD HH:MM>
+<таблица>
+```