Прослеживаемость: спецификации, код и карта

Пометки в коде

03Элемент Rust, который воплощает правило, несёт атрибут с адресом правила; тест, который его проверяет, несёт проверяющий атрибут; модуль, который обслуживает целый раздел, объявляет область. Связи живут в коде, рядом с тем, что описывают, и потому едут с каждым рефакторингом и каждой копией. Глаголы: implements, verifies, documents, deviates и informs; отклонение обязано сказать почему.

04 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).

05 Verbs: implements, verifies, documents, deviates, informs. deviates REQUIRES reason.

06implements — утверждение о коде, который выполняется. Объявление типа его не несёт: ребро от объявления неотличимо от покрытия, и карта, которая считала бы объявления, была бы зелёной ни о чём.

07 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.

Карта

08cargo xtask specmap обходит крейты в поисках пометок и дерево спецификаций в поисках единиц и пишет specmap.json: узлы для каждой единицы спецификации с её ревизией и хешем содержимого, узлы для каждого помеченного элемента кода и рёбра между ними. Карта закоммичена, и cargo xtask specmap --check падает, когда дерево сдвинулось, а карта нет. Политика того, что сканируется, какие крейты под воротами, а какие освобождены, живёт в specmap.toml; сам движок поставляется с пакетом дисциплины и вендорится, никогда не правится на месте.

09 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.

10Карту стерегут трое ворот. Храповик сирот: публичный элемент в крейте под воротами без пометки проваливает проверку, если только он не диспозиционирован с идентификатором долга. Ворота разрешения: каждое ребро в собственное пространство имён этого проекта должно приземлиться на существующий якорь. Правило подозрения: когда ревизия единицы спецификации поднимается, каждое ребро, закреплённое за старой ревизией, становится подозрительным, и проверка его называет, чтобы код перечитали против правила, которое сдвинулось.

11 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.

12Сгенерированный код исключён из ворот сирот; пометки вместо него несёт вход генератора, схема, и их читает сканер схем.

13 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 = <stem> and <stem>::<def>, 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.

Как спросить карту

14Команды ниже работают в чекауте самого vibe, чьи спецификации несут карту; установленный пакет отвечает, только если поставил свою. vibe explain "spec://…#anchor" строит карту заново в памяти и печатает подграф одной цели: что её воплощает, проверяет или документирует. vibe query фильтрует карту по адресу, символу или виду и возвращает множество подходящих узлов. vibe select --where "lacks:verifies scope:spec://…" обходит граф с предикатом: каждое правило без проверяющего, элементы, которые воплощают правило, и один переход вокруг них. --json отдаёт каждый ответ агенту.

Документация на карте

16Это руководство входит в ту же карту. Каждый блок rule на странице — ребро documents от страницы к правилу, которое она цитирует, просканированное на стороне хоста через шов сканера движка. Ребро не несёт пина ревизии: цитата живая, страница показывает текущий текст правила, и единственная проверка — что якорь существует. Устарела ли проза вокруг цитаты — вопрос к человеку, а не флаг подозрения.

17 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 = "<doc>", after the precedent of the JTD scanner's "<schema>"; the engine's wire schema does not change.

18 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.

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

19Единицы бывают четырёх видов, и у каждого своё ребро по умолчанию: требование воплощают и проверяют, дизайн информирует, руководство документирует; предложение решает, и это пока не глагол, который система несёт.

20 Decision. Four unit kinds, each with a different default edge semantics:

21Карту носят, а не генерируют: соответствие между прозой и кодом нельзя вывести, только написать и проверить, и потому пометки в коде, а ворота в сборке.

22 The mapping cannot be generated; it can only be carried and verified. Until M1.5's vibe build exists, every edge is authored metadata.

23Пакет может нести собственную карту, package.specmap.json, сгенерированную vibe specmap перед публикацией, так что потребитель спрашивает установленный пакет, не пересобирая его.