@aipper/aiws-spec 0.0.24 → 0.0.26

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

@@ -0,0 +1,111 @@
+---
+name: ws-bugfix
+description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片证据，汇总到 issues/fix_bus_issues.csv，并绑定到 changes/<change-id>/）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 用禅道 MCP 拉取 bug 详情与附件（尤其图片）
+- 把证据落盘到 `changes/<change-id>/bug/`（避免只停留在对话）
+- 把修复任务汇总/更新到 `issues/fix_bus_issues.csv`
+- 与 `ws-dev` / `aiws change` 流程绑定，确保可追溯、可验证
+
+非目标（强制）：
+- 不自动 commit / push
+- 不写入任何 secrets（token、cookie、内网地址）
+- 不在无法复现时直接改代码（先产出阻塞信息）
+
+前置：
+1) 先运行 `$ws-preflight`。
+2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
+3) 建立 change 上下文（推荐先于任何落盘）：
+   - 若当前还不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start`
+   - 工作区必须先干净；否则不要先写 `changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
+   - 仓库已有提交：优先 `--worktree`
+   - superproject + submodule：优先 `--worktree --submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `--no-switch`
+```bash
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree dirty before ws-bugfix creates change context"
+  exit 2
+fi
+
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+  if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&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：后续 bug 证据、CSV 更新、`$ws-dev` 修复都必须在该 worktree 中继续；不要回原工作区重复创建 change
+   - 若该 change 涉及 submodule：
+     - 优先复用 `$ws-dev` 的 `submodules.targets` 生成/确认流程
+     - detached HEAD 时默认建议取 `.gitmodules` 声明的分支
+     - 已附着在某个本地分支时默认建议取当前分支
+     - 以上都只是建议值，最终必须显式写入 `changes/<change-id>/submodules.targets`
+
+建议流程（按顺序）：
+
+## 1) 通过禅道 MCP 拉取 bug
+- 使用当前会话中已启用的 zentao MCP 工具获取：
+  - `bug_id`、标题、优先级/严重级、模块、状态、指派人
+  - 重现步骤、期望结果、实际结果
+  - 附件列表（含图片 URL/文件名）
+- 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
+
+## 2) 证据落盘（强制）
+在当前 active change 上下文的 `changes/<change-id>/bug/` 下落盘：
+- `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
+- `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
+- `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
+
+建议目录：
+```text
+changes/<change-id>/bug/
+  zentao-bug-<bug-id>.json
+  zentao-bug-<bug-id>.md
+  images/<bug-id>/
+```
+
+## 3) 汇总到 issues/fix_bus_issues.csv（upsert）
+- 目标文件：当前 active change 上下文中的 `issues/fix_bus_issues.csv`
+- 若文件不存在，先创建表头：
+```csv
+Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Paths,Evidence_Path,Verify_Command,Fix_Status,Updated_At,Notes
+```
+- 以 `Bug_ID` 为主键 upsert：
+  - 已存在：更新状态/证据/图片路径
+  - 不存在：新增一行
+
+字段约束：
+- `Change_ID`：必须等于当前 `change-id`
+- `Evidence_Path`：指向 `changes/<change-id>/bug/zentao-bug-<bug-id>.md`
+- `Image_Paths`：多个路径用 `;` 分隔
+- `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
+
+## 4) 修复执行与回填
+- 进入 `$ws-dev` 做最小改动修复；若 `ws-bugfix` 创建了 worktree，则必须在该 worktree 中继续。
+- 完成后回填 `issues/fix_bus_issues.csv`：
+  - `Fix_Status`
+  - `Verify_Command`
+  - `Updated_At`
+  - `Notes`（必要时写阻塞原因）
+
+## 5) 验证与交付
+```bash
+aiws change validate <change-id> --strict
+aiws validate . --stamp
+```
+- 需要提交时走 `$ws-commit`。
+- 需要收尾合并时走 `$ws-finish`（或在 superproject + submodule 场景走 `$ws-deliver`）。
+
+输出要求：
+- `Change_ID:` `<change-id>`
+- `Change context:` `<当前分支或 worktree 路径>`
+- `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
+- `Evidence:` `changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
+- `Verify:` 实际运行命令与结果（未运行不声称已运行）

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

@@ -0,0 +1,130 @@
+---
+name: ws-commit
+description: 提交（当前分支可直提；submodule 感知；先审计/门禁再 commit）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 支持在**当前分支直接提交**（不要求必须先切 `change/<change-id>`）
+- 提交前审计与证据落盘（`$ws-review`）
+- 提交前门禁校验与证据落盘（`aiws validate . --stamp`）
+- 最后执行 `git commit`（commit 前必须让用户确认 message；不使用 `--no-verify` 绕过 hooks）
+- 若仓库含 submodule：提交前识别并提示正确顺序（先 submodule，再 superproject）
+ - 若你经常遇到 submodule detached：建议日常拉取使用 `$ws-pull`（尽量把 submodule “挂回分支”且不改变 gitlink commit）
+
+安全约束（强制）：
+- 不自动 `git add -A`（避免误提交）；只在用户明确指示时才执行 staging 命令
+- 不自动 push
+- 不写入任何 secrets
+- 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
+- commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
+- 若启用了 `.githooks/commit-msg`：默认按仓库角色区分
+  - superproject / root 仓库（存在 `.gitmodules`）默认允许自由 commit message
+  - submodule / 普通仓库默认提示优先中文
+  - 只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+
+阶段定位：
+- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
+
+必需输入：
+- 当前分支与 staged diff
+- `$ws-review` 生成的审计证据
+- `aiws validate . --stamp` 生成的校验证据
+- 用户确认后的 commit message
+
+必需输出：
+- `证据（Evidence）:` review 文件路径 + validate stamp 路径
+- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
+- `提交信息（Commit）:` 最终提交信息
+
+阻断条件：
+- 没有 staged changes
+- submodule 工作区不干净或 detached 处理不完整
+- 用户未确认 commit message
+- validate 失败
+
+完成判定：
+- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
+
+执行步骤（建议）：
+1) 运行 `$ws-preflight`（确保真值文件就绪）。
+2) 运行 `$ws-review`（优先生成审计证据：`changes/<change-id>/review/codex-review.md`；无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`）。
+3) 运行门禁校验并写 stamp：
+```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
+```
+4) 输出当前提交上下文（必须输出给用户确认）：
+```bash
+git branch --show-current
+git status --porcelain
+```
+5) 检测是否存在 submodule（有则进入 submodule 感知模式）：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\..*\.path$' || true
+else
+  echo "[info] no .gitmodules"
+fi
+```
+6) 若存在 submodule，逐个检查子仓库工作区是否干净：
+```bash
+while read -r _ sub_path; do
+  [[ -z "${sub_path:-}" ]] && continue
+  echo "== submodule: ${sub_path} =="
+  git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
+  git -C "${sub_path}" status --porcelain || true
+done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true)
+```
+判定规则（强制）：
+- 任一 submodule `git status --porcelain` 非空：停止 superproject commit，先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target_branch>`；不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
+处理指引（detached submodule）：
+```bash
+cur_branch="$(git branch --show-current)"
+change_id="$(echo "${cur_branch}" | sed -n 's|^change/||p')"
+targets="changes/${change_id}/submodules.targets"
+
+source tools/ws_resolve_sub_target.sh
+ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${cur_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
+```
+7) 检查当前 staging 内容（必须输出给用户确认）：
+```bash
+git status --porcelain
+git diff --staged --submodule=short
+```
+8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
+9) 生成中文 commit message 草案（格式：`<类型>: <简述>`），输出给用户确认后再执行。
+   - 类型参考：`功能` / `修复` / `重构` / `文档` / `测试` / `构建` / `杂项`
+   - 简述用一句话概括本次改动的"为什么"而非"改了什么"
+   - 命令/路径/代码标识符保持原样不翻译
+   - 若用户给出全英文 message：优先改写成中文；若用户明确要求保留英文，也可以提交（但 strict 模式下会被 hook 拒绝）
+10) 执行提交（不带 `--no-verify`）：
+```bash
+git commit -m "<message>"
+```
+11) 输出提交结果（可选）：
+```bash
+git show --stat --oneline -1
+```
+
+输出要求：
+- `证据（Evidence）:` `changes/<change-id>/review/codex-review.md`（无 `change-id` 时回退 `.agentdocs/tmp/review/codex-review.md`） + `.agentdocs/tmp/aiws-validate/*.json`
+- `上下文（Context）:` 当前分支 + 是否检测到 submodule + 若阻断则给出阻断原因
+- `提交信息（Commit）:` 最终使用的 commit message（仅当用户确认后）

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

@@ -0,0 +1,63 @@
+---
+name: ws-delegate
+description: 原生多 agent 委托入口（OpenCode + oMo 优先；先写委托合同，再调用对应 agent）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 OpenCode 中，优先借用 `oh-my-opencode` 的现有 agent 做任务拆分；若 oMo 不可用，再回退为普通 OpenCode delegation / 单 agent 执行。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- delegation contract：`packages/spec/docs/workflow-delegation-contracts.md`
+- OpenCode + oMo 适配说明：`packages/spec/docs/opencode-omo-adapter.md`
+- 当前任务已绑定 `Req_ID` / change / Verify
+
+必需输出：
+- `Delegation Plan:` 写清 role / preferred agent / readScope / writeScope / artifactTargets / fallback
+- `Execution Mode:` `omo-native` / `opencode-native` / `single-agent`
+- `Evidence:` 产物路径
+- `Next:` 回到 `ws-dev` / `ws-review` / `ws-commit` / `ws-finish`
+
+阻断条件：
+- 任务未绑定
+- 没有写清委托边界
+- 无法判断当前是否可用 oMo，又不能接受回退
+
+推荐映射：
+- `planner` -> `planner-sisyphus`
+- `explorer` -> `@explore` / `@librarian`
+- `reviewer` -> `@oracle`
+- `integrator` -> 当前主 agent
+
+执行步骤（建议）：
+1) 先读真值文件、delegation contract 和 `opencode-omo-adapter.md`。
+2) 判断当前项目是否启用了 oMo：
+   - 优先检查 `.opencode/oh-my-opencode.json`
+   - 或当前会话是否明确可用 `planner-sisyphus` / `librarian` / `explore` / `oracle`
+3) 先写 `Delegation Plan:`：
+   - `role`
+   - `preferred agent`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+4) 若 oMo 可用：
+   - planning 优先 `planner-sisyphus`
+   - 文档/知识检索优先 `@librarian`
+   - 代码导航与结构探索优先 `@explore`
+   - 独立审查优先 `@oracle`
+5) 主 agent 统一收敛结果，并把产物回收到：
+   - `changes/<id>/analysis/`
+   - `changes/<id>/patches/`
+   - `changes/<id>/review/`
+   - `changes/<id>/evidence/`
+6) 若 oMo 不可用：
+   - 输出 `Execution Mode: opencode-native` 或 `Execution Mode: single-agent`
+   - 不阻断工作流，继续按 AIWS 委托合同执行
+
+安全：
+- 不让 `ws-delegate` 变成第二套 orchestrator。
+- 不覆盖 oMo 的 hooks / session / agent harness。
+- 不让 delegated agent 越权写未授权文件。

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

@@ -0,0 +1,230 @@
+---
+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) 归档说明
+- 标准链路下不需要再单独执行 `aiws change archive <change-id>`。
+- 进入 `$ws-finish` 并使用 `aiws change finish --push` 时，会自动完成 archive + handoff。
+
+输出要求：
+- `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）