Traceability: specs, code and the map

Marks in the code

03A Rust item that implements a rule carries an attribute naming the rule's address; a test that verifies one carries a verifying attribute; a module that serves one section as a whole declares a scope. The links live in the code, beside the thing they describe, so they travel with every refactor and every copy. The verbs are implements, verifies, documents, deviates and informs; a deviation must say why.

06implements is a claim about code that runs. A type declaration does not carry it: an edge from a declaration is indistinguishable from coverage, and a map that counted declarations would be green about nothing.

The map

08cargo xtask specmap walks the crates for marks and the specification tree for units, and writes specmap.json: nodes for every spec unit with its revision and content hash, nodes for every tagged code item, and the edges between them. The map is committed, and cargo xtask specmap --check fails when the tree moved and the map did not. The policy of what is scanned, which crates are gated and which are exempt lives in specmap.toml; the engine itself ships with the discipline package and is vendored, never edited in place.

10Three gates guard the map. The orphan ratchet: a public item in a gated crate without a mark fails the check, unless it is dispositioned with a debt id. The resolve gate: every edge into this project's own namespace must land on an existing anchor. The suspect rule: when a spec unit's revision bumps, every edge pinned to the old revision becomes suspect and the check names it, so the code is re-read against the rule that moved.

12Generated code is excluded from the orphan gate; the generator's input, the schema, carries the marks instead, and a schema scanner reads them.

Asking the map

14The commands below run in a checkout of vibe itself, whose specifications carry a map; an installed package answers only if it shipped one. vibe explain "spec://…#anchor" builds the map fresh in memory and prints one target's subgraph: what implements, verifies or documents it. vibe query filters the map by address, symbol or kind and returns the many nodes that fit. vibe select --where "lacks:verifies scope:spec://…" walks the graph with a predicate: every rule with no verifier, the implementers of a rule and one hop around them. --json gives each answer to an agent.

vibe select --where "uri:spec://org.vibevm.core/vibevm/common/PROP-000#KIND-SET depth:1"

map select · grammar v1 · uri=spec://org.vibevm.core/vibevm/common/PROP-000#KIND-SET AND depth=1
7 results

  d0 spec -          `kind ∈ {flow, feat, stack, tool, mcp, lang, doc, app}` — eight kinds; `mcp` shipped with [PROP-027](../modules/vibe-mcp/PROP-027-mcp-packages.xml); `doc` and `app` admitted by [PROP-057](PROP-057-documentation-packages-and-site.xml) through the `VIBEVM-SPEC.md` §4.1 amendment of 2026-09-12 (pending the owner's ratification at the merge of the docs-2026-09 branch; the code learns the two kinds in that campaign's phase 2). (§Invariants `INV-VOCABULARY` in this file carries the same list.) <status stage="spec" state="done" action="continue" actionstage="impl"/>  vibevm/vibespecs/common/PROP-000.xml:75  spec://org.vibevm.core/vibevm/common/PROP-000#KIND-SET
  d1 code doc-page   authoring::write-a-lang-package  vibevm/vibepacks/org.vibevm.core/vibevm-docs-ru/v1.0.0/vibevm/vibespecs/authoring/write-a-lang-package.xml:1
  d1 code doc-page   authoring::write-a-lang-package  vibevm/vibepacks/org.vibevm.core/vibevm-docs/v1.0.0/vibevm/vibespecs/authoring/write-a-lang-package.xml:1
  d1 code doc-page   glossary::index  vibevm/vibepacks/org.vibevm.core/vibevm-docs-ru/v1.0.0/vibevm/vibespecs/glossary/index.xml:1
  d1 code doc-page   glossary::index  vibevm/vibepacks/org.vibevm.core/vibevm-docs/v1.0.0/vibevm/vibespecs/glossary/index.xml:1
  d1 code doc-page   model::packages-and-kinds  vibevm/vibepacks/org.vibevm.core/vibevm-docs-ru/v1.0.0/vibevm/vibespecs/model/packages-and-kinds.xml:1
  d1 code doc-page   model::packages-and-kinds  vibevm/vibepacks/org.vibevm.core/vibevm-docs/v1.0.0/vibevm/vibespecs/model/packages-and-kinds.xml:1

Documentation in the map

16This manual enters the same map. Every rule block on a page is a documents edge from the page to the rule it quotes, scanned on the host side through the engine's scanner seam. The edge carries no revision pin: the citation is live, the page shows the rule's current text, and the only check is that the anchor exists. Whether the prose around a citation went stale is a human's question, not a suspect flag.

Edge cases and rules

19Units come in four kinds, and each has a default edge: a requirement is implemented and verified, a design informs, a guide documents; a proposal decides, which is not yet a verb the system carries.

21The map is carried, not generated: a mapping between prose and code cannot be inferred, only authored and verified, which is why the marks are in the code and the gates are in the build.

23A package can carry its own map, package.specmap.json, generated by vibe specmap before publishing, so a consumer queries an installed package without rebuilding it.