gsd-lite 0.5.5 → 0.5.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.5.5",
+      "version": "0.5.7",
       "keywords": [
         "orchestration",
         "mcp",

package/.claude-plugin/plugin.json

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

package/hooks/gsd-auto-update.cjs

@@ -393,6 +393,11 @@ async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
       try { fs.rmSync(backupPath, { force: true }); } catch { /* ignore */ }
     }
 
+    // Sync to plugin cache if installed as plugin
+    // The MCP server loads from plugins/cache, not the runtime dir,
+    // so we must update the cache for version changes to take effect.
+    syncPluginCache(tmpDir, verbose);
+
     return true;
   } catch (err) {
     if (verbose) console.error('  Install failed:', err.message);
@@ -437,6 +442,70 @@ function writeNotification(notification) {
   }
 }
 
+// ── Plugin Cache Sync ─────────────────────────────────────
+// When installed as a plugin, the MCP server runs from plugins/cache/gsd/gsd/<version>/
+// The auto-update installs to ~/.claude/gsd/ (runtime dir) via install.js,
+// but must ALSO update the cache directory for the MCP server to pick up changes.
+function syncPluginCache(extractedDir, verbose = false) {
+  try {
+    const pluginsFile = path.join(claudeDir, 'plugins', 'installed_plugins.json');
+    if (!fs.existsSync(pluginsFile)) return;
+
+    const plugins = JSON.parse(fs.readFileSync(pluginsFile, 'utf8'));
+    const gsdEntry = plugins.plugins?.['gsd@gsd']?.[0];
+    if (!gsdEntry?.installPath) return;
+
+    // Read new version from extracted package
+    const newPkgPath = path.join(extractedDir, 'package.json');
+    if (!fs.existsSync(newPkgPath)) return;
+    const newVersion = JSON.parse(fs.readFileSync(newPkgPath, 'utf8')).version;
+    if (!newVersion) return;
+
+    // Determine new cache path
+    const cacheBase = path.join(claudeDir, 'plugins', 'cache', 'gsd', 'gsd');
+    const newCachePath = path.join(cacheBase, newVersion);
+
+    // Skip if already up to date
+    if (gsdEntry.installPath === newCachePath && fs.existsSync(newCachePath)) {
+      const existingVersion = (() => {
+        try { return JSON.parse(fs.readFileSync(path.join(newCachePath, 'package.json'), 'utf8')).version; }
+        catch { return null; }
+      })();
+      if (existingVersion === newVersion) {
+        if (verbose) console.log('  Plugin cache already up to date');
+        return;
+      }
+    }
+
+    // Copy extracted files to new cache directory
+    if (verbose) console.log(`  Syncing plugin cache → ${newCachePath}`);
+    fs.mkdirSync(newCachePath, { recursive: true });
+    fs.cpSync(extractedDir, newCachePath, { recursive: true });
+
+    // Install dependencies in cache dir
+    if (!fs.existsSync(path.join(newCachePath, 'node_modules', '@modelcontextprotocol'))) {
+      spawnSync('npm', ['install', '--omit=dev', '--ignore-scripts'], {
+        cwd: newCachePath,
+        stdio: 'pipe',
+        timeout: 60000,
+      });
+    }
+
+    // Update installed_plugins.json to point to new cache path
+    gsdEntry.installPath = newCachePath;
+    gsdEntry.version = newVersion;
+    gsdEntry.lastUpdated = new Date().toISOString();
+    const tmpPlugins = pluginsFile + `.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPlugins, JSON.stringify(plugins, null, 2) + '\n');
+    fs.renameSync(tmpPlugins, pluginsFile);
+
+    if (verbose) console.log(`  Plugin cache synced to v${newVersion}`);
+  } catch (err) {
+    // Best effort — don't fail the update if cache sync fails
+    if (verbose) console.error('  Plugin cache sync failed:', err.message);
+  }
+}
+
 module.exports = {
   checkForUpdate,
   getCurrentVersion,

package/package.json

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

package/references/review-classification.md

@@ -7,6 +7,7 @@
 | L0 | 无运行时语义变化 (docs/config/style) | checkpoint 后直接 accepted |
 | L1 | 普通编码任务 (默认) | phase 结束后批量审查 |
 | L2 | 高风险 (auth/payment/public API/DB migration) | checkpoint 后立即独立审查 |
+| L3 | 最高风险 (复杂架构/关键系统) | 与 L2 相同: checkpoint 后立即独立审查 |
 
 ## 运行时重分类
 
@@ -62,14 +63,14 @@ executor checkpointed
   -> 批量审查所有 checkpointed task (排除 L0)
 ```
 
-### L2 流程
+### L2/L3 流程
 
 ```
 executor checkpointed
-  -> handleExecutorResult 检测 reviewLevel === 'L2' && review_required !== false
+  -> handleExecutorResult 检测 (reviewLevel === 'L2' || reviewLevel === 'L3') && review_required !== false
   -> 设置 current_review = { scope: 'task', scope_id: task.id, stage: 'spec' }
   -> workflow_mode = 'reviewing_task'
-  -> 派发 reviewer (scope='task', review_level='L2')
+  -> 派发 reviewer (scope='task', review_level='L2' 或 'L3')
   -> 审查通过后才释放下游依赖
 ```
 

package/src/schema.js

@@ -619,8 +619,9 @@ export function validateReviewerResult(r) {
       errors.push('critical_issues entries must be objects');
       continue;
     }
-    if (typeof issue.reason !== 'string' || issue.reason.length === 0) {
-      errors.push('critical_issues[].reason must be non-empty string');
+    const issueText = issue.reason ?? issue.description;
+    if (typeof issueText !== 'string' || issueText.length === 0) {
+      errors.push('critical_issues[].reason (or .description) must be non-empty string');
     }
     if ('task_id' in issue && typeof issue.task_id !== 'string') {
       errors.push('critical_issues[].task_id must be string');

package/src/server.js

@@ -7,6 +7,24 @@ import { init, read, update, phaseComplete } from './tools/state.js';
 
 const _require = createRequire(import.meta.url);
 const PKG_VERSION = _require('../package.json').version;
+
+// Dev-mode version drift detection: warn when running code differs from disk
+const _isDevMode = (() => {
+  try { return _require('node:fs').existsSync(new URL('../.git', import.meta.url)); } catch { return false; }
+})();
+function _checkVersionDrift() {
+  if (!_isDevMode) return null;
+  try {
+    // Clear require cache to read fresh package.json
+    const pkgPath = _require.resolve('../package.json');
+    delete _require.cache[pkgPath];
+    const diskVersion = _require('../package.json').version;
+    if (diskVersion !== PKG_VERSION) {
+      return `⚠️ GSD server running v${PKG_VERSION} but code on disk is v${diskVersion}. Run /mcp to restart.`;
+    }
+  } catch { /* ignore */ }
+  return null;
+}
 import {
   handleDebuggerResult,
   handleExecutorResult,
@@ -130,7 +148,13 @@ const TOOLS = [
     description: 'Resume the minimal orchestration loop from workflow_mode/current_phase state',
     inputSchema: {
       type: 'object',
-      properties: {},
+      properties: {
+        unblock_tasks: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional task IDs to force-unblock before resuming (e.g. ["1.1", "2.3"])',
+        },
+      },
     },
   },
   {
@@ -185,7 +209,7 @@ const TOOLS = [
       properties: {
         result: {
           type: 'object',
-          description: 'Reviewer result: {scope: "task"|"phase", scope_id: string|number, review_level: "L2"|"L1-batch", spec_passed: boolean, quality_passed: boolean, critical_issues: object[], important_issues: object[], minor_issues: object[], accepted_tasks: string[], rework_tasks: string[], evidence: object[]}',
+          description: 'Reviewer result: {scope: "task"|"phase", scope_id: string|number, review_level: "L2"|"L1-batch", spec_passed: boolean, quality_passed: boolean, critical_issues: [{reason|description: string, task_id?: string, invalidates_downstream?: boolean}], important_issues: [{reason|description: string}], minor_issues: object[], accepted_tasks: string[], rework_tasks: string[], evidence: object[]}',
         },
       },
       required: ['result'],
@@ -202,6 +226,7 @@ async function dispatchToolCall(name, args) {
   switch (name) {
     case 'health': {
       const stateResult = await read(args || {});
+      const versionDrift = _checkVersionDrift();
       result = {
         status: 'ok',
         server: 'gsd',
@@ -213,6 +238,7 @@ async function dispatchToolCall(name, args) {
           current_phase: stateResult.current_phase,
           total_phases: stateResult.total_phases,
         }),
+        ...(versionDrift ? { warning: versionDrift } : {}),
       };
       break;
     }

package/src/tools/orchestrator.js

@@ -18,6 +18,56 @@ const MAX_RESUME_DEPTH = 3;
 const CONTEXT_RESUME_THRESHOLD = 40;
 const MAX_DECISIONS = 200;
 
+// ── Result Contracts ──
+// Provided in dispatch responses so agents produce valid results on the first call.
+const RESULT_CONTRACTS = {
+  executor: {
+    task_id: 'string — must match dispatched task_id',
+    outcome: '"checkpointed" | "blocked" | "failed"',
+    summary: 'string — non-empty description of work done',
+    checkpoint_commit: 'string — required when outcome="checkpointed"',
+    files_changed: 'string[] — list of modified file paths',
+    decisions: '{ id, title, rationale }[] — architectural decisions made',
+    blockers: '{ description, type }[] — what blocked progress (when outcome="blocked")',
+    contract_changed: 'boolean — true if external API/behavior contract changed',
+    evidence: '{ type, detail }[] — verification evidence (test results, lint, etc.)',
+  },
+  reviewer: {
+    scope: '"task" | "phase"',
+    scope_id: 'string | number — task id (e.g. "1.2") or phase number',
+    review_level: '"L2" | "L1-batch" | "L1"',
+    spec_passed: 'boolean',
+    quality_passed: 'boolean',
+    critical_issues: '{ reason|description, task_id?, invalidates_downstream? }[] — blocking issues',
+    important_issues: '{ description, task_id? }[]',
+    minor_issues: '{ description, task_id? }[]',
+    accepted_tasks: 'string[] — task ids that passed review',
+    rework_tasks: 'string[] — task ids that need rework (disjoint with accepted_tasks)',
+    evidence: '{ type, detail }[]',
+  },
+  researcher: {
+    result: {
+      decision_ids: 'string[] — ids of decisions addressed',
+      volatility: '"low" | "medium" | "high"',
+      expires_at: 'string — ISO date when research expires',
+      sources: '{ id, type, ref, title?, accessed_at? }[] — research sources',
+    },
+    decision_index: '{ [id]: { id, title, rationale, status, summary } } — keyed by decision id',
+    artifacts: '{ "STACK.md", "ARCHITECTURE.md", "PITFALLS.md", "SUMMARY.md" } — all four required',
+  },
+  debugger: {
+    task_id: 'string — must match debug target',
+    outcome: '"root_cause_found" | "fix_suggested" | "failed"',
+    root_cause: 'string — non-empty root cause description',
+    evidence: '{ type, detail }[]',
+    hypothesis_tested: '{ hypothesis, result: "confirmed"|"rejected", evidence }[]',
+    fix_direction: 'string — recommended fix approach',
+    fix_attempts: 'number — non-negative integer (>=3 requires outcome="failed")',
+    blockers: '{ description, type }[]',
+    architecture_concern: 'boolean',
+  },
+};
+
 function isTerminalWorkflowMode(workflowMode) {
   return workflowMode === 'completed' || workflowMode === 'failed';
 }
@@ -353,6 +403,7 @@ function buildExecutorDispatch(state, phase, task, extras = {}) {
     phase_id: phase.id,
     task_id: task.id,
     executor_context: context,
+    result_contract: RESULT_CONTRACTS.executor,
     ...extras,
   };
 }
@@ -420,6 +471,7 @@ async function resumeExecutingTask(state, basePath) {
       phase_id: phase.id,
       current_review: state.current_review,
       debug_target: getDebugTarget(phase, task, state.current_review),
+      result_contract: RESULT_CONTRACTS.debugger,
     };
   }
 
@@ -450,8 +502,9 @@ async function resumeExecutingTask(state, basePath) {
 
   if (selection.task) {
     const task = selection.task;
-    // Two-step transition for needs_revalidation: must go through pending first
-    if (task.lifecycle === 'needs_revalidation') {
+    // Compound transition: auto-reset to pending for states that require it
+    // needs_revalidation/blocked/failed all transition through pending before running
+    if (['needs_revalidation', 'blocked', 'failed'].includes(task.lifecycle)) {
       const resetError = await persist(basePath, {
         phases: [{ id: phase.id, todo: [{ id: task.id, lifecycle: 'pending' }] }],
       });
@@ -520,6 +573,14 @@ async function resumeExecutingTask(state, basePath) {
   const reviewPassed = phase.phase_review?.status === 'accepted'
     || phase.phase_handoff?.required_reviews_passed === true;
   if (allAccepted && reviewPassed) {
+    // Auto-advance phase lifecycle to 'reviewing' if currently 'active'
+    // (mirrors trigger_review path at line 480-482)
+    if (phase.lifecycle === 'active') {
+      const advanceError = await persist(basePath, {
+        phases: [{ id: phase.id, lifecycle: 'reviewing' }],
+      });
+      if (advanceError) return advanceError;
+    }
     return {
       success: true,
       action: 'complete_phase',
@@ -544,7 +605,7 @@ async function resumeExecutingTask(state, basePath) {
   };
 }
 
-export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } = {}) {
+export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0, unblock_tasks } = {}) {
   if (_depth >= MAX_RESUME_DEPTH) {
     return { error: true, message: `resumeWorkflow recursive depth limit exceeded (max ${MAX_RESUME_DEPTH})` };
   }
@@ -554,6 +615,31 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } =
     return state;
   }
 
+  // Force-unblock specified tasks before normal resume flow
+  if (Array.isArray(unblock_tasks) && unblock_tasks.length > 0 && _depth === 0) {
+    const phase = getCurrentPhase(state);
+    if (phase) {
+      const patches = [];
+      for (const taskId of unblock_tasks) {
+        const task = (phase.todo || []).find(t => t.id === taskId);
+        if (task?.lifecycle === 'blocked') {
+          patches.push({ id: taskId, lifecycle: 'pending', blocked_reason: null, unblock_condition: null });
+        }
+      }
+      if (patches.length > 0) {
+        const persistError = await persist(basePath, {
+          workflow_mode: 'executing_task',
+          current_task: null,
+          current_review: null,
+          phases: [{ id: phase.id, todo: patches }],
+        });
+        if (persistError) return persistError;
+        // Re-read state after unblock and continue
+        return resumeWorkflow({ basePath, _depth: _depth + 1 });
+      }
+    }
+  }
+
   const preflight = await evaluatePreflight(state, basePath);
   if (preflight.override) {
     const persistError = await persist(basePath, preflight.override.updates);
@@ -600,7 +686,7 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } =
       const autoUnblock = await tryAutoUnblock(state, phase, basePath);
       if (autoUnblock.error) return autoUnblock;
 
-      if (autoUnblock.autoUnblocked.length > 0 && autoUnblock.blockers.length === 0) {
+      if (autoUnblock.blockers.length === 0) {
         const persistError = await persist(basePath, {
           workflow_mode: 'executing_task',
           current_task: null,
@@ -643,6 +729,7 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } =
           checkpoint_commit: task.checkpoint_commit || null,
           files_changed: task.files_changed || [],
         })),
+        result_contract: RESULT_CONTRACTS.reviewer,
       };
     }
     case 'reviewing_task': {
@@ -670,6 +757,7 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } =
           checkpoint_commit: task.checkpoint_commit || null,
           files_changed: task.files_changed || [],
         } : null,
+        result_contract: RESULT_CONTRACTS.reviewer,
       };
     }
     case 'completed':
@@ -796,7 +884,7 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
     const isL0 = reviewLevel === 'L0';
     const autoAccept = isL0 || task.review_required === false;
 
-    const current_review = !isL0 && reviewLevel === 'L2' && task.review_required !== false
+    const current_review = !isL0 && (reviewLevel === 'L2' || reviewLevel === 'L3') && task.review_required !== false
       ? { scope: 'task', scope_id: task.id, stage: 'spec' }
       : null;
     const workflow_mode = current_review ? 'reviewing_task' : 'executing_task';
@@ -843,6 +931,7 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
       review_level: reviewLevel,
       current_review,
       auto_accepted: autoAccept,
+      ...(current_review ? { result_contract: RESULT_CONTRACTS.reviewer } : {}),
     };
   }
 
@@ -920,6 +1009,7 @@ export async function handleExecutorResult({ result, basePath = process.cwd() }
     task_id: task.id,
     retry_count,
     current_review,
+    result_contract: shouldDebug ? RESULT_CONTRACTS.debugger : RESULT_CONTRACTS.executor,
   };
 }
 
@@ -1039,12 +1129,21 @@ export async function handleReviewerResult({ result, basePath = process.cwd() }
     }
   }
 
-  // Rework tasks
+  // Rework tasks — persist reviewer feedback so executor knows what to fix
   for (const taskId of (result.rework_tasks || [])) {
     const task = getTaskById(phase, taskId);
     if (!task) continue;
     if (task.lifecycle === 'checkpointed' || task.lifecycle === 'accepted') {
-      taskPatches.push({ id: taskId, lifecycle: 'needs_revalidation', evidence_refs: [] });
+      const taskIssues = [
+        ...(result.critical_issues || []).filter(i => !i.task_id || i.task_id === taskId),
+        ...(result.important_issues || []).filter(i => !i.task_id || i.task_id === taskId),
+      ].map(i => i.reason ?? i.description ?? '');
+      taskPatches.push({
+        id: taskId,
+        lifecycle: 'needs_revalidation',
+        evidence_refs: [],
+        last_review_feedback: taskIssues.length > 0 ? taskIssues : null,
+      });
     }
   }
 

package/src/tools/state.js

@@ -146,7 +146,17 @@ export async function init({ project, phases, research, force = false, basePath
     state.context.last_session = new Date(Math.ceil(Math.max(...mtimes))).toISOString();
     await writeJson(statePath, state);
 
-    return { success: true };
+    return {
+      success: true,
+      project: state.project,
+      total_phases: state.total_phases,
+      phases: state.phases.map(p => ({
+        id: p.id,
+        name: p.name,
+        tasks: p.todo.length,
+      })),
+      research: !!research,
+    };
   });
 }
 
@@ -394,13 +404,23 @@ export async function phaseComplete({
     }
 
     // Validate phase lifecycle transition FIRST (fail-fast) [I-4]
-    const transitionResult = validateTransition(
-      'phase',
-      phase.lifecycle,
-      'accepted',
-    );
-    if (!transitionResult.valid) {
-      return { error: true, code: ERROR_CODES.TRANSITION_ERROR, message: transitionResult.error };
+    // Allow active → accepted by auto-advancing through 'reviewing' intermediate state
+    if (phase.lifecycle === 'active') {
+      const intermediateResult = validateTransition('phase', 'active', 'reviewing');
+      const finalResult = validateTransition('phase', 'reviewing', 'accepted');
+      if (!intermediateResult.valid || !finalResult.valid) {
+        return { error: true, code: ERROR_CODES.TRANSITION_ERROR, message: `Invalid phase transition: ${phase.lifecycle} → accepted` };
+      }
+      // Will be set to 'accepted' below; just validate here
+    } else {
+      const transitionResult = validateTransition(
+        'phase',
+        phase.lifecycle,
+        'accepted',
+      );
+      if (!transitionResult.valid) {
+        return { error: true, code: ERROR_CODES.TRANSITION_ERROR, message: transitionResult.error };
+      }
     }
 
     // Check handoff gate: all tasks must be accepted
@@ -670,7 +690,8 @@ export function selectRunnableTask(phase, state, { maxRetry = DEFAULT_MAX_RETRY
         if (gate === 'accepted' && depTask.lifecycle !== 'accepted') { depsOk = false; break; }
         if (gate === 'phase_complete') { depsOk = false; break; } // phase_complete is only valid on phase-kind deps
       } else if (dep.kind === 'phase') {
-        const depPhase = (state.phases || []).find(p => p.id === dep.id);
+        const depPhaseId = Number(dep.id);
+        const depPhase = (state.phases || []).find(p => p.id === depPhaseId);
         if (!depPhase || depPhase.lifecycle !== 'accepted') { depsOk = false; break; }
       }
     }
@@ -725,7 +746,8 @@ export function selectRunnableTask(phase, state, { maxRetry = DEFAULT_MAX_RETRY
           reasons.push(`dep ${dep.id} has phase_complete gate (invalid for task-kind dependency)`);
         }
       } else if (dep.kind === 'phase') {
-        const depPhase = (state.phases || []).find(p => p.id === dep.id);
+        const depPhaseId = Number(dep.id);
+        const depPhase = (state.phases || []).find(p => p.id === depPhaseId);
         if (!depPhase || depPhase.lifecycle !== 'accepted') {
           reasons.push(`phase dep ${dep.id} not accepted`);
         }
@@ -827,6 +849,10 @@ export function buildExecutorContext(state, taskId, phaseId) {
     evidence: task.debug_context.evidence || [],
   } : null;
 
+  const rework_feedback = Array.isArray(task.last_review_feedback) && task.last_review_feedback.length > 0
+    ? task.last_review_feedback
+    : null;
+
   return {
     task_spec,
     research_decisions,
@@ -835,6 +861,7 @@ export function buildExecutorContext(state, taskId, phaseId) {
     workflows,
     constraints,
     debugger_guidance,
+    rework_feedback,
   };
 }