@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

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

@@ -2,9 +2,9 @@ const baseGuardrails = `**约束条件**
 - **语言要求**：必须使用中文回答所有问题和输出所有内容（All responses MUST be in Chinese）。
 - 优先采用简单、最小化的实现，仅在请求或明确需要时添加复杂性。
 - 将更改严格限制在请求的结果范围内。
-- **工作区边界（强制）**：查找文档、检索工程代码、读取 \`.llm-wiki\`、执行 grep/glob/ls 时，范围必须限定在当前 ZhuanSpec 工作区内。禁止使用 \`../**\`、上级目录绝对路径或手动拼接到工作区外路径。Glob 返回相对路径时，必须以本次工具调用的 \`path\` 参数作为基准拼接绝对路径，不得误解为当前目录或上级目录。
+- **工作区边界（强制）**：查找文档、检索工程代码、执行 grep/glob/ls 时，范围必须限定在当前 ZhuanSpec 工作区内。禁止使用 \`../**\`、上级目录绝对路径或手动拼接到工作区外路径。Glob 返回相对路径时，必须以本次工具调用的 \`path\` 参数作为基准拼接绝对路径，不得误解为当前目录或上级目录。
 - **知识库参考**：开始任何阶段前，先检查 \`zhuanspec/knowledge/\` 目录。使用 \`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践，避免重复踩坑。阅读 \`zhuanspec/knowledge/index.md\` 了解项目级知识摘要。
-- **工程代码检索顺序**：凡是需要检索工程代码、配置类、数据模型类或关键实现位置时，优先读取已定位服务目录下的 \`[service]/.llm-wiki/index.md\`。\`llmwiki query -e --token <token> "[关键词]"\` 中的 \`<token>\` 必须来自对应服务的 \`[service]/.llm-wiki/index.md\`；每次执行 \`llmwiki query\` 后，必须判断查询结果是否与当前请求诉求匹配，并将关键词、服务、匹配/不匹配结论、简要原因记录到对应服务的 \`[service]/.llm-wiki/result.log\`；查配置类、数据模型类、配置项归属时优先使用 \`llmwiki knowledge points "[关键词]"\`。仅当对应服务的 \`.llm-wiki/\` 不存在、llmwiki 无结果、结果与当前请求诉求不匹配、或结果明显偏差时，才回退到 \`grep/glob/ls\`。
+- **工程代码检索顺序**：凡是需要检索工程代码、配置类、数据模型类或关键实现位置时，必须先调用 \`@skill:load-project-knowledge\` 进行渐进式加载，使用返回的 search_priority 限定检索范围，按优先路径定位代码。仅当 Skill 无匹配结果时，才回退到 \`grep/glob/ls\`。
 - 如果需要额外的 ZhuanSpec 约定或澄清，请参考 \`zhuanspec/AGENTS.md\`（位于 \`zhuanspec/\` 目录内 - 如果看不到，请运行 \`ls zhuanspec\` 或 \`zhuanspec update\`）。`;
 const proposalGuardrails = `${baseGuardrails}\n- **强制澄清要求**：在创建任何提案文件之前，必须首先分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、优先级、验收标准等）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测、假设或创建提案。严禁要求用户手动输入大段文字来回答澄清问题。
 - 识别任何模糊或歧义的细节，使用带预设选项的选择题在编辑文件之前询问必要的后续问题。
@@ -66,13 +66,7 @@ const proposalSteps = `**步骤**
      * 获取：matched_services（涉及的服务列表）、search_priority（检索优先路径）、architecture_constraints（架构约束）
      * 使用：后续代码定位使用 search_priority 限定范围，方案设计检查 architecture_constraints
    - 审查 \`zhuanspec/project.md\`，运行 \`zhuanspec list\` 和 \`zhuanspec list --specs\`
-   - 检查已定位服务是否存在 \`[service]/.llm-wiki/\`：
-     * 若存在，先阅读对应服务目录下的 \`[service]/.llm-wiki/index.md\`
-     * \`llmwiki query -e --token <token> "[关键词]"\` 中的 \`<token>\` 必须来自对应服务的 \`[service]/.llm-wiki/index.md\`
-     * 功能/实现定位优先使用 \`llmwiki query -e --token <token> "[关键词]"\`
-     * 每次执行 \`llmwiki query\` 后，必须判断查询结果是否与当前请求诉求匹配，并将关键词、服务、匹配/不匹配结论、简要原因记录到对应服务的 \`[service]/.llm-wiki/result.log\`
-     * 配置类、数据模型类、配置项归属优先使用 \`llmwiki knowledge points "[关键词]"\`
-   - 检查相关代码或文档时，优先使用 llmwiki 的结果缩小范围；仅当对应服务的 \`.llm-wiki/\` 不存在、llmwiki 无结果、结果与当前请求诉求不匹配、或结果明显偏差时，才通过 \`rg\`/\`ls\`/\`glob\` 兜底；注意任何需要澄清的空白。
+   - **工程代码检索**：使用 \`@skill:load-project-knowledge\` 返回的 search_priority 限定检索范围，按优先路径定位代码；仅当 Skill 无匹配结果时，才通过 \`rg\`/\`ls\`/\`glob\` 兆底。
    - **TechDesign 目录识别**：
      * 扫描 changes/ 目录下的所有变更
      * 检查每个变更的 metrics/progress.json 的 phase 字段
@@ -177,6 +171,36 @@ const proposalSteps = `**步骤**
      * 分层实现说明、关键逻辑 → 写入 \`## 实现细节\`
      * 参数校验、错误码、异常处理 → 写入 \`## 边界条件 / 异常处理\`
    - **摄取原则**：保留原始章节标题和结构，便于 apply 阶段按章节定位；不要压缩或省略具体字段定义
+
+   ⚠️ **CHECKPOINT [DESIGN-EXTERNAL-DEPENDENCY-GATE]**（提案阶段前置闭环，必须在创建 design.md 后立即执行）：
+   依据 techDesign 阶段产出的外部依赖清单（如不存在则从用户提供的技术方案 / specs 中提取），对每一项依赖执行“有疑问就 AskQuestion”原则：
+   1. **依赖识别**：全量罗列 ES 索引 / MQ Topic / Redis key / SCF-RPC 接口 / HTTP API / OSS / Apollo 配置 / 定时任务 共 8 类外部依赖，按类型分桶
+   2. **硬规则使用 AskQuestion**：只要某项依赖的状态、版本、负责方、兜底策略任一字段不明确，**必须** 调用 \`AskQuestion\` 工具一次性展示；严禁默认写 ✅ 或 “待确认”跳过
+   3. **矩阵数据落地**：根据用户回答将结果写入 design.md 的「外部依赖可用性矩阵」段（**6 列**，格式见下），作为后续 propose / apply / 集成验证阶段的唯一事实源
+   4. **闭环完结**：本步骤结束前对账——所有 techDesign 阶段标记为 ⚠️/❓ 的条目必须沉淀为 ✅ / ❌ / ✅+兜底，不允许留白
+
+   外部依赖可用性矩阵（6 列标准格式，必须出现在 design.md）：
+   \`\`\`markdown
+   ## 外部依赖可用性矩阵
+
+   | 依赖名称 | 类型 | 状态 | 版本/环境 | 兜底/阻塞策略 | 负责方 |
+   |----------|------|------|-----------|------------------|--------|
+   | t_customer_ext ES 索引 | ES | ✅ 可用 | prod v7.10 | 必须真实接入 | DBA @zhangsan |
+   | 员工组织树 API | SCF-RPC | ❌ 不可用 | — | 标记 BLOCKED，不生成占位代码 | HR @lisi |
+   | zzmq:customer-sync | MQ | ⚠️ 待确认 | pre 环境未建 | 未解除前用 DB 轮询兜底 | infra @wangwu |
+   | \`dh:customer:merge:*\` Redisson 键 | Redis | ✅ 可用 | prod v4.x | 统一键前缀 + 30s TTL | 本域 |
+   | OSS 导出桶 | OSS | ⚠️ 待确认 | bucket 未申请 | 先用本地文件兜底 | ops @zhaoliu |
+   | Apollo 配置空间 customer.limit | Config | ✅ 可用 | prod | 新增 key 默认值 100 | 本域 |
+   \`\`\`
+
+   列含义：
+   - **依赖名称**：具体到索引/Topic/键/接口类名，禁止写“ES”/“MQ”等类型占位
+   - **类型**：枚举 \`ES|MQ|Redis|SCF-RPC|HTTP|OSS|Config|Job\` 八桶之一
+   - **状态**：枚举 \`✅ 可用\` / \`⚠️ 待确认\` / \`❌ 不可用\`
+   - **版本/环境**：写出确认的版本号或部署环境，未确认则与“状态=⚠️”保持一致
+   - **兜底/阻塞策略**：状态=❌ 必须写 “标记 BLOCKED...”；状态=⚠️ 必须写出兜底方案
+   - **负责方**：确认人或模块负责人（可写 “本域” 表示无需外部确认）
+
 6. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
 
    ⚠️ **CHECKPOINT [SPEC-REQUIREMENT-FORMAT]**：
@@ -304,19 +328,21 @@ const proposalSteps = `**步骤**
    - [ ] 每个任务的「内容」字段自包含：AI 执行时不需要再回溯技术方案猜测实现细节
 
    **D. 外部依赖可用性**（必须在 design.md 中列出）：
-   - [ ] design.md 包含"外部依赖可用性矩阵"段
+   - [ ] design.md 包含"外部依赖可用性矩阵"段（**6 列**：依赖名称 / 类型 / 状态 / 版本环境 / 兜底阻塞策略 / 负责方）
+   - [ ] 矩阵条目按 8 类分桶完整罗列：ES / MQ / Redis / SCF-RPC / HTTP / OSS / Config / Job
    - [ ] 每个外部依赖标注状态：✅ 可用 / ⚠️ 待确认 / ❌ 不可用
    - [ ] 状态为 ❌ 的依赖，对应功能在 tasks.md 中标注"不生成占位实现，标记 BLOCKED"
    - [ ] 状态为 ⚠️ 的依赖，说明兜底方案（如 ES 不可用时用 DB 查询兜底）
-
-   依赖矩阵格式（必须出现在 design.md 中）：
+   - [ ] 条目不得留空或写 TBD，疑问必须在步骤 5 的 DESIGN-EXTERNAL-DEPENDENCY-GATE 中通过 AskQuestion 解决
+   
+   依赖矩阵格式（必须出现在 design.md 中，6 列）：
    \`\`\`
-   | 依赖 | 状态 | 阻塞策略 |
-   |------|------|---------|
-   | ES 集群 | ✅ 可用 | 必须真实接入 |
-   | 员工组织树 API | ❌ 不可用 | 标记 BLOCKED，不生成占位代码 |
-   | MQ Topic | ✅ 可用 | 必须真实消费 |
-   | OSS 导出 | ⚠️ 待确认 | 先用本地文件兜底 |
+   | 依赖名称 | 类型 | 状态 | 版本/环境 | 兜底/阻塞策略 | 负责方 |
+   |----------|------|------|-----------|------------------|--------|
+   | t_customer_ext ES 索引 | ES | ✅ 可用 | prod v7.10 | 必须真实接入 | DBA @zhangsan |
+   | 员工组织树 API | SCF-RPC | ❌ 不可用 | — | 标记 BLOCKED，不生成占位代码 | HR @lisi |
+   | zzmq:customer-sync | MQ | ✅ 可用 | prod | 必须真实消费 | infra @wangwu |
+   | OSS 导出桶 | OSS | ⚠️ 待确认 | bucket 未申请 | 先用本地文件兜底 | ops @zhaoliu |
    \`\`\`
 
    **E. 测试与验收标准**（若为 TDD 模式或已提供测试 case）：
@@ -396,7 +422,7 @@ const proposalSteps = `**步骤**
 const proposalReferences = `**参考**
 - 当验证失败时，使用 \`zhuanspec show <id> --json --deltas-only\` 或 \`zhuanspec show <spec> --type spec\` 检查详细信息。
 - 在编写新要求之前，使用 \`rg -n "Requirement:|Scenario:" zhuanspec/specs\` 搜索现有要求。
-- 探索代码库时，先检查已定位服务目录下是否存在 \`[service]/.llm-wiki/\`；若存在，先阅读 \`[service]/.llm-wiki/index.md\`，并使用其中提供的 token 执行 \`llmwiki query -e --token <token> <keyword>\`，随后判断查询结果是否与当前请求诉求匹配，并将关键词、服务、匹配/不匹配结论、简要原因记录到对应服务的 \`[service]/.llm-wiki/result.log\`；也可使用 \`llmwiki knowledge points <keyword>\` 缩小范围。仅在 llmwiki 不可用、未命中、或结果与当前请求诉求不匹配时，再使用 \`rg <keyword>\`、\`ls\` 或直接文件读取。`;
+- 探索代码库时，先调用 \`@skill:load-project-knowledge\` 进行渐进式加载，使用返回的 search_priority 限定检索范围，按优先路径定位代码。仅当 Skill 无匹配结果时，再使用 \`rg <keyword>\`、\`ls\` 或直接文件读取。`;
 const applySteps = `**步骤**
 将这些步骤作为待办事项跟踪，逐一完成。
 1. **检查知识库并确认 Phase**：
@@ -503,15 +529,67 @@ const applySteps = `**步骤**
       - 提取状态为 DONE_WITH_CONCERNS 或 BLOCKED 的任务及其 concerns/blocker 原因
       - 将结果记录到集成测试报告的 **Concerns 追踪章节**
 
-   B5. **阻塞任务重试**：
-      - 将当前 Wave 中编译失败被标记为 BLOCKED 的任务重新执行
-      - 重新启动 subagent 执行阻塞任务（此时可利用同 Wave 已完成任务的上下文）
-      - 重试后仍失败 → 记录到集成测试报告
+   B4.1. **外部依赖全量扫描与兜底闭环（MANDATORY，不允许遗漏）**：
+      此环节是提案阶段 DESIGN-EXTERNAL-DEPENDENCY-GATE 的**集成验证兑现验收点**，用于兜底“新产生的未知外部依赖 / 原矩阵漏网项”，严禁遗漏。步骤必须完整依序执行：
+
+      **第一步：三类来源全量采集**
+      1. 从 \`design.md\` 的「外部依赖可用性矩阵」6 列表格提取原始清单（包含状态 ✅ / ⚠️ / ❌ 和负责方）
+      2. 从本 Wave 所有任务报告的 concerns / blocker 文本中提取涉及外部依赖的条目（关键词：ES / 索引 / MQ / Topic / Consumer / Redis / RPC / SCF / HTTP / OSS / Apollo / xxl-job / 定时任务 ...）
+      3. 对本 Wave 新增 / 修改的源码做静态扫描，抓取上述关键词所对应的注解 / API 调用 / Bean 注入（例：\`@MessageConsumer\` / \`RedisTemplate\` / \`@ApolloJsonValue\` / \`@XxlJob\` / \`@ServiceContract\`）
+
+      **第二步：按下述 8 桶分类**，将第一步的汇总项映射到桶中，**每一桶都必须给出结论**（没有项 → 显式写 \`—\` 并注明已确认无依赖，禁止跳过桶）：
+      \`\`\`
+      桶 1：ES（索引 / 查询 / 异构同步）
+      桶 2：MQ（zzmq / RocketMQ Producer / Consumer / Topic）
+      桶 3：Redis（缓存 key / Redisson 分布式锁 / ZZLock）
+      桶 4：SCF-RPC（@ServiceContract 下游接口 / contract、client pom 依赖是否已引入 / 版本是否需要升级）
+      桶 5：HTTP（第三方 REST API / 网关 / Webhook）
+      桶 6：OSS（导入 / 导出 / 附件存储 bucket）
+      桶 7：Config（Apollo namespace / 环境变量 / 配置项）
+      桶 8：Job（xxl-job 注册 / cron / 分片任务）
+      \`\`\`
+
+      **第三步：状态不明确的桶强制 AskQuestion**
+      - 对任一桶中出现下列情形 → **必须** 调用 \`AskQuestion\` 一次性批量向用户澄清：
+        * design.md 矩阵中状态=❌ 或 ⚠️ ，且任务报告仍在涉及该依赖
+        * 第一步代码扫描发现新的 / 未录入矩阵的依赖项
+        * 任务报告的 concern 文本明确说明“给了占位 / 默认兜底 / 待核实”
+        * 桶内无任何条目 但 Wave 新增代码涉及该类型关键词（依赖声明遗漏）
+      - 严禁以“任务状态为 DONE_WITH_CONCERNS 且有报告就算闭环”为由跳过 AskQuestion；必须拿到用户选项式答复
+
+      **第四步：对账表写回集成报告**
+      - 将本步骤结果写入集成测试报告的 **外部依赖兜底对账表**（5 列）：
+        \`\`\`
+        | 桶 | 依赖条目 | 来源（矩阵/报告/代码） | 解决状态（✅ 真实实现 / ❌ BLOCKED / ✅+兜底） | 后续动作 |
+        \`\`\`
+      - 所有 ✅+兜底 条目必须同步回写 design.md 矩阵（结束时两份数据保持一致）
+      - 存在任一桶结论缺失 → B6 报告整体状态强制标记 FAIL，阻断进入下一 Wave
+
+      **第五步：依赖补齐后即刻列出重跑清单（MANDATORY，澄清 ≠ 闭环）**
+      - 扫描本 Wave 所有状态为 \`NEEDS_CONTEXT\` 或 \`BLOCKED\` 的任务报告，识别「阻断原因涉及本次 AskQuestion 已澄清依赖 / 兜底对账表中解决状态变为 ✅ 的条目」的任务
+      - 在集成测试报告中新增 \`## 🔁 待重试任务清单\` 段（5 列）：
+        \`\`\`
+        | 任务ID | 原状态 | 阻断原因（concern 摘要） | 已澄清/补齐的依赖条目 | 重跑执行方 |
+        \`\`\`
+      - **立刻移交 B5 统一执行重跑**（不得拖到全局 Concerns 汇总；不得将 NEEDS_CONTEXT 当 DONE_WITH_CONCERNS 混过）
+      - 若清单为空（本 Wave 无需重跑）→ 显式写 \`— 无需重跑\`，禁止省略该段
+
+   B5. **阻塞任务重试（BLOCKED ∪ NEEDS_CONTEXT 合并处理）**：
+      - 重试对象覆盖两类：
+        a. 编译失败 / 测试失败被标记为 \`BLOCKED\` 的任务（原有范围）
+        b. B4.1 第五步「待重试任务清单」中因外部依赖已澄清而解锁的 \`NEEDS_CONTEXT\` / \`BLOCKED\` 任务
+      - 重跑前确认：design.md 矩阵已写回澄清结果（与兜底对账表一致），否则 subagent 仍会读到旧状态再次报 NEEDS_CONTEXT
+      - 重新启动 subagent（\`applyAgent\` / \`tddApplyAgent\`），**在下发 prompt 中显式标注 \`Execution Mode = RETRY\`** 并附带：
+        * 上次报告中的 concerns / blocker 摘要
+        * 本次澄清补齐的依赖条目（来自兜底对账表）
+        * 最新 design.md 矩阵片段
+      - 重试后仍失败 → 保留 BLOCKED 状态并记录到集成测试报告；B6 整体状态强制 FAIL
 
    B6. **生成集成测试报告（MANDATORY，不得跳过）**：
       - 报告路径：\`changes/<change-id>/reports/wave-{N}-integration-report.md\`
       - 记录所有任务执行结果、编译检查结果、阻塞任务重试结果
       - **MUST 包含 Concerns 追踪章节**，列出所有 DONE_WITH_CONCERNS 和 BLOCKED 任务及其疑虑
+      - **MUST 包含 \`## 🔁 待重试任务清单\` 段**（即使为空也要写 \`— 无需重跑\`），与 B4.1 第五步、B5 重试结果汇总一致
       - 整体状态：所有检查通过且无未解决的阻塞任务 → PASS
       - **未生成报告文件 → 阻断，不得进入下一 Wave**
 
@@ -551,9 +629,10 @@ const applySteps = `**步骤**
    - 如果存在未解决的 Concerns：
      * 输出汇总列表（任务ID、状态、疑虑内容、建议后续处理）
      * **选项式提问用户**：
-       a. “全部修复” → 逐个处理未解决的 concerns
-       b. “忽略并继续” → 记录用户决策后进入 TC 验证
-       c. “部分修复” → 让用户选择哪些需要修复
+       a. “全部修复” → 对每个未解决 concern 对应任务，**以 \`Execution Mode = RETRY\` 重新下发 subagent**（applyAgent / tddApplyAgent），重跑产出新报告后回到本步骤再次扫描，直至 Concerns 清零或用户改选 b/c
+       b. “忽略并继续” → 记录用户决策（含忽略原因）后进入 TC 验证
+       c. “部分修复” → 让用户勾选待修复任务，**仅对勾选任务按 RETRY 模式重新下发**，其余记录决策后进入 TC 验证
+     * **「修复」选项的执行契约（MANDATORY）**：选 a 或 c 后，对所选任务以 \`Execution Mode = RETRY\` 重新 spawn subagent（applyAgent / tddApplyAgent）；prompt 中须附带：上次报告 concerns 摘要 + 本次已澄清的依赖条目 + 最新 design.md 矩阵片段。重跑产出新报告后回到本步骤再次扫描，直至 Concerns 清零或用户改选 b。禁止在主线程串行“修复”或在没有重新产出报告的前提下手动改成 DONE
    - 如果无未解决的 Concerns：直接进入 TC 验证
 9. **TC 实现验证** - 所有任务完成后、进入审查门禁前：
    - 检查提案目录中是否存在 \`test-cases.md\`
@@ -614,12 +693,15 @@ const archiveSteps = `**前置检查**：
    - \`progress.phaseDurations\` 必须关闭 review 段并开启 archive 段
 2. 通过运行 \`zhuanspec list\`（或 \`zhuanspec show <id>\`）验证变更 ID，如果变更缺失、已归档或尚未准备好归档，则停止。
 3. **验证 Review 门禁**：确认上述五个结果文件存在且全部通过（含轨道 4 的 \`closure-check-result.json\`）。
-4. 运行 \`zhuanspec archive <id> --yes\`，以便 CLI 移动变更并应用规范更新，无需提示（仅对仅工具类工作使用 \`--skip-specs\`）。
-5. 审查命令输出以确认目标规范已更新，并且变更已进入 \`changes/archive/\`。
-6. 使用 \`zhuanspec validate --strict\` 进行验证，如果看起来有问题，使用 \`zhuanspec show <id>\` 进行检查。
-7. **知识沉淀（手动补充）**：调用 \`@skill:zhuanspec:knowledge\` skill 从本次会话记忆中补充知识。
+4. **知识沉淀（手动补充，必须前置）**：调用 \`@skill:zhuanspec:knowledge\` skill（模式 A）从本次会话记忆中补充知识。
+   - 🔴 **红线（顺序不可调整）**：本步骤**必须**在执行 \`zhuanspec archive <id>\` 之前完成。\`zhuanspec archive\` 命令内部会按顺序执行 \`postArchiveHook\`（自动结构化提取） → \`pushArchiveResultToRemote\`（一次性同步 specs / archive / knowledge 三目录到远端）；如果把手动沉淀放在 archive 命令之后，新写入的 knowledge 文件**仅落本地**，不会被推送到远端模板仓库，团队其他成员将看不到。
+   - 🔴 **禁止 AI 自行决定沉淀内容**：必须严格按 zhuanspec:knowledge skill 模式 A 步骤 4 执行——先列候选清单，再调用 \`askUserQuestion\` 让用户多选确认，再写入。禁止默认全沉淀，禁止跳过询问。
    - CLI 已自动从变更目录提取结构化知识（design.md/proposal.md/tasks.md 中的决策、注意事项等）
    - AI 需从会话记忆补充无法自动提取的内容（如对话中发现的隐式约定、调试陷阱等）
+   - 用户选择「跳过本次沉淀」时，本步骤可不写入任何文件，但仍需经过显式确认环节，禁止默认跳过。
+5. 运行 \`zhuanspec archive <id> --yes\`，以便 CLI 移动变更并应用规范更新，无需提示（仅对仅工具类工作使用 \`--skip-specs\`）。**该命令将自动 push specs / archive / knowledge 三目录到远端**，因此必须在步骤 4 完成知识沉淀后才执行。
+6. 审查命令输出以确认目标规范已更新，并且变更已进入 \`changes/archive/\`，且 "推送到远端" 段输出 \`✅ 已推送归档结果到远端\`（如使用 \`--skip-specs\` 则跳过推送）。
+7. 使用 \`zhuanspec validate --strict\` 进行验证，如果看起来有问题，使用 \`zhuanspec show <id>\` 进行检查。
 8. **会话分析**：调用 \`@skill:session-analytics\` skill 分析本次会话的指标数据（工具调用、Token消耗、时长等）。
 9. **输出反馈链接**：告知用户填写使用反馈：
    📋 https://doc.weixin.qq.com/forms/AJ4AfQfgAAwACwAAwaVABsCNqDXIKn8sf`;
@@ -627,8 +709,8 @@ const archiveReferences = `**参考**
 - 在归档之前使用 \`zhuanspec list\` 确认变更 ID。
 - 使用 \`zhuanspec list --specs\` 检查刷新的规范，并在移交之前解决任何验证问题。
 - 知识提取分工：
-  - **CLI 自动**：归档时从变更目录（proposal.md/tasks.md/design.md/specs/*.md）正则提取结构化知识
-  - **AI 手动**：调用 \`zhuanspec:knowledge\` skill 从会话记忆补充隐式约定、调试发现等
+  - **CLI 自动**（archive 命令内）：归档时从变更目录（proposal.md/tasks.md/design.md/specs/*.md）正则提取结构化知识，写入本地 \`zhuanspec/knowledge/\`，随后由同一条 archive 命令一并 push 到远端
+  - **AI 手动**（archive 命令前）：调用 \`zhuanspec:knowledge\` skill 从会话记忆补充隐式约定、调试发现等。**必须在 \`zhuanspec archive\` 命令之前**调用，否则补充内容仅落本地、不会进入远端推送
 - 会话分析 (\`session-analytics\`)：记录本次会话的效率指标，用于改进工作流。`;
 const designGuardrails = `${baseGuardrails}\n- **独立设计阶段**：techDesign 命令用于在 proposal 之前生成技术设计请求文档，不依赖变更提案。设计文档可作为后续提案的输入。
 - **需求澄清优先**：在生成设计请求前，必须确认需求来源（大神页面、需求描述文本等）。
@@ -709,6 +791,31 @@ const designSteps = `**步骤**
    - Skill 会自动获取大神页面内容并生成完整技术方案文档
    - **禁止**：在未完成步骤 4 的开发范围确认和步骤 5 的 Skill 可用性校验前调用任何 Skill；禁止两个 Skill 同时调用。
 
+6.5. **新增表澄清与数据存储策略（硬约束，存在新增表时必须执行）**：
+   - 从步骤 6 产出的 tech-spec.md 中提取所有 **新增/重构 DB 表**（关键词：CREATE TABLE / 新增表 / t_* / 新建业务表），形成候选表清单。若无新增表 → 跳过本步并在技术方案写明“无新增表，无需数据存储策略评估”
+   - 对每张新增表，**必须** 调用 \`AskQuestion\` 向用户批量澄清下列字段（可多表合并一次问答），严禁默认和代书填入：
+     1. **预估数量级**：枚举 \`< 10w\` / \`10w~100w\` / \`100w~1000w\` / \`> 1000w\`
+     2. **查询场景**：枚举 \`单表查询\` / \`连表查询\` / \`跨库查询\` / \`复杂聚合/全文搜索\`
+     3. **QPS 量级**：枚举 \`读 < 50\` / \`读 50~500\` / \`读 > 500\`；写入同样枚举
+     4. **数据时效性**：枚举 \`强一致\` / \`最终一致（分钟级）\` / \`T+1 离线\`
+     5. **一致性要求**：枚举 \`强一致\` / \`最终一致\` / \`弱一致\`；并追问 **是否跨表事务**（是 / 否）
+   - 根据用户回答自动推荐 **存储策略**（用 Skill 或启发式规则均可）：
+     * 数量级 ≥ 100w 且写 QPS 不高 → 建议 **分库分表**（或 OLAP 异构），在技术方案补充分片键 / 路由策略
+     * 读 QPS ≥ 500 或 表 ≥ 1000w → 建议 **引入 Redis 缓存**，给出缓存 key / TTL / 失效策略
+     * 查询场景为“复杂聚合/全文搜索”或表 ≥ 1000w 且需多维度筛选 → 建议 **引入 ES 异构索引**，描述写入时机与同步方案
+     * 一致性要求为“强一致”且跨表事务为“是” → 不使用 最终一致方案（Redis/ES 异构 仅做旁路），主链路用 MySQL 事务，必要时补 TCC / 补偿
+     * 其余情形 → 保留仅 MySQL，补充必要索引设计
+   - 将澄清结果和存储决策写入技术方案的「## 数据存储策略」段（固定模板）：
+     \`\`\`markdown
+     ## 数据存储策略
+
+     | 表名 | 预估数量级 | 查询场景 | 读/写 QPS | 时效性 | 一致性（含跨表事务） | 存储策略 | 备注 |
+     |------|-----------|---------|------------|--------|-------------------|---------|------|
+     | t_customer_ext | 100w~1000w | 多维度筛选 | 800 / 100 | 最终一致 | 最终一致 / 否 | MySQL + ES 异构 | 写入后异步同步 ES |
+     | t_customer_tag_link | < 10w | 单表 | 50 / 5 | 强一致 | 强一致 / 是 | 仅 MySQL + 联合索引(tenant_id,customer_id) | — |
+     \`\`\`
+   - ⚠️ **CHECKPOINT [DATA-STORAGE-STRATEGY]**：表行任一列写 \`TBD\` / 空 / \`待评估\` → 本步骤未通过，禁止进入步骤 7
+
 7. **外部依赖可用性确认（必须在技术方案定稿前执行）**：
    - 从 Skill 生成的技术方案中提取所有外部依赖（ES、MQ、Redis、OSS、权限服务、员工组织树 API、下游 RPC 等）
    - 使用 AskQuestion 工具逐项确认可用状态：
@@ -757,24 +864,34 @@ const reviewGuardrails = `${baseGuardrails}\n- **门禁审查阶段**：review
 - **Schema 版本**：新生成的 \`code-review-result.json\` / \`unit-test-result.json\` / \`closure-check-result.json\` 必须包含 \`"schemaVersion": 2\` 字段以启用 Skill 真实性硬校验；缺失或 < 2 时 CLI 会按历史数据豁免并打 ⚠️ 警告，禁止借 legacy 通道规避校验。`;
 const reviewSteps = `**步骤**
 0. **⚠️ 纠偏沉淀优先检查（Phase 切换前强制执行）**：
-   - 读取 \`zhuanspec/changes/<change-id>/metrics/progress.json\`，检查以下两个字段：
-     - \`corrections\` 数组是否存在且有元素（\`length > 0\`）
+   - **计数源（两级 fallback，新→旧）**：
+     - Level 1：读 \`zhuanspec/changes/<change-id>/metrics/user_inputs.json\`，筛选 \`correctionSignal.kind === 'hard' && postBaseline === true\` 的条目作为纠偏明细
+     - Level 2：\`user_inputs.json\` 存在但条目缺 \`correctionSignal\` → 按 \`inputs[*].summary\` 关键词扫描推断
+   - **同时读** \`zhuanspec/changes/<change-id>/metrics/progress.json\`，检查：
+     - 上述任一 Level 得到的纠偏条目数 N 是否 > 0
      - \`askedPitfallSaved\` 字段是否为 \`true\`
-   - **如果满足条件（corrections 非空 且 askedPitfallSaved !== true）**：
-     - **立即调用 \`AskUserQuestion\` 工具**，以二选一方式询问用户：
-       \`\`\`
-       header: "踩坑沉淀"
-       question: "本轮 Apply 阶段发生过 N 次用户纠偏（N 为 corrections 数组的实际长度，请列出最近 3 条 promptPreview 摘要），是否沉淀为项目知识？"
-       选项 1: "是，沉淀"
-       选项 2: "否，跳过"
-       \`\`\`
-     - **用户选择"是"时**：
-       1. **必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`**（或等价的 \`/zhuanspec:knowledge\` slash command 并在交互中选择模式 B）来完成沉淀
-       2. 本 skill 将自动完成：读取 \`.correction-log\` → 分类决策树归入 \`troubleshooting/\` / \`best-practices/\` / \`implicit-conventions/\` → 去重扫描 → 套用统一 Front Matter → 写入知识文件 → 更新 \`knowledge/index.md\` → 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`
-       3. **红线**：**禁止主 agent 自行使用 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**，禁止自行判定分类或文件名格式；禁止新建 \`decisions/\` 或三类目录以外的分类。
-     - **用户选择"否"时**：
-       - 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\` 标记已处理，不写入任何知识文件
-   - **如果不满足条件（无纠偏或已沉淀）**：直接进入下一步
+   - **如果满足条件（N > 0 且 askedPitfallSaved !== true）**：
+     1. **先生成决策清单（必须）**：运行
+        \`\`\`bash
+        zhuanspec progress list-corrections <change-id>
+        \`\`\`
+        CLI 会完成：读 user_inputs.json → 过滤 trivial 确认词（如“是的/好的/ok”）→ 去重（完全重复 + 子串包含）→ 启发式分类 → 写到 \`zhuanspec/changes/<change-id>/review/pending-corrections.md\`。并在 stdout 输出 **合计 / 有效 / 过滤** 三个计数。
+     2. **调用 \`AskUserQuestion\`（三选项，禁止默认）**：
+        \`\`\`
+        header: "踩坑沉淀"
+        question: "本轮有 M 条有效纠偏候选（已过滤 trivial / 去重，详见 review/pending-corrections.md），请选择沉淀范围："
+        选项 1："全部沉淀"
+        选项 2："选择性沉淀（请回复编号清单，例如 1,3,5）"
+        选项 3："跳过"
+        \`\`\`
+        🔴 **红线**：禁止跳过本次询问；禁止仅根据最近 N 条摘要就起心动念、绕过清单文件。
+     3. **用户选择 "全部沉淀" 或 "选择性沉淀"**：
+        - 必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`（或 \`/zhuanspec:knowledge\` 交互模式 B）来完成沉淀。
+        - 选择性沉淀时，把用户回复的编号清单以 \`--include <编号串>\` 形式透传给 skill（例：\`--include 1,3,5\`），或在 skill 交互中照实转述编号。skill 必须以 \`pending-corrections.md\` 作为商定范围的单一源，禁止从会话记忆里“发挥”额外条目。
+        - skill 完成后会自动运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`。
+        🔴 **红线**：禁止主 agent 自行使用 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件；禁止自行判定分类或文件名格式；禁止新建 \`decisions/\` 或三类目录以外的分类。
+     4. **用户选择 "跳过"**：运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。
+   - **如果不满足条件（无纠偏或已沉淀）**：直接进入下一步。
 
 1. **切换 Phase 到 review（第一步，必须立即执行）**：
    - 如果此提示已包含特定的变更 ID，请使用该值；否则运行 \`zhuanspec list\` 显示活跃变更并询问用户要审查哪个
@@ -891,7 +1008,7 @@ const knowledgeGuardrails = `${baseGuardrails}
 - **职责分离**：
   - **CLI 自动提取**（归档阶段 post-archive）：从变更目录 design.md/proposal.md/tasks.md/specs 抽取结构化知识。CLI 的"决策类"输出归并到 \`best-practices/\`，不再写入 \`decisions/\`。
   - **AI 手动补充**（本 skill 模式 A）：从会话记忆中补充无法自动提取的知识。
-  - **纠偏沉淀**（本 skill 模式 B）：对接 apply 阶段 \`.correction-log\` 的纠偏记录。`;
+  - **纠偏沉淀**（本 skill 模式 B）：对接 apply 阶段 \`user_inputs.json\` 的纠偏记录。`;
 const knowledgeSteps = `**步骤**
 
 本 skill 支持两种模式，触发方式不同、流程不同：
@@ -948,12 +1065,34 @@ const knowledgeSteps = `**步骤**
 3. **搜索**：
    - \`rg "<关键词>" zhuanspec/knowledge/\`
    - 结合 \`index.md\` 关键词段快速锁定
-4. **从会话添加**：
-   - 先按**分类决策树**判定归属目录；**禁止**凭习惯写到 decisions/
-   - 先 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\` 做去重扫描：若命中高度相似条目 → 在已有文件追加 \`## 追加：<日期>\` 章节，不新建文件
-   - 否则新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`，严格套用上面的 Front Matter 模板
+4. **从会话添加（强制：先列候选 → 用户确认 → 再写入）**：
+
+   🔴 **红线**：禁止 AI 自行判断 "哪些内容值得沉淀" 后直接 Write/Edit。必须严格走完 4.1 → 4.2 → 4.3 → 4.4 四个子步骤，缺一不可。
+
+   **4.1 列候选清单（不写入任何文件）**：
+   基于本次会话记忆，按【分类决策树】先列出所有 "待沉淀候选条目"，每条必须包含：
+   - 序号（1、 2、 3 …）
+   - 候选标题（≤ 30 字）
+   - 命中分类（\`troubleshooting\` / \`best-practices\` / \`implicit-conventions\`）
+   - 一句话理由（来自会话哪段对话 / 哪个修复 / 哪条纠偏）
+   - 拟用文件名（\`<YYYYMMDD>-<kebab-slug>.md\`）
+   - 重复检查结果：先对主关键词执行 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\`，命中需展示对应文件路径与拟采取动作（追加章节 vs 新建文件）
+
+   **4.2 调用 \`askUserQuestion\` 让用户决策（必须多选，禁止默认）**：
+   - 选项 A：全部沉淀
+   - 选项 B：选择性沉淀（用户回复编号清单，例如 \`1,3,5\`）
+   - 选项 C：跳过本次沉淀
+   - 🔴 **红线**：禁止「默认全沉淀」，禁止「跳过此询问」，禁止「合并多条后一次性写入」。askUserQuestion 未调用前不得启动任何 Write/Edit/MultiEdit 操作。
+
+   **4.3 按用户决策写入**：
+   - 用户未选中的条目一律不写入，不生成任何文件
+   - 命中重复的：在已有文件追加 \`## 追加：<日期>\` 章节，不新建文件
+   - 新条目：新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`，严格套用上面的 Front Matter 模板
    - **同步更新** \`zhuanspec/knowledge/index.md\`：在对应分区（\`## Troubleshooting\` / \`## Best Practices\` / \`## Implicit Conventions\`）追加一行 \`- [<标题>](<category>/<文件名>) — <关键词摘要>\`
 
+   **4.4 输出摘要**：
+   列出本轮新建 / 追加 / 被跳过的候选编号与路径，供用户复核。
+
 ---
 
 ## 模式 B：纠偏沉淀（Apply 阶段收尾 / Review 步骤 0 / PostToolUse 触发）
@@ -962,26 +1101,26 @@ const knowledgeSteps = `**步骤**
    - 优先使用入参 \`--correction <change-id>\`
    - 否则读取 \`zhuanspec/changes/*/metrics/progress.json\`，定位 \`corrections.length > 0 && askedPitfallSaved !== true\` 的 change-id
    - 同时存在多个时，调用 \`askUserQuestion\` 让用户二选一，严禁随意选择
-2. **读取原始纠偏记录**（两份必须都读）：
-   - \`zhuanspec/changes/<change-id>/.correction-log\`（JSONL，每行含 \`ts\` / \`event\` / \`promptPreview\` / \`reason?\`）
-   - \`zhuanspec/changes/<change-id>/metrics/progress.json\` 的 \`corrections\` 数组
-3. **用户二次确认（强制）**：
-   - 将最近 3 条 promptPreview 摘要打印给用户
-   - 调 \`askUserQuestion\`：\`是，沉淀 / 否，跳过\`
-   - 用户选"否"时，直接跳到步骤 7 只做 resolve-correction --mark-pitfall-saved，不写入任何文件
-4. **逐条分类**：对每条 correction 走上面的「分类决策树」，得到 \`<category>\`。
+2. **以 pending-corrections.md 为起点（商定范围的唯一源）**：
+   - 检查文件是否存在：\`zhuanspec/changes/<change-id>/review/pending-corrections.md\`。不存在则运行 \`zhuanspec progress list-corrections <change-id>\` 生成（CLI 已含 trivial 过滤 + 去重）。
+   - 清单已明确标出：有效候选编号 / 拟分类 / 拟用文件名 / 已过滤明细（trivial / 过短 / 重复 / 子串包含）。**模式 B 只从这份清单里取候选**，禁止从会话记忆里“发挥”额外条目。
+3. **范围决策（跟随 review 步骤 0 的三选项）**：
+   - 接收入参 \`--include <编号串>\`（如 \`--include 1,3,5\`）表示选择性沉淀；未传则默认 = 全部有效候选。
+   - 若未提供且不是从 review 步骤 0 / Stop hook 走进来，调 \`askUserQuestion\` 让用户三选一：\`全部沉淀 / 选择性沉淀（回复编号串） / 跳过\`。
+   - 选择“跳过”时，直接跳到步骤 7 只做 resolve-correction --mark-pitfall-saved，不写入任何文件。
+4. **逐条分类**：对选中的每条候选走上面的「分类决策树」，可参考清单里的「拟分类」作为起点，但决策树优先级更高。
 5. **去重扫描**：对每条（含其关键词）先执行 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\`：
    - 命中相似条目 → 在已有文件追加 \`## 追加：<日期> — <change-id>\` 章节
    - 未命中 → 新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`
 6. **写入文件**（严格使用统一 Front Matter 模板）：
    - \`**来源**\` 字段固定写 \`用户纠偏（change: <change-id>）\`
    - \`**来源变更**\` 字段固定写 \`<change-id>\`
-   - \`## 背景\` / \`## 问题 / 经验\` / \`## 解决方案 / 建议\` 必须基于 \`.correction-log\` 原始 promptPreview 与当次会话上下文还原，**禁止编造**
+   - \`## 背景\` / \`## 问题 / 经验\` / \`## 解决方案 / 建议\` 必须基于 user_inputs.json 的 fullPrompt / summary 与当次会话上下文还原，**禁止编造**
    - 同步更新 \`zhuanspec/knowledge/index.md\` 对应分区
-7. **标记已处理（强制收尾，无论步骤 3 用户选是/否）**：
+7. **标记已处理（强制收尾，无论步骤 3 用户选什么）**：
    - 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`
    - 确认 \`progress.json.askedPitfallSaved === true\`，避免下次 Stop hook 重复询问
-8. **输出摘要**：列出本轮新建 / 追加的知识文件路径 + index.md 更新行；报告 \`<change-id>\` 的纠偏沉淀已完成。
+8. **输出摘要**：列出本轮新建 / 追加 / 被跳过的知识文件路径 + index.md 更新行；报告 \`<change-id>\` 的纠偏沉淀已完成。
 
 ---
 
@@ -989,6 +1128,7 @@ const knowledgeSteps = `**步骤**
 - 所有写入 knowledge 目录的动作只能经本 skill 完成；禁止主 agent 或其他流程自行 Write。
 - 只能写入三类目录之一，禁止新建 decisions/。
 - 文件名、Front Matter、index.md 更新三者缺一不可。
+- **模式 A 写入前必须走完「列候选（4.1） + askUserQuestion 多选确认（4.2）」双步骤**；禁止 AI 自行判断「哪些内容值得沉淀」后直接写入，禁止默认全沉淀，禁止跳过询问环节。
 - 模式 B 必须以 \`resolve-correction --mark-pitfall-saved\` 收尾。`;
 const knowledgeReferences = `**参考**
 - 参考样例（格式基准）：项目 \`zhuanspec/knowledge/best-practices/oms-call-pattern.md\`、\`zhuanspec/knowledge/troubleshooting/20260506-apply-pitfalls.md\`、\`zhuanspec/knowledge/implicit-conventions/outbound-cis-inventory-lock.md\`
@@ -997,7 +1137,9 @@ const knowledgeReferences = `**参考**
   - \`best-practices/\` — 可复用的最佳实践、设计决策落地
   - \`implicit-conventions/\` — 隐式约定、默认行为、团队惯例
 - CLI 归档时自动从变更目录提取知识（post-archive hook）；所有"决策类"输出归入 \`best-practices/\`
-- 模式 B 依赖文件：\`zhuanspec/changes/<change-id>/.correction-log\`（JSONL）、\`metrics/progress.json.corrections\`
+- 模式 B 依赖文件（两级 fallback，按优先级）：
+  1. \`zhuanspec/changes/<change-id>/metrics/user_inputs.json\`（v2.15.15+ 主数据源，含 \`fullPrompt\` / \`correctionSignal\` / \`postBaseline\` / \`resolution\`）
+  2. \`zhuanspec/changes/<change-id>/metrics/progress.json\` 的 \`corrections\` 数组（计数交叉校验）
 - 模式 B 收尾命令：\`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\``;
 export const slashCommandBodies = {
     proposal: [proposalGuardrails, proposalOutputFormat, proposalSteps, proposalReferences].join('\n\n'),

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

@@ -40,6 +40,25 @@ Answer: <!-- user answer -->
 <!-- If @skill:none, MUST provide justification in description -->
 <!-- @skill names MUST match exactly the names returned by \`zhuanspec skills list\` -->
 
+### 中间件/基础能力 → 必选 Skill 映射（强制项）
+
+任务描述出现下表任一关键词时，@skill 字段 **MUST** 引用对应 Skill（多个用逗号分隔）：
+
+| 任务涉及中间件/能力 | 关键词识别 | 必选 @skill |
+|--------------------|-----------|-------------|
+| MQ Producer/Consumer | zzmq / RocketMQ / Topic: / @MessageConsumer / @MessageProducer | java-middleware-usage-skill |
+| 定时任务 | xxl-job / @JobHandler / @XxlJob / cron | java-middleware-usage-skill |
+| 分布式锁 | Redisson / @RedissonLock / ZZLock | java-middleware-usage-skill |
+| Apollo 配置 | @ApolloJsonValue / apollo / 配置中心 | java-middleware-usage-skill |
+| Redis 缓存 | @Cacheable / RedisTemplate / Lettuce / 缓存 | java-middleware-usage-skill |
+| SCF RPC | @ServiceContract / @SCFInterface / scf-client / SCF 接口 | java-scf-rpc-usage-skill |
+| DAO / Mapper | Mapper.xml / MyBatis / selectByXxx / @MyBatis | java-db-schema-standards |
+| Elasticsearch | Elasticsearch / ES 索引 / ES 异构索引 | es-integration（若已注册） |
+
+未来扩展：新增中间件参考文件时，同步追加本表及 \`src/core/validation/strict-rules.ts\` 的中间件关键词白名单。
+
+### 实现区域 Skill 关联
+
 | 实现区域 | 实际功能 | 关联 Skill | 匹配理由 |
 |---------|---------|-----------|---------|
 | <!-- module/file --> | <!-- actual function --> | <!-- skill name --> | <!-- why it matches --> |
@@ -72,6 +91,31 @@ Answer: <!-- user answer -->
   4. 确保引用的章节在技术方案文档中存在
 -->
 
+## 分层拆分原则（强制）
+
+⚠️ **大型需求拆分时 MUST 遵循以下分层约束**，每个任务只实现"一个功能模块的一层代码"，禁止跨层混合：
+
+| Wave | 允许层 | 代表任务 |
+|------|--------|---------|
+| Wave 1（底层） | \`dao\` + 外部 \`assemble\` + \`ddl\` + \`config\` | Mapper/DAO/Entity/Mapper.xml、对外 SCF/HTTP 封装类 |
+| Wave 2（中间层） | \`domain\` + \`application\` | DomainService（单聚合）、ApplicationService（跨聚合编排） |
+| Wave 3（顶层） | \`entry-*\` + \`fe\` | SCF 实现/Controller、MQ Producer/Consumer、xxl-job Handler、前端页面 |
+
+**任务 @layer 标签白名单**（必填项，与 \`@skill\`/\`@depends\`/\`@ref\` 并列）：
+- \`@layer:dao\` / \`@layer:assemble\` / \`@layer:domain\` / \`@layer:application\`
+- 入口层细分：\`@layer:entry-scf\` / \`@layer:entry-mq-producer\` / \`@layer:entry-mq-consumer\` / \`@layer:entry-job\`
+- 纯前端/配置/DDL 可用：\`@layer:fe\` / \`@layer:config\` / \`@layer:ddl\`
+
+**拆分步骤**（由 Propose Agent 在任务分解前执行）：
+1. 先按上表把所有要新增/修改的文件归入分层桶；
+2. 同一层允许多个任务，**但单任务禁止横跨两层**；
+3. 按 Wave 顺序编号，Wave 数量可扩展（例如 ES 索引初始化可放 Wave 0）。
+
+**按 \`@layer\` 自动归 Wave（先分层后填 Wave 编号，禁止混层）**：
+- Wave 1 （底层） = \`@layer:dao\` / \`@layer:assemble\` / \`@layer:ddl\` / \`@layer:config\`
+- Wave 2 （中间层） = \`@layer:domain\` / \`@layer:application\`
+- Wave 3 （顶层） = \`@layer:entry-scf\` / \`@layer:entry-mq-producer\` / \`@layer:entry-mq-consumer\` / \`@layer:entry-job\` / \`@layer:fe\`
+
 ## 任务格式说明
 
 ⚠️ **所有任务项必须使用 GitHub Flavored Markdown 复选框格式**：
@@ -80,11 +124,11 @@ Answer: <!-- user answer -->
 - **严禁使用** \`#### Task N.M:\` 或 \`#### T1:\` 标题格式
 - **严禁使用** ✅ emoji 标记完成，必须用 \`[x]\`
 
-每个任务按类型使用对应的固定模板，必须填满所有字段：
+每个任务按类型使用对应的固定模板，必须填满所有字段，**@layer 为强制字段**：
 
 ### 类型 A：新增文件
 
-- [ ] N.M [描述] @skill:xxx @ref:xxx
+- [ ] N.M [描述] @layer:xxx @skill:xxx @ref:xxx
   - **文件**: \`完整相对路径\`（新增）
   - **内容**:
     - 类定义: [类名、继承/实现关系]
@@ -95,7 +139,7 @@ Answer: <!-- user answer -->
   - **验证**: [具体的输入输出断言，含正常和异常场景]
 
 示例：
-- [ ] 5.1 创建 CustomerDomainService @skill:java-scf-rpc-usage-skill
+- [ ] 5.1 创建 CustomerDomainService @layer:domain @skill:java-scf-rpc-usage-skill
   @ref:techDesign/tech-spec.md#3.1-新建客户
   - **文件**: \`domain_hub_server/src/main/java/com/zz/domain/hub/domain/CustomerDomainService.java\`（新增）
   - **内容**:
@@ -108,14 +152,14 @@ Answer: <!-- user answer -->
 
 ### 类型 B：修改文件
 
-- [ ] N.M [描述] @skill:xxx @ref:xxx
+- [ ] N.M [描述] @layer:xxx @skill:xxx @ref:xxx
   - **文件**: \`完整相对路径\`（总行数）
   - **修改位置**: L行号范围 \`函数名/类名\` 之后/之内
   - **内容**: [具体改什么：新增代码逻辑/修改现有逻辑/删除代码，描述修改方式]
   - **验证**: [修改后的预期行为，含回归验证]
 
 示例：
-- [ ] 1.1 在 review 命令中增加任务完成度硬门禁 @skill:none
+- [ ] 1.1 在 review 命令中增加任务完成度硬门禁 @layer:config @skill:none
   @ref:techDesign/tech-spec.md#7.1-任务完成度检查
   - **文件**: \`src/commands/review.ts\`（138行）
   - **修改位置**: L32-38 \`runReview()\` 函数内，现有校验逻辑之后
@@ -127,6 +171,7 @@ Answer: <!-- user answer -->
 - 单个任务 AI 执行时间不超过 30 分钟
 - 超过则需拆分为多个子任务
 - **禁止模糊描述**：不允许"创建XXX类"不带文件路径、"实现YYY方法"不带方法签名和关键逻辑
+- **禁止跨层合并**：单任务不得同时修改 dao/domain/entry 等多层代码
 
 ## Coverage Checklist
 
@@ -144,23 +189,30 @@ Answer: <!-- user answer -->
 | 配置项 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
 | 前端组件 | <!-- N个 --> | <!-- T编号范围 --> | <!-- 100% --> |
 
-### Wave 1
+### Wave 1（底层：DAO / 外部 Assemble）
+
+<!-- Wave 1: Tasks with no dependencies, 层归属限定 dao/assemble/ddl/config -->
+
+- [ ] 1.1 <!-- Task description --> @layer:dao @skill:none <!-- 纯配置变更或手动操作 -->
 
-<!-- Wave 1: Tasks with no dependencies -->
+### Wave 2（中间层：Domain / Application）
 
-- [ ] 1.1 <!-- Task description --> @skill:none <!-- 纯配置变更或手动操作 -->
+<!-- Wave 2: Tasks depending on Wave 1, 层归属限定 domain/application -->
 
-### Wave 2
+- [ ] 2.1 <!-- Task description --> @depends:1.1 @layer:domain @skill:none <!-- 无需特定 skill -->
 
-<!-- Wave 2: Tasks depending on Wave 1 -->
+### Wave 3（顶层：SCF / MQ / 定时任务 / 前端）
 
-- [ ] 2.1 <!-- Task description --> @depends:1.1 @skill:none <!-- 无需特定 skill -->
+<!-- Wave 3: Tasks depending on Wave 2, 层归属限定 entry-scf/entry-mq-*/entry-job/fe -->
 
-### Wave 3
+- [ ] 3.1 <!-- Task description --> @depends:2.1 @layer:entry-scf @skill:none <!-- 无需特定 skill -->
 
-<!-- Wave 3: Tasks depending on Wave 2 -->
+#### Layered Task Splitting Self-Check（填写 tasks.md 前自检）
 
-- [ ] 3.1 <!-- Task description --> @depends:2.1 @skill:none <!-- 无需特定 skill -->
+- [ ] 每个 task 只包含一层的修改（不跨 dao/service/entry）
+- [ ] 每个 task 都带了合法的 \`@layer:xxx\`（白名单 11 种：dao/assemble/domain/application/entry-scf/entry-mq-producer/entry-mq-consumer/entry-job/fe/config/ddl）
+- [ ] Wave 编号与 \`@layer\` 一致（Wave 1 底层 / Wave 2 中间 / Wave 3 顶层）
+- [ ] 含 CREATE TABLE / MQ / 定时任务 / Redis 等关键词的 task 均已关联对应 \`@skill\`
 
 ## Dependency Analysis
 

package/dist/core/update.js

@@ -5,6 +5,7 @@ import { ZHUANSPEC_DIR_NAME } from './config.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 import { agentsTemplate } from './templates/agents-template.js';
+import { InitCommand } from './init.js';
 import { cloneArchRepoToTemp, readBusinessDirection, fetchArchitectureFile, syncBusinessSpecTemplate, syncBusinessClaudeAssets, syncCommonDotClaude, } from './business-assets-sync.js';
 export class UpdateCommand {
     async execute(projectPath) {
@@ -65,6 +66,19 @@ export class UpdateCommand {
         //    and .claude/ from the architecture repo. A single git clone is
         //    shared across all sync calls to avoid repeated network IO.
         const businessSync = await this.runBusinessAssetSync(resolvedProjectPath, zhuanspecPath);
+        // 5. v2.15.16：同步 .claude/settings.json。
+        //    早期的 update 流程仅刷 CLAUDE.md，不管 settings.json，
+        //    导致老版 settings.json 里已下线的 hook entry
+        //    （如 deviation-check --trigger post-prompt）无法被清理。
+        //    这里复用 InitCommand.syncClaudeSettings，内部会先剔除纯 ZhuanSpec 管辖
+        //    的老 group（所有 command 以 zhuanspec-hook 开头），再 append 新模板。
+        let settingsHookSummary = null;
+        try {
+            settingsHookSummary = await new InitCommand().syncClaudeSettings(resolvedProjectPath);
+        }
+        catch (error) {
+            console.error(`同步 .claude/settings.json 失败：${error instanceof Error ? error.message : String(error)}`);
+        }
         const summaryParts = [];
         const instructionFiles = ['zhuanspec/AGENTS.md'];
         if (updatedFiles.includes('AGENTS.md')) {
@@ -81,6 +95,9 @@ export class UpdateCommand {
         }
         // Business-sync summary lines
         this.appendBusinessSyncSummary(summaryParts, businessSync);
+        if (settingsHookSummary) {
+            summaryParts.push(`.claude/settings.json 已同步（新增 ${settingsHookSummary.totalAddedHooks} 条、跳过重复 ${settingsHookSummary.duplicateHooksSkipped} 条）`);
+        }
         const failedItems = [
             ...failedFiles,
             ...failedSlashTools.map((toolId) => `斜杠命令刷新（${toolId}）`),