ADR Vault
"A tool that works for mysterious reasons is not a tool — it is a ritual. Zenzic works for documented reasons. This vault is the proof."
This page is the complete index of Architectural Decision Records (ADRs) for the Zenzic project. Each ADR documents a major technical decision: its context (why the problem existed), its decision (what was chosen), and its invariants (what must never change as a consequence).
For day-to-day contribution flow, release checks, and governance enforcement, follow the operational runbook instead:
ADRs are the immutable memory of the project. They explain not only what Zenzic does, but why. Operational behavior at commit and push time is governed by the Developer Release and Governance Protocol.
Genesis Decisions
These ADRs define the philosophical and technical foundations on which all subsequent decisions rest.
| ADR | Title |
|---|---|
| ADR 001 | Lint the Source, Not the Build |
| ADR 002 | Zero Subprocesses Policy (Maintainer Only) |
Core Architecture Decisions
These ADRs document the structural decisions for the current architecture.
| ADR | Title |
|---|---|
| ADR 003 | Root Discovery Protocol |
| ADR 004 | Decentralized CLI Package |
| ADR 005 | Z404 Agnostic Universalism |
| ADR 007 | Sovereign Sandbox (Maintainer Only) |
| ADR 008 | Bilingual Structural Invariant |
| ADR 009 | Path Sovereignty |
| ADR 013 | The Regex Anti-Corruption Layer (ReDoS Protection) |
| ADR 015 | Native Telemetry Validation |
| ADR 020 | Parallel Audit Completeness vs. Fail-Fast |
Documentation Site Decisions
These ADRs document architectural decisions specific to this documentation site
(zenzic.dev) — choices about how the Docusaurus site is built, localized, and
maintained.
| ADR | Title |
|---|---|
| ADR 006 | Unified Scan Scope (Storage + Blog) |
Reading Guide
Each ADR follows a consistent structure:
-
Context — the problem that existed before the decision was made. Reading
the Context of an ADR tells you what pain the decision was eliminating.
-
Decision — the choice that was made, stated precisely and without
ambiguity. If you ever wonder "why does Zenzic do X?", the Decision section of the relevant ADR is the answer.
-
Rationale — the engineering reasoning behind the decision. This section
is the "why not the alternative?" — it records the rejected approaches and explains why they were insufficient.
-
Invariants — the constraints that must never be violated as a consequence
of the decision. These are permanent. They do not expire with version increments. A PR that violates an invariant listed in an ADR is an automatic revert candidate, regardless of its other merits.
-
Consequences — the known trade-offs and capabilities that the decision
enables or forecloses. Reading Consequences helps contributors understand the boundaries of what Zenzic can and cannot do by design.
Adding a New ADR
For the step-by-step procedure on how to propose and record a new Architectural Decision Record, see the ADR contribution guide.