# Harness Rule Governance

本文定义规则如何进入 `AGENTS.md`、深文档、prompt、task template 和自动化检查。目标是控制指令预算，同时让关键约束可执行、可验证、可演进。

## 落地结论

规则治理的目标不是把长文档原样塞进入口文件，而是约束规则系统的形态：

- `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/*` 等更合适的层级。官方自动加载的 `.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 |

## 自主续跑策略

默认采用“自动补齐 + 留痕 + 继续”的策略，而不是把歧义直接升级成真人阻塞。

- 语义、追溯、测试、镜像或运行时口径出现缺口时，先按 canonical truth source、增量补齐和最小闭环原则自动修复。
- 自动拍板后的理由、取舍和回退方案写入 `docs/ai/AUTO_DECISIONS.md`，不要只留在聊天上下文里。
- 不影响当前交付真假或安全边界的问题，写入 `docs/harness/governance-auto-repair.md` 作为治理债务，不阻断 driver 继续推进。
- `failed trace`、`CURRENT_TASK` 滞后、镜像漂移、缺少 outer completed trace 这类 post-run / governance residue，默认归类为 `auto_repair` 或 `soft_debt`，不是 human blocker。
- 本地命令、服务、数据库、缓存或其他依赖不可用时，优先用 Docker 或等价本地 bootstrap 恢复，再继续验证；不要先升级成人工阻塞。
- 只有会导致越权、破坏性写入、真实安全泄露或无法通过非破坏手段恢复的情况，才允许保留为硬阻断。

### 安装/修复入口真实性

当失败原因是 `doctor`、使用指南或 stop gate 给出了仓库里并不存在的修复命令时，按下面的层级修复：

- 先修 `tools/harness/doctor.ps1`、对应 `docs/harness/*` 文案和真实安装脚本的入口解析，不要先补一个名字看起来合理但仓库中没有的 wrapper。
- `FixCommand`、README、使用指南和治理文档只能引用当前 checkout 实际存在且已验证可运行的入口。
- 如果仓库当前没有独立修复脚本，输出 `manual review` 或明确人工步骤；不要伪造 `install-agent.ps1`、`init-project.ps1`、`install-user.ps1` 之类的命令占位。
- 如果真实入口依赖 thin install 的 `packageRoot` 或其他 runtime 元数据，先让真实入口能从 `.codex-harness/state/config.json` 等稳定真源自解析，再把它写进 `FixCommand`。

这类问题优先下沉到 `doctor`、bootstrap/runtime 脚本和 `docs/harness/*`，而不是升级到根 `AGENTS.md`；因为它属于可验证的安装面一致性，不是所有会话都必须记忆的常驻规则。

## 变更流程

1. 先确认触发来源：trace、review finding、失败日志、用户明确要求或文档分析。
2. 选择最小生效层级，不把深文档内容直接搬进 `AGENTS.md`。
3. 如果架构设计、实施计划或任务队列已经把某个目录的职责、边界、入口和验证方式分清，而该目录后续会被实现任务写入，必须在进入实现前把这些事实固化到对应子目录 `AGENTS.md`；不要在项目初始化时盲写，也不要等代码写完后再补。
4. 如果改动影响模板或镜像，按 `harness-surface-sync` 同步 canonical source 和 mirrors。
5. 运行最小验证：文档至少 `git diff --check`，JSON 需要 `ConvertFrom-Json`，PowerShell 需要 parser 检查。
6. 提交前确认没有把 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` 索引补链接 |
