@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/global-rules-and-bootstrap.md

@@ -0,0 +1,399 @@
+# Codex 全局规则与环境接入教程
+
+本教程回答三个问题：
+
+1. 全局规则应该写什么？
+2. 新项目应该怎么接入 Codex Harness？
+3. 新环境或新电脑应该怎么初始化？
+
+如果只需要可复制的 `~/.codex/AGENTS.md` 和 `~/.codex/config.toml` 示例，先看 `codex-global-rules-example.md`。
+
+## 1. 先分清三层规则
+
+不要把所有规则都塞进一个 `AGENTS.md`。推荐拆成三层：
+
+| 层级     | 位置                         | 应该放什么                                               | 不应该放什么                           |
+| -------- | ---------------------------- | -------------------------------------------------------- | -------------------------------------- |
+| 全局层   | `~/.codex/AGENTS.md`       | 跨项目稳定习惯、危险命令策略、默认输出风格、工具查找规则 | 某个项目的业务术语、目录结构、接口规则 |
+| 项目层   | `<repo>/AGENTS.md`         | 当前仓库的任务规则、测试要求、目录约束、提交要求         | 只在某个子目录成立的细节               |
+| 深文档层 | `<repo>/docs/harness/*.md` | 详细架构、回归规则、trace 格式、CI 策略                  | 高频入口规则                           |
+| 导航层   | `<repo>/docs/ai/repo-map.md` 或同类代码地图 | 关键目录、模块职责、入口文件、禁改区和验证命令 | 逐函数源码解释、无法维护的临时路径 |
+
+判断标准很简单：
+
+- **换项目后仍然成立**，放全局层。
+- **只在当前仓库成立**，放项目层。
+- **用于帮助 Agent 找代码和理解模块边界**，放导航层。
+- **太长，不适合每次都塞进上下文**，放深文档层。
+
+## 2. 全局规则怎么写
+
+全局规则应该短、稳、工程化。建议控制在 50-150 行。
+
+推荐包含：
+
+1. 默认语言和输出风格。
+2. 工具查找策略，例如先 `Get-Command`，再用绝对路径。
+3. 危险命令策略，例如禁止 `git reset --hard`、禁止在未确认时删文件。
+4. 验证原则，例如“没有 fresh verification evidence 不宣布完成”。
+5. dirty workspace 处理原则。
+6. 跨项目通用的环境约束，例如 Windows、PowerShell、PATH、代理设置。
+
+不推荐包含：
+
+- 某个仓库的目录名。
+- 某个产品的业务规则。
+- 某个项目专属的 API key 名称。
+- 很长的逐步实现流程。
+- `task.json`、`progress.txt`、`tools/harness/codex-loop.ps1` 这类项目 workflow 细节。
+
+可复制模板：
+
+- 全局 AGENTS: `templates/config/global-AGENTS.md`
+
+## 2.1 如果现有全局 AGENTS 已经很重，怎么清理
+
+清理原则是：**先备份，再瘦身，不直接把所有内容删空。**
+
+推荐分三类处理：
+
+### 保留在全局的内容
+
+- 工具查找策略
+- Windows / PowerShell 通用规则
+- 危险命令和 dirty workspace 原则
+- 验证优先原则
+- 全局输出语言和通用协作风格
+
+### 迁出到项目层的内容
+
+- 两阶段 spec / 自动实现工作流
+- `task.json`、`progress.txt`、`tools/harness/codex-loop.ps1` 约定
+- BLOCKED 固定格式
+- 提交规则
+- 项目专用 skill 使用方式
+
+### 直接删除的内容
+
+- 只对某个项目成立的目录名和业务术语
+- 已经过时的命令入口
+- 与当前 Codex 行为不符的旧规则
+
+## 2.2 config.toml 为什么不和 AGENTS 一起重写
+
+`AGENTS.md` 和 `config.toml` 不是一类东西：
+
+- `AGENTS.md` 是行为规则和工作约定。
+- `config.toml` 是模型、sandbox、approval、MCP、PATH、trust 等运行配置。
+
+如果 `config.toml` 当前还能正常工作，不应该在重写全局规则时顺手一起改。正确做法是：
+
+1. 先单独清理全局 `AGENTS.md`。
+2. 再评估 `config.toml` 里哪些是运行配置、哪些是敏感信息、哪些该迁到环境变量。
+
+所以本次建议是：**重写全局 AGENTS，但不自动改 `config.toml`。**
+
+## 3. 项目规则怎么写
+
+项目 `AGENTS.md` 负责把 Codex 绑定到当前仓库的真实执行方式。
+
+最少应包含：
+
+- 任务入口文件，例如 `task.json`。
+- driver 命令，例如 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1`。
+- 实现前 testing truth source 要求，例如验收示例、追溯矩阵、验证矩阵。
+- 代码地图入口，例如 `docs/ai/repo-map.md`。
+- 测试要求。
+- 阻塞格式。
+- 提交要求。
+- 深文档索引。
+
+可复制模板：
+
+- 项目 AGENTS: `templates/runtime/AGENTS.md`
+
+## 4. 新项目接入步骤
+
+### Step 1: 确认项目是 Git 仓库
+
+```powershell
+git rev-parse --show-toplevel
+```
+
+如果失败，先初始化：
+
+```powershell
+git init
+```
+
+### Step 2: 复制最小组合
+
+至少复制以下文件到项目根目录：
+
+```text
+AGENTS.md
+task.json
+tools/harness/codex-loop.ps1
+tools/harness/doctor.ps1
+tools/harness/verify.ps1
+progress.txt
+```
+
+并额外复制默认运行策略文件：
+
+```text
+.codex/task-run-profile.json
+```
+
+如果这是新项目第一次接入，建议额外复制：
+
+```text
+tools/harness/templates/smoke-task.json
+```
+
+同时复制以下文档到 `docs/harness/`：
+
+```text
+harness-architecture.md
+new-project-usage.md
+regression-rules.md
+spec-to-ui-to-code-workflow.md
+task-session-strategy.md
+trace-format.md
+```
+
+并复制或初始化以下 `docs/testing/` 真相源：
+
+```text
+ACCEPTANCE_CRITERIA.md
+ACCEPTANCE_EXAMPLES.md
+TRACEABILITY_MATRIX.md
+TEST_STRATEGY.md
+TEST_DATA_MATRIX.md
+RISK_BASED_TEST_PLAN.md
+REGRESSION_PLAN.md
+EVIDENCE_PROTOCOL.md
+test-matrix.md
+verify-matrix.md
+failure-triage.md
+test-data-plan.md
+e2e-plan.md
+```
+
+建议同时初始化代码地图，作为大型项目的检索入口：
+
+```text
+docs/ai/repo-map.md
+```
+
+如果使用本包模板，可从 `templates/context/repo-map.md` 复制后按项目事实裁剪。根 `AGENTS.md` 只需要索引它，不要把整张代码地图复制进入口文件。
+
+通过 `tools/install/install-agent.ps1` 或 `tools/install/bootstrap-codex-harness.ps1` 安装时，模板会自动初始化：
+
+```text
+docs/ai/repo-map.md
+docs/ai/architecture-brief.md
+```
+
+安装后第一件事不是直接跑业务任务，而是把这两个文件从模板内容裁剪为目标项目事实。
+
+### Step 3: 配置项目 `.codex/config.toml`
+
+按需从模板复制：
+
+- `templates/config/codex-config.toml`
+- `templates/config/mcp-config.toml`
+
+项目配置只放项目特有内容。能在全局复用的项放到 `~/.codex/config.toml`。
+
+### Step 4: 初始化任务
+
+编辑 `task.json`：
+
+- 写入任务 id。
+- 写入依赖。
+- 写入 `test_command`。
+- 写入验收标准。
+- 为实现任务写入 `requirement_ids`、affected tests 和 owned paths。
+- 按需为单任务补 `context_files` 和 `execution` 覆盖策略。
+
+如果只是验证接入链路，不要直接写业务任务。先使用 `templates/runtime/tools/harness/templates/smoke-task.json` 做一轮 smoke test，确认 driver、trace、progress 和自动提交都正常，再切回真实 `task.json`。
+
+如果目标是正式业务任务，不要在 testing truth source 还缺失时就急着生成真实任务队列。至少先补齐：
+
+- `ACCEPTANCE_CRITERIA.md`
+- `ACCEPTANCE_EXAMPLES.md`
+- `TRACEABILITY_MATRIX.md`
+- `TEST_DATA_MATRIX.md`
+- `test-matrix.md`
+- `verify-matrix.md`
+
+如果目标仓库是刚 `git init` 的 brand new 仓库，bootstrap 和任务初始化完成后，先做一次基线提交，再启动 driver：
+
+```powershell
+git add --all
+git commit -m "chore: bootstrap codex harness baseline"
+```
+
+这样可以让 clean workspace 检查针对“真正的任务改动”生效，而不是把 bootstrap 入口文件本身当成脏工作区。
+
+### Step 5: 跑环境检查和验证
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/doctor.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+如果需要先做环境诊断，再额外运行模板里的：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\codex-harness-engineering\templates\config\tools/install/env-check.ps1
+```
+
+### Step 6: 首次运行 driver
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1
+全自动完成所有task
+ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/codex-loop.ps1 -RunUntilDone
+```
+
+## 5. 新环境初始化步骤
+
+这里指新电脑、新 runner、WSL、新 CI 环境。
+
+### Step 1: 安装基础工具
+
+至少需要：
+
+- Git
+- PowerShell 或对应 shell
+- Node.js
+- Codex CLI
+
+Windows 下建议先确认：
+
+```powershell
+Get-Command git
+Get-Command pwsh
+Get-Command node
+Get-Command codex
+```
+
+### Step 2: 准备全局配置目录
+
+Codex 全局配置通常放在：
+
+```text
+~/.codex/
+```
+
+建议至少准备：
+
+```text
+~/.codex/AGENTS.md
+~/.codex/config.toml
+```
+
+可复制模板：
+
+- `templates/config/global-AGENTS.md`
+- `templates/config/global-config.toml`
+
+### Step 3: 配置 API key 和环境变量
+
+禁止把真实密钥提交进仓库。推荐用：
+
+- 用户级环境变量
+- CI secret
+- `.env.local` 这类本地文件
+
+可复制模板：
+
+- `templates/config/env.example`
+
+### Step 4: 配置 PATH 和 trust
+
+如果是 Windows 环境，优先保证 `config.toml` 里的 shell environment policy 与本机实际工具路径一致。
+
+项目首次接入时，按需加入信任项目：
+
+```toml
+[projects.'E:\\path\\to\\repo']
+trust_level = "trusted"
+```
+
+### Step 5: 按环境选择执行模式
+
+| 环境       | 推荐模式                                      |
+| ---------- | --------------------------------------------- |
+| 本地开发   | `workspace-write` 或 `danger-full-access` |
+| CI 审查    | `workspace-write`                           |
+| 不可信输入 | `read-only` 或受限 `workspace-write`      |
+
+### Step 6: hooks 只做增强，不做主链路
+
+Codex hooks 当前可作为增强层启用。Windows 环境不要把 hooks 当主链路，优先使用 driver；如需结束前 continuation / feedback gate，可再参考：
+
+- `templates/hooks/hooks.json`
+- `templates/hooks/hook-stop-verify.ps1`
+
+## 6. 推荐的全局与项目拆分
+
+### 放在全局 `~/.codex/AGENTS.md`
+
+- 输出语言
+- 工具查找原则
+- 危险命令原则
+- 验证优先原则
+- dirty workspace 原则
+
+### 放在项目 `<repo>/AGENTS.md`
+
+- 当前项目任务入口
+- 当前项目代码地图入口
+- 当前项目测试命令
+- 当前项目目录边界
+- 当前项目阻塞格式
+- 当前项目提交要求
+
+### 放在项目 `docs/harness/*.md`
+
+- 回归规则
+- trace 格式
+- sandbox 策略
+- CI 工作流
+- 架构说明
+
+### 放在项目 `docs/ai/repo-map.md`
+
+- 关键目录和模块职责
+- 真实入口和 truth source
+- 生成代码、敏感目录和禁改区
+- 常用验证命令
+- 最近更新时间和维护责任
+
+## 7. 最常见错误
+
+1. 把项目规则写进全局 AGENTS，导致换仓库就错。
+2. 把所有长文档都塞进 AGENTS，导致上下文挤爆。
+3. 新环境只复制项目模板，不准备全局 config。
+4. 没有 `tools/harness/doctor.ps1` 和 `tools/harness/verify.ps1` 就直接跑 driver。
+5. 在 dirty workspace 中自动提交。
+6. 把 hooks 当成 Windows 主链路。
+7. 没补验收示例和追溯矩阵就创建正式 `task.json`。
+8. 把 Stage 17 当成第一次定义测试范围的地方。
+9. 没有代码地图就让 Agent 在大型仓库里全量搜索。
+
+## 8. 推荐复制路径
+
+| 目标         | 复制模板                                                                                                |
+| ------------ | ------------------------------------------------------------------------------------------------------- |
+| 全局规则     | `templates/config/global-AGENTS.md`                                                                          |
+| 全局配置     | `templates/config/global-config.toml`                                                                        |
+| 项目规则     | `templates/runtime/AGENTS.md`                                                                                 |
+| 项目任务流   | `templates/runtime/task.json`, `templates/runtime/codex-loop.ps1`, `templates/runtime/doctor.ps1`, `templates/runtime/verify.ps1` |
+| 项目文档     | `templates/docs/harness-architecture.md`, `templates/docs/new-project-usage.md`, `templates/docs/regression-rules.md`, `templates/docs/spec-to-ui-to-code-workflow.md`, `templates/docs/task-session-strategy.md`, `templates/docs/trace-format.md` |
+| 代码地图     | `templates/context/repo-map.md` |
+| 项目测试真相源 | `templates/testing/ACCEPTANCE_CRITERIA.md`, `templates/testing/ACCEPTANCE_EXAMPLES.md`, `templates/testing/TRACEABILITY_MATRIX.md`, `templates/testing/TEST_STRATEGY.md`, `templates/testing/TEST_DATA_MATRIX.md`, `templates/testing/RISK_BASED_TEST_PLAN.md`, `templates/testing/REGRESSION_PLAN.md`, `templates/testing/EVIDENCE_PROTOCOL.md`, `templates/testing/test-matrix.md`, `templates/testing/verify-matrix.md` |
+| 项目工具配置 | `templates/config/codex-config.toml`, `templates/config/mcp-config.toml`                                          |

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

@@ -0,0 +1,276 @@
+# Agent Implementation Flow
+
+本文从 当前安装包源码仓库的真实文件结构出发，说明当前 Codex Harness Agent 的整体实现流程。它不是新的流程规范，而是对现有安装、模板、driver、验证、知识归档和同步机制的结构化说明。
+
+## 1. 包的职责边界
+
+当前仓库本身就是一个可分发的 driver-first 能力包，核心职责是把目标项目初始化成可重复执行的 Codex Harness 项目。
+
+| 层级 | 主要文件 | 职责 |
+| --- | --- | --- |
+| 安装入口 | `tools/install/install-agent-here.ps1`、`tools/install/install-agent.ps1` | 把当前仓库的安装资产投影到目标项目，并触发 bootstrap |
+| 项目 runtime | `tools\harness\codex-loop.ps1`、`tools\harness\verify.ps1`、`tools\install\env-check.ps1`、`docs\harness\trace.schema.json` | 在目标项目根目录执行任务、验证、trace 和提交 |
+| 项目规则 | `AGENTS.md`、`rules/*.rules`、`rules/*.md` | `.rules` 约束命令执行策略；Markdown rules 约束主控会话、driver、子代理和项目规则边界 |
+| Codex 配置 | `.codex/config.toml`、`.codex/agents/*.toml`、`.codex/prompts/*.md` | 定义模型、角色、prompt、hook 和 task run profile |
+| Harness 文档 | `docs/harness/*.md` | 解释架构、任务策略、知识、回归、sandbox、trace 和新项目使用方式 |
+| 测试左移 | `docs/testing/*.md` | 在实现前固定验收、示例、追溯、测试数据、风险、证据和回归计划 |
+| 任务模板 | `tools\harness\templates\project-task-template.json`、`tools\harness\templates\smoke-task.json` | 提供正式任务队列和安装 smoke 的起点 |
+| 扩展能力 | `.agents/skills/`、`.agents/workflows/`、`.agents/.specify/` | 提供 SpecKit、skills、规则分发和工程辅助能力 |
+| 分发镜像 | `docs/codex-harness-engineering/templates/`、`templates/package-assets/` | 保存安装复制源和 package 自描述文档 |
+
+当前仓库默认使用 thin project 安装语义，并保留显式 legacy full 兼容入口。SpecKit 仍随包安装，但它只服务于 spec、plan 和 tasks 输入生成；方案确认后必须回到 `task.json + tools\harness\codex-loop.ps1`。
+
+## 2. 从包到项目的安装流程
+
+安装的实际链路如下：
+
+```text
+tools/install/install-agent-here.ps1
+  -> tools/install/install-agent.ps1 -ProjectRoot <target>
+  -> 复制 package-assets 到 <target>/.agents/
+  -> 调用 <target>/tools\install\bootstrap-codex-harness.ps1
+  -> bootstrap 把 runtime/docs/testing/.codex 模板落到项目根
+  -> 可选 InitSmoke / baseline commit
+```
+
+关键点：
+
+- `install-agent-here.ps1` 只负责推断目标项目根，并转调 `tools/install/install-agent.ps1`。
+- `tools/install/install-agent.ps1` 会拒绝在已有 `.agents/` 上静默覆盖，除非显式传入 `-Force`。
+- 如果目标目录不是 Git 仓库，只有传入 `-InitGitIfNeeded` 才会初始化 Git。
+- 安装前工作区不干净时，不会自动 baseline commit，避免把无关改动混入安装提交。
+- 自更新场景下，如果脚本从已安装的 `.agents/` 内运行，会先复制到临时目录，避免边复制边删除源目录。
+
+## 3. Bootstrap 落盘流程
+
+`tools\install\bootstrap-codex-harness.ps1` 是安装后真正把目标项目变成 Harness 项目的脚本。
+
+它负责落盘：
+
+- 根入口：`AGENTS.md`、`tools\harness\codex-loop.ps1`、`tools\harness\verify.ps1`、`tools\install\env-check.ps1`、`docs\harness\trace.schema.json`
+- Codex 配置：`.codex/config.toml`、`.codex/hooks.json`、`.codex/task-run-profile.json`、`.codex/agents/`、`.codex/prompts/`
+- 任务入口：`task.json`、`tools\harness\templates\smoke-task.json`、`tools\harness\templates\project-task-template.json`
+- Harness 文档：`docs/harness/*`
+- Testing truth sources：`docs/testing/*`
+- 服务拓扑 truth source：`.service-matrix/dependencies.yaml`，用于多服务、多仓库、契约或外部系统影响面。
+- Knowledge 初始索引：`docs/knowledge/knowledge-catalog.md`、`docs/knowledge/catalog.md`
+- hook 脚本：`tools/harness/hook-stop-verify.ps1`
+
+`task.json` 已存在时，bootstrap 不会盲目覆盖；它只确保 `runtime.driver` 存在。正式任务队列应从 `tools\harness\templates\project-task-template.json` 裁剪生成，而不是长期使用 smoke 或示例任务。
+
+## 4. 新项目实施流程
+
+目标项目安装后，推荐实施顺序是：
+
+```text
+bootstrap baseline
+  -> smoke task
+  -> product/design/context/testing truth sources
+  -> tools\harness\templates\project-task-template.json -> task.json
+  -> tools\harness\codex-loop.ps1 -RunUntilDone
+  -> release verify
+  -> archive knowledge
+```
+
+每一步的职责：
+
+| 阶段 | 输入 | 输出 | 通过条件 |
+| --- | --- | --- | --- |
+| Bootstrap | 当前包仓库和目标 Git 仓库 | 根 runtime、`.codex/`、`.agents/`、docs 模板 | `tools\harness\verify.ps1` 通过，工作区有清晰 baseline |
+| Smoke | `tools\harness\templates\smoke-task.json` | `progress.txt`、`traces/*.json`、一次 driver 提交 | driver、trace、progress、commit 链路可用 |
+| 需求收敛 | spec、PRD、访谈、现有代码 | `docs/product/`、`docs/context/`、`docs/design/` | P0/P1 需求有 Requirement IDs 和验收边界 |
+| 测试左移 | 需求、设计、风险 | `docs/testing/*` | 验收示例、追溯矩阵、测试数据、证据路径齐备 |
+| 任务队列 | `tools\harness\templates\project-task-template.json` | 真实 `task.json` | 无 smoke 占位，依赖、owned paths、test_command 可执行 |
+| 实现执行 | `task.json` 当前未完成任务 | 代码/文档改动、测试输出、trace、commit | Stage 1、test_command、Stage 2 全部通过 |
+| Release | 已完成用户故事 | affected tests、P0/P1 回归、视觉/契约证据 | fresh evidence 可追溯 |
+| Archive | trace、progress、review、failure triage | `docs/knowledge/*`、候选报告 | 可复用经验归档，不越权提升规则 |
+
+## 5. Driver 单任务执行流程
+
+`tools\harness\codex-loop.ps1` 每次只处理一个 `passes: false` 且依赖已满足的任务。核心流程是：
+
+```text
+读取 task.json
+  -> 选择下一个可执行任务
+  -> 合并 runtime / task-run-profile / task execution policy
+  -> 检查 truth sources
+  -> 创建 task_session_id 和 traces/<task-id>-<session>/
+  -> codex exec 实现阶段
+  -> Stage 1 需求/设计一致性审查
+  -> 运行 task.test_command
+  -> Stage 2 代码质量/测试风险审查
+  -> commit path ownership gate
+  -> task.passes=true
+  -> 写 progress.txt 和 trace
+  -> state compaction 归档旧任务和旧进度
+  -> git commit
+```
+
+失败时的处理：
+
+- truth source 缺失：不进入实现，写 `progress.txt` 和 failed trace。
+- Codex 实现失败或输出 BLOCKED：不跑后续 gate。
+- Stage 1 失败：先修需求、设计、状态或范围偏差。
+- `test_command` 失败：禁止标记 `passes=true`。
+- Stage 2 失败：先修代码质量、测试缺口或维护性风险。
+- commit path ownership gate 失败：说明改动超出 `owned_paths` 或 runtime allowlist，需要拆任务或修正任务边界。
+
+## 6. Task.json 的实现契约
+
+`task.json` 是 driver 的唯一任务状态源。正式任务至少应明确：
+
+- `id`、`description`、`priority`、`dependencies`
+- `passes: false`
+- `task_kind`、`phase`、`gate_profile`
+- `required_truth_sources`
+- `handoff_contract.scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`
+- `context_files`
+- `owned_paths`
+- `requirement_ids`
+- `test_command`
+- `acceptance`
+- `execution.mode: single`
+
+`tools\harness\templates\project-task-template.json` 目前按 full 链路组织为：
+
+```text
+INIT-001
+  -> ANALYSIS-001
+  -> DESIGN-001
+  -> PLAN-001
+  -> US1/US2/US3
+  -> RELEASE-001
+  -> ARCHIVE-001
+```
+
+模板只是交接骨架。真实项目必须替换占位的 feature slug、用户故事、Requirement IDs、owned paths、context files 和验证命令。
+
+## 6.1 状态文件压缩与归档
+
+`task.json` 和 `progress.txt` 不能无限增长。driver 模板内置 `runtime.state_compaction`，在成功任务写入 trace 后、`git add` 前自动执行：
+
+- `task.json` 只保留 active queue、未完成任务和最近 `completed_task_retention` 个已完成任务。
+- 旧的已完成任务体写入 `archive/tasks/<task-id>-<timestamp>.json`，完整索引写入 `archive/tasks/index.json`。
+- `task.json.runtime.state_archive.completed_task_ids` 保留归档完成任务 ID，使后续任务依赖仍能判定通过。
+- `progress.txt` 超过 `progress_max_lines` 后只保留最近窗口，旧内容轮转到 `progress/archive/progress-*.log`。
+- 完整审计链路由 `traces/`、`archive/tasks/`、`progress/archive/` 和 Git commit 共同承担。
+
+这条规则的目的不是隐藏历史，而是避免实现会话和子代理反复读取、改写大状态文件时误删任务、错改 `passes` 或把旧失败当成当前状态。AI 只能按需读取近期摘要和相关 trace；不得手工整理 `task.json` / `progress.txt` 来“优化上下文”。
+
+## 7. Prompt、角色与子代理
+
+执行时，driver 通过 `.codex/prompts/implement-one-task.md` 生成单任务实现 prompt，并把当前 task、truth source、owned paths、test command、知识读取要求注入给 Codex。
+
+子代理不是独立状态机，而是单任务实现阶段的受控加速能力：
+
+- 只读角色适合探索、研究、审查、失败归因和测试规划。
+- writer 角色适合明确授权的文档、前端、后端、测试和 harness 文件写入。
+- 实现阶段可以在当前 task `owned_paths` 内使用子代理并行推进，例如前后端分层、测试与实现分离、文档与代码分离、复杂调研与编码分离。
+- 企业级任务可以把 Stage 2 拆成设计一致性、复杂度、并发与状态、错误处理、安全、契约一致性、追溯性和辅助检查等只读 review 维度；这些维度只产出 findings，不产生第二套状态源。
+- 使用 writer 子代理前必须声明 ownership split：允许修改、禁止修改、验收输出和验证命令；多个 writer 不得同时写同一路径。
+- 主控会话需要更新 `task.json`、`AGENTS.md`、`.codex/*`、`.codex/rules/*`、`docs/harness/*` 或 prompt 时，应委派匹配 writer。
+- 子代理启动前必须读取 `AGENTS.md`、`docs/harness/task-session-strategy.md`、`.codex/rules/agents.md` 和相关 skill。
+
+这套设计的目标是提高实现速度，同时避免主控会话和子代理同时伪造 driver 状态。子代理不得修改 `task.json`、`progress.txt`、`traces/` 或 Git 状态；所有完成状态仍回到 `tools\harness\codex-loop.ps1` 的验证、trace 和 Git commit。
+
+## 8. 验证与证据链
+
+当前包把完成定义压到三类证据上：
+
+| 证据 | 文件或命令 | 用途 |
+| --- | --- | --- |
+| 命令证据 | `task.test_command`、`tools\harness\verify.ps1`、`git diff --check` | 判断当前任务是否真的通过 |
+| 过程证据 | `progress.txt`、`traces/*.json`、task session log | 记录失败阶段、命令退出码、review verdict 和文件改动 |
+| 需求证据 | `docs/testing/*`、Requirement IDs、acceptance examples | 证明实现范围和测试覆盖不是事后猜测 |
+
+`tools\harness\verify.ps1` 是包级 sanity check，默认至少运行 `git diff --check`，并检查 package freshness、hook 配置兼容性、PowerShell 语法和过时引用。具体项目的业务验证仍由每个 task 的 `test_command` 决定。
+
+## 8.1 Stop Hook 治理自迭代
+
+Stop hook 是每轮会话结束前的治理入口，不只检查是否还有 runnable task。当前模板链路是：
+
+```text
+Stop hook
+  -> tools/harness/hook-stop-verify.ps1
+  -> git diff --check
+  -> scripts/harness/harness-governance-check.ps1 -WriteExperience
+  -> task/progress/trace gate
+  -> continuation JSON 或 allow stop
+```
+
+`harness-governance-check.ps1` 负责检查：
+
+- `AGENTS.md`、`.codex/`、`docs/harness/`、`docs/codex-harness-engineering/` 是否有 merge marker。
+- `.codex/hooks.json` 是否引用缺失的 `tools/harness/hook-stop-verify.ps1`。
+- `.codex/rules/` 是否缺少官方 `*.rules` 执行策略。
+- `.codex/config.toml` 是否保留无实体 fallback。
+- 最新 trace 是否失败，失败原因应沉淀到哪个治理或测试文档。
+
+失败经验不会直接升级为硬规则。Stop hook 只把 failed trace 摘要去重写入 `docs/harness/governance-auto-repair.md`，并在 continuation JSON 中要求下一轮先读：
+
+- `AGENTS.md`
+- `docs/harness/governance-auto-repair.md`
+- `docs/harness/rule-governance.md`
+- `.codex/rules/agents.md`
+
+后续由 `harness-writer` 或 driver 修复对应路径。只有经过复验且可复用的经验，才允许提升到 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或测试文档。
+
+## 9. 知识闭环
+
+知识系统不是独立产品，而是 driver 执行后的归档层：
+
+```text
+实现任务读取 docs/knowledge/
+  -> 最终输出 knowledge_references / knowledge_outputs
+  -> trace 保留 knowledge_references / knowledge_outputs / archive_summary
+  -> ARCHIVE-001 更新 docs/knowledge/
+  -> knowledge lint 检查索引、冲突、重复、衰减
+  -> 可选 team knowledge sync 输出跨项目候选
+```
+
+约束：
+
+- `draft` 知识只能辅助判断，不作为强阻塞依据。
+- 单次任务经验不得直接升级为 `AGENTS.md` 规则。
+- `verified -> proven` 需要多任务/多项目证据或 maintainer 审批。
+- 团队知识库不可用时，只输出候选报告，不阻塞本地 driver。
+
+## 10. Agent 包自身同步流程
+
+当前仓库本身就是可推送的包根。同步由 `refresh-agent-package.ps1` 和 `.ai-sync.yml` 管理。
+
+典型同步方向：
+
+```text
+root runtime/docs/testing/.codex
+  -> docs/codex-harness-engineering/templates/runtime + docs/*
+  -> agent package-assets
+  -> .agents template mirrors
+```
+
+新增或修改内容时应先判断 canonical：
+
+- runtime 和 driver truth source：优先改 root。
+- human-facing package docs：优先改 `docs/codex-harness-engineering/*.md`。
+- active skills：优先改 `.agents/skills/<name>`，再同步到 package-assets。
+- template package assets：优先改 `docs/codex-harness-engineering/templates/...`，再同步 `.agents/...`。
+
+完成后至少运行：
+
+```powershell
+git diff --check
+powershell -NoProfile -ExecutionPolicy Bypass -Command "& .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot .\agent -CheckOnly -Surface @('docs','runtime','package-assets')"
+```
+
+如果改了 JSON 或 PowerShell，还要分别做 JSON parse 和 PowerShell parser 检查。
+
+## 11. 关键不变量
+
+- `task.json` 是任务状态源；不在聊天里伪造任务完成。
+- `tools\harness\codex-loop.ps1` 是自动执行入口；不要引入第二套 runtime 状态机。
+- driver 每次只处理一个可执行任务。
+- `execution.mode` 当前只支持 `single`。
+- 测试范围必须前置到 `docs/testing/*`，release 阶段只确认 fresh evidence 和回归。
+- 业务代码、文档、`task.json`、`progress.txt`、trace 和 commit 必须形成同一条证据链。
+- 归档沉淀知识，但不重新定义需求范围。
+- 当前仓库可以直接远程推送；如果没有远程，就只做本地提交。