@haaaiawd/anws 2.1.2 → 2.2.1

package/templates/.agents/workflows/forge.md

@@ -21,10 +21,11 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
 - **绝不**添加文档未定义的功能或依赖
 - **绝不**在有疑问时猜测——必须停下来确认
 
-**核心原则**：
-- 📖 **文档即合约** — 规范文档是不可违反的权威
-- 🌊 **波次执行** — 每波 2-5 个任务，加载→编码→验证→提交
-- 🛑 **遇疑则停** — 发现问题立即停止，不猜不赶
+**核心原则**：
+- 📖 **文档即合约** — 规范文档是不可违反的权威
+- 🌊 **波次执行** — 每波 2-5 个任务，加载→编码→验证→提交
+- 🛑 **遇疑则停** — 发现问题立即停止，不猜不赶
+- ✍ **签名机制** — 每次波次开始都要经过检查点；普通模式由用户签名，`/forge自动` 模式记为 `AUTO`
 
 **与用户的关系**：
 你是用户的**忠实执行者**，不是自由发挥的创造者。
@@ -75,14 +76,15 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
 >
 > | 冲突类型 | 处理方式 |
 > |---------|---------|
-> | 文档之间互相矛盾 | 🛑 停止 → 列出矛盾点 → 用户通过 `/change` 修复 |
-> | 任务描述模糊/不完整 | 🛑 停止 → 列出疑问 → 用户确认或通过 `/change` 补充 |
-> | 依赖的前置任务产物与预期不符 | 🛑 停止 → 报告差异 → 用户决定 |
-> | 发现设计不可实现 | 🛑 停止 → 记录原因 → 建议用户运行 `/challenge` |
-> | 需要 ADR 未批准的新依赖 | 🛑 停止 → 说明理由 → 用户决定是否创建新 ADR |
-> | 需要的系统设计文档不存在 | 🛑 停止 → 引导用户运行 `/design-system` |
->
-> **核心原则: 宁可停下来问，也不要猜测。**
+> | 文档之间互相矛盾 | 🛑 停止 → 列出矛盾点 → 用户通过 `/change` 修复 |
+> | 任务描述模糊/不完整 | 🛑 停止 → 列出疑问 → 用户确认或通过 `/change` 补充 |
+> | 依赖的前置任务产物与预期不符 | 🛑 停止 → 报告差异 → 用户决定 |
+> | 发现设计不可实现 | 🛑 停止 → 记录原因 → 建议用户运行 `/challenge` |
+> | 需要 ADR 未批准的新依赖 | 🛑 停止 → 说明理由 → 用户决定是否创建新 ADR |
+> | 需要的系统设计文档不存在 | 🛑 停止 → 引导用户运行 `/design-system` |
+> | **发现未定义但必须新增/修改的公共契约** | 🛑 停止 → 生成回流说明 → 跳转 `/change` |
+>
+> **核心原则: 宁可停下来问，也不要猜测。**
 
 ---
 
@@ -105,23 +107,40 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
    - [ ] `{TARGET_DIR}/04_SYSTEM_DESIGN/` 存在且非空
    - 如缺失: "⚠️ 建议先运行 `/design-system`。缺少详细设计可能导致实现质量下降。"
 
-5. **如果必需文件缺失**: 报错并提示运行 `/genesis` + `/blueprint`。
-
-6. **断点续做判定**:
-   - 读取 `AGENTS.md` 的 `🌊 Wave` 块
-   - 如果存在波次信息：
-     - 查看波次任务列表，对照 `05_TASKS.md` 中的 checkbox
-     - 如有未完成任务 → **断点续做** → 跳入 Step 3 继续未完成的任务
-     - 如全部完成 → **新波次** → 继续 Step 1
-   - 如果不存在 → **新开始** → 继续 Step 1
-
-7. **Git 上下文检查**:
-   - 读取当前 branch
-   - 如当前在 `main` 且本次不是单文件小修 → 先创建并切换到 `feature/{topic-slug}`
-   - 如当前已在 `feature/*` 且本波次仍属于同一交付主题 → 继续在当前 branch 上推进
-   - 如当前已在 `feature/*` 但本波次目标已切换为另一独立主题 → 新建并切换到新的 `feature/{topic-slug}`
-   - 同一交付目标下的多波次，默认持续使用同一个 `feature/*` branch，直到 Step 5 完成里程碑结算
-   - 如本波次属于高风险改造（跨系统 / 预计改动 > 5 文件 / 涉及公共接口）→ 在当前工作 branch 上先创建 checkpoint commit：`checkpoint: before {topic}`
+5. **如果必需文件缺失**: 报错并提示运行 `/genesis` + `/blueprint`。
+
+6. **Challenge 门禁检查**:
+   - 如果 `{TARGET_DIR}/07_CHALLENGE_REPORT.md` 存在，必须先读取最新审查结果
+   - 如存在**未处理 Critical** → **立即阻塞**，不得进入 `/forge`
+   - 如存在**未处理 High** → 仅允许用户显式签名放行；AUTO 模式不得自动通过
+   - 如无未处理高严重度问题 → 继续
+
+7. **断点续做判定**:
+    - 读取 `AGENTS.md` 的 `🌊 Wave` 块
+    - 如果存在波次信息：
+      - 查看波次任务列表，对照 `05_TASKS.md` 中的 checkbox
+      - 如有未完成任务 → **断点续做** → 跳入 Step 3 继续未完成的任务
+      - 如全部完成 → **新波次** → 继续 Step 1
+    - 如果不存在 → **新开始** → 继续 Step 1
+
+8. **模式判定**:
+   - 如用户输入 `/forge自动` 或明确要求自动连续推进 → 进入 **AUTO 模式**
+   - 否则 → 默认 **普通模式**
+
+9. **Git 上下文检查**:
+    - 读取当前 branch
+    - 仓库只认两类分支：`main` 和 `feature/*`
+    - `main` 只保存已验证通过、可视为稳定的状态
+    - 所有正常开发默认都在 `feature/*` 上完成；只要不是单文件小修，就不要直接在 `main` 上改
+    - 如当前在 `main` 且本次不是单文件小修 → 创建并切换到 `feature/{topic-slug}`
+    - 如当前已在 `feature/*` 且仍属于同一交付主题 → 继续在当前 branch 上推进，不因补任务、补契约、补测试而反复新开分支
+    - 如当前已在 `feature/*` 且主题未变，即使经历 `/change` 回流，也继续使用同一条分支
+    - 只有 `/genesis` 触发、版本前提变化时，旧 `feature/*` 才冻结；新版本应从最新 `main` 重新开一条新的 `feature/*`
+    - 如进入 `/change` 前需要保护点，可先在当前 `feature/*` 上创建 checkpoint commit：`checkpoint: before {topic}`
+
+> [!IMPORTANT]
+> **Git 判断口诀**：
+> 同主题就不换分支，`/change` 不换分支，`/genesis` 才换分支；开发都在 `feature/*`，稳定结果才进 `main`，tag 只打 `main`。
 
 ---
 
@@ -129,10 +148,10 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
 
 **目标**: 从任务清单中挑选一组可执行的任务，组成一个"波次"。
 
-> [!IMPORTANT]
-> **你不能自己决定波次内容，必须建议后由用户确认。**
->
-> **为什么？** 用户对项目优先级和进度节奏有最终决定权。
+> [!IMPORTANT]
+> **你不能自己决定波次内容，必须在检查点获得签名后再开始。**
+>
+> **为什么？** 用户对项目优先级和进度节奏有最终决定权；`/forge自动` 只是把签名从用户改为 `AUTO`，不是删除检查点。
 
 ### 1.1 扫描可执行任务
 
@@ -168,14 +187,18 @@ description: "按照架构文档和任务清单将设计锻造为代码。适用
 确认此波次？或调整任务组合？
 ```
 
-**人类检查点** ⚠️: 用户确认后，将确认的波次写入 `AGENTS.md` 的 `🌊 Wave` 块：
+**签名检查点** ⚠️: 获得签名后，将确认的波次写入 `AGENTS.md` 的 `🌊 Wave` 块：
 
 ```markdown
 ### 🌊 Wave {N} — {波次目标简述}
 T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 ```
 
-然后进入 Step 2。
+然后进入 Step 2。
+
+签名规则：
+- 普通模式 → 等待用户签名
+- AUTO 模式 → 保留波次展示，并将签名记为 `AUTO` 后继续执行
 
 ---
 
@@ -267,15 +290,26 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ---
 
-### 3.3 编码实现
+### 3.3 编码实现
 
 > [!IMPORTANT]
 > **严格按设计文档和验收标准编码，不多不少。**
 
-- 代码结构遵循 `02_ARCHITECTURE_OVERVIEW.md` 定义的目录结构
-- 接口签名遵循 `04_SYSTEM_DESIGN/{system}.md` 的定义
-- 具体实现遵循任务描述和验收标准
-- Lint 通过（如有配置）
+- 代码结构遵循 `02_ARCHITECTURE_OVERVIEW.md` 定义的目录结构
+- 接口签名遵循 `04_SYSTEM_DESIGN/{system}.md` 的定义
+- 具体实现遵循任务描述和验收标准
+- Lint 通过（如有配置）
+
+> [!IMPORTANT]
+> **契约回流规则（CRITICAL）**：
+>
+> 如果实现过程中发现需要新增或修改以下任一“对外可观察契约”，而该契约未在当前任务或设计文档中显式定义：
+> - API / CLI 参数语义
+> - 配置结构 / 文件格式 / 状态格式
+> - 错误语义 / 返回结构
+> - 跨系统接口 / 持久化结构
+>
+> 则必须停止编码，生成最小回流说明，并跳转 `/change`。不得在 `/forge` 中偷偷补写这些契约。
 
 ---
 
@@ -283,28 +317,30 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 **根据任务的验证类型执行相应验证**，并按类型分类证据：
 
-> [!IMPORTANT]
-> **验证类型决定验证方式和证据要求**：
->
-> | 验证类型 | 验证方式 | 证据要求 | 标记 |
-> |---------|---------|---------|:----:|
-> | **单元测试** | 运行 `npm test` 或等效命令 | 终端输出：`X passed, 0 failed` | ✅/❌ |
-> | **集成测试** | 运行集成测试脚本 | 终端输出或日志 | ✅/❌ |
-> | **E2E测试** | 运行 E2E 测试脚本 | 测试报告或截图 | ✅/❌ |
-> | **编译检查** | 运行 `npm run build` 或等效命令 | 终端输出：`Build succeeded` | ✅/❌ |
-> | **Lint检查** | 运行 `npm run lint` 或等效命令 | 终端输出：`0 problems` | ✅/❌ |
-> | **手动验证** | 人工检查 | 用户确认 | ⏳ |
+> [!IMPORTANT]
+> **验证类型决定验证方式和证据要求**：
+>
+> | 验证类型 | 验证方式 | 证据要求 | 标记 |
+> |---------|---------|---------|:----:|
+> | **单元测试** | 运行 `npm test` 或等效命令 | 终端输出：`X passed, 0 failed` | ✅/❌ |
+> | **集成测试** | 运行集成测试脚本 | 终端输出或日志 | ✅/❌ |
+> | **E2E测试** | 运行 E2E 测试脚本 | 测试报告或截图 | ✅/❌ |
+> | **冒烟测试** | 运行最小真实路径检查 | 关键路径日志、截图或终端输出 | ✅/❌ |
+> | **回归测试** | 运行受影响能力的最小回归测试集 | 明确列出复验范围 + 测试输出 | ✅/❌ |
+> | **编译检查** | 运行 `npm run build` 或等效命令 | 终端输出：`Build succeeded` | ✅/❌ |
+> | **Lint检查** | 运行 `npm run lint` 或等效命令 | 终端输出：`0 problems` | ✅/❌ |
+> | **手动验证** | 人工检查 | 用户确认 | ⏳ |
 
 ```markdown
 ### ✅ 验证报告: T{X.Y.Z}
 
-**验证类型**: [单元测试 | 集成测试 | E2E测试 | 编译检查 | Lint检查 | 手动验证]
-
-**自动验证** (单元测试/集成测试/E2E/编译/Lint)：
-| 验收标准 | 命令 | 输出摘要 | 状态 |
-| -------- | ---- | -------- | :--: |
-| 测试通过 | `npm test` | 12 passed, 0 failed | ✅ |
-| 构建成功 | `npm run build` | Build succeeded | ✅ |
+**验证类型**: [单元测试 | 集成测试 | E2E测试 | 冒烟测试 | 回归测试 | 编译检查 | Lint检查 | 手动验证]
+
+**自动验证** (单元测试/集成测试/E2E/冒烟/回归/编译/Lint)：
+| 验收标准 | 命令 | 输出摘要 | 状态 |
+| -------- | ---- | -------- | :--: |
+| 测试通过 | `npm test` | 12 passed, 0 failed | ✅ |
+| 构建成功 | `npm run build` | Build succeeded | ✅ |
 
 **手动验证**：
 | 验收标准 | 说明 | 状态 |
@@ -312,15 +348,39 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 | 页面显示正确 | 需要打开浏览器确认渲染效果 | ⏳ |
 ```
 
-按任务的 `**验证类型**` 和 `**验证说明**` 字段执行检查。
-
-- 自动验证类型全部 ✅ 且无手动验证项 → 继续 3.5
-- 自动验证类型全部 ✅ 但有手动验证项 → 继续 3.5（手动项随后确认）
-- 自动验证类型有 ❌ → **修复后重新验证**，不得跳过
-
----
-
-### 3.5 遵从性检查 (Compliance Check)
+按任务的 `**验证类型**` 和 `**验证说明**` 字段执行检查。
+
+> [!IMPORTANT]
+> **冒烟测试与回归测试执行规则**：
+> - 冒烟测试必须验证少量真实关键路径是否可运行，不得退化成“跑一下已有脚本就算过”
+> - 回归测试必须显式写出本次复验覆盖了哪些既有能力，避免泛化成“随便跑点测试”
+> - 若任务声明了冒烟测试或回归测试，但 `验证说明` 无法指导执行，应视为验证定义不完整，先修任务定义或回流 `/change`
+
+- 自动验证类型全部 ✅ 且无手动验证项 → 继续 3.5
+- 自动验证类型全部 ✅ 但有手动验证项 → 先进入 **3.4.5 静态忠实度审查**，再继续 3.5（手动项随后确认）
+- 自动验证类型有 ❌ → **修复后重新验证**，不得跳过
+
+---
+
+### 3.4.5 静态忠实度审查 (Code Fidelity Check)
+
+**目标**: 在请求用户进行手动验证前，先用纯静态方式检查实现是否已经偏离契约与任务承诺。
+
+> [!IMPORTANT]
+> 当任务存在手动验证项，或本波次触及公共契约 / 基础共享逻辑 / 高风险变更时，应先运行 `code-reviewer`。
+>
+> **为什么？** 手动验证适合确认最终体验，但不该替代“实现是否忠于契约”的静态检查。AUTO 模式下尤其不能把这一步省掉。
+
+执行规则：
+- 调用 `code-reviewer`，输入当前工作目录 `src/` 与 `{TARGET_DIR}` 下的 PRD / Architecture / ADR / System Design / TASKS
+- 如 `code-reviewer` 发现 **Critical / High**：
+  - 若问题属于当前版本内可收敛的契约 / 任务 / 测试 / 回流缺口 → 停止并进入 `/change`
+  - 若问题已经触及需求前提 / 架构前提 / ADR 核心前提 → 停止并升级 `/genesis`
+- 如无高严重度阻塞 → 继续后续遵从性检查与手动验证交接
+
+---
+
+### 3.5 遵从性检查 (Compliance Check)
 
 **检查清单** (每条都要回答)：
 
@@ -330,9 +390,9 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 | 2   | 未引入 ADR 未批准的依赖？           |  ✅/❌   |
 | 3   | 未添加任务范围外的功能？            |  ✅/❌   |
 | 4   | 代码风格与项目一致，lint 通过？     |  ✅/❌   |
-| 5   | 所有验收标准已验证通过？            |  ✅/❌   |
-| 6   | 所有可执行验收标准有终端输出证据？  |  ✅/❌   |
-| 7   | 需人工确认的验收标准已标记 ⏳？      |  ✅/❌   |
+| 5   | 所有验收标准已验证通过？            |  ✅/❌   |
+| 6   | 所有可执行验收标准有足够证据（终端/日志/截图）？  |  ✅/❌   |
+| 7   | 需人工确认的验收标准已标记 ⏳？      |  ✅/❌   |
 
 - 全部 ✅ → 继续 3.6
 - 有 ❌ → **修复**
@@ -341,10 +401,10 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ### 3.6 提交 (Commit)
 
-1. **Git commit**：
-   - Task commit 一律落在**当前工作 branch** 上
-   - 默认当前工作 branch 为本次交付对应的 `feature/*`；只有 Step 0 明确判定为单文件小修时才允许留在 `main`
-   - 消息格式: `{type}({scope}): T{X.Y.Z} — 任务标题`
+1. **Git commit**：
+    - Task commit 一律落在**当前工作 branch** 上
+    - 默认当前工作 branch 为本次交付对应的 `feature/*`；只有 Step 0 明确判定为单文件小修时才允许留在 `main`
+    - 消息格式: `{type}({scope}): T{X.Y.Z} — 任务标题`
    - `type` ∈ `feat | fix | refactor | docs | test | chore`
    - `scope` 默认使用 `system-id`；workflow/skill 改动可用对应名称
    - 例: `feat(core): T2.1.1 — 地形与资源数据模型`
@@ -396,10 +456,11 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 **阻塞项** (如有): ...
 ```
 
-### 4.3 Git commit 状态更新
-
-- Wave settlement commit 与本波次 task commits 一样，落在当前工作 branch 上
-- 如下一波仍属于同一交付主题，默认继续沿用当前 `feature/*` branch
+### 4.3 Git commit 状态更新
+
+- Wave settlement commit 与本波次 task commits 一样，落在当前工作 branch 上
+- 如下一波仍属于同一交付主题，默认继续沿用当前 `feature/*` branch
+- `/change` 回流后恢复编码时，继续沿用当前 `feature/*` branch
 
 ```markdown
 chore(wave): settle wave {N} progress
@@ -407,11 +468,19 @@ chore(wave): settle wave {N} progress
 
 ### 4.4 下一步判定
 
-**人类检查点** ⚠️：
-
-- 还有未完成任务 → 询问用户："继续下一波？" → 回到 **Step 1**
-- 当前 Sprint 所有任务完成 → 进入 **Step 5**
-- 有阻塞问题 → 引导用户运行相应工作流修复
+**签名检查点** ⚠️：
+
+- 还有未完成任务 → 询问："继续下一波？"；普通模式等待用户签名，AUTO 模式以 `AUTO` 签名继续 → 回到 **Step 1**
+- 当前 Sprint 所有任务完成 → 进入 **Step 5**
+- 有阻塞问题 → 引导用户运行相应工作流修复
+
+> [!IMPORTANT]
+> **AUTO 模式的停止条件**：
+> - 命中手动验证且需要用户最终确认
+> - `/change` 评估后发现必须升级到 `/genesis`
+> - 其他工作流要求用户作出新的版本级决定
+>
+> 命中以上任一条件，AUTO 必须立即停止，等待用户批准。
 
 ---
 
@@ -423,14 +492,14 @@ chore(wave): settle wave {N} progress
 
 1. **集成验证**: 运行集成测试（如有），确保跨系统功能正常
 2. **更新 AGENTS.md**: 清除"当前波次"信息，更新已完成的 Sprint/Phase
-3. **Git 里程碑锚点**：
-   - Sprint/Phase 完成 → `milestone: {name} complete`
-   - 对应版本发布 → `release: vX.Y.Z`
-   - 如存在明确版本号，可打 tag：`vX.Y.Z`
-   - 以上里程碑 commit / tag 默认创建在当前工作 branch 上
-4. **合流主线**：
-   - 当前 feature branch 达到可验收里程碑后，合并回 `main`
-   - 合并策略遵循仓库既有规范（merge / squash / rebase），但 `main` 最终应指向该里程碑的稳定状态
+3. **Git 里程碑锚点**：
+   - `feature/*` 上可创建里程碑 settlement commit，用于标记该分支已达到可验收状态
+   - 版本 tag 与正式 release **只允许创建在 `main` 上**，不得提前打在 `feature/*` 分支上
+4. **合流主线**：
+   - 只有当当前 `feature/*` 分支已经达到可验收里程碑、相关验证已经通过，并且用户明确确认可以合流时，才允许合并回 `main`
+   - 合流策略统一固定为 **merge commit**
+   - 不使用 squash merge 或 rebase merge 作为主线合流方式
+   - `main` 最终只保存已验证通过、可视为稳定的状态
 5. **汇报用户**: 列出已完成的 Sprint/Phase 概要
 
 ---

package/templates/.agents/workflows/genesis.md

@@ -10,11 +10,12 @@ description: "从 0 到代码的项目启动全流程。适用于新项目立项
 **你的核心使命**：
 将用户模糊的想法转化为**清晰的文档基础**，完成从0到文档的全流程设计。
 
-**核心原则**：
-- **版本化架构** - 架构文档必须版本化 (`.anws/v1`, `.anws/v2`...)
-- **文档先行** - 代码是文档的实现，而非相反
-- **产品优先** - 先PRD后技术，先需求后方案
-- **系统拆解** - 识别独立系统，关注点分离
+**核心原则**：
+- **版本化架构** - 架构文档必须版本化 (`.anws/v1`, `.anws/v2`...)
+- **文档先行** - 代码是文档的实现，而非相反
+- **产品优先** - 先PRD后技术，先需求后方案
+- **系统拆解** - 识别独立系统，关注点分离
+- **Git 分支换轨** - `/genesis` 代表版本前提变化；旧 `feature/*` 应冻结，新版本应从最新 `main` 重新开一条新的 `feature/*`
 
 **Output Goal (Versioned)**:
 - `.anws/v{N}/00_MANIFEST.md` ← 版本元数据
@@ -26,9 +27,13 @@ description: "从 0 到代码的项目启动全流程。适用于新项目立项
 
 ---
 
-## 🚀 Pre-Check: 自动初始化 (Auto-Init)
-
-> **目的**: 确保项目已正确初始化，无 AGENTS.md 则自动创建。
+## 🚀 Pre-Check: 自动初始化 (Auto-Init)
+
+> **目的**: 确保项目已正确初始化，无 AGENTS.md 则自动创建。
+
+> [!IMPORTANT]
+> **Git 换轨前置规则**：
+> 如果 `/genesis` 是从一个正在开发中的 `feature/*` 分支升级而来，先冻结旧分支；必要时创建 checkpoint / freeze commit。随后从最新 `main` 重新开一条新的 `feature/*` 承接新版本，不要把旧分支上的实现和新版本文档混在一起。
 
 ### 自动检测流程