@aipper/aiws-spec 0.0.42 → 0.0.44

package/docs/ws-goal-contract.md

@@ -171,14 +171,25 @@ ws-goal 在执行 pipeline delegation（管道委托，见 1.§ 第四步）之
 ═══════════════════════
 ```
 
-#### 2.5.4 确认门禁
+#### 2.5.4 确认门禁（分级处理）
 
-报告输出后，必须等待用户确认：
+报告输出后，按影响等级分级处理：
+
+| 等级 | 行为 |
+|------|------|
+| **NONE** | 自动继续。发现项记录到 Audit Trail，不阻断 |
+| **LOW** | 自动继续。输出提示，发现项记录到 Audit Trail |
+| **MED** | 自动继续。输出警告信息，发现项记录到 Audit Trail |
+| **HIGH** | **阻断**。必须等待用户确认后才能继续 |
+
+**HIGH 阻断确认选项**：
 - **继续** → 进入 pipeline delegation
 - **暂停** → goal status=paused，报告写入 Audit Trail
 - **先清理** → goal status=paused，输出清理建议步骤
 
-用户未确认，不得进入 delegation。
+用户未确认 HIGH 阻断项，不得进入 delegation。
+
+> **设计原则**：LOW/MED 发现项不应阻断工作流。它们被记录到 Audit Trail 供后续回溯，但不需要用户停下当前工作。HIGH 发现项才是真正的风险门禁，必须有用户显式授权放行。
 
 ---
 
@@ -379,9 +390,50 @@ Auto-resume 时输出以下通知（含问题级进度展示，但不需要用
 2. 启发式判断已 frozen 问题：找到第一个未回答的问题标记，之前的都算 frozen
 3. 生成 state.json，status=in_progress
 
----
+#### 3.2.9 上下文感知 INTAKE（Context-Aware Intake）
+
+**问题**：用户可能在未使用 ws-goal 的情况下已经开始工作（如直接修 bug、做重构、编写代码）。此时执行 ws-goal，PHASE 0 INTAKE 从空白开始提问，用户需要重新陈述已做的工作，体验割裂。
+
+**方案**：PHASE 0 在开始对抗式审问前，先扫描工作区获取上下文信号，预填充 intake 的初始答案。
+
+**扫描信号**：
+
+| 信号 | 来源 | 可靠性 |
+|------|------|--------|
+| 未提交变更 | `git diff --stat` | 高（具体文件与改动量） |
+| 最近提交 | `git log --oneline -5` | 高（可反映近期工作主题） |
+| Change 分支 | `git branch --list 'change/*'` | 高（aiws 管理的分支） |
+| 孤立 intake 草稿 | `.aiws/plan/*.intake.md` | 高（aiws 工件） |
+| 进行中的 intake | `.aiws/intake/*.state.json` | 高（aiws 工件） |
+| 暂存的工作 | `git stash list` | 中（可能有无关的 stash） |
+
+**不使用的信号**：会话日志（短暂/有损）、lsp_diagnostics（与意图无关）。
 
-### 3.3 Evidence Type Registry
+**退化处理**：非 git 目录下，所有 git 命令（`git diff --stat`、`git log`、`git branch --list`、`git stash list`）应检测并静默跳过，对应信号标记为 `unavailable`。扫描退化为仅依赖非 git 信号（孤立 intake 草稿、进行中的 intake state.json）。若全部信号均不可用，输出"未检测到现有工作上下文"，intake 从空白开始。
+
+**大篇幅截断**：`git diff --stat` 输出超过 20 行（约 20 个文件）时，截断为"`<N> files changed, <+M>/-R`"总计行，不再逐文件列出。完整 diff 可通过 `git diff --stat` 查看。`git log --oneline -5` 保持最多 5 条不变。
+
+**输出格式**：
+
+```text
+═══ 工作区上下文 ═══
+未提交改动: BizDeviceRepo.kt (+12 -0) — 修复 activeType 过滤
+最近提交:   "fix: device/pages filter activeType and deviceId"
+Change 分支: change/fix-auth (3 commits, 未合并)
+孤立 Intake: .aiws/plan/20240115-auth-intake.md (3/5 问题已冻结)
+════════════════════
+```
+
+**预填规则**：
+
+1. 扫描输出作为上下文摘要，嵌入 intake 草案开头
+2. 对抗式审问的初始问题答案以此上下文预填（用户可见并可修改确认）
+3. 预填内容不影响 checkpoint 机制——所有 checkpoint 仍为 pending，不从预填内容推导阶段完成
+4. 工作区上下文扫描是 intake 阶段的内部实现细节，不影响外部协议接口（goal.md、state.json 格式不变）
+5. 若扫描无任何发现（空工作区），输出"未检测到现有工作上下文"，intake 从空白开始
+6. 预填的 intake 问题答案状态为 `prefill_pending`（非 `frozen`）。用户必须显式确认后状态才变为 `frozen`。此规则将"no checkpoint backfilling"原则延续到 intake 问题级：预填是初始提示（prompt），不从预填内容推导问题已冻结，不绕过用户的确认权。`.aiws/intake/<id>.state.json` 中问题 `status` 字段在预填状态下仍保持 `pending`，直到用户确认后才写入 `frozen`。
+
+**设计原则**：缩短用户输入成本，不改变审计完整性。上下文预填是提示（prompt）而非判断（judgment）——用户始终拥有最终确认权。
 
 完成审计使用的证据类型：
 
@@ -629,14 +681,15 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
 3. FOR each group in topological order:
    a. Update group status → in_progress
    b. Group PHASE 1 - PLAN:
-      i.   Construct phase delegation prompt:
-           - 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
+       i.   Construct phase delegation prompt:
+            - 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
@@ -651,22 +704,39 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
       iii. Verify design_context and internal_tasks non-empty
       iv.  If either empty: output warning (non-blocking), suggest filling
    d. Group PHASE 2 - DEV:
-      i.   Construct phase delegation prompt:
-           - Plan content, proposal links
-           - Phase scope: ONLY implement per plan + local verify
-           - Phase constraints: NOT modify proposal/plan, NOT commit
-      ii.  Delegate to sub-agent:
-           - `task(category="deep", prompt="...")`
-           - Wait for completion
-      iii. Main session verify:
-           - Diagnostics clean (lsp_diagnostics on changed files)
-           - Changes match plan scope
-           - Fail → group paused, blocker recorded, STOP
-   e. Group PHASE 3 - REVIEW:
-      i.   Construct phase delegation prompt:
-           - Proposal + plan + changed files
-           - Phase scope: ONLY audit, produce review evidence
-           - Phase constraints: NOT modify code
+       i.   Construct phase delegation prompt:
+            - Plan content, proposal links
+            - Phase scope: ONLY implement per plan + local verify
+            - Phase constraints: NOT modify proposal/plan, NOT commit
+            - output_manifest: list of promised output files (paths relative to repo root)
+       ii.  Delegate to sub-agent:
+            - `task(category="deep", prompt="...")`
+            - Wait for completion
+        ii.a Output Verification Gate:
+             - Read back the output_manifest from sub-agent's final response
+             - Glob check each promised file exists
+             - Minimum content check: each file > 3 lines of non-whitespace content
+             - Exception：声明为配置/单行格式的文件（manifest 中标记 `"config": true` 或文件扩展名为 `.env`、`.json`、`.conf` 等配置格式），最小内容检查降为 ≥1 行非空白内容
+            - All pass → continue to step iii
+            - Fail → classify failure before retry:
+              a) Zero files produced → CLASS-A (prompt too complex, context overflow)
+              b) Partial files produced → CLASS-B (narrow scope; retry only missing files)
+              c) All files exist but content empty/wrong → CLASS-C (check diagnostics, retry with augmented context)
+            - Retry strategy per class:
+              - CLASS-A: split goal into smaller sub-goals or invoke degraded mode (see §6.8)
+              - CLASS-B: retry only missing files with narrowed prompt
+              - CLASS-C: retry with additional context (plan, related source files)
+            - Max 2 retries per class; after exhaustion → group paused, blocker recorded, STOP
+       iii. Main session verify:
+            - Diagnostics clean (lsp_diagnostics on changed files)
+            - Changes match plan scope
+            - Fail → group paused, blocker recorded, STOP
+    e. Group PHASE 3 - REVIEW:
+       i.   Construct phase delegation prompt:
+            - Proposal + plan + changed files
+            - Phase scope: ONLY audit, produce review evidence
+            - Phase constraints: NOT modify code
+            - output_manifest: review evidence files
       ii.  Delegate to sub-agent:
            - `task(category="unspecified-high", prompt="...")`
            - Wait for completion
@@ -674,10 +744,11 @@ ws-goal 执行 Phase-Level Sequential Dispatch 时遵循以下协议：
            - Review evidence files exist
            - No HIGH blocker unresolved
            - Fail → group paused, blocker recorded, STOP
-   f. Group PHASE 4 - FINISH:
-      i.   Construct phase delegation prompt:
-           - Phase scope: ONLY commit + finish
-           - Phase constraints: NOT modify code
+    f. Group PHASE 4 - FINISH:
+       i.   Construct phase delegation prompt:
+            - Phase scope: ONLY commit + finish
+            - Phase constraints: NOT modify code
+            - output_manifest: commit SHA, merge confirmation
       ii.  Delegate to sub-agent:
            - `task(category="quick", load_skills=["git-master"], prompt="...")`
            - Wait for completion
@@ -723,8 +794,16 @@ Phase-Level Pipeline Dispatch 的审计分散在各 phase 的门禁验证中，
 
 1. ws-goal 记录当前组停止位置到 Progress Notes
 2. 标记 goal state=paused
-3. **默认重试**：下一 session 自动从失败 phase 重新委托（不询问 skip）
-4. 重试耗尽（3 次）后自动暂停并 handoff，输出恢复上下文供手动处理
+3. **Failure classification**：在重试前，按 Output Verification Gate（§6.4 step ii.a）的分类判断失败原因：
+   - CLASS-A（系统性缺陷：prompt 复杂度过高、context 溢出）→ **不盲重试**，拆分后再试或进入降级模式（§6.8）
+   - CLASS-B（局部缺失：部分文件未产出）→ 缩小范围重试缺失部分
+   - CLASS-C（质量缺陷：文件存在但内容错误）→ 补充上下文后重试
+   - 未触发 Output Verification Gate 的失败（如 phase 验证未通过）→ 归入 CLASS-C 处理
+4. **默认重试**：下一 session 自动从失败 phase 根据分类策略重新委托（不询问 skip）
+5. 重试耗尽（每种分类 2 次，总计最多 6 次）后自动暂停并 handoff，输出恢复上下文供手动处理
+6. **Escalation to degraded mode**：若同一 group 在 2 种不同分类中各失败 1 次，主 session 可选择：
+   - 继续按当前分类重试
+   - 将该 group 切换为降级模式（§6.8）——main session 直接 batch-edit，post-hoc review 覆盖审计
 
 ### 6.7 Backward Compatibility
 
@@ -734,6 +813,118 @@ Phase-Level Pipeline Dispatch 的审计分散在各 phase 的门禁验证中，
 | 含 groups 定义的 goal（新格式） | 进入 Phase-Level Sequential Dispatch 模式，每 group 按 4-phase 执行 |
 | 已有 goal 工件（.md 文件） | 兼容。goal 文件格式不变，仅 delegation 执行方式变更 |
 
+### 6.8 Degraded Mode Protocol
+
+#### 6.8.1 Motivation
+
+当 group scope 过大（CLASS-A 失败反复出现）或子 agent 反复失败（多种分类各消耗 1 次重试）时，完整 4-phase 委托的开销可能超过其收益。此时继续保持多轮委托只会加剧"退回直接编辑"的崩溃——main session 在重试 3 轮后放弃协议，直接改代码。
+
+降级模式提供** sanctioned 的中间路径**：在 maintain auditability 的前提下，减少事前委托、增加事后审计。
+
+#### 6.8.2 Entry Criteria
+
+任一条件满足即可进入降级模式（由主 session 自主判定，**不阻断**）：
+
+| 条件 | 触发值 |
+|---|---|
+| CLASS-A 失败 ≥ 2 次（同一 group） | 当前 group 可降级 |
+| 同一 group 的 2 种不同分类各失败 1 次 | 当前 group 可降级 |
+| goal 含 > 10 个 group 且 ≥ 30% 失败 | 整个 goal 可降级 |
+| 主 session 主动声明 `degraded: true` | 指定 group 可降级 |
+
+#### 6.8.3 Degraded Mode Protocol
+
+降级模式修改 §6.2.4 的 delegation model：
+
+```
+group execution (degraded):
+  PHASE 1 - PLAN:    正常 4-phase 委托（不变）
+  PHASE 2 - DEV:     main session 直接 batch-edit（跳过低层级子 agent 委托）
+                       → output verification gate 由 main session 自行验证
+                       → 改动记录到 changes/<id>/patches/degraded-batch.md
+  PHASE 3 - REVIEW:  正常 review 委托（不变，reviewer 独立审查 batch-edit 产出）
+  PHASE 4 - FINISH:  正常 finish 委托（不变）
+```
+
+**变更内容**（Degraded DEV）：
+
+- DEV phase 不再委托给子 agent，改为 main session 直接使用 `edit` / `write` 工具批量修改文件
+- main session 在开始 batch-edit 前，必须将预期改动写入 `changes/<id>/patches/degraded-batch.md`（格式见下）
+- batch-edit 完成后，main session 自行运行验证：`lsp_diagnostics` + 测试命令
+- 验证通过后，继续进入 REVIEW phase（独立 reviewer 审查 batch-edit 的改动）
+- REVIEW phase 不变：独立 reviewer 仍然从需求 / 实现质量 / 回归风险角度审查
+
+**关键约束**：
+- **不能跳过 REVIEW phase**。降级模式只跳过低层级子 agent 委托，不跳过审查门禁
+- **不能跳过 completion audit**。§6.5 的总体审计在降级模式下同样适用
+- 降级只作用于当前 group，不强制影响其他 group
+- REVIEW 发现 HIGH blocker 时，修复仍在降级模式下进行（main session 直接修复，不走子 agent 重试循环）
+- 降级模式的 group 在 completion audit 中标记为 `degraded: true`，区分于正常委托 group
+
+**嵌套失败边界**：
+- 降级模式**不能嵌套**——已在降级模式下的 group 如果 REVIEW 或 FINISH 委托再次失败（CLASS-A/B/C），`"进入降级模式"`的升级路径替换为`"暂停 group 并 handoff"`。
+- 原因：降级模式已经是 full delegation 的最后逃生通道；如果 sub-agent 在降级模式（REVIEW 或 FINISH）下仍然反复失败，说明问题不在 delegation 模式，而是目标本身或上下文不完整——此时重试无意义，应暂停并输出恢复上下文供手动处理。
+
+#### 6.8.4 Degraded Batch Record 格式
+
+```markdown
+# Degraded Batch: <goal-id> / <group-id>
+
+## Trigger
+- <entry criteria>: <具体描述，如 "DEV phase CLASS-A 失败 2 次：context overflow">
+
+## Expected Changes
+| File | Operation | Summary |
+|------|-----------|---------|
+| src/a.ts | edit | Rename validate() to validateEmail() |
+| src/b.ts | edit | Add null check before call |
+| src/a.test.ts | write | Add edge case tests |
+
+## Verification
+- [ ] lsp_diagnostics clean
+- [ ] Test command 1: npm test -- --filter ...
+- [ ] Test command 2: ...
+
+## Actual Outcome
+- [ ] All changes applied
+- [ ] Diagnostics clean
+- [ ] All tests pass
+- Notes: <any issues during batch-edit>
+```
+
+#### 6.8.5 全局降级模式
+
+当整个 goal 进入降级模式（所有 group 降级），执行链路：
+
+```
+Goal (fully degraded):
+  INTAKE → PLAN (once, for all groups) → DEGRADED DEV (batch-all groups) → REVIEW (once, full goal) → FINISH
+```
+
+此时不拆分为逐 group 的 4-phase 循环，而是：
+1. 一个 PLAN 子 agent 产出所有 group 的 proposal + plan
+2. Main session 对所有 group 批量编辑（记录到同一份 degraded-batch.md）
+3. 一个 REVIEW 子 agent 审查全部改动
+4. 一个 FINISH 子 agent 完成提交
+
+#### 6.8.6 降级证据记录
+
+降级模式的 group 必须记录以下证据：
+- `changes/<id>/patches/degraded-batch.md`：预期改动 + 验证结果（主 session 在 batch-edit 前写入）
+- `changes/<id>/review/degraded-review.md`：reviewer 对 batch-edit 的审查结论（与正常 review 证据文件格式一致）
+- `changes/<id>/evidence/degraded-evidence.md`：降级触发原因 + 涉及 group + 当前降级范围（主 session 在进入降级模式时写入）
+- goal Progress Notes 记录降级原因 + 涉及 group 列表
+
+三个文件共同构成降级模式的完整证据链：batch 记录（what changed）→ 审查结论（review 确认）→ 降级记录（why degraded）。
+
+#### 6.8.7 退出降级
+
+降级模式是 group 级别的选项。下一 group 可以：
+- 保持降级（如果主 session 判定 delegation 仍然不可行）
+- 恢复完整 4-phase 委托
+
+退出条件：同一 goal 中后续 group 未出现 §6.8.2 的 entry criteria，主 session 可选择恢复。
+
 ## 7. Persistence & Resume
 
 ### 7.1 Motivation & Gap Analysis
@@ -836,6 +1027,17 @@ Session 重启后 ws-goal step 0 检测流程：
 
 > 设计原则：用户执行 ws-goal 即代表意图明确——继续未完成的工作。重复询问"是否要继续"增加摩擦、不增加价值。仅在无法自动决策时（如多个冲突 goal）才需要用户介入。
 
+#### 7.4.1 Question Tool Interruption
+
+`question` tool 调用会中断当前会话，下一个会话是新的 session 边界。Auto-Resume（§7.4）适用：
+
+1. 执行者在调用 `question` tool **之前**，必须先写入 state.json 检查点（更新 `current_phase` 与当前 checkpoint `status=in_progress`）。
+2. 写入完成后调用 `question` tool。会话可能在此后结束。
+3. 下一个会话启动时，Auto-Resume 检测到 status=active 的 state.json，自动从当前 phase 恢复。
+4. `question` 的上下文已在注入 §7.5 continuation context 时一并传递，不需要额外持久化。
+
+> 例外：如果 `question` 在 PHASE 0（INTAKE）阶段调用，此时尚未创建 state.json。执行者应在 `question` 前记录 intake 草案到 `plan/<timestamp>-<slug>.intake.md`，下个会话通过询问用户后重新从 PHASE 0 开始。
+
 ### 7.5 Continuation Context Template
 
 当 session 重启后检测到 paused goal 并 auto-resume 时，ws-goal 技能注入以下上下文：
@@ -871,3 +1073,238 @@ Instructions: Continue from the failed phase. Do NOT redo completed phases.
 - 如果用户手动删除或修改 state.json，ws-goal 降级为全量重跑（可重新生成）
 - 并行执行多个 goal 时，state.json 独立管理，互不依赖
 - state.json 不包含 secrets 或凭证信息
+
+### 7.8 Pipeline Auto-Advance
+
+#### 7.8.1 Motivation
+
+§7.4 定义了 session 重启时的 auto-resume（向后恢复），但缺少**前向自动推进**——当当前 phase 完成后，自动读取 state.json 启动下一个 phase，而不是等待主 session 手动检查 checkpoint 并触发下一轮委托。
+
+当前协议依赖主 session 在 phase 完成后手动判断"已完成 phase X，现在开始 phase Y"。这个判断是纯机械的，每次都重复一样逻辑。Auto-Advance 将此机械工作自动化，减少阶段转换摩擦。
+
+**覆盖范围**：Auto-Advance 适用于完整 phase 生命周期，不仅限于 pipeline 内部的 PLAN→DEV→REVIEW→FINISH 阶段间推进。它同样适用于：
+- INTAKE → GOAL_DEF（intake 无 UNRESOLVED_BRANCH 时自动推进）
+- GOAL_DEF → DEP_CHECK（goal 定义完成后自动进入依赖链预检）
+- DEP_CHECK → WS_ANALYSIS（依赖链通过后自动进入工作区分析）
+- WS_ANALYSIS → PLAN（工作区分析无 HIGH 阻断项时自动进入 PLAN）
+
+唯一需要人工确认的 phase 转换：**当前 phase 存在真实阻断项时**（UNRESOLVED_BRANCH、依赖链 UNHEALTHY、工作区分析 HIGH、PLAN 多分支无明确推荐）。这些阻断必须由 §2.5.4、§2.4.3 或 §7.9.2 的规则产生，不得在无阻断时额外询问用户。
+
+#### 7.8.2 Mechanism
+
+使用基于 **state.json checkpoint 文件产出**的自动推进，不依赖文本标记（如 `PHASE_DONE` 字符串）：
+
+```
+phase 完成 → checkpoint status=complete（写入 state.json）
+          → 读取 state.json，找到下一个 status=pending 的 checkpoint
+          → 若存在 → 自动启动该 phase（注入职责+上下文）
+          → 若不存在 → 全部完成，触发整体 completion audit（§6.5）
+```
+
+**不使用文本标记**的原因：
+- 依赖 agent 输出固定格式字符串是脆弱耦合（格式偏差即断链）
+- 文件状态（checkpoint written/last_phase.json 存在）是更可靠的信号
+- state.json 的 `status` 字段是机器可读、工具无关的检查点
+
+#### 7.8.3 Phase Transition Protocol
+
+```
+Current phase in_progress:
+1. Sub-agent completes current phase → main session 验证通过
+2. Main session 更新 checkpoint → status=complete + timestamp
+3. Main session 扫描 state.json checkpoints:
+   a. 找到第一个 status=pending 且「所有依赖的 group phase 已 complete」的 checkpoint
+   b. 若找到 → 设置 current_phase, current_group，checkpoint status=in_progress
+   c. 若未找到 → 全部完成，进入整体 completion audit
+4. **Context offload**（phase 间上下文卸载）:
+   a. Main session 写入 phase summary 到 Progress Notes（goal .md 文件）
+   b. Main session 写入当前 phase 的关键产出摘要到 state.json（extra 字段）
+   c. Main session **释放**当前 phase 的原始上下文（raw output、sub-agent logs）——不再保留在活动窗口中
+   d. 从 state.json 冷加载下一 phase：
+      - 读取 goal objective、verification、boundaries
+      - 读取下一 phase 的 checkpoint 状态
+      - 读取上一 phase 的 summary（仅摘要，非原始输出）
+      - 构造新 phase 的委托 prompt
+5. 启动下一 phase
+
+Phase complete → 明确标记为 complete
+Phase failed → 标记为 failed，走 §6.6 Failure Recovery
+```
+
+#### 7.8.4 Context Offload
+
+每个 phase 完成后的上下文卸载是 auto-advance 的关键机制，防止主 session 上下文累积导致性能下降或崩溃：
+
+| 保留内容 | 卸载内容 |
+|---|---|
+| Phase 摘要（≤10 行结构化总结） | Sub-agent 完整输出 |
+| 关键产物的文件路径+checksum | 产物具体内容 |
+| 当前 phase 的 blocker/recovery 记录 | Sub-agent 中间错误栈 |
+| 下一 phase 需要的输入引用 | 上一 phase 的全文 prompt |
+| Goal objective & verification（持久引用） | 历史 phase 的委托结果原文 |
+
+**卸载方法**：
+
+```yaml
+# Progress Notes 中的 phase summary 格式
+PHASE <name> (<group-id>):
+  status: complete | failed
+  summary: "<10-line structured summary of what happened>"
+  outputs:
+    - file: <path>    # 关键产出路径
+      check: <checksum or "verified">
+  blockers: <none or description>
+  next_phase_input: <引用信息供下一 phase 使用>
+```
+
+#### 7.8.5 与 §7.4 Resume Protocol 的关系
+
+| 协议 | 方向 | 触发条件 |
+|---|---|---|
+| Auto-Resume（§7.4） | 向后恢复 | Session 重启、检测到 paused/active state.json |
+| Auto-Advance（§7.8） | 前向推进 | 当前 phase complete、下一 phase pending |
+
+两者互补：
+- Auto-Resume 从 state.json 恢复中断位置
+- Auto-Advance 在运行中沿 state.json 向前推进
+- 两者共享同一套 checkpoint 状态机
+  
+**重新进入 Auto-Advance**：Auto-Resume 恢复 phase 后，该 phase 完成时重新进入 Auto-Advance 循环（启动接下来的 phase），不需要额外状态。
+
+#### 7.8.6 失败行为
+
+- Phase 验证未通过 → 不推进，走 §6.6 Failure Recovery
+- state.json 不一致（多个 checkpoint 同时 in_progress）→ 阻断，输出诊断报告，要求手动修复
+- state.json 缺失（被手动删除）→ 降级为暂停，等待主 session 检查 goal .md 文件的 Progress Notes 手动判断下一步
+
+#### 7.8.7 与 Degraded Mode 的交互
+
+Auto-Advance 在降级模式下仍然适用，但推进逻辑调整：
+
+- 降级模式 group 的 DEV phase 由 main session 直接 batch-edit（不经过子 agent 委托），但 main session 仍将 DEV checkpoint 写入 state.json（status=complete + `degraded: true`）
+- Auto-Advance 读取 state.json 时，`degraded: true` 标记的 checkpoint 视为 complete，正常推进到 REVIEW phase
+- REVIEW phase 仍然委托给子 agent，无论当前 group 的 DEV 是否处于降级模式
+- 全 goal 降级模式（§6.8.5）下，Auto-Advance 的 phase 序列变为：`intake → goal_def → dep_check → ws_analysis → plan → dev (degraded) → review → finish`
+
+**即**：降级模式改变的是*执行方式*（batch-edit vs delegation），不改变 checkpoint 状态机。Auto-Advance 不关心执行方式，只关心 checkpoint 状态。
+
+### 7.9 Structured Decision Support
+
+#### 7.9.1 Motivation
+
+某些决策点（如 PLAN 产出后的多分支选择）需要业务判断，不能完全自动化。但是，当前模式要求用户从原始计划产出中自行推导选项和权衡，认知负担高。
+
+**原则**：AI 做分析、结构化和建议，用户做决策。不在无阻断时提问，但在真正需要判断时提供预处理的选项。
+
+#### 7.9.2 触发条件
+
+结构化决策支持适用于以下场景：
+
+| 场景 | 产出物 | 说明 |
+|------|--------|------|
+| **PLAN 多分支选择** | PLAN 产出包含多个可行路径 | 如"Phase1&2 vs Phase3 vs 修 P0 stub" |
+| **修复方案选择** | 同一问题有多种修复方式 | 如"回滚 vs 热修复 vs 临时规避" |
+| **优先级排序** | 多个独立任务需决定执行顺序 | 如"先修高风险 bug vs 先加固测试" |
+
+#### 7.9.3 输出格式
+
+当出现多分支时，主 session 必须将选项格式化为结构化建议块：
+
+```text
+══════ 决策建议 ══════
+分支 A：<标题>
+  内容：<该分支包含的具体工作>
+  风险：<风险评估>
+  预估：<时间/工作量>
+  推荐理由：<何时选择此分支>
+
+分支 B：<标题>
+  内容：<该分支包含的具体工作>
+  风险：<风险评估>
+  预估：<时间/工作量>
+  推荐理由：<何时选择此分支>
+
+推荐：<分支 A/B/C 及理由>
+═══════════════════════
+```
+
+用户从选项中确认选择。仅在无明确推荐时（如各分支风险/收益相近）才需要用户主动分析。
+
+#### 7.9.4 与 Oracle 集成
+
+当 PLAN 产出包含多分支时，可委托 Oracle 分析各分支的代码级影响，生成结构化建议块：
+
+```
+PLAN 产出 → Oracle 读 PLAN + 代码扫描 + git 历史
+  → 分析各分支风险/工作量/依赖
+  → 输出结构化建议块（§7.9.3 格式）
+  → 主 session 呈现给用户
+```
+
+Oracle 的 role 是**决策支持**（decision support），不是**决策制定**（decision making）。用户始终拥有最终决策权。
+
+### 7.10 Oracle-Advisor Protocol Role
+
+#### 7.10.1 定义
+
+Oracle-Advisor 是一个可选的协议角色，用于在决策点提供分析支持。它不是一个独立的阶段或执行者，而是在主 session 编排中按需调用的**只读顾问**。
+
+#### 7.10.2 触发条件
+
+| 决策点 | 自动执行 | Oracle 参与模式 |
+|--------|---------|----------------|
+| 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）** |
+| 阶段间推进 | ✅ Auto-Advance（§7.8） | 无需 Oracle |
+
+#### 7.10.3 角色约束
+
+| 维度 | 约束 |
+|------|------|
+| **读取范围** | 仅当前决策点相关的工件（PLAN 产出、代码扫描片段、git 历史摘要）。不得读取未关联文件 |
+| **写入范围** | 仅写入 `changes/<id>/analysis/oracle-decision-<phase>.md` 或显示在会话输出中。不得修改任何代码/工件 |
+| **输出格式** | 必须包含：分析摘要、置信度信号、推荐选项及理由、升级路径 |
+| **不可访问时** | 降级为不依赖 Oracle 的建议，仍用 §7.9.3 格式输出（由主 session 直接生成结构化块） |
+
+#### 7.10.4 工件格式
+
+Oracle 的分析输出必须写入 `changes/<id>/analysis/oracle-decision-<phase>.md`：
+
+```markdown
+---
+oracle_advisor:
+  phase: <phase 名称>
+  triggered_at: <ISO 8601>
+  confidence: high | medium | low
+---
+
+## 分析摘要
+
+<5 行以内的分析总结>
+
+## 置信度信号
+
+| 信号 | 评估 | 说明 |
+|------|------|------|
+| 证据完整性 | high/medium/low | 所需工件是否齐全 |
+| 规范规则 | deterministic/ambiguous | 规范是否明确规定了行为 |
+| 业务依赖 | none/partial/critical | 决策是否需要业务上下文 |
+
+## 推荐选项
+
+<结构化建议块，见 §7.9.3>
+
+## 升级路径
+
+<如果 confidence=medium 或 low，说明什么条件下应升级到用户>
+```
+
+#### 7.10.5 与 §7.8 Auto-Advance 的关系
+
+- Auto-Advance 负责**机械性 phase 推进**（无分支、无阻断时自动走）
+- Oracle-Advisor 负责**决策点分析**（有分支或阻断时提供结构化建议）
+- 两者不重叠：Auto-Advance 在无阻断时自动推进；Oracle-Advisor 在决策点提供信息支持
+- Oracle-Advisor 分析完成后，主 session 或用户做出最终决定，然后 Auto-Advance 继续推进

package/package.json

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