# Governance Auto Repair

本文件记录 Stop hook 治理检查在会话结束时发现的 Harness 漂移、失败 trace 和可复用修复经验。它是自动化经验暂存区，不是硬规则入口。

## 写入来源

Stop hook 会调用：

```powershell
scripts/harness/harness-governance-check.ps1 -WriteExperience
```

该脚本只做两类写入：

- 为新的 failed trace 追加一条去重后的 `Stop Hook Experience`。
- 创建本文件的基础结构。
- 对受影响目录的子 `AGENTS.md` 刷新自动维护区块，补齐 changed paths、候选入口和验证命令。

它不会直接改 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或 task queue。
它也不会重写整份子 `AGENTS.md`；自动化只维护受控区块，手写目录规则必须放在区块外。

## 经验提升规则

每条自动记录的经验都必须经过复验后再提升：

| 情况 | 提升目标 |
| --- | --- |
| 重复出现的规则分层、fallback、autoload、hook 漂移 | `docs/harness/rule-governance.md` 或 `.codex/rules/*.md` |
| 命令权限、危险操作、sandbox 误用 | `.codex/rules/*.rules` 或 `docs/harness/sandbox-policy.md` |
| Stage 1 产品/设计/计划不一致 | 对应 product/design/plan truth source |
| Stage 2 代码质量、测试缺口、回归风险 | `docs/testing/failure-triage.md` 或测试矩阵 |
| driver、trace、progress、commit gate 闭环缺口 | `docs/harness/task-session-strategy.md` 或 `trace-format.md` |

## 失败经验分类

Stop hook 写入 failed trace 摘要时，应尽量归入下面的分类，方便后续判断是补 truth source、补 hook、补子代理边界，还是只保留为一次性 trace。

| 分类 | 典型信号 | 优先处理 |
| --- | --- | --- |
| `semantic_constraint_lost` | 字段口径、单位、禁止修改范围、兼容性约束只出现在聊天里，后续实现忘记 | 补 product/context/testing truth source 或 task 语义约束包 |
| `truth_source_missing` | task 声明了需求、架构、测试或数据证据，但对应文件不存在或内容不足 | BLOCKED，先补 truth source |
| `hook_gap` | 问题可被确定性检查发现，但当前 hook / `.rules` / verify 没拦住 | 补 hook、`.rules` 或 `tools/harness/verify.ps1` 检查 |
| `subagent_context_overflow` | 主会话读取了大量日志、依赖树、数据样本、完整 Skill 流程，导致上下文污染 | 改为子代理读取并只返回摘要 |
| `state_file_bloat` | `task.json` / `progress.txt` 过大、格式漂移或被 AI 手工整理 | 交给 `runtime.state_compaction` 或治理修复，不允许手工重排 |
| `review_gate_gap` | Stage 1 / Stage 2 未覆盖的产品、设计、测试可信度或维护性问题 | 补 review prompt、测试矩阵或 qa contract |
| `domain_rule_candidate` | 多次出现同类领域规范违规，但还不是通用项目硬规则 | 先沉淀到 domain docs / skill，再决定是否提升 |
| `service_topology_gap` | 跨服务、契约、IDL、schema、上下游或外部系统影响面靠 AI 搜索和猜测 | 补 `.service-matrix/dependencies.yaml` 或等价拓扑 truth source |

提升前必须回答：

- 这是一次性任务问题，还是会跨任务重复？
- 能否用 deterministic check 发现？
- 是否需要进入 instruction chain，还是应下沉到 docs / skill / hook / `.rules`？
- 是否有复验证据证明修复后不再复现？

## 修复流程

1. Stop hook 发现治理失败或 failed trace。
2. `harness-governance-check.ps1` 输出 JSON findings，并把 failed trace 摘要写入本文件。
3. Stop hook 返回 continuation JSON，阻断停止。
4. 下一轮先读 `AGENTS.md`、本文件、`docs/harness/rule-governance.md`、`.codex/rules/agents.md`。
5. 由 `harness-writer` 或 driver 修复对应路径。
6. 运行 `tools/harness/verify.ps1` 和直接相关验证。
7. 只有复验成立且可复用时，才把经验提升到对应正式文档。

## Self-Refinement 提升路径

Stop hook、review、用户纠正或 failed trace 发现的问题，不应只停留在本轮对话。按下面路径处理：

| 信号 | 首选落点 | 何时升级 |
| --- | --- | --- |
| 一次性任务事实 | 当前 trace、`progress.txt`、任务相关 product / testing 文档 | 不升级 |
| 可复用项目经验 | `docs/knowledge/experience/` 或 `docs/knowledge/guidelines/` | 复验后进入 `ARCHIVE-001` |
| 反复出现的领域口径 | domain docs、service matrix、project skill | 多次任务引用且有证据 |
| 可机械化检查 | hook、`.rules`、`tools/harness/verify.ps1`、CI、lint、contract test | 已有确定性失败样本和通过样本 |
| 每次会话都必须遵守的硬规则 | `AGENTS.md` 或子目录 `AGENTS.md` | proven 级别或 maintainer 明确要求 |

提升前必须保留原始证据路径、复验命令和失败样本。不能把单次用户偏好、一次性修复或未复验猜测直接提升为全局规则。

## 自动记录区

新的 Stop hook 经验会追加在此节之后。
