# Harness 架构

## 目标

Harness 的目标是把 Codex 的执行过程固定成可重复、可验证、可追踪、可沉淀知识的工程闭环。

## 核心链路

```text
task.json
  -> tools/harness/codex-loop.ps1
  -> codex exec
  -> verify / lint / build / test
  -> progress.txt + traces/*.json
  -> docs/knowledge/ 引用与归档
  -> task.json passes=true
  -> git commit
```

## 分层

- 规则层：`AGENTS.md`
- 任务层：`task.json`
- 执行层：`tools/harness/codex-loop.ps1`
- 配置层：`.codex/task-run-profile.json`
- 证据层：`progress.txt`、`traces/`
- 验证层：`tools/harness/verify.ps1` 与任务内 `test_command`
- 知识层：`docs/knowledge/knowledge-catalog.md`、分类索引和知识条目
- 治理层：`docs/harness/rule-governance.md`、`docs/harness/knowledge-architecture.md`、`docs/harness/knowledge-import.md`、`docs/harness/knowledge-lint.md`、`docs/harness/team-knowledge-sync.md`
- 拓扑层：`.service-matrix/dependencies.yaml` 与 `docs/harness/service-dependency-matrix.md`，仅在多服务、多仓库、契约或外部系统项目启用。

## 原则

- 任何完成声明都必须有验证证据。
- 任何任务推进都必须回到可验证的 `task.json`、`progress.txt` 或 `traces/` 证据链上。
- 任何复用过的项目经验都应在 trace 中留下 `knowledge_references`，避免知识只停留在对话上下文。
- 任何可复用的新经验都应在归档任务中沉淀到 `docs/knowledge/`，初始成熟度默认是 `draft`。
- 任何会影响服务拓扑、公开契约、上游 / 下游调用、IDL、schema 或外部系统的任务，都必须先能从 `.service-matrix/dependencies.yaml` 或等价 truth source 找到影响面；找不到时先 BLOCKED。
- 既有项目接入时，知识冷启动只生成 draft 条目；成熟度提升必须来自后续引用和验证证据。
- 知识库需要定期 lint，检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目。
- 团队知识库是可选上层能力，只同步 verified/proven 级别的跨项目候选；外部知识库不可用时不应阻塞本地 driver。
- `progress.txt`、`traces/` 和 Git 状态由 runtime 脚本落盘；其他需要新增或修改的仓库内容必须委派给匹配的 writer 子代理，主控会话自身不直接写文件。
- 默认只在当前 Git 工作区内执行，不创建额外执行目录。

## 任务控制面

Harness 不要求所有任务都走相同重量。判断标准是影响面和复用价值：

| 类型 | 适用场景 | 最小要求 |
| --- | --- | --- |
| 轻量任务 | 单文件、小修、验证明确、无跨模块影响 | `task.json` 中明确 scope、owned paths、test_command 和验收；允许 `gate_profile: lightweight` |
| 标准任务 | 有真实交付、测试、文档或评审要求 | 完整 plan、truth source、qa_contract、trace 和 commit |
| 企业级任务 | 多服务、多仓库、契约、数据迁移、权限、外部系统 | 额外启用服务依赖矩阵、契约 gate、失败/回滚验证和多维 review |

轻量任务可以少写文档，但不能绕过验证、trace、owned paths 和完成证据。

## 多维 Review

Stage 2 默认可以由单个 reviewer 执行；当任务满足企业级任务条件时，应拆成多个只读审查维度并聚合：

| 维度 | 检查重点 |
| --- | --- |
| 设计一致性 | 实现是否符合 spec、design、architecture truth source |
| 复杂度 | 是否过度抽象、职责混杂、文件过大或难以维护 |
| 并发与状态 | 锁、幂等、竞态、异步边界、前端状态源是否正确 |
| 错误处理 | 失败路径、重试、回滚、用户反馈、日志和恢复策略 |
| 安全 | 权限、输入、secrets、外部调用、危险命令和数据泄露 |
| 契约一致性 | API / IDL / schema / event / generated code 是否同步 |
| 追溯性 | Requirement ID、测试用例、证据和改动路径是否可追踪 |
| 辅助检查 | lint、类型、格式、构建、脚本、hook 和 runtime 漂移 |

多维 review 是可选强化，不是第二套状态机。所有结论仍回到当前 task 的 trace、review gate 和修复队列。

## 外层控制台集成

- 如果项目接入外层任务控制台、看板或自动化编排系统，Harness 的完成状态仍以 `tools/harness/codex-loop.ps1`、`test_command`、review gate、trace 和 commit gate 为准。
- 具体集成产品、部署方式和权限边界，应在当前项目自己的集成文档中说明。
