@aipper/aiws-spec 0.0.23 → 0.0.25

package/templates/workspace/.claude/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/skills/ws-verify-before-complete/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ws-verify-before-complete
+description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
+- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+
+阶段定位：
+- finish 前 gate；负责 completion readiness 检查，不直接做 merge / push / handoff。
+
+必需输入：
+- `changes/<change-id>/review/spec-review.md`
+- `changes/<change-id>/review/quality-review.md`
+- `.agentdocs/tmp/aiws-validate/*.json`
+- 若存在：`changes/<change-id>/evidence/...`、`git status`
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/evidence/verify-before-complete.md` 或回退 `.agentdocs/tmp/review/verify-before-complete.md`
+- `结论（Result）:` pass / fail
+- `缺失项（Missing）:` 未满足的 gate
+- `下一步（Next）:` 进入 `$ws-finish` / `$ws-handoff`，或回退前置 gate
+
+阻断条件：
+- 缺少 spec review
+- 缺少 quality review
+- 缺少 validate stamp
+- review 中仍有未关闭 blocker
+- 无法写 verification 证据
+
+完成判定：
+- 已落盘 verify-before-complete 证据，并明确能否进入 `$ws-finish` / `$ws-handoff`。
+
+步骤（建议）：
+1) 识别当前 `change/<change-id>`。
+2) 检查以下最小 gate：
+   - `changes/<change-id>/review/spec-review.md`
+   - `changes/<change-id>/review/quality-review.md`
+   - `.agentdocs/tmp/aiws-validate/*.json`
+3) 若存在 `changes/<change-id>/evidence/`，检查是否已经收敛 review / validate / collaboration summary。
+4) 将结果落盘到：
+   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
+   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
+5) 输出：
+   - `证据（Evidence）:`
+   - `结论（Result）: pass|fail`
+   - `缺失项（Missing）:`
+   - `下一步（Next）:`
+
+重点：
+- 这个 gate 不替代 `$ws-finish`；它只判断“是否具备进入 finish / handoff 的前置条件”。
+- 若 fail，必须明确回退到哪个 gate：`$ws-spec-review`、`$ws-quality-review`、`aiws validate . --stamp` 或 `aiws change evidence <change-id>`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

package/templates/workspace/.codex/prompts/ws-dev.md

@@ -12,8 +12,12 @@ argument-hint: ""
 
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `$ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
 2) 建立变更归因（推荐）：
-   - 推荐一键：`aiws change start <change-id> --hooks`
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `$ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若 `/ws-plan` 已生成 `plan/...` 或 `changes/<change-id>/...` 导致工作区非空，这是预期行为；此时不要直接再做 `--switch/--worktree`，优先：`aiws change start <change-id> --hooks --no-switch`，或先提交规划工件。
+   - 推荐一键（工作区干净时）：`aiws change start <change-id> --hooks`
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`
    - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
    - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
    - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）

package/templates/workspace/.githooks/commit-msg

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${WS_CHANGE_HOOK_BYPASS:-0}" == "1" ]]; then
+  echo "warn: WS_CHANGE_HOOK_BYPASS=1; skip aiws commit-msg hook" >&2
+  exit 0
+fi
+
+msg_file="${1:-}"
+[[ -n "${msg_file:-}" && -f "$msg_file" ]] || exit 0
+
+policy="${AIWS_COMMIT_MSG_POLICY:-}"
+if [[ -z "${policy:-}" ]]; then
+  policy="$(git config --get aiws.commitMessagePolicy 2>/dev/null || true)"
+fi
+policy="${policy:-warn}"
+
+case "$policy" in
+  off|disabled|0)
+    exit 0
+    ;;
+  warn|prefer-zh)
+    policy="warn"
+    ;;
+  strict|require-zh|1)
+    policy="strict"
+    ;;
+  *)
+    echo "warn: unknown aiws commit message policy '${policy}', fallback to warn" >&2
+    policy="warn"
+    ;;
+esac
+
+first_line="$(sed -n '1{s/\r$//;p;q;}' "$msg_file")"
+first_line="${first_line#"${first_line%%[![:space:]]*}"}"
+first_line="${first_line%"${first_line##*[![:space:]]}"}"
+
+[[ -n "${first_line:-}" ]] || exit 0
+
+case "$first_line" in
+  Merge\ *|Revert\ *|fixup!\ *|squash!\ *)
+    exit 0
+    ;;
+esac
+
+has_cjk=1
+if command -v python3 >/dev/null 2>&1; then
+  if python3 - "$first_line" <<'PY'
+import re
+import sys
+
+line = sys.argv[1].strip()
+sys.exit(0 if re.search(r"[\u3400-\u9fff]", line) else 1)
+PY
+  then
+    has_cjk=0
+  fi
+else
+  if printf '%s\n' "$first_line" | grep -q '[一-龥]'; then
+    has_cjk=0
+  fi
+fi
+
+if [[ "$has_cjk" -eq 0 ]]; then
+  exit 0
+fi
+
+if [[ "$policy" == "warn" ]]; then
+  cat >&2 <<'EOF'
+warn: commit message is better in Chinese, but English is still allowed.
+
+hint:
+  - preferred format: 修复: 登录页空指针
+  - or: 功能: 新增 submodule targets 校验
+  - if you are in AI tools, prefer: $ws-commit / /ws-commit / ws:commit
+  - set strict mode if needed: git config aiws.commitMessagePolicy strict
+  - disable this reminder: git config aiws.commitMessagePolicy off
+
+allowed exceptions:
+  - Merge ...
+  - Revert ...
+  - fixup! ...
+  - squash! ...
+EOF
+
+  echo "message: ${first_line}" >&2
+  exit 0
+fi
+
+cat >&2 <<'EOF'
+error: commit message should be in Chinese (strict mode).
+
+hint:
+  - use format: 修复: 登录页空指针
+  - or: 功能: 新增 submodule targets 校验
+  - if you are in AI tools, prefer: $ws-commit / /ws-commit / ws:commit
+  - downgrade to warn: git config aiws.commitMessagePolicy warn
+  - disable only when necessary: git config aiws.commitMessagePolicy off
+  - bypass only when necessary: WS_CHANGE_HOOK_BYPASS=1 git commit ...
+
+allowed exceptions:
+  - Merge ...
+  - Revert ...
+  - fixup! ...
+  - squash! ...
+EOF
+
+echo "message: ${first_line}" >&2
+exit 1

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

@@ -16,6 +16,7 @@ prompt = """
 - 不使用 `--no-verify` 绕过 hooks
 - 不自动 push
 - 不打印 secrets
+- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
 
 强制步骤：
 1) 读取真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`（缺失则先运行 `/aiws-init` 或 `aiws init .`）。
@@ -36,7 +37,7 @@ prompt = """
    - `git status --porcelain`
    - `git diff --staged --submodule=short`
 8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-9) 让用户提供 commit message（必须确认后再执行）。
+9) 优先生成并确认中文 commit message（格式建议：`<类型>: <简述>`；若用户明确要求英文也可保留，但 strict 模式下会被 hook 拒绝）。
 10) 执行提交（不带 `--no-verify`）：`git commit -m "<message>"`。
 
 输出必须包含：

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

@@ -8,7 +8,7 @@ description = "交付（submodules + superproject 分步提交，并安全合并
 prompt = """
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：适配 superproject + submodule（数量不固定）的交付收尾，降低“提交顺序/合并回 base 分支”出错概率：
+目标：适配 superproject + submodule（数量不固定）的交付收尾，降低提交顺序和合并回 base 分支的出错概率：
 1) 先逐个提交 submodule（每个 repo 单独确认 commit message；默认 `git add -p`）
 2) 再提交 superproject（包含 submodule gitlink 指针更新 + 自身改动/变更工件）
 3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `ws:finish`）
@@ -21,11 +21,15 @@ prompt = """
 建议流程（按顺序）：
 1) 先确认真值文件存在并遵守：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
 2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `ws:submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
+2.1) 若存在 submodule：必须准备 `changes/<change-id>/submodules.targets`，并覆盖所有 submodule path；这是本次交付的目标分支真值。
+   - 生成该文件时可先做默认预填：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在本地分支时默认建议取当前分支。
+   - 上述都只是建议值；真正的 deliver/finish 只认 `submodules.targets`。
 2) 发现 submodules：
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
    - `git -C "<sub_path>" status --porcelain`
-   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`
+   - 先说明该 submodule 目标分支的来源：attached branch 默认建议取当前分支；detached HEAD 默认建议取 `.gitmodules`；若与 `submodules.targets` 已落盘值冲突，则以 `submodules.targets` 为准
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `submodules.targets`（若分支为 `.` 则展开为 `.ws-change.json` 的 `base_branch`）挂到 `aiws/pin/<target-branch>`
    - `git -C "<sub_path>" add -p`
    - `git -C "<sub_path>" diff --staged --stat`
    - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）

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

@@ -22,33 +22,33 @@ prompt = """
 5) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 5.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
 5.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
-6) 安全合并（默认 fast-forward）：
-   - 在 `change/<change-id>` 分支上：`aiws change finish`（会尝试读 `changes/<change-id>/.ws-change.json` 的 `base_branch` 并切回目标分支）
-   - 否则：`aiws change finish <change-id>`
-7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish`。
-8) 合并成功后，按顺序处理每个 submodule（先“并回目标分支”，再 push）：
+6) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+   - `aiws change finish <change-id> --push`
+   - 在 `change/<change-id>` 分支上也可省略 `<change-id>`；命令会尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch`
+   - 该命令会在 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；显式传入 `--push` 即视为确认
+7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+8) 若需要先处理 submodules，则按顺序处理每个 submodule（先并回目标分支，再 push）：
+   - 先显式解析 base branch，不要用当前分支名替代：
+     - `python3 - <<'PY'`
+     - `import json, pathlib; meta = pathlib.Path("changes") / "<change-id>" / ".ws-change.json"; print((json.loads(meta.read_text(encoding="utf-8")).get("base_branch") or "").strip())`
+     - `PY`
    - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
-     - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
-     - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”
+     - 目标分支真值：`changes/<change-id>/submodules.targets`；若条目里分支写 `.`，则展开为刚才解析出的 `base_branch`
+     - 生成/检查 `submodules.targets` 时，detached HEAD 默认建议取 `.gitmodules` 的 `submodule.<name>.branch`；已附着在本地分支时默认建议取当前分支；这些都只是预填建议，不是 finish/push 的运行时真值
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached
      - 用 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`
-   - `git push`
-11) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
-   - `change_ref="refs/heads/change/<change-id>"`
-   - `main_wt="$(git rev-parse --show-toplevel)"`
-   - `change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '$1=="worktree"{wt=substr($0,10)} $1=="branch"&&$2==ref{print wt; exit}')"`
-   - 若 `change_wt` 非空且不等于 `main_wt`：先输出并让用户确认，再执行 `git worktree remove "$change_wt"`（不带 `--force`），最后 `git worktree prune`
-   - 若 `git -C "$change_wt" status --porcelain` 非空：停止并提示先清理该 worktree
-12) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+10) submodules push 完成后，再回到主仓库执行：
+   - `aiws change finish <change-id> --push`
+11) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 边界：
-- push 前先输出状态并请用户确认远端/分支。
+- push 前先输出状态并说明远端/分支。
 - 不执行破坏性命令。
 """

package/templates/workspace/.opencode/command/using-aiws.md

@@ -0,0 +1,29 @@
+---
+description: 默认 workflow router：先判定阶段，再进入具体 ws-* 入口
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:using-aiws -->
+# using aiws
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 把当前任务先路由到正确的 AIWS workflow，而不是直接跳进实现。
+
+执行建议：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+   - 若检测到 `.opencode/oh-my-opencode.json`：输出 `OpenCode mode: oMo-enabled`，并注明后续会优先借用 `planner-sisyphus` / `explore` / `librarian` / `oracle`
+   - 若未检测到：输出 `OpenCode mode: standard-opencode`
+2) 若缺失任一真值文件：先 `/ws-preflight`，必要时运行 `aiws init .`，不要继续实现。
+3) 若任务意图、归因或验证入口不明确：先提 1-3 个关键澄清问题并停止。
+4) 路由规则：
+   - 需求/验收/合同变更：`/ws-req-review`
+   - 中大型实现或需要 change/worktree：`/ws-plan`
+   - 小步明确实现：`/ws-dev`
+   - 评审/审计：`/ws-review`
+   - finish / merge / push / cleanup：`/ws-finish`
+   - handoff / archive summary：`/ws-handoff`
+5) 输出 `OpenCode mode:` / `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
+6) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。
+<!-- AIWS_MANAGED_END:opencode:using-aiws -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -11,15 +11,20 @@ description: 缺陷修复：禅道 MCP 拉单、图片证据落盘并汇总 fix_
 
 建议流程：
 1) 先运行 `/ws-preflight`。
-2) 建立变更工件（推荐）：`aiws change start <change-id> --hooks`（superproject+submodule 可用 `--worktree --submodules`）。
-3) 通过已配置 zentao MCP 拉取 bug 字段与附件列表。
-4) 落盘证据到 `changes/<change-id>/bug/`：
+2) 若当前不在 `change/<change-id>` 分支 / worktree，先建立 change 上下文：
+   - 工作区先保持干净
+   - 仓库已有提交：优先 `aiws change start <change-id> --hooks --worktree`
+   - superproject + submodule：优先 `aiws change start <change-id> --hooks --worktree --submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `aiws change start <change-id> --hooks --no-switch`
+3) 若上一步创建了 worktree：后续 bug 证据、CSV 更新、`/ws-dev` 修复都必须在该 worktree 中继续。
+4) 通过已配置 zentao MCP 拉取 bug 字段与附件列表。
+5) 落盘证据到当前 active change 上下文的 `changes/<change-id>/bug/`：
    - `zentao-bug-<bug-id>.json`
    - `zentao-bug-<bug-id>.md`
    - `images/<bug-id>/...`
-5) upsert `issues/fix_bus_issues.csv`（主键 `Bug_ID`）。
-6) 进入 `/ws-dev` 修复并回填 `Fix_Status/Verify_Command/Updated_At`。
-7) 质量门：`aiws change validate <change-id> --strict` + `aiws validate . --stamp`。
+6) upsert 当前 active change 上下文中的 `issues/fix_bus_issues.csv`（主键 `Bug_ID`）。
+7) 进入 `/ws-dev` 修复并回填 `Fix_Status/Verify_Command/Updated_At`。
+8) 质量门：`aiws change validate <change-id> --strict` + `aiws validate . --stamp`。
 
 强制约束：
 - 不自动 commit / push。

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

@@ -14,6 +14,7 @@ description: 提交：门禁/审计后提交（submodule 感知）
 - 不使用 `--no-verify` 绕过 hooks
 - 不自动 push
 - 不打印 secrets
+- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
 
 步骤（建议）：
 1) 先运行 `/ws-preflight`。
@@ -54,7 +55,7 @@ git status --porcelain
 git diff --staged --submodule=short
 ```
 7) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-8) 让用户提供 commit message（必须确认后再执行）。
+8) 优先生成并确认中文 commit message（格式建议：`<类型>: <简述>`；若用户明确要求英文也可保留，但 strict 模式下会被 hook 拒绝）。
 9) 执行提交（不带 `--no-verify`）：
 ```bash
 git commit -m "<message>"

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

@@ -0,0 +1,33 @@
+---
+description: 委托：按 AIWS 合同拆分子任务，并优先借用 oMo agent
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-delegate -->
+# ws delegate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：先写清 delegation plan，再决定是否优先借用 `oh-my-opencode` 的 `planner-sisyphus` / `explore` / `librarian` / `oracle`；若不可用则回退，不阻断流程。
+
+执行建议：
+1) 先运行 `/ws-preflight`，再读取 `packages/spec/docs/workflow-delegation-contracts.md` 与 `packages/spec/docs/opencode-omo-adapter.md`。
+2) 先写 `Delegation Plan:`，至少包含：
+   - `role`
+   - `preferred agent`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+3) 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用相关 agent：
+   - planning 优先 `planner-sisyphus`
+   - 探索优先 `@explore` / `@librarian`
+   - 独立审查优先 `@oracle`
+4) 主 agent 统一收敛结果，并把产物回收到：
+   - `changes/<id>/analysis/`
+   - `changes/<id>/patches/`
+   - `changes/<id>/review/`
+   - `changes/<id>/evidence/`
+5) 若 oMo agent 不可用：明确回退为普通 OpenCode delegation / 单 agent 执行。
+<!-- AIWS_MANAGED_END:opencode:ws-delegate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -6,7 +6,7 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：适配 superproject + submodule（数量不固定）的交付收尾，降低“提交顺序/合并回 base 分支”出错概率：
+目标：适配 superproject + submodule（数量不固定）的交付收尾，降低提交顺序和合并回 base 分支的出错概率：
 1) 先逐个提交 submodule（每个 repo 单独确认 commit message；默认 `git add -p`）
 2) 再提交 superproject（包含 submodule gitlink 指针更新 + 自身改动/变更工件）
 3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `/ws-finish`）
@@ -19,11 +19,15 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 建议流程（按顺序）：
 1) 先运行 `/ws-preflight`。
 2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `/ws-submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
+2.1) 若存在 submodule：必须准备 `changes/<change-id>/submodules.targets`，并覆盖所有 submodule path；这是本次交付的目标分支真值。
+   - 生成该文件时可先做默认预填：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在本地分支时默认建议取当前分支。
+   - 上述都只是建议值；真正的 deliver/finish 只认 `submodules.targets`。
 2) 发现 submodules：
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
    - `git -C "<sub_path>" status --porcelain`
-   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`
+   - 先说明该 submodule 目标分支的来源：attached branch 默认建议取当前分支；detached HEAD 默认建议取 `.gitmodules`；若与 `submodules.targets` 已落盘值冲突，则以 `submodules.targets` 为准
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `submodules.targets`（若分支为 `.` 则展开为 `.ws-change.json` 的 `base_branch`）挂到 `aiws/pin/<target-branch>`
    - `git -C "<sub_path>" add -p`
    - `git -C "<sub_path>" diff --staged --stat`
    - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）

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

@@ -10,10 +10,13 @@ description: 开发：在 AIWS 约束下完成小步交付
 
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `/ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
 2) 建立变更归因（推荐）：
-   - ⚠️ 开始前先确认工作区干净：`git status --porcelain` 为空；否则切分支/创建 worktree 后，未提交改动可能“看起来丢了”（worktree 只从 `HEAD` checkout，未提交内容会留在原目录）。
+   - ⚠️ 若准备切分支/创建 worktree，先看 `git status --porcelain`；否则切换上下文后，未提交改动可能“看起来丢了”。
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `/ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若非空仅因为 `/ws-plan` 生成了 `plan/...` 或 `changes/<change-id>/...`，这是预期行为；此时优先 `aiws change start <change-id> --hooks --no-switch`，若仍要 `--switch/--worktree`，先提交这些规划工件。
    - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
-   - 准备进入实现（且工作区干净）后再切换：`git switch change/<change-id>`
+   - 准备进入实现时：若当前已在 `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`
    - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`

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

@@ -37,34 +37,34 @@ fi
 2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
 2.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
 2.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
-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（减少 detached；再 push）：
+3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+   - `aiws change finish <change-id> --push`
+   - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`
+   - 该命令会在 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；显式传入 `--push` 即视为确认
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若需要先处理 submodules，则按顺序处理每个 submodule（减少 detached；再 push）：
+   - 先显式解析 base branch，不要用当前分支名替代：
+     - `python3 - <<'PY'`
+     - `import json, pathlib; meta = pathlib.Path("changes") / "<change-id>" / ".ws-change.json"; print((json.loads(meta.read_text(encoding="utf-8")).get("base_branch") or "").strip())`
+     - `PY`
    - 发现 submodules：`git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'`
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
-     - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
-     - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”
+     - 目标分支真值：`changes/<change-id>/submodules.targets`；若条目里分支写 `.`，则展开为刚才解析出的 `base_branch`
+     - 生成/检查 `submodules.targets` 时，detached HEAD 默认建议取 `.gitmodules` 的 `submodule.<name>.branch`；已附着在本地分支时默认建议取当前分支；这些都只是预填建议，不是 finish/push 的运行时真值
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached
      - 用 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`
-   - `git push`
-8) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
-   - `change_ref="refs/heads/change/<change-id>"`
-   - `main_wt="$(git rev-parse --show-toplevel)"`
-   - `change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '$1=="worktree"{wt=substr($0,10)} $1=="branch"&&$2==ref{print wt; exit}')"`
-   - 若 `change_wt` 非空且不等于 `main_wt`：先输出并让用户确认，再执行 `git worktree remove "$change_wt"`（不带 `--force`），最后 `git worktree prune`
-   - 若 `git -C "$change_wt" status --porcelain` 非空：停止并提示先清理该 worktree
-9) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+7) submodules 全部成功后，再回到主仓库执行：
+   - `aiws change finish <change-id> --push`
+8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 安全：
-- push 前先输出状态并请用户确认远端/分支。
+- push 前先输出状态并说明远端/分支。
 - 不执行破坏性命令。
 <!-- AIWS_MANAGED_END:opencode:ws-finish -->
 

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

@@ -7,14 +7,21 @@ description: 规划：生成可落盘 plan 工件
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 生成可落盘执行计划（供 /ws-dev 执行）。
+- 若尚未进入本次 change 的工作上下文：先建立 `change/<change-id>` 分支 / worktree，再生成可落盘执行计划（供 /ws-dev 执行）。
 
 执行建议：
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
-2) 生成或更新计划文件：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`。
-3) 计划至少包含：`Bindings`、`Goal`、`Non-goals`、`Scope`、`Plan`、`Verify`、`Risks & Rollback`、`Evidence`。
-4) 若已有 `changes/<change-id>/proposal.md`，对齐 `Plan_File` / `Contract_Row` / `Evidence_Path`。
-5) 完成后先运行 `/ws-plan-verify`，通过再进入 `/ws-dev`。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `planner-sisyphus` / `explore` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - 计划主框架优先 `planner-sisyphus`；结构探索优先 `@explore`；规范/文档查证优先 `@librarian`。
+2) 若当前不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start <change-id>` 建立上下文：
+   - 仓库已有提交：优先 `aiws change start <change-id> --hooks --worktree`；若声明了 submodules，加 `--submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `aiws change start <change-id> --hooks --no-switch`
+3) 若上一步创建了 worktree：切到输出的 `worktree:` 路径，后续所有计划文件都写在该 worktree 中。
+4) 生成或更新计划文件：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`。
+5) 计划至少包含：`Bindings`、`Goal`、`Non-goals`、`Scope`、`Plan`、`Verify`、`Risks & Rollback`、`Evidence`。
+6) 若已有 `changes/<change-id>/proposal.md`，对齐 `Plan_File` / `Contract_Row` / `Evidence_Path`。
+7) 完成后先运行 `/ws-plan-verify`，通过再进入 `/ws-dev`。
+8) 若 oMo 不可用：回退为普通 OpenCode `plan` / 当前 agent 本地规划，但仍必须落盘完整 `plan/...`。
 <!-- AIWS_MANAGED_END:opencode:ws-plan -->
 
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -20,6 +20,10 @@ description: 预检：读取真值文件并输出约束摘要
    - `Root:` <项目根路径>
    - `Found:` <实际读取到的文件列表>
    - `Missing:` <缺失文件列表>
+   - `OpenCode mode:` 
+     - 若检测到 `.opencode/oh-my-opencode.json`：`oMo-enabled`
+     - 否则：`standard-opencode`
+   - 若为 `oMo-enabled`：附一句说明后续 `ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 会优先借用 oMo agent
    - `Key rules:` 3–8 条 bullet（范围/禁止项/必须产物/必须验证命令）
 
 安全：