@aipper/aiws-spec 0.0.21 → 0.0.24

package/templates/workspace/.opencode/command/{aiws-validate.md → p-aiws-validate.md}

@@ -1,9 +1,11 @@
 ---
-description: 门禁：校验 required/托管块/漂移（可落盘 stamp）
+description: 私有：门禁：校验 required/托管块/漂移（可落盘 stamp）
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-validate -->
 # aiws validate
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
 - 强门禁：缺 `python3`/缺 required 脚本也应失败

package/templates/workspace/.opencode/command/ws-bugfix.md

@@ -11,15 +11,20 @@ description: 缺陷修复：禅道 MCP 拉单、图片证据落盘并汇总 fix_
 
 建议流程：
 1) 先运行 `/ws-preflight`。
-2) 建立变更工件（推荐）：`aiws change start <change-id> --hooks`（superproject+submodule 可用 `--worktree --submodules`）。
-3) 通过已配置 zentao MCP 拉取 bug 字段与附件列表。
-4) 落盘证据到 `changes/<change-id>/bug/`：
+2) 若当前不在 `change/<change-id>` 分支 / worktree，先建立 change 上下文：
+   - 工作区先保持干净
+   - 仓库已有提交：优先 `aiws change start <change-id> --hooks --worktree`
+   - superproject + submodule：优先 `aiws change start <change-id> --hooks --worktree --submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `aiws change start <change-id> --hooks --no-switch`
+3) 若上一步创建了 worktree：后续 bug 证据、CSV 更新、`/ws-dev` 修复都必须在该 worktree 中继续。
+4) 通过已配置 zentao MCP 拉取 bug 字段与附件列表。
+5) 落盘证据到当前 active change 上下文的 `changes/<change-id>/bug/`：
    - `zentao-bug-<bug-id>.json`
    - `zentao-bug-<bug-id>.md`
    - `images/<bug-id>/...`
-5) upsert `issues/fix_bus_issues.csv`（主键 `Bug_ID`）。
-6) 进入 `/ws-dev` 修复并回填 `Fix_Status/Verify_Command/Updated_At`。
-7) 质量门：`aiws change validate <change-id> --strict` + `aiws validate . --stamp`。
+6) upsert 当前 active change 上下文中的 `issues/fix_bus_issues.csv`（主键 `Bug_ID`）。
+7) 进入 `/ws-dev` 修复并回填 `Fix_Status/Verify_Command/Updated_At`。
+8) 质量门：`aiws change validate <change-id> --strict` + `aiws validate . --stamp`。
 
 强制约束：
 - 不自动 commit / push。

package/templates/workspace/.opencode/command/ws-commit.md

@@ -1,5 +1,5 @@
 ---
-description: Commit：门禁/审计后提交（submodule 感知）
+description: 提交：门禁/审计后提交（submodule 感知）
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-commit -->
 # ws commit
@@ -14,6 +14,7 @@ description: Commit：门禁/审计后提交（submodule 感知）
 - 不使用 `--no-verify` 绕过 hooks
 - 不自动 push
 - 不打印 secrets
+- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
 
 步骤（建议）：
 1) 先运行 `/ws-preflight`。
@@ -54,7 +55,7 @@ git status --porcelain
 git diff --staged --submodule=short
 ```
 7) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-8) 让用户提供 commit message（必须确认后再执行）。
+8) 优先生成并确认中文 commit message（格式建议：`<类型>: <简述>`；若用户明确要求英文也可保留，但 strict 模式下会被 hook 拒绝）。
 9) 执行提交（不带 `--no-verify`）：
 ```bash
 git commit -m "<message>"

package/templates/workspace/.opencode/command/ws-deliver.md

@@ -6,7 +6,7 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：适配 superproject + submodule（数量不固定）的交付收尾，降低“提交顺序/合并回 base 分支”出错概率：
+目标：适配 superproject + submodule（数量不固定）的交付收尾，降低提交顺序和合并回 base 分支的出错概率：
 1) 先逐个提交 submodule（每个 repo 单独确认 commit message；默认 `git add -p`）
 2) 再提交 superproject（包含 submodule gitlink 指针更新 + 自身改动/变更工件）
 3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `/ws-finish`）
@@ -19,11 +19,15 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 建议流程（按顺序）：
 1) 先运行 `/ws-preflight`。
 2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `/ws-submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
+2.1) 若存在 submodule：必须准备 `changes/<change-id>/submodules.targets`，并覆盖所有 submodule path；这是本次交付的目标分支真值。
+   - 生成该文件时可先做默认预填：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在本地分支时默认建议取当前分支。
+   - 上述都只是建议值；真正的 deliver/finish 只认 `submodules.targets`。
 2) 发现 submodules：
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
    - `git -C "<sub_path>" status --porcelain`
-   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`
+   - 先说明该 submodule 目标分支的来源：attached branch 默认建议取当前分支；detached HEAD 默认建议取 `.gitmodules`；若与 `submodules.targets` 已落盘值冲突，则以 `submodules.targets` 为准
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `submodules.targets`（若分支为 `.` 则展开为 `.ws-change.json` 的 `base_branch`）挂到 `aiws/pin/<target-branch>`
    - `git -C "<sub_path>" add -p`
    - `git -C "<sub_path>" diff --staged --stat`
    - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）

package/templates/workspace/.opencode/command/ws-dev.md

@@ -10,8 +10,14 @@ description: 开发：在 AIWS 约束下完成小步交付
 
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `/ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
 2) 建立变更归因（推荐）：
-   - 推荐一键：`aiws change start <change-id> --hooks`
+   - ⚠️ 若准备切分支/创建 worktree，先看 `git status --porcelain`；否则切换上下文后，未提交改动可能“看起来丢了”。
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `/ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若非空仅因为 `/ws-plan` 生成了 `plan/...` 或 `changes/<change-id>/...`，这是预期行为；此时优先 `aiws change start <change-id> --hooks --no-switch`，若仍要 `--switch/--worktree`，先提交这些规划工件。
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
+   - 准备进入实现时：若当前已在 `change/<change-id>` 直接继续；若需切换到该分支，先确认除规划工件外无额外未提交改动，再执行：`git switch change/<change-id>`
+   - 若你明确要“一键切分支”（不推荐，且 dirty 会被拦截）：`aiws change start <change-id> --hooks --switch`
    - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
    - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
    - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）

package/templates/workspace/.opencode/command/ws-finish.md

@@ -37,34 +37,34 @@ fi
 2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 2.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
 2.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
-3) 安全合并并切回目标分支：
-   - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
-   - 否则执行：`aiws change finish <change-id>`
-4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
-5) 合并成功后，按顺序处理每个 submodule（减少 detached；再 push）：
+3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+   - `aiws change finish <change-id> --push`
+   - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`
+   - 该命令会在 fast-forward 合并成功后 push 目标分支；默认优先使用 upstream 配置（`branch.<name>.remote` + `branch.<name>.merge`），只有在你明确知道要推向别的 remote 时才追加 `--remote <name>`
+   - 若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则会在 push 成功后自动执行 `git worktree remove` + `git worktree prune`
+   - AI 入口执行前，应先向用户说明将要 push 的 remote/branch；显式传入 `--push` 即视为确认
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若需要先处理 submodules，则按顺序处理每个 submodule（减少 detached；再 push）：
+   - 先显式解析 base branch，不要用当前分支名替代：
+     - `python3 - <<'PY'`
+     - `import json, pathlib; meta = pathlib.Path("changes") / "<change-id>" / ".ws-change.json"; print((json.loads(meta.read_text(encoding="utf-8")).get("base_branch") or "").strip())`
+     - `PY`
    - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
-     - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
-     - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”
+     - 目标分支真值：`changes/<change-id>/submodules.targets`；若条目里分支写 `.`，则展开为刚才解析出的 `base_branch`
+     - 生成/检查 `submodules.targets` 时，detached HEAD 默认建议取 `.gitmodules` 的 `submodule.<name>.branch`；已附着在本地分支时默认建议取当前分支；这些都只是预填建议，不是 finish/push 的运行时真值
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached
      - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
      - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
      - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
 6) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
-7) submodules 全部成功后，再 push 主仓库当前分支：
-   - `git branch --show-current`
-   - `git status -sb`
-   - `git push`
-8) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
-   - `change_ref="refs/heads/change/<change-id>"`
-   - `main_wt="$(git rev-parse --show-toplevel)"`
-   - `change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '$1=="worktree"{wt=substr($0,10)} $1=="branch"&&$2==ref{print wt; exit}')"`
-   - 若 `change_wt` 非空且不等于 `main_wt`：先输出并让用户确认，再执行 `git worktree remove "$change_wt"`（不带 `--force`），最后 `git worktree prune`
-   - 若 `git -C "$change_wt" status --porcelain` 非空：停止并提示先清理该 worktree
-9) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+7) submodules 全部成功后，再回到主仓库执行：
+   - `aiws change finish <change-id> --push`
+8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 安全：
-- push 前先输出状态并请用户确认远端/分支。
+- push 前先输出状态并说明远端/分支。
 - 不执行破坏性命令。
 <!-- AIWS_MANAGED_END:opencode:ws-finish -->
 

package/templates/workspace/.opencode/command/ws-handoff.md

@@ -0,0 +1,25 @@
+---
+description: 交接：查看归档 change 的 handoff.md（由 aiws change archive 生成）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-handoff -->
+# ws handoff
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 交接与回放：通过 `handoff.md` 让已归档的 change 可被下一位/下一次会话快速接力。
+- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（由 `aiws change archive` 自动生成）。
+
+执行建议：
+1) 若 change 已完成并准备归档：运行 `/p-aiws-change-archive`（会先严格校验，再归档并生成 `handoff.md`）。
+2) 查看 handoff：
+```bash
+change_id="<change-id>"
+ls -1 changes/archive/*-"${change_id}"/handoff.md
+sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
+```
+3) 依赖提示：
+- 若你在某个 change 的 `proposal.md` 声明了 `Depends_On`，`aiws change start` 会尝试读取依赖 change 的 `handoff.md` 并输出摘要（前提：依赖已归档且 handoff 存在）。
+<!-- AIWS_MANAGED_END:opencode:ws-handoff -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-plan.md

@@ -7,14 +7,18 @@ description: 规划：生成可落盘 plan 工件
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 生成可落盘执行计划（供 /ws-dev 执行）。
+- 若尚未进入本次 change 的工作上下文：先建立 `change/<change-id>` 分支 / worktree，再生成可落盘执行计划（供 /ws-dev 执行）。
 
 执行建议：
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
-2) 生成或更新计划文件：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`。
-3) 计划至少包含：`Bindings`、`Goal`、`Non-goals`、`Scope`、`Plan`、`Verify`、`Risks & Rollback`、`Evidence`。
-4) 若已有 `changes/<change-id>/proposal.md`，对齐 `Plan_File` / `Contract_Row` / `Evidence_Path`。
-5) 完成后先运行 `/ws-plan-verify`，通过再进入 `/ws-dev`。
+2) 若当前不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start <change-id>` 建立上下文：
+   - 仓库已有提交：优先 `aiws change start <change-id> --hooks --worktree`；若声明了 submodules，加 `--submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `aiws change start <change-id> --hooks --no-switch`
+3) 若上一步创建了 worktree：切到输出的 `worktree:` 路径，后续所有计划文件都写在该 worktree 中。
+4) 生成或更新计划文件：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`。
+5) 计划至少包含：`Bindings`、`Goal`、`Non-goals`、`Scope`、`Plan`、`Verify`、`Risks & Rollback`、`Evidence`。
+6) 若已有 `changes/<change-id>/proposal.md`，对齐 `Plan_File` / `Contract_Row` / `Evidence_Path`。
+7) 完成后先运行 `/ws-plan-verify`，通过再进入 `/ws-dev`。
 <!-- AIWS_MANAGED_END:opencode:ws-plan -->
 
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/command/ws-review.md

@@ -1,5 +1,5 @@
 ---
-description: Review：提交前审计改动并落盘证据
+description: 评审：提交前审计改动并落盘证据
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-review -->
 # ws review

package/templates/workspace/AGENTS.md

@@ -8,23 +8,27 @@
 协作约束（建议最小集）：
 - 每次变更使用分支 `change/<change-id>`，并维护 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
 - 启用本机门禁（推荐）：`aiws hooks install .`（或手工：`git config core.hooksPath .githooks`；`git commit`/`git push` 会自动跑 `aiws validate .`）
+- 启用 hooks 后，`.githooks/commit-msg` 默认提示优先使用中文 commit message；如需强制，可执行：`git config aiws.commitMessagePolicy strict`
 - 提交前校验（强制门禁）：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - Codex（推荐）：本仓库内置 repo skills：`.agents/skills/`（可显式 `$ws-dev`，也可隐式套用工作流）
+- Codex skills 命名约定：`ws-*` 为常用链路入口；`p-*` 为私有原子入口（一般不需要直接调用）。
 - Codex skills（常用，一句话说明）：
   - `$ws-preflight`：预检（读取真值文件并输出约束摘要）
   - `$ws-submodule-setup`：子模块分支对齐（写入 `.gitmodules` 的 `submodule.<name>.branch`）
   - `$ws-plan`：规划（生成可落盘 `plan/` 工件；供 `$ws-dev` 执行）
   - `$ws-plan-verify`：计划质检（执行前检查计划是否过长/跑偏）
+  - `$p-tasks-plan`：原子：tasks 同步（从 `changes/<id>/tasks.md` 生成 `update_plan` payload）
   - `$ws-dev`：开发（按需求实现并验证；适用于任何需要修改代码/配置的任务）
   - `$ws-bugfix`：缺陷修复（禅道 MCP 拉单 + 图片证据落盘 + `issues/fix_bus_issues.csv` 汇总）
   - `$ws-pull`：拉取并对齐 submodules（尽量避免 detached；减少人为差异）
   - `$ws-push`：推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
   - `$ws-review`：评审（提交前审计；证据优先落盘到 `changes/<change-id>/review/`）
   - `$ws-commit`：提交（先审计/门禁再 commit；submodule 感知）
-  - `$aiws-init`：初始化工作区（生成真值文件与门禁）
-  - `$aiws-validate`：校验工作区（漂移检测 + 门禁）
-  - `$aiws-hooks-install`：启用 git hooks 门禁（`core.hooksPath=.githooks`）
-  - `$aiws-change-new`：创建 `changes/<change-id>` 工件
+  - `$ws-handoff`：交接（归档后生成/查看 `changes/archive/.../handoff.md`，便于跨会话接力）
+  - `$p-aiws-init`：初始化工作区（生成真值文件与门禁）
+  - `$p-aiws-validate`：校验工作区（漂移检测 + 门禁）
+  - `$p-aiws-hooks-install`：启用 git hooks 门禁（`core.hooksPath=.githooks`）
+  - `$p-aiws-change-new`：创建 `changes/<change-id>` 工件
 - Codex CLI（推荐，可选）：安装全局 skills：`npx @aipper/aiws codex install-skills`（写入 `~/.codex/skills/` 或 `$CODEX_HOME/skills`）
 - Codex CLI（遗留，可选）：安装全局 prompts：`npx @aipper/aiws codex install-prompts`（写入 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`；prompts 已 deprecated）
 - 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等

package/templates/workspace/AI_WORKSPACE.md

@@ -80,10 +80,10 @@
 - 先 `/server-test-plan` → `/server-test` 跑到验收通过
 - 再 `/server-commit` 对 `server_dirs` 指定的 submodule 做 commit，并在工作区根仓库提交 submodule 指针更新
 
-建议 commit message 保持通用简洁（Conventional Commits 风格），例如：
-- `fix(api): ...`
-- `chore(server): api test fixes`
-- `chore(workspace): bump server submodules`
+建议 commit message 保持通用简洁，优先使用中文；英文也可以，例如：
+- `修复: API 健康检查空指针`
+- `构建: 调整 server 测试脚本`
+- `杂项: 更新 workspace submodule 指针`
 
 ## 3) 测试入口
 

package/templates/workspace/changes/README.md

@@ -28,6 +28,7 @@ changes/
   - 可选：`--worktree-dir <path>` 覆盖 worktree 目录
   - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`
 - `aiws change finish <change-id>`（安全合并：fast-forward 合并回目标分支；在 `change/<change-id>` 分支上执行时会尝试使用 `.ws-change.json` 的 `base_branch` 作为目标分支）
+- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则在 push 成功后自动执行 worktree cleanup；含 submodule 的 worktree 会因 Git 原生限制在 clean-check 后内部走 `git worktree remove --force`）
 - `aiws change new <change-id>`
 - `aiws change list`
 - `aiws change status <change-id>`
@@ -41,9 +42,10 @@ Active change（推荐，团队共享）：
 - 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync|archive`
 
 计划质量门（推荐，执行前）：
-- 先生成计划：`$ws-plan`
+- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支 / worktree，再在该上下文内写 `plan/...`）
 - 再执行计划质检：`$ws-plan-verify`
 - 最后进入实现：`$ws-dev`
+- 若 `$ws-plan` 创建了独立 worktree，后续 `$ws-plan-verify` / `$ws-dev` / `$ws-finish` 都应优先在该 worktree 内继续
 - 目标：确保计划具备主索引绑定、步骤不过长、验证命令可复现且有预期结果
 
 模板覆盖（可选）：
@@ -59,7 +61,10 @@ Active change（推荐，团队共享）：
 - 若真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）在变更期间发生变化，严格校验/归档会要求先运行 `aiws change sync <change-id>` 确认基线。
 
 Hooks/CI（推荐，硬约束）：
-- 工作区会安装 `.githooks/{pre-commit,pre-push}`（默认执行 `aiws validate .`）与门禁脚本（`tools/ws_change_check.py`、`tools/requirements_contract.py`）。
+- 工作区会安装 `.githooks/{commit-msg,pre-commit,pre-push}`：
+  - `commit-msg`：默认提示优先使用中文 commit message；若执行 `git config aiws.commitMessagePolicy strict`，则会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+  - `pre-commit` / `pre-push`：默认执行 `aiws validate .`
+- 还会安装门禁脚本（`tools/ws_change_check.py`、`tools/requirements_contract.py`）。
 - **启用 hooks 需要本地配置**（不会自动提交到 git）：
   - 直接启用：`git config core.hooksPath .githooks`
   - 或使用：`aiws hooks install .`（等价）
@@ -69,4 +74,5 @@ Hooks/CI（推荐，硬约束）：
 合并建议（减少人为 merge 引入新问题）：
 - 优先使用 worktree + fast-forward 合并：
   - 完成后在主工作区（例如 `main`）执行：`aiws change finish <change-id>`（等价于 `git merge --ff-only change/<change-id>`）
+  - 若还要顺手 push 并清理独立 change worktree：`aiws change finish <change-id> --push`
   - 若失败：先在 worktree 里 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`