gsd-lite 0.3.5 → 0.3.7

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.3.4",
+      "version": "0.3.6",
       "keywords": ["orchestration", "mcp", "tdd", "task-management"],
       "category": "Development workflows"
     }

package/.claude-plugin/plugin.json

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

package/agents/debugger.md

@@ -1,7 +1,7 @@
 ---
 name: debugger
 description: Systematic debugging with root cause analysis
-tools: Read, Write, Edit, Bash, Grep, Glob
+tools: Read, Bash, Grep, Glob
 ---
 
 <role>
@@ -54,11 +54,11 @@ Phase 3 假设测试:
   2. 最小变更测试 (一次只改一个变量)
   3. 验证: 有效 → Phase 4 / 无效 → 新假设
 
-Phase 4 实施修复:
-  1. 写失败测试 (复现 bug)
-  2. 修复根因 (不是症状)
-  3. 验证测试通过 + 无回归
-  → 3 次修复失败 → 停止。质疑架构。报告给编排器。
+Phase 4 修复方向建议:
+  1. 提出修复方案 (针对根因，不是症状)
+  2. 建议失败测试用例 (供 executor 实现)
+  3. 评估修复影响范围 (哪些下游可能受影响)
+  → 3 次修复方向均被 executor 验证无效 → 停止。标记 architecture_concern: true。报告给编排器。
 </four_phases>
 
 <result_contract>

package/agents/researcher.md

@@ -39,3 +39,12 @@ tools: Read, Write, Bash, WebSearch, WebFetch, mcp__plugin_context7_context7__*
 ```
 </result_contract>
 </research_output>
+
+<uncertainty_handling>
+## 遇到不确定性时
+子代理不能直接与用户交互。遇到不确定性时:
+1. 来源冲突 → 报告双方立场及置信度，让编排器决定。在 result 中标注 "[DECISION] 选择了X因为Y"
+2. 所有来源不可用 (Context7 + WebSearch + 官方文档均失败) → 返回 "[BLOCKED] 需要: 研究来源不可用，请提供替代信息或缩小范围"
+3. 研究范围过广无法收敛 → 返回 "[BLOCKED] 需要: 研究范围过广，请指定重点领域"
+4. 发现结论与已有 decisions 矛盾 → 在 result 中标注冲突，让编排器决定是否更新 decision
+</uncertainty_handling>

package/commands/prd.md

@@ -100,12 +100,16 @@ argument-hint: File path to requirements doc, or inline description text
 
 → 自审修正后再展示给用户
 
+<HARD-GATE id="plan-confirmation">
 ## STEP 9: 展示计划，等待用户确认
 
 - 展示完整分阶段计划
 - 用户指出问题 → 调整 → 再展示
 - 用户确认 → 继续
 
+⛔ 不得在用户确认前执行 STEP 10-12。未确认 = 不写文件、不执行代码。
+</HARD-GATE>
+
 ## STEP 10: 生成文档
 
 - 创建 .gsd/ 目录

package/commands/resume.md

@@ -35,17 +35,18 @@ description: Resume project execution from saved state with workspace validation
      - 不一致 → 覆写 `workflow_mode = reconcile_workspace`
 
 2. **计划版本校验:**
-   - 如果本地 plan.md 或 phases/*.md 被手动修改，且 `plan_version` 不匹配
+   - 如果本地 plan.md 或 phases/*.md 被手动修改 (mtime > last_session)
    - → 覆写 `workflow_mode = replan_required`
 
-3. **研究过期校验:**
+3. **方向漂移校验:**
+   - 如果当前或任何未完成 phase 的 `phase_handoff.direction_ok === false`
+   - → 覆写 `workflow_mode = awaiting_user`
+
+4. **研究过期校验:**
    - 如果 `research.expires_at` 已过期 (早于当前时间)
+   - 或 research.decision_index 中有条目的 expires_at 已过期
    - → 覆写 `workflow_mode = research_refresh_needed`
 
-4. **工作区冲突校验:**
-   - 运行 `git status` 检查是否存在冲突或脏工作区
-   - 存在未解决的合并冲突 → 覆写 `workflow_mode = awaiting_user`
-
 5. **全部通过:**
    - 保持原 `workflow_mode` 不变
 
@@ -176,6 +177,14 @@ description: Resume project execution from saved state with workspace validation
 
 ---
 
+### `planning` — 计划中断
+
+- 计划编制过程中被中断
+- 告知用户: "项目仍在计划阶段。请运行 /gsd:start 或 /gsd:prd 重新启动计划流程"
+- 不自动执行
+
+---
+
 ### `failed` — 已失败
 
 - 展示失败信息:

package/commands/start.md

@@ -30,7 +30,7 @@ argument-hint: Optional feature or project description
 ## STEP 4 — 需求追问
 
 用户回答后，跟进追问直到需求清晰:
-- 使用 `references/questioning.md` 技巧 (挑战模糊、具象化、发现边界)
+- 使用 Read 工具读取 `references/questioning.md`，按其中的技巧进行提问 (挑战模糊、具象化、发现边界)
 - 每个问题提供选项，标识 ⭐ 推荐选项
 - 多轮对话直到需求清晰 (通常 2-4 轮)
 - 每轮最多 3-5 个问题，避免过度追问
@@ -113,12 +113,17 @@ argument-hint: Optional feature or project description
 
 → 自审修正后再展示给用户。
 
+<HARD-GATE id="plan-confirmation">
 ## STEP 9 — 用户确认计划
 
 展示计划给用户，等待确认:
 - 用户指出问题 → 调整计划 → 重新展示
 - 用户确认 → 继续
 
+⛔ 不得在用户确认前执行 STEP 10-12。未确认 = 不写文件、不执行代码。
+</HARD-GATE>
+
+<HARD-GATE id="docs-written">
 ## STEP 10 — 生成文档
 
 1. 创建 `.gsd/` 目录
@@ -141,6 +146,13 @@ argument-hint: Optional feature or project description
 - `phases/*.md` 是 task 规格的唯一 source of truth
 - `plan.md` 不包含 task 级细节，避免与 `phases/*.md` 重复
 
+□ state.json 已写入且包含所有 canonical fields
+□ plan.md 已写入
+□ phases/*.md 已写入 (每个 phase 一个文件)
+□ 所有 task 都有 lifecycle / level / requires / review_required
+→ 全部满足才可继续
+</HARD-GATE>
+
 ## STEP 11 — 自动执行主路径
 
 进入执行主循环。phase = 管理边界，task = 执行边界。

package/commands/stop.md

@@ -11,8 +11,9 @@ description: Save current state and pause project execution
 
 ## STEP 1: 保存完整状态
 
-读取并更新 `.gsd/state.json`:
+读取 `.gsd/state.json`:
 - 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，无需停止"，停止
+- 如果 `workflow_mode` 已是 `completed` 或 `failed` → 告知用户 "项目已终结 ({workflow_mode})，无需停止"，停止
 
 确保以下信息已保存到 state.json:
 - `current_phase` / `current_task` — 当前执行位置

package/hooks/context-monitor.js

@@ -31,10 +31,10 @@ export function postToolUse(basePath) {
     const gsdDir = join(basePath || process.cwd(), '.gsd');
     const health = parseInt(readFileSync(join(gsdDir, '.context-health'), 'utf-8'), 10);
 
-    if (health < 25) {
+    if (health <= 25) {
       return `🛑 CONTEXT EMERGENCY (${health}% remaining): Save state NOW. Set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
     }
-    if (health < 35) {
+    if (health <= 35) {
       return `⚠️ CONTEXT LOW (${health}% remaining): Complete current task, save state, set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
     }
   } catch (err) {

package/hooks/gsd-context-monitor.cjs

@@ -68,14 +68,18 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // Non-GSD sessions: don't interfere — let Claude's auto-compaction handle it
+    const isGsdActive = metrics.has_gsd === true;
+    if (!isGsdActive) {
+      process.exit(0);
+    }
+
     // Debounce logic
     const warnPath = path.join(tmpDir, `gsd-ctx-${sessionId}-warned.json`);
     let warnData = { callsSinceWarn: 0, lastLevel: null };
-    let firstWarn = true;
 
     try {
       warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
-      firstWarn = false;
     } catch {
       // No prior warning state — first warning this session
     }
@@ -85,25 +89,24 @@ process.stdin.on('end', () => {
     const isCritical = remaining <= CRITICAL_THRESHOLD;
     const currentLevel = isCritical ? 'critical' : 'warning';
 
-    // Severity escalation bypasses debounce
+    // Atomic debounce state write helper
+    const writeWarnData = (data) => {
+      const tmpFile = warnPath + `.${process.pid}-${Date.now()}.tmp`;
+      fs.writeFileSync(tmpFile, JSON.stringify(data));
+      fs.renameSync(tmpFile, warnPath);
+    };
+
+    // Severity escalation bypasses debounce (lastLevel null = first warning, always fire)
     const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
-    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
-      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+    if (warnData.lastLevel !== null && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      writeWarnData(warnData);
       process.exit(0);
     }
 
     // Reset debounce
     warnData.callsSinceWarn = 0;
     warnData.lastLevel = currentLevel;
-    fs.writeFileSync(warnPath, JSON.stringify(warnData));
-
-    // Use bridge data to avoid extra filesystem check
-    const isGsdActive = metrics.has_gsd === true;
-
-    // Non-GSD sessions: don't interfere — let Claude's auto-compaction handle it
-    if (!isGsdActive) {
-      process.exit(0);
-    }
+    writeWarnData(warnData);
 
     let message;
     if (isCritical) {

package/hooks/gsd-statusline.cjs

@@ -7,6 +7,24 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
+/**
+ * Walk from startDir up to filesystem root looking for a .gsd directory.
+ * Returns the absolute path to .gsd if found, or null.
+ */
+function findGsdDir(startDir) {
+  let dir = startDir;
+  while (true) {
+    const candidate = path.join(dir, '.gsd');
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate;
+    } catch {
+      const parent = path.dirname(dir);
+      if (parent === dir) return null; // reached filesystem root
+      dir = parent;
+    }
+  }
+}
+
 let input = '';
 const stdinTimeout = setTimeout(() => process.exit(0), 3000);
 process.stdin.setEncoding('utf8');
@@ -24,8 +42,8 @@ process.stdin.on('end', () => {
     // Current GSD task from state.json
     let task = '';
     let hasGsd = false;
-    const gsdDir = path.join(cwd, '.gsd');
-    try {
+    const gsdDir = findGsdDir(cwd);
+    if (gsdDir) try {
       const state = JSON.parse(fs.readFileSync(path.join(gsdDir, 'state.json'), 'utf8'));
       hasGsd = true;
       if (state.current_task && state.current_phase) {
@@ -71,21 +89,24 @@ process.stdin.on('end', () => {
       }
 
       // Also write to .gsd/.context-health for MCP server reads (atomic, skip if unchanged)
-      try {
-        const healthPath = path.join(gsdDir, '.context-health');
-        let needsHealthWrite = true;
+      // Only write if a .gsd directory was found — never create .gsd from the hook
+      if (gsdDir) {
         try {
-          const current = fs.readFileSync(healthPath, 'utf8').trim();
-          if (current === String(remaining)) needsHealthWrite = false;
-        } catch { /* file doesn't exist yet */ }
-        if (needsHealthWrite) {
-          fs.mkdirSync(gsdDir, { recursive: true });
-          const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}-${Date.now()}.tmp`);
-          fs.writeFileSync(tmpHealth, String(remaining));
-          fs.renameSync(tmpHealth, healthPath);
+          const healthPath = path.join(gsdDir, '.context-health');
+          let needsHealthWrite = true;
+          try {
+            const current = fs.readFileSync(healthPath, 'utf8').trim();
+            if (current === String(remaining)) needsHealthWrite = false;
+          } catch { /* file doesn't exist yet */ }
+          if (needsHealthWrite) {
+            fs.mkdirSync(gsdDir, { recursive: true });
+            const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}-${Date.now()}.tmp`);
+            fs.writeFileSync(tmpHealth, String(remaining));
+            fs.renameSync(tmpHealth, healthPath);
+          }
+        } catch (e) {
+          if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: context-health write failed: ${e.message}\n`);
         }
-      } catch (e) {
-        if (process.env.GSD_DEBUG) process.stderr.write(`gsd-statusline: context-health write failed: ${e.message}\n`);
       }
 
       // Progress bar (10 segments)

package/package.json

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

package/references/evidence-spec.md

@@ -102,13 +102,12 @@ if (Object.keys(state.evidence).length > MAX_EVIDENCE_ENTRIES) {
 
 `_pruneEvidenceFromState(state, currentPhase, gsdDir)`:
 
-1. 计算阈值: `threshold = currentPhase - 1`
-2. 遍历所有 evidence 条目
-3. 对每条 evidence 调用 `parseScopePhase(entry.scope)` 提取 phase 编号
-4. 如果 `phaseNum !== null && phaseNum < threshold` -> 标记为待归档
-5. 其余保留 (包括 scope 无法解析的条目)
+1. 遍历所有 evidence 条目
+2. 对每条 evidence 调用 `parseScopePhase(entry.scope)` 提取 phase 编号
+3. 如果 `phaseNum !== null && phaseNum < currentPhase` -> 标记为待归档
+4. 其余保留 (包括 scope 无法解析的条目)
 
-规则: 保留当前 phase 和前一个 phase 的 evidence，归档更早 phase 的 evidence。
+规则: 仅保留当前 phase 的 evidence，归档所有更早 phase 的 evidence。
 
 ## 归档生命周期
 

package/references/execution-loop.md

@@ -123,7 +123,7 @@ executor 上下文传递协议 (orchestrator → executor):
 阶段完成后，编排器批量更新 state.json:
 - 更新 phase lifecycle → `accepted`
 - 更新 phase_handoff 信息
-- 归档旧 phase 的 evidence (只保留当前 phase 和上一 phase)
+- 归档旧 phase 的 evidence (仅保留当前 phase)
 - 推进 `current_phase` 到下一个 pending phase
 
 **规则:** 只有编排器写 state.json，避免并发竞态。
@@ -133,13 +133,13 @@ executor 上下文传递协议 (orchestrator → executor):
 每次派发子代理前和阶段切换时检查上下文健康度:
 
 ```
-remaining < 35%:
+remaining <= 35%:
   1. 保存完整状态到 state.json
   2. workflow_mode = awaiting_clear
-  3. 输出: "上下文剩余 <35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
+  3. 输出: "上下文剩余 <=35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
   4. 停止执行
 
-remaining < 25%:
+remaining <= 25%:
   1. 紧急保存状态到 state.json
   2. workflow_mode = awaiting_clear
   3. 输出: "上下文即将耗尽，已保存进度。请立即执行 /clear 然后 /gsd:resume"

package/src/schema.js

@@ -33,9 +33,11 @@ export const PHASE_LIFECYCLE = {
   reviewing:  ['accepted', 'active'],
   accepted:   [],
   blocked:    ['active'],
-  failed:     [],
+  failed:     ['active'],  // H-3: Allow recovery from failed state (gated behind explicit user action)
 };
 
+export const TASK_LEVELS = ['L0', 'L1', 'L2', 'L3'];
+
 export const PHASE_REVIEW_STATUS = ['pending', 'reviewing', 'accepted', 'rework_required'];
 
 export const CANONICAL_FIELDS = [
@@ -223,6 +225,17 @@ export function validateStateUpdate(state, updates) {
       case 'evidence':
         if (!isPlainObject(updates.evidence)) {
           errors.push('evidence must be an object');
+        } else {
+          // M-5: Validate evidence entry structure
+          for (const [id, entry] of Object.entries(updates.evidence)) {
+            if (!isPlainObject(entry)) {
+              errors.push(`evidence["${id}"] must be an object`);
+              continue;
+            }
+            if (typeof entry.scope !== 'string' || entry.scope.length === 0) {
+              errors.push(`evidence["${id}"].scope must be a non-empty string`);
+            }
+          }
         }
         break;
       case 'research':
@@ -235,6 +248,14 @@ export function validateStateUpdate(state, updates) {
     }
   }
 
+  // M-4: Cross-field check — current_phase ≤ total_phases (skip degenerate 0-phase case)
+  const effectivePhase = 'current_phase' in updates ? updates.current_phase : state.current_phase;
+  const effectiveTotal = 'total_phases' in updates ? updates.total_phases : state.total_phases;
+  if (Number.isFinite(effectivePhase) && Number.isFinite(effectiveTotal)
+      && effectiveTotal > 0 && effectivePhase > effectiveTotal) {
+    errors.push(`current_phase (${effectivePhase}) must not exceed total_phases (${effectiveTotal})`);
+  }
+
   return { valid: errors.length === 0, errors };
 }
 
@@ -318,6 +339,22 @@ export function validateState(state) {
   }
   if (!isPlainObject(state.evidence)) {
     errors.push('evidence must be an object');
+  } else {
+    // M-5: Validate evidence entry structure
+    for (const [id, entry] of Object.entries(state.evidence)) {
+      if (!isPlainObject(entry)) {
+        errors.push(`evidence["${id}"] must be an object`);
+        continue;
+      }
+      if (typeof entry.scope !== 'string' || entry.scope.length === 0) {
+        errors.push(`evidence["${id}"].scope must be a non-empty string`);
+      }
+    }
+  }
+  // M-4: Cross-field check — current_phase ≤ total_phases (skip degenerate 0-phase case)
+  if (Number.isFinite(state.current_phase) && Number.isFinite(state.total_phases)
+      && state.total_phases > 0 && state.current_phase > state.total_phases) {
+    errors.push(`current_phase (${state.current_phase}) must not exceed total_phases (${state.total_phases})`);
   }
   if (Array.isArray(state.phases)) {
     if (typeof state.total_phases === 'number' && state.total_phases !== state.phases.length) {
@@ -387,8 +424,8 @@ export function validateState(state) {
         if (!TASK_LIFECYCLE[task.lifecycle]) {
           errors.push(`Task ${task.id}: invalid lifecycle ${task.lifecycle}`);
         }
-        if (typeof task.level !== 'string') {
-          errors.push(`Task ${task.id}: level must be a string`);
+        if (!TASK_LEVELS.includes(task.level)) {
+          errors.push(`Task ${task.id}: level must be one of ${TASK_LEVELS.join(', ')}`);
         }
         if (!Array.isArray(task.requires)) {
           errors.push(`Task ${task.id}: requires must be an array`);
@@ -530,6 +567,33 @@ export function validateDebuggerResult(r) {
   return { valid: errors.length === 0, errors };
 }
 
+// C-1: Schema migration infrastructure
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Migrate state from older schema versions to current.
+ * Apply sequential migrations: v0→v1, v1→v2, etc.
+ * Mutates and returns the state object.
+ */
+export function migrateState(state) {
+  if (!state || typeof state !== 'object') return state;
+  const version = state.schema_version || 0;
+
+  // Migration v0 → v1: add missing fields introduced in v1
+  if (version < 1) {
+    if (!state.evidence) state.evidence = {};
+    if (!state.research) state.research = null;
+    if (!state.decisions) state.decisions = [];
+    if (!state.context) state.context = { last_session: new Date().toISOString(), remaining_percentage: 100 };
+    state.schema_version = 1;
+  }
+
+  // Future migrations go here:
+  // if (version < 2) { migrateV1toV2(state); state.schema_version = 2; }
+
+  return state;
+}
+
 export function createInitialState({ project, phases }) {
   if (!Array.isArray(phases)) {
     return { error: true, message: 'phases must be an array' };
@@ -548,6 +612,38 @@ export function createInitialState({ project, phases }) {
       seenIds.add(id);
     }
   }
+
+  // M-7: Detect circular dependencies within each phase (Kahn's algorithm)
+  for (const [pi, p] of phases.entries()) {
+    const tasks = p.tasks || [];
+    const taskIds = tasks.map((t, ti) => `${pi + 1}.${t.index ?? (ti + 1)}`);
+    const inDegree = new Map(taskIds.map(id => [id, 0]));
+    const adj = new Map(taskIds.map(id => [id, []]));
+    for (const [ti, t] of tasks.entries()) {
+      const id = `${pi + 1}.${t.index ?? (ti + 1)}`;
+      for (const dep of (t.requires || [])) {
+        if (dep.kind === 'task' && inDegree.has(dep.id)) {
+          adj.get(dep.id).push(id);
+          inDegree.set(id, inDegree.get(id) + 1);
+        }
+      }
+    }
+    const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([id]) => id);
+    let sorted = 0;
+    while (queue.length > 0) {
+      const node = queue.shift();
+      sorted++;
+      for (const neighbor of adj.get(node)) {
+        const d = inDegree.get(neighbor) - 1;
+        inDegree.set(neighbor, d);
+        if (d === 0) queue.push(neighbor);
+      }
+    }
+    if (sorted < taskIds.length) {
+      const cycleNodes = [...inDegree.entries()].filter(([, d]) => d > 0).map(([id]) => id);
+      return { error: true, message: `Circular dependency detected in phase ${pi + 1}: ${cycleNodes.join(', ')}` };
+    }
+  }
   return {
     project,
     schema_version: 1,

package/src/tools/orchestrator.js

@@ -15,7 +15,9 @@ import { validateDebuggerResult, validateExecutorResult, validateResearcherResul
 import { getGitHead, getGsdDir } from '../utils.js';
 
 const MAX_DEBUG_RETRY = 3;
+const MAX_RESUME_DEPTH = 3;
 const CONTEXT_RESUME_THRESHOLD = 40;
+const MAX_DECISIONS = 200;
 
 function isTerminalWorkflowMode(workflowMode) {
   return workflowMode === 'completed' || workflowMode === 'failed';
@@ -482,7 +484,11 @@ async function resumeExecutingTask(state, basePath) {
   };
 }
 
-export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
+export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } = {}) {
+  if (_depth >= MAX_RESUME_DEPTH) {
+    return { error: true, message: `resumeWorkflow recursive depth limit exceeded (max ${MAX_RESUME_DEPTH})` };
+  }
+
   const state = await read({ basePath });
   if (state.error) {
     return state;
@@ -540,7 +546,7 @@ export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
           current_review: null,
         });
         if (persistError) return persistError;
-        const resumed = await resumeWorkflow({ basePath });
+        const resumed = await resumeWorkflow({ basePath, _depth: _depth + 1 });
         if (resumed.error) return resumed;
         return { ...resumed, auto_unblocked: autoUnblock.autoUnblocked };
       }
@@ -614,17 +620,48 @@ export async function resumeWorkflow({ basePath = process.cwd() } = {}) {
         total_phases: state.total_phases,
         message: 'Workflow already completed',
       };
-    case 'failed':
+    case 'failed': {
+      const failedPhases = [];
+      const failedTasks = [];
+      for (const phase of state.phases || []) {
+        if (phase.lifecycle === 'failed') failedPhases.push({ id: phase.id, name: phase.name });
+        for (const t of phase.todo || []) {
+          if (t.lifecycle === 'failed') {
+            failedTasks.push({
+              id: t.id,
+              name: t.name,
+              phase_id: phase.id,
+              retry_count: t.retry_count || 0,
+              last_failure_summary: t.last_failure_summary || null,
+              debug_context: t.debug_context || null,
+            });
+          }
+        }
+      }
       return {
         success: true,
-        action: 'noop',
+        action: 'await_recovery_decision',
         workflow_mode: state.workflow_mode,
-        failed_phases: (state.phases || []).filter((phase) => phase.lifecycle === 'failed').map((phase) => phase.id),
-        failed_tasks: (state.phases || []).flatMap((phase) =>
-          (phase.todo || []).filter((task) => task.lifecycle === 'failed').map((task) => task.id)),
-        message: 'Workflow is in failed state',
+        failed_phases: failedPhases,
+        failed_tasks: failedTasks,
+        recovery_options: ['retry_failed', 'skip_failed', 'replan'],
+        message: 'Workflow is in failed state. Recovery options available.',
       };
+    }
     case 'paused_by_user':
+      return {
+        success: true,
+        action: 'await_manual_intervention',
+        workflow_mode: state.workflow_mode,
+        resume_to: state.current_review?.scope === 'phase'
+          ? 'reviewing_phase'
+          : state.current_review?.scope === 'task'
+            ? 'reviewing_task'
+            : 'executing_task',
+        current_review: state.current_review || null,
+        current_task: state.current_task || null,
+        message: 'Project is paused. Confirm to resume execution.',
+      };
     case 'planning':
     case 'reconcile_workspace':
     case 'replan_required':
@@ -660,7 +697,9 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
   }
 
   const decisionEntries = buildDecisionEntries(result.decisions, phase.id, task.id, (state.decisions || []).length);
-  const decisions = [...(state.decisions || []), ...decisionEntries];
+  const allDecisions = [...(state.decisions || []), ...decisionEntries];
+  // H-1: Cap decisions to prevent unbounded growth
+  const decisions = allDecisions.length > MAX_DECISIONS ? allDecisions.slice(-MAX_DECISIONS) : allDecisions;
 
   if (result.outcome === 'checkpointed') {
     const reviewLevel = reclassifyReviewLevel(task, result);

package/src/tools/state.js

@@ -2,7 +2,7 @@
 
 import { join, dirname } from 'node:path';
 import { stat, writeFile, rename, unlink } from 'node:fs/promises';
-import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject, clearGsdDirCache } from '../utils.js';
+import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject, clearGsdDirCache, withFileLock } from '../utils.js';
 import {
   CANONICAL_FIELDS,
   TASK_LIFECYCLE,
@@ -13,16 +13,42 @@ import {
   validateStateUpdate,
   validateTransition,
   createInitialState,
+  migrateState,
 } from '../schema.js';
 import { runAll } from './verify.js';
 
 const RESEARCH_FILES = ['STACK.md', 'ARCHITECTURE.md', 'PITFALLS.md', 'SUMMARY.md'];
 const MAX_EVIDENCE_ENTRIES = 200;
+const MAX_ARCHIVE_ENTRIES = 1000;
+
+// M-10: Structured error codes
+export const ERROR_CODES = {
+  NO_PROJECT_DIR: 'NO_PROJECT_DIR',
+  INVALID_INPUT: 'INVALID_INPUT',
+  VALIDATION_FAILED: 'VALIDATION_FAILED',
+  STATE_EXISTS: 'STATE_EXISTS',
+  NOT_FOUND: 'NOT_FOUND',
+  TERMINAL_STATE: 'TERMINAL_STATE',
+  TRANSITION_ERROR: 'TRANSITION_ERROR',
+  HANDOFF_GATE: 'HANDOFF_GATE',
+};
 
 // 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;
+
+export function setLockPath(lockPath) {
+  _fileLockPath = lockPath;
+}
+
 function withStateLock(fn) {
-  const p = _mutationQueue.then(fn);
+  const p = _mutationQueue.then(() => {
+    if (_fileLockPath) {
+      return withFileLock(_fileLockPath, fn);
+    }
+    return fn();
+  });
   _mutationQueue = p.catch(() => {});
   return p;
 }
@@ -47,10 +73,10 @@ function normalizeResearchArtifacts(artifacts) {
  */
 export async function init({ project, phases, research, force = false, basePath = process.cwd() }) {
   if (!project || typeof project !== 'string') {
-    return { error: true, message: 'project must be a non-empty string' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'project must be a non-empty string' };
   }
   if (!Array.isArray(phases)) {
-    return { error: true, message: 'phases must be an array' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'phases must be an array' };
   }
   const gsdDir = join(basePath, '.gsd');
   const statePath = join(gsdDir, 'state.json');
@@ -60,8 +86,16 @@ export async function init({ project, phases, research, force = false, basePath
     if (!force) {
       try {
         await stat(statePath);
-        return { error: true, message: 'state.json already exists; pass force: true to reinitialize' };
+        return { error: true, code: ERROR_CODES.STATE_EXISTS, message: 'state.json already exists; pass force: true to reinitialize' };
       } catch {} // File doesn't exist, proceed
+    } else {
+      // H-8: Backup existing state before force overwrite
+      try {
+        const existing = await readJson(statePath);
+        if (existing.ok) {
+          await writeJson(join(gsdDir, 'state.json.bak'), existing.data);
+        }
+      } catch {} // No existing state to backup
     }
 
     const phasesDir = join(gsdDir, 'phases');
@@ -105,17 +139,25 @@ export async function init({ project, phases, research, force = false, basePath
 /**
  * Read state.json, optionally filtering to specific fields.
  */
-export async function read({ fields, basePath = process.cwd() } = {}) {
+export async function read({ fields, basePath = process.cwd(), validate = false } = {}) {
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
 
   const result = await readJson(statePath);
   if (!result.ok) {
-    return { error: true, message: result.error };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
+  }
+  const state = migrateState(result.data);
+
+  // H-7: Optional semantic validation on read
+  if (validate) {
+    const validation = validateState(state);
+    if (!validation.valid) {
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `State validation failed: ${validation.errors.join('; ')}` };
+    }
   }
-  const state = result.data;
 
   if (fields && Array.isArray(fields) && fields.length > 0) {
     const filtered = {};
@@ -135,7 +177,7 @@ export async function read({ fields, basePath = process.cwd() } = {}) {
  */
 export async function update({ updates, basePath = process.cwd() } = {}) {
   if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
-    return { error: true, message: 'updates must be a non-null object' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'updates must be a non-null object' };
   }
   // Guard: reject non-canonical fields
   const nonCanonical = Object.keys(updates).filter(
@@ -144,22 +186,34 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
   if (nonCanonical.length > 0) {
     return {
       error: true,
+      code: ERROR_CODES.INVALID_INPUT,
       message: `Non-canonical fields rejected: ${nonCanonical.join(', ')}`,
     };
   }
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
+  // C-2: Initialize cross-process lock path on first mutation
+  if (!_fileLockPath) _fileLockPath = join(dirname(statePath), 'state.lock');
 
   return withStateLock(async () => {
     const result = await readJson(statePath);
     if (!result.ok) {
-      return { error: true, message: result.error };
+      return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: result.error };
     }
     const state = result.data;
 
+    // Guard: reject workflow_mode changes FROM terminal states
+    if (updates.workflow_mode) {
+      const currentMode = state.workflow_mode;
+      if ((currentMode === 'completed' || currentMode === 'failed')
+          && updates.workflow_mode !== currentMode) {
+        return { error: true, code: ERROR_CODES.TERMINAL_STATE, message: `Cannot change workflow_mode from terminal state '${currentMode}'` };
+      }
+    }
+
     // Validate lifecycle transitions before merging
     if (updates.phases && Array.isArray(updates.phases)) {
       for (const newPhase of updates.phases) {
@@ -169,7 +223,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
         // Check phase lifecycle transition
         if (newPhase.lifecycle && newPhase.lifecycle !== oldPhase.lifecycle) {
           const tr = validateTransition('phase', oldPhase.lifecycle, newPhase.lifecycle);
-          if (!tr.valid) return { error: true, message: tr.error };
+          if (!tr.valid) return { error: true, code: ERROR_CODES.TRANSITION_ERROR, message: tr.error };
         }
 
         // Check task lifecycle transitions
@@ -179,7 +233,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
             if (!oldTask) continue;
             if (newTask.lifecycle && newTask.lifecycle !== oldTask.lifecycle) {
               const tr = validateTransition('task', oldTask.lifecycle, newTask.lifecycle);
-              if (!tr.valid) return { error: true, message: tr.error };
+              if (!tr.valid) return { error: true, code: ERROR_CODES.TRANSITION_ERROR, message: tr.error };
             }
           }
         }
@@ -229,6 +283,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
     if (!validation.valid) {
       return {
         error: true,
+        code: ERROR_CODES.VALIDATION_FAILED,
         message: `Validation failed: ${validation.errors.join('; ')}`,
       };
     }
@@ -266,20 +321,20 @@ export async function phaseComplete({
   direction_ok,
 } = {}) {
   if (typeof phase_id !== 'number') {
-    return { error: true, message: 'phase_id must be a number' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'phase_id must be a number' };
   }
   if (verification != null && (typeof verification !== 'object' || Array.isArray(verification))) {
-    return { error: true, message: 'verification must be an object when provided' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'verification must be an object when provided' };
   }
   if (typeof run_verify !== 'boolean') {
-    return { error: true, message: 'run_verify must be a boolean' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'run_verify must be a boolean' };
   }
   if (direction_ok !== undefined && typeof direction_ok !== 'boolean') {
-    return { error: true, message: 'direction_ok must be a boolean when provided' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'direction_ok must be a boolean when provided' };
   }
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
 
   return withStateLock(async () => {
@@ -291,13 +346,13 @@ export async function phaseComplete({
 
     const phase = state.phases.find((p) => p.id === phase_id);
     if (!phase) {
-      return { error: true, message: `Phase ${phase_id} not found` };
+      return { error: true, code: ERROR_CODES.NOT_FOUND, message: `Phase ${phase_id} not found` };
     }
     if (!Array.isArray(phase.todo)) {
-      return { error: true, message: `Phase ${phase_id} has invalid todo list` };
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Phase ${phase_id} has invalid todo list` };
     }
     if (!phase.phase_handoff || typeof phase.phase_handoff !== 'object') {
-      return { error: true, message: `Phase ${phase_id} is missing phase_handoff metadata` };
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Phase ${phase_id} is missing phase_handoff metadata` };
     }
 
     // Validate phase lifecycle transition FIRST (fail-fast) [I-4]
@@ -307,7 +362,7 @@ export async function phaseComplete({
       'accepted',
     );
     if (!transitionResult.valid) {
-      return { error: true, message: transitionResult.error };
+      return { error: true, code: ERROR_CODES.TRANSITION_ERROR, message: transitionResult.error };
     }
 
     // Check handoff gate: all tasks must be accepted
@@ -315,6 +370,7 @@ export async function phaseComplete({
     if (pendingTasks.length > 0) {
       return {
         error: true,
+        code: ERROR_CODES.HANDOFF_GATE,
         message: `Handoff gate not met: ${pendingTasks.length} task(s) not accepted — ${pendingTasks.map((t) => `${t.id}:${t.lifecycle}`).join(', ')}`,
       };
     }
@@ -323,6 +379,7 @@ export async function phaseComplete({
     if (phase.phase_handoff.critical_issues_open > 0) {
       return {
         error: true,
+        code: ERROR_CODES.HANDOFF_GATE,
         message: `Handoff gate not met: ${phase.phase_handoff.critical_issues_open} critical issue(s) open`,
       };
     }
@@ -332,6 +389,7 @@ export async function phaseComplete({
     if (!reviewPassed) {
       return {
         error: true,
+        code: ERROR_CODES.HANDOFF_GATE,
         message: 'Handoff gate not met: required reviews not passed',
       };
     }
@@ -343,6 +401,7 @@ export async function phaseComplete({
     if (!testsPassed) {
       return {
         error: true,
+        code: ERROR_CODES.HANDOFF_GATE,
         message: `Handoff gate not met: verification checks failed — ${verificationSummary(verificationResult)}`,
       };
     }
@@ -360,7 +419,7 @@ export async function phaseComplete({
       phase.phase_handoff.direction_ok = false;
       const driftValidation = validateState(state);
       if (!driftValidation.valid) {
-        return { error: true, message: `Validation failed: ${driftValidation.errors.join('; ')}` };
+        return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Validation failed: ${driftValidation.errors.join('; ')}` };
       }
       await writeJson(statePath, state);
       return {
@@ -383,11 +442,15 @@ export async function phaseComplete({
     // Increment current_phase if this was the active phase
     if (state.current_phase === phase_id && phase_id < state.total_phases) {
       state.current_phase = phase_id + 1;
-      // Activate the next phase
+      // Activate the next phase (M-3: use validateTransition for consistency)
       const nextPhase = state.phases.find((p) => p.id === state.current_phase);
-      if (nextPhase && nextPhase.lifecycle === 'pending') {
-        nextPhase.lifecycle = 'active';
+      if (nextPhase) {
+        const nextTr = validateTransition('phase', nextPhase.lifecycle, 'active');
+        if (nextTr.valid) nextPhase.lifecycle = 'active';
       }
+    } else if (state.current_phase === phase_id && phase_id >= state.total_phases) {
+      // Final phase completed — mark workflow as completed
+      state.workflow_mode = 'completed';
     }
 
     // Update git_head to current commit
@@ -408,18 +471,18 @@ export async function phaseComplete({
 export async function addEvidence({ id, data, basePath = process.cwd() }) {
   // I-8: Validate inputs
   if (!id || typeof id !== 'string') {
-    return { error: true, message: 'id must be a non-empty string' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'id must be a non-empty string' };
   }
   if (!data || typeof data !== 'object' || Array.isArray(data)) {
-    return { error: true, message: 'data must be a non-null object' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'data must be a non-null object' };
   }
   if (typeof data.scope !== 'string') {
-    return { error: true, message: 'data.scope must be a string' };
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'data.scope must be a string' };
   }
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
 
   return withStateLock(async () => {
@@ -454,13 +517,12 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
 async function _pruneEvidenceFromState(state, currentPhase, gsdDir) {
   if (!state.evidence) return 0;
 
-  const threshold = currentPhase - 1;
   const toArchive = {};
   const toKeep = {};
 
   for (const [id, entry] of Object.entries(state.evidence)) {
     const phaseNum = parseScopePhase(entry.scope);
-    if (phaseNum !== null && phaseNum < threshold) {
+    if (phaseNum !== null && phaseNum < currentPhase) {
       toArchive[id] = entry;
     } else {
       toKeep[id] = entry;
@@ -474,8 +536,15 @@ async function _pruneEvidenceFromState(state, currentPhase, gsdDir) {
     const existing = await readJson(archivePath);
     const archive = existing.ok ? existing.data : {};
     Object.assign(archive, toArchive);
-    await writeJson(archivePath, archive);
 
+    // H-2: Cap archive size to prevent unbounded growth
+    const archiveKeys = Object.keys(archive);
+    if (archiveKeys.length > MAX_ARCHIVE_ENTRIES) {
+      const toRemove = archiveKeys.slice(0, archiveKeys.length - MAX_ARCHIVE_ENTRIES);
+      for (const key of toRemove) delete archive[key];
+    }
+
+    await writeJson(archivePath, archive);
     state.evidence = toKeep;
   }
 
@@ -483,13 +552,16 @@ async function _pruneEvidenceFromState(state, currentPhase, gsdDir) {
 }
 
 /**
- * Prune evidence: archive entries from phases older than currentPhase - 1.
+ * Prune evidence: archive entries from phases before currentPhase (keep only current phase).
  * Scope format is "task:X.Y" where X is the phase number.
  */
 export async function pruneEvidence({ currentPhase, basePath = process.cwd() }) {
+  if (typeof currentPhase !== 'number' || !Number.isFinite(currentPhase)) {
+    return { error: true, code: ERROR_CODES.INVALID_INPUT, message: 'currentPhase must be a finite number' };
+  }
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
 
   return withStateLock(async () => {
@@ -874,7 +946,7 @@ export function applyResearchRefresh(state, newResearch) {
 export async function storeResearch({ result, artifacts, decision_index, basePath = process.cwd() } = {}) {
   const resultValidation = validateResearcherResult(result || {});
   if (!resultValidation.valid) {
-    return { error: true, message: `Invalid researcher result: ${resultValidation.errors.join('; ')}` };
+    return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Invalid researcher result: ${resultValidation.errors.join('; ')}` };
   }
 
   const artifactsValidation = validateResearchArtifacts(artifacts, {
@@ -883,17 +955,17 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     expiresAt: result.expires_at,
   });
   if (!artifactsValidation.valid) {
-    return { error: true, message: `Invalid research artifacts: ${artifactsValidation.errors.join('; ')}` };
+    return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Invalid research artifacts: ${artifactsValidation.errors.join('; ')}` };
   }
 
   const decisionIndexValidation = validateResearchDecisionIndex(decision_index, result.decision_ids);
   if (!decisionIndexValidation.valid) {
-    return { error: true, message: `Invalid research decision_index: ${decisionIndexValidation.errors.join('; ')}` };
+    return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `Invalid research decision_index: ${decisionIndexValidation.errors.join('; ')}` };
   }
 
   const statePath = await getStatePath(basePath);
   if (!statePath) {
-    return { error: true, message: 'No .gsd directory found' };
+    return { error: true, code: ERROR_CODES.NO_PROJECT_DIR, message: 'No .gsd directory found' };
   }
 
   return withStateLock(async () => {
@@ -930,11 +1002,10 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
       throw err;
     }
 
-    const { decision_index: _, ...nextResearchBase } = {
+    const nextResearchBase = {
       volatility: result.volatility,
       expires_at: result.expires_at,
       sources: result.sources,
-      decision_index,
       files: RESEARCH_FILES,
       updated_at: new Date().toISOString(),
     };
@@ -957,7 +1028,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
 
     const validation = validateState(state);
     if (!validation.valid) {
-      return { error: true, message: `State validation failed: ${validation.errors.join('; ')}` };
+      return { error: true, code: ERROR_CODES.VALIDATION_FAILED, message: `State validation failed: ${validation.errors.join('; ')}` };
     }
 
     await writeJson(statePath, state);

package/src/utils.js

@@ -23,7 +23,7 @@ export async function getGsdDir(startDir = process.cwd()) {
     } catch {}
     const parent = dirname(dir);
     if (parent === dir) {
-      _gsdDirCache.set(resolved, null);
+      // H-9: Don't cache negative results — .gsd may be created later by init()
       return null;
     }
     dir = parent;
@@ -52,6 +52,52 @@ export async function getGitHead(cwd = process.cwd()) {
   }
 }
 
+// C-2: Advisory file lock for cross-process serialization
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100; // 5 seconds total
+
+/**
+ * Execute fn while holding an advisory file lock.
+ * Uses O_CREAT|O_EXCL (via 'wx' flag) for atomic lock acquisition.
+ * Stale locks (>10s) are automatically broken.
+ * Falls through without locking on non-EEXIST errors (e.g., read-only fs).
+ */
+export async function withFileLock(lockPath, fn) {
+  let acquired = false;
+  for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+    try {
+      await writeFile(lockPath, String(process.pid), { flag: 'wx' });
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        try {
+          const s = await stat(lockPath);
+          if (Date.now() - s.mtimeMs > LOCK_STALE_MS) {
+            try { await unlink(lockPath); } catch {}
+            continue;
+          }
+        } catch {
+          // stat failed — lock may have been released between checks
+          continue;
+        }
+        await new Promise(r => setTimeout(r, LOCK_RETRY_MS));
+      } else {
+        break; // Non-EEXIST error — proceed without lock
+      }
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    if (acquired) {
+      try { await unlink(lockPath); } catch {}
+    }
+  }
+}
+
 let _tmpCounter = 0;
 function tmpPath(filePath) {
   return `${filePath}.${process.pid}-${Date.now()}-${_tmpCounter++}.tmp`;