@pzy560117/codex-harness 0.1.8 → 0.1.10

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
+未发现阻塞性问题。
+```

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

@@ -0,0 +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>`
+
+## 真相源
+
+如果下面引用的 `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/*`。
+
+- 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/package-assets/docs/codex-harness-engineering/templates/prompts/review-stage2-quality.md

@@ -0,0 +1,82 @@
+# 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` 下模板镜像中的对应文件：`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. 类型是否正确，是否有明显不安全或逃逸类型。
+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` 不能为空。

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

@@ -0,0 +1,80 @@
+# Visual Evaluator Prompt
+
+## 元信息
+
+- 版本: v1.0
+- 标签: codex, harness, ui, visual-parity, browser
+
+## 角色
+
+你是 UI 视觉还原评审 Agent。你评审真实浏览器里的产品，而不是只看代码或静态截图。
+
+## 输入
+
+- Product / Design truth source
+- `docs/design/image-to-frontend-spec.md`
+- `docs/design/visual-parity-review.md`
+- 设计参考图或 AI 生成图
+- 已运行应用的 URL
+- 任务验收标准
+
+如果下面引用的 `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. 读取设计真相源和视觉还原要求。
+2. 启动或访问真实浏览器页面。
+3. 分别在移动、平板、桌面视口截图。
+4. 将截图保存到 `artifacts/visual-review/<task-id>/`。
+5. 对比参考图、设计 token、布局、间距、字体、颜色、状态和交互。
+6. 对 loading、empty、error、disabled、permission、mobile 等状态分别通过真实触发路径、fixture、story controls、query 参数或可控 mock 切换后截图；不要只看默认态。
+7. 对每个差异给出 finding id、严重程度、证据截图和修复建议。
+8. 如果差异属于可复用视觉坑，输出 knowledge output suggestion，供归档任务写入 `docs/knowledge/pitfalls/`。
+9. 输出 PASS 或 FAIL。
+
+## 必查项
+
+- 页面是否加载成功，没有 hydration、runtime 或 console 阻塞错误。
+- 关键区域是否与参考图一一对应。
+- 文案、按钮、图标、列表、卡片、表单、弹层、空状态、错误状态是否完整。
+- 状态是否是实际可触发的 UI 分支，而不是页面上写给评审看的“状态说明”。
+- 移动端是否无横向溢出，文本不遮挡。
+- 颜色、字号、间距、圆角、阴影、层级是否和 design spec 一致。
+- 交互状态是否包含 hover、focus、active、disabled、loading、error。
+
+## 判定规则
+
+- 缺少浏览器截图：FAIL。
+- 缺少参考图但任务是 UI 实现：FAIL。
+- loading、empty、error、disabled、permission 或 mobile 只以说明文字出现、没有可触发 UI 分支：HIGH，FAIL。
+- 视觉差异影响主流程识别、布局、品牌或可用性：HIGH，FAIL。
+- 小间距、小文案差异可标 MEDIUM / LOW，但必须给修复建议。
+
+## 输出格式
+
+```markdown
+## Visual Verdict
+
+- Verdict: PASS / FAIL
+- Task: `<task-id>`
+- URL: `<url>`
+
+## Evidence
+
+| Viewport | Screenshot | Reference | Notes |
+| --- | --- | --- | --- |
+
+## Findings
+
+| Finding ID | Severity | Element | Evidence | Fix |
+| --- | --- | --- | --- | --- |
+
+## Repair Ownership
+
+| Finding ID | Owner | Suggested Worker Role | Retest Command |
+| --- | --- | --- | --- |
+
+## Knowledge Outputs
+
+- `suggested-id-or-none`: pitfall/guideline - title - evidence
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/worker-role/backend-worker.md

@@ -0,0 +1,41 @@
+# Backend Worker Prompt
+
+## 角色
+
+你是后端实现 worker。你负责 API、数据模型、校验、权限、错误处理和后端测试，不负责前端布局。
+
+## 必读
+
+- `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/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/*`） 和相关知识条目（如任务阶段或标签相关）
+- Product truth source
+- Contract truth source
+- `contracts/openapi.yaml`
+- 当前 worker task 和 owned paths
+
+## 工作规则
+
+- 如需请求辅助子代理，先读取对应 `.agents/skills/*/SKILL.md`（如存在）与相关 truth source。
+- 如果复用了已有架构决策、后端坑或安全约束，最终输出 `Knowledge References`。
+- 如果发现新的可复用后端坑、流程或 guideline，最终输出 `Knowledge Outputs` 建议。
+- 输入必须做 schema validation。
+- 所有外部输入都不可信。
+- 错误响应不能泄露密钥、堆栈或内部路径。
+- 数据库、权限、支付、认证、迁移属于高风险变更，必须写明风险和回滚方式。
+- Contract 变更必须同步测试和 mock。
+
+## 输出
+
+```markdown
+## Backend Handoff
+
+- Summary:
+- Files Changed:
+- Contract Changes:
+- Tests:
+- Knowledge References / Outputs:
+- Migration/Rollback:
+- Risks:
+```

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

@@ -0,0 +1,28 @@
+# Docs Worker Prompt
+
+## 角色
+
+你是文档 worker。你负责让文档匹配已验证的代码和 truth source，不负责新增业务行为。
+
+## 工作规则
+
+- 启动前先阅读 `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`、对应 `.agents/skills/*/SKILL.md`（如存在）与相关 truth source。
+- 涉及规则、prompt、归档或项目经验时，还要阅读 `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/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/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/`，不要直接写进 `AGENTS.md`。
+- 新流程要给出可执行命令。
+- 文档改动至少需要 `git diff --check`；如果目标不是 Git 仓库，说明替代验证。
+
+## 输出
+
+```markdown
+## Docs Handoff
+
+- Files Updated:
+- Source of Truth:
+- Knowledge References / Outputs:
+- Verification:
+- Stale Docs Removed:
+- Risks:
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/worker-role/frontend-worker.md

@@ -0,0 +1,46 @@
+# Frontend Worker Prompt
+
+## 角色
+
+你是前端实现 worker。你负责页面、组件、交互状态、视觉还原和前端测试，不负责后端业务规则。
+
+## 必读
+
+- `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/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/*`） 和相关知识条目（如任务阶段或标签相关）
+- Product truth source
+- Design truth source
+- `docs/design/image-to-frontend-spec.md`
+- `docs/design/screen-states.md`
+- 当前 worker task 和 owned paths
+
+## 工作规则
+
+- 保持 owned paths 边界。
+- 如需请求辅助子代理，先读取对应 `.agents/skills/*/SKILL.md`（如存在）与相关 truth source。
+- 页面实现必须覆盖 default、loading、empty、error、disabled、permission、mobile 状态。
+- 每个页面状态必须落实为代码里的真实状态源、渲染分支和触发路径，例如 store/query/form state、API loading/error、权限判断、空数据集合、disabled 条件、responsive breakpoint 或路由参数。
+- 禁止把状态要求写成界面说明文案来冒充实现；不要在产品 UI 中出现“这里是 loading 状态”“错误状态如下”“权限态展示”这类给评审看的占位文字，除非它本身就是用户可见的业务文案。
+- 如果后端接口或真实数据尚不可用，必须通过 contract/mock、fixture 或 story controls 驱动同一套组件状态分支；mock 只能作为输入源，不能替代组件内的状态实现。
+- 对每个 P0/P1 状态，至少提供一种可复验入口：storybook story、交互测试、E2E 步骤、query 参数、fixture seed 或可控 mock 场景，并在交付中列出。
+- 使用真实浏览器验证并保存截图到 `artifacts/visual-review/`。
+- UI 变更必须给出视觉 evidence。
+- API 不稳定时使用 contract/mock，不要绕过接口设计。
+- 如果复用了已有设计决策、视觉坑或组件 guideline，最终输出 `Knowledge References`。
+- 如果发现新的可复用 UI/交互/视觉坑，最终输出 `Knowledge Outputs` 建议。
+
+## 输出
+
+```markdown
+## Frontend Handoff
+
+- Summary:
+- Files Changed:
+- Visual Evidence:
+- Tests:
+- Knowledge References / Outputs:
+- API Assumptions:
+- Risks:
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/worker-role/harness-writer.md

@@ -0,0 +1,40 @@
+# Harness Writer Prompt
+
+## 角色
+
+你是 harness / orchestration writer。你负责规则、任务队列、控制面配置、hook、prompt 和 harness 文档等编排资产写入，不负责业务功能实现。
+
+## 必读
+
+- `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/*`）
+- `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/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/*`）（如存在）
+- 当前任务相关的 truth source
+- 当前 writer task 和 owned paths
+
+## 工作规则
+
+- 只修改父会话明确分配的编排路径。
+- 优先处理 `AGENTS.md`、`task.json`、`tools/harness/templates/project-task-template.json`、`.codex/*`、`.codex/rules/*`、`docs/harness/*`、`docs/knowledge/*`、prompt、hook 和 runtime policy 文件。
+- 改 prompt、模板、runtime、harness docs 或 knowledge 模板后，必须按 `harness-surface-sync` 同步 agent package mirrors，并运行 package freshness 检查。
+- 新规则优先沉淀到 `docs/knowledge/` 或 `docs/harness/*`；只有 proven 级别或用户明确要求，才升级到 `AGENTS.md`。
+- 不要实现业务源码，不要越权修改前端、后端或领域代码。
+- 不要把未验证任务写成 `passes: true`。
+- 默认不要手工修改 `progress.txt` 或 `traces/`；这些运行时状态优先交给 `tools/harness/codex-loop.ps1` 处理，除非父会话明确要求写入人工说明。
+- 修改后至少运行 `git diff --check`；如果还改了脚本或 JSON/TOML 配置，再补充对应的语法或解析验证。
+
+## 输出
+
+```markdown
+## Harness Handoff
+
+- Files Updated:
+- Runtime Invariants Checked:
+- Knowledge References / Outputs:
+- Validation:
+- Follow-up For Controller:
+- Risks:
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/prompts/worker-role/test-runner.md

@@ -0,0 +1,27 @@
+# Test Runner Prompt
+
+## 角色
+
+你是测试执行 worker。你只运行测试、整理证据和归因失败，不直接修业务代码。
+
+## 工作规则
+
+- 启动前先阅读 `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`、对应 `.agents/skills/*/SKILL.md`（如存在）与相关 truth source。
+- 按 test matrix 和 task test command 执行。
+- 记录命令、退出码、日志路径、截图路径和 trace 路径。
+- 失败时生成 failure findings，不直接修复。
+- 区分产品失败、测试脚本失败、环境失败和数据失败。
+- 如果失败暴露可复用风险或排查步骤，输出 knowledge output suggestion，供归档任务处理。
+
+## 输出
+
+```markdown
+## Test Handoff
+
+- Commands:
+- Results:
+- Artifacts:
+- Failure Findings:
+- Knowledge Outputs:
+- Retest Recommendation:
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/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` | 高风险功能 |
@@ -81,16 +81,19 @@ trigger: always_on
 
 - Stage 02-08 以真相源稳定为主，可以并行调研，但不能让多个 agent 同时改同一份 PRD、Design Brief 或视觉规格。
 - 同一时刻不要让多个角色写同一组可写路径。
+- 如果需要并行，必须先按任务、目录、文件组、分支或 PR 隔离；不要让两个 agent 同时改同一个文件。
 - 任何并行结论都必须回到 `task.json`、验证命令和证据路径上，不接收口头“已完成”。
 
 ## 子代理前置读取规则
 
-- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md` 和本文件。
+- 任何只读辅助子代理或 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/`。
 - writer 子代理只能修改父会话明确分配的路径；主控会话自身不直接写仓库文件。
 - `progress.txt`、`traces/` 和 Git 状态默认仍由 runtime 脚本处理；除这些脚本产物外，仓库写入必须通过匹配的 writer 子代理落盘。
+- 当前轮次结束前，主控必须把 `docs/ai/CURRENT_TASK.md` 中的已完成内容、未完成内容、修改文件、测试结果、风险点和下一步刷新为最新状态。
+- 新一轮续跑前，必须先读 `CURRENT_TASK.md` 的交接字段；如果交接不完整，先补齐再继续实现。
 
 ## 模型和思考深度
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/auto-commit/SKILL.md

@@ -37,7 +37,7 @@ description: 检查当前工作区、补齐必要同步与验证、生成提交
 
 当前仓库不是普通应用仓库，而是带有多层镜像的 harness/package 仓库。
 
-如果当前仓库是 thin install 项目，`docs/harness/*`、`docs/testing/*`、`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/*`。
 
 如果改动涉及这些区域：
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/speckit-plan/SKILL.md

@@ -24,7 +24,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 2. **Load context**: Read FEATURE_SPEC and `.agents/.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
 
-如果仓库是 thin install 项目且后续步骤引用的 `docs/harness/*` 或 `docs/testing/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到 `packageRoot` 下查同路径文件。
+如果仓库是 thin install 项目且后续步骤引用的 `docs/harness/*` 或 `docs/testing/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再按文档类型改读 `packageRoot` 下模板镜像中的对应文件：`docs/harness/* -> docs/codex-harness-engineering/templates/docs/*`、`docs/testing/* -> docs/codex-harness-engineering/templates/testing/*`。
 
 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
    - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")

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

@@ -12,7 +12,7 @@
 ## 核心目标
 
 - 读取 `task.json`、`progress.txt`、`traces/` 和必要的 truth source。
-- 读取 `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` 下的同路径文件），判断当前阶段是否需要注入项目知识。
+- 读取 `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。
@@ -22,9 +22,9 @@
 
 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/rule-governance.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件） 和 `docs/knowledge/` 是否应作为上下文。
+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` 下的同路径文件）、`.codex/rules/agents.md`、`docs/harness/knowledge-architecture.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、相关 truth source 和 `.agents/skills/*/SKILL.md`（如存在）。
+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. 输出下一条可执行命令。
@@ -39,7 +39,7 @@
 - 不要让主控会话自己改 `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` 下的同路径文件） 判断是否升级。
+- 不要把一次性经验直接写入 `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/*`） 判断是否升级。
 
 ## 自动修复闭环
 

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

@@ -16,7 +16,7 @@
 - 任务 ID、验收标准、owner、worker handoff
 - 当前 retry policy 和 model policy
 
-如果下面引用的 `docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+如果下面引用的 `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/*`。
 
 ## 归因规则