Сопровождение документации — регламент, черновик кампании

2.1 Петля коммита: мелочи

07Правило одно, и это привычка команды, а не технический гейт: изменение продукта, которое видно пользователю, несёт документацию в том же коммите — как сегодня DEV-GUIDE и RUNTIME-GUIDE (план, R-11). «Видно пользователю» — это новая или изменённая команда, флаг, поле манифеста или lock-файла, формат отчёта, сообщение об ошибке с адресом, факт спеки с actionstage="doc", новый PROP. Привычку держит чекбокс в шаблоне pull request'а: «документация: обновлена / долг записан / не нужна».

08Если документация в том же коммите невозможна (большая страница, ждёт решения), коммит несёт строку долга: запись в BACKLOG.md с префиксом docs: и severity, с адресом изменения. Панель считает строки долга и печатает дрейф числом; ни то ни другое не роняет сборку — при десяти релизах в день замок между продуктом и документацией недопустим, дрейф между сверками принят как риск (§2.4). Месячная петля дренирует долг, полная сверка добирает всё, что осталось. Долг без адреса не принимается.

09Для правок только документации — путь короткий: правка → vibe doc check --style --examples --citations на затронутых страницах → коммит docs(vibevm-docs): …. Мелкая правка подчиняется дисциплине §6.

10Первое действие любой правки — git status и проверка живого конфликта писателей (журнал, J-005): две центральные сессии в одном дереве — стоп.

2.2 Недельная петля: малое ревью

11Порядок, буквально:

1. 12Дешёвая модель запускает vibe doc todo --format md и vibe doc check по всему пакету и кладёт отчёт в журнал недели. Центральная сессия читает отчёт, не сырые выводы.
2. Сортировка очереди: что чинится за пять минут — чинится сейчас (не больше пяти правок за петлю, иначе это не мелочь); что больше — становится строкой долга с severity; что спорно — вопрос владельцу одной строкой.
3. Сигналы недели (§5): вопросы людей и агентов, отставание адаптаций, страницы с аномальным поведением читателей. Каждый сигнал — либо правка, либо долг, либо «наблюдение без действия» с причиной.
4. Страница недели. Одна страница по кругу (порядок — reviews.toml); владелец или центральная сессия читает её вслух как читатель из STYLE.md §1. Спотыкание — правка или долг. Дата чтения — в reviews.toml.
5. Запись в журнал: что сделано, что отложено, что удивило. Мелкие правки публикуются патч-версией пакета документации раз в неделю (вопрос владельцу, §11).

2.3 Месячная петля: большое ревью

1. 13Метрики (§7) за месяц — таблица в отчёте; тренд важнее значения.
2. Аудит корпуса: каждая верхнеуровневая команда, каждое поле манифеста, каждый kind имеет страницу (сверка с derived); глоссарий — одно слово, одно значение (поиск синонимов по корпусу); лестница между страницами (термин впервые введён там, где его ищут); дубли и мёртвые страницы; уровни llms.txt укладываются в бюджеты токенов; выборка из десяти промптов прогоняется агентом (vibe doc check --prompts --sample 10, D-30) — красный ассерт → правка страницы или долг.
3. Аналитика: страницы с высоким выходом и коротким чтением — кандидаты на переписывание; запросы поиска без результата (когда поиск появится); принятые IndexNow, ошибки Search Console.
4. Адаптации: суммарное отставание; страницы, где отставание больше трёх ревизий, — в очередь адаптации.
5. Долг: BACKLOG.md строки docs: — каждая либо закрыта, либо получила атом, либо переоценена с причиной.
6. Стиль: тики, проскочившие за месяц (найдены при чтении), добавляются в списки линтера; ложные срабатывания линтера — правка правила.
7. Журнал → регламент: каждая запись месяца с пустым полем «→ регламент» получает решение; изменения регламента — правки этого документа (потом PROP) с датой и ссылкой на записи.
8. Чтение вслух трёх страниц владельцем: одна новая, одна самая посещаемая, одна самая старая по reviews.toml.
9. Релиз пакета документации минорной версией с changelog, собранным из журнала месяца (человеческий текст пишет центральная сессия).

2.4 Полная сверка: обещание команды, не замок

14Продукт выходит по десять раз в день и принимает по сто pull request'ов; документация между сверками дрейфует, и этот риск принят. Ни один технический гейт не связывает релиз продукта с документацией, и ничто не пытается измерить «сколько изменилось с прошлого раза» — такой меры нет по замыслу проекта (D-27). Вместо замка — две вещи: текущие пробелы измеряются (vibe doc todo печатает число команд, полей и обязательств без страницы, красных примеров и неразрешимых цитат; никогда не роняет сборку) и команда обещает себе полную сверку: раз в квартал и перед крупной вехой — мажорной версией, публичным анонсом, — не на каждый релиз.

15Порядок сверки, день–два:

1. 16Дешёвая модель собирает документацию против текущего релизного бинарника, не отладочного (J-001): vibe doc todo, vibe doc check со всеми флагами, все примеры и все промпты через агента (--prompts, D-30); отчёт — в журнал.
2. Центральная сессия закрывает пробелы: страницы для новых команд, полей и обязательств пишутся или получают долг с атомом; derived перегенерируются; примеры с изменившимся выводом обновляются как golden-тесты; неразрешимые цитаты чинятся.
3. Каждая страница перечитывается против текущего продукта — это и есть сверка, потому что устаревшую прозу машина не видит: рядом с текстом открыты --help и спека, коридоры переписываются там, где разошлись. Порядок — по reviews.toml, от самых давно не читанных. Страницы, до которых руки не дошли, остаются с прежней датой чтения — честно.
4. Адаптации перечитываются против источника; расхождение структуры (--translations) — ноль.
5. Пакет документации релизится версией, совместимой с текущим релизом продукта ([[documents]] version); сайт показывает её как latest; после публикации — curl корневых ссылок домена на /doc/sitemap.xml и /doc/llms.txt (J-004), IndexNow по изменённым адресам.
6. Отчёт сверки в журнал: пробелы до и после, число перечитанных и переписанных страниц, время. Ноль пробелов и все даты чтения не старше сверки — единственный гейт, и это гейт сверки, не релиза продукта.

2.5 Смена версии: псевдоистория для разработчиков документации

17Версия — контракт на поведение. Владелец поднимает номер осознанно, когда контракт изменился, и это единственный момент, когда машина считает «разницу между версиями» (D-27). Смысл механизма — не искать, что изменилось в файлах, а алгоритмически назвать страницы, которые надо обновить, чтобы LLM правила их, а не перечитывала всю документацию.

18Порядок, часы:

1. 19Владелец меняет номер версии продукта. Никакого технического гейта на этом шаге нет и не будет.
2. Дешёвая модель записывает снимок поверхности новой версии против текущего релизного бинарника: vibe doc surface --record <новая> → maintenance/surface/<новая>.json. Снимок старой версии уже лежит рядом — его записала последняя полная сверка или прошлая смена версии.
3. vibe doc diff <старая> <новая> печатает список: что изменилось в контракте (команда, флаг, поле, обязательство, схема) и какие страницы это цитируют, выводят или обязаны покрывать; у каждой страницы — причина. Пустой список — тоже ответ.
4. Центральная сессия обновляет только перечисленные страницы (и пишет новые для того, что появилось без страницы); остальное не трогается. То, что не успевает, — долг docs: с атомом.
5. Человеческий changelog между версиями для читателей пишется по выводу diff — руками, по STYLE.md; сам вывод diff наружу не публикуется.
6. Пакет документации выходит с новым [[documents]] version; сайт показывает его как latest для новой версии. Читатель видит номер и контракт, ничего из кухни.
7. Запись в журнал: сколько страниц назвал diff, сколько обновлено, время.

20Внутри версии тот же инструмент можно запустить как vibe doc diff <версия> now — подсказка полной сверке, какие страницы перечитать первыми. Это кухня: никаких следов на страницах, никаких меток для читателя (вопрос владельцу, VISION.md §10 п. 14).