gsd-lite 0.3.17 → 0.4.1

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

package/.claude-plugin/plugin.json

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

package/commands/doctor.md

@@ -0,0 +1,98 @@
+---
+description: Run diagnostic checks on GSD-Lite installation and project health
+---
+
+<role>
+You are GSD-Lite diagnostician. Run system health checks and report results clearly.
+Use the user's input language for all output.
+</role>
+
+<process>
+
+## STEP 1: State File Check
+
+Check if `.gsd/state.json` exists:
+- If exists: parse it as JSON
+  - Valid JSON: record PASS with project name and workflow_mode
+  - Invalid JSON (parse error): record FAIL with error details
+- If not exists: record INFO "No active project (state.json not found)"
+
+## STEP 2: MCP Server Health
+
+Call the `gsd health` MCP tool:
+- If returns `status: "ok"`: record PASS with server version
+- If returns error or unreachable: record FAIL with error message
+- Note: if MCP server is not available at all (tool not found), record FAIL "MCP server not registered"
+
+## STEP 3: Hooks Registration
+
+Check if GSD hooks are registered in Claude settings:
+- Read `~/.claude/settings.json` (or `~/.claude/settings.local.json`)
+- Check for `statusLine` entry containing `gsd-statusline`
+- Check for `PostToolUse` hook entry containing `gsd-context-monitor`
+- Both present: record PASS
+- Partial: record WARN with which hook is missing
+- Neither: record FAIL "No GSD hooks registered"
+
+Also verify the hook files exist on disk:
+- `~/.claude/hooks/gsd-statusline.cjs`
+- `~/.claude/hooks/gsd-context-monitor.cjs`
+- Files missing but settings present: record WARN "Hook registered but file missing"
+
+## STEP 4: Lock File Check
+
+Check if `.gsd/.state-lock` exists:
+- If not exists: record PASS "No stale lock"
+- If exists: check file age
+  - Older than 5 minutes: record WARN "Stale lock file detected (age: {age}). May indicate a crashed process. Consider removing it."
+  - Recent (< 5 min): record INFO "Lock file present (age: {age}), likely active operation"
+
+## STEP 5: Auto-Update Status
+
+Check for update-related information:
+- Read `~/.claude/gsd/package.json` for installed version
+- Compare with the version from `gsd health` tool response
+- If versions match: record PASS with version number
+- If mismatch: record WARN "Version mismatch: installed={x}, server={y}"
+- If `~/.claude/gsd/.update-pending` exists: record INFO "Update pending, will apply on next session"
+- If cannot determine: record INFO "Update status unavailable"
+
+## STEP 6: Output Summary
+
+Output a diagnostic summary with status indicators:
+
+```
+GSD Doctor - Diagnostic Report
+===============================
+
+[PASS] State file         — {details}
+[PASS] MCP server         — {details}
+[PASS] Hooks registered   — {details}
+[PASS] Lock file          — {details}
+[PASS] Update status      — {details}
+
+Result: All checks passed (or N issues found)
+```
+
+Status indicators:
+- `[PASS]` — check passed, no issues
+- `[WARN]` — potential issue, not blocking
+- `[FAIL]` — problem detected, needs attention
+- `[INFO]` — informational, no action needed
+
+If any FAIL or WARN items exist, add a "Suggested Actions" section:
+```
+Suggested Actions:
+- {action for each FAIL/WARN item}
+```
+
+</process>
+
+<rules>
+- Read-only operation: do not modify any files
+- Do not modify state.json or any configuration
+- Report raw facts: do not guess or infer causes beyond what is directly observable
+- If a check cannot be performed (e.g., tool unavailable), report INFO rather than FAIL
+- Always show all 5 checks in the summary, even if some are INFO/skipped
+</rules>
+</output>

package/hooks/gsd-auto-update.cjs

@@ -313,9 +313,24 @@ function getCurrentVersion(mode = getInstallMode()) {
   return '0.0.0';
 }
 
+// ── Package Validation ──────────────────────────────────────
+function validateExtractedPackage(extractDir) {
+  try {
+    const pkgPath = path.join(extractDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (pkg.name !== 'gsd-lite') return false;
+    if (!pkg.version || !/^\d+\.\d+\.\d+/.test(pkg.version)) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ── Download & Install ─────────────────────────────────────
 async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
   const tmpDir = path.join(os.tmpdir(), `gsd-update-${Date.now()}`);
+  const backupPath = path.join(pluginRoot, 'package.json.bak');
+  let backedUp = false;
   try {
     fs.mkdirSync(tmpDir, { recursive: true });
 
@@ -341,6 +356,23 @@ async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
     const tar = spawnSync('tar', ['xzf', tarPath, '-C', tmpDir, '--strip-components=1'], { timeout: 30000 });
     if (tar.status !== 0) throw new Error(`tar extract failed: ${(tar.stderr || '').toString().slice(0, 200)}`);
 
+    // Validate extracted package before installing
+    if (!validateExtractedPackage(tmpDir)) {
+      if (verbose) console.error('  Package validation failed — aborting install');
+      return false;
+    }
+
+    // Backup current package.json before install
+    const currentPkgPath = path.join(pluginRoot, 'package.json');
+    try {
+      if (fs.existsSync(currentPkgPath)) {
+        fs.copyFileSync(currentPkgPath, backupPath);
+        backedUp = true;
+      }
+    } catch {
+      /* best effort — proceed without backup */
+    }
+
     // Run installer with spawnSync (no shell)
     if (verbose) console.log('  Running installer...');
     const install = spawnSync(process.execPath, [path.join(tmpDir, 'install.js')], {
@@ -348,7 +380,18 @@ async function downloadAndInstall(tarballUrl, verbose = false, token = null) {
       stdio: verbose ? 'inherit' : 'pipe',
       env: { ...process.env, PLUGIN_AUTO_UPDATE: '1' },
     });
-    if (install.status !== 0) throw new Error(`Installer failed: ${(install.stderr || '').toString().slice(0, 200)}`);
+    if (install.status !== 0) {
+      // Restore backup on install failure
+      if (backedUp) {
+        try { fs.copyFileSync(backupPath, currentPkgPath); } catch { /* best effort */ }
+      }
+      throw new Error(`Installer failed: ${(install.stderr || '').toString().slice(0, 200)}`);
+    }
+
+    // Success — remove backup
+    if (backedUp) {
+      try { fs.rmSync(backupPath, { force: true }); } catch { /* ignore */ }
+    }
 
     return true;
   } catch (err) {
@@ -402,6 +445,7 @@ module.exports = {
   isDevMode,
   shouldCheck,
   shouldSkipUpdateCheck,
+  validateExtractedPackage,
 };
 
 // ── CLI Entry Point (for background auto-install) ─────────

package/install.js

@@ -136,7 +136,7 @@ export function main() {
     copyDir(localNM, join(RUNTIME_DIR, 'node_modules'), 'runtime/node_modules (copied)');
   } else if (!DRY_RUN) {
     log('  ⧗ Installing runtime dependencies...');
-    execSync('npm install --omit=dev', { cwd: RUNTIME_DIR, stdio: 'pipe' });
+    execSync('npm ci --omit=dev', { cwd: RUNTIME_DIR, stdio: 'pipe' });
     log('  ✓ runtime dependencies installed');
   } else {
     log('  [dry-run] Would install runtime dependencies');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-lite",
-  "version": "0.3.17",
+  "version": "0.4.1",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {
@@ -39,7 +39,8 @@
     "cli.js",
     "launcher.js",
     "install.js",
-    "uninstall.js"
+    "uninstall.js",
+    "package-lock.json"
   ],
   "engines": {
     "node": ">=20.0.0"

package/src/schema.js

@@ -256,6 +256,17 @@ export function validateStateUpdate(state, updates) {
     errors.push(`current_phase (${effectivePhase}) must not exceed total_phases (${effectiveTotal})`);
   }
 
+  // P2-9: Cross-field — current_task must belong to current_phase
+  const effectiveTask = 'current_task' in updates ? updates.current_task : state.current_task;
+  if (effectiveTask && Array.isArray(state.phases)) {
+    const curPhase = state.phases.find(p => p.id === effectivePhase);
+    if (curPhase && Array.isArray(curPhase.todo)) {
+      if (!curPhase.todo.some(t => t.id === effectiveTask)) {
+        errors.push(`current_task "${effectiveTask}" not found in current_phase ${effectivePhase}`);
+      }
+    }
+  }
+
   return { valid: errors.length === 0, errors };
 }
 
@@ -356,6 +367,57 @@ export function validateState(state) {
       && 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})`);
   }
+  // P2-9: Cross-field consistency — current_task must belong to current_phase
+  if (state.current_task && Array.isArray(state.phases)) {
+    const curPhase = state.phases.find(p => p.id === state.current_phase);
+    if (curPhase && Array.isArray(curPhase.todo)) {
+      const taskExists = curPhase.todo.some(t => t.id === state.current_task);
+      if (!taskExists) {
+        errors.push(`current_task "${state.current_task}" not found in current_phase ${state.current_phase}`);
+      }
+    }
+  }
+  // P2-9: workflow_mode consistency — completed project must not have active/running tasks
+  if (state.workflow_mode === 'completed' && Array.isArray(state.phases)) {
+    for (const phase of state.phases) {
+      for (const task of (phase.todo || [])) {
+        if (task.lifecycle === 'running') {
+          errors.push(`Completed project has running task ${task.id} in phase ${phase.id}`);
+        }
+      }
+    }
+  }
+  // P2-9: workflow_mode consistency — reviewing modes require matching current_review
+  if (state.workflow_mode === 'reviewing_phase' || state.workflow_mode === 'reviewing_task') {
+    const expectedScope = state.workflow_mode === 'reviewing_phase' ? 'phase' : 'task';
+    if (!state.current_review || state.current_review.scope !== expectedScope) {
+      errors.push(`workflow_mode "${state.workflow_mode}" requires current_review with scope="${expectedScope}"`);
+    }
+  }
+  // P2-9: current_review.scope_id must reference an existing phase or task
+  if (state.current_review && state.current_review.scope_id != null && Array.isArray(state.phases)) {
+    if (state.current_review.scope === 'phase') {
+      if (!state.phases.some(p => p.id === state.current_review.scope_id)) {
+        errors.push(`current_review.scope_id ${state.current_review.scope_id} references non-existent phase`);
+      }
+    } else if (state.current_review.scope === 'task') {
+      const curPhase = state.phases.find(p => p.id === state.current_phase);
+      if (curPhase && Array.isArray(curPhase.todo) && !curPhase.todo.some(t => t.id === state.current_review.scope_id)) {
+        errors.push(`current_review.scope_id "${state.current_review.scope_id}" references non-existent task in phase ${state.current_phase}`);
+      }
+    }
+  }
+  // P2-9: accepted phase must not contain non-accepted tasks
+  if (Array.isArray(state.phases)) {
+    for (const phase of state.phases) {
+      if (phase.lifecycle === 'accepted' && Array.isArray(phase.todo)) {
+        const nonAccepted = phase.todo.filter(t => t.lifecycle !== 'accepted');
+        if (nonAccepted.length > 0) {
+          errors.push(`Accepted phase ${phase.id} contains non-accepted tasks: ${nonAccepted.map(t => `${t.id}:${t.lifecycle}`).join(', ')}`);
+        }
+      }
+    }
+  }
   if (Array.isArray(state.phases)) {
     if (typeof state.total_phases === 'number' && state.total_phases !== state.phases.length) {
       errors.push(`total_phases (${state.total_phases}) does not match phases.length (${state.phases.length})`);

package/src/tools/orchestrator.js

@@ -168,6 +168,32 @@ async function evaluatePreflight(state, basePath) {
     });
   }
 
+  // P0-2: Dirty-phase detection — rollback current_phase to earliest phase
+  // that has needs_revalidation tasks, ensuring earlier invalidated work
+  // is re-executed before proceeding with later phases.
+  // Use filter+reduce (not .find) to guarantee lowest-ID match regardless of array order.
+  const dirtyPhases = (state.phases || []).filter(p =>
+    p.id < state.current_phase
+    && (p.todo || []).some(t => t.lifecycle === 'needs_revalidation'),
+  );
+  const earliestDirtyPhase = dirtyPhases.length > 0
+    ? dirtyPhases.reduce((min, p) => (p.id < min.id ? p : min))
+    : null;
+  if (earliestDirtyPhase) {
+    hints.push({
+      workflow_mode: 'executing_task',
+      action: 'rollback_to_dirty_phase',
+      updates: {
+        workflow_mode: 'executing_task',
+        current_phase: earliestDirtyPhase.id,
+        current_task: null,
+        current_review: null,
+      },
+      dirty_phase: { id: earliestDirtyPhase.id, name: earliestDirtyPhase.name },
+      message: `Phase ${earliestDirtyPhase.id} has invalidated tasks; rolling back from phase ${state.current_phase}`,
+    });
+  }
+
   if (hints.length === 0) return { override: null };
 
   return {
@@ -469,6 +495,21 @@ async function resumeExecutingTask(state, basePath) {
     };
   }
 
+  // P0-1: Auto phase completion — when all tasks accepted and review passed,
+  // signal complete_phase instead of going idle
+  const allAccepted = phase.todo.length > 0 && phase.todo.every(t => t.lifecycle === 'accepted');
+  const reviewPassed = phase.phase_review?.status === 'accepted'
+    || phase.phase_handoff?.required_reviews_passed === true;
+  if (allAccepted && reviewPassed) {
+    return {
+      success: true,
+      action: 'complete_phase',
+      workflow_mode: 'executing_task',
+      phase_id: phase.id,
+      message: 'All tasks accepted and review passed; phase ready for completion',
+    };
+  }
+
   const persistError = await persist(basePath, {
     current_task: null,
     current_review: null,
@@ -509,6 +550,7 @@ export async function resumeWorkflow({ basePath = process.cwd(), _depth = 0 } =
       ...(preflight.override.current_git_head ? { current_git_head: preflight.override.current_git_head } : {}),
       ...(preflight.override.changed_files ? { changed_files: preflight.override.changed_files } : {}),
       ...(preflight.override.expired_research ? { expired_research: preflight.override.expired_research } : {}),
+      ...(preflight.override.dirty_phase ? { dirty_phase: preflight.override.dirty_phase } : {}),
       ...(preflight.hints && preflight.hints.length > 1 ? { pending_issues: preflight.hints.slice(1) } : {}),
     };
   }

package/src/tools/verify.js

@@ -75,7 +75,14 @@ export async function runTypeCheck(pm, cwd) {
   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);
+  // Local-first: use node_modules/.bin/tsc if available, skip otherwise
+  const localTsc = join(cwd, 'node_modules', '.bin', 'tsc');
+  try {
+    await stat(localTsc);
+  } catch {
+    return { exit_code: 0, summary: 'skipped: no local typescript found' };
+  }
+  return runCommand(localTsc, ['--noEmit'], cwd);
 }
 
 export async function runAll(cwd = process.cwd()) {