Files
marqdo/doc/adr/0010-skill-proof-boundary.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

80 lines
5.7 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ADR 0010: SKILL 证明边界:定理表、可证子集与顾问式判定
| 项目 | 约定 |
|---|---|
| 状态 | **Accepted(决策已定)**;实现未开始,路线见 [roadmap/prove.md](../roadmap/prove.md) |
| 日期 | 2026-11-13 |
| 设计 | [design/prove-cli.md](../design/prove-cli.md) |
| 相关 | [core-surface.md](../design/core-surface.md)(不新增标记)· [layers.md](../design/layers.md)(Language 层扩表角色)· [contract.rs](../../src/contract.rs)(既有契约表提取)· [replay-policy](../../verification/replay-policy/README.md)(Lean 伴随判定先例) |
## 背景
Agent 改写 SKILL 后,人需要逐行确认"分支是否绕开审核、失败是否被吞掉"。这类**控制平面**性质适合形式化:编排是带条件的有限 DAG,没有死循环、没有指针。同时,把整个 Marqdo 当通用语言编译到 Lean 会立刻撞上字符串/JSON/浮点/IO 的语义鸿沟,收益被稀释。
项目已有一条 Lean 纪律:`verification/replay-policy` 用 Lean 做唯一判定,Rust 不保留第二份实现,缺伴随进程时失败关闭。本 ADR 决定把同样的纪律用于 SKILL 编排,但**降级为顾问式**:证明用于减少审核量,不作为发布门禁。
## 决策
1. **定理是契约表的第四种角色**,不是新标记。
函数体首条可执行语句之前可放一张「定理表」(`定理 | 结论 | 前提 | 策略`),与 `参数`/`返回`/`字段` 表同槽位;解析期提取进 `Function.claims`,从 body 移除,不参与运行。核心标记计数不变,`CORE_CONSTRUCTS` 不增行;`layers.md` 的 Language 清单补记该角色。
2. **可证子集显式封闭**:无 `while`、无递归、无动态派发(插件、变量函数名、`code` 值调用)。越界函数被跳过(`rejected`),不降级成不透明块。外部操作是 `Env := Op → Val` 参数,不是公理;后置条件只能来自 `假设` 表并成为定理前提。
3. **Lean 是唯一能产生 `proved` 的判定器**。离线判定只到 `checked`,且被限制在一个极小的片段(路径枚举、轨迹、字面结果、命题组合、单变量区间),凡是离线判定为真的定理都必须同时生成 Lean 脚本。运行期若 Lean 可用则复核;离线 `checked` 而 Lean 未关闭视为内部错误(`proof.divergence`),以 Lean 为准并退出非零。
4. **顾问式,不强制**。默认退出码只对"作者写下的定理未被关闭"(`unproved`)与工具错误非零;缺工具链、`rejected`、`unverified` 默认 0。需要严格覆盖的调用方显式传 `--require-lean`。规范与技能手册**推荐**在发布 SKILL 前运行,但不设为门禁。
5. **`prove` 不执行被证程序**。只读源码、写缓存与 `--emit` 目录;这一点由测试夹具(带 `fs.write` 的函数)守住。
## 备选与取舍
| 备选 | 否决理由 |
|---|---|
| frontmatter `proof:` 块 | 丢函数作用域与行级锚点;多函数文件无法分派;诊断指不回具体行 |
| `# 证明` 标题 | `#` 是对象、`##` 是函数;新增"标题=命题"破坏"标题即可调用单元"的既有习惯,还会进命名空间 |
| ` ```proof ` 围栏 | 代码围栏必须跟在空赋值后,为写定理先造死变量,比表更别扭;且会被当作可执行值 |
| 普通注释承载定理 | 注释不参与语义,无法可靠区分说明与定理,拿不到行锚点 |
| 旁挂 `.proof.md` | 把真理拆成两份,违背"文档与代码同一份"的项目前提 |
| 细化类型(refinement types) | 语义增量过大,且与既有契约表形成两份作者真相 |
| 强制门禁(proved 才能发布) | 与"降低审核难度"的目标冲突;无 Lean 的团队会绕过工具 |
## 后果
**正面**
- 作者在一个地方写清"这条编排保证什么",机器可判定、行号可定位;
- 定理表与契约表同一提取路径,`check` / `view` / `catalog` 可逐步接入,不产生第二套声明;
- 外部依赖以假设形式显式化,证书是本项目一贯的"可复核证据";
- 不新增核心标记,守卫测试与文档计数不膨胀。
**负面 / 代价**
- 新增一个语言层语义角色与一个 CLI 命令,需要 ADR + 测试 + 文档(本 ADR 即准入材料);
- 离线判定器是新代码,必须长期用 Lean 语料护栏,防止"过度自信";
- 作者可能误以为定理会在运行时生效——需要文档、`view` 与 `check` 三处反复澄清;
- `proved` 容易被读成"整份 SKILL 安全"——README 必须写死"只对陈述负责"。
## 语义增量清单
| 新增 | 是否进运行时 | 说明 |
|---|---|---|
| `Function.claims` | 否 | 与 `Function.contract` 同类的声明元数据 |
| `结果` / `轨迹` 与 `包含` / `长度` / `下标` | 否 | 仅定理作用域;与普通表达式作用域隔离 |
| `check --proof` | 否 | 静态校验,默认关 |
不新增:求值规则、作用域规则、调用约定、核心标记、类型系统扩展。同名遮蔽(参数或局部变量叫 `结果`/`轨迹`)一律报 `proof.name_shadow`,不做隐式优先。
## 验收(摘要)
- 核心表面:`cargo test --test core_surface` 不变红;`CORE_CONSTRUCTS` 计数不变。
- 单调性:语料中每条离线 `checked` 的定理,Lean 均 `proved`;分歧为 0。
- 不执行:带 `fs.write` 的夹具在 `prove` 后无副作用。
- 确定性:同输入两次 `emit` 字节一致。
- 诚实性:文本、JSON、证书三处对 `checked`/`proved` 的措辞一致。
## 未决(不阻塞实现)
- `假设` 表是否需要扩展列(`来源`、`责任方`)。
- `--all` 的聚合粒度(按文件/按函数)。
- 证书是否需要签名,以及签名由谁持有。