@aipper/aiws-spec 0.0.24 → 0.0.25

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

@@ -0,0 +1,231 @@
+---
+name: ws-deliver
+description: 交付（submodules + superproject 分步提交，并安全合并回目标分支）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 适配 superproject + submodule（数量不固定）的交付收尾：
+  1) 先逐个提交 submodule（每个 repo 单独确认 commit message）
+  2) 再提交 superproject（包含 submodule gitlink 指针更新 + 变更工件/代码）
+  3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`，减少手动 merge 出错）
+
+非目标（强制）：
+- 不自动 `git add -A`（避免误提交）
+- 不自动 push
+- 不自动删除分支
+
+前置（强制）：
+1) 先运行 `$ws-preflight`。
+2) 确认当前处于 change 分支（推荐）：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）。
+   - 若不在 change 分支：要求用户先切换到 `change/<change-id>`（或在命令里显式提供 `<change-id>`）。
+3) 任何自动提交都必须在提交前输出：
+   - 该 repo 的 `git status --porcelain`
+   - 该 repo 的 `git diff --staged`
+   并让用户确认 commit message（每个 repo 单独确认）。
+
+阶段定位：
+- delivery 阶段；负责在多 repo / submodule 场景下完成顺序提交、证据收敛和最终合并前准备。
+
+必需输入：
+- 当前 `change/<change-id>` 上下文
+- 若存在 submodule：`.gitmodules` + `changes/<change-id>/submodules.targets`
+- 各 repo 当前状态与 staged diff
+
+必需输出：
+- `Submodules:` 每个 submodule 的提交摘要
+- `Superproject:` 主仓库提交摘要
+- `Evidence:` validate stamp 与持久证据路径
+- `Next:` 进入 `$ws-finish` 或 `aiws change finish`
+
+阻断条件：
+- 不在正确的 change 上下文
+- submodule branch / targets 真值不完整
+- 任一 repo 未确认 commit message 或存在未处理冲突
+
+完成判定：
+- submodule 与 superproject 提交都已完成，证据已收敛，且可以安全进入 finish 阶段。
+
+建议流程（按顺序）：
+
+## 0) submodule branch 真值检查（减少 detached 与人为差异）
+如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `$ws-submodule-setup` 并提交 `.gitmodules`，否则后续 `aiws validate .` 会失败，且 `ws-pull/ws-finish` 无法确定性工作。
+> 说明：若同一 superproject 分支内存在多渠道 submodule 目标分支的交付需求，可在 `changes/<change-id>/submodules.targets` 额外声明本次 change 的目标分支；交付时会优先使用该文件（不改变 `.gitmodules` 的团队默认真值）。
+> 生成该文件时，可以按当前状态做默认预填，但必须显式说明来源并让用户确认：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在某个本地分支时默认建议取当前分支；finish/push 最终只认 `submodules.targets`。
+```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
+
+  # 强约束：当 .gitmodules 声明 submodules 时，要求本次 change 存在 submodules.targets 且覆盖所有 submodule path
+  if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+    change_id="$(git branch --show-current | sed -n 's|^change/||p')"
+    targets="changes/${change_id}/submodules.targets"
+    if [[ ! -f "${targets}" ]]; then
+      echo "error: missing ${targets} (required when .gitmodules declares submodules)"
+      exit 2
+    fi
+    t_missing=0
+    while read -r _ sub_path; do
+      [[ -z "${sub_path:-}" ]] && continue
+      if ! awk -v p="${sub_path}" '$1==p && $0 !~ /^[[:space:]]*#/ && $2!="" { found=1 } END { exit(found?0:1) }' "${targets}" 2>/dev/null; then
+        echo "error: ${targets} missing entry for submodule path=${sub_path}"
+        t_missing=1
+      fi
+    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+    if [[ "${t_missing}" -ne 0 ]]; then
+      echo "hint: fill ${targets} as: <path> <target_branch> [remote]"
+      exit 2
+    fi
+  fi
+fi
+```
+
+## A) 发现 submodules 清单（数量不固定）
+在 superproject 根目录执行：
+```bash
+git submodule status --recursive
+```
+如果没有 submodule：跳到 C)。
+
+## B) 逐个提交 submodules（先 submodule，后 superproject）
+对每个 submodule path（可递归）重复以下步骤（建议按 `git submodule status --recursive` 顺序）：
+1) 定位并检查状态：
+```bash
+sub_path="<path>"
+git -C "$sub_path" branch --show-current
+git -C "$sub_path" status --porcelain
+```
+2) 先确定该 submodule 的目标分支来源，并显式说明给用户：
+   - `branch --show-current` 非空：默认建议用当前分支
+   - `branch --show-current` 为空（detached HEAD）：默认建议用 `.gitmodules` 的 `submodule.<name>.branch`
+   - 若建议值与 `changes/<change-id>/submodules.targets` 已落盘值不一致：以 `submodules.targets` 为准，并先提示差异
+3) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
+   - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
+   - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached。
+   - 若你要在该 submodule 里提交：先按目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
+     - 目标分支真值优先级：`changes/<change-id>/submodules.targets`（若存在）> `.gitmodules submodule.<name>.branch`
+```bash
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
+sub_name="$(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null | awk -v p="${sub_path}" '$2==p { name=$1; sub(/^submodule\\./,"",name); sub(/\\.path$/,"",name); print name; exit }')"
+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 "${sub_name}"
+test -n "${base_branch}"
+
+source tools/ws_resolve_sub_target.sh
+ws_resolve_sub_target "${sub_path}" "${sub_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 submodule path=${sub_path}"
+  exit 2
+fi
+git -C "$sub_path" checkout -B "aiws/pin/${target_branch}" HEAD
+git -C "$sub_path" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
+```
+   - 若 `origin/<target-branch>` 不存在，或用户明确不想使用 pin 分支：停止，解释风险（提交可能不可追溯/难以推送）。
+4) 选择性 staging（默认用 `-p` 更安全）：
+```bash
+git -C "$sub_path" add -p
+git -C "$sub_path" diff --staged --stat
+git -C "$sub_path" diff --staged
+```
+5) AI 生成该 submodule 的 commit message（标题+可选 body），并让用户确认（每个 repo 单独确认）。
+6) 执行提交（不带 `--no-verify`）：
+```bash
+git -C "$sub_path" commit -m "<message>"
+```
+7) 若该 submodule 没有 staged changes：跳过（不要硬提交空 commit）。
+
+## C) 提交 superproject（更新 gitlinks + 自身改动 + changes 工件）
+1) 先检查 submodule 指针差异（gitlinks）：
+```bash
+git diff --submodule
+```
+2) 选择性 staging：
+   - 先 stage 发生指针变化的 submodule 路径（明确列出）：
+```bash
+git add <submodule-path-1> <submodule-path-2>
+```
+   - 再 stage superproject 自身改动（默认 `-p`）：
+```bash
+git add -p
+git diff --staged --stat
+git diff --staged
+```
+3) AI 生成 superproject 的 commit message（应包含 `bump submodule <name> -> <sha>` 等关键信息），并让用户确认。
+4) 提交：
+```bash
+git commit -m "<message>"
+```
+
+## D) 门禁与证据（推荐）
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws validate . --stamp
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate . --stamp
+else
+  npx @aipper/aiws validate . --stamp
+fi
+```
+
+## D2) 生成持久证据并回填 Evidence_Path（强烈建议）
+> 说明：`.agentdocs/tmp/...` 默认 gitignored；交付前建议把关键结果落到 `changes/<change-id>/evidence/...` 并回填 `proposal.md`/`plan` 的 `Evidence_Path`，避免后续评审/二次会话读不到证据。
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change evidence "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change evidence "${change_id}"
+else
+  npx @aipper/aiws change evidence "${change_id}"
+fi
+```
+
+## D3) 生成状态快照（可选，建议）
+```bash
+aiws change state "${change_id}" --write
+```
+
+## E) 安全合并回目标分支（fast-forward）
+优先使用 `$ws-finish`（底层调用 `aiws change finish`，并在 push 成功后清理对应 change worktree）。
+
+若需要显式指定目标分支：
+```bash
+aiws change finish <change-id> --into <base-branch>
+```
+
+## F) （可选）归档变更工件
+```bash
+aiws change archive <change-id>
+```
+
+输出要求：
+- `Submodules:` 每个 submodule 的分支/提交摘要（repo → commit sha → message）
+- `Superproject:` 提交摘要
+- `Merge:` `aiws change finish` 的输出（into/from）
+- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
+- `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）

package/templates/workspace/.opencode/skills/ws-dev/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: ws-dev
+description: 开发（按需求实现并验证；适用于任何需要修改代码/配置的任务）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+阶段定位：
+- implementation 阶段；负责在既定计划/需求绑定下完成最小实现与验证。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前任务的归因目标（`Req_ID` 或 `Problem_ID`）
+- 若为 medium/complex：已通过 `$ws-plan` / `$ws-plan-verify` 的计划
+- 当前 `change/<change-id>` 上下文或等价变更归因
+
+必需输出：
+- `变更文件（Changed）:` 实际改动清单
+- `验证（Verify）:` 实际运行的命令与结果说明
+- `证据（Evidence）:` `plan/...`、`changes/<change-id>/...`、`.agentdocs/tmp/...` 等证据路径
+- `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
+
+阻断条件：
+- 无法把改动归因到 `REQUIREMENTS.md` 或问题单
+- 没有可复现验证入口
+- 需要创建 change 上下文但当前工作区状态不允许安全切换
+
+完成判定：
+- 改动已落盘、验证已执行或明确未执行原因、证据路径可回放，并可进入 review/commit 阶段。
+
+建议流程：
+1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+   - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
+   - 若已有 `plan/` 工件：先执行 `$ws-plan-verify`；通过后再进入实现（防止计划过长/跑偏）。
+   - 若 `$ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回到原工作区重复 `aiws change start ...`
+2) 建立变更归因（推荐）：
+   - ⚠️ 若你准备执行 `aiws change start ... --switch/--worktree` 或手工 `git switch ...` 改变 checkout 上下文，先确认工作区状态：`git status --porcelain`。否则切分支/创建 worktree 后，未提交改动可能看起来丢了（worktree 只从 `HEAD` checkout，未提交内容会留在原目录）。
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `$ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若 `git status --porcelain` 非空仅因为上一轮 `$ws-plan` / `aiws change new|sync` 生成了 `plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`、`design.md`、`submodules.targets`，这是预期行为，不等于流程出错。处理方式：
+     - 已经在 `change/<change-id>` 分支：直接继续实现，并把这些文件作为计划/证据工件保留。
+     - 还没进入 `change/<change-id>`：先运行 `aiws change start <change-id> --hooks --no-switch` 建立 change 上下文；若你仍要 `--switch/--worktree`，先提交这些规划工件，再切换上下文。
+   - 强制（当你准备执行 `aiws change start ... --worktree/--switch` 创建新 change 时）：先同步线上代码（含 submodules），避免基线过旧导致的 rebase/冲突与别人已更新但本地没拉的协作摩擦。
+     - 若你已经在 `change/<change-id>` 上继续开发：不要在此处强制 pull（避免把远端变动拉进变更分支）；改为按需 `git fetch`/rebase，并保持门禁与验证可复现。
+     - 在 AI 工具中运行：`$ws-pull`（推荐；会在工作区不干净时阻断）
+     - 或等价手工（必须工作区干净；失败则停止并人工处理）：
+```bash
+cur="$(git branch --show-current)"
+if [[ "${cur}" =~ ^(change|changes|ws|ws-change)/ ]]; then
+  echo "info: already on change branch (${cur}); skip pull here"
+else
+  git status --porcelain
+  git pull --ff-only
+  if [[ -f .gitmodules ]]; then
+    git submodule sync --recursive
+    git submodule update --init --recursive
+  fi
+fi
+```
+   - 推荐更安全（默认）：`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`（创建独立 worktree；当前目录分支保持不变；会在新 worktree 内初始化 submodules；若忘了 `--submodules` 也会强制初始化）
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 若仓库存在 submodule（`.gitmodules` 声明了 submodule 条目）：进入编码前必须准备好 `changes/<change-id>/submodules.targets`，并把每个 submodule 挂到对应的 `aiws/pin/<target_branch>`（必要时切到 `<remote>/<target_branch>`；这可能会改变 superproject 的 gitlink 指针，属于预期的选渠道行为；缺失该文件会被门禁阻断）
+   - 允许用当前 submodule 状态来做默认预填，但必须显式说明来源，并最终落盘到 `submodules.targets`：
+     - detached HEAD：默认建议取 `.gitmodules` 中声明的 `submodule.<name>.branch`
+     - 已附着在某个本地分支：默认建议取该 submodule 的当前分支名
+     - 上述两条都只是建议值，不是运行时真值；真正的 finish/push 只认 `changes/<change-id>/submodules.targets`
+```bash
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
+has_submodules=0
+if [[ -f .gitmodules ]]; then
+  if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+    has_submodules=1
+  fi
+fi
+if [[ "${has_submodules}" -eq 1 && ! -f "${targets}" ]]; then
+  echo "error: missing ${targets} (required when .gitmodules declares submodules)"
+  echo "hint: create it first; defaults may be inferred, but the final truth must be written explicitly"
+  exit 2
+fi
+
+if [[ -f "${targets}" ]]; then
+  echo "info: applying submodule targets: ${targets}"
+  while read -r sub_path target_branch remote; do
+    [[ -z "${sub_path:-}" ]] && continue
+    [[ "${sub_path}" == \#* ]] && continue
+    [[ -z "${target_branch:-}" ]] && { echo "error: missing target_branch for path=${sub_path}"; exit 2; }
+    remote="${remote:-origin}"
+
+    echo "== submodule: ${sub_path} target=${remote}/${target_branch} =="
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null)" ]]; then
+      echo "error: submodule dirty: ${sub_path} (commit/stash first)"
+      exit 2
+    fi
+    git -C "${sub_path}" fetch "${remote}" --prune
+    # 选渠道：默认切到远端目标分支，并用 pin 分支承载本地提交（避免 detached）
+    git -C "${sub_path}" checkout -B "aiws/pin/${target_branch}" "${remote}/${target_branch}"
+    git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
+    git -C "${sub_path}" status -sb
+  done < "${targets}"
+
+  # 检查 superproject 的 gitlink 是否发生变化（预期：若切了不同渠道，会看到差异）
+  git diff --submodule
+fi
+```
+   - 若你还没写 `submodules.targets`，可按下面方式先生成建议值，再人工确认后落盘：
+```bash
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
+: > "${targets}"
+
+git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null | while read -r key sub_path; do
+  name="${key#submodule.}"; name="${name%.path}"
+  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
+    inferred_branch="${current_branch}"
+    inferred_from="current branch"
+  else
+    inferred_branch="${declared_branch}"
+    inferred_from=".gitmodules"
+  fi
+
+  if [[ -z "${inferred_branch}" ]]; then
+    echo "error: cannot infer target branch for ${sub_path}; set it manually"
+    exit 2
+  fi
+
+  printf "%s %s\n" "${sub_path}" "${inferred_branch}" >> "${targets}"
+  echo "info: ${sub_path} -> ${inferred_branch} (inferred from ${inferred_from}; remote defaults to origin unless you edit ${targets})"
+done
+
+echo "review required: ${targets}"
+cat "${targets}"
+```
+   - 若你明确要在 superproject 直接切分支：`aiws change start <change-id> --hooks --switch`（仅在存在 `.gitmodules` 时有意义；会尝试让 submodules 工作区跟随 superproject 指针）
+   - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+3) 若需要外部 / 子 agent 协作：
+   - 分析结论落盘到 `changes/<change-id>/analysis/`
+   - patch 草案落盘到 `changes/<change-id>/patches/`
+   - 不要把 `patches/` 当成“已应用代码”；主 agent 必须先审查再决定是否采用
+   - 若采用了委托结果，后续在 `ws-review` 或 `changes/<change-id>/review/` 中收敛最终结论
+4) 如涉及需求调整：先做需求评审（可用 `$ws-req-review`）→ 用户确认后再做需求落盘（可用 `$ws-req-change`）（避免需求漂移）。
+5) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
+6) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
+7) 多步任务（≥2 步）：使用 `update_plan` 工具跟踪 `pending → in_progress → completed`，每完成一步立即更新（不要事后批量更新）。
+8) 提交前强制门禁（commit/push hooks 也会阻断）：
+```bash
+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
+```
+9) 若使用了协同工件，交付前建议执行 `aiws change evidence <change-id>`，把 review / validate / collaboration summary 收敛到 `changes/<change-id>/evidence/`。
+10) 交付收尾（推荐，减少手动 merge 出错）：运行 `$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
+
+输出要求：
+- `变更文件（Changed）:` 文件清单
+- `验证（Verify）:` 实际运行的命令 + 期望结果
+- `证据（Evidence）:` 证据路径（例如 `changes/<change-id>/review/...`、`plan/...`、`.agentdocs/tmp/aiws-validate/...` 或 `changes/<change-id>/...`）

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

@@ -0,0 +1,220 @@
+---
+name: ws-finish
+description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在结束一次变更交付时，用 fast-forward 安全合并 `change/<change-id>` 回目标分支，减少手输分支名导致的错误
+- 合并成功后，按 `submodule -> superproject` 顺序 push，避免遗漏导致其它仓库拉取异常
+- 不自动删分支；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）
+- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
+
+阶段定位：
+- finish 阶段；负责把已提交的 change 安全合并回目标分支，并按约束完成 push / worktree cleanup。
+
+必需输入：
+- 干净的当前工作区
+- 已提交完成的 `change/<change-id>`
+- 若存在 submodule：`.gitmodules` 与 `changes/<change-id>/submodules.targets`
+- 当前 push 目标说明（remote / branch）
+
+必需输出：
+- `Merge:` `aiws change finish` 的结果（from / into）
+- `Push:` 实际 remote / branch 或未 push 原因
+- `Worktree cleanup:` 清理结果
+- `Evidence:` validate stamp / evidence / state 路径
+
+阻断条件：
+- 工作区不干净
+- 缺失 submodule branch / targets 真值
+- fast-forward 失败
+- 子模块目标分支无法安全 push
+
+完成判定：
+- change 已安全合并回目标分支，必要的 push 与 worktree cleanup 已完成或明确说明未完成原因。
+
+建议步骤：
+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
+  ./node_modules/.bin/aiws validate . --stamp
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate . --stamp
+else
+  npx @aipper/aiws validate . --stamp
+fi
+```
+1.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change evidence "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change evidence "${change_id}"
+else
+  npx @aipper/aiws change evidence "${change_id}"
+fi
+```
+1.2) （可选）生成状态快照（建议）：
+```bash
+aiws change state "${change_id}" --write
+```
+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}" --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
+```
+说明：
+- 该命令会在 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
+# 不要用当前分支名代替目标分支；这里显式使用 .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 分支策略：
+# - `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>`
+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
+
+  source tools/ws_resolve_sub_target.sh
+
+  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
+
+      sub_sha="$(git rev-parse "HEAD:${sub_path}")"
+
+      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 不在 `<remote>/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
+
+6) 仅当 submodules 全部成功后，再在 superproject 当前分支执行最小收尾闭环：
+```bash
+change_id="<change-id>"
+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
+```
+说明：
+- 该命令内部已经包含主仓库 push 成功后安全清理独立 change worktree 的逻辑。
+
+7) （可选）归档变更工件（完成交付后推荐）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "${change_id}"
+else
+  npx @aipper/aiws change archive "${change_id}"
+fi
+```