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