/x-spec3

name: x-spec3
description: |
  在开发方案已经讨论清楚、需要固化保存时使用。也适用于用户明确要求保存方案、编写规格文档，或希望在开发前明确目标、边界、约束和验收标准的场景。将已确认的方案整理成可供后续任务拆解、开发和验证共同使用的规格文档。

x-spec3

x-spec3 产出最小完整开发契约。每段内容都服务于实现决策、测试设计或事实验证；同一事实只保留一个权威落点。

产物

在 `docs/spec/<spec-name>/` 中只生成 `spec.md`。完整读取 `templates/spec.md` 后填充，并删除注释、占位符、空表示例。

`spec.md` 固定包含：

1. 任务目标与可观察成功结果。 2. 非目标，限定本次实现范围。 3. 风险评分：复杂度、重要性、平均分、动态预算和与预算一致的审查状态。 4. 影响边界：目标模块、上游、下游、相关模块、主要风险及其不变量。 5. 判断依据：只记录会改变实现或验收的事实、规范、推断和待确认项。 6. 建模覆盖声明：数据流、状态、时序、资源、不变量、故障六项逐一声明，无则写'无'，禁止捏造事实。 7. 验收清单：单元测试、Smoke 测试、按需 E2E 测试及其判定依据。 8. 测试驱动开发顺序。 9. 可执行的 GIVEN/WHEN/THEN Scenarios，每项标记 `initial-spec` 来源。 10. 对抗性审查记录；standard 由 x-spec3 完成，deep/full 由 x-adversarial-risk 完成。

工作流

高能力模型的单轮压缩

完整题面、fixture 与代码已在当前工作区时，优先用一次宽读取建立“硬约束 → 模块/不变量 → 反例 → Scenario”矩阵。独立文件并行读取；同一文件只在其内容变化后重读。

`spec.md` 一次成稿后运行一次完整 validate。validate 返回多个 issue 时，在同一编辑批次修完并整体复跑；语义自审与最小反例检查合并在该批次完成。过程更新只报告新证据、失败或决策变化，省略对已读题面和已写章节的复述。

1. 建立证据边界

读取任务描述与相关代码、测试、接口、配置和既有文档。任务输入给出目录或通配符时，首次宽读取覆盖其递归文件清单；顶层 `*` 只表示一层文件。调用方已提供完整清单时直接批量读取，避免重复枚举。

先确定：

• 需要改变的可观察系统结果。
• 本次明确排除的工作。
• 直接修改模块、调用它的上游、消费其结果的下游。
• 每个受影响模块最可能发生的事故；新模块重点参考同类模块的常见事故。
• 这些模块在修改前后都应成立的不变量。
• 边界、竞态、故障和资源生命周期中的隐蔽失败路径。

证据缺口会实质改变方案时，把它写成待确认判断；其余可逆细节采用最小合理默认并注明推断。

2. 压缩为单一契约

使用 `templates/spec.md`。采用明确目标状态描述行为；关键边界同时给出紧凑可判定断言。判断理由集中放在 J-ID 表中，由边界、验收或 Scenario 引用。

写入前做一次契约一致性检查，只在生成过程使用，不增加 spec.md 章节：

1. 从用户任务提取带有“必须、不得、只、每个、全部、错误、顺序、阈值、所有权”等约束的句子，视为硬约束。 2. 逐条检查目标、非目标、J-ID、边界不变量和 Scenario。LLM 推断只能补足任务未定义的空白，不能放宽、收窄或覆盖硬约束；类型字段可选、零值可用等接口形状本身不产生额外业务语义。 3. 对全称、否定和错误规则构造一个最小反例，优先代入空集合、缺失节点、嵌套边界、覆盖/删除/恢复、共享引用、并发和乱序。若该输入满足当前 spec 却违反用户原句，立即修正判断并补上可判定 Scenario。 4. `待确认` 只用于来源确实没有定义且不同答案会改变实现或验收的事项。任何待确认项存在时，spec 保持草案状态并停止交接 x-req3。

影响边界表覆盖：

• 目标模块的职责变化与公开契约。
• 上游提供的输入、调用顺序、重试或并发方式。
• 下游依赖的输出、错误、持久化或副作用。
• 每个模块由本次变化引入或放大的主要风险。
• 相关模块中必须保持的不变量。

风险写成具体的“触发条件 → 事故 → 影响”，只保留最可能或损失最高的项。新模块至少预判一个同类模块常见事故，已有模块关注回归和不变量破坏。风险必须由不变量、验收项或 Scenario 承接。

`spec.md` 顶部前七行固定复制模板字段形态，每行以 `> ` 开头，只替换冒号后的值；第八行保持空行，第九行开始 `# <spec-name>`。首行直接写 `> spec_version: 3`。

按 `templates/spec.md` 顶部字段写入复杂度与重要性 1–5 分、两者一位小数平均分和预算：

• 复杂度 1–5 依次表示简单 CRUD、单体校验、状态/复杂分支、核心高损失链路、锁/幂等/跨进程并发/崩溃恢复/多阶段持久化提交/核心算法。最后一组任一信号命中即为 5。
• 重要性 1–5 依次表示本地单用户内部非核心、小范围内部日常、全用户非核心、全用户核心、资金/隐私/合规生命线。本地单用户内部 CLI 归入 1；调用者依赖强度不改变实际受众范围。
• 平均分低于 3 为 `standard`，3 到低于 4 为 `deep`，4 及以上为 `full`。
• 任一维度为 4 时预算至少为 `deep`；任一维度为 5 时预算为 `full`。

把评分理由写入“风险评分依据”。`standard` 在同一次 Spec 写入中设置 `adversarial_review: skipped-standard`，写入 ARV-1 且保持 Scenario 集合不扩张。`deep/full` 设置 `adversarial_review: pending`，交给 x-adversarial-risk。

建模覆盖声明逐项给出当前文档锚点。某项确实不适用时写出与本任务相关的具体理由。

3. 先写验收，再写场景

验收清单固定包含单元测试和 Smoke 测试。E2E 按跨进程、跨服务、真实基础设施或用户链路风险决定，并明确写“需要”或“省略”及依据。

测试驱动顺序按风险展开：

1. 将每个 Scenario 映射为会先失败的测试。 2. 先覆盖核心语义，再覆盖边界、错误、并发和资源路径。 3. 实现满足测试的最小代码。 4. 重构后复跑单元、Smoke 和已选择的 E2E。

4. 直接列出 Scenarios

每个 Scenario 标题使用 `### Scenario SC_01: <可判定行为名称>`。ID 固定为 `SC_` 加两位十进制数，从 `SC_01` 开始按文档顺序连续递增。同一 spec 内 ID 禁止重复，新 Scenario 使用当前最大 ID 加一，已有 ID 禁止复用或重编号。语义名称可修改，checklist 和 verify 只按 ID 对账。

每个 Scenario 只表达一个可判定行为，包含：

• **GIVEN**：输入、初始状态与关键边界。
• **WHEN**：唯一触发动作。
• **THEN**：可观察结果、错误、状态或副作用。
• 测试层：`unit`、`smoke` 或 `e2e`。
• 依据：相关 J-ID；直接任务契约可写“用户任务”。
• 来源：第一版统一写 `initial-spec`；x-adversarial-risk 追加的场景使用其独立来源格式。

场景集合优先覆盖高损失边界：递归/嵌套输入、空值与删除、并发交错、重复/乱序、超时/失败、所有权与不可变性、确定性、容量和性能阈值。每项只在与任务相关时出现。

5. 自审并交接

完成规格后做语义自审：

• 每条用户硬约束都能定位到目标、不变量或 Scenario，且没有 J-ID、非目标或 Scenario 与其冲突。
• 每条全称、否定和错误规则都经过最小反例检查；发现的新行为边界已经进入 Scenario。
• 每个目标都有 Scenario 和验收项。
• 每个受影响模块都有具体主要风险；新模块包含同类常见事故预判。
• 每个边界不变量都有可观察验证。
• Scenario ID 均为 `SC_01` 格式，按顺序递增且没有重复；新增或修改场景保持已有 ID 稳定。
• 复杂度、重要性、平均分和预算满足映射，评分依据能定位到当前任务事实。
• 第一版每个 Scenario 都标记 `来源：initial-spec`；`standard` 写入 `skipped-standard` 与 ARV-1，`deep/full` 在交接对抗审查前保持 `pending`。
• 每个 Scenario 能直接转成测试，THEN 避免“正确处理”等不可判定措辞。
• 单元、Smoke、E2E 的职责清晰，E2E 决策有依据。
• 判断依据有消费者，建模覆盖没有空洞锚点。
• 重复说明已经合并，背景材料没有进入执行上下文。

交接时报告 spec 路径、契约一致性检查结果、待确认判断、双评分、预算、测试层选择和最高风险 Scenario。存在待确认项时明确报告“spec 草案，阻断风险审查与 x-req3”。`standard` 完成本阶段后直接交接。`deep/full` 使用一个批量工具调用同时完整读取 `skills/x-adversarial-risk/SKILL.md`、目标 `spec.md` 和同 skill 目录的 `references/risk-mistakes.md`，该调用计为对抗审查第 1 轮；随后只执行一次集中 patch、一次 `validate-review` 和一次回执。`adversarial_review` 达到 `skipped-standard` 或 `complete` 且机械门禁通过后，x-req3 依据该单文档拆解开发任务，verify 依据 Scenario 测试层复跑事实证据。