@aipper/aiws-spec 0.0.28 → 0.0.30

package/docs/workflow-governance-rules.json

@@ -1,6 +1,29 @@
 {
-  "version": 1,
+  "version": 2,
   "description": "Machine-readable governance inference rules for aiws change status/next/dashboard.",
+  "workflowStateSuffix": {
+    "description": "每轮注入的 workflow state 面包屑后缀约定。格式: [workflow-state:session:{state}]",
+    "values": ["intake", "planning", "dev", "review", "deliver", "completed"],
+    "stateSuffixMap": {
+      "intake": "[workflow-state:session:intake]",
+      "planning": "[workflow-state:session:planning]",
+      "dev": "[workflow-state:session:dev]",
+      "review": "[workflow-state:session:review]",
+      "deliver": "[workflow-state:session:deliver]",
+      "completed": "[workflow-state:session:completed]"
+    }
+  },
+  "stateEnum": {
+    "values": ["intake", "planning", "dev", "review", "deliver", "completed"],
+    "stageMapping": {
+      "intake": ["ws-intake"],
+      "planning": ["ws-plan", "ws-plan-verify"],
+      "dev": ["ws-dev", "ws-dev-lite"],
+      "review": ["ws-review", "ws-spec-review", "ws-quality-review", "ws-commit"],
+      "deliver": ["ws-deliver", "ws-finish", "ws-verify-before-complete"],
+      "completed": ["ws-handoff"]
+    }
+  },
   "governanceRules": [
     {
       "id": "finish_resume_required",
@@ -70,14 +93,14 @@
       "when": { "signal": "git_conflicted", "gt": 0 },
       "currentStage": "ws-commit",
       "recommendedStage": "ws-commit",
-      "rationale": "review exists but the change worktree still has merge conflicts"
+      "rationale": "review exists but the change branch still has merge conflicts"
     },
     {
       "id": "review_dirty",
       "when": { "signal": "git_total", "gt": 0 },
       "currentStage": "ws-commit",
       "recommendedStage": "ws-commit",
-      "rationale": "review exists but the change worktree is still dirty"
+      "rationale": "review exists but the change branch is still dirty"
     },
     {
       "id": "deliver_finish_gate_pending_submodules",
@@ -181,11 +204,29 @@
     },
     {
       "id": "guidance_review",
-      "when": { "signal": "governance_current_stage", "eq": "ws-review" },
+      "when": {
+        "all": [
+          { "signal": "governance_current_stage", "eq": "ws-review" },
+          { "signal": "review_effective_count", "eq": 0 }
+        ]
+      },
       "lines": [
         "进入审计：在 AI 工具中运行 `$ws-review`（形成 review 结论后再进入提交/交付）"
       ]
     },
+    {
+      "id": "guidance_review_dual_gate",
+      "when": {
+        "all": [
+          { "signal": "governance_current_stage", "eq": "ws-review" },
+          { "signal": "review_effective_count", "gt": 0 },
+          { "signal": "dual_review_missing_count", "gt": 0 }
+        ]
+      },
+      "lines": [
+        "已有通用 review，但 dual review gate 仍未完成：继续补齐 `$ws-spec-review` / `$ws-quality-review`，不要把 `codex-review.md` 误当成 finish gate"
+      ]
+    },
     {
       "id": "guidance_review_spec_missing",
       "when": { "signal": "spec_review_ready", "falsy": true },
@@ -266,7 +307,7 @@
       "id": "guidance_finish_cleanup_pending",
       "when": { "signal": "governance_rule_id", "eq": "finish_cleanup_pending" },
       "lines": [
-        "push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 worktree 后重跑 `$ws-finish`"
+        "push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 change 分支后重跑 `$ws-finish`"
       ]
     },
     {
@@ -280,7 +321,7 @@
       "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`）"
+        "finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支上运行 `aiws validate . --stamp`）"
       ]
     },
     {

package/docs/workflow-governance-rules.md

@@ -9,10 +9,10 @@
 
 ## 概览
 
-- version: `1`
+- version: `2`
 - description: Machine-readable governance inference rules for aiws change status/next/dashboard.
 - governance rules: 17
-- guidance rules: 17
+- guidance rules: 18
 
 ## 阶段推断规则
 
@@ -27,8 +27,8 @@
 | `finish_local` | `finish_state` == `local` | `ws-finish` | `ws-finish` | finish started locally but is not fully completed yet |
 | `review_missing` | `review_effective_count` == `0` | `ws-review` | `ws-review` | deliver-ready state has no review artifact yet |
 | `dual_review_incomplete` | `dual_review_missing_count` > 0 | `ws-review` | `ws-review` | dual review gate incomplete (spec={spec_review_status}, quality={quality_review_status}) |
-| `review_conflicted` | `git_conflicted` > 0 | `ws-commit` | `ws-commit` | review exists but the change worktree still has merge conflicts |
-| `review_dirty` | `git_total` > 0 | `ws-commit` | `ws-commit` | review exists but the change worktree is still dirty |
+| `review_conflicted` | `git_conflicted` > 0 | `ws-commit` | `ws-commit` | review exists but the change branch still has merge conflicts |
+| `review_dirty` | `git_total` > 0 | `ws-commit` | `ws-commit` | review exists but the change branch is still dirty |
 | `deliver_finish_gate_pending_submodules` | (`repo_submodules` > 0) AND ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` > 0) | `ws-deliver` | `ws-deliver` | delivery evidence exists but finish gate is incomplete (missing={finish_gate_missing_count}) |
 | `deliver_finish_gate_pending` | ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` > 0) | `ws-deliver` | `ws-deliver` | delivery evidence exists but finish gate is incomplete (missing={finish_gate_missing_count}) |
 | `deliver_evidence_converged_submodules` | (`repo_submodules` > 0) AND ((`evidence_persistent_count` > 0) OR (`lifecycle_evidence_runs` > 0)) AND (`finish_gate_missing_count` == `0`) | `ws-deliver` | `ws-finish` | delivery evidence and finish gate are converged; next step is submodule-aware finish |
@@ -42,7 +42,8 @@
 | --- | --- | --- |
 | `guidance_plan_verify` | `governance_current_stage` == `ws-plan-verify` | 先修复 strict blockers，再复跑 `aiws change validate <id> --strict` |
 | `guidance_dev` | `governance_current_stage` == `ws-dev` | 继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证） |
-| `guidance_review` | `governance_current_stage` == `ws-review` | 进入审计：在 AI 工具中运行 `$ws-review`（形成 review 结论后再进入提交/交付） |
+| `guidance_review` | (`governance_current_stage` == `ws-review`) AND (`review_effective_count` == `0`) | 进入审计：在 AI 工具中运行 `$ws-review`（形成 review 结论后再进入提交/交付） |
+| `guidance_review_dual_gate` | (`governance_current_stage` == `ws-review`) AND (`review_effective_count` > 0) AND (`dual_review_missing_count` > 0) | 已有通用 review，但 dual review gate 仍未完成：继续补齐 `$ws-spec-review` / `$ws-quality-review`，不要把 `codex-review.md` 误当成 finish gate |
 | `guidance_review_spec_missing` | `spec_review_ready` is falsy | 补齐流程审查：运行 `$ws-spec-review`，并落盘 `changes/<change-id>/review/spec-review.md` |
 | `guidance_review_quality_missing` | `quality_review_ready` is falsy | 补齐质量审查：运行 `$ws-quality-review`，并落盘 `changes/<change-id>/review/quality-review.md` |
 | `guidance_commit` | `governance_current_stage` == `ws-commit` | 进入提交门：在 AI 工具中运行 `$ws-commit`（review + validate stamp + commit message 确认） |
@@ -51,9 +52,9 @@
 | `guidance_deliver_validate_missing` | (`governance_current_stage` == `ws-deliver`) AND (`validate_stamp_ready` is falsy) | 补齐 validate stamp：运行 `aiws validate . --stamp` |
 | `guidance_deliver_verify_before_complete_missing` | (`governance_current_stage` == `ws-deliver`) AND (`verify_before_complete_ready` is falsy) | 补齐完成前 gate：运行 `$ws-verify-before-complete`，并落盘 `changes/<change-id>/evidence/verify-before-complete.md` |
 | `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_cleanup_pending` | `governance_rule_id` == `finish_cleanup_pending` | push 已完成，但 cleanup 仍未完成（{finish_state_reason}）；清理对应 change 分支后重跑 `$ws-finish` |
 | `guidance_finish_handoff` | `governance_rule_id` == `finish_completed` | 收尾已完成且 change 应已归档：下一步运行 `$ws-handoff` 检查/补充归档 handoff |
-| `guidance_finish_resume_required` | `governance_rule_id` == `finish_resume_required` | finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支 worktree 运行 `aiws validate . --stamp`） |
+| `guidance_finish_resume_required` | `governance_rule_id` == `finish_resume_required` | finish closeout 未完成：直接重跑 `aiws change finish {change_id} --push`（不要先在目标分支上运行 `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-governance-rules.schema.json

@@ -1,9 +1,47 @@
 {
   "type": "object",
-  "required": ["version", "description", "governanceRules", "guidanceRules"],
+  "required": ["version", "description", "workflowStateSuffix", "stateEnum", "governanceRules", "guidanceRules"],
   "properties": {
     "version": { "type": "integer" },
     "description": { "type": "string", "minLength": 1 },
+    "workflowStateSuffix": {
+      "type": "object",
+      "required": ["description", "values", "stateSuffixMap"],
+      "properties": {
+        "description": { "type": "string", "minLength": 1 },
+        "values": {
+          "type": "array",
+          "minItems": 6,
+          "items": { "type": "string", "pattern": "^(intake|planning|dev|review|deliver|completed)$" }
+        },
+        "stateSuffixMap": {
+          "type": "object",
+          "minProperties": 6,
+          "additionalProperties": { "type": "string", "pattern": "^\\[workflow-state:session:[a-z]+\\]$" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "stateEnum": {
+      "type": "object",
+      "required": ["values", "stageMapping"],
+      "properties": {
+        "values": {
+          "type": "array",
+          "minItems": 6,
+          "items": { "type": "string", "pattern": "^(intake|planning|dev|review|deliver|completed)$" }
+        },
+        "stageMapping": {
+          "type": "object",
+          "minProperties": 6,
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "governanceRules": {
       "type": "array",
       "minItems": 1,

package/docs/workflow-review-gates.json

@@ -27,6 +27,12 @@
       "mustWrite": "changes/<change-id>/review/quality-review.md（无法识别 change 时回退 .agentdocs/tmp/review/quality-review.md）",
       "blockers": "没有可审改动；没有验证上下文；无法写 review 证据",
       "exitCriteria": "已给出高优先级缺陷/风险、测试缺口和最小验证建议",
+      "aiSlopChecks": [
+        "unnecessary_abstraction",
+        "fake_comments",
+        "over_defensive",
+        "cargo_cult"
+      ],
       "next": "ws-verify-before-complete 或修复后重审"
     },
     {

package/docs/workflow-review-gates.md

@@ -10,11 +10,20 @@
 
 ## Gate 表
 
-| Gate | Stage | Focus | Must Read | Must Write | Blockers | Exit | Next |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| `ws-spec-review` | review | requirements 归因、plan/change 绑定、证据路径、流程 gate 与危险操作边界 | AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md；plan/...；changes/<change-id>/... | changes/<change-id>/review/spec-review.md（无法识别 change 时回退 .agentdocs/tmp/review/spec-review.md） | 无法定位真值文件；无法确认变更归因；无法写 review 证据 | 已给出流程/真值层 blockers、scope/gate 问题与最小修复建议 | ws-quality-review 或修复后重审 |
-| `ws-quality-review` | review | 行为回归、边界条件、测试覆盖、实现质量、可维护性 | git diff；验证结果；相关代码/配置；已有 review/analysis/patches 工件 | changes/<change-id>/review/quality-review.md（无法识别 change 时回退 .agentdocs/tmp/review/quality-review.md） | 没有可审改动；没有验证上下文；无法写 review 证据 | 已给出高优先级缺陷/风险、测试缺口和最小验证建议 | ws-verify-before-complete 或修复后重审 |
-| `ws-verify-before-complete` | finish_gate | finish / handoff 前检查 review、validate、evidence 与 completion gate 是否齐全 | changes/<change-id>/review/...；.agentdocs/tmp/aiws-validate/*.json；changes/<change-id>/evidence/...；git status | changes/<change-id>/evidence/verify-before-complete.md（无法识别 change 时回退 .agentdocs/tmp/review/verify-before-complete.md） | 缺少 spec review；缺少 quality review；缺少 validate stamp；存在未关闭 blocker | 已明确 pass/fail、缺失项与是否可进入 ws-finish / ws-handoff | ws-finish / ws-handoff 或回退前置 gate |
+| Gate | Stage | Focus | Must Read | Must Write | Blockers | Exit | AI-Slop | Next |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `ws-spec-review` | review | requirements 归因、plan/change 绑定、证据路径、流程 gate 与危险操作边界 | AI_PROJECT.md；REQUIREMENTS.md；AI_WORKSPACE.md；plan/...；changes/<change-id>/... | changes/<change-id>/review/spec-review.md（无法识别 change 时回退 .agentdocs/tmp/review/spec-review.md） | 无法定位真值文件；无法确认变更归因；无法写 review 证据 | 已给出流程/真值层 blockers、scope/gate 问题与最小修复建议 | N/A | ws-quality-review 或修复后重审 |
+| `ws-quality-review` | review | 行为回归、边界条件、测试覆盖、实现质量、可维护性 | git diff；验证结果；相关代码/配置；已有 review/analysis/patches 工件 | changes/<change-id>/review/quality-review.md（无法识别 change 时回退 .agentdocs/tmp/review/quality-review.md） | 没有可审改动；没有验证上下文；无法写 review 证据 | 已给出高优先级缺陷/风险、测试缺口和最小验证建议 | 4 checks | ws-verify-before-complete 或修复后重审 |
+| `ws-verify-before-complete` | finish_gate | finish / handoff 前检查 review、validate、evidence 与 completion gate 是否齐全 | changes/<change-id>/review/...；.agentdocs/tmp/aiws-validate/*.json；changes/<change-id>/evidence/...；git status | changes/<change-id>/evidence/verify-before-complete.md（无法识别 change 时回退 .agentdocs/tmp/review/verify-before-complete.md） | 缺少 spec review；缺少 quality review；缺少 validate stamp；存在未关闭 blocker | 已明确 pass/fail、缺失项与是否可进入 ws-finish / ws-handoff | N/A | ws-finish / ws-handoff 或回退前置 gate |
+
+## AI-Slop Check Items
+
+`ws-quality-review` 必须检查以下 AI 生成代码常见缺陷：
+
+- **`unnecessary_abstraction`**：过度抽象（单实现接口、未使用的泛化层）
+- **`fake_comments`**：伪注释（表述代码行为但不解释 why 的注释，或与代码不一致的注释）
+- **`over_defensive`**：过度防御（不必要的安全检查、对不可能情况的处理）
+- **`cargo_cult`**：货舱崇拜（照搬模式但不理解原因，如不必要的 observer/strategy 模式）
 
 ## 统一规则
 

package/docs/workflow-review-gates.schema.json

@@ -34,6 +34,10 @@
           "mustWrite": { "type": "string", "minLength": 1 },
           "blockers": { "type": "string", "minLength": 1 },
           "exitCriteria": { "type": "string", "minLength": 1 },
+          "aiSlopChecks": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1, "pattern": "^[a-z_]+$" }
+          },
           "next": { "type": "string", "minLength": 1 }
         },
         "additionalProperties": false

package/docs/workflow-router-rules.json

@@ -29,8 +29,8 @@
     },
     {
       "step": "classify_intent",
-      "action": "判断当前任务是在做需求变更、实现、评审、收尾还是交接。",
-      "why": "先判 workflow，再决定进入哪个 skill；不能一开始就跳进实现。"
+      "action": "收集项目上下文（git status、涉及文件范围、当前 change 状态），再判断当前任务是在做需求变更、实现、评审、收尾还是交接。",
+      "why": "先收集上下文才能准确判 workflow；避免仅凭用户描述就判定为小步实现而误路由。"
     },
     {
       "step": "check_intent_freeze",
@@ -92,7 +92,7 @@
     {
       "id": "finish_request",
       "intent": "收尾/合并/推送/cleanup",
-      "match": "用户要求 finish、merge、push、收尾、交付完成、清理 worktree 或 branch。",
+      "match": "用户要求 finish、merge、push、收尾、交付完成、清理 change 分支。",
       "routeTo": "ws-finish",
       "gate": "必须满足 finish gate，不能跳过 validate / push / cleanup。",
       "rationale": "finish 是独立治理阶段，不能与普通实现混用。"
@@ -108,7 +108,7 @@
     {
       "id": "plan_first",
       "intent": "中大型实现或需要建立 change 上下文",
-      "match": "任务是多步实现、跨文件、跨模块、需要方案、需要新建 change/worktree，且需求已经冻结或已有可消费的 intake 草案。",
+      "match": "任务是多步实现、跨文件、跨模块、需要方案、需要新建 change 分支，且需求已经冻结或已有可消费的 intake 草案。",
       "routeTo": "ws-plan",
       "gate": "plan 过 gate 前不进入 `ws-dev`。",
       "rationale": "medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。"
@@ -116,10 +116,42 @@
     {
       "id": "direct_implementation",
       "intent": "小步实现/修复/配置调整",
-      "match": "目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。",
+      "match": "已知改动位置、已知改动内容、无需探索代码库；router 已收集项目上下文（涉及文件数、模块范围）确认是小步修复；归因清晰、验证入口明确，且无需先改 requirements 或单独评审。",
+  "preconditions": [
+    "router 必须先收集项目上下文（git status, 涉及文件范围, 当前 change 状态）确认任务确实是单点/小步修复，而非仅凭用户描述判定",
+    "collected project context (git status/diff/stat)",
+    "change file count ≤ 3",
+    "change total lines ≤ 100",
+    "verify entry confirmed",
+    "design gate: for implementations changing >2 files, proposal.md and tasks.md must exist in changes/<id>/"
+  ],
       "routeTo": "ws-dev",
       "gate": "若执行中发现复杂度升高，必须回退到 `ws-plan`。",
-      "rationale": "router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。"
+      "rationale": "router 允许明确的小步任务直接实现，但前提是已验证项目上下文确认范围可控；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。router 不能仅凭用户描述判\"小步\"；必须读项目上下文验证。"
+    },
+    {
+      "id": "escape_hatch",
+      "intent": "用户显式跳过流程",
+      "match": "用户明确说\"直接改\"/\"跳过流程\"/\"do it inline\"/\"不要走流程\"等表达",
+      "routeTo": "ws-dev-lite",
+      "gate": "仍须遵守最小约束：归因到 Req_ID、有验证入口、落盘 evidence 标记 [escape-hatch: direct-implementation]",
+      "rationale": "允许用户在明确知情的情况下跳过完整流程，但不免除基础治理约束"
+    },
+    {
+      "id": "design_first",
+      "intent": "需要先出设计方案",
+      "match": "任务涉及新流程、新模块、新架构或对现有架构有显著影响的方向决策，需要先出设计方案再进入实现。",
+      "routeTo": "ws-plan",
+      "gate": "plan 阶段需包含设计内容（design.md 或 plan 内 design 章节），plan 过 gate 前不进入 `ws-dev`。",
+      "rationale": "复杂或高影响改动应先出设计方案，让设计过审后再投入实现，避免返工。当前通过 ws-plan 统一承载设计，无需单独 ws-design skill。"
+    },
+    {
+      "id": "spec_update",
+      "intent": "需要更新规范/文档/验收标准",
+      "match": "任务涉及更新 AI_PROJECT.md、REQUIREMENTS.md、AI_WORKSPACE.md 中的规范说明、验收标准或 contract 文档。",
+      "routeTo": "ws-req-change",
+      "gate": "spec 更新必须先过 req-review，再同步到真值文件。",
+      "rationale": "规范更新与功能变更不同，router 应优先引导到 spec 维护链而非直接实现。当前走 ws-req-change 链路（ws-req-review → 确认 → ws-req-change）。"
     }
   ],
   "routeCases": [
@@ -166,7 +198,7 @@
     {
       "id": "case_finish_request",
       "scenario": "用户要求合并、push、cleanup 或 finish 当前 change。",
-      "request": "把 demo-change finish 掉并 push，顺便 cleanup worktree。",
+      "request": "把 demo-change finish 掉并 push，顺便 cleanup。",
       "expectedRuleId": "finish_request",
       "expectedRoute": "ws-finish",
       "why": "finish 是独立治理阶段，必须先走 finish gate。"
@@ -181,7 +213,7 @@
     },
     {
       "id": "case_plan_first",
-      "scenario": "任务是跨文件、多步实现，且需要先建立 change/worktree 或方案。",
+      "scenario": "任务是跨文件、多步实现，且需要先建立 change 分支或方案。",
       "request": "实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。",
       "expectedRuleId": "plan_first",
       "expectedRoute": "ws-plan",
@@ -194,6 +226,38 @@
       "expectedRuleId": "direct_implementation",
       "expectedRoute": "ws-dev",
       "why": "小步明确实现允许直接进入 dev；若用户明确要轻量直修，可进一步显式使用 ws-dev-lite，但治理归属仍收敛到 ws-dev。"
+    },
+    {
+      "id": "case_context_gate",
+      "scenario": "Router 必须先收集项目上下文再判 direct vs plan。",
+      "request": "修复一个 auth bug。",
+      "expectedRuleId": "direct_implementation",
+      "expectedRoute": "ws-dev",
+      "why": "Router 必须先 git status/读相关文件确认范围后才能判 direct；`precondition` 字段显式要求先收集上下文；不能仅凭任务描述判\"小步\"。"
+    },
+    {
+      "id": "case_escape_hatch",
+      "scenario": "用户说'跳过流程直接改'",
+      "request": "\"别走流程了，直接改\"",
+      "expectedRuleId": "escape_hatch",
+      "expectedRoute": "ws-dev-lite",
+      "why": "显式跳过但遵守最小约束"
+    },
+    {
+      "id": "case_design_first",
+      "scenario": "任务需要先出设计方案再进入实现。",
+      "request": "设计 dashboard 架构，出方案后再实现。",
+      "expectedRuleId": "design_first",
+      "expectedRoute": "ws-plan",
+      "why": "高影响改动应先出设计方案，过审后再投入实现。当前通过 ws-plan 统一承载设计。"
+    },
+    {
+      "id": "case_spec_update",
+      "scenario": "任务涉及更新规范或验收标准文档。",
+      "request": "更新 AI_WORKSPACE.md 中的验证命令说明。",
+      "expectedRuleId": "spec_update",
+      "expectedRoute": "ws-req-change",
+      "why": "规范更新应先走 spec 维护链（ws-req-change），直接实现会绕过 review 门禁。"
     }
   ],
   "clarificationTriggers": [

package/docs/workflow-router-rules.md

@@ -31,24 +31,27 @@ router 在做任何 workflow 判断前，必须先读取：
 | Step | Action | Why |
 | --- | --- | --- |
 | `read_truths` | 先定位项目根，并读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。 | router 不能绕过真值文件，否则会把 workflow 判断建立在会话猜测上。 |
-| `classify_intent` | 判断当前任务是在做需求变更、实现、评审、收尾还是交接。 | 先判 workflow，再决定进入哪个 skill；不能一开始就跳进实现。 |
+| `classify_intent` | 收集项目上下文（git status、涉及文件范围、当前 change 状态），再判断当前任务是在做需求变更、实现、评审、收尾还是交接。 | 先收集上下文才能准确判 workflow；避免仅凭用户描述就判定为小步实现而误路由。 |
 | `check_intent_freeze` | 判断需求是否已经冻结；若存在多条待确认问题或需要多轮沟通，先进入 intake 阶段。 | 中大型需求在计划前往往需要多轮澄清；router 应该先把问题冻结，而不是把沟通负担全部塞给 `ws-plan`。 |
 | `check_binding` | 检查任务是否具备 `Req_ID` / `Problem_ID` / change 上下文 / Verify 入口等最小绑定。 | 缺失绑定时必须阻断或回退到 `ws-plan`，避免无归因实现。 |
 | `route_or_clarify` | 给出单一路由结果；若意图不明确，则先问关键澄清问题并停止。 | default-routed workflow 的关键不是自动执行，而是避免模糊任务直接进入实现。 |
 
 ## 路由规则
 
-| Rule ID | Intent | Match | Route | Gate | Rationale |
-| --- | --- | --- | --- | --- | --- |
-| `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，且需求已经冻结或已有可消费的 intake 草案。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。 |
-| `direct_implementation` | 小步实现/修复/配置调整 | 目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。 |
+| Rule ID | Intent | Match | Route | Gate | Preconditions | Rationale |
+| --- | --- | --- | --- | --- | --- | --- |
+| `missing_truths` | 仓库未初始化或真值缺失 | 缺失任一真值文件，或无法确定项目根目录。 | `ws-preflight` | 先补齐真值或确认项目根，不进入实现。 | N/A | 所有后续 skill 都依赖真值文件；缺失时 router 只能回退到 preflight/init 路径。 |
+| `unclear_intent` | 用户目标、归因或验收不清晰 | 无法明确当前是需求变更、实现、评审、finish 还是 handoff；或无法明确 `Req_ID` / `Problem_ID` / Verify。 | `clarify` | 必须先问 1-3 个关键澄清问题，然后停止。 | N/A | router 的职责是阻断模糊任务，而不是用猜测替代路由。 |
+| `needs_intake` | 需求存在多条待确认问题，尚未冻结 | 任务是新需求或中大型变更；目标方向大致明确，但存在多条待确认问题、需要逐条沟通，或用户明确要求先多轮澄清再进入计划。 | `ws-intake` | 先逐条澄清并冻结结论；未形成 intake 草案前不进入 `ws-plan`。 | N/A | `ws-intake` 负责把多轮需求沟通收敛为轻量草案，避免 `ws-plan` 同时承担反复澄清与正式计划落盘。 |
+| `requirements_change` | 需求/验收/合同变更 | 任务涉及 `REQUIREMENTS.md`、requirements CSV、spec contract、验收标准或 workflow 真值变更。 | `ws-req-review` | 先做需求评审，再决定是否进入 `ws-plan` / `ws-dev`。 | N/A | 需求真值变更必须先过 review，不能直接编码。 |
+| `review_request` | 审计/评审/找风险 | 用户明确要求 review、audit、评审、找 bug、识别风险或检查回归。 | `ws-review` | 先给 findings；除非用户另行要求，不先改代码。 | N/A | 评审任务与实现任务的输出契约不同，必须优先走 review。 |
+| `finish_request` | 收尾/合并/推送/cleanup | 用户要求 finish、merge、push、收尾、交付完成、清理 change 分支。 | `ws-finish` | 必须满足 finish gate，不能跳过 validate / push / cleanup。 | N/A | finish 是独立治理阶段，不能与普通实现混用。 |
+| `handoff_request` | 交接/归档总结 | 用户要求 handoff、交接说明、archive summary、会话总结或接力说明。 | `ws-handoff` | 先确认 change 已 finish 或 archive 上下文存在。 | N/A | handoff 依赖已有证据与归档上下文，不应在实现前触发。 |
+| `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change 分支，且需求已经冻结或已有可消费的 intake 草案。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | N/A | medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。 |
+| `direct_implementation` | 小步实现/修复/配置调整 | 已知改动位置、已知改动内容、无需探索代码库；router 已收集项目上下文（涉及文件数、模块范围）确认是小步修复；归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | - router 必须先收集项目上下文（git status, 涉及文件范围, 当前 change 状态）确认任务确实是单点/小步修复，而非仅凭用户描述判定<br>- collected project context (git status/diff/stat)<br>- change file count ≤ 3<br>- change total lines ≤ 100<br>- verify entry confirmed<br>- design gate: for implementations changing >2 files, proposal.md and tasks.md must exist in changes/<id>/ | router 允许明确的小步任务直接实现，但前提是已验证项目上下文确认范围可控；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。router 不能仅凭用户描述判"小步"；必须读项目上下文验证。 |
+| `escape_hatch` | 用户显式跳过流程 | 用户明确说"直接改"/"跳过流程"/"do it inline"/"不要走流程"等表达 | `ws-dev-lite` | 仍须遵守最小约束：归因到 Req_ID、有验证入口、落盘 evidence 标记 [escape-hatch: direct-implementation] | N/A | 允许用户在明确知情的情况下跳过完整流程，但不免除基础治理约束 |
+| `design_first` | 需要先出设计方案 | 任务涉及新流程、新模块、新架构或对现有架构有显著影响的方向决策，需要先出设计方案再进入实现。 | `ws-plan` | plan 阶段需包含设计内容（design.md 或 plan 内 design 章节），plan 过 gate 前不进入 `ws-dev`。 | N/A | 复杂或高影响改动应先出设计方案，让设计过审后再投入实现，避免返工。当前通过 ws-plan 统一承载设计，无需单独 ws-design skill。 |
+| `spec_update` | 需要更新规范/文档/验收标准 | 任务涉及更新 AI_PROJECT.md、REQUIREMENTS.md、AI_WORKSPACE.md 中的规范说明、验收标准或 contract 文档。 | `ws-req-change` | spec 更新必须先过 req-review，再同步到真值文件。 | N/A | 规范更新与功能变更不同，router 应优先引导到 spec 维护链而非直接实现。当前走 ws-req-change 链路（ws-req-review → 确认 → ws-req-change）。 |
 
 ## Route Cases
 
@@ -59,10 +62,14 @@ router 在做任何 workflow 判断前，必须先读取：
 | `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。 |
+| `case_finish_request` | 用户要求合并、push、cleanup 或 finish 当前 change。 | 把 demo-change finish 掉并 push，顺便 cleanup。 | `finish_request` | `ws-finish` | finish 是独立治理阶段，必须先走 finish gate。 |
 | `case_handoff_request` | 用户要求 handoff、交接说明、archive summary 或接力文档。 | 给这个 change 写 handoff，并补 archive summary。 | `handoff_request` | `ws-handoff` | handoff 依赖已有 finish/archive 上下文，不能当成普通实现。 |
-| `case_plan_first` | 任务是跨文件、多步实现，且需要先建立 change/worktree 或方案。 | 实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。 | `plan_first` | `ws-plan` | 中大型实现应先落盘计划，再进入 dev。 |
+| `case_plan_first` | 任务是跨文件、多步实现，且需要先建立 change 分支或方案。 | 实现 dashboard 的阶段治理视图并补测试，需要新建 change 和计划。 | `plan_first` | `ws-plan` | 中大型实现应先落盘计划，再进入 dev。 |
 | `case_direct_implementation` | 任务是小步明确修复，归因和验证入口都已清楚。 | 修复 codex install-skills 的默认路径，并补一条可复现回归。 | `direct_implementation` | `ws-dev` | 小步明确实现允许直接进入 dev；若用户明确要轻量直修，可进一步显式使用 ws-dev-lite，但治理归属仍收敛到 ws-dev。 |
+| `case_context_gate` | Router 必须先收集项目上下文再判 direct vs plan。 | 修复一个 auth bug。 | `direct_implementation` | `ws-dev` | Router 必须先 git status/读相关文件确认范围后才能判 direct；`precondition` 字段显式要求先收集上下文；不能仅凭任务描述判"小步"。 |
+| `case_escape_hatch` | 用户说'跳过流程直接改' | "别走流程了，直接改" | `escape_hatch` | `ws-dev-lite` | 显式跳过但遵守最小约束 |
+| `case_design_first` | 任务需要先出设计方案再进入实现。 | 设计 dashboard 架构，出方案后再实现。 | `design_first` | `ws-plan` | 高影响改动应先出设计方案，过审后再投入实现。当前通过 ws-plan 统一承载设计。 |
+| `case_spec_update` | 任务涉及更新规范或验收标准文档。 | 更新 AI_WORKSPACE.md 中的验证命令说明。 | `spec_update` | `ws-req-change` | 规范更新应先走 spec 维护链（ws-req-change），直接实现会绕过 review 门禁。 |
 
 ## 必须先澄清的情形
 

package/docs/workflow-router-rules.schema.json

@@ -73,6 +73,10 @@
             "pattern": "^(clarify|ws-[a-z0-9-]+)$"
           },
           "gate": { "type": "string", "minLength": 1 },
+          "preconditions": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
           "rationale": { "type": "string", "minLength": 1 }
         },
         "additionalProperties": false

package/docs/workflow-stage-contracts.json

@@ -14,15 +14,15 @@
     "ws-dev",
     "ws-review",
     "ws-commit",
+    "ws-verify-before-complete",
     "ws-deliver",
     "ws-finish",
     "ws-handoff"
   ],
   "notes": [
     "ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。",
-    "ws-finish 用于 fast-forward 合并、push、worktree cleanup，并在完整 finish 后自动归档 change。",
-    "ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。",
-    "若存在独立 change worktree，治理信号应优先读取该 worktree；若 worktree metadata 已 stale，则降级为 warning 并回退到当前 worktree。"
+    "ws-finish 用于 fast-forward 合并、push、change 分支清理，并在完整 finish 后自动归档 change。",
+    "ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。"
   ],
   "stages": [
     {
@@ -59,6 +59,7 @@
     },
     {
       "stage": "ws-dev",
+      "gateBefore": "ws-plan-verify passed",
       "goal": "实施最小改动并验证",
       "requiredInputs": "真值文件；归因目标；计划（medium/complex）",
       "requiredOutputs": "Changed；Verify；Evidence；Next",
@@ -67,6 +68,7 @@
     },
     {
       "stage": "ws-review",
+      "gateBefore": "evaluate-optimize completed",
       "goal": "审计规范、风险与验证完整性",
       "requiredInputs": "当前 diff；验证结果；真值文件",
       "requiredOutputs": "review 文件；Top risks；Next",
@@ -79,7 +81,15 @@
       "requiredInputs": "staged diff；review 证据；validate stamp；用户确认的 message",
       "requiredOutputs": "Evidence；Context；Commit",
       "blockers": "无 staged changes；submodule dirty；validate 失败；message 未确认",
-      "next": "ws-deliver / ws-finish"
+      "next": "ws-verify-before-complete / ws-deliver"
+    },
+    {
+      "stage": "ws-verify-before-complete",
+      "goal": "检查双审查、validate stamp 与交付证据齐全，确认无 Critical 阻塞",
+      "requiredInputs": "spec-review 证据；quality-review 证据；validate stamp；无 Critical blocker；change artifacts 状态",
+      "requiredOutputs": "verify-before-complete gate 通过/回退；结构化验证输出（逐项 pass/fail）",
+      "blockers": "缺少任一 review 证据；validate 失败；存在 Critical blocker；handoff 记录缺失",
+      "next": "ws-deliver 或回退修复"
     },
     {
       "stage": "ws-deliver",
@@ -93,7 +103,7 @@
       "stage": "ws-finish",
       "goal": "安全合并、push、cleanup，并自动归档",
       "requiredInputs": "干净工作区；已提交的 change；push 目标；submodule 真值（若有）",
-      "requiredOutputs": "Merge；Push；Worktree cleanup；Archive/Handoff；Evidence",
+      "requiredOutputs": "Merge；Push；Change 分支清理；Archive/Handoff；Evidence",
       "blockers": "dirty 工作区；ff 失败；submodule 无法安全 push",
       "next": "ws-handoff"
     },
@@ -106,6 +116,11 @@
       "next": "新 change 通过 Depends_On 接力"
     }
   ],
+  "boundaryDescriptions": {
+    "mainSession": "编排 + 质量网关：主 session 只做任务分解、路由、收敛证据与门禁判定，不直接实现代码改动。所有代码修改必须通过 ws-dev 由实现者完成。",
+    "subagent": "执行 + 证据产出：subagent 在主 session 授权的边界内执行具体任务，产出的 findings/patches/evidence 必须写入 changes/<id>/ 对应目录。subagent 不自审、不跳门禁。",
+    "handoff": "跨会话 / 跨角色接力：handoff 必须写入 changes/<id>/evidence/ 或 changes/archive/.../handoff.md，不允许仅依赖会话上下文传递关键信息。"
+  },
   "unifiedRules": [
     "每个阶段都必须回指真值文件或 change 工件，不能只依赖会话上下文。",
     "每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。",
@@ -128,6 +143,10 @@
         "label": "validate",
         "value": "`.agentdocs/tmp/aiws-validate/*.json`"
       },
+      {
+        "label": "verify-before-complete",
+        "value": "`changes/<change-id>/evidence/verify-before-complete.md`；结构化逐项 gate 结果（spec-review ✓/✗, quality-review ✓/✗, validate ✓/✗, no-Critical ✓/✗, handoff ✓/✗）"
+      },
       {
         "label": "deliver / finish",
         "value": "`changes/<change-id>/evidence/...`、`state`、merge / push 结果"

package/docs/workflow-stage-contracts.md

@@ -12,28 +12,28 @@
 
 默认链路：
 
-`ws-preflight` -> `ws-intake` -> `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-verify-before-complete` -> `ws-deliver` -> `ws-finish` -> `ws-handoff`
 
 说明：
 - ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。
-- ws-finish 用于 fast-forward 合并、push、worktree cleanup，并在完整 finish 后自动归档 change。
+- ws-finish 用于 fast-forward 合并、push、change 分支清理，并在完整 finish 后自动归档 change。
 - ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。
-- 若存在独立 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-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 |
-| `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；Archive/Handoff；Evidence | dirty 工作区；ff 失败；submodule 无法安全 push | ws-handoff |
-| `ws-handoff` | 查看/补充可接力的归档交接说明 | 已归档的 change | changes/archive/.../handoff.md；Next | 无法定位已归档 change；handoff 无法生成或读取 | 新 change 通过 Depends_On 接力 |
+| Stage | 目标 | Gate Before | 必需输入 | 必需输出 | 阻断条件 | 下一步 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `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` | 实施最小改动并验证 | ws-plan-verify passed | 真值文件；归因目标；计划（medium/complex） | Changed；Verify；Evidence；Next | 无法归因；没有验证入口；change 上下文不安全 | ws-review / ws-commit |
+| `ws-review` | 审计规范、风险与验证完整性 | evaluate-optimize completed | 当前 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-verify-before-complete / ws-deliver |
+| `ws-verify-before-complete` | 检查双审查、validate stamp 与交付证据齐全，确认无 Critical 阻塞 |  | spec-review 证据；quality-review 证据；validate stamp；无 Critical blocker；change artifacts 状态 | verify-before-complete gate 通过/回退；结构化验证输出（逐项 pass/fail） | 缺少任一 review 证据；validate 失败；存在 Critical blocker；handoff 记录缺失 | ws-deliver 或回退修复 |
+| `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；Change 分支清理；Archive/Handoff；Evidence | dirty 工作区；ff 失败；submodule 无法安全 push | ws-handoff |
+| `ws-handoff` | 查看/补充可接力的归档交接说明 |  | 已归档的 change | changes/archive/.../handoff.md；Next | 无法定位已归档 change；handoff 无法生成或读取 | 新 change 通过 Depends_On 接力 |
 
 ## 统一规则
 
@@ -50,6 +50,7 @@
 - planning：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`
 - review：`changes/<change-id>/review/...` 或 `.agentdocs/tmp/review/...`
 - validate：`.agentdocs/tmp/aiws-validate/*.json`
+- verify-before-complete：`changes/<change-id>/evidence/verify-before-complete.md`；结构化逐项 gate 结果（spec-review ✓/✗, quality-review ✓/✗, validate ✓/✗, no-Critical ✓/✗, handoff ✓/✗）
 - deliver / finish：`changes/<change-id>/evidence/...`、`state`、merge / push 结果
 - handoff：`changes/archive/.../handoff.md`