diff --git a/AGENTS.md b/AGENTS.md
index f9aad55..c92c83b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,6 +30,14 @@
 - 命令失败、文件读不到、解析失败 → 结论是「未知」，不是「空」或「没问题」。
 - 没跑的验证写 `Not tried: <原因>`。
 
+### 收尾（Commit）
+
+- **任务完成后自动提交**：一个任务一个 commit（一个 commit 一个目标），不为附带产物（如 `uv.lock`）单开提交，它们跟着产生它的那次任务走。
+- **重大变更开始前，工作区必须干净**：重大变更指改依赖、改表结构、改 `AGENTS.md` / `docs/architecture.md` 这类规则文档、发版本；有残留改动先提交或撤销，再动手。
+- **发版本是独立动作**：只在用户明确确认「发版」后才触发，见「发版本流程」。
+- 提交范围：只提交本次任务的文件（`git add <具体路径>`）。提交前 `git status` 必须只剩本次任务的文件；出现别人的或无关的改动 → 停下问，不顺手提交。
+- 提交信息：标题 `<区域>: <用户可见的变化>`；body 写 现象 → 根因 → 边界（哪些变了、哪些没变）→ 运行了什么 / 没跑什么。
+
 ## 多 Agent 协作
 
 - 看板表头统一为 `| 路径 | 任务 | Agent | 状态 |`，历史行 `Agent` 列留空。
@@ -68,13 +76,12 @@
 
 ## 发版本流程
 
-- 发版本时，先把 `CHANGELOG.md` 的 `Unreleased` 变更整理成新的版本记录，并保留空的 `Unreleased` 标题。
-- **只在发版提交时提升版本号**：`metadata.yaml`、`pyproject.toml`、`uv.lock` 三处 `version` 一起改（bumpversion 已配置这三处）；普通提交不动版本号。
-- 发版提交前跑一次 `uv lock`，确认 `uv.lock` 里的依赖与 `study-tool` 版本跟 `pyproject.toml` 一致；有变化就一起提交。
-- 提交范围：只提交本次任务的文件（`git add <具体路径>`）。提交前 `git status` 必须只剩本次任务的文件；出现别人的或无关的改动 → 停下问，不顺手提交。
-- 提交完成后，给当前提交打最新版本号对应的 tag（如 `v0.0.8`）。打之前 `git tag -l` 查重、`git rev-parse HEAD` 确认，不覆盖已有 tag。
-- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；前端改动仍需 `pnpm build` 并把 `static/` 一起提交。
-- 完成一个能独立回滚的改动就提交一次（一个 commit 一个目标）。提交信息：标题 `<区域>: <用户可见的变化>`；body 写 现象 → 根因 → 边界（哪些变了、哪些没变）→ 运行了什么 / 没跑什么。
+- 发版本只在用户明确确认后触发；触发前工作区必须干净（见「收尾」）。
+- 先把 `CHANGELOG.md` 的 `Unreleased` 变更整理成新的版本记录，保留空的 `Unreleased` 标题，并作为一个普通提交先提交。
+- 发版前跑一次 `uv lock` 自检：它若改动了 `uv.lock`，说明某个任务漏提交了锁文件——补进那次任务，不为它单开提交。
+- 工作区干净后执行 `uv tool run bump-my-version bump patch`：它一次完成「改 `metadata.yaml` / `pyproject.toml` / `uv.lock` 三处 `version` + 自动提交 + 自动打 tag」，**不要再手动 commit 或 `git tag`**。普通提交不动版本号。
+- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确；打 tag 前工具会失败于同名 tag，不覆盖已有 tag。
+- 发版本流程中不要执行编译、测试或构建，除非用户明确要求；前端改动仍需 `pnpm build` 并把 `static/` 一起提交（在发版前的普通提交里完成）。
 
 ## 项目契约
 
diff --git a/docs/agent_workflow.md b/docs/agent_workflow.md
index 21a521b..cd82be0 100644
--- a/docs/agent_workflow.md
+++ b/docs/agent_workflow.md
@@ -41,6 +41,14 @@
 - Seen：1×
 - 状态：观察中（文档里的 python 代码块以钩子结果为准，别手改对抗）
 
+### 发版配置写完要真跑一次 dry-run
+
+- 为什么：没验证过的发版配置会在发版当天才暴露问题，那时最没有余量排查。
+- 证据：
+  - `ecadae5` 之前的 `pyproject.toml`：`bump-my-version` 默认 `regex = false`，且仓库文件是 CRLF，原 `search` 真跑报 `Did not find '(?m)^version = "0.0.8"$' in file: 'pyproject.toml'`，这条发版命令从未成功过。
+- Seen：1×
+- 状态：观察中（改发版配置后跑 `bump-my-version bump patch --dry-run --allow-dirty -vv`，确认三处都会被改）
+
 ## 已升级 → AGENTS.md
 
 ### 修改已存在文件：一次清单、一次同意
@@ -92,6 +100,22 @@
 - Seen：2×
 - 状态：已升级 → AGENTS.md「文档规范」（`docs/todo.md` 已删除；其中 2 条仍未修的代码问题已迁入 `docs/progress/todo.md`）
 
+### 发版流程只留一条线，别让手动步骤和工具自动步骤并存
+
+- 为什么：工具已经自动提交 + 打 tag，文档还写「提交完成后手动打 tag」，照做就会撞同名 tag 失败。
+- 证据：
+  - `ecadae5`：`pyproject.toml` 里 `commit = true` / `tag = true`，而当时 `AGENTS.md` 发版流程仍有「提交完成后，给当前提交打 tag」一条。
+- Seen：1×
+- 状态：已升级 → AGENTS.md「发版本流程」（改为 bump-my-version 一次完成改版本 + 提交 + 打 tag）
+
+### 附带产物跟着任务走，不单开提交
+
+- 为什么：为 1 行 `uv.lock` 单开提交会让历史里充满噪音，也让「一个任务一个 commit」失去意义。
+- 证据：
+  - `4784ac0`：`chore: uv.lock 的 study-tool 版本同步到 0.0.8`，仅 1 行改动，是 v0.0.8 发版的遗留；用户指出「完成一个任务才需要提交」。
+- Seen：1×
+- 状态：已升级 → AGENTS.md「收尾（Commit）」
+
 ## 已否决（不要再提议）
 
 | 规则 | 原因 |