@aipper/aiws-spec 0.0.27 → 0.0.29

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

@@ -1,217 +1,18 @@
 ---
 name: ws-finish
-description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push）
+description: `aiws ws-finish` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-finish
 
-目标：
-- 在结束一次变更交付时，用 fast-forward 安全合并 `change/<change-id>` 回目标分支，减少手输分支名导致的错误
-- 合并成功后，按 `submodule -> superproject` 顺序 push，避免遗漏导致其它仓库拉取异常
-- 不自动删分支；AI 入口执行前应先向用户说明将要 push 的 remote/branch，显式传入 `--push` 即视为确认
-- 若团队希望减少 submodule detached 的人为差异：建议在 `.gitmodules` 配置 `submodule.<name>.branch`，并在日常拉取时使用 `$ws-pull`
+`aiws ws-finish` 的薄包装入口。
 
-前置（必须）：
-- 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
-- change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若使用 worktree：普通 finish 的 `validate/evidence/state` 先在 `change/<change-id>` worktree 完成；真正执行 `aiws change finish` 时再切到目标分支所在 worktree（命令会提示正确的 worktree）
-- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`：说明 merge 已发生，只剩 push / archive / cleanup closeout；直接在该 worktree 运行 `aiws change finish <change-id> --push`，不要先跑 `aiws validate . --stamp`
-- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则无法确定性减少 detached；先运行 `$ws-submodule-setup` 并提交 `.gitmodules`）
-
-阶段定位：
-- finish 阶段；负责把已提交的 change 安全合并回目标分支，并按约束完成 push / worktree cleanup。
-
-必需输入：
-- 干净的当前工作区
-- 已提交完成的 `change/<change-id>`
-- 若存在 submodule：`.gitmodules` 与 `changes/<change-id>/submodules.targets`
-- 当前 push 目标说明（remote / branch）
-
-必需输出：
-- `Merge:` `aiws change finish` 的结果（from / into）
-- `Push:` 实际 remote / branch 或未 push 原因
-- `Worktree cleanup:` 清理结果
-- `Evidence:` validate stamp / evidence / state 路径
-
-阻断条件：
-- 工作区不干净
-- 缺失 submodule branch / targets 真值
-- fast-forward 失败
-- 子模块目标分支无法安全 push
-
-完成判定：
-- change 已安全合并回目标分支，必要的 push 与 worktree cleanup 已完成或明确说明未完成原因。
-
-建议步骤：
-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
-```
-0.5) 先运行 `aiws change status <change-id>`，优先看稳定字段 `governance_rule:`：
-- 若为 `finish_resume_required`：直接跳到步骤 2 执行 `aiws change finish <change-id> --push`
-- 若不是该值：按普通 finish 继续；不要依赖自然语言提示句做分支判断
-
-1) （推荐，仅适用于普通 finish，且应在 `change/<change-id>` worktree 执行）先跑一次门禁并落盘证据：
-```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
-```
-若你已经位于目标分支 worktree，且 `governance_rule` 不是 `finish_resume_required`：
-- 不要在这里跑 `aiws validate . --stamp`
-- 先回 `change/<change-id>` worktree 补齐 finish gate，或先跑 `$ws-verify-before-complete`
-1.1) （强烈建议，仅适用于普通 finish）收敛持久证据并回填 `Evidence_Path`：
-```bash
-change_id="<change-id>"
-if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change evidence "${change_id}"
-elif command -v aiws >/dev/null 2>&1; then
-  aiws change evidence "${change_id}"
-else
-  npx @aipper/aiws change evidence "${change_id}"
-fi
-```
-1.2) （可选，仅适用于普通 finish）生成状态快照（建议）：
-```bash
-aiws change state "${change_id}" --write
-```
-2) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接使用最小收尾闭环：
-```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}" --push
-elif command -v aiws >/dev/null 2>&1; then
-  aiws change finish "${change_id}" --push
-else
-  npx @aipper/aiws change finish "${change_id}" --push
-fi
-```
-说明：
-- 该命令会在 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；CLI 本身只有在显式传入 `--push` 时才会真正执行 push。
-
-3) 若你需要先处理 submodules，则不要依赖当前分支名推断目标分支，先显式解析 `base_branch`，再执行 submodule 步骤，最后回到主仓库执行 `aiws change finish --push`：
-```bash
-change_id="<change-id>"
-base_branch="$(python3 - <<'PY'
-import json, pathlib
-change_id = "<change-id>"
-meta = pathlib.Path("changes") / change_id / ".ws-change.json"
-data = json.loads(meta.read_text(encoding="utf-8"))
-print((data.get("base_branch") or "").strip())
-PY
-)"
-test -n "$base_branch"
-```
-4) 若 fast-forward 失败（提示需要 rebase）：先在 change 分支（或对应 worktree）里 `git rebase <target-branch>`，再重试 `aiws change finish --push`。
-5) 若存在 `.gitmodules`，先把每个 submodule 的 gitlink commit 合并回其目标分支（解决 detached HEAD），并按顺序 push：
-```bash
-# 不要用当前分支名代替目标分支；这里显式使用 .ws-change.json 的 base_branch
-change_id="<change-id>"
-targets="changes/${change_id}/submodules.targets"
-
-# 子模块清单（没有则跳过）
-git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true
-
-# 对每个 submodule.<name>.path <sub_path>：
-# 说明：`git submodule update` 会把 submodule checkout 到固定 gitlink commit，导致 detached HEAD。
-# 为减少游离状态的协作摩擦，本步骤采用 pin 分支策略：
-# - `changes/<change-id>/submodules.targets` 是本次 finish/push 的真值；每个 submodule path 都必须在该文件中声明目标分支（可选 remote）
-# - `.gitmodules` 的 `submodule.<name>.branch` 仍建议保留，用于团队默认配置与校验，但不再作为 finish/push 的 fallback
-# - 生成/检查 `submodules.targets` 时可显式说明默认来源：
-#   - detached HEAD：默认建议取 `.gitmodules` 的 `submodule.<name>.branch`
-#   - 已附着在某个本地分支：默认建议取当前分支
-#   - 以上仅为预填建议；真正执行 finish/push 时仍只认 `submodules.targets`
-# - 不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来解 detached
-# - 不改动 submodule 现有分支指针（例如不强行移动 main/master）
-# - 创建/更新本地 pin 分支：`aiws/pin/<target_branch>` 指向 gitlink commit，并将其 upstream 设为 `origin/<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
-
-  source tools/ws_resolve_sub_target.sh
-
-  while read -r key sub_path; do
-      name="${key#submodule.}"; name="${name%.path}"
-      [[ -z "${sub_path:-}" ]] && continue
-      echo "== submodule: ${sub_path} (${name}) =="
-
-      current_branch="$(git -C "${sub_path}" branch --show-current 2>/dev/null || true)"
-      declared_branch="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
-      if [[ -n "${current_branch}" ]]; then
-        echo "info: ${sub_path} default suggestion would be current branch: ${current_branch}"
-      elif [[ -n "${declared_branch}" ]]; then
-        echo "info: ${sub_path} default suggestion would be .gitmodules branch: ${declared_branch}"
-      else
-        echo "warn: ${sub_path} has no current branch and no .gitmodules branch; submodules.targets must be filled manually"
-      fi
-
-      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}" 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
-
-      # 仅当 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 不在 `<remote>/<target_branch>` 历史中：立即停止，先人工处理分叉，再继续。
-
-6) 仅当 submodules 全部成功后，再在 superproject 当前分支执行最小收尾闭环：
 ```bash
-change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change finish "${change_id}" --push
+  ./node_modules/.bin/aiws ws-finish
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change finish "${change_id}" --push
+  aiws ws-finish
 else
-  npx @aipper/aiws change finish "${change_id}" --push
+  npx @aipper/aiws ws-finish
 fi
 ```
-说明：
-- 该命令内部已经包含主仓库 push 成功后安全清理独立 change worktree 的逻辑。
-- 当 `--push` 完整成功时，还会自动把 `changes/<change-id>/` 归档到 `changes/archive/...`，生成 `handoff.md`，并补一个 `归档: <change-id>` commit。

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

@@ -1,52 +1,18 @@
 ---
 name: ws-handoff
-description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
+description: `aiws ws-handoff` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-handoff
 
-目标：
-- 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
-- 若存在协同工件：在 handoff 中一并概述 `analysis/`、`patches/`、`review/`、`evidence/`
-- 指引在归档与依赖场景下如何使用 handoff
+`aiws ws-handoff` 的薄包装入口。
 
-说明：
-- `handoff.md` 默认由 `aiws change finish --push` 自动归档时生成：`changes/archive/<date>-<change-id>/handoff.md`
-- `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
-
-阶段定位：
-- handoff / archive 阶段；负责查看或补充已归档 change 的交接说明。
-
-必需输入：
-- 已归档的 `change/<change-id>`
-- 对应 archive 目录
-
-必需输出：
-- `Change_ID:` 当前交接对象
-- `Handoff:` `changes/archive/.../handoff.md`
-- `Next:` 推荐后续 change / `Depends_On` 关系
-
-阻断条件：
-- 无法定位目标 change
-- `handoff.md` 无法生成或读取
-
-完成判定：
-- 下一位协作者可以只依赖 `handoff.md` 和绑定信息继续工作，而不需要回溯整段会话。
-
-执行建议：
-1) 先运行 `$ws-preflight`。
-2) 先确认本 change 已通过 `aiws change finish <change-id> --push` 完成自动归档。
-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
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws ws-handoff
+elif command -v aiws >/dev/null 2>&1; then
+  aiws ws-handoff
+else
+  npx @aipper/aiws ws-handoff
+fi
 ```
-4) 若是历史/异常场景，尚未归档且需要手工恢复，再运行 `aiws change archive <change-id>`。
-5) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
-6) 若本 change 使用了外部 / 子 agent 协作：确认关键结论已经进入 `review/` 或 `evidence/`，避免 handoff 只留下原始 patch/分析文件而没有最终结论。
-
-输出要求：
-- `Change_ID:` <change-id>
-- `Handoff:` `changes/archive/.../handoff.md`
-- `Next:` 若还有后续工作，建议创建新 change 并在其 `Depends_On` 引用本 change

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

@@ -0,0 +1,87 @@
+---
+name: ws-intake
+description: 计划前置澄清（逐条冻结问题并产出 intake 草案，供 ws-plan 消费）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在进入 `$ws-plan` 前，把新需求或中大型变更里的待确认问题逐条澄清并冻结
+- 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论
+- 产出一份可被 `$ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`
+
+约束：
+- 不直接创建 change，不直接落正式 `plan/...`，不直接进入实现
+- 同一时刻只能有 1 条问题处于 `in_discussion`
+- 当前问题没有被标记为 `frozen` 或 `deferred` 前，不进入下一题
+- 新衍生问题只加入 `Open Questions` 队列，不抢占当前问题
+
+阶段定位：
+- pre-planning 阶段；负责把“多轮沟通”从正式计划阶段剥离出来，先冻结需求结论。
+
+必需输入：
+- 当前任务描述
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 若已存在：最新 `plan/*.intake.md`
+
+必需输出：
+- `Intake file:` 实际写入的 `plan/*.intake.md`
+- `Current question:` 当前正在处理的问题
+- `Open Questions:` 尚未冻结的问题列表
+- `Frozen Decisions:` 已冻结结论
+- `Ready for ws-plan:` yes/no
+- `Next:` 继续 `$ws-intake` 或进入 `$ws-plan`
+
+阻断条件：
+- 无法确定项目根或真值文件缺失
+- 当前问题无法被表达为具体、可冻结的决策
+- 无法把澄清结果实际写盘
+
+完成判定：
+- 已有一份最新 intake 草案，且当前轮次至少把 1 条问题推进到 `frozen` 或 `deferred`
+- 当 `Open Questions` 已清空，或剩余问题明确被标记为 `deferred`，输出 `Ready for ws-plan: yes`
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`，读取真值文件并输出约束摘要。
+2) 读取当前任务描述；若存在最新 `plan/*.intake.md`，先读取其中的：
+   - `Open Questions`
+   - `Resolved Questions`
+   - `Frozen Decisions`
+   - `Draft Scope`
+   - `Draft Verify`
+3) 初始化或续写问题队列：
+   - 把当前任务拆成 `N` 条待决问题
+   - 每条问题都要写成一句明确的决策句，而不是模糊话题
+   - 状态只允许：`open` / `in_discussion` / `frozen` / `deferred`
+4) 选择唯一的当前问题：
+   - 优先取已有 `in_discussion`
+   - 否则取最影响 `Goal / Scope / Verify / Binding` 的 `open`
+5) 对当前问题输出并沟通：
+   - `Current question:`
+   - `Why it matters:`
+   - `Current options / current understanding:`
+   - `Exit condition:` 这条问题在什么条件下算谈完
+6) 只推进当前问题：
+   - 允许围绕这 1 条问题多轮问答
+   - 若用户回答引出新问题：加入 `Open Questions`
+   - 若当前问题已经有明确结论：标记为 `frozen`
+   - 若当前问题故意留到后面：标记为 `deferred`
+7) 每次落盘 `plan/<timestamp>-<slug>.intake.md`，至少包含：
+   - `Context`
+   - `Open Questions`
+   - `Resolved Questions`
+   - `Frozen Decisions`
+   - `Draft Scope`
+   - `Draft Verify`
+   - `Ready for ws-plan: yes/no`
+8) 判断是否可以移交给 `$ws-plan`：
+   - 若仍有关键问题未冻结：`Ready for ws-plan: no`，`Next: 继续 $ws-intake`
+   - 若关键问题已冻结，剩余仅是实现细节或已标记 `deferred`：`Ready for ws-plan: yes`，`Next: $ws-plan`
+
+输出要求：
+- `Intake file:` <实际写入的路径>
+- `Current question:` <当前问题>
+- `Open Questions:` <剩余问题列表>
+- `Frozen Decisions:` <已冻结结论>
+- `Ready for ws-plan:` <yes/no>
+- `Next:` <继续 `$ws-intake` 或进入 `$ws-plan`>

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

@@ -24,6 +24,7 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 必需输入：
 - 当前任务描述
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 若已存在：最新 `plan/*.intake.md`
 - 若已存在：`changes/<change-id>/proposal.md`
 - 若已有计划：当前 `plan/...` 文件
 
@@ -44,9 +45,13 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 
 执行步骤（建议）：
 1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
-2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
-3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
-4) 识别或建立主索引 / change 上下文：
+2) 若存在最新 `plan/*.intake.md`：
+   - 优先读取其中的 `Open Questions` / `Resolved Questions` / `Frozen Decisions` / `Draft Scope` / `Draft Verify`
+   - 若 `Ready for ws-plan: yes`，把它作为本次计划输入
+   - 若仍有未冻结问题，或明确写着 `Ready for ws-plan: no`：停止，并回退到 `$ws-intake`
+3) 若用户任务描述不清，且也没有可消费的 intake 草案：先问 1-3 个关键澄清问题（不要猜）；若问题较多则回退到 `$ws-intake`
+4) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
+5) 识别或建立主索引 / change 上下文：
    - 若存在 `changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
    - 若缺失关键绑定：先补齐 proposal（至少 `Change_ID`、`Req_ID|Problem_ID`、`Contract_Row`）再继续生成计划
    - 若当前不在 `change/<change-id>` 分支 / worktree，且本次任务需要新建 change：先调用 `aiws change start` 建立上下文，再继续写 plan
@@ -81,25 +86,26 @@ else
 fi
 ```
    - 若上一步创建了 worktree：后续所有读取/写入都必须切到 `aiws change start` 输出的 `worktree:` 路径中进行；不要把 `plan/...` 写回原工作区
-5) 生成计划文件：
+6) 生成计划文件：
    - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
    - 若 `plan/` 不存在先创建
    - 必须实际写入到磁盘（不要只在对话里输出）；如因权限/策略无法写盘，必须明确说明原因并输出可复制的完整内容
    - 计划必须写在当前 active change 上下文内：若当前已进入 `change/<change-id>` worktree，则 `plan/...`、`proposal.md`、`tasks.md` 都应写在该 worktree 中
-6) 计划内容至少包含（不要留空）：
+7) 计划内容至少包含（不要留空）：
    - `Bindings`：`Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
    - `Goal`：要达成什么
    - `Non-goals`：明确不做什么（避免 scope creep）
+   - `Intake Decisions`（若消费了 intake 草案）：列出本次从 intake 继承的已冻结结论；不要重新打开除非明确发现冲突
    - `Scope`：默认写成 `## Scope` 或 `## 影响范围（Scope）`，并包含 `### In Scope` / `### Out of Scope`；`In Scope` 下列出允许修改的文件/目录清单（支持 glob，不确定就写 `TBD` 并说明如何确定）
    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
    - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
    - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
    - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
-7) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
-8) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
-9) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
-10) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
+8) 若存在 change proposal：回填并对齐 `proposal.md` 的 `Plan_File`（必要时同步 `Contract_Row` / `Evidence_Path`），保证 plan/proposal 一致。
+9) 运行 `$ws-plan-verify` 作为执行前质量门（计划不过长、不跑偏、验证可复现）。
+10) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
+11) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
 
 补充：submodule 目标分支真值（强约束；同一 superproject 分支内可多渠道）
 - 背景：`.gitmodules submodule.<name>.branch` 适合作为“团队默认分支真值”，但当同一 superproject 分支需要在不同交付中选择不同 submodule 目标分支（多渠道）时，仅靠 `.gitmodules` 不足。

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

@@ -1,61 +1,18 @@
 ---
 name: ws-plan-verify
-description: 计划质检（执行前检查计划是否过长/跑偏，并给出最小修正清单）
+description: `aiws ws-plan-verify` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-plan-verify
 
-目标：
-- 在进入 `$ws-dev` 前，对 `plan/...` 与 `changes/<change-id>/proposal.md` 做一次“硬约束”质检
-- 避免计划过长、步骤不够具体、验证不可复现、与需求合同绑定不一致
-- 失败时只给最小修正项，修完后再进入实现
+`aiws ws-plan-verify` 的薄包装入口。
 
-适用时机：
-- 已执行过 `$ws-plan`，且准备开始编码
-- 或用户反馈“计划太长/容易跑偏”，需要先压缩并对齐
-
-阶段定位：
-- planning gate；负责在编码前检查计划是否满足 change 严格契约。
-
-必需输入：
-- 当前 `plan/...`
-- `changes/<change-id>/proposal.md`
-- 当前 change 上下文
-
-必需输出：
-- `Quality gate:` pass/fail
-- `Fix list:` 最小修正项
-- `Next:` 通过则 `$ws-dev`，未通过则继续修正并复跑
-
-阻断条件：
-- 无法定位当前 change 或计划文件
-- `aiws change validate <change-id> --strict` 未通过
-
-完成判定：
-- 计划满足严格门禁，且后续实现可以在不补需求/补绑定的情况下直接开始。
-
-执行步骤（建议）：
-1) 先运行 `$ws-preflight`。
-2) 识别 change 上下文：
-   - 优先从当前分支推断 `change/<change-id>`
-   - 若无法推断：读取 `changes/*/proposal.md` 中的 `Change_ID`，并让用户确认本次要质检的 change
-3) 运行严格门禁（这是硬约束入口）：
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws change validate <change-id> --strict
+  ./node_modules/.bin/aiws ws-plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change validate <change-id> --strict
+  aiws ws-plan-verify
 else
-  npx @aipper/aiws change validate <change-id> --strict
+  npx @aipper/aiws ws-plan-verify
 fi
 ```
-4) 若失败：按报错逐条修正 `proposal.md` / `plan/...`，优先级如下：
-   - 先修绑定：`Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
-   - 再修计划质量：必需章节、步骤数量、步骤具体性、验证命令与预期
-5) 复跑 strict 校验，直到通过。
-6) 输出“可执行最小计划摘要”（3-8 步），再进入 `$ws-dev`。
-
-输出要求：
-- `Quality gate:` pass/fail
-- `Fix list:` 仅保留必须修改项（按阻断级别排序）
-- `Next:` 通过后建议 `$ws-dev`；未通过则继续修正并复跑 strict

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

@@ -6,6 +6,7 @@ description: 评审（提交前审计与证据落盘）
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
+若当前语境已经明确是“准备交付/finish”，则本入口不应只停留在通用 review：应继续同时补齐 `$ws-spec-review` 与 `$ws-quality-review`，把 dual review gate 一次性收敛完。
 
 阶段定位：
 - review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
@@ -40,7 +41,11 @@ description: 评审（提交前审计与证据落盘）
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-4) 回复中输出：
+4) 若当前任务已进入“准备提交/交付/finish”的语境，继续补齐 dual review gate：
+   - 运行/收敛 `$ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`（或回退 `.agentdocs/tmp/review/spec-review.md`）
+   - 运行/收敛 `$ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`（或回退 `.agentdocs/tmp/review/quality-review.md`）
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令

package/templates/workspace/.agents/skills/ws-verify-before-complete/SKILL.md

@@ -1,59 +1,18 @@
 ---
 name: ws-verify-before-complete
-description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+description: `aiws ws-verify-before-complete` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-verify-before-complete
 
-目标：
-- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
-- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+`aiws ws-verify-before-complete` 的薄包装入口。
 
-阶段定位：
-- finish 前 gate；负责 completion readiness 检查，不直接做 merge / push / handoff。
-
-必需输入：
-- `changes/<change-id>/review/spec-review.md`
-- `changes/<change-id>/review/quality-review.md`
-- `.agentdocs/tmp/aiws-validate/*.json`
-- 若存在：`changes/<change-id>/evidence/...`、`git status`
-
-必需输出：
-- `证据（Evidence）:` `changes/<change-id>/evidence/verify-before-complete.md` 或回退 `.agentdocs/tmp/review/verify-before-complete.md`
-- `结论（Result）:` pass / fail
-- `缺失项（Missing）:` 未满足的 gate
-- `下一步（Next）:` 进入 `$ws-finish` / `$ws-handoff`，或回退前置 gate
-
-阻断条件：
-- 缺少 spec review
-- 缺少 quality review
-- 缺少 validate stamp
-- review 中仍有未关闭 blocker
-- 无法写 verification 证据
-
-完成判定：
-- 已落盘 verify-before-complete 证据，并明确能否进入 `$ws-finish` / `$ws-handoff`。
-
-步骤（建议）：
-1) 识别当前 `change/<change-id>`。
-2) 检查以下最小 gate：
-   - `changes/<change-id>/review/spec-review.md`
-   - `changes/<change-id>/review/quality-review.md`
-   - `.agentdocs/tmp/aiws-validate/*.json`
-3) 若存在 `changes/<change-id>/evidence/`，检查是否已经收敛 review / validate / collaboration summary。
-4) 将结果落盘到：
-   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
-   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
-5) 输出：
-   - `证据（Evidence）:`
-   - `结论（Result）: pass|fail`
-   - `缺失项（Missing）:`
-   - `下一步（Next）:`
-
-重点：
-- 这个 gate 不替代 `$ws-finish`；它只判断“是否具备进入 finish / handoff 的前置条件”。
-- 若 fail，必须明确回退到哪个 gate：`$ws-spec-review`、`$ws-quality-review`、`aiws validate . --stamp` 或 `aiws change evidence <change-id>`。
-
-安全：
-- 不打印 secrets。
-- 不执行破坏性命令。
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws ws-verify-before-complete
+elif command -v aiws >/dev/null 2>&1; then
+  aiws ws-verify-before-complete
+else
+  npx @aipper/aiws ws-verify-before-complete
+fi
+```

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

@@ -0,0 +1,19 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-intake -->
+# ws intake
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在正式 `/ws-plan` 前，先把需求里的待确认问题逐条澄清并冻结。
+
+执行建议：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+2) 若存在最新 `plan/*.intake.md`，先续写；否则创建新的 intake 草案。
+3) 把问题写成 `Open Questions`，状态只允许 `open / in_discussion / frozen / deferred`。
+4) 每次只推进 1 条 `Current question`，允许围绕这 1 条问题多轮沟通。
+5) 当前问题未标记为 `frozen` 或 `deferred` 前，不进入下一题。
+6) 每轮都要把结论落到 `plan/<timestamp>-<slug>.intake.md`，并输出 `Ready for ws-plan: yes/no`。
+7) 只有关键问题已冻结时，`Next` 才能进入 `/ws-plan`；否则继续 `/ws-intake`。
+<!-- AIWS_MANAGED_END:claude:ws-intake -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -14,7 +14,11 @@
 3) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
-4) 回复中输出：
+4) 若当前任务已进入“准备提交/交付/finish”的语境，继续补齐 dual review gate：
+   - 运行/收敛 `/ws-spec-review`，落盘 `changes/<change-id>/review/spec-review.md`
+   - 运行/收敛 `/ws-quality-review`，落盘 `changes/<change-id>/review/quality-review.md`
+   - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
+5) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令