gsd-lite 0.3.1 → 0.3.5

package/src/tools/state.js

@@ -1,8 +1,8 @@
 // State CRUD tools
 
 import { join, dirname } from 'node:path';
-import { stat } from 'node:fs/promises';
-import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject } from '../utils.js';
+import { stat, writeFile, rename, unlink } from 'node:fs/promises';
+import { ensureDir, readJson, writeJson, writeAtomic, getStatePath, getGitHead, isPlainObject, clearGsdDirCache } from '../utils.js';
 import {
   CANONICAL_FIELDS,
   TASK_LIFECYCLE,
@@ -10,12 +10,14 @@ import {
   validateResearchDecisionIndex,
   validateResearcherResult,
   validateState,
+  validateStateUpdate,
   validateTransition,
   createInitialState,
 } from '../schema.js';
 import { runAll } from './verify.js';
 
 const RESEARCH_FILES = ['STACK.md', 'ARCHITECTURE.md', 'PITFALLS.md', 'SUMMARY.md'];
+const MAX_EVIDENCE_ENTRIES = 200;
 
 // C-1: Serialize all state mutations to prevent TOCTOU races
 let _mutationQueue = Promise.resolve();
@@ -53,55 +55,58 @@ export async function init({ project, phases, research, force = false, basePath
   const gsdDir = join(basePath, '.gsd');
   const statePath = join(gsdDir, 'state.json');
 
-  // Guard: reject re-initialization unless force is set
-  if (!force) {
-    try {
-      await stat(statePath);
-      return { error: true, message: 'state.json already exists; pass force: true to reinitialize' };
-    } catch {} // File doesn't exist, proceed
-  }
-
-  const phasesDir = join(gsdDir, 'phases');
+  return withStateLock(async () => {
+    // Guard: reject re-initialization unless force is set
+    if (!force) {
+      try {
+        await stat(statePath);
+        return { error: true, message: 'state.json already exists; pass force: true to reinitialize' };
+      } catch {} // File doesn't exist, proceed
+    }
 
-  await ensureDir(phasesDir);
-  if (research) {
-    await ensureDir(join(gsdDir, 'research'));
-  }
+    const phasesDir = join(gsdDir, 'phases');
 
-  const state = createInitialState({ project, phases });
-  if (state.error) return state;
-  state.git_head = await getGitHead(basePath);
+    clearGsdDirCache(); // Invalidate cache since we're creating .gsd/
+    await ensureDir(phasesDir);
+    if (research) {
+      await ensureDir(join(gsdDir, 'research'));
+    }
 
-  // Create plan.md placeholder (atomic write)
-  await writeAtomic(
-    join(gsdDir, 'plan.md'),
-    `# ${project}\n\nPlan placeholder — populate during planning phase.\n`,
-  );
+    const state = createInitialState({ project, phases });
+    if (state.error) return state;
+    state.git_head = await getGitHead(basePath);
 
-  // Create phase placeholder .md files (atomic writes)
-  for (const phase of state.phases) {
+    // Create plan.md placeholder (atomic write)
     await writeAtomic(
-      join(phasesDir, `phase-${phase.id}.md`),
-      `# Phase ${phase.id}: ${phase.name}\n\nTasks and details go here.\n`,
+      join(gsdDir, 'plan.md'),
+      `# ${project}\n\nPlan placeholder — populate during planning phase.\n`,
     );
-  }
 
-  const trackedFiles = [
-    join(gsdDir, 'plan.md'),
-    ...state.phases.map((phase) => join(phasesDir, `phase-${phase.id}.md`)),
-  ];
-  const mtimes = await Promise.all(trackedFiles.map(async (filePath) => (await stat(filePath)).mtimeMs));
-  state.context.last_session = new Date(Math.ceil(Math.max(...mtimes))).toISOString();
-  await writeJson(join(gsdDir, 'state.json'), state);
+    // Create phase placeholder .md files (atomic writes)
+    for (const phase of state.phases) {
+      await writeAtomic(
+        join(phasesDir, `phase-${phase.id}.md`),
+        `# Phase ${phase.id}: ${phase.name}\n\nTasks and details go here.\n`,
+      );
+    }
 
-  return { success: true };
+    const trackedFiles = [
+      join(gsdDir, 'plan.md'),
+      ...state.phases.map((phase) => join(phasesDir, `phase-${phase.id}.md`)),
+    ];
+    const mtimes = await Promise.all(trackedFiles.map(async (filePath) => (await stat(filePath)).mtimeMs));
+    state.context.last_session = new Date(Math.ceil(Math.max(...mtimes))).toISOString();
+    await writeJson(statePath, state);
+
+    return { success: true };
+  });
 }
 
 /**
  * Read state.json, optionally filtering to specific fields.
  */
 export async function read({ fields, basePath = process.cwd() } = {}) {
-  const statePath = getStatePath(basePath);
+  const statePath = await getStatePath(basePath);
   if (!statePath) {
     return { error: true, message: 'No .gsd directory found' };
   }
@@ -143,7 +148,7 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
     };
   }
 
-  const statePath = getStatePath(basePath);
+  const statePath = await getStatePath(basePath);
   if (!statePath) {
     return { error: true, message: 'No .gsd directory found' };
   }
@@ -217,8 +222,10 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
       }
     }
 
-    // Validate full state after merge
-    const validation = validateState(merged);
+    // Use incremental validation for simple updates (no phases changes)
+    const validation = !updates.phases
+      ? validateStateUpdate(state, updates)
+      : validateState(merged);
     if (!validation.valid) {
       return {
         error: true,
@@ -236,7 +243,6 @@ export async function update({ updates, basePath = process.cwd() } = {}) {
  */
 function verificationPassed(verification) {
   if (!verification || typeof verification !== 'object') return false;
-  if ('passed' in verification) return verification.passed === true;
   return ['lint', 'typecheck', 'test'].every((key) => (
     verification[key]
     && typeof verification[key].exit_code === 'number'
@@ -271,7 +277,7 @@ export async function phaseComplete({
   if (direction_ok !== undefined && typeof direction_ok !== 'boolean') {
     return { error: true, message: 'direction_ok must be a boolean when provided' };
   }
-  const statePath = getStatePath(basePath);
+  const statePath = await getStatePath(basePath);
   if (!statePath) {
     return { error: true, message: 'No .gsd directory found' };
   }
@@ -358,10 +364,11 @@ export async function phaseComplete({
       }
       await writeJson(statePath, state);
       return {
-        error: true,
-        message: 'Handoff gate not met: direction drift detected, awaiting user decision',
+        success: true,
+        action: 'direction_drift',
         workflow_mode: 'awaiting_user',
         phase_id: phase.id,
+        message: 'Direction drift detected; awaiting user decision before phase can complete',
       };
     }
 
@@ -410,7 +417,7 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
     return { error: true, message: 'data.scope must be a string' };
   }
 
-  const statePath = getStatePath(basePath);
+  const statePath = await getStatePath(basePath);
   if (!statePath) {
     return { error: true, message: 'No .gsd directory found' };
   }
@@ -427,6 +434,14 @@ export async function addEvidence({ id, data, basePath = process.cwd() }) {
     }
 
     state.evidence[id] = data;
+
+    // Auto-prune when evidence exceeds limit
+    const entries = Object.keys(state.evidence);
+    if (entries.length > MAX_EVIDENCE_ENTRIES) {
+      const gsdDir = dirname(statePath);
+      await _pruneEvidenceFromState(state, state.current_phase, gsdDir);
+    }
+
     await writeJson(statePath, state);
     return { success: true };
   });
@@ -472,7 +487,7 @@ 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() }) {
-  const statePath = getStatePath(basePath);
+  const statePath = await getStatePath(basePath);
   if (!statePath) {
     return { error: true, message: 'No .gsd directory found' };
   }
@@ -521,6 +536,11 @@ export function selectRunnableTask(phase, state, { maxRetry = DEFAULT_MAX_RETRY
   if (!phase || !Array.isArray(phase.todo)) {
     return { error: true, message: 'Phase todo must be an array' };
   }
+  // D-4: Zero-task phase — immediately trigger review so phase can advance
+  if (phase.todo.length === 0) {
+    return { mode: 'trigger_review' };
+  }
+
   const runnableTasks = [];
 
   for (const task of phase.todo) {
@@ -723,7 +743,8 @@ export function reclassifyReviewLevel(task, executorResult) {
 
   // Check for explicit [LEVEL-UP] in decisions
   const hasLevelUp = (executorResult.decisions || []).some(d =>
-    typeof d === 'string' && d.includes('[LEVEL-UP]')
+    (typeof d === 'string' && d.includes('[LEVEL-UP]'))
+    || (d && typeof d === 'object' && typeof d.summary === 'string' && d.summary.includes('[LEVEL-UP]'))
   );
   if (hasLevelUp) return 'L2';
 
@@ -792,6 +813,9 @@ export function applyResearchRefresh(state, newResearch) {
   const oldIndex = state.research?.decision_index || {};
   const newIndex = newResearch?.decision_index || {};
 
+  // Copy-on-write: build merged index without mutating oldIndex
+  const mergedIndex = { ...oldIndex };
+
   // Collect IDs of decisions that changed or were removed
   const invalidatedIds = new Set();
 
@@ -800,11 +824,11 @@ export function applyResearchRefresh(state, newResearch) {
     if (id in newIndex) {
       const newDecision = newIndex[id];
       if (oldDecision.summary === newDecision.summary) {
-        // Rule 1: same conclusion — update metadata in place
-        Object.assign(oldIndex[id], newDecision);
+        // Rule 1: same conclusion — update metadata
+        mergedIndex[id] = { ...oldDecision, ...newDecision };
       } else {
         // Rule 2: changed conclusion — replace and invalidate
-        oldIndex[id] = newDecision;
+        mergedIndex[id] = newDecision;
         invalidatedIds.add(id);
       }
     } else {
@@ -817,13 +841,13 @@ export function applyResearchRefresh(state, newResearch) {
   // Rule 4: brand new IDs — just add them
   for (const [id, newDecision] of Object.entries(newIndex)) {
     if (!(id in oldIndex)) {
-      oldIndex[id] = newDecision;
+      mergedIndex[id] = newDecision;
     }
   }
 
-  // Ensure decision_index is set on state
+  // Assign merged index to state (atomic replacement)
   if (!state.research) state.research = {};
-  state.research.decision_index = oldIndex;
+  state.research.decision_index = mergedIndex;
 
   // C-3: Only invalidate tasks whose lifecycle allows needs_revalidation
   if (invalidatedIds.size > 0) {
@@ -867,7 +891,7 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     return { error: true, message: `Invalid research decision_index: ${decisionIndexValidation.errors.join('; ')}` };
   }
 
-  const statePath = getStatePath(basePath);
+  const statePath = await getStatePath(basePath);
   if (!statePath) {
     return { error: true, message: 'No .gsd directory found' };
   }
@@ -883,12 +907,30 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     const researchDir = join(gsdDir, 'research');
     await ensureDir(researchDir);
 
+    // Atomic multi-file write: write all artifacts first, then rename in batch
     const normalizedArtifacts = normalizeResearchArtifacts(artifacts);
-    for (const fileName of RESEARCH_FILES) {
-      await writeAtomic(join(researchDir, fileName), normalizedArtifacts[fileName]);
+    const tmpSuffix = `.${process.pid}-${Date.now()}.tmp`;
+    const tmpPaths = [];
+    try {
+      for (const fileName of RESEARCH_FILES) {
+        const finalPath = join(researchDir, fileName);
+        const tmpFile = finalPath + tmpSuffix;
+        tmpPaths.push({ tmp: tmpFile, final: finalPath });
+        await writeFile(tmpFile, normalizedArtifacts[fileName], 'utf-8');
+      }
+      // All writes succeeded — rename in batch
+      for (const { tmp, final: finalPath } of tmpPaths) {
+        await rename(tmp, finalPath);
+      }
+    } catch (err) {
+      // Cleanup any temp files on failure
+      for (const { tmp } of tmpPaths) {
+        try { await unlink(tmp); } catch {}
+      }
+      throw err;
     }
 
-    const nextResearch = {
+    const { decision_index: _, ...nextResearchBase } = {
       volatility: result.volatility,
       expires_at: result.expires_at,
       sources: result.sources,
@@ -898,13 +940,15 @@ export async function storeResearch({ result, artifacts, decision_index, basePat
     };
 
     const refreshResult = state.research
-      ? applyResearchRefresh(state, nextResearch)
+      ? applyResearchRefresh(state, { ...nextResearchBase, decision_index })
       : { warnings: [] };
 
+    // After applyResearchRefresh, state.research.decision_index is the merged result
+    const mergedDecisionIndex = state.research?.decision_index || decision_index;
     state.research = {
       ...(state.research || {}),
-      ...nextResearch,
-      decision_index: state.research?.decision_index || decision_index,
+      ...nextResearchBase,
+      decision_index: mergedDecisionIndex,
     };
 
     if (state.workflow_mode === 'research_refresh_needed') {

package/src/tools/verify.js

@@ -37,7 +37,7 @@ async function runCommand(command, args, cwd) {
     return { exit_code: 0, summary: summarizeOutput(stdout, 3) };
   } catch (err) {
     return {
-      exit_code: typeof err.code === 'number' ? err.code : (err.status || 1),
+      exit_code: err.status ?? (typeof err.code === 'number' ? err.code : 1),
       summary: summarizeOutput(err.stderr || err.stdout || err.message || '', 5),
     };
   }
@@ -65,13 +65,16 @@ export async function runLint(pm, cwd) {
   return runCommand(pm, ['run', 'lint'], cwd);
 }
 
-export async function runTypeCheck(cwd) {
+export async function runTypeCheck(pm, cwd) {
   // M-8: Only run tsc if tsconfig.json exists
   try {
     await stat(join(cwd, 'tsconfig.json'));
   } catch {
     return { exit_code: 0, summary: 'skipped: no tsconfig.json found' };
   }
+  if (pm === 'pnpm') return runCommand('pnpm', ['exec', 'tsc', '--noEmit'], cwd);
+  if (pm === 'yarn') return runCommand('yarn', ['tsc', '--noEmit'], cwd);
+  if (pm === 'bun') return runCommand('bun', ['run', 'tsc', '--noEmit'], cwd);
   return runCommand('npx', ['tsc', '--noEmit'], cwd);
 }
 
@@ -83,7 +86,7 @@ export async function runAll(cwd = process.cwd()) {
   }
   const [lint, typecheck, test] = await Promise.all([
     runLint(pm, cwd),
-    runTypeCheck(cwd),
+    runTypeCheck(pm, cwd),
     runTests(pm, cwd),
   ]);
   return { lint, typecheck, test };

package/src/utils.js

@@ -1,27 +1,41 @@
-import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
-import { statSync } from 'node:fs';
+import { readFile, writeFile, rename, mkdir, unlink, stat } from 'node:fs/promises';
 import { join, dirname, resolve } from 'node:path';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFileCb);
 
-export function getGsdDir(startDir = process.cwd()) {
-  let dir = resolve(startDir);
+const _gsdDirCache = new Map();
+
+export async function getGsdDir(startDir = process.cwd()) {
+  const resolved = resolve(startDir);
+  if (_gsdDirCache.has(resolved)) return _gsdDirCache.get(resolved);
+
+  let dir = resolved;
   while (true) {
     const candidate = join(dir, '.gsd');
     try {
-      const s = statSync(candidate);
-      if (s.isDirectory()) return candidate;
+      const s = await stat(candidate);
+      if (s.isDirectory()) {
+        _gsdDirCache.set(resolved, candidate);
+        return candidate;
+      }
     } catch {}
     const parent = dirname(dir);
-    if (parent === dir) return null;
+    if (parent === dir) {
+      _gsdDirCache.set(resolved, null);
+      return null;
+    }
     dir = parent;
   }
 }
 
-export function getStatePath(startDir = process.cwd()) {
-  const gsdDir = getGsdDir(startDir);
+export function clearGsdDirCache() {
+  _gsdDirCache.clear();
+}
+
+export async function getStatePath(startDir = process.cwd()) {
+  const gsdDir = await getGsdDir(startDir);
   if (!gsdDir) return null;
   return join(gsdDir, 'state.json');
 }
@@ -38,8 +52,15 @@ export async function getGitHead(cwd = process.cwd()) {
   }
 }
 
+let _tmpCounter = 0;
+function tmpPath(filePath) {
+  return `${filePath}.${process.pid}-${Date.now()}-${_tmpCounter++}.tmp`;
+}
+
 export function isPlainObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }
 
 export async function ensureDir(dirPath) {
@@ -63,13 +84,13 @@ export async function readJson(filePath) {
  * Atomically write JSON data (write to .tmp then rename).
  */
 export async function writeJson(filePath, data) {
-  const tmpPath = `${filePath}.${process.pid}-${Date.now()}.tmp`;
+  const tmp = tmpPath(filePath);
   await ensureDir(dirname(filePath));
   try {
-    await writeFile(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-    await rename(tmpPath, filePath);
+    await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    await rename(tmp, filePath);
   } catch (err) {
-    try { await unlink(tmpPath); } catch {}
+    try { await unlink(tmp); } catch {}
     throw err;
   }
 }
@@ -78,13 +99,13 @@ export async function writeJson(filePath, data) {
  * Atomically write text content (write to .tmp then rename). [I-3]
  */
 export async function writeAtomic(filePath, content) {
-  const tmpPath = `${filePath}.${process.pid}-${Date.now()}.tmp`;
+  const tmp = tmpPath(filePath);
   await ensureDir(dirname(filePath));
   try {
-    await writeFile(tmpPath, content, 'utf-8');
-    await rename(tmpPath, filePath);
+    await writeFile(tmp, content, 'utf-8');
+    await rename(tmp, filePath);
   } catch (err) {
-    try { await unlink(tmpPath); } catch {}
+    try { await unlink(tmp); } catch {}
     throw err;
   }
 }