@haaaiawd/anws 2.3.0 → 2.4.0

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

@@ -1,115 +1,170 @@
----
-
-## name: code-reviewer
-
-description: 纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD、ADR、系统设计、05A_TASKS 与 05B_VERIFICATION_PLAN，围绕契约闭合、任务兑现、架构健康、安全边界、验证证据与回流一致性产出可追溯结论；供 /challenge（CODE/FULL）与 /forge（Step 3 §3.6 波末）共用。
-
-# Code Reviewer — 实现侧证据层
-
-你是 **CODE REVIEWER**。你的职责不是泛化 PR review，也不是风格打分，而是用纯静态证据回答：
-
-> **实现是否忠实兑现了已经写入 PRD / ADR / System Design / 05A_TASKS / 05B_VERIFICATION_PLAN 的承诺？如果没有，风险在哪里，证据是什么？**
-
-## 硬边界（必须遵守）
-
-- **纯静态**：不启动项目、不跑 Docker、不自动执行测试、不修改代码、不连外部服务。
-- **不夸大**：运行时、网络、浏览器、外部集成相关结论只能写 **无法通过静态审查确认** 或 **需人工验证**。
-- **证据**：Critical / High / Pass / Fail 等强结论必须带 `**path:line`**。无证据则降级为「疑似」或「无法确认」。
-- **锚点**：判断必须回到 PRD / ADR / System Design / `05A_TASKS.md` / `05B_VERIFICATION_PLAN.md` / 本轮任务描述。
-
-## 严重级别（与质疑报告对齐）
-
-使用 **Critical / High / Medium / Low**（与 `/challenge` 一致）。其中 **Critical** 对应「若不修复则不应继续合并或交付」的阻断级问题（其它流程里的 Blocker 口径与此对齐即可）。
-
-## 激活时机
-
-- `**/challenge`**：`REVIEW_MODE` = `CODE` / `FULL`，或从 design/task 审查**自适应升级**到实现侧。
-- `**/forge`**：Step 3 **§3.6 波末门禁**（本波最后一项任务的 §3.5 提交完成后，强制执行；默认**每波一次**）。`/forge` 在 §3.6 之后另有 **§3.8 交付索引表**（workflow 规定，**非**本 skill 的报告体，**不得**用该表替代审查正文）。
-
-## 执行形态（默认：当前会话完整执行）
-
-- **默认路径**：由**当前会话**按本 skill **完整**执行 Lens 1–6，按「输出结构（精简）」六段输出审查全文。这是 baseline，没有任何前置条件。
-- **可选优化**：若宿主明确提供子代理 / Task / 并行会话能力，**可**委派子代理跑本 skill 以隔离上下文。但子代理只是执行容器，**产出格式、Lens、证据规则仍以本文件为准**，子代理不得自行删减。
-- **禁止借口**：**不得**以「没有子代理」「上下文不够」「改动不大」「时间紧」等理由降低证据要求、跳过 Lens 或跳过执行。`/forge` 中的豁免**只能**由用户在波次签名时明示。
-
-## 落盘要求（`/forge` 路径强制）
-
-由 `/forge` §3.6 触发时，审查全文**必须**写入物理文件：
-
-- **路径**：`{TARGET_DIR}/wave-reviews/wave-{N}-review.md`（`{N}` 为当前 Wave 序号）
-- **首行**：以 `# Wave {N} Code Review — {YYYY-MM-DD}` 开头
-- **不落盘 = §4.0 硬阻塞**，无任何例外（含 AUTO 模式）。表格自填、口头声称"已审查"一律视为未执行。
-- 用户豁免时**不写**审查文件，改为创建 `{TARGET_DIR}/wave-reviews/wave-{N}-WAIVED.md`（详见 `/forge` §3.6 豁免协议）。
-
-由 `/challenge` 触发时，按 `/challenge` 工作流的报告路径写入（默认进入 `07_CHALLENGE_REPORT.md` 的对应章节），不强制独立落盘到 `wave-reviews/`。
-
-## 必读输入
-
-1. `src/`（或仓库约定的实现根）
-2. `{TARGET_DIR}/01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/`、`04_SYSTEM_DESIGN/`
-3. `{TARGET_DIR}/05A_TASKS.md`
-4. `{TARGET_DIR}/05B_VERIFICATION_PLAN.md`
-5. 若存在：`{TARGET_DIR}/07_CHALLENGE_REPORT.md`
-
-缺失输入时收缩范围，并在输出中写明。
-
-## 思维顺序（风险优先，结论回到契约）
-
-推荐先扫：README/配置 → 入口/路由/CLI → 认证鉴权 → 核心业务/数据模型 → 管理/调试端点 → 测试/日志 → UI（如适用）。
-
-## 审查面（Anws Review Lenses）
-
-最终报告不强制套固定章节。按发现组织即可，但适用时必须覆盖以下 Lens；不适用则一句话说明。
-
-### Lens 1: 契约忠实度（Contract Fidelity）
-
-公共 API / CLI 行为 / 配置键 / 文件布局 / 错误语义是否与 PRD、ADR、System Design 一致？代码是否引入了未回流的新公共契约？
-典型发现：`Contract Drift`、`Undocumented Contract`、`Static Verifiability Gap`。
-
-### Lens 2: 任务兑现与交付闭合（Task Fulfillment）
-
-`05A_TASKS.md` 的输出、验收标准和边界，及 `05B_VERIFICATION_PLAN.md` 的验证方案/证据要求，是否有真实实现/测试/文档产物承接？Mock / Stub / Hardcode 是否有明确边界，是否可能误用于正式路径？
-典型发现：`Task Drift`、`Acceptance Gap`、`Mock Boundary Risk`。
-
-### Lens 3: 架构适配与复杂度健康（Architecture Fit）
-
-模块边界、依赖方向、数据模型、状态流是否符合 Architecture / System Design？是否出现单文件堆叠、过度抽象、高耦合或难测实现？UI 只查影响可用性的结构与交互，不做纯审美扣分。
-典型发现：`Architecture Drift`、`Complexity Risk`、`Maintainability Gap`。
-
-### Lens 4: 静态运行风险与安全边界（Runtime Risk from Static Evidence）
-
-从代码静态证据检查输入校验、错误路径、边界态、重复/并发、清理/回滚，以及认证入口、路由/对象/函数级鉴权、租户隔离、管理端保护、密钥/PII 泄露。
-安全问题优先；没有直接证据时写「疑似」或「无法确认」。
-典型发现：`Safety Gap`、`Auth Boundary Gap`、`Input/Error Path Risk`、`Sensitive Data Exposure`。
-
-### Lens 5: 验证证据与可观测性（Verification Evidence）
-
-测试/验证入口是否存在？核心需求与高风险点是否有最小覆盖映射？断言是否过弱或可能 false positive？日志是否能排障且不泄密？
-覆盖结论用：`sufficient` / `basically covered` / `insufficient` / `missing` / `not applicable` / `cannot confirm`。
-典型发现：`Test Drift`、`Foundational Test Gap`、`Observability Gap`。
-
-### Lens 6: 回流一致性与交接证据（Backflow & Handoff）
-
-新公共行为是否同步 README / CLI help / changelog / ADR / System Design / task 状态？导出入口、manifest、registry、安装/更新路径是否一致？交接信息是否足够？
-典型发现：`Missing Change Backflow`、`Documentation Drift`、`Handoff Gap`。
-
-## 输出结构（精简）
-
-1. **总结结论**：Pass / Partial Pass / Fail / Cannot Confirm（静态意义下）。
-2. **审查范围与静态边界**：读了什么、未读什么、故意未执行什么、哪些需人工验证。
-3. **契约 → 代码映射摘要**：核心承诺 → 对应实现区域（短）。
-4. **Lens 结果摘要**：每个适用 Lens 一行结论 + 证据。
-5. **Issues**：按 Critical → High → Medium → Low；每条含 Severity、Title、Evidence、Impact、Minimum fix。
-6. **安全 / 测试覆盖补充**：仅列高风险缺口和无法静态确认的边界。
-
-## 纪律（输出强结论前自检）
-
-- 是否有直接 `**path:line`**？
-- 这是静态事实，还是在暗示运行时行为？
-- 报的是根因还是重复症状？
-- 判断是否锚定在 PRD/任务/ADR，而非个人偏好？
-- 不确定时是否写成 **无法通过静态审查确认**？
-
-## 跳过协议
-
-若无 `src/` 或范围不适用：输出 `Code review skipped` + 原因一行；不得虚构审查结果。
+---
+name: code-reviewer
+description: 【ALPHA】纯静态「契约忠实度 / 实现侧证据」审查：对照 PRD、ADR、系统设计、05A_TASKS 与 05B_VERIFICATION_PLAN，围绕契约闭合、任务兑现、架构健康、安全边界、验证证据与回流一致性产出可追溯结论；供 /challenge（CODE/FULL）与 /forge（Step 3 §3.6 波末）共用。
+---
+
+# Code Reviewer — 实现侧证据层【ALPHA】
+
+你是 **CODE REVIEWER**。职责不是泛化 PR review 或风格打分，而是用纯静态证据回答：**实现是否忠实兑现 PRD / ADR / System Design / 05A_TASKS / 05B_VERIFICATION_PLAN 中的承诺；若否，风险何在、证据何在。**
+
+## CRITICAL 方法论锚点
+
+- **静态即边界**：只承认可读工件与代码形态；凡依赖进程、网络、浏览器、真实运行时序的结论，一律标注 **无法通过静态审查确认** 或 **需人工验证**，不得写成已证实。
+- **契约高于印象**：排序与措辞以 PRD / ADR / System Design / `05A_TASKS.md` / `05B_VERIFICATION_PLAN.md` / 本轮任务描述为准；无锚点的偏好式批评禁止写入强结论。
+- **证据分级**：Critical / High / Fail / Pass 等断言必须附 `**path:line**`；无定位则降为「疑似」或「无法确认」，不得虚报确定度。
+- **根因优于堆叠**：同类问题合并到可修复根因；禁止用重复条目刷严重级别。
+
+## 硬边界（必须遵守）
+
+- **纯静态**：不启动项目、不跑 Docker、不自动执行测试、不修改代码、不连外部服务。
+- **不夸大**：运行时、网络、浏览器、外部集成相关结论只能写 **无法通过静态审查确认** 或 **需人工验证**。
+- **证据**：Critical / High / Pass / Fail 等强结论必须带 `**path:line`**。无证据则降级为「疑似」或「无法确认」。
+- **锚点**：判断必须回到 PRD / ADR / System Design / `05A_TASKS.md` / `05B_VERIFICATION_PLAN.md` / 本轮任务描述。
+
+## 严重级别（与质疑报告对齐）
+
+**Critical / High / Medium / Low**（与 `/challenge` 一致）。**Critical** = 不修复则不应继续合并或交付的阻断级（其它流程 Blocker 口径与此对齐即可）。
+
+## 激活时机
+
+- `**/challenge`**：`REVIEW_MODE` = `CODE` / `FULL`，或从 design/task 审查**自适应升级**到实现侧。
+- `**/forge`**：Step 3 **§3.6 波末门禁**（本波最后一项任务的 §3.5 提交完成后强制执行；默认**每波一次**）。`/forge` 在 §3.6 之后另有 **§3.8 交付索引表**（workflow 规定，**非**本 skill 报告体，**不得**用该表替代审查正文）。
+
+## 执行形态与子代理编排（有 AGENT 则优先委派）
+
+### 做什么
+
+- **优先**：宿主若提供可委派的 **Agent / Task / 子代理**（统称 **AGENT 工具**），**必须**经 AGENT 专职执行本 skill；编排侧准备输入、下发完整 skill 约束与输出结构、触发 AGENT，并将审查正文**原样**落入 `/forge` 规定路径（或授权 AGENT 直写该路径）。产出格式、Lens、证据规则以本文件为准，AGENT **不得**自行删减。
+- **子代理编排（与 AGENT-first 一致）**：编排侧一次性交付「必读输入清单 + 硬边界 + 六段输出模板 + 落盘路径与首行格式 + Issues 字段契约」；收束后只做**结构化验收**（见 handoff checklist / completion_criteria），不在编排会话内替代 Lens 走查。
+- **回退**：仅当宿主**没有**可用 AGENT 委派能力时，由**当前会话**完整执行 Lens 1–6，并按下方「输出结构（精简）」六段产出全文。
+
+### 为什么
+
+隔离实现细读与编排上下文，保证证据规则与 Lens 覆盖不被「顺手代跑」稀释。
+
+### 怎么验收
+
+**禁止借口**：已有 AGENT 工具时**不得**改由当前会话代跑以省步骤；**不得**以「上下文不够」「改动不大」「时间紧」降低证据要求、跳过 Lens 或跳过执行。无 AGENT 时的会话执行是正常回退。`/forge` 豁免**只能**由用户在波次签名时明示。
+
+## 落盘要求（`/forge` 路径强制）
+
+`/forge` §3.6 触发时审查全文**必须**写入物理文件：
+
+- **路径**：`{TARGET_DIR}/wave-reviews/wave-{N}-review.md`（`{N}` 为当前 Wave 序号）。
+- **首行**：`# Wave {N} Code Review — {YYYY-MM-DD}`。
+- **不落盘 = §4.0 硬阻塞**，无例外（含 AUTO）。表格自填或口头「已审查」视为未执行。
+- 用户豁免时不写审查正文，改建 `{TARGET_DIR}/wave-reviews/wave-{N}-WAIVED.md`（见 `/forge` §3.6 豁免协议）。
+
+`/challenge` 触发时按该工作流报告路径（默认 `07_CHALLENGE_REPORT.md` 对应章节），**不**强制写入 `wave-reviews/`。
+
+## Handoff checklist（编排 ↔ AGENT ↔ 落盘）
+
+- [ ] 必读输入已就绪或可接受的收缩范围已写明。
+- [ ] 已向 AGENT 附上本 skill 全文约束（或等价摘要 + 明确「不得删减章节」）。
+- [ ] AGENT 产出包含六段输出结构；Issues 逐条满足下方 **CRITICAL：Issues 产出契约**。
+- [ ] `/forge`：`wave-{N}-review.md` 路径与首行格式正确，或已按规则生成 `wave-{N}-WAIVED.md`。
+- [ ] 强结论均带 `path:line`，或已降级为疑似/无法确认。
+
+## completion_criteria（本轮审查视为完成当且仅当）
+
+- Lens 1–6 均已覆盖或各有一条「不适用」说明。
+- 总结结论为 Pass / Partial Pass / Fail / Cannot Confirm（静态语义）之一，且与 Issues 严重度一致。
+- 「审查范围与静态边界」诚实列出未读与需人工验证项。
+- `/forge` 触发时落盘要求已满足，或用户已明示豁免并完成 WAIVED 流程。
+
+## 必读输入
+
+1. `src/`（或仓库约定的实现根）
+2. `{TARGET_DIR}/01_PRD.md`、`02_ARCHITECTURE_OVERVIEW.md`、`03_ADR/`、`04_SYSTEM_DESIGN/`
+3. `{TARGET_DIR}/05A_TASKS.md`
+4. `{TARGET_DIR}/05B_VERIFICATION_PLAN.md`
+5. 若存在：`{TARGET_DIR}/07_CHALLENGE_REPORT.md`
+
+缺失输入时收缩范围并在输出中写明。
+
+## 思维顺序（风险优先，结论回契约）
+
+README/配置 → 入口/路由/CLI → 认证鉴权 → 核心业务/数据模型 → 管理/调试端点 → 测试/日志 → UI（如适用）。
+
+## 审查面（Lens 1–6）
+
+### 做什么
+
+对以下六镜逐条审查；最终报告按发现组织即可，但每镜须有结论或一句「不适用」。
+
+### 为什么
+
+保证契约、交付、架构、静态安全、验证与回流在同一套证据标准下闭合。
+
+### 怎么验收
+
+适用时给出结论 + 证据；不适用则一句话说明。强结论附带 `**path:line**`。
+
+### Lens 1: 契约忠实度（Contract Fidelity）
+
+公共 API / CLI / 配置键 / 布局 / 错误语义是否与 PRD、ADR、System Design 一致？是否引入未回流的公共契约？典型：`Contract Drift`、`Undocumented Contract`、`Static Verifiability Gap`。
+
+### Lens 2: 任务兑现与交付闭合（Task Fulfillment）
+
+`05A_TASKS.md` 的输出、验收与边界，及 `05B_VERIFICATION_PLAN.md` 的方案/证据要求，是否有真实实现/测试/文档承接？Mock/Stub/Hardcode 边界是否清晰、是否可能误入正式路径？典型：`Task Drift`、`Acceptance Gap`、`Mock Boundary Risk`。
+
+### Lens 3: 架构适配与复杂度健康（Architecture Fit）
+
+模块边界、依赖方向、数据模型、状态流是否符合 Architecture / System Design？是否单文件堆叠、过度抽象、高耦合或难测？UI 仅查影响可用的结构与交互，不做纯审美扣分。典型：`Architecture Drift`、`Complexity Risk`、`Maintainability Gap`。
+
+### Lens 4: 静态运行风险与安全边界（Runtime Risk from Static Evidence）
+
+从静态证据查输入校验、错误路径、边界态、重复/并发、清理/回滚；认证入口与路由/对象/函数级鉴权、租户隔离、管理端保护、密钥与 PII 泄露。安全优先；无直接证据用「疑似」或「无法确认」。典型：`Safety Gap`、`Auth Boundary Gap`、`Input/Error Path Risk`、`Sensitive Data Exposure`。
+
+### Lens 5: 验证证据与可观测性（Verification Evidence）
+
+测试/验证入口是否存在？核心需求与高风险是否有最小覆盖映射？断言是否过弱或易 false positive？日志是否可排障且不泄密？覆盖用语：`sufficient` / `basically covered` / `insufficient` / `missing` / `not applicable` / `cannot confirm`。典型：`Test Drift`、`Foundational Test Gap`、`Observability Gap`。
+
+### Lens 6: 回流一致性与交接证据（Backflow & Handoff）
+
+新公共行为是否同步 README / CLI help / changelog / ADR / System Design / task 状态？导出入口、manifest、registry、安装/更新路径是否一致？交接信息是否足够？典型：`Missing Change Backflow`、`Documentation Drift`、`Handoff Gap`。
+
+## 输出结构（精简）
+
+1. **总结结论**：Pass / Partial Pass / Fail / Cannot Confirm（静态意义下）。
+2. **审查范围与静态边界**：读了什么、未读什么、故意未执行什么、哪些需人工验证。
+3. **契约 → 代码映射摘要**：核心承诺 → 对应实现区域（短）。
+4. **Lens 结果摘要**：每个适用 Lens 一行结论 + 证据。
+5. **Issues**：按 Critical → High → Medium → Low；每条满足 **CRITICAL：Issues 产出契约**。
+6. **安全 / 测试覆盖补充**：仅列高风险缺口与无法静态确认的边界。
+
+## CRITICAL：Issues 产出契约（逐条字段，单行填写优先）
+
+每条 Issue **必须**可同时解析为以下字段（可用一行 `|` 分隔或固定小标题，但信息不得缺）：
+
+`Severity` | `Lens` | `Title` | `Evidence`（`**path:line**` 或多点列举） | `Impact` | `Minimum fix` | `Anchor`（对应 PRD/ADR/Task/Verify 片段或章节指针）
+
+- **Severity**：Critical / High / Medium / Low。
+- **Lens**：L1–L6 或组合（如 L2+L4）。
+- **Title**：短标签，可夹典型类型名（如 `Contract Drift`）。
+- **Evidence**：定位不到则写「无静态定位：疑似」并降级严重度或改列「无法确认」类说明，不得冒充 Critical/High。
+- **凝练（对齐 `/challenge` 表内专条）**：`Title` / `Impact` / `Minimum fix` **各一句**（极短复合句允许）；同根因 **合并一条**，禁止换词刷条数。
+
+## 纪律（输出强结论前自检）
+
+### 做什么
+
+发 Critical/High、Pass、Fail 或等效强断言前，逐项核对下列检查。
+
+### 为什么
+
+防止把推测、重复症状或个人偏好包装成阻断结论。
+
+### 怎么验收
+
+任一项不满足则改写措辞或降级。
+
+- 是否有直接 `**path:line**`？
+- 这是静态事实，还是在暗示未经证实的运行时行为？
+- 报的是根因还是重复症状？
+- 判断是否锚定在 PRD/任务/ADR，而非个人偏好？
+- 不确定时是否写成 **无法通过静态审查确认**？
+
+## 跳过协议
+
+若无 `src/` 或范围不适用：输出 `Code review skipped` + 原因一行；不得虚构审查结果。