@aipper/aiws-spec 0.0.27 → 0.0.29

package/docs/workflow-delegation-context-injection.md

@@ -0,0 +1,217 @@
+# Workflow Delegation Context Injection
+
+<!-- Managed by aiws. Do not hand edit. -->
+
+**规范 ID**: `workflow-delegation-context-injection`
+**版本**: 1
+
+## 目的
+
+定义 delegation 场景下，主 agent（integrator）如何为子 agent（delegated subagent）**策划并交付上下文**，让子 agent 在第一次尝试时就能获取到正确的约束与信息，减少因遗漏关键文件导致的重试与审查循环。
+
+本规范的适用范围：
+- 主 agent 派遣 worker / reviewer / explorer 等子 agent 前
+- 需要明确告知子 agent 项目约束、委托合同、分配模块、计划文件与相关分析成果时
+- 上下文超出子 agent prompt 容量时（通过 sections + priority 管理预算）
+
+**非目标**：
+- 替代子 agent 自身的代码搜索能力（grep / glob / 文件遍历）
+- 保证子 agent 一定读取并理解所有注入的上下文（最终依赖 LLM 遵从度）
+
+## 上下文文件格式
+
+### 定义
+
+上下文信息通过一个 **JSONL（JSON Lines）** 文件传递。每行一个 JSON 对象，代表一个需要子 agent 读取的引用文件。
+
+文件命名约定：
+
+```
+changes/<id>/analysis/<role>-context.jsonl
+```
+
+其中：
+- `<id>`：当前 change 的 identifier
+- `<role>`：子 agent 的角色（worker / explorer / reviewer / planner / integrator）
+
+### 字段定义
+
+| 字段 | 必需 | 类型 | 描述 |
+|------|------|------|------|
+| `file` | ✅ | `string` | 相对于仓库根的文件路径 |
+| `reason` | ✅ | `string` | **为什么此文件相关**。子 agent 通过此字段理解该文件的阅读目的与上下文锚点。应包含具体条款引用或原因说明 |
+| `sections` | ❌ | `[[int,int], ...]` | 针对大文件的精确行范围（1-indexed）。缺省或 `null` 表示读取整个文件 |
+| `priority` | ✅ | `"high" \| "medium" \| "low"` | 上下文预算管理。子 agent 按优先级顺序读取；窗口不足时可跳过低优先级 |
+| `kind` | ❌ | `string` | 认知分类标签。帮助子 agent 理解阅读目的（约束型 vs 实现型 vs 历史型）。可选值见下方 |
+
+### 可选 kind 值
+
+| kind | 含义 | 示例文件 |
+|------|------|----------|
+| `truth` | 项目真值、约束、规则 | `AI_PROJECT.md`, `REQUIREMENTS.md` |
+| `contract` | 委托合同、角色边界 | `workflow-delegation-contracts.md` |
+| `adapter` | 工具适配规则 | `opencode-omo-adapter.md` |
+| `assigned` | 本次分配的模块代码 | `src/auth/login.ts` |
+| `plan` | 变更计划 | `changes/<id>/plan/session-*.md` |
+| `analysis` | 影响分析、方案分析 | `changes/<id>/analysis/impact.md` |
+| `evidence` | 验证证据基线 | `changes/<id>/evidence/*.md` |
+| `handoff` | 交接说明 | `changes/<id>/handoff.md` |
+
+### 完整示例
+
+```jsonl
+{"file":"AI_PROJECT.md","reason":"第25-50行：安全与边界强制条款；第95-106行：产物与证据强制条款","sections":[[25,50],[95,106]],"priority":"high","kind":"truth"}
+{"file":"packages/spec/docs/workflow-delegation-contracts.md","reason":"Worker 角色的 readScope/writeScope/artifactTargets 边界定义（第84-107行）；通用规则（第236-243行）","sections":[[84,107],[236,243]],"priority":"high","kind":"contract"}
+{"file":"packages/spec/docs/opencode-omo-adapter.md","reason":"委托给 oMo agent 时的回退规则与执行约定","sections":[[1,30],[245,254]],"priority":"medium","kind":"adapter"}
+{"file":"src/auth/login.ts","reason":"分配的模块——身份验证核心逻辑：LoginService.login() 方法","sections":null,"priority":"high","kind":"assigned"}
+{"file":"changes/demo-change/plan/session-20260515-auth-refactor.md","reason":"变更计划——目标/非目标/范围/步骤/验证命令","sections":null,"priority":"high","kind":"plan"}
+{"file":"changes/demo-change/analysis/impact.md","reason":"影响分析——调用 login() 的所有函数清单及调用链","sections":null,"priority":"medium","kind":"analysis"}
+{"file":"changes/demo-change/evidence/pre-refactor-test-run.md","reason":"重构前测试基线——当前测试通过状态与覆盖率","sections":null,"priority":"low","kind":"evidence"}
+```
+
+## OpenCode 插件集成
+
+aiws 提供了两个 OpenCode 插件，自动实现上下文注入：
+
+### aiws-session-start（chat.message hook）
+
+每个新会话启动时，自动读取当前 change 上下文、项目真值、规范索引，并注入到第一条用户消息中。
+
+**注入内容**：
+- `<aiws-context>` 声明块
+- `getContextSummary()` 输出（change ID、绑定状态等）
+- `getSpecIndex()` 输出（可用的规范索引清单）
+- 可用 spec discovery 提示
+
+当插件被激活时，主 agent 启动会话即获得项目状态概览，无需手动阅读真值文件。
+
+### aiws-inject-context（tool.execute.before hook）
+
+当 `task()` 调用且 prompt 中包含 `role: <role>` 标记时自动拦截，读取 `changes/<id>/analysis/<role>-context.jsonl` 并注入到子 agent prompt。
+
+**自动注入内容**：
+1. JSONL 中引用的每个文件内容（按 priority 排序）
+2. `<aiws-context-injection>` 头部（含 role、context file 路径、entry 数量）
+3. 粘性指令：要求子 agent 先读上下文文件再工作
+
+当插件被激活时，主 agent 不需要手动粘性指令模板——插件会自动生成。
+
+### 配置方法
+
+本地插件放在 `.opencode/plugins/` 后由 OpenCode 启动时自动加载；`.opencode/opencode.json` 仅保留合法 schema 声明，若需要显式注册 npm/远程插件则使用 OpenCode 1.15 的 `plugin`（单数）字段。
+
+## 策展流程
+
+上下文文件由委托者在派遣子 agent 前通过**三层混合模式**策展：
+
+### 第 0 层：静态基线（合同定义）
+
+`workflow-delegation-contracts.json` 中每个角色类型（`roleTypes[]`）可选的 `contextFiles` 属性定义了该角色**总是需要**的上下文基线。使用 glob 模式表达。
+
+示例（worker 角色）：
+
+```json
+"contextFiles": [
+  {"glob": "AI_PROJECT.md",                    "sections": [[25, 50], [95, 106]],               "priority": "high",   "kind": "truth"},
+  {"glob": "REQUIREMENTS.md",                  "sections": [[1, 100]],                           "priority": "high",   "kind": "truth"},
+  {"glob": "AI_WORKSPACE.md",                  "priority": "medium", "kind": "truth"},
+  {"glob": "packages/spec/docs/workflow-delegation-contracts.md", "sections": [[84, 107], [236, 243]],   "priority": "high",   "kind": "contract"},
+  {"glob": "changes/<id>/plan/*.md",                                                  "priority": "high",   "kind": "plan"},
+  {"glob": "changes/<id>/analysis/*.md",                                              "priority": "medium", "kind": "analysis"},
+  {"glob": "changes/<id>/evidence/*.md",                                              "priority": "low",    "kind": "evidence"}
+]
+```
+
+### 第 1 层：自动展开（预派遣）
+
+在派遣子 agent 前，主 agent 或预派遣脚本执行：
+1. 读取角色的 `contextFiles` 条目
+2. 将 `<id>` 替换为实际 change-id
+3. 将 glob 模式展开为具体文件路径（使用 `glob` 工具）
+4. 从 `writeScope` / `readScope` 推导"分配的模块"，添加 `kind: "assigned"` 条目
+5. 输出 JSONL 基线
+
+### 第 2 层：委托者覆盖（手工调整）
+
+主 agent（integrator）在写入前：
+1. 添加任务特定的文件（如当前 plan 文件、新影响分析）
+2. 删除不相关的条目（如旧的分析/证据文件）
+3. 重新排序或调整 priority/sections
+4. 执行预算检查（见下文）
+5. 写入 `changes/<id>/analysis/<role>-context.jsonl`
+
+### 策展决策记录
+
+当策展过程产生非平凡决策时（如删除了 3 个文件、将某个文件从 high 降为 medium），应在 JSONL 文件头部以 JSON 注释形式记录：
+
+```jsonl
+// curation: trimmed from 8 to 5 files; excluded changes/demo/evidence/stale-test.md (unrelated)
+// curation: downgraded changes/demo/analysis/impact.md from high to medium (too broad; only lines 50-70 relevant)
+```
+
+## 上下文预算管理
+
+子 agent 的上下文窗口有限。策展者必须执行预算检查：
+
+### 预算规则
+
+1. **5 文件软上限**：统计 `priority=high` + `medium` 的文件数。若超过 5 个，删除所有 `low` 条目并输出警告
+2. **4000 行硬上限**：估算每个文件的真实行数（通过 `git show HEAD:<path> \| wc -l` 或类似命令）。若总行数超过 4000：
+   - 优先用 `sections` 缩小范围
+   - 若仍超出，删除所有 `medium`，仅保留 `high`
+   - 若无法切分，考虑将任务拆分为更小的子任务
+3. **零文件阻断**：若最终文件数 = 0，返回 `BLOCKED`，不派遣
+
+### 优先级回退顺序
+
+子 agent 应按照 `priority` 顺序读取文件：
+1. 先读取所有 `high` 文件
+2. 若上下文窗口允许，再读取 `medium`
+3. 若窗口仍有空间，最后读取 `low`
+
+当文件内容超出子 agent 上下文时，子 agent 可选择：
+- 仅读取指定 sections（若有提供）
+- 仅读取文件的开头部分（若未指定 sections）
+- 跳过 `low` 优先级并记录"上下文预算超限，已跳过下列文件：..."
+
+## 粘性指令模板
+
+当主 agent 通过 `task()` 调用派遣子 agent 时，子 agent prompt 的**第一条指令**必须包含以下内容：
+
+```
+## ⚠️ 上下文文件（必需——开始任何工作前执行）
+
+你必须首先读取 `{contextJsonlPath}`。此文件列出你必须在开始工作前了解的文件，包括项目约束、委托合同、变更计划与分配模块。
+
+**执行步骤**:
+1. 使用 Read 工具打开 JSONL 文件
+2. 按 priority 顺序读取每个文件（high → medium → low）
+3. 若文件有 `sections` 字段且行数超过 200，仅读取指定行范围
+4. 若无法访问任何文件，返回 `NEEDS_CONTEXT`——立即停止，不要猜测内容
+
+**确认（你的第一条回复）**:
+列出你已读取的文件及每个文件的关键要点（≤3 要点/文件）。
+```
+
+## 与委托合同的关系
+
+| | 委托合同（delegation-contracts.json） | 上下文文件（<role>-context.jsonl） |
+|---|---|---|
+| **目的** | 定义角色的**总是需要什么**（团队共识、静态知识） | 定义**本次派遣需要什么**（任务特定、运行时） |
+| **内容** | glob 模式 + 默认 sections/priority/kind | 展开的具体文件路径 + 委托者调整后的信息 |
+| **生命周期** | 跨项目、跨会话不变 | 每次派遣重新生成 |
+| **提交到 git？** | 是（在 `packages/spec/`） | 是（在 `changes/<id>/analysis/`） |
+| **谁维护** | 项目维护者 | 委托者（主 agent） |
+
+委托合同定义"规则"，上下文文件是规则的运行时实例化。合同中的 `contextFiles` 是**可选**字段——未填充时，系统行为与现有完全一致。
+
+## 安全注意事项
+
+1. **JSONL 不应包含 secrets 引用**——委托者策展时不能将 `secrets/`、`.env*`、token 等路径写入 JSONL
+2. **子 agent 无法访问 JSONL 时的处理**——返回 `NEEDS_CONTEXT`，后续见 Subagent Status Protocol 的 BLOCKED/NEEDS_CONTEXT 处理
+3. **JSONL 文件本身是 change 工件**——提交在 `changes/<id>/analysis/` 中，使审计者可以追溯"子 agent 被赋予了怎样的上下文"
+
+## 更新历史
+
+- v1 (2026-05-15): 初版。基于 trellis 的 JSONL 上下文注入模式 + aiws delegation contract 三层策展模型设计。
+- v1.1 (2026-05-15): 新增 OpenCode 插件集成描述（aiws-session-start / aiws-inject-context）并移除"不提供平台级 hooks"的约束。

package/docs/workflow-delegation-contracts.json

@@ -22,6 +22,11 @@
       "action": "根据任务性质选择 `planner / explorer / worker / reviewer / integrator` 角色，而不是把所有子任务都视为同一种 agent。",
       "why": "不同角色的读写权限、输出契约与收敛方式不同。"
     },
+    {
+      "step": "curate_context",
+      "action": "为子 agent 策划上下文文件（changes/<id>/analysis/<role>-context.jsonl），参阅 workflow-delegation-context-injection.md。",
+      "why": "子 agent 在第一次尝试时拿到正确的上下文，减少重试与审查循环。"
+    },
     {
       "step": "limit_scope",
       "action": "为每个委托声明 `readScope` / `writeScope` / `artifactTargets`，超出范围必须回退给主 agent。",
@@ -60,6 +65,13 @@
       "handoffRequirements": [
         "写明目标、非目标、范围、验证方式",
         "写明每个后续委托角色的 scope 边界"
+      ],
+      "contextFiles": [
+        {"glob": "AI_PROJECT.md", "priority": "high", "kind": "truth"},
+        {"glob": "REQUIREMENTS.md", "priority": "high", "kind": "truth"},
+        {"glob": "AI_WORKSPACE.md", "priority": "medium", "kind": "truth"},
+        {"glob": "changes/<id>/analysis/*.md", "priority": "medium", "kind": "analysis"},
+        {"glob": "changes/<id>/evidence/verify-before-complete.md", "priority": "low", "kind": "evidence"}
       ]
     },
     {
@@ -79,6 +91,11 @@
       "handoffRequirements": [
         "结论必须附来源文件或路径",
         "对不确定项要显式标注风险或缺口"
+      ],
+      "contextFiles": [
+        {"glob": "AI_PROJECT.md", "sections": [[25, 50], [95, 106]], "priority": "high", "kind": "truth"},
+        {"glob": "changes/<id>/plan/*.md", "priority": "high", "kind": "plan"},
+        {"glob": "changes/<id>/analysis/*.md", "priority": "medium", "kind": "analysis"}
       ]
     },
     {
@@ -104,6 +121,16 @@
       "handoffRequirements": [
         "写清改动文件、验证命令、未完成项",
         "不得越过显式授权的写入范围"
+      ],
+      "contextFiles": [
+        {"glob": "AI_PROJECT.md", "sections": [[25, 50], [95, 106]], "priority": "high", "kind": "truth"},
+        {"glob": "REQUIREMENTS.md", "sections": [[1, 100]], "priority": "high", "kind": "truth"},
+        {"glob": "AI_WORKSPACE.md", "priority": "medium", "kind": "truth"},
+        {"glob": "packages/spec/docs/workflow-delegation-contracts.md", "sections": [[84, 107], [236, 243]], "priority": "high", "kind": "contract"},
+        {"glob": "packages/spec/docs/workflow-delegation-context-injection.md", "priority": "high", "kind": "contract"},
+        {"glob": "changes/<id>/plan/*.md", "priority": "high", "kind": "plan"},
+        {"glob": "changes/<id>/analysis/*.md", "priority": "medium", "kind": "analysis"},
+        {"glob": "changes/<id>/evidence/*.md", "priority": "low", "kind": "evidence"}
       ]
     },
     {
@@ -126,6 +153,14 @@
       "handoffRequirements": [
         "先列 findings，再给假设或残余风险",
         "明确这是 spec review、quality review 还是交付前验证"
+      ],
+      "contextFiles": [
+        {"glob": "AI_PROJECT.md", "sections": [[25, 50], [95, 106]], "priority": "high", "kind": "truth"},
+        {"glob": "REQUIREMENTS.md", "priority": "high", "kind": "truth"},
+        {"glob": "changes/<id>/plan/*.md", "priority": "high", "kind": "plan"},
+        {"glob": "changes/<id>/analysis/*.md", "priority": "medium", "kind": "analysis"},
+        {"glob": "changes/<id>/patches/*.patch", "priority": "high", "kind": "assigned"},
+        {"glob": "changes/<id>/evidence/*.md", "priority": "medium", "kind": "evidence"}
       ]
     },
     {
@@ -207,6 +242,36 @@
       "changes/<id>/evidence/verify-before-complete.md"
     ]
   },
+  "subagentStatusProtocol": {
+    "title": "Subagent Status Protocol",
+    "description": "四状态返回协议：定义 subagent 完成后返回的状态值及主 agent 的处理动作。",
+    "states": [
+      { "status": "DONE",               "meaning": "任务完成 + 验证通过 + 证据路径有效", "allowedNextRoles": ["reviewer", "integrator"] },
+      { "status": "DONE_WITH_CONCERNS", "meaning": "实现完成但边角情况未全覆盖 / 质量有残余风险", "allowedNextRoles": ["reviewer"] },
+      { "status": "NEEDS_CONTEXT",      "meaning": "subagent 从给定 scope 无法继续，缺关键上下文", "allowedNextRoles": ["planner", "explorer"] },
+      { "status": "BLOCKED",            "meaning": "治理规则阻断（缺工件、dirty 工作区、validate 失败等）", "allowedNextRoles": ["integrator"] }
+    ],
+    "handlerResponses": [
+      { "forStatus": "DONE",               "response": "进入 ws-review; 若已过 review 则准备 ws-finish" },
+      { "forStatus": "DONE_WITH_CONCERNS", "response": "先执行 ws-quality-review，根据残余风险决定是否阻断 ws-finish" },
+      { "forStatus": "NEEDS_CONTEXT",      "response": "主 agent 补充缺失上下文后重新委托同一 subagent（最多 2 次）；若仍 NEEDS_CONTEXT → 回退单 agent" },
+      { "forStatus": "BLOCKED",            "response": "停止委托流程；输出 blocker 详情；主 agent 解 blocker 后重试" }
+    ]
+  },
+  "workflowPatterns": [
+    {
+      "id": "worker_reviewer_loop",
+      "description": "默认实现审查闭环：worker dispatch → status check → reviewer dispatch → pass/fail → loop back to worker if fail",
+      "steps": [
+        { "step": "dispatch_worker", "action": "主 session 策展上下文后派发 aiws-worker", "input": "curated JSONL context + plan", "output": "worker status + patches/ + evidence/" },
+        { "step": "check_worker_status", "action": "检查 worker 返回状态", "condition": "DONE → 进入 dispatch_reviewer; DONE_WITH_CONCERNS → 先 ws-quality-review; NEEDS_CONTEXT → 补充上下文重试; BLOCKED → 升级给人类" },
+        { "step": "dispatch_reviewer", "action": "派发 aiws-reviewer 审查实现", "input": "patches/ + analysis/ + evidence/", "output": "reviewer findings + pass/fail" },
+        { "step": "check_reviewer_result", "action": "审查结果判定", "condition": "pass → 主 session 收敛准备 ws-finish; fail → 返回 worker 修复（最多 3 次循环）" },
+        { "step": "loop_back_worker", "action": "reviewer fail 后返回 worker 修复", "maxRetries": 3, "fallback": "升级给人类决策" },
+        { "step": "converge", "action": "主 session 收敛最终 patch + evidence + review 到 changes/<id>/", "output": "changes/<id>/evidence/*.md + changes/<id>/review/*.md" }
+      ]
+    }
+  ],
   "fallbackMode": {
     "default": "single_agent_with_artifacts",
     "triggers": [
@@ -262,6 +327,7 @@
   "universalRules": [
     "delegation 必须先绑定 `Req_ID` / change / Verify 入口，不能绕过真值文件。",
     "主 agent 必须显式说明每个 sub-task 的角色、scope、产物目标与收敛方式。",
+    "主 agent 必须在派遣前执行上下文策展并写入 JSONL 上下文文件。",
     "除显式授权的 worker/integrator 外，delegated agent 默认不直接写业务文件。",
     "任何 native multi-agent 结果都必须能回收到 `analysis/patches/review/evidence` 约定路径。",
     "native delegation 是可选执行策略，不是 workflow 的必需前提。"
@@ -269,6 +335,7 @@
   "notes": [
     "`aiws` 的价值在于治理内核和合同层，不在于成为统一 runtime。",
     "这一版先把 contract 写清，再决定哪些入口需要在模板里显式投影。",
-    "后续若工具原生能力变化，只需要更新 capability matrix 与适配策略，不需要重写 workflow 真值。"
+    "后续若工具原生能力变化，只需要更新 capability matrix 与适配策略，不需要重写 workflow 真值。",
+    "v1.1: 新增 curate_context 流程步骤 + roleTypes[].contextFiles 基线 + 上下文策展 universal 规则。"
   ]
 }

package/docs/workflow-delegation-contracts.md

@@ -22,6 +22,7 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 | --- | --- | --- |
 | `bind_task` | 先把任务绑定到 `Req_ID` / change / Verify 入口，再决定是否允许委托。 | 没有绑定的委托只会扩大漂移；delegation 不能绕过真值入口。 |
 | `select_role` | 根据任务性质选择 `planner / explorer / worker / reviewer / integrator` 角色，而不是把所有子任务都视为同一种 agent。 | 不同角色的读写权限、输出契约与收敛方式不同。 |
+| `curate_context` | 为子 agent 策划上下文文件（changes/<id>/analysis/<role>-context.jsonl），参阅 workflow-delegation-context-injection.md。 | 子 agent 在第一次尝试时拿到正确的上下文，减少重试与审查循环。 |
 | `limit_scope` | 为每个委托声明 `readScope` / `writeScope` / `artifactTargets`，超出范围必须回退给主 agent。 | native 多 agent 的最大风险是越界写盘；scope 必须先于执行。 |
 | `converge_outputs` | 把委托结果统一收敛到 `analysis/`、`patches/`、`review/`、`evidence/` 或明确允许的代码写入范围。 | 即使执行方式不同，交付证据与审计路径必须一致。 |
 | `fallback_or_integrate` | 原生能力不可用、权限不满足或结果不可靠时，回退到单 agent / 手工委托；由主 agent 负责最终整合。 | `aiws` 的职责是治理和降级，不是保证每个工具都支持同一套运行时。 |
@@ -237,6 +238,7 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 
 - delegation 必须先绑定 `Req_ID` / change / Verify 入口，不能绕过真值文件。
 - 主 agent 必须显式说明每个 sub-task 的角色、scope、产物目标与收敛方式。
+- 主 agent 必须在派遣前执行上下文策展并写入 JSONL 上下文文件。
 - 除显式授权的 worker/integrator 外，delegated agent 默认不直接写业务文件。
 - 任何 native multi-agent 结果都必须能回收到 `analysis/patches/review/evidence` 约定路径。
 - native delegation 是可选执行策略，不是 workflow 的必需前提。
@@ -246,3 +248,4 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 - `aiws` 的价值在于治理内核和合同层，不在于成为统一 runtime。
 - 这一版先把 contract 写清，再决定哪些入口需要在模板里显式投影。
 - 后续若工具原生能力变化，只需要更新 capability matrix 与适配策略，不需要重写 workflow 真值。
+- v1.1: 新增 curate_context 流程步骤 + roleTypes[].contextFiles 基线 + 上下文策展 universal 规则。

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

@@ -10,6 +10,7 @@
     "roleTypes",
     "artifactTargets",
     "reviewConvergence",
+    "subagentStatusProtocol",
     "fallbackMode",
     "toolCapabilityMatrix",
     "universalRules",
@@ -71,6 +72,30 @@
             "type": "array",
             "minItems": 1,
             "items": { "type": "string", "minLength": 1 }
+          },
+          "contextFiles": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["glob", "priority", "kind"],
+              "properties": {
+                "glob": { "type": "string", "minLength": 1 },
+                "sections": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "items": { "type": "integer", "minimum": 1 }
+                  }
+                },
+                "priority": { "type": "string", "enum": ["high", "medium", "low"] },
+                "kind": { "type": "string", "minLength": 1 }
+              },
+              "additionalProperties": false
+            }
           }
         },
         "additionalProperties": false
@@ -121,6 +146,46 @@
       },
       "additionalProperties": false
     },
+    "subagentStatusProtocol": {
+      "type": "object",
+      "required": ["title", "description", "states", "handlerResponses"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "states": {
+          "type": "array",
+          "minItems": 4,
+          "items": {
+            "type": "object",
+            "required": ["status", "meaning", "allowedNextRoles"],
+            "properties": {
+              "status": { "type": "string", "pattern": "^(DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED)$" },
+              "meaning": { "type": "string", "minLength": 1 },
+              "allowedNextRoles": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string", "minLength": 1 }
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "handlerResponses": {
+          "type": "array",
+          "minItems": 4,
+          "items": {
+            "type": "object",
+            "required": ["forStatus", "response"],
+            "properties": {
+              "forStatus": { "type": "string", "pattern": "^(DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED)$" },
+              "response": { "type": "string", "minLength": 1 }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "fallbackMode": {
       "type": "object",
       "required": ["default", "triggers", "requiredBehavior"],
@@ -161,6 +226,36 @@
         "additionalProperties": false
       }
     },
+    "workflowPatterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "steps"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9_]+$", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "steps": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["step", "action"],
+              "properties": {
+                "step": { "type": "string", "pattern": "^[a-z0-9_]+$", "minLength": 1 },
+                "action": { "type": "string", "minLength": 1 },
+                "condition": { "type": "string" },
+                "input": { "type": "string" },
+                "output": { "type": "string" },
+                "maxRetries": { "type": "integer", "minimum": 1 },
+                "fallback": { "type": "string" }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "universalRules": {
       "type": "array",
       "minItems": 1,

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

@@ -12,7 +12,7 @@
 - version: `1`
 - 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 |