@aipper/aiws-spec 0.0.42 → 0.0.43

package/docs/ws-goal-contract.md

@@ -629,14 +629,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 +652,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 +692,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 +742,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 +761,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 +975,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 +1021,109 @@ 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 将此机械工作自动化，减少阶段转换摩擦。
+
+#### 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 状态。

package/package.json

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

package/templates/workspace/.opencode/skills/using-aiws/SKILL.md

@@ -7,14 +7,14 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 
 目标：默认入口，先读真值文件，判定当前任务 workflow，再进入具体 `ws-*` skill。若意图不明确：先澄清，不直接进入实现。
 
+阶段定位：bootstrap/router 阶段；负责分流，不直接完成实现。
+
 ## 编排约束
 
-- **不直接实现**：`using-aiws` 自身不是实现阶段；只判 workflow、读真值、路由到对应 `ws-*`。主 session 不直接写代码。
-- **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——具体检查：`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）、`AI_WORKSPACE.md` 中声明的验证命令可行性。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+- **不直接实现**：只判 workflow、读真值、路由到对应 `ws-*`。主 session 不直接写代码。
+- **上下文先于判决**：路由 `direct_implementation` 前必须收集项目上下文——`git status --porcelain`（改动文件数）、`git diff --stat`（改动行范围）、`AI_WORKSPACE.md` 验证入口。仅当 ≤3 文件、≤100 行改动、验证明确时，才可判 direct。
 - **意图不明先澄清**：`routeTo=clarify` 时必须停止并问 1-3 个关键问题，不猜测。
 
-阶段定位：bootstrap/router 阶段；负责分流，不直接完成实现。
-
 ## 必需输入
 
 - 当前任务描述
@@ -27,40 +27,24 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 
 ## 阻断条件
 
-- 无法确定项目根目录
-- 缺失任一真值文件
-- 无法明确当前任务意图
-- 无法明确归因或验证入口，且不能安全推断
+- 无法确定项目根目录、缺失任一真值文件、无法明确任务意图、无法归因且不能安全推断
 
 ## 执行步骤
 
 ### 1. Preflight
 
-读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
-
-- 若检测到 `.opencode/oh-my-opencode.json`：输出 `oMo-enabled`
-- 若未检测到：输出 `standard-opencode`
-- 若缺失任一真值文件 → route = `$ws-preflight`，建议先 `aiws init .`
+读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。若检测到 `.opencode/oh-my-opencode.json` 输出 `oMo-enabled`，否则 `standard-opencode`。缺失真值文件则 route = `$ws-preflight`，建议 `aiws init .`
 
 ### 1.5 Per-turn Breadcrumb（必做）
 
-每轮对话开始时强制读取当前 change 状态（`.aiws/changes/<change-id>/.ws-change.json` 或 phase 状态文件），输出 `[workflow-state:PHASE/N]` breadcrumb 标记。
-
-目的：即使 context 被压缩，breadcrumb 也能让 AI 知道当前处于哪个阶段、上次做到哪一步。
-
-格式：`[workflow-state:PHASE_NAME/N]`，其中 PHASE_NAME 取自 standardChain，N 为步骤序号。
+每轮对话开始时读取当前 change 状态，输出 `[workflow-state:PHASE_NAME/N]` 标记。
 
 ### 2. 路由判定
 
-根据 `packages/spec/docs/workflow-router-rules.json` 判定：
-
-- 路由前先读上下文：判 direct_implementation 前，router 必须先收集项目上下文（git status、涉及文件范围），确认是真正的单文件修复，再决定 direct vs plan。
+根据 `packages/spec/docs/workflow-router-rules.json` 判定。判 direct_implementation 前必须先收集上下文（git status、涉及文件范围）：
 
-上下文收集清单（判 direct_implementation 前必须完成）：
-- `git status --porcelain` — 确认未提交改动范围
-- `git diff --stat` — 确认改动文件数量
-- 改动涉及 ≤2 文件且均在已知路径 → 可判 direct
-- 改动涉及 ≥3 文件或含未知路径 → 必须走 ws-plan
+- ≤2 文件且均在已知路径 → direct
+- ≥3 文件或含未知路径 → ws-plan
 
 | 意图 | Route |
 |------|-------|
@@ -75,53 +59,32 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 | 极简修复 | `$ws-dev-lite` |
 | Subagent 不可用 | 回退单 agent + 工件模式 |
 
-注：`$ws-dev` 默认走 subagent-first 策略（详见 `packages/spec/docs/opencode-subagent-first.md`）。主 session 应优先通过 `$ws-delegate` 派发 `aiws-worker`，除非用户明确说"直接改"或"do it inline"。
+注：`$ws-dev` 默认走 subagent-first 策略。主 session 应优先通过 `$ws-delegate` 派发 `aiws-worker`，除非用户明确说"直接改"。
 
-**Escape Hatch**：若用户明确说"跳过流程"/"直接改"/"do it inline"，允许走 `direct_implementation` 路由，但必须：
-1. 输出 `[escape-hatch: direct-implementation]` 标记
-2. 仍须归因到 Req_ID / Problem_ID
-3. 仍须有可复现验证入口
-4. 仍须落盘 evidence 标记 escape-hatch 使用原因
+**Escape Hatch**：用户明确说"跳过流程"时允许 direct_implementation，但须输出 `[escape-hatch]` 标记、归因到 Req_ID、有可复现验证入口、落盘 evidence 注明原因。
 
 ### 3. 意图不明确
 
-只问 1-3 个关键问题，明确缺什么（意图、Req_ID/Problem_ID、verify、change 上下文），然后停止。
+只问 1-3 个关键问题（意图、Req_ID/Problem_ID、verify、change），然后停止。
 
 ### 4. Continuation Routing（新 session 恢复）
 
-`.opencode/plugins/aiws-session-start.js` 自动注入 `<resume-recommendation>` 块，包含 active change ID、phase、journal 摘要及 next action。
-
-续跑决策表（与 `aiws-context.js#getChangeState` 同步）：
+续跑决策：
 
-```
-┌──────────────────┬──────────────────────────────────────────────┐
-│ Phase            │ 推荐 Next Action                             │
-├──────────────────┼──────────────────────────────────────────────┤
-│ none（无 change） │ ws-intake 或 ws-plan 建立 change 上下文       │
-│ intake           │ ws-intake 继续澄清，或 ws-plan 转到规划        │
-│ planning         │ plan 存在 → ws-plan-verify；否则 ws-plan       │
-│ ready-for-dev    │ 派发 aiws-worker（subagent-first）             │
-│ in-progress      │ patches 存在 → aiws-reviewer + ws-review      │
-│                  │ 上次 DONE_WITH_CONCERNS → ws-quality-review   │
-│                  │ 否则 worker 继续或 aiws-reviewer 审查          │
-│ review           │ evidence 齐 → ws-finish/ws-commit              │
-│                  │ 否则补 evidence 再提交                         │
-│ finished         │ ws-finish 收尾归档                             │
-│ unknown          │ ws-preflight 重新评估                          │
-└──────────────────┴──────────────────────────────────────────────┘
-```
+| Phase | Next Action |
+|-------|-------------|
+| none（无 change） | ws-intake 或 ws-plan |
+| intake | ws-intake 继续，或 ws-plan |
+| planning | plan 存在→ws-plan-verify；否则 ws-plan |
+| ready-for-dev | 派发 aiws-worker |
+| in-progress | patches 存在→review；was DONE_WITH_CONCERNS→ws-quality-review；否则继续 |
+| review | evidence 齐→ws-finish/ws-commit；否则补 evidence |
+| finished | ws-finish 收尾归档 |
+| unknown | ws-preflight |
 
-Subagent 不可用时的降级路径：
-- ready-for-dev 无 subagent → 当前 agent 直接执行 ws-dev（走 inline escape hatch）
-- in-progress 无 reviewer → 当前 agent 自审（走 evaluate-optimize 1 轮）
-- review 无 oracle → 当前 agent 本地 review（不阻断流程）
+Subagent 降级：无 subagent 时当前 agent 直接执行，evidence 中记录降级原因（`mode: single-agent`）。
 
-特殊状态：
-- 上次 delegation 返回 `BLOCKED` → 先解决 blocker 再继续
-- 上次 delegation 返回 `NEEDS_CONTEXT` → 补 context JSONL 后重新派发
-- Subagent-first 默认：`ready-for-dev` / `in-progress` 默认派发 worker/reviewer
-- Subagent 不可用时：降级为当前 agent 直接执行，但必须在 evidence 中记录降级原因
-- Subagent 不可用时回退：单 agent 模式 + 显式维护 `.aiws/changes/<id>/` 工件（handoff-evidence.md, analysis/, patches/）；不阻断流程，但须标注 `mode: single-agent`
+特殊状态：`BLOCKED` 需解 blocker；`NEEDS_CONTEXT` 补 JSONL 后重试。
 
 ### 5. 输出路由
 
@@ -140,5 +103,7 @@ Next: <继续执行对应 skill，或提出澄清问题>
 
 - Router 自己不实现代码；不给 route 前不直接改代码
 - 一次只选一个主 route
-- 若复杂度升高：`$ws-dev` 回退到 `$ws-plan`；`$ws-finish` 回退到前置门禁
-- 若 subagent 不可用：回退为单 agent 执行，但须维护与 subagent 模式等价的工件结构（handoff、evidence、review 文件），确保后续 session 可接力
+- 复杂度升高：`$ws-dev` 回退 `$ws-plan`；`$ws-finish` 回退前置门禁
+- subagent 不可用：单 agent 执行，但须维护等价工件结构
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`