# 验收契约方法

## 激活与身份

进入本方法时先建立 active acceptance ledger，而不是只引用设计或计划中的被动清单：

- `contract-id` 标识本次整体契约，`parent-goal` 固定用户最终结果；
- 为每个会改变整体完成判断的标准分配 stable acceptance ID，登记 `Required: true | false`、合同、`Status: not-run | passed | failed | blocked | stale`、当前证据和失效原因；
- 优先复用用户或已有权威文档中的稳定 ID；无 ID 时按契约内稳定前缀递增，重命名实现、阶段或版本不得重编号；
- 设计、计划、issue 或发布说明只是候选来源；只有登记到 active ledger 的条目才参与阶段更新和 completion gate。

`passed` 只表示证据仍匹配当前实现、范围、环境与场景版本；相关事实变化后立即转为 `stale`。`blocked` 是未完成状态，不能通过改成非必需来消失。

### 跨架构交付的双向对账

更换运行宿主、存储归属、能力目录或主要用户链路时，在原 active contract 中对照三类事实：旧产品实际能力（旧入口与代表性使用路径）、用户当前要求（原始输入及有效修订）、候选方案及产物能力。设计阶段用拟交付的触发路径检查覆盖范围；实现后改用新入口与运行证据判定实际能力，不把方案当事实。只登记本次触达且可能改变用户结果的能力。分别检查旧→新有无未经解释的变化或退化，以及目标→新有无未实现、未验证的必需结果；不另建平行账本。

每个 Required 结果拆到用户动作与可观察结果能够独立判定；含条件分支时逐分支留证。`passed` 须有可触发入口、实际执行和结果的正向证据；“没有工具”或“无人触发”不能证明按需能力。设计把 Required 能力列为未来扩展时，Design Ready 前须将它纳入当前实现和验证设计，或取得用户确认的范围变更。缺可行触发证据记 `not-run`/`blocked`，确认缺实现记 `failed`；其它分支成功或发布成功不能改写它。

## 建立整体契约

先基于已确认的用户目标与事实写最小整体契约；未知项明确标记，不用猜测补齐。大型交付默认保存为 `docs/work/YYYY-MM-DD-<delivery-slug>/acceptance-contract.md`；项目已有等价载体则在工作入口明确映射，不另抄标准。日期取创建日，跨天沿用。

讨论转入执行或用户纠偏时及时保存预期与来源：区分用户明确要求、已确认选择、授权内 AI 决定和未确认假设；沉默不算确认。来源可用消息链接，不能稳定定位时保留日期与必要原话。重要取舍保留理由，模糊表达的具体化注明推断；只有影响决策的歧义才澄清。稳定 ID 用于重要标准，不给每句聊天或普通观察编号。

大型交付的原始输入、材料版本与用途、原意及后续补充保存在 `docs/logs/` 的“原始输入与约束”章节或其链接文件；本合同引用该记录及相关来源，拥有当前有效标准与生效变更，不复制原始材料清单。提炼时反查原件，不能因账本遗漏而排除用户已要求的结果；已确认的新约定可替代旧要求，但保留来源与替代关系。

1. **最终结果**：一句话描述用户最终能完成什么，而不是列实现组件。
2. **必须成立**：只保留缺失后用户会认为“没有交付完整”的结果、关键链路与产品能力。
3. **必须不发生**：只记录本任务真实高风险的退化、漂移、数据损坏、安全越界或错误兼容。
4. **架构不变量**：只约束 owner、数据/事件归属、公共 contract 或单一路径等长期意图；不锁定可替换的临时实现。
5. **代表性场景**：用少量真实用户任务覆盖主要机制、数据状态、失败边界和适用生命周期；不按 API 数量机械穷举。
6. **交付边界**：区分本地可交付、安装/升级、发布/部署和需要授权的外部动作。
7. **真实边界**：只记录用户明确排除、与最终结果无关、需要新增授权或受外部条件阻塞的内容；AI 不得为了让任务有限而自行制造“本轮非目标”。

当响应速度、吞吐、资源消耗或成本是用户目标，或足以改变架构选择时，将其登记为可判定的 Required 结果：实现前固定代表性任务、数据量、并发或活跃用户、冷/热状态、用户可感知的起止点、统计口径、基线或目标门槛及测量环境。成本在相同使用条件下区分固定与边际开销；比较方案时保持负载、模型和计费假设一致。门槛取自用户要求、现状证据或说明依据的设计目标，不凭空设通用数值，也不在看到实现结果后调低。条件不同的路径分别判定，功能通过不能抵消性能或成本 Required 项失败。

### 完成边界、阶段切片与授权边界

大型任务必须分开维护三件事：

- **最终完成边界**来自用户想得到的结果和 AI 被委托负责的产品方向。用户把一个方面交给 AI 时，默认包含当前能够独立完成的产品、架构、实现、体验、生命周期、文档、打包与验证闭环，而不是只包含最先出现的任务清单。
- **阶段切片**只决定先后顺序和当前工作量。阶段完成只能表述为“该阶段完成”，不得据此把整体目标改称完成，也不得把后续仍可实施的工作放入“未来”后结束任务。
- **授权或外部边界**只暂停相应动作。commit、发布、部署等需要授权时，先完成其余可做工作并把产物准备到可执行状态；不得把“尚未获准执行外部动作”扩张成整个产品方向的缩减。

`MVP`、`本轮`、`非目标` 或 `后续再做` 不能由 AI 单方面降低用户结果。只有以下情况才能排除工作：

1. 用户明确排除或限定；
2. 证据表明它与最终用户结果无关；
3. 它需要尚未获得的外部授权、凭据、硬件或第三方状态；
4. 新事实证明继续建设没有产品价值，并经用户确认停止或缩小。

删除 Required ID、改成 optional、降低合同或把工作移出 `parent-goal` 都是 scope reduction；先记录 `scope-change: proposed`，只有用户明确同意后才能写入 `scope-confirmation: user-confirmed` 并提高 `scope-revision`。用户补充信息、实现学习、版本或发布时间点不能静默授权缩 scope。

当用户表达“你负责这个方面”“能做的都做掉”或同等委托时，每次阶段收尾必须追问：**在不需要用户新增输入和授权的前提下，我现在还能继续闭合什么？** 只要答案非空，就只能报告阶段进展，不能报告整体完成。

验收标准定义“什么必须被证明”，Validation 决定“用什么证据证明”。不要复制测试命令或阶段 owner 的通用清单。

## 标准质量过滤

每条候选标准必须同时通过：

- 如果它不成立，用户是否会合理地认为任务未完成？
- 它是否对应当前任务真实可能出现的失败，而不是泛化想象？
- 它是否可通过行为、状态、产物或边界证据判断？
- 它是否保留合理实现空间，没有把临时方案写成永久合同？

再做删除测试：**删掉这条后，哪个现实中的坏结果会被错误放行？** 无法回答就删除。仓库常驻规则、一般 AI 不会遗漏的常识和与当前任务无关的最佳实践不要重复写入。

## 分阶段与即时阶段门

大型交付默认一个阶段，允许多个工作项及跨轮执行。分阶段必须记录：两侧可观察结果、真实证据/外部依赖或风险、合并会出什么具体问题、通过/返工条件。普通排序或提前集成足以解决时不分阶段；文件多、耗时长、需要 plan 均不足以拆分。

方案 Review 检查相邻阶段能否合并，缺依据则合并；同时检查未解决的关键假设，不能为单阶段而盲目展开。新证据消除边界后允许合并；通过阶段门后仍有可执行必要工作就继续，不新增例行人工审批。

每个阶段开始时，基于最新证据即时写阶段门：

- 本阶段结束时新增的可观察结果；
- 必须保持的整体契约和架构不变量；
- 覆盖该结果的代表性成功、状态恢复或失败场景；
- 本阶段暂不处理但仍属于整体目标的内容；
- 进入下一阶段前必须关闭的缺口。

阶段结束时只更新受新事实影响的 ID 和后续阶段，不重写稳定契约。每个阶段返回 `acceptance_updates` 与 `parent_status: in-progress | blocked | ready-for-retrospective | ready-for-completion-check`；Delivery 和专项 release 只能关闭子目标，随后返回 lifecycle parent。Delivery 成功后先进入复盘，复盘给出明确决定后才允许完成检查；不能自行把发布、版本或阶段成功升级成整体完成。

## 学习与漂移控制

实现中出现新发现时必须归类：

- 当前验收必需：加入当前阶段并说明遗漏原因；
- 原标准被事实证明错误：修改契约，记录证据、影响与理由；
- 有价值且属于最终结果：纳入当前可执行工作或按真实依赖排序，保持未关闭，不为放进“后续”而造阶段；
- 有价值但与当前委托无关：只有通过真实边界条件时才排除；
- 与目标无关：丢弃，不因已经发现就扩张范围。

不得静默改变最终结果、Required IDs、架构不变量、代表性场景或交付边界。设计学习可以改变实现，不能悄悄改变用户得到的结果。

有效约定与待决提案分开。变更写明原约定、新事实、建议与影响：保持用户结果的授权内实现选择可自主修订；改变用户目标、体验、关键取舍或权限时按原授权决定，无相应授权则等用户确认，旧约定保持有效。生效时记录依据与替代关系，只使受影响证据 stale。普通验收状态变化不提升标准修订号；不能倒改标准追认已偏离的实现。

工作开始/恢复时读取有效约定及相关设计；Review 从实际产物反查约定与用户来源，检查最初提炼是否漏项。多个 AI 产物相互一致不证明理解正确。只更新变动项，不要求每次工具调用重读全部合同。

兼容或legacy保留先按[真实存量与兼容证据](../../../../../skills/development-design/references/architecture-principles.md#真实存量与兼容证据)核对实际消费者/数据/对外承诺，不能用旧草案或聊天路径虚构存量。兼容、fallback、重试或legacy分支进入契约还须写明真实消费者、为何不应显式失败、可观察方式和退出条件；否则采用单一正确路径。

## 一次契约 Review

整体契约和每个阶段门各做一次针对性 Review：

- 是否可能所有条目都通过，用户仍明显只拿到 80% 的结果？
- 是否由 AI 自己选择了 `MVP`、单平台或单链路，然后把其它仍可完成的产品工作写成非目标？
- 当前还有哪些无需用户新增输入或授权就能继续完成的工作？若存在，整体状态必须保持未完成。
- 是否漏掉与当前产品真实相关的数据、权限、恢复、安装、升级、卸载、失败或 Agent 调用链路？
- 是否有条目只是重复项目规则、与任务无关或几乎不可能出错？
- 是否把临时实现、未来平台愿景或主观偏好误写成硬约束？
- 是否引入没有当前消费者的兼容层、兜底或扩展点？

只修正能改变完成判断的问题，不进行无上限自我辩论或反复改写。

## 连续性与最终门

跨会话、交接或上下文压缩前，持久化 `active-contract`、`parent-goal`、`scope-revision`、`open-required`、最近 `acceptance_updates`、证据指针和用户确认的 scope decisions。恢复后先重载 ledger，把阶段/发布结果对账到 stable IDs；不得从最新版本号、最近总结或局部成功猜测范围和完成状态。

大型交付还须对账delivery-goals中的规划功能/可执行任务：当前必需项均已完成，证据与当前合同一致；再反查parent-goal有无遗漏。名字不必写成上层效果，每项完成标准须可验收；清单不完整或整体场景失败时，即使所有编码项已完成也不能关闭整体。清单载体沿工作记录协议，不在本合同另复制任务状态。

只有 lifecycle 可以执行 completion gate：全部 `Required: true` ID 当前均为 `Status: passed`、证据未失效，且没有未登记但属于 `parent-goal` 的必要缺口，才允许整体完成。任一 Required ID 为 not-run、failed、blocked 或 stale 时只能继续、返工或真实阻塞；版本发布、文档状态和阶段汇报不能覆盖该结论。

## 最小活文档

```markdown
# 交付合同

## 身份与来源

- contract-id：
- parent-goal：
- scope-revision / scope-confirmation：
- 用户来源（大型交付链接日志中的原始输入记录）、确认性质、适用范围与授权：

## 当前有效约定
- 稳定 ID、表述、来源、适用范围（下列维度按实际需要组织）：
- 必须成立：
- 必须不发生：
- 架构不变量：
- 代表性场景：
- 交付边界：
- 真实边界：

### 阶段安排（默认单阶段，必要拆分才展开）
| 阶段 | 可验收结果 | 进入下一阶段的门 | 状态 |

## 验收账本（Active acceptance ledger）
| ID（引用有效约定） | Required | Status | 当前证据 | 失效原因 |

### 当前阶段门
- 结果：
- 保持项：
- 场景：
- 本阶段不做：
- 待关闭缺口：

## 待决变更
- 原约定 / 新事实 / 建议 / 影响 / 待谁决定（没有则写无）：

## 生效记录
- 原→新 / 原因 / 授权依据 / 修订 / 受影响 ID（没有则写无）：

### 尚未关闭
- open-required、未验证边界、真实外部阻塞或待授权动作：
```

契约形成后明确说明被删除的主要噪声标准及原因。契约足以支持下一阶段做明确决策后退出。
