# PROP-052: the vibevm/ root — the directory layout law {#root}

@status:impl/done

## 1. Mandate {#mandate}

[p01] @fact:RELAYOUT-MANDATE-VERBATIM The owner's mandate, verbatim (2026-08-24):
«Я обнаружил проблему: массовые клеши с реально существующими
проектами, имеющими директорию spec или packages в корне. Кроме
того, динамическим лоадерам сложно искать по таким директориям. В
качестве решения, я хочу сделать глобальное переименование корневых
директорий в проектах/пакетах. В корне создается директория vibevm.
Внутрь неё переезжают директории: Директория spec переезжает с
именем vibespecs. Директория packages переезжает с именем vibepacks.
Директория vibedeps переезжает c исходным именем. Директория
vibefacts переезжает с исходным именем. В мире не существует никаких
легаси проектов с директорией vibevm в корне, а по именам типа
"vibespecs" агентам проще делать grep и find, чем по spec (который
приносит много мусора). Совершенно все спецификации, которые
содержат эти имена (spec, packages, vibedeps, vibefacts) - должны
быть проверены и переписаны соответствующе (spec ->
vibevm/vibespecs). Конечно же, совершенно весь код. Сам проект
vibevm и все его пакеты в packages должны быть переделаны под новую
раскладку директорий. Результаты проверены/протестированы и
измерены на предмет того, что ничего не сломалось.» @status:spec/done

[p02] @fact:THE-LAYOUT The layout: every project and every package carries ONE
distinctive root directory `vibevm/`, holding `vibevm/vibespecs`
(was `spec/`), `vibevm/vibepacks` (was `packages/`),
`vibevm/vibedeps` (was root `vibedeps/`) and `vibevm/vibefacts`
(was root `vibefacts/`). Nothing else moves; `vibe.toml` stays at
the project root. @status:spec/done

## 2. Laws {#laws}

[p03] @fact:ADDRESSES-SURVIVE-THE-MOVE **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. @status:spec/done

[p04] @fact:ONE-LAYOUT-MODULE **L2 — one layout module.** The four roots are named in
exactly ONE place in the product — a layout module in the core
(`vibespecs_root()` / `vibepacks_root()` / `vibedeps_root()` /
`vibefacts_root()` and the derived boot paths); every crate routes
through it, and a string literal of the old or new root outside
that module (tests' own scaffolds excepted) is a conform-guarded
defect. @status:spec/done

[p05] @fact:NO-LEGACY-LAYOUT **L3 — no legacy reading.** The old layout is not read and
not migrated silently: a project carrying root `spec/` beside
`vibe.toml` (or root `vibedeps/`/`vibefacts/`) fails loudly with
the migration recipe. The owner's ground: no project in the world
carries a root `vibevm/` today, so the new root is unambiguous and
the old one is retired whole. @status:spec/done

[p06] @fact:PACKAGES-CARRY-THE-LAYOUT-TOO **L4 — packages too.** Every package root mirrors the same
layout (`vibevm/vibespecs` inside the package instead of `spec/`);
materialisation mirrors package layout into the slots, boot-snippet
paths and INDEX targets follow. @status:spec/done

[p07] @fact:REFACTOR-VERBS-FOLLOW **L5 — the refactor family follows.** `convert-package-src`
and `convert-spec-src` resolve spec homes by the NEW names
(`vibevm/vibespecs`, `vibevm/vibepacks`); an old-layout root gets
the loud migration recipe, never a silent walk. @status:spec/done

[p08] @fact:SCRAPE-IS-THE-TERMINAL-EXCEPTION **L6 — removal is
explicit and terminal.** The only supported transition from this layout to a
project with no `vibevm/` root is the contract-driven, health-gated,
recoverable scrape operation at
@spec://org.vibevm.core/vibevm/common/PROP-056#root. Blind deletion does not
become a legacy layout and receives no compatibility reader. @status:impl/plan

## 3. Verification {#verification}

[p09] @fact:RELAYOUT-PROOF «Ничего не сломалось» is proven, not assumed: the full
panel green over the moved world; `vibe check` 0/0/0; specmap
resolve 0 unresolved with the SAME edge count as before the move;
judging debt unchanged; a double reinstall with zero lock drift
(idempotence); INDEX targets resolving to on-disk files by script;
zero grep hits of the old roots in product code outside the layout
module; a clean-room smoke (`vibe init` → `install` → `check` in a
tempdir) on the new layout; and a cold-agent routing probe finding
the lanes under `vibevm/vibespecs/boot`. @status:spec/done