@aipper/aiws-spec 0.0.45 → 0.0.47

package/docs/ws-goal-contract.md

@@ -123,7 +123,19 @@ main → change/A → change/B → change/C (当前)
 |---|---|
 | 全部 HEALTHY | 放行，无需确认 |
 | 存在 STALE | 输出警告，允许继续 |
-| 存在 UNHEALTHY | 输出完整 chain 拓扑 + 健康报告，**必须用户显式确认**才能继续 |
+| 存在 UNHEALTHY | **硬阻断**。输出完整 chain 拓扑 + 健康报告 + 按 link 分类的修复建议，goal status → blocked。用户必须按建议修复上游后重试，或变更 target_base_branch 剔除不健康 link |
+
+**UNHEALTHY 修复建议格式**（每个不健康 link 附带）：
+```text
+link: change/A
+状态: UNHEALTHY (review 有 HIGH blocker)
+修复: 1) `aiws review` → 解决 blocker 后通过 review
+      2) 或 `aiws change target_base_branch main` → 跳过此 link (如适用)
+link: change/D
+状态: UNHEALTHY (50% WS:TODO 未完成，14 天无进展)
+修复: 1) `aiws dev` → 推进 TODO 到 <50%
+      2) 或 `aiws change target_base_branch main` → 跳过此 link
+```
 | 父 change 不存在（孤儿分支）| 阻断，提示选择已知 base |
 | **实际 base_branch ≠ goal target_base_branch** | **阻断**。输出 "goal 声明 target_base_branch = X，但当前 base_branch = Y"，必须用户修正或显式确认才能继续。此检查优先于链健康检查——如果 base_branch 本身就选错了，不需要继续追溯 |
 
@@ -132,7 +144,6 @@ main → change/A → change/B → change/C (当前)
 验证结果必须写入 goal artifact 的 `Dependency Chain` 字段（见 3.1 模板），包括：
 - 完整 chain 拓扑（从 main 到当前）
 - 每个 link 的健康状态与判定理由
-- 用户确认记录（若 UNHEALTHY 被显式放行）
 
 ### 2.5 Workspace State Analysis
 
@@ -171,25 +182,28 @@ ws-goal 在执行 pipeline delegation（管道委托，见 1.§ 第四步）之
 ═══════════════════════
 ```
 
-#### 2.5.4 确认门禁（分级处理）
+#### 2.5.4 自动处理策略（分级自动处理，无阻断）
 
-报告输出后，按影响等级分级处理：
+报告输出后，按影响等级自动处理：
 
 | 等级 | 行为 |
 |------|------|
 | **NONE** | 自动继续。发现项记录到 Audit Trail，不阻断 |
 | **LOW** | 自动继续。输出提示，发现项记录到 Audit Trail |
 | **MED** | 自动继续。输出警告信息，发现项记录到 Audit Trail |
-| **HIGH** | **阻断**。必须等待用户确认后才能继续 |
+| **HIGH** | **自动解决**。按以下策略自动处理每种 HIGH 场景；仅自动化失败时才通知用户 |
 
-**HIGH 阻断确认选项**：
-- **继续** → 进入 pipeline delegation
-- **暂停** → goal status=paused，报告写入 Audit Trail
-- **先清理** → goal status=paused，输出清理建议步骤
+**HIGH 场景自动解决策略**：
 
-用户未确认 HIGH 阻断项，不得进入 delegation。
+| HIGH 场景 | 自动解决行为 |
+|-----------|-------------|
+| Dirty 工作区（staged/unstaged 改动） | `git stash push --keep-index -m "ws-goal auto-stash: <goal-id>"` → 继续。完成后尝试 `git stash pop`，若冲突则输出恢复命令（`git stash drop && git stash pop`），不阻断 |
+| 旧 change 分支未合并 | 输出警告 "检测到遗留 change: <branch>" → **自动继续**。不阻断 |
+| Submodule dirty / detached | `git submodule update --recursive` 自动修复 → 若失败则输出警告并继续 |
+| 同名 goal 冲突 | 追加时间戳后缀自动重命名 → 继续。记录原始 goal id 到 Audit Trail |
+| Unpushed commits | 输出提示 "存在未推送提交" → **自动继续**。不阻断 |
 
-> **设计原则**：LOW/MED 发现项不应阻断工作流。它们被记录到 Audit Trail 供后续回溯，但不需要用户停下当前工作。HIGH 发现项才是真正的风险门禁，必须有用户显式授权放行。
+> 设计原则：工作区问题不应该是 ws-goal 的阻断项。ws-goal 应尽可能自动处理，让用户专注于目标本身，而不是被工作区状态打断。只有自动化处理真正失败时才通知用户——且即使通知也不阻断，只输出提示。
 
 ---
 
@@ -571,7 +585,7 @@ Group 是 goal 内部的一个自包含执行单元：
 | **status** | enum | `pending \| in_progress \| complete \| paused \| failed` |
 | **design_context** | string | 该组的设计草稿/意图说明，委托 subagent 前必须填写 |
 | **internal_tasks** | string[] | 组内部可安全委托的自包含子任务列表，每项应 ≤ 3 文件改动粒度 |
-| **granularity_ok** | boolean | 主 session 在 DEV phase 前设置，true = 该组 scope ≤ 5 文件且不跨模块 |
+| **granularity_ok** | boolean | ⚠️ **已废弃**（v2 起不再手动设置）。改为 Granularity Gate（§6.4 step c）自动计算二级评估（compliant / marginal）并递归自动分解。向后兼容：读取到 `granularity_ok=false` 时等价于 Level 2 MARGINAL（自动分解）；`granularity_ok=true` 时等价于 Level 1 COMPLIANT |
 
 #### 6.2.2 Group Dependencies
 
@@ -633,6 +647,26 @@ phase 间的主 session 验证是门禁：
 - **失败隔离**：一个 phase 失败不影响其他 phase 的产出；只需重试失败的 phase
 - **可审计**：每个 phase 的产出有明确的验证标准，主 session 逐条核验
 
+#### 6.2.5 Scope Advisory（INTAKE 阶段）
+
+Group 结构应在 INTAKE 阶段确定，而非在 Granularity Gate 才暴露。Scope Advisory 在 INTAKE 结束时运行：
+
+1. **输入**：INTAKE 已冻结的目标范围、约束、边界
+2. **评估**：基于以下信号判断 scope 规模：
+   - 涉及文件数（估算）、模块数、跨层改动（API/DB/UI）
+   - 变更类型（重构 vs 新功能 vs 修复）
+   - 与历史 group 的比较经验
+3. **输出**：
+   - scope 合理（≤5 文件、≤2 模块、单层改动）→ 直接继续，单 group
+   - scope 较大（>5 文件或 >2 模块或跨层改动）→ 输出 scope 评估报告，建议分拆：
+     - 提供推荐方案：按模块 / 按阶段 / 其他边界
+     - 用户选择是否拆分及具体方案
+4. **结果**：
+   - 若用户选择拆分 → 在 goal 文件中定义 sub_groups（§6.3 模板）
+   - 若用户选择不拆分 → 单 group 处理，但**提示用户**："注意：如果 scope 执行时 Granularity Gate 发现 >3 文件/多模块，仍会自动拆分为多个执行单元。你不需要管理这些拆分——它们是透明的执行细节。"
+
+设计原则：scope 拆分的决策应在用户参与度最高的 intake 阶段完成，而不是在执行阶段才被发现。Granularity Gate 的职责降为：对已确定结构的 group 做细粒度自动分解（MARGINAL），不做 scope 级的判断。
+
 ### 6.3 Goal File Extension
 
 启用 Pipeline Sequential Dispatch 的 goal，在 `Progress Notes` 字段上方或 `Tasks` 区域添加 groups 定义：
@@ -647,28 +681,88 @@ phase 间的主 session 验证是门禁：
   - "Replace hardcoded grid with <ProductGrid> component"
   - "Add category filter sidebar to category.tsx"
   - "Wire search API endpoint to search.tsx"
-- granularity_ok: false
 - verification:
   - "Home page renders product grid"
   - "Category page renders with filters"
   - "Search results show 10 items per page"
 - depends_on: []
 - status: pending
+# granularity will be auto-assessed by Granularity Gate (§6.4 step c)
 
-### group-2: Purchase Conversion
-- scope: cart.tsx, checkout.tsx, payment-form.tsx
+### group-2: Purchase Conversion (overload example — will auto-decompose)
+- scope: cart.tsx, checkout.tsx, payment-form.tsx, order-history.tsx, return-flow.tsx, email-receipt.tsx
 - design_context: "Purchase flow is client-only, uses React context for cart state"
 - internal_tasks:
   - "Refactor cart context to persist to localStorage"
   - "Add shipping address form with validation"
   - "Implement card number validation with Luhn check"
-- granularity_ok: false
+  - "Add order history page with pagination"
+  - "Implement return request flow with RMA generation"
+  - "Generate email receipt PDF on order confirmation"
 - verification:
   - "Add to cart updates badge count"
   - "Checkout collects shipping address"
   - "Payment form validates card number"
+  - "Order history shows 20 items per page"
+  - "Return request generates RMA number"
+  - "Email receipt is sent on order confirmation"
+- depends_on: [group-1]
+- status: pending
+# Granularity Gate: 6 files > 3 → MARGINAL, auto-split into sub-groups, recurse
+
+### group-3: Search Module (manual recursive nest example)
+- scope: src/search/
+- design_context: "Search module with 3 sub-modules. User pre-split to match team expertise."
+- internal_tasks: []
+- verification:
+  - "Full-text search returns results within 500ms"
+  - "Search history persists across sessions"
+  - "Filter panel updates result list reactively"
 - depends_on: [group-1]
 - status: pending
+- sub_groups:
+  ### group-3/search-core
+  - scope: search.tsx, search-result.tsx, search-store.ts
+  - design_context: "Core search logic: debounced input, API call, result caching"
+  - internal_tasks:
+    - "Implement debounced search input with 300ms delay"
+    - "Wire search API endpoint with abort controller"
+    - "Add result caching layer to search-store"
+  - verification:
+    - "Search input debounces at 300ms"
+    - "API calls are cancellable on input change"
+    - "Cached results served on repeated query"
+  - status: pending
+
+  ### group-3/search-filter
+  - scope: filter-panel.tsx, filter-store.ts, filter-types.ts
+  - design_context: "Filter sidebar with multi-select categories, reactive updates"
+  - internal_tasks:
+    - "Build filter panel UI with multi-select checkboxes"
+    - "Wire filter-store to search-store for reactive result refresh"
+    - "Add URL-sync for filter state persistence"
+  - verification:
+    - "Filter panel shows/hides on toggle"
+    - "Changing filter refreshes search results"
+    - "Filter state restores from URL on page load"
+  - depends_on: [group-3/search-core]
+  - status: pending
+
+  ### group-3/search-history
+  - scope: history.tsx, history-store.ts, history-api.ts
+  - design_context: "Search history: recent queries list, local persistence, clear option"
+  - internal_tasks:
+    - "Implement history-store with localStorage persistence"
+    - "Build history dropdown UI with recent queries"
+    - "Add 'clear history' action with confirmation"
+  - verification:
+    - "Recent queries appear in history dropdown"
+    - "History persists after page reload"
+    - "Clear history removes all entries"
+  - depends_on: [group-3/search-core]
+  - status: pending
+# group-3 manually defines 3 children. Granularity Gate skips parent (has sub_groups),
+# validates each leaf independently. Completion propagates: leaves → parent → goal.
 ```
 
 ### 6.4 Dispatch Protocol (Phase-Level)
@@ -680,29 +774,104 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
 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. Group PHASE 1 - PLAN:
+   a1. **Container group check** (has sub_groups):
+       - If group has pre-defined `sub_groups` → mark as **container** but **proceed to PLAN** (step b)
+       - Container runs PLAN to produce a **single unified proposal** covering all children's scopes
+       - **Container never runs DEV/REVIEW/FINISH itself** — children handle execution
+       - After PLAN → step c processes children recursively → step g propagates completion
+   b. **PHASE 1 - PLAN** (leaf group or container group):
        i.   Construct phase delegation prompt:
+            - **Container group**: include container's scope + all sub_groups' scopes + dependencies
+            - **Leaf group**: include current group scope and verification only
             - Goal outcome, verification (group-level), constraints, boundaries
-            - Current group scope and verification
             - target_base_branch from goal
             - Dependency chain validation results (step 4)
             - Workspace state analysis results (step 4.5)
             - Phase scope: ONLY proposal.md + plan file + plan-verify
             - Phase constraints: NOT dev, NOT review, NOT commit/finish
             - output_manifest: proposal.md, plan file, plan-verify evidence
-      ii.  Delegate to sub-agent:
-           - `task(category="unspecified-high", prompt="...")`
-           - Wait for completion
-      iii. Main session verify:
-           - proposal.md exists
-           - plan file exists with verification commands
-           - plan-verify passed
-           - Fail max 2x → group paused, blocker recorded, STOP
-   c. Granularity Gate (before DEV):
-      i.   Read current group's granularity_ok field
-      ii.  If granularity_ok !== true: output block report (scope, file count, cross-module span), pause goal
-      iii. Verify design_context and internal_tasks non-empty
-      iv.  If either empty: output warning (non-blocking), suggest filling
+       ii.  Delegate to sub-agent:
+            - `task(category="unspecified-high", prompt="...")`
+            - Wait for completion
+       iii. Main session verify:
+            - proposal.md exists (covers ALL children if container)
+            - plan file exists with verification commands
+            - plan-verify passed
+            - Fail max 2x → group paused, blocker recorded, STOP
+c. Granularity Gate & Decomposition (before DEV):
+        ⚠️ **Scope 边界已在 INTAKE 阶段确定（§6.2.5）**。此 Gate 只处理细粒度自动分解（MARGINAL），不做 scope 级的分拆决策。
+        i.   Check if current group has pre-defined sub_groups:
+            - If `sub_groups` field exists and has entries → parent is a **container group**
+            - **Skip** granularity assessment for the container group
+            - For each child in sub_groups, recursively run step c (Granularity Gate on each child)
+            - Child groups with their own sub_groups → recurse deeper
+            - Leaf groups (no sub_groups) → run normal granularity assessment (steps ii-v)
+            - After all leaves pass → return to step d for the **first ready leaf** (topological order)
+            - **Leaves skip PLAN**: container's PLAN (step b) already covers all children; leaves go directly to DEV (step d)
+            - Skip container: it never has its own DEV phase (only children execute)
+       ii.  **Leaf group**: compute granularity assessment:
+            - Count estimated files from scope description (file patterns listed)
+            - Count distinct modules/directories referenced
+            - Count internal_tasks and estimate per-task file scope
+        iii. Granularity classification (2-level assessment, no blocking):
+
+             **Level 1 — COMPLIANT** (≤3 files, single module, each internal_task ≤2 files)
+             → Proceed to DEV phase directly (step d)
+             → Record assessment: `granularity_assessment: "compliant"` in state.json
+
+             **Level 2 — MARGINAL** (>3 files, or multi-module, or any internal_task >2 files, or cannot estimate)
+             → Auto-decompose group into sub-groups:
+               a. Detect module boundaries from scope file paths (same directory prefix → same module)
+               b. If clear module boundaries exist → split by module affinity
+               c. If no clear boundaries (all files in one directory) → split evenly by file count (≤3 files per sub-group)
+               d. Assign each sub-group a compound id: `<group-id>/sub-<N>` (e.g. `group-1/sub-1`)
+               e. Each sub-group inherits parent's design_context and verification
+                f. Each sub-group goes through Granularity Gate recursively (back to step i)
+                   - If sub-group also MARGINAL → split again. Recursion handles arbitrary depth.
+                   - Leaf sub-groups eventually reach COMPLIANT → proceed to DEV
+                f1. **DAG re-validation**: After creating sub-groups (auto or manual), validate their local DAG:
+                    - Ensure no cycles among sub-groups within the same parent
+                    - Ensure all `depends_on` references resolve to known sibling sub-groups or root groups
+                    - If cycle detected → auto-repair: break cycle by removing the longest dependency chain, log warning to Audit Trail
+                    - If unresolved dependency → auto-repair: remove unknown reference, log warning
+                    - Validation applies recursively at each nesting level (sub-groups of sub-groups also validated)
+                g. Parent group becomes container (has sub_groups) → skip DEV, pass-through to children
+               h. Update state.json:
+                  - Parent group status → `in_progress`, `decomposed: true`
+                  - First leaf status → `in_progress`
+                  - `current_group` → first leaf
+             → Record assessment: `granularity_assessment: "marginal", decomposed: true` in state.json
+
+             **No user confirmation needed.** Recursive auto-split handles any scope size.
+
+        iv.  Verify design_context and internal_tasks non-empty:
+             - If design_context empty: output warning (non-blocking), suggest filling before DEV
+             - If internal_tasks empty but scope is clear: MEDIUM warning, auto-generate task suggestions from scope
+        v.   State.json sub-group entry format (for MARGINAL auto-decomposition):
+
+             ```json
+             "groups": {
+               "group-1": {
+                 "status": "in_progress",
+                 "design_context": "...",
+                 "verification": ["..."],
+                 "granularity_assessment": "marginal",
+                 "decomposed": true,
+                 "sub_groups": {
+                   "group-1/sub-1": {
+                     "scope": "src/a.ts, src/b.ts",
+                     "internal_tasks": ["Task 1", "Task 2"],
+                     "status": "in_progress"
+                   },
+                   "group-1/sub-2": {
+                     "scope": "src/c.ts, src/d.ts",
+                     "internal_tasks": ["Task 3", "Task 4"],
+                     "status": "pending"
+                   }
+                }
+              }
+            }
+            ```
    d. Group PHASE 2 - DEV:
        i.   Construct phase delegation prompt:
             - Plan content, proposal links
@@ -755,8 +924,40 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
       iii. Main session verify:
            - Change branch merged to target_base_branch
            - Pushed to remote
-   g. Update group status → complete
-   h. Update goal Progress Notes with group result
+    g. Recursive completion propagation (通用递归，不限于 sub-group):
+        i.   Mark current node `status=complete`
+        ii.  **Find next executable node** — depth-first traversal:
+             a. If current node is a leaf (no sub_groups) → check **next sibling** in parent's child list
+             b. If next sibling exists → set `status=in_progress`, `current_group` = sibling id
+                → Jump to step d (DEV phase)
+             c. If no next sibling → **propagate up**: parent complete → go to step ii-a with parent as current
+             d. If parent has no parent (back at root-level group list) → **check next root-level group**
+                → If found → step a (PLAN phase for next root group)
+                → If not found → all groups complete → go to step 4 (overall completion audit)
+        iii. **Container groups** (groups with sub_groups, never execute DEV themselves):
+             - A container group is marked `status=complete` **only** when all its children are complete
+             - The propagation in step ii-c automatically handles this: last child done → parent complete → check parent's sibling
+        iv.  **Example propagation** (3-level nesting):
+             ```
+             root groups: [group-1, group-2, group-3]
+               group-3 children: [group-3/core, group-3/filter, group-3/history]
+                 group-3/filter depends_on: [group-3/core]
+
+             Execution order:
+               1. group-1 FINISH complete → step g
+               2. check root sibling → group-2 → step a (PLAN)
+               3. group-2 FINISH complete → step g
+               4. check root sibling → group-3 → step a (PLAN)
+               5. group-3 is container → skip → first leaf → group-3/core DEV
+               6. group-3/core FINISH complete → step g
+               7. leaf → check sibling → group-3/filter → DEV (depends on core, satisfied)
+               8. group-3/filter FINISH complete → step g
+               9. leaf → check sibling → group-3/history → DEV
+               10. group-3/history FINISH complete → step g
+               11. leaf → no sibling → propagate up: group-3 complete
+               12. root sibling → none → all complete → step 4 audit
+             ```
+    h. Update goal Progress Notes with group result
 4. All groups complete:
    - Run overall completion audit (all verification + goal-level checks)
    - Update goal state → complete
@@ -925,6 +1126,241 @@ Goal (fully degraded):
 
 退出条件：同一 goal 中后续 group 未出现 §6.8.2 的 entry criteria，主 session 可选择恢复。
 
+### 6.9 Granularity Decomposition Protocol
+
+#### 6.9.1 Motivation
+
+§6.4 step c 将 Granularity Gate 从二进制 pass/block 门禁升级为三级分解机制。本协议定义了分解的具体流程、状态记录和子 group 生命周期，与 §6.4 step c 配合使用。
+
+#### 6.9.2 Decomposition Flow
+
+MARGINAL 自动分解执行流程（支持递归）：
+
+```
+1. 触发条件：叶子 group 通过 Granularity Gate 判定为 MARGINAL
+2. 分解策略：
+   a. 检测 scope 文件的模块边界（同目录前缀 → 同模块）
+   b. 有清晰模块边界 → 按模块分组
+   c. 无清晰边界（单目录多文件）→ 按文件数均分（≤3 files/sub-group）
+3. OUTPUT: 子 group 列表
+   - 每个子 group 包含：scope（≤3 files）、internal_tasks、verification（继承父级）、status
+   - 子 group id = <parent-group-id>/sub-<N>
+4. 每个子 group 递归进入 Granularity Gate（§6.4 step c-i）
+   - COMPLIANT → 进入 DEV
+   - MARGINAL → 继续分解，直到所有叶子为 COMPLIANT
+5. 父 group 自动转为容器（pass-through），不执行自身 DEV
+```
+
+#### 6.9.3 Sub-Group Phase Execution
+
+每个子 group 独立执行完整的 DEV→REVIEW→FINISH 三阶段（**不**重新执行 PLAN，因为 decomposition 发生在 PLAN 之后）：
+
+```
+子 group 执行路径（跳过 PLAN）:
+  Granularity Gate passed (COMPLIANT)
+  → PHASE 2 - DEV:  仅实现该子 group 的 internal_tasks
+  → PHASE 3 - REVIEW: 审计该子 group 的改动
+  → PHASE 4 - FINISH: 提交并合并该子 group 的改动
+```
+
+设计原则：
+- **PLAN 只做一次**：整体 PLAN 在 decomposition 前已完成。子 group 不再重新规划，避免重复开销
+- **每个子 group 独立 DEV**：每个子 group 的改动范围 ≤3 文件，确保 DEV sub-agent 上下文可控
+- **有序合并**：子 group 按顺序执行 FINISH，每个 commit 聚焦一个子 group 的改动，降低 review 负担
+- **失败隔离**：一个子 group 失败不影响其他子 group。修复后只需重试该子 group
+
+```
+整体时间线:
+PLAN (一次) → [sub-1: DEV → REVIEW → FINISH] → [sub-2: DEV → REVIEW → FINISH] → ...
+```
+
+#### 6.9.4 Sub-Group Dependency Within Same Parent
+
+同一父 group 的子 group 之间默认无依赖关系（所有 internal_tasks 在 PLAN 阶段已被认定为可独立执行）。
+
+例外处理：
+- 若 Granularity Gate 检测到子 group 间存在文件级依赖（如 sub-1 修改的文件被 sub-2 引用），自动添加 `depends_on`：
+  - sub-2 `depends_on: [group-1/sub-1]`
+  - 执行顺序自动调整为 sub-1 → sub-2
+- 文件级依赖检测方法：
+  - 检查子 group scope 中的文件是否存在 import/reference 交叉
+  - 若无法自动检测（非结构化 scope 描述）→ 按声明顺序执行（安全默认）
+
+#### 6.9.5 State.json 更新规则
+
+子 group 的 checkpoint 在 state.json 中独立记录：
+
+```json
+{
+  "goal_id": "refactor-pages",
+  "current_phase": "dev",
+  "current_group": "group-2/sub-1",
+  "checkpoints": {
+    "intake": { "status": "complete", "attempts": 0, "completed_at": "2026-07-16T...", "error": null },
+    "goal_def": { "status": "complete", ... },
+    "dep_check": { "status": "complete", ... },
+    "ws_analysis": { "status": "complete", ... },
+    "plan": { "status": "complete", ... },
+    "dev": { "status": "in_progress", "attempts": 0, "completed_at": null, "error": null },
+    "review": { "status": "pending", ... },
+    "finish": { "status": "pending", ... }
+  },
+  "groups": {
+    "group-1": {
+      "status": "complete",
+      "granularity_assessment": "compliant",
+      "decomposed": false
+    },
+    "group-2": {
+      "status": "in_progress",
+      "granularity_assessment": "marginal",
+      "decomposed": true,
+      "sub_groups": {
+        "group-2/sub-1": {
+          "scope": "cart.tsx, checkout.tsx",
+          "internal_tasks": ["Refactor cart context", "Add shipping form"],
+          "status": "in_progress"
+        },
+        "group-2/sub-2": {
+          "scope": "payment-form.tsx, order-history.tsx",
+          "internal_tasks": ["Card validation", "Order history page"],
+          "status": "pending"
+        }
+      }
+    }
+  }
+}
+```
+
+#### 6.9.6 Sub-Group and Degraded Mode Interaction
+
+子 group 也可以进入降级模式（§6.8）：
+
+- 子 group 的 entry criteria 和降级判定**独立于**父 group 和其他子 group
+- 一个子 group 进入降级模式不影响同父的其他子 group
+- 子 group 降级后，degraded-batch.md 记录在 `changes/<id>/patches/degraded-batch-<group-id>-sub-<N>.md`
+- 降级证据中的涉 group 列表改为涉子 group 路径（如 `group-2/sub-1`）
+
+#### 6.9.7 Backward Compatibility (Updated)
+
+| 现有 goal 配置 | 兼容性 |
+|---|---|
+| 含 `granularity_ok: true` 的 group | 兼容。Granularity Gate 读到该字段时降级为 COMPLIANT 处理，直接进入 DEV |
+| 含 `granularity_ok: false` 的 group | 兼容。读到该字段时降级为 MARGINAL（自动分解），不再阻断 |
+| 不含 `granularity_ok` 的 group（新格式） | 正常模式。Gate 按 scope/internal_tasks 自动计算三级评估 |
+| 无 groups 定义的 goal（单 group 模式） | 不受影响。Granularity Gate 仍对隐式 group 执行三级评估 |
+| 含 `sub_groups` 的 group（递归嵌套新格式） | 新增。Gate 跳过容器 group，递归验证叶子节点；自动升级到递归完成传播 |
+
+#### 6.9.8 Recursive Nested Execution
+
+**动机**：§6.4 step c 和 §6.9 的原始设计只支持一层 `group → sub-group` 的自动分解。但用户可能在 goal 定义时已经有一个自然的层级组织（如模块→子模块→文件），需要直接表达为嵌套结构，而不是等 Gate 拆平。
+
+**方案**：group 的 `sub_groups` 字段递归 —— 任何 group 都可以包含 sub_groups，sub_groups 的成员也可以包含自己的 sub_groups，层层嵌套。深度不限。
+
+##### 执行规则
+
+```
+1. 容器 group（有 sub_groups）：不执行自己的 PLAN/DEV/REVIEW/FINISH
+   - 它的 scope 只是描述性汇总，不作为 DEV 粒度依据
+   - 它的 verification 是整体验收，在所有叶子完成后执行（不作为子 group 门禁）
+
+2. 叶子 group（无 sub_groups）：正常执行 PLAN→DEV→REVIEW→FINISH
+   - 叶子是实际的执行单元
+   - Granularity Gate 只对叶子执行三级评估
+
+3. 中间 group（有 sub_groups，自己也是父级的 children）：
+   - 既是父级的 children，也是子级的 container
+   - 不执行 DEV，但负责 propagate 完成状态
+   - 状态流转：所有 children complete → 中间 group complete → propagate 给父级
+
+4. 递归执行入口：
+   - 根层 FOR each group in topological order → 如果是容器 → 不 PLAN，直接找第一个叶子
+   - 叶子走正常 PLAN→DEV→REVIEW→FINISH
+   - 完成时 step g 递归 propagate
+```
+
+##### 执行示例（3 层嵌套）
+
+```
+goal:
+  group-A: 容器
+    group-A/sub-1: 叶子 → PLAN→DEV→REVIEW→FINISH → complete → propagate
+    group-A/sub-2: 容器（中间节点）
+      group-A/sub-2/a: 叶子 → PLAN→DEV→REVIEW→FINISH → complete
+      group-A/sub-2/b: 叶子 → 依赖 sub-2/a → 在其后执行
+      # sub-2 的 children 全部 complete → sub-2 complete → 继续 propagate
+  group-B: 叶子 → 正常执行
+```
+
+##### 与自动分解的关系
+
+两种分解路径共存，在执行层收敛：
+
+```
+用户手工嵌套            Granularity Gate 自动分解
+(group 含 sub_groups)   (叶子 group 不含 sub_groups)
+      │                         │
+      └──────────┬──────────────┘
+                 ▼
+         递归验证叶子粒度
+         容器 group 跳过
+                 │
+                 ▼
+         叶子走 DEV→REVIEW→FINISH
+         完成时递归 propagate
+                 │
+                 ▼
+         全部 complete → 整体审计
+```
+
+- 用户手工嵌套的 group，Gate **跳过**粒度评估（假设用户已合理拆分）
+- 仅对**叶子**做 COMPLIANT/MARGINAL 二级评估
+- MARGINAL 叶子可以进一步自动拆 sub-sub-group（递归）
+- 两种路径从执行层开始统一，叶子执行路径完全相同
+
+##### State.json 递归表示
+
+```json
+{
+  "groups": {
+    "group-A": {
+      "status": "complete",
+      "sub_groups": {
+        "group-A/sub-1": {
+          "status": "complete",
+          "granularity_assessment": "compliant"
+        },
+        "group-A/sub-2": {
+          "status": "complete",
+          "sub_groups": {
+            "group-A/sub-2/a": { "status": "complete" },
+            "group-A/sub-2/b": { "status": "complete" }
+          }
+        }
+      }
+    },
+    "group-B": {
+      "status": "in_progress",
+      "granularity_assessment": "compliant"
+    }
+  }
+}
+```
+
+##### Auto-Advance 保证
+
+递归嵌套下的自动推进由 §6.4 step g（递归完成传播）保证，不需要额外配置：
+
+| 事件 | 自动推进行为 |
+|------|------------|
+| 叶子 group FINISH 完成 | step g 自动检查兄弟 → 无则 propagate 父级 → 检查父级兄弟 → 持续到根 |
+| 中间节点所有 children 完成 | 自动标记 complete → propagate 给父级 |
+| 根层 group 完成 | 自动检查下一个根层 group → 进入其 PLAN (如果是叶子) 或递归找其第一个叶子 |
+| 所有 group 完成 | 触发整体 completion audit（§6.5） |
+| 叶子 Granularity Gate 发现 MARGINAL | 自动拆 sub-group，递归执行，同一套 propagate 机制 |
+
+**保证**：一旦 DEV 开始，在整体审计前不需要任何人干预。递归嵌套 + 自动分解处理任意 scope 大小。无阻断点。
+
 ## 7. Persistence & Resume
 
 ### 7.1 Motivation & Gap Analysis
@@ -1067,10 +1503,42 @@ Instructions: Continue from the failed phase. Do NOT redo completed phases.
 3. 如果 status 为 complete 或 archived：
    - 不生成 state.json（不需要恢复）
 
-### 7.7 Limitations
+### 7.7 State.json 生命周期管理
+
+#### 7.7.1 原子写入协议
+
+所有 state.json 写入必须使用原子写入模式，防止进程崩溃导致文件损坏：
+
+```shell
+# 写入流程：
+1. 构建完整 state.json 内容到内存
+2. 序列化为 JSON 字符串
+3. 写入临时文件:  cat > ".aiws/goals/<goal-id>.state.json.tmp"
+4. 原子重命名: mv ".aiws/goals/<goal-id>.state.json.tmp" ".aiws/goals/<goal-id>.state.json"
+```
+
+**规则**：
+- 从不直接原地编辑 state.json
+- 从不使用多步写入（如 write→read→write 循环）
+- 每次写入必须是一次完整的 JSON 对象替换
+- 临时文件与目标文件在同一文件系统（同一目录），保证 `mv` 原子性
 
-- state.json 是当前工作区本地文件，不支持跨设备同步
-- 如果用户手动删除或修改 state.json，ws-goal 降级为全量重跑（可重新生成）
+#### 7.7.2 损坏检测与恢复
+
+读取 state.json 时执行以下检测：
+
+| 检测项 | 行为 |
+|--------|------|
+| 文件不存在 | 按 §7.7.3 处理 |
+| JSON 解析失败（语法错误） | 视为损坏，降级为全量重跑，输出警告"state.json 损坏，已忽略" |
+| JSON 结构校验失败（缺少必填字段） | 尝试修补默认值，若不可修补则降级为全量重跑 |
+| 多个 checkpoint 同时 in_progress | 阻断，输出诊断报告，要求手动修复 |
+| **状态机跃迁非法**（如从 `plan` 跳到 `finish` 跳过 `dev`）| 自动修复：重置所有后续 phase 为 `pending`，输出警告 |
+
+#### 7.7.3 恢复策略
+
+- 如果用户手动删除或修改 state.json，ws-goal 降级为全量重跑（从 PHASE 0 开始，可重新生成）
+- 如果 state.json 损坏且无法修复，ws-goal 降级为暂停，输出恢复指引，等待主 session 检查 goal .md 文件的 Progress Notes 手动判断下一步
 - 并行执行多个 goal 时，state.json 独立管理，互不依赖
 - state.json 不包含 secrets 或凭证信息
 
@@ -1083,12 +1551,14 @@ Instructions: Continue from the failed phase. Do NOT redo completed phases.
 当前协议依赖主 session 在 phase 完成后手动判断"已完成 phase X，现在开始 phase Y"。这个判断是纯机械的，每次都重复一样逻辑。Auto-Advance 将此机械工作自动化，减少阶段转换摩擦。
 
 **覆盖范围**：Auto-Advance 适用于完整 phase 生命周期，不仅限于 pipeline 内部的 PLAN→DEV→REVIEW→FINISH 阶段间推进。它同样适用于：
-- INTAKE → GOAL_DEF（intake 无 UNRESOLVED_BRANCH 时自动推进）
+- INTAKE → GOAL_DEF（intake 完成后自动推进。Scope Advisory（§6.2.5）是 intake 的正常对话部分，用户确认后自动继续，不视为阻断）
 - GOAL_DEF → DEP_CHECK（goal 定义完成后自动进入依赖链预检）
 - DEP_CHECK → WS_ANALYSIS（依赖链通过后自动进入工作区分析）
-- WS_ANALYSIS → PLAN（工作区分析无 HIGH 阻断项时自动进入 PLAN）
+- WS_ANALYSIS → PLAN（工作区 HIGH 自动解决后自动进入 PLAN）
+
+**所有 phase 边界均自动推进**。不应询问用户。INTAKE 问问题和 scope advisory 是正常流程（不是阻断）；工作区问题自动解决（§2.5.4）；scope 拆分的 OVERLOAD 在 INTAKE 阶段由 Scope Advisory 处理（§6.2.5），不延迟到 Granularity Gate；PLAN 多分支按序全部执行；依赖链 UNHEALTHY 是唯一硬阻断（§2.4.3），用户需修复上游或改 base_branch 才能继续，不提供"确认放行"选项。
 
-唯一需要人工确认的 phase 转换：**当前 phase 存在真实阻断项时**（UNRESOLVED_BRANCH、依赖链 UNHEALTHY、工作区分析 HIGH、PLAN 多分支无明确推荐）。这些阻断必须由 §2.5.4、§2.4.3 或 §7.9.2 的规则产生，不得在无阻断时额外询问用户。
+**CLI 编码**：此章节描述的自动推进决策逻辑由 `aiws goal advance` CLI 命令实现（§10）。CLI 读取 state.json，执行状态机校验，计算下一个 phase/group，然后写入更新后的 state.json。pre-commit hook 在每次提交时调用 `aiws goal validate-state` 校验 state.json 一致性。不再依赖 AI 对自然语言描述的理解来推导"下一步去哪"。
 
 #### 7.8.2 Mechanism
 
@@ -1112,6 +1582,11 @@ phase 完成 → checkpoint status=complete（写入 state.json）
 Current phase in_progress:
 1. Sub-agent completes current phase → main session 验证通过
 2. Main session 更新 checkpoint → status=complete + timestamp
+2.5. **Budget check**（在推进前检查预算）:
+    a. 读取 goal 的 `token_budget` 和 `time_budget`（§3.4），与当前已消耗值比较
+    b. 如果 token 或 time 预算耗尽 → `status=budget_limited`，生成进度报告，**停止**推进
+    c. 如果预算未耗尽 → 进入 step 3
+    d. 预算检查适用于所有 phase 边界（包括递归嵌套的子组推进）
 3. Main session 扫描 state.json checkpoints:
    a. 找到第一个 status=pending 且「所有依赖的 group phase 已 complete」的 checkpoint
    b. 若找到 → 设置 current_phase, current_group，checkpoint status=in_progress
@@ -1192,19 +1667,25 @@ Auto-Advance 在降级模式下仍然适用，但推进逻辑调整：
 
 #### 7.9.1 Motivation
 
-某些决策点（如 PLAN 产出后的多分支选择）需要业务判断，不能完全自动化。但是，当前模式要求用户从原始计划产出中自行推导选项和权衡，认知负担高。
+某些决策点需要业务判断，不能完全自动化。但 ws-goal 的默认策略是：**能自动走的就不停**。只在两种情况下才需要用户决策：
+- 选项**互斥**（选择了 A 就不能选择 B）
+- ws-goal 自动处理失败（如工作区修复、分解方案估算）
+
+不在非互斥场景下询问用户"先做哪个"——所有非互斥路径按序全部执行。
 
-**原则**：AI 做分析、结构化和建议，用户做决策。不在无阻断时提问，但在真正需要判断时提供预处理的选项。
+**原则**：AI 做分析、结构化和建议，用户做决策。但仅当路径真正互斥时才需要决策。
 
 #### 7.9.2 触发条件
 
-结构化决策支持适用于以下场景：
+结构化决策支持适用于以下场景（**仅互斥路径**）：
 
-| 场景 | 产出物 | 说明 |
-|------|--------|------|
-| **PLAN 多分支选择** | PLAN 产出包含多个可行路径 | 如"Phase1&2 vs Phase3 vs 修 P0 stub" |
-| **修复方案选择** | 同一问题有多种修复方式 | 如"回滚 vs 热修复 vs 临时规避" |
-| **优先级排序** | 多个独立任务需决定执行顺序 | 如"先修高风险 bug vs 先加固测试" |
+| 场景 | 产出物 | 说明 | 是否阻断 |
+|------|--------|------|---------|
+| **修复方案选择** | 同一问题有多种修复方式 | 如"回滚 vs 热修复 vs 临时规避" | ✅ 互斥，需用户选择 |
+| ~~Granularity OVERLOAD~~ | — | 已移除：递归嵌套自动分解处理任意 scope 大小，不再需要用户确认 | ❌ 不再视为决策点 |
+| ~~依赖链 UNHEALTHY~~ | — | 已移除：硬阻断，不提供"确认放行"选项，必须修复上游 | ❌ 非决策点 |
+| ~~PLAN 多分支选择~~ | — | 已移除：PLAN 产出所有路径按序执行 | ❌ 不再视为决策点 |
+| ~~优先级排序~~ | — | 已移除：多个独立 task 按声明顺序执行 | ❌ 不再视为决策点 |
 
 #### 7.9.3 输出格式
 
@@ -1255,9 +1736,9 @@ Oracle-Advisor 是一个可选的协议角色，用于在决策点提供分析
 |--------|---------|----------------|
 | Intake → Plan 转换 | ✅ 自动（无阻断时） | 无需 Oracle |
 | 工作区分析 LOW/MED | ✅ 自动（§2.5.4） | 无需 Oracle |
-| 工作区分析 HIGH | ❌ 用户确认 | Oracle 可辅助分析 HIGH 项是否可降级 |
-| 依赖链 UNHEALTHY | ❌ 用户确认（§2.4.3） | Oracle 可分析 UNHEALTHY 的实际影响范围 |
-| PLAN 多分支选择 | ❌ 用户决策（§7.9） | **Oracle 生成结构化建议块（§7.9.3）** |
+| 工作区分析 HIGH | ✅ 自动解决（§2.5.4） | Oracle 仅在自动修复失败时辅助分析 |
+| 依赖链 UNHEALTHY | 🚫 硬阻断（§2.4.3） | Oracle 可分析 UNHEALTHY 的影响范围及修复方案 |
+| ~~PLAN 多分支选择~~ | ✅ 全部执行（§7.9.2） | 无需 Oracle |
 | 阶段间推进 | ✅ Auto-Advance（§7.8） | 无需 Oracle |
 
 #### 7.10.3 角色约束

package/package.json

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

package/templates/workspace/.githooks/pre-commit

@@ -31,6 +31,15 @@ fi
 
 "$aiws_bin" validate .
 
+# Goal state integrity check (blocking if errors)
+if [[ -d "$root/.aiws/goals" ]]; then
+  if ! "$aiws_bin" goal validate-state >/dev/null 2>&1; then
+    echo "error: goal state validation failed — state machine integrity check" >&2
+    echo "hint: run 'aiws goal validate-state' to see details" >&2
+    exit 1
+  fi
+fi
+
 # Quality gates (non-blocking warnings)
 if [[ -f "package.json" ]] && grep -q '"lint"' package.json 2>/dev/null; then
   npm run lint >/dev/null 2>&1 || echo "warn: lint found issues (non-blocking)" >&2

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

@@ -31,6 +31,20 @@ ws-goal 只做三件事，不做更多：
       - 若发现 status=active 或 status=paused 的 state.json，输出恢复选项（从失败的 phase 继续 / 跳过 / handoff）
       - 用户选择后设置 current_phase 到对应 phase 并继续执行
    c) 若未找到 state.json 但有 status=active 或 status=paused 的 .md 文件（旧格式迁移），按 §7.6 自动生成 state.json 后全量重跑
+   d) 若发现 status=complete 的 state.json 但 checkpoints 中仍有未完成项（status != complete）：
+      - 读取对应 `.aiws/goals/<goal-id>.md` 文件，输出 goal 摘要
+      - 列出所有未完成的 checkpoints（status=in_progress/pending/failed 的项）
+      - 输出续跑选项：
+        - （a）跳过 PHASE 0，从依赖链预检（step 4）恢复执行
+            自动跳过 step 1-3（真值读取/目标输入/文件生成），使用已有 goal 文件
+        - （b）查看 goal 详情
+        - （c）忽略，按新目标处理
+      - 若用户选择 a）：
+        - 设置 state.json：status=active，current_phase 到最近一个未完成 checkpoint 对应 phase
+        - 输出"跳过 PHASE 0，从 step 4 依赖链预检恢复"
+        - 直接进入 step 4 继续执行
+      - 若用户选择 b）：输出完整 goal 详情后回到选项
+      - 若用户选择 c）：作为新目标正常走 step 0→1→2 完整流程
 
 1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
 

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

@@ -0,0 +1,285 @@
+---
+description: 目标协议：设定可审计的 goal 目标；依赖链预检；完成审计
+---
+<!-- AIWS_MANAGED_BEGIN:opencode:ws-goal -->
+# ws goal
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+## 职责边界
+
+ws-goal 只做三件事，不做更多：
+
+| 做 | 不做 |
+|---|---|---|
+| 录入目标（写 `.aiws/goals/<id>.md`） | 直接在 main session 创建/驱动 change（通过 pipeline subagent 委托执行） |
+| 依赖链预检（上游死 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/` 目录（先扫描 `.state.json`，再扫描 `.md`）：
+   a) 若用户仅查询状态（无明确目标），列出所有 goal 文件及其 status 字段，然后结束。
+   b) 扫描 `.aiws/goals/*.state.json`：
+      - 若发现 status=active 或 status=paused 的 state.json，输出恢复选项（从失败的 phase 继续 / 跳过 / handoff）
+      - 用户选择后设置 current_phase 到对应 phase 并继续执行
+   c) 若未找到 state.json 但有 status=active 或 status=paused 的 .md 文件（旧格式迁移），按 §7.6 自动生成 state.json 后全量重跑
+   d) 若发现 status=complete 的 state.json 但 checkpoints 中仍有未完成项（status != complete）：
+      - 读取对应 `.aiws/goals/<goal-id>.md` 文件，输出 goal 摘要
+      - 列出所有未完成的 checkpoints（status=in_progress/pending/failed 的项）
+      - 输出续跑选项：
+        - （a）跳过 PHASE 0，从依赖链预检（step 4）恢复执行
+            自动跳过 step 1-3（真值读取/目标输入/文件生成），使用已有 goal 文件
+        - （b）查看 goal 详情
+        - （c）忽略，按新目标处理
+      - 若用户选择 a）：
+        - 设置 state.json：status=active，current_phase 到最近一个未完成 checkpoint 对应 phase
+        - 输出"跳过 PHASE 0，从 step 4 依赖链预检恢复"
+        - 直接进入 step 4 继续执行
+      - 若用户选择 b）：输出完整 goal 详情后回到选项
+      - 若用户选择 c）：作为新目标正常走 step 0→1→2 完整流程
+
+1) 读取真值文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`），确认项目规则与边界。
+
+2) 接受用户输入的 goal objective，明确目标范围与验收标准。
+
+3) 按 ws-goal-contract.md 的目标模板生成目标文件，写入 `.aiws/goals/<goal-id>.md`。
+   并同时创建 `.aiws/goals/<goal-id>.state.json`（§7.2 格式），初始状态 `status=active`、`current_phase=intake`、所有 checkpoints pending。
+   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) 展示报告后要求用户选择：
+         - **继续** → 更新 state.json checkpoint `ws_analysis=complete`，进入 step 5
+         - **暂停** → state.json status=paused，报告写入 Audit Trail，结束
+         - **先清理** → state.json status=paused，输出清理建议步骤，结束
+      用户未确认前，不得进入 step 5。
+
+5) **Phase-Level Pipeline Delegation**：依赖链预检 + workspace 分析通过后，将 goal 拆分为 PLAN→DEV→REVIEW→FINISH 四个 phase 顺序执行，每个 phase 委托给独立轻量子 agent，主 session 验证每个 phase 产出后决定继续/重试/暂停。
+     前置条件：step 4 必须通过（ALL HEALTHY 或 UNHEALTHY 已显式放行）。若 step 4 阻断，不允许 delegation。
+     前置条件 2：不存在 status=active 的 change 分支。若有，让用户选择「使用已有 change 继续」或「暂停」。
+     前置条件 3：每个 pipeline phase 开始前更新 state.json `current_phase` + checkpoint `status=in_progress`；完成/失败后对应更新 checkpoint。
+
+5a) **Check for Groups**：读取 goal 文件，检查是否定义了 `Groups` 区域。
+    - 若 goal **不含** groups → 走单组 phase-level pipeline（step 5b-5g）
+    - 若 goal **包含** groups → 走 Sequential Group Phase-Level Dispatch（step 5.1）
+
+--- 以下为 phase-level pipeline（无 groups 的 goal） ---
+
+5b) **Phase-Level Sequential Execution**：主 session 按 PLAN→DEV→REVIEW→FINISH 顺序执行 4 个 phase，每个 phase 前检查当前进度（支持断点续跑）。共用一个 change 分支，change id = goal-id。
+
+5c) **PHASE 1 - PLAN**（主 session 执行 change start + 委托子 agent 做 plan）：
+    1. 主 session 执行 `aiws change start <goal-id> --allow-dirty`（若 change 已存在则跳过）
+    2. 委托子 agent 执行 PLAN phase：
+        ```
+        task(
+          category="unspecified-high",
+          description="PLAN phase for goal <goal-id>",
+          prompt="TASK: Write proposal.md + plan file + run plan-verify for goal <goal-id>.
+                  INPUT: goal file at .aiws/goals/<goal-id>.md, truth files at AI_PROJECT.md/REQUIREMENTS.md/AI_WORKSPACE.md.
+                  CONSTRAINTS: Do NOT implement code. Do NOT do review. Do NOT commit.
+                  COMPLETION: proposal.md exists, plan file exists, plan-verify passes."
+        )
+        ```
+    3. 主 session 验证产出：
+        - proposal.md 文件存在
+        - plan 文件存在
+        - plan-verify 通过
+    4. 验证通过 → 进入 PHASE 2
+    5. 验证失败 → 可重试最多 2 次 → 仍失败则 goal state=paused，记录 blocker
+
+5d) **PHASE 2 - DEV**（委托子 agent 做 dev）：
+    1. 委托子 agent 执行 DEV phase：
+        ```
+        task(
+          category="deep",
+          description="DEV phase for goal <goal-id>",
+          prompt="TASK: Implement all code changes per plan for goal <goal-id>.
+                  INPUT: proposal.md at .aiws/changes/<goal-id>/proposal.md, plan file.
+                  CONSTRAINTS: Do NOT modify proposal or plan files. Do NOT commit.
+                  COMPLETION: All changes implemented, lint/typecheck clean."
+        )
+        ```
+    2. 主 session 验证产出：
+        - diagnostics 干净（`lsp_diagnostics` 检查改动文件）
+        - 改动范围与 plan 一致
+    3. 验证通过 → 进入 PHASE 3
+    4. 验证失败 → goal state=paused，记录 blocker
+
+5e) **PHASE 3 - REVIEW**（委托子 agent 做 review）：
+    1. 委托子 agent 执行 REVIEW phase：
+        ```
+        task(
+          category="unspecified-high",
+          load_skills=["review-work"],
+          description="REVIEW phase for goal <goal-id>",
+          prompt="TASK: Audit code changes for goal <goal-id>, produce review evidence.
+                  INPUT: proposal.md, plan file, changed files.
+                  CONSTRAINTS: Do NOT modify code. Do NOT commit.
+                  COMPLETION: Review evidence files exist, no HIGH blockers."
+        )
+        ```
+    2. 主 session 验证产出：
+        - review 证据文件存在
+        - 无未解决的 HIGH blocker
+    3. 验证通过 → 进入 PHASE 4
+    4. 验证失败 → goal state=paused，记录 blocker
+
+5f) **PHASE 4 - FINISH**（委托子 agent 做 commit + finish）：
+    1. 委托子 agent 执行 FINISH phase：
+        ```
+        task(
+          category="quick",
+          load_skills=["git-master"],
+          description="FINISH phase for goal <goal-id>",
+          prompt="TASK: Commit and finish (merge + push) for goal <goal-id> change branch.
+                  CONSTRAINTS: Do NOT modify code. Git operations only.
+                  COMPLETION: Change branch merged to target_base_branch and pushed."
+        )
+        ```
+    2. 主 session 验证产出：
+        - 确认 change 分支已合并到 target_base_branch
+        - 确认已推送
+    3. 验证通过 → goal state=complete，输出 "Goal <goal-id> complete"
+    4. 验证失败 → goal state=paused，记录 blocker
+
+5g) **Simple Goal Escape Hatch**：若 goal 为简单改动（≤3 文件，配置/doc/规范变更，无架构风险）：
+    - 可跳过 PHASE 3（REVIEW），在 PHASE 2 验证后直接进入 PHASE 4
+    - 必须在 goal 文件的 Progress Notes 标注 "skipped review phase (simple goal)"
+
+--- 以下为 Sequential Group Phase-Level Dispatch（含 groups 的 goal） ---
+
+5.1) **Sequential Group Phase-Level Dispatch**：
+     当 goal 文件包含 Groups 定义时，ws-goal 按依赖顺序逐个调度每个 group，每个 group 内按 5c-5f 的 4-phase 流程执行。主 session 负责编排每个 group 的 4 个 phase 并验证每个 phase 的产出。
+
+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（phase-level）**：
+     FOR each group in 拓扑顺序：
+       1. 更新 group status → `in_progress`，写入 goal 文件 Progress Notes
+       2. **PHASE 1 - PLAN**（同 5c，但 change id = `<goal-id>-<group-id>`）：
+          - 主 session 执行 `aiws change start <goal-id>-<group-id> --allow-dirty`
+          - 委托子 agent 写 proposal.md + plan 文件 + plan-verify
+          - 主 session 验证：proposal/plan 存在，plan-verify 通过
+       3. **PHASE 2 - DEV**（同 5d，scope 限定到当前 group）：
+          - 委托子 agent 按 plan 实现当前 group 的代码改动
+          - 主 session 验证：diagnostics 干净，改动匹配 group scope
+       4. **PHASE 3 - REVIEW**（同 5e，scope 限定到当前 group）：
+          - 委托子 agent 审计当前 group 改动
+          - 主 session 验证：review 证据存在，无 HIGH blocker
+       5. **PHASE 4 - FINISH**（同 5f）：
+          - 委托子 agent 做 commit + finish
+          - 主 session 验证：分支已合并推送
+       6. 任一 phase 失败 → group status = paused/failed，记录 blocker，**STOP**（后续 group 不再调度）
+       7. 全部 phase 通过 → 更新 group status → `complete`，更新 Progress Notes
+          - 若 goal 配置了多组并行：可在 PLANNING 通过且 DAG 无冲突前提下的顺序执行
+
+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（从失败的 phase 重新开始）
+       - （b）跳过该 group（标记 complete，继续下游）
+       - （c）暂停并 handoff
+     - 用户选择后执行对应操作
+<!-- AIWS_MANAGED_END:opencode:ws-goal -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。