Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

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

  2. govctl rfc deprecate <id>

  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>

  2. govctl adr reject <id>

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

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>

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

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:

ResourceCanonical pathPermitted operation
RFCtitle--set
RFCowners, refs, tags--add, --remove
RFCchangelog.summary--set
RFCchangelog.added, changelog.changed, changelog.deprecated, changelog.removed, changelog.fixed, changelog.security--add, --remove
ADRtitle, date, context, decision, consequences--set
ADRrefs, tags--add, --remove
ADRalternatives--add, --remove, --tick
ADRalternatives[i].text, alternatives[i].rejection_reason--set
ADRalternatives[i].pros, alternatives[i].cons--add, --remove
Work Itemtitle, description--set
Work Itemrefs, depends_on, tags, notes--add, --remove
Work Itemacceptance_criteria--add, --remove, --tick
Work Itemacceptance_criteria[i], acceptance_criteria[i].text, acceptance_criteria[i].category--set
Work Itemverification.required_guards--add, --remove
Work Itemverification.waivers--remove
Work Itemverification.waivers[i].guard, verification.waivers[i].reason--set
Clausetitle, text, kind--set
Clauseanchors, tags--add, --remove
Guardtitle, command, timeout_secs, pattern--set
Guardrefs, tags--add, --remove
Conformance Casetitle, path, selector--set
Conformance Caserequirements, guards, tags--add, --remove
Conformance Caserequirements[i]--remove
Conformance Caserequirements[i].version--set

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