@aipper/aiws-spec 0.0.21 → 0.0.24

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

@@ -11,6 +11,7 @@
 - 不使用 `--no-verify` 绕过 hooks
 - 不自动 push
 - 不打印 secrets
+- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
 
 步骤（建议）：
 1) 先运行 `/ws-preflight`。
@@ -51,7 +52,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/.claude/commands/ws-deliver.md

@@ -3,7 +3,7 @@
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：适配 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`）
@@ -16,11 +16,15 @@
 建议流程（按顺序）：
 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/.claude/commands/ws-dev.md

@@ -7,8 +7,14 @@
 
 建议流程：
 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/.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-handoff.md

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude: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:claude:ws-handoff -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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/{aiws-change-archive.md → p-aiws-change-archive.md}

@@ -1,13 +1,15 @@
 ---
-description: 变更归档：归档已完成的 change 工件
+description: 私有：变更归档：归档已完成的 change 工件并生成 handoff.md
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-archive -->
 # aiws change archive
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 归档已完成 change 工件
+- 归档已完成 change 工件，并生成交接文档：`changes/archive/.../handoff.md`
 
 执行（在仓库根目录）：
 ```bash

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

@@ -1,9 +1,11 @@
 ---
-description: 变更收尾：安全合并 change 分支回目标分支
+description: 私有：变更收尾：安全合并 change 分支回目标分支
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-finish -->
 # aiws change finish
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更列表：列出当前仓库 change 工件
+description: 私有：变更列表：列出当前仓库 change 工件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-list -->
 # aiws change list
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更新建：创建 changes/<change-id> 工件
+description: 私有：变更新建：创建 changes/<change-id> 工件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-new -->
 # aiws change new
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更下一步：输出当前 change 的建议动作
+description: 私有：变更下一步：输出当前 change 的建议动作
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-next -->
 # aiws change next
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更开始：切到 change/<change-id> 并初始化工件
+description: 私有：变更开始：切到 change/<change-id> 并初始化工件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-start -->
 # aiws change start
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更状态：查看 change 状态与阻断项
+description: 私有：变更状态：查看 change 状态与阻断项
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-status -->
 # aiws change status
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更同步：同步 change 与真值基线
+description: 私有：变更同步：同步 change 与真值基线
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-sync -->
 # aiws change sync
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 模板初始化：初始化 changes/templates 覆盖模板
+description: 私有：模板初始化：初始化 changes/templates 覆盖模板
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-templates-init -->
 # aiws change templates init
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 模板来源：查看 change templates 来源
+description: 私有：模板来源：查看 change templates 来源
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-templates-which -->
 # aiws change templates which
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 变更校验：按 strict 校验变更工件与绑定
+description: 私有：变更校验：按 strict 校验变更工件与绑定
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-validate -->
 # aiws change validate
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: Hooks 启用：启用 git hooks 门禁
+description: 私有：Hooks 启用：启用 git hooks 门禁
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-hooks-install -->
 # aiws hooks install
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: Hooks 状态：查看当前仓库 hooks 门禁状态
+description: 私有：Hooks 状态：查看当前仓库 hooks 门禁状态
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-hooks-status -->
 # aiws hooks status
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

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

@@ -1,9 +1,11 @@
 ---
-description: 初始化：落盘 AIWS 真值与门禁文件
+description: 私有：初始化：落盘 AIWS 真值与门禁文件
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-init -->
 # aiws init
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
 - 写入/更新 `.gitignore` 的 aiws 托管块

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

@@ -1,9 +1,11 @@
 ---
-description: 回滚：从 .aiws/backups 恢复快照
+description: 私有：回滚：从 .aiws/backups 恢复快照
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-rollback -->
 # aiws rollback
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 从 `.aiws/backups/` 恢复到某次备份快照
 

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

@@ -1,9 +1,11 @@
 ---
-description: 更新：刷新模板与 tool-native 文件（先备份）
+description: 私有：更新：刷新模板与 tool-native 文件（先备份）
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:aiws-update -->
 # aiws update
 
+（私有原子入口；日常优先用 ws-* 链路。）
+
 目标：
 - 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
 - 更新前备份到 `.aiws/backups/<timestamp>/`