@zhuan-ai/zhuanspec 2.9.5 → 2.11.2

package/dist/core/templates/agents-template.js

@@ -153,19 +153,33 @@ Wave: W/N | Phase: Apply
      * 兼容策略：若未找到 project.md 或关键词无匹配，输出警告并使用全局检索
    - 阅读 \`zhuanspec/project.md\` 了解项目约定（提示："✓ Loaded project.md"）
    - 审查 \`zhuanspec/project.md\`，\`zhuanspec list\` 和 \`zhuanspec list --specs\` 以了解当前上下文。
-1. **强制询问测试用例（TDD 模式检查点，必须首先执行）**：
-   - 使用选项式交互询问："请提供相关的测试用例（可选），可以是：本地目录路径、在线链接（将通过 zzcase-data-fetcher skill 获取）、或跳过此步骤继续常规流程"
-   - 用户选择"提供测试用例"：进入 TDD 驱动模式
-     * 明确告知：测试用例将用于需求定义、单元测试生成、实施验证
-     * 在 proposal.md 创建 "Test Case Coverage" 部分
-     * 在 tasks.md 使用 \`@test-case:TC-XXX\` 标签关联任务
-     * 创建 test-cases.md 记录测试用例详情
-   - 用户选择"跳过"：继续常规流程（即提案无需考虑测试case）
-
-   ⚠️ **CHECKPOINT [TDD-MODE]**:
-   - TDD 模式下，Apply 阶段每个任务完成后需验证对应测试用例通过
-   - Review 阶段包含测试覆盖率检查
-   - 测试用例在 TDD 模式下发挥关键验证作用，确保代码符合预期行为
+1. **测试 case 来源确认（最先执行，禁止跳过）**：
+   在进行任何澄清、设计或编写任何提案文件之前，使用选项式交互询问用户：
+   - 选项 A：提供测试 case（有现成 case，走 TDD 模式）
+   - 选项 B：暂不提供测试 case
+   - 选项 C：其他（请在后续补充说明）
+
+   用户选择"提供测试 case"时：进入 TDD 驱动模式
+   - 明确告知：测试用例将用于需求定义、单元测试生成、实施验证
+   - 若用户提供链接（格式：\`https://zzcase.zhuanspirit.com/plan/taskDetail/module/{moduleId}/task/{taskId}\`），从 URL 提取 \`moduleId\`，调用 MCP 工具 \`mcp__caseweb__GET_get2\` 读取数据；否则手动录入
+   - 创建 test-cases.md 记录测试 case 详情（每个 TC-XXX 含前置条件、步骤、预期结果、验收点）
+   - tasks.md 使用 \`@test-case:TC-XXX\` 标签关联任务与测试 case
+   - 任务实施顺序调整为：先写测试 → 再写实现 → 验证测试通过
+
+   用户选择"暂不提供"：跳过，按常规流程继续
+   用户选择"其他"：等待用户补充说明后继续
+
+   ⚠️ **CHECKPOINT [TEST-CASE-INQUIRY]**：
+   无论用户选择什么，必须**立即**将结果记录到 tasks.md 的 \`## Test Case Source Log\` 段
+   （若 tasks.md 尚未创建，先创建并写入此段，其余内容后续补充）：
+   \`\`\`
+   ## Test Case Source Log
+   - 用户回答：[提供测试 case / 暂不提供 / 具体说明]
+   - TDD 模式：[启用 / 禁用]
+   - （如启用）测试 case 来源：[链接 / 手动录入 / bicId]
+   \`\`\`
+   此段不得为空，validate --strict 会**无条件**检查其存在与内容，缺失直接报 ERROR。
+   未完成此 checkpoint 记录之前，禁止执行步骤 2 及后续任何文件写入操作。
 
 2. **强制澄清检查（必须执行，不可跳过）**：分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、实现细节、数据获取来源、服务分层、依赖关系、优先级、验收标准等......）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测或创建提案，严禁要求用户手动输入大段文字。
 
@@ -180,6 +194,12 @@ Wave: W/N | Phase: Apply
 4. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
 5. 当解决方案跨越多个系统、引入新模式或在提交规范之前需要权衡讨论时，在 \`design.md\` 中捕获架构推理。
 6. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
+
+   ⚠️ **CHECKPOINT [SPEC-REQUIREMENT-FORMAT]**：
+   每个 \`### Requirement:\` 块写完后必须自检以下两点，违反任意一条 \`zhuanspec validate\` 会报 ERROR：
+   1. **必须有需求描述文本**：header 之后、第一个 \`#### Scenario\` 之前，必须至少有一行非空的需求描述文本；不能直接从 \`### Requirement:\` 跳到 \`#### Scenario:\`。
+   2. **第一行描述必须包含 SHALL 或 MUST**：验证器用 \`/\\b(SHALL|MUST)\\b/\` 检查第一行，缺失直接 ERROR。正确示例：\`系统 MUST 提供...\` / \`The system SHALL...\`；错误示例：仅写普通陈述句（如"提供客户查询能力"）。
+
 7. **发现可用 Skill 并创建 tasks.md**：
    - 运行 \`zhuanspec skills list --json\` 获取当前环境中可用的 skill 列表及其 description
    - 在 \`proposal.md\` 的 **Skill Mapping** 段中基于 skill description 进行语义匹配：
@@ -188,6 +208,21 @@ Wave: W/N | Phase: Apply
      - 简单的代码修改（如枚举值增删）应匹配通用编码规范 skill，而非架构级 skill
      - 避免仅因模块名称或文件路径中的关键词而错误匹配
      - 在表格中说明匹配理由
+   - **任务分解规则（模板驱动）**：
+     - 每个任务按类型使用固定模板，必须填满所有字段（文件 → 位置 → 内容 → 验证）：
+       * **新增文件任务**：必须包含 \`文件\`（完整相对路径+"新增"标记）、\`内容\`（类定义、依赖注入、核心方法签名+返回类型、关键逻辑流程、字段列表）、\`验证\`（正常+异常场景的输入输出断言）
+       * **修改文件任务**：必须包含 \`文件\`（完整相对路径+总行数）、\`修改位置\`（L行号范围+函数名）、\`内容\`（具体改什么和怎么改）、\`验证\`（修改后预期行为+回归验证）
+     - 任务编号严格使用 N.M 格式（如 1.1、2.3），不允许 3.2a 等非标准编号
+     - 每个任务必须包含 @ref 标签指向技术方案具体章节（格式：@ref:<tech-spec路径>#章节编号-章节名称，路径为实际定位到的技术方案文件相对路径）
+     - **技术方案摄取**：当技术方案文档存在时（按优先级：用户 --tech-spec 指定路径 > techDesign/tech-spec.md）：
+       * 逐章解析 DB 表、接口方法、ES 索引、MQ、配置项等元素
+       * 每个技术元素必须对应至少一个任务
+       * 任务的"内容"段必须引用技术方案中的具体字段定义（如表字段列表、接口入参出参、枚举值）
+       * 新增 Coverage Checklist 段，确保覆盖率 >= 95%
+     - **禁止模糊描述**：
+       * 禁止："创建 CustomerMapper" — 缺少文件路径、方法列表、关键逻辑
+       * 正确："创建 CustomerMapper" + 文件路径 + 继承 BaseMapper<CustomerEntity> + 3个自定义方法签名 + 验证
+       * 任务描述必须自包含：AI 执行时不需要再读技术方案猜测实现细节
    - 将 \`tasks.md\` 起草为有序的小型、可验证工作项列表
    - 使用 \`@skill:<real-skill-name>\` 标注与 skill 匹配的任务（支持多个：\`@skill:name1,name2\`）
    - 仅当 skill 明确匹配任务时才标注，没有匹配的 skill 可省略标签
@@ -206,6 +241,10 @@ Wave: W/N | Phase: Apply
    3. No task may appear before a task it depends on
    4. You MUST add a "## Dependency Analysis" section at the end with "Status: COMPLETED"
    5. validate --strict will verify task ordering matches computed waves
+   6. 如果多个任务描述中引用了相同文件路径，必须在 "## File Conflict Analysis" 表中声明：
+      - 各任务修改的具体区域（函数名、行号范围、配置节名称）
+      - 隔离策略：parallel（不同区域，可在同一 Wave 并行）或 serial（同区域，必须跨 Wave 串行）
+      - 若所有任务修改不同文件，无冲突时跳过此表或填写 N/A
 
 8. **测试 case 处理（仅 TDD 模式）**：
 
@@ -214,28 +253,44 @@ Wave: W/N | Phase: Apply
    - **无 case 模式**：普通 spec-driven 工作流，用户未提供测试 case 相关信息
 
    **【有 case 模式】**（必须执行以下步骤）：
-   - **【强制】获取测试 case 的方式**：
+   - **【强制】获取测试 case 的方式**（按优先级选择）：
+     * **优先**：检查 \`./doc/\` 目录下是否存在 \`*-tdd-cases.md\` 文件（由技术方案 skill 自动转换生成）
+       - 存在 → 直接读取，无需重新获取原始 case
+       - 不存在 → 使用以下方式获取原始 case
      * 如果用户提供的是**链接**（如 zzcase 平台 URL）：使用 \`@skill:zzcase-data-fetcher\` skill 直接读取
      * 如果用户提供 **taskId/bicId**：使用 \`@skill:zzcase-data-fetcher\` skill 通过参数获取
      * **禁止**使用 MCP 工具 \`zzcase_get_api_report_queryBaseCase\` 获取测试 case
      * 或手动录入测试 case
    - **【强制】创建 test-cases.md 文件**：
-     * 使用 \`getTestCasesTemplate\` 模板（从 \`src/core/templates/index.ts\` 导出）
+     * 若已读取 \`./doc/*-tdd-cases.md\`：直接复制内容到 \`changes/<change-id>/test-cases.md\`，无需重新生成
+     * 若从原始 case 获取：使用 \`getTestCasesTemplate\` 模板（从 \`src/core/templates/index.ts\` 导出）
      * 文件路径：\`changes/<change-id>/test-cases.md\`
-     * 填写获取时间、来源（taskId/bicId/manual）、测试 case 详情
-     * 每个 TC-XXX 必须包含：前置条件、测试步骤、预期结果、验收点
+     * 填写获取时间、来源（tdd-cases.md / taskId/bicId/manual）、测试 case 详情
+     * 每个 TC-XXX 必须包含：前置条件、测试步骤、预期结果、验收点、**@layer 标注（BE/FE/BOTH）**
+   - **【强制】tasks.md @test-case 标注**：
+     * 读取 test-cases.md 中所有 TC-XXX 条目
+     * 为 tasks.md 中每个 task，**按语义匹配**找到相关 Case：
+       - task 描述中涉及「新建/编辑/删除」→ 匹配对应 CRUD Case
+       - task 描述中涉及「手机号去重/合并」→ 匹配手机号冲突相关 Case
+       - task 描述中涉及「租户/权限」→ 匹配权限隔离相关 Case
+       - task 描述中涉及「MQ/消息消费」→ 匹配 MQ 消费相关 Case
+       - task 描述中涉及「导出」→ 匹配导出相关 Case
+     * 匹配到 → 追加 \`@test-case:TC-XXX\`（可多个：\`@test-case:TC-022,TC-024\`）
+     * 匹配不到 → 不追加，该 task 走普通 Apply Agent
    - 在 \`tasks.md\` 增加 **Test Case Coverage** 表格（四列格式）：
      | Task | 测试 Case ID | 测试 Case 文件路径 | 覆盖场景 |
      |------|-------------|-------------------|----------|
-     * "测试 Case 文件路径" 列填写 BIC 路径层级格式
+     * "测试 Case 文件路径" 列填写 \`changes/<change-id>/test-cases.md\`
    - 使用 \`@test-case:TC-XXX\` 关联任务与测试 case
 
    ⚠️ **CHECKPOINT [TEST-CASE-COVERAGE]**（仅适用于有 case 模式）:
    1. 每个 Requirement 应至少对应一个测试 case
    2. 测试 case 应覆盖正向和异常场景
-   3. **必须创建 test-cases.md 文件**（使用 \`getTestCasesTemplate\` 模板）
+   3. **必须创建 test-cases.md 文件**（优先复用 \`./doc/*-tdd-cases.md\`，否则使用 \`getTestCasesTemplate\` 模板）
    4. Test Case Coverage 表格必须包含四列：Task、测试 Case ID、测试 Case 文件路径、覆盖场景
-   5. validate --strict 会验证测试 case 覆盖率（**阻塞级别**）
+   5. **每个 TC-XXX 必须有 @layer 标注**（BE/FE/BOTH），无标注视为格式不完整
+   6. **有 @test-case 标注的 task**，必须通过语义匹配找到对应 Case，不得随意指定无关 Case
+   7. validate --strict 会验证测试 case 覆盖率（**阻塞级别**）
 
    **【无 case 模式】**（跳过测试 case 相关步骤）：
    - 不创建 test-cases.md
@@ -656,8 +711,42 @@ The system SHALL provide...
 4. 必须在文件末尾添加 "## 依赖分析" 章节并标明"状态：已完成"
 5. validate --strict 会验证任务排序是否与计算的波次匹配
 
-5. **创建 design.md（必选）**：
-每个提案都必须创建 \`design.md\`，记录技术决策和架构思考：
+## Subagent 启动前上下文准备
+
+在编排层为每个 Subagent 准备上下文时，按三级策略注入：
+
+### L1 核心（全量注入，必须完整）
+1. 解析当前任务的 @test-case 标注 → 从 test-cases.md 中提取对应 TC 全文
+2. 解析当前任务的 @ref 标注 → 从技术方案文档中提取对应章节（按优先级查找：用户 --tech-spec 指定路径 > techDesign/tech-spec.md）
+3. 定位当前任务所属的 capability → 读取 specs/<capability>/spec.md
+
+### L2 关联（全量注入）
+4. design.md 全文
+5. Rules + Knowledge
+6. 当前 Wave 其他任务的一句话摘要 + 前置 Wave 完成结果摘要
+
+### L3 背景（摘要 + 按需读取）
+7. 技术方案其他章节 → 输出清单式摘要（“还包含 N 张表：xxx, yyy, ...，详见技术方案文档”）
+8. 其他 spec 的 Requirement 标题列表 → 输出清单（"另有 M 个 spec，详见 specs/ 目录"）
+
+### 最终校验
+- L1+L2 总行数 > 800 行 → 对 L2 中 design.md 做章节裁剪（只保留当前任务相关章节）
+- L1 不允许裁剪
+- L3 的摘要必须包含所有元素名称，不允许用"等"或"..."省略
+
+5. **基于技术方案逐章映射到 design.md（必选）**：
+每个提案都必须创建 \`design.md\`，记录技术决策和架构思考。
+
+**章节映射规则**：
+- **必选章节**（所有提案必须包含）：背景/Background、决策/Decision、风险/Risks
+- **按需章节**（仅当技术方案涉及时才生成）：
+  - 技术方案有建表 SQL / DDL → 生成 数据模型/Database Design 章节
+  - 技术方案有接口定义 / API / SCF / RPC → 生成 接口设计/API Contract 章节
+  - 技术方案有 ES / MQ / 缓存 → 生成 基础设施/Infrastructure 章节
+  - 技术方案有前端设计 → 生成 前端设计/Frontend Design 章节
+  -...(按照提供的技术方案补充 总之要覆盖全)
+- 每个按需章节的内容从技术方案对应章节映射而来
+- 无技术方案文档时，仅校验必选章节（向后兼容）
 
 \`\`\`markdown
 ## 背景
@@ -687,7 +776,7 @@ The system SHALL provide...
 - [...]
 \`\`\`
 
-**重要**：design.md 是知识提取的主要来源，归档时会自动提取其中的"决策"、"最佳实践"、"隐式约定"沉淀到项目知识库。
+**重要**：design.md 是知识提取的主要来源，归档时会自动提取其中的“决策”、“最佳实践”、“隐式约定”沉淀到项目知识库。
 - [...]
 \`\`\`
 
@@ -1028,12 +1117,39 @@ Apply 阶段使用两种专用 Agent 类型执行代码实施任务，由编排
 - 相关的 spec 文件路径和内容（仅限该 task 涉及的部分）
 - 前序 wave 的完成摘要（而非完整输出）
 - Rules 和 Knowledge 上下文
+- **若 task 有 \`@test-case\` 标注**：从 \`test-cases.md\` 中提取对应 TC-XXX 的完整内容（含 @layer、BE 验收、FE 验收），注入给 TDD Apply Agent
+- **design.md 的层间依赖规则 + 架构约束**（所有 task 必须注入，确保 Agent 了解禁止的跨层调用）
 
 **禁止注入**：
 - 其他 wave 的 task 详情
 - 不相关的 skill 内容
 - 其他 subagent 的完整输出
 
+## Skill 断流恢复
+
+如果在执行 @skill 过程中遇到异常：
+1. 记录异常到 progress.json 的 skillCalls
+2. 标记 afterAction: 'skip-and-continue'
+3. 继续当前任务的后续实施步骤
+4. 在任务完成报告中标注 "Skill [name] skipped due to [reason]"
+
+⚠️ Skill 是辅助工具，不应阻断主流程。任何 Skill 失败都不应导致任务失败。
+
+## Wave 集成验证
+
+每个 Wave 全部 Subagent 完成后，编排 Agent 执行集成验证：
+1. 编译检查（\`mvn compile -q\` 或 \`tsc --noEmit\`）
+2. 导入解析检查（本 Wave 新增 import 是否可解析）
+3. 接口签名一致性（调用方参数与定义匹配）
+4. TC 覆盖快照对比（如 tc-implementation-verify Skill 已安装）：
+   - 生成 \`metrics/tc-snapshot-wave-N.json\`
+   - 与前一 Wave 快照对比
+   - 回归（implemented → missing）→ 阻断
+   - 进展（missing → implemented）→ 记录
+
+验证失败 → 修复后才进入下一 Wave。
+验证通过 → 记录 Wave 完成状态，进入下一 Wave。
+
 ---
 
 ### Rules 和 Knowledge 注入示例

package/dist/core/templates/skill-templates.js

@@ -276,6 +276,13 @@ export function getApplyChangeSkillTemplate() {
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
+   ### Wave 完成后检查
+   每个 Wave 的所有任务执行完毕后：
+   1. 运行编译检查确保无错误
+   2. 验证跨任务的接口一致性
+   3. 如有 tc-implementation-verify Skill，运行 TC 覆盖快照
+   4. 所有检查通过后才进入下一 Wave
+
 7. **On completion or pause, show status**
 
    Display:
@@ -414,7 +421,20 @@ What would you like to do?
 This skill supports the "actions on a change" model:
 
 - **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly`
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
+
+## Skill 执行完成后的衔接协议
+
+每个 Skill 执行完成后必须：
+1. 输出结构化结果文件（JSON 格式）到约定路径
+2. 明确声明接续动作（afterAction）：
+   - continue: 继续当前任务流
+   - validate: 触发 zhuanspec validate
+   - pause: 暂停等用户确认
+   - review-gate: 结果进入审查门禁
+3. 如果 Skill 执行失败，不阻断 ZhuanSpec 主流程
+
+⚠️ Skill 是工具，不是流程控制器。Skill 不应改变 ZhuanSpec 阶段。`
     };
 }
 /**

package/dist/core/templates/slash-command-templates.js

@@ -6,7 +6,7 @@ const baseGuardrails = `**约束条件**
 const proposalGuardrails = `${baseGuardrails}\n- **强制澄清要求**：在创建任何提案文件之前，必须首先分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、优先级、验收标准等）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测、假设或创建提案。严禁要求用户手动输入大段文字来回答澄清问题。
 - 识别任何模糊或歧义的细节，使用带预设选项的选择题在编辑文件之前询问必要的后续问题。
 - 在提案阶段不要编写任何代码。先完成 techDesign（需求技术方案）后再创建 proposal/specs/tasks，实施在批准后的应用阶段进行。
-- **TechDesign 目录识别**：proposal 阶段扫描 changes/ 目录，通过 progress.json 的 phase 字段识别 techDesign 目录，交互式确认复用。
+- **TechDesign 目录识别**：proposal 阶段扫描 changes/ 目录，通过 progress.json 的 phase 字段识别 techDesign 目录，**自动复用**（无需询问用户）。复用时按优先级查找技术方案：① 用户通过 --tech-spec 指定的外部路径 ② changes/<name>/techDesign/tech-spec.md，找到后作为提案输入上下文。
 - **Phase 自动更新**：复用 techDesign 目录时，自动运行 \`zhuanspec progress set-phase <change-id> propose\` 更新 phase。`;
 const proposalOutputFormat = `**输出格式要求**
 每个步骤完成后，输出阶段性进度报告：
@@ -64,15 +64,48 @@ const proposalSteps = `**步骤**
    - **TechDesign 目录识别**：
      * 扫描 changes/ 目录下的所有变更
      * 检查每个变更的 metrics/progress.json 的 phase 字段
-     * 如果存在 phase=techDesign 的目录，列为候选
-     * 使用 AskQuestion 工具交互式确认：
-       - 选择复用现有 techDesign 目录（列出所有候选）
-       - 创建新目录
-       - 其他（手动指定）
+     * 如果存在 phase=techDesign 的目录，**直接复用该目录，无需询问用户**，并输出提示："techDesign 阶段已提前创建提案目录，直接复用该目录"
+     * 如果存在多个 phase=techDesign 目录，复用最新创建的目录
+     * 如果不存在 phase=techDesign 目录，创建新目录
+   - **技术方案定位（多源）**：
+     * 按优先级依次查找技术方案文档：
+       1. 用户通过 \`--tech-spec <path>\` 指定的外部路径（绝对或相对路径均可）
+       2. \`changes/<name>/techDesign/tech-spec.md\`
+     * 找到第一个存在且内容非空（非模板占位符）的文件，Read 全文作为 Propose 的输入上下文
+     * 将技术方案内容系统性注入后续 design.md、proposal.md 和 tasks.md
+     * 如果所有路径均不存在或为空占位符，按原流程从头生成提案
    - **Phase 初始化**：
      * 如果复用 techDesign 目录：运行 \`zhuanspec progress set-phase <change-id> propose\`
      * 如果新建目录：目录创建时自动初始化 phase=propose
-1. **强制澄清检查（必须首先执行，不可跳过）**：
+1. **测试 case 来源确认（最先执行，禁止跳过）**：
+   在进行任何澄清、设计或编写任何提案文件之前，使用 AskQuestion 工具询问用户：
+   - 选项 A：提供测试 case（有现成 case，走 TDD 模式）
+   - 选项 B：暂不提供测试 case
+   - 选项 C：其他（请在后续补充说明）
+
+   用户选择"提供测试 case"时：
+   - 启用 **TDD 模式**：先获取测试 case，再基于 case 设计 spec 和任务
+   - **获取方式**：若用户提供链接（格式：\`https://zzcase.zhuanspirit.com/plan/taskDetail/module/{moduleId}/task/{taskId}\`），从 URL 路径中提取 \`moduleId\`，调用 MCP 工具 \`mcp__caseweb__GET_get2\` 读取数据；否则手动录入
+   - **创建 test-cases.md**（路径：\`changes/<change-id>/test-cases.md\`），使用 \`getTestCasesTemplate\` 模板，每个 TC-XXX 包含：前置条件、测试步骤、预期结果、验收点
+   - tasks.md 中使用 \`@test-case:TC-XXX\` 关联任务与测试 case，表格四列：Task、测试 Case ID、测试 Case 文件路径、覆盖场景
+   - 任务实施顺序调整为：先写测试 → 再写实现 → 验证测试通过
+
+   用户选择"暂不提供"：跳过，按常规流程继续
+   用户选择"其他"：等待用户补充说明后继续
+
+   ⚠️ **CHECKPOINT [TEST-CASE-INQUIRY]**：
+   无论用户选择什么，必须**立即**将结果记录到 tasks.md 的 \`## Test Case Source Log\` 段
+   （若 tasks.md 尚未创建，先创建并写入此段，其余内容后续补充）：
+   \`\`\`
+   ## Test Case Source Log
+   - 用户回答：[提供测试 case / 暂不提供 / 具体说明]
+   - TDD 模式：[启用 / 禁用]
+   - （如启用）测试 case 来源：[链接 / 手动录入 / bicId]
+   \`\`\`
+   此段不得为空，validate --strict 会**无条件**检查其存在与内容，缺失直接报 ERROR。
+   未完成此 checkpoint 记录之前，禁止执行步骤 2 及后续任何文件写入操作。
+
+2. **强制澄清检查（必须首先执行，不可跳过）**：
    - 仔细分析用户请求，识别所有不确定或模糊的方面：
      * 范围是否明确？（边界、包含/排除的内容）
      * 技术选择是否明确？（框架、库、架构模式）
@@ -102,12 +135,25 @@ const proposalSteps = `**步骤**
    - This section MUST NOT be empty or contain only HTML comments
    - NEVER proceed to proposal writing without completing this checkpoint
    
-2. 选择一个唯一的动词开头的 \`change-id\`，但是必须注意，如果经过了techDesign阶段并且已经提前创建好了提案目录则必须直接复用，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\` 和 \`design.md\`。
+3. 选择一个唯一的动词开头的 \`change-id\`，但是必须注意，如果经过了techDesign阶段并且已经提前创建好了提案目录则必须直接复用，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\` 和 \`design.md\`。
     -如果复用了techDesign创建的提案目录，需要输出'techDesign阶段已经提前创建好提案目录，我将直接在该目录生成相关提案文件'
-3. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
-4. 创建 \`design.md\`（必选），记录技术决策、最佳实践、隐式约定。归档时会自动提取这些内容沉淀到项目知识库。
-5. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
-6. **发现可用 Skill 并创建 tasks.md**：
+4. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
+5. 创建 \`design.md\`（必选），记录技术决策、最佳实践、隐式约定。归档时会自动提取这些内容沉淀到项目知识库。
+   - **如果用户已提供详细技术方案**，必须将以下内容系统性摄取到 design.md 对应章节，不得遗漏：
+     * 接口定义（方法签名、入参/出参字段、类型、枚举值）→ 写入 \`## 接口设计\`
+     * DB schema 变更、实体类字段 → 写入 \`## 数据模型\`
+     * 流程图/时序图 → 写入 \`## 业务流程\`
+     * 分层实现说明、关键逻辑 → 写入 \`## 实现细节\`
+     * 参数校验、错误码、异常处理 → 写入 \`## 边界条件 / 异常处理\`
+   - **摄取原则**：保留原始章节标题和结构，便于 apply 阶段按章节定位；不要压缩或省略具体字段定义
+6. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
+
+   ⚠️ **CHECKPOINT [SPEC-REQUIREMENT-FORMAT]**：
+   每个 \`### Requirement:\` 块写完后必须自检以下两点，违反任意一条 \`zhuanspec validate\` 会报 ERROR：
+   1. **必须有需求描述文本**：header 之后、第一个 \`#### Scenario\` 之前，必须至少有一行非空的需求描述文本；不能直接从 \`### Requirement:\` 跳到 \`#### Scenario:\`。
+   2. **第一行描述必须包含 SHALL 或 MUST**：验证器用 \`/\\b(SHALL|MUST)\\b/\` 检查第一行，缺失直接 ERROR。正确示例：\`系统 MUST 提供...\` / \`The system SHALL...\`；错误示例：仅写普通陈述句（如"提供客户查询能力"）。
+
+7. **发现可用 Skill 并创建 tasks.md**：
    - 运行 \`zhuanspec skills list --json\` 获取当前环境中可用的 skill 列表及其 description
    - 在 \`proposal.md\` 的 **Skill Mapping** 段中基于 skill description 进行语义匹配：
      - 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
@@ -115,6 +161,21 @@ const proposalSteps = `**步骤**
      - 简单的代码修改（如枚举值增删）应匹配通用编码规范 skill，而非架构级 skill
      - 避免仅因模块名称或文件路径中的关键词而错误匹配
      - 在表格中说明匹配理由
+   - **任务分解规则（模板驱动）**：
+     - 每个任务按类型使用固定模板，必须填满所有字段（文件 → 位置 → 内容 → 验证）：
+       * **新增文件任务**：必须包含 \`文件\`（完整相对路径+"新增"标记）、\`内容\`（类定义、依赖注入、核心方法签名+返回类型、关键逻辑流程、字段列表）、\`验证\`（正常+异常场景的输入输出断言）
+       * **修改文件任务**：必须包含 \`文件\`（完整相对路径+总行数）、\`修改位置\`（L行号范围+函数名）、\`内容\`（具体改什么和怎么改）、\`验证\`（修改后预期行为+回归验证）
+     - 任务编号严格使用 N.M 格式（如 1.1、2.3），不允许 3.2a 等非标准编号
+     - 每个任务必须包含 @ref 标签指向技术方案具体章节（格式：@ref:<tech-spec路径>#章节编号-章节名称，路径为实际定位到的技术方案文件相对路径）
+     - **技术方案摄取**：当技术方案文档存在时（按优先级：用户 --tech-spec 指定路径 > techDesign/tech-spec.md）：
+       * 逐章解析 DB 表、接口方法、ES 索引、MQ、配置项等元素
+       * 每个技术元素必须对应至少一个任务
+       * 任务的"内容"段必须引用技术方案中的具体字段定义（如表字段列表、接口入参出参、枚举值）
+       * 新增 Coverage Checklist 段，确保覆盖率 >= 95%
+     - **禁止模糊描述**：
+       * 禁止："创建 CustomerMapper" — 缺少文件路径、方法列表、关键逻辑
+       * 正确："创建 CustomerMapper" + 文件路径 + 继承 BaseMapper<CustomerEntity> + 3个自定义方法签名 + 验证
+       * 任务描述必须自包含：AI 执行时不需要再读技术方案猜测实现细节
    - 将 \`tasks.md\` 起草为有序的小型、可验证工作项列表
    - 使用 \`@skill:<real-skill-name>\` 标注与 skill 匹配的任务（支持多个：\`@skill:name1,name2\`）
    - 仅当 skill 明确匹配任务时才标注，没有匹配的 skill 可省略标签
@@ -135,43 +196,6 @@ const proposalSteps = `**步骤**
    5. validate --strict will verify task ordering matches computed waves
 
 
-7. **测试 case 来源询问**（强制询问）：
-   - 使用 AskQuestion 工具询问用户是否提供测试 case：
-     * 选项 A：提供测试 case（有现成 case，走 TDD 模式）
-     * 选项 B：暂不提供测试 case
-     * 选项 C：其他（请在后续补充说明）
-   - 用户选择处理：
-     * 选择"提供测试 case"：
-       - 启用 **TDD 模式**：先获取测试 case，再基于 case 设计 spec 和任务
-       - **【强制】获取测试 case 的方式**：
-         * 如果用户提供的是**链接**（如 zzcase 平台 URL）：使用 \`@skill:zzcase-data-fetcher\` skill 直接读取
-         * 如果用户提供 **taskId/bicId**：使用 \`@skill:zzcase-data-fetcher\` skill 通过参数获取
-         * **禁止**使用 MCP 工具 \`zzcase_get_api_report_queryBaseCase\` 获取测试 case
-       - 或手动录入测试 case
-       - **【强制】创建 test-cases.md 文件**：
-         * 使用 \`getTestCasesTemplate\` 模板（从 \`src/core/templates/index.ts\` 导出）
-         * 文件路径：\`changes/<change-id>/test-cases.md\`
-         * 填写获取时间、来源（taskId/bicId/manual）、测试 case 详情
-         * 每个 TC-XXX 必须包含：前置条件、测试步骤、预期结果、验收点
-       - 在 \`tasks.md\` 的 **Test Case Coverage** 表格中使用 \`@test-case:TC-XXX\` 关联任务与测试 case
-       - **表格格式要求**（四列）：
-         | Task | 测试 Case ID | 测试 Case 文件路径 | 覆盖场景 |
-         |------|-------------|-------------------|----------|
-         | T1 | TC-001 | \`退货退款 > 创建售后 > 三选一页面 > 组装机弹窗\` | 描述 |
-         * "测试 Case 文件路径" 列填写 BIC 路径层级格式
-       - 任务实施顺序调整为：先写测试 → 再写实现 → 验证测试通过
-     * 选择"暂不提供"：跳过此步骤，按常规流程继续
-     * 选择"其他"：等待用户补充说明后继续
-
-   ⚠️ **CHECKPOINT [TEST-CASE-COVERAGE]**:
-   1. 如果用户提供测试 case，启用 TDD 模式，每个 Requirement 必须对应测试 case
-   2. 测试 case 应覆盖正向和异常场景
-   3. **必须创建 test-cases.md 文件**（使用 \`getTestCasesTemplate\` 模板）
-   4. Test Case Coverage 表格必须包含四列：Task、测试 Case ID、测试 Case 文件路径、覆盖场景
-   5. validate --strict 会验证测试 case 覆盖率（警告级别，不阻塞）
-   6. 记录询问结果到 tasks.md 的 **Test Case Source Log** 段
-
-
 8. 【自动验证与修复】：
 	   运行 \`zhuanspec validate <id> --strict --auto-fix\` 进行验证：
 	   - 如果验证通过（PASS）：继续下一步
@@ -182,6 +206,15 @@ const proposalSteps = `**步骤**
 	     * 循环结束后仍未通过：输出错误报告，等待人工干预
 	   - 验证通过后，输出提案摘要
 
+	8.5. 【技术方案覆盖度自动完善】（当存在技术方案文档时：techDesign/ 目录下的 tech-spec.md，或用户指定了本地技术方案路径）：
+	   - 运行覆盖度检查（通过 Skill \`@skill:tech-spec-coverage-check\` 或内置 \`zhuanspec validate <change-id> --strict\`）
+	   - 如果发现未覆盖的技术方案元素，**自动补充到对应提案文件**：
+	     * 未覆盖的数据库表/API → 自动追加到 specs/ 对应 spec.md 的 Requirements 中
+	     * 未覆盖的类名/接口 → 自动追加到 tasks.md 作为新任务项
+	     * 未覆盖的配置项/基础设施 → 自动追加到 design.md 对应章节
+	   - 补充完成后重新检查覆盖率，确认 >= 90%
+	   - 将覆盖度报告写入 metrics/tech-spec-coverage.json
+
 	9. 【输出提案摘要】：
 	   • 变更原因、内容、影响范围
 	   • 关键 Requirements
@@ -228,24 +261,78 @@ const applySteps = `**步骤**
      → **Agent 类型选择**：根据任务是否标注 \`@test-case\` 选择：
        * 无 \`@test-case\` 标注 → 使用 \`applyAgent\`（普通代码实施）
        * 有 \`@test-case:TC-XXX\` 标注 → 使用 \`tddApplyAgent\`（TDD 模式）
-     → **Rules 和 Knowledge 注入**：编排 Agent MUST 在每个 subagent prompt 中注入：
-       * Rules：根据任务的 \`@skill\` 标注选择性注入 \`api-design.md\`、\`dao-standards.md\`、\`coding-standards.md\` 等
-       * Knowledge：始终注入 \`knowledge/index.md\` 知识索引摘要
-       * Troubleshooting：注入与任务相关的踩坑警告
-     → Subagent 上下文隔离：仅注入当前任务、关联 skill、相关 spec、Rules/Knowledge
+     → **Subagent 上下文注入（三级策略）**：
+
+       **L1 核心（全量注入，不可省略）**：
+         ① spec 内容：当前任务对应的 specs/<capability>/spec.md 全文
+         ② test-cases：当前任务 @test-case:TC-XXX 对应的 TC 详情（从 test-cases.md 提取）
+         ③ techDesign 实施细节：当前任务 @ref 指向的技术方案章节（从 techDesign/tech-spec.md 提取）
+
+       **L2 关联（全量注入）**：
+         ④ design.md 全文（已有，保持不变）
+         ⑤ Rules + Knowledge（已有，保持不变）
+         ⑥ 当前 Wave 其他任务摘要 + 前置 Wave 完成结果
+
+       **L3 背景（摘要嵌入 + 提供 Read 路径）**：
+         ⑦ 技术方案其他章节摘要（列出所有元素清单，如"10 张表：t_customer, t_customer_tag, ..."）
+         ⑧ 其他 spec 摘要
+         → 提供完整文件路径，Subagent 如需详情可自行 Read
+
+       **关键约束**：
+       - L1 和 L2 必须全量注入，不允许摘要或截断
+       - L3 的摘要必须列出所有元素清单，确保 Subagent 知道完整范围
+       - 最终校验：L1+L2 总行数超过 800 行时，对 L2 中的 design.md 做章节裁剪（只保留与当前任务相关的章节），但不允许裁剪 L1
    - **如果 tasks.md 无依赖声明**：
      → 按顺序执行（见下方步骤 3-5）
 3. **按顺序实施任务**（无依赖声明时）- 保持编辑最小化并专注于请求的变更。如果任务标注了 \`@skill:<skill-name>\`，直接调用对应 skill 获取指导后再实施。
+
+   **Subagent 调用 @skill 后的行为**：
+   1. 执行 @skill 标注的 Skill
+   2. 读取 Skill 输出的 JSON 结果
+   3. 无论 Skill 成功/失败，**必须回到当前任务的实施步骤继续**
+   4. 如果 Skill 异常或超时，跳过 Skill 继续实施
+
    - **阶段职责（按 Agent 类型区分）**：
      * **applyAgent（普通模式）**：不生成单元测试文件，单测生成与验证统一在 Review 阶段执行
      * **tddApplyAgent（TDD 模式，任务有 \`@test-case\` 标注）**：基于 test-cases.md 先写测试再实现代码
 4. **确认完成** - 在更新状态之前确保 \`tasks.md\` 中的每个项目都已完成。
 5. **更新清单** - 所有工作完成后，将每个任务设置为 \`- [x]\`，以便列表反映实际情况。
 6. **处理 Subagent 状态报告**（Wave 并行执行时）：
-   - **DONE**：继续下一任务
-   - **DONE_WITH_CONCERNS**：记录 concerns 并评估是否需要修复
-   - **BLOCKED**：评估 blocker 类型并决定处理策略（提供上下文/换更强模型/拆分任务）
-   - **NEEDS_CONTEXT**：提供缺失信息并重新启动 subagent
+   - **必须转发进度汇报**：每个 subagent 完成后，将其输出的 \`━━━ ✅ 任务完成\` 进度块原文转发输出给用户
+   - **DONE**：转发进度汇报 → 继续下一任务
+   - **DONE_WITH_CONCERNS**：转发进度汇报 → 记录 concerns 并评估是否需要修复
+   - **BLOCKED**：转发进度汇报 → 评估 blocker 类型并决定处理策略（提供上下文/换更强模型/拆分任务）
+   - **NEEDS_CONTEXT**：转发进度汇报 → 提供缺失信息并重新启动 subagent
+   - 所有任务报告文件均保存在 \`changes/<change-id>/reports/\` 目录，可告知用户按 task-id 查阅
+7. **Wave 完成后集成验证**（Wave 并行执行时）：
+   每个 Wave 全部任务完成后，编排 Agent 自动执行以下检查：
+
+   1. **编译检查**：运行项目编译命令，确保无编译错误
+      - Java: \`mvn compile -q\` / \`gradle compileJava\`
+      - TypeScript: \`tsc --noEmit\`
+      - 编译失败 → 阻断后续 Wave，定位失败文件并修复
+
+   2. **导入检查**：验证本 Wave 新增的 import 是否都能解析
+      - 搜索本 Wave 修改文件中的 import 语句
+      - 检查 import 的类/模块是否存在
+
+   3. **接口签名一致性**：
+      - 提取本 Wave 新增/修改的接口定义（参数类型、返回类型）
+      - 检查调用方的参数是否与定义一致
+
+   4. **TC 覆盖快照与回归检测**：
+      - 如果 tc-implementation-verify Skill 已安装：
+        a. 运行 tc-implementation-verify，生成当前 Wave 的 TC 覆盖快照
+        b. 将结果写入 \`metrics/tc-snapshot-wave-N.json\`
+        c. 读取上一个 Wave 的快照 \`metrics/tc-snapshot-wave-(N-1).json\`
+        d. 对比两个快照：
+           - 新增 implemented 的 TC → 记录为进展
+           - 从 implemented 变为 missing 的 TC → **回归告警**，阻断后续 Wave
+           - missing 数量未减少 → 记录警告但不阻断
+        e. 输出对比结果到 \`metrics/tc-wave-comparison.json\`
+      - 如果 Skill 未安装：跳过此步骤
+
+   任何检查失败 → 修复后再进入下一个 Wave
 8. 需要额外上下文时，参考 \`zhuanspec list\` 或 \`zhuanspec show <item>\`。
 9. **触发审查门禁** - 所有任务完成后选项式提问用户是否进入 Review 阶段`;
 const applyGuardrails = `${baseGuardrails}\n- **Wave 并行执行**：当 tasks.md 包含 \`@depends\` 时，按 Wave 编号串行执行，Wave 内任务通过 Agent tool 并行启动 subagent。
@@ -339,7 +426,7 @@ const designReferences = `**参考**
 - 使用 \`zhuanspec techDesign --help\` 查看 CLI 命令选项（用于生成请求文档或验证现有设计）`;
 const reviewGuardrails = `${baseGuardrails}\n- **门禁审查阶段**：review 命令用于执行三轨并行校验并汇总结论。
 - **强制审查**：所有变更在归档前必须通过三轨门禁，确保代码质量、测试覆盖与 Spec-Code 一致性。
-- **Skill 触发要求**：必须触发 \`code-review-expert\`（代码审查轨）与 \`generate-mockito-unit-test-skill\`（单测轨）。`;
+- **Skill 触发要求**：必须触发 \`code-review-expert\`（代码审查轨）与 \`generate-mockito-unit-test\`（单测轨）。`;
 const reviewSteps = `**步骤**
 1. **确定变更 ID 并设置 Phase**：
    - 如果此提示已包含特定的变更 ID，请使用该值
@@ -349,15 +436,28 @@ const reviewSteps = `**步骤**
    - **轨道 A：Code Review 轨**
      - 使用 Skill 工具调用 \`code-review-expert\` skill
      - 输出 \`code-review-report.md\`，记录 Critical/Important 问题
+     - skill 完成后，**AI 将结果写入** \`changes/<id>/review/code-review-result.json\`，格式：
+       \`\`\`json
+       { "criticalCount": 0, "importantCount": 0, "infoCount": 0, "issues": [], "sonarStatus": "skip", "loopCount": 0 }
+       \`\`\`
    - **轨道 B：Unit Test 轨（Skill）**
-     - 使用 Skill 工具调用 \`generate-mockito-unit-test-skill\`
+     - 使用 Skill 工具调用 \`generate-mockito-unit-test\`
      - 对缺失场景补齐单测并执行测试命令，输出单测结果
+     - skill 完成后，**AI 将结果写入** \`changes/<id>/review/unit-test-result.json\`，格式：
+       \`\`\`json
+       { "testPassed": true, "passRate": 100, "coverage": 85, "coverageThreshold": 80, "newTestsGenerated": [], "failedTests": [], "loopCount": 0 }
+       \`\`\`
    - **轨道 C：Spec-Code 一致性轨**
      - 运行 \`zhuanspec validate <change-id> --strict\`
      - 确认 \`spec-code-consistent\` 规则通过
+     - validate 完成后，**AI 将结果写入** \`changes/<id>/review/spec-consistency-result.json\`，格式：
+       \`\`\`json
+       { "consistencyRate": 100, "totalRequirements": 0, "totalScenarios": 0, "coveredScenarios": 0, "uncoveredScenarios": [], "mapping": [], "loopCount": 0 }
+       \`\`\`
 3. **汇总执行 CLI Review**：
    - 运行 \`zhuanspec review <change-id>\`
-   - CLI 汇总三轨结果并生成 \`review-report.md\` 及 JSON 结果文件
+   - CLI 读取三个 JSON，生成 \`changes/<id>/review/review-report.md\`
+   - 如果 skill JSON 未写入，CLI 将打印缺失文件列表并退出
 4. **审查结果处理**：
    - **PASS**：三轨全部通过（CR=PASS、UT=PASS、Spec-Code=PASS）且 Critical=0，可以继续归档
    - **FAIL**：输出问题列表，需要修复后重新审查
@@ -369,9 +469,9 @@ const reviewSteps = `**步骤**
    - 提示可以使用 \`/zhuanspec:archive\` 进行归档`;
 const reviewReferences = `**参考**
 - 使用 \`zhuanspec review --help\` 查看完整选项
-- 审查报告包含：\`code-review-result.json\`、\`unit-test-result.json\`、\`spec-consistency-result.json\`、\`review-report.md\`
+- 审查报告文件均位于 \`changes/<id>/review/\` 目录下：\`code-review-result.json\`、\`unit-test-result.json\`、\`spec-consistency-result.json\`、\`review-report.md\`
 - 单元测试覆盖率阈值默认 80%，可通过 \`--coverage-threshold\` 调整
-- \`code-review-expert\` Skill 输出保存到 \`zhuanspec/changes/<id>/metrics/code-review-report.md\``;
+- \`code-review-expert\` Skill 结果由 AI 写入 \`changes/<id>/review/code-review-result.json\`，\`generate-mockito-unit-test\` Skill 结果由 AI 写入 \`changes/<id>/review/unit-test-result.json\``;
 const knowledgeGuardrails = `${baseGuardrails}\n- **知识管理阶段**：knowledge 命令用于管理项目级知识库（最佳实践、陷阱、隐式约定）。
 - **跨变更积累**：知识不绑定单个变更，是长期积累的项目资产。
 - **职责分离**：