Текст в пакете полезен агенту, только если у каждого правила в нём есть адрес. Эта страница показывает форму такого текста: именованные разделы, одна мысль на единицу, статус на каждой и адрес, который после публикации не меняется никогда.
Человек и агент делят один репозиторий и ничего больше: ни коридора, ни общей памяти, ни интонации. Дерево [спецификаций](../glossary/index.xml#specification) — единственный канал между ними, а канал работает, когда на сообщение можно указать. «Поправь число повторов» отправляет агента гадать; «поправь `spec://org.acme/notes-flow/flows/notes/PROTOCOL#RETRY-COUNT`» отправляет его к одной строке. Второе стоит около двадцати токенов; первое стоит сотни и может попасть не в то правило.
`spec://<group>/<name>[@<version>]/<path>/<document>#<anchor>`: [координата](../glossary/index.xml#coordinate) пакета, необязательная версия, путь документа внутри `vibevm/vibespecs/` без расширения и [якорь](../glossary/index.xml#anchor). Версия — удобство, а не обязанность: без неё адрес разрешается по самой свежей установленной версии. Якоря — это идентификаторы разделов и [фактов](../glossary/index.xml#fact) в одном адресном пространстве, так что правило цитируется одинаково, будь оно разделом или одним предложением.
Единица — один заголовок с якорем и текст под ним до следующего заголовка; она несёт одно решение или одно правило, понятна сама по себе и помещается на страницу. Если единице нужно «а ещё», это две единицы. Контрактные утверждения используют MUST, SHOULD и MAY; читатель никогда не должен гадать, обязывает ли предложение. Проверяемые утверждения стоят вне блоков кода, потому что у блока нет якоря, а инструкция внутри него не проверена по построению.
Спецификация пишется в Markdown или на XML-диалекте проекта, и обе формы разбираются в одну модель документа. В XML раздел — элемент, названный по своему якорю, `<retry-policy title="3. Повторы">`. Правило — элемент, названный по своему идентификатору, с атрибутом `fact="true"` и статусом. В Markdown то же правило — абзац, который открывается `@fact:RETRY-COUNT` и закрывается `@status:spec/done`. Инструмент, который ничего не знает о вашем словаре, всё равно находит каждое правило одной проверкой атрибута, а конвертер переводит одну форму в другую, сообщая обо всём, что не пережило бы обратный путь.
Статус на каждой единице говорит, где она стоит: `spec/done` для устоявшегося правила, `impl/done`, когда оно уже воплощено в коде, `spec/work` для черновика. Два регистра идентификаторов несут сигнал бесплатно: идентификатор в верхнем регистре помечает правило с обязывающим весом, в нижнем — вводную или заметку.
`vibe refactor convert-source --to xml` или `--to markdown` конвертирует файлы или целые папки, пропуская дерево зависимостей и сгенерированные файлы. Он пишет соседнюю форму и удаляет оригинал одним действием, так что дерево никогда не держит обе формы одного документа. Перед записью он конвертирует результат обратно и сравнивает: побайтно совпавший обратный путь конвертируется молча, а потеря комментариев или раскладки отвергается с описанием по каждому файлу, пока вы не подтвердите или не передадите `--force`. Изменение смысла отвергается всегда, потому что это дефект конвертера, а не вашего файла. `--dry-run` сообщает о каждом файле и ничего не пишет.
Спецификация может подтянуть другую по адресу. `#use spec://…` подтягивает весь раздел верхнего уровня, содержащий адресованный узел, но не его соседей; `#embed` вклеивает ровно адресованный узел, не больше. Слияние по умолчанию — `:add`, так что текст интерфейса не нужно повторять, чтобы он попал в результат. Каждый файл, который называет директива, должен быть объявлен в [манифесте](../glossary/index.xml#manifest) пакета. Циклы законны в слое контрактов и запрещены между телами исходников, и именно это гарантирует, что сборка всегда заканчивается.
В прозе, которую читает агент, `@spec://…` с собакой обязателен: агент читает его на месте, один раз, при первой встрече, а компилятор никогда его не вклеивает. Голый `spec://…` остаётся на усмотрение агента.
После публикации якорь неизменяем. Переименование раздела или правила оставляет на старом якоре надгробие, указывающее на новый, так что ссылка, написанная год назад, всё ещё попадает куда надо. Перемещение файлов адреса тоже не меняет: адрес логический, путь — физика.
Сгенерированный файл никогда не цель цитаты: цитируйте исходный документ, а не скомпилированную [стартовую полосу](../glossary/index.xml#boot-lane).
`vibe facts check` проверяет разметку спецификаций пакета; `vibe check` проверяет пакет целиком; обе запускаются перед публикацией.
Код тоже может цитировать спецификации, атрибутом на элементе, который воплощает правило, и тогда карта отвечает, какой код стоит за каким правилом, в обе стороны; эту карту объясняют страницы об архитектуре этого руководства.