@aipper/aiws-spec 0.0.27 → 0.0.29

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

@@ -1,54 +0,0 @@
----
-name: ws-migrate
-description: 迁移（补齐/升级 AIWS 工作区文件）
----
-
-用中文输出；命令与路径保持原样不翻译。
-
-目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
-
-执行（在项目根目录）：
-```bash
-if [[ -f ".aiws/manifest.json" ]]; then
-  if [[ -x "./node_modules/.bin/aiws" ]]; then
-    ./node_modules/.bin/aiws update .
-  elif command -v aiws >/dev/null 2>&1; then
-    aiws update .
-  else
-    npx @aipper/aiws update .
-  fi
-else
-  if [[ -x "./node_modules/.bin/aiws" ]]; then
-    ./node_modules/.bin/aiws init .
-  elif command -v aiws >/dev/null 2>&1; then
-    aiws init .
-  else
-    npx @aipper/aiws init .
-  fi
-fi
-
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate .
-elif command -v aiws >/dev/null 2>&1; then
-  aiws validate .
-else
-  npx @aipper/aiws validate .
-fi
-
-git config core.hooksPath .githooks
-```
-
-回滚（恢复最近一次快照）：
-```bash
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws rollback . latest
-elif command -v aiws >/dev/null 2>&1; then
-  aiws rollback . latest
-else
-  npx @aipper/aiws rollback . latest
-fi
-```
-
-约束：
-- 不写入任何 secrets。
-- 不执行破坏性命令。

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

@@ -1,119 +0,0 @@
----
-name: ws-pull
-description: 拉取并对齐 submodules（避免 detached；减少人为差异）
----
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-背景：
-- Git submodule 在别的电脑 `git submodule update` 后常见现象是子模块处于 detached HEAD（因为主仓库记录的是固定 gitlink commit）。
-- detached 本身不一定是错，但会增加“需要手动切分支/容易忘”的操作差异。
-
-目标：
-- 安全拉取 superproject（默认只允许 fast-forward）
-- 初始化/同步 submodules（`--init --recursive`）
-- 在**不改动 superproject gitlink commit** 的前提下，尽量把每个 submodule 从 detached HEAD “挂回”到一个**确定的目标分支**（仅当该分支包含 gitlink commit 时）
-- 若未配置 `.gitmodules` 的 `submodule.<name>.branch`：保持 detached，并提示先运行 `$ws-submodule-setup`
-
-安全约束（强制）：
-- 不执行破坏性命令（不 `reset --hard` 主仓库；不改动远端）
-- 不自动提交/不自动 push
-- 若工作区不干净：停止并要求用户先 commit 或 stash（不要自动处理）
-
-执行步骤（建议）：
-0) 输出上下文：
-```bash
-git rev-parse --show-toplevel
-git branch --show-current
-git status --porcelain
-```
-若 `git status --porcelain` 非空：停止，要求用户先清理工作区（commit 或 stash）。
-
-1) 拉取 superproject（默认只允许 fast-forward，避免隐式 merge/rebase）：
-```bash
-git pull --ff-only
-```
-若失败（需要 merge/rebase）：停止并向用户解释原因，让用户明确选择 `git pull --rebase` 或手动处理。
-
-2) 同步并更新 submodules 到 superproject 记录的 gitlink commit：
-```bash
-if [[ -f .gitmodules ]]; then
-  git submodule sync --recursive
-  git submodule update --init --recursive
-else
-  echo "[info] no .gitmodules"
-fi
-```
-
-3) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”，减少手工操作差异：
-
-说明：
-- 该步骤不会改变 superproject 的 gitlink commit（也不会让主仓库出现“submodule modified”）。
-- 只在目标分支包含该 gitlink commit 时才执行“挂回”；否则保持 detached 并提示原因。
-- 为了避免 origin 分支较多时“猜错分支”，本步骤**只在** `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行“挂回分支”；否则保持 detached 并提示先运行 `$ws-submodule-setup` 对齐配置。
-
-```bash
-if [[ -f .gitmodules ]]; then
-  base_branch="$(git branch --show-current)"
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-    | while read -r key sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      name="${key#submodule.}"
-      name="${name%.path}"
-      echo "== submodule: ${sub_path} (${name}) =="
-
-      sub_sha="$(git rev-parse "HEAD:${sub_path}" 2>/dev/null || true)"
-      if [[ -z "${sub_sha:-}" ]]; then
-        echo "[warn] failed to read gitlink sha for ${sub_path}"
-        continue
-      fi
-
-      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 ws-submodule-setup to set it)"
-        continue
-      fi
-
-      target_branch="${cfg_branch}"
-      pin_branch="aiws/pin/${target_branch}"
-
-      git -C "${sub_path}" fetch origin --prune || true
-
-      if git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-        if git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-          # 不改动现有分支（避免把已有 main/master 等分支强行指回旧 commit）
-          # 仅创建/更新一个 AIWS 专用 pin 分支指向 gitlink commit，从 detached “挂回分支”。
-          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
-          echo "[ok] attached ${sub_path} to ${pin_branch} (upstream=origin/${target_branch}) at ${sub_sha}"
-        else
-          echo "[warn] ${sub_path}: ${sub_sha} is not in origin/${target_branch}; keep detached"
-        fi
-      else
-        echo "[warn] ${sub_path}: origin/${target_branch} not found; keep detached"
-      fi
-
-      git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
-      git -C "${sub_path}" status -sb || true
-    done
-fi
-```
-
-4) 一次性配置（方案 2）：为每个 submodule 写入跟踪分支，便于团队统一（需要用户确认，会改动 `.gitmodules`）：
-```bash
-# 示例：把某个 submodule 固定跟踪 main（会写入 .gitmodules 的 submodule.<name>.branch）
-git submodule set-branch --branch main <sub_path>
-
-# 提示：该变更需要提交到 superproject
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branch"
-```
-建议：
-- 只有当团队明确希望“子模块按分支滚动”（而不是锁定固定 commit）时，才采用方案 2。
-- 若只是想避免 detached 但仍锁定 gitlink commit：优先使用步骤 3（不改 `.gitmodules`）。
-- 推荐用 `$ws-submodule-setup` 交互式对齐所有 submodules 的 branch，并提交 `.gitmodules`。
-
-输出要求：
-- `Context:` 当前分支 + 是否存在 `.gitmodules` + submodule 列表
-- `Result:` pull 是否 fast-forward；每个 submodule 是否成功“挂回分支”，失败原因是什么

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

@@ -1,110 +0,0 @@
----
-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)"
-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
-    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
-
-    ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
-    target_branch="${_resolved_branch}"
-    remote="${_resolved_remote}"
-
-    git -C "${sub_path}" fetch "${remote}" --prune
-    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
-      echo "error: missing ${remote}/${target_branch} for ${sub_path}"
-      exit 2
-    fi
-
-    # 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 -> <remote>/<branch>（不 force）
-    git -C "${sub_path}" push "${remote}" "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

@@ -1,65 +0,0 @@
----
-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/skills/ws-migrate/SKILL.md

@@ -1,54 +0,0 @@
----
-name: ws-migrate
-description: 迁移（补齐/升级 AIWS 工作区文件）
----
-
-用中文输出；命令与路径保持原样不翻译。
-
-目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
-
-执行（在项目根目录）：
-```bash
-if [[ -f ".aiws/manifest.json" ]]; then
-  if [[ -x "./node_modules/.bin/aiws" ]]; then
-    ./node_modules/.bin/aiws update .
-  elif command -v aiws >/dev/null 2>&1; then
-    aiws update .
-  else
-    npx @aipper/aiws update .
-  fi
-else
-  if [[ -x "./node_modules/.bin/aiws" ]]; then
-    ./node_modules/.bin/aiws init .
-  elif command -v aiws >/dev/null 2>&1; then
-    aiws init .
-  else
-    npx @aipper/aiws init .
-  fi
-fi
-
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate .
-elif command -v aiws >/dev/null 2>&1; then
-  aiws validate .
-else
-  npx @aipper/aiws validate .
-fi
-
-git config core.hooksPath .githooks
-```
-
-回滚（恢复最近一次快照）：
-```bash
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws rollback . latest
-elif command -v aiws >/dev/null 2>&1; then
-  aiws rollback . latest
-else
-  npx @aipper/aiws rollback . latest
-fi
-```
-
-约束：
-- 不写入任何 secrets。
-- 不执行破坏性命令。

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

@@ -1,119 +0,0 @@
----
-name: ws-pull
-description: 拉取并对齐 submodules（避免 detached；减少人为差异）
----
-
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
-
-背景：
-- Git submodule 在别的电脑 `git submodule update` 后常见现象是子模块处于 detached HEAD（因为主仓库记录的是固定 gitlink commit）。
-- detached 本身不一定是错，但会增加“需要手动切分支/容易忘”的操作差异。
-
-目标：
-- 安全拉取 superproject（默认只允许 fast-forward）
-- 初始化/同步 submodules（`--init --recursive`）
-- 在**不改动 superproject gitlink commit** 的前提下，尽量把每个 submodule 从 detached HEAD “挂回”到一个**确定的目标分支**（仅当该分支包含 gitlink commit 时）
-- 若未配置 `.gitmodules` 的 `submodule.<name>.branch`：保持 detached，并提示先运行 `$ws-submodule-setup`
-
-安全约束（强制）：
-- 不执行破坏性命令（不 `reset --hard` 主仓库；不改动远端）
-- 不自动提交/不自动 push
-- 若工作区不干净：停止并要求用户先 commit 或 stash（不要自动处理）
-
-执行步骤（建议）：
-0) 输出上下文：
-```bash
-git rev-parse --show-toplevel
-git branch --show-current
-git status --porcelain
-```
-若 `git status --porcelain` 非空：停止，要求用户先清理工作区（commit 或 stash）。
-
-1) 拉取 superproject（默认只允许 fast-forward，避免隐式 merge/rebase）：
-```bash
-git pull --ff-only
-```
-若失败（需要 merge/rebase）：停止并向用户解释原因，让用户明确选择 `git pull --rebase` 或手动处理。
-
-2) 同步并更新 submodules 到 superproject 记录的 gitlink commit：
-```bash
-if [[ -f .gitmodules ]]; then
-  git submodule sync --recursive
-  git submodule update --init --recursive
-else
-  echo "[info] no .gitmodules"
-fi
-```
-
-3) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”，减少手工操作差异：
-
-说明：
-- 该步骤不会改变 superproject 的 gitlink commit（也不会让主仓库出现“submodule modified”）。
-- 只在目标分支包含该 gitlink commit 时才执行“挂回”；否则保持 detached 并提示原因。
-- 为了避免 origin 分支较多时“猜错分支”，本步骤**只在** `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行“挂回分支”；否则保持 detached 并提示先运行 `$ws-submodule-setup` 对齐配置。
-
-```bash
-if [[ -f .gitmodules ]]; then
-  base_branch="$(git branch --show-current)"
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-    | while read -r key sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      name="${key#submodule.}"
-      name="${name%.path}"
-      echo "== submodule: ${sub_path} (${name}) =="
-
-      sub_sha="$(git rev-parse "HEAD:${sub_path}" 2>/dev/null || true)"
-      if [[ -z "${sub_sha:-}" ]]; then
-        echo "[warn] failed to read gitlink sha for ${sub_path}"
-        continue
-      fi
-
-      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 ws-submodule-setup to set it)"
-        continue
-      fi
-
-      target_branch="${cfg_branch}"
-      pin_branch="aiws/pin/${target_branch}"
-
-      git -C "${sub_path}" fetch origin --prune || true
-
-      if git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-        if git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-          # 不改动现有分支（避免把已有 main/master 等分支强行指回旧 commit）
-          # 仅创建/更新一个 AIWS 专用 pin 分支指向 gitlink commit，从 detached “挂回分支”。
-          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
-          echo "[ok] attached ${sub_path} to ${pin_branch} (upstream=origin/${target_branch}) at ${sub_sha}"
-        else
-          echo "[warn] ${sub_path}: ${sub_sha} is not in origin/${target_branch}; keep detached"
-        fi
-      else
-        echo "[warn] ${sub_path}: origin/${target_branch} not found; keep detached"
-      fi
-
-      git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
-      git -C "${sub_path}" status -sb || true
-    done
-fi
-```
-
-4) 一次性配置（方案 2）：为每个 submodule 写入跟踪分支，便于团队统一（需要用户确认，会改动 `.gitmodules`）：
-```bash
-# 示例：把某个 submodule 固定跟踪 main（会写入 .gitmodules 的 submodule.<name>.branch）
-git submodule set-branch --branch main <sub_path>
-
-# 提示：该变更需要提交到 superproject
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branch"
-```
-建议：
-- 只有当团队明确希望“子模块按分支滚动”（而不是锁定固定 commit）时，才采用方案 2。
-- 若只是想避免 detached 但仍锁定 gitlink commit：优先使用步骤 3（不改 `.gitmodules`）。
-- 推荐用 `$ws-submodule-setup` 交互式对齐所有 submodules 的 branch，并提交 `.gitmodules`。
-
-输出要求：
-- `Context:` 当前分支 + 是否存在 `.gitmodules` + submodule 列表
-- `Result:` pull 是否 fast-forward；每个 submodule 是否成功“挂回分支”，失败原因是什么

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

@@ -1,110 +0,0 @@
----
-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)"
-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
-    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
-
-    ws_resolve_sub_target "${sub_path}" "${name}" "${targets}" "${base_branch}" || exit 2
-    target_branch="${_resolved_branch}"
-    remote="${_resolved_remote}"
-
-    git -C "${sub_path}" fetch "${remote}" --prune
-    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
-      echo "error: missing ${remote}/${target_branch} for ${sub_path}"
-      exit 2
-    fi
-
-    # 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 -> <remote>/<branch>（不 force）
-    git -C "${sub_path}" push "${remote}" "HEAD:refs/heads/${target_branch}"
-  done
-
-# 最后 push superproject（仍需用户确认远端/分支）
-git remote -v
-git push
-```
-
-输出要求：
-- `Context:` 当前分支 + 是否有 submodules
-- `Submodules:` 每个 submodule push 的目标分支与结果（成功/阻断原因）
-- `Superproject:` push 结果