FIRST GOVERNED TASK
第一个受治理任务
从定义验收、定位上下文和限定 diff，到规划门禁、运行验证并保留交付证据。
开始前的条件
这条流程面向已有权限的 Super Dolphin checkout。开始前应完成快速开始，并确保：
- 当前终端位于准备修改的 checkout，而不是相邻 worktree。
- Git hooks 已通过
make install-hooks安装。 - Provider CLI 已认证，所需语言服务器可用。
- 一个分支只承载一个逻辑任务，不混入格式化、依赖升级或无关生成物变化。
若使用 linked Git worktree，先在该 worktree 内执行：
make codex-worktree-ready
go run ./cmd/codex-worktree-setup ready
go run ./cmd/codex-worktree-setup verify
通过后开启一个新的 Agent 任务，使它加载当前 worktree 自己的 MCP/LSP peer。不要复用其他 checkout 的二进制、配置、定义、诊断或编辑结果。
1. 定义任务与验收结果
先写清楚要改变什么，而不是先让 Agent 搜索整个仓库。一个可执行任务至少包含：
- 用户或系统当前遇到的问题。
- 预期可观察行为。
- 明确不在本次修改范围内的内容。
- 需要保留的兼容性、安全或数据约束。
- 什么证据足以证明任务完成。
修复类任务应先复现缺陷，并计划加入能锁住根因的测试、fixture、golden file 或 snapshot。仓库不会把“代码看起来合理”当作回归证据。
2. 定位最小上下文
从 docs/doc/codemap/README.md 选择与任务最接近的代码地图，再沿以下顺序收缩范围：
目标行为
-> 代码地图与能力清单
-> 模块所有权与契约
-> LSP definition / references / hierarchy / diagnostics
-> 源码与聚焦测试
代码地图负责导航，源码和测试负责当前行为真相。契约、架构决策和注册表解释所有权及依赖方向。不要因为一个生成式地图过期就直接编辑它；应修改所属真源，再由 owning generator 刷新。
3. 理解影响面
在编辑前，用当前 worktree 的 LSP 获取定义、引用、调用层级和诊断。确认：
- 哪个模块拥有这项行为。
- 数据经过哪些 port、DTO、mapper 或 schema。
- 哪些调用方和测试依赖当前语义。
- 是否会跨越 Store、Provider、Platform、UI 或 command 边界。
- 缺少配置、身份、所有权或依赖时应该如何失败。
跨模块任务可以扩大必要上下文，但扩大影响面分析不等于通读整个仓库。若必须读完所有代码才能判断后果，通常说明边界、所有权或守卫还不够明确，应把它作为架构风险记录下来。
4. 做最窄的修改
保持以下纪律：
- 只修改能够解释为同一意图的文件。
- 非平凡修复同时提交回归证据。
- 无效配置、缺失依赖和畸形数据必须 fail-fast。
- 不用默认值、空结果或 silent catch 隐藏失败。
- 不让业务模块直接依赖 Store、Provider 或 UI 实现。
- 不手改生成输出来压住 drift check。
- 不把凭据、本地数据库、日志、Provider home、用户 Memory 或机器路径写入 diff。
5. 让仓库规划门禁
在执行一组宽泛命令前，先查看本次文件变化会选择哪些维护门禁：
./scripts/ai_maintenance_gates.sh \
--print-plan \
--changed-file internal/module/example/service.go \
--changed-file internal/module/example/service_test.go
--changed-file 可以重复传入。--print-plan 只输出计划，不执行门禁；它让检查范围、owner 和证据要求在运行前可见。
6. 运行匹配变更面的验证
| 变更面 | 最低验证入口 |
|---|---|
| 仅文档 | git diff --check |
| 聚焦 Go package | ./scripts/test_with_guard.sh <实际 package> -count=1 |
| 架构规则或 guard baseline | make guard |
| 广泛 Go 或跨层修改 | make test 与 make build-plain |
| React 前端 | cd frontend-app && npm run lint && npm test && npm run build |
| SQL 或 Store 生成 | make sqlc-verify 加受影响 package 的 guarded tests |
| 代码地图 | make codemap-check |
| Project map | make project-map-check |
| Capability contract | make capcontract-check |
这是最低入口，不是固定的万能命令清单。实际任务仍应运行能证明其用户行为、失败路径和跨层契约的聚焦测试。
7. 记录可复查证据
交付记录至少保留：
- 源提交或精确 diff。
- 实际执行的命令。
- 对应规则、测试、诊断或生成物。
- 退出状态与有意义的失败输出。
- 跳过表面、既有失败和尚未解除的 blocker。
后来一次绿色重跑不能抹去更早的确定性失败。需要说明之前为什么失败、修改了什么以及为什么新的结果足以关闭问题。
8. 提交前检查
确认 diff 仍只有一个逻辑意图，并使用包含中文的提交标题。修复类提交必须在同一提交中包含 bug-locking 证据；不要用 --no-verify 把失败 hook 变成成功声明。
一个可接受的标题示例：
fix(thread): 修复恢复状态丢失并补充回归测试
完成标准
一次受治理任务只有同时满足以下条件才算完成：目标行为可观察、影响面得到解释、变更保持在所有权边界内、失败语义没有被隐藏、匹配变更面的验证为绿色，并且剩余风险与 blocker 被明确记录。
Agent 的 done 只表示执行结束，不代表仓库已经接受变更。
下一步
阅读桌面工作区，了解用户从哪里创建对话、选择项目、观察执行、处理中断与恢复。