gm-skill 0.1.2 → 2.0.1080

package/lib/learning.js

@@ -0,0 +1,169 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const spool = require('./spool.js');
+
+const RS_LEARN_HOST = '127.0.0.1';
+const RS_LEARN_PORT = 4801;
+const LOG_DIR = path.join(os.homedir(), '.claude', 'gm-log');
+
+let daemonBootstrap = null;
+function getDaemonBootstrap() {
+  if (!daemonBootstrap) {
+    try {
+      daemonBootstrap = require('./daemon-bootstrap.js');
+    } catch (e) {
+      console.error('[learning] Failed to load daemon-bootstrap:', e.message);
+      return null;
+    }
+  }
+  return daemonBootstrap;
+}
+
+let requestIdCounter = 1000;
+
+function getRequestId() {
+  return ++requestIdCounter;
+}
+
+function emitLearningEvent(action, severity, message, details = {}) {
+  try {
+    const date = new Date().toISOString().split('T')[0];
+    const logDir = path.join(LOG_DIR, date);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    const logFile = path.join(logDir, 'learning.jsonl');
+    const entry = {
+      ts: new Date().toISOString(),
+      action,
+      severity,
+      message,
+      ...details,
+    };
+    fs.appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch (e) {
+    console.error(`[learning] Failed to emit event: ${e.message}`);
+  }
+}
+
+async function ensureDaemonRunning(sessionId = null) {
+  const sid = sessionId || process.env.CLAUDE_SESSION_ID || 'unknown';
+  const bootstrap = getDaemonBootstrap();
+
+  if (!bootstrap) {
+    emitLearningEvent('daemon', 'warn', 'daemon-bootstrap not available, skipping spawn', { sessionId: sid });
+    return false;
+  }
+
+  try {
+    const startTime = Date.now();
+    const result = await bootstrap.ensureRsLearningDaemonRunning();
+    emitLearningEvent('daemon', 'info', 'daemon spawn result', {
+      sessionId: sid,
+      ok: result.ok,
+      already_running: result.already_running,
+      durationMs: Date.now() - startTime,
+    });
+    return result.ok === true;
+  } catch (error) {
+    emitLearningEvent('daemon', 'warn', 'daemon spawn failed', {
+      sessionId: sid,
+      error: error.message,
+    });
+    return false;
+  }
+}
+
+async function checkLearningAvailable(timeoutMs = 500) {
+  const sessionId = process.env.CLAUDE_SESSION_ID || 'unknown';
+  try {
+    const result = await spool.execSpool('health', 'health', { timeoutMs, sessionId });
+    const ok = !!(result && result.ok);
+    emitLearningEvent('check', ok ? 'info' : 'warn', ok ? 'rs-learn reachable (spool)' : 'rs-learn unavailable (spool)', { sessionId, timeoutMs });
+    return ok;
+  } catch (e) {
+    emitLearningEvent('check', 'warn', 'rs-learn availability check failed (spool)', { sessionId, timeoutMs, error: e.message });
+    return false;
+  }
+}
+
+async function queryLearning(query, discipline = 'default', sessionId = null) {
+  const sid = sessionId || process.env.CLAUDE_SESSION_ID || 'unknown';
+  const startTime = Date.now();
+
+  try {
+    emitLearningEvent('query', 'info', `Learning query: ${query}`, { sessionId: sid, query, discipline });
+
+    const available = await checkLearningAvailable();
+    if (!available) {
+      emitLearningEvent('query', 'warn', 'Learning unavailable', { sessionId: sid, query });
+      return null;
+    }
+
+    const payload = discipline && discipline !== 'default' ? `@${discipline} ${query}` : query;
+    const result = await spool.execRecall(payload, { timeoutMs: 5000, sessionId: sid });
+    if (!result.ok) throw new Error(result.stderr || result.stdout || 'recall failed');
+
+    emitLearningEvent('query', 'info', 'Learning query completed', {
+      sessionId: sid,
+      query,
+      discipline,
+      hitCount: (result.stdout || '').length > 0 ? 1 : 0,
+      durationMs: Date.now() - startTime,
+    });
+
+    return result.stdout || '';
+  } catch (error) {
+    emitLearningEvent('query', 'error', `Learning query failed: ${query}`, {
+      sessionId: sid,
+      query,
+      error: error.message,
+      durationMs: Date.now() - startTime,
+    });
+    return null;
+  }
+}
+
+async function persistLearning(fact, discipline = 'default', sessionId = null) {
+  const sid = sessionId || process.env.CLAUDE_SESSION_ID || 'unknown';
+  const startTime = Date.now();
+
+  try {
+    emitLearningEvent('persist', 'info', 'Learning persist initiated', { sessionId: sid, discipline, factLength: fact.length });
+
+    const available = await checkLearningAvailable();
+    if (!available) {
+      emitLearningEvent('persist', 'error', 'Learning unavailable for persist', { sessionId: sid, discipline });
+      throw new Error('rs-learn daemon not available');
+    }
+
+    const payload = discipline && discipline !== 'default' ? `@${discipline}\n${fact}` : fact;
+    const result = await spool.execMemorize(payload, { timeoutMs: 5000, sessionId: sid });
+    if (!result.ok) throw new Error(result.stderr || result.stdout || 'memorize failed');
+
+    emitLearningEvent('persist', 'info', 'Learning persist completed', {
+      sessionId: sid,
+      discipline,
+      durationMs: Date.now() - startTime,
+    });
+
+    return result;
+  } catch (error) {
+    emitLearningEvent('persist', 'error', `Learning persist failed: ${error.message}`, {
+      sessionId: sid,
+      discipline,
+      durationMs: Date.now() - startTime,
+    });
+    throw error;
+  }
+}
+
+module.exports = {
+  checkLearningAvailable,
+  queryLearning,
+  persistLearning,
+  ensureDaemonRunning,
+  RS_LEARN_HOST,
+  RS_LEARN_PORT,
+};

package/lib/skill-bootstrap.js

@@ -0,0 +1,406 @@
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { execSync, spawn } = require('child_process');
+const crypto = require('crypto');
+const os = require('os');
+const spool = require('./spool.js');
+
+const PLUGKIT_TOOLS_DIR = path.join(os.homedir(), '.claude', 'gm-tools');
+const PLUGKIT_VERSION_FILE = path.join(PLUGKIT_TOOLS_DIR, 'plugkit.version');
+const PLUGKIT_WASM_PATH = path.join(PLUGKIT_TOOLS_DIR, 'plugkit.wasm');
+const PLUGKIT_WASM_WRAPPER = path.join(PLUGKIT_TOOLS_DIR, 'plugkit-wasm-wrapper.js');
+const BOOTSTRAP_STATUS_FILE = path.join(os.homedir(), '.gm', 'bootstrap-status.json');
+const BOOTSTRAP_ERROR_FILE = path.join(os.homedir(), '.gm', 'bootstrap-error.json');
+const LOG_DIR = path.join(os.homedir(), '.claude', 'gm-log');
+
+function getPlugkitPath() {
+  if (fs.existsSync(PLUGKIT_WASM_WRAPPER) && fs.existsSync(PLUGKIT_WASM_PATH)) {
+    return PLUGKIT_WASM_WRAPPER;
+  }
+  throw new Error(`plugkit WASM not found at ${PLUGKIT_WASM_PATH}`);
+}
+
+function emitBootstrapEvent(severity, message, details) {
+  try {
+    const date = new Date().toISOString().split('T')[0];
+    const logDir = path.join(LOG_DIR, date);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    const logFile = path.join(logDir, 'bootstrap.jsonl');
+    const entry = {
+      ts: new Date().toISOString(),
+      severity,
+      message,
+      ...details,
+    };
+    fs.appendFileSync(logFile, JSON.stringify(entry) + '\n');
+  } catch (e) {
+    console.error(`[bootstrap] Failed to emit event: ${e.message}`);
+  }
+}
+
+function readManifest() {
+  try {
+    const gmJsonPath = path.join(process.cwd(), 'gm-starter', 'gm.json');
+    if (!fs.existsSync(gmJsonPath)) {
+      throw new Error('gm-starter/gm.json not found');
+    }
+    const gm = JSON.parse(fs.readFileSync(gmJsonPath, 'utf8'));
+    const version = gm.plugkitVersion;
+
+    const sha256Path = path.join(process.cwd(), 'gm-starter', 'bin', 'plugkit.wasm.sha256');
+    if (!fs.existsSync(sha256Path)) {
+      throw new Error('gm-starter/bin/plugkit.wasm.sha256 not found');
+    }
+    const sha256Content = fs.readFileSync(sha256Path, 'utf8').trim();
+    const expectedHash = sha256Content.split(/\s+/)[0];
+
+    return { version, expectedHash };
+  } catch (e) {
+    emitBootstrapEvent('error', 'Failed to read manifest', { error: e.message });
+    throw e;
+  }
+}
+
+function getInstalledVersion() {
+  try {
+    if (fs.existsSync(PLUGKIT_VERSION_FILE)) {
+      return fs.readFileSync(PLUGKIT_VERSION_FILE, 'utf8').trim();
+    }
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function computeFileHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+async function downloadPlugkitBinary(version) {
+  const binaryName = 'plugkit.wasm';
+  const url = `https://github.com/AnEntrypoint/plugkit-bin/releases/download/v${version}/${binaryName}`;
+
+  emitBootstrapEvent('info', 'Starting WASM download', { version, url });
+
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { timeout: 30000 }, (res) => {
+        if (res.statusCode === 404) {
+          reject(new Error(`WASM not found: v${version}`));
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode} downloading plugkit.wasm`));
+          return;
+        }
+
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const data = Buffer.concat(chunks);
+          emitBootstrapEvent('info', 'WASM download complete', { bytes: data.length });
+          resolve(data);
+        });
+      })
+      .on('error', (e) => {
+        emitBootstrapEvent('error', 'Download failed', { error: e.message });
+        reject(e);
+      });
+  });
+}
+
+function isProcessRunning(pidOrName) {
+  try {
+    const plat = getPlatformKey();
+    if (plat === 'win32') {
+      const output = execSync('tasklist /FO CSV /NH', { encoding: 'utf8' });
+      const lines = output.split('\n').filter(Boolean);
+      return lines.some(line => {
+        const parts = line.split(',').map(p => p.trim().replace(/^"/, '').replace(/"$/, ''));
+        return parts[0] === 'plugkit.exe' || parts[0] === pidOrName;
+      });
+    } else {
+      try {
+        execSync(`ps -p ${pidOrName} > /dev/null 2>&1`);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  } catch (e) {
+    return false;
+  }
+}
+
+function killExistingPlugkit() {
+  try {
+    const plat = getPlatformKey();
+    if (plat === 'win32') {
+      execSync('taskkill /IM plugkit.exe /F 2>nul || true', { shell: true });
+      emitBootstrapEvent('info', 'Killed existing plugkit process on Windows');
+    } else {
+      execSync('pkill -f "plugkit" || true', { shell: true });
+      emitBootstrapEvent('info', 'Killed existing plugkit process on Unix');
+    }
+  } catch (e) {
+    emitBootstrapEvent('warn', 'Failed to kill existing plugkit', { error: e.message });
+  }
+}
+
+async function ensureBinaryWritable(filePath) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  } catch (e) {
+    throw new Error(`Cannot write to ${filePath}: ${e.message}`);
+  }
+}
+
+async function writeBinaryWithRetry(filePath, data, maxRetries = 3) {
+  let lastErr;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      await ensureBinaryWritable(filePath);
+      fs.writeFileSync(filePath, data);
+      fs.chmodSync(filePath, 0o755);
+      emitBootstrapEvent('info', 'Binary written successfully', { path: filePath });
+      return;
+    } catch (e) {
+      lastErr = e;
+      emitBootstrapEvent('warn', `Write attempt ${attempt + 1} failed`, { error: e.message });
+      if (attempt < maxRetries - 1) {
+        await new Promise(r => setTimeout(r, 50 * Math.pow(2, attempt)));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+async function verifyBinaryHealth(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    const stat = fs.statSync(filePath);
+    if (stat.size < 1024) {
+      throw new Error(`File too small: ${stat.size} bytes`);
+    }
+    emitBootstrapEvent('info', 'Binary health check passed', { size: stat.size });
+    return true;
+  } catch (e) {
+    emitBootstrapEvent('warn', 'Binary health check failed', { error: e.message });
+    return false;
+  }
+}
+
+async function spawnPlugkitWatcher(wasmPath) {
+  try {
+    emitBootstrapEvent('info', 'Spawning plugkit WASM watcher daemon');
+
+    let wrapperPath;
+    try {
+      const gmPlugkit = require('gm-plugkit');
+      wrapperPath = path.join(path.dirname(gmPlugkit.getPath ? gmPlugkit.getPath() : require.resolve('gm-plugkit')), 'plugkit-wasm-wrapper.js');
+    } catch (e) {
+      emitBootstrapEvent('warn', 'gm-plugkit npm not available, using bundled wrapper', { error: e.message });
+      wrapperPath = path.join(path.dirname(wasmPath), 'plugkit-wasm-wrapper.js');
+    }
+
+    if (!fs.existsSync(wrapperPath)) {
+      throw new Error(`WASM wrapper not found at ${wrapperPath}`);
+    }
+
+    const runtime = process.platform === 'win32' ? 'bun.exe' : 'bun';
+    const proc = spawn(runtime, [wrapperPath, 'spool'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() },
+    });
+
+    const pid = proc.pid;
+    proc.unref();
+
+    emitBootstrapEvent('info', 'Plugkit WASM watcher spawned', { pid });
+    return pid;
+  } catch (e) {
+    emitBootstrapEvent('error', 'Failed to spawn plugkit WASM watcher', { error: e.message });
+    throw e;
+  }
+}
+
+async function bootstrapPlugkit() {
+  const startTime = Date.now();
+
+  try {
+    emitBootstrapEvent('info', 'Bootstrap started');
+
+    const { version: manifestVersion, expectedHash } = readManifest();
+    const installedVersion = getInstalledVersion();
+    const plugkitPath = getPlugkitPath();
+
+    const versionMismatch = installedVersion !== manifestVersion;
+    const binaryMissing = !fs.existsSync(plugkitPath);
+
+    if (!binaryMissing && !versionMismatch) {
+      emitBootstrapEvent('info', 'Binary up-to-date', { version: installedVersion });
+
+      if (isProcessRunning('plugkit')) {
+        emitBootstrapEvent('info', 'Plugkit watcher already running');
+        const statusPayload = {
+          ok: true,
+          version: installedVersion,
+          status: 'running',
+          timestamp: new Date().toISOString(),
+          durationMs: Date.now() - startTime,
+        };
+        fs.mkdirSync(path.dirname(BOOTSTRAP_STATUS_FILE), { recursive: true });
+        fs.writeFileSync(BOOTSTRAP_STATUS_FILE, JSON.stringify(statusPayload, null, 2));
+        return { ok: true };
+      }
+    }
+
+    if (binaryMissing || versionMismatch) {
+      emitBootstrapEvent('info', 'Downloading binary', {
+        reason: binaryMissing ? 'missing' : 'version-mismatch',
+        version: manifestVersion,
+      });
+
+      let binaryData;
+      try {
+        binaryData = await downloadPlugkitBinary(manifestVersion);
+      } catch (downloadErr) {
+        emitBootstrapEvent('error', 'Download failed, checking for cached binary', {
+          error: downloadErr.message,
+          fallback: fs.existsSync(plugkitPath),
+        });
+
+        if (!fs.existsSync(plugkitPath)) {
+          throw downloadErr;
+        }
+        emitBootstrapEvent('info', 'Using cached binary as fallback');
+        binaryData = null;
+      }
+
+      if (binaryData) {
+        const downloadedHash = crypto.createHash('sha256').update(binaryData).digest('hex');
+        if (downloadedHash !== expectedHash) {
+          throw new Error(`Hash mismatch: got ${downloadedHash}, expected ${expectedHash}`);
+        }
+
+        killExistingPlugkit();
+        await writeBinaryWithRetry(plugkitPath, binaryData);
+
+        fs.mkdirSync(path.dirname(PLUGKIT_VERSION_FILE), { recursive: true });
+        fs.writeFileSync(PLUGKIT_VERSION_FILE, manifestVersion + '\n');
+        emitBootstrapEvent('info', 'Binary installed', { version: manifestVersion });
+      }
+    }
+
+    const isHealthy = await verifyBinaryHealth(plugkitPath);
+    if (!isHealthy) {
+      emitBootstrapEvent('warn', 'Binary health check failed, but proceeding');
+    }
+
+    const watcherRunning = isProcessRunning('plugkit');
+    let watcherPid;
+    if (!watcherRunning) {
+      watcherPid = await spawnPlugkitWatcher(plugkitPath);
+    } else {
+      watcherPid = 'already-running';
+      emitBootstrapEvent('info', 'Watcher already running');
+    }
+
+    const currentVersion = getInstalledVersion() || manifestVersion;
+    const statusPayload = {
+      ok: true,
+      version: currentVersion,
+      watcherPid,
+      timestamp: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+    };
+
+    fs.mkdirSync(path.dirname(BOOTSTRAP_STATUS_FILE), { recursive: true });
+    fs.writeFileSync(BOOTSTRAP_STATUS_FILE, JSON.stringify(statusPayload, null, 2));
+
+    emitBootstrapEvent('info', 'Bootstrap completed successfully', statusPayload);
+    return { ok: true };
+  } catch (err) {
+    const errorPayload = {
+      ok: false,
+      error: err.message,
+      timestamp: new Date().toISOString(),
+      durationMs: Date.now() - startTime,
+      stack: err.stack,
+    };
+
+    fs.mkdirSync(path.dirname(BOOTSTRAP_ERROR_FILE), { recursive: true });
+    fs.writeFileSync(BOOTSTRAP_ERROR_FILE, JSON.stringify(errorPayload, null, 2));
+
+    emitBootstrapEvent('error', 'Bootstrap failed', errorPayload);
+    console.error(`[skill-bootstrap] ${err.message}`);
+
+    return { ok: false, error: err.message };
+  }
+}
+
+async function checkPortReachable(host, port, timeoutMs = 500) {
+  try {
+    const result = await spool.execSpool('health', 'health', { timeoutMs, sessionId: process.env.CLAUDE_SESSION_ID || 'unknown' });
+    return !!(result && result.ok);
+  } catch (e) {
+    return false;
+  }
+}
+
+async function bootstrapAcptoapi() {
+  const port = 4800;
+  const running = await checkPortReachable('127.0.0.1', port);
+  if (running) return { ok: true, status: 'already-running' };
+
+  emitBootstrapEvent('info', 'Spawning acptoapi daemon');
+  try {
+    const child = spawn('bun', ['x', 'acptoapi@latest'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+    emitBootstrapEvent('info', 'acptoapi spawned', { pid: child.pid });
+    return { ok: true, status: 'spawned', pid: child.pid };
+  } catch (e) {
+    emitBootstrapEvent('error', 'Failed to spawn acptoapi', { error: e.message });
+    return { ok: false, error: e.message };
+  }
+}
+
+async function getSnapshot(sessionId, cwd) {
+  const plugkitPath = getPlugkitPath();
+  if (!fs.existsSync(plugkitPath)) {
+    return { git: { ok: false }, tasks: [], error: 'plugkit not found' };
+  }
+
+  try {
+    const sid = sessionId || process.env.CLAUDE_SESSION_ID || 'default';
+    const c = cwd || process.cwd();
+    const cmd = `"${plugkitPath}" snapshot --session "${sid}" --cwd "${c}"`;
+    const output = execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return JSON.parse(output);
+  } catch (e) {
+    emitBootstrapEvent('warn', 'Failed to get snapshot', { error: e.message });
+    return { git: { ok: false }, tasks: [], error: e.message };
+  }
+}
+
+module.exports = { 
+  bootstrapPlugkit,
+  bootstrapAcptoapi,
+  getSnapshot,
+  checkPortReachable
+};

package/lib/spool-dispatch.js

@@ -0,0 +1,100 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+async function dispatchSpool(cmd, lang, body, timeoutMs, sessionId) {
+  const taskId = `${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+  const langDir = lang.match(/^(nodejs|python|bash|typescript|go|rust|c|cpp|java|deno)$/) ? lang : 'nodejs';
+  const ext = {
+    nodejs: 'js',
+    python: 'py',
+    bash: 'sh',
+    typescript: 'ts',
+    go: 'go',
+    rust: 'rs',
+    c: 'c',
+    cpp: 'cpp',
+    java: 'java',
+    deno: 'ts'
+  }[langDir] || 'js';
+
+  const inDir = path.join(process.cwd(), '.gm', 'exec-spool', 'in', langDir);
+  const outDir = path.join(process.cwd(), '.gm', 'exec-spool', 'out');
+  const inFile = path.join(inDir, `${taskId}.${ext}`);
+  const jsonFile = path.join(outDir, `${taskId}.json`);
+
+  fs.mkdirSync(inDir, { recursive: true });
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const code = sessionId ? `const SESSION_ID = '${sessionId}';\n${body}` : body;
+  fs.writeFileSync(inFile, code, 'utf8');
+
+  return pollForCompletion(jsonFile, timeoutMs, taskId);
+}
+
+async function pollForCompletion(jsonFile, timeoutMs, taskId) {
+  const start = Date.now();
+  const interval = 50;
+
+  while (Date.now() - start < timeoutMs) {
+    if (fs.existsSync(jsonFile)) {
+      try {
+        const metadata = JSON.parse(fs.readFileSync(jsonFile, 'utf8'));
+        const outFile = jsonFile.replace(/\.json$/, '.out');
+        const errFile = jsonFile.replace(/\.json$/, '.err');
+        const stdout = fs.existsSync(outFile) ? fs.readFileSync(outFile, 'utf8') : '';
+        const stderr = fs.existsSync(errFile) ? fs.readFileSync(errFile, 'utf8') : '';
+        return {
+          ok: metadata.exitCode === 0 && !metadata.timedOut,
+          exitCode: metadata.exitCode,
+          stdout,
+          stderr,
+          durationMs: metadata.durationMs,
+          taskId,
+          timedOut: metadata.timedOut || false
+        };
+      } catch (e) {
+        await new Promise(r => setTimeout(r, interval));
+      }
+    } else {
+      await new Promise(r => setTimeout(r, interval));
+    }
+  }
+
+  return {
+    ok: false,
+    exitCode: -1,
+    stdout: '',
+    stderr: `[spool dispatch timeout after ${timeoutMs}ms]`,
+    durationMs: Date.now() - start,
+    taskId,
+    timedOut: true
+  };
+}
+
+function checkDispatchGates(sessionId, operation) {
+  const gm = path.join(process.cwd(), '.gm');
+  const prdPath = path.join(gm, 'prd.yml');
+  const mutsPath = path.join(gm, 'mutables.yml');
+  const needsGmPath = path.join(gm, 'needs-gm');
+  const gmFiredPath = path.join(gm, `gm-fired-${sessionId}`);
+
+  if (!['write', 'edit', 'git'].includes(operation)) return { allowed: true };
+
+  if (fs.existsSync(prdPath) && fs.existsSync(needsGmPath) && !fs.existsSync(gmFiredPath)) {
+    return { allowed: false, reason: 'gm orchestration in progress; skills must complete work before tools execute' };
+  }
+
+  if (fs.existsSync(mutsPath)) {
+    try {
+      const content = fs.readFileSync(mutsPath, 'utf8');
+      if (content.includes('status: unknown')) {
+        return { allowed: false, reason: 'unresolved mutables block tool execution; resolve all mutables before proceeding' };
+      }
+    } catch (_) {}
+  }
+
+  return { allowed: true };
+}
+
+module.exports = { dispatchSpool, checkDispatchGates };