@aipper/aiws-spec 0.0.34 → 0.0.37

package/docs/ws-goal-contract.md

@@ -32,9 +32,18 @@ aiws 当前没有等价协议。OpenCode + oh-my-opencode 已经提供了 3 层
 
 ### 方案：ws-goal 作为协议层
 
-ws-goal 定义为**协议层**（prompt-template + artifact spec），不是运行时引擎。它负责任务目标的结构化定义、完成审计的证据规范、预算耗尽协议。续跑调度继续借用各平台已有的能力。
+ws-goal 定义为**协议层**（prompt-template + artifact spec），不是运行时引擎。**它做四件事：录入目标、依赖链预检、管道委托、完成审计。**
 
-这样做的好处是：不重复造 runtime，不绑定特定工具，只写一份规范就能投影到所有平台。
+| 步骤 | 做什么 | 不做什么 |
+|---|---|---|
+| 录入目标 | 按模板写 `.aiws/goals/<id>.md` | 不创建 change/plan |
+| 依赖链预检 | 追溯上游 change 健康度 + target_base_branch 一致性 | 不修改上游工件 |
+| 管道委托 | 预检通过后，将 goal 委托给子 agent 执行完整 pipeline（ws-plan → ws-dev → ws-review → ws-commit → ws-finish → 审计） | ws-goal 自己不执行任何实现步骤 |
+| 完成审计 | Verification 对照 outcome 逐条验证 | 不替代 review 门禁 |
+
+第四步（管道委托）是 ws-goal 的**编排出口**：依赖链预检通过后，ws-goal 构造一个包含 goal 文件完整内容 + 真值文件路径 + 强制 pipeline 步骤的委托 prompt，交由平台支持的子 agent 执行。子 agent 执行完成后，ws-goal 执行最终的完成审计并更新 goal status。
+
+这样做的好处是：ws-goal 保持轻量协议层，不重复造 runtime，但通过委托机制提供了从 goal 到 complete 的自动化路径。
 
 ---
 
@@ -51,7 +60,8 @@ ws-goal 定义为**协议层**（prompt-template + artifact spec），不是运
 | **constraints** | object | 预算限制：token_budget（token 上限）、time_budget（wall clock 上限）、max_iterations（turn 次数上限） |
 | **boundaries** | string[] | 显式的非目标、范围限制。什么不在本次 goal 内 |
 | **iteration_policy** | object | max_attempts（重试次数）、reaudit_frequency（每几次迭代重新审计一次） |
-| **blocked_stop** | boolean | 遇到 blocker 时是否暂停并报告。true = 报告并等待，不能静默失败 |
+| **blocked_stop** | boolean/object | 遇到 blocker 时是否暂停并报告。true = 报告并等待，不能静默失败。可扩展为 `{ enabled: true, extends_to_upstream: true }`，将阻断语义延伸到上游依赖链不健康的情况（见 2.4） |
+| **target_base_branch** | string | 目标交付的目标分支（如 `main`、`release/v2`）。agent 在 ws-plan 创建 change 时必须以此为 base_branch，不得自由选择。默认 `main`。若使用的 base_branch 与 `target_base_branch` 不一致，阻断并提示。 |
 
 ### 2.2 Goal State Machine
 
@@ -78,6 +88,98 @@ active → paused (optional) → complete | budget_limited → archived
 7. **Uncertain = NOT achieved**：不确定的、间接的、推论性的证据不能作为完成依据。audit 需要确定的证明
 8. **Prove, not disprove**：audit 必须正面证明完成，而不是反面证明"没找到未完成的工作"。找不出 bug 不等于代码正确
 
+### 2.4 Dependency Chain Validation
+
+引入 change 流水线之前（由 ws-plan/ws-dev 负责），必须先对其上游依赖链做健康检查——这是 ws-goal 作为预检门的职责。防止"死 change 阻塞下游"或"base_branch 选错导致 chaining 混乱"。
+
+#### 2.4.1 依赖链定义
+
+依赖链是从当前 goal 的目标分支追溯到 main 的完整 change 列表：
+
+```
+main → change/A → change/B → change/C (当前)
+```
+
+每个环节称为一个 **link**。每个 link 有独立健康状态。
+
+#### 2.4.2 Link 健康判定
+
+| 维度 | 健康 (HEALTHY) | 不健康 (UNHEALTHY) | 过时 (STALE) |
+|---|---|---|---|
+| **Artifacts 完整性** | proposal/tasks/design 都存在 | 缺失任意一项 | — |
+| **Task 完成率** | ≤30% WS:TODO，有实际进展 | >50% WS:TODO，无进展迹象 | — |
+| **Review** | review 已通过或无 blocking 项 | review 存在 HIGH blocker | — |
+| **活跃度** | 最近 14 天内有更新 | — | >14 天无任何更新 |
+| **Truth drift** | `aiws validate .` 通过 | `aiws validate .` 失败 | — |
+
+整体判定规则：
+- 任意维度 UNHEALTHY → link 标记 **UNHEALTHY**
+- 所有维度 HEALTHY 但任一维度 STALE → link 标记 **STALE**
+- 全部 HEALTHY 且无 STALE → link 标记 **HEALTHY**
+
+#### 2.4.3 阻断与确认规则
+
+| 上游状态 | 当前 goal 行为 |
+|---|---|
+| 全部 HEALTHY | 放行，无需确认 |
+| 存在 STALE | 输出警告，允许继续 |
+| 存在 UNHEALTHY | 输出完整 chain 拓扑 + 健康报告，**必须用户显式确认**才能继续 |
+| 父 change 不存在（孤儿分支）| 阻断，提示选择已知 base |
+| **实际 base_branch ≠ goal target_base_branch** | **阻断**。输出 "goal 声明 target_base_branch = X，但当前 base_branch = Y"，必须用户修正或显式确认才能继续。此检查优先于链健康检查——如果 base_branch 本身就选错了，不需要继续追溯 |
+
+#### 2.4.4 Dependency Chain 证据记录
+
+验证结果必须写入 goal artifact 的 `Dependency Chain` 字段（见 3.1 模板），包括：
+- 完整 chain 拓扑（从 main 到当前）
+- 每个 link 的健康状态与判定理由
+- 用户确认记录（若 UNHEALTHY 被显式放行）
+
+### 2.5 Workspace State Analysis
+
+ws-goal 在执行 pipeline delegation（管道委托，见 1.§ 第四步）之前，必须先对当前工作区做全面的状态分析。目的是防止委托子 agent 时因为 workspace 的 dirty 状态、子模块未提交、旧 change 残留等问题导致执行失败或产生意外副作用。
+
+#### 2.5.1 分析维度
+
+| 维度 | 检查项 | 工具 |
+|---|---|---|
+| **Dirty 状态** | staged changes、unstaged changes、untracked files | `git diff --cached --stat` / `git diff --stat` / `git status --porcelain` |
+| **Submodule 状态** | dirty submodules、detached HEAD、unpushed commits | `git submodule status` / `git -C <path> symbolic-ref HEAD` / `git -C <path> log @{u}..HEAD --oneline` |
+| **Change artifacts** | 已有 change 分支、未完成的 change、旧残留 | `git branch --list 'change/*'` / 检查 WS:TODO 比例 |
+| **Git 状态** | unpushed commits、stash | `git log @{u}..HEAD --oneline` / `git stash list` |
+| **Goal 冲突** | 同名 goal、相同 scope 的 active goal | 扫描 `.aiws/goals/*.md` 的 status 与 outcome |
+
+#### 2.5.2 影响评估
+
+每个发现项必须归属影响等级：
+
+| 等级 | 含义 | 示例 |
+|---|---|---|
+| **HIGH** | 阻碍 goal 执行，必须处理 | 子模块 dirty 且与 goal 同一目录 |
+| **MED** | 可能干扰或产生误报 | 旧 change 残留导致依赖链误判 |
+| **LOW** | 无影响，仅提示 | untracked 日志文件 |
+| **NONE** | 完全无关 | `.DS_Store` 之类的系统文件 |
+
+#### 2.5.3 报告格式
+
+分析结果必须用结构化文本块输出，便于用户快速扫描：
+
+```text
+═══ 工作区状态报告 ═══
+[HIGH] <发现项描述> — <影响说明>
+[MED]  <发现项描述> — <影响说明>
+[LOW]  <发现项描述> — <影响说明>
+═══════════════════════
+```
+
+#### 2.5.4 确认门禁
+
+报告输出后，必须等待用户确认：
+- **继续** → 进入 pipeline delegation
+- **暂停** → goal status=paused，报告写入 Audit Trail
+- **先清理** → goal status=paused，输出清理建议步骤
+
+用户未确认，不得进入 delegation。
+
 ---
 
 ## 3. Protocol Specification
@@ -87,8 +189,8 @@ active → paused (optional) → complete | budget_limited → archived
 ```markdown
 ---
 ws_goal:
-  version: 1
-  state: active          # active | paused | complete | budget_limited | archived
+  version: 2                        # ↑ bumped to 2 for dependency chain support
+  state: active                      # active | paused | complete | budget_limited | archived
   created_at: <ISO 8601>
   updated_at: <ISO 8601>
   iteration: 1
@@ -123,10 +225,24 @@ ws_goal:
 - max_attempts: <number>
 - reaudit_frequency: <number>  # 每 N 次 iteration 重新做一次完成审计
 
-## Blocked Stop
+## Target Base Branch
+
+- target_base_branch: main | change/<id> | release/<name>  # 强制。agent 创建 change 时必须以此为 base
+- base_branch_mismatch_action: block | warn  # base_branch 不匹配时的行为。默认 block
+
+## Dependency Chain
+
+- base_branch: main | change/<id>
+- chain:
+  - <link-1>: HEALTHY
+  - <link-2>: HEALTHY
+  - <link-3>: UNHEALTHY (reason: ...)
+- chain_verified_at: <ISO 8601>
+- user_confirmed_unhealthy: true | false | null  # UNHEALTHY 时是否显式确认放行
+
+## Audit Trail
 
-- enabled: true | false
-- report_to: user | log
+<确认记录、约束传递记录、关键变更等>
 
 ## Progress Notes
 
@@ -164,6 +280,7 @@ token_budget 依赖平台的 token 计数器。aiws 不提供独立的 token 监
 | `changes/<id>/tasks.md` | tasks.md 中的每个 item 可携带 `ws_goal_id: <id>` 引用，表示该 task 通过 goal 自动执行。`update_plan` 的 progress tracking 反映 goal iteration 进度 |
 | `.aiws/plan/...` proposal | proposal 中的 `Plan_File` 可以指向 goal objective markdown，表示该 change 使用 goal-driven 执行模式 |
 | `aiws validate` + evidence | validate 的门禁检查可以包含对 goal 的完成审计证据的校验。goal 的 evidence 应落盘到 `changes/<id>/evidence/`，与其他 change 工件统一 |
+| `changes/<id>/.ws-change.json` | `base_branch` 字段作为 dependency chain 验证的起点。ws-goal 在依赖链预检中读取 `.ws-change.json` 的 `base_branch` 追溯上游链 |
 
 ---
 
@@ -221,10 +338,192 @@ aiws 只定义"预算耗尽时应该做什么"的协议，不提供跨平台的
 
 aiws 协议层定义了完整的语义状态，但各平台只能实现其中一部分。goal 创建时应注意平台的能力边界。
 
-### 5.5 Completion Audit 的执行成本
+### 5.5 Dependency Chain Validation 依赖仓库上下文
+
+Dependency chain 验证（2.4）需要：
+- 当前仓库的 git 历史完整（能追溯到 main）
+- `.ws-change.json` 或 proposal.md 记录了 `base_branch`
+- 对链上每个 change 的 artifacts 有读权限（同一工作区）
+
+如果当前不在 git 仓库、或无法访问上游 change 的工件（例如跨仓库依赖），则 chain 验证降级为：
+- 报 UNKNOWN 状态
+- 输出警告"无法验证上游依赖链"
+- 不阻断，但要求用户确认已知风险
+
+### 5.6 Completion Audit 的执行成本
 
 8 步完成审计方法在完整执行时需要独立审计者（在 OpenCode L3 中需要额外模型调用）。对于小目标（比如"修复一个 lint 错误"），完整审计的 overhead 可能超过实际工作的成本。建议根据目标复杂度选择审计级别：
 
 - **轻量**（< 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.34",
+  "version": "0.0.37",
   "description": "AIWS spec and templates (single source of truth).",
   "type": "module",
   "files": [

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

@@ -1,44 +1,236 @@
 ---
-description: 目标协议：设定可审计的 goal 目标并执行完成闭环
+description: 目标协议：设定可审计的 goal 目标；依赖链预检；完成审计
 ---
 <!-- AIWS_MANAGED_BEGIN:opencode:ws-goal -->
 # ws goal
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：
-- 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件，驱动完成闭环。
+## 职责边界
+
+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（但在同一 goal 内支持多组顺序调度 §6） |
+
+超出以上范围的需求，路由到对应 ws-* 技能，ws-goal 不碰。
+
+## 前置条件
 
-前置条件：
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
 
-执行流程：
+## 执行流程
+
 0) 检查 `.aiws/goals/` 目录：
    a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
    b) 若存在 status=active 或 status=paused 的 goal 文件，优先读取并恢复执行，不再新建 goal。
+
 1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
+
 2) 接受用户输入的 goal objective，明确目标范围与验收标准。
+
 3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
-4) 输出 completion audit checklist，列出每个 goal 的完成标准与验证方式。
-5) **Scope Assessment + 路由**：评估目标复杂度，自动选择执行路径：
-   a) 简单（≤5 文件、配置/doc/规范为主、低风险）→ 直行：后续步骤 6-8 auto-finish 闭环
-   b) 复杂（多模块、代码改动 >5 文件、架构/安全/迁移风险）→ 自动触发 `ws-plan` 启动 change 流水线（ws-plan → ws-dev → review → ws-commit → ws-finish），完成后更新 goal status=complete
-   c) 将路由决策写入 goal 文件 Audit Trail
-6) 建议续跑方式：简单路径直行 auto-finish；复杂路径进入 change 流水线后建议 `ws-dev`
-7) 每轮 execution 结束后执行 completion audit，比对 checklist 判断 goal 是否达成；未达成则继续下一轮。
-8) 若 completion audit 确认 goal 达成，自动执行闭环 pipeline：
-   a) Review 检查（按改动类型）：
-      - 配置/文档/规范类（markdown）：内容一致性、引用完整性、内容正确性、无 secrets、格式统一
-      - 代码类（ts/js/py 等）：lint/typecheck 通过、符合现有代码模式、无 secrets、测试通过或覆盖缺口已记录
-      - 混合类：以上两种合并
-   b) 简单路径：`git add` 目标产出文件 → `git commit -m "goal(<goal-id>): <objective 摘要>"` → `git push` → 更新 goal status=complete
-   c) 复杂路径：走 `ws-commit` → `ws-finish` → archive change → 更新 goal status=complete
-   d) 不通过：记录 blocker → 继续 fix 循环
-9) **Auto-chain to next goal**：当前 goal pipeline 完成后：
-   a) 扫描 `.aiws/goals/*.md`，按文件名排序找出第一个 status=pending 的 goal
-   b) 若找到：读取其 objective，输出 "→ Auto-continuing to <goal-id>"，回到步骤 5 创建新 pipeline 自动继续
-   c) 若未找到：输出 "All goals completed" 并结束
-   d) 若找到的 pending goal 缺少 Success Criteria：输出 blocker 并停止（不自动跳过）
+   a) 生成时填入 `Target Base Branch` 字段：
+      - `target_base_branch`：从当前分支追踪或用户声明确定。默认 `main`
+      - `base_branch_mismatch_action`：默认 `block`
+   b) 生成时填入初始 `Dependency Chain` 字段：
+      - `base_branch`：当前检出分支或用户指定的基分支
+      - `chain`：追溯完整的 change 链到 main
+      - `chain_verified_at`：当前时间
+      - `user_confirmed_unhealthy`：初始为 null
+
+4) **Dependency Chain Validation**：上游依赖链健康检查（不创建任何 change/plan/commit）。
+   a) 确定 base_branch：
+      - 若当前已存在 change 分支，读取 `.ws-change.json` 或 proposal.md 的 `base_branch`
+      - 若用户显式指定 base_branch，以用户指定为准
+      - 否则默认 main
+   a1) **target_base_branch 一致性检查**（Rule C）：
+      - 读取 goal 文件的 `Target Base Branch.target_base_branch`
+      - 若 `base_branch != target_base_branch`：
+        - 输出 "goal 声明 target_base_branch = X，但当前 base_branch = Y"
+        - 若 `base_branch_mismatch_action` 为 `block`（默认）：**强制 blocker**，必须用户修正 base_branch 或显式确认 mismatch 才能继续
+        - 若为 `warn`：输出警告并允许继续
+        - 将 mismatch 记录到 goal 文件的 Audit Trail
+      - 若一致：继续 step b
+   b) 追溯 chain：从 base_branch 逐级向上追溯到 main
+      - 每级检查 `.ws-change.json` 的 `base_branch` 或 git 分支关系
+      - 若无法追溯（孤儿分支），标记 UNKNOWN 并输出警告
+   c) 对 chain 中每个 link 做健康检查（按 ws-goal-contract.md 2.4.2 标准）：
+      - artifacts 完整性：proposal/tasks/design 是否存在
+      - task 完成率：WS:TODO 占比
+      - review 状态：是否有 HIGH blocker
+      - 活跃度：最后更新时间
+      - truth drift：`aiws validate .` 是否通过
+   d) 结果：
+      - ALL HEALTHY → 输出 "依赖链健康" 并继续
+      - 存在 STALE → 输出链拓扑 + 警告，允许继续
+      - 存在 UNHEALTHY → 输出完整 chain 拓扑 + 每级健康报告，**强制 blocker**，必须用户显式确认才能继续
+      - UNKNOWN（无法追溯）→ 输出警告"无法验证上游依赖链"，不阻断但要求用户确认
+   e) 将验证结果写入 goal 文件的 `Dependency Chain` 字段：
+       - 更新 `chain` 中每个 link 的健康状态与判定理由
+       - 若用户放行 UNHEALTHY：设置 `user_confirmed_unhealthy: true` 并记录到 `Audit Trail`
+       - 若用户未放行：设置 goal status=paused 并结束
+
+4.5) **Workspace State Analysis**：依赖链预检通过后、delegation 前，分析工作区状态并输出报告。
+     必须用户确认后才能进入 step 5。
+     a) 检查 dirty 状态：
+        - staged changes（`git diff --cached --stat`）
+        - unstaged changes（`git diff --stat`）
+        - untracked files（`git status --porcelain` 中 `??` 开头项）
+     b) 检查 submodule 状态：
+        - 每个 submodule 的 dirty 状态（`git submodule status`）
+        - detached HEAD（`git -C <path> symbolic-ref HEAD` 失败）
+        - unpushed 提交（`git -C <path> log @{u}..HEAD --oneline`）
+     c) 检查 change artifacts：
+        - 存在哪些 change 分支（`git branch --list 'change/*'`）
+        - 是否有未完成的 change（proposal/tasks 仍含 WS:TODO）
+        - 是否与当前 goal 冲突（同名、同域）
+     d) 检查 git 状态：
+        - 是否有 unpushed 提交（`git log @{u}..HEAD --oneline`）
+        - 是否有 stash（`git stash list`）
+     e) 评估影响：逐项判断与当前 goal 的关联度：
+        - HIGH：阻碍 goal 执行，必须处理
+        - MED：可能干扰或产生误报
+        - LOW：无影响，仅提示
+        - NONE：完全无关，忽略
+     f) 输出结构化分析报告：
+        用格式化的文本块输出，每行标注影响等级：
+        ```
+        ═══ 工作区状态报告 ═══
+        [HIGH] 子模块 web/ dirty（7 文件）— 与 goal 同一目录，可能干扰
+        [MED]  旧 change contract-ai-rag 残留 — 可能干扰依赖链判断
+        [LOW]  .aiws/journal/ 日志文件 — 无影响
+        ════════════════════════
+        ```
+     g) 展示报告后要求用户选择：
+        - **继续** → 进入 step 5
+        - **暂停** → goal status=paused，报告写入 Audit Trail，结束
+        - **先清理** → goal status=paused，输出清理建议步骤，结束
+     用户未确认前，不得进入 step 5。
+
+5) **Pipeline Delegation**：依赖链预检 + workspace 分析通过后，将 goal 完整执行委托给管道 agent。
+    前置条件：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

@@ -1,13 +1,21 @@
 ---
 name: ws-goal
-description: 目标协议：设定可审计的 goal 目标并执行完成闭环（基于 ws-goal-contract.md）
+description: 目标协议：设定可审计的 goal 目标；依赖链预检；管道委托；完成审计
 ---
 # ws-goal
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件，驱动完成闭环。
+- 将用户需求转化为可审计的 goal 目标，按 ws-goal-contract.md 的目标模板写入目标文件。
+- 依赖链预检：阻断"死 change 阻塞下游"这类 chain 问题。
+- 管道委托：预检通过后将完整 pipeline 委托给子 agent（从 ws-plan 一路走到 ws-finish）。
+- 完成审计：claim done 时验证 outcome 真伪。
+
+ws-goal 不做的事：
+- 不直接创建 change、不直接写 code
+- 不替换 review/commit/finish 门禁
+- 不 auto-chain 到下一个 goal（但在同一 goal 内支持多组顺序调度 §6）
 
 前置条件：
 1) 先运行 `/ws-preflight`（对齐 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）。
@@ -20,22 +28,5 @@ description: 目标协议：设定可审计的 goal 目标并执行完成闭环
 2) 接受用户输入的 goal objective，明确目标范围与验收标准。
 3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
 4) 输出 completion audit checklist，列出每个 goal 的完成标准与验证方式。
-5) **Scope Assessment + 路由**：评估目标复杂度，自动选择执行路径：
-   a) 简单（≤5 文件、配置/doc/规范为主、低风险）→ 直行：后续步骤 6-8 auto-finish 闭环
-   b) 复杂（多模块、代码改动 >5 文件、架构/安全/迁移风险）→ 自动触发 `ws-plan` 启动 change 流水线（ws-plan → ws-dev → review → ws-commit → ws-finish），完成后更新 goal status=complete
-   c) 将路由决策写入 goal 文件 Audit Trail
-6) 建议续跑方式：简单路径直行 auto-finish；复杂路径进入 change 流水线后建议 `ws-dev`
-7) 每轮 execution 结束后执行 completion audit，比对 checklist 判断 goal 是否达成；未达成则继续下一轮。
-8) 若 completion audit 确认 goal 达成，自动执行闭环 pipeline：
-   a) Review 检查（按改动类型）：
-      - 配置/文档/规范类（markdown）：内容一致性、引用完整性、内容正确性、无 secrets、格式统一
-      - 代码类（ts/js/py 等）：lint/typecheck 通过、符合现有代码模式、无 secrets、测试通过或覆盖缺口已记录
-      - 混合类：以上两种合并
-   b) 简单路径：`git add` 目标产出文件 → `git commit -m "goal(<goal-id>): <objective 摘要>"` → `git push` → 更新 goal status=complete
-   c) 复杂路径：走 `ws-commit` → `ws-finish` → archive change → 更新 goal status=complete
-   d) 不通过：记录 blocker → 继续 fix 循环
-9) **Auto-chain to next goal**：当前 goal pipeline 完成后：
-   a) 扫描 `.aiws/goals/*.md`，按文件名排序找出第一个 status=pending 的 goal
-   b) 若找到：读取其 objective，输出 "→ Auto-continuing to <goal-id>"，回到步骤 5 创建新 pipeline 自动继续
-   c) 若未找到：输出 "All goals completed" 并结束
-   d) 若找到的 pending goal 缺少 Success Criteria：输出 blocker 并停止（不自动跳过）
+5) **Workspace State Analysis**：分析 dirty/submodule/change artifacts/git 状态，输出影响等级报告，用户确认后才能继续。参考 `/ws-goal` command 的 step 4.5 完整流程。
+6) **Pipeline Delegation**：预检 + 分析通过后，将 goal 完整执行委托给管道 agent。参考 `/ws-goal` command 的 step 5 完整流程。

package/templates/workspace/manifest.json

@@ -48,6 +48,18 @@
     ".opencode/command/ws-plan-verify.md",
     ".opencode/command/ws-spec-review.md",
     ".opencode/command/ws-quality-review.md",
+    ".opencode/command/ws-migrate.md",
+    ".opencode/command/ws-preflight.md",
+    ".opencode/command/ws-pull.md",
+    ".opencode/command/ws-push.md",
+    ".opencode/command/ws-req-change.md",
+    ".opencode/command/ws-req-contract-sync.md",
+    ".opencode/command/ws-req-contract-validate.md",
+    ".opencode/command/ws-req-flow-sync.md",
+    ".opencode/command/ws-req-review.md",
+    ".opencode/command/ws-review.md",
+    ".opencode/command/ws-rule.md",
+    ".opencode/command/ws-submodule-setup.md",
     ".opencode/command/ws-verify-before-complete.md",
     ".opencode/plugins/aiws-inject-context.js",
     ".opencode/plugins/aiws-session-start.js",
@@ -325,7 +337,19 @@
       ".opencode/skills/ws-quality-review/SKILL.md",
       ".opencode/skills/ws-verify-before-complete/SKILL.md",
       ".opencode/skills/ws-rule/SKILL.md",
-      ".opencode/skills/ws-submodule-setup/SKILL.md"
+      ".opencode/skills/ws-submodule-setup/SKILL.md",
+      ".opencode/command/ws-migrate.md",
+      ".opencode/command/ws-preflight.md",
+      ".opencode/command/ws-pull.md",
+      ".opencode/command/ws-push.md",
+      ".opencode/command/ws-req-change.md",
+      ".opencode/command/ws-req-contract-sync.md",
+      ".opencode/command/ws-req-contract-validate.md",
+      ".opencode/command/ws-req-flow-sync.md",
+      ".opencode/command/ws-req-review.md",
+      ".opencode/command/ws-review.md",
+      ".opencode/command/ws-rule.md",
+      ".opencode/command/ws-submodule-setup.md"
     ],
     "managed_blocks": {
       "AGENTS.md": ["agents"],