@pzy560117/codex-harness 0.1.8 → 0.1.10

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

@@ -9,7 +9,7 @@
 
 你是 Harness 审计 Agent。你只评估工程外壳本身，不改业务代码。
 
-如果下面引用的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+如果下面引用的 `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/*`。
 
 ## 审计维度
 

package/package-source/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/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/prompts/review-one-task.md

@@ -9,7 +9,7 @@
 - 验收标准: `<acceptance>`
 - 测试命令: `<test_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/*`。
 
 ## 必查项
 

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

@@ -12,7 +12,7 @@
 
 ## 真相源
 
-如果下面引用的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+如果下面引用的 `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>`

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

@@ -8,7 +8,7 @@
 - 描述: `<task-description>`
 - 测试命令: `<test-command>`
 
-如果下面引用的 `docs/harness/*`、`docs/testing/*` 或 `docs/knowledge/*` 文件在 thin project 项目根不存在，改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件。
+如果下面引用的 `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/*`。
 
 ## 必查项
 

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

@@ -18,7 +18,7 @@
 - 已运行应用的 URL
 - 任务验收标准
 
-如果下面引用的 `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/*`。
 
 ## 评审流程
 

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

@@ -7,9 +7,9 @@
 ## 必读
 
 - `AGENTS.md`
-- `docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）
+- `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/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`

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

@@ -6,8 +6,8 @@
 
 ## 工作规则
 
-- 启动前先阅读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、`.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/knowledge-architecture.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件） 和 `docs/knowledge/knowledge-catalog.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）。
+- 启动前先阅读 `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`。

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

@@ -7,9 +7,9 @@
 ## 必读
 
 - `AGENTS.md`
-- `docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）
+- `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/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`

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

@@ -7,11 +7,11 @@
 ## 必读
 
 - `AGENTS.md`
-- `docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）
+- `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/rule-governance.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）
-- `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/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
 

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

@@ -6,7 +6,7 @@
 
 ## 工作规则
 
-- 启动前先阅读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）、`.codex/rules/agents.md`、对应 `.agents/skills/*/SKILL.md`（如存在）与相关 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。
 - 按 test matrix 和 task test command 执行。
 - 记录命令、退出码、日志路径、截图路径和 trace 路径。
 - 失败时生成 failure findings，不直接修复。

package/package-source/docs/codex-harness-engineering/templates/runtime/AGENTS.md

@@ -1,65 +1,54 @@
-# AGENTS.md
+## 模板优先
 
-本文件只保留每次会话都必须知道的 Harness 入口规则。细节按需读取下方深文档，不把长期协议全部塞进入口文件。
+- 需要影响新项目 bootstrap、生成物结构、默认导航层、默认 prompt、默认规则、默认技能、默认上下文模板时，先修改模板 canonical：
+  - `docs/codex-harness-engineering/templates/`
+  - `tools/harness/templates/`
+  - `docs/codex-harness-engineering/templates/package-assets/`
+- 当前仓库根目录下的活跃文档或脚本，只在它本身就是 canonical，或为了验证模板落地效果、保持当前仓库可运行时再同步修改。
+- 如果一次改动同时涉及根目录活跃文件和模板文件，优先说明哪一份是 canonical，避免只修当前仓库、不修模板源。
 
-## 模板源目录说明
+## 任务结构硬门禁
 
-- 当你在模板源仓库维护 `templates/runtime/` 时，本文件也同时代表该目录的本地索引。
-- 当前目录主要包含：
-  - `AGENTS.md`：安装到目标项目根目录的入口规则模板
-  - `codex-loop.ps1` / `doctor.ps1` / `verify.ps1`：driver 与运行时脚本模板
-  - `project-task-template.json` / `smoke-task.json` / `task.json` / `progress.txt`：任务与运行状态模板
-  - `task-run-profile.json`：运行策略模板
-  - `scripts/`：runtime 自检和队列校验脚本
-- 维护该目录时，优先确认这些文件是“安装后运行面”，不要把只适用于模板仓库的局部说明大量混入这里。
+- 未经用户明确同意，不得把标准 `task.json` 模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
+- P0/P1 项目禁止跳过 `TESTCASE-001`；缺少 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`ACCEPTANCE_CRITERIA.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md`、`verify-matrix.md` 任一项，都不得生成最终 `task.json`。
+- `feature_impl` 没有 `qa_contract` 不得进入正式任务队列；`qa_contract` 没有完整 `tdd_contract`、`development_validation`、`acceptance_validation` 不得开始实现。
+- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
 
-## 核心入口
+## 子目录 AGENTS 规则
 
-- 本仓库默认采用 `driver-first`：真实任务进入 `task.json`，由 `tools/harness/codex-loop.ps1` 逐个执行。
-- `single task` 是当前唯一自动执行模式；每轮 driver 只处理一个 `passes: false` 且依赖已通过的任务。
-- 交互开发模式只负责需求收敛、分析、规划和任务输入；方案确认后，默认回到 `task.json -> tools/harness/codex-loop.ps1`。
-- 主控会话不直接维护仓库状态文件；`task.json`、`progress.txt`、`traces/` 和 Git 提交由 runtime 链路推进。
-- 长会话续跑前，先重读 `docs/ai/CURRENT_TASK.md`、`docs/ai/repo-map.md` 和相关 truth source；不要只靠聊天记忆继续实现。
-- 需要理解代码结构或安装包边界时，先读 `docs/ai/repo-map.md`，再进入具体目录或深文档。
-- 需要落盘规则、任务、文档、前端、后端或测试内容时，先确认 truth source，再委派匹配的 writer 子代理或进入 driver 任务。
+- 新增业务目录、模块职责变化、目录入口变化、目录级测试命令变化时，必须检查并更新最接近该目录的子目录 `AGENTS.md`。
+- 目录级 `AGENTS.md` 负责承载局部职责、边界、入口、测试命令、复用模式、坑点和禁止事项；不要把这类规则长期堆在根 `AGENTS.md`。
+- 自动托管区块 `AUTO-MODULE-FACTS` 只补动态事实，不等于目录规则完整；即使 facts 已自动刷新，仍需要有人维护手写的局部规则部分。
+- 如果 `task.json.owned_paths`、`docs/ai/repo-map.md` 或模块边界已经明确某目录是独立模块，而该目录缺少子目录 `AGENTS.md`，应视为至少 `warn`，高风险目录应直接阻断进入正式任务队列或实现阶段。
 
-## 硬约束
+## 目录级规则
 
-- 启动前 Git 工作区必须干净，除非用户明确说明哪些改动属于本任务；可再生运行产物只能通过 `runtime.git.non_blocking_dirty_paths` 列白名单。
-- 不要伪造完成状态：不得手工把未验证任务标记为 `passes: true`，不得绕过 `test_command`、review gate 或 commit gate。
-- 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
-- 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
-- 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
-- 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 三段测试左移与实施计划 phase。
-- P0/P1 任务禁止跳过 `TESTCASE-001`；没有自然语言测试用例、测试数据矩阵、回归计划和验证矩阵，不得生成最终 `task.json`。
-- `feature_impl` 没有 `qa_contract` 不得进入正式 `task.json`；`qa_contract` 没有完整 `tdd_contract`、开发验证和最终验收验证，不得开始实现。
-- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆成独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。
-- 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
-- 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
-- `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。
-- Stage 1 Review 先审声明的架构约束符合性，再审业务规格；仅当任务要求架构门禁且约束缺失或实现冲突时 FAIL。
-- 多 Agent 协作时，禁止多个 Agent 同时修改同一文件或同一组可写路径；必须先按任务、目录、文件组、分支或 PR 隔离。
-- 当前轮次结束前必须刷新 `docs/ai/CURRENT_TASK.md` 中的已完成内容、未完成内容、修改文件、测试结果和下一步。
-- 阻塞时追加 `progress.txt`，输出 `BLOCKED - 需要人工介入`，然后停止。
-
-## 阶段更新规则
-
-- Stage 01 初始化：更新 `task.json`、`AGENTS.md`、项目路径和验证命令。
-- Stage 02 需求收敛：更新 `docs/product/`、Requirement IDs、验收标准和可执行验收示例。
-- Stage 03 追溯与架构约束：更新架构约束 truth source、测试追溯矩阵和证据协议。
-- Stage 09 DEV-PLAN / 任务拆分：把架构约束、禁止实现和验证命令写入每个相关 `feature_impl`。
-- Stage 10-14 实现与集成：只更新任务 owned paths 内的实现、测试和证据。
-- Stage 15-16 Review：保持只读审查，输出 findings、证据和 repair queue。
-- Stage 17 Verify / Regression：刷新验证证据，不在本阶段第一次补需求或测试范围。
-- Archive：更新 `docs/knowledge/`、索引和可复用经验，不升级一次性结论为全局规则。
+- 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：
+  - 目录有独立模块职责或技术栈
+  - 目录存在与全仓不同的架构边界
+  - 目录有独立入口文件、测试命令或验证方式
+  - 目录反复出现相同 review 问题、坑点或禁止事项
+- 子目录 `AGENTS.md` 应重点写：
+  - 该目录负责什么 / 不负责什么
+  - 入口文件和核心文件
+  - 修改前必须先看的文件
+  - 本目录的局部架构规则和复用模式
+  - 测试 / 构建 / 验证命令
+  - 常见坑和禁止事项
+- `docs/ai/repo-map.md` 及模板中的 repo-map 应维护“子目录规则索引”，明确哪些路径已有本地规则、适用于什么场景。
 
 ## 必读索引
 
-如果当前仓库是 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`
+- Codex 宿主自动加载机制：`docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
+- Codex 自动加载优化清单：`harness-analysis/10-codex-autoload-optimization-checklist.md`
 - Harness 架构：`docs/harness/architecture.md`
-- 代码地图：`docs/ai/repo-map.md`
-- 架构摘要：`docs/ai/architecture-brief.md`
 - 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
 - 新项目使用：`docs/harness/new-project-usage.md`
 - Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
@@ -68,3 +57,9 @@
 - Trace 格式：`docs/harness/trace-format.md`
 - 权限策略：`docs/harness/sandbox-policy.md`
 - Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`
+
+## 当前在做的事情
+
+- 正在持续分析当前仓库里的 Codex 宿主层、Harness 控制层、安装工程和桥接层。
+- 当前重点是把“哪些内容会被 Codex 自动加载到上下文、哪些只是运行配置、哪些是 Harness runtime 二次读取”彻底拆清。
+- 所有新增分析文档统一落在 `harness-analysis/`，方法论和模板级说明补充到 `docs/codex-harness-engineering/`。

package/package-source/docs/codex-harness-engineering/templates/runtime/doctor.ps1

@@ -533,9 +533,6 @@ function Test-DoctorThinLegacyResidue {
   param([string]$Root)
 
   $legacyResiduePaths = @(
-    "docs\harness",
-    "docs\testing",
-    "docs\knowledge",
     "docs\requirement-prep-kit"
   )
 
@@ -578,6 +575,61 @@ function Test-DoctorThinLegacyResidue {
 
   return $false
 }
+
+function Get-ThinProjectExcludedDestinations {
+  return @(
+    "docs/testing/",
+    "docs/harness/",
+    "docs/requirement-prep-kit/",
+    "docs/knowledge/"
+  )
+}
+
+function Test-ProjectScopeInstallSurface {
+  param(
+    [string]$Root,
+    [object]$ManifestSnapshot,
+    [ref]$Errors
+  )
+
+  if ($null -eq $ManifestSnapshot) {
+    return
+  }
+
+  $entries = @($ManifestSnapshot.entries | Where-Object { [string]$_.scope -eq "project" })
+  foreach ($entry in $entries) {
+    $destinationRaw = [string]$entry.destination
+    if ([string]::IsNullOrWhiteSpace($destinationRaw)) {
+      continue
+    }
+
+    $skipForThinProject = $false
+    foreach ($excludedDestination in @(Get-ThinProjectExcludedDestinations)) {
+      if ($destinationRaw.Replace('\', '/').StartsWith($excludedDestination, [System.StringComparison]::OrdinalIgnoreCase)) {
+        $skipForThinProject = $true
+        break
+      }
+    }
+    if ($skipForThinProject) {
+      continue
+    }
+
+    $normalizedDestination = $destinationRaw.Replace('/', '\').TrimStart('\')
+    $expectsDirectory = $destinationRaw.Trim().Replace('\', '/').EndsWith('/', [System.StringComparison]::Ordinal)
+    $targetPath = Join-Path $Root $normalizedDestination
+
+    if ($expectsDirectory) {
+      if (-not (Test-Path -LiteralPath $targetPath -PathType Container)) {
+        Add-DoctorError -Errors $Errors -Message "project scope 安装缺少目录: $normalizedDestination"
+      }
+      continue
+    }
+
+    if (-not (Test-Path -LiteralPath $targetPath -PathType Leaf)) {
+      Add-DoctorError -Errors $Errors -Message "project scope 安装缺少文件: $normalizedDestination"
+    }
+  }
+}
 
 function Test-DoctorMissingUserPackage {
   param([object]$HarnessConfigInfo)
@@ -796,7 +848,7 @@ function Test-PackageLock {
   }
 }
 
-function Test-InstallManifestSnapshot {
+function Test-InstallManifestSnapshot {
   param(
     [string]$Root,
     [bool]$RequireSnapshot,
@@ -874,9 +926,6 @@ function Test-ThinProjectSurface {
   }
 
   $legacyResiduePaths = @(
-    "docs\harness",
-    "docs\testing",
-    "docs\knowledge",
     "docs\requirement-prep-kit"
   )
 
@@ -915,6 +964,17 @@ function Test-ThinProjectSurface {
     }
   }
 }
+
+function Read-InstallManifestSnapshotOrNull {
+  param([string]$Root)
+
+  $snapshotPath = Join-Path $Root ".codex-harness\manifests\install-manifest.json"
+  if (-not (Test-Path -LiteralPath $snapshotPath -PathType Leaf)) {
+    return $null
+  }
+
+  return Read-JsonFileOrNull -Path $snapshotPath
+}
 
 function Test-HarnessConfig {
   param(
@@ -1145,21 +1205,25 @@ if ((Test-Path -LiteralPath $specManifestSchemaPath) -and (-not (Test-JsonFile -
   Add-DoctorError -Errors ([ref]$errors) -Message "spec-manifest.schema.json 不是合法 JSON: docs\\spec\\spec-manifest.schema.json"
 }
 
-if ($isNotInstalledProject) {
-  Add-DoctorError -Errors ([ref]$errors) -Message "readiness gate 未检测到 harness config 或 legacy vendor，请先安装 project scope。"
-}
-else {
+if ($isNotInstalledProject) {
+  Add-DoctorError -Errors ([ref]$errors) -Message "readiness gate 未检测到 harness config 或 legacy vendor，请先安装 project scope。"
+}
+else {
   if (-not $isVendorProjectInstall) {
     Test-SpecManifest -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
   }
 
-  Test-HarnessConfig -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
-  Test-PackageLock -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
-  if (-not $isThinProjectInstall) {
-    Test-InstallManifest -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
-  }
-  Test-InstallManifestSnapshot -Root $resolvedProjectRoot -RequireSnapshot:$harnessConfigInfo.Exists -Errors ([ref]$errors) -Warnings ([ref]$warnings)
-}
+  Test-HarnessConfig -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
+  Test-PackageLock -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
+  if (-not $isThinProjectInstall) {
+    Test-InstallManifest -Root $resolvedProjectRoot -Errors ([ref]$errors) -Warnings ([ref]$warnings)
+  }
+  Test-InstallManifestSnapshot -Root $resolvedProjectRoot -RequireSnapshot:$harnessConfigInfo.Exists -Errors ([ref]$errors) -Warnings ([ref]$warnings)
+  if ($isThinProjectInstall) {
+    $installManifestSnapshot = Read-InstallManifestSnapshotOrNull -Root $resolvedProjectRoot
+    Test-ProjectScopeInstallSurface -Root $resolvedProjectRoot -ManifestSnapshot $installManifestSnapshot -Errors ([ref]$errors)
+  }
+}
 
 if (-not (Test-Path -LiteralPath $taskPath)) {
   if ($isNotInstalledProject) {

package/package-source/install-manifest.json

@@ -2,7 +2,7 @@
   "schemaVersion": "0.1",
   "status": "draft",
   "package": "codex-harness",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "installModes": [
     {
       "name": "user",

package/package-source/tools/install/bootstrap-codex-harness.ps1

@@ -667,7 +667,8 @@ $contextFiles = @(
   @{ Source = "context\API_MAP.md"; Destination = "docs\ai\API_MAP.md" },
   @{ Source = "context\DB_SCHEMA.md"; Destination = "docs\ai\DB_SCHEMA.md" },
   @{ Source = "context\KNOWN_ISSUES.md"; Destination = "docs\ai\KNOWN_ISSUES.md" },
-  @{ Source = "context\CHANGELOG_AI.md"; Destination = "docs\ai\CHANGELOG_AI.md" }
+  @{ Source = "context\CHANGELOG_AI.md"; Destination = "docs\ai\CHANGELOG_AI.md" },
+  @{ Source = "context\service-dependency-matrix.yaml"; Destination = ".service-matrix\dependencies.yaml" }
 )
 
 foreach ($file in $contextFiles) {