Skip to main content

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).

ADRs are the immutable memory of the project. They explain not only what Zenzic does, but why — so that future contributors can extend the system without unknowingly violating the constraints that make it trustworthy.

Genesis Decisions​

These ADRs were established before the first public release. They define the philosophical and technical foundations on which all subsequent decisions rest.

ADRTitleSprint
ADR 001Lint the Source, Not the BuildGenesis (pre-v0.1.0)
ADR 002Zero Subprocesses PolicyGenesis (pre-v0.1.0)

Core Architecture Decisions​

These ADRs document the structural decisions made during the active development of Zenzic v0.6.x and v0.7.0.

ADRTitleSprint
ADR 003Root Discovery ProtocolD036 / ZRT-005
ADR 004Decentralized CLI PackageD062-B / D064
ADR 005Z404 Agnostic UniversalismD087
ADR 007Sovereign SandboxD043
ADR 008Bilingual Structural InvariantD045
ADR 009Path SovereigntyCEO-052

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.

ADRTitleSprint
ADR 006Unified Perimeter (Storage + Blog)CEO 051
ADR 011Cross-Instance Absolute Path AllowlistEPOCH 5 (v0.7.0)

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​

When a significant architectural decision is made — one that constrains future contributors or resolves a structural tension — it must be recorded here.

  1. Create developers/explanation/adr-<slug>.mdx with the next

    available ADR number.

  2. Create the Italian mirror at the corresponding path in i18n/it/.

  3. Add both files to the table above in the appropriate section.

  4. Record the decision in the [ADR] section of the relevant Zenzic Ledger

    (.github/copilot-instructions.md) in the repository where the decision was implemented.

The ADR is permanent once published. To amend a decision, add a new ADR that references the original and documents the amendment — never rewrite history.