@aipper/aiws-spec 0.0.3 → 0.0.5

package/docs/cli-interface.md

@@ -231,6 +231,7 @@
 - 若 `changes/<change-id>/` 不存在：等价执行 `aiws change new ...`。
 - 可选：`--hooks` 等价于 `aiws hooks install .`。
 - 可选：`--switch` 显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义；否则等价于默认行为）。
+  - 实现细节：当存在 `.gitmodules` 且使用 `--switch` 时，CLI 会尝试使用 `git switch/checkout --recurse-submodules` 让 submodules 工作区跟随 superproject 指针；若 git 不支持该选项，会降级为普通切分支并提示手工更新 submodules。
 - 可选：`--no-switch` 不切换当前分支（仅确保目标分支存在，并初始化变更工件）；适用于 superproject + submodule 场景，避免意外切换 A 目录分支导致 submodule 状态混乱。
 - 可选：`--worktree` 使用 `git worktree` 创建一个独立工作区并在其中 checkout `change/<change-id>`，当前目录分支保持不变（推荐用于 superproject + submodule）。
   - 默认 worktree 目录：`../<repo-name>-<change-id>`（相对于 git root）

package/package.json

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

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

@@ -0,0 +1,114 @@
+---
+name: ws-deliver
+description: 交付（submodules + superproject 分步提交，并安全合并回目标分支）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 适配 superproject + submodule（数量不固定）的交付收尾：
+  1) 先逐个提交 submodule（每个 repo 单独确认 commit message）
+  2) 再提交 superproject（包含 submodule gitlink 指针更新 + 变更工件/代码）
+  3) 最后 fast-forward 合并回目标分支（复用 `aiws change finish`，减少手动 merge 出错）
+
+非目标（强制）：
+- 不自动 `git add -A`（避免误提交）
+- 不自动 push
+- 不自动删除分支
+
+前置（强制）：
+1) 先运行 `$ws-preflight`。
+2) 确认当前处于 change 分支（推荐）：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）。
+   - 若不在 change 分支：要求用户先切换到 `change/<change-id>`（或在命令里显式提供 `<change-id>`）。
+3) 任何自动提交都必须在提交前输出：
+   - 该 repo 的 `git status --porcelain`
+   - 该 repo 的 `git diff --staged`
+   并让用户确认 commit message（每个 repo 单独确认）。
+
+建议流程（按顺序）：
+
+## A) 发现 submodules 清单（数量不固定）
+在 superproject 根目录执行：
+```bash
+git submodule status --recursive
+```
+如果没有 submodule：跳到 C)。
+
+## B) 逐个提交 submodules（先 submodule，后 superproject）
+对每个 submodule path（可递归）重复以下步骤（建议按 `git submodule status --recursive` 顺序）：
+1) 定位并检查状态：
+```bash
+sub_path="<path>"
+git -C "$sub_path" branch --show-current
+git -C "$sub_path" status --porcelain
+```
+2) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
+   - 默认建议：在该 submodule 内创建并切到同名 change 分支（与 superproject 对齐），例如 `change/<change-id>`：
+```bash
+git -C "$sub_path" switch -c "change/<change-id>"
+```
+   - 若用户明确不想建分支：停止，解释风险（提交可能不可追溯/难以推送）。
+3) 选择性 staging（默认用 `-p` 更安全）：
+```bash
+git -C "$sub_path" add -p
+git -C "$sub_path" diff --staged --stat
+git -C "$sub_path" diff --staged
+```
+4) AI 生成该 submodule 的 commit message（标题+可选 body），并让用户确认（每个 repo 单独确认）。
+5) 执行提交（不带 `--no-verify`）：
+```bash
+git -C "$sub_path" commit -m "<message>"
+```
+6) 若该 submodule 没有 staged changes：跳过（不要硬提交空 commit）。
+
+## C) 提交 superproject（更新 gitlinks + 自身改动 + changes 工件）
+1) 先检查 submodule 指针差异（gitlinks）：
+```bash
+git diff --submodule
+```
+2) 选择性 staging：
+   - 先 stage 发生指针变化的 submodule 路径（明确列出）：
+```bash
+git add <submodule-path-1> <submodule-path-2>
+```
+   - 再 stage superproject 自身改动（默认 `-p`）：
+```bash
+git add -p
+git diff --staged --stat
+git diff --staged
+```
+3) AI 生成 superproject 的 commit message（应包含 “bump submodule <name> -> <sha>” 等关键信息），并让用户确认。
+4) 提交：
+```bash
+git commit -m "<message>"
+```
+
+## D) 门禁与证据（推荐）
+```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
+```
+
+## E) 安全合并回目标分支（fast-forward）
+优先使用 `$ws-finish`（底层调用 `aiws change finish`）。
+
+若需要显式指定目标分支：
+```bash
+aiws change finish <change-id> --into <base-branch>
+```
+
+## F) （可选）归档变更工件
+```bash
+aiws change archive <change-id>
+```
+
+输出要求：
+- `Submodules:` 每个 submodule 的分支/提交摘要（repo → commit sha → message）
+- `Superproject:` 提交摘要
+- `Merge:` `aiws change finish` 的输出（into/from）
+- `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）

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

@@ -13,6 +13,7 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 2) 建立变更归因（推荐）：
    - 推荐一键：`aiws change start <change-id> --hooks`（切分支 + 初始化变更工件 + 启用 hooks）
    - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`（创建独立 worktree；当前目录分支保持不变）
+   - 若你明确要在 superproject 直接切分支：`aiws change start <change-id> --hooks --switch`（仅在存在 `.gitmodules` 时有意义；会尝试让 submodules 工作区跟随 superproject 指针）
    - 或手工：`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`（问题）。

package/templates/workspace/manifest.json

@@ -126,6 +126,7 @@
       ".agents/skills/ws-analyze/SKILL.md",
       ".agents/skills/ws-commit/SKILL.md",
       ".agents/skills/ws-dev/SKILL.md",
+      ".agents/skills/ws-deliver/SKILL.md",
       ".agents/skills/ws-finish/SKILL.md",
       ".agents/skills/ws-migrate/SKILL.md",
       ".agents/skills/ws-plan/SKILL.md",