@aipper/aiws-spec 0.0.26 → 0.0.28

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/docs/workflow-router-rules.json

@@ -16,7 +16,7 @@
     "kind": "skill",
     "summary": "默认 workflow bootstrap/router：先读真值，再把任务路由到正确的 `ws-*` 入口。",
     "outputContract": [
-      "Root / Found / Missing",
+      "Root / Found / Missing / Intent status",
       "Task intent / Binding status / Route",
       "Why / Next"
     ]
@@ -32,6 +32,11 @@
       "action": "判断当前任务是在做需求变更、实现、评审、收尾还是交接。",
       "why": "先判 workflow，再决定进入哪个 skill；不能一开始就跳进实现。"
     },
+    {
+      "step": "check_intent_freeze",
+      "action": "判断需求是否已经冻结；若存在多条待确认问题或需要多轮沟通，先进入 intake 阶段。",
+      "why": "中大型需求在计划前往往需要多轮澄清；router 应该先把问题冻结，而不是把沟通负担全部塞给 `ws-plan`。"
+    },
     {
       "step": "check_binding",
       "action": "检查任务是否具备 `Req_ID` / `Problem_ID` / change 上下文 / Verify 入口等最小绑定。",
@@ -60,6 +65,14 @@
       "gate": "必须先问 1-3 个关键澄清问题，然后停止。",
       "rationale": "router 的职责是阻断模糊任务，而不是用猜测替代路由。"
     },
+    {
+      "id": "needs_intake",
+      "intent": "需求存在多条待确认问题，尚未冻结",
+      "match": "任务是新需求或中大型变更；目标方向大致明确，但存在多条待确认问题、需要逐条沟通，或用户明确要求先多轮澄清再进入计划。",
+      "routeTo": "ws-intake",
+      "gate": "先逐条澄清并冻结结论；未形成 intake 草案前不进入 `ws-plan`。",
+      "rationale": "`ws-intake` 负责把多轮需求沟通收敛为轻量草案，避免 `ws-plan` 同时承担反复澄清与正式计划落盘。"
+    },
     {
       "id": "requirements_change",
       "intent": "需求/验收/合同变更",
@@ -95,10 +108,10 @@
     {
       "id": "plan_first",
       "intent": "中大型实现或需要建立 change 上下文",
-      "match": "任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，或当前还没有计划工件。",
+      "match": "任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，且需求已经冻结或已有可消费的 intake 草案。",
       "routeTo": "ws-plan",
       "gate": "plan 过 gate 前不进入 `ws-dev`。",
-      "rationale": "medium/complex 任务必须先生成可落盘计划，避免 router 直接跳进实现。"
+      "rationale": "medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。"
     },
     {
       "id": "direct_implementation",
@@ -126,6 +139,14 @@
       "expectedRoute": "clarify",
       "why": "这种场景必须先澄清意图和绑定，不能猜测实现。"
     },
+    {
+      "id": "case_needs_intake",
+      "scenario": "任务方向大致明确，但存在多条待确认问题，需要逐条沟通后再计划。",
+      "request": "做一个新的 change intake 流程，我想先一条一条把需求和边界聊清楚，再进入正式计划。",
+      "expectedRuleId": "needs_intake",
+      "expectedRoute": "ws-intake",
+      "why": "这类需求不是完全不清晰，但还没有冻结，适合先走 intake。"
+    },
     {
       "id": "case_requirements_change",
       "scenario": "任务要修改 REQUIREMENTS、requirements CSV 或 workflow 真值。",
@@ -179,13 +200,15 @@
     "用户只说“继续”“优化一下”“看一下”，但没有明确目标对象或当前阶段。",
     "无法把任务绑定到 `Req_ID` / `Problem_ID` / change 上下文。",
     "没有可复现验证入口，且无法从 `AI_WORKSPACE.md` 推断。",
-    "当前描述同时包含需求变更、实现和收尾，但没有明确优先级。"
+    "当前描述同时包含需求变更、实现和收尾，但没有明确优先级。",
+    "同一个任务包含多条待确认问题，且用户希望逐条、多轮沟通。"
   ],
   "universalRules": [
     "router 自己不是实现阶段；先判定 workflow，再进入具体 `ws-*` skill。",
     "除缺失真值场景外，router 至少要给出一个明确的 `Route:` 结果或明确的澄清问题。",
     "当 `routeTo=clarify` 时，必须停止，不直接写代码。",
-    "当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` 时，后续行为必须遵循对应 skill 契约。",
+    "当 `routeTo=ws-intake` 时，必须先逐条冻结问题并产出 intake 草案；不要跳过到 `ws-plan`。",
+    "当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` / `ws-intake` 时，后续行为必须遵循对应 skill 契约。",
     "任何 route 都不能绕过 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。"
   ],
   "notes": [

package/docs/workflow-router-rules.md

@@ -22,7 +22,7 @@ router 在做任何 workflow 判断前，必须先读取：
 - kind: `skill`
 - summary: 默认 workflow bootstrap/router：先读真值，再把任务路由到正确的 `ws-*` 入口。
 - output contract:
-  - Root / Found / Missing
+  - Root / Found / Missing / Intent status
   - Task intent / Binding status / Route
   - Why / Next
 
@@ -32,6 +32,7 @@ router 在做任何 workflow 判断前，必须先读取：
 | --- | --- | --- |
 | `read_truths` | 先定位项目根，并读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。 | router 不能绕过真值文件，否则会把 workflow 判断建立在会话猜测上。 |
 | `classify_intent` | 判断当前任务是在做需求变更、实现、评审、收尾还是交接。 | 先判 workflow，再决定进入哪个 skill；不能一开始就跳进实现。 |
+| `check_intent_freeze` | 判断需求是否已经冻结；若存在多条待确认问题或需要多轮沟通，先进入 intake 阶段。 | 中大型需求在计划前往往需要多轮澄清；router 应该先把问题冻结，而不是把沟通负担全部塞给 `ws-plan`。 |
 | `check_binding` | 检查任务是否具备 `Req_ID` / `Problem_ID` / change 上下文 / Verify 入口等最小绑定。 | 缺失绑定时必须阻断或回退到 `ws-plan`，避免无归因实现。 |
 | `route_or_clarify` | 给出单一路由结果；若意图不明确，则先问关键澄清问题并停止。 | default-routed workflow 的关键不是自动执行，而是避免模糊任务直接进入实现。 |
 
@@ -41,11 +42,12 @@ router 在做任何 workflow 判断前，必须先读取：
 | --- | --- | --- | --- | --- | --- |
 | `missing_truths` | 仓库未初始化或真值缺失 | 缺失任一真值文件，或无法确定项目根目录。 | `ws-preflight` | 先补齐真值或确认项目根，不进入实现。 | 所有后续 skill 都依赖真值文件；缺失时 router 只能回退到 preflight/init 路径。 |
 | `unclear_intent` | 用户目标、归因或验收不清晰 | 无法明确当前是需求变更、实现、评审、finish 还是 handoff；或无法明确 `Req_ID` / `Problem_ID` / Verify。 | `clarify` | 必须先问 1-3 个关键澄清问题，然后停止。 | router 的职责是阻断模糊任务，而不是用猜测替代路由。 |
+| `needs_intake` | 需求存在多条待确认问题，尚未冻结 | 任务是新需求或中大型变更；目标方向大致明确，但存在多条待确认问题、需要逐条沟通，或用户明确要求先多轮澄清再进入计划。 | `ws-intake` | 先逐条澄清并冻结结论；未形成 intake 草案前不进入 `ws-plan`。 | `ws-intake` 负责把多轮需求沟通收敛为轻量草案，避免 `ws-plan` 同时承担反复澄清与正式计划落盘。 |
 | `requirements_change` | 需求/验收/合同变更 | 任务涉及 `REQUIREMENTS.md`、requirements CSV、spec contract、验收标准或 workflow 真值变更。 | `ws-req-review` | 先做需求评审，再决定是否进入 `ws-plan` / `ws-dev`。 | 需求真值变更必须先过 review，不能直接编码。 |
 | `review_request` | 审计/评审/找风险 | 用户明确要求 review、audit、评审、找 bug、识别风险或检查回归。 | `ws-review` | 先给 findings；除非用户另行要求，不先改代码。 | 评审任务与实现任务的输出契约不同，必须优先走 review。 |
 | `finish_request` | 收尾/合并/推送/cleanup | 用户要求 finish、merge、push、收尾、交付完成、清理 worktree 或 branch。 | `ws-finish` | 必须满足 finish gate，不能跳过 validate / push / cleanup。 | finish 是独立治理阶段，不能与普通实现混用。 |
 | `handoff_request` | 交接/归档总结 | 用户要求 handoff、交接说明、archive summary、会话总结或接力说明。 | `ws-handoff` | 先确认 change 已 finish 或 archive 上下文存在。 | handoff 依赖已有证据与归档上下文，不应在实现前触发。 |
-| `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，或当前还没有计划工件。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | medium/complex 任务必须先生成可落盘计划，避免 router 直接跳进实现。 |
+| `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，且需求已经冻结或已有可消费的 intake 草案。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。 |
 | `direct_implementation` | 小步实现/修复/配置调整 | 目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。 |
 
 ## Route Cases
@@ -54,6 +56,7 @@ router 在做任何 workflow 判断前，必须先读取：
 | --- | --- | --- | --- | --- | --- |
 | `case_missing_truths` | 仓库未初始化或真值缺失时，不能直接开始实现。 | 在一个还没执行 aiws init 的仓库里继续开发这个功能。 | `missing_truths` | `ws-preflight` | 缺失真值文件时只能先补齐 preflight/init 路径。 |
 | `case_unclear_continue` | 用户只说继续，但没有明确当前 change、归因或验证入口。 | 继续。 | `unclear_intent` | `clarify` | 这种场景必须先澄清意图和绑定，不能猜测实现。 |
+| `case_needs_intake` | 任务方向大致明确，但存在多条待确认问题，需要逐条沟通后再计划。 | 做一个新的 change intake 流程，我想先一条一条把需求和边界聊清楚，再进入正式计划。 | `needs_intake` | `ws-intake` | 这类需求不是完全不清晰，但还没有冻结，适合先走 intake。 |
 | `case_requirements_change` | 任务要修改 REQUIREMENTS、requirements CSV 或 workflow 真值。 | 更新 REQUIREMENTS.md 和 requirements/requirements-issues.csv，补充验收标准。 | `requirements_change` | `ws-req-review` | 需求真值变更必须先做需求评审。 |
 | `case_review_request` | 用户明确要求 review、审计、找风险或检查回归。 | review 这批改动，先给我风险和回归点，不要先改代码。 | `review_request` | `ws-review` | 评审任务的输出契约是 findings，不应直接进入实现。 |
 | `case_finish_request` | 用户要求合并、push、cleanup 或 finish 当前 change。 | 把 demo-change finish 掉并 push，顺便 cleanup worktree。 | `finish_request` | `ws-finish` | finish 是独立治理阶段，必须先走 finish gate。 |
@@ -67,13 +70,15 @@ router 在做任何 workflow 判断前，必须先读取：
 - 无法把任务绑定到 `Req_ID` / `Problem_ID` / change 上下文。
 - 没有可复现验证入口，且无法从 `AI_WORKSPACE.md` 推断。
 - 当前描述同时包含需求变更、实现和收尾，但没有明确优先级。
+- 同一个任务包含多条待确认问题，且用户希望逐条、多轮沟通。
 
 ## 统一规则
 
 - router 自己不是实现阶段；先判定 workflow，再进入具体 `ws-*` skill。
 - 除缺失真值场景外，router 至少要给出一个明确的 `Route:` 结果或明确的澄清问题。
 - 当 `routeTo=clarify` 时，必须停止，不直接写代码。
-- 当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` 时，后续行为必须遵循对应 skill 契约。
+- 当 `routeTo=ws-intake` 时，必须先逐条冻结问题并产出 intake 草案；不要跳过到 `ws-plan`。
+- 当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` / `ws-intake` 时，后续行为必须遵循对应 skill 契约。
 - 任何 route 都不能绕过 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
 
 ## 说明

package/docs/workflow-stage-contracts.json

@@ -8,6 +8,7 @@
   ],
   "standardChain": [
     "ws-preflight",
+    "ws-intake",
     "ws-plan",
     "ws-plan-verify",
     "ws-dev",
@@ -30,21 +31,29 @@
       "requiredInputs": "项目根；AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md",
       "requiredOutputs": "Root / Found / Missing / Key rules / Next",
       "blockers": "无法确定项目根；真值缺失",
-      "next": "ws-plan 或 ws-dev"
+      "next": "ws-intake / ws-plan 或 ws-dev"
+    },
+    {
+      "stage": "ws-intake",
+      "goal": "逐条澄清问题并冻结需求结论，产出可被计划阶段消费的草案",
+      "requiredInputs": "任务描述；真值文件；当前已知绑定与约束；若已存在则读取最新 intake 草案",
+      "requiredOutputs": "plan/*.intake.md；Open Questions / Resolved Questions / Frozen Decisions / Draft Scope / Draft Verify / Ready for ws-plan",
+      "blockers": "任务目标完全无法识别；关键真值缺失；无法把当前问题收敛为 frozen 或 deferred",
+      "next": "继续 intake 或进入 ws-plan"
     },
     {
       "stage": "ws-plan",
       "goal": "建立 change 绑定并落盘计划",
-      "requiredInputs": "任务描述；真值文件；proposal.md（若存在）",
+      "requiredInputs": "任务描述；真值文件；proposal.md（若存在）；若已有则优先消费最新 intake 草案",
       "requiredOutputs": "plan/...；Bindings；Verify；Risks；Evidence；Next",
-      "blockers": "绑定不清；dirty 工作区无法安全建 context；无法写盘",
+      "blockers": "绑定不清；需求尚未冻结；dirty 工作区无法安全建 context；无法写盘",
       "next": "ws-plan-verify"
     },
     {
       "stage": "ws-plan-verify",
-      "goal": "检查计划是否满足严格契约",
+      "goal": "检查计划是否满足严格契约，并做多视角方案审查",
       "requiredInputs": "plan/...；proposal.md；当前 change",
-      "requiredOutputs": "Quality gate；Fix list；可执行最小计划摘要",
+      "requiredOutputs": "Quality gate；Perspective findings；Fix list；可执行最小计划摘要",
       "blockers": "strict 校验失败；无法定位 change",
       "next": "修计划后重跑或进入 ws-dev"
     },

package/docs/workflow-stage-contracts.md

@@ -12,7 +12,7 @@
 
 默认链路：
 
-`ws-preflight` -> `ws-plan` -> `ws-plan-verify` -> `ws-dev` -> `ws-review` -> `ws-commit` -> `ws-deliver` -> `ws-finish` -> `ws-handoff`
+`ws-preflight` -> `ws-intake` -> `ws-plan` -> `ws-plan-verify` -> `ws-dev` -> `ws-review` -> `ws-commit` -> `ws-deliver` -> `ws-finish` -> `ws-handoff`
 
 说明：
 - ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。
@@ -24,9 +24,10 @@
 
 | 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-preflight` | 对齐真值文件与协作约束 | 项目根；AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md | Root / Found / Missing / Key rules / Next | 无法确定项目根；真值缺失 | ws-intake / ws-plan 或 ws-dev |
+| `ws-intake` | 逐条澄清问题并冻结需求结论，产出可被计划阶段消费的草案 | 任务描述；真值文件；当前已知绑定与约束；若已存在则读取最新 intake 草案 | plan/*.intake.md；Open Questions / Resolved Questions / Frozen Decisions / Draft Scope / Draft Verify / Ready for ws-plan | 任务目标完全无法识别；关键真值缺失；无法把当前问题收敛为 frozen 或 deferred | 继续 intake 或进入 ws-plan |
+| `ws-plan` | 建立 change 绑定并落盘计划 | 任务描述；真值文件；proposal.md（若存在）；若已有则优先消费最新 intake 草案 | plan/...；Bindings；Verify；Risks；Evidence；Next | 绑定不清；需求尚未冻结；dirty 工作区无法安全建 context；无法写盘 | ws-plan-verify |
+| `ws-plan-verify` | 检查计划是否满足严格契约，并做多视角方案审查 | plan/...；proposal.md；当前 change | Quality gate；Perspective findings；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 |

package/package.json

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

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

@@ -9,6 +9,7 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
 - 作为默认入口，先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
 - 先判定当前任务属于哪个 workflow，再进入具体 `ws-*` skill
 - 若任务意图、归因或验证入口不明确：先澄清，不直接进入实现
+- 若任务方向大致明确但仍有多条待确认问题：先进入 `$ws-intake` 冻结需求，再进入计划
 
 阶段定位：
 - bootstrap/router 阶段；负责 workflow 分流，而不是直接完成实现。
@@ -23,6 +24,7 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
 必需输出：
 - `Root:` 当前项目根
 - `Found:` 实际读取到的真值文件
+- `Intent status:` 当前需求是否已经冻结
 - `Task intent:` 当前任务意图分类
 - `Binding:` `Req_ID` / `Problem_ID` / change 上下文是否清晰
 - `Route:` 选中的下一步 skill
@@ -52,14 +54,22 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
    - 评审/审计/找风险：`$ws-review`
    - finish / merge / push / cleanup：`$ws-finish`
    - handoff / archive summary：`$ws-handoff`
-   - 中大型实现、需要方案、需要 change/worktree：`$ws-plan`
+   - 新需求或中大型变更，且存在多条待确认问题 / 用户要求逐条多轮沟通：`$ws-intake`
+   - 中大型实现、需要方案、需要 change/worktree，且需求已经冻结：`$ws-plan`
    - 小步明确实现/修复/配置调整：`$ws-dev`（若是 simple/local 单点修复，且用户明确希望走轻量入口，可显式进入 `$ws-dev-lite`）
 4) 若任务意图或归因不明确：
    - 只问 1-3 个关键澄清问题
    - 明确写出缺的是什么：意图、`Req_ID` / `Problem_ID`、verify、change 上下文
    - 然后停止；不要直接写代码
-5) 若已确定 route：
+5) 若任务方向大致明确，但同一个任务包含多条待确认问题、范围尚未冻结，或用户明确说“想一条一条聊清楚再计划”：
+   - 输出 `Intent status: not_frozen`
+   - `Route: $ws-intake`
+   - `Why:` 说明当前不适合直接进入 `$ws-plan`
+   - `Next:` 进入 `$ws-intake`
+   - 然后在同一轮中继续遵循 `$ws-intake` 的契约
+6) 若已确定 route：
    - 先输出：
+     - `Intent status:`
      - `Task intent:`
      - `Binding:`
      - `Route:`
@@ -69,17 +79,19 @@ description: 默认 workflow bootstrap/router：先读真值，再路由到正
    - 否则：
      - `Next:` 进入对应主 skill
    - 然后在同一轮中继续遵循对应 skill 的契约
-6) 路由约束：
+7) 路由约束：
    - router 自己不是实现阶段；不要在给出 route 之前直接改代码
    - 除非用户只想听判断结果，否则给出 route 后应继续按对应 skill 的规则推进
    - 一次只选择一个主 route；不要把 `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` 混成并行终态
-7) 若执行过程中发现复杂度升高：
+8) 若执行过程中发现复杂度升高：
    - 从 `$ws-dev` 回退到 `$ws-plan`
+   - 从 `$ws-plan` 回退到 `$ws-intake`（当发现需求并未冻结）
    - 从 `$ws-finish` 回退到前置门禁而不是硬推完成
 
 输出模板：
 - `Root:` <path>
 - `Found:` <files>
+- `Intent status:` <frozen / not_frozen>
 - `Task intent:` <分类>
 - `Binding:` <清晰 / 缺失项>
 - `Route:` <$ws-... 或 clarify>

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/.agents/skills/ws-intake/SKILL.md

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

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

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

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

@@ -8,6 +8,7 @@ description: 计划质检（执行前检查计划是否过长/跑偏，并给出
 目标：
 - 在进入 `$ws-dev` 前，对 `plan/...` 与 `changes/<change-id>/proposal.md` 做一次“硬约束”质检
 - 避免计划过长、步骤不够具体、验证不可复现、与需求合同绑定不一致
+- 显式做一次多视角方案审查，避免计划“格式合格但方向跑偏”
 - 失败时只给最小修正项，修完后再进入实现
 
 适用时机：
@@ -24,6 +25,7 @@ description: 计划质检（执行前检查计划是否过长/跑偏，并给出
 
 必需输出：
 - `Quality gate:` pass/fail
+- `Perspective findings:` 多视角审查结论
 - `Fix list:` 最小修正项
 - `Next:` 通过则 `$ws-dev`，未通过则继续修正并复跑
 
@@ -52,10 +54,17 @@ fi
 4) 若失败：按报错逐条修正 `proposal.md` / `plan/...`，优先级如下：
    - 先修绑定：`Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
    - 再修计划质量：必需章节、步骤数量、步骤具体性、验证命令与预期
-5) 复跑 strict 校验，直到通过。
-6) 输出“可执行最小计划摘要”（3-8 步），再进入 `$ws-dev`。
+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