RFC-0000: govctl Governance Framework

Version: 1.0.0 | 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

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

Changelog

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