gsd-lite 0.6.7 → 0.6.8

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.6.7",
+      "version": "0.6.8",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

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

package/agents/executor.md

@@ -56,6 +56,7 @@ tools: Read, Write, Edit, Bash, Grep, Glob
   "blockers": [],
   "contract_changed": true,
   "confidence": "high",
+  "error_fingerprint": "optional string — short fingerprint for 3-strike deduplication (file+line or msg[:50])",
   "evidence": [
     {"id": "ev:test:users-update", "scope": "task:2.3"},
     {"id": "ev:typecheck:phase-2", "scope": "task:2.3"}

package/agents/researcher.md

@@ -68,7 +68,30 @@ tools: Read, Write, Bash, WebSearch, WebFetch, mcp__plugin_context7_context7__*
 ## 遇到不确定性时
 子代理不能直接与用户交互。遇到不确定性时:
 1. 来源冲突 → 报告双方立场及置信度，让编排器决定。在 result 中标注 "[DECISION] 选择了X因为Y"
-2. 所有来源不可用 (Context7 + WebSearch + 官方文档均失败) → 返回 "[BLOCKED] 需要: 研究来源不可用，请提供替代信息或缩小范围"
-3. 研究范围过广无法收敛 → 返回 "[BLOCKED] 需要: 研究范围过广，请指定重点领域"
+2. 所有来源不可用 (Context7 + WebSearch + 官方文档均失败) → 仍然返回有效的 result contract JSON (编排器需要通过 `validateResearcherResult` 校验)，在 decision 摘要中标注阻塞原因:
+   ```json
+   {
+     "result": {
+       "decision_ids": ["decision:blocked-no-sources"],
+       "volatility": "high",
+       "expires_at": "<24h后的ISO时间>",
+       "sources": []
+     },
+     "decision_index": {
+       "decision:blocked-no-sources": {
+         "summary": "[BLOCKED] 研究来源不可用，请提供替代信息或缩小范围",
+         "source": "none",
+         "expires_at": "<24h后的ISO时间>"
+       }
+     },
+     "artifacts": {
+       "STACK.md": "# 研究受阻\n来源不可用，无法完成研究。",
+       "ARCHITECTURE.md": "# 研究受阻\n来源不可用。",
+       "PITFALLS.md": "# 研究受阻\n来源不可用。",
+       "SUMMARY.md": "# 研究受阻\n所有来源 (Context7/WebSearch/官方文档) 均不可用。需要用户提供替代信息或缩小范围。"
+     }
+   }
+   ```
+3. 研究范围过广无法收敛 → 同上模式，decision 摘要改为 "[BLOCKED] 研究范围过广，请指定重点领域"
 4. 发现结论与已有 decisions 矛盾 → 在 result 中标注冲突，让编排器决定是否更新 decision
 </uncertainty_handling>

package/commands/doctor.md

@@ -44,7 +44,7 @@ Also verify the hook files exist on disk:
 
 ## STEP 4: Lock File Check
 
-Check if `.gsd/.state-lock` exists:
+Check if `.gsd/state.lock` exists:
 - If not exists: record PASS "No stale lock"
 - If exists: check file age
   - Older than 5 minutes: record WARN "Stale lock file detected (age: {age}). May indicate a crashed process. Consider removing it."

package/commands/resume.md

@@ -51,16 +51,16 @@ description: Resume project execution from saved state with workspace validation
    - 如果当前或任何未完成 phase 的 `phase_handoff.direction_ok === false`
    - → 覆写 `workflow_mode = awaiting_user`
 
-4. **研究过期校验:**
+4. **Dirty-phase 回滚检测:**
+   - 检查 `current_phase` 之前的 phase (`p.id < current_phase`) 中是否有 `needs_revalidation` 状态的 task
+   - 如有 → 回滚 `current_phase` 到最早的 dirty phase
+   - → 覆写 `workflow_mode = executing_task`
+
+5. **研究过期校验:**
    - 如果 `research.expires_at` 已过期 (早于当前时间)
    - 或 research.decision_index 中有条目的 expires_at 已过期
    - → 覆写 `workflow_mode = research_refresh_needed`
 
-5. **Dirty-phase 回滚检测:**
-   - 检查已完成 phase 中是否有 `needs_revalidation` 状态的 task
-   - 如有 → 回滚 `current_phase` 到最早的 dirty phase
-   - → 覆写 `workflow_mode = executing_task`
-
 6. **全部通过:**
    - 保持原 `workflow_mode` 不变
 

package/commands/stop.md

@@ -27,6 +27,8 @@ description: Save current state and pause project execution
 
 将 `workflow_mode` 设置为 `paused_by_user`
 
+使用 `state-update` MCP 工具更新状态，确保通过 schema 校验和乐观锁。
+
 使用原子写入: 先写 `.gsd/state.json.tmp`，成功后 rename 为 `.gsd/state.json`
 
 ## STEP 3: 确认输出

package/hooks/gsd-auto-update.cjs

@@ -324,12 +324,37 @@ function validateExtractedPackage(extractDir) {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     if (pkg.name !== 'gsd-lite') return false;
     if (!pkg.version || !/^\d+\.\d+\.\d+/.test(pkg.version)) return false;
+    // Verify install.js exists and is a regular file (lstat rejects symlinks)
+    const installPath = path.join(extractDir, 'install.js');
+    const lstat = fs.lstatSync(installPath);
+    if (!lstat.isFile()) return false;
     return true;
   } catch {
     return false;
   }
 }
 
+// ── Tarball URL Validation ─────────────────────────────────
+const ALLOWED_TARBALL_HOSTS = [
+  'github.com',
+  'api.github.com',
+  'codeload.github.com',
+  'objects.githubusercontent.com',
+];
+
+function validateTarballUrl(url) {
+  if (!url) return false;
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:') return false;
+    return ALLOWED_TARBALL_HOSTS.some(
+      allowed => parsed.hostname === allowed || parsed.hostname.endsWith('.' + allowed),
+    );
+  } catch {
+    return false;
+  }
+}
+
 // ── Download & Install ─────────────────────────────────────
 async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
   const tmpDir = path.join(os.tmpdir(), `gsd-update-${Date.now()}`);
@@ -340,6 +365,9 @@ async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
 
     // Download tarball via fetch (no shell interpolation)
     if (verbose) console.log('  Downloading tarball...');
+    if (!validateTarballUrl(tarballUrl)) {
+      throw new Error(`Tarball URL failed host validation: ${(() => { try { return new URL(tarballUrl).hostname; } catch { return tarballUrl; } })()}`);
+    }
     const headers = { Accept: 'application/vnd.github+json', 'User-Agent': 'gsd-lite-auto-update/1.0' };
     if (token) headers.Authorization = `Bearer ${token}`;
 
@@ -347,7 +375,26 @@ async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
     const dlTimeout = setTimeout(() => controller.abort(), 30000);
     let tarData;
     try {
-      const res = await fetch(tarballUrl, { signal: controller.signal, headers, redirect: 'follow' });
+      let res = await fetch(tarballUrl, { signal: controller.signal, headers, redirect: 'manual' });
+      // Handle redirect manually to prevent Authorization header leakage
+      if (res.status === 301 || res.status === 302) {
+        const location = res.headers.get('location');
+        if (!location || !validateTarballUrl(location)) {
+          throw new Error(`Redirect URL failed host validation: ${location || '(empty)'}`);
+        }
+        // Follow redirect WITHOUT Authorization header (prevent token leakage to CDN)
+        // Use redirect: 'manual' to validate any further redirects in the chain
+        const redirectHeaders = { Accept: 'application/vnd.github+json', 'User-Agent': 'gsd-lite-auto-update/1.0' };
+        res = await fetch(location, { signal: controller.signal, headers: redirectHeaders, redirect: 'manual' });
+        // Handle one more potential redirect from CDN (e.g., 303/307/308)
+        if (res.status >= 300 && res.status < 400) {
+          const loc2 = res.headers.get('location');
+          if (!loc2 || !validateTarballUrl(loc2)) {
+            throw new Error(`Secondary redirect URL failed host validation: ${loc2 || '(empty)'}`);
+          }
+          res = await fetch(loc2, { signal: controller.signal, headers: redirectHeaders, redirect: 'error' });
+        }
+      }
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       tarData = Buffer.from(await res.arrayBuffer());
     } finally {
@@ -452,7 +499,7 @@ function pruneOldCacheVersions(cacheBase, keepCount = 3, verbose = false) {
   try {
     if (!fs.existsSync(cacheBase)) return;
     const entries = fs.readdirSync(cacheBase, { withFileTypes: true })
-      .filter(e => e.isDirectory())
+      .filter(e => e.isDirectory() && /^\d+\.\d+\.\d+$/.test(e.name))
       .map(e => e.name);
     if (entries.length <= keepCount) return;
 
@@ -581,6 +628,7 @@ module.exports = {
   shouldCheck,
   shouldSkipUpdateCheck,
   validateExtractedPackage,
+  validateTarballUrl,
 };
 
 // ── CLI Entry Point (for background auto-install) ─────────

package/hooks/gsd-session-init.cjs

@@ -53,11 +53,20 @@ setTimeout(() => process.exit(0), 4000).unref();
     const stableStatuslinePath = path.join(claudeDir, 'hooks', 'gsd-statusline.cjs');
     if (fs.existsSync(stableStatuslinePath)) {
       let settings = {};
+      let settingsParseError = false;
       try {
         settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-      } catch { /* Can't read settings — skip registration */ }
+      } catch (e) {
+        if (e.code === 'ENOENT') {
+          settings = {}; // File doesn't exist — create fresh
+        } else {
+          // Parse error or other — skip write to avoid overwriting corrupted file
+          if (process.env.GSD_DEBUG) console.error('[gsd-session-init] settings.json read error:', e.message);
+          settingsParseError = true;
+        }
+      }
 
-      if (settings) {
+      if (!settingsParseError && settings) {
         const current = settings.statusLine?.command || '';
 
         if (current.includes('gsd-statusline')) {
@@ -120,12 +129,13 @@ setTimeout(() => process.exit(0), 4000).unref();
     const notifPath = path.join(claudeDir, 'gsd', 'runtime', 'update-notification.json');
     if (fs.existsSync(notifPath)) {
       const notif = JSON.parse(fs.readFileSync(notifPath, 'utf8'));
+      const safeSemver = (s) => /^\d+\.\d+\.\d+/.test(String(s || '')) ? String(s) : '?.?.?';
       if (notif.kind === 'updated') {
-        console.log(`✅ GSD-Lite auto-updated: v${notif.from} → v${notif.to}`);
+        console.log(`✅ GSD-Lite auto-updated: v${safeSemver(notif.from)} → v${safeSemver(notif.to)}`);
       } else if (notif.kind === 'available' && notif.action === 'plugin_update') {
-        console.log(`📦 GSD-Lite update available: v${notif.from} → v${notif.to}. Run /plugin update gsd`);
+        console.log(`📦 GSD-Lite update available: v${safeSemver(notif.from)} → v${safeSemver(notif.to)}. Run /plugin update gsd`);
       } else if (notif.kind === 'available') {
-        console.log(`📦 GSD-Lite update available: v${notif.from} → v${notif.to}. Run gsd update`);
+        console.log(`📦 GSD-Lite update available: v${safeSemver(notif.from)} → v${safeSemver(notif.to)}. Run gsd update`);
       }
       fs.unlinkSync(notifPath);
     }
@@ -163,11 +173,14 @@ setTimeout(() => process.exit(0), 4000).unref();
           }
         } catch { /* skip */ }
 
+        // Sanitize user-controlled strings to prevent HTML/markdown injection
+        const safeName = (s) => String(s || '').replace(/<!--|-->/g, '').slice(0, 200);
+
         // Stdout: only output session-end warning (crash recovery), skip routine progress
         // Routine progress is handled by CLAUDE.md injection below — avoids noise
         const shortHead = progress.gitHead ? progress.gitHead.substring(0, 7) : 'n/a';
         if (sessionEndInfo) {
-          console.log(`⚠️ GSD: Previous session ended unexpectedly at ${sessionEndInfo.ended_at} (was: ${sessionEndInfo.workflow_mode_was}). Run /gsd:resume to recover.`);
+          console.log(`⚠️ GSD: Previous session ended unexpectedly at ${sessionEndInfo.ended_at} (was: ${safeName(sessionEndInfo.workflow_mode_was)}). Run /gsd:resume to recover.`);
         }
 
         // Write status block to CLAUDE.md
@@ -178,13 +191,13 @@ setTimeout(() => process.exit(0), 4000).unref();
 
         const statusBlock = [
           BEGIN_MARKER,
-          `### GSD Project: ${progress.project}`,
-          `- Phase: ${progress.currentPhase || '?'}/${progress.totalPhases} (${progress.phaseName})`,
-          `- Task: ${progress.currentTask || 'none'}${progress.taskName ? ` (${progress.taskName})` : ''}`,
-          `- Mode: ${progress.workflowMode}`,
+          `### GSD Project: ${safeName(progress.project)}`,
+          `- Phase: ${progress.currentPhase || '?'}/${progress.totalPhases} (${safeName(progress.phaseName)})`,
+          `- Task: ${progress.currentTask || 'none'}${progress.taskName ? ` (${safeName(progress.taskName)})` : ''}`,
+          `- Mode: ${safeName(progress.workflowMode)}`,
           `- Progress: ${progress.acceptedTasks}/${progress.totalTasks} tasks done`,
-          `- Last checkpoint: ${shortHead}`,
-          sessionEndInfo ? `- ⚠️ Previous session ended unexpectedly (${sessionEndInfo.ended_at})` : null,
+          `- Last checkpoint: ${safeName(shortHead)}`,
+          sessionEndInfo ? `- ⚠️ Previous session ended unexpectedly (${safeName(sessionEndInfo.ended_at)})` : null,
           END_MARKER,
         ].filter(Boolean).join('\n');
 

package/hooks/lib/semver-sort.cjs

@@ -9,10 +9,10 @@
  * @returns {number}
  */
 function semverSortComparator(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
+  const pa = a.split('.').map(s => parseInt(s, 10) || 0);
+  const pb = b.split('.').map(s => parseInt(s, 10) || 0);
   for (let i = 0; i < 3; i++) {
-    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
   }
   return 0;
 }

package/install.js

@@ -264,7 +264,7 @@ export function main() {
     if (existsSync(cacheBase)) {
       try {
         const entries = readdirSync(cacheBase, { withFileTypes: true })
-          .filter(e => e.isDirectory()).map(e => e.name);
+          .filter(e => e.isDirectory() && /^\d+\.\d+\.\d+$/.test(e.name)).map(e => e.name);
         if (entries.length > 3) {
           const sorted = entries.slice().sort(semverSortComparator);
           // Detect versions with active processes to avoid disrupting running sessions

package/package.json

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

package/references/execution-loop.md

@@ -33,8 +33,10 @@ executor 上下文传递协议 (orchestrator → executor):
 ├── research_decisions:  从 research_basis 引用的 decision 摘要
 ├── predecessor_outputs: 前置依赖 task 的 files_changed + checkpoint_commit
 ├── project_conventions: CLAUDE.md 路径 (executor 自行读取)
-├── workflows:           需加载的工作流文件路径 (如 tdd-cycle.md)
-└── constraints:         retry_count / level / review_required
+├── workflows:           需加载的工作流文件路径 (如 tdd-cycle.md, deviation-rules.md; retry 时追加 debugging.md; 有 research_basis 时追加 research.md)
+├── constraints:         retry_count / level / review_required
+├── debugger_guidance:   debugger 分析结果 (root_cause / fix_direction / fix_attempts / evidence)，仅在 debug_context 存在时提供，否则 null
+└── rework_feedback:     reviewer 返工反馈 (issue 描述数组)，仅在 last_review_feedback 存在时提供，否则 null
 ```
 
 派发 `executor` 子代理执行单个 task。
@@ -146,6 +148,8 @@ remaining <= 25%:
   4. 立即停止
 ```
 
+> **Note:** 上述 35%/25% 阈值为编排器主动发起上下文保存的建议阈值。Resume 时的恢复阻断阈值为 `CONTEXT_RESUME_THRESHOLD = 40`（服务端强制校验），低于 40% 时 resume 会拒绝恢复并要求 /clear。
+
 ---
 
 ## 依赖门槛语义 (Gate-aware dependencies)

package/references/state-diagram.md

@@ -7,7 +7,7 @@
 | 当前状态 | 允许的目标状态 |
 |----------|---------------|
 | `pending` | `running`, `blocked` |
-| `running` | `checkpointed`, `blocked`, `failed` |
+| `running` | `checkpointed`, `blocked`, `failed`, `accepted` |
 | `checkpointed` | `accepted`, `needs_revalidation` |
 | `accepted` | `needs_revalidation` |
 | `blocked` | `pending` |
@@ -24,6 +24,7 @@ stateDiagram-v2
     pending --> blocked : executor 报告阻塞
 
     running --> checkpointed : executor 完成 checkpoint
+    running --> accepted : L0/review_required=false 自动接受 (跳过 checkpointed)
     running --> blocked : executor 运行时阻塞
     running --> failed : executor 执行失败
 
@@ -172,8 +173,11 @@ stateDiagram-v2
     executing_task --> failed : debugger 报告架构问题
 
     reviewing_task --> executing_task : 审查完成 (通过或返工)
-    reviewing_phase --> executing_task : 审查返工 (有 critical)
-    reviewing_phase --> completed : 最终 phase 审查通过
+    reviewing_phase --> executing_task : 审查完成 (通过或返工，reviewer 始终返回 executing_task)
+    reviewing_phase --> completed : 最终 phase 审查通过 (schema 允许)
+
+    note right of executing_task : 最终 phase 审查通过后，\nresume 返回 complete_phase action，\nLLM 调用 phase-complete 设置 completed
+    executing_task --> completed : phase-complete (最终 phase)
 
     awaiting_clear --> executing_task : /clear + /resume 后恢复
     awaiting_user --> executing_task : 用户解除阻塞 / 自动匹配 decision
@@ -182,14 +186,18 @@ stateDiagram-v2
     executing_task --> preflight_overrides : resume 时 preflight 检测
     preflight_overrides --> reconcile_workspace : git HEAD 不匹配
     preflight_overrides --> replan_required : 计划文件被修改
-    preflight_overrides --> research_refresh_needed : 研究缓存过期
     preflight_overrides --> awaiting_user : 方向漂移检测
+    preflight_overrides --> executing_task : dirty-phase 回滚 (rollback_to_dirty_phase)
+    preflight_overrides --> research_refresh_needed : 研究缓存过期
 
     research_refresh_needed --> executing_task : 研究刷新完成
     research_refresh_needed --> reviewing_task : 刷新后恢复审查状态
     research_refresh_needed --> reviewing_phase : 刷新后恢复审查状态
 
     paused_by_user --> executing_task : 用户恢复
+    paused_by_user --> research_refresh_needed : resume 时研究过期
+    paused_by_user --> reviewing_task : resume 恢复审查状态
+    paused_by_user --> reviewing_phase : resume 恢复审查状态
 
     completed --> [*]
     failed --> [*]
@@ -198,7 +206,8 @@ stateDiagram-v2
 ### 关键转换说明
 
 **执行主路径**:
-`planning -> executing_task -> reviewing_phase -> executing_task (next phase) -> ... -> completed`
+`planning -> executing_task -> reviewing_phase -> executing_task -> complete_phase -> executing_task (next phase) -> ... -> executing_task -> phase-complete -> completed`
+注: `reviewing_phase` 审查通过后始终先回到 `executing_task`，再由 resume 返回 `complete_phase` action，LLM 调用 `phase-complete` MCP tool 推进。最终 phase 的 `phase-complete` 调用会直接设置 `workflow_mode = 'completed'`。
 
 **L2 审查分支**:
 `executing_task -> reviewing_task -> executing_task`
@@ -211,7 +220,8 @@ stateDiagram-v2
 1. git HEAD 不匹配 -> `reconcile_workspace`
 2. 计划文件被外部修改 -> `replan_required`
 3. 方向漂移 -> `awaiting_user`
-4. 研究缓存过期 -> `research_refresh_needed`
+4. `current_phase` 之前的 phase 有 `needs_revalidation` task -> `rollback_to_dirty_phase`
+5. 研究缓存过期 -> `research_refresh_needed`
 
 **Research 刷新后恢复**:
 `storeResearch()` 中: 如果 `workflow_mode === 'research_refresh_needed'`，调用 `inferWorkflowModeAfterResearch()` 根据 `current_review` 状态推断恢复到 `reviewing_phase` / `reviewing_task` / `executing_task`。

package/src/schema.js

@@ -602,7 +602,7 @@ export function validateReviewerResult(r) {
   if (!(typeof r.scope_id === 'string' || typeof r.scope_id === 'number') || r.scope_id === '' || r.scope_id === 0) {
     errors.push('missing or invalid scope_id');
   }
-  if (!['L2', 'L1-batch', 'L1'].includes(r.review_level)) errors.push('invalid review_level (expected L2, L1-batch, or L1)');
+  if (!['L3', 'L2', 'L1-batch', 'L1'].includes(r.review_level)) errors.push('invalid review_level (expected L3, L2, L1-batch, or L1)');
   if (typeof r.spec_passed !== 'boolean') errors.push('spec_passed must be boolean');
   if (typeof r.quality_passed !== 'boolean') errors.push('quality_passed must be boolean');
   if (!Array.isArray(r.critical_issues)) errors.push('critical_issues must be array');

package/src/server.js

@@ -375,7 +375,7 @@ export async function main() {
 process.on('SIGINT', () => process.exit(0));
 process.on('SIGTERM', () => process.exit(0));
 process.on('unhandledRejection', (err) => {
-  if (process.env.GSD_DEBUG) console.error('[gsd] unhandledRejection', err);
+  process.stderr.write(`[gsd] unhandledRejection: ${err?.stack || err}\n`);
 });
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/src/tools/orchestrator/helpers.js

@@ -32,7 +32,7 @@ const RESULT_CONTRACTS = {
   reviewer: {
     scope: '"task" | "phase"',
     scope_id: 'string | number — task id (e.g. "1.2") or phase number',
-    review_level: '"L2" | "L1-batch" | "L1"',
+    review_level: '"L3" | "L2" | "L1-batch" | "L1"',
     spec_passed: 'boolean',
     quality_passed: 'boolean',
     critical_issues: '{ reason|description, task_id?, invalidates_downstream? }[] — blocking issues',
@@ -361,7 +361,7 @@ function buildErrorFingerprint(result) {
     parts.push([...result.files_changed].sort().join(','));
   }
   const combined = parts.filter(Boolean).join('|');
-  return combined.length > 0 ? combined.slice(0, 120) : result.summary.slice(0, 80);
+  return combined.length > 0 ? combined.slice(0, 120) : (result.summary || '').slice(0, 80);
 }
 
 function getBlockedReasonFromResult(result) {
@@ -376,8 +376,8 @@ function getBlockedReasonFromResult(result) {
   };
 }
 
-async function persist(basePath, updates, { _append_decisions, _propagation_tasks } = {}) {
-  const result = await update({ updates, basePath, _append_decisions, _propagation_tasks });
+async function persist(basePath, updates, { _append_decisions, _propagation_tasks, expectedVersion } = {}) {
+  const result = await update({ updates, basePath, expectedVersion, _append_decisions, _propagation_tasks });
   if (result.error) {
     return result;
   }
@@ -385,8 +385,8 @@ async function persist(basePath, updates, { _append_decisions, _propagation_task
 }
 
 // persist variant that returns merged state from update(), avoiding re-reads
-async function persistAndRead(basePath, updates, { _append_decisions, _propagation_tasks } = {}) {
-  const result = await update({ updates, basePath, _append_decisions, _propagation_tasks });
+async function persistAndRead(basePath, updates, { _append_decisions, _propagation_tasks, expectedVersion } = {}) {
+  const result = await update({ updates, basePath, expectedVersion, _append_decisions, _propagation_tasks });
   if (result.error) {
     return { error: true, ...result };
   }

package/src/tools/state/constants.js

@@ -34,7 +34,7 @@ export function setLockPath(lockPath) {
  * Must be called before withStateLock in all mutation paths.
  */
 export function ensureLockPathFromStatePath(statePath) {
-  if (!_fileLockPath && statePath) {
+  if (statePath) {
     _fileLockPath = join(dirname(statePath), 'state.lock');
   }
 }
@@ -44,6 +44,7 @@ export function withStateLock(fn) {
     if (_fileLockPath) {
       return withFileLock(_fileLockPath, fn);
     }
+    process.stderr.write('[gsd] WARNING: withStateLock called without lock path — cross-process safety not guaranteed\n');
     return fn();
   });
   _mutationQueue = p.catch(() => {});

package/src/tools/state/crud.js

@@ -606,8 +606,8 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
   if (!data || typeof data !== 'object' || Array.isArray(data)) {
     return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'data must be a non-null object' };
   }
-  if (typeof data.scope !== 'string') {
-    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'data.scope must be a string' };
+  if (typeof data.scope !== 'string' || data.scope.length === 0) {
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'data.scope must be a non-empty string' };
   }
 
   const statePath = await getStatePath(basePath);
@@ -906,7 +906,8 @@ function _applyPatchOp(state, op) {
     }
 
     case 'update_task': {
-      const { task_id, task: taskObj, ...fields } = op;
+      // Destructure envelope keys explicitly so they don't leak into fields
+      const { task_id, task: taskObj, op: _op, phase_id: _pid, ...fields } = op;
       if (typeof task_id !== 'string') return { error: true, message: 'task_id must be a string' };
 
       const phase = state.phases.find(p => p.todo?.some(t => t.id === task_id));

package/src/tools/state/logic.js

@@ -1,6 +1,7 @@
 // Automation/business logic functions
 
 import { dirname, join } from 'node:path';
+import { writeFileSync, unlinkSync } from 'node:fs';
 import { writeFile, rename, unlink } from 'node:fs/promises';
 import { ensureDir, readJson, writeJson, getStatePath } from '../../utils.js';
 import {
@@ -445,6 +446,12 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     const researchDir = join(gsdDir, 'research');
     await ensureDir(researchDir);
 
+    // Crash-consistency sentinel: marks the window between artifact renames and
+    // state.json write. On recovery (future iteration), presence of this file
+    // indicates a potentially inconsistent research state.
+    const sentinelPath = join(gsdDir, '.research-commit-pending');
+    writeFileSync(sentinelPath, JSON.stringify({ timestamp: Date.now(), pid: process.pid }));
+
     // Atomic multi-file write: write all artifacts first, then rename in batch
     const normalizedArtifacts = normalizeResearchArtifacts(artifacts);
     const tmpSuffix = `.${process.pid}-${Date.now()}.tmp`;
@@ -465,6 +472,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
       for (const { tmp } of tmpPaths) {
         try { await unlink(tmp); } catch {}
       }
+      try { unlinkSync(sentinelPath); } catch {}
       throw err;
     }
 
@@ -501,11 +509,16 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
 
     const validation = validateState(state);
     if (!validation.valid) {
+      try { unlinkSync(sentinelPath); } catch {}
       return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `State validation failed: ${validation.errors.join('; ')}` };
     }
 
     state._version = (state._version ?? 0) + 1;
     await writeJson(statePath, state);
+
+    // Remove sentinel after successful state write — crash consistency window closed
+    try { unlinkSync(sentinelPath); } catch {}
+
     return {
       success: true,
       workflow_mode: state.workflow_mode,

package/src/tools/verify.js

@@ -29,12 +29,12 @@ function summarizeOutput(output, lines) {
 
 async function runCommand(command, args, cwd) {
   try {
-    const { stdout } = await execFile(command, args, {
+    const { stdout, stderr } = await execFile(command, args, {
       cwd,
       encoding: 'utf-8',
       timeout: 120000,
     });
-    return { exit_code: 0, summary: summarizeOutput(stdout, 3) };
+    return { exit_code: 0, summary: summarizeOutput(stdout || stderr, 3) };
   } catch (err) {
     return {
       exit_code: err.status ?? (typeof err.code === 'number' ? err.code : 1),

package/workflows/debugging.md

@@ -131,7 +131,7 @@ debugger 由编排器在以下情况派发:
 
 **目标:** 提出根因修复方案 (不是症状)，交由 executor 实施。
 
-> 调试器不直接写代码 — 返回 fix_direction + 测试用例描述，由 executor 实施。
+> 调试器不直接写代码 (无 Write 工具) — 返回 fix_direction + 测试用例描述，由 executor 实施。
 
 ### 步骤 1: 描述回归测试用例
 

package/workflows/execution-flow.md

@@ -131,7 +131,7 @@
 1. 调用 `orchestrator-resume` 获取 action
 2. 按 action 执行对应操作 (见下方 action 处理表)
 3. 操作完成后回到步骤 1
-4. 终止: action ∈ {idle, awaiting_user, completed, failed, await_manual_intervention}
+4. 终止: action ∈ {idle, awaiting_user, noop, phase_failed, task_failed, await_manual_intervention, await_recovery_decision, review_retry_exhausted}
 
 不要在循环中间停下来等用户确认 — 让编排器驱动。
 
@@ -151,6 +151,14 @@
 | `replan_required` | 计划文件被修改。**自动处理:** 确认计划无误后，调用 `state-update({updates: {workflow_mode: "executing_task"}})` → 继续循环 |
 | `reconcile_workspace` | Git HEAD 不一致。检查变更，调用 `state-update({updates: {git_head: "<当前HEAD>", workflow_mode: "executing_task"}})` → 继续循环 |
 | `rollback_to_dirty_phase` | 早期 phase 有失效 task。**自动处理:** 继续循环 (resume 已回滚 current_phase) |
+| `trigger_review` | 所有 task 已 checkpointed，触发 phase review → 继续循环 (resume 会自动 dispatch_reviewer) |
+| `phase_failed` | debugger 报告架构问题，phase 标记 failed。向用户展示失败信息 |
+| `task_failed` | debugger 报告 task 不可修复 (非架构问题)，task 标记 failed。继续循环 (如有其他可运行 task) 或向用户报告 |
+| `review_retry_exhausted` | phase 审查返工次数超限。向用户展示问题，等待用户干预 |
+| `research_stored` | researcher 结果已存储。继续循环 |
+| `awaiting_user` | task 被阻塞或方向漂移，需要用户输入。展示 blockers 列表，等待用户解除 |
+| `await_manual_intervention` | 上下文不足 / 项目暂停 / 计划阶段。根据场景执行: awaiting_clear 时执行 /clear + /resume; paused 时确认恢复; planning 时完成计划并 state-init |
+| `noop` | 工作流已完成 (completed 状态)，无需操作。展示完成信息和 PR 建议 |
 | `idle` | 当前 phase 无可运行 task。检查 task 状态和依赖关系，必要时向用户报告 |
 | `await_recovery_decision` | 工作流处于 failed 状态。向用户展示失败信息和恢复选项 (retry/skip/replan) |
 

package/workflows/research.md

@@ -124,7 +124,7 @@ Decision ID 供 plan/task 的 `research_basis` 字段引用，建立研究→计
 
 ---
 
-## 结果契约 (与 researcher 一致)
+## 结果契约 (与 researcher 一致，完整 3 参数调用契约见 `agents/researcher.md`)
 
 ```json
 {