The Governance Hierarchy: How Documentation Governs Engineering Decisions in VANI

Most software projects have informal governance: senior engineers make decisions, junior engineers follow, PRs are reviewed, and the decisions live in people's heads. VANI codifies a formal document hierarchy that governs every decision from vision to implementation.

GOVERNANCE.md defines this hierarchy as version 2.0 (indicating the governance system itself has evolved).

VISION.md                    ← Frozen (Architecture Constitution)
        ↓
FOUNDATION.md                ← Frozen (Architectural Laws)
        ↓
Accepted ACPs                ← Architecture Change Proposals
        ↓
Accepted ADRs                ← Architectural Decision Records
        ↓
Engineering Program          ← Phase planning and delivery
        ↓
Technology Strategy          ← Technology selection decisions
        ↓
AI Models Document           ← AI-specific decisions
        ↓
Architecture Documents       ← Subsystem architecture specs
        ↓
Specifications               ← Detailed implementation specs
        ↓
Implementation               ← Source code
        ↓
Certification                ← Validation evidence

"Higher authority always overrides lower authority."

VISION.md — Frozen. Cannot be changed without an approved ACP. Defines what VANI is, what it is not, and the core architectural invariants. Questions at this level: "Is VANI a chatbot?" "Does VANI prioritize local execution?"

FOUNDATION.md — Frozen. The 10 Architectural Laws. Questions at this level: "Can this module have global mutable state?" "Can services call each other directly?" Violations require ACPs.

ACPs (Architecture Change Proposals) — Formal process for proposing changes to frozen architecture. Like a Constitutional Amendment process. Required before modifying VISION.md or FOUNDATION.md constraints.

ADRs (Architectural Decision Records) — Decisions about how to implement architecture. Questions at this level: "Should we use constructor DI or service locator?" "Should logging be centralized or per-service?" ADRs can be superseded by later ADRs but cannot contradict FOUNDATION.md.

Engineering Program — Phase plans, milestones, delivery timelines. Governed by accepted ADRs.

Technology Strategy / AI Models — Technology selections that serve the architecture. Cannot contradict ADRs.

Architecture Documents — Per-subsystem architecture specs. Each must follow the Foundation laws and accepted ADRs.

Specifications / Implementation / Certification — Bottom layers. Implementation follows specifications; certification validates implementation.

From docs/adr/README.md:

ADR lifecycle: Draft → Review → Accepted → Superseded → Deprecated

ADRs are required for:

• New subsystem frameworks
• Communication mechanism changes
• Security model changes
• Data storage changes
• External API introductions
• Cross-domain interface changes

ADRs are NOT required for:

• Internal refactoring within existing architecture
• Adding tests
• Performance optimization within existing design
• Documentation updates

Approval pipeline: Author → Architecture Review → Lead Approval → Merge

For changes to frozen components (FOUNDATION.md, VISION.md), an Architecture Change Proposal is required. From FOUNDATION.md:

ACP is required when:

• Modifying a frozen architectural document
• Changing a principle in FOUNDATION.md or VISION.md
• Modifying architectural laws
• Introducing an architectural pattern that contradicts existing laws

• docs/architecture/GOVERNANCE.md — Governance hierarchy (version 2.0, frozen)
• docs/architecture/FOUNDATION.md — ADR and ACP process sections
• docs/adr/README.md — ADR lifecycle, required triggers, not-required triggers, approval pipeline
• docs/adr/ADR-001 through ADR-008 — Accepted ADRs (Phase 1)
• docs/vision/VISION.md — "Frozen (Architecture Constitution)" status

Established: The governance hierarchy is documented in GOVERNANCE.md v2.0 and cross-referenced in FOUNDATION.md. The ADR process with lifecycle states (Draft → Review → Accepted → Superseded → Deprecated) is implemented.

Established: 8 ADRs have been accepted through this process (Phase 1). The frozen status of VISION.md and FOUNDATION.md is explicitly marked.

Established: The ACP process is defined for frozen components. No ACPs have been filed yet (Phase 0 and early Phase 1 haven't required modifying frozen architecture).

Observation: The governance system is more elaborate than most single-developer projects need. The system is explicitly designed for a 50-year lifespan with a single developer — creating formal governance now means future collaborators (or the future developer's future self) have documented decision history.

Observation: All 8 ADRs have "Date: YYYY-MM-DD" (unfilled). This is a gap in the governance process — ADRs without dates lose temporal context.

A governance hierarchy makes implicit authority explicit. Most projects have a de facto authority hierarchy (founder > senior engineers > junior engineers) that is never documented. When the founder or senior engineer leaves, the authority structure is lost. Documenting it creates a persistent, inspectable decision framework.

The "documentation is architecture" principle: VANI explicitly states "Documentation Is Part of the Architecture" in its lessons learned. The governance hierarchy is not separate from the architecture — it is the architecture's maintenance system.

For any long-lived system (more than 3 years), documenting the authority structure of architectural decisions produces more long-term value than speed of delivery. The alternative — decisions living in people's heads — creates technical debt every time someone leaves the project. For a single-developer project with a 50-year horizon, the "decision history" value of ADRs is even more important because the developer will forget what they decided and why.

• docs/architecture/GOVERNANCE.md — Governance hierarchy, engineering workflow, ACP process
• docs/adr/README.md — ADR lifecycle and process
• docs/architecture/FOUNDATION.md — ADR/ACP process sections (lines 654–696)
• docs/vision/VISION.md — Frozen constitution