# Прослеживаемость: спецификации, код и карта {#root} @status:doc/work @audience:dev [p01] Каждый публичный кусок кода в vibe указывает на правило, которое он воплощает, а сгенерированная карта отвечает в обе стороны: какой код стоит за этим правилом, какому правилу отвечает этот код. [p02] Example `explain` is copied from the source page at projection time. ## Пометки в коде {#marks} [p03] Элемент Rust, который воплощает правило, несёт атрибут с адресом правила; тест, который его проверяет, несёт проверяющий атрибут; модуль, который обслуживает целый раздел, объявляет область. Связи живут в коде, рядом с тем, что описывают, и потому едут с каждым рефакторингом и каждой копией. Глаголы: `implements`, `verifies`, `documents`, `deviates` и `informs`; отклонение обязано сказать почему. > [p04] **Edges travel with the artefacts.** Code-side links live *in the code* (attributes on items) and survive any refactor that moves the item. Spec-side links live *in the spec* (stable anchors). External sidecar maps are rejected (§5.1). > > > [p05] **Verbs:** `implements`, `verifies`, `documents`, `deviates`, `informs`. `deviates` REQUIRES `reason`. > > [p06] `implements` — утверждение о коде, который выполняется. Объявление типа его не несёт: ребро от объявления неотличимо от покрытия, и карта, которая считала бы объявления, была бы зелёной ни о чём. > [p07] **`implements` is a claim about code that RUNS, and a bare declaration does not carry one.** A trait, an abstract signature or any other declared shape that no production code implements gets no `implements` edge, however faithfully it describes the requirement. The edge arrives with the implementation. > > ## Карта {#the-map} [p08] `cargo xtask specmap` обходит крейты в поисках пометок и дерево [спецификаций](../glossary/index.xml#specification) в поисках единиц и пишет `specmap.json`: узлы для каждой единицы спецификации с её ревизией и хешем содержимого, узлы для каждого помеченного элемента кода и рёбра между ними. Карта закоммичена, и `cargo xtask specmap --check` падает, когда дерево сдвинулось, а карта нет. Политика того, что сканируется, какие крейты под воротами, а какие освобождены, живёт в `specmap.toml`; сам движок поставляется с пакетом дисциплины и вендорится, никогда не правится на месте. > [p09] **Invariants are machine-checked.** Dangling references, uncovered requirements, orphan code, and — the load-bearing one — **staleness**: a spec unit carries a revision + content hash; when it changes, every edge pinned to the old revision flips to *suspect* until re-affirmed. > > [p10] Карту стерегут трое ворот. *Храповик сирот*: публичный элемент в крейте под воротами без пометки проваливает проверку, если только он не диспозиционирован с идентификатором долга. *Ворота разрешения*: каждое ребро в собственное пространство имён этого проекта должно приземлиться на существующий [якорь](../glossary/index.xml#anchor). *Правило подозрения*: когда ревизия единицы спецификации поднимается, каждое ребро, закреплённое за старой ревизией, становится подозрительным, и проверка его называет, чтобы код перечитали против правила, которое сдвинулось. > [p11] Spec unit `r` bumps → every edge pinned to the old `r` becomes **suspect**; CI gate lists them; each is cleared by re-affirming (updating the pin) after review. > > [p12] Сгенерированный код исключён из ворот сирот; пометки вместо него несёт вход генератора, схема, и их читает сканер схем. > [p13] **Generated code** (e.g. `vibe-wire/src/generated/`) is excluded from orphan checks via a directory marker; the *generator input* (JTD schema file) is the taggable unit instead. *BUILT 2026-08-05 — both halves are now real. The exclusion half always was: `rscan` and `ratchet` skip a path containing `/generated/`. The designation half was a decision nobody could act on, because no scanner opened a `.json` at all and the edge model hangs an address off a code SYMBOL, which a JSON document has no obvious equivalent of. Both are answered: a schema's units are its ROOT and each `definitions` entry (`symbol` = `` and `::`, `item_kind` = `schema` / `schema-def`), and the tag lives in JTD's own `metadata.spec` block as a verb → URI map. The scanner is opt-in per project through `schema_roots`, empty by default. Measured on the host that raised this: seven wire contracts tagged, 16 units and 7 edges in the map, and `vibe explain` now answers «what implements PROP-000 §16» with all seven, by file and line.* > > ## Как спросить карту {#asking} [p14] Команды ниже работают в чекауте самого vibe, чьи спецификации несут карту; установленный пакет отвечает, только если поставил свою. `vibe explain "spec://…#anchor"` строит карту заново в памяти и печатает подграф одной цели: что её воплощает, проверяет или документирует. `vibe query` фильтрует карту по адресу, символу или виду и возвращает множество подходящих узлов. `vibe select --where "lacks:verifies scope:spec://…"` обходит граф с предикатом: каждое правило без проверяющего, элементы, которые воплощают правило, и один переход вокруг них. `--json` отдаёт каждый ответ агенту. [p15] Example `select` is copied from the source page at projection time. ## Документация на карте {#documentation-edges} [p16] Это руководство входит в ту же карту. Каждый блок `rule` на странице — ребро `documents` от страницы к правилу, которое она цитирует, просканированное на стороне хоста через шов сканера движка. Ребро не несёт пина ревизии: цитата живая, страница показывает текущий текст правила, и единственная проверка — что якорь существует. Устарела ли проза вокруг цитаты — вопрос к человеку, а не флаг подозрения. > [p17] The `rule` element is read on the **host side**: a host module scans documentation pages and injects into the traceability engine through its public `CodeScanner` seam (`build_with_scanner`, `check_with_scanner`, `write_with_scanner`, `CompositeScanner`). The engine and its vendored copies are not edited and `sync-engines` is not run. Documentation pages lie **outside** `spec_roots`, the page-scan policy lives in a host file rather than in `specmap.toml`, and the scanner is injected at both points of `xtask/src/specmap.rs` — the main pass and the resolve gate — so the coverage gate cannot be green by emptiness. The edge's tail is a `CodeItem` with the sentinel `crate_name = ""`, after the precedent of the JTD scanner's `""`; the engine's wire schema does not change. > > > [p18] Every `rule` yields a `documents` edge **without a pin**: the citation is live, and the page shows the fact's current text by address at every render. `vibe doc check --citations` checks one thing — that the anchor exists; a vanished anchor without a tombstone fails the build. There are no revisions, no text hashes and no «the spec moved ahead»: such checks would need a history the project does not keep by design. > > ## Особые случаи и правила {#edge-cases} [p19] Единицы бывают четырёх видов, и у каждого своё ребро по умолчанию: требование воплощают и проверяют, дизайн информирует, руководство документирует; предложение решает, и это пока не глагол, который система несёт. > [p20] **Decision.** Four unit kinds, each with a different default edge semantics: > > [p21] Карту носят, а не генерируют: соответствие между прозой и кодом нельзя вывести, только написать и проверить, и потому пометки в коде, а ворота в сборке. > [p22] The mapping cannot be *generated*; it can only be *carried and verified*. Until M1.5's `vibe build` exists, every edge is authored metadata. > > [p23] Пакет может нести собственную карту, `package.specmap.json`, сгенерированную `vibe specmap` перед публикацией, так что потребитель спрашивает установленный пакет, не пересобирая его.