` river is not. The generic > form `

` remains in the dialect as the REQUIRED > fallback for the two cases XML itself forbids or the grammar reserves: an > anchor that is not a valid XML name (leading digit) and an anchor > colliding with the structural vocabulary (`spec`,`title`,`status`, > `section`,`p`,`fact`,`list`,`item`,`table`,`tr`,`td`,`fence`,`quote») — > measured over the live corpus, that tail is 2 anchors of 1393; the > emitter writes the named form everywhere else, the readers accept both. > The converter recipe bumps (`specdoc/1` → `specdoc/2`), so every > transformed slot re-materialises by the derived-manifest law rather than > lingering in the old shape. The owner's next call arrived the same > day — facts follow, see `##NAMED-FACT-ELEMENTS`. Landed: the emitter > writes named sections everywhere the predicate allows (the live redbook > README golden carries 7 named / 0 generic), both readers accept both > forms, and the engine mirrors the predicate verbatim across the > separability seam. > > > [p17] **Decision (ADR-part; owner ruling 2026-08-22, > near-verbatim): «Не правильней ли не включать внутри list элементы item, > а сразу ставить в тело list элементы типа ``? И > вместо `` использовать тэг `` — это новое слово для > зарезервированного словарика… Если же список состоит из обычного текста > (там могут даже иногда встречаться факты), то все элементы — это item и > группировка — list, а факты в нём рендерятся как сейчас».** The law: a > list whose every item is exactly one meaningful fact materialises as the > vocabulary element `` with the fact elements (named > or generic) directly in its body — no `` wrappers; any other list > (plain text, or mixed with occasional facts) keeps today's > ``/`` shape with facts rendered inside items. `facts` joins > the reserved vocabulary (an anchor named `facts` falls back to the > generic form); `ordered` carries over exactly as on ``; the model > is unchanged — both shapes parse to the same `Block::List`, so the > reader accepts BOTH forms (old materialisations in the wild stay > readable) and a rewrite normalises the all-fact shape to ``. > Loud errors guard the grouping: a non-fact child inside ``, bare > text inside ``, an empty ``. Both readers — the pivot and > the specmap engine's native one — learn the form mirror-wise; the > converter recipe bumps `specdoc/3` → `specdoc/4` and the host > re-materialises once. Landed: the writer branch, the `facts_block` > parser (split into the pivot's own `xml_facts.rs` along the engine's > seam) and the vocabulary word sit in both readers with the four loud > errors pinned; the engine proves model-identity by content hash > between the two shapes; the redbook README golden re-pins with two > `` groups and the same 45 named facts; the host's 37 slots > re-materialised at `specdoc/4`; and the §5a stand re-ran as the > regression tool it was left as — polygons rebuilt on the new shape > (121 files carry groups), the sensitive tier (`gpt-5.5`@`low`) swept > 9/9 with the negative control clean. > > [p18] Статус на каждой единице говорит, где она стоит: `spec/done` для устоявшегося правила, `impl/done`, когда оно уже воплощено в коде, `spec/work` для черновика. Два регистра идентификаторов несут сигнал бесплатно: идентификатор в верхнем регистре помечает правило с обязывающим весом, в нижнем — вводную или заметку. > [p19] **Decision — two anchor-id registers (owner ruling, 2026-07-24).** > `@fact:UPPER-SLUG` names a **normative fact** (a law, rule, carrier, > changelog entry — content with binding weight); `@fact:kebab-case` > names a **service unit** (status lines, lead-ins, connective > prose). > > [p20] Example `convert` is copied from the source page at projection time. [p21] `vibe refactor convert-source --to xml` или `--to markdown` конвертирует файлы или целые папки, пропуская дерево зависимостей и сгенерированные файлы. Он пишет соседнюю форму и удаляет оригинал одним действием, так что дерево никогда не держит обе формы одного документа. Перед записью он конвертирует результат обратно и сравнивает: побайтно совпавший обратный путь конвертируется молча, а потеря комментариев или раскладки отвергается с описанием по каждому файлу, пока вы не подтвердите или не передадите `--force`. Изменение смысла отвергается всегда, потому что это дефект конвертера, а не вашего файла. `--dry-run` сообщает о каждом файле и ничего не пишет. > [p22] `vibe refactor convert-source --to > xml|markdown [PATH…]` converts spec sources between the two PROP-045 > serialisations (`md` accepted as an alias of `markdown`). Each PATH is a > file or a directory; a directory walks recursively and selects spec > sources (`is_spec_source`) currently in the OPPOSITE form; a file in the > target form already is reported `already` and skipped. The walk always > skips: `vibedeps/` (##VIBEDEPS-NEVER-CONVERTED), dot-directories, > `target/`, and any file whose leading lines carry the `generated by > vibe` marker (generated artifacts regenerate; they are not authored > sources) — an EXPLICIT file argument overrides only the marker skip, > never the `vibedeps/` skip. > > > [p23] A conversion writes the sibling > serialisation and deletes the original in the same act, so the > one-document-one-form law (PROP-045 ##TARGET-MIXED, the pair-collision > check) holds at every instant — the tree never holds `X.md` and `X.xml` > together, not even transiently between files. The verb assumes version > control underneath it and keeps no backups of its own. > > > [p24] The destructiveness check is the owner's law, > implemented by reverse reconversion through the pivot: for a source > `S`, parse to IR, emit the target form, read the target form back, and > project it into the SOURCE form again; compare. Three classes: > **(1) byte-stable** — the back-projection equals `S` byte-for-byte: > converts silently. **(2) IR-stable loss** — the back-projection > re-parses to the SAME IR but differs in bytes (dropped MD/XML comments, > normalised layout): the verb REFUSES with a per-file description of > what is lost, and proceeds only on interactive confirmation or > `--force`. **(3) IR-divergent** — the back-projection re-parses to a > DIFFERENT IR: always refused, `--force` does not apply; that class is a > `vibe-specdoc` defect to file (the pivot broke its own round-trip law), > never a corpus to damage. > > > [p25] On a TTY, class-2 files prompt per file > (yes / no / all); off a TTY, class-2 without `--force` is an error > listing every lossy file and what each loses. `--force` waives class 2 > only. `--dry-run` classifies and reports every file, writes nothing, > and always exits 0 (an inventory, not an attempt); a real run exits 0 > iff every requested conversion landed, non-zero when any file was > refused or declined. > > ## Директивы: use, embed и read {#directives} [p26] Спецификация может подтянуть другую по адресу. `#use spec://…` подтягивает весь раздел верхнего уровня, содержащий адресованный узел, но не его соседей; `#embed` вклеивает ровно адресованный узел, не больше. Слияние по умолчанию — `:add`, так что текст интерфейса не нужно повторять, чтобы он попал в результат. Каждый файл, который называет директива, должен быть объявлен в [манифесте](../glossary/index.xml#manifest) пакета. Циклы законны в слое контрактов и запрещены между телами исходников, и именно это гарантирует, что сборка всегда заканчивается. > [p27] **`#use` pulls the whole top-level anchored ancestor** of the addressed node — reference a subsection, load its enclosing top-level section as one connected block. It does **not** pull that ancestor's siblings; siblings are read only when themselves needed. > > > [p28] **`#embed` has arbitrary granularity** — it splices exactly the addressed node, no more. > > > [p29] **Default is `:add`** (absent a `:`-suffix) — so the interface text need not be duplicated to appear in the result. > > > [p30] Every file referenced by any directive MUST be declared in the package's `vibe.toml` (the directive graph and the manifest cannot disagree). > > > [p31] **Invariant.** The **contract layer is where cycles are legal; the source layer is where topological order is mandatory.** This is the theoretical no-deadlock guarantee: as long as the contract hierarchy is acyclic-under-`#embed` and no source body participates in a `#use` cycle, the build always terminates. > > [p32] В прозе, которую читает агент, `@spec://…` с собакой обязателен: агент читает его на месте, один раз, при первой встрече, а компилятор никогда его не вклеивает. Голый `spec://…` остаётся на усмотрение агента. > [p33] **`@spec://…`** (an `@` before `spec`) is an **in-place use**: the agent MUST read it (mandatory), exactly as if a `#use` had been declared at the top of the file. **Amendment (2026-08-24, the normal-flip ruling):** the obligation is the AGENT's, not the AOT compiler's — a `@spec` target is **never spliced** into a compiled lane; the address itself is the compiled artefact, and the §2 equivalence invariant is carried by the agent's read obligation. (Splicing every `@spec` realised ##OPEN-CLOSURE-EXPLOSION on the first normal-format host build: the lane grew 250 KB → 2.5 MB off prose pointers.) Only an explicit `#use` is a compiler splice edge. > > > [p34] **Read once.** An `@spec` target is read only on **first** encounter, never re-read blindly — see the read-set (§below). > > > [p35] **Bare `spec://…`** (no `@`) is at the agent's discretion — read it if useful, skip it otherwise. (A future algorithmic agent narrows this further.) > > ## Адрес никогда не двигается {#immutable} [p36] После публикации якорь неизменяем. Переименование раздела или правила оставляет на старом якоре надгробие, указывающее на новый, так что ссылка, написанная год назад, всё ещё попадает куда надо. Перемещение файлов адреса тоже не меняет: адрес логический, путь — физика. > [p37] **L1 — physics moves, addresses do not.** `spec://` > addresses, anchors, fact ids, specmap edges, `scope!` citations and > recorded verdicts are LOGICAL and do not change: only the physical > prefix maps differently (`vibevm/vibespecs/common/PROP-000.xml` > still canonicalises to the same `common/PROP-000` document path). > Any relayout step that would rename an address is a defect of the > step. > > > [p38] **Anchors are immutable; a rename is a tombstone** — for published documentation pages as for specs, and for translations, which must match their source. > > ## Особые случаи и правила {#edge-cases} [p39] Сгенерированный файл никогда не цель цитаты: цитируйте исходный документ, а не скомпилированную [стартовую полосу](../glossary/index.xml#boot-lane). > [p40] **A generated `STATIC.md` is not a citation target** — authored text never cites `spec://…/boot/STATIC#…`; the lane is compiler output, and source-of-truth is the package source under `vibedeps/` (PROP-035 §11's lint, B-011 §6.1). > > [p41] `vibe facts check` проверяет разметку спецификаций пакета; `vibe check` проверяет пакет целиком; обе запускаются перед публикацией. [p42] Код тоже может цитировать спецификации, атрибутом на элементе, который воплощает правило, и тогда карта отвечает, какой код стоит за каким правилом, в обе стороны; эту карту объясняют страницы об архитектуре этого руководства.