@aipper/aiws-spec 0.0.23 → 0.0.25

package/docs/workflow-delegation-contracts.md

@@ -0,0 +1,248 @@
+# workflow-delegation-contracts
+
+<!-- Generated from packages/spec/docs/workflow-delegation-contracts.json by scripts/sync-workflow-delegation-contracts.mjs. Do not hand edit. -->
+
+## 目的
+
+这份文档把 `aiws` 对原生多 agent 的吸收边界收口为机器可读真值：`aiws` 定义合同、角色、写边界、工件路径、审查收敛与降级策略，各工具自己负责原生执行。
+
+重点不是统一调度不同工具的 agent API，而是约束任何 native delegation 都必须回到同一套 workflow/artifact/governance contract。
+
+## 真值入口
+
+delegation contract 在做任何角色拆分或原生多 agent 调用前，必须先读取：
+
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+
+## Delegation Flow
+
+| Step | Action | Why |
+| --- | --- | --- |
+| `bind_task` | 先把任务绑定到 `Req_ID` / change / Verify 入口，再决定是否允许委托。 | 没有绑定的委托只会扩大漂移；delegation 不能绕过真值入口。 |
+| `select_role` | 根据任务性质选择 `planner / explorer / worker / reviewer / integrator` 角色，而不是把所有子任务都视为同一种 agent。 | 不同角色的读写权限、输出契约与收敛方式不同。 |
+| `limit_scope` | 为每个委托声明 `readScope` / `writeScope` / `artifactTargets`，超出范围必须回退给主 agent。 | native 多 agent 的最大风险是越界写盘；scope 必须先于执行。 |
+| `converge_outputs` | 把委托结果统一收敛到 `analysis/`、`patches/`、`review/`、`evidence/` 或明确允许的代码写入范围。 | 即使执行方式不同，交付证据与审计路径必须一致。 |
+| `fallback_or_integrate` | 原生能力不可用、权限不满足或结果不可靠时，回退到单 agent / 手工委托；由主 agent 负责最终整合。 | `aiws` 的职责是治理和降级，不是保证每个工具都支持同一套运行时。 |
+
+## Role Types
+
+### `planner`
+
+拆分需求、明确非目标、绑定验证入口，产出计划与委托边界。
+
+**Read Scope**
+
+- AI_PROJECT.md
+- REQUIREMENTS.md
+- AI_WORKSPACE.md
+- plan/
+- changes/<id>/
+
+**Write Scope**
+
+- plan/
+- changes/<id>/analysis/
+
+**Artifact Targets**
+
+- plan/<timestamp>-<slug>.md
+- changes/<id>/analysis/*.md
+
+**Handoff Requirements**
+
+- 写明目标、非目标、范围、验证方式
+- 写明每个后续委托角色的 scope 边界
+
+### `explorer`
+
+只读探索代码库、定位影响面、收集实现信息，不直接改业务文件。
+
+**Read Scope**
+
+- repo source files
+- packages/spec/
+- changes/<id>/
+
+**Write Scope**
+
+- changes/<id>/analysis/
+
+**Artifact Targets**
+
+- changes/<id>/analysis/*.md
+
+**Handoff Requirements**
+
+- 结论必须附来源文件或路径
+- 对不确定项要显式标注风险或缺口
+
+### `worker`
+
+在明确授权的文件范围内实现局部改动，必要时补最小验证。
+
+**Read Scope**
+
+- assigned modules
+- AI_PROJECT.md
+- REQUIREMENTS.md
+- AI_WORKSPACE.md
+- changes/<id>/analysis/
+
+**Write Scope**
+
+- assigned source files
+- changes/<id>/patches/
+- changes/<id>/evidence/
+
+**Artifact Targets**
+
+- changes/<id>/patches/*.patch
+- changes/<id>/evidence/*.md
+- assigned source files
+
+**Handoff Requirements**
+
+- 写清改动文件、验证命令、未完成项
+- 不得越过显式授权的写入范围
+
+### `reviewer`
+
+从需求、实现质量、回归风险或交付 gate 角度做独立审查。
+
+**Read Scope**
+
+- repo source files
+- changes/<id>/analysis/
+- changes/<id>/patches/
+- changes/<id>/evidence/
+
+**Write Scope**
+
+- changes/<id>/review/
+- changes/<id>/evidence/
+
+**Artifact Targets**
+
+- changes/<id>/review/*.md
+- changes/<id>/evidence/verify-before-complete.md
+
+**Handoff Requirements**
+
+- 先列 findings，再给假设或残余风险
+- 明确这是 spec review、quality review 还是交付前验证
+
+### `integrator`
+
+主 agent 角色，负责汇总委托输出、决定是否应用改动、补齐最终验证与交接。
+
+**Read Scope**
+
+- repo source files
+- changes/<id>/analysis/
+- changes/<id>/patches/
+- changes/<id>/review/
+- changes/<id>/evidence/
+
+**Write Scope**
+
+- authorized source files
+- changes/<id>/evidence/
+- changes/<id>/review/
+- changes/<id>/handoff.md
+
+**Artifact Targets**
+
+- authorized source files
+- changes/<id>/evidence/*.md
+- changes/<id>/review/*.md
+- changes/<id>/handoff.md
+
+**Handoff Requirements**
+
+- 收敛 delegated outputs，给出最终结论与残余风险
+- 确认验证、review gate 与 artifact 状态
+
+## Artifact Targets
+
+| Kind | Path | Purpose | Allowed Roles |
+| --- | --- | --- | --- |
+| `analysis` | `changes/<id>/analysis/` | 只读分析、影响面、方案草案、风险说明。 | `planner`, `explorer`, `integrator` |
+| `patches` | `changes/<id>/patches/` | 委托 patch 草案或实现建议，不代表已应用。 | `worker`, `integrator` |
+| `review` | `changes/<id>/review/` | 多 reviewer 的 findings、双审查与最终审计结论。 | `reviewer`, `integrator` |
+| `evidence` | `changes/<id>/evidence/` | 验证命令、运行结果摘要、交付前 gate 证据。 | `worker`, `reviewer`, `integrator` |
+| `source_files` | `explicitly assigned source paths only` | 只有在主 agent 显式授权时，worker/integrator 才能直接改业务文件。 | `worker`, `integrator` |
+
+## Review Convergence
+
+**Required Reviews**
+
+- spec_review
+- quality_review
+
+**Optional Reviews**
+
+- verify_before_complete
+
+**Rules**
+
+- 多 agent review 不是投票系统；由 integrator 统一收敛 findings、假设与 blocker。
+- 若委托 worker 直接改了代码，必须至少再有一个独立 reviewer 做审查。
+- 交付前仍需满足现有 `validate_stamp`、`verify_before_complete` 与 finish gate。
+
+**Evidence Targets**
+
+- changes/<id>/review/spec-review.md
+- changes/<id>/review/quality-review.md
+- changes/<id>/evidence/verify-before-complete.md
+
+## Fallback Mode
+
+- default: `single_agent_with_artifacts`
+- triggers:
+  - 当前工具没有稳定的 native multi-agent 能力
+  - 当前工具支持原生 agent，但无法声明 write scope / artifact 边界
+  - native agent 结果无法审计、无法落盘或不能绑定 change/verify
+  - 任务规模太小，不值得引入额外委托复杂度
+- required behavior:
+  - 回退后仍使用同一套 `analysis/patches/review/evidence` 工件约定
+  - 主 agent 明确说明是原生 delegation 还是降级执行
+  - 不能因为降级而跳过 plan/review/finish gate
+
+## Tool Capability Matrix
+
+| Tool | Native Support | Status | Entrypoint | Write Isolation | Fallback |
+| --- | --- | --- | --- | --- | --- |
+| `codex` | `yes` | `phase1_target` | native multi-agent / sub-agent capability | 可按角色和文件范围显式约束；优先用于 explorer/worker/reviewer 分工。 | 若原生 delegation 不可用，则回退为单 agent + 协同工件模式。 |
+| `claude` | `partial` | `capability_matrix_only` | 后续根据稳定的 native delegation 能力补齐；当前只定义 contract 与 fallback。 | 若无法稳定声明 write scope，则不承诺 worker 级直接写盘委托。 | 优先回退为单 agent + review/artifact 模式，而不是临时造桥接 runtime。 |
+| `opencode` | `partial` | `capability_matrix_only` | 后续根据稳定的 native delegation 能力补齐；当前只定义 contract 与 fallback。 | 若不能稳定约束 read/write scope，则仅允许 analysis/review 型委托。 | 回退为单 agent + 协同工件，不新增 OpenCode 专属 runtime controller。 |
+
+### `codex` Notes
+
+- 作为第一优先适配对象。
+- 即使支持原生多 agent，也必须遵守 artifact path 与 review convergence 约定。
+
+### `claude` Notes
+
+- 本阶段不把 `aiws` 做成 `claude_code_bridge` 风格系统。
+- 先定义边界，再视工具能力补实现。
+
+### `opencode` Notes
+
+- 当前阶段先保证 workflow contract 与工件路径一致。
+- 不为了工具差异再造一层统一调度面。
+
+## Universal Rules
+
+- delegation 必须先绑定 `Req_ID` / change / Verify 入口，不能绕过真值文件。
+- 主 agent 必须显式说明每个 sub-task 的角色、scope、产物目标与收敛方式。
+- 除显式授权的 worker/integrator 外，delegated agent 默认不直接写业务文件。
+- 任何 native multi-agent 结果都必须能回收到 `analysis/patches/review/evidence` 约定路径。
+- native delegation 是可选执行策略，不是 workflow 的必需前提。
+
+## Notes
+
+- `aiws` 的价值在于治理内核和合同层，不在于成为统一 runtime。
+- 这一版先把 contract 写清，再决定哪些入口需要在模板里显式投影。
+- 后续若工具原生能力变化，只需要更新 capability matrix 与适配策略，不需要重写 workflow 真值。

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

@@ -0,0 +1,176 @@
+{
+  "type": "object",
+  "required": [
+    "version",
+    "title",
+    "description",
+    "purpose",
+    "truthFiles",
+    "delegationFlow",
+    "roleTypes",
+    "artifactTargets",
+    "reviewConvergence",
+    "fallbackMode",
+    "toolCapabilityMatrix",
+    "universalRules",
+    "notes"
+  ],
+  "properties": {
+    "version": { "type": "integer" },
+    "title": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "purpose": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "truthFiles": {
+      "type": "array",
+      "minItems": 3,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "delegationFlow": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["step", "action", "why"],
+        "properties": {
+          "step": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "action": { "type": "string", "minLength": 1 },
+          "why": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "roleTypes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "summary", "readScope", "writeScope", "artifactTargets", "handoffRequirements"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "summary": { "type": "string", "minLength": 1 },
+          "readScope": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "writeScope": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "artifactTargets": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "handoffRequirements": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "artifactTargets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["kind", "path", "purpose", "allowedRoles"],
+        "properties": {
+          "kind": { "type": "string", "minLength": 1, "pattern": "^[a-z_]+$" },
+          "path": { "type": "string", "minLength": 1 },
+          "purpose": { "type": "string", "minLength": 1 },
+          "allowedRoles": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "reviewConvergence": {
+      "type": "object",
+      "required": ["requiredReviews", "optionalReviews", "rules", "evidenceTargets"],
+      "properties": {
+        "requiredReviews": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1, "pattern": "^[a-z_]+$" }
+        },
+        "optionalReviews": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1, "pattern": "^[a-z_]+$" }
+        },
+        "rules": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "evidenceTargets": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "fallbackMode": {
+      "type": "object",
+      "required": ["default", "triggers", "requiredBehavior"],
+      "properties": {
+        "default": { "type": "string", "minLength": 1 },
+        "triggers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "requiredBehavior": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "toolCapabilityMatrix": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["tool", "nativeSupport", "status", "entrypoint", "writeIsolation", "fallbackRoute", "notes"],
+        "properties": {
+          "tool": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_-]+$" },
+          "nativeSupport": { "type": "string", "minLength": 1, "enum": ["yes", "partial", "no"] },
+          "status": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" },
+          "entrypoint": { "type": "string", "minLength": 1 },
+          "writeIsolation": { "type": "string", "minLength": 1 },
+          "fallbackRoute": { "type": "string", "minLength": 1 },
+          "notes": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "universalRules": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "notes": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}