gsd-lite 0.6.9 → 0.7.3

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -291,7 +291,7 @@ gsd-lite/
 │   ├── 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)
+├── tests/                  # 966 tests (unit + simulation + E2E integration)
 ├── cli.js                  # Install/uninstall CLI entry
 ├── install.js              # Installation script (plugin-aware, idempotent)
 └── uninstall.js            # Uninstall script
@@ -300,7 +300,7 @@ gsd-lite/
 ## Testing
 
 ```bash
-npm test                    # Run all 909 tests
+npm test                    # Run all 966 tests
 npm run test:coverage       # Tests + coverage report (94%+ lines, 83%+ branches)
 npm run lint                # Biome lint
 node --test tests/file.js   # Run a single test file

package/agents/debugger.md

@@ -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/doctor.md

@@ -28,18 +28,25 @@ Call the `health` MCP tool:
 
 Check if GSD hooks are registered in Claude settings:
 - Read `~/.claude/settings.json` (or `~/.claude/settings.local.json`)
-- StatusLine check (check BOTH paths):
-  1. Direct: `statusLine` entry containing `gsd-statusline`
-  2. Composite: read `~/.cache/code-graph/statusline-registry.json` — if any entry's `command` contains `gsd-statusline`, it is registered through the composite statusline system
-  - Either path present: StatusLine = registered
-- Check for `PostToolUse` hook entry containing `gsd-context-monitor`
-- Both present: record PASS
-- Partial: record WARN with which hook is missing
-- Neither: record FAIL "No GSD hooks registered"
-
-Also verify the hook files exist on disk:
+- StatusLine check (registered if ANY path matches):
+  1. Direct: `statusLine.command` contains `gsd-statusline`
+  2. Composite cache registry: `~/.cache/code-graph/statusline-registry.json` — any entry whose `command` contains `gsd-statusline`
+  3. Composite backup mirror: `~/.claude/statusline-providers.json` — same match rule (durable mirror written by code-graph's chain CLI)
+  - Any path present: StatusLine = registered
+- Check the three hook arrays in `settings.hooks`:
+  - `PostToolUse` entry referencing `gsd-context-monitor`
+  - `SessionStart` entry referencing `gsd-session-init`
+  - `Stop` entry referencing `gsd-session-stop`
+- All four (statusLine + three hooks) present: record PASS
+- Partial: record WARN naming each missing hook
+- None: record FAIL "No GSD hooks registered"
+
+Also verify the hook files exist on disk (install.js copies all five):
 - `~/.claude/hooks/gsd-statusline.cjs`
 - `~/.claude/hooks/gsd-context-monitor.cjs`
+- `~/.claude/hooks/gsd-session-init.cjs`
+- `~/.claude/hooks/gsd-session-stop.cjs`
+- `~/.claude/hooks/gsd-auto-update.cjs`
 - Files missing but settings present: record WARN "Hook registered but file missing"
 
 ## STEP 4: Lock File Check

package/commands/status.md

@@ -91,6 +91,7 @@ Blocked 任务:
 
 | workflow_mode | 建议 |
 |---|---|
+| planning | "仍在计划阶段，运行 /gsd:start 或 /gsd:prd 重新启动计划" |
 | executing_task | "自动执行中，等待完成" |
 | reviewing_task | "L2 审查进行中" |
 | reviewing_phase | "L1 阶段审查进行中" |

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/hooks/lib/statusline-composite.cjs

@@ -1,14 +1,26 @@
 'use strict';
 // Detect and register with composite statusline systems (e.g., code-graph).
 // Used by install.js, gsd-session-init.cjs, and uninstall.js.
+//
+// Preferred path (code-graph ≥ shipping statusline-chain.js): invoke that CLI
+// with `register gsd <cmd> --stdin` / `unregister gsd`. The CLI owns both the
+// primary cache registry and the ~/.claude/statusline-providers.json backup
+// mirror, so we do not have to know their layout.
+// Fallback path (older code-graph without the CLI): write the cache registry
+// directly, same as the original behavior.
 
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+const { semverSortComparator } = require('./semver-sort.cjs');
 
-// Known composite statusline registry paths
+const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+
+// Known composite statusline registry paths (fallback-only — chain CLI is preferred).
 const REGISTRY_PATHS = [
   path.join(os.homedir(), '.cache', 'code-graph', 'statusline-registry.json'),
+  path.join(CLAUDE_DIR, 'statusline-providers.json'),
 ];
 
 function isCompositeStatusLine(command) {
@@ -22,13 +34,46 @@ function findCompositeRegistry() {
   return null;
 }
 
+/**
+ * Find code-graph's statusline-chain.js in the plugin cache (newest semver).
+ * Returns absolute path or null if the CLI hasn't shipped yet.
+ */
+function findChainScript() {
+  const base = path.join(CLAUDE_DIR, 'plugins', 'cache', 'code-graph-mcp', 'code-graph-mcp');
+  if (!fs.existsSync(base)) return null;
+  let versions;
+  try {
+    versions = fs.readdirSync(base).filter(v => /^\d+\.\d+\.\d+/.test(v));
+  } catch { return null; }
+  versions.sort(semverSortComparator).reverse();
+  for (const v of versions) {
+    const p = path.join(base, v, 'scripts', 'statusline-chain.js');
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function runChainCLI(args) {
+  const chainScript = findChainScript();
+  if (!chainScript) return false;
+  try {
+    execFileSync(process.execPath, [chainScript, ...args], { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
 /**
  * Register GSD as a provider in the composite statusline registry.
+ * Prefers code-graph's statusline-chain.js CLI when available; falls back to
+ * writing the cache registry directly for older code-graph versions.
  * Idempotent: updates existing entry or inserts before code-graph.
  * @param {string} statuslineScriptPath - Absolute path to gsd-statusline.cjs
  * @returns {boolean} true if registered/updated
  */
 function registerProvider(statuslineScriptPath) {
+  const command = `node ${JSON.stringify(statuslineScriptPath)}`;
+  if (runChainCLI(['register', 'gsd', command, '--stdin'])) return true;
+
   let registryPath = findCompositeRegistry();
 
   // If composite statusLine is configured but registry file is missing,
@@ -54,7 +99,6 @@ function registerProvider(statuslineScriptPath) {
     }
     if (!Array.isArray(registry)) return false;
 
-    const command = `node ${JSON.stringify(statuslineScriptPath)}`;
     const provider = { id: 'gsd', command, needsStdin: true };
 
     // Find existing GSD entry (by id or command)
@@ -82,9 +126,13 @@ function registerProvider(statuslineScriptPath) {
 
 /**
  * Remove GSD entry from composite statusline registry.
+ * Prefers code-graph's statusline-chain.js CLI when available; falls back to
+ * rewriting the cache registry directly for older code-graph versions.
  * @returns {boolean} true if an entry was removed
  */
 function removeProvider() {
+  if (runChainCLI(['unregister', 'gsd'])) return true;
+
   const registryPath = findCompositeRegistry();
   if (!registryPath) return false;
 

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 });
@@ -272,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.9",
+  "version": "0.7.3",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {
@@ -50,6 +50,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1"
   },
+  "overrides": {
+    "hono": "^4.12.14",
+    "@hono/node-server": "^1.19.14"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
     "c8": "^11.0.0"

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);
@@ -485,8 +493,8 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0, unb
           success: true,
           action: 'await_manual_intervention',
           workflow_mode: state.workflow_mode,
-          guidance: 'Complete planning and call state-init to initialize the project',
-          message: 'Project is in planning mode; complete the plan and initialize with state-init',
+          guidance: 'Plan is being revised. Run /gsd:start or /gsd:prd to continue planning, or state-update workflow_mode back to executing_task when ready.',
+          message: 'Project is in planning mode (plan revision). Finish the plan then set workflow_mode back to executing_task.',
         };
         break;
       case 'reconcile_workspace': {

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);
 }
 
 /**
@@ -156,7 +156,7 @@ export async function init({ project, phases, research, force = false, basePath
 export async function read({ fields, basePath = process.cwd(), validate = false } = {}) {
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
 
   const result = await readJson(statePath);
@@ -207,7 +207,7 @@ export async function update({ updates, basePath = process.cwd(), expectedVersio
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
   ensureLockPathFromStatePath(statePath);
 
@@ -378,7 +378,7 @@ export async function update({ updates, basePath = process.cwd(), expectedVersio
 
     await writeJson(statePath, merged);
     return { success: true, state: merged };
-  });
+  }, statePath);
 }
 
 /**
@@ -425,7 +425,7 @@ export async function phaseComplete({
   }
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
   ensureLockPathFromStatePath(statePath);
 
@@ -592,7 +592,7 @@ export async function phaseComplete({
       workflow_mode: state.workflow_mode,
       ...(isCompleted ? { message: 'All phases completed — project finished' } : {}),
     };
-  });
+  }, statePath);
 }
 
 /**
@@ -612,7 +612,7 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
   ensureLockPathFromStatePath(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);
 }
 
 /**
@@ -693,7 +693,7 @@ export async function pruneEvidence({ currentPhase, basePath = process.cwd() })
   }
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
   ensureLockPathFromStatePath(statePath);
 
@@ -712,7 +712,7 @@ export async function pruneEvidence({ currentPhase, basePath = process.cwd() })
     }
 
     return { success: true, archived };
-  });
+  }, statePath);
 }
 
 /**
@@ -733,7 +733,7 @@ export async function patchPlan({ operations, basePath = process.cwd() } = {}) {
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
   ensureLockPathFromStatePath(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 {
@@ -431,7 +430,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No GSD project found (.gsd directory missing). Run /gsd:start or /gsd:prd to begin.' };
   }
   ensureLockPathFromStatePath(statePath);
 
@@ -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"`