@aipper/aiws-spec 0.0.28 → 0.0.30

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

@@ -6,6 +6,7 @@ description: 评审（提交前审计与证据落盘）
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+若当前语境已经明确是“准备交付/finish”，则本入口不应只停留在通用 review：应继续同时补齐 `$ws-spec-review` 与 `$ws-quality-review`，把 dual review gate 一次性收敛完。
 
 阶段定位：
 - review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
@@ -40,7 +41,11 @@ description: 评审（提交前审计与证据落盘）
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-4) 回复中输出：
+4) 若当前任务已进入“准备提交/交付/finish”的语境，继续补齐 dual review gate：
+   - 运行/收敛 `$ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`（或回退 `.agentdocs/tmp/review/spec-review.md`）
+   - 运行/收敛 `$ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`（或回退 `.agentdocs/tmp/review/quality-review.md`）
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

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

@@ -1,65 +1,18 @@
 ---
 name: ws-submodule-setup
-description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch；减少 detached 与人为差异）
+description: `aiws submodule-setup` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-submodule-setup
 
-目标：
-- 为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`，让 `ws-pull` / `ws-finish` 能确定性地“挂回分支/fast-forward push”，避免 origin 多分支时靠猜导致偏差。
-- 该变更是 **superproject 的团队真值**：需要提交 `.gitmodules`。
+`aiws submodule-setup` 的薄包装入口。
 
-安全约束（强制）：
-- 不自动提交、不自动 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
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws submodule-setup
+elif command -v aiws >/dev/null 2>&1; then
+  aiws submodule-setup
+else
+  npx @aipper/aiws submodule-setup
+fi
 ```
-
-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

@@ -1,59 +1,18 @@
 ---
 name: ws-verify-before-complete
-description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+description: `aiws verify-bc` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-verify-before-complete
 
-目标：
-- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
-- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+`aiws verify-bc` 的薄包装入口。
 
-阶段定位：
-- 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。
-- 不执行破坏性命令。
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws verify-bc
+elif command -v aiws >/dev/null 2>&1; then
+  aiws verify-bc
+else
+  npx @aipper/aiws verify-bc
+fi
+```

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

@@ -30,3 +30,16 @@ if [[ -z "${aiws_bin:-}" ]]; then
 fi
 
 "$aiws_bin" validate .
+
+# Quality gates (non-blocking warnings)
+if [[ -f "package.json" ]] && grep -q '"lint"' package.json 2>/dev/null; then
+  npm run lint >/dev/null 2>&1 || echo "warn: lint found issues (non-blocking)" >&2
+fi
+
+if [[ -f "packages/aiws/package.json" ]] && grep -q '"build"' packages/aiws/package.json 2>/dev/null; then
+  npm run --workspace packages/aiws build >/dev/null 2>&1 || echo "warn: build/typecheck found issues (non-blocking)" >&2
+fi
+
+if [[ -f "package.json" ]] && grep -q '"test"' package.json 2>/dev/null; then
+  npm test >/dev/null 2>&1 || echo "warn: tests found issues (non-blocking)" >&2
+fi

package/templates/workspace/.githooks/pre-push

@@ -30,3 +30,10 @@ if [[ -z "${aiws_bin:-}" ]]; then
 fi
 
 "$aiws_bin" validate .
+
+# Quality gates — non-blocking (failures downgraded to warning to avoid false positives)
+if [[ -f "$root/package.json" ]]; then
+  npm --prefix "$root" run lint --if-present 2>/dev/null || echo "[aiws] lint: skipped or failed (non-blocking)" >&2
+  npm --prefix "$root" run typecheck --if-present 2>/dev/null || echo "[aiws] typecheck: skipped or failed (non-blocking)" >&2
+  npm --prefix "$root" test --if-present 2>/dev/null || echo "[aiws] test: skipped or failed (non-blocking)" >&2
+fi

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

@@ -0,0 +1,33 @@
+---
+description: 自动 bootstrap：检查 update、确保 watchdog 已启动，并给出下一步
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-auto -->
+# ws auto
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为当前 OpenCode 工作区执行一次显式 auto bootstrap，先补齐托管内容，再按条件启动 watchdog。
+
+执行建议：
+1) 先运行 `/ws-preflight`，确认 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 已读取。
+2) 在项目根运行 `aiws opencode auto .`。
+3) 输出：
+   - `Auto Bootstrap:`
+   - `Update:`
+   - `OpenCode mode:`
+   - `Watchdog:`
+   - `Next:`
+4) 若输出 `watchdog:` 为已启动状态：
+   - 若当前任务意图明确：继续 `/using-aiws`、`/ws-plan`、`/ws-dev` 或 `/ws-review`
+   - 若当前只是要声明自主协作合同：继续 `/ws-autonomy`
+5) 若输出 `watchdog: skipped (...)`：
+   - 明确写出原因
+   - 不要假装已经进入 autonomous 模式
+
+边界：
+- 允许通过 `aiws update .` 刷新 AIWS 托管内容。
+- 不自动复制 `.opencode/oh-my-opencode.json.example` 成真实配置。
+- 不自动批准 host permission，不自动执行 tmux rescue。
+<!-- AIWS_MANAGED_END:opencode:ws-auto -->
+
+可在下方追加本项目对 auto bootstrap 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,25 @@
+---
+description: 自主协作实验：声明 completion/retry/rescue 合同，并按需启用 tmux helper
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-autonomy -->
+# ws autonomy
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：声明当前 OpenCode/oMo 任务的 autonomous execution mode，并写清 completion/retry/rescue 合同。
+
+执行建议：
+1) 先运行 `/ws-preflight`，再读取 `packages/spec/docs/opencode-autonomous-swarm.md` 与 `packages/spec/docs/opencode-omo-adapter.md`。
+2) 输出：
+   - `Execution Mode: single-agent / omo-native / omo-native + tmux-swarm`
+   - `Completion Contract:`
+   - `Retry Contract:`
+   - `Rescue Policy:`
+   - `Evidence:`
+3) 若选择 `omo-native + tmux-swarm`：
+   - 先运行 `.opencode/helpers/tmux-swarm-scan.sh`
+   - 仅在需要安全白名单救援时运行 `.opencode/helpers/tmux-swarm-rescue.sh`
+4) 明确这是实验层，不接管 runtime controller，不替代 `ws-plan` / `ws-dev` / `ws-review`。
+<!-- AIWS_MANAGED_END:opencode:ws-autonomy -->
+
+可在下方追加本项目对 autonomous swarm 的额外说明（托管块外内容会被保留）。

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

@@ -19,7 +19,11 @@ description: 评审：提交前审计改动并落盘证据
 3) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
-4) 回复中输出：
+4) 若当前任务已进入“准备提交/交付/finish”的语境，继续补齐 dual review gate：
+   - 运行/收敛 `/ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`
+   - 运行/收敛 `/ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

package/templates/workspace/.opencode/commands/ws-auto.md

@@ -0,0 +1,33 @@
+---
+description: 自动 bootstrap：检查 update、确保 watchdog 已启动，并给出下一步
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-auto -->
+# ws auto
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为当前 OpenCode 工作区执行一次显式 auto bootstrap，先补齐托管内容，再按条件启动 watchdog。
+
+执行建议：
+1) 先运行 `/ws-preflight`，确认 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 已读取。
+2) 在项目根运行 `aiws opencode auto .`。
+3) 输出：
+   - `Auto Bootstrap:`
+   - `Update:`
+   - `OpenCode mode:`
+   - `Watchdog:`
+   - `Next:`
+4) 若输出 `watchdog:` 为已启动状态：
+   - 若当前任务意图明确：继续 `/using-aiws`、`/ws-plan`、`/ws-dev` 或 `/ws-review`
+   - 若当前只是要声明自主协作合同：继续 `/ws-autonomy`
+5) 若输出 `watchdog: skipped (...)`：
+   - 明确写出原因
+   - 不要假装已经进入 autonomous 模式
+
+边界：
+- 允许通过 `aiws update .` 刷新 AIWS 托管内容。
+- 不自动复制 `.opencode/oh-my-opencode.json.example` 成真实配置。
+- 不自动批准 host permission，不自动执行 tmux rescue。
+<!-- AIWS_MANAGED_END:opencode:ws-auto -->
+
+可在下方追加本项目对 auto bootstrap 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-autonomy.md

@@ -0,0 +1,25 @@
+---
+description: 自主协作实验：声明 completion/retry/rescue 合同，并按需启用 tmux helper
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-autonomy -->
+# ws autonomy
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：声明当前 OpenCode/oMo 任务的 autonomous execution mode，并写清 completion/retry/rescue 合同。
+
+执行建议：
+1) 先运行 `/ws-preflight`，再读取 `packages/spec/docs/opencode-autonomous-swarm.md` 与 `packages/spec/docs/opencode-omo-adapter.md`。
+2) 输出：
+   - `Execution Mode: single-agent / omo-native / omo-native + tmux-swarm`
+   - `Completion Contract:`
+   - `Retry Contract:`
+   - `Rescue Policy:`
+   - `Evidence:`
+3) 若选择 `omo-native + tmux-swarm`：
+   - 先运行 `.opencode/helpers/tmux-swarm-scan.sh`
+   - 仅在需要安全白名单救援时运行 `.opencode/helpers/tmux-swarm-rescue.sh`
+4) 明确这是实验层，不接管 runtime controller，不替代 `ws-plan` / `ws-dev` / `ws-review`。
+<!-- AIWS_MANAGED_END:opencode:ws-autonomy -->
+
+可在下方追加本项目对 autonomous swarm 的额外说明（托管块外内容会被保留）。

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

@@ -4,67 +4,15 @@ description: 提交：门禁/审计后提交（submodule 感知）
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-commit -->
 # ws commit
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws commit`.
 
-目标：在**当前分支可直提**的前提下，先做审计与门禁，并在存在 submodule 时给出正确的提交顺序（先 submodule，再 superproject），最后执行 `git commit`。
-补充：若你经常遇到 submodule detached，建议日常拉取优先使用 `/ws-pull`（尽量把 submodule “挂回分支”且不改变 gitlink commit）。
-
-安全约束（强制）：
-- 不自动 `git add -A`；只在用户明确指示时才做 staging
-- 不使用 `--no-verify` 绕过 hooks
-- 不自动 push
-- 不打印 secrets
-- commit message 优先使用中文；若启用了 `.githooks/commit-msg`，默认仅提示，只有 strict 模式才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
-
-步骤（建议）：
-1) 先运行 `/ws-preflight`。
-2) 运行 `/ws-review`（优先落盘审计证据到 `changes/<change-id>/review/`）。
-3) 运行门禁校验并写 stamp：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws validate . --stamp
+  ./node_modules/.bin/aiws commit -m "<message>"
 elif command -v aiws >/dev/null 2>&1; then
-  aiws validate . --stamp
+  aiws commit -m "<message>"
 else
-  npx @aipper/aiws validate . --stamp
-fi
-```
-4) 输出提交上下文（必须输出给用户确认）：
-```bash
-git branch --show-current
-git status --porcelain
-```
-5) submodule 感知检查：
-```bash
-if [[ -f .gitmodules ]]; then
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+  npx @aipper/aiws commit -m "<message>"
 fi
-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；先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
-- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`。
-6) 检查 staging（必须输出给用户确认）：
-```bash
-git status --porcelain
-git diff --staged --submodule=short
-```
-7) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-8) 优先生成并确认中文 commit message（格式建议：`<类型>: <简述>`；若用户明确要求英文也可保留，但 strict 模式下会被 hook 拒绝）。
-9) 执行提交（不带 `--no-verify`）：
-```bash
-git commit -m "<message>"
-```
-
-输出必须包含：
-- `证据（Evidence）:` `changes/<change-id>/review/*`（无 change-id 时回退 `.agentdocs/tmp/review/*`） + `.agentdocs/tmp/aiws-validate/*`
-- `上下文（Context）:` 当前分支 + 是否检测到 submodule + 若阻断则给出阻断原因
-- `下一步（Next）:` 若存在 submodule 改动，先提示用户进入 submodule 提交
 <!-- AIWS_MANAGED_END:opencode:ws-commit -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -4,55 +4,15 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-deliver -->
 # ws deliver
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws deliver`.
 
-目标：适配 superproject + submodule（数量不固定）的交付收尾，降低提交顺序和合并回 base 分支的出错概率：
-1) 先逐个提交 submodule（每个 repo 单独确认 commit message；默认 `git add -p`）
-2) 再提交 superproject（包含 submodule gitlink 指针更新 + 自身改动/变更工件）
-3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `/ws-finish`）
-
-强制约束：
-- 不自动 `git add -A`。
-- 不自动 push。
-- 不自动删除分支。
-
-建议流程（按顺序）：
-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`
-   - 先说明该 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 单独确认）
-   - `git -C "<sub_path>" commit -m "<message>"`
-4) 提交 superproject（gitlinks + 自身改动）：
-   - `git diff --submodule`
-   - `git add <submodule-path-1> <submodule-path-2> ...`
-   - `git add -p`
-   - 生成并让用户确认 superproject 的 commit message
-   - `git commit -m "<message>"`
-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) 安全合并回目标分支：
-   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
-
-输出要求：
-- `Submodules:` 每个 submodule 的 commit 摘要（repo/path → sha → message）
-- `Superproject:` commit 摘要
-- `Merge:` `/ws-finish` 输出（into/from）
-- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
-- `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws deliver -m "<message>"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws deliver -m "<message>"
+else
+  npx @aipper/aiws deliver -m "<message>"
+fi
+```
 <!-- AIWS_MANAGED_END:opencode:ws-deliver -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -1,5 +1,5 @@
 ---
-description: 收尾：fast-forward 合并并把 submodule 并回目标分支后顺序 push
+description: 收尾：fast-forward 合并并把 submodule 并回目标分支后顺序 push。完成后标记 finish 阶段为 DONE
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-finish -->
 # ws finish
@@ -70,6 +70,14 @@ fi
 安全：
 - push 前先输出状态并说明远端/分支。
 - 不执行破坏性命令。
-<!-- AIWS_MANAGED_END:opencode:ws-finish -->
 
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws finish
+elif command -v aiws >/dev/null 2>&1; then
+  aiws finish
+else
+  npx @aipper/aiws finish
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:ws-finish -->

package/templates/workspace/.opencode/commands/ws-handoff.md

@@ -1,26 +1,18 @@
 ---
-description: 交接：查看归档 change 的 handoff.md（标准由 aiws change finish --push 自动归档生成）
+description: 交接：查看归档 change 的 handoff.md
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-handoff -->
 # ws handoff
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws handoff`.
 
-目标：
-- 交接与回放：通过 `handoff.md` 让已归档的 change 可被下一位/下一次会话快速接力。
-- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（默认由 `aiws change finish --push` 自动归档时生成）。
-
-执行建议：
-1) 先确认 change 已通过 `/ws-finish` 或 `aiws change finish --push` 完成自动归档。
-2) 查看 handoff：
 ```bash
-change_id="<change-id>"
-ls -1 changes/archive/*-"${change_id}"/handoff.md
-sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws handoff
+elif command -v aiws >/dev/null 2>&1; then
+  aiws handoff
+else
+  npx @aipper/aiws handoff
+fi
 ```
-3) 依赖提示：
-- 若你在某个 change 的 `proposal.md` 声明了 `Depends_On`，`aiws change start` 会尝试读取依赖 change 的 `handoff.md` 并输出摘要（前提：依赖已归档且 handoff 存在）。
-- 若是历史/异常场景尚未归档，再手工运行 `/p-aiws-change-archive`。
 <!-- AIWS_MANAGED_END:opencode:ws-handoff -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-migrate.md

@@ -4,22 +4,15 @@ description: 迁移：把仓库对齐到 aiws workspace 模板
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-migrate -->
 # ws migrate
 
-用中文输出；命令与路径保持原样不翻译。
+Thin CLI wrapper. Delegates to `aiws migrate`.
 
-目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
-
-执行（在项目根目录）：
-1) 若已存在 `.aiws/manifest.json`：`npx @aipper/aiws update .`
-2) 否则：`npx @aipper/aiws init .`
-3) 门禁校验：`npx @aipper/aiws validate .`
-4) 启用本机 git hooks（推荐，本地生效）：`git config core.hooksPath .githooks`
-
-回滚：
-- 恢复最近一次快照：`npx @aipper/aiws rollback . latest`
-
-约束：
-- 不写入任何 secrets。
-- 不执行破坏性命令。
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws migrate
+elif command -v aiws >/dev/null 2>&1; then
+  aiws migrate
+else
+  npx @aipper/aiws migrate
+fi
+```
 <!-- AIWS_MANAGED_END:opencode:ws-migrate -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-plan-verify.md

@@ -1,28 +1,18 @@
 ---
-description: 计划质检：执行前检查并给出最小修正项
+description: 计划质检：执行前检查并给出最小修正项。通过后标记 plan 阶段为 DONE
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-plan-verify -->
 # ws plan verify
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+Thin CLI wrapper. Delegates to `aiws plan-verify`.
 
-目标：
-- 执行前检查计划是否跑偏，并给出最小修正项。
-
-执行建议：
-1) 先运行 `/ws-preflight`。
-2) 运行严格门禁：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change validate <change-id> --strict
+  ./node_modules/.bin/aiws plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change validate <change-id> --strict
+  aiws plan-verify
 else
-  npx @aipper/aiws change validate <change-id> --strict
+  npx @aipper/aiws plan-verify
 fi
 ```
-3) 若失败：先修 `proposal.md` / `plan` 的绑定字段与验证命令，再复跑。
-4) 通过后再进入 `/ws-dev`。
 <!-- AIWS_MANAGED_END:opencode:ws-plan-verify -->
-
-可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。