@pzy560117/codex-harness 0.1.8 → 0.1.9

package/README.md

@@ -106,7 +106,7 @@ harness init --plan
 ### 钉住远程版本初始化
 
 ```powershell
-npx @pzy560117/codex-harness init --version 0.1.8
+npx @pzy560117/codex-harness init --version 0.1.9
 ```
 
 适合 release smoke 或回滚到某个已发布版本。

package/package-source/AGENTS.md

@@ -14,6 +14,13 @@
 - `feature_impl` 没有 `qa_contract` 不得进入正式任务队列；`qa_contract` 没有完整 `tdd_contract`、`development_validation`、`acceptance_validation` 不得开始实现。
 - 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
 
+## 子目录 AGENTS 规则
+
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`。
+- 目录级 `AGENTS.md` 负责承载局部职责、边界、入口、测试命令、复用模式、坑点和禁止事项；不要把这类规则长期堆在根 `AGENTS.md`。
+- 自动托管区块 `AUTO-MODULE-FACTS` 只补动态事实，不等于目录规则完整；即使 facts 已自动刷新，仍需要有人维护手写的局部规则部分。
+- 如果 `task.json.owned_paths`、`docs/ai/repo-map.md` 或模块边界已经明确某目录是独立模块，而该目录缺少子目录 `AGENTS.md`，应视为至少 `warn`，高风险目录应直接阻断进入正式任务队列或实现阶段。
+
 ## 目录级规则
 
 - 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：
@@ -32,7 +39,10 @@
 
 ## 必读索引
 
-如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下查同路径文件。
+如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：
+- `docs/harness/*` -> `docs/codex-harness-engineering/templates/docs/*`
+- `docs/testing/*` -> `docs/codex-harness-engineering/templates/testing/*`
+- `docs/knowledge/*` -> `docs/codex-harness-engineering/templates/knowledge/*`
 
 - Harness 分层分析索引：`harness-analysis/README.md`
 - Codex Harness Engineering 总览：`docs/codex-harness-engineering/README.md`

package/package-source/docs/codex-harness-engineering/templates/config/rules/agents.md

@@ -34,11 +34,11 @@ trigger: always_on
 | `contract-designer` | OpenAPI、mock、client 生成、字段和错误码契约 | `api-contract-template`, `api-design` | Contract First |
 | `backend-worker` | API、数据库、权限、异常流、后端测试 | `backend-patterns`, `database`, 项目后端技能 | 后端实现 |
 | `integration-worker` | 前后端联调、mock 切真实服务、主流程 E2E | `api-integration`, `fullstack-workflow` | Integration |
-| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划和证据路径 | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
+| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划、影响面和证据路径；高风险用户可见任务要明确是否需要 `e2e-plan.md` | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
 | `test-runner` | 运行确定性验证、汇总失败、写测试报告 | `e2e-runner`, `qa-e2e-runner`, `verify` | Verify / Regression |
 | `stage1-reviewer` | 产品、设计、计划一致性审查 | `spec-based-review`, `spec-review` | Stage 1 Review |
 | `stage2-reviewer` | 代码质量、测试覆盖、回归风险审查 | `code-reviewer`, `security-reviewer` | Stage 2 Review |
-| `failure-triage` | 失败归因、owner 分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
+| `failure-triage` | 失败一级分类、owner 二级分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
 | `repair-worker` | 按 finding 定点修复并复验 | 原开发 agent + `repair-one-finding.md` | 修复闭环 |
 | `docs-worker` | 文档、索引、使用指南、模板同步 | `doc-updater`, `update-docs` | 文档更新和交付归档 |
 | `security-reviewer` | 权限、认证、支付、密钥、敏感数据和 sandbox 风险 | `security-reviewer`, `security-review` | 高风险功能 |
@@ -86,7 +86,7 @@ trigger: always_on
 
 ## 子代理前置读取规则
 
-- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）和本文件。
+- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）和本文件。
 - 子代理必须再读取该角色对应的 `.agents/skills/*/SKILL.md`（如存在）、项目 truth source 和必要的深文档，再输出结论。
 - 如果当前轮次是被 stop hook / continuation gate 强制继续后的续跑，先重新阅读上面这些文档，再决定是否真的需要子代理。
 - 只读辅助子代理默认只读，不直接写业务代码，不修改 `task.json`、`progress.txt`、`traces/`。

package/package-source/docs/codex-harness-engineering/templates/docs/project-agents-template.md

@@ -8,6 +8,7 @@
 - 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
 - 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
 - 根 `AGENTS.md` 只写全项目都成立的入口规则；目录独有的模块职责、边界、入口、测试命令、坑点和禁止事项，优先写进最接近该目录的子目录 `AGENTS.md`。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`；不要等 review 发现目录规则缺口后再补。
 - 如果项目同时维护模板源、镜像和运行时副本，先确认哪一份是 canonical；默认优先修改模板 canonical，再同步活跃副本，不要只修当前工作区现状。
 - 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
 - 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
@@ -29,6 +30,7 @@
 | 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
 | 自动化检查 | linter、formatter、typecheck、CI、hooks |
 | 命名与业务词典 | `docs/harness/code-style-and-naming.md`、`docs/code-style.md`、接口 / 数据字典 |
+| 目录级规则覆盖 | `owned_paths`、`docs/ai/repo-map.md`、现有子目录 `AGENTS.md`、模块入口文件 |
 | 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
 | Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
 
@@ -57,6 +59,7 @@
 - 真实入口：<启动、构建、测试、driver 或任务系统入口>
 - 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
 - 如果存在目录级 `AGENTS.md`：进入对应目录后同时遵守根规则和本地规则。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须同步更新对应子目录 `AGENTS.md`。
 - 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
 
 ## 模板与 Canonical
@@ -143,7 +146,7 @@
 
 ## 子目录 AGENTS.md 模板
 
-只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
+只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。一旦目录已具备独立模块职责、入口、测试命令或反复出现局部坑点，就不应继续把规则堆在根入口文件里。
 
 ````markdown
 # <path> AGENTS.md
@@ -152,6 +155,7 @@
 
 - 本文件只适用于 `<path>/` 下的改动。
 - 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
+- 如果存在 `<!-- BEGIN AUTO-MODULE-FACTS -->` 托管区块，它只维护动态事实；手写规则必须保留在托管区块外。
 
 ## 本目录约束
 
@@ -162,6 +166,7 @@
 - 修改前必须先看：<核心文件 / 规则 / 测试>
 - 测试命令：<目录级验证命令>
 - 常见复用对象：<组件 / hook / service / helper / fixture>
+- 常见坑和禁止事项：<本目录专属坑点，以及对应替代方案>
 
 ## 决策表
 
@@ -204,6 +209,8 @@
 | 是否包含通用编码常识 | 删除 |
 | 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
 | 是否把目录级规则堆在根 AGENTS.md | 下沉到最接近适用范围的子目录 `AGENTS.md` |
+| 是否新增了独立模块目录却没有子目录 `AGENTS.md` | 立即补齐，至少写职责、边界、入口、测试命令和局部禁止事项 |
+| 子目录 `AGENTS.md` 是否只剩 `AUTO-MODULE-FACTS` 托管区块 | 补手写规则，不要把动态 facts 当成目录规则完成态 |
 | 是否没有说明 canonical | 补充模板源 / 活跃副本 / 运行时副本的优先级 |
 | 禁令是否没有替代方案 | 补替代方案或降级为风险 |
 | 是否引用不存在的命令或路径 | 修正或删除 |

package/package-source/docs/codex-harness-engineering/templates/docs/task-session-strategy.md

@@ -27,10 +27,12 @@
 - 如果 `task.json` 为空文件，先初始化为合法 JSON；如果仍是 smoke 模板或示例任务，先替换为当前项目真实任务。
 - 交互开发模式可以决定新增或更新哪些待办任务，但实际写入必须委派给 `harness-writer` 等匹配 writer。
 - 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
+- 创建或重建任务队列时，必须根据 `owned_paths`、`docs/ai/repo-map.md` 和模块职责判断哪些目录需要局部规则；命中独立模块目录却缺少子目录 `AGENTS.md` 时，不得把该任务队列视为正式完成。
 - 任务进入 driver 前必须冻结交付语义：`scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`。不适用字段必须写 `not_applicable`，不能留给实现会话猜。
 - 进入实现前，`docs/ai/CURRENT_TASK.md` 必须能回答本轮已完成内容、剩余问题、修改文件、测试结果、风险点和下一步，不允许只靠聊天记忆续跑。
 - `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 的 testing truth source 产物必须在生成最终 `task.json` 前补齐：`docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/REGRESSION_PLAN.md`、`docs/testing/verify-matrix.md`。缺任一项都不得进入正式任务队列。
 - 创建或重建任务队列时必须一次性补齐每个任务的完整交接字段：`requirement_ids`、`owned_paths`、`context_files`、`produces_artifacts`、`test_command`、`acceptance`、自然语言测试用例、测试数据、开发验证、最终验收验证、证据路径和 `qa_contract`。不得创建“先跑起来、后面再补测试/证据/整链路”的实现任务。
+- 自动刷新出来的 `AUTO-MODULE-FACTS` 只能证明目录事实被收集，不代表目录级规则完整；如果模块目录只有托管 facts 而没有职责、边界、入口、测试或禁止事项等手写规则，应继续标记为待补齐，而不是当作完成态。
 - PRD / 需求文档完成后、进入实现前必须有自然语言测试用例阶段；每条 P0/P1 需求必须按 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 的需求类型覆盖矩阵满足最小用例数，并回溯到 Requirement ID、PRD 来源、Oracle、测试数据、证据路径和 TDD RED 预期失败。
 - 每个 `feature_impl` 任务必须声明两段验证：`development_validation` 用于编码过程中的 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint；`acceptance_validation` 用于代码写完后从用户故事入口重新跑完整链路。
 - 每个 `feature_impl.qa_contract.tdd_contract.red.source_case_ids` 必须能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`；缺少自然语言用例来源时不得进入实现阶段。
@@ -125,6 +127,7 @@
 - 先收敛 truth source，再进入实现。
 - 大任务先拆成多个 `single` 任务，再交给 driver 顺序执行。
 - 当主控遇到文档、规则、任务队列、前端、后端或测试相关写入时，分别委派 `docs-worker`、`harness-writer`、`frontend-worker`、`backend-worker`、`test-runner` 等 writer 角色处理。
+- 目录级规则变化优先落到最接近该目录的子目录 `AGENTS.md`；根 `AGENTS.md` 只保留全局入口规则。
 - 实现阶段可以使用子代理并行加速，但必须按 owned paths 或明确文件组拆分；如需并行写入，不允许多个角色同时写同一路径。
 - 每个 writer 子代理启动前必须声明允许修改、禁止修改、验收输出和验证命令；只读子代理只能返回结构化结论。
 - 子代理不得修改 `task.json`、`progress.txt`、`traces/` 或 Git 状态；主实现会话必须整合子代理输出并运行当前任务 `test_command`。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/project-agents-template.md

@@ -8,6 +8,7 @@
 - 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
 - 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
 - 根 `AGENTS.md` 只写全项目都成立的入口规则；目录独有的模块职责、边界、入口、测试命令、坑点和禁止事项，优先写进最接近该目录的子目录 `AGENTS.md`。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`；不要等 review 发现目录规则缺口后再补。
 - 如果项目同时维护模板源、镜像和运行时副本，先确认哪一份是 canonical；默认优先修改模板 canonical，再同步活跃副本，不要只修当前工作区现状。
 - 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
 - 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
@@ -28,9 +29,22 @@
 | 代码地图 | `docs/ai/repo-map.md`、`codemaps/*`、架构索引或模块清单 |
 | 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
 | 自动化检查 | linter、formatter、typecheck、CI、hooks |
+| 命名与业务词典 | `docs/harness/code-style-and-naming.md`、`docs/code-style.md`、接口 / 数据字典 |
+| 目录级规则覆盖 | `owned_paths`、`docs/ai/repo-map.md`、现有子目录 `AGENTS.md`、模块入口文件 |
 | 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
 | Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
 
+最小核心文档集建议至少覆盖：
+
+- `AGENTS.md`
+- `README.md`
+- `docs/architecture.md`
+- `docs/code-style.md`
+- `docs/api-convention.md`
+- `docs/component-map.md`
+- `docs/test-strategy.md`
+- `docs/current-task.md`
+
 ## 根 AGENTS.md 模板
 
 ```markdown
@@ -45,6 +59,7 @@
 - 真实入口：<启动、构建、测试、driver 或任务系统入口>
 - 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
 - 如果存在目录级 `AGENTS.md`：进入对应目录后同时遵守根规则和本地规则。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须同步更新对应子目录 `AGENTS.md`。
 - 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
 
 ## 模板与 Canonical
@@ -71,12 +86,40 @@
 | <例如状态管理> | `<existing-pattern>` | <不要引入的新库> |
 | <例如数据访问> | `<repository/service>` | <不要跨层调用> |
 
+常见可直接复用的规则样板：
+
+```text
+前端：
+- 页面只负责展示和组合
+- 业务逻辑放 hooks
+- 接口请求放 services
+- 类型放 types
+- 常量放 constants
+- 公共组件放 components/common
+
+后端：
+- Controller 只处理请求和响应
+- Service 处理业务逻辑
+- Repository/DAO 处理数据库
+- DTO 处理输入输出结构
+```
+
 ## 项目硬约束
 
 - <CRITICAL 规则 1>；替代方案：<明确可执行做法>。
 - <CRITICAL 规则 2>；替代方案：<明确可执行做法>。
 - <安全 / 数据 / 权限 / 迁移 / 发布红线>；替代方案：<明确可执行做法>。
 
+常见禁止事项样板：
+
+```text
+- 禁止在页面组件中直接请求接口；替代方案：统一走 services / API client。
+- 禁止重复封装 axios/fetch；替代方案：复用现有 HTTP client。
+- 禁止在公共组件里写业务逻辑；替代方案：把业务逻辑下沉到 feature 或 hooks。
+- 禁止绕过权限系统；替代方案：复用既有权限入口或 policy。
+- 禁止新增 utils2、common2、helper2 这类目录；替代方案：放回既有模块或补目录级规则后再新增。
+```
+
 ## 测试与完成定义
 
 - 修改 <模块/路径> 后至少运行 `<command>`。
@@ -94,6 +137,7 @@
 
 - 架构：`<docs/architecture.md>`
 - 代码地图：`<docs/ai/repo-map.md>`
+- 代码风格 / 命名：`<docs/harness/code-style-and-naming.md 或 docs/code-style.md>`
 - API / 契约：`<docs/api.md>`
 - 测试策略：`<docs/testing.md>`
 - 部署 / 运维：`<docs/deploy.md>`
@@ -102,7 +146,7 @@
 
 ## 子目录 AGENTS.md 模板
 
-只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
+只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。一旦目录已具备独立模块职责、入口、测试命令或反复出现局部坑点，就不应继续把规则堆在根入口文件里。
 
 ````markdown
 # <path> AGENTS.md
@@ -111,6 +155,7 @@
 
 - 本文件只适用于 `<path>/` 下的改动。
 - 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
+- 如果存在 `<!-- BEGIN AUTO-MODULE-FACTS -->` 托管区块，它只维护动态事实；手写规则必须保留在托管区块外。
 
 ## 本目录约束
 
@@ -120,12 +165,15 @@
 - 入口文件：<真实入口>
 - 修改前必须先看：<核心文件 / 规则 / 测试>
 - 测试命令：<目录级验证命令>
+- 常见复用对象：<组件 / hook / service / helper / fixture>
+- 常见坑和禁止事项：<本目录专属坑点，以及对应替代方案>
 
 ## 决策表
 
 | 场景 | 应使用 | 不要使用 |
 | --- | --- | --- |
 | <场景> | <本目录模式> | <禁止做法> |
+| 复用同类能力 | <已有组件 / hook / service / helper> | <重复新建一套实现> |
 
 ## 代码示例
 
@@ -161,6 +209,8 @@
 | 是否包含通用编码常识 | 删除 |
 | 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
 | 是否把目录级规则堆在根 AGENTS.md | 下沉到最接近适用范围的子目录 `AGENTS.md` |
+| 是否新增了独立模块目录却没有子目录 `AGENTS.md` | 立即补齐，至少写职责、边界、入口、测试命令和局部禁止事项 |
+| 子目录 `AGENTS.md` 是否只剩 `AUTO-MODULE-FACTS` 托管区块 | 补手写规则，不要把动态 facts 当成目录规则完成态 |
 | 是否没有说明 canonical | 补充模板源 / 活跃副本 / 运行时副本的优先级 |
 | 禁令是否没有替代方案 | 补替代方案或降级为风险 |
 | 是否引用不存在的命令或路径 | 修正或删除 |

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/controller-loop.md

@@ -0,0 +1,88 @@
+# Controller Loop Prompt
+
+## 元信息
+
+- 版本: v1.1
+- 标签: codex, harness, controller, driver
+
+## 角色
+
+你是 Harness 主控 Agent。你负责读取任务、推进阶段、触发评审、整理证据和决定阻塞，不直接替代业务实现，也不直接写仓库文件。
+
+## 核心目标
+
+- 读取 `task.json`、`progress.txt`、`traces/` 和必要的 truth source。
+- 读取 `docs/knowledge/knowledge-catalog.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`） 和 `docs/knowledge/catalog.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`），判断当前阶段是否需要注入项目知识。
+- 选择下一步：执行单任务、进入审查、生成 repair task、继续等待、或 BLOCKED。
+- 保持任务边界、文件边界和验证边界清晰。
+- 确保所有通过结论都有 fresh verification evidence。
+- 任何非 driver 的仓库写入都先派给匹配的 writer 子代理；`progress.txt`、`traces/` 仍由 `tools/harness/codex-loop.ps1` 统一处理。
+
+## 决策顺序
+
+1. 检查 Git 工作区是否干净；默认只归因，不自动清理。只有当 stop hook 或 driver 已明确指出 dirty workspace 是当前唯一阻塞、仓库存在 `.agents/skills/auto-commit/SKILL.md`、改动属于当前任务且没有混入用户无关改动时，才允许先按 auto-commit skill 完成审查、验证和提交，再继续 driver。
+2. 读取待执行任务、依赖、gate、truth source 和验证命令。
+3. 如果任务涉及 harness、规则、prompt、trace、模板、review 或归档，先检查 `docs/harness/knowledge-architecture.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）、`docs/harness/rule-governance.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`） 和 `docs/knowledge/` 是否应作为上下文。
+4. 判断当前任务是否具备进入实现阶段的输入。
+5. 如需委派子代理，先确定它是只读辅助角色还是 writer 角色，并要求其先阅读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）、`.codex/rules/agents.md`、`docs/harness/knowledge-architecture.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）、相关 truth source 和 `.agents/skills/*/SKILL.md`（如存在）。
+6. 触发 driver 实现、writer 子代理、审查、测试、修复闭环或 `ARCHIVE-*` 知识归档。
+7. 对规则、文档、任务队列、prompt、配置等非 driver 内容，安排匹配的 writer 子代理落盘；运行时状态继续交给 `tools/harness/codex-loop.ps1`。
+8. 输出下一条可执行命令。
+
+## 禁止事项
+
+- 不要跳过 Stage 1、Stage 2、测试、视觉还原或 security gate。
+- 不要在没有 evidence 的情况下把任务判定为完成。
+- 不要伪造 `task.json`、`progress.txt` 或 `traces/` 的完成状态。
+- 不要把多个独立需求合并成一个实现任务。
+- 不要把混入用户无关改动的 dirty workspace 直接交给 auto-commit skill。
+- 不要让主控会话自己改 `task.json`、`AGENTS.md`、`.codex/*`、`.codex/rules/*`、`docs/harness/*`、prompt、spec、plan 或业务文件。
+- 不要让只读辅助子代理直接写文件，也不要跳过先读 skill / docs / rules 的步骤。
+- 不要把 draft 知识条目当作强约束；只有 verified / proven 或当前 truth source 明确要求时，才能作为阻塞依据。
+- 不要把一次性经验直接写入 `AGENTS.md`；先沉淀到 `docs/knowledge/`，再按 `docs/harness/rule-governance.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`） 判断是否升级。
+
+## 自动修复闭环
+
+当 Stage 1、Stage 2、测试、E2E 或视觉评审失败：
+
+1. 抽取 finding id、severity、owner、evidence path、recommended fix。
+2. 合并重复 finding，避免冲突修复。
+3. 生成修复任务或修复说明。
+4. 优先派给原实现链路修复。
+5. 由原测试或评审链路复验。
+6. 同一 finding 两次失败后升级模型和 reasoning effort。
+7. 达到 retry budget 后输出 BLOCKED。
+
+## 输出格式
+
+```markdown
+## Controller Decision
+
+- State: execute / review / repair / blocked / done
+- Reason: ...
+- Next command: `...`
+
+## Active Task
+
+- Task: ...
+- Gate: ...
+- Verification: ...
+
+## Findings Queue
+
+| Finding | Severity | Owner | Retry | Evidence | Next |
+| --- | --- | --- | --- | --- | --- |
+
+## Verification Evidence
+
+- ...
+
+## Knowledge Context
+
+- References:
+- Outputs / Archive Needed:
+
+## Risks
+
+- ...
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/failure-triage.md

@@ -0,0 +1,71 @@
+# Failure Triage Prompt
+
+## 元信息
+
+- 版本: v1.0
+- 标签: codex, harness, failure-triage, repair-loop
+
+## 角色
+
+你是失败归因 Agent。你只负责把失败证据转成结构化 findings，不直接修复代码。
+
+## 输入
+
+- 失败命令和退出码
+- 测试日志、构建日志、浏览器截图、trace、review report
+- 任务 ID、验收标准、owner、worker handoff
+- 当前 retry policy 和 model policy
+
+如果下面引用的 `docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`。
+
+## 归因规则
+
+1. 先输出一级分类：`TEST_CODE_ISSUE` / `PRODUCT_BUG` / `REQUIREMENT_CHANGE` / `ENV_OR_DATA_ISSUE` / `FLAKY`。
+2. 再区分失败来源：spec mismatch、visual mismatch、unit、integration、e2e、build、typecheck、lint、security、environment、unknown。
+3. 每个 finding 必须能追溯到具体证据路径或日志片段。
+4. 合并重复 finding，避免同一根因生成多个 repair task。
+5. 给出 owner：frontend、backend、test、visual-reviewer、docs、controller、environment。
+6. 给出推荐复验命令。
+7. 无法归因时输出 `owner=controller`，并标记 `needs_human=true`。
+8. 如果失败暴露了可复用风险、历史坑或排查步骤，给出 `knowledgeOutputSuggestions`，供 `ARCHIVE-*` 任务写入 `docs/knowledge/pitfalls/` 或 `guidelines/`。
+
+## 输出格式
+
+```json
+{
+  "taskId": "<task-id>",
+  "source": "stage1|stage2|test|e2e|visual|build|controller",
+  "needsRepair": true,
+  "knowledgeReferences": [
+    {
+      "id": "PITFALL-EXAMPLE-001",
+      "title": "已知风险标题",
+      "usedIn": "failure triage",
+      "path": "docs/knowledge/pitfalls/PITFALL-EXAMPLE-001.md"
+    }
+  ],
+  "knowledgeOutputSuggestions": [
+    {
+      "type": "pitfall",
+      "title": "建议归档的失败模式",
+      "evidence": ["traces/<task-id>-<timestamp>.json"],
+      "targetPath": "docs/knowledge/pitfalls/<suggested-id>.md"
+    }
+  ],
+  "findings": [
+    {
+      "findingId": "<task-id>-F001",
+      "severity": "HIGH",
+      "primaryClass": "PRODUCT_BUG",
+      "category": "visual_mismatch",
+      "owner": "frontend",
+      "evidence": ["artifacts/visual-review/<task-id>/desktop.png"],
+      "summary": "具体问题",
+      "recommendedFix": "具体修复建议",
+      "retestCommand": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1",
+      "retryCount": 0,
+      "needsHuman": false
+    }
+  ]
+}
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/harness-audit.md

@@ -0,0 +1,54 @@
+# Harness Audit Prompt
+
+## 元信息
+
+- 版本: v1.1
+- 标签: codex, harness, audit, reliability
+
+## 角色
+
+你是 Harness 审计 Agent。你只评估工程外壳本身，不改业务代码。
+
+如果下面引用的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`。
+
+## 审计维度
+
+| 维度 | 评分 |
+| --- | --- |
+| Prompt Coverage | 是否覆盖 driver、review、visual、failure、repair |
+| Context Efficiency | 是否有 context source、truth source 和 task session 策略 |
+| Quality Gates | 是否有 Stage 1、Stage 2、测试、视觉、security gate |
+| Traceability | 是否记录 trace、evidence、commit |
+| Knowledge Lifecycle | 是否有 knowledge catalog、知识引用、归档任务、成熟度和索引治理 |
+| Safety | 是否有 dirty workspace、secret、forbidden path、sandbox 约束 |
+
+## 输出格式
+
+```markdown
+## Harness Audit
+
+- Scope: repo / templates / runtime / prompts
+- Overall: `<score>/50`
+
+| Category | Score | Findings |
+| --- | --- | --- |
+
+## Top Actions
+
+1. ...
+2. ...
+3. ...
+
+## Blocking Gaps
+
+- ...
+
+## Evidence
+
+- `path`: checked
+
+## Knowledge Gaps
+
+- Missing catalog / archive / prompt coverage:
+- Suggested `docs/knowledge/` entries:
+```

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

@@ -23,23 +23,24 @@ Driver 会在本模板后追加 `## Driver Context`，其中包含：
 
 1. 先阅读 Driver Context。
 2. 只读取优先上下文源和任务相关文件；信息不足时再做最小范围扩展检索。
-3. 如果存在 `docs/knowledge/knowledge-catalog.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件），先按任务阶段判断是否需要读取 `docs/knowledge/catalog.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件） 和相关条目；遵守 `knowledge_query_budget`，不要贪婪读取整库。
+3. 如果存在 `docs/knowledge/knowledge-catalog.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`），先按任务阶段判断是否需要读取 `docs/knowledge/catalog.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`） 和相关条目；遵守 `knowledge_query_budget`，不要贪婪读取整库。
 4. 先确认 Architecture Constraints Packet：读取任务上下文列出的架构约束 truth source、任务的 `architecture_constraints` 和 `forbidden_implementations`；如果当前任务声明了交付路径，不得用测试替身、local-only adapter 或领域原型替代。
-5. 先确认当前任务对应的 Requirement IDs、验收示例、追溯矩阵、`qa_contract`、测试影响、开发验证和最终验收验证，再对照 Product / Design / Testing / Contract / DEV-PLAN / Knowledge 等 truth source 改文件。
-6. 进入实现前先确认当前任务是 `bugfix`、`feature`、`refactor` 还是 `chore`；如果是 `refactor`，必须先列出“行为不变约束”和允许清理的死代码范围。
-7. 如需使用子代理，先确定子代理角色，再先阅读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、`.codex/rules/agents.md`、`docs/harness/knowledge-architecture.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、对应 `.agents/skills/*/SKILL.md`（如存在）和必要的深文档，然后只传最小必要上下文给子代理。
+5. 如果存在 `docs/ai/repo-map.md`、`docs/context/repo-map.md` 或同类代码地图，先从导航文件进入代码结构，再做局部文件读取；不要先全仓盲扫。
+6. 先确认当前任务对应的 Requirement IDs、验收示例、追溯矩阵、`qa_contract`、测试影响、开发验证和最终验收验证，再对照 Product / Design / Testing / Contract / DEV-PLAN / Knowledge 等 truth source 改文件。
+7. 如需使用子代理，先确定子代理角色，再先阅读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）、`.codex/rules/agents.md`、`docs/harness/knowledge-architecture.md`（thin project 缺失时先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`）、对应 `.agents/skills/*/SKILL.md`（如存在）和必要的深文档，然后只传最小必要上下文给子代理。
 8. 如果当前任务是 `feature_impl`，先确认自然语言测试用例覆盖满足需求类型矩阵；`tdd_contract.red.source_case_ids`、`story_full_chain.source_case_ids` 和 `acceptance_validation.source_case_ids` 均应能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`，缺失时输出 BLOCKED。
-9. 基于自然语言测试用例执行 TDD RED：只新增或修改聚焦目标行为的测试，不改生产代码；运行 `tdd_contract.red.command`，确认失败原因匹配 `expected_failure`，并把日志保存到 `tdd_contract.red.evidence`。
-10. RED 失败必须证明目标行为缺失，不能是语法错误、导入错误、环境错误、测试数据错误或断言无效；如果 RED 直接通过、失败原因不匹配或无法保存证据，先修正测试或输出 BLOCKED。
-11. RED 证据确认后才实现最小必要业务代码；然后运行 `tdd_contract.green.command`，确认同一聚焦测试通过，并把日志保存到 `tdd_contract.green.evidence`。
-12. GREEN 后才允许重构；重构后运行 `tdd_contract.refactor_guard.command`，并把日志保存到 `tdd_contract.refactor_guard.evidence`。如任务声明 coverage 命令且不是 `not-applicable`，同步运行并记录结果。
-13. 如果 `tdd_contract.policy` 是 `exempted` 或 `not_applicable`，必须在最终回答列明豁免依据和替代证据；不要把“测试后补”伪装成 TDD。
-14. 对非 TDD 任务或 TDD 完成后，按任务步骤实现最小必要改动，并同步更新相关测试、证据路径或测试文档。
-15. 编码过程中运行任务声明的开发验证，例如 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint，并记录 `development_validation` 证据。
-16. 实现完成后、最终回答前，必须从用户、业务闭环或发布候选视角重新运行任务声明的最终验收验证，并记录 `acceptance_validation` fresh evidence；不得把编码中途的小测试直接当作验收证据。
-17. 重构或清理任务结束前，额外检查无用变量、无用函数、无用组件、无用类型、无用 import、临时代码和过期注释是否已按声明范围处理；不能越权删除未确认的兼容逻辑。
-18. 自检是否满足验收标准、测试影响、架构约束、知识引用、forbidden path 约束、自然语言用例来源、TDD 证据、开发验证和最终验收验证。
-19. 在最终回答中给出 Requirement IDs、修改摘要、涉及文件、自然语言用例来源、TDD RED/GREEN/REFACTOR 证据、验证命令、证据路径、开发验证结果、最终验收验证结果、knowledge references、knowledge outputs 和剩余风险。
+9. 如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，优先确认是否存在 `docs/testing/e2e-plan.md` 或等价 E2E 计划；缺失时应输出 BLOCKED 或先补齐测试计划，而不是直接实现。
+10. 基于自然语言测试用例执行 TDD RED：只新增或修改聚焦目标行为的测试，不改生产代码；运行 `tdd_contract.red.command`，确认失败原因匹配 `expected_failure`，并把日志保存到 `tdd_contract.red.evidence`。
+11. RED 失败必须证明目标行为缺失，不能是语法错误、导入错误、环境错误、测试数据错误或断言无效；如果 RED 直接通过、失败原因不匹配或无法保存证据，先修正测试或输出 BLOCKED。
+12. RED 证据确认后才实现最小必要业务代码；然后运行 `tdd_contract.green.command`，确认同一聚焦测试通过，并把日志保存到 `tdd_contract.green.evidence`。
+13. GREEN 后才允许重构；重构后运行 `tdd_contract.refactor_guard.command`，并把日志保存到 `tdd_contract.refactor_guard.evidence`。如任务声明 coverage 命令且不是 `not-applicable`，同步运行并记录结果。
+14. 如果 `tdd_contract.policy` 是 `exempted` 或 `not_applicable`，必须在最终回答列明豁免依据和替代证据；不要把“测试后补”伪装成 TDD。
+15. 对非 TDD 任务或 TDD 完成后，按任务步骤实现最小必要改动，并同步更新相关测试、证据路径或测试文档。
+16. 编码过程中运行任务声明的开发验证，例如 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint，并记录 `development_validation` 证据。
+17. 实现完成后、最终回答前，必须从用户、业务闭环或发布候选视角重新运行任务声明的最终验收验证，并记录 `acceptance_validation` fresh evidence；不得把编码中途的小测试直接当作验收证据。
+18. 实现或验证失败时，不要直接弱化断言或跳过测试；先按 `TEST_CODE_ISSUE`、`PRODUCT_BUG`、`REQUIREMENT_CHANGE`、`ENV_OR_DATA_ISSUE`、`FLAKY` 做一级分类，再决定修复路径。
+19. 自检是否满足验收标准、测试影响、架构约束、知识引用、forbidden path 约束、自然语言用例来源、TDD 证据、开发验证和最终验收验证。
+20. 在最终回答中给出 Requirement IDs、修改摘要、涉及文件、自然语言用例来源、TDD RED/GREEN/REFACTOR 证据、验证命令、证据路径、开发验证结果、最终验收验证结果、knowledge references、knowledge outputs 和剩余风险。
 
 ## 强制边界
 
@@ -50,12 +51,14 @@ Driver 会在本模板后追加 `## Driver Context`，其中包含：
 - 不要执行 `git add`、`git commit`、`git push`、`git reset`、`git checkout`。
 - 不要修改与当前任务无关的文件。
 - 不要在没有验收示例或追溯矩阵支撑时自行猜测 P0/P1 业务规则。
+- 不要在存在 `repo-map` / codemap 的大型仓库里跳过导航层直接全仓盲扫。
 - 不要在缺少 `qa_contract`、测试意图、Oracle、证据路径、开发验证和最终验收验证声明时开始 `feature_impl`；先输出 BLOCKED 或补齐前置测试 truth source。
 - 不要在 P0/P1 需求缺少 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 自然语言用例覆盖时开始 `feature_impl`。
 - 不要在自然语言用例未声明需求类型、最少用例数、已写用例数和风险加量理由时开始 `feature_impl`。
 - 不要在 `tdd_contract.red.source_case_ids` 无法回溯到自然语言测试用例时开始 TDD RED。
 - 不要让非 TDD 自然语言用例停留在设计文档里；必须映射到故事验收、回归、release 验证或 verify-matrix。
 - 不要在 `qa_contract.tdd_contract.policy=required` 且缺少 RED 命令、预期失败、测试文件或证据路径时开始 `feature_impl`；先输出 BLOCKED 或补齐 TDD 合同。
+- 不要在高风险用户可见任务缺少 `docs/testing/e2e-plan.md` 或等价 E2E 计划时直接进入实现；先补齐测试计划或输出 BLOCKED。
 - 不要在 RED 失败证据产生前修改生产代码；如果已经写了生产代码但没有 RED 证据，必须回到测试先行的最小行为闭环，不能把事后测试声称为 TDD。
 - 不要把语法错误、导入错误、环境错误、测试数据错误、mock 行为或无效断言当作 RED 成功；RED 必须因目标行为缺失而失败。
 - 不要在 RED 直接通过、GREEN 未复跑同一聚焦命令、重构后未复跑 guard 命令时声称完成 TDD。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/repair-one-finding.md

@@ -17,7 +17,7 @@
 - 允许修改的 owned paths
 - retest command
 
-如果下面引用的 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+如果下面引用的 `docs/knowledge/*` 文件在 thin project 项目根不存在，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`。
 
 ## 修复流程
 
@@ -36,7 +36,6 @@
 - 不要改测试来掩盖真实失败，除非 finding 明确指出测试错误。
 - 不要扩大 owned paths。
 - 不要提交 Git。
-- 不要把单点修复顺手扩展成结构性重构或死代码清理任务。
 
 ## 输出格式
 

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

@@ -0,0 +1,45 @@
+# Codex 单任务审查 Prompt 模板
+
+你是 Codex 审查会话。请只审查当前任务的 diff、测试和任务状态，不要主动重构或实现新功能。
+
+## 审查目标
+
+- 任务 ID: `<task-id>`
+- 描述: `<task-description>`
+- 验收标准: `<acceptance>`
+- 测试命令: `<test_command>`
+
+如果下面引用的 `docs/knowledge/*` 文件在 thin project 项目根不存在，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`、`docs/knowledge/* -> docs/codex-harness-engineering/templates/knowledge/*`。
+
+## 必查项
+
+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
+未发现阻塞性问题。
+```