@aipper/aiws-spec 0.0.42 → 0.0.43

package/docs/aiws-bootstrap-routing-design.md

@@ -42,12 +42,14 @@
 
 1. 先进入 bootstrap：
    - 读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
-2. 识别任务意图：
-   - 规划类 -> `ws-plan`
-   - 实现类 -> `ws-dev` / `ws-execute` / `ws-subagent-dev`
-   - 评审类 -> `ws-review`（后续拆分成 `ws-spec-review` + `ws-quality-review`）
-   - 收尾类 -> `ws-finish`
-   - 交接类 -> `ws-handoff`
+2. 识别任务意图与复杂度：
+   - **中等复杂度以上**（跨文件改动、多模块、2+ 步骤、含验证要求）→ 自动路由到 `ws-goal` 作为默认入口，由 ws-goal 再拆分为 PLAN → DEV → REVIEW → FINISH
+   - **简单任务**（单文件、≤3 文件改动、无跨模块依赖）→ 直接进入 `ws-dev` / `ws-dev-lite`
+   - 规划类 → `ws-plan`
+   - 实现类 → `ws-dev` / `ws-execute` / `ws-subagent-dev`
+   - 评审类 → `ws-review`（后续拆分成 `ws-spec-review` + `ws-quality-review`）
+   - 收尾类 → `ws-finish`
+   - 交接类 → `ws-handoff`
 3. 若意图不明确：
    - 阻断，先澄清任务归因与目标
 
@@ -91,3 +93,6 @@
    - `ws-quality-review`
    - `ws-verify-before-complete`
    - 当前已由 `TOOLING-002I` 落地
+5. **ws-goal 路由默认**：
+   - 中等复杂度以上任务自动路由到 `ws-goal` 作为默认入口
+   - 由本轮优化（P3→router default）新增

package/docs/run-behavior-guidelines.md

@@ -0,0 +1,32 @@
+# 运行时行为约束指引（Run Behavior Guidelines）
+
+本文件定义了 agent 在工作流 skill 中的输出行为约束，是运行时 token 优化的 SSOT。
+
+所有引用本文件的 skill 必须遵守以下约束，不得在 skill 内额外 inline 重复相同规则。
+
+---
+
+## 核心约束（强制）
+
+### 1. 最小叙述原则
+
+- 工具调用之间：最多一行状态叙述（"定位中"、"验证中"、"写入文件 X"）。
+- 禁止：过程推理（"我先读 X，发现 Y，考虑 Z，接下来准备做 A"）。
+- 禁止：重复复述你刚从工具输出读到的内容。
+
+### 2. 无废话输出
+
+- 无开场白：不要以"我来帮你..."/"让我先..."/"好的！"开头。直接行动。
+- 无过程叙述：不解释你正在做什么的中间状态。工具调用之间的消息只输出最小必要信息。
+- 无总结收尾：不重复已经在证据文件中的内容。完成即停。
+
+### 3. 工具调用效率
+
+- 首选在 3 次工具调用内产出完整结果。
+- 不把 1 步拆成 4 步：能一次读 2000 行就不要限 500+500+500+500。
+- 不在同一文件上反复 Read/Write。尽量一次读完，一次写完。
+
+### 4. 输出格式
+
+- 使用 todo 追踪进度，不在对话里列清单。
+- 回答直接回应问题，不绕弯子。

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

@@ -193,6 +193,57 @@ aiws 提供了两个 OpenCode 插件，自动实现上下文注入：
 列出你已读取的文件及每个文件的关键要点（≤3 要点/文件）。
 ```
 
+## Context Minimum Gate (P1)
+
+### 用途
+
+确保子 agent 在开始编码之前确实读取了必需的上下文文件，而非仅声明"已读"后直接跳入实现。这是对 §粘性指令模板 的强化——把"建议读取"变为"必须先声明已读及理解要点，再开始编码"。
+
+### 声明门禁
+
+子 agent 的第一条回复**必须**满足以下格式，不得直接开始编码或返回实现代码：
+
+```
+## Context Declaration
+
+已读文件及关键要点：
+
+1. `{file-path}`（high）:
+   - {要点 1}
+   - {要点 2}
+
+2. `{file-path}`（medium）:
+   - {要点 1}
+
+开始编码条件：以上所有 high + medium 文件均已读取并理解。若条件不满足，此处列出缺失文件。
+```
+
+**约束**：
+- 必须先列出 `high` 文件，再列 `medium`。`low` 文件可选
+- 每个文件至少 1 个要点，要点必须从文件中**具体引用**（非泛泛总结）。例如"AI_PROJECT.md 第 25-30 行禁止将 secrets 写入 git"而非"项目有安全规范"
+- 未列出 `high` 文件的要点 → 主 agent 应要求补充，不继续
+- 子 agent 直接返回代码实现而不声明 → 主 agent 应阻断、要求先声明，第二次违规视为 CLASS-C 失败
+
+### 信任缺口
+
+声明门禁无法完全确保子 agent **实际**读取了文件而非仅"记住了要点格式"。子 agent 可能：
+- 根据训练数据推断常见文件内容而不实际读取
+- 从 prompt 上下文推理而非从文件读取
+- 声明读了但未获取最新版本文件
+
+推荐验证方法：
+- **抽查**：要求子 agent 引用某个文件的精确行号内容（如"AI_PROJECT.md 第 25 行的原文是什么?"）
+- **交叉验证**：对同一组上下文，委托 2 个不同子 agent，对比它们的要点是否一致
+- 验证仅建议在质量不一致时执行，不作为每次委托的强制步骤
+
+### 升级路径
+
+此 Gate 当前为 **P1（验证后定级）**：
+1. 先在委托 prompt 模板中加上声明要求（已完成）
+2. 手动验证至少 3 次委托，检查子 agent 是否真的读取了声明的文件
+3. 若 >80% 的委托中声明与实际读取一致 → 升级为 P0（写入 delegation contract 成为强制门禁，增加随机抽查）
+4. 若 ≤80% 声明不反映实际读取 → 保留 P1，不升级，转而探索其他上下文注入方案（如插件级自动注入）
+
 ## 与委托合同的关系
 
 | | 委托合同（delegation-contracts.json） | 上下文文件（<role>-context.jsonl） |

package/docs/workflow-delegation-contracts.json

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": 2,
   "title": "workflow-delegation-contracts",
   "description": "Machine-readable delegation contract for using native multi-agent capabilities without turning aiws into a runtime orchestrator.",
   "purpose": [
@@ -37,6 +37,11 @@
       "action": "把委托结果统一收敛到 `analysis/`、`patches/`、`review/`、`evidence/` 或明确允许的代码写入范围。",
       "why": "即使执行方式不同，交付证据与审计路径必须一致。"
     },
+    {
+      "step": "verify_output",
+      "action": "委托完成后，按子 agent 声明的 `output_manifest` 做 glob 检查 + 最小内容检查（≥3 行非空白内容）。缺失或质量不足时分类处理：CLASS-A（零文件→拆分或降级），CLASS-B（部分缺失→缩小范围重试），CLASS-C（内容错误→补充上下文重试）。",
+      "why": "盲重试系统性缺陷浪费资源；分类后重试才有效。"
+    },
     {
       "step": "fallback_or_integrate",
       "action": "原生能力不可用、权限不满足或结果不可靠时，回退到单 agent / 手工委托；由主 agent 负责最终整合。",
@@ -66,6 +71,7 @@
         "写明目标、非目标、范围、验证方式",
         "写明每个后续委托角色的 scope 边界"
       ],
+      "outputManifest": "子 agent 必须在开始 plan 前声明预期产出的 plan 文件路径 + proposal 路径。主 agent 收到后按 output_manifest 验证产出（CLASS-A/B/C 分类）。",
       "contextFiles": [
         {"glob": "AI_PROJECT.md", "priority": "high", "kind": "truth"},
         {"glob": "REQUIREMENTS.md", "priority": "high", "kind": "truth"},
@@ -122,6 +128,7 @@
         "写清改动文件、验证命令、未完成项",
         "不得越过显式授权的写入范围"
       ],
+      "outputManifest": "子 agent 必须在开始 work 前声明预期产出的文件列表。主 agent 收到后按此列表进行 output verification（CLASS-A/B/C 分类）。",
       "contextFiles": [
         {"glob": "AI_PROJECT.md", "sections": [[25, 50], [95, 106]], "priority": "high", "kind": "truth"},
         {"glob": "REQUIREMENTS.md", "sections": [[1, 100]], "priority": "high", "kind": "truth"},
@@ -155,6 +162,7 @@
         "产出结构化 findings：[Critical] 阻塞问题；[Warning] 应修复项；[Info] 建议改进（对齐 reworkLoopProtocol.findingSeverities）",
         "明确这是 spec review、quality review 还是交付前验证"
       ],
+      "outputManifest": "子 agent 必须在开始 review 前声明预期产出的 review 证据文件路径。主 agent 收到后按 output_manifest 验证产出（CLASS-A/B/C 分类）。",
       "contextFiles": [
         {"glob": "AI_PROJECT.md", "sections": [[25, 50], [95, 106]], "priority": "high", "kind": "truth"},
         {"glob": "REQUIREMENTS.md", "priority": "high", "kind": "truth"},
@@ -285,18 +293,39 @@
     }
   ],
   "fallbackMode": {
-    "default": "single_agent_with_artifacts",
-    "triggers": [
-      "当前工具没有稳定的 native multi-agent 能力",
-      "当前工具支持原生 agent，但无法声明 write scope / artifact 边界",
-      "native agent 结果无法审计、无法落盘或不能绑定 change/verify",
-      "任务规模太小，不值得引入额外委托复杂度"
-    ],
-    "requiredBehavior": [
-      "回退后仍使用同一套 `analysis/patches/review/evidence` 工件约定",
-      "主 agent 明确说明是原生 delegation 还是降级执行",
-      "不能因为降级而跳过 plan/review/finish gate"
-    ]
+    "singleAgent": {
+      "default": "single_agent_with_artifacts",
+      "triggers": [
+        "当前工具没有稳定的 native multi-agent 能力",
+        "当前工具支持原生 agent，但无法声明 write scope / artifact 边界",
+        "native agent 结果无法审计、无法落盘或不能绑定 change/verify",
+        "任务规模太小，不值得引入额外委托复杂度"
+      ],
+      "requiredBehavior": [
+        "回退后仍使用同一套 `analysis/patches/review/evidence` 工件约定",
+        "主 agent 明确说明是原生 delegation 还是降级执行",
+        "不能因为降级而跳过 plan/review/finish gate"
+      ]
+    },
+    "degradedMode": {
+      "description": "当子 agent 反复失败（2+ 次，覆盖 2+ 分类）时，主 session 直接编辑 + 事后审查",
+      "triggers": [
+        "CLASS-A 失败 ≥ 2 次（同一委托）",
+        "同一委托的 2 种不同分类各失败 1 次",
+        "主 session 主动判定 delegation 开销超过直接编辑"
+      ],
+      "requiredBehavior": [
+        "改前必须记录预期改动到 changes/<id>/patches/degraded-batch.md",
+        "降级触发时，主 session 写入 changes/<id>/evidence/degraded-evidence.md（原因+范围+涉及 group）",
+        "batch-edit 完成后，reviewer 产出 changes/<id>/review/degraded-review.md 审查结论",
+        "不能跳过 review gate——必须由独立 reviewer 审查 batch-edit 产出",
+        "不能跳过 completion audit——所有改动仍需通过完成审计"
+      ],
+      "exitCriteria": [
+        "后续子任务可恢复完整 4-phase 委托",
+        "或 goal 整体完成，降级模式结束"
+      ]
+    }
   },
   "toolCapabilityMatrix": [
     {
@@ -342,7 +371,8 @@
     "主 agent 必须在派遣前执行上下文策展并写入 JSONL 上下文文件。",
     "除显式授权的 worker/integrator 外，delegated agent 默认不直接写业务文件。",
     "任何 native multi-agent 结果都必须能回收到 `analysis/patches/review/evidence` 约定路径。",
-    "native delegation 是可选执行策略，不是 workflow 的必需前提。"
+    "native delegation 是可选执行策略，不是 workflow 的必需前提。",
+    "Output Verification Gate: 委托完成后必须验证子 agent 的 output_manifest。按 CLASS-A/B/C 分类处理失败（见 ws-goal-contract §6.4 step ii.a），不盲重试。"
   ],
   "standardRoles": {
     "title": "Standard Roles (Recommended)",
@@ -375,6 +405,7 @@
     "`aiws` 的价值在于治理内核和合同层，不在于成为统一 runtime。",
     "这一版先把 contract 写清，再决定哪些入口需要在模板里显式投影。",
     "后续若工具原生能力变化，只需要更新 capability matrix 与适配策略，不需要重写 workflow 真值。",
-    "v1.1: 新增 curate_context 流程步骤 + roleTypes[].contextFiles 基线 + 上下文策展 universal 规则。"
+    "v1.1: 新增 curate_context 流程步骤 + roleTypes[].contextFiles 基线 + 上下文策展 universal 规则。",
+    "v2: 新增 output_manifest（worker role）、verify_output 流程步骤、Output Verification Gate 通用规则、degradedMode 降级模式。对应 Oracle 评审调整的 ws-goal 优化方案（P0a Output Gate + P0+ Degraded Mode + P1 Context Gate + P2 Auto-Advance）。"
   ]
 }

package/docs/workflow-delegation-contracts.md

@@ -25,6 +25,7 @@ delegation contract 在做任何角色拆分或原生多 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/` 或明确允许的代码写入范围。 | 即使执行方式不同，交付证据与审计路径必须一致。 |
+| `verify_output` | 委托完成后，按子 agent 声明的 `output_manifest` 做 glob 检查 + 最小内容检查（≥3 行非空白内容）。缺失或质量不足时分类处理：CLASS-A（零文件→拆分或降级），CLASS-B（部分缺失→缩小范围重试），CLASS-C（内容错误→补充上下文重试）。 | 盲重试系统性缺陷浪费资源；分类后重试才有效。 |
 | `fallback_or_integrate` | 原生能力不可用、权限不满足或结果不可靠时，回退到单 agent / 手工委托；由主 agent 负责最终整合。 | `aiws` 的职责是治理和降级，不是保证每个工具都支持同一套运行时。 |
 
 ## Role Types
@@ -210,16 +211,9 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 
 ## Fallback Mode
 
-- default: `single_agent_with_artifacts`
+- default: ``
 - 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
 
@@ -252,6 +246,7 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 - 除显式授权的 worker/integrator 外，delegated agent 默认不直接写业务文件。
 - 任何 native multi-agent 结果都必须能回收到 `analysis/patches/review/evidence` 约定路径。
 - native delegation 是可选执行策略，不是 workflow 的必需前提。
+- Output Verification Gate: 委托完成后必须验证子 agent 的 output_manifest。按 CLASS-A/B/C 分类处理失败（见 ws-goal-contract §6.4 step ii.a），不盲重试。
 
 ## Notes
 
@@ -259,3 +254,4 @@ delegation contract 在做任何角色拆分或原生多 agent 调用前，必
 - 这一版先把 contract 写清，再决定哪些入口需要在模板里显式投影。
 - 后续若工具原生能力变化，只需要更新 capability matrix 与适配策略，不需要重写 workflow 真值。
 - v1.1: 新增 curate_context 流程步骤 + roleTypes[].contextFiles 基线 + 上下文策展 universal 规则。
+- v2: 新增 output_manifest（worker role）、verify_output 流程步骤、Output Verification Gate 通用规则、degradedMode 降级模式。对应 Oracle 评审调整的 ws-goal 优化方案（P0a Output Gate + P0+ Degraded Mode + P1 Context Gate + P2 Auto-Advance）。

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

@@ -97,7 +97,8 @@
               },
               "additionalProperties": false
             }
-          }
+          },
+          "outputManifest": { "type": "string", "minLength": 1 }
         },
         "additionalProperties": false
       }
@@ -208,18 +209,48 @@
     },
     "fallbackMode": {
       "type": "object",
-      "required": ["default", "triggers", "requiredBehavior"],
+      "required": ["singleAgent", "degradedMode"],
       "properties": {
-        "default": { "type": "string", "minLength": 1 },
-        "triggers": {
-          "type": "array",
-          "minItems": 1,
-          "items": { "type": "string", "minLength": 1 }
+        "singleAgent": {
+          "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
         },
-        "requiredBehavior": {
-          "type": "array",
-          "minItems": 1,
-          "items": { "type": "string", "minLength": 1 }
+        "degradedMode": {
+          "type": "object",
+          "required": ["description", "triggers", "requiredBehavior", "exitCriteria"],
+          "properties": {
+            "description": { "type": "string", "minLength": 1 },
+            "triggers": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "requiredBehavior": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "exitCriteria": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -315,7 +346,8 @@
                 "type": "array",
                 "minItems": 1,
                 "items": { "type": "string", "minLength": 1 }
-              }
+              },
+              "outputManifest": { "type": "string", "minLength": 1 }
             },
             "additionalProperties": false
           }

package/docs/workflow-router-rules.json

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": 2,
   "title": "workflow-router-rules",
   "description": "Machine-readable bootstrap/router rules for the aiws default workflow entry.",
   "purpose": [
@@ -113,6 +113,14 @@
       "gate": "plan 过 gate 前不进入 `ws-dev`。",
       "rationale": "medium/complex 任务在需求冻结后必须先生成可落盘计划，避免 router 直接跳进实现。"
     },
+    {
+      "id": "goal_driven",
+      "intent": "中大型实现（ws-goal 可用时）",
+      "match": "任务是多步实现、跨文件、跨模块，且 ws-goal 已初始化（检测到 .aiws/goals/ 目录或 ws-goal skill 可用），且任务复杂度 ≥ medium（涉及文件 > 3 或涉及模块 > 1）。",
+      "routeTo": "ws-goal",
+      "gate": "ws-goal 先做 intake/dep_check/ws_analysis，再进入 pipeline delegation。",
+      "rationale": "ws-goal 可用时，medium+ 任务优先使用 ws-goal 协议（目标设定→依赖链预检→管道委托→完成审计），**并且**在必要时可通过 degraded mode 降级回 ws-dev。当 ws-goal 不可用或路由结果不明确时，fallthrough 到 plan_first（ws-plan）。"
+    },
     {
       "id": "direct_implementation",
       "intent": "小步实现/修复/配置调整",
@@ -211,6 +219,14 @@
       "expectedRoute": "ws-handoff",
       "why": "handoff 依赖已有 finish/archive 上下文，不能当成普通实现。"
     },
+    {
+      "id": "case_goal_driven",
+      "scenario": "任务是跨文件、多步实现，且 ws-goal 已初始化。",
+      "request": "实现 dashboard 的阶段治理视图，ws-goal 已经初始化。",
+      "expectedRuleId": "goal_driven",
+      "expectedRoute": "ws-goal",
+      "why": "ws-goal 可用时优先走 ws-goal 协议（目标设定→pipeline delegation→completion audit），且必要时可降级回 ws-dev。"
+    },
     {
       "id": "case_plan_first",
       "scenario": "任务是跨文件、多步实现，且需要先建立 change 分支或方案。",
@@ -272,12 +288,13 @@
     "除缺失真值场景外，router 至少要给出一个明确的 `Route:` 结果或明确的澄清问题。",
     "当 `routeTo=clarify` 时，必须停止，不直接写代码。",
     "当 `routeTo=ws-intake` 时，必须先逐条冻结问题并产出 intake 草案；不要跳过到 `ws-plan`。",
-    "当 `routeTo=ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` / `ws-intake` 时，后续行为必须遵循对应 skill 契约。",
+    "当 `routeTo=ws-goal` / `ws-plan` / `ws-dev` / `ws-review` / `ws-finish` / `ws-handoff` / `ws-req-review` / `ws-intake` 时，后续行为必须遵循对应 skill 契约。",
     "任何 route 都不能绕过 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。"
   ],
   "notes": [
     "default-routed workflow 不等于 daemon / pane / runtime orchestration；这一版只固定真值和入口。",
     "`using-aiws` 可以作为默认入口；若未来需要更短命名，可再引入 `ws-router` 作为等价别名。",
-    "OpenCode 的 native 目录不同，但 router 语义必须共用同一份 JSON 真值。"
+    "OpenCode 的 native 目录不同，但 router 语义必须共用同一份 JSON 真值。",
+    "v2: 新增 goal_driven 路由规则。当 ws-goal 初始化完成时，medium+ 复杂度任务优先路由到 ws-goal（而非 ws-plan）。ws-goal 在必要时可通过 degraded mode 降级回 ws-dev。"
   ]
 }