@whitehatd/crag 0.2.1 → 0.2.3

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@whitehatd/crag",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "The bedrock layer for AI coding agents. One governance.md. Any project. Never stale.",
   "bin": {
     "crag": "bin/crag.js"
   },
   "scripts": {
-    "test": "node test/all.js"
+    "test": "node test/all.js",
+    "sync-hashes": "node scripts/sync-skill-hashes.js",
+    "release:patch": "node scripts/bump-version.js patch",
+    "release:minor": "node scripts/bump-version.js minor",
+    "release:major": "node scripts/bump-version.js major"
   },
   "keywords": [
     "claude-code",

package/src/cli-errors.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Exit code convention for crag commands:
+ *   0            — success
+ *   EXIT_USER=1  — user-recoverable error (missing governance.md, bad flag,
+ *                  invalid argument, file not found in expected location,
+ *                  gate assertion failure in `check`, drift in `diff`)
+ *   EXIT_INTERNAL=2 — internal / environmental error the user likely cannot
+ *                     fix by re-running with different input (EACCES on write,
+ *                     disk full, unexpected stat failure, bug in crag itself)
+ *
+ * Scripts can use `if [ $? -eq 1 ]` to distinguish user mistakes from
+ * infrastructure problems.
+ */
+const EXIT_USER = 1;
+const EXIT_INTERNAL = 2;
+
+/**
+ * Print a formatted error message and exit with the given code.
+ * Matches the style of other crag output (two-space indent, red marker).
+ */
+function cliError(message, exitCode) {
+  const code = exitCode === EXIT_INTERNAL ? EXIT_INTERNAL : EXIT_USER;
+  console.error(`  \x1b[31m✗\x1b[0m Error: ${message}`);
+  process.exit(code);
+}
+
+/**
+ * Print a warning but do NOT exit. Use for non-fatal conditions.
+ */
+function cliWarn(message) {
+  console.warn(`  \x1b[33m!\x1b[0m Warning: ${message}`);
+}
+
+/**
+ * Read a file with a clear error message on failure.
+ * Throws a structured error that command wrappers can catch and exit with.
+ */
+function readFileOrExit(fs, filePath, label) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    const what = label || filePath;
+    if (err.code === 'ENOENT') {
+      cliError(`${what} not found: ${filePath}`, EXIT_USER);
+    } else if (err.code === 'EACCES' || err.code === 'EPERM') {
+      cliError(`permission denied reading ${what}: ${filePath}`, EXIT_INTERNAL);
+    } else {
+      cliError(`failed to read ${what}: ${err.message}`, EXIT_INTERNAL);
+    }
+  }
+}
+
+module.exports = { EXIT_USER, EXIT_INTERNAL, cliError, cliWarn, readFileOrExit };

package/src/cli.js

@@ -8,6 +8,7 @@ const { diff } = require('./commands/diff');
 const { upgrade } = require('./commands/upgrade');
 const { workspace } = require('./commands/workspace');
 const { checkOnce } = require('./update/version-check');
+const { EXIT_USER } = require('./cli-errors');
 
 function printUsage() {
   console.log(`
@@ -48,6 +49,13 @@ function printUsage() {
     crag analyze --workspace          Analyze all workspace members
     crag analyze --merge              Merge with existing governance
 
+  Check options:
+    crag check                        Human-readable infrastructure report
+    crag check --json                 Machine-readable JSON output
+
+  Compile options:
+    crag compile --target <t> --dry-run  Preview output paths without writing
+
   Upgrade options:
     crag upgrade --check              Show what would change
     crag upgrade --workspace          Update all workspace members
@@ -81,7 +89,7 @@ function run(args) {
   switch (command) {
     case 'init':      init(); break;
     case 'install':   install(); break;
-    case 'check':     check(); break;
+    case 'check':     check(args); break;
     case 'compile':   compile(args); break;
     case 'analyze':   analyze(args); break;
     case 'diff':      diff(args); break;
@@ -95,7 +103,7 @@ function run(args) {
     default:
       console.error(`  Unknown command: ${command}`);
       printUsage();
-      process.exit(1);
+      process.exit(EXIT_USER);
   }
 }
 

package/src/commands/analyze.js

@@ -5,6 +5,8 @@ const fs = require('fs');
 const path = require('path');
 const { detectWorkspace } = require('../workspace/detect');
 const { enumerateMembers } = require('../workspace/enumerate');
+const { extractRunCommands, isGateCommand } = require('../governance/yaml-run');
+const { cliWarn, cliError, EXIT_INTERNAL } = require('../cli-errors');
 
 /**
  * crag analyze — generate governance.md from existing project without interview.
@@ -45,21 +47,30 @@ function analyze(args) {
 
   const govPath = path.join(cwd, '.claude', 'governance.md');
   const govDir = path.dirname(govPath);
-  if (!fs.existsSync(govDir)) fs.mkdirSync(govDir, { recursive: true });
-
-  if (fs.existsSync(govPath) && !merge) {
-    const backupPath = govPath + '.bak.' + Date.now();
-    fs.copyFileSync(govPath, backupPath);
-    console.log(`  Backed up existing governance to ${path.basename(backupPath)}`);
-  }
+  try {
+    if (!fs.existsSync(govDir)) fs.mkdirSync(govDir, { recursive: true });
+
+    if (fs.existsSync(govPath) && !merge) {
+      const backupPath = govPath + '.bak.' + Date.now();
+      try {
+        fs.copyFileSync(govPath, backupPath);
+        console.log(`  Backed up existing governance to ${path.basename(backupPath)}`);
+      } catch (err) {
+        // Backup failure shouldn't block the analyze, but warn loudly.
+        cliWarn(`could not create backup (continuing anyway): ${err.message}`);
+      }
+    }
 
-  if (merge && fs.existsSync(govPath)) {
-    console.log('  Merge mode: preserving existing governance, appending new gates');
-    const existing = fs.readFileSync(govPath, 'utf-8');
-    const mergedContent = mergeWithExisting(existing, governance);
-    fs.writeFileSync(govPath, mergedContent);
-  } else {
-    fs.writeFileSync(govPath, governance);
+    if (merge && fs.existsSync(govPath)) {
+      console.log('  Merge mode: preserving existing governance, appending new gates');
+      const existing = fs.readFileSync(govPath, 'utf-8');
+      const mergedContent = mergeWithExisting(existing, governance);
+      fs.writeFileSync(govPath, mergedContent);
+    } else {
+      fs.writeFileSync(govPath, governance);
+    }
+  } catch (err) {
+    cliError(`failed to write ${path.relative(cwd, govPath)}: ${err.message}`, EXIT_INTERNAL);
   }
 
   console.log(`  \x1b[32m✓\x1b[0m Generated ${path.relative(cwd, govPath)}`);
@@ -167,50 +178,7 @@ function extractCIGates(dir, result) {
   }
 }
 
-/**
- * Extract commands from YAML `run:` steps, handling both inline and block-scalar forms:
- *   run: npm test
- *   run: |
- *     npm test
- *     npm build
- *   run: >-
- *     npm test
- */
-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();
-
-    // Block scalar: | or |- or |+ or > or >- or >+
-    if (/^[|>][+-]?\s*$/.test(rest)) {
-      // Collect following lines with greater indent
-      const blockLines = [];
-      for (let j = i + 1; j < lines.length; j++) {
-        const ln = lines[j];
-        if (ln.trim() === '') { blockLines.push(''); continue; }
-        const indentMatch = ln.match(/^(\s*)/);
-        if (indentMatch[1].length <= baseIndent) break;
-        blockLines.push(ln.slice(baseIndent + 2));
-      }
-      for (const bl of blockLines) {
-        const trimmed = bl.trim();
-        if (trimmed && !trimmed.startsWith('#')) commands.push(trimmed);
-      }
-    } else if (rest && !rest.startsWith('#')) {
-      // Inline: remove surrounding quotes if any
-      commands.push(rest.replace(/^["']|["']$/g, ''));
-    }
-  }
-
-  return commands;
-}
+// extractRunCommands and isGateCommand now live in src/governance/yaml-run.js.
 
 function extractPackageScripts(dir, result) {
   const pkgPath = path.join(dir, 'package.json');
@@ -310,25 +278,18 @@ function inferGitPatterns(dir, result) {
     const branchList = branches.trim().split('\n');
     const featureBranches = branchList.filter(b => /^(feat|fix|docs|chore|feature|hotfix|release)\//.test(b));
     result.branchStrategy = featureBranches.length > 2 ? 'feature-branches' : 'trunk-based';
-  } catch {
+  } catch (err) {
+    // git may not be installed, or this may not be a git repo — non-fatal,
+    // just report and leave defaults. Matches the "best-effort" semantics of
+    // analyze (it infers what it can from whatever exists).
+    if (err && err.code !== 'ENOENT') {
+      cliWarn(`could not detect git patterns in ${path.basename(dir)}: ${err.message}`);
+    }
     result.branchStrategy = 'unknown';
     result.commitConvention = 'unknown';
   }
 }
 
-function isGateCommand(cmd) {
-  const gatePatterns = [
-    /npm (run |ci|test|install)/, /npx /, /node /,
-    /cargo (test|build|check|clippy)/, /rustfmt/,
-    /go (test|build|vet)/, /golangci-lint/,
-    /pytest/, /python -m/, /ruff/, /mypy/, /flake8/,
-    /gradle/, /mvn /, /maven/,
-    /eslint/, /biome/, /prettier/, /tsc/,
-    /docker (build|compose)/, /make /, /just /,
-  ];
-  return gatePatterns.some(p => p.test(cmd));
-}
-
 function generateGovernance(analysis, cwd) {
   const sections = [];
 

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';

package/src/governance/gate-to-shell.js

@@ -3,11 +3,21 @@
 /**
  * Escape a string for safe inclusion inside double quotes in a shell command.
  * Escapes: backslash, backtick, dollar sign, double quote.
+ * Backslash MUST be replaced first so its replacement isn't re-escaped.
  */
 function shellEscapeDoubleQuoted(s) {
   return String(s).replace(/[\\`"$]/g, '\\$&');
 }
 
+/**
+ * Escape a string for safe inclusion inside single quotes in a shell command.
+ * Single quotes cannot be escaped inside single quotes — the standard pattern
+ * is to close the quote, emit an escaped quote, and reopen: 'foo'\''bar'.
+ */
+function shellEscapeSingleQuoted(s) {
+  return String(s).replace(/'/g, "'\\''");
+}
+
 /**
  * Convert human-readable gate descriptions to shell commands.
  * e.g. Verify src/skills/pre-start-context.md contains "discovers any project"
@@ -25,4 +35,4 @@ function gateToShell(cmd) {
   return cmd;
 }
 
-module.exports = { gateToShell, shellEscapeDoubleQuoted };
+module.exports = { gateToShell, shellEscapeDoubleQuoted, shellEscapeSingleQuoted };

package/src/governance/parse.js

@@ -14,6 +14,30 @@
 // Protects against ReDoS on catastrophic-backtracking-prone regex.
 const MAX_CONTENT_SIZE = 256 * 1024; // 256 KB
 
+/**
+ * Validate an annotation path (used for `path:` and `if:` on gate sections).
+ *
+ * Rejects:
+ *   - Absolute paths (/, C:\, \\server\share)
+ *   - Parent traversal (..)
+ *   - Newlines or null bytes (defense against injection into generated YAML/shell)
+ *
+ * These paths are interpolated into shell commands and YAML scalars downstream
+ * (husky, pre-commit, github-actions), so the parser is the single chokepoint
+ * where untrusted path strings from governance.md become structured data.
+ */
+function isValidAnnotationPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return false;
+  if (p.length > 512) return false;
+  if (/[\n\r\x00]/.test(p)) return false;
+  // POSIX absolute or Windows drive-letter / UNC
+  if (p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('\\\\')) return false;
+  // Parent traversal (match as a path segment, not as substring of a name)
+  const segments = p.split(/[\\/]/);
+  if (segments.includes('..')) return false;
+  return true;
+}
+
 /**
  * Extract a markdown section body by heading name.
  * Starts after the first line matching `## <name>` (with optional trailing text),
@@ -90,8 +114,22 @@ function parseGovernance(content) {
       if (sub) {
         section = sub[1].trim().toLowerCase();
         sectionMeta = { path: null, condition: null };
-        if (sub[2] === 'path') sectionMeta.path = sub[3].trim();
-        if (sub[2] === 'if') sectionMeta.condition = sub[3].trim();
+        if (sub[2] === 'path') {
+          const raw = sub[3].trim();
+          if (isValidAnnotationPath(raw)) {
+            sectionMeta.path = raw;
+          } else {
+            result.warnings.push(`Invalid path annotation in section "${sub[1].trim()}": ${JSON.stringify(raw)} (must be a relative in-repo path without "..")`);
+          }
+        }
+        if (sub[2] === 'if') {
+          const raw = sub[3].trim();
+          if (isValidAnnotationPath(raw)) {
+            sectionMeta.condition = raw;
+          } else {
+            result.warnings.push(`Invalid if annotation in section "${sub[1].trim()}": ${JSON.stringify(raw)} (must be a relative in-repo path without "..")`);
+          }
+        }
         result.gates[section] = {
           commands: [],
           path: sectionMeta.path,
@@ -179,4 +217,4 @@ function flattenGatesRich(gates) {
   return out;
 }
 
-module.exports = { parseGovernance, flattenGates, flattenGatesRich, extractSection };
+module.exports = { parseGovernance, flattenGates, flattenGatesRich, extractSection, isValidAnnotationPath };

package/src/governance/yaml-run.js

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * Shared YAML `run:` command extraction for GitHub Actions workflows.
+ *
+ * Both `crag analyze` and `crag diff` need to enumerate the shell commands
+ * inside CI workflows to either generate gates from them or compare them
+ * against governance. This module is the single source of truth so a fix to
+ * the parser benefits both commands.
+ *
+ * Handles:
+ *   run: npm test                    (inline)
+ *   run: "npm test"                  (inline, quoted)
+ *   run: |                           (literal block scalar)
+ *     npm test
+ *     npm run build
+ *   run: >-                          (folded block scalar)
+ *     npm test
+ *
+ * Comment-only lines and blank lines inside blocks are skipped.
+ */
+function extractRunCommands(content) {
+  const commands = [];
+  const lines = String(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: collect following lines with greater indent than the key
+      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('#')) {
+      // Inline: strip surrounding single/double quotes if present
+      commands.push(rest.replace(/^["']|["']$/g, ''));
+    }
+  }
+
+  return commands;
+}
+
+/**
+ * Classify a shell command as a "gate" — i.e., a quality check that belongs
+ * in governance.md (test, lint, typecheck, build, etc.) as opposed to
+ * deployment, git operations, or environment setup.
+ *
+ * This is a heuristic and intentionally conservative: false positives
+ * (extra gates) are easier to spot than false negatives (missing gates).
+ */
+function isGateCommand(cmd) {
+  const patterns = [
+    /\bnpm (run |ci|test|install)/,
+    /\bnpx /,
+    /\bnode /,
+    /\bcargo (test|build|check|clippy)/,
+    /\brustfmt/,
+    /\bgo (test|build|vet)/,
+    /\bgolangci-lint/,
+    /\bpytest/,
+    /\bpython -m/,
+    /\bruff/,
+    /\bmypy/,
+    /\bflake8/,
+    /\bgradle/,
+    /\bmvn /,
+    /\bmaven/,
+    /\beslint/,
+    /\bbiome/,
+    /\bprettier/,
+    /\btsc/,
+    /\bdocker (build|compose)/,
+    /\bmake /,
+    /\bjust /,
+  ];
+  return patterns.some((p) => p.test(cmd));
+}
+
+module.exports = { extractRunCommands, isGateCommand };

package/src/skills/post-start-validation.md

@@ -1,6 +1,6 @@
 ---
 name: post-start-validation
-version: 0.2.1
+version: 0.2.2
 source_hash: 5a64dfe68b13577dff818fa63ddb6185be360c80b100f205bc586aac39e19e80
 description: Universal validation and knowledge capture. Detects what changed, runs governance gates, captures knowledge, verifies deployment. Works for any project.
 ---

package/src/skills/pre-start-context.md

@@ -1,6 +1,6 @@
 ---
 name: pre-start-context
-version: 0.2.1
+version: 0.2.2
 source_hash: b7be8434b99d5b189c904263e783d573c82109218725cc31fbd4fa1bf81538b6
 description: Universal context loader. Discovers any project's stack, architecture, and state at runtime. Reads governance.md for project-specific rules. Works for any language, framework, or deployment target.
 ---

package/src/update/integrity.js

@@ -47,8 +47,18 @@ function readFrontmatter(filePath) {
 }
 
 /**
- * Format a value for YAML frontmatter.
+ * Format a value for YAML frontmatter or YAML block scalars.
  * Quotes strings that contain special characters or could be ambiguous.
+ *
+ * Rules roughly follow YAML 1.2 plain-scalar constraints:
+ *   - Leading/trailing whitespace → must quote
+ *   - Special markers anywhere: : # & * ! | > ' " % @ `
+ *   - Leading flow indicators: [ ] { } , (would start a flow sequence/map)
+ *   - Leading dash + space looks like a block sequence entry
+ *   - Leading ? or ! looks like a YAML tag or complex-key marker
+ *   - Reserved words that coerce to other types: true/false/null/yes/no/~
+ *   - Number-like strings
+ *   - Empty string
  */
 function yamlScalar(value) {
   if (value == null) return '';
@@ -60,15 +70,18 @@ function yamlScalar(value) {
     return `|\n${indented}`;
   }
 
-  // Characters that require quoting in YAML plain scalar:
-  //   : leading/trailing or followed by space (key separator)
-  //   # comment marker
-  //   special markers: & * ! | > ' " % @ `
-  //   leading/trailing whitespace
-  //   strings that could be misread as other types: true, false, null, yes, no, numbers
+  // Control characters (tabs, etc.) must be quoted so they survive round-trip.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f]/.test(str)) {
+    return `"${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\t/g, '\\t').replace(/\r/g, '\\r')}"`;
+  }
+
   const needsQuoting =
     /^[\s]|[\s]$/.test(str) ||
     /[:#&*!|>'"%@`]/.test(str) ||
+    /^[\[\]{},]/.test(str) ||
+    /^- /.test(str) ||
+    /^[?!]/.test(str) ||
     /^(true|false|null|yes|no|~)$/i.test(str) ||
     /^-?\d+(\.\d+)?$/.test(str) ||
     str === '';

package/src/update/skill-sync.js

@@ -113,4 +113,4 @@ function syncSkills(targetDir, options = {}) {
   return result;
 }
 
-module.exports = { syncSkills };
+module.exports = { syncSkills, isTrustedSource };