Продвинутые Markdown и XML

Что понадобится

Почему всё становится XML

03В проекте, который об этом просит, каждый текст, принесённый пакетом, ложится на диск как XML, в какой бы форме его ни написал автор. Эти тексты — спецификации: правила, которые пакет задаёт агентам, работающим под ним; а причина конверсии — читатель. Модель, которая читает <TESTS-FIRST fact="true" status="spec/done">, знает, где правило начинается, где кончается, как называется и в каком оно состоянии, не угадывая по вёрстке. Проза заставляет модель выводить все четыре ответа самой.

04Измерения согласны с интуицией. В эталонном исследовании Юань Суй с коллегами дали GPT-3.5 и GPT-4 одни и те же таблицы, записанные шестью способами: от простого текста с разделителями до CSV, JSON, XML, HTML и Markdown (WSDM 2024). На семи видах вопросов разметка, называющая свои части, обошла тот же текст в прозе. Лучше всех оказался HTML — на 6,76 процента по цифре самой статьи. В одной задаче, где нужно сказать, где начинаются и кончаются части таблицы, XML набрал 96,00 процента против 93,00 у простого текста и 92,33 у Markdown. Исследование про таблицы, и ровно до этого места страница его и доводит.

05Совет производителя говорит то же с другой стороны. Руководство Anthropic по промптам для Claude — рекомендация, а не исследование — советует оборачивать каждый вид содержимого в свой XML-тег, чтобы модель разбирала длинный промпт без двусмысленности (руководство). Олег Чирухин, автор VibeVM, обнаружил это на собственной практике раньше, чем об этом сказала хоть одна опубликованная работа. Цель xml — форма, в которой живут проекты этого руководства, и та, которую спецификация называет будущей основной.

07Имена значат не меньше скобок. Раздел становится элементом, названным по себе самому, <tests-first title="Tests before fixes">. Правило становится элементом, названным по своему идентификатору, с одним опознавательным атрибутом, fact="true", так что читатель, ничего не знающий о вашем словаре, находит каждое правило одной проверкой. Первый читатель этого диалекта — агент, а тегу, который говорит, что в нём лежит, легенда не нужна.

10Одно предостережение для тех, кто обучает модели. Свидетельства выше — про текст, который модель читает. Для текста, который модель пишет, всё наоборот: принуждение ответа к JSON, XML или YAML может стоить качества рассуждений (Тэм с коллегами, EMNLP 2024). VibeVM задаёт форму тому, что агент читает, и никогда — тому, что он отвечает, так что этот результат его не касается.

Markdown и XML: одна модель под капотом

11Под капотом две формы — одна сущность. Каждый документ, Markdown или XML, разбирается в одно дерево: заголовок, статус и разделы, вложенные по глубине заголовков. Внутри разделов лежат абзацы, списки, таблицы, блоки кода и цитаты, и некоторые из них несут факт — одно именованное правило со статусом. vibe никогда не переписывает текст Markdown в текст XML. Он разбирает в дерево и печатает из него, в любую сторону.

13Авторы компиляторов называют такое дерево промежуточным представлением, IR: единственная форма, в которую разбирает каждый фронтенд и из которой печатает каждый бэкенд. Компилятору для трёх языков и четырёх процессоров нужны три фронтенда и четыре бэкенда, а не двенадцать переводчиков, и правило, один раз сформулированное о дереве, действует для всех языков. У VibeVM та же форма: два фронтенда и два бэкенда, Markdown и XML с каждой стороны.

15Дерево нужно ему по тем же двум причинам. Без него каждой паре форм понадобился бы свой конвертер, а конвертеры расходятся. Обзор кода в 2026 году нашёл внутри vibe четыре читателя Markdown, каждый со своим чуть иным диалектом: болезнь, от которой одно общее дерево и должно лечить. И каждый инструмент, читающий спецификацию, читает XML через то же дерево: проверка фактов, компилятор, который собирает список чтения агента, маршрутизатор, который разрешает адрес. Поэтому документ в XML и его двойник в Markdown дают каждому инструменту один и тот же ответ.

17У дерева есть будущее за пределами конверсии. Компилятор называет его уровни — от текста одного документа до всего достижимого замыкания проекта, — и плагин компилятора может их читать и переписывать. Агент с длинным горизонтом когда-нибудь сможет планировать поверх этого замыкания: не стена текста, а граф именованных единиц с адресами. Это направление, а не возможность, которую можно запустить сегодня. И сам VibeVM — не агент. Он никогда не читает ваши правила, чтобы по ним действовать; он готовит текст, дерево и адреса для того агента, которого запускаете вы.

20Вывод для вас прост. Пишите спецификации своих пакетов в Markdown — в форме, с которой уже справляются ваш редактор и ваши рецензенты. Каждое свойство формы XML придёт само: именованные элементы, факты, которые проверяет машина, адрес у каждого правила. Шаги ниже делают ровно это и в конце это доказывают.

Шаг 1: проект, который материализуется в XML

211. Создайте проект в пустой папке, как на странице Создать первый проект. Имя станет именем папки:

vibe init review-lab

Initializing project `review-lab` in `review-lab`
  ✓ created  vibevm/vibespecs/boot/00-core.md
  ✓ created  vibevm/vibespecs/boot/90-user.md
  ✓ created  vibe.toml
  ✓ created  vibe.lock
  ✓ created  .vibe/.gitignore
  ✓ created  .gitignore
  ✓ created  vibevm/vibespecs/boot/INDEX.md
  ✓ created  CLAUDE.md
  ✓ created  AGENTS.md
  ✓ created  GEMINI.md

Done. Project `review-lab`: 10 files created, 0 kept.

Next:
  • edit vibevm/vibespecs/boot/00-core.md and vibevm/vibespecs/common as your project takes shape
  • install packages with `vibe install <kind>:<name>` (e.g. flow:wal)

232. Откройте review-lab/vibe.toml, манифест проекта, и добавьте одну строку под [project]:

[project]
spec_format = "xml"
name = "review-lab"

253. Дальше работайте внутри папки: cd review-lab.

26Эта строка решает, в какой форме ляжет каждый текст, который приносит пакет. С xml vibe конвертирует то, что автор написал в Markdown, пока копирует пакет в проект, а XML копирует как есть. Ваши собственные файлы не конвертируются никогда. Без этой строки каждый файл сохраняет форму, в которой его написал автор.

Шаг 2: создать заготовку пакета

291. Добавьте в проект пакет. Это flow, пакет рабочих правил для агента, и он просит формат normal, смысл которого объясняет шаг 4:

vibe init package org.acme/review --kind flow --format normal

Creating package `org.acme/review` in `<TMP>/work/review-lab`
  ✓ created  vibevm/vibepacks/org.acme/review/v0.1.0/vibe.toml
  ✓ created  vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/boot/10-flow-review.md
  ✓ created  vibevm/vibepacks/org.acme/review/v0.1.0/README.md
  • kept     vibevm/vibespecs/boot/INDEX.md (regenerated)
  • kept     CLAUDE.md (regenerated)
  • kept     AGENTS.md (regenerated)
  • kept     GEMINI.md (regenerated)

Done. Project `org.acme/review`: 3 files created, 4 kept.

Next:
  • edit vibevm/vibespecs/boot/00-core.md and vibevm/vibespecs/common as your project takes shape
  • install packages with `vibe install <kind>:<name>` (e.g. flow:wal)

312. Откройте манифест, который написала заготовка:

cat vibevm/vibepacks/org.acme/review/v0.1.0/vibe.toml

[package]
group = "org.acme"
name = "review"
kind = "flow"
version = "0.1.0"
epoch = 1
authors = ["vibevm docs fixtures"]
license = "UPL-1.0"
description = ""
format = "normal"

[boot_snippet]
source = "vibevm/vibespecs/boot/10-flow-review.md"
category = "flow"
link = "dynamic"

333. Измените две строки: дайте пакету description и поставьте link = "static". Конец файла станет таким:

description = "The team's code review rules, as a contract with its reasons."
format = "normal"

[boot_snippet]
source = "vibevm/vibespecs/boot/10-flow-review.md"
category = "flow"
link = "static"

35Тип связи (link type) говорит, как текст пакета доходит до агента. При static vibe компилирует текст в тот единственный файл, который агент читает первым, целиком, в начале каждой сессии. При dynamic, выборе заготовки, он перечисляет файл, чтобы агент открыл его сам. Эта страница берёт static, чтобы вы увидели компилятор за работой.

Шаг 3: якоря и факты, в Markdown

38Пакету нужны два документа. Первый — заметка, которую агент читает в начале сессии, стартовый фрагмент (boot snippet) пакета. Второй — контракт: сами правила, каждое со своим адресом.

391. Замените заметку заготовки, vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/boot/10-flow-review.md, на эту:

# Review flow

Before you open a change for review, hold it to the review rules. This
note pulls the rules in; each rule is one fact with an address, and the
reasons follow the rules. Cite a rule by its address, for example
`spec://org.acme/review/contract/REVIEW#ONE-IDEA`.

#use spec://org.acme/review/contract/REVIEW#root

41Строка, начинающаяся с #use, — директива: инструкция компилятору, а не проза. Она втягивает контракт перед заметкой, так что агент встречает правила раньше заметки, которая на них ссылается. Файлы этой страницы написаны по-английски, как и вывод команд, чтобы примеры совпадали с тем, что вы увидите у себя.

422. Создайте vibevm/vibespecs/contract/REVIEW.md в том же пакете:

# Review rules {#root}

<status stage="spec" state="done"/>

The rules a reviewer holds every change to. Each rule is one anchored
fact with a status.

## One idea per change {#one-idea}

@fact:ONE-IDEA A change under review carries one idea, named in its first line. @status:spec/done

## Tests before fixes {#tests-first}

@fact:TESTS-FIRST A change that alters behaviour carries a test that fails without it. @status:spec/done

44Прочитайте файл так, как читает машина. Заголовок несёт якорь в фигурных скобках, {#one-idea}: имя, которым пользуется ссылка, часть адреса после #. Абзац, который открывается @fact:ONE-IDEA, — факт, одно заякоренное правило со статусом. @status:spec/done в его конце говорит, что правило решено и ещё не построено. Элемент <status> под заголовком — тот же маркер для всего документа. Якоря заголовков и идентификаторы фактов делят одно пространство имён, поэтому ни один не повторяется в документе дважды.

49Регистр идентификатора — сигнал. Идентификаторы в верхнем регистре помечают правила с обязывающей силой; в нижнем — заголовки, вводные и заметки. Адрес первого правила — spec://org.acme/review/contract/REVIEW#ONE-IDEA. Он складывается из координаты пакета, пути документа под vibevm/vibespecs/ без расширения и якоря. Адрес не меняется, когда файл меняет форму.

523. Проверьте разметку пакета:

vibe facts check --path vibevm/vibepacks/org.acme/review/v0.1.0

progress check: clean (2 files, 0 warning(s))

54Проверка читает каждый документ под vibevm/vibespecs/ пакета. Маркер на абзаце без якоря и идентификатор, определённый дважды, — ошибки, которые называют строку.

554. Установите пакет в его собственный проект:

vibe install org.acme/review --assume-yes

Resolving 1 root package…

Materialising 1 package into vibedeps/:
  org.acme/review@0.1.0

closure diff:
  → + org.acme/review@0.1.0 (root-edge)
  → lane vibevm/vibespecs/boot/INDEX.md: 737 -> 781 B
  → lane vibevm/vibespecs/boot/STATIC.xml: absent -> 2809 B

Materialised 1 package into vibedeps/; regenerated boot artifacts for 1 node(s).

57Установка копирует пакет в vibevm/vibedeps/, конвертируя оба документа в XML. Она же компилирует стартовую полосу (boot lane) — упорядоченный список файлов, которые агент читает в начале сессии. Последние две строки диффа — это она: в INDEX.md появилась строка с именем скомпилированного файла, а STATIC.xml возник.

585. Откройте контракт таким, каким его прочитает агент:

cat vibevm/vibedeps/org.acme.review/0.1.0/vibevm/vibespecs/contract/REVIEW.xml

<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="root">Review rules</title>
  <status stage="spec" state="done"/>
  <p>The rules a reviewer holds every change to. Each rule is one anchored
fact with a status.</p>
  <one-idea title="One idea per change">
    <p><ONE-IDEA fact="true" status="spec/done">A change under review carries one idea, named in its first line.</ONE-IDEA></p>
  </one-idea>
  <tests-first title="Tests before fixes">
    <p><TESTS-FIRST fact="true" status="spec/done">A change that alters behaviour carries a test that fails without it.</TESTS-FIRST></p>
  </tests-first>
</spec>

60Каждая часть названа по себе самой. Раздел {#one-idea} стал элементом <one-idea> с заголовком в атрибуте. Факт стал <ONE-IDEA fact="true" status="spec/done">. Префикс @fact: и суффикс @status: из текста исчезли: они были написанием, а дерево хранит только смысл. Строчная разметка Markdown — обратные кавычки, ссылки — едет внутри текста без изменений.

Заголовочный файл и его реализация

62Контракт, который говорит всё, обходится дорого. Каждое слово стартовой полосы читает каждый агент в начале каждой сессии. Поэтому текст, который должен быть перед глазами всегда, хочет быть коротким, а рассуждение за ним хочет лежать там, куда агент дотянется, когда спросит. C решил задачу такой формы в 1970-е двумя файлами, и C++ сохранил это решение. Заголовочный файл, .h, в нескольких строках объявляет, что предлагает библиотека; единица трансляции, .c или .cpp, несёт реализацию. Все, кто пользуется библиотекой, включают заголовок, и никто не вставляет реализацию в собственный код.

64VibeVM заимствует это разделение для текста. Пакет в формате normal держит под vibevm/vibespecs/ две папки. contract/ — заголовок: маленький, дешёвый в загрузке, поверхность, которую видят другие пакеты и агенты. source/ — реализация: тяжёлое тело, которое втягивается только тогда, когда кто-то попросит. Компилятор C видит всю программу и сам сводит объявления с определениями; у vibe такого взгляда на ваш текст нет, поэтому контракт сам называет свою реализацию директивой #source. У формата по умолчанию, simple, ничего этого нет: такой пакет несут целиком и читают потому, что он есть.

70Спецификации называют этот механизм наследованием, как в C++: один документ строится на другом, не копируя его текст. Втягивают две директивы, и с одной вы уже знакомы. #use называет документ или раздел, который нужно прочитать раньше текста, который им пользуется; компилятор копирует его вперёд, и копия приводит с собой всё, что втягивает сам скопированный документ. #source называет реализацию контракта, и компилятор компилирует её вслед за контрактом. В скомпилированном файле обеих директив уже нет — они израсходованы. Третья, #embed, вклеивает ровно один адресованный узел на то место, где стоит: макрос, а не include.

Шаг 4: отделить контракт от его причин

741. Создайте в пакете vibevm/vibespecs/source/details.md, реализацию контракта:

# Review rules, the reasons {#details}

## Why one idea per change {#one-idea-why}

@fact:ONE-IDEA-WHY A change with two ideas cannot be reverted one idea at a time, and its review takes twice as long. @status:spec/done

## Why tests before fixes {#tests-first-why}

@fact:TESTS-FIRST-WHY A fix without a failing test proves nothing: the test states what was wrong. @status:spec/done

## What a reviewer checks {#checklist}

- @fact:CHECK-SCOPE The first line names the one idea, and every hunk serves it. @status:spec/done
- @fact:CHECK-TEST The test fails on the parent commit and passes on this one. @status:spec/done

76Каждый якорь здесь отличается от якорей контракта: one-idea-why рядом с one-idea; особые случаи ниже объясняют почему. Последний раздел — список, в котором каждый пункт — факт.

772. В contract/REVIEW.md добавьте одну строку после первого абзаца:

#source spec://org.acme/review/source/details

79Адрес называет целый документ, без якоря, так что компилятор берёт его от заголовка и ниже.

803. Установите снова:

vibe install org.acme/review --assume-yes

Resolving 1 root package…

Materialising 1 package into vibedeps/:
  org.acme/review@0.1.0

closure diff:
  → lane vibevm/vibespecs/boot/STATIC.xml: 2809 -> 4557 B

Materialised 1 package into vibedeps/; regenerated boot artifacts for 1 node(s).

82Ни один пакет не добавлен, поэтому полоса — единственная строка диффа: скомпилированный файл вырос на реализацию.

834. Спросите vibe, что агент читает первым:

vibe tree --plain

project: <TMP>/work/review-lab
STATIC.xml: 4557 bytes, 69 lines, 1 contribution(s)
packages: 1   roots: 1
columns: load  T=transitive  C=condition  S=in STATIC.xml

org.acme/review  static   .  .  x

85Один пакет, связанный как static, и x говорит, что его текст скомпилирован в STATIC.xml.

865. Откройте скомпилированный файл:

cat vibevm/vibespecs/boot/STATIC.xml

<!-- vibe:c1 vibevm/vibespecs/boot/STATIC.xml — generated by vibe, do not edit. -->
<!-- vibe:c1 The static boot lane (PROP-009 §2.3): the highest-priority -->
<!-- vibe:c1 contributions, compiled anchor-qualified. Read this first, in full. -->

<!-- vibe:c1 RESOLUTION RULES — read these five lines before anything else:
  1. Labels in this file are qualified: <origin-slug>-%2D<original>. The origin
     is named by the provenance comment above each block; the original short
     label is the tail after the last `-%2D`.
  2. A short label you cannot find here → check the RENAMED ANCHORS table
     below for its qualified heirs; never guess among look-alikes.
  3. Full spec:// addresses resolve against package SOURCES under vibevm/vibedeps/,
     never against this generated file. This file is a cache, not a target.
  4. `#use spec://… as X` binds a file-local alias; `@!X` is a mandatory read
     of X's target (same rules as @spec://…). In this compiled file every @!X
     is already rewritten to its full address.
  5. An ambiguous or unresolvable short reference is an ERROR to surface with
     candidates — never silently pick one. -->

<!-- vibe:c1 RENAMED ANCHORS (short → qualified heirs):
  CHECK-SCOPE → org-acme-%2Dreview-%2DCHECK-SCOPE (org.acme/review)
  CHECK-TEST → org-acme-%2Dreview-%2DCHECK-TEST (org.acme/review)
  ONE-IDEA → org-acme-%2Dreview-%2DONE-IDEA (org.acme/review)
  ONE-IDEA-WHY → org-acme-%2Dreview-%2DONE-IDEA-WHY (org.acme/review)
  TESTS-FIRST → org-acme-%2Dreview-%2DTESTS-FIRST (org.acme/review)
  TESTS-FIRST-WHY → org-acme-%2Dreview-%2DTESTS-FIRST-WHY (org.acme/review)
  checklist → org-acme-%2Dreview-%2Dchecklist (org.acme/review)
  details → org-acme-%2Dreview-%2Ddetails (org.acme/review)
  one-idea → org-acme-%2Dreview-%2Done-idea (org.acme/review)
  one-idea-why → org-acme-%2Dreview-%2Done-idea-why (org.acme/review)
  root → org-acme-%2Dreview-%2Droot (org.acme/review)
  tests-first → org-acme-%2Dreview-%2Dtests-first (org.acme/review)
  tests-first-why → org-acme-%2Dreview-%2Dtests-first-why (org.acme/review) -->

<!-- vibe:c1 vibe:static org.acme/review — vibevm/vibedeps/org.acme.review/0.1.0/vibevm/vibespecs/boot/10-flow-review.xml -->

<?xml version="1.0" encoding="UTF-8"?>
<spec xmlns="https://vibevm.org/spec/1">
  <title id="org-acme--review--root">Review rules</title>
  <status stage="spec" state="done"/>
  <p>The rules a reviewer holds every change to. Each rule is one anchored
fact with a status.</p>
  <org-acme--review--one-idea title="One idea per change">
    <p><org-acme--review--ONE-IDEA fact="true" status="spec/done">A change under review carries one idea, named in its first line.</org-acme--review--ONE-IDEA></p>
  </org-acme--review--one-idea>
  <org-acme--review--tests-first title="Tests before fixes">
    <p><org-acme--review--TESTS-FIRST fact="true" status="spec/done">A change that alters behaviour carries a test that fails without it.</org-acme--review--TESTS-FIRST></p>
  </org-acme--review--tests-first>
  <org-acme--review--details title="Review rules, the reasons">
    <org-acme--review--one-idea-why title="Why one idea per change">
      <p><org-acme--review--ONE-IDEA-WHY fact="true" status="spec/done">A change with two ideas cannot be reverted one idea at a time, and its review takes twice as long.</org-acme--review--ONE-IDEA-WHY></p>
    </org-acme--review--one-idea-why>
    <org-acme--review--tests-first-why title="Why tests before fixes">
      <p><org-acme--review--TESTS-FIRST-WHY fact="true" status="spec/done">A fix without a failing test proves nothing: the test states what was wrong.</org-acme--review--TESTS-FIRST-WHY></p>
    </org-acme--review--tests-first-why>
    <org-acme--review--checklist title="What a reviewer checks">
      <facts ordered="false">
        <org-acme--review--CHECK-SCOPE fact="true" status="spec/done">The first line names the one idea, and every hunk serves it.</org-acme--review--CHECK-SCOPE>
        <org-acme--review--CHECK-TEST fact="true" status="spec/done">The test fails on the parent commit and passes on this one.</org-acme--review--CHECK-TEST>
      </facts>
    </org-acme--review--checklist>
  </org-acme--review--details>
  <section title="Review flow">
    <p>Before you open a change for review, hold it to the review rules. This
note pulls the rules in; each rule is one fact with an address, and the
reasons follow the rules. Cite a rule by its address, for example
`spec://org.acme/review/contract/REVIEW#ONE-IDEA`.</p>
  </section>
</spec>

88Читайте сверху. Сначала комментарии: правила, по которым агент трактует метки в этом файле, затем таблица всех переименованных якорей. XML запрещает два дефиса подряд внутри комментария, поэтому -- в метке там записано как -%2D; элементы ниже несут настоящие --. Затем один документ XML: сначала контракт, за ним реализация, вкомпилированная одним вложенным разделом. Последней идёт заметка из фрагмента — простой <section>, потому что у её заголовка не было якоря. Строк #source и #use больше нет.

90Каждый якорь теперь несёт префикс org-acme--review-- — метку своего происхождения. Два пакета, у которых раздел назван root, не столкнутся в одном файле, а таблица наверху говорит, чем стало каждое короткое имя. Ссылайтесь на исходный документ и никогда на этот файл: это кэш, который меняется всякий раз, когда меняется пакет.

936. Откройте запись, которую vibe хранит рядом со своей копией пакета:

cat vibevm/vibedeps/org.acme.review/0.1.0/.vibe-slot.toml

schema = 1
source_hash = "sha256:30fef78663fe343057c2d36d65514d3708d2f5053a2d41b713a749a0b28cc8eb"
spec_format = "xml"
converter_recipe = "specdoc/4"
derived_hash = "sha256:e420b6841c71fab586dfd72fe4720881b77d056e8f7a86217d1174b5fde0feba"

[[file]]
path = "README.xml"
sha256 = "c26e751356947bca54346b4099dc297dcdcac44831087d06436b1cb5f51ecec1"
disposition = "converted"
source = "README.md"

[[file]]
path = "vibe.toml"
sha256 = "42cb5b83bdc0e8ef61bdbb46095688593b05e4ad07bc61b8b346c13be0e753c6"
disposition = "copied"
source = "vibe.toml"

[[file]]
path = "vibevm/vibespecs/boot/10-flow-review.xml"
sha256 = "925cd961b99debb27cd179a42908bdf006c5103422c2a216ee8fc874d30865d3"
disposition = "converted"
source = "vibevm/vibespecs/boot/10-flow-review.md"

[[file]]
path = "vibevm/vibespecs/contract/REVIEW.xml"
sha256 = "ebcda3b670be21b409aa07b2600582ceb57cdc7eef8dbb3ef0dfe92dbc4f7a11"
disposition = "converted"
source = "vibevm/vibespecs/contract/REVIEW.md"

[[file]]
path = "vibevm/vibespecs/source/details.xml"
sha256 = "d35c2052468004ff1fb0dfc7724a496d8773aa280e686ce597fd14615acf6a2d"
disposition = "converted"
source = "vibevm/vibespecs/source/details.md"

95spec_format называет цель, converter_recipe — версию конвертера. Каждая строка говорит, был файл скопирован (copied) или сконвертирован (converted), и несёт хэш того, что легло на диск. Держите этот файл в уме: шаг 5 прочитает его снова.

Эквивалентные формы

97Конструкции, которыми пользовалась эта страница, бок о бок, из её собственных файлов:

99Диалект закрыт и мал нарочно. Он выражает ровно то, что выражает Markdown, поэтому конверсия в любую сторону не теряет смысла, а элемент вне диалекта — громкая ошибка, а не молчаливый пропуск. У двух якорей нет собственного элемента: у того, что начинается с цифры, и у того, что совпадает со словом самого диалекта, таким как title или list. Для них встают общие <section id="…"> и <fact id="…">, и каждый читатель принимает оба написания. Единственное исключение из правила эквивалентности — словарь пакетов документации, к которым принадлежит и это руководство: у их выполняемых примеров и живых цитат нет формы в Markdown, и в Markdown они проецируются только в одну сторону.

Шаг 5: сконвертировать и увидеть, что ничего не изменилось

103Вы написали Markdown и отгрузили XML. Последний шаг показывает, что XML, который вы написали бы руками, — тот же файл, байт в байт.

1041. Спросите конвертер, что потеряет конверсия:

vibe refactor convert-source --to xml --dry-run vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs

dry-run ir-stable-loss vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/boot/10-flow-review.md
--- source
+++ reverse-projection
@@ -8,2 +8,3 @@
 #use spec://org.acme/review/contract/REVIEW#root

+

dry-run ir-stable-loss vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/contract/REVIEW.md
--- source
+++ reverse-projection
@@ -16,2 +16,3 @@
 @fact:TESTS-FIRST A change that alters behaviour carries a test that fails without it. @status:spec/done

+

dry-run ir-stable-loss vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/source/details.md
--- source
+++ reverse-projection
@@ -14,2 +14,3 @@
 - @fact:CHECK-TEST The test fails on the parent commit and passes on this one. @status:spec/done

+

summary converted=0 already=0 lossy-confirmed=0 refused=0 skipped-generated=0 skipped-foreign=0 skipped-harness=0 dry-run=3

106Конвертер разбирает каждый файл в дерево, печатает XML, читает его обратно и снова печатает Markdown, а затем сравнивает. Вердикт ir-stable-loss значит, что дерево уцелело, а байты нет, и дифф показывает, что изменилось. Здесь это одна пустая строка в конце каждого файла, которую добавляет принтер Markdown. Без --force команда отказывает файлу из-за такой потери. В изменении смысла она отказывает всегда, потому что это был бы дефект конвертера, а не вашего файла.

1092. Сконвертируйте три документа. Команда пишет каждый .xml рядом с его .md и удаляет .md тем же действием. Дерево никогда не держит документ в обеих формах:

vibe refactor convert-source --to xml --force vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs

1123. В манифесте пакета направьте source на новый файл, vibevm/vibespecs/boot/10-flow-review.xml.

1134. Установите снова:

vibe install org.acme/review --assume-yes

Resolving 1 root package…

Materialising 1 package into vibedeps/:
  org.acme/review@0.1.0

  → closure unchanged (1 packages)

Materialised 1 package into vibedeps/; regenerated boot artifacts for 1 node(s).

1155. Откройте запись ещё раз:

cat vibevm/vibedeps/org.acme.review/0.1.0/.vibe-slot.toml

schema = 1
source_hash = "sha256:6c7b5d64df7efadb3ebb7ba950902e3e3e1cc1a0a9c0a06f464c55a9f01bd209"
spec_format = "xml"
converter_recipe = "specdoc/4"
derived_hash = "sha256:908b2213850eba6789f655e7cfac4722328659e1eb5ea5017b8eb71055a152dc"

[[file]]
path = "README.xml"
sha256 = "c26e751356947bca54346b4099dc297dcdcac44831087d06436b1cb5f51ecec1"
disposition = "converted"
source = "README.md"

[[file]]
path = "vibe.toml"
sha256 = "018fe59c3ed0b41a24ad236798f5b8198c6ad983a58a9c72d7f73897a4d56e62"
disposition = "copied"
source = "vibe.toml"

[[file]]
path = "vibevm/vibespecs/boot/10-flow-review.xml"
sha256 = "925cd961b99debb27cd179a42908bdf006c5103422c2a216ee8fc874d30865d3"
disposition = "copied"
source = "vibevm/vibespecs/boot/10-flow-review.xml"

[[file]]
path = "vibevm/vibespecs/contract/REVIEW.xml"
sha256 = "ebcda3b670be21b409aa07b2600582ceb57cdc7eef8dbb3ef0dfe92dbc4f7a11"
disposition = "copied"
source = "vibevm/vibespecs/contract/REVIEW.xml"

[[file]]
path = "vibevm/vibespecs/source/details.xml"
sha256 = "d35c2052468004ff1fb0dfc7724a496d8773aa280e686ce597fd14615acf6a2d"
disposition = "copied"
source = "vibevm/vibespecs/source/details.xml"

117Сравните её с записью шага 4. Каждый из трёх документов теперь copied, и хэш каждого — тот же, что был у него как у converted. То, что конвертер написал из вашего Markdown, — это то, что из него написала установка, байт в байт. Скомпилированный файл тоже не изменился:

vibe tree --plain

project: <TMP>/work/review-lab
STATIC.xml: 4557 bytes, 69 lines, 1 contribution(s)
packages: 1   roots: 1
columns: load  T=transitive  C=condition  S=in STATIC.xml

org.acme/review  static   .  .  x

119Те же байты, те же строки. Вот что значит на практике одна модель под капотом. Форма, в которой вы пишете, — ваш выбор; текст, который доходит до агента, один и тот же. Проект с spec_format = "markdown" проходит ту же дорогу в обратную сторону. Markdown, который он пишет из вашего XML, — ваш исходный файл плюс та самая пустая строка.

Что появилось на диске

122Ваш пакет живёт под vibevm/vibepacks/org.acme/review/v0.1.0/: манифест, README и три документа XML, которые правите вы. Копия vibe живёт под vibevm/vibedeps/org.acme.review/0.1.0/ вместе с записью .vibe-slot.toml и переписывается при каждой установке. В vibevm/vibespecs/boot/ лежат скомпилированный STATIC.xml и INDEX.md, чья строка static называет скомпилированный файл, а рядом — два ваших стартовых файла, которых ни одна установка не трогает. vibe.lock, лок-файл проекта, закрепляет за пакетом его версию и хэш.

Особые случаи и правила

124При spec_format = "xml" раздел источника не должен повторять якорь контракта, а заголовок заметки не несёт якоря. Компилятор сливает разделы с общим якорем, и результат слияния сегодня не компилируется в STATIC.xml. Установка останавливается с fact id … is defined twice; копия пакета уже на диске, а лок-файл не записан. Два документа, чьи заголовки оба {#root}, сталкиваются так же. При spec_format по умолчанию тот же пакет компилируется.

125Точка внутри якоря — путь, а не символ. К {#verification.timeout} нельзя обратиться, тогда как #verification.timeout доходит до раздела timeout, вложенного в раздел verification. Якорь — это буква, за которой идут буквы, цифры, _ и -.

127vibe init package пишет link = "dynamic", какой бы --link вы ни передали. Задайте связь в манифесте, как делает шаг 2.

128При link = "dynamic" скомпилированного файла нет. INDEX.md называет саму заметку, и агент, который её откроет, встретит строку #use и должен будет сам по ней пойти.

129vibe explain отвечает только за пакет, который несёт карту прослеживаемости (traceability map). Про этот он так и говорит и останавливается.

130vibe facts check ловит опечатку в состоянии в форме элемента, state="finished", и называет значение. В короткой форме @status:spec/finished вовсе не читается как маркер, и файл проходит как чистый. Состояния — plan, work, done, hold и void; стадии — idea, spec, impl, test, doc, freeze и unknown.