Introduction

This book contains the governance documentation for govctl, an opinionated CLI for RFC-driven software development.

How This Book Is Organized

Specifications

RFCs (Requests for Comments) are the normative specifications that define govctl’s behavior. They are constitutional law — implementation must conform to them.

• RFC-0000: The governance framework itself. Start here to understand the core concepts: RFCs, Clauses, ADRs, and Work Items.
• RFC-0001: Lifecycle state machines for all artifact types.

Decisions

ADRs (Architectural Decision Records) document significant design choices. They explain why things are built a certain way.

Work Items

Work Items track units of work from inception to completion. They provide an audit trail of what was done and when.

The Data Model

All governance artifacts have a Single Source of Truth (SSOT) in the gov/ directory:

gov/
├── config.toml           # govctl configuration
├── rfc/                  # RFC-NNNN/rfc.toml + clauses/*.toml
├── adr/                  # ADR-NNNN-*.toml
├── work/                 # WI-YYYY-MM-DD-NNN-*.toml
├── guard/                # GUARD-*.toml verification guards
└── releases.toml         # Release history

The markdown files in this book are rendered projections — generated from the SSOT by govctl render. Each includes a SHA-256 signature for tampering detection.

Phase Discipline

govctl enforces a strict phase lifecycle:

spec → impl → test → stable

• spec: Defining what will be built. No implementation work permitted.
• impl: Building what was specified.
• test: Verifying implementation matches specification.
• stable: Released for production use.

Phases cannot be skipped. This discipline ensures specifications precede implementation.

Getting Started

1. Read RFC-0000 to understand the governance model
2. Follow the Getting Started guide to install and initialize
3. Read the Recommended Workflows guide to choose the right path for each change
4. Learn about RFCs, ADRs, and Work Items

Getting Started

This guide walks you through installing govctl and creating your first governed artifact.

Requirements

• Rust 1.96+ (per Cargo.toml rust-version)

Installation

# From crates.io (includes TUI by default)
cargo install govctl

# Without TUI
cargo install govctl --no-default-features

# Or build from source
git clone https://github.com/govctl-org/govctl
cd govctl
cargo build --release
# Binary at ./target/release/govctl

Features

Shell Completion

Generate completion scripts for your shell:

# Bash
govctl completions bash > ~/.local/share/bash-completion/completions/govctl

# Zsh (add to your .zshrc or install to completion directory)
govctl completions zsh > ~/.zsh/completions/_govctl
# Then add to fpath: fpath=(~/.zsh/completions $fpath)

# Fish
govctl completions fish > ~/.config/fish/completions/govctl.fish

# PowerShell (add to your profile)
govctl completions powershell >> $PROFILE

Restart your shell or source the configuration to enable tab completion.

Initialize a Project

govctl init

This creates the governance directory structure:

gov/
├── config.toml       # Configuration (project name, schema version, guards)
├── rfc/              # RFC sources (TOML)
├── adr/              # ADR sources (TOML)
├── work/             # Work item sources (TOML)
├── guard/            # Verification guards (TOML)
├── schema/           # JSON schemas for validation
└── releases.toml     # Release history

All governance artifacts use TOML with #:schema comment headers for IDE discoverability:

#:schema ../schema/adr.schema.json

[govctl]
id = "ADR-0001"
title = "My Decision"
status = "proposed"
...

Create Your First RFC

govctl rfc new "Feature Title"

This creates gov/rfc/RFC-0000/rfc.toml with the RFC metadata.

Add a Clause

RFCs are composed of clauses — atomic units of specification:

govctl clause new RFC-0000:C-SCOPE "Scope" -s "Specification" -k normative

Edit Clause Content

govctl clause edit RFC-0000:C-SCOPE text --set --stdin <<'EOF'
The feature MUST do X.
The feature SHOULD do Y.
EOF

View Artifacts

# Styled markdown to stdout
govctl rfc show RFC-0000
govctl adr show ADR-0001
govctl work show WI-2026-01-17-001
govctl clause show RFC-0000:C-SCOPE

# Interactive TUI dashboard
govctl tui

Search Artifacts

Search looks across RFCs, clauses, ADRs, work items, and verification guards:

govctl search cache
govctl search "schema migration" --type rfc --type adr
govctl search RFC-0002 --output json
govctl search cli --tag validation -n 5
govctl search loop --reindex

Search keeps any persisted index under .govctl/ as disposable local state. Artifacts under gov/ remain authoritative; --reindex forces a rebuild before returning results.

Validate Everything

govctl check

This validates all governance artifacts against JSON schemas, phase rules, cross-references, and source code annotations.

Recommended Workflow

Before using govctl on non-trivial work, read the Recommended Workflows guide. It explains when to use RFCs, ADRs, Work Items, execution loops, reviewer agents, and verification guards together.

Render to Markdown

govctl render

Generates human-readable markdown in docs/.

Current Views and History

Human-readable show output is optimized for the current governance context. Deprecated RFC bodies, superseded ADR bodies, and deprecated or superseded Clause text are hidden by default while their identity, lifecycle state, and replacement metadata remain visible.

# Current context for humans and agents
govctl rfc show RFC-0002

# Complete historical body content
govctl rfc show RFC-0002 --history

# Complete structured resources for automation
govctl rfc show RFC-0002 --output json
govctl rfc show RFC-0002 --output yaml
govctl rfc show RFC-0002 --output toml

--history applies only to human-readable table and plain output. Structured output is always complete. render also always preserves complete historical content in generated Markdown; it is not affected by the default show projection. Work Items and Guards have no obsolete-body lifecycle state, so their current and archival human-readable views are equivalent.

Read Output Formats

Resource list commands support table, json, and yaml. They default to a table in a terminal and JSON when piped. Complete get supports table, json, yaml, and toml; field retrieval supports plain, json, and yaml, with plain text as the field default.

govctl rfc list --output yaml
govctl rfc get RFC-0002 --output toml
govctl rfc get RFC-0002 phase
govctl rfc get RFC-0002 owners --output json

Interactive TUI

govctl includes an optional read-only terminal cockpit:

govctl tui

The cockpit is for human inspection: overview, artifact lists, search, loop state and dependency DAGs, guards, releases, tags, and check diagnostics. State-changing operations remain CLI commands.

TUI Keyboard Shortcuts

Cutting a Release

When a set of work items is complete and ready for release:

# Collect all unreleased done work items into a version
govctl release 0.2.0

# Specify a custom date
govctl release 0.2.0 --date 2026-04-15

This records the release in gov/releases.toml and makes those work items available for changelog generation.

Adopting govctl in an Existing Project

govctl init is safe to run in existing repositories — it only creates the gov/ directory structure alongside existing files.

For AI-assisted migration, use the /migrate skill to systematically discover undocumented decisions, backfill ADRs, and annotate source code with [[...]] references.

govctl migrate vs the /migrate Skill

Run govctl migrate for supported schema upgrades and bundled-file synchronization. Schema versions below 3 require migration with a compatible earlier govctl version before upgrading. Use the /migrate skill when bringing a project under governance for the first time.

Canonical Edit Surface

Editable artifact fields use a unified path-based edit interface:

Quote every path containing brackets so shells such as zsh do not expand it as a glob. For rich text containing backticks, $(), or other shell syntax, use --stdin so the shell does not interpret the value.

# Set a scalar value
govctl rfc edit RFC-0010 title --set "Updated title"

# Add to an array
govctl adr edit ADR-0003 refs --add RFC-0010

# Replace a scalar list item in place
govctl rfc edit RFC-0010 "owners[0]" --set "@new-owner"

# Correct criterion text and optionally its category
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --set "fix: Handle edge case"

# Remove by index
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --remove

# Tick checklist items
govctl adr edit ADR-0003 "alternatives[0]" --tick accepted
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --tick done

Nested object fields use dot-delimited paths:

govctl adr edit ADR-0003 decision --set "We will use Redis"
govctl adr edit ADR-0003 "alternatives[0].pros" --add "Low latency"
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0].text" --set "Literal criterion text"
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0].category" --set fixed

CLI Self-Description

govctl provides a machine-readable command catalog:

govctl describe
govctl describe --context   # Adds actionable project state and read-only next commands

The versioned JSON describes the command grammar compiled into the running binary. Context mode reports complete lifecycle counts but enumerates only non-terminal RFCs, ADRs, work items, and loops, so historical records do not inflate an agent’s working context. Workflow policy remains in the RFCs and installed skills.

Next Steps

• Working with RFCs — Full RFC lifecycle
• Working with ADRs — Decision records
• Working with Work Items — Task tracking
• Validation & Rendering — Quality gates, guards, tags, and more

Recommended Workflows

govctl is a governance tool, not a single enforced process. The recommended workflow is upstream-first: clarify requirements before design, design before execution, and execution before release.

Use this page as the default operating model when you are working with an AI agent or coordinating changes across a team.

The Default Path

For non-trivial product work, prefer:

RFC -> ADR -> Work Item -> Code -> Verification -> Release

Each layer has a different job:

When in doubt, ask what the text is trying to do:

• “What must be true?” belongs in an RFC.
• “Why this option?” belongs in an ADR.
• “What are we doing in this task?” belongs in a Work Item.
• “What happened in this round?” belongs in loop state or the final response.

Agent Guidance Model

Bundled skills provide policy and discovery, not a second copy of the CLI manual. Each workflow skill keeps a compact operational baseline:

• where to inspect current state and find deeper guidance;
• hard stops for authority, authorization, and unsafe mutation;
• policy for choosing the next action from repository context; and
• evidence that defines completion.

Information stays with its authoritative owner:

Skills retain safety-critical triggers even when the full explanation lives elsewhere. Detailed material moves out of a skill only after it has a stable discovery route. If authoritative state or the named fallback is unavailable, the safe response is to stop before mutation rather than infer permission.

This structure lets capable agents plan from live context while keeping weaker agents recoverable. Guidance changes should be staged and checked across both common paths and lifecycle-sensitive recovery paths before older instructions are removed.

Small Changes

Not every change needs every artifact.

Use the smallest path that still leaves a useful record:

Do not create work items for helper extraction, file moves, fixture sharing, formatting, or other low-level steps whose durable record is the diff.

Discovery And Drafting

Use /discuss when the problem is still unclear. Good /discuss output is a draft RFC, a proposed ADR, or a decision that no new artifact is needed.

During discovery:

• Keep RFCs focused on externally relevant obligations.
• Keep ADRs focused on trade-offs and decisions.
• Do not start implementation while the governing RFC is still ambiguous.
• Use reviewer agents before treating RFC or ADR drafts as settled.

RFC and ADR drafting should remain human-in-the-loop. Agents can produce strong drafts, but semantic review is still necessary because govctl check validates structure, not judgment.

Upstream-First Refinement

RFCs and ADRs may change as you learn. The important rule is direction:

Update upstream artifacts first, then implement downstream work.

If implementation reveals that a requirement is wrong, incomplete, or ambiguous, do not silently make the code diverge. Amend the RFC or ADR first, then continue the Work Item.

Avoid the reverse pattern:

Code first -> patch RFC/ADR afterward to match what happened

That pattern turns governance into a log of implementation choices instead of a source of authority.

Work Item Execution

Use Work Items for non-trivial implementation even when no new RFC or ADR is needed. A good Work Item says what will be completed and how closure is checked.

Before implementation:

govctl work new --active "Implement stale search index refresh"
govctl work edit WI-YYYY-MM-DD-NNN refs --add RFC-0002
govctl work edit WI-YYYY-MM-DD-NNN acceptance_criteria --add "changed: Search refreshes stale derived indexes before querying"
govctl work edit WI-YYYY-MM-DD-NNN acceptance_criteria --add "chore: govctl check passes"
govctl work list active

Confirm the intended work item appears in the active list. During execution:

• Tick acceptance criteria as they become true.
• Add notes only for durable constraints or retry rules.
• Do not put progress updates, command output, review status, next actions, or temporary blockers in notes.

After execution:

govctl work edit WI-YYYY-MM-DD-NNN "acceptance_criteria[0]" --tick done
govctl work edit WI-YYYY-MM-DD-NNN "acceptance_criteria[1]" --tick done
govctl work move WI-YYYY-MM-DD-NNN done

Moving to done runs verification guards when verification is enabled.

When To Use Loops

Use a loop when non-trivial execution needs resumable local round evidence, including single-Work-Item work.

Good loop use cases:

• A batch has multiple independently meaningful Work Items.
• Work Items have depends_on edges and need ready-item planning.
• You expect several implementation/review/verification rounds.
• You need local evidence for changed paths, blockers, note candidates, or validation results without polluting Work Item fields.

Do not use a loop to justify over-splitting one task into mechanical Work Items. Do not create a separate loop for every tiny cleanup.

Typical loop flow:

govctl loop list open
govctl loop start WI-YYYY-MM-DD-001 WI-YYYY-MM-DD-002
govctl loop run LOOP-YYYY-MM-DD-NNN
# implement, verify, and fill the opened round evidence
govctl loop run LOOP-YYYY-MM-DD-NNN

Important boundaries:

• loop run advances local round state only.
• It does not implement code.
• It does not tick acceptance criteria.
• It does not add Work Item notes.
• It does not move Work Items to done.

If batch scope changes, keep the same loop identity:

govctl loop add LOOP-YYYY-MM-DD-NNN work WI-YYYY-MM-DD-003
govctl loop remove LOOP-YYYY-MM-DD-NNN work WI-YYYY-MM-DD-002
govctl loop replan LOOP-YYYY-MM-DD-NNN

If loop show or loop list reports a stale plan, the current Work Item dependency closure differs from the stored loop plan. Run govctl loop replan LOOP-YYYY-MM-DD-NNN before opening another round.

Loop state is local execution memory under .govctl/loops/. Work Items remain the durable task record.

Agent Goals And Loops

Some agent runtimes provide session-level goal features, such as /goal. These work well with batched Work Items in a loop when the boundaries stay clear:

For a batched loop, set the agent goal to the current loop or round instead of duplicating the Work Item list:

Goal: Complete the current round for LOOP-YYYY-MM-DD-NNN.

That goal gives the agent a narrow execution target while the loop remains the source of truth for ready Work Items, blockers, changed paths, validation evidence, and note candidates.

Use a simpler goal for simple work:

• For one small Work Item, a goal may point directly at that Work Item.
• For a multi-Work-Item batch, prefer one goal for the active loop or current round.
• Do not create one goal per mechanical substep.

Do not store agent goals in RFCs, ADRs, or Work Item notes. Goals are runtime focus. Loop state is local execution memory. Work Items are the durable task record.

Review And Verification

Run structural checks directly:

govctl check

govctl check validates schemas, references, lifecycle rules, tags, source annotations, and other deterministic constraints. It does not decide whether an RFC is too implementation-specific or whether an ADR is intellectually honest.

When closing a Work Item, use govctl work move <WI-ID> done as the final verification gate. The move runs the Work Item’s effective verification guards, so do not run govctl verify --work <WI-ID> immediately beforehand. Run govctl verify independently only to diagnose guards or when the Work Item will remain active.

Use reviewer agents for semantic checks:

• rfc-reviewer catches vague requirements and implementation details inside RFCs.
• adr-reviewer catches missing alternatives, dishonest consequences, and ADRs that invent requirements.
• wi-reviewer catches vague criteria, transient notes, local requirements, and over-split Work Items.
• compliance-checker audits implementation against normative RFC clauses and accepted ADR decisions.

Treat reviewer findings as design feedback, not just formatting feedback.

Project-Specific Guards

Domain projects often need extra checks. For example:

• Requirement ID tracing from RFC clauses to tests and source comments.
• Generated-code or assembler inspection for low-level performance work.
• Protocol conformance suites.
• Language-specific lint or style checks.

Model these as verification guards when they can be automated:

govctl guard new "Requirement trace"
govctl guard edit GUARD-REQUIREMENT-TRACE command --set "cargo run --bin trace-check"
govctl work edit WI-YYYY-MM-DD-NNN verification.required_guards --add GUARD-REQUIREMENT-TRACE

Keep the guard domain-specific. govctl provides the governance structure; your project owns the language, framework, and protocol-specific checks. Project defaults are the checks every Work Item needs. Select heavier or domain-specific guards per Work Item, and reserve full suites for changes whose blast radius crosses the narrower domains.

Common Pitfalls

• Writing implementation details into RFCs because they are easy to describe.
• Writing new requirements into ADRs because the decision needs justification.
• Writing current plans or validation output into Work Item notes.
• Creating many tiny Work Items for one coherent refactor.
• Treating loops as mandatory ceremony instead of local execution coordination.
• Treating an agent goal as durable governance state.
• Treating govctl check as a substitute for human or agent semantic review.

The goal is not to maximize artifact count. The goal is to keep authority, decision rationale, execution state, and verification evidence in the right places.

Working with RFCs

RFCs (Requests for Comments) are the normative specifications in govctl. They define what will be built before implementation begins.

Creating RFCs

# Auto-assign next available ID
govctl rfc new "Feature Title"

# Specify ID manually
govctl rfc new "Feature Title" --id RFC-0010

RFC Structure

An RFC consists of:

• Metadata (rfc.toml) — ID, title, status, phase, version, owners
• Clauses (clauses/*.toml) — Atomic units of specification

The TOML files use #:schema headers and a [govctl] + [content] layout:

#:schema ../../schema/rfc.schema.json

[govctl]
id = "RFC-0010"
title = "Feature Title"
version = "0.1.0"
status = "draft"
phase = "spec"
owners = ["@you"]
created = "2026-03-17"
refs = []

[content]
summary = "Brief summary of this RFC."

Tagging RFCs

Once tags are registered in the project vocabulary, apply them to RFCs:

govctl rfc edit RFC-0010 tags --add caching
govctl rfc edit RFC-0010 tags --add api

Filter lists by tag:

govctl rfc list --tag caching
govctl rfc list --tag caching,api

Canonical Edit Surface

Editable RFC and Clause fields use path-based operations. Lifecycle-owned fields such as RFC versions, changelog dates, and Clause since values use dedicated commands or automatic assignment instead:

# Lifecycle-managed fields use dedicated verbs
govctl rfc finalize RFC-0010 normative
govctl rfc bump RFC-0010 --minor -m "Add new clause for edge case"

# Correct metadata for the current RFC version only
govctl rfc get RFC-0010 changelog
govctl rfc edit RFC-0010 changelog.summary --set "Clarify edge-case behavior"
govctl rfc edit RFC-0010 changelog.fixed --add "Correct timeout wording"
govctl rfc edit RFC-0010 "changelog.fixed[0]" --remove

# Add to array fields
govctl rfc edit RFC-0010 refs --add RFC-0001
govctl rfc edit RFC-0010 owners --add "@co-maintainer"

# Remove by index or pattern
govctl rfc edit RFC-0010 "refs[0]" --remove
govctl rfc edit RFC-0010 owners --remove "@old-owner"

# Edit clause text
govctl clause edit RFC-0010:C-SCOPE text --set --stdin <<'EOF'
New clause text here
EOF

Finalization is the initial publication boundary for a draft RFC. A version-changing bump opens the next candidate from a normative RFC in impl, test, or stable; draft, deprecated, and already-open spec RFCs are rejected. Changelog-only corrections do not change the version and remain available through either rfc edit ... changelog or rfc bump --change.

Working with Clauses

Clauses are first-class CLI resources. Use the root govctl clause namespace for every Clause operation, even though Clause IDs and files are scoped by an RFC. govctl rfc operates on the RFC resource itself.

Create a Clause

govctl clause new RFC-0010:C-SCOPE "Scope" -s "Specification" -k normative

Options:

• -s, --section — Section name (e.g., “Specification”, “Rationale”)
• -k, --kind — normative (binding) or informative (explanatory)

Clause files use the same [govctl] + [content] layout:

#:schema ../../../schema/clause.schema.json

[govctl]
id = "C-SCOPE"
title = "Scope"
kind = "normative"
status = "active"
since = "0.1.0"

[content]
text = """
The system MUST validate all inputs."""

since is assigned when the target version is known. Clauses created in a draft RFC remain pending until finalization. Clauses created in a normative RFC already in spec receive the current RFC version immediately. Clauses created in impl, test, or stable remain pending until the content amendment is released by an RFC version bump.

Edit Clause Text

# From stdin (recommended for multi-line)
govctl clause edit RFC-0010:C-SCOPE text --set --stdin <<'EOF'
The system MUST validate all inputs.
The system SHOULD log validation failures.
EOF

# Inline text
govctl clause edit RFC-0010:C-SCOPE text --set "The system MUST validate all inputs."

# From file
govctl clause edit RFC-0010:C-SCOPE text --set --stdin < clause-text.md

Delete a Clause

Accidentally created clauses can be deleted before they become part of a sealed version:

govctl clause delete RFC-0010:C-MISTAKE -f

Safety: Deletion is only allowed when no artifact references the Clause and either:

• The RFC status is draft; or
• The RFC is normative/spec and the Clause since equals the current RFC version.

The second case identifies a Clause introduced only in the open candidate. Inherited Clauses and all Clauses in sealed phases use govctl clause deprecate or govctl clause supersede instead.

List Clauses

govctl clause list
govctl clause list RFC-0010
govctl clause list --tag core    # Filter by tag

View a Clause

govctl clause show RFC-0010:C-SCOPE

Status Lifecycle

RFCs have three statuses:

draft → normative → deprecated

Finalize to Normative

When the spec is complete and approved:

govctl rfc finalize RFC-0010 normative

This ratifies the RFC lineage. While its current version remains in spec, that content is still an authoring candidate. The version becomes the implementation baseline when it advances to impl.

Deprecate

When an RFC is superseded or obsolete:

govctl rfc deprecate RFC-0010

Phase Lifecycle

RFCs progress through four phases:

spec → impl → test → stable

Advance Phase

govctl rfc advance RFC-0010 impl    # Ready for implementation
govctl rfc advance RFC-0010 test    # Implementation complete, ready for testing
govctl rfc advance RFC-0010 stable  # Tested, ready for production

Phase transitions are gated:

• spec → impl requires status = normative
• spec → impl requires every Clause to have a resolved since version
• spec → impl seals the current RFC and Clause content signature
• impl → test and test → stable require that sealed signature to remain present
• Each phase has invariants that must be satisfied

The sealed signature is a content baseline, not a file lock. A code-only defect found during impl can be fixed without changing the RFC. If RFC or Clause content must change, edit it and then release that amendment with a patch, minor, or major bump. The bump starts the new version in spec; phase progression rejects the amendment until that happens. Changelog-only corrections do not affect the sealed baseline. If a sealed-phase RFC has no signature, bump and later phase progression stop without changing files; run govctl migrate or restore the baseline from version-control history instead of guessing it.

Versioning

RFCs use semantic versioning after normative finalization. Draft RFCs remain on their initial version while they are authored, and deprecated RFCs cannot start a new version lifecycle:

# Bump version with changelog entry
govctl rfc bump RFC-0010 --patch -m "Fix typo in clause C-SCOPE"
govctl rfc bump RFC-0010 --minor -m "Add new clause for edge case"
govctl rfc bump RFC-0010 --major -m "Publish the stable 1.0 contract"

The bump flags select literal SemVer components; they are not remapped impact labels. For an RFC at 0.y.z, use --minor for a breaking pre-1.0 amendment that starts the next 0.(y+1).0 line, and reserve --major for the deliberate transition to 1.0.0. Use --patch for amendments that remain compatible within the current 0.y line.

A content-changing bump starts the new version in spec only from impl, test, or stable. RFC and Clause content can continue changing during that spec phase without another version bump; a second version-changing bump is rejected. Advancing to impl seals the final content for the version.

Use change-only bump syntax to append categorized metadata without changing the RFC version:

govctl rfc bump RFC-0010 --change "fix: Correct current-version wording"

Current-version changelog correction always resolves the entry whose version matches the RFC version, regardless of array order. Historical entries and all RFC/changelog version and date fields are not editable through the resource edit surface.

Listing and Viewing

govctl rfc list
govctl rfc list normative    # Filter by status
govctl rfc list impl         # Filter by phase
govctl rfc list --tag api    # Filter by tag
govctl rfc show RFC-0010     # Styled markdown to stdout

Working with ADRs

ADRs (Architectural Decision Records) document significant design choices. They explain why things are built a certain way.

Creating ADRs

govctl adr new "Use Redis for caching"

This creates a TOML file in gov/adr/ with the decision context.

ADR Structure

ADRs are TOML files with #:schema headers:

#:schema ../schema/adr.schema.json

[govctl]
id = "ADR-0003"
title = "Use Redis for caching"
status = "proposed"
date = "2026-03-17"
refs = ["RFC-0001"]

[content]
context = "We need a caching layer for..."
decision = "We will use Redis because..."
consequences = "Positive: faster reads. Negative: operational complexity."

[[content.alternatives]]
text = "Memcached"
pros = ["Simpler"]
cons = ["No persistence"]
rejection_reason = "Persistence is required for our use case"

ADRs contain:

• Context — The situation requiring a decision
• Decision — What was decided
• Consequences — Expected outcomes (positive and negative)
• Alternatives — Options considered with pros, cons, and rejection reasons (per [[ADR-0027]])
• Status — proposed, accepted, rejected, or superseded

Editing ADRs

Use govctl to get/set fields:

# Get specific field
govctl adr get ADR-0003 status

# Set content field value
govctl adr edit ADR-0003 decision --set "We will use Redis because..."

# Set multi-line content from stdin
govctl adr edit ADR-0003 context --set --stdin <<'EOF'
We need a caching layer that can handle
10k requests per second with sub-millisecond latency.
EOF

Canonical Edit Paths

All ADR fields are accessible through a unified path-based edit interface:

# Scalar fields
govctl adr edit ADR-0003 decision --set "We will use Redis"
govctl adr edit ADR-0003 context --set --stdin < context.md

# Array fields — add, remove, tick
govctl adr edit ADR-0003 refs --add RFC-0010
govctl adr edit ADR-0003 "refs[0]" --remove

# Nested alternatives
govctl adr edit ADR-0003 alternatives --add "Option C: Use etcd"
govctl adr edit ADR-0003 "alternatives[0].pros" --add "Fast reads"
govctl adr edit ADR-0003 "alternatives[0].cons" --add "Operational cost"
govctl adr edit ADR-0003 "alternatives[0]" --tick accepted
govctl adr edit ADR-0003 "alternatives[0].rejection_reason" --set "Too complex"

# Tick alternative status
govctl adr edit ADR-0003 "alternatives[0]" --tick accepted

Edit paths use logical field names:

Tagging ADRs

Once tags are registered in the project vocabulary, apply them to ADRs:

govctl adr edit ADR-0003 tags --add caching
govctl adr edit ADR-0003 tags --add performance

Filter lists by tag:

govctl adr list --tag caching
govctl adr list --tag caching,performance

Status Lifecycle

proposed → accepted → superseded
         ↘ rejected

Accept a Decision

Before accepting, the ADR must have at least 2 alternatives with 1 accepted and 1 rejected per [[ADR-0042]]:

govctl adr edit ADR-0003 "alternatives[0]" --tick accepted
govctl adr edit ADR-0003 "alternatives[1]" --tick rejected

govctl adr accept ADR-0003

Use --force for historical backfills where alternatives cannot be reconstructed:

govctl adr accept ADR-0003 --force

When consensus is reached:

govctl adr accept ADR-0003

Reject a Proposal

When a proposed ADR should not proceed:

govctl adr reject ADR-0003

Accepted ADRs are not deprecated. When a newer decision replaces an accepted ADR, supersede it instead.

Supersede

When a new decision replaces an old one:

govctl adr supersede ADR-0001 --by ADR-0005

This marks ADR-0001 as superseded and records ADR-0005 as its replacement.

Listing and Viewing

govctl adr list
govctl adr list accepted    # Filter by status
govctl adr show ADR-0003    # Styled markdown to stdout

Working with Work Items

Work Items track durable units of work from inception to completion, including scope, lifecycle state, acceptance criteria, references, dependencies, and durable notes. Round-by-round execution trace belongs in local loop state and round artifacts.

See also: Tags, TUI, Canonical Edit

Creating Work Items

# Create in queue (pending)
govctl work new "Implement caching layer"

# Create and activate immediately
govctl work new --active "Urgent bug fix"

Work items are automatically assigned IDs like WI-2026-01-17-001.

Work Item Structure

Work items are TOML files with #:schema headers:

#:schema ../schema/work.schema.json

[govctl]
id = "WI-2026-01-17-001"
title = "Implement caching layer"
status = "active"
started = "2026-01-17"
refs = ["RFC-0010", "ADR-0003"]
depends_on = ["WI-2026-01-16-001"]

[content]
description = "Add Redis caching for the query endpoint."
notes = ["Do not retry the old validation path"]

[[content.acceptance_criteria]]
text = "Cache invalidation on write"
status = "pending"
category = "added"

[[content.acceptance_criteria]]
text = "govctl check passes"
status = "pending"
category = "chore"

Work items contain:

• Title — Brief description
• Description — Task scope declaration
• Notes — Durable learnings and constraints
• Acceptance Criteria — Checkable completion criteria with changelog category
• Refs — Links to related RFCs, ADRs, or external resources
• Depends On — Blocking dependencies on other work items

Status Lifecycle

queue → active → done
    ↘        ↘ cancelled

Move Between States

# By ID
govctl work move WI-2026-01-17-001 active
govctl work move WI-2026-01-17-001 done

# By filename (without path)
govctl work move implement-caching.toml active

Moving to done requires all verification guards to pass (see Validation).

Acceptance Criteria

Add Criteria

govctl work edit WI-2026-01-17-001 acceptance_criteria --add "chore: Unit tests pass"
govctl work edit WI-2026-01-17-001 acceptance_criteria --add "add: Documentation updated"

Category prefixes (add:, fix:, change:, chore:, etc.) are required and drive changelog generation. Conventional-commit aliases like feat:, refactor:, test:, docs: are also accepted.

Canonical changelog categories are still the preferred form in stored artifacts. The conventional-commit aliases are accepted as input sugar and normalized into the changelog model.

Correct Criteria

Set an indexed criterion directly to correct its text. A recognized category prefix updates the category at the same time; input without one preserves the existing category. Both forms preserve checklist status.

govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --set "fix: Handle empty input"
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --set "Handle empty input"

Use the child path when a recognized prefix must remain literal text:

govctl work edit WI-2026-01-17-001 "acceptance_criteria[0].text" --set "fix: shown to the user"

Mark Criteria Complete

govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --tick done

Checklist state changes address one item by index.

Canonical Edit Paths

Most work item fields are accessible through the unified path-based edit interface. Lifecycle-managed fields (such as status) are excluded — use govctl work move for status transitions instead.

# Set scalar fields
govctl work edit WI-2026-01-17-001 description --set --stdin <<'EOF'
New description here
EOF

# Add to array fields
govctl work edit WI-2026-01-17-001 refs --add RFC-0010
govctl work edit WI-2026-01-17-001 depends_on --add WI-2026-01-16-001
govctl work edit WI-2026-01-17-001 acceptance_criteria --add "fix: Handle edge case"

# Remove by index
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --remove

# Tick checklist items
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --tick done
govctl work edit WI-2026-01-17-001 "acceptance_criteria[1]" --tick cancelled

Edit paths use logical field names:

Dependencies and Execution Loops

Use depends_on for hard execution ordering between work items. Keep refs for informational links to RFCs, ADRs, clauses, guards, or related work.

govctl work edit WI-2026-01-17-002 depends_on --add WI-2026-01-17-001
govctl check

govctl check validates dependency targets and rejects dependency cycles. A work item should only depend on another work item when the dependent work cannot start until the blocker has completed.

For a batch with multiple independently meaningful work items, create one local execution loop and let govctl generate the loop ID:

govctl loop list open
govctl loop start WI-2026-01-17-001 WI-2026-01-17-002
govctl loop run <LOOP-ID>

Loop state and round evidence live under .govctl/loops/<LOOP-ID>/. loop run opens or validates local rounds; it does not implement code, tick acceptance criteria, add notes, or move work items to done.

When batch scope changes, keep the same loop identity:

govctl loop add <LOOP-ID> work WI-2026-01-17-003
govctl loop remove <LOOP-ID> work WI-2026-01-17-002
govctl loop replan <LOOP-ID>

Use work item notes only for durable lessons or constraints. Put transient execution trace, failed attempts, blockers, next actions, and round summaries in loop state and round artifacts.

Tagging Work Items

Once tags are registered in the project vocabulary, apply them to work items:

govctl work edit WI-2026-01-17-001 tags --add backend
govctl work edit WI-2026-01-17-001 tags --add performance

Filter lists by tag:

govctl work list --tag backend
govctl work list --tag backend,performance

Per-Work-Item Guards

Work items can require extra verification guards in addition to the project’s default guard set.

Example:

[verification]
required_guards = ["GUARD-CLIPPY"]

This means:

• GUARD-CLIPPY is required for this work item even if it is not a project default
• project defaults from gov/config.toml still apply when verification is enabled
• the work item cannot move to done until the effective required guards pass or are explicitly waived

Project defaults should contain only the checks required by every Work Item. Choose additional guards from the Work Item’s changed surface, governing references, and acceptance criteria. Prefer a narrow domain guard over a full test suite; require the full suite when the change crosses shared boundaries or cannot be covered reliably by narrower checks.

To run the effective guard set for a single work item:

govctl verify --work WI-2026-01-17-001

Use this command for early feedback or diagnosis while the Work Item remains active. Moving the Work Item to done runs the same effective guard set, so running both commands back to back repeats the guards.

Waiving A Guard

If a specific guard must be waived for this work item, record that in the artifact with a reason:

[[verification.waivers]]
guard = "GUARD-CARGO-TEST"
reason = "Temporarily flaky on macOS runners; tracked in issue #123"

Waivers are per-work-item only. They do not disable the guard globally, and they should remain rare and justified.

Notes

Add closure-worthy durable notes for constraints or retry rules that should remain useful after the work item is done:

govctl work edit WI-2026-01-17-001 notes --add "Do not retry the old validation path; it fails on missing refs"
govctl work edit WI-2026-01-17-001 "notes[0]" --set "Retry only after the referenced RFC is normative"

Do not use notes for progress updates, commands run, validation output, current plans, next actions, temporary blockers, or TODOs. Put transient execution trace in local loop state and round artifacts instead.

Nested path edits are also available for structured fields:

govctl work edit WI-2026-01-17-001 "acceptance_criteria[0]" --set "fix: Handle edge case"
govctl work edit WI-2026-01-17-001 "acceptance_criteria[0].category" --set fixed

Removing Items

Remove items from array fields using flexible matching:

# Exact value
govctl work edit WI-2026-01-17-001 notes --remove "edge case"

# Another exact value
govctl work edit WI-2026-01-17-001 notes --remove "Discovered edge case in validation"

# By index (0-based)
govctl work edit WI-2026-01-17-001 "notes[0]" --remove

# Regex pattern
govctl work edit WI-2026-01-17-001 refs --remove "RFC-.*" --regex

# Remove every item
govctl work edit WI-2026-01-17-001 refs --remove --all

Deleting Work Items

Accidentally created work items can be deleted if they’re still in queue status:

govctl work delete WI-2026-01-17-999 -f

Safety: Deletion is only allowed when:

• The work item status is queue (never activated)
• No other artifacts reference it

For work items that have been activated, use status transitions instead:

govctl work move WI-2026-01-17-001 cancelled

Listing and Viewing

govctl work list
govctl work list queue      # Pending items
govctl work list active     # In progress
govctl work list done       # Completed
govctl work show WI-2026-01-17-001  # Styled markdown to stdout

Conformance Cases

Conformance Cases connect a project-owned acceptance scenario to one or more versioned RFC Clause requirements and reusable Verification Guards:

RFC Clause requirement -> Conformance Case -> Verification Guard
normative authority       derived scenario    execution entrypoint

A Case is traceability metadata, not a test runner or a source of normative requirements. When a Case and an RFC disagree, the RFC governs.

Create A Case

The scenario path must already exist, stay inside the repository, and remain outside gov/. The selector is project-defined; use * for the complete file.

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

Requirement values always use <CLAUSE-ID>@<RFC-VERSION>. A Case may bind multiple requirements and Guards.

Inspect And Edit

govctl conformance list
govctl conformance show CONF-CACHE-INVALIDATION-BEHAVIOR
govctl conformance get CONF-CACHE-INVALIDATION-BEHAVIOR requirements

govctl conformance edit CONF-CACHE-INVALIDATION-BEHAVIOR \
  requirements --add RFC-0012:C-CACHE-FALLBACK@1.2.0
govctl conformance edit CONF-CACHE-INVALIDATION-BEHAVIOR \
  requirements[0].version --set 1.3.0
govctl conformance edit CONF-CACHE-INVALIDATION-BEHAVIOR \
  requirements[1] --remove

Case mutations validate the complete prospective trace graph before writing. Removing the final requirement is rejected.

Query Traceability

govctl conformance trace
govctl conformance trace RFC-0012
govctl conformance trace RFC-0012:C-CACHE-EXPIRY
govctl conformance trace CONF-CACHE-INVALIDATION-BEHAVIOR --output json
govctl conformance trace GUARD-CACHE-CONFORMANCE

Trace output derives provisional, candidate, current, or stale applicability from the referenced RFC version and Clause lifecycle. These values describe the declared relationship only; they do not mean that a scenario has run or passed.

Cases also participate in govctl search, controlled-vocabulary tags, govctl status, and govctl check.

Schema Migration

Conformance Cases were introduced in project schema version 4. Upgrade an existing project to the current schema with:

govctl migrate
govctl check

Migration preserves valid prospective Case files and rejects an invalid Case graph without partially changing the repository.

Validation & Rendering

govctl provides tools to validate governance artifacts, enforce completion gates, and render human-readable documentation.

Validation

Check All Artifacts

govctl check

This validates:

• Schema conformance — All required fields present, correct types
• Phase discipline — No invalid state transitions
• Cross-references — refs and [[...]] annotations point to existing artifacts
• Controlled-vocabulary tags — All artifact tags are registered in gov/config.toml [tags] allowed
• Clause structure — Normative clauses in spec sections
• Source code scanning — [[RFC-0001]] annotations in source files are verified

Exit Codes

• 0 — All validations passed
• 1 — Validation errors found

Source Code Scanning

govctl scans source files for [[artifact-id]] annotations and verifies they reference existing, non-deprecated artifacts:

#![allow(unused)]
fn main() {
// Implements [[RFC-0001:C-VALIDATION]]
fn validate() { ... }

// Per [[ADR-0005]], we use semantic colors
}

Configure scanning in gov/config.toml:

[source_scan]
enabled = true
include = ["src/**/*.rs"]

include is the positive scan domain and uses Git gitignore path-pattern semantics. Project .gitignore files provide the baseline exclusions. Governance-specific exclusions and re-inclusions belong in .govignore files:

# Skip generated source evidence
generated/

# Restore one governed subtree excluded by .gitignore
!fixtures/
!fixtures/governed/

.govignore uses normal gitignore ordering and ! re-inclusion, and its rules take precedence over .gitignore. Re-including a descendant requires re-including each excluded parent directory. govctl prunes excluded directories before reading their contents.

An optional source_scan.pattern override must be a valid regular expression whose capture group 1 returns the complete artifact ID for every match. Unknown and outdated reference diagnostics report the normalized source path followed by a one-based line and byte column.

Controlled-Vocabulary Tags

Tags provide cross-cutting categorization across all governance artifacts. Every tag must be registered in a project-level allow list before use.

Managing the Tag Registry

# List all registered tags with usage counts
govctl tag list

# Register a new tag
govctl tag new caching

# Remove a tag (fails if any artifact still uses it)
govctl tag delete caching

Tagging Artifacts

Once a tag is registered, apply it to any artifact via the standard edit command with --add:

govctl rfc edit RFC-0010 tags --add caching
govctl adr edit ADR-0003 tags --add caching
govctl work edit WI-2026-01-17-001 tags --add caching

Filtering by Tag

List commands support --tag to filter by one or more tags (comma-separated, AND logic):

govctl rfc list --tag caching
govctl adr list --tag caching,performance
govctl work list --tag breaking-change

Tags are validated at govctl check time — any tag not in the allow list produces error E1105.

Verification Guards

Guards are executable completion checks that run automatically when a work item moves to done. They prevent work items from closing unless all configured checks pass.

How Guards Work

When you run govctl work move <WI-ID> done, govctl executes each guard defined in gov/config.toml:

[verification]
enabled = true
default_guards = ["GUARD-GOVCTL-CHECK"]

Each guard is a TOML file in gov/guard/:

#:schema ../schema/guard.schema.json

[govctl]
id = "GUARD-LIFECYCLE-TESTS"
title = "lifecycle tests pass"
refs = ["RFC-0000"]

[check]
command = "cargo test --test lifecycle_tests"
timeout_secs = 300

Guard Subcommands

Guards are first-class resources with their own CRUD verbs:

# Create a new guard
govctl guard new "My Lint Check"

# List all guards
govctl guard list

# Show guard definition
govctl guard show GUARD-MY-LINT

# Set guard fields
govctl guard edit GUARD-MY-LINT command --set "npm run lint"
govctl guard edit GUARD-MY-LINT timeout_secs --set 60

# Delete a guard (blocked if still referenced by work items or project defaults)
govctl guard delete GUARD-MY-LINT

Guard Fields

Guard Behavior

• A guard passes when its command exits with code 0 (and matches pattern if specified)
• A guard fails when the command exits non-zero, times out, or doesn’t match the pattern
• All guards must pass before govctl work move <WI-ID> done succeeds

Running Guards Independently

Use govctl verify to run guards without moving a work item:

# Run all project default guards
govctl verify

# Run specific guards
govctl verify GUARD-CARGO-TEST GUARD-GOVCTL-CHECK

# Run guards required by a specific work item
govctl verify --work WI-2026-01-17-001

govctl work move <WI-ID> done runs the same effective required guards. Do not run govctl verify --work <WI-ID> immediately before that move; doing so executes the guards twice. Use independent verification for early feedback, diagnosis, or workflows that leave the Work Item active.

Per-Work-Item Guards

Project-level default_guards are only part of the picture. A work item can also require additional guards of its own:

[verification]
required_guards = ["GUARD-CLIPPY"]

This is useful when one work item needs an extra check that should not become a project-wide default.

The effective required guard set for a work item is:

• the project-level default_guards when verification is enabled
• plus the work item’s verification.required_guards
• minus any explicitly waived guards

Choosing Guard Granularity

Treat default_guards as the intersection of checks required by every Work Item, not as a catalog of everything the project can verify. A default guard should be necessary even for documentation-only work, fast enough for every completion gate, stable, and independent of optional services.

Keep reusable checks narrow and name them for the risk domain they cover, such as lifecycle tests, schema tests, or CLI parsing tests. Add those guards to affected Work Items:

govctl work edit WI-2026-01-17-001 verification.required_guards --add GUARD-LIFECYCLE-TESTS

Full test suites, full lint suites, integration tests, and other expensive aggregate checks should remain available as guards, but normally be required only by Work Items that change shared infrastructure or cross multiple risk domains. One-off diagnostic commands do not need Guard artifacts.

Repeated waivers are not a substitute for correct scope. If many unrelated Work Items waive the same default guard, remove it from default_guards and require it only where its risk applies.

Guard Waivers

If a guard must be waived for a specific work item, record that explicitly with a reason:

[[verification.waivers]]
guard = "GUARD-CARGO-TEST"
reason = "Flaky on CI runner image; tracked in issue #123"

Waivers are scoped to a single work item. They do not disable verification globally, and they should be treated as an exception that must be explained.

Rendering

Render governance artifacts to markdown for documentation.

Render All

govctl render            # RFCs to docs/rfc/
govctl render adr        # ADRs to docs/adr/
govctl render work       # Work items to docs/work/
govctl render all        # Everything
govctl render changelog  # CHANGELOG.md

Render Single Items

govctl rfc render RFC-0010
govctl adr render ADR-0005
govctl work render WI-2026-01-17-001

View Without Writing Files

The show commands render styled markdown to stdout without writing files:

govctl rfc show RFC-0010
govctl adr show ADR-0005
govctl work show WI-2026-01-17-001
govctl clause show RFC-0010:C-SCOPE

Hash Signatures

Rendered markdown includes a SHA-256 signature for tampering detection:

<!-- SIGNATURE: sha256:abc123... -->

If the source changes, the signature won’t match — indicating the rendered doc is stale.

Project Status

govctl status

Shows RFC/ADR/work item counts by status, phase breakdown, and active work items.

Search

govctl search cache
govctl search "work item" --type work
govctl search RFC-0002 --output json
govctl search migration --tag cli -n 5
govctl search cache --reindex

Search is project-wide discovery across RFCs, clauses, ADRs, work items, and verification guards. Use repeated --type flags to restrict artifact kinds and repeated --tag flags to require all listed tags.

Supported output formats are table (default), json, and plain. If govctl persists a search index, it lives under .govctl/ as derived local state. The command establishes index freshness before returning results; --reindex forces a full rebuild.

CLI Self-Description

govctl provides a machine-readable command catalog for agent discoverability:

govctl describe
govctl describe --context   # Adds counts and non-terminal project state

The output includes a schema version and derives its command tree from the running CLI. Context mode omits terminal artifact details and offers only read-only discovery commands; use resource show commands or installed skills for deeper guidance.

Self-Update

Update govctl to the latest release:

govctl self-update          # Download and replace binary
govctl self-update --check  # Check for newer version without downloading

Supports GITHUB_TOKEN environment variable for authenticated API requests.

Agent Integration

Install or update govctl’s user-scoped integration through the agent runtime’s native plugin mechanism:

govctl agent doctor all
govctl agent install claude
govctl agent install codex
govctl agent update all

doctor is read-only. install preserves existing Codex reviewer-role files; update refreshes govctl’s installed role files. Start a new agent session after installation or update so the runtime reloads its integration. Both runtimes load bundled skills and hooks from their native plugin. Claude also loads Markdown reviewer agents from that plugin; Codex reviewer agents are standalone TOML roles managed by the same command.

Claude and Codex load separate hook manifests so each client receives fields and output in its native protocol. At session start, govctl uses normal upward project discovery and injects compact active-work and loop context only when the working directory belongs to a governed project. It stays silent in unmanaged directories and reports damaged governance state as non-blocking recovery context.

Before a direct edit to lifecycle-managed artifacts, the hook advises using the resource-specific CLI when it can express the change. The edit is never blocked: direct editing remains the recovery path for unsupported operations, followed by govctl check. The plugin does not run project-wide validation at the end of every turn.

Use init-skills only when a project-local or custom-directory copy is needed:

govctl init-skills --format claude
govctl init-skills --format codex
govctl init-skills --dir /path/to/agent-config

This direct projection does not register a native user plugin. It writes bundled workflow skills, writer/helper skills, and reviewer agents to the resolved destination.

Schema Migration

When the governance schema evolves between govctl versions, artifact files may need format upgrades:

govctl migrate

This upgrades TOML artifact file formats (e.g., adding #:schema headers or normalizing schema metadata) with transactional safety — changes are staged, backed up, and committed atomically.

govctl migrate vs the /migrate Workflow

These are related but serve different purposes:

Run govctl migrate when govctl reports an outdated schema version, missing or stale bundled schema files, or missing govctl-managed local-state .gitignore entries such as .govctl.lock and .govctl/. Schema versions below 3 require migration with a compatible earlier govctl version before upgrading. Legacy RFC or clause JSON storage is rejected explicitly. Use the /migrate skill when bringing an existing project under governance for the first time.

RFC-0000: govctl Governance Framework

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

1. Summary

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

govctl is a governance CLI that manages seven 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
• Conformance Cases: Current non-normative declarations relating acceptance scenarios to RFC versions and Guards

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).

Each reference MUST resolve to an existing Clause TOML file within the directory containing that RFC’s rfc.toml. Implementations MUST reject unresolved references and references whose resolved targets escape that directory, including through symbolic links.

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

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:

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 except a Conformance Case.

• RFC and ADR refs entries, [[...]] link targets, and known Conformance Case ID mentions in governed content fields MUST NOT identify a Conformance Case. Known Conformance Case ID mentions in governed Work Item prose MUST NOT identify a Conformance Case.

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 defines the RFC/ADR/Work Item authority hierarchy, inline reference syntax expectations, and the Conformance Case target restriction. It does not impose other 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.

Conformance Cases are mutable current declarations rather than durable authorities. Prohibiting RFC, ADR, and Work Item references to them prevents later Case edits or deletion from rewriting the meaning of authoritative specifications, decisions, or historical execution records.

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.

Tags: core, validation

Since: v1.1.0

Changelog

v1.9.0 (2026-07-27)

Define Conformance Case authority boundary

Added

• Recognize Conformance Cases as derived governance resources

Changed

• Exclude Conformance Cases as RFC, ADR, and Work Item reference targets

v1.8.0 (2026-07-26)

Define contained Clause reference resolution

Fixed

• Reject dangling Clause references

Security

• Require Clause references to resolve within their RFC directory

v1.7.0 (2026-07-20)

Define single-candidate RFC version boundaries

Changed

• Restrict version-changing bumps to sealed RFC versions
• Allow deletion of unreferenced Clauses introduced in the current spec candidate

v1.6.1 (2026-07-16)

Clarify Clause version assignment at RFC publication boundaries

Fixed

• Keep draft Clause versions pending until normative finalization

v1.6.0 (2026-07-16)

Define current-version RFC authoring and changelog invariants

Changed

• Defined spec-phase sealing, Clause version assignment, and current changelog ownership

v1.5.0 (2026-07-15)

Define guarded correction for local release cuts

Added

• Define guarded newest-release correction and canonical changelog projection

Changed

• Define Releases as local version-cut records

v1.4.2 (2026-07-15)

Clarify optional Work Item verification lists

Changed

• Define omitted verification guard and waiver lists as empty

v1.4.1 (2026-07-15)

Clarify Work Item serialized field requirements

Changed

• Allow empty Work Item list fields to be omitted while requiring created metadata and completion criteria

v1.4.0 (2026-07-15)

Clarify lifecycle and ADR projection boundaries

Added

• Define ADR projection ownership validation

Changed

• Scope RFC phase to each version
• Freeze Work Items at unique release membership

v1.3.3 (2026-06-11)

Clarify inline reference validation

Changed

• Project validation should warn on known artifact IDs in governed prose that are not written with inline reference syntax

v1.3.2 (2026-06-04)

Align reference hierarchy wording

Changed

• reference hierarchy wording now describes only the RFC-to-ADR-or-Work Item and ADR-to-Work Item prohibitions

v1.3.1 (2026-06-04)

Close plain-text reference hierarchy loophole

Changed

• Known lower-authority artifact IDs in governed RFC/ADR prose are validated even without [[…]] delimiters

v1.3.0 (2026-06-04)

Remove legacy JSON artifact storage compatibility

Removed

• legacy RFC and clause JSON storage is no longer supported in normal operation

v1.2.0 (2026-05-31)

Remove a legacy execution-history field from Work Item field operations

Changed

• historical execution entries may still be parsed for Work Item rendering

Removed

• legacy execution-history field is no longer path-addressable per ADR-0047

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

RFC-0001: Lifecycle State Machines

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

1. Summary

[RFC-0001:C-SUMMARY] Summary (Informative)

This RFC defines state machines governing RFC, ADR, Work Item, and Clause lifecycles, including the additional transition gates that control when work may be treated as complete.

Tags: lifecycle

Since: v0.1.0

2. Specification

[RFC-0001:C-RFC-STATUS] RFC Status Transitions (Normative)

An RFC MUST have exactly one of the following status values:

1. draft — Initial state. The RFC is under development and not yet binding.
2. normative — The RFC defines required behavior. Implementations MUST conform. Normative RFCs MAY be amended via version bumping; amendments MUST include a changelog entry documenting the change.
3. deprecated — The RFC is no longer recommended. Existing conforming implementations MAY continue, but new implementations SHOULD NOT use this RFC.

Valid transitions:

• draft → normative (via finalize command)
• normative → deprecated (via deprecate command)

Invalid transitions (MUST be rejected):

• normative → draft (no “un-finalize”)
• deprecated → normative (no resurrection)
• deprecated → draft (no resurrection)
• Any skip (e.g., draft → deprecated directly)

Tags: lifecycle

Since: v0.1.0

[RFC-0001:C-RFC-PHASE] RFC Phase Transitions (Normative)

An RFC MUST have exactly one of the following phase values. The phase describes conformance work for the RFC’s current version:

1. spec - Specification phase. The current version candidate is being written. Implementation work against that candidate is not permitted.
2. impl - Implementation phase. Code is being written to conform to the sealed current version.
3. test - Testing phase. Implementation is complete; tests are being written and validated against the sealed current version.
4. stable - Stable phase. Implementation and tests for the sealed current version are complete.

Within one RFC version, valid transitions are forward only via the advance command:

• spec -> impl
• impl -> test
• test -> stable

Within one RFC version, the following transitions MUST be rejected:

• Any backward transition (for example, impl -> spec)
• Any skip (for example, spec -> test or spec -> stable)
• stable -> any (stable is terminal for that version)

A version bump that releases a detected RFC or clause content amendment MUST start the new RFC version in spec, regardless of the prior version’s phase. This starts a new version lifecycle and is not a backward transition within one version. Version-changing bump eligibility MUST follow RFC-0000:C-PHASE-LIFECYCLE.

Only a normative RFC MAY advance from spec to impl. A normative RFC’s current spec content is an authoring candidate rather than an implementation conformance baseline. The most recently sealed version remains the implementation baseline until the current candidate enters impl.

RFC and clause content MAY change while the current version remains in spec. Such changes belong to the current version. Such changes MUST NOT require another version bump. Advancing from spec to impl MUST set or replace the current version’s stored signature with the current amendment content. The transition MUST reject every pending clause defined by RFC-0000:C-CLAUSE-DEF.

After the current version enters impl, amendment content that differs from the stored signature MUST be treated as an unversioned amendment. Phase progression MUST reject that amendment until a version bump releases it and starts the next version in spec.

Changelog-only updates MUST preserve the current phase. Changelog-only updates MUST preserve the current signature. Establishing or replacing the signature while sealing a spec version MUST preserve the selected RFC version.

Amendment content and bookkeeping fields are defined by RFC-0000:C-PHASE-LIFECYCLE.

Rationale: Scoping phase to the current RFC version preserves ordered specification, implementation, and testing gates while allowing the RFC itself to evolve through versioned amendments. Treating spec as the current version’s mutable authoring boundary avoids version inflation, while sealing at impl gives implementation a precise contract.

Tags: lifecycle

Since: v0.1.0

[RFC-0001:C-WORK-STATUS] Work Item Status Transitions (Normative)

A Work Item MUST have exactly one of the following status values:

1. queue — Initial state. The work item is defined but not yet started.
2. active — The work item is currently being worked on.
3. done — The work item is complete and eligible for release. All acceptance criteria are satisfied, and any required verification guards have passed or been explicitly waived.
4. cancelled — The work item was abandoned. No further work will be done.

Valid transitions via the move command are:

• queue → active (start work)
• queue → cancelled (abandon before starting)
• active → done (complete work)
• active → cancelled (abandon in progress)
• done → active when no release references the Work Item (correct a pre-release completion)

The following transitions MUST be rejected:

• done → active when any release references the Work Item
• done → queue or cancelled
• cancelled → any (cancelled is terminal)
• queue → done (cannot complete without being active)
• active → queue (no “un-start”)

Release membership is derived from releases[].refs; it does not add another Work Item status. A released Work Item MUST remain done.

Timestamp behavior:

• queue → active: Sets started if it is not already set
• active → done: Sets completed
• active → cancelled: Sets completed
• done → active: Preserves started and removes completed

Returning a Work Item to done after reopening MUST apply the same acceptance-criteria and verification-guard gates as any other active → done transition.

Reopening a Work Item MUST NOT mutate existing loop state or round artifacts. Existing loop-local done, failed, and cancelled outcomes remain terminal according to RFC-0006:C-WORK-ITEM-INTERACTION, RFC-0006:C-LOOP-RESUMPTION, and RFC-0006:C-LOOP-SCOPE-MUTATION. A reopened Work Item can be executed through a new loop or explicit non-terminal loop scope according to those clauses.

Rationale: Completion remains correctable until release membership freezes the lifecycle record. Clearing completed on reopening keeps status and timestamp semantics consistent, while release membership prevents the same Work Item ID from re-entering later release collection. Keeping loop outcomes separate preserves existing execution audit history.

Tags: lifecycle

Since: v0.1.0

[RFC-0001:C-ADR-STATUS] ADR Status Transitions (Normative)

An ADR MUST have exactly one of the following status values:

1. proposed — Initial state. The decision is under consideration.
2. accepted — The decision has been accepted and is in effect.
3. rejected — The decision was considered and explicitly declined.
4. superseded — The decision has been replaced by another ADR.

Valid transitions:

• proposed → accepted (via accept command)
• proposed → rejected (via reject command)
• accepted → superseded (via supersede command, requires --by to specify replacement)

Invalid transitions (MUST be rejected):

• proposed → superseded (cannot supersede without first accepting)
• accepted → proposed (no “un-accept”)
• accepted → rejected (accepted decisions must be superseded, not retroactively rejected)
• rejected → any (rejected is terminal)
• superseded → any (superseded is terminal)

When an ADR is superseded:

• The superseded_by field MUST be set to the ID of the replacing ADR
• The replacing ADR SHOULD reference the superseded ADR

When an ADR is rejected:

• The ADR MUST remain available as historical record
• The superseded_by field MUST NOT be set

Tags: lifecycle

Since: v0.1.0

[RFC-0001:C-CLAUSE-STATUS] Clause Status Transitions (Normative)

A Clause MUST have exactly one of the following status values:

1. active — Default state. The clause is in effect.
2. deprecated — The clause is no longer recommended but still valid.
3. superseded — The clause has been replaced by another clause.

Valid transitions:

• active → deprecated (via deprecate command)
• active → superseded (via supersede command, requires replacement clause)
• deprecated → superseded (already deprecated, now replaced)

Invalid transitions (MUST be rejected):

• deprecated → active (no resurrection)
• superseded → any (superseded is terminal)

A clause supersession transition has the following preconditions:

• The replacing clause MUST exist.
• The replacing clause MUST be active when the transition is performed.
• The replacing clause MUST be different from the clause being superseded.
• A replacing clause in another RFC MUST be identified by its qualified RFC-NNNN:C-NAME ID.

The transition MUST be rejected if any required precondition is not satisfied.

After a successful clause supersession transition:

• The source clause status MUST be superseded.
• The source clause superseded_by field MUST identify the direct replacing clause selected for that transition.
• The replacing clause SHOULD have a since field indicating the version it was introduced.

Every populated superseded_by field defines a directed edge from its source clause to its target clause. The clause supersession graph consists of these edges across every RFC in the governed project.

Repository validation MUST reject an edge whose target clause does not exist. Repository validation MUST NOT reject an existing edge solely because its target clause was later deprecated or superseded.

If clause A identifies clause B as its direct replacement and B is later replaced by clause C, B MUST identify C as its direct replacement. Clause A MUST continue to identify B. The clause supersession graph MUST NOT contain a cycle. Repository validation MUST reject a graph that contains a cycle.

Rationale:

Transition-time checks ensure that a newly selected replacement is in effect. Persisted edges record historical direct replacements, so later clause evolution does not invalidate or erase prior provenance. Qualified IDs allow the same model to represent unambiguous replacements across RFC boundaries.

Tags: lifecycle

Since: v0.1.0

[RFC-0001:C-GATE-CONDITIONS] Transition Gate Conditions (Normative)

Certain transitions have additional gate conditions beyond the state machine rules.

Work Item -> done:

1. The work item MUST have at least one acceptance criterion defined.
2. All acceptance criteria MUST have status done or cancelled.
3. Every guard named in the work item’s verification.required_guards MUST pass or be explicitly waived with a reason.
4. If project verification is enabled, every project-level default guard MUST also pass or be explicitly waived with a reason.

The effective required verification guards are the union of the work item’s verification.required_guards and, only when project verification is enabled, the project’s configured default guards. Only guards covered by explicit waivers are removed from that set.

Rationale: Prevents marking work as complete without defined success criteria or executable completion proof.

RFC draft -> normative:

• No additional gates (policy decision, not structural).

RFC phase spec -> impl:

• RFC status MUST be normative.
• Every clause MUST have a resolved since version under RFC-0000:C-CLAUSE-DEF.

Rationale: Implementation must follow a ratified and version-resolved specification.

RFC phase impl -> test:

• No additional gates.

RFC phase test -> stable:

• No additional gates (assumes tests are passing externally).

Future gates MAY be added via RFC amendment, but MUST NOT break existing valid workflows. Project verification MUST default to disabled when the project config does not opt into it.

Tags: lifecycle, validation

Since: v0.1.0

Changelog

v0.7.0 (2026-07-20)

Clarify RFC candidate phase transitions

Changed

• Bind version bumps and signature sealing to explicit phase boundaries

v0.6.0 (2026-07-16)

Align RFC phase gates with current-version sealing

Changed

• Required normative status and resolved Clause versions before implementation entry

v0.5.0 (2026-07-15)

Scope terminal states to versions and releases

Changed

• Restart phase progression for amended RFC versions
• Allow unreleased done Work Items to return to active

v0.4.2 (2026-06-28)

Split direct-edge preservation requirements

Changed

• Express B-to-C insertion and A-to-B preservation as separate testable obligations

v0.4.1 (2026-06-28)

Clarify clause supersession validation boundaries

Added

• Define project-wide direct-edge graph semantics and explicit rejection behavior for missing targets and cycles

Changed

• Separate transition-time replacement checks from persisted graph validation
• Document the distinct-target rule and preserve historical edges after target status changes

v0.4.0 (2026-06-28)

Define direct clause supersession chains

Added

• Require active transition targets, qualified cross-RFC references, and acyclic supersession graphs

Changed

• Treat superseded_by as a persistent direct replacement edge

v0.3.0 (2026-03-17)

Add executable verification gates to work completion

Added

• Added required verification guard gate conditions for work completion

v0.2.1 (2026-01-26)

Remove ADR reference from C-RFC-STATUS; RFCs are self-contained and should not reference ADRs

Added

• Inline amendment rule in C-RFC-STATUS clause (was referencing ADR-0016)

v0.2.0 (2026-01-19)

Clarify that normative RFCs may be amended via version bumping

v0.1.0 (2026-01-17)

Initial draft

RFC-0002: CLI Resource Model and Command Architecture

Version: 3.6.0 | Status: normative | Phase: stable Owners: @govctl-org Tags: cli, editing, lifecycle, validation, release

1. Summary

[RFC-0002:C-SUMMARY] Summary (Informative)

This RFC defines the resource-first command architecture for the govctl CLI. It establishes normative requirements for command structure, resource types, verb semantics, and project-level verification commands to ensure consistency and discoverability.

The design follows established patterns from Docker, kubectl, and other modern CLIs where commands are grouped by resource type (noun-first) rather than operation type (verb-first).

Scope: This RFC specifies the structural contract (which commands exist, how they’re organized, what resources they operate on). Implementation details (flag syntax, help text formatting, terminal colors) are left to ADRs.

Rationale: A stable command structure enables:

1. Predictable UX across all resource types
2. Agent/script automation via consistent patterns
3. Scoped help and command discovery
4. Future extensibility without namespace pollution

Tags: cli

Since: v0.1.0

2. Specification

[RFC-0002:C-RESOURCE-MODEL] Resource-First Command Structure (Normative)

The govctl CLI MUST use a resource-first command structure. Except for the stable release-creation form defined below, resource operations MUST use:

govctl <resource> <verb> [arguments] [flags]

Where:

• <resource> is a governance artifact type such as rfc, adr, work, clause, release, or guard
• <verb> is an operation defined for that resource, such as new, list, get, show, edit, delete, or a resource-specific lifecycle operation
• [arguments] are positional parameters with stable roles
• [flags] are modifiers defined by the selected operation

Only command and subcommand names defined by normative RFC clauses are part of the accepted CLI grammar. Implementations MUST reject alternative command-name and subcommand-name aliases. This restriction does not prohibit short option flags that are part of a documented command syntax.

Global command exceptions are governed by RFC-0002:C-GLOBAL-COMMANDS. A command MAY remain at the global namespace when it operates across multiple resource types, performs project-level or CLI-level work, or manages local execution state that coordinates governed resources without becoming a governed artifact resource.

Resource-specific CRUD, field-editing, and lifecycle operations MUST remain resource-first unless an RFC explicitly defines an alternative grammar.

Release creation is a stable alternative grammar. Implementations MUST support govctl release <version> [--date <YYYY-MM-DD>].

Release correction is a resource-first operation. Implementations MUST support govctl release undo <expected-version>.

Both release forms MUST coexist. The token undo selects correction because it is not a valid semantic version; a semantic-version token selects release creation.

Rationale:

Resource-first organization provides scoped discovery, clear namespaces, stable argument roles, and room to extend one resource without polluting the global namespace. A canonical-only command vocabulary removes parser ambiguity and prevents documentation and agent metadata from teaching multiple spellings for the same operation.

Tags: cli

Since: v0.1.0

[RFC-0002:C-RESOURCES] Resource Types (Normative)

The following resource types MUST be supported as top-level command namespaces:

1. rfc - Request for Comments

Manages RFC specifications (normative documents defining system behavior).

• ID Format: RFC-NNNN (e.g., RFC-0001)
• Lifecycle: draft → normative → deprecated (per RFC-0001:C-RFC-STATUS)
• Phase: spec → impl → test → stable (per RFC-0001:C-RFC-PHASE)

2. adr - Architecture Decision Record

Manages ADRs (records of architectural decisions).

• ID Format: ADR-NNNN (e.g., ADR-NNNN-style IDs)
• Lifecycle: proposed → accepted → superseded, or proposed → rejected (per RFC-0001:C-ADR-STATUS)

3. work - Work Item

Manages Work Items (tasks, features, bugs).

• ID Format: WI-YYYY-MM-DD-NNN (e.g., WI-YYYY-MM-DD-NNN)
• Lifecycle: queue → active → done, with cancellation at any stage (per RFC-0001:C-WORK-STATUS)

4. clause - RFC Clause

Manages individual clauses within RFCs.

• ID Format: RFC-NNNN:C-NAME (e.g., RFC-0001:C-SUMMARY)
• Lifecycle: active → deprecated → superseded (per RFC-0001:C-CLAUSE-STATUS)

Clause Namespace vs Storage:

Clauses remain at the CLI top-level namespace despite being child resources of RFCs because their ID format (RFC-NNNN:C-NAME) is self-scoping and unambiguous.

The CLI namespace is independent of filesystem layout. Implementations MAY store clause files nested under RFC directories (e.g., gov/rfc/RFC-0001/clauses/C-NAME.toml) while maintaining the flat CLI command structure (govctl clause get RFC-0001:C-NAME).

5. guard - Verification Guard

Manages reusable executable completion checks defined by RFC-0000:C-GUARD-DEF.

• ID Format: GUARD-NAME (e.g., GUARD-CARGO-TEST)
• Storage: gov/guard/ as individual TOML files
• No lifecycle (guards are either present or removed)

6. conformance - Conformance Case

Manages current non-normative acceptance-scenario declarations.

• ID Format: CONF-[A-Z][A-Z0-9-]* (e.g., CONF-RFC-BUMP)
• Storage: gov/conformance/ as individual TOML files
• No persistent lifecycle status

7. release - Release Cut

Manages local version-cut records and their included Work Item references.

• ID Format: Semantic version (e.g., 1.0.0)
• Storage: gov/releases.toml as defined by RFC-0000:C-RELEASE-DEF
• Mutation boundary: the newest entry may be corrected through release undo; all other entries are immutable
• No persistent lifecycle status

Resource Identification:

Each resource type MUST have a unique, predictable ID format that:

1. Is stable across filesystem operations
2. Can be referenced in other artifacts
3. Clearly identifies the resource type without context
4. Supports lexicographic sorting where meaningful
5. Is case-sensitive (RFC-0001 ≠ rfc-0001)

Date Format:

All date-valued resource metadata fields (such as created, updated, started, completed, and date) MUST use ISO 8601 calendar date format YYYY-MM-DD.

Tags:

RFCs, clauses, ADRs, Work Items, guards, and Conformance Cases MAY include an optional tags array in the [govctl] section. Each tag MUST be a string from the project’s controlled vocabulary defined in gov/config.toml under [tags] allowed. Tags MUST match the pattern [a-z][a-z0-9-]* (lowercase kebab-case). Releases do not carry tags. govctl check MUST reject any artifact that references a tag not present in the allowed set.

Future Extensions:

Additional resource types MAY be added via RFC amendment. New resource types MUST follow the same structural patterns defined in RFC-0002:C-CRUD-VERBS.

Tags: cli, schema

Since: v0.1.0

[RFC-0002:C-CRUD-VERBS] Universal CRUD Verbs (Normative)

Governed artifact resources MUST expose the following universal operations where applicable. Release records MUST NOT expose these operations; their constrained creation and correction commands are defined by RFC-0002:C-LIFECYCLE-VERBS.

1. new - Create Resource

Syntax: govctl <resource> new <arguments>

new MUST be supported for RFCs, ADRs, Work Items, Clauses, Guards, and Conformance Cases. It MUST validate inputs. It MUST generate or validate the resource ID. It MUST initialize schema-defined defaults and create the canonical storage structure.

Guard creation through govctl guard new "<title>" MUST scaffold a Guard TOML file under gov/guard/. The generated ID MUST use the GUARD- prefix. The command SHOULD print guidance for adding the Guard to project verification policy.

2. list - List Resources

Syntax: govctl <resource> list [status] [--tag <tag>[,<tag>...]]

list MUST be supported for RFCs, ADRs, Work Items, Clauses, Guards, and Conformance Cases. Results MUST be sorted lexicographically by ID. A positional status filter, where supported by the resource lifecycle, MUST accept only that resource’s defined status values. Tag filtering MUST require every requested tag. Tag filtering MUST accept comma-separated tag values for taggable resource types. Output MUST follow RFC-0002:C-OUTPUT-FORMAT.

3. get - Read Resource

Syntax: govctl <resource> get <id> [field]

get MUST be supported for RFCs, ADRs, Work Items, Clauses, Guards, and Conformance Cases. With no field, it returns the complete structured resource. With a field, it returns that logical field value. Unknown resources and fields MUST be rejected. Output MUST follow RFC-0002:C-OUTPUT-FORMAT.

Field identifiers exposed by get MUST be logical artifact field names rather than persisted table-layout paths. Renaming a logical field identifier requires a breaking govctl release.

4. show - Present Resource

Syntax: govctl <resource> show <id> [--history] [--output <format>]

show MUST be supported as defined by RFC-0002:C-SHOW-PROJECTION.

5. edit - Mutate Resource

Syntax:

govctl <resource> edit <id> <path> --set [<value>]
govctl <resource> edit <id> <path> --add [<value>]
govctl <resource> edit <id> <path> --remove [<pattern>]
govctl <resource> edit <id> <path> --tick <status>

edit MUST be supported for RFCs, ADRs, Work Items, Clauses, Guards, and Conformance Cases. It MUST be the only universal field-mutation subcommand for those resources. These resources MUST NOT expose set, add, remove, or tick as sibling mutation subcommands.

An edit invocation MUST select exactly one mutation operation. --stdin MAY supply the value for --set or --add. Selectors and their exclusivity rules are defined by RFC-0002:C-EDIT-FIELD-CONTRACT.

A path MUST use a canonical logical path defined by RFC-0002:C-EDIT-FIELD-CONTRACT. Nested object and array traversal MUST use dotted and indexed segments such as alternatives[0].pros. The parser MUST consume the complete path. Unknown fields MUST be rejected. Invalid indices MUST be rejected. Aliases and wire-layout prefixes MUST be rejected. An operation not permitted for the addressed path MUST be rejected.

The same edit grammar and flag roles MUST apply across supported resource types. Resource-specific compatibility flags MUST be rejected. Values MUST be validated against the addressed field type before writing. A failed edit MUST leave the artifact unchanged.

6. delete - Delete Resource

Syntax: govctl <resource> delete <id>

delete MUST be supported for Work Items, Clauses, Guards, and Conformance Cases. RFCs and ADRs MUST use their lifecycle operations instead.

For Guards, deletion MUST reject references from Work Item verification requirements, Work Item waivers, project default Guards, and Conformance Case guard bindings.

For Clauses, deletion MUST enforce RFC-0000:C-CLAUSE-DEF and report every governed referrer that prevents deletion.

For Work Items, deletion MUST require queue status and MUST reject any governed referrer.

Deletion SHOULD require confirmation unless an explicit force option is provided. A delete operation MUST be atomic.

Consistency requirements:

• ID arguments MUST precede field paths across resources.
• Equivalent universal operations MUST use the same flag names and exit-code conventions.
• Error messages MUST identify the rejected resource, field path, or value.
• Input transport such as stdin MUST NOT change mutation semantics.
• A mutating universal operation invoked with --dry-run MUST perform the same validation and target selection as execution, MUST report the planned mutation, and MUST leave persistent state unchanged.

Rationale:

A path-oriented mutation command lets users and agents select a field and then apply one permitted operation. A closed canonical field contract removes ambiguous spellings while retaining set, add, remove, and checklist-transition capabilities.

Tags: cli, editing

Since: v0.1.0

[RFC-0002:C-LIFECYCLE-VERBS] Resource-Specific Lifecycle Operations (Normative)

Resource-specific lifecycle and constrained-mutation operations implement state transitions defined in RFC-0001 or mutation defined by their resource contract. These operations MUST be scoped to their resource namespace.

RFC Lifecycle Operations:

1. govctl rfc finalize <id> normative

   • Implements the draft -> normative transition in RFC-0001:C-RFC-STATUS.
   • Assigns the RFC’s current version to pending clauses as defined by RFC-0000:C-CLAUSE-DEF.

2. govctl rfc deprecate <id>

   • Implements the normative -> deprecated transition in RFC-0001:C-RFC-STATUS.

3. govctl rfc advance <id> <spec|impl|test|stable>

   • Implements RFC-0001:C-RFC-PHASE transitions.
   • Phase progression MUST be forward-only within the current RFC version.
   • A spec -> impl transition MUST require normative RFC status.
   • A spec -> impl transition MUST reject every pending clause.
   • A spec -> impl transition MUST NOT assign clause version metadata.
   • A spec -> impl transition MUST set or replace the stored amendment signature with a signature of the current amendment content.
   • A later phase transition MUST reject amendment content that differs from the stored signature.

4. govctl rfc bump <id> <patch|minor|major> -m <message>

   • The version-changing form MUST require normative RFC status.
   • The version-changing form MUST enforce the source-phase and stored-signature eligibility in RFC-0000:C-PHASE-LIFECYCLE.
   • Rejection for draft or deprecated RFC status, phase spec, or a missing sealed signature MUST occur without mutation.
   • Missing-signature rejection outside spec MUST leave pending clauses unchanged and MUST instruct the user to migrate the repository or restore its sealed baseline.
   • Version bumping MUST follow semantic versioning.
   • A version bump MUST update the changelog automatically.
   • A version bump MAY include --change <description> for additional changelog entries.
   • A version bump MUST be rejected when the RFC has a stored amendment signature and no amendment content has changed since that signature.
   • Amendment comparison MUST exclude RFC version, phase, changelog, and signature fields.
   • A bump that releases detected RFC or clause content MUST set phase to spec.
   • A bump MUST assign its new version to pending clauses as defined by RFC-0000:C-CLAUSE-DEF.
   • --change without a bump level MUST remain a changelog-only operation.
   • The normative-status and source-phase requirements for version-changing bumps MUST NOT apply to --change without a bump level.
   • --change without a bump level MUST resolve the unique current changelog entry by matching the entry version to the RFC version.
   • --change without a bump level MUST reject zero or multiple current entries without mutation.
   • --change without a bump level MUST preserve the RFC version.
   • --change without a bump level MUST preserve the current changelog date.
   • --change without a bump level MUST preserve phase.
   • --change without a bump level MUST preserve the amendment signature.
   • --change without a bump level MUST NOT make a later version bump valid.
   • A change prefixed by add:, change:, deprecate:, remove:, fix:, or security: MUST be appended to the corresponding changelog category.
   • A change without a category prefix MUST be appended to added.
   • An unknown category prefix MUST be rejected.

5. RFC current-version changelog access

   • govctl rfc get <id> changelog MUST expose only the unique changelog entry whose version matches the RFC’s current version.
   • The field result MUST be one object rather than an array.
   • The object MUST contain version, date, summary, added, changed, deprecated, removed, fixed, and security fields.
   • summary MAY be a string or null.
   • Each categorized field MUST be an array of strings.
   • Full-resource retrieval and RFC rendering MAY include historical changelog entries.
   • Indexed changelog get paths MUST be rejected.
   • Nested changelog get paths MUST be rejected.
   • govctl rfc edit <id> changelog.summary --set <value> MUST update the current entry’s summary.
   • govctl rfc edit <id> changelog.<category> --add <value> MUST append to one of added, changed, deprecated, removed, fixed, or security.
   • govctl rfc edit <id> changelog.<category>[<index>] --remove MUST remove an indexed item from the current category.
   • Current-entry resolution MUST match by version.
   • Current-entry resolution MUST NOT depend on changelog array position.
   • Current-changelog operations MUST reject zero or multiple current entries without mutation.
   • Changelog editing MUST reject historical entry selection.
   • Changelog editing MUST reject changelog version and date paths.
   • RFC editing MUST reject the top-level RFC version path.
   • Changelog editing MUST preserve the RFC version.
   • Changelog editing MUST preserve phase.
   • Changelog editing MUST preserve the amendment signature.
   • Changelog editing MUST preserve the current changelog date.

6. govctl rfc supersede <id> --by <replacement-id>

   • Marks RFC as superseded by another RFC.
   • Both RFCs must exist.

ADR Lifecycle Operations:

1. govctl adr accept <id>

   • Implements RFC-0001:C-ADR-STATUS proposed -> accepted.

2. govctl adr reject <id>

   • Implements RFC-0001:C-ADR-STATUS proposed -> rejected.

3. govctl adr supersede <id> --by <replacement-id>

   • Implements RFC-0001:C-ADR-STATUS accepted -> superseded.
   • Both ADRs must exist.

Work Lifecycle Operations:

1. govctl work move <id> <queue|active|done|cancelled>
   • Implements RFC-0001:C-WORK-STATUS transitions.
   • Validates gate conditions when entering done.
   • MUST reject done -> active when any release references the Work Item.
   • queue -> active MUST set started when it is absent.
   • active -> done MUST set completed.
   • active -> cancelled MUST set completed.
   • done -> active MUST preserve started.
   • done -> active MUST remove completed.
   • done -> active MUST NOT mutate loop state or round artifacts governed by RFC-0006:C-WORK-ITEM-INTERACTION.

Release Lifecycle Operations:

1. The CLI MUST support govctl release <version> [--date <YYYY-MM-DD>]. The operation MUST create the newest local release entry according to RFC-0000:C-RELEASE-DEF.

2. The CLI MUST support govctl release undo <expected-version>. The operation MUST correct the newest local release entry according to RFC-0000:C-RELEASE-DEF.

Clause Lifecycle Operations:

1. govctl clause new <id> <title>

   • MUST assign or defer since according to the parent RFC status and phase rules in RFC-0000:C-CLAUSE-DEF.

2. govctl clause deprecate <id>

   • Implements RFC-0001:C-CLAUSE-STATUS active -> deprecated.

3. govctl clause supersede <id> --by <replacement-id>

   • Implements RFC-0001:C-CLAUSE-STATUS active/deprecated -> superseded.
   • Both clauses must exist.

Consistency Requirements:

1. All lifecycle operations MUST validate transitions per RFC-0001 or their resource definition.
2. All lifecycle operations MUST update timestamp fields where applicable.
3. Except for the rollback-failure path in requirement 4, before a lifecycle invocation exits with a non-zero status, it MUST restore each governed-artifact path it created, deleted, or wrote to the path-existence state observed at baseline and, when that path existed at baseline, to its baseline byte content.
4. If an I/O or storage error prevents complete restoration, the invocation MUST return a non-zero exit status.
5. The rollback-failure diagnostic MUST contain the term rollback.
6. The rollback-failure diagnostic MUST state that governed-artifact restoration may be incomplete.
7. For each governed-artifact path covered by requirement 3, the restoration baseline is whether its resolved path existed and, when it existed, its artifact byte content observed after the invocation acquires its exclusive write scope under RFC-0004:C-SCOPE and before its first governed-artifact mutation.
8. Unexpected process termination before restoration completes, host failure, and the rollback-failure path in requirement 4 are outside the lifecycle atomicity guarantee.
9. Permissions, ownership, timestamps, and other filesystem metadata are outside the lifecycle atomicity guarantee.
10. All lifecycle operations MUST support global --dry-run flag.
11. Invalid transitions MUST error with clear explanation of valid transitions.

Rationale:

Lifecycle operations are resource-specific because:

• RFCs have status AND phase (two dimensions of state).
• ADRs can be rejected (not applicable to RFCs).
• Work Items have gate conditions (acceptance criteria).
• Release correction has a newest-entry and expected-version boundary.
• Each resource has different valid transitions.

Scoping these operations to resources makes their applicability explicit and prevents confusion. Lifecycle atomicity defines path existence and byte content for the non-zero exits covered by requirement 3; it does not require filesystem-metadata restoration or a crash-recovery subsystem for the flat-file artifact store.

Tags: cli, lifecycle

Since: v0.1.0

[RFC-0002:C-OUTPUT-FORMAT] Output Format Control (Normative)

All commands that output resource data MUST support the --output (or -o) flag with the following format options:

Required Output Formats:

1. table (default for human use)

   • Formatted tables with headers and aligned columns
   • MAY use colors when terminal supports them
   • MUST be readable in plain text (no control codes in non-TTY)

2. json

   • Valid JSON output
   • Pretty-printed with 2-space indentation
   • MUST be parseable by standard JSON tools

3. yaml

   • Valid YAML output
   • Formatted for readability
   • MUST be parseable by standard YAML tools

4. toml

   • Valid TOML output (native format for governance artifacts)
   • MUST be parseable by standard TOML tools

5. plain

   • Plain text values with no formatting
   • One value per line for lists
   • Single value (no newline) for scalar fields
   • Suitable for shell scripting and piping

Applicability:

Commands MUST support output formats as follows:

• get with no field: table, json, yaml, toml
• get with field: plain (default), json, yaml
• list: table (default), json, yaml

Commands MAY add format-specific flags (e.g., --format-json-compact) but MUST NOT remove or change behavior of standard formats.

Format Selection:

1. Explicit --output <format> takes precedence
2. If not specified:
   • For TTY: default is table
   • For non-TTY: default MUST be json
3. Invalid format names MUST error with list of valid formats

Exceptions:

govctl status is exempt from output format requirements and always produces human-readable tabular output intended for interactive use only.

govctl conformance trace is a scoped exception and supports only table and json.

Consistency Requirements:

1. JSON/YAML/TOML output MUST match the internal schema exactly
2. Table format MAY omit fields for readability but MUST show all critical fields
3. Plain format MUST output stable, parseable text (no decorations)
4. Output format MUST NOT affect command semantics (same data, different representation)

Rationale:

Universal output format control enables:

• Human readability (table)
• Script automation (json/yaml)
• Integration with standard tools (jq, yq)
• Native format inspection (toml for governance artifacts)

This pattern follows kubectl and Docker conventions where -o json works on all read operations.

Tags: cli

Since: v0.1.0

[RFC-0002:C-GLOBAL-COMMANDS] Global Commands (Normative)

The following commands operate at the project or CLI level and MUST remain at the global namespace level rather than under an artifact resource namespace:

1. govctl init

Initializes a new govctl project in the current directory.

Syntax: govctl init [--force]

Behavior:

• Creates gov/ directory structure
• Generates gov/config.toml declaring project schema version 5
• Creates subdirectories for RFCs, ADRs, Work Items, verification guards, and Conformance Cases
• Installs bundled JSON Schema files under gov/schema/
• MUST error if already initialized (unless --force)
• MUST NOT install agent skills or agents (see init-skills)
• SHOULD print a hint about govctl init-skills and plugin installation

2. govctl check

Validates all governance artifacts across the project.

Syntax: govctl check [--deny-warnings]

Behavior:

• Validates RFCs, ADRs, clauses, work items, releases, verification guards, and Conformance Cases
• Implementations MUST define a corresponding machine-readable JSON Schema for each governance artifact type: RFC, clause, ADR, work item, release, verification guard, and Conformance Case
• These schemas MUST be JSON files stored under gov/schema/
• For TOML artifacts, MUST validate the canonical structured layout against the corresponding JSON Schema after parsing
• Checks state machine invariants
• Verifies cross-references
• Validates the semantic correctness of the optional [verification] section in gov/config.toml, including that configured default guard IDs resolve
• Scans source code for references (if enabled in config)
• MUST enforce the repository and unsupported-storage rules in RFC-0002:C-COMPATIBILITY-BOUNDARY before reporting successful validation
• If any bundled JSON Schema file under gov/schema/ is missing or differs from the current bundled schema, MUST report a schema-outdated diagnostic that instructs users to run govctl migrate
• If any govctl-managed local-state .gitignore entry is missing or outdated, MUST report a project-support-outdated diagnostic that instructs users to run govctl migrate
• Returns exit code 0 if valid, non-zero if errors
• With --deny-warnings: treats warnings as errors

3. govctl status

Shows summary counts of all artifacts grouped by status.

Syntax: govctl status

Behavior:

• Displays counts by status/phase for each resource type
• Highlights active work items
• Shows pending decisions (proposed ADRs, draft RFCs)
• Uses colors in TTY mode for visual scanning
• No output format flag (always human-readable table)

4. govctl render

Generates markdown documentation from source-of-truth governance artifacts.

Syntax: govctl render [targets...] [--dry-run] [--force]

Behavior:

• Renders RFCs from TOML to markdown (published)
• Renders ADRs from TOML to markdown (local only)
• Renders work items from TOML to markdown (local only)
• Generates CHANGELOG.md from releases
• For changelog rendering without --force: updates the unreleased section and adds missing releases while preserving existing released sections
• For changelog rendering with --force: regenerates the complete changelog from current canonical release data and Work Items
• Default: renders RFCs only
• With targets: rfc, adr, work, changelog, all
• MUST validate before rendering

5. govctl describe

Provides machine-readable discovery for agent and tool integration as defined by RFC-0002:C-DESCRIBE-COMMAND.

Syntax: govctl describe [--context]

6. govctl completions

Generates shell completion scripts.

Syntax: govctl completions <bash|zsh|fish|powershell>

Behavior:

• Outputs completion script for specified shell
• Can be sourced or installed per shell conventions

7. govctl migrate

Performs versioned repository-local format migration for governance artifacts.

Syntax: govctl migrate [--dry-run]

Behavior:

• Reads the current schema version from gov/config.toml [schema] version
• Enforces the minimum supported schema version in RFC-0002:C-COMPATIBILITY-BOUNDARY before planning file operations
• Runs all pending migration steps from a supported version to the latest
• Each step produces a set of file operations executed transactionally
• With --dry-run, MUST perform the same schema checks, repository validation, project-support discovery, and migration planning as execution; MUST report every planned file operation; and MUST leave persistent project and local state unchanged
• Bumps [schema] version in gov/config.toml after successful migration
• If a migration operation fails after changing any target, implementation MUST attempt rollback before returning
• When rollback succeeds, implementation MUST leave every migration target file unchanged and return the original operation failure
• If rollback fails, implementation MUST return E0903, identify that restoration may be incomplete and where recovery backups were retained, MUST NOT report migration success, and MUST NOT discard the recovery backups
• MUST be safe to run on an already-migrated repository and report a no-op result
• MUST NOT perform heuristic project discovery or broad adoption tasks
• MUST ensure all bundled JSON Schema files exist in gov/schema/, overwriting with the latest version regardless of schema version
• MUST ensure local govctl state ignore entries are present in .gitignore, including .govctl.lock and .govctl/, regardless of schema version
• MUST enforce the migration and unsupported-storage behavior in RFC-0002:C-COMPATIBILITY-BOUNDARY

8. govctl verify

Executes reusable verification guards.

Syntax:

• govctl verify [GUARD-ID ...]
• govctl verify --work WI-ID

Behavior:

• Loads Verification Guard artifacts from gov/guard/
• Explicit GUARD-ID arguments and --work WI-ID MUST NOT be combined in the same invocation
• With explicit GUARD-ID arguments: runs those guards
• With --work WI-ID: runs the effective required guards for that work item after applying project defaults and work-item waivers
• With no explicit guards and no --work: runs the project-level default guards from gov/config.toml
• Reads project-level verification policy from RFC-0002:C-VERIFY-CONFIG
• Executes each guard command non-interactively from the project root
• Reports pass/fail per selected guard
• Returns non-zero if any selected guard fails, if no guards are selected, or if a requested guard ID is unknown

9. govctl init-skills

Installs agent skills and agents into the project’s agent directory.

Syntax: govctl init-skills [--force] [--format <claude|codex>] [--dir PATH]

Behavior:

• --dir overrides the output directory for this invocation. Resolution order: --dir flag > agent_dir from config > format-implied default (.claude for claude, .codex for codex)
• --format selects the output format for agent definitions (default claude):
  • claude: skills as full skills/*/ bundles rooted at SKILL.md, agents as agents/*.md with YAML frontmatter (compatible with Claude Code, Cursor, Windsurf, and similar editors)
  • codex: skills as full skills/*/ bundles rooted at SKILL.md (same format), agents as agents/*.toml with developer_instructions field (compatible with Codex CLI)
• Skill bundle resources under directories such as references/, assets/, and scripts/ MUST be installed with their parent skill; agent output remains format-specific
• Skips files that already exist unless --force is used
• Reports created/updated/skipped counts
• This command is separate from init because plugin users receive skills globally and do not need local copies

10. govctl tag

Manages the project’s controlled tag vocabulary.

Syntax:

• govctl tag new <tag>
• govctl tag delete <tag>
• govctl tag list

Behavior:

• new: registers a new tag in gov/config.toml under [tags] allowed. Tags MUST match [a-z][a-z0-9-]* (lowercase kebab-case). MUST error if the tag already exists.
• delete: removes a tag from the allowed list. MUST error if any artifact still references the tag.
• list: displays all registered tags with usage counts (how many artifacts reference each tag).

Artifact-level tagging uses existing resource verbs on taggable types (rfc, clause, adr, work, guard, conformance):

• govctl {rfc|clause|adr|work|guard|conformance} edit <ID> tags --add <tag> - assign a tag to an artifact
• govctl {rfc|clause|adr|work|guard|conformance} edit <ID> tags --remove <tag> - remove a tag from an artifact

11. govctl self-update

Updates the govctl binary to the latest release.

Syntax: govctl self-update [--check]

Behavior:

• Downloads and replaces the running binary from GitHub Releases
• With --check: prints version comparison without downloading
• Full specification in RFC-0002:C-SELF-UPDATE

12. govctl loop

Manages project-local loop execution state for driving work items through iterative rounds.

Syntax: govctl loop <subcommand> [arguments] [flags]

Behavior:

• Operates on local execution state under .govctl/loops/, not on a governed artifact resource
• Coordinates work items, verification guards, and local loop state according to RFC-0006
• MUST NOT expose universal CRUD field-editing verbs for loop state
• MUST keep work item lifecycle transitions routed through govctl work semantics
• MUST use stable subcommand and argument semantics defined by RFC-0006:C-LOOP-COMMAND-SURFACE

13. govctl search

Searches governed artifacts across the project by user-provided query text.

Syntax: govctl search <query>... [--type <rfc|clause|adr|work|guard|conformance>]... [--tag <tag>]... [-n <limit>] [-o <table|json|plain>] [--reindex]

Behavior:

• Operates across RFCs, clauses, ADRs, work items, verification guards, and Conformance Cases according to RFC-0002:C-SEARCH-COMMAND
• MUST remain at the global namespace because it is project-level discovery across multiple governed resource types, not a resource-specific CRUD operation
• MUST NOT be required as a universal resource verb under each artifact namespace unless a future RFC amendment explicitly adds scoped search aliases

14. govctl agent

Manages the user-scoped govctl agent integration.

Syntax:

• govctl agent <doctor|install|update> <codex|claude|all>
• govctl agent hook <session-start|pre-tool-use> (internal adapter)

Behavior, including the internal adapter exception to runtime selection, is defined by RFC-0002:C-AGENT-INTEGRATION.

Rationale:

These commands are global because they:

1. Operate on multiple resource types simultaneously
2. Don’t fit the <resource> <verb> pattern semantically
3. Are project-level operations, not resource-level
4. Match user mental model of “project commands” vs “resource commands”
5. May manage local execution state that coordinates governed resources without becoming a governed resource itself

govctl migrate qualifies because it operates across the governance repository as a whole and changes multiple resource types in one coordinated step.

govctl verify qualifies because it executes project-level completion checks that may be required by multiple work items and by the project configuration.

govctl init-skills qualifies because it performs project-level initialization of agent assets (criterion 2).

govctl tag qualifies because it manages project-level configuration that applies across all resource types (criterion 1).

govctl self-update qualifies because it provides meta-information about the CLI itself and performs binary lifecycle management (criterion 3).

govctl loop qualifies because it manages local execution state that coordinates work items and verification guards without making loop state a governed resource (criterion 5).

govctl search qualifies because it performs project-level discovery across multiple governed resource types (criterion 1).

govctl agent qualifies because it manages CLI-level integration state for external agent runtimes without becoming a governed artifact resource (criterion 3).

Future Additions:

New global commands MAY be added via RFC amendment. They MUST meet at least one criterion:

1. Operate on multiple resource types
2. Perform project-level initialization or cleanup
3. Provide meta-information about the CLI itself
4. Manage local execution state that coordinates governed resources without becoming a governed resource itself

Tags: cli

Since: v0.1.0

[RFC-0002:C-VERIFY-CONFIG] Verification Configuration (Normative)

The project config file gov/config.toml MAY include an optional [verification] section.

When present, the section MUST support the following fields:

• enabled — boolean, default false
• default_guards — array of Verification Guard IDs, default []

If the section is absent, the implementation MUST behave as if enabled = false and default_guards = [].

Every guard ID listed in default_guards MUST resolve to an existing Verification Guard defined by RFC-0000:C-GUARD-DEF. Unknown IDs MUST cause validation failure.

When enabled = false, project-level default guards MUST NOT be applied automatically by govctl verify or by Work Item completion checks.

Work Item verification.required_guards remain effective regardless of the project-level enabled value.

Rationale: The project config controls whether shared default guard policy is active. Explicit Work Item requirements remain local and auditable instead of becoming inert metadata.

Tags: cli, validation

Since: v0.3.0

[RFC-0002:C-SELF-UPDATE] Self-Update Command (Normative)

11. govctl self-update

Updates the govctl binary to the latest release.

Syntax: govctl self-update [--check]

Behavior:

• Queries the GitHub Releases API for the govctl-org/govctl repository to determine the latest published version
• Compares the latest version against the running binary’s compiled version
• Without --check: downloads the platform-appropriate binary asset, verifies integrity, and replaces the running executable. MUST print the old and new version on success. MUST exit with code 0 if already up to date, printing a message indicating no update is needed.
• With --check: prints current version and latest available version without downloading. MUST exit with code 0 if up to date, exit with code 1 if a newer version is available.
• MUST detect the current platform target at compile time and select the matching release asset
• MUST display download progress when connected to a TTY
• MUST error with a clear message if the binary lacks write permission to its install location
• MUST error with a clear message if the GitHub API is unreachable or rate-limited
• SHOULD support GITHUB_TOKEN environment variable for authenticated API requests to avoid rate limits

Rationale:

A self-update command provides a single canonical update path that works regardless of how govctl was originally installed (cargo install, cargo binstall, or direct binary download). This meets criterion 3 of RFC-0002:C-GLOBAL-COMMANDS (meta-information about the CLI itself).

Tags: cli, release

Since: v0.8.0

[RFC-0002:C-SEARCH-COMMAND] Search Command (Normative)

govctl search searches governed artifacts by user-provided query text.

Syntax:

• govctl search <query>... [--type <rfc|clause|adr|work|guard|conformance>]... [--tag <tag>]... [-n <limit>] [-o <table|json|plain>] [--reindex]

Behavior:

• The command MUST operate at the global command namespace as an explicit RFC-0002:C-RESOURCE-MODEL exception listed in RFC-0002:C-GLOBAL-COMMANDS, because it searches across multiple governed resource types and is project-level discovery rather than a resource-specific CRUD operation.
• The command MUST search RFCs, clauses, ADRs, work items, verification guards, and Conformance Cases unless one or more --type filters are provided.
• Positional <query>... values MUST be interpreted as user search terms by default, not as backend-specific raw query syntax.
• The command MUST support artifact ID lookup as a search use case. A query containing an existing artifact ID SHOULD rank that artifact ahead of lower-confidence full-text matches. Results with equal relevance MUST be ordered lexicographically by artifact kind and then artifact ID.
• The command MUST support --tag <tag> filters. When multiple tags are provided, returned artifacts MUST contain all requested tags.
• The command MUST support -n, --limit <limit> and MUST apply a finite default limit when the flag is omitted.
• The command MUST support --reindex, which forces a rebuild of any local derived search index before returning results.
• The command MUST NOT modify governed artifact files or rendered documentation.
• If the implementation persists a search index, it MUST store that index under .govctl/ local state and MUST NOT store it under gov/ or the rendered docs directory.
• A persisted search index is derived local state and MUST NOT be treated as an authoritative artifact source. TOML governance artifacts remain the source of truth.
• The command MUST establish index freshness before returning indexed results. If freshness cannot be established, the command MUST rebuild the index, perform an uncached authoritative scan, or return a diagnostic. It MUST NOT silently return stale indexed results.
• Search index synchronization MAY mutate .govctl/ local state. This local-state mutation MUST NOT require the RFC-0004 gov-root exclusive write lock because it does not mutate governed artifacts or rendered documentation.
• Output rows MUST include at least artifact kind, artifact ID, title, source path, and a match snippet or equivalent human-readable context.
• JSON output MUST expose stable result fields including kind, id, title, path, and snippet. It MAY include ranking score and status metadata.
• Plain output MUST emit one artifact ID per line in result order.

Rationale:

Search is discovery across the governance corpus, not a resource-specific CRUD operation. Keeping indexes under .govctl/ preserves the boundary between authoritative governed artifacts and disposable local execution or cache state. Requiring freshness before returning results prevents the local index from becoming a misleading second source of truth.

Since: v0.10.1

[RFC-0002:C-SHOW-PROJECTION] Show Projection Modes (Normative)

For the purposes of this clause, table and plain are human-readable output formats, while json, yaml, and toml are structured output formats. current is the projection used to omit obsolete body content, and archive is the complete historical projection.

RFC, ADR, Work Item, Clause, Guard, and Conformance Case resource commands MUST expose show <id> as a side-effect-free projection operation distinct from get. This distinction is a scoped exception to RFC-0002:C-CRUD-VERBS: get retrieves a field or complete structured resource, while show presents either the current or archival projection defined here.

The show output matrix MUST be:

• show <id> with no --output uses the human-readable table format and the current projection, regardless of whether stdout is a TTY.
• show <id> --history with no --output uses the human-readable table format and the archive projection, regardless of whether stdout is a TTY.
• show <id> --output table and show <id> --output plain use the current projection unless --history selects archive.
• show <id> --output json, --output yaml, or --output toml returns the complete structured resource with a schema equivalent to complete get <id> retrieval.
• Combining --history with --output json, --output yaml, or --output toml MUST be rejected.

This matrix is a scoped exception to RFC-0002:C-OUTPUT-FORMAT for the implicit non-TTY default and for the historical-body completeness of human-readable show. Choosing among structured formats MUST NOT change resource semantics or completeness.

For an RFC whose status is deprecated under RFC-0001:C-RFC-STATUS, the current projection MUST retain its heading, identity, title, version, status, phase, owners, tags, references, and direct replacement metadata when present. It MUST omit the RFC body sections, Clause list and bodies, and changelog. Parent suppression MUST take precedence over the status of nested Clauses.

For an RFC not suppressed by the preceding rule, the current projection MUST fully render the RFC body and every active Clause. A nested Clause whose status is deprecated or superseded under RFC-0001:C-CLAUSE-STATUS MUST retain its heading, generated heading anchor, identity, title, kind, status, since, tags, and direct superseded_by metadata when present. Its Clause text MUST be omitted.

For an ADR whose status is superseded under RFC-0001:C-ADR-STATUS, the current projection MUST retain its heading, identity, title, status, date, tags, references, and direct superseded_by metadata. It MUST omit context, alternatives, decision, and consequences.

For a directly shown Clause whose status is deprecated or superseded, the current projection MUST retain the same metadata required for a suppressed nested Clause. Its Clause text MUST be omitted.

For resources without a deprecated or superseded lifecycle state, including Work Items, Guards, and Conformance Cases, current and archive MUST be content-equivalent. Other lifecycle states MUST remain fully rendered.

The archive projection MUST render all governed resource content supported by the resource’s human-readable renderer without lifecycle-based omission. In particular, it MUST include every RFC section, Clause text, RFC changelog entry, ADR content section and alternative, Work Item content section, Guard field, and Conformance Case field present in the selected resource. Terminal styling and transport-only wrappers MAY differ. render MUST always use the archive projection and MUST NOT suppress deprecated or superseded content.

get, validation, signatures, search, and the authoritative governance artifacts MUST remain unaffected by human-readable projection mode.

Rationale: Agents need a concise default view that does not present obsolete requirements as current, while maintainers and generated documentation need an explicit, lossless path to the complete governance history. An explicit projection boundary preserves both uses without changing stored artifacts or structured automation interfaces.

Since: v0.15.0

[RFC-0002:C-COMPATIBILITY-BOUNDARY] Compatibility Boundary (Normative)

This clause defines the compatibility boundary for the canonical-only breaking release.

CLI boundary:

• The CLI MUST accept only command names, subcommand names, field paths, and mutation flags defined by the current normative RFC clauses.
• The CLI MUST reject compatibility aliases for command names and subcommand names.
• The CLI MUST accept only the field paths defined by RFC-0002:C-EDIT-FIELD-CONTRACT.
• The CLI MUST reject field-path aliases and wire-layout prefixes such as content., govctl., and check..
• The CLI MUST reject resource-specific compatibility flags on the universal edit operation.

Repository boundary:

• Project schema version 3 MUST be the minimum supported project schema version, and the running binary’s current schema version MUST be the maximum supported project schema version.
• Project schema version 4 introduced Conformance Case storage and validation. Normal commands on a version 3 repository containing prospective Case files MUST reject the repository without mutation and instruct the user to run govctl migrate; migration MAY inspect those files under version 4 rules before updating the declared version.
• Project schema version 5 MUST be the current schema version. Version 5 removes source_scan.exclude and establishes the source-selection and ignore contract in RFC-0009. Normal commands on a version 4 repository MUST reject the repository without mutation and instruct the user to run govctl migrate. Migration MUST apply the version 4 to version 5 behavior defined by RFC-0009:C-IGNORE-MIGRATION.
• Any command that loads an existing governance project MUST validate that the declared project schema version is within the supported inclusive range before reading or writing governed artifacts, generated documentation, or .govctl local state.
• A repository whose gov/config.toml declares a schema version below 3 MUST be rejected. The rejection MUST leave gov/, generated documentation, and .govctl unchanged. The diagnostic MUST instruct the user to migrate the repository with a compatible earlier govctl version before upgrading.
• A repository whose gov/config.toml declares a schema version newer than the running binary’s current schema version MUST be rejected without mutation. The diagnostic MUST instruct the user to upgrade govctl to a version that supports the repository schema.
• If gov/config.toml is absent while gov/ contains governance project state, the project schema cannot be established and normal project commands MUST reject the repository without mutation. The diagnostic MUST identify the missing configuration. A new project with no existing governance state MAY still be initialized.
• RFC and Clause artifacts MUST use the structured TOML wire layout defined by their current schemas. The former flat RFC and Clause TOML layouts MUST be rejected.
• RFC, Clause, ADR, Work Item, Guard, and Conformance Case TOML files MUST NOT contain the legacy [govctl].schema field.
• Work Item TOML containing content.journal MUST be rejected.
• Loading or rewriting a loop round TOML file containing max_rounds MUST be rejected.
• Project schema version 3 establishes the content-signature interpretation for stored RFC signatures. RFC signatures stored for project schema version 3 or later MUST use the content-signature contract in RFC-0000:C-PHASE-LIFECYCLE. Repositories below version 3 MUST be migrated with a compatible earlier govctl version before the current binary loads their RFC baselines. The current binary MUST NOT infer a pre-version-3 signature algorithm from an untagged hash value.

Migration and safety:

• govctl migrate MUST support migration from project schema version 3 to each later schema version supported by the running binary.
• govctl migrate MUST reject project schema versions below 3 without mutation. Its diagnostic MUST direct the user to a compatible earlier govctl version.
• JSON RFC files matching gov/rfc/RFC-NNNN/rfc.json MUST produce an unsupported-storage diagnostic that identifies the path.
• JSON Clause files matching gov/rfc/RFC-NNNN/clauses/C-NAME.json MUST produce an unsupported-storage diagnostic that identifies the path.
• Project loading and validation MUST perform those JSON checks before reporting success. Recognized legacy JSON files MUST NOT be silently ignored.
• Historical RFCs, Clauses, ADRs, Work Items, release records, and released changelog content that conform to the supported schemas MUST remain authoritative history.
• Lifecycle status alone MUST NOT make a conforming historical artifact unsupported.

Rationale:

A single explicit boundary is smaller and more predictable than indefinitely carrying transitional parsers and CLI grammars. Requiring an earlier compatible binary for pre-baseline repositories preserves an upgrade path without making every future release understand every historical representation. Explicit unsupported-storage diagnostics prevent apparent success when governed data would otherwise be skipped.

Since: v1.0.0

[RFC-0002:C-EDIT-FIELD-CONTRACT] Canonical Edit Field Contract (Normative)

This clause defines the complete canonical mutation-path contract for govctl <resource> edit. A path not listed here MUST be rejected. Lifecycle-owned fields remain mutable only through the lifecycle verbs in RFC-0002:C-LIFECYCLE-VERBS.

Each resource MUST support these paths and operations:

Every listed list path whose items are scalar values also defines an indexed <list-path>[i] path supporting --set and --remove. Indexed scalar replacement MUST replace exactly one item in place, preserve the list length and item position, and apply before persistence the same value and reference validation as --add on the owning list. Structured list items MUST NOT inherit direct --set unless the indexed item path is explicitly listed above; their listed child paths remain the scalar replacement surface.

Acceptance-criterion category input MUST recognize these ASCII case-insensitive prefix tokens when the trimmed token precedes the first colon:

• add, added, feat, and feature map to added;
• change, changed, refactor, and perf map to changed;
• deprecate and deprecated map to deprecated;
• remove and removed map to removed;
• fix and fixed map to fixed;
• security and sec map to security; and
• chore, internal, test, tests, doc, docs, ci, and build map to chore.

The text following a recognized prefix MUST be trimmed and non-empty. acceptance_criteria --add MUST require a recognized prefix and reject an absent or unrecognized prefix.

For Work Item acceptance_criteria[i], --set <value> MUST update the existing criterion without changing its status. If <value> begins with a recognized acceptance-criterion category prefix, the operation MUST update both the criterion text and category using the mapping above. Otherwise, it MUST treat the complete trimmed value as criterion text and preserve the existing category. The direct acceptance_criteria[i].text path MUST treat its value as literal text and preserve both status and category. An empty resulting text MUST be rejected.

For Conformance Case requirements, --remove MUST select either one exact <CLAUSE-ID>@<VERSION> value or one indexed path. --regex and --all MUST be rejected for this object-valued, non-empty list.

List selection MUST use only these canonical forms:

govctl <resource> edit <id> <scalar-list-path>[<index>] --set <value>
govctl work edit <id> acceptance_criteria[<index>] --set <value>
govctl <resource> edit <id> <list-path>[<index>] --remove
govctl <resource> edit <id> <list-path> --remove <exact-value>
govctl <resource> edit <id> <list-path> --remove <pattern> --regex
govctl <resource> edit <id> <list-path> --remove --all
govctl <resource> edit <id> <checklist-path>[<index>] --tick <status>

Indices MUST be zero-based decimal integers. --remove <value> MUST use exact matching unless --regex is present. --all MUST NOT be combined with a value, indexed path, or --regex. --tick MUST require an indexed path and a lifecycle value permitted for that checklist type. Selector flags such as --at and --exact MUST be rejected because the canonical path and exact-value form already express those selections.

RFC changelog paths address only the current version record. Released historical changelog records MUST NOT be editable through this surface.

The logical Guard paths command, timeout_secs, and pattern map to persisted check configuration without exposing the wire-layout name. Work Item waiver creation remains owned by the verification waiver command; edit only corrects or removes an existing waiver.

Rationale:

A closed list gives scripts and agents one discoverable interface and makes removal of aliases testable. Uniform indexed replacement gives scalar lists one predictable correction operation. Acceptance criteria expose a concise item-level text update while retaining explicit child paths for precise field edits. Logical paths keep the command contract independent of TOML table layout while lifecycle and verification commands retain ownership of constrained transitions.

Since: v1.0.0

[RFC-0002:C-NAMESPACE-RECOVERY] Misrouted resource command recovery (Normative)

Governed artifact resources are first-class CLI namespaces even when their storage or identifiers express ownership by another resource.

An invocation under the rfc namespace MUST fail with a non-zero exit when an argument in the command’s canonical RFC-ID position is a Clause reference (RFC-NNNN:C-NAME). The rejected invocation MUST leave governed artifacts and local state unchanged. For the shared get, show, and edit verbs, the diagnostic MUST show the corresponding govctl clause command when replacing only the resource token rfc with clause produces a syntactically valid Clause invocation with every remaining argument and flag unchanged. For any other RFC verb, or when the token-preserving replacement is not a valid Clause invocation, the diagnostic MUST identify the reference as a Clause and the expected govctl clause namespace without synthesizing a complete command.

The exact nested form govctl rfc clause ... MUST remain invalid and fail with a non-zero exit. It MUST leave governed artifacts and local state unchanged. Its diagnostic MUST direct the user to the command formed by removing the rfc token: govctl clause ....

When govctl rfc edit <RFC-ID> <path> ... rejects an unknown path whose first logical segment is clause or clauses, its diagnostic MUST identify Clause content as belonging to the govctl clause edit <RFC-ID:C-NAME> ... namespace. Because that form does not identify a Clause, the diagnostic MUST NOT invent a Clause ID or claim a complete replacement command.

Recovery guidance MUST NOT make an invalid invocation an alias, rewrite it into an executable command, or otherwise cause the requested operation to succeed.

Rationale: Deterministic guidance lets agents recover from the storage-derived assumption that Clauses are RFC subcommands while preserving one accepted resource-first grammar. Restricting exact replacements to token-preserving namespace changes avoids guessing user intent.

Since: v1.0.1

[RFC-0002:C-PRE-1-RELEASE-TARGET-COMPATIBILITY] Pre-1.0 Release Target Compatibility (Normative)

For govctl release versions at or after 0.17.0 whose SemVer major component is zero, the canonical prebuilt-binary target set is:

• x86_64-unknown-linux-musl
• aarch64-unknown-linux-musl
• x86_64-apple-darwin
• aarch64-apple-darwin
• x86_64-pc-windows-gnu
• aarch64-pc-windows-gnullvm

Every release in that scope MUST also publish compatibility alias archives with these mappings:

• x86_64-unknown-linux-gnu -> x86_64-unknown-linux-musl
• aarch64-unknown-linux-gnu -> aarch64-unknown-linux-musl
• x86_64-pc-windows-msvc -> x86_64-pc-windows-gnu
• aarch64-pc-windows-msvc -> aarch64-pc-windows-gnullvm

{version} below denotes the complete SemVer release version without a leading v; the v shown in each template is literal. For every canonical or alias target identifier listed by this Clause, release archives MUST use this layout:

• Linux and macOS targets: asset filename govctl-v{version}-{target}.tar.gz, gzip-compressed tar format, one root directory named govctl-v{version}-{target}, and executable path govctl-v{version}-{target}/govctl.
• Windows targets: asset filename govctl-v{version}-{target}.zip, ZIP format, one root directory named govctl-v{version}-{target}, and executable path govctl-v{version}-{target}/govctl.exe.

For each compatibility mapping, the executable bytes at the alias executable path MUST equal the executable bytes at the mapped canonical executable path for the same release version.

The alias set applies to every release in this pre-1.0 transition window so legacy-target self-update clients and package installers can cross the target transition even when versions are skipped.

A release version whose SemVer major component is one or greater, including a prerelease such as 1.0.0-rc.1, MUST NOT publish the four compatibility alias target archives defined by this Clause. A pre-1.0 installation that has not crossed the target transition before that breaking boundary may require reinstallation through another distribution channel.

Since: v3.1.0

3. Global Commands

[RFC-0002:C-DESCRIBE-COMMAND] Agent Introspection Contract (Normative)

govctl describe provides read-only, machine-readable discovery for the running CLI.

Syntax

govctl describe [--context]

The command MUST emit JSON and MUST NOT mutate project or local execution state. Without --context, it MUST succeed without an initialized governance project.

Schema v1

The top-level object MUST contain:

• schema_version: the integer 1
• tool_version: the running binary semantic version as a string
• purpose: a string
• commands: an array of command nodes
• workflow: an object containing only phase_order

Without --context, project_state and suggested_actions MUST be absent. With --context, both fields MUST be present.

A command node MUST contain name, summary, and usage strings plus a subcommands array of command nodes. The command catalog MUST represent every top-level command and nested command defined by the accepted CLI grammar. Generic help dispatch MUST be omitted. commands and every subcommands array MUST be sorted lexicographically by name. usage MUST contain the canonical invocation without a leading Usage: label. Command nodes MUST NOT contain examples, prerequisites, workflow policy, or when_to_use guidance.

workflow.phase_order MUST equal ["spec", "impl", "test", "stable"] and MUST NOT prescribe a task sequence.

With --context, project_state MUST contain counts, rfcs, adrs, work_items, and loops.

counts MUST contain these objects and integer fields, including zero-valued fields:

• rfcs: total, draft, normative, deprecated, spec, impl, test, and stable
• adrs: total, proposed, accepted, rejected, and superseded
• work_items: total, queue, active, done, and cancelled
• loops: total, pending, active, paused, completed, and failed

RFC status and phase counts MUST cover every RFC according to RFC-0001:C-RFC-STATUS and RFC-0001:C-RFC-PHASE. ADR, Work Item, and loop counts MUST cover every corresponding record according to RFC-0001:C-ADR-STATUS, RFC-0001:C-WORK-STATUS, and RFC-0006:C-LOOP-LIFECYCLE.

rfcs MUST enumerate only draft RFCs and normative RFCs whose phase is not stable. Each RFC record MUST contain id, title, status, and phase strings.

adrs MUST enumerate only proposed ADRs. Each ADR record MUST contain id, title, and status strings.

work_items MUST enumerate only Work Items in queue or active. Each Work Item record MUST contain id, title, and status strings.

loops MUST enumerate only loops in pending, active, or paused. Each loop record MUST contain id, state, and next_action strings plus a work array of Work Item ID strings. If valid loop state omits next_action as permitted by RFC-0006:C-LOOP-STATE-STORAGE, the record MUST report "start". The work array MUST preserve the stored loop.work order.

Each context record array MUST be sorted lexicographically by id. Terminal records MUST affect counts but MUST NOT be enumerated. Context output MUST NOT contain artifact body text, changelogs, acceptance criteria, notes, loop round records, or other historical content.

suggested_actions MUST be an array of canonical read-only command strings. It MUST contain one discovery command for each enumerated record, ordered by RFCs, ADRs, Work Items, then loops, preserving each record array’s order:

• RFC: govctl rfc show <id>
• ADR: govctl adr show <id>
• Work Item: govctl work show <id>
• loop: govctl loop resume <id>

A suggested action indicates only how to inspect current state. It MUST NOT assert that a lifecycle gate passes or recommend a mutating transition.

If requested context cannot be loaded completely, describe --context MUST exit non-zero, MUST emit no JSON or partial context to stdout, and MUST report diagnostics to stderr.

Compatibility

schema_version MUST increase for a backward-incompatible output change. Removing or renaming a field, changing a field’s type or meaning, making an optional field required, or changing required ordering is backward-incompatible. A backward-incompatible schema change also requires a major govctl version bump. Additive optional fields MAY retain the current schema version. Consumers SHOULD ignore unknown fields.

Rationale

A small versioned command map lets agents discover the running binary without loading a duplicate workflow manual. Counts retain project-scale awareness, while non-terminal records and read-only inspection commands keep context proportional to current work rather than repository history.

Since: v2.0.0

[RFC-0002:C-AGENT-INTEGRATION] Agent Integration Management (Normative)

govctl agent manages the user-scoped govctl agent integration independently of project governance state.

Syntax

govctl agent doctor <codex|claude|all>
govctl agent install <codex|claude|all>
govctl agent update <codex|claude|all>
govctl agent hook <session-start|pre-tool-use>

The runtime selector is required for doctor, install, and update; all selects Codex and Claude. hook is an internal adapter entry point used by bundled runtime manifests. It takes no runtime selector, consumes the native event payload as JSON on standard input, and emits the applicable non-blocking hook response as JSON on standard output. It MUST remain hidden from user-facing command discovery.

Shared behavior

• These commands MUST work without an initialized govctl project.
• doctor MUST be read-only. It MUST verify that every selected runtime exposes the native plugin operations required by install and update, and it MUST exit non-zero when any selected runtime is unavailable or incompatible.
• install and update MUST use plugin assets bundled with the running govctl version. They MUST materialize those assets at a persistent user-scoped support path before registering that path as a native marketplace source.
• The materialized plugin version MUST equal the running govctl version.
• install MUST preserve an existing Codex reviewer-role file rather than replacing it.
• update MUST replace the govctl reviewer-role files for Codex with the bundled projection.
• When all is selected, request validation and native-operation preflight MUST complete for both runtimes before the first native mutation. The command MUST exit non-zero unless every selected runtime succeeds, and failure output MUST identify completed, failed, and skipped runtime work without claiming cross-runtime atomicity.
• With global --dry-run, install and update MUST perform target resolution and readiness checks, report planned persistent writes and native operations, and leave persistent state unchanged.
• Successful install and update MUST tell the user that a new agent session is required before refreshed integration is available.

Client projections

• Claude MUST receive the bundled skills, Claude Markdown reviewer agents, and hooks through its native plugin mechanism.
• Codex MUST receive the bundled common skills and hooks through its native plugin mechanism.
• Codex reviewer agents MUST be installed separately as standalone TOML files in the selected user’s Codex agent directory. Every generated role MUST contain name, description, and developer_instructions, and review-only roles MUST select a read-only sandbox mode.
• The bundled plugin MUST select a runtime-specific hook manifest for each client. Shared governance behavior MUST be adapted to the client’s supported event fields and output protocol rather than relying on one shared hook document.

Bundled hook behavior

• On SessionStart, the hook adapter MUST resolve the event working directory with the same upward project-discovery semantics as other govctl commands.
• If no governed project is found, SessionStart MUST succeed without model-visible output. If governance state is found but cannot be loaded, it MUST provide concise, non-blocking recovery context. For a valid governed project, it MUST provide bounded, actionable context about current active Work Items and non-terminal loops without running project-wide validation.
• Before a direct file-edit tool changes lifecycle-managed RFC, Clause, ADR, Work Item, Guard, Conformance Case, or release artifacts, PreToolUse MUST provide non-blocking guidance to prefer a canonical govctl command when that command can express the change. The hook MUST allow the tool call to proceed, MUST acknowledge direct editing as the recovery path for unsupported operations, and MUST recommend govctl check after such an edit.
• Bundled hooks MUST NOT run project-wide validation on Stop or after every file edit. Hook advice is a recoverability aid and MUST NOT be treated as an enforcement boundary.

The existing govctl init-skills command remains the project-local and custom-directory projection path. Agent plugin management MUST NOT change its overwrite or destination semantics.

Since: v3.2.0

Changelog

v3.6.0 (2026-08-02)

Make acceptance-criterion text correction ergonomic

Added

• Define item-level acceptance-criterion replacement with category-prefix parsing

v3.5.0 (2026-07-31)

Define the internal agent hook adapter command contract

Added

• Specify hook event syntax, JSON invocation, and the runtime-selector exception

v3.4.0 (2026-07-31)

Adapt bundled hooks to Claude and Codex runtimes

Changed

• Define runtime-specific hook manifests and shared governance semantics
• Replace per-turn validation with governed-project context and advisory edit guidance

v3.3.0 (2026-07-31)

Clarify native agent plugin projections

Added

• Require Codex hooks to load through its native plugin

v3.2.0 (2026-07-31)

Add native agent integration management

Added

• Define agent doctor, install, and update commands

v3.1.0 (2026-07-30)

Define pre-1.0 release target compatibility

Added

• Define canonical prebuilt targets and compatibility aliases through 0.x

Removed

• End legacy target alias publication at 1.0.0

v3.0.3 (2026-07-30)

Clarify rollback target boundary

Fixed

• Separate target restoration from best-effort temporary-state cleanup

v3.0.2 (2026-07-30)

Narrow recovery boundary to rollback failure

Fixed

• Keep temporary transaction cleanup best-effort without redefining migration results

v3.0.1 (2026-07-30)

Define migration recovery failure boundary

Fixed

• Preserve recovery backups and report E0903 when rollback or cleanup fails

v3.0.0 (2026-07-30)

Adopt schema v5 source scan ignore semantics

Changed

• Define schema v5 as the current repository format

Removed

• Replace source_scan.exclude with gitignore-compatible .govignore rules

v2.2.0 (2026-07-29)

Define uniform indexed replacement for scalar-valued lists

Added

• Define in-place indexed replacement for canonical scalar-list paths

Fixed

• Require replacement values to pass owning-list validation before persistence

v2.1.0 (2026-07-27)

Integrate Conformance Cases into the resource model

Added

• Define the Conformance Case resource and canonical CRUD surface

Changed

• Extend validation, search, tag, output, and migration contracts

v2.0.0 (2026-07-26)

Define reliable agent introspection

Changed

• Derive describe command metadata from the compiled CLI and limit context to actionable state

v1.1.0 (2026-07-26)

Define universal dry-run preflight semantics

Changed

• Require dry-runs to preserve execution validation and target selection

v1.0.4 (2026-07-26)

Restore schema boundary formatting

Fixed

• Render repository schema rules as separate requirements

v1.0.3 (2026-07-26)

Close repository schema validation gaps

Fixed

• Reject future schemas and existing projects with missing configuration

v1.0.2 (2026-07-26)

Clarify schema-3 RFC signature semantics

Changed

• Define schema version 3 as the content-signature interpretation boundary

v1.0.1 (2026-07-25)

Guide misrouted Clause commands to the canonical namespace

Changed

• Define deterministic recovery diagnostics for Clause commands sent through the RFC namespace

v1.0.0 (2026-07-25)

Adopt the canonical-only compatibility boundary

Changed

• Define the complete canonical edit path and selector contract
• Diagnose recognized unsupported legacy storage before project operations succeed

Removed

• Remove sibling mutation verbs, command aliases, field aliases, wire-layout paths, and resource-specific edit flags
• End migration support for project schemas below version 3 and remove legacy storage readers

v0.15.0 (2026-07-21)

Define current and archival show projections

Added

• Define current-context show output, explicit history access, and complete structured serialization

v0.14.0 (2026-07-20)

Align lifecycle commands with sealed RFC versions

Changed

• Enforce candidate bump and signature baseline rules
• Permit deletion of unreferenced current-candidate Clauses

v0.13.2 (2026-07-16)

Clarify lifecycle rollback restoration state

Changed

• Define rollback over target path existence and byte content

v0.13.1 (2026-07-16)

Reject version-changing bumps for non-normative RFCs

Fixed

• Restrict version-changing RFC bump to normative status

v0.13.0 (2026-07-16)

Specify current-version changelog editing and RFC sealing

Added

• Defined current changelog access and in-version spec authoring lifecycle operations

v0.12.1 (2026-07-15)

Restore stable release creation syntax

Fixed

• Preserve govctl release alongside release undo

v0.12.0 (2026-07-15)

Make release commands consistently resource-first

Added

• Add guarded release undo

Changed

• Replace the legacy no-verb release syntax with release cut
• Exclude release records from universal CRUD verbs

v0.11.1 (2026-07-15)

Align RFC lifecycle verb definitions

Changed

• Separate RFC finalization from deprecation in the lifecycle command contract

v0.11.0 (2026-07-15)

Align lifecycle command semantics

Changed

• Align lifecycle verbs with version-scoped phases and pre-release Work Item reopening

v0.10.4 (2026-06-28)

Clarify lifecycle failure atomicity boundary

Changed

• define byte-for-byte restoration for normally returned lifecycle errors and explicit rollback-failure boundaries

v0.10.3 (2026-06-15)

Reject empty RFC version bumps

Fixed

• reject RFC version bumps without RFC or clause content changes

v0.10.2 (2026-06-08)

Clarify init-skills skill bundle installation

Changed

• init-skills installs full skill bundles rooted at SKILL.md, including bundled references/assets/scripts

v0.10.1 (2026-06-04)

Set search clause version metadata

Fixed

• C-SEARCH-COMMAND has derived since version metadata

v0.10.0 (2026-06-04)

Add search command contract

Added

• C-SEARCH-COMMAND clause for govctl search

v0.9.4 (2026-06-04)

Narrow project support diagnostics

Changed

• project-support diagnostics are scoped to govctl-managed local-state .gitignore entries

v0.9.3 (2026-06-04)

Clarify edit path addressing

Changed

• edit operations use deterministic path-based addressing for arrays and nested fields

v0.9.2 (2026-06-04)

Clarify project support file sync

Changed

• govctl check and migrate cover project support file freshness

v0.9.1 (2026-06-04)

Require check to surface stale bundled schemas

Changed

• govctl check reports missing or stale bundled schema files and instructs users to run govctl migrate

v0.9.0 (2026-06-04)

Remove legacy JSON migration support

Removed

• govctl migrate no longer converts legacy RFC or clause JSON storage in v0.9 and later

v0.8.0 (2026-04-13)

Add self-update global command (ADR-0041)

Added

• C-SELF-UPDATE clause for govctl self-update command

Changed

• C-GLOBAL-COMMANDS updated with entry 11 and rationale for self-update

v0.7.0 (2026-04-09)

Add controlled-vocabulary tags: tags field on RFC/clause/ADR/work/guard, –tag filter on list, govctl tag new/delete/list for registry management (ADR-0040)

v0.6.1 (2026-04-08)

Add –dir flag to init-skills for one-step directory override without config editing

v0.6.0 (2026-04-08)

Add –format flag to init-skills for cross-platform agent format support (claude/codex)

v0.5.0 (2026-03-27)

Add guard as a resource type with CRUD verbs

Added

• Added guard to C-RESOURCES as resource type 5 (renumbered release to 6)
• Updated C-CRUD-VERBS with guard-specific verb applicability
• Updated C-RESOURCE-MODEL to include guard in resource list

v0.4.0 (2026-03-17)

Add init-skills command, update init and migrate per ADR-0035

Added

• init-skills global command for explicit agent asset installation

Changed

• init no longer installs skills/agents
• migrate now ensures schema JSON files are up to date

v0.3.0 (2026-03-17)

Add project-level verification command and config semantics

Added

• Added global verify command and verification config contract

v0.2.0 (2026-01-19)

Incorporate review feedback: add deletion safety constraints, field name stability, output format defaults, describe schema versioning, and editorial clarifications

Added

• Added deletion safety constraints requiring draft RFCs and reference checks
• Added field name stability guarantee for get command
• Specified json as default output format for non-TTY
• Added status command exception to output format requirements
• Added describe command schema versioning contract
• Clarified clause namespace vs filesystem storage independence
• Added case-sensitivity and timestamp format requirements

v0.1.0 (2026-01-19)

Initial draft

RFC-0003: TUI UX improvements

Version: 0.1.0 | Status: normative | Phase: stable Owners: @govctl-org Tags: tui

1. Summary

[RFC-0003:C-SUM] Summary (Informative)

• Define a consistent TUI navigation frame with shared header and footer.
• Add list filtering and quick-jump for faster browsing.
• Improve detail view readability with consistent layout and scroll position.

Tags: tui

Since: v0.1.0

2. Specification

[RFC-0003:C-NAV] Shared header/footer navigation (Normative)

• The TUI MUST render a persistent header and footer across all views.
• The header MUST show the current view hierarchy (breadcrumb) and basic counts for the active view.
• The footer MUST provide the current keymap for primary navigation, including quit and back.
• Existing navigation keys MUST remain functional.

Tags: tui

Since: v0.1.0

[RFC-0003:C-FILTER] List filtering and quick-jump (Normative)

• List views MUST support an inline filter mode that matches ID, title, or status.
• Filter mode MUST be entered with a single key and exited without leaving the list view.
• When a filter is active, the list MUST show only matching items and navigation MUST operate over the filtered set.
• List views MUST support quick-jump to top and bottom and allow stepping through matches.

Tags: tui

Since: v0.1.0

[RFC-0003:C-DETAIL] Detail view readability (Normative)

• Detail views MUST present metadata and content sections consistently across artifact types.
• Detail views MUST show scroll position to indicate where the user is within the content.
• Scrolling MUST not lose the current view context or selection.

Tags: tui

Since: v0.1.0

Changelog

v0.1.0 (2026-02-07)

Initial draft

RFC-0004: Concurrent write safety for governance artifacts

Version: 0.1.1 | Status: normative | Phase: stable Owners: @govctl-org Tags: safety

1. Summary

[RFC-0004:C-SUMMARY] Summary (Informative)

This RFC specifies that govctl MUST preserve integrity of governance artifacts when multiple processes invoke write operations concurrently (e.g. agent-triggered parallel tasks creating or editing RFCs, ADRs, or work items).

Scope: Applies to any command that modifies files under the gov root or writes rendered output under the docs root. The concrete mechanism to satisfy this requirement is an implementation detail.

Backward compatibility: Existing command invocations and arguments remain valid. This RFC adds only coordination and failure behaviour; it does not change command semantics.

Specification outline: The RFC defines terms (write command, read-only command, concurrent invocations, corrupted file); requires that every write command participate in a single global concurrency mechanism and that read-only commands never block on it; requires that concurrent writes never produce corrupted files, duplicate work item IDs, or lost read-modify-write updates; and requires predictable failure behaviour (bounded wait, then either proceed or fail with an actionable error) when the mechanism cannot be acquired.

Rationale: Concurrent writes without coordination cause file corruption, duplicate IDs, and lost updates. Agents and scripts often run multiple govctl invocations in parallel; the implementation must prevent observable corruption and provide clear behaviour on conflict.

Tags: safety

Since: v0.1.0

2. Specification

[RFC-0004:C-CONCURRENT-WRITE] Concurrent write safety (Normative)

Commands that modify the governance tree or rendered output MUST use a concurrency mechanism such that:

1. No two concurrent invocations (across processes) produce corrupted artifact files. Corrupted means: invalid JSON/TOML, truncated content, or interleaved content from different writes.
2. Work item creation MUST NOT assign the same ID to two items created by concurrent invocations when both use the same ID prefix (e.g. same date under sequential or author-hash strategy). The scenario is same repository, concurrent processes (distinct from branch-merge ID collision).
3. Read-modify-write operations (e.g. edit, set, bump) MUST NOT lose updates from another concurrent invocation modifying the same artifact.

This RFC requires the observable behaviour: artifact integrity and no duplicate IDs under concurrent write load. The concrete mechanism (e.g. process-level filesystem locking) is an implementation detail.

Rationale: Agents and CI may run multiple govctl write commands in parallel. Without a defined concurrency strategy, races are observable in practice (file corruption, duplicate WI IDs). The normative requirement ensures implementors address this.

Tags: safety

Since: v0.1.0

[RFC-0004:C-DEFINITIONS] Definitions (Informative)

Write command: A govctl invocation that may create, modify, or delete files under the gov root, or write files under the docs root (e.g. render output). Any invocation that writes files under the docs root is a write command regardless of command name. Examples: rfc new, adr new, work new, clause new, guard new, rfc edit, adr edit, work edit, clause edit, guard edit, rfc bump, rfc finalize, rfc advance, adr accept, work move, render.

Read-only command: A govctl invocation that does not modify gov or docs. Examples: rfc list, adr list, work list, clause list, guard list, rfc get, adr get, work get, clause get, guard get, check, status. The commands show and describe are read-only when they do not write to gov or docs (e.g. when they output only to stdout).

Concurrent invocations: Two or more govctl processes running at the same time, such that their execution may overlap (e.g. multiple agent tasks, or a script spawning parallel govctl calls).

Corrupted artifact file: A file under gov or docs that does not conform to the expected schema (invalid JSON or TOML), or that contains truncated or interleaved content from more than one logical write.

Rationale: These definitions make the scope and guarantees of this RFC testable and unambiguous.

Tags: safety

Since: v0.1.0

[RFC-0004:C-FAILURE-BEHAVIOUR] Behaviour when concurrency mechanism is unavailable (Normative)

When a write command cannot obtain exclusive access (e.g. because another write command is in progress), the implementation MUST either wait for a bounded time and then proceed, or wait for a bounded time and then fail. The maximum wait time is implementation-defined and MUST be documented. Implementations SHOULD use a default maximum wait of at least 30 seconds for interoperability and testability. The maximum wait time MAY be configurable.

If the implementation chooses to fail after waiting, it MUST exit with a non-zero status and MUST emit an actionable error message that indicates that another govctl write is in progress and that the user or agent should retry later. The message MUST NOT assume a specific concurrency mechanism (e.g. must not require the word “lock”).

If the implementation waits until access is granted, it MUST eventually proceed; it MUST NOT deadlock.

Implementations SHOULD ensure that exclusive access is released on process exit or that time-based expiry or stale-lock cleanup applies, so that a crashed process does not block writers indefinitely.

Rationale: Predictable failure behaviour allows agents and scripts to retry or serialise writes; clear errors avoid confusion. A documented, implementation-defined bound makes conformance testable; the 30-second SHOULD gives implementations and tests a shared expectation. The stale-lock note supports the “MUST NOT deadlock” requirement when a holder crashes.

Tags: safety

Since: v0.1.0

[RFC-0004:C-SCOPE] Scope of write commands (Normative)

Every write command MUST participate in the concurrency mechanism before performing any mutation of the gov tree or docs output. Participation means acquiring exclusive access (or equivalent) for the duration of the write operations performed by that invocation.

Read-only commands MUST NOT acquire exclusive access and MUST NOT block on the concurrency mechanism. They MAY run concurrently with each other and with at most one write command.

The concurrency mechanism SHALL apply to the entire gov root (and, when a command writes rendered output, to the docs root) as a single unit. Exclusive access MUST NOT be held by more than one write command at the same time.

Rationale: Defining scope ensures that all mutation paths are covered and that read-only usage is never blocked by writers.

Tags: safety

Since: v0.1.0

Changelog

v0.1.1 (2026-07-26)

Refresh command examples for the canonical edit surface

Fixed

• Replace removed mutation command examples with canonical commands

v0.1.0 (2026-02-15)

Initial draft

RFC-0006: Loop Execution Model

Version: 1.0.0 | Status: normative | Phase: stable Owners: @govctl-org

1. Summary

[RFC-0006:C-SUMMARY] Summary (Informative)

This RFC defines the loop execution model for coordinating local agent execution rounds around one or more Work Items.

A loop is a first-class local execution concept that tracks one or more Work Items through dependency-aware rounds of implementation, verification evidence collection, and refinement. Loops support:

• Single Work Item execution context: Create resumable local round state for one Work Item
• Multi-Work Item batch execution context: Coordinate several Work Items with dependency resolution and deterministic readiness ordering
• Failure and blocker propagation: Represent failed, blocked, or cancelled loop-level outcomes without adding new Work Item lifecycle states
• Resumption: Resume interrupted execution from loop state and round artifacts

The loop model maintains clear separation between:

• Work Items: Durable outcome artifacts that contain scope (description), success criteria (acceptance_criteria), durable memory (notes), references, dependencies, and verification policy
• Loop state: Local execution state that tracks rounds, selected work, summary evidence, blockers, and next action

This separation ensures Work Items remain clean outcome artifacts while enabling rich local execution traceability for debugging and resumption.

Loops interact with Work Item lifecycle exclusively through existing govctl work semantics. govctl loop run advances local round state; it does not implement code, tick acceptance criteria, add notes, or mark Work Items done on behalf of the agent.

Tags: core

Since: v0.1.0

2. Specification

[RFC-0006:C-LOOP-DEFINITION] Loop Definition (Normative)

A loop is a local execution session that coordinates one or more Work Items through iterative rounds of agent implementation, verification evidence collection, and refinement.

Each loop MUST:

1. Be initialized from an explicit, finite root set of Work Items
2. Resolve the transitive dependency closure before execution begins
3. Recompute the transitive dependency closure after any successful scope mutation defined by RFC-0006:C-LOOP-SCOPE-MUTATION
4. Track execution state independently of Work Item files
5. Store transient round evidence in loop-local artifacts rather than Work Item fields
6. Terminate when all Work Items in the current resolved loop set reach terminal loop-level outcomes or a failure condition is met

A loop MAY support explicit scope mutation after start. A scope mutation MUST be requested through loop commands; implementations MUST NOT treat unrelated Work Item file edits as implicit loop scope changes.

A loop MUST NOT:

1. Modify Work Item files directly except by invoking existing govctl work command semantics where explicitly required
2. Persist execution trace to Work Item fields; execution trace belongs in loop state and round artifacts
3. Assume a specific implementation order (sequential or parallel) beyond dependency readiness
4. Introduce parallel replacements for Work Item notes, depends_on, acceptance criteria, or verification guards

Rationale: Loops are a first-class execution concept that coordinates Work Item completion without becoming a second Work Item model. By keeping loops separate from Work Item files, govctl preserves the boundary between local execution trace (ephemeral) and governance artifacts (durable). Work Item notes hold durable constraints and learnings that should survive future work; loop state holds transient execution evidence. Explicit scope mutation lets long cleanup loops adapt without replacing the execution session identity.

Tags: core

Since: v0.1.0

[RFC-0006:C-LOOP-LIFECYCLE] Loop Lifecycle (Normative)

A loop MUST have exactly one of the following lifecycle states:

1. pending — Initial state. The loop is defined but execution has not started.
2. active — The loop is currently executing rounds on work items.
3. paused — Execution stopped before a terminal outcome and may be resumed.
4. completed — All work items in the resolved loop set reached non-failed terminal loop outcomes (done or cancelled) without any failed or blocked loop outcomes.
5. failed — An unrecoverable failure condition was met, such as a critical local-state error, an explicit failed work item, or a blocked dependency chain.

Valid transitions:

• pending → active (loop execution begins)
• active → paused (loop pauses for resumption)
• paused → active (loop execution resumes)
• active → completed (all work items finish without failed or blocked outcomes)
• active → failed (failure condition met)
• paused → failed (resumption detects unrecoverable state)

Invalid transitions (MUST be rejected):

• completed → any (terminal state)
• failed → any (terminal state)
• pending → completed (cannot complete without being active)
• pending → failed (cannot fail without being active)
• paused → completed (completion requires active execution)

Round count is audit metadata. Implementations MUST NOT infer loop failure, Work Item failure, or dependency blockage from round count alone.

Rationale: The loop lifecycle provides clear semantics for tracking execution progress and enables resumption after interruption. A distinct paused state avoids overloading pending, which means execution has not started. Terminal states (completed, failed) indicate the loop has finished and cannot be restarted. Keeping round count out of failure semantics preserves the separation between govctl’s local round protocol and caller-level retry policy.

Tags: lifecycle, core

Since: v0.1.0

[RFC-0006:C-DEPENDENCY-SEMANTICS] Work Item Dependency Semantics (Normative)

Work items MAY declare dependencies on other work items using the depends_on field in the [govctl] section. The depends_on field MUST contain a list of work item IDs.

The depends_on field is an optional Work Item metadata field for repositories implementing this RFC. Implementations that validate Work Items against a JSON Schema MUST include govctl.depends_on as an optional array of Work Item IDs in that schema.

At loop start, and after every scope mutation, the loop MUST resolve the dependency closure for the current explicit root set. The resolved loop set MUST include every transitive depends_on dependency needed by the current root set. If any dependency ID does not identify an existing Work Item, the loop start or scope mutation MUST be rejected before the new state becomes authoritative.

Dependency rules:

1. Acyclicity: The dependency graph MUST be acyclic. Implementations MUST detect cycles at loop start and after scope mutation and reject the operation before the new state becomes authoritative. The diagnostic MUST include at least one Work Item ID from the detected cycle.

2. Selection readiness: A work item MUST NOT be selected for new round work until every dependency has a terminal loop-level outcome.

3. Outcome checking: After a dependency reaches a terminal loop-level outcome, the loop MUST check that outcome:

   • If all dependencies are done: the dependent work item MAY be selected for round work
   • If any dependency is cancelled, failed, or blocked: the dependent work item MUST be marked as blocked in loop state and MUST NOT be selected

4. Distinction from refs: The depends_on field is distinct from refs:

   • refs: informational cross-references to related artifacts (RFCs, ADRs, work items)
   • depends_on: blocking execution dependencies (work items only)

5. Failure propagation: When a work item is marked as blocked, all work items that depend on it (directly or transitively) MUST also be marked as blocked.

Loop-level status tracking: The blocked, failed, and cancelled states are loop-level execution statuses tracked in loop state, not additional Work Item status field values. Work Items maintain their own lifecycle states (queue, active, done, cancelled) per RFC-0001:C-WORK-STATUS. A Work Item with Work Item status cancelled MUST be represented as cancelled in loop state when it is part of the resolved loop set.

Rationale: Dependencies enable complex workflows where work items must be selected in a specific order. By keeping depends_on separate from refs, we maintain clear semantics: refs are informational, depends_on are blocking. Resolving a dependency closure preserves an explicit root set while ensuring the loop has every prerequisite needed for deterministic planning. Re-resolving after explicit scope mutation lets a long-running loop adapt to corrected or newly discovered work without losing its execution session. Loop-level status tracking avoids polluting the Work Item status field with execution-specific states.

Tags: lifecycle, validation, work-items

Since: v0.1.0

[RFC-0006:C-ROUND-EXECUTION] Round Execution (Normative)

Loop rounds are local execution-protocol checkpoints for one loop, not automatic implementation performed by govctl.

A loop round MAY cover one or more work items from the loop’s current resolved dependency closure. The selected work set for a round MUST be derived from the loop state, dependency readiness, and any explicit --work selector accepted by RFC-0006:C-LOOP-COMMAND-SURFACE.

Round lifecycle:

Each round MUST have one of these local round states:

1. open — govctl has created the round skeleton and the agent is expected to implement, verify, and fill the summary evidence.
2. submitted — the round summary evidence has been provided but has not yet been incorporated into authoritative loop state.
3. closed — govctl has validated the round evidence and updated loop state.

govctl loop run LOOP-ID MUST advance exactly one local round-protocol step. It MUST NOT implement repository changes itself. It MUST NOT mark a Work Item done directly merely because loop-local criteria appear satisfied. Work Item lifecycle transitions remain owned by govctl work move per RFC-0002:C-LIFECYCLE-VERBS.

Opening a round:

When no open round exists, loop run MUST:

1. Load and validate the loop state.
2. Re-read current Work Item files for the selected work set.
3. Verify dependency readiness using RFC-0006:C-DEPENDENCY-SEMANTICS.
4. Create a loop-level round artifact under the loop directory.
5. Write a summary skeleton that records where the agent MUST provide actions, changed paths, verification evidence, blockers, and note candidates.
6. Display the round artifact path and the next required agent action.

Opening a round MAY update loop-local item statuses and round counters, but MUST NOT write transient execution trace into Work Item files. Round counters are audit metadata only and MUST NOT control selection, failure, or dependency propagation.

Closing a round:

When an open round exists, loop run MUST validate the round summary before advancing loop state. A round summary MUST distinguish:

• actions performed during the round
• changed paths or explicitly state that no file changes were made
• verification evidence, including existing govctl verify --work WI-ID or project guard output when applicable
• blockers or open questions
• note candidates that may become durable Work Item notes through explicit govctl work edit <WI-ID> notes --add ...

If required summary evidence is missing, loop run MUST return a Diagnostic that names the round artifact to complete and MUST leave loop state unchanged.

If blockers prevent progress, loop run MUST keep the loop non-terminal and record the next action in loop state. Durable retry rules MAY be added to Work Item notes, but only through explicit Work Item commands.

If the relevant Work Items have already reached terminal Work Item lifecycle states through govctl work move, loop run MUST reflect those lifecycle states in loop-local item status and MAY mark the loop completed when every current resolved item is terminal without failed or blocked loop outcomes.

loop run MUST NOT infer loop failure, Work Item failure, or dependency blockage from the number of rounds opened or closed for a Work Item.

Rationale:

govctl coordinates local execution state, Work Item metadata, dependency readiness, and verification evidence while the agent performs implementation work. This keeps loop execution trace in local loop artifacts and preserves Work Items as durable outcome artifacts. Retry budgets and repeated-invocation limits belong to callers because callers decide how much autonomous execution is appropriate.

Tags: core, validation

Since: v0.1.0

[RFC-0006:C-WORK-ITEM-INTERACTION] Work Item Interaction (Normative)

Loops interact with work items by reading Work Item lifecycle state, mapping it into loop-local item state, and recording local execution evidence. Loops MUST NOT own Work Item lifecycle transitions.

Lifecycle ownership:

1. Work Items in the resolved loop set MUST remain valid Work Items whose lifecycle state is one of queue, active, done, or cancelled.
2. govctl loop run MUST NOT transition a Work Item from queue to active.
3. govctl loop run MUST NOT transition a Work Item from active to done.
4. Work Item lifecycle transitions remain owned by govctl work move and its existing acceptance-criteria and verification-guard gates.
5. A Work Item with lifecycle state done MUST be represented as done in loop state when reflected by a loop operation.
6. A Work Item with lifecycle state cancelled MUST be represented as cancelled in loop state when reflected by a loop operation and MUST NOT be selected for new round work.

Validation requirements:

Before a Work Item is transitioned to done, the Work Item lifecycle command MUST verify the existing gate conditions defined by RFC-0001:C-GATE-CONDITIONS. A loop MAY record verification evidence in round summary artifacts, but that evidence does not replace the Work Item lifecycle gate.

Durable work item context:

The work item notes field is reserved for durable context that should persist across sessions:

• Key decisions made during implementation
• Blockers encountered and how they were resolved
• Important technical insights

Execution trace, including round-by-round progress, MUST be tracked in loop state and round artifacts, not in Work Item fields.

Loop-level work item status:

The loop tracks additional execution status for each work item in loop state:

• pending: Work item has not been selected or reflected as active/done/cancelled in this loop
• active: Work item is selected for local execution protocol or remains in progress
• done: Work item completed successfully through Work Item lifecycle state
• failed: Local loop execution evidence records an unrecoverable failure and dependents must not be selected
• blocked: Work item cannot be selected because dependencies failed, blocked, or were cancelled
• cancelled: Work item has Work Item status cancelled and is not selected

The loop-level statuses are independent of Work Item status field values except where explicitly mapped above. done, failed, blocked, and cancelled are terminal loop-level outcomes for dependency planning.

Rationale: Existing Work Item commands already provide lifecycle validation, acceptance criteria, verification guards, and durable governance history. Loops provide resumable local execution protocol state around those commands without becoming a second Work Item lifecycle engine. Separating loop-level status from Work Item status and notes maintains clear boundaries between execution state and governed artifacts.

Tags: lifecycle, validation, work-items

Since: v0.1.0

[RFC-0006:C-LOOP-RESUMPTION] Loop Resumption (Normative)

A loop MAY be paused and resumed across CLI invocations or agent sessions.

If a loop implementation supports resumption, it MUST:

1. Persist loop state using the storage contract defined by RFC-0006:C-LOOP-STATE-STORAGE.
2. Resume existing loop operations by positional LOOP-ID as defined by RFC-0006:C-LOOP-COMMAND-SURFACE.
3. Resume from the last recorded state and open round artifact rather than starting fresh when the requested loop state exists and is non-terminal.
4. Reject operations that require a non-terminal loop when the loop is terminal.

Discovery semantics:

Loop discovery MUST be separate from loop execution. Implementations MAY discover existing loops by listing persisted state, by filtering list output, or by reusing an existing non-terminal loop during loop start [--id LOOP-ID] WI-ID... when the requested work set matches exactly.

A stored loop matches a requested work set when its current editable work field contains the same Work Item IDs as the request, ignoring order. If a command performs work-set discovery and exactly one matching non-terminal loop exists, the implementation MAY select that loop. If more than one matching non-terminal loop exists, the implementation MUST reject the discovery attempt as ambiguous and require a positional LOOP-ID.

loop run MUST NOT perform work-set discovery and MUST NOT start a new loop.

Resumption semantics:

When resuming a loop:

• Work items in done loop state MUST NOT be selected for new round work.
• Work items in active loop state MAY be selected again only through the local round protocol.
• Work items in blocked, failed, or cancelled loop state MUST remain terminal for dependency planning unless an explicit scope mutation recomputes a dependency-derived blocked outcome.
• Work items in pending loop state MAY be selected in dependency order when opening a round unless an explicit run selector narrows execution per RFC-0006:C-LOOP-COMMAND-SURFACE.
• If loop.current_round points at an open round artifact, loop run MUST validate or reject that artifact before opening another round.
• Prior round counts MUST NOT prevent a non-terminal work item from being selected again when it is otherwise ready.

State preservation:

The loop state MUST preserve:

• Execution status of each current work item (pending, active, done, failed, blocked, cancelled)
• Round count for each current work item as audit metadata
• Last selected round for each current work item when known
• Current editable work field values
• Dependency graph at last planning time
• Current loop-level round number when known
• Next required action when known

The loop state MAY preserve:

• Detailed round history
• Guard execution result summaries
• Agent context and decision history inside local round artifacts

Rationale: Resumption enables long-running multi-WI loops to survive agent session boundaries without losing progress. Positional loop IDs provide precise lookup that matches the CLI’s noun/verb/object shape. Work-set matching remains a discovery convenience for start/list workflows, not an execution command mode. By persisting state independently of work item files, govctl maintains the separation between execution state and governed artifacts. Scope mutation makes the stored work set current rather than historical, so discovery continues to match the loop the user intends to resume. Round counts remain useful for audit and display without becoming hidden retry policy.

Tags: lifecycle

Since: v0.1.0

[RFC-0006:C-LOOP-STATE-STORAGE] Loop State Storage (Normative)

Loop execution state MUST be stored under .govctl/loops/<loop-id>/.

A loop ID is local execution-state identity, not a governed resource ID. A generated loop ID MUST match ^LOOP-\d{4}-\d{2}-\d{2}-\d{3}$. The date component MUST use ISO 8601 calendar date format YYYY-MM-DD for the local date when the ID is generated. The sequence component MUST be a three-digit positive sequence starting at 001 for each date. Implementations MUST choose the first available sequence for the date that does not collide with an existing .govctl/loops/<loop-id>/ directory. Implementations MUST generate a loop ID when one is omitted. Implementations MUST reject explicit loop IDs that do not match the canonical loop ID pattern. A loop ID MUST NOT contain /, \, or .. path traversal segments.

Each loop directory MUST contain state.toml as its authoritative current-state file. The state.toml file MUST use the following top-level shape:

[loop]
id = "<loop-id>"
state = "pending|active|paused|completed|failed"
work = ["WI-YYYY-MM-DD-NNN"]
resolved = ["WI-YYYY-MM-DD-NNN"]
current_round = 0
next_action = "start|write_summary|continue|resolve_blocker|complete"

[dependencies]
"WI-YYYY-MM-DD-NNN" = ["WI-YYYY-MM-DD-NNN"]

[items."WI-YYYY-MM-DD-NNN"]
status = "pending|active|done|failed|blocked|cancelled"
round_count = 0
last_round = 0

The loop.id value MUST match the <loop-id> directory name. The loop.state value MUST be one of the loop lifecycle states defined by RFC-0006:C-LOOP-LIFECYCLE. The loop.work array MUST preserve the current explicit work item set for the loop. The loop.resolved array MUST contain the current resolved dependency closure and MUST include every loop.work entry. The loop.work and loop.resolved arrays MUST NOT contain duplicate Work Item IDs.

The optional loop.current_round value records the latest loop-level round number known to state. The optional loop.next_action value records the next required human or agent action. Older state files that omit these fields MAY be upgraded in place when written.

The [dependencies] table MUST contain one entry for each work item in loop.resolved. Each dependency entry MUST be an array of Work Item IDs. Each dependency ID MUST also appear in loop.resolved. Dependency arrays MUST NOT contain duplicate Work Item IDs.

The [items.<WI-ID>] table MUST contain one entry for each work item in loop.resolved. Each item status MUST be one of the loop-level work item statuses defined by RFC-0006:C-WORK-ITEM-INTERACTION. Each round_count MUST be a non-negative integer. The optional last_round value records the last loop-level round that selected or updated the item. round_count and last_round are audit metadata and MUST NOT encode retry budgets or failure policy.

Loop state storage MUST be keyed by loop ID, not by work item ID. A multi-work-item loop MUST have one shared loop state root so dependency planning, failure propagation, and resumption use the same authoritative state.

Loop round artifacts MUST be stored under .govctl/loops/<loop-id>/rounds/round-NNN.toml, where NNN is the three-digit loop-level round number. A round artifact MUST identify the loop ID, round number, selected work item IDs, round state, summary evidence, blockers, and note candidates. Round artifacts MUST NOT encode maximum round limits or caller retry budgets. Round artifacts are local execution trace and MUST NOT be written to Work Item fields.

Round artifacts MAY mention Work Item IDs when evidence applies to specific work, but the storage root is loop-level. Implementations MUST NOT require per-work-item round directories for the canonical state model.

Loop state is local execution state, not a governed artifact. Deleting .govctl/loops/ MUST NOT invalidate RFCs, ADRs, Work Items, Guards, or rendered governance projections, but MAY remove resumability and local execution trace.

Rationale: A loop can drive multiple work items, so a per-work-item state root cannot represent the loop lifecycle, dependency graph, aggregate outcome, or round evidence. A single loop directory keeps execution state separate from Work Item files while preserving enough protocol state for resumption. Canonical generated loop IDs follow the existing artifact style of a type prefix, date, and sequence while avoiding collision-prone plain-text IDs. Keeping retry budgets out of persisted loop state prevents caller policy from becoming hidden local-state semantics.

Tags: core

Since: v0.1.0

[RFC-0006:C-LOOP-SCOPE-MUTATION] Loop Scope Mutation (Normative)

A loop implementation MAY support explicit scope mutation for a non-terminal loop. A scope mutation changes or refreshes the loop’s current editable work field and recomputes the resolved dependency closure without creating a new loop ID.

Scope mutation MUST support these operations:

1. Replan: keep the current editable work field and recompute its dependency closure from the current work item files.
2. Add work: add one Work Item ID to the current editable work field, then recompute the dependency closure.
3. Remove work: remove one Work Item ID from the current editable work field, then recompute the dependency closure.

Implementations MUST reject scope mutation for terminal loops. Implementations MUST reject scope mutation that would leave the editable work field empty. Implementations MUST validate added or removed work values as Work Item IDs. Implementations MUST store the explicit work set without duplicates.

A scope mutation MUST build a candidate loop state before replacing the stored state. The candidate state MUST use the current explicit work set after the requested add/remove/replan operation. The candidate state MUST resolve dependencies using the rules in RFC-0006:C-DEPENDENCY-SEMANTICS. If dependency resolution fails, the implementation MUST leave the previously stored loop state unchanged.

For work items that remain in the resolved dependency closure, scope mutation MUST preserve round_count. Scope mutation MUST preserve explicit terminal execution outcomes done, failed, and cancelled. Scope mutation MUST recompute blocked outcomes from the current dependency graph and current terminal dependency outcomes; a previously blocked work item MAY return to pending when its current dependencies no longer require blocking. Non-terminal work items MUST NOT be selected for a new round until their current dependencies satisfy RFC-0006:C-DEPENDENCY-SEMANTICS.

For newly introduced work items, scope mutation MUST initialize loop-level item state using the same Work Item status mapping used at loop start. For work items that no longer appear in the resolved dependency closure, scope mutation MUST remove their entries from loop.resolved, [dependencies], and [items] in state.toml. Removing a work item from current loop state MUST NOT undo any Work Item lifecycle transitions that already happened through govctl work commands. Optional historical round artifacts for removed work items MAY remain under the loop directory, but they MUST NOT be treated as part of the current loop state.

Rationale:

Long-running cleanup and implementation loops often discover that the original batch is missing work, contains unnecessary work, or needs dependency files re-read after edits. Scope mutation keeps one execution session identity while making the current work field and dependency closure explicit, validated, and recoverable. Modeling this as a field mutation keeps loop commands aligned with the existing edit model while preserving loop-specific replanning behavior.

Since: v0.2.0

[RFC-0006:C-LOOP-LISTING] Loop Listing (Normative)

If provided, the listing command MUST enumerate persisted loop state from .govctl/loops/*/state.toml without requiring a caller to know a loop ID or work item set first. The command MUST validate each canonical loop state it lists using the storage contract in RFC-0006:C-LOOP-STATE-STORAGE.

The listing command MUST produce deterministic output ordered by loop ID. Each listed loop MUST include at least the loop ID, lifecycle state, editable work field values, resolved work item count, and aggregate round count across current loop items. Machine-readable output, when supported, MUST expose the same user-facing fields.

The listing command MAY support filters by lifecycle state, loop ID substring, or work item ID substring. Filtering MUST NOT mutate loop state and MUST NOT select a loop for execution by itself.

Rationale: Work-set discovery is useful only after the caller has a stable loop identity. A listing command gives agents and humans a stable discovery entrypoint for interrupted or long-running batch loops while preserving the rule that loop state remains local execution state rather than a governed artifact. The caller can then pass the listed loop ID as the positional object to commands such as loop run, loop show, or loop resume.

Since: v0.3.0

[RFC-0006:C-LOOP-COMMAND-SURFACE] Loop Command Surface (Normative)

Implementations that expose a govctl loop command MUST treat it as a project-level local execution-state command namespace as defined by RFC-0002:C-GLOBAL-COMMANDS. Loop state is not a governed artifact resource, so loop commands MUST NOT expose unrestricted resource CRUD field-editing verbs for arbitrary loop state. Loop commands MAY expose specified editable fields whose semantics are defined by this RFC.

Argument roles:

Loop command arguments MUST have stable roles:

1. A positional LOOP-ID argument identifies an existing persisted local loop state directory.
2. A --id LOOP-ID flag MAY be used only by commands that create a loop state, where it requests the ID to create or reuse.
3. Positional WI-ID... arguments identify explicit loop work field values for loop creation or field mutation.
4. Positional WI-ID... arguments MUST NOT mean an execution target subset.
5. Execution target selection MUST use an explicit selector flag.
6. Loop field mutation MUST use the explicit add LOOP-ID work WI-ID and remove LOOP-ID work WI-ID shapes defined below.

Canonical subcommands:

The canonical loop subcommands are:

1. loop list [filter]: read persisted loop states. This command MUST be read-only.
2. loop show LOOP-ID: read one persisted loop state by loop ID. This command MUST be read-only.
3. loop start [--id LOOP-ID] WI-ID...: create or reuse a loop for an explicit work field set.
4. loop resume LOOP-ID: select and display an existing non-terminal loop by loop ID. This command MUST be read-only and MUST NOT advance rounds.
5. loop run LOOP-ID [--work WI-ID ...]: advance the local round protocol for an existing loop state.
6. loop replan LOOP-ID: recompute the dependency closure for the current explicit work field set.
7. loop add LOOP-ID work WI-ID: add a Work Item ID to the loop’s editable work field and replan.
8. loop remove LOOP-ID work WI-ID: remove a Work Item ID from the loop’s editable work field and replan.

loop run MUST NOT accept a maximum-rounds argument or any other caller retry-budget argument. Repeated execution limits belong to callers and MUST NOT be persisted in loop state or round artifacts.

The work field is the only accepted user-facing field name for the loop’s explicit work set. Implementations MUST reject wi and every other field alias.

Discovery semantics:

loop start [--id LOOP-ID] WI-ID... MAY reuse an existing non-terminal loop with the same current explicit work field set instead of creating a new loop. If more than one non-terminal loop matches the requested work set, the implementation MUST reject the operation as ambiguous and require the caller to use loop list and then pass a positional LOOP-ID to the desired operation.

loop list [filter] MUST support discovering loop state without requiring a caller to know a loop ID first per RFC-0006:C-LOOP-LISTING. Work-set discovery is a discovery behavior, not an execution selector.

loop run MUST NOT start a new loop and MUST NOT discover a loop by positional Work Item IDs. It operates only on the positional LOOP-ID argument.

Run selection semantics:

The --work WI-ID flag selects execution targets inside the loop identified by the positional LOOP-ID. Implementations MUST reject duplicate --work values. Implementations MUST reject any --work value that is not a Work Item ID in the current loop.resolved array. These validations MUST complete before writing loop state.

If no --work selector is provided, loop run LOOP-ID MUST consider every current work item in the loop’s resolved dependency closure when opening a round, subject to dependency readiness.

If one or more --work selectors are provided, loop run LOOP-ID --work WI-ID... MUST restrict the opened or advanced round to the selected target work items and their current in-loop transitive dependencies. The implementation MUST NOT select unrelated work items for that round. The implementation MAY update derived loop-level dependency outcomes, such as blocked dependents, when required to keep loop state consistent with RFC-0006:C-DEPENDENCY-SEMANTICS.

Targeted run selection MUST NOT replace, shrink, expand, or otherwise mutate the loop’s editable work field. Scope changes MUST use replan, add, or remove.

loop run MUST NOT silently perform repository implementation work, tick acceptance criteria, add Work Item notes, or move Work Items to done. Agents and humans MUST perform those operations through the existing Work Item and verification command surfaces. loop run records and validates local round evidence so those existing operations have resumable execution context.

Rationale:

The loop command namespace coordinates several governed resources but stores its own local execution state, so it is neither a governed artifact resource nor a simple single global command. Existing-loop operations use positional LOOP-ID arguments to match the rest of the CLI’s noun/verb/object shape. Stable argument roles prevent hidden mode switches: positional work item IDs in add and remove are field values for the loop’s work field, while --work is the explicit work-item execution selector. Keeping the field position visible preserves the CLI edit model while making loop-specific replanning a domain side effect of changing the field. Reusing run as the round-protocol advancement command preserves existing skill guidance while removing the misleading interpretation that govctl itself implements code. Excluding retry-budget flags keeps the command surface small and leaves autonomous execution policy to callers.

Since: v0.4.0

3. Rationale

[RFC-0006:C-UNIFIED-MODEL] Unified Model Rationale (Informative)

The unified loop model (single primitive for both single-WI and multi-WI execution) was chosen over separate /loop and /batch skills because:

1. Work items naturally form DAGs: Agents frequently create multiple related work items with dependencies, then iterate through them as a batch. Separate skills would force users to choose between /loop WI-001 and /batch WI-001 WI-002 WI-003 when the underlying mechanism is identical.

2. Simpler mental model: “A loop drives work items to completion” is one concept. “A loop drives one work item, a batch drives multiple” is two concepts with overlapping semantics.

3. Consistent state model: .govctl/loops/<loop-id>/ works the same whether the loop contains one work item or ten. Execution logs, state file, and round logs scale naturally.

4. Downstream flexibility: The loop does not prescribe sequential or parallel execution. Downstream applications (agents, CI systems) can choose the execution model that fits their constraints.

Tags: core

Since: v0.1.0

[RFC-0006:C-EXECUTION-STATE-SEPARATION] Execution State Separation Rationale (Informative)

Execution state lives in .govctl/loops/<loop-id>/ (not in work item TOML) because:

1. Work items are outcome artifacts: They should contain scope (description), success criteria (acceptance_criteria), and durable context (notes). They should not accumulate execution logs during active work.

2. Rich execution traceability: Loops need to track round-by-round progress, guard results, criteria addressed per round, and detailed logs. This is too much data for a work item TOML file.

3. Clean diffs: Work item TOML files remain stable and reviewable. Execution state changes frequently during a loop and is not meant for code review.

4. Ephemeral by design: Loop state is local to the developer’s machine. It can be deleted without losing governance artifacts. The work item’s notes field captures durable learnings.

5. Shared loop coordination: Multi-work-item loops need one state root for lifecycle, dependency graph, failure propagation, and resumption. A per-work-item state root would force the loop to reconstruct shared state from fragments.

Tags: core

Since: v0.1.0

[RFC-0006:C-DEPENDENCY-SEPARATION] Dependency Separation Rationale (Informative)

The depends_on field is separate from refs because they serve different purposes:

• refs: Informational cross-references (“this work item is related to that RFC”). Does not block execution. Used for traceability and navigation.

• depends_on: Execution dependencies (“this work item cannot start until that work item completes”). Blocks execution. Used for dependency resolution and failure propagation.

Conflating these would force the loop to guess whether a ref is a hard dependency or just a related artifact. Separate fields make intent explicit.

Tags: core, work-items

Since: v0.1.0

Changelog

v1.0.0 (2026-07-25)

Use canonical loop command and round metadata surfaces

Changed

• Use canonical Work Item edit syntax in round evidence guidance

Removed

• Remove the loop work-item field alias and legacy round metadata tolerance

v0.5.0 (2026-06-15)

Remove loop max-rounds budget from the round protocol

Changed

• round_count is audit metadata and cannot drive failure semantics

Removed

• loop run –max-rounds retry-budget argument
• max_rounds from new loop round artifacts

v0.4.0 (2026-06-03)

Define loop command surface

Added

• Loop command surface defines canonical loop subcommands and argument roles

Changed

• Loop run advances an existing local round protocol by LOOP-ID with explicit –work target selection

v0.3.0 (2026-06-01)

Define loop listing discovery

Added

• Loop listing command discovers persisted local loop state

v0.2.0 (2026-06-01)

Define loop scope mutation and canonical loop IDs

Added

• Loop scope mutation supports replan plus add/remove of the editable work field

Changed

• Loop IDs use LOOP-YYYY-MM-DD-NNN canonical format

v0.1.0 (2026-05-31)

Initial draft

RFC-0007: TUI v2 read-only cockpit

Version: 0.4.0 | Status: normative | Phase: impl Owners: @govctl-org Tags: tui

References: RFC-0003, RFC-0006, RFC-0002, RFC-0008

1. Summary

[RFC-0007:C-SUMMARY] Summary (Informative)

This RFC defines TUI v2 as a human-first, read-only cockpit for understanding a governed project.

TUI v2 builds on the baseline browsing behavior in RFC-0003, the global search contract in RFC-0002:C-SEARCH-COMMAND, and the loop state model in RFC-0006. It focuses on project overview, artifact discovery, loop state visualization, diagnostics, and readable navigation.

Scope: This RFC covers externally visible TUI behavior and interaction constraints. It does not specify private Rust module layout, ratatui widget internals, or a full interactive artifact editor.

Rationale: The existing TUI is useful for browsing RFCs, ADRs, and work items, but it does not expose newer governance concepts such as search, loop local state, dependency DAGs, guards, releases, or check diagnostics. TUI v2 should help a human understand project state quickly without creating a second mutation surface parallel to the CLI.

Since: v0.1.0

2. Specification

[RFC-0007:C-READ-ONLY] Read-only cockpit boundary (Normative)

TUI v2 MUST be read-only for governed project state in its first implementation phase.

TUI v2 MUST NOT create, edit, delete, move, finalize, accept, reject, supersede, deprecate, render, or otherwise mutate governed artifacts.

TUI v2 MUST NOT mutate persisted loop state or round artifacts under .govctl/loops/.

TUI v2 MAY refresh disposable derived local indexes under .govctl/ only when doing so follows the freshness and local-state rules defined by RFC-0002:C-SEARCH-COMMAND.

When TUI v2 presents an operation that would mutate state, it MUST present it as a suggested CLI command or help text rather than executing it.

Rationale: The CLI already owns mutation semantics, dry-run behavior, diagnostics, lock handling, and lifecycle gates. Keeping the first TUI v2 phase read-only gives humans a richer project cockpit without creating a second, weaker edit model.

Since: v0.1.0

[RFC-0007:C-RESPONSIBILITY-BOUNDARIES] TUI responsibility boundaries (Normative)

TUI v2 MUST keep terminal I/O, input dispatch, data loading, and rendering as separate responsibilities.

The terminal adapter MUST be limited to terminal lifecycle, event polling, event reading, frame drawing, and shutdown handling.

Input dispatch MUST translate keyboard input into in-memory TUI state transitions.

Input dispatch MUST NOT perform filesystem I/O, database access, command execution, terminal drawing, or governed artifact mutation.

Renderers MUST read already-loaded TUI state and draw frames.

Renderers MUST NOT load project artifacts, refresh indexes, execute commands, mutate governed state, or mutate persisted loop state.

Data-loading code MUST convert filesystem, schema, search-index, and loop-state failures into visible diagnostic state rather than hiding them from the cockpit.

New primary views or key-routing behavior SHOULD be covered by focused state-transition tests, renderer tests using a terminal test backend, or both.

Rationale: These boundaries keep TUI v2 human-facing, read-only, and testable without creating a second hidden execution model beside the CLI.

Since: v0.2.0

[RFC-0007:C-COCKPIT-VIEWS] Cockpit view model (Normative)

TUI v2 MUST provide a top-level human navigation model with visible entry points for overview, artifact browsing, search, loops, and diagnostics.

The overview view MUST summarize at least RFCs, ADRs, work items, and verification guards when those artifacts are available.

The artifact browsing views MUST preserve the existing RFC, ADR, and Work Item browsing capabilities required by RFC-0003.

The artifact browsing views SHOULD include verification guards, clauses, releases, and tags when those data sources can be loaded without violating RFC-0007:C-READ-ONLY.

Artifact detail views MUST use the current projection defined by RFC-0002:C-SHOW-PROJECTION so obsolete RFC, ADR, and Clause body content is omitted by default.

The current view, selection context, active filter or query, and primary key bindings MUST remain visible or discoverable without leaving the TUI.

Rationale: A cockpit should orient a human before asking them to drill into details. Reusing the current projection keeps obsolete requirements from appearing authoritative, while the CLI retains explicit archival access. The top-level model makes newer governance concepts discoverable while preserving the older RFC/ADR/Work browsing workflows.

Since: v0.1.0

[RFC-0007:C-LOOP-VIEWS] Loop state views (Normative)

TUI v2 MUST provide a loop list view that discovers persisted loop states according to RFC-0006:C-LOOP-LISTING.

Each listed loop MUST show the loop ID, lifecycle state, editable work roots, resolved work item count, aggregate round count, and next action when those values are present in valid loop state.

TUI v2 MUST provide a loop inspector for a selected loop.

The loop inspector MUST show the selected loop’s lifecycle state, current round, next action, editable work roots, resolved work set, loop-level item statuses, round counts, and dependency information.

If a loop state file is invalid, TUI v2 MUST present a readable diagnostic for that loop and MUST NOT treat invalid loop state as authoritative.

TUI v2 MUST NOT repair, replan, resume, run, or otherwise mutate loop state while rendering loop views.

Rationale: Loop state is local but highly useful to humans resuming or auditing work. The TUI should expose this state directly while preserving RFC-0006 ownership of loop execution semantics.

Since: v0.1.0

[RFC-0007:C-LOOP-DAG] Loop dependency DAG visualization (Normative)

TUI v2 MUST render a selected loop’s dependency graph as a visual DAG derived from the loop state’s dependencies table.

The DAG view MUST represent every work item in the loop state’s resolved work set unless viewport constraints require an explicit neighborhood or layer-limited fallback.

The DAG view MUST distinguish loop-level item statuses such as pending, active, done, failed, blocked, and cancelled using readable text and semantic styling.

The DAG view MUST make the selected work item visually distinct and MUST show its direct dependencies and direct dependents when that information is available.

The DAG layout MUST be deterministic for the same loop state.

When the graph is too large or the terminal viewport is too small for a full DAG, TUI v2 MUST degrade to a readable representation that still exposes ordering, dependencies, selected item context, and hidden item counts.

Rationale: A plain topological list is not enough for humans to understand batch execution. A visual DAG exposes why work is ready, blocked, or downstream of another item while still allowing terminal-size fallbacks.

Since: v0.1.0

[RFC-0007:C-SEARCH] TUI search (Normative)

TUI v2 MUST provide a search view for governed artifacts.

The search view MUST interpret query text according to RFC-0002:C-SEARCH-COMMAND rather than exposing backend-specific raw query syntax.

The search view SHOULD support artifact type filtering and tag filtering when the terminal interaction model can expose those filters clearly.

Search results MUST show at least artifact kind, ID, title, and enough snippet or metadata context for a human to choose a result.

Selecting a search result MUST navigate to the corresponding TUI detail view when that artifact kind is supported by TUI v2.

Search result loading MUST follow the read-only boundary in RFC-0007:C-READ-ONLY.

Rationale: Search is the fastest way for humans to recover context in a large governed repository. Reusing the CLI search contract prevents TUI search from drifting into a separate discovery model.

Since: v0.1.0

[RFC-0007:C-DIAGNOSTICS] Diagnostics view (Normative)

TUI v2 MUST provide a diagnostics view that presents project check diagnostics to a human.

The diagnostics view MUST show diagnostic severity, code, message, and target context when those fields are available.

The diagnostics view SHOULD group or filter diagnostics by severity and artifact target.

When a diagnostic target corresponds to an artifact that TUI v2 can display, selecting the diagnostic SHOULD navigate to that artifact’s detail view or an equivalent contextual view.

The diagnostics view MUST NOT automatically apply migrations, edit artifacts, render documents, or run mutation commands to resolve diagnostics.

Rationale: govctl check is the central safety signal for governed work. TUI v2 should make those diagnostics easier for a human to triage without turning validation into an implicit repair workflow.

Since: v0.1.0

[RFC-0007:C-HUMAN-UX] Human-first terminal UX (Normative)

TUI v2 MUST optimize rendered screens for human comprehension rather than machine parsing.

TUI v2 MUST use consistent semantic styling for artifact kind, lifecycle status, phase, diagnostic severity, loop item status, selection, and muted secondary information.

TUI v2 MUST preserve keyboard-only navigation across all primary views.

TUI v2 MUST expose view-specific key bindings through persistent footer text, help overlay, or an equivalent discoverable mechanism.

TUI v2 MUST avoid layouts where essential text overlaps, truncates without context, or becomes unreadable on common narrow terminal widths.

When a terminal is too small for the preferred layout, TUI v2 MUST fall back to a simpler readable layout rather than preserving a broken multi-pane layout.

Rationale: A human-facing terminal UI succeeds when state, hierarchy, and next steps are quickly legible. Visual polish should come from semantic consistency and resilient layout, not from decorative complexity.

Since: v0.1.0

[RFC-0007:C-CONFORMANCE-VIEWS] Conformance Case views (Normative)

TUI v2 MUST expose Conformance Cases as a first-class read-only artifact view when the project schema supports Conformance Cases.

The overview MUST show the number of Conformance Cases.

The Conformance Case list MUST show each Case ID, title, aggregate requirement applicability, scenario path and selector, and associated Verification Guards.

The Conformance Case detail view MUST show the Case ID, title, tags, scenario path and selector, all versioned requirement bindings with their derived applicability, the aggregate requirement applicability, and all associated Verification Guards.

Requirement applicability MUST be derived according to RFC-0008:C-TRACE-QUERY. TUI v2 MUST NOT label a Case, requirement, or Guard as covered, passed, conformant, or evidenced.

Selecting a Conformance Case search result MUST navigate to its detail view. When a diagnostic target identifies a Conformance Case, selecting that diagnostic SHOULD navigate to its detail view.

Tag usage summaries MUST include Conformance Case tags.

All Conformance Case views MUST follow RFC-0007:C-READ-ONLY and the resilient layout requirements in RFC-0007:C-HUMAN-UX.

Rationale: First-class Case browsing keeps requirement-to-scenario-to-Guard relationships visible in the same cockpit as other governed artifacts while preserving the declared-not-evidenced boundary.

Tags: tui

Since: v0.4.0

Changelog

v0.4.0 (2026-07-27)

Expose Conformance Cases in the TUI cockpit

Added

• Add read-only Conformance Case overview, list, detail, and navigation

v0.3.0 (2026-07-27)

Align TUI detail views with current governance state

Changed

• Use current projections for artifact detail views

v0.2.0 (2026-06-07)

Specify TUI responsibility boundaries

Added

• Require terminal I/O, input dispatch, data loading, and rendering to remain separate testable responsibilities

v0.1.0 (2026-06-06)

Initial draft

RFC-0008: Conformance Case and Declared Traceability Model

Version: 0.1.1 | Status: normative | Phase: impl Owners: @govctl-org

References: RFC-0000:C-CLAUSE-DEF, RFC-0000:C-GUARD-DEF, RFC-0000:C-REFERENCE-HIERARCHY, RFC-0001:C-RFC-STATUS, RFC-0001:C-CLAUSE-STATUS, RFC-0002:C-RESOURCE-MODEL, RFC-0002:C-RESOURCES, RFC-0002:C-CRUD-VERBS, RFC-0002:C-EDIT-FIELD-CONTRACT, RFC-0002:C-SHOW-PROJECTION, RFC-0002:C-GLOBAL-COMMANDS, RFC-0002:C-COMPATIBILITY-BOUNDARY, RFC-0002:C-OUTPUT-FORMAT, RFC-0002:C-SEARCH-COMMAND

1. Summary

[RFC-0008:C-SCOPE] Scope and Authority (Informative)

Projects can identify RFC Clauses and execute reusable Verification Guards, but they cannot give individual acceptance scenarios stable governance identities or query the declared relationships between scenarios, requirements, and Guards. At scale, scenario prose is copied into RFCs or Work Items, positional test references become unstable, and agents must search opaque project files to reconstruct context.

This RFC defines a first-class Conformance Case as a version-aware, non-normative declaration between RFC Clauses and Verification Guards. An RFC Clause remains the sole semantic authority. A Case identifies project-owned scenario content and declared Guard associations; it does not prove execution, passage, coverage, or conformance.

This RFC covers current Case identity and storage, stable scenario locators, version-bound requirement relationships, derived applicability state, structural validation, and trace queries. It does not define sub-Clause requirement anchors, a test runner, domain-specific fixture or oracle formats, Work Item completion requirements, persistent run results, Case revisions or lifecycle states, Suite resources, or a general custom-artifact framework.

The Conformance Case resource integrates with the authority, resource, CRUD, edit, show, global-command, search, compatibility, and output contracts defined by RFC-0000:C-REFERENCE-HIERARCHY, RFC-0002:C-RESOURCES, RFC-0002:C-CRUD-VERBS, RFC-0002:C-EDIT-FIELD-CONTRACT, RFC-0002:C-SHOW-PROJECTION, RFC-0002:C-GLOBAL-COMMANDS, RFC-0002:C-SEARCH-COMMAND, RFC-0002:C-COMPATIBILITY-BOUNDARY, and RFC-0002:C-OUTPUT-FORMAT.

Tags: core

Since: v0.1.0

2. Specification

[RFC-0008:C-CONFORMANCE-CASE] Conformance Case Definition (Normative)

A Conformance Case is a current, non-normative declaration that gives one project-owned acceptance scenario a stable identity and relates it to RFC version markers and reusable Verification Guards.

Every Conformance Case MUST be stored at gov/conformance/<CONF-ID>.toml with:

• a [govctl] section containing id and title;
• an optional [govctl] field tags; and
• a [case] section containing path, selector, requirements, and optional guards.

Each requirements entry MUST be an object containing exactly ref and version. ref MUST be a fully qualified RFC Clause ID. version MUST be a semantic version belonging to the owning RFC. The version is a declared applicability and rebaseline marker; it MUST NOT be interpreted as a retrievable historical Clause snapshot, content signature, or execution result. Omitted guards and tags fields MUST be interpreted as empty arrays.

A Conformance Case ID MUST match CONF-[A-Z][A-Z0-9-]*. The ID MUST be unique within the repository. The filename stem MUST equal the ID. The title MUST be non-empty.

path MUST be a repository-relative path that resolves within the project root, outside the configured gov root, to an existing regular file. selector MUST be a non-empty, project-defined locator token associated with that file. The reserved selector * MUST declare that the Case applies to the complete file. govctl MUST treat all other selector syntax and resolution semantics as opaque. The (path, selector) pair MUST be unique among Conformance Cases. Pair equality MUST compare the canonical resolved filesystem target for path and the exact stored selector string, so lexically different paths or symlinks to the same file do not create duplicate locators.

A Case MAY bind one scenario to multiple requirement Clauses and multiple Guards. These bindings are declarations only. A Case MUST NOT establish, alter, or broaden an RFC obligation, and humans and agents MUST resolve every semantic disagreement in favor of the RFC.

A Conformance Case has no persisted lifecycle status. Its requirement bindings derive current, candidate, provisional, or stale applicability under RFC-0008:C-TRACE-QUERY. Editing or deleting a Case changes only the current declaration; repository version control remains the history mechanism. Case mutation MUST NOT modify RFC versions, changelogs, Clause metadata, or sealed content signatures.

Conformance Case storage MUST use project schema version 4. Conformance commands on a version 3 project MUST fail without mutation and instruct the user to run govctl migrate. Normal project loading of version 3 data that contains gov/conformance/*.toml MUST fail with the same instruction rather than ignore those files.

Migration from version 3 to version 4 MUST install all current bundled schemas and MUST NOT create Cases or requirement bindings. A successfully migrated project MUST load and validate Conformance Case files, enforce prohibited Conformance Case references, expose the conformance resource commands, and include Cases in search --type conformance. As a recovery exception to normal version 3 loading, govctl migrate MUST validate prospective Case files with the version 4 schema and MUST validate the complete prospective Case graph under RFC-0008:C-VALIDATION before mutation. Valid files MUST be preserved by the atomic migration; any schema or graph error MUST produce diagnostics and leave the project unchanged.

Rationale: Stable locator tokens and RFC version markers make declared relationships addressable without importing project test semantics into govctl. Current-only mutation keeps the resource small, while derived stale applicability exposes RFC evolution without creating another artifact lifecycle.

Tags: schema

Since: v0.1.0

[RFC-0008:C-TRACEABILITY] Case-Owned Declared Traceability (Normative)

Conformance traceability MUST use Case-owned edges:

1. A Conformance Case owns its versioned requirements edges to RFC Clauses.
2. A Conformance Case MAY own guards edges to Verification Guards.
3. Verification Guards and Work Items MUST NOT persist reverse Conformance Case lists. A Verification Guard refs entry MUST NOT identify a Conformance Case.

Each Guard ID in a Case MUST identify an existing Verification Guard. A Case-to-Guard edge declares that the project associates that Guard with execution of the Case locator. It MUST NOT be treated as evidence that the Guard selects the locator, has run, has passed, or establishes conformance.

Implementations MUST derive Clause-to-Case, Guard-to-Case, and Clause-to-Guard views from Case-owned edges. A Guard associated with a multi-requirement Case is related to that Case and its listed requirement bindings; this relationship MUST NOT be summarized as proof that every obligation in a Clause is covered.

Deleting a Verification Guard MUST be rejected while any Conformance Case identifies that Guard. The diagnostic MUST identify every Case referrer.

Conformance Case target restrictions for RFCs, ADRs, and Work Items are defined by RFC-0000:C-REFERENCE-HIERARCHY. Work Item completion policy MUST continue to select Verification Guards through the existing required-Guard surface rather than through Cases.

Rationale: Keeping both edge types in the Case makes one scenario locally understandable and avoids Guard files containing hundreds of reverse IDs. Prohibiting durable Work Item references preserves current-only Case mutation without rewriting historical task meaning.

Tags: validation

Since: v0.1.0

[RFC-0008:C-VALIDATION] Conformance Validation (Normative)

Project validation MUST validate every Conformance Case and the complete declared trace graph.

Validation MUST report an error when:

• a Case file fails its machine-readable schema;
• a Case ID is duplicated or differs from its filename;
• a title, path, or selector is empty;
• a path is absolute, escapes the project root, resolves under the configured gov root, is missing, or does not resolve to a regular file;
• two Cases use the same (path, selector) pair under the equality rule in RFC-0008:C-CONFORMANCE-CASE;
• a Case has no requirement binding;
• a requirement ref is missing, is not a Clause, or identifies an informative Clause;
• a requirement version is not present in the owning RFC changelog, predates the Clause since version, or differs from the current version of a draft RFC;
• a requirement targets a pending Clause whose owning RFC is not draft;
• a Case repeats the same requirement ref;
• a Guard ID is missing or repeated within a Case;
• a Case repeats a tag, or uses an unregistered or malformed tag; or
• a Verification Guard refs entry identifies a Conformance Case.

A pending Clause in a draft RFC has no since version. For such a Clause, validation MUST accept only a binding to the draft RFC current version. A pending Clause in a normative or deprecated RFC MUST NOT be a valid Case target because no RFC version owns it yet.

A permanent Clause deletion MUST reject a Clause referenced by a Conformance Case and MUST identify the Case as a referrer. RFC or Clause status transitions and RFC version changes MUST NOT be rejected solely because they make a valid Case binding stale.

A structurally valid stale, candidate, or provisional binding MUST NOT produce a project-validation diagnostic. An empty Case guards array MUST NOT produce a diagnostic. govctl validates identities, versions, paths, and typed edges; it MUST NOT claim to validate the opaque scenario semantics, selector resolution, or actual Guard execution.

Rationale: Structural validation keeps declared traceability navigable and prevents silent data loss. Derived applicability avoids either blocking RFC evolution or forcing users to retarget stable Case IDs merely to keep the repository valid.

Tags: validation

Since: v0.1.0

[RFC-0008:C-COMMAND-SURFACE] Conformance Resource Commands (Normative)

Implementations MUST expose Conformance Cases through the top-level conformance resource namespace and the resource-first structure defined by RFC-0002:C-RESOURCE-MODEL.

Creation MUST use:

govctl conformance new "<title>" --path <path> --selector <selector> --requirement <CLAUSE-ID>@<VERSION> [--requirement <CLAUSE-ID>@<VERSION> ...] [--guard <GUARD-ID> ...] [--id <CONF-ID>]

--path and --selector MUST each occur exactly once. --requirement MUST be repeatable and occur at least once. --guard MAY be repeated. When --id is absent, govctl MUST generate a valid unused ID from the title. When --id is present, govctl MUST validate and use that ID.

The resource MUST support list, get, show, edit, and delete with the applicable shared behavior defined by RFC-0002:C-CRUD-VERBS and RFC-0002:C-SHOW-PROJECTION. get <id> [field] MUST expose id, title, tags, path, selector, requirements, and guards. Plain retrieval of requirements MUST emit one <CLAUSE-ID>@<VERSION> value per line; plain retrieval of guards and tags MUST emit one stored value per line. Because Cases have no lifecycle state, current and archive show projections MUST be content-equivalent.

conformance edit MUST accept only these logical paths and operations:

Adding or exact-value removing a requirement MUST accept the same <CLAUSE-ID>@<VERSION> value used by new. Changing a requirement ref MUST use an add followed by removal of the old binding; it MUST NOT expose a scalar requirements[i].ref mutation that can create an invalid intermediate ref-version pair. Indexed removal MUST use requirements[i] --remove.

Wire-layout prefixes such as govctl. and case. MUST be rejected. Every Case creation and edit MUST validate the mutated Case’s own fields, locator uniqueness, and direct Clause, Guard, tag, and scenario-path dependencies before writing. Case deletion MUST validate its governed referrers. Repository-wide consistency remains owned by govctl check; a Case mutation MUST NOT be rejected solely because an unrelated artifact or derived projection is invalid or stale. An edit that would remove the final requirement binding MUST be rejected. Every failed creation, edit, or deletion MUST leave governed files unchanged.

Conformance Case tags MUST use the controlled vocabulary and syntax defined by RFC-0002:C-RESOURCES. conformance list MUST support the shared --tag filter. Cases MUST be included in govctl tag list usage counts, and govctl tag delete MUST reject a tag still used by a Case.

Global search MUST index Conformance Case IDs, titles, tags, paths, selectors, requirement refs and versions, and Guard IDs. govctl search --type conformance MUST select this resource type. A Case search result path MUST identify the gov/conformance/<CONF-ID>.toml artifact source rather than the scenario path; JSON Case results MUST expose the scenario path separately as scenario_path.

Rationale: Canonical CRUD keeps authoring consistent with existing resources, while a dedicated trace query supplies reverse navigation without creating a general graph language or a second execution policy.

Tags: cli

Since: v0.1.0

[RFC-0008:C-TRACE-QUERY] Declared Trace Query (Normative)

Implementations MUST support the resource-first query:

govctl conformance trace [TARGET] [--output <format>]

TARGET MAY be absent or identify one RFC, Clause, Conformance Case, or Verification Guard. An absent target MUST select all Cases. An RFC target MUST select Cases with at least one binding owned by that RFC. A Clause target MUST select Cases with a matching requirement ref. A Case target MUST select that Case. A Guard target MUST select Cases containing that Guard ID. Every selected Case record MUST retain all of its requirement and Guard bindings. An unknown or unsupported target MUST produce a diagnostic and a non-zero exit status.

Each requirement binding MUST derive one requirement-applicability value:

• provisional when its owning RFC is draft, the Clause is active, and the binding version equals the RFC current version;
• candidate when its owning RFC is normative in spec, the Clause is active, the Clause has a since version, and the binding version equals the RFC current version;
• current when its owning RFC is normative in impl, test, or stable, the Clause is active, the Clause has a since version, and the binding version equals the RFC current version; or
• stale otherwise.

A Case requirement_applicability value MUST be stale when any binding is stale. Otherwise it MUST be provisional when any binding is provisional. Otherwise it MUST be candidate when any binding is candidate. Otherwise it MUST be current. This value describes only the relationship to RFC versions and Clause lifecycle state. It MUST NOT imply that the path content, selector, Guard command, or execution result is current or valid.

The logical result MUST be one collection of Case records. Each record MUST contain id, title, tags, path, selector, requirements, guards, and derived requirement_applicability. Each requirement record MUST contain ref, version, and its derived requirement_applicability. The command MUST NOT label any Case, Clause, or Guard as covered, passed, conformant, or evidenced.

JSON output MUST encode the logical result as an object with a cases array. Table output MUST expose the same Case records in human-readable form. Cases MUST be sorted by ID. Tags and Guards MUST be unique and lexicographically sorted. Requirement records MUST be unique by ref and sorted by ref and then version.

The command MUST support table and json output as a scoped exception to RFC-0002:C-OUTPUT-FORMAT. In a TTY the default MUST be table; outside a TTY the default MUST be json.

The command MUST validate the complete Conformance Case graph before emitting data. Structural errors MUST produce a non-zero exit status and no partial result. Stale, candidate, or provisional bindings and Cases without Guards MUST remain successful trace results.

Rationale: A single Case-oriented result is sufficient to derive every reverse relationship without materializing conflicting graph projections. Explicit applicability and vocabulary keep a declared mapping from being mistaken for execution evidence.

Since: v0.1.0

Changelog

v0.1.1 (2026-07-27)

Keep Case mutations local and recoverable

Fixed

• Limit Case mutation validation to the target and its direct dependencies

v0.1.0 (2026-07-27)

Define version-aware current Conformance Cases and declared traceability

Added

• Conformance Case resource definition
• Canonical Conformance Case command and edit surface
• Case-owned Clause and Guard traceability bindings
• Version-aware declared trace query and derived applicability states

RFC-0009: Source Scan Selection and Ignore Semantics

Version: 0.3.0 | Status: normative | Phase: stable Owners: @govctl-org

References: RFC-0002

1. Summary

[RFC-0009:C-SUMMARY] Source Scan Model (Informative)

Source reference scanning has two independent path-selection layers. The source-scan include list defines the positive scan domain. Repository .gitignore files and governance-specific .govignore files define traversal exclusions and explicit re-inclusions. Keeping these layers separate lets projects reuse established ignore policy, override it for governance evidence, and avoid enumerating excluded directory trees.

Since: v0.1.0

2. Specification

[RFC-0009:C-SOURCE-SELECTION] Source Selection (Normative)

When source_scan.enabled is false, source reference validation MUST NOT enumerate project source paths.

When source reference validation is enabled, a regular file is eligible for content scanning only when its normalized project-relative path matches at least one source_scan.include entry and its final ignore decision is not excluded. Normalized paths MUST use / as the separator, MUST omit a leading ./, and MUST be matched case-sensitively on every platform.

Each include entry represents one positive Git gitignore path pattern evaluated from the project root. A leading / anchors the pattern to the project root. A pattern with no / MUST match at any depth. A trailing / MUST select regular-file descendants of a matching directory. An empty entry or an unescaped leading ! MUST be rejected. Because include entries are configuration values rather than ignore-file lines, a leading # MUST be treated as a pattern character rather than a comment marker. Git escaping and wildcard forms, including *, ?, character classes, and **, MUST retain their gitignore meanings.

An empty include list MUST select no files. An ignore re-inclusion MUST NOT admit a file that is outside the positive include domain.

Since: v0.1.0

[RFC-0009:C-IGNORE-RULES] Ignore Sources and Precedence (Normative)

Source traversal MUST evaluate .gitignore and .govignore files located at the project root and in reached descendant directories. Both file types MUST use Git gitignore pattern syntax, including comments, escaping, directory-only patterns, ordered matches, and ! re-inclusion. Matching MUST use normalized project-relative paths and MUST NOT depend on whether a path is tracked by Git or whether the project root is a Git repository.

When matching rules conflict, a matching .govignore rule MUST take precedence over a matching .gitignore rule. Within one file type, a rule in a deeper directory MUST take precedence over a rule inherited from an ancestor directory. Within one ignore file, the last matching rule MUST win.

When the winning rule is a re-inclusion, the path MUST become non-excluded unless an ancestor remains excluded. Otherwise, a winning exclusion MUST keep the path excluded. After ignore resolution, source_scan.include MUST be applied only to decide whether a non-excluded regular file is eligible for content scanning; it MUST NOT prevent traversal through a non-excluded directory.

Source traversal MUST NOT consult ignore rules outside the project root, user-level or global Git ignore configuration, .git/info/exclude, or generic .ignore files. A path MUST NOT be excluded solely because its name is hidden.

Since: v0.1.0

[RFC-0009:C-TRAVERSAL] Traversal and Pruning (Normative)

The final ignore decision for a reached directory MUST be evaluated before enumerating its child entries. When the final decision excludes a directory, source traversal MUST prune the directory without enumerating its descendants.

A re-inclusion that targets a descendant of an excluded directory MUST have no effect unless every excluded ancestor is also re-included by rules available from reached directories. Ignore files beneath a pruned directory MUST NOT be read and MUST NOT re-include that directory or its descendants.

Source traversal MUST NOT follow symbolic links.

While source scanning is enabled, an invalid include rule, an unreadable or invalid ignore file discovered in a reached directory, an error while traversing a directory that was not pruned, or a read or decoding error for a selected regular file MUST produce a validation diagnostic. Source reference validation MUST NOT report success after such an error.

A directory named .git MUST be treated as repository metadata and pruned before its child entries are enumerated, regardless of source_scan.include or ignore-file rules.

Since: v0.1.0

[RFC-0009:C-IGNORE-MIGRATION] Ignore Configuration Migration (Normative)

Project schema version 5 MUST establish the source-selection and ignore contract in this RFC. Normal project commands other than govctl migrate that load a version 4 project MUST reject the project without mutation and instruct the user to run govctl migrate. Project-independent commands MUST NOT require repository migration. Migration from version 4 to version 5 MUST follow the transactional and dry-run behavior in RFC-0002:C-GLOBAL-COMMANDS.

The version 5 configuration MUST remove source_scan.exclude. When that legacy list is non-empty, migration MUST place each entry as one root .govignore rule, preserving array order and placing the migrated rules before any pre-existing .govignore content. A leading ! or # that was a literal character in a legacy entry MUST be escaped when written as an ignore-file rule. A legacy entry containing a carriage return or line feed MUST cause migration to fail without mutation and identify that entry.

Pre-existing .govignore content MUST remain byte-for-byte unchanged after the inserted migration block. The version 5 source-scan migration step MUST NOT modify .gitignore; independent project-support synchronization required by RFC-0002:C-GLOBAL-COMMANDS MAY modify .gitignore in the same govctl migrate invocation.

Migrated entries adopt Git gitignore matching semantics in version 5. Migration MUST NOT claim that their match sets remain identical to the legacy glob matcher. govctl migrate --dry-run MUST show the resulting configuration and .govignore changes before they are applied.

When the legacy list is empty, migration MUST remove the field without creating .govignore. A version 5 project without a .govignore file MUST be valid and MUST behave as though it has no governance-specific ignore rules. A version 5 configuration that contains source_scan.exclude MUST be rejected without mutation, and the diagnostic MUST identify the unsupported field.

Since: v0.1.0

[RFC-0009:C-REFERENCE-REPORTING] Source Reference Reporting (Normative)

A configured source_scan.pattern MUST compile successfully and MUST define capture group 1 as the artifact-reference target. govctl check MUST report E0501 when either condition is not met, whether or not source-file traversal is enabled. Every full match MUST produce a present, non-empty capture group 1; otherwise source scanning MUST report E0501 and MUST NOT treat that match as a reference.

A diagnostic about an unknown or outdated detected source reference MUST identify the normalized project-relative source path and the one-based line and byte-column position at which capture group 1 starts.

Source-reference diagnostics MUST be ordered by ascending normalized path, line, and byte column, with diagnostic code and captured target as ascending tie-breakers. Diagnostics with the same code, normalized path, capture-start position, and captured target MUST be emitted once.

Since: v0.2.0

Changelog

v0.3.0 (2026-07-30)

Exclude Git metadata from source traversal

Changed

• Prune .git directories before enumerating their contents

v0.2.0 (2026-07-30)

Make source-reference diagnostics precise and deterministic

Added

• Define reference-pattern validation and source locations

Changed

• Order and deduplicate source-reference diagnostics

v0.1.1 (2026-07-30)

Close source traversal failure gaps

Fixed

• Treat selected source read and decoding failures as validation errors

v0.1.0 (2026-07-29)

Initial draft

RFC-0010: Multi-workspace coordination for parallel agents

Version: 0.2.0 | Status: normative | Phase: impl Owners: @govctl-org Tags: collaboration

References: RFC-0004, RFC-0002

1. Summary

[RFC-0010:C-SUMMARY] Summary (Informative)

This RFC specifies how govctl coordinates governance work when one repository clone hosts multiple concurrent working trees — git worktrees or jj workspaces — driven by parallel agents.

Scope: Applies to every govctl command invocation in any working tree of a clone that hosts more than one working tree. It covers command scope classification, a shared coordination registry, cross-workspace ID reservation, exclusive claims for version-semantics operations, and cross-workspace presence visibility.

Backward compatibility: Single-checkout repositories are unaffected: with exactly one working tree, coordination reduces to the behavior defined by RFC-0004. Without version control, multiple workspaces cannot exist, so commands silently behave as they always have. One deliberate exception: because allocation consults shared version-control history, identifiers of deleted artifacts are not reused, which protects historical references from dangling onto unrelated successors.

Specification outline: Commands are classified as workspace, branch-content, or trunk scoped, and trunk-scoped commands are refused outside the primary workspace. A per-clone coordination registry holds ID reservations, artifact claims, and presence records. ID reservation makes cross-branch ID collisions impossible by construction; claims make concurrent version-semantics changes to the same RFC visible and serialized; presence lets agents in one workspace see active work in others.

Rationale: Governance artifacts remain versioned with the branch so that changes travel through pull request review, while coordination state — which is live, operational, and not reviewable — is shared per clone. Without this split, parallel agents in separate worktrees collide on sequential IDs, cannot see each other’s active work, and can silently bump or finalize the same RFC.

Since: v0.1.0

2. Specification

[RFC-0010:C-DEFINITIONS] Definitions (Informative)

Working tree / workspace: A distinct checkout of a repository clone that shares version-control metadata with the clone’s other working trees — a linked git worktree or a jj workspace. A workspace is identified by the absolute path of its working-tree root. Moving or renaming a workspace therefore invalidates its registry records, which expire under the liveness rules below and are recreated by new activity from the moved workspace.

Primary workspace: The working tree designated as the canonical location for trunk-scoped commands. For git, the main working tree (the one containing the repository’s shared metadata directory). For VCS tools whose workspaces are peers, the workspace named by project configuration.

Shared repository storage: Storage provided by the version-control system that is common to every working tree of a clone, such as the git common directory or the jj repository store. It is distinct from any working tree’s checked-out files. Shared version-control history is the commit history recorded in that shared storage and visible to every workspace of the clone.

Coordination registry: Local, per-clone state in shared repository storage that records ID reservations, artifact claims, and presence records. The registry is coordination state, not a governed artifact, and is never committed to version control.

ID reservation: An atomic registry record that binds a not-yet-merged artifact ID to the workspace that generated it. Reservation liveness is defined by RFC-0010:C-ID-RESERVATION through the existence of the artifact file at the owning workspace’s recorded path, not by an activity timestamp.

Artifact claim: An exclusive registry record binding an existing RFC to the workspace performing version-semantics operations on it.

Presence record: A registry record indicating that a workspace is actively working on a specific work item.

Live record: A claim or presence record whose owning workspace path still exists and whose recorded activity has not exceeded the configured inactivity period.

Since: v0.1.0

[RFC-0010:C-COMMAND-SCOPE] Command scope classification (Normative)

Every govctl command that reads or writes governed artifacts or coordination state has exactly one scope: workspace, branch-content, or trunk. This classification applies to every command in the CLI surface defined by RFC-0002, and any command added to that surface MUST be assigned exactly one scope at the time it is added.

Workspace scope. Read-only and local-execution commands such as status, check, list, show, search, verify, describe, claim list, and loop execution. Workspace-scoped commands MUST run in any workspace and MUST NOT mutate governed artifacts. Coordination-state-mutating commands that never touch governed artifacts, such as claim release and claim steal, are branch-content scoped for enforcement purposes but MUST NOT acquire the gov-root write lock.

Branch-content scope. Commands that create or mutate governed artifacts in the invoking workspace’s working tree, including artifact creation, content editing, lifecycle transitions, and rendering. Branch-content commands MUST run in any workspace, subject to the reservation and claim rules of RFC-0010:C-ID-RESERVATION and RFC-0010:C-ARTIFACT-CLAIM.

Trunk scope. Exactly the commands that cut or undo a release or migrate the repository’s governance format are trunk-scoped. A trunk-scoped command invoked outside the primary workspace MUST refuse to execute, MUST leave governed and coordination state unchanged, and MUST report a diagnostic that identifies the primary workspace.

The primary workspace MUST be determined from version-control metadata when the VCS defines a main working tree. Where the VCS treats workspaces as peers, the primary is the workspace named by project configuration, or — absent configuration, for jj — the workspace named default, which jj assigns to the initial workspace of every repository. When version control is present but no primary workspace can be determined, trunk-scoped commands MUST proceed as if the current workspace were primary and MUST emit a warning that trunk-scope enforcement is inactive. Without version control, multiple workspaces cannot exist, so trunk-scope enforcement is inapplicable and commands proceed silently, consistent with RFC-0010:C-REGISTRY degradation.

Rationale: Release cutting, release undo, and format migration rewrite the canonical line of project history and must have a single point of execution, while content work benefits from running wherever the agent’s branch lives. Refusing trunk operations in secondary workspaces replaces an entire class of merge conflicts with an explicit, actionable error. The warning is reserved for the case where enforcement is expected but impossible; a project without version control has no second workspace to protect against. Treating jj’s initial default workspace as the fallback primary mirrors the convention every jj repository already has, so most projects need no configuration at all.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-REGISTRY] Shared coordination registry (Normative)

The coordination registry MUST be stored in shared repository storage so that every workspace of a clone observes and updates the same records. The registry MUST be namespaced per governed project root, so a clone hosting multiple governed projects keeps independent registries.

The registry MUST NOT be stored inside any workspace’s working tree, under the gov root, or under rendered documentation directories. Registry records are local coordination state: they are not governed artifacts, MUST NOT be committed to version control, and MUST NOT be treated as an authoritative source over TOML governance artifacts. The registry MAY inform only coordination-facing output — the presence overlay in govctl status and reservation or claim diagnostics — and MUST NOT alter the parsed content, status fields, or lifecycle state of governed artifacts as loaded from their TOML sources.

Concurrent registry updates from parallel processes across workspaces MUST be atomic: two concurrent invocations MUST NOT produce lost, duplicated, or interleaved registry records. This coordination mechanism is distinct from, and does not replace, the concurrency mechanism required by RFC-0004 for mutations of the gov tree. Registry access MUST NOT block read-only commands.

Because multiple working trees are themselves a version-control facility, a directory without version control cannot host more than one workspace. Commands in such a directory MUST silently use single-checkout behavior; coordination is not merely inactive but inapplicable, and no warning is emitted. Degraded detection MUST resolve toward caution: when version-control metadata is present but unreadable, or its presence cannot be reliably determined, commands MUST behave as if version control were present and shared storage were unavailable — that is, degrade with a warning — rather than taking the silent no-VCS path. Under the same caution rule, a registry write failure or detected registry corruption with version control present MUST degrade to single-checkout behavior and MUST emit a warning, since the clone may host other workspaces whose coordination state is now stale. Registry loss or corruption MUST NOT make governed artifacts unusable; the consequence is limited to losing the uniqueness and visibility guarantees of this RFC until the registry is repopulated by new activity.

Rationale: Placing coordination state in VCS-shared storage gives every workspace of a clone a single rendezvous point without a daemon or network service, while keeping the working tree — and therefore pull requests — free of operational state. Because the storage is VCS metadata rather than a checked-out file, the registry requires no ignore rules. Warning on registry failure when version control is present surfaces a real coordination gap, while staying silent without version control avoids punishing single-checkout projects for a facility they cannot use.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-ID-RESERVATION] Cross-workspace ID reservation (Normative)

A branch-content command that creates a governed artifact with a generated identifier MUST atomically reserve that identifier in the coordination registry as part of creation, and the reservation MUST record the owning workspace.

Two artifact creations in different workspaces of the same clone MUST NOT be assigned the same identifier, regardless of when their respective branches merge. This extends the concurrent-invocation uniqueness required by RFC-0004:C-CONCURRENT-WRITE from same-checkout processes to across-workspace sequences. Across clones — where no shared registry exists — identifier strategies that derive collision-safe identifiers from author identity or randomness remain the available mitigation.

Identifier allocation MUST take as its input the union of three witnesses: the identifiers present in the invoking workspace’s gov tree, the identifiers bound by live reservations in the registry, and the identifiers recorded in the clone’s shared version-control history. An identifier is recorded in shared history when a governed-artifact source path bearing that identifier exists in any commit reachable from the clone’s shared storage. Allocation MUST choose the next identifier monotonically within the numbering scheme of the artifact type, so identifiers stay sortable and predictable for humans. Because shared history is visible to every workspace of the clone, a merged artifact witnesses its identifier even to workspaces on stale branches.

A reservation for a newly created artifact MUST be honored as live while the artifact file exists at the owning workspace’s recorded path. The reservation MAY be discarded only once the artifact is recorded in the clone’s shared version-control history, from which point the history entry is the uniqueness witness for every workspace.

Rationale: Sequential identifiers are a deliberate readability choice for RFCs and ADRs. Reservation preserves that choice under parallel branch work by moving the collision point from merge time — where renumbering breaks references — to creation time, where an atomic shared record costs nothing. Defining the allocation input as local tree plus reservations plus shared history keeps the uniqueness guarantee intact across the reservation’s entire lifecycle, including after its discard.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-ARTIFACT-CLAIM] Artifact claims for version-semantics operations (Normative)

Operations that change an RFC’s version semantics — version bump, finalization, phase advancement, deprecation, and supersession — MUST acquire an exclusive artifact claim before mutating, on every RFC whose version-semantics fields the operation mutates. A supersession therefore requires claims on both the superseding and the superseded RFC. When another workspace holds a live claim on a required RFC, the command MUST fail without mutating anything, and its diagnostic MUST identify the claiming workspace.

Commands that edit an RFC’s content without changing version semantics — including clause authoring — MUST NOT be blocked by a claim. When a live claim held by another workspace exists, they MUST emit a non-blocking warning naming the claiming workspace, so overlapping intent is visible without forbidding parallel work on independent clauses.

A claim MUST record the owning workspace and a last-activity timestamp. Any govctl invocation that writes coordination state in the claiming workspace SHOULD refresh that workspace’s claim and presence timestamps; read-only invocations MUST NOT refresh, so that they never become writers. A claim whose owning workspace no longer exists, or whose last activity exceeds a configurable inactivity period, MUST be treated as expired and MUST NOT block operations.

Users MUST be able to explicitly release a claim and to take over a claim held by another workspace. Every takeover MUST be recorded in the registry as an audit event that names both workspaces involved, and audit events MUST be retained beyond the expiry of the claim they transferred, so that claim transfers remain auditable after the fact.

Rationale: Version-semantics operations on one RFC cannot merge meaningfully when performed on two branches at once — both would edit the same version and changelog fields — so they are serialized by an exclusive claim. Content edits to independent clause files merge cleanly, so they receive visibility rather than exclusion. Refresh is scoped to coordination-writing invocations so that read-only commands never take the registry lock, per RFC-0010:C-REGISTRY.

Tags: collaboration

Since: v0.1.0

[RFC-0010:C-PRESENCE] Cross-workspace presence (Normative)

Activating a work item — or creating one directly in active status — in any workspace MUST register a presence record in the coordination registry naming the work item and the owning workspace.

govctl status MUST surface work items with live presence records owned by other workspaces of the clone, identifying both the work item and the owning workspace, so an agent can tell which items are being worked on elsewhere before starting new work.

Presence records follow the liveness rules of RFC-0010:C-ARTIFACT-CLAIM: they record a last-activity timestamp, are refreshed by invocations in the owning workspace, and expire after the same configurable inactivity period.

Presence is advisory visibility, not exclusion: it MUST NOT block activating or editing the same work item in another workspace. Where hard coordination for work items is wanted, projects use work item dependency and assignment workflows rather than presence.

Rationale: The common multi-agent failure is two agents unknowingly doing the same work. A live, shared view of active work removes the invisibility without turning advisory information into a locking protocol.

Tags: collaboration

Since: v0.1.0

Changelog

v0.2.0 (2026-09-08)

Clarify trunk scope and workspace detection

Added

• Name release undo in the trunk-scoped command set
• Classify claim list as workspace-scoped and claim release/steal as lock-free branch-content commands
• Treat jj’s default workspace as the fallback primary when no primary is configured

Changed

• Scope claim and presence timestamp refresh to coordination-writing invocations so read-only commands never write

v0.1.0 (2026-09-08)

Initial normative version

ADR-0001: Use TOML for ADRs and Work Items

Status: superseded | Date: 2026-01-17 Superseded by: ADR-0034

Tags: schema

References: RFC-0000:C-ADR-DEF, RFC-0000:C-WORK-DEF

Context

ADRs and Work Items need a human-readable, machine-parseable format. JSON is verbose and hard to edit manually. YAML has implicit typing issues. TOML provides explicit typing, clean multiline strings, and good tooling support.

Decision

Use TOML for ADRs and Work Items instead of JSON. Structure follows [govctl] metadata section and [content] body section. This aligns with Rust ecosystem conventions (Cargo.toml).

Consequences

Positive: Easier manual editing, cleaner diffs, natural multiline support. Negative: Different format from RFC clauses (which remain JSON for richer structure). Migration: Existing JSON-based work items would need conversion.

ADR-0002: Fix artifact lifecycle design flaws

Status: accepted | Date: 2026-01-17

Tags: lifecycle

References: RFC-0000

Context

Analysis of the artifact lifecycle state machines revealed several design flaws:

1. Clause kind vs status duplication: The kind enum includes deprecated alongside normative and informative, but status also has deprecated. This creates confusion about where deprecation state belongs.

2. ADR missing rejected state: The ADR lifecycle is proposed → accepted → superseded. If a proposal is rejected rather than accepted, there is no state to record this outcome. The alternative is leaving it as proposed forever or deleting it, both of which lose information.

3. Work Item forced activation before cancellation: The lifecycle queue → active → done|cancelled implies you must start work before abandoning it. This is illogical - planned work can be abandoned before starting.

4. RFC status×phase constraint rules undocumented: The 3×4 matrix of valid/invalid status×phase combinations exists implicitly but is not formally documented in SCHEMA.md.

Decision

We will fix all four lifecycle design flaws:

1. Remove deprecated from Clause kind: The kind field should only contain semantic categories (normative, informative). Deprecation is a lifecycle state that belongs in status.

2. Add rejected to ADR lifecycle: The new lifecycle becomes:

   proposed → accepted → superseded
            → rejected
   

   This allows recording when a proposal was considered but declined.

3. Allow Work Item queue → cancelled: The new lifecycle becomes:

   queue → active → done
       ↘        ↘ cancelled
   

   Work can be abandoned at any stage.

4. Document RFC constraint rules: Add explicit invariant rules to SCHEMA.md stating when status×phase combinations are forbidden.

Consequences

Positive:

• Cleaner separation of concerns (kind = category, status = lifecycle)
• Complete lifecycle coverage for all artifact types
• Explicit rules prevent confusion about valid state combinations

Negative:

• Existing tools validating kind: deprecated will need updating
• Schema version bump required for breaking changes

Migration:

• Any clause with kind: deprecated should change to kind: normative, status: deprecated
• Currently no such clauses exist in the codebase

ADR-0003: Deterministic hash signatures for rendered projections

Status: accepted | Date: 2026-01-17

Tags: validation

References: RFC-0000

Context

govctl renders markdown files from authoritative JSON/TOML sources (RFCs, ADRs, Work Items). These rendered markdown files are projections — read-only views intended for human consumption.

Problem: Without a mechanism to detect tampering, someone could edit docs/rfc/RFC-0000.md directly. This edit would:

1. Be overwritten on next govctl render
2. Create confusion about which version is authoritative
3. Violate the Single Source of Truth (SSOT) principle

We need a mechanism to:

• Mark rendered files as generated (not authoritative)
• Detect when a rendered file has been edited directly
• Ensure verification is deterministic (same source always produces same hash)

Decision

Implement deterministic hash signatures embedded in rendered markdown.

Signature Format:

<!-- GENERATED: do not edit. Source: RFC-0000 -->
<!-- SIGNATURE: sha256:<64-hex-chars> -->

Hash Computation:

1. Collect all source JSON content (RFC metadata + clauses, or ADR/Work Item TOML)
2. Canonicalize JSON/TOML: sort object keys recursively, normalize whitespace
3. For RFCs: sort clauses by clause_id before hashing
4. Compute SHA-256 of the canonical representation
5. Include a signature version prefix for future-proofing

Determinism Requirements:

• Object keys sorted alphabetically at all nesting levels
• Arrays preserve order (only objects get key-sorted)
• Consistent string escaping and number formatting
• No dependency on file modification times or filesystem order

Verification:

• govctl check extracts signature from rendered markdown
• Recomputes hash from current source files
• Reports mismatch as a diagnostic error

Consequences

Positive:

• Enforces “edit the source, not the projection” discipline
• Tampered markdown is detected automatically by govctl check
• Deterministic hashes enable reproducible builds
• Clear provenance: every rendered file traces back to its source

Negative:

• Existing rendered markdown will fail verification until re-rendered
• Minor source reformatting (whitespace) changes the hash
• Adds complexity to the render pipeline

Migration:

• Run govctl render to regenerate all markdown with signatures
• Commit the updated files

ADR-0004: Adopt Keep a Changelog format for RFC changelogs

Status: accepted | Date: 2026-01-17

Tags: release

References: RFC-0000

Context

RFC changelogs use a flat changes array. This makes it difficult to categorize changes by type (additions, fixes, removals). The Keep a Changelog format (keepachangelog.com) is a widely-adopted standard that organizes changes into semantic categories aligned with semver.

Decision

Replace the flat changes array with categorized arrays: added, changed, deprecated, removed, fixed, security. Keep summary field as optional notes. Migrate existing RFC-0000 changelog (trivial: one entry).

Consequences

Positive: Standard format, better scanability, semver-aligned categories. Negative: More verbose schema, breaking change to ChangelogEntry model. Migration cost is minimal (RFC-0000 has only one entry).

ADR-0005: CLI output color scheme and formatting

Status: accepted | Date: 2026-01-17

Tags: cli

References: RFC-0000

Context

CLI output uses plain text with no visual hierarchy. Users cannot quickly distinguish success from failure, or identify important values. Status messages blend together making output hard to scan.

Decision

Adopt semantic color scheme: Green for success, Red for errors, Yellow for warnings, Cyan for paths/IDs, Bold for emphasis. Use owo-colors crate (zero-cost, no deps). Auto-detect terminal color support. All output via ui module for consistency.

Consequences

Positive: Better UX, faster scanning, clearer status. Negative: One new dependency (owo-colors). Migration: All eprintln! calls routed through ui module.

ADR-0006: Global dry-run support for content-modifying commands

Status: accepted | Date: 2026-01-17

Tags: cli

References: RFC-0000:C-WORK-DEF, ADR-0019

Context

All content-modifying commands (new, set, add, remove, edit, tick, bump, finalize, advance, accept, deprecate, supersede, move) write files immediately with no way to preview changes. Only render commands support –dry-run. Users and agents need a way to preview what changes will be made before committing to disk, especially for destructive or complex operations.

Decision

Add global -n/–dry-run flag at CLI level. Create WriteOp enum with Preview/Execute variants in write.rs. All write functions accept WriteOp. In Preview mode: serialize, display via ui::dry_run_preview, skip fs::write. Read-only commands ignore the flag.

Consequences

Positive: Unified dry-run UX, follows Unix -n convention, DRY write logic. Negative: Signature changes for write functions. Migration: Update all write callsites to use WriteOp.

ADR-0007: Ergonomic array field matching for remove and tick commands

Status: superseded | Date: 2026-01-17 Superseded by: ADR-0037

Tags: editing

References: RFC-0000:C-WORK-DEF, RFC-0000:C-ADR-DEF

Context

The remove command requires exact string match, which is fragile for long strings like URLs. The tick command uses substring matching but remove does not. Checklist fields (acceptance_criteria, decisions, alternatives) require separate semantics from string fields, leading to confusion about when to use remove vs tick.

Decision

Unify matching semantics: (1) Default to case-insensitive substring matching for remove and tick. (2) Add –exact flag for exact matching. (3) Add --at <index> for positional removal. (4) Add –regex flag for pattern matching. (5) Add –all flag for bulk removal. (6) Single match proceeds; multiple matches error with guidance. (7) remove works on all array types including checklists; tick only changes status.

Consequences

Positive: Ergonomic default matching, safe bulk operations, unified semantics. Negative: Breaking change for scripts relying on exact match. Migration: Existing exact-match callers should add –exact flag.

ADR-0008: Add refs field to RfcSpec for artifact cross-referencing

Status: accepted | Date: 2026-01-17

Tags: schema

References: RFC-0000

Context

RFCs are the supreme governance documents in govctl, yet they cannot formally reference other artifacts (ADRs, other RFCs, work items). Meanwhile, ADRs and Work Items both have a refs field for cross-referencing.

This asymmetry creates problems:

1. RFCs cannot declare dependencies on ADRs that informed their design
2. No way to trace which ADRs led to an RFC’s creation
3. Validation cannot check RFC references for consistency
4. Impact analysis for deprecation is incomplete

The existing pattern in AdrMeta and WorkItemMeta is: refs: Vec<String> with validation against known artifact IDs.

Decision

Add refs field to RfcSpec following the same pattern as AdrMeta and WorkItemMeta:

1. Add refs: Vec<String> to RfcSpec model (serde skip_serializing_if empty)
2. Add diagnostic code E0105RfcRefNotFound for validation errors
3. Extend validate_artifact_refs() to include RFC refs validation
4. Support add/remove/get refs operations in edit commands for RFCs
5. Validate RFC supersedes field against known RFCs (currently unvalidated)

This creates consistency across all artifact types and enables complete cross-reference tracking.

Consequences

Positive:

• RFCs can now reference ADRs, other RFCs, and work items
• Complete artifact graph for impact analysis
• Consistent API across all artifact types
• Existing RFCs remain valid (refs is optional, defaults to empty)

Negative:

• Minor schema change to RfcSpec
• Slightly more validation overhead on check

Neutral:

• Existing RFCs do not need migration (empty default)

ADR-0009: Configurable source code reference scanning

Status: superseded | Date: 2026-01-17 Superseded by: ADR-0059

Tags: validation

References: RFC-0000

Context

Source code often contains references to governance artifacts (RFCs, clauses, ADRs) in comments. These references can become stale when artifacts are deprecated, superseded, or renamed.

Currently govctl validates internal artifact references (refs fields) but has no mechanism to detect broken references in source code comments. This creates a gap where documentation in code can drift from the actual governance state.

neotex-spec implements this via a hardcoded comment scanning pattern, but govctl needs a generalized solution with configurable patterns to work across different projects and conventions.

Decision

Add configurable source code scanning with:

1. New [source_scan] config section with:

   • enabled: bool (default false)
   • roots: Vec<PathBuf> (directories to scan)
   • exts: Vec<String> (file extensions to include)
   • pattern: String (regex with capture group for artifact ID)

2. Default pattern matches RFC-0001:C-NAME and ADR-0001 style references

3. Scanner walks configured directories, applies pattern, validates extracted IDs against ProjectIndex

4. New diagnostics: E0107SourceRefUnknown (error), W0107SourceRefOutdated (warning for deprecated/superseded)

5. Scanner runs during ‘govctl check’ when source_scan.enabled = true

Consequences

Positive:

• Dead link detection in source code comments
• Configurable pattern supports different project conventions
• Disabled by default - opt-in for projects that want it
• Catches outdated references to deprecated/superseded artifacts

Negative:

• Adds walkdir dependency
• Additional check time when scanning large codebases

Neutral:

• Pattern configuration requires regex knowledge
• Projects must explicitly enable and configure

ADR-0010: Validate work item descriptions for placeholder content

Status: accepted | Date: 2026-01-17

Tags: validation

References: RFC-0000:C-WORK-DEF

Context

Work items are created with a placeholder description template: “Describe the work to be done. What is the goal? What are the acceptance criteria?” This placeholder is meant to be replaced with actual content, but 21 of 24 existing work items still have this placeholder text.

Empty or placeholder descriptions provide no value for audit trails, make it hard to understand what was actually done, and defeat the purpose of structured governance.

Decision

Add a warning diagnostic (W0106) for work items with placeholder or empty descriptions.

Detection patterns:

1. Description matches the exact template text
2. Description is empty or whitespace-only
3. Description contains only generic phrases like “TODO”, “TBD”, “Fill in later”

This is a warning (not error) because:

• Existing work items should not block govctl check
• It’s advisory during development, not a hard gate
• Users can address warnings incrementally

Consequences

Positive:

• Encourages meaningful documentation of completed work
• Improves audit trail quality
• Catches forgotten placeholders before they become permanent

Negative:

• Existing 21 work items will trigger warnings until fixed
• Minor noise during govctl check until addressed

Migration: Fix existing work items by adding meaningful descriptions based on their titles and acceptance criteria.

ADR-0011: Inline reference expansion in rendered content

Status: accepted | Date: 2026-01-17

Tags: editing

References: RFC-0000

Context

Content fields (description, context, decision, consequences) are rendered as-is with no link expansion. The refs field gets expanded to markdown links, but inline references like [RFC-0000](../rfc/RFC-0000.md) in text remain as literal strings.

This creates an inconsistency:

1. The source_scan feature uses [[artifact-id]] pattern to detect references in source code
2. Users might expect the same pattern to work in content fields
3. Without expansion, content authors must write full markdown links manually

The source_scan config already defines a customizable pattern field for reference format.

Decision

Add inline reference expansion to content fields during rendering:

1. Use the same pattern from source_scan.pattern config (defaults to [[RFC-NNNN]] format)
2. Expand matched references using existing ref_link() function
3. Apply to: description, context, decision, consequences, notes, acceptance_criteria text
4. Pattern is evaluated at render time, so config changes apply on next render

This creates consistency between source code scanning and content rendering — the same reference format works everywhere.

Consequences

Positive:

• Inline references in content become clickable links
• Consistent with source_scan pattern format
• No new config needed (reuses source_scan.pattern)
• Works with custom patterns if configured

Negative:

• Couples rendering to source_scan config (even if source_scan.enabled is false)
• Literal [[text]] in content will be matched if it looks like an artifact ID

Migration: Existing content with literal [[...]] that happens to match artifact patterns will now become links. This is likely the desired behavior.

ADR-0012: Prefix-based changelog category parsing

Status: accepted | Date: 2026-01-17

Tags: release

References: ADR-0013

Context

The govctl bump command supports adding changelog entries via -c flags, but all changes are hardcoded to the added category. The ChangelogEntry model supports 6 categories (added, changed, deprecated, removed, fixed, security) per Keep a Changelog format, but users must manually edit JSON to use any category other than added.

Decision

Parse conventional-commit-style prefixes from change strings to route to the correct changelog category. Supported prefixes: add:, fix:, changed:, deprecated:, removed:, security:. Unknown prefixes produce a validation error. No prefix defaults to added for backward compatibility.

Example: govctl bump RFC-0001 --patch -m "Bug fixes" -c "fix: memory leak" -c "security: patched CVE"

Consequences

Users can populate all changelog categories via CLI without JSON editing. The prefix syntax follows conventional commits, reducing learning curve. Invalid prefixes are caught early with helpful error messages listing valid options.

ADR-0013: Add category field to acceptance criteria for changelog generation

Status: accepted | Date: 2026-01-17

Tags: schema

References: ADR-0012

Context

Work items track implementation work (features, fixes, refactoring), but lack categorization that maps to Keep a Changelog format. RFC changelog entries already use Keep a Changelog categories (Added, Changed, Deprecated, Removed, Fixed, Security). To generate a repo-level CHANGELOG.md from completed work items, we need the same categorization. Acceptance criteria are the natural atomic unit for changelog entries - each criterion represents one deliverable.

Decision

Add a category field to ChecklistItem (acceptance criteria) using the existing ChangelogCategory enum (added, changed, deprecated, removed, fixed, security). Default to added for backward compatibility. Reuse ADR-0012 prefix parsing: govctl add WI-xxx acceptance_criteria "fix: memory leak" parses to category=fixed, text="memory leak". This consolidates ChangelogCategory from write.rs into model.rs for reuse across RFC changelogs and work item criteria.

Consequences

Acceptance criteria can be grouped by category when rendering CHANGELOG.md. Each criterion becomes one changelog entry. Work items can span multiple categories without being split. Existing work items remain valid (criteria default to added). Single ChangelogCategory enum used for both RFC changelog entries and work item criteria.

Alternatives Considered

Add category field to WorkItemMeta (work-item level) (rejected)

Add category field to ChecklistItem (criterion level) with prefix parsing (accepted)

ADR-0014: Release management with releases.toml

Status: accepted | Date: 2026-01-17

Tags: release

References: ADR-0013, RFC-0000:C-WORK-DEF

Context

To generate a CHANGELOG.md from work items, we need version information. Work items have completed dates but no version. Version is a release-time concept, not a work-time concept. We need a way to track which work items belong to which release without mutating completed work items.

Decision

Store release history in a single gov/releases.toml file with explicit work item references:

[[releases]]
version = "0.2.0"
date = "2026-01-17"
refs = ["WI-YYYY-MM-DD-029", "WI-YYYY-MM-DD-008"]

The govctl release <version> command collects all done work items not yet in any release and adds them to a new release entry. The govctl render changelog command generates CHANGELOG.md grouped by release version and category.

Consequences

Completed work items remain immutable. Explicit refs list eliminates ambiguity about release membership. Single file is simpler than per-release artifacts. Unreleased work items appear under [Unreleased] section in changelog.

Alternatives Considered

Add version field to work items after release (rejected)

Store releases in single gov/releases.toml with explicit refs (accepted)

ADR-0015: Context-aware self-describing CLI for agent discoverability

Status: superseded | Date: 2026-01-18 Superseded by: ADR-0058

Tags: cli

References: RFC-0000

Context

AI coding agents (Claude, Cursor, Codex, etc.) can invoke shell commands, making govctl immediately usable. However, agents lack semantic understanding of when to use which command and why.

User feedback: “I need to tell the agent in my prompt what this tool is and when to run it.”

Current solutions:

1. MCP (Model Context Protocol) — adds structured tool definitions, but requires server setup, process management, and creates a parallel interface to maintain
2. Agent guide files (.claude/CLAUDE.md) — static, requires manual updates, doesn’t reflect current project state
3. --help output — describes syntax, not semantics or workflow context

The core problem: discovery and context-awareness, not invocation. Agents need to understand govctl’s philosophy, command purposes, and what actions are relevant given current project state.

Decision

Add a govctl describe command with two modes:

1. Static mode (default):

govctl describe --json

Outputs machine-readable JSON containing:

• version: govctl version
• purpose: one-line description of govctl’s role
• philosophy: core principles (RFC supremacy, phase discipline)
• commands[]: for each command:
  • name: command name (e.g., “new rfc”, “advance”)
  • purpose: what it does
  • when_to_use: semantic guidance on when to invoke
  • example: concrete usage
  • prerequisites: what must be true before running
• workflow: typical command sequence for common tasks

2. Context-aware mode:

govctl describe --context --json

Reads current project state and outputs:

• project_state: current RFCs, ADRs, work items with their statuses/phases
• suggested_actions[]: contextually relevant commands with reasons
  • Example: “RFC-0001 is in impl phase. If implementation complete, run govctl advance RFC-0001 test”
• warnings[]: governance issues detected (stale items, blocked transitions)

Implementation:

• Command metadata derived from existing clap #[command(about = "...")] attributes where possible
• Semantic guidance (when_to_use) defined as static data
• Context mode reuses status and list logic for project state
• Output format follows JSON Schema for predictable parsing

Consequences

Positive:

• Agents gain semantic understanding without MCP complexity
• Single interface (CLI) — no parallel implementation to maintain
• Context-aware mode reduces agent trial-and-error
• Works with any shell-capable agent (not limited to MCP-compatible tools)
• Self-documenting: govctl describe output stays in sync with actual commands
• Distribution unchanged: cargo install govctl is all users need

Negative:

• Additional ~200-300 lines of code for command metadata and describe logic
• Semantic guidance (when_to_use) must be manually authored and maintained
• JSON output format becomes a compatibility surface (changes need care)

Neutral:

• Agents must call govctl describe once per session (cacheable)
• Plain --help remains available for human users
• Does not preclude future MCP integration if demand materializes

Comparison to MCP:

ADR-0016: Allow RFC amendments via versioning during implementation

Status: accepted | Date: 2026-01-19

Tags: lifecycle

References: RFC-0001, ADR-0004

Context

Real-world governance experience from the neotex-v2 project shows that RFCs often need amendments during implementation. This conflicts with the current govctl mental model that treats normative status as “frozen” — the documentation (CLAUDE.md:79) states “normative: Frozen. Implementation MUST conform.”

This creates a false dichotomy:

• Theory: Spec everything perfectly, then implement
• Practice: You discover spec bugs, ambiguities, and wrong assumptions during implementation

The problem is not with RFC-0001:C-RFC-STATUS (which only says “normative” means “binding”), but with the interpretation that “binding” implies “immutable.” This forces workarounds: draft ADRs, inline comments, or ignoring governance entirely.

The infrastructure for RFC evolution already exists: versioning (version field) and changelog (changelog array per ADR-0004). We’re just not using it for governance.

Decision

Clarify the semantics of “normative”:

• normative means binding (code must conform to current version)
• normative does NOT mean frozen (spec can evolve with version bumps)

Operational changes:

1. Remove “normative = frozen” messaging from all documentation
2. Document that normative RFCs MAY be amended via version bumping
3. When amending a normative RFC:
   • Bump version according to semantic versioning
   • Add changelog entry documenting the change
   • Rationale and audit trail live in git/jj history

Precedent: Linux kernel APIs are both binding (drivers must conform) and evolving (with deprecation, versioning, compatibility) simultaneously.

Consequences

Easier:

• Amending RFCs during implementation (matches real workflow)
• Iterative spec refinement (discover-fix-document cycle)
• Honest governance (no pretending specs are perfect)

More difficult:

• Reviewers must check RFC changelog to see what changed
• Multiple versions of an RFC might exist during development (but this is reality anyway)

No breaking changes:

• Existing RFCs remain valid
• No data model changes required
• Validation rules simplified (remove frozen assumption)

ADR-0017: CLI Command Implementation Details

Status: superseded | Date: 2026-01-19 Superseded by: ADR-0037

Tags: cli

References: RFC-0002, ADR-0037

Context

RFC-0002 defines the structural contract for govctl CLI commands: resource-first organization, universal CRUD verbs, lifecycle operations, and output format control. However, RFC-0002 intentionally defers implementation details to preserve flexibility while maintaining a stable interface contract.

Implementation requires decisions on:

• Exact flag syntax and naming conventions
• Array field editing notation (how to add/remove items)
• Help text formatting and structure
• Error message templates and exit codes
• Terminal capability detection (colors, interactive prompts)
• Confirmation prompt behavior
• Progress indicators for long-running operations

Without documented conventions, implementers would make inconsistent choices, leading to:

• Flags named differently across commands (–filter vs –query)
• Array editing syntax that varies by resource type
• Inconsistent help text structure
• Error messages with different formats
• Terminal behavior that breaks in non-interactive contexts

This ADR establishes implementation conventions that realize RFC-0002’s structural contract with consistent UX.

Decision

We adopt the following implementation conventions:

1. Flag Syntax and Naming

Long flags: Always use double-dash with kebab-case

• --output, --filter, --dry-run, --force

Short flags: Single letter aliases for common flags only

• -o for --output
• -f for --force
• -n for --limit (per ADR-0019, aligns with head/tail convention)

No short flag for --dry-run: Safety flags benefit from explicit long form.

No short flags for domain-specific options to avoid collision:

• --filter has no short form
• --rfc-id has no short form

Flag values:

• Space-separated: --output json (preferred)
• Equals accepted: --output=json (clap auto-supports)
• No colons: avoid --output:json

2. Field Editing Commands

govctl uses distinct verbs for different mutation operations. Each verb is clear and discoverable via --help.

Scalar fields: Use set

govctl rfc set RFC-0001 title "New Title"
govctl work set WI-001 description "Updated description"
govctl adr set ADR-001 status accepted

Array fields - append: Use add

govctl work add WI-001 refs RFC-0001
govctl rfc add RFC-0001 owners @alice
govctl work add WI-001 acceptance_criteria "New criterion"

Array fields - remove: Use remove

govctl work remove WI-001 refs RFC-0001
govctl rfc remove RFC-0001 owners @bob

Checklist status: Use tick

govctl work tick WI-001 acceptance_criteria "Tests pass" -s done
govctl work tick WI-001 acceptance_criteria "Docs" -s pending

Pattern matching for array operations: Same semantics as ADR-0007

• Default: case-insensitive substring match
• Use --exact for exact match
• Use --regex for pattern match
• Use --at N for index-based access

Rationale: Distinct verbs (set, add, remove, tick) are more intuitive and discoverable than a unified edit command with prefix notation. Users immediately understand what each command does.

3. Help Text Structure

All commands follow this template:

USAGE:
    govctl <resource> <verb> [OPTIONS] <ARGS>

ARGS:
    <required>     Description
    [optional]     Description

OPTIONS:
    -o, --output <FORMAT>    Output format [default: table] [possible: json, yaml, toml, plain]
    --filter <EXPR>          Filter results (KEY=VALUE)
    --dry-run                Preview changes without writing
    -h, --help               Print help

EXAMPLES:
    govctl rfc list draft
    govctl rfc get RFC-0001 -o json
    govctl rfc set RFC-0001 title "New Title"

Ordering:

1. Universal flags first (output, filter, dry-run)
2. Resource-specific flags second
3. Help/version last

4. Error Messages and Exit Codes

Exit codes:

• 0 - Success
• 1 - General error (validation, not found, invalid transition)
• 2 - Usage error (wrong arguments, unknown flag)

Error format:

error[CODE]: <message>
  --> <location>
  |
  | <context>

Example:

error[E0102]: RFC not found: RFC-9999
  --> gov/rfc/RFC-9999
  |
  | Run 'govctl rfc list' to see available RFCs

Diagnostic codes: Use existing govctl error taxonomy (E0xxx, W0xxx).

5. Terminal Capability Detection

Color output:

• Auto-detect TTY with atty or is-terminal crate
• Respect NO_COLOR environment variable
• Respect --color <always|never|auto> flag (future)

Interactive prompts:

• Only show in TTY mode
• Skip if --force flag provided
• Skip if stdin is not TTY

Progress indicators:

• Use indicatif crate for long operations (>2s expected)
• Show progress for: render, check, bulk operations
• Suppress if --quiet or non-TTY

6. Confirmation Prompts

Destructive operations require confirmation unless --force:

• delete (clauses, work items)
• deprecate (RFCs, clauses)
• supersede (RFCs, ADRs, clauses)

Prompt format:

Delete work item WI-YYYY-MM-DD-NNN? [y/N]

Behavior:

• Default to “no” (capital N)
• Accept: y, Y, yes, Yes, YES
• Reject: n, N, no, No, NO, empty, anything else
• Timeout: none (wait indefinitely)

7. Filter Syntax

Per RFC-0002:C-CRUD-VERBS, list commands support filtering.

Simple filter (shorthand):

govctl rfc list draft          # filter by status
govctl work list active        # filter by status

Explicit filter (future extension):

govctl rfc list --filter status=draft
govctl rfc list --filter phase=impl,status=normative

Implementation: Start with simple substring matching, defer explicit expressions to future ADR.

8. Stdin Handling

When --stdin flag is present:

• Read entire stdin to EOF
• Trim trailing newline only (preserve internal newlines)
• Empty stdin is valid (allows heredocs with empty content)

HEREDOC pattern (recommended for multi-line):

govctl clause set RFC-0001:C-SCOPE text --stdin <<'EOF'
This clause defines the scope.
EOF

9. Dry-Run Behavior

Global --dry-run flag:

• Shows what would be written
• Prints diff or file preview
• Exits with 0 (success simulation)
• No short flag (safety flags should be explicit)

Output format:

[DRY RUN] Would write: gov/rfc/RFC-0001/rfc.json
--- before
+++ after

10. Subcommand Organization (clap)

Structure:

Use nested Subcommand enums for resource-first organization.
Resource commands contain their own verb subcommands.
Global commands remain at top level.

Backward compatibility aliases: Emit deprecation warning when old verb-first commands are used.

Consequences

Positive:

1. Consistent UX: All commands follow the same patterns. Users learn once, apply everywhere.

2. Agent-friendly: Predictable flags, stable error codes, machine-readable output defaults make automation reliable.

3. Maintainable: Implementation conventions documented, not scattered across code comments.

4. Discoverable: Distinct verbs (set, add, remove, tick) are immediately understandable. Users can explore via --help without reading documentation.

5. Safe: Confirmation prompts prevent accidental destructive actions. Dry-run mode enables testing before committing.

6. Debuggable: Structured error messages with codes and locations make issues easy to diagnose.

Negative:

1. Multiple verbs: Users must learn four verbs for mutation operations (set, add, remove, tick) instead of one. However, each verb’s meaning is immediately clear.

2. Testing complexity: Need tests for TTY detection, confirmation prompts, dry-run mode, error formatting, etc.

Trade-offs Accepted:

• Clarity over brevity: Distinct verbs are more verbose than a unified edit command, but much easier to understand. add and remove are clearer than edit +value and edit -value.

• Discoverability over uniformity: Four clear verbs are better than one verb with special syntax that requires documentation.

• Safety over speed: Confirmation prompts slow down destructive operations. This is intentional to prevent accidents.

Alternatives Considered

Document shared CLI implementation conventions. (accepted)

• Pros: Keeps command behavior consistent across resources
• Cons: Requires maintaining a single convention document

Leave CLI implementation details undocumented per command. (rejected)

• Pros: No extra ADR maintenance
• Cons: Commands drift in flags, prompts, errors, and help shape
• Rejected because: Inconsistent command behavior undermines RFC-0002’s stable interface contract.

ADR-0018: Global Command Shortcuts vs Strict Resource-First Syntax

Status: accepted | Date: 2026-01-19

Tags: cli

References: RFC-0002, ADR-0017

Context

During implementation of RFC-0002, we successfully built the resource-first command structure (govctl <resource> <verb>). However, a design question emerged about backward compatibility with existing verb-first shortcuts.

Current Implementation

Both syntaxes currently work:

# Resource-first (RFC-0002 canonical)
govctl rfc list
govctl work new "title"
govctl adr accept ADR-0001

# Verb-first shortcuts (legacy)
govctl list rfc
govctl new work "title"

The Tension

RFC-0002:C-GLOBAL-COMMANDS explicitly defines which commands should remain global:

• init, check, status, render, describe, completions

Notably absent from this list: list, new, and all resource-specific operations like move, tick, accept, etc.

This suggests the RFC intentionally designed these as resource-scoped operations, not global commands.

Problem Statement

Should we:

1. Keep list and new as convenient global shortcuts that delegate to resource-first implementations?
2. Remove them entirely and enforce strict resource-first syntax per RFC-0002?
3. Keep them with deprecation warnings for gradual migration?

User Impact

We have ~40 completed work items and governance workflows that use the old syntax. Scripts, documentation, and muscle memory are built around patterns like govctl list rfc and govctl new work.

However, we are pre-1.0 (currently 0.2.0), which traditionally allows breaking changes.

Implementation Complexity

Current implementation maintains both paths through the canonical command pattern, adding ~40 lines of delegation code. This works but violates the “one way to do it” principle.

Decision

Decision: Remove shortcuts immediately (Option 2)

We will remove govctl list and govctl new shortcuts entirely, enforcing strict resource-first syntax per RFC-0002.

Rationale

1. RFC Compliance: RFC-0002:C-GLOBAL-COMMANDS deliberately defines the exhaustive list of global commands. list and new are not on that list, indicating they should be resource-scoped.

2. Design Clarity: The resource-first pattern (govctl <resource> <verb>) provides a clear, predictable structure:

   • govctl rfc list - list RFCs
   • govctl work new - create work item
   • govctl adr accept - accept ADR

   Having two ways (govctl list rfc vs govctl rfc list) violates the “one obvious way” principle.

3. Reduced Complexity: Maintaining both patterns adds ~40 lines of delegation code and increases cognitive load for users (“which way should I use?”).

4. Pre-1.0 Window: We’re at version 0.2.0, which traditionally allows breaking changes before stabilizing at 1.0.

5. Shell Aliases Sufficient: Users who want shortcuts can add personal aliases:

   alias gl='govctl rfc list'
   alias gw='govctl work'
   alias ga='govctl adr'
   

   This moves convenience to where it belongs—user preference—rather than mandating it in the tool.

6. Consistency: If we keep list and new as globals, why not move, tick, accept, reject? The line becomes arbitrary. Resource-first is consistent across all operations.