openrig 能力增量（Capability Delta）模板：在发布边界诚实宣告能力变化、选择探针与过期治理

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI

openrig 的 release 型 mission 在创建时会自动落盘一份CAPABILITY-DELTA-v<版本>.md，它既不是变更日志，也不是版本说明，而是一份「可被真实 Agent 与人类共同消费」的能力增量契约：精确声明本次发布相比上一份已吸收能力基线，用户/Agent 现在能做什么、还不能做什么、应该停止做什么，以及如何用探针验证这些新能力真的可被「干净世界安装」的 Agent 触达。读完本文，你将掌握该模板每个 frontmatter 字段与正文小节的确切含义与填写口径，理解 openrig 的「能力典范（canon）吸收 → 增量过期 → 后继增量接力」生命周期，并能借助rig scope mission create与rig scope audit在真实发布流程中落地这套机制。

一、能力增量解决什么问题：发布边界的诚实通信

在 openrig 的 SDLC 约定中，发布（release）不是「合代码、贴标签」，而是一次需要在能力层面向世界（world-installed Agent、下游消费者、团队评审者）交代清楚的行为。能力增量文档正是为此而设的发布边界工件：

• 它把「这次发布带来了什么新能力」表述为可观测的新事实（observable new truth），而不是一堆 PR 标题的罗列；
• 它必须绑定到精确发布的 cut（commit），并记录 dirty 状态，绝不绑定到未 cut 的分支；
• 它的基线是「能力典范（canon）实际最后吸收的标记」，而不是「上一个 semver 一定被吸收了」的假设——当 canon 落后时，新增量要成为所有中间增量的累积综合（cumulative synthesis），保留被取代与转向的内容，而不是简单拼接旧文案（见 release-boundary.md §6）。

这份约定的权威出处是 sdlc-conventions.md 的RELEASE行，其中明确定义了「CAPABILITY-DELTA LIFECYCLE LAW」：每个发布的能力增量在围栏（fence）处编写并绑定到精确候选，再与发布的 cut 对账；过期要求 canon 头部点名该增量、且存在一个不同的后继增量文件，仅有 draft 头部不构成过期；实际边界事件必须验证后再记录过期，并停止引用已过期增量。

二、模板全貌与 frontmatter：机器可读的身份与绑定信息

模板文件本体位于 packages/cli/src/lib/scope-templates/capability-delta.md，以 YAML frontmatter 开头，承载增量自身的身份、绑定目标、评审状态与过期条件：

--- capability_delta: capability-delta-v{{release_version}} release: {{release_version}} taxonomy: world binding_target: sha: "<exact cut commit>" dirty: "<true|false>" audience: "<who must consume this delta>" review_status: "<draft|reviewed and by whom>" expiry: event: "canon header names capability-delta-v{{release_version}} and successor delta exists" canon_path: "<path to capability canon>" successor_path: "<path to successor delta>" ---

各字段逐项说明如下：

这些字段并非装饰：过期判定实现capabilityDeltaExpiryFindings会逐一读取它们（见下文「过期治理的源码实现」），所以身份、canon_path、successor_path 三者缺一，过期 advisory 就不会被触发。

三、绑定纪律：只绑定精确 cut，绝不绑定未 cut 分支

模板标题# CAPABILITY DELTA — <previous version> → {{release_version}}之下，第一段正文就是绑定纪律：

Bind this delta to the exact published cut inbinding_target; never bind it to an uncut branch or omit the dirty-state observation.

这意味着撰写增量时，binding_target.sha只能引用实际发布的 commit（cut），而不是「功能分支上最新的那个提交」；同时binding_target.dirty必须如实记录。这条纪律与 release-boundary.md §6 的「候选人吸收不是已发布或已服务生产采纳的证据」互为表里——候选 commit 通过了评审并不等于它进入了发布，增量只对真实 cut 负责。

四、核心内容区：以「情境触发」组织新能力

4.1 What you can now do（situation-keyed）

模板要求把每条新能力写成可观测的新事实，并为它标注触发情境：

## What you can now do (situation-keyed) 1. **<Capability stated as an observable new truth>.** **REACH FOR IT WHEN:** <the situation that should trigger this capability>.

填写要点：

• 能力必须是「可观测的」（observable），即能通过命令输出、文件状态、运行结果等外部证据检验的陈述，而不是「架构上更合理了」这类主观判断；
• REACH FOR IT WHEN描述的是用户或 Agent 处于什么情境时应该调用这个能力，为后文「selection probes」提供直接素材；
• 每条能力一行粗体 + 一行触发情境，保持机器可解析的扁平结构，便于 canon 吸收与 world 安装消费。

4.2 Landed, not yet drivable：诚实标注「已落地、还开不了门」的能力

模板用一张表格记录那些**代码已合入、但还没有可用入口（live door）**的能力，并要求给出「诚实的当前做法」：

## Landed, not yet drivable | Landed surface | Missing live door | Honest current action | |---|---|---| | <surface> | <what cannot yet be exercised> | <what to do instead> |

这是 openrig「诚实边界」原则在发布工件上的直接体现：不把「代码存在」当成「能力可用」，明确告诉读者哪块表面目前无法被实际调用，以及在该能力可用之前应当用什么替代做法。任何「没发货的缺失能力」都应当在这里被点名，见 sdlc-conventions.md 中关于 missing capability 的约定。

4.3 What to STOP doing：退休旧认知与旧 workaround

能力增量不只宣告新增，还要宣告退役——哪些旧的认知、绕法或信念在本次发布后不再成立：

## What to STOP doing 1. **<Retired workaround or belief>.** - **Correct before:** <the prior release truth that justified it>. - **Wrong now:** <the new release truth and the replacement action>.

两条子项分别记录「旧版本里它为什么合理」与「新版本里正确的事实和替代动作」。这个「Correct before → Wrong now」的二元结构，让下游读者能精确对照自己的既有行为是否已过时，避免带着上一版认知继续使用新版本。

五、选择探针（Selection probes）与 DELTA-ONLY QUALIFICATION

为了让「新能力真的能被 Agent 触达」这件事可验证，模板要求写出一对探针：

## Selection probes - **P-A — <negative or present-to-absent case>:** <prompt and expected first answer>. - **P-B — <positive case>:** <prompt and expected first answer>.

• P-A：负例（present-to-absent），即「旧行为仍被期望但已不存在」的场景，期望的首次回答应体现变化后的新事实；
• P-B：正例，期望的回答应命中新能力。

模板特别强调DELTA-ONLY QUALIFICATION判定规则：

在 seat（被测 Agent）运行或读取任何东西之前，先对它的首次陈述作答打分。只有当「基线（未训练 delta 的 Agent）答错变化后的新事实、而 delta 训练后的回答答对」时，探针才算合格；本来就已知的行为不构成 delta 证据。

也就是说，探针的价值不在于「新版本 Agent 答得对」，而在于「旧基线答不对、新基线答对」——这个差分（delta）才是能力真正新增的证据。这与 release-boundary.md 中「干净世界安装的 Agent 能否从其情境到达该能力，而不被直接告知能力名称」的验收口径一致。

六、Canon patch：最小化吸收补丁与过期标记

增量最终要被能力典范（canon）吸收，模板用三个条目规范吸收动作：

## Canon patch - **Already present — do not duplicate:** <canon content that already teaches the truth>. - **Patch:** <the smallest missing canon change, with its exact destination path>. - **Expiry marker:** when absorption is complete, put `capability-delta-v{{release_version}}` in the named canon file's header and create the successor delta at `expiry.successor_path`. The advisory audit then reports this delta as citable no more.

• Already present：如果 canon 里已经有内容在教授这条新事实，不要重复写——吸收的准则是「最小缺失补丁」，而非整篇搬运；
• Patch：给出最小缺失变更及其精确落点路径；
• Expiry marker：吸收完成后，在 canon 文件头部写入增量身份，并创建后继增量。只有完成这两步，审计才会把该增量标记为「不可再引用」。

模板页脚的说明也很关键：过程与约定（SOP）一律见 sdlc-conventions.md（安装后位于$OPENRIG_HOME/reference/sdlc-conventions.md），增量工件只承载发布专属事实，不得把发布边界 SOP 整段拷入。

七、CLI 落盘机制：rig scope mission create自动生成增量

模板不是静态文档，而是被 CLI 真实消费的渲染源。在 templates.ts 中，renderCapabilityDeltaTemplate读取capability-delta.md并应用占位符（含{{release_version}}、{{id}}、{{slug}}、{{mission}}、{{title}}、{{created_date}}、{{intent}}、{{depends_on}}）；占位符替换逻辑见 applyPlaceholders。

在 mission create 命令 中，当 mission 名称匹配 release 模式^release-\d+\.\d+(?:\.\d+)?$时：

1. 从名称剥离release-前缀得到releaseVersion；
2. 渲染 capability delta 正文（scope.ts#L850-L861）；
3. 在 mission 根目录写入CAPABILITY-DELTA-v${releaseVersion}.md（scope.ts#L871-L876），并在 JSON/人类可读输出中返回capabilityDeltaPath。

实际用法：

rig scope mission create release-0.5.4 --intent "Honest 0.5.4 boundary" --json

该命令会创建release-0.5.4/mission 目录，并在其中同时生成SPEC.md、mission.yaml、PROGRESS.md、NOTES.md以及CAPABILITY-DELTA-v0.5.4.md。若非 release 命名的 mission（如backlog-*），则不会生成增量文件——增量是发布专属工件。workspace 根目录可通过--workspace <path>覆盖（默认从 cwd 或$OPENRIG_WORK_ROOT推断）。

八、过期治理的源码实现：audit 如何判定「不再可引用」

增量并非永远可引用。rig scope audit --mission <name>在审计 mission 时会并入增量的过期检查（scope.ts#L1039-L1041），核心逻辑在 capability-delta.ts 的capabilityDeltaExpiryFindings：

1. 扫描 mission 目录下匹配^CAPABILITY-DELTA-v.+\.md$的文件并排序；
2. 解析每个文件的 frontmatter，提取capability_delta身份、expiry.canon_path、expiry.successor_path——三者任一缺失即跳过；
3. 将 canon 与 successor 解析为相对增量文件所在目录的绝对路径；若 successor 指向自身、或 canon/successor 文件不存在，跳过；
4. 读取 canon 文件首个##之前的头部（documentHeader），按[^A-Za-z0-9._-]+分词后精确检查是否包含增量身份；
5. 全部条件满足，产出expired_capability_delta类 finding，severity 为medium，message 说明「canon header 点名了它且后继存在，它不再可引用」，remediation 指示「停止引用该增量，改用后继增量，并在发布流程要求时归档」。

值得注意的实现细节：

• 合取与精确匹配：canon 头部必须点名完全一致的增量身份。测试中专门构造了 canon 头部写capability-delta-v0.5.40（与真实身份capability-delta-v0.5.4仅差一个尾字符）的近匹配场景，审计不会触发过期（见 scope-convention-scaffold.test.ts#L297-L354）；
• fail-open 的 advisory：缺失、不可读的输入一律保持「未知/存活」，绝不把 advisory 变成 gate（代码注释明确：missing or unreadable inputs remain unknown/live and never turn the advisory into a gate）。因此expired_capability_delta是 medium 级 advisory，不会翻转审计退出码；
• draft 头部不构成过期：只有 canon 头部点名 + 后继文件存在双条件齐备才算过期，与 release-boundary.md §6 的「header alone does not expire it」「Do not create a successor merely to make the condition true」完全对应——不允许为了凑条件而人为创建后继增量。

九、测试证据：模板形状与过期判定的双保险

scope-convention-scaffold.test.ts 用三个用例锁定了这套机制：

1. 模板形状测试：渲染结果必须包含capability_delta: capability-delta-v0.5.4、binding_target、sha、dirty、audience、review_status、expiry，以及## What you can now do (situation-keyed)、REACH FOR IT WHEN、## Landed, not yet drivable、## What to STOP doing、Correct before:、Wrong now:、## Selection probes、DELTA-ONLY QUALIFICATION、## Canon patch、Already present — do not duplicate等全部关键段落——防止模板在演进中悄悄丢失骨架；
2. 真实落盘测试：mission create release-0.5.4 --intent "Honest 0.5.4 boundary"后断言CAPABILITY-DELTA-v0.5.4.md真实存在且内容包含增量身份，验证渲染 → 落盘全链路；
3. 过期判定测试：依次验证近匹配 canon 头部不触发、successor 缺失不触发、canon 不可读不触发，最后在「canon 头部精确点名 + successor 文件存在」时恰好产出一条expired_capability_delta（medium）——完整刻画了过期事件的边界条件。

十、实操模板：一份可复制的增量填写示例

综合以上规则，一份填写完毕的能力增量应当长这样（以release-0.5.4为例）：

--- capability_delta: capability-delta-v0.5.4 release: 0.5.4 taxonomy: world binding_target: sha: "9f2c1ab..." dirty: "false" audience: "clean world-installed agent; release reviewers" review_status: "reviewed by pm-lead" expiry: event: "canon header names capability-delta-v0.5.4 and successor delta exists" canon_path: capability-canon.md successor_path: CAPABILITY-DELTA-v0.5.5.md ---

# CAPABILITY DELTA — 0.5.3 → 0.5.4 Bind this delta to the exact published cut in `binding_target`; never bind it to an uncut branch or omit the dirty-state observation. ## What you can now do (situation-keyed) 1. **`rig scope audit` now reports expired capability deltas with a medium advisory.** **REACH FOR IT WHEN:** you suspect a release's delta has been absorbed and superseded. ## Landed, not yet drivable | Landed surface | Missing live door | Honest current action | |---|---|---| | successor-aware archive | no public command yet | keep citing the successor delta manually | ## What to STOP doing 1. **Assuming the previous semver's delta was always absorbed.** - **Correct before:** canon was assumed in lockstep with semver. - **Wrong now:** baseline is canon's actual last-absorbed marker; verify it. ## Selection probes - **P-A — delta no longer citable:** "Is capability-delta-v0.5.4 still citable?" expected first answer: "No — canon absorbed it and a successor exists." - **P-B — new capability reachable:** "What happens when I audit a mission with an expired delta?" expected first answer: "A medium advisory `expired_capability_delta`." **DELTA-ONLY QUALIFICATION:** grade the seat's first stated answer before it runs or reads anything. A probe qualifies only when the baseline misses the changed truth and the delta-trained answer gets it; already-known behavior is not delta evidence. ## Canon patch - **Already present — do not duplicate:** release-boundary.md §6 already teaches the lifecycle law. - **Patch:** add `capability-delta-v0.5.4` to `capability-canon.md` header once absorbed. - **Expiry marker:** when absorption is complete, put `capability-delta-v0.5.4` in the named canon file's header and create the successor delta at `expiry.successor_path`. The advisory audit then reports this delta as citable no more.

过程与约定以 sdlc-conventions.md 为准（安装后：$OPENRIG_HOME/reference/sdlc-conventions.md）；本工件只承载发布专属事实，不得把发布边界 SOP 拷入。

十一、注意事项与边界

• 增量只承载发布专属事实：过程性约定统一指向docs/reference/sdlc-conventions.md（安装后$OPENRIG_HOME/reference/sdlc-conventions.md），不要在本工件里复制 SOP；
• 过期不是惩罚而是接力：expired_capability_delta是 medium advisory，作用是把「已经过时的引用」显式叫停，引导读者转向后继增量；它不会阻塞审计（exit code 只受 high finding 影响，见 scope-audit.ts 的注释与 finding 定义）；
• 不允许制造过期：为让条件成立而人为创建 successor 文件、或在 canon 头部塞入不精确的近似字符串，都会被实现与测试机制识别为无效（successorPath === deltaPath直接跳过、近匹配分词不命中）；
• 候选人吸收 ≠ 发布：增量对发布 cut 负责，cut 前的候选提交状态不构成能力已上线的证据。

能力增量模板把「发布」从一个 git 动作还原为一次可验证、可被 Agent 触达、可被后续审计接力的能力通信事件——这正是 openrig 在发布边界上坚持诚实与可证伪的工程化体现。

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI