RFC-0000: govctl Governance Framework

Version: 1.0.1 | Status: normative | Phase: stable

1. Summary

[RFC-0000:C-SUMMARY] Framework Summary (Informative)

govctl is a governance CLI that manages four artifact types:

RFCs: Normative specifications that define intent and constraints
Clauses: Individual requirements within RFCs
ADRs: Architectural Decision Records documenting design choices
Work Items: Units of work tracking implementation progress

All artifacts follow explicit lifecycle states and phase gates to ensure disciplined development.

Since: v1.0.0

2. RFC Specification

[RFC-0000:C-RFC-DEF] RFC Definition (Normative)

An RFC (Request for Comments) is a normative document that defines intent, constraints, or decisions governing implementation.

An RFC is not a suggestion. It is law.

Every RFC MUST be stored as a JSON file (rfc.json) containing:

rfc_id: Unique identifier (e.g., RFC-0001)
title: Human-readable title
version: Semantic version (MAJOR.MINOR.PATCH)
status: Lifecycle state (draft | normative | deprecated)
phase: Work stage (spec | impl | test | stable)
owners: List of responsible parties
sections: Ordered list of sections with clause references
changelog: Version history

Since: v1.0.0

[RFC-0000:C-STATUS-LIFECYCLE] RFC Status Lifecycle (Normative)

RFC status follows this lifecycle:

draft → normative → deprecated

draft: Under discussion. Implementation MUST NOT depend on draft RFCs.

normative: Frozen and ratified. Implementation MUST conform to normative RFCs.

deprecated: Superseded or obsolete. Implementation SHOULD migrate away.

Transition rules:

draft → normative: Requires explicit finalization
normative → deprecated: Requires a superseding RFC or explicit deprecation
Reverse transitions are FORBIDDEN

Since: v1.0.0

[RFC-0000:C-PHASE-LIFECYCLE] RFC Phase Lifecycle (Normative)

RFC phase follows this lifecycle:

spec → impl → test → stable

spec: Defining what will be built. No implementation work permitted.

impl: Building what was specified. Implementation proceeds per spec.

test: Verifying implementation matches specification.

stable: Released for production use.

Phase rules:

Phases MUST proceed in order; skipping is FORBIDDEN
Each phase transition requires the previous phase gate to pass
draft + stable is FORBIDDEN (cannot stabilize unratified work)
deprecated + impl/test is FORBIDDEN (no new work on deprecated specs)

Since: v1.0.0

[RFC-0000:C-REFERENCE-HIERARCHY] Artifact Reference Hierarchy (Normative)

Governance artifacts follow a strict authority hierarchy. References between artifact types MUST respect this hierarchy.

Authority Order (highest to lowest):

RFC — Constitutional law. Defines what the system does.
ADR — Interpretation. Documents decisions implementing RFCs.
Work Item — Execution. Tracks work implementing ADRs and RFCs.

Reference Rules:

RFCs MUST NOT reference ADRs in normative clause text. RFCs are self-contained specifications. If an RFC needs to describe a decision, the decision MUST be stated directly in the RFC, not delegated to an ADR.

ADRs MAY reference RFCs to establish authority for decisions. ADRs SHOULD cite the RFC clause that the decision interprets or implements.

Work Items MAY reference any artifact type. Work Items typically reference the RFC or ADR they implement.

Rationale:

This hierarchy prevents circular dependencies and maintains clear authority chains. An RFC that references an ADR inverts the hierarchy — the ADR becomes the authority, which defeats the purpose of having RFCs as constitutional law.

Changelog entries and informative notes MAY mention ADRs for historical context, but normative clause text MUST remain self-contained.

Since: v1.0.1

3. Clause Specification

[RFC-0000:C-CLAUSE-DEF] Clause Definition (Normative)

A clause is an individual requirement or statement within an RFC.

Every clause MUST be stored as a JSON file containing:

clause_id: Unique identifier within the RFC (e.g., C-PHASE-ORDER)
title: Human-readable title
kind: normative | informative
status: active | superseded | deprecated
text: The clause content
since: Version when the clause was introduced

Clause kinds:

normative: Defines a requirement. Implementations MUST comply.
informative: Provides context. No compliance requirement.

Deprecation is a lifecycle state (in status), not a document kind.

Since: v1.0.0

4. ADR Specification

[RFC-0000:C-ADR-DEF] ADR Definition (Normative)

An ADR (Architectural Decision Record) documents a significant design decision.

Every ADR MUST be stored as a TOML file containing:

[govctl] section with: id, title, status, date, refs
[content] section with: context, decision, consequences

ADR status lifecycle:

proposed → accepted → superseded
         → rejected

proposed: Under consideration. Not yet binding.

accepted: Ratified. Design SHOULD follow this decision.

rejected: Declined after consideration. Reason documented in decision field.

superseded: Replaced by a newer ADR. Listed in superseded_by field.

Since: v1.0.0

5. Work Item Specification

[RFC-0000:C-WORK-DEF] Work Item Definition (Normative)

A Work Item tracks a unit of work from inception to completion.

Every Work Item MUST be stored as a TOML file containing:

[govctl] section with: id, title, status, refs
[content] section with: description, acceptance_criteria, decisions, notes

Work Item status lifecycle:

queue → active → done
    ↘        ↘ cancelled

queue: Planned but not started.

active: Currently in progress. Only one active item recommended per focus area.

done: Completed. All acceptance criteria met.

cancelled: Abandoned from queue or active. Reason documented in notes.

A Work Item MUST NOT transition to done if any acceptance_criteria are pending.

Since: v1.0.0

Add C-REFERENCE-HIERARCHY clause defining that RFCs must not reference ADRs

v1.0.0 (2026-01-17)

Initial stable release of the govctl governance framework.

Added

RFC specification with status and phase lifecycle
Clause specification for normative and informative requirements
ADR specification for architectural decisions
Work Item specification for task tracking

Keyboard shortcuts

govctl