kodu 2.1.1 → 2.1.3

package/lefthook.yml

@@ -1,4 +1,11 @@
 pre-commit:
-  jobs:
-    - name: Check project
+  parallel: false
+  commands:
+    check:
       run: npm run check
+
+pre-push:
+  parallel: false
+  commands:
+    test:
+      run: npm run test

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodu",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "High-performance CLI to prepare codebase for LLMs, automate reviews, and draft commits.",
   "repository": {
     "type": "git",
@@ -34,6 +34,7 @@
     "generate:schema": "ts-node scripts/generate-json-schema.ts",
     "postbuild": "npm run generate:schema",
     "start:prod": "node dist/main.js",
+    "start:dev": "nest start --watch",
     "new:command": "nest g -c nest-commander-schematics command",
     "new:question": "nest g -c nest-commander-schematics question",
     "________________ FORMAT AND LINT ________________": "",
@@ -43,8 +44,14 @@
     "ts:check": "tsc --noEmit",
     "knip": "knip --production",
     "check": "run-p ts:check lint:fix knip",
+    "________________ TEST ________________": "",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
     "________________ OTHER ________________": "",
-    "prepare": "lefthook install"
+    "prepare": "is-ci || lefthook install",
+    "update": "npx npm-check-updates -u && rimraf node_modules package-lock.json && npm i",
+    "postupdate": "npm run lint:fix && npm run check"
   },
   "dependencies": {
     "@inquirer/confirm": "^6.0.4",
@@ -73,13 +80,17 @@
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.1",
     "@types/node": "^22.10.7",
+    "is-ci": "^4.1.0",
     "knip": "^5.82.1",
     "lefthook": "^2.0.15",
     "nest-commander-schematics": "^3.2.0",
+    "npm-check-updates": "^18.3.1",
     "npm-run-all": "^4.1.5",
+    "rimraf": "^6.1.3",
     "ts-loader": "^9.5.2",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
   }
 }

package/skills/doc-gen/SKILL.md

@@ -0,0 +1,490 @@
+---
+name: doc-gen
+description: Генерирует документацию продукта уровня MVP+. Запускай когда пользователь явно планирует новый продукт/сервис/приложение или просит помочь со структурой проекта. НЕ запускай при вопросах о существующем коде, разовых задачах («напиши скрипт», «исправь баг») или учебных упражнениях.
+license: MIT
+compatibility: opencode
+metadata:
+  level: multi
+  output: папка с markdown-файлами
+---
+
+## Назначение
+
+Скилл создаёт два документа, которые полностью описывают продукт для разработки:
+- **Концепция** (VISION.md) — зачем создаётся продукт и для кого
+- **Спецификация** (SPEC.md) — из чего состоит продукт, достаточно для начала разработки
+
+**Когда запускать:**
+- Пользователь описывает **новый продукт** или **сервис** и планирует его строить
+- Пользователь просит **структурировать проект** или описать архитектуру
+- Пользователь говорит «хочу сделать X» в контексте продукта или сервиса
+
+**Когда НЕ запускать:**
+- Вопрос о коде существующего проекта
+- Разовая задача («напиши скрипт», «добавь функцию»)
+- Учебный или тестовый проект без цели развивать
+
+---
+
+## Входные данные
+
+Пользователь предоставляет **минимальное описание**:
+1. Какую проблему решает продукт
+2. Кто будет пользоваться
+3. Что должно работать в первую очередь
+
+Если данных недостаточно — задать **не более 2 уточняющих вопросов**.
+
+---
+
+## Структура вывода
+
+```
+<имя проекта>/
+├── INDEX.md                             — оглавление
+├── 1_PRODUCT_VISION/
+│   └── VISION.md                        — концепция продукта
+├── 2_PRODUCT_SPEC/
+│   └── SPEC.md                          — спецификация продукта
+└── 3_ARTIFACTS/                         — вспомогательные материалы
+    ├── legal/                           — юридические документы (договоры, оферты, политики конфиденциальности)
+    ├── media/
+    │   ├── images/                      — изображения (логотипы, скриншоты, схемы, мокапы)
+    │   └── video/                       — видеоматериалы (демо, инструкции)
+    ├── content/                         — тексты для страниц и маркетинговые материалы
+    └── examples/                        — примеры контента, шаблоны, тестовые данные
+```
+
+---
+
+## Артефакты (3_ARTIFACTS/)
+
+Артефакты — вспомогательные материалы, на которые ссылаются документы. Это не исходный код и не дополнительная документация — это конкретные файлы, нужные для разработки или запуска продукта.
+
+### Организация папок
+
+| Папка | Что хранить |
+|-------|-------------|
+| `legal/` | Договоры, оферты, политики конфиденциальности, условия использования, лицензионные соглашения |
+| `media/images/` | Логотипы, брендинг, скриншоты интерфейсов, схемы архитектуры, мокапы страниц |
+| `media/video/` | Демо продукта, обучающие видео, презентации |
+| `content/` | Тексты для страниц сайта, маркетинговые тексты, email-шаблоны, FAQ |
+| `examples/` | Примеры заполнения форм, шаблоны контента, тестовые наборы данных |
+
+### Правила работы с артефактами
+
+- **Папку `3_ARTIFACTS/` и подпапки создавать только при наличии реального файла для размещения.** Пустые папки запрещены.
+- **Каждый артефакт** должен быть явно упомянут хотя бы в одном документе (VISION.md, SPEC.md или INDEX.md)
+- **SPEC.md** должен содержать раздел `## Артефакты` со ссылками на все файлы из `3_ARTIFACTS/`
+- **INDEX.md** должен содержать быстрые ссылки на ключевые артефакты
+- Ссылки — **относительные**, например `../3_ARTIFACTS/legal/privacy-policy.md`
+- Имена файлов — латинские буквы, дефисы, без пробелов: `privacy-policy.pdf`, `logo-main.svg`
+- **Не добавлять в SPEC.md ссылки-заглушки** на файлы, которых ещё не существует
+
+---
+
+## Процесс работы
+
+> **Скрипт:** `~/.config/opencode/skills/doc-gen/scripts/doc_gen.py`
+> Скрипт НЕ копируется в проект — используется напрямую из папки скилла.
+> Далее в примерах: `{DOC_GEN}` = полный путь выше.
+
+### Шаг 1. Сбор информации
+Задать не более **2 уточняющих вопросов**. Если заявленный функционал явно избыточен для первой версии — указать до начала генерации.
+
+### Шаг 2. Создание структуры файлов
+```bash
+python3 {DOC_GEN} generate "НазваниеПроекта"
+
+# Только концепция (VISION.md):
+python3 {DOC_GEN} generate "НазваниеПроекта" --only L1
+
+# Только спецификация (SPEC.md):
+python3 {DOC_GEN} generate "НазваниеПроекта" --only L2
+
+# Дополнение без перезаписи существующих файлов:
+python3 {DOC_GEN} generate "НазваниеПроекта" --update
+```
+
+Команда `generate` **не создаёт** папку `3_ARTIFACTS/` автоматически. Папка и подпапки создаются **только при размещении реального файла-артефакта**. Если артефактов нет — раздел `## Артефакты` в SPEC.md **должен присутствовать** с явной пометкой: «Артефактов нет.»
+
+### Шаг 3. Заполнение документов
+Заполнять **строго в порядке**: VISION.md → SPEC.md. Все ссылки — относительные.
+
+**Обязательные правила заполнения:**
+- Незаполненных заглушек (текст в `[квадратных скобках]`) быть не должно
+- Каждый раздел либо **заполнен конкретным содержимым**, либо **явно содержит отрицание** (например: «Интеграций нет.»)
+- **Запрещено** писать «при необходимости», «опционально», «возможно» — только конкретные утверждения
+- Нет опциональных решений: либо что-то **есть** в продукте, либо **явно написано**, что его нет
+
+### Шаг 4. Полная проверка: структура + согласованность **(обязательно)**
+После **любого** изменения документации запускать полную валидацию:
+```bash
+python3 {DOC_GEN} validate "НазваниеПроекта"
+```
+**Документация не считается готовой, пока валидация не пройдена без ошибок.**
+
+Скрипт выполняет **два блока проверок последовательно**:
+
+**Блок 1 — Структура и содержимое:**
+- Все обязательные файлы существуют
+- Все обязательные разделы присутствуют в каждом файле
+- Строки **Статус** и **Дата** присутствуют
+- Незаполненных заглушек `[...]` нет
+- Запрещённые слова/фразы отсутствуют («возможно», «удобно», «быстро», «опционально» и др.)
+- Разделы VISION/SPEC не слишком короткие (минимум 60 символов)
+- Целевые значения в «Метрики успеха» содержат числа
+- Раздел `## Артефакты` присутствует в SPEC.md (либо с ссылками, либо с «Артефактов нет.»)
+- Каждый файл в `3_ARTIFACTS/` упомянут хотя бы в одном документе (нет «мёртвых» артефактов)
+
+**Блок 2 — Согласованность и противоречия (автоматически):**
+- `[VISION]` Попарная проверка: «Что входит» ↔ «Что НЕ входит» (≥2 общих слова у пары → флаг)
+- `[VISION]` Попарно: «Цель» конфликтует с «Что НЕ входит»
+- `[VISION→SPEC]` Исключённые элементы VISION обнаружены в SPEC операциях/страницах
+- `[VISION→SPEC]` Ключевые возможности VISION не отражены в SPEC (<40% ключевых слов)
+- `[VISION→SPEC]` Пункты «Что входит» не покрыты в SPEC (<35% ключевых слов)
+- `[SPEC]` Сущности не упоминаются в «Ключевые операции»
+- `[SPEC]` Отсутствуют обязательные подразделы «Тестирование»
+- `[SPEC]` Термины глоссария нигде не используются
+
+Для изолированного запуска только анализа согласованности:
+```bash
+python3 {DOC_GEN} consistency "НазваниеПроекта"
+```
+
+### Шаг 5. AI-проверка качества **(обязательно)**
+После успешного `validate` — выполнить вручную. Скрипт эти вещи не проверяет.
+
+**Читаемость и форматирование:**
+1. Каждая возможность в «Ключевые возможности» имеет **жирное название** (`**Название**:`) и стрелку `→` — формат «пользователь делает X → получает Y»
+2. Разделы «Проблема», «Целевая аудитория», «Цель», «Как устроена система» содержат хотя бы одно **жирное** ключевое утверждение для быстрого сканирования
+3. Нет монолитных абзацев — предложения разбиты; ни одно предложение не длиннее 2–3 строк
+4. Разделы «Ключевые возможности», «Что входит», «Что НЕ входит», «Ключевые операции» оформлены именно как списки, а не сплошной текст
+5. Жирным не выделено всё подряд — только ключевые слова/действия (не более 30% строк в разделе)
+
+**Логика и смысл:**
+6. «Цель» конкретно решает «Проблему» — нет разрыва между описанием боли и описанием продукта
+7. Каждая метрика успеха измеряет именно заявленную «Цель», а не общий рост бизнеса
+8. «Что НЕ входит» не противоречит «Ключевым возможностям» по смыслу (не только по ключевым словам — проверить значение)
+9. Сценарии тестирования охватывают реальные риски данного домена, а не только шаблонные кейсы
+
+**Язык:**
+10. «Ключевые операции» описывают **результат для пользователя**, не технический процесс («пользователь видит список заказов», а не «система возвращает массив объектов»)
+11. Термины в «Глоссарии» действительно требуют пояснения — не добавлены очевидные слова типа «пользователь» или «система»
+12. Нигде нет технического жаргона (эндпоинт, CRUD, ORM, REST, JSON и т.п.) — исключение: продукт-API, там это допустимо в разделе «Страницы и экраны»
+
+### Шаг 6. Git-коммит **(обязательно)**
+После каждого изменения документации создавать **коммит**:
+```bash
+git add docs/
+git commit -m "docs: обновление документации <НазваниеПроекта>"
+```
+Если **git-репозитория нет** — создать его до первого коммита:
+```bash
+git init
+git add .
+git commit -m "docs: начальная документация <НазваниеПроекта>"
+```
+**Git-репозиторий обязателен.** Без него история изменений недоступна.
+
+---
+
+## Команды управления
+
+### Статус документации
+```bash
+# Все проекты в папке docs/:
+python3 {DOC_GEN} status
+
+# Конкретный проект:
+python3 {DOC_GEN} status "НазваниеПроекта"
+```
+Выводит таблицу: проект / файл / статус / дата.
+
+### Обновление статуса
+```bash
+python3 {DOC_GEN} update-status "НазваниеПроекта" "на ревью"
+python3 {DOC_GEN} update-status "НазваниеПроекта" "утверждён"
+python3 {DOC_GEN} update-status "НазваниеПроекта" "черновик"
+```
+Атомарно обновляет **Статус** и **Дата** во всех трёх файлах (INDEX.md, VISION.md, SPEC.md). После — создать git-коммит.
+
+### Только анализ согласованности
+```bash
+python3 {DOC_GEN} consistency "НазваниеПроекта"
+```
+Запускает только Блок 2 без структурной проверки. Полезно при итеративной правке содержимого.
+
+---
+
+## Управление статусом документов
+
+Каждый документ содержит строку статуса в начале:
+```
+**Статус:** черновик | **Дата:** YYYY-MM-DD
+```
+
+| Статус | Условие перехода |
+|--------|-----------------|
+| `черновик` | Документ создан, не проверен командой |
+| `на ревью` | Документ отправлен на проверку |
+| `утверждён` | Документ согласован и готов к разработке |
+
+**Дату** обновлять при каждом значимом изменении. История изменений — `git log -- <файл>`.
+
+---
+
+## Правила написания концепции (VISION.md)
+
+**Плохой пример:**
+- «Сделать авторизацию»
+- «Приложение для заметок»
+
+**Хороший пример:**
+- «Вход через внешние сервисы (Google, GitHub) без хранения паролей»
+- «Мобильное приложение для заметок с работой без интернета для пользователей с нестабильным подключением»
+
+### Обязательная структура VISION.md
+
+```markdown
+# <Название продукта>
+
+**Статус:** черновик | **Дата:** YYYY-MM-DD
+
+## Проблема
+Что конкретно неудобно или не работает. Контекст. 2–4 предложения.
+
+## Целевая аудитория
+Роль и контекст работы пользователя. Не «все пользователи», а конкретный тип. 2–4 предложения.
+
+## Цель
+Что именно создаём и для кого. 2–4 предложения.
+
+## Ключевые возможности
+1. **<Название>**: пользователь выполняет X → получает Y
+2. ...
+
+## Метрики успеха
+| Метрика | Целевое значение |
+|---------|------------------|
+| ... | конкретное число |
+
+## Что входит (границы проекта)
+Функциональность, которая будет реализована:
+1. ...
+
+## Что НЕ входит
+Явные исключения для предотвращения расширения границ проекта:
+- Не включает X
+- Не включает Y
+```
+
+### Правила раздела
+
+- Без упоминания **технологий и стека** разработки
+- **Конкретные метрики** с числами (не «быстрее» — а «менее 2 секунд»)
+- Каждая возможность объясняет **ценность для пользователя**
+- Оба раздела границ проекта заполнены
+
+---
+
+## Правила написания спецификации (SPEC.md)
+
+Документ описывает **из чего состоит продукт** в терминах бизнеса. Без технических деталей реализации — но **достаточно конкретно**, чтобы разработчик мог начать без дополнительных вопросов.
+
+**Обязательные разделы:** Ссылки, Как устроена система, Глоссарий, Сущности, Страницы и экраны, Ключевые операции, Интеграции, Тестирование.
+
+### Обязательная структура SPEC.md
+
+```markdown
+# Продуктовая спецификация: <Название продукта>
+
+**Статус:** черновик | **Дата:** YYYY-MM-DD
+
+## Ссылки
+- Концепция: [VISION.md](../1_PRODUCT_VISION/VISION.md)
+
+## Как устроена система
+Краткое описание из каких частей состоит продукт и как они взаимодействуют.
+Пример: «Веб-приложение с личным кабинетом и административной панелью. Данные хранятся
+централизованно, доступ — через браузер без установки приложений.»
+
+## Глоссарий
+Ключевые понятия продукта. Каждый термин имеет одно точное определение без синонимов.
+
+| Термин | Определение |
+|--------|-------------|
+| ... | ... |
+
+## Сущности
+Основные объекты, с которыми работает система. В терминах бизнеса, не базы данных.
+
+| Сущность | Описание | Ключевые свойства |
+|----------|----------|-------------------|
+| Пользователь | Зарегистрированный участник системы | Имя, email, роль, дата регистрации |
+| ... | ... | ... |
+
+### Жизненный цикл сущностей
+Для каждой ключевой сущности — допустимые статусы и переходы между ними.
+
+| Сущность | Статусы | Переходы |
+|----------|---------|----------|
+| Заказ | черновик → подтверждён → выполнен → отменён | черновик→подтверждён: пользователь нажимает «Оформить» |
+
+## Страницы и экраны
+Исчерпывающий список страниц и экранов, которые должны быть созданы.
+
+| Страница | Назначение | Ключевые элементы |
+|----------|------------|-------------------|
+| Главная | Точка входа, обзор возможностей | Навигация, блок преимуществ, кнопка действия |
+| Регистрация | Создание аккаунта | Форма, валидация, подтверждение email |
+| ... | ... | ... |
+
+## Ключевые операции
+Что пользователи могут делать в системе. Группировать по ролям при наличии нескольких типов.
+
+**<Роль или «Все пользователи»>:**
+- Операция 1: краткое описание результата
+- Операция 2: краткое описание результата
+
+## Интеграции
+Внешние сервисы, без которых продукт не работает.
+Если интеграций нет — написать: «Интеграций нет.»
+
+| Сервис | Назначение |
+|--------|------------|
+| ... | ... |
+
+## Тестирование
+Функциональность, покрытая тестами.
+
+**Критические сценарии** (обязаны работать без ошибок):
+- Пользователь регистрируется и входит в систему
+- ...
+
+**Бизнес-правила** (корректность расчётов и ограничений):
+- Расчёт X при условии Y
+- Валидация Z
+- ...
+
+**Негативные сценарии** (поведение системы при ошибках и отменах):
+- Пользователь вводит неверный пароль → система отображает «Неверный логин или пароль», доступ не предоставляется
+- Пользователь отменяет заказ → статус меняется на «отменён», деньги возвращаются в течение 3 рабочих дней
+- ...
+
+## Артефакты
+Вспомогательные материалы для разработки и запуска продукта.
+Если артефактов нет — написать: «Артефактов нет.»
+
+| Файл | Тип | Назначение |
+|------|-----|-----------|
+| [privacy-policy.md](../3_ARTIFACTS/legal/privacy-policy.md) | Юридический | Политика конфиденциальности |
+| [logo-main.svg](../3_ARTIFACTS/media/images/logo-main.svg) | Изображение | Основной логотип продукта |
+| [homepage-copy.md](../3_ARTIFACTS/content/homepage-copy.md) | Контент | Тексты для главной страницы |
+| ... | ... | ... |
+```
+
+### Правила раздела
+
+- Язык бизнеса, не разработчика: «список товаров», не «массив объектов»
+- Страницы — **исчерпывающий** список, ни одна не пропущена
+- Сущности — только те, что **реально нужны** продукту
+- Операции описывают **результат**, не техническую реализацию
+- Тестирование описывает **что проверять**, не как это реализовать
+- Без стека, фреймворков, архитектурных паттернов
+- **Негативные сценарии обязательны**: что происходит при ошибках, отменах, конфликтах
+
+---
+
+## INDEX.md — Оглавление
+
+```markdown
+# Документация продукта: <Название>
+
+**Статус:** черновик | **Дата:** YYYY-MM-DD
+
+## Навигация
+
+| Документ | Описание |
+|----------|----------|
+| [Концепция](./1_PRODUCT_VISION/VISION.md) | Проблема, аудитория, цель, границы проекта |
+| [Спецификация](./2_PRODUCT_SPEC/SPEC.md) | Сущности, страницы, операции, тестирование |
+
+## Быстрые ссылки
+
+- [Ключевые возможности](./1_PRODUCT_VISION/VISION.md#ключевые-возможности)
+- [Страницы и экраны](./2_PRODUCT_SPEC/SPEC.md#страницы-и-экраны)
+- [Тестирование](./2_PRODUCT_SPEC/SPEC.md#тестирование)
+- [Артефакты](./2_PRODUCT_SPEC/SPEC.md#артефакты)
+
+## Артефакты
+
+| Файл | Описание |
+|------|----------|
+| [Политика конфиденциальности](./3_ARTIFACTS/legal/privacy-policy.md) | Условия обработки персональных данных |
+| ... | ... |
+```
+
+*Если артефактов нет, раздел «Артефакты» и таблицу удалить. В «Быстрых ссылках» строку «Артефакты» тоже удалить.*
+
+---
+
+## Edge Cases
+
+### Продукт без UI (API, CLI, библиотека)
+Раздел «Страницы и экраны» заменить на «Эндпоинты и команды» с аналогичной структурой таблицы. В начале SPEC.md явно указать: «Продукт не имеет пользовательского интерфейса.» Валидатор пропускает переименованный раздел — обязательный заголовок `## Страницы и экраны` всё равно должен присутствовать, содержание заменяется.
+
+### Несколько типов пользователей (ролей)
+В «Ключевые операции» — подраздел для каждой роли. В Глоссарии — определение каждой роли. Сущность «Пользователь» отражает разделение ролей (свойство «роль»). Метрики успеха — для каждой роли отдельно.
+
+### Противоречие между VISION.md и SPEC.md
+Скрипт (`validate` / `consistency`) обнаруживает противоречия автоматически. Приоритет разрешения — VISION.md. Уточнить с пользователем до финализации SPEC.md. Нельзя считать документацию готовой, если `validate` завершается с ошибками блока «Согласованность».
+
+### Пользователь меняет требования после генерации
+1. Обновить VISION.md.
+2. Проверить согласованность с SPEC.md (чеклист из Шага 5).
+3. Запустить валидацию.
+4. Создать коммит с описанием что и почему изменилось.
+Не пересоздавать файлы — использовать `--update` или редактировать напрямую.
+
+### Имя проекта с пробелами или спецсимволами
+Использовать CamelCase или дефис: `МойПроект`, `my-project`. Пробелы и символы `/ \ : * ? " < > |` недопустимы — doc_gen.py откажет с ошибкой.
+
+### Продукт без интеграций
+Удалить таблицу. Написать явно: «Интеграций нет.» Это единственный раздел, где допустимо явное отрицание вместо таблицы.
+
+### Продукт с несколькими подпродуктами (монорепо)
+Запускать `doc_gen.py generate` отдельно для каждого подпродукта с разными именами. Общий INDEX.md на верхнем уровне создаётся вручную со ссылками на каждую папку.
+
+### Смена концепции (pivot)
+Создать ветку git. Переписать VISION.md с нуля. Пересмотреть SPEC.md полностью. Не смешивать старую и новую концепции в одном документе — старая версия хранится в git-истории.
+
+### Артефакты ещё не созданы
+Пока файл не создан физически в `3_ARTIFACTS/` — **не упоминать его в SPEC.md и не создавать подпапку под него**. Раздел `## Артефакты` содержит только уже существующие ссылки или «Артефактов нет.». Правило: сначала есть реальный файл — потом создаётся папка и добавляется ссылка. Никак не наоборот.
+
+### Слишком много артефактов одного типа
+При большом количестве файлов одного типа — создавать вложенные подпапки внутри стандартных:
+`media/images/screenshots/`, `media/images/mockups/`, `legal/agreements/`, `content/emails/`.
+Структура должна быть очевидной без объяснений — не создавать подпапку ради одного файла.
+
+### Артефакты без документации
+Артефакт не может существовать без упоминания в документе. Если файл в `3_ARTIFACTS/` нигде не ссылается — либо удалить его, либо добавить ссылку в SPEC.md. «Мёртвые» артефакты не допускаются.
+
+### Ложные срабатывания валидатора на заглушки
+Паттерн `[текст]` без следующей `(` считается заглушкой. Исключения: ссылки `[текст](url)` — не заглушка. Если в содержимом нужны квадратные скобки не как заглушка (например, `[RFC 7231]`), использовать HTML-эскейп: `&#91;RFC 7231&#93;`.
+
+---
+
+## Ключевые ограничения
+
+- Без технологий и стека — документ реализуем на **любом** языке и платформе
+- Язык понятен владельцу бизнеса **без технического образования**
+- Каждая страница в SPEC.md **связана** с возможностью из VISION.md
+- Незаполненных заглушек быть не должно
+- **Нет опциональных решений**: либо явно описано, либо явно сказано «нет»
+- Язык документации — **русский**
+- Все ссылки — **относительные**
+- После каждого изменения — **валидация** (`{DOC_GEN} validate`) и **git-коммит**
+- **`3_ARTIFACTS/` не создаётся автоматически** — только при размещении реального файла
+- **Каждый артефакт** в `3_ARTIFACTS/` упомянут хотя бы в одном документе
+- **SPEC.md обязан** содержать раздел `## Артефакты` (либо с таблицей ссылок, либо с «Артефактов нет.»)