@aipper/aiws-spec 0.0.23 → 0.0.24

package/templates/workspace/.claude/commands/ws-finish.md

@@ -34,34 +34,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:claude:ws-finish -->
 

package/templates/workspace/.claude/commands/ws-plan.md

@@ -4,14 +4,18 @@
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 生成可落盘执行计划（供 /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:claude:ws-plan -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-dev.md

@@ -12,8 +12,12 @@ argument-hint: ""
 
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `$ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
 2) 建立变更归因（推荐）：
-   - 推荐一键：`aiws change start <change-id> --hooks`
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `$ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若 `/ws-plan` 已生成 `plan/...` 或 `changes/<change-id>/...` 导致工作区非空，这是预期行为；此时不要直接再做 `--switch/--worktree`，优先：`aiws change start <change-id> --hooks --no-switch`，或先提交规划工件。
+   - 推荐一键（工作区干净时）：`aiws change start <change-id> --hooks`
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-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/.githooks/commit-msg

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${WS_CHANGE_HOOK_BYPASS:-0}" == "1" ]]; then
+  echo "warn: WS_CHANGE_HOOK_BYPASS=1; skip aiws commit-msg hook" >&2
+  exit 0
+fi
+
+msg_file="${1:-}"
+[[ -n "${msg_file:-}" && -f "$msg_file" ]] || exit 0
+
+policy="${AIWS_COMMIT_MSG_POLICY:-}"
+if [[ -z "${policy:-}" ]]; then
+  policy="$(git config --get aiws.commitMessagePolicy 2>/dev/null || true)"
+fi
+policy="${policy:-warn}"
+
+case "$policy" in
+  off|disabled|0)
+    exit 0
+    ;;
+  warn|prefer-zh)
+    policy="warn"
+    ;;
+  strict|require-zh|1)
+    policy="strict"
+    ;;
+  *)
+    echo "warn: unknown aiws commit message policy '${policy}', fallback to warn" >&2
+    policy="warn"
+    ;;
+esac
+
+first_line="$(sed -n '1{s/\r$//;p;q;}' "$msg_file")"
+first_line="${first_line#"${first_line%%[![:space:]]*}"}"
+first_line="${first_line%"${first_line##*[![:space:]]}"}"
+
+[[ -n "${first_line:-}" ]] || exit 0
+
+case "$first_line" in
+  Merge\ *|Revert\ *|fixup!\ *|squash!\ *)
+    exit 0
+    ;;
+esac
+
+has_cjk=1
+if command -v python3 >/dev/null 2>&1; then
+  if python3 - "$first_line" <<'PY'
+import re
+import sys
+
+line = sys.argv[1].strip()
+sys.exit(0 if re.search(r"[\u3400-\u9fff]", line) else 1)
+PY
+  then
+    has_cjk=0
+  fi
+else
+  if printf '%s\n' "$first_line" | grep -q '[一-龥]'; then
+    has_cjk=0
+  fi
+fi
+
+if [[ "$has_cjk" -eq 0 ]]; then
+  exit 0
+fi
+
+if [[ "$policy" == "warn" ]]; then
+  cat >&2 <<'EOF'
+warn: commit message is better in Chinese, but English is still allowed.
+
+hint:
+  - preferred format: 修复: 登录页空指针
+  - or: 功能: 新增 submodule targets 校验
+  - if you are in AI tools, prefer: $ws-commit / /ws-commit / ws:commit
+  - set strict mode if needed: git config aiws.commitMessagePolicy strict
+  - disable this reminder: git config aiws.commitMessagePolicy off
+
+allowed exceptions:
+  - Merge ...
+  - Revert ...
+  - fixup! ...
+  - squash! ...
+EOF
+
+  echo "message: ${first_line}" >&2
+  exit 0
+fi
+
+cat >&2 <<'EOF'
+error: commit message should be in Chinese (strict mode).
+
+hint:
+  - use format: 修复: 登录页空指针
+  - or: 功能: 新增 submodule targets 校验
+  - if you are in AI tools, prefer: $ws-commit / /ws-commit / ws:commit
+  - downgrade to warn: git config aiws.commitMessagePolicy warn
+  - disable only when necessary: git config aiws.commitMessagePolicy off
+  - bypass only when necessary: WS_CHANGE_HOOK_BYPASS=1 git commit ...
+
+allowed exceptions:
+  - Merge ...
+  - Revert ...
+  - fixup! ...
+  - squash! ...
+EOF
+
+echo "message: ${first_line}" >&2
+exit 1

package/templates/workspace/.iflow/commands/ws-commit.toml

@@ -16,6 +16,7 @@ prompt = """
 - 不使用 `--no-verify` 绕过 hooks
 - 不自动 push
 - 不打印 secrets
+- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
 
 强制步骤：
 1) 读取真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`（缺失则先运行 `/aiws-init` 或 `aiws init .`）。
@@ -36,7 +37,7 @@ prompt = """
    - `git status --porcelain`
    - `git diff --staged --submodule=short`
 8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-9) 让用户提供 commit message（必须确认后再执行）。
+9) 优先生成并确认中文 commit message（格式建议：`<类型>: <简述>`；若用户明确要求英文也可保留，但 strict 模式下会被 hook 拒绝）。
 10) 执行提交（不带 `--no-verify`）：`git commit -m "<message>"`。
 
 输出必须包含：

package/templates/workspace/.iflow/commands/ws-deliver.toml

@@ -8,7 +8,7 @@ description = "交付（submodules + superproject 分步提交，并安全合并
 prompt = """
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：适配 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`）
@@ -21,11 +21,15 @@ prompt = """
 建议流程（按顺序）：
 1) 先确认真值文件存在并遵守：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
 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/.iflow/commands/ws-finish.toml

@@ -22,33 +22,33 @@ prompt = """
 5) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 5.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
 5.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
-6) 安全合并（默认 fast-forward）：
-   - 在 `change/<change-id>` 分支上：`aiws change finish`（会尝试读 `changes/<change-id>/.ws-change.json` 的 `base_branch` 并切回目标分支）
-   - 否则：`aiws change finish <change-id>`
-7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish`。
-8) 合并成功后，按顺序处理每个 submodule（先“并回目标分支”，再 push）：
+6) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+   - `aiws change finish <change-id> --push`
+   - 在 `change/<change-id>` 分支上也可省略 `<change-id>`；命令会尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch`
+   - 该命令会在 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` 即视为确认
+7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+8) 若需要先处理 submodules，则按顺序处理每个 submodule（先并回目标分支，再 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>"`
 9) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
-10) submodules push 完成后，再 push 主仓库当前分支：
-   - `git branch --show-current`
-   - `git status -sb`
-   - `git push`
-11) 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
-12) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+10) submodules push 完成后，再回到主仓库执行：
+   - `aiws change finish <change-id> --push`
+11) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 边界：
-- push 前先输出状态并请用户确认远端/分支。
+- push 前先输出状态并说明远端/分支。
 - 不执行破坏性命令。
 """

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

@@ -14,6 +14,7 @@ description: 提交：门禁/审计后提交（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,10 +10,13 @@ description: 开发：在 AIWS 约束下完成小步交付
 
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `/ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
 2) 建立变更归因（推荐）：
-   - ⚠️ 开始前先确认工作区干净：`git status --porcelain` 为空；否则切分支/创建 worktree 后，未提交改动可能“看起来丢了”（worktree 只从 `HEAD` checkout，未提交内容会留在原目录）。
+   - ⚠️ 若准备切分支/创建 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；不切分支）
-   - 准备进入实现（且工作区干净）后再切换：`git switch change/<change-id>`
+   - 准备进入实现时：若当前已在 `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`

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-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/AGENTS.md

@@ -8,6 +8,7 @@
 协作约束（建议最小集）：
 - 每次变更使用分支 `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-*` 为私有原子入口（一般不需要直接调用）。

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`

package/templates/workspace/manifest.json

@@ -17,6 +17,7 @@
     "REQUIREMENTS.md",
     ".gitignore",
     ".aiws/manifest.json",
+    ".githooks/commit-msg",
     ".githooks/pre-commit",
     ".githooks/pre-push",
     "changes/README.md",
@@ -212,6 +213,7 @@
     ],
     "replace_file": [
       ".aiws/manifest.json",
+      ".githooks/commit-msg",
       ".githooks/pre-commit",
       ".githooks/pre-push",
       "tools/ws_change_check.py",

package/templates/workspace/tools/ws_change_check.py

@@ -53,7 +53,7 @@ def list_submodules_from_gitmodules(root: Path) -> List[Tuple[str, str]]:
             continue
         key = line[:idx].strip()
         sub_path = line[idx + 1 :].strip()
-        m = re.match(r"^submodule\.([^.]+)\.path$", key)
+        m = re.match(r"^submodule\.(.+)\.path$", key)
         if not m:
             continue
         name = (m.group(1) or "").strip()

package/templates/workspace/tools/ws_resolve_sub_target.sh

@@ -28,6 +28,7 @@ ws_resolve_sub_target() {
   if [[ -n "${override:-}" ]]; then
     _resolved_branch="${override%% *}"
     _resolved_remote="${override#* }"
+    if [[ "${_resolved_branch:-}" == "." ]]; then _resolved_branch="${base_branch}"; fi
   else
     # Priority 2: .gitmodules submodule.<name>.branch
     local cfg_branch