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

**Explains:** [PROP-058](../common/PROP-058-documentation-maintenance.xml).

Документация дрейфует с первого дня после публикации. Продукт меняет команды и поля; читатели приносят вопросы, на которые страниц нет; мелкие правки, накопившись, ломают лестницу понятий и тон. Ни один из трёх процессов не останавливается сам. Значит, обновление — не «когда руки дойдут», а регламент с триггерами, дежурными, инструментами и гейтами.

Одно ограничение задано владельцем: продукт выходит по десять раз в день и принимает по сто pull request'ов, документация между проверками неизбежно дрейфует, и этот риск принят. Второе ограничение оттуда же: версия — контракт на поведение, а не набор файлов; внутри версии продукт меняется невидимо, десять релизов в день могут нести один номер, история переписывается, и отличить одну amend-версию от другой не может никто. Поэтому регламент не опирается ни на что, кроме номера версии, который владелец меняет осознанно: единственная «разница», которую считает машина, — разница между объявленными версиями по снимкам поверхности (§2.5), и она — внутренняя кухня разработчиков документации; читатель видит номер и контракт (`VISION.md`, D-27). Внутри версии всё сравнивается только с текущим состоянием. Регламент не ставит технических замков между релизом продукта и документацией. Он делает три вещи: измеряет дрейф, показывает его читателю и закрепляет обещание команды время от времени проводить полную сверку (§2.4).

Этот документ описывает регламент **до** того, как документация написана, чтобы кампания реализации сразу накапливала материал для него: каждая удача, неудача и находка кампании записывается в журнал с пометкой, какое правило регламента она подтверждает, меняет или создаёт. В фазе 6 регламент переписывается по журналу и дважды репетируется на свежей документации, прежде чем стать нормой.

Дрейф Как выглядит Что ловит уже по вижену Что добавляет регламент
**Продукт меняется** новая команда, флаг, поле манифеста, поведение; текст спеки изменился `rule` цитирует текущий текст спеки (D-14); `derived` регенерируется из текущего бинарника; примеры исполняются как golden-тесты; гейт покрытия видит команды, поля и обязательства без страницы очередь `vibe doc todo` (§3) как измеритель текущих пробелов, не замок; полная сверка по обещанию команды (§2.4); долг документации в `BACKLOG.md`. Устаревшую **прозу** машина не видит — её читает человек
**Мир меняется** вопросы без страницы; новый сценарий; агенты не находят ответ по якорю манифест страниц и гейт покрытия обязательств (D-14) сигналы использования (§5), очередь `vibe doc todo`, «страница недели»
**Текст стареет** лестница сломана вставками; термин появился без введения; тон поплыл; страницу не читали год линтер стиля (D-25) правило пяти правок (§6), возраст страницы в `reviews.toml`, чтение вслух, месячное ревью
Петля Триггер Кто Время Вход Выход Гейт
**Коммита** (§2.1) любой коммит в продукт или в документацию автор коммита; для прозы — центральная сессия минуты дифф документация в том же коммите или строка долга — привычка, не замок панель: внутренние проверки документации зелёные; дрейф и долг — числом, не красным
**Недельная** (§2.2) календарь, раз в неделю дежурная центральная сессия; механика — дешёвая модель; владелец читает одну страницу 30–60 минут `vibe doc todo`, сигналы недели до пяти мелких правок, долг рассортирован, страница недели прочитана, запись в журнал отчёт недели в журнале
**Месячная** (§2.3) календарь, раз в месяц центральная сессия с владельцем; код — Opus 5 полдня метрики §7, журнал месяца, аналитика до трёх переписанных страниц, изменения регламента, релиз пакета документации отчёт месяца; `reviews.toml` обновлён
**Полная сверка** (§2.4) обещание команды: раз в квартал и перед крупной вехой; не на каждый релиз центральная сессия с владельцем; механика — дешёвая модель; код — Opus 5 день–два `vibe doc todo` и `vibe doc check` против текущего продукта; весь корпус страниц пробелы покрытия к нулю, `derived` перегенерированы, примеры зелёные, все страницы и адаптации перечитаны против текущего продукта, даты чтения обновлены, снимок поверхности текущей версии записан, релиз пакета документации отчёт сверки; ноль пробелов и красных примеров на дату сверки; все страницы с датой чтения не старше сверки
**Смена версии** (§2.5) осознанное решение владельца поднять номер версии продукта разработчики документации: центральная сессия; механика — дешёвая модель часы `vibe doc diff <старая> <новая>` по снимкам поверхности обновлены только перечисленные страницы, снимок новой версии записан, changelog для читателей написан руками, пакет документации выходит с новым `[[documents]] version` все страницы из списка diff обновлены или получили долг с атомом; читателю не видно ничего, кроме номера

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

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

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

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

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

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

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

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

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

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

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

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

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

**`vibe doc todo`** — очередь сопровождения по **текущему** состоянию, без сравнений «с тех пор»: команды, поля манифеста и обязательства без страницы (гейт покрытия), красные примеры, неразрешимые цитаты, расхождения структуры адаптаций, возраст страниц по `reviews.toml` (старше 90 дней), строки долга из `BACKLOG.md`, статистика линтера; `--format md` для отчёта недели, `--format json` для метрик. Печатает числа, никогда не роняет сборку. **`vibe doc check`** — существующие проверки (D-14, D-25); флаг `--prompts` прогоняет промпты страниц сценариев через агента-исполнителя и проверяет ассерты (D-30) — дорого, поэтому не в панели: руками, в месячной петле выборкой, на сверке целиком. **`vibe doc surface --record <версия>`** — снимок поверхности продукта на объявленную версию: структурный JSON (команды и флаги из `--help`, поля манифеста и lock-файла, схемы, тексты фактов с `actionstage="doc"`, реестр форматов), не хэш; ключ — только номер версии, который назвал владелец. Лежит в `maintenance/surface/<версия>.json` пакета документации; сайт этот каталог не рендерит. **`vibe doc diff <старая> <новая>`** — разница двух снимков, переведённая в страницы: через граф цитат `rule`, источники `derived` и карту покрытия — «что изменилось → какие страницы обновить → почему». Только для разработчиков документации (§2.5). **`reviews.toml`** в пакете документации: страница → дата последнего чтения вслух и кто читал; порядок «страницы недели». Данные, не генерат и не история: дата говорит «когда читали», а не «против чего». **`JOURNAL.md`** — журнал (§4). В кампании — в папке вижена, с фазы 1 в зоне кампании; после кампании — в пакете документации. **`CHANGELOG.md`** пакета документации — что изменилось для читателя, по версиям; пишется из журнала, человеческим текстом. **`BACKLOG.md`** хоста — долг документации строками `docs:` с severity.

Одна таблица, только дописывается. Поля: дата; тип — `успех`, `неудача`, `находка`, `наблюдение`; стабильный идентификатор `J-NNN`; что случилось; свидетельство (команда, коммит, якорь, файл); **→ регламент** — какое правило это подтверждает, меняет или создаёт, либо «наблюдение без действия: причина».

Три закона журнала:

**Запись делается в том же атоме**, где случилось событие: красная проба, ложное срабатывание линтера, опровергнутое предсказание, обходной путь, удачный приём. Не «в конце недели по памяти». **Поле «→ регламент» не остаётся пустым** дольше месячной петли. **Правило без находки — гипотеза.** Каждое правило регламента ссылается на записи журнала, которые его породили; правило без ссылки помечается «гипотеза» и проверяется. Так находки кампании не теряются и не выдумываются: регламент растёт только из того, что случилось.
Источник Сигнал Куда попадает
Сборка неразрешимые цитаты, красные примеры, дыры покрытия, расхождения структуры адаптаций, статистика линтера `vibe doc todo`
Продукт новые команды, поля, обязательства и PROP без страницы — видны гейту покрытия как текущие пробелы, не как «изменения с тех пор» `vibe doc todo`, петля коммита
Владелец решение поднять номер версии продукта §2.5: `vibe doc diff`, список страниц к обновлению
Промпты красный ассерт при прогоне агентом; агент не понял промпт правка страницы или долг `docs:`; два падения подряд — переписывание
Люди вопросы в чате и issue, замечания владельца при чтении вслух долг `docs:` или правка
Агенты скилл `vibevm-docs` просит агента, не нашедшего ответ по якорю, записать вопрос строкой `docs-gap:` в `BACKLOG.md` проекта-потребителя; для хоста — в его `BACKLOG.md` недельная петля
Сайт просмотры, выходы, время чтения по страницам (Umami); поисковые запросы без результата, когда появится поиск; Search Console месячная петля
Журнал записи с пустым «→ регламент» месячная петля
Одна правка — один коммит `docs(vibevm-docs): …` с конкретным описанием. Якоря не меняются (R-06); `derived` руками не правится (R-03); число или имя поля в прозе — только с `rule` рядом (R-01). Вставленный термин вводится на месте (`STYLE.md` §2); линтер стиля зелёный на странице. **Правило пяти правок:** пятая мелкая правка одной страницы с последнего чтения вслух ставит страницу в очередь «страница недели» — накопленные заплатки ломают лестницу незаметно для каждого автора заплатки. Мелкая правка, которая тянет за собой другие страницы, — не мелкая: она становится долгом с атомом.
Метрика Как считать Куда должна идти
Пробелы на начало месяца число строк `vibe doc todo` по покрытию, примерам и цитатам к нулю
Возраст страниц медиана дней с последнего чтения по `reviews.toml` ниже 90
Отставание адаптаций сумма ревизий по всем страницам адаптации к нулю на полной сверке
Покрытие обязательств `vibe doc check --coverage` 100 процентов
Тики на тысячу слов линтер стиля по корпусу к нулю
Долг строки `docs:` в `BACKLOG.md` по severity P1 = 0
Находки → регламент записей за месяц / из них с решением все с решением
Дней с последней полной сверки по дате в `reviews.toml` не больше 90 при квартальной каденции

Восемь чисел, не больше; таблица в отчёте месяца, тренд рядом.

Ярус В петле коммита В недельной В месячной В полной сверке При смене версии
Владелец — читает страницу недели (по желанию) читает три страницы вслух; решает по регламенту назначает дату, принимает отчёт сверки поднимает номер; принимает changelog
Центральная сессия (Fable) правит прозу, если коммит её требует сортирует очередь, делает мелкие правки, пишет запись в журнал аудит корпуса, переписывание страниц, изменения регламента, changelog перечитывает страницы против текущего продукта, переписывает коридоры, закрывает пробелы новыми страницами обновляет страницы из списка diff, пишет changelog для читателей
Opus 5 High код инструментов — правки инструментов по находкам правки инструментов и генераторов `derived` правки `surface`/`diff` по находкам
Дешёвая модель — прогоняет `todo` и `check`, собирает отчёт собирает метрики и аналитику, машинный черновик адаптации прогоняет `todo`, `check` и примеры против текущего релиза, собирает отчёт; записывает снимок поверхности записывает снимок новой версии, прогоняет `diff`, собирает список

Регламент — не догма: он меняется по журналу в месячной петле (§2.3 п. 7). Каждое изменение — правка с датой и ссылками на записи `J-NNN`. Раз в квартал — вопрос владельцу: какие петли оказались лишними, какие метрики никто не смотрит, какие правила ни разу не сработали. Правило, не сработавшее за квартал, помечается «спящее» и выносится из чеклиста; правило без записи-основания — «гипотеза». Так регламент худеет, а не толстеет.

Что Где Когда
Норма петель, журнала, долга, гейта релиза PROP «documentation maintenance», следующий свободный номер после PROP-057 фаза 6, атом A6.4
Страница для мейнтейнера «How this manual is maintained» (аудитория `dev`) пакет `vibevm-docs` A6.4
Чеклисты `maintenance/weekly.md`, `monthly.md`, `release.md` пакет `vibevm-docs` A6.4
`reviews.toml`, `JOURNAL.md`, `CHANGELOG.md` пакет `vibevm-docs` A6.1, A6.4
`vibe doc todo` `vibe-doc`, CLI фаза 2, A2.27
`vibe doc surface`, `vibe doc diff`, каталог `maintenance/surface/` `vibe-doc`, CLI; пакет документации фаза 2, A2.26; первый снимок — A6.5
Календарь полной сверки, чеклист `maintenance/reconcile.md` пакет документации; даты чтения в `reviews.toml` A6.5
Регламент как flow-пакет для чужих проектов с doc-пакетами `org.vibevm.world/docs-maintenance` вторая волна: когда второй проект захочет тот же ритуал
Каденции: неделя и месяц, как здесь, или две недели и квартал. Дежурный по недельной петле: владелец с центральной сессией или только сессия с отчётом владельцу. Публиковать мелкие правки патч-версией еженедельно или копить до месячного релиза. Сигнал от агентов `docs-gap:` в `BACKLOG.md` проектов-потребителей — уместно ли писать в чужой файл по воле скилла, или только предлагать. Каденция полной сверки: раз в квартал, перед крупной вехой, или и то и другое. Рекомендация — и то и другое, с правом владельца отложить. Примеры с `expect` — единственная техническая связка продукта с документацией (golden-тесты в панели): оставить как тесты или тоже перевести в измеритель. Рекомендация — оставить: они правятся как любой golden-файл и стоят минуты. Псевдоистория версий (§2.5): где хранить снимки и разрешить ли внутренний `vibe doc diff <версия> now` как подсказку сверке (`VISION.md` §10 п. 14).