# Зачем это нужно

Репозиторий проваливается не на коде, а на документации. `git push` проходит, тесты
зелёные, а читатель не понимает, как проект запустить. Дефект живёт годами, потому что
его не видно: ни компилятор, ни CI о нём не сообщают.

## Пять дефектов, которые встречаются чаще всего

| Дефект | Как выглядит | Чем опасен |
|---|---|---|
| README без установки | сразу архитектура и философия | читатель уходит на втором абзаце |
| Журнал изменений без дат | `## 1.1.0` и всё | версии нельзя сравнить и связать |
| Вики без навигации | десять страниц, ссылок нет | страницы существуют, но не находятся |
| Ссылка в никуда | `[API](docs/api.md)` при `docs/API.md` | документация «есть», но не открывается |
| Описание из трёх слов | «panel», «tools» | поиск не показывает проект |

Ни один из них не ловится запуском кода. Все пять ловятся сверкой: файл против контракта,
ссылка против дерева, якорь против заголовка.

## Почему это работа для агента

Проверка механическая, но требует внимания к деталям, которых человек не держит в голове:
шестнадцать обязательных файлов, правила якорей с кириллицей, порядок типов изменений,
лимит тем в API. Агент с одной командой делает это за секунды и не забывает про исключения.

Обратная сторона: агент без проверки выдумывает. Он напишет «быстрая панель» вместо
измеренного числа и «см. документацию» вместо ссылки. Поэтому пакет устроен так, что
каждое утверждение либо проверяется, либо отклоняется.

## Что считается провалом

| Ситуация | Почему провал |
|---|---|
| Проверка осмотрела ноль файлов и вернула «успех» | зелёный результат ничего не значит |
| Ссылка на несуществующую страницу вики | читатель считает, что документация есть |
| Публикация вики удалила чужую страницу | потеря данных без предупреждения |
| Выпуск версии без записей | журнал перестаёт что-либо значить |
| Число в README без источника | проверить нельзя, доверять нельзя |

## Дальше

- [Установка](02-Install.ru) — поставить и проверить.
- [Ловушки платформы](06-Traps.ru) — места, где поведение GitHub отличается от ожидаемого.
- [Контракты файлов](03-Repository-Contract.ru) — что именно проверяется.