architext 0.0.3 → 0.0.5

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,71 +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"关联文件"提取源码，读入口文件提取公共接口/导出类型，作为上游接口参考。
-        - 避免重复定义上游接口，确保对接点精确对齐。
-
-    **Output**: 向用户输出 **Task Context Brief**：
-    ```
-    ### Task Context: [功能名称] ([ID])
-
-    **目标**: [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，无则写"未设置"]
-    ```
-    内部保留完整上下文素材，进入 step_2。
+    1.  **Pre-flight**: 读取 roadmap.json，仅读 `<ID>` 条目及直接 deps 的 `id/title/status`；deps 未完成则拒绝（除非用户强制）。
+    2.  **Load**: vision.md（仅北极星+设计哲学）、02_tech_stack.md（红线 + §9 项目约定，提取 Error Handling/Data Flow/Auth 继承值）、（仅ui项目）design_tokens.json + ui_context.md（定位屏幕 ID，锁定范围供 step_4 填入，禁自行发明新 ID；不存在则跳过）、（仅data项目）data_snapshot.json。
+    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**: 产品顾问
-    **Action**: 评估功能复杂度，决定是否走完整 step_2 流程：
+<step_2_complexity>
+    **Action**: 检测任务类型，评估复杂度，决定流程路径。
 
-    **① 粒度红线检查（优先于复杂度判定）**：
+    **⓪ Task Type + 粒度红线**：
 
-    | 指标 | 上限 |
-    |:---|:---|
-    | 预估 spec.md Scenario 数 | ≤ 6 个 |
-    | 预估 plan.json Phase 数 | ≤ 4 个 |
+    | 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 | 继承原任务类型 | 继承 | 继承 | 继承 |
 
-    > 预估方法：根据 step_1 加载的 roadmap task goal 和依赖上下文，快速列举核心行为路径数量。超出上限即触发，无需精确计算。
+    > 混合型任务可在 § 2 中组合多维度，用子标题区分。预估超出上限即触发拆分。
 
-    **② 复杂度判定（粒度通过后执行）**：
+    **① 复杂度判定**：
 
     | 信号 | 判定 | 流程 |
     |:---|:---|:---|
-    | 无依赖 + 无新实体 + 无架构决策 + 预估 ≤3 tasks | **Simple** | 跳过 step_2 访谈，直接生成 spec + plan |
-    | 有依赖 或 有新实体 或 需架构决策 | **Standard** | 正常执行 step_2 Unified Proposal |
+    | 无依赖 + 无新实体 + 无架构决策 + 预估 ≤3 tasks | **Simple** | 跳过 step_3，直接生成 spec + plan（精简单 Phase，signoff 时确认） |
+    | 有依赖 或 有新实体 或 需架构决策 | **Standard** | 正常执行 step_3 Unified Proposal |
 
-    **Simple 模式**:
-    - 跳过 5 维度架构建议和 User Confirm Gate
-    - spec 精简为 1-2 个 Gherkin 场景
-    - plan 精简为单 Phase
-    - signoff 时确认（替代 step_2 的 Gate）
-</step_1_5_complexity>
+    **② Design 信号检测**（Standard 后执行）：
 
-<step_2_interview>
+    | 信号 | 判定 |
+    |:---|:---|
+    | AI- 含复杂度警告 或 涉及自定义状态机/非平凡算法/多组件协调/重试恢复 | **Standard + Design**（step_3 输出机制预览，step_5 额外生成 design.md） |
+    | 标准 CRUD / 配置 / 简单集成 | **Standard** |
+</step_2_complexity>
+
+<step_3_interview>
     **Role**: 架构师
 
     ---
@@ -113,141 +92,150 @@
 
     #### Part 2: Architecture Recommendations (架构建议)
 
-    [[SKILL: 按 `archi-plan-options` Skill 的三步选用逻辑（约定继承 → 标签路由 → 推荐 vs 展开），从五个维度的选项库中为本功能生成架构建议]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` 并遵循其三步选用逻辑执行）]]
+    [[SKILL: archi-plan-options|按 skill 的三步选用逻辑（约定继承 → 标签路由 → 推荐 vs 展开），从五个维度的选项库中为本功能生成架构建议。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-plan-options/SKILL.md` 并遵循其三步选用逻辑执行）]]
 
-    展开 Q-table 时，格式遵循 [[SKILL: `archi-interview-protocol` Skill 的标准输出格式]][[NO-SKILL: `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md`]]。
+    展开 Q-table 时，格式遵循 [[SKILL: archi-interview-protocol|skill 的标准输出格式]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则执行）]]。
 
-    #### Output Format
+    #### Part 1.5: Mechanism Preview (机制预览) 仅Complex任务:
 
-    ```
-    ## Task Proposal: [功能名称] ([ID])
+    仅当 step_2 判定为 **Standard + Design** 时输出。列出需要技术方案设计的核心机制及拟用模式（机制 / 模式 / 简述表格）。用户可增删机制或修改模式选择。
 
-    ### 功能设计
-    [按复杂度级别输出，见上方 Part 1]
-
-    ### 架构建议
-    | 维度 | 推荐 | 来源 | 理由 |
-    |:---|:---|:---|:---|
-    | 核心结构 | [推荐选项] | 功能推荐 | [结合此功能的 1-2 句理由] |
-    | 交互模式 | [推荐选项] | 功能推荐 | [理由] |
-    | 错误处理 | [项目约定值] | 项目约定 | ref: 02_tech_stack.md §9 |
-    | ... | ... | ... | ... |
-
-    [仅对需要用户裁决的维度展开选项表]:
-    **[Q<n>] 问题标题**
-    > 为什么需要用户决定（一句话）
+    #### Output Format
 
-    | ID | 选项 | 说明 | AI+ | AI- |
-    |:---|:---|:---|:---|:---|
-    | A [推荐] | ... | 具体行为（2-3句） | 完整句子 | 完整句子 |
-    | B | ... | ... | ... | ... |
-    | Z | 自定义 | (请描述) | - | - |
-
-    ---
-    > 回复 **OK** 接受全部建议；或标注要修改的部分，如：
-    > - 设计修正: "注册不需要邮箱验证步骤"
-    > - 维度覆写: "核心结构=C, 错误处理=B D"
-    > - 问题回答: "Q1=B"
-    ```
+    输出 **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`**: 提取提案中的**项目业务**新术语填入 `entities`/`verbs`；注册新共享工具到 `utilities`；注册新公共组件到 `components`。
-    3.  [?Data] **`data_snapshot.json`**: 根据架构建议中核心结构的选择新增/修改 Schema。禁写"待定"，须写出字段名和类型。
-    4.  **`error_codes.json`**: 根据架构建议中错误处理的选择注册新**业务**错误码。框架脚本错误由 exit code + stderr 处理，禁注册。
-    5.  **`map.json` featureRelations**: 判断本 Task 是否属于「聚合型 Task」——即其核心职责是**列举、汇总或动态反映**其他一类 Task（如「列出所有命令」「汇总所有页面入口」「注册所有路由」）。若是，在 `featureRelations` 中追加一条记录：
-        ```json
-        {
-          "aggregator": "<本 Task ID 或文件路径>",
-          "sources": "<一句话描述聚合来源范围，如'所有 CLI 命令类 Task'>",
-          "evidence": "<依据，如'spec.md §X 描述本 Task 会动态列出所有 Y 类 Task'>",
-          "checkNote": "此类 Task 新增或删除时，检查 <aggregator> 是否需要同步"
-        }
-        ```
-        若非聚合型 Task，跳过此步。
-
-    **Output**: 上述文件的变更 Diff (简要)。
-</step_3_global_sync>
-
-<step_4_generate>
-    **Role**: 文档工程师
-    **Input**: 确认的 Unified Proposal（功能设计 + 架构建议）+ 已更新的全局上下文。
+    2.  **数据治理同步** (`dictionary.json` / `error_codes.json` / `data_snapshot.json` 等): 按 `03_data_governance.md` 规则，将提案中涉及的新业务术语、错误码、Schema 增量同步至对应全局文件。
+    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_5_generate。
+</step_4_global_sync>
+
+<step_5_generate>
+    **Input**: 确认的 Unified Proposal（功能设计 + 架构建议）+ 已更新的全局上下文 + step_2 检测的 Task Type。
     **Action**: 在 `[[__DOCS_DIR__]]/tasks/<ID>_<Slug>/` 下生成标准文档。
 
     **1. `spec.md`** (必须):
     - 模板: `templates/spec.template.md`。
-    - 基于确认的功能设计和架构建议，转化为 Gherkin Scenarios。
-    - 每个 Scenario 须对应功能设计中的具体流程步骤或异常路径，禁凭空编造场景。
-    - 若为上游任务，须包含明确的 Interface/Type 定义。
 
-    **2. `ui.md`** [?UI]:
+    **spec § 2 按 Task Type 选择维度格式**：
+
+    | Task Type | § 2 主维度 | 格式要求 |
+    |:---|:---|:---|
+    | Feature | Behavioral | Gherkin (Given/When/Then)，每个 Scenario 对应功能设计中的具体流程步骤或异常路径 |
+    | Infrastructure | Structural | Configuration Contract，每个配置文件/服务一个 Contract（Path + Key Settings + Constraints + Verify）。Key Settings **须写出具体值**，禁泛化描述 |
+    | Quality | Quantitative | Quality Target，每个优化目标含 Metric + Baseline + Target + Verify |
+    | Edit | 继承原任务 | 同原任务类型 |
+
+    > 混合型任务在 § 2 内用子标题区分维度。
+
+    **spec § 4 Interface Exports**：INF 任务**必填**，FEAT 任务有下游 deps 时必填。
+    **spec § 5 Constraints**：**必填** — 从 vision.md + 02_tech_stack.md 提取与本任务相关的红线。
+
+    **通用规则**:
+    - 禁凭空编造 AC 条目，须对应功能设计中的具体内容。
+    - 若为上游任务，须在 § 4 包含明确的 Interface/Type 定义。
+
+    **2. `ui.md`** （本任务涉及UI时）:
     - 模板 `templates/ui.template.md`。
     - **有 `ui_context.md`（主路径）**:
-      1. **UI 偏差检查**（写 `ui.md` 前必须执行）：对比 step_2 确认的功能设计与 `ui_context.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 |
-         | 轻微增量 | 新增状态/弹窗/局部区域，不改整体布局 | 调用 `archi-ui-wireframe` Skill（Plan 细化模式）更新 `ui_concept.html` + `ui_context.md`，在 `ui.md` 注明 `MODIFIED: S-XX` |
-         | 结构性偏差 | 布局重构、新增独立屏幕、流程路径变化 | **暂停**，向用户输出偏差说明，等待 **OK** 后调用 Skill 更新 `ui_concept.html` + `ui_context.md`，再写 `ui.md` |
+         | 轻微增量 | 新增状态/弹窗/局部区域，不改整体布局 | 调用 skill 更新 `ui_concept.html` + `ui_context.md`，注明 `MODIFIED: S-XX` |
+         | 结构性偏差 | 布局重构、新增独立屏幕、流程路径变化 | **暂停**，向用户输出偏差说明，等待 **OK** 后调用 skill 更新，再写 `ui.md` |
 
       2. 完成偏差处理后，按 `ui.template.md` 填写屏幕范围声明和差异组件。
     - **无 `ui_context.md`（降级路径）**: 按完整 ITP v3.0 描述组件树，引用 `design_tokens.json` Token 定义。
 
-    **3. `plan.json`** (必须):
-    - 模板: `templates/plan.template.json`。
-    - 根据项目类型动态调整 Phase；确保每个 Task 上下文自包含。
-    - 任务描述中明确 "Additive Only" + "Respect Unknowns"。
-    - **`decisions`**: 按各维度填写；`choice` 支持多选（如 `A B`，空格分隔）、自定义（`Z: …`）；`rationale` 须填写理由，供 code 阶段参照，禁留空。
-    - **`notes`**: 每个 task 的 `notes` 须填写：`[范围] · [spec 引用] · [关键约束] · 验证: [具体操作]`；供 `/archi.code` step_4 精确定位并执行 e2e，禁留空。
-      > 示例：`实现 POST /auth/login · spec §3.1 · JWT 禁含 password · 验证: curl POST /auth/login 返回 200 + token 字段`
-    - 生成后运行 `npx archi render` 生成可读的 `.md` 视图。
-</step_4_generate>
-
-<step_5_audit>
-    **Role**: 首席审计官
-    **Checklist**:
-    1.  **Design Fidelity**: Spec 中的 Scenarios 是否完整覆盖确认的功能设计（流程步骤和异常路径）？
-    2.  **Tech Consistency**: 是否用了未声明技术？
-    3.  **Data Integrity**: Scenario 中的实体和字段是否与确认的核心实体一致？
-    4.  **Error Handling**: 是否覆盖架构建议中错误处理的选择？
-    5.  **AX Compliance**: 是否遵守 Anti-Clobbering 和 Interface Stability？
-
-    如有问题则静默修正；严重问题标记 `⚠️ Risk Warning`。
-</step_5_audit>
-
-<step_6_signoff>
-    **Terminal Gate** (禁止跳过，须在输出总结前全部完成):
+    **3. 仅Complex任务: `design.md`**:
+    - 模板: `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 上下文自包含。
+    - 每个 Phase 须包含 `rationale` 字段，记录该阶段关键设计决策的依据（用户选择/AI 推荐理由）。
+
+    **WBS 分解三原则**：
+
+    **原则 1 — 交付物导向**: 每个 task 的 `title` 描述**产出物**而非活动。
+    > Red Flag: `配置 TypeScript` ← 应为 `apps/web/tsconfig.json — strict + path aliases`
+
+    **原则 2 — 100% 覆盖**: spec § 2 每个 AC → ≥1 task 覆盖；§ 4 每个 Interface → 有 task 创建；§ 5 每个 Constraint → 有 task notes 引用。遗漏则补充。
+
+    **原则 3 — 粒度与互斥**:
+    | 信号 | 判定 |
+    |:---|:---|
+    | 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_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_6_verify>
+
+<step_7_signoff>
+    **Terminal Gate** (禁止跳过): 标准检查 (task --check + render)。
     | 步骤 | 命令 | 通过条件 |
     |:---|:---|:---|
-    | 1 | `npx archi task --check` | 无 ERROR 级问题 |
-    | 2 | `npx archi task <ID> --status active` | 任务已标记为进行中 |
-    | 3 | `npx archi render` | `.md` 视图生成完成 |
-
-    **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 已同步（dictionary/error_codes/data_snapshot）
+    □ 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

@@ -0,0 +1,48 @@
+<protocol_recover>
+**Trigger**: `/archi.recover <pack-file>`
+**Goal**: 读取 pack 文件，将其中所有用户数据（文档、任务、自定义规则）写入当前项目对应路径，完成框架升级后的数据还原。
+
+<meta>
+  <style>Precise, Efficient, Non-interactive</style>
+  <language>简体中文</language>
+  <principles>
+    1. **User Data Only**: pack 文件仅含用户数据（`global/`、`tasks/`、`scripts/`、`refs/`、自定义规则），全部写入，无需过滤。
+    2. **Overwrite Always**: 目标路径已存在时直接覆盖（框架升级场景下旧数据即为空模板，安全替换）。
+    3. **Delta Notation**: 输出须以 `ADDED` / `MODIFIED` 标注每个写入文件。
+    4. **No Partial Write**: 任一文件写入失败则立即停止并报告；已写入文件不回滚（幂等，重跑安全）。
+  </principles>
+</meta>
+
+<step_1_ingest>
+  **Role**: 情报分析官
+  **Action**:
+  1. 读取 `<pack-file>` 路径的文件内容。
+  2. 解析 XML，提取 `<files>` 下每个 `<file>` 元素的 `path` 属性与 CDATA 内容。
+
+  | 情况 | 处理 |
+  |:---|:---|
+  | 文件不存在或无法读取 | 停止 — 告知用户检查路径，提示先运行 `archi pack` 生成 |
+  | XML 格式错误 | 停止 — 提示文件可能损坏，重新运行 `archi pack` |
+  | `<files>` 为空 | 停止 — 告知 pack 为空 |
+
+  **Output**: 内部文件列表（路径 + 内容），不输出给用户。
+</step_1_ingest>
+
+<step_2_apply>
+  **Action**:
+  1. 对每个 `<file>` 条目：以 `path`（相对项目根）为写入目标，已存在 → 覆盖（`MODIFIED`），不存在 → 新建（`ADDED`）。写入 CDATA 完整内容，保留原始换行与编码。
+  2. pack 中路径可能含嵌套子目录，须确保父目录存在。
+
+  **Output**: 每个文件的 `ADDED` / `MODIFIED` 状态列表。
+</step_2_apply>
+
+<step_3_signoff>
+  **Output**: 还原摘要 — 总计写入文件数（ADDED / MODIFIED 分别统计）+ Next Steps:
+
+  | 步骤 | 说明 |
+  |:---|:---|
+  | 确认框架状态 | 运行 `/archi.help` 查看项目当前状态与建议下一步 |
+  | 清理 pack 文件 | 可删除 `<pack-file>`，已不再需要 |
+</step_3_signoff>
+
+</protocol_recover>

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

@@ -0,0 +1,163 @@
+<protocol_ref>
+**Trigger**: `/archi.ref <sub> [args]`
+**Goal**: 管理外部知识引用（第三方 API、公司内部 SDK、业务规则等），结构化存入 `refs/`，供 `plan`/`code` 按需注入上下文。
+
+**子命令**:
+| 子命令 | 格式 | 作用 |
+|:---|:---|:---|
+| `add` | `/archi.ref add [input]` | 摘要并存储外部知识（核心） |
+| `list` | `/archi.ref list` | 列出所有已存引用 |
+| `update` | `/archi.ref update <id>` | 重新摘要指定引用 |
+| `remove` | `/archi.ref remove <id>` | 删除指定引用 |
+
+<meta>
+  <style>Analytical, Precise, Context-Aware</style>
+  <language>简体中文</language>
+  <principles>
+    1. **Summarize, Not Copy**: 禁全量复制原文；须提炼为 AI 可高效使用的结构化摘要（关键接口 / 约束 / 示例），压缩比不低于 50%。
+    2. **Format-Aware**: 根据内容类型自动选择最合适的载体格式（`.md` / `.json` / `.yaml`），保留原始格式的语义优势。
+    3. **Tag-Driven**: 每个 ref 须携带 tags，供 `plan`/`code` 按需匹配注入，禁无 tag 引用。
+    4. **Index-First**: 所有操作须同步更新 `refs/index.json`，AI 通过索引按需加载，禁全量扫描。
+  </principles>
+</meta>
+
+<!-- ─── 载体格式选择规则 ─── -->
+<format_selection>
+  **Format-Aware 规则**（step_3_store 执行时参照）：
+
+  | 内容类型 | 推荐格式 | 理由 |
+  |:---|:---|:---|
+  | 网页 / URL / PDF / 纯文本 | `.md` | 结构化摘要，AI 读取效率最高 |
+  | OpenAPI / Swagger 规范 | `.yaml` | 保留机器可读结构，禁转为 .md |
+  | JSON Schema / 配置文件 | `.json` | 结构化数据原格式最优 |
+  | 混合（含大量代码示例）| `.md`（含代码块）| 代码块保留语法，加说明上下文 |
+  | 用户直接粘贴（纯 Markdown） | `.md` | 同格式存储，可精炼 |
+</format_selection>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                   ADD 子命令                   -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_add>
+
+<step_0_ingest>
+  **Role**: 情报分析官
+  **Trigger**: `/archi.ref add [input]`
+  **Action**: 解析 `[input]`，确定输入来源。
+
+  | input 形式 | 处理 |
+  |:---|:---|
+  | 本地文件路径（如 `./docs/api.yaml`） | 读取文件内容，记录 `sourceType: local-file` |
+  | URL（如 `https://...`） | 抓取页面内容，记录 `sourceType: url` |
+  | 未提供（对话模式）| 告知用户粘贴内容或提供路径/URL，等待输入，记录 `sourceType: manual` |
+
+  检查 `[[__DOCS_DIR__]]/refs/index.json` 是否存在：
+  - 存在 → 读取，获取现有 id 列表（防重复命名）
+  - 不存在 → 初始化为 `{ "refs": [] }`
+
+  **Output**: 内部（原始内容 + sourceType + 现有 id 列表），进入 `<step_1_analyze>`。
+</step_0_ingest>
+
+<step_1_analyze>
+  **Action**:
+  1. **内容类型识别**: 判断原始内容属于哪种类型（参照 `<format_selection>`），确定推荐存储格式。
+  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>
+  **Trigger**: 仅当 id / tags / 侧重点任一不确定时执行。
+  **Action**: 向用户提问，问题上限 3 题，选项优先。
+
+  **Output**: 引用信息确认 — 含内容类型与存储格式、内容摘要、Q1 引用 ID（AI 推断候选 + 自定义）、Q2 分类 Tags（多选）、（内容庞大时）Q3 关注侧重。
+
+  **Gate**: 等待用户回复后进入 `<step_3_store>`。
+</step_2_interview>
+
+<step_3_store>
+  **Action**:
+  1. 确定存储参数：`id`（用户确认或 AI 推断）、`format`（由 format_selection 决定）、`filename: {id}.{format}`、`tags`。
+
+  2. **生成引用文件内容**（按格式）:
+     - **`.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` 数组追加条目（id/title/tags/format/file/sourceType/updatedAt）。
+
+  **Output**:
+  ```
+  ADDED  [[__DOCS_DIR__]]/refs/{id}.{ext}
+  MODIFIED  [[__DOCS_DIR__]]/refs/index.json
+  ```
+</step_3_store>
+
+<step_4_signoff_add>
+  **Output**: 添加摘要，含引用 ID、存储格式及理由、Tags、文件路径、使用说明（plan 时自动读取 / code 时补充上下文 / 手动引用）。
+</step_4_signoff_add>
+
+</sub_add>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                  LIST 子命令                   -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_list>
+
+**Trigger**: `/archi.ref list`
+**Action**: 读取 `[[__DOCS_DIR__]]/refs/index.json`。
+
+| 情况 | 处理 |
+|:---|:---|
+| 索引不存在 / refs 为空 | 提示"当前无引用，运行 `/archi.ref add` 添加第一个" |
+| 正常 | 按 tags 分组展示（ID / 标题 / 格式 / 更新时间） |
+
+</sub_list>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                 UPDATE 子命令                  -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_update>
+
+**Trigger**: `/archi.ref update <id>`
+**Action**:
+1. 从 `index.json` 找到 `<id>` 对应的 `file` 和 `sourceType`。
+2. 若 `sourceType` 为 `url` → 重新抓取；`local-file` → 重新读取；`manual` → 提示粘贴新内容。
+3. 重新执行 `<step_1_analyze>` + `<step_3_store>`（保留原 id/tags/format，仅刷新内容和 `updatedAt`）。
+
+| 情况 | 处理 |
+|:---|:---|
+| id 不存在于 index.json | 停止 — 提示检查 id，可运行 `/archi.ref list` 查看 |
+
+</sub_update>
+
+<!-- ═══════════════════════════════════════════════ -->
+<!--                 REMOVE 子命令                  -->
+<!-- ═══════════════════════════════════════════════ -->
+
+<sub_remove>
+
+**Trigger**: `/archi.ref remove <id>`
+**Action**:
+1. 从 `index.json` 中找到并移除 `<id>` 条目。
+2. 删除对应的 `refs/{id}.{ext}` 文件。
+3. 更新 `index.json`。
+
+**Output**:
+```
+REMOVED  [[__DOCS_DIR__]]/refs/{id}.{ext}
+MODIFIED  [[__DOCS_DIR__]]/refs/index.json
+```
+
+| 情况 | 处理 |
+|:---|:---|
+| id 不存在 | 停止 — 提示检查 id，可运行 `/archi.ref list` 查看 |
+
+</sub_remove>
+
+</protocol_ref>