# Harness Mode Matrix

## 1. Summary

当前安装体系同时保留 `user`、`project`、`vendor`、`full` 四种模式，但它们暴露的是不同层能力，不应混成一个概念：

| 模式 | 主要定位 |
| --- | --- |
| `user` | 用户级共享能力层，更适合全局技能、规则和类似 `/goal` 的外层长期目标控制习惯 |
| `project` | 项目根 runtime + truth source，适合 driver-first、stop hook、trace、verify 闭环 |
| `vendor` | 离线 / 隔离环境下的完整 package 镜像复制 |
| `full` | `project` runtime + 完整 `.agents/` package assets，适合长期驻留的完整 Harness 项目 |

其中：

- **外层目标控制** 更适合放在 `user` 层使用。
- **仓库级持续执行与治理** 更适合放在 `project` / `full` 层使用。

| 字段 | user | project | vendor | full |
| --- | --- | --- | --- | --- |
| 适用场景 | 全局规则、共享技能、外层长期目标控制 | 目标项目最小 driver-first 闭环 | 离线 / 隔离复制完整包 | 长期业务项目的完整 Harness 工程 |
| 状态源 | 用户环境 | `task.json` | 以复制的 package 为主 | `task.json` |
| 执行入口 | 用户级 Codex / CLI / App | `tools/harness/codex-loop.ps1` | 按目标环境决定 | `tools/harness/codex-loop.ps1` |
| 提交责任 | 不负责项目提交 | driver | 不默认承担项目提交 | driver |
| trace 责任 | 无项目级 trace 保证 | driver 写 `traces/*.json` | 取决于目标环境 | driver 写 `traces/*.json` |
| 验证入口 | 用户自定义 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` | 取决于目标环境 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` |
| 持续运行定位 | 可承载 `/goal` 这类外层长期目标控制 | stop hook + driver continuation | 取决于复制后的目标环境 | 同时具备 `project` 执行面和 `.agents/` 能力包 |
| 禁区 | 不应假装拥有项目级 gate | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 | 不应误当作项目执行协议本身 | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 |

## 2. Installation Outputs

| 模式 | 必备安装产物 |
| --- | --- |
| user | 共享 package assets、全局规则/技能入口，不要求目标项目先具备完整 runtime |
| project | `AGENTS.md`、`tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`task.json`、`.codex/*`、`docs/harness/*`、`docs/testing/*`、`docs/ai/*` |
| vendor | `.agents/` 下的完整 package 镜像、模板和 skills/workflows |
| full | `project` runtime 产物 + `.agents/workflows/*`、`.agents/.specify/*`、`.agents/skills/*` 等完整能力包 |

## 3. Ownership Rules

| 字段 | project / full |
| --- | --- |
| 当前任务边界 | `task.json` 当前 task 的 `owned_paths`、`dependencies`、`test_command` |
| 提交者 | `tools/harness/codex-loop.ps1` 或任务收尾流程 |
| 失败记录 | `progress.txt` + `traces/*.json` |
| 允许的运行产物 | `task.json`、`progress.txt`、`traces/`、显式 `non_blocking_dirty_paths` |

`user` 和 `vendor` 模式本身不应宣称拥有上述项目级 ownership gate；它们更多提供共享控制面或分发面。

## 4. SpecKit Usage

SpecKit 仍用于生成或完善 `spec.md`、`plan.md`、testing truth sources 和任务拆解输入。方案确认后，应把结果转成 `tools/harness/templates/project-task-template.json` / `task.json`，再交给 `tools/harness/codex-loop.ps1` 执行。

如果未来要把 Codex `/goal` 纳入长期运行体验，推荐分层是：

- `user` 层承载 `/goal` 这类长期目标控制习惯
- `project` / `full` 层承载 driver-first 的仓库执行协议
