govctl v0.15.0: From Requirements to Evidence | govctl Blog

govctl v0.15.0 is the point where several recent release lines become one coherent model.

The headline feature is first-class Conformance Cases: stable, non-normative links from versioned RFC requirements to project-owned scenarios and reusable Verification Guards. But the larger change spans the 0.10 through 0.15 series:

RFC versions now have an explicit authoring and sealing lifecycle
obsolete requirements no longer dominate the default human-readable view
one canonical CLI path replaces accumulated compatibility syntax
agent guidance is smaller and backed by parser-owned discovery
the TUI has grown into a structured governance control plane

Together, these changes move govctl beyond storing governance documents. It can now help an agent answer three separate questions without confusing their authority:

What is required?  -> RFC Clause
How is it checked? -> Conformance Case
What runs it?      -> Verification Guard

Conformance Cases Fill The Missing Middle

Before 0.15.0, govctl had normative RFC Clauses and executable Guards. What it did not have was a reusable identity for the scenario between them.

That gap matters in larger projects. Verification scenarios tend to end up in one of three bad places:

embedded in normative prose, making coverage changes look like specification changes
copied into multiple Work Items
hidden in test names and external manifests with no validated reverse link

A Conformance Case gives that scenario a stable CONF-* identity:

govctl conformance new "Cache expiry" \
  --path tests/conformance/cache.toml \
  --selector cache-expiry \
  --requirement RFC-0012:C-CACHE-EXPIRY@1.2.0 \
  --guard GUARD-CACHE-CONFORMANCE

The authority direction is intentionally one-way:

RFC requirement -> Conformance Case -> Guard
normative          derived              executable

A Case cannot create a new obligation or reinterpret an RFC. A Guard binding declares which Cases a command covers; it does not claim that a particular run has passed. govctl validates the graph and leaves domain-specific fixtures, oracles, and test execution to the project.

Use trace queries to inspect the relationship:

govctl conformance trace RFC-0012
govctl conformance trace CONF-CACHE-EXPIRY -o json

Trace output distinguishes provisional, candidate, current, and stale applicability. This makes version drift visible instead of silently treating an old scenario as current evidence.

RFC Versions Now Behave Like Real Candidates

The 0.10 through 0.13 releases rebuilt RFC version handling around a simpler idea: one version is one authoring candidate.

A normative RFC in spec can still be refined. Moving it to impl seals the content that implementation is expected to satisfy. If a problem is found later, edit the sealed content to form an amendment, then bump the RFC to open the next candidate in spec.

spec -> impl -> test -> stable
         |
         +-- later amendment -> version bump -> spec

This removed several sources of bookkeeping churn:

no empty bump just to seal unchanged content
no second bump while a spec candidate is already open
no silent rewriting of Clause since history
no inferring lifecycle success from loop round counts

The same period added two practical recovery boundaries. An unreleased completed Work Item can be reopened, and the newest local release cut can be undone when its expected version matches. Both operations stop once history has become published or otherwise immutable.

Current State And History Are Different Views

Governance history must remain complete, but agents should not treat superseded text as a current instruction.

Since 0.14.0, human-readable show defaults to the current projection. Deprecated RFCs, superseded ADRs, and obsolete Clauses retain identity and replacement metadata while hiding bodies that no longer govern new work.

Complete history remains explicit:

govctl clause show RFC-0012:C-OLD --history
govctl rfc show RFC-0012 --history

Generated Markdown remains archival, and structured output remains complete. The change is about safer default context for humans and agents, not deleting history.

One Canonical CLI, With Better Recovery

0.15.0 completes a compatibility cleanup that began in the 0.8 line. Mutation now has one shape:

govctl <resource> edit <id> <path> <operation>

Wire-layout prefixes, field aliases, compatibility command names, and resource-specific mutation flags are no longer parallel interfaces. Clause operations always live under the root govctl clause namespace.

Removing aliases is only useful if failure is recoverable. Recent diagnostics therefore do more than reject input:

a Clause operation sent through govctl rfc prints the canonical govctl clause replacement
an unknown edit path lists valid fields at that level
an unsupported operation reports the operations accepted by that path
unsupported legacy storage is identified rather than silently skipped

This is a breaking boundary, but it leaves agents with a smaller grammar and a direct route out of common mistakes.

Smaller Skills, Stronger Discovery

Long workflow manuals are not automatically safer for capable agents. They can duplicate the CLI, drift from the parser, and encourage unnecessary ceremony.

The bundled skills now focus on policy:

artifact authority
lifecycle boundaries
authorization stops
completion evidence

Command syntax comes from --help and the new machine-readable entry point:

govctl describe
govctl describe --context

describe derives its command tree from the parser and returns concise, versioned JSON. With --context, it adds complete counts but enumerates only actionable RFCs, ADRs, Work Items, and local loops. It does not dump artifact bodies or prescribe a speculative task sequence.

Guard guidance follows the same principle. Cheap checks that apply to every task belong in project defaults. Expensive suites belong on the Work Items whose risk requires them. Closing a Work Item remains the final effective guard gate, so agents do not need to run the same suite immediately beforehand.

A More Legible Read-Only TUI

The TUI remains read-only, but it is no longer a flat list of text panels.

Recent releases added:

aligned lifecycle matrices for RFCs, ADRs, and Work Items
separate execution and diagnostic health regions
a visible filter command strip with room for long input
stable result counts and scroll indicators
Conformance Case browsing, navigation, tags, and applicability
current-state detail projection for obsolete artifacts

The division of responsibility remains unchanged: use the TUI to understand the project, then use a canonical CLI command to mutate it.

Upgrade To 0.15.0

Install from crates.io:

cargo install govctl --version 0.15.0 --locked

Schema version 3 repositories can upgrade transactionally:

govctl migrate
govctl check

Schema version 4 enables Conformance Cases. Repositories below schema version 3 must first be upgraded with a compatible earlier govctl release. Legacy RFC or Clause JSON storage is rejected explicitly rather than ignored.

After migration, use govctl describe --context for a compact machine-readable orientation, or open govctl tui for the human control plane.

Why Release 0.15 Before 1.0

Conformance traceability is a significant model addition. Releasing it in the 0.15 line gives real projects time to test the storage, migration, query, and agent-context behavior before the compatibility promise becomes 1.0.

The direction is now much clearer:

RFCs define authority
ADRs preserve rationale
Work Items track delivery
Conformance Cases map requirements to scenarios
Guards provide reusable execution gates
loops retain local execution evidence

That is the model 0.15.0 is asking projects to exercise.

Full changelog: CHANGELOG.md

Release: govctl v0.15.0