RFC-0000: govctl Governance Framework

Version: 1.7.0 | Status: normative | Phase: stable Owners: @govctl-org Tags: core, schema, validation, lifecycle

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: Local version-cut records 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 constrained mutation 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 canonical RFC storage format is TOML. Repositories 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).

The RFC version field is lifecycle-owned. Resource editing operations MUST NOT modify the RFC version field.

An RFC MUST have exactly one current changelog entry whose version equals the RFC’s current version. Other changelog entries are historical versions. Validation MUST reject an RFC with zero current changelog entries. Validation MUST reject an RFC with multiple current changelog entries. Current-changelog field operations MUST reject either invalid state without mutation.

The current entry’s summary and categorized changes MAY be corrected without changing the RFC version or phase. Changelog version fields are lifecycle-owned. Changelog date fields are lifecycle-owned. Resource editing operations MUST NOT modify either lifecycle-owned field. Resource editing operations MUST NOT modify any historical changelog entry.

Implementations MUST reject legacy RFC JSON storage files (rfc.json) during normal operations. The diagnostic MUST instruct users to migrate those repositories with a govctl version earlier than 0.9 before upgrading to a TOML-only govctl release.

Rationale: The current changelog entry describes the current RFC version and may need refinement while that version is authored. Matching by version avoids relying on array position. Keeping version identity, dates, and historical entries lifecycle-owned preserves version provenance.

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: The RFC lineage is ratified. A normative version in impl, test, or stable is sealed, and implementation MUST conform to that sealed version. A normative version in spec is a controlled authoring candidate and MUST NOT be used as an implementation conformance baseline. The most recently sealed version remains the implementation baseline until the current spec version enters impl.

deprecated: Superseded or obsolete. Implementation SHOULD migrate away.

Transition rules:

The draft -> normative transition MUST require explicit finalization.
The normative -> deprecated transition MUST require a superseding RFC or explicit deprecation.
Reverse status transitions MUST be rejected.

Rationale: Normative status ratifies the RFC lineage, while phase identifies whether its current version is still being authored or has been sealed for implementation. This distinction permits controlled current-version authoring without presenting mutable spec content as a binding implementation contract.

Tags: core, lifecycle

Since: v1.0.0

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

RFC phase describes the current RFC version and follows this lifecycle within that version:

spec -> impl -> test -> stable

spec: Authoring the current version candidate. Implementation work against that candidate MUST NOT begin.

impl: Building what the sealed current version specifies.

test: Verifying implementation against the sealed current version.

stable: Implementation and tests for the sealed current version are complete.

Phase rules:

Phases within one version MUST proceed in order.
Phase transitions MUST NOT skip a phase.
Each phase transition MUST satisfy the preceding phase gate.
stable MUST be terminal for one RFC version.
A version-changing bump MUST be rejected while the current version remains in spec.
A later version-changing bump MAY start another phase lifecycle only when the current version is in impl, test, or stable.
A version bump that releases a detected content amendment MUST start the new version at spec.
Only a normative RFC MAY advance from spec to impl.
While phase is spec, RFC and clause content belongs to the current version candidate and MAY change without another version bump.
The spec -> impl transition MUST set or replace the stored amendment signature with a signature of the current RFC and clause content.
The spec -> impl transition MUST reject pending clauses as defined by RFC-0000:C-CLAUSE-DEF.
Changelog-only updates MUST preserve phase.
Changelog-only updates MUST NOT change the amendment signature.
In impl, test, or stable, content that differs from the stored amendment signature is an unversioned amendment.
An unversioned amendment MUST be released by a version bump before further phase progression.
A normative RFC in impl, test, or stable MUST have a stored amendment signature. A version-changing bump or later phase progression MUST reject a missing signature without mutation and MUST leave pending clauses unchanged.
A draft RFC MUST NOT enter stable.
A deprecated RFC MUST NOT enter impl or test.

For amendment detection, RFC content is the canonical RFC and clause data other than RFC version, phase, changelog, and signature fields. Those four fields are lifecycle or changelog bookkeeping and MUST be excluded from amendment comparison. A stored signature is the sealed content baseline for the current version after it enters impl. While the version remains in spec, establishing or replacing that baseline MUST NOT be treated as a content amendment. While the version remains in spec, establishing or replacing that baseline MUST NOT require another version bump.

Rationale: Scoping phase to one version lets later amendments reuse the existing ordered gates. The spec phase is the mutable authoring boundary for that version, and entry into impl seals the exact contract that implementation follows. Defining the comparison surface prevents phase progression and changelog bookkeeping from recursively appearing as new content amendments. Rejecting another version-changing bump from spec prevents an unsealed candidate from becoming compatibility history. A missing signature outside spec cannot establish a trustworthy amendment baseline through a version change; it requires migration or restoration of the sealed baseline.

Tags: core, lifecycle

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.

Structured reference rules:

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

RFC refs entries, [[...]] link targets, and known artifact-ID mentions in governed RFC clause text MUST NOT identify an ADR or a Work Item.
ADR refs entries, [[...]] link targets, and known artifact-ID mentions in governed ADR content fields MUST NOT identify a Work Item.
Work Item refs entries and [[...]] link targets MAY identify any artifact type.

Known artifact-ID mentions in reviewable governed RFC clause text, governed ADR content fields, and governed Work Item prose SHOULD use [[artifact-id]] inline reference syntax. This inline syntax expectation does not apply to structured refs field entries.

For this inline syntax warning, reviewable governed prose means draft RFC clause text, proposed ADR content fields, and Work Item description, notes, and acceptance criteria for Work Items that are not done.

Project validation SHOULD report a warning when a known artifact ID appears in reviewable governed prose outside [[...]] inline reference syntax.

Project validation MAY omit this inline syntax warning for accepted, stable, deprecated, superseded, done, or otherwise historical artifacts.

Unknown artifact-ID-shaped text MAY appear as an example without being treated as an artifact reference.

This clause only defines the RFC/ADR/Work Item authority hierarchy and inline reference syntax expectations. It does not impose additional target-kind restrictions for artifact types outside that hierarchy.

Rationale:

This hierarchy prevents circular dependencies and maintains clear authority chains. An RFC that links to or names an ADR or Work Item as a governed reference inverts the dependency direction — lower layers become authorities over the specification.

Inline reference syntax makes artifact links explicit in source while allowing rendered projections to remain human-readable. A validation warning gives reviewers source-level evidence for raw reference syntax without requiring them to infer it from rendered output. Limiting this warning to reviewable artifacts avoids forcing historical backfill before existing accepted or completed artifacts can pass normal project validation.

Prose outside governed reference surfaces:

Normative RFC clause text SHOULD remain self-contained. Non-governed explanatory text MAY mention artifact identifier shapes as examples, but known lower-authority artifact identifiers in governed RFC clause text and governed ADR content fields are validated as references even without [[...]] delimiters.

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 canonical clause storage format is TOML. Repositories 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.

Implementations MUST reject legacy clause JSON storage files (gov/rfc/<RFC-ID>/clauses/*.json) during normal operations. The diagnostic MUST instruct users to migrate those repositories with a govctl version earlier than 0.9 before upgrading to a TOML-only govctl release.

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.

The since field identifies the first RFC version that contains the clause. A clause whose since field is absent is a pending clause. since is lifecycle-owned: generic editing MUST NOT set, change, or remove it. Finalization and version bumps MUST assign since only to pending clauses and MUST preserve every non-pending clause’s existing since value.

Clause creation and version assignment MUST follow these rules:

A new clause in a draft RFC MUST be pending.
Finalizing a draft RFC as normative MUST assign the RFC’s current version to every pending clause.
A new clause in a normative RFC whose phase is spec MUST set since to the RFC’s current version.
A new clause in a normative RFC whose phase is impl, test, or stable MUST be pending.
A version bump of a normative RFC MUST assign the new RFC version to every pending clause.
Creating a clause in a deprecated RFC MUST be rejected.

Permanent clause deletion MUST be allowed when the containing RFC is draft. Permanent clause deletion MUST also be allowed when the containing RFC is normative, its phase is spec, and the clause since equals the RFC current version. Permanent deletion MUST be rejected for every other RFC status, phase, or clause-version combination. Permanent deletion MUST reject a clause referenced by any other artifact and MUST report the referencing artifact IDs.

Advancing a normative RFC from spec to impl MUST reject every pending clause. That transition MUST NOT assign clause version metadata. That transition MUST NOT rewrite existing clause version metadata.

Rationale: A clause can record its version immediately only after that target version is known. Initial draft clauses receive a version only at finalization, amendments created outside spec receive a version at the next normative RFC bump, and clauses added to an already-open normative spec version can safely use the current version. This preserves version provenance without making phase advancement own clause metadata. Lifecycle-only assignment and preservation make since == current version reliable evidence that a Clause belongs only to the open candidate, while the reference gate prevents dangling governance links.

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

[RFC-0000:C-ADR-PROJECTION-OWNERSHIP] ADR Projection Ownership (Normative)

ADR source fields and rendered projections MUST have one canonical owner for each semantic section.

The ADR renderer owns the artifact title and the fixed Context, Decision, Consequences, and Alternatives Considered section headings. The structured refs field owns the rendered reference inventory. Structured content.alternatives entries own their generated alternative headings and trade-off labels.

ADR content fields MUST contain section body prose rather than reproducing renderer-owned structure.

A conflicting heading is a Markdown heading recognized by CommonMark parsing outside a code block whose visible text, after surrounding whitespace is removed, matches one of the following using ASCII case-insensitive comparison:

the rendered artifact title <ADR-ID>: <title>;
Context, Decision, Consequences, References, Alternatives Considered, or the semantic alias Options Considered;
a heading generated for a structured alternative: its text, followed by (accepted) or (rejected) when that status suffix applies.

Project validation MUST inspect content.context, content.decision, and content.consequences in proposed ADRs for conflicting headings. Project validation MUST report a validation error for each conflict. Each diagnostic MUST identify the content field. Each diagnostic MUST identify the conflicting visible heading text.

ADR acceptance MUST apply the same projection-ownership validation before changing status. A force option that bypasses alternatives-completeness checks MUST NOT bypass projection-ownership validation.

Project validation MAY omit projection-ownership diagnostics for ADRs that are no longer proposed so that historical artifacts do not become invalid solely because govctl gained this validation.

Inline references that support nearby prose remain valid. This clause does not prohibit contextual [[...]] references inside content fields.

Rationale: A single owner for each rendered section prevents structurally valid source fields from producing duplicated or contradictory human-readable ADRs. CommonMark heading events distinguish actual headings from examples in fenced code blocks and normalize inline formatting to visible text. Acceptance-time enforcement prevents a proposed violation from escaping validation by becoming historical.

Since: v1.4.0

5. Work Item Specification

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

A Work Item tracks a unit of work from inception through a release-eligible completion. Release membership freezes its lifecycle status.

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

[govctl] section with required fields: id, title, status, created
optional [govctl] fields: started, completed, refs
[content] section with required field: description
optional [content] fields: acceptance_criteria, notes
optional [verification] section with: required_guards, waivers

Omitted list-valued fields refs, acceptance_criteria, notes, verification.required_guards, and verification.waivers MUST be interpreted as empty lists.

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 transitions:

queue → active
queue → cancelled
active → done
active → cancelled
done → active (unreleased only)

queue: Planned but not started.

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

done: Completed and eligible for release. 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 contain at least one acceptance criterion before it transitions to done.

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

A done Work Item that is not referenced by a release MUST be allowed to return to active. This transition MUST preserve started and remove completed.

A Work Item referenced by a release MUST remain done.

Rationale: An unreleased completion is a correctable judgment. Release membership supplies the immutable lifecycle boundary without adding another persisted Work Item status. Omitting empty list fields keeps the TOML representation minimal without changing the logical data model.

Tags: core

Since: v1.0.0

6. Release Specification

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

A Release is a local version-cut record that groups completed Work Items under a semantic version. A Release records local governance state; it is not proof that Git tags, hosted releases, packages, or other external artifacts were published.

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 whose status is done.

A Work Item ID MUST appear in the refs of at most one release.

A release cut MUST include every Work Item whose status is done and which is not referenced by an existing release. It MUST reject the cut without modifying governed artifacts when no such Work Item exists.

When a release cut omits --date, it MUST use the current calendar date in the host’s local timezone.

Release entries MUST be stored newest-first. Release creation MUST prepend the new entry to the releases array.

A Work Item referenced by any release MUST remain done. Lifecycle commands MUST reject transitions away from done for that Work Item.

Project validation MUST report a release reference to a Work Item whose status is not done.

Project validation MUST report a Work Item ID referenced by more than one release.

A release entry has no persistent lifecycle status. An existing entry MUST remain immutable except when the newest entry is removed through the guarded latest-release correction defined below.

The latest-release correction MUST require an expected version. The correction MUST reject an empty release history or an expected version that does not exactly match the newest entry’s version without modifying governed artifacts.

A successful latest-release correction MUST remove only the newest release entry. It MUST NOT mutate the referenced Work Items; those items remain done and become unreleased because no release references them.

The latest-release correction MUST mutate only canonical release data. It MUST NOT create, remove, or modify CHANGELOG.md, Git tags, hosted releases, or published packages.

After a latest-release correction, govctl render changelog --force MUST derive release membership only from the current canonical release entries. The full projection MUST omit release versions absent from canonical release data and MUST classify as unreleased every done Work Item not referenced by a current release.

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: Release membership is the immutability boundary for a completed Work Item while its release entry exists. Unique membership and a frozen done status preserve release history. Restricting correction to the newest entry restores the immediately preceding local state without permitting arbitrary history rewriting, while the expected-version check rejects stale operator intent.

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.