@aipper/aiws-spec 0.0.28 → 0.0.30

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

@@ -1,70 +1,18 @@
 ---
 name: ws-plan-verify
-description: 计划质检（执行前检查计划是否过长/跑偏，并给出最小修正清单）
+description: `aiws plan-verify` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-plan-verify
 
-目标：
-- 在进入 `$ws-dev` 前，对 `plan/...` 与 `changes/<change-id>/proposal.md` 做一次“硬约束”质检
-- 避免计划过长、步骤不够具体、验证不可复现、与需求合同绑定不一致
-- 显式做一次多视角方案审查，避免计划“格式合格但方向跑偏”
-- 失败时只给最小修正项，修完后再进入实现
+`aiws plan-verify` 的薄包装入口。
 
-适用时机：
-- 已执行过 `$ws-plan`，且准备开始编码
-- 或用户反馈“计划太长/容易跑偏”，需要先压缩并对齐
-
-阶段定位：
-- planning gate；负责在编码前检查计划是否满足 change 严格契约。
-
-必需输入：
-- 当前 `plan/...`
-- `changes/<change-id>/proposal.md`
-- 当前 change 上下文
-
-必需输出：
-- `Quality gate:` pass/fail
-- `Perspective findings:` 多视角审查结论
-- `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 plan-verify
 elif command -v aiws >/dev/null 2>&1; then
-  aiws change validate <change-id> --strict
+  aiws plan-verify
 else
-  npx @aipper/aiws change validate <change-id> --strict
+  npx @aipper/aiws plan-verify
 fi
 ```
-4) 若失败：按报错逐条修正 `proposal.md` / `plan/...`，优先级如下：
-   - 先修绑定：`Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
-   - 再修计划质量：必需章节、步骤数量、步骤具体性、验证命令与预期
-5) 在 strict 通过后，增加多视角方案审查（不要跳过）：
-   - 产品/范围：目标是否清楚、是否有 scope creep、是否把不该做的内容带进来
-   - 工程实现：数据流、边界条件、失败模式、回滚、验证是否闭合
-   - 体验 / DX（按需）：若任务涉及 UI、CLI、API、文档或工具链，检查关键路径是否可用、成本是否可接受
-   - 验收完整性：是否能凭当前 Verify 判断 done / not done
-6) 若多视角审查发现阻断问题：`Quality gate: fail`，只输出最小修正项，不进入实现。
-7) 复跑 strict 校验，直到通过。
-8) 输出“可执行最小计划摘要”（3-8 步），再进入 `$ws-dev`。
-
-输出要求：
-- `Quality gate:` pass/fail
-- `Perspective findings:` 按视角列出阻断点 / 警告 / 通过结论
-- `Fix list:` 仅保留必须修改项（按阻断级别排序）
-- `Next:` 通过后建议 `$ws-dev`；未通过则继续修正并复跑 strict

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

@@ -1,119 +1,18 @@
 ---
 name: ws-pull
-description: 拉取并对齐 submodules（避免 detached；减少人为差异）
+description: `aiws pull` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-pull
 
-背景：
-- Git submodule 在别的电脑 `git submodule update` 后常见现象是子模块处于 detached HEAD（因为主仓库记录的是固定 gitlink commit）。
-- detached 本身不一定是错，但会增加“需要手动切分支/容易忘”的操作差异。
+`aiws pull` 的薄包装入口。
 
-目标：
-- 安全拉取 superproject（默认只允许 fast-forward）
-- 初始化/同步 submodules（`--init --recursive`）
-- 在**不改动 superproject gitlink commit** 的前提下，尽量把每个 submodule 从 detached HEAD “挂回”到一个**确定的目标分支**（仅当该分支包含 gitlink commit 时）
-- 若未配置 `.gitmodules` 的 `submodule.<name>.branch`：保持 detached，并提示先运行 `$ws-submodule-setup`
-
-安全约束（强制）：
-- 不执行破坏性命令（不 `reset --hard` 主仓库；不改动远端）
-- 不自动提交/不自动 push
-- 若工作区不干净：停止并要求用户先 commit 或 stash（不要自动处理）
-
-执行步骤（建议）：
-0) 输出上下文：
 ```bash
-git rev-parse --show-toplevel
-git branch --show-current
-git status --porcelain
-```
-若 `git status --porcelain` 非空：停止，要求用户先清理工作区（commit 或 stash）。
-
-1) 拉取 superproject（默认只允许 fast-forward，避免隐式 merge/rebase）：
-```bash
-git pull --ff-only
-```
-若失败（需要 merge/rebase）：停止并向用户解释原因，让用户明确选择 `git pull --rebase` 或手动处理。
-
-2) 同步并更新 submodules 到 superproject 记录的 gitlink commit：
-```bash
-if [[ -f .gitmodules ]]; then
-  git submodule sync --recursive
-  git submodule update --init --recursive
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws pull
+elif command -v aiws >/dev/null 2>&1; then
+  aiws pull
 else
-  echo "[info] no .gitmodules"
+  npx @aipper/aiws pull
 fi
 ```
-
-3) （可选但推荐）把 submodule 从 detached HEAD 尽量“挂回分支”，减少手工操作差异：
-
-说明：
-- 该步骤不会改变 superproject 的 gitlink commit（也不会让主仓库出现“submodule modified”）。
-- 只在目标分支包含该 gitlink commit 时才执行“挂回”；否则保持 detached 并提示原因。
-- 为了避免 origin 分支较多时“猜错分支”，本步骤**只在** `.gitmodules` 明确配置了 `submodule.<name>.branch` 时才执行“挂回分支”；否则保持 detached 并提示先运行 `$ws-submodule-setup` 对齐配置。
-
-```bash
-if [[ -f .gitmodules ]]; then
-  base_branch="$(git branch --show-current)"
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-    | while read -r key sub_path; do
-      [[ -z "${sub_path:-}" ]] && continue
-      name="${key#submodule.}"
-      name="${name%.path}"
-      echo "== submodule: ${sub_path} (${name}) =="
-
-      sub_sha="$(git rev-parse "HEAD:${sub_path}" 2>/dev/null || true)"
-      if [[ -z "${sub_sha:-}" ]]; then
-        echo "[warn] failed to read gitlink sha for ${sub_path}"
-        continue
-      fi
-
-      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 (run ws-submodule-setup to set it)"
-        continue
-      fi
-
-      target_branch="${cfg_branch}"
-      pin_branch="aiws/pin/${target_branch}"
-
-      git -C "${sub_path}" fetch origin --prune || true
-
-      if git -C "${sub_path}" show-ref --verify --quiet "refs/remotes/origin/${target_branch}"; then
-        if git -C "${sub_path}" merge-base --is-ancestor "${sub_sha}" "origin/${target_branch}"; then
-          # 不改动现有分支（避免把已有 main/master 等分支强行指回旧 commit）
-          # 仅创建/更新一个 AIWS 专用 pin 分支指向 gitlink commit，从 detached “挂回分支”。
-          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
-          echo "[ok] attached ${sub_path} to ${pin_branch} (upstream=origin/${target_branch}) at ${sub_sha}"
-        else
-          echo "[warn] ${sub_path}: ${sub_sha} is not in origin/${target_branch}; keep detached"
-        fi
-      else
-        echo "[warn] ${sub_path}: origin/${target_branch} not found; keep detached"
-      fi
-
-      git -C "${sub_path}" rev-parse --abbrev-ref HEAD 2>/dev/null || true
-      git -C "${sub_path}" status -sb || true
-    done
-fi
-```
-
-4) 一次性配置（方案 2）：为每个 submodule 写入跟踪分支，便于团队统一（需要用户确认，会改动 `.gitmodules`）：
-```bash
-# 示例：把某个 submodule 固定跟踪 main（会写入 .gitmodules 的 submodule.<name>.branch）
-git submodule set-branch --branch main <sub_path>
-
-# 提示：该变更需要提交到 superproject
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branch"
-```
-建议：
-- 只有当团队明确希望“子模块按分支滚动”（而不是锁定固定 commit）时，才采用方案 2。
-- 若只是想避免 detached 但仍锁定 gitlink commit：优先使用步骤 3（不改 `.gitmodules`）。
-- 推荐用 `$ws-submodule-setup` 交互式对齐所有 submodules 的 branch，并提交 `.gitmodules`。
-
-输出要求：
-- `Context:` 当前分支 + 是否存在 `.gitmodules` + submodule 列表
-- `Result:` pull 是否 fast-forward；每个 submodule 是否成功“挂回分支”，失败原因是什么

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

@@ -1,110 +1,18 @@
 ---
 name: ws-push
-description: 推送（submodule 感知：先 submodules 后 superproject；fast-forward 安全）
+description: `aiws push` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-push
 
-目标：
-- 在不自动提交的前提下，安全 push 当前仓库
-- 若仓库包含 submodules：按 `submodules -> superproject` 顺序 push，减少“别人拉取后子模块 detached/分叉”的协作摩擦
-- 若不包含 submodules：按普通 git 仓库的规则 push
+`aiws push` 的薄包装入口。
 
-安全约束（强制）：
-- 不自动提交、不自动 `git add -A`
-- 不使用 `--force` / `--force-with-lease`
-- 默认只允许 fast-forward push（发现分叉则停止并提示人工处理）
-- 若工作区不干净：停止并要求先 commit 或 stash
-
-执行步骤（建议）：
-0) 输出上下文：
-```bash
-git branch --show-current
-git status --porcelain
-git status -sb
-```
-若 `git status --porcelain` 非空：停止。
-
-1) 判断是否存在 submodules：
 ```bash
-if [[ -f .gitmodules ]]; then
-  git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' || true
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws push
+elif command -v aiws >/dev/null 2>&1; then
+  aiws push
 else
-  echo "[info] no .gitmodules"
-fi
-```
-
-2) 若不存在 `.gitmodules` 或没有 submodule 条目：按普通仓库 push（仍需用户确认）：
-```bash
-git remote -v
-git push
-```
-
-3) 若存在 submodules：先检查 `.gitmodules` 的 branch 真值是否齐全（缺失则停止并提示 setup）：
-```bash
-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
+  npx @aipper/aiws push
 fi
 ```
-
-4) 逐个 push submodules（fast-forward only），再 push superproject：
-```bash
-base_branch="$(git branch --show-current)"
-change_id="$(echo "${base_branch}" | sed -n 's|^change/||p')"
-targets="changes/${change_id}/submodules.targets"
-# Note: if not on a change/ branch, change_id is empty and targets file won't exist;
-# resolution falls back to .gitmodules submodule.<name>.branch via ws_resolve_sub_target.
-
-source tools/ws_resolve_sub_target.sh
-
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null \
-  | while read -r key sub_path; do
-    name="${key#submodule.}"; name="${name%.path}"
-    echo "== submodule: ${sub_path} (${name}) =="
-
-    # submodule 工作区必须干净
-    if [[ -n "$(git -C "${sub_path}" status --porcelain 2>/dev/null || true)" ]]; then
-      echo "error: submodule dirty: ${sub_path}"
-      exit 2
-    fi
-
-    ws_resolve_sub_target "${sub_path}" "${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 ${sub_path}"
-      exit 2
-    fi
-
-    # fast-forward only: <remote>/<branch> 必须是 HEAD 的祖先
-    if ! git -C "${sub_path}" merge-base --is-ancestor "${remote}/${target_branch}" HEAD; then
-      echo "error: non-fast-forward (submodule=${sub_path}, remote=${remote}, branch=${target_branch})"
-      echo "hint: rebase/merge in submodule, then retry"
-      exit 2
-    fi
-
-    # push HEAD -> <remote>/<branch>（不 force）
-    git -C "${sub_path}" push "${remote}" "HEAD:refs/heads/${target_branch}"
-  done
-
-# 最后 push superproject（仍需用户确认远端/分支）
-git remote -v
-git push
-```
-
-输出要求：
-- `Context:` 当前分支 + 是否有 submodules
-- `Submodules:` 每个 submodule push 的目标分支与结果（成功/阻断原因）
-- `Superproject:` push 结果

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-submodule-setup/SKILL.md

@@ -1,65 +1,18 @@
 ---
 name: ws-submodule-setup
-description: 子模块分支对齐（写入 .gitmodules 的 submodule.<name>.branch；减少 detached 与人为差异）
+description: `aiws submodule-setup` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-submodule-setup
 
-目标：
-- 为每个 submodule 写入 `.gitmodules` 的 `submodule.<name>.branch`，让 `ws-pull` / `ws-finish` 能确定性地“挂回分支/fast-forward push”，避免 origin 多分支时靠猜导致偏差。
-- 该变更是 **superproject 的团队真值**：需要提交 `.gitmodules`。
+`aiws submodule-setup` 的薄包装入口。
 
-安全约束（强制）：
-- 不自动提交、不自动 push（必须先输出 diff 并让用户确认）
-- 不在 submodule 中做破坏性操作（不 `reset --hard` / 不改动远端）
-
-步骤（建议）：
-1) 确认工作区干净（否则停止）：
-```bash
-git status --porcelain
-```
-
-2) 列出 submodules（没有则停止并说明无需配置）：
-```bash
-test -f .gitmodules || { echo "no .gitmodules"; exit 0; }
-git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$'
-```
-
-3) 对每个 submodule，输出当前配置与建议分支（让用户确认每个 submodule 的 branch）：
-```bash
-while read -r key sub_path; do
-  name="${key#submodule.}"; name="${name%.path}"
-  echo "== submodule: ${name} path=${sub_path} =="
-  echo "[current] branch=$(git config --file .gitmodules --get submodule.${name}.branch || true)"
-  echo "[origin]  HEAD=$(git -C \"${sub_path}\" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true)"
-  git -C "${sub_path}" branch -r --list "origin/*" | sed -n '1,30p' || true
-  echo "[choose] set one of:"
-  echo "  - a concrete branch, e.g. main / master / release/x.y"
-  echo "  - '.' to follow superproject current branch name (only if your team uses matching branch names)"
-done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$')
-```
-
-4) 逐个写入分支配置（每次写完都回显，避免误配）：
 ```bash
-# Example:
-# git submodule set-branch --branch main path/to/submodule
-# git submodule set-branch --branch .    path/to/submodule
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws submodule-setup
+elif command -v aiws >/dev/null 2>&1; then
+  aiws submodule-setup
+else
+  npx @aipper/aiws submodule-setup
+fi
 ```
-
-5) 输出变更并让用户确认是否提交：
-```bash
-git diff -- .gitmodules
-git status --porcelain
-```
-
-6) 若用户确认要提交：
-```bash
-git add .gitmodules
-git commit -m "chore(submodule): set tracking branches"
-```
-
-输出要求：
-- `Submodules:` name/path + 选择的 branch（每个都列出）
-- `Diff:` `.gitmodules` 的 diff（或至少 `git diff -- .gitmodules` 的摘要）
-- `Next:` 提示后续用 `$ws-pull` 拉取可自动减少 detached；`aiws validate` 会检查该配置是否齐全
-

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 verify-bc` 的薄包装入口
 ---
 
-用中文输出（命令/路径/代码标识符保持原样不翻译）。
+# ws-verify-before-complete
 
-目标：
-- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
-- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+`aiws verify-bc` 的薄包装入口。
 
-阶段定位：
-- 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 verify-bc
+elif command -v aiws >/dev/null 2>&1; then
+  aiws verify-bc
+else
+  npx @aipper/aiws verify-bc
+fi
+```

package/templates/workspace/{changes → .aiws/changes}/README.md

@@ -9,7 +9,7 @@
 
 建议结构：
 ```
-changes/
+.aiws/changes/
   README.md
   <change-id>/
     proposal.md
@@ -32,15 +32,12 @@ changes/
 - `aiws change new <change-id>` 会预创建以上目录，减少临时约定漂移。
 
 常用命令（推荐使用 `aiws`；不依赖 dotfiles）：
-- `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录；若检测到 `.gitmodules` 则默认优先使用 worktree，失败则回退为不切分支，避免 submodule 状态混乱）
+- `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录）
 - `aiws change start <change-id> --no-switch`（superproject + submodule 场景：不切分支，仅准备 `change/<change-id>` 分支与工件目录）
-- `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅切 superproject，不递归切换 submodule；仅在存在 `.gitmodules` 时有意义）
-- `aiws change start <change-id> --worktree`（推荐用于 superproject + submodule：创建独立 worktree；当前目录分支保持不变）
-  - 可选：`--worktree-dir <path>` 覆盖 worktree 目录
-  - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`
+- `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅切 superproject，不递归切换 submodule）
 - `aiws change finish <change-id>`（安全合并：fast-forward 合并回目标分支；在 `change/<change-id>` 分支上执行时会尝试使用 `.ws-change.json` 的 `base_branch` 作为目标分支）
-- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；若 `change/<change-id>` 位于独立 worktree，且该 worktree 干净，则在 push 成功后自动执行 worktree cleanup，并把 `changes/<id>/` 自动归档到 `changes/archive/...`，同时生成 `handoff.md` 与 archive commit）
-- 已 archive 的 `change/<change-id>` 才算真正终态；若只是“已 finish 但仍有 active `changes/<id>/` 未归档”，默认应重跑 `aiws change finish <change-id> --push` 续完收尾，而不是继续开发或复用旧 branch 做新需求。
+- `aiws change finish <change-id> --push [--remote <name>]`（最小收尾闭环：若存在 `.gitmodules` 则先按 `.aiws/changes/<id>/submodules.targets` 顺序 push submodule，再 push 目标分支；默认优先遵循 upstream 配置；push 成功后把 `.aiws/changes/<id>/` 自动归档到 `.aiws/changes/archive/...`，同时生成 `handoff.md` 与 archive commit）
+- 已 archive 的 `change/<change-id>` 才算真正终态；若只是"已 finish 但仍有 active `.aiws/changes/<id>/` 未归档"，默认应重跑 `aiws change finish <change-id> --push` 续完收尾，而不是继续开发或复用旧 branch 做新需求。
 - `aiws change new <change-id>`
 - `aiws change list`
 - `aiws change status <change-id>`
@@ -48,24 +45,24 @@ changes/
 - `aiws change validate <change-id>`
 - `aiws change sync <change-id>`
 - `aiws change archive <change-id>`（手工恢复 / 历史兼容入口；标准链路一般不需要单独执行）
-- `aiws change evidence <change-id>`（收敛 review / validate / collaboration summary 到 `changes/<id>/evidence/`）
+- `aiws change evidence <change-id>`（收敛 review / validate / collaboration summary 到 `.aiws/changes/<id>/evidence/`）
 
 Active change（推荐，团队共享）：
 - 使用分支名声明当前变更：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
 - 切到该分支后，可省略 `<change-id>` 执行：`aiws change status|next|validate|sync`
 
 计划质量门（推荐，执行前）：
-- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支 / worktree，再在该上下文内写 `plan/...`）
+- 先生成计划：`$ws-plan`（若尚未进入 `change/<change-id>` 上下文，应先由它调用 `aiws change start <change-id>` 建立分支，再在该上下文内写 `.aiws/plan/...`）
 - 再执行计划质检：`$ws-plan-verify`
 - 最后进入实现：`$ws-dev`
-- 若 `$ws-plan` 创建了独立 worktree，后续 `$ws-plan-verify` / `$ws-dev` / `$ws-finish` 都应优先在该 worktree 内继续
+- 若 `$ws-plan` 创建了独立 `change/<change-id>` 分支，后续 `$ws-plan-verify` / `$ws-dev` / `$ws-finish` 都应优先在该分支内继续
 - 目标：确保计划具备主索引绑定、步骤不过长、验证命令可复现且有预期结果
 
 模板覆盖（可选）：
-- 在工作区创建 `changes/templates/` 可覆盖默认模板：
-  - `changes/templates/proposal.md`
-  - `changes/templates/tasks.md`
-  - `changes/templates/design.md`
+- 在工作区创建 `.aiws/changes/templates/` 可覆盖默认模板：
+  - `.aiws/changes/templates/proposal.md`
+  - `.aiws/changes/templates/tasks.md`
+  - `.aiws/changes/templates/design.md`
 - 快速初始化模板：`aiws change templates init`
 - 查看模板来源：`aiws change templates which`
 
@@ -80,7 +77,7 @@ Hooks/CI（推荐，硬约束）：
     - submodule / 普通仓库：默认 `warn`，提示优先使用中文 commit message
     - 若执行 `git config aiws.commitMessagePolicy strict`，则会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
   - `pre-commit` / `pre-push`：默认执行 `aiws validate .`
-- 还会安装门禁脚本（`tools/ws_change_check.py`、`tools/requirements_contract.py`）。
+- 还会安装门禁脚本（`.aiws/tools/ws_change_check.py`、`.aiws/tools/requirements_contract.py`）。
 - **启用 hooks 需要本地配置**（不会自动提交到 git）：
   - 直接启用：`git config core.hooksPath .githooks`
   - 或使用：`aiws hooks install .`（等价）
@@ -88,13 +85,13 @@ Hooks/CI（推荐，硬约束）：
 - 紧急跳过（不推荐）：`WS_CHANGE_HOOK_BYPASS=1 ...`（CI 不应允许跳过）。
 
 合并建议（减少人为 merge 引入新问题）：
-- 优先使用 worktree + fast-forward 合并：
-  - 完成后在主工作区（例如 `main`）执行：`aiws change finish <change-id>`（等价于 `git merge --ff-only change/<change-id>`）
-  - 若还要顺手 push 并清理独立 change worktree：`aiws change finish <change-id> --push`
-  - 若失败：先在 worktree 里 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`
+- 优先使用 fast-forward 合并：
+  - 完成后在目标分支（例如 `main`）执行：`aiws change finish <change-id>`（等价于 `git merge --ff-only change/<change-id>`）
+  - 若还要顺手 push：`aiws change finish <change-id> --push`
+  - 若失败：先在 change 分支 `git rebase main`（或更新 main 后再 rebase），再重试 `--ff-only`
 
 协同交付建议：
-- 委托分析先落到 `changes/<id>/analysis/`，由主 agent 在 `ws-review` 或 `review/*.md` 中收敛结论。
-- patch 草案先落到 `changes/<id>/patches/`，未经审查不要直接应用。
-- 交付前建议执行：`aiws change evidence <change-id>`，让 `delivery-summary` 与 `collaboration-summary` 一起落到 `changes/<id>/evidence/`。
+- 委托分析先落到 `.aiws/changes/<id>/analysis/`，由主 agent 在 `ws-review` 或 `review/*.md` 中收敛结论。
+- patch 草案先落到 `.aiws/changes/<id>/patches/`，未经审查不要直接应用。
+- 交付前建议执行：`aiws change evidence <change-id>`，让 `delivery-summary` 与 `collaboration-summary` 一起落到 `.aiws/changes/<id>/evidence/`。
 - finish 自动归档后生成的 `handoff.md` 会包含协同工件摘要，便于下一次会话继续接力。

package/templates/workspace/{changes → .aiws/changes}/templates/proposal.md

@@ -18,8 +18,8 @@
 - 需求交付：`Req_ID` = <!-- WS:TODO （需求交付可填；例如 TOOLING-001B） -->
 - 问题修复：`Problem_ID` = <!-- WS:TODO （问题修复可填；例如 PROB-001） -->
 - `Contract_Row` = <!-- WS:TODO 绑定执行合同中的行 ID，可多项（逗号分隔）；例如 Req_ID=TOOLING-001B -->
-- `Plan_File` = <!-- WS:TODO 例如 plan/2026-02-08_15-30-00-xxx.md -->
-- `Evidence_Path` = <!-- WS:TODO 证据路径，可多项（逗号分隔）；优先写持久证据 changes/<change-id>/evidence/...；也可附带 changes/<change-id>/review/... 或 .agentdocs/tmp/... -->
+- `Plan_File` = <!-- WS:TODO 例如 .aiws/plan/2026-02-08_15-30-00-xxx.md -->
+- `Evidence_Path` = <!-- WS:TODO 证据路径，可多项（逗号分隔）；优先写持久证据 .aiws/changes/<change-id>/evidence/...；也可附带 .aiws/changes/<change-id>/review/... 或 .aiws/tmp/... -->
 
 ## 依赖关系（可选）
 
@@ -33,7 +33,7 @@
 
 > 规则：
 > - `Req_ID` 与 `Problem_ID` 至少填写一项。
-> - `Contract_Row` 必须引用 `requirements/requirements-issues.csv` 或 `issues/problem-issues.csv` 中的真实行。
+> - `Contract_Row` 必须引用 `.aiws/requirements/requirements-issues.csv` 或 `.aiws/issues/problem-issues.csv` 中的真实行。
 > - `Plan_File` 对应的计划文件必须存在，且其绑定字段与本文件一致。
 > - `Evidence_Path` 可先声明计划路径，交付前需完成证据落盘。
 
@@ -48,9 +48,9 @@
 ## 协同与委托（可选）
 
 - `analysis/`：
-  - <!-- WS:TODO 如需委托分析，写明预计产物；例如 `changes/<change-id>/analysis/research-a.md` -->
+  - <!-- WS:TODO 如需委托分析，写明预计产物；例如 `.aiws/changes/<change-id>/analysis/research-a.md` -->
 - `patches/`：
-  - <!-- WS:TODO 如需外部 patch 草案，写明预计文件；例如 `changes/<change-id>/patches/fix-a.patch` -->
+  - <!-- WS:TODO 如需外部 patch 草案，写明预计文件；例如 `.aiws/changes/<change-id>/patches/fix-a.patch` -->
 - `review/`：
   - <!-- WS:TODO 如需多审查者，写明 reviewer 文件命名或汇总策略 -->
 
@@ -96,17 +96,17 @@
 > 从 `AI_WORKSPACE.md` 选择最贴近本变更的验证入口，写成可直接复制执行的命令。
 
 - 命令：
-  - <!-- WS:TODO 例如：`uv run tools/server_test_runner.py --workspace .` -->
+  - <!-- WS:TODO 例如：`uv run .aiws/tools/server_test_runner.py --workspace .` -->
 - 期望结果：
   - <!-- WS:TODO 例如：所有相关用例 DONE；无新增错误日志 -->
 
 ## 真值文件/合同更新清单
 
 - `REQUIREMENTS.md`：<!-- WS:TODO 需要/不需要；如需要，写明新增/修改的验收条款 -->
-- `requirements/CHANGELOG.md`：<!-- WS:TODO 需要/不需要 -->
-- `requirements/requirements-issues.csv`：<!-- WS:TODO 需要/不需要 -->
-- `issues/problem-issues.csv`：<!-- WS:TODO 需要/不需要 -->
+- `.aiws/requirements/CHANGELOG.md`：<!-- WS:TODO 需要/不需要 -->
+- `.aiws/requirements/requirements-issues.csv`：<!-- WS:TODO 需要/不需要 -->
+- `.aiws/issues/problem-issues.csv`：<!-- WS:TODO 需要/不需要 -->
 - 证据落盘（推荐双层）：
-  - 持久（建议入库）：`changes/<change-id>/evidence/...`（例如 validate 总结、review 总结、关键日志摘要）
-  - 临时（可忽略入库）：`.agentdocs/tmp/...`（例如 `aiws validate . --stamp` 的 JSON）
-  - 协同（按需）：`changes/<change-id>/analysis/...`、`patches/...`、`review/...`
+  - 持久（建议入库）：`.aiws/changes/<change-id>/evidence/...`（例如 validate 总结、review 总结、关键日志摘要）
+  - 临时（可忽略入库）：`.aiws/tmp/...`（例如 `aiws validate . --stamp` 的 JSON）
+  - 协同（按需）：`.aiws/changes/<change-id>/analysis/...`、`.aiws/changes/<change-id>/patches/...`、`.aiws/changes/<change-id>/review/...`