@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/docs/prompt-knowledge-integration.md

@@ -1,89 +1,100 @@
-# Prompt Knowledge Integration
-
-本文定义 `.codex/prompts/*` 如何消费 `docs/harness/*` 和 `docs/knowledge/*`，确保知识沉淀不只停留在文档里，而是进入实现、审查、修复和归档链路。
-
-## 目标
-
-- 每个执行角色都知道何时读取知识目录。
-- 每个输出角色都能记录 `knowledge_references` 和 `knowledge_outputs`。
-- review 能检查知识是否被使用、是否被误用。
-- failure triage、repair 和 visual review 能把坏例转成可归档建议。
-- harness writer 和 docs worker 能按规则治理协议决定内容写到哪里。
-
-## Prompt 覆盖矩阵
-
-| Prompt | 知识消费 | 知识产出 |
-| --- | --- | --- |
-| `controller-loop.md` | 判断任务是否需要注入 `docs/knowledge/` 和规则治理上下文 | 决定是否进入 `ARCHIVE-*` |
-| `implement-one-task.md` | 按阶段读取 knowledge catalog 和相关条目 | 输出 `Knowledge References` / `Knowledge Outputs` |
-| `review-stage1-spec.md` | 检查 `knowledge` truth source、archive 阶段和规则误升级 | 输出 `knowledge_gap` finding |
-| `review-stage2-quality.md` | 检查代码或文档决策是否引用知识 | 输出 `knowledge_gap` finding |
-| `failure-triage.md` | 读取历史坑辅助归因 | 输出 `knowledgeOutputSuggestions` |
-| `repair-one-finding.md` | 读取相关知识，避免重复踩坑 | 输出修复后的知识建议 |
-| `visual-evaluator.md` | 使用设计和视觉相关经验 | 输出视觉 pitfall / guideline 建议 |
-| `harness-audit.md` | 审计 prompt、trace、archive 和 catalog 覆盖 | 输出 Knowledge Gaps |
-| `worker-role/harness-writer.md` | 读取知识架构和规则治理 | 同步 prompt/docs/knowledge mirrors |
-| `worker-role/docs-worker.md` | 判断长期文档与临时讨论边界 | 把可复用经验写入 `docs/knowledge/` |
-| `worker-role/frontend-worker.md` | 读取 UI/视觉/组件经验 | 输出前端知识引用和新坑建议 |
-| `worker-role/backend-worker.md` | 读取架构、安全、API 风险经验 | 输出后端知识引用和新坑建议 |
-| `worker-role/test-runner.md` | 读取历史测试/环境坑 | 输出失败模式归档建议 |
-
-## 阶段查询矩阵
-
-实现会话不应一次性读取全部知识。先读 `knowledge-catalog.md`，再按阶段和任务类型选择 catalog 与少量完整条目。
-
-| 阶段 | 查询重点 | 优先知识类型 | 默认用途 |
-| --- | --- | --- | --- |
-| `analysis` / 产品分析 | 业务实体、历史需求、流程和已知坑 | `model`、`process`、`pitfall` | 补齐需求边界、异常流和术语 |
-| `plan` / 技术分析 | 既有架构决策、禁止做法、失败模式 | `decision`、`guideline(avoid)`、`pitfall` | 避免重复推导和重复踩坑 |
-| `design` / 架构设计 | 实体关系、模块边界、历史决策 | `model`、`decision` | 保持设计与已有约束一致 |
-| `implement` | 编码实践、团队约定、风险路径 | `guideline`、`pitfall` | 指导实现细节和边界处理 |
-| `verify` / release | 回归风险、环境坑、禁止做法 | `pitfall`、`guideline(avoid)` | 选择 affected tests 和失败排查路径 |
-| `archive` | 本轮引用、产出、冲突和可提升条目 | 全部类型 | 更新 `last_referenced`、输出 promotion/decay/conflict/merge candidates |
-
-每个阶段只读取和当前任务直接相关的条目。`draft` 条目可以启发分析，但不能成为阻塞性 review 依据；`proven` 条目才适合升级为规则、模板或 prompt。
-
-## 输出字段约定
-
-实现、修复和 worker handoff 应尽量使用以下 Markdown 字段：
-
-```markdown
-## Knowledge References
-- `id`: title - used_in - `path`
-
-## Knowledge Outputs
-- `suggested-id`: type - title - action - `target-path`
-```
-
-失败归因 JSON 使用：
-
-```json
-{
-  "knowledgeReferences": [],
-  "knowledgeOutputSuggestions": []
-}
-```
-
-driver trace 使用 `docs/harness/trace.schema.json` 中的：
-
-- `knowledge_references`
-- `knowledge_outputs`
-- `archive_summary`
-
-## 使用边界
-
-- `draft` 知识只能作为参考，不应作为阻塞性 review 依据。
-- `verified` 知识可以作为 reviewer 的辅助依据。
-- `proven` 知识才适合升级为规则、模板或 prompt。
-- 单次任务经验不得直接写入 `AGENTS.md`，应先进入 `docs/knowledge/`。
-- prompt 改动后必须同步 `agent/.codex/prompts/`、`docs/codex-harness-engineering/templates/prompts/` 和 `.agents/docs/codex-harness-engineering/templates/prompts/`。
-
-## 维护检查
-
-每次改动 `docs/harness/knowledge-architecture.md`、`docs/harness/rule-governance.md`、`docs/harness/trace.schema.json` 或 `tools/harness/templates/project-task-template.json` 后，检查：
-
-1. `implement-one-task.md` 是否仍要求输出知识引用和知识产出。
-2. Stage 1 / Stage 2 review 是否能检查知识缺口。
-3. failure / repair / visual prompts 是否能把坏例转成归档建议。
-4. worker-role prompts 是否要求读取对应知识文档。
-5. `refresh-agent-package.ps1 -CheckOnly` 是否通过。
+# Prompt Knowledge Integration
+
+本文定义 `.codex/prompts/*` 如何消费 `docs/harness/*` 和 `docs/knowledge/*`，确保知识沉淀不只停留在文档里，而是进入实现、审查、修复和归档链路。
+
+## 目标
+
+- 每个执行角色都知道何时读取知识目录。
+- 每个输出角色都能记录 `knowledge_references` 和 `knowledge_outputs`。
+- review 能检查知识是否被使用、是否被误用。
+- failure triage、repair 和 visual review 能把坏例转成可归档建议。
+- harness writer 和 docs worker 能按规则治理协议决定内容写到哪里。
+
+## 默认读取顺序
+
+1. `AGENTS.md`
+2. `docs/ai/repo-map.md`
+3. `docs/ai/architecture-brief.md`
+4. `docs/ai/CURRENT_TASK.md`
+5. 任务需要时读取 `docs/ai/PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`
+6. `docs/harness/*`
+7. `docs/knowledge/knowledge-catalog.md`
+8. 仅在项目内信息不足或问题依赖 freshness 时查询 MCP / 外部知识
+
+## Prompt 覆盖矩阵
+
+| Prompt | 知识消费 | 知识产出 |
+| --- | --- | --- |
+| `controller-loop.md` | 判断任务是否需要注入 `docs/knowledge/` 和规则治理上下文 | 决定是否进入 `ARCHIVE-*` |
+| `implement-one-task.md` | 按阶段读取 knowledge catalog 和相关条目 | 输出 `Knowledge References` / `Knowledge Outputs` |
+| `review-stage1-spec.md` | 检查 `knowledge` truth source、archive 阶段和规则误升级 | 输出 `knowledge_gap` finding |
+| `review-stage2-quality.md` | 检查代码或文档决策是否引用知识 | 输出 `knowledge_gap` finding |
+| `failure-triage.md` | 读取历史坑辅助归因 | 输出 `knowledgeOutputSuggestions` |
+| `repair-one-finding.md` | 读取相关知识，避免重复踩坑 | 输出修复后的知识建议 |
+| `visual-evaluator.md` | 使用设计和视觉相关经验 | 输出视觉 pitfall / guideline 建议 |
+| `harness-audit.md` | 审计 prompt、trace、archive 和 catalog 覆盖 | 输出 Knowledge Gaps |
+| `worker-role/harness-writer.md` | 读取知识架构和规则治理 | 同步 prompt/docs/knowledge mirrors |
+| `worker-role/docs-worker.md` | 判断长期文档与临时讨论边界 | 把可复用经验写入 `docs/knowledge/` |
+| `worker-role/frontend-worker.md` | 读取 UI/视觉/组件经验 | 输出前端知识引用和新坑建议 |
+| `worker-role/backend-worker.md` | 读取架构、安全、API 风险经验 | 输出后端知识引用和新坑建议 |
+| `worker-role/test-runner.md` | 读取历史测试/环境坑 | 输出失败模式归档建议 |
+
+## 阶段查询矩阵
+
+实现会话不应一次性读取全部知识。先读 `knowledge-catalog.md`，再按阶段和任务类型选择 catalog 与少量完整条目。
+
+| 阶段 | 查询重点 | 优先知识类型 | 默认用途 |
+| --- | --- | --- | --- |
+| `analysis` / 产品分析 | 业务实体、历史需求、流程和已知坑 | `model`、`process`、`pitfall` | 补齐需求边界、异常流和术语 |
+| `plan` / 技术分析 | 既有架构决策、禁止做法、失败模式 | `decision`、`guideline(avoid)`、`pitfall` | 避免重复推导和重复踩坑 |
+| `design` / 架构设计 | 实体关系、模块边界、历史决策 | `model`、`decision` | 保持设计与已有约束一致 |
+| `implement` | 编码实践、团队约定、风险路径 | `guideline`、`pitfall` | 指导实现细节和边界处理 |
+| `verify` / release | 回归风险、环境坑、禁止做法 | `pitfall`、`guideline(avoid)` | 选择 affected tests 和失败排查路径 |
+| `archive` | 本轮引用、产出、冲突和可提升条目 | 全部类型 | 更新 `last_referenced`、输出 promotion/decay/conflict/merge candidates |
+
+每个阶段只读取和当前任务直接相关的条目。`draft` 条目可以启发分析，但不能成为阻塞性 review 依据；`proven` 条目才适合升级为规则、模板或 prompt。
+
+## 输出字段约定
+
+实现、修复和 worker handoff 应尽量使用以下 Markdown 字段：
+
+```markdown
+## Knowledge References
+- `id`: title - used_in - `path`
+
+## Knowledge Outputs
+- `suggested-id`: type - title - action - `target-path`
+```
+
+失败归因 JSON 使用：
+
+```json
+{
+  "knowledgeReferences": [],
+  "knowledgeOutputSuggestions": []
+}
+```
+
+driver trace 使用 `docs/harness/trace.schema.json` 中的：
+
+- `knowledge_references`
+- `knowledge_outputs`
+- `archive_summary`
+
+## 使用边界
+
+- `draft` 知识只能作为参考，不应作为阻塞性 review 依据。
+- `verified` 知识可以作为 reviewer 的辅助依据。
+- `proven` 知识才适合升级为规则、模板或 prompt。
+- 单次任务经验不得直接写入 `AGENTS.md`，应先进入 `docs/knowledge/`。
+- prompt 改动后必须同步 `agent/.codex/prompts/`、`docs/codex-harness-engineering/templates/prompts/` 和 `.agents/docs/codex-harness-engineering/templates/prompts/`。
+
+## 维护检查
+
+每次改动 `docs/harness/knowledge-architecture.md`、`docs/harness/rule-governance.md`、`docs/harness/trace.schema.json` 或 `tools/harness/templates/project-task-template.json` 后，检查：
+
+1. `implement-one-task.md` 是否仍要求输出知识引用和知识产出。
+2. Stage 1 / Stage 2 review 是否能检查知识缺口。
+3. failure / repair / visual prompts 是否能把坏例转成归档建议。
+4. worker-role prompts 是否要求读取对应知识文档。
+5. `refresh-agent-package.ps1 -CheckOnly` 是否通过。

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

@@ -1,45 +1,47 @@
-# 回归规则
-
-| 风险 | 约束 |
-| --- | --- |
-| 误改文件 | Git 工作区清洁检查、task 边界、owned paths |
-| 漏测 | 每个任务必须运行 `test_command` |
-| 伪完成 | `passes=true` 必须建立在 fresh evidence 上 |
-| 文档漂移 | 规则、模板、命令改动后同步更新对应文档 |
-
-## 基本要求
-
-- 文档改动至少运行 `git diff --check`。
-- 代码改动必须运行与任务风险匹配的验证命令。
-- 不允许在未验证的情况下手工把任务标记为通过。
-
-## 需求到验证的左移规则
-
-- 测试从需求收敛阶段开始介入，不允许等代码完成后才第一次补测试范围。
-- 任何 P0/P1 需求进入实现前，至少要有 Requirement ID、业务规则、正向示例、异常示例、测试层级映射、测试数据说明和证据路径。
-- 任何 P0/P1 或高风险测试进入脚本实现前，必须先定义测试意图和 Oracle；写操作、权限、状态机、异步链路必须包含副作用或无副作用验证。
-- 创建或重建 `task.json` 时必须一次性补齐完整 QA 合约；后续不得依赖人工逐项补 `requirement_ids`、测试数据、Oracle、开发验证、最终验收验证、证据路径或整链路验证。
-- `docs/testing/TRACEABILITY_MATRIX.md`、验收示例和验证矩阵属于实现前 truth source；缺失时应优先补齐，而不是继续猜测实现。
-- 修改业务代码时必须同时检查测试影响；相关测试缺失时，先补测试骨架或测试计划，再继续实现。
-- Stage 2 必须拦截假测试，包括只断言 200 / truthy、只测 happy path、mock 被测逻辑、缺少业务断言、缺少执行证据或缺少来源绑定的测试。
-
-## 完成定义
-
-- 对外部系统、既定开源栈、第三方平台或真实环境的集成型需求，完成定义至少包含：真实依赖接上、真实请求走通、成功态证据、失败态证据。
-- 页面能打开、本地接口能返回、单元测试通过，都不足以声称正式 `FR-*` 已完成。
-- 每个 `feature_impl` 必须同时具备两段证据：编码过程中的 `development_validation`，以及代码写完后从用户 / 业务闭环视角重新运行的 `acceptance_validation`。
-- 每个 `feature_impl` 至少需要故事级完整链路验收证据；只跑单元测试、局部 smoke、affected tests、静态检查或 `git diff --check` 不足以完成任务。
-- 如果当前只是原型 / spike / exploratory 路径，不要把演示性交付直接标成正式 `FR-*` 完成；应改用 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 等单独标识，或在 spec / plan 中显式记录该 FR 仍处于未完成集成态。
-- 单元测试只能证明本地逻辑；集成型需求还必须补环境 smoke、E2E、真实下游连通性验证和验收证据 note。
-- Release 完成必须有发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证；不得把各子任务局部测试简单相加当作整测。
-- Stage 17 只负责 fresh evidence、affected tests 和 P0/P1 回归确认，不负责第一次定义需求测试范围。
-
-## 技术栈验证基线
-
-| 改动类型 | 最小验证 |
-| --- | --- |
-| 文档 | `git diff --check` |
-| JSON | `ConvertFrom-Json` |
-| PowerShell | Parser 语法检查 |
-| TypeScript / 前端 | lint、typecheck、build |
-| API 或业务流程 | 单元测试、集成测试或 E2E，按风险选择 |
+# 回归规则
+
+| 风险 | 约束 |
+| --- | --- |
+| 误改文件 | Git 工作区清洁检查、task 边界、owned paths |
+| 漏测 | 每个任务必须运行 `test_command` |
+| 伪完成 | `passes=true` 必须建立在 fresh evidence 上 |
+| 文档漂移 | 规则、模板、命令改动后同步更新对应文档 |
+
+## 基本要求
+
+- 文档改动至少运行 `git diff --check`。
+- 代码改动必须运行与任务风险匹配的验证命令。
+- 不允许在未验证的情况下手工把任务标记为通过。
+
+## 需求到验证的左移规则
+
+- 测试从需求收敛阶段开始介入，不允许等代码完成后才第一次补测试范围。
+- 任何 P0/P1 需求进入实现前，至少要有 Requirement ID、业务规则、正向示例、异常示例、测试层级映射、测试数据说明和证据路径。
+- 任何 P0/P1 或高风险测试进入脚本实现前，必须先定义测试意图和 Oracle；写操作、权限、状态机、异步链路必须包含副作用或无副作用验证。
+- 创建或重建 `task.json` 时必须一次性补齐完整 QA 合约；后续不得依赖人工逐项补 `requirement_ids`、测试数据、Oracle、开发验证、最终验收验证、证据路径或整链路验证。
+- `docs/testing/TRACEABILITY_MATRIX.md`、验收示例和验证矩阵属于实现前 truth source；缺失时应优先补齐，而不是继续猜测实现。
+- 修改业务代码时必须同时检查测试影响；相关测试缺失时，先补测试骨架或测试计划，再继续实现。
+- Stage 2 必须拦截假测试，包括只断言 200 / truthy、只测 happy path、mock 被测逻辑、缺少业务断言、缺少执行证据或缺少来源绑定的测试。
+
+## 完成定义
+
+- 对外部系统、既定开源栈、第三方平台或真实环境的集成型需求，完成定义至少包含：真实依赖接上、真实请求走通、成功态证据、失败态证据。
+- 页面能打开、本地接口能返回、单元测试通过，都不足以声称正式 `FR-*` 已完成。
+- 每个 `feature_impl` 必须同时具备两段证据：编码过程中的 `development_validation`，以及代码写完后从用户 / 业务闭环视角重新运行的 `acceptance_validation`。
+- 每个 `feature_impl` 至少需要故事级完整链路验收证据；只跑单元测试、局部 smoke、affected tests、静态检查或 `git diff --check` 不足以完成任务。
+- 如果当前只是原型 / spike / exploratory 路径，不要把演示性交付直接标成正式 `FR-*` 完成；应改用 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 等单独标识，或在 spec / plan 中显式记录该 FR 仍处于未完成集成态。
+- 单元测试只能证明本地逻辑；集成型需求还必须补环境 smoke、E2E、真实下游连通性验证和验收证据 note。
+- Release 完成必须有发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证；不得把各子任务局部测试简单相加当作整测。
+- Stage 17 只负责 fresh evidence、affected tests 和 P0/P1 回归确认，不负责第一次定义需求测试范围。
+- 重构任务必须显式声明行为不变约束；接口、用户路径、数据结构和兼容逻辑不能在未说明时被顺手改变。
+- 重构结束前应按声明范围清理无用变量、无用函数、无用组件、无用类型、无用 import、临时代码和过期注释。
+
+## 技术栈验证基线
+
+| 改动类型 | 最小验证 |
+| --- | --- |
+| 文档 | `git diff --check` |
+| JSON | `ConvertFrom-Json` |
+| PowerShell | Parser 语法检查 |
+| TypeScript / 前端 | lint、typecheck、build |
+| API 或业务流程 | 单元测试、集成测试或 E2E，按风险选择 |

package/package-source/docs/codex-harness-engineering/templates/docs/requirement-prep-kit/README.md

@@ -1,3 +1,3 @@
-# Requirement Prep Kit
-
-本目录预留给需求收敛前的访谈、输入清洗、范围确认和验收准备模板。当前默认包不强制使用本目录；项目需要时可以在这里补充团队自己的需求准备表、访谈提纲或任务入口检查表。
+# Requirement Prep Kit
+
+本目录预留给需求收敛前的访谈、输入清洗、范围确认和验收准备模板。当前默认包不强制使用本目录；项目需要时可以在这里补充团队自己的需求准备表、访谈提纲或任务入口检查表。

package/package-source/docs/codex-harness-engineering/templates/docs/rule-governance.md

@@ -1,98 +1,98 @@
-# Harness Rule Governance
-
-本文定义规则如何进入 `AGENTS.md`、深文档、prompt、task template 和自动化检查。目标是控制指令预算，同时让关键约束可执行、可验证、可演进。
-
-## `docs/doc/1.md` 落地结论
-
-`docs/doc/1.md` 的核心价值不是把模板原样搬进本仓库，而是约束规则系统的形态：
-
-- `AGENTS.md` 做短入口，保留每次会话必须遵守的少量硬约束和深文档索引。
-- AI 可以从代码、schema、lint 或脚本推断 / 检查的内容，不进入 `AGENTS.md`。
-- 禁令必须带替代方案；例如不要伪造 `passes=true`，替代方案是让 `tools/harness/codex-loop.ps1` 在验证、review 和 commit gate 通过后写回状态。
-- Bad Case 先进入知识、prompt、role rules 或自动化检查；只有所有会话都必须知道时，才升级到 `AGENTS.md`。
-- 能自动检查的规则应进入 `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema、hook 或同步脚本，不长期只靠文字提醒。
-- 重要深文档必须被 `AGENTS.md` 引用，避免成为孤立文档。
-
-本仓库实践选择：入口文件控制在“读完即可开工”的长度；任务、验证、知识、prompt 和镜像同步细节分别落到 `docs/harness/*`、`.codex/rules/*.md`、`.codex/prompts/*` 和 `agent/` package mirrors。官方自动加载的 `.codex/rules/*.rules` 只承载命令执行策略。
-
-## 分层原则
-
-| 层级 | 放什么 | 不放什么 |
-| --- | --- | --- |
-| `AGENTS.md` | 每次会话都必须遵守的少量硬约束、入口索引 | 长模板、通用编码常识、会频繁变动的细节 |
-| `docs/harness/*` | driver、任务、验证、知识、治理等工程协议 | 具体业务需求 |
-| `.codex/rules/*.rules` | Codex 官方 execpolicy：命令 allow / prompt / forbidden | agent 编排、测试原则、编码风格、项目 instruction |
-| `.codex/rules/*.md` | agent 角色、阶段路由、协作边界等 Harness 语义规则 | 单个功能的临时计划；也不要误写成官方 execpolicy |
-| `.codex/prompts/*` | driver 注入给实现、review、repair 的执行提示 | 人类阅读优先的长说明 |
-| `task.json` | 当前真实任务队列和验证命令 | 模板示例、过期 smoke 占位 |
-
-## 规则进入标准
-
-只有满足以下至少一项，才应新增规则：
-
-- 同类问题在 review、trace 或失败记录中重复出现。
-- 违反后会造成安全、数据、提交、验证或上下文污染风险。
-- AI 无法从代码和现有文档自然推断。
-- 新人或新会话必须知道，否则会走错执行链路。
-
-以下内容默认不写进规则：
-
-- formatter、linter 已经确定性检查的风格细节。
-- “写清晰代码”这类无法改变行为的泛化建议。
-- README 面向人类读者的项目介绍。
-- 没有验证方式的一次性偏好。
-
-## 禁令写法
-
-禁令必须同时给替代方案：
-
-```text
-不要直接改 task.json 来伪造完成状态；应让 tools/harness/codex-loop.ps1 在验证、review 和 commit gate 通过后写回 passes=true。
-```
-
-如果无法给替代方案，先不要写成硬规则，改写成待确认风险或知识条目。
-
-## Bad Case 闭环
-
-每次出现 AI 错误，先判断应该落到哪里：
-
-| 错误类型 | 处理位置 |
-| --- | --- |
-| 单次任务失败 | `progress.txt`、trace、failure triage |
-| 可复用经验 | `docs/knowledge/pitfalls/` 或 `guidelines/` |
-| 会反复影响 driver 行为 | `.codex/prompts/*` 或 `.codex/rules/*.md` |
-| 可确定为命令权限边界 | `.codex/rules/*.rules` |
-| 所有会话必须知道 | `AGENTS.md` |
-| 可以自动检查 | `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema 或 hook |
-
-## 变更流程
-
-1. 先确认触发来源：trace、review finding、失败日志、用户明确要求或文档分析。
-2. 选择最小生效层级，不把深文档内容直接搬进 `AGENTS.md`。
-3. 如果改动影响模板或镜像，按 `harness-surface-sync` 同步 canonical source 和 mirrors。
-4. 运行最小验证：文档至少 `git diff --check`，JSON 需要 `ConvertFrom-Json`，PowerShell 需要 parser 检查。
-5. 提交前确认没有把 token、cookie、私钥、密码写入规则或 trace。
-
-## 定期治理
-
-建议每 10 个 driver 任务或每次较大 harness 改造后执行一次规则治理检查：
-
-- `AGENTS.md` 是否仍保持短入口。
-- 深文档是否有孤立规则没有被入口引用。
-- prompt 是否与 `AGENTS.md`、`.codex/rules/agents.md` 冲突。
-- `.codex/rules/*.rules` 是否仍只包含执行策略，且能通过 `codex execpolicy check`。
-- task template 是否还包含 smoke、示例领域或占位路径。
-- 知识条目是否有重复、过时、矛盾或长期未引用内容。
-
-## AGENTS.md 压缩检查表
-
-调整 `AGENTS.md` 时逐条检查：
-
-| 问题 | 处理 |
-| --- | --- |
-| 这条规则是否每次会话都必须知道？ | 是则保留，否则下沉到深文档 |
-| 这条规则是否已有脚本、schema、lint 或 hook 检查？ | 链接自动化位置，不重复写长说明 |
-| 这条规则是否只是通用工程常识？ | 删除 |
-| 这条规则是否只有禁止项？ | 补充替代方案，否则降级为风险说明 |
-| 这条规则是否源自单次失败？ | 先进入 `docs/knowledge/` 或 trace，不直接升级入口 |
-| 深文档是否在入口可发现？ | 在 `AGENTS.md` 索引补链接 |
+# Harness Rule Governance
+
+本文定义规则如何进入 `AGENTS.md`、深文档、prompt、task template 和自动化检查。目标是控制指令预算，同时让关键约束可执行、可验证、可演进。
+
+## `docs/doc/1.md` 落地结论
+
+`docs/doc/1.md` 的核心价值不是把模板原样搬进本仓库，而是约束规则系统的形态：
+
+- `AGENTS.md` 做短入口，保留每次会话必须遵守的少量硬约束和深文档索引。
+- AI 可以从代码、schema、lint 或脚本推断 / 检查的内容，不进入 `AGENTS.md`。
+- 禁令必须带替代方案；例如不要伪造 `passes=true`，替代方案是让 `tools/harness/codex-loop.ps1` 在验证、review 和 commit gate 通过后写回状态。
+- Bad Case 先进入知识、prompt、role rules 或自动化检查；只有所有会话都必须知道时，才升级到 `AGENTS.md`。
+- 能自动检查的规则应进入 `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema、hook 或同步脚本，不长期只靠文字提醒。
+- 重要深文档必须被 `AGENTS.md` 引用，避免成为孤立文档。
+
+本仓库实践选择：入口文件控制在“读完即可开工”的长度；任务、验证、知识、prompt 和镜像同步细节分别落到 `docs/harness/*`、`.codex/rules/*.md`、`.codex/prompts/*` 和 `agent/` package mirrors。官方自动加载的 `.codex/rules/*.rules` 只承载命令执行策略。
+
+## 分层原则
+
+| 层级 | 放什么 | 不放什么 |
+| --- | --- | --- |
+| `AGENTS.md` | 每次会话都必须遵守的少量硬约束、入口索引 | 长模板、通用编码常识、会频繁变动的细节 |
+| `docs/harness/*` | driver、任务、验证、知识、治理等工程协议 | 具体业务需求 |
+| `.codex/rules/*.rules` | Codex 官方 execpolicy：命令 allow / prompt / forbidden | agent 编排、测试原则、编码风格、项目 instruction |
+| `.codex/rules/*.md` | agent 角色、阶段路由、协作边界等 Harness 语义规则 | 单个功能的临时计划；也不要误写成官方 execpolicy |
+| `.codex/prompts/*` | driver 注入给实现、review、repair 的执行提示 | 人类阅读优先的长说明 |
+| `task.json` | 当前真实任务队列和验证命令 | 模板示例、过期 smoke 占位 |
+
+## 规则进入标准
+
+只有满足以下至少一项，才应新增规则：
+
+- 同类问题在 review、trace 或失败记录中重复出现。
+- 违反后会造成安全、数据、提交、验证或上下文污染风险。
+- AI 无法从代码和现有文档自然推断。
+- 新人或新会话必须知道，否则会走错执行链路。
+
+以下内容默认不写进规则：
+
+- formatter、linter 已经确定性检查的风格细节。
+- “写清晰代码”这类无法改变行为的泛化建议。
+- README 面向人类读者的项目介绍。
+- 没有验证方式的一次性偏好。
+
+## 禁令写法
+
+禁令必须同时给替代方案：
+
+```text
+不要直接改 task.json 来伪造完成状态；应让 tools/harness/codex-loop.ps1 在验证、review 和 commit gate 通过后写回 passes=true。
+```
+
+如果无法给替代方案，先不要写成硬规则，改写成待确认风险或知识条目。
+
+## Bad Case 闭环
+
+每次出现 AI 错误，先判断应该落到哪里：
+
+| 错误类型 | 处理位置 |
+| --- | --- |
+| 单次任务失败 | `progress.txt`、trace、failure triage |
+| 可复用经验 | `docs/knowledge/pitfalls/` 或 `guidelines/` |
+| 会反复影响 driver 行为 | `.codex/prompts/*` 或 `.codex/rules/*.md` |
+| 可确定为命令权限边界 | `.codex/rules/*.rules` |
+| 所有会话必须知道 | `AGENTS.md` |
+| 可以自动检查 | `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema 或 hook |
+
+## 变更流程
+
+1. 先确认触发来源：trace、review finding、失败日志、用户明确要求或文档分析。
+2. 选择最小生效层级，不把深文档内容直接搬进 `AGENTS.md`。
+3. 如果改动影响模板或镜像，按 `harness-surface-sync` 同步 canonical source 和 mirrors。
+4. 运行最小验证：文档至少 `git diff --check`，JSON 需要 `ConvertFrom-Json`，PowerShell 需要 parser 检查。
+5. 提交前确认没有把 token、cookie、私钥、密码写入规则或 trace。
+
+## 定期治理
+
+建议每 10 个 driver 任务或每次较大 harness 改造后执行一次规则治理检查：
+
+- `AGENTS.md` 是否仍保持短入口。
+- 深文档是否有孤立规则没有被入口引用。
+- prompt 是否与 `AGENTS.md`、`.codex/rules/agents.md` 冲突。
+- `.codex/rules/*.rules` 是否仍只包含执行策略，且能通过 `codex execpolicy check`。
+- task template 是否还包含 smoke、示例领域或占位路径。
+- 知识条目是否有重复、过时、矛盾或长期未引用内容。
+
+## AGENTS.md 压缩检查表
+
+调整 `AGENTS.md` 时逐条检查：
+
+| 问题 | 处理 |
+| --- | --- |
+| 这条规则是否每次会话都必须知道？ | 是则保留，否则下沉到深文档 |
+| 这条规则是否已有脚本、schema、lint 或 hook 检查？ | 链接自动化位置，不重复写长说明 |
+| 这条规则是否只是通用工程常识？ | 删除 |
+| 这条规则是否只有禁止项？ | 补充替代方案，否则降级为风险说明 |
+| 这条规则是否源自单次失败？ | 先进入 `docs/knowledge/` 或 trace，不直接升级入口 |
+| 深文档是否在入口可发现？ | 在 `AGENTS.md` 索引补链接 |

package/package-source/docs/codex-harness-engineering/templates/docs/service-dependency-matrix.md

@@ -1,55 +1,70 @@
-# Service Dependency Matrix
-
-本文件说明 `.service-matrix/dependencies.yaml` 的维护口径。它是多服务、多仓库、IDL / API 契约或外部系统集成项目的可选 truth source；单体、小型前端或一次性脚本可以标记为 `not_applicable`。
-
-## 适用条件
-
-满足任一条件时，应启用服务依赖矩阵：
-
-- 一个需求会修改或影响多个服务、包、仓库、worker、前端应用或脚本入口。
-- 涉及 OpenAPI、protobuf、GraphQL schema、数据库 schema、消息事件、文件格式或第三方 API 契约。
-- 需要确认上游调用方、下游依赖方、灰度、回滚、兼容性或分支一致性。
-- 过去出现过“AI 只改了局部代码但漏掉调用链 / 契约 / 下游影响”的返工。
-
-## 维护原则
-
-- 矩阵只记录稳定拓扑和契约事实，不记录一次性任务过程。
-- 不把矩阵写成项目百科；每条依赖必须能回答“谁依赖谁、通过什么契约、变更时检查什么”。
-- 如果依赖需要人工确认，写 `status: needs-confirmation`，不得让实现任务继续猜。
-- 如果某个项目不需要矩阵，在 `docs/architecture/constraints.md` 中写明 `service_matrix: not_applicable`。
-
-## 最小字段
-
-| 字段 | 说明 |
-| --- | --- |
-| `service_id` | 稳定服务、应用、包、worker 或集成名 |
-| `repo_path` | 当前仓库内路径或外部仓库标识 |
-| `entrypoints` | HTTP route、CLI command、worker、UI route、package export 等公开入口 |
-| `contracts` | OpenAPI、protobuf、GraphQL、typed API、schema、event、file format 或 `none` |
-| `upstream` | 调用本服务 / 包 / 入口的上游 |
-| `downstream` | 本服务 / 包 / 入口调用的下游 |
-| `change_gates` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
-| `owner` | 维护 owner 或确认人 |
-| `status` | `active` / `draft` / `needs-confirmation` / `deprecated` / `not_applicable` |
-
-## Driver 使用方式
-
-- `ANALYSIS` 阶段识别本轮需求是否需要服务矩阵；需要时补齐 `.service-matrix/dependencies.yaml`。
-- `PLAN` 阶段把受影响服务、契约和 change gates 映射到每个 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
-- `feature_impl` 阶段不得新增未声明的跨服务影响；发现矩阵缺失或不可信时输出 `BLOCKED`。
-- `release` 阶段必须验证跨服务主链路、契约/API、失败态和回写证据。
-
-## Review 口径
-
-Stage 1 先检查矩阵是否足以支撑实现计划：
-
-- 受影响服务是否都已列出。
-- 上下游、契约、分支或版本约束是否明确。
-- 是否有未确认依赖被实现任务当成已确认事实。
-- 验证命令是否覆盖矩阵中的 change gates。
-
-Stage 2 再检查代码是否真的遵守矩阵：
-
-- 公开入口、契约、实现、测试和证据是否一致。
-- 是否漏改下游调用、mock、生成代码、schema 或配置。
-- 失败、回滚、兼容性和灰度路径是否有证据。
+# Service Dependency Matrix
+
+本文件说明 `.service-matrix/dependencies.yaml` 的维护口径。它是多服务、多仓库、IDL / API 契约或外部系统集成项目的可选 truth source；单体、小型前端或一次性脚本可以标记为 `not_applicable`。
+
+## 适用条件
+
+满足任一条件时，应启用服务依赖矩阵：
+
+- 一个需求会修改或影响多个服务、包、仓库、worker、前端应用或脚本入口。
+- 涉及 OpenAPI、protobuf、GraphQL schema、数据库 schema、消息事件、文件格式或第三方 API 契约。
+- 需要确认上游调用方、下游依赖方、灰度、回滚、兼容性或分支一致性。
+- 过去出现过“AI 只改了局部代码但漏掉调用链 / 契约 / 下游影响”的返工。
+
+## 维护原则
+
+- 矩阵只记录稳定拓扑和契约事实，不记录一次性任务过程。
+- 不把矩阵写成项目百科；每条依赖必须能回答“谁依赖谁、通过什么契约、变更时检查什么”。
+- 如果依赖需要人工确认，写 `status: needs-confirmation`，不得让实现任务继续猜。
+- 如果某个项目不需要矩阵，在 `docs/architecture/constraints.md` 中写明 `service_matrix: not_applicable`。
+
+## 最小字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `service_id` | 稳定服务、应用、包、worker 或集成名 |
+| `repo_path` | 当前仓库内路径或外部仓库标识 |
+| `entrypoints` | HTTP route、CLI command、worker、UI route、package export 等公开入口 |
+| `contracts` | OpenAPI、protobuf、GraphQL、typed API、schema、event、file format 或 `none` |
+| `upstream` | 调用本服务 / 包 / 入口的上游 |
+| `downstream` | 本服务 / 包 / 入口调用的下游 |
+| `change_gates` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
+| `callback_webhook` | 回调、Webhook、验签入口或 `none` |
+| `credential_source` | 凭据 / Secret 注入位置或 `none` |
+| `retry_idempotency` | 外部调用的重试、幂等、去重策略 |
+| `rate_limit_or_quota` | 第三方频率限制、配额或防刷规则 |
+| `failure_fallback` | 超时、失败、降级、补偿或人工介入策略 |
+| `owner` | 维护 owner 或确认人 |
+| `status` | `active` / `draft` / `needs-confirmation` / `deprecated` / `not_applicable` |
+
+## Driver 使用方式
+
+- `ANALYSIS` 阶段识别本轮需求是否需要服务矩阵；需要时补齐 `.service-matrix/dependencies.yaml`。
+- `PLAN` 阶段把受影响服务、契约和 change gates 映射到每个 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `feature_impl` 阶段不得新增未声明的跨服务影响；发现矩阵缺失或不可信时输出 `BLOCKED`。
+- `release` 阶段必须验证跨服务主链路、契约/API、失败态和回写证据。
+
+## 第三方服务专项
+
+如果依赖项属于支付、短信、邮件、推送、对象存储、上传扫描、OCR、AI API 或其他外部平台，矩阵至少补齐：
+
+- 回调 / Webhook / 验签入口
+- 凭据来源与注入位置
+- 幂等 / 重试 / 超时 / 降级策略
+- 频率限制、配额或防刷边界
+- 失败时的人工介入、补偿或对账路径
+
+## Review 口径
+
+Stage 1 先检查矩阵是否足以支撑实现计划：
+
+- 受影响服务是否都已列出。
+- 上下游、契约、分支或版本约束是否明确。
+- 是否有未确认依赖被实现任务当成已确认事实。
+- 验证命令是否覆盖矩阵中的 change gates。
+
+Stage 2 再检查代码是否真的遵守矩阵：
+
+- 公开入口、契约、实现、测试和证据是否一致。
+- 是否漏改下游调用、mock、生成代码、schema 或配置。
+- 失败、回滚、兼容性和灰度路径是否有证据。