Vord

Architecture Decision Record

0007. Adopt Wyrd's governance model and the status-aware ADR lifecycle

Context

ADR-0001 inaugurates the ADR practice and fixes its lifecycle — Proposed → Accepted → Superseded — over the four document classes, but it deliberately defers to governance the questions that lifecycle leaves open: who may accept a decision, what the roles are, and how the immutability is enforced. This ADR supplies that governance. Vord is a separate project from Wyrd, but it is a sibling built by the same people for the same kind of adopters; running it under a different governance than Wyrd would be an accident, not a choice. Encoding the governance now, before outside contributors arrive, is cheap; retrofitting authority onto a project that has been operating on assumed authority is not.

Two concrete gaps make this urgent. First, the six founding ADRs were written Status: Accepted in a plaintext header before any lifecycle existed to make "Accepted" mean something — there was no board to accept them and no rule that acceptance requires settling open questions, yet ADR-0001 itself still carries [OPEN] items. Second, this whole design phase is about to add many ADRs that must be revisable in review and frozen only once settled; the lifecycle (ADR-0001) therefore needs enforcement — an immutability rule that distinguishes a draft from a ratified record, and an authority that ratifies. Wyrd already solved both (its GOVERNANCE.md and its status-aware adr-immutability check). Vord adopts that solution rather than inventing a parallel one.

Decision

  1. Adopt Wyrd's governance wholesale, recorded in Vord's own docs/governance/GOVERNANCE.md (the role ladder — Contributor, Associate, Maintainer, Founding maintainer — and the architecture board as the body with authority to accept and supersede ADRs, specifications, and proposals) and docs/governance/CODE_OF_CONDUCT.md (Contributor Covenant 3.0, adapted via The Apache Way). Eduard Ralph is the founding maintainer with transitional bootstrap authority, exactly as in Wyrd. The board, once constituted, governs Vord and Wyrd as separate bodies under one shared rulebook.

  2. Enforce that lifecycle with status-aware immutability. The lifecycle itself is inaugurated in ADR-0001 (Proposed → Accepted → Superseded); this ADR makes it operable. An ADR's status: in YAML frontmatter is the source of truth: a Proposed ADR may be edited or dropped freely; an Accepted ADR is immutable — never rewritten, only superseded by a later ADR that references it. The adr-immutability CI check reads status: from the pull request's base and freezes only records that are already Accepted/Superseded, which is what makes the Proposed→Accepted transition itself a legal edit. An ADR moves to Accepted only when it carries no unresolved [OPEN] items and the board (or, during bootstrap, the founding maintainer, provisionally) ratifies it.

  3. Migrate the founding set (0001–0006) to the frontmatter format with status: Proposed. None of the six has been ratified under this lifecycle, and ADR-0001 carries open items, so none yet meets the acceptance bar; marking them Proposed states their real condition rather than an aspirational one (the same honest posture under which most of Wyrd's own foundational ADRs remain Proposed). The immutability check's exemption for legacy, pre-frontmatter records is what permits this one-time conversion to land.

  4. Build on ADR-0001's inception, do not replace it. ADR-0001 inaugurates the ADR practice, the lifecycle, and the four document classes; this ADR supplies the who decides (roles, board, provisional bootstrap authority) and the enforcement that operate them, and does not alter the classes. Licensing, the DCO, and dependency-selection criteria — the other half of Wyrd's founding governance — are the sibling decision recorded in ADR-0008.

Consequences

  • Vord and Wyrd share one governance, so a contributor moves between the two projects without relearning the rules, and a single architecture board can hold both to a consistent bar.
  • Nothing is "Accepted" until ratified [OPEN]-free. Expect most design-phase ADRs — including this one — to sit Proposed for a while; that is the honest state of a design still settling, not a deficiency.
  • The status-aware immutability rule removes the failure mode of "immutable from creation" (a draft that cannot be corrected): a Proposed ADR is revised in review and frozen exactly at the moment it is accepted, and not before.
  • This ADR is itself Proposed; it is accepted once the founding maintainer ratifies it under the bootstrap rule — a deliberately small act, consistent with the governance it adopts. Until then it is the working description of how Vord intends to govern its decisions.
  • Governance documents live in docs/governance/ (GitHub-facing), outside the published design/ tree, mirroring Wyrd; the rendered site is unaffected.