@aipper/aiws-spec 0.0.29 → 0.0.30

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

@@ -23,11 +23,32 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 - `证据（Evidence）:` `plan/...`、`changes/<change-id>/...`、`.agentdocs/tmp/...` 等证据路径
 - `Next:` 若准备提交，建议 `$ws-review` 或 `$ws-commit`
 
-## 阻断条件
+## 前置条件（硬阻断 — 必须最先检查）
 
-- 无法把改动归因到 `REQUIREMENTS.md` 或问题单
-- 没有可复现验证入口
-- 需要创建 change 上下文但当前工作区状态不允许安全切换
+在开始任何代码改动之前，必须完成以下检查：
+
+1. **Design Gate**：若 `changes/<change-id>/proposal.md` 不存在：
+   - 立即停止，不要写代码
+   - 输出：`BLOCKED: 缺少 proposal。请先执行 $ws-plan 创建变更计划与任务分解。`
+2. **Task Gate**：若 `changes/<change-id>/tasks.md` 不存在：
+   - 立即停止，不要写代码
+   - 输出：`BLOCKED: 缺少 tasks。请先执行 $ws-plan 创建任务分解。`
+
+> 例外：`ws-dev-lite` 是轻量入口，可豁免 Design Gate，但仅限单文件/typo/config/bugfix 场景。
+
+## TDD 约束（强制）
+
+对于所有需要编写新代码或修改业务逻辑的任务，必须遵守 RED-GREEN-REFACTOR 流程：
+
+1. **RED**：先编写测试用例，运行并确认测试失败（或确认现有测试覆盖缺口）
+2. **GREEN**：编写最小实现代码使测试通过
+3. **REFACTOR**：重构代码，保持测试通过
+
+禁止：
+- 先写实现代码再补测试
+- 跳过测试步骤直接提交
+
+自我检查顺序（每次修改后）：`lint → typecheck → test`。若项目无对应脚本则跳过该项。
 
 ## 完成判定
 
@@ -40,9 +61,18 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
 
 - 中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件。
+- 中大型任务默认执行 [3.1 自我修正循环](#31-自我修正循环evaluate-optimize)——这是必经步骤，不是可选项：实现后先自审修正（最多 2 轮），再进入 review
 - 已有计划：先 `$ws-plan-verify`，通过后进入实现。
 - `$ws-plan` 已创建 worktree：直接在该 worktree 中继续。
 
+### 1.5 Spec Refresh（进入实现前必做）
+
+在开始任何代码改动前，强制重读并输出摘要：
+- `AI_PROJECT.md` 安全边界（哪些目录不能动、哪些约束必须遵守）
+- `REQUIREMENTS.md` 中与本次 `Req_ID` 相关的条目（摘要 2-3 段即可）
+
+目的：避免落地时遗忘约束或需求边界。仅需 2-3 段摘要，不需要全文复读。
+
 ### 2. 建立变更归因
 
 - 若 `git status --porcelain` 仅有计划/工件文件，属于预期行为，继续即可。
@@ -60,6 +90,24 @@ description: 使用时机：需要修改代码、配置、测试时。触发词
 - 根据 review 结果决定 fix 或收敛 evidence
 - **Inline escape hatch**：如果用户明确说"你直接改"或"do it inline"，主 session 可直接写代码，但必须落盘 evidence 记录理由
 
+**验证先行推荐**：对于非 trivial 改动，建议先确认验证入口再开始实现：
+1. 先确认 `AI_WORKSPACE.md` 中对应的验证命令
+2. 若验证命令不明确：先补验证入口，再开始实现
+3. 可选模式（不强求 TDD）：先写最小验证 → 实现 → 补完整验证
+
+### 3.1 自我修正循环（evaluate-optimize）——必经步骤
+
+在 dispatch subagent 前，主 session 必须执行最多 **2 轮** 自审+修正循环：
+
+1. **实现** → subagent 产出代码
+2. **自审** → 主 session 检查：lint/type-check 是否通过？是否符合现有代码模式？是否有明显 bug？
+3. **修正** → 如果发现问题，要求 subagent 修正后重新提交
+4. **2 轮上限** → 如果 2 轮后仍有问题，升级到 `$ws-review` 做正式审查
+
+**适用场景**：所有非 trivial 改动（单文件修复、配置调整、小步实现、中大型任务均适用）。不适合跨模块架构变更——此类变更直接走 $ws-review。
+
+**注意**：这不是替代 `$ws-review` 的门禁；自审通过后仍需走正式 review gate。
+
 ### 4. 其他规则
 
 - 需求调整：先 `$ws-req-review` → 确认后 `$ws-req-change`

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

@@ -14,8 +14,10 @@ description: 使用时机：单文件/小范围快速修复时。触发词：轻
 适用前提：
 - 目标明确，且能归因到 `Req_ID` 或 `Problem_ID`
 - 验证入口明确，且能做最小可复现验证
-- 一般只影响单文件或紧密相关的小范围文件
+- 一般只影响单文件或紧密相关的小范围文件（≤2 文件，≤100 行）
 - 不需要先改 `REQUIREMENTS.md`，也不需要先单独做 review
+- 仅限以下场景：typo 修复、配置调整、已知回归修复、单点 bugfix
+- 禁止用于：新 feature 开发、跨模块重构、架构变更
 
 立即升级回主流程的情形：
 - 发现任务其实是 medium/complex、跨模块、跨目录或需要方案设计
@@ -25,6 +27,7 @@ description: 使用时机：单文件/小范围快速修复时。触发词：轻
 
 默认约束：
 - 先做 `$ws-preflight`
+- **Escape Hatch**：若用户明确说"跳过流程"/"直接改"，允许 early-start 实现，但必须输出 `[escape-hatch: direct-implementation]` 标记，并仍然遵守最小约束（归因、验证、evidence）
 - 默认不创建 `plan/...`
 - 默认不跑 `$ws-plan-verify`
 - 默认不要求先做双 review

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

@@ -1,18 +1,22 @@
 ---
 name: ws-finish
-description: Thin wrapper for `aiws ws-finish`
+description: `aiws finish` 的收尾入口（finish_resume_required）
 ---
 
 # ws-finish
 
-Thin skill wrapper. Delegates to `aiws ws-finish`. See `aiws ws-finish --help` for details.
+`aiws finish` 的收尾入口。
+
+关键契约：
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`，继续执行 `aiws change finish <change-id> --push`
+- 普通 finish 的 `validate/evidence/state` 仍应在 `change/<change-id>` worktree 完成，不要在目标 worktree 里跑 `aiws validate . --stamp`
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-finish
+  ./node_modules/.bin/aiws finish
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-finish
+  aiws finish
 else
-  npx @aipper/aiws ws-finish
+  npx @aipper/aiws finish
 fi
 ```

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

@@ -1,18 +1,18 @@
 ---
 name: ws-handoff
-description: Thin wrapper for `aiws ws-handoff`
+description: Thin wrapper for `aiws handoff`
 ---
 
 # ws-handoff
 
-Thin skill wrapper. Delegates to `aiws ws-handoff`. See `aiws ws-handoff --help` for details.
+Thin skill wrapper. Delegates to `aiws handoff`. See `aiws handoff --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-handoff
+  ./node_modules/.bin/aiws handoff
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-handoff
+  aiws handoff
 else
-  npx @aipper/aiws ws-handoff
+  npx @aipper/aiws handoff
 fi
 ```

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

@@ -10,6 +10,35 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
 - 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论。
 - 产出一份可被 `/ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`。
 
+## 发散-收敛两子阶段
+
+当需求模糊、方向不明确时，intake 分两子阶段推进：
+
+### 发散阶段（Explore）
+- 目标：快速探索 2-3 个可能方向，不深入任何单一方向
+- 输出：每个方向的 1-2 段摘要 + 关键风险 + 依赖
+- 时限：不超过 3 轮对话
+
+### 收敛阶段（Converge）
+- 目标：从发散结果中选择 1 个方向，逐条冻结具体问题
+- 回到标准"一题一线程"模式
+- 把发散产出的摘要作为收敛的输入上下文
+
+触发条件：用户说"不确定"/"多个方向"/"帮我分析" 等模糊表达。
+非模糊需求不需要经过发散阶段，直接进入收敛。
+
+## 核心原则：一次一个问题
+
+- 每轮只推进 1 个 `Open Questions` 中的问题
+- 当前问题未标记 `frozen` 或 `deferred` 前，不进入下一题
+- 输出格式：`Current question → Why it matters → Options → Exit condition`
+- 用户选择后立即写盘更新草案，再进入下一题
+
+**队列保护**：若用户一次提出多个问题，必须显式建队（Queue），逐一处理——不可同时推进多个维度。队列格式：
+- Queue: [Q1: ..., Q2: ..., Q3: ...]
+- Current: Q1
+- Status: [open/in_discussion/frozen/deferred] per item
+
 执行要求：
 1) 先读 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，必要时先 `/ws-preflight`。
 2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
@@ -18,8 +47,9 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
    - `Current question:`
    - `Why it matters:`
    - `Current options / current understanding:`
-   - `Exit condition:`
-5) 当前问题在没有被标记成 `frozen` 或 `deferred` 前，不进入下一题。
+    - `Exit condition:`
+- 每个问题独立线程：在未标记 frozen/deferred 前，不进入下一题。问答往返不限轮数，但一次只处理一个维度的决策。
+5) 若用户一次提出多个问题，必须显式排队：列出所有问题编号，按顺序逐个处理；不得同时推进多个问题的讨论。输出格式：`Queued questions: #1, #2, ...  | Current: #1`
 6) 每轮都要把 intake 草案写盘，至少包含：
    - `Context`
    - `Open Questions`

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

@@ -1,18 +1,18 @@
 ---
 name: ws-migrate
-description: Thin wrapper for `aiws ws-migrate`
+description: Thin wrapper for `aiws migrate`
 ---
 
 # ws-migrate
 
-Thin skill wrapper. Delegates to `aiws ws-migrate`. See `aiws ws-migrate --help` for details.
+Thin skill wrapper. Delegates to `aiws migrate`. See `aiws migrate --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-migrate
+  ./node_modules/.bin/aiws migrate
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-migrate
+  aiws migrate
 else
-  npx @aipper/aiws ws-migrate
+  npx @aipper/aiws migrate
 fi
 ```

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

@@ -52,41 +52,15 @@ OpenCode + oMo 优先策略：
    - 若检测到 oMo：优先让 `planner-sisyphus` 生成 planning draft；若需要补结构探索，再委托 `@explore` / `@librarian`。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
 3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
-4) 识别或建立主索引 / change 上下文：
+ 4) 识别或建立主索引 / change 上下文：
    - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
    - 若缺失关键绑定：先补齐 proposal（至少 `Change_ID`、`Req_ID|Problem_ID`、`Contract_Row`）再继续生成计划
-   - 若当前不在 `change/<change-id>` 分支 / worktree，且本次任务需要新建 change：先调用 `aiws change start` 建立上下文，再继续写 plan
-   - 推荐顺序：
-     - 工作区已存在未提交改动：不要先写 `plan/...`；先停下来说明原因，并要求用户先 commit/stash，或改用已有 change 上下文
-     - 仓库已有提交：优先创建独立 worktree；若仓库声明了 submodules，加上 `--submodules`
-     - 仓库尚无提交 / 不满足 worktree 前置条件：回退为 `--no-switch`
-```bash
-change_id="<change-id>"
-if [[ -n "$(git status --porcelain)" ]]; then
-  echo "error: working tree dirty before ws-plan creates change context"
-  echo "hint: commit/stash first, or continue inside an existing change/<change-id> context"
-  exit 2
-fi
-
-has_commits=0
-git rev-parse --verify HEAD >/dev/null 2>&1 && has_commits=1
-
-has_submodules=0
-if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
-  has_submodules=1
-fi
-
-if [[ "${has_commits}" -eq 1 ]]; then
-  if [[ "${has_submodules}" -eq 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：后续所有读取/写入都必须切到 `aiws change start` 输出的 `worktree:` 路径中进行；不要把 `plan/...` 写回原工作区
+   - 若当前不在 `change/<change-id>` 分支 / worktree，且本次任务需要新建 change：
+     ```bash
+     bash .opencode/scripts/ws-plan-setup-worktree.sh <change-id>
+     ```
+     脚本自动处理：dirty 检查、commits/submodules 检测、worktree 创建。
+   - 若脚本创建了 worktree：后续所有读取/写入都必须切到 `aiws change start` 输出的 `worktree:` 路径中进行；不要把 `plan/...` 写回原工作区
 5) 生成计划文件：
    - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
    - 若 `plan/` 不存在先创建
@@ -122,26 +96,10 @@ oMo 回退：
     - 第 1 列：submodule path（例如 `vendor/foo`）
     - 第 2 列：target branch（例如 `release/channel-a`）
     - 第 3 列（可选）：remote 名（默认 `origin`）
-- 生成模板（建议在确认 `Change_ID` 后执行；如文件已存在先备份再覆盖）：
-```bash
-change_id="<change-id>"
-targets="changes/${change_id}/submodules.targets"
-mkdir -p "changes/${change_id}"
-if [[ -f "${targets}" ]]; then
-  bak="${targets}.bak.$(date -u +%Y%m%d-%H%M%SZ)"
-  cp "${targets}" "${bak}"
-  echo "info: backup: ${bak}"
-fi
-: > "${targets}"
-echo "# path<TAB>target_branch<TAB>remote(optional, default=origin)" >> "${targets}"
-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)"
-  [[ "${b:-}" == "." ]] && b="$(git branch --show-current)"  # '.' means "follow superproject branch"
-  printf "%s\t%s\t%s\n" "${sub_path}" "${b:-<fill-me>}" "origin" >> "${targets}"
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
-echo "ok: wrote ${targets}"
-```
+ - 生成模板：
+   ```bash
+   bash .opencode/scripts/ws-plan-gen-submodule-targets.sh <change-id>
+   ```
 - 计划里必须写清：本次交付选择的 `targets` 内容，以及后续在 `$ws-dev` 进入编码前会把 submodules 挂到 `aiws/pin/<target_branch>`（必要时先 `fetch`）。
 
 输出要求：

package/templates/workspace/.opencode/skills/ws-plan-verify/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-plan-verify
-description: Thin wrapper for `aiws ws-plan-verify`
+description: Thin wrapper for `aiws plan-verify`
 ---
 
 # ws-plan-verify
 
-Thin skill wrapper. Delegates to `aiws ws-plan-verify`. See `aiws ws-plan-verify --help` for details.
+Thin skill wrapper. Delegates to `aiws plan-verify`. See `aiws plan-verify --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-plan-verify
+  ./node_modules/.bin/aiws plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-plan-verify
+  aiws plan-verify
 else
-  npx @aipper/aiws ws-plan-verify
+  npx @aipper/aiws plan-verify
 fi
 ```

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

@@ -1,18 +1,18 @@
 ---
 name: ws-pull
-description: Thin wrapper for `aiws ws-pull`
+description: Thin wrapper for `aiws pull`
 ---
 
 # ws-pull
 
-Thin skill wrapper. Delegates to `aiws ws-pull`. See `aiws ws-pull --help` for details.
+Thin skill wrapper. Delegates to `aiws pull`. See `aiws pull --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-pull
+  ./node_modules/.bin/aiws pull
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-pull
+  aiws pull
 else
-  npx @aipper/aiws ws-pull
+  npx @aipper/aiws pull
 fi
 ```

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

@@ -1,18 +1,18 @@
 ---
 name: ws-push
-description: Thin wrapper for `aiws ws-push`
+description: Thin wrapper for `aiws push`
 ---
 
 # ws-push
 
-Thin skill wrapper. Delegates to `aiws ws-push`. See `aiws ws-push --help` for details.
+Thin skill wrapper. Delegates to `aiws push`. See `aiws push --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-push
+  ./node_modules/.bin/aiws push
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-push
+  aiws push
 else
-  npx @aipper/aiws ws-push
+  npx @aipper/aiws push
 fi
 ```

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

@@ -43,7 +43,12 @@ OpenCode + oMo 优先策略：
    - 行为是否可能回归
    - 边界条件 / 失败路径是否覆盖
    - 测试是否足以支撑改动
-   - 是否存在明显复杂度、耦合、可维护性或性能问题
+    - 是否存在明显复杂度、耦合、可维护性或性能问题
+    - **AI-Slop 检查**（source: `workflow-review-gates.json` aiSlopChecks）：
+      - unnecessary_abstraction：过度抽象（单实现接口、未使用的泛化层）
+      - fake_comments：伪注释（表述代码行为但不解释 why，或与代码不一致）
+      - over_defensive：过度防御（不必要的安全检查、对不可能情况的处理）
+      - cargo_cult：货舱崇拜（照搬模式但不理解原因，如不必要的 observer/strategy）
 3) 将结论落盘到：
    - 默认：`changes/<change-id>/review/quality-review.md`
    - 回退：`.agentdocs/tmp/review/quality-review.md`

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

@@ -3,6 +3,12 @@ name: ws-review
 description: 使用时机：需要审计当前改动、查找风险时。触发词：审计、评审、review、风险检查、回归检查。注意：高风险变更应补 ws-spec-review + ws-quality-review。
 ---
 
+## 双审查边界
+
+- `ws-review` 是通用评审入口
+- **高风险或准备 finish 的变更**：必须拆为 `ws-spec-review`（流程/归因/真值完整性）+ `ws-quality-review`（行为回归/边界条件/测试覆盖），两份独立证据
+- 单份 review 文件同时覆盖 spec 和 quality 不计为双审查
+
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
@@ -15,6 +21,7 @@ OpenCode + oMo 优先策略：
 
 阶段定位：
 - review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
+- 双审查边界：ws-spec-review 查流程/真值归因，ws-quality-review 查行为/回归/测试。高风险或准备 finish 的任务必须同时完成两者。
 
 必需输入：
 - 当前 `git status` / `git diff`
@@ -38,26 +45,39 @@ OpenCode + oMo 优先策略：
 步骤（建议）：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
    - 若检测到 oMo：优先让 `@oracle` 做独立审查；必要时再让 `@explore` / `@librarian` 补上下文。
-2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+1.5) **Triage**：preflight 后立即判断本 change 是否需要双审查：
+   - 需要双审查的条件：改动涉及 REQUIREMENTS 真值、跨 3+ 文件、涉及安全/数据一致性、或准备 finish
+   - 若需要双审查：在步骤 3 开始时即标注 "dual-review: required"，并规划 spec-review + quality-review 两条并行路径
+    - 若不需要双审查：继续通用 review 流程，标注 "dual-review: not-required"
+    - **不得等到 step 6 才决定是否需要双审查**——风险判定必须前置
+   - **Triage 输出格式**：
+     ```
+     Triage: dual-review: required | not-required
+     Rationale: <one reason>
+     Spec review scope: <what to check> (if required)
+     Quality review scope: <what to check> (if required)
+     ```
+   - Findings 格式要求：每个 finding 必须有 [Critical/Warning/Info] 级别标签 + 归因到 SPEC/QUALITY/REGRESSION 类别
+3) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据
    - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
    - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
-3) Workflow State Suffix 审计（检查 4 种后缀使用是否一致）：
+4) Workflow State Suffix 审计（检查 4 种后缀使用是否一致）：
    - `session` 后缀：只由 ws-dev-lite / ws-intake 写入，标记会话级进度（如 `[workflow-state:session:in_progress]`）
    - `gate` 后缀：由 ws-dev / ws-plan-verify 写入，标记计划/实现门禁结果（如 `[workflow-state:gate:plan_passed]`）
    - `plan` 后缀：由 ws-plan 写入，标记计划阶段状态（如 `[workflow-state:plan:in_progress]`）
    - `gateway` 后缀：由 ws-finish / ws-deliver 写入，标记交付门禁结果（如 `[workflow-state:gateway:finish_gate_ok]`）
    - 检查当前 change 中使用的后缀类型是否正确对应所在阶段；若出现混用（如 session 与 gate 在同一文件），在审计报告中标记异常并说明应该修正的方向。
-4) 将审计落盘到（目录不存在则创建）：
+5) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-5) 若当前任务已进入"准备提交/交付/finish"的语境，继续补齐 dual review gate：
+6) 若 triage 标记为 `dual_review_required`，继续补齐 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 已完成
-6) 回复中输出：
+7) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

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

@@ -1,18 +1,18 @@
 ---
 name: ws-submodule-setup
-description: Thin wrapper for `aiws ws-submodule-setup`
+description: Thin wrapper for `aiws submodule-setup`
 ---
 
 # ws-submodule-setup
 
-Thin skill wrapper. Delegates to `aiws ws-submodule-setup`. See `aiws ws-submodule-setup --help` for details.
+Thin skill wrapper. Delegates to `aiws submodule-setup`. See `aiws submodule-setup --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-submodule-setup
+  ./node_modules/.bin/aiws submodule-setup
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-submodule-setup
+  aiws submodule-setup
 else
-  npx @aipper/aiws ws-submodule-setup
+  npx @aipper/aiws submodule-setup
 fi
 ```

package/templates/workspace/.opencode/skills/ws-verify-before-complete/SKILL.md

@@ -1,18 +1,49 @@
 ---
 name: ws-verify-before-complete
-description: Thin wrapper for `aiws ws-verify-before-complete`
+description: Thin wrapper for `aiws verify-bc`
 ---
 
 # ws-verify-before-complete
 
-Thin skill wrapper. Delegates to `aiws ws-verify-before-complete`. See `aiws ws-verify-before-complete --help` for details.
+## 完成前验证 Gate
+
+进入 `ws-finish` / `ws-handoff` 前必须确认：
+
+- [ ] `ws-spec-review` 已完成：`test -f changes/<id>/review/spec-review.md` (→ PASS/FAIL)
+- [ ] `ws-quality-review` 已完成：`test -f changes/<id>/review/quality-review.md` (→ PASS/FAIL)
+- [ ] `aiws validate .` stamp 存在：`ls .agentdocs/tmp/aiws-validate/*.json 2>/dev/null` (→ PASS/FAIL)
+- [ ] 无未关闭 Critical blocker：`grep -c 'Critical' changes/<id>/review/*.md` = 0 或已标记 resolved (→ PASS/FAIL)
+- [ ] 评审-返工循环 handoff 记录：`test -f changes/<id>/handoff-evidence.md` 且含 rework round 记录 (→ PASS/FAIL)
+
+## Gate Result（结构化输出）
+
+```
+Gate: PASS / FAIL
+Items:
+1. spec-review: PASS
+2. quality-review: PASS
+3. validate-stamp: PASS
+4. no-critical-blocker: PASS
+5. rework-handoff: N/A (未经过返工循环)
+Summary: <一句话总结>
+Action: → ws-finish / → 需补齐: <缺失项>
+```
+
+任一项 FAIL 即阻断 finish；输出中必须给出具体缺失项与补救路径。
+
+Thin skill wrapper. Delegates to `aiws verify-bc`. See `aiws verify-bc --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-verify-before-complete
+  ./node_modules/.bin/aiws verify-bc
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-verify-before-complete
+  aiws verify-bc
 else
-  npx @aipper/aiws ws-verify-before-complete
+  npx @aipper/aiws verify-bc
 fi
 ```
+
+## 执行要求
+
+- 按 Gate Result 结构化输出逐项验证；任一项 FAIL 即阻断 finish。
+- finish 前门禁证据：须确认存在 spec-review.md + quality-review.md（双审查）+ 有效 validate stamp + 已关闭所有 blocker；缺任一项即阻断 finish。