@aipper/aiws-spec 0.0.24 → 0.0.26

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

@@ -0,0 +1,26 @@
+---
+description: 交接：查看归档 change 的 handoff.md（标准由 aiws change finish --push 自动归档生成）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-handoff -->
+# ws 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
+```
+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

@@ -0,0 +1,25 @@
+---
+description: 迁移：把仓库对齐到 aiws workspace 模板
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-migrate -->
+# ws 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。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-migrate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

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

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

@@ -0,0 +1,27 @@
+---
+description: 规划：生成可落盘 plan 工件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-plan -->
+# ws plan
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 若尚未进入本次 change 的工作上下文：先建立 `change/<change-id>` 分支 / worktree，再生成可落盘执行计划（供 /ws-dev 执行）。
+
+执行建议：
+1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
+   - 若检测到 `.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/commands/ws-preflight.md

@@ -0,0 +1,34 @@
+---
+description: 预检：读取真值文件并输出约束摘要
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-preflight -->
+# ws preflight
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 输出：
+   - `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（范围/禁止项/必须产物/必须验证命令）
+
+安全：
+- 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-preflight -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,87 @@
+---
+description: 拉取：fast-forward 拉取并对齐 submodules（尽量避免 detached）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-pull -->
+# ws pull
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全拉取 superproject，并对齐 submodules，尽量把 submodule 从 detached HEAD “挂回”分支（仅当该分支包含 gitlink commit），减少人为操作差异。
+
+安全约束（强制）：
+- 不执行破坏性命令；不自动提交/不自动 push
+- 若工作区不干净：停止并要求用户先 commit 或 stash
+- `git pull` 默认只允许 fast-forward（避免隐式 merge/rebase）
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+```bash
+git rev-parse --show-toplevel
+git branch --show-current
+git status --porcelain
+```
+若 `git status --porcelain` 非空：停止。
+
+2) 拉取 superproject（fast-forward only）：
+```bash
+git pull --ff-only
+```
+若失败：停止并说明需要用户明确选择 `git pull --rebase` 或手动处理。
+
+3) 更新 submodules 到 superproject 记录的 gitlink commit：
+```bash
+if [[ -f .gitmodules ]]; then
+  git submodule sync --recursive
+  git submodule update --init --recursive
+else
+  echo "[info] no .gitmodules"
+fi
+```
+
+4) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”（不改动 gitlink commit）：
+为避免 origin 多分支时“猜错分支”，本步骤只在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行；否则保持 detached 并提示先运行 `/ws-submodule-setup` 对齐配置。
+```bash
+if [[ -f .gitmodules ]]; then
+  base_branch="$(git branch --show-current)"
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
+    | while read -r key sub_path; do
+      [[ -z "${sub_path:-}" ]] && continue
+      name="${key#submodule.}"; name="${name%.path}"
+      echo "== submodule: ${sub_path} (${name}) =="
+      sub_sha="$(git rev-parse "HEAD:${sub_path}" 2>/dev/null || true)"
+      [[ -z "${sub_sha:-}" ]] && { echo "[warn] no gitlink sha"; continue; }
+
+      cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+      if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
+      if [[ -z "${cfg_branch:-}" ]]; then
+        echo "[warn] ${sub_path}: missing .gitmodules submodule.${name}.branch; keep detached (run ws-submodule-setup)"
+        continue
+      fi
+      target_branch="${cfg_branch}"
+      pin_branch="aiws/pin/${target_branch}"
+
+      git -C "${sub_path}" fetch origin --prune || true
+      if git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
+        if git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
+          git -C "${sub_path}" checkout -B "${pin_branch}" "${sub_sha}"
+          git -C "${sub_path}" branch --set-upstream-to "origin/${target_branch}" "${pin_branch}" >/dev/null 2>&1 || true
+          echo "[ok] attached ${sub_path} to ${pin_branch} (upstream=origin/${target_branch}) at ${sub_sha}"
+        else
+          echo "[warn] ${sub_path}: ${sub_sha} is not in origin/${target_branch}; keep detached"
+        fi
+      else
+        echo "[warn] ${sub_path}: origin/${target_branch} not found; keep detached"
+      fi
+    done
+fi
+```
+
+可选（方案 2，一次性设置 submodule 跟踪分支，会改 `.gitmodules`，需提交）：
+```bash
+git submodule set-branch --branch main <sub_path>
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branch"
+```
+<!-- AIWS_MANAGED_END:opencode:ws-pull -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,93 @@
+---
+description: 推送：submodule 感知（先 submodules 后 superproject；fast-forward；不 force）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-push -->
+# ws push
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全 push 当前仓库；若仓库包含 submodules，则先 push submodules，再 push superproject（默认 fast-forward；不 force）。
+
+强制约束：
+- 不自动提交、不自动 `git add -A`
+- 不使用 `--force` / `--force-with-lease`
+- 若工作区不干净：停止并要求先 commit 或 stash
+
+步骤（建议）：
+1) 输出上下文并检查工作区干净：
+```bash
+git branch --show-current
+git status --porcelain
+git status -sb
+```
+若 `git status --porcelain` 非空：停止。
+
+2) 判断是否存在 submodules：
+```bash
+if [[ -f .gitmodules ]]; then
+  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+fi
+```
+
+3) 若没有 submodules：正常 push（仍需用户确认远端/分支）：
+```bash
+git remote -v
+git push
+```
+
+4) 若有 submodules：先检查 `.gitmodules` 的 `submodule.<name>.branch` 是否齐全（缺失则停止并提示 `/ws-submodule-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
+```
+
+5) 逐个 push submodules（fast-forward only），再 push superproject：
+```bash
+base_branch="$(git branch --show-current)"
+
+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}) =="
+
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
+      echo "error: submodule dirty: ${sub_path}"
+      exit 2
+    fi
+
+    cfg_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+    if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
+    target_branch="${cfg_branch}"
+
+    git -C "${sub_path}" fetch origin --prune
+    if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
+      echo "error: missing origin/${target_branch} for ${sub_path}"
+      exit 2
+    fi
+
+    if ! git -C "${sub_path}" merge-base --is-ancestor "origin/${target_branch}" HEAD; then
+      echo "error: non-fast-forward (submodule=${sub_path}, branch=${target_branch})"
+      exit 2
+    fi
+
+    git -C "${sub_path}" push origin "HEAD:refs/heads/${target_branch}"
+  done
+
+git remote -v
+git push
+```
+<!-- AIWS_MANAGED_END:opencode:ws-push -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/.opencode/commands/ws-quality-review.md

@@ -0,0 +1,30 @@
+---
+description: 质量审查：行为回归 / 测试覆盖 / 实现质量
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-quality-review -->
+# ws quality review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查行为回归、边界条件、测试覆盖与实现质量。
+
+步骤（建议）：
+1) 读取 `git diff`、已执行的验证结果和相关代码。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `explore`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - 质量/回归审查优先 `@oracle`；代码路径与影响面补充优先 `@explore`。
+2) 检查：
+   - 是否存在行为回归或明显 bug 风险
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑当前改动
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+5) 若 oMo 不可用：回退为当前 agent 本地 quality review。
+<!-- AIWS_MANAGED_END:opencode:ws-quality-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-change.md

@@ -0,0 +1,45 @@
+---
+description: 需求变更：更新 REQUIREMENTS 并同步执行合同
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-change -->
+# ws req change
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `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/密钥到仓库
+<!-- AIWS_MANAGED_END:opencode:ws-req-change -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,21 @@
+---
+description: 合同同步：把 REQUIREMENTS FlowSpec 同步到 requirements-issues.csv
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-sync -->
+# ws req 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`
+<!-- AIWS_MANAGED_END:opencode:ws-req-contract-sync -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,16 @@
+---
+description: 合同校验：校验 requirements-issues.csv 字段完整性
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-contract-validate -->
+# ws req contract validate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议
+<!-- AIWS_MANAGED_END:opencode:ws-req-contract-validate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,23 @@
+---
+description: Flow 同步：从 REQUIREMENTS 生成 api-flow 与场景执行合同
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-flow-sync -->
+# ws req flow sync
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `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`：提示用户先运行 `npx @aipper/aiws init .`（默认会安装 optional tools）。
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`
+<!-- AIWS_MANAGED_END:opencode:ws-req-flow-sync -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-req-review.md

@@ -0,0 +1,36 @@
+---
+description: 需求评审：对 REQUIREMENTS 做整体 QA（不改文件）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-req-review -->
+# ws req review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `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`。
+<!-- AIWS_MANAGED_END:opencode:ws-req-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,33 @@
+---
+description: 评审：提交前审计改动并落盘证据
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-review -->
+# ws review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `explore` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - 独立审查优先 `@oracle`；diff 影响面优先 `@explore`；规范/文档上下文优先 `@librarian`。
+2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+   - 是否存在越界目录改动/危险操作
+   - 是否有可复现验证命令与证据
+   - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+3) 将审计落盘到（目录不存在则创建）：
+   - 默认：`changes/<change-id>/review/codex-review.md`
+   - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
+4) 回复中输出：
+   - `证据（Evidence）:` 证据文件路径
+   - `主要风险（Top risks）:` 3–8 条（高→低）
+   - `下一步（Next）:` 最小修复清单 + 最小验证命令
+5) 若 oMo 不可用：回退为当前 agent 本地 review，不阻断流程。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,27 @@
+---
+description: 规则：把口述规则整理并写入 AI_PROJECT.md 托管段
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-rule -->
+# ws rule
+
+     用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+     目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+     安全规则（强制）：
+     - 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+     - 不执行破坏性命令。
+
+     工作流：
+     1) 先运行 `/ws-preflight`；若缺失 `AI_PROJECT.md`：提示用户先 `/ws-migrate` 或运行 `npx @aipper/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 .`
+<!-- AIWS_MANAGED_END:opencode:ws-rule -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-spec-review.md

@@ -0,0 +1,30 @@
+---
+description: 规范审查：requirements / plan / evidence / gate 完整性
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-spec-review -->
+# ws spec review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查 requirements 归因、plan/change 绑定、evidence 与 workflow gate 完整性。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+   - 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用 `oracle` / `librarian`：优先按 `packages/spec/docs/opencode-omo-adapter.md` 借用这些 agent。
+   - requirements / gate / evidence 审查优先 `@oracle`；规范与文档真值补充优先 `@librarian`。
+2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+   - 当前改动是否能归因到 `Req_ID` / `Problem_ID`
+   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否保持一致
+   - 是否存在越界改动、危险操作或缺失 gate
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/spec-review.md`
+   - 回退：`.agentdocs/tmp/review/spec-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `阻断项（Blockers）:`
+   - `警告（Warnings）:`
+   - `下一步（Next）:`
+5) 若 oMo 不可用：回退为当前 agent 本地 spec review。
+<!-- AIWS_MANAGED_END:opencode:ws-spec-review -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-submodule-setup.md

@@ -0,0 +1,57 @@
+---
+description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-submodule-setup -->
+# ws submodule setup
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`（团队真值），让 `/ws-pull`、`/ws-finish` 能确定性地减少 detached 与人为差异；并使 `aiws validate` 的 submodule 分支门禁通过。
+
+约束：
+- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
+- 不做破坏性命令
+
+步骤（建议）：
+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 让用户选择目标分支（推荐具体分支名；可选 `.` 表示跟随 superproject 分支名）：
+```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)"
+done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
+```
+
+4) 写入分支配置：
+```bash
+git submodule set-branch --branch <branch-or-dot> <sub_path>
+```
+
+5) 输出 diff 并让用户确认是否提交：
+```bash
+git diff -- .gitmodules
+git status --porcelain
+```
+
+6) 用户确认后提交：
+```bash
+git add .gitmodules
+git commit -m "chore(submodule): set tracking branches"
+```
+<!-- AIWS_MANAGED_END:opencode:ws-submodule-setup -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+