@aipper/aiws-spec 0.0.21 → 0.0.24

package/templates/workspace/.agents/skills/ws-finish/SKILL.md

@@ -8,13 +8,13 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 目标：
 - 在结束一次变更交付时，用 fast-forward 安全合并 `change/<change-id>` 回目标分支，减少手输分支名导致的错误
 - 合并成功后，按 `submodule -> superproject` 顺序 push，避免遗漏导致其它仓库拉取异常
-- 不自动删分支；push 前必须让用户确认
- - 若团队希望减少 submodule detached 的人为差异：建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `$ws-pull`
+- 不自动删分支；AI 入口执行前应先向用户说明将要 push 的 remote/branch，显式传入 `--push` 即视为确认
+- 若团队希望减少 submodule detached 的人为差异：建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `$ws-pull`
 
 前置（必须）：
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
 - change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若使用 worktree：在“目标分支所在 worktree”执行（`aiws change finish` 会提示正确的 worktree）
+- 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
 - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
 
 建议步骤：
@@ -61,96 +61,127 @@ fi
 ```bash
 aiws change state "${change_id}" --write
 ```
-2) 安全合并（默认 fast-forward；并会在需要时切到目标分支）：
+2) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接使用最小收尾闭环：
 ```bash
 # 若当前就在 change/<change-id> 分支上，可省略 <change-id>
 change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change finish "${change_id}"
+  ./node_modules/.bin/aiws change finish "${change_id}" --push
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change finish "${change_id}"
+  aiws change finish "${change_id}" --push
 else
-  npx @aipper/aiws change finish "${change_id}"
+  npx @aipper/aiws change finish "${change_id}" --push
 fi
 ```
-3) 若 fast-forward 失败（提示需要 rebase）：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
-4) 合并成功后，先把每个 submodule 的 gitlink commit 合并回其目标分支（解决 detached HEAD），并按顺序 push：
+说明：
+- 该命令会在 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；CLI 本身只有在显式传入 `--push` 时才会真正执行 push。
+
+3) 若你需要先处理 submodules，则不要依赖当前分支名推断目标分支，先显式解析 `base_branch`，再执行 submodule 步骤，最后回到主仓库执行 `aiws change finish --push`：
+```bash
+change_id="<change-id>"
+base_branch="$(python3 - <<'PY'
+import json, pathlib
+change_id = "<change-id>"
+meta = pathlib.Path("changes") / change_id / ".ws-change.json"
+data = json.loads(meta.read_text(encoding="utf-8"))
+print((data.get("base_branch") or "").strip())
+PY
+)"
+test -n "$base_branch"
+```
+4) 若 fast-forward 失败（提示需要 rebase）：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若存在 `.gitmodules`，先把每个 submodule 的 gitlink commit 合并回其目标分支（解决 detached HEAD），并按顺序 push：
 ```bash
-# superproject 当前分支（finish 后通常是 base 分支）
-base_branch="$(git branch --show-current)"
+# 不要用当前分支名代替目标分支；这里显式使用 .ws-change.json 的 base_branch
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
 
 # 子模块清单（没有则跳过）
 git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true
 
 # 对每个 submodule.<name>.path <sub_path>：
 # 说明：`git submodule update` 会把 submodule checkout 到固定 gitlink commit，导致 detached HEAD。
-# 为减少“游离状态”的协作摩擦，本步骤采用“pin 分支”策略：
-# - 仅在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时执行（避免 origin 多分支导致误判）
-# - 不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来“解 detached”
+# 为减少游离状态的协作摩擦，本步骤采用 pin 分支策略：
+# - `changes/<change-id>/submodules.targets` 是本次 finish/push 的真值；每个 submodule path 都必须在该文件中声明目标分支（可选 remote）
+# - `.gitmodules` 的 `submodule.<name>.branch` 仍建议保留，用于团队默认配置与校验，但不再作为 finish/push 的 fallback
+# - 生成/检查 `submodules.targets` 时可显式说明默认来源：
+#   - detached HEAD：默认建议取 `.gitmodules` 的 `submodule.<name>.branch`
+#   - 已附着在某个本地分支：默认建议取当前分支
+#   - 以上仅为预填建议；真正执行 finish/push 时仍只认 `submodules.targets`
+# - 不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来解 detached
 # - 不改动 submodule 现有分支指针（例如不强行移动 main/master）
 # - 创建/更新本地 pin 分支：`aiws/pin/<target_branch>` 指向 gitlink commit，并将其 upstream 设为 `origin/<target_branch>`
-sub_sha="$(git rev-parse "HEAD:<sub_path>")"
-cfg_branch="$(git config --file .gitmodules --get "submodule.<name>.branch" 2>/dev/null || true)"
-if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-if [[ -z "${cfg_branch:-}" ]]; then
-  echo "[warn] <sub_path>: missing .gitmodules submodule.<name>.branch; keep detached and skip auto-push"
-  continue
-fi
-target_branch="$cfg_branch"
-pin_branch="aiws/pin/${target_branch}"
+if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+  if [[ ! -f "${targets}" ]]; then
+    echo "error: missing ${targets} (required when .gitmodules declares submodules)"
+    exit 2
+  fi
 
-git -C "<sub_path>" fetch origin --prune
-if ! git -C "<sub_path>" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-  echo "[warn] <sub_path>: origin/${target_branch} not found; keep detached and skip auto-push"
-  continue
-fi
+  source tools/ws_resolve_sub_target.sh
 
-# 仅当 gitlink commit 属于 origin/<target_branch> 的历史时才“挂回分支”
-if ! git -C "<sub_path>" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-  echo "[warn] <sub_path>: ${sub_sha} is not in origin/${target_branch}; keep detached and stop (need manual reconcile)"
-  exit 1
-fi
+  while read -r key sub_path; do
+      name="${key#submodule.}"; name="${name%.path}"
+      [[ -z "${sub_path:-}" ]] && continue
+      echo "== submodule: ${sub_path} (${name}) =="
+
+      current_branch="$(git -C "${sub_path}" branch --show-current 2>/dev/null || true)"
+      declared_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+      if [[ -n "${current_branch}" ]]; then
+        echo "info: ${sub_path} default suggestion would be current branch: ${current_branch}"
+      elif [[ -n "${declared_branch}" ]]; then
+        echo "info: ${sub_path} default suggestion would be .gitmodules branch: ${declared_branch}"
+      else
+        echo "warn: ${sub_path} has no current branch and no .gitmodules branch; submodules.targets must be filled manually"
+      fi
 
-git -C "<sub_path>" checkout -B "${pin_branch}" "${sub_sha}"
-git -C "<sub_path>" branch --set-upstream-to "origin/${target_branch}" "${pin_branch}" >/dev/null 2>&1 || true
-git -C "<sub_path>" status -sb
+      sub_sha="$(git rev-parse "HEAD:${sub_path}")"
 
-# push：只允许 fast-forward（若远端分叉会被拒绝；此时必须人工处理）
-git -C "<sub_path>" push origin "${sub_sha}:refs/heads/${target_branch}"
+      ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
+      target_branch="${_resolved_branch}"
+      remote="${_resolved_remote}"
+      pin_branch="aiws/pin/${target_branch}"
+
+      git -C "${sub_path}" fetch "${remote}" --prune
+      if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
+        echo "error: ${sub_path}: missing ${remote}/${target_branch}; refusing to push superproject (would break gitlink fetchability)"
+        exit 2
+      fi
+
+      # 仅当 gitlink commit 属于 <remote>/<target_branch> 的历史时才挂回分支
+      if ! git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "${remote}/${target_branch}"; then
+        echo "[warn] ${sub_path}: ${sub_sha} is not in ${remote}/${target_branch}; keep detached and stop (need manual reconcile)"
+        exit 1
+      fi
+
+      git -C "${sub_path}" checkout -B "${pin_branch}" "${sub_sha}"
+      git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "${pin_branch}" >/dev/null 2>&1 || true
+      git -C "${sub_path}" status -sb
+
+      # push：只允许 fast-forward（若远端分叉会被拒绝；此时必须人工处理）
+      git -C "${sub_path}" push "${remote}" "${sub_sha}:refs/heads/${target_branch}"
+    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+fi
 ```
 规则：
-- 每个 submodule 必须先执行“pin 分支挂回 + fast-forward push”，再 push 主仓库。
-- 若任一 submodule 的 gitlink commit 不在 `origin/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
+- 每个 submodule 必须先执行 pin 分支挂回 + fast-forward push，再 push 主仓库。
+- 若任一 submodule 的 gitlink commit 不在 `<remote>/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
 
-5) 仅当 submodules 全部成功后，再 push superproject 当前分支：
-```bash
-git branch --show-current
-git status -sb
-git push
-```
-6) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
+6) 仅当 submodules 全部成功后，再在 superproject 当前分支执行最小收尾闭环：
 ```bash
 change_id="<change-id>"
-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 }
-')"
-
-if [[ -n "${change_wt:-}" && "$change_wt" != "$main_wt" ]]; then
-  if [[ -n "$(git -C "$change_wt" status --porcelain 2>/dev/null)" ]]; then
-    echo "[warn] worktree not clean, skip remove: $change_wt"
-    echo "hint: clean it first, then run: git worktree remove \"$change_wt\""
-  else
-    git worktree remove "$change_wt"
-    git worktree prune
-  fi
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "${change_id}" --push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "${change_id}" --push
+else
+  npx @aipper/aiws change finish "${change_id}" --push
 fi
 ```
-规则：
-- 清理前先把 `change_wt` 输出给用户确认，避免误删。
-- 仅使用 `git worktree remove`（不带 `--force`）。
+说明：
+- 该命令内部已经包含主仓库 push 成功后安全清理独立 change worktree 的逻辑。
 
 7) （可选）归档变更工件（完成交付后推荐）：
 ```bash

package/templates/workspace/.agents/skills/ws-handoff/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: ws-handoff
+description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
+- 指引在归档与依赖场景下如何使用 handoff
+
+说明：
+- `handoff.md` 由 `aiws change archive` 自动生成：`changes/archive/<date>-<change-id>/handoff.md`
+- `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
+
+执行建议：
+1) 先运行 `$ws-preflight`。
+2) 若本 change 已完成并准备归档：运行 `aiws change archive <change-id>`（会先做严格校验，并移动目录到 `changes/archive/`，同时生成 `handoff.md`）。
+3) 查看 handoff：
+```bash
+change_id="<change-id>"
+ls -1 changes/archive/*-"${change_id}"/handoff.md
+sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
+```
+4) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
+
+输出要求：
+- `Change_ID:` <change-id>
+- `Handoff:` `changes/archive/.../handoff.md`
+- `Next:` 若还有后续工作，建议创建新 change 并在其 `Depends_On` 引用本 change
+

package/templates/workspace/.agents/skills/ws-plan/SKILL.md

@@ -7,6 +7,7 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 
 目标：
 - 对齐真值文件（`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）
+- 若尚未进入本次 change 的工作上下文：先建立 `change/<change-id>` 分支 / worktree，再生成计划
 - 为当前任务生成一份可追踪的执行计划文件：`plan/<timestamp>-<slug>.md`
 - 计划必须包含可复现验证命令（优先引用 `AI_WORKSPACE.md`）
 - 计划必须包含“主索引绑定”：`Change_ID` / (`Req_ID` or `Problem_ID`) / `Contract_Row` / `Plan_File` / `Evidence_Path`
@@ -21,19 +22,53 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
 3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
-4) 识别主索引上下文（若存在）：
+4) 识别或建立主索引 / change 上下文：
    - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
    - 若缺失关键绑定：先补齐 proposal（至少 `Change_ID`、`Req_ID|Problem_ID`、`Contract_Row`）再继续生成计划
+   - 若当前不在 `change/<change-id>` 分支 / worktree，且本次任务需要新建 change：先调用 `aiws change start` 建立上下文，再继续写 plan
+   - 推荐顺序：
+     - 工作区已存在未提交改动：不要先写 `plan/...`；先停下来说明原因，并要求用户先 commit/stash，或改用已有 change 上下文
+     - 仓库已有提交：优先创建独立 worktree；若仓库声明了 submodules，加上 `--submodules`
+     - 仓库尚无提交 / 不满足 worktree 前置条件：回退为 `--no-switch`
+```bash
+change_id="<change-id>"
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree dirty before ws-plan creates change context"
+  echo "hint: commit/stash first, or continue inside an existing change/<change-id> context"
+  exit 2
+fi
+
+has_commits=0
+git rev-parse --verify HEAD >/dev/null 2>&1 && has_commits=1
+
+has_submodules=0
+if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+  has_submodules=1
+fi
+
+if [[ "${has_commits}" -eq 1 ]]; then
+  if [[ "${has_submodules}" -eq 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：后续所有读取/写入都必须切到 `aiws change start` 输出的 `worktree:` 路径中进行；不要把 `plan/...` 写回原工作区
 5) 生成计划文件：
    - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
    - 若 `plan/` 不存在先创建
    - 必须实际写入到磁盘（不要只在对话里输出）；如因权限/策略无法写盘，必须明确说明原因并输出可复制的完整内容
+   - 计划必须写在当前 active change 上下文内：若当前已进入 `change/<change-id>` worktree，则 `plan/...`、`proposal.md`、`tasks.md` 都应写在该 worktree 中
 6) 计划内容至少包含（不要留空）：
    - `Bindings`：`Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
    - `Goal`：要达成什么
    - `Non-goals`：明确不做什么（避免 scope creep）
    - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
+   - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
    - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
    - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
@@ -42,6 +77,38 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 9) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
 10) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
 
+补充：submodule 目标分支真值（强约束；同一 superproject 分支内可多渠道）
+- 背景：`.gitmodules submodule.<name>.branch` 适合作为“团队默认分支真值”，但当同一 superproject 分支需要在不同交付中选择不同 submodule 目标分支（多渠道）时，仅靠 `.gitmodules` 不足。
+- 强约束：当 `.gitmodules` 声明了 submodule 条目时，门禁会要求本次 change 存在该文件且覆盖所有 submodule path（否则 `aiws validate .` / `aiws change validate --strict` 阻断）。
+- 约定：为本次 change 落盘一个“交付目标分支映射”文件，并在后续 `$ws-dev`/`$ws-deliver`/`$ws-finish` 优先使用它：
+  - 文件：`changes/<change-id>/submodules.targets`
+  - 格式：每行一个 submodule（忽略空行与 `#` 注释），字段用空白分隔（推荐 `TAB`）：
+    - 第 1 列：submodule path（例如 `vendor/foo`）
+    - 第 2 列：target branch（例如 `release/channel-a`）
+    - 第 3 列（可选）：remote 名（默认 `origin`）
+- 生成模板（建议在确认 `Change_ID` 后执行；如文件已存在先备份再覆盖）：
+```bash
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
+mkdir -p "changes/${change_id}"
+if [[ -f "${targets}" ]]; then
+  bak="${targets}.bak.$(date -u +%Y%m%d-%H%M%SZ)"
+  cp "${targets}" "${bak}"
+  echo "info: backup: ${bak}"
+fi
+: > "${targets}"
+echo "# path<TAB>target_branch<TAB>remote(optional, default=origin)" >> "${targets}"
+while read -r key sub_path; do
+  name="${key#submodule.}"; name="${name%.path}"
+  b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+  [[ "${b:-}" == "." ]] && b="$(git branch --show-current)"  # '.' means "follow superproject branch"
+  printf "%s\t%s\t%s\n" "${sub_path}" "${b:-<fill-me>}" "origin" >> "${targets}"
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+echo "ok: wrote ${targets}"
+```
+- 计划里必须写清：本次交付选择的 `targets` 内容，以及后续在 `$ws-dev` 进入编码前会把 submodules 挂到 `aiws/pin/<target_branch>`（必要时先 `fetch`）。
+
 输出要求：
 - `Plan file:` <实际写入的路径>
+- `Change context:` <当前 change 分支或 worktree 路径；若新建了 worktree 需明确写出>
 - `Next:` 推荐下一步（先 `$ws-plan-verify`，通过后再 `$ws-dev`；或 `aiws change start <change-id> --hooks`，superproject + submodule 可用 `--worktree`）

package/templates/workspace/.agents/skills/ws-push/SKILL.md

@@ -60,6 +60,12 @@ fi
 4) 逐个 push submodules（fast-forward only），再 push superproject：
 ```bash
 base_branch="$(git branch --show-current)"
+change_id="$(echo "${base_branch}" | sed -n 's|^change/||p')"
+targets="changes/${change_id}/submodules.targets"
+# Note: if not on a change/ branch, change_id is empty and targets file won't exist;
+# resolution falls back to .gitmodules submodule.<name>.branch via ws_resolve_sub_target.
+
+source tools/ws_resolve_sub_target.sh
 
 git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
   | while read -r key sub_path; do
@@ -72,25 +78,25 @@ git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null
       exit 2
     fi
 
-    cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-    if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-    target_branch="${cfg_branch}"
+    ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
+    target_branch="${_resolved_branch}"
+    remote="${_resolved_remote}"
 
-    git -C "${sub_path}" fetch origin --prune
-    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-      echo "error: missing origin/${target_branch} for ${sub_path}"
+    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 ${sub_path}"
       exit 2
     fi
 
-    # fast-forward only: origin/<branch> 必须是 HEAD 的祖先
-    if ! git -C "${sub_path}" merge-base --is-ancestor "origin/${target_branch}" HEAD; then
-      echo "error: non-fast-forward (submodule=${sub_path}, branch=${target_branch})"
+    # fast-forward only: <remote>/<branch> 必须是 HEAD 的祖先
+    if ! git -C "${sub_path}" merge-base --is-ancestor "${remote}/${target_branch}" HEAD; then
+      echo "error: non-fast-forward (submodule=${sub_path}, remote=${remote}, branch=${target_branch})"
       echo "hint: rebase/merge in submodule, then retry"
       exit 2
     fi
 
-    # push HEAD -> origin/<branch>（不 force）
-    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
+    # push HEAD -> <remote>/<branch>（不 force）
+    git -C "${sub_path}" push "${remote}" "HEAD:refs/heads/${target_branch}"
   done
 
 # 最后 push superproject（仍需用户确认远端/分支）
@@ -102,4 +108,3 @@ git push
 - `Context:` 当前分支 + 是否有 submodules
 - `Submodules:` 每个 submodule push 的目标分支与结果（成功/阻断原因）
 - `Superproject:` push 结果
-

package/templates/workspace/.claude/commands/{aiws-change-archive.md → p-aiws-change-archive.md}

@@ -3,8 +3,10 @@
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
-- 归档已完成 change 工件
+- 归档已完成 change 工件，并生成交接文档：`changes/archive/.../handoff.md`
 
 执行（在仓库根目录）：
 ```bash

package/templates/workspace/.claude/commands/{aiws-change-finish.md → p-aiws-change-finish.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-finish -->
 # aiws change finish
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-list.md → p-aiws-change-list.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-list -->
 # aiws change list
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-new.md → p-aiws-change-new.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-new -->
 # aiws change new
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-next.md → p-aiws-change-next.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-next -->
 # aiws change next
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-start.md → p-aiws-change-start.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-start -->
 # aiws change start
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-status.md → p-aiws-change-status.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-status -->
 # aiws change status
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-sync.md → p-aiws-change-sync.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-sync -->
 # aiws change sync
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-templates-init.md → p-aiws-change-templates-init.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-templates-init -->
 # aiws change templates init
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-change-templates-which.md → p-aiws-change-templates-which.md}

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

package/templates/workspace/.claude/commands/{aiws-change-validate.md → p-aiws-change-validate.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-change-validate -->
 # aiws change validate
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-hooks-install.md → p-aiws-hooks-install.md}

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

package/templates/workspace/.claude/commands/{aiws-hooks-status.md → p-aiws-hooks-status.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-hooks-status -->
 # aiws hooks status
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：

package/templates/workspace/.claude/commands/{aiws-init.md → p-aiws-init.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-init -->
 # aiws init
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
 - 写入/更新 `.gitignore` 的 aiws 托管块
@@ -16,4 +18,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-init -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.claude/commands/{aiws-rollback.md → p-aiws-rollback.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-rollback -->
 # aiws rollback
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 从 `.aiws/backups/` 恢复到某次备份快照
 
@@ -9,4 +11,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-rollback -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.claude/commands/{aiws-update.md → p-aiws-update.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-update -->
 # aiws update
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
 - 更新前备份到 `.aiws/backups/<timestamp>/`
@@ -15,4 +17,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-update -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

package/templates/workspace/.claude/commands/{aiws-validate.md → p-aiws-validate.md}

@@ -1,6 +1,8 @@
 <!-- AIWS_MANAGED_BEGIN:claude:aiws-validate -->
 # aiws validate
 
+（私有原子入口；日常优先用 /ws-* 链路。）
+
 目标：
 - 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
 - 强门禁：缺 `python3`/缺 required 脚本也应失败
@@ -10,4 +12,3 @@
 <!-- AIWS_MANAGED_END:claude:aiws-validate -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

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

@@ -8,15 +8,20 @@
 
 建议流程：
 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。