gsd-lite 0.2.1 → 0.3.1

package/hooks/gsd-context-monitor.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// GSD-Lite Context Monitor — PostToolUse hook
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high.
+//
+// Architecture:
+// 1. StatusLine hook writes metrics to /tmp/gsd-ctx-{session_id}.json
+// 2. This hook reads those metrics after each tool use
+// 3. When remaining context drops below thresholds, injects a warning
+//    via hookSpecificOutput.additionalContext
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent must stop and save state
+//
+// Debounce: 5 tool uses between warnings to avoid spam
+// Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const WARNING_THRESHOLD = 35;
+const CRITICAL_THRESHOLD = 25;
+const STALE_SECONDS = 60;
+const DEBOUNCE_CALLS = 5;
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) {
+      process.exit(0);
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `gsd-ctx-${sessionId}.json`);
+
+    let metrics;
+    try {
+      metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    } catch {
+      process.exit(0); // No bridge file — fresh session or subagent
+    }
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    // Cheapest check first — most calls exit here
+    if (remaining > WARNING_THRESHOLD) {
+      process.exit(0);
+    }
+
+    // Ignore stale metrics
+    const now = Math.floor(Date.now() / 1000);
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
+      process.exit(0);
+    }
+
+    // Debounce logic
+    const warnPath = path.join(tmpDir, `gsd-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    try {
+      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      firstWarn = false;
+    } catch {
+      // No prior warning state — first warning this session
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+
+    // Severity escalation bypasses debounce
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    // Reset debounce
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    // Use bridge data to avoid extra filesystem check
+    const isGsdActive = metrics.has_gsd === true;
+
+    let message;
+    if (isCritical) {
+      message = isGsdActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. `
+          + 'Context is nearly exhausted. Complete current task checkpoint immediately, '
+          + 'set workflow_mode = awaiting_clear via gsd-state-update, and tell user to /clear then /gsd:resume.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. `
+          + 'Context is nearly exhausted. Inform the user that context is low and ask how they want to proceed.';
+    } else {
+      message = isGsdActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. `
+          + 'Context is getting limited. Avoid starting new complex work. Complete current task then save state.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. `
+          + 'Be aware that context is getting limited. Avoid unnecessary exploration or starting new complex work.';
+    }
+
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: message,
+      },
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    process.exit(0);
+  }
+});

package/hooks/gsd-session-init.cjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// GSD-Lite SessionStart hook
+// Auto-registers statusLine in settings.json if not already configured.
+// This bridges the gap for plugin marketplace installs (which don't run install.js).
+// Idempotent: skips if statusLine already points to gsd-statusline, preserves
+// third-party statuslines.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const pluginRoot = path.resolve(__dirname, '..');
+const claudeDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const settingsPath = path.join(claudeDir, 'settings.json');
+const statuslineScript = path.join(pluginRoot, 'hooks', 'gsd-statusline.cjs');
+
+// Clean up stale bridge/debounce files from previous sessions (older than 24h)
+try {
+  const tmpDir = os.tmpdir();
+  const DAY_MS = 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  for (const entry of fs.readdirSync(tmpDir)) {
+    if (!entry.startsWith('gsd-ctx-')) continue;
+    try {
+      const fullPath = path.join(tmpDir, entry);
+      if (now - fs.statSync(fullPath).mtimeMs > DAY_MS) fs.unlinkSync(fullPath);
+    } catch { /* skip */ }
+  }
+} catch { /* silent */ }
+
+try {
+  // Verify the statusline script exists (sanity check)
+  if (!fs.existsSync(statuslineScript)) {
+    process.exit(0);
+  }
+
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    process.exit(0); // Can't read settings — don't risk writing a broken file
+  }
+
+  // Already has a statusLine configured (ours or third-party) — don't overwrite
+  if (settings.statusLine?.command) {
+    process.exit(0);
+  }
+
+  // Register our statusLine
+  settings.statusLine = {
+    type: 'command',
+    command: `node ${JSON.stringify(statuslineScript)}`
+  };
+
+  // Atomic write to avoid corruption
+  const tmpPath = settingsPath + '.gsd-tmp';
+  fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2) + '\n');
+  fs.renameSync(tmpPath, settingsPath);
+} catch {
+  // Silent fail — never block session start
+}

package/hooks/gsd-statusline.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// GSD-Lite StatusLine hook
+// Shows: model | current task | directory | context usage progress bar
+// Reads JSON from stdin, writes bridge file for context-monitor PostToolUse hook.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const cwd = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Current GSD task from state.json
+    let task = '';
+    let hasGsd = false;
+    const gsdDir = path.join(cwd, '.gsd');
+    try {
+      const state = JSON.parse(fs.readFileSync(path.join(gsdDir, 'state.json'), 'utf8'));
+      hasGsd = true;
+      if (state.current_task && state.current_phase) {
+        const phase = (state.phases || []).find(p => p.id === state.current_phase);
+        const t = phase?.todo?.find(t => t.id === state.current_task);
+        if (t) task = `${t.id} ${t.name}`;
+      }
+    } catch {
+      // No state.json or parse error — skip task display
+    }
+
+    // Context window display (USED percentage scaled to usable context)
+    // Claude Code reserves ~16.5% for autocompact buffer
+    const AUTO_COMPACT_BUFFER_PCT = 16.5;
+    let ctx = '';
+    if (remaining != null) {
+      const usableRemaining = Math.max(0, ((remaining - AUTO_COMPACT_BUFFER_PCT) / (100 - AUTO_COMPACT_BUFFER_PCT)) * 100);
+      const used = Math.max(0, Math.min(100, Math.round(100 - usableRemaining)));
+
+      // Write bridge file for context-monitor PostToolUse hook (skip if remaining unchanged)
+      if (session) {
+        try {
+          const bridgePath = path.join(os.tmpdir(), `gsd-ctx-${session}.json`);
+          let needsWrite = true;
+          try {
+            const existing = JSON.parse(fs.readFileSync(bridgePath, 'utf8'));
+            if (existing.remaining_percentage === remaining) needsWrite = false;
+          } catch { /* no existing file */ }
+          if (needsWrite) {
+            const tmpBridge = bridgePath + '.tmp';
+            fs.writeFileSync(tmpBridge, JSON.stringify({
+              session_id: session,
+              remaining_percentage: remaining,
+              used_pct: used,
+              has_gsd: hasGsd,
+              timestamp: Math.floor(Date.now() / 1000),
+            }));
+            fs.renameSync(tmpBridge, bridgePath);
+          }
+        } catch {
+          // Silent fail — bridge is best-effort
+        }
+      }
+
+      // Also write to .gsd/.context-health for MCP server reads (skip if unchanged)
+      try {
+        const healthPath = path.join(gsdDir, '.context-health');
+        const current = fs.readFileSync(healthPath, 'utf8').trim();
+        if (current !== String(remaining)) {
+          fs.writeFileSync(healthPath, String(remaining));
+        }
+      } catch {
+        // File doesn't exist yet or .gsd/ missing — ensure dir exists then atomic write
+        try {
+          fs.mkdirSync(gsdDir, { recursive: true });
+          const tmpHealth = path.join(gsdDir, `.context-health.${process.pid}.tmp`);
+          fs.writeFileSync(tmpHealth, String(remaining));
+          fs.renameSync(tmpHealth, path.join(gsdDir, '.context-health'));
+        } catch { /* silent */ }
+      }
+
+      // Progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(10 - filled);
+
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m\uD83D\uDC80 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Output
+    const dirname = path.basename(cwd);
+    if (task) {
+      process.stdout.write(`\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch {
+    // Silent fail
+  }
+});

package/hooks/hooks.json

@@ -1,13 +1,26 @@
 {
-  "description": "GSD-Lite context monitoring hooks",
+  "description": "GSD-Lite hooks: statusline auto-registration + context health monitor",
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-session-init.cjs\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-monitor.js\" postToolUse"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-context-monitor.cjs\"",
+            "timeout": 3
           }
         ]
       }

package/install.js

@@ -1,28 +1,25 @@
 #!/usr/bin/env node
 // Plugin installer for GSD-Lite
 
-import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { execSync } from 'node:child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const CLAUDE_DIR = join(homedir(), '.claude');
-const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd-lite');
+const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd');
 const DRY_RUN = process.argv.includes('--dry-run');
 
 function log(msg) { console.log(msg); }
 
-function formatHookCommand(scriptPath, hookName) {
-  return `node ${JSON.stringify(scriptPath)} ${hookName}`;
-}
 
-function registerStatusLine(settings, hookPath) {
-  const command = formatHookCommand(hookPath, 'statusLine');
+function registerStatusLine(settings, statuslineScriptPath) {
+  const command = `node ${JSON.stringify(statuslineScriptPath)}`;
   // Don't overwrite non-GSD statusLine
   if (settings.statusLine && typeof settings.statusLine === 'object'
-      && !settings.statusLine.command?.includes('context-monitor.js')) {
+      && !settings.statusLine.command?.includes('gsd-statusline')) {
     log('  ! Preserved existing statusLine');
     return false;
   }
@@ -32,8 +29,8 @@ function registerStatusLine(settings, hookPath) {
   return true;
 }
 
-function registerPostToolUseHook(hooks, hookPath) {
-  const command = formatHookCommand(hookPath, 'postToolUse');
+function registerPostToolUseHook(hooks, contextMonitorPath) {
+  const command = `node ${JSON.stringify(contextMonitorPath)}`;
   const entry = { matcher: '*', hooks: [{ type: 'command', command }] };
   if (!hooks.PostToolUse) {
     hooks.PostToolUse = [entry];
@@ -41,7 +38,7 @@ function registerPostToolUseHook(hooks, hookPath) {
   }
   // Handle legacy string format
   if (typeof hooks.PostToolUse === 'string') {
-    if (!hooks.PostToolUse.includes('context-monitor.js')) {
+    if (!hooks.PostToolUse.includes('gsd-context-monitor')) {
       log('  ! Preserved existing PostToolUse hook');
       return false;
     }
@@ -50,7 +47,7 @@ function registerPostToolUseHook(hooks, hookPath) {
   }
   if (Array.isArray(hooks.PostToolUse)) {
     const idx = hooks.PostToolUse.findIndex(e =>
-      e.hooks?.some(h => h.command?.includes('context-monitor.js')));
+      e.hooks?.some(h => h.command?.includes('gsd-context-monitor')));
     if (idx >= 0) hooks.PostToolUse[idx] = entry;
     else hooks.PostToolUse.push(entry);
     return true;
@@ -88,6 +85,13 @@ export function main() {
 
   log('Installing files...');
 
+  // Clean up legacy "gsd-lite" runtime directory from older versions
+  const LEGACY_RUNTIME_DIR = join(CLAUDE_DIR, 'gsd-lite');
+  if (!DRY_RUN && existsSync(LEGACY_RUNTIME_DIR)) {
+    rmSync(LEGACY_RUNTIME_DIR, { recursive: true, force: true });
+    log('  ✓ Removed legacy gsd-lite runtime');
+  }
+
   // Reset managed runtime directory to avoid stale files on reinstall
   if (!DRY_RUN && existsSync(RUNTIME_DIR)) {
     rmSync(RUNTIME_DIR, { recursive: true, force: true });
@@ -109,8 +113,8 @@ export function main() {
   copyDir(join(__dirname, 'hooks'), join(CLAUDE_DIR, 'hooks'), 'hooks → ~/.claude/hooks/');
 
   // 6. Stable runtime for MCP server
-  copyDir(join(__dirname, 'src'), join(RUNTIME_DIR, 'src'), 'runtime/src → ~/.claude/gsd-lite/src/');
-  copyFile(join(__dirname, 'package.json'), join(RUNTIME_DIR, 'package.json'), 'runtime/package.json → ~/.claude/gsd-lite/package.json');
+  copyDir(join(__dirname, 'src'), join(RUNTIME_DIR, 'src'), 'runtime/src → ~/.claude/gsd/src/');
+  copyFile(join(__dirname, 'package.json'), join(RUNTIME_DIR, 'package.json'), 'runtime/package.json → ~/.claude/gsd/package.json');
 
   // 7. Runtime dependencies — copy local node_modules or install fresh (npx hoists deps)
   const localNM = join(__dirname, 'node_modules');
@@ -130,21 +134,30 @@ export function main() {
     let settings = {};
     try {
       settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-    } catch {}
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        log(`  ! Warning: Could not parse ${settingsPath}: ${err.message}`);
+      }
+    }
 
     if (!settings.mcpServers) settings.mcpServers = {};
-    settings.mcpServers['gsd-lite'] = {
+    // Remove legacy "gsd-lite" server entry from older versions
+    delete settings.mcpServers['gsd-lite'];
+    settings.mcpServers.gsd = {
       command: 'node',
       args: [join(RUNTIME_DIR, 'src', 'server.js')],
     };
 
     // Register statusLine (top-level setting) and PostToolUse hook
     if (!settings.hooks) settings.hooks = {};
-    const hookPath = join(CLAUDE_DIR, 'hooks', 'context-monitor.js');
-    const statusLineRegistered = registerStatusLine(settings, hookPath);
-    const postToolUseRegistered = registerPostToolUseHook(settings.hooks, hookPath);
-
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    const statuslinePath = join(CLAUDE_DIR, 'hooks', 'gsd-statusline.cjs');
+    const contextMonitorPath = join(CLAUDE_DIR, 'hooks', 'gsd-context-monitor.cjs');
+    const statusLineRegistered = registerStatusLine(settings, statuslinePath);
+    const postToolUseRegistered = registerPostToolUseHook(settings.hooks, contextMonitorPath);
+
+    const tmpSettings = settingsPath + `.${process.pid}-${Date.now()}.tmp`;
+    writeFileSync(tmpSettings, JSON.stringify(settings, null, 2) + '\n');
+    renameSync(tmpSettings, settingsPath);
     log('  ✓ MCP server registered in settings.json');
     if (statusLineRegistered || postToolUseRegistered) {
       log('  ✓ GSD-Lite hooks registered in settings.json');

package/launcher.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Auto-install dependencies and start MCP server
+// Used by plugin system where npm install is not run during /plugin install
+
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+if (!existsSync(join(__dirname, 'node_modules', '@modelcontextprotocol'))) {
+  try {
+    execSync('npm install --omit=dev --ignore-scripts', {
+      cwd: __dirname,
+      stdio: 'pipe',
+    });
+  } catch (err) {
+    console.error('Failed to install dependencies:', err.stderr?.toString() || err.message);
+    process.exit(1);
+  }
+}
+
+const { main } = await import('./src/server.js');
+await main();

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "gsd-lite",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
   "type": "module",
   "bin": {
-    "gsd-lite": "./cli.js"
+    "gsd": "./cli.js"
   },
   "scripts": {
     "test": "node --test tests/*.test.js",
-    "test:coverage": "c8 --reporter=text --reporter=lcov node --test tests/*.test.js",
+    "test:coverage": "c8 --check-coverage --lines 80 --branches 75 --reporter=text --reporter=lcov node --test tests/*.test.js",
     "lint": "biome check src/ tests/ hooks/",
     "lint:fix": "biome check --write src/ tests/ hooks/",
     "start": "node src/server.js"
@@ -35,6 +35,7 @@
     "references/",
     "hooks/",
     "cli.js",
+    "launcher.js",
     "install.js",
     "uninstall.js"
   ],

package/references/questioning.md

@@ -1,6 +1,6 @@
 # 提问技巧参考 (Questioning Reference)
 
-> 本文档供编排器在需求讨论阶段 (`/gsd:start` STEP 1) 使用。
+> 本文档供编排器在需求讨论阶段 (`/gsd:start` STEP 4) 使用。
 > 目标: 通过结构化提问，将模糊需求转化为可执行规格。
 
 ---

package/src/schema.js

@@ -1,5 +1,7 @@
 // State schema + lifecycle validation
 
+import { isPlainObject } from './utils.js';
+
 export const WORKFLOW_MODES = [
   'planning',
   'executing_task',
@@ -21,7 +23,7 @@ export const TASK_LIFECYCLE = {
   checkpointed:         ['accepted', 'needs_revalidation'],
   accepted:             ['needs_revalidation'],
   blocked:              ['pending'],
-  failed:               [],
+  failed:               ['pending'],
   needs_revalidation:   ['pending'],
 };
 
@@ -52,10 +54,6 @@ export const CANONICAL_FIELDS = [
   'evidence',
 ];
 
-function isPlainObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function validateResearchSourcesArray(sources, errors, path = 'sources') {
   if (!Array.isArray(sources)) {
     errors.push(`${path} must be array`);
@@ -423,6 +421,14 @@ export function validateDebuggerResult(r) {
 }
 
 export function createInitialState({ project, phases }) {
+  // Validate task names before creating state
+  for (const [pi, p] of (phases || []).entries()) {
+    for (const [ti, t] of (p.tasks || []).entries()) {
+      if (!t.name || typeof t.name !== 'string') {
+        return { error: true, message: `Phase ${pi + 1} task ${ti + 1}: name is required (got ${JSON.stringify(t.name)})` };
+      }
+    }
+  }
   return {
     project,
     workflow_mode: 'executing_task',