@aipper/aiws-spec 0.0.20 → 0.0.21

package/docs/cli-interface.md

@@ -274,9 +274,31 @@
 - 调用 `python3 tools/ws_change_check.py` 校验单个 change 工件目录。
 - `--strict`：强门禁（例如 WS:TODO、占位符、缺归因、truth drift 等都失败）。
 - `--allow-truth-drift`：仅用于紧急场景跳过 truth drift gating（仍会输出 warnings；不建议常用）。
+- `--check-evidence`：证据存在性门禁（可选）：校验 `Evidence_Path` 声明的路径必须是工作区相对路径且文件存在；并要求至少包含 1 条持久证据路径（`changes/<id>/evidence/...` 或 `changes/<id>/review/...`）。
+- `--check-scope`：scope 门禁（可选，best-effort）：要求 proposal/plan 中包含 “In Scope” 与 “Out of Scope” 标记（用于减少 scope creep）。
 
 接口（仅定义）：
-- `aiws change validate [<change-id>] [--strict] [--allow-truth-drift]`
+- `aiws change validate [<change-id>] [--strict] [--allow-truth-drift] [--check-evidence] [--check-scope]`
+
+说明：
+- `--check-evidence/--check-scope` 默认不启用，避免对历史 change 造成行为破坏；交付阶段建议启用 `--check-evidence`。
+
+### `aiws change evidence`
+
+语义：
+- 为交付阶段生成“可入库的持久证据”，并自动回填 `Evidence_Path`：
+  - 写入 `changes/<change-id>/evidence/`（例如：严格门禁结果快照、状态快照、validate stamp 复制等）
+  - 将生成的证据路径追加回填到：
+    - `changes/<change-id>/proposal.md` 的 `Evidence_Path`
+    - `Plan_File` 指向的计划文件中的 `Evidence_Path`（若存在）
+  - 若存在 `.agentdocs/tmp/review/codex-review.md` 且 `changes/<id>/review/codex-review.md` 不存在：复制为持久 review 证据。
+
+接口（仅定义）：
+- `aiws change evidence [<change-id>] [--no-validate] [--allow-fail]`
+
+选项：
+- `--no-validate`：不执行严格门禁校验；仅生成/回填证据（适用于早期阶段先固化证据结构）。
+- `--allow-fail`：即使严格门禁失败也继续生成证据并回填（默认会失败退出，避免“带病交付”）。
 
 ### `aiws change archive`
 
@@ -301,6 +323,7 @@
 - `aiws change list`
 - `aiws change status [<change-id>]`
 - `aiws change next [<change-id>]`
+- `aiws change state [<change-id>] [--write]`（状态快照；`--write` 写入 `changes/<id>/STATE.md`）
 
 ### `aiws change templates which/init`
 
@@ -310,3 +333,11 @@
 接口（仅定义）：
 - `aiws change templates which`
 - `aiws change templates init`
+
+## `aiws metrics`
+
+语义：
+- 读取 `changes/*/metrics.json` 与 `changes/archive/*/metrics.json`，输出 best-effort 流程指标汇总（不修改任何文件）。
+
+接口（仅定义）：
+- `aiws metrics summary [--since YYYY-MM-DD]`

package/package.json

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

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

@@ -55,7 +55,16 @@ while read -r _ sub_path; do
 done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true)
 ```
 判定规则（强制）：
-- 任一 submodule `git status --porcelain` 非空：停止 superproject commit，先在对应 submodule 完成 commit（必要时先切回可提交分支），再回到 superproject 更新并提交 gitlink。
+- 任一 submodule `git status --porcelain` 非空：停止 superproject commit，先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+- 若该 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
+```
 7) 检查当前 staging 内容（必须输出给用户确认）：
 ```bash
 git status --porcelain

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

@@ -64,11 +64,22 @@ git -C "$sub_path" status --porcelain
 ```
 2) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
    - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
-   - 若你要在该 submodule 里提交：在 submodule 内创建并切到同名 change 分支（与 superproject 对齐），例如 `change/<change-id>`：
+   - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
+   - 若你要在该 submodule 里提交：先按 `.gitmodules` 的目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
 ```bash
-git -C "$sub_path" switch -c "change/<change-id>"
+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
+if [[ -z "${cfg_branch:-}" ]]; then
+  echo "error: missing .gitmodules submodule.${sub_name}.branch (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
 ```
-   - 若用户明确不想建分支：停止，解释风险（提交可能不可追溯/难以推送）。
+   - 若 `origin/<target-branch>` 不存在，或用户明确不想使用 pin 分支：停止，解释风险（提交可能不可追溯/难以推送）。
 3) 选择性 staging（默认用 `-p` 更安全）：
 ```bash
 git -C "$sub_path" add -p
@@ -115,8 +126,26 @@ else
 fi
 ```
 
+## D2) 生成持久证据并回填 Evidence_Path（强烈建议）
+> 说明：`.agentdocs/tmp/...` 默认 gitignored；交付前建议把关键结果落到 `changes/<change-id>/evidence/...` 并回填 `proposal.md`/`plan` 的 `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
+```
+
+## D3) 生成状态快照（可选，建议）
+```bash
+aiws change state "${change_id}" --write
+```
+
 ## E) 安全合并回目标分支（fast-forward）
-优先使用 `$ws-finish`（底层调用 `aiws change finish`）。
+优先使用 `$ws-finish`（底层调用 `aiws change finish`，并在 push 成功后清理对应 change worktree）。
 
 若需要显式指定目标分支：
 ```bash
@@ -132,4 +161,5 @@ aiws change archive <change-id>
 - `Submodules:` 每个 submodule 的分支/提交摘要（repo → commit sha → message）
 - `Superproject:` 提交摘要
 - `Merge:` `aiws change finish` 的输出（into/from）
+- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
 - `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）

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

@@ -14,6 +14,7 @@ description: 开发（按需求实现并验证；适用于任何需要修改代
 2) 建立变更归因（推荐）：
    - 推荐一键：`aiws change start <change-id> --hooks`（切分支 + 初始化变更工件 + 启用 hooks）
    - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`（创建独立 worktree；当前目录分支保持不变）
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
    - 若你明确要在 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

@@ -46,6 +46,21 @@ else
   npx @aipper/aiws validate . --stamp
 fi
 ```
+1.1) （强烈建议）收敛持久证据并回填 `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) （可选）生成状态快照（建议）：
+```bash
+aiws change state "${change_id}" --write
+```
 2) 安全合并（默认 fast-forward；并会在需要时切到目标分支）：
 ```bash
 # 若当前就在 change/<change-id> 分支上，可省略 <change-id>
@@ -71,6 +86,7 @@ git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null |
 # 说明：`git submodule update` 会把 submodule checkout 到固定 gitlink commit，导致 detached HEAD。
 # 为减少“游离状态”的协作摩擦，本步骤采用“pin 分支”策略：
 # - 仅在 `.gitmodules` 明确配置了 `submodule.<name>.branch` 时执行（避免 origin 多分支导致误判）
+# - 不要直接切 `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>")"
@@ -112,7 +128,31 @@ git branch --show-current
 git status -sb
 git push
 ```
-6) （可选）归档变更工件（完成交付后推荐）：
+6) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
+```bash
+change_id="<change-id>"
+change_ref="refs/heads/change/${change_id}"
+main_wt="$(git rev-parse --show-toplevel)"
+change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '
+  $1=="worktree" { wt=substr($0,10) }
+  $1=="branch" && $2==ref { print wt; exit }
+')"
+
+if [[ -n "${change_wt:-}" && "$change_wt" != "$main_wt" ]]; then
+  if [[ -n "$(git -C "$change_wt" status --porcelain 2>/dev/null)" ]]; then
+    echo "[warn] worktree not clean, skip remove: $change_wt"
+    echo "hint: clean it first, then run: git worktree remove \"$change_wt\""
+  else
+    git worktree remove "$change_wt"
+    git worktree prune
+  fi
+fi
+```
+规则：
+- 清理前先把 `change_wt` 输出给用户确认，避免误删。
+- 仅使用 `git worktree remove`（不带 `--force`）。
+
+7) （可选）归档变更工件（完成交付后推荐）：
 ```bash
 change_id="<change-id>"
 if [[ -x "./node_modules/.bin/aiws" ]]; then

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

@@ -43,7 +43,8 @@ while read -r _ sub_path; do
 done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
 ```
 判定规则（强制）：
-- 任一 submodule `git status --porcelain` 非空：停止提交 superproject；先在对应 submodule 完成 commit（必要时先切回可提交分支），再回到 superproject 更新并提交 gitlink。
+- 任一 submodule `git status --porcelain` 非空：停止提交 superproject；先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`。
 6) 检查 staging（必须输出给用户确认）：
 ```bash
 git status --porcelain

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

@@ -20,6 +20,7 @@
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
    - `git -C "<sub_path>" status --porcelain`
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`
    - `git -C "<sub_path>" add -p`
    - `git -C "<sub_path>" diff --staged --stat`
    - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）
@@ -32,13 +33,18 @@
    - `git commit -m "<message>"`
 5) （推荐）门禁 + 证据：
    - `aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）
+5.1) （强烈建议）生成持久证据并回填 `Evidence_Path`：
+   - `aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）
+5.2) （可选）生成状态快照（建议）：
+   - `aiws change state <change-id> --write`
 6) 安全合并回目标分支：
-   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`）
+   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
 
 输出要求：
 - `子模块（Submodules）:` 每个 submodule 的 commit 摘要（repo/path → sha → message）
 - `主仓库（Superproject）:` commit 摘要
 - `合并信息（Merge）:` `/ws-finish` 输出（into/from）
+- `工作区清理（Worktree cleanup）:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
 - `证据（Evidence）:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
 <!-- AIWS_MANAGED_END:claude:ws-deliver -->
 

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

@@ -8,8 +8,10 @@
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
 2) 建立变更归因（推荐）：
-   - 切分支：`git switch -c change/<change-id>`
-   - 初始化变更工件：创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+   - 推荐一键：`aiws change start <change-id> --hooks`
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 或手工：`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`（问题）。
 5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。

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

@@ -32,6 +32,8 @@ fi
 ```
 1) 先运行 `/ws-preflight`（确保真值文件齐全）。
 2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+2.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
+2.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
 3) 安全合并并切回目标分支：
    - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
    - 否则执行：`aiws change finish <change-id>`
@@ -41,6 +43,7 @@ fi
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
      - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”
      - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
      - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
      - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
@@ -49,7 +52,13 @@ fi
    - `git branch --show-current`
    - `git status -sb`
    - `git push`
-8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+8) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
+   - `change_ref="refs/heads/change/<change-id>"`
+   - `main_wt="$(git rev-parse --show-toplevel)"`
+   - `change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '$1=="worktree"{wt=substr($0,10)} $1=="branch"&&$2==ref{print wt; exit}')"`
+   - 若 `change_wt` 非空且不等于 `main_wt`：先输出并让用户确认，再执行 `git worktree remove "$change_wt"`（不带 `--force`），最后 `git worktree prune`
+   - 若 `git -C "$change_wt" status --porcelain` 非空：停止并提示先清理该 worktree
+9) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 安全：
 - push 前先输出状态并请用户确认远端/分支。

package/templates/workspace/.codex/prompts/ws-dev.md

@@ -13,12 +13,15 @@ argument-hint: ""
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
 2) 建立变更归因（推荐）：
-   - 切分支：`git switch -c change/<change-id>`
-   - 初始化变更工件：创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+   - 推荐一键：`aiws change start <change-id> --hooks`
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 或手工：`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`（问题）。
 5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
 6) 提交前强制：`aiws validate .`（commit/push hooks 也会阻断）。
+7) 交付收尾（推荐，减少手动 merge 出错）：运行 `/ws-finish`（底层调用 `aiws change finish`，默认 fast-forward 安全合并回目标分支）。
 
 输出要求：
 - `变更文件（Changed）:` 文件清单

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

@@ -30,7 +30,8 @@ prompt = """
    - 对每个 `<sub_path>` 输出：
      - `git -C "<sub_path>" rev-parse --abbrev-ref HEAD`
      - `git -C "<sub_path>" status --porcelain`
-   - 判定规则：任一 submodule `git status --porcelain` 非空 → **停止提交 superproject**，先在该 submodule 完成 commit（必要时切回可提交分支），再回到 superproject 更新并提交 gitlink。
+   - 判定规则：任一 submodule `git status --porcelain` 非空 → **停止提交 superproject**，先在该 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+   - 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`。
 7) 检查 staging（必须输出给用户确认）：
    - `git status --porcelain`
    - `git diff --staged --submodule=short`

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

@@ -25,6 +25,7 @@ prompt = """
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
    - `git -C "<sub_path>" status --porcelain`
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`
    - `git -C "<sub_path>" add -p`
    - `git -C "<sub_path>" diff --staged --stat`
    - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）
@@ -37,12 +38,17 @@ prompt = """
    - `git commit -m "<message>"`
 5) （推荐）门禁 + 证据：
    - `aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）
+5.1) （强烈建议）生成持久证据并回填 `Evidence_Path`：
+   - `aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）
+5.2) （可选）生成状态快照（建议）：
+   - `aiws change state <change-id> --write`
 6) 安全合并回目标分支：
-   - 优先运行 `ws:finish`（底层调用 `aiws change finish`，默认 `--ff-only`）
+   - 优先运行 `ws:finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
 
 输出要求：
 - `Submodules:` 每个 submodule 的 commit 摘要（repo/path → sha → message）
 - `Superproject:` commit 摘要
 - `Merge:` `ws:finish`/`aiws change finish` 输出（into/from）
+- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
 - `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
 """

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

@@ -20,6 +20,8 @@ prompt = """
 4) 若工作区不干净：停止，并要求先 commit 或 stash（不要尝试自动处理）。
 4.1) 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `ws:submodule-setup` 并提交 `.gitmodules`）。
 5) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+5.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
+5.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
 6) 安全合并（默认 fast-forward）：
    - 在 `change/<change-id>` 分支上：`aiws change finish`（会尝试读 `changes/<change-id>/.ws-change.json` 的 `base_branch` 并切回目标分支）
    - 否则：`aiws change finish <change-id>`
@@ -29,6 +31,7 @@ prompt = """
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
      - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”
      - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
      - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
      - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
@@ -37,7 +40,13 @@ prompt = """
    - `git branch --show-current`
    - `git status -sb`
    - `git push`
-11) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+11) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
+   - `change_ref="refs/heads/change/<change-id>"`
+   - `main_wt="$(git rev-parse --show-toplevel)"`
+   - `change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '$1=="worktree"{wt=substr($0,10)} $1=="branch"&&$2==ref{print wt; exit}')"`
+   - 若 `change_wt` 非空且不等于 `main_wt`：先输出并让用户确认，再执行 `git worktree remove "$change_wt"`（不带 `--force`），最后 `git worktree prune`
+   - 若 `git -C "$change_wt" status --porcelain` 非空：停止并提示先清理该 worktree
+12) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 边界：
 - push 前先输出状态并请用户确认远端/分支。

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

@@ -46,7 +46,8 @@ while read -r _ sub_path; do
 done < <(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null || true)
 ```
 判定规则（强制）：
-- 任一 submodule `git status --porcelain` 非空：停止提交 superproject；先在对应 submodule 完成 commit（必要时先切回可提交分支），再回到 superproject 更新并提交 gitlink。
+- 任一 submodule `git status --porcelain` 非空：停止提交 superproject；先在对应 submodule 完成 commit，再回到 superproject 更新并提交 gitlink。
+- 若该 submodule 当前为 detached HEAD：先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`。
 6) 检查 staging（必须输出给用户确认）：
 ```bash
 git status --porcelain

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

@@ -23,6 +23,7 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
    - `git submodule status --recursive`
 3) 逐个提交 submodules（按上一步顺序）：
    - `git -C "<sub_path>" status --porcelain`
+   - 若当前为 detached HEAD：不要直接切 `change/<change-id>` / `main` / `master`；先按 `.gitmodules` 的目标分支挂到 `aiws/pin/<target-branch>`
    - `git -C "<sub_path>" add -p`
    - `git -C "<sub_path>" diff --staged --stat`
    - 生成并让用户确认该 submodule 的 commit message（每个 repo 单独确认）
@@ -35,13 +36,18 @@ description: 交付：submodules+superproject 分步提交并安全合并回 bas
    - `git commit -m "<message>"`
 5) （推荐）门禁 + 证据：
    - `aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）
+5.1) （强烈建议）生成持久证据并回填 `Evidence_Path`：
+   - `aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）
+5.2) （可选）生成状态快照（建议）：
+   - `aiws change state <change-id> --write`
 6) 安全合并回目标分支：
-   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`）
+   - 优先运行 `/ws-finish`（底层调用 `aiws change finish`，默认 `--ff-only`；push 成功后会清理对应 change worktree）
 
 输出要求：
 - `Submodules:` 每个 submodule 的 commit 摘要（repo/path → sha → message）
 - `Superproject:` commit 摘要
 - `Merge:` `/ws-finish` 输出（into/from）
+- `Worktree cleanup:` 若存在独立 change worktree，输出清理结果（removed/skipped + reason）
 - `Evidence:` `.agentdocs/tmp/aiws-validate/*.json`（若使用 --stamp）
 <!-- AIWS_MANAGED_END:opencode:ws-deliver -->
 

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

@@ -11,8 +11,10 @@ description: 开发：在 AIWS 约束下完成小步交付
 建议流程：
 1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
 2) 建立变更归因（推荐）：
-   - 切分支：`git switch -c change/<change-id>`
-   - 初始化变更工件：创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+   - 推荐一键：`aiws change start <change-id> --hooks`
+   - superproject + submodule（推荐）：`aiws change start <change-id> --hooks --worktree --submodules`
+   - 若后续需要在 detached submodule 内提交：先挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master`
+   - 或手工：`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`（问题）。
 5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。

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

@@ -35,6 +35,8 @@ fi
 ```
 1) 先运行 `/ws-preflight`（确保真值文件齐全）。
 2) （推荐）门禁校验并落盘证据：`aiws validate . --stamp`（未安装全局 aiws 时可用 `npx @aipper/aiws validate . --stamp`）。
+2.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：`aiws change evidence <change-id>`（未安装全局 aiws 时可用 `npx @aipper/aiws change evidence <change-id>`）。
+2.2) （可选）生成状态快照（建议）：`aiws change state <change-id> --write`。
 3) 安全合并并切回目标分支：
    - 若当前就在 `change/<change-id>` 分支上，可直接执行：`aiws change finish`
    - 否则执行：`aiws change finish <change-id>`
@@ -44,6 +46,7 @@ fi
    - 对每个 `<sub_path>`：
      - 读取 superproject 当前 gitlink：`git rev-parse "HEAD:<sub_path>"`
      - 目标分支：必须在 `.gitmodules` 配置 `submodule.<name>.branch`（若为 `.` 则用当前主仓库分支；避免 origin 多分支时误判）
+     - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”
      - 用 pin 分支挂回（不改动现有 main/master 指针）：`git -C "<sub_path>" checkout -B "aiws/pin/<target-branch>" <gitlink-sha>`
      - 仅当 `<gitlink-sha>` 属于 `origin/<target-branch>` 历史时才允许 push；否则停止并人工处理分叉
      - push（只允许 fast-forward）：`git -C "<sub_path>" push origin "<gitlink-sha>:refs/heads/<target-branch>"`
@@ -52,7 +55,13 @@ fi
    - `git branch --show-current`
    - `git status -sb`
    - `git push`
-8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+8) push 成功后，清理 `change/<change-id>` 对应 worktree（若存在且不是当前 worktree）：
+   - `change_ref="refs/heads/change/<change-id>"`
+   - `main_wt="$(git rev-parse --show-toplevel)"`
+   - `change_wt="$(git worktree list --porcelain | awk -v ref="$change_ref" '$1=="worktree"{wt=substr($0,10)} $1=="branch"&&$2==ref{print wt; exit}')"`
+   - 若 `change_wt` 非空且不等于 `main_wt`：先输出并让用户确认，再执行 `git worktree remove "$change_wt"`（不带 `--force`），最后 `git worktree prune`
+   - 若 `git -C "$change_wt" status --porcelain` 非空：停止并提示先清理该 worktree
+9) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
 
 安全：
 - push 前先输出状态并请用户确认远端/分支。

package/templates/workspace/AI_PROJECT.md

@@ -38,6 +38,8 @@
 推荐（防规则/范围漂移）：
 - 创建工件：补齐 `changes/<change-id>/proposal.md`、`tasks.md`（可选 `design.md`）
 - 声明 active change（团队共享）：切到分支 `change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
+- 若仓库存在 `.gitmodules`：优先使用 `aiws change start <change-id> --worktree`（或至少 `--no-switch`）；不要在当前 superproject worktree 里直接手工切分支。
+- 若 submodule 因 gitlink checkout 处于 detached HEAD：只允许挂到 `aiws/pin/<target-branch>`；不要直接切 `change/<change-id>` / `main` / `master` 等业务分支来“解 detached”。
 - 严格校验：`aiws validate .`（包含：漂移检测 + `ws_change_check` + `requirements_contract`）
 - 启用 hooks（本地生效）：`git config core.hooksPath .githooks`（提交/推送时自动跑 `aiws validate .`）
 - CI 建议追加：`aiws validate .`

package/templates/workspace/changes/templates/proposal.md

@@ -19,7 +19,17 @@
 - 问题修复：`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>/review/codex-review.md -->
+- `Evidence_Path` = <!-- WS:TODO 证据路径，可多项（逗号分隔）；优先写持久证据 changes/<change-id>/evidence/...；也可附带 changes/<change-id>/review/... 或 .agentdocs/tmp/... -->
+
+## 依赖关系（可选）
+
+- `Depends_On` = <!-- WS:TODO 本 change 依赖的前置 change ID（逗号分隔）；例如 feature-auth -->
+- `Blocks` = <!-- WS:TODO 本 change 完成后才能开始的后续 change ID（逗号分隔）；例如 feature-dashboard -->
+
+> 规则：
+> - `Depends_On` 的 change 应已完成（archived）；未完成时 `aiws change start` 会输出警告。
+> - `Blocks` 用于记录依赖关系，便于后续 change 读取交接文档。
+> - 依赖字段为可选，不强制填写。
 
 > 规则：
 > - `Req_ID` 与 `Problem_ID` 至少填写一项。
@@ -37,10 +47,28 @@
 
 ## 影响范围（Scope）
 
-- 影响的服务/模块/目录：
-  - <!-- WS:TODO -->
+### In Scope（本次改动范围）
+
+> 列出允许修改的文件/目录（支持 glob 模式）；用于 `aiws change validate --check-scope` 检查越界改动。
+
+- <!-- WS:TODO 例如：`packages/cli/src/commands/change.ts` - 修改 change 命令逻辑 -->
+- <!-- WS:TODO 例如：`packages/cli/tests/**/*.test.ts` - 相关测试文件 -->
+
+### Out of Scope（明确不改动）
+
+> 列出明确不在本次改动范围内的模块/目录；防止"顺手重构"。
+
+- <!-- WS:TODO 例如：`packages/spec/` - 不修改规范定义 -->
+- <!-- WS:TODO 例如：配置文件 - 不修改 .aiws/config.yaml -->
+
+### 外部影响
+
 - 可能影响的外部接口/使用方：
-  - <!-- WS:TODO -->
+  - <!-- WS:TODO 例如：CLI 命令行接口、API 端点、配置格式等 -->
+
+> 规则：
+> - 实际改动超出 In Scope 时，需在 delivery 时解释原因并更新本章节。
+> - 可使用 `aiws change validate --check-scope` 检查越界文件。
 
 ## 风险与回滚
 
@@ -64,4 +92,6 @@
 - `requirements/CHANGELOG.md`：<!-- WS:TODO 需要/不需要 -->
 - `requirements/requirements-issues.csv`：<!-- WS:TODO 需要/不需要 -->
 - `issues/problem-issues.csv`：<!-- WS:TODO 需要/不需要 -->
-- 证据落盘（`.agentdocs/tmp/...`）：<!-- WS:TODO 计划输出哪些报告/日志 -->
+- 证据落盘（推荐双层）：
+  - 持久（建议入库）：`changes/<change-id>/evidence/...`（例如 validate 总结、review 总结、关键日志摘要）
+  - 临时（可忽略入库）：`.agentdocs/tmp/...`（例如 `aiws validate . --stamp` 的 JSON）

package/templates/workspace/tools/ws_change_check.py

@@ -325,6 +325,8 @@ def validate_change(
     change_id: str,
     strict: bool,
     allow_truth_drift: bool,
+    check_evidence: bool,
+    check_scope: bool,
 ) -> int:
     change_dir = root / "changes" / change_id
     required_files = ["proposal.md", "tasks.md"]
@@ -389,6 +391,185 @@ def validate_change(
         if "WS:TODO" in text:
             (errors if strict else warnings).append(f"WS:TODO markers remain in {rel}")
 
+    def evidence_is_persistent(p: str) -> bool:
+        p2 = p.replace("\\", "/")
+        return p2.startswith(f"changes/{change_id}/evidence/") or p2.startswith(f"changes/{change_id}/review/")
+
+    def parse_scope_patterns_from_plan(plan_text: str) -> List[str]:
+        # Extract bullet list items under "## Scope" (until next heading).
+        lines = (plan_text or "").splitlines()
+        patterns: List[str] = []
+        in_scope = False
+        for raw in lines:
+            line = raw.rstrip("\n")
+            if line.startswith("## "):
+                in_scope = line.strip() in ("## Scope", "## 影响范围（Scope）", "## 影响范围 (Scope)")
+                continue
+            if not in_scope:
+                continue
+            if line.startswith("## "):
+                break
+            s = line.strip()
+            if not s:
+                continue
+            if s.startswith("- "):
+                v = s[2:].strip()
+                if v.startswith("`") and v.endswith("`") and len(v) >= 2:
+                    v = v[1:-1].strip()
+                if v.upper() == "TBD":
+                    continue
+                # Normalize common "path (note)" into "path"
+                v = v.split("（", 1)[0].split("(", 1)[0].strip()
+                if v:
+                    patterns.append(v)
+        return patterns
+
+    def normalize_scope_pattern(pat: str) -> str:
+        p = (pat or "").strip().replace("\\", "/")
+        if p.startswith("./"):
+            p = p[2:]
+        # Treat trailing slash as directory prefix match.
+        if p.endswith("/") and not p.endswith("/**"):
+            p = p + "**"
+        return p
+
+    def match_scope_pattern(relpath: str, pat: str) -> bool:
+        import fnmatch
+
+        rp = (relpath or "").replace("\\", "/")
+        p = normalize_scope_pattern(pat)
+        if not p:
+            return False
+        # If the pattern contains glob syntax, fnmatch it.
+        if any(ch in p for ch in ["*", "?", "[", "]"]):
+            return fnmatch.fnmatch(rp, p)
+        # Otherwise treat as prefix (file or directory).
+        if rp == p:
+            return True
+        return rp.startswith(p.rstrip("/") + "/")
+
+    def check_declared_paths(rel: str, decl: str) -> None:
+        paths = split_declared_values(decl)
+        if not paths:
+            return
+        has_persistent = any(evidence_is_persistent(p) for p in paths)
+        if not has_persistent:
+            (errors if strict else warnings).append(
+                f"{rel} Evidence_Path should include at least one persistent path under changes/<id>/evidence or changes/<id>/review"
+            )
+        for raw in paths:
+            p = raw.strip()
+            if not p:
+                continue
+            if p.startswith("./"):
+                p = p[2:]
+            if p.startswith("~") or os.path.isabs(p):
+                errors.append(f"{rel} Evidence_Path must be workspace-relative, got absolute path: {raw}")
+                continue
+            if ".." in Path(p).parts:
+                errors.append(f"{rel} Evidence_Path must not contain '..': {raw}")
+                continue
+            abs_p = (root / p).resolve()
+            try:
+                abs_p.relative_to(root)
+            except Exception:
+                errors.append(f"{rel} Evidence_Path points outside workspace: {raw}")
+                continue
+            if not abs_p.exists():
+                errors.append(f"{rel} Evidence_Path missing file: {raw}")
+
+    def scope_check_from_plan(plan_rel: str, plan_text: str) -> None:
+        if not check_scope:
+            return
+        patterns = [normalize_scope_pattern(p) for p in parse_scope_patterns_from_plan(plan_text)]
+        patterns = [p for p in patterns if p]
+        if not patterns:
+            (errors if strict else warnings).append(f"{plan_rel} scope check enabled but no patterns found under '## Scope'")
+            return
+
+        meta_path = change_dir / ".ws-change.json"
+        base_branch = ""
+        if meta_path.exists():
+            try:
+                meta = json.loads(read_text(meta_path))
+                base_branch = str((meta or {}).get("base_branch") or "").strip()
+            except Exception:
+                base_branch = ""
+        if not base_branch:
+            (errors if strict else warnings).append(
+                "scope check requires base_branch recorded in changes/<id>/.ws-change.json (run `aiws change start <id>` to record it)"
+            )
+            return
+
+        # Compute changed files vs merge-base with base_branch (include staged + unstaged).
+        try:
+            mb = subprocess.run(
+                ["git", "-C", str(root), "merge-base", base_branch, "HEAD"],
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+        except Exception as e:
+            (errors if strict else warnings).append(f"scope check failed to run git merge-base: {e}")
+            return
+        if mb.returncode != 0:
+            (errors if strict else warnings).append(f"scope check failed to compute merge-base vs {base_branch}: {mb.stderr.strip() or mb.stdout.strip()}")
+            return
+        base = (mb.stdout or "").strip()
+        if not base:
+            (errors if strict else warnings).append(f"scope check failed to compute merge-base vs {base_branch}: empty output")
+            return
+
+        def diff_names(args: List[str]) -> List[str]:
+            try:
+                res = subprocess.run(
+                    ["git", "-C", str(root), "diff", "--name-only", "--diff-filter=ACMR", *args],
+                    check=False,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                )
+            except Exception:
+                return []
+            if res.returncode != 0:
+                return []
+            return [ln.strip() for ln in (res.stdout or "").splitlines() if ln.strip()]
+
+        # Include untracked files as "changed" too (new files are common in dev/deliver stages).
+        untracked: List[str] = []
+        try:
+            ls = subprocess.run(
+                ["git", "-C", str(root), "ls-files", "--others", "--exclude-standard"],
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+            if ls.returncode == 0:
+                untracked = [ln.strip() for ln in (ls.stdout or "").splitlines() if ln.strip()]
+        except Exception:
+            untracked = []
+
+        changed = sorted(set(diff_names([base]) + diff_names(["--cached", base]) + untracked))
+        if not changed:
+            return
+
+        # Always allow core workflow artifacts.
+        always_allow = [
+            f"changes/{change_id}/**",
+            "plan/**",
+            "REQUIREMENTS.md",
+            "requirements/requirements-issues.csv",
+            "issues/problem-issues.csv",
+        ]
+        all_patterns = patterns + always_allow
+
+        out_of_scope = [p for p in changed if not any(match_scope_pattern(p, pat) for pat in all_patterns)]
+        if out_of_scope:
+            msg = "out-of-scope files detected (update plan Scope or explain): " + ", ".join(out_of_scope[:20]) + (" ..." if len(out_of_scope) > 20 else "")
+            (errors if strict else warnings).append(f"{plan_rel} {msg}")
+
     req_id = ""
     prob_id = ""
     change_id_decl = ""
@@ -425,6 +606,8 @@ def validate_change(
             errors.append("proposal.md must include non-empty Plan_File")
         if strict and not evidence_path_decl:
             errors.append("proposal.md must include non-empty Evidence_Path")
+        if check_evidence and evidence_path_decl:
+            check_declared_paths("proposal.md", evidence_path_decl)
 
         if req_id and req_csv.exists():
             ok = False
@@ -532,6 +715,9 @@ def validate_change(
                         errors.append(f"{plan_rel} must include non-empty Plan_File")
                     if strict and not plan_evidence_path:
                         errors.append(f"{plan_rel} must include non-empty Evidence_Path")
+                    if check_evidence and plan_evidence_path:
+                        check_declared_paths(plan_rel, plan_evidence_path)
+                    scope_check_from_plan(plan_rel, plan_text)
 
                     if plan_file_from_plan:
                         plan_file_refs = split_declared_values(plan_file_from_plan)
@@ -602,6 +788,16 @@ def main(argv: Optional[List[str]] = None) -> int:
         action="store_true",
         help="Do not fail strict validation on truth drift (use only for emergencies).",
     )
+    parser.add_argument(
+        "--check-evidence",
+        action="store_true",
+        help="Validate Evidence_Path points to workspace-relative existing files; require at least one persistent evidence path.",
+    )
+    parser.add_argument(
+        "--check-scope",
+        action="store_true",
+        help="Scope gate: compare git diff vs base_branch with plan '## Scope' patterns and warn/error on out-of-scope files.",
+    )
     parser.add_argument(
         "--allow-branches",
         default="main,master",
@@ -663,6 +859,8 @@ def main(argv: Optional[List[str]] = None) -> int:
         change_id=change_id,
         strict=args.strict,
         allow_truth_drift=args.allow_truth_drift,
+        check_evidence=args.check_evidence,
+        check_scope=args.check_scope,
     )