gsd-lite 0.6.7 → 0.6.9

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.9",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

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

package/README.md

@@ -2,7 +2,7 @@
 
 > Get Shit Done — AI orchestration for Claude Code
 
-GSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It combines structured project management with built-in quality discipline: TDD enforcement, anti-rationalization guards, multi-level code review, and automatic failure recovery — all driven by a state machine that keeps multi-phase projects on track.
+GSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It combines structured project management with built-in quality discipline: TDD enforcement, anti-rationalization guards, multi-level code review, and automatic failure recovery — all driven by a 12-state workflow machine that keeps multi-phase projects on track.
 
 **Discuss thoroughly, execute automatically.** Have as many rounds of requirement discussion as needed. Once the plan is approved, GSD-Lite auto-executes: coding, self-review, independent review, verification, and phase advancement — with minimal human intervention.
 
@@ -10,7 +10,7 @@ GSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.co
 
 ### Structured Execution Engine
 - **Phase-based project management** — Break work into phases with ordered tasks, dependency tracking, and handoff gates
-- **State machine orchestration** — 12 workflow modes with precise state transitions, persistent to `state.json`
+- **12-state workflow machine** — `planning → executing_task → reviewing_task → reviewing_phase → completed` with precise transitions, persistent to `state.json`
 - **Automatic task scheduling** — Gate-aware dependency resolution determines what runs next
 - **Session resilience** — Stop anytime, resume exactly where you left off — crash protection via Stop hook auto-saves state markers
 
@@ -32,13 +32,19 @@ GSD-Lite is an AI orchestration tool for [Claude Code](https://docs.anthropic.co
 - **Parallel task scheduling** — Independent tasks within the same phase are identified for concurrent dispatch
 - **Auto PR suggestion** — Phase/project completion prompts PR creation with evidence summary
 
-### Context Protection
+### Context Protection & Monitoring
 - **Subagent isolation** — Each task runs in its own agent context, preventing cross-contamination
-- **StatusLine monitoring** — Real-time context health tracking via Claude Code StatusLine
+- **Real-time context health monitoring** — StatusLine tracks context usage and project phase; composite StatusLine support coexists with other plugins
 - **Session lifecycle hooks** — Stop hook writes crash marker; SessionStart injects project status into CLAUDE.md; resume detects non-graceful exits
 - **Evidence-based verification** — Every claim backed by command output, not assertions
 - **Research with TTL** — Research artifacts include volatility ratings and expiration dates
 
+### Auto-Update & Version Management
+- **Automatic update checks** — Checks GitHub Releases every 24 hours with rate-limit backoff
+- **Version drift detection** — Server startup compares running version against disk and plugin registry, warns on mismatch
+- **Smart cache management** — Keeps latest 3 cached versions, auto-prunes old entries
+- **Idempotent installer** — Reinstall anytime without uninstalling; legacy files auto-cleaned
+
 ## Architecture
 
 ```
@@ -54,8 +60,8 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 |---------|---------|
 | `/gsd:start` | Interactive start — discuss requirements, research, plan, then auto-execute |
 | `/gsd:prd <input>` | Start from a requirements doc or description text |
-| `/gsd:resume` | Resume execution from saved state |
-| `/gsd:status` | View project progress dashboard |
+| `/gsd:resume` | Resume execution from saved state with workspace validation |
+| `/gsd:status` | View project progress dashboard (derived from canonical state fields) |
 | `/gsd:stop` | Save state and pause execution |
 | `/gsd:doctor` | Diagnostic checks on GSD-Lite installation and project health |
 
@@ -68,6 +74,17 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 | **researcher** | Ecosystem research (Context7 → official docs → web) | Confidence scoring + TTL |
 | **debugger** | 4-phase systematic root cause analysis | Root Cause Iron Law |
 
+### 6 Workflows
+
+| Workflow | Purpose |
+|----------|---------|
+| `tdd-cycle` | RED-GREEN-REFACTOR TDD cycle enforcement |
+| `review-cycle` | Two-level review gates and accept/rework decisions |
+| `debugging` | 4-phase root cause analysis process |
+| `research` | Research with confidence scoring and TTL expiration |
+| `deviation-rules` | Anti-rationalization guards and red-flag checklists |
+| `execution-flow` | Complete task execution cycle from dispatch to checkpoint |
+
 ### MCP Server (11 Tools)
 
 | Tool | Purpose |
@@ -84,6 +101,19 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 | `orchestrator-handle-researcher-result` | Store research artifacts and decisions |
 | `orchestrator-handle-debugger-result` | Process root cause analysis, re-dispatch executor |
 
+### 8 References
+
+| Reference | Content |
+|-----------|---------|
+| `execution-loop` | 9-step execution loop specification (single source of truth) |
+| `review-classification` | Review level classification decision tree (L0/L1/L2) |
+| `evidence-spec` | Evidence validation and citation rules |
+| `state-diagram` | 12-state lifecycle workflow machine diagram |
+| `testing-patterns` | Test structure and patterns |
+| `anti-rationalization-full` | Full red-flag checklist for agents |
+| `git-worktrees` | Git worktree isolation strategy |
+| `questioning` | Requirements clarification patterns |
+
 ## Installation
 
 ### Method 1: Claude Code Plugin (Recommended)
@@ -96,7 +126,7 @@ User → discuss + research (confirm requirements) → approve plan → auto-exe
 /plugin install gsd
 ```
 
-Automatically registers all commands, agents, workflows, MCP server, and hooks. Run these commands inside a Claude Code session.
+Automatically registers all commands, agents, workflows, MCP server, hooks, and auto-update. Run these commands inside a Claude Code session.
 
 ### Method 2: npx
 
@@ -113,12 +143,14 @@ cd gsd-lite && npm install && node cli.js install
 
 Methods 2 & 3 write components to `~/.claude/` and register the MCP server in `settings.json`.
 
+The installer copies commands, agents, workflows, references, and hooks to `~/.claude/`, and sets up the MCP server runtime in `~/.claude/gsd/`.
+
 Uninstall: `node cli.js uninstall` or `npx gsd-lite uninstall`
 
 ## Upgrade
 
 ```bash
-# Plugin
+# Plugin (auto-update checks GitHub Releases every 24h)
 /plugin update gsd
 
 # npx
@@ -130,6 +162,7 @@ git pull && npm install && node cli.js install
 
 - Installer is idempotent — no need to uninstall first
 - Upgrades from older versions auto-clean legacy files
+- Smart cache management keeps latest 3 versions, prunes old entries
 - Restart Claude Code after updating to load new MCP server / hooks
 
 ## Quick Start
@@ -204,8 +237,10 @@ executor retries → with debugger guidance injected
 All state lives in `.gsd/state.json` — a single source of truth with:
 - Canonical fields (whitelist-controlled, schema-validated)
 - Lifecycle state machine (pending → running → checkpointed → accepted)
+- Optimistic concurrency control (`_version` field with `VERSION_CONFLICT` detection)
 - Evidence references (command outputs, test results)
 - Research artifacts and decision index
+- Incremental validation (simple field updates use fast path; phases use full validation)
 
 ## Comparison with GSD
 
@@ -213,20 +248,22 @@ All state lives in `.gsd/state.json` — a single source of truth with:
 |-----------|-----|----------|
 | Commands | 32 | **6** |
 | Agents | 12 | **4** |
-| Source files | 100+ | **~48** |
+| Source files | 100+ | **~15** |
 | Installer | 2465 lines | **~290 lines** |
 | User interactions | 6+ confirmations | **Typically 2** |
 | TDD / Anti-rationalization | No | **Yes** |
 | State machine recovery | Partial | **Full (12 modes)** |
 | Evidence-based verification | No | **Yes** |
+| Auto-update | No | **Yes** |
+| Context health monitoring | No | **Yes** |
 
 ## Project Structure
 
 ```
 gsd-lite/
-├── src/                    # MCP Server + tools
-│   ├── server.js           # MCP Server entry (11 tools)
-│   ├── schema.js           # State schema + lifecycle validation
+├── src/                    # MCP Server + tools (15 source files)
+│   ├── server.js           # MCP Server entry (11 tools + version drift detection)
+│   ├── schema.js           # State schema + lifecycle validation + incremental validation
 │   ├── utils.js            # Shared utilities (atomic writes, git, file lock)
 │   └── tools/
 │       ├── state/          # State management (modular)
@@ -236,7 +273,7 @@ gsd-lite/
 │       │   └── index.js      # Re-exports
 │       ├── orchestrator/   # Orchestration logic (modular)
 │       │   ├── helpers.js    # Shared constants, preflight, dispatch
-│       │   ├── resume.js     # Workflow resume state machine
+│       │   ├── resume.js     # Workflow resume state machine (12 modes)
 │       │   ├── executor.js   # Executor result handler
 │       │   ├── reviewer.js   # Reviewer result handler
 │       │   ├── debugger.js   # Debugger result handler
@@ -246,19 +283,24 @@ gsd-lite/
 ├── commands/               # 6 slash commands (start, prd, resume, status, stop, doctor)
 ├── agents/                 # 4 subagent prompts (executor, reviewer, researcher, debugger)
 ├── workflows/              # 6 core workflows (TDD, review, debug, research, deviation, execution-flow)
-├── references/             # 8 reference docs
-├── hooks/                  # Session lifecycle (StatusLine + PostToolUse + SessionStart + Stop + AutoUpdate)
-│   └── lib/               # Shared hook utilities (gsd-finder)
-├── tests/                  # 866 tests (unit + simulation + E2E)
+├── references/             # 8 reference docs (execution-loop, state-diagram, evidence-spec, etc.)
+├── hooks/                  # Session lifecycle hooks
+│   ├── gsd-auto-update.cjs   # Auto-update from GitHub Releases (24h check interval)
+│   ├── gsd-context-monitor.cjs # Real-time context health monitoring
+│   ├── gsd-session-init.cjs   # Session initialization + CLAUDE.md status injection
+│   ├── gsd-session-stop.cjs   # Graceful shutdown with crash markers
+│   ├── gsd-statusline.cjs     # StatusLine display (composite-aware)
+│   └── lib/                   # Shared hook utilities (gsd-finder, composite statusline, semver)
+├── tests/                  # 909 tests (unit + simulation + E2E integration)
 ├── cli.js                  # Install/uninstall CLI entry
-├── install.js              # Installation script
+├── install.js              # Installation script (plugin-aware, idempotent)
 └── uninstall.js            # Uninstall script
 ```
 
 ## Testing
 
 ```bash
-npm test                    # Run all 866 tests
+npm test                    # Run all 909 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
@@ -270,6 +312,11 @@ node --test tests/file.js   # Run a single test file
 - [Engineering Tasks](docs/gsd-lite-engineering-tasks.md) — 38 implementation tasks (5 phases, all complete)
 - [Calibration Notes](docs/calibration-notes.md) — Context threshold and TTL calibration
 
+## Requirements
+
+- Node.js >= 20.0.0
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
 ## License
 
 MIT

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

@@ -183,6 +183,11 @@ export function main() {
   // 6. Stable runtime for MCP server
   copyDir(join(__dirname, 'src'), join(RUNTIME_DIR, 'src'), 'runtime/src → ~/.claude/gsd/src/');
   copyFile(join(__dirname, 'package.json'), join(RUNTIME_DIR, 'package.json'), 'runtime/package.json → ~/.claude/gsd/package.json');
+  // Copy lock file so `npm ci` works when node_modules are not present (npx scenario)
+  const lockFile = join(__dirname, 'package-lock.json');
+  if (existsSync(lockFile)) {
+    copyFile(lockFile, join(RUNTIME_DIR, 'package-lock.json'), 'runtime/package-lock.json → ~/.claude/gsd/package-lock.json');
+  }
 
   // 7. Runtime dependencies — copy local node_modules or install fresh (npx hoists deps)
   const localNM = join(__dirname, 'node_modules');
@@ -190,8 +195,11 @@ export function main() {
     copyDir(localNM, join(RUNTIME_DIR, 'node_modules'), 'runtime/node_modules (copied)');
   } else if (!DRY_RUN) {
     log('  ⧗ Installing runtime dependencies...');
+    const lockFile = join(RUNTIME_DIR, 'package-lock.json');
+    const hasLockFile = existsSync(lockFile);
+    const installCmd = hasLockFile ? 'npm ci --omit=dev' : 'npm install --omit=dev --no-fund --no-audit';
     try {
-      execSync('npm ci --omit=dev', { cwd: RUNTIME_DIR, stdio: 'pipe' });
+      execSync(installCmd, { cwd: RUNTIME_DIR, stdio: 'pipe' });
       log('  ✓ runtime dependencies installed');
     } catch (err) {
       log(`  ✗ Failed to install runtime dependencies: ${err.message}`);
@@ -264,7 +272,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.9",
   "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
 {