@aipper/aiws-spec 0.0.29 → 0.0.31

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

@@ -21,7 +21,7 @@ OpenCode + oMo 优先策略：
 - 不写入任何 secrets（token、账号、内网端点等不得进入 git）
 - 本 skill 只负责“想清楚怎么做 + 落盘计划”，不要直接大规模改动代码
 - 未运行不声称已运行；验证命令要写清“预期结果”
-- 若存在 `changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
+- 若存在 `.aiws/changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
 
 阶段定位：
 - planning 阶段；负责把用户目标收敛为 change 绑定、计划文件和验证入口。
@@ -29,7 +29,7 @@ OpenCode + oMo 优先策略：
 必需输入：
 - 当前任务描述
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
-- 若已存在：`changes/<change-id>/proposal.md`
+- 若已存在：`.aiws/changes/<change-id>/proposal.md`
 - 若已有计划：当前 `plan/...` 文件
 
 必需输出：
@@ -52,41 +52,15 @@ OpenCode + oMo 优先策略：
    - 若检测到 oMo：优先让 `planner-sisyphus` 生成 planning draft；若需要补结构探索，再委托 `@explore` / `@librarian`。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
 3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
-4) 识别或建立主索引 / change 上下文：
-   - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
+ 4) 识别或建立主索引 / change 上下文：
+   - 若存在 `.aiws/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/` 不存在先创建
@@ -102,7 +76,7 @@ fi
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
     - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
     - 若 intake 草案包含 `Error States` 或 `Rollback Plan`：必须显式引用并纳入本计划的 `Risks & Rollback` 中，不能丢弃 intake 已识别的问题
-   - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
+   - `Evidence`：计划文件路径；若创建了变更工件则附 `.aiws/changes/<change-id>/...`
 7) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
 8) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
    - 通过后：标记 `[workflow-state:plan:DONE]` 或 `[workflow-state:gate:plan_passed]`，表示 plan 阶段已收敛。
@@ -117,31 +91,15 @@ oMo 回退：
 - 背景：`.gitmodules submodule.<name>.branch` 适合作为“团队默认分支真值”，但当同一 superproject 分支需要在不同交付中选择不同 submodule 目标分支（多渠道）时，仅靠 `.gitmodules` 不足。
 - 强约束：当 `.gitmodules` 声明了 submodule 条目时，门禁会要求本次 change 存在该文件且覆盖所有 submodule path（否则 `aiws validate .` / `aiws change validate --strict` 阻断）。
 - 约定：为本次 change 落盘一个“交付目标分支映射”文件，并在后续 `$ws-dev`/`$ws-deliver`/`$ws-finish` 优先使用它：
-  - 文件：`changes/<change-id>/submodules.targets`
+  - 文件：`.aiws/changes/<change-id>/submodules.targets`
   - 格式：每行一个 submodule（忽略空行与 `#` 注释），字段用空白分隔（推荐 `TAB`）：
     - 第 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

@@ -7,7 +7,7 @@ description: 使用时机：需要审查实现质量、测试覆盖时。触发
 
 目标：
 - 审查当前改动的行为正确性、边界条件、测试覆盖和实现质量
-- 把“代码/行为层 findings”优先落盘到 `changes/<change-id>/review/quality-review.md`
+- 把“代码/行为层 findings”优先落盘到 `.aiws/changes/<change-id>/review/quality-review.md`
 
 OpenCode + oMo 优先策略：
 - 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `explore`，优先借用这些 agent 做质量审查。
@@ -21,10 +21,10 @@ OpenCode + oMo 优先策略：
 - 当前 `git diff`
 - 已执行的验证结果
 - 相关代码 / 配置 / 测试文件
-- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 review 文件
+- 若存在：`.aiws/changes/<change-id>/analysis/`、`patches/`、已有 review 文件
 
 必需输出：
-- `证据（Evidence）:` `changes/<change-id>/review/quality-review.md` 或回退 `.agentdocs/tmp/review/quality-review.md`
+- `证据（Evidence）:` `.aiws/changes/<change-id>/review/quality-review.md` 或回退 `.aiws/tmp/review/quality-review.md`
 - `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
 - `下一步（Next）:` 最小修复项与回归命令
 
@@ -43,10 +43,15 @@ 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`
+   - 默认：`.aiws/changes/<change-id>/review/quality-review.md`
+   - 回退：`.aiws/tmp/review/quality-review.md`
 4) 输出：
    - `证据（Evidence）:`
    - `主要发现（Findings）:`

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

@@ -3,9 +3,15 @@ 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/`）。
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `.aiws/changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.aiws/tmp/review/`）。
 若当前语境已经明确是“准备交付/finish”，则本入口不应只停留在通用 review：应继续同时补齐 `$ws-spec-review` 与 `$ws-quality-review`，把 dual review gate 一次性收敛完。
 
 OpenCode + oMo 优先策略：
@@ -15,16 +21,17 @@ OpenCode + oMo 优先策略：
 
 阶段定位：
 - review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
+- 双审查边界：ws-spec-review 查流程/真值归因，ws-quality-review 查行为/回归/测试。高风险或准备 finish 的任务必须同时完成两者。
 
 必需输入：
 - 当前 `git status` / `git diff`
 - 已执行的验证结果
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
 - 当前 `change/<change-id>` 上下文（若能识别）
-- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
+- 若存在：`.aiws/changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
 
 必需输出：
-- 审计文件：`changes/<change-id>/review/codex-review.md` 或回退 `.agentdocs/tmp/review/codex-review.md`
+- 审计文件：`.aiws/changes/<change-id>/review/codex-review.md` 或回退 `.aiws/tmp/review/codex-review.md`
 - `主要风险（Top risks）:` 3-8 条
 - `下一步（Next）:` 最小修复清单 + 最小验证命令
 
@@ -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`
+   - 是否维护了 `.aiws/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) 将审计落盘到（目录不存在则创建）：
-   - 默认：`changes/<change-id>/review/codex-review.md`
-   - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
+5) 将审计落盘到（目录不存在则创建）：
+   - 默认：`.aiws/changes/<change-id>/review/codex-review.md`
+   - 回退：`.aiws/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-5) 若当前任务已进入"准备提交/交付/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`）
+6) 若 triage 标记为 `dual_review_required`，继续补齐 dual review gate：
+   - 运行/收敛 `$ws-spec-review`，落盘 `.aiws/changes/<change-id>/review/spec-review.md`（或回退 `.aiws/tmp/review/spec-review.md`）
+   - 运行/收敛 `$ws-quality-review`，落盘 `.aiws/changes/<change-id>/review/quality-review.md`（或回退 `.aiws/tmp/review/quality-review.md`）
    - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
-6) 回复中输出：
+7) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

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

@@ -7,7 +7,7 @@ description: 使用时机：需要审查流程完整性、requirements 归因时
 
 目标：
 - 审查当前改动是否满足真值文件、change 绑定、证据路径和 gate 完整性要求
-- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `changes/<change-id>/review/spec-review.md`
+- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `.aiws/changes/<change-id>/review/spec-review.md`
 
 OpenCode + oMo 优先策略：
 - 若检测到 `.opencode/oh-my-opencode.json`，或当前会话明确可用 `oracle` / `librarian`，优先借用它们做 spec / gate 审查。
@@ -22,10 +22,10 @@ OpenCode + oMo 优先策略：
 - `REQUIREMENTS.md`
 - `AI_WORKSPACE.md`
 - 当前 `git diff`
-- 若存在：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
+- 若存在：`plan/...`、`.aiws/changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
 
 必需输出：
-- `证据（Evidence）:` `changes/<change-id>/review/spec-review.md` 或回退 `.agentdocs/tmp/review/spec-review.md`
+- `证据（Evidence）:` `.aiws/changes/<change-id>/review/spec-review.md` 或回退 `.aiws/tmp/review/spec-review.md`
 - `阻断项（Blockers）:` requirements 归因 / gate / evidence 缺口
 - `下一步（Next）:` 修复项与最小验证命令
 
@@ -46,8 +46,8 @@ OpenCode + oMo 优先策略：
    - 是否存在越界目录改动、危险操作、未声明的非目标扩张
    - 是否已经准备好可复现验证入口
 3) 把结论落盘到：
-   - 默认：`changes/<change-id>/review/spec-review.md`
-   - 回退：`.agentdocs/tmp/review/spec-review.md`
+   - 默认：`.aiws/changes/<change-id>/review/spec-review.md`
+   - 回退：`.aiws/tmp/review/spec-review.md`
 4) 输出：
    - `证据（Evidence）:`
    - `阻断项（Blockers）:`

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 .aiws/changes/<id>/review/spec-review.md` (→ PASS/FAIL)
+- [ ] `ws-quality-review` 已完成：`test -f .aiws/changes/<id>/review/quality-review.md` (→ PASS/FAIL)
+- [ ] `aiws validate .` stamp 存在：`ls .aiws/tmp/aiws-validate/*.json 2>/dev/null` (→ PASS/FAIL)
+- [ ] 无未关闭 Critical blocker：`grep -c 'Critical' .aiws/changes/<id>/review/*.md` = 0 或已标记 resolved (→ PASS/FAIL)
+- [ ] 评审-返工循环 handoff 记录：`test -f .aiws/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。

package/templates/workspace/AGENTS.md

@@ -1,91 +1,36 @@
 <!-- AIWS_MANAGED_BEGIN:agents -->
-本仓库启用 AIWS（AI Workspace）约定，请先读取并遵守（按优先级）：
-1) `AI_PROJECT.md`（规则/边界）
-2) `REQUIREMENTS.md`（需求与验收真值）
-3) `AI_WORKSPACE.md`（运行/测试入口真值）
-4) `changes/README.md`（变更工件流程与归档）
-
-最小协作约束：
-- 不确定先跑 `/using-aiws`（Codex 对应 `$using-aiws`）；它会先读真值，再把任务路由到合适的 `ws-*` 入口。
-- 若你已经明确只是做预检，也可以直接跑 `/ws-preflight`（Codex 对应 `$ws-preflight`）；所有实现/修复都以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准。
-- 每次变更建议进入 `change/<change-id>`，并维护 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）。
-- 若仓库存在 `.gitmodules`：使用 `aiws change start <change-id> --switch`；不要在当前 superproject 里直接手工切分支。
-- 提交前执行 `aiws validate .`；需要本机门禁时运行 `aiws hooks install .`（或 `git config core.hooksPath .githooks`）。
-- 不要把敏感信息写入 git：`secrets/test-accounts.json`、`.env*`、token、内网地址等。
-
-标准链路（建议默认）：
-- `using-aiws`：默认 bootstrap/router；先读真值，先判 workflow，再进入具体阶段；意图不明确时先澄清。
-- `ws-preflight`：读取真值文件，输出约束摘要；若真值缺失，先停止，不直接开工。
-- `ws-intake`：计划前置澄清；适用于新需求或中大型变更，按“一题一线程”逐条冻结问题，产出 `plan/*.intake.md` 轻量草案。
-- `ws-plan`：建立 `change/<change-id>` 绑定，落盘 `plan/...`，明确 Verify / Risks / Evidence。
-- `ws-plan-verify`：在编码前做计划质检 + 多视角方案审查；不过门禁就先修 plan，不跳步进实现。
-- `ws-dev`：只做可归因、可验证的小步实现；输出 Changed / Verify / Evidence。
-- `ws-dev-lite`：`ws-dev` 的轻量入口；适用于 simple/local 单点修复，默认不建 `plan/...`、不跑 `ws-plan-verify`，治理归属仍收敛到 `ws-dev`。
-- `ws-delegate`：仅在任务已绑定且 scope 可控时，使用原生多 agent / sub-agent；否则明确降级为单 agent + 协同工件模式。
-- `ws-review`：对当前改动做通用审计；高风险或准备交付时，继续细化到 `ws-spec-review` + `ws-quality-review`。
-- `ws-spec-review`：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
-- `ws-quality-review`：审查行为回归、边界条件、测试覆盖与实现质量。
-- `ws-commit`：串联 review + validate stamp + commit message 确认；不跳过 hooks。
-- `ws-verify-before-complete`：在 finish / handoff 前检查双审查、validate stamp 与交付证据是否齐全。
-- `ws-deliver` / `ws-finish`：做交付收尾、fast-forward 合并、submodule 感知 push，并在完整 finish 后自动归档。
-- `ws-handoff`：查看/补充归档后的 handoff，给下一次会话或下一位协作者接力。
-
-阶段产物（最少）：
-- intake：`plan/*.intake.md`
-- planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
-- implementation：代码 / 配置改动 + Verify 命令记录
-- collaboration：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`
-- review：`changes/<change-id>/review/...` 或回退 `.agentdocs/tmp/review/...`
-- validate：`.agentdocs/tmp/aiws-validate/*.json`
-- handoff / archive：`changes/<change-id>/evidence/...`、`changes/archive/.../handoff.md`
-
-OpenCode（如果你主要用 OpenCode，优先）：
-- native skills 在 `.opencode/skills/`；native commands 在 `.opencode/commands/`
-- 若项目启用了 `.opencode/oh-my-opencode.json`：`ws-plan` / `ws-review` / `ws-spec-review` / `ws-quality-review` / `ws-delegate` 会优先借用 oMo 的 `planner-sisyphus` / `explore` / `librarian` / `oracle`
-- 若你想按项目固定这组 agent，可参考 `.opencode/oh-my-opencode.json.example`；它提供 autonomy 示例配置，但仍不接管 hooks/MCP/LSP/runtime
-- 若你要做实验性的“尽量无人值守直到完成”：先看 `/ws-auto`、`/ws-autonomy`、`.claude/settings.json.example` 与 `.opencode/helpers/tmux-swarm-*.sh`
-- 常用手动入口继续保留在 `.opencode/commands/`（migration window 内 `.opencode/command/` 也会保留）；直接使用 `/ws-*`
-- 若你不确定当前任务该先 plan、dev、review 还是 finish：先用 `/using-aiws`
-- 需求还没冻结、想逐条把问题聊清楚：先用 `/ws-intake`
-- `/ws-preflight`：读取真值文件并输出约束摘要
-- `/ws-plan` / `/ws-plan-verify`：先生成计划，再做执行前质检与多视角方案审查
-- `/ws-dev`：常规实现/改配置/改测试
-- `/ws-dev-lite`：小问题直修；若复杂度升高，立刻回到 `/ws-dev` 或 `/ws-plan`
-- `/ws-delegate`：按 AIWS 委托合同拆分子任务，并优先借用 oMo agent
-- `/ws-auto`：OpenCode/oMo 自动 bootstrap 入口；会先检查托管内容/是否需要 update，再按条件确保 watchdog 已启动
-- `/ws-autonomy`：OpenCode/oMo 自主协作实验入口；声明 completion/retry/rescue 合同，不接管 runtime controller
-- `/ws-bugfix`：缺陷修复 + 证据落盘 + CSV 汇总
-- `/ws-review` / `/ws-commit`：提交前审计、门禁与 commit
-- `/ws-spec-review` / `/ws-quality-review`：高风险改动建议显式拆成流程审查 + 质量审查
-- `/ws-verify-before-complete`：finish / handoff 前检查双审查和 validate/evidence
-- `/ws-finish` / `/ws-deliver`：交付收尾（fast-forward / submodule 感知）
-- `/ws-pull` / `/ws-push` / `/ws-submodule-setup`：submodule 场景辅助
-- `/p-aiws-*` 为底层原子入口；模板会同时写入 `.opencode/commands/` 与 `.opencode/command/`，一般不需要直接调用
-
-Claude Code（如果你主要用 Claude Code）：
-- native skills 在 `.claude/skills/`；command-style 兼容入口保留在 `.claude/commands/`
-- 常用链路可按 `ws-*` / `p-aiws-*` 理解；native skills 与 compatibility commands 指向同一套 AIWS workflow
-- 若你不确定当前任务该走哪个阶段：先用 `/using-aiws`
-- 需求还没冻结、想逐条把问题聊清楚：先用 `/ws-intake`
-- 高风险改动或准备 finish 时，建议额外跑 `/ws-spec-review`、`/ws-quality-review`、`/ws-verify-before-complete`
-
-Codex（对应入口，可选）：
-- 若你不想先记住阶段，先用 `$using-aiws` 让 router 判定下一步
-- 对应入口在 `.agents/skills/`；显式调用时使用 `$ws-*`
-- `$using-aiws`
-- `$ws-preflight` / `$ws-intake` / `$ws-plan` / `$ws-plan-verify` / `$ws-dev` / `$ws-dev-lite` / `$ws-delegate` / `$ws-frontend-design`
-- `$ws-review` / `$ws-spec-review` / `$ws-quality-review` / `$ws-commit`
-- `$ws-verify-before-complete` / `$ws-finish` / `$ws-deliver`
-- `$ws-pull` / `$ws-push` / `$ws-submodule-setup`
-- 其它入口见 `.agents/skills/`：`ws-*` 为常用链路；`p-*` 为底层原子入口，一般不需要直接调用
-
-Codex 全局入口（可选）：
-- `npx @aipper/aiws codex install-skills`（推荐；安装全局 skills）
-- `npx @aipper/aiws codex install-prompts`（遗留兼容；prompts 已 deprecated）
-
-缺文件或模板漂移时：
-- `npx @aipper/aiws init`（初始化）
-- `npx @aipper/aiws update`（按模板更新托管内容）
+本仓库启用 AIWS（AI Workspace）约定。真值文件（按优先读取）：
+1) `AI_PROJECT.md`（规则/边界）→ 2) `REQUIREMENTS.md`（需求与验收真值）→ 3) `AI_WORKSPACE.md`（运行/测试入口真值）
+
+快速分流：
+- 小修（≤3 文件，≤100 行）→ `/ws-dev-lite`
+- 常规实现 → `/ws-plan` → `ws-dev`
+- 高风险变更 → 加 `ws-spec-review` + `ws-quality-review` 双审查
+- 不确定 → `/using-aiws`（先读真值，再路由）
+
+协作约束：
+- 变更绑定 `change/<id>`，走 plan→verify→dev→review→commit→finish
+- review 完成 → `ws-verify-before-complete` 确认验证通过 → 再 finish
+- review 三方（spec/quality/verify）需 triage 确定是否有 HIGH blocker
+- 主 session 编排收敛，不直接写业务代码；实现与验证由 subagent 产出
+- 提交前 `aiws validate .`；敏感信息不入 git
+- 缺真值文件先 stop，不直接开工
+- handoff 产出 `handoff-evidence.md` 供后续 session 恢复
+
+Red Flags（这些想法都是错的）：
+| 你想的 | 实际 |
+|--------|------|
+| "看着简单直接改" | 简单→ws-dev-lite，不确定→先 /using-aiws |
+| "先动手再说" | 评估先于行动，分流在实现之前 |
+| "跳过 review" | review 是门禁，不是建议 |
+| "主 session 自己写代码" | 编排收敛，subagent 实现 |
+| "不想走流程直接改" | escape-hatch: 可走 ws-dev-lite，但须遵守最小约束（降级需标明） |
+
+阶段产物（最少）：intake=`.aiws/plan/*.intake.md` | planning=`.aiws/plan/...`+`proposal.md`+`tasks.md` | dev=代码+Verify | review=`review/...` | validate=`aiws-validate/*.json` | archive=`evidence/...`+`handoff.md`
+
+平台前缀：OpenCode/Claude=`/` Codex=`$` | 例：`/ws-dev` 或 `$ws-dev`
+Codex 全局安装：`npx @aipper/aiws codex install-skills`
+缺文件/漂移时：`npx @aipper/aiws init` / `npx @aipper/aiws update`
 <!-- AIWS_MANAGED_END:agents -->
 
 你可以在本段下方追加项目自定义说明；`aiws update` 不会改动托管块以外内容。

package/templates/workspace/AI_PROJECT.md

@@ -29,14 +29,14 @@
 ## 3) 产物与证据（强制）
 
 每轮迭代必须落盘至少一个“可追溯产物”（三选一即可）：
-- 证据：`.agentdocs/tmp/...`（report/log/resp）
+- 证据：`.aiws/tmp/...`（report/log/resp）
 - 合同：`issues/*.csv`（状态变化：TODO/DOING/DONE/BLOCKED/SKIP）
-- 变更工件：`changes/<change-id>/`（proposal/tasks/design；详见 `changes/README.md`）
+- 变更工件：`.aiws/changes/<change-id>/`（proposal/tasks/design；详见 `.aiws/changes/README.md`）
 
 不得只在对话里口头描述“已验证/已修复”。
 
 推荐（防规则/范围漂移）：
-- 创建工件：补齐 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
+- 创建工件：补齐 `.aiws/changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
 - 声明 active change（团队共享）：切到分支 `change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
 - 若仓库存在 `.gitmodules`：使用 `aiws change start <change-id> --switch`；不要在当前 superproject 里直接手工切分支。
 - 若 submodule 因 gitlink checkout 处于 detached HEAD：只允许挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来“解 detached”。
@@ -74,7 +74,7 @@
 
 - `X-Request-Id`：自动化测试请求必须携带；服务端必须回传同名响应头；日志应包含 `request_id=<id>` 以便按单次请求定位问题。
 - 接口清单真值：优先使用 `docs/openapi.json`。若缺失，先补齐导出方式并生成到该路径，再做全量覆盖测试（避免“覆盖范围不可复现”）。
-- 证据落盘：每轮至少更新一次 `.agentdocs/tmp/...` 或 `issues/*.csv`（禁止只在对话里口头宣称“已验证/已修复”）。
+- 证据落盘：每轮至少更新一次 `.aiws/tmp/...` 或 `issues/*.csv`（禁止只在对话里口头宣称“已验证/已修复”）。
 
 <!-- AIWS_MANAGED_END:ai-project:core -->
 

package/templates/workspace/AI_WORKSPACE.md

@@ -16,7 +16,7 @@
 
 - base_url: "http://127.0.0.1:8080"
 - health_path: "/health"
-- log_path: ".agentdocs/tmp/server-test/app.log"
+- log_path: ".aiws/tmp/server-test/app.log"
 
 - environment: "test"
 - base_url_allowlist:

package/templates/workspace/REQUIREMENTS.md

@@ -71,7 +71,7 @@
 - `issues/server-api-issues.csv`：每个 endpoint 的验收字段与状态机（TODO/DOING/DONE/BLOCKED/SKIP）
 - `issues/server-fix-issues.csv`：当出现 BLOCKED 时自动生成的“下一步修复清单”（用于持续闭环；包含 Failure_Category/Failure_Analysis/Suggestion）
 - `issues/server-triage-issues.csv`：当 runner 无法稳定归因/需要人工判断时生成的“人工介入清单”（避免把噪声混进 fix issues）
-- `.agentdocs/tmp/server-test/`：响应与日志片段（不入库）
+- `.aiws/tmp/server-test/`：响应与日志片段（不入库）
 
 当出现 BLOCKED：
 - 若属于业务/需求不清：先补齐本文件对应接口的期望，再改代码

package/templates/workspace/gitignore

@@ -1,5 +1,5 @@
 # AIWS_MANAGED_BEGIN:gitignore
-.agentdocs/
+.aiws/tmp/
 .aiws/backups/
 secrets/test-accounts.json
 .env