architext 0.0.3 → 0.0.4

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

@@ -27,8 +27,8 @@
         - `[[__DOCS_DIR__]]/global/dictionary.json`
         - `[[__DOCS_DIR__]]/global/error_codes.json`
         - `02_tech_stack.md`
-        - [?UI] `[[__DOCS_DIR__]]/global/design_tokens.json`
-        - [?Data] `[[__DOCS_DIR__]]/global/data_snapshot.json`
+        - （仅ui项目） `[[__DOCS_DIR__]]/global/design_tokens.json`
+        - （仅data项目） `[[__DOCS_DIR__]]/global/data_snapshot.json`
     2.  **Scan Task Index**: 扫描 `[[__DOCS_DIR__]]/tasks/` 目录，建立 Task 索引（ID、名称、状态）。
     3.  **Intent Analysis**: 根据用户 `[context]`，初步定位受影响的全局资产类别。
 
@@ -104,7 +104,7 @@
     **Phase 1 — 修改全局资产**:
     按用户确认的清单修改全局文件。每个文件修改后输出变更摘要。
 
-    **[?UI] Phase 1.5 — 设计系统变更检查**:
+    **（仅ui项目） Phase 1.5 — 设计系统变更检查**:
     若 `design_tokens.json` 有以下变更，须在 Phase 2 完成后执行对应操作：
 
     | 变更范围 | 影响 | 处理方式 |
@@ -120,12 +120,20 @@
     **Phase 2 — 级联更新 Task 文档**:
     对每个受影响的 Task，按 `/archi.edit` 标准执行:
     1.  更新 `spec.md`（逻辑/规则因全局变更而需调整的部分）。
-    2.  [?UI] 更新 `ui.md`（范围/交互因全局变更而需调整的部分）；如屏幕结构受影响，运行 `archi-ui-wireframe` Skill（局部更新模式）同步更新 `ui_concept.html` + `ui_context.md`。
+    2.  （仅ui项目） 更新 `ui.md`（范围/交互因全局变更而需调整的部分）；如屏幕结构受影响，[[SKILL: archi-ui-wireframe|运行 skill（局部更新模式）同步更新 `ui_concept.html` + `ui_context.md`]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]。
     3.  在 `plan.json` 的 `phases` 中追加新 Phase: `Phase X: Global Revision — [变更主题] (<Date>)`，列出落地任务。
 
     **Output**: 每个文件的变更摘要（全局 + Task）。
 </step_4_execute>
 
+<step_4_5_verify>
+    **Role**: 独立审查官
+
+    [[SUBAGENT: archi-silent-audit|mode: plan-docs, context: 审查 step_4 Phase 2 级联更新的 Task 文档（spec.md、ui.md、plan.json 新 Phase），确保与修改后的全局资产一致，Plan tasks 可验证]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: plan-docs 的审查维度表逐项检查）]]
+
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_4_5_verify>
+
 <step_5_summary>
     **Role**: 审计官
     **Checklist**:

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

@@ -58,7 +58,7 @@
     2. **任务清单完整性**: Brief 任务清单是否足以支撑需求目标？
     3. **影响评估**: Brief 中"受影响的已有任务" → 对照 roadmap/tasks 验证是否存在、状态如何。
     4. **缺口识别**: 检查 Brief 是否有关键信息缺失。
-    5. **联动检查**: 读取 `map.json.featureRelations`，将新任务的描述与各条 `sources` 字段做语义对比，判断新任务是否属于某聚合方的覆盖范围。命中时在摘要中输出联动提示。
+    5. **联动检查**: [[SUBAGENT: archi-feature-relations|mode: check, context: 将新任务描述与 featureRelations sources 做语义对比，命中时在摘要中输出联动提示]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-feature-relations/SKILL.md`，按 mode: check 的逻辑执行）]]
 
     **缺口分级**:
     - **必须**: 缺失则无法合理分解（如任务清单为空）
@@ -84,7 +84,7 @@
     |:---|:---|:---|
     | [ID: 名称] | [done/active/stub] | [需修改/需扩展/无影响] |
 
-    **[?有命中] 联动提示**:
+    **（有命中） 联动提示**:
     | 聚合方 | checkNote |
     |:---|:---|
     | [aggregator ID/路径] | [checkNote 内容] |
@@ -102,14 +102,14 @@
     **Trigger**: 仅当 Step 2 发现"必须"或"可补"级缺口时执行。
     **Input**: Step 2 的缺口列表。问题数上限 3 题。
 
-    [[SKILL: 按 `archi-interview-protocol` Skill 的核心规则和标准输出格式提问。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则）]]
+    [[SKILL: archi-interview-protocol|按 skill 的核心规则和标准输出格式提问。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则）]]
 </step_2_5_supplementary>
 
 <step_3_decompose>
     **Role**: 首席架构师
     **Input**: Brief 全文 + 项目上下文 + 补充回答（如有）。
 
-    **Action**: [[SKILL: 按 `archi-decompose-roadmap` Skill 的协议，基于 Scope Brief 任务清单生成增量任务数据]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 并遵循其协议执行）]]
+    **Action**: [[SKILL: archi-decompose-roadmap|按 skill 的协议，基于 Scope Brief 任务清单生成增量任务数据。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 并遵循其协议执行）]]
 
     **展示格式**（将 Skill 产出的任务数据转换为以下格式，向用户呈现后等待确认）：
 
@@ -147,7 +147,7 @@
     1.  将新任务追加到 `[[__DOCS_DIR__]]/global/roadmap.json` 对应 Phase 的 `tasks` 数组中。
     2.  如需新增 Phase → 追加到 `phases` 数组。
     3.  更新 `lastUpdated` 字段。
-    4.  [?新模块] 更新 `[[__DOCS_DIR__]]/global/map.json` 的 `directoryMapping`：为新增任务预注册推断的模块路径（基于 tech_stack 架构模式和任务描述推断，仅目录级别；详细内容在 `/archi.plan` 时完善）。
+    4.  （新模块） 更新 `[[__DOCS_DIR__]]/global/map.json` 的 `directoryMapping`：为新增任务预注册推断的模块路径（基于 tech_stack 架构模式和任务描述推断，仅目录级别；详细内容在 `/archi.plan` 时完善）。
 
     **Terminal Gate** (禁止跳过，须在输出总结前全部完成):
     | 步骤 | 命令 | 通过条件 |
@@ -171,7 +171,7 @@
 
     | 优先级 | 动作 | 说明 |
     |:---|:---|:---|
-    | [?UI] 推荐 | 运行 `archi-ui-wireframe` Skill（追加模式） | 为新增任务追加屏幕到 `ui_concept.html`，同步更新 `ui_context.md` |
+    | （仅ui项目） 推荐 | [[SKILL: archi-ui-wireframe|运行 skill（追加模式）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]] | 为新增任务追加屏幕到 `ui_concept.html`，同步更新 `ui_context.md` |
     | 1 | `/archi.plan <第一个 pending 任务 ID>` | 对首个可执行任务做深度规划 |
     | 2 | 审查 roadmap | 确认依赖关系和优先级 |
 </step_5_signoff>

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

@@ -68,7 +68,7 @@
     | 技术栈-选填 | 数据库/ORM/CSS方案/部署等留空项 | 可补 |
     | 项目起点 | 全新 or 已有代码（影响架构决策） | 必须 |
     | 已有资源 | 设计稿/品牌/已有API/第三方服务是否明确 | 可补 |
-    | 风格调性 | [?UI] 视觉关键词 / [?CLI] 输出风格 / [?API] 文档方案 | 可补 |
+    | 风格调性 | （仅ui项目） 视觉关键词 / （仅cli项目） 输出风格 / （仅api项目） 文档方案 | 可补 |
     | 边界 | 至少声明了 1 个反目标或硬性约束 | 建议 |
     | 成功指标 | 已填写具体可量化指标 | 建议 |
     | 参考项目 | 至少列出 1 个参照 | 建议 |
@@ -104,7 +104,7 @@
     **Trigger**: 仅当 Step 1 发现"必须"或"可补"级缺口时执行。
     **Input**: Step 1 的缺口列表。问题数上限 3-6 题。
 
-    [[SKILL: 按 `archi-interview-protocol` Skill 的核心规则和标准输出格式提问。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则）]]
+    [[SKILL: archi-interview-protocol|按 skill 的核心规则和标准输出格式提问。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-interview-protocol/SKILL.md` 并遵循其规则）]]
 </step_2_supplementary>
 
 <step_3_constitution>
@@ -122,8 +122,8 @@
     | 项目身份、目标用户、成功指标、参考灵感 | `[[__DOCS_DIR__]]/global/vision.md` |
     | 技术栈、部署目标、第三方库/服务 | 规则文件 `02_tech_stack` |
     | 风格调性（UI/CLI/API）— 审美方向/信息密度/动效偏好 | 规则文件 `02_tech_stack` (UI Protocol) + `design_tokens.json` aestheticDirection + motion.preference + illustration |
-    | [?UI] **审美方向** (saas-dark/saas-light/dashboard/marketing/mobile-app/editorial/brutalist/custom) | `design_tokens.json` `aestheticDirection.preset` + `aestheticDirection.customDescription` |
-    | [?UI] **视觉参考**（品牌色板/字体/图标库/竞品截图/禁用风格） | `design_tokens.json` primitivePalette.brand + illustration + motion; 截图/URL 存入 `vision.md` Visual Reference |
+    | （仅ui项目） **审美方向** (saas-dark/saas-light/dashboard/marketing/mobile-app/editorial/brutalist/custom) | `design_tokens.json` `aestheticDirection.preset` + `aestheticDirection.customDescription` |
+    | （仅ui项目） **视觉参考**（品牌色板/字体/图标库/竞品截图/禁用风格） | `design_tokens.json` primitivePalette.brand + illustration + motion; 截图/URL 存入 `vision.md` Visual Reference |
     | 核心任务列表 | `[[__DOCS_DIR__]]/global/roadmap.json` |
     | **已有设计决策** | Roadmap 对应任务的 `goal` 字段中注入，并在 `/archi.plan` 时作为硬约束 |
     | 边界与反目标 | `[[__DOCS_DIR__]]/global/vision.md` Boundaries |
@@ -147,12 +147,12 @@
     - Brief 中留空/写"推荐"的 → AI 基于项目特征推荐，须在输出中标注 `(AI 推荐)` 并简述理由
     - Brief 中已有的第三方服务/API → 写入对应 Section
     - **AX Optimization**: 推荐时优先 AI 友好型技术 (Static Typing, Popular Frameworks, Convention-over-Configuration)
-    - 须填充完整的 Section 1-9（Global Mandates、Technology Selection、Coding Standards、UI Protocol[?UI]、Testing、Deployment、Architecture、Anti-Patterns、**Project Conventions**）
+    - 须填充完整的 Section 1-9（Global Mandates、Technology Selection、Coding Standards、UI Protocol（仅ui项目）、Testing、Deployment、Architecture、Anti-Patterns、**Project Conventions**）
     - `Section 5 Testing` 中的 Environment Scripts 定义须完整
     - **Section 9 Project Conventions**: 基于 Brief 和项目特征确立全局架构约定，`/archi.plan` 将自动继承这些约定而非逐任务重复提问：
-      - **Error Handling**: 根据项目类型推断 — [?UI] Fail Fast + Form Validation; [?CLI] Fail Fast (stderr); [?API] Schema Validation + Fail Fast; 多选时空格分隔
-      - [?UI] **Data Flow**: 根据实时性需求 — 无实时需求 → Standard Request (+ SWR/React Query if applicable); Brief 提及实时/协作 → Realtime
-      - [?Web/API] **Auth & Access**: 根据 Brief 用户角色 — 单角色 → Authenticated; 多角色 → RBAC; 无权限描述 → 留空待 Plan 阶段逐任务确认
+      - **Error Handling**: 根据项目类型推断 — （仅ui项目） Fail Fast + Form Validation; （仅cli项目） Fail Fast (stderr); （仅api项目） Schema Validation + Fail Fast; 多选时空格分隔
+      - （仅ui项目） **Data Flow**: 根据实时性需求 — 无实时需求 → Standard Request (+ SWR/React Query if applicable); Brief 提及实时/协作 → Realtime
+      - （仅ui或api项目） **Auth & Access**: 根据 Brief 用户角色 — 单角色 → Authenticated; 多角色 → RBAC; 无权限描述 → 留空待 Plan 阶段逐任务确认
       - 每项须填写 Strategy/Default + Rationale（理由须结合此项目的具体场景）
 
     ### 3.3 Custom Rules (规则文件 `90_custom_rules`)
@@ -161,12 +161,12 @@
     - 如用户未提供任何自定义规则，保持模板默认内容
 
     ### 3.4 Roadmap (`[[__DOCS_DIR__]]/global/roadmap.json`)
-    [[SKILL: 按 `archi-decompose-roadmap` Skill 的协议，基于 Brief 任务列表生成任务链，写入 roadmap.json]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 并遵循其协议执行）]]，生成后直接进入下一步，无需用户确认。
+    [[SKILL: archi-decompose-roadmap|按 skill 的协议，基于 Brief 任务列表生成任务链，写入 roadmap.json，生成后直接进入下一步，无需用户确认。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-decompose-roadmap/SKILL.md` 并遵循其协议执行）]]
 
     ### 3.5 其他全局文档 (按需)
     - `dictionary.json`: 从 Brief 提取领域术语
-    - [?Data] `data_snapshot.json`: 基于 Brief 中的数据描述，初始化核心实体骨架（实体名 + 主键字段）；无数据描述时写入空模板
-    - [?UI] `design_tokens.json`: 基于 Brief「风格与调性」和「视觉参考」填充：
+    - （仅data项目） `data_snapshot.json`: 基于 Brief 中的数据描述，初始化核心实体骨架（实体名 + 主键字段）；无数据描述时写入空模板
+    - （仅ui项目） `design_tokens.json`: 基于 Brief「风格与调性」和「视觉参考」填充：
       - `aestheticDirection.preset`: 从 Brief 审美方向字段填入；Brief 未填时基于项目特征推断（Web SaaS 默认 saas-light，Dashboard 默认 dashboard 等）
       - `aestheticDirection.customDescription`: 仅 custom 时填入用户描述
       - `primitivePalette.brand`: 从品牌色板提取 Hex 值；无则留空
@@ -186,23 +186,16 @@
     **Output**: 写入所有文件，然后运行 `npx archi render` 生成可视化 `.md`。
 </step_3_constitution>
 
-<step_4_audit>
-    **Role**: 首席审计官
-    **Checklist**:
-    1.  **Vision 完整性**: `vision.md` 含北极星指标和设计哲学？
-    2.  **Tech Stack 一致性**: 规则文件 `02_tech_stack` 与 Brief 技术偏好一致？含完整技术栈声明？
-    3.  **Custom Rules**: Brief 补充说明/技术红线中的规则是否已写入规则文件 `90_custom_rules`？
-    4.  **Roadmap 合规**: 运行 `npx archi task --check` 验证一致性。
-    5.  [?UI] **Design Tokens**: `design_tokens.json` 含基础颜色/字体/间距定义？
-    6.  **Brief 对齐**: 所有 Brief 中声明的核心任务均已映射到 Roadmap 任务？
-    7.  **信息零遗漏**: Brief 中所有用户填写的内容均已路由到对应文件？
+<step_4_verify>
+    **Role**: 独立审查官
+    [[SUBAGENT: archi-silent-audit|mode: init, context: 审查 step_3 生成的全局文件（vision, tech_stack, roadmap, dictionary 等）]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-silent-audit/SKILL.md`，按 mode: init 的审查维度表逐项检查）]]
 
-    如有问题则静默修正；严重问题标记 `Risk Warning`。
-</step_4_audit>
+    [[INCLUDE: shared/verify-result-handling.md]]
+</step_4_verify>
 
 <step_4_5_ui_wireframe>
-    **Trigger**: 仅当项目特征含 [?UI] 时执行。
-    **Action**: 自动调用 `archi-ui-wireframe` Skill（Phase 1 线框图）。
+    **Trigger**: 仅当项目 features 含 `ui` 时执行。
+    **Action**: [[SKILL: archi-ui-wireframe|按 skill 的协议，自动调用 Phase 1 线框图生成。]][[NO-SKILL: （Skill 未安装：请阅读 `[[__DOCS_DIR__]]/skills/archi-ui-wireframe/SKILL.md` 并遵循其协议执行）]]
     - 无需用户确认即开始生成
     - 读取刚写入的 vision.md + roadmap.json + design_tokens.json + 02_tech_stack
     - 写入 `ui_concept.html` + `ui_context.md`
@@ -230,7 +223,7 @@
 
     | 优先级 | 行动 | 说明 |
     |:---|:---|:---|
-    | [?UI] 推荐 | 回复 **OK** 进入 Phase 2 着色 | Phase 1 线框图已自动生成；确认布局后着色 |
+    | （仅ui项目） 推荐 | 回复 **OK** 进入 Phase 2 着色 | Phase 1 线框图已自动生成；确认布局后着色 |
     | 推荐 | `/archi.plan INF-01` | 规划第一个基础设施任务 |
     | 可选 | `/archi.scope <scope-brief.md>` | 如有更多需求待分解，追加到 Roadmap |
 </step_5_signoff>

package/dist/templates/zh/docs/shared/verify-result-handling.md

@@ -0,0 +1,6 @@
+**审查结果处理**:
+| 级别 | 处理 |
+|:---|:---|
+| CRITICAL | 须修复后再继续 |
+| WARNING | 须在签收中说明处理方式 |
+| INFO | 可自行决定 |

package/dist/templates/zh/docs/templates/design.template.md

@@ -0,0 +1,77 @@
+---
+description: "仅Complex任务: 技术方案设计 — 定义核心机制的实现策略、状态流转、参数与不变量。仅当任务含非平凡技术决策时生成。"
+glue: 衔接 spec.md(WHAT) 与 plan.json(DO)，定义 HOW。plan.json tasks 须覆盖本文档所有机制；spec.md § 2 AC 须可在本设计中追踪出完整路径。
+---
+
+# Technical Design: {FEATURE_NAME}
+
+> **Spec**: `spec.md`（验收标准 — 本设计的约束来源）
+> **Plan**: `plan.json`（执行任务 — 本设计的下游消费者）
+> **Trigger**: [AI: 一句话说明为什么本任务需要技术方案设计]
+
+## 1. Solution Overview
+
+<!-- [AI]: 2-3 句概述技术方案及核心取舍。
+  - 引用 plan.json decisions 中的选型结果（如 "Data Flow=Realtime WebSocket"）
+  - 说明为何选此方案而非替代方案（如已在 step_2 讨论则简引）
+  - 禁重复 spec.md 验收标准内容；本节回答"用什么方式实现"而非"实现什么"
+-->
+
+## 2. Core Mechanisms
+
+<!-- [AI]: 本文档主体。按技术需求选用 ≥1 个结构化模式描述核心机制。
+  每个机制独立一个子章节（2.1, 2.2, ...），标注模式类型。
+  同一任务可组合多个模式（如：连接管理用状态机 + 消息处理用流水线）。
+
+  [[SKILL: archi-design-patterns|按 skill 的模式选择指南选取适用模式，生成标准格式表格并执行自检。自检未通过须修补后重检，全部通过再进入下一个机制。]]
+-->
+
+### 2.1 [机制名称] — 模式: [State Machine / Pipeline / Decision Matrix / Protocol]
+
+<!-- 按 archi-design-patterns skill 中对应模式的标准格式填写 -->
+
+## 3. Parameters
+
+<!-- [AI]: 所有机制中的具体数值，集中声明。
+  禁模糊描述（如"适当的超时"、"合理的间隔"），须写出具体值 + 单位 + 依据。
+
+  | 参数 | 值 | 单位 | 依据 |
+  |:---|:---|:---|:---|
+  | [参数名] | [具体值] | [单位] | [为什么是这个值] |
+-->
+
+## 4. Invariants
+
+<!-- [AI]: 系统在任何时刻都须满足的断言。每条须可被代码 assert 或测试验证。
+  格式: [INV-N] 断言描述
+
+  约束:
+  - 每条不变量须对应 plan.json 中至少一个 test 条目或 task notes 中的验证项
+  - 不变量是实现的"护栏"：AI 写代码时须确保不违反任何一条
+-->
+
+## 5. Failure Modes
+
+<!-- [AI]: 显式列举核心机制可能的故障场景。每个故障须有检测方式和应对策略。
+
+  | 故障 | 检测方式 | 应对策略 | 降级行为 |
+  |:---|:---|:---|:---|
+  | [故障描述] | [如何发现: 事件/超时/异常类型] | [首选恢复: 重试/重连/回滚] | [恢复失败后: 切换模式/提示用户/静默记录] |
+
+  约束:
+  - 检测方式须具体（禁"检测到错误时"，须写"收到 4xx / 心跳 3 次超时 / catch TypeError"）
+  - 降级行为须可观测（禁"报错"，须写具体 UI 反馈或 exit code）
+-->
+
+## 6. Trace Verification
+
+<!-- [AI]: 从 spec.md § 2 每条 AC 出发，在本设计中追踪执行路径。
+
+  | AC (来自 spec § 2) | 追踪路径 (在本设计中的执行链) | 结果 |
+  |:---|:---|:---|
+  | [Given X When Y Then Z] | [State A →(event)→ State B →(action)→ State C] 或 [Pipeline Step 1→2→3] | ✓ 可达 |
+  | [Given X When Error Then W] | [State A →(error)→ State D; Failure Mode #2 → 降级行为] | ✓ 可达 |
+
+  **Gap Check**: 某条 AC 无法追踪 → 回到 § 2 补充机制或 § 5 补充故障处理。
+  所有 AC 均 ✓ 后本设计可交付。
+-->

package/dist/templates/zh/docs/templates/spec.template.md

@@ -1,51 +1,86 @@
 ---
-description: Behavioral Specification (Gherkin) for {FEATURE_NAME}.
+description: Task Specification for {FEATURE_NAME}.
 ---
 
 # Task Spec: {FEATURE_NAME}
 
 > **Status:** [Draft]
-> **Context:** [AI: Insert a 1-sentence summary of the task's value]
+> **Task Type:** [Feature / Infra / Polish]
+> **Context:** [AI: 一句话描述本任务的目标和价值]
 
-## 1. User Stories
+## 1. Overview
 
-<!-- [AI Instruction]: 简述用户价值，从用户视角描述任务需求 -->
+<!-- [AI]: 简述任务背景、目标和用户价值（2-3 句）。
+  - FEAT 任务: 从用户视角描述 "As a [Role], I want to [Action], So that [Benefit]"
+  - INF 任务: 描述本基础设施支撑的下游范围
+  - POLISH 任务: 描述当前状态和优化目标
+-->
 
-- **As a** [Role] (e.g. 注册用户), **I want to** [Action] (e.g. 发表评论), **So that** [Benefit] (e.g. 与其他用户互动).
+## 2. Acceptance Criteria
 
-## 2. Behavioral Specifications (Gherkin)
+<!-- [AI]: 核心验收契约 — 开发和测试的唯一依据。
+  按 Task Type（从 ID 前缀推断）选择适用的维度格式，可组合多个维度。
 
-<!-- [AI Instruction]: 核心逻辑契约。这是开发和测试的唯一依据。 -->
+  === 维度积木（按需组合，至少选一个主维度）===
 
-### Scenario: [Happy Path Name, e.g. 用户成功提交]
+  ▸ Behavioral（行为维度）[FEAT 主维度]
+    用 Gherkin Given/When/Then 定义系统行为路径（正常 + 异常）。
 
-- **Given** 用户处于 [前置状态] (e.g. 已登录且表单填写合法)
+  ▸ Structural（结构维度）[INF 主维度]
+    用 Configuration Contract 定义文件/配置的目标状态：
+    - Path: 文件路径
+    - Key Settings: 关键配置项及具体值（禁泛化描述如"配置 X"）
+    - Constraints: 技术红线
+    - Verify: 可执行命令 + 期望输出
 
-- **When** 用户执行 [操作] (e.g. 点击提交按钮)
+  ▸ Quantitative（量化维度）[POLISH 主维度]
+    用 Quality Target 定义可度量目标：
+    - Metric: 指标名
+    - Baseline: 当前值
+    - Target: 目标值
+    - Verify: 测量方式
 
-- **Then** 系统应返回 [预期结果] (e.g. 显示成功 Toast)
+  ▸ Contractual（契约维度）[集成/共享引擎常用]
+    定义对外暴露或对接的接口契约：
+    - 外部 API 的 Input/Output/Error 映射
+    - 共享模块的导出类型签名
 
-- **And** 数据库记录应 [状态变更] (Ref: `data_snapshot.json`)
+  ▸ Invariant（不变量维度）[重构常用]
+    声明必须保持不变的行为/接口：
+    - Preserve: [必须不变的行为或接口]
+    - Verify: [回归验证方式]
 
-### Scenario: [Edge Case Name, e.g. 网络超时]
+  === 混合型任务示例 ===
+  INF 任务可能含 Behavioral 子维度（如热键注册有行为路径）
+  FEAT 任务可能含 Structural 子维度（如需创建配置文件）
+  用子标题区分不同维度即可。
+-->
 
-- **Given** 用户网络不稳定
+## 3. Data Requirements
 
-- **When** 用户点击提交按钮
+<!-- [AI]: （仅data项目） 声明数据变更，引用 data_snapshot.json 中的表结构。
+  无数据变更时写 "N/A"。
 
-- **Then** 系统应显示 [Error Message] (Ref: `error_codes.json`)
+  * Schema: [Table Name] -> [Field] (Add/Modify)
+  * API: [Method] [Path]
+  * Permissions: [Required Role]
+-->
 
-- **And** 不应产生脏数据
+## 4. Interface Exports
 
-## 3. Data Requirements
+<!-- [AI]: （有下游消费者时） 本任务暴露给下游任务的公共接口、约定、导入路径。
+  下游任务依赖此处声明而非猜测。无下游消费者时省略本节。
 
-<!-- [AI Instruction]: 明确数据变更，必须引用 `data_snapshot.json` 中的表结构 -->
+  格式:
+  | Export | Value | Consumer |
+  |:---|:---|:---|
+  | [约定/API/path alias/脚本] | [具体值] | [下游任务 ID] |
+-->
 
-* **Schema**: [Table Name] -> [Field] (Add/Modify)
-  - Example: `Comment` -> `content` (Add), `parent_id` (Add, nullable)
+## 5. Constraints
 
-* **API**: [Method] [Path]
-  - Example: `POST /api/comments`, `GET /api/comments/:id`
+<!-- [AI]: 从 vision.md + 02_tech_stack.md 提取与本任务相关的红线约束。
 
-* **Permissions**: [Required Role]
-  - Example: `authenticated` (for POST), `public` (for GET)
+  格式:
+  - [约束内容] (ref: [来源])
+-->

package/dist/templates/zh/rules/00_system.md

@@ -5,6 +5,15 @@ applyTo: **/*
 alwaysApply: true
 ---
 
+<priority_chain>
+规则冲突时优先级（高→低）:
+1. `/archi.*` 协议文件（可覆盖 thinking_process、communication_style）
+2. `90_custom_rules.md`（可覆盖 02_tech_stack 具体选项）
+3. `00_system.md` core_philosophy（不可覆盖的宪法条款）
+4. `02_tech_stack.md` + `03_data_governance.md`
+5. `99_context_glue.md`（导航辅助，无决策权）
+</priority_chain>
+
 <system_role>
 你是一位**世界级的架构师 (World-Class Architect)**。
 你不仅是代码生成者，更是 **Project Architecture (Based on map.json)** 的守护者和 **Document-Driven AI Development (DDAD)** 的执行官。
@@ -45,6 +54,31 @@ alwaysApply: true
 </protocol>
 </critical_protocols>
 
+<project_features>
+协议与模板中以 `仅xx项目:` 开头或 `（仅xx项目）` 标注的内容表示条件执行——仅当项目 features 包含对应值时才执行/读取，否则跳过。
+
+读取 `architext.json` → `features` 数组判定项目特征。条件性全局文件（如 `api_snapshot.json`）由 CLI init 时按 features 筛选部署，文件存在即表示该 feature 已激活。
+
+| feature | 含义 |
+|:---|:---|
+| ui | 有用户界面（Web/移动端/桌面端/小程序） |
+| data | 有数据层（数据库/ORM/本地存储） |
+| api | 有 HTTP/RPC/GraphQL 接口 |
+| cli | 有命令行入口 |
+| lib | 作为库/SDK/NPM 包发布 |
+| mobile | 移动端（RN/Flutter/Expo） |
+| desktop | 桌面端（Electron/Tauri） |
+| miniapp | 小程序（微信/支付宝/uni-app） |
+| extension | 浏览器扩展（Chrome/Firefox） |
+| realtime | 实时/WebSocket/协作 |
+| ai | AI Agent / MCP |
+
+**其他条件**按字面含义判定：
+- `仅Complex任务:` — `/archi.plan` step_1_5 判定，任务含复杂机制（状态机/流水线/协议）时成立
+- `仅GraphQL/CRDT/MCP/i18n项目:` — 读 `02_tech_stack.md` 判断技术选型是否匹配
+- 其余中文条件（如 `如有下游消费者:`）— 按字面理解
+</project_features>
+
 <architecture_governance>
   <style>Defined in `02_tech_stack.md` (Dynamic)</style>
 
@@ -106,11 +140,7 @@ alwaysApply: true
     - ⚠️ 超出 spec 范围（新接口 · 改签名 · 新行为 · 新场景）→ 输出 `⚠️ Spec 漂移`，建议 `/archi.edit <ID>`
 
     **B. 数据治理**:
-    | 触发条件 | 文件 | 动作 |
-    |:---|:---|:---|
-    | 引入未登记的业务实体 · 动作 · 共享工具 | `dictionary.json` | 直接追加写入 |
-    | 引入未注册的错误场景 | `error_codes.json` | 直接追加写入 |
-    | [?Data] Schema 有变更 | `data_snapshot.json` | 直接同步 |
+    [[SUBAGENT: archi-data-sync|context: 扫描本次变更引入的新业务实体/错误码/Schema，按 03_data_governance.md 规则增量同步]][[NO-SKILL: 本次变更引入新业务实体/错误码/Schema 时，按 `03_data_governance.md` 增量同步规则执行。]]
   </step>
 </thinking_process>
 

package/dist/templates/zh/rules/01_workflow.md

@@ -37,7 +37,8 @@ alwaysApply: true
 
 > **Protocol Load Gate** (禁跳过，三步须按序完成):
 > 1. **Read** 目标 `.md` 全文 → 文件不存在时停止，输出: `协议文件未找到，中止执行`
-> 2. **Override** `00_system` 部分设定
+> 2. **Override** — 可覆盖: `<system_role>`, `<thinking_process>`, `<communication_style>`。
+>    不可覆盖: `<core_philosophy>`, `<critical_protocols>`, `<architecture_governance>`。
 > 3. **Execute** `<step_1>` — 禁在步骤 1 完成前执行任何协议内容
 
 ---
@@ -73,9 +74,9 @@ alwaysApply: true
 ### 2.3 未纳管代码
 
 修改对象未在 `map.json` 中注册、无对应 Task:
-- 告知用户该模块未纳管
-- 建议 `/archi.inherit` 或 `/archi.scope` 纳入
-- 用户确认"临时调整"后可直接修改
+- **STOP & ASK** — 告知用户该模块未纳管
+- 建议 `/archi.inherit` 或 `/archi.scope` 纳入管理
+- 禁直接修改未纳管代码，须等待用户提供文档路径或完成纳管后再操作
 
 ### 2.4 基底规则
 

package/dist/templates/zh/rules/02_tech_stack.md

@@ -50,6 +50,7 @@ alwaysApply: true
 
 ---
 
+<!-- ═══════ 以下为固定协议（禁修改） ═══════ -->
 ## 4. UI Protocol: ITP v3.0 (Dual-Artifact) [可选 - 仅适用于有 UI 的项目]
 <!-- 核心 UI 描述协议 -->
 > **Note:** 如果项目没有 UI（如 CLI、Backend API、Library），可以删除此章节。
@@ -109,7 +110,7 @@ UI 制品层级：
 ### Test Suite (测试套件)
 * **Unit:** Tool: [例如：Vitest / Jest / pytest / cargo test / go test]  Scope: [例如：Utils 工具函数、核心业务逻辑、算法]  Rule: [例如：须 Mock 外部依赖；禁对易变 UI 做快照测试]
 * **Integration:** Tool: [例如：Vitest + Testcontainers / pytest + Docker]  Scope: [例如：API→DB 写入链路 / CLI 完整执行流程]
-* **E2E:** Tool: [例如：[?Web] Playwright / Cypress  [?API] Supertest / httpie  [?CLI] bats / shell script  [?Lib] 示例项目 + 自动化脚本  [?Mobile] Detox / Maestro]  Scope: [例如：[?Web] 核心用户路径  [?API] 关键 endpoint 全链路  [?CLI] 关键命令全流程  [?Lib] 公开 API 典型使用场景]
+* **E2E:** Tool: [例如：（仅ui项目） Playwright / Cypress （仅api项目） Supertest / httpie （仅cli项目） bats / shell script （仅lib项目） 示例项目 + 自动化脚本 （仅mobile项目） Detox / Maestro]  Scope: [例如：（仅ui项目） 核心用户路径 （仅api项目） 关键 endpoint 全链路 （仅cli项目） 关键命令全流程 （仅lib项目） 公开 API 典型使用场景]
 * **Test Command:** [例如：`pnpm test` / `pytest` / `cargo test` / `go test ./...`]
 
 ### Environment Scripts (环境脚本)
@@ -158,9 +159,9 @@ UI 制品层级：
 | :--- | :--- | :--- |
 | **Unit Tests** | [e.g. Centralized 或 Colocation] | `__tests__/utils/date.test.ts` / `utils/date.test.ts` |
 | **Interfaces/Types** | [e.g. Near usage 或 Global types] | `types/user.d.ts` / `domain/user.entity.ts` |
-| **Assets/Images** [?UI] | [e.g. Public 或 Module assets] | `public/images` / `assets/` |
-| **Styles** [?UI] | [e.g. 按组件或全局] | `Button.module.css` / `global.css` |
-| **DTOs/Models** [?Data] | [e.g. Domain 或 Shared] | `domain/user/dto` / `models/` |
+| **Assets/Images**（仅ui项目） | [e.g. Public 或 Module assets] | `public/images` / `assets/` |
+| **Styles**（仅ui项目） | [e.g. 按组件或全局] | `Button.module.css` / `global.css` |
+| **DTOs/Models**（仅data项目） | [e.g. Domain 或 Shared] | `domain/user/dto` / `models/` |
 
 ---
 
@@ -183,10 +184,10 @@ UI 制品层级：
 * **Strategy:** [例如：Fail Fast + Form Validation / Fail Fast (stderr) / Schema Validation + Fail Fast]
 * **Rationale:** [例如：表单密集型应用，需前端实时校验 + 后端快速失败]
 
-### Data Flow (数据流模式) [?UI]
+### Data Flow (数据流模式) （仅ui项目）
 * **Default:** [例如：Standard Request + SWR / Realtime (Socket) / Polling]
 * **Rationale:** [例如：大部分页面为 CRUD 读写，SWR 做缓存和重新验证]
 
-### Auth & Access (认证与权限) [?Web/API]
+### Auth & Access (认证与权限) （仅ui或api项目）
 * **Mechanism:** [例如：JWT + RBAC / Session + Owner Only / API Key]
 * **Rationale:** [例如：多角色后台管理系统，需细粒度权限控制]

package/dist/templates/zh/rules/03_data_governance.md

@@ -16,9 +16,13 @@ alwaysApply: true
 | `roadmap.json` | 路线图 | `/archi.plan`, `/archi.code` 开始时 | `/archi.start` 创建; AI 直接编辑或 `npx archi task` 更新状态 |
 | `map.json` | 架构地图 | 触碰代码时 (via context_glue) | `/archi.plan` Step 3 (全局同步); `/archi.inherit` Step 3.6; `/archi.map` |
 | `dictionary.json` | 术语字典 | 生成变量名/命名时 | `/archi.plan` Step 3; code/fix 后 step_5 自动追加 |
-| `design_tokens.json` | 设计令牌 [?UI] | 生成 UI 代码时 | `/archi.start` 创建; 设计变更时更新 |
-| `data_snapshot.json` | 数据快照 [?Data] | `/archi.plan` Q1 设计; `/archi.code` 实现时 | Plan 阶段设计 Schema; Code 阶段同步实际变更 |
-| `error_codes.json` | 错误码契约 | 编写错误处理时 | `/archi.plan` Step 3; code/fix 后 step_5 自动追加 |
+| `design_tokens.json` | 设计令牌（仅ui项目） | 生成 UI 代码时 | `/archi.start` 创建; 设计变更时更新 |
+| `data_snapshot.json` | 数据快照（仅data项目） | `/archi.plan` Q1 设计; `/archi.code` 实现时 | Plan 阶段设计 Schema; Code 阶段同步实际变更 |
+| `error_codes.json` | 业务错误码 | 编写错误处理时 | `/archi.plan` Step 3; code/fix 后 step_5 自动追加 |
+| `api_snapshot.json` | API 端点（仅api项目） | 实现/对接 HTTP 端点时 | `/archi.plan` Step 3 注册端点; Code 阶段同步实际路径 |
+| `env_registry.json` | 环境变量（仅api项目） | 引入新配置项时 | Code 阶段引入新 env var 后立即追加 |
+| `command_api.json` | 命令签名（仅cli项目） | 实现/修改 CLI 命令时 | `/archi.plan` Step 3 注册命令; Code 阶段同步实际签名 |
+| `public_api.json` | 公共导出（仅lib项目） | 新增/修改导出 API 时 | `/archi.plan` Step 3 注册导出; Code 阶段同步实际签名 |
 
 ---
 
@@ -29,7 +33,7 @@ alwaysApply: true
 - **JSON Only**: 全局数据的唯一真理源是 `.json` 文件。`.md` 视图由 `npx archi render` 自动生成，禁直接编辑 `.md` 视图。
 - **Schema Stability**: 分两档管理：
   - **Tier 1 (严格)**: `roadmap.json`, `plan.json` — CLI 渲染/命令直接依赖，结构由 Zod Schema 校验，禁随意变更字段。
-  - **Tier 2 (宽松)**: `dictionary.json`, `error_codes.json`, `data_snapshot.json`, `design_tokens.json`, `map.json` — 仅校验顶层 key 存在。若现有字段无法充分描述需记录的内容，可自行扩展字段（添加新 key 或在数组 item 中添加新属性），无需修改 CLI。
+  - **Tier 2 (宽松)**: `dictionary.json`, `error_codes.json`, `data_snapshot.json`, `design_tokens.json`, `map.json`, `api_snapshot.json`, `env_registry.json`, `command_api.json`, `public_api.json` — 仅校验顶层 key 存在。若现有字段无法充分描述需记录的内容，可自行扩展字段（添加新 key 或在数组 item 中添加新属性），无需修改 CLI。
 - **Valid JSON**: 写入后须保证合法 JSON (无尾逗号、无注释)。
 
 ### 2.2 读写纪律
@@ -67,16 +71,16 @@ alwaysApply: true
 - **entities**: 生成变量名前须查阅 `entities[].codeName`；禁使用 `forbiddenSynonyms` 中的词。
 - **verbs**: 业务动作命名须查阅 `verbs[].codeName`，保持全项目动词一致。
 - **utilities**: 封装的共享工具（如 logger、AppError、fetchClient）须注册；AI 须用已注册工具替代原始 API（参照 `replaces` 字段）。
-- **components** [?UI]: 创建新组件前须搜索现有组件，优先复用。
+- **components** （仅ui项目）: 创建新组件前须搜索现有组件，优先复用。
 - **可扩展**: 若现有字段不足以描述某个术语/工具，可在对应数组 item 中自行添加字段（如 `tags`、`scope`、`deprecated`），也可添加新顶层数组（如 `enums`、`constants`）。
 
-### `design_tokens.json` [?UI]
+### `design_tokens.json` （仅ui项目）
 
 - **Token Only**: 样式严格使用 Token；禁硬编码 Hex/px/rem。
 - **Dark Mode**: 须同时定义 `light` 和 `dark` 值。
 - **可扩展**: 若现有 Token 结构不足以覆盖项目需求（如 `motion`、`breakpoints`、`z-index`），可自行添加新属性。
 
-### `data_snapshot.json` [?Data]
+### `data_snapshot.json` （仅data项目）
 
 - **结构**: `models[]`（名称、字段、类型、约束）+ `relationships[]`（模型间关系：1:1/1:N/M:N/self-ref）。
 - **Design First**: Plan 阶段须定义模型结构和字段类型，禁写 "TBD"，须精确到字段名与类型。
@@ -86,11 +90,38 @@ alwaysApply: true
 ### `error_codes.json`
 
 - **Boundary**: 仅注册**项目业务域**错误。框架基础设施（scripts/validate、dev-up、dev-reset 等）的错误由脚本自身 exit code + stderr 处理，禁注册到此文件。
-- **结构**: `protocolMapping [?API]`（状态码→行为映射）+ `businessErrors`（业务错误注册表）。
+- **结构**: `businessErrors`（业务错误注册表）。HTTP 协议状态码映射见 `api_snapshot.json`。
 - **Code Format**: `ERR_[MODULE]_[REASON]` (如 `ERR_AUTH_INVALID_TOKEN`)。
 - **statusCode**: 按项目类型填写（HTTP status / Exit code / 留空）。
 - **Design Before Code**: 编写错误处理代码前须先在此注册错误码，含 `message` 和 `recovery`。
-- **可扩展**: 若现有字段不足以描述错误信息（如需记录 `severity`、`retryable`、`httpBody`），可在 item 中自行添加字段。
+- **可扩展**: 若现有字段不足以描述错误信息（如需记录 `severity`、`retryable`），可在 item 中自行添加字段。
+
+### `api_snapshot.json` （仅api项目）
+
+- **结构**: `endpoints[]`（端点注册表）+ `protocolMapping[]`（HTTP 状态码→调用方行为映射）。
+- **Register First**: 规划端点前须先在此注册，禁实现未登记的端点。
+- **owner**: 每个端点须标注归属 Task ID，便于追踪变更来源。
+- **可扩展**: 可在 endpoint item 中追加 `tags`、`deprecated`、`version` 等字段。
+
+### `env_registry.json` （仅api项目）
+
+- **Register on Introduce**: 代码中每引入一个新的 `process.env.X` 或等价配置读取，须立即在此追加记录。
+- **required**: 必填项标 `true`；有合理默认值的标 `false` 并填写 `default`。
+- **example**: 须提供示例值，禁留空（帮助新成员快速配置环境）。
+- **可扩展**: 可追加 `sensitive`（是否为密钥）、`validValues`（枚举约束）等字段。
+
+### `command_api.json` （仅cli项目）
+
+- **Register on Introduce**: 每新增或修改 CLI 命令后同步更新此文件。
+- **owner**: 每条命令须标注归属 Task ID。
+- **可扩展**: 可追加 `examples`、`deprecated`、`since` 等字段。
+
+### `public_api.json` （仅lib项目）
+
+- **Stability First**: 导出 API 一旦标注 `stable`，变更须走 `/archi.edit` 流程，不可随意修改签名。
+- **signature**: 须写完整 TypeScript 签名，禁模糊描述（如"返回用户对象"）。
+- **owner**: 每条导出须标注归属 Task ID。
+- **可扩展**: 可追加 `since`、`examples`、`seeAlso` 等字段。
 
 ---
 

package/dist/templates/zh/rules/99_context_glue.md

@@ -33,8 +33,8 @@ alwaysApply: true
 | 代码类型 | 必读上下文 | 真理来源 |
 |:---|:---|:---|
 | **Business Logic** (Tasks/Entities) | Spec Document | `[[__DOCS_DIR__]]/global/map.json` → Module Entry |
-| **UI Components** (Pages/Widgets) [?UI] | UI Document + `[[__DOCS_DIR__]]/global/design_tokens.json` | `[[__DOCS_DIR__]]/global/map.json` + Global Rules |
-| **Data Schema** (ORM/SQL/Models) [?Data] | Data Snapshot | `[[__DOCS_DIR__]]/global/data_snapshot.json` |
+| **UI Components** (Pages/Widgets)（仅ui项目） | UI Document + `[[__DOCS_DIR__]]/global/design_tokens.json` | `[[__DOCS_DIR__]]/global/map.json` + Global Rules |
+| **Data Schema** (ORM/SQL/Models)（仅data项目） | Data Snapshot | `[[__DOCS_DIR__]]/global/data_snapshot.json` |
 | **Config / Infra** (Package.json...) | Tech Stack | `02_tech_stack.md` |
 
 ---