@aipper/aiws-spec 0.0.24 → 0.0.26

package/templates/workspace/.opencode/commands/p-aiws-change-templates-init.md

@@ -0,0 +1,26 @@
+---
+description: 私有：模板初始化：初始化 changes/templates 覆盖模板
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-templates-init -->
+# aiws change templates init
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 初始化 changes/templates 覆盖模板
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates init
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates init
+else
+  npx @aipper/aiws change templates init
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-templates-init -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-change-templates-which.md

@@ -0,0 +1,26 @@
+---
+description: 私有：模板来源：查看 change templates 来源
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-templates-which -->
+# aiws change templates which
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 查看 change 模板来源
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates which
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates which
+else
+  npx @aipper/aiws change templates which
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-templates-which -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-change-validate.md

@@ -0,0 +1,27 @@
+---
+description: 私有：变更校验：按 strict 校验变更工件与绑定
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-change-validate -->
+# aiws change validate
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 按严格模式校验变更工件与绑定关系
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate "${change_id}"
+else
+  npx @aipper/aiws change validate "${change_id}"
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-change-validate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-hooks-install.md

@@ -0,0 +1,26 @@
+---
+description: 私有：Hooks 启用：启用 git hooks 门禁
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-hooks-install -->
+# aiws hooks install
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 启用 git hooks 门禁（core.hooksPath=.githooks）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks install .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks install .
+else
+  npx @aipper/aiws hooks install .
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-hooks-install -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-hooks-status.md

@@ -0,0 +1,26 @@
+---
+description: 私有：Hooks 状态：查看当前仓库 hooks 门禁状态
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-hooks-status -->
+# aiws hooks status
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 查看当前仓库 hooks 门禁状态（只读）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```
+<!-- AIWS_MANAGED_END:opencode:aiws-hooks-status -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-init.md

@@ -0,0 +1,23 @@
+---
+description: 私有：初始化：落盘 AIWS 真值与门禁文件
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-init -->
+# aiws init
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+建议执行：
+1) `npx @aipper/aiws init`
+2) `npx @aipper/aiws validate`
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件
+<!-- AIWS_MANAGED_END:opencode:aiws-init -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-rollback.md

@@ -0,0 +1,16 @@
+---
+description: 私有：回滚：从 .aiws/backups 恢复快照
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-rollback -->
+# aiws rollback
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+目标：
+- 从 `.aiws/backups/` 恢复到某次备份快照
+
+建议执行：
+- `npx @aipper/aiws rollback latest`
+<!-- AIWS_MANAGED_END:opencode:aiws-rollback -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-update.md

@@ -0,0 +1,22 @@
+---
+description: 私有：更新：刷新模板与 tool-native 文件（先备份）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-update -->
+# aiws update
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+目标：
+- 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+建议执行：
+1) `npx @aipper/aiws update`
+2) `npx @aipper/aiws validate`
+
+约束：
+- 不写入任何 secrets
+- 只更新托管块或 spec 指定的 `replace_file` 文件
+<!-- AIWS_MANAGED_END:opencode:aiws-update -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/p-aiws-validate.md

@@ -0,0 +1,17 @@
+---
+description: 私有：门禁：校验 required/托管块/漂移（可落盘 stamp）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:aiws-validate -->
+# aiws validate
+
+（私有原子入口；日常优先用 ws-* 链路。）
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+建议执行：
+- `npx @aipper/aiws validate`
+<!-- AIWS_MANAGED_END:opencode:aiws-validate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/using-aiws.md

@@ -0,0 +1,30 @@
+---
+description: 默认 workflow router：先判定阶段，再进入具体 ws-* 入口
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:using-aiws -->
+# using aiws
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 把当前任务先路由到正确的 AIWS workflow，而不是直接跳进实现。
+
+执行建议：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+   - 若检测到 `.opencode/oh-my-opencode.json`：输出 `OpenCode mode: oMo-enabled`，并注明后续会优先借用 `planner-sisyphus` / `explore` / `librarian` / `oracle`
+   - 若未检测到：输出 `OpenCode mode: standard-opencode`
+2) 若缺失任一真值文件：先 `/ws-preflight`，必要时运行 `aiws init .`，不要继续实现。
+3) 若任务意图、归因或验证入口不明确：先提 1-3 个关键澄清问题并停止。
+4) 路由规则：
+   - 需求/验收/合同变更：`/ws-req-review`
+   - 中大型实现或需要 change/worktree：`/ws-plan`
+   - 小步明确实现：`/ws-dev`（若是 simple/local 单点修复，可显式进入 `/ws-dev-lite`）
+   - 评审/审计：`/ws-review`
+   - finish / merge / push / cleanup：`/ws-finish`
+   - handoff / archive summary：`/ws-handoff`
+5) 输出 `OpenCode mode:` / `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
+6) 若 `Route: ws-dev` 且任务属于 simple/local 单点修复：`Next` 可显式建议 `/ws-dev-lite`。
+7) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。
+<!-- AIWS_MANAGED_END:opencode:using-aiws -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,30 @@
+---
+description: 分析：实现前技术分析并落盘证据
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-analyze -->
+# ws analyze
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+
+输入：
+- 主题/需求：`$ARGUMENTS`（若为空，先问用户一句“本次分析主题是什么？”）
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 基于真值文件与当前代码现状，输出：
+   - 目标 / 非目标
+   - 现状证据（文件路径/接口路径）
+   - 推荐方案（1 个）+ 备选（可选）
+   - 风险与回滚（3–8 条）
+   - 最小验证命令（可复现）
+3) 将分析落盘到：`.agentdocs/tmp/analyze/opencode-analysis.md`（目录不存在则创建）。
+4) 回复中必须包含：`Evidence:` 证据文件路径。
+
+安全：
+- 不打印 secrets（尤其 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-analyze -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,35 @@
+---
+description: 缺陷修复：禅道 MCP 拉单、图片证据落盘并汇总 fix_bus_issues.csv
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-bugfix -->
+# ws bugfix
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 通过禅道 MCP 拉单、图片证据落盘并汇总 `issues/fix_bus_issues.csv`。
+
+建议流程：
+1) 先运行 `/ws-preflight`。
+2) 若当前不在 `change/<change-id>` 分支 / worktree，先建立 change 上下文：
+   - 工作区先保持干净
+   - 仓库已有提交：优先 `aiws change start <change-id> --hooks --worktree`
+   - superproject + submodule：优先 `aiws change start <change-id> --hooks --worktree --submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `aiws change start <change-id> --hooks --no-switch`
+3) 若上一步创建了 worktree：后续 bug 证据、CSV 更新、`/ws-dev` 修复都必须在该 worktree 中继续。
+4) 通过已配置 zentao MCP 拉取 bug 字段与附件列表。
+5) 落盘证据到当前 active change 上下文的 `changes/<change-id>/bug/`：
+   - `zentao-bug-<bug-id>.json`
+   - `zentao-bug-<bug-id>.md`
+   - `images/<bug-id>/...`
+6) upsert 当前 active change 上下文中的 `issues/fix_bus_issues.csv`（主键 `Bug_ID`）。
+7) 进入 `/ws-dev` 修复并回填 `Fix_Status/Verify_Command/Updated_At`。
+8) 质量门：`aiws change validate <change-id> --strict` + `aiws validate . --stamp`。
+
+强制约束：
+- 不自动 commit / push。
+- 不写入 secrets（token、cookie、内网地址）。
+- 无法复现时先输出阻塞信息并落盘，不直接改代码。
+<!-- AIWS_MANAGED_END:opencode:ws-bugfix -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,70 @@
+---
+description: 提交：门禁/审计后提交（submodule 感知）
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-commit -->
+# ws 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
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate . --stamp
+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
+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-delegate.md

@@ -0,0 +1,33 @@
+---
+description: 委托：按 AIWS 合同拆分子任务，并优先借用 oMo agent
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-delegate -->
+# ws delegate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：先写清 delegation plan，再决定是否优先借用 `oh-my-opencode` 的 `planner-sisyphus` / `explore` / `librarian` / `oracle`；若不可用则回退，不阻断流程。
+
+执行建议：
+1) 先运行 `/ws-preflight`，再读取 `packages/spec/docs/workflow-delegation-contracts.md` 与 `packages/spec/docs/opencode-omo-adapter.md`。
+2) 先写 `Delegation Plan:`，至少包含：
+   - `role`
+   - `preferred agent`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+3) 若检测到 `.opencode/oh-my-opencode.json` 或当前会话明确可用相关 agent：
+   - planning 优先 `planner-sisyphus`
+   - 探索优先 `@explore` / `@librarian`
+   - 独立审查优先 `@oracle`
+4) 主 agent 统一收敛结果，并把产物回收到：
+   - `changes/<id>/analysis/`
+   - `changes/<id>/patches/`
+   - `changes/<id>/review/`
+   - `changes/<id>/evidence/`
+5) 若 oMo agent 不可用：明确回退为普通 OpenCode delegation / 单 agent 执行。
+<!-- AIWS_MANAGED_END:opencode:ws-delegate -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/{.iflow/commands/ws-deliver.toml → .opencode/commands/ws-deliver.md}

@@ -1,17 +1,15 @@
-# Command: ws:deliver
-# Description: 交付（submodules + superproject 分步提交，并安全合并回目标分支）
-# Category: workspace
-# Version: 1
+---
+description: 交付：submodules+superproject 分步提交并安全合并回 base
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-deliver -->
+# ws deliver
 
-description = "交付（submodules + superproject 分步提交，并安全合并回目标分支）"
-
-prompt = """
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：适配 superproject + submodule（数量不固定）的交付收尾，降低提交顺序和合并回 base 分支的出错概率：
 1) 先逐个提交 submodule（每个 repo 单独确认 commit message；默认 `git add -p`）
 2) 再提交 superproject（包含 submodule gitlink 指针更新 + 自身改动/变更工件）
-3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `ws:finish`）
+3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`；建议用 `/ws-finish`）
 
 强制约束：
 - 不自动 `git add -A`。
@@ -19,8 +17,8 @@ prompt = """
 - 不自动删除分支。
 
 建议流程（按顺序）：
-1) 先确认真值文件存在并遵守：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
-2) 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `ws:submodule-setup` 并提交 `.gitmodules`（否则 `aiws validate .` 会失败，且 submodule 工作流会产生人为差异）。
+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`。
@@ -47,12 +45,14 @@ prompt = """
 5.2) （可选）生成状态快照（建议）：
    - `aiws change state <change-id> --write`
 6) 安全合并回目标分支：
-   - 优先运行 `ws:finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
+   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
 
 输出要求：
 - `Submodules:` 每个 submodule 的 commit 摘要（repo/path → sha → message）
 - `Superproject:` commit 摘要
-- `Merge:` `ws:finish`/`aiws change finish` 输出（into/from）
+- `Merge:` `/ws-finish` 输出（into/from）
 - `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
 - `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
-"""
+<!-- AIWS_MANAGED_END:opencode:ws-deliver -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/commands/ws-dev-lite.md

@@ -0,0 +1,34 @@
+---
+description: 轻量开发：simple/local 单点修复；最小改动 + 最小验证
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-dev-lite -->
+# ws dev lite
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：处理 simple/local 单点修复，走最小改动 + 最小验证，不默认拉起完整重流程。
+
+使用条件：
+- 目标明确、归因明确、验证入口明确
+- 一般只影响单文件或紧密相关的小范围文件
+- 不需要先改 `REQUIREMENTS.md`
+
+强制流程：
+1) 先运行 `/ws-preflight`。
+2) 先说明：
+   - `Goal:`
+   - `Why lite:`
+   - 若说不清，立刻回到 `/ws-dev` 或 `/ws-plan`
+3) 实施最小改动；不要为形式完整额外扩 scope。
+4) 运行最小可复现验证；允许比全量更窄，但必须说明为什么足够。
+5) 输出 `Changed / Verify / Evidence / Next`。
+6) 若准备提交或交付：后续仍进入 `/ws-review`、`/ws-commit`、`/ws-finish`。
+
+边界：
+- 默认不创建 `plan/...`
+- 默认不跑 `ws-plan-verify`
+- 默认不要求先做双 review
+- 一旦复杂度升高，停止 lite，切回主流程
+<!-- AIWS_MANAGED_END:opencode:ws-dev-lite -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,36 @@
+---
+description: 开发：在 AIWS 约束下完成小步交付
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-dev -->
+# ws dev
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+建议流程：
+1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+   - 若 `/ws-plan` 刚创建了 `change/<change-id>` worktree：后续实现必须在该 worktree 中继续；不要回原工作区重复 `aiws change start ...`
+2) 建立变更归因（推荐）：
+   - ⚠️ 若准备切分支/创建 worktree，先看 `git status --porcelain`；否则切换上下文后，未提交改动可能“看起来丢了”。
+   - 若当前目录已经是 `change/<change-id>` worktree（例如由 `/ws-plan` 创建）：直接在这里继续，不要再创建第二个 worktree，也不要回原工作区写代码。
+   - 若非空仅因为 `/ws-plan` 生成了 `plan/...` 或 `changes/<change-id>/...`，这是预期行为；此时优先 `aiws change start <change-id> --hooks --no-switch`，若仍要 `--switch/--worktree`，先提交这些规划工件。
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
+   - 准备进入实现时：若当前已在 `change/<change-id>` 直接继续；若需切换到该分支，先确认除规划工件外无额外未提交改动，再执行：`git switch change/<change-id>`
+   - 若你明确要“一键切分支”（不推荐，且 dirty 会被拦截）：`aiws change start <change-id> --hooks --switch`
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+3) 如涉及需求调整：先 `/ws-req-review` → 用户确认后再 `/ws-req-change`（避免需求漂移）。
+4) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
+5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
+6) 提交前强制：`aiws validate .`（commit/push hooks 也会阻断）。
+7) 交付收尾（推荐，减少手动 merge 出错）：运行 `/ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
+
+输出要求：
+- `变更文件（Changed）:` 文件清单
+- `验证（Verify）:` 实际运行的命令 + 期望结果
+- `证据（Evidence）:` 证据路径（例如 `changes/<change-id>/review/...`、`changes/<change-id>/...` 或 `.agentdocs/tmp/...`）
+<!-- AIWS_MANAGED_END:opencode:ws-dev -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/{.iflow/commands/ws-finish.toml → .opencode/commands/ws-finish.md}

@@ -1,35 +1,50 @@
-# Command: ws:finish
-# Description: AI Workspace 安全收尾（门禁 + fast-forward 合并 + submodule 并回分支后顺序 push）
-# Category: workspace
-# Version: 1
+---
+description: 收尾：fast-forward 合并并把 submodule 并回目标分支后顺序 push
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-finish -->
+# ws finish
 
-description = "AI Workspace 安全收尾（门禁 + fast-forward 合并 + submodule 并回分支后顺序 push）"
-
-prompt = """
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，并按 `submodule -> superproject` 顺序 push，减少遗漏。
-补充：若团队希望减少 submodule detached 的人为差异，建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `ws:pull`。
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，避免手输分支名导致的错误。
+补充：若团队希望减少 submodule detached 的人为差异，建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `/ws-pull`。
+
+前置（必须）：
+- 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
+- change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+ - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
 
-强制步骤：
-1) 读取真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`（缺失则先运行 `/aiws-init` 或 `aiws init .`）。
-2) 若 iFlow 拦截写入：先执行 `/ws-contract-check`，再继续。
-3) 确认 git 状态（必须输出给用户）：
-   - `git status --porcelain`
-   - `git branch --show-current`（或 `git rev-parse --abbrev-ref HEAD`）
-4) 若工作区不干净：停止，并要求先 commit 或 stash（不要尝试自动处理）。
-4.1) 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `ws:submodule-setup` 并提交 `.gitmodules`）。
-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) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
+步骤（建议）：
+0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
+```bash
+if [[ -f .gitmodules ]]; then
+  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
+fi
+```
+1) 先运行 `/ws-preflight`（确保真值文件齐全）。
+2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+2.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
+2.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
+3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
    - `aiws change finish <change-id> --push`
-   - 在 `change/<change-id>` 分支上也可省略 `<change-id>`；命令会尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch`
+   - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`
    - 该命令会在 fast-forward 合并成功后 push 目标分支；默认优先使用 upstream 配置（`branch.<name>.remote` + `branch.<name>.merge`），只有在你明确知道要推向别的 remote 时才追加 `--remote <name>`
    - 若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则会在 push 成功后自动执行 `git worktree remove` + `git worktree prune`
    - AI 入口执行前，应先向用户说明将要 push 的 remote/branch；显式传入 `--push` 即视为确认
-7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
-8) 若需要先处理 submodules，则按顺序处理每个 submodule（先并回目标分支，再 push）：
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
+5) 若需要先处理 submodules，则按顺序处理每个 submodule（减少 detached；再 push）：
    - 先显式解析 base branch，不要用当前分支名替代：
      - `python3 - <<'PY'`
      - `import json, pathlib; meta = pathlib.Path("changes") / "<change-id>" / ".ws-change.json"; print((json.loads(meta.read_text(encoding="utf-8")).get("base_branch") or "").strip())`
@@ -43,12 +58,14 @@ prompt = """
      - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
      - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
      - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
-9) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
-10) submodules push 完成后，再回到主仓库执行：
+6) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
+7) submodules 全部成功后，再回到主仓库执行：
    - `aiws change finish <change-id> --push`
-11) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+8) `aiws change finish --push` 成功后会自动归档并生成 handoff；只有历史/异常场景才需要手工运行 `aiws change archive <change-id>`。
 
-边界：
+安全：
 - push 前先输出状态并说明远端/分支。
 - 不执行破坏性命令。
-"""
+<!-- AIWS_MANAGED_END:opencode:ws-finish -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。