@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/prompts/review-one-task.md

@@ -1,43 +1,45 @@
-# Codex 单任务审查 Prompt 模板
-
-你是 Codex 审查会话。请只审查当前任务的 diff、测试和任务状态，不要主动重构或实现新功能。
-
-## 审查目标
-
-- 任务 ID: `<task-id>`
-- 描述: `<task-description>`
-- 验收标准: `<acceptance>`
-- 测试命令: `<test_command>`
-
-## 必查项
-
-1. `task.json` 中只有当前任务的 `passes` 被改为 `true`。
-2. `progress.txt` 包含当前任务的完成记录。
-3. 代码或文档改动与任务描述一致。
-4. 没有无关文件、临时文件、密钥或调试输出。
-5. 测试命令已经运行且结果可信。
-6. 如果任务使用了 `docs/knowledge/`，最终报告包含对应 `knowledge_references`。
-7. 如果任务产生了可复用经验，最终报告包含 `knowledge_outputs` 或说明没有可归档条目。
-8. 如果有失败风险，按严重程度列出发现。
-
-## 输出格式
-
-```markdown
-## Findings
-
-- [severity] 文件:行 - 问题说明
-
-## Verification
-
-- 已检查的命令和结果
-
-## Residual Risk
-
-- 剩余风险或测试缺口
-```
-
-如果没有发现问题，明确写：
-
-```text
-未发现阻塞性问题。
-```
+# Codex 单任务审查 Prompt 模板
+
+你是 Codex 审查会话。请只审查当前任务的 diff、测试和任务状态，不要主动重构或实现新功能。
+
+## 审查目标
+
+- 任务 ID: `<task-id>`
+- 描述: `<task-description>`
+- 验收标准: `<acceptance>`
+- 测试命令: `<test_command>`
+
+如果下面引用的 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+
+## 必查项
+
+1. `task.json` 中只有当前任务的 `passes` 被改为 `true`。
+2. `progress.txt` 包含当前任务的完成记录。
+3. 代码或文档改动与任务描述一致。
+4. 没有无关文件、临时文件、密钥或调试输出。
+5. 测试命令已经运行且结果可信。
+6. 如果任务使用了 `docs/knowledge/`，最终报告包含对应 `knowledge_references`。
+7. 如果任务产生了可复用经验，最终报告包含 `knowledge_outputs` 或说明没有可归档条目。
+8. 如果有失败风险，按严重程度列出发现。
+
+## 输出格式
+
+```markdown
+## Findings
+
+- [severity] 文件:行 - 问题说明
+
+## Verification
+
+- 已检查的命令和结果
+
+## Residual Risk
+
+- 剩余风险或测试缺口
+```
+
+如果没有发现问题，明确写：
+
+```text
+未发现阻塞性问题。
+```

package/package-source/docs/codex-harness-engineering/templates/prompts/review-stage1-spec.md

@@ -1,109 +1,111 @@
-# Stage 1 Review Prompt 模板
-
-你是 Stage 1 Reviewer。只审查**当前实现是否符合 Product Spec / Design Brief / 设计稿 / DEV-PLAN**，不要讨论代码风格。
-
-## 当前任务
-
-- Task ID: `<task-id>`
-- 描述: `<task-description>`
-- Task Kind: `<task-kind>`
-- Gate Profile: `<gate-profile>`
-- 对应 Phase: `<phase>`
-
-## 真相源
-
-- Truth source completeness: `<truth-source-state>`
-- Product Spec: `<product-spec>`
-- Design Brief: `<design-brief>`
-- Testing truth source: `<testing-truth-source>`
-- Knowledge Catalog: `docs/knowledge/knowledge-catalog.md` / `docs/knowledge/catalog.md`（如存在）
-- Architecture Constraints Packet: Driver Context 中声明的架构约束 truth source（默认 `docs/architecture/constraints.md`，如存在）
-- 设计稿 / Figma: `<design-source>`
-- DEV-PLAN: `<dev-plan>`
-- 状态矩阵: `<state-matrix>`
-
-## 必查项
-
-1. 先审查 Architecture Constraints Packet：交付形态、公开入口、数据边界、异步边界、测试替身策略、禁止实现和 Definition of Done 是否已按当前项目明确；不适用项必须标记 `not_applicable`。
-2. 如果当前任务是需要架构门禁的 `feature_impl`，是否携带 `architecture_constraints`、`forbidden_implementations` 和能验证声明交付形态的 `test_command`。
-3. 当前实现是否符合声明的交付形态；例如服务型项目应有声明的公开入口证据，库项目应有 package API 证据，CLI 应有命令入口证据，纯前端应有页面/路由和浏览器证据。
-4. 是否使用测试替身、mock、fixture、local-only adapter 或领域原型替代声明交付路径；除非任务明确允许，否则这类情况必须 FAIL。
-5. Contract / OpenAPI / protobuf / GraphQL schema / package API / CLI help / 页面路由等公开契约是否能追踪到实现、测试和证据路径。
-6. 功能有没有漏实现。
-7. 有没有多做 Product Spec 没要求的内容。
-8. 每条 P0/P1 需求是否有 Requirement ID，并且能追溯到页面、状态、字段、操作、接口、测试和验收。
-9. 是否存在“页面有功能但需求没有”的多余实现。
-10. 高风险难点是否已在 `difficulty-research.md` 中提前研究并落实到计划。
-11. 页面状态是否完整：`default / empty / loading / error / disabled / permission / mobile`。
-12. 页面状态是否有真实实现入口：代码里能追溯到状态源、渲染分支、触发条件和复验证据，而不是把状态名称写成界面说明文案。
-13. 是否存在“状态文案化”冒充实现：例如 UI 中出现“loading 状态”“错误状态展示”“权限态如下”等评审占位文字，但代码没有对应 loading/error/permission/empty/disabled 分支；如有必须按 `state_gap` FAIL。
-14. AI 生成界面图是否已通过 `ui-image-review.md`，并已转成 `image-to-frontend-spec.md`。
-15. 前端 UI 任务是否已在真实浏览器截图，并把截图保存到 `artifacts/visual-review/`。
-16. 浏览器实拍图是否已和设计参考图通过 `visual-parity-review.md` 完成对比，且 Verdict 为 PASS。
-17. 交互是否与设计稿、Design Brief、CSS/token 和 Image To Frontend Spec 冲突。
-18. 验收示例、TRACEABILITY_MATRIX、测试矩阵和任务上下文之间是否一致。
-19. P0/P1 PRD 需求是否已经在 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 中逐条生成自然语言测试用例，并绑定 Requirement ID、PRD 来源、Oracle、测试数据、证据路径和 TDD RED 预期失败。
-20. 自然语言测试用例是否按 `NATURAL_LANGUAGE_TEST_CASES.md` 的需求类型覆盖矩阵满足最小用例数，并记录需求类型、优先级、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数和风险加量理由。
-21. Contract 相关行为是否与当前 Spec 一致。
-22. 如果需求需要异常路径、权限路径或极端数据路径，这些路径是否已经进入测试或规格文档。
-23. P0/P1 或高风险需求是否已经先定义自然语言测试用例、测试意图和 Oracle，而不是直接生成脚本。
-24. 写操作、权限、状态机、异步链路是否在 `NATURAL_LANGUAGE_TEST_CASES.md`、`TRACEABILITY_MATRIX.md`、`test-matrix.md` 或 `verify-matrix.md` 中声明副作用或无副作用证据。
-25. 每个实现任务是否在 `qa_contract` 或等价任务字段中声明 `required_layers`、`story_full_chain`、`evidence` 和 `release_impact`；缺失时不得进入实现。
-26. 每个实现任务的 `qa_contract.tdd_contract.red.source_case_ids`、`story_full_chain.source_case_ids` 和 `acceptance_validation.source_case_ids` 是否能回溯到自然语言测试用例；缺失时不得进入实现。
-27. 实现任务是否有故事级完整链路验证；不能只声明单元测试、小范围 smoke 或 `git diff --check`。
-28. 测试数据是否能从 `TEST_DATA_MATRIX.md` 追溯到 seed、fixture、隔离或清理策略。
-29. 如果任务声明 `required_truth_sources` 包含 `knowledge`，或任务阶段是 `archive`，是否读取并使用了 `docs/knowledge/` 的索引与相关条目。
-30. 如果实现明显复用了项目经验，最终报告是否列出 `knowledge_references`；如果产生了可复用经验，是否列出 `knowledge_outputs` 建议。
-31. 是否把单次经验直接升级成 `AGENTS.md` 或全局规则；如有，必须有 proven evidence 或用户明确要求。
-
-如果当前任务涉及页面 UI，而缺少参考图、浏览器截图或视觉还原对比报告，Stage 1 必须输出 `FAIL`。只有在任务明确不是 UI 任务，或 `screen-states.md` / `image-to-frontend-spec.md` 明确豁免该状态时，才可以跳过视觉还原闸门。
-
-## 忽略项
-
-下面这些属于外层 driver 在 Stage 1 之后统一处理的状态收口，不要在 Stage 1 中作为失败项：
-
-- `task.json` 中的 `passes=true`
-- `progress.txt` 完成记录
-- `traces/` 目录和 trace 文件
-- 自动 `git commit`
-
-## Finding 规则
-
-每个问题都必须带 `finding_id`，格式建议为 `<task-id>-S1-F001`。每个 finding 必须包含：
-
-- severity: `HIGH` / `MEDIUM` / `LOW`
-- category: `architecture_gap` / `forbidden_implementation` / `missing_requirement` / `extra_scope` / `state_gap` / `visual_gap` / `contract_gap` / `truth_source_missing` / `oracle_gap` / `evidence_gap` / `full_chain_gap` / `knowledge_gap`
-- owner: `frontend` / `backend` / `contract` / `design` / `product` / `controller`
-- evidence: 文件路径、截图路径、日志路径或具体页面/状态
-- recommended_fix: 下一轮 repair worker 可直接执行的修复建议
-- retest_command: 推荐复验命令或报告路径
-
-## 输出格式
-
-```markdown
-## Stage 1 Findings
-
-| Finding ID | Severity | Category | Owner | Evidence | Recommended Fix | Retest |
-| --- | --- | --- | --- | --- | --- | --- |
-
-## Verdict
-
-- PASS
-- FAIL
-
-## Repair Queue
-
-| Finding ID | Owner | Suggested Worker Role | Retry Budget | Blocking |
-| --- | --- | --- | --- | --- |
-```
-
-规则:
-
-- 只要存在 `HIGH` 问题，结论必须是 `FAIL`。
-- 如果 `gate-profile` 不是 `lightweight`，缺少 required truth source 必须视为 `HIGH`。
-- 如果需要架构门禁的 `feature_impl` 缺少架构约束，或实现与声明的架构约束冲突，必须视为 `HIGH`。
-- 如果声明交付路径使用测试替身、local-only adapter 或领域原型冒充完成，必须视为 `HIGH`。
-- 如果 P0/P1 或高风险实现任务缺少故事级完整链路验证声明，必须视为 `HIGH`。
-- 如果前端状态只作为页面说明文案存在，没有对应状态源、渲染分支和可复验触发方式，必须视为 `HIGH`。
-- 不要在 Stage 1 讨论命名、格式化、测试框架选型这类代码质量问题。
-- 如果 `Verdict: FAIL`，`Repair Queue` 不能为空。
+# Stage 1 Review Prompt 模板
+
+你是 Stage 1 Reviewer。只审查**当前实现是否符合 Product Spec / Design Brief / 设计稿 / DEV-PLAN**，不要讨论代码风格。
+
+## 当前任务
+
+- Task ID: `<task-id>`
+- 描述: `<task-description>`
+- Task Kind: `<task-kind>`
+- Gate Profile: `<gate-profile>`
+- 对应 Phase: `<phase>`
+
+## 真相源
+
+如果下面引用的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+
+- Truth source completeness: `<truth-source-state>`
+- Product Spec: `<product-spec>`
+- Design Brief: `<design-brief>`
+- Testing truth source: `<testing-truth-source>`
+- Knowledge Catalog: `docs/knowledge/knowledge-catalog.md` / `docs/knowledge/catalog.md`（如存在）
+- Architecture Constraints Packet: Driver Context 中声明的架构约束 truth source（默认 `docs/architecture/constraints.md`，如存在）
+- 设计稿 / Figma: `<design-source>`
+- DEV-PLAN: `<dev-plan>`
+- 状态矩阵: `<state-matrix>`
+
+## 必查项
+
+1. 先审查 Architecture Constraints Packet：交付形态、公开入口、数据边界、异步边界、测试替身策略、禁止实现和 Definition of Done 是否已按当前项目明确；不适用项必须标记 `not_applicable`。
+2. 如果当前任务是需要架构门禁的 `feature_impl`，是否携带 `architecture_constraints`、`forbidden_implementations` 和能验证声明交付形态的 `test_command`。
+3. 当前实现是否符合声明的交付形态；例如服务型项目应有声明的公开入口证据，库项目应有 package API 证据，CLI 应有命令入口证据，纯前端应有页面/路由和浏览器证据。
+4. 是否使用测试替身、mock、fixture、local-only adapter 或领域原型替代声明交付路径；除非任务明确允许，否则这类情况必须 FAIL。
+5. Contract / OpenAPI / protobuf / GraphQL schema / package API / CLI help / 页面路由等公开契约是否能追踪到实现、测试和证据路径。
+6. 功能有没有漏实现。
+7. 有没有多做 Product Spec 没要求的内容。
+8. 每条 P0/P1 需求是否有 Requirement ID，并且能追溯到页面、状态、字段、操作、接口、测试和验收。
+9. 是否存在“页面有功能但需求没有”的多余实现。
+10. 高风险难点是否已在 `difficulty-research.md` 中提前研究并落实到计划。
+11. 页面状态是否完整：`default / empty / loading / error / disabled / permission / mobile`。
+12. 页面状态是否有真实实现入口：代码里能追溯到状态源、渲染分支、触发条件和复验证据，而不是把状态名称写成界面说明文案。
+13. 是否存在“状态文案化”冒充实现：例如 UI 中出现“loading 状态”“错误状态展示”“权限态如下”等评审占位文字，但代码没有对应 loading/error/permission/empty/disabled 分支；如有必须按 `state_gap` FAIL。
+14. AI 生成界面图是否已通过 `ui-image-review.md`，并已转成 `image-to-frontend-spec.md`。
+15. 前端 UI 任务是否已在真实浏览器截图，并把截图保存到 `artifacts/visual-review/`。
+16. 浏览器实拍图是否已和设计参考图通过 `visual-parity-review.md` 完成对比，且 Verdict 为 PASS。
+17. 交互是否与设计稿、Design Brief、CSS/token 和 Image To Frontend Spec 冲突。
+18. 验收示例、TRACEABILITY_MATRIX、测试矩阵和任务上下文之间是否一致。
+19. P0/P1 PRD 需求是否已经在 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 中逐条生成自然语言测试用例，并绑定 Requirement ID、PRD 来源、Oracle、测试数据、证据路径和 TDD RED 预期失败。
+20. 自然语言测试用例是否按 `NATURAL_LANGUAGE_TEST_CASES.md` 的需求类型覆盖矩阵满足最小用例数，并记录需求类型、优先级、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数和风险加量理由。
+21. Contract 相关行为是否与当前 Spec 一致。
+22. 如果需求需要异常路径、权限路径或极端数据路径，这些路径是否已经进入测试或规格文档。
+23. P0/P1 或高风险需求是否已经先定义自然语言测试用例、测试意图和 Oracle，而不是直接生成脚本。
+24. 写操作、权限、状态机、异步链路是否在 `NATURAL_LANGUAGE_TEST_CASES.md`、`TRACEABILITY_MATRIX.md`、`test-matrix.md` 或 `verify-matrix.md` 中声明副作用或无副作用证据。
+25. 每个实现任务是否在 `qa_contract` 或等价任务字段中声明 `required_layers`、`story_full_chain`、`evidence` 和 `release_impact`；缺失时不得进入实现。
+26. 每个实现任务的 `qa_contract.tdd_contract.red.source_case_ids`、`story_full_chain.source_case_ids` 和 `acceptance_validation.source_case_ids` 是否能回溯到自然语言测试用例；缺失时不得进入实现。
+27. 实现任务是否有故事级完整链路验证；不能只声明单元测试、小范围 smoke 或 `git diff --check`。
+28. 测试数据是否能从 `TEST_DATA_MATRIX.md` 追溯到 seed、fixture、隔离或清理策略。
+29. 如果任务声明 `required_truth_sources` 包含 `knowledge`，或任务阶段是 `archive`，是否读取并使用了 `docs/knowledge/` 的索引与相关条目。
+30. 如果实现明显复用了项目经验，最终报告是否列出 `knowledge_references`；如果产生了可复用经验，是否列出 `knowledge_outputs` 建议。
+31. 是否把单次经验直接升级成 `AGENTS.md` 或全局规则；如有，必须有 proven evidence 或用户明确要求。
+
+如果当前任务涉及页面 UI，而缺少参考图、浏览器截图或视觉还原对比报告，Stage 1 必须输出 `FAIL`。只有在任务明确不是 UI 任务，或 `screen-states.md` / `image-to-frontend-spec.md` 明确豁免该状态时，才可以跳过视觉还原闸门。
+
+## 忽略项
+
+下面这些属于外层 driver 在 Stage 1 之后统一处理的状态收口，不要在 Stage 1 中作为失败项：
+
+- `task.json` 中的 `passes=true`
+- `progress.txt` 完成记录
+- `traces/` 目录和 trace 文件
+- 自动 `git commit`
+
+## Finding 规则
+
+每个问题都必须带 `finding_id`，格式建议为 `<task-id>-S1-F001`。每个 finding 必须包含：
+
+- severity: `HIGH` / `MEDIUM` / `LOW`
+- category: `architecture_gap` / `forbidden_implementation` / `missing_requirement` / `extra_scope` / `state_gap` / `visual_gap` / `contract_gap` / `truth_source_missing` / `oracle_gap` / `evidence_gap` / `full_chain_gap` / `knowledge_gap`
+- owner: `frontend` / `backend` / `contract` / `design` / `product` / `controller`
+- evidence: 文件路径、截图路径、日志路径或具体页面/状态
+- recommended_fix: 下一轮 repair worker 可直接执行的修复建议
+- retest_command: 推荐复验命令或报告路径
+
+## 输出格式
+
+```markdown
+## Stage 1 Findings
+
+| Finding ID | Severity | Category | Owner | Evidence | Recommended Fix | Retest |
+| --- | --- | --- | --- | --- | --- | --- |
+
+## Verdict
+
+- PASS
+- FAIL
+
+## Repair Queue
+
+| Finding ID | Owner | Suggested Worker Role | Retry Budget | Blocking |
+| --- | --- | --- | --- | --- |
+```
+
+规则:
+
+- 只要存在 `HIGH` 问题，结论必须是 `FAIL`。
+- 如果 `gate-profile` 不是 `lightweight`，缺少 required truth source 必须视为 `HIGH`。
+- 如果需要架构门禁的 `feature_impl` 缺少架构约束，或实现与声明的架构约束冲突，必须视为 `HIGH`。
+- 如果声明交付路径使用测试替身、local-only adapter 或领域原型冒充完成，必须视为 `HIGH`。
+- 如果 P0/P1 或高风险实现任务缺少故事级完整链路验证声明，必须视为 `HIGH`。
+- 如果前端状态只作为页面说明文案存在，没有对应状态源、渲染分支和可复验触发方式，必须视为 `HIGH`。
+- 不要在 Stage 1 讨论命名、格式化、测试框架选型这类代码质量问题。
+- 如果 `Verdict: FAIL`，`Repair Queue` 不能为空。

package/package-source/docs/codex-harness-engineering/templates/prompts/review-stage2-quality.md

@@ -1,80 +1,82 @@
-# Stage 2 Review Prompt 模板
-
-你是 Stage 2 Reviewer。Stage 1 已通过。现在只审查**代码质量、测试、风险和可维护性**，不要重新做需求裁判。
-
-## 当前任务
-
-- Task ID: `<task-id>`
-- 描述: `<task-description>`
-- 测试命令: `<test-command>`
-
-## 必查项
-
-1. 类型是否正确，是否有明显不安全或逃逸类型。
-2. 命名、模块边界、职责分离是否清晰。
-3. 是否有无关文件、临时代码、调试输出、硬编码密钥。
-4. 改动代码是否有对应测试、契约验证或证据路径；如果没有，是否给出可信豁免。
-5. 测试是否覆盖关键行为、异常流、权限路径和历史回归路径。
-6. 是否存在“只 mock 不验证结果”“只测 happy path”“跳过失败测试”或其它假测试迹象。
-7. 写操作是否至少验证 DB、缓存、事件、审计、通知、文件或其他业务副作用之一。
-8. 权限拒绝、非法状态、参数校验失败和重放请求是否验证无副作用、无泄露和无缓存污染。
-9. 测试是否绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
-10. 是否存在 mock 被测 service、权限判断、状态机、数据库写入或核心业务路径的问题。
-11. 如果任务声明了 `architecture_constraints` 或 `forbidden_implementations`，测试是否覆盖对应架构约束；例如公开入口、真实数据边界、worker/异步边界、包导出、页面路由、文件格式或禁止使用测试替身。
-12. 验证结果是否可信，是否缺少 affected tests、契约检查、fresh evidence 或目标路径命中证据。
-13. 是否把编码过程中的开发验证误当成最终验收验证；单元、组件、局部 smoke、类型检查、lint 或 affected tests 只能证明开发过程反馈，不能替代用户 / 验收 / 发布视角完整链路。
-14. 对 `feature_impl`，是否在代码写完后运行了任务声明的用户故事验收链路；只跑单元测试、小范围 smoke、静态检查或局部组件测试不能作为完成证据。
-15. 对 `feature_impl` 且 `qa_contract.tdd_contract.policy=required`，是否存在 RED 失败证据、GREEN 通过证据和 REFACTOR guard 证据；缺任何一项都视为 TDD 证据缺口。
-16. `tdd_contract.red.source_case_ids` 是否能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`；无法回溯时必须 FAIL。
-17. `story_full_chain.source_case_ids` 和 `acceptance_validation.source_case_ids` 是否覆盖非 TDD 自然语言用例；如果非 TDD 用例没有进入验收、回归或 verify-matrix，必须 FAIL。
-18. 自然语言测试用例是否按需求类型覆盖矩阵达到最少用例数；如果 P0/P1 写操作、权限、状态机、异步链路或高风险需求只覆盖 happy path，必须 FAIL。
-19. RED 日志是否显示测试先于生产代码验证目标行为缺失；如果 RED 直接通过，或失败原因是语法错误、导入错误、环境错误、测试数据错误、mock 行为或无效断言，必须 FAIL。
-20. GREEN 是否复跑与 RED 相同的聚焦测试命令；重构后是否运行 `refactor_guard.command`；如果命令或证据路径缺失，必须 FAIL。
-21. 是否存在实现后补测试、测试只覆盖实现细节、测试只验证 mock、测试名称覆盖多行为但实际只跑 happy path 等 TDD 违规迹象。
-22. 对 `release`，是否运行了发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证，并把失败态证据写入报告。
-23. 是否存在明显性能、可访问性或回归风险。
-24. 如果本次修复了历史坑或形成了可复用经验，是否在最终报告中给出 `knowledge_outputs` 建议，供 `ARCHIVE-*` 任务归档。
-25. 如果代码或文档决策依赖 `docs/knowledge/`，是否给出 `knowledge_references`，避免知识只存在于会话上下文。
-
-## Finding 规则
-
-每个问题都必须带 `finding_id`，格式建议为 `<task-id>-S2-F001`。每个 finding 必须包含：
-
-- severity: `HIGH` / `MEDIUM` / `LOW`
-- category: `type_safety` / `test_gap` / `tdd_violation` / `architecture_test_gap` / `oracle_gap` / `side_effect_gap` / `fake_test` / `full_chain_gap` / `security` / `performance` / `maintainability` / `artifact_gap` / `environment` / `knowledge_gap`
-- owner: `frontend` / `backend` / `test` / `security` / `docs` / `controller`
-- evidence: 文件路径、测试输出、日志路径或命令结果
-- recommended_fix: 下一轮 repair worker 可直接执行的修复建议
-- retest_command: 推荐复验命令
-
-## 输出格式
-
-```markdown
-## Stage 2 Findings
-
-| Finding ID | Severity | Category | Owner | Evidence | Recommended Fix | Retest |
-| --- | --- | --- | --- | --- | --- | --- |
-
-## Verification
-
-- 已检查命令:
-- 结果摘要:
-
-## Verdict
-
-- PASS
-- FAIL
-
-## Repair Queue
-
-| Finding ID | Owner | Suggested Worker Role | Retry Budget | Blocking |
-| --- | --- | --- | --- | --- |
-```
-
-规则:
-
-- `HIGH` 问题存在时必须 `FAIL`。
-- 如果测试覆盖明显不足，也可以直接 `FAIL`。
-- 如果 `feature_impl` 声明 TDD required 但缺少可信自然语言用例来源、需求类型最小覆盖、非 TDD 用例验收映射或 RED/GREEN/REFACTOR 证据，必须 `FAIL`。
-- 允许提出 `LOW` 级建议，但不要把风格偏好伪装成阻塞问题。
-- 如果 `Verdict: FAIL`，`Repair Queue` 不能为空。
+# Stage 2 Review Prompt 模板
+
+你是 Stage 2 Reviewer。Stage 1 已通过。现在只审查**代码质量、测试、风险和可维护性**，不要重新做需求裁判。
+
+## 当前任务
+
+- Task ID: `<task-id>`
+- 描述: `<task-description>`
+- 测试命令: `<test-command>`
+
+如果下面引用的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+
+## 必查项
+
+1. 类型是否正确，是否有明显不安全或逃逸类型。
+2. 命名、模块边界、职责分离是否清晰。
+3. 是否有无关文件、临时代码、调试输出、硬编码密钥。
+4. 改动代码是否有对应测试、契约验证或证据路径；如果没有，是否给出可信豁免。
+5. 测试是否覆盖关键行为、异常流、权限路径和历史回归路径。
+6. 是否存在“只 mock 不验证结果”“只测 happy path”“跳过失败测试”或其它假测试迹象。
+7. 写操作是否至少验证 DB、缓存、事件、审计、通知、文件或其他业务副作用之一。
+8. 权限拒绝、非法状态、参数校验失败和重放请求是否验证无副作用、无泄露和无缓存污染。
+9. 测试是否绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
+10. 是否存在 mock 被测 service、权限判断、状态机、数据库写入或核心业务路径的问题。
+11. 如果任务声明了 `architecture_constraints` 或 `forbidden_implementations`，测试是否覆盖对应架构约束；例如公开入口、真实数据边界、worker/异步边界、包导出、页面路由、文件格式或禁止使用测试替身。
+12. 验证结果是否可信，是否缺少 affected tests、契约检查、fresh evidence 或目标路径命中证据。
+13. 是否把编码过程中的开发验证误当成最终验收验证；单元、组件、局部 smoke、类型检查、lint 或 affected tests 只能证明开发过程反馈，不能替代用户 / 验收 / 发布视角完整链路。
+14. 对 `feature_impl`，是否在代码写完后运行了任务声明的用户故事验收链路；只跑单元测试、小范围 smoke、静态检查或局部组件测试不能作为完成证据。
+15. 对 `feature_impl` 且 `qa_contract.tdd_contract.policy=required`，是否存在 RED 失败证据、GREEN 通过证据和 REFACTOR guard 证据；缺任何一项都视为 TDD 证据缺口。
+16. `tdd_contract.red.source_case_ids` 是否能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`；无法回溯时必须 FAIL。
+17. `story_full_chain.source_case_ids` 和 `acceptance_validation.source_case_ids` 是否覆盖非 TDD 自然语言用例；如果非 TDD 用例没有进入验收、回归或 verify-matrix，必须 FAIL。
+18. 自然语言测试用例是否按需求类型覆盖矩阵达到最少用例数；如果 P0/P1 写操作、权限、状态机、异步链路或高风险需求只覆盖 happy path，必须 FAIL。
+19. RED 日志是否显示测试先于生产代码验证目标行为缺失；如果 RED 直接通过，或失败原因是语法错误、导入错误、环境错误、测试数据错误、mock 行为或无效断言，必须 FAIL。
+20. GREEN 是否复跑与 RED 相同的聚焦测试命令；重构后是否运行 `refactor_guard.command`；如果命令或证据路径缺失，必须 FAIL。
+21. 是否存在实现后补测试、测试只覆盖实现细节、测试只验证 mock、测试名称覆盖多行为但实际只跑 happy path 等 TDD 违规迹象。
+22. 对 `release`，是否运行了发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证，并把失败态证据写入报告。
+23. 是否存在明显性能、可访问性或回归风险。
+24. 如果本次修复了历史坑或形成了可复用经验，是否在最终报告中给出 `knowledge_outputs` 建议，供 `ARCHIVE-*` 任务归档。
+25. 如果代码或文档决策依赖 `docs/knowledge/`，是否给出 `knowledge_references`，避免知识只存在于会话上下文。
+
+## Finding 规则
+
+每个问题都必须带 `finding_id`，格式建议为 `<task-id>-S2-F001`。每个 finding 必须包含：
+
+- severity: `HIGH` / `MEDIUM` / `LOW`
+- category: `type_safety` / `test_gap` / `tdd_violation` / `architecture_test_gap` / `oracle_gap` / `side_effect_gap` / `fake_test` / `full_chain_gap` / `security` / `performance` / `maintainability` / `artifact_gap` / `environment` / `knowledge_gap`
+- owner: `frontend` / `backend` / `test` / `security` / `docs` / `controller`
+- evidence: 文件路径、测试输出、日志路径或命令结果
+- recommended_fix: 下一轮 repair worker 可直接执行的修复建议
+- retest_command: 推荐复验命令
+
+## 输出格式
+
+```markdown
+## Stage 2 Findings
+
+| Finding ID | Severity | Category | Owner | Evidence | Recommended Fix | Retest |
+| --- | --- | --- | --- | --- | --- | --- |
+
+## Verification
+
+- 已检查命令:
+- 结果摘要:
+
+## Verdict
+
+- PASS
+- FAIL
+
+## Repair Queue
+
+| Finding ID | Owner | Suggested Worker Role | Retry Budget | Blocking |
+| --- | --- | --- | --- | --- |
+```
+
+规则:
+
+- `HIGH` 问题存在时必须 `FAIL`。
+- 如果测试覆盖明显不足，也可以直接 `FAIL`。
+- 如果 `feature_impl` 声明 TDD required 但缺少可信自然语言用例来源、需求类型最小覆盖、非 TDD 用例验收映射或 RED/GREEN/REFACTOR 证据，必须 `FAIL`。
+- 允许提出 `LOW` 级建议，但不要把风格偏好伪装成阻塞问题。
+- 如果 `Verdict: FAIL`，`Repair Queue` 不能为空。