@aipper/aiws-spec 0.0.26 → 0.0.27

package/docs/cli-interface.md

@@ -274,14 +274,15 @@ Dashboard API（本地只读）：
 ### `aiws change start`
 
 语义：
-- 默认行为：切分支到 `change/<change-id>`（存在则切换；不存在则创建）。
+- 默认行为：切分支到 `change/<change-id>`（存在则切换；不存在则创建）；若仓库存在 `.gitmodules`，只切 superproject，本次不会递归切换 submodules。
 - 若检测到 `.gitmodules`（git submodules）且未显式指定 `--switch/--no-switch/--worktree`：默认优先采用 `--worktree`（避免切走 superproject 分支导致 submodule 状态混乱）；若不满足 `--worktree` 前置条件则回退为 `--no-switch`。
 - 若 `changes/<change-id>/` 不存在：等价执行 `aiws change new ...`。
 - 可选：`--hooks` 等价于 `aiws hooks install .`。
 - 可选：`--switch` 显式允许切换 superproject 分支（仅在存在 `.gitmodules` 时有意义；否则等价于默认行为）。
-  - 实现细节：当存在 `.gitmodules` 且使用 `--switch` 时，CLI 会尝试使用 `git switch/checkout --recurse-submodules` 让 submodules 工作区跟随 superproject 指针；若 git 不支持该选项，会降级为普通切分支并提示手工更新 submodules。
+  - 实现细节：当存在 `.gitmodules` 且使用 `--switch` 时，CLI 只切 superproject 分支；submodules 保持当前状态，由 `ws-pull` / `ws-finish` 再统一挂回 `aiws/pin/<target-branch>`。
 - 可选：`--no-switch` 不切换当前分支（仅确保目标分支存在，并初始化变更工件）；适用于 superproject + submodule 场景，避免意外切换 A 目录分支导致 submodule 状态混乱。
 - 可选：`--worktree` 使用 `git worktree` 创建一个独立工作区并在其中 checkout `change/<change-id>`，当前目录分支保持不变（推荐用于 superproject + submodule）。
+- 当 `.gitmodules` 存在时，submodule 的 detached HEAD 恢复应统一使用 `aiws/pin/<target-branch>`；不要把 submodule 切到 `change/<change-id>`。
   - 默认 worktree 目录：`../<repo-name>-<change-id>`（相对于 git root）
   - 可选：`--worktree-dir <path>` 覆盖 worktree 目录（推荐放在仓库外；相对路径按 `../` 作为基准理解）
   - 可选：`--submodules` 在 worktree 内执行 `git submodule update --init --recursive`（避免新 worktree 下 submodule 目录为空）
@@ -311,6 +312,7 @@ Dashboard API（本地只读）：
   - 只有完整 finish 成功（兼容旧事件 `finish`，新事件 `finish_done`）后，治理阶段才可进入 `ws-handoff`
   - 当 `--push` 完整成功时，CLI 应自动执行 archive：将 `changes/<id>/` 移动到 `changes/archive/<YYYY-MM-DD>-<id>/`，生成 `handoff.md`，提交 `归档: <change-id>`，并将该 archive commit push 到同一目标分支
   - 若 auto-archive commit/push 失败，应报错并保留已归档工件，提示用户继续提交/推送 archive 结果；不应要求重新做 merge
+  - 若发现“已 finish 但 active `changes/<id>/` 仍存在”的 `finished_unarchived` 状态，应视为 finish closeout 未完成：默认恢复动作是重跑 `aiws change finish <id> --push`，而不是继续开发或要求从头再做 merge
 
 接口（仅定义）：
 - `aiws change finish [<change-id>] [--into <branch> | --base <branch>]`

package/docs/workflow-governance-rules.json

@@ -2,6 +2,13 @@
   "version": 1,
   "description": "Machine-readable governance inference rules for aiws change status/next/dashboard.",
   "governanceRules": [
+    {
+      "id": "finish_resume_required",
+      "when": { "signal": "finish_resume_required", "truthy": true },
+      "currentStage": "ws-finish",
+      "recommendedStage": "ws-finish",
+      "rationale": "finish already completed locally, but archive/push closeout is still pending; rerun finish to resume"
+    },
     {
       "id": "strict_blockers",
       "when": { "signal": "blockers_strict_count", "gt": 0 },
@@ -269,9 +276,16 @@
         "收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff"
       ]
     },
+    {
+      "id": "guidance_finish_resume_required",
+      "when": { "signal": "governance_rule_id", "eq": "finish_resume_required" },
+      "lines": [
+        "finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支 worktree 运行 `aiws validate . --stamp`）"
+      ]
+    },
     {
       "id": "guidance_finish_retry",
-      "when": { "signal": "governance_rule_id", "in": ["finish_failed", "finish_local"] },
+      "when": { "signal": "governance_rule_id", "in": ["finish_failed", "finish_local", "finish_resume_required"] },
       "lines": [
         "收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish`"
       ]

package/docs/workflow-governance-rules.md

@@ -11,13 +11,14 @@
 
 - version: `1`
 - description: Machine-readable governance inference rules for aiws change status/next/dashboard.
-- governance rules: 16
-- guidance rules: 16
+- governance rules: 17
+- guidance rules: 17
 
 ## 阶段推断规则
 
 | Rule ID | Match | Current | Next | Rationale |
 | --- | --- | --- | --- | --- |
+| `finish_resume_required` | `finish_resume_required` is truthy | `ws-finish` | `ws-finish` | finish already completed locally, but archive/push closeout is still pending; rerun finish to resume |
 | `strict_blockers` | `blockers_strict_count` > 0 | `ws-plan-verify` | `ws-plan-verify` | strict blockers remain unresolved |
 | `unchecked_tasks` | `tasks_unchecked` > 0 | `ws-dev` | `ws-dev` | {tasks_unchecked} unchecked task(s) remain |
 | `finish_completed` | `finish_state` == `done` | `ws-finish` | `ws-handoff` | finish completed; archive should already exist and handoff is ready for follow-up |
@@ -52,7 +53,8 @@
 | `guidance_deliver_finish` | (`governance_current_stage` == `ws-deliver`) AND (`governance_recommended_stage` == `ws-finish`) | 交付工件齐全后，进入 `$ws-finish`（安全合并 + push + cleanup） |
 | `guidance_finish_cleanup_pending` | `governance_rule_id` == `finish_cleanup_pending` | push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 worktree 后重跑 `$ws-finish` |
 | `guidance_finish_handoff` | `governance_rule_id` == `finish_completed` | 收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff |
-| `guidance_finish_retry` | `governance_rule_id` in [`finish_failed`, `finish_local`] | 收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish` |
+| `guidance_finish_resume_required` | `governance_rule_id` == `finish_resume_required` | finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支 worktree 运行 `aiws validate . --stamp`） |
+| `guidance_finish_retry` | `governance_rule_id` in [`finish_failed`, `finish_local`, `finish_resume_required`] | 收尾未完整完成：检查 push / cleanup / submodule 状态后重跑 `$ws-finish` |
 | `guidance_handoff` | `governance_current_stage` == `ws-handoff` | 进入交接：在 AI 工具中运行 `$ws-handoff`，并检查归档 handoff 是否足够支撑下一次接力 |
 | `guidance_default` | `governance_current_stage` == `` | 按阶段契约继续推进当前 change |
 

package/package.json

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

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

@@ -14,7 +14,8 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 前置（必须）：
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
 - change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
+- 若使用 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`）
 
 阶段定位：
@@ -60,7 +61,11 @@ if [[ -f .gitmodules ]]; then
   fi
 fi
 ```
-1) （推荐）先跑一次门禁并落盘证据：
+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
@@ -70,7 +75,10 @@ else
   npx @aipper/aiws validate . --stamp
 fi
 ```
-1.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：
+若你已经位于目标分支 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
@@ -81,7 +89,7 @@ else
   npx @aipper/aiws change evidence "${change_id}"
 fi
 ```
-1.2) （可选）生成状态快照（建议）：
+1.2) （可选，仅适用于普通 finish）生成状态快照（建议）：
 ```bash
 aiws change state "${change_id}" --write
 ```

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

@@ -9,7 +9,9 @@
 前置（必须）：
 - 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
 - change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
- - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
+- 普通 finish 的 `validate/evidence/state` 应先在 `change/<change-id>` worktree 完成；真正执行 `aiws change finish` 时再切到目标分支所在 worktree
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`：说明 merge 已发生，只需继续 push / archive / cleanup closeout；直接在提示的 worktree 运行 `aiws change finish <change-id> --push`
+- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
 
 步骤（建议）：
 0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
@@ -31,9 +33,11 @@ if [[ -f .gitmodules ]]; then
 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`。
+2) 先运行 `aiws change status <change-id>`，优先看稳定字段 `governance_rule:`。
+   - 若为 `finish_resume_required`：直接跳到步骤 3 执行 `aiws change finish <change-id> --push`
+   - 若不是该值：按普通 finish 继续；不要依赖自然语言提示句做分支判断
+2.1) 普通 finish 时，`aiws validate . --stamp` / `aiws change evidence <change-id>` / `aiws change state <change-id> --write` 应在 `change/<change-id>` worktree 完成。
+   - 如果已经在目标分支 worktree，且 `governance_rule` 不是 `finish_resume_required`，不要在这里跑 `aiws validate . --stamp`；先回 `change/<change-id>` worktree，或先跑 `/ws-verify-before-complete`
 3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
    - `aiws change finish <change-id> --push`
    - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`

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

@@ -14,7 +14,8 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 前置（必须）：
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
 - change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
+- 若使用 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`）
 
 阶段定位：
@@ -60,7 +61,11 @@ if [[ -f .gitmodules ]]; then
   fi
 fi
 ```
-1) （推荐）先跑一次门禁并落盘证据：
+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
@@ -70,7 +75,10 @@ else
   npx @aipper/aiws validate . --stamp
 fi
 ```
-1.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：
+若你已经位于目标分支 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
@@ -81,7 +89,7 @@ else
   npx @aipper/aiws change evidence "${change_id}"
 fi
 ```
-1.2) （可选）生成状态快照（建议）：
+1.2) （可选，仅适用于普通 finish）生成状态快照（建议）：
 ```bash
 aiws change state "${change_id}" --write
 ```

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

@@ -12,7 +12,9 @@ description: 收尾：fast-forward 合并并把 submodule 并回目标分支后
 前置（必须）：
 - 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
 - change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
- - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
+- 普通 finish 的 `validate/evidence/state` 应先在 `change/<change-id>` worktree 完成；真正执行 `aiws change finish` 时再切到目标分支所在 worktree
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`：说明 merge 已发生，只需继续 push / archive / cleanup closeout；直接在提示的 worktree 运行 `aiws change finish <change-id> --push`
+- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
 
 步骤（建议）：
 0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
@@ -34,9 +36,11 @@ if [[ -f .gitmodules ]]; then
 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`。
+2) 先运行 `aiws change status <change-id>`，优先看稳定字段 `governance_rule:`。
+   - 若为 `finish_resume_required`：直接跳到步骤 3 执行 `aiws change finish <change-id> --push`
+   - 若不是该值：按普通 finish 继续；不要依赖自然语言提示句做分支判断
+2.1) 普通 finish 时，`aiws validate . --stamp` / `aiws change evidence <change-id>` / `aiws change state <change-id> --write` 应在 `change/<change-id>` worktree 完成。
+   - 如果已经在目标分支 worktree，且 `governance_rule` 不是 `finish_resume_required`，不要在这里跑 `aiws validate . --stamp`；先回 `change/<change-id>` worktree，或先跑 `/ws-verify-before-complete`
 3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
    - `aiws change finish <change-id> --push`
    - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`

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

@@ -12,7 +12,9 @@ description: 收尾：fast-forward 合并并把 submodule 并回目标分支后
 前置（必须）：
 - 工作区干净：`git status --porcelain` 无输出（否则先 commit 或 stash）
 - change 分支存在（`change/<change-id>`；也支持 `changes/`、`ws/`、`ws-change/`）
- - 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
+- 普通 finish 的 `validate/evidence/state` 应先在 `change/<change-id>` worktree 完成；真正执行 `aiws change finish` 时再切到目标分支所在 worktree
+- 若 `aiws change status <change-id>` 输出 `governance_rule: finish_resume_required`：说明 merge 已发生，只需继续 push / archive / cleanup closeout；直接在提示的 worktree 运行 `aiws change finish <change-id> --push`
+- 若存在 `.gitmodules`：必须为每个 submodule 配置 `submodule.<name>.branch`（否则先运行 `/ws-submodule-setup` 并提交 `.gitmodules`）
 
 步骤（建议）：
 0) 若存在 `.gitmodules`，先检查 submodule branch 配置是否齐全（缺失则停止并提示 setup）：
@@ -34,9 +36,11 @@ if [[ -f .gitmodules ]]; then
 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`。
+2) 先运行 `aiws change status <change-id>`，优先看稳定字段 `governance_rule:`。
+   - 若为 `finish_resume_required`：直接跳到步骤 3 执行 `aiws change finish <change-id> --push`
+   - 若不是该值：按普通 finish 继续；不要依赖自然语言提示句做分支判断
+2.1) 普通 finish 时，`aiws validate . --stamp` / `aiws change evidence <change-id>` / `aiws change state <change-id> --write` 应在 `change/<change-id>` worktree 完成。
+   - 如果已经在目标分支 worktree，且 `governance_rule` 不是 `finish_resume_required`，不要在这里跑 `aiws validate . --stamp`；先回 `change/<change-id>` worktree，或先跑 `/ws-verify-before-complete`
 3) 若不存在 `.gitmodules`，或 submodules 已按顺序处理完成，优先直接执行最小收尾闭环：
    - `aiws change finish <change-id> --push`
    - 若当前就在 `change/<change-id>` 分支上，也可省略 `<change-id>`

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

@@ -14,7 +14,8 @@ description: 收尾（门禁 + 安全合并 + submodule→主仓库顺序 push
 前置（必须）：
 - 工作区是干净的：`git status --porcelain` 无输出（若有未提交改动：先 commit 或 stash）
 - change 分支已存在：`change/<change-id>`（也支持 `changes/`、`ws/`、`ws-change/`）
-- 若使用 worktree：在目标分支所在 worktree 执行（`aiws change finish` 会提示正确的 worktree）
+- 若使用 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`）
 
 阶段定位：
@@ -60,7 +61,11 @@ if [[ -f .gitmodules ]]; then
   fi
 fi
 ```
-1) （推荐）先跑一次门禁并落盘证据：
+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
@@ -70,7 +75,10 @@ else
   npx @aipper/aiws validate . --stamp
 fi
 ```
-1.1) （强烈建议）收敛持久证据并回填 `Evidence_Path`：
+若你已经位于目标分支 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
@@ -81,7 +89,7 @@ else
   npx @aipper/aiws change evidence "${change_id}"
 fi
 ```
-1.2) （可选）生成状态快照（建议）：
+1.2) （可选，仅适用于普通 finish）生成状态快照（建议）：
 ```bash
 aiws change state "${change_id}" --write
 ```

package/templates/workspace/changes/README.md

@@ -34,12 +34,13 @@ changes/
 常用命令（推荐使用 `aiws`；不依赖 dotfiles）：
 - `aiws change start <change-id>`（默认：切到 `change/<change-id>` 并初始化工件目录；若检测到 `.gitmodules` 则默认优先使用 worktree，失败则回退为不切分支，避免 submodule 状态混乱）
 - `aiws change start <change-id> --no-switch`（superproject + submodule 场景：不切分支，仅准备 `change/<change-id>` 分支与工件目录）
-- `aiws change start <change-id> --switch`（显式允许切换 superproject 分支；仅在存在 `.gitmodules` 时有意义）
+- `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 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 new <change-id>`
 - `aiws change list`
 - `aiws change status <change-id>`

package/templates/workspace/tools/ws_change_check.py

@@ -16,6 +16,13 @@ from typing import Any, Dict, List, Optional, Tuple
 
 CHANGE_BRANCH_RE = re.compile(r"^(change|changes|ws|ws-change)/([a-z0-9]+(?:-[a-z0-9]+)*)$")
 CHANGE_ID_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+PIN_BRANCH_RE = re.compile(r"^aiws/pin/.+$")
+FINISH_DONE_COMPLETED_CLEANUPS = {
+    "removed",
+    "pruned-missing",
+    "skipped:no_separate_change_worktree",
+    "skipped:current_worktree",
+}
 
 
 def eprint(msg: str) -> None:
@@ -93,6 +100,53 @@ def parse_submodule_targets(path: Path) -> Tuple[Dict[str, Tuple[str, str]], Lis
     return parsed, perr
 
 
+def git_text(root: Path, args: List[str]) -> Tuple[int, str, str]:
+    try:
+        res = subprocess.run(
+            ["git", "-C", str(root), *args],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        return (res.returncode, (res.stdout or "").strip(), (res.stderr or "").strip())
+    except Exception as exc:
+        return (1, "", str(exc))
+
+
+def resolve_change_gitlink_commit(root: Path, change_id: str, sub_path: str) -> str:
+    for spec in (f"change/{change_id}:{sub_path}", f"HEAD:{sub_path}"):
+        code, out, _ = git_text(root, ["rev-parse", spec])
+        if code == 0 and out:
+            return out
+    return ""
+
+
+def git_ref_exists(root: Path, ref: str) -> bool:
+    code, _, _ = git_text(root, ["show-ref", "--verify", "--quiet", ref])
+    return code == 0
+
+
+def git_revision_exists(root: Path, rev: str) -> bool:
+    code, _, _ = git_text(root, ["cat-file", "-e", f"{rev}^{{commit}}"])
+    return code == 0
+
+
+def git_is_ancestor(root: Path, older: str, newer: str) -> bool:
+    code, _, _ = git_text(root, ["merge-base", "--is-ancestor", older, newer])
+    return code == 0
+
+
+def resolve_branch_ref(repo_root: Path, remote: str, branch: str) -> str:
+    remote_ref = f"refs/remotes/{remote}/{branch}"
+    if git_ref_exists(repo_root, remote_ref):
+        return remote_ref
+    local_ref = f"refs/heads/{branch}"
+    if git_ref_exists(repo_root, local_ref):
+        return local_ref
+    return ""
+
+
 def sha256(path: Path) -> str:
     h = hashlib.sha256()
     with path.open("rb") as f:
@@ -128,6 +182,17 @@ def current_branch(root: Path) -> Optional[str]:
         return None
 
 
+def is_submodule_repo(root: Path) -> bool:
+    try:
+        parent = subprocess.check_output(
+            ["git", "-C", str(root), "rev-parse", "--show-superproject-working-tree"],
+            text=True,
+        ).strip()
+        return bool(parent)
+    except Exception:
+        return False
+
+
 def infer_change_id_from_branch(branch: Optional[str]) -> Optional[str]:
     if not branch:
         return None
@@ -137,6 +202,103 @@ def infer_change_id_from_branch(branch: Optional[str]) -> Optional[str]:
     return m.group(2)
 
 
+def parse_archived_change_dir_name(entry_name: str) -> Optional[Tuple[str, str, str]]:
+    m = re.match(r"^(\d{4}-\d{2}-\d{2})-(.+?)(?:-(\d{8}-\d{6}Z))?$", entry_name or "")
+    if not m:
+        return None
+    change_id = (m.group(2) or "").strip()
+    if not CHANGE_ID_RE.match(change_id):
+        return None
+    return (m.group(1) or "", change_id, m.group(3) or "")
+
+
+def find_archived_change(root: Path, change_id: str) -> Optional[Path]:
+    archive_root = root / "changes" / "archive"
+    if not archive_root.exists():
+        return None
+    matches: List[Path] = []
+    for entry in archive_root.iterdir():
+        if not entry.is_dir():
+            continue
+        parsed = parse_archived_change_dir_name(entry.name)
+        if parsed and parsed[1] == change_id:
+            matches.append(entry)
+    if not matches:
+        return None
+    return sorted(matches, key=lambda item: item.name)[-1]
+
+
+def classify_finish_lifecycle_event(ev: Dict[str, Any]) -> Optional[Tuple[str, str]]:
+    event_type = str((ev or {}).get("type") or "").strip()
+    if not event_type:
+        return None
+    if event_type == "finish_local":
+        return ("local", "")
+    if event_type == "finish_failed":
+        return ("failed", str((ev or {}).get("payload", {}).get("error") or ""))
+    if event_type == "finish_cleanup_pending":
+        payload = (ev or {}).get("payload") or {}
+        return ("cleanup_pending", str(payload.get("reason") or payload.get("cleanup") or ""))
+    if event_type == "finish":
+        return ("done", "")
+    if event_type != "finish_done":
+        return None
+    payload = (ev or {}).get("payload")
+    if not isinstance(payload, dict):
+        payload = {}
+    push_present = "push" in payload
+    push_completed = payload.get("push") is True if push_present else None
+    cleanup = str(payload.get("cleanup") or "").strip()
+    if push_completed is False or cleanup == "not_requested":
+        return ("local", "")
+    if not cleanup or cleanup in FINISH_DONE_COMPLETED_CLEANUPS:
+        return ("done", "")
+    reason = cleanup[len("skipped:") :] if cleanup.startswith("skipped:") else cleanup
+    return ("cleanup_pending", reason)
+
+
+def summarize_finish_state(change_dir: Path) -> str:
+    metrics_path = change_dir / "metrics.json"
+    if not metrics_path.exists():
+        return ""
+    try:
+        metrics = json.loads(read_text(metrics_path))
+    except Exception:
+        return ""
+    events = metrics.get("events")
+    if not isinstance(events, list):
+        return ""
+    finish_state = ""
+    for ev in events:
+        event_type = str((ev or {}).get("type") or "").strip()
+        if not event_type:
+            continue
+        if finish_state == "done" and event_type not in ("finish_done", "finish"):
+            continue
+        classified = classify_finish_lifecycle_event(ev)
+        if not classified:
+            continue
+        finish_state = classified[0]
+    return finish_state
+
+
+def terminated_change_message(root: Path, change_id: str) -> Optional[str]:
+    change_dir = root / "changes" / change_id
+    if change_dir.exists() and summarize_finish_state(change_dir) == "done":
+        return (
+            f"change/{change_id} already reached finish, but archive/push closeout is still pending; "
+            f"rerun `aiws change finish {change_id} --push` instead of continuing development on this branch"
+        )
+    archived = find_archived_change(root, change_id)
+    if archived:
+        handoff = archived / "handoff.md"
+        details = f"change/{change_id} is already archived at {archived.relative_to(root)}"
+        if handoff.exists():
+            details += f" (handoff: {handoff.relative_to(root)})"
+        return details + "; create a new follow-up change instead of reusing this branch"
+    return None
+
+
 def has_truth_files(root: Path) -> Tuple[bool, List[str]]:
     required = ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"]
     missing = [f for f in required if not (root / f).exists()]
@@ -487,6 +649,45 @@ def validate_change(
                 else:
                     warnings.append(msg)
 
+        if subs:
+            targets_path = change_dir / "submodules.targets"
+            if targets_path.exists() and targets_path.stat().st_size > 0:
+                targets, _ = parse_submodule_targets(targets_path)
+                base_branch = str(meta.get("base_branch") or "").strip() or "main"
+                for _, sub_path in subs:
+                    target = targets.get(sub_path)
+                    if not target:
+                        continue
+                    target_branch = target[0] if target[0] != "." else base_branch
+                    remote = target[1] or "origin"
+                    gitlink_sha = resolve_change_gitlink_commit(root, change_id, sub_path)
+                    if not gitlink_sha:
+                        warnings.append(f"unable to resolve gitlink commit for submodule path: {sub_path}")
+                        continue
+                    sub_root = root / sub_path
+                    if not sub_root.exists():
+                        warnings.append(f"submodule path not initialized locally (skip target consistency check): {sub_path}")
+                        continue
+                    if not git_revision_exists(sub_root, gitlink_sha):
+                        warnings.append(
+                            f"{sub_path}: gitlink commit {gitlink_sha} is not available in local submodule clone; run `git submodule update --init --recursive`"
+                        )
+                        continue
+                    branch_ref = resolve_branch_ref(sub_root, remote, target_branch)
+                    if not branch_ref:
+                        warnings.append(
+                            f"{sub_path}: cannot verify target branch history locally (missing {remote}/{target_branch} and local branch {target_branch})"
+                        )
+                        continue
+                    if git_is_ancestor(sub_root, gitlink_sha, branch_ref):
+                        continue
+                    errors.append(
+                        f"{sub_path}: gitlink commit {gitlink_sha} is not contained in declared target branch {remote}/{target_branch}"
+                    )
+                    errors.append(
+                        f"hint: fix `.gitmodules` / `changes/{change_id}/submodules.targets`, or move the submodule gitlink onto a commit reachable from {remote}/{target_branch}"
+                    )
+
     def placeholder_scan(rel: str, text: str) -> None:
         if "{{CHANGE_ID}}" in text or "{{TITLE}}" in text or "{{CREATED_AT}}" in text:
             errors.append(f"unrendered template placeholders in {rel}")
@@ -942,6 +1143,8 @@ def main(argv: Optional[List[str]] = None) -> int:
 
     branch_arg = (args.branch or "").strip()
     branch = branch_arg or current_branch(root)
+    inferred_from_branch = False
+    submodule_repo = is_submodule_repo(root)
     if not change_id:
         # Detached HEAD during rebase/merge; do not block unless CI passes --branch.
         if not branch:
@@ -950,26 +1153,40 @@ def main(argv: Optional[List[str]] = None) -> int:
         allow = {b.strip() for b in (args.allow_branches or "").split(",") if b.strip()}
         if branch in allow:
             return 0
+        if submodule_repo and PIN_BRANCH_RE.match(branch):
+            return 0
         inferred = infer_change_id_from_branch(branch)
         if not inferred:
             eprint(f"error: branch must be change/<change-id> (current: {branch})")
             eprint("hint: switch/create: git switch -c change/<change-id>")
             return 2
         change_id = inferred
+        inferred_from_branch = True
     else:
         # If CI provides --branch, cross-check branch naming even when --change-id is provided.
         if branch_arg:
             allow = {b.strip() for b in (args.allow_branches or "").split(",") if b.strip()}
             if branch_arg not in allow:
-                inferred = infer_change_id_from_branch(branch_arg)
-                if not inferred:
-                    eprint(f"error: branch must be change/<change-id> (current: {branch_arg})")
-                    return 2
-                if inferred != change_id:
-                    eprint(f"error: change-id does not match branch (branch={branch_arg}, change_id={change_id})")
-                    return 2
+                if submodule_repo and PIN_BRANCH_RE.match(branch_arg):
+                    branch_arg = ""
+                else:
+                    inferred = infer_change_id_from_branch(branch_arg)
+                    if not inferred:
+                        eprint(f"error: branch must be change/<change-id> (current: {branch_arg})")
+                        return 2
+                    if inferred != change_id:
+                        eprint(f"error: change-id does not match branch (branch={branch_arg}, change_id={change_id})")
+                        return 2
 
     change_dir = root / "changes" / change_id
+    terminated = terminated_change_message(root, change_id) if (inferred_from_branch or bool(branch_arg)) else None
+    if terminated:
+        eprint(f"error: {terminated}")
+        eprint(
+            f"hint: stop using change/{change_id} for new work; rerun `aiws change finish {change_id} --push` "
+            "or archive manually only for local recovery"
+        )
+        return 2
     if not change_dir.exists():
         eprint(f"error: missing change dir: {change_dir}")
         eprint(f"hint: create: aiws change new {change_id} --no-design")