@aipper/aiws-spec 0.0.21 → 0.0.23

package/docs/spec-contract.md

@@ -18,6 +18,7 @@
 - managed surface（可托管面）：
   - `replace_file`：该文件由 aiws 全量托管（更新可整文件覆盖）。
   - `managed_blocks`：只更新文件内 `AIWS_MANAGED_BEGIN/END` 标记的托管块；块外内容保留给用户自定义。
+  - `remove`：该文件在本版本已废弃；`update` 会先备份再删除（可通过 `aiws rollback` 恢复）。仅用于跨版本改名/废弃场景。
 - unmanaged required（必需但不托管）：
   - 模板 `manifest.json` 里的 `required` 仅表示“init/validate 必须存在”。
   - 若某个 required 文件不在 `update.replace_file` 且不在 `update.managed_blocks` 中：视为用户自主管理内容；`aiws update` 不应修改其内容（最多只补齐缺失文件）。
@@ -127,8 +128,8 @@ hash 规则（用于跨平台稳定性）：
 - 默认覆盖：Claude Code / OpenCode / Codex / iFlow。
 
 约定路径（示例；最终以模板 manifest 为准）：
-- Claude Code：`.claude/commands/aiws-*.md`（commands）
-- OpenCode：`.opencode/command/aiws-*.md`（command）
+- Claude Code：`.claude/commands/p-aiws-*.md`（commands；私有原子入口）
+- OpenCode：`.opencode/command/p-aiws-*.md`（command；私有原子入口）
 - Codex：`.agents/skills/*/SKILL.md`（skills）
 - iFlow：`.iflow/commands/aiws-*.toml`（commands）
 
@@ -160,13 +161,13 @@ hash 规则（用于跨平台稳定性）：
 
 建议的默认取值（与 `workspace` 模板一致）：
 - Claude Code
-  - `path_pattern`：`.claude/commands/aiws-*.md`
+  - `path_pattern`：`.claude/commands/p-aiws-*.md`
   - `purpose`：提供“在 Claude 内可见的命令入口/说明”，引导用户运行 `npx @aipper/aiws ...`
   - `autodiscovery`：不作为契约要求（由工具决定；aiws 不做保证）
   - `reload_needed`：不作为契约要求
   - `fallback`：在 shell 直接运行 `npx @aipper/aiws init|update|validate|rollback`
 - OpenCode
-  - `path_pattern`：`.opencode/command/aiws-*.md`
+  - `path_pattern`：`.opencode/command/p-aiws-*.md`
   - `purpose`：提供命令入口/说明（同上）
   - `autodiscovery`：不作为契约要求
   - `reload_needed`：不作为契约要求

package/package.json

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

package/templates/workspace/.agents/skills/{aiws-change-archive → p-aiws-change-archive}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-archive
-description: 归档变更工件（会先做严格校验）
+name: p-aiws-change-archive
+description: 私有：归档变更工件（会先做严格校验并生成 handoff.md）
 ---
 
 目标：
@@ -21,3 +21,4 @@ fi
 说明：
 - `archive` 默认会先跑严格校验并要求 tasks 全部勾选
 - `--force` 会绕过部分门禁（不推荐）
+- 归档后会生成交接文档：`changes/archive/<date>-<change-id>/handoff.md`

package/templates/workspace/.agents/skills/{aiws-change-finish → p-aiws-change-finish}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-finish
-description: 安全合并 change/<change-id> 回目标分支（默认 fast-forward）
+name: p-aiws-change-finish
+description: 私有：安全合并 change/<change-id> 回目标分支（默认 fast-forward）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-list → p-aiws-change-list}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-list
-description: 列出 changes 工件（只读）
+name: p-aiws-change-list
+description: 私有：列出 changes 工件（只读）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-new → p-aiws-change-new}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-new
-description: 创建 changes/<change-id> 工件
+name: p-aiws-change-new
+description: 私有：创建 changes/<change-id> 工件
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-next → p-aiws-change-next}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-next
-description: 给出下一步建议（只读）
+name: p-aiws-change-next
+description: 私有：给出下一步建议（只读）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-start → p-aiws-change-start}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-start
-description: 切分支并初始化变更工件（可选安装 hooks）
+name: p-aiws-change-start
+description: 私有：切分支并初始化变更工件（可选安装 hooks）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-status → p-aiws-change-status}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-status
-description: 查看单个变更工件状态（只读）
+name: p-aiws-change-status
+description: 私有：查看单个变更工件状态（只读）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-sync → p-aiws-change-sync}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-sync
-description: 同步真值基线到 changes/<change-id>（写入 .ws-change.json）
+name: p-aiws-change-sync
+description: 私有：同步真值基线到 changes/<change-id>（写入 .ws-change.json）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-templates-init → p-aiws-change-templates-init}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-templates-init
-description: 在仓库内初始化 change templates（写入 changes/templates）
+name: p-aiws-change-templates-init
+description: 私有：在仓库内初始化 change templates（写入 changes/templates）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-templates-which → p-aiws-change-templates-which}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-templates-which
-description: 查看当前 change templates 来源（只读）
+name: p-aiws-change-templates-which
+description: 私有：查看当前 change templates 来源（只读）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-change-validate → p-aiws-change-validate}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-change-validate
-description: 校验 changes 工件（可 strict）
+name: p-aiws-change-validate
+description: 私有：校验 changes 工件（可 strict）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-hooks-install → p-aiws-hooks-install}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-hooks-install
-description: 启用 git hooks 门禁（core.hooksPath=.githooks）
+name: p-aiws-hooks-install
+description: 私有：启用 git hooks 门禁（core.hooksPath=.githooks）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-hooks-status → p-aiws-hooks-status}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-hooks-status
-description: 查看当前仓库 hooks 状态（只读）
+name: p-aiws-hooks-status
+description: 私有：查看当前仓库 hooks 状态（只读）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-init → p-aiws-init}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-init
-description: 初始化工作区（生成真值文件与门禁）
+name: p-aiws-init
+description: 私有：初始化工作区（生成真值文件与门禁）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-rollback → p-aiws-rollback}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-rollback
-description: 回滚工作区（从备份恢复）
+name: p-aiws-rollback
+description: 私有：回滚工作区（从备份恢复）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-update → p-aiws-update}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-update
-description: 更新工作区（刷新模板与托管块）
+name: p-aiws-update
+description: 私有：更新工作区（刷新模板与托管块）
 ---
 
 目标：

package/templates/workspace/.agents/skills/{aiws-validate → p-aiws-validate}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: aiws-validate
-description: 校验工作区（漂移检测 + 门禁）
+name: p-aiws-validate
+description: 私有：校验工作区（漂移检测 + 门禁）
 ---
 
 目标：

package/templates/workspace/.agents/skills/p-tasks-plan/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: p-tasks-plan
+description: 原子：tasks 同步（从 changes/<id>/tasks.md 生成 update_plan payload）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 用 `changes/<change-id>/tasks.md` 的 checkbox 任务作为“步骤真值”
+- 生成可直接用于 `update_plan` 的 JSON payload（`pending/in_progress/completed`）
+- 输出当前进度摘要（done/total + 当前 in_progress）
+
+约束：
+- 不写入任何 secrets（token、账号、内网端点等不得进入 git）
+- 只读 `changes/<id>/tasks.md`（不自动改写 tasks 文件）
+- 未运行不声称已运行
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`。
+2) 推断 `change-id`：
+   - 优先从当前分支名读取：`git rev-parse --abbrev-ref HEAD`（期望形如 `change/<change-id>`）
+   - 若无法推断：让用户明确本次要同步的 `<change-id>`
+3) 检查 tasks 文件存在：`test -f changes/<change-id>/tasks.md`
+4) 输出进度摘要：
+```bash
+python3 tools/ws_tasks_plan.py status --file changes/<change-id>/tasks.md
+```
+5) 生成 `update_plan` payload（JSON 输出到 stdout）：
+```bash
+python3 tools/ws_tasks_plan.py plan --file changes/<change-id>/tasks.md --explanation "sync tasks.md -> update_plan"
+```
+6) 调用 `update_plan`，将上一步 JSON 原样作为入参（确保任意时刻最多 1 条 `in_progress`）。
+
+输出要求：
+- `Change_ID:` <change-id>
+- `Tasks:` `changes/<change-id>/tasks.md`
+- `Next:` 推荐下一步（通常为继续完善 tasks 或进入 `$ws-dev`）

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

@@ -18,6 +18,7 @@ description: 提交（当前分支可直提；submodule 感知；先审计/门
 - 不自动 push
 - 不写入任何 secrets
 - 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
+- commit message 默认使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
 
 执行步骤（建议）：
 1) 运行 `$ws-preflight`（确保真值文件就绪）。
@@ -59,11 +60,22 @@ done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/d
 - 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target_branch>`；不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
 处理指引（detached submodule）：
 ```bash
-sub_name="<submodule-name>"
-base_branch="$(git branch --show-current)"
-cfg_branch="$(git config --file .gitmodules --get "submodule.${sub_name}.branch" 2>/dev/null || true)"
-if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-git -C "${sub_path}" checkout -B "aiws/pin/${cfg_branch}" HEAD
+cur_branch="$(git branch --show-current)"
+change_id="$(echo "${cur_branch}" | sed -n 's|^change/||p')"
+targets="changes/${change_id}/submodules.targets"
+
+source tools/ws_resolve_sub_target.sh
+ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${cur_branch}" || exit 2
+target_branch="${_resolved_branch}"
+remote="${_resolved_remote}"
+
+git -C "${sub_path}" fetch "${remote}" --prune
+if ! git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
+  echo "error: missing ${remote}/${target_branch} for submodule path=${sub_path}"
+  exit 2
+fi
+git -C "${sub_path}" checkout -B "aiws/pin/${target_branch}" HEAD
+git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
 ```
 7) 检查当前 staging 内容（必须输出给用户确认）：
 ```bash
@@ -71,7 +83,10 @@ git status --porcelain
 git diff --staged --submodule=short
 ```
 8) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
-9) 让用户提供 commit message（必须确认后再执行）。
+9) 生成中文 commit message 草案（格式：`<类型>: <简述>`），输出给用户确认后再执行。
+   - 类型参考：`功能` / `修复` / `重构` / `文档` / `测试` / `构建` / `杂项`
+   - 简述用一句话概括本次改动的"为什么"而非"改了什么"
+   - 命令/路径/代码标识符保持原样不翻译
 10) 执行提交（不带 `--no-verify`）：
 ```bash
 git commit -m "<message>"

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

@@ -29,6 +29,7 @@ description: 交付（submodules + superproject 分步提交，并安全合并
 
 ## 0) submodule branch 真值检查（减少 detached 与人为差异）
 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `$ws-submodule-setup` 并提交 `.gitmodules`，否则后续 `aiws validate .` 会失败，且 `ws-pull/ws-finish` 无法确定性工作。
+> 说明：若同一 superproject 分支内存在“多渠道 submodule 目标分支”的交付需求，可在 `changes/<change-id>/submodules.targets` 额外声明本次 change 的目标分支；交付时会优先使用该文件（不改变 `.gitmodules` 的团队默认真值）。
 ```bash
 if [[ -f .gitmodules ]]; then
   missing=0
@@ -44,6 +45,28 @@ if [[ -f .gitmodules ]]; then
     echo "hint: run $ws-submodule-setup (and commit .gitmodules), then retry"
     exit 2
   fi
+
+  # 强约束：当 .gitmodules 声明 submodules 时，要求本次 change 存在 submodules.targets 且覆盖所有 submodule path
+  if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+    change_id="$(git branch --show-current | sed -n 's|^change/||p')"
+    targets="changes/${change_id}/submodules.targets"
+    if [[ ! -f "${targets}" ]]; then
+      echo "error: missing ${targets} (required when .gitmodules declares submodules)"
+      exit 2
+    fi
+    t_missing=0
+    while read -r _ sub_path; do
+      [[ -z "${sub_path:-}" ]] && continue
+      if ! awk -v p="${sub_path}" '$1==p && $0 !~ /^[[:space:]]*#/ && $2!="" { found=1 } END { exit(found?0:1) }' "${targets}" 2>/dev/null; then
+        echo "error: ${targets} missing entry for submodule path=${sub_path}"
+        t_missing=1
+      fi
+    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+    if [[ "${t_missing}" -ne 0 ]]; then
+      echo "hint: fill ${targets} as: <path> <target_branch> [remote]"
+      exit 2
+    fi
+  fi
 fi
 ```
 
@@ -65,19 +88,25 @@ git -C "$sub_path" status --porcelain
 2) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
    - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
    - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
-   - 若你要在该 submodule 里提交：先按 `.gitmodules` 的目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
+   - 若你要在该 submodule 里提交：先按目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
+     - 目标分支真值优先级：`changes/<change-id>/submodules.targets`（若存在）> `.gitmodules submodule.<name>.branch`
 ```bash
-sub_name="<submodule-name>"
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
 base_branch="$(git branch --show-current)"
-cfg_branch="$(git config --file .gitmodules --get "submodule.${sub_name}.branch" 2>/dev/null || true)"
-if [[ "${cfg_branch:-}" == "." ]]; then cfg_branch="$base_branch"; fi
-if [[ -z "${cfg_branch:-}" ]]; then
-  echo "error: missing .gitmodules submodule.${sub_name}.branch (path=${sub_path})"
+
+source tools/ws_resolve_sub_target.sh
+ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${base_branch}" || exit 2
+target_branch="${_resolved_branch}"
+remote="${_resolved_remote}"
+
+git -C "$sub_path" fetch "${remote}" --prune
+if ! git -C "$sub_path" show-ref --verify --quiet "refs/remotes/${remote}/${target_branch}"; then
+  echo "error: missing ${remote}/${target_branch} for submodule path=${sub_path}"
   exit 2
 fi
-git -C "$sub_path" fetch origin --prune
-git -C "$sub_path" checkout -B "aiws/pin/${cfg_branch}" HEAD
-git -C "$sub_path" branch --set-upstream-to "origin/${cfg_branch}" "aiws/pin/${cfg_branch}" >/dev/null 2>&1 || true
+git -C "$sub_path" checkout -B "aiws/pin/${target_branch}" HEAD
+git -C "$sub_path" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
 ```
    - 若 `origin/<target-branch>` 不存在，或用户明确不想使用 pin 分支：停止，解释风险（提交可能不可追溯/难以推送）。
 3) 选择性 staging（默认用 `-p` 更安全）：

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

@@ -12,9 +12,68 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
    - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
    - 若已有 `plan/` 工件：先执行 `$ws-plan-verify`；通过后再进入实现（防止计划过长/跑偏）。
 2) 建立变更归因（推荐）：
-   - 推荐一键：`aiws change start <change-id> --hooks`（切分支 + 初始化变更工件 + 启用 hooks）
-   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`（创建独立 worktree；当前目录分支保持不变）
+   - ⚠️ 开始前先确认工作区干净：`git status --porcelain` 为空；否则切分支/创建 worktree 后，未提交改动可能“看起来丢了”（worktree 只从 `HEAD` checkout，未提交内容会留在原目录）。
+   - 强制（当你准备执行 `aiws change start ... --worktree/--switch` 创建新 change 时）：先同步线上代码（含 submodules），避免基线过旧导致的 rebase/冲突与“别人已更新但本地没拉”的协作摩擦。
+     - 若你已经在 `change/<change-id>` 上继续开发：不要在此处强制 pull（避免把远端变动拉进变更分支）；改为按需 `git fetch`/rebase，并保持门禁与验证可复现。
+     - 在 AI 工具中运行：`$ws-pull`（推荐；会在工作区不干净时阻断）
+     - 或等价手工（必须工作区干净；失败则停止并人工处理）：
+```bash
+cur="$(git branch --show-current)"
+if [[ "${cur}" =~ ^(change|changes|ws|ws-change)/ ]]; then
+  echo "info: already on change branch (${cur}); skip pull here"
+else
+  git status --porcelain
+  git pull --ff-only
+  if [[ -f .gitmodules ]]; then
+    git submodule sync --recursive
+    git submodule update --init --recursive
+  fi
+fi
+```
+   - 推荐更安全（默认）：`aiws change start <change-id> --hooks --no-switch`（只创建分支/工件 + 启用 hooks；不切分支）
+   - 准备进入实现（且工作区干净）后再切换：`git switch change/<change-id>`
+   - 若你明确要“一键切分支”（不推荐，且 dirty 会被拦截）：`aiws change start <change-id> --hooks --switch`
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`（创建独立 worktree；当前目录分支保持不变；会在新 worktree 内初始化 submodules；若忘了 `--submodules` 也会强制初始化）
    - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 若仓库存在 submodule（`.gitmodules` 声明了 submodule 条目）：进入编码前必须准备好 `changes/<change-id>/submodules.targets`，并把每个 submodule 挂到对应的 `aiws/pin/<target_branch>`（必要时切到 `<remote>/<target_branch>`；这可能会改变 superproject 的 gitlink 指针，属于预期的“选渠道”行为；缺失该文件会被门禁阻断）
+```bash
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
+has_submodules=0
+if [[ -f .gitmodules ]]; then
+  if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+    has_submodules=1
+  fi
+fi
+if [[ "${has_submodules}" -eq 1 && ! -f "${targets}" ]]; then
+  echo "error: missing ${targets} (required when .gitmodules declares submodules)"
+  exit 2
+fi
+
+if [[ -f "${targets}" ]]; then
+  echo "info: applying submodule targets: ${targets}"
+  while read -r sub_path target_branch remote; do
+    [[ -z "${sub_path:-}" ]] && continue
+    [[ "${sub_path}" == \#* ]] && continue
+    [[ -z "${target_branch:-}" ]] && { echo "error: missing target_branch for path=${sub_path}"; exit 2; }
+    remote="${remote:-origin}"
+
+    echo "== submodule: ${sub_path} target=${remote}/${target_branch} =="
+    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null)" ]]; then
+      echo "error: submodule dirty: ${sub_path} (commit/stash first)"
+      exit 2
+    fi
+    git -C "${sub_path}" fetch "${remote}" --prune
+    # 选渠道：默认切到远端目标分支，并用 pin 分支承载本地提交（避免 detached）
+    git -C "${sub_path}" checkout -B "aiws/pin/${target_branch}" "${remote}/${target_branch}"
+    git -C "${sub_path}" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
+    git -C "${sub_path}" status -sb
+  done < "${targets}"
+
+  # 检查 superproject 的 gitlink 是否发生变化（预期：若切了不同渠道，会看到差异）
+  git diff --submodule
+fi
+```
    - 若你明确要在 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`）（避免需求漂移）。

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

@@ -78,6 +78,8 @@ fi
 ```bash
 # superproject 当前分支（finish 后通常是 base 分支）
 base_branch="$(git branch --show-current)"
+change_id="<change-id>"
+targets="changes/${change_id}/submodules.targets"
 
 # 子模块清单（没有则跳过）
 git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true
@@ -89,38 +91,50 @@ git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null |
 # - 不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来“解 detached”
 # - 不改动 submodule 现有分支指针（例如不强行移动 main/master）
 # - 创建/更新本地 pin 分支：`aiws/pin/<target_branch>` 指向 gitlink commit，并将其 upstream 设为 `origin/<target_branch>`
-sub_sha="$(git rev-parse "HEAD:<sub_path>")"
-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 and skip auto-push"
-  continue
-fi
-target_branch="$cfg_branch"
-pin_branch="aiws/pin/${target_branch}"
+if git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+  if [[ ! -f “${targets}” ]]; then
+    echo “error: missing ${targets} (required when .gitmodules declares submodules)”
+    exit 2
+  fi
 
-git -C "<sub_path>" fetch origin --prune
-if ! git -C "<sub_path>" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-  echo "[warn] <sub_path>: origin/${target_branch} not found; keep detached and skip auto-push"
-  continue
-fi
+  source tools/ws_resolve_sub_target.sh
 
-# 仅当 gitlink commit 属于 origin/<target_branch> 的历史时才“挂回分支”
-if ! git -C "<sub_path>" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-  echo "[warn] <sub_path>: ${sub_sha} is not in origin/${target_branch}; keep detached and stop (need manual reconcile)"
-  exit 1
-fi
+  while read -r key sub_path; do
+      name=”${key#submodule.}”; name=”${name%.path}”
+      [[ -z “${sub_path:-}” ]] && continue
+      echo “== submodule: ${sub_path} (${name}) ==”
+
+      sub_sha=”$(git rev-parse “HEAD:${sub_path}”)”
+
+      ws_resolve_sub_target “${sub_path}” “${name}” “${targets}” “${base_branch}” || exit 2
+      target_branch=”${_resolved_branch}”
+      remote=”${_resolved_remote}”
+      pin_branch=”aiws/pin/${target_branch}”
 
-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
-git -C "<sub_path>" status -sb
+      git -C “${sub_path}” fetch “${remote}” --prune
+      if ! git -C “${sub_path}” show-ref --verify --quiet “refs/remotes/${remote}/${target_branch}”; then
+        echo “error: ${sub_path}: missing ${remote}/${target_branch}; refusing to push superproject (would break gitlink fetchability)”
+        exit 2
+      fi
 
-# push：只允许 fast-forward（若远端分叉会被拒绝；此时必须人工处理）
-git -C "<sub_path>" push origin "${sub_sha}:refs/heads/${target_branch}"
+      # 仅当 gitlink commit 属于 <remote>/<target_branch> 的历史时才”挂回分支”
+      if ! git -C “${sub_path}” merge-base --is-ancestor “${sub_sha}” “${remote}/${target_branch}”; then
+        echo “[warn] ${sub_path}: ${sub_sha} is not in ${remote}/${target_branch}; keep detached and stop (need manual reconcile)”
+        exit 1
+      fi
+
+      git -C “${sub_path}” checkout -B “${pin_branch}” “${sub_sha}”
+      git -C “${sub_path}” branch --set-upstream-to “${remote}/${target_branch}” “${pin_branch}” >/dev/null 2>&1 || true
+      git -C “${sub_path}” status -sb
+
+      # push：只允许 fast-forward（若远端分叉会被拒绝；此时必须人工处理）
+      git -C “${sub_path}” push “${remote}” “${sub_sha}:refs/heads/${target_branch}”
+    done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
+fi
 ```
 规则：
 - 每个 submodule 必须先执行“pin 分支挂回 + fast-forward push”，再 push 主仓库。
-- 若任一 submodule 的 gitlink commit 不在 `origin/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
+- 若任一 submodule 的 gitlink commit 不在 `<remote>/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
 
 5) 仅当 submodules 全部成功后，再 push superproject 当前分支：
 ```bash

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

@@ -0,0 +1,31 @@
+---
+name: ws-handoff
+description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
+- 指引在归档与依赖场景下如何使用 handoff
+
+说明：
+- `handoff.md` 由 `aiws change archive` 自动生成：`changes/archive/<date>-<change-id>/handoff.md`
+- `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
+
+执行建议：
+1) 先运行 `$ws-preflight`。
+2) 若本 change 已完成并准备归档：运行 `aiws change archive <change-id>`（会先做严格校验，并移动目录到 `changes/archive/`，同时生成 `handoff.md`）。
+3) 查看 handoff：
+```bash
+change_id="<change-id>"
+ls -1 changes/archive/*-"${change_id}"/handoff.md
+sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
+```
+4) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
+
+输出要求：
+- `Change_ID:` <change-id>
+- `Handoff:` `changes/archive/.../handoff.md`
+- `Next:` 若还有后续工作，建议创建新 change 并在其 `Depends_On` 引用本 change
+

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

@@ -34,6 +34,7 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
    - `Non-goals`：明确不做什么（避免 scope creep）
    - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
+   - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
    - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
    - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
@@ -42,6 +43,37 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 9) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
 10) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
 
+补充：submodule 目标分支真值（强约束；同一 superproject 分支内可多渠道）
+- 背景：`.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`
+  - 格式：每行一个 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}"
+```
+- 计划里必须写清：本次交付选择的 `targets` 内容，以及后续在 `$ws-dev` 进入编码前会把 submodules 挂到 `aiws/pin/<target_branch>`（必要时先 `fetch`）。
+
 输出要求：
 - `Plan file:` <实际写入的路径>
 - `Next:` 推荐下一步（先 `$ws-plan-verify`，通过后再 `$ws-dev`；或 `aiws change start <change-id> --hooks`，superproject + submodule 可用 `--worktree`）