@aipper/aiws-spec 0.0.24 → 0.0.25

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

@@ -0,0 +1,110 @@
+---
+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/.opencode/skills/ws-quality-review/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ws-quality-review
+description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动的行为正确性、边界条件、测试覆盖和实现质量
+- 把“代码/行为层 findings”优先落盘到 `changes/<change-id>/review/quality-review.md`
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore`，优先借用这些 agent 做质量审查。
+- `@oracle` 优先负责独立质量/回归审查；`@explore` 负责补代码路径、依赖关系和影响面探索。
+- 主 agent 负责把 findings / gaps / next 收敛并落盘。
+
+阶段定位：
+- review 子 gate；负责实现质量、行为回归与验证覆盖审查。
+
+必需输入：
+- 当前 `git diff`
+- 已执行的验证结果
+- 相关代码 / 配置 / 测试文件
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 review 文件
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/quality-review.md` 或回退 `.agentdocs/tmp/review/quality-review.md`
+- `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
+- `下一步（Next）:` 最小修复项与回归命令
+
+阻断条件：
+- 没有可审改动
+- 没有任何验证上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 quality review 证据，且 findings / 测试缺口 / next 明确。
+
+步骤（建议）：
+1) 先读取 `git diff`、验证结果与相关代码。
+   - 若检测到 oMo：优先让 `@oracle` 做 quality review 草稿；必要时再调用 `@explore` 补代码路径上下文。
+2) 检查：
+   - 行为是否可能回归
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑改动
+   - 是否存在明显复杂度、耦合、可维护性或性能问题
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是质量 / 回归 review，不替代 requirements / gate review。
+- 若发现流程、归因、evidence 缺口，转交给 `$ws-spec-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+- 若 oMo agent 不可用，回退为当前 agent 本地 quality review。

package/templates/workspace/.opencode/skills/ws-req-change/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ws-req-change
+description: 需求变更（更新 REQUIREMENTS 并同步执行合同）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `REQUIREMENTS.md` + 追加 `requirements/CHANGELOG.md`），并同步/校验执行合同 `requirements/requirements-issues.csv`。
+
+步骤（必须按顺序）：
+1) 读取：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`requirements/CHANGELOG.md`（缺失则创建目录与文件）。
+2) 先产出“拟变更方案”（不要立刻写文件）：
+   - 变更摘要（1–5 条）
+   - 影响范围（API/鉴权/字段/状态码/测试边界）
+   - 回滚思路（1–2 条）
+3) 对比与冲突检查（强制，不写文件）：
+   - 对比“变更前 vs 拟变更后”的差异清单（新增/删除/语义变化）
+   - 整理潜在冲突/不确定点（只列“最可能影响验收/实现”的，避免噪音）
+4) 逐条澄清（强制，避免一次问完）：
+   - 若存在潜在冲突/不确定点：**本轮只问 1 个**最高优先级问题（给出 2–4 个可选答案或二选一），然后停止，等待用户回复；不要继续问下一题，也不要写文件。
+   - 收到用户回复后：更新“拟变更方案”，回到步骤 3) 重新对比，直至没有未决问题。
+5) 强制停下来让用户确认：是否继续落盘？(Y/N)
+6) 用户确认 Y 后再写入：
+   - 更新 `REQUIREMENTS.md`（只保留当前有效版本，不在此堆历史）
+   - 追加 `requirements/CHANGELOG.md`
+7) 同步/补齐需求执行合同（强制，自动处理 FlowSpec 有/无两种情况）：
+   - `python3 tools/requirements_contract_sync.py --workspace .`
+   - 说明：若 `REQUIREMENTS.md` 中不存在 FlowSpec（或 flows 为空），该命令只会确保 `requirements/requirements-issues.csv` 表头存在并给出 WARN（这是预期行为，不要当成失败）。
+8) 校验需求执行合同（强制）：`python3 tools/requirements_contract.py validate`
+9) 同步场景合同（可选，但若存在 FlowSpec 则强烈建议自动执行）：
+   - 若 `REQUIREMENTS.md` 同时包含 `<!-- FLOW_SPEC_BEGIN -->` 与 `<!-- FLOW_SPEC_END -->`：运行 `$ws-req-flow-sync`
+   - 否则：跳过，并提示用户“可以先不维护 FlowSpec；后续需要场景回归时再补”
+
+输出必须包含：
+- 本次更新的文件清单（路径）
+- 回滚方案（如何撤销本次需求变更）
+- 下一步建议命令
+
+安全：
+- 不打印 `secrets/test-accounts.json`
+- 不引入任何 token/密钥到仓库

package/templates/workspace/.opencode/skills/ws-req-contract-sync/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ws-req-contract-sync
+description: 合同同步（requirements contract sync）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+用途：从 `REQUIREMENTS.md` 的 FlowSpec 补齐 `requirements/requirements-issues.csv`（只生成骨架，不猜测完成状态）。
+
+执行（在 workspace 根目录）：
+- `python3 tools/requirements_contract_sync.py --workspace .`
+
+输出要求：
+- 说明新增/更新了多少条
+- 明确下一步：手工补齐 CRUD/Inputs/Outputs/Business_Logic/Tests，并将可开工条目标为 `Spec_Status=READY`
+
+下一步建议：`$ws-req-contract-validate`

package/templates/workspace/.opencode/skills/ws-req-contract-validate/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: ws-req-contract-validate
+description: 合同校验（requirements contract validate）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议

package/templates/workspace/.opencode/skills/ws-req-flow-sync/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ws-req-flow-sync
+description: Flow 同步（生成 api-flow 与场景执行合同）
+---
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `REQUIREMENTS.md` 的 FlowSpec 生成：
+- `docs/api-flow.mmd`（简短逻辑图，Mermaid）
+- `issues/server-scenario-issues.csv`（场景执行合同：TODO/DONE/BLOCKED）
+
+执行（在 workspace 根目录）：
+`python3 tools/requirements_flow_gen.py --workspace .`
+
+若缺少工具 `tools/requirements_flow_gen.py`：提示用户先运行 `$aiws-init`（默认会安装 optional tools），或执行：
+```bash
+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
+```
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`

package/templates/workspace/.opencode/skills/ws-req-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: ws-req-review
+description: 需求评审（对齐真值与验收）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+   - `requirements/CHANGELOG.md`（若存在）
+   - `requirements/requirements-issues.csv`（若存在）
+3) 输出固定结构的报告：
+
+## Requirements QA
+- 结论：是否可进入实现（是/否/有条件）
+- 漂移风险：最容易导致不一致的点
+- 可验收性缺口：缺少输入/输出/错误码/边界/示例的条目
+- 完整性：Non-goals/兼容性/鉴权/重试/并发/观测性/性能
+- 一致性：与 `AI_PROJECT.md` 约束冲突点
+- 可测试性与证据：最小验证命令 + 期望结果 + 证据路径
+- 风险清单：3–8 条
+- 需要澄清的问题：5–12 个（按优先级）
+
+4) 最后询问用户：是否进入需求落盘流程 `$ws-req-change`？(Y/N)
+
+安全：不打印 `secrets/test-accounts.json`。

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

@@ -0,0 +1,57 @@
+---
+name: ws-review
+description: 评审（提交前审计与证据落盘）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore` / `librarian`，优先借用这些 agent 做 review。
+- `@oracle` 优先负责独立审查与 findings；`@explore` 用于补 diff 影响面；`@librarian` 用于补 requirements / docs / 依赖上下文。
+- 主 agent 必须负责把 findings 收敛并落盘，不要把子 agent 输出直接当最终 review 结论。
+
+阶段定位：
+- review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
+
+必需输入：
+- 当前 `git status` / `git diff`
+- 已执行的验证结果
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前 `change/<change-id>` 上下文（若能识别）
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
+
+必需输出：
+- 审计文件：`changes/<change-id>/review/codex-review.md` 或回退 `.agentdocs/tmp/review/codex-review.md`
+- `主要风险（Top risks）:` 3-8 条
+- `下一步（Next）:` 最小修复清单 + 最小验证命令
+
+阻断条件：
+- 没有可审计的改动或验证上下文
+- 审计证据无法写盘
+
+完成判定：
+- 审计证据已落盘，主要风险和下一步已明确，可作为 commit/deliver 前置输入。
+
+步骤（建议）：
+1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+   - 若检测到 oMo：优先让 `@oracle` 做独立审查；必要时再让 `@explore` / `@librarian` 补上下文。
+2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+   - 是否存在越界目录改动/危险操作
+   - 是否有可复现验证命令与证据
+   - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+   - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
+3) 将审计落盘到（目录不存在则创建）：
+   - 默认：`changes/<change-id>/review/codex-review.md`
+   - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
+   - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
+4) 回复中输出：
+   - `证据（Evidence）:` 证据文件路径
+   - `主要风险（Top risks）:` 3–8 条（高→低）
+   - `下一步（Next）:` 最小修复清单 + 最小验证命令
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+- 若 oMo agent 不可用，回退为当前 agent 本地 review，不阻断流程。

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

@@ -0,0 +1,23 @@
+---
+name: ws-rule
+description: 规则（解释项目规则与边界）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+安全规则（强制）：
+- 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+- 不执行破坏性命令。
+
+工作流：
+1) 先做 preflight；若缺失 `AI_PROJECT.md`：提示用户先 `$ws-migrate`（或 `$aiws-init`）。
+2) 写入前创建备份（必须）：
+`ts="$(date +%Y%m%d-%H%M%S)"; mkdir -p .aiws/backups/manual; cp -a AI_PROJECT.md .aiws/backups/manual/AI_PROJECT.md.bak.${ts}`
+3) 先输出“将写入的规则清单”（3–12 条），并要求用户回复 `CONFIRM` 后再落盘。
+4) 用户确认后，**仅更新** BEGIN/END 段内内容（合并去重；写成可检查条款：目录白名单/必须验证命令/禁止项/产物要求）。
+5) 输出必须包含：
+   - 更新了哪些文件（路径）
+   - 回滚方式（恢复备份文件）
+   - 下一步建议：`$aiws-validate`

package/templates/workspace/.opencode/skills/ws-spec-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ws-spec-review
+description: 规范审查（requirements / plan / evidence / gate 完整性）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动是否满足真值文件、change 绑定、证据路径和 gate 完整性要求
+- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `changes/<change-id>/review/spec-review.md`
+
+OpenCode + oMo 优先策略：
+- 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `librarian`，优先借用它们做 spec / gate 审查。
+- `@oracle` 优先负责 requirements / gate / evidence 独立审查；`@librarian` 负责补文档、规范、依赖与路径真值。
+- 主 agent 负责把 blocker / warning / next 收敛到最终 review 文件。
+
+阶段定位：
+- review 子 gate；负责 requirements / plan / evidence / workflow gate 完整性审查。
+
+必需输入：
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 当前 `git diff`
+- 若存在：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/spec-review.md` 或回退 `.agentdocs/tmp/review/spec-review.md`
+- `阻断项（Blockers）:` requirements 归因 / gate / evidence 缺口
+- `下一步（Next）:` 修复项与最小验证命令
+
+阻断条件：
+- 无法定位项目根或真值文件
+- 无法判断当前 change / 归因上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 spec review 证据，且明确指出 blocker / warning / next。
+
+步骤（建议）：
+1) 先运行 `$ws-preflight`。
+   - 若检测到 oMo：优先让 `@oracle` 做 spec review 草稿；需要补规范上下文时再调用 `@librarian`。
+2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+   - 当前改动能否归因到 `Req_ID` / `Problem_ID`
+   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否与改动保持一致
+   - 是否存在越界目录改动、危险操作、未声明的非目标扩张
+   - 是否已经准备好可复现验证入口
+3) 把结论落盘到：
+   - 默认：`changes/<change-id>/review/spec-review.md`
+   - 回退：`.agentdocs/tmp/review/spec-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `阻断项（Blockers）:`
+   - `警告（Warnings）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是 spec / gate review，不是代码质量 review。
+- 若发现实现质量或回归问题，转交给 `$ws-quality-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+- 若 oMo agent 不可用，回退为当前 agent 本地 spec review。

package/templates/workspace/.opencode/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/.opencode/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。
+- 不执行破坏性命令。