@aipper/aiws-spec 0.0.12 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.12",
+  "version": "0.0.15",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

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

@@ -27,6 +27,26 @@ description: 交付（submodules + superproject 分步提交，并安全合并
 
 建议流程（按顺序）：
 
+## 0) submodule branch 真值检查（减少 detached 与人为差异）
+如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `$ws-submodule-setup` 并提交 `.gitmodules`，否则后续 `aiws validate .` 会失败，且 `ws-pull/ws-finish` 无法确定性工作。
+```bash
+if [[ -f .gitmodules ]]; then
+  missing=0
+  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)"
+    if [[ -z "${b:-}" ]]; then
+      echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+      missing=1
+    fi
+  done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+  if [[ "$missing" -ne 0 ]]; then
+    echo "hint: run $ws-submodule-setup (and commit .gitmodules), then retry"
+    exit 2
+  fi
+fi
+```
+
 ## A) 发现 submodules 清单（数量不固定）
 在 superproject 根目录执行：
 ```bash
@@ -43,7 +63,8 @@ git -C "$sub_path" branch --show-current
 git -C "$sub_path" status --porcelain
 ```
 2) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
-   - 默认建议：在该 submodule 内创建并切到同名 change 分支（与 superproject 对齐），例如 `change/<change-id>`：
+   - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
+   - 若你要在该 submodule 里提交：在 submodule 内创建并切到同名 change 分支（与 superproject 对齐），例如 `change/<change-id>`：
 ```bash
 git -C "$sub_path" switch -c "change/<change-id>"
 ```

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

@@ -15,8 +15,27 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
 - change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
 - 若使用 worktree：在“目标分支所在 worktree”执行（`aiws change finish` 会提示正确的 worktree）
+- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
 
 建议步骤：
+0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
+```bash
+if [[ -f .gitmodules ]]; then
+  missing=0
+  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)"
+    if [[ -z "${b:-}" ]]; then
+      echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+      missing=1
+    fi
+  done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+  if [[ "$missing" -ne 0 ]]; then
+    echo "hint: run $ws-submodule-setup (and commit .gitmodules), then retry"
+    exit 2
+  fi
+fi
+```
 1) （推荐）先跑一次门禁并落盘证据：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
@@ -49,39 +68,43 @@ base_branch="$(git branch --show-current)"
 git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true
 
 # 对每个 submodule.<name>.path <sub_path>：
-# 1) 计算 superproject 当前 HEAD 记录的 gitlink commit
+# 说明：`git submodule update` 会把 submodule checkout 到固定 gitlink commit，导致 detached HEAD。
+# 为减少“游离状态”的协作摩擦，本步骤采用“pin 分支”策略：
+# - 仅在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时执行（避免 origin 多分支导致误判）
+# - 不改动 submodule 现有分支指针（例如不强行移动 main/master）
+# - 创建/更新本地 pin 分支：`aiws/pin/<target_branch>` 指向 gitlink commit，并将其 upstream 设为 `origin/<target_branch>`
 sub_sha="$(git rev-parse "HEAD:<sub_path>")"
-# 2) 推断目标分支（优先：.gitmodules 的 submodule.<name>.branch；否则 origin/HEAD；否则 main/master）
 cfg_branch="$(git config --file .gitmodules --get "submodule.<name>.branch" 2>/dev/null || true)"
 if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-origin_head="$(git -C "<sub_path>" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || true)"
-target_branch="${cfg_branch:-${origin_head:-}}"
-if [[ -z "${target_branch:-}" ]]; then
-  if git -C "<sub_path>" show-ref --verify --quiet refs/heads/main || git -C "<sub_path>" show-ref --verify --quiet refs/remotes/origin/main; then
-    target_branch="main"
-  else
-    target_branch="master"
-  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}"
 
-# 3) 切到目标分支（若本地无分支则从 origin 跟踪创建）
-git -C "<sub_path>" fetch origin
-git -C "<sub_path>" switch "$target_branch" || git -C "<sub_path>" switch -c "$target_branch" --track "origin/$target_branch"
+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
 
-# 4) fast-forward 到 gitlink commit（非 ff 直接停止，避免错误合并）
-git -C "<sub_path>" status -sb
-if git -C "<sub_path>" merge-base --is-ancestor "$sub_sha" HEAD; then
-  echo "[skip] <sub_path> already contains $sub_sha"
-else
-  git -C "<sub_path>" merge --ff-only "$sub_sha"
+# 仅当 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
 
-# 5) push（若无 upstream 则首次 -u）
-git -C "<sub_path>" push || git -C "<sub_path>" push -u origin "$target_branch"
+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
+
+# push：只允许 fast-forward（若远端分叉会被拒绝；此时必须人工处理）
+git -C "<sub_path>" push origin "${sub_sha}:refs/heads/${target_branch}"
 ```
 规则：
-- 每个 submodule 必须先执行“切目标分支 + `merge --ff-only <gitlink-sha>`”，再 push；禁止在 detached HEAD 直接 push。
-- 若任一 submodule 不能 fast-forward（`merge --ff-only` 失败），立即停止，先人工处理冲突/分叉，再继续。
+- 每个 submodule 必须先执行“pin 分支挂回 + fast-forward push”，再 push 主仓库。
+- 若任一 submodule 的 gitlink commit 不在 `origin/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
 
 5) 仅当 submodules 全部成功后，再 push superproject 当前分支：
 ```bash

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

@@ -23,6 +23,9 @@ description: 预检（提交前快速检查与建议）
    - `Found:` <实际读取到的文件列表>
    - `Missing:` <缺失文件列表>
    - `Key rules:` 3–8 条 bullet（范围/禁止项/必须产物/必须验证命令）
+5) 若存在 `.gitmodules`：
+   - 输出 submodule 列表：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+   - 检查每个 submodule 是否配置 `submodule.<name>.branch`（缺失则提示先运行 `$ws-submodule-setup`；否则 `aiws validate .` 会失败）
 
 安全：
 - 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。

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

@@ -13,7 +13,7 @@ description: 拉取并对齐 submodules（避免 detached；减少人为差异
 - 安全拉取 superproject（默认只允许 fast-forward）
 - 初始化/同步 submodules（`--init --recursive`）
 - 在**不改动 superproject gitlink commit** 的前提下，尽量把每个 submodule 从 detached HEAD “挂回”到一个**确定的目标分支**（仅当该分支包含 gitlink commit 时）
-- 若需要长期稳定地“挂回分支”，给出一次性 `.gitmodules` branch 配置建议（方案 2）
+- 若未配置 `.gitmodules` 的 `submodule.<name>.branch`：保持 detached，并提示先运行 `$ws-submodule-setup`
 
 安全约束（强制）：
 - 不执行破坏性命令（不 `reset --hard` 主仓库；不改动远端）
@@ -50,7 +50,7 @@ fi
 说明：
 - 该步骤不会改变 superproject 的 gitlink commit（也不会让主仓库出现“submodule modified”）。
 - 只在目标分支包含该 gitlink commit 时才执行“挂回”；否则保持 detached 并提示原因。
-- 为了避免 origin 分支较多时“猜错分支”，本步骤**只在** `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行“挂回分支”；否则保持 detached 并提示先对齐配置（见步骤 4）。
+- 为了避免 origin 分支较多时“猜错分支”，本步骤**只在** `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行“挂回分支”；否则保持 detached 并提示先运行 `$ws-submodule-setup` 对齐配置。
 
 ```bash
 if [[ -f .gitmodules ]]; then
@@ -71,7 +71,7 @@ if [[ -f .gitmodules ]]; then
       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 (run step 4 to set it)"
+        echo "[warn] ${sub_path}: missing .gitmodules submodule.${name}.branch; keep detached (run ws-submodule-setup to set it)"
         continue
       fi
 
@@ -112,6 +112,7 @@ git commit -m "chore(submodule): set tracking branch"
 建议：
 - 只有当团队明确希望“子模块按分支滚动”（而不是锁定固定 commit）时，才采用方案 2。
 - 若只是想避免 detached 但仍锁定 gitlink commit：优先使用步骤 3（不改 `.gitmodules`）。
+- 推荐用 `$ws-submodule-setup` 交互式对齐所有 submodules 的 branch，并提交 `.gitmodules`。
 
 输出要求：
 - `Context:` 当前分支 + 是否存在 `.gitmodules` + submodule 列表

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

@@ -0,0 +1,105 @@
+---
+name: ws-push
+description: 推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在不自动提交的前提下，安全 push 当前仓库
+- 若仓库包含 submodules：按 `submodules -> superproject` 顺序 push，减少“别人拉取后子模块 detached/分叉”的协作摩擦
+- 若不包含 submodules：按普通 git 仓库的规则 push
+
+安全约束（强制）：
+- 不自动提交、不自动 `git add -A`
+- 不使用 `--force` / `--force-with-lease`
+- 默认只允许 fast-forward push（发现分叉则停止并提示人工处理）
+- 若工作区不干净：停止并要求先 commit 或 stash
+
+执行步骤（建议）：
+0) 输出上下文：
+```bash
+git branch --show-current
+git status --porcelain
+git status -sb
+```
+若 `git status --porcelain` 非空：停止。
+
+1) 判断是否存在 submodules：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+else
+  echo "[info] no .gitmodules"
+fi
+```
+
+2) 若不存在 `.gitmodules` 或没有 submodule 条目：按普通仓库 push（仍需用户确认）：
+```bash
+git remote -v
+git push
+```
+
+3) 若存在 submodules：先检查 `.gitmodules` 的 branch 真值是否齐全（缺失则停止并提示 setup）：
+```bash
+missing=0
+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)"
+  if [[ -z "${b:-}" ]]; then
+    echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+    missing=1
+  fi
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+if [[ "$missing" -ne 0 ]]; then
+  echo "hint: run $ws-submodule-setup (and commit .gitmodules), then retry"
+  exit 2
+fi
+```
+
+4) 逐个 push submodules（fast-forward only），再 push superproject：
+```bash
+base_branch="$(git branch --show-current)"
+
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
+  | while read -r key sub_path; do
+    name="${key#submodule.}"; name="${name%.path}"
+    echo "== submodule: ${sub_path} (${name}) =="
+
+    # submodule 工作区必须干净
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
+      echo "error: submodule dirty: ${sub_path}"
+      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}"
+
+    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}"
+      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})"
+      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}"
+  done
+
+# 最后 push superproject（仍需用户确认远端/分支）
+git remote -v
+git push
+```
+
+输出要求：
+- `Context:` 当前分支 + 是否有 submodules
+- `Submodules:` 每个 submodule push 的目标分支与结果（成功/阻断原因）
+- `Superproject:` push 结果
+

package/templates/workspace/.agents/skills/ws-submodule-setup/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ws-submodule-setup
+description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch；减少 detached 与人为差异）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`，让 `ws-pull` / `ws-finish` 能确定性地“挂回分支/fast-forward push”，避免 origin 多分支时靠猜导致偏差。
+- 该变更是 **superproject 的团队真值**：需要提交 `.gitmodules`。
+
+安全约束（强制）：
+- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
+- 不在 submodule 中做破坏性操作（不 `reset --hard` / 不改动远端）
+
+步骤（建议）：
+1) 确认工作区干净（否则停止）：
+```bash
+git status --porcelain
+```
+
+2) 列出 submodules（没有则停止并说明无需配置）：
+```bash
+test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
+```
+
+3) 对每个 submodule，输出当前配置与建议分支（让用户确认每个 submodule 的 branch）：
+```bash
+while read -r key sub_path; do
+  name="${key#submodule.}"; name="${name%.path}"
+  echo "== submodule: ${name} path=${sub_path} =="
+  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
+  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+  git -C "${sub_path}" branch -r --list "origin/*" | sed -n '1,30p' || true
+  echo "[choose] set one of:"
+  echo "  - a concrete branch, e.g. main / master / release/x.y"
+  echo "  - '.' to follow superproject current branch name (only if your team uses matching branch names)"
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
+```
+
+4) 逐个写入分支配置（每次写完都回显，避免误配）：
+```bash
+# Example:
+# git submodule set-branch --branch main path/to/submodule
+# git submodule set-branch --branch .    path/to/submodule
+```
+
+5) 输出变更并让用户确认是否提交：
+```bash
+git diff -- .gitmodules
+git status --porcelain
+```
+
+6) 若用户确认要提交：
+```bash
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branches"
+```
+
+输出要求：
+- `Submodules:` name/path + 选择的 branch（每个都列出）
+- `Diff:` `.gitmodules` 的 diff（或至少 `git diff -- .gitmodules` 的摘要）
+- `Next:` 提示后续用 `$ws-pull` 拉取可自动减少 detached；`aiws validate` 会检查该配置是否齐全
+

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

@@ -15,6 +15,7 @@
 
 建议流程（按顺序）：
 1) 先运行 `/ws-preflight`。
+2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `/ws-submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
 2) 发现 submodules：
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
@@ -42,4 +43,3 @@
 <!-- AIWS_MANAGED_END:claude:ws-deliver -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
-

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

@@ -9,23 +9,42 @@
 前置（必须）：
 - 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
 - change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+ - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
 
 步骤（建议）：
+0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
+```bash
+if [[ -f .gitmodules ]]; then
+  missing=0
+  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)"
+    if [[ -z "${b:-}" ]]; then
+      echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+      missing=1
+    fi
+  done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+  if [[ "$missing" -ne 0 ]]; then
+    echo "hint: run /ws-submodule-setup (and commit .gitmodules), then retry"
+    exit 2
+  fi
+fi
+```
 1) 先运行 `/ws-preflight`（确保真值文件齐全）。
 2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 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（先“并回目标分支”，再 push）：
+5) 合并成功后，按顺序处理每个 submodule（减少 detached；再 push）：
    - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
-     - 推断目标分支：优先 `.gitmodules` 的 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支），否则 `origin/HEAD`，再 fallback `main/master`
-     - 切到目标分支（必要时创建跟踪分支）：`git -C "<sub_path>" switch <target-branch> || git -C "<sub_path>" switch -c <target-branch> --track origin/<target-branch>`
-     - 合并 gitlink commit：`git -C "<sub_path>" merge --ff-only <gitlink-sha>`
-     - push：`git -C "<sub_path>" push`（无 upstream 则 `git -C "<sub_path>" push -u origin <target-branch>`）
-6) 任一 submodule `merge --ff-only` 失败时立即停止（不要继续 push 主仓库）。
+     - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
+     - 用 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`

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

@@ -36,7 +36,7 @@ fi
 ```
 
 4) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”（不改动 gitlink commit）：
-为避免 origin 多分支时“猜错分支”，本步骤只在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行；否则保持 detached 并提示先对齐配置。
+为避免 origin 多分支时“猜错分支”，本步骤只在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行；否则保持 detached 并提示先运行 `/ws-submodule-setup` 对齐配置。
 ```bash
 if [[ -f .gitmodules ]]; then
   base_branch="$(git branch --show-current)"
@@ -51,7 +51,7 @@ if [[ -f .gitmodules ]]; then
       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"
+        echo "[warn] ${sub_path}: missing .gitmodules submodule.${name}.branch; keep detached (run ws-submodule-setup)"
         continue
       fi
       target_branch="${cfg_branch}"

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

@@ -0,0 +1,90 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-push -->
+# ws push
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全 push 当前仓库；若仓库包含 submodules，则先 push submodules，再 push superproject（默认 fast-forward；不 force）。
+
+强制约束：
+- 不自动提交、不自动 `git add -A`
+- 不使用 `--force` / `--force-with-lease`
+- 若工作区不干净：停止并要求先 commit 或 stash
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+```bash
+git branch --show-current
+git status --porcelain
+git status -sb
+```
+若 `git status --porcelain` 非空：停止。
+
+2) 判断是否存在 submodules：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+fi
+```
+
+3) 若没有 submodules：正常 push（仍需用户确认远端/分支）：
+```bash
+git remote -v
+git push
+```
+
+4) 若有 submodules：先检查 `.gitmodules` 的 `submodule.<name>.branch` 是否齐全（缺失则停止并提示 `/ws-submodule-setup`）：
+```bash
+missing=0
+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)"
+  if [[ -z "${b:-}" ]]; then
+    echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+    missing=1
+  fi
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+if [[ "$missing" -ne 0 ]]; then
+  echo "hint: run /ws-submodule-setup (and commit .gitmodules), then retry"
+  exit 2
+fi
+```
+
+5) 逐个 push submodules（fast-forward only），再 push superproject：
+```bash
+base_branch="$(git branch --show-current)"
+
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
+  | while read -r key sub_path; do
+    name="${key#submodule.}"; name="${name%.path}"
+    echo "== submodule: ${sub_path} (${name}) =="
+
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
+      echo "error: submodule dirty: ${sub_path}"
+      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}"
+
+    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}"
+      exit 2
+    fi
+
+    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})"
+      exit 2
+    fi
+
+    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
+  done
+
+git remote -v
+git push
+```
+<!-- AIWS_MANAGED_END:claude:ws-push -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/.claude/commands/ws-submodule-setup.md

@@ -0,0 +1,54 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-submodule-setup -->
+# ws submodule setup
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`（团队真值），让 `/ws-pull`、`/ws-finish` 能确定性地减少 detached 与人为差异；并使 `aiws validate` 的 submodule 分支门禁通过。
+
+约束：
+- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
+- 不做破坏性命令
+
+步骤（建议）：
+1) 确认工作区干净：
+```bash
+git status --porcelain
+```
+非空则停止。
+
+2) 列出 submodules：
+```bash
+test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
+```
+
+3) 对每个 submodule 让用户选择目标分支（推荐具体分支名；可选 `.` 表示跟随 superproject 分支名）：
+```bash
+while read -r key sub_path; do
+  name="${key#submodule.}"; name="${name%.path}"
+  echo "== submodule: ${name} path=${sub_path} =="
+  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
+  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
+```
+
+4) 写入分支配置：
+```bash
+git submodule set-branch --branch <branch-or-dot> <sub_path>
+```
+
+5) 输出 diff 并让用户确认是否提交：
+```bash
+git diff -- .gitmodules
+git status --porcelain
+```
+
+6) 用户确认后提交：
+```bash
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branches"
+```
+<!-- AIWS_MANAGED_END:claude:ws-submodule-setup -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
+

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

@@ -20,6 +20,7 @@ prompt = """
 
 建议流程（按顺序）：
 1) 先确认真值文件存在并遵守：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `ws:submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
 2) 发现 submodules：
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
@@ -45,4 +46,3 @@ prompt = """
 - `Merge:` `ws:finish`/`aiws change finish` 输出（into/from）
 - `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
 """
-

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

@@ -18,6 +18,7 @@ prompt = """
    - `git status --porcelain`
    - `git branch --show-current`（或 `git rev-parse --abbrev-ref HEAD`）
 4) 若工作区不干净：停止，并要求先 commit 或 stash（不要尝试自动处理）。
+4.1) 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `ws:submodule-setup` 并提交 `.gitmodules`）。
 5) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 6) 安全合并（默认 fast-forward）：
    - 在 `change/<change-id>` 分支上：`aiws change finish`（会尝试读 `changes/<change-id>/.ws-change.json` 的 `base_branch` 并切回目标分支）
@@ -27,11 +28,11 @@ prompt = """
    - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
-     - 推断目标分支：优先 `.gitmodules` 的 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支），否则 `origin/HEAD`，再 fallback `main/master`
-     - 切到目标分支（必要时创建跟踪分支）：`git -C "<sub_path>" switch <target-branch> || git -C "<sub_path>" switch -c <target-branch> --track origin/<target-branch>`
-     - 合并 gitlink commit：`git -C "<sub_path>" merge --ff-only <gitlink-sha>`
-     - push：`git -C "<sub_path>" push`（无 upstream 则 `git -C "<sub_path>" push -u origin <target-branch>`）
-9) 任一 submodule `merge --ff-only` 失败时立即停止（不要继续 push 主仓库）。
+     - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
+     - 用 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`

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

@@ -43,4 +43,5 @@ prompt = """
 可选（方案 2，一次性设置 submodule 跟踪分支，会改 `.gitmodules`，需提交）：
 - `git submodule set-branch --branch main <sub_path>`
 - `git add .gitmodules && git commit -m "chore(submodule): set tracking branch"`
+推荐：优先使用 `ws:submodule-setup` 交互式对齐所有 submodules 的 branch，并提交 `.gitmodules`。
 """

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

@@ -0,0 +1,40 @@
+# Command: ws:push
+# Description: 推送（submodule 感知：先 submodules 后 superproject；fast-forward；不 force）
+# Category: workspace
+# Version: 1
+
+description = "推送（submodule 感知：先 submodules 后 superproject；fast-forward；不 force）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全 push 当前仓库；若仓库包含 submodules，则先 push submodules，再 push superproject（默认 fast-forward；不 force）。
+
+约束：
+- 不自动提交、不自动 `git add -A`
+- 不使用 `--force` / `--force-with-lease`
+- 若工作区不干净：停止并要求先 commit 或 stash
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+   - `git branch --show-current`
+   - `git status --porcelain`
+   - `git status -sb`
+   - 非空则停止。
+
+2) 判断是否存在 submodules：若存在 `.gitmodules`，输出 submodule 列表：
+   - `git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+
+3) 若没有 submodules：正常 push（仍需用户确认远端/分支）：
+   - `git remote -v`
+   - `git push`
+
+4) 若有 submodules：先检查 `.gitmodules` 的 `submodule.<name>.branch` 是否齐全（缺失则停止并提示 `ws:submodule-setup`）。
+
+5) 逐个 push submodules（fast-forward only），再 push superproject：
+   - `git -C "<sub_path>" fetch origin --prune`
+   - 若 `origin/<target_branch>` 不是 `HEAD` 的祖先：停止并提示先在 submodule 做 rebase/merge
+   - `git -C "<sub_path>" push origin "HEAD:refs/heads/<target_branch>"`
+   - 最后 `git push`
+"""
+

package/templates/workspace/.iflow/commands/ws-submodule-setup.toml

@@ -0,0 +1,32 @@
+# Command: ws:submodule-setup
+# Description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch）
+# Category: workspace
+# Version: 1
+
+description = "子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`（团队真值），让 `ws:pull`、`ws:finish` 能确定性地减少 detached 与人为差异；并使 `aiws validate` 的 submodule 分支门禁通过。
+
+约束：
+- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
+- 不做破坏性命令
+
+步骤（建议）：
+1) 确认工作区干净：`git status --porcelain`（非空则停止）。
+2) 列出 submodules：
+   - `test -f .gitmodules || { echo "no .gitmodules"; exit 0; }`
+   - `git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
+3) 对每个 submodule 让用户选择目标分支（推荐具体分支名；可选 `.` 表示跟随 superproject 分支名）。
+4) 写入分支配置：
+   - `git submodule set-branch --branch <branch-or-dot> <sub_path>`
+5) 输出 diff 并让用户确认是否提交：
+   - `git diff -- .gitmodules`
+   - `git status --porcelain`
+6) 用户确认后提交：
+   - `git add .gitmodules`
+   - `git commit -m "chore(submodule): set tracking branches"`
+"""
+

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

@@ -18,6 +18,7 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 
 建议流程（按顺序）：
 1) 先运行 `/ws-preflight`。
+2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `/ws-submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
 2) 发现 submodules：
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：

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

@@ -12,23 +12,42 @@ description: 收尾：fast-forward 合并并把 submodule 并回目标分支后
 前置（必须）：
 - 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
 - change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+ - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
 
 步骤（建议）：
+0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
+```bash
+if [[ -f .gitmodules ]]; then
+  missing=0
+  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)"
+    if [[ -z "${b:-}" ]]; then
+      echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+      missing=1
+    fi
+  done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+  if [[ "$missing" -ne 0 ]]; then
+    echo "hint: run /ws-submodule-setup (and commit .gitmodules), then retry"
+    exit 2
+  fi
+fi
+```
 1) 先运行 `/ws-preflight`（确保真值文件齐全）。
 2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 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（先“并回目标分支”，再 push）：
+5) 合并成功后，按顺序处理每个 submodule（减少 detached；再 push）：
    - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
-     - 推断目标分支：优先 `.gitmodules` 的 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支），否则 `origin/HEAD`，再 fallback `main/master`
-     - 切到目标分支（必要时创建跟踪分支）：`git -C "<sub_path>" switch <target-branch> || git -C "<sub_path>" switch -c <target-branch> --track origin/<target-branch>`
-     - 合并 gitlink commit：`git -C "<sub_path>" merge --ff-only <gitlink-sha>`
-     - push：`git -C "<sub_path>" push`（无 upstream 则 `git -C "<sub_path>" push -u origin <target-branch>`）
-6) 任一 submodule `merge --ff-only` 失败时立即停止（不要继续 push 主仓库）。
+     - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
+     - 用 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`

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

@@ -39,7 +39,7 @@ fi
 ```
 
 4) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”（不改动 gitlink commit）：
-为避免 origin 多分支时“猜错分支”，本步骤只在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行；否则保持 detached 并提示先对齐配置。
+为避免 origin 多分支时“猜错分支”，本步骤只在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行；否则保持 detached 并提示先运行 `/ws-submodule-setup` 对齐配置。
 ```bash
 if [[ -f .gitmodules ]]; then
   base_branch="$(git branch --show-current)"
@@ -54,7 +54,7 @@ if [[ -f .gitmodules ]]; then
       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"
+        echo "[warn] ${sub_path}: missing .gitmodules submodule.${name}.branch; keep detached (run ws-submodule-setup)"
         continue
       fi
       target_branch="${cfg_branch}"

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

@@ -0,0 +1,93 @@
+---
+description: 推送：submodule 感知（先 submodules 后 superproject；fast-forward；不 force）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-push -->
+# ws push
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全 push 当前仓库；若仓库包含 submodules，则先 push submodules，再 push superproject（默认 fast-forward；不 force）。
+
+强制约束：
+- 不自动提交、不自动 `git add -A`
+- 不使用 `--force` / `--force-with-lease`
+- 若工作区不干净：停止并要求先 commit 或 stash
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+```bash
+git branch --show-current
+git status --porcelain
+git status -sb
+```
+若 `git status --porcelain` 非空：停止。
+
+2) 判断是否存在 submodules：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+fi
+```
+
+3) 若没有 submodules：正常 push（仍需用户确认远端/分支）：
+```bash
+git remote -v
+git push
+```
+
+4) 若有 submodules：先检查 `.gitmodules` 的 `submodule.<name>.branch` 是否齐全（缺失则停止并提示 `/ws-submodule-setup`）：
+```bash
+missing=0
+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)"
+  if [[ -z "${b:-}" ]]; then
+    echo "error: missing .gitmodules submodule.${name}.branch (path=${sub_path})"
+    missing=1
+  fi
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+if [[ "$missing" -ne 0 ]]; then
+  echo "hint: run /ws-submodule-setup (and commit .gitmodules), then retry"
+  exit 2
+fi
+```
+
+5) 逐个 push submodules（fast-forward only），再 push superproject：
+```bash
+base_branch="$(git branch --show-current)"
+
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
+  | while read -r key sub_path; do
+    name="${key#submodule.}"; name="${name%.path}"
+    echo "== submodule: ${sub_path} (${name}) =="
+
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
+      echo "error: submodule dirty: ${sub_path}"
+      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}"
+
+    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}"
+      exit 2
+    fi
+
+    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})"
+      exit 2
+    fi
+
+    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
+  done
+
+git remote -v
+git push
+```
+<!-- AIWS_MANAGED_END:opencode:ws-push -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/.opencode/command/ws-submodule-setup.md

@@ -0,0 +1,57 @@
+---
+description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-submodule-setup -->
+# ws submodule setup
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`（团队真值），让 `/ws-pull`、`/ws-finish` 能确定性地减少 detached 与人为差异；并使 `aiws validate` 的 submodule 分支门禁通过。
+
+约束：
+- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
+- 不做破坏性命令
+
+步骤（建议）：
+1) 确认工作区干净：
+```bash
+git status --porcelain
+```
+非空则停止。
+
+2) 列出 submodules：
+```bash
+test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
+```
+
+3) 对每个 submodule 让用户选择目标分支（推荐具体分支名；可选 `.` 表示跟随 superproject 分支名）：
+```bash
+while read -r key sub_path; do
+  name="${key#submodule.}"; name="${name%.path}"
+  echo "== submodule: ${name} path=${sub_path} =="
+  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
+  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
+```
+
+4) 写入分支配置：
+```bash
+git submodule set-branch --branch <branch-or-dot> <sub_path>
+```
+
+5) 输出 diff 并让用户确认是否提交：
+```bash
+git diff -- .gitmodules
+git status --porcelain
+```
+
+6) 用户确认后提交：
+```bash
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branches"
+```
+<!-- AIWS_MANAGED_END:opencode:ws-submodule-setup -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/AGENTS.md

@@ -10,7 +10,7 @@
 - 启用本机门禁（推荐）：`aiws hooks install .`（或手工：`git config core.hooksPath .githooks`；`git commit`/`git push` 会自动跑 `aiws validate .`）
 - 提交前校验（强制门禁）：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - Codex（推荐）：本仓库内置 repo skills：`.agents/skills/`（可显式 `$ws-dev`，也可隐式套用工作流）
-- Codex skills（常用）：`$ws-preflight` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-pull` / `$ws-review` / `$ws-commit` / `$aiws-init` / `$aiws-validate` / `$aiws-hooks-install` / `$aiws-change-new`
+- Codex skills（常用）：`$ws-preflight` / `$ws-submodule-setup` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-pull` / `$ws-push` / `$ws-review` / `$ws-commit` / `$aiws-init` / `$aiws-validate` / `$aiws-hooks-install` / `$aiws-change-new`
 - Codex CLI（推荐，可选）：安装全局 skills：`npx @aipper/aiws codex install-skills`（写入 `~/.codex/skills/` 或 `$CODEX_HOME/skills`）
 - Codex CLI（遗留，可选）：安装全局 prompts：`npx @aipper/aiws codex install-prompts`（写入 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`；prompts 已 deprecated）
 - 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等

package/templates/workspace/manifest.json

@@ -31,7 +31,9 @@
     ".claude/commands/ws-deliver.md",
     ".claude/commands/ws-analyze.md",
     ".claude/commands/ws-pull.md",
+    ".claude/commands/ws-push.md",
     ".claude/commands/ws-finish.md",
+    ".claude/commands/ws-submodule-setup.md",
     ".claude/commands/ws-review.md",
     ".claude/commands/ws-commit.md",
     ".claude/commands/ws-rule.md",
@@ -50,7 +52,9 @@
     ".opencode/command/ws-deliver.md",
     ".opencode/command/ws-analyze.md",
     ".opencode/command/ws-pull.md",
+    ".opencode/command/ws-push.md",
     ".opencode/command/ws-finish.md",
+    ".opencode/command/ws-submodule-setup.md",
     ".opencode/command/ws-review.md",
     ".opencode/command/ws-commit.md",
     ".opencode/command/ws-rule.md",
@@ -78,7 +82,9 @@
     ".iflow/commands/ws-analyze.toml",
     ".iflow/commands/ws-deliver.toml",
     ".iflow/commands/ws-pull.toml",
+    ".iflow/commands/ws-push.toml",
     ".iflow/commands/ws-finish.toml",
+    ".iflow/commands/ws-submodule-setup.toml",
     ".iflow/commands/ws-review.toml",
     ".iflow/commands/ws-commit.toml",
     ".iflow/commands/ws-rule.toml",
@@ -141,6 +147,8 @@
       ".agents/skills/ws-plan/SKILL.md",
       ".agents/skills/ws-plan-verify/SKILL.md",
       ".agents/skills/ws-pull/SKILL.md",
+      ".agents/skills/ws-push/SKILL.md",
+      ".agents/skills/ws-submodule-setup/SKILL.md",
       ".agents/skills/ws-preflight/SKILL.md",
       ".agents/skills/ws-req-change/SKILL.md",
       ".agents/skills/ws-req-contract-sync/SKILL.md",
@@ -168,7 +176,9 @@
       ".iflow/commands/ws-analyze.toml",
       ".iflow/commands/ws-deliver.toml",
       ".iflow/commands/ws-pull.toml",
+      ".iflow/commands/ws-push.toml",
       ".iflow/commands/ws-finish.toml",
+      ".iflow/commands/ws-submodule-setup.toml",
       ".iflow/commands/ws-review.toml",
       ".iflow/commands/ws-commit.toml",
       ".iflow/commands/ws-rule.toml",
@@ -201,7 +211,9 @@
       ".claude/commands/ws-deliver.md": ["claude:ws-deliver"],
       ".claude/commands/ws-analyze.md": ["claude:ws-analyze"],
       ".claude/commands/ws-pull.md": ["claude:ws-pull"],
+      ".claude/commands/ws-push.md": ["claude:ws-push"],
       ".claude/commands/ws-finish.md": ["claude:ws-finish"],
+      ".claude/commands/ws-submodule-setup.md": ["claude:ws-submodule-setup"],
       ".claude/commands/ws-review.md": ["claude:ws-review"],
       ".claude/commands/ws-commit.md": ["claude:ws-commit"],
       ".claude/commands/ws-rule.md": ["claude:ws-rule"],
@@ -220,7 +232,9 @@
       ".opencode/command/ws-deliver.md": ["opencode:ws-deliver"],
       ".opencode/command/ws-analyze.md": ["opencode:ws-analyze"],
       ".opencode/command/ws-pull.md": ["opencode:ws-pull"],
+      ".opencode/command/ws-push.md": ["opencode:ws-push"],
       ".opencode/command/ws-finish.md": ["opencode:ws-finish"],
+      ".opencode/command/ws-submodule-setup.md": ["opencode:ws-submodule-setup"],
       ".opencode/command/ws-review.md": ["opencode:ws-review"],
       ".opencode/command/ws-commit.md": ["opencode:ws-commit"],
       ".opencode/command/ws-rule.md": ["opencode:ws-rule"],