govctl logo govctl
返回博客
govctl team

govctl v0.15.0：从规范要求到验证证据

govctl 0.15 引入一等 Conformance Case，完成 canonical CLI 收口，并把近期 RFC 生命周期、agent discovery 与 TUI 改进整合为统一模型。

releasegovctlv0.15.0conformanceagents

govctl v0.15.0 是最近几条演进路线汇合成统一模型的节点。

这一版最显眼的新功能是一等 Conformance Case：它在带版本的 RFC requirement、项目自己的验证场景和可复用 Verification Guard 之间建立稳定、非规范性的 链接。但更大的变化横跨 0.10 到 0.15：

  • RFC version 现在拥有明确的候选编写与封存生命周期
  • 过时 requirement 不再占据默认的人类可读上下文
  • 一条 canonical CLI path 取代累积的兼容语法
  • agent guidance 更短，并由 parser-owned discovery 支撑
  • TUI 逐渐成为结构化的治理控制面

这些变化让 govctl 不再只是存放治理文档。Agent 现在可以分别回答三个问题，同时不混淆 它们的权威性：

要求是什么？   -> RFC Clause
如何验收？     -> Conformance Case
由什么执行？   -> Verification Guard

Conformance Case 补上缺失的中间层

在 0.15.0 之前，govctl 已有规范性的 RFC Clause，也有可执行的 Guard，但缺少一个可 复用的身份来表示两者之间的验证场景。

在大型项目中，这个空缺通常会让验证场景流入三个不理想的位置：

  • 塞进规范正文，使 coverage 变化看起来像规范变化
  • 在多个 Work Item 之间重复
  • 藏在测试名和外部 manifest 中，没有可验证的反向链接

Conformance Case 为场景提供稳定的 CONF-* 身份：

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

权威方向被有意限制为单向：

RFC requirement -> Conformance Case -> Guard
规范权威            派生场景             执行入口

Case 不能创造新义务，也不能反向解释 RFC。Guard binding 声明一个命令覆盖哪些 Case， 但不声称某次运行已经通过。govctl 负责验证关系图；领域相关的 fixture、oracle 和测试 执行仍由项目负责。

可以用 trace query 查看这些关系：

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

Trace output 会区分 provisional、candidate、current 和 stale applicability。这样版本 漂移会被直接暴露，而不是把旧场景静默当成当前证据。

RFC Version 开始像真正的候选版本

0.10 到 0.13 重新整理了 RFC version handling，核心想法很简单：一个 version 对应一个 authoring candidate。

处于 spec 的 normative RFC 仍可继续细化。进入 impl 时，当前内容被封存为实现应 满足的 baseline。如果之后发现问题，先编辑已封存内容形成 amendment，再 bump RFC， 从 spec 打开下一个 candidate。

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

这消除了几类纯 bookkeeping churn：

  • 不再为了封存未变化内容做一次空 bump
  • 已有打开的 spec candidate 时不再允许第二次 bump
  • 不再静默重写 Clause since 历史
  • 不再用 loop round 数量推断执行失败

同期还加入了两个实用的恢复边界。尚未发布的 done Work Item 可以重新打开；最新一次 本地 release cut 可以在 expected version 匹配时撤回。一旦历史已经发布或进入其他 不可变边界，这两个操作都会停止。

当前状态与完整历史是两种视图

治理历史必须完整保留，但 agent 不应该把 superseded text 当成当前指令。

从 0.14.0 开始，人类可读的 show 默认使用 current projection。Deprecated RFC、 superseded ADR 和过时 Clause 会保留身份与 replacement metadata，但隐藏不再约束新 工作的正文。

完整历史仍然可以明确请求：

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

生成的 Markdown 仍然是 archival projection，结构化输出也仍然完整。这项变化不是 删除历史，而是为人和 agent 提供更安全的默认上下文。

一条 Canonical CLI，并提供更好的错误恢复

0.15.0 完成了从 0.8 系列开始的 compatibility cleanup。Mutation 现在只有一种 形状：

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

Wire-layout prefix、field alias、compatibility command name 和资源专属 mutation flag 不再作为并行接口存在。所有 Clause 操作始终位于根级 govctl clause namespace。

移除 alias 只有在错误可恢复时才有价值。因此最近的 diagnostic 不只是拒绝输入：

  • 发到 govctl rfc 的 Clause 操作会打印对应的 canonical govctl clause 命令
  • 未知 edit path 会列出当前层级的合法字段
  • 不支持的操作会报告该 path 接受的操作
  • 不支持的 legacy storage 会被明确识别，而不是静默跳过

这是一个 breaking boundary，但它给 agent 留下了更小的 grammar，以及从常见错误 直接恢复的路径。

更短的 Skill，更可靠的 Discovery

对能力更强的 agent 来说，长 workflow manual 不会自动带来更高安全性。它们可能重复 CLI、逐渐偏离 parser，并诱发不必要的 ceremony。

Bundled skill 现在更聚焦于 policy：

  • artifact authority
  • lifecycle boundary
  • authorization stop
  • completion evidence

命令语法来自 --help 和新的 machine-readable entry point：

govctl describe
govctl describe --context

describe 从 parser 派生命令树，并返回紧凑、有版本的 JSON。使用 --context 时，它会 加入完整计数，但只枚举 actionable RFC、ADR、Work Item 和本地 loop。它不会 dump artifact body，也不会凭空规定任务顺序。

Guard guidance 也遵循同一原则。适用于所有任务的廉价检查属于 project default；昂贵 suite 只绑定到风险确实需要它们的 Work Item。关闭 Work Item 仍是最终 effective guard gate，因此 agent 不需要在它之前立即重复运行同一套检查。

更清晰的只读 TUI

TUI 仍然只读，但它已经不再是一组平铺的文字 panel。

最近几个版本加入了：

  • 对齐的 RFC、ADR 与 Work Item lifecycle matrix
  • 分离的 execution activity 与 diagnostic health 区域
  • 更显眼、可容纳长输入的 filter command strip
  • 稳定的 result count 与 scroll indicator
  • Conformance Case 浏览、导航、tag 与 applicability
  • 对过时 artifact 使用 current-state detail projection

职责边界没有变化：用 TUI 理解项目，再用 canonical CLI command 修改项目。

升级到 0.15.0

从 crates.io 安装：

cargo install govctl --version 0.15.0 --locked

Schema version 3 仓库可以事务性升级：

govctl migrate
govctl check

Schema version 4 启用 Conformance Case。低于 schema version 3 的仓库必须先使用兼容的 早期 govctl 完成升级。Legacy RFC 或 Clause JSON storage 现在会被明确拒绝，而不是 静默忽略。

迁移后，可以用 govctl describe --context 获取紧凑的机器可读入口，或打开 govctl tui 使用人类控制面。

为什么在 1.0 之前先发布 0.15

Conformance traceability 是一次重要的数据模型扩展。先通过 0.15 系列发布，可以让 真实项目在 1.0 compatibility promise 之前充分测试 storage、migration、query 和 agent-context 行为。

现在的方向已经更清楚：

  • RFC 定义权威要求
  • ADR 保存设计理由
  • Work Item 跟踪交付
  • Conformance Case 把 requirement 映射到场景
  • Guard 提供可复用执行门禁
  • loop 保存本地执行证据

这就是 0.15.0 希望真实项目开始检验的模型。

完整变更日志：CHANGELOG.md

发布页面：govctl v0.15.0