@aipper/aiws-spec 0.0.2 → 0.0.3

package/README.md

@@ -1,12 +1,14 @@
 # @aipper/aiws-spec
 
-本包存放 aiws 的规范与模板（单一真值来源）。
+本包存放 aiws 的规范与模板（单一真值来源，SSOT），供 `@aipper/aiws` CLI 读取并生成/更新目标仓库文件。
 
-当前已从 dotfiles 复制一份 AI Workspace 模板到：
-- `templates/workspace/`
+通常你只需要安装并使用 CLI：
+```bash
+npx @aipper/aiws init .
+```
 
-后续 `@aipper/aiws` CLI 将以此为输入生成/更新目标仓库内的真值文件与 tool-native 配置文件。
+## 内容
 
-另见（本包内文档）：
+- `templates/workspace/`：workspace 模板（真值文件、tool-native commands/skills、hooks、门禁脚本等）
 - `docs/spec-contract.md`：模板契约（required/optional、managed markers、tool matrix、`.aiws/manifest.json` 约定）
-- `docs/cli-interface.md`：CLI 行为语义（仅定义，不实现）
+- `docs/cli-interface.md`：CLI 行为语义（定义为主）

package/docs/cli-interface.md

@@ -226,12 +226,33 @@
 ### `aiws change start`
 
 语义：
-- 切分支：`change/<change-id>`（存在则切换；不存在则创建）。
+- 默认行为：切分支到 `change/<change-id>`（存在则切换；不存在则创建）。
+- 若检测到 `.gitmodules`（git submodules）且未显式指定 `--switch/--no-switch/--worktree`：默认优先采用 `--worktree`（避免切走 superproject 分支导致 submodule 状态混乱）；若不满足 `--worktree` 前置条件则回退为 `--no-switch`。
 - 若 `changes/<change-id>/` 不存在：等价执行 `aiws change new ...`。
 - 可选：`--hooks` 等价于 `aiws hooks install .`。
+- 可选：`--switch` 显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义；否则等价于默认行为）。
+- 可选：`--no-switch` 不切换当前分支（仅确保目标分支存在，并初始化变更工件）；适用于 superproject + submodule 场景，避免意外切换 A 目录分支导致 submodule 状态混乱。
+- 可选：`--worktree` 使用 `git worktree` 创建一个独立工作区并在其中 checkout `change/<change-id>`，当前目录分支保持不变（推荐用于 superproject + submodule）。
+  - 默认 worktree 目录：`../<repo-name>-<change-id>`（相对于 git root）
+  - 可选：`--worktree-dir <path>` 覆盖 worktree 目录（推荐放在仓库外；相对路径按 `../` 作为基准理解）
+  - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`（避免新 worktree 下 submodule 目录为空）
+- 约束：`--worktree` 与 `--no-switch` 互斥。
 
 接口（仅定义）：
-- `aiws change start <change-id> [--title <title>] [--no-design] [--hooks]`
+- `aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--worktree] [--worktree-dir <path>] [--submodules]`
+
+### `aiws change finish`
+
+语义：
+- 安全合并：将 `change/<change-id>` fast-forward 合并回目标分支（默认 `--ff-only`，不生成 merge commit）。
+- 目标分支推断：
+  - 若当前分支不是 `change/<change-id>`：默认合并到当前分支。
+  - 若当前分支是 `change/<change-id>`：尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch` 作为目标分支；若缺失则要求显式指定 `--into/--base`。
+- 约束：要求工作区 clean（无未提交改动）。
+- worktree 场景：若目标分支正在其它 worktree 被 checkout，会提示到对应 worktree 执行。
+
+接口（仅定义）：
+- `aiws change finish [<change-id>] [--into <branch> | --base <branch>]`
 
 ### `aiws change sync`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/aiws-spec",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

package/templates/workspace/.agents/skills/aiws-change-finish/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: aiws-change-finish
+description: 安全合并 change/<change-id> 回目标分支（默认 fast-forward）
+---
+
+目标：
+- 将 `change/<change-id>` fast-forward 合并回目标分支，减少手输分支名导致的错误
+
+执行（在目标分支所在 worktree 的仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "$change_id"
+else
+  npx @aipper/aiws change finish "$change_id"
+fi
+```
+
+说明：
+- 默认等价于：`git merge --ff-only change/<change-id>`
+- 若你当前就在 `change/<change-id>` 分支上，`finish` 会尝试读取 `changes/<change-id>/.ws-change.json` 的 `base_branch` 作为目标分支
+- 若无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`

package/templates/workspace/.agents/skills/aiws-change-start/SKILL.md

@@ -5,6 +5,7 @@ description: 切分支并初始化变更工件（可选安装 hooks）
 
 目标：
 - 切到分支 `change/<change-id>` 并初始化 `changes/<change-id>/` 工件
+  - 若检测到 `.gitmodules`（git submodules），默认优先使用 `--worktree`（失败则回退为 `--no-switch`），避免切走 superproject 分支导致 submodule 状态混乱
 
 要求：
 - 需要 git 仓库；若不是 git 仓库先 `git init`
@@ -25,3 +26,8 @@ fi
 - `--hooks`：同时执行 `aiws hooks install .`
 - `--title <title>`：写入标题
 - `--no-design`：不生成 design.md
+- `--switch`：显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义）
+- `--no-switch`：不切换当前分支（仅确保 `change/<change-id>` 分支存在并初始化工件）；适用于 superproject + submodule 场景
+- `--worktree`：用 `git worktree` 创建独立工作区并在其中 checkout `change/<change-id>`（推荐用于 superproject + submodule）
+  - `--worktree-dir <path>`：覆盖 worktree 目录
+  - `--submodules`：在 worktree 内执行 `git submodule update --init --recursive`

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

@@ -12,6 +12,7 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
    - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
 2) 建立变更归因（推荐）：
    - 推荐一键：`aiws change start <change-id> --hooks`（切分支 + 初始化变更工件 + 启用 hooks）
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`（创建独立 worktree；当前目录分支保持不变）
    - 或手工：`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`（问题）。
@@ -27,6 +28,7 @@ else
   npx @aipper/aiws validate .
 fi
 ```
+8) 交付收尾（推荐，减少手动 merge 出错）：运行 `$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
 
 输出要求：
 - `Changed:` 文件清单

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

@@ -0,0 +1,51 @@
+---
+name: ws-finish
+description: 收尾（门禁 + 安全合并 change/<change-id> 回目标分支）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在结束一次变更交付时，用 fast-forward 安全合并 `change/<change-id>` 回目标分支，减少手输分支名导致的错误
+- 不自动 push；不自动删分支；必要时先让用户确认
+
+前置（必须）：
+- 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
+- change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
+- 若使用 worktree：在“目标分支所在 worktree”执行（`aiws change finish` 会提示正确的 worktree）
+
+建议步骤：
+1) （推荐）先跑一次门禁并落盘证据：
+```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
+```
+2) 安全合并（默认 fast-forward；并会在需要时切到目标分支）：
+```bash
+# 若当前就在 change/<change-id> 分支上，可省略 <change-id>
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change finish "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change finish "${change_id}"
+else
+  npx @aipper/aiws change finish "${change_id}"
+fi
+```
+3) 若 fast-forward 失败（提示需要 rebase）：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
+4) （可选）归档变更工件（完成交付后推荐）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "${change_id}"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "${change_id}"
+else
+  npx @aipper/aiws change archive "${change_id}"
+fi
+```

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

@@ -36,4 +36,4 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 
 输出要求：
 - `Plan file:` <实际写入的路径>
-- `Next:` 推荐下一步（通常是 `$ws-dev` 或 `aiws change start <change-id> --hooks`）
+- `Next:` 推荐下一步（通常是 `$ws-dev` 或 `aiws change start <change-id> --hooks`；superproject + submodule 可用 `--worktree`）

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

@@ -14,6 +14,7 @@
 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:` 文件清单

package/templates/workspace/.claude/commands/ws-finish.md

@@ -0,0 +1,26 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-finish -->
+# ws finish
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，避免手输分支名导致的错误。
+
+前置（必须）：
+- 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
+- change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`（确保真值文件齐全）。
+2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+3) 安全合并并切回目标分支：
+   - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
+   - 否则执行：`aiws change finish <change-id>`
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
+5) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+
+安全：
+- 不自动 push。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:claude:ws-finish -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.iflow/commands/ws-finish.toml

@@ -0,0 +1,30 @@
+# Command: ws:finish
+# Description: AI Workspace 安全收尾（门禁 + fast-forward 合并 change/<change-id> 回目标分支）
+# Category: workspace
+# Version: 1
+
+description = "AI Workspace 安全收尾（门禁 + fast-forward 合并 change/<change-id> 回目标分支）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，减少手输分支名导致的错误。
+
+强制步骤：
+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（不要尝试自动处理）。
+5) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+6) 安全合并（默认 fast-forward）：
+   - 在 `change/<change-id>` 分支上：`aiws change finish`（会尝试读 `changes/<change-id>/.ws-change.json` 的 `base_branch` 并切回目标分支）
+   - 否则：`aiws change finish <change-id>`
+7) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里执行 `git rebase <target-branch>`，再重试 `aiws change finish`。
+8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+
+边界：
+- 不自动 push。
+- 不执行破坏性命令。
+"""

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

@@ -14,6 +14,7 @@
 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:` 文件清单

package/templates/workspace/.opencode/command/ws-finish.md

@@ -0,0 +1,26 @@
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-finish -->
+# ws finish
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：安全把 `change/<change-id>` fast-forward 合并回目标分支，避免手输分支名导致的错误。
+
+前置（必须）：
+- 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
+- change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`（确保真值文件齐全）。
+2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+3) 安全合并并切回目标分支：
+   - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
+   - 否则执行：`aiws change finish <change-id>`
+4) 若提示无法 fast-forward：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish`。
+5) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+
+安全：
+- 不自动 push。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:opencode:ws-finish -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/changes/README.md

@@ -21,7 +21,13 @@ changes/
 ```
 
 常用命令（推荐使用 `aiws`；不依赖 dotfiles）：
-- `aiws change start <change-id>`（推荐：自动切到 `change/<change-id>` 并初始化工件目录）
+- `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录；若检测到 `.gitmodules` 则默认优先使用 worktree，失败则回退为不切分支，避免 submodule 状态混乱）
+- `aiws change start <change-id> --no-switch`（superproject + submodule 场景：不切分支，仅准备 `change/<change-id>` 分支与工件目录）
+- `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅在存在 `.gitmodules` 时有意义）
+- `aiws change start <change-id> --worktree`（推荐用于 superproject + submodule：创建独立 worktree；当前目录分支保持不变）
+  - 可选：`--worktree-dir <path>` 覆盖 worktree 目录
+  - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`
+- `aiws change finish <change-id>`（安全合并：fast-forward 合并回目标分支；在 `change/<change-id>` 分支上执行时会尝试使用 `.ws-change.json` 的 `base_branch` 作为目标分支）
 - `aiws change new <change-id>`
 - `aiws change list`
 - `aiws change status <change-id>`
@@ -53,3 +59,8 @@ Hooks/CI（推荐，硬约束）：
   - 或使用：`aiws hooks install .`（等价）
 - CI 建议增加一步（对 PR 分支执行）：`aiws validate .`。
 - 紧急跳过（不推荐）：`WS_CHANGE_HOOK_BYPASS=1 ...`（CI 不应允许跳过）。
+
+合并建议（减少人为 merge 引入新问题）：
+- 优先使用 worktree + fast-forward 合并：
+  - 完成后在主工作区（例如 `main`）执行：`aiws change finish <change-id>`（等价于 `git merge --ff-only change/<change-id>`）
+  - 若失败：先在 worktree 里 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`

package/templates/workspace/manifest.json

@@ -29,6 +29,7 @@
     ".claude/commands/ws-migrate.md",
     ".claude/commands/ws-dev.md",
     ".claude/commands/ws-analyze.md",
+    ".claude/commands/ws-finish.md",
     ".claude/commands/ws-review.md",
     ".claude/commands/ws-rule.md",
     ".claude/commands/ws-req-review.md",
@@ -44,6 +45,7 @@
     ".opencode/command/ws-migrate.md",
     ".opencode/command/ws-dev.md",
     ".opencode/command/ws-analyze.md",
+    ".opencode/command/ws-finish.md",
     ".opencode/command/ws-review.md",
     ".opencode/command/ws-rule.md",
     ".opencode/command/ws-req-review.md",
@@ -68,6 +70,7 @@
     ".iflow/commands/ws-migrate.toml",
     ".iflow/commands/ws-dev.toml",
     ".iflow/commands/ws-analyze.toml",
+    ".iflow/commands/ws-finish.toml",
     ".iflow/commands/ws-review.toml",
     ".iflow/commands/ws-rule.toml",
     ".iflow/commands/ws-contract-check.toml",
@@ -112,6 +115,7 @@
       ".agents/skills/aiws-change-list/SKILL.md",
       ".agents/skills/aiws-change-new/SKILL.md",
       ".agents/skills/aiws-change-start/SKILL.md",
+      ".agents/skills/aiws-change-finish/SKILL.md",
       ".agents/skills/aiws-change-status/SKILL.md",
       ".agents/skills/aiws-change-next/SKILL.md",
       ".agents/skills/aiws-change-sync/SKILL.md",
@@ -122,6 +126,7 @@
       ".agents/skills/ws-analyze/SKILL.md",
       ".agents/skills/ws-commit/SKILL.md",
       ".agents/skills/ws-dev/SKILL.md",
+      ".agents/skills/ws-finish/SKILL.md",
       ".agents/skills/ws-migrate/SKILL.md",
       ".agents/skills/ws-plan/SKILL.md",
       ".agents/skills/ws-preflight/SKILL.md",
@@ -149,6 +154,7 @@
       ".iflow/commands/ws-migrate.toml",
       ".iflow/commands/ws-dev.toml",
       ".iflow/commands/ws-analyze.toml",
+      ".iflow/commands/ws-finish.toml",
       ".iflow/commands/ws-review.toml",
       ".iflow/commands/ws-rule.toml",
       ".iflow/commands/ws-contract-check.toml",
@@ -178,6 +184,7 @@
       ".claude/commands/ws-migrate.md": ["claude:ws-migrate"],
       ".claude/commands/ws-dev.md": ["claude:ws-dev"],
       ".claude/commands/ws-analyze.md": ["claude:ws-analyze"],
+      ".claude/commands/ws-finish.md": ["claude:ws-finish"],
       ".claude/commands/ws-review.md": ["claude:ws-review"],
       ".claude/commands/ws-rule.md": ["claude:ws-rule"],
       ".claude/commands/ws-req-review.md": ["claude:ws-req-review"],
@@ -193,6 +200,7 @@
       ".opencode/command/ws-migrate.md": ["opencode:ws-migrate"],
       ".opencode/command/ws-dev.md": ["opencode:ws-dev"],
       ".opencode/command/ws-analyze.md": ["opencode:ws-analyze"],
+      ".opencode/command/ws-finish.md": ["opencode:ws-finish"],
       ".opencode/command/ws-review.md": ["opencode:ws-review"],
       ".opencode/command/ws-rule.md": ["opencode:ws-rule"],
       ".opencode/command/ws-req-review.md": ["opencode:ws-req-review"],