contextos-agents 2.1.0 → 2.1.1

package/.agents/adapters/aider/export.js

@@ -90,8 +90,8 @@ function render(context) {
       }
 
       aiderConfContent = yamlProv + '\n' + YAML.stringify(parsed);
-    } catch {
-      aiderConfContent = yamlProv + '\nread:\n  - CONVENTIONS.md\n';
+    } catch (err) {
+      throw new Error(`Failed to parse existing .aider.conf.yml: ${err.message}. Aborting to protect existing configuration from data loss.`);
     }
   } else {
     aiderConfContent = [

package/.agents/adapters/claude/export.js

@@ -9,13 +9,15 @@ const { collectSkillDirectories, readMeaningfulMarkdown } = require('../shared.j
 const { registerAdapter, applyArtifacts } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'claude@2';
+const CLAUDE_START_MARKER = '<!-- CONTEXTOS:START -->';
+const CLAUDE_END_MARKER = '<!-- CONTEXTOS:END -->';
 
 function describe() {
   return {
     name: 'claude',
     version: '2.0.0',
-    description: 'Compiles clean markdown skills for Claude Code CLI',
-    targetPattern: '.agents/generated/claude/skills/**/SKILL.md',
+    description: 'Compiles clean markdown skills for Claude Code CLI and manages CLAUDE.md entrypoint',
+    targetPattern: '{CLAUDE.md,.agents/generated/claude/skills/**/SKILL.md}',
   };
 }
 
@@ -53,6 +55,50 @@ function renderClaudeSkill(skillDir, context) {
   };
 }
 
+function renderClaudeRootIndex(skills, context) {
+  const projectRoot = context?.projectRoot || '.';
+  const claudePath = path.join(projectRoot, 'CLAUDE.md');
+  let existingContent = '';
+  if (fs.existsSync(claudePath)) {
+    try {
+      existingContent = fs.readFileSync(claudePath, 'utf8');
+    } catch {}
+  }
+
+  const skillEntries = skills.map(skillDir => {
+    const name = path.basename(skillDir);
+    return `- [${name}](.agents/generated/claude/skills/${name}/SKILL.md)`;
+  }).join('\n');
+
+  const managedBlock = `${CLAUDE_START_MARKER}
+<!-- Do not edit this section directly. Synchronized by ContextOS. -->
+# ContextOS Agent Governance
+
+The following skills are managed by ContextOS:
+${skillEntries}
+${CLAUDE_END_MARKER}`;
+
+  let finalContent;
+  if (existingContent.includes(CLAUDE_START_MARKER)) {
+    const regex = new RegExp(`${CLAUDE_START_MARKER}[\\s\\S]*?${CLAUDE_END_MARKER}`);
+    finalContent = existingContent.replace(regex, managedBlock);
+  } else if (existingContent.trim()) {
+    finalContent = `${existingContent.trimEnd()}\n\n${managedBlock}\n`;
+  } else {
+    finalContent = `${managedBlock}\n`;
+  }
+
+  return {
+    path: 'CLAUDE.md',
+    content: finalContent.replace(/\r\n/g, '\n'),
+    mediaType: 'text/markdown',
+    kind: 'generated-adapter',
+    generator: GENERATOR_ID,
+    sourceSkillIds: skills.map(s => path.basename(s)),
+    inputsHash: context?.sourceGraphHash || 'none',
+  };
+}
+
 function render(context) {
   const skills = collectSkillDirectories(context?.profile, context?.projectRoot);
   const artifacts = [];
@@ -62,6 +108,11 @@ function render(context) {
     if (art) artifacts.push(art);
   }
 
+  if (skills.length > 0) {
+    const rootIndex = renderClaudeRootIndex(skills, context);
+    if (rootIndex) artifacts.push(rootIndex);
+  }
+
   return artifacts;
 }
 

package/.agents/adapters/drift-detector.js

@@ -170,10 +170,13 @@ function detectDrift(projectRoot, adapters = 'all', options = {}) {
     } else {
       const diskContent = fs.readFileSync(fullPath, 'utf8');
       const diskSemanticHash = computeSemanticHash(diskContent);
+      const lockRecord = lockfile?.managedFiles?.[art.path];
 
-      // Check if disk matches projected render
-      if (diskSemanticHash !== projectedSemanticHash) {
-        const lockRecord = lockfile?.managedFiles?.[art.path];
+      // Check if disk matches projected render and recorded lockfile
+      const matchesProjection = diskSemanticHash === projectedSemanticHash;
+      const matchesLock = lockRecord ? diskSemanticHash === lockRecord.semanticTextSha256 : matchesProjection;
+
+      if (!matchesProjection || !matchesLock) {
         if (lockRecord && lockRecord.semanticTextSha256 !== diskSemanticHash) {
           findings[DRIFT_STATES.MODIFIED_MANAGED_OUTPUT].push({
             path: art.path,

package/.agents/adapters/pure-compiler.js

@@ -86,11 +86,22 @@ function loadCompilerContext(projectRoot, options = {}) {
 
   // 2. Profile v2
   let profile = null;
-  try {
-    const profiles = require('../profiles.js');
-    profile = options.profile ? profiles.getProfile(options.profile, absRoot) : profiles.getActiveProfile(absRoot);
-  } catch {
-    profile = null;
+  const profiles = require('../profiles.js');
+  if (options.profile) {
+    try {
+      profile = profiles.getProfile(options.profile, absRoot);
+    } catch (err) {
+      throw new Error(`Failed to load profile '${options.profile}': ${err.message}`);
+    }
+    if (!profile) {
+      throw new Error(`Profile '${options.profile}' was specified but does not exist.`);
+    }
+  } else {
+    try {
+      profile = profiles.getActiveProfile(absRoot);
+    } catch {
+      profile = null;
+    }
   }
 
   // 3. Workspace Graph
@@ -172,9 +183,10 @@ function listAdapters() {
  */
 function renderAdapters(projectRoot, adapterNames = 'all', options = {}) {
   const context = loadCompilerContext(projectRoot, options);
-  const targets = adapterNames === 'all'
+  const rawTargets = adapterNames === 'all'
     ? listAdapters()
     : (Array.isArray(adapterNames) ? adapterNames : [adapterNames]);
+  const targets = rawTargets.flatMap(a => (typeof a === 'string' && a.includes(',') ? a.split(',').map(s => s.trim()).filter(Boolean) : a));
 
   const allArtifacts = [];
   const pathToArtifact = new Map();

package/.agents/ctx.js

@@ -253,8 +253,8 @@ if (command === 'export') {
     : (args.find(a => a.startsWith('--scope=')) || '').split('=')[1] || null;
 
   if (subcommand === 'list') {
-    const list = profiles.listProfiles();
-    const active = profiles.getActiveProfile();
+    const list = profiles.listProfiles(process.cwd());
+    const active = profiles.getActiveProfile(process.cwd());
     if (asJson) {
       console.log(JSON.stringify({ active, profiles: list }, null, 2));
     } else {
@@ -285,7 +285,7 @@ if (command === 'export') {
       console.error('[ERROR] Usage: node ctx.js profile show <name> [--json]');
       process.exit(1);
     }
-    const profile = profiles.getProfile(name);
+    const profile = profiles.getProfile(name, process.cwd());
     if (!profile) {
       console.error(`[ERROR] Profile '${name}' not found.`);
       process.exit(1);
@@ -306,7 +306,7 @@ if (command === 'export') {
       process.exit(1);
     }
     try {
-      const explanation = profiles.explainProfile(name);
+      const explanation = profiles.explainProfile(name, process.cwd());
       if (asJson) {
         console.log(JSON.stringify(explanation, null, 2));
       } else {

package/.agents/plugins.js

@@ -26,7 +26,7 @@ const https   = require('https');
 const crypto  = require('crypto');
 const { execFileSync } = require('child_process');
 const { ProjectMutationLock } = require('./filesystem/project-lock.js');
-const JournaledTransaction = require('./filesystem/journaled-transaction.js');
+const { JournaledTransaction } = require('./filesystem/journaled-transaction.js');
 const {
   calculateTreeDigest,
   validateArchiveEntry,
@@ -284,11 +284,49 @@ function isValidNpmPackage(name) {
   return /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/.test(name);
 }
 
-function parseRef(ref) {
+function parseRef(ref, projectRoot = null) {
   if (typeof ref !== 'string' || !ref.trim()) {
     throw new Error('A plugin reference is required');
   }
 
+  // 1. Built-in package catalog skills take strict precedence for catalog names.
+  // Consumer project local files can never spoof or hijack package catalog skills.
+  const pkgCatalogPath = path.join(path.resolve(__dirname, '..'), 'catalog', 'skills', ref);
+  if (fs.existsSync(pkgCatalogPath) && fs.existsSync(path.join(pkgCatalogPath, 'SKILL.md'))) {
+    return {
+      type: 'catalog',
+      name: ref,
+      path: pkgCatalogPath,
+      isPinned: true,
+      raw: ref,
+    };
+  }
+
+  // 2. Explicit local references (must start with 'local:', './', '../', or 'file:')
+  if (ref.startsWith('local:') || ref.startsWith('./') || ref.startsWith('../') || ref.startsWith('file:')) {
+    const rawTarget = ref.startsWith('local:')
+      ? ref.slice(6)
+      : (ref.startsWith('file:') ? ref.slice(5) : ref);
+
+    const baseRoot = projectRoot || process.cwd();
+    let localDir = path.resolve(baseRoot, rawTarget);
+    if (!fs.existsSync(localDir)) {
+      localDir = path.join(baseRoot, 'catalog', 'skills', rawTarget);
+    }
+
+    if (fs.existsSync(localDir) && fs.existsSync(path.join(localDir, 'SKILL.md'))) {
+      const skillName = path.basename(localDir);
+      return {
+        type: 'catalog',
+        name: skillName,
+        path: localDir,
+        isPinned: true,
+        raw: ref,
+      };
+    }
+    throw new Error(`Local skill not found at: '${ref}'`);
+  }
+
   // Scoped packages contain a slash but are npm packages, not GitHub refs.
   if (ref.startsWith('@')) {
     if (!isValidNpmPackage(ref)) {
@@ -529,6 +567,62 @@ function installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe = f
   return sha256;
 }
 
+// ── Catalog installer ─────────────────────────────────────────────────────────
+function installFromCatalog(descriptor, skillName, dryRun, checksum, forceUnsafe = false, tx = null) {
+  const sourceDir = descriptor.path;
+  const targetDir = path.join(PLUGINS_DIR, skillName);
+  const relTargetDir = toPosix(path.relative(ROOT, targetDir));
+
+  if (dryRun) {
+    console.log(c.dim(`  [DRY-RUN] Would copy catalog skill from: ${sourceDir}`));
+    return 'sha256:0000000000000000000000000000000000000000000000000000000000000000';
+  }
+
+  function copyRecursive(src, dest, relDest) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      const relPath = toPosix(path.join(relDest, entry.name));
+
+      if (entry.isDirectory()) {
+        copyRecursive(srcPath, destPath, relPath);
+      } else {
+        const content = fs.readFileSync(srcPath, 'utf8');
+        if (tx) {
+          tx.stageWrite(relPath, content);
+        } else {
+          fs.writeFileSync(destPath, content, 'utf8');
+        }
+      }
+    }
+  }
+
+  copyRecursive(sourceDir, targetDir, relTargetDir);
+
+  const primarySkillMd = path.join(sourceDir, 'SKILL.md');
+  const sha256 = fs.existsSync(primarySkillMd) ? crypto.createHash('sha256').update(fs.readFileSync(primarySkillMd)).digest('hex') : null;
+
+  const sourceMeta = {
+    source: 'catalog',
+    name: skillName,
+    path: toPosix(path.relative(ROOT, sourceDir)),
+    sha256,
+    installedAt: new Date().toISOString(),
+  };
+  if (tx) {
+    tx.stageWrite(`${relTargetDir}/.source`, JSON.stringify(sourceMeta, null, 2) + '\n');
+  } else {
+    fs.writeFileSync(path.join(targetDir, '.source'), JSON.stringify(sourceMeta, null, 2) + '\n');
+  }
+
+  console.log(c.green(`  ✓ Installed from built-in catalog: ${skillName}`));
+  return sha256;
+}
+
 // ── Derive skill name from ref ────────────────────────────────────────────────
 function deriveSkillName(ref) {
   // username/repo/path/to/my-skill → my-skill
@@ -570,7 +664,7 @@ async function add(ref, options = {}) {
   }
 
   // Supply-chain source pinning check (Wave 6)
-  if (!dryRun) {
+  if (!dryRun && descriptor.type !== 'catalog') {
     const pinning = validatePluginPinning(
       {
         type: descriptor.type,
@@ -637,7 +731,9 @@ async function add(ref, options = {}) {
     lockToken = projectLock.acquire({ command: 'skill:add' });
 
     let installedSha256 = null;
-    if (descriptor.type === 'github') {
+    if (descriptor.type === 'catalog') {
+      installedSha256 = installFromCatalog(descriptor, skillName, dryRun, checksum, forceUnsafe, tx);
+    } else if (descriptor.type === 'github') {
       installedSha256 = await installFromGitHub(descriptor, skillName, dryRun, checksum, forceUnsafe, tx);
     } else {
       installedSha256 = installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe, tx);

package/.agents/profiles.js

@@ -298,14 +298,26 @@ function validateProfile(profile, registry = null) {
 }
 
 /**
- * Lists all available project profiles defined in core/profiles.
+ * Lists all available project profiles defined in core/profiles and optionally consumer project.
+ * Searches built-in profiles in packageRoot, and if projectRoot is supplied, searches
+ * consumer project .agents/profiles, .agents/core/profiles, and profiles directories.
  *
+ * @param {string|null} [projectRoot=null] - Optional consumer project root
  * @returns {ProfileConfig[]} Array of profile configurations
  */
-function listProfiles() {
+function listProfiles(projectRoot = null) {
   const profiles = [];
   const searchDirs = [PROFILES_DIR, path.join(AGENTS_DIR, 'catalog', 'presets')];
 
+  if (projectRoot) {
+    const absConsumer = path.resolve(projectRoot);
+    searchDirs.push(
+      path.join(absConsumer, '.agents', 'profiles'),
+      path.join(absConsumer, '.agents', 'core', 'profiles'),
+      path.join(absConsumer, 'profiles')
+    );
+  }
+
   for (const dir of searchDirs) {
     if (!fs.existsSync(dir)) continue;
     const files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
@@ -314,22 +326,31 @@ function listProfiles() {
       const parsed = parseYamlProfile(content);
       if (!parsed.id) parsed.id = path.basename(file, path.extname(file));
       if (!parsed.name) parsed.name = parsed.id;
-      profiles.push(parsed);
+
+      // Consumer profiles can override or extend built-in profiles; deduplicate by id
+      const normId = parsed.id.toLowerCase();
+      const existingIdx = profiles.findIndex(p => p.id.toLowerCase() === normId);
+      if (existingIdx !== -1) {
+        profiles[existingIdx] = parsed;
+      } else {
+        profiles.push(parsed);
+      }
     }
   }
   return profiles;
 }
 
 /**
- * Finds a profile by its slug ID or title.
+ * Finds a profile by its slug ID or title across package and consumer roots.
  *
  * @param {string} name - Profile identifier or name
+ * @param {string|null} [projectRoot=null] - Optional consumer project root
  * @returns {ProfileConfig|null} Found profile or null
  */
-function getProfile(name) {
+function getProfile(name, projectRoot = null) {
   if (!name) return null;
   const clean = name.toLowerCase().trim();
-  const all = listProfiles();
+  const all = listProfiles(projectRoot);
   return all.find(p => p.id.toLowerCase() === clean || p.name.toLowerCase() === clean) || null;
 }
 
@@ -398,7 +419,7 @@ function getActiveProfile(projectDir = process.cwd(), targetFileOrScope = null)
     }
 
     if (matchedProfileName) {
-      const overrideProf = getProfile(matchedProfileName);
+      const overrideProf = getProfile(matchedProfileName, projectDir);
       if (overrideProf) {
         return {
           ...overrideProf,
@@ -424,9 +445,9 @@ function getActiveProfile(projectDir = process.cwd(), targetFileOrScope = null)
  * @returns {Object} Updated profile lock data
  */
 function applyProfile(profileName, projectDir = process.cwd(), options = {}) {
-  const profile = getProfile(profileName);
+  const profile = getProfile(profileName, projectDir);
   if (!profile) {
-    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles().map(p => p.id).join(', ')}`);
+    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles(projectDir).map(p => p.id).join(', ')}`);
   }
 
   validateProfile(profile);
@@ -563,9 +584,9 @@ function removeActiveProfile(projectDir = process.cwd(), options = {}) {
  * @returns {Object} Explanation structure
  */
 function explainProfile(profileName, projectDir = process.cwd()) {
-  const profile = getProfile(profileName);
+  const profile = getProfile(profileName, projectDir);
   if (!profile) {
-    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles().map(p => p.id).join(', ')}`);
+    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles(projectDir).map(p => p.id).join(', ')}`);
   }
 
   return {

package/README.md

@@ -172,9 +172,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.0.0
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.1.1
         with:
-          version: '2.0.0'       # Pinned version of contextos-agents runner
+          version: '2.1.1'       # Pinned version of contextos-agents runner
           adapters: 'all'        # Adapters to verify (or specific: 'cursor', 'claude')
           working-directory: '.' # Project root directory
 ```

package/bin/commands/hook.js

@@ -17,7 +17,28 @@ const HOOK_MARKER_START = '# BEGIN CONTEXTOS HOOK';
 const HOOK_MARKER_END = '# END CONTEXTOS HOOK';
 
 const HOOK_PAYLOAD = `${HOOK_MARKER_START}
-npx contextos-agents scan --staged --enforce || exit 1
+CTX_SCOPE_ARG=""
+if [ -f ".agents/task-scope.json" ]; then
+  CTX_SCOPE_ARG="--scope .agents/task-scope.json"
+fi
+
+if [ -f "./node_modules/.bin/contextos" ]; then
+  ./node_modules/.bin/contextos scan --staged --enforce --placeholders $CTX_SCOPE_ARG
+  CTX_STATUS=$?
+elif [ -f "./node_modules/.bin/contextos-agents" ]; then
+  ./node_modules/.bin/contextos-agents scan --staged --enforce --placeholders $CTX_SCOPE_ARG
+  CTX_STATUS=$?
+elif [ -f "./bin/index.js" ] && [ -f "./package.json" ]; then
+  node ./bin/index.js scan --staged --enforce --placeholders $CTX_SCOPE_ARG
+  CTX_STATUS=$?
+else
+  echo "[ERROR] ContextOS local runner not found. Install locally (npm i -D contextos-agents) before committing." >&2
+  exit 2
+fi
+
+if [ $CTX_STATUS -ne 0 ]; then
+  exit $CTX_STATUS
+fi
 ${HOOK_MARKER_END}`;
 
 function installHook(cwd = process.cwd()) {
@@ -37,19 +58,36 @@ function installHook(cwd = process.cwd()) {
   if (fs.existsSync(hookFile)) {
     const existing = fs.readFileSync(hookFile, 'utf8');
 
-    if (existing.includes(HOOK_MARKER_START)) {
-      // Replace existing block cleanly
-      const regex = new RegExp(`${HOOK_MARKER_START}[\\s\\S]*?${HOOK_MARKER_END}`);
-      const updated = existing.replace(regex, HOOK_PAYLOAD);
-      fs.writeFileSync(hookFile, updated, 'utf8');
-      console.log(`✓ ContextOS pre-commit hook updated in ${hookFile}`);
+    // Validate shebang if present
+    const shebangMatch = existing.match(/^#!([^\r\n]+)/);
+    if (shebangMatch) {
+      const interpreter = shebangMatch[1].toLowerCase();
+      const isShell = /\b(sh|bash|zsh|dash)\b/.test(interpreter);
+      if (!isShell) {
+        console.error(`[ERROR] Pre-commit hook uses non-shell interpreter (${shebangMatch[0]}). ContextOS pre-commit hook requires POSIX shell.`);
+        process.exit(1);
+      }
+    }
+
+    // Strip any existing ContextOS block (e.g. legacy trailing block from v2.1.0)
+    const stripped = existing.includes(HOOK_MARKER_START)
+      ? existing.replace(new RegExp(`\\n?${HOOK_MARKER_START}[\\s\\S]*?${HOOK_MARKER_END}\\n?`, 'g'), '').trim()
+      : existing.trim();
+
+    // Place HOOK_PAYLOAD right after shebang so it runs first and cannot be bypassed by user 'exit 0'
+    let updated;
+    const strippedShebangMatch = stripped.match(/^#!.*(?:\r?\n|$)/);
+    if (strippedShebangMatch) {
+      const shebang = strippedShebangMatch[0];
+      const rest = stripped.slice(shebang.length).trim();
+      const sep = rest ? '\n\n' : '\n';
+      updated = `${shebang.trimEnd()}\n\n${HOOK_PAYLOAD}${sep}${rest}`;
     } else {
-      // Append while preserving user's existing hook script
-      const separator = existing.endsWith('\n') ? '\n' : '\n\n';
-      const updated = existing + separator + HOOK_PAYLOAD + '\n';
-      fs.writeFileSync(hookFile, updated, 'utf8');
-      console.log(`✓ ContextOS pre-commit hook appended to existing hook in ${hookFile}`);
+      updated = `#!/bin/sh\n\n${HOOK_PAYLOAD}${stripped ? `\n\n${stripped}` : ''}`;
     }
+
+    fs.writeFileSync(hookFile, updated.trimEnd() + '\n', 'utf8');
+    console.log(`✓ ContextOS pre-commit hook installed in ${hookFile}`);
   } else {
     // Fresh hook installation with shebang
     const fresh = `#!/bin/sh\n\n${HOOK_PAYLOAD}\n`;

package/bin/commands/scan.js

@@ -7,9 +7,10 @@
 
 'use strict';
 
+const path = require('path');
 const { runScan } = require('../lib/scan.js');
 
-function scanCommand(args, flags) {
+function scanCommand(args, flags = {}) {
   const isJson = flags.json || args.includes('--json');
   const enforce = flags.enforce || args.includes('--enforce');
   const checkPlaceholders = flags.placeholders || args.includes('--placeholders');
@@ -18,8 +19,13 @@ function scanCommand(args, flags) {
   const scopeIdx = args.indexOf('--scope');
   const scopeFile = scopeIdx !== -1 && args[scopeIdx + 1] ? args[scopeIdx + 1] : null;
 
+  const projectIdx = args.indexOf('--project');
+  const projectArg = projectIdx !== -1 && args[projectIdx + 1] ? args[projectIdx + 1] : null;
+  const targetProject = flags.project || projectArg;
+  const projectDir = targetProject ? path.resolve(targetProject) : process.cwd();
+
   const result = runScan({
-    cwd: process.cwd(),
+    cwd: projectDir,
     staged: true,
     secrets: checkSecrets,
     placeholders: checkPlaceholders,
@@ -43,6 +49,7 @@ function scanCommand(args, flags) {
 
   console.log(`  Staged Files Scanned : ${result.stats.stagedFilesCount}`);
   console.log(`  Enforcement Mode     : ${enforce ? 'STRICT (fails on findings)' : 'ADVISORY (warnings only)'}`);
+  console.log(`  Scope Containment    : ${result.scope.status.toUpperCase()}`);
   console.log(`  Violations Found     : ${result.stats.violationsCount}\n`);
 
   if (result.findings.length > 0) {
@@ -58,7 +65,7 @@ function scanCommand(args, flags) {
 
   console.log('──────────────────────────────────────────────────────');
   if (result.ok) {
-    console.log('  RESULT: PASSED (No blocking violations in staged index)');
+    console.log('  RESULT: PASSED (Verification completed cleanly, no blocking violations)');
   } else {
     console.log('  RESULT: FAILED (Commit blocked due to staged violations)');
   }

package/bin/index.js

@@ -270,7 +270,10 @@ if (mainCommand === 'recover') {
 // Gate command (deterministic quality gate verification)
 if (mainCommand === 'gate') {
   const { runGate, emitGitHubAnnotations, writeGitHubSummary } = require('./lib/gate.js');
-  const target = flags.target || (args[1] && !args[1].startsWith('-') ? args[1] : 'all');
+  let target = flags.target || (args[1] && !args[1].startsWith('-') ? args[1] : 'all');
+  if (typeof target === 'string' && target.includes(',')) {
+    target = target.split(',').map(s => s.trim()).filter(Boolean);
+  }
   const result = runGate(flags.project, {
     target,
     profile: flags.profile,
@@ -377,7 +380,7 @@ if (mainCommand === 'hook') {
 
 // Proxy commands to trusted package .agents/ctx.js targeting flags.project
 const PROXY_COMMANDS = [
-  'profile', 'export', 'validate', 'resolve', 'skill', 'index',
+  'profile', 'export', 'validate', 'audit', 'resolve', 'skill', 'index',
   'clean-worktrees', 'stats', 'watch', 'compile', 'explain',
   'thread'
 ];
@@ -545,6 +548,9 @@ if (mainCommand === 'install-skill') {
   console.error('             To use the MCP Bridge or execution runtime, install @contextos/mcp:');
   console.error('             npm install @contextos/mcp --save-dev');
   process.exit(1);
+} else if (mainCommand && mainCommand !== 'init') {
+  console.error(`[ERROR] Unknown command: '${mainCommand}'. Run 'contextos --help' for available commands.`);
+  process.exit(1);
 } else {
 
 // ── Paths ─────────────────────────────────────────────────────────────────────