@aipper/aiws-spec 0.0.29 → 0.0.30

package/docs/workflow-delegation-contracts.json

@@ -152,6 +152,7 @@
       ],
       "handoffRequirements": [
         "先列 findings，再给假设或残余风险",
+        "产出结构化 findings：[Critical] 阻塞问题；[Warning] 应修复项；[Info] 建议改进（对齐 reworkLoopProtocol.findingSeverities）",
         "明确这是 spec review、quality review 还是交付前验证"
       ],
       "contextFiles": [
@@ -187,7 +188,8 @@
       ],
       "handoffRequirements": [
         "收敛 delegated outputs，给出最终结论与残余风险",
-        "确认验证、review gate 与 artifact 状态"
+        "确认验证、review gate 与 artifact 状态",
+        "记录每轮 rework 回合数、已修复/剩余 Critical 与 Warning 数量（对齐 reworkLoopProtocol.handoffRecording）"
       ]
     }
   ],
@@ -258,6 +260,16 @@
       { "forStatus": "BLOCKED",            "response": "停止委托流程；输出 blocker 详情；主 agent 解 blocker 后重试" }
     ]
   },
+  "reworkLoopProtocol": {
+    "title": "Rework Loop Protocol",
+    "description": "结构化反馈环：reviewer findings → worker fix → re-review，最多 2 轮",
+    "maxRounds": 2,
+    "findingSeverities": ["Critical", "Warning", "Info"],
+    "workerFixContract": "worker 接收结构化 fix list，只修 Critical + Warning；info 由 integrator 处理",
+    "handoffRecording": "每轮结束后 handoff.md 必须记录 roundNumber、criticalFixed、criticalRemaining、warningFixed、warningRemaining、infoCount",
+    "escalationRule": "2 轮后仍有 Critical → 升级给 integrator 做人类决策，不得无限循环",
+    "mainSessionRule": "即使是 review 建议的小修，也应由 worker subagent 执行；例外：用户明确说'你直接改'"
+  },
   "workflowPatterns": [
     {
       "id": "worker_reviewer_loop",
@@ -332,6 +344,33 @@
     "任何 native multi-agent 结果都必须能回收到 `analysis/patches/review/evidence` 约定路径。",
     "native delegation 是可选执行策略，不是 workflow 的必需前提。"
   ],
+  "standardRoles": {
+    "title": "Standard Roles (Recommended)",
+    "description": "推荐的标准角色定义，供 delegation 场景使用。每个角色有明确的读写权限和产物目标。",
+    "roles": [
+      {
+        "id": "implementer",
+        "description": "在授权范围内实现代码改动，补齐测试与验证证据",
+        "readAccess": ["AI_PROJECT.md", "REQUIREMENTS.md", "AI_WORKSPACE.md", "changes/<id>/plan/", "changes/<id>/analysis/"],
+        "writeAccess": ["assigned source files", "assigned test files", "changes/<id>/evidence/"],
+        "artifacts": ["code files", "test files", "changes/<id>/evidence/*.md"]
+      },
+      {
+        "id": "reviewer",
+        "description": "从需求、实现质量、回归风险角度独立审查，产出结构化 findings",
+        "readAccess": ["AI_PROJECT.md", "REQUIREMENTS.md", "git diff", "changes/<id>/evidence/"],
+        "writeAccess": ["changes/<id>/review/"],
+        "artifacts": ["changes/<id>/review/*.md"]
+      },
+      {
+        "id": "researcher",
+        "description": "只读探索代码库与外部文档，输出分析笔记与影响面评估",
+        "readAccess": ["AI_PROJECT.md", "REQUIREMENTS.md", "AI_WORKSPACE.md", "repo source files", "external docs"],
+        "writeAccess": ["changes/<id>/analysis/"],
+        "artifacts": ["changes/<id>/analysis/*.md"]
+      }
+    ]
+  },
   "notes": [
     "`aiws` 的价值在于治理内核和合同层，不在于成为统一 runtime。",
     "这一版先把 contract 写清，再决定哪些入口需要在模板里显式投影。",

package/docs/workflow-delegation-contracts.md

@@ -132,6 +132,7 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 **Handoff Requirements**
 
 - 先列 findings，再给假设或残余风险
+- 产出结构化 findings：[Critical] 阻塞问题；[Warning] 应修复项；[Info] 建议改进（对齐 reworkLoopProtocol.findingSeverities）
 - 明确这是 spec review、quality review 还是交付前验证
 
 ### `integrator`
@@ -164,6 +165,15 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 
 - 收敛 delegated outputs，给出最终结论与残余风险
 - 确认验证、review gate 与 artifact 状态
+- 记录每轮 rework 回合数、已修复/剩余 Critical 与 Warning 数量（对齐 reworkLoopProtocol.handoffRecording）
+
+## Standard Roles (Recommended)
+
+| Role | Description | Read | Write | Artifacts |
+| --- | --- | --- | --- | --- |
+| `implementer` | 在授权范围内实现代码改动，补齐测试与验证证据 | `AI_PROJECT.md`, `REQUIREMENTS.md`, `AI_WORKSPACE.md`, `changes/<id>/plan/`, `changes/<id>/analysis/` | `assigned source files`, `assigned test files`, `changes/<id>/evidence/` | `code files`, `test files`, `changes/<id>/evidence/*.md` |
+| `reviewer` | 从需求、实现质量、回归风险角度独立审查，产出结构化 findings | `AI_PROJECT.md`, `REQUIREMENTS.md`, `git diff`, `changes/<id>/evidence/` | `changes/<id>/review/` | `changes/<id>/review/*.md` |
+| `researcher` | 只读探索代码库与外部文档，输出分析笔记与影响面评估 | `AI_PROJECT.md`, `REQUIREMENTS.md`, `AI_WORKSPACE.md`, `repo source files`, `external docs` | `changes/<id>/analysis/` | `changes/<id>/analysis/*.md` |
 
 ## Artifact Targets
 

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

@@ -11,6 +11,7 @@
     "artifactTargets",
     "reviewConvergence",
     "subagentStatusProtocol",
+    "reworkLoopProtocol",
     "fallbackMode",
     "toolCapabilityMatrix",
     "universalRules",
@@ -186,6 +187,25 @@
       },
       "additionalProperties": false
     },
+    "reworkLoopProtocol": {
+      "type": "object",
+      "required": ["title", "description", "maxRounds", "findingSeverities", "escalationRule", "workerFixContract", "handoffRecording", "mainSessionRule"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "maxRounds": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "findingSeverities": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "escalationRule": { "type": "string", "minLength": 1 },
+        "workerFixContract": { "type": "string", "minLength": 1 },
+        "handoffRecording": { "type": "string", "minLength": 1 },
+        "mainSessionRule": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
     "fallbackMode": {
       "type": "object",
       "required": ["default", "triggers", "requiredBehavior"],
@@ -265,6 +285,43 @@
       "type": "array",
       "minItems": 1,
       "items": { "type": "string", "minLength": 1 }
+    },
+    "standardRoles": {
+      "type": "object",
+      "required": ["title", "description", "roles"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "roles": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["id", "description", "readAccess", "writeAccess", "artifacts"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+              "description": { "type": "string", "minLength": 1 },
+              "readAccess": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "writeAccess": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string", "minLength": 1 }
+              },
+              "artifacts": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string", "minLength": 1 }
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/docs/workflow-governance-rules.md

@@ -9,7 +9,7 @@
 
 ## 概览
 
-- version: `1`
+- version: `2`
 - description: Machine-readable governance inference rules for aiws change status/next/dashboard.
 - governance rules: 17
 - guidance rules: 18

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",
@@ -116,26 +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-design",
-      "gate": "design 未完成 review 前，不进入 `ws-plan`。",
-      "rationale": "复杂或高影响改动应先出设计方案，让设计过审后再投入实现，避免返工。"
+      "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-spec-update",
-      "gate": "spec 更新必须先过 review，再同步到真值文件。",
-      "rationale": "规范更新与功能变更不同，router 应优先引导到 spec 维护链而非直接实现。"
+      "routeTo": "ws-req-change",
+      "gate": "spec 更新必须先过 req-review，再同步到真值文件。",
+      "rationale": "规范更新与功能变更不同，router 应优先引导到 spec 维护链而非直接实现。当前走 ws-req-change 链路（ws-req-review → 确认 → ws-req-change）。"
     }
   ],
   "routeCases": [
@@ -211,21 +227,37 @@
       "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-design",
-      "why": "高影响改动应先出设计方案，过审后再投入实现。"
+      "expectedRoute": "ws-plan",
+      "why": "高影响改动应先出设计方案，过审后再投入实现。当前通过 ws-plan 统一承载设计。"
     },
     {
       "id": "case_spec_update",
       "scenario": "任务涉及更新规范或验收标准文档。",
       "request": "更新 AI_WORKSPACE.md 中的验证命令说明。",
       "expectedRuleId": "spec_update",
-      "expectedRoute": "ws-spec-update",
-      "why": "规范更新应先走 spec 维护链，直接实现会绕过 review 门禁。"
+      "expectedRoute": "ws-req-change",
+      "why": "规范更新应先走 spec 维护链（ws-req-change），直接实现会绕过 review 门禁。"
     }
   ],
   "clarificationTriggers": [

package/docs/workflow-router-rules.md

@@ -31,26 +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、收尾、交付完成、清理 change 分支。 | `ws-finish` | 必须满足 finish gate，不能跳过 validate / push / cleanup。 | finish 是独立治理阶段，不能与普通实现混用。 |
-| `handoff_request` | 交接/归档总结 | 用户要求 handoff、交接说明、archive summary、会话总结或接力说明。 | `ws-handoff` | 先确认 change 已 finish 或 archive 上下文存在。 | handoff 依赖已有证据与归档上下文，不应在实现前触发。 |
-| `plan_first` | 中大型实现或需要建立 change 上下文 | 任务是多步实现、跨文件、跨模块、需要方案、需要新建 change 分支，且需求已经冻结或已有可消费的 intake 草案。 | `ws-plan` | plan 过 gate 前不进入 `ws-dev`。 | medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。 |
-| `direct_implementation` | 小步实现/修复/配置调整 | 目标明确、归因清晰、验证入口明确，且无需先改 requirements 或单独评审。 | `ws-dev` | 若执行中发现复杂度升高，必须回退到 `ws-plan`。 | router 允许明确的小步任务直接实现，但必须保留回退计划阶段的门；若用户明确要走轻量入口，可在实现阶段显式使用 `ws-dev-lite` 作为 `ws-dev` 的 facade。 |
-| `design_first` | 需要先出设计方案 | 任务涉及新流程、新模块、新架构或对现有架构有显著影响的方向决策，需要先出设计方案再进入实现。 | `ws-design` | design 未完成 review 前，不进入 `ws-plan`。 | 复杂或高影响改动应先出设计方案，让设计过审后再投入实现，避免返工。 |
-| `spec_update` | 需要更新规范/文档/验收标准 | 任务涉及更新 AI_PROJECT.md、REQUIREMENTS.md、AI_WORKSPACE.md 中的规范说明、验收标准或 contract 文档。 | `ws-spec-update` | spec 更新必须先过 review，再同步到真值文件。 | 规范更新与功能变更不同，router 应优先引导到 spec 维护链而非直接实现。 |
+| 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
 
@@ -65,8 +66,10 @@ router 在做任何 workflow 判断前，必须先读取：
 | `case_handoff_request` | 用户要求 handoff、交接说明、archive summary 或接力文档。 | 给这个 change 写 handoff，并补 archive summary。 | `handoff_request` | `ws-handoff` | handoff 依赖已有 finish/archive 上下文，不能当成普通实现。 |
 | `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_design_first` | 任务需要先出设计方案再进入实现。 | 设计 dashboard 架构，出方案后再实现。 | `design_first` | `ws-design` | 高影响改动应先出设计方案，过审后再投入实现。 |
-| `case_spec_update` | 任务涉及更新规范或验收标准文档。 | 更新 AI_WORKSPACE.md 中的验证命令说明。 | `spec_update` | `ws-spec-update` | 规范更新应先走 spec 维护链，直接实现会绕过 review 门禁。 |
+| `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,6 +14,7 @@
     "ws-dev",
     "ws-review",
     "ws-commit",
+    "ws-verify-before-complete",
     "ws-deliver",
     "ws-finish",
     "ws-handoff"
@@ -21,7 +22,7 @@
   "notes": [
     "ws-deliver 用于多 repo / submodule 场景的顺序提交与交付准备。",
     "ws-finish 用于 fast-forward 合并、push、change 分支清理，并在完整 finish 后自动归档 change。",
-    "ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。",
+    "ws-handoff 通常在 finish 自动归档后使用，用于查看/补充归档交接说明。"
   ],
   "stages": [
     {
@@ -58,6 +59,7 @@
     },
     {
       "stage": "ws-dev",
+      "gateBefore": "ws-plan-verify passed",
       "goal": "实施最小改动并验证",
       "requiredInputs": "真值文件；归因目标；计划（medium/complex）",
       "requiredOutputs": "Changed；Verify；Evidence；Next",
@@ -66,6 +68,7 @@
     },
     {
       "stage": "ws-review",
+      "gateBefore": "evaluate-optimize completed",
       "goal": "审计规范、风险与验证完整性",
       "requiredInputs": "当前 diff；验证结果；真值文件",
       "requiredOutputs": "review 文件；Top risks；Next",
@@ -78,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",
@@ -105,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 工件，不能只依赖会话上下文。",
     "每个阶段都必须有明确输出，不能只给“建议继续”而不留下工件或证据。",
@@ -127,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,7 +12,7 @@
 
 默认链路：
 
-`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 场景的顺序提交与交付准备。
@@ -21,18 +21,19 @@
 
 ## 阶段表
 
-| 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；Change 分支清理；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 接力 |
 
 ## 统一规则
 
@@ -49,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`
 

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

@@ -43,7 +43,8 @@
           "requiredInputs": { "type": "string", "minLength": 1 },
           "requiredOutputs": { "type": "string", "minLength": 1 },
           "blockers": { "type": "string", "minLength": 1 },
-          "next": { "type": "string", "minLength": 1 }
+          "next": { "type": "string", "minLength": 1 },
+          "gateBefore": { "type": "string", "minLength": 1 }
         },
         "additionalProperties": false
       }
@@ -53,6 +54,16 @@
       "minItems": 1,
       "items": { "type": "string", "minLength": 1 }
     },
+    "boundaryDescriptions": {
+      "type": "object",
+      "required": ["mainSession", "subagent", "handoff"],
+      "properties": {
+        "mainSession": { "type": "string", "minLength": 1 },
+        "subagent": { "type": "string", "minLength": 1 },
+        "handoff": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
     "evidence": {
       "type": "object",
       "required": ["intro", "minimum", "notes"],

package/package.json

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