> Markdown twin of https://adna.network/reference/specification/13-collision-prevention/
> Index: https://adna.network/llms.txt · Full corpus: https://adna.network/llms-full.txt
> State is a build-time snapshot generated 2026-08-30 (UTC); nothing here is live.

# 13. Collision Prevention — aDNA Specification

> **Scan**: Three tiers — universal (frontmatter attribution, read-before-write), sync (file safety tiers, archive-don't-rename), multi-agent (coordination notes, scope declarations).

*Decisions: D7*

## 13.1 Overview

Collision prevention protects against data loss when multiple agents or humans modify the same files. The system is tiered — projects adopt the tiers they need.

```mermaid
flowchart TB
    T1["Tier 1 — Universal<br/>Every aDNA instance"]
    T2["Tier 2 — Sync Environments<br/>Cloud storage, team sync"]
    T3["Tier 3 — Multi-Agent<br/>Concurrent agents"]

    T1 --> A1["Frontmatter attribution"]
    T1 --> A2["Read-before-write"]
    T1 --> A3["New-file safety"]
    T1 --> A4["No harness-injected context"]

    T2 --> B1["File safety tiers"]
    T2 --> B2["Archive-don't-rename"]
    T2 --> B3["One config at a time"]

    T3 --> C1["Coordination notes"]
    T3 --> C2["Scope declarations"]
    T3 --> C3["Update-field check"]

    T1 -.->|extends| T2
    T2 -.->|extends| T3

    style T1 fill:#22c55e,color:#fff
    style T2 fill:#eab308,color:#000
    style T3 fill:#ef4444,color:#fff
```

## 13.2 Tier 1 — Universal

Every aDNA instance MUST implement Tier 1:

1. **Frontmatter attribution**: Every file modification MUST update `last_edited_by` and `updated` in frontmatter.
2. **Read-before-write**: Agents MUST read current file content immediately before writing. Never rely on cached reads.
3. **New-file safety**: Creating a new file has no collision risk. New files are always safe.
4. **No harness-injected context**: Governance files (`CLAUDE.md`/`STATE.md`/`AGENTS.md`) MUST NOT carry committed **harness context boundaries** — the `# userEmail` and `# currentDate (Today's date is …)` lines an agent harness injects into a running session. They are session context, not governance: once committed they are stale and information-free (the email lives in the credential broker; the date is a frozen snapshot). Strip them before committing; a session that commits a governance file MUST drop any injected tail. (ADR-042.)

## 13.3 Tier 2 — Sync Environments

Projects using file sync (cloud storage, team sync tools) SHOULD additionally implement:

1. **Safety tiers**: Classify files as Safe (content — low collision risk), Shared Config (governance, plugin configs — medium risk), or Volatile (auto-generated files like `workspace.json` — do not attempt to maintain).
2. **Archive-don't-rename**: Move files to `archive/` instead of renaming. Sync systems handle renames poorly.
3. **One config at a time**: Edit one shared config file, verify the write, then move to the next.

## 13.4 Tier 3 — Multi-Agent

Projects with multiple agents operating simultaneously SHOULD additionally implement:

1. **Coordination notes**: Use `who/coordination/` (§11) for strategic cross-agent communication.
2. **Session scope declarations**: Tier 2 sessions declare which files/directories they will modify.
3. **Update-field check**: Before modifying a file where `updated` is today and `last_edited_by` is not you, confirm with the user before overwriting.

---