architext 0.0.4 → 0.0.6

package/dist/templates/zh/docs/prompts/plan.md

@@ -1,5 +1,5 @@
 <protocol_plan>
-  **Trigger**: `/archi.plan <ID> [context]`
+  **Trigger**: `/archi.plan <ID> [context]` | 自然语言触发时由 Workflow Dispatch 自动加载
   **Goal**: 通过深度架构访谈，定义功能的 Spec/UI/Plan。
   **Input**:
   - `<ID>` (必填): Roadmap 中已存在的任务 ID。须先通过 `/archi.scope` 或 `/archi.inherit` 创建任务。
@@ -17,103 +17,50 @@
       2.  **AI-Native Perspective**: 所有选项 Pros/Cons 从 AI Agent 视角撰写。关注：Context Locality、Type Safety、Boilerplate、Ambiguity。
       3.  **Flexible Interaction**: 选项为启发式建议，支持多选、混合或自定义。
       4.  **Audit-Gated**: 只有通过审计的文档才能交付。
+      5.  **IDE-Native First**: 利用 IDE 原生能力驱动执行节奏，本协议定义质量标准和检查点，不对抗 IDE 的规划/执行机制。
     </principles>
 </meta>
 
 <step_1_load>
-    **Role**: 系统分析师
     **Action**:
-    1.  **Read Roadmap**: 读取 `[[__DOCS_DIR__]]/global/roadmap.json`。
-        - **Pre-flight**: 仅读取 `<ID>` 对应的任务条目及其直接 deps 的 `id/title/status`；检查 deps 是否已完成，未完成则拒绝 Plan（除非用户强制）。无需加载其他任务数据。
-    2.  **Read Vision**: 读取 `[[__DOCS_DIR__]]/global/vision.md` — 仅提取北极星指标和设计哲学段落；其余章节跳过。
-    3.  **Read Tech Stack**: `02_tech_stack.md` (技术红线 + **Section 9 项目约定**)。
-        - 提取 Section 9 中的全局架构约定（Error Handling / Data Flow / Auth & Access），供 step_2 约定继承使用。
-    4.  （仅ui项目） **Read Design Tokens**: `[[__DOCS_DIR__]]/global/design_tokens.json`。
-    4.5 （仅ui项目） **Read UI Context**: `[[__DOCS_DIR__]]/global/ui_context.md`（如存在）。
-        - 从屏幕索引中定位本功能对应的屏幕 ID（如 S-03）及其负责的状态。
-        - 锁定屏幕范围，供 step_4 生成 `ui.md §1` 时直接填入，禁自行发明新屏幕 ID。
-        - 若 `ui_context.md` 不存在 → 跳过，`ui.md` 按完整 ITP 格式填写。
-    5.  （仅data项目） **Read Data Model**: `[[__DOCS_DIR__]]/global/data_snapshot.json`。
-    6.  **Read Dependency Context** (如有依赖任务):
-        - 仅读依赖任务 `spec.md` 的 Interface/Type 定义段（`## Interface` 或 `## Types` 章节）；不读 Scenarios 等其余内容。
-        - 仅当当前 spec/plan 出现 `ref: tasks/<dep_id>/spec.md#X` 引用时执行；无引用时跳过。
-        - **Stub 兼容**: 如依赖任务的 Spec-Status 为 Stub，从 stub"关联文件"提取源码，读入口文件提取公共接口/导出类型，作为上游接口参考。
-        - 避免重复定义上游接口，确保对接点精确对齐。
-    7.  **Read Refs** (如有): 读取 `[[__DOCS_DIR__]]/refs/index.json`（如存在）。
-        - 根据 tags 与当前任务描述语义匹配相关 ref 条目。
-        - 仅读取命中的 ref 文件（`[[__DOCS_DIR__]]/refs/{id}.{ext}`），忽略无关条目。
-        - 若 `refs/index.json` 不存在或 refs 为空 → 跳过。
-
-    **Output**: 向用户输出 **Task Context Brief**：
-    ```
-    ### Task Context: [功能名称] ([ID])
-
-    **任务类型**: [从 ID 前缀推断: Infrastructure / Feature / Quality / Edit]
-    **目标**: [roadmap task 的 goal，如含 [用户预设] 须高亮标注]
-    **上游依赖**: [已完成的依赖任务及其关键接口/类型，无则写"无"]
-    **项目特征**: [已激活的 UI/Data/CLI/Lib/API 标签]
-    **技术约束**: [来自 02_tech_stack.md 的关键红线]
-    **设计哲学**: [来自 vision.md 的北极星指标和设计原则]
-    **项目约定**: [来自 02_tech_stack.md §9 — Error Handling: X | Data Flow: X | Auth: X，无则写"未设置"]
-    **外部知识引用**: [命中的 ref id 列表，如 `wechat-pay`, `company-sdk`；无则写"无"]
-    ```
-    内部保留完整上下文素材，进入 step_2。
+    1.  **Pre-flight**: 读取 roadmap.json，仅读 `<ID>` 条目及直接 deps 的 `id/title/status`；deps 未完成则拒绝（除非用户强制）。
+    2.  **Load**: 读取项目上下文（vision、tech_stack、按需读取 feature 相关 JSON），详见 00_system.md 数据治理规则。
+    3.  **Dependency Context** (有依赖时): 仅读依赖任务 spec.md 的 Interface/Type 段；无引用时跳过。Stub 依赖 → 从关联文件提取源码公共接口。
+    4.  **Refs** (如有): 读 refs/index.json，按 tags 语义匹配，仅读命中 ref 文件；不存在则跳过。
+
+    **Output**: 向用户输出 **Task Context Brief** — 含任务类型（从 ID 前缀推断）、目标（goal，高亮 [用户预设]）、上游依赖及关键接口、项目特征标签、技术约束、设计哲学、项目约定（§9 各项值，无则"未设置"）、外部知识引用（命中 ref id 列表）。内部保留完整上下文，进入 step_2_complexity。
 </step_1_load>
 
-<step_1_5_complexity>
-    **Role**: 产品顾问
+<step_2_complexity>
     **Action**: 检测任务类型，评估复杂度，决定流程路径。
 
-    **⓪ Task Type 检测（最先执行）**：
-
-    从 `<ID>` 前缀推断任务类型，贯穿后续所有 step：
-
-    | ID 前缀 | Task Type | spec § 2 主维度 | spec § 4 Interface Exports |
-    |:---|:---|:---|:---|
-    | `INF-` | Infrastructure | Structural（配置契约） | **必填**（下游基础设施） |
-    | `FEAT-` | Feature | Behavioral（行为场景） | 有下游 deps 时必填 |
-    | `POLISH-` | Quality | Quantitative（量化目标） | 通常省略 |
-    | `EDIT-` | Edit | 继承原任务类型 | 继承 |
-
-    > 混合型任务（如 INF 任务含行为面）可在 § 2 中组合多个维度，用子标题区分。
+    **⓪ Task Type + 粒度红线**：
 
-    **① 粒度红线检查（按 Task Type 调整上限）**：
+    | ID 前缀 | Task Type | spec § 2 主维度 | § 4 Interface | AC 上限 | Phase 上限 |
+    |:---|:---|:---|:---|:---|:---|
+    | `INF-` | Infrastructure | Structural（配置契约） | **必填** | ≤ 8 Contracts | ≤ 5 |
+    | `FEAT-` | Feature | Behavioral（行为场景） | 有下游 deps 时必填 | ≤ 6 Scenarios | ≤ 4 |
+    | `POLISH-` | Quality | Quantitative（量化目标） | 通常省略 | ≤ 4 Targets | ≤ 3 |
+    | `EDIT-` | Edit | 继承原任务类型 | 继承 | 继承 | 继承 |
 
-    | Task Type | Acceptance Criteria 条目上限 | plan.json Phase 上限 |
-    |:---|:---|:---|
-    | Feature | ≤ 6 个 Scenarios | ≤ 4 个 |
-    | Infrastructure | ≤ 8 个 Contracts | ≤ 5 个 |
-    | Quality | ≤ 4 个 Targets | ≤ 3 个 |
-
-    > 预估方法：根据 step_1 加载的 roadmap task goal 和依赖上下文，快速列举核心路径数量。超出上限即触发，无需精确计算。
+    > 混合型任务可在 § 2 中组合多维度，用子标题区分。预估超出上限即触发拆分。
 
-    **② 复杂度判定（粒度通过后执行）**：
+    **① 复杂度判定**：
 
     | 信号 | 判定 | 流程 |
     |:---|:---|:---|
-    | 无依赖 + 无新实体 + 无架构决策 + 预估 ≤3 tasks | **Simple** | 跳过 step_2 访谈，直接生成 spec + plan |
-    | 有依赖 或 有新实体 或 需架构决策 | **Standard** | 正常执行 step_2 Unified Proposal |
-
-    **Simple 模式**:
-    - 跳过 5 维度架构建议和 User Confirm Gate
-    - spec 精简为 1-2 个 Acceptance Criteria 条目（按 Task Type 选格式）
-    - plan 精简为单 Phase
-    - signoff 时确认（替代 step_2 的 Gate）
-
-    **③ Design 信号检测（Standard 判定后执行）**：
+    | 无依赖 + 无新实体 + 无架构决策 + 预估 ≤3 tasks | **Simple** | 跳过 step_3，直接生成 spec + plan（精简单 Phase，signoff 时确认） |
+    | 有依赖 或 有新实体 或 需架构决策 | **Standard** | 正常执行 step_3 Unified Proposal |
 
-    Standard 任务中，检测是否需要生成 `design.md`（技术方案设计）：
+    **② Design 信号检测**（Standard 后执行）：
 
     | 信号 | 判定 |
     |:---|:---|
-    | 架构建议选型的 AI- 含复杂度警告（如"极难正确实现"、"状态管理复杂"、"连接泄漏"） | **Standard + Design** |
-    | 涉及自定义状态机、非平凡算法、多组件协调协议、重试/恢复策略 | **Standard + Design** |
-    | 标准 CRUD / 配置 / 简单集成 | **Standard**（无 design.md） |
+    | AI- 含复杂度警告 或 涉及自定义状态机/非平凡算法/多组件协调/重试恢复 | **Standard + Design**（step_3 输出机制预览，step_5 额外生成 design.md） |
+    | 标准 CRUD / 配置 / 简单集成 | **Standard** |
+</step_2_complexity>
 
-    > Standard + Design 时，step_2 须输出机制预览（Part 1.5），step_4 须额外生成 `design.md`。
-</step_1_5_complexity>
-
-<step_2_interview>
+<step_3_interview>
     **Role**: 架构师
 
     ---
@@ -151,88 +98,42 @@
 
     #### Part 1.5: Mechanism Preview (机制预览) 仅Complex任务:
 
-    仅当 step_1_5 判定为 **Standard + Design** 时输出。列出需要技术方案设计的核心机制及拟用模式：
-
-    ```
-    ### 机制预览 (将生成 design.md)
-    | 机制 | 模式 | 简述 |
-    |:---|:---|:---|
-    | [机制名称] | [State Machine / Pipeline / Decision Matrix / Protocol] | [一句话描述] |
-    ```
-
-    > 用户可在此增删机制或修改模式选择。
+    仅当 step_2 判定为 **Standard + Design** 时输出。列出需要技术方案设计的核心机制及拟用模式（机制 / 模式 / 简述表格）。用户可增删机制或修改模式选择。
 
     #### Output Format
 
-    ```
-    ## Task Proposal: [功能名称] ([ID])
-
-    ### 功能设计
-    [按复杂度级别输出，见上方 Part 1]
-
-    ### 架构建议
-    | 维度 | 推荐 | 来源 | 理由 |
-    |:---|:---|:---|:---|
-    | 核心结构 | [推荐选项] | 功能推荐 | [结合此功能的 1-2 句理由] |
-    | 交互模式 | [推荐选项] | 功能推荐 | [理由] |
-    | 错误处理 | [项目约定值] | 项目约定 | ref: 02_tech_stack.md §9 |
-    | ... | ... | ... | ... |
-
-    [仅 Standard + Design]:
-    ### 机制预览 (将生成 design.md)
-    | 机制 | 模式 | 简述 |
-    |:---|:---|:---|
-    | ... | ... | ... |
-
-    [仅对需要用户裁决的维度展开选项表]:
-    **[Q<n>] 问题标题**
-    > 为什么需要用户决定（一句话）
-
-    | ID | 选项 | 说明 | AI+ | AI- |
-    |:---|:---|:---|:---|:---|
-    | A [推荐] | ... | 具体行为（2-3句） | 完整句子 | 完整句子 |
-    | B | ... | ... | ... | ... |
-    | Z | 自定义 | (请描述) | - | - |
-
-    ---
-    > 回复 **OK** 接受全部建议；或标注要修改的部分，如：
-    > - 设计修正: "注册不需要邮箱验证步骤"
-    > - 维度覆写: "核心结构=C, 错误处理=B D"
-    > - 问题回答: "Q1=B"
-    > - 机制修改: "去掉 Pipeline，重连不需要那么复杂"
-    ```
+    输出 **Task Proposal** 含：功能设计（按 Part 1）、架构建议表（维度/推荐/来源/理由）、（仅 Standard+Design）机制预览表、（仅需用户裁决的维度）展开的 Q-table（ID/选项/说明/AI+/AI-，A 为推荐，Z 为自定义）。末尾附确认指引：OK 接受全部；或标注修改项（设计修正/维度覆写/问题回答/机制修改）。
 
     **Goal**: 锁定 `spec`, `ui`(如适用), `data_snapshot.json`(如适用)。
 
-    **⌨️ INPUT**: 回复 **OK** 全部接受；或自由文本标注修改项。无需按固定格式。
-</step_2_interview>
+    **⌨️ INPUT**: 回复 **OK** 全部接受（→ 进入 step_4_global_sync）；或自由文本标注修改项（→ 进入 step_3_5_refinement）。无需按固定格式。
+</step_3_interview>
 
-<step_2_5_refinement>
-    **Role**: 咨询顾问
+<step_3_5_refinement>
     **Trigger**: 用户回复非 OK，含修正、疑问、覆写或明显逻辑冲突。
     **Action**: 不生成文档。融入用户反馈，刷新 Unified Proposal 重新输出，等待再次确认。
     - 如是功能设计疑问 → 给出替代方案对比，重新提出设计
     - 如是架构维度疑问 → 结合此功能具体场景解释差异，更新推荐
     - 如是维度覆写 → 直接替换推荐并调整相关设计
-</step_2_5_refinement>
 
-<step_3_global_sync>
-    **Role**: 系统管理员
+    用户回复 OK → 进入 step_4_global_sync。
+</step_3_5_refinement>
+
+<step_4_global_sync>
     **Constraint**: 在生成 Task 文档**之前**，须先更新以下全局文件。
 
     **Boundary**: 仅注册**项目业务域**内容。Architext 框架概念（scripts、scaffold、roadmap、plan 等）和框架基础设施错误禁注册到全局文件。
 
     **Action Checklist**:
     1.  **`map.json`**: 在 `directoryMapping` 注册 `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>`；在 `logicalTopology` 定义模块职责与依赖。
-    2.  **数据治理同步** (`dictionary.json` / `error_codes.json` / `data_snapshot.json` 等): 按 `03_data_governance.md` 规则，将提案中涉及的新业务术语、错误码、Schema 增量同步至对应全局文件。
+    2.  **数据治理同步**: [[SUBAGENT: archi-data-sync|context: 扫描 Task 提案中引入的新业务实体/错误码/Schema/端点/命令/导出，按 00_system.md 规则增量同步]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-data-sync/SKILL.md`，按其执行协议操作）]]
     3.  **`map.json` featureRelations**: [[SUBAGENT: archi-feature-relations|mode: register, context: 判断本 Task 是否为聚合型，若是则注册 featureRelations 条目]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`，按 mode: register 的逻辑执行）]]
 
-    **Output**: 上述文件的变更 Diff (简要)。
-</step_3_global_sync>
+    **Output**: 上述文件的变更 Diff (简要)。进入 step_5_generate。
+</step_4_global_sync>
 
-<step_4_generate>
-    **Role**: 文档工程师
-    **Input**: 确认的 Unified Proposal（功能设计 + 架构建议）+ 已更新的全局上下文 + step_1_5 检测的 Task Type。
+<step_5_generate>
+    **Input**: 确认的 Unified Proposal（功能设计 + 架构建议）+ 已更新的全局上下文 + step_2 检测的 Task Type。
     **Action**: 在 `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>/` 下生成标准文档。
 
     **1. `spec.md`** (必须):
@@ -243,104 +144,104 @@
     | Task Type | § 2 主维度 | 格式要求 |
     |:---|:---|:---|
     | Feature | Behavioral | Gherkin (Given/When/Then)，每个 Scenario 对应功能设计中的具体流程步骤或异常路径 |
-    | Infrastructure | Structural | Configuration Contract，每个配置文件/服务一个 Contract（Path + Key Settings + Constraints + Verify）。Key Settings **须写出具体值**，禁泛化描述（如"配置 X"） |
+    | Infrastructure | Structural | Configuration Contract，每个配置文件/服务一个 Contract（Path + Key Settings + Constraints + Verify）。Key Settings **须写出具体值**，禁泛化描述 |
     | Quality | Quantitative | Quality Target，每个优化目标含 Metric + Baseline + Target + Verify |
     | Edit | 继承原任务 | 同原任务类型 |
 
-    > 混合型任务在 § 2 内用子标题区分维度（如 INF 任务含 Behavioral 子节描述热键行为）。
+    > 混合型任务在 § 2 内用子标题区分维度。
 
-    **spec § 4 Interface Exports**：INF 任务**必填**（下游基础设施须声明导出约定），FEAT 任务有下游 deps 时必填。
-    **spec § 5 Constraints**：**必填** — 从 vision.md + 02_tech_stack.md 提取与本任务相关的红线。
+    **spec § 4 Interface Exports**：INF 任务**必填**，FEAT 任务有下游 deps 时必填。
+    **spec § 5 Constraints**：**必填** — 从 vision.md + tech_stack.md 提取与本任务相关的红线。
 
     **通用规则**:
-    - 禁凭空编造 Acceptance Criteria 条目，须对应功能设计中的具体内容。
+    - 禁凭空编造 AC 条目，须对应功能设计中的具体内容。
     - 若为上游任务，须在 § 4 包含明确的 Interface/Type 定义。
 
     **2. `ui.md`** （本任务涉及UI时）:
     - 模板 `templates/ui.template.md`。
     - **有 `ui_context.md`（主路径）**:
-      1. **UI 偏差检查**（写 `ui.md` 前必须执行）：对比 step_2 确认的功能设计与 `ui_context.md` 中的屏幕索引，识别偏差。[[SKILL: archi-ui-wireframe|按 skill 的协议处理 UI 偏差]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]。判定标准与处理方式：
+      1. **UI 偏差检查**（写 `ui.md` 前必须执行）：对比功能设计与屏幕索引，识别偏差。[[SKILL: archi-ui-wireframe|按 skill 的协议处理 UI 偏差]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]。
 
          | 偏差类型 | 判定标准 | 处理方式 |
          |:---|:---|:---|
          | 无偏差 | 屏幕索引与设计一致 | 直接写 `ui.md`，引用屏幕 ID |
-         | 轻微增量 | 新增状态/弹窗/局部区域，不改整体布局 | 调用 skill（Plan 细化模式）更新 `ui_concept.html` + `ui_context.md`，在 `ui.md` 注明 `MODIFIED: S-XX` |
-         | 结构性偏差 | 布局重构、新增独立屏幕、流程路径变化 | **暂停**，向用户输出偏差说明，等待 **OK** 后调用 skill 更新 `ui_concept.html` + `ui_context.md`，再写 `ui.md` |
+         | 轻微增量 | 新增状态/弹窗/局部区域，不改整体布局 | 调用 skill 更新 `screens/S-XX.html` + `ui_context.md`，注明 `MODIFIED: screens/S-XX.html` |
+         | 结构性偏差 | 布局重构、新增独立屏幕、流程路径变化 | **暂停**，向用户输出偏差说明，等待 **OK** 后调用 skill 更新，再写 `ui.md` |
 
       2. 完成偏差处理后，按 `ui.template.md` 填写屏幕范围声明和差异组件。
     - **无 `ui_context.md`（降级路径）**: 按完整 ITP v3.0 描述组件树，引用 `design_tokens.json` Token 定义。
 
     **3. 仅Complex任务: `design.md`**:
-    - 模板: `templates/design.template.md`。
-    - 仅在 step_1_5 判定为 **Standard + Design** 时生成。
-    - § 2 Core Mechanisms: 按 step_2 确认的机制预览，调用 [[SKILL: archi-design-patterns|skill 的模式选择指南和标准格式生成机制描述并执行自检]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-design-patterns/SKILL.md` 并遵循其模式格式和自检清单执行）]]。
-    - § 3 Parameters: 所有机制中的数值须具体化，禁模糊描述。
-    - § 4 Invariants: 每条须可测试，须对应 plan.json 的 test 条目。
-    - § 5 Failure Modes: 每个故障须有检测方式 + 降级行为。
-    - § 6 Trace Verification: 从 spec § 2 每条 AC 追踪设计路径，有 Gap 须回补。
+    - 模板: `templates/design.template.md`。仅在 **Standard + Design** 时生成。
+    - § 2 Core Mechanisms: 按确认的机制预览，调用 [[SKILL: archi-design-patterns|skill 的模式选择指南和标准格式生成机制描述并执行自检]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-design-patterns/SKILL.md` 并遵循其模式格式和自检清单执行）]]。
+    - § 3 Parameters: 数值须具体化，禁模糊。§ 4 Invariants: 须可测试，对应 plan.json test 条目。§ 5 Failure Modes: 须有检测+降级。§ 6 Trace Verification: 从 spec § 2 每条 AC 追踪设计路径，有 Gap 须回补。
 
     **4. `plan.json`** (必须):
-    - 模板: `templates/plan.template.json`。
-    - 根据项目类型动态调整 Phase；确保每个 Task 上下文自包含。
-    - 任务描述中明确 "Additive Only" + "Respect Unknowns"。
+    - 模板: `templates/plan.template.json`。根据项目类型动态调整 Phase；每个 Task 上下文自包含。
+    - 每个 Phase 须包含 `rationale` 字段，记录该阶段关键设计决策的依据（用户选择/AI 推荐理由）。
 
-    **WBS 分解三原则（生成 plan.json 时须遵循）**：
+    **WBS 分解三原则**：
 
     **原则 1 — 交付物导向**: 每个 task 的 `title` 描述**产出物**而非活动。
-    > ✅ 好: `apps/web/tsconfig.json — strict + path aliases`
-    > ❌ 差: `配置 TypeScript`
+    > Red Flag: `配置 TypeScript` ← 应为 `apps/web/tsconfig.json — strict + path aliases`
 
-    **原则 2 — 100% 覆盖**: 生成后须逐项确认覆盖度：
-    | 检查项 | 规则 |
-    |:---|:---|
-    | spec § 2 每个 Acceptance Criteria 条目 | 须有 ≥1 个 task 覆盖 |
-    | spec § 4 每个 Interface Export | 须有 task 负责创建/暴露该接口 |
-    | spec § 5 每个 Constraint | 须有 task 的 notes 中引用该约束 |
-    遗漏则补充 task 直到 100%。
+    **原则 2 — 100% 覆盖**: spec § 2 每个 AC → ≥1 task 覆盖；§ 4 每个 Interface → 有 task 创建；§ 5 每个 Constraint → 有 task notes 引用。遗漏则补充。
 
     **原则 3 — 粒度与互斥**:
     | 信号 | 判定 |
     |:---|:---|
-    | task 涉及 ≥3 个不相关文件 | 太粗 — 须拆分 |
-    | task 的 title 无法对应到具体产出文件 | 太抽象 — 须具体化 |
-    | 两个 task 修改同一文件同一区域 | 违反互斥 — 合并或重划边界 |
-    | task 的 notes 只有一句话且无验证项 | 信息量不足 — 须补充 |
-
-    **`decisions` 质量标准**:
-    - `rationale` **须含实施指导**，不仅说明"为什么选"，须说明"选了怎么配"。
-    > ✅ 好: `pnpm workspace 管理 apps/ + packages/；Turborepo pipeline: build→lint→type-check 三级缓存；root scripts 统一入口`
-    > ❌ 差: `Brief 明确要求` ← 零实施指导
-
-    **`notes` 质量标准**:
-    - 格式: `[产出文件路径或操作对象] · [spec 引用] · [关键约束] · 验证: [可执行命令 + 期望结果]`
-    - 供 `/archi.code` step_4 精确定位并执行 e2e，禁留空。
-    > ✅ 好: `创建 apps/web/next.config.ts · spec §2.2 · transpilePackages: ['@repo/ui'], output: 'standalone' · 禁 CSS-in-JS · 验证: pnpm --filter web build 成功 (exit 0)`
-    > ❌ 差: `配置 Next.js · spec §2.2` ← 无具体内容、无约束、无验证
-    > ❌ 差: `创建文件 · spec §2.1 · 验证: 检查文件存在` ← "检查文件存在" 不可执行
-    > **Red Flag**: notes 退化为 title 同义重复。每个 notes 须包含 title 中**不存在**的信息量。
-
-    - 生成后运行 `npx archi render` 生成可读的 `.md` 视图。
-</step_4_generate>
-
-<step_5_verify>
+    | task 涉及 ≥3 个不相关文件 | 太粗 — 拆分 |
+    | title 无法对应具体产出文件 | 太抽象 — 具体化 |
+    | 两个 task 修改同一文件同一区域 | 违反互斥 — 合并或重划 |
+    | notes 只有一句话且无验证项 | 信息量不足 — 补充 |
+
+    **`decisions` 质量**: `rationale` 须含实施指导，不仅说明"为什么选"，须说明"选了怎么配"。
+    > Red Flag: `Brief 明确要求` ← 零实施指导
+
+    **`notes` 质量**: 格式 `[产出文件路径] · [spec 引用] · [关键约束] · 验证: [可执行命令 + 期望结果]`。禁留空。
+    > Red Flag: notes 退化为 title 同义重复。每个 notes 须包含 title 中**不存在**的信息量。
+
+    - 生成后运行 `npx archi render` 生成可读的 `.md` 视图。进入 step_6_verify。
+</step_5_generate>
+
+<step_6_verify>
     **Role**: 独立审查官
-    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: 审查 step_4 生成的文档（spec.md, ui.md, plan.json, design.md）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: plan-docs 的审查维度表逐项检查）]]
+    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: 审查 step_5 生成的文档（spec.md, ui.md, plan.json, design.md）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: plan-docs 的审查维度表逐项检查）]]
 
     [[INCLUDE: shared/verify-result-handling.md]]
-</step_5_verify>
+</step_6_verify>
 
-<step_6_signoff>
-    **Terminal Gate** (禁止跳过，须在输出总结前全部完成):
+<step_7_signoff>
+    **Terminal Gate** (禁止跳过): 标准检查 (task --check + render)。
     | 步骤 | 命令 | 通过条件 |
     |:---|:---|:---|
-    | 1 | `npx archi task --check` | 无 ERROR 级问题 |
-    | 2 | `npx archi render` | `.md` 视图生成完成 |
-    | 3 | `npx archi task <ID> --status active` | 任务已标记为进行中 |
-
-    **Action** (Gate 通过后):
+    | 1 | `npx archi task <ID> --status active` | 任务已标记为进行中 |
+
+    **Pre-signoff Checklist** (Gate 通过后、输出前须逐项确认):
+    □ spec.md § 2 — AC/场景/契约对应功能设计中的具体内容（无凭空捏造）
+    □ spec.md § 4 Interface — 已填写（INF 任务 / 有下游 deps 时必填）
+    □ spec.md § 5 Constraints — 已从 vision + tech_stack 提取（非空）
+    □ plan.json — spec § 2 每条 AC → ≥1 task 覆盖（100% 覆盖原则）
+    □ plan.json — 每个 task notes 含验证字段（非空，非 title 同义重复）
+    □ map.json — tasks/<ID>_<Slug> 已在 directoryMapping 注册
+    □ 全局文件 — 新术语/错误码/Schema/Token/环境变量 已同步
+      - dictionary.json + error_codes.json + env_registry.json — 必填
+      - （仅ui项目）design_tokens.json + ui_context.md
+      - （仅data项目）data_snapshot.json
+      - （仅api项目）api_snapshot.json
+      - （仅cli项目）command_api.json
+      - （仅lib项目）public_api.json
+    □ Step 6 Silent Audit — 已执行，所有 CRITICAL 问题已修复
+
+    **Action** (Checklist 全部确认后):
     1.  输出总结。
 
-    **Output**: Task 定义摘要，含架构建议确认表（各维度最终选择及理由）和 Next Steps 表格。
-</step_6_signoff>
+    **Output**: Task 定义摘要，含架构建议确认表（各维度最终选择及理由）和 Next Steps：
+
+    | 优先级 | 动作 | 说明 |
+    |:---|:---|:---|
+    | 1 | `/archi.code <ID>` | Spec 和 Plan 已就绪，开始实现（须用户确认） |
+    | 可选 | 审查 spec.md / plan.json | 在动手前再检查一遍文档 |
+</step_7_signoff>
 
 </protocol_plan>

package/dist/templates/zh/docs/prompts/recover.md

@@ -6,10 +6,10 @@
   <style>Precise, Efficient, Non-interactive</style>
   <language>简体中文</language>
   <principles>
-    1. **User Data Only**: pack 文件仅含用户数据（`global/`、`tasks/`、`scripts/`、`refs/`、自定义规则），无框架文件，全部写入，无需过滤。
-    2. **Overwrite Always**: 目标路径已存在文件时直接覆盖，无需询问（框架升级场景下旧数据即为空模板，可安全替换）。
+    1. **User Data Only**: pack 文件仅含用户数据（`global/`、`tasks/`、`scripts/`、`refs/`、自定义规则），全部写入，无需过滤。
+    2. **Overwrite Always**: 目标路径已存在时直接覆盖（框架升级场景下旧数据即为空模板，安全替换）。
     3. **Delta Notation**: 输出须以 `ADDED` / `MODIFIED` 标注每个写入文件。
-    4. **No Partial Write**: 若任一文件写入失败，立即停止并报告；已写入文件不回滚（幂等，重跑安全）。
+    4. **No Partial Write**: 任一文件写入失败则立即停止并报告；已写入文件不回滚（幂等，重跑安全）。
   </principles>
 </meta>
 
@@ -25,34 +25,19 @@
   | XML 格式错误 | 停止 — 提示文件可能损坏，重新运行 `archi pack` |
   | `<files>` 为空 | 停止 — 告知 pack 为空 |
 
-  **Output**: 内部文件列表（路径 + 内容），不直接输出给用户。
+  **Output**: 内部文件列表（路径 + 内容），不输出给用户。
 </step_1_ingest>
 
 <step_2_apply>
-  **Role**: 资深工程师
   **Action**:
-  1. 对每个 `<file>` 条目：
-     - 以 `path` 属性（相对项目根目录）为写入目标。
-     - 若目标文件已存在 → 覆盖（标记 `MODIFIED`）。
-     - 若目标文件不存在 → 新建（标记 `ADDED`）。
-     - 写入 CDATA 中的完整内容，保留原始换行与编码。
-  2. 注意：pack 中的路径可能含嵌套子目录（如 `tasks/FEAT-001_auth/spec.md`），须确保父目录存在。
-
-  **Output**:
-  ```
-  ADDED     .architext/global/vision.md
-  ADDED     .architext/global/roadmap.json
-  ADDED     .architext/tasks/FEAT-001_auth/spec.md
-  MODIFIED  .cursor/rules/90_custom_rules.mdc
-  ...
-  ```
+  1. 对每个 `<file>` 条目：以 `path`（相对项目根）为写入目标，已存在 → 覆盖（`MODIFIED`），不存在 → 新建（`ADDED`）。写入 CDATA 完整内容，保留原始换行与编码。
+  2. pack 中路径可能含嵌套子目录，须确保父目录存在。
+
+  **Output**: 每个文件的 `ADDED` / `MODIFIED` 状态列表。
 </step_2_apply>
 
 <step_3_signoff>
-  **Action**:
-  1. 输出还原摘要：
-     - 总计写入文件数（ADDED + MODIFIED 分别统计）
-  2. Next Steps：
+  **Output**: 还原摘要 — 总计写入文件数（ADDED / MODIFIED 分别统计）+ Next Steps:
 
   | 步骤 | 说明 |
   |:---|:---|

package/dist/templates/zh/docs/prompts/ref.md

@@ -59,105 +59,35 @@
 </step_0_ingest>
 
 <step_1_analyze>
-  **Role**: 系统分析师
   **Action**:
   1. **内容类型识别**: 判断原始内容属于哪种类型（参照 `<format_selection>`），确定推荐存储格式。
-  2. **关键信息提取**: 从内容中提取：
-     - 核心接口/端点/函数签名
-     - 参数列表与类型（入参/出参）
-     - 重要约束、限制、注意事项
-     - 认证/鉴权方式（如有）
-     - 典型使用示例（不超过 3 个）
-  3. **信息缺口识别**:
-     - id 命名（推断一个候选值，如 `wechat-pay`，待用户确认）
-     - tags 分类（从以下标准 tag 推断：`api` / `sdk` / `internal` / `payment` / `auth` / `map` / `notification` / `storage` / 自定义）
-     - 关注侧重点（若内容庞大，须确认用户最关心哪些接口/功能）
+  2. **关键信息提取**: 核心接口/端点/签名、参数与类型、重要约束/限制、认证方式（如有）、典型示例（≤3 个）。
+  3. **信息缺口识别**: id 命名（推断候选值）、tags 分类（从标准 tag 推断：`api`/`sdk`/`internal`/`payment`/`auth`/`map`/`notification`/`storage`/自定义）、关注侧重点（内容庞大时确认用户最关心的接口）。
 
   **Output**: 内部分析摘要，进入 `<step_2_interview>`（有缺口时）或直接 `<step_3_store>`（信息完整时）。
 </step_1_analyze>
 
 <step_2_interview>
-  **Role**: 产品顾问
   **Trigger**: 仅当 id / tags / 侧重点任一不确定时执行。
   **Action**: 向用户提问，问题上限 3 题，选项优先。
 
-  **Output 格式**:
-  ```
-  ### 引用信息确认
-
-  **内容类型**: [识别结果] → 将存储为 [.md / .yaml / .json]
-  **内容摘要**: [一句话描述原始内容]
-
-  **Q1 — 引用 ID**（用于文件命名和引用）:
-  [A] [AI 推断的候选值]（推荐）
-  [B] 自定义
-
-  **Q2 — 分类 Tags**（多选）:
-  [A] api  [B] sdk  [C] internal  [D] payment  [E] auth  [F] 其他: ___
-
-  （内容庞大时）**Q3 — 关注侧重**:
-  [A] 完整保留  [B] 仅保留 [具体接口列表]  [C] 自定义
-
-  **INPUT**: Q1答案 | Q2答案 | Q3答案（如有）
-  ```
+  **Output**: 引用信息确认 — 含内容类型与存储格式、内容摘要、Q1 引用 ID（AI 推断候选 + 自定义）、Q2 分类 Tags（多选）、（内容庞大时）Q3 关注侧重。
 
   **Gate**: 等待用户回复后进入 `<step_3_store>`。
 </step_2_interview>
 
 <step_3_store>
-  **Role**: 资深工程师
   **Action**:
-  1. 确定存储参数：
-     - `id`: 用户确认的值（或 AI 推断值）
-     - `format`: 由 `<format_selection>` 规则确定的文件扩展名
-     - `filename`: `{id}.{format}`
-     - `tags`: 用户确认的 tags 列表
+  1. 确定存储参数：`id`（用户确认或 AI 推断）、`format`（由 format_selection 决定）、`filename: {id}.{format}`、`tags`。
 
   2. **生成引用文件内容**（按格式）:
-
-     **`.md` 格式骨架**:
-     ```markdown
-     ---
-     id: {id}
-     title: {标题}
-     tags: [{tags}]
-     sourceType: url | local-file | manual
-     source: {来源路径或 URL，manual 时填 "manual-input"}
-     created: {YYYY-MM-DD}
-     updated: {YYYY-MM-DD}
-     ---
-
-     ## 核心信息
-     <!-- 基础 URL、版本、认证方式等 -->
-
-     ## 关键接口
-     | 接口/函数 | 路径/签名 | 说明 |
-     |:---|:---|:---|
-
-     ## 重要约束与注意事项
-
-     ## 示例
-     <!-- 不超过 3 个最具代表性的示例 -->
-     ```
-
-     **`.yaml` 格式**: 直接存储原始 OpenAPI/Swagger 内容（精简掉示例响应中冗余的 example 字段，保留 schema 结构）。
-
-     **`.json` 格式**: 直接存储原始 JSON Schema 或配置内容（移除注释、保留结构）。
+     - **`.md`**: frontmatter（id/title/tags/sourceType/source/created/updated）+ 4 个 section（核心信息、关键接口表、重要约束、示例≤3个）
+     - **`.yaml`**: 直接存储精简后的 OpenAPI/Swagger（移除冗余 example 字段，保留 schema）
+     - **`.json`**: 直接存储原始结构（移除注释，保留结构）
 
   3. **写入文件**: `[[__DOCS_DIR__]]/refs/{id}.{ext}`
 
-  4. **更新索引**: 向 `[[__DOCS_DIR__]]/refs/index.json` 的 `refs` 数组追加：
-     ```json
-     {
-       "id": "{id}",
-       "title": "{标题}",
-       "tags": ["{tags}"],
-       "format": "{ext}",
-       "file": "{id}.{ext}",
-       "sourceType": "url | local-file | manual",
-       "updatedAt": "{YYYY-MM-DD}"
-     }
-     ```
+  4. **更新索引**: 向 `[[__DOCS_DIR__]]/refs/index.json` 的 `refs` 数组追加条目（id/title/tags/format/file/sourceType/updatedAt）。
 
   **Output**:
   ```
@@ -167,18 +97,7 @@
 </step_3_store>
 
 <step_4_signoff_add>
-  **Output**: 添加摘要，含：
-  - **引用 ID**: `{id}`
-  - **存储格式**: `{ext}` — 理由（一句话）
-  - **Tags**: `[tags]`
-  - **文件路径**: `[[__DOCS_DIR__]]/refs/{id}.{ext}`
-  - **如何使用**:
-
-  | 场景 | 说明 |
-  |:---|:---|
-  | `/archi.plan <ID>` | 规划时若任务涉及 `[tags]` 相关功能，AI 将自动读取此 ref |
-  | `/archi.code <ID>` | 编码时作为补充上下文注入，提供接口签名和约束细节 |
-  | 手动引用 | 在对话中直接提到 "参考 `refs/{id}`" 即可 |
+  **Output**: 添加摘要，含引用 ID、存储格式及理由、Tags、文件路径、使用说明（plan 时自动读取 / code 时补充上下文 / 手动引用）。
 </step_4_signoff_add>
 
 </sub_add>
@@ -189,25 +108,13 @@
 
 <sub_list>
 
-**Role**: 系统分析师
 **Trigger**: `/archi.ref list`
 **Action**: 读取 `[[__DOCS_DIR__]]/refs/index.json`。
 
 | 情况 | 处理 |
 |:---|:---|
 | 索引不存在 / refs 为空 | 提示"当前无引用，运行 `/archi.ref add` 添加第一个" |
-| 正常 | 按 tags 分组展示 |
-
-**Output**:
-```
-### 外部知识引用库 (共 N 条)
-
-#### [tag 分组名]
-| ID | 标题 | 格式 | 更新时间 |
-|:---|:---|:---|:---|
-| wechat-pay | 微信支付 V3 API | .md | 2025-01-15 |
-| openapi-spec | 内部服务 OpenAPI | .yaml | 2025-01-10 |
-```
+| 正常 | 按 tags 分组展示（ID / 标题 / 格式 / 更新时间） |
 
 </sub_list>
 
@@ -217,11 +124,10 @@
 
 <sub_update>
 
-**Role**: 资深工程师
 **Trigger**: `/archi.ref update <id>`
 **Action**:
 1. 从 `index.json` 找到 `<id>` 对应的 `file` 和 `sourceType`。
-2. 若 `sourceType` 为 `url` → 重新抓取原始 URL；`local-file` → 重新读取文件；`manual` → 提示用户粘贴新内容。
+2. 若 `sourceType` 为 `url` → 重新抓取；`local-file` → 重新读取；`manual` → 提示粘贴新内容。
 3. 重新执行 `<step_1_analyze>` + `<step_3_store>`（保留原 id/tags/format，仅刷新内容和 `updatedAt`）。
 
 | 情况 | 处理 |
@@ -236,7 +142,6 @@
 
 <sub_remove>
 
-**Role**: 系统管理员
 **Trigger**: `/archi.ref remove <id>`
 **Action**:
 1. 从 `index.json` 中找到并移除 `<id>` 条目。