@aipper/aiws-spec 0.0.28 → 0.0.30

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"}
       ]
     },
     {
@@ -125,7 +152,16 @@
       ],
       "handoffRequirements": [
         "先列 findings，再给假设或残余风险",
+        "产出结构化 findings：[Critical] 阻塞问题；[Warning] 应修复项；[Info] 建议改进（对齐 reworkLoopProtocol.findingSeverities）",
         "明确这是 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"}
       ]
     },
     {
@@ -152,7 +188,8 @@
       ],
       "handoffRequirements": [
         "收敛 delegated outputs，给出最终结论与残余风险",
-        "确认验证、review gate 与 artifact 状态"
+        "确认验证、review gate 与 artifact 状态",
+        "记录每轮 rework 回合数、已修复/剩余 Critical 与 Warning 数量（对齐 reworkLoopProtocol.handoffRecording）"
       ]
     }
   ],
@@ -207,6 +244,46 @@
       "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 后重试" }
+    ]
+  },
+  "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",
+      "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,13 +339,42 @@
   "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 的必需前提。"
   ],
+  "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 写清，再决定哪些入口需要在模板里显式投影。",
-    "后续若工具原生能力变化，只需要更新 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` 的职责是治理和降级，不是保证每个工具都支持同一套运行时。 |
@@ -131,6 +132,7 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 **Handoff Requirements**
 
 - 先列 findings，再给假设或残余风险
+- 产出结构化 findings：[Critical] 阻塞问题；[Warning] 应修复项；[Info] 建议改进（对齐 reworkLoopProtocol.findingSeverities）
 - 明确这是 spec review、quality review 还是交付前验证
 
 ### `integrator`
@@ -163,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
 
@@ -237,6 +248,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 +258,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,8 @@
     "roleTypes",
     "artifactTargets",
     "reviewConvergence",
+    "subagentStatusProtocol",
+    "reworkLoopProtocol",
     "fallbackMode",
     "toolCapabilityMatrix",
     "universalRules",
@@ -71,6 +73,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 +147,65 @@
       },
       "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
+    },
+    "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"],
@@ -161,6 +246,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,
@@ -170,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