@aipper/aiws-spec 0.0.23 → 0.0.25

package/docs/workflow-stage-contracts.md

@@ -0,0 +1,70 @@
+# workflow-stage-contracts
+
+<!-- Generated from packages/spec/docs/workflow-stage-contracts.json by scripts/sync-workflow-stage-contracts.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档把 `aiws` 核心 `ws-*` workflow 的阶段契约写成统一真值，避免不同工具、不同协作者把同一个入口用成不同语义。
+
+重点不是“命令名长什么样”，而是每个阶段必须收什么输入、产出什么结果、在什么情况下必须停止。
+
+## 标准链路
+
+默认链路：
+
+`ws-preflight` -> `ws-plan` -> `ws-plan-verify` -> `ws-dev` -> `ws-review` -> `ws-commit` -> `ws-deliver` -> `ws-finish` -> `ws-handoff`
+
+说明：
+- ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。
+- ws-finish 用于 fast-forward 合并、push 和 worktree cleanup。
+- ws-handoff 通常在 archive 后使用，为下一次会话留下交接说明。
+- 若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。
+
+## 阶段表
+
+| Stage | 目标 | 必需输入 | 必需输出 | 阻断条件 | 下一步 |
+| --- | --- | --- | --- | --- | --- |
+| `ws-preflight` | 对齐真值文件与协作约束 | 项目根；AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md | Root / Found / Missing / Key rules / Next | 无法确定项目根；真值缺失 | ws-plan 或 ws-dev |
+| `ws-plan` | 建立 change 绑定并落盘计划 | 任务描述；真值文件；proposal.md（若存在） | plan/...；Bindings；Verify；Risks；Evidence；Next | 绑定不清；dirty 工作区无法安全建 context；无法写盘 | ws-plan-verify |
+| `ws-plan-verify` | 检查计划是否满足严格契约 | plan/...；proposal.md；当前 change | Quality gate；Fix list；可执行最小计划摘要 | strict 校验失败；无法定位 change | 修计划后重跑或进入 ws-dev |
+| `ws-dev` | 实施最小改动并验证 | 真值文件；归因目标；计划（medium/complex） | Changed；Verify；Evidence；Next | 无法归因；没有验证入口；change 上下文不安全 | ws-review / ws-commit |
+| `ws-review` | 审计规范、风险与验证完整性 | 当前 diff；验证结果；真值文件 | review 文件；Top risks；Next | 无改动可审；无法写审计证据 | ws-commit 或修复后重审 |
+| `ws-commit` | 串联 review、validate、commit 确认 | staged diff；review 证据；validate stamp；用户确认的 message | Evidence；Context；Commit | 无 staged changes；submodule dirty；validate 失败；message 未确认 | ws-deliver / ws-finish |
+| `ws-deliver` | 在 submodule 场景下完成顺序提交与证据收敛 | change 上下文；.gitmodules；submodules.targets；各 repo 状态 | submodule 提交摘要；superproject 提交摘要；Evidence | submodule 真值不完整；不在正确 change；commit 未确认 | ws-finish |
+| `ws-finish` | 安全合并、push、cleanup | 干净工作区；已提交的 change；push 目标；submodule 真值（若有） | Merge；Push；Worktree cleanup；Evidence | dirty 工作区；ff 失败；submodule 无法安全 push | ws-handoff 或 archive |
+| `ws-handoff` | 生成可接力的归档交接说明 | 已归档或待归档的 change | changes/archive/.../handoff.md；Next | 无法定位 change；archive 失败；handoff 无法生成 | 新 change 通过 Depends_On 接力 |
+
+## 统一规则
+
+- 每个阶段都必须回指真值文件或 change 工件，不能只依赖会话上下文。
+- 每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。
+- 遇到阻断条件时必须停止，不能为了推进速度跳过门禁。
+- 如果一个阶段没有留下可审计路径，它就不算真正完成。
+- `ws-finish` 只有在 merge、push、cleanup 都完成后才算完成；仅本地 merge 成功不等于可进入 `ws-handoff`。
+
+## 证据约定
+
+最少证据集合：
+
+- planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
+- review：`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`
+- validate：`.agentdocs/tmp/aiws-validate/*.json`
+- deliver / finish：`changes/<change-id>/evidence/...`、`state`、merge / push 结果
+- handoff：`changes/archive/.../handoff.md`
+
+补充：
+- tmp review 证据可以作为“进入 commit gate”的临时治理信号，但在交付前应通过 `aiws change evidence` 收敛为持久 review 证据。
+- finish 生命周期建议区分“本地开始”和“完整完成”两类信号，避免仅凭本地 merge 就误导到 handoff。
+
+## 与产品定位的关系
+
+这份阶段契约文档是 `aiws` “治理内核”定位的直接落点：
+
+- `packages/spec/` 继续作为规则真值层
+- `ws-*` 阶段契约是工作流治理层
+- `docs/workflow-stage-contracts.json` 是运行时阶段契约的机器可读真值
+- `docs/workflow-governance-rules.json` 是运行时阶段推断的机器可读真值
+- CLI / tool-native files 是执行与分发层
+- review / validate / handoff 等工件属于证据与审计层
+
+如果未来要吸收新的 skill、协同角色或外部 workflow，优先判断它能否被映射到这张阶段表；不能稳定映射的能力，不应直接成为核心真值。

package/docs/workflow-stage-contracts.schema.json

@@ -0,0 +1,98 @@
+{
+  "type": "object",
+  "required": [
+    "version",
+    "title",
+    "description",
+    "purpose",
+    "standardChain",
+    "notes",
+    "stages",
+    "unifiedRules",
+    "evidence",
+    "positioning"
+  ],
+  "properties": {
+    "version": { "type": "integer" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "purpose": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "standardChain": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" }
+    },
+    "notes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["stage", "goal", "requiredInputs", "requiredOutputs", "blockers", "next"],
+        "properties": {
+          "stage": { "type": "string", "minLength": 1, "pattern": "^ws-[a-z0-9-]+$" },
+          "goal": { "type": "string", "minLength": 1 },
+          "requiredInputs": { "type": "string", "minLength": 1 },
+          "requiredOutputs": { "type": "string", "minLength": 1 },
+          "blockers": { "type": "string", "minLength": 1 },
+          "next": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "unifiedRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["intro", "minimum", "notes"],
+      "properties": {
+        "intro": { "type": "string", "minLength": 1 },
+        "minimum": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["label", "value"],
+            "properties": {
+              "label": { "type": "string", "minLength": 1 },
+              "value": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          }
+        },
+        "notes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "positioning": {
+      "type": "object",
+      "required": ["intro", "layers", "closing"],
+      "properties": {
+        "intro": { "type": "string", "minLength": 1 },
+        "layers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "closing": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

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

package/templates/workspace/.agents/skills/using-aiws/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: using-aiws
+description: 默认 workflow bootstrap/router：先读真值，再路由到正确的 ws-* 入口
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
+- 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+
+阶段定位：
+- bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
+
+必需输入：
+- 当前任务描述
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 若已存在：当前 `change/<change-id>` 上下文、`plan/...`、`changes/<change-id>/...`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Task intent:` 当前任务意图分类
+- `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
+- `Route:` 选中的下一步 skill
+- `Why:` 选择该 route 的原因
+- `Next:` 进入对应 skill，或先提澄清问题
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+- 无法明确当前任务意图
+- 无法明确归因或验证入口，且不能安全推断
+
+完成判定：
+- 已经明确给出单一路由结果，并进入对应 `ws-*` skill；或已提出关键澄清问题并停止。
+
+执行步骤（强制）：
+1) 先遵守 `$ws-preflight` 的真值读取要求：
+   - 定位项目根目录
+   - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+   - 输出 `Root:` / `Found:` / `Missing:`
+2) 若缺失任一真值文件：
+   - 不进入实现
+   - 输出下一步：先 `aiws init .`（或 `npx @aipper/aiws init .`），然后重新执行 `$using-aiws`
+   - 此时 route 视为 `$ws-preflight`
+3) 根据 `packages/spec/docs/workflow-router-rules.json` 判定任务属于哪一类：
+   - 需求/验收/合同变更：`$ws-req-review`
+   - 评审/审计/找风险：`$ws-review`
+   - finish / merge / push / cleanup：`$ws-finish`
+   - handoff / archive summary：`$ws-handoff`
+   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
+   - 小步明确实现/修复/配置调整：`$ws-dev`
+4) 若任务意图或归因不明确：
+   - 只问 1-3 个关键澄清问题
+   - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
+   - 然后停止；不要直接写代码
+5) 若已确定 route：
+   - 先输出：
+     - `Task intent:`
+     - `Binding:`
+     - `Route:`
+     - `Why:`
+   - 然后在同一轮中继续遵循对应 skill 的契约
+6) 路由约束：
+   - router 自己不是实现阶段；不要在给出 route 之前直接改代码
+   - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
+   - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
+7) 若执行过程中发现复杂度升高：
+   - 从 `$ws-dev` 回退到 `$ws-plan`
+   - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
+
+输出模板：
+- `Root:` <path>
+- `Found:` <files>
+- `Task intent:` <分类>
+- `Binding:` <清晰 / 缺失项>
+- `Route:` <$ws-... 或 clarify>
+- `Why:` <一句到三句>
+- `Next:` <继续执行对应 skill，或提出澄清问题>

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

@@ -19,12 +19,34 @@ description: 缺陷修复（通过禅道 MCP 拉取 bug 与附件，下载图片
 前置：
 1) 先运行 `$ws-preflight`。
 2) 准备 `change-id`（建议：`bug-<bug-id>` 或 `bugfix-<bug-id>-<slug>`）。
-3) 建立变更工件（推荐）：
+3) 建立 change 上下文（推荐先于任何落盘）：
+   - 若当前还不在 `change/<change-id>` 分支 / worktree，先调用 `aiws change start`
+   - 工作区必须先干净；否则不要先写 `changes/<change-id>/bug/` 或 `issues/fix_bus_issues.csv`，避免后续切 worktree 时工件留在原工作区
+   - 仓库已有提交：优先 `--worktree`
+   - superproject + submodule：优先 `--worktree --submodules`
+   - 仓库尚无提交 / 不满足 worktree 前置条件：回退 `--no-switch`
 ```bash
-aiws change start <change-id> --hooks
-# superproject + submodule 推荐：
-aiws change start <change-id> --hooks --worktree --submodules
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree dirty before ws-bugfix creates change context"
+  exit 2
+fi
+
+if git rev-parse --verify HEAD >/dev/null 2>&1; then
+  if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' >/dev/null 2>&1; then
+    aiws change start <change-id> --hooks --worktree --submodules
+  else
+    aiws change start <change-id> --hooks --worktree
+  fi
+else
+  aiws change start <change-id> --hooks --no-switch
+fi
 ```
+   - 若上一步创建了 worktree：后续 bug 证据、CSV 更新、`$ws-dev` 修复都必须在该 worktree 中继续；不要回原工作区重复创建 change
+   - 若该 change 涉及 submodule：
+     - 优先复用 `$ws-dev` 的 `submodules.targets` 生成/确认流程
+     - detached HEAD 时默认建议取 `.gitmodules` 声明的分支
+     - 已附着在某个本地分支时默认建议取当前分支
+     - 以上都只是建议值，最终必须显式写入 `changes/<change-id>/submodules.targets`
 
 建议流程（按顺序）：
 
@@ -36,7 +58,7 @@ aiws change start <change-id> --hooks --worktree --submodules
 - 若当前环境没有 zentao MCP 工具：立即停止并提示用户先配置，不要猜数据。
 
 ## 2) 证据落盘（强制）
-在 `changes/<change-id>/bug/` 下落盘：
+在当前 active change 上下文的 `changes/<change-id>/bug/` 下落盘：
 - `zentao-bug-<bug-id>.json`：原始字段快照（避免信息丢失）
 - `zentao-bug-<bug-id>.md`：人类可读摘要（复现步骤/期望/实际/风险）
 - `images/<bug-id>/...`：下载的图片附件（保留原扩展名）
@@ -50,7 +72,7 @@ changes/<change-id>/bug/
 ```
 
 ## 3) 汇总到 issues/fix_bus_issues.csv（upsert）
-- 目标文件：`issues/fix_bus_issues.csv`
+- 目标文件：当前 active change 上下文中的 `issues/fix_bus_issues.csv`
 - 若文件不存在，先创建表头：
 ```csv
 Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Paths,Evidence_Path,Verify_Command,Fix_Status,Updated_At,Notes
@@ -66,7 +88,7 @@ Bug_ID,Title,Severity,Module,Status,Assigned_To,Change_ID,Image_Count,Image_Path
 - `Fix_Status`：`TODO|DOING|DONE|BLOCKED`
 
 ## 4) 修复执行与回填
-- 进入 `$ws-dev` 做最小改动修复。
+- 进入 `$ws-dev` 做最小改动修复；若 `ws-bugfix` 创建了 worktree，则必须在该 worktree 中继续。
 - 完成后回填 `issues/fix_bus_issues.csv`：
   - `Fix_Status`
   - `Verify_Command`
@@ -83,6 +105,7 @@ aiws validate . --stamp
 
 输出要求：
 - `Change_ID:` `<change-id>`
+- `Change context:` `<当前分支或 worktree 路径>`
 - `CSV:` `issues/fix_bus_issues.csv` 中对应 `Bug_ID` 行的关键字段
 - `Evidence:` `changes/<change-id>/bug/zentao-bug-<bug-id>.md` + 图片目录
 - `Verify:` 实际运行命令与结果（未运行不声称已运行）

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

@@ -18,7 +18,31 @@ description: 提交（当前分支可直提；submodule 感知；先审计/门
 - 不自动 push
 - 不写入任何 secrets
 - 检测到 submodule 有未提交改动时，不允许直接提交 superproject（先处理 submodule）
-- commit message 默认使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
+- commit message 优先使用中文（命令/路径/代码标识符保持原样不翻译）；格式建议：`<类型>: <简述>`（例如 `修复: 登录页空指针`、`功能: 新增 submodule targets 校验`、`重构: 提取共享脚本`）
+- 若启用了 `.githooks/commit-msg`：默认会提示优先中文；只有在 `git config aiws.commitMessagePolicy strict` 时才会拒绝全英文首行（`Merge/Revert/fixup!/squash!` 例外）
+
+阶段定位：
+- commit gate；负责在提交前收敛 review、validate 和 message 确认，不允许跳过 hooks。
+
+必需输入：
+- 当前分支与 staged diff
+- `$ws-review` 生成的审计证据
+- `aiws validate . --stamp` 生成的校验证据
+- 用户确认后的 commit message
+
+必需输出：
+- `证据（Evidence）:` review 文件路径 + validate stamp 路径
+- `上下文（Context）:` 当前分支、submodule 检测结果、阻断原因（若有）
+- `提交信息（Commit）:` 最终提交信息
+
+阻断条件：
+- 没有 staged changes
+- submodule 工作区不干净或 detached 处理不完整
+- 用户未确认 commit message
+- validate 失败
+
+完成判定：
+- 提交已完成，证据路径明确，且没有通过 `--no-verify` 绕过门禁。
 
 执行步骤（建议）：
 1) 运行 `$ws-preflight`（确保真值文件就绪）。
@@ -87,6 +111,7 @@ git diff --staged --submodule=short
    - 类型参考：`功能` / `修复` / `重构` / `文档` / `测试` / `构建` / `杂项`
    - 简述用一句话概括本次改动的"为什么"而非"改了什么"
    - 命令/路径/代码标识符保持原样不翻译
+   - 若用户给出全英文 message：优先改写成中文；若用户明确要求保留英文，也可以提交（但 strict 模式下会被 hook 拒绝）
 10) 执行提交（不带 `--no-verify`）：
 ```bash
 git commit -m "<message>"

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

@@ -0,0 +1,75 @@
+---
+name: ws-delegate
+description: 原生多 agent 委托入口（Codex 优先；先定义角色/边界/工件/降级，再决定是否委托）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 治理约束下，只有在任务已绑定且 scope 可控时，才使用当前工具的原生多 agent / sub-agent 能力；否则明确降级为单 agent + 协同工件模式。
+
+阶段定位：
+- implementation / review 的辅助入口；它不是独立 workflow 阶段，也不能绕过 `ws-plan`、`ws-dev`、`ws-review`、`ws-finish`。
+
+必需输入：
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- delegation contract：`packages/spec/docs/workflow-delegation-contracts.md`
+- 当前任务已绑定 `Req_ID` / change / Verify 入口
+- 拟委托子任务的角色划分、读写边界、artifact 目标与 fallback
+
+必需输出：
+- `Delegation Plan:` 逐项写清 role / task / readScope / writeScope / artifactTargets / fallback
+- `Execution Mode:` 明确是 `native multi-agent` 还是 `fallback single-agent`
+- `Evidence:` 委托产物路径（`analysis/` / `patches/` / `review/` / `evidence/`）
+- `Next:` 收敛后应回到 `ws-dev`、`ws-review`、`ws-commit` 或 `ws-finish`
+
+阻断条件：
+- 无法绑定到 `Req_ID` / change / Verify
+- 没有明确的 `writeScope` / `artifactTargets`
+- 当前工具缺少稳定 native delegation 能力，且你又不能接受降级执行
+- 任务规模太小，引入委托只会增加复杂度
+
+完成判定：
+- 已经明确本次是否适合委托
+- 若适合：delegation plan 已声明并执行，产物回收到 AIWS 约定路径
+- 若不适合：已明确降级原因，并回到单 agent 流程继续执行
+
+步骤（建议）：
+1) 先读取真值文件与 `packages/spec/docs/workflow-delegation-contracts.md`，确认这不是“为了多 agent 而多 agent”。
+2) 判断当前任务是否真的需要委托：
+   - 需要并行的只读探索
+   - 需要把实现与审查拆开
+   - 有明确、互不重叠的写入边界
+   - 委托收益大于协调成本
+3) 先写 `Delegation Plan:`，至少包含：
+   - `role`
+   - `task`
+   - `readScope`
+   - `writeScope`
+   - `artifactTargets`
+   - `fallback`
+4) 若当前环境支持原生多 agent：
+   - 优先把探索型工作交给 `explorer`
+   - 只把显式授权的文件范围交给 `worker`
+   - 至少保留一个独立 `reviewer`
+   - 由主 agent / `integrator` 统一收敛结果
+5) 若当前环境不支持，或无法稳定约束 scope：
+   - 明确输出 `Execution Mode: fallback single-agent`
+   - 仍按 AIWS 协同工件约定执行：
+     - `changes/<id>/analysis/`
+     - `changes/<id>/patches/`
+     - `changes/<id>/review/`
+     - `changes/<id>/evidence/`
+6) 不论是否启用原生多 agent，都不要跳过：
+   - 需求归因
+   - 验证命令
+   - review convergence
+   - finish / handoff gate
+
+Codex 优先说明：
+- 若当前环境支持原生多 agent / sub-agent，就按 delegation contract 显式拆 role 与 scope。
+- 若不支持，或你无法保证写边界，直接降级，不临时发明新的 runtime/controller。
+
+安全：
+- 不把 `aiws` 变成统一 orchestrator。
+- 不让 delegated agent 越权写未授权文件。
+- 不把 `patches/` 视为“已合并代码”。

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

@@ -25,11 +25,34 @@ description: 交付（submodules + superproject 分步提交，并安全合并
    - 该 repo 的 `git diff --staged`
    并让用户确认 commit message（每个 repo 单独确认）。
 
+阶段定位：
+- delivery 阶段；负责在多 repo / submodule 场景下完成顺序提交、证据收敛和最终合并前准备。
+
+必需输入：
+- 当前 `change/<change-id>` 上下文
+- 若存在 submodule：`.gitmodules` + `changes/<change-id>/submodules.targets`
+- 各 repo 当前状态与 staged diff
+
+必需输出：
+- `Submodules:` 每个 submodule 的提交摘要
+- `Superproject:` 主仓库提交摘要
+- `Evidence:` validate stamp 与持久证据路径
+- `Next:` 进入 `$ws-finish` 或 `aiws change finish`
+
+阻断条件：
+- 不在正确的 change 上下文
+- submodule branch / targets 真值不完整
+- 任一 repo 未确认 commit message 或存在未处理冲突
+
+完成判定：
+- submodule 与 superproject 提交都已完成，证据已收敛，且可以安全进入 finish 阶段。
+
 建议流程（按顺序）：
 
 ## 0) submodule branch 真值检查（减少 detached 与人为差异）
 如果存在 `.gitmodules` 但缺少 `submodule.<name>.branch`，先运行 `$ws-submodule-setup` 并提交 `.gitmodules`，否则后续 `aiws validate .` 会失败，且 `ws-pull/ws-finish` 无法确定性工作。
-> 说明：若同一 superproject 分支内存在“多渠道 submodule 目标分支”的交付需求，可在 `changes/<change-id>/submodules.targets` 额外声明本次 change 的目标分支；交付时会优先使用该文件（不改变 `.gitmodules` 的团队默认真值）。
+> 说明：若同一 superproject 分支内存在多渠道 submodule 目标分支的交付需求，可在 `changes/<change-id>/submodules.targets` 额外声明本次 change 的目标分支；交付时会优先使用该文件（不改变 `.gitmodules` 的团队默认真值）。
+> 生成该文件时，可以按当前状态做默认预填，但必须显式说明来源并让用户确认：detached HEAD 默认建议取 `.gitmodules` 声明分支；已附着在某个本地分支时默认建议取当前分支；finish/push 最终只认 `submodules.targets`。
 ```bash
 if [[ -f .gitmodules ]]; then
   missing=0
@@ -85,15 +108,29 @@ sub_path="<path>"
 git -C "$sub_path" branch --show-current
 git -C "$sub_path" status --porcelain
 ```
-2) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
+2) 先确定该 submodule 的目标分支来源，并显式说明给用户：
+   - `branch --show-current` 非空：默认建议用当前分支
+   - `branch --show-current` 为空（detached HEAD）：默认建议用 `.gitmodules` 的 `submodule.<name>.branch`
+   - 若建议值与 `changes/<change-id>/submodules.targets` 已落盘值不一致：以 `submodules.targets` 为准，并先提示差异
+3) 若 submodule 处于 detached HEAD（`branch --show-current` 为空）：
    - 说明：这通常是因为 superproject 的 gitlink checkout（例如 `git submodule update`）导致 detached。
-   - 不要直接切 `change/<change-id>` / `main` / `master` 来“解 detached”。
+   - 不要直接切 `change/<change-id>` / `main` / `master` 来解 detached。
    - 若你要在该 submodule 里提交：先按目标分支挂到 pin 分支 `aiws/pin/<target-branch>`，再在其上提交：
      - 目标分支真值优先级：`changes/<change-id>/submodules.targets`（若存在）> `.gitmodules submodule.<name>.branch`
 ```bash
 change_id="<change-id>"
 targets="changes/${change_id}/submodules.targets"
-base_branch="$(git branch --show-current)"
+sub_name="$(git config --file .gitmodules --get-regexp '^submodule\\..*\\.path$' 2>/dev/null | awk -v p="${sub_path}" '$2==p { name=$1; sub(/^submodule\\./,"",name); sub(/\\.path$/,"",name); print name; exit }')"
+base_branch="$(python3 - <<'PY'
+import json, pathlib
+change_id = "<change-id>"
+meta = pathlib.Path("changes") / change_id / ".ws-change.json"
+data = json.loads(meta.read_text(encoding="utf-8"))
+print((data.get("base_branch") or "").strip())
+PY
+)"
+test -n "${sub_name}"
+test -n "${base_branch}"
 
 source tools/ws_resolve_sub_target.sh
 ws_resolve_sub_target "${sub_path}" "${sub_name}" "${targets}" "${base_branch}" || exit 2
@@ -109,18 +146,18 @@ git -C "$sub_path" checkout -B "aiws/pin/${target_branch}" HEAD
 git -C "$sub_path" branch --set-upstream-to "${remote}/${target_branch}" "aiws/pin/${target_branch}" >/dev/null 2>&1 || true
 ```
    - 若 `origin/<target-branch>` 不存在，或用户明确不想使用 pin 分支：停止，解释风险（提交可能不可追溯/难以推送）。
-3) 选择性 staging（默认用 `-p` 更安全）：
+4) 选择性 staging（默认用 `-p` 更安全）：
 ```bash
 git -C "$sub_path" add -p
 git -C "$sub_path" diff --staged --stat
 git -C "$sub_path" diff --staged
 ```
-4) AI 生成该 submodule 的 commit message（标题+可选 body），并让用户确认（每个 repo 单独确认）。
-5) 执行提交（不带 `--no-verify`）：
+5) AI 生成该 submodule 的 commit message（标题+可选 body），并让用户确认（每个 repo 单独确认）。
+6) 执行提交（不带 `--no-verify`）：
 ```bash
 git -C "$sub_path" commit -m "<message>"
 ```
-6) 若该 submodule 没有 staged changes：跳过（不要硬提交空 commit）。
+7) 若该 submodule 没有 staged changes：跳过（不要硬提交空 commit）。
 
 ## C) 提交 superproject（更新 gitlinks + 自身改动 + changes 工件）
 1) 先检查 submodule 指针差异（gitlinks）：
@@ -138,7 +175,7 @@ git add -p
 git diff --staged --stat
 git diff --staged
 ```
-3) AI 生成 superproject 的 commit message（应包含 “bump submodule <name> -> <sha>” 等关键信息），并让用户确认。
+3) AI 生成 superproject 的 commit message（应包含 `bump submodule <name> -> <sha>` 等关键信息），并让用户确认。
 4) 提交：
 ```bash
 git commit -m "<message>"