gsd-lite 0.6.8 → 0.7.0

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "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/debugger.md

@@ -49,9 +49,9 @@ Phase 2 模式分析:
   2. 对比差异，列出所有不同点
   3. 不要假设"那个不重要"
 
-Phase 3 假设测试:
+Phase 3 假设测试 (通过观察验证，不直接修改代码):
   1. 明确陈述: "我认为 X 是根因，因为 Y"
-  2. 最小变更测试 (一次只改一个变量)
+  2. 通过 Bash 运行测试/添加日志、读取运行时输出来验证假设
   3. 验证: 有效 → Phase 4 / 无效 → 新假设
 
 Phase 4 修复方向建议:

package/agents/executor.md

@@ -52,7 +52,7 @@ tools: Read, Write, Edit, Bash, Grep, Glob
   "summary": "Implemented PUT /api/users/:id endpoint",
   "checkpoint_commit": "a1b2c3d",
   "files_changed": ["src/api/users.ts", "tests/users.test.ts"],
-  "decisions": ["[DECISION] use optimistic locking by version column"],
+  "decisions": [{"id": "d1", "summary": "use optimistic locking by version column", "rationale": "prevents concurrent update conflicts"}],
   "blockers": [],
   "contract_changed": true,
   "confidence": "high",

package/commands/stop.md

@@ -29,8 +29,6 @@ description: Save current state and pause project execution
 
 使用 `state-update` MCP 工具更新状态，确保通过 schema 校验和乐观锁。
 
-使用原子写入: 先写 `.gsd/state.json.tmp`，成功后 rename 为 `.gsd/state.json`
-
 ## STEP 3: 确认输出
 
 输出: "已暂停。运行 /gsd:resume 继续"

package/hooks/gsd-auto-update.cjs

@@ -323,7 +323,7 @@ function validateExtractedPackage(extractDir) {
     const pkgPath = path.join(extractDir, 'package.json');
     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;
+    if (!pkg.version || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.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);
@@ -404,8 +404,26 @@ async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
     // Write tarball to file, then extract with spawnSync (no shell)
     const tarPath = path.join(tmpDir, 'release.tar.gz');
     fs.writeFileSync(tarPath, tarData);
-    const tar = spawnSync('tar', ['xzf', tarPath, '-C', tmpDir, '--strip-components=1'], { timeout: 30000 });
-    if (tar.status !== 0) throw new Error(`tar extract failed: ${(tar.stderr || '').toString().slice(0, 200)}`);
+    const stripFlag = process.platform === 'win32' ? [] : ['--strip-components=1'];
+    const tar = spawnSync('tar', ['xzf', tarPath, '-C', tmpDir, ...stripFlag], { timeout: 30000 });
+    if (tar.status !== 0) {
+      const errMsg = (tar.stderr || '').toString().slice(0, 200);
+      if (process.platform === 'win32') {
+        console.error('[gsd] Auto-update: tar extraction failed on Windows — manual update may be required');
+      }
+      throw new Error(`tar extract failed: ${errMsg}`);
+    }
+    // On Windows without --strip-components, the content is nested in a subdirectory
+    if (process.platform === 'win32') {
+      const entries = fs.readdirSync(tmpDir).filter(e => e !== 'release.tar.gz');
+      if (entries.length === 1 && fs.statSync(path.join(tmpDir, entries[0])).isDirectory()) {
+        const nested = path.join(tmpDir, entries[0]);
+        for (const f of fs.readdirSync(nested)) {
+          fs.renameSync(path.join(nested, f), path.join(tmpDir, f));
+        }
+        fs.rmdirSync(nested);
+      }
+    }
 
     // Validate extracted package before installing
     if (!validateExtractedPackage(tmpDir)) {
@@ -499,7 +517,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() && /^\d+\.\d+\.\d+$/.test(e.name))
+      .filter(e => e.isDirectory() && /^\d+\.\d+\.\d+(-[\w.]+)?$/.test(e.name))
       .map(e => e.name);
     if (entries.length <= keepCount) return;
 
@@ -546,7 +564,7 @@ function syncPluginCache(extractedDir, verbose = false) {
     const newPkgPath = path.join(extractedDir, 'package.json');
     if (!fs.existsSync(newPkgPath)) return;
     const newVersion = JSON.parse(fs.readFileSync(newPkgPath, 'utf8')).version;
-    if (!newVersion) return;
+    if (!newVersion || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(newVersion)) return;
 
     // Determine new cache path
     const cacheBase = path.join(claudeDir, 'plugins', 'cache', 'gsd', 'gsd');

package/hooks/lib/semver-sort.cjs

@@ -2,17 +2,45 @@
 '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.
+ * Compare two semver version strings for sorting.
+ * Handles pre-release suffixes: 1.0.0-beta.1 < 1.0.0 (per semver spec).
  * @param {string} a
  * @param {string} b
  * @returns {number}
  */
 function semverSortComparator(a, b) {
-  const pa = a.split('.').map(s => parseInt(s, 10) || 0);
-  const pb = b.split('.').map(s => parseInt(s, 10) || 0);
+  const [coreA, preA] = String(a).split('-', 2);
+  const [coreB, preB] = String(b).split('-', 2);
+  const pa = coreA.split('.').map(s => parseInt(s, 10) || 0);
+  const pb = coreB.split('.').map(s => parseInt(s, 10) || 0);
   for (let i = 0; i < 3; i++) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  // Same core version: pre-release < release (1.0.0-beta < 1.0.0)
+  if (preA && !preB) return -1;
+  if (!preA && preB) return 1;
+  if (preA && preB) {
+    // Compare pre-release identifiers left-to-right
+    const partsA = preA.split('.');
+    const partsB = preB.split('.');
+    for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
+      if (i >= partsA.length) return -1; // fewer fields = lower precedence
+      if (i >= partsB.length) return 1;
+      const na = parseInt(partsA[i], 10);
+      const nb = parseInt(partsB[i], 10);
+      const aIsNum = !Number.isNaN(na);
+      const bIsNum = !Number.isNaN(nb);
+      if (aIsNum && bIsNum) {
+        if (na !== nb) return na - nb;
+      } else if (aIsNum) {
+        return -1; // numeric < string
+      } else if (bIsNum) {
+        return 1;
+      } else {
+        const cmp = partsA[i].localeCompare(partsB[i]);
+        if (cmp !== 0) return cmp;
+      }
+    }
   }
   return 0;
 }

package/install.js

@@ -145,7 +145,7 @@ export function main() {
     const preserveRuntime = existsSync(runtimeSubdir);
     let runtimeBackup;
     if (preserveRuntime) {
-      runtimeBackup = join(RUNTIME_DIR, '..', '.gsd-runtime-backup');
+      runtimeBackup = join(RUNTIME_DIR, '..', `.gsd-runtime-backup-${process.pid}`);
       try { cpSync(runtimeSubdir, runtimeBackup, { recursive: true }); } catch { runtimeBackup = null; }
     }
     rmSync(RUNTIME_DIR, { recursive: true, force: true });
@@ -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() && /^\d+\.\d+\.\d+$/.test(e.name)).map(e => e.name);
+          .filter(e => e.isDirectory() && /^\d+\.\d+\.\d+(-[\w.]+)?$/.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/launcher.js

@@ -14,6 +14,7 @@ if (!existsSync(join(__dirname, 'node_modules', '@modelcontextprotocol'))) {
     execSync('npm install --omit=dev --ignore-scripts', {
       cwd: __dirname,
       stdio: 'pipe',
+      timeout: 60000,
     });
   } catch (err) {
     console.error('Failed to install dependencies:', err.stderr?.toString() || err.message);

package/package.json

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

package/references/review-classification.md

@@ -34,6 +34,7 @@ task.level 当前值?
 └── L0 或 L1
     ├── executor decisions 含 [LEVEL-UP]? -> 升级为 L2
     ├── contract_changed: true + task.name 匹配敏感关键词? -> 升级为 L2
+    ├── L1 + confidence: 'low'? -> 升级为 L2
     ├── L1 + confidence: 'high' + !contract_changed + 有 evidence 且无测试失败? -> 降为 L0
     └── 否 -> 保持当前级别
 ```

package/src/tools/orchestrator/executor.js

@@ -23,6 +23,7 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
   // Note: read() is outside the state lock. This is safe because the MCP server
   // processes tool calls sequentially (single-session, promise-queue serialized).
   // persist() below re-acquires the lock and applies changes atomically.
+  // TODO: if MCP SDK supports concurrent tool calls, move this read inside withStateLock.
   const state = await read({ basePath });
   if (state.error) return state;
   const { phase, task } = getPhaseAndTask(state, result.task_id);

package/src/tools/orchestrator/resume.js

@@ -1,5 +1,7 @@
 import { read, selectRunnableTask } from '../state/index.js';
-import { getGitHead } from '../../utils.js';
+import { getGitHead, getGsdDir } from '../../utils.js';
+import { join } from 'node:path';
+import { unlink } from 'node:fs/promises';
 import {
   MAX_RESUME_DEPTH,
   CONTEXT_RESUME_THRESHOLD,
@@ -269,6 +271,12 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0, unb
     return state;
   }
 
+  // Clear session-end marker if present (crash recovery)
+  try {
+    const gsdDir = await getGsdDir(basePath);
+    if (gsdDir) await unlink(join(gsdDir, '.session-end')).catch(() => {});
+  } catch {}
+
   // Force-unblock specified tasks before normal resume flow
   if (Array.isArray(unblock_tasks) && unblock_tasks.length > 0 && _depth === 0) {
     const phase = getCurrentPhase(state);

package/src/tools/state/constants.js

@@ -22,32 +22,43 @@ export const ERROR_CODES = {
 
 // C-1: Serialize all state mutations to prevent TOCTOU races
 // C-2: Layer cross-process advisory file lock on top of in-process queue
-let _mutationQueue = Promise.resolve();
-let _fileLockPath = null;
+// Per-basePath keyed maps — safe for multi-project concurrent use
+const _mutationQueues = new Map();
+const _fileLockPaths = new Map();
 
 export function setLockPath(lockPath) {
-  _fileLockPath = lockPath;
+  // Legacy API for tests — sets/clears the default (null-key) lock path
+  if (lockPath === null) {
+    _fileLockPaths.delete(null);
+    _mutationQueues.delete(null);
+  } else {
+    _fileLockPaths.set(null, lockPath);
+  }
 }
 
 /**
- * Ensure _fileLockPath is set from a known state path.
+ * Ensure lock path is set for a given state path.
  * Must be called before withStateLock in all mutation paths.
  */
 export function ensureLockPathFromStatePath(statePath) {
   if (statePath) {
-    _fileLockPath = join(dirname(statePath), 'state.lock');
+    const lockPath = join(dirname(statePath), 'state.lock');
+    _fileLockPaths.set(statePath, lockPath);
   }
 }
 
-export function withStateLock(fn) {
-  const p = _mutationQueue.then(() => {
-    if (_fileLockPath) {
-      return withFileLock(_fileLockPath, fn);
+export function withStateLock(fn, statePath) {
+  const lockPath = _fileLockPaths.get(statePath) ?? _fileLockPaths.get(null);
+  const queueKey = statePath ?? null;
+  const prev = _mutationQueues.get(queueKey) ?? Promise.resolve();
+  const p = prev.then(() => {
+    if (lockPath) {
+      return withFileLock(lockPath, fn);
     }
     process.stderr.write('[gsd] WARNING: withStateLock called without lock path — cross-process safety not guaranteed\n');
     return fn();
   });
-  _mutationQueue = p.catch(() => {});
+  _mutationQueues.set(queueKey, p.catch(() => {}));
   return p;
 }
 

package/src/tools/state/crud.js

@@ -147,7 +147,7 @@ export async function init({ project, phases, research, force = false, basePath
       })),
       research: !!research,
     };
-  });
+  }, statePath);
 }
 
 /**
@@ -378,7 +378,7 @@ export async function update({ updates, basePath = process.cwd(), expectedVersio
 
     await writeJson(statePath, merged);
     return { success: true, state: merged };
-  });
+  }, statePath);
 }
 
 /**
@@ -592,7 +592,7 @@ export async function phaseComplete({
       workflow_mode: state.workflow_mode,
       ...(isCompleted ? { message: 'All phases completed — project finished' } : {}),
     };
-  });
+  }, statePath);
 }
 
 /**
@@ -639,7 +639,7 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
     state._version = (state._version ?? 0) + 1;
     await writeJson(statePath, state);
     return { success: true };
-  });
+  }, statePath);
 }
 
 /**
@@ -712,7 +712,7 @@ export async function pruneEvidence({ currentPhase, basePath = process.cwd() })
     }
 
     return { success: true, archived };
-  });
+  }, statePath);
 }
 
 /**
@@ -792,7 +792,7 @@ export async function patchPlan({ operations, basePath = process.cwd() } = {}) {
     state._version = (state._version ?? 0) + 1;
     await writeJson(statePath, state);
     return { success: true, applied, plan_version: state.plan_version };
-  });
+  }, statePath);
 }
 
 function _applyPatchOp(state, op) {

package/src/tools/state/logic.js

@@ -1,7 +1,6 @@
 // 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 {
@@ -450,7 +449,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     // 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 }));
+    await writeFile(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);
@@ -472,7 +471,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
       for (const { tmp } of tmpPaths) {
         try { await unlink(tmp); } catch {}
       }
-      try { unlinkSync(sentinelPath); } catch {}
+      try { await unlink(sentinelPath); } catch {}
       throw err;
     }
 
@@ -509,7 +508,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
 
     const validation = validateState(state);
     if (!validation.valid) {
-      try { unlinkSync(sentinelPath); } catch {}
+      try { await unlink(sentinelPath); } catch {}
       return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `State validation failed: ${validation.errors.join('; ')}` };
     }
 
@@ -517,7 +516,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     await writeJson(statePath, state);
 
     // Remove sentinel after successful state write — crash consistency window closed
-    try { unlinkSync(sentinelPath); } catch {}
+    try { await unlink(sentinelPath); } catch {}
 
     return {
       success: true,
@@ -527,5 +526,5 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
       warnings: refreshResult.warnings,
       research: state.research,
     };
-  });
+  }, statePath);
 }

package/workflows/deviation-rules.md

@@ -77,7 +77,7 @@
 
 ### STOP: 3 次失败停止
 
-**条件:** 同一错误指纹 (file+line 或 msg[:50]) 出现 3 次。
+**条件:** 同一 task 连续失败 3 次 (retry_count >= 3)。error_fingerprint 仅用于调试上下文，不参与触发判断。
 
 处理:
 1. 返回 `outcome: "failed"`