specline 2.0.1 → 2.0.3

package/core/skills/specline-pipeline/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 ---
 
-## Layer 0: Session 绑定
+## 第 0 层：Session 绑定
 
 Session 通过 `specline gate bind <session_id> <change>` 绑定到 Pipeline。
 绑定后 sessionStart Hook 自动注入阶段上下文，归档时自动解绑。
@@ -17,7 +17,7 @@ Session 通过 `specline gate bind <session_id> <change>` 绑定到 Pipeline。
 
 ---
 
-## Layer 1: 速览与定位
+## 第 1 层：速览与定位
 
 你是**流水线编排者**，不是执行者。
 
@@ -30,7 +30,7 @@ Session 通过 `specline gate bind <session_id> <change>` 绑定到 Pipeline。
 **你不做：**
 - 需求判断/Spec 编写、代码编写、代码审查、测试编写、门禁判断——这些都交给子 Agent 和 Gate 脚本
 
-### Phase 流程图
+### 阶段流程图
 
 ```
     SPEC ──→ CODING ──→ CODE REVIEW ──→ TEST ──→ ARCHIVE
@@ -56,6 +56,13 @@ Session 通过 `specline gate bind <session_id> <change>` 绑定到 Pipeline。
 
 **子 Agent 确认行为**：当策略为 `minimal` 或 `none` 时，编排者应在派发子 Agent 时传递 `HUMAN_GATE_POLICY=<policy>` 上下文，告知子 Agent 跳过所有 {{CONFIRM}} 交互（如 spec_ambiguity 暂停、skill 级确认等），直接采用默认安全选项继续执行。编排者自身在测试失败处理中的 spec_ambiguity 暂停也应改为记录 WARNING 事件日志后继续。
 
+**SPEC 澄清中断行为**：`pipeline.human_gate_policy` 同时控制 SPEC 阶段 Ambiguity Scan 是否可以打断用户：
+- `full`：仅在 blocking ambiguity 存在时允许打断，最多 1-3 个聚焦问题；HG1 必须展示确认过的决策、假设、未解决项和 warning default。
+- `minimal`：不打断用户；采用安全推荐默认值继续，并把 warning default、假设和风险写入 `clarification_context`，HG1 自动通过时记录 WARNING 事件。
+- `none`：不打断用户；只记录假设、风险和 deferred questions，不要求用户确认，也不引入任何 {{CONFIRM}}。
+
+普通 `/specline-pipeline` 请求默认保持自动化，不展示默认问卷。只有用户明确要求 `strict`、`grill`、深度追问或面试式澄清时，才进入扩展澄清预算；即使在 strict/grill 路径，每个问题也必须是决策型问题，包含推荐答案和选项。
+
 ### 入口模式
 
 1. **新建流水线**: `/specline-pipeline <自然语言需求>`
@@ -64,7 +71,9 @@ Session 通过 `specline gate bind <session_id> <change>` 绑定到 Pipeline。
 
 ### 最终产出
 
-归档到 `specline/changes/archive/YYYY-MM-DD-<name>/`
+归档到 `specline/changes/archive/YYYY-MM-DD-<name>/`。
+
+归档完成后，如果本次 change 包含重大架构、接口、工作流或设计决策影响，可能由 `specline-archive-change` 提示用户是否将相关内容更新到项目知识库。该动作发生在归档成功之后，用户可跳过，不影响 pipeline 成功状态。
 
 ### Quickfix vs Pipeline 边界判断
 
@@ -72,16 +81,16 @@ Session 通过 `specline gate bind <session_id> <change>` 绑定到 Pipeline。
 
 ---
 
-## Core Operating Behaviors
+## 核心行为守则
 
 以下守则对编排者自身和所有派发的子 Agent 均生效。编排者在决策（跳过 Gate、手动修复、忽略警告）时同样接受这些守则的约束。
 
-### 1. Surface Assumptions
+### 1. 显式暴露假设
 
 执行任何非平凡操作前，显式列出假设：
 
 ```
-ASSUMPTIONS I'M MAKING:
+我当前基于这些假设继续：
 1. [关于需求的假设]
 2. [关于架构的假设]
 3. [关于范围的假设]
@@ -90,7 +99,7 @@ ASSUMPTIONS I'M MAKING:
 
 不要默默填补模糊需求。错误的假设是最昂贵的返工来源。
 
-### 2. Manage Confusion Actively
+### 2. 主动处理困惑
 
 遇到矛盾、冲突需求或模糊规范时：
 
@@ -102,7 +111,7 @@ ASSUMPTIONS I'M MAKING:
 **错误做法**：默默选择一种解释，祈祷它是正确的。
 **正确做法**："Spec 说 X 但现有代码是 Y。以哪个为准？"
 
-### 3. Push Back When Warranted
+### 3. 必要时提出异议
 
 你不是应声虫。当一个方案有明显问题时：
 
@@ -113,7 +122,7 @@ ASSUMPTIONS I'M MAKING:
 
 谄媚是失败模式。"当然可以！"然后实现一个糟糕的方案对谁都没好处。
 
-### 4. Enforce Simplicity
+### 4. 坚持简单性
 
 主动抵抗复杂化的自然倾向。完成任何实现前问自己：
 
@@ -123,7 +132,7 @@ ASSUMPTIONS I'M MAKING:
 
 1000 行能做的事用了 100 行是成功，100 行能做的事用了 1000 行是失败。
 
-### 5. Maintain Scope Discipline
+### 5. 维护范围纪律
 
 只碰你被要求碰的。不：
 - "清理"与你任务无关的代码
@@ -133,17 +142,17 @@ ASSUMPTIONS I'M MAKING:
 
 你的工作是外科手术式精确修改，不是主动翻新。
 
-### 6. Verify, Don't Assume
+### 6. 验证，不靠猜测
 
 "看起来对"永远不够——必须有证据（通过的测试、构建输出、运行时数据）。编排者自身在 Gate 决策中也不例外：Gate 脚本的 exit code 是唯一判断依据，"看着应该通过了"不算数。
 
 ---
 
-## Layer 2: Happy Path — 新建流水线
+## 第 2 层：新建流水线主流程
 
-### Phase 1: SPEC
+### 阶段 1：SPEC
 
-#### Step 1: 创建 Change
+#### 步骤 1：创建 Change
 
 ```bash
 specline gate new --change "<kebab-case-name>"
@@ -160,7 +169,50 @@ specline gate new --change "<kebab-case-name>"
 
 > 📋 完整 JSON Schema 见 [附录 A](#附录-a-pipeline-statejson-完整-schema)
 
-#### Step 2: 启动 specline-spec-creator
+#### 步骤 2：Ambiguity Scan（风险触发，不是默认问卷）
+
+在启动 `specline-spec-creator` 前，编排者先做一次轻量 Ambiguity Scan。它只判断用户需求中是否存在会改变实现方向的模糊点，不把正常缺省信息变成问卷。
+
+分类规则：
+
+1. **Default path（无实质模糊）**：如果现有需求足以选择实现方向，直接进入步骤 3，不提问，也不传额外澄清上下文。
+2. **Non-blocking ambiguity（非阻断模糊）**：如果不确定性不会改变实现方向、公开行为、数据模型、安全姿态、兼容性或任务排序，则记录为 assumptions/risks，继续进入步骤 3，不打断用户。
+3. **Blocking ambiguity（阻断模糊）**：仅当不问清楚可能改变实现方向、公开行为、数据模型、安全姿态、兼容性或任务排序时才判定为 blocking。
+4. **Explicit strict/grill path（显式严格澄清）**：只有用户明确要求 strict、grill、深度追问或面试式澄清时，才扩大问题预算；普通 pipeline 请求绝不自动进入该路径。
+
+Blocking ambiguity 的处理由 `pipeline.human_gate_policy` 决定：
+
+- `full`：可以先问 1-3 个聚焦问题。每个问题必须说明被决定的事项、为什么会改变实现方向、推荐答案、小选项集，以及如果后续必须继续时采用的默认值。
+- `minimal`：不得打断用户。采用安全推荐默认值继续，把默认值、理由和风险作为 warning default 写入 `clarification_context`，并在 HG1 自动通过时记录 warning/assumption。
+- `none`：不得打断用户。只记录 assumptions、risks 和 deferred questions，不把默认值包装成用户已确认决策。
+
+若 Ambiguity Scan 产生上下文，传给 `specline-spec-creator` 的 prompt 中必须包含：
+
+```yaml
+clarification_context:
+  risk_level: none | low | medium | high
+  confirmed_decisions:
+    - decision: "..."
+      source: "user"
+  assumed_decisions:
+    - decision: "..."
+      recommended_answer: "..."
+      rationale: "..."
+      risk: "..."
+      policy: "full|minimal|none"
+  deferred_questions:
+    - question: "..."
+      default: "..."
+      reason_deferred: "..."
+      implementation_constraint: "..."
+      blocking: true|false
+  warnings:
+    - "..."
+```
+
+约束：`confirmed_decisions` 只能放用户明确回答或明确同意的内容；`minimal` 和 `none` 模式下不得制造用户中断，必须把未确认内容记录为 assumption、warning 或 deferred question。
+
+#### 步骤 3：启动 specline-spec-creator
 
 specline-spec-creator 子 Agent 的职责是根据内联模板直接生成全部规划文件：
 - `proposal.md` — 需求提案（What/Why/Scope）
@@ -168,7 +220,7 @@ specline-spec-creator 子 Agent 的职责是根据内联模板直接生成全部
 - `tasks.md` — 任务拆解清单（含 Type/Depends/Covers/Files 标注）
 - `specs/<capability>/spec.md` — 功能规格（Requirements/Scenarios）
 
-{{DISPATCH}}，role="specline-spec-creator"，描述中传入 change name 和自然语言需求，让 specline-spec-creator 根据内联模板直接生成。
+{{DISPATCH}}，role="specline-spec-creator"，描述中传入 change name、自然语言需求、`HUMAN_GATE_POLICY=<policy>`，以及 Ambiguity Scan 产生的可选 `clarification_context`。让 specline-spec-creator 根据内联模板直接生成，并把 confirmed decisions、assumptions、deferred questions、risk level 和 warnings 写入规划 Artifact。
 
 > **任务标注规范**：tasks.md 每个任务必须包含：
 > - `Type`: frontend | backend | infra | db | config | docs
@@ -185,7 +237,7 @@ NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 jq --arg time "$NOW" '.updated_at = $time | .phases.spec.sub_phases["specline-spec-creator"] = {"status": "completed", "completed_at": $time}' "$STATE_FILE" > tmp && mv tmp "$STATE_FILE"
 ```
 
-#### Step 3: 审核全部规划文件（specline-spec-reviewer）
+#### 步骤 4：审核全部规划文件（specline-spec-reviewer）
 
 specline-spec-reviewer 审核三份文件：
 1. `specs/` 下所有 spec.md 的完整性和一致性
@@ -196,7 +248,7 @@ specline-spec-reviewer 审核三份文件：
 
 若 rejected：将 feedback 反馈给用户修改，或手动编辑相应文件后重新审核（最多 3 次循环）。
 
-#### Step 4: Spec Gate
+#### 步骤 5：Spec Gate
 
 ```bash
 specline gate spec --change "<name>"
@@ -206,19 +258,23 @@ specline gate spec --change "<name>"
 
 exit code 0 = 通过，写入 passed。exit code != 0 = 失败，读取 stderr 展示给用户。
 
-#### Step 5: 人工确认 (Human Gate 1) 🟡
+#### 步骤 6：人工确认 (Human Gate 1) 🟡
+
+> **策略判断**：读取 `specline/config.yaml` → `pipeline.human_gate_policy`。若为 `minimal` 或 `none` → 跳过此 HG，直接写入 `human_gate_1.passed = true`，进入阶段 2；同时把 `clarification_context` 中的 assumptions、deferred questions、warning defaults 和风险摘要记录到事件日志或阶段摘要，不能静默丢弃。
 
-> **策略判断**：读取 `specline/config.yaml` → `pipeline.human_gate_policy`。若为 `minimal` 或 `none` → 跳过此 HG，直接写入 `human_gate_1.passed = true`，进入 Phase 2。
+Spec Gate 通过后，`full` 策略使用 {{CONFIRM}} 请求确认。展示内容包括：需求提案摘要、功能需求列表、任务拆解概览（含并行组），以及 Ambiguity Scan/Spec Creator 产出的：
 
-Spec Gate 通过后，使用 {{CONFIRM}} 请求确认。展示内容包括：需求提案摘要、功能需求列表、任务拆解概览（含并行组）。
+- 用户已确认的关键决策。
+- 未经确认但将采用的 assumptions 和 recommended defaults。
+- deferred questions、unresolved items、warning defaults 及其实现风险。
 
-Human Gate 1 具体交互：使用 {{CONFIRM}}，title="确认 Spec 和任务规划"，选项：`approve`（确认通过，继续编码）/ `reject`（不通过，手动修改后重新审核）。
+Human Gate 1 具体交互：使用 {{CONFIRM}}，title="确认 Spec 和任务规划"，选项：`approve`（确认通过，继续编码）/ `reject`（不通过，手动修改后重新审核）。若 HG1 因 `minimal` 或 `none` 跳过，编排者不得补问用户；只记录 warnings/assumptions，并保证后续 reviewer/gate 能看到这些风险。
 
-### Phase 2: CODING
+### 阶段 2：CODING
 
 > **并行加速**：Human Gate 1 通过后，**同时**启动 coding 和 specline-test-writer。specline-test-writer 是黑盒的——读取 Spec（验收标准）和 design.md（对外接口契约），不需要实现代码。两者并行可节省 specline-test-writer 的编写时间。
 
-#### Step 6: 并行启动（test-writer + DAG 构建）
+#### 步骤 6：并行启动（test-writer + DAG 构建）
 
 时序图：
 
@@ -231,7 +287,7 @@ Track A (test-writer):
 Track B (coding):
   6b 解析 tasks.md ──→ 6c 冲突检测 ──→ 7a 派发批次1 ──→ 7b 更新状态 ──→ 7c 派发批次2...
                                                                                     ↓
-                                                                            Step 8: Build Gate
+                                                                            步骤 8：Build Gate
 
 Track A 和 Track B 同时启动，互不阻塞。test-writer 在 Coding 全部完成后、TEST 阶段前被检查（Step 12）。
 ```
@@ -256,7 +312,7 @@ Track A 和 Track B 同时启动，互不阻塞。test-writer 在 Coding 全部
 
 将当前批次所有任务的 `Files` 按路径前缀分为三类（`implementation` / `unit_test` / `other_test`），同类型文件重叠视为冲突。跨类型重叠不冲突（测试目录与实现目录天然隔离）。
 
-#### Step 7: 按 Type 分组后并发派发 Coding Agent
+#### 步骤 7：按 Type 分组后并发派发 Coding Agent
 
 对每个批次依次处理：
 
@@ -320,7 +376,7 @@ sed -i '' "s/^## ${task_id}\. \[ \]/## ${task_id}. [x]/" specline/changes/<name>
 
 **7c. 检查是否有下一批次**。如有，回到 6c（冲突检测）→ 7a 继续派发。
 
-#### Step 8: Build Gate
+#### 步骤 8：Build Gate
 
 全部批次完成后，运行 Build Gate：
 
@@ -336,11 +392,11 @@ Build Gate 校验内容：
   - 有契约 → 逐项检查 CLI 命令注册、HTTP 路径注册、模块导出声明是否存在（只检查签名存在性，不检查语义正确性）
   - 无 test-writer 任务 → 跳过
 
-exit code 0 = 通过，进入 Phase 3。失败处理见 [Layer 3: Build Gate 失败处理](#build-gate-失败处理)。
+exit code 0 = 通过，进入阶段 3。失败处理见 [第 3 层：异常与恢复](#第-3-层异常与恢复)。
 
-### Phase 3: CODE REVIEW
+### 阶段 3：CODE REVIEW
 
-#### Step 9: 启动审查 Agent
+#### 步骤 9：启动审查 Agent
 
 根据 tasks.md 中任务类型决定审查方式：
 
@@ -364,7 +420,7 @@ code-review.json 中 unit test 相关的 finding 标注 `type` 为 `"unit_test_q
 
 > 两种审查 Agent 可并发启动。产出均为 `specline/changes/<name>/.tmp/code-review.json`（`{ "findings": [{ "severity": "error"|"warning", "type": "unit_test_quality"|"style"|"security"|"logic", "file": "...", "covers": "Requirement: xxx", "message": "..." }] }`）。
 
-#### Step 10: Lint Gate
+#### 步骤 10：Lint Gate
 
 ```bash
 specline gate lint --change "<name>"
@@ -374,19 +430,19 @@ specline gate lint --change "<name>"
 
 失败 → 根据 findings 的 `file` 和 `covers` 字段定位到具体任务，只回对应 coding agent 修复（最多 2 次）。
 
-#### Step 11: 可选人工复核 (Human Gate 2) 🟡
+#### 步骤 11：可选人工复核 (Human Gate 2) 🟡
 
-> **策略判断**：读取 `specline/config.yaml` → `pipeline.human_gate_policy`。若为 `minimal` 或 `none` → 跳过此 HG，直接写入 `human_gate_2.passed = true`，进入 Phase 4。
+> **策略判断**：读取 `specline/config.yaml` → `pipeline.human_gate_policy`。若为 `minimal` 或 `none` → 跳过此 HG，直接写入 `human_gate_2.passed = true`，进入阶段 4。
 
 仅当 code-review.json 中 warnings > 0 且 errors = 0 时，使用 {{CONFIRM}} 询问是否人工复核（`skip` 自动继续 / `review` 展示警告详情）。
 
-### Phase 4: TEST
+### 阶段 4：TEST
 
 > **config/docs 跳过测试**：如果 tasks.md 中所有任务均为 `Type: config` 或 `Type: docs`（无应用代码变更），TEST 阶段自动跳过——test-unit/integration/e2e Gate 在无测试目录时自动放行。流水线直接从 CODE REVIEW 进入 ARCHIVE。
 
-#### Step 12: 确认 specline-test-writer 完成
+#### 步骤 12：确认 specline-test-writer 完成
 
-specline-test-writer 已在 Phase 2（Step 6a）与 Coding 并行启动。进入 TEST 阶段时，检查 specline-test-writer 是否已完成：
+specline-test-writer 已在 阶段 2（步骤 6a）与 Coding 并行启动。进入 TEST 阶段时，检查 specline-test-writer 是否已完成：
 
 - 已完成 → 读取 `specline/changes/<name>/.tmp/test-code-result.json` 获取 `test_framework`，写入 `.pipeline-state.json`：
   ```bash
@@ -400,7 +456,7 @@ specline-test-writer 已在 Phase 2（Step 6a）与 Coding 并行启动。进入
 
 > **黑盒约束回顾**：specline-test-writer 只能基于 Spec 文档（验收标准）和 design.md 的「对外接口契约」章节（接口签名）编写测试，不能读取任何实现源代码。specline-test-writer 会自动检测项目测试框架（Jest/pytest/go test 等），按项目实际语言编写测试。
 
-#### Step 13: 测试门禁链（串行）
+#### 步骤 13：测试门禁链（串行）
 
 ```bash
 # 单元测试
@@ -411,17 +467,17 @@ specline gate test-integration --change "<name>"
 specline gate test-e2e --change "<name>"
 ```
 
-exit code 全 0 = 通过，进入 Phase 5。失败处理见 [Layer 3: 测试失败处理](#测试失败处理)。
+exit code 全 0 = 通过，进入阶段 5。失败处理见 [第 3 层：异常与恢复](#第-3-层异常与恢复)。
 
-### Phase 5: ARCHIVE
+### 阶段 5：ARCHIVE
 
-#### Step 14: 归档确认 (Human Gate 3) 🟡
+#### 步骤 14：归档确认 (Human Gate 3) 🟡
 
 > **策略判断**：读取 `specline/config.yaml` → `pipeline.human_gate_policy`。若为 `none` → 跳过此 HG，直接写入 `human_gate_3.passed = true`，执行归档。`minimal` 策略下 HG3 保留人工确认。
 
 全部测试通过后，使用 {{CONFIRM}} 请求归档确认（`archive` 执行归档 / `cancel` 暂停流水线）。
 
-#### Step 15: 归档
+#### 步骤 15：归档
 
 ```bash
 specline gate archive --execute --change "<name>"
@@ -429,6 +485,8 @@ specline gate archive --change "<name>"
 ```
 
 > 归档的详细逻辑（Delta spec sync 决策、目录移动、摘要展示）由 **specline-archive-change** Skill 负责。编排者只需确认 Human Gate 3 通过后调用上述归档命令。
+>
+> 归档成功后，**specline-archive-change** 可能执行“归档后知识库更新建议”。该动作是可选的，必须由用户确认，且绝不阻塞 pipeline 完成；项目存在 `specline-knowledge` 结构时可使用它，否则应询问其他知识落点。
 
 ---
 
@@ -449,7 +507,7 @@ specline gate archive --change "<name>"
 
 ---
 
-## Layer 3: 异常与恢复
+## 第 3 层：异常与恢复
 
 ### Build 失败差异化处理
 
@@ -569,7 +627,7 @@ done
 
 ---
 
-## Layer 4: 参考文档
+## 第 4 层：参考文档
 
 > 以下文档为完整参考信息，根据需要查阅：
 
@@ -593,11 +651,11 @@ done
 | "Build 失败看起来是子 Agent 的问题，我先继续往下" | 错误会传播。修复当前阶段再向下，否则下游建立在错误的基座上。 |
 | "影响范围看起来不大，全重置就行" | 接口不兼容只应重置受影响的下游任务。全重置浪费已完成的工作，且破坏断点续跑的状态完整性。 |
 
-## Verification Checklist
+## 验证清单
 
 每阶段完成后，编排者自查：
 
-- [ ] **SPEC 阶段**：4 Artifact 齐全（proposal/design/tasks/specs）；Spec Gate 通过；HG1 已确认；spec-review.json status=approved
+- [ ] **SPEC 阶段**：4 Artifact 齐全（proposal/design/tasks/specs）；Ambiguity Scan 已完成且必要的 `clarification_context` 已传递；Spec Gate 通过；HG1 已确认或按策略记录 warnings/assumptions 后跳过；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 全绿

package/core/skills/specline-pipeline/references/event-log-spec.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-定义 Pipeline 编排者写入状态和事件日志的规范——谁在何时写入什么内容。这是编排者在 SPE 编码阶段（Step 7）和异常恢复阶段（Layer 3）写入 `.pipeline-state.json` 和 `pipeline-events.jsonl` 时必须遵循的规则。
+定义 Pipeline 编排者写入状态和事件日志的规范——谁在何时写入什么内容。这是编排者在 SPE 编码阶段（步骤 7）和异常恢复阶段（第 3 层）写入 `.pipeline-state.json` 和 `pipeline-events.jsonl` 时必须遵循的规则。
 
 ## 状态写入规则
 

package/core/skills/specline-pipeline/templates/subagent-prompts.md

@@ -2,11 +2,11 @@
 
 ## Purpose
 
-4 套子 Agent prompt 模板，供 SKILL.md Step 7 的编排者按需读取。编排者根据 `task.type` 和 `task.testable` 选择对应模板，填充 `${变量}` 后作为子 Agent 的 prompt。
+4 套子 Agent prompt 模板，供 SKILL.md 步骤 7 的编排者按需读取。编排者根据 `task.type` 和 `task.testable` 选择对应模板，填充 `${变量}` 后作为子 Agent 的 prompt。
 
 ## 使用说明
 
-编排者在 Step 7 中执行以下逻辑：
+编排者在步骤 7 中执行以下逻辑：
 
 1. 读取本文件（`templates/subagent-prompts.md`）
 2. 根据 `task.type` 和 `task.testable` 选择模板：
@@ -120,7 +120,7 @@
 1. 分析 Spec 中本任务覆盖的 Scenario，提取需要测试的逻辑单元
 2. 在 tests/unit/<module>/test_<feature>.{ext} 下编写测试文件
 3. 每个 Scenario 至少 1 个测试函数/方法
-4. 覆盖：Happy Path + 边界条件（空值、极值、边界值）+ 异常路径（错误输入、异常状态）
+4. 覆盖：正常路径（Happy Path）+ 边界条件（空值、极值、边界值）+ 异常路径（错误输入、异常状态）
 5. 运行测试，确认全部 FAIL（RED）
 
 ### GREEN 阶段

package/core/skills/specline-propose/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   直接按内联模板创建全部 Artifact，不依赖外部 CLI。
 ---
 
-## Layer 1: TL;DR
+## 第 1 层：速览
 
 > **一句话**：根据自然语言需求生成完整的 Spec 规划文件。
 > **入口**：`/specline-pipeline <需求>` 或由编排者通过 Task 工具派发
@@ -28,15 +28,15 @@ specline/changes/<change-name>/
 
 ---
 
-## Layer 2: Happy Path
+## 第 2 层：主流程
 
-**Input**: 用户需求描述（自然语言），由编排者传入 change-name。
+**输入**：用户需求描述（自然语言），由编排者传入 change-name。
 
-### Step 1: 理解需求并推导 change name
+### 步骤 1：理解需求并推导 change name
 
 如果编排者没有传入明确的 change name，从需求描述推导 kebab-case 名称（如 "添加用户登录功能" → `add-user-login`）。
 
-### Step 2: 创建 Change 目录
+### 步骤 2：创建 Change 目录
 
 ```bash
 specline gate new --change "<name>"
@@ -44,7 +44,7 @@ specline gate new --change "<name>"
 
 创建 `specline/changes/<name>/` 目录及必要的元数据文件。
 
-### Step 3: 按顺序生成 4 个 Artifact
+### 步骤 3：按顺序生成 4 个 Artifact
 
 | 顺序 | Artifact | 路径 | 内容要点 |
 |------|----------|------|---------|
@@ -63,7 +63,7 @@ specline gate new --change "<name>"
 
   还包括：Impact（影响哪些系统）
 
-- **spec.md**：H1 标题含 "Specification"，包含 `## Purpose` 和 `## Requirements`，每个 Requirement 至少 1 个 Scenario，每个 Scenario 含 `**WHEN**`/`**THEN**` 配对，至少覆盖 Happy Path 和 1 个异常场景
+- **spec.md**：H1 标题含 "Specification"，包含 `## Purpose` 和 `## Requirements`，每个 Requirement 至少 1 个 Scenario，每个 Scenario 含 `**WHEN**`/`**THEN**` 配对，至少覆盖正常路径（Happy Path）和 1 个异常场景
 
 - **design.md**：包含 Architecture Overview、Key Design Decisions（每项说明选择理由和替代方案）、Data Flow、Component Interaction、**Architecture Impact Analysis**（侵入点/模块边界/依赖方向/数据影响/接口兼容性分析，每项标注置信度 ✅/⚠️）、**对外接口契约**（如有 specline-test-writer 负责的集成/E2E 测试；CLI 命令/HTTP 端点/模块导出签名）
 
@@ -81,7 +81,7 @@ specline gate new --change "<name>"
 
   > 💡 **并行度自检**：统计 tasks.md 中 `Depends: (none)` 的任务占比 — ≥ 60% 通过，< 60% 则重新拆解（最多 2 次），仍不达标则记录警告。
 
-### Step 4: 验证完整性
+### 步骤 4：验证完整性
 
 ```bash
 specline gate artifacts --change "<name>" --json
@@ -89,7 +89,7 @@ specline gate artifacts --change "<name>" --json
 
 确保 proposal/design/tasks/specs 四个文件都已存在。
 
-### Step 5: 输出完成摘要
+### 步骤 5：输出完成摘要
 
 - Change 名称和位置
 - 4 个文件生成确认
@@ -97,7 +97,7 @@ specline gate artifacts --change "<name>" --json
 
 ---
 
-## Layer 3: 规范详解
+## 第 3 层：规范详解
 
 ### tasks.md 拆分规范
 
@@ -152,7 +152,7 @@ specline-spec-creator 生成的 tasks.md 末尾会包含「测试文件归属」
 
 ---
 
-### Guardrails
+### 约束
 
 - 所有文件直接写入 `specline/changes/<name>/`，不调用外部 CLI
 - 先读已有 dependency 再生成后续文件
@@ -174,12 +174,12 @@ specline-spec-creator 生成的 tasks.md 末尾会包含「测试文件归属」
 | "并行度 50% 够了，不用追求 60%" | 60% 不是硬指标，但 <50% 意味着功能边界划分不合理——大概率任务之间耦合太紧。 |
 | "测试文件归属表格我后面补" | 补的从来不会补。没有归属表格，coding agent 和 test-writer 会踩到对方的文件。 |
 
-## Verification Checklist
+## 验证清单
 
 生成 Spec 规划文件后，自查：
 
 - [ ] proposal.md 包含：What / Why / In Scope / Out of Scope（两段显式分开）/ Impact
-- [ ] spec.md 包含：Purpose + Requirements，每个 Requirement ≥1 Scenario（含 WHEN/THEN），Happy Path + 至少 1 个异常场景
+- [ ] spec.md 包含：Purpose + Requirements，每个 Requirement ≥1 Scenario（含 WHEN/THEN），正常路径（Happy Path）+ 至少 1 个异常场景
 - [ ] design.md 包含：Architecture Overview、Key Design Decisions（理由+替代方案）、Data Flow、Component Interaction、**Architecture Impact Analysis**（侵入点/模块边界/依赖方向/数据影响/接口兼容性，每项带置信度 ✅/⚠️）、**对外接口契约**（如有 test-writer 测试任务；CLI/HTTP/模块导出表格）
 - [ ] tasks.md 每个任务标注完整（Type/Depends/Covers/Testable/Files），Depends: (none) 占比 ≥ 60%，第 1 批次 Files 无重叠
 - [ ] 测试文件归属表格存在：单元测试归属 coding agent，集成/E2E 归属 test-writer

package/core/skills/specline-quickfix/SKILL.md

@@ -7,7 +7,7 @@ description: 轻量修改 Skill —— 小改动用 quickfix，大功能用 pipe
 
 ---
 
-## Layer 1: 速览与定位
+## 第 1 层：速览与定位
 
 **一句话定位**：小改动用 quickfix，大功能用 pipeline。
 
@@ -45,13 +45,13 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
 
 ---
 
-## Layer 2: Happy Path
+## 第 2 层：主流程
 
-### Phase 1: UNDERSTAND
+### 阶段 1：UNDERSTAND
 
 **目标**：理解变更上下文，明确修改范围。
 
-**Steps**：
+**步骤**：
 
 1. 解析用户描述，提取关键词（文件名、函数名、错误信息等）
 <!-- platform:cursor -->
@@ -67,15 +67,15 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
    - 不需要新测试 ✓
 4. **意图模糊时**：使用 {{CONFIRM}} 向用户确认变更范围和目标，不要猜测
 
-**准入条件**：变更范围已验证在 quickfix 适用范围内（参见 Layer 3 边界判断）
+**准入条件**：变更范围已验证在 quickfix 适用范围内（参见第 3 层边界判断）
 
 ---
 
-### Phase 2: IMPLEMENT
+### 阶段 2：IMPLEMENT
 
 **目标**：直接编辑源文件，完成修改。
 
-**Steps**：
+**步骤**：
 
 <!-- platform:cursor -->
 1. 使用 Write / StrReplace 工具直接编辑文件
@@ -95,11 +95,11 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
 
 ---
 
-### Phase 3: REVIEW
+### 阶段 3：REVIEW
 
 **目标**：通过 Lint 检查和 Agent 自审确保代码质量。
 
-**Steps**：
+**步骤**：
 
 <!-- platform:cursor -->
 1. 运行 ReadLints 收集所有 lint 问题
@@ -120,11 +120,11 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
 
 ---
 
-### Phase 4: TEST
+### 阶段 4：TEST
 
 **目标**：运行项目已有单元测试，确保不引入回归。
 
-**Steps**：
+**步骤**：
 
 1. **自动检测测试框架**：
    - 检查 `package.json` scripts → Jest / Mocha / Vitest
@@ -139,11 +139,11 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
 
 ---
 
-### Phase 5: ARCHIVE
+### 阶段 5：ARCHIVE
 
 **目标**：生成轻量归档，提供变更可追溯性。
 
-**Steps**：
+**步骤**：
 
 1. 在 `specline/changes/archive/` 下创建归档目录：
    ```
@@ -182,7 +182,7 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
 
 ---
 
-## Layer 3: 异常与边界
+## 第 3 层：异常与边界
 
 ### Quickfix vs Pipeline 边界判断
 
@@ -223,7 +223,7 @@ Quickfix 不绑定 Pipeline session，所有 Hook（sessionStart、preToolUse、
 
 ---
 
-## Layer 4: 附录
+## 第 4 层：附录
 
 ### 与 Pipeline 的关系
 
@@ -276,7 +276,7 @@ Quickfix 的极简流程容易让人产生"反正很快，随便点"的心态：
 | "不用归档了，就是个小修，没记录无所谓" | 不归档意味着不可追溯。三个月后没人记得这个修改是谁做的、为什么做的。 |
 | "不用询问用户 git commit，我自己提交了" | Commit 是用户的决定，不是 Agent 的。擅自 commit 剥夺了用户的审查机会。 |
 
-## Verification Checklist
+## 验证清单
 
 Quickfix 完成后，自查：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specline",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Spec-driven AI coding pipeline with deterministic quality gates for Cursor IDE",
   "bin": {
     "specline": "./cli.mjs"

package/templates/.cursor/README.md

@@ -1,18 +0,0 @@
-# ⚠️ DEPRECATED
-
-This directory is a legacy compatibility layer. **Do not edit files here directly.**
-
-## Source of Truth
-
-- Skills: `core/skills/`
-- Agents: `core/agents/`
-- Gates: `core/gates/`
-- Hooks: `core/hooks/`
-- Adapters: `adapters/{cursor,claude,codex,opencode}/`
-
-## Migration
-
-Files in this directory are no longer the primary source. They will be maintained
-for backward compatibility during the v1→v2 transition period.
-
-Use `specline sync` to update your project from the new `core/` + `adapters/` structure.