@whitehatd/crag 0.2.2 → 0.2.4

package/src/commands/check.js

@@ -2,54 +2,87 @@
 
 const fs = require('fs');
 const path = require('path');
+const { EXIT_USER } = require('../cli-errors');
 
-function check() {
+const CORE_CHECKS = [
+  ['.claude/skills/pre-start-context/SKILL.md', 'Pre-start skill (universal)'],
+  ['.claude/skills/post-start-validation/SKILL.md', 'Post-start skill (universal)'],
+  ['.claude/governance.md', 'Governance rules'],
+  ['.claude/hooks/drift-detector.sh', 'Drift detector hook'],
+  ['.claude/hooks/circuit-breaker.sh', 'Circuit breaker hook'],
+  ['.claude/agents/test-runner.md', 'Test runner agent'],
+  ['.claude/agents/security-reviewer.md', 'Security reviewer agent'],
+  ['.claude/ci-playbook.md', 'CI playbook'],
+  ['.claude/settings.local.json', 'Settings with hooks'],
+];
+
+const OPTIONAL_CHECKS = [
+  ['.claude/.session-name', 'Session name (remote access)'],
+  ['.claude/hooks/pre-compact-snapshot.sh', 'Pre-compact hook (MemStack)'],
+  ['.claude/hooks/post-compact-recovery.sh', 'Post-compact hook (MemStack)'],
+  ['.claude/rules/knowledge.md', 'MemStack knowledge rule'],
+  ['.claude/rules/diary.md', 'MemStack diary rule'],
+  ['.claude/rules/echo.md', 'MemStack echo rule'],
+];
+
+/**
+ * Probe the filesystem and return a structured report of crag infrastructure.
+ * Exported for testing — the CLI wraps this and prints.
+ */
+function runChecks(cwd) {
+  const core = CORE_CHECKS.map(([file, name]) => ({
+    file,
+    name,
+    present: fs.existsSync(path.join(cwd, file)),
+  }));
+  const optional = OPTIONAL_CHECKS.map(([file, name]) => ({
+    file,
+    name,
+    present: fs.existsSync(path.join(cwd, file)),
+  }));
+  const missing = core.filter((c) => !c.present).length;
+  return {
+    cwd,
+    core,
+    optional,
+    missing,
+    total: core.length,
+    complete: missing === 0,
+  };
+}
+
+function check(args = []) {
   const cwd = process.cwd();
-  const checks = [
-    ['.claude/skills/pre-start-context/SKILL.md', 'Pre-start skill (universal)'],
-    ['.claude/skills/post-start-validation/SKILL.md', 'Post-start skill (universal)'],
-    ['.claude/governance.md', 'Governance rules'],
-    ['.claude/hooks/drift-detector.sh', 'Drift detector hook'],
-    ['.claude/hooks/circuit-breaker.sh', 'Circuit breaker hook'],
-    ['.claude/agents/test-runner.md', 'Test runner agent'],
-    ['.claude/agents/security-reviewer.md', 'Security reviewer agent'],
-    ['.claude/ci-playbook.md', 'CI playbook'],
-    ['.claude/settings.local.json', 'Settings with hooks'],
-  ];
-
-  const optional = [
-    ['.claude/.session-name', 'Session name (remote access)'],
-    ['.claude/hooks/pre-compact-snapshot.sh', 'Pre-compact hook (MemStack)'],
-    ['.claude/hooks/post-compact-recovery.sh', 'Post-compact hook (MemStack)'],
-    ['.claude/rules/knowledge.md', 'MemStack knowledge rule'],
-    ['.claude/rules/diary.md', 'MemStack diary rule'],
-    ['.claude/rules/echo.md', 'MemStack echo rule'],
-  ];
+  const report = runChecks(cwd);
+
+  // --json: machine-readable output, no colors, no prose
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(report, null, 2));
+    if (!report.complete) process.exit(EXIT_USER);
+    return;
+  }
 
   console.log(`\n  Checking crag infrastructure in ${cwd}\n`);
 
   console.log(`  Core:`);
-  let missing = 0;
-  for (const [file, name] of checks) {
-    const exists = fs.existsSync(path.join(cwd, file));
-    const icon = exists ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
-    console.log(`    ${icon} ${name}`);
-    if (!exists) missing++;
+  for (const c of report.core) {
+    const icon = c.present ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    console.log(`    ${icon} ${c.name}`);
   }
 
   console.log(`\n  Optional:`);
-  for (const [file, name] of optional) {
-    const exists = fs.existsSync(path.join(cwd, file));
-    const icon = exists ? '\x1b[32m✓\x1b[0m' : '\x1b[90m○\x1b[0m';
-    console.log(`    ${icon} ${name}`);
+  for (const o of report.optional) {
+    const icon = o.present ? '\x1b[32m✓\x1b[0m' : '\x1b[90m○\x1b[0m';
+    console.log(`    ${icon} ${o.name}`);
   }
 
-  console.log(`\n  ${checks.length - missing}/${checks.length} core files present.`);
-  if (missing > 0) {
+  console.log(`\n  ${report.total - report.missing}/${report.total} core files present.`);
+  if (report.missing > 0) {
     console.log(`  Run 'crag init' to generate missing files.\n`);
+    process.exit(EXIT_USER);
   } else {
     console.log(`  Infrastructure complete.\n`);
   }
 }
 
-module.exports = { check };
+module.exports = { check, runChecks, CORE_CHECKS, OPTIONAL_CHECKS };

package/src/commands/compile.js

@@ -15,6 +15,7 @@ const { generateContinue } = require('../compile/continue');
 const { generateWindsurf } = require('../compile/windsurf');
 const { generateZed } = require('../compile/zed');
 const { generateCody } = require('../compile/cody');
+const { cliError, readFileOrExit, EXIT_USER, EXIT_INTERNAL } = require('../cli-errors');
 
 // All supported compile targets in dispatch order.
 // Grouped: CI (3) + AI agent native (3) + AI agent extras (6)
@@ -36,16 +37,19 @@ const ALL_TARGETS = [
 function compile(args) {
   const targetIdx = args.indexOf('--target');
   const target = targetIdx !== -1 ? args[targetIdx + 1] : args[1];
+  const dryRun = args.includes('--dry-run');
   const cwd = process.cwd();
   const govPath = path.join(cwd, '.claude', 'governance.md');
 
   if (!fs.existsSync(govPath)) {
-    console.error('  Error: No .claude/governance.md found. Run crag init first.');
-    process.exit(1);
+    cliError('no .claude/governance.md found. Run crag init or crag analyze first.', EXIT_USER);
   }
 
-  const content = fs.readFileSync(govPath, 'utf-8');
+  const content = readFileOrExit(fs, govPath, 'governance.md');
   const parsed = parseGovernance(content);
+  if (parsed.warnings && parsed.warnings.length > 0) {
+    for (const w of parsed.warnings) console.warn(`  \x1b[33m!\x1b[0m ${w}`);
+  }
   const flat = flattenGates(parsed.gates);
   const gateCount = Object.values(flat).flat().length;
 
@@ -68,37 +72,80 @@ function compile(args) {
     console.log('    crag compile --target zed          .zed/rules.md');
     console.log('    crag compile --target cody         .sourcegraph/cody-instructions.md\n');
     console.log('  Combined:');
-    console.log('    crag compile --target all          All 12 targets at once\n');
+    console.log('    crag compile --target all          All 12 targets at once');
+    console.log('    crag compile --target <t> --dry-run  Preview paths without writing\n');
     return;
   }
 
   const targets = target === 'all' ? ALL_TARGETS : [target];
 
   console.log(`\n  Compiling governance.md → ${targets.join(', ')}`);
-  console.log(`  ${gateCount} gates, ${parsed.runtimes.length} runtimes detected\n`);
+  console.log(`  ${gateCount} gates, ${parsed.runtimes.length} runtimes detected${dryRun ? ' (dry-run)' : ''}\n`);
 
-  for (const t of targets) {
-    switch (t) {
-      case 'github':     generateGitHubActions(cwd, parsed); break;
-      case 'husky':      generateHusky(cwd, parsed); break;
-      case 'pre-commit': generatePreCommitConfig(cwd, parsed); break;
-      case 'agents-md':  generateAgentsMd(cwd, parsed); break;
-      case 'cursor':     generateCursorRules(cwd, parsed); break;
-      case 'gemini':     generateGeminiMd(cwd, parsed); break;
-      case 'copilot':    generateCopilot(cwd, parsed); break;
-      case 'cline':      generateCline(cwd, parsed); break;
-      case 'continue':   generateContinue(cwd, parsed); break;
-      case 'windsurf':   generateWindsurf(cwd, parsed); break;
-      case 'zed':        generateZed(cwd, parsed); break;
-      case 'cody':       generateCody(cwd, parsed); break;
-      default:
+  // --dry-run: print the planned output paths without writing files.
+  if (dryRun) {
+    for (const t of targets) {
+      const outPath = planOutputPath(cwd, t);
+      if (outPath) {
+        console.log(`  \x1b[36mplan\x1b[0m ${path.relative(cwd, outPath)}`);
+      } else {
         console.error(`  Unknown target: ${t}`);
         console.error(`  Valid targets: ${ALL_TARGETS.join(', ')}, all, list`);
-        process.exit(1);
+        process.exit(EXIT_USER);
+      }
     }
+    console.log('\n  Dry-run complete — no files written.\n');
+    return;
+  }
+
+  try {
+    for (const t of targets) {
+      switch (t) {
+        case 'github':     generateGitHubActions(cwd, parsed); break;
+        case 'husky':      generateHusky(cwd, parsed); break;
+        case 'pre-commit': generatePreCommitConfig(cwd, parsed); break;
+        case 'agents-md':  generateAgentsMd(cwd, parsed); break;
+        case 'cursor':     generateCursorRules(cwd, parsed); break;
+        case 'gemini':     generateGeminiMd(cwd, parsed); break;
+        case 'copilot':    generateCopilot(cwd, parsed); break;
+        case 'cline':      generateCline(cwd, parsed); break;
+        case 'continue':   generateContinue(cwd, parsed); break;
+        case 'windsurf':   generateWindsurf(cwd, parsed); break;
+        case 'zed':        generateZed(cwd, parsed); break;
+        case 'cody':       generateCody(cwd, parsed); break;
+        default:
+          console.error(`  Unknown target: ${t}`);
+          console.error(`  Valid targets: ${ALL_TARGETS.join(', ')}, all, list`);
+          process.exit(EXIT_USER);
+      }
+    }
+  } catch (err) {
+    cliError(`compile failed: ${err.message}`, EXIT_INTERNAL);
   }
 
   console.log('\n  Done. Governance is now executable infrastructure.\n');
 }
 
-module.exports = { compile, ALL_TARGETS };
+/**
+ * Map a target name to its destination path relative to cwd.
+ * Used by --dry-run to show what would be written.
+ */
+function planOutputPath(cwd, target) {
+  const map = {
+    'github':     path.join(cwd, '.github', 'workflows', 'gates.yml'),
+    'husky':      path.join(cwd, '.husky', 'pre-commit'),
+    'pre-commit': path.join(cwd, '.pre-commit-config.yaml'),
+    'agents-md':  path.join(cwd, 'AGENTS.md'),
+    'cursor':     path.join(cwd, '.cursor', 'rules', 'governance.mdc'),
+    'gemini':     path.join(cwd, 'GEMINI.md'),
+    'copilot':    path.join(cwd, '.github', 'copilot-instructions.md'),
+    'cline':      path.join(cwd, '.clinerules'),
+    'continue':   path.join(cwd, '.continuerules'),
+    'windsurf':   path.join(cwd, '.windsurfrules'),
+    'zed':        path.join(cwd, '.zed', 'rules.md'),
+    'cody':       path.join(cwd, '.sourcegraph', 'cody-instructions.md'),
+  };
+  return map[target] || null;
+}
+
+module.exports = { compile, ALL_TARGETS, planOutputPath };

package/src/commands/diff.js

@@ -4,6 +4,8 @@ const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const { parseGovernance, flattenGates } = require('../governance/parse');
+const { extractRunCommands, isGateCommand } = require('../governance/yaml-run');
+const { cliError, EXIT_USER, EXIT_INTERNAL, readFileOrExit } = require('../cli-errors');
 
 /**
  * crag diff — compare governance.md against codebase reality.
@@ -13,12 +15,14 @@ function diff(args) {
   const govPath = path.join(cwd, '.claude', 'governance.md');
 
   if (!fs.existsSync(govPath)) {
-    console.error('  Error: No .claude/governance.md found. Run crag init or crag analyze first.');
-    process.exit(1);
+    cliError('no .claude/governance.md found. Run crag init or crag analyze first.', EXIT_USER);
   }
 
-  const content = fs.readFileSync(govPath, 'utf-8');
+  const content = readFileOrExit(fs, govPath, 'governance.md');
   const parsed = parseGovernance(content);
+  if (parsed.warnings && parsed.warnings.length > 0) {
+    for (const w of parsed.warnings) console.warn(`  \x1b[33m!\x1b[0m ${w}`);
+  }
   const flat = flattenGates(parsed.gates);
 
   console.log(`\n  Governance vs Reality — ${parsed.name || 'project'}\n`);
@@ -169,46 +173,8 @@ function extractCIGateCommands(cwd) {
   return gates;
 }
 
-/**
- * Extract commands from YAML `run:` steps, handling block scalars.
- */
-function extractRunCommands(content) {
-  const commands = [];
-  const lines = content.split(/\r?\n/);
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const m = line.match(/^(\s*)-?\s*run:\s*(.*)$/);
-    if (!m) continue;
-
-    const baseIndent = m[1].length;
-    const rest = m[2].trim();
-
-    if (/^[|>][+-]?\s*$/.test(rest)) {
-      // Block scalar
-      for (let j = i + 1; j < lines.length; j++) {
-        const ln = lines[j];
-        if (ln.trim() === '') continue;
-        const indentMatch = ln.match(/^(\s*)/);
-        if (indentMatch[1].length <= baseIndent) break;
-        const trimmed = ln.trim();
-        if (trimmed && !trimmed.startsWith('#')) commands.push(trimmed);
-      }
-    } else if (rest && !rest.startsWith('#')) {
-      commands.push(rest.replace(/^["']|["']$/g, ''));
-    }
-  }
-
-  return commands;
-}
-
-function isGateCommand(cmd) {
-  const patterns = [
-    /npm (run|test|ci)/, /npx /, /node /, /cargo /, /go (test|build|vet)/,
-    /pytest/, /ruff/, /mypy/, /eslint/, /biome/, /prettier/, /tsc/, /gradle/,
-  ];
-  return patterns.some(p => p.test(cmd));
-}
+// extractRunCommands and isGateCommand now live in src/governance/yaml-run.js
+// and are re-exported below for backward compatibility with existing tests.
 
 /**
  * Normalize commands to a canonical form for equality comparison.
@@ -287,3 +253,4 @@ function hasNpmScript(cwd, script) {
 }
 
 module.exports = { diff, normalizeCmd, extractRunCommands, isGateCommand };
+

package/src/commands/init.js

@@ -2,46 +2,66 @@
 
 const { execSync, spawn } = require('child_process');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const { cliError, EXIT_USER, EXIT_INTERNAL } = require('../cli-errors');
 
 const SRC = path.join(__dirname, '..');
 const AGENT_SRC = path.join(SRC, 'crag-agent.md');
 const PRE_START_SRC = path.join(SRC, 'skills', 'pre-start-context.md');
 const POST_START_SRC = path.join(SRC, 'skills', 'post-start-validation.md');
-const GLOBAL_AGENT_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'agents');
+
+// Use os.homedir() as the authoritative source — fall back only if it returns
+// empty (extremely rare, e.g. stripped-down containers). Never pass undefined
+// to path.join, which throws ERR_INVALID_ARG_TYPE.
+function resolveHomeDir() {
+  const h = os.homedir();
+  if (h && h.length > 0) return h;
+  return process.env.HOME || process.env.USERPROFILE || os.tmpdir();
+}
+
+const GLOBAL_AGENT_DIR = path.join(resolveHomeDir(), '.claude', 'agents');
 const GLOBAL_AGENT_PATH = path.join(GLOBAL_AGENT_DIR, 'crag-project.md');
 
 function install() {
-  if (!fs.existsSync(GLOBAL_AGENT_DIR)) {
-    fs.mkdirSync(GLOBAL_AGENT_DIR, { recursive: true });
+  try {
+    if (!fs.existsSync(GLOBAL_AGENT_DIR)) {
+      fs.mkdirSync(GLOBAL_AGENT_DIR, { recursive: true });
+    }
+    fs.copyFileSync(AGENT_SRC, GLOBAL_AGENT_PATH);
+    console.log(`  Installed crag-project agent to ${GLOBAL_AGENT_PATH}`);
+    console.log(`  Run /crag-project from any Claude Code session.`);
+  } catch (err) {
+    cliError(`failed to install global agent: ${err.message}`, EXIT_INTERNAL);
   }
-  fs.copyFileSync(AGENT_SRC, GLOBAL_AGENT_PATH);
-  console.log(`  Installed crag-project agent to ${GLOBAL_AGENT_PATH}`);
-  console.log(`  Run /crag-project from any Claude Code session.`);
 }
 
 function installSkills(targetDir) {
-  const skillDirs = [
-    path.join(targetDir, '.claude', 'skills', 'pre-start-context'),
-    path.join(targetDir, '.claude', 'skills', 'post-start-validation'),
-    path.join(targetDir, '.agents', 'workflows'),
-  ];
-
-  for (const dir of skillDirs) {
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  }
+  try {
+    const skillDirs = [
+      path.join(targetDir, '.claude', 'skills', 'pre-start-context'),
+      path.join(targetDir, '.claude', 'skills', 'post-start-validation'),
+      path.join(targetDir, '.agents', 'workflows'),
+    ];
+
+    for (const dir of skillDirs) {
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    }
 
-  // Copy skills
-  fs.copyFileSync(PRE_START_SRC, path.join(targetDir, '.claude', 'skills', 'pre-start-context', 'SKILL.md'));
-  fs.copyFileSync(POST_START_SRC, path.join(targetDir, '.claude', 'skills', 'post-start-validation', 'SKILL.md'));
+    // Copy skills
+    fs.copyFileSync(PRE_START_SRC, path.join(targetDir, '.claude', 'skills', 'pre-start-context', 'SKILL.md'));
+    fs.copyFileSync(POST_START_SRC, path.join(targetDir, '.claude', 'skills', 'post-start-validation', 'SKILL.md'));
 
-  // Workflow copies (remove name: line)
-  for (const [src, name] of [[PRE_START_SRC, 'pre-start-context.md'], [POST_START_SRC, 'post-start-validation.md']]) {
-    const content = fs.readFileSync(src, 'utf-8').replace(/^name:.*\n/m, '');
-    fs.writeFileSync(path.join(targetDir, '.agents', 'workflows', name), content);
-  }
+    // Workflow copies (remove name: line)
+    for (const [src, name] of [[PRE_START_SRC, 'pre-start-context.md'], [POST_START_SRC, 'post-start-validation.md']]) {
+      const content = fs.readFileSync(src, 'utf-8').replace(/^name:.*\n/m, '');
+      fs.writeFileSync(path.join(targetDir, '.agents', 'workflows', name), content);
+    }
 
-  console.log(`  Installed universal skills to ${targetDir}`);
+    console.log(`  Installed universal skills to ${targetDir}`);
+  } catch (err) {
+    cliError(`failed to install skills: ${err.message}`, EXIT_INTERNAL);
+  }
 }
 
 function init() {
@@ -53,7 +73,7 @@ function init() {
   } catch {
     console.error('  Error: Claude Code CLI not found (or did not respond in 5s).');
     console.error('  Install: https://claude.com/claude-code');
-    process.exit(1);
+    process.exit(EXIT_USER);
   }
 
   // Pre-flight: warn if not a git repo (non-blocking, just informative)
@@ -86,14 +106,18 @@ function init() {
   console.log(`  The universal skills are already installed.\n`);
   console.log(`  >>> Type "go" and press Enter to start the interview <<<\n`);
 
-  const claude = spawn('claude', ['--agent', 'crag-project'], {
+  // On Windows, `shell: true` defaults to cmd.exe which can't always resolve
+  // the `claude` binary the way PowerShell / Git Bash can. Use an explicit
+  // shell path on Windows (bash from Git for Windows is the common install).
+  const spawnOpts = {
     stdio: 'inherit',
-    shell: true,
-  });
+    shell: process.platform === 'win32' ? (process.env.SHELL || 'bash') : true,
+  };
+  const claude = spawn('claude', ['--agent', 'crag-project'], spawnOpts);
 
   claude.on('error', (err) => {
     console.error(`\n  Error launching claude: ${err.message}`);
-    process.exit(1);
+    process.exit(EXIT_USER);
   });
 
   claude.on('exit', (code, signal) => {
@@ -101,7 +125,7 @@ function init() {
       console.log(`\n  crag setup complete. Run 'crag check' to verify.`);
     } else if (signal) {
       console.error(`\n  Interview terminated by signal: ${signal}`);
-      process.exit(1);
+      process.exit(EXIT_USER);
     } else if (code !== null) {
       console.error(`\n  Interview exited with code ${code}`);
       process.exit(code);
@@ -109,4 +133,4 @@ function init() {
   });
 }
 
-module.exports = { init, install, installSkills };
+module.exports = { init, install, installSkills, resolveHomeDir };

package/src/compile/atomic-write.js

@@ -1,31 +1,39 @@
 'use strict';
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
 /**
  * Write `content` to `filePath` atomically:
  *   1. Ensure parent directory exists
- *   2. Write to a sibling tempfile
+ *   2. Write to a sibling tempfile (unpredictable suffix — crypto-random)
  *   3. Rename tempfile over destination
  *
  * If any step fails, the tempfile is cleaned up and the original destination
  * remains untouched. Prevents partial-write state if the process is killed
  * mid-write or the filesystem runs out of space.
+ *
+ * The random suffix makes the temp filename unpredictable, blocking
+ * race-condition attacks on shared filesystems where an attacker could
+ * pre-create a symlink at the expected temp path.
  */
 function atomicWrite(filePath, content) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
-  const tmp = filePath + '.tmp.' + process.pid + '.' + Date.now();
+  const suffix = crypto.randomBytes(8).toString('hex');
+  const tmp = `${filePath}.tmp.${suffix}`;
 
   try {
-    fs.writeFileSync(tmp, content);
+    // wx flag: fail if the temp path somehow already exists (defense-in-depth
+    // on top of the unpredictable suffix).
+    fs.writeFileSync(tmp, content, { flag: 'wx' });
     fs.renameSync(tmp, filePath);
   } catch (err) {
     // Best-effort cleanup
     try { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); } catch {}
-    throw err;
+    throw new Error(`atomicWrite failed for ${filePath}: ${err.message}`);
   }
 }
 

package/src/compile/github-actions.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { gateToShell } = require('../governance/gate-to-shell');
 const { flattenGatesRich } = require('../governance/parse');
 const { atomicWrite } = require('./atomic-write');
+const { yamlScalar } = require('../update/integrity');
 
 /**
  * Extract the major Node version from package.json engines.node field.
@@ -95,7 +96,10 @@ function generateGitHubActions(cwd, parsed) {
     setupSteps += '      - name: Setup Python\n';
     setupSteps += '        uses: actions/setup-python@v5\n';
     setupSteps += `        with:\n          python-version: '${pythonVersion}'\n`;
-    setupSteps += '      - run: pip install -r requirements.txt 2>/dev/null || true\n';
+    // Explicit `shell: bash` so redirects work on Windows runners (which default to cmd.exe).
+    setupSteps += '      - name: Install Python deps (best-effort)\n';
+    setupSteps += '        shell: bash\n';
+    setupSteps += '        run: pip install -r requirements.txt 2>/dev/null || true\n';
   }
   if (parsed.runtimes.includes('java')) {
     setupSteps += '      - name: Setup Java\n';
@@ -108,13 +112,10 @@ function generateGitHubActions(cwd, parsed) {
     setupSteps += `        with:\n          go-version: '${goVersion}'\n`;
   }
 
-  // Escape for YAML double-quoted scalar: \, ", and control chars.
-  const yamlDqEscape = (s) => String(s)
-    .replace(/\\/g, '\\\\')
-    .replace(/"/g, '\\"')
-    .replace(/\r/g, '\\r')
-    .replace(/\n/g, '\\n')
-    .replace(/\t/g, '\\t');
+  // GHA expression escape for strings inside hashFiles('...'):
+  // single quotes are doubled. The value is already validated to be a
+  // relative in-repo path by the parser, but we escape defensively.
+  const ghaExprEscape = (s) => String(s).replace(/'/g, "''");
 
   let gateSteps = '';
   for (const gate of flattenGatesRich(parsed.gates)) {
@@ -122,12 +123,17 @@ function generateGitHubActions(cwd, parsed) {
     const label = gate.cmd.length > 60 ? gate.cmd.substring(0, 57) + '...' : gate.cmd;
     const prefix = gate.classification !== 'MANDATORY' ? `[${gate.classification}] ` : '';
     const condExpr = gate.condition ? ` (if: ${gate.condition})` : '';
-    const workDir = gate.path ? `\n        working-directory: ${gate.path}` : '';
+    // Route gate.path through yamlScalar — it will quote if the path contains
+    // YAML-sensitive characters (colon, #, quotes, etc.).
+    const workDir = gate.path ? `\n        working-directory: ${yamlScalar(gate.path)}` : '';
     const contOnErr = (gate.classification === 'OPTIONAL' || gate.classification === 'ADVISORY')
       ? '\n        continue-on-error: true' : '';
     const ifGuard = gate.condition
-      ? `\n        if: hashFiles('${gate.condition}') != ''` : '';
-    gateSteps += `      - name: "${prefix}${yamlDqEscape(gate.section)}: ${yamlDqEscape(label)}${yamlDqEscape(condExpr)}"${ifGuard}${workDir}${contOnErr}\n`;
+      ? `\n        if: hashFiles('${ghaExprEscape(gate.condition)}') != ''` : '';
+    // Use yamlScalar for the name field so user input can never break the YAML
+    // structure even if it contains quotes, newlines, colons, or control chars.
+    const stepName = `${prefix}${gate.section}: ${label}${condExpr}`;
+    gateSteps += `      - name: ${yamlScalar(stepName)}${ifGuard}${workDir}${contOnErr}\n`;
     gateSteps += `        run: |\n          ${shell.replace(/\n/g, '\n          ')}\n`;
   }
 

package/src/compile/husky.js

@@ -2,7 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { gateToShell } = require('../governance/gate-to-shell');
+const { gateToShell, shellEscapeDoubleQuoted } = require('../governance/gate-to-shell');
 const { flattenGatesRich } = require('../governance/parse');
 const { atomicWrite } = require('./atomic-write');
 
@@ -22,9 +22,10 @@ function generateHusky(cwd, parsed) {
     body += `# ${section}\n`;
     for (const gate of gates) {
       const shell = gateToShell(gate.cmd);
-      // Quote path/condition for shell safety
-      const quotedPath = gate.path ? gate.path.replace(/"/g, '\\"') : null;
-      const quotedCond = gate.condition ? gate.condition.replace(/"/g, '\\"') : null;
+      // Escape path/condition for the double-quoted shell context.
+      // The escaper handles \ before " so the replacements don't overlap.
+      const quotedPath = gate.path ? shellEscapeDoubleQuoted(gate.path) : null;
+      const quotedCond = gate.condition ? shellEscapeDoubleQuoted(gate.condition) : null;
 
       // Build the core command (with cd if path-scoped)
       const coreCmd = quotedPath ? `(cd "${quotedPath}" && ${shell})` : shell;
@@ -32,7 +33,7 @@ function generateHusky(cwd, parsed) {
       // Build failure handler based on classification
       let onFail;
       if (gate.classification === 'OPTIONAL' || gate.classification === 'ADVISORY') {
-        const escLabel = shell.replace(/"/g, '\\"');
+        const escLabel = shellEscapeDoubleQuoted(shell);
         onFail = `echo "  [${gate.classification}] Gate failed: ${escLabel}"`;
       } else {
         onFail = 'exit 1';

package/src/compile/pre-commit.js

@@ -2,9 +2,10 @@
 
 const fs = require('fs');
 const path = require('path');
-const { gateToShell } = require('../governance/gate-to-shell');
+const { gateToShell, shellEscapeDoubleQuoted, shellEscapeSingleQuoted } = require('../governance/gate-to-shell');
 const { flattenGatesRich } = require('../governance/parse');
 const { atomicWrite } = require('./atomic-write');
+const { yamlScalar } = require('../update/integrity');
 
 function generatePreCommitConfig(cwd, parsed) {
   const gates = flattenGatesRich(parsed.gates);
@@ -17,16 +18,23 @@ function generatePreCommitConfig(cwd, parsed) {
     const truncated = name.length > 60 ? name.substring(0, 57) + '...' : name;
 
     let shell = gateToShell(gate.cmd);
-    if (gate.path) shell = `cd "${gate.path}" && ${shell}`;
-    if (gate.condition) shell = `[ -e "${gate.condition}" ] && (${shell}) || true`;
+    // gate.path and gate.condition come from user-authored governance.md.
+    // Parser rejects absolute paths and `..`, but contents still need to be
+    // escaped for the surrounding double-quoted shell context.
+    if (gate.path) {
+      shell = `cd "${shellEscapeDoubleQuoted(gate.path)}" && ${shell}`;
+    }
+    if (gate.condition) {
+      shell = `[ -e "${shellEscapeDoubleQuoted(gate.condition)}" ] && (${shell}) || true`;
+    }
     // For OPTIONAL/ADVISORY: never fail the hook
     if (gate.classification === 'OPTIONAL' || gate.classification === 'ADVISORY') {
       shell = `(${shell}) || echo "[${gate.classification}] failed — continuing"`;
     }
 
     hooks += `      - id: ${id}\n`;
-    hooks += `        name: "${truncated.replace(/"/g, '\\"')}"\n`;
-    hooks += `        entry: bash -c '${shell.replace(/'/g, "'\\''")}'\n`;
+    hooks += `        name: ${yamlScalar(truncated)}\n`;
+    hooks += `        entry: bash -c '${shellEscapeSingleQuoted(shell)}'\n`;
     hooks += '        language: system\n';
     hooks += '        pass_filenames: false\n';
     hooks += '        always_run: true\n';