ADR-002 — Documentation First

Status: Accepted
Date: 2026-06-28
Phase: 12-1A
Deciders: Platform Architect
Supersedes: None — codifies ERP Principle 1 / EOS Principle 6

---

Context

AI-assisted engineering fails when IDE-injected rules duplicate or contradict docs/. ERP v1.0 established Documentation First at runtime layer. ZEP must codify this as a permanent platform invariant spanning years and multiple products.

---

Decision

Documentation First is Platform Engineering Principle E1 and Architecture Principle A-layer invariant:

1. Platform specifications and manifests in platform repository are canonical authority
2. Adapter workspace files are mirrors — they implement, never redefine
3. Conflict resolution: documentation beats adapter text beats chat history
4. Validation tests enforce manifest ↔ workspace parity
5. Products may extend via registry only — not by editing vendored platform docs

Canonical documentation hierarchy for platform concerns:

PLATFORM_CONSTITUTION
    → PLATFORM_BOUNDARIES / PUBLIC_API / EXTENSION_MODEL / VERSIONING
    → Runtime Contracts
    → Runtime specification
    → Adapter profiles
    → Materialized workspace

---

Consequences

Positive

• Multi-year stability — contracts outlive IDE vendors
• Onboarding clarity — one documentation chain
• CI-detectable drift

Negative

• Documentation phases required for behavioral changes
• Cannot "quick fix" in .cursor/ without manifest update

---

Alternatives considered

Alternative	Rejected because
IDE-first governance	Not portable; not auditable
Dual authority (docs + rules equal)	Conflict ambiguity
Generated docs from adapter	Inverts authority

---

ADR-002 — Documentation First is non-negotiable for ZEP.