.pouch/kits/ack/examples/project.example.md

notes-web Agent 协作协议（示例，项目覆盖层）

本项目基于 ack v0.6.0。 稳定规范引用 docs/ack/kit/core/，本文件只填项目差异。 覆盖层文件放在 docs/ack/project.md，不占用 AGENTS.md。 目录下只有一个软链接 kit/ + project.md + tasks.yaml。

项目概览

• 项目：notes-web
• 技术栈：TypeScript + React (Vite) + Go
• 运行命令：npm run dev（前端）、go run ./server（后端）
• Base URL：http://localhost:5173
• 任务板：docs/ack/tasks.yaml
• 覆盖层文件：docs/ack/project.md

稳定规范（引用，不重复）

• 角色 / 权限 / 状态机 / 完成定义：docs/ack/kit/core/roles-and-permissions.md
• 模型档位与升级规则：docs/ack/kit/core/model-routing.md
• 闭环流程（含手动模式、worktree 对齐）：docs/ack/kit/core/closed-loop.md
• 优化方法（验收信号、三轮策略）：docs/ack/kit/core/optimization-method.md
• 派发 prompt 模板：docs/ack/kit/core/prompt-templates.md
• Orca 编排命令：docs/ack/kit/core/orca-adapter.md

模型档位

角色	默认档位	本项目实际
Coordinator (PM)	强模型	claude-sonnet-5-thinking-high
Test	中低模型	默认（中低）
Developer	中低模型	默认（中低），架构任务临时升级

路径权限

路径	Coordinator	Test	Developer	说明
docs/spec/**	R/W	Read-only	Read-only	产品规格（PM 拥有）
tests/browser/**	Read-only	R/W	Read-only	浏览器回归用例（Test 拥有）
.qa-records/**	Read-only	R/W	Read-only	复测记录（gitignore）
web/**、server/**	Read-only	Read-only	R/W	应用源码
**/*_test.go、web/**/*.test.tsx	Read-only	Read-only	R/W	单元测试
config/*.example.*	Read-only	Read-only	R/W	可提交配置模板
.env、config/local.*	Read-only	Read-only	Read-only	本地私有配置
tasks.yaml	R/W	Read-only	Read-only	只有 Coordinator 写

命令

Developer 白盒验证：

npm run build
go test ./...
npm run dev   # 本地起前端

Test 黑盒复测：

curl -s http://localhost:5173/api/health
curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
# 浏览器回归：tests/browser/cases/*.md

任务板校验：

python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml

硬规则（其余见 kit/core/）

• 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
• 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 kit/core/model-routing.md）。
• worker_done 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 verified。
• 只有 Coordinator 写 tasks.yaml；Test 与 Developer 只读。
• 每个任务最多派发 3 轮，仍不过标记 leftover 并继续。
• 不提交或推送，除非用户明确要求。