gsd-lite 0.3.16 → 0.4.0

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

package/.claude-plugin/plugin.json

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

package/cli.js

@@ -40,7 +40,11 @@ switch (command) {
     if (result?.updated) {
       console.log(`\n✓ Updated: v${result.from} → v${result.to}`);
     } else if (result?.updateAvailable) {
-      console.log(`\n! Update available v${result.to} but install failed. Try manually.`);
+      if (result.action === 'plugin_update') {
+        console.log(`\n! Update available: v${result.to}. Run /plugin update gsd`);
+      } else {
+        console.log(`\n! Update available v${result.to} but install failed. Try manually.`);
+      }
     } else if (!result) {
       console.log('✓ Already up to date');
     }

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

@@ -20,104 +20,200 @@ const claudeDir =
 const runtimeDir = path.join(claudeDir, 'gsd');
 const stateDir = path.join(runtimeDir, 'runtime');
 const STATE_FILE = path.join(stateDir, 'update-state.json');
+const STATE_LOCK_FILE = path.join(stateDir, 'update-state.lock');
+const NOTIFICATION_FILE = path.join(stateDir, 'update-notification.json');
 const pluginRoot = path.resolve(__dirname, '..');
 
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+
 // ── Main Entry ─────────────────────────────────────────────
 async function checkForUpdate(options = {}) {
-  const { force = false, verbose = false, install = true } = options;
+  const {
+    force = false,
+    verbose = false,
+    install = true,
+    notify = false,
+    fetchLatestRelease: fetchLatestReleaseImpl = fetchLatestRelease,
+    downloadAndInstall: downloadAndInstallImpl = downloadAndInstall,
+    getCurrentVersion: getCurrentVersionImpl = getCurrentVersion,
+  } = options;
+  const installMode = getInstallMode();
 
   try {
     if (!force && shouldSkipUpdateCheck()) {
       if (verbose) console.log('Skipping update check (dev mode or auto-update in progress)');
       return null;
     }
-
-    const state = readState();
-    if (!force && !shouldCheck(state)) {
-      if (state.updateAvailable && state.latestVersion) {
-        return {
-          updateAvailable: true,
-          from: getCurrentVersion(),
-          to: state.latestVersion,
-        };
+    return await withFileLock(async () => {
+      const state = readState();
+      if (!force && !shouldCheck(state)) {
+        if (state.updateAvailable && state.latestVersion) {
+          return {
+            updateAvailable: true,
+            from: getCurrentVersionImpl(installMode),
+            to: state.latestVersion,
+            installMode,
+          };
+        }
+        if (verbose) console.log('Throttled — last check:', state.lastCheck);
+        return null;
       }
-      if (verbose) console.log('Throttled — last check:', state.lastCheck);
-      return null;
-    }
-
-    if (verbose) console.log('Checking GitHub for latest release...');
-    const token = getGitHubToken();
-    const latest = await fetchLatestRelease(token);
-    if (!latest) {
-      if (latest === false) state.rateLimited = true; // 403 rate-limited
-      saveState({ ...state, lastCheck: new Date().toISOString() });
-      if (verbose) console.log('Could not fetch latest release');
-      return null;
-    }
 
-    // Successful fetch — clear rate-limit back-off
-    state.rateLimited = false;
-    const currentVersion = getCurrentVersion();
-    if (verbose) console.log(`Current: v${currentVersion} — Latest: v${latest.version}`);
+      if (verbose) console.log('Checking GitHub for latest release...');
+      const token = getGitHubToken();
+      const latest = await fetchLatestReleaseImpl(token);
+      if (!latest) {
+        if (latest === false) state.rateLimited = true; // 403 rate-limited
+        saveState({ ...state, lastCheck: new Date().toISOString() });
+        if (verbose) console.log('Could not fetch latest release');
+        return null;
+      }
 
-    const hasUpdate = compareVersions(latest.version, currentVersion) > 0;
+      // Successful fetch — clear rate-limit back-off
+      state.rateLimited = false;
+      const currentVersion = getCurrentVersionImpl(installMode);
+      if (verbose) console.log(`Current: v${currentVersion} — Latest: v${latest.version}`);
+
+      const hasUpdate = compareVersions(latest.version, currentVersion) > 0;
+
+      if (hasUpdate) {
+        if (installMode === 'plugin' && install) {
+          saveState({
+            ...state,
+            lastCheck: new Date().toISOString(),
+            latestVersion: latest.version,
+            updateAvailable: true,
+          });
+          if (notify) {
+            writeNotification({
+              kind: 'available',
+              from: currentVersion,
+              to: latest.version,
+              action: 'plugin_update',
+            });
+          }
+          return {
+            updateAvailable: true,
+            from: currentVersion,
+            to: latest.version,
+            action: 'plugin_update',
+            autoInstallSupported: false,
+            installMode,
+          };
+        }
+
+        if (!install) {
+          // Check-only mode (used by SessionStart hook)
+          saveState({
+            ...state,
+            lastCheck: new Date().toISOString(),
+            latestVersion: latest.version,
+            updateAvailable: true,
+          });
+          return {
+            updateAvailable: true,
+            from: currentVersion,
+            to: latest.version,
+            installMode,
+          };
+        }
+
+        if (verbose) console.log(`Downloading v${latest.version}...`);
+        const success = await downloadAndInstallImpl(latest.tarballUrl, verbose, token);
 
-    if (hasUpdate) {
-      if (!install) {
-        // Check-only mode (used by SessionStart hook)
         saveState({
           ...state,
           lastCheck: new Date().toISOString(),
           latestVersion: latest.version,
-          updateAvailable: true,
+          updateAvailable: !success,
+          lastUpdate: success ? new Date().toISOString() : state.lastUpdate,
         });
+
+        if (success && notify) {
+          writeNotification({
+            kind: 'updated',
+            from: currentVersion,
+            to: latest.version,
+          });
+        }
+
         return {
-          updateAvailable: true,
+          updateAvailable: !success,
+          updated: success,
           from: currentVersion,
           to: latest.version,
+          installMode,
         };
       }
 
-      if (verbose) console.log(`Downloading v${latest.version}...`);
-      const success = await downloadAndInstall(latest.tarballUrl, verbose, token);
-
+      // No update needed
       saveState({
         ...state,
         lastCheck: new Date().toISOString(),
         latestVersion: latest.version,
-        updateAvailable: !success,
-        lastUpdate: success ? new Date().toISOString() : state.lastUpdate,
+        updateAvailable: false,
       });
-
-      return {
-        updateAvailable: !success,
-        updated: success,
-        from: currentVersion,
-        to: latest.version,
-      };
-    }
-
-    // No update needed
-    saveState({
-      ...state,
-      lastCheck: new Date().toISOString(),
-      latestVersion: latest.version,
-      updateAvailable: false,
+      if (verbose) console.log('Already up to date');
+      return null;
     });
-    if (verbose) console.log('Already up to date');
-    return null;
   } catch (err) {
     if (verbose) console.error('Update check failed:', err.message);
     return null;
   }
 }
 
+async function withFileLock(fn) {
+  let acquired = false;
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+  } catch {
+    /* best effort */
+  }
+
+  for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+    try {
+      fs.writeFileSync(STATE_LOCK_FILE, String(process.pid), { flag: 'wx' });
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        try {
+          const stats = fs.statSync(STATE_LOCK_FILE);
+          if (Date.now() - stats.mtimeMs > LOCK_STALE_MS) {
+            try { fs.rmSync(STATE_LOCK_FILE, { force: true }); } catch {}
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_MS));
+      } else {
+        break;
+      }
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    if (acquired) {
+      try { fs.rmSync(STATE_LOCK_FILE, { force: true }); } catch {}
+    }
+  }
+}
+
 // ── Skip Check Detection ──────────────────────────────────
 // Returns true when update checks should be skipped:
 // 1. PLUGIN_AUTO_UPDATE env set → recursive guard (auto-update already in progress)
 // 2. Running from a git clone → dev mode (developer working on source)
 function shouldSkipUpdateCheck() {
   if (process.env.PLUGIN_AUTO_UPDATE) return true;
+  return isDevMode();
+}
+
+function isDevMode() {
   try {
     if (!fs.existsSync(path.join(pluginRoot, '.git'))) return false;
     const pkg = JSON.parse(
@@ -129,6 +225,13 @@ function shouldSkipUpdateCheck() {
   }
 }
 
+function getInstallMode() {
+  if (isDevMode()) return 'dev';
+  return path.resolve(pluginRoot) === path.resolve(claudeDir)
+    ? 'manual'
+    : 'plugin';
+}
+
 // ── Throttle ───────────────────────────────────────────────
 function shouldCheck(state) {
   if (!state.lastCheck) return true;
@@ -196,11 +299,11 @@ function compareVersions(a, b) {
   return 0;
 }
 
-function getCurrentVersion() {
-  for (const p of [
-    path.join(pluginRoot, 'package.json'),
-    path.join(runtimeDir, 'package.json'),
-  ]) {
+function getCurrentVersion(mode = getInstallMode()) {
+  const candidates = mode === 'manual'
+    ? [path.join(runtimeDir, 'package.json'), path.join(pluginRoot, 'package.json')]
+    : [path.join(pluginRoot, 'package.json'), path.join(runtimeDir, 'package.json')];
+  for (const p of candidates) {
     try {
       return JSON.parse(fs.readFileSync(p, 'utf8')).version;
     } catch {
@@ -210,9 +313,24 @@ function getCurrentVersion() {
   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 });
 
@@ -238,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')], {
@@ -245,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) {
@@ -280,32 +426,31 @@ function saveState(state) {
   }
 }
 
+function writeNotification(notification) {
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    const tmpPath = NOTIFICATION_FILE + `.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, JSON.stringify(notification, null, 2) + '\n');
+    fs.renameSync(tmpPath, NOTIFICATION_FILE);
+  } catch {
+    /* silent */
+  }
+}
+
 module.exports = {
   checkForUpdate,
   getCurrentVersion,
   compareVersions,
+  getInstallMode,
+  isDevMode,
+  shouldCheck,
   shouldSkipUpdateCheck,
+  validateExtractedPackage,
 };
 
 // ── CLI Entry Point (for background auto-install) ─────────
 if (require.main === module) {
-  checkForUpdate({ install: true, verbose: false })
-    .then((result) => {
-      if (result?.updated) {
-        const notifPath = path.join(stateDir, 'update-notification.json');
-        fs.mkdirSync(stateDir, { recursive: true });
-        const tmpPath = notifPath + `.${process.pid}.tmp`;
-        fs.writeFileSync(
-          tmpPath,
-          JSON.stringify({
-            from: result.from,
-            to: result.to,
-            at: new Date().toISOString(),
-          }) + '\n',
-        );
-        fs.renameSync(tmpPath, notifPath);
-      }
-    })
+  checkForUpdate({ install: true, verbose: false, notify: true })
     .catch(() => {})
     .finally(() => process.exit(0));
 }

package/hooks/gsd-session-init.cjs

@@ -2,7 +2,7 @@
 // GSD-Lite SessionStart hook
 // 1. Cleans up stale temp files (throttled to once/day).
 // 2. Auto-registers statusLine in settings.json if not already configured.
-// 3. Shows notification if a previous background auto-update completed.
+// 3. Shows notification if a previous background update completed or found a new version.
 // 4. Spawns background auto-update (detached, non-blocking).
 // Idempotent: skips if statusLine already points to gsd-statusline, preserves
 // third-party statuslines.
@@ -71,7 +71,13 @@ setTimeout(() => process.exit(0), 4000).unref();
     const notifPath = path.join(claudeDir, 'gsd', 'runtime', 'update-notification.json');
     if (fs.existsSync(notifPath)) {
       const notif = JSON.parse(fs.readFileSync(notifPath, 'utf8'));
-      console.log(`✅ GSD-Lite auto-updated: v${notif.from} → v${notif.to}`);
+      if (notif.kind === 'updated') {
+        console.log(`✅ GSD-Lite auto-updated: v${notif.from} → v${notif.to}`);
+      } else if (notif.kind === 'available' && notif.action === 'plugin_update') {
+        console.log(`📦 GSD-Lite update available: v${notif.from} → v${notif.to}. Run /plugin update gsd`);
+      } else if (notif.kind === 'available') {
+        console.log(`📦 GSD-Lite update available: v${notif.from} → v${notif.to}. Run gsd update`);
+      }
       fs.unlinkSync(notifPath);
     }
   } catch { /* silent */ }

package/package.json

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

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,26 @@ 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}`);
+        }
+      }
+    }
+  }
   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()) {