specline 1.3.4 → 2.0.0

package/templates/.cursor/skills/specline-knowledge/SKILL.md

@@ -0,0 +1,539 @@
+---
+name: specline-knowledge
+description: >-
+  面向 AI 的项目知识库管理。检测 AGENTS.md 入口文件，追踪引用的知识文件链，
+  对比代码自行判断新鲜度，按需生成/更新六类知识文件（术语表/架构/约定/决策/参考/操作指南）。
+  Use when the user wants to check, generate, or update AI-oriented project knowledge files.
+---
+
+# /specline-knowledge 知识库管理 Skill
+
+---
+
+## Layer 1: 速览与定位
+
+**一句话定位**：管理面向 AI 的项目知识库——找入口、查新鲜度、按需生成六类知识文件。
+
+**入口**：`/specline-knowledge [可选: 文件名]`
+
+**你做**：
+
+- 定位 AGENTS.md（或 CLAUDE.md / CURSOR.md）
+- 解析入口文件中的知识文件引用链
+- 读取源文件，自行对比判断每个知识文件的新鲜度
+- 按用户选择生成/更新六类知识文件
+
+**你不做**：
+
+- 往知识文件中添加任何元数据（哈希、时间戳、front matter）
+- 与 pipeline / quickfix 自动联动
+- 修改项目源代码
+
+**核心原则**：知识文件是 AI 的速览地图，不是完整文档。新鲜度由 AI 阅读理解判断，不由时间戳驱动。
+
+---
+
+## Layer 2: Happy Path
+
+### Step 1: 定位入口文件
+
+按优先级搜索项目根目录：
+
+```text
+AGENTS.md  →  CLAUDE.md  →  CURSOR.md  →  .cursor/rules/
+```
+
+**找到入口文件**：
+
+- 读取内容，提取其中的 markdown 链接 `[text](path)` 作为知识文件引用链
+- 进入 Step 2
+
+**未找到任何入口文件**：
+
+- 提示用户：「未找到 AGENTS.md 或其他入口文件。是否需要我创建一个？入口文件是知识库的导航地图，记录所有知识文件的位置。」
+- 用户确认 → 使用下方 `agents-entry-template` 创建 AGENTS.md（只创建入口文件，不立即生成子知识文件）
+- 用户拒绝 → 结束，提示可随时再次调用
+
+**多个入口文件并存**：
+
+- 列出所有存在的入口文件及其位置
+- 询问用户以哪个为主入口
+
+---
+
+### Step 2: 解析知识文件
+
+如果用户传入了文件名参数（如 `/specline-knowledge architecture.md`），只检查该文件。
+
+否则，扫描入口文件中的引用链 + `docs/knowledge/` 目录：
+
+**引用链解析**：
+
+- 提取入口文件中所有 `[text](相对路径)` 格式的链接
+- 过滤出指向知识文件类型的链接（`.md` 文件）
+- 逐文件追踪引用（如果被引用的文件内部又有链接，递归追踪）
+
+**目录扫描**：
+
+- 检查 `docs/knowledge/` 目录下所有 `.md` 文件
+- 如果文件存在但入口文件无引用 → 标记为「孤儿知识文件」
+
+**展示给用户**：
+
+```text
+  知识库状态：
+  ✅ docs/knowledge/glossary.md      — 新鲜
+  ⚠️ docs/knowledge/architecture.md  — 部分过时（src/auth/ 路径已变更）
+  ⚠️ docs/knowledge/reference.md     — 缺失（入口引用了但文件不存在）
+  
+  孤儿文件（未被入口引用）：
+  📄 docs/knowledge/old-notes.md     — 存在但不在 AGENTS.md 中
+```
+
+---
+
+### Step 3: 判断新鲜度
+
+**不做任何额外的技术检测**——不加哈希、不加时间戳、不加 front matter。
+
+做法：
+
+1. 读取知识文件的内容
+2. 找出文件中描述的核心模块/文件/概念
+3. 直接读取对应的源代码文件
+4. AI 自行对比：知识描述和实际代码还匹配吗？
+
+**标记规则**：
+
+| 标记 | 含义 | 触发条件 |
+|------|------|---------|
+| ✅ 新鲜 | 描述与代码一致 | 提到的模块存在、结构正确、接口匹配 |
+| ⚠️ 部分过时 | 部分内容不准确 | 路径变了、函数重命名了、部分描述不对 |
+| ❌ 严重过时 | 大部分不匹配 | 被引用的文件不存在、架构发生根本变化 |
+
+**新鲜度判断提示词**（每次判断时在脑中执行）：
+
+> 这个知识文件中描述的模块路径、接口签名、概念定义，和我刚读完的源代码还一致吗？如果不一致，差异有多大？
+
+---
+
+### Step 4: 生成/更新知识文件
+
+**展示可选列表**，让用户勾选需要的类型：
+
+```text
+  可生成的知识文件：
+  [ ] GLOSSARY      — 从代码中推断术语定义
+  [ ] ARCHITECTURE  — 从目录结构和 import 关系分析
+  [ ] CONVENTIONS   — 从代码风格和配置中提取约定
+  [ ] DECISIONS     — 从已归档 change 的 design.md 提取
+  [ ] REFERENCE     — 从导出函数、CLI 参数提取关键接口
+  [ ] HOWTOS        — 从 scripts/ 和常见模式提取操作指南
+
+  默认路径：docs/knowledge/
+```
+
+**用户选择后**，按下方模板为每种类型生成内容。
+
+**生成原则**：
+- 知识文件是纯 Markdown，无 front matter / 元数据
+- 只基于代码中真实存在的内容推断
+- 不确定的地方加上 `<!-- UNVERIFIED: 描述 -->` 注释
+- 每个关键陈述尽量暗示推断来源
+- 内容控制在给 AI 速览的粒度，不写成完整文档
+
+**更新策略**：
+- 已有文件被判定为 ⚠️ 或 ❌ → 询问「保留手写版本 / 用 AI 重新生成 / 跳过」
+- 目标文件不存在 → 直接生成
+
+---
+
+### Step 5: 更新入口文件
+
+生成/更新知识文件后，检查 AGENTS.md 是否包含对应的引用：
+
+- 无需引用的文件 → 追加引用到 AGENTS.md 的对应章节
+- 已有引用 → 确认路径是否正确
+
+```markdown
+# AGENTS.md 中追加的格式：
+
+## 系统架构
+- [架构说明](docs/knowledge/architecture.md)
+```
+
+**冲突处理**：
+
+| 场景 | 处理 |
+|------|------|
+| AGENTS.md 已有内容（非 Specline 创建） | 追加知识索引段落到末尾，不覆盖原有内容 |
+| 知识文件存在但 AGENTS 无引用 | 提示「孤儿文件」，询问是否纳入管理 |
+| 用户手动删了引用 | 不自动恢复，下次扫描时提示 |
+
+---
+
+## Layer 3: 六类知识文件详解
+
+### 术语表 (GLOSSARY)
+
+**文件**：`docs/knowledge/glossary.md`
+
+**推断来源**：
+- `type` / `interface` / `class` / `enum` 定义
+- README 中的概念说明
+- spec 文档中的术语
+
+**生成内容**：
+
+```markdown
+# 术语表
+
+<!-- 以下术语从项目代码中推断，基于类型定义和文档中出现的概念 -->
+
+## <概念名>
+- **是什么**：一句话定义
+- **在哪里**：定义位置（文件:行号）
+- **相关术语**：关联的其他概念
+```
+
+**示例**（以本项目为例）：
+
+```markdown
+# 术语表
+
+## Template
+- **是什么**：Specline 的源文件目录（templates/.cursor/），npm 发布时打包
+- **在哪里**：项目根目录 templates/
+- **相关术语**：.cursor/（运行时副本）、sync（同步机制）
+
+## Change
+- **是什么**：Specline 中的一次变更单元，包含 proposal/design/tasks/specs
+- **在哪里**：specline/changes/<name>/
+- **相关术语**：Pipeline、Archive、Gate
+```
+
+---
+
+### 系统架构 (ARCHITECTURE)
+
+**文件**：`docs/knowledge/architecture.md`
+
+**推断来源**：
+- 顶级目录结构
+- 模块间 import 关系
+- package.json / requirements.txt / go.mod 依赖
+- tsconfig / 项目配置中的模块映射
+
+**生成内容**：
+
+```markdown
+# 系统架构
+
+## 模块地图
+
+### <模块路径> — <模块名>
+<一句话职责描述>
+- 入口: <入口文件>
+- 依赖: <依赖的模块>
+- 被依赖: <哪些模块依赖它>
+
+## 依赖关系图
+
+\`\`\`
+<ASCII 依赖图>
+\`\`\`
+```
+
+---
+
+### 编码约定 (CONVENTIONS)
+
+**文件**：`docs/knowledge/conventions.md`
+
+**推断来源**：
+- `.eslintrc` / `.prettierrc` / `pyproject.toml` 等配置
+- 代码风格的一致性模式
+- 已有的 `.cursor/rules/` 中的规则
+- 错误处理模式、命名约定等
+
+**生成内容**：
+
+```markdown
+# 编码约定
+
+## 代码风格
+- <从配置文件提取的规则>
+
+## 命名约定
+- <从代码模式推断的命名习惯>
+
+## 错误处理
+- <从代码推断的错误处理模式>
+
+## 已有规则
+- <引用 .cursor/rules/ 中的规则文件>
+```
+
+---
+
+### 设计决策 (DECISIONS)
+
+**文件**：`docs/knowledge/decisions/<YYYY-MM-DD-<title>>.md`
+
+**推断来源**：
+- `specline/changes/archive/` 中已归档 change 的 `design.md`
+- 如果项目不使用 Specline → 跳过此类
+
+**生成内容**：
+
+```markdown
+# <决策标题>
+
+- **日期**：YYYY-MM-DD
+- **状态**：已采纳
+- **决策**：<我们做了什么选择>
+- **理由**：<为什么这么选>
+- **替代方案**：<考虑过但放弃的方案及其被放弃的原因>
+- **来源**：<从哪个 change 的 design.md 提取>
+```
+
+---
+
+### API 参考 (REFERENCE)
+
+**文件**：`docs/knowledge/reference.md`
+
+**推断来源**：
+- 导出函数/类/接口的签名
+- CLI 参数定义
+- 配置文件 schema
+- 关键常量和枚举
+
+**生成内容**：
+
+```markdown
+# 关键接口参考
+
+## <函数名 / 类名>
+- **签名**：\`functionName(param: Type) => ReturnType\`
+- **用途**：一句话描述
+- **位置**：文件:行号
+```
+
+**示例**：
+
+```markdown
+# 关键接口参考
+
+## specline-pipeline-gate.sh
+- **入口**：\`specline-pipeline-gate.sh <action> [--change <name>]\`
+- **支持动作**：list / bind / unbind / new / artifacts / check
+- **位置**：.cursor/hooks/specline-pipeline-gate.sh
+```
+
+---
+
+### 操作指南 (HOWTOS)
+
+**文件**：`docs/knowledge/howtos/<主题>.md`
+
+**推断来源**：
+- `scripts/` 目录下的脚本
+- package.json 中的 npm scripts
+- README 中的操作说明
+
+**生成内容**：
+
+```markdown
+# <操作名称>
+
+## 背景
+<什么时候需要做这个操作>
+
+## 步骤
+
+### 1. <步骤名称>
+\`\`\`bash
+<命令>
+\`\`\`
+<预期输出>
+
+### 2. <步骤名称>
+...
+```
+
+---
+
+## Layer 4: 模板
+
+以下模板在生成对应文件时使用。
+
+### AGENTS.md 入口模板
+
+```markdown
+# Project Knowledge Index
+
+> 本文件是面向 AI 的项目知识库导航地图。每个 AI agent 应首先阅读本文件以了解项目上下文。
+> 由 specline-knowledge 管理。
+
+## 系统架构
+- [架构说明](docs/knowledge/architecture.md)
+
+## 术语表
+- [术语定义](docs/knowledge/glossary.md)
+
+## 编码约定
+- [代码约定](docs/knowledge/conventions.md)
+
+## 设计决策
+- [决策记录](docs/knowledge/decisions/)
+
+## API 参考
+- [关键接口](docs/knowledge/reference.md)
+
+## 操作指南
+- [操作指南](docs/knowledge/howtos/)
+```
+
+### 术语表模板
+
+```markdown
+# 术语表
+
+<!-- 以下术语从项目代码中推断生成 -->
+
+## <概念名>
+- **是什么**：<一句话定义>
+- **在哪定义**：<文件路径:行号>
+- **相关术语**：<关联概念>
+```
+
+### 架构模板
+
+```markdown
+# 系统架构
+
+<!-- 以下架构从目录结构和 import 关系推断 -->
+
+## 项目结构
+
+\`\`\`
+<顶级目录树>
+\`\`\`
+
+## 模块地图
+
+### <模块路径> — <模块名称>
+<职责描述>
+- **入口**：<文件>
+- **依赖**：<列表>
+```
+
+### 约定模板
+
+```markdown
+# 编码约定
+
+<!-- 以下约定从代码风格、配置文件和一致性模式中推断 -->
+
+## 代码风格
+- <规则>
+
+## 命名约定
+- <约定>
+
+## 错误处理
+- <模式>
+```
+
+### 决策记录模板
+
+```markdown
+# <决策标题>
+
+- **日期**：YYYY-MM-DD
+- **状态**：已采纳
+- **决策**：<内容>
+- **理由**：<原因>
+- **替代方案**：<被放弃的方案及理由>
+- **来源**：<源文档路径>
+```
+
+### 参考模板
+
+```markdown
+# 关键接口参考
+
+<!-- 以下接口从代码导出中提取 -->
+
+## <名称>
+- **签名**：\`<signature>\`
+- **用途**：<描述>
+- **位置**：<文件:行号>
+```
+
+### 操作指南模板
+
+```markdown
+# <操作名称>
+
+## 背景
+<何时需要此操作>
+
+## 步骤
+1. \`\`\`bash
+   <命令>
+   \`\`\`
+
+## 常见问题
+- <问题及解决>
+```
+
+---
+
+## Layer 5: 异常与边界
+
+### 边界判断
+
+| 情况 | 处理方式 |
+|------|---------|
+| 入口文件不存在且用户拒绝创建 | 结束，提示可随时再次调用 |
+| 入口文件存在但无任何引用链接 | 提示「入口文件未包含任何知识文件引用」，询问是否扫描 `docs/knowledge/` 目录 |
+| 知识文件全部新鲜 | 报告「所有知识文件均为最新 ✓」，结束 |
+| 用户传入的文件参数不存在 | 提示「文件 X 不在入口文件的引用链中」，列出已引用的文件供选择 |
+| AGENTS.md 已有非 specline-knowledge 内容 | 追加知识索引段落，不覆盖原有内容 |
+| 知识文件存在但缺少入口引用 | 标记为孤儿文件，询问是否纳入管理 |
+| 用户手写了知识文件（无 AI 生成标记） | AI 仍可判断新鲜度（读代码对比），更新时询问保留/替换/合并 |
+| 用户项目不使用 Specline（无 changes/archive/） | DECISIONS 类型自动跳过，提示原因 |
+| 项目无 package.json / 无显式模块结构 | ARCHITECTURE 类型降级为目录树 + 文件说明 |
+| 项目代码量极小（< 10 源文件） | 提示「项目规模较小，知识文件可能收益有限」，仍允许生成 |
+
+---
+
+## Anti-Rationalization 表格
+
+| 借口 | 现实 |
+|------|------|
+| 「AI 直接读代码就行，不需要知识文件」 | 代码能告诉你"是什么"，但"为什么"和"全局关系"散落在各处。知识文件给 AI 一张速览地图，节省每次重新扫描的 token 和时间。 |
+| 「新鲜度让用户自己判断吧」 | 用户很难记住「glossary.md 引用了哪几个源文件，那些文件改了没」。AI 并行读取对比是自然优势。 |
+| 「ALL 知识文件都生成一遍，一步到位」 | 不同项目需要不同类型的知识。小型脚本可能只需要 GLOSSARY，大型 monorepo 需要全部六类。让用户选择，别替用户决定。 |
+| 「判断新鲜度时保守一点，不确定就标记 ⚠️」 | 频繁的假过期警报会让用户不信任标记。只有确实发现不一致时才标记 ⚠️，无法判断就说「无法判断」。 |
+| 「给知识文件加上时间戳/hash 更精确」 | 额外的元数据增加认知负担和维护成本。AI 阅读对比代码已经足够好，简单方案就是好方案。 |
+| 「这个文件和 AGENTS.md 的链接断了，自动修」 | AGENTS.md 是用户的主入口文件。自动修改可能覆盖用户的手动编排意图。提示用户，让用户决定。 |
+
+---
+
+## Verification Checklist
+
+技能实现完成后，自查：
+
+- [ ] 入口文件检测优先级正确：AGENTS.md → CLAUDE.md → CURSOR.md → .cursor/rules/
+- [ ] 能正确解析 markdown 链接 `[text](path)` 作为引用链
+- [ ] 新鲜度判断仅靠 AI 阅读理解对比，不添加任何元数据
+- [ ] 六类知识文件（GLOSSARY/ARCHITECTURE/CONVENTIONS/DECISIONS/REFERENCE/HOWTOS）全部支持
+- [ ] 生成的知识文件为纯 Markdown，无 front matter / 元数据
+- [ ] 不确定的内容标记了 `<!-- UNVERIFIED -->`
+- [ ] 与 pipeline/quickfix 无联动，纯手动触发
+- [ ] 支持按需检查（指定文件名）和全量扫描两种模式
+- [ ] 冲突处理覆盖：已有入口文件、已有同名知识文件、孤儿文件
+- [ ] 未覆盖/不适用的情况有降级策略（代码量极小、无模块结构等）

package/templates/.cursor/skills/specline-pipeline/SKILL.md

@@ -72,6 +72,73 @@ Session 通过 `specline-pipeline-gate.sh bind <session_id> <change>` 绑定到
 
 ---
 
+## Core Operating Behaviors
+
+以下守则对编排者自身和所有派发的子 Agent 均生效。编排者在决策（跳过 Gate、手动修复、忽略警告）时同样接受这些守则的约束。
+
+### 1. Surface Assumptions
+
+执行任何非平凡操作前，显式列出假设：
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [关于需求的假设]
+2. [关于架构的假设]
+3. [关于范围的假设]
+→ 现在纠正，否则我将按这些假设继续。
+```
+
+不要默默填补模糊需求。错误的假设是最昂贵的返工来源。
+
+### 2. Manage Confusion Actively
+
+遇到矛盾、冲突需求或模糊规范时：
+
+1. **STOP** — 不要猜
+2. 明确命名具体困惑点
+3. 呈现权衡或提出澄清问题
+4. 等待解决后再继续
+
+**错误做法**：默默选择一种解释，祈祷它是正确的。
+**正确做法**："Spec 说 X 但现有代码是 Y。以哪个为准？"
+
+### 3. Push Back When Warranted
+
+你不是应声虫。当一个方案有明显问题时：
+
+- 直接指出问题
+- 解释具体代价（量化："这会增加 ~200ms 延迟"，而非"可能变慢"）
+- 提出替代方案
+- 如果用户在有完整信息的情况下仍然坚持，接受决定
+
+谄媚是失败模式。"当然可以！"然后实现一个糟糕的方案对谁都没好处。
+
+### 4. Enforce Simplicity
+
+主动抵抗复杂化的自然倾向。完成任何实现前问自己：
+
+- 可以用更少的行数实现吗？
+- 这些抽象真的值得它们的复杂度吗？
+- 一个资深工程师看了会说"你为什么不直接……"吗？
+
+1000 行能做的事用了 100 行是成功，100 行能做的事用了 1000 行是失败。
+
+### 5. Maintain Scope Discipline
+
+只碰你被要求碰的。不：
+- "清理"与你任务无关的代码
+- 顺便重构相邻系统
+- 删除看起来没用的代码（未经明确批准）
+- 添加 Spec 中没有的"看起来有用"的功能
+
+你的工作是外科手术式精确修改，不是主动翻新。
+
+### 6. Verify, Don't Assume
+
+"看起来对"永远不够——必须有证据（通过的测试、构建输出、运行时数据）。编排者自身在 Gate 决策中也不例外：Gate 脚本的 exit code 是唯一判断依据，"看着应该通过了"不算数。
+
+---
+
 ## Layer 2: Happy Path — 新建流水线
 
 ### Phase 1: SPEC
@@ -149,7 +216,7 @@ Human Gate 1 具体交互：使用 `AskUserQuestion`，title="确认 Spec 和任
 
 ### Phase 2: CODING
 
-> **并行加速**：Human Gate 1 通过后，**同时**启动 coding 和 specline-test-writer。specline-test-writer 是黑盒的——只需要 Spec 文档，不需要实现代码。两者并行可节省 specline-test-writer 的编写时间。
+> **并行加速**：Human Gate 1 通过后，**同时**启动 coding 和 specline-test-writer。specline-test-writer 是黑盒的——读取 Spec（验收标准）和 design.md（对外接口契约），不需要实现代码。两者并行可节省 specline-test-writer 的编写时间。
 
 #### Step 6: 并行启动（test-writer + DAG 构建）
 
@@ -171,7 +238,7 @@ Track A 和 Track B 同时启动，互不阻塞。test-writer 在 Coding 全部
 
 **6a. 启动 specline-test-writer（与 Coding 阶段 Agent 同时启动）**：
 
-使用 Task 工具，subagent_type="specline-test-writer"，prompt 中包含 changeName/Spec/Tasks 路径和黑盒约束。specline-test-writer 只编写 tests/integration/** 和 tests/e2e/** 下的测试，产出 test-code-result.json。
+使用 Task 工具，subagent_type="specline-test-writer"，prompt 中包含 changeName/Spec/Design/Tasks 路径和黑盒约束。test-writer 从 `design.md` 的「对外接口契约」章节获取 CLI 命令/HTTP 端点/模块导出签名（若章节不存在则在 prompt 中注明无需契约），从 spec.md 获取行为验收标准（WHEN/THEN）。specline-test-writer 只编写 tests/integration/** 和 tests/e2e/** 下的测试，产出 test-code-result.json。
 
 **6b. 解析 tasks.md，构建任务 DAG**：
 
@@ -246,6 +313,10 @@ sed -i '' "s/^## ${task_id}\. \[ \]/## ${task_id}. [x]/" specline/changes/<name>
 Build Gate 校验内容：
 - 编译/语法检查（原有逻辑）
 - **单元测试文件存在性检查**（新增）：对 Testable=true 的任务，检查其 `tests/unit/` 和 `tests/models/` 下的单元测试文件是否存在且语法正确。如果 Testable=true 的任务未产出对应测试文件，Build Gate 失败
+- **对外接口契约签名检查**（新增）：以 tasks.md 为决策源头——仅当 tasks.md 末尾「测试文件归属」表格中存在 specline-test-writer 负责的测试时，才检查 design.md 的「对外接口契约」章节：
+  - 有 test-writer 任务但缺契约章节 → 阻断（报错：缺契约）
+  - 有契约 → 逐项检查 CLI 命令注册、HTTP 路径注册、模块导出声明是否存在（只检查签名存在性，不检查语义正确性）
+  - 无 test-writer 任务 → 跳过
 
 exit code 0 = 通过，进入 Phase 3。失败处理见 [Layer 3: Build Gate 失败处理](#build-gate-失败处理)。
 
@@ -309,7 +380,7 @@ specline-test-writer 已在 Phase 2（Step 6a）与 Coding 并行启动。进入
 
 > `test_framework` 写入状态文件后，后续 `specline-pipeline-gate.sh` 的 test gate 会自动读取并选择正确的测试命令（Jest/pytest/go test 等）。
 
-> **黑盒约束回顾**：specline-test-writer 只能基于 Spec 文档编写测试，不能读取任何实现源代码。specline-test-writer 会自动检测项目测试框架（Jest/pytest/go test 等），按项目实际语言编写测试。
+> **黑盒约束回顾**：specline-test-writer 只能基于 Spec 文档（验收标准）和 design.md 的「对外接口契约」章节（接口签名）编写测试，不能读取任何实现源代码。specline-test-writer 会自动检测项目测试框架（Jest/pytest/go test 等），按项目实际语言编写测试。
 
 #### Step 13: 测试门禁链（串行）
 
@@ -353,6 +424,7 @@ specline-pipeline-gate.sh archive --execute --change "<name>"
 4. **Gate 重置**：`jq '...gate.passed = null' "$STATE_FILE"`
 5. **特殊规则**：
    - `spec_ambiguity` → 暂停流水线展示模糊点（minimal/none 策略下降级为 WARNING）
+   - `contract_mismatch` → 优先回 coding agent 按契约修正（最多 2 次）；2 次后仍不一致 → 暂停并报告用户确认
    - 接口不兼容 → 只重置受影响的下游任务（保留未受影响任务的状态）
    - Hook 阻断 → 先诊断原因 → 与用户沟通（AskUserQuestion）→ 修复后重试 → 绝不静默降级
    - 测试失败优先级：单元测试优先于集成/E2E
@@ -375,6 +447,7 @@ specline-pipeline-gate.sh archive --execute --change "<name>"
 - **集成/E2E 测试失败**（`tests/integration/` / `tests/e2e/`）：先判断是测试代码还是实现代码问题
   - 测试代码问题 → specline-test-writer 自修（最多 2 次）
   - 实现代码问题 → Covers 追溯定位 → 回 coding agent 修复 → 用影响范围算法重置受影响 Gate
+  - **契约不一致** (`contract_mismatch`)：实现代码的对外接口与 design.md 契约不一致 → 优先回 coding agent 按契约修正代码（最多 2 次）；若 2 次后仍不一致，暂停并报告用户确认以 design.md 契约为准还是以代码为准
   - Gate 重置：`.phases.test.sub_phases.integration.gates.test_integration_gate.passed = null | .phases.test.sub_phases.e2e.gates.test_e2e_gate.passed = null`
 - **优先级**：单元测试失败优先修复；代码修复后所有测试 Gate 全部重置
 
@@ -515,3 +588,29 @@ AskUserQuestion({
 - State Schema → 详见 `references/pipeline-state-schema.md`
 - Event Log → 详见 `references/event-log-spec.md`
 - Hook & Constraints → 详见 `references/error-recovery-details.md`
+
+---
+
+## Anti-Rationalization 表格
+
+编排者在运作流水线时会找借口跳过步骤。以下是常见借口及其反驳：
+
+| 借口 | 现实 |
+|------|------|
+| "这需求太简单了，不需要 Spec" | 简单需求也有隐含假设。Spec 的价值在于暴露假设，与复杂度无关。 |
+| "Gate 跳过一次没关系" | Gate 是确定性脚本，跳过意味着自动化防线失效。一次跳过会变成习惯。 |
+| "手工改一下比回子 Agent 修复快" | 手工改绕过了 Covers 追溯链和影响范围算法，下次断点续跑会丢失上下文。 |
+| "测试最后一起跑" | Bug 会复合。阶段 1 的 Bug 让阶段 2-5 的产出都不可靠。每个阶段验证，不是事后验证。 |
+| "HG 确认我替用户点了吧" | Human Gate 存在是因为这些决策需要人的判断。替用户确认等于架空人机门禁。 |
+| "Build 失败看起来是子 Agent 的问题，我先继续往下" | 错误会传播。修复当前阶段再向下，否则下游建立在错误的基座上。 |
+| "影响范围看起来不大，全重置就行" | 接口不兼容只应重置受影响的下游任务。全重置浪费已完成的工作，且破坏断点续跑的状态完整性。 |
+
+## Verification Checklist
+
+每阶段完成后，编排者自查：
+
+- [ ] **SPEC 阶段**：4 Artifact 齐全（proposal/design/tasks/specs）；Spec Gate 通过；HG1 已确认；spec-review.json status=approved
+- [ ] **CODING 阶段**：全部批次完成；每个 task 产出报告存在；tasks.md checkbox 全部 [x]；Build Gate 通过（含契约签名检查）；Testable=true 任务的 test_files 非空
+- [ ] **CODE REVIEW 阶段**：code-review.json 存在；error 计数 = 0；Lint Gate 通过；HG2 已处理
+- [ ] **TEST 阶段**：test_framework 已写入状态文件；test-unit/integration/e2e Gate 全绿
+- [ ] **ARCHIVE 阶段**：HG3 已确认；归档目录已创建；session 绑定已解除；Delta spec sync 决策已完成