# <项目名> Agent 协作协议（项目覆盖层）

> 本项目基于 ACK Skill v<ack_version>。通用规范由 `/ack` 从 Skill 自身的
> `references/` 读取；本文件只保存项目差异。
>
> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
> 若希望 Agent 自动加载，可由项目维护者自行在 `AGENTS.md` 中引用本文件；ACK
> 不会自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
> `docs/ack/` 只保存本项目的 `project.md`、`tasks.yaml`、`knowledge.yaml` 与默认关闭的
> `delivery.yaml`，
> 不复制或链接 Skill。

## 项目概览

- 项目：`<project_name>`
- 技术栈：`<tech_stack>`
- 运行命令：`<run_command>`
- Base URL：`<base_url>`
- 任务板：`docs/ack/tasks.yaml`
- 项目知识：`docs/ack/knowledge.yaml`
- 交付契约：`docs/ack/delivery.yaml`（默认关闭）
- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）

## 通用规范（由 ACK Skill 按需读取）

- 开始需求：`references/kickoff.md`
- 角色、权限、状态机与完成定义：`references/roles-and-permissions.md`
- 模型档位与升级规则：`references/model-routing.md`
- 闭环流程与 worktree 对齐：`references/closed-loop.md`
- 验收信号与三轮策略：`references/optimization-method.md`
- 派发 prompt 模板：`references/prompt-templates.md`
- Orca 编排命令（可选）：`references/orca-adapter.md`
- 验证后交付与配置维护（可选）：`references/delivery.md`
- 一次性源码/DEB/镜像发布路由（可选）：`references/delivery-routing.md`

## Worker 路由

机器可校验的模型、reasoning effort、权限模式、默认 profile、允许 worktree 和启动
receipt 全部以 `docs/ack/tasks.yaml` 的 `project.orchestration` 与顶层
`workerReceipts` 为准。本文件不保存可执行 worker 命令。

默认 profile：

| 角色 | profile ID | 档位 |
|------|------------|------|
| Developer | `codex-dev-standard` | standard |
| Test | `codex-test-standard` | standard |
| Operator | `codex-operator-standard` | standard（模型/effort 与 Test 相同） |
| Developer 升级 | `codex-dev-strong` | strong |

项目如改用 Cursor，应修改结构化 profile、allowlist 和 defaults，再运行任务板
校验；不能在这里粘贴 `orca --command`、Agent CLI 参数或自由 shell。
每次自动派发必须先审阅 launcher plan，再把其中的 `launchFingerprint` 作为
`--expected-launch-fingerprint` 启动 fresh worker。v0.10 的 `receiptHash` 只作
审计 checksum，不授权自动复用旧终端。

## 路径权限（项目覆盖层，必须填实际路径）

| 路径 | Coordinator | Test | Developer | 说明 |
|------|:-----------:|:----:|:---------:|------|
| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
| `<local_config_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
| `knowledge.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写；Developer/Test 通过回报提名或验证 |
| `delivery.yaml` | 仅显式维护时 R/W | Read-only | Read-only | 项目交付能力，不是执行授权 |

## 命令（项目覆盖层）

Developer 白盒验证：

```bash
<unit_test_command>
<build_command>
<local_run_command>
```

Test 黑盒复测：

```bash
<preflight_command>
<api_smoke_command>
<browser_regression_command>
```

知识项的 `verification.ref` 只能引用 `knowledge.yaml.verificationRegistry` 中已
审查的检查入口。Registry 只保存仓库内相对 path 和结构化 args，不保存或执行自由
shell 命令；新项目没有知识时保持空对象。Developer/Test 只能把 registry ID 交给
Skill 的 `scripts/run_verification.py` 执行，不直接拼接 path/args。检查脚本从项目
根 cwd 或 `ACK_PROJECT_ROOT` 定位资源，不能依赖自身文件路径。
`ACK_PROJECT_ROOT` 是 runner 固定的根目录 fd 路径；仅用于日志的原始路径位于
`ACK_PROJECT_ROOT_DISPLAY`。

项目状态校验由 `/ack` 使用 Skill 自带的 `scripts/validate_tasks.py`、
`scripts/validate_knowledge.py` 和 `scripts/validate_delivery.py` 执行。
构建/发布/部署的机器入口以 `delivery.yaml` 为准；本文件不维护第二套交付命令。

## 硬规则（其余见 references/）

- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
- 一次性交付 Operator 不进入三角色闭环；它使用 Test 同档模型执行被路由的低层 Skill，
  只回传证据，不写 ACK 状态文件。
- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
- 自动 worker 只能由 ACK 的 `scripts/launch_worker.py` 按结构化 profile 启动；
  禁止直接拼 `orca terminal create --command`，禁止 `command`、`extraArgs`、`env`
  等第二配置面。
- v0.10 自动 launcher 只支持 `read-only` 和 `workspace-write`。full-access、
  bypass、YOLO/force 与关闭 sandbox 均 fail closed；需要可信平台审批通道后再开放。
- v0.10 不自动复用持久化 receipt 指向的旧终端；每次自动派发都重新 plan/launch。
- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Developer 与 Test 都只读，
  通过消息回报。
- Coordinator 只派发按 scope 命中并显式写入 `knowledgeRefs` 的 `active` 知识；
  `candidate` 不派发，知识库不全量注入。
- Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
  `knowledgeChecks`。关键约束应下沉为测试、lint、CI 或正式规范。
- ACK 不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
- `delivery.yaml` 默认关闭，只描述能力，不自动授权提交、推送、发布或部署；交付仅在
  任务 `verified` 且本次 profile/目标/停止点得到确认后运行。
- 默认交付 profile 最多到 `review_ready`；stable 发布或 production 部署必须有
  approval 步骤并再次获得明确批准。配置变更只影响下一次 run。
- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
- 不提交、推送、发布或部署，除非用户确认的 ACK 任务或 delivery profile 明确包含。