02-计划开发与协作

todo-api/
├── src/routes/todos.ts
├── src/services/todo-service.ts
├── src/repositories/todo-repository.ts
├── src/models/todo.ts
├── test/
├── package.json
└── AGENTS.md

pwd
git status --short --branch
git branch --show-current
git log -1 --oneline
codex --version

现在只做只读开工检查，不要修改、安装、联网、写数据库、提交或推送。
确认仓库根目录、当前分支、HEAD、工作区未提交修改、README、AGENTS.md、运行命令和测试命令。
读取 todos 的路由、服务、仓储、模型、数据库适配器和现有测试。
输出：项目结构、已有 GET/PATCH 行为、错误格式、可复用测试约定、候选文件、风险和无法确认的假设。
每条结论都带文件路径和符号；完成后停止等待指令。

基线：main @ 8f31c2a
运行：npm run dev；测试：npm test
已有 GET /todos 返回数组，错误为 { error: { code, message } }
候选文件：src/routes/todos.ts、src/services/todo-service.ts、test/todos.test.ts
风险：分页默认值和数据库稳定排序尚未确认

进入计划模式，只读，不要改文件。
为 TODO API v2 制定实施计划：
- GET /todos 支持 page、page_size、completed、tag；
- 响应保留已有字段，并增加 page、page_size、total、items；
- PATCH /todos/{id} 支持 title、tag、completed 的部分更新；
- 非法参数、空标题、未知 ID 继续遵循现有错误格式；
- 不换数据库、不改认证、不改前端、不引入第三方依赖。
输出：
1. 当前与目标行为的差异；
2. 参数、响应和错误契约草案；
3. 按依赖拆分的任务清单；
4. 每项的文件范围、输出和验证命令；
5. 可并行与必须串行的任务；
6. 风险、需人工决定的事项和回滚方案；
7. 阶段性交付建议。等待批准，不要实现。

请把后续动作标记为 read、write、network、external 或 irreversible。
read 可以执行；write 只限批准文件；network、external、irreversible 必须再次请求批准。
列出所有会改变公共 API、数据库、锁文件、分支或远端的动作，等待“批准阶段 1”。

作为只读探索员，检查 todos API 的真实执行路径。
读取路由、服务、仓储、模型、数据库适配器和测试；不要修改文件或写数据。
输出不超过 30 行：GET/PATCH 调用链、分页和筛选插入点、参数校验和错误约定、文件与符号、兼容风险。
每条结论引用文件路径和符号名，只回摘要，不贴大段源码。

根据探索报告起草 TODO API v2 契约，不修改业务代码。
明确 page、page_size、completed、tag 的类型、默认值、上限、组合规则和错误。
明确 PATCH 的部分更新、空字符串、未知字段和未知 ID 语义。
保留现有字段和错误 envelope；若无法兼容，列出冲突并停止。
输出契约表及 5 个请求/响应示例，供实现和测试共同使用。

实现已批准的 TODO API v2 数据层契约。
只修改 src/models/todo.ts、src/repositories/todo-repository.ts 及直接数据层测试。
加入分页、completed/tag 筛选和 PATCH 部分更新；不要改路由、认证、迁移、依赖或错误格式。
先检查接口，再小步实现；完成后运行数据层测试并报告文件、命令、结果和未解决问题。
若需要新增依赖、迁移或公共类型变化，先停止并说明原因。

数据层已按下列契约验收：[粘贴契约]
只修改 src/routes/todos.ts、src/services/todo-service.ts 和 test/ 中直接相关文件。
实现 GET 分页筛选和 PATCH 部分更新，保持认证、错误 envelope、状态码和旧客户端行为。
覆盖正常路径、默认值、非法 page/page_size、completed 非法值、tag 无结果、空标题、未知字段、未知 ID 和旧请求。
先展示计划再修改；完成后运行相关测试、完整测试、lint、类型检查和构建。
不要提交、推送或访问外部服务。

git status --short
git rev-parse HEAD
git diff --check
npm test

只做基线验证，运行已有测试和必要静态检查，不改文件。
输出命令、退出码、失败测试、环境假设和基线提交。
失败统一标记为 BASELINE_FAILURE，不要顺手修复。

contract：已批准的参数、响应、错误和兼容规则
files：每项任务的允许文件集合
dependencies：P0 -> P1 -> P2/P3 -> P4 -> P5
risks：响应形状、分页默认值、数据库排序、性能
approval_needed：是否允许数据层类型和查询变更

这是数据层 Worktree，只负责阶段 2。
先运行 git worktree list、git status --short、git branch --show-current，确认没有误入主工作区。
如果是 detached HEAD，报告当前提交，不要自行建分支。
只修改批准的模型、仓储和数据层测试文件；每个小步运行相关测试。
结束时输出 diff --stat、测试结果、未解决问题和回滚点。

批准阶段 2 在 todo-api-data Worktree 修改：
- src/models/todo.ts
- src/repositories/todo-repository.ts
- test/repository/todo-repository.test.ts
允许运行既有本地测试和类型检查。
禁止安装依赖、联网、读取密钥、写共享数据库、修改其他文件、提交和推送。
超出范围立即暂停。

git diff --stat：仅 3 个批准文件
相关测试：12 passed
未验证：真实数据量下的查询性能
回滚点：commit 1ab42ef 或 phase-2.patch

对照契约逐项验收；查看完整 diff；确认没有路由、认证、依赖、迁移或敏感文件变更。
运行数据层测试和类型检查。每项输出证据；不能证明的标记 UNVERIFIED，失败标记 BLOCKED。

批准阶段 3。先确认数据层提交哈希和当前 Worktree 无未提交修改。
基于已批准契约实现路由、服务和接口测试，只修改批准文件。
遇到契约与现有代码冲突先停下报告。
测试断言真实响应体、状态码、错误格式和用户行为，不只断言没有抛异常。
运行相关测试、完整测试、lint、类型检查和构建；不要提交、推送或访问生产。

并行派出 3 个只读子代理审查当前 diff：
correctness：检查分页、筛选、PATCH 和错误处理；
compatibility：检查旧客户端、响应字段、状态码和数据库行为；
tests：检查边界覆盖、断言质量和回归缺口。
三个代理都只读、不改文件、不提交、不联网；等全部返回后按阻塞、应修、建议汇总。
每条发现带文件、符号、复现条件、证据和修复建议；不要贴大段源码。

阻塞：src/routes/todos.ts:parsePage，page_size=abc 被当成默认值。
应修：test/todos.test.ts 未断言空结果的 total。
建议：可抽出参数对象，但不属于本次范围。

name = "api_reviewer"
description = "Read-only reviewer for TODO API correctness and compatibility."
sandbox_mode = "read-only"
model_reasoning_effort = "medium"
developer_instructions = """
只读审查 API 代码和测试，关注行为、边界、兼容性和安全性。
不要修改、提交、联网；输出带文件和符号的精炼发现。
"""

出现合并冲突。先不要编辑冲突文件。
读取双方 diff、共同祖先和已批准契约，说明冲突文件/符号、两边行为、必需与额外改动、最小合并方案和必须运行的测试。
等待批准后，在集成 Worktree 解决；不要自动选择 ours/theirs。

git worktree list
git status --short
git branch --show-current

fatal: 'feature/todo-api-v2' is already used by worktree at '...'

如果缺少 .env、数据库连接或依赖，不要猜值、不要读取其他工作区的密钥、不要连接生产。
列出缺失项和安全的测试环境方案，等待批准。

git status --short --branch
git worktree list
git log --oneline --decorate --all --max-count=20

先只读检查阶段 2/3 提交哈希、文件范围、未提交修改、Worktree 分支占用和审查阻塞项。
输出集成顺序和冲突风险，不要 merge 或 rebase。

批准在集成 Worktree 合并阶段 2 和阶段 3。
合并前后运行 git status；冲突立即停止，不自动选 ours/theirs。
合并后运行 npm test、npm run lint、npm run typecheck、npm run build。

请按 D1-D7 逐项验收，不要只说“完成”。每项提供证据；不能证明标记 UNVERIFIED，失败标记 BLOCKED。
检查未批准文件、敏感值、外部调用、数据库变更、临时产物和公共 API 兼容性。
最后给出交付、返工或回滚建议；不要 commit、push、merge 或 release。

阶段：2 数据层
完成：分页、completed/tag 筛选、PATCH 部分更新
变更：3 个批准文件
验证：npm test -- repository，12 passed
未完成：真实数据量性能未验证
风险：page_size 上限仍需确认
回滚点：1ab42ef / phase-2.patch
下一步：阶段 3，等待批准

进入交付前审查，只读。检查当前 diff、提交历史、测试输出和契约：
范围是否准确，公共 API 是否兼容，测试是否验证用户行为，是否有敏感文件或构建产物，审查意见是否关闭，回滚点是否明确。
输出最终报告和 BLOCKED 项；不要 commit、push、merge 或 release。

git status --short
git diff --stat
git diff --check
git diff -- src/routes/todos.ts src/services/todo-service.ts
git diff -- test/

批准创建一个本地提交。提交前列出暂存文件、提交信息和测试结果。
仅包含 TODO API v2 批准文件；暂不批准 push、merge、数据库迁移和生产发布。

工作区检查
→ 计划模式
→ 契约审批
→ 只读探索
→ 任务拆分
→ Worktree 隔离
→ 阶段实现
→ 子代理审查
→ 集成
→ 完整验收
→ 人工批准
→ 提交/发布