gsd-lite 0.5.15 → 0.6.1

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "gsd",
       "source": "./",
       "description": "AI orchestration tool — GSD management shell + Superpowers quality core. 5 commands, 4 agents, 5 workflows, MCP server, context monitoring.",
-      "version": "0.5.15",
+      "version": "0.6.1",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd",
-  "version": "0.5.15",
+  "version": "0.6.1",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "author": {
     "name": "sdsrss",

package/README.md

@@ -213,8 +213,8 @@ All state lives in `.gsd/state.json` — a single source of truth with:
 |-----------|-----|----------|
 | Commands | 32 | **6** |
 | Agents | 12 | **4** |
-| Source files | 100+ | **~35** |
-| Installer | 2465 lines | **~80 lines** |
+| Source files | 100+ | **~48** |
+| Installer | 2465 lines | **~290 lines** |
 | User interactions | 6+ confirmations | **Typically 2** |
 | TDD / Anti-rationalization | No | **Yes** |
 | State machine recovery | Partial | **Full (12 modes)** |
@@ -249,7 +249,7 @@ gsd-lite/
 ├── references/             # 8 reference docs
 ├── hooks/                  # Session lifecycle (StatusLine + PostToolUse + SessionStart + Stop + AutoUpdate)
 │   └── lib/               # Shared hook utilities (gsd-finder)
-├── tests/                  # 826 tests (unit + simulation + E2E)
+├── tests/                  # 866 tests (unit + simulation + E2E)
 ├── cli.js                  # Install/uninstall CLI entry
 ├── install.js              # Installation script
 └── uninstall.js            # Uninstall script
@@ -258,7 +258,7 @@ gsd-lite/
 ## Testing
 
 ```bash
-npm test                    # Run all 826 tests
+npm test                    # Run all 866 tests
 npm run test:coverage       # Tests + coverage report (94%+ lines, 83%+ branches)
 npm run lint                # Biome lint
 node --test tests/file.js   # Run a single test file

package/agents/debugger.md

@@ -55,8 +55,11 @@ Phase 3 假设测试:
   3. 验证: 有效 → Phase 4 / 无效 → 新假设
 
 Phase 4 修复方向建议:
-  1. 提出修复方案 (针对根因，不是症状)
-  2. 建议失败测试用例 (供 executor 实现)
+  调试器不直接写代码 — 返回 fix_direction + 测试用例描述，由 executor 实施。
+  1. 提出修复方案 (针对根因，不是症状) → 写入 `fix_direction`
+  2. 描述回归测试用例 (测什么、预期 vs 实际) → 供 executor 实现
+     - 不要自己写测试代码，你没有 Write 工具
+     - 用自然语言描述: 输入、操作步骤、预期结果、实际错误行为
   3. 评估修复影响范围 (哪些下游可能受影响)
   → 3 次修复方向均被 executor 验证无效 → 停止。标记 architecture_concern: true。报告给编排器。
 </four_phases>
@@ -66,6 +69,10 @@ Phase 4 修复方向建议:
 {
   "task_id": "2.3",
   "outcome": "root_cause_found | fix_suggested | failed",
+  // outcome 判定:
+  //   root_cause_found — 根因已确认，有明确的修复方向
+  //   fix_suggested    — 部分理解，建议一个尝试方向 (根因尚未完全确认)
+  //   failed           — 穷尽假设仍无法定位根因，或 fix_attempts >= 3
   "root_cause": "Description of the identified root cause",
   "evidence": [
     { "id": "ev:repro:error-xyz", "scope": "task:2.3", "command": "npm test", "exit_code": 1, "stdout": "...", "stderr": "...", "timestamp": "ISO8601" }
@@ -73,8 +80,8 @@ Phase 4 修复方向建议:
   "hypothesis_tested": [
     { "hypothesis": "X causes Y", "result": "confirmed | rejected", "evidence": "non-empty string (required)" }
   ],
-  "fix_direction": "Suggested fix approach for executor",
-  "fix_attempts": 0,
+  "fix_direction": "Suggested fix approach for executor (include suggested test case description)",
+  "fix_attempts": 0, // 由编排器 dispatch context 中的 debug_context 传入，记录已尝试的修复方向次数
   "blockers": [],
   "architecture_concern": false
 }

package/agents/reviewer.md

@@ -51,6 +51,14 @@ L1 普通编码任务 → executor 自审 + 阶段结束时批量 review
 L2 关键任务 → 单任务独立 review
    (涉及认证/支付/数据安全/核心架构的任务)
 
+L3 最高风险任务 → 单任务独立 review + 人工确认
+   (auth/payment/security architecture 等最高风险任务)
+   - 与 L2 相同的双阶段审查流程，外加:
+   - 结果中必须包含 `requires_human_confirmation: true`
+   - review summary 必须明确列出安全影响 (security implications)
+   - 质量审查阶段必须检查 OWASP Top 10 相关问题
+   - 审查通过后 task 进入 `awaiting_user` 而非 `accepted`，需用户显式确认
+
 判定规则按影响面，不按关键词猜测:
   - 改 auth/payment/permission/public API/DB migration/core architecture → L2
   - 纯 docs/comment/style/config 且无运行时语义变化 → L0
@@ -107,7 +115,9 @@ Minor = 建议修复 (命名/风格)
 {
   "scope": "task | phase",
   "scope_id": "2.3 (task scope: string ID) | 2 (phase scope: number ID)",
-  "review_level": "L2 | L1-batch | L1",
+  "review_level": "L2 | L3 | L1-batch | L1",
+  "requires_human_confirmation": false, // L3 时必须为 true
+  "security_implications": [], // L3 时必须列出安全影响
   "spec_passed": true,
   "quality_passed": false,
   "critical_issues": [
@@ -141,4 +151,5 @@ checkpoint commit ≠ accepted
 L0: checkpoint commit = accepted
 L1: checkpoint commit → phase batch review 通过 → accepted
 L2: checkpoint commit → immediate independent review 通过 → accepted
+L3: checkpoint commit → immediate independent review 通过 → awaiting_user → 用户确认 → accepted
 </checkpoint_topology>

package/commands/doctor.md

@@ -102,4 +102,3 @@ Suggested Actions:
 - If a check cannot be performed (e.g., tool unavailable), report INFO rather than FAIL
 - Always show all 5 checks in the summary, even if some are INFO/skipped
 </rules>
-</output>

package/commands/prd.md

@@ -17,13 +17,30 @@ argument-hint: File path to requirements doc, or inline description text
 
 <process>
 
+## STEP 0 — 已有项目检测
+
+调用 `health` 工具（MCP tool 名称: health）。如果返回 state_exists=true 且项目未完成/未失败:
+- 告知用户: "检测到进行中的 GSD 项目。"
+- 显示当前项目状态 (项目名、当前阶段、workflow_mode)
+- 提供选项:
+  - (a) 恢复现有项目 → 转到 `/gsd:resume`
+  - (b) 覆盖并重新开始 → 继续 STEP 1（现有 state.json 将被覆盖）
+  - (c) 取消
+- 等待用户选择后再继续
+
+如果无 state 或项目已完成/已失败 → 直接进入 STEP 1。
+
 ## STEP 1: 解析输入
 
 判断 `$ARGUMENTS` 的类型:
 
 **如果是文件路径** (包含 `/` 或 `.` 且文件存在):
 - 使用 Read 工具读取文件内容
-- 如果文件不存在 → 告知用户并停止
+- 如果文件不存在:
+  - 告知用户文件不存在
+  - 提示常见原因: 路径拼写错误、当前工作目录不正确
+  - 建议: "请确认文件路径，或使用绝对路径重试。需要我帮你查找文件吗？"
+  - 停止
 
 **如果是文本描述**:
 - 直接作为需求描述使用

package/commands/resume.md

@@ -9,19 +9,20 @@ description: Resume project execution from saved state with workspace validation
 
 <process>
 
-## STEP 1: 读取状态
+## STEP 1: 调用 orchestrator-resume 获取状态摘要
 
-读取 `.gsd/state.json`:
-- 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，请先运行 /gsd:start 或 /gsd:prd"，停止
-- 如果文件损坏或解析失败 → 告知用户并停止
+调用 MCP tool `orchestrator-resume`，使用响应中的 `summary` 字段展示状态给用户:
+- 如果响应为 error 且 message 包含 "No .gsd directory" → 告知用户 "未找到 GSD 项目状态，请先运行 /gsd:start 或 /gsd:prd"，停止
+- 如果响应为 error → 告知用户错误信息并停止
 
-提取关键 canonical fields:
+`summary` 字段包含:
 - `workflow_mode` — 当前工作流状态
-- `current_phase` / `current_task` — 当前执行位置
-- `current_review` — 当前审查状态
-- `git_head` — 上次记录的 Git HEAD
-- `plan_version` — 计划版本号
-- `research.expires_at` — 研究过期时间
+- `current_phase` — 当前阶段 (格式: "N/M")
+- `current_task` — 当前任务 (id + name)
+- `phase_progress` — 阶段进度 (格式: "done/total")
+- `recent_decisions` — 最近 2-3 个决策 (如有)
+
+注意: 不需要单独读取 state.json，`orchestrator-resume` 的响应已包含所有需要展示的信息。
 
 ## STEP 2: 前置校验
 
@@ -55,10 +56,15 @@ description: Resume project execution from saved state with workspace validation
    - 或 research.decision_index 中有条目的 expires_at 已过期
    - → 覆写 `workflow_mode = research_refresh_needed`
 
-5. **全部通过:**
+5. **Dirty-phase 回滚检测:**
+   - 检查已完成 phase 中是否有 `needs_revalidation` 状态的 task
+   - 如有 → 回滚 `current_phase` 到最早的 dirty phase
+   - → 覆写 `workflow_mode = executing_task`
+
+6. **全部通过:**
    - 保持原 `workflow_mode` 不变
 
-校验顺序: 1→2→3→4，首个命中的覆写生效 (不累积)
+校验顺序: 1→2→3→4→5，首个命中的覆写生效 (不累积)
 </HARD-GATE>
 
 ## STEP 3: 按 workflow_mode 恢复
@@ -106,8 +112,8 @@ description: Resume project execution from saved state with workspace validation
 ### `awaiting_clear` — 继续自动执行
 
 - 上下文已通过 /clear 清理
-- 直接继续自动执行主路径
-- 从 `current_phase` + `current_task` 恢复调度
+- 再次验证上下文健康度 ≥ 40%，不足则要求再次 /clear
+- 验证通过后从 `current_phase` + `current_task` 恢复调度
 
 ---
 
@@ -208,17 +214,17 @@ description: Resume project execution from saved state with workspace validation
 
 ## STEP 4: 显示当前进度 + 下一动作
 
-每次恢复后都展示简要进度面板:
+每次恢复后使用 `orchestrator-resume` 响应中的 `summary` 字段展示简要进度面板:
 
 ```
-项目: {project}
-模式: {workflow_mode}
-进度: Phase {current_phase}/{total_phases} | Task {done}/{tasks}
-当前: {current_task} — {task_name}
-下一步: {根据 workflow_mode 推导的下一动作}
+模式: {summary.workflow_mode}
+进度: Phase {summary.current_phase} | Task {summary.phase_progress}
+当前: {summary.current_task.id} — {summary.current_task.name}
+决策: {summary.recent_decisions (如有)}
+下一步: {根据 action 推导的下一动作}
 ```
 
-所有展示数据从 canonical fields 实时推导，不使用 derived fields。
+注意: 所有展示数据直接取自 `summary` 字段，不需要额外读取 state.json。
 
 ## STEP 5: 自动执行循环
 

package/commands/start.md

@@ -58,3 +58,11 @@ argument-hint: Optional feature or project description
 使用 Read 工具读取 `workflows/execution-flow.md`，严格按照其中 STEP 5-12 执行。
 
 </process>
+
+<EXTREMELY-IMPORTANT>
+## 编排器纪律
+- 只有编排器写 state.json，子代理不直接写
+- 所有摘要/提示在展示时从 canonical fields 推导，不持久化 derived fields
+- 子代理返回结构化 JSON，不解析自然语言
+- 上下文 < 35% → 保存状态 + workflow_mode = awaiting_clear + 停止执行
+</EXTREMELY-IMPORTANT>

package/hooks/gsd-auto-update.cjs

@@ -7,6 +7,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { execSync, spawnSync } = require('node:child_process');
+const { semverSortComparator } = require('./lib/semver-sort.cjs');
 
 // ── Configuration ──────────────────────────────────────────
 const GITHUB_REPO = 'sdsrss/gsd-lite';
@@ -195,12 +196,13 @@ async function withFileLock(fn) {
     }
   }
 
+  if (!acquired) {
+    return null;
+  }
   try {
     return await fn();
   } finally {
-    if (acquired) {
-      try { fs.rmSync(STATE_LOCK_FILE, { force: true }); } catch {}
-    }
+    try { fs.rmSync(STATE_LOCK_FILE, { force: true }); } catch {}
   }
 }
 
@@ -209,7 +211,7 @@ async function withFileLock(fn) {
 // 1. PLUGIN_AUTO_UPDATE env set → recursive guard (auto-update already in progress)
 // 2. Running from a git clone → dev mode (developer working on source)
 function shouldSkipUpdateCheck() {
-  if (process.env.PLUGIN_AUTO_UPDATE) return true;
+  if (process.env.PLUGIN_AUTO_UPDATE === '1') return true;
   return isDevMode();
 }
 
@@ -297,15 +299,8 @@ async function fetchLatestRelease(token) {
 }
 
 // ── Version Comparison (semver) ────────────────────────────
-function compareVersions(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-  }
-  return 0;
-}
+// Reuse shared comparator; callers only check sign (> 0, < 0, === 0)
+const compareVersions = semverSortComparator;
 
 function getCurrentVersion(mode = getInstallMode()) {
   const candidates = mode === 'manual'
@@ -460,18 +455,25 @@ function pruneOldCacheVersions(cacheBase, keepCount = 3, verbose = false) {
       .map(e => e.name);
     if (entries.length <= keepCount) return;
 
-    // Sort by semver: split into [major, minor, patch] and compare numerically
-    const sorted = entries.slice().sort((a, b) => {
-      const pa = a.split('.').map(Number);
-      const pb = b.split('.').map(Number);
-      for (let i = 0; i < 3; i++) {
-        if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
-      }
-      return 0;
-    });
+    // Sort by semver using shared comparator
+    const sorted = entries.slice().sort(semverSortComparator);
+
+    // Detect versions with active processes to avoid disrupting running sessions
+    let activeVersions;
+    try {
+      const psOutput = spawnSync('ps', ['aux'], { stdio: 'pipe', timeout: 5000 });
+      const lines = (psOutput.stdout || '').toString();
+      activeVersions = new Set(
+        entries.filter(ver => lines.includes(`/cache/gsd/gsd/${ver}/`))
+      );
+    } catch { activeVersions = new Set(); }
 
     const toRemove = sorted.slice(0, sorted.length - keepCount);
     for (const ver of toRemove) {
+      if (activeVersions.has(ver)) {
+        if (verbose) console.log(`  Skipped ${ver} (active process detected)`);
+        continue;
+      }
       const verPath = path.join(cacheBase, ver);
       fs.rmSync(verPath, { recursive: true, force: true });
       if (verbose) console.log(`  Pruned old cache: ${ver}`);

package/hooks/gsd-context-monitor.cjs

@@ -112,7 +112,7 @@ process.stdin.on('end', () => {
     if (isCritical) {
       message = `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. `
         + 'Context is nearly exhausted. Complete current task checkpoint immediately, '
-        + 'set workflow_mode = awaiting_clear via gsd-state-update, and tell user to /clear then /gsd:resume.';
+        + 'set workflow_mode = awaiting_clear via state-update, and tell user to /clear then /gsd:resume.';
     } else {
       message = `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. `
         + 'Context is getting limited. Avoid starting new complex work. Complete current task then save state.';

package/hooks/lib/gsd-finder.cjs

@@ -9,26 +9,42 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const _findCache = new Map();
+
 /**
  * Walk from startDir up to filesystem root looking for a .gsd directory
  * that contains state.json. Returns the absolute path to .gsd or null.
+ * Results are cached per startDir (positive hits only — null is not cached
+ * so that a later-created .gsd directory can be discovered).
  */
 function findGsdDir(startDir) {
+  if (_findCache.has(startDir)) return _findCache.get(startDir);
+
   let dir = startDir;
   while (true) {
     const candidate = path.join(dir, '.gsd');
     try {
       if (fs.statSync(candidate).isDirectory()) {
         // Only return if state.json exists (not just an empty .gsd dir)
-        if (fs.existsSync(path.join(candidate, 'state.json'))) return candidate;
+        if (fs.existsSync(path.join(candidate, 'state.json'))) {
+          _findCache.set(startDir, candidate);
+          return candidate;
+        }
       }
     } catch { /* skip */ }
     const parent = path.dirname(dir);
-    if (parent === dir) return null;
+    if (parent === dir) return null; // Don't cache negative results
     dir = parent;
   }
 }
 
+/**
+ * Clear the findGsdDir result cache. Useful for testing.
+ */
+function clearFindGsdDirCache() {
+  _findCache.clear();
+}
+
 /**
  * Read and parse .gsd/state.json. Returns parsed object or null on any failure.
  */
@@ -81,4 +97,4 @@ function getProgress(state) {
   };
 }
 
-module.exports = { findGsdDir, readState, getProgress };
+module.exports = { findGsdDir, clearFindGsdDirCache, readState, getProgress };

package/hooks/lib/semver-sort.cjs

@@ -0,0 +1,20 @@
+// Shared semver sort comparator for use by install.js and gsd-auto-update.cjs
+'use strict';
+
+/**
+ * Compare two semver version strings (e.g. "1.2.3") for sorting.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function semverSortComparator(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
+}
+
+module.exports = { semverSortComparator };

package/install.js

@@ -6,8 +6,11 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const _require = createRequire(import.meta.url);
+const { semverSortComparator } = _require('./hooks/lib/semver-sort.cjs');
 const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
 const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd');
 const DRY_RUN = process.argv.includes('--dry-run');
@@ -116,8 +119,23 @@ export function main() {
   }
 
   // Reset managed runtime directory to avoid stale files on reinstall
+  // Preserve runtime/ subdirectory (update-state.json, update-notification.json)
   if (!DRY_RUN && existsSync(RUNTIME_DIR)) {
+    const runtimeSubdir = join(RUNTIME_DIR, 'runtime');
+    const preserveRuntime = existsSync(runtimeSubdir);
+    let runtimeBackup;
+    if (preserveRuntime) {
+      runtimeBackup = join(RUNTIME_DIR, '..', '.gsd-runtime-backup');
+      try { cpSync(runtimeSubdir, runtimeBackup, { recursive: true }); } catch { runtimeBackup = null; }
+    }
     rmSync(RUNTIME_DIR, { recursive: true, force: true });
+    if (runtimeBackup) {
+      try {
+        mkdirSync(join(RUNTIME_DIR, 'runtime'), { recursive: true });
+        cpSync(runtimeBackup, join(RUNTIME_DIR, 'runtime'), { recursive: true });
+        rmSync(runtimeBackup, { recursive: true, force: true });
+      } catch { /* best effort */ }
+    }
   }
 
   // 1. Commands
@@ -242,19 +260,22 @@ export function main() {
         const entries = readdirSync(cacheBase, { withFileTypes: true })
           .filter(e => e.isDirectory()).map(e => e.name);
         if (entries.length > 3) {
-          const sorted = entries.slice().sort((a, b) => {
-            const pa = a.split('.').map(Number);
-            const pb = b.split('.').map(Number);
-            for (let i = 0; i < 3; i++) {
-              if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
-            }
-            return 0;
-          });
+          const sorted = entries.slice().sort(semverSortComparator);
+          // Detect versions with active processes to avoid disrupting running sessions
+          let activeVersions;
+          try {
+            const psOut = execSync('ps aux', { stdio: 'pipe', timeout: 5000 }).toString();
+            activeVersions = new Set(entries.filter(v => psOut.includes(`/cache/gsd/gsd/${v}/`)));
+          } catch { activeVersions = new Set(); }
+
           const toRemove = sorted.slice(0, sorted.length - 3);
+          let pruned = 0;
           for (const ver of toRemove) {
+            if (activeVersions.has(ver)) continue; // skip versions with running processes
             rmSync(join(cacheBase, ver), { recursive: true, force: true });
+            pruned++;
           }
-          log(`  ✓ Pruned ${toRemove.length} old cache version(s), kept latest 3`);
+          if (pruned > 0) log(`  ✓ Pruned ${pruned} old cache version(s), kept latest 3`);
         }
       } catch { /* best effort */ }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-lite",
-  "version": "0.5.15",
+  "version": "0.6.1",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {

package/references/execution-loop.md

@@ -81,7 +81,7 @@ executor 上下文传递协议 (orchestrator → executor):
 **审查级别运行时重分类:**
 - executor 报告 `contract_changed: true` + 涉及 auth/payment/public API → 自动升级为 L2
 - executor 标注 `[LEVEL-UP]` → 编排器采纳
-- 不主动降级 (安全优先)
+- 不主动降级 (安全优先)，L1 + high confidence + 有 evidence 且无测试失败 → L0 例外
 
 ### 11.6 — 处理 reviewer 结果
 

package/references/review-classification.md

@@ -7,7 +7,7 @@
 | L0 | 无运行时语义变化 (docs/config/style) | checkpoint 后直接 accepted |
 | L1 | 普通编码任务 (默认) | phase 结束后批量审查 |
 | L2 | 高风险 (auth/payment/public API/DB migration) | checkpoint 后立即独立审查 |
-| L3 | 最高风险 (复杂架构/关键系统) | 与 L2 相同: checkpoint 后立即独立审查 |
+| L3 | 最高风险 (auth/payment/security architecture) | checkpoint 后立即独立审查 + 人工确认 |
 
 ## 运行时重分类
 
@@ -21,7 +21,10 @@
 /\b(auth|payment|security|public.?api|login|token|credential|session|oauth)\b/i
 ```
 
-规则: 只升不降 (安全优先)。当前级别为 L2 或 L3 时直接保持不变。
+规则: L2/L3 只升不降。L1 在满足条件时可降为 L0:
+- `confidence: 'high'` + `contract_changed: false`
+- 有 evidence 且无测试失败
+- 此时自审即可，无需独立审查
 
 ## 决策树
 
@@ -31,6 +34,7 @@ task.level 当前值?
 └── L0 或 L1
     ├── executor decisions 含 [LEVEL-UP]? -> 升级为 L2
     ├── contract_changed: true + task.name 匹配敏感关键词? -> 升级为 L2
+    ├── L1 + confidence: 'high' + !contract_changed + 有 evidence 且无测试失败? -> 降为 L0
     └── 否 -> 保持当前级别
 ```
 
@@ -63,15 +67,30 @@ executor checkpointed
   -> 批量审查所有 checkpointed task (排除 L0)
 ```
 
-### L2/L3 流程
+### L2 流程
 
 ```
 executor checkpointed
-  -> handleExecutorResult 检测 (reviewLevel === 'L2' || reviewLevel === 'L3') && review_required !== false
+  -> handleExecutorResult 检测 reviewLevel === 'L2' && review_required !== false
   -> 设置 current_review = { scope: 'task', scope_id: task.id, stage: 'spec' }
   -> workflow_mode = 'reviewing_task'
-  -> 派发 reviewer (scope='task', review_level='L2' 或 'L3')
-  -> 审查通过后才释放下游依赖
+  -> 派发 reviewer (scope='task', review_level='L2')
+  -> 审查通过后 → accepted，释放下游依赖
+```
+
+### L3 流程
+
+```
+executor checkpointed
+  -> handleExecutorResult 检测 reviewLevel === 'L3' && review_required !== false
+  -> 设置 current_review = { scope: 'task', scope_id: task.id, stage: 'spec' }
+  -> workflow_mode = 'reviewing_task'
+  -> 派发 reviewer (scope='task', review_level='L3')
+  -> reviewer 返回 requires_human_confirmation: true + security_implications
+  -> 审查通过后 → task 进入 awaiting_user (非 accepted)
+  -> 编排器向用户展示审查摘要 + 安全影响
+  -> 用户显式确认 → accepted，释放下游依赖
+  -> 用户拒绝 → 返工
 ```
 
 ## Reviewer 结果处理

package/references/state-diagram.md

@@ -62,7 +62,7 @@ stateDiagram-v2
 | `reviewing` | `accepted`, `active` |
 | `accepted` | *(终态，无后续转换)* |
 | `blocked` | `active` |
-| `failed` | *(终态，无后续转换)* |
+| `failed` | `active` (H-3: 用户显式恢复) |
 
 ### Mermaid 图
 
@@ -81,15 +81,16 @@ stateDiagram-v2
 
     blocked --> active : 阻塞解除
 
+    failed --> active : H-3 用户显式恢复 (resume 提供 retry/skip/replan)
+
     accepted --> [*]
-    failed --> [*]
 ```
 
 ### 关键路径说明
 
 - **正常路径**: `pending -> active -> reviewing -> accepted`
 - **返工路径**: `active -> reviewing -> active -> reviewing -> accepted` (最多循环)
-- **失败路径**: `active -> failed` (终态，不可恢复)
+- **失败路径**: `active -> failed -> active` (H-3: 可通过 resume 恢复)
 - **Phase 推进**: 当前 phase `accepted` 后，下一个 `pending` phase 自动转为 `active`
 
 来源: `PHASE_LIFECYCLE` in `src/schema.js`