@aipper/aiws-spec 0.0.24 → 0.0.25

package/templates/workspace/.claude/skills/p-aiws-change-validate/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: p-aiws-change-validate
+description: 私有：校验 changes 工件（可 strict）
+---
+
+目标：
+- 校验 `changes/<change-id>/` 工件完整性、归因与 WS:TODO（用于 hooks/CI）
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate "$change_id" --strict
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate "$change_id" --strict
+else
+  npx @aipper/aiws change validate "$change_id" --strict
+fi
+```
+
+说明：
+- `--strict` 会把 `WS:TODO`/缺少归因视为错误，并启用计划质量门（章节完整、步骤粒度、验证命令与预期）
+- 紧急情况下可用 `--allow-truth-drift`（不推荐）

package/templates/workspace/.claude/skills/p-aiws-hooks-install/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: p-aiws-hooks-install
+description: 私有：启用 git hooks 门禁（core.hooksPath=.githooks）
+---
+
+目标：
+- 为当前 git 仓库启用 aiws 门禁 hooks（`git commit`/`git push` 自动跑 `aiws validate .`）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks install .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks install .
+else
+  npx @aipper/aiws hooks install .
+fi
+```
+
+验证（可选）：
+```bash
+git config core.hooksPath
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-hooks-status/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-hooks-status
+description: 私有：查看当前仓库 hooks 状态（只读）
+---
+
+目标：
+- 输出当前仓库 hooks 状态（不修改文件）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-init/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: p-aiws-init
+description: 私有：初始化工作区（生成真值文件与门禁）
+---
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws init .
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws init .
+  aiws validate .
+else
+  npx @aipper/aiws init .
+  npx @aipper/aiws validate .
+fi
+```
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件

package/templates/workspace/.claude/skills/p-aiws-rollback/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: p-aiws-rollback
+description: 私有：回滚工作区（从备份恢复）
+---
+
+目标：
+- 从 `.aiws/backups/` 恢复到某次备份快照
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws rollback . latest
+elif command -v aiws >/dev/null 2>&1; then
+  aiws rollback . latest
+else
+  npx @aipper/aiws rollback . latest
+fi
+```

package/templates/workspace/.claude/skills/p-aiws-update/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: p-aiws-update
+description: 私有：更新工作区（刷新模板与托管块）
+---
+
+目标：
+- 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws update .
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws update .
+  aiws validate .
+else
+  npx @aipper/aiws update .
+  npx @aipper/aiws validate .
+fi
+```
+
+约束：
+- 不写入任何 secrets
+- 只更新托管块或 spec 指定的 `replace_file` 文件

package/templates/workspace/.claude/skills/p-aiws-validate/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: p-aiws-validate
+description: 私有：校验工作区（漂移检测 + 门禁）
+---
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  AIWS_VALIDATE_STAMP=1 ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  AIWS_VALIDATE_STAMP=1 aiws validate .
+else
+  AIWS_VALIDATE_STAMP=1 npx @aipper/aiws validate .
+fi
+```
+
+证据（可选）：
+- stamp：`.agentdocs/tmp/aiws-validate/*.json`（由 `.gitignore` 忽略）

package/templates/workspace/.claude/skills/p-tasks-plan/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: p-tasks-plan
+description: 原子：tasks 同步（从 changes/<id>/tasks.md 生成 update_plan payload）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 用 `changes/<change-id>/tasks.md` 的 checkbox 任务作为“步骤真值”
+- 生成可直接用于 `update_plan` 的 JSON payload（`pending/in_progress/completed`）
+- 输出当前进度摘要（done/total + 当前 in_progress）
+
+约束：
+- 不写入任何 secrets（token、账号、内网端点等不得进入 git）
+- 只读 `changes/<id>/tasks.md`（不自动改写 tasks 文件）
+- 未运行不声称已运行
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`。
+2) 推断 `change-id`：
+   - 优先从当前分支名读取：`git rev-parse --abbrev-ref HEAD`（期望形如 `change/<change-id>`）
+   - 若无法推断：让用户明确本次要同步的 `<change-id>`
+3) 检查 tasks 文件存在：`test -f changes/<change-id>/tasks.md`
+4) 输出进度摘要：
+```bash
+python3 tools/ws_tasks_plan.py status --file changes/<change-id>/tasks.md
+```
+5) 生成 `update_plan` payload（JSON 输出到 stdout）：
+```bash
+python3 tools/ws_tasks_plan.py plan --file changes/<change-id>/tasks.md --explanation "sync tasks.md -> update_plan"
+```
+6) 调用 `update_plan`，将上一步 JSON 原样作为入参（确保任意时刻最多 1 条 `in_progress`）。
+
+输出要求：
+- `Change_ID:` <change-id>
+- `Tasks:` `changes/<change-id>/tasks.md`
+- `Next:` 推荐下一步（通常为继续完善 tasks 或进入 `$ws-dev`）

package/templates/workspace/.claude/skills/using-aiws/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: using-aiws
+description: 默认 workflow bootstrap/router：先读真值，再路由到正确的 ws-* 入口
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
+- 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+
+阶段定位：
+- bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
+
+必需输入：
+- 当前任务描述
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Task intent:` 当前任务意图分类
+- `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
+- `Route:` 选中的下一步 skill
+- `Why:` 选择该 route 的原因
+- `Next:` 进入对应 skill，或先提澄清问题
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+- 无法明确当前任务意图
+- 无法明确归因或验证入口，且不能安全推断
+
+完成判定：
+- 已经明确给出单一路由结果，并进入对应 `ws-*` skill；或已提出关键澄清问题并停止。
+
+执行步骤（强制）：
+1) 先遵守 `$ws-preflight` 的真值读取要求：
+   - 定位项目根目录
+   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+   - 输出 `Root:` / `Found:` / `Missing:`
+2) 若缺失任一真值文件：
+   - 不进入实现
+   - 输出下一步：先 `aiws init .`（或 `npx @aipper/aiws init .`），然后重新执行 `$using-aiws`
+   - 此时 route 视为 `$ws-preflight`
+3) 根据 `packages/spec/docs/workflow-router-rules.json` 判定任务属于哪一类：
+   - 需求/验收/合同变更：`$ws-req-review`
+   - 评审/审计/找风险：`$ws-review`
+   - finish / merge / push / cleanup：`$ws-finish`
+   - handoff / archive summary：`$ws-handoff`
+   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
+   - 小步明确实现/修复/配置调整：`$ws-dev`
+4) 若任务意图或归因不明确：
+   - 只问 1-3 个关键澄清问题
+   - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
+   - 然后停止；不要直接写代码
+5) 若已确定 route：
+   - 先输出：
+     - `Task intent:`
+     - `Binding:`
+     - `Route:`
+     - `Why:`
+   - 然后在同一轮中继续遵循对应 skill 的契约
+6) 路由约束：
+   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+7) 若执行过程中发现复杂度升高：
+   - 从 `$ws-dev` 回退到 `$ws-plan`
+   - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
+
+输出模板：
+- `Root:` <path>
+- `Found:` <files>
+- `Task intent:` <分类>
+- `Binding:` <清晰 / 缺失项>
+- `Route:` <$ws-... 或 clarify>
+- `Why:` <一句到三句>
+- `Next:` <继续执行对应 skill，或提出澄清问题>

package/templates/workspace/.claude/skills/ws-analyze/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ws-analyze
+description: 分析（定位问题与收集上下文）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+
+输入：
+- 主题/需求：用户在本次消息中提供的主题（若不明确，先问一句“本次分析主题是什么？”）
+
+步骤（建议）：
+1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+2) 基于真值文件与当前代码现状，输出：
+   - 目标 / 非目标
+   - 现状证据（文件路径/接口路径）
+   - 推荐方案（1 个）+ 备选（可选）
+   - 风险与回滚（3–8 条）
+   - 最小验证命令（可复现）
+3) 将分析落盘到：`.agentdocs/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
+4) 回复中必须包含：`Evidence:` 证据文件路径。
+
+安全：
+- 不打印 secrets（尤其 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。

package/templates/workspace/.claude/skills/ws-bugfix/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ws-bugfix
+description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片证据，汇总到 issues/fix_bus_issues.csv，并绑定到 changes/<change-id>/）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 用禅道 MCP 拉取 bug 详情与附件（尤其图片）
+- 把证据落盘到 `changes/<change-id>/bug/`（避免只停留在对话）
+- 把修复任务汇总/更新到 `issues/fix_bus_issues.csv`
+- 与 `ws-dev` / `aiws change` 流程绑定，确保可追溯、可验证
+
+非目标（强制）：
+- 不自动 commit / push
+- 不写入任何 secrets（token、cookie、内网地址）
+- 不在无法复现时直接改代码（先产出阻塞信息）
+
+前置：
+1) 先运行 `$ws-preflight`。
+2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
+3) 建立 change 上下文（推荐先于任何落盘）：
+   - 若当前还不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start`
+   - 工作区必须先干净；否则不要先写 `changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
+   - 仓库已有提交：优先 `--worktree`
+   - superproject + submodule：优先 `--worktree --submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `--no-switch`
+```bash
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree dirty before ws-bugfix creates change context"
+  exit 2
+fi
+
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+  if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+    aiws change start <change-id> --hooks --worktree --submodules
+  else
+    aiws change start <change-id> --hooks --worktree
+  fi
+else
+  aiws change start <change-id> --hooks --no-switch
+fi
+```
+   - 若上一步创建了 worktree：后续 bug 证据、CSV 更新、`$ws-dev` 修复都必须在该 worktree 中继续；不要回原工作区重复创建 change
+   - 若该 change 涉及 submodule：
+     - 优先复用 `$ws-dev` 的 `submodules.targets` 生成/确认流程
+     - detached HEAD 时默认建议取 `.gitmodules` 声明的分支
+     - 已附着在某个本地分支时默认建议取当前分支
+     - 以上都只是建议值，最终必须显式写入 `changes/<change-id>/submodules.targets`
+
+建议流程（按顺序）：
+
+## 1) 通过禅道 MCP 拉取 bug
+- 使用当前会话中已启用的 zentao MCP 工具获取：
+  - `bug_id`、标题、优先级/严重级、模块、状态、指派人
+  - 重现步骤、期望结果、实际结果
+  - 附件列表（含图片 URL/文件名）
+- 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
+
+## 2) 证据落盘（强制）
+在当前 active change 上下文的 `changes/<change-id>/bug/` 下落盘：
+- `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
+- `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
+- `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
+
+建议目录：
+```text
+changes/<change-id>/bug/
+  zentao-bug-<bug-id>.json
+  zentao-bug-<bug-id>.md
+  images/<bug-id>/
+```
+
+## 3) 汇总到 issues/fix_bus_issues.csv（upsert）
+- 目标文件：当前 active change 上下文中的 `issues/fix_bus_issues.csv`
+- 若文件不存在，先创建表头：
+```csv
+Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Paths,Evidence_Path,Verify_Command,Fix_Status,Updated_At,Notes
+```
+- 以 `Bug_ID` 为主键 upsert：
+  - 已存在：更新状态/证据/图片路径
+  - 不存在：新增一行
+
+字段约束：
+- `Change_ID`：必须等于当前 `change-id`
+- `Evidence_Path`：指向 `changes/<change-id>/bug/zentao-bug-<bug-id>.md`
+- `Image_Paths`：多个路径用 `;` 分隔
+- `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
+
+## 4) 修复执行与回填
+- 进入 `$ws-dev` 做最小改动修复；若 `ws-bugfix` 创建了 worktree，则必须在该 worktree 中继续。
+- 完成后回填 `issues/fix_bus_issues.csv`：
+  - `Fix_Status`
+  - `Verify_Command`
+  - `Updated_At`
+  - `Notes`（必要时写阻塞原因）
+
+## 5) 验证与交付
+```bash
+aiws change validate <change-id> --strict
+aiws validate . --stamp
+```
+- 需要提交时走 `$ws-commit`。
+- 需要收尾合并时走 `$ws-finish`（或在 superproject + submodule 场景走 `$ws-deliver`）。
+
+输出要求：
+- `Change_ID:` `<change-id>`
+- `Change context:` `<当前分支或 worktree 路径>`
+- `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
+- `Evidence:` `changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
+- `Verify:` 实际运行命令与结果（未运行不声称已运行）

package/templates/workspace/.claude/skills/ws-commit/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ws-commit
+description: 提交（当前分支可直提；submodule 感知；先审计/门禁再 commit）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 支持在**当前分支直接提交**（不要求必须先切 `change/<change-id>`）
+- 提交前审计与证据落盘（`$ws-review`）
+- 提交前门禁校验与证据落盘（`aiws validate . --stamp`）
+- 最后执行 `git commit`（commit 前必须让用户确认 message；不使用 `--no-verify` 绕过 hooks）
+- 若仓库含 submodule：提交前识别并提示正确顺序（先 submodule，再 superproject）
+ - 若你经常遇到 submodule detached：建议日常拉取使用 `$ws-pull`（尽量把 submodule “挂回分支”且不改变 gitlink commit）
+
+安全约束（强制）：
+- 不自动 `git add -A`（避免误提交）；只在用户明确指示时才执行 staging 命令
+- 不自动 push
+- 不写入任何 secrets
+- 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
+- commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
+- 若启用了 `.githooks/commit-msg`：默认会提示优先中文；只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+
+阶段定位：
+- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
+
+必需输入：
+- 当前分支与 staged diff
+- `$ws-review` 生成的审计证据
+- `aiws validate . --stamp` 生成的校验证据
+- 用户确认后的 commit message
+
+必需输出：
+- `证据（Evidence）:` review 文件路径 + validate stamp 路径
+- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
+- `提交信息（Commit）:` 最终提交信息
+
+阻断条件：
+- 没有 staged changes
+- submodule 工作区不干净或 detached 处理不完整
+- 用户未确认 commit message
+- validate 失败
+
+完成判定：
+- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
+
+执行步骤（建议）：
+1) 运行 `$ws-preflight`（确保真值文件就绪）。
+2) 运行 `$ws-review`（优先生成审计证据：`changes/<change-id>/review/codex-review.md`；无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`）。
+3) 运行门禁校验并写 stamp：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws validate . --stamp
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate . --stamp
+else
+  npx @aipper/aiws validate . --stamp
+fi
+```
+4) 输出当前提交上下文（必须输出给用户确认）：
+```bash
+git branch --show-current
+git status --porcelain
+```
+5) 检测是否存在 submodule（有则进入 submodule 感知模式）：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\..*\.path$' || true
+else
+  echo "[info] no .gitmodules"
+fi
+```
+6) 若存在 submodule，逐个检查子仓库工作区是否干净：
+```bash
+while read -r _ sub_path; do
+  [[ -z "${sub_path:-}" ]] && continue
+  echo "== submodule: ${sub_path} =="
+  git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
+  git -C "${sub_path}" status --porcelain || true
+done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true)
+```
+判定规则（强制）：
+- 任一 submodule `git status --porcelain` 非空：停止 superproject commit，先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target_branch>`；不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
+处理指引（detached submodule）：
+```bash
+cur_branch="$(git branch --show-current)"
+change_id="$(echo "${cur_branch}" | sed -n 's|^change/||p')"
+targets="changes/${change_id}/submodules.targets"
+
+source tools/ws_resolve_sub_target.sh
+ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${cur_branch}" || exit 2
+target_branch="${_resolved_branch}"
+remote="${_resolved_remote}"
+
+git -C "${sub_path}" fetch "${remote}" --prune
+if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
+  echo "error: missing ${remote}/${target_branch} for submodule path=${sub_path}"
+  exit 2
+fi
+git -C "${sub_path}" checkout -B "aiws/pin/${target_branch}" HEAD
+git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
+```
+7) 检查当前 staging 内容（必须输出给用户确认）：
+```bash
+git status --porcelain
+git diff --staged --submodule=short
+```
+8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
+9) 生成中文 commit message 草案（格式：`<类型>: <简述>`），输出给用户确认后再执行。
+   - 类型参考：`功能` / `修复` / `重构` / `文档` / `测试` / `构建` / `杂项`
+   - 简述用一句话概括本次改动的"为什么"而非"改了什么"
+   - 命令/路径/代码标识符保持原样不翻译
+   - 若用户给出全英文 message：优先改写成中文；若用户明确要求保留英文，也可以提交（但 strict 模式下会被 hook 拒绝）
+10) 执行提交（不带 `--no-verify`）：
+```bash
+git commit -m "<message>"
+```
+11) 输出提交结果（可选）：
+```bash
+git show --stat --oneline -1
+```
+
+输出要求：
+- `证据（Evidence）:` `changes/<change-id>/review/codex-review.md`（无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`） + `.agentdocs/tmp/aiws-validate/*.json`
+- `上下文（Context）:` 当前分支 + 是否检测到 submodule + 若阻断则给出阻断原因
+- `提交信息（Commit）:` 最终使用的 commit message（仅当用户确认后）