Как сопровождается это руководство
01Это руководство — пакет, и оно расходится с продуктом, как любой код на следующий день после выпуска: продукт добавляет флаг, читатель задаёт вопрос, на который не отвечает ни одна страница, абзац, залатанный пять раз, перестаёт читаться. Само по себе это не останавливается, поэтому руководство держится на небольшом наборе петель с именованными триггерами, очереди, которая измеряет пробелы, и журнале, куда записывается, что нашла каждая петля. Эта страница говорит, что это за петли, что их запускает и что вы должны, когда меняете продукт.
02
Нет замка между продуктом и руководством
03Продукт выпускается много раз в день и вливает много пул-реквестов; руководство не может следовать за каждым, и это принято. Никакие ворота не держат выпуск продукта ради документации, и ни один шаг панели самопроверки не краснеет оттого, что продукт ушёл вперёд страницы. Панель красная, только когда руководство сломано изнутри: пример, чей вывод изменился, блок derived, который больше не собирается, цитата, чей якорь исчез.
04 spec: Only internal breakage of the documentation…
Only internal breakage of the documentation is red in the panel: a red example, aderivedblock that no longer builds, a vanished citation anchor, a page the pivot cannot read. Drift and debt are printed as numbers (PROP-057##OBS-NO-RELEASE-LOCK; J-074, J-088).
05 spec: The owner set the frame…
The owner set the frame on 2026-09-10 (J-013, J-014): the product ships up to ten times a day and merges up to a hundred pull requests, documentation drifts between checks and that risk is accepted; a version is a contract on behaviour, not a set of files; no technical lock binds a product release to the documentation. The regulation therefore measures drift, shows it to the reader and keeps a team promise to reconcile fully on a calendar.
06Вместо замка есть мера. Команда очереди печатает пробелы числами: обязательства, о которых не говорит ни одна страница, примеры, которые больше не совпадают, цитаты, которые не разрешаются, страницы, которые никто не читал вслух, строки долга, счёт линтера. Она никогда не валит сборку и отличает «ничего не найдено» от «никто не смотрел»: секция, которая не запускалась, печатает null, а не ноль.
07 spec: vibe doc todo is the maintenance…
vibe doc todois the maintenance queue by the current state, with no «since» comparison: commands, fields and obligations without a page, red examples, unresolvable citations, structural divergences of adaptations, page age byreviews.toml,docs:debt lines fromBACKLOG.md, and the linter's statistics;--format mdfor the weekly report,--format jsonfor the metrics. It prints numbers and never fails a build; every section carriesmeasured, and a metric the run could not take isnull, never0— «no findings» and «nobody looked» must print differently (J-099). Examples run only with--examples, because a sandbox per fixture costs minutes and the weekly reading should not.
Что вы должны, когда меняете продукт
08Изменение, которое видит пользователь, несёт свою страницу в том же коммите: новая или изменённая команда или флаг, поле манифеста или лок-файла, формат отчёта, сообщение об ошибке с адресом, факт спецификации, помеченный для документации, новая спецификация. Руководства разработчика уже работают так, а шаблон пул-реквеста держит привычку одной галочкой: документация обновлена, долг записан или не нужна.
09 spec: The commit loop
The commit loop. A product change a user can see — a new or changed command, flag, manifest or lock-file field, report format, error message with an address, a spec fact markedactionstage="doc", a new PROP — carries its documentation in the same commit, asDEV-GUIDE.mdandRUNTIME-GUIDE.mdalready do; when that is impossible, the commit carries a debt line (§8). This is a habit kept by the pull-request checkbox «documentation: updated / debt recorded / not needed», never a lock (J-013; PROP-057##OBS-NO-RELEASE-LOCK).
10Когда страница не может прийти вместе с коммитом, коммит приносит вместо неё строку долга: строку в BACKLOG.md хоста с префиксом docs:, серьёзностью и адресом изменения. Строка без адреса не принимается. Месячная петля осушает список.
11 spec: A debt line is a row…
A debt line is a row of the host'sBACKLOG.mdprefixeddocs:, with a severity P1–P3 and the address of the change it owes a page to; a line without an address is not accepted. The monthly loop drains the list; the full reconciliation takes what is left (J-064: «needs an author» was closed by a rule written into a script, not row by row).
12Перед любой правкой посмотрите git status и убедитесь, что никакая другая сессия не пишет в том же дереве. В дереве, разделённом с параллельными воркерами, коммитьте только с явными путями, чтобы ничьи проиндексированные файлы не уехали внутри вашего коммита.
13 spec: The first action of any edit…
The first action of any edit isgit statusand a check for a live conflicting writer; two central sessions in one tree stop (J-005). In a tree shared with parallel workers, commits name their paths explicitly —git commit -m … -- <paths>, never a bare commit orgit add -A(J-072, J-090).
Петли
15Недельная петля занимает меньше часа. Дешёвая модель прогоняет очередь и проверки по всему пакету и складывает отчёт. Сопровождающий разбирает очередь: что занимает пять минут, чинится сейчас, не больше пяти правок за петлю; что больше, становится строкой долга; что спорно, становится однострочным вопросом владельцу. Одна страница читается вслух, следующая по ротации чтения, и каждая запинка становится правкой или строкой долга. Запись в журнале закрывает петлю.
16 spec: The weekly loop
The weekly loop, 30–60 minutes, in this order: a cheap model runsvibe doc todo --format mdandvibe doc checkover the whole package and files the report; the central session sorts the queue — what is fixed in five minutes is fixed now, at most five edits per loop, what is bigger becomes a debt line with severity, what is disputable becomes a one-line question to the owner; the signals of the week (§6) each become an edit, a debt line or «observation without action: reason»; the page of the week — the next page alongreviews.toml— is read aloud by the owner or the central session as the reader of the style law, every stumble becomes an edit or a debt line, and the reading date goes intoreviews.toml; a journal entry closes the loop with what was done, deferred and surprising (J-112: rehearsed 2026-09-12 in 25 minutes).
17Месячная петля занимает полдня с владельцем: восемь метрик с их трендом, аудит корпуса, осушенный список долга, списки линтера, пополненные тиками, которые проскочили мимо него, каждая запись журнала с её решением, три страницы, прочитанные вслух, и публикация под тем же номером с датированной записью в списке изменений, написанной руками.
18 spec: The monthly loop
The monthly loop, half a day, with the owner: the eight metrics of §9 as a table with their trend; an audit of the corpus — every top-level command, manifest field and kind has a page, the glossary keeps one word to one meaning, terms are introduced where readers look for them, duplicates and dead pages, thellmstiers within their budgets, a sample of ten prompts run through an agent; the analytics of the site; the lag of adaptations; the drain ofdocs:debt — every line closed, given an atom or re-rated with a reason; the ticks that slipped past the linter go into its lists and false positives fix the rule; every journal entry of the month still owing a decision gets one, and the regulation is amended with a date and the entries; the owner reads three pages aloud — one new, one most visited, one oldest byreviews.toml; the documentation package is published again under the same number, with a dated entry in the changelog written by hand from the journal, for as long as PROP-057##VERSION-OVERWRITE-POLICYholds (hypothesis until the first monthly rehearsal, A6.3).
19Полная сверка — обещание, которое команда даёт себе, раз в квартал и перед крупной вехой: руководство сверяется с текущим бинарником выпуска, каждая страница перечитывается против продукта с открытыми рядом текстом справки и спецификацией, адаптации перечитываются против своих источников, и пакет выпускает версию, совпадающую с выпуском. Единственные её ворота — её собственные: ноль пробелов и ни одной даты чтения старше сверки.
20 spec: The full reconciliation
The full reconciliation, a day or two, once a quarter and before a major milestone — a promise the team makes itself, never a release condition: a cheap model builds the documentation against the current release binary, not a debug one (J-001), runsvibe doc todoandvibe doc checkwith every flag, all examples and all prompts through an agent, and files the report; the central session closes the gaps — new pages or debt with an atom, regeneratedderived, updated golden examples, repaired citations; every page is reread against the current product with--helpand the spec open beside it, in the order ofreviews.tomlfrom the least recently read, and each page reread gets the date; adaptations are reread against their sources; the package ships a version compatible with the current product release, the site shows it aslatest, and after publication the root links of the domain to/doc/sitemap.xmland/doc/llms.txtare checked withcurl(J-004); the report goes to the journal with the gaps before and after, the pages reread and rewritten, and the time. The only gate is the reconciliation's own: zero gaps and no reading date older than the reconciliation (hypothesis until the first reconciliation, A6.5).
21Смена версии начинается, только когда владелец поднимает версию продукта. Для новой версии записывается снимок поверхности продукта, разница двух снимков называет страницы для обновления с причиной для каждой, и трогаются только эти страницы. Читатели видят номер версии и список изменений, никогда не диф.
22 spec: The version change
The version change, hours: the owner bumps the product version — no gate on that step; a cheap model records the surface snapshot of the new version against the current release binary,vibe doc surface --record <new>, beside the snapshot the last reconciliation or version change left — one snapshot while the number stands still, overwritten in place byvibe doc surface --record 1.0.0, for as long as PROP-057##VERSION-OVERWRITE-POLICYholds;vibe doc diff <old> <new>names the pages to update with a reason each — an empty list is also an answer; the central session updates only the pages named and writes new ones for what appeared without a page, the rest becomesdocs:debt with an atom; a human changelog between versions is written from the diff by hand and the diff itself is never published; the package is published again under that same number, with a dated entry in the changelog and the new[[documents]] version, and the site shows it aslatest; the journal records how many pages the diff named, how many were updated, and the time (J-017, J-099; PROP-057##OBS-SURFACE-SNAPSHOTS,##OBS-NOTHING-LEAKS).
23Пока владелец не скажет иначе, каждый номер, который публикует этот репозиторий, остаётся 1.0.0, а изменение выходит под тем же номером на месте: сайт показывает текущее содержимое номера, список изменений ведётся по датам, а проект, закрепивший номер, хранит байты, которые записал его лок-файл.
24 spec: Until the owner decides otherwise (ruling…
Until the owner decides otherwise (ruling 2026-09-14), every package this repository publishes carries the number1.0.0, and a change is published under the same number in place: the registry keeps no past publication, the site shows the current content of the number, and the changelog records what changed by date rather than by a new number. A consumer who pinned the number keeps the bytes the lock file recorded, and a fresh install gets the current ones (##SITE-VERSION-SHOWS-CURRENT, PROP-002##PUBLISH-MUTABLE-VERSIONS).
Что пакет держит для этого
25maintenance/reviews.toml записывает, когда каждую страницу в последний раз читали вслух и кто. Он пишется руками, держит дату и читателя и ничего не знает о ревизиях или хешах: факт, который он хранит, в том, что кто-то сел со страницей в такой-то день. Страница без строки никогда не читалась вслух, и очередь так и говорит. Порядок строк — ротация чтения.
26 spec: maintenance/reviews.toml records when each page was…
maintenance/reviews.toml records when each page was last read aloud and by whom, and the date of the last full reconciliation; the order of its rows is the reading rota. It is authored data, never a generated record: a date and a reader, never a revision, a hash or «checked against». A page with no row has never been read aloud, and the queue says exactly that. The reader is named by a name people recognise or by a role such as «central session», never by the name of a model (J-112).
27JOURNAL.md — журнал петель. Запись пишется в том атоме, где случилось событие, никогда в конце недели по памяти; она называет улику и правило, которое подтверждает, меняет или создаёт. Правило регламента, которого не породила ни одна запись, — гипотеза, пока петля его не подтвердит.
28 spec: Law one
Law one. The entry is written in the same atom where the event happened — a red probe, a false positive of the linter, a refuted prediction, a workaround, a trick that worked — never «at the end of the week from memory» (J-046, J-063, J-066: three entries that would have been lost a day later).
29CHANGELOG.md говорит, что изменилось для читателя, по версиям, простым текстом. Чеклисты под maintenance/ — это петли в виде списков: weekly.md, monthly.md, release.md, а после первой сверки reconcile.md, написанный по прожитому.
30 spec: The package carries the checklists…
The package carries the checklists the loops are run by —maintenance/weekly.md,maintenance/monthly.md,maintenance/release.md, and after the first reconciliationmaintenance/reconcile.mdwritten from what was lived; a checklist item without a rule here is a hypothesis.
Как менять инструменты
31Очередь, проверки, снимки поверхности и генераторы — код, и кампания, которая их построила, оставила правила для всякого, кто их меняет. Два кусаются первыми: никогда не останавливайте процесс, который не вы запустили, даже чтобы освободить бинарник, нужный сборке, и никогда не снимайте измерения «до и после», пока другой пакет задач перегенерирует код в том же дереве.
32 spec: A worker never stops a process…
A worker never stops a process it did not start; a busy binary is waited for or built into a private target directory, and a worker that flips the features of the shared binary returns it to the panel's state or says it could not (J-105, J-110).
33 spec: Before/after measurements are taken one…
Before/after measurements are taken one at a time and with no other packet's codegen in the tree; a test that reads generated code is not measured during parallel work (J-101).
34Шаг, который читает вывод vibe doc build, прогоняется хотя бы раз по настоящему руководству, прежде чем его закоммитят, а число, записанное в задачу, — догадка, пока его не измерили на собранном выводе. Оба правила существуют потому, что фикстуры были зелёными, пока настоящий вывод терял две проекции из трёх, а политика ждала два встроенных скрипта там, где вывод нёс сорок семь.
35 spec: A step over the output…
A step over the output of vibe doc build runs at least once over the real manual before it is committed, and a builder runs once over the real registry: fixtures did not catch a copy step that lost two projections of three, a shelf that stayed empty, or a table that lost its first row (J-097, J-108).
Особые случаи и правила
37Маленькая правка — один коммит с конкретным описанием; пятая маленькая правка страницы с тех пор, как её в последний раз читали вслух, отправляет страницу в начало ротации чтения. Маленькая правка, которая тянет за собой другие страницы, не маленькая и становится строкой долга с атомом.
38 spec: One edit is one commit docs(vibevm-docs)…
One edit is one commit docs(vibevm-docs): … with a concrete description, so the reading rota and the rule of five can count them (J-112: five edits, five commits).
39 spec: A small edit that pulls other…
A small edit that pulls other pages after it is not small: it becomes a debt line with an atom (J-062: seven pages described a layout vibe init does not create, and the fix was an atom, not a patch).
40Журнал поставляется с пакетом. Поэтому запись не называет ни приватной инфраструктуры, ни неподтверждённого дефекта соседнего продукта, ни пути на чьей-то машине; над ней работают те же ворота, что стерегут записи кампании.
41 spec: The journal ships with the package…
The journal ships with the package, so an entry names no private infrastructure, no unconfirmed defect of a neighbouring product, no user-local identifier and no temporary path; the campaign-side gate that checks those patterns runs over the package journal before every commit that touches it (J-046, J-111).
42Каденции, кто дежурит по недельной петле, выходят ли маленькие правки еженедельно или ежемесячно и может ли агент писать строку docs-gap: в бэклог проекта — открытые вопросы владельца; до его слова петли работают, как написано здесь, а навык (skill) только предлагает.
43 spec: Open to the owner: the cadences…
Open to the owner: the cadences — week and month as written, or two weeks and a quarter; who is on duty for the weekly loop — the owner with the central session, or the session alone with a report; whether small edits ship as a patch version weekly or accumulate to the monthly release.