@haaaiawd/anws 2.2.3 → 2.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "2.2.3",
+  "version": "2.2.4",
   "description": "Anws — A spec-driven workflow framework for AI-assisted development. Empowers prompt engineers to build production-ready software through structured PRD → Architecture → Task decomposition. Works with Claude Code, GitHub Copilot, Cursor, Windsurf, and any tool that reads AGENTS.md.",
   "keywords": [
     "anws",

package/templates/.agents/skills/code-reviewer/SKILL.md

@@ -2,7 +2,7 @@
 
 ## name: code-reviewer
 
-description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD、ADR、系统设计与 05_TASKS，围绕契约闭合、任务兑现、架构健康、安全边界、验证证据与回流一致性产出可追溯结论；供 /challenge（CODE/FULL）与 /forge（3.4.5）共用。
+description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD、ADR、系统设计与 05_TASKS，围绕契约闭合、任务兑现、架构健康、安全边界、验证证据与回流一致性产出可追溯结论；供 /challenge（CODE/FULL）与 /forge（Step 1 §1.4 波前）共用。
 
 # Code Reviewer — 实现侧证据层
 
@@ -24,7 +24,7 @@ description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD
 ## 激活时机
 
 - `**/challenge`**：`REVIEW_MODE` = `CODE` / `FULL`，或从 design/task 审查**自适应升级**到实现侧。
-- `**/forge`**：Step **3.4.5** 提交前门禁（默认 **波次级频控**，见 `forge` workflow）。
+- `**/forge`**：**Step 1 §1.4 波前**门禁（默认**每新波一次**，进入 Step 2 之前；豁免与跳过见 `forge` workflow）。
 
 ## 执行形态（宿主能力）
 

package/templates/.agents/skills/e2e-testing-guide/SKILL.md

@@ -1,204 +1,136 @@
----
-name: e2e-testing-guide
-description: 为依赖浏览器或页面交互的任务生成真实用户视角的 E2E 验证清单，并在具备浏览器自动化能力且用户授权时执行页面验证、收集证据。
----
-
-# E2E Testing Guide
-
-> "不要测试组件存在，要测试用户能不能完成事情。"
-
-你是 **E2E 验证编排者**。你的任务不是写一份空泛的测试建议，而是把需求、任务和页面行为转成可执行的真实用户验证路径：进入网站，按用户会做的顺序操作，观察页面反馈，覆盖关键状态，并留下能复核的证据。
-
----
-
-## 触发条件
-
-当任务满足任一条件时使用本 skill：
-
-- `05_TASKS.md` 的验证类型包含 **E2E测试** 或 **手动验证**。
-- 改动影响浏览器页面、导航、表单、登录态、支付/提交/发布等用户流程。
-- 需求验收依赖真实页面状态，而不是单元测试或接口测试即可证明。
-- 用户明确要求“像真实用户一样测试”“进网站跑一遍”“浏览器验证”“截图验证”。
-
----
-
-## 硬约束
-
-- **真实用户优先**：测试步骤必须围绕用户目标组织，不要按组件或代码文件罗列。
-- **不假装已测**：没有实际打开页面、执行操作、观察结果，就只能写 `未执行`，不能写 `通过`。
-- **证据闭环**：每个已执行场景必须记录 URL、环境、账号/角色（若适用）、关键截图或可复现观察。
-- **先授权再操作**：需要登录、访问外部站点、提交数据、删除/发布/支付等有副作用动作时，先向用户确认。
-- **不碰不可逆动作**：删除、付款、发送真实通知、发布到生产等动作默认停在确认页；除非用户明确授权。
-- **失败也算结果**：失败要记录实际现象、期望现象、复现步骤和疑似原因，不要把失败折叠成“需进一步测试”。
-
----
-
-## 工作流程
-
-### 1. 读取上下文
-
-优先读取这些材料：
-
-1. 当前任务说明或 `05_TASKS.md` 中对应任务。
-2. 相关 PRD / 验收标准 / 用户故事。
-3. 影响的页面、路由、组件、接口和状态管理代码。
-4. 已有测试、seed 数据、开发启动方式、环境变量说明。
-
-如果缺少页面 URL、启动命令、测试账号或目标用户角色，先列为阻塞项并向用户询问。
-
-### 2. 建立用户旅程清单
-
-按用户目标产出测试清单，每条都必须能被浏览器操作验证：
-
-```text
-Journey J1: 用户完成核心目标
-  角色: 未登录访客 / 普通用户 / 管理员 / 其他
-  起点: URL 或入口页面
-  目标: 用户想完成的事情
-  数据: 需要输入或预置的数据
-  步骤: 真实点击、输入、等待、确认顺序
-  期望: 页面可见反馈、URL 变化、状态变化、数据持久化
-  证据: 截图 / URL / 控制台 / 网络请求 / 数据库观察
-```
-
-至少覆盖：
-
-- **核心成功路径**：用户能完成最主要的业务目标。
-- **首次进入路径**：空状态、未登录、无数据、默认配置。
-- **错误路径**：无效输入、权限不足、网络/API 失败、服务端校验错误。
-- **边界路径**：最小/最大输入、重复提交、刷新页面、返回上一页、多标签或重复操作。
-- **响应式路径**：桌面宽度和一个移动宽度；如果产品只支持桌面，要明确写出。
-- **可访问性基本路径**：键盘可达、焦点可见、按钮/表单有可理解名称。
-
-### 3. 生成执行计划
-
-在执行前输出一份短计划：
-
-```markdown
-## E2E Plan
-
-- Target: <站点 URL / 本地地址>
-- Environment: <dev/staging/prod-like>
-- Browser: <浏览器/设备尺寸>
-- Roles: <用户角色>
-- Data Setup: <需要准备的数据>
-- Journeys: J1, J2, J3...
-- Side Effects: <是否会创建/修改/删除数据>
-- Blockers: <缺失信息>
-```
-
-若具备浏览器自动化工具且没有阻塞项，询问或确认用户授权后再执行。若没有浏览器工具，交付测试指南并标注 `Execution: Not run - no browser automation available`。
-
-### 4. 浏览器执行协议
-
-执行时要像真实用户一样操作：
-
-1. 打开目标 URL，记录初始页面和环境。
-2. 从页面可见入口开始，不要直接调用内部 API 伪造状态。
-3. 点击真实按钮/链接，填写真实表单，等待页面反馈。
-4. 每次页面结构变化后重新观察页面，再继续下一步。
-5. 同时关注：
-  - URL / 路由是否符合预期。
-  - 页面文案和视觉状态是否让用户知道发生了什么。
-  - 表单校验是否清晰。
-  - 加载、空状态、错误状态是否可恢复。
-  - 控制台是否出现错误。
-  - 关键网络请求是否成功，失败时 UI 是否正确处理。
-6. 对高风险动作停在确认步骤，记录“未执行原因”和用户授权需求。
-
-### 5. 结果判定
-
-每个 Journey 只能使用这些状态：
-
-- `PASS`：实际执行，结果符合预期，并有证据。
-- `FAIL`：实际执行，结果不符合预期，并有复现步骤。
-- `BLOCKED`：因登录、权限、缺数据、环境不可用或需人工授权无法执行。
-- `NOT RUN`：未执行。必须说明原因，不能混同为通过。
-
----
-
-## 输出格式
-
-最终输出必须包含：
-
-```markdown
-## E2E Verification
-
-### Scope
-- Target:
-- Environment:
-- Browser / Viewport:
-- User Role:
-- Build / Commit:
-
-### Checklist
-| ID | User Journey | Status | Evidence | Notes |
-|---|---|---|---|---|
-| J1 | <用户目标> | PASS/FAIL/BLOCKED/NOT RUN | <截图/URL/日志> | <关键观察> |
-
-### Findings
-- [HIGH/MEDIUM/LOW] <问题标题>
-  - Expected:
-  - Actual:
-  - Repro:
-  - Evidence:
-  - Suggested Fix:
-
-### Coverage Gaps
-- <未覆盖路径及原因>
-
-### Recommendation
-- <是否可以合并/发布/需要修复后重测>
-```
-
-如果没有发现问题，也要明确写：
-
-```text
-No E2E issues found in executed journeys. Remaining risk: <未覆盖范围>.
-```
-
----
-
-## 常用 Journey 模板
-
-### 登录/认证
-
-- 访客进入受保护页面会被引导登录。
-- 正确账号能登录并回到原目标页。
-- 错误密码、空字段、过期会话有清晰提示。
-- 刷新页面后登录态保持或按设计失效。
-- 退出登录后不能通过返回按钮看到受保护内容。
-
-### 表单/提交
-
-- 用户能从入口找到表单并完成提交。
-- 必填、格式、长度、重复提交都有反馈。
-- 提交成功后页面给出明确结果，并能继续下一步。
-- 提交失败时用户输入不应无故丢失。
-
-### 列表/搜索/筛选
-
-- 空状态、加载状态、有数据状态都可理解。
-- 搜索、筛选、排序、分页能组合使用。
-- 刷新或复制 URL 后关键查询状态按设计保留。
-- 没有结果时提供恢复路径。
-
-### 创建/编辑/删除
-
-- 创建后能在列表或详情页看到新数据。
-- 编辑后数据持久化，刷新后仍正确。
-- 删除类动作必须有确认；未授权时停在确认前。
-- 取消操作不会产生副作用。
-
-### 导航/布局
-
-- 主要入口可发现，面包屑/返回路径合理。
-- 深链可直接打开。
-- 浏览器返回/前进不破坏状态。
-- 桌面和移动视口下关键操作不被遮挡。
-
----
-
-## 质量标准
-
-好的 E2E 指南看起来应该像一名认真测试人员的操作记录：有目标、有路径、有证据、有判断。坏的指南只会写“测试登录、测试提交、测试页面显示”。那种不行。
+---
+
+## name: e2e-testing-guide
+description: 规定如何撰写面向真人的 E2E / 手动验证《测试指南》及《E2E Verification》报告格式（PRD 对照、功能面、旅程与步骤）；不含实机浏览器编排——实机顺序由 `/forge` §3.4.6 写死。
+
+# E2E Testing Guide
+
+本 skill **只解决两件事**：（1）**怎么写**可执行的 E2E / 手动验证**测试指南**；（2）**报告长什么样**（含评测列）。**是否在浏览器里按指南操作**，由 `**/forge` §3.4.6** 统一编排：先按本 skill 产出报告，再在用户授权下使用宿主浏览器工具回填证据。
+
+> 原则：像真人逛产品一样写清「从哪进、点哪、期望看到什么」；每一项应对得上 **PRD / 验收** 里的可追溯条目。
+
+### 测试指南要像人类那样写（必遵）
+
+写《测试指南》时，**默认读者是第一次用产品的人**，不是跑脚本的 QA 自动化。指南里必须能还原：
+
+1. **真入口**：从用户会用的入口进（首页、深链、邮件里的链接等），**不要**默认从 Storybook/内部调试页写起，除非任务写明允许。
+2. **先「看」再「动」**：每一步前先写「此刻屏幕上应看到什么」（标题、主导航、空态文案），再写要点哪里；禁止「未描述界面就连续点下一步」。
+3. **走完整壳**：顶栏/侧栏/用户菜单/设置/帮助/面包屑/返回等，**人类会乱点的入口**都要在 **Surface coverage** 或 **Journey** 里出现一次，或进 **Coverage gaps** 写原因。
+4. **扫遍范围内可用能力**：每个叶子屏上的 **主 CTA + 明显次要操作**（更多菜单、行内按钮、tabs）在指南里至少有一条对应 **Step**；**不要**只写一条 happy path 就结束。
+5. **人类常用组合**：至少规划筛选+排序+分页、刷新、后退、复制 URL 再打开、Tab 键能走到主按钮等（按产品实际取舍，不写的要进 **Coverage gaps**）。
+6. **数据形态**：列表/表格写清「空一条 / 有一条 / 多条」时分别期望看到什么（能准备数据则写准备方式；不能则写 **Blockers**）。
+
+---
+
+## 触发条件
+
+- `05_TASKS.md` 含 **E2E测试** 或 **手动验证**；或改动影响页面/导航/表单/登录等需真机感受的路径。
+- 用户要求「写测试指南」「E2E 报告」「浏览器验证清单」等。
+
+---
+
+## 硬约束
+
+- **PRD / 验收可追溯**：表格与步骤须能对应到 **PRD 锚点** 或 **任务验收条目**；无 PRD 时在 Scope 声明「准 PRD」来源。
+- **人类式覆盖（写在指南里）**：须落实上一节 **《测试指南要像人类那样写》**；导航、空状态、次要入口、主/次 CTA、tabs、行内操作等**在范围内**的能力，须在 **Surface coverage** 或 **Journey/Step** 中出现；刻意不测的写在 **Coverage gaps**。
+- **不编造执行结果**：指南可以「未执行」列留空或写「待实机」；**不得**在未实机时把结论写成 `PASS`。
+- **证据列留给实机**：URL、截图、日志等由 `/forge` 浏览器阶段填写；指南阶段写清「应采集何种证据」即可。
+- **副作用**：指南中须标注哪些步骤需用户事先授权（登录、写库、支付等）。
+
+---
+
+## 撰写流程（仅文档）
+
+### 1. 读取上下文
+
+任务与 `05_TASKS.md`、`01_PRD.md`（或 `**输入`** 指向的需求）、相关路由/页面说明、启动方式、账号与角色；缺 URL/账号等写入 **Blockers**。
+
+### 2. PRD 对照表（RTM）
+
+
+| PRD 引用 | 需求摘要 | 优先级 P0/P1/P2 | 将落在哪些 Journey |
+| ------ | ---- | ------------ | ------------- |
+
+
+无 PRD 时第一列用 **任务验收 T-x**，并在 Scope 说明。
+
+### 3. 功能面清单（Surface）
+
+按 **「人类会先看到什么、再点哪里」** 枚举；**禁止**只列路由名而不写「用户怎么发现这个入口」。
+
+
+| 功能面 / 入口 | 用户如何发现 | 映射 Journey | PRD 引用 |
+| -------- | ------ | ---------- | ------ |
+
+
+### 4. 旅程与分项步骤
+
+每条 Journey 含 PRD、角色、起点、目标；**Step 顺序 = 人类实际操作顺序**。每步固定写三句：**（1）读屏预期（2）动作（3）可观察结果 + 应采集的证据类型**（如「整页截图」「某接口 200」）。
+
+须覆盖：核心成功、冷启动/空态、典型错误、简单边界（刷新/后退/深链）、至少一种视口（若产品声明仅桌面则写明）。
+
+### 5. 执行计划（可选短文）
+
+`Target` / `Environment` / `Role` / `Data setup` / `Side effects` / `Blockers` 一段即可。**不写**浏览器点击协议——实机见 `**/forge` §3.4.6**。
+
+---
+
+## 输出格式（Required output）
+
+以下 Markdown **原样作为报告骨架**；表头与章节名不要随意删。撰写时假定执行者是 **第一次打开产品的真人**，Surface / Journey / Step 须能体现 **「像人类那样」** 的探索顺序（见上文必遵节）。
+
+
+
+```markdown
+## E2E Verification
+
+### Scope
+- PRD / 需求来源:
+- Target:
+- Environment:
+- Browser / Viewport（计划）:
+- User Role:
+- Build / Commit:
+
+### PRD traceability (RTM)
+| PRD ref | Summary | Priority | Journeys |
+| --- | --- | --- | --- |
+
+### Surface coverage
+| 功能面 / 入口 | 如何发现 | Journey | PRD ref | Notes |
+| --- | --- | --- | --- | --- |
+
+### Journeys（旅程级）
+| ID | PRD ref | User Journey | 旅程结果 | Evidence | Notes |
+| --- | --- | --- | --- | --- | --- |
+
+### Step breakdown
+| Journey | Step | PRD ref | Step 结果 | Evidence | Notes |
+| --- | --- | --- | --- | --- | --- |
+
+### Findings
+- [HIGH/MEDIUM/LOW] 标题
+  - PRD ref:
+  - Expected / Actual / Repro / Evidence / Suggested fix:
+
+### Coverage gaps
+- 未写入旅程或未计划实机的范围及原因
+
+### Recommendation
+- 是否建议合并/发布/先修再测（基于指南与已知实机结果；若尚未实机须写明）
+```
+
+---
+
+## 片段模板（可裁剪进 Journey）
+
+- **登录**：访客进受保护页 → 登录成功/失败/空字段/会话过期提示。
+- **表单**：必填与校验、成功反馈、失败不丢已填。
+- **列表**：空/加载/有数据、筛选排序分页、无结果恢复路径。
+- **导航**：主导航、返回、深链、关键操作不被遮挡。
+
+---
+
+## 质量标准
+
+读者拿到指南就能**不读代码**、**像第一次用产品的人那样**按顺序走完全部范围内能力；且每条能对上 PRD/验收。**Surface 清单与 Journey 步骤不得两张皮**。

package/templates/.agents/workflows/change.md

@@ -37,26 +37,26 @@
 >
 > | 能力                                                       | 允许  | 禁止  |
 > | -------------------------------------------------------- | --- | --- |
-> | 修改已有任务的描述                                                | 是 | |
-> | 修改已有任务的验收标准                                              | 是 | |
-> | 调整已有任务的估时                                                | 是 | |
-> | 标记任务阻塞/重分优先级                                             | 是 | |
-> | 微调 `04_SYSTEM_DESIGN/` 中已有文件的细节                          | 是 | |
-> | 修改当前版本中的普通文档/设计文件细节                                      | 是 | |
-> | 修改 `01_PRD.md` 中**不改变需求前提**的表达/命名/澄清内容                   | 是 | |
-> | 修改 `02_ARCHITECTURE_OVERVIEW.md` 中**不改变架构前提**的表达/命名/澄清内容 | 是 | |
-> | 修改 `03_ADR/` 中**不改变 ADR 核心决策前提**的接口、命名、契约补全或澄清内容         | 是 | |
-> | 为承接当前版本内变更创建少量必要文档文件                                     | 是 | |
-> | 为承接已明确请求的局部修订而补充少量必要任务                                   | 是 | |
-> | 更新任务说明字段，但不改变完成状态                                        | 是 | |
-> | 调整任务编排、Sprint/Wave 内排序（不改变 ADR 前提）                       | 是 | |
-> | **回填 `05_TASKS.md` checkbox**                            | | 是 |
-> | **添加 AI 自认为好的功能**                                        | | 是 |
-> | **修改 [REQ-XXX] 需求引用**                                    | | 是 |
-> | **改变需求目标、用户故事集合或需求边界**                                   | | 是 |
-> | **改变系统边界、跨系统架构基线或关键执行模型**                                | | 是 |
-> | **推翻 ADR 的核心决策前提**                                       | | 是 |
-> | **让当前 `05_TASKS.md` 整体失效、必须整体重建任务树**                     | | 是 |
+> | 修改已有任务的描述                                                | 是 | |
+> | 修改已有任务的验收标准                                              | 是 | |
+> | 调整已有任务的估时                                                | 是 | |
+> | 标记任务阻塞/重分优先级                                             | 是 | |
+> | 微调 `04_SYSTEM_DESIGN/` 中已有文件的细节                          | 是 | |
+> | 修改当前版本中的普通文档/设计文件细节                                      | 是 | |
+> | 修改 `01_PRD.md` 中**不改变需求前提**的表达/命名/澄清内容                   | 是 | |
+> | 修改 `02_ARCHITECTURE_OVERVIEW.md` 中**不改变架构前提**的表达/命名/澄清内容 | 是 | |
+> | 修改 `03_ADR/` 中**不改变 ADR 核心决策前提**的接口、命名、契约补全或澄清内容         | 是 | |
+> | 为承接当前版本内变更创建少量必要文档文件                                     | 是 | |
+> | 为承接已明确请求的局部修订而补充少量必要任务                                   | 是 | |
+> | 更新任务说明字段，但不改变完成状态                                        | 是 | |
+> | 调整任务编排、Sprint/Wave 内排序（不改变 ADR 前提）                       | 是 | |
+> | **回填 `05_TASKS.md` checkbox**                            | | 是 |
+> | **添加 AI 自认为好的功能**                                        | | 是 |
+> | **修改 [REQ-XXX] 需求引用**                                    | | 是 |
+> | **改变需求目标、用户故事集合或需求边界**                                   | | 是 |
+> | **改变系统边界、跨系统架构基线或关键执行模型**                                | | 是 |
+> | **推翻 ADR 的核心决策前提**                                       | | 是 |
+> | **让当前 `05_TASKS.md` 整体失效、必须整体重建任务树**                     | | 是 |
 >
 >
 > **一旦命中禁止项 → 当前版本无法继续承接，升级到 `/genesis`。**

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

@@ -27,7 +27,7 @@
 - **文档即合约** — 规范文档是不可违反的权威
 - **波次执行** — 每波 2-5 个任务，加载→编码→验证→提交
 - **遇疑则停** — 发现问题立即停止，不猜不赶
-- **签名机制** — 每次波次开始都要经过检查点；普通模式由用户签名，`/forge自动` 模式记为 `AUTO`
+- **签名机制** — 每次波次开始都要经过检查点；**普通模式**下须用户**逐波批准**任务组合后方可编码，`/forge自动` 模式以 `AUTO` 代签连续推进（见 Step 1 **模式边界**）
 
 **与用户的关系**：
 你是用户的**忠实执行者**，不是自由发挥的创造者。
@@ -37,23 +37,23 @@
 ## CRITICAL 权限边界
 
 > [!IMPORTANT]
-> **`/forge` 的权限严格限定**:
+> `**/forge` 的权限严格限定**:
 >
 >
 > | 能力                          | 允许  | 禁止  |
 > | --------------------------- | --- | --- |
-> | 在 `src/` 下编写业务代码            | 是 | |
-> | 编写单元测试                      | 是 | |
-> | 更新 `05_TASKS.md` 的 checkbox | 是 | |
-> | 运行测试和 lint                  | 是 | |
-> | Git commit 已完成的任务           | 是 | |
-> | 更新 `AGENTS.md` 当前状态         | 是 | |
-> | **修改 `.anws/` 下任何设计文档**     | | 是 |
-> | **创建 TASKS.md 中不存在的功能**     | | 是 |
-> | **降级或跳过验收标准**               | | 是 |
-> | **引入 ADR 未批准的第三方依赖**        | | 是 |
-> | **修改已有代码的公共接口（除非任务明确要求）**   | | 是 |
-> | **"顺便"优化/重构不在任务范围内的代码**     | | 是 |
+> | 在 `src/` 下编写业务代码            | 是   |     |
+> | 编写单元测试                      | 是   |     |
+> | 更新 `05_TASKS.md` 的 checkbox | 是   |     |
+> | 运行测试和 lint                  | 是   |     |
+> | Git commit 已完成的任务           | 是   |     |
+> | 更新 `AGENTS.md` 当前状态         | 是   |     |
+> | **修改 `.anws/` 下任何设计文档**     |     | 是   |
+> | **创建 TASKS.md 中不存在的功能**     |     | 是   |
+> | **降级或跳过验收标准**               |     | 是   |
+> | **引入 ADR 未批准的第三方依赖**        |     | 是   |
+> | **修改已有代码的公共接口（除非任务明确要求）**   |     | 是   |
+> | **"顺便"优化/重构不在任务范围内的代码**     |     | 是   |
 >
 
 ---
@@ -78,15 +78,15 @@
 > **以下情况必须立即停止编码，报告用户**:
 >
 >
-> | 冲突类型                   | 处理方式                                |
-> | ---------------------- | ----------------------------------- |
-> | 文档之间互相矛盾               |  停止 → 列出矛盾点 → 用户通过 `/change` 修复   |
-> | 任务描述模糊/不完整             |  停止 → 列出疑问 → 用户确认或通过 `/change` 补充 |
-> | 依赖的前置任务产物与预期不符         |  停止 → 报告差异 → 用户决定                 |
-> | 发现设计不可实现               |  停止 → 记录原因 → 建议用户运行 `/challenge`  |
-> | 需要 ADR 未批准的新依赖         |  停止 → 说明理由 → 用户决定是否创建新 ADR        |
-> | 需要的系统设计文档不存在           |  停止 → 引导用户运行 `/design-system`     |
-> | **发现未定义但必须新增/修改的公共契约** |  停止 → 生成回流说明 → 跳转 `/change`       |
+> | 冲突类型                   | 处理方式                             |
+> | ---------------------- | -------------------------------- |
+> | 文档之间互相矛盾               | 停止 → 列出矛盾点 → 用户通过 `/change` 修复   |
+> | 任务描述模糊/不完整             | 停止 → 列出疑问 → 用户确认或通过 `/change` 补充 |
+> | 依赖的前置任务产物与预期不符         | 停止 → 报告差异 → 用户决定                 |
+> | 发现设计不可实现               | 停止 → 记录原因 → 建议用户运行 `/challenge`  |
+> | 需要 ADR 未批准的新依赖         | 停止 → 说明理由 → 用户决定是否创建新 ADR        |
+> | 需要的系统设计文档不存在           | 停止 → 引导用户运行 `/design-system`     |
+> | **发现未定义但必须新增/修改的公共契约** | 停止 → 生成回流说明 → 跳转 `/change`       |
 >
 >
 > **核心原则: 宁可停下来问，也不要猜测。**
@@ -109,11 +109,7 @@
   - `{TARGET_DIR}/04_SYSTEM_DESIGN/` 存在且非空
   - 如缺失: " 建议先运行 `/design-system`。缺少详细设计可能导致实现质量下降。"
 5. **如果必需文件缺失**: 报错并提示运行 `/genesis` + `/blueprint`。
-6. **Challenge 门禁检查**:
-  - 如果 `{TARGET_DIR}/07_CHALLENGE_REPORT.md` 存在，必须先读取最新审查结果
-  - 如存在**未处理 Critical** → **立即阻塞**，不得进入 `/forge`
-  - 如存在**未处理 High** → 仅允许用户显式签名放行；AUTO 模式不得自动通过
-  - 如无未处理高严重度问题 → 继续
+6. **`07_CHALLENGE_REPORT.md`（若存在）**：先读结论；有未闭环 **Critical** → **停止**，不得进入本工作流后续编码步骤；有未闭环 **High** → 仅用户显式放行（AUTO 不可替代）；其余继续。门禁语义与 **`/challenge`** 一致，**不在此重复展开**。
 7. **断点续做判定**:
   - 读取 `AGENTS.md` 的 `Wave` 块
     - 如果存在波次信息：
@@ -133,12 +129,15 @@
     - 如当前已在 `feature/`* 且仍属于同一交付主题 → 继续在当前 branch 上推进，不因补任务、补契约、补测试而反复新开分支
     - 如当前已在 `feature/`* 且主题未变，即使经历 `/change` 回流，也继续使用同一条分支
     - 只有 `/genesis` 触发、版本前提变化时，旧 `feature/`* 才冻结；新版本应从最新 `main` 重新开一条新的 `feature/`*
-    - 如进入 `/change` 前需要保护点，可先在当前 `feature/*` 上创建 checkpoint commit：`checkpoint: before {topic}`
+    - 如进入 `/change` 前需要保护点，可先在当前 `feature/`* 上创建 checkpoint commit：`checkpoint: before {topic}`
 
 > [!IMPORTANT]
 > **Git 判断口诀**：
 > 同主题就不换分支，`/change` 不换分支，`/genesis` 才换分支；开发都在 `feature/`*，稳定结果才进 `main`，tag 只打 `main`。
 
+> [!IMPORTANT]
+> **AUTO 与在场性**：一旦判定为 **AUTO 模式**，默认用户**可能不在屏幕前**（喝咖啡、休息等）。除 **Step 0** 中 **`07_CHALLENGE_REPORT` Critical 未闭环**、**§1.4 波前 `code-reviewer` 硬阻塞**、任务 **手动验证**须用户终局确认、以及 **Step 4.4「AUTO 必须停下」** 所列情形外，**不要**再就「是否确认本波任务组合」「是否继续下一波」等向用户发问；展示 Wave 建议后以 **`AUTO`** 假名签署并顺序执行 **§1.4 → Step 2**。需要人类随队微调波次请用**普通模式**。
+
 ---
 
 ## Step 1: 波次规划 (Wave Planning)
@@ -146,9 +145,12 @@
 **目标**: 从任务清单中挑选一组可执行的任务，组成一个"波次"。
 
 > [!IMPORTANT]
-> **你不能自己决定波次内容，必须在检查点获得签名后再开始。**
+> **模式边界（CRITICAL）**
+>
+> - **普通模式（默认）**：与既有协议一致——**每一波**在 Step 1 **展示 Wave 建议 → 用户确认并批准本波任务组合（签名）→** 再写入 `AGENTS.md` 的 `Wave` 块、执行 **§1.4**；Step 4 结算后若仍有未完成任务，**下一波**仍须回到 Step 1 **再次**展示并**等待用户批准**，不得在未经批准时开工下一波。Step 4.4 的「不问是否继续」**仅适用于 AUTO**，**不**削弱普通模式的逐波批准权。
+> - **AUTO 模式**（`/forge自动` 或用户明确要求自动连续推进）：检查点逻辑仍在，但签名人记为 `AUTO`；**不得**为「波次是否满意」「是否继续下一波」发起闲聊式确认（见 **Step 0「AUTO 与在场性」**、**Step 4.4**）。
 >
-> **为什么？** 用户对项目优先级和进度节奏有最终决定权；`/forge自动` 只是把签名从用户改为 `AUTO`，不是删除检查点。
+> **为什么？** 优先级与任务边界须可审计；普通模式由人**逐波把关**，AUTO 则由硬性停止条件顶替「人在场」的口头确认。
 
 ### 1.1 扫描可执行任务
 
@@ -194,18 +196,35 @@
 T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 ```
 
-然后进入 Step 2。
+签名规则（与 **模式边界** 一致）：
+
+- **普通模式** → 用户**明示批准**本波 Wave（可对任务组合提出调整，定稿后再签）→ 写入 `AGENTS.md` `Wave` 块 → 再执行 **§1.4**。**禁止**在用户未批准前写入 Wave 或进入 Step 2/3。
+- **AUTO 模式** → 展示 Wave 建议后**立即**将本波记为 `AUTO` 签入并执行 **§1.4**（**不得**为「确认组合是否满意」再打断用户）。
+
+### 1.4 波前静态审查（`code-reviewer`，默认每波）
+
+**时机**：`AGENTS.md` 的 **Wave {N}** 已写入且 **Step 1 签名**已达成之后，**进入 Step 2 之前**。
+
+**断点续做**：Step 0 若判定**同一波**未收官、直接进入 Step 3，视为该波已在当时完成 Step 1 批准；**不**对同一波重复 §1.4。若无法从 Wave 备注 / 会话记录确认本波曾完成 §1.4（须有一次审查产出或合法豁免），**回到 Step 1** 补办本波签名与 §1.4，再进入 Step 2/3。
+
+**默认**：每一**新**波次（含普通模式下用户刚批准的下一波）都必须执行一轮 **`code-reviewer`**，审查对象为 **截至本波开始前、当前工作分支上已 commit 的实现**（相对 `{TARGET_DIR}` 下 PRD / Architecture / ADR / System Design / **`05_TASKS.md`**，含本波将执行任务之契约边界），避免带着错误假设进入编码。
+
+**仅以下情形可跳过（须写明原因，写入 Wave 备注或等同持久位）**：
+
+1. **无可审实现**：业务实现根（如 `src/`，以项目约定为准）上**尚无可审查的、与本 Sprint / 本波相关的已落地代码**（纯初始化、仅文档、尚未开工）— **不做**形式主义空跑。
+2. **用户明确全域禁止 static review**：用户**明示**「不做 code review / 跳过一切 `code-reviewer`」— 本会话内后续各波均不再调用 **`code-reviewer`**，直接进 **Step 2**；须在 **`AGENTS.md`** 或 Wave 侧标注 **`CODE_REVIEW_DISABLED_BY_USER`**，直至用户声明撤销。**未**收到明示前 **禁止** AI 自行省略波审。
 
-签名规则：
+**执行**：完整遵从 **`code-reviewer`** skill；宿主有子代理时 **优先**委派。
 
-- 普通模式 → 等待用户签名
-- AUTO 模式 → 保留波次展示，并将签名记为 `AUTO` 后继续执行
+**门禁路由**：Critical / High 按 skill 走 **`/change`** / **`/genesis`**；未解决 blocking 前 **不得** 进入 Step 2（**含 AUTO**，遇此类必须停下）。
+
+然后进入 **Step 2**。
 
 ---
 
 ## Step 2: 上下文加载 (Context Loading)
 
-**目标**: 按需加载本波次需要的文档，不多加载一份。
+**目标**: 按需加载本波次需要的文档，不多加载一份。**前提**：**§1.4** 已完成或可合法豁免（见上）；否则不得加载开工。
 
 > [!IMPORTANT]
 > **只加载当前波次需要的文档。不要"以防万一"多加载。**
@@ -245,12 +264,24 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 ## Step 3: 任务执行循环 (Task Execution Loop)
 
-**目标**: 逐个完成波次内的任务：思考→编码→验证→提交。
+**目标**: 逐个完成波次内任务（思考→编码→验证→提交）。
 
 > [!IMPORTANT]
 > **严格按以下流程执行每个任务，不跳步。**
 
-对本波次中的每个任务，执行以下循环：
+### Wave 内建结构（Wave = 波前门 + 任务循环）
+
+把 **一次 Wave** 视为 **波前静态门 + 逐任务循环**（Step 3 仅承载后者；**未完成不得进入 Step 4**）：
+
+
+| 阶段                                 | 内容                                                                             | 完成判据                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| **0. 波前（`code-reviewer`）**          | **Step 1 签名之后、Step 2 之前**；见 **§1.4**                                        | 审查产出可追溯，或 **`code-reviewer`** skill 下的**合法豁免**已落盘；不得无声跳过 |
+| **A. 逐任务循环**                       | 对本波每个任务依次执行 **§3.1 → §3.6**（**末任务**在 §3.4 后走 **§3.4.6**）                 | 每个任务的验收、验证证据与 commit 已落地；`05_TASKS.md` 已按规则回写                           |
+
+> **一句**：**§1.4** 与 **Step 4 §4.0** 对齐（波前已完成或可豁免）。
+
+对本波次中的每个任务，执行以下循环（阶段 A）：
 
 ---
 
@@ -327,8 +358,8 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 > **验证类型决定验证方式和证据要求**：
 >
 >
-> | 验证类型       | 验证方式                     | 证据要求                      | 标记  |
-> | ---------- | ------------------------ | ------------------------- | --- |
+> | 验证类型       | 验证方式                     | 证据要求                      | 标记     |
+> | ---------- | ------------------------ | ------------------------- | ------ |
 > | **单元测试**   | 运行 `npm test` 或等效命令      | 终端输出：`X passed, 0 failed` | 通过/未通过 |
 > | **集成测试**   | 运行集成测试脚本                 | 终端输出或日志                   | 通过/未通过 |
 > | **E2E测试**  | 运行 E2E 测试脚本              | 测试报告或截图                   | 通过/未通过 |
@@ -336,7 +367,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 > | **回归测试**   | 运行受影响能力的最小回归测试集          | 明确列出复验范围 + 测试输出           | 通过/未通过 |
 > | **编译检查**   | 运行 `npm run build` 或等效命令 | 终端输出：`Build succeeded`    | 通过/未通过 |
 > | **Lint检查** | 运行 `npm run lint` 或等效命令  | 终端输出：`0 problems`         | 通过/未通过 |
-> | **手动验证**   | 人工检查                     | 用户确认                      | 待确认 |
+> | **手动验证**   | 人工检查                     | 用户确认                      | 待确认    |
 >
 
 ```markdown
@@ -366,49 +397,20 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 > - 若任务声明了冒烟测试或回归测试，但 `验证说明` 无法指导执行，应视为验证定义不完整，先修任务定义或回流 `/change`
 
 - 若任一自动验证类型未通过 → **修复后重新验证**，不得跳过
-- 若全部自动验证类型通过 → 按下方 **「3.4.5 / 3.4.6 频控」** 决定是否在本任务执行 **3.4.5 / 3.4.6**，然后进入 **3.5 → 3.6**。跳过或顺延须在任务备注 / Wave 记录中写明依据（与对应 **skill** 的跳过协议一致）。
-
-### 3.4.5 / 3.4.6 频控（默认）
-
-> [!IMPORTANT]
-> **`code-reviewer`（3.4.5）默认不在每个任务后强制执行**（避免噪声与上下文浪费）。**`e2e-testing-guide`（3.4.6）** 的触发与 **3.4.5 频控相互独立** — UI/E2E 类任务只要 skill 触发就应执行 3.4.6，即使不是 Wave 最后一个任务。
->
-> **3.4.5（`code-reviewer`）默认节奏**：
->
-> - **主路径**：在本 **Wave** 的 **最后一个任务** 完成 3.4 的自动验证后，集中执行 **一次** 3.4.5（审查范围为本 Wave 已落地变更）。
-> - **Wave 内较早的任务**：通常 **跳过** 3.4.5，直接进入 **3.5 → 3.6**；若跳过，在任务或 Wave 备注标注依据（如 `3.4.5 deferred — wave cadence`）。
-> - **兜底**：若已连续 **约 2～3 个 Wave** 未执行 3.4.5，应在下一 Wave **Step 1** 之前或上一 Wave **Step 4** 末尾 **补跑一次**（范围与证据见 skill）。
-> - **例外**（可改为本任务后立即跑 3.4.5）：任务/用户显式要求 **逐任务静态审查**；**公共契约高风险**；**`/forge自动` 长会话**需加密审查 — 仍须服从 **`code-reviewer` skill** 的跳过/加密协议。
->
-> **3.4.6（`e2e-testing-guide`）与浏览器工具**：
->
-> - 未触发 skill → 跳过 + 一行原因 → **3.5**。
-> - **具备浏览器自动化能力时**：按 skill — **先** 产出/对齐 Testing Guide，**再在用户授权下** 执行真实浏览器步骤。
-> - **无浏览器工具**：**guide-only**，不得在无证据时声称 E2E/冒烟已通过。
-
----
-
-### 3.4.5 静态忠实度审查 (Code Fidelity Check)
-
-（按频控：本任务执行；或顺延至 Wave 最后一个任务 / 兜底补跑 — 见上。）
+- 若全部自动验证类型通过：
+  - **非本波最后一个任务** → **3.5 → 3.6**（不在此执行 **§3.4.6**）。
+  - **本波最后一个任务** → **§3.4.6（见下）** → **3.5 → 3.6**。
 
-完整遵从 `**code-reviewer`** skill（输入、Lens、输出、跳过协议均以 skill 为准）。
+### 3.4.6 波末 E2E（写死：`e2e-testing-guide` → 浏览器）
 
-**执行方式**：宿主支持子代理（Task / 并行会话等）时 **优先**委派子代理执行本小节；若无子代理能力，则由**当前会话**按同一 skill 执行（不得以无子代理为由缩水审查）。
+**仅**在 **本波最后一个任务**、且该任务 **§3.4**（自动侧）已通过之后执行。静态忠实度门在 **§1.4 波前** 已完成或可豁免，此处**不再**重复 **`code-reviewer`**。
 
-**门禁路由**：Critical / High → 当前版本内可收敛则 **`/change`**；撼动需求/架构/ADR 前提则 **`/genesis`**。无阻塞 → **3.4.6**（若触发）或 **3.5**。
-
----
-
-### 3.4.6 浏览器与 E2E 验证指南
-
-完整遵从 `**e2e-testing-guide`** skill（触发条件、guide-only、证据规则均以 skill 为准）。
-
-验证以**用户旅程**为主线：步骤、断言、证据与 `PASS` / `FAIL` / `BLOCKED` / `NOT RUN` 状态规则均以 skill 为准。
-
-若宿主具备浏览器自动化：**先 Guide、后实机（用户授权）**；无工具则 guide-only，不得冒充已测。
-
-未触发 → `E2E guide skipped` + 一行原因 → **3.5**。
+1. 若本波 `05_TASKS.md` 中**任一**任务含 **E2E测试** 或 **手动验证**（或等价须实机 UI 的验收）：
+   - **必须**提示用户二选一（除非用户已预先声明）：
+     - **收尾 A**：本轮**仅**依赖 **§1.4** 已完成的 **`code-reviewer`**（或合法豁免记录）+ 本任务 **§3.4**，**不**再跑 E2E 报告与浏览器；若仍残留 UI 类验收未测，须在 Wave/会话备注写明**风险与原因**。
+     - **收尾 B**：**先** 严格按 **`e2e-testing-guide`** skill **只写**《E2E Verification》指南与表格（报告骨架与三档评测含义以 skill **Required output** 内 `<!-- -->` 注释为准：**仅** `PASS` / `PARTIAL_PASS` / `FAIL`）；**再** 在用户授权下用宿主 **浏览器工具** 按报告逐步执行，并把 **Evidence / 各 verdict 列** 回填。
+2. 若本波**无**上述验证类型 → 一行 `§3.4.6 skipped — no E2E/manual in wave` → **3.5**。
+3. **无浏览器工具**：只交付 skill 文档，标注 `guide-only`，不得声称已完成实机 `PASS`。
 
 ---
 
@@ -425,7 +427,7 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 | 4   | 代码风格与项目一致，lint 通过？        | 是/否 |
 | 5   | 所有验收标准已验证通过？              | 是/否 |
 | 6   | 所有可执行验收标准有足够证据（终端/日志/截图）？ | 是/否 |
-| 7   | 需人工确认的验收标准已标记 ？          | 是/否 |
+| 7   | 需人工确认的验收标准已标记 ？           | 是/否 |
 
 
 - 若检查清单全部通过 → 继续 3.6
@@ -462,6 +464,15 @@ T{X.Y.Z}, T{X.Y.Z}, T{X.Y.Z}
 
 **目标**: 结算本波次，更新状态，准备下一步。
 
+### 4.0 Wave 合拢门禁（硬）
+
+同时满足方可进入 **4.1+**：
+
+1. **§1.4**：本波进入 **Step 2** 之前 **`code-reviewer`** 已完成（可溯源），或 **`code-reviewer`** skill 下的**合法豁免**（含 **`CODE_REVIEW_DISABLED_BY_USER`** / **无可审实现** 等）已写明。
+2. **Step 3**：本波内**全部**任务已完成；**末任务**之 **§3.4.6** 已按 **收尾 A/B** 处理或已跳过（无 E2E/手动等），且 **§3.5 / §3.6** 已闭环。
+
+**不满足 → 禁止**进入 **4.1 及之后**；回到 Step 1（缺 §1.4）或 Step 3（缺任务闭环）补齐。
+
 ### 4.1 更新状态
 
 **更新 `AGENTS.md`**：
@@ -502,16 +513,17 @@ chore(wave): settle wave {N} progress
 
 **签名检查点** ：
 
-- 还有未完成任务 → 询问："继续下一波？"；普通模式等待用户签名，AUTO 模式以 `AUTO` 签名继续 → 回到 **Step 1**
+- 还有未完成任务 → **普通模式**：展示下一波 Wave 建议并等待用户签名 → 回到 **Step 1**。**AUTO 模式**：**不得**再问「是否继续下一波」— 直接回到 **Step 1** 并以 **`AUTO`** 签署下一波（展示 Wave 建议即可）。
 - 当前 Sprint 所有任务完成 → 进入 **Step 5**
 - 有阻塞问题 → 引导用户运行相应工作流修复
 
 > [!IMPORTANT]
-> **AUTO 模式的停止条件**：
+> **AUTO 模式的停止条件**（**仅**以下及上文已声明的等价硬阻塞；**不得**扩展为「征求意见」式停顿）：
 >
 > - 命中手动验证且需要用户最终确认
 > - `/change` 评估后发现必须升级到 `/genesis`
 > - 其他工作流要求用户作出新的版本级决定
+> - **§1.4 波前 `code-reviewer`** 产出未解决的 **Critical / High**，且无法在本会话内按 skill 收窄为可执行修复路径（须走 **`/change`** / **`/genesis`** 或用户显式承担风险—**未显式承担则停**）
 >
 > 命中以上任一条件，AUTO 必须立即停止，等待用户批准。
 
@@ -539,10 +551,9 @@ chore(wave): settle wave {N} progress
 
 - 每个任务的验收标准全部通过
 - 每个任务的遵从性检查全部通过
-- **3.4.5**：按 Wave 末次任务 / 约 2～3 Wave 兜底 / skill 例外执行 `code-reviewer`，或在任务与 Wave 记录中写明跳过或顺延依据
-- **3.4.6**：按 `e2e-testing-guide` 触发；有浏览器工具则先 Guide 后实机；否则 guide-only；未触发则写明原因
+- **§1.4 / §3.4.6**：**§4.0** 已满足；§1.4 波前审查或合法豁免已落盘；§3.4.6 已按 **收尾 A/B** 处理（选 A 须有备注），或本波无 E2E/手动态
 - 所有代码已 git commit，message 包含 Task ID
 - 所有任务已完成持久化（`05_TASKS.md`）
 - `AGENTS.md` 当前状态已更新
-- 用户已确认波次完成
+- 用户已确认波次完成，或 **AUTO** 已按规则完成结算署名