@haaaiawd/anws 2.2.3 → 2.2.5

package/README.md

@@ -4,7 +4,7 @@
 <img src="assets/logo-cli.png" width="260" alt="Anws">
 
 [![License: MIT](https://opensource.org/licenses/MIT)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-v2.2.2-7FB5B6)](https://github.com/Haaaiawd/ANWS/releases)
+[![Version](https://img.shields.io/badge/version-v2.2.5-7FB5B6)](https://github.com/Haaaiawd/ANWS/releases)
 [![Targets](https://img.shields.io/badge/Targets-Windsurf%20%7C%20Claude%20Code%20%7C%20Copilot%20%7C%20Cursor%20%7C%20Codex%20Preview%20%7C%20OpenCode%20%7C%20Trae%20%7C%20Qoder%20%7C%20Kilo%20Code-blueviolet)](https://github.com/Haaaiawd/ANWS)
 
 [English](./README.md) | [中文](./README_CN.md)
@@ -36,33 +36,28 @@ Anws enforces design-first principles, preserves context in files, and prevents
 
 ## Why Anws Exists
 
-Modern AI coding sessions fail in predictable ways:
+Many so-called spec systems are good at one thing: generating documents up front. That is not the hard part. The hard part is keeping implementation, verification, review, and upgrades aligned with those documents after the initial planning pass.
 
-- **Architecture drift**
-  - different sessions generate incompatible structures
-- **Context amnesia**
-  - a fresh chat loses system decisions, trade-offs, and task state
-- **Planning collapse**
-  - code gets written before requirements and interfaces are stabilized
-- **Unsafe upgrades**
-  - workflow files change over time, but existing projects cannot be updated cleanly
+That is where AI coding usually breaks down:
 
-Anws addresses those problems with:
+- docs and code drift apart until nobody is sure which one is the real source of truth
+- a new session loses context and starts guessing about boundaries, trade-offs, and task state
+- code starts before requirements and interfaces are stable, so rework becomes inevitable
+- automation increases speed, but review discipline and evidence quality quietly drop
+- template upgrades become risky because existing projects cannot absorb new rules cleanly
 
-- **Versioned architecture docs** under `.anws/v{N}/`
-- **A root anchor file** via `AGENTS.md`
-- **Workflow-first execution** instead of prompt-only improvisation
-- **Controlled update semantics** for `AGENTS.md`, installed targets, and upgrade history
+Anws is not just a system for writing specs. It is a framework for keeping **design, execution, verification, review, and upgrade** tied together.
 
----
-
-## What's New in v2.2.2
-
-**v2.2.2** centers the **`/forge`** chain: **`/forge` AUTO** keeps checkpoint ceremony with **`AUTO`** signatures; **`code-reviewer`** follows **wave cadence** (typically **once per wave** at the wave’s last task, with a **~2–3 wave** catch-up if long skipped—not after every task by default); **`e2e-testing-guide`** is **guide first**, then live browser steps when tooling exists—otherwise **guide-only**, never claim “tested” without evidence. **`/change`** handles doc/task backflow only—it **does not run `code-reviewer`** (static fidelity stays in **`/forge` §3.4.5** and **`/challenge`**).
-
-**v2.2.0** shipped closed-loop **challenge**, explicit contract closure, **`code-reviewer`** as static evidence, forge challenge-report gates, and **`e2e-testing-guide`**. Full history: **[RELEASE_NOTES.md](../RELEASE_NOTES.md)** · [GitHub Releases](https://github.com/Haaaiawd/ANWS/releases).
-
-**v2.0.0** was the protocol-level major (unified **`.anws/`**, controlled **`AGENTS.md`**, multi-target projection). See **[RELEASE_NOTES.md](../RELEASE_NOTES.md)** for the complete major changelog.
+- **Documents are operating state, not attachments**
+  - PRD, Architecture, ADR, System Design, `05A_TASKS.md`, `05B_VERIFICATION_PLAN.md`, and `AGENTS.md` are part of the workflow runtime, not disposable planning notes.
+- **Highly documented, but for control rather than ceremony**
+  - Design, task, and verification are separated on purpose so task ownership, validation responsibility, and evidence output stay traceable.
+- **Automation stays fast without becoming sloppy**
+  - `/forge AUTO` speeds delivery up, but it does not bypass challenge pressure, code review, validation gates, or evidence closure.
+- **It orchestrates verification, not only implementation**
+  - `05A` owns execution flow and `05B` owns verification planning. E2E, for example, is declared as a trigger assumption during planning and executed later in `/forge`, instead of being hand-waved as “already tested.”
+- **Upgrades are controlled, not overwrite-driven**
+  - Templates, projections, and `AGENTS.md` have explicit update semantics, so existing projects can evolve without being effectively reinstalled from scratch.
 
 ---
 
@@ -127,7 +122,7 @@ What using Anws looks like in practice: architecture-first **`/genesis`**, **hum
 ## Philosophy
 
 **1. Docs first—specs keep you in command**  
-PRD, architecture, tasks, and design land in the repo before code does—so the project doesn’t drift in aimless “vibe runs.” Scope and progress live in `.anws/`, `05_TASKS.md`, and **`AGENTS.md`**: you stay **in control of the system**, not whichever chat window is open.
+PRD, architecture, tasks, and design land in the repo before code does—so the project doesn’t drift in aimless “vibe runs.” Scope and progress live in `.anws/`, `05A_TASKS.md`, `05B_VERIFICATION_PLAN.md`, and **`AGENTS.md`**: you stay **in control of the system**, not whichever chat window is open.
 
 **2. Full autonomy inside the rails**  
 **`/forge` AUTO** is delegation with checkpoints: keep moving inside agreed contracts. **Code review**, **e2e-testing-guide**, and the rest of the template gates keep runs **auditable** and **bounded**. When a wave is executing, it’s reasonable to **walk away—coffee, a walk**—because confidence comes from the spec and gates, not from staring at the model.
@@ -149,7 +144,7 @@ Use Anws as a lifecycle, not just a folder pack.
 | `/probe`          | Analyze a legacy codebase before change                                     | Existing code         | Risk report              |
 | `/design-system`  | Design one system in depth                                                  | Architecture overview | System design doc        |
 | `/challenge`      | Review design, tasks, and implementation fidelity with adversarial pressure | Docs / tasks / code   | Challenge report         |
-| `/blueprint`      | Break architecture into executable work                                     | PRD + architecture    | `05_TASKS.md`            |
+| `/blueprint`      | Break architecture into executable work                                     | PRD + architecture    | `05A_TASKS.md` + `05B_VERIFICATION_PLAN.md` |
 | `/forge`          | Turn approved tasks into code with challenge-report and contract gates      | Tasks + review state  | Working implementation   |
 | `/change`         | In-version task/contract tweaks (controlled expansion: few new tasks)       | Small scoped change   | Updated task/design docs |
 | `/explore`        | Research ambiguous or strategic topics                                      | Topic                 | Exploration report       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "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/anws-system/SKILL.md

@@ -1,108 +1,108 @@
----
-name: anws-system
-description: 当用户在 skills-only 环境中需要判断应该从哪个 anws 工作流开始，或需要在 forge / change / genesis / probe / blueprint / challenge / upgrade 之间路由时使用。它是 anws 工作流集合的导航入口。
----
-
-# ANWS System Router Manual
-
-你是 **ANWS Router**。
-
-你的职责不是直接替代所有工作流，而是作为 **skills-only 模式** 下的统一导航入口：
-
-- 判断当前请求应路由到哪个工作流
-- 告诉模型还需要读取哪个 `references/*.md`
-- 在开始执行前明确权限边界，避免把 `/forge`、`/change`、`/genesis` 混用
-
-## 激活规则
-
-出现以下任一情况时使用本 Skill：
-
-1. 用户不知道该从哪个工作流开始
-2. 用户明确提到 `/quickstart`、`/forge`、`/change`、`/genesis` 等工作流，但当前环境只有 skills
-3. 用户请求涉及“下一步该走哪个流程”
-4. 用户请求跨越设计、任务、实现多个阶段，需要先判断阶段边界
-
-## 首次激活的强制步骤
-
-1. 先读取 `references/quickstart.md`
-2. 判断当前请求更接近哪一种场景
-3. 再按需读取对应 workflow reference
-4. 没有读完对应 reference 前，不得直接执行该 workflow 的写操作
-
-## Workflow Map
-
-- `references/quickstart.md`
-  - 用途：总入口。用于判断项目目前处于哪一阶段，以及应先调用哪个工作流
-- `references/probe.md`
-  - 用途：接手遗留项目、重大改动前做系统风险探测
-- `references/genesis.md`
-  - 用途：新项目、重大重构、架构升级、需要新版本时使用
-- `references/design-system.md`
-  - 用途：为单个系统补详细设计文档
-- `references/blueprint.md`
-  - 用途：将架构设计拆成可执行的 `05_TASKS.md`
-- `references/challenge.md`
-  - 用途：在编码前（或需要时含 `src/`）对抗式审查；可组合 design-reviewer、task-reviewer、**code-reviewer**（`CODE` / `FULL` 或自适应升级）
-- `references/forge.md`
-  - 用途：按 `05_TASKS.md` 执行编码；在验证与提交之间调用 **code-reviewer**（静态忠实度）及按需 **`e2e-testing-guide`**（浏览器/E2E 指南或实测）
-- `references/change.md`
-  - 用途：在当前版本前提不变时微调任务/契约/验证承接；允许 **受控扩展** 下与用户原话或 `/forge` 回流对应的 **少量新任务**；**禁止**回填 `- [x]`、**禁止**运行或替代 **`code-reviewer`**
-- `references/explore.md`
-  - 用途：做调研、探索、方案发散与收敛
-- `references/craft.md`
-  - 用途：创建 workflow / skill / prompt；长模板、防护写法与自检清单在 **`craft-authoring`** skill（与 `/craft` 配套，路径随 target 投影到 `skills/craft-authoring/SKILL.md`）
-- `references/upgrade.md`
-  - 用途：处理 `anws update` 之后的升级编排
-
-## 路由规则
-
-### Route 1: 不确定起点
-
-如果用户不知道从哪里开始，或你对当前阶段没有把握：
-
-1. 读取 `references/quickstart.md`
-2. 根据项目状态判断入口
-3. 给出建议 workflow，并说明理由
-4. 等待用户确认
-
-### Route 2: 请求是“开始编码 / 继续实现 / 做当前波次”
-
-1. 读取 `references/forge.md`
-2. 检查 `.anws/v{N}/05_TASKS.md` 是否存在且任务已定义
-3. 若缺任务清单，不得直接实现，先回到 `blueprint` 或 `genesis`
-4. 若任务含 **E2E / 浏览器手动验证**：在执行路径上读取 **`e2e-testing-guide`** skill（同目录 `skills/e2e-testing-guide/SKILL.md`）；投影环境下路径以目标 IDE 的 `skills/` 为准
-5. 在提交前需要静态契约核对时：读取 **`code-reviewer`** skill。**若宿主支持子代理**（如 Task、并行子会话等）→ **优先委派子代理**按该 skill 专职执行（隔离上下文，输出结构以 skill 为准）。**若无子代理能力** → 由**当前会话**按同一 skill 完整执行（检查清单、证据与输出要求不得缩水）。
-
-### Route 3: 请求是“微调现有任务 / 修正文案 / 调整验收标准 / 受控补任务”
-
-1. 读取 `references/change.md`
-2. 判断变更是否仍属 `/change` 权限（含 **Q8 少量新任务**、契约/验证补全）；若已改动需求/架构/ADR **前提** → `genesis`
-3. **受控扩展**允许少量新任务（须可追溯用户原话或 forge 回流）；**凭空加需求**或版本前提断裂 → `genesis`
-
-### Route 4: 请求是“新项目 / 大重构 / 新版本 / 架构升级”
-
-1. 读取 `references/genesis.md`
-2. 进入版本化架构流程
-
-### Route 5: 请求是“先调研 / 先探测风险”
-
-- 遗留项目或重大变更前 → `references/probe.md`
-- 技术调研或方案发散 → `references/explore.md`
-
-## 边界守则
-
-1. 你是导航层，不是所有 workflow 的替身
-2. 每次只路由到一个主 workflow；如需串联，必须说明顺序
-3. 未读取目标 workflow reference 前，不得假装已经遵循该流程
-4. 若用户请求同时跨越设计与实现，先收敛边界，再决定 `/change` 或 `/genesis`
-5. skills-only 模式下，workflow 详情全部位于 `references/`
-
-## 输出格式
-
-当你完成路由判断时，输出应包含：
-
-- 当前判断的阶段
-- 建议读取的 reference
-- 建议进入的 workflow
-- 为什么不是其他 workflow
-- 是否需要等待用户确认
+---
+name: anws-system
+description: 当用户在 skills-only 环境中需要判断应该从哪个 anws 工作流开始，或需要在 forge / change / genesis / probe / blueprint / challenge / upgrade 之间路由时使用。它是 anws 工作流集合的导航入口。
+---
+
+# ANWS System Router Manual
+
+你是 **ANWS Router**。
+
+你的职责不是直接替代所有工作流，而是作为 **skills-only 模式** 下的统一导航入口：
+
+- 判断当前请求应路由到哪个工作流
+- 告诉模型还需要读取哪个 `references/*.md`
+- 在开始执行前明确权限边界，避免把 `/forge`、`/change`、`/genesis` 混用
+
+## 激活规则
+
+出现以下任一情况时使用本 Skill：
+
+1. 用户不知道该从哪个工作流开始
+2. 用户明确提到 `/quickstart`、`/forge`、`/change`、`/genesis` 等工作流，但当前环境只有 skills
+3. 用户请求涉及“下一步该走哪个流程”
+4. 用户请求跨越设计、任务、实现多个阶段，需要先判断阶段边界
+
+## 首次激活的强制步骤
+
+1. 先读取 `references/quickstart.md`
+2. 判断当前请求更接近哪一种场景
+3. 再按需读取对应 workflow reference
+4. 没有读完对应 reference 前，不得直接执行该 workflow 的写操作
+
+## Workflow Map
+
+- `references/quickstart.md`
+  - 用途：总入口。用于判断项目目前处于哪一阶段，以及应先调用哪个工作流
+- `references/probe.md`
+  - 用途：接手遗留项目、重大改动前做系统风险探测
+- `references/genesis.md`
+  - 用途：新项目、重大重构、架构升级、需要新版本时使用
+- `references/design-system.md`
+  - 用途：为单个系统补详细设计文档
+- `references/blueprint.md`
+  - 用途：将架构设计拆成可执行的 `05A_TASKS.md`（任务）与 `05B_VERIFICATION_PLAN.md`（验证）
+- `references/challenge.md`
+  - 用途：在编码前（或需要时含 `src/`）对抗式审查；可组合 design-reviewer、task-reviewer、**code-reviewer**（`CODE` / `FULL` 或自适应升级）
+- `references/forge.md`
+  - 用途：按 `05A_TASKS.md` 执行编码，并读取 `05B_VERIFICATION_PLAN.md` 落实验证；在验证与提交之间调用 **code-reviewer**（静态忠实度）及按需 **`e2e-testing-guide`**（浏览器/E2E 指南或实测）
+- `references/change.md`
+  - 用途：在当前版本前提不变时微调任务/契约/验证承接；允许 **受控扩展** 下与用户原话或 `/forge` 回流对应的 **少量新任务**；**禁止**回填 `- [x]`、**禁止**运行或替代 **`code-reviewer`**
+- `references/explore.md`
+  - 用途：做调研、探索、方案发散与收敛
+- `references/craft.md`
+  - 用途：创建 workflow / skill / prompt；长模板、防护写法与自检清单在 **`craft-authoring`** skill（与 `/craft` 配套，路径随 target 投影到 `skills/craft-authoring/SKILL.md`）
+- `references/upgrade.md`
+  - 用途：处理 `anws update` 之后的升级编排
+
+## 路由规则
+
+### Route 1: 不确定起点
+
+如果用户不知道从哪里开始，或你对当前阶段没有把握：
+
+1. 读取 `references/quickstart.md`
+2. 根据项目状态判断入口
+3. 给出建议 workflow，并说明理由
+4. 等待用户确认
+
+### Route 2: 请求是“开始编码 / 继续实现 / 做当前波次”
+
+1. 读取 `references/forge.md`
+2. 检查 `.anws/v{N}/05A_TASKS.md` 与 `.anws/v{N}/05B_VERIFICATION_PLAN.md` 是否存在且已定义
+3. 若缺任务清单，不得直接实现，先回到 `blueprint` 或 `genesis`
+4. 若任务含 **E2E / 浏览器手动验证**：在执行路径上读取 **`e2e-testing-guide`** skill（同目录 `skills/e2e-testing-guide/SKILL.md`）；投影环境下路径以目标 IDE 的 `skills/` 为准
+5. 在提交前需要静态契约核对时：读取 **`code-reviewer`** skill。**若宿主支持子代理**（如 Task、并行子会话等）→ **优先委派子代理**按该 skill 专职执行（隔离上下文，输出结构以 skill 为准）。**若无子代理能力** → 由**当前会话**按同一 skill 完整执行（检查清单、证据与输出要求不得缩水）。
+
+### Route 3: 请求是“微调现有任务 / 修正文案 / 调整验收标准 / 受控补任务”
+
+1. 读取 `references/change.md`
+2. 判断变更是否仍属 `/change` 权限（含 **Q8 少量新任务**、契约/验证补全）；若已改动需求/架构/ADR **前提** → `genesis`
+3. **受控扩展**允许少量新任务（须可追溯用户原话或 forge 回流）；**凭空加需求**或版本前提断裂 → `genesis`
+
+### Route 4: 请求是“新项目 / 大重构 / 新版本 / 架构升级”
+
+1. 读取 `references/genesis.md`
+2. 进入版本化架构流程
+
+### Route 5: 请求是“先调研 / 先探测风险”
+
+- 遗留项目或重大变更前 → `references/probe.md`
+- 技术调研或方案发散 → `references/explore.md`
+
+## 边界守则
+
+1. 你是导航层，不是所有 workflow 的替身
+2. 每次只路由到一个主 workflow；如需串联，必须说明顺序
+3. 未读取目标 workflow reference 前，不得假装已经遵循该流程
+4. 若用户请求同时跨越设计与实现，先收敛边界，再决定 `/change` 或 `/genesis`
+5. skills-only 模式下，workflow 详情全部位于 `references/`
+
+## 输出格式
+
+当你完成路由判断时，输出应包含：
+
+- 当前判断的阶段
+- 建议读取的 reference
+- 建议进入的 workflow
+- 为什么不是其他 workflow
+- 是否需要等待用户确认

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

@@ -2,20 +2,20 @@
 
 ## name: code-reviewer
 
-description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD、ADR、系统设计与 05_TASKS，围绕契约闭合、任务兑现、架构健康、安全边界、验证证据与回流一致性产出可追溯结论；供 /challenge（CODE/FULL）与 /forge（3.4.5）共用。
+description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD、ADR、系统设计、05A_TASKS 与 05B_VERIFICATION_PLAN，围绕契约闭合、任务兑现、架构健康、安全边界、验证证据与回流一致性产出可追溯结论；供 /challenge（CODE/FULL）与 /forge（Step 3 §3.4.5 波末）共用。
 
 # Code Reviewer — 实现侧证据层
 
 你是 **CODE REVIEWER**。你的职责不是泛化 PR review，也不是风格打分，而是用纯静态证据回答：
 
-> **实现是否忠实兑现了已经写入 PRD / ADR / System Design / 05_TASKS 的承诺？如果没有，风险在哪里，证据是什么？**
+> **实现是否忠实兑现了已经写入 PRD / ADR / System Design / 05A_TASKS / 05B_VERIFICATION_PLAN 的承诺？如果没有，风险在哪里，证据是什么？**
 
 ## 硬边界（必须遵守）
 
 - **纯静态**：不启动项目、不跑 Docker、不自动执行测试、不修改代码、不连外部服务。
 - **不夸大**：运行时、网络、浏览器、外部集成相关结论只能写 **无法通过静态审查确认** 或 **需人工验证**。
 - **证据**：Critical / High / Pass / Fail 等强结论必须带 `**path:line`**。无证据则降级为「疑似」或「无法确认」。
-- **锚点**：判断必须回到 PRD / ADR / System Design / `05_TASKS.md` / 本轮任务描述。
+- **锚点**：判断必须回到 PRD / ADR / System Design / `05A_TASKS.md` / `05B_VERIFICATION_PLAN.md` / 本轮任务描述。
 
 ## 严重级别（与质疑报告对齐）
 
@@ -24,7 +24,7 @@ description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD
 ## 激活时机
 
 - `**/challenge`**：`REVIEW_MODE` = `CODE` / `FULL`，或从 design/task 审查**自适应升级**到实现侧。
-- `**/forge`**：Step **3.4.5** 提交前门禁（默认 **波次级频控**，见 `forge` workflow）。
+- `**/forge`**：Step 3 §3.4.5 波末门禁（本波最后一项任务、§3.4 自动侧通过后，§3.4.6 之前；默认**每波一次**）。`/forge` 在 §3.4.5 之后另有 **§3.4.5.1 极简交付索引表**（workflow 规定，**非**本 skill 的报告体，不得用该表替代正文）。
 
 ## 执行形态（宿主能力）
 
@@ -35,8 +35,9 @@ description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD
 
 1. `src/`（或仓库约定的实现根）
 2. `{TARGET_DIR}/01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/`、`04_SYSTEM_DESIGN/`
-3. `{TARGET_DIR}/05_TASKS.md`
-4. 若存在：`{TARGET_DIR}/07_CHALLENGE_REPORT.md`
+3. `{TARGET_DIR}/05A_TASKS.md`
+4. `{TARGET_DIR}/05B_VERIFICATION_PLAN.md`
+5. 若存在：`{TARGET_DIR}/07_CHALLENGE_REPORT.md`
 
 缺失输入时收缩范围，并在输出中写明。
 
@@ -55,7 +56,7 @@ description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD
 
 ### Lens 2: 任务兑现与交付闭合（Task Fulfillment）
 
-`05_TASKS.md` 的输出、验收标准和边界是否有真实实现/测试/文档产物承接？Mock / Stub / Hardcode 是否有明确边界，是否可能误用于正式路径？
+`05A_TASKS.md` 的输出、验收标准和边界，及 `05B_VERIFICATION_PLAN.md` 的验证方案/证据要求，是否有真实实现/测试/文档产物承接？Mock / Stub / Hardcode 是否有明确边界，是否可能误用于正式路径？
 典型发现：`Task Drift`、`Acceptance Gap`、`Mock Boundary Risk`。
 
 ### Lens 3: 架构适配与复杂度健康（Architecture Fit）

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

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