gsd-lite 0.3.6 → 0.3.7

package/hooks/gsd-statusline.cjs

@@ -16,8 +16,7 @@ function findGsdDir(startDir) {
   while (true) {
     const candidate = path.join(dir, '.gsd');
     try {
-      fs.statSync(candidate);
-      return candidate;
+      if (fs.statSync(candidate).isDirectory()) return candidate;
     } catch {
       const parent = path.dirname(dir);
       if (parent === dir) return null; // reached filesystem root
@@ -44,7 +43,7 @@ process.stdin.on('end', () => {
     let task = '';
     let hasGsd = false;
     const gsdDir = findGsdDir(cwd);
-    try {
+    if (gsdDir) try {
       const state = JSON.parse(fs.readFileSync(path.join(gsdDir, 'state.json'), 'utf8'));
       hasGsd = true;
       if (state.current_task && state.current_phase) {

package/package.json

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

package/src/schema.js

@@ -33,7 +33,7 @@ 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'];
@@ -225,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':
@@ -237,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 };
 }
 
@@ -320,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) {
@@ -532,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' };
@@ -550,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

@@ -17,6 +17,7 @@ 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';
@@ -696,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,19 +186,22 @@ 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;
 
@@ -165,7 +210,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
       const currentMode = state.workflow_mode;
       if ((currentMode === 'completed' || currentMode === 'failed')
           && updates.workflow_mode !== currentMode) {
-        return { error: true, message: `Cannot change workflow_mode from terminal state '${currentMode}'` };
+        return { error: true, code: ERROR_CODES.TERMINAL_STATE, message: `Cannot change workflow_mode from terminal state '${currentMode}'` };
       }
     }
 
@@ -178,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
@@ -188,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 };
             }
           }
         }
@@ -238,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('; ')}`,
       };
     }
@@ -275,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 () => {
@@ -300,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]
@@ -316,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
@@ -324,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(', ')}`,
       };
     }
@@ -332,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`,
       };
     }
@@ -341,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',
       };
     }
@@ -352,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)}`,
       };
     }
@@ -369,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 {
@@ -392,10 +442,11 @@ 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
@@ -420,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 () => {
@@ -485,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;
   }
 
@@ -498,9 +556,12 @@ async function _pruneEvidenceFromState(state, currentPhase, gsdDir) {
  * 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 () => {
@@ -885,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, {
@@ -894,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 () => {
@@ -967,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`;