@aipper/aiws-spec 0.0.45 → 0.0.46

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.46",
   "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