@aipper/aiws-spec 0.0.36 → 0.0.37

package/docs/ws-goal-contract.md

@@ -357,3 +357,173 @@ Dependency chain 验证（2.4）需要：
 - **轻量**（< 3 步，单文件改动）：只做 step 1-2（derive + preserve），跳过完整证据链
 - **标准**（3-10 步，多文件改动）：完整 8 步审计
 - **严格**（跨模块、跨 repo）：8 步审计 + 独立审计者 + ws-review 门禁
+
+---
+
+## 6. Pipeline Sequential Dispatch
+
+### 6.1 Motivation
+
+ws-goal step 5（Pipeline Delegation）将 goal 的完整执行委托给单个子 agent。对于包含多个独立交付批次的 goal（如"分四组完成全部页面重构"），单个子 agent 可能在长时间执行中：
+- 因上下文超限而丢失精度
+- 中途失败导致整个 goal 回退
+- 无法体现不同页面组的边界差异
+
+Pipeline Sequential Dispatch 通过**组（group）机制**解决此问题：同一 goal 内的多个执行单元各自委托给独立的子 agent，按依赖顺序逐个执行，ws-goal 负责编排调度。
+
+### 6.2 Core Design
+
+#### 6.2.1 Group 定义
+
+Group 是 goal 内部的一个自包含执行单元：
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| **id** | string | 组标识，如 `group-1`, `group-foundation` |
+| **title** | string | 简短标题 |
+| **scope** | string | 范围描述：哪些文件、哪些模块 |
+| **verification** | string[] | 该组的验收标准。组完成时需逐条验证 |
+| **depends_on** | string[] | 依赖的其他 group id。默认 `[]`（无依赖） |
+| **status** | enum | `pending \| in_progress \| complete \| paused \| failed` |
+
+#### 6.2.2 Group Dependencies
+
+Group 之间的依赖构成 DAG（有向无环图）：
+
+- Group B 声明 `depends_on: [A]` → B 仅在 A 完成后启动
+- 无依赖的 group 之间当前必须顺序执行（并行调度暂不实现）
+- 禁止循环依赖
+- 默认（不声明 `depends_on`）按声明顺序执行
+
+#### 6.2.3 State Machine
+
+每个 group 有自己的状态，与整体 goal 状态解耦：
+
+```
+group: pending → in_progress → complete
+                                → paused (下游 block)
+                                → failed (下游 block)
+```
+
+整体 goal 的状态：
+
+```
+active → group 1 executing → group 1 complete → group 2 executing → ... → all groups complete → overall completion audit → complete
+                                                                      → any group paused → paused
+                                                                      → any group failed → paused (with failure recorded)
+```
+
+#### 6.2.4 Delegation Model
+
+每个 group 由一个独立的子 agent 执行完整 pipeline：
+
+1. ws-goal 为当前 group 构造定向委托 prompt（含 goal 完整上下文 + 当前 group 的具体 scope 和 verification）
+2. 子 agent 执行 ws-plan → ws-dev → ws-review → ws-commit → ws-finish 完整链路（或等效步骤）
+3. ws-goal 收集子 agent 输出，运行 group 级完成审计
+4. group 通过 → 更新 goal Progress Notes → 调度下一个 group
+5. group 中断（paused/failed）→ 更新 goal state=paused，在 Audit Trail 记录 blocker
+
+### 6.3 Goal File Extension
+
+启用 Pipeline Sequential Dispatch 的 goal，在 `Progress Notes` 字段上方或 `Tasks` 区域添加 groups 定义：
+
+```yaml
+## Groups
+
+### group-1: Foundation Pages
+- scope: index.tsx, category.tsx, search.tsx
+- verification:
+  - "Home page renders product grid"
+  - "Category page renders with filters"
+  - "Search results show 10 items per page"
+- depends_on: []
+- status: pending
+
+### group-2: Purchase Conversion
+- scope: cart.tsx, checkout.tsx, payment-form.tsx
+- verification:
+  - "Add to cart updates badge count"
+  - "Checkout collects shipping address"
+  - "Payment form validates card number"
+- depends_on: [group-1]
+- status: pending
+```
+
+### 6.4 Dispatch Protocol
+
+ws-goal 执行 Sequential Dispatch 时遵循以下协议：
+
+```
+1. Parse goal file → extract group list
+2. Validate group DAG (no cycles, deps resolve to known groups)
+3. FOR each group in topological order:
+   a. Update group status → in_progress
+   b. Construct group delegation prompt:
+      - Full goal context (outcome, verification, constraints, boundaries)
+      - Current group scope and verification
+      - Target branch from goal's target_base_branch
+      - Dependency chain validation results (from step 4)
+      - Workspace state analysis results (from step 4.5)
+      - Mandatory pipeline steps list
+   c. Delegate to sub-agent:
+      - `task(category="deep"|"unspecified-high", load_skills=[...], prompt="...")`
+      - Wait for completion
+   d. Run group-level completion audit:
+      - Verify group's verification criteria against sub-agent output
+      - Check change artifacts (change branch created, proposal, tasks, plan)
+      - Lint/typecheck clean
+   e. On audit pass:
+      - Update group status → complete
+      - Update goal Progress Notes with group result
+   f. On audit fail:
+      - Update group status → paused (recoverable) or failed (unrecoverable)
+      - Record blocker in Audit Trail
+      - Set goal state → paused
+      - STOP dispatching remaining groups
+      - Output: "Goal <id> paused at group <group-id>: <reason>"
+4. All groups complete:
+   - Run overall completion audit (all verification + goal-level checks)
+   - Update goal state → complete
+   - Output: "Goal <id> complete (<N> groups executed)"
+```
+
+### 6.5 Completion Audit
+
+Pipeline Sequential Dispatch 的审计分为两层：
+
+**Group 级审计**（每 group 完成时执行）：
+- 验证 group 的 scope 是否已实现
+- 验证 group 的 verification 条目（测试通过/文件存在/命令成功）
+- 验证 pipeline 完整（change 已创建、已 merge、已 push）
+
+**整体审计**（所有 group 完成后执行）：
+- 验证 goal 级别的 outcome 字段是否满足
+- 验证所有 group 均标记 complete，无 paused/failed
+- 回归检查：全局改动未引入新的 lint/type 错误
+- 验证 dependency chain 在最终合并后仍然健康
+- 输出审计报告：每 group 结果 + 整体结论
+
+### 6.6 Failure Recovery
+
+当 group 中途失败或暂停时：
+
+1. ws-goal 记录当前组停止位置到 Progress Notes
+2. 标记 goal state=paused
+3. 输出恢复命令建议，例如：
+   ```
+   Goal <id> paused at group <group-id>.
+   To resume: fix the reported issue, then restart ws-goal.
+   ws-goal will detect the paused goal and ask whether to:
+     a) Retry group <group-id> (re-delegate)
+     b) Skip group <group-id> (mark complete manually, proceed to next)
+     c) Pause and handoff
+   ```
+4. 下一 session 启动 ws-goal 时（step 0），检测到 paused goal → 输出恢复选项 → 用户选择后继续
+
+### 6.7 Backward Compatibility
+
+| 现有 goal | 兼容性 |
+|---|---|
+| 不含 groups 定义的 goal | 完全不受影响。step 5 照常执行单次 delegation |
+| 含 groups 定义的 goal（新格式） | 进入 Sequential Dispatch 模式 |
+| 已有 step 5 的委托行为 | 无变更。新机制仅在同 goal 内存在 group 定义时激活 |

package/package.json

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

package/templates/workspace/.opencode/command/ws-goal.md

@@ -15,7 +15,7 @@ ws-goal 只做三件事，不做更多：
 | 录入目标（写 `.aiws/goals/<id>.md`） | 创建/驱动 change（那是 ws-plan/ws-dev） |
 | 依赖链预检（上游死 change → 阻断） | 评估复杂度、路由执行路径 |
 | 完成审计（claim done 时验证 outcome） | git add/commit/push、finish |
-| 记录 target_base_branch 约束 | auto-chain 到下一个 goal |
+| 记录 target_base_branch 约束 | auto-chain 到下一个 goal（但在同一 goal 内支持多组顺序调度 §6） |
 
 超出以上范围的需求，路由到对应 ws-* 技能，ws-goal 不碰。
 
@@ -113,39 +113,124 @@ ws-goal 只做三件事，不做更多：
      用户未确认前，不得进入 step 5。
 
 5) **Pipeline Delegation**：依赖链预检 + workspace 分析通过后，将 goal 完整执行委托给管道 agent。
-   前置条件：step 4 必须通过（ALL HEALTHY 或 UNHEALTHY 已显式放行）。若 step 4 阻断，则不允许 delegation。
-   a) 读取 goal 文件，评估复杂度：
-      - 简单（配置/doc/规范，≤5 文件，低风险）→ delegate 到 ws-dev-lite
-      - 复杂（代码改动 >5 文件，多模块，架构/迁移风险）→ delegate 到完整 pipeline
-   b) 构造 delegation prompt，包含：
-      - goal 文件完整路径与内容（含 target_base_branch、dependency chain 验证结果）
-      - 真值文件路径（AI_PROJECT.md / REQUIREMENTS.md / AI_WORKSPACE.md）
-      - 强制 pipeline 步骤（见下方 c）
-      - 完成条件：goal 文件的 Verification 字段全部通过
-   c) 强制 pipeline 步骤（子 agent 必须依次执行，不得跳过）：
-      1. 如果 change 不存在：`aiws change start <goal-id> --allow-dirty`，base_branch 必须用 goal 的 target_base_branch
-      2. 写 proposal.md：绑定 goal 的 outcome 到 Req_ID，plan_file 指向即将生成的 plan
-      3. 写 plan 文件：`plan/<timestamp>-<goal-id>.md`，含验证命令与预期
-      4. 运行 plan-verify：`aiws plan-verify <plan-file>` 或等效检查
-      5. 实现代码改动（ws-dev）：按 plan 实施，边改边验证
-      6. review 检查：lint/typecheck/code review 按 ws-review 标准
-      7. 提交：`ws-commit`（或等效 git add + commit）
-      8. 收尾：`ws-finish`（fast-forward 合并 + 推送）
-      9. 更新 goal status=complete：修改 goal 文件中的 state 字段
-      「not applicable」步骤可跳过，但必须说明理由
-   d) 使用 task 委托：
-      - 简单 → `task(category="quick", load_skills=[], ...)`
-      - 复杂 → `task(category="deep", load_skills=[], ...)` 或 `task(subagent_type="general", ...)`
-   e) 委托任务执行完成后：
-      - 收集子 agent 的输出，逐项对照 goal 文件的 Verification 字段做完成审计
-      - 全部通过 → 更新 goal state=complete，输出 "Goal <goal-id> complete"
-      - 有未通过 → 更新 goal state=paused，记录 blocker 到 Audit Trail，输出 "Goal <goal-id> paused: <reason>"
-      - 若子 agent 返回了未完成的 pipeline 状态（只有部分步骤完成），在 goal 文件的 Progress Notes 中记录进展，标记 goal state=paused 并输出当前进度
-    f) 判断平台是否支持 task 委托：
-       - 调用 `task(category="quick", load_skills=[], description="probe", prompt="probe", run_in_background=true)`
-       - 若返回有效的 task_id/session_id → 支持委托，走 e)
-       - 若返回错误或无 session_id → 不支持委托
-       - 不支持时：在本会话中亲自执行 c) 的 pipeline 步骤，全部完成后更新 goal status=complete
+    前置条件：step 4 必须通过（ALL HEALTHY 或 UNHEALTHY 已显式放行）。若 step 4 阻断，则不允许 delegation。
+
+5a) **Check for Groups**：读取 goal 文件，检查是否定义了 `Groups` 区域。
+    - 若 goal **不含** groups → 走 single-shot delegation（step 5b-5g）
+    - 若 goal **包含** groups → 走 Sequential Group Dispatch（step 5.1）
+
+--- 以下为 single-shot delegation（无 groups 的 goal） ---
+
+5b) **评估复杂度（single-shot）**：
+    - 简单（配置/doc/规范，≤5 文件，低风险）→ delegate 到 ws-dev-lite
+    - 复杂（代码改动 >5 文件，多模块，架构/迁移风险）→ delegate 到完整 pipeline
+
+5c) **构造 delegation prompt**，包含：
+    - goal 文件完整路径与内容（含 target_base_branch、dependency chain 验证结果）
+    - 真值文件路径（AI_PROJECT.md / REQUIREMENTS.md / AI_WORKSPACE.md）
+    - 强制 pipeline 步骤（见 step 5d）
+    - 完成条件：goal 文件的 Verification 字段全部通过
+
+5d) **强制 pipeline 步骤**（子 agent 必须依次执行，不得跳过）：
+    1. 如果 change 不存在：`aiws change start <goal-id> --allow-dirty`，base_branch 必须用 goal 的 target_base_branch
+    2. 写 proposal.md：绑定 goal 的 outcome 到 Req_ID，plan_file 指向即将生成的 plan
+    3. 写 plan 文件：`plan/<timestamp>-<goal-id>.md`，含验证命令与预期
+    4. 运行 plan-verify：`aiws plan-verify <plan-file>` 或等效检查
+    5. 实现代码改动（ws-dev）：按 plan 实施，边改边验证
+    6. review 检查：lint/typecheck/code review 按 ws-review 标准
+    7. 提交：`ws-commit`（或等效 git add + commit）
+    8. 收尾：`ws-finish`（fast-forward 合并 + 推送）
+    9. 更新 goal status=complete：修改 goal 文件中的 state 字段
+    「not applicable」步骤可跳过，但必须说明理由
+
+5e) **使用 task 委托**：
+    - 简单 → `task(category="quick", load_skills=[], ...)`
+    - 复杂 → `task(category="deep", load_skills=[], ...)` 或 `task(subagent_type="general", ...)`
+
+5f) **委托任务执行完成后**：
+    - 收集子 agent 的输出，逐项对照 goal 文件的 Verification 字段做完成审计
+    - 全部通过 → 更新 goal state=complete，输出 "Goal <goal-id> complete"
+    - 有未通过 → 更新 goal state=paused，记录 blocker 到 Audit Trail，输出 "Goal <goal-id> paused: <reason>"
+    - 若子 agent 返回了未完成的 pipeline 状态（只有部分步骤完成），在 goal 文件的 Progress Notes 中记录进展，标记 goal state=paused 并输出当前进度
+
+5g) **判断平台是否支持 task 委托**：
+    - 调用 `task(category="quick", load_skills=[], description="probe", prompt="probe", run_in_background=true)`
+    - 若返回有效的 task_id/session_id → 支持委托，走 step 5f
+    - 若返回错误或无 session_id → 不支持委托
+    - 不支持时：在本会话中亲自执行 step 5d 的 pipeline 步骤，全部完成后更新 goal status=complete
+
+--- 以下为 Sequential Group Dispatch（含 groups 的 goal） ---
+
+5.1) **Sequential Group Dispatch**：
+     当 goal 文件包含 Groups 定义时，ws-goal 按依赖顺序逐个调度每个 group，每个 group 交由独立子 agent 执行完整 pipeline。
+
+5.1a) **解析并验证 groups**：
+     - 提取 goal 文件中所有 group 定义（id, scope, verification, depends_on, status）
+     - 验证 DAG：无循环依赖，depends_on 引用正确的已知 group
+     - 将所有 group status 初始化为 `pending`
+     - 若解析失败（格式错误、循环依赖）→ 输出错误，不允许 delegation
+
+5.1b) **计算拓扑顺序**：
+     - 按 depends_on 确定执行顺序。默认：声明顺序
+     - 输出 group 执行计划列表：
+       ```
+       ═══ Group 执行计划 ═══
+       [1] group-1: Foundation Pages（depends_on: none）
+       [2] group-2: Purchase Conversion（depends_on: group-1）
+       [3] group-3: Account & Orders（depends_on: group-1）
+       ═══════════════════════════
+       ```
+     - 展示计划后要求用户确认是否继续。用户确认后才开始调度
+
+5.1c) **按顺序执行每个 group**：
+     FOR each group in 拓扑顺序：
+       1. 更新 group status → `in_progress`，写入 goal 文件 Progress Notes
+        2. 构造 group 级 delegation prompt：
+          - goal 完整上下文（outcome, verification, constraints, boundaries, target_base_branch）
+          - 当前 group 的 scope 与 verification
+          - 依赖链验证结果（step 4 产出）
+          - 工作区状态分析结果（step 4.5 产出）
+          - **目标项目绝对路径**：检测当前工作目录（`$PWD` 或 `$PROJECT_ROOT`），在 prompt 首行指示子 agent `cd <path>` 切换到正确目录后再执行
+          - 强制 pipeline 步骤（同 step 5d，但 change id 为 `<goal-id>-<group-id>`）
+          - 完成条件：当前 group 的 verification 条目全部通过
+       3. 使用 task 委托：
+          ```
+          task(
+            category="deep",
+            load_skills=[...],
+            description="<group-title>",
+            prompt="<group delegation prompt>"
+          )
+          ```
+       4. 收集子 agent 输出，运行 group 级完成审计：
+          - 对照 group 的 verification 条目逐条验证
+          - 检查 change artifacts 完整性（proposal/tasks/design 存在）
+          - lint/typecheck 干净
+       5. 审计通过 → 更新 group status → `complete`，更新 Progress Notes
+       6. 审计未通过：
+          - 判定可恢复（paused）或不可恢复（failed）
+          - 更新 group status → paused/failed
+          - 记录 blocker 到 Audit Trail
+          - 更新 goal state → paused
+          - 输出："Goal <id> paused at group <group-id>: <reason>"
+          - **STOP**：后续 group 不再调度
+          - BREAK
+
+5.1d) **所有 group 完成后**：
+     - 运行整体完成审计：
+       - goal 级别的 outcome 是否满足
+       - 所有 group 均为 complete（无 paused/failed）
+       - 全局 lint/type 检查无新增错误
+       - 输出每 group 结果 + 整体结论
+     - 全部通过 → 更新 goal state=complete，输出 "Goal <id> complete（<N> groups executed）"
+     - 有未通过 → 更新 goal state=paused
+
+5.1e) **恢复机制**（下一 session 进入 step 0 时触发）：
+     - 检测到 paused goal 且含 groups → 输出恢复选项：
+       - （a）重试失败的 group（重新委托）
+       - （b）跳过该 group（标记 complete，继续下游）
+       - （c）暂停并 handoff
+     - 用户选择后执行对应操作
 <!-- AIWS_MANAGED_END:opencode:ws-goal -->
 
 可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.opencode/skills/ws-goal/SKILL.md

@@ -15,7 +15,7 @@ description: 目标协议：设定可审计的 goal 目标；依赖链预检；
 ws-goal 不做的事：
 - 不直接创建 change、不直接写 code
 - 不替换 review/commit/finish 门禁
-- 不 auto-chain 到下一个 goal
+- 不 auto-chain 到下一个 goal（但在同一 goal 内支持多组顺序调度 §6）
 
 前置条件：
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。