PROP-012: The managed redirect block — vibevm as a co-tenant of the agent instruction files

1. Motivation

• 06PROP-009 §2.3 has vibe install generate the CLAUDE.md / AGENTS.md / GEMINI.md thin redirect that points a session at the boot artifacts.
• The Phase-4 implementation — vibe-workspace::boot_artifacts::write_boot_artifacts — does this with an unconditional whole-file fs::write: every vibe install / vibe reinstall / vibe uninstall / vibe update replaces the entire file with vibevm's generated content.

• 07This is wrong, and it is wrong in the most damaging possible place.

08CLAUDE.md / AGENTS.md / GEMINI.md are not vibevm's files. They are the shared contact surface every coding agent reads at session start, and many parties legitimately write there:

• 09the developer's own hand-authored project instructions;
• another tool, agent, framework, or convention the developer runs alongside vibevm — vibevm must assume it is never the only tenant of a repository;
• in the vibevm repository itself, CLAUDE.md is today ~200 hand-authored lines carrying the four non-negotiable rules and the session-end command.

• 10A whole-file overwrite silently destroys every byte of that.
• The first vibe install in any project with a non-trivial CLAUDE.md is a data-loss event — and it destroys precisely the file a developer is most likely to have invested in by hand.

• 11It also contradicts vibevm's own founding rule. PROP-009 §2.1 — the C++-#include rule — is that installing a dependency must never modify a node's authored content.
• The redirect write violates exactly that, for the most visible authored file in the project.

• 12The fix is the standard managed-block discipline (the general problem and the co-tenant law: the managed-blocks flow's spec://org.vibevm.world/managed-blocks/flows/managed-blocks/MANAGED-BLOCKS-PROTOCOL#problem) — the shape ssh, shell-rc installers, and countless config tools already use: vibevm owns one small, clearly-delimited, machine-findable region of each instruction file, and never touches a byte outside it.
• vibevm becomes a good co-tenant — it writes its redirect into its own pen and leaves the rest of the file to whoever else shares it.

2. Decisions

<vibevm>
<!-- Generated by vibe — do not edit inside this block. It is rewritten on `vibe install`. -->
... the boot redirect (§2.6) ...
</vibevm>

3. Command and crate surface

40design r1

• 41vibe-workspace::boot_artifacts — the implementation site. write_boot_artifacts's redirect loop changes from a whole-file fs::write to a locate-validate-splice. New helpers: locate the block, classify well-formedness, splice the body. render_redirect becomes the block-body renderer; REDIRECT_BODY's "do not edit" framing moves inside the block.
• The install orchestration (apply_resolution and the vibe reinstall path) — gains the §2.5 plan-time validation pass over every node's instruction files before any mutation.
• vibe-cli — vibe install / reinstall / uninstall / update surface the malformed-block abort as a clear error; vibe init scaffolds each instruction file with a <vibevm> block instead of a one-line file.
• vibe-check — CheckId::RedirectBlock reports a malformed <vibevm> block (a file with anything other than zero markers or one ordered pair), composing with the boot-directory check.
• Exit code — the malformed-block abort is conflict-shaped; reusing exit code 3 (package conflict) is the working assumption (§5).

4. Migration

42req r1

43The one non-trivial case is an instruction file that is wholly the old whole-file generated redirect — written by the Phase-4 fs::write, recognisable by its generated header, and carrying no <vibevm> markers. For a file with no markers, vibe:

• 44if the entire file is recognisably the old whole-file generated redirect (it matches the known generated header) — replaces it with a clean file containing just the <vibevm> block. The old content was vibevm's; reclaiming it as a block loses nothing.
• otherwise — takes the §2.3 absent → create path: appends a block, preserves everything else.

• 45This is also the gentle path for the vibevm repository's own self-migration (PROP-009 §4 / M1.18 Phase 7).
• vibevm's CLAUDE.md / AGENTS.md / GEMINI.md are hand-authored — not the generated form — so they take the append path: every hand-authored line, including the four non-negotiable rules, stays, and a <vibevm> block is appended.
• The destructive whole-file write is what made the Phase-7 self-migration delicate; with PROP-012 it is not.

46Because the defect is in shipped code, PROP-012 must land before any vibe install / vibe reinstall is run against a project with a real CLAUDE.md — including the vibevm repository itself. It is therefore a prerequisite of the Phase-7 redirect rewrite, not a successor to it (§7).

5. Open questions

1. 47Exit code. Reuse 3 (package conflict — a malformed managed block is conflict-shaped) or mint a dedicated code? Leaning: reuse 3.
2. Old-redirect detection for migration (§4). Match the exact Phase-4 generated-header string (precise; a false positive would wrongly destroy a hand-authored file) versus a looser heuristic. Leaning: exact string match.

48Closed in draft 2: the marker syntax — bare <vibevm> … </vibevm> tags (§2.2), chosen for legibility to an LLM; the markdown-rendering cosmetics are an accepted, deferred cost.

6. Rejected / deferred alternatives

• 49The whole-file overwrite (the shipped Phase-4 status quo). Rejected — it destroys co-tenant content; undoing it is the reason this PROP exists.
• Heuristic or LLM-assisted block detection ("find the part that looks like vibevm's"). Rejected — the region that gates a mutating write must be found by a deterministic byte scan, with no model and no guessing.
• Auto-repairing a malformed file (delete the surplus marker, keep the first block). Rejected — vibevm never decides which of two regions is canonical; a malformed file is a hard stop for the human (§2.3).
• A sidecar file (.vibe/redirect, a vibe-owned file the agent is pointed at) instead of a block inside CLAUDE.md. Rejected — the entire value of CLAUDE.md / AGENTS.md / GEMINI.md is that every agent already reads them with zero configuration (PROP-009 §6.1's cross-agent property). A sidecar the agent does not natively read forfeits that.

7. Phase plan

1. 50The block engine in vibe-workspace::boot_artifacts — locate / classify / splice; write_boot_artifacts's redirect loop reworked; unit tests for every well-formedness class (absent, well-formed, each malformed shape, byte-identical no-op).
2. Plan-time validation wired into apply_resolution and the vibe reinstall path; the malformed-block abort surfaced by vibe install / reinstall / uninstall / update; vibe init scaffolds the block.
3. Migration of the old whole-file generated redirect (§4).
4. vibe check finding, the docs/ note, and the VIBEVM-SPEC.md §6.1 / §4.2 wording (inside the M1.18 Phase-7 spec-consistency pass).

51Sequencing. PROP-012 corrects shipped Phase-1–6 behaviour and is a prerequisite for PROP-009 §4 / the M1.18 Phase-7 redirect rewrite — the vibevm self-migration must not be able to destroy CLAUDE.md. Recommended: implement PROP-012 within M1.18 Phase 7, ahead of the self-migration step, rather than as a later standalone milestone. Owner to confirm.

8. Version history

• 522026-05-22 — draft 1. Requirements captured in an owner discussion during M1.18 Phase-7 planning. The whole-file redirect overwrite shipped in PROP-009 Phase 4 is destructive to co-tenant content; vibevm must own only a <vibevm>-delimited block of each agent instruction file: exactly one block per file, a hard stop on a malformed file (the user repairs it by hand — vibevm never guesses), absent → create at end of file, present → splice, validated at plan time. The block's position is thereafter the user's — vibevm never relocates it, so the user can promote the block to a "First Prompt" or leave it a sidecar. Recorded as a separate PROP at the owner's request.
• 2026-05-22 — draft 2. Owner review settled the one substantive §5 question — the marker syntax: bare <vibevm> … </vibevm> tags (§2.2), chosen because they read unambiguously to an LLM, the file's primary consumer; the markdown-rendering cosmetics of a bare tag are an accepted, deferred cost. The two remaining §5 questions — the exit code and old-redirect detection — are implementation details with working answers. PROP-012 is ready for implementation within M1.18 Phase 7.
• 2026-06-12 — unit typing (the depth program). §2.1–2.5 and §4 typed req r1, §2.6 and §3 typed design r1; the Status line updated to reflect the shipped M1.18 Phase-7 implementation (the audit's finding 2026-06-12-04 recorded PROP-012 as implemented-with-zero-edges; the affirmation sweep tags the implementation against these units).