@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,122 +0,0 @@
-# Codex Harness Engineering 最佳实践包
-
-**日期**: 2026-04-16  
-**适用环境**: Windows + PowerShell + Codex CLI + Git 仓库  
-**目标**: 把 Codex 从一次性对话工具升级为可复用、可审计、可验证的自动化工程执行系统。
-
-## 0. 从哪里开始
-
-如果这是你第一次进入这个目录，先读 `START-HERE.md`，再读 `mode-matrix.md` 理解当前唯一保留的 `full` driver-first 主链路。
-
-## 1. 当前范围
-
-这套文档和模板当前只保留单工作区、单 driver 的执行模型：
-
-```text
-task.json
-  -> tools/harness/codex-loop.ps1
-  -> codex exec
-  -> lint/build/test/eval
-  -> progress.txt + trace.json
-  -> task.json passes=true
-  -> git commit
-```
-
-额外 Git 执行工作区、外部 worker 编排、控制面状态机和相关模板已经从当前包中移除。
-
-## 2. 主要内容
-
-| 文件 | 用途 |
-| --- | --- |
-| `README.md` | 当前目录总览 |
-| `START-HERE.md` | 首次进入目录时的分流入口 |
-| `mode-matrix.md` | `user/project/vendor/full` 的职责边界、状态源、持续运行定位和验证入口 |
-| `best-practices.md` | 任务、上下文、权限、测试、阻塞、提交、回归沉淀的最佳实践 |
-| `implementation-flow.md` | 从 当前仓库包根结构出发说明安装、bootstrap、driver、验证、知识归档和同步的整体实现流程 |
-| `goal-harness-integration-guide.md` | 说明如何把 Codex `/goal` 与 Harness driver/stop hook 结合使用，包含推荐用法和提示词模板 |
-| `harness-analysis-and-practice.md` | GitHub 调研后的 Harness 工程分析、当前安装包工程评估和改进路线图 |
-| `harness-quality-model.md` | 定义好的、好用的、完整的 Harness 工程质量模型、成熟度和评分标准 |
-| `harness-improvement-plan.md` | 基于质量模型和源码审计的 Harness 改进计划，说明每项改哪里、怎么改、如何验收 |
-| `implementation-guide.md` | 在当前 Windows + Codex CLI 工程中落地的步骤 |
-| `global-rules-and-bootstrap.md` | 全局规则写法、新项目接入和新环境初始化教程 |
-| `codex-global-rules-example.md` | `~/.codex/AGENTS.md` 和 `~/.codex/config.toml` 的推荐配置示例与分层边界 |
-| `agent-ecosystem-practices.md` | 分析大型项目 AI 编程生态实践，说明哪些内容应吸收到 当前仓库包根、模板、skills、hooks 和 MCP 配置 |
-| `spec-to-ui-to-code-workflow.md` | 从需求、设计、前端、契约到回归的前端先行闭环 |
-| `templates/docs/frontend-quality-rules.md` | 前端审美、动效、响应式、可访问性、性能和证据要求 |
-| `templates/docs/service-dependency-matrix.md` | 多服务、多仓库、契约和外部系统影响面的可选 truth source 维护口径 |
-| `templates/design/frontend-architecture.md` | 前端页面、feature、组件、状态、API、响应式和测试边界模板 |
-| `examples/goal-templates.md` | `/goal` 启动模板库，强调它是外层控制壳而不是替代 `task.json` / spec 的目标定义 |
-| `templates/` | 可复制模板集中目录 |
-| `templates/docs/project-agents-template.md` | 根据不同项目事实生成项目根 `AGENTS.md` / 子目录 `AGENTS.md` / `CLAUDE.md` 组合的通用模板 |
-
-## 3. 快速使用方式
-
-1. 先读 `START-HERE.md`。
-2. 再读 `global-rules-and-bootstrap.md` 和 `codex-global-rules-example.md`。
-3. 读 `mode-matrix.md`，确认当前项目使用 full driver-first 主链路。
-4. 运行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\codex-harness-engineering\templates\bootstrap-codex-harness.ps1 -ProjectRoot .
-```
-
-5. 如果这是一个刚初始化的全新仓库，先提交一次 bootstrap 基线，避免 driver 因未解释改动直接阻塞。
-6. 如果需要把根 `AGENTS.md` 调整为项目专属规则，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成，不要原样套模板。
-7. 首次接入时，建议先用 `templates/runtime/smoke-task.json` 验证主链路；一旦 spec / plan 确认，就改用 `templates/runtime/project-task-template.json` 生成正式 `task.json` 并切回 driver。
-8. 正式任务队列落盘前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/ACCEPTANCE_EXAMPLES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/verify-matrix.md` 等测试左移真相源。
-9. 如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 `docs/testing/e2e-plan.md`，并先从 `docs/ai/repo-map.md` 进入代码结构后再做实现规划。
-10. 运行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1
-```
-
-## 4. 推荐项目结构
-
-```text
-<project-root>/
-  AGENTS.md
-  task.json
-  progress.txt
-  tools/harness/codex-loop.ps1
-  .codex/
-    task-run-profile.json
-  .service-matrix/
-    dependencies.yaml
-  docs/
-    ai/
-      repo-map.md
-      architecture-brief.md
-    harness/
-      architecture.md
-      frontend-quality-rules.md
-      service-dependency-matrix.md
-      new-project-usage.md
-      regression-rules.md
-      sandbox-policy.md
-      task-session-strategy.md
-      trace-format.md
-    testing/
-      ACCEPTANCE_CRITERIA.md
-      ACCEPTANCE_EXAMPLES.md
-      TEST_STRATEGY.md
-      TRACEABILITY_MATRIX.md
-      RISK_BASED_TEST_PLAN.md
-      REGRESSION_PLAN.md
-      EVIDENCE_PROTOCOL.md
-      TEST_DATA_MATRIX.md
-      test-matrix.md
-      verify-matrix.md
-  traces/
-    <task-id>-<timestamp>.json
-```
-
-## 5. 参考资料
-
-- OpenAI Codex CLI: https://developers.openai.com/codex/cli
-- OpenAI Codex non-interactive mode: https://developers.openai.com/codex/noninteractive
-- OpenAI Codex AGENTS.md: https://developers.openai.com/codex/guides/agents-md
-- OpenAI Codex MCP: https://developers.openai.com/codex/mcp
-- OpenAI Codex hooks: https://developers.openai.com/codex/hooks
-- OpenAI Codex GitHub Action: https://developers.openai.com/codex/github-action
-- OpenAI Harness Engineering: https://openai.com/index/harness-engineering/

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/START-HERE.md

@@ -1,53 +0,0 @@
-# Codex Harness Engineering Start Here
-
-这份文档只做一件事：
-
-- 帮第一次进入 `codex-harness-engineering/` 的人快速判断应该先读什么、先做什么。
-
-## 路线 A：先理解方法论
-
-推荐阅读顺序：
-
-1. `README.md`
-2. `mode-matrix.md`
-3. `global-rules-and-bootstrap.md`
-4. `implementation-guide.md`
-
-## 路线 B：把 Harness 接到一个新项目
-
-推荐阅读顺序：
-
-1. `README.md`
-2. `mode-matrix.md`
-3. `global-rules-and-bootstrap.md`
-4. `implementation-guide.md`
-
-建议执行顺序：
-
-1. 确认目标目录本身是 Git 仓库。
-2. 运行 `templates/bootstrap-codex-harness.ps1`。
-3. 如果这是全新仓库，先提交一次 bootstrap 基线。
-4. 先裁剪 `docs/ai/repo-map.md` 和 `docs/ai/architecture-brief.md`，让 Agent 能准确导航目标项目。
-5. 需要项目专属 `AGENTS.md` 时，按 `templates/docs/project-agents-template.md` 扫描项目事实后裁剪生成。
-6. 先使用 `templates/runtime/smoke-task.json` 做首次自检。
-7. 补齐 `docs/testing/ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md`、`TEST_DATA_MATRIX.md` 等实现前 testing truth source。
-8. 通过后再替换为真实业务 `task.json`。
-
-## 路线 C：给现有项目补自动化
-
-推荐阅读顺序：
-
-1. `README.md`
-2. `mode-matrix.md`
-3. `global-rules-and-bootstrap.md`
-4. `implementation-guide.md`
-
-## 最短路径
-
-1. 读 `README.md`
-2. 读 `mode-matrix.md`
-3. 跑 `templates/bootstrap-codex-harness.ps1`
-4. 提交 bootstrap 基线
-5. 裁剪 `docs/ai/repo-map.md`
-6. 用 `templates/runtime/smoke-task.json` 跑一次 smoke
-7. 补 testing truth source，再进入 `implementation-guide.md`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/agent-ecosystem-practices.md

@@ -1,140 +0,0 @@
-# Agent 生态实践吸收建议
-
-本文分析一组关于大型项目中使用 AI 编程工具的实践材料，并说明哪些内容适合吸收到 当前仓库包根，哪些应该保持为项目本地配置或后续扩展。
-
-核心判断：决定效果的不是单个模型，而是围绕模型建立的可导航、可验证、可分发、可复盘的工程环境。对本仓库来说，当前仓库包根就是这套环境的分发载体。
-
-## 可吸收内容总览
-
-| 来源思想 | 在 `agent/` 中的落点 | 吸收方式 |
-| --- | --- | --- |
-| 根入口规则保持短小 | `templates/runtime/AGENTS.md`、`templates/docs/project-agents-template.md` | 强化短入口、深文档索引、子目录规则分层 |
-| 子目录级规则按需加载 | `templates/docs/project-agents-template.md` | 只在目录规则明显不同的模块生成子目录 `AGENTS.md` |
-| 代码地图提升检索效率 | `templates/context/repo-map.md`、`update-codemaps` skill | 把 repo map / codemap 作为 AI 导航索引维护 |
-| 技能承载固定流程 | `skills/*`、`templates/package-assets/skills/*` | 将安全审查、文档同步、代码地图更新等流程沉淀为 skill |
-| Hooks 做自动化一致行为 | `templates/hooks/*` | 保持为增强层，用于 stop-gate、反馈门禁、会话复盘触发 |
-| 插件 / 包做团队分发 | `agent/` package assets | 通过 package mirrors 分发 rules、skills、prompts、hooks、docs |
-| MCP 连接外部系统 | `templates/config/mcp-config.toml`、接入文档 | 只放非敏感模板，真实服务和密钥留在项目配置或环境变量 |
-| LSP 提升代码导航 | `global-rules-and-bootstrap.md`、环境检查建议 | 作为环境建议，不把具体语言服务器写成所有项目硬约束 |
-| 定期规则治理 | `rule-governance.md`、`best-practices.md` | 3-6 个月或模型升级后清理过时规则 |
-
-## 1. 入口规则分层
-
-材料中强调不要把所有知识都塞进 `CLAUDE.md`。在 Codex / AGENTS 体系里，同样适用：
-
-- 全局 `~/.codex/AGENTS.md` 只放跨项目稳定习惯。
-- 项目根 `AGENTS.md` 只放每次会话必须知道的项目规则、真实入口和深文档索引。
-- 子目录 `AGENTS.md` 只在 monorepo、支付、权限、数据迁移等目录约束明显不同的地方添加。
-- 具体流程、长模板、复盘经验应下沉到 `docs/`、`.codex/rules/`、`.codex/prompts/` 或 skill。
-
-不建议吸收到根入口的内容：
-
-- 某个团队的口头偏好。
-- 已经能由 lint、schema、verify、hook 检查的长规则。
-- 只对单个模块成立的细节。
-
-## 2. 代码地图作为 AI 导航索引
-
-大型代码库中，AI 最大的浪费通常发生在“找错地方”和“全仓扫描”。因此 当前仓库包根应把 repo map / codemap 当成一等公民。
-
-推荐结构：
-
-```text
-AGENTS.md
-docs/ai/repo-map.md
-docs/ai/architecture-brief.md
-docs/architecture/constraints.md
-docs/harness/*
-docs/testing/*
-```
-
-根 `AGENTS.md` 应明确说明：需要理解代码结构时，先读 `docs/ai/repo-map.md` 或项目声明的同类文件，再进入具体模块；进入具有子目录 `AGENTS.md` 的模块后，必须同时遵守根规则和本地规则。
-
-代码地图应该记录：
-
-- 项目目标和主要业务域。
-- 关键目录职责。
-- 模块入口和真实 truth source。
-- 生成代码、外部系统、敏感目录和禁改区。
-- 常用验证命令。
-- 最近更新时间和维护责任。
-
-不应记录：
-
-- 大段源码解释。
-- 每个函数的实现细节。
-- 会频繁变化但没有维护机制的临时路径。
-
-## 3. 技能沉淀固定流程
-
-材料中“技能按需加载”的思想已符合当前 `docs/codex-harness-engineering/templates/package-assets/skills/*` 设计。适合继续吸收的方向：
-
-- 把重复的工作流沉淀成 skill，例如 code review、API contract、E2E planning、codemap 更新、文档同步。
-- skill 描述必须写清触发场景，避免每次会话都加载。
-- skill 内部要给确定性步骤、输入输出、验证方式和可复用脚本。
-- 专家知识优先放 skill，不放根 `AGENTS.md`。
-
-判断是否应创建 skill：
-
-| 条件 | 处理 |
-| --- | --- |
-| 多个项目复用同一流程 | 创建或更新 skill |
-| 只影响当前项目一次 | 放任务文档或 `docs/knowledge/` |
-| 可以脚本化 | skill 调用脚本，不重复写大段命令 |
-| 必须所有会话知道 | 才升级为 `AGENTS.md` 入口规则 |
-
-## 4. Hooks 的边界
-
-材料中提到 hooks 可用于格式化、检查和会话学习。对当前 Windows + PowerShell driver-first harness，边界应更保守：
-
-- hooks 可以作为增强层，例如 stop-gate、feedback-gate、格式检查提醒、复盘入口。
-- 不把 hooks 当主链路；任务选择、验证、trace、commit 仍由 `tools/harness/codex-loop.ps1` 负责。
-- 会话复盘不应每轮都写知识库，建议按轮次、失败类型或人工确认触发，避免低质量经验污染规则。
-- hook 产生的新知识先进入 `docs/knowledge/` 或 review queue，经治理后再升级为规则、prompt 或 skill。
-
-## 5. 包和插件分发
-
-材料中“插件像私有包一样分发能力”的思想，在本仓库对应 `agent/` package：
-
-- `.codex/rules/*` 分发角色和阶段规则。
-- `.codex/prompts/*` 分发 driver 注入提示。
-- `skills/*` 分发可复用流程。
-- `templates/hooks/*` 分发增强 hooks。
-- `docs/codex-harness-engineering/*` 分发人类可读方法论。
-
-新增或更新这些能力时，必须按同步矩阵刷新 package mirrors，避免只改活跃副本导致新项目安装不到。
-
-## 6. MCP 与外部系统
-
-MCP 适合连接工单、需求、设计、测试、知识库、监控等外部系统。`agent/` 里应吸收的是模板和边界，而不是真实配置：
-
-- 提供 `mcp-config.toml` 示例。
-- 文档说明 MCP 适合读取哪些外部 truth source。
-- 密钥、token、私有 URL、账号信息必须留在环境变量、用户配置或项目私有配置中。
-- 任务声明如果依赖外部系统，完成证据必须包含真实接入成功态和失败态，而不是 mock-only 结果。
-
-## 7. LSP 与导航工具
-
-LSP 对大型项目有明显价值，但具体语言服务器取决于项目技术栈。适合吸收为环境建议：
-
-- 新环境初始化时提示安装对应语言插件或 LSP。
-- 对 Java、TypeScript、Python、Go 等项目，在项目 `AGENTS.md` 或 README 中列出本项目推荐工具。
-- 不在全局规则里强制某个语言服务器。
-
-## 8. 定期治理
-
-模型能力、工具行为和团队工作流会变化。当前仓库包根应明确治理节奏：
-
-- 模型或 CLI 大版本升级后，检查 `AGENTS.md`、rules、prompts、skills 是否仍必要。
-- 每 3-6 个月清理一次重复、过时、已经自动化的文字规则。
-- 对失败复盘优先补测试、schema、verify 或 hook，再考虑写规则。
-- 入口规则越短，越容易长期保持有效。
-
-## 推荐落地优先级
-
-1. 先完善 `AGENTS.md` 分层、repo map 模板和 `update-codemaps` skill。
-2. 再把高频流程沉淀成 skill，避免继续增肥入口规则。
-3. 然后治理 hooks，让它们只做增强和复盘入口。
-4. 最后补 MCP、LSP、插件分发文档和环境检查。
-
-这套吸收方式可以把材料中的经验转成 当前仓库包根可分发的工程资产，同时避免把长篇知识直接塞进每次会话上下文。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/best-practices.md

@@ -1,267 +0,0 @@
-# Codex Harness Engineering 最佳实践
-
-## 1. 总原则
-
-Codex Harness 的目标不是让 Codex “更自由”，而是让 Codex 在明确边界内持续交付。
-
-本目录已经为当前推荐分层提供了可复制模板。先看 `README.md` 和 `templates/README.md`，再按项目成熟度复制 `templates/` 下的最小组合。
-
-实践优先级如下：
-
-1. **结构化任务优先于口头指令**：任务必须有 id、描述、步骤、依赖、验收和测试命令。
-2. **确定性验证优先于模型自评**：任务是否完成由 lint、build、test、e2e、eval 和 Git 状态判断。
-3. **测试左移优先于末端补测**：实现前先补齐验收示例、追溯矩阵、测试数据和回归范围。
-4. **短入口文档优先于巨型规则文档**：`AGENTS.md` 只放硬规则和索引，细节放 `docs/`。
-5. **隔离执行优先于共享脏工作区**：自动任务启动前必须检查 Git 工作区。
-6. **回归约束优先于经验提醒**：失败后优先补测试、lint、driver 校验或 eval，最后才写文档提醒。
-
-## 2. 任务设计
-
-一个合格任务必须包含：
-
-| 字段 | 要求 |
-| --- | --- |
-| `id` | 稳定、唯一、可用于提交信息和 trace 文件名 |
-| `description` | 一句话描述业务目标，不写实现细枝末节 |
-| `priority` | 数字越小优先级越高 |
-| `dependencies` | 依赖任务全部通过后才能执行 |
-| `passes` | 只有验证通过后才能改成 `true` |
-| `requirement_ids` | 关联的需求编号，必须能回到追溯矩阵和验收示例 |
-| `steps` | 2-8 个执行步骤，足够具体但不过度限定实现 |
-| `owned_paths` | 当前任务允许接管的代码或文档范围 |
-| `test_command` | 单任务必须运行的验证命令 |
-| `acceptance` | 可验证的验收标准 |
-
-不要把多个独立功能塞进一个任务。单个 `codex exec` 会话只处理一个任务，这样失败时可以清晰定位。
-
-对 `feature_impl` 类任务，还应额外满足：
-
-- 实现前能从 `TRACEABILITY_MATRIX.md` 和 `ACCEPTANCE_EXAMPLES.md` 找到对应 Requirement IDs。
-- 任务描述能说清 affected tests、验证层级和证据路径。
-- 不能把“先写实现，最后再补测试范围”当成默认策略。
-
-## 3. 上下文组织
-
-Codex 会在启动时读取 `AGENTS.md` 链。官方文档说明，Codex 会从全局、项目根到当前目录逐层合并指导文件，并受 `project_doc_max_bytes` 限制。因此推荐：
-
-```text
-AGENTS.md                  # 入口规则和索引
-docs/ai/repo-map.md        # 代码地图和导航索引
-docs/ai/architecture-brief.md # 架构摘要和分层职责
-docs/harness/*.md          # 自动化规则
-docs/architecture/*.md     # 架构说明
-docs/testing/*.md          # 测试策略
-<module>/AGENTS.md         # 只在目录规则明显不同时添加
-```
-
-`AGENTS.md` 推荐结构：
-
-```markdown
-# AGENTS.md
-
-## 当前工程规则
-
-- 每次只处理 `task.json` 中一个 `passes: false` 的任务。
-- 需要理解代码结构时，先读 `docs/ai/repo-map.md` 或项目声明的同类代码地图。
-- 修改代码后必须运行任务指定的 `test_command`。
-- 测试失败时禁止把任务标记为通过。
-- 阻塞时必须写入 `progress.txt` 并输出 BLOCKED。
-
-## 深文档索引
-
-- Harness 规则: `docs/harness/architecture.md`
-- 代码地图: `docs/ai/repo-map.md`
-- 架构摘要: `docs/ai/architecture-brief.md`
-- 回归规则: `docs/harness/regression-rules.md`
-- Trace 格式: `docs/harness/trace-format.md`
-- 验收示例: `docs/testing/ACCEPTANCE_EXAMPLES.md`
-- 需求追溯: `docs/testing/TRACEABILITY_MATRIX.md`
-- 验证矩阵: `docs/testing/verify-matrix.md`
-```
-
-根 `AGENTS.md` 不应承载所有业务知识。目录级规则、架构约束、代码地图、测试策略、历史坑和固定流程应分别下沉到子目录 `AGENTS.md`、`docs/architecture/`、`docs/ai/repo-map.md`、`docs/testing/`、`docs/knowledge/` 和 `skills/`。当新增大型模块、外部系统、生成代码或敏感目录时，优先更新代码地图；只有该规则会影响每次会话时，才升级到入口文件。
-
-## 4. 执行控制
-
-Windows 不应依赖 Codex hooks 作为主链路。Codex hooks 可以作为结束前 stop-gate、feedback-gate 这类增强层；确定性控制仍由 PowerShell driver 承担：
-
-- 选择一个任务。
-- 检查依赖。
-- 检查 Git 工作区。
-- 生成 prompt。
-- 调用 `codex exec`。
-- 检测 `BLOCKED`。
-- 运行测试命令。
-- 更新 `task.json` 和 `progress.txt`。
-- 生成 trace。
-- 提交 Git commit。
-
-同理，Codex 官方 `/goal` 更适合作为**外层长期目标控制面**，而不是直接替代当前仓库的 `task.json + codex-loop.ps1 + stop hook` 执行协议。当前 Harness 的推荐分层仍然是：
-
-- `/goal` 负责长期目标保持和人机 steering
-- driver 负责任务、验证、trace 和提交
-- stop hook 负责停止前治理门和 continuation 决策
-
-要明确区分两层职责：
-
-- 内层 `codex exec` 会话只负责当前任务直接要求的代码或文档改动。
-- 外层 driver 负责 `task.json`、`progress.txt`、`traces/*.json` 和 Git 提交。
-
-如果把这两层职责混在一起，常见后果是状态文件重复写入、二次 trace、dirty workspace 回流，以及 driver 已提交后又被后续会话写脏。
-
-推荐命令：
-
-```powershell
-codex exec --sandbox danger-full-access -C <ProjectRoot> -
-```
-
-只在隔离、干净、可审计的工作区使用 `danger-full-access`。普通 CI 或审查任务优先使用 `workspace-write` 或只读模式。
-
-## 5. 权限与安全
-
-权限策略按最小化原则选择：
-
-| 场景 | 推荐 sandbox | 说明 |
-| --- | --- | --- |
-| 只读审查 | `read-only` | 不允许改文件 |
-| 常规修复 | `workspace-write` | 只允许写工作区 |
-| 本地无人值守实现 | `danger-full-access` | 仅用于可信机器和干净工作区 |
-| CI PR 审查 | GitHub Action + `workspace-write` | 限制触发者和 secret 暴露 |
-
-禁止把 secret、token、cookie、私钥写入 prompt、trace 或 progress。GitHub Action 中必须限制触发者，避免把不可信 issue 或 PR 文本直接喂给 Codex。
-
-## 6. 验证策略
-
-验证不是只发生在任务结束时。实现前至少要先有：
-
-- `ACCEPTANCE_CRITERIA.md`
-- `ACCEPTANCE_EXAMPLES.md`
-- `TRACEABILITY_MATRIX.md`
-- `TEST_DATA_MATRIX.md`
-- `test-matrix.md`
-- 必要时的 `RISK_BASED_TEST_PLAN.md`、`REGRESSION_PLAN.md`、`EVIDENCE_PROTOCOL.md`
-
-推荐验证顺序：
-
-```text
-格式检查
-  -> 静态检查
-  -> 类型检查
-  -> 单元测试
-  -> 集成测试
-  -> E2E
-  -> 业务 eval
-```
-
-最小任务可以只跑 `git diff --check` 或 `npm run build`，但跨模块改动必须扩大验证范围。PowerShell 中不要用普通分号串联多个会失败的命令，否则前一个命令失败可能被后一个命令的退出码掩盖。需要显式检查 `$LASTEXITCODE`，或者把多个检查封装成项目内 `npm run verify`、`make verify` 这类单一命令。
-
-对 smoke/self-check 类任务，`test_command` 不能只校验“文件存在”。如果结果文件还承担语义说明作用，例如必须写出“内层 Codex 自动实现会话生成结果文件”，那么测试命令也必须检查关键文本内容和基本文件质量，否则 Stage 2 review 应该把它判为测试覆盖缺口。
-
-同时，不要把**外层 driver 才会在 Stage 2 之后写入的状态产物**直接放进 smoke task 的任务验收里，例如：
-
-- `task.json` 中 `passes=true`
-- `progress.txt` 完成记录
-- `traces/` 目录和 trace 文件
-- 自动提交
-
-这些应改为 smoke run 完成后的外层检查清单，否则两阶段审查会在外层产物落盘前就把任务判失败。
-
-Stage 17 的职责也要收窄：
-
-- 运行 fresh evidence。
-- 运行 affected tests 和 P0/P1 regression。
-- 校验 verify matrix、契约验证和端到端证据是否仍然成立。
-
-不要在 Stage 17 第一次补需求测试范围、第一次写验收示例，或第一次决定应该测什么。
-
-验收不要写成“实现良好”“用户体验好”这种主观描述，应写成：
-
-- `npm run lint` 退出码为 0。
-- `/api/orders` 对缺失参数返回 400。
-- `progress.txt` 包含任务 id 和测试结果。
-- `task.json` 中对应任务 `passes` 为 `true`。
-
-## 7. 阻塞处理
-
-遇到以下情况必须 BLOCKED：
-
-- 缺少 API key、账号、权限或外部服务。
-- 任务描述互相矛盾。
-- 测试命令持续失败且无法确认根因。
-- 工作区启动时已有未解释的未提交改动。
-- 需要人工产品决策。
-
-阻塞输出必须包含：
-
-```text
-BLOCKED - 需要人工介入
-
-当前任务: <task-id> <description>
-
-已完成的工作:
-- ...
-
-阻塞原因:
-- ...
-
-需要人工操作:
-1. ...
-
-解除阻塞后请运行:
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1
-```
-
-阻塞时禁止提交、禁止把 `passes` 改为 `true`、禁止继续处理下一个任务。
-
-## 8. 进度与 trace
-
-`progress.txt` 面向人类，记录任务摘要、测试结果和后续提示。`traces/*.json` 面向机器，记录命令、退出码、文件改动、状态和失败原因。
-
-模板层面有两个推荐约定：
-
-- `templates/runtime/progress.txt` 保持空白初始状态，不要预填演示记录。
-- 新项目第一次接入先跑 `templates/runtime/smoke-task.json`，不要一上来就用真实业务任务验证 Harness。
-
-推荐 trace 字段：
-
-| 字段 | 说明 |
-| --- | --- |
-| `task_id` | 当前任务 |
-| `agent` | `codex`、`claude-code` 或其他 |
-| `started_at` / `ended_at` | 时间范围 |
-| `status` | `passed`、`failed`、`blocked` |
-| `commands` | 命令和退出码 |
-| `files_changed` | Git 检测到的文件 |
-| `blocked_reason` | 阻塞原因 |
-| `final_message` | Codex 最终消息摘要 |
-
-## 9. 提交规则
-
-自动任务的提交必须满足：
-
-- 启动前工作区干净，或只有当前任务明确接管的改动。
-- 代码、文档、`task.json`、`progress.txt`、trace 在同一 commit。
-- 测试全部通过后才允许 `passes=true`。
-- commit message 包含任务 id。
-
-推荐格式：
-
-```text
-feat: <task description> - completed <task-id>
-```
-
-## 10. 回归沉淀
-
-每次失败都要问：下次怎么让机器自动发现？
-
-| 失败类型 | 优先沉淀方式 |
-| --- | --- |
-| 构建失败 | build/test 命令加入 `test_command` |
-| 类型遗漏 | 增加 typecheck 或单测 |
-| 格式问题 | 增加 formatter/lint/diff check |
-| 文件误改 | driver 增加路径白名单或启动前 dirty 检查 |
-| 重复需求误解 | 改 `task.json` 模板和 prompt |
-| 外部服务缺失 | 增加环境变量检查 |
-| 隐蔽业务错误 | 增加 E2E 或业务 eval |
-
-不要只把失败写进“注意事项”。能自动化的必须自动化。