Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFC-0000: govctl Governance Framework

Version: 1.1.1 | Status: normative | Phase: stable

1. Summary

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

govctl is a governance CLI that manages six 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
  • Releases: Published versions and the work items included in each version
  • Verification Guards: Reusable executable checks that turn completion requirements into auditable pass/fail gates

All artifacts follow explicit lifecycle states, phase gates, or immutability rules to ensure disciplined development.

Tags: core

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.

The current canonical RFC storage format is TOML. New repositories and repositories that have completed the RFC/clause migration MUST store each RFC as a TOML file (rfc.toml) containing:

  • [govctl] section with: id, title, version, status, phase, owners, created
  • optional [govctl] fields: updated, supersedes, refs, signature
  • [[sections]] array with ordered section definitions and clause references
  • [[changelog]] array for version history

Format evolution is tracked by the project-level [schema] version in gov/config.toml, not per-artifact fields.

Entries in sections[].clauses MUST reference clause TOML files by relative path (for example clauses/C-EXAMPLE.toml) in migrated repositories.

Repositories that have not yet completed the RFC/clause migration MAY retain legacy JSON RFC files temporarily. After govctl migrate has completed for a repository, normal govctl operations MUST create and modify RFCs only in TOML form.

Rationale: This removes the last storage-format split from RFC handling without forcing a silent in-place break for repositories that still need an explicit migration step.

Tags: core, schema

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

Tags: core, lifecycle

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)

Tags: core, lifecycle

Since: v1.0.0

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

[govctl] id = “C-REFERENCE-HIERARCHY” title = “Artifact Reference Hierarchy” kind = “normative” status = “active” since = “1.0.1”

[content] text = “”“ Governance artifacts follow a strict authority hierarchy. References between artifact types MUST respect this hierarchy.

Authority Order (highest to lowest):

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

Structured reference rules (refs fields and [[…]] link targets):

Implementations MUST validate these rules during project validation (for example govctl check).

  • RFC refs entries and [[...]] link targets MUST NOT identify an ADR or a Work Item. RFCs MUST link only to RFCs and RFC clause references (RFC-ID:C-CLAUSE).

  • ADR refs entries and [[...]] link targets MUST NOT identify a Work Item. ADRs MAY link to RFCs (including clause references) and to ADRs.

  • Work Item refs entries and [[...]] link targets MAY identify any artifact type.

Rationale:

This hierarchy prevents circular dependencies and maintains clear authority chains. An RFC that links to an ADR or Work Item in refs or [[...]] inverts the dependency direction — lower layers become authorities over the specification.

Prose outside refs and [[…]]:

Normative RFC clause text SHOULD remain self-contained. Plain prose (without [[...]]) MAY cite artifact identifiers for explanation; that form is not governed by the structured rules above.“”“

Tags: core, validation

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.

The current canonical clause storage format is TOML. New repositories and repositories that have completed the RFC/clause migration MUST store each clause as a TOML file containing:

  • [govctl] section with: id, title, kind, status
  • optional [govctl] fields: since, superseded_by, anchors
  • [content] section with: text

Format evolution is tracked by the project-level [schema] version in gov/config.toml, not per-artifact fields.

After govctl migrate has completed for a repository, normal govctl operations MUST create and modify clauses only in TOML form.

Repositories that have not yet completed the RFC/clause migration MAY retain legacy JSON clause files temporarily.

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.

Rationale: This aligns clause storage with RFC, ADR, Work Item, and Release storage while preserving an explicit migration boundary for existing repositories.

Tags: core, schema

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
  • optional [govctl] field: superseded_by
  • [content] section with: context, decision, consequences

Format evolution is tracked by the project-level [schema] version in gov/config.toml, not per-artifact fields.

Implementations MUST define a machine-readable JSON Schema for the ADR file structure and MUST validate ADR files against that schema during project validation.

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.

Tags: core, schema

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, created, refs
  • optional [govctl] fields: started, completed
  • [content] section with: description, acceptance_criteria, journal, notes
  • optional [verification] section with: required_guards, waivers

Format evolution is tracked by the project-level [schema] version in gov/config.toml, not per-artifact fields.

Implementations MUST define a machine-readable JSON Schema for the Work Item file structure and MUST validate Work Item files against that schema during project validation.

When present, verification.required_guards MUST be an array of Verification Guard IDs defined by RFC-0000:C-GUARD-DEF. These guard IDs augment project-level default guard requirements when project verification is enabled.

When present, each verification.waivers entry MUST be an object with exactly two fields: guard and reason.

The guard field MUST name exactly one Verification Guard ID.

The reason field MUST be a non-empty string.

Waiver entries MUST reference only guards that appear in the work item’s effective required guard set. Duplicate waivers for the same guard MUST be rejected during validation.

A waiver MUST suppress only the named guard. A Work Item MUST NOT disable the verification system globally.

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, and any required verification guards have passed or been explicitly waived.

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

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

Tags: core

Since: v1.0.0

6. Release Specification

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

A Release tracks a published version and the set of work items included in that version.

Release data MUST be stored as a TOML file at gov/releases.toml containing:

  • [[releases]] array with entries containing: version, date, refs

Format evolution is tracked by the project-level [schema] version in gov/config.toml, not per-artifact fields.

Each releases[].version MUST be a valid semantic version.

Each releases[].date MUST use ISO 8601 calendar date format YYYY-MM-DD.

Each releases[].refs entry MUST reference an existing Work Item ID.

A release entry has no lifecycle and MUST be treated as immutable once created.

Implementations MUST define a machine-readable JSON Schema for the release file structure and MUST validate gov/releases.toml against that schema during project validation.

Rationale: Releases are first-class governance artifacts because changelog generation and release membership depend on them. Giving releases a defined TOML structure and required JSON Schema removes the remaining schema-less storage special case.

Tags: core, release

Since: v1.0.2

7. Verification Guard Specification

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

A Verification Guard defines a reusable executable completion check for a govctl project.

Every Verification Guard MUST be stored as a TOML file under gov/guard/ containing:

  • [govctl] section with: id, title
  • optional [govctl] field: refs
  • [check] section with: command
  • optional [check] fields: timeout_secs, pattern

Format evolution is tracked by the project-level [schema] version in gov/config.toml, not per-artifact fields.

Implementations MUST define a machine-readable JSON Schema for the Verification Guard file structure and MUST validate guard files during project validation.

Verification Guard IDs MUST be unique within a repository.

A guard check MUST execute its command non-interactively from the project root.

If timeout_secs is absent, implementations MUST use a default timeout of 300 seconds.

A guard check that exceeds its timeout MUST fail.

A guard check MUST evaluate pattern, when present, against the combined standard output and standard error streams using case-insensitive regular-expression matching.

A guard check MUST pass only when the command exits successfully. If pattern is provided, the combined output MUST also match that pattern.

Rationale: Verification Guards make completion rules explicit, reusable, and machine-executable so agents cannot satisfy them with checklist text alone.

Tags: core, validation

Since: v1.1.0

Changelog

v1.1.1 (2026-03-22)

Clarify machine-validated reference hierarchy for refs and [[…]]

Added

  • Structured rules: RFC must not link ADR/WI; ADR must not link WI

v1.1.0 (2026-03-17)

Add verification guards and work-item verification metadata

Added

  • Added Verification Guard artifact definition and work-item verification fields

v1.0.2 (2026-03-17)

Record release artifact clause and migration amendments

v1.0.1 (2026-01-26)

Add artifact reference hierarchy clause

Added

  • 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